From 6f2a6926d8815ba5a72e27d8cf88155df65ef857 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Mon, 2 Nov 2026 09:59:49 -0700 Subject: [PATCH 001/131] fix(pumas): consume the v0.8 additive typed HTTP contract Pumas v0.8 (feat/v080-consumer-api, 4c79cd8e) grows typed responses additively and makes error.outcome authoritative. Tuldok refused valid responses and misreported refusals. - Capabilities: validate only the fields, capabilities (chat, image generation, image-to-text) and option bounds Tuldok uses; ignore context_tokens, multimodal_embedding/decision, new formats, reasons, options and fields; select by name; drop list-length caps (1 MiB body bound instead). - Errors: classify by error.outcome, not HTTP status (404/409 are ordinary refusals); accept request_id null; keep unknown codes; show Pumas' bounded error.message in job/UI errors, capability refusals and pumas_error bodies on OpenAI-compatible routes (after redaction). - Results: ignore additive envelope/result fields. - Image-to-text: no fixed 2048 max_tokens cap; the live bound follows the served context. Image facts are checked only when advertised. - Model listing prefers GET /v1/served-models (profiles shown), falling back to /v1/models on 404. - Repin the six actual DTO schema exports, source-derived capability fixture and source.json to 4c79cd8e; update the consumer contract doc. The PR51 advertisement decoder stays closed because it is retained as evidence. Co-Authored-By: Claude Opus 5.5 --- ai_http.py | 42 ++- .../contracts/pumas-image-to-text-consumer.md | 103 ++++-- gateway_discovery.py | 10 +- image_generation.py | 8 +- pumas_operations.py | 324 +++++++++++++----- pumas_vision.py | 15 +- tests/fake_ai.py | 6 + tests/fake_images.py | 3 + tests/fake_pumas_typed.py | 14 +- tests/fake_pumas_vision.py | 19 +- .../controlled-capabilities.json | 126 +++++-- .../schemas/capabilities-response.schema.json | 54 ++- .../schemas/capability-descriptor.schema.json | 45 ++- .../schemas/error-response.schema.json | 7 +- .../schemas/modality-request.schema.json | 256 +++++++++++++- .../schemas/operation-request.schema.json | 167 ++++++++- .../schemas/operation-response.schema.json | 117 +++++++ .../pumas-image-to-text-v1/source.json | 57 +-- tests/test_ai.py | 7 + tests/test_image_generation.py | 17 + tests/test_pumas_typed.py | 49 ++- tests/test_pumas_vision.py | 125 +++++-- 22 files changed, 1315 insertions(+), 256 deletions(-) diff --git a/ai_http.py b/ai_http.py index c1ea21bf..d1ac25ac 100644 --- a/ai_http.py +++ b/ai_http.py @@ -88,6 +88,26 @@ def collect(value, depth=0): return 'Provider detail: ' + ' | '.join(messages)[:340] if messages else 'The provider returned no readable error message.' +def pumas_error_detail(data, payload=None, headers=None): + """Pumas' OpenAI-compatible errors carry its (redacted) reason in `error.message`. + + Returns '' for any body that is not a bounded `pumas_error`; that reason is + still passed through the same redaction as other provider diagnostics. + """ + if not data or len(data) > MAX_ERROR_BODY: + return '' + try: + value = json.loads(data) + except (ValueError, UnicodeError): + return '' + error = value.get('error') if isinstance(value, dict) else None + if (not isinstance(error, dict) or error.get('type') != 'pumas_error' + or not isinstance(error.get('message'), str) or not error['message'].strip()): + return '' + detail = provider_error_detail(json.dumps({'message': error['message']}).encode(), payload, headers) + return 'Pumas reported: ' + detail.removeprefix('Provider detail: ') if detail.startswith('Provider detail: ') else '' + + def request_error_hint(data): """Classify bounded provider errors without exposing arbitrary response text.""" try: @@ -184,18 +204,24 @@ def watch_cancel(): 403: 'Check account permissions and provider restrictions.', 429: 'Rate limit reached; wait before trying again.'}.get(response.status, 'Check the selected model and structured-output support.') - if response.status == 400 or response.status >= 500: - try: - transport.settimeout(max(.001, min(2, deadline - time.monotonic()))) - error_data = response.read(MAX_ERROR_BODY + 1) - specific = request_error_hint(error_data) if len(error_data) <= MAX_ERROR_BODY else '' + try: + transport.settimeout(max(.001, min(2, deadline - time.monotonic()))) + error_data = response.read(MAX_ERROR_BODY + 1) + except (OSError, http.client.HTTPException): + error_data = None + if label == 'OpenRouter' and (response.status == 400 or response.status >= 500): + hint = 'Could not read the provider error body within the diagnostic limit.' + if error_data is not None: + specific = request_error_hint(error_data) if len(error_data) <= MAX_ERROR_BODY else '' + pumas_detail = pumas_error_detail(error_data, payload, headers) + if pumas_detail: + # Pumas' own (redacted) reason is shown for every refusal status. + hint = (specific + ' ' if specific else '') + pumas_detail + elif response.status == 400 or response.status >= 500: if label == 'OpenRouter' or response.status >= 500: hint = provider_error_detail(error_data, payload, headers) elif specific: hint = specific - except (OSError, http.client.HTTPException): - if label == 'OpenRouter': - hint = 'Could not read the provider error body within the diagnostic limit.' raise CodexError(f'{label} returned HTTP {response.status}. {hint}', retryable=response.status in (502, 503, 504)) yield response, transport, deadline diff --git a/docs/contracts/pumas-image-to-text-consumer.md b/docs/contracts/pumas-image-to-text-consumer.md index a6fa3697..287693cf 100644 --- a/docs/contracts/pumas-image-to-text-consumer.md +++ b/docs/contracts/pumas-image-to-text-consumer.md @@ -1,22 +1,47 @@ # Pumas Image→Text consumer -This opt-in caption path consumes the contract at Pumas Library merged PR68, -source `36c2aab2c885b8416fd4e39cf8c37c510596d6e4`: -[Image→Text contract](https://github.com/MrScripty/Pumas-Library/blob/36c2aab2c885b8416fd4e39cf8c37c510596d6e4/docs/contracts/image-to-text-v0.8.md). -It is based on Tuldok main `d99e23d2b0d2783a7a9863232a7453cd9f2db7aa`. -The legacy compatible caption path and the previous typed text/image operations -remain available. Their existing producer receipt is not silently repinned. +This opt-in caption path, and the typed text and image operations that share +`pumas_operations`, consume the Pumas Library v0.8 typed HTTP contract on branch +`feat/v080-consumer-api`, source `4c79cd8e35db566b70caaa13d8d8f92265f5976e`: +[model operations, contract version 1](https://github.com/MrScripty/Pumas-Library/blob/4c79cd8e35db566b70caaa13d8d8f92265f5976e/docs/contracts/model-operations-v1.md). +It supersedes the merged PR68 pin `36c2aab2c885b8416fd4e39cf8c37c510596d6e4`, +which `source.json` keeps as `previous_producer`. The legacy compatible caption +path remains available. The PR54 typed text/image capture receipt in +`tests/fixtures/pumas-typed-v1` is historical and is not repinned. -`pumas_operations.validate_manifest` accepts all seven closed capability variants, -the three additional image input formats and image byte/pixel/count option names. -The existing unavailable reasons remain unchanged. Availability is a live -observation, not a model qualification receipt. Audio's existing -`max_output_tokens` descriptor option is accepted as declared in the inspected DTO. +### Additive compatibility + +Pumas responses grow additively within contract version 1. Tuldok validates +only what it uses and selects capabilities and option bounds by name, never by +position or count: + +- `GET /v1/capabilities` requires `supported_contract_versions` containing 1, + `model`, an exact `profile`, positive `max_request_bytes`/`max_response_bytes` + and a `capabilities` list. Other fields (`context_tokens`, + `max_stream_event_bytes`, future fields) are retained but not required. +- Only `chat_generation`, `image_generation` and `image_to_text` descriptors are + validated: fixed semantic task, string format lists, an availability `state` + with an optional string reason, and finite, ordered bounds for the options + Tuldok compares (`max_tokens`, `temperature`, `top_p`, `width`, `height`, + `seed`, `image_bytes`, `image_pixels`, `image_count`). A used capability or + option advertised twice is refused as ambiguous. +- Other capabilities (`multimodal_embedding`, `decision`, audio, future values), + formats (`content_batch`, `decision`, `decisions`, future values), option names, + availability states and reasons, and response or result fields are ignored. + Any availability other than `available` means unavailable, and its reason is + shown. +- The capability observation is bounded at 1 MiB. `GET /v1/served-models` is + preferred for listing serving aliases with their profiles; gateways without it + (HTTP 404) fall back to `/v1/models`, which lists each ID once with `profiles`. + +Availability is a live observation, not a model qualification receipt. Choose **Pumas typed v1** in the image caption form, select the serving alias and optional exact profile, and inspect capabilities. On each new attempt, the owner requires `pumas.model-operations.image-to-text:1` in the gateway build advertisement -and an available Image→Text descriptor for the exact resolved model/profile. +and an available Image→Text descriptor for the exact resolved model/profile. The +gateway advertisement keeps its own closed, versioned decoder: it is retained as +evidence, so unknown advertisement fields are refused rather than stored. The request uses the facade's `messages`, `semantic_task:"image_to_text"`, text-generation options and `stream:false`. The seed is omitted. Named image and `image_messages` inputs are also supported by the bounded consumer request builder. @@ -25,8 +50,10 @@ messages can contain images; audio, URLs, paths and data-URL envelopes are refus The consumer applies the producer's 32 MiB whole-request, 8 MiB per-image, 16 MiB aggregate, four-image, 4096-axis, 4,194,304-pixel, 128-message and 128-total-part -bounds. Tokens default to 512 and permit 1–2048; temperature/top-p must be finite -and within 0–2/0–1. The caption application's existing preparation is smaller: +bounds. Tokens default to 512. Pumas no longer caps Image→Text `max_tokens` at +2048; the live `max_tokens` bound follows the served context window and is +checked before admission. Temperature/top-p must be finite and within 0–2/0–1. +Advertised image byte, pixel, count and dimension bounds are checked when present. The caption application's existing preparation is smaller: one RGB JPEG, at most 2 MiB and 1600 pixels on its longest side. It decodes the captured, hash-verified canonical image and retains both canonical-source and prepared-input hashes. Preparation is explicit in request history. @@ -37,8 +64,8 @@ replace Pumas's production PNG/turbojpeg validation, allocation controls or admission authority, and does not claim equivalent JPEG warning detection. No local validation result is used as permission to bypass provider refusals. -The response is the closed `{contract_version, request_id, result}` envelope. -The request ID must match; `result.kind` must be text. There is no response-model +The response is the `{contract_version, request_id, result}` envelope; added +fields are ignored. The request ID must match; `result.kind` must be text. There is no response-model requirement and no private provider envelope projection. This application requires a complete `stop` finish reason and valid caption JSON within a 256 KiB response bound; partial or filtered output is not applied. Capability/build observations, @@ -47,8 +74,15 @@ on the exact job. List responses omit image-bearing canonical requests and raw bytes. Explicit application creates a draft target and records its evidence in revision history; human review remains separate. -HTTP 400/413/422/503 pre-admission refusals and 502 failures retain their typed -code, HTTP status and `outcome` in the asynchronous job. A disconnect, uncertain +Every typed error is `{contract_version, request_id, error:{code, outcome, message}}`. +`error.outcome` is authoritative: `not_admitted` records no provider effect and +anything else is `unknown`, whatever the HTTP status. 404 `model_not_found` and +409 `ambiguous_model`/`ambiguous_operation` are ordinary refusals. An error whose +`request_id` is `null` (Pumas could not read the body) is still a typed refusal. +Unknown error codes are kept verbatim. The job retains the code, HTTP status and +outcome, and its error text includes Pumas' `error.message`, bounded and on one +line. Capability refusals show the same message. On the OpenAI-compatible routes, +a `pumas_error` body's `error.message` is shown after the existing redaction. A disconnect, uncertain response or possibly dispatched interrupted attempt remains `unknown`. Repeating an existing exact application request ID returns the retained attempt; it never replays inference. A new attempt requires a new explicit request. Browser recovery @@ -65,27 +99,30 @@ and packaged application acceptance remain integration-lead/provider-owner gates `tests/fixtures/pumas-image-to-text-v1/source.json` labels the capability/wire fixture as **source-derived**, with inspected production-source hashes. It is not -a captured native DTO schema export or an actual model reply. The tests exercise -seven-capability parsing, named/facade PNG/JPEG inputs (including progressive +a captured native DTO schema export or an actual model reply. The fixture follows +the pinned descriptor construction for a llama.cpp vision serving with an +8192-token context, including the `multimodal_embedding` and `decision` +descriptors. The tests exercise additive capability parsing, named/facade PNG/JPEG inputs (including progressive JPEG), order, closed shapes, finite/resource bounds, typed application captions, draft/history, live selection refusal, cancellation/borrowed-owner survival, HTTP outcomes, restart and no replay. The existing typed browser suite additionally checks the actual caption form, capability inspection, application and disconnect. -The six actual production DTO schemas regenerated from the combined source -are retained in `tests/fixtures/pumas-image-to-text-v1/schemas/`, with SHA-256 -identities in `source.json`. The source-derived capability fixture and authored -named/facade image requests and typed responses validate against these exports. -The schemas describe wire shape; finite bounds and live readiness remain runtime -checks. Neither fixture output nor schema validity proves native inference. +The six actual production DTO schemas regenerated at the pinned source with the +`export-contract` feature are retained in +`tests/fixtures/pumas-image-to-text-v1/schemas/`, with SHA-256 identities in +`source.json`. All six changed from the PR68 export (new capabilities, formats, +`context_tokens`, decision and content-batch DTOs and the required error +`message`). The +source-derived capability fixture and authored named/facade image requests and +typed responses validate against these exports in the vision tests. The schemas +describe wire shape; finite bounds and live readiness remain runtime checks. +Neither fixture output nor schema validity proves native inference. -The reviewed producer retains identical DTO definitions and schema dependencies; -all six exported schema SHA-256 identities are unchanged. `source.json` records -the export commit and refreshed handler/controlled-test source hashes. The fixture -gateway advertisement reads the same versioned source pin as its consumer -acceptance evidence. -This pin is the immutable merged Pumas main commit. Its source tree is identical -to the reviewed producer that passed CI before the coordinated merge. +`source.json` records the branch, commit, tree, contract document hash and +handler/controlled-test source hashes. The pin is a branch commit, not a merged +Pumas main commit; repin when it merges. The fixture gateway advertisement reads +the same versioned source pin as its consumer acceptance evidence. The combined desktop contract and packaged application are provider integration gates. Real model/projector inference, semantic quality, managed native teardown and production audio qualification remain unclaimed. No models or runtimes are diff --git a/gateway_discovery.py b/gateway_discovery.py index 314023d3..db3afc8b 100644 --- a/gateway_discovery.py +++ b/gateway_discovery.py @@ -35,7 +35,10 @@ def listening_endpoints(): return sorted(endpoints, key=lambda endpoint: (endpoint[1], endpoint[0])) -def get_json(host, port, path, deadline, payload=None, max_response=MAX_RESPONSE, decode=json.loads, require_complete=False): +def get_json(host, port, path, deadline, payload=None, max_response=MAX_RESPONSE, decode=json.loads, require_complete=False, + error=None): + """GET/POST bounded JSON. With `error`, a non-200 body is read under the same bounds + and passed to `error(status, raw)`, which raises a readable refusal.""" timeout = min(1.5, deadline - time.monotonic()) if timeout <= 0: raise TimeoutError() @@ -64,7 +67,7 @@ def expire(): expiry.daemon = True expiry.start() with connection.getresponse() as response: - if response.status != 200: + if response.status != 200 and error is None: raise ValueError('Not a gateway response') if require_complete: declared = response.getheader('Content-Length') @@ -86,6 +89,9 @@ def expire(): raise ValueError('Pumas descriptor response ended before its declared length') if require_complete and time.monotonic() >= deadline: raise TimeoutError() + if response.status != 200: + error(response.status, bytes(data)) + raise ValueError('Not a gateway response') return decode(data) finally: if expiry is not None: diff --git a/image_generation.py b/image_generation.py index 76e37f2f..2ca126f5 100644 --- a/image_generation.py +++ b/image_generation.py @@ -258,7 +258,13 @@ def watch_cancel(): 499: 'Image generation cancelled.', 503: 'The image model is unavailable. Load it in Pumas and refresh models.', 507: 'Pumas reported insufficient GPU memory. Free memory before trying again.'} - raise ValueError(messages.get(response.status, 'Pumas image generation failed. Check its runtime status. The request was not retried.')) + message = messages.get(response.status, 'Pumas image generation failed. Check its runtime status. The request was not retried.') + try: + transport.settimeout(2) + detail = ai_http.pumas_error_detail(response.read(ai_http.MAX_ERROR_BODY + 1), payload) + except (OSError, http.client.HTTPException): + detail = '' + raise ValueError(message + (' ' + detail if detail else '')) data = bytearray() while not response.isclosed(): chunk = response.read1(65536) diff --git a/pumas_operations.py b/pumas_operations.py index 89d345bc..3878473a 100644 --- a/pumas_operations.py +++ b/pumas_operations.py @@ -1,4 +1,9 @@ -"""Finite PR54 selected-model operations. Discovery budgets never time generation.""" +"""Finite Pumas typed model operations (contract version 1, v0.8 additive rules). + +Discovery budgets never time generation. Responses grow additively: unknown +response fields, capabilities, formats, option names, availability reasons and +error codes are ignored; only what Tuldok uses is validated and selected by name. +""" import hashlib import http.client import json @@ -13,20 +18,20 @@ from workbench import WorkbenchError, encode PROTOCOL = 'pumas_typed_v1' -SOURCE_COMMIT = '40c5cbfed67a6f0e862a1197bb5105363d67bdb1' -MAX_CAPABILITIES = 65536 +SOURCE_COMMIT = '4c79cd8e35db566b70caaa13d8d8f92265f5976e' +MAX_CAPABILITIES = 1024 * 1024 +MAX_SERVED_MODELS = 8 * 1024 * 1024 MAX_TEXT_RESPONSE = 256 * 1024 MAX_IMAGE_JSON = 12 * 1024 * 1024 MAX_DIMENSION = 2048 MAX_PIXELS = 4194304 -CAPABILITIES = {'chat_generation': 'chat_generation', 'text_generation': 'text_generation', - 'text_embedding': 'text_embedding', 'image_generation': 'text_to_image', - 'image_to_text': 'image_to_text', - 'audio_transcription': 'speech_to_text', 'audio_classification': 'audio_classification'} -ERROR_CODES = {'invalid_request', 'unsupported_contract', 'model_not_found', 'ambiguous_model', - 'ambiguous_operation', 'unsupported_modality', - 'capability_unavailable', 'provider_failure', 'invalid_provider_result', - 'request_limit', 'response_limit', 'transport_lost'} +MAX_MESSAGE = 600 +# Capabilities Tuldok sends, with their fixed contract-version-1 semantic task. +USED_CAPABILITIES = {'chat_generation': 'chat_generation', 'image_generation': 'text_to_image', + 'image_to_text': 'image_to_text'} +# Option bounds Tuldok compares against. Other advertised options are ignored. +USED_OPTIONS = {'max_tokens', 'temperature', 'top_p', 'width', 'height', 'seed', + 'image_bytes', 'image_pixels', 'image_count'} class OperationError(WorkbenchError): @@ -56,10 +61,63 @@ def constant(_): def object_fields(value, required, optional=()): + """Closed shape for request-side DTOs that Tuldok itself builds.""" if type(value) is not dict or not set(required) <= value.keys() or value.keys() - set(required) - set(optional): raise ValueError('Unsupported typed Pumas fields.') +def response_fields(value, required): + """Open shape for Pumas responses: required fields present, additive fields ignored.""" + if type(value) is not dict or not set(required) <= value.keys(): + raise ValueError('Typed Pumas response is missing required fields.') + + +def _positive_int(value): + return type(value) is int and value > 0 + + +def message_text(value): + """Bounded single-line display of Pumas' human-readable reason (never parsed).""" + if not isinstance(value, str): + return '' + value = ' '.join(''.join(c if c.isprintable() else ' ' for c in value).split()) + return value[:MAX_MESSAGE] + ('…' if len(value) > MAX_MESSAGE else '') + + +def typed_error(value): + """Decode `{contract_version, request_id, error:{code, outcome, message}}` or return None. + + `outcome` is authoritative. Only `not_admitted` proves no provider effect; + any other value is treated as `unknown`. Unknown codes are kept verbatim. + """ + if type(value) is not dict or type(value.get('error')) is not dict: + return None + error = value['error'] + code = error.get('code') + if not isinstance(code, str) or not code or len(code) > 200: + return None + outcome = 'not_admitted' if error.get('outcome') == 'not_admitted' else 'unknown' + return {'code': code, 'outcome': outcome, 'message': message_text(error.get('message'))} + + +def error_message(error, prefix='Pumas'): + detail = (': ' + error['message']) if error['message'] else '.' + if error['outcome'] == 'not_admitted': + return f"{prefix} refused the request ({error['code']}; not admitted, no provider effect){detail}" + return f"{prefix} reported {error['code']}; provider outcome unknown, no automatic replay{detail}" + + +def http_error(status, raw): + """Raise a readable ValueError for a non-200 typed discovery response.""" + try: + error = typed_error(strict_json(raw)) + except ValueError: + error = None + if error is None: + raise ValueError(f'Pumas returned HTTP {status} without a typed error body.') + raise ValueError(error_message(error)) + + def alias(value): if (not isinstance(value, str) or not value or value != value.strip() or len(value.encode('utf-8')) > 256 or any(ord(c) < 32 or ord(c) == 127 for c in value)): @@ -89,50 +147,69 @@ def configuration(body, *, image=False): return {'protocol': PROTOCOL, 'profile': profile(body['profile'])} +def _bound_number(value): + return type(value) in (int, float) and -1e308 <= value <= 1e308 + + +def _descriptor(item): + """Validate one descriptor Tuldok uses. Extra fields and enum values are ignored.""" + response_fields(item, ('capability', 'semantic_task', 'input_formats', 'output_formats', 'availability', 'option_bounds')) + name = item['capability'] + if item['semantic_task'] != USED_CAPABILITIES[name]: + raise ValueError('Pumas reports a different semantic task for '+name+' within contract version 1.') + for field in ('input_formats', 'output_formats'): + if type(item[field]) is not list or any(type(value) is not str for value in item[field]): + raise ValueError('Invalid typed Pumas '+field.replace('_', ' ')+'.') + availability = item['availability'] + if (type(availability) is not dict or type(availability.get('state')) is not str + or availability.get('reason') is not None and type(availability['reason']) is not str): + raise ValueError('Invalid typed Pumas availability.') + bounds = item['option_bounds'] + if type(bounds) is not list: + raise ValueError('Invalid typed Pumas option bounds.') + seen = set() + for bound in bounds: + if type(bound) is not dict or type(bound.get('option')) is not str or bound['option'] not in USED_OPTIONS: + continue + response_fields(bound, ('option', 'minimum', 'maximum')) + if bound['option'] in seen: + raise ValueError('Pumas advertises the '+bound['option']+' bound more than once.') + seen.add(bound['option']) + if not _bound_number(bound['minimum']) or not _bound_number(bound['maximum']) or bound['minimum'] > bound['maximum']: + raise ValueError('Invalid typed Pumas option interval.') + + def validate_manifest(raw): + """Validate the fields Tuldok uses from `GET /v1/capabilities`. + + Additive fields (for example `context_tokens`), unused capabilities such as + `multimodal_embedding` or `decision`, and unknown formats, reasons and option + names are accepted and ignored. The raw observation is retained unchanged. + """ value = strict_json(raw) - object_fields(value, ('supported_contract_versions', 'model', 'profile', 'max_request_bytes', - 'max_response_bytes', 'max_stream_event_bytes', 'capabilities')) + response_fields(value, ('supported_contract_versions', 'model', 'profile', 'max_request_bytes', + 'max_response_bytes', 'capabilities')) versions = value['supported_contract_versions'] - if type(versions) is not list or not 1 <= len(versions) <= 16 or any(type(v) is not int for v in versions) or 1 not in versions: + if type(versions) is not list or not any(type(version) is int and version == 1 for version in versions): raise ValueError('Pumas typed contract version 1 is unavailable.') alias(value['model']) if profile(value['profile']) is None: raise ValueError('Pumas must resolve an exact profile.') - for key, maximum in [('max_request_bytes', 32*1024*1024), ('max_response_bytes', 32*1024*1024), ('max_stream_event_bytes', 256*1024)]: - if type(value[key]) is not int or not 0 < value[key] <= maximum: + for key in ('max_request_bytes', 'max_response_bytes'): + if not _positive_int(value[key]): raise ValueError('Unsupported typed Pumas byte bounds.') entries = value['capabilities'] - if type(entries) is not list or len(entries) > len(CAPABILITIES): + if type(entries) is not list: raise ValueError('Invalid typed Pumas capability list.') seen = set() for item in entries: - object_fields(item, ('capability', 'semantic_task', 'input_formats', 'output_formats', 'streaming', 'availability', 'option_bounds')) - name = item['capability'] - if type(name) is not str or name not in CAPABILITIES or name in seen or item['semantic_task'] != CAPABILITIES[name] or type(item['streaming']) is not bool: - raise ValueError('Unsupported typed Pumas semantic capability.') + name = item.get('capability') if type(item) is dict else None + if type(name) is not str or name not in USED_CAPABILITIES: + continue + if name in seen: + raise ValueError('Pumas advertises '+name+' more than once for one serving.') seen.add(name) - for field, allowed in [('input_formats', {'messages_text', 'text', 'text_batch', 'pcm_s16le', 'pcm_f32le', 'png_base64', 'jpeg_base64', 'messages_image'}), - ('output_formats', {'text', 'embeddings_float32', 'png_base64', 'labels'})]: - items = item[field] - if type(items) is not list or not 1 <= len(items) <= len(allowed) or any(type(v) is not str or v not in allowed for v in items) or len(set(items)) != len(items): - raise ValueError('Unsupported typed Pumas format.') - availability = item['availability'] - object_fields(availability, ('state',), ('reason',)) - if availability not in [{'state': 'available'}] and (availability.get('state') != 'unavailable' or - type(availability.get('reason')) is not str or availability.get('reason') not in {'unsupported_adapter', 'unqualified_audio_runtime', 'unknown_model_task', 'model_task_mismatch', 'runtime_unavailable'}): - raise ValueError('Invalid typed Pumas availability.') - bounds = item['option_bounds'] - if type(bounds) is not list or len(bounds) > 13: - raise ValueError('Invalid typed Pumas option bounds.') - options = set() - for bound in bounds: - object_fields(bound, ('option', 'minimum', 'maximum')) - if type(bound['option']) is not str or bound['option'] not in {'max_tokens', 'temperature', 'top_p', 'dimensions', 'input_count', 'input_characters', 'width', 'height', 'seed', 'max_output_tokens', 'image_bytes', 'image_pixels', 'image_count'} or bound['option'] in options: - raise ValueError('Unsupported typed Pumas option.') - options.add(bound['option']) - if any(type(bound[k]) not in (int, float) or not -1e308 <= bound[k] <= 1e308 for k in ('minimum', 'maximum')) or bound['minimum'] > bound['maximum']: - raise ValueError('Invalid typed Pumas option interval.') + _descriptor(item) return {'capabilities': value, 'observed_sha256': hashlib.sha256(raw).hexdigest()} @@ -144,7 +221,8 @@ def capabilities(base, model, exact_profile=None): query['profile'] = exact_profile try: observed = gateway_discovery.get_json(parts.hostname, parts.port, '/v1/capabilities?' + urlencode(query), - time.monotonic()+3, max_response=MAX_CAPABILITIES, decode=validate_manifest, require_complete=True) + time.monotonic()+3, max_response=MAX_CAPABILITIES, decode=validate_manifest, require_complete=True, + error=http_error) except (ValueError, OSError, http.client.HTTPException) as error: raise OperationError('Selected-model capabilities unavailable: '+str(error)) from None manifest = observed['capabilities'] @@ -153,37 +231,102 @@ def capabilities(base, model, exact_profile=None): return observed +class _RouteMissing(ValueError): + pass + + +def _listing(aliases): + rows = [] + for name, profiles in aliases.items(): + required = len(profiles) > 1 + label = name + (' (profiles: ' + ', '.join(profiles) + '; choose one)' if required else '') + rows.append({'id': name, 'name': label, 'profiles': profiles, 'profile_required': required}) + return rows + + +def _served_models(raw): + """`GET /v1/served-models`: one entry per served (model, profile) pair.""" + value = strict_json(raw) + response_fields(value, ('models',)) + if type(value['models']) is not list: + raise ValueError('Invalid Pumas served-model listing.') + aliases = {} + for item in value['models']: + response_fields(item, ('model', 'profile')) + selected = profile(item['profile']) + if selected is None: + raise ValueError('Pumas served-model entry has no exact profile.') + profiles = aliases.setdefault(alias(item['model']), []) + if selected not in profiles: + profiles.append(selected) + return {'models': _listing(aliases), 'source': '/v1/served-models', + 'qualification': 'Served (model, profile) pairs. Inspect the selected model capabilities before admission.'} + + +def _openai_models(raw): + value = strict_json(raw) + entries = value.get('data') if type(value) is dict else None + if type(entries) is not list: + raise ValueError('Invalid bounded Pumas served model listing.') + aliases = {} + for item in entries: + if type(item) is not dict: + raise ValueError('Invalid model listing entry.') + profiles = aliases.setdefault(alias(item.get('id')), []) + # v0.8 lists each ID once with `profiles`; earlier gateways omit it. + listed = item.get('profiles') + for selected in listed if type(listed) is list else (): + if isinstance(selected, str) and re.fullmatch(r'[A-Za-z0-9_.-]{1,128}', selected) and selected not in profiles: + profiles.append(selected) + return {'models': _listing(aliases), 'source': '/v1/models', + 'qualification': 'Serving aliases only. Inspect the selected model capabilities before admission.'} + + def models(base): + """Prefer the typed served-model listing; fall back to `/v1/models` on gateways without it.""" parts = urlsplit(endpoint(base)) - def decode(raw): - value = strict_json(raw) - entries = value.get('data') if type(value) is dict else None - if type(entries) is not list or len(entries) > 512: - raise ValueError('Invalid bounded Pumas served model listing.') - names = [] - for item in entries: - if type(item) is not dict: - raise ValueError('Invalid model listing entry.') - name = alias(item.get('id')) - # PR54 emits one catalog row per served profile and omits profile - # in these rows. Exact-profile capabilities remain admission authority. - if name not in names: - names.append(name) - return {'models': [{'id': name, 'name': name} for name in names], - 'qualification': 'Serving aliases only. Inspect the selected model capabilities before admission.'} + def missing(status, raw): + if status == 404: + raise _RouteMissing() + http_error(status, raw) + try: + return gateway_discovery.get_json(parts.hostname, parts.port, '/v1/served-models', time.monotonic()+3, + max_response=MAX_SERVED_MODELS, decode=_served_models, require_complete=True, error=missing) + except _RouteMissing: + pass return gateway_discovery.get_json(parts.hostname, parts.port, '/v1/models', time.monotonic()+3, - max_response=1024*1024, decode=decode, require_complete=True) - - -def require(observed, name, input_format, output_format, options): - item = next((row for row in observed['capabilities']['capabilities'] if row['capability'] == name), None) - if (item is None or item['availability']['state'] != 'available' or input_format not in item['input_formats'] - or output_format not in item['output_formats']): - raise OperationError('Selected model does not currently advertise the required '+name+' capability.') - bounds = {row['option']: row for row in item['option_bounds']} + max_response=1024*1024, decode=_openai_models, require_complete=True, error=http_error) + + +def descriptor(observed, name): + """Select a capability descriptor by name, never by position or count.""" + return next((row for row in observed['capabilities']['capabilities'] + if type(row) is dict and row.get('capability') == name), None) + + +def require(observed, name, input_format, output_format, options, advisory=()): + """Check live availability and bounds. `advisory` options are checked only when advertised.""" + item = descriptor(observed, name) + if item is None: + raise OperationError('Selected model does not advertise the '+name+' capability.') + availability = item['availability'] + if availability.get('state') != 'available': + reason = availability.get('reason') + raise OperationError('Selected model reports '+name+' unavailable' + + (' ('+message_text(reason)+')' if isinstance(reason, str) else '') + '.') + if input_format not in item['input_formats'] or output_format not in item['output_formats']: + raise OperationError('Selected model does not advertise '+input_format+' to '+output_format+' for '+name+'.') + bounds = {row['option']: row for row in item['option_bounds'] + if type(row) is dict and type(row.get('option')) is str and row['option'] in USED_OPTIONS} for key, value in options.items(): - if key not in bounds or not bounds[key]['minimum'] <= value <= bounds[key]['maximum']: - raise OperationError('Selected model does not advertise the requested '+key+' bound.') + bound = bounds.get(key) + if bound is None: + if key in advisory: + continue + raise OperationError('Selected model does not advertise a '+key+' bound for '+name+'.') + if not bound['minimum'] <= value <= bound['maximum']: + raise OperationError(f"Requested {key} {value} is outside the selected model's {name} bound " + f"{bound['minimum']:g}–{bound['maximum']:g}.") def chat_request(job, user_text, max_tokens): @@ -236,9 +379,8 @@ def watch(): try: value = result(raw, payload['request_id']) except OperationError as error: + # The typed error's `outcome` is authoritative; HTTP status is evidence only. error.provider_http_status = response.status - if error.provider_code and response.status not in (400, 413, 422, 502, 503): - error.outcome = 'unknown' raise if value['kind'] != {'text': 'text', 'png_base64': 'image'}.get(payload['output']): raise OperationError('Typed result has the wrong output kind; no replay.', 'unknown', raw=raw) @@ -259,35 +401,45 @@ def watch(): def result(raw, request_id): + """Decode a finite typed response. Unknown response fields are ignored.""" try: value = strict_json(raw) - object_fields(value, ('contract_version', 'request_id'), ('result', 'error')) - if type(value['contract_version']) is not int or value['contract_version'] != 1 or value['request_id'] != request_id or ('result' in value) == ('error' in value): - raise ValueError('Wrong typed operation correlation.') + if type(value) is not dict or type(value.get('contract_version')) is not int or value['contract_version'] != 1: + raise ValueError('Typed response is not contract version 1.') if 'error' in value: - error = value['error']; object_fields(error, ('code', 'outcome')) - if type(error['code']) is not str or error['code'] not in ERROR_CODES or error['outcome'] not in ('not_admitted', 'unknown'): - raise ValueError('Invalid typed operation error.') - raise OperationError('Pumas '+error['code']+'; outcome '+error['outcome']+'. No automatic replay.', error['outcome'], error['code'], raw) + error = typed_error(value) + if error is None: + detail = message_text(value['error'].get('message')) if type(value['error']) is dict else '' + raise ValueError('Invalid typed operation error' + (': ' + detail if detail else '.')) + # A null request_id means Pumas could not read the body; it is still a typed rejection. + if value.get('request_id') not in (request_id, None): + raise ValueError('Typed error belongs to another request.') + raise OperationError(error_message(error), error['outcome'], error['code'], raw) + response_fields(value, ('request_id', 'result')) + if value['request_id'] != request_id: + raise ValueError('Typed result belongs to another request.') projected = value['result'] if type(projected) is not dict: raise ValueError('Invalid typed result.') if projected.get('kind') == 'text': - object_fields(projected, ('kind', 'text', 'finish_reason')) - if not isinstance(projected['text'], str) or projected['finish_reason'] != 'stop': - raise ValueError('A complete stop-terminated text result is required.') + response_fields(projected, ('kind', 'text', 'finish_reason')) + if not isinstance(projected['text'], str): + raise ValueError('Invalid typed text result.') + if projected['finish_reason'] != 'stop': + raise ValueError('Text did not finish with stop; partial output is not applied.') projected['text'].encode('utf-8') elif projected.get('kind') == 'image': - object_fields(projected, ('kind', 'png_base64', 'seed')) + response_fields(projected, ('kind', 'png_base64', 'seed')) if not isinstance(projected['png_base64'], str) or type(projected['seed']) is not int or not 0 <= projected['seed'] <= 4294967295: raise ValueError('Invalid typed image result.') else: - raise ValueError('Unsupported typed result format.') + raise ValueError('Unsupported typed result kind.') return projected except OperationError: raise - except (ValueError, UnicodeError, TypeError): - raise OperationError('Malformed or incomplete typed result; provider outcome unknown, no replay.', 'unknown', raw=raw) from None + except (ValueError, UnicodeError, TypeError) as error: + raise OperationError('Malformed or incomplete typed result; provider outcome unknown, no replay. '+str(error), + 'unknown', raw=raw) from None def image_dimensions(width, height): diff --git a/pumas_vision.py b/pumas_vision.py index 65ba2f2f..59a677ab 100644 --- a/pumas_vision.py +++ b/pumas_vision.py @@ -1,4 +1,4 @@ -"""Finite Image→Text consumer pinned to combined Pumas PR68, never model qualification. +"""Finite Image→Text consumer of the Pumas v0.8 typed contract, never model qualification. The application sends its prepared image bytes, without URL/path authority. Pumas's production PNG/turbojpeg decoder remains the admission authority. @@ -17,7 +17,7 @@ import pumas_operations as pumas from workbench import encode -SOURCE_COMMIT = '36c2aab2c885b8416fd4e39cf8c37c510596d6e4' +SOURCE_COMMIT = pumas.SOURCE_COMMIT SCHEMA = 'pumas.model-operations.image-to-text' MAX_REQUEST = 32 * 1024 * 1024 MAX_IMAGE = 8 * 1024 * 1024 @@ -26,6 +26,9 @@ MAX_AXIS = 4096 MAX_PIXELS = 4194304 MAX_MESSAGES = MAX_PARTS = 128 +# Pumas has no fixed generation cap; the live max_tokens bound follows the served context. +MAX_TOKENS = 4294967295 +IMAGE_FACTS = ('image_count', 'image_bytes', 'image_pixels', 'width', 'height') def _container(data, encoding): @@ -142,7 +145,8 @@ def validate_input(value, *, facade=False): def request(job, input_value, *, facade=True, max_tokens=512, temperature=None, top_p=None): - if type(max_tokens) is not int or not 1 <= max_tokens <= 2048: raise ValueError('Tokens must be 1–2048.') + if type(max_tokens) is not int or not 1 <= max_tokens <= MAX_TOKENS: + raise ValueError('Tokens must be a positive integer; the selected model bounds the maximum.') options = {'kind': 'text_generation', 'max_tokens': max_tokens} for key, value, maximum in [('temperature', temperature, 2), ('top_p', top_p, 1)]: if value is not None: @@ -171,7 +175,8 @@ def prepare(job, payload, stop): payload['profile'] = observed['capabilities']['profile'] input_format, images = validate_input(payload['input'], facade='semantic_task' in payload) options = {key: value for key, value in payload['options'].items() if key != 'kind'} - pumas.require(observed, 'image_to_text', input_format, 'text', dict(options, image_count=len(images))) - for image in images: pumas.require(observed, 'image_to_text', input_format, 'text', image) + # Image facts are checked against advertised bounds; local preflight already bounds them. + pumas.require(observed, 'image_to_text', input_format, 'text', dict(options, image_count=len(images)), advisory=IMAGE_FACTS) + for image in images: pumas.require(observed, 'image_to_text', input_format, 'text', image, advisory=IMAGE_FACTS) job.update(capability_observation=observed, build_observation=build, producer_contract_source=SOURCE_COMMIT) pumas.request_evidence(job, payload) diff --git a/tests/fake_ai.py b/tests/fake_ai.py index 75e4fb2d..d74e7f34 100644 --- a/tests/fake_ai.py +++ b/tests/fake_ai.py @@ -26,6 +26,12 @@ def do_POST(self): self.send_response(404);self.send_header('Content-Length','0');self.end_headers();return body=json.loads(self.rfile.read(int(self.headers['Content-Length']))) requests.append((self.path,body,dict(self.headers))) + if body['model']=='pumas-conflict': + encoded=json.dumps({'error':{'message':'model corners-test is served by profiles a, b; select one','type':'pumas_error','code':'ambiguous_model'}}).encode() + self.send_response(409);self.send_header('Content-Length',str(len(encoded)));self.end_headers();self.wfile.write(encoded);return + if body['model']=='plain-conflict': + encoded=json.dumps({'error':{'message':'private upstream wording'}}).encode() + self.send_response(409);self.send_header('Content-Length',str(len(encoded)));self.end_headers();self.wfile.write(encoded);return if body['model']=='missing-projector': encoded=json.dumps({'error':{'message':'image input is not supported - provide the mmproj'}}).encode() self.send_response(500);self.send_header('Content-Length',str(len(encoded)));self.end_headers();self.wfile.write(encoded);return diff --git a/tests/fake_images.py b/tests/fake_images.py index 885af67c..f7103fab 100644 --- a/tests/fake_images.py +++ b/tests/fake_images.py @@ -50,6 +50,9 @@ def do_POST(self): return if body['prompt'] == 'busy': return self.reply({'error': {'code': 'runtime_busy'}}, 409) + if body['prompt'] == 'pumas-refusal': + return self.reply({'error': {'message': 'width 33 is not a multiple of 8 for this model; token=sk-abcdefghijkl', + 'type': 'pumas_error', 'code': 'invalid_request'}}, 400) if body['prompt'] == 'unprocessable': return self.reply({'detail': 'fixture contract mismatch'}, 422) raw = b'invalid PNG' if body['prompt'] == 'invalid' else png((body['width'], body['height']), '#467e9a' if body.get('seed', 7) == 7 else '#%06x' % (body['seed'] % 16777216)) diff --git a/tests/fake_pumas_typed.py b/tests/fake_pumas_typed.py index b402ba68..e28f311e 100644 --- a/tests/fake_pumas_typed.py +++ b/tests/fake_pumas_typed.py @@ -24,6 +24,8 @@ def reply(self, value, status=200): try: self.wfile.write(raw) except OSError: pass def do_GET(self): + if self.path == '/v1/served-models' and state.get('served_models') is not None: + return self.reply(state['served_models']) if self.path == '/v1/models': rows = [{'id': 'controlled-text'}, {'id': 'controlled-image'}] if state.get('duplicate_alias'): rows.append({'id': 'controlled-text'}) @@ -31,7 +33,13 @@ def do_GET(self): query = parse_qs(urlsplit(self.path).query) model = query.get('model', [''])[0] if model not in ('controlled-text', 'controlled-image'): + if urlsplit(self.path).path == '/v1/capabilities': + return self.reply({'contract_version': 1, 'request_id': None, 'error': {'code': 'model_not_found', + 'outcome': 'not_admitted', 'message': 'no served model is named ' + repr(model)}}, 404) return self.reply({'error': 'unknown model'}, 404) + if state.get('ambiguous'): + return self.reply({'contract_version': 1, 'request_id': None, 'error': {'code': 'ambiguous_model', + 'outcome': 'not_admitted', 'message': 'alias is served by profiles a, b; send profile'}}, 409) manifest = json.loads((FIXTURES / (model+'-capabilities.json')).read_bytes()) if state['mode'] == 'wrong_profile': manifest['profile'] = 'foreign' if state['mode'] == 'unavailable': @@ -47,7 +55,11 @@ def do_POST(self): if mode == 'loss': self.close_connection = True; return if mode in ('not_admitted', 'unknown'): return self.reply({'contract_version': 1, 'request_id': body['request_id'], - 'error': {'code': 'capability_unavailable' if mode == 'not_admitted' else 'provider_failure', 'outcome': mode}}, 503) + 'error': {'code': 'capability_unavailable' if mode == 'not_admitted' else 'provider_failure', 'outcome': mode, + 'message': state.get('error_message', 'fixture provider reason')}}, state.get('error_status', 503)) + if mode == 'unreadable': + return self.reply({'contract_version': 1, 'request_id': None, 'error': {'code': 'invalid_request', + 'outcome': 'not_admitted', 'message': 'request body is not valid JSON'}}, 400) result = {'kind': 'text', 'text': state['content'], 'finish_reason': 'stop'} if body['capability'] == 'image_generation': import io diff --git a/tests/fake_pumas_vision.py b/tests/fake_pumas_vision.py index 2da5684c..a1eda85e 100644 --- a/tests/fake_pumas_vision.py +++ b/tests/fake_pumas_vision.py @@ -35,7 +35,16 @@ def do_GET(self): value = json.loads((FIXTURES / 'controlled-capabilities.json').read_bytes()) query = parse_qs(urlsplit(self.path).query) if query.get('profile', ['vision-cpu'])[0] != 'vision-cpu': return self.reply({},404) - if state['mode'] == 'unavailable': value['capabilities'][-1]['availability'] = {'state':'unavailable','reason':'runtime_unavailable'} + vision = next(row for row in value['capabilities'] if row['capability'] == 'image_to_text') + if state['mode'] == 'unavailable': vision['availability'] = {'state':'unavailable','reason':'runtime_unavailable'} + if state['mode'] == 'additive': + # v0.8 additive growth: new fields, capabilities, formats, options and reasons. + value['future_field'] = {'nested': True} + value['capabilities'].insert(0, {'capability':'future_capability','semantic_task':'future_task','input_formats':['future'], + 'output_formats':['future'],'streaming':False,'availability':{'state':'deferred'},'option_bounds':[],'extra':1}) + vision['input_formats'].append('future_format'); vision['future'] = 'ignored' + vision['option_bounds'].insert(0, {'option':'future_option','minimum':0.0,'maximum':1.0,'step':1}) + value['capabilities'][-1]['availability'] = {'state':'unavailable','reason':'future_reason'} if state['mode'] == 'wrong_profile': value['profile'] = 'foreign' if state['mode'] == 'wrong_model': value['model'] = 'foreign' return self.reply(value) @@ -47,11 +56,15 @@ def do_POST(self): if mode == 'loss': self.close_connection = True; return if mode in ('not_admitted','unknown'): return self.reply({'contract_version':1,'request_id':body['request_id'], - 'error':{'code':'unsupported_modality' if mode=='not_admitted' else 'invalid_provider_result','outcome':mode}},state['refusal_status']) + 'error':{'code':state.get('error_code') or ('unsupported_modality' if mode=='not_admitted' else 'invalid_provider_result'), + 'outcome':mode,'message':state.get('error_message','fixture reason')}},state['refusal_status']) + if mode == 'unreadable': + return self.reply({'contract_version':1,'request_id':None, + 'error':{'code':'invalid_request','outcome':'not_admitted','message':'request body is not valid JSON'}},400) value = {'contract_version':1,'request_id':body['request_id'], 'result':{'kind':'text','text':state['content'],'finish_reason':'stop'}} if mode == 'wrong_id': value['request_id'] = 'foreign' - if mode == 'private': value['model'] = 'provider/private' + if mode == 'additive': value['future'] = {'x': 1}; value['result']['future'] = 'ignored' if mode == 'length': value['result']['finish_reason'] = 'length' if mode == 'nonfinite': value['extra'] = float('nan') if mode == 'oversized': value['result']['text'] = 'x'*300000 diff --git a/tests/fixtures/pumas-image-to-text-v1/controlled-capabilities.json b/tests/fixtures/pumas-image-to-text-v1/controlled-capabilities.json index 27a4122a..262544db 100644 --- a/tests/fixtures/pumas-image-to-text-v1/controlled-capabilities.json +++ b/tests/fixtures/pumas-image-to-text-v1/controlled-capabilities.json @@ -7,6 +7,7 @@ "max_request_bytes": 33554432, "max_response_bytes": 33554432, "max_stream_event_bytes": 262144, + "context_tokens": 8192, "capabilities": [ { "capability": "chat_generation", @@ -25,7 +26,7 @@ { "option": "max_tokens", "minimum": 1.0, - "maximum": 4294967295.0 + "maximum": 8192.0 }, { "option": "temperature", @@ -56,7 +57,7 @@ { "option": "max_tokens", "minimum": 1.0, - "maximum": 4294967295.0 + "maximum": 8192.0 }, { "option": "temperature", @@ -89,17 +90,7 @@ { "option": "dimensions", "minimum": 1.0, - "maximum": 8192.0 - }, - { - "option": "input_count", - "minimum": 1.0, - "maximum": 128.0 - }, - { - "option": "input_characters", - "minimum": 0.0, - "maximum": 65536.0 + "maximum": 4294967295.0 } ] }, @@ -158,8 +149,8 @@ "option_bounds": [ { "option": "max_output_tokens", - "minimum": 512, - "maximum": 512 + "minimum": 512.0, + "maximum": 512.0 } ] }, @@ -176,7 +167,7 @@ "streaming": false, "availability": { "state": "unavailable", - "reason": "unqualified_audio_runtime" + "reason": "unsupported_adapter" }, "option_bounds": [] }, @@ -198,43 +189,114 @@ "option_bounds": [ { "option": "max_tokens", - "minimum": 1, - "maximum": 2048 + "minimum": 1.0, + "maximum": 8192.0 }, { "option": "temperature", - "minimum": 0, - "maximum": 2 + "minimum": 0.0, + "maximum": 2.0 }, { "option": "top_p", - "minimum": 0, - "maximum": 1 + "minimum": 0.0, + "maximum": 1.0 }, { "option": "image_bytes", - "minimum": 1, - "maximum": 8388608 + "minimum": 1.0, + "maximum": 8388608.0 }, { "option": "image_pixels", - "minimum": 1, - "maximum": 4194304 + "minimum": 1.0, + "maximum": 4194304.0 }, { "option": "image_count", - "minimum": 1, - "maximum": 4 + "minimum": 1.0, + "maximum": 4.0 }, { "option": "width", - "minimum": 1, - "maximum": 4096 + "minimum": 1.0, + "maximum": 4096.0 }, { "option": "height", - "minimum": 1, - "maximum": 4096 + "minimum": 1.0, + "maximum": 4096.0 + } + ] + }, + { + "capability": "multimodal_embedding", + "semantic_task": "multimodal_embedding", + "input_formats": [ + "png_base64", + "jpeg_base64", + "content_batch" + ], + "output_formats": [ + "embeddings_float32" + ], + "streaming": false, + "availability": { + "state": "unavailable", + "reason": "model_task_mismatch" + }, + "option_bounds": [ + { + "option": "dimensions", + "minimum": 1.0, + "maximum": 4294967295.0 + }, + { + "option": "image_bytes", + "minimum": 1.0, + "maximum": 8388608.0 + }, + { + "option": "image_pixels", + "minimum": 1.0, + "maximum": 4194304.0 + }, + { + "option": "image_count", + "minimum": 1.0, + "maximum": 4.0 + } + ] + }, + { + "capability": "decision", + "semantic_task": "decision", + "input_formats": [ + "decision" + ], + "output_formats": [ + "decisions" + ], + "streaming": false, + "availability": { + "state": "unavailable", + "reason": "model_task_mismatch" + }, + "option_bounds": [ + { + "option": "image_bytes", + "minimum": 1.0, + "maximum": 8388608.0 + }, + { + "option": "image_pixels", + "minimum": 1.0, + "maximum": 4194304.0 + }, + { + "option": "image_count", + "minimum": 0.0, + "maximum": 4.0 } ] } diff --git a/tests/fixtures/pumas-image-to-text-v1/schemas/capabilities-response.schema.json b/tests/fixtures/pumas-image-to-text-v1/schemas/capabilities-response.schema.json index d9534ecd..c455d4f7 100644 --- a/tests/fixtures/pumas-image-to-text-v1/schemas/capabilities-response.schema.json +++ b/tests/fixtures/pumas-image-to-text-v1/schemas/capabilities-response.schema.json @@ -43,16 +43,30 @@ "type": "string" }, "Capability": { - "enum": [ - "chat_generation", - "text_generation", - "text_embedding", - "image_generation", - "image_to_text", - "audio_transcription", - "audio_classification" - ], - "type": "string" + "oneOf": [ + { + "enum": [ + "chat_generation", + "text_generation", + "text_embedding", + "image_generation", + "image_to_text", + "audio_transcription", + "audio_classification" + ], + "type": "string" + }, + { + "const": "multimodal_embedding", + "description": "One embedding per image or per mixed text/image item, in the same\nvector space as the model's text embeddings.", + "type": "string" + }, + { + "const": "decision", + "description": "Typed questions about a state answered with probabilities by a native\ndecision model (llama.cpp `/v1/systemone`, e.g. Kev, OpenJev).", + "type": "string" + } + ] }, "CapabilityDescriptor": { "properties": { @@ -107,7 +121,9 @@ "text", "text_batch", "pcm_s16le", - "pcm_f32le" + "pcm_f32le", + "content_batch", + "decision" ], "type": "string" }, @@ -155,7 +171,8 @@ "text", "embeddings_float32", "png_base64", - "labels" + "labels", + "decisions" ], "type": "string" }, @@ -167,7 +184,9 @@ "text_to_image", "speech_to_text", "audio_classification", - "image_to_text" + "image_to_text", + "multimodal_embedding", + "decision" ], "type": "string" } @@ -180,6 +199,15 @@ }, "type": "array" }, + "context_tokens": { + "description": "Context window configured for this serving, when the runtime reports it.", + "format": "uint32", + "minimum": 0, + "type": [ + "integer", + "null" + ] + }, "max_request_bytes": { "format": "uint", "minimum": 0, diff --git a/tests/fixtures/pumas-image-to-text-v1/schemas/capability-descriptor.schema.json b/tests/fixtures/pumas-image-to-text-v1/schemas/capability-descriptor.schema.json index 0377d31b..9dc9d126 100644 --- a/tests/fixtures/pumas-image-to-text-v1/schemas/capability-descriptor.schema.json +++ b/tests/fixtures/pumas-image-to-text-v1/schemas/capability-descriptor.schema.json @@ -43,16 +43,30 @@ "type": "string" }, "Capability": { - "enum": [ - "chat_generation", - "text_generation", - "text_embedding", - "image_generation", - "image_to_text", - "audio_transcription", - "audio_classification" - ], - "type": "string" + "oneOf": [ + { + "enum": [ + "chat_generation", + "text_generation", + "text_embedding", + "image_generation", + "image_to_text", + "audio_transcription", + "audio_classification" + ], + "type": "string" + }, + { + "const": "multimodal_embedding", + "description": "One embedding per image or per mixed text/image item, in the same\nvector space as the model's text embeddings.", + "type": "string" + }, + { + "const": "decision", + "description": "Typed questions about a state answered with probabilities by a native\ndecision model (llama.cpp `/v1/systemone`, e.g. Kev, OpenJev).", + "type": "string" + } + ] }, "InputFormat": { "enum": [ @@ -63,7 +77,9 @@ "text", "text_batch", "pcm_s16le", - "pcm_f32le" + "pcm_f32le", + "content_batch", + "decision" ], "type": "string" }, @@ -111,7 +127,8 @@ "text", "embeddings_float32", "png_base64", - "labels" + "labels", + "decisions" ], "type": "string" }, @@ -123,7 +140,9 @@ "text_to_image", "speech_to_text", "audio_classification", - "image_to_text" + "image_to_text", + "multimodal_embedding", + "decision" ], "type": "string" } diff --git a/tests/fixtures/pumas-image-to-text-v1/schemas/error-response.schema.json b/tests/fixtures/pumas-image-to-text-v1/schemas/error-response.schema.json index 89f00acb..a7694c93 100644 --- a/tests/fixtures/pumas-image-to-text-v1/schemas/error-response.schema.json +++ b/tests/fixtures/pumas-image-to-text-v1/schemas/error-response.schema.json @@ -22,13 +22,18 @@ "code": { "$ref": "#/$defs/ErrorCode" }, + "message": { + "description": "Human-readable reason. Consumers display or log it; they branch on `code`.", + "type": "string" + }, "outcome": { "$ref": "#/$defs/Outcome" } }, "required": [ "code", - "outcome" + "outcome", + "message" ], "type": "object" }, diff --git a/tests/fixtures/pumas-image-to-text-v1/schemas/modality-request.schema.json b/tests/fixtures/pumas-image-to-text-v1/schemas/modality-request.schema.json index dc979861..0f014046 100644 --- a/tests/fixtures/pumas-image-to-text-v1/schemas/modality-request.schema.json +++ b/tests/fixtures/pumas-image-to-text-v1/schemas/modality-request.schema.json @@ -27,6 +27,32 @@ ], "type": "string" }, + "Capability": { + "oneOf": [ + { + "enum": [ + "chat_generation", + "text_generation", + "text_embedding", + "image_generation", + "image_to_text", + "audio_transcription", + "audio_classification" + ], + "type": "string" + }, + { + "const": "multimodal_embedding", + "description": "One embedding per image or per mixed text/image item, in the same\nvector space as the model's text embeddings.", + "type": "string" + }, + { + "const": "decision", + "description": "Typed questions about a state answered with probabilities by a native\ndecision model (llama.cpp `/v1/systemone`, e.g. Kev, OpenJev).", + "type": "string" + } + ] + }, "Content": { "anyOf": [ { @@ -40,6 +66,71 @@ } ] }, + "ContentItem": { + "additionalProperties": false, + "properties": { + "parts": { + "items": { + "$ref": "#/$defs/ImagePart" + }, + "type": "array" + } + }, + "required": [ + "parts" + ], + "type": "object" + }, + "DecisionImage": { + "additionalProperties": false, + "properties": { + "data_base64": { + "type": "string" + }, + "encoding": { + "$ref": "#/$defs/ImageEncoding" + } + }, + "required": [ + "encoding", + "data_base64" + ], + "type": "object" + }, + "DecisionQuestion": { + "additionalProperties": false, + "properties": { + "criteria": true, + "instructions": true, + "type": { + "$ref": "#/$defs/DecisionType" + } + }, + "required": [ + "type", + "instructions" + ], + "type": "object" + }, + "DecisionType": { + "oneOf": [ + { + "const": "choice", + "description": "Pick one option; `criteria` maps option to description (or null).", + "type": "string" + }, + { + "const": "score", + "description": "Rate on a scale; `criteria` lists level descriptions, lowest first.", + "type": "string" + }, + { + "const": "noul", + "description": "Probability that the answer is true; optional `criteria` describes\n`true` and `false`.", + "type": "string" + } + ] + }, "ImageEncoding": { "enum": [ "png", @@ -47,6 +138,67 @@ ], "type": "string" }, + "ImageMessage": { + "additionalProperties": false, + "properties": { + "content": { + "items": { + "$ref": "#/$defs/ImagePart" + }, + "type": "array" + }, + "role": { + "$ref": "#/$defs/Role" + } + }, + "required": [ + "role", + "content" + ], + "type": "object" + }, + "ImagePart": { + "oneOf": [ + { + "additionalProperties": false, + "properties": { + "kind": { + "const": "text", + "type": "string" + }, + "text": { + "type": "string" + } + }, + "required": [ + "kind", + "text" + ], + "type": "object" + }, + { + "additionalProperties": false, + "properties": { + "data_base64": { + "type": "string" + }, + "encoding": { + "$ref": "#/$defs/ImageEncoding" + }, + "kind": { + "const": "image", + "type": "string" + } + }, + "required": [ + "kind", + "encoding", + "data_base64" + ], + "type": "object" + } + ] + }, "Input": { "oneOf": [ { @@ -106,6 +258,27 @@ ], "type": "object" }, + { + "additionalProperties": false, + "description": "Messages whose content is a list of text and image parts.", + "properties": { + "kind": { + "const": "image_messages", + "type": "string" + }, + "messages": { + "items": { + "$ref": "#/$defs/ImageMessage" + }, + "type": "array" + } + }, + "required": [ + "kind", + "messages" + ], + "type": "object" + }, { "additionalProperties": false, "properties": { @@ -166,6 +339,57 @@ "data_base64" ], "type": "object" + }, + { + "additionalProperties": false, + "description": "Items to embed together; each item produces one vector.", + "properties": { + "items": { + "items": { + "$ref": "#/$defs/ContentItem" + }, + "type": "array" + }, + "kind": { + "const": "content_batch", + "type": "string" + } + }, + "required": [ + "kind", + "items" + ], + "type": "object" + }, + { + "additionalProperties": false, + "description": "A state and typed questions for a native decision model.", + "properties": { + "images": { + "default": [], + "items": { + "$ref": "#/$defs/DecisionImage" + }, + "type": "array" + }, + "kind": { + "const": "decision", + "type": "string" + }, + "questions": { + "additionalProperties": { + "$ref": "#/$defs/DecisionQuestion" + }, + "type": "object" + }, + "state": true + }, + "required": [ + "kind", + "state", + "questions" + ], + "type": "object" } ] }, @@ -313,6 +537,19 @@ "kind" ], "type": "object" + }, + { + "additionalProperties": false, + "properties": { + "kind": { + "const": "decision", + "type": "string" + } + }, + "required": [ + "kind" + ], + "type": "object" } ] }, @@ -323,7 +560,8 @@ "png_base64", "labels", "pcm_s16le", - "pcm_f32le" + "pcm_f32le", + "decisions" ], "type": "string" }, @@ -425,7 +663,9 @@ "text_to_image", "speech_to_text", "audio_classification", - "image_to_text" + "image_to_text", + "multimodal_embedding", + "decision" ], "type": "string" } @@ -433,6 +673,18 @@ "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, "properties": { + "capability": { + "anyOf": [ + { + "$ref": "#/$defs/Capability" + }, + { + "type": "null" + } + ], + "default": null, + "description": "Optional explicit capability. When present, resolution only considers it." + }, "contract_version": { "format": "uint32", "minimum": 0, diff --git a/tests/fixtures/pumas-image-to-text-v1/schemas/operation-request.schema.json b/tests/fixtures/pumas-image-to-text-v1/schemas/operation-request.schema.json index ee426cd0..84219b50 100644 --- a/tests/fixtures/pumas-image-to-text-v1/schemas/operation-request.schema.json +++ b/tests/fixtures/pumas-image-to-text-v1/schemas/operation-request.schema.json @@ -28,16 +28,95 @@ "type": "string" }, "Capability": { - "enum": [ - "chat_generation", - "text_generation", - "text_embedding", - "image_generation", - "image_to_text", - "audio_transcription", - "audio_classification" + "oneOf": [ + { + "enum": [ + "chat_generation", + "text_generation", + "text_embedding", + "image_generation", + "image_to_text", + "audio_transcription", + "audio_classification" + ], + "type": "string" + }, + { + "const": "multimodal_embedding", + "description": "One embedding per image or per mixed text/image item, in the same\nvector space as the model's text embeddings.", + "type": "string" + }, + { + "const": "decision", + "description": "Typed questions about a state answered with probabilities by a native\ndecision model (llama.cpp `/v1/systemone`, e.g. Kev, OpenJev).", + "type": "string" + } + ] + }, + "ContentItem": { + "additionalProperties": false, + "properties": { + "parts": { + "items": { + "$ref": "#/$defs/ImagePart" + }, + "type": "array" + } + }, + "required": [ + "parts" ], - "type": "string" + "type": "object" + }, + "DecisionImage": { + "additionalProperties": false, + "properties": { + "data_base64": { + "type": "string" + }, + "encoding": { + "$ref": "#/$defs/ImageEncoding" + } + }, + "required": [ + "encoding", + "data_base64" + ], + "type": "object" + }, + "DecisionQuestion": { + "additionalProperties": false, + "properties": { + "criteria": true, + "instructions": true, + "type": { + "$ref": "#/$defs/DecisionType" + } + }, + "required": [ + "type", + "instructions" + ], + "type": "object" + }, + "DecisionType": { + "oneOf": [ + { + "const": "choice", + "description": "Pick one option; `criteria` maps option to description (or null).", + "type": "string" + }, + { + "const": "score", + "description": "Rate on a scale; `criteria` lists level descriptions, lowest first.", + "type": "string" + }, + { + "const": "noul", + "description": "Probability that the answer is true; optional `criteria` describes\n`true` and `false`.", + "type": "string" + } + ] }, "ImageEncoding": { "enum": [ @@ -262,6 +341,60 @@ "data_base64" ], "type": "object" + }, + { + "additionalProperties": false, + "description": "Items to embed; each item's text and image parts produce one vector.", + "properties": { + "items": { + "items": { + "$ref": "#/$defs/ContentItem" + }, + "type": "array" + }, + "kind": { + "const": "content_batch", + "type": "string" + } + }, + "required": [ + "kind", + "items" + ], + "type": "object" + }, + { + "additionalProperties": false, + "description": "A state and typed questions for a decision model.", + "properties": { + "images": { + "description": "Optional images, for decision models with a loaded projector.", + "items": { + "$ref": "#/$defs/DecisionImage" + }, + "type": "array" + }, + "kind": { + "const": "decision", + "type": "string" + }, + "questions": { + "additionalProperties": { + "$ref": "#/$defs/DecisionQuestion" + }, + "description": "Question id to question. Each question is answered independently.", + "type": "object" + }, + "state": { + "description": "Content to evaluate: a string, or JSON given to the model as text." + } + }, + "required": [ + "kind", + "state", + "questions" + ], + "type": "object" } ] }, @@ -393,6 +526,19 @@ "kind" ], "type": "object" + }, + { + "additionalProperties": false, + "properties": { + "kind": { + "const": "decision", + "type": "string" + } + }, + "required": [ + "kind" + ], + "type": "object" } ] }, @@ -401,7 +547,8 @@ "text", "embeddings_float32", "png_base64", - "labels" + "labels", + "decisions" ], "type": "string" }, diff --git a/tests/fixtures/pumas-image-to-text-v1/schemas/operation-response.schema.json b/tests/fixtures/pumas-image-to-text-v1/schemas/operation-response.schema.json index 82857c00..277d7a17 100644 --- a/tests/fixtures/pumas-image-to-text-v1/schemas/operation-response.schema.json +++ b/tests/fixtures/pumas-image-to-text-v1/schemas/operation-response.schema.json @@ -1,5 +1,94 @@ { "$defs": { + "DecisionAnswer": { + "oneOf": [ + { + "properties": { + "choice": { + "type": "string" + }, + "confidence": { + "format": "double", + "type": "number" + }, + "probabilities": { + "additionalProperties": { + "format": "double", + "type": "number" + }, + "type": "object" + }, + "type": { + "const": "choice", + "type": "string" + } + }, + "required": [ + "type", + "choice", + "probabilities", + "confidence" + ], + "type": "object" + }, + { + "properties": { + "confidence": { + "format": "double", + "type": "number" + }, + "legend": { + "additionalProperties": { + "type": "string" + }, + "type": "object" + }, + "probabilities": { + "additionalProperties": { + "format": "double", + "type": "number" + }, + "type": "object" + }, + "score": { + "description": "Probability-weighted level index; may fall between levels.", + "format": "double", + "type": "number" + }, + "type": { + "const": "score", + "type": "string" + } + }, + "required": [ + "type", + "score", + "legend", + "probabilities", + "confidence" + ], + "type": "object" + }, + { + "properties": { + "noul": { + "description": "Probability that the answer is true.", + "format": "double", + "type": "number" + }, + "type": { + "const": "noul", + "type": "string" + } + }, + "required": [ + "type", + "noul" + ], + "type": "object" + } + ] + }, "FinishReason": { "enum": [ "stop", @@ -74,6 +163,34 @@ "seed" ], "type": "object" + }, + { + "properties": { + "answers": { + "additionalProperties": { + "$ref": "#/$defs/DecisionAnswer" + }, + "type": "object" + }, + "input_tokens": { + "description": "Prompt tokens evaluated across all questions, when reported.", + "format": "uint64", + "minimum": 0, + "type": [ + "integer", + "null" + ] + }, + "kind": { + "const": "decisions", + "type": "string" + } + }, + "required": [ + "kind", + "answers" + ], + "type": "object" } ] } diff --git a/tests/fixtures/pumas-image-to-text-v1/source.json b/tests/fixtures/pumas-image-to-text-v1/source.json index e3254144..40d6dc5d 100644 --- a/tests/fixtures/pumas-image-to-text-v1/source.json +++ b/tests/fixtures/pumas-image-to-text-v1/source.json @@ -1,32 +1,45 @@ { "producer_repository": "MrScripty/Pumas-Library", - "producer_pr": 68, - "producer_commit": "36c2aab2c885b8416fd4e39cf8c37c510596d6e4", - "contract_url": "https://github.com/MrScripty/Pumas-Library/blob/36c2aab2c885b8416fd4e39cf8c37c510596d6e4/docs/contracts/image-to-text-v0.8.md", + "producer_branch": "feat/v080-consumer-api", + "producer_commit": "4c79cd8e35db566b70caaa13d8d8f92265f5976e", + "producer_tree": "c646a01d5cc88814bdd2dd7e4565d9d1deda2203", + "contract_path": "docs/contracts/model-operations-v1.md", + "contract_url": "https://github.com/MrScripty/Pumas-Library/blob/4c79cd8e35db566b70caaa13d8d8f92265f5976e/docs/contracts/model-operations-v1.md", + "contract_sha256": "ab0f8a2c9b01f89a28d9a03ed3a9d9246eb6d1665ee2690a4fd2bcb8ff0f9d44", "fixture_kind": "Source-derived controlled consumer fixture; not actual native DTO export or model inference", "inspected_source_sha256": { - "types.rs": "875977948163c4256e60783d540337f117ec70edb1bb3636e7598e516587cca3", - "model_operations.rs": "7c4dfac738db1af29b576691ee929f873b141c7c8e9549e11bc44c4ee1e05c28", - "projection.rs": "444c500edd7ca3ea478d37e68212f8da9325028b87a35f6cdedb3e0e8aaed7a7", - "vision_tests.rs": "e2c175c8d1eab53227d1a91b0fca4621838081ec1d587325ff29312f93be41d6" + "types.rs": "dc4e11a3de059f268c7bbf0f2008b4d1710f5ca6e8c20d06608e67773579bbd0", + "model_operations.rs": "2ffd1b7e215fc0da59fbb70acfbd6a5beb2aa4370fb15546afc7a16f6b49ef16", + "projection.rs": "7357166a8ef9e73b29602323b6ef3d7cca3364b9a18ac0a4715f467e9080f9d8", + "vision_tests.rs": "ce340d0dfe576196330e85b6a92151e6d7329dd9878a0c39e52f0f8126a0dc5a" }, - "schema_export_status": "Six actual production Rust DTO schemas were regenerated at schema_export_commit. The reviewed producer retains identical DTO definitions and schema dependencies; all six SHA-256 identities are unchanged. Handler and controlled-test source hashes are refreshed. The merged main source tree matches the reviewed producer exactly. Packaged/native qualification remains separate.", "inspected_source_native_blob_sha": { - "types.rs": "f7d70f90770deb124dc17dde5212d88b058d9e0e", - "model_operations.rs": "13d15ea4805cfc4df103951d974d76f8987d2964", - "projection.rs": "2a2061a0659a916998455bd22cbc55a7b7f4b0a6", - "vision_tests.rs": "531ff6b48c450800e860a5bc98ea7f00fe27fd3b" + "types.rs": "4b5414db04e62af6d1e39a3c39455ed6bc23e546", + "model_operations.rs": "64ed36cf3606f3028a3a2ec641d02790e71e56fc", + "projection.rs": "c1595de051af74c752e2553e6d2f3c5159c1f47e", + "vision_tests.rs": "4de87a94aba30ec82f19e49c4a8e47ef6de49654" }, - "originating_vision_pr": 65, + "schema_export_status": "Six actual production Rust DTO schemas were regenerated at schema_export_commit with the export-contract feature. The controlled capability fixture follows that commit's descriptor construction for a llama.cpp vision serving with an 8192-token context. Packaged/native qualification remains separate.", "actual_dto_schema_sha256": { - "capabilities-response.schema.json": "b55b150f6958239e71d71f1b28fd36450907ddccf78544d52b64543ad4f2493d", - "capability-descriptor.schema.json": "eb25783123d38de5ff6aedf4cfa69de8f4f5f5c60799768b1b90da258b85f922", - "error-response.schema.json": "b024363b19d55a004d9577ad04d7e2ec9209d3d1193b7c53c46a7d6ed401e3be", - "modality-request.schema.json": "24b5f0a73a1252d31a3b22687a84f07b16a9d3ea700809a42e615e7f4e668704", - "operation-request.schema.json": "08f46f0e79c6cb288c413b008abbdfbedb1898d02fb98d396ef73faf8634c642", - "operation-response.schema.json": "20bf98dfd7292b1e3a99bf34ec524858351ba6f9d226f17257362e9ddf0500f8" + "capabilities-response.schema.json": "e1949bef5e7480f2808f2f1ec66e77adf438e44c6d000a04430bbf15d117a04e", + "capability-descriptor.schema.json": "c586a54fd8c0524dfcbae00dd298d5ee06bb70675c78e871b8a82a77c7ba5316", + "error-response.schema.json": "6b681ab7c7f224e2a35dddaeeb113e9ee2069b058904ced3390c17d1fe36c218", + "modality-request.schema.json": "feb94daa68db1003eb633161ef72431611c1cd5eb6c3096f20c2b69d4a6b9162", + "operation-request.schema.json": "a09fac92af50255d960d1d27ce570c7f89dd377bd7733cead30c4f7fea70a5c5", + "operation-response.schema.json": "17f366d747de6a0047d40a5e549af5abe7045a3a8f64d987c398b7786488d476" }, - "schema_export_command": "PUMAS_IMAGE_CONTRACT_EXPORT_DIR=... ORT_SKIP_DOWNLOAD=1 CARGO_BUILD_JOBS=1 cargo test --locked --offline --manifest-path rust/Cargo.toml -p pumas-rpc --bin pumas-rpc --all-features handlers::model_operations::types::image_to_text_schema_tests::image_to_text_actual_dto_schema_export", - "producer_tree": "cf4d3ca3fbaa77ccd7ba2ebd10c7e9d5ba434ef4", - "schema_export_commit": "5c7d78d7e4eefe65f2395bb3ca2d7bc2ada83c2f" + "schema_export_command": "PUMAS_IMAGE_CONTRACT_EXPORT_DIR=... cargo test --locked -p pumas-rpc --features export-contract image_to_text_actual_dto_schema_export (from rust/)", + "schema_export_commit": "4c79cd8e35db566b70caaa13d8d8f92265f5976e", + "previous_producer": { + "producer_pr": 68, + "producer_commit": "36c2aab2c885b8416fd4e39cf8c37c510596d6e4", + "actual_dto_schema_sha256": { + "capabilities-response.schema.json": "b55b150f6958239e71d71f1b28fd36450907ddccf78544d52b64543ad4f2493d", + "capability-descriptor.schema.json": "eb25783123d38de5ff6aedf4cfa69de8f4f5f5c60799768b1b90da258b85f922", + "error-response.schema.json": "b024363b19d55a004d9577ad04d7e2ec9209d3d1193b7c53c46a7d6ed401e3be", + "modality-request.schema.json": "24b5f0a73a1252d31a3b22687a84f07b16a9d3ea700809a42e615e7f4e668704", + "operation-request.schema.json": "08f46f0e79c6cb288c413b008abbdfbedb1898d02fb98d396ef73faf8634c642", + "operation-response.schema.json": "20bf98dfd7292b1e3a99bf34ec524858351ba6f9d226f17257362e9ddf0500f8" + } + } } diff --git a/tests/test_ai.py b/tests/test_ai.py index dcf601ae..b39c3818 100644 --- a/tests/test_ai.py +++ b/tests/test_ai.py @@ -68,6 +68,13 @@ def test_server_error_explains_missing_projector(self): self.data.suggest(dict(self.body,model='missing-projector')) self.assertIsNone(self.data.sample(self.sample['id'])['annotation']) + def test_pumas_refusal_reason_is_shown_for_any_status(self): + with self.assertRaisesRegex(ai_codex.CodexError, 'HTTP 409.*Pumas reported: model corners-test is served by profiles a, b'): + self.data.suggest(dict(self.body,model='pumas-conflict')) + with self.assertRaises(ai_codex.CodexError) as caught: + self.data.suggest(dict(self.body,model='plain-conflict')) + self.assertNotIn('private upstream wording',str(caught.exception)) + def test_openrouter_catalog_and_auth(self): with patch.object(ai_openrouter,'BASE_URL',self.url): catalog=ai.models(dict(provider='openrouter',api_key='test-key')) diff --git a/tests/test_image_generation.py b/tests/test_image_generation.py index 93e7f74b..576d27e4 100644 --- a/tests/test_image_generation.py +++ b/tests/test_image_generation.py @@ -64,6 +64,23 @@ def test_unprocessable_fields_name_a_contract_mismatch(self): with self.assertRaisesRegex(ValueError, 'contract'): self.manager.generate({**self.body(), 'prompt': 'unprocessable', 'width': 33, 'height': 33}) self.assertEqual(len(self.requests), 1) + def test_pumas_error_message_is_shown_redacted(self): + with self.assertRaises(ValueError) as caught: + self.manager.generate({**self.body(), 'prompt': 'pumas-refusal'}) + message = str(caught.exception) + self.assertIn('Pumas rejected the image request', message) + self.assertIn('Pumas reported: width 33 is not a multiple of 8', message) + self.assertNotIn('sk-abcdefghijkl', message) + with self.assertRaises(ValueError) as caught: + self.manager.generate({**self.body(), 'prompt': 'busy'}) + self.assertNotIn('Pumas reported', str(caught.exception)) + def test_pumas_error_detail_only_reads_pumas_shaped_bodies(self): + import ai_http + self.assertEqual(ai_http.pumas_error_detail(b'{"error":{"message":"m","type":"server_error"}}'), '') + self.assertEqual(ai_http.pumas_error_detail(b''), '') + self.assertEqual(ai_http.pumas_error_detail(b'{"error":{"message":" ","type":"pumas_error"}}'), '') + self.assertEqual(ai_http.pumas_error_detail(b'{"error":{"message":"context window exceeded","type":"pumas_error"}}'), + 'Pumas reported: context window exceeded') def test_no_duration_deadline_remains_and_connect_stays_bounded(self): source = Path(image_generation.__file__).read_text() self.assertFalse(hasattr(image_generation, 'TIMEOUT')) diff --git a/tests/test_pumas_typed.py b/tests/test_pumas_typed.py index b6b76be2..059ddd55 100644 --- a/tests/test_pumas_typed.py +++ b/tests/test_pumas_typed.py @@ -190,18 +190,61 @@ def test_grounded_rewrite_stays_in_source_family_and_draft(self): self.assertEqual(record['review'],'draft'); self.assertEqual(record['parents'],[row['id']]) self.assertEqual(record['groups'],row['groups']); self.assertEqual(record['provenance']['rights'],row['provenance']['rights']) self.assertEqual(record['provenance']['canonical_request']['profile'],'controlled-text-cpu') - def test_manifest_hash_closed_semantics_nonfinite_intervals(self): + def test_manifest_hash_additive_semantics_nonfinite_intervals(self): raw=(FIXTURES/'controlled-text-capabilities.json').read_bytes(); observed=pumas.validate_manifest(raw) self.assertEqual(observed['observed_sha256'],hashlib.sha256(raw).hexdigest()) self.assertEqual(pumas.models(self.url)['models'][0]['id'],'controlled-text') self.state['duplicate_alias']=True self.assertEqual(len(pumas.models(self.url)['models']),2) - for mutate in (lambda v:v.update(extra=1),lambda v:v['capabilities'][0].update(capability={}), - lambda v:v['capabilities'][0]['option_bounds'][0].update(minimum=10**500), + # Additive fields and unrecognised capability entries are ignored, never refused. + for mutate in (lambda v:v.update(extra=1,context_tokens=4096),lambda v:v['capabilities'][0].update(capability={}), + lambda v:v['capabilities'].append({'capability':'decision','semantic_task':'decision'}), + lambda v:v['capabilities'][0]['option_bounds'].append({'option':'top_k','minimum':'n/a'})): + value=copy.deepcopy(observed['capabilities']); mutate(value) + pumas.validate_manifest(json.dumps(value).encode()) + value=copy.deepcopy(observed['capabilities']); value['capabilities'][0].update(capability={}) + with self.assertRaises(pumas.OperationError): + pumas.require(pumas.validate_manifest(json.dumps(value).encode()),'chat_generation','messages_text','text',{'max_tokens':1}) + for mutate in (lambda v:v['capabilities'][0]['option_bounds'][0].update(minimum=10**500), lambda v:v['capabilities'][0]['option_bounds'][0].update(minimum=10,maximum=1), lambda v:v['capabilities'][0].update(availability={'state':'unavailable','reason':{}})): value=copy.deepcopy(observed['capabilities']); mutate(value) with self.assertRaises(ValueError): pumas.validate_manifest(json.dumps(value).encode()) + def test_served_models_listing_profiles_and_fallback(self): + self.state['served_models']={'supported_contract_versions':[1],'max_request_bytes':1,'max_response_bytes':1,'max_stream_event_bytes':1, + 'future':True,'models':[ + {'model':'shared','profile':'gpu','model_id':'lib/a','provider':'llama_cpp','load_state':'loaded','profile_required':True,'capabilities':[],'extra':1}, + {'model':'shared','profile':'cpu','model_id':'lib/a','provider':'llama_cpp','load_state':'loading','profile_required':True,'capabilities':[]}, + {'model':'controlled-text','profile':'controlled-text-cpu','model_id':'lib/t','provider':'ollama','load_state':'loaded','context_tokens':8192, + 'profile_required':False,'capabilities':[]}]} + listed=pumas.models(self.url) + self.assertEqual(listed['source'],'/v1/served-models') + rows={row['id']:row for row in listed['models']} + self.assertEqual(rows['shared']['profiles'],['gpu','cpu']); self.assertTrue(rows['shared']['profile_required']) + self.assertIn('choose one',rows['shared']['name']); self.assertEqual(rows['controlled-text']['name'],'controlled-text') + self.state['served_models']=None + self.assertEqual(pumas.models(self.url)['source'],'/v1/models') + def test_capability_refusals_surface_pumas_message(self): + with self.assertRaises(pumas.OperationError) as caught: pumas.capabilities(self.url,'missing-model') + self.assertIn("no served model is named 'missing-model'",str(caught.exception)); self.assertIn('model_not_found',str(caught.exception)) + self.assertEqual(caught.exception.outcome,'not_admitted') + self.state['ambiguous']=True + with self.assertRaises(pumas.OperationError) as caught: pumas.capabilities(self.url,'controlled-text') + self.assertIn('send profile',str(caught.exception)) + self.state['ambiguous']=False; self.state['mode']='unavailable' + job=self.generate(); self.assertIn('runtime_unavailable',job['error']); self.assertFalse(self.state['requests']) + def test_typed_error_outcome_is_authoritative_and_message_is_retained(self): + for mode,status in (('not_admitted',502),('not_admitted',404),('not_admitted',409),('unknown',400),('unknown',503)): + with self.subTest(mode=mode,status=status): + self.state.update(mode=mode,error_status=status,error_message='provider said '+str(status)) + job=self.generate() + self.assertEqual(job['provider_outcome'],mode); self.assertEqual(job['provider_http_status'],status) + self.assertIn('provider said '+str(status),job['error']) + self.state['mode']='unreadable'; job=self.generate() + self.assertEqual(job['provider_outcome'],'not_admitted'); self.assertIn('not valid JSON',job['error']) + self.state.update(mode='not_admitted',error_status=503,error_message='image runtime is busy') + with self.assertRaises(pumas.OperationError) as caught: self.data.image_requests.generate(self.image()) + self.assertIn('image runtime is busy',str(caught.exception)); self.assertEqual(caught.exception.outcome,'not_admitted') for raw in (b'{"x":1,"x":2}',b'{"x":NaN}',b'{','{"x":1}'.encode('utf-16')): with self.assertRaises(ValueError): pumas.strict_json(raw) diff --git a/tests/test_pumas_vision.py b/tests/test_pumas_vision.py index 22f8a860..91641985 100644 --- a/tests/test_pumas_vision.py +++ b/tests/test_pumas_vision.py @@ -1,4 +1,4 @@ -"""Application acceptance of source-derived vision fixtures and actual DTO schema pins, not inference.""" +"""Application acceptance of source-derived v0.8 vision fixtures and actual DTO schema pins, not inference.""" from auth_helpers import bind_owner import base64 import copy @@ -11,6 +11,7 @@ import uuid from unittest.mock import patch +import jsonschema from PIL import Image from app import Dataset from fake_pumas_vision import FIXTURES, start @@ -39,22 +40,74 @@ def test_actual_dto_schema_identities_and_closed_capability_enum(self): self.assertEqual(hashlib.sha256(raw).hexdigest(), digest, name) self.assertEqual(json.loads(raw)['$schema'], 'https://json-schema.org/draft/2020-12/schema') descriptor = json.loads((FIXTURES/'schemas/capability-descriptor.schema.json').read_text()) - self.assertEqual(set(descriptor['$defs']['Capability']['enum']), set(pumas.CAPABILITIES)) + # Documented capability variants export as `oneOf`; new ones are appended additively. + variants = descriptor['$defs']['Capability']['oneOf'] + names = [name for row in variants for name in row.get('enum', [row.get('const')])] + self.assertTrue(set(pumas.USED_CAPABILITIES) <= set(names)) + self.assertTrue({'multimodal_embedding', 'decision'} <= set(names)) + error = json.loads((FIXTURES/'schemas/error-response.schema.json').read_text()) + self.assertIn('message', error['$defs']['OperationError']['required']) + self.assertEqual(error['properties']['request_id']['type'], ['string', 'null']) for name in ('operation-request', 'modality-request'): schema = json.loads((FIXTURES/'schemas'/(name+'.schema.json')).read_text()) self.assertFalse(schema['additionalProperties']) self.assertEqual(schema['$defs']['ImageEncoding']['enum'], ['png','jpeg']) - def test_seven_source_derived_descriptors_hash_reasons_and_closed_fields(self): + def test_source_derived_descriptors_validate_against_actual_schemas(self): + schemas = {name: json.loads((FIXTURES/'schemas'/(name+'.schema.json')).read_text()) for name in ( + 'capabilities-response', 'operation-request', 'modality-request', 'operation-response', 'error-response')} + def valid(name, value): jsonschema.Draft202012Validator(schemas[name]).validate(value) + valid('capabilities-response', json.loads((FIXTURES/'controlled-capabilities.json').read_bytes())) + valid('operation-request', vision.request(self.job(), image(), facade=False)) + valid('operation-request', vision.request(self.job(), {'kind':'image_messages','messages':[{'role':'user','content':[image()]}]}, facade=False)) + valid('modality-request', {key: value for key, value in vision.request(self.job(), image('jpeg')).items()}) + valid('operation-response', {'contract_version':1,'request_id':'caption-17','result':{'kind':'text','text':'x','finish_reason':'stop'}}) + valid('error-response', {'contract_version':1,'request_id':None,'error':{'code':'invalid_request','outcome':'not_admitted','message':'unreadable body'}}) + def test_source_derived_descriptors_hash_and_select_by_name(self): raw = (FIXTURES/'controlled-capabilities.json').read_bytes() observed = pumas.validate_manifest(raw) self.assertEqual(observed['observed_sha256'],hashlib.sha256(raw).hexdigest()) - self.assertEqual(set(row['capability']for row in observed['capabilities']['capabilities']),set(pumas.CAPABILITIES)) - self.assertEqual(len(pumas.CAPABILITIES),7) - self.assertEqual(observed['capabilities']['capabilities'][4]['option_bounds'][0]['option'],'max_output_tokens') - for mutate in (lambda row:row.update(capability='image_understanding'),lambda row:row['input_formats'].append('image_url'), - lambda row:row['option_bounds'][0].update(maximum=float('inf')),lambda row:row.update(semantic_task='chat_generation')): - value = copy.deepcopy(observed['capabilities']); mutate(value['capabilities'][-1]) - with self.assertRaises(ValueError): pumas.validate_manifest(json.dumps(value).encode()) + names = [row['capability'] for row in observed['capabilities']['capabilities']] + self.assertTrue({'multimodal_embedding','decision'} | set(pumas.USED_CAPABILITIES) <= set(names)) + self.assertEqual(observed['capabilities']['context_tokens'], 8192) + self.assertEqual(pumas.descriptor(observed,'audio_transcription')['option_bounds'][0]['option'],'max_output_tokens') + vision_row = pumas.descriptor(observed,'image_to_text') + self.assertEqual(next(b for b in vision_row['option_bounds'] if b['option']=='max_tokens')['maximum'], 8192) + def test_additive_fields_capabilities_formats_options_and_reasons_are_ignored(self): + value = json.loads((FIXTURES/'controlled-capabilities.json').read_bytes()) + value.update(future_field={'nested':True}, supported_contract_versions=[2,1]) + value['capabilities'].reverse() + value['capabilities'].insert(3, {'capability':'image_understanding','semantic_task':'x','input_formats':[7],'availability':'odd'}) + value['capabilities'].append('not even an object') + row = next(r for r in value['capabilities'] if type(r) is dict and r['capability']=='image_to_text') + row['input_formats'].append('image_url'); row['output_formats'].append('future'); row['future'] = 1 + row['option_bounds'].insert(0, {'option':'future_option','minimum':'unbounded'}) + row['option_bounds'].append({'option':'max_tokens_hint','minimum':1,'maximum':1}) + for item in value['capabilities']: + if type(item) is dict and item.get('capability') == 'decision': + item['availability'] = {'state':'unavailable','reason':'future_reason'} + observed = pumas.validate_manifest(json.dumps(value).encode()) + pumas.require(observed,'image_to_text','messages_image','text',{'max_tokens':4096,'image_count':1}) + with self.assertRaises(pumas.OperationError) as caught: + pumas.require(observed,'image_to_text','messages_image','text',{'max_tokens':8193}) + self.assertIn('8192', str(caught.exception)) + with self.assertRaises(pumas.OperationError) as caught: + pumas.require(observed,'decision','decision','decisions',{}) + self.assertIn('future_reason', str(caught.exception)) + del value['context_tokens']; del value['max_stream_event_bytes'] + pumas.validate_manifest(json.dumps(value).encode()) + def test_used_descriptor_fields_are_still_validated(self): + observed = pumas.validate_manifest((FIXTURES/'controlled-capabilities.json').read_bytes()) + def vision_row(value): return next(r for r in value['capabilities'] if r['capability']=='image_to_text') + for mutate in (lambda v:vision_row(v)['option_bounds'][0].update(maximum=float('inf')), + lambda v:vision_row(v).update(semantic_task='chat_generation'), + lambda v:vision_row(v).update(input_formats='messages_image'), + lambda v:vision_row(v).update(availability={'state':'unavailable','reason':{}}), + lambda v:vision_row(v)['option_bounds'].append({'option':'max_tokens','minimum':1,'maximum':2}), + lambda v:v['capabilities'].append(copy.deepcopy(vision_row(v))), + lambda v:v.update(supported_contract_versions=[2]), + lambda v:v.update(profile=None), lambda v:v.pop('capabilities')): + value = copy.deepcopy(observed['capabilities']); mutate(value) + with self.subTest(value=value), self.assertRaises(ValueError): pumas.validate_manifest(json.dumps(value).encode()) def test_named_and_facade_image_order_and_original_compressed_bytes(self): for encoding in ('png','jpeg'): part = image(encoding,progressive=encoding=='jpeg') @@ -98,18 +151,40 @@ def messages(parts,role='user'):return {'kind':'messages','messages':[{'role':ro with self.assertRaises(ValueError): vision.request(self.job(),value) self.assertEqual((vision.MAX_IMAGE,vision.MAX_AGGREGATE,vision.MAX_REQUEST,vision.MAX_IMAGES),(8388608,16777216,33554432,4)) def test_finite_options_and_correlated_typed_result_without_model(self): - for key,value in [('max_tokens',0),('max_tokens',2049),('max_tokens',True),('temperature',float('nan')), + for key,value in [('max_tokens',0),('max_tokens',2**32),('max_tokens',True),('temperature',float('nan')), ('temperature',3),('top_p',float('inf')),('top_p',-1)]: with self.assertRaises(ValueError): vision.request(self.job(),image(),**{key:value}) - request=vision.request(self.job(),image(),max_tokens=2048,temperature=2,top_p=1) - self.assertEqual(request['options'],{'kind':'text_generation','max_tokens':2048,'temperature':2,'top_p':1}) + # No fixed 2048 cap: the live max_tokens bound follows the served context. + request=vision.request(self.job(),image(),max_tokens=8192,temperature=2,top_p=1) + self.assertEqual(request['options'],{'kind':'text_generation','max_tokens':8192,'temperature':2,'top_p':1}) response={'contract_version':1,'request_id':'caption-17','result':{'kind':'text','text':'A blue rectangle.','finish_reason':'stop'}} self.assertEqual(pumas.result(encode(response).encode(),'caption-17')['text'],'A blue rectangle.') - for mutate in (lambda v:v.update(request_id='foreign'),lambda v:v.update(model='private'), - lambda v:v['result'].update(finish_reason='length'),lambda v:v['result'].update(extra='private')): + for mutate in (lambda v:v.update(model='additive'),lambda v:v['result'].update(extra='additive')): + value=copy.deepcopy(response);mutate(value) + self.assertEqual(pumas.result(encode(value).encode(),'caption-17')['text'],'A blue rectangle.') + for mutate in (lambda v:v.update(request_id='foreign'),lambda v:v['result'].update(finish_reason='length'), + lambda v:v.update(contract_version=2),lambda v:v['result'].update(kind='decisions')): value=copy.deepcopy(response);mutate(value) with self.assertRaises(pumas.OperationError)as caught:pumas.result(encode(value).encode(),'caption-17') self.assertEqual(caught.exception.outcome,'unknown') + def test_typed_errors_use_outcome_message_and_null_request_id(self): + def error(request_id='caption-17', **fields): + body={'code':'model_not_found','outcome':'not_admitted','message':'no served model is named "x"'}; body.update(fields) + return encode({'contract_version':1,'request_id':request_id,'error':body}).encode() + cases=[(error(),'not_admitted','model_not_found'),(error(None,code='invalid_request'),'not_admitted','invalid_request'), + (error(code='ambiguous_operation'),'not_admitted','ambiguous_operation'), + (error(code='future_code'),'not_admitted','future_code'), + (error(code='provider_failure',outcome='unknown'),'unknown','provider_failure'), + (error(outcome='future_outcome'),'unknown','model_not_found')] + for raw,outcome,code in cases: + with self.subTest(raw=raw),self.assertRaises(pumas.OperationError)as caught:pumas.result(raw,'caption-17') + self.assertEqual((caught.exception.outcome,caught.exception.provider_code),(outcome,code)) + self.assertIn('no served model is named "x"',str(caught.exception)) + for raw in (error('foreign'),error(code=7),encode({'contract_version':1,'request_id':'caption-17','error':'text'}).encode()): + with self.subTest(raw=raw),self.assertRaises(pumas.OperationError)as caught:pumas.result(raw,'caption-17') + self.assertEqual(caught.exception.outcome,'unknown') + with self.assertRaises(pumas.OperationError)as caught:pumas.result(error(message='x'*5000+'\nnext'),'caption-17') + self.assertLess(len(str(caught.exception)),800);self.assertNotIn('\n',str(caught.exception)) class VisionApplicationTests(unittest.TestCase): @@ -151,16 +226,24 @@ def test_build_selection_and_unavailability_refuse_without_post(self): for mode in ('missing_build','unavailable','wrong_profile','wrong_model'): self.state['mode']=mode;job=self.generate() self.assertEqual(job['status'],'failed');self.assertEqual(job['provider_outcome'],'not_admitted') + if mode=='unavailable':self.assertIn('runtime_unavailable',job['error']) self.assertFalse(self.state['requests']) with self.assertRaises(ValueError):self.data.caption_proposals.start(self.body(seed=42)) def test_http_refusals_outcomes_and_uncertain_failures_are_never_replayed(self): - for status in (400,413,422,503,502): - mode='unknown'if status==502 else'not_admitted' - self.state.update(mode=mode,refusal_status=status);body=self.body();job=self.generate(body) - self.assertEqual(job['provider_outcome'],mode);self.assertEqual(job['provider_http_status'],status) + # `outcome` is authoritative, not the HTTP status (404/409 are ordinary refusals). + cases=[(400,'not_admitted'),(404,'not_admitted'),(409,'not_admitted'),(413,'not_admitted'),(422,'not_admitted'), + (503,'not_admitted'),(502,'not_admitted'),(502,'unknown'),(500,'unknown'),(400,'unknown')] + for status,mode in cases: + self.state.update(mode=mode,refusal_status=status,error_message='reason for '+str(status));body=self.body();job=self.generate(body) + self.assertEqual(job['provider_outcome'],mode,status);self.assertEqual(job['provider_http_status'],status) + self.assertIn('reason for '+str(status),job['error']) self.data.caption_proposals.start(body) - self.assertEqual(len(self.state['requests']),5) - for mode in ('wrong_id','private','length','nonfinite','oversized','truncated','loss'): + self.state['mode']='unreadable';job=self.generate() + self.assertEqual(job['provider_outcome'],'not_admitted');self.assertEqual(job['provider_error_code'],'invalid_request') + self.assertIn('request body is not valid JSON',job['error']) + self.assertEqual(len(self.state['requests']),len(cases)+1) + self.state['mode']='additive';self.assertEqual(self.generate()['status'],'completed') + for mode in ('wrong_id','length','nonfinite','oversized','truncated','loss'): self.state['mode']=mode;body=self.body();before=len(self.state['requests']);job=self.generate(body) self.assertEqual(job['status'],'failed',mode);self.assertEqual(job['provider_outcome'],'unknown',mode) self.data.caption_proposals.start(body);self.assertEqual(len(self.state['requests']),before+1) From 50bbc884310122d71d0d98e6b9ab6371e0636c58 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Mon, 2 Nov 2026 19:25:42 -0700 Subject: [PATCH 002/131] fix(pumas): ignore additive fields in the /.well-known/pumas advertisement The gateway advertisement decoder was closed: any field Pumas added to the advertisement, or more than 64 entries in an open list, made the gateway disappear from scans. Required fields are now checked for presence and type only. Unknown fields are ignored and dropped from the decoded advertisement, so the stored build observation keeps only the known fields; list-length caps give way to the 64 KiB body bound. Missing required fields, wrong types, unsupported schema versions and malformed endpoints still fail, now as descriptor.Rejected with a reason naming the field. A gateway scan returns refused advertisements under `rejected` with their reasons, and the chooser shows them. Co-Authored-By: Claude Opus 5.5 --- .../contracts/pumas-image-to-text-consumer.md | 9 +- gateway_discovery.py | 13 +- pumas_gateway_descriptor.py | 166 +++++++++++------- static/pumas-gateways.js | 4 +- tests/test_pumas_gateways.py | 67 ++++++- 5 files changed, 185 insertions(+), 74 deletions(-) diff --git a/docs/contracts/pumas-image-to-text-consumer.md b/docs/contracts/pumas-image-to-text-consumer.md index 287693cf..c557e28e 100644 --- a/docs/contracts/pumas-image-to-text-consumer.md +++ b/docs/contracts/pumas-image-to-text-consumer.md @@ -40,8 +40,13 @@ Choose **Pumas typed v1** in the image caption form, select the serving alias an optional exact profile, and inspect capabilities. On each new attempt, the owner requires `pumas.model-operations.image-to-text:1` in the gateway build advertisement and an available Image→Text descriptor for the exact resolved model/profile. The -gateway advertisement keeps its own closed, versioned decoder: it is retained as -evidence, so unknown advertisement fields are refused rather than stored. +gateway advertisement (`GET /.well-known/pumas`) has its own versioned decoder, +which also grows additively: unknown fields and new protocol, schema, capability or +compiled-feature entries are ignored and are not retained in the stored build +observation, which keeps only the known fields. Missing required fields, wrong +types, unsupported schema versions and malformed endpoints are refused with a +reason naming the field; a gateway scan lists such refused advertisements with +their reasons instead of hiding them. The request uses the facade's `messages`, `semantic_task:"image_to_text"`, text-generation options and `stream:false`. The seed is omitted. Named image and `image_messages` inputs are also supported by the bounded consumer request builder. diff --git a/gateway_discovery.py b/gateway_discovery.py index db3afc8b..7528c658 100644 --- a/gateway_discovery.py +++ b/gateway_discovery.py @@ -218,15 +218,20 @@ def scan_advertised(): def observe(item): host, port = item address = '[' + host + ']' if ':' in host else host + url = f'http://{address}:{port}' try: - return inspect_advertised(f'http://{address}:{port}', deadline) + return inspect_advertised(url, deadline), None + except descriptor.Rejected as error: + # Pumas answered but its advertisement was refused: keep the reason for the user. + return None, {'server_url': url, 'reason': str(error)} except (OSError, ValueError, TypeError, http.client.HTTPException): - return None + return None, None with ThreadPoolExecutor(max_workers=32) as pool: results = list(pool.map(observe, endpoints)) # Distinct IPv4/IPv6 services on one port must retain their library context. - found = {row['server_url']: row for row in results if row is not None} - return {'gateways': list(found.values()), 'qualification': + found = {row['server_url']: row for row, _ in results if row is not None} + rejected = [refusal for _, refusal in results if refusal is not None] + return {'gateways': list(found.values()), 'rejected': rejected, 'qualification': 'Read-only HTTP advertisements. Core ownership is not authenticated; compiled features do not prove model readiness.'} finally: SCAN_LOCK.release() diff --git a/pumas_gateway_descriptor.py b/pumas_gateway_descriptor.py index eb25b9f1..b1eb3ec0 100644 --- a/pumas_gateway_descriptor.py +++ b/pumas_gateway_descriptor.py @@ -1,12 +1,23 @@ -"""Decode the public Pumas PR51 HTTP advertisement; no owner authentication.""" +"""Decode the public Pumas HTTP advertisement (`GET /.well-known/pumas`); no owner authentication. + +The advertisement grows additively. Unknown fields and new entries in open lists +(protocols, schemas, capabilities, compiled features) are ignored: they are neither +errors nor retained in the decoded advertisement. Missing required fields, wrong +types, unsupported schema versions and malformed endpoints are refused with a +reason naming the field. +""" import hashlib import ipaddress import json from urllib.parse import urlsplit SOURCE_COMMIT = '80f06ab17f9eea639fee143c86319ca9b5e1a21c' +# Transport bound. Open lists have no entry-count cap of their own. MAX_DESCRIPTION_BYTES = 64 * 1024 -MAX_ITEMS = 64 + + +class Rejected(ValueError): + """A Pumas advertisement that was read and refused. The message is the reason.""" def endpoint(value): @@ -28,60 +39,82 @@ def endpoint(value): return f'http://{address}:{port}' -def _text(value, limit=4096): +def _fail(where, problem): + raise Rejected(' '.join(filter(None, ('Pumas advertisement', where, problem))) + '.') + + +def _text(value, where, limit=4096): if not isinstance(value, str) or not value or len(value) > limit: - raise ValueError('Invalid Pumas descriptor text.') - value.encode('utf-8', errors='strict') + _fail(where, f'must be a nonempty string of at most {limit} characters') + try: + value.encode('utf-8', errors='strict') + except UnicodeError: + _fail(where, 'must be valid Unicode text') -def _uint(value): +def _uint(value, where): if type(value) is not int or not 0 <= value <= 4294967295: - raise ValueError('Invalid Pumas descriptor integer.') + _fail(where, 'must be an unsigned 32-bit integer') -def _object(value, required, optional=()): - if type(value) is not dict or not set(required) <= value.keys() or value.keys() - set(required) - set(optional): - raise ValueError('Unsupported Pumas descriptor fields.') +def _version(value, where): + if type(value) is not int: + _fail(where, 'must be an integer') + if value != 1: + raise Rejected(f'Pumas advertisement {where} {value} is unsupported; Tuldok supports version 1.') -def _list(value): - if type(value) is not list or len(value) > MAX_ITEMS: - raise ValueError('Invalid Pumas descriptor list.') +def _object(value, where, required, optional=()): + """Open shape: every required field present. Returns only the known fields.""" + if type(value) is not dict: + _fail(where, 'must be an object') + missing = [name for name in required if name not in value] + if missing: + _fail(where, 'is missing required field(s) ' + ', '.join(missing)) + known = set(required) | set(optional) + return {name: item for name, item in value.items() if name in known} -def _strings(value): - _list(value) - for item in value: - _text(item, 512) +def _list(value, where): + if type(value) is not list: + _fail(where, 'must be a list') + return value -def _protocols(value): - _list(value) - for item in value: - _object(item, ('name', 'versions')) - _text(item['name'], 512) - _list(item['versions']) - for version in item['versions']: - _uint(version) +def _strings(value, where): + for index, item in enumerate(_list(value, where)): + _text(item, f'{where}[{index}]', 512) + return list(value) -def _build(value): - _object(value, ('build_info_schema_version', 'component', 'package_version', 'compiled_features', 'protocols', 'schemas'), - ('build_id', 'source_revision', 'target')) - if type(value['build_info_schema_version']) is not int or value['build_info_schema_version'] != 1: - raise ValueError('Unsupported Pumas build-info schema.') +def _protocols(value, where): + result = [] + for index, item in enumerate(_list(value, where)): + item = _object(item, f'{where}[{index}]', ('name', 'versions')) + _text(item['name'], f'{where}[{index}].name', 512) + for position, version in enumerate(_list(item['versions'], f'{where}[{index}].versions')): + _uint(version, f'{where}[{index}].versions[{position}]') + result.append(item) + return result + + +def _build(value, where): + value = _object(value, where, ('build_info_schema_version', 'component', 'package_version', 'compiled_features', + 'protocols', 'schemas'), ('build_id', 'source_revision', 'target')) + _version(value['build_info_schema_version'], where + '.build_info_schema_version') for name in ('component', 'package_version', 'build_id', 'source_revision', 'target'): - if name in value and value[name] is not None: - _text(value[name]) - elif name in ('component', 'package_version'): - raise ValueError('Missing Pumas build identity.') - _strings(value['compiled_features']) - _protocols(value['protocols']) - _list(value['schemas']) - for item in value['schemas']: - _object(item, ('name', 'version')) - _text(item['name'], 512) - _uint(item['version']) + if name in ('component', 'package_version') or value.get(name) is not None: + _text(value[name], f'{where}.{name}') + value['compiled_features'] = _strings(value['compiled_features'], where + '.compiled_features') + value['protocols'] = _protocols(value['protocols'], where + '.protocols') + schemas = [] + for index, item in enumerate(_list(value['schemas'], where + '.schemas')): + item = _object(item, f'{where}.schemas[{index}]', ('name', 'version')) + _text(item['name'], f'{where}.schemas[{index}].name', 512) + _uint(item['version'], f'{where}.schemas[{index}].version') + schemas.append(item) + value['schemas'] = schemas + return value def _pairs(pairs): @@ -102,29 +135,34 @@ def decode(raw): raise ValueError('Pumas descriptor exceeds the 64 KiB observation limit.') try: value = json.loads(raw.decode('utf-8'), object_pairs_hook=_pairs, parse_constant=_constant) - _object(value, ('advertisement_schema_version', 'service_generation', 'instance', 'endpoint', 'build_info')) - if type(value['advertisement_schema_version']) is not int or value['advertisement_schema_version'] != 1: - raise ValueError('Unsupported Pumas HTTP advertisement schema.') - _text(value['service_generation'], 128) - endpoint(value['endpoint']) - instance = value['instance'] - _object(instance, ('discovery_schema_version', 'registry_library_id', 'library_root', 'generation', 'pumas_version', - 'protocols', 'capabilities', 'model_ref_schema_version', 'selector_schema_version'), ('build_info',)) - if type(instance['discovery_schema_version']) is not int or instance['discovery_schema_version'] != 1: - raise ValueError('Unsupported Pumas discovery schema.') - for name in ('registry_library_id', 'library_root', 'generation', 'pumas_version'): - _text(instance[name]) - for name in ('model_ref_schema_version', 'selector_schema_version'): - _uint(instance[name]) - _protocols(instance['protocols']) - _strings(instance['capabilities']) - if instance.get('build_info') is not None: - _build(instance['build_info']) - build = value['build_info'] - _build(build) - if (not any(p['name'] == 'pumas.local-http' and 1 in p['versions'] for p in build['protocols']) - or not any(s['name'] == 'pumas.http-advertisement' and s['version'] == 1 for s in build['schemas'])): - raise ValueError('Unsupported Pumas HTTP protocol/schema advertisement.') except (UnicodeError, RecursionError) as error: raise ValueError('Invalid Pumas descriptor encoding or nesting.') from error + if type(value) is not dict or 'advertisement_schema_version' not in value: + raise ValueError('Not a Pumas HTTP advertisement: advertisement_schema_version is missing.') + value = _object(value, '', ('advertisement_schema_version', 'service_generation', 'instance', 'endpoint', + 'build_info')) + _version(value['advertisement_schema_version'], 'advertisement_schema_version') + _text(value['service_generation'], 'service_generation', 128) + try: + endpoint(value['endpoint']) + except ValueError as error: + raise Rejected(f'Pumas advertisement endpoint is invalid: {error}') from None + instance = value['instance'] = _object( + value['instance'], 'instance', ('discovery_schema_version', 'registry_library_id', 'library_root', 'generation', + 'pumas_version', 'protocols', 'capabilities', 'model_ref_schema_version', + 'selector_schema_version'), ('build_info',)) + _version(instance['discovery_schema_version'], 'instance.discovery_schema_version') + for name in ('registry_library_id', 'library_root', 'generation', 'pumas_version'): + _text(instance[name], 'instance.' + name) + for name in ('model_ref_schema_version', 'selector_schema_version'): + _uint(instance[name], 'instance.' + name) + instance['protocols'] = _protocols(instance['protocols'], 'instance.protocols') + instance['capabilities'] = _strings(instance['capabilities'], 'instance.capabilities') + if instance.get('build_info') is not None: + instance['build_info'] = _build(instance['build_info'], 'instance.build_info') + build = value['build_info'] = _build(value['build_info'], 'build_info') + if not any(p['name'] == 'pumas.local-http' and 1 in p['versions'] for p in build['protocols']): + raise Rejected('Pumas advertisement build_info does not advertise protocol pumas.local-http version 1.') + if not any(s['name'] == 'pumas.http-advertisement' and s['version'] == 1 for s in build['schemas']): + raise Rejected('Pumas advertisement build_info does not advertise schema pumas.http-advertisement version 1.') return {'advertisement': value, 'observed_sha256': hashlib.sha256(raw).hexdigest()} diff --git a/static/pumas-gateways.js b/static/pumas-gateways.js index f6bc193c..6214e738 100644 --- a/static/pumas-gateways.js +++ b/static/pumas-gateways.js @@ -31,7 +31,9 @@ $('pumas-gateway-scan').addEventListener('click',async()=>{ pumasGateways=result.gateways; $('pumas-gateway-choice').replaceChildren(new Option('Choose an advertised gateway',''),...pumasGateways.map(row=> new Option(row.server_url+' · '+row.advertisement.build_info.package_version+' · '+row.advertisement.instance.registry_library_id,row.server_url))); - pumasGatewayStatus(pumasGateways.length?'Choose a gateway and annotation workflow. Model support is checked when you request a proposal.':'No compatible HTTP advertisements found. Start Pumas with HTTP discovery, or enter a legacy gateway URL in the proposal form.'); + // Advertisements Pumas served but Tuldok refused keep their reasons. + const refused=(Array.isArray(result.rejected)?result.rejected:[]).map(row=>' Refused '+row.server_url+': '+row.reason).join(''); + pumasGatewayStatus((pumasGateways.length?'Choose a gateway and annotation workflow. Model support is checked when you request a proposal.':'No compatible HTTP advertisements found. Start Pumas with HTTP discovery, or enter a legacy gateway URL in the proposal form.')+refused); }catch(error){if(token.epoch===pumasGatewayEpoch&&!pumasGatewayPaused)pumasGatewayStatus(error.message);} finally{if(pumasGatewayOperation===token){pumasGatewayOperation=null;renderPumasGateway();}} }); diff --git a/tests/test_pumas_gateways.py b/tests/test_pumas_gateways.py index 2bda674b..7f7d8005 100644 --- a/tests/test_pumas_gateways.py +++ b/tests/test_pumas_gateways.py @@ -57,7 +57,68 @@ def test_exact_named_identity_optional_provenance_and_raw_hash(self): legacy['instance']['build_info'] = None self.assertIsNone(descriptor.decode(json.dumps(legacy).encode())['advertisement']['instance']['build_info']) - def test_versions_boolean_wrong_shapes_unknown_fields_and_oversizing_fail(self): + def test_additive_fields_and_open_list_entries_are_accepted_and_not_retained(self): + additions = [ + lambda v: v.update(future_field={'nested': [1, 2]}), + lambda v: v['instance'].update(connection_token='never retained'), + lambda v: v['instance']['build_info'].update(future_field=True), + lambda v: v['build_info'].update(future_field='ignored'), + lambda v: v['build_info']['protocols'][0].update(future_field='ignored'), + lambda v: v['build_info']['schemas'][0].update(future_field='ignored'), + lambda v: v['build_info']['schemas'].append({'name': 'pumas.discovery', 'version': 2}), + lambda v: v['build_info']['schemas'].append({'name': 'pumas.future-schema', 'version': 1}), + lambda v: v['build_info']['protocols'].append({'name': 'pumas.future-protocol', 'versions': [3]}), + lambda v: v['build_info']['protocols'][-1].update(versions=[1, 2]), + lambda v: v['instance'].update(capabilities=[f'future.capability{i}@1' for i in range(100)]), + ] + for add in additions: + value = fixture(); add(value) + with self.subTest(value=value): + decoded = descriptor.decode(json.dumps(value).encode())['advertisement'] + self.assertEqual(decoded['instance']['registry_library_id'], fixture()['instance']['registry_library_id']) + text = json.dumps(decoded) + self.assertNotIn('future_field', text) + self.assertNotIn('connection_token', text) + value = fixture(); value['future_field'] = 'ignored'; value['instance']['future_field'] = 'ignored' + self.assertEqual(descriptor.decode(json.dumps(value).encode())['advertisement'], fixture()) + endpoint, calls = self.server(value) + self.assertEqual(discovery.inspect_advertised(f'http://127.0.0.1:{endpoint[1]}')['advertisement']['instance'], + fixture()['instance']) + + def test_missing_required_fields_and_unsupported_versions_are_refused_with_reasons(self): + cases = [ + (lambda v: v.pop('service_generation'), + 'Pumas advertisement is missing required field(s) service_generation.'), + (lambda v: v['instance'].pop('generation'), + 'Pumas advertisement instance is missing required field(s) generation.'), + (lambda v: v['build_info'].pop('schemas'), + 'Pumas advertisement build_info is missing required field(s) schemas.'), + (lambda v: v['build_info']['protocols'][0].pop('versions'), + 'Pumas advertisement build_info.protocols[0] is missing required field(s) versions.'), + (lambda v: v.update(advertisement_schema_version=2), + 'Pumas advertisement advertisement_schema_version 2 is unsupported; Tuldok supports version 1.'), + (lambda v: v['instance'].update(selector_schema_version='1'), + 'Pumas advertisement instance.selector_schema_version must be an unsigned 32-bit integer.'), + (lambda v: v.update(endpoint='http://example.com:8765'), + 'Pumas advertisement endpoint is invalid: Enter a numeric-loopback HTTP base URL.'), + ] + for mutate, reason in cases: + value = fixture(); mutate(value) + with self.subTest(reason=reason): + with self.assertRaises(descriptor.Rejected) as caught: + descriptor.decode(json.dumps(value).encode()) + self.assertEqual(str(caught.exception), reason) + value = fixture(); value['instance'].pop('generation') + endpoint, calls = self.server(value) + with patch.object(discovery, 'listening_endpoints', return_value=[endpoint]): + result = discovery.scan_advertised() + self.assertEqual(result['gateways'], []) + self.assertEqual(result['rejected'], [{'server_url': f'http://127.0.0.1:{endpoint[1]}', + 'reason': 'Pumas advertisement instance is missing required field(s) generation.'}]) + with self.assertRaisesRegex(ValueError, 'missing required field'): + discovery.inspect_advertised(f'http://127.0.0.1:{endpoint[1]}') + + def test_versions_boolean_wrong_shapes_and_oversizing_fail(self): mutations = [ lambda v: v.update(advertisement_schema_version=True), lambda v: v.update(advertisement_schema_version=2), @@ -69,8 +130,8 @@ def test_versions_boolean_wrong_shapes_unknown_fields_and_oversizing_fail(self): lambda v: v['build_info']['schemas'][-1].update(version=True), lambda v: v['build_info'].update(compiled_features=[None]), lambda v: v.update(service_generation=''), - lambda v: v['instance'].update(connection_token='do not expose'), - lambda v: v['instance'].update(capabilities=['x'] * 65), + lambda v: v['instance'].update(capabilities='model.query@1'), + lambda v: v.update(instance=[]), lambda v: v['instance'].update(library_root='x' * 4097), lambda v: v.update(endpoint='http://example.com:8765'), lambda v: v.update(endpoint='http://[::1%lo]:8765'), From e505b88975a913983460e203fb05f84094c8d6b7 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Mon, 2 Nov 2026 22:48:06 -0700 Subject: [PATCH 003/131] test(pumas): require the used capability instead of a fixed count The vision gateway fixture is projected from the Pumas DTOs, which now also advertise decision and multimodal_embedding. Pumas responses grow additively, so the browser flow asserts image_to_text is offered rather than an exact capability count. Co-Authored-By: Claude Opus 5.5 --- tests/browser_pumas_typed.cjs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/tests/browser_pumas_typed.cjs b/tests/browser_pumas_typed.cjs index ba87eab7..6dfa832f 100644 --- a/tests/browser_pumas_typed.cjs +++ b/tests/browser_pumas_typed.cjs @@ -117,7 +117,8 @@ function launch(command,args,options={}){const child=spawn(command,args,options) assert.equal(await evaluate('document.getElementById("caption-proposal-seed").disabled'),true); await click('caption-proposal-capabilities');await until(()=>evaluate('document.getElementById("caption-proposal-capability-metadata").textContent.includes("image_to_text")')); const visionManifest=JSON.parse(await evaluate('document.getElementById("caption-proposal-capability-metadata").textContent')); - assert.equal(visionManifest.capabilities.capabilities.length,7); + // Pumas responses grow additively; require the capability this flow uses, not a fixed count. + assert.ok(visionManifest.capabilities.capabilities.some(d=>d.capability==='image_to_text')); await evaluate('document.getElementById("caption-proposal-form").requestSubmit()'); const visionJob=await until(async()=> (await request('caption-proposals')).jobs.find(j=>j.source.id===visionSource.id && j.status==='completed')); const visionExact=await request('caption-proposals/'+visionJob.id); From d55903f8137b31a9cf4dcca90503d82fdcb2e3f9 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Tue, 10 Nov 2026 14:42:40 -0700 Subject: [PATCH 004/131] docs(plan): definition-first projects plan and milestone 1-2 spec The approved redesign: a project folder holds only definitions, notes and result summaries; what is built from them stays in the database and a local product store. Includes the implementation spec for milestones 1 and 2 and the execution ledger for milestone 1. Co-Authored-By: Claude Fable 5.2 --- .../execution-ledger.md | 36 ++ docs/plans/definition-first-projects/plan.md | 281 +++++++++++++ .../definition-first-projects/spec-m1-m2.md | 381 ++++++++++++++++++ 3 files changed, 698 insertions(+) create mode 100644 docs/plans/definition-first-projects/execution-ledger.md create mode 100644 docs/plans/definition-first-projects/plan.md create mode 100644 docs/plans/definition-first-projects/spec-m1-m2.md diff --git a/docs/plans/definition-first-projects/execution-ledger.md b/docs/plans/definition-first-projects/execution-ledger.md new file mode 100644 index 00000000..b0550683 --- /dev/null +++ b/docs/plans/definition-first-projects/execution-ledger.md @@ -0,0 +1,36 @@ +# Execution ledger: definition-first projects + +## 2026-11-10 — milestone 1, the folder + +**Branch:** `feat/definition-first-projects` from `d8d91fbf`, nothing committed. Lab work on `reorg/reproducible-lab-20261102`, nothing committed. + +**Done by:** three Opus 5.5 agents at medium effort, one per slice, from [spec-m1-m2.md](spec-m1-m2.md); each slice reviewed and re-run by the orchestrating session. + +| Slice | Files | Result | +| --- | --- | --- | +| T1 checker | `tuldok_project/{documents,folder,graph,check,__main__}.py`, `tuldok_project/schemas/*.json`, `tests/test_tuldok_project_check.py`, `tests/fixtures/tuldok_project/minimal/` | 59 tests pass. Independent check: eight hand-broken folders (symbolic link, duplicate key, stray directory, cycle, bad placeholder, unknown field, missing reference, clean) all reported correctly | +| T2 summaries | `tuldok_project/results.py`, `tests/test_tuldok_project_results.py` | 56 tests pass. Independent check: statistics and file round trip recomputed by hand | +| L1 lab folder | `lab:scripts/build_tuldok_project.py`, `lab:scripts/tests/`, `lab:projects/surrogate-lab/` | 21 tests pass; `--check` passes; folder is 12 MB in 486 files; checker reports 0 errors, 8 warnings. Independent check: all 645 ungrouped rows of `results/original-pressure-cases.csv` recomputed from the nine source result sets, none disagree | + +Command for the Tuldok tests: `.venv/bin/python -m unittest discover -s tests -p 'test_tuldok_project_*.py'` (115 tests, 2 s). + +**The lab folder holds** 206 recipes, 32 datasets, 18 benchmarks with summaries (4,589 rows), 4 steps, 2 environments, 1 model, 205 cards. 459 of 477 result subjects are linked to a model; the other 18 are solver assemblies or execution variants. + +**Format changes made during the milestone** (all in the spec): + +- `earlier_work.rebuild` gained `needs-work`: nothing is lost, but the recorded command does not run as written. Labels state a fact about the item alone; Tuldok derives from the graph whether anything upstream blocks a rebuild. +- Earlier items name tracked files, not the staged copies under `runs/`; files the old Tuldok generated for a run are not sources. +- Checker choices accepted as implemented: paths must already be in normal form; a missing field is reported at the field's own pointer; knock-on problems from one broken reference are suppressed; a missing final newline in a results file is a warning. + +**Findings:** + +- Of the 205 earlier models, 177 are labelled `no` and 28 `needs-work`; carried through inputs, 183 and 22. No earlier training command runs as written: all 203 take arguments the old Tuldok supplied. +- 173 earlier recipes name code or run material that is in Git only inside the old project folder's blob store, or not at all: 375 distinct files, 7.8 MB (1.1 MB Python, 1.9 MB JSON, one 4.0 MB zip, 0.8 MB arrays). +- Of the 26 earlier training sets and their recording groups, 13 have an exact command; the rest have none or several. +- Authored content in the old notes that the new folder does not carry: 19 task groups and 26 comparisons between models (`notes/00-models.portfolio.json`). + +**Open for the owner:** whether to bring the earlier runs' code into the lab repository; whether to carry the authored groups and comparisons as notes; commit of both repositories' new files. + +**Lab changes the new-work definitions need** (for milestones 4 and 6): a `--json` option on `surrogate.datasets plan`; the benchmark result in Tuldok's results format; `spectral-composition` cannot run on a fresh clone; no lock file yet for the GPU environment; the reference solver needs Rust, which the format's environments do not describe. + +**Remaining in milestone 1:** slice D1, the format contract under `docs/contracts/`, after the owner has read the folder. diff --git a/docs/plans/definition-first-projects/plan.md b/docs/plans/definition-first-projects/plan.md new file mode 100644 index 00000000..b81d99f1 --- /dev/null +++ b/docs/plans/definition-first-projects/plan.md @@ -0,0 +1,281 @@ +# Plan: Definition-first projects + +**Plan status:** `Approved` by the owner on 2026-11-10, with the decisions recorded under [Decisions](#decisions). Implementation proceeds one milestone at a time from the specifications in this folder. + +**Written:** 2026-11-10, against Tuldok `d8d91fbf`, with the Rheon Surrogate Lab project as the test case. + +## Summary + +A project folder becomes a small set of plain files that say what to build and how. Everything built from them (datasets, weights, raw results, logs, history) stays on the local machine, in Tuldok's database and a local product store. Tuldok builds the dependency graph in its database, rebuilds products from the definitions in order, stores results as rows with summaries computed once, and draws charts from the summaries. + +The test is the lab: a fresh clone of the lab, Tuldok and Rheon opens in seconds, shows the models, recipes and result charts, and lists the ordered steps that regenerate every dataset and model defined in it. + +## Why: what the lab project shows + +The lab's project folder in Git is 682 MB in 55,865 files. What the owner needs from it is about 12 MB (the cards, the recipes and a summary of results), plus dataset and benchmark definitions that do not exist in the project today. + +| In the folder today | Size | Why it is there | +| --- | ---: | --- | +| 31 benchmark result sets | 342.5 MB | Each embeds a copy of its raw source documents (189 MB) so every value can be checked against them; the 478,660 values take 146 MB at about 300 bytes each | +| Note and card records | 77.5 MB | The full text of every revision; the actual text is about 13 MB | +| Python environment listings | 56.2 MB | Every file of the Python install with its checksum, listed twice per record (25,765 files for the GPU install) | +| Run records (460) | 54.8 MB | Complete run documents with their admission proofs | +| Fork, extraction, composition, snapshot and operation records | 44.8 MB | Bookkeeping about the project's own history | +| `project.json` | 34.1 MB | Lists every one of the 53,977 records | +| Graphs, model definitions, recipes, studies, trials | 24.3 MB | Definitions together with every past revision | +| Run observations | 14.3 MB | Exact copies of earlier run documents | +| One record per stored file | 6.9 MB | 51,244 files, mostly one per file of a Python environment | +| Stored model source files | 11.0 MB | Captured copies of each model's source code | +| Cards, recipes and notes as plain files | 15.2 MB | The part the owner asked for | + +These are not accidents. They follow from six properties of the current design: + +1. **The folder is the whole record set, by rule.** "Only the inventory in .tuldok/project.json confers authority" (`project_store.py:3`), every record must be listed, and each commit carries a digest over all of them. There is no way to leave a family or a record out of the folder. +2. **History is stored inside the records.** Every save of a note, model, graph or study appends the complete new revision (`project_files.py:342`, `project_material.py:466`). A fork keeps both the old record and the new one. +3. **Everything is proven byte by byte.** Environments are recorded as per-file checksum lists and re-checked before and after each run. Every stored file needs its own record. Every result value must match a pointer into an embedded source document (`retained_measurements.py:230`). +4. **Nothing derived is stored.** The database holds records as opaque bytes in two tables (`project_working_store.py:37`). Every chart request re-reads and re-checks the whole result-set files; the only aggregate is the maximum per model; there are two fixed chart specifications and a chart cannot be saved. +5. **Runs are chained by hand.** The run queue is first-in, first-out (`runs.py:1909`). A step that uses another step's output names it by exact checksum. There is no dataset defined by a generator, and nothing can say "this is missing, build it". +6. **Two modes that cannot be combined.** GPU environments and live run progress exist only in the older catalog mode; projects use the project-files mode, which has neither. + +## Goals + +Stated by the owner on 2026-11-10: + +- **G1.** The Git folder holds only the minimum needed to rebuild everything: recipes, definitions, the necessary scripts and the high-level benchmark results. It does not hold generated data, or the data the results were calculated from. +- **G2.** Generated data lives only in Tuldok's local storage and can be regenerated. +- **G3.** Tuldok builds the dependency graph in its database and uses it. +- **G4.** Charts are not rebuilt from raw data on each request. +- **G5.** A clean install reproduces: clone, open, rebuild. +- **G6.** New work must be fully reproducible. Earlier lab work that cannot be reproduced is an accepted exception, and not every earlier model needs to be kept. + +## Design + +### 1. Three places + +| Place | Holds | In Git | If it is lost | +| --- | --- | --- | --- | +| Project folder | Definitions, notes and cards, result summaries | Yes | It is the source; Git has it | +| Tuldok database | The imported definitions, the graph, run history, result rows and summaries, the activity log | No | Re-import the folder, then re-run or restore products | +| Product store (a local folder) | Generated files: datasets, weights, raw result files, logs | No | Re-run the steps, or restore from a product archive (section 9) | + +The rule for deciding where something goes: if a person or an agent wrote it, it is a definition and belongs in the folder. If a command produced it, it is a product and stays local. The one deliberate exception is the result summary, which Tuldok writes into the folder so the results travel with the project. + +### 2. Definitions + +A definition is one small JSON file. There are seven kinds: + +| Kind | Says | Produces | +| --- | --- | --- | +| `dataset` | The command that generates or prepares the data, its settings, the splits, and which other datasets or models it is built from | A dataset | +| `model` | The architecture: the code entry point and its configuration | Nothing by itself | +| `recipe` | How to train: the model, the training datasets, the settings and seeds, the environment, the resources | Weights | +| `benchmark` | The cases (a dataset and split), the metrics, the subjects, and how to group the summary | Results | +| `step` | Any other command whose output something else needs, such as building the reference solver | Files | +| `environment` | The Python version, the package versions, the device and how to install it | An installed environment on this machine | +| `chart` | Which benchmark and metric to plot, how to group, which chart form | Nothing; it is drawn from summaries | + +Underneath, `dataset`, `recipe`, `benchmark` and `step` are the same thing: a command, its named inputs and its named outputs. The kinds exist so Tuldok knows where to show each one. + +Two illustrative files for the lab (field names are settled in milestone 1; numbers are placeholders): + +```json +{ + "kind": "dataset", + "title": "Diversity scenes v1", + "command": ["python", "-m", "surrogate.datasets", "generate", "diversity-v1", "--root", "{output}"], + "estimate": ["python", "-m", "surrogate.datasets", "plan", "diversity-v1"], + "inputs": {"solver": "reference-solver"}, + "environment": "lab-cpu", + "splits": {"train": 148, "development": 24, "reserved": 52} +} +``` + +```json +{ + "kind": "recipe", + "title": "Pilot stepper on dense scenes", + "model": "divergence-free-stepper", + "inputs": {"training": "sinusoidal-v1"}, + "command": ["python", "-m", "surrogate.train", "surrogate/configs/pilot-dense-k1.json", "{output}", "--device", "cuda"], + "environment": "cuda-torch", + "resources": {"gpu": 1, "wall_hours": 12, "disk_gb": 5}, + "outputs": {"weights": "model.pt", "log": "log.jsonl"} +} +``` + +Rules: + +- **One file per definition.** The file name is its name, and other definitions refer to it by that name. +- **No checksums of other documents.** A definition never records the checksum of another definition or of a script, so changing one file never forces a change in another. +- **Checked on import.** Each kind has a schema; unknown fields are refused with the file and field named. +- **One set of files for everyone.** Tuldok's screens, an agent and a text editor all edit the same files. + +### 3. The project folder + +``` +tuldok.json project name, id, format version, where the code root is +datasets/*.json +models/*.json +recipes/*.json +benchmarks/*.json +steps/*.json +environments/*.json +charts/*.json +results/*.csv result summaries, written by Tuldok on Save +notes/ cards and notes as plain files +``` + +There is no inventory of records, no `records/` tree, no receipts and no stored-file records. Scripts stay where they are in the repository; definitions name them by path. Git is the history of every file in the folder. + +For the lab, this folder is expected to be about 12 MB: the 205 cards (8.3 MB), the recipes (1.9 MB), the summaries (0.4 MB) and the definitions. + +### 4. The graph + +On import, Tuldok reads each definition's `inputs` and stores the graph in the database: one node per definition, one edge per input. Every node has a state: + +| State | Meaning | +| --- | --- | +| Not built | No product on this machine | +| Built | A product exists and matches the current definition | +| Out of date | A product exists, but the definition, its code or one of its inputs changed since | +| Running, failed | A run is in progress or ended in error | +| Cannot be rebuilt | An earlier lab item whose inputs or command are lost (section 10) | + +The graph is what the lineage map, the rebuild plan and "what does changing this affect" all read. It is not exported; it is rebuilt from the definitions whenever they change. + +"Out of date" is found without chains of checksums. Each product keeps a copy of its definition as it was when built, the Git commit of the code, and which products it consumed. Tuldok compares those with the present state and says what changed. It is information for the owner, never a reason to refuse to run. + +### 5. Products and runs + +**What a product records.** The definition as run, the Git commit, the input products, the package versions actually found, the device, start and end times, the output files with their sizes, and the log. Checksums are computed only for files that never change once written (weights, result files), and for large datasets only when they are archived or checked on request. + +**Runs start from committed code.** Tuldok runs each step from a clean copy of the commit, so a run is tied to a commit and later edits cannot disturb it. A run on uncommitted code is possible but is marked as a scratch run, and its product is never reported as reproducible. + +**Tuldok sets up environments.** On an explicit action Tuldok installs the environment a definition describes (the Python version and the listed package versions), or connects one that already exists on the machine. It never does this on Open. Which interpreter on this machine fulfils an environment is a local setting outside Git. + +**Environments are checked by version.** At the start of a run Tuldok checks that the Python and package versions match the `environment` definition and records what it found, including the GPU and driver. There is no per-file listing and no re-hashing of the install. + +**Limits belong to the definition.** Wall time, disk and GPU come from `resources`, with defaults, in place of fixed constants such as the 30-minute GPU limit and the 64 MiB output cap. Large outputs stay where the step wrote them in the product store; they are not copied. + +**GPU runs and live progress** work for projects: the log tail and the last progress line are available while a run is executing, to the screens and to agents. + +**Plan, then build.** "Plan" lists the steps needed to build a chosen definition, in dependency order, with what is already built and each step's own estimate of disk and time. It runs nothing. "Build" queues those steps on the existing run queue (one GPU slot, several CPU slots). There is one queue and one launcher, as now; the graph only decides the order. + +**Nothing runs on Open.** Opening a project reads files and never executes project code, installs anything or regenerates data. Setting up an environment is its own explicit action. A build needs the owner's approval of the plan. An owner can give an agent a budget (GPU hours, disk) for named definitions. + +### 6. Results and charts + +**What a benchmark writes.** One plain results file: a header (metrics with units, subjects, cases, grouping labels) and one row per value (subject, case, metric, value or the reason it is unavailable). It has no embedded source documents and no pointers. Its provenance is the run that wrote it. + +**What Tuldok stores.** On completion the rows go into a database table, and a summary table is computed once: for each benchmark, subject, metric and declared group, the count, the unavailable count, mean, median, 10th and 90th percentile, minimum and maximum. A benchmark definition can name further statistics. + +**What charts read.** A chart is a saved definition. Tuldok answers it from the summary table with one query. Looking at the individual cases behind a point reads the rows table, also by query. No result file is opened to draw a chart. + +**What goes to Git.** Save writes each benchmark's summary to `results/`, with the commit and date it was produced. For the lab's existing results that is 2,541 rows by model and metric (4,407 with the per-value settings), about 0.4 MB. A benchmark definition can ask for its per-case table to be saved as well; that is off by default. + +**On a fresh clone.** Tuldok imports the summaries, so every chart works at once. Per-case detail shows as not present until the benchmark is rebuilt or its product is restored. + +The first set of chart forms covers the Benchmarks screen of the workspace redesign (accuracy against speed with the best-trade-off line, error across checkpoints, comparison of selected models) and the two existing charts. + +### 7. Notes, history and bookkeeping + +- **Notes and cards** are plain files in `notes/`. Git keeps their history. Tuldok does not store revisions in the folder. +- **Run history and the activity log** (who did what, approvals, admissions) stay in the database. +- **Forks, extractions, compositions, snapshots and operation receipts** are dropped from the project format. A Git branch is a fork. + +### 8. Agent control + +Every operation in this plan is available through the agent interface and the command line, with the same checks as the screens: read and check definitions, read the graph and node states, plan, request a build, watch a run, query results and summaries, and create charts. Because definitions are plain files, an agent with access to the repository can also write them directly and ask Tuldok to check them. + +### 9. Product archive + +Some products cannot be regenerated or are expensive to. A product archive is a folder Tuldok writes on request, containing chosen products with their records, which can be copied to another disk or host and restored into another install. It is the answer to "where do the weights live", and it is never Git. + +### 10. The lab project: conversion and the exception + +A one-time converter, owned by the lab, turns the existing project into the new folder: + +- **Models.** Each of the 205 earlier models becomes a `recipe` with its card and its extracted training recipe, marked as earlier work. Each carries one of three labels: can be rebuilt, can be rebuilt after another model, or cannot be rebuilt with the reason. Today 115 trace only to scenes and formulas and 88 depend on earlier models. +- **Training sets.** The 26 earlier training sets become `dataset` definitions where the command is known. Only 5 have a recorded command, 10 depend on earlier models' weights, and a few have unknown or lost producers; those are recorded as they are and labelled. +- **Results.** The 31 result sets are imported once into the rows table and summarised. +- **Products.** The existing weights and prepared inputs (16 GB, of which most files exist only on the owner's laptop) are registered in the product store where they are, so nothing is recomputed. +- **The old folder** stays on disk, outside Git. + +The owner may drop earlier models that are neither the best of their line nor needed by a later one; the converter takes a list. + +New work under `surrogate/` (dataset definitions, the pilot recipe, the benchmark suites, the reference solver build) is written as definitions from the start and must pass the clean-install test. + +## What changes in Tuldok + +| Area | Today | Under this plan | +| --- | --- | --- | +| Project folder | Record inventory, receipts and record families, 18 of them in the lab's project (`project_store.py`, `project_working_store.py`) | Definition files, notes, summaries | +| Definitions | Graphs, model drafts, materials, recipe materials, each with revisions (`project_material.py`, `pipeline.py`, `recipe_contract.py`) | Seven kinds of plain file, no revisions in the file | +| Environments | Per-file listings, captured copies, re-hashing (`runtime_snapshots.py`, `torch_runtime.py`) | Version check and a record of what was found | +| Runs | Hand-chained, fixed limits, GPU and progress in catalog mode only | Planned from the graph, limits per definition, GPU and progress for projects | +| Queue and launcher | `runs.py`, `run_capacity.py`, `recipe_process.py` | Kept | +| Results | Self-proving documents re-read per request (`retained_measurements.py`, `project_measurements.py`) | Rows and summaries in the database | +| Charts | Two fixed specifications | Saved chart definitions | +| History and bookkeeping | Records in the folder (`project_history.py`, `project_fork.py`, `project_extraction.py`, `project_composition.py`) | Database only, or dropped | +| Access, approvals, agent transport | `access.py`, `agent_api.py`, MCP, CLI | Kept; operations are replaced | +| Catalog mode | The older data workspaces | Not changed by this plan | + +The current project-files code is about 20,900 lines in 38 modules. Its record families refer to each other, so none can be removed alone. The proposal is therefore to build the new project format as a new, small core beside it, reusing the queue, the launcher, the database and the access layer, convert the lab, and then delete the old project-files modules. Tuldok's standing policy since 2026-10-20 already permits breaking format changes with an owner-led one-time migration. + +## Earlier decisions this plan changes + +| Decision | Now | +| --- | --- | +| "The external project directory owns scientific records. PostgreSQL is a disposable projection" (`docs/decisions/external-project-authority.md`) | The folder owns definitions and summaries. The database and product store own what was built. They are a cache that can be rebuilt by running, or restored from a product archive, not something to discard freely | +| "Save writes byte-identical files" and records stored as exact bytes (`docs/plans/database-working-store.md`) | No longer needed: definitions are plain authored files and Tuldok writes one only when it was edited in Tuldok | +| A clone with no database must reopen with identical history (`external-project-save-load/plan.md`) | A clone reopens with identical definitions, notes and summaries. Run history is local | +| "Do not introduce a second graph engine or scheduler" (`generic-scientific-projects/plan.md`) | Still one queue and one launcher. A project-level dependency graph is added, which that plan deferred | +| "No package install" and runtime capture by file listing | Tuldok installs and configures an environment on an explicit owner action, never on Open. The file listings go | +| Out of scope: "saved view persistence", "computed-on-open analyses" (`retained-analysis/plan.md`) | Charts are saved; summaries are computed when results arrive, not on open | + +Kept as they are: the database is the working copy and Save is explicit; Open never executes project code; one run queue; owner approval before anything runs; no per-file source checksum maps. + +## Milestones + +Each milestone ends with a check against the lab. Sizes are relative. + +| # | Milestone | Size | Done when | +| --- | --- | --- | --- | +| 1 | The folder, on paper. Schemas for the seven kinds, and the lab's converter | Small | The converted lab folder exists for the owner to read, is under 20 MB, and every file passes its schema | +| 2 | Open and Save. Tuldok imports the folder into new database tables and builds the graph | Medium | A fresh clone of the lab opens with an empty database in seconds and lists every dataset, model, recipe and benchmark with its links and state | +| 3 | Results and charts. Rows, summaries, saved charts, summaries written on Save | Medium | The lab's 31 result sets import once; per-model maxima equal today's comparison; charts are answered from summaries without opening a result file; a fresh clone draws them from `results/` alone | +| 4 | Plan. The rebuild plan with estimates | Small | Planning the pilot model lists its steps in order with disk estimates and runs nothing | +| 5 | Environments. Tuldok installs or connects an environment from its definition and checks it | Medium | On a machine without the lab's environments, Tuldok sets up the CPU and the GPU environment from their definitions and reports the versions it found. The GPU install is a multi-gigabyte download and needs the owner's go-ahead | +| 6 | Build. Runs from a commit, per-definition limits, GPU, live progress, results published by the run | Large | On a fresh clone Tuldok builds one tiny dataset, trains one tiny model on the GPU with live progress, benchmarks it and charts it. This run needs the owner's go-ahead | +| 7 | Agent operations and command line for all of the above | Medium | An agent repeats milestone 6 through the interface alone | +| 8 | Convert the lab for good, then retire the old code. Product archive, tracked export replaced, old project-files modules removed | Medium | The lab repository holds the new folder only; the clean-install test in the summary passes. Before any old module is deleted, a written check lists every capability of the old project-files mode as covered, moved or deliberately dropped, and the owner signs it off | + +The workspace redesign (the Map variant chosen on 2026-11-03) builds on milestones 2 and 3 and gets its own plan. + +## Out of scope + +- The workspace screens themselves, and how charts are drawn (Vega as now, or plain SVG as in the mockups). +- Annotation data. The same rule applies to it (annotations are authored, so they belong in Git; source media are referenced), but its file layout is a separate plan. +- Retiring catalog mode. +- Sandboxing. Steps remain ordinary local processes with the user's access. +- Hosting for product archives. + +## Decisions + +Decided by the owner on 2026-11-10: + +1. **The new project format is built beside the old one, and the old one is then deleted.** The condition is that we know the old one is no longer needed: milestone 8 does not delete anything until the written capability check is signed off. +2. **Runs require committed code**, with a marked scratch-run escape. +3. **Tuldok installs and configures environments.** This replaces the proposal's "checked, not installed". + +Still open, and needed only before milestone 8: + +4. **Where the product archive for the earlier weights and raw results goes** (an external disk or a host). +5. **Which earlier models to drop**, if any. + +## Risks + +- **Less proof in Git.** A result in Git can no longer be checked against its raw source from the folder alone. Its provenance is the run record in the local database. This is the trade the goals ask for. +- **Local products are single copies.** Losing the machine loses weights and raw results that have no archive. This is already true today for most of the lab's stored files. +- **Size of the change.** It replaces the project-files core over several milestones. Each milestone is usable by itself and is checked on the lab before the next starts. +- **Summaries can lag.** The summaries in Git are as fresh as the last Save. Tuldok shows when results are newer than the saved summaries. diff --git a/docs/plans/definition-first-projects/spec-m1-m2.md b/docs/plans/definition-first-projects/spec-m1-m2.md new file mode 100644 index 00000000..6123f883 --- /dev/null +++ b/docs/plans/definition-first-projects/spec-m1-m2.md @@ -0,0 +1,381 @@ +# Implementation spec: milestones 1 and 2 + +This is the exact specification for milestones 1 and 2 of [the plan](plan.md). The plan says what and why; this file says how. Where the two differ, this file wins for these milestones. Later milestones get their own spec after these are accepted; section 6 records what is already settled for them. + +Paths are relative to the Tuldok repository unless they start with `lab:`, which means the Rheon Surrogate Lab repository (`graphics-3d/rheon-surrogate-lab`). + +## 1. Rules for implementers + +- **New code lives in the package `tuldok_project/`** at the repository root. Milestones 1 and 2 change no existing Tuldok file except `docs/README.md` (one link) and the files a slice names. +- **Do not import from the old project modules** (`project_*.py`, `projects.py`, `retained_measurements.py`, `recipe_contract.py`, `pipeline.py`, `runs.py`). They will be deleted. Where a helper there is useful, copy the few lines into the new package. `metadata.connection_info` is the one allowed import from existing code. +- **Dependencies:** the standard library, `jsonschema` 4.26.0 and `psycopg` 3.3.6, all already in `requirements.txt`. Add nothing. +- **Python:** 3.12, run as `.venv/bin/python`. Module docstrings follow the house style: one summary line, then a short paragraph on what the module owns. +- **Tests:** `unittest`, in `tests/test_tuldok_project_*.py`. Run one file with `.venv/bin/python -m unittest discover -s tests -p 'test_tuldok_project_*.py' -v`. A test file starts with `sys.path.insert(0, str(Path(__file__).resolve().parents[1]))`. +- **Database tests** (milestone 2 only) are skipped unless `TULDOK_DATABASE_URL` is set, and must run against a disposable cluster, never the owner's working database: `python scripts/local_postgres.py init --directory /pg`, then `eval "$(python scripts/local_postgres.py env --directory /pg)"`, and `stop` when finished. +- **Standards:** if the tool `mcp__standards-engine__route` is available, call it with the facts `routing.activities = ["implementation", "verification"]`, `routing.details = ["topic.code-design"]`, every other fact `{"state": "known-absent"}`, and `content = {}`, and follow what it returns. +- **Git:** work in the checked-out branch, do not commit, do not push, do not switch branches. +- **Report:** end with the list of files written, the exact test command run and its result, and anything in this spec that turned out to be wrong or ambiguous. Do not silently work around a spec problem. + +## 2. The project folder format (normative) + +### 2.1 Layout + +``` +tuldok.json +datasets/.json +models/.json +recipes/.json +benchmarks/.json +steps/.json +environments/.json +charts/.json +results/.csv +notes/... +``` + +- The seven definition directories hold only `.json` files, one definition each, no subdirectories. A directory may be absent. +- `` matches `^[a-z0-9][a-z0-9._-]{0,119}$`. +- Top level may also hold `README.md` and `.gitignore`. Any other top-level entry is an error. +- `notes/` holds any plain files in any depth. They are not parsed. +- Every file is a regular file, not a symbolic link. A definition file is at most 1 MiB. `tuldok.json` is at most 64 KiB. A results file is at most 16 MiB. + +### 2.2 JSON rules + +Files are UTF-8 JSON objects. Duplicate keys, `NaN` and `Infinity` are refused. Unknown fields are refused everywhere except inside `settings`, `config` and `labels`, whose contents are free. + +### 2.3 `tuldok.json` + +| Field | Type | Rule | +| --- | --- | --- | +| `format` | string | exactly `tuldok_project_v1` | +| `id` | string | 32 lowercase hex characters | +| `name` | string | 1 to 120 characters | +| `code_root` | string | a relative path from the project folder to the root of the code the commands run in; default `.`; never absolute | + +### 2.4 References + +A reference is the string `/`, for example `datasets/sinusoidal-v1`. It names the definition in `/.json`. Each field that takes a reference states which directories it accepts. + +An **input** is either a reference (the whole product of that definition) or `{"from": , "output": }` (one named output of it). + +### 2.5 Fields common to every definition + +| Field | Required | Type | Rule | +| --- | --- | --- | --- | +| `format` | yes | string | exactly `tuldok_definition_v1` | +| `kind` | yes | string | `dataset`, `model`, `recipe`, `benchmark`, `step`, `environment` or `chart`; must match the directory | +| `title` | yes | string | 1 to 200 characters | +| `description` | no | string | at most 4,000 characters | +| `card` | no | string | a path under `notes/`, relative to the project folder; the file must exist | +| `labels` | no | object | at most 32 entries, string values of at most 400 characters | +| `earlier_work` | no | object | see below; not allowed on `environment` and `chart` | + +`earlier_work` marks an item converted from work done before this format: + +| Field | Required | Rule | +| --- | --- | --- | +| `rebuild` | yes | `yes`, `after-inputs`, `needs-work` or `no` | +| `reason` | when `rebuild` is `no` or `needs-work` | 1 to 1,000 characters | + +The label states a fact about this item alone, never about what it uses: + +- `yes`: its command, code and settings are in Git and the command runs as written under this format. +- `after-inputs`: the same, and one of its inputs is an earlier model's weights. +- `needs-work`: nothing it names is lost, but the recorded command does not run as written under this format. The reason says what has to change. +- `no`: its command, its code or its producer is lost or was never in Git. The reason says which. + +Whether an item can in fact be rebuilt also depends on everything it uses; Tuldok works that out from the graph (section 4.3). + +### 2.6 The `run` block + +`dataset`, `recipe`, `benchmark` and `step` carry a `run` object. It is required unless `earlier_work.rebuild` is `no`. + +| Field | Required | Type | Rule | +| --- | --- | --- | --- | +| `command` | yes | array | 1 to 64 strings; when the first is `python` it means the environment's interpreter | +| `environment` | when the command starts with `python` | reference | `environments/` | +| `inputs` | no | object | at most 32; keys match `^[a-z][a-z0-9_]{0,31}$`; values are inputs from `datasets/`, `recipes/` or `steps/` | +| `settings` | no | object | free content; Tuldok writes it to a file whose path replaces `{settings}` | +| `settings_file` | no | string | a path relative to the code root; excludes `settings` | +| `env` | no | object | at most 32; keys match `^[A-Z_][A-Z0-9_]*$`; string values | +| `outputs` | no | object | keys like input keys; values `{"path": , "role": }` with role `data`, `weights`, `results`, `log`, `report` or `file` | +| `resources` | no | object | any of `gpu` (boolean), `cpu_threads` (integer ≥ 1), `memory_gb`, `wall_hours`, `disk_gb` (numbers > 0) | +| `sources` | no | array | at most 64 paths relative to the code root; a change in them means the code changed | +| `estimate` | no | object | `{"command": [...]}`; the command prints one JSON object with any of `disk_bytes`, `wall_seconds`, `items` | + +**Placeholders** may appear in `command`, in `env` values and in `estimate.command`: + +| Placeholder | Becomes | +| --- | --- | +| `{output}` | the directory the step writes into | +| `{settings}` | the path of the settings file | +| `{inputs.}` | the path of that input; the name must be declared in `inputs` | +| `{subject}` and `{subject.name}` | benchmarks only, see 2.7 | + +Any other `{...}` is an error. `{{` and `}}` are literal braces. `{settings}` requires `settings` or `settings_file`. + +### 2.7 Kind-specific fields + +**`dataset`** + +| Field | Required | Rule | +| --- | --- | --- | +| `run` | per 2.6 | | +| `splits` | no | object, split name to a count of items (integer ≥ 0) | + +**`model`** + +| Field | Required | Rule | +| --- | --- | --- | +| `entry` | no | string, for example `surrogate.models:DivergenceFreeStepper` | +| `config` | no | object, free content; excludes `config_file` | +| `config_file` | no | path relative to the code root | +| `sources` | no | as in 2.6 | + +**`recipe`** + +| Field | Required | Rule | +| --- | --- | --- | +| `run` | per 2.6 | | +| `model` | no | reference to `models/` | + +**`step`**: `run`, required. + +**`benchmark`** + +| Field | Required | Rule | +| --- | --- | --- | +| `run` | per 2.6 | the command runs once per subject; when present, `outputs` must contain exactly one output with role `results` | +| `metrics` | yes | 1 to 64 of `{"id", "title", "units"?, "better"}`; `id` matches `^[a-z][a-z0-9_]{0,63}$` and is unique; `better` is `lower`, `higher` or `none` | +| `subjects` | yes | 0 to 1,000 of `{"name", "title"?, "recipe"?, "argument"?}`; `name` follows the name rule in 2.1 and is unique; `recipe` is a reference to `recipes/`; `argument` is the string that replaces `{subject}` and may contain `{recipe}` (the path of that recipe's product) when `recipe` is given | +| `cases` | no | `{"dataset"?: reference to datasets/, "split"?: string, "count"?: integer ≥ 0}` | +| `summary` | no | `{"group_by"?: up to 8 strings matching the metric id pattern, "statistics"?: a subset of mean, median, p10, p90, min, max}` | + +**`environment`** + +| Field | Required | Rule | +| --- | --- | --- | +| `python` | yes | `3.`, for example `3.12` | +| `device` | yes | `cpu` or `cuda` | +| `packages` | yes | object, 1 to 64 entries, package name to exact version string; these are what a run checks | +| `install` | no | `{"requirements": , "index_urls"?: up to 4 https URLs}` | + +**`chart`** + +| Field | Required | Rule | +| --- | --- | --- | +| `benchmark` | yes | reference to `benchmarks/` | +| `form` | yes | `ranking`, `tradeoff`, `progression` or `comparison` | +| `metric` | yes | a metric id of that benchmark | +| `metric_x` | when `form` is `tradeoff`, otherwise not allowed | a metric id of that benchmark | +| `statistic` | no | one of the six statistics; default `median` | +| `subjects` | no | names of that benchmark's subjects; default all | +| `group` | no | one of that benchmark's `summary.group_by` | + +### 2.8 Results files + +`results/.csv` holds the summary of benchmark `benchmarks/.json`, which must exist. + +- UTF-8, `\n` line ends, RFC 4180 quoting, first line exactly: + `subject,metric,group,count,unavailable,mean,median,p10,p90,min,max,commit,produced` +- `subject` is one of the benchmark's subject names; `metric` one of its metric ids. +- `group` is empty, or `key=value` pairs joined by `;` with keys sorted and each key in the benchmark's `summary.group_by`. A value is written as plain text and may not contain `;`, `=` or a line break. +- `count` and `unavailable` are integers ≥ 0. The six statistics are decimal numbers, all empty when `count` is 0. +- `commit` is 40 lowercase hex characters or empty. `produced` is `YYYY-MM-DD` or `YYYY-MM-DDTHH:MM:SSZ`. +- Rows are unique on (subject, metric, group) and sorted by those three as strings. + +**Statistics.** Over the measured values of one (subject, metric, group): `count` is how many there are; `unavailable` how many values were not measured; `mean` the arithmetic mean; `min` and `max`; `median`, `p10` and `p90` by linear interpolation between closest ranks, position `p × (count − 1)` in the ascending values. Numbers are written with Python's `repr(float)`. + +### 2.9 Checks across files + +1. Every reference names an existing definition in an accepted directory. +2. Every `{"from", "output"}` input names an output the producer declares. +3. The uses-graph has no cycle. Its edges, each from user to used, with a role: + + | From | To | Role | + | --- | --- | --- | + | a `run.inputs` entry | the referenced definition | `input:` | + | `run.environment` | the environment | `environment` | + | `recipe.model` | the model | `model` | + | `benchmark.subjects[].recipe` | the recipe | `subject:` | + | `benchmark.cases.dataset` | the dataset | `cases` | + | `chart.benchmark` | the benchmark | `benchmark` | + +4. Paths relative to the code root (`settings_file`, `config_file`, `sources`, `install.requirements`) are normalised, contain no `..`, and exist under the code root. A missing path is a warning when the definition has `earlier_work`, an error otherwise. This check is skipped when the caller asks not to look at the code. +5. Results files obey 2.8. + +A problem is reported as severity (`error` or `warning`), the file's path relative to the project folder, a JSON pointer to the field (empty for whole-file problems), and one sentence. All problems are collected; the check does not stop at the first. + +## 3. Milestone 1: the folder + +**Done when:** the converted lab folder exists, is under 20 MB, and `python -m tuldok_project check ` reports no errors. + +### Slice T1: documents, folder, graph, check (Tuldok) + +Files to write: + +- `tuldok_project/__init__.py` +- `tuldok_project/schemas/project.schema.json` and one `.schema.json` per kind (JSON Schema 2020-12), expressing every single-file rule of section 2 that JSON Schema can express. +- `tuldok_project/documents.py`: strict JSON decoding (2.2); the name, reference and placeholder rules as functions; loading and caching the schemas. +- `tuldok_project/folder.py`: reading a project folder safely: no symbolic links, regular files only, the size caps of 2.1, the layout rules. Returns each definition with its kind, name, path, bytes, SHA-256, text and decoded document. +- `tuldok_project/graph.py`: pure functions over decoded definitions: `edges(definitions)`, `order(definitions)` (dependencies first, ties broken by reference string), `cycles(definitions)`, `users_of(definitions, reference)`. +- `tuldok_project/check.py`: `check_folder(folder, *, code=True) -> Report`. `Report` has `problems`, `ok` (no errors), and the parsed project (the `tuldok.json` document, the definitions keyed by reference, the edges). It applies sections 2.1 to 2.9 and calls `results.check_results` for each results file. +- `tuldok_project/__main__.py`: `python -m tuldok_project check FOLDER [--no-code] [--json]`. Prints one line per problem (`severity path pointer message`) and a final count; exit status 1 when there is an error, 2 on a usage error. +- `tests/fixtures/tuldok_project/minimal/project/`: a valid folder with at least one definition of every kind, an input chain three deep, one `{"from", "output"}` input, one earlier-work item with `rebuild: no`, one results file and one card. Beside it, `tests/fixtures/tuldok_project/minimal/code/` is a small code tree; the folder's `code_root` is `../code`. +- `tests/test_tuldok_project_check.py`: the fixture passes; and for each rule of section 2 at least one test that copies the fixture to a temporary directory, breaks that one rule, and asserts the problem's path, pointer and severity. + +### Slice T2: result summaries (Tuldok) + +Files to write: + +- `tuldok_project/results.py`: + - `summarise(values) -> dict` implementing the statistics of 2.8 for one list of measured numbers plus an unavailable count. + - `SummaryRow` (the thirteen columns) and `write_results(rows) -> str`, `read_results(text) -> list[SummaryRow]`, which round-trip exactly. + - `check_results(text, benchmark_document) -> list[problem]` applying 2.8. A problem here is `(severity, pointer, message)`, where the pointer is `line `; `check.py` adds the path. +- `tests/test_tuldok_project_results.py`: statistics on hand-computed cases (one value, two values, an even and an odd count, ties, negative values, a count of zero), the round trip, and one failing case per rule of 2.8. + +T1 and T2 can be written at the same time. `tuldok_project/__init__.py` and a skeleton of `tuldok_project/results.py` with these signatures exist before either starts; T2 fills the skeleton in. Until it does, `check_results` raises `NotImplementedError`, so T1 keeps its results-file tests in a class of their own. + +### Slice D1: the format contract (Tuldok) + +`docs/contracts/project-folder.md`: the format for users, taken from section 2 of this spec, with the two examples from the plan corrected to this format; plus a link to it from `docs/README.md` under "Installation, access and storage". Written after T1 and T2 are accepted, so it describes what the checker enforces. + +### Slice L1: the lab's folder (lab repository) + +Output folder: `lab:projects/surrogate-lab/`. It is written by `lab:scripts/build_tuldok_project.py`, which takes `--tuldok ` (to import `tuldok_project`), `--source projects/rheon-model-portfolio-unified-04`, `--output projects/surrogate-lab`, and `--check` (write nothing; fail if the folder differs from what would be written). + +The script owns every file that carries `earlier_work`, every file under `results/` and `notes/`, and `tuldok.json`. It never touches a definition without `earlier_work`; those are written by hand in this slice and kept. + +**Written by hand (new work):** + +| File | Content | +| --- | --- | +| `environments/lab-cpu.json` | Python 3.12, `cpu`, `torch` 2.8.0+cpu, `numpy` 2.3.5; install from `tuldok/requirements-cpu.lock` with index `https://download.pytorch.org/whl/cpu` | +| `environments/cuda-torch.json` | Python 3.14, `cuda`, `torch` 2.14.0+cu132, `numpy` 2.5.3; no `install` yet | +| `steps/reference-solver.json` | the `cargo build` of `probes/reference/` described in `surrogate/README.md` | +| `datasets/sinusoidal-v1.json`, `datasets/diversity-v1.json` | `python -m surrogate.datasets generate --root {output}`, with the solver step as an input and the splits from `surrogate/datasets/definitions/` | +| `models/divergence-free-stepper.json` | the stepper in `surrogate/models/` | +| `recipes/pilot-dense-k1.json` | `python -m surrogate.train` with `surrogate/configs/pilot-dense-k1.json` | +| `benchmarks/.json` | one per suite listed by `python -m surrogate.bench suites`, with the subjects and metrics that `surrogate/bench/` defines | + +Where the lab's command line cannot yet take a placeholder the format needs (for example a results path), write the definition as the format requires and list the lab change needed in the report. Do not change `surrogate/` in this slice. + +**Written by the script (earlier work):** + +| Output | From | Rules | +| --- | --- | --- | +| `recipes/.json`, 205 files | `notes/recipes/.json` and the card | `title` from the model name; `card` is `notes/fits/.md`; `labels` carry `fit_id`, `tuldok_run`, `trained_at`, `device`; `run` from the recorded command, settings, resources and inputs, with each recorded `` turned into `{inputs.x}`; training-data inputs refer to `datasets/`, earlier-weights inputs to `recipes/` | +| `datasets/.json` | `notes/recipes/training-sets.json` (the 26 training sets and the recording groups) | `run` from the recorded or reconstructed command; a recording group that is one of the new datasets refers to it and gets no file of its own | +| `benchmarks/.json` | the 31 result sets, grouped by the part of their title after the first `·` with any `(n subjects)` and `part n` removed | metrics from the result sets; one subject per result-set subject, named by its id in lower case with other characters turned into `-` and its original id and label in `title`; `recipe` set wherever the subject can be matched to a model (by `fit_item_id`, else by weights checksum or checkpoint number through the notes); `summary.group_by` is the per-value dimensions in use | +| `results/.csv` | the same result sets | statistics from `tuldok_project.results.summarise` | +| `notes/fits/*.md` and `notes/*.md` | copied | nothing else is copied from `notes/` | +| `tuldok.json` | fixed | name `Rheon surrogate lab`, a fixed new id, `code_root` `../..` | + +**Code paths.** The earlier runs executed staged copies of their scripts under `runs/`, which is not in Git. For every script and source path of an earlier item, the script looks for a tracked file with identical content (outside the old project folder) and writes that path. Files the old Tuldok generated for a run (for example under `runtime-bootstrap/`) are not sources and are left out. + +**The `earlier_work.rebuild` label** (section 2.5 defines the four values): + +- `no` when the item has no recorded command or no single command line, when its producer is unknown or lost, or when its script or one of its sources has no tracked file. Earlier benchmarks are all `no`, with the reason that they were measured by the earlier study harness. +- `needs-work` when everything it names is in Git but the recorded command cannot run as written. This is the case for the earlier training recipes, whose commands take two arguments that the old Tuldok supplied. +- `after-inputs` and `yes` only when the command line is exact. When the command was reconstructed and not recorded at the time, say so in `description`. + +**The script's report** (printed, and required in the agent's final report): counts of each kind; how many of each `rebuild` label; how many result-set subjects were matched to a model and how many were not, with the unmatched listed; the folder's size; and a list of what the `notes/*.json` files and `notes/checkpoints/` contain that the new folder does not carry, so the owner can decide whether any of it should be kept. + +Tests: `lab:surrogate/tests/` is for the surrogate package; put the script's tests in `lab:scripts/tests/test_build_tuldok_project.py` and run them with the lab's `.venv/bin/python -m unittest`. + +## 4. Milestone 2: open and save + +**Done when:** with an empty database, `python -m tuldok_project open lab:projects/surrogate-lab` completes in under 10 seconds and `list` and `graph` show every definition with its links and state; a second `open` with nothing changed completes in under 1 second. + +### 4.1 Database + +One Postgres schema per project, named `project_`, created on first open with `CREATE SCHEMA IF NOT EXISTS` and `CREATE TABLE IF NOT EXISTS`, under a session advisory lock, on a dedicated autocommit connection from `metadata.connection_info`. Later changes are additive `ALTER TABLE ... ADD COLUMN IF NOT EXISTS`. + +```sql +CREATE TABLE state ( + singleton boolean PRIMARY KEY DEFAULT true CHECK (singleton), + project_id text NOT NULL, name text NOT NULL, + folder text NOT NULL, -- real path of the folder this copy is bound to + code_root text NOT NULL, + imported_at timestamptz NOT NULL); + +CREATE TABLE definitions ( + directory text NOT NULL, name text NOT NULL, + kind text NOT NULL, title text NOT NULL, + text text NOT NULL, -- the exact file content + document jsonb NOT NULL, + file_sha256 text, -- of the file as last imported or saved; NULL if never on disk + unsaved boolean NOT NULL DEFAULT false, + removed boolean NOT NULL DEFAULT false, -- deleted in the database, not yet saved + PRIMARY KEY (directory, name)); + +CREATE TABLE edges ( + from_ref text NOT NULL, to_ref text NOT NULL, role text NOT NULL, + PRIMARY KEY (from_ref, to_ref, role)); +CREATE INDEX edges_to ON edges (to_ref); +``` + +### 4.2 Open + +`store.open_project(folder, *, rebind=False, on_conflict=None) -> Project`: + +1. Read `tuldok.json`; find or create the schema. +2. If `state.folder` exists and is a different real path, refuse with a message naming both paths, unless `rebind` is true. +3. List the definition files with size and SHA-256. If every file matches `definitions.file_sha256` and none was added or removed, attach without checking anything else. +4. Otherwise run `check_folder`. If it has errors, refuse and leave the database unchanged; the error carries the problems. +5. If a changed or removed file has an `unsaved` row, refuse and name those definitions, unless `on_conflict` is `keep` (keep the database's version) or `discard` (take the file). +6. In one transaction: upsert changed definitions, delete rows for removed files, rebuild `edges` from `graph.edges`, update `state`. + +### 4.3 States + +Milestone 2 knows five states. They are computed from the definition and the graph, never stored in a file: + +| State | When | +| --- | --- | +| `cannot-rebuild` | its `earlier_work.rebuild` is `no`, or something it uses through an input, directly or further up, is `cannot-rebuild` | +| `needs-work` | not `cannot-rebuild`, and its `earlier_work.rebuild` is `needs-work` or something it uses through an input is `needs-work` | +| `not-built` | any other dataset, recipe, benchmark or step | +| `not-set-up` | an environment | +| `none` | a model or a chart | + +Only `input:` edges carry these states upward. A benchmark is not made `cannot-rebuild` by one of its subjects. + +### 4.4 Edit and save + +- `project.set_definition(reference, text)` checks the document alone and against the project as it would then be (references, cycles), stores it with `unsaved = true` and updates `edges`. +- `project.remove_definition(reference)` refuses when another definition uses it; otherwise sets `removed = true`. +- `project.save()` writes each unsaved definition to its file (temporary file in the same directory, `fsync`, rename) and deletes the files of removed ones. Before writing a file it checks the file on disk still has `file_sha256`; if any does not, it writes nothing and names them. + +### 4.5 Command line + +`python -m tuldok_project FOLDER`, with `--database-url` or `TULDOK_DATABASE_URL`, and `--json` on every reading command: + +| Command | Does | +| --- | --- | +| `open [--rebind] [--keep | --discard]` | 4.2; prints counts per kind and the time taken | +| `list [--kind K]` | reference, title, state | +| `show REFERENCE` | the definition, what it uses and what uses it | +| `graph [--order]` | nodes with state and edges; `--order` prints build order | +| `status` | unsaved and removed definitions; files changed on disk since import | +| `set REFERENCE FILE`, `remove REFERENCE`, `save` | 4.4 | + +### 4.6 Slices + +| Slice | Files | Tests | +| --- | --- | --- | +| T3 store | `tuldok_project/store.py` (4.1, 4.2, 4.3) | `tests/test_tuldok_project_store.py`, database | +| T4 edit and save | `store.py` additions (4.4) | same file, database | +| T5 commands | `tuldok_project/__main__.py` additions (4.5) | `tests/test_tuldok_project_cli.py` | +| T6 lab check | a timing run of the lab folder, recorded in `execution-ledger.md` | none | + +T3 comes first; T4 and T5 follow it and do not overlap. + +## 5. Not in milestones 1 and 2 + +No change to `app.py`, `agent_api.py`, the browser code or any existing module. No HTTP route, no agent operation, no screen. No products, runs, environments set-up or result rows. The summaries in `results/` are checked but not imported. + +## 6. Already settled for later milestones + +- **Wiring into the app (start of milestone 3).** The new core gets its own start-up flag, its own route prefix and its own agent profile, with operations named `project.*`. `app.py` routes by a mode attribute in about eight places and `agent_api.capabilities` filters by profile; both need a third case. The agent contract fixtures under `tests/fixtures/` are pinned and must be regenerated with that change. +- **Environments (milestone 5).** Tuldok has no installer code today. Set-up will use `uv` (a venv for the definition's Python version, then the pinned requirements with the index URLs), or connect an existing interpreter; the check imports each listed package in a child process and compares versions, as the existing run-start checks do. +- **Running (milestone 6).** The process custodian in `recipe_process.py` (`launch`, `Handle`, the child-reaping helper) can run a plain command with small local changes: limits from the caller, subdirectories allowed in the output, longer streams truncated and not fatal. The queue in `runs.py` cannot be reused: admission, saving and recovery all require the old recipe material and one-use grants. The new core gets a small queue of its own that shares one capacity object (one GPU slot, the CPU and memory budget) with the existing queue while catalog mode exists, and keeps its safety rules: only the custodian's own end-of-children proof counts as stopped, and a restart never replays started work. From 3297f8dd30901dff06ddf0a534a85bbdcc860282 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Tue, 10 Nov 2026 14:42:40 -0700 Subject: [PATCH 005/131] feat(project): check a definition-first project folder Adds the tuldok_project package: strict reading of a project folder, JSON Schema and cross-file checks for the seven definition kinds, the uses-graph, and benchmark result summaries (statistics and results/*.csv files). Command line: python -m tuldok_project check FOLDER. No existing module is changed or imported except jsonschema. Co-Authored-By: Claude Fable 5.2 --- .../minimal/code/configs/stepper.json | 1 + .../minimal/code/configs/train-k1.json | 1 + .../tuldok_project/minimal/code/lab/bench.py | 1 + .../tuldok_project/minimal/code/lab/model.py | 5 + .../tuldok_project/minimal/code/lab/train.py | 1 + .../minimal/code/requirements.txt | 1 + .../minimal/code/tools/build_solver.py | 1 + .../minimal/code/tools/make_waves.py | 1 + .../tuldok_project/minimal/project/README.md | 3 + .../minimal/project/benchmarks/rollout.json | 23 + .../project/charts/rollout-ranking.json | 11 + .../project/charts/speed-accuracy.json | 9 + .../minimal/project/datasets/waves.json | 18 + .../minimal/project/environments/lab-cpu.json | 9 + .../minimal/project/models/stepper.json | 8 + .../minimal/project/notes/decisions.md | 3 + .../minimal/project/notes/fits/early-fit.md | 4 + .../minimal/project/recipes/early-fit.json | 10 + .../minimal/project/recipes/stepper-k1.json | 18 + .../minimal/project/recipes/stepper-k2.json | 17 + .../minimal/project/results/rollout.csv | 10 + .../minimal/project/steps/solver.json | 15 + .../minimal/project/tuldok.json | 6 + tests/test_tuldok_project_check.py | 682 ++++++++++++++++++ tests/test_tuldok_project_results.py | 310 ++++++++ tuldok_project/__init__.py | 6 + tuldok_project/__main__.py | 46 ++ tuldok_project/check.py | 304 ++++++++ tuldok_project/documents.py | 287 ++++++++ tuldok_project/folder.py | 254 +++++++ tuldok_project/graph.py | 177 +++++ tuldok_project/results.py | 282 ++++++++ tuldok_project/schemas/benchmark.schema.json | 451 ++++++++++++ tuldok_project/schemas/chart.schema.json | 140 ++++ tuldok_project/schemas/dataset.schema.json | 340 +++++++++ .../schemas/environment.schema.json | 120 +++ tuldok_project/schemas/model.schema.json | 143 ++++ tuldok_project/schemas/project.schema.json | 34 + tuldok_project/schemas/recipe.schema.json | 338 +++++++++ tuldok_project/schemas/step.schema.json | 333 +++++++++ 40 files changed, 4423 insertions(+) create mode 100644 tests/fixtures/tuldok_project/minimal/code/configs/stepper.json create mode 100644 tests/fixtures/tuldok_project/minimal/code/configs/train-k1.json create mode 100644 tests/fixtures/tuldok_project/minimal/code/lab/bench.py create mode 100644 tests/fixtures/tuldok_project/minimal/code/lab/model.py create mode 100644 tests/fixtures/tuldok_project/minimal/code/lab/train.py create mode 100644 tests/fixtures/tuldok_project/minimal/code/requirements.txt create mode 100644 tests/fixtures/tuldok_project/minimal/code/tools/build_solver.py create mode 100644 tests/fixtures/tuldok_project/minimal/code/tools/make_waves.py create mode 100644 tests/fixtures/tuldok_project/minimal/project/README.md create mode 100644 tests/fixtures/tuldok_project/minimal/project/benchmarks/rollout.json create mode 100644 tests/fixtures/tuldok_project/minimal/project/charts/rollout-ranking.json create mode 100644 tests/fixtures/tuldok_project/minimal/project/charts/speed-accuracy.json create mode 100644 tests/fixtures/tuldok_project/minimal/project/datasets/waves.json create mode 100644 tests/fixtures/tuldok_project/minimal/project/environments/lab-cpu.json create mode 100644 tests/fixtures/tuldok_project/minimal/project/models/stepper.json create mode 100644 tests/fixtures/tuldok_project/minimal/project/notes/decisions.md create mode 100644 tests/fixtures/tuldok_project/minimal/project/notes/fits/early-fit.md create mode 100644 tests/fixtures/tuldok_project/minimal/project/recipes/early-fit.json create mode 100644 tests/fixtures/tuldok_project/minimal/project/recipes/stepper-k1.json create mode 100644 tests/fixtures/tuldok_project/minimal/project/recipes/stepper-k2.json create mode 100644 tests/fixtures/tuldok_project/minimal/project/results/rollout.csv create mode 100644 tests/fixtures/tuldok_project/minimal/project/steps/solver.json create mode 100644 tests/fixtures/tuldok_project/minimal/project/tuldok.json create mode 100644 tests/test_tuldok_project_check.py create mode 100644 tests/test_tuldok_project_results.py create mode 100644 tuldok_project/__init__.py create mode 100644 tuldok_project/__main__.py create mode 100644 tuldok_project/check.py create mode 100644 tuldok_project/documents.py create mode 100644 tuldok_project/folder.py create mode 100644 tuldok_project/graph.py create mode 100644 tuldok_project/results.py create mode 100644 tuldok_project/schemas/benchmark.schema.json create mode 100644 tuldok_project/schemas/chart.schema.json create mode 100644 tuldok_project/schemas/dataset.schema.json create mode 100644 tuldok_project/schemas/environment.schema.json create mode 100644 tuldok_project/schemas/model.schema.json create mode 100644 tuldok_project/schemas/project.schema.json create mode 100644 tuldok_project/schemas/recipe.schema.json create mode 100644 tuldok_project/schemas/step.schema.json diff --git a/tests/fixtures/tuldok_project/minimal/code/configs/stepper.json b/tests/fixtures/tuldok_project/minimal/code/configs/stepper.json new file mode 100644 index 00000000..eec75e7a --- /dev/null +++ b/tests/fixtures/tuldok_project/minimal/code/configs/stepper.json @@ -0,0 +1 @@ +{"width": 32, "depth": 2} diff --git a/tests/fixtures/tuldok_project/minimal/code/configs/train-k1.json b/tests/fixtures/tuldok_project/minimal/code/configs/train-k1.json new file mode 100644 index 00000000..e2c2f3e7 --- /dev/null +++ b/tests/fixtures/tuldok_project/minimal/code/configs/train-k1.json @@ -0,0 +1 @@ +{"epochs": 4, "learning_rate": 0.001, "seed": 1} diff --git a/tests/fixtures/tuldok_project/minimal/code/lab/bench.py b/tests/fixtures/tuldok_project/minimal/code/lab/bench.py new file mode 100644 index 00000000..90dd5ea8 --- /dev/null +++ b/tests/fixtures/tuldok_project/minimal/code/lab/bench.py @@ -0,0 +1 @@ +"""Measure one subject on the cases into --out.""" diff --git a/tests/fixtures/tuldok_project/minimal/code/lab/model.py b/tests/fixtures/tuldok_project/minimal/code/lab/model.py new file mode 100644 index 00000000..3a384cd4 --- /dev/null +++ b/tests/fixtures/tuldok_project/minimal/code/lab/model.py @@ -0,0 +1,5 @@ +"""The stepper model.""" + + +class Stepper: + pass diff --git a/tests/fixtures/tuldok_project/minimal/code/lab/train.py b/tests/fixtures/tuldok_project/minimal/code/lab/train.py new file mode 100644 index 00000000..a39f9c56 --- /dev/null +++ b/tests/fixtures/tuldok_project/minimal/code/lab/train.py @@ -0,0 +1 @@ +"""Train a stepper from --data into --out.""" diff --git a/tests/fixtures/tuldok_project/minimal/code/requirements.txt b/tests/fixtures/tuldok_project/minimal/code/requirements.txt new file mode 100644 index 00000000..d59d856f --- /dev/null +++ b/tests/fixtures/tuldok_project/minimal/code/requirements.txt @@ -0,0 +1 @@ +numpy==2.3.5 diff --git a/tests/fixtures/tuldok_project/minimal/code/tools/build_solver.py b/tests/fixtures/tuldok_project/minimal/code/tools/build_solver.py new file mode 100644 index 00000000..56bc5bc3 --- /dev/null +++ b/tests/fixtures/tuldok_project/minimal/code/tools/build_solver.py @@ -0,0 +1 @@ +"""Build the toy solver into --out.""" diff --git a/tests/fixtures/tuldok_project/minimal/code/tools/make_waves.py b/tests/fixtures/tuldok_project/minimal/code/tools/make_waves.py new file mode 100644 index 00000000..1609fd09 --- /dev/null +++ b/tests/fixtures/tuldok_project/minimal/code/tools/make_waves.py @@ -0,0 +1 @@ +"""Generate wave scenes with the solver into --out.""" diff --git a/tests/fixtures/tuldok_project/minimal/project/README.md b/tests/fixtures/tuldok_project/minimal/project/README.md new file mode 100644 index 00000000..1c412f37 --- /dev/null +++ b/tests/fixtures/tuldok_project/minimal/project/README.md @@ -0,0 +1,3 @@ +# Minimal surrogate project + +A small project folder used by Tuldok's checker tests. Its code is in `../code`. diff --git a/tests/fixtures/tuldok_project/minimal/project/benchmarks/rollout.json b/tests/fixtures/tuldok_project/minimal/project/benchmarks/rollout.json new file mode 100644 index 00000000..959287e2 --- /dev/null +++ b/tests/fixtures/tuldok_project/minimal/project/benchmarks/rollout.json @@ -0,0 +1,23 @@ +{ + "format": "tuldok_definition_v1", + "kind": "benchmark", + "title": "Rollout error", + "run": { + "command": ["python", "lab/bench.py", "--weights", "{subject}", "--name", "{subject.name}", "--cases", "{inputs.cases}", "--out", "{output}"], + "environment": "environments/lab-cpu", + "inputs": {"cases": "datasets/waves"}, + "outputs": {"values": {"path": "values.jsonl", "role": "results"}}, + "sources": ["lab/bench.py"] + }, + "metrics": [ + {"id": "rmse", "title": "Rollout RMSE", "units": "m/s", "better": "lower"}, + {"id": "seconds", "title": "Time per scene", "units": "s", "better": "lower"} + ], + "subjects": [ + {"name": "stepper-k1", "title": "Stepper k1", "recipe": "recipes/stepper-k1", "argument": "{recipe}/model.pt"}, + {"name": "stepper-k2", "title": "Stepper k2", "recipe": "recipes/stepper-k2", "argument": "{recipe}/model.pt"}, + {"name": "early-fit", "title": "Early fit (fit-0042)", "recipe": "recipes/early-fit", "argument": "{recipe}/model.pt"} + ], + "cases": {"dataset": "datasets/waves", "split": "development", "count": 4}, + "summary": {"group_by": ["horizon"], "statistics": ["median", "p10", "p90"]} +} diff --git a/tests/fixtures/tuldok_project/minimal/project/charts/rollout-ranking.json b/tests/fixtures/tuldok_project/minimal/project/charts/rollout-ranking.json new file mode 100644 index 00000000..1a459259 --- /dev/null +++ b/tests/fixtures/tuldok_project/minimal/project/charts/rollout-ranking.json @@ -0,0 +1,11 @@ +{ + "format": "tuldok_definition_v1", + "kind": "chart", + "title": "Rollout error by subject", + "benchmark": "benchmarks/rollout", + "form": "ranking", + "metric": "rmse", + "statistic": "median", + "subjects": ["stepper-k1", "stepper-k2", "early-fit"], + "group": "horizon" +} diff --git a/tests/fixtures/tuldok_project/minimal/project/charts/speed-accuracy.json b/tests/fixtures/tuldok_project/minimal/project/charts/speed-accuracy.json new file mode 100644 index 00000000..0aaaafce --- /dev/null +++ b/tests/fixtures/tuldok_project/minimal/project/charts/speed-accuracy.json @@ -0,0 +1,9 @@ +{ + "format": "tuldok_definition_v1", + "kind": "chart", + "title": "Error against time", + "benchmark": "benchmarks/rollout", + "form": "tradeoff", + "metric": "rmse", + "metric_x": "seconds" +} diff --git a/tests/fixtures/tuldok_project/minimal/project/datasets/waves.json b/tests/fixtures/tuldok_project/minimal/project/datasets/waves.json new file mode 100644 index 00000000..3fe6a839 --- /dev/null +++ b/tests/fixtures/tuldok_project/minimal/project/datasets/waves.json @@ -0,0 +1,18 @@ +{ + "format": "tuldok_definition_v1", + "kind": "dataset", + "title": "Wave scenes", + "description": "Small wave scenes made with the toy solver.", + "labels": {"family": "waves"}, + "run": { + "command": ["python", "tools/make_waves.py", "--solver", "{inputs.solver}", "--settings", "{settings}", "--out", "{output}"], + "environment": "environments/lab-cpu", + "inputs": {"solver": {"from": "steps/solver", "output": "binary"}}, + "settings": {"scenes": 12, "seed": 7, "layout": {"grid": [16, 16]}}, + "env": {"OMP_NUM_THREADS": "2"}, + "outputs": {"scenes": {"path": "scenes", "role": "data"}}, + "sources": ["tools/make_waves.py"], + "estimate": {"command": ["python", "tools/make_waves.py", "--plan", "--settings", "{settings}"]} + }, + "splits": {"train": 8, "development": 4} +} diff --git a/tests/fixtures/tuldok_project/minimal/project/environments/lab-cpu.json b/tests/fixtures/tuldok_project/minimal/project/environments/lab-cpu.json new file mode 100644 index 00000000..195857bd --- /dev/null +++ b/tests/fixtures/tuldok_project/minimal/project/environments/lab-cpu.json @@ -0,0 +1,9 @@ +{ + "format": "tuldok_definition_v1", + "kind": "environment", + "title": "Lab CPU", + "python": "3.12", + "device": "cpu", + "packages": {"numpy": "2.3.5"}, + "install": {"requirements": "requirements.txt", "index_urls": ["https://pypi.org/simple"]} +} diff --git a/tests/fixtures/tuldok_project/minimal/project/models/stepper.json b/tests/fixtures/tuldok_project/minimal/project/models/stepper.json new file mode 100644 index 00000000..3de9ddf1 --- /dev/null +++ b/tests/fixtures/tuldok_project/minimal/project/models/stepper.json @@ -0,0 +1,8 @@ +{ + "format": "tuldok_definition_v1", + "kind": "model", + "title": "Stepper", + "entry": "lab.model:Stepper", + "config_file": "configs/stepper.json", + "sources": ["lab/model.py"] +} diff --git a/tests/fixtures/tuldok_project/minimal/project/notes/decisions.md b/tests/fixtures/tuldok_project/minimal/project/notes/decisions.md new file mode 100644 index 00000000..3699330e --- /dev/null +++ b/tests/fixtures/tuldok_project/minimal/project/notes/decisions.md @@ -0,0 +1,3 @@ +# Decisions + +- Benchmarks group rollout error by horizon. diff --git a/tests/fixtures/tuldok_project/minimal/project/notes/fits/early-fit.md b/tests/fixtures/tuldok_project/minimal/project/notes/fits/early-fit.md new file mode 100644 index 00000000..259409fa --- /dev/null +++ b/tests/fixtures/tuldok_project/minimal/project/notes/fits/early-fit.md @@ -0,0 +1,4 @@ +# Early fit (fit-0042) + +Trained in March 2026 by the earlier study harness. The command and the exact +training data were not recorded; only the weights and the measurements remain. diff --git a/tests/fixtures/tuldok_project/minimal/project/recipes/early-fit.json b/tests/fixtures/tuldok_project/minimal/project/recipes/early-fit.json new file mode 100644 index 00000000..bb92cd60 --- /dev/null +++ b/tests/fixtures/tuldok_project/minimal/project/recipes/early-fit.json @@ -0,0 +1,10 @@ +{ + "format": "tuldok_definition_v1", + "kind": "recipe", + "title": "Early fit (fit-0042)", + "description": "A stepper trained before this format; only its weights and measurements remain.", + "card": "notes/fits/early-fit.md", + "labels": {"fit_id": "fit-0042", "trained_at": "2026-03-14", "device": "cuda"}, + "earlier_work": {"rebuild": "no", "reason": "Trained by the earlier study harness; its command and training data were not recorded."}, + "model": "models/stepper" +} diff --git a/tests/fixtures/tuldok_project/minimal/project/recipes/stepper-k1.json b/tests/fixtures/tuldok_project/minimal/project/recipes/stepper-k1.json new file mode 100644 index 00000000..dec6f995 --- /dev/null +++ b/tests/fixtures/tuldok_project/minimal/project/recipes/stepper-k1.json @@ -0,0 +1,18 @@ +{ + "format": "tuldok_definition_v1", + "kind": "recipe", + "title": "Stepper on wave scenes", + "model": "models/stepper", + "run": { + "command": ["python", "lab/train.py", "--data", "{inputs.training}", "--settings", "{settings}", "--out", "{output}"], + "environment": "environments/lab-cpu", + "inputs": {"training": "datasets/waves"}, + "settings_file": "configs/train-k1.json", + "outputs": { + "weights": {"path": "model.pt", "role": "weights"}, + "log": {"path": "log.jsonl", "role": "log"} + }, + "resources": {"gpu": false, "cpu_threads": 4, "memory_gb": 2, "wall_hours": 0.5, "disk_gb": 0.1}, + "sources": ["lab/train.py", "lab/model.py"] + } +} diff --git a/tests/fixtures/tuldok_project/minimal/project/recipes/stepper-k2.json b/tests/fixtures/tuldok_project/minimal/project/recipes/stepper-k2.json new file mode 100644 index 00000000..1b80683f --- /dev/null +++ b/tests/fixtures/tuldok_project/minimal/project/recipes/stepper-k2.json @@ -0,0 +1,17 @@ +{ + "format": "tuldok_definition_v1", + "kind": "recipe", + "title": "Stepper fine-tuned from k1", + "model": "models/stepper", + "run": { + "command": ["python", "lab/train.py", "--start", "{inputs.start}", "--data", "{inputs.training}", "--settings", "{settings}", "--out", "{output}"], + "environment": "environments/lab-cpu", + "inputs": { + "start": {"from": "recipes/stepper-k1", "output": "weights"}, + "training": "datasets/waves" + }, + "settings": {"epochs": 2, "learning_rate": 0.0005, "seed": 2}, + "outputs": {"weights": {"path": "model.pt", "role": "weights"}}, + "sources": ["lab/train.py", "lab/model.py"] + } +} diff --git a/tests/fixtures/tuldok_project/minimal/project/results/rollout.csv b/tests/fixtures/tuldok_project/minimal/project/results/rollout.csv new file mode 100644 index 00000000..d9210d0c --- /dev/null +++ b/tests/fixtures/tuldok_project/minimal/project/results/rollout.csv @@ -0,0 +1,10 @@ +subject,metric,group,count,unavailable,mean,median,p10,p90,min,max,commit,produced +early-fit,rmse,horizon=1,4,0,0.625,0.625,0.325,0.925,0.25,1.0,0123456789abcdef0123456789abcdef01234567,2026-11-02T10:15:00Z +early-fit,rmse,horizon=8,0,4,,,,,,,0123456789abcdef0123456789abcdef01234567,2026-11-02 +early-fit,seconds,,2,2,2.5,2.5,2.1,2.9,2.0,3.0,0123456789abcdef0123456789abcdef01234567,2026-11-02T10:15:00Z +stepper-k1,rmse,horizon=1,4,0,0.5,0.5,0.325,0.675,0.25,0.75,0123456789abcdef0123456789abcdef01234567,2026-11-02T10:15:00Z +stepper-k1,rmse,horizon=8,4,0,2.0,2.0,1.15,2.85,1.0,3.0,0123456789abcdef0123456789abcdef01234567,2026-11-02T10:15:00Z +stepper-k1,seconds,,4,0,1.75,1.75,1.15,2.35,1.0,2.5,0123456789abcdef0123456789abcdef01234567,2026-11-02T10:15:00Z +stepper-k2,rmse,horizon=1,4,0,0.3125,0.3125,0.1625,0.4625,0.125,0.5,0123456789abcdef0123456789abcdef01234567,2026-11-02T10:15:00Z +stepper-k2,rmse,horizon=8,4,0,1.25,1.25,0.65,1.85,0.5,2.0,0123456789abcdef0123456789abcdef01234567,2026-11-02T10:15:00Z +stepper-k2,seconds,,4,0,1.375,1.375,1.075,1.675,1.0,1.75,0123456789abcdef0123456789abcdef01234567,2026-11-02T10:15:00Z diff --git a/tests/fixtures/tuldok_project/minimal/project/steps/solver.json b/tests/fixtures/tuldok_project/minimal/project/steps/solver.json new file mode 100644 index 00000000..53b72db0 --- /dev/null +++ b/tests/fixtures/tuldok_project/minimal/project/steps/solver.json @@ -0,0 +1,15 @@ +{ + "format": "tuldok_definition_v1", + "kind": "step", + "title": "Build the toy solver", + "run": { + "command": ["python", "tools/build_solver.py", "--out", "{output}"], + "environment": "environments/lab-cpu", + "outputs": { + "binary": {"path": "bin/solver", "role": "file"}, + "log": {"path": "build.log", "role": "log"} + }, + "resources": {"cpu_threads": 2, "wall_hours": 0.1}, + "sources": ["tools/build_solver.py"] + } +} diff --git a/tests/fixtures/tuldok_project/minimal/project/tuldok.json b/tests/fixtures/tuldok_project/minimal/project/tuldok.json new file mode 100644 index 00000000..cf2e440e --- /dev/null +++ b/tests/fixtures/tuldok_project/minimal/project/tuldok.json @@ -0,0 +1,6 @@ +{ + "format": "tuldok_project_v1", + "id": "3f9c2a1b7d4e4f60a8b1c2d3e4f50617", + "name": "Minimal surrogate project", + "code_root": "../code" +} diff --git a/tests/test_tuldok_project_check.py b/tests/test_tuldok_project_check.py new file mode 100644 index 00000000..bdea4c5d --- /dev/null +++ b/tests/test_tuldok_project_check.py @@ -0,0 +1,682 @@ +"""The project folder checker: the fixture passes, and each rule of the format is caught when broken. + +Each rule test copies tests/fixtures/tuldok_project/minimal into a temporary +directory, breaks exactly one rule of section 2 of +docs/plans/definition-first-projects/spec-m1-m2.md, and asserts the reported +path, JSON pointer and severity. Results-file content (2.8) belongs to +tuldok_project.results; the classes that need it call the real function and are +kept apart (ResultsFiles, CommandLineOnFixture). Every other class replaces it +with a stub so that a fault there cannot mask or fake a fault here. +""" +import json +import os +from pathlib import Path +import shutil +import subprocess +import sys +import tempfile +import unittest +from unittest import mock + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) + +from tuldok_project import documents, graph, results # noqa: E402 +from tuldok_project.check import check_folder # noqa: E402 + +REPOSITORY = Path(__file__).resolve().parents[1] +FIXTURE = REPOSITORY / 'tests' / 'fixtures' / 'tuldok_project' / 'minimal' +DELETE = object() + + +def _parts(pointer): + return [part.replace('~1', '/').replace('~0', '~') for part in pointer.split('/')[1:]] + + +def _apply(document, pointer, value): + """Set (or with DELETE remove) the value at pointer; an index equal to a list's length appends.""" + *parents, last = _parts(pointer) + holder = document + for part in parents: + holder = holder[int(part)] if isinstance(holder, list) else holder[part] + if isinstance(holder, list): + index = int(last) + if value is DELETE: + del holder[index] + elif index == len(holder): + holder.append(value) + else: + holder[index] = value + elif value is DELETE: + del holder[last] + else: + holder[last] = value + + +class FixtureCopy(unittest.TestCase): + """A fresh copy of the fixture per test, with helpers to break it.""" + stub_results = True + + def setUp(self): + directory = tempfile.TemporaryDirectory() + self.addCleanup(directory.cleanup) + self.base = Path(directory.name) / 'minimal' + shutil.copytree(FIXTURE, self.base, symlinks=True) + self.project = self.base / 'project' + self.code = self.base / 'code' + if self.stub_results: + patcher = mock.patch.object(results, 'check_results', return_value=[]) + patcher.start() + self.addCleanup(patcher.stop) + + def edit(self, relative, pointer, value): + path = self.project / relative + document = json.loads(path.read_text(encoding='utf-8')) + _apply(document, pointer, value) + path.write_text(json.dumps(document, indent=2) + '\n', encoding='utf-8') + + def write(self, relative, content): + path = self.project / relative + path.parent.mkdir(parents=True, exist_ok=True) + if isinstance(content, bytes): + path.write_bytes(content) + else: + path.write_text(content, encoding='utf-8') + + def assertProblem(self, report, path, pointer, severity='error', *, alone=True): + listing = '\n'.join(f' {p.severity} {p.path} {p.pointer!r} {p.message}' for p in report.problems) or ' (none)' + matches = [p for p in report.problems if (p.path, p.pointer, p.severity) == (path, pointer, severity)] + self.assertTrue(matches, f'expected {severity} at {path} {pointer!r}; got:\n{listing}') + for problem in matches: + self.assertTrue(problem.message.strip(), 'every problem carries a sentence') + self.assertTrue(problem.message.rstrip().endswith('.'), problem.message) + if alone: + self.assertEqual(len(report.problems), 1, f'expected only that problem; got:\n{listing}') + return matches[0] + + def assertClean(self, report): + listing = '\n'.join(f' {p.severity} {p.path} {p.pointer!r} {p.message}' for p in report.problems) + self.assertEqual(report.problems, [], listing) + self.assertTrue(report.ok) + + +# -------------------------------------------------------------- 2.1 layout + +class Layout(FixtureCopy): + def test_fixture_has_no_problems_and_parses_the_project(self): + report = check_folder(self.project) + self.assertClean(report) + self.assertEqual(report.project['code_root'], '../code') + self.assertEqual({d.kind for d in report.definitions.values()}, set(documents.DIRECTORIES)) + self.assertIn(graph.Edge('recipes/stepper-k2', 'recipes/stepper-k1', 'input:start'), report.edges) + waves = report.definitions['datasets/waves'] + self.assertEqual((waves.kind, waves.name, waves.path), ('dataset', 'waves', 'datasets/waves.json')) + self.assertEqual(len(waves.sha256), 64) + self.assertEqual(waves.document['title'], 'Wave scenes') + + def test_unknown_top_level_file(self): + self.write('extra.txt', 'x') + self.assertProblem(check_folder(self.project), 'extra.txt', '') + + def test_unknown_top_level_directory(self): + self.write('scratch/a.txt', 'x') + self.assertProblem(check_folder(self.project), 'scratch', '') + + def test_readme_and_gitignore_are_allowed(self): + self.write('.gitignore', '*.tmp\n') + self.assertClean(check_folder(self.project)) + + def test_definition_directory_may_be_absent(self): + shutil.rmtree(self.project / 'charts') + self.assertClean(check_folder(self.project)) + + def test_definition_directory_holds_only_json(self): + self.write('datasets/notes.txt', 'x') + self.assertProblem(check_folder(self.project), 'datasets/notes.txt', '') + + def test_definition_directory_has_no_subdirectories(self): + self.write('datasets/old/waves.json', '{}') + self.assertProblem(check_folder(self.project), 'datasets/old', '') + + def test_definition_file_name_follows_the_name_rule(self): + shutil.copy(self.project / 'charts/speed-accuracy.json', self.project / 'charts/Speed_Accuracy.json') + self.assertProblem(check_folder(self.project), 'charts/Speed_Accuracy.json', '') + + def test_definition_directory_must_be_a_directory(self): + shutil.rmtree(self.project / 'charts') + self.write('charts', 'x') + self.assertProblem(check_folder(self.project), 'charts', '') + + def test_definition_file_may_not_be_a_symbolic_link(self): + os.symlink('speed-accuracy.json', self.project / 'charts/copy.json') + self.assertProblem(check_folder(self.project), 'charts/copy.json', '') + + def test_definition_directory_may_not_be_a_symbolic_link(self): + shutil.move(self.project / 'charts', self.base / 'charts') + os.symlink(self.base / 'charts', self.project / 'charts') + self.assertProblem(check_folder(self.project), 'charts', '') + + def test_project_file_may_not_be_a_symbolic_link(self): + shutil.move(self.project / 'tuldok.json', self.base / 'tuldok.json') + os.symlink(self.base / 'tuldok.json', self.project / 'tuldok.json') + self.assertProblem(check_folder(self.project), 'tuldok.json', '') + + def test_project_file_is_required(self): + (self.project / 'tuldok.json').unlink() + self.assertProblem(check_folder(self.project), 'tuldok.json', '') + + def test_notes_may_not_hold_symbolic_links(self): + os.symlink('fits/early-fit.md', self.project / 'notes/link.md') + self.assertProblem(check_folder(self.project), 'notes/link.md', '') + + def test_definition_size_cap(self): + path = self.project / 'charts/speed-accuracy.json' + path.write_text(path.read_text() + ' ' * (1024 * 1024), encoding='utf-8') + self.assertProblem(check_folder(self.project), 'charts/speed-accuracy.json', '') + + def test_project_file_size_cap(self): + path = self.project / 'tuldok.json' + path.write_text(path.read_text() + ' ' * (64 * 1024), encoding='utf-8') + self.assertProblem(check_folder(self.project), 'tuldok.json', '') + + def test_results_file_size_cap(self): + with open(self.project / 'results/rollout.csv', 'r+b') as handle: + handle.truncate(16 * 1024 * 1024 + 1) + self.assertProblem(check_folder(self.project), 'results/rollout.csv', '') + + def test_results_directory_holds_only_csv_files_with_valid_names(self): + self.write('results/rollout.txt', 'x') + self.write('results/Rollout.csv', 'x') + report = check_folder(self.project) + self.assertProblem(report, 'results/rollout.txt', '', alone=False) + self.assertProblem(report, 'results/Rollout.csv', '', alone=False) + self.assertEqual(len(report.problems), 2) + + def test_missing_folder_is_reported_not_raised(self): + report = check_folder(self.base / 'nowhere') + self.assertProblem(report, '.', '') + + +# ------------------------------------------------------------ 2.2 JSON rules + +CHART = 'charts/speed-accuracy.json' +CHART_TEXT = ('{"format": "tuldok_definition_v1", "kind": "chart", "title": "T", ' + '"benchmark": "benchmarks/rollout", "form": "tradeoff", "metric": "rmse", "metric_x": "seconds"%s}') + + +class JsonRules(FixtureCopy): + def test_strict_decoding(self): + cases = { + 'duplicate key': CHART_TEXT % ', "title": "again"', + 'NaN': CHART_TEXT % ', "labels": {"a": NaN}', + 'Infinity': CHART_TEXT % ', "labels": {"a": Infinity}', + 'minus Infinity': CHART_TEXT % ', "labels": {"a": -Infinity}', + 'overflowing number': CHART_TEXT % ', "labels": {"a": 1e999}', + 'not an object': '[1, 2]', + 'not JSON': '{"format": ', + 'not UTF-8': b'{"title": "\xff"}', + } + for label, text in cases.items(): + with self.subTest(label): + self.setUp() + self.write(CHART, text) + self.assertProblem(check_folder(self.project), CHART, '') + + def test_valid_raw_text_passes(self): + self.write(CHART, CHART_TEXT % '') + self.assertClean(check_folder(self.project)) + + def test_free_content_in_settings_config_and_labels(self): + self.edit('datasets/waves.json', '/run/settings/Any Key!', {'Nested': [1, None, {'x': True}]}) + self.edit('models/stepper.json', '/config_file', DELETE) + self.edit('models/stepper.json', '/config', {'Width': 32, 'blocks': [{'kind': 'conv'}]}) + self.edit('recipes/early-fit.json', '/labels/Any Key!', 'value') + self.assertClean(check_folder(self.project)) + + +# ---------------------------------- 2.3 to 2.7: one field of one document + +LONG = 'x' * 4001 +# (label, file, pointer to change, new value or DELETE, expected pointer) +DOCUMENT_CASES = [ + # 2.2 unknown fields + ('unknown top-level field', 'datasets/waves.json', '/owner', 'me', '/owner'), + ('unknown nested field', 'datasets/waves.json', '/run/shell', True, '/run/shell'), + # 2.3 tuldok.json + ('project format', 'tuldok.json', '/format', 'tuldok_project_v2', '/format'), + ('project id', 'tuldok.json', '/id', '3F9C2A1B7D4E4F60A8B1C2D3E4F50617', '/id'), + ('project id length', 'tuldok.json', '/id', 'abc', '/id'), + ('project name required', 'tuldok.json', '/name', DELETE, '/name'), + ('project name length', 'tuldok.json', '/name', 'x' * 121, '/name'), + ('project name empty', 'tuldok.json', '/name', '', '/name'), + ('project code root absolute', 'tuldok.json', '/code_root', '/srv/code', '/code_root'), + ('project unknown field', 'tuldok.json', '/owner', 'me', '/owner'), + # 2.5 common fields + ('definition format', 'datasets/waves.json', '/format', 'tuldok_definition_v2', '/format'), + ('kind matches directory', 'models/stepper.json', '/kind', 'dataset', '/kind'), + ('kind is known', 'models/stepper.json', '/kind', 'widget', '/kind'), + ('kind required', 'models/stepper.json', '/kind', DELETE, '/kind'), + ('title required', 'models/stepper.json', '/title', DELETE, '/title'), + ('title empty', 'models/stepper.json', '/title', '', '/title'), + ('title length', 'models/stepper.json', '/title', 'x' * 201, '/title'), + ('description length', 'models/stepper.json', '/description', LONG, '/description'), + ('card exists', 'recipes/early-fit.json', '/card', 'notes/fits/missing.md', '/card'), + ('card under notes', 'recipes/early-fit.json', '/card', 'README.md', '/card'), + ('card path normal', 'recipes/early-fit.json', '/card', 'notes/../README.md', '/card'), + ('labels count', 'recipes/early-fit.json', '/labels', {f'k{i}': 'v' for i in range(33)}, '/labels'), + ('label value type', 'recipes/early-fit.json', '/labels/fit_id', 42, '/labels/fit_id'), + ('label value length', 'recipes/early-fit.json', '/labels/fit_id', 'x' * 401, '/labels/fit_id'), + ('no earlier_work on environment', 'environments/lab-cpu.json', '/earlier_work', {'rebuild': 'yes'}, '/earlier_work'), + ('no earlier_work on chart', CHART, '/earlier_work', {'rebuild': 'yes'}, '/earlier_work'), + ('rebuild no needs reason', 'recipes/early-fit.json', '/earlier_work/reason', DELETE, '/earlier_work/reason'), + ('reason length', 'recipes/early-fit.json', '/earlier_work/reason', 'x' * 1001, '/earlier_work/reason'), + ('rebuild value', 'steps/solver.json', '/earlier_work', {'rebuild': 'maybe'}, '/earlier_work/rebuild'), + ('earlier_work unknown field', 'recipes/early-fit.json', '/earlier_work/when', '2026', '/earlier_work/when'), + # 2.6 the run block + ('run required', 'datasets/waves.json', '/run', DELETE, '/run'), + ('command required', 'datasets/waves.json', '/run/command', DELETE, '/run/command'), + ('command not empty', 'steps/solver.json', '/run/command', [], '/run/command'), + ('command at most 64', 'steps/solver.json', '/run/command', ['cargo'] * 65, '/run/command'), + ('command strings', 'steps/solver.json', '/run/command/1', 3, '/run/command/1'), + ('python needs environment', 'steps/solver.json', '/run/environment', DELETE, '/run/environment'), + ('environment reference directory', 'steps/solver.json', '/run/environment', 'steps/solver', '/run/environment'), + ('input key pattern', 'recipes/stepper-k1.json', '/run/inputs/Training', 'datasets/waves', '/run/inputs/Training'), + ('input count', 'recipes/stepper-k1.json', '/run/inputs', {'training': 'datasets/waves', **{f'i{n}': 'datasets/waves' for n in range(32)}}, '/run/inputs'), + ('input reference directory', 'recipes/stepper-k1.json', '/run/inputs/training', 'models/stepper', '/run/inputs/training'), + ('input object needs output', 'datasets/waves.json', '/run/inputs/solver/output', DELETE, '/run/inputs/solver'), + ('input object unknown field', 'datasets/waves.json', '/run/inputs/solver/as', 'x', '/run/inputs/solver'), + ('settings excludes settings_file', 'recipes/stepper-k1.json', '/run/settings', {}, '/run/settings_file'), + ('settings is an object', 'recipes/stepper-k2.json', '/run/settings', [1], '/run/settings'), + ('env key pattern', 'datasets/waves.json', '/run/env/omp', '1', '/run/env/omp'), + ('env value string', 'datasets/waves.json', '/run/env/OMP_NUM_THREADS', 2, '/run/env/OMP_NUM_THREADS'), + ('env count', 'datasets/waves.json', '/run/env', {f'V{n}': '1' for n in range(33)}, '/run/env'), + ('output key pattern', 'datasets/waves.json', '/run/outputs/Scenes', {'path': 's', 'role': 'data'}, '/run/outputs/Scenes'), + ('output role', 'datasets/waves.json', '/run/outputs/scenes/role', 'dataset', '/run/outputs/scenes/role'), + ('output path required', 'datasets/waves.json', '/run/outputs/scenes/path', DELETE, '/run/outputs/scenes/path'), + ('output path relative', 'datasets/waves.json', '/run/outputs/scenes/path', '/tmp/scenes', '/run/outputs/scenes/path'), + ('output path inside', 'datasets/waves.json', '/run/outputs/scenes/path', '../scenes', '/run/outputs/scenes/path'), + ('resources gpu boolean', 'recipes/stepper-k1.json', '/run/resources/gpu', 1, '/run/resources/gpu'), + ('resources cpu_threads', 'recipes/stepper-k1.json', '/run/resources/cpu_threads', 0, '/run/resources/cpu_threads'), + ('resources memory positive', 'recipes/stepper-k1.json', '/run/resources/memory_gb', 0, '/run/resources/memory_gb'), + ('resources wall positive', 'recipes/stepper-k1.json', '/run/resources/wall_hours', -1, '/run/resources/wall_hours'), + ('resources disk positive', 'recipes/stepper-k1.json', '/run/resources/disk_gb', 0, '/run/resources/disk_gb'), + ('resources unknown', 'recipes/stepper-k1.json', '/run/resources/tpu', 1, '/run/resources/tpu'), + ('sources count', 'recipes/stepper-k1.json', '/run/sources', ['lab/train.py'] * 65, '/run/sources'), + ('estimate unknown field', 'datasets/waves.json', '/run/estimate/shell', True, '/run/estimate/shell'), + ('estimate needs command', 'datasets/waves.json', '/run/estimate/command', DELETE, '/run/estimate/command'), + # 2.6 placeholders + ('unknown placeholder', 'datasets/waves.json', '/run/command/7', '{out}', '/run/command/7'), + ('undeclared input placeholder', 'datasets/waves.json', '/run/command/3', '{inputs.mesher}', '/run/command/3'), + ('settings placeholder needs settings', 'steps/solver.json', '/run/command/3', '{settings}', '/run/command/3'), + ('subject placeholder only in benchmark', 'steps/solver.json', '/run/command/3', '{subject}', '/run/command/3'), + ('subject.name placeholder only in benchmark', 'steps/solver.json', '/run/command/3', '{subject.name}', '/run/command/3'), + ('lone opening brace', 'steps/solver.json', '/run/command/3', '{output', '/run/command/3'), + ('lone closing brace', 'steps/solver.json', '/run/command/3', 'output}', '/run/command/3'), + ('literal braces are fine', 'steps/solver.json', '/run/command/3', '{{output}}/x', None), + ('placeholder in env value', 'datasets/waves.json', '/run/env/OMP_NUM_THREADS', '{threads}', '/run/env/OMP_NUM_THREADS'), + ('placeholder in estimate', 'datasets/waves.json', '/run/estimate/command/1', '{inputs.nope}', '/run/estimate/command/1'), + ('non-python command needs no environment', 'steps/solver.json', '/run/command', ['cargo', 'build', '--target-dir', '{output}'], None), + # 2.7 dataset + ('splits count integer', 'datasets/waves.json', '/splits/train', 1.5, '/splits/train'), + ('splits count not negative', 'datasets/waves.json', '/splits/train', -1, '/splits/train'), + # 2.7 model + ('config excludes config_file', 'models/stepper.json', '/config', {}, '/config_file'), + ('entry is a string', 'models/stepper.json', '/entry', ['lab.model'], '/entry'), + ('model sources count', 'models/stepper.json', '/sources', ['lab/model.py'] * 65, '/sources'), + ('model has no run', 'models/stepper.json', '/run', {'command': ['true']}, '/run'), + # 2.7 recipe + ('recipe model directory', 'recipes/stepper-k1.json', '/model', 'datasets/waves', '/model'), + # 2.7 step + # 2.7 benchmark + ('benchmark needs one results output', 'benchmarks/rollout.json', '/run/outputs/values/role', 'data', '/run/outputs'), + ('benchmark has only one results output', 'benchmarks/rollout.json', '/run/outputs/more', {'path': 'm.jsonl', 'role': 'results'}, '/run/outputs'), + ('benchmark run declares outputs', 'benchmarks/rollout.json', '/run/outputs', DELETE, '/run'), + ('metrics required', 'benchmarks/rollout.json', '/metrics', DELETE, '/metrics'), + ('metrics not empty', 'benchmarks/rollout.json', '/metrics', [], '/metrics'), + ('metric id unique', 'benchmarks/rollout.json', '/metrics/2', {'id': 'rmse', 'title': 'Again', 'better': 'lower'}, '/metrics/2/id'), + ('metric id pattern', 'benchmarks/rollout.json', '/metrics/2', {'id': 'Error', 'title': 'E', 'better': 'lower'}, '/metrics/2/id'), + ('metric better', 'benchmarks/rollout.json', '/metrics/0/better', 'smaller', '/metrics/0/better'), + ('metric title required', 'benchmarks/rollout.json', '/metrics/0/title', DELETE, '/metrics/0/title'), + ('metric unknown field', 'benchmarks/rollout.json', '/metrics/0/scale', 'log', '/metrics/0/scale'), + ('subjects required', 'benchmarks/rollout.json', '/subjects', DELETE, '/subjects'), + ('subject name unique', 'benchmarks/rollout.json', '/subjects/3', {'name': 'stepper-k1'}, '/subjects/3/name'), + ('subject name pattern', 'benchmarks/rollout.json', '/subjects/3', {'name': 'Stepper K3'}, '/subjects/3/name'), + ('subject recipe directory', 'benchmarks/rollout.json', '/subjects/0/recipe', 'models/stepper', '/subjects/0/recipe'), + ('subject argument recipe needs recipe', 'benchmarks/rollout.json', '/subjects/3', {'name': 'baseline', 'argument': '{recipe}/model.pt'}, '/subjects/3/argument'), + ('subject argument only recipe', 'benchmarks/rollout.json', '/subjects/0/argument', '{output}/model.pt', '/subjects/0/argument'), + ('cases dataset directory', 'benchmarks/rollout.json', '/cases/dataset', 'recipes/stepper-k1', '/cases/dataset'), + ('cases count', 'benchmarks/rollout.json', '/cases/count', -1, '/cases/count'), + ('cases unknown field', 'benchmarks/rollout.json', '/cases/seed', 1, '/cases/seed'), + ('summary statistic', 'benchmarks/rollout.json', '/summary/statistics/0', 'average', '/summary/statistics/0'), + ('summary group_by count', 'benchmarks/rollout.json', '/summary/group_by', ['horizon'] + [f'g{n}' for n in range(8)], '/summary/group_by'), + ('summary group_by pattern', 'benchmarks/rollout.json', '/summary/group_by/1', 'Scene', '/summary/group_by/1'), + # 2.7 environment + ('python version form', 'environments/lab-cpu.json', '/python', '3.12.1', '/python'), + ('python version major', 'environments/lab-cpu.json', '/python', '2.7', '/python'), + ('python required', 'environments/lab-cpu.json', '/python', DELETE, '/python'), + ('device', 'environments/lab-cpu.json', '/device', 'gpu', '/device'), + ('packages not empty', 'environments/lab-cpu.json', '/packages', {}, '/packages'), + ('packages count', 'environments/lab-cpu.json', '/packages', {f'p{n}': '1.0' for n in range(65)}, '/packages'), + ('package version exact', 'environments/lab-cpu.json', '/packages/numpy', '>=2.3', '/packages/numpy'), + ('install requirements required', 'environments/lab-cpu.json', '/install/requirements', DELETE, '/install/requirements'), + ('index urls https', 'environments/lab-cpu.json', '/install/index_urls/0', 'http://pypi.org/simple', '/install/index_urls/0'), + ('index urls count', 'environments/lab-cpu.json', '/install/index_urls', ['https://a.example/'] * 5, '/install/index_urls'), + # 2.7 chart + ('tradeoff needs metric_x', CHART, '/metric_x', DELETE, '/metric_x'), + ('metric_x only on tradeoff', 'charts/rollout-ranking.json', '/metric_x', 'seconds', '/metric_x'), + ('chart form', 'charts/rollout-ranking.json', '/form', 'pie', '/form'), + ('chart statistic', 'charts/rollout-ranking.json', '/statistic', 'mode', '/statistic'), + ('chart benchmark directory', 'charts/rollout-ranking.json', '/benchmark', 'datasets/waves', '/benchmark'), + ('chart metric in benchmark', 'charts/rollout-ranking.json', '/metric', 'mae', '/metric'), + ('chart metric_x in benchmark', CHART, '/metric_x', 'joules', '/metric_x'), + ('chart subjects in benchmark', 'charts/rollout-ranking.json', '/subjects/0', 'nobody', '/subjects/0'), + ('chart group in group_by', 'charts/rollout-ranking.json', '/group', 'scene', '/group'), +] + + +class DocumentRules(FixtureCopy): + def test_each_single_document_rule(self): + for label, relative, pointer, value, expected in DOCUMENT_CASES: + with self.subTest(label): + self.setUp() + if relative.startswith('benchmarks/'): + # A broken benchmark also makes its results file unchecked (a + # warning, tested in ResultsFiles); drop the file to isolate the rule. + shutil.rmtree(self.project / 'results') + self.edit(relative, pointer, value) + report = check_folder(self.project) + if expected is None: + self.assertClean(report) + else: + self.assertProblem(report, relative, expected) + + def test_step_run_is_required_and_its_named_outputs_go_with_it(self): + self.edit('steps/solver.json', '/run', DELETE) + report = check_folder(self.project) + self.assertProblem(report, 'steps/solver.json', '/run', alone=False) + self.assertProblem(report, 'datasets/waves.json', '/run/inputs/solver/output', alone=False) + self.assertEqual(len(report.problems), 2) + + def test_chart_is_not_checked_against_a_broken_benchmark(self): + shutil.rmtree(self.project / 'results') + self.edit('benchmarks/rollout.json', '/metrics', DELETE) + self.assertProblem(check_folder(self.project), 'benchmarks/rollout.json', '/metrics') + + def test_needs_work_with_a_reason_passes(self): + for relative in ('datasets/waves.json', 'models/stepper.json', 'recipes/stepper-k1.json', + 'benchmarks/rollout.json', 'steps/solver.json'): + with self.subTest(relative): + self.setUp() + self.edit(relative, '/earlier_work', {'rebuild': 'needs-work', 'reason': 'The command takes an old flag.'}) + self.assertClean(check_folder(self.project)) + + def test_needs_work_needs_a_reason(self): + self.edit('recipes/stepper-k1.json', '/earlier_work', {'rebuild': 'needs-work'}) + self.assertProblem(check_folder(self.project), 'recipes/stepper-k1.json', '/earlier_work/reason') + + def test_needs_work_still_needs_run(self): + self.edit('datasets/waves.json', '/run', DELETE) + self.edit('datasets/waves.json', '/earlier_work', {'rebuild': 'needs-work', 'reason': 'The command takes an old flag.'}) + self.assertProblem(check_folder(self.project), 'datasets/waves.json', '/run') + + def test_unknown_rebuild_value_is_an_error(self): + self.edit('recipes/stepper-k1.json', '/earlier_work', {'rebuild': 'later', 'reason': 'x'}) + self.assertProblem(check_folder(self.project), 'recipes/stepper-k1.json', '/earlier_work/rebuild') + + def test_run_is_required_unless_rebuild_is_no(self): + self.edit('datasets/waves.json', '/run', DELETE) + self.edit('datasets/waves.json', '/earlier_work', {'rebuild': 'after-inputs'}) + self.assertProblem(check_folder(self.project), 'datasets/waves.json', '/run') + self.edit('datasets/waves.json', '/earlier_work', {'rebuild': 'no', 'reason': 'Lost.'}) + self.assertClean(check_folder(self.project)) + + def test_unknown_field_names_the_field(self): + self.edit('datasets/waves.json', '/run/shell', True) + problem = self.assertProblem(check_folder(self.project), 'datasets/waves.json', '/run/shell') + self.assertIn("'shell'", problem.message) + + def test_many_problems_in_many_files_are_all_reported(self): + self.edit('datasets/waves.json', '/title', '') + self.edit('models/stepper.json', '/owner', 'me') + self.write(CHART, '{"broken": ') + report = check_folder(self.project) + self.assertProblem(report, 'datasets/waves.json', '/title', alone=False) + self.assertProblem(report, 'models/stepper.json', '/owner', alone=False) + self.assertProblem(report, CHART, '', alone=False) + self.assertEqual(len(report.problems), 3) + self.assertFalse(report.ok) + + +# ------------------------------------------------------ 2.9 across files + +class CrossFileRules(FixtureCopy): + def test_each_reference_names_an_existing_definition(self): + cases = [ + ('input', 'recipes/stepper-k1.json', '/run/inputs/training', 'datasets/missing', '/run/inputs/training'), + ('input object', 'datasets/waves.json', '/run/inputs/solver/from', 'steps/missing', '/run/inputs/solver/from'), + ('environment', 'steps/solver.json', '/run/environment', 'environments/gpu', '/run/environment'), + ('model', 'recipes/stepper-k1.json', '/model', 'models/missing', '/model'), + ('subject recipe', 'benchmarks/rollout.json', '/subjects/0/recipe', 'recipes/missing', '/subjects/0/recipe'), + ('cases dataset', 'benchmarks/rollout.json', '/cases/dataset', 'datasets/missing', '/cases/dataset'), + ('chart benchmark', CHART, '/benchmark', 'benchmarks/missing', '/benchmark'), + ] + for label, relative, pointer, value, expected in cases: + with self.subTest(label): + self.setUp() + self.edit(relative, pointer, value) + self.assertProblem(check_folder(self.project), relative, expected) + + def test_named_output_must_be_declared_by_producer(self): + self.edit('recipes/stepper-k2.json', '/run/inputs/start/output', 'checkpoint') + self.assertProblem(check_folder(self.project), 'recipes/stepper-k2.json', '/run/inputs/start/output') + + def test_named_output_of_producer_without_run(self): + self.edit('recipes/stepper-k2.json', '/run/inputs/start/from', 'recipes/early-fit') + self.assertProblem(check_folder(self.project), 'recipes/stepper-k2.json', '/run/inputs/start/output') + + def test_cycle_is_reported_on_each_member(self): + self.edit('steps/solver.json', '/run/inputs', {'seed': 'datasets/waves'}) + report = check_folder(self.project) + self.assertProblem(report, 'steps/solver.json', '/run/inputs/seed', alone=False) + self.assertProblem(report, 'datasets/waves.json', '/run/inputs/solver/from', alone=False) + self.assertEqual(len(report.problems), 2) + + def test_definition_using_itself_is_a_cycle(self): + self.edit('datasets/waves.json', '/run/inputs/again', 'datasets/waves') + self.assertProblem(check_folder(self.project), 'datasets/waves.json', '/run/inputs/again') + + +class CodeRootPaths(FixtureCopy): + def test_missing_code_path_is_an_error(self): + cases = [ + ('settings_file', 'recipes/stepper-k1.json', '/run/settings_file', 'configs/missing.json'), + ('run sources', 'recipes/stepper-k1.json', '/run/sources/0', 'lab/missing.py'), + ('config_file', 'models/stepper.json', '/config_file', 'configs/missing.json'), + ('model sources', 'models/stepper.json', '/sources/0', 'lab/missing.py'), + ('install requirements', 'environments/lab-cpu.json', '/install/requirements', 'missing.txt'), + ] + for label, relative, pointer, value in cases: + with self.subTest(label): + self.setUp() + self.edit(relative, pointer, value) + self.assertProblem(check_folder(self.project), relative, pointer) + + def test_missing_code_path_is_a_warning_for_earlier_work(self): + self.edit('models/stepper.json', '/earlier_work', {'rebuild': 'yes'}) + self.edit('models/stepper.json', '/config_file', 'configs/missing.json') + report = check_folder(self.project) + self.assertProblem(report, 'models/stepper.json', '/config_file', 'warning') + self.assertTrue(report.ok) + + def test_code_path_may_not_leave_the_code_root(self): + self.edit('recipes/stepper-k1.json', '/run/sources/0', '../project/tuldok.json') + self.assertProblem(check_folder(self.project), 'recipes/stepper-k1.json', '/run/sources/0') + + def test_code_path_must_be_normalised(self): + for value in ('lab//train.py', './lab/train.py', 'lab/', '/abs/train.py'): + with self.subTest(value): + self.setUp() + self.edit('recipes/stepper-k1.json', '/run/sources/0', value) + self.assertProblem(check_folder(self.project), 'recipes/stepper-k1.json', '/run/sources/0') + + def test_code_path_may_not_escape_through_a_symbolic_link(self): + outside = self.base / 'outside' + outside.mkdir() + (outside / 'secret.py').write_text('x') + os.symlink(outside, self.code / 'escape') + self.edit('recipes/stepper-k1.json', '/run/sources/0', 'escape/secret.py') + self.assertProblem(check_folder(self.project), 'recipes/stepper-k1.json', '/run/sources/0') + + def test_code_root_must_be_a_directory(self): + self.edit('tuldok.json', '/code_root', '../nowhere') + self.assertProblem(check_folder(self.project), 'tuldok.json', '/code_root') + + def test_no_code_skips_lookups_but_not_path_form(self): + self.edit('tuldok.json', '/code_root', '../nowhere') + self.edit('recipes/stepper-k1.json', '/run/settings_file', 'configs/missing.json') + self.assertClean(check_folder(self.project, code=False)) + self.edit('recipes/stepper-k1.json', '/run/sources/0', '../lab/train.py') + self.assertProblem(check_folder(self.project, code=False), 'recipes/stepper-k1.json', '/run/sources/0') + + +# ------------------------------------------------------------ 2.8 results + +class ResultsFiles(FixtureCopy): + """Uses the real results.check_results (slice T2).""" + stub_results = False + + def test_fixture_with_its_results_file_has_no_problems(self): + self.assertClean(check_folder(self.project)) + + def test_problem_in_a_results_row_carries_the_file_path(self): + path = self.project / 'results/rollout.csv' + path.write_text(path.read_text().replace('early-fit,rmse,horizon=1', 'nobody,rmse,horizon=1', 1)) + report = check_folder(self.project) + problem = self.assertProblem(report, 'results/rollout.csv', 'line 2', alone=False) + self.assertIn('nobody', ' '.join(p.message for p in report.problems)) + self.assertTrue(problem.message) + + def test_results_not_checked_against_a_broken_benchmark(self): + self.edit('benchmarks/rollout.json', '/metrics/0/better', 'smaller') + report = check_folder(self.project) + self.assertProblem(report, 'benchmarks/rollout.json', '/metrics/0/better', alone=False) + self.assertProblem(report, 'results/rollout.csv', '', 'warning', alone=False) + self.assertEqual(len(report.problems), 2) + + +class ResultsFileBenchmark(FixtureCopy): + """The results file's benchmark must exist (check.py's rule; no call to check_results).""" + + def test_results_file_needs_its_benchmark(self): + shutil.copy(self.project / 'results/rollout.csv', self.project / 'results/other.csv') + self.assertProblem(check_folder(self.project), 'results/other.csv', '') + + +# ------------------------------------------------------- graph and schemas + +class Graph(unittest.TestCase): + def setUp(self): + with mock.patch.object(results, 'check_results', return_value=[]): + report = check_folder(FIXTURE / 'project') + self.definitions = {reference: d.document for reference, d in report.definitions.items()} + + def test_order_puts_dependencies_first_with_ties_by_reference(self): + built = graph.order(self.definitions) + self.assertEqual(sorted(built), sorted(self.definitions)) + position = {reference: index for index, reference in enumerate(built)} + for edge in graph.edges(self.definitions): + self.assertLess(position[edge.to_ref], position[edge.from_ref], edge) + self.assertEqual(built[:3], ['environments/lab-cpu', 'models/stepper', 'recipes/early-fit']) + + def test_users_of(self): + users = graph.users_of(self.definitions, 'recipes/stepper-k1') + self.assertEqual(users, [graph.Edge('benchmarks/rollout', 'recipes/stepper-k1', 'subject:stepper-k1'), + graph.Edge('recipes/stepper-k2', 'recipes/stepper-k1', 'input:start')]) + + def test_cycles_and_order_refuses_them(self): + self.assertEqual(graph.cycles(self.definitions), []) + self.definitions['steps/solver']['run']['inputs'] = {'seed': 'datasets/waves'} + self.assertEqual(graph.cycles(self.definitions), [('datasets/waves', 'steps/solver')]) + with self.assertRaises(ValueError): + graph.order(self.definitions) + + def test_edges_ignore_malformed_fields(self): + self.assertEqual(graph.edges({'datasets/x': {'kind': 'dataset', 'run': {'inputs': [1], 'environment': 3}}}), []) + + +class Schemas(unittest.TestCase): + def test_schemas_are_valid_and_share_their_definitions(self): + names = ['project'] + list(documents.DIRECTORIES) + shared = {} + for name in names: + documents.validator(name) # checks the schema against the 2020-12 meta-schema + schema = json.loads((REPOSITORY / 'tuldok_project/schemas' / f'{name}.schema.json').read_text()) + self.assertEqual(schema['$schema'], 'https://json-schema.org/draft/2020-12/schema') + for key, value in schema.get('$defs', {}).items(): + with self.subTest(schema=name, definition=key): + self.assertEqual(shared.setdefault(key, value), value, + 'a $defs entry must be the same in every schema that has it') + + +# --------------------------------------------------------- command line + +def _run(*arguments): + environment = dict(os.environ, PYTHONDONTWRITEBYTECODE='1') + return subprocess.run([sys.executable, '-m', 'tuldok_project', *map(str, arguments)], + cwd=REPOSITORY, env=environment, capture_output=True, text=True, timeout=60) + + +class CommandLine(FixtureCopy): + """Runs on a copy without results/, so it does not depend on results.check_results.""" + + def setUp(self): + super().setUp() + shutil.rmtree(self.project / 'results') + + def test_clean_folder_exits_zero(self): + completed = _run('check', self.project) + self.assertEqual(completed.returncode, 0, completed.stdout + completed.stderr) + self.assertIn('0 errors, 0 warnings', completed.stdout) + + def test_broken_folder_exits_one_and_prints_each_problem(self): + self.edit('datasets/waves.json', '/title', '') + completed = _run('check', self.project) + self.assertEqual(completed.returncode, 1, completed.stdout + completed.stderr) + self.assertIn('error datasets/waves.json /title ', completed.stdout) + self.assertIn('1 error, 0 warnings', completed.stdout) + + def test_json_output_parses(self): + self.edit('datasets/waves.json', '/title', '') + completed = _run('check', self.project, '--json') + self.assertEqual(completed.returncode, 1) + report = json.loads(completed.stdout) + self.assertFalse(report['ok']) + self.assertEqual(report['problems'], [{'severity': 'error', 'path': 'datasets/waves.json', + 'pointer': '/title', 'message': report['problems'][0]['message']}]) + + def test_warnings_alone_exit_zero_and_no_code_skips_lookups(self): + self.edit('recipes/stepper-k1.json', '/run/settings_file', 'configs/missing.json') + self.assertEqual(_run('check', self.project).returncode, 1) + self.assertEqual(_run('check', self.project, '--no-code').returncode, 0) + self.edit('models/stepper.json', '/earlier_work', {'rebuild': 'yes'}) + self.edit('models/stepper.json', '/config_file', 'configs/missing.json') + self.edit('recipes/stepper-k1.json', '/run/settings_file', 'configs/train-k1.json') + completed = _run('check', self.project) + self.assertEqual(completed.returncode, 0, completed.stdout) + self.assertIn('warning models/stepper.json /config_file', completed.stdout) + + def test_usage_error_exits_two(self): + self.assertEqual(_run('check').returncode, 2) + self.assertEqual(_run('verify', self.project).returncode, 2) + + +class CommandLineOnFixture(unittest.TestCase): + """The real fixture, results file included: depends on results.check_results (slice T2).""" + + def test_fixture_exits_zero(self): + completed = _run('check', FIXTURE / 'project', '--json') + self.assertEqual(completed.returncode, 0, completed.stdout + completed.stderr) + self.assertEqual(json.loads(completed.stdout)['problems'], []) + + +if __name__ == '__main__': + unittest.main() diff --git a/tests/test_tuldok_project_results.py b/tests/test_tuldok_project_results.py new file mode 100644 index 00000000..b4affca6 --- /dev/null +++ b/tests/test_tuldok_project_results.py @@ -0,0 +1,310 @@ +import sys +import unittest +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) + +from tuldok_project.results import ( # noqa: E402 + COLUMNS, STATISTICS, SummaryRow, check_results, read_results, summarise, write_results, +) + +HEADER = ','.join(COLUMNS) +COMMIT = '0123456789abcdef0123456789abcdef01234567' +BENCHMARK = { + 'kind': 'benchmark', + 'metrics': [{'id': 'rmse', 'title': 'RMSE', 'better': 'lower'}, + {'id': 'step_time', 'title': 'Step time', 'better': 'lower'}], + 'subjects': [{'name': 'baseline'}, {'name': 'stepper-v2'}], + 'summary': {'group_by': ['resolution', 'case_family']}, +} +GOOD_ROW = f'baseline,rmse,,3,0,2.0,2.0,1.2,2.8,1.0,3.0,{COMMIT},2026-11-02' + + +def row(**changes): + """Return one valid SummaryRow with the given fields changed.""" + fields = dict(subject='baseline', metric='rmse', group='', count=3, unavailable=0, + mean=2.0, median=2.0, p10=1.2, p90=2.8, min=1.0, max=3.0, + commit=COMMIT, produced='2026-11-02') + fields.update(changes) + return SummaryRow(**fields) + + +def results_text(*lines): + return '\n'.join((HEADER,) + lines) + '\n' + + +def replace_cell(line, column, value): + cells = line.split(',') + cells[COLUMNS.index(column)] = value + return ','.join(cells) + + +class SummariseTests(unittest.TestCase): + def assertSummary(self, values, expected, unavailable=0): + summary = summarise(values, unavailable) + self.assertEqual(set(summary), {'count', 'unavailable', *STATISTICS}) + for name, value in expected.items(): + self.assertEqual(summary[name], value, name) + + def test_one_value(self): + self.assertSummary([5], dict(count=1, unavailable=0, mean=5.0, median=5.0, + p10=5.0, p90=5.0, min=5.0, max=5.0)) + + def test_two_values(self): + # Positions: median 0.5, p10 0.1, p90 0.9 between 1 and 3. + self.assertSummary([3, 1], dict(count=2, mean=2.0, median=2.0, p10=1.2, p90=2.8, + min=1.0, max=3.0)) + + def test_odd_count(self): + # Ascending 1..5, count - 1 = 4: median at 2, p10 at 0.4, p90 at 3.6. + self.assertSummary([3, 1, 2, 5, 4], dict(count=5, mean=3.0, median=3.0, p10=1.4, + p90=4.6, min=1.0, max=5.0)) + + def test_even_count(self): + # Ascending 1..4, count - 1 = 3: median at 1.5, p10 at 0.3, p90 at 2.7. + self.assertSummary([4, 2, 3, 1], dict(count=4, mean=2.5, median=2.5, p10=1.3, + p90=3.7, min=1.0, max=4.0)) + + def test_positions_on_whole_ranks(self): + # Eleven values 0..10: p10 at exactly 1, p90 at exactly 9. + self.assertSummary(list(range(11)), dict(count=11, mean=5.0, median=5.0, + p10=1.0, p90=9.0)) + + def test_ties(self): + # Ascending 2, 2, 2, 7: median at 1.5 is 2; p90 at 2.7 is 2 + 0.7 * 5. + self.assertSummary([2, 7, 2, 2], dict(count=4, mean=3.25, median=2.0, p10=2.0, + p90=5.5, min=2.0, max=7.0)) + + def test_negative_values(self): + # Ascending -10, -4, -1: p10 at 0.2 is -10 + 0.2 * 6; p90 at 1.8 is -4 + 0.8 * 3. + summary = summarise([-4, -1, -10]) + self.assertEqual((summary['mean'], summary['median'], summary['min'], summary['max']), + (-5.0, -4.0, -10.0, -1.0)) + self.assertAlmostEqual(summary['p10'], -8.8, places=12) + self.assertAlmostEqual(summary['p90'], -1.6, places=12) + + def test_zero_values(self): + self.assertSummary([0, 0, 0], dict(count=3, mean=0.0, median=0.0, p10=0.0, p90=0.0, + min=0.0, max=0.0)) + + def test_zero_count(self): + self.assertSummary([], dict(count=0, unavailable=3, **{name: None for name in STATISTICS}), + unavailable=3) + + def test_rejects_non_finite_values_and_bad_unavailable(self): + with self.assertRaises(ValueError): + summarise([1.0, float('nan')]) + with self.assertRaises(ValueError): + summarise([1.0], unavailable=-1) + + +class RoundTripTests(unittest.TestCase): + def test_rows_round_trip_exactly_and_are_sorted(self): + rows = [ + row(subject='stepper-v2', metric='step_time', mean=0.1 + 0.2, median=1e-05, + p10=-0.0, p90=1.5e+16, min=-3.25, max=123456789.123456789), + row(group='case_family=plume;resolution=64', commit='', produced='2026-11-02T10:30:00Z'), + row(count=0, unavailable=4, **{name: None for name in STATISTICS}), + row(metric='step_time', group='case_family=a "quoted", value'), + ] + text = write_results(rows) + self.assertTrue(text.startswith(HEADER + '\n')) + self.assertNotIn('\r', text) + self.assertIn('"case_family=a ""quoted"", value"', text) + back = read_results(text) + self.assertEqual(back, sorted(rows, key=lambda r: (r.subject, r.metric, r.group))) + self.assertEqual(write_results(back), text) + self.assertEqual(repr(back[-1].mean), repr(0.1 + 0.2)) + + def test_empty_cells_for_missing_statistics(self): + text = write_results([row(count=0, **{name: None for name in STATISTICS})]) + self.assertEqual(text.splitlines()[1], f'baseline,rmse,,0,0,,,,,,,{COMMIT},2026-11-02') + + def test_written_file_passes_the_check(self): + rows = [row(), row(subject='stepper-v2', group='resolution=32')] + self.assertEqual(check_results(write_results(rows), BENCHMARK), []) + + def test_read_rejects_malformed_files(self): + for text in ('', 'subject,metric\n', results_text('baseline,rmse'), + results_text(replace_cell(GOOD_ROW, 'count', 'three')), + results_text(replace_cell(GOOD_ROW, 'mean', 'nan')), + results_text('"baseline,rmse')): + with self.subTest(text=text), self.assertRaises(ValueError): + read_results(text) + + +class CheckResultsTests(unittest.TestCase): + def assertProblem(self, text, severity, pointer, fragment): + problems = check_results(text, BENCHMARK) + matching = [p for p in problems if p[0] == severity and p[1] == pointer and fragment in p[2]] + self.assertTrue(matching, f'no {severity} at {pointer!r} mentioning {fragment!r}: {problems}') + + def assertBadCell(self, column, value, fragment): + self.assertProblem(results_text(GOOD_ROW, replace_cell(GOOD_ROW.replace('baseline', 'stepper-v2'), + column, value)), + 'error', 'line 3', fragment) + + def test_valid_file_has_no_problems(self): + self.assertEqual(check_results(results_text(GOOD_ROW), BENCHMARK), []) + + def test_header_only_file_is_valid(self): + self.assertEqual(check_results(HEADER + '\n', BENCHMARK), []) + + # UTF-8, line ends, quoting, header. + def test_not_utf8(self): + problems = check_results(b'\xff' + results_text(GOOD_ROW).encode(), BENCHMARK) + self.assertEqual(problems, [('error', '', 'The results file is not UTF-8.')]) + + def test_utf8_bytes_are_accepted(self): + self.assertEqual(check_results(results_text(GOOD_ROW).encode('utf-8'), BENCHMARK), []) + + def test_carriage_return_line_ends(self): + self.assertProblem(results_text(GOOD_ROW).replace('\n', '\r\n'), 'error', '', '\\r') + + def test_missing_final_line_end(self): + self.assertProblem(results_text(GOOD_ROW).rstrip('\n'), 'warning', '', 'line end') + + def test_bad_quoting(self): + self.assertProblem(results_text(GOOD_ROW, 'baseline,"rm"se,,0,0,,,,,,,,2026-11-02'), + 'error', 'line 3', 'RFC 4180') + + def test_empty_file(self): + self.assertProblem('', 'error', '', 'empty') + + def test_wrong_header(self): + self.assertProblem(results_text(GOOD_ROW).replace('p10,p90', 'p90,p10'), + 'error', 'line 1', 'first line') + + def test_quoted_header_is_not_exact(self): + text = '"subject"' + results_text(GOOD_ROW)[len('subject'):] + self.assertProblem(text, 'error', 'line 1', 'first line') + + def test_wrong_cell_count(self): + self.assertProblem(results_text(GOOD_ROW + ',extra'), 'error', 'line 2', 'cells') + + def test_empty_line(self): + self.assertProblem(results_text(GOOD_ROW, '', GOOD_ROW.replace('baseline', 'stepper-v2')), + 'error', 'line 3', 'Empty lines') + + # Subject and metric. + def test_unknown_subject(self): + self.assertBadCell('subject', 'nobody', 'subject') + + def test_unknown_metric(self): + self.assertBadCell('metric', 'accuracy', 'metric') + + # Group. + def test_group_key_not_in_group_by(self): + self.assertBadCell('group', 'seed=1', 'summary.group_by') + + def test_group_keys_unsorted(self): + self.assertBadCell('group', 'resolution=64;case_family=plume', 'sorted') + + def test_group_key_repeated(self): + self.assertBadCell('group', 'resolution=32;resolution=64', 'repeat') + + def test_group_pair_without_equals(self): + self.assertBadCell('group', 'resolution', 'key=value') + + def test_group_value_with_equals(self): + self.assertBadCell('group', 'resolution=6=4', 'key=value') + + def test_group_value_with_line_break(self): + line = replace_cell(GOOD_ROW, 'group', '"resolution=6\n4"') + self.assertProblem(results_text(line), 'error', 'line 2', 'line break') + + def test_group_without_group_by_in_benchmark(self): + benchmark = dict(BENCHMARK, summary={}) + problems = check_results(results_text(replace_cell(GOOD_ROW, 'group', 'resolution=64')), benchmark) + self.assertEqual([(p[0], p[1]) for p in problems], [('error', 'line 2')]) + + # Count, unavailable and statistics. + def test_count_not_an_integer(self): + self.assertBadCell('count', '2.5', 'count') + + def test_count_negative(self): + self.assertBadCell('count', '-1', 'count') + + def test_unavailable_not_an_integer(self): + self.assertBadCell('unavailable', 'none', 'unavailable') + + def test_statistic_not_a_decimal_number(self): + self.assertBadCell('median', 'nan', 'median') + + def test_statistic_infinite(self): + self.assertBadCell('max', 'inf', 'max') + + def test_statistics_filled_when_count_is_zero(self): + self.assertBadCell('count', '0', 'empty when count is 0') + + def test_statistics_missing_when_count_above_zero(self): + self.assertBadCell('p90', '', 'missing') + + def test_statistics_outside_summary_statistics_may_be_empty(self): + benchmark = dict(BENCHMARK, summary={'statistics': ['median']}) + line = f'baseline,rmse,,3,0,,2.0,,,,,{COMMIT},2026-11-02' + self.assertEqual(check_results(results_text(line), benchmark), []) + + def test_zero_count_with_empty_statistics_is_valid(self): + line = 'baseline,rmse,,0,5,,,,,,,,2026-11-02' + self.assertEqual(check_results(results_text(line), BENCHMARK), []) + + # Commit and produced. + def test_commit_uppercase(self): + self.assertBadCell('commit', COMMIT.upper(), 'commit') + + def test_commit_short(self): + self.assertBadCell('commit', COMMIT[:7], 'commit') + + def test_produced_wrong_form(self): + self.assertBadCell('produced', '2026-11-02 10:30', 'produced') + + def test_produced_not_a_real_date(self): + self.assertBadCell('produced', '2026-02-30', 'produced') + + def test_produced_empty(self): + self.assertBadCell('produced', '', 'produced') + + def test_produced_with_time(self): + line = replace_cell(GOOD_ROW, 'produced', '2026-11-02T23:59:59Z') + self.assertEqual(check_results(results_text(line), BENCHMARK), []) + + # Uniqueness and order. + def test_duplicate_row(self): + self.assertProblem(results_text(GOOD_ROW, GOOD_ROW), 'error', 'line 3', 'repeats') + + def test_rows_out_of_order(self): + later = GOOD_ROW.replace('baseline', 'stepper-v2') + self.assertProblem(results_text(later, GOOD_ROW), 'error', 'line 3', 'out of order') + + def test_order_is_by_group_as_string(self): + first = replace_cell(GOOD_ROW, 'group', 'resolution=128') + second = replace_cell(GOOD_ROW, 'group', 'resolution=64') + self.assertEqual(check_results(results_text(first, second), BENCHMARK), []) + self.assertProblem(results_text(second, first), 'error', 'line 3', 'out of order') + + # Collecting and robustness. + def test_collects_every_problem(self): + line = 'nobody,accuracy,seed=1,x,-1,,,,,,,ABC,yesterday' + problems = check_results(results_text(line), BENCHMARK) + self.assertGreaterEqual(len(problems), 7) + self.assertTrue(all(p[:2] == ('error', 'line 2') for p in problems)) + + def test_line_numbers_follow_physical_lines(self): + quoted = replace_cell(GOOD_ROW, 'group', '"resolution=6\n4"') + bad = replace_cell(GOOD_ROW.replace('baseline', 'stepper-v2'), 'metric', 'accuracy') + self.assertProblem(results_text(quoted, bad), 'error', 'line 4', 'metric') + + def test_never_raises_on_bad_input(self): + for text, benchmark in ((None, BENCHMARK), (results_text(GOOD_ROW), None), + (results_text(GOOD_ROW), {'subjects': 'x', 'metrics': [1], + 'summary': {'group_by': 5}}), + ('\x00,"', BENCHMARK)): + with self.subTest(text=text, benchmark=benchmark): + problems = check_results(text, benchmark) + self.assertTrue(problems) + self.assertTrue(all(p[0] in ('error', 'warning') for p in problems)) + + +if __name__ == '__main__': + unittest.main() diff --git a/tuldok_project/__init__.py b/tuldok_project/__init__.py new file mode 100644 index 00000000..8744bb7b --- /dev/null +++ b/tuldok_project/__init__.py @@ -0,0 +1,6 @@ +"""Definition-first projects: a folder of small definition files and what Tuldok builds from them. + +This package owns the project folder format (docs/plans/definition-first-projects/), +its checker, and the database copy of an opened project. It does not import the +older project-files modules, which it replaces. +""" diff --git a/tuldok_project/__main__.py b/tuldok_project/__main__.py new file mode 100644 index 00000000..4444f085 --- /dev/null +++ b/tuldok_project/__main__.py @@ -0,0 +1,46 @@ +"""Command line for project folders: `python -m tuldok_project check FOLDER [--no-code] [--json]`. + +Owns the command-line surface of the package: parsing arguments, printing a +check report as text lines or JSON, and the exit status (0 no errors, 1 errors, +2 usage error). The checking itself is check.check_folder. +""" +import argparse +import json +import sys + +from .check import check_folder + + +def _parser(): + parser = argparse.ArgumentParser(prog='python -m tuldok_project', + description='Work with a Tuldok project folder.') + commands = parser.add_subparsers(dest='command', required=True) + check = commands.add_parser('check', help='check a project folder against the format') + check.add_argument('folder', help='the project folder (the one holding tuldok.json)') + check.add_argument('--no-code', action='store_true', help='do not look up paths in the code root') + check.add_argument('--json', action='store_true', help='print the report as one JSON object') + return parser + + +def _plural(count, word): + return f'{count} {word}' + ('' if count == 1 else 's') + + +def main(argv=None): + arguments = _parser().parse_args(argv) # exits with status 2 on a usage error + report = check_folder(arguments.folder, code=not arguments.no_code) + errors, warnings = report.count('error'), report.count('warning') + if arguments.json: + json.dump({'folder': report.folder, 'ok': report.ok, 'errors': errors, 'warnings': warnings, + 'problems': [problem.as_dict() for problem in report.problems]}, + sys.stdout, indent=2, ensure_ascii=False) + sys.stdout.write('\n') + else: + for problem in report.problems: + print(f'{problem.severity} {problem.path} {problem.pointer or "-"} {problem.message}') + print(f'{_plural(errors, "error")}, {_plural(warnings, "warning")} in {report.folder}') + return 0 if report.ok else 1 + + +if __name__ == '__main__': + sys.exit(main()) diff --git a/tuldok_project/check.py b/tuldok_project/check.py new file mode 100644 index 00000000..2d91a5e4 --- /dev/null +++ b/tuldok_project/check.py @@ -0,0 +1,304 @@ +"""The project folder checker: every rule of the format, applied to one folder, every problem reported. + +Owns the order in which sections 2.1 to 2.9 of +docs/plans/definition-first-projects/spec-m1-m2.md are applied and the rules +that are neither layout (folder.py), single-field syntax (documents.py and the +schemas) nor summary-file content (results.py): kind against directory, cards, +placeholders in context, benchmark uniqueness rules, references and named +outputs, charts against their benchmark, cycles, and paths into the code root. +Problems are collected, never raised, so one bad file never hides another. +""" +from dataclasses import dataclass, field +import os + +from . import documents, folder as folder_reader, graph, results +from .documents import Problem + +_SEVERITY_ORDER = {'error': 0, 'warning': 1} + + +@dataclass +class Report: + """The outcome of check_folder. + + project is the decoded tuldok.json (or None), definitions maps each + reference to its folder.Definition, edges is graph.edges() over them. + """ + folder: str + problems: list = field(default_factory=list) + project: dict | None = None + definitions: dict = field(default_factory=dict) + edges: list = field(default_factory=list) + + @property + def ok(self): + return not any(problem.severity == 'error' for problem in self.problems) + + def count(self, severity): + return sum(1 for problem in self.problems if problem.severity == severity) + + +def check_folder(folder, *, code=True): + """Check the project folder at `folder`; with code=False, paths into the code root are not looked up.""" + read = folder_reader.read_folder(folder) + problems = list(read.problems) + + def add(severity, path, pointer, message): + problems.append(Problem(severity, path, pointer, message)) + + project = read.project.document if read.project is not None else None + if project is not None: + for pointer, message in documents.schema_problems('project', project): + add('error', folder_reader.PROJECT_FILE, pointer, message) + + definitions = {definition.reference: definition for definition in read.definitions} + for definition in read.definitions: + if definition.document is not None: + _check_definition(definition, read.notes, add) + + # Single-file errors so far decide which benchmarks are sound enough to check results against. + unsound = {problem.path for problem in problems if problem.severity == 'error'} + + code_root = _code_root(project, read.root, add) if code and project is not None else None + for definition in read.definitions: + if definition.document is not None: + _check_code_paths(definition, code_root, add) + + _check_references(definitions, add) + _check_charts(definitions, unsound, add) + _check_cycles(definitions, add) + _check_results(read.results, definitions, unsound, add) + + problems.sort(key=lambda p: (p.path, p.pointer, _SEVERITY_ORDER.get(p.severity, 2), p.message)) + decoded = {reference: d.document for reference, d in definitions.items() if d.document is not None} + return Report(read.root, problems, project, definitions, graph.edges(decoded)) + + +# ------------------------------------------------------- one definition + +def _check_definition(definition, notes, add): + document, path = definition.document, definition.path + for pointer, message in documents.schema_problems(definition.kind, document): + add('error', path, pointer, message) + + kind = document.get('kind') + if kind in documents.DIRECTORIES and kind != definition.kind: + add('error', path, '/kind', + f'The kind is {kind!r} but the file is in {definition.directory}/; ' + f'move it to {documents.DIRECTORIES[kind]}/ or change kind to {definition.kind!r}.') + + card = document.get('card') + if isinstance(card, str) and card.startswith('notes/'): + wrong = documents.relative_path_problem(card) + if wrong: + add('error', path, '/card', f'The card path {card!r} {wrong}.') + elif card not in notes: + add('error', path, '/card', f'The card {card} does not exist; add the file or fix the path.') + + run = document.get('run') + if isinstance(run, dict): + _check_run(run, path, benchmark=definition.kind == 'benchmark', add=add) + if definition.kind == 'benchmark': + _check_benchmark(document, path, add) + + +def _check_run(run, path, *, benchmark, add): + inputs = set(run['inputs']) if isinstance(run.get('inputs'), dict) else set() + context = {'inputs': inputs, 'has_settings': 'settings' in run or 'settings_file' in run, 'benchmark': benchmark} + texts = [] + if isinstance(run.get('command'), list): + texts += [(documents.pointer('run', 'command', i), value) for i, value in enumerate(run['command'])] + if isinstance(run.get('env'), dict): + texts += [(documents.pointer('run', 'env', key), value) for key, value in run['env'].items()] + estimate = run.get('estimate') + if isinstance(estimate, dict) and isinstance(estimate.get('command'), list): + texts += [(documents.pointer('run', 'estimate', 'command', i), value) for i, value in enumerate(estimate['command'])] + for pointer, value in texts: + if isinstance(value, str): + for message in documents.command_placeholder_problems(value, **context): + add('error', path, pointer, message) + + outputs = run.get('outputs') + if isinstance(outputs, dict): + for key, output in outputs.items(): + if isinstance(output, dict) and isinstance(output.get('path'), str): + wrong = documents.relative_path_problem(output['path']) + if wrong: + add('error', path, documents.pointer('run', 'outputs', key, 'path'), + f'The output path {output["path"]!r} {wrong}.') + + +def _first_repeats(items, key): + """Yield (index, value) for each item whose key value already appeared earlier in the list.""" + seen = set() + for index, item in enumerate(items): + value = item.get(key) if isinstance(item, dict) else None + if isinstance(value, str): + if value in seen: + yield index, value + seen.add(value) + + +def _check_benchmark(document, path, add): + metrics = document.get('metrics') + if isinstance(metrics, list): + for index, value in _first_repeats(metrics, 'id'): + add('error', path, documents.pointer('metrics', index, 'id'), + f'The metric id {value!r} is used more than once; give each metric its own id.') + subjects = document.get('subjects') + if isinstance(subjects, list): + for index, value in _first_repeats(subjects, 'name'): + add('error', path, documents.pointer('subjects', index, 'name'), + f'The subject name {value!r} is used more than once; give each subject its own name.') + for index, subject in enumerate(subjects): + if isinstance(subject, dict) and isinstance(subject.get('argument'), str): + for message in documents.argument_placeholder_problems(subject['argument'], has_recipe='recipe' in subject): + add('error', path, documents.pointer('subjects', index, 'argument'), message) + run = document.get('run') + if isinstance(run, dict): + outputs = run.get('outputs') + roles = [o.get('role') for o in outputs.values() if isinstance(o, dict)] if isinstance(outputs, dict) else [] + if roles.count('results') != 1: + add('error', path, '/run/outputs' if 'outputs' in run else '/run', + f'A benchmark run must declare exactly one output with role "results"; it declares {roles.count("results")}.') + + +# --------------------------------------------------------- code root (2.9.4) + +def _code_root(project, root, add): + """Return the real path of the code root, or None (with a problem) when it cannot be used.""" + value = project.get('code_root', '.') + if not isinstance(value, str) or not value or value.startswith('/') or '\x00' in value: + return None # the schema has reported it + resolved = os.path.realpath(os.path.join(root, value)) + if not os.path.isdir(resolved): + add('error', folder_reader.PROJECT_FILE, '/code_root' if 'code_root' in project else '', + f'The code root {value!r} is not a directory next to this folder; fix code_root or use --no-code.') + return None + return resolved + + +def _code_paths(document): + """Yield (pointer, value) for every path relative to the code root in a document.""" + def sources(holder, *prefix): + if isinstance(holder.get('sources'), list): + for index, value in enumerate(holder['sources']): + yield documents.pointer(*prefix, 'sources', index), value + + run = document.get('run') + if isinstance(run, dict): + if 'settings_file' in run: + yield '/run/settings_file', run['settings_file'] + yield from sources(run, 'run') + if 'config_file' in document: + yield '/config_file', document['config_file'] + yield from sources(document) + install = document.get('install') + if isinstance(install, dict) and 'requirements' in install: + yield '/install/requirements', install['requirements'] + + +def _check_code_paths(definition, code_root, add): + document, path = definition.document, definition.path + missing = 'warning' if 'earlier_work' in document else 'error' + for pointer, value in _code_paths(document): + if not isinstance(value, str): + continue + wrong = documents.relative_path_problem(value) + if wrong: + add('error', path, pointer, f'The path {value!r} {wrong}.') + continue + if code_root is None: + continue + resolved = os.path.realpath(os.path.join(code_root, value)) + if resolved != code_root and not resolved.startswith(code_root + os.sep): + add('error', path, pointer, f'The path {value!r} leads outside the code root through a symbolic link; point at a file inside it.') + elif not os.path.exists(resolved): + add(missing, path, pointer, f'The path {value!r} does not exist under the code root; fix the path or add the file.') + + +# ----------------------------------------------------------- across files + +def _check_references(definitions, add): + for definition in definitions.values(): + for use in graph.uses(definition.document): + if not graph.is_wellformed(use): + continue # malformed or in the wrong directory: the schema has reported it + target = definitions.get(use.target) + if target is None: + add('error', definition.path, use.pointer, + f'{use.target} does not exist; add {use.target}.json or fix the reference.') + continue + if use.output is None or target.document is None: + continue + run = target.document.get('run') + outputs = run.get('outputs') if isinstance(run, dict) else None + if not isinstance(outputs, dict) or use.output not in outputs: + name = use.role.split(':', 1)[1] + add('error', definition.path, documents.pointer('run', 'inputs', name, 'output'), + f'{use.target} declares no output named {use.output!r}; use one of its run.outputs or declare it there.') + + +def _sound_benchmark(chart, definitions, unsound): + """Return the chart's benchmark document, or None when it is missing or has its own errors.""" + target = definitions.get(chart.get('benchmark')) if isinstance(chart.get('benchmark'), str) else None + if target is None or target.kind != 'benchmark' or target.document is None or target.path in unsound: + return None + return target.document + + +def _check_charts(definitions, unsound, add): + for definition in definitions.values(): + chart = definition.document + if definition.kind != 'chart' or not isinstance(chart, dict): + continue + benchmark = _sound_benchmark(chart, definitions, unsound) + if benchmark is None: + continue # a missing benchmark is a reference problem; a broken one reports its own + reference = chart['benchmark'] + metrics = benchmark.get('metrics') if isinstance(benchmark.get('metrics'), list) else [] + metric_ids = {m.get('id') for m in metrics if isinstance(m, dict)} + for key in ('metric', 'metric_x'): + if isinstance(chart.get(key), str) and chart[key] not in metric_ids: + add('error', definition.path, f'/{key}', f'{reference} has no metric {chart[key]!r}; use one of its metric ids.') + subjects = benchmark.get('subjects') if isinstance(benchmark.get('subjects'), list) else [] + names = {s.get('name') for s in subjects if isinstance(s, dict)} + if isinstance(chart.get('subjects'), list): + for index, name in enumerate(chart['subjects']): + if isinstance(name, str) and name not in names: + add('error', definition.path, documents.pointer('subjects', index), + f'{reference} has no subject {name!r}; use one of its subject names.') + if isinstance(chart.get('group'), str): + summary = benchmark.get('summary') if isinstance(benchmark.get('summary'), dict) else {} + group_by = summary.get('group_by') if isinstance(summary.get('group_by'), list) else [] + if chart['group'] not in group_by: + add('error', definition.path, '/group', + f'{reference} does not group its summary by {chart["group"]!r}; use one of its summary.group_by.') + + +def _check_cycles(definitions, add): + decoded = {reference: d.document for reference, d in definitions.items() if d.document is not None} + for group in graph.cycles(decoded): + members = set(group) + listed = ', '.join(group) + for reference in group: + definition = definitions[reference] + pointer = next((use.pointer for use in graph.uses(definition.document) if use.target in members), '') + add('error', definition.path, pointer, + f'This definition is in a cycle of uses ({listed}); remove one of the references to break it.') + + +def _check_results(files, definitions, unsound, add): + for file in files: + name = file.path[len('results/'):-len('.csv')] + benchmark = definitions.get(documents.reference('benchmarks', name)) + if benchmark is None: + add('error', file.path, '', f'There is no benchmarks/{name}.json for this summary; add the benchmark or remove the file.') + continue + if file.text is None or benchmark.document is None: + continue # unreadable: already reported + if benchmark.path in unsound: + add('warning', file.path, '', f'Not checked, because {benchmark.path} has errors; fix those first.') + continue + for severity, pointer, message in results.check_results(file.text, benchmark.document): + add(severity, file.path, pointer, message) diff --git a/tuldok_project/documents.py b/tuldok_project/documents.py new file mode 100644 index 00000000..06f426ee --- /dev/null +++ b/tuldok_project/documents.py @@ -0,0 +1,287 @@ +"""Single-document rules of the project folder format: JSON, names, references, placeholders, schemas. + +Owns the rules that can be decided from one file alone (sections 2.1 to 2.7 of +docs/plans/definition-first-projects/spec-m1-m2.md): strict JSON decoding, the +name and reference syntax, the placeholder syntax of commands, the form of +relative paths, and validation against the JSON Schema files in schemas/, +whose errors it turns into a field pointer and one plain sentence. It also owns +Problem, the one shape every checker in this package reports. +""" +from dataclasses import dataclass +from functools import lru_cache +import json +import math +from pathlib import Path +import re + +import jsonschema + +PROJECT_FORMAT = 'tuldok_project_v1' +DEFINITION_FORMAT = 'tuldok_definition_v1' + +# Kind -> the directory that holds definitions of that kind. +DIRECTORIES = { + 'dataset': 'datasets', + 'model': 'models', + 'recipe': 'recipes', + 'benchmark': 'benchmarks', + 'step': 'steps', + 'environment': 'environments', + 'chart': 'charts', +} +KINDS = {directory: kind for kind, directory in DIRECTORIES.items()} + +# Which directories each reference-taking field accepts (2.6, 2.7). The keys +# are the edge roles of 2.9 without their ":" suffix. +ACCEPTS = { + 'input': ('datasets', 'recipes', 'steps'), + 'environment': ('environments',), + 'model': ('models',), + 'subject': ('recipes',), + 'cases': ('datasets',), + 'benchmark': ('benchmarks',), +} + +STATISTICS = ('mean', 'median', 'p10', 'p90', 'min', 'max') + +NAME = re.compile(r'^[a-z0-9][a-z0-9._-]{0,119}$') +_REFERENCE = re.compile(r'^([a-z]+)/([a-z0-9][a-z0-9._-]{0,119})$') +_SCHEMAS = Path(__file__).resolve().parent / 'schemas' + + +@dataclass(frozen=True) +class Problem: + """One finding: severity is 'error' or 'warning'; path is relative to the project folder.""" + severity: str + path: str + pointer: str + message: str + + def as_dict(self): + return {'severity': self.severity, 'path': self.path, + 'pointer': self.pointer, 'message': self.message} + + +class DocumentError(ValueError): + """A file is not a strict UTF-8 JSON object.""" + + +# ---------------------------------------------------------------- JSON (2.2) + +def _refuse_constant(name): + raise DocumentError(f'The file contains {name}, which this format does not allow.') + + +def _finite_float(text): + value = float(text) + if not math.isfinite(value): + raise DocumentError(f'The number {text} is too large to represent; write a smaller number.') + return value + + +def _unique_object(pairs): + seen = {} + for key, value in pairs: + if key in seen: + raise DocumentError(f'The key {key!r} appears twice in one object; keep only one.') + seen[key] = value + return seen + + +def decode(raw): + """Return the JSON object in raw (bytes or str); raise DocumentError on anything 2.2 refuses.""" + if isinstance(raw, bytes): + try: + raw = raw.decode('utf-8') + except UnicodeDecodeError as exc: + raise DocumentError(f'The file is not UTF-8 text (bad byte at offset {exc.start}).') from None + try: + value = json.loads(raw, object_pairs_hook=_unique_object, + parse_constant=_refuse_constant, parse_float=_finite_float) + except json.JSONDecodeError as exc: + raise DocumentError(f'The file is not valid JSON: {exc.msg} at line {exc.lineno}, column {exc.colno}.') from None + if not isinstance(value, dict): + raise DocumentError('The file must hold one JSON object, not a list or a single value.') + return value + + +# ------------------------------------------------------ names and references + +def is_name(value): + """True when value follows the name rule of 2.1.""" + return isinstance(value, str) and NAME.fullmatch(value) is not None + + +def parse_reference(value): + """Return (directory, name) for a reference string such as 'datasets/x', or None.""" + if not isinstance(value, str): + return None + match = _REFERENCE.fullmatch(value) + if match is None or match.group(1) not in KINDS: + return None + return match.group(1), match.group(2) + + +def reference(directory, name): + return f'{directory}/{name}' + + +def pointer(*parts): + """Return the JSON pointer for these path parts (keys or list indexes).""" + return ''.join('/' + str(part).replace('~', '~0').replace('/', '~1') for part in parts) + + +# ------------------------------------------------------------- paths (2.6) + +def relative_path_problem(value): + """Return a sentence fragment when value is not a normal relative path, else None. + + Normal means: not empty, not absolute, no '..', and no empty or '.' parts + (so no doubled or trailing '/'). + """ + if not isinstance(value, str) or not value: + return 'must be a non-empty relative path' + if '\x00' in value: + return 'contains a NUL character' + if value.startswith('/'): + return 'is absolute; write it relative' + parts = value.split('/') + if '..' in parts: + return "contains '..'; paths must stay inside their root" + if any(part in ('', '.') for part in parts): + return "is not in normal form; remove empty or '.' parts and any trailing '/'" + return None + + +# ------------------------------------------------------- placeholders (2.6) + +def placeholders(text): + """Return the names written as {name} in text; raise ValueError on a brace with no partner. + + '{{' and '}}' are literal braces and are not returned. + """ + names, index = [], 0 + while index < len(text): + char = text[index] + if char == '{': + if text.startswith('{{', index): + index += 2 + continue + end = text.find('}', index + 1) + inner = text[index + 1:end] if end >= 0 else '' + if end < 0 or '{' in inner: + raise ValueError('has a "{" with no closing "}"; write "{{" for a literal brace') + names.append(inner) + index = end + 1 + elif char == '}': + if text.startswith('}}', index): + index += 2 + continue + raise ValueError('has a "}" with no opening "{"; write "}}" for a literal brace') + else: + index += 1 + return names + + +def command_placeholder_problems(text, *, inputs, has_settings, benchmark): + """Return sentences for each placeholder in text that 2.6 does not allow here. + + inputs is the set of declared input names; has_settings says whether the run + has settings or settings_file; benchmark says whether {subject} is allowed. + """ + try: + names = placeholders(text) + except ValueError as exc: + return [f'The text {text!r} {exc}.'] + problems = [] + for name in names: + if name == 'output': + continue + if name == 'settings': + if not has_settings: + problems.append('{settings} is used but the run has neither settings nor settings_file; add one or remove the placeholder.') + continue + if name.startswith('inputs.'): + if name[len('inputs.'):] not in inputs: + problems.append(f'{{{name}}} names an input that run.inputs does not declare; declare it or fix the name.') + continue + if name in ('subject', 'subject.name'): + if not benchmark: + problems.append(f'{{{name}}} is only allowed in a benchmark; remove it.') + continue + problems.append(f'{{{name}}} is not a known placeholder; use {{output}}, {{settings}}, {{inputs.}}, or write "{{{{" for a literal brace.') + return problems + + +def argument_placeholder_problems(text, *, has_recipe): + """Return sentences for placeholders a benchmark subject's argument may not use (only {recipe}).""" + try: + names = placeholders(text) + except ValueError as exc: + return [f'The text {text!r} {exc}.'] + problems = [] + for name in names: + if name == 'recipe': + if not has_recipe: + problems.append('{recipe} is used but this subject has no recipe; add one or remove the placeholder.') + else: + problems.append(f'{{{name}}} is not allowed in a subject argument; only {{recipe}} is.') + return problems + + +# ----------------------------------------------------------------- schemas + +@lru_cache(maxsize=None) +def validator(name): + """Return the cached Draft 2020-12 validator for schemas/.schema.json ('project' or a kind).""" + schema = json.loads((_SCHEMAS / f'{name}.schema.json').read_text(encoding='utf-8')) + jsonschema.Draft202012Validator.check_schema(schema) + return jsonschema.Draft202012Validator(schema) + + +def _short(value): + text = json.dumps(value, ensure_ascii=False) + return text if len(text) <= 60 else text[:57] + '...' + + +def _translate(error): + """Yield (pointer, message) for one jsonschema error.""" + at = list(error.absolute_path) + where = pointer(*at) + schema = error.schema if isinstance(error.schema, dict) else {} + if error.validator == 'required': + for field in error.validator_value: + if isinstance(error.instance, dict) and field not in error.instance and error.message.startswith(repr(field)): + yield pointer(*at, field), f'Add the required field {field!r}.' + return + if error.validator == 'additionalProperties' and schema.get('additionalProperties') is False: + known = schema.get('properties', {}) + for field in sorted(error.instance): + if field not in known: + yield pointer(*at, field), f'Remove the unknown field {field!r}; this format does not define it here.' + return + description = schema.get('description') + if 'propertyNames' in error.absolute_schema_path: + # jsonschema reports a bad key at its object; point at the key instead. + expected = f'; expected {description}' if description else '' + yield pointer(*at, error.instance), f'The key {error.instance!r} is not valid here{expected}.' + return + if error.validator == 'const': + yield where, f'The value must be {json.dumps(error.validator_value)}.' + return + if error.validator == 'not' and description: + yield where, description + return + if description: + yield where, f'The value {_short(error.instance)} is not valid here; expected {description}.' + return + message = error.message if len(error.message) <= 200 else error.message[:197] + '...' + yield where, message[0].upper() + message[1:] + ('' if message.endswith('.') else '.') + + +def schema_problems(name, document): + """Return (pointer, message) pairs for every way document breaks schemas/.schema.json.""" + found = [] + for error in validator(name).iter_errors(document): + found.extend(_translate(error)) + return sorted(set(found)) diff --git a/tuldok_project/folder.py b/tuldok_project/folder.py new file mode 100644 index 00000000..a141c06f --- /dev/null +++ b/tuldok_project/folder.py @@ -0,0 +1,254 @@ +"""Reading a project folder safely: the layout, file types and size caps of the format. + +Owns section 2.1 of docs/plans/definition-first-projects/spec-m1-m2.md. It walks +the folder through directory descriptors without following symbolic links, +accepts only regular files and directories, enforces the size caps, and returns +every file it could read together with the problems it found. It decodes +tuldok.json and the definitions (documents.decode) but judges nothing else +about their content; that is check.py's work. +""" +from dataclasses import dataclass, field +import errno +import hashlib +import os +import stat + +from . import documents +from .documents import Problem + +DEFINITION_LIMIT = 1024 * 1024 +PROJECT_LIMIT = 64 * 1024 +RESULTS_LIMIT = 16 * 1024 * 1024 + +PROJECT_FILE = 'tuldok.json' +OPTIONAL_FILES = ('README.md', '.gitignore') +RESULTS = 'results' +NOTES = 'notes' + +_DIRECTORY_FLAGS = os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW | os.O_CLOEXEC +_FILE_FLAGS = os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK | os.O_CLOEXEC + + +@dataclass(frozen=True) +class File: + """One file read from the folder. document is the decoded JSON object, or None.""" + path: str + raw: bytes + sha256: str + text: str | None + document: dict | None + + +@dataclass(frozen=True) +class Definition(File): + kind: str = '' + name: str = '' + + @property + def directory(self): + return documents.DIRECTORIES[self.kind] + + @property + def reference(self): + return documents.reference(self.directory, self.name) + + +@dataclass +class Folder: + """What read_folder found. root is the absolute path of the folder.""" + root: str + project: File | None = None + definitions: list = field(default_factory=list) + results: list = field(default_factory=list) + notes: frozenset = frozenset() + problems: list = field(default_factory=list) + + +class _Unsafe(Exception): + """A file that the format does not allow; the message is one sentence for the owner.""" + + +def _read(directory_fd, name, limit): + """Return the bytes of a regular file, refusing links, other file types and oversize files.""" + try: + fd = os.open(name, _FILE_FLAGS, dir_fd=directory_fd) + except OSError as exc: + if exc.errno == errno.ELOOP: + raise _Unsafe('This is a symbolic link; replace it with a regular file.') from None + raise _Unsafe(f'The file cannot be opened: {exc.strerror}.') from None + try: + info = os.fstat(fd) + if not stat.S_ISREG(info.st_mode): + raise _Unsafe('This is not a regular file; replace it with one.') + if info.st_size > limit: + raise _Unsafe(f'The file is {info.st_size} bytes; the limit for this file is {limit} bytes.') + chunks, size = [], 0 + while size <= limit: + chunk = os.read(fd, min(1024 * 1024, limit + 1 - size)) + if not chunk: + break + chunks.append(chunk) + size += len(chunk) + if size > limit: + raise _Unsafe(f'The file grew past the limit of {limit} bytes while it was read.') + return b''.join(chunks) + finally: + os.close(fd) + + +def _entries(directory_fd): + """Return (name, kind) for each entry, sorted; kind is 'file', 'directory', 'link' or 'other'.""" + found = [] + with os.scandir(directory_fd) as listing: + for entry in listing: + if entry.is_symlink(): + kind = 'link' + elif entry.is_dir(follow_symlinks=False): + kind = 'directory' + elif entry.is_file(follow_symlinks=False): + kind = 'file' + else: + kind = 'other' + found.append((entry.name, kind)) + return sorted(found) + + +def _wrong_type(kind, wanted): + if kind == 'link': + return f'This is a symbolic link; replace it with a regular {wanted}.' + return f'This must be a {wanted}.' + + +def _load(folder, directory_fd, name, path, limit, *, decode): + """Read one file into a File, or record why not and return None.""" + try: + raw = _read(directory_fd, name, limit) + except _Unsafe as exc: + folder.problems.append(Problem('error', path, '', str(exc))) + return None + digest = hashlib.sha256(raw).hexdigest() + try: + text = raw.decode('utf-8') + except UnicodeDecodeError as exc: + folder.problems.append(Problem('error', path, '', f'The file is not UTF-8 text (bad byte at offset {exc.start}).')) + return File(path, raw, digest, None, None) + document = None + if decode: + try: + document = documents.decode(text) + except documents.DocumentError as exc: + folder.problems.append(Problem('error', path, '', str(exc))) + return File(path, raw, digest, text, document) + + +def _open_directory(folder, parent_fd, name, path): + try: + return os.open(name, _DIRECTORY_FLAGS, dir_fd=parent_fd) + except OSError as exc: + folder.problems.append(Problem('error', path, '', f'The directory cannot be opened: {exc.strerror}.')) + return None + + +def _read_definitions(folder, root_fd, directory): + fd = _open_directory(folder, root_fd, directory, directory) + if fd is None: + return + kind = documents.KINDS[directory] + try: + for name, entry_kind in _entries(fd): + path = f'{directory}/{name}' + if entry_kind != 'file' or not name.endswith('.json'): + message = (_wrong_type(entry_kind, 'file') if entry_kind == 'link' + else f'{directory}/ may hold only .json files, one definition each; move or remove this.') + folder.problems.append(Problem('error', path, '', message)) + continue + stem = name[:-len('.json')] + if not documents.is_name(stem): + folder.problems.append(Problem('error', path, '', f'{stem!r} is not a valid name; use lowercase letters, digits, ".", "_" or "-", starting with a letter or digit.')) + continue + loaded = _load(folder, fd, name, path, DEFINITION_LIMIT, decode=True) + if loaded is not None: + folder.definitions.append(Definition(**vars(loaded), kind=kind, name=stem)) + finally: + os.close(fd) + + +def _read_results(folder, root_fd): + fd = _open_directory(folder, root_fd, RESULTS, RESULTS) + if fd is None: + return + try: + for name, entry_kind in _entries(fd): + path = f'{RESULTS}/{name}' + stem = name[:-len('.csv')] if name.endswith('.csv') else None + if entry_kind != 'file' or stem is None or not documents.is_name(stem): + message = (_wrong_type(entry_kind, 'file') if entry_kind == 'link' + else 'results/ may hold only .csv files; move or remove this.') + folder.problems.append(Problem('error', path, '', message)) + continue + loaded = _load(folder, fd, name, path, RESULTS_LIMIT, decode=False) + if loaded is not None: + folder.results.append(loaded) + finally: + os.close(fd) + + +def _read_notes(folder, root_fd): + """Collect the relative paths of every regular file under notes/; contents are not read.""" + found = set() + top = _open_directory(folder, root_fd, NOTES, NOTES) + if top is None: + return + pending = [(top, NOTES)] + while pending: + fd, prefix = pending.pop() + try: + for name, entry_kind in _entries(fd): + path = f'{prefix}/{name}' + if entry_kind == 'file': + found.add(path) + elif entry_kind == 'directory': + child = _open_directory(folder, fd, name, path) + if child is not None: + pending.append((child, path)) + else: + folder.problems.append(Problem('error', path, '', _wrong_type(entry_kind, 'file or directory'))) + finally: + os.close(fd) + folder.notes = frozenset(found) + + +def read_folder(path): + """Read the project folder at path; return a Folder with every file read and every layout problem.""" + root = os.path.abspath(os.fspath(path)) + folder = Folder(root) + try: + root_fd = os.open(root, os.O_RDONLY | os.O_DIRECTORY | os.O_CLOEXEC) + except OSError as exc: + folder.problems.append(Problem('error', '.', '', f'The project folder {root} cannot be opened: {exc.strerror}.')) + return folder + try: + entries = dict(_entries(root_fd)) + for name, entry_kind in sorted(entries.items()): + if name == PROJECT_FILE or name in OPTIONAL_FILES: + # README.md and .gitignore are allowed but not read; a link is still refused. + if entry_kind != 'file': + folder.problems.append(Problem('error', name, '', _wrong_type(entry_kind, 'file'))) + elif name == PROJECT_FILE: + folder.project = _load(folder, root_fd, name, name, PROJECT_LIMIT, decode=True) + elif name in documents.KINDS or name in (RESULTS, NOTES): + if entry_kind != 'directory': + folder.problems.append(Problem('error', name, '', _wrong_type(entry_kind, 'directory'))) + elif name == RESULTS: + _read_results(folder, root_fd) + elif name == NOTES: + _read_notes(folder, root_fd) + else: + _read_definitions(folder, root_fd, name) + else: + folder.problems.append(Problem('error', name, '', 'This entry is not part of the project folder format; move it into notes/ or out of the folder.')) + if PROJECT_FILE not in entries: + folder.problems.append(Problem('error', PROJECT_FILE, '', 'The folder has no tuldok.json; add one with format, id and name.')) + finally: + os.close(root_fd) + return folder diff --git a/tuldok_project/graph.py b/tuldok_project/graph.py new file mode 100644 index 00000000..b17ee573 --- /dev/null +++ b/tuldok_project/graph.py @@ -0,0 +1,177 @@ +"""The uses-graph of a project: which definition uses which, and in what order to build them. + +Owns the edge table of section 2.9 of docs/plans/definition-first-projects/spec-m1-m2.md. +Every function is pure and takes `definitions`, a mapping of reference (such as +'datasets/x') to decoded document. Documents need not be valid: fields of the +wrong type are skipped, so the graph can be read even from a folder with problems. +Edges whose target is not in `definitions` are kept by edges() and uses() but +ignored by order() and cycles(). +""" +from dataclasses import dataclass +import heapq + +from . import documents + + +@dataclass(frozen=True, order=True) +class Edge: + """from_ref uses to_ref in the given role (for example 'input:training').""" + from_ref: str + to_ref: str + role: str + + +@dataclass(frozen=True) +class Use: + """One reference field of a document: its role, its JSON pointer, the target, and the named output if any.""" + role: str + pointer: str + target: str + output: str | None = None + + @property + def accepts(self): + """The directories this field accepts (documents.ACCEPTS).""" + return documents.ACCEPTS[self.role.split(':', 1)[0]] + + +def uses(document): + """Return every reference a document makes, in document order (the rows of the 2.9 table).""" + if not isinstance(document, dict): + return [] + found = [] + run = document.get('run') + if isinstance(run, dict): + inputs = run.get('inputs') + if isinstance(inputs, dict): + for name, value in inputs.items(): + if isinstance(value, str): + found.append(Use(f'input:{name}', documents.pointer('run', 'inputs', name), value)) + elif isinstance(value, dict) and isinstance(value.get('from'), str): + output = value.get('output') if isinstance(value.get('output'), str) else None + found.append(Use(f'input:{name}', documents.pointer('run', 'inputs', name, 'from'), value['from'], output)) + if isinstance(run.get('environment'), str): + found.append(Use('environment', '/run/environment', run['environment'])) + kind = document.get('kind') + if kind == 'recipe' and isinstance(document.get('model'), str): + found.append(Use('model', '/model', document['model'])) + if kind == 'benchmark': + subjects = document.get('subjects') + if isinstance(subjects, list): + for index, subject in enumerate(subjects): + if isinstance(subject, dict) and isinstance(subject.get('recipe'), str) and isinstance(subject.get('name'), str): + found.append(Use(f'subject:{subject["name"]}', documents.pointer('subjects', index, 'recipe'), subject['recipe'])) + cases = document.get('cases') + if isinstance(cases, dict) and isinstance(cases.get('dataset'), str): + found.append(Use('cases', '/cases/dataset', cases['dataset'])) + if kind == 'chart' and isinstance(document.get('benchmark'), str): + found.append(Use('benchmark', '/benchmark', document['benchmark'])) + return found + + +def is_wellformed(use): + """True when the target is a reference into a directory this field accepts.""" + parsed = documents.parse_reference(use.target) + return parsed is not None and parsed[0] in use.accepts + + +def edges(definitions): + """Return the sorted, distinct edges whose target is a reference into a directory the field accepts.""" + found = set() + for source, document in definitions.items(): + for use in uses(document): + if is_wellformed(use): + found.add(Edge(source, use.target, use.role)) + return sorted(found) + + +def _adjacency(definitions): + """Return {reference: sorted targets} restricted to references present in definitions.""" + adjacency = {reference: set() for reference in definitions} + for edge in edges(definitions): + if edge.to_ref in adjacency: + adjacency[edge.from_ref].add(edge.to_ref) + return {reference: sorted(targets) for reference, targets in adjacency.items()} + + +def cycles(definitions): + """Return each group of definitions that use each other in a cycle, as sorted tuples, sorted. + + A group is a strongly connected component with more than one member, or one + definition that uses itself. + """ + adjacency = _adjacency(definitions) + index_of, low, on_stack, stack, groups = {}, {}, set(), [], [] + counter = 0 + for start in sorted(adjacency): + if start in index_of: + continue + # Iterative Tarjan: each frame is (node, iterator over its targets). + index_of[start] = low[start] = counter + counter += 1 + stack.append(start) + on_stack.add(start) + frames = [(start, iter(adjacency[start]))] + while frames: + node, targets = frames[-1] + advanced = False + for target in targets: + if target not in index_of: + index_of[target] = low[target] = counter + counter += 1 + stack.append(target) + on_stack.add(target) + frames.append((target, iter(adjacency[target]))) + advanced = True + break + if target in on_stack: + low[node] = min(low[node], index_of[target]) + if advanced: + continue + frames.pop() + if frames: + parent = frames[-1][0] + low[parent] = min(low[parent], low[node]) + if low[node] == index_of[node]: + group = [] + while True: + member = stack.pop() + on_stack.discard(member) + group.append(member) + if member == node: + break + if len(group) > 1 or node in adjacency[node]: + groups.append(tuple(sorted(group))) + return sorted(groups) + + +def order(definitions): + """Return every reference with each one after everything it uses; ties broken by reference string. + + Raises ValueError when the graph has a cycle, since no such order exists. + """ + adjacency = _adjacency(definitions) + waiting = {reference: len(targets) for reference, targets in adjacency.items()} + users = {reference: [] for reference in adjacency} + for reference, targets in adjacency.items(): + for target in targets: + users[target].append(reference) + ready = [reference for reference, count in waiting.items() if count == 0] + heapq.heapify(ready) + result = [] + while ready: + reference = heapq.heappop(ready) + result.append(reference) + for user in users[reference]: + waiting[user] -= 1 + if waiting[user] == 0: + heapq.heappush(ready, user) + if len(result) != len(adjacency): + raise ValueError('The definitions use each other in a cycle: ' + + '; '.join(', '.join(group) for group in cycles(definitions)) + '.') + return result + + +def users_of(definitions, reference): + """Return the sorted edges whose target is reference: what uses it, and how.""" + return [edge for edge in edges(definitions) if edge.to_ref == reference] diff --git a/tuldok_project/results.py b/tuldok_project/results.py new file mode 100644 index 00000000..254fc9c8 --- /dev/null +++ b/tuldok_project/results.py @@ -0,0 +1,282 @@ +"""Benchmark result summaries: the statistics and the results/.csv files. + +Owns how a list of measured values becomes one summary row, and how summary rows +are written to, read from and checked in a project folder's results/ directory. +The format is section 2.8 of docs/plans/definition-first-projects/spec-m1-m2.md. +""" +import csv +import io +import math +import re +from dataclasses import dataclass +from datetime import datetime + +COLUMNS = ('subject', 'metric', 'group', 'count', 'unavailable', 'mean', 'median', + 'p10', 'p90', 'min', 'max', 'commit', 'produced') +STATISTICS = ('mean', 'median', 'p10', 'p90', 'min', 'max') + +HEADER = ','.join(COLUMNS) +_INTEGER = re.compile(r'[0-9]+') +# A finite decimal number, including the exponent form repr(float) uses (1e-05). +_DECIMAL = re.compile(r'-?[0-9]+(\.[0-9]+)?([eE][-+]?[0-9]+)?') +_COMMIT = re.compile(r'[0-9a-f]{40}') +_PRODUCED_FORMATS = ((re.compile(r'[0-9]{4}-[0-9]{2}-[0-9]{2}'), '%Y-%m-%d'), + (re.compile(r'[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z'), + '%Y-%m-%dT%H:%M:%SZ')) + + +@dataclass(frozen=True) +class SummaryRow: + """One line of a results file. The six statistics are None when count is 0.""" + subject: str + metric: str + group: str + count: int + unavailable: int + mean: float | None + median: float | None + p10: float | None + p90: float | None + min: float | None + max: float | None + commit: str + produced: str + + +def summarise(values, unavailable=0): + """Return {'count', 'unavailable', 'mean', 'median', 'p10', 'p90', 'min', 'max'} for measured values.""" + if isinstance(unavailable, bool) or not isinstance(unavailable, int) or unavailable < 0: + raise ValueError('unavailable must be an integer of at least 0') + ordered = sorted(float(value) for value in values) + if not all(math.isfinite(value) for value in ordered): + raise ValueError('measured values must be finite numbers') + summary = {'count': len(ordered), 'unavailable': unavailable} + if not ordered: + summary.update((name, None) for name in STATISTICS) + return summary + summary.update( + mean=math.fsum(ordered) / len(ordered), + median=_percentile(ordered, 5), + p10=_percentile(ordered, 1), + p90=_percentile(ordered, 9), + min=ordered[0], + max=ordered[-1], + ) + return summary + + +def _percentile(ordered, tenths): + """Linear interpolation at position (tenths / 10) * (count - 1), computed without rounding the position.""" + lower, remainder = divmod(tenths * (len(ordered) - 1), 10) + if remainder == 0: + return ordered[lower] + low, high = ordered[lower], ordered[lower + 1] + return low + (high - low) * (remainder / 10) + + +def _sort_key(row): + return (row.subject, row.metric, row.group) + + +def write_results(rows): + """Return the text of a results file for these SummaryRow items, sorted as the format requires.""" + buffer = io.StringIO() + writer = csv.writer(buffer, lineterminator='\n') + writer.writerow(COLUMNS) + for row in sorted(rows, key=_sort_key): + cells = [] + for column in COLUMNS: + value = getattr(row, column) + if column in STATISTICS: + cells.append('' if value is None else repr(float(value))) + elif column in ('count', 'unavailable'): + cells.append(str(int(value))) + else: + cells.append(value) + writer.writerow(cells) + return buffer.getvalue() + + +def _records(text): + """Return ([(first physical line number, cells)], error), error being None or (line number, message).""" + reader = csv.reader(io.StringIO(text, newline=''), strict=True) + records = [] + previous_end = 0 + try: + for cells in reader: + records.append((previous_end + 1, cells)) + previous_end = reader.line_num + except csv.Error as error: + return records, (reader.line_num, str(error)) + return records, None + + +def read_results(text): + """Return the SummaryRow items of a results file's text; raise ValueError on a malformed file.""" + rows = [] + records, error = _records(text) + if error is not None: + raise ValueError(f'line {error[0]}: results file is not valid CSV: {error[1]}') + if not records or text.split('\n', 1)[0] != HEADER: + raise ValueError(f'results file must start with the header {HEADER}') + for line, cells in records[1:]: + if len(cells) != len(COLUMNS): + raise ValueError(f'line {line}: expected {len(COLUMNS)} cells, found {len(cells)}') + fields = dict(zip(COLUMNS, cells)) + for column in ('count', 'unavailable'): + if not _INTEGER.fullmatch(fields[column]): + raise ValueError(f'line {line}: {column} must be an integer of at least 0') + fields[column] = int(fields[column]) + for column in STATISTICS: + if fields[column] == '': + fields[column] = None + elif _DECIMAL.fullmatch(fields[column]): + fields[column] = float(fields[column]) + else: + raise ValueError(f'line {line}: {column} must be a decimal number or empty') + rows.append(SummaryRow(**fields)) + return rows + + +def _benchmark_names(benchmark_document): + """Return (subject names, metric ids, group_by keys, required statistics) read defensively.""" + document = benchmark_document if isinstance(benchmark_document, dict) else {} + + def strings(items, field): + if not isinstance(items, list): + return set() + return {item[field] for item in items + if isinstance(item, dict) and isinstance(item.get(field), str)} + + summary = document.get('summary') if isinstance(document.get('summary'), dict) else {} + group_by = summary.get('group_by') + group_by = {key for key in group_by if isinstance(key, str)} if isinstance(group_by, list) else set() + statistics = summary.get('statistics') + if isinstance(statistics, list): + statistics = [name for name in STATISTICS if name in statistics] + else: + statistics = list(STATISTICS) + return (strings(document.get('subjects'), 'name'), strings(document.get('metrics'), 'id'), + group_by, statistics) + + +def _group_problems(group, group_by): + """Return the messages for a group cell that breaks the key=value;key=value rule.""" + if group == '': + return [] + if '\n' in group or '\r' in group: + return ['group may not contain a line break.'] + keys = [] + for pair in group.split(';'): + key, separator, value = pair.partition('=') + if not separator or '=' in value: + return [f'group pair {pair!r} must be exactly one key=value.'] + keys.append(key) + messages = [f'group key {key!r} is not in the benchmark\'s summary.group_by.' + for key in keys if key not in group_by] + if len(set(keys)) != len(keys): + messages.append('group keys must not repeat.') + elif keys != sorted(keys): + messages.append('group keys must be sorted.') + return messages + + +def _produced_is_valid(produced): + for pattern, date_format in _PRODUCED_FORMATS: + if pattern.fullmatch(produced): + try: + datetime.strptime(produced, date_format) + except ValueError: + return False + return True + return False + + +def _row_problems(fields, subjects, metrics, group_by, statistics): + """Return the messages for one record's thirteen cells, each a sentence without its leading 'The '.""" + messages = [] + if fields['subject'] not in subjects: + messages.append(f'subject {fields["subject"]!r} is not a subject of the benchmark.') + if fields['metric'] not in metrics: + messages.append(f'metric {fields["metric"]!r} is not a metric id of the benchmark.') + messages.extend(_group_problems(fields['group'], group_by)) + for column in ('count', 'unavailable'): + if not _INTEGER.fullmatch(fields[column]): + messages.append(f'{column} {fields[column]!r} must be an integer of at least 0.') + for column in STATISTICS: + value = fields[column] + if value != '' and not _DECIMAL.fullmatch(value): + messages.append(f'{column} {value!r} must be a decimal number or empty.') + if _INTEGER.fullmatch(fields['count']): + if int(fields['count']) == 0: + filled = [column for column in STATISTICS if fields[column] != ''] + if filled: + messages.append(f'statistics must be empty when count is 0: {", ".join(filled)}.') + else: + missing = [column for column in statistics if fields[column] == ''] + if missing: + messages.append(f'statistics are missing although count is above 0: {", ".join(missing)}.') + if fields['commit'] != '' and not _COMMIT.fullmatch(fields['commit']): + messages.append('commit must be 40 lowercase hexadecimal characters or empty.') + if not _produced_is_valid(fields['produced']): + messages.append(f'produced {fields["produced"]!r} must be YYYY-MM-DD or YYYY-MM-DDTHH:MM:SSZ.') + return messages + + +def check_results(text, benchmark_document): + """Return a list of (severity, pointer, message) problems for a results file against its benchmark.""" + if isinstance(text, (bytes, bytearray)): + try: + text = bytes(text).decode('utf-8') + except UnicodeDecodeError: + return [('error', '', 'The results file is not UTF-8.')] + if not isinstance(text, str): + return [('error', '', 'The results file could not be read as text.')] + problems = [] + if text == '': + return [('error', '', 'The results file is empty; it must start with the header line.')] + if '\r' in text: + problems.append(('error', '', 'The results file must use \\n line ends, without \\r.')) + if not text.endswith('\n'): + problems.append(('warning', '', 'The results file does not end with a line end.')) + records, error = _records(text) + header_is_exact = text.split('\n', 1)[0].rstrip('\r') == HEADER + problems.extend(_record_problems(records, header_is_exact, benchmark_document)) + if error is not None: + problems.append(('error', f'line {error[0]}', f'The line is not valid RFC 4180 CSV: {error[1]}.')) + return problems + + +def _record_problems(records, header_is_exact, benchmark_document): + """Return the problems of the header and the rows that parsed as CSV, in line order.""" + problems = [] + if not records: + return problems + if not header_is_exact: + problems.append(('error', 'line 1', f'The first line must be exactly {HEADER}.')) + return problems + subjects, metrics, group_by, statistics = _benchmark_names(benchmark_document) + seen = set() + previous = None + for line, cells in records[1:]: + pointer = f'line {line}' + if not cells: + problems.append(('error', pointer, 'Empty lines are not allowed.')) + continue + if len(cells) != len(COLUMNS): + problems.append(('error', pointer, + f'The line has {len(cells)} cells; it must have {len(COLUMNS)}.')) + continue + fields = dict(zip(COLUMNS, cells)) + for message in _row_problems(fields, subjects, metrics, group_by, statistics): + problems.append(('error', pointer, 'The ' + message)) + key = (fields['subject'], fields['metric'], fields['group']) + if key in seen: + problems.append(('error', pointer, + 'The row repeats an earlier (subject, metric, group).')) + elif previous is not None and key < previous: + problems.append(('error', pointer, + 'The row is out of order; rows are sorted by subject, metric and group.')) + seen.add(key) + previous = key if previous is None or key > previous else previous + return problems diff --git a/tuldok_project/schemas/benchmark.schema.json b/tuldok_project/schemas/benchmark.schema.json new file mode 100644 index 00000000..98bb4ded --- /dev/null +++ b/tuldok_project/schemas/benchmark.schema.json @@ -0,0 +1,451 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://tuldok.invalid/schemas/benchmark.schema.json", + "title": "Tuldok benchmark definition", + "description": "One benchmark definition in benchmarks/.json (tuldok_definition_v1). Rules JSON Schema cannot express are checked in tuldok_project/check.py.", + "type": "object", + "additionalProperties": false, + "required": [ + "format", + "kind", + "title", + "metrics", + "subjects" + ], + "properties": { + "format": { + "const": "tuldok_definition_v1" + }, + "kind": { + "enum": [ + "dataset", + "model", + "recipe", + "benchmark", + "step", + "environment", + "chart" + ] + }, + "title": { + "$ref": "#/$defs/title" + }, + "description": { + "$ref": "#/$defs/description" + }, + "card": { + "$ref": "#/$defs/card" + }, + "labels": { + "$ref": "#/$defs/labels" + }, + "earlier_work": { + "$ref": "#/$defs/earlier_work" + }, + "run": { + "$ref": "#/$defs/run" + }, + "metrics": { + "type": "array", + "minItems": 1, + "maxItems": 64, + "items": { + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "title", + "better" + ], + "properties": { + "id": { + "$ref": "#/$defs/metric_id" + }, + "title": { + "$ref": "#/$defs/title" + }, + "units": { + "type": "string" + }, + "better": { + "enum": [ + "lower", + "higher", + "none" + ] + } + } + } + }, + "subjects": { + "type": "array", + "maxItems": 1000, + "items": { + "type": "object", + "additionalProperties": false, + "required": [ + "name" + ], + "properties": { + "name": { + "$ref": "#/$defs/name" + }, + "title": { + "$ref": "#/$defs/title" + }, + "recipe": { + "type": "string", + "pattern": "^recipes/[a-z0-9][a-z0-9._-]{0,119}$", + "description": "a reference to a recipe, such as recipes/" + }, + "argument": { + "type": "string" + } + } + } + }, + "cases": { + "type": "object", + "additionalProperties": false, + "properties": { + "dataset": { + "type": "string", + "pattern": "^datasets/[a-z0-9][a-z0-9._-]{0,119}$", + "description": "a reference to a dataset, such as datasets/" + }, + "split": { + "type": "string", + "minLength": 1 + }, + "count": { + "type": "integer", + "minimum": 0 + } + } + }, + "summary": { + "type": "object", + "additionalProperties": false, + "properties": { + "group_by": { + "type": "array", + "maxItems": 8, + "uniqueItems": true, + "items": { + "$ref": "#/$defs/metric_id" + } + }, + "statistics": { + "type": "array", + "uniqueItems": true, + "items": { + "enum": [ + "mean", + "median", + "p10", + "p90", + "min", + "max" + ] + } + } + } + } + }, + "if": { + "required": [ + "earlier_work" + ], + "properties": { + "earlier_work": { + "type": "object", + "required": [ + "rebuild" + ], + "properties": { + "rebuild": { + "const": "no" + } + } + } + } + }, + "else": { + "required": [ + "run" + ] + }, + "$defs": { + "name": { + "type": "string", + "pattern": "^[a-z0-9][a-z0-9._-]{0,119}$", + "description": "a name of lowercase letters, digits, '.', '_' or '-' that starts with a letter or digit, at most 120 characters" + }, + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$", + "description": "a key of lowercase letters, digits and '_' that starts with a letter, at most 32 characters" + }, + "metric_id": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,63}$", + "description": "an id of lowercase letters, digits and '_' that starts with a letter, at most 64 characters" + }, + "path": { + "type": "string", + "minLength": 1, + "maxLength": 1024 + }, + "sources": { + "type": "array", + "maxItems": 64, + "items": { + "$ref": "#/$defs/path" + } + }, + "command": { + "type": "array", + "minItems": 1, + "maxItems": 64, + "items": { + "type": "string" + } + }, + "title": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "description": { + "type": "string", + "maxLength": 4000 + }, + "card": { + "type": "string", + "pattern": "^notes/", + "description": "a path under notes/, such as notes/.md" + }, + "labels": { + "type": "object", + "maxProperties": 32, + "additionalProperties": { + "type": "string", + "maxLength": 400 + } + }, + "earlier_work": { + "type": "object", + "additionalProperties": false, + "required": [ + "rebuild" + ], + "properties": { + "rebuild": { + "enum": [ + "yes", + "after-inputs", + "needs-work", + "no" + ] + }, + "reason": { + "type": "string", + "minLength": 1, + "maxLength": 1000 + } + }, + "if": { + "required": [ + "rebuild" + ], + "properties": { + "rebuild": { + "enum": [ + "no", + "needs-work" + ] + } + } + }, + "then": { + "required": [ + "reason" + ] + } + }, + "input_reference": { + "type": "string", + "pattern": "^(datasets|recipes|steps)/[a-z0-9][a-z0-9._-]{0,119}$", + "description": "a reference to a definition in datasets/, recipes/ or steps/, such as datasets/" + }, + "input": { + "description": "a reference such as datasets/, or {\"from\": , \"output\": }", + "oneOf": [ + { + "$ref": "#/$defs/input_reference" + }, + { + "type": "object", + "additionalProperties": false, + "required": [ + "from", + "output" + ], + "properties": { + "from": { + "$ref": "#/$defs/input_reference" + }, + "output": { + "$ref": "#/$defs/key" + } + } + } + ] + }, + "run": { + "type": "object", + "additionalProperties": false, + "required": [ + "command" + ], + "properties": { + "command": { + "$ref": "#/$defs/command" + }, + "environment": { + "type": "string", + "pattern": "^environments/[a-z0-9][a-z0-9._-]{0,119}$", + "description": "a reference to an environment, such as environments/" + }, + "inputs": { + "type": "object", + "maxProperties": 32, + "propertyNames": { + "$ref": "#/$defs/key" + }, + "additionalProperties": { + "$ref": "#/$defs/input" + } + }, + "settings": { + "type": "object" + }, + "settings_file": { + "$ref": "#/$defs/path" + }, + "env": { + "type": "object", + "maxProperties": 32, + "propertyNames": { + "type": "string", + "pattern": "^[A-Z_][A-Z0-9_]*$", + "description": "an environment variable name of capital letters, digits and '_'" + }, + "additionalProperties": { + "type": "string" + } + }, + "outputs": { + "type": "object", + "propertyNames": { + "$ref": "#/$defs/key" + }, + "additionalProperties": { + "type": "object", + "additionalProperties": false, + "required": [ + "path", + "role" + ], + "properties": { + "path": { + "$ref": "#/$defs/path" + }, + "role": { + "enum": [ + "data", + "weights", + "results", + "log", + "report", + "file" + ] + } + } + } + }, + "resources": { + "type": "object", + "additionalProperties": false, + "properties": { + "gpu": { + "type": "boolean" + }, + "cpu_threads": { + "type": "integer", + "minimum": 1 + }, + "memory_gb": { + "type": "number", + "exclusiveMinimum": 0 + }, + "wall_hours": { + "type": "number", + "exclusiveMinimum": 0 + }, + "disk_gb": { + "type": "number", + "exclusiveMinimum": 0 + } + } + }, + "sources": { + "$ref": "#/$defs/sources" + }, + "estimate": { + "type": "object", + "additionalProperties": false, + "required": [ + "command" + ], + "properties": { + "command": { + "$ref": "#/$defs/command" + } + } + } + }, + "dependentSchemas": { + "settings": { + "properties": { + "settings_file": { + "not": {}, + "description": "Use either settings or settings_file, not both; remove one." + } + } + } + }, + "if": { + "required": [ + "command" + ], + "properties": { + "command": { + "type": "array", + "minItems": 1, + "prefixItems": [ + { + "const": "python" + } + ] + } + } + }, + "then": { + "required": [ + "environment" + ] + } + } + } +} diff --git a/tuldok_project/schemas/chart.schema.json b/tuldok_project/schemas/chart.schema.json new file mode 100644 index 00000000..4cc338dc --- /dev/null +++ b/tuldok_project/schemas/chart.schema.json @@ -0,0 +1,140 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://tuldok.invalid/schemas/chart.schema.json", + "title": "Tuldok chart definition", + "description": "One chart definition in charts/.json (tuldok_definition_v1). Rules JSON Schema cannot express are checked in tuldok_project/check.py.", + "type": "object", + "additionalProperties": false, + "required": [ + "format", + "kind", + "title", + "benchmark", + "form", + "metric" + ], + "properties": { + "format": { + "const": "tuldok_definition_v1" + }, + "kind": { + "enum": [ + "dataset", + "model", + "recipe", + "benchmark", + "step", + "environment", + "chart" + ] + }, + "title": { + "$ref": "#/$defs/title" + }, + "description": { + "$ref": "#/$defs/description" + }, + "card": { + "$ref": "#/$defs/card" + }, + "labels": { + "$ref": "#/$defs/labels" + }, + "benchmark": { + "type": "string", + "pattern": "^benchmarks/[a-z0-9][a-z0-9._-]{0,119}$", + "description": "a reference to a benchmark, such as benchmarks/" + }, + "form": { + "enum": [ + "ranking", + "tradeoff", + "progression", + "comparison" + ] + }, + "metric": { + "$ref": "#/$defs/metric_id" + }, + "metric_x": { + "$ref": "#/$defs/metric_id" + }, + "statistic": { + "enum": [ + "mean", + "median", + "p10", + "p90", + "min", + "max" + ] + }, + "subjects": { + "type": "array", + "uniqueItems": true, + "items": { + "$ref": "#/$defs/name" + } + }, + "group": { + "$ref": "#/$defs/metric_id" + } + }, + "if": { + "required": [ + "form" + ], + "properties": { + "form": { + "const": "tradeoff" + } + } + }, + "then": { + "required": [ + "metric_x" + ] + }, + "else": { + "properties": { + "metric_x": { + "not": {}, + "description": "metric_x is only allowed when form is tradeoff; remove it." + } + } + }, + "$defs": { + "name": { + "type": "string", + "pattern": "^[a-z0-9][a-z0-9._-]{0,119}$", + "description": "a name of lowercase letters, digits, '.', '_' or '-' that starts with a letter or digit, at most 120 characters" + }, + "metric_id": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,63}$", + "description": "an id of lowercase letters, digits and '_' that starts with a letter, at most 64 characters" + }, + "title": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "description": { + "type": "string", + "maxLength": 4000 + }, + "card": { + "type": "string", + "pattern": "^notes/", + "description": "a path under notes/, such as notes/.md" + }, + "labels": { + "type": "object", + "maxProperties": 32, + "additionalProperties": { + "type": "string", + "maxLength": 400 + } + } + } +} diff --git a/tuldok_project/schemas/dataset.schema.json b/tuldok_project/schemas/dataset.schema.json new file mode 100644 index 00000000..61ba913e --- /dev/null +++ b/tuldok_project/schemas/dataset.schema.json @@ -0,0 +1,340 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://tuldok.invalid/schemas/dataset.schema.json", + "title": "Tuldok dataset definition", + "description": "One dataset definition in datasets/.json (tuldok_definition_v1). Rules JSON Schema cannot express are checked in tuldok_project/check.py.", + "type": "object", + "additionalProperties": false, + "required": [ + "format", + "kind", + "title" + ], + "properties": { + "format": { + "const": "tuldok_definition_v1" + }, + "kind": { + "enum": [ + "dataset", + "model", + "recipe", + "benchmark", + "step", + "environment", + "chart" + ] + }, + "title": { + "$ref": "#/$defs/title" + }, + "description": { + "$ref": "#/$defs/description" + }, + "card": { + "$ref": "#/$defs/card" + }, + "labels": { + "$ref": "#/$defs/labels" + }, + "earlier_work": { + "$ref": "#/$defs/earlier_work" + }, + "run": { + "$ref": "#/$defs/run" + }, + "splits": { + "type": "object", + "additionalProperties": { + "type": "integer", + "minimum": 0 + } + } + }, + "if": { + "required": [ + "earlier_work" + ], + "properties": { + "earlier_work": { + "type": "object", + "required": [ + "rebuild" + ], + "properties": { + "rebuild": { + "const": "no" + } + } + } + } + }, + "else": { + "required": [ + "run" + ] + }, + "$defs": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$", + "description": "a key of lowercase letters, digits and '_' that starts with a letter, at most 32 characters" + }, + "path": { + "type": "string", + "minLength": 1, + "maxLength": 1024 + }, + "sources": { + "type": "array", + "maxItems": 64, + "items": { + "$ref": "#/$defs/path" + } + }, + "command": { + "type": "array", + "minItems": 1, + "maxItems": 64, + "items": { + "type": "string" + } + }, + "title": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "description": { + "type": "string", + "maxLength": 4000 + }, + "card": { + "type": "string", + "pattern": "^notes/", + "description": "a path under notes/, such as notes/.md" + }, + "labels": { + "type": "object", + "maxProperties": 32, + "additionalProperties": { + "type": "string", + "maxLength": 400 + } + }, + "earlier_work": { + "type": "object", + "additionalProperties": false, + "required": [ + "rebuild" + ], + "properties": { + "rebuild": { + "enum": [ + "yes", + "after-inputs", + "needs-work", + "no" + ] + }, + "reason": { + "type": "string", + "minLength": 1, + "maxLength": 1000 + } + }, + "if": { + "required": [ + "rebuild" + ], + "properties": { + "rebuild": { + "enum": [ + "no", + "needs-work" + ] + } + } + }, + "then": { + "required": [ + "reason" + ] + } + }, + "input_reference": { + "type": "string", + "pattern": "^(datasets|recipes|steps)/[a-z0-9][a-z0-9._-]{0,119}$", + "description": "a reference to a definition in datasets/, recipes/ or steps/, such as datasets/" + }, + "input": { + "description": "a reference such as datasets/, or {\"from\": , \"output\": }", + "oneOf": [ + { + "$ref": "#/$defs/input_reference" + }, + { + "type": "object", + "additionalProperties": false, + "required": [ + "from", + "output" + ], + "properties": { + "from": { + "$ref": "#/$defs/input_reference" + }, + "output": { + "$ref": "#/$defs/key" + } + } + } + ] + }, + "run": { + "type": "object", + "additionalProperties": false, + "required": [ + "command" + ], + "properties": { + "command": { + "$ref": "#/$defs/command" + }, + "environment": { + "type": "string", + "pattern": "^environments/[a-z0-9][a-z0-9._-]{0,119}$", + "description": "a reference to an environment, such as environments/" + }, + "inputs": { + "type": "object", + "maxProperties": 32, + "propertyNames": { + "$ref": "#/$defs/key" + }, + "additionalProperties": { + "$ref": "#/$defs/input" + } + }, + "settings": { + "type": "object" + }, + "settings_file": { + "$ref": "#/$defs/path" + }, + "env": { + "type": "object", + "maxProperties": 32, + "propertyNames": { + "type": "string", + "pattern": "^[A-Z_][A-Z0-9_]*$", + "description": "an environment variable name of capital letters, digits and '_'" + }, + "additionalProperties": { + "type": "string" + } + }, + "outputs": { + "type": "object", + "propertyNames": { + "$ref": "#/$defs/key" + }, + "additionalProperties": { + "type": "object", + "additionalProperties": false, + "required": [ + "path", + "role" + ], + "properties": { + "path": { + "$ref": "#/$defs/path" + }, + "role": { + "enum": [ + "data", + "weights", + "results", + "log", + "report", + "file" + ] + } + } + } + }, + "resources": { + "type": "object", + "additionalProperties": false, + "properties": { + "gpu": { + "type": "boolean" + }, + "cpu_threads": { + "type": "integer", + "minimum": 1 + }, + "memory_gb": { + "type": "number", + "exclusiveMinimum": 0 + }, + "wall_hours": { + "type": "number", + "exclusiveMinimum": 0 + }, + "disk_gb": { + "type": "number", + "exclusiveMinimum": 0 + } + } + }, + "sources": { + "$ref": "#/$defs/sources" + }, + "estimate": { + "type": "object", + "additionalProperties": false, + "required": [ + "command" + ], + "properties": { + "command": { + "$ref": "#/$defs/command" + } + } + } + }, + "dependentSchemas": { + "settings": { + "properties": { + "settings_file": { + "not": {}, + "description": "Use either settings or settings_file, not both; remove one." + } + } + } + }, + "if": { + "required": [ + "command" + ], + "properties": { + "command": { + "type": "array", + "minItems": 1, + "prefixItems": [ + { + "const": "python" + } + ] + } + } + }, + "then": { + "required": [ + "environment" + ] + } + } + } +} diff --git a/tuldok_project/schemas/environment.schema.json b/tuldok_project/schemas/environment.schema.json new file mode 100644 index 00000000..3a33f985 --- /dev/null +++ b/tuldok_project/schemas/environment.schema.json @@ -0,0 +1,120 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://tuldok.invalid/schemas/environment.schema.json", + "title": "Tuldok environment definition", + "description": "One environment definition in environments/.json (tuldok_definition_v1). Rules JSON Schema cannot express are checked in tuldok_project/check.py.", + "type": "object", + "additionalProperties": false, + "required": [ + "format", + "kind", + "title", + "python", + "device", + "packages" + ], + "properties": { + "format": { + "const": "tuldok_definition_v1" + }, + "kind": { + "enum": [ + "dataset", + "model", + "recipe", + "benchmark", + "step", + "environment", + "chart" + ] + }, + "title": { + "$ref": "#/$defs/title" + }, + "description": { + "$ref": "#/$defs/description" + }, + "card": { + "$ref": "#/$defs/card" + }, + "labels": { + "$ref": "#/$defs/labels" + }, + "python": { + "type": "string", + "pattern": "^3\\.(0|[1-9][0-9]*)$", + "description": "a Python version written 3., such as 3.12" + }, + "device": { + "enum": [ + "cpu", + "cuda" + ] + }, + "packages": { + "type": "object", + "minProperties": 1, + "maxProperties": 64, + "propertyNames": { + "type": "string", + "pattern": "^[A-Za-z0-9]([A-Za-z0-9._-]*[A-Za-z0-9])?$", + "description": "a package name such as numpy" + }, + "additionalProperties": { + "type": "string", + "pattern": "^[0-9A-Za-z][0-9A-Za-z.+!_-]*$", + "description": "an exact version such as 2.3.5, with no comparison operators" + } + }, + "install": { + "type": "object", + "additionalProperties": false, + "required": [ + "requirements" + ], + "properties": { + "requirements": { + "$ref": "#/$defs/path" + }, + "index_urls": { + "type": "array", + "maxItems": 4, + "items": { + "type": "string", + "pattern": "^https://\\S+$", + "description": "an https:// URL" + } + } + } + } + }, + "$defs": { + "path": { + "type": "string", + "minLength": 1, + "maxLength": 1024 + }, + "title": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "description": { + "type": "string", + "maxLength": 4000 + }, + "card": { + "type": "string", + "pattern": "^notes/", + "description": "a path under notes/, such as notes/.md" + }, + "labels": { + "type": "object", + "maxProperties": 32, + "additionalProperties": { + "type": "string", + "maxLength": 400 + } + } + } +} diff --git a/tuldok_project/schemas/model.schema.json b/tuldok_project/schemas/model.schema.json new file mode 100644 index 00000000..b3db3056 --- /dev/null +++ b/tuldok_project/schemas/model.schema.json @@ -0,0 +1,143 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://tuldok.invalid/schemas/model.schema.json", + "title": "Tuldok model definition", + "description": "One model definition in models/.json (tuldok_definition_v1). Rules JSON Schema cannot express are checked in tuldok_project/check.py.", + "type": "object", + "additionalProperties": false, + "required": [ + "format", + "kind", + "title" + ], + "properties": { + "format": { + "const": "tuldok_definition_v1" + }, + "kind": { + "enum": [ + "dataset", + "model", + "recipe", + "benchmark", + "step", + "environment", + "chart" + ] + }, + "title": { + "$ref": "#/$defs/title" + }, + "description": { + "$ref": "#/$defs/description" + }, + "card": { + "$ref": "#/$defs/card" + }, + "labels": { + "$ref": "#/$defs/labels" + }, + "earlier_work": { + "$ref": "#/$defs/earlier_work" + }, + "entry": { + "type": "string", + "minLength": 1 + }, + "config": { + "type": "object" + }, + "config_file": { + "$ref": "#/$defs/path" + }, + "sources": { + "$ref": "#/$defs/sources" + } + }, + "dependentSchemas": { + "config": { + "properties": { + "config_file": { + "not": {}, + "description": "Use either config or config_file, not both; remove one." + } + } + } + }, + "$defs": { + "path": { + "type": "string", + "minLength": 1, + "maxLength": 1024 + }, + "sources": { + "type": "array", + "maxItems": 64, + "items": { + "$ref": "#/$defs/path" + } + }, + "title": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "description": { + "type": "string", + "maxLength": 4000 + }, + "card": { + "type": "string", + "pattern": "^notes/", + "description": "a path under notes/, such as notes/.md" + }, + "labels": { + "type": "object", + "maxProperties": 32, + "additionalProperties": { + "type": "string", + "maxLength": 400 + } + }, + "earlier_work": { + "type": "object", + "additionalProperties": false, + "required": [ + "rebuild" + ], + "properties": { + "rebuild": { + "enum": [ + "yes", + "after-inputs", + "needs-work", + "no" + ] + }, + "reason": { + "type": "string", + "minLength": 1, + "maxLength": 1000 + } + }, + "if": { + "required": [ + "rebuild" + ], + "properties": { + "rebuild": { + "enum": [ + "no", + "needs-work" + ] + } + } + }, + "then": { + "required": [ + "reason" + ] + } + } + } +} diff --git a/tuldok_project/schemas/project.schema.json b/tuldok_project/schemas/project.schema.json new file mode 100644 index 00000000..768bc388 --- /dev/null +++ b/tuldok_project/schemas/project.schema.json @@ -0,0 +1,34 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://tuldok.invalid/schemas/project.schema.json", + "title": "Tuldok project folder: tuldok.json", + "description": "The tuldok.json file at the top of a project folder (tuldok_project_v1).", + "type": "object", + "additionalProperties": false, + "required": [ + "format", + "id", + "name" + ], + "properties": { + "format": { + "const": "tuldok_project_v1" + }, + "id": { + "type": "string", + "pattern": "^[0-9a-f]{32}$", + "description": "32 lowercase hexadecimal characters" + }, + "name": { + "type": "string", + "minLength": 1, + "maxLength": 120 + }, + "code_root": { + "type": "string", + "minLength": 1, + "pattern": "^[^/]", + "description": "a relative path from the project folder to the code root, never absolute" + } + } +} diff --git a/tuldok_project/schemas/recipe.schema.json b/tuldok_project/schemas/recipe.schema.json new file mode 100644 index 00000000..055a32a3 --- /dev/null +++ b/tuldok_project/schemas/recipe.schema.json @@ -0,0 +1,338 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://tuldok.invalid/schemas/recipe.schema.json", + "title": "Tuldok recipe definition", + "description": "One recipe definition in recipes/.json (tuldok_definition_v1). Rules JSON Schema cannot express are checked in tuldok_project/check.py.", + "type": "object", + "additionalProperties": false, + "required": [ + "format", + "kind", + "title" + ], + "properties": { + "format": { + "const": "tuldok_definition_v1" + }, + "kind": { + "enum": [ + "dataset", + "model", + "recipe", + "benchmark", + "step", + "environment", + "chart" + ] + }, + "title": { + "$ref": "#/$defs/title" + }, + "description": { + "$ref": "#/$defs/description" + }, + "card": { + "$ref": "#/$defs/card" + }, + "labels": { + "$ref": "#/$defs/labels" + }, + "earlier_work": { + "$ref": "#/$defs/earlier_work" + }, + "run": { + "$ref": "#/$defs/run" + }, + "model": { + "type": "string", + "pattern": "^models/[a-z0-9][a-z0-9._-]{0,119}$", + "description": "a reference to a model, such as models/" + } + }, + "if": { + "required": [ + "earlier_work" + ], + "properties": { + "earlier_work": { + "type": "object", + "required": [ + "rebuild" + ], + "properties": { + "rebuild": { + "const": "no" + } + } + } + } + }, + "else": { + "required": [ + "run" + ] + }, + "$defs": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$", + "description": "a key of lowercase letters, digits and '_' that starts with a letter, at most 32 characters" + }, + "path": { + "type": "string", + "minLength": 1, + "maxLength": 1024 + }, + "sources": { + "type": "array", + "maxItems": 64, + "items": { + "$ref": "#/$defs/path" + } + }, + "command": { + "type": "array", + "minItems": 1, + "maxItems": 64, + "items": { + "type": "string" + } + }, + "title": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "description": { + "type": "string", + "maxLength": 4000 + }, + "card": { + "type": "string", + "pattern": "^notes/", + "description": "a path under notes/, such as notes/.md" + }, + "labels": { + "type": "object", + "maxProperties": 32, + "additionalProperties": { + "type": "string", + "maxLength": 400 + } + }, + "earlier_work": { + "type": "object", + "additionalProperties": false, + "required": [ + "rebuild" + ], + "properties": { + "rebuild": { + "enum": [ + "yes", + "after-inputs", + "needs-work", + "no" + ] + }, + "reason": { + "type": "string", + "minLength": 1, + "maxLength": 1000 + } + }, + "if": { + "required": [ + "rebuild" + ], + "properties": { + "rebuild": { + "enum": [ + "no", + "needs-work" + ] + } + } + }, + "then": { + "required": [ + "reason" + ] + } + }, + "input_reference": { + "type": "string", + "pattern": "^(datasets|recipes|steps)/[a-z0-9][a-z0-9._-]{0,119}$", + "description": "a reference to a definition in datasets/, recipes/ or steps/, such as datasets/" + }, + "input": { + "description": "a reference such as datasets/, or {\"from\": , \"output\": }", + "oneOf": [ + { + "$ref": "#/$defs/input_reference" + }, + { + "type": "object", + "additionalProperties": false, + "required": [ + "from", + "output" + ], + "properties": { + "from": { + "$ref": "#/$defs/input_reference" + }, + "output": { + "$ref": "#/$defs/key" + } + } + } + ] + }, + "run": { + "type": "object", + "additionalProperties": false, + "required": [ + "command" + ], + "properties": { + "command": { + "$ref": "#/$defs/command" + }, + "environment": { + "type": "string", + "pattern": "^environments/[a-z0-9][a-z0-9._-]{0,119}$", + "description": "a reference to an environment, such as environments/" + }, + "inputs": { + "type": "object", + "maxProperties": 32, + "propertyNames": { + "$ref": "#/$defs/key" + }, + "additionalProperties": { + "$ref": "#/$defs/input" + } + }, + "settings": { + "type": "object" + }, + "settings_file": { + "$ref": "#/$defs/path" + }, + "env": { + "type": "object", + "maxProperties": 32, + "propertyNames": { + "type": "string", + "pattern": "^[A-Z_][A-Z0-9_]*$", + "description": "an environment variable name of capital letters, digits and '_'" + }, + "additionalProperties": { + "type": "string" + } + }, + "outputs": { + "type": "object", + "propertyNames": { + "$ref": "#/$defs/key" + }, + "additionalProperties": { + "type": "object", + "additionalProperties": false, + "required": [ + "path", + "role" + ], + "properties": { + "path": { + "$ref": "#/$defs/path" + }, + "role": { + "enum": [ + "data", + "weights", + "results", + "log", + "report", + "file" + ] + } + } + } + }, + "resources": { + "type": "object", + "additionalProperties": false, + "properties": { + "gpu": { + "type": "boolean" + }, + "cpu_threads": { + "type": "integer", + "minimum": 1 + }, + "memory_gb": { + "type": "number", + "exclusiveMinimum": 0 + }, + "wall_hours": { + "type": "number", + "exclusiveMinimum": 0 + }, + "disk_gb": { + "type": "number", + "exclusiveMinimum": 0 + } + } + }, + "sources": { + "$ref": "#/$defs/sources" + }, + "estimate": { + "type": "object", + "additionalProperties": false, + "required": [ + "command" + ], + "properties": { + "command": { + "$ref": "#/$defs/command" + } + } + } + }, + "dependentSchemas": { + "settings": { + "properties": { + "settings_file": { + "not": {}, + "description": "Use either settings or settings_file, not both; remove one." + } + } + } + }, + "if": { + "required": [ + "command" + ], + "properties": { + "command": { + "type": "array", + "minItems": 1, + "prefixItems": [ + { + "const": "python" + } + ] + } + } + }, + "then": { + "required": [ + "environment" + ] + } + } + } +} diff --git a/tuldok_project/schemas/step.schema.json b/tuldok_project/schemas/step.schema.json new file mode 100644 index 00000000..b8baa0d0 --- /dev/null +++ b/tuldok_project/schemas/step.schema.json @@ -0,0 +1,333 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://tuldok.invalid/schemas/step.schema.json", + "title": "Tuldok step definition", + "description": "One step definition in steps/.json (tuldok_definition_v1). Rules JSON Schema cannot express are checked in tuldok_project/check.py.", + "type": "object", + "additionalProperties": false, + "required": [ + "format", + "kind", + "title" + ], + "properties": { + "format": { + "const": "tuldok_definition_v1" + }, + "kind": { + "enum": [ + "dataset", + "model", + "recipe", + "benchmark", + "step", + "environment", + "chart" + ] + }, + "title": { + "$ref": "#/$defs/title" + }, + "description": { + "$ref": "#/$defs/description" + }, + "card": { + "$ref": "#/$defs/card" + }, + "labels": { + "$ref": "#/$defs/labels" + }, + "earlier_work": { + "$ref": "#/$defs/earlier_work" + }, + "run": { + "$ref": "#/$defs/run" + } + }, + "if": { + "required": [ + "earlier_work" + ], + "properties": { + "earlier_work": { + "type": "object", + "required": [ + "rebuild" + ], + "properties": { + "rebuild": { + "const": "no" + } + } + } + } + }, + "else": { + "required": [ + "run" + ] + }, + "$defs": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$", + "description": "a key of lowercase letters, digits and '_' that starts with a letter, at most 32 characters" + }, + "path": { + "type": "string", + "minLength": 1, + "maxLength": 1024 + }, + "sources": { + "type": "array", + "maxItems": 64, + "items": { + "$ref": "#/$defs/path" + } + }, + "command": { + "type": "array", + "minItems": 1, + "maxItems": 64, + "items": { + "type": "string" + } + }, + "title": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "description": { + "type": "string", + "maxLength": 4000 + }, + "card": { + "type": "string", + "pattern": "^notes/", + "description": "a path under notes/, such as notes/.md" + }, + "labels": { + "type": "object", + "maxProperties": 32, + "additionalProperties": { + "type": "string", + "maxLength": 400 + } + }, + "earlier_work": { + "type": "object", + "additionalProperties": false, + "required": [ + "rebuild" + ], + "properties": { + "rebuild": { + "enum": [ + "yes", + "after-inputs", + "needs-work", + "no" + ] + }, + "reason": { + "type": "string", + "minLength": 1, + "maxLength": 1000 + } + }, + "if": { + "required": [ + "rebuild" + ], + "properties": { + "rebuild": { + "enum": [ + "no", + "needs-work" + ] + } + } + }, + "then": { + "required": [ + "reason" + ] + } + }, + "input_reference": { + "type": "string", + "pattern": "^(datasets|recipes|steps)/[a-z0-9][a-z0-9._-]{0,119}$", + "description": "a reference to a definition in datasets/, recipes/ or steps/, such as datasets/" + }, + "input": { + "description": "a reference such as datasets/, or {\"from\": , \"output\": }", + "oneOf": [ + { + "$ref": "#/$defs/input_reference" + }, + { + "type": "object", + "additionalProperties": false, + "required": [ + "from", + "output" + ], + "properties": { + "from": { + "$ref": "#/$defs/input_reference" + }, + "output": { + "$ref": "#/$defs/key" + } + } + } + ] + }, + "run": { + "type": "object", + "additionalProperties": false, + "required": [ + "command" + ], + "properties": { + "command": { + "$ref": "#/$defs/command" + }, + "environment": { + "type": "string", + "pattern": "^environments/[a-z0-9][a-z0-9._-]{0,119}$", + "description": "a reference to an environment, such as environments/" + }, + "inputs": { + "type": "object", + "maxProperties": 32, + "propertyNames": { + "$ref": "#/$defs/key" + }, + "additionalProperties": { + "$ref": "#/$defs/input" + } + }, + "settings": { + "type": "object" + }, + "settings_file": { + "$ref": "#/$defs/path" + }, + "env": { + "type": "object", + "maxProperties": 32, + "propertyNames": { + "type": "string", + "pattern": "^[A-Z_][A-Z0-9_]*$", + "description": "an environment variable name of capital letters, digits and '_'" + }, + "additionalProperties": { + "type": "string" + } + }, + "outputs": { + "type": "object", + "propertyNames": { + "$ref": "#/$defs/key" + }, + "additionalProperties": { + "type": "object", + "additionalProperties": false, + "required": [ + "path", + "role" + ], + "properties": { + "path": { + "$ref": "#/$defs/path" + }, + "role": { + "enum": [ + "data", + "weights", + "results", + "log", + "report", + "file" + ] + } + } + } + }, + "resources": { + "type": "object", + "additionalProperties": false, + "properties": { + "gpu": { + "type": "boolean" + }, + "cpu_threads": { + "type": "integer", + "minimum": 1 + }, + "memory_gb": { + "type": "number", + "exclusiveMinimum": 0 + }, + "wall_hours": { + "type": "number", + "exclusiveMinimum": 0 + }, + "disk_gb": { + "type": "number", + "exclusiveMinimum": 0 + } + } + }, + "sources": { + "$ref": "#/$defs/sources" + }, + "estimate": { + "type": "object", + "additionalProperties": false, + "required": [ + "command" + ], + "properties": { + "command": { + "$ref": "#/$defs/command" + } + } + } + }, + "dependentSchemas": { + "settings": { + "properties": { + "settings_file": { + "not": {}, + "description": "Use either settings or settings_file, not both; remove one." + } + } + } + }, + "if": { + "required": [ + "command" + ], + "properties": { + "command": { + "type": "array", + "minItems": 1, + "prefixItems": [ + { + "const": "python" + } + ] + } + } + }, + "then": { + "required": [ + "environment" + ] + } + } + } +} From 3e787e065f26534c473fcf0d433b7b5a9ad12ad2 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Tue, 10 Nov 2026 14:49:46 -0700 Subject: [PATCH 006/131] docs(contracts): describe the project folder format and its checker A reference for people and agents who write a definition-first project folder: the layout, the seven definition kinds, result summary files, the rules that span files, and how to check a folder. Every example in it passes python -m tuldok_project check. Co-Authored-By: Claude Fable 5.2 --- docs/README.md | 1 + docs/contracts/project-folder.md | 554 +++++++++++++++++++++++++++++++ 2 files changed, 555 insertions(+) create mode 100644 docs/contracts/project-folder.md diff --git a/docs/README.md b/docs/README.md index 679739f8..eb187806 100644 --- a/docs/README.md +++ b/docs/README.md @@ -12,6 +12,7 @@ Start with the [root README](../README.md) for installation and the Data → Pip - [Project manifests and read-only inspection](contracts/projects.md) - [External text project files and current milestone limits](contracts/project-files.md) - [Project command line](contracts/project-cli.md) +- [Project folder format and checker](contracts/project-folder.md) ## Pipelines and execution diff --git a/docs/contracts/project-folder.md b/docs/contracts/project-folder.md new file mode 100644 index 00000000..26006907 --- /dev/null +++ b/docs/contracts/project-folder.md @@ -0,0 +1,554 @@ +# Project folder format + +Owner: the package `tuldok_project/` (`folder.py` reads the folder, `documents.py` +and `schemas/*.json` check single files, `check.py` applies every rule, +`results.py` owns summary files). The format names are `tuldok_project_v1` for +the folder and `tuldok_definition_v1` for each definition. + +A project folder describes a piece of research as a set of small JSON files that +people and agents write and keep in Git. Each file is a **definition**: it says +what a dataset, model, training recipe, benchmark, build step, environment or +chart is and, where something has to be produced, which command produces it. +What a command writes is a **product**. Products stay on the machine that made +them; the folder holds only what someone wrote, plus benchmark summaries. + +`python -m tuldok_project check FOLDER` tells you whether a folder is valid. This +document says exactly what the checker accepts. + +## What belongs in the folder + +Put in the folder: the definitions, the result summary of each benchmark +(`results/`), and cards and notes written by people (`notes/`). + +Keep out of the folder: generated datasets, weights, logs, run directories, +installed environments, caches, checksums of other files, and history. Git is +the history of every file in the folder. The scripts that commands run stay in +your code repository; definitions name them by path. + +A rule of thumb: if a person or an agent wrote it, it belongs in the folder. If a +command produced it, it does not. Result summaries are the one exception, so that +results travel with the project. + +## Layout + +``` +tuldok.json +README.md optional, not read +.gitignore optional, not read +datasets/.json +models/.json +recipes/.json +benchmarks/.json +steps/.json +environments/.json +charts/.json +results/.csv +notes/... +``` + +- `tuldok.json` is required. Every other entry is optional. +- Any other top-level entry is an error. Move such files into `notes/` or out of + the folder. +- The seven **definition directories** (`datasets/` to `charts/`) hold only + `.json` files, one definition each, and no subdirectories. +- `results/` holds only `.csv` files. +- `notes/` holds plain files and directories to any depth. Their contents are not + read. +- Every file is a regular file and every directory a real directory. A symbolic + link anywhere in the folder, including under `notes/`, is an error. +- Size limits: `tuldok.json` 64 KiB, a definition 1 MiB, a results file 16 MiB. + +A **name** is 1 to 120 characters of lowercase letters, digits, `.`, `_` and `-`, +starting with a letter or digit (`^[a-z0-9][a-z0-9._-]{0,119}$`). The file +`recipes/pilot-dense-k1.json` defines the recipe named `pilot-dense-k1`. + +## JSON rules + +`tuldok.json` and every definition are UTF-8 JSON, without a byte order mark, +holding one JSON object. The checker refuses: + +- a key that appears twice in one object; +- `NaN`, `Infinity` and `-Infinity`, and numbers too large to represent; +- any field this document does not define. The contents of `settings`, `config` + and the keys of `labels` are free. + +## `tuldok.json` + +| Field | Required | Rule | +| --- | --- | --- | +| `format` | yes | exactly `tuldok_project_v1` | +| `id` | yes | 32 lowercase hexadecimal characters; make a new one per project | +| `name` | yes | 1 to 120 characters | +| `code_root` | no | the path from the project folder to the root of the code that commands run in; default `.`; not empty and not absolute; may contain `..` | + +The **code root** is the directory that commands run in and that code paths in +definitions are relative to. It must be an existing directory. A folder kept at +`projects/surrogate-lab/` inside the code repository uses `../..`. + +Example, `tuldok.json`: + +```json +{ + "format": "tuldok_project_v1", + "id": "0dcc3af1e6b84b89a0e70554d98e7326", + "name": "Rheon surrogate lab", + "code_root": "../.." +} +``` + +## References and inputs + +A **reference** is the string `/`, for example +`datasets/sinusoidal-v1`. It names the definition in `datasets/sinusoidal-v1.json`, +which must exist. Each field that takes a reference accepts only some +directories: + +| Field | Accepts | +| --- | --- | +| `run.inputs` | `datasets/`, `recipes/`, `steps/` | +| `run.environment` | `environments/` | +| `model` (recipe) | `models/` | +| `subjects[].recipe` (benchmark) | `recipes/` | +| `cases.dataset` (benchmark) | `datasets/` | +| `benchmark` (chart) | `benchmarks/` | + +An **input** is what a command reads from another definition's product. It is +written either as a reference, meaning the whole product, or as +`{"from": , "output": }`, meaning one named output that the +other definition declares in its `run.outputs`. + +## Fields common to every definition + +| Field | Required | Rule | +| --- | --- | --- | +| `format` | yes | exactly `tuldok_definition_v1` | +| `kind` | yes | `dataset`, `model`, `recipe`, `benchmark`, `step`, `environment` or `chart`; must match the directory | +| `title` | yes | 1 to 200 characters | +| `description` | no | at most 4,000 characters | +| `card` | no | path of an existing file under `notes/`, written from the project folder, for example `notes/fits/early-fit.md` | +| `labels` | no | object of at most 32 entries; any keys; string values of at most 400 characters | +| `earlier_work` | no | see below; allowed on `dataset`, `model`, `recipe`, `benchmark` and `step` | + +`earlier_work` marks an item converted from work done before this format existed: + +| Field | Required | Rule | +| --- | --- | --- | +| `rebuild` | yes | `yes`, `after-inputs`, `needs-work` or `no` | +| `reason` | when `rebuild` is `needs-work` or `no` | 1 to 1,000 characters | + +The label states a fact about this item alone, never about what it uses: + +- `yes`: its command, code and settings are in Git and the command runs as written. +- `after-inputs`: the same, and one of its inputs is an earlier model's weights. +- `needs-work`: nothing it names is lost, but the recorded command does not run as + written. The reason says what has to change. +- `no`: its command, its code or its producer is lost or was never in Git. The + reason says which. + +Whether an item can in fact be rebuilt also depends on everything it uses; Tuldok +works that out from the references, so do not record it here. An item with +`rebuild: no` may leave out `run`. Code paths that are missing in an item with +`earlier_work` are warnings, not errors. + +Example, `recipes/pressure-fit-0042.json`: + +```json +{ + "format": "tuldok_definition_v1", + "kind": "recipe", + "title": "Pressure fit 0042", + "card": "notes/fits/pressure-fit-0042.md", + "labels": {"fit_id": "fit-0042", "trained_at": "2026-03-14"}, + "earlier_work": {"rebuild": "no", "reason": "Trained by the earlier study harness; its command and training data were not recorded."}, + "model": "models/divergence-free-stepper" +} +``` + +## The `run` block + +`dataset`, `recipe`, `benchmark` and `step` say how they are produced in a `run` +object. It is required unless `earlier_work.rebuild` is `no`. + +| Field | Required | Rule | +| --- | --- | --- | +| `command` | yes | 1 to 64 strings, the program and its arguments; run in the code root. When the first string is exactly `python` it means the environment's interpreter | +| `environment` | when the first string of `command` is `python` | reference to `environments/` | +| `inputs` | no | at most 32 entries; keys `^[a-z][a-z0-9_]{0,31}$`; values are inputs from `datasets/`, `recipes/` or `steps/` | +| `settings` | no | object, free content, written to a file whose path replaces `{settings}`; not together with `settings_file` | +| `settings_file` | no | code path of a settings file whose path replaces `{settings}` | +| `env` | no | at most 32 environment variables; names `^[A-Z_][A-Z0-9_]*$`; string values | +| `outputs` | no | keys as for `inputs`; each value `{"path": , "role": }`; role `data`, `weights`, `results`, `log`, `report` or `file` | +| `resources` | no | any of `gpu` (boolean), `cpu_threads` (integer ≥ 1), `memory_gb`, `wall_hours`, `disk_gb` (numbers > 0) | +| `sources` | no | at most 64 code paths (files or directories); a change in them means the code changed | +| `estimate` | no | `{"command": [...]}`, 1 to 64 strings; the command prints one JSON object with any of `disk_bytes`, `wall_seconds`, `items` | + +A **code path** is a path relative to the code root, at most 1,024 characters. +`settings_file`, `sources`, a model's `config_file` and `sources`, and an +environment's `install.requirements` are code paths. A code path, and an output's +`path`, must be in normal form: not absolute, no `..`, no `.` or empty parts, no +trailing `/`. A code path must exist under the code root (as a file or a +directory) and may not lead outside it through a symbolic link. + +**Placeholders** are written in braces in `command`, in `env` values and in +`estimate.command`: + +| Placeholder | Becomes | +| --- | --- | +| `{output}` | the directory the command writes into | +| `{settings}` | the path of the settings file; requires `settings` or `settings_file` | +| `{inputs.}` | the path of that input; `` must be a key of `inputs` | +| `{subject}` | benchmarks only: the current subject's `argument` | +| `{subject.name}` | benchmarks only: the current subject's name | + +Any other placeholder is an error, and so is a brace without its partner. Write +`{{` and `}}` for literal braces. + +## The seven kinds + +The examples below come from one project. References in them point at the other +examples, except `environments/cuda-torch`, a second environment not shown. + +### `dataset` + +| Field | Required | Rule | +| --- | --- | --- | +| `run` | unless `earlier_work.rebuild` is `no` | see the `run` block | +| `splits` | no | object, split name to a number of items (integer ≥ 0) | + +Example, `datasets/sinusoidal-v1.json`: + +```json +{ + "format": "tuldok_definition_v1", + "kind": "dataset", + "title": "Sinusoidal-forcing scenes v1", + "run": { + "command": ["python", "-m", "surrogate.datasets", "generate", "sinusoidal-v1", "--root", "{output}"], + "environment": "environments/lab-cpu", + "inputs": {"solver": {"from": "steps/reference-solver", "output": "probe"}}, + "env": {"SURROGATE_PROBE": "{inputs.solver}"}, + "outputs": {"bank": {"path": "sinusoidal-v1/bank.json", "role": "data"}}, + "resources": {"cpu_threads": 1}, + "sources": ["surrogate/datasets", "surrogate/scenes.py", "surrogate/solver.py"], + "estimate": {"command": ["python", "-m", "surrogate.datasets", "plan", "sinusoidal-v1", "--root", "{output}"]} + }, + "splits": {"train": 16, "development": 8, "reserved": 88} +} +``` + +### `model` + +A model is an architecture. It produces nothing by itself; recipes train it. + +| Field | Required | Rule | +| --- | --- | --- | +| `entry` | no | non-empty string naming the code entry point, for example `surrogate.models:DivergenceFreeStepper` | +| `config` | no | object, free content; not together with `config_file` | +| `config_file` | no | code path | +| `sources` | no | at most 64 code paths | + +Example, `models/divergence-free-stepper.json`: + +```json +{ + "format": "tuldok_definition_v1", + "kind": "model", + "title": "Divergence-free U-Net stepper", + "entry": "surrogate.models:DivergenceFreeStepper", + "sources": ["surrogate/models/stepper.py", "surrogate/models/unet3d.py"] +} +``` + +### `recipe` + +A recipe trains a model; its product is weights. + +| Field | Required | Rule | +| --- | --- | --- | +| `run` | unless `earlier_work.rebuild` is `no` | see the `run` block | +| `model` | no | reference to `models/` | + +Example, `recipes/pilot-dense-k1.json`: + +```json +{ + "format": "tuldok_definition_v1", + "kind": "recipe", + "title": "Pilot stepper on sinusoidal scenes, one output per pass", + "model": "models/divergence-free-stepper", + "run": { + "command": ["python", "-m", "surrogate.train", "{settings}", "{output}", "--device", "cuda"], + "environment": "environments/cuda-torch", + "settings_file": "surrogate/configs/pilot-dense-k1.json", + "inputs": {"training": "datasets/sinusoidal-v1"}, + "env": {"SURROGATE_DATA": "{inputs.training}"}, + "outputs": { + "weights": {"path": "model.pt", "role": "weights"}, + "log": {"path": "log.jsonl", "role": "log"} + }, + "resources": {"gpu": true}, + "sources": ["surrogate/train.py", "surrogate/models"] + } +} +``` + +### `step` + +A step is any other command whose output something needs, such as building a +solver. + +| Field | Required | Rule | +| --- | --- | --- | +| `run` | unless `earlier_work.rebuild` is `no` | see the `run` block | + +Example, `steps/reference-solver.json`: + +```json +{ + "format": "tuldok_definition_v1", + "kind": "step", + "title": "Rheon reference solver probe", + "run": { + "command": ["cargo", "build", "--release", "--locked", "--manifest-path", "probes/reference/Cargo.toml"], + "env": {"CARGO_TARGET_DIR": "{output}"}, + "outputs": {"probe": {"path": "release/rheon-reference-probe", "role": "file"}}, + "sources": ["probes/reference/Cargo.toml", "probes/reference/Cargo.lock", "probes/reference/src"] + } +} +``` + +### `benchmark` + +A benchmark measures **subjects** (the things being compared, usually trained +recipes) on **cases** (usually one split of a dataset) and reports **metrics**. +Its command runs once per subject. + +| Field | Required | Rule | +| --- | --- | --- | +| `run` | unless `earlier_work.rebuild` is `no` | see the `run` block; `outputs` must declare exactly one output with role `results` | +| `metrics` | yes | 1 to 64 objects, see below | +| `subjects` | yes | 0 to 1,000 objects, see below | +| `cases` | no | `{"dataset"?: reference to datasets/, "split"?: non-empty string, "count"?: integer ≥ 0}` | +| `summary` | no | `{"group_by"?: up to 8 distinct ids, "statistics"?: distinct names from mean, median, p10, p90, min, max}` | + +A metric is `{"id", "title", "units"?, "better"}`: `id` matches +`^[a-z][a-z0-9_]{0,63}$` and is unique in the benchmark; `title` is 1 to 200 +characters; `units` is any string; `better` is `lower`, `higher` or `none`. + +A subject is `{"name", "title"?, "recipe"?, "argument"?}`: `name` follows the name +rule and is unique in the benchmark; `title` is 1 to 200 characters; `recipe` is a +reference to `recipes/`; `argument` is the string that replaces `{subject}`. The +only placeholder an argument may hold is `{recipe}`, the path of that recipe's +product, and only when the subject has a `recipe`. + +`summary.group_by` names the dimensions the summary is split by, written with the +metric id pattern. `summary.statistics` says which statistics every summary row +with measured values must fill; without it, all six. + +Example, `benchmarks/dense-development-240.json`: + +```json +{ + "format": "tuldok_definition_v1", + "kind": "benchmark", + "title": "Sinusoidal development scenes, 240-output rollouts", + "run": { + "command": ["python", "-m", "surrogate.bench", "run", "--suite", "dense-development-240", "--subject", "{subject}", "--output", "{output}/result.json"], + "environment": "environments/cuda-torch", + "inputs": {"cases": "datasets/sinusoidal-v1"}, + "env": {"SURROGATE_DATA": "{inputs.cases}"}, + "outputs": {"results": {"path": "result.json", "role": "results"}}, + "sources": ["surrogate/bench"] + }, + "metrics": [ + {"id": "velocity_error_final", "title": "Final velocity error", "units": "ratio", "better": "lower"}, + {"id": "time_per_output_ms", "title": "Time per output", "units": "ms", "better": "lower"} + ], + "subjects": [ + {"name": "persistence", "title": "No change: the error any model must beat", "argument": "persistence"}, + {"name": "pilot-dense-k1", "recipe": "recipes/pilot-dense-k1", "argument": "checkpoint:{recipe}/model.pt"} + ], + "cases": {"dataset": "datasets/sinusoidal-v1", "split": "development", "count": 8}, + "summary": {"group_by": ["cells_per_metre"]} +} +``` + +### `environment` + +An environment says which Python and packages a command needs. Commands whose +first word is `python` name one. + +| Field | Required | Rule | +| --- | --- | --- | +| `python` | yes | `3.`, for example `3.12` | +| `device` | yes | `cpu` or `cuda` | +| `packages` | yes | 1 to 64 entries, package name to exact version. Names match `^[A-Za-z0-9]([A-Za-z0-9._-]*[A-Za-z0-9])?$`; versions match `^[0-9A-Za-z][0-9A-Za-z.+!_-]*$`, so `2.8.0+cpu` is allowed and `>=2.8` is not | +| `install` | no | `{"requirements": , "index_urls"?: up to 4 https:// URLs}` | + +`earlier_work` is not allowed here. + +Example, `environments/lab-cpu.json`: + +```json +{ + "format": "tuldok_definition_v1", + "kind": "environment", + "title": "Lab CPU environment", + "python": "3.12", + "device": "cpu", + "packages": {"numpy": "2.3.5", "torch": "2.8.0+cpu"}, + "install": { + "requirements": "tuldok/requirements-cpu.lock", + "index_urls": ["https://download.pytorch.org/whl/cpu"] + } +} +``` + +### `chart` + +A chart is drawn from one benchmark's summary. + +| Field | Required | Rule | +| --- | --- | --- | +| `benchmark` | yes | reference to `benchmarks/` | +| `form` | yes | `ranking`, `tradeoff`, `progression` or `comparison` | +| `metric` | yes | a metric id of that benchmark | +| `metric_x` | when `form` is `tradeoff`; otherwise not allowed | a metric id of that benchmark | +| `statistic` | no | `mean`, `median`, `p10`, `p90`, `min` or `max`; default `median` | +| `subjects` | no | distinct subject names of that benchmark; default all | +| `group` | no | one of that benchmark's `summary.group_by` | + +`earlier_work` is not allowed here. + +Example, `charts/final-velocity-ranking.json`: + +```json +{ + "format": "tuldok_definition_v1", + "kind": "chart", + "title": "Final velocity error by subject", + "benchmark": "benchmarks/dense-development-240", + "form": "ranking", + "metric": "velocity_error_final", + "group": "cells_per_metre" +} +``` + +## Results files + +`results/.csv` is the summary of benchmark `benchmarks/.json`, which +must exist. One row summarises the values of one metric for one subject, either +over all cases or over one group of them. + +- UTF-8, `\n` line ends (a `\r` is an error), CSV quoting as in RFC 4180, no + empty lines. The file should end with a line end; a missing one is a warning. +- The first line is exactly + `subject,metric,group,count,unavailable,mean,median,p10,p90,min,max,commit,produced` + and every other line has these 13 cells. + +| Column | Rule | +| --- | --- | +| `subject` | a subject name of the benchmark | +| `metric` | a metric id of the benchmark | +| `group` | empty for all cases, or `key=value` pairs joined by `;`, keys distinct, sorted, and each in the benchmark's `summary.group_by`; a value may not contain `;`, `=` or a line break | +| `count` | integer ≥ 0, digits only | +| `unavailable` | integer ≥ 0, digits only | +| `mean`, `median`, `p10`, `p90`, `min`, `max` | a decimal number matching `-?[0-9]+(\.[0-9]+)?([eE][-+]?[0-9]+)?`, or empty. All six are empty when `count` is 0. When `count` is above 0, each statistic in the benchmark's `summary.statistics` (all six by default) is filled; the others may be empty | +| `commit` | 40 lowercase hexadecimal characters (the Git commit of the code that measured), or empty | +| `produced` | a real date `YYYY-MM-DD` or time `YYYY-MM-DDTHH:MM:SSZ` | + +Rows are unique on (`subject`, `metric`, `group`) and sorted by those three +compared as plain strings, so `cells_per_metre=16` comes before +`cells_per_metre=8`. + +**Statistics.** For one subject, metric and group, take the measured values in +ascending order, v₀ … vₙ₋₁. `count` is n; `unavailable` is how many values could +not be measured. `mean` is the arithmetic mean, `min` is v₀ and `max` is vₙ₋₁. +`median`, `p10` and `p90` are the value at position p × (n − 1) for p = 0.5, 0.1 +and 0.9, interpolating linearly between the two closest values when the position +is not whole. For 0.12, 0.15, 0.2, 0.31, `p10` is at position 0.3: +0.12 + 0.3 × (0.15 − 0.12) = 0.129. Numbers are written as Python's +`repr(float)` writes them. `tuldok_project.results.summarise` computes them. + +Example, `results/dense-development-240.csv`: + +```csv +subject,metric,group,count,unavailable,mean,median,p10,p90,min,max,commit,produced +persistence,time_per_output_ms,,0,8,,,,,,,,2026-11-09 +persistence,velocity_error_final,cells_per_metre=8,4,0,0.9875,0.975,0.915,1.07,0.9,1.1,,2026-11-09 +pilot-dense-k1,time_per_output_ms,,8,0,43.825,43.8,40.76,46.99,40.2,47.9,4f1c0e9a7b2d3c5e6f708192a3b4c5d6e7f80912,2026-11-09T14:30:00Z +pilot-dense-k1,velocity_error_final,cells_per_metre=16,4,0,0.2625,0.235,0.192,0.355,0.18,0.4,4f1c0e9a7b2d3c5e6f708192a3b4c5d6e7f80912,2026-11-09T14:30:00Z +pilot-dense-k1,velocity_error_final,cells_per_metre=8,4,0,0.195,0.175,0.129,0.277,0.12,0.31,4f1c0e9a7b2d3c5e6f708192a3b4c5d6e7f80912,2026-11-09T14:30:00Z +``` + +## Rules across files + +1. Every reference names an existing definition in a directory its field accepts. +2. Every `{"from", "output"}` input names an output that the definition it comes + from declares in `run.outputs`. +3. Definitions may not use each other in a cycle. A definition uses another + through these fields: + + | Field | Role of the use | + | --- | --- | + | an entry of `run.inputs` | `input:` | + | `run.environment` | `environment` | + | a recipe's `model` | `model` | + | a benchmark subject's `recipe` | `subject:` | + | a benchmark's `cases.dataset` | `cases` | + | a chart's `benchmark` | `benchmark` | + +4. A chart's `metric`, `metric_x`, `subjects` and `group` exist in its benchmark. +5. Code paths exist under the code root (see the `run` block). +6. Every results file has its benchmark and follows the rules above. + +## Checking a folder + +From the Tuldok repository: + +```sh +.venv/bin/python -m tuldok_project check FOLDER [--no-code] [--json] +``` + +`FOLDER` is the directory that holds `tuldok.json`. `--no-code` skips looking +into the code root: the code root and code paths are not required to exist, but +paths are still checked for normal form. `--json` prints one JSON object instead +of text. + +The exit status is 0 when there are no errors (warnings allowed), 1 when there is +at least one error, and 2 for a usage error such as an unknown option. + +Every problem is reported; the check does not stop at the first. A problem has a +severity (`error` or `warning`), the file's path relative to the project folder, +a JSON pointer to the field (empty for a problem with the whole file; `line ` +in a results file), and one sentence. Text output prints one line per problem, +with the parts separated by two spaces and `-` for an empty pointer, sorted by +path and pointer, then a count: + +``` +error recipes/pilot-dense-k1.json /run/inputs/training datasets/sinusoidal-v2 does not exist; add datasets/sinusoidal-v2.json or fix the reference. +warning results/dense-development-240.csv - The results file does not end with a line end. +1 error, 1 warning in /home/me/lab/projects/surrogate-lab +``` + +With `--json` the object is `{"folder", "ok", "errors", "warnings", "problems"}`, +each problem being `{"severity", "path", "pointer", "message"}`. + +There are three warnings; every other problem is an error: + +- a code path that does not exist, in a definition with `earlier_work`; +- a results file without a final line end; +- a results file that is not checked because its benchmark has errors. + +One mistake is reported once. A reference into the wrong directory is reported by +the field's own rule and not again as a missing definition, and a chart is not +compared with a benchmark that has errors of its own. + +## What the format does not do yet + +The folder is checked, nothing more. Tuldok does not yet run any command, +estimate, install an environment, compare installed package versions, write +settings files, import results files or read the contents of notes. The `run`, `resources`, +`estimate`, `install` and `settings` fields record what a later Tuldok will use. + +Background: [the design notes for this format](../plans/definition-first-projects/). From e027ed3f703b335cbe86499061589e3ac2f12820 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Tue, 10 Nov 2026 14:53:09 -0700 Subject: [PATCH 007/131] feat(project): import a project folder into Postgres and save edits back store.open_project imports a checked folder into one schema per project (definitions as exact text plus jsonb, and the uses-graph as an edges table), attaches without re-checking when no definition file changed, and refuses a folder with errors without touching the database. Definitions can be set, removed and saved back to their files, with conflicts between unsaved edits and files changed on disk refused unless told to keep or discard. graph.states derives each definition's state from its own label and what it uses. The lab's 263 definitions open in 0.6 s into an empty database and in 0.01 s when nothing changed. Co-Authored-By: Claude Fable 5.2 --- .../definition-first-projects/spec-m1-m2.md | 41 +- tests/test_tuldok_project_store.py | 534 +++++++++++++++ tuldok_project/graph.py | 47 ++ tuldok_project/store.py | 639 ++++++++++++++++++ 4 files changed, 1255 insertions(+), 6 deletions(-) create mode 100644 tests/test_tuldok_project_store.py create mode 100644 tuldok_project/store.py diff --git a/docs/plans/definition-first-projects/spec-m1-m2.md b/docs/plans/definition-first-projects/spec-m1-m2.md index 6123f883..5eb0659c 100644 --- a/docs/plans/definition-first-projects/spec-m1-m2.md +++ b/docs/plans/definition-first-projects/spec-m1-m2.md @@ -283,6 +283,17 @@ Where the lab's command line cannot yet take a placeholder the format needs (for Tests: `lab:surrogate/tests/` is for the surrogate package; put the script's tests in `lab:scripts/tests/test_build_tuldok_project.py` and run them with the lab's `.venv/bin/python -m unittest`. +### Slice L2: the earlier runs' code and the authored comparisons (lab repository) + +Decided by the owner on 2026-11-10: bring the earlier runs' code into the lab repository, and keep the authored comparisons. + +- **`lab:earlier-run-code/`** holds the code and settings files that earlier items name and that have no tracked copy elsewhere. A file from `runs/` is copied to `earlier-run-code/`. Each distinct content is copied once: its home is the first of its paths in sorted order, and every item that names an identical file refers to that home. A `README.md` there says what the folder is and that `scripts/build_tuldok_project.py` writes it. +- **Copied:** Python code and settings files (the values a run was configured with). +- **Not copied:** archives and arrays (`.zip`, `.npz`, `.npy`, weights), which are generated data; and files that are records about other files and not settings (checksum listings, source witnesses, receipts, qualification records). Those are treated like files the old Tuldok generated: left out of `sources`, and named in the `needs-work` reason of an item whose command reads them. +- The script owns `earlier-run-code/` completely: it writes it, removes stale files, and `--check` covers it. +- Labels are recomputed with these files counted as tracked. +- **`notes/model-groups-and-comparisons.json`**, written by the script: the task groups and the comparisons between models from the old `notes/00-models.portfolio.json`, with each model named by its recipe reference. + ## 4. Milestone 2: open and save **Done when:** with an empty database, `python -m tuldok_project open lab:projects/surrogate-lab` completes in under 10 seconds and `list` and `graph` show every definition with its links and state; a second `open` with nothing changed completes in under 1 second. @@ -346,7 +357,24 @@ Only `input:` edges carry these states upward. A benchmark is not made `cannot-r - `project.remove_definition(reference)` refuses when another definition uses it; otherwise sets `removed = true`. - `project.save()` writes each unsaved definition to its file (temporary file in the same directory, `fsync`, rename) and deletes the files of removed ones. Before writing a file it checks the file on disk still has `file_sha256`; if any does not, it writes nothing and names them. -### 4.5 Command line +### 4.5 The `Project` object + +`store.open_project` returns a `Project` bound to one open connection. It reads from the database on demand and keeps no copy of the definitions in memory. + +| Member | Returns | +| --- | --- | +| `summary()` | project id, name, folder, code root, counts per kind, counts per state | +| `definitions(kind=None)` | one row per definition: reference, kind, title, state, unsaved, removed | +| `definition(reference)` | the text, the document, the state, what it uses and what uses it (each with its role) | +| `graph()` | the nodes with their states, and the edges | +| `order()` | the references in build order | +| `status()` | unsaved and removed definitions; files added, changed or missing on disk since the last import | +| `set_definition`, `remove_definition`, `save` | section 4.4 | +| `close()` | closes the connection | + +`store.drop_project(project_id, dsn=None)` drops a project's schema; tests and the `forget` command use it. A `Project` holds a session advisory lock for as long as it is open, so one process at a time has a project open; every command closes its `Project` before it exits. States are computed by a pure function `graph.states(definitions)` so the checker, the store and later milestones agree. + +### 4.6 Command line `python -m tuldok_project FOLDER`, with `--database-url` or `TULDOK_DATABASE_URL`, and `--json` on every reading command: @@ -358,17 +386,18 @@ Only `input:` edges carry these states upward. A benchmark is not made `cannot-r | `graph [--order]` | nodes with state and edges; `--order` prints build order | | `status` | unsaved and removed definitions; files changed on disk since import | | `set REFERENCE FILE`, `remove REFERENCE`, `save` | 4.4 | +| `forget` | drops this project's copy from the database (`store.drop_project`); the folder is not touched | -### 4.6 Slices +### 4.7 Slices | Slice | Files | Tests | | --- | --- | --- | -| T3 store | `tuldok_project/store.py` (4.1, 4.2, 4.3) | `tests/test_tuldok_project_store.py`, database | -| T4 edit and save | `store.py` additions (4.4) | same file, database | -| T5 commands | `tuldok_project/__main__.py` additions (4.5) | `tests/test_tuldok_project_cli.py` | +| T3 store | `tuldok_project/store.py` (4.1, 4.2, 4.5), `graph.states` in `tuldok_project/graph.py` (4.3) | `tests/test_tuldok_project_store.py`, database | +| T4 edit and save | `store.py` (4.4) | same file, database | +| T5 commands | `tuldok_project/__main__.py` additions (4.6) | `tests/test_tuldok_project_cli.py` | | T6 lab check | a timing run of the lab folder, recorded in `execution-ledger.md` | none | -T3 comes first; T4 and T5 follow it and do not overlap. +T3 and T4 are written together by one agent. T5 and T6 follow. ## 5. Not in milestones 1 and 2 diff --git a/tests/test_tuldok_project_store.py b/tests/test_tuldok_project_store.py new file mode 100644 index 00000000..e23b539f --- /dev/null +++ b/tests/test_tuldok_project_store.py @@ -0,0 +1,534 @@ +"""The database copy of a project folder: open, states, edit and save (spec sections 4.1 to 4.5). + +Database tests run only when TULDOK_DATABASE_URL names a disposable cluster +(see docs/plans/definition-first-projects/spec-m1-m2.md, section 1). Each test +copies tests/fixtures/tuldok_project/minimal into a temporary directory, gives +it a fresh project id and drops that project's schema afterwards, so tests +share no state. The states of section 4.3 are also tested as a pure function. +""" +import json +import os +from pathlib import Path +import shutil +import sys +import tempfile +import unittest +from unittest import mock +import uuid + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) + +import psycopg # noqa: E402 + +from metadata import connection_info # noqa: E402 +from tuldok_project import check, graph, store # noqa: E402 +from tuldok_project.store import ProjectError # noqa: E402 + +REPOSITORY = Path(__file__).resolve().parents[1] +FIXTURE = REPOSITORY / 'tests' / 'fixtures' / 'tuldok_project' / 'minimal' +DATABASE = os.environ.get('TULDOK_DATABASE_URL') + +FIXTURE_STATES = { + 'benchmarks/rollout': 'not-built', # its early-fit subject carries nothing + 'charts/rollout-ranking': 'none', + 'charts/speed-accuracy': 'none', + 'datasets/waves': 'not-built', + 'environments/lab-cpu': 'not-set-up', + 'models/stepper': 'none', + 'recipes/early-fit': 'cannot-rebuild', + 'recipes/stepper-k1': 'not-built', + 'recipes/stepper-k2': 'not-built', + 'steps/solver': 'not-built', +} + + +def _fixture_documents(): + project = FIXTURE / 'project' + found = {} + for path in sorted(project.glob('*/*.json')): + found[f'{path.parent.name}/{path.stem}'] = json.loads(path.read_text(encoding='utf-8')) + return found + + +class States(unittest.TestCase): + """graph.states, section 4.3, without a database.""" + + def setUp(self): + self.documents = _fixture_documents() + + def mark(self, reference, rebuild): + self.documents[reference]['earlier_work'] = {'rebuild': rebuild, 'reason': 'Test.'} + + def test_fixture(self): + self.assertEqual(graph.states(self.documents), FIXTURE_STATES) + + def test_needs_work_travels_up_through_inputs(self): + self.mark('steps/solver', 'needs-work') + states = graph.states(self.documents) + for reference in ('steps/solver', 'datasets/waves', 'recipes/stepper-k1', 'recipes/stepper-k2', + 'benchmarks/rollout'): + self.assertEqual(states[reference], 'needs-work', reference) + self.assertEqual(states['recipes/early-fit'], 'cannot-rebuild') + self.assertEqual(states['environments/lab-cpu'], 'not-set-up') + + def test_cannot_rebuild_travels_up_and_wins_over_needs_work(self): + self.mark('steps/solver', 'needs-work') + self.mark('recipes/stepper-k1', 'no') + states = graph.states(self.documents) + self.assertEqual(states['datasets/waves'], 'needs-work') + self.assertEqual(states['recipes/stepper-k1'], 'cannot-rebuild') + self.assertEqual(states['recipes/stepper-k2'], 'cannot-rebuild') # k1 is no, waves needs-work + self.assertEqual(states['benchmarks/rollout'], 'needs-work') # k1 is only a subject of it + + def test_only_input_edges_carry_states(self): + self.mark('models/stepper', 'no') # used by recipes through "model", not an input + states = graph.states(self.documents) + self.assertEqual(states['models/stepper'], 'cannot-rebuild') + self.assertEqual(states['recipes/stepper-k1'], 'not-built') + + def test_cycle_is_tolerated(self): + self.documents['steps/solver']['run']['inputs'] = {'scenes': 'datasets/waves'} + self.mark('datasets/waves', 'needs-work') + states = graph.states(self.documents) + self.assertEqual(states['steps/solver'], 'needs-work') + self.assertEqual(states['datasets/waves'], 'needs-work') + + +@unittest.skipUnless(DATABASE, 'TULDOK_DATABASE_URL is not set; database tests need a disposable cluster.') +class StoreCase(unittest.TestCase): + """A fresh copy of the fixture with its own project id, dropped afterwards.""" + + def setUp(self): + directory = tempfile.TemporaryDirectory() + self.addCleanup(directory.cleanup) + self.temporary = Path(directory.name) + self.base = self.temporary / 'minimal' + shutil.copytree(FIXTURE, self.base) + self.folder = self.base / 'project' + self.project_id = uuid.uuid4().hex + project_file = self.folder / 'tuldok.json' + document = json.loads(project_file.read_text(encoding='utf-8')) + document['id'] = self.project_id + project_file.write_text(json.dumps(document, indent=2) + '\n', encoding='utf-8') + self.schema = f'project_{self.project_id}' + self.opened = [] + self.addCleanup(self._cleanup) + + def _cleanup(self): + for project in self.opened: + project.close() + store.drop_project(self.project_id) + + def open(self, folder=None, **options): + project = store.open_project(folder or self.folder, **options) + self.opened.append(project) + return project + + def close(self, project): + project.close() + self.opened.remove(project) + + def database(self): + connection = psycopg.connect(connection_info(), autocommit=True) + self.addCleanup(connection.close) + return connection + + def dump(self): + """Every row of the project's tables, for asserting that nothing changed.""" + connection = self.database() + if connection.execute('SELECT 1 FROM pg_namespace WHERE nspname = %s', (self.schema,)).fetchone() is None: + return None + tables = {} + for table in ('state', 'definitions', 'edges'): + query = psycopg.sql.SQL('SELECT * FROM {}.{} ORDER BY 1, 2').format( + psycopg.sql.Identifier(self.schema), psycopg.sql.Identifier(table)) + tables[table] = connection.execute(query).fetchall() + return tables + + def read(self, reference): + return (self.folder / f'{reference}.json').read_text(encoding='utf-8') + + def write(self, reference, text, folder=None): + path = (folder or self.folder) / f'{reference}.json' + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(text, encoding='utf-8') + + def edited(self, reference, change, folder=None): + """The file's document with change(document) applied, as indented text.""" + document = json.loads(((folder or self.folder) / f'{reference}.json').read_text(encoding='utf-8')) + change(document) + return json.dumps(document, indent=4) + '\n' + + def counting_checker(self): + patcher = mock.patch.object(check, 'check_folder', wraps=check.check_folder) + checker = patcher.start() + self.addCleanup(patcher.stop) + return checker + + +class Open(StoreCase): + + def test_first_open_imports_every_definition(self): + project = self.open() + summary = project.summary() + self.assertEqual(summary['project_id'], self.project_id) + self.assertEqual(summary['folder'], os.path.realpath(self.folder)) + self.assertEqual(summary['code_root'], '../code') + self.assertEqual(summary['kinds'], {'benchmark': 1, 'chart': 2, 'dataset': 1, 'environment': 1, + 'model': 1, 'recipe': 3, 'step': 1}) + self.assertEqual(summary['states'], {'cannot-rebuild': 1, 'none': 3, 'not-built': 5, 'not-set-up': 1}) + rows = project.definitions() + self.assertEqual({row['reference']: row['state'] for row in rows}, FIXTURE_STATES) + self.assertEqual([row['reference'] for row in project.definitions(kind='chart')], + ['charts/rollout-ranking', 'charts/speed-accuracy']) + + shown = project.definition('datasets/waves') + self.assertEqual(shown['text'], self.read('datasets/waves')) # the exact file text + self.assertEqual(shown['document']['run']['settings']['layout'], {'grid': [16, 16]}) + self.assertEqual(shown['uses'], [{'reference': 'environments/lab-cpu', 'role': 'environment'}, + {'reference': 'steps/solver', 'role': 'input:solver'}]) + self.assertIn({'reference': 'recipes/stepper-k1', 'role': 'input:training'}, shown['used_by']) + self.assertIn({'reference': 'benchmarks/rollout', 'role': 'cases'}, shown['used_by']) + + drawn = project.graph() + self.assertEqual(len(drawn['nodes']), 10) + self.assertIn({'from': 'recipes/stepper-k2', 'to': 'recipes/stepper-k1', 'role': 'input:start'}, drawn['edges']) + self.assertEqual(len(drawn['edges']), len(check.check_folder(self.folder).edges)) + order = project.order() + self.assertLess(order.index('steps/solver'), order.index('datasets/waves')) + self.assertLess(order.index('recipes/stepper-k1'), order.index('recipes/stepper-k2')) + self.assertEqual(project.status(), {'unsaved': [], 'removed': [], 'added': [], 'changed': [], + 'missing': [], 'irregular': []}) + + def test_second_open_of_unchanged_folder_does_not_run_the_checker(self): + self.close(self.open()) + before = self.dump() + checker = self.counting_checker() + project = self.open() + checker.assert_not_called() + self.assertEqual(self.dump(), before) + self.assertEqual(len(project.definitions()), 10) + + def test_changed_added_and_removed_files_are_imported(self): + self.close(self.open()) + self.write('datasets/waves', self.edited('datasets/waves', lambda d: d.update(title='Waves again'))) + added = self.edited('charts/speed-accuracy', lambda d: d.update(title='Seconds against error')) + self.write('charts/seconds', added) + (self.folder / 'charts' / 'speed-accuracy.json').unlink() + checker = self.counting_checker() + project = self.open() + checker.assert_called_once() + references = {row['reference']: row for row in project.definitions()} + self.assertEqual(references['datasets/waves']['title'], 'Waves again') + self.assertEqual(project.definition('charts/seconds')['text'], added) + self.assertNotIn('charts/speed-accuracy', references) + self.assertNotIn('charts/speed-accuracy', [edge['from'] for edge in project.graph()['edges']]) + self.assertIn('charts/seconds', [edge['from'] for edge in project.graph()['edges']]) + + def test_folder_with_errors_leaves_the_database_unchanged(self): + self.close(self.open()) + before = self.dump() + self.write('datasets/waves', self.edited('datasets/waves', lambda d: d.pop('title'))) + with self.assertRaises(ProjectError) as caught: + self.open() + self.assertEqual(caught.exception.code, 'invalid') + self.assertIn(('datasets/waves.json', '/title'), + [(p.path, p.pointer) for p in caught.exception.problems if p.severity == 'error']) + self.assertEqual(self.dump(), before) + + def test_first_open_with_errors_creates_nothing(self): + self.write('recipes/stepper-k2', self.edited('recipes/stepper-k2', + lambda d: d.update(model='models/missing'))) + with self.assertRaises(ProjectError) as caught: + self.open() + self.assertEqual([(p.path, p.pointer) for p in caught.exception.problems], + [('recipes/stepper-k2.json', '/model')]) + self.assertIsNone(self.dump()) + + def test_second_path_requires_rebind(self): + self.close(self.open()) + moved = self.temporary / 'moved' + shutil.copytree(self.base, moved) + with self.assertRaises(ProjectError) as caught: + self.open(moved / 'project') + self.assertEqual(caught.exception.code, 'bound-elsewhere') + self.assertIn(os.path.realpath(self.folder), str(caught.exception)) + self.assertIn(os.path.realpath(moved / 'project'), str(caught.exception)) + checker = self.counting_checker() + project = self.open(moved / 'project', rebind=True) + checker.assert_not_called() # same files: rebinding attaches without a check + self.assertEqual(project.summary()['folder'], os.path.realpath(moved / 'project')) + self.close(project) + with self.assertRaises(ProjectError): + self.open() # the original path is now the other one + + def test_rebind_to_a_folder_with_different_files_imports_them(self): + self.close(self.open()) + moved = self.temporary / 'moved' + shutil.copytree(self.base, moved) + self.write('steps/solver', self.edited('steps/solver', lambda d: d.update(title='Moved solver'), + folder=moved / 'project'), folder=moved / 'project') + project = self.open(moved / 'project', rebind=True) + self.assertEqual(project.definition('steps/solver')['title'], 'Moved solver') + + def test_a_project_is_open_once(self): + self.open() + with self.assertRaises(ProjectError) as caught: + self.open() + self.assertEqual(caught.exception.code, 'busy') + with self.assertRaises(ProjectError): + store.drop_project(self.project_id) + + def test_states_travel_up_in_the_store(self): + self.write('steps/solver', self.edited('steps/solver', lambda d: d.update( + earlier_work={'rebuild': 'needs-work', 'reason': 'Its command needs a new flag.'}))) + self.write('recipes/stepper-k1', self.edited('recipes/stepper-k1', lambda d: d.update( + earlier_work={'rebuild': 'no', 'reason': 'Its code is lost.'}))) + project = self.open() + states = {row['reference']: row['state'] for row in project.definitions()} + self.assertEqual(states['datasets/waves'], 'needs-work') + self.assertEqual(states['benchmarks/rollout'], 'needs-work') + self.assertEqual(states['recipes/stepper-k2'], 'cannot-rebuild') + self.assertEqual(project.definition('recipes/stepper-k2')['state'], 'cannot-rebuild') + + +class Edit(StoreCase): + + def setUp(self): + super().setUp() + self.project = self.open() + + def assert_refused(self, reference, text, *expected): + before = self.dump() + with self.assertRaises(ProjectError) as caught: + self.project.set_definition(reference, text) + self.assertEqual(caught.exception.code, 'invalid') + found = [(p.path, p.pointer) for p in caught.exception.problems] + for item in expected: + self.assertIn(item, found) + self.assertEqual(self.dump(), before) + return caught.exception + + def test_set_definition_stores_the_exact_text_and_its_edges(self): + extra = json.dumps({'format': 'tuldok_definition_v1', 'kind': 'step', 'title': 'Extra', + 'run': {'command': ['true'], 'outputs': {'mesh': {'path': 'mesh.bin', 'role': 'file'}}}}) + self.project.set_definition('steps/extra', extra) + waves = self.edited('datasets/waves', lambda d: d['run']['inputs'].update( + mesh={'from': 'steps/extra', 'output': 'mesh'})) + self.project.set_definition('datasets/waves', waves) + shown = self.project.definition('datasets/waves') + self.assertEqual(shown['text'], waves) + self.assertTrue(shown['unsaved']) + self.assertIn({'reference': 'steps/extra', 'role': 'input:mesh'}, shown['uses']) + self.assertEqual(self.project.definition('steps/extra')['used_by'], + [{'reference': 'datasets/waves', 'role': 'input:mesh'}]) + self.assertEqual(self.project.status()['unsaved'], ['datasets/waves', 'steps/extra']) + self.assertLess(self.project.order().index('steps/extra'), self.project.order().index('datasets/waves')) + + def test_set_definition_changes_states(self): + self.project.set_definition('steps/solver', self.edited('steps/solver', lambda d: d.update( + earlier_work={'rebuild': 'needs-work', 'reason': 'Its command needs a new flag.'}))) + self.assertEqual(self.project.definition('recipes/stepper-k2')['state'], 'needs-work') + + def test_refused_when_not_json(self): + self.assert_refused('datasets/waves', '{"format": "tuldok_definition_v1",', ('datasets/waves.json', '')) + + def test_refused_when_the_document_alone_is_wrong(self): + self.assert_refused('datasets/waves', self.edited('datasets/waves', lambda d: d.pop('title')), + ('datasets/waves.json', '/title')) + self.assert_refused('datasets/waves', self.edited('datasets/waves', lambda d: d.update(kind='step')), + ('datasets/waves.json', '/kind')) + self.assert_refused('datasets/waves', self.edited('datasets/waves', lambda d: d['run'].update( + sources=['tools/missing.py'])), ('datasets/waves.json', '/run/sources/0')) + + def test_refused_when_a_reference_is_missing(self): + self.assert_refused('recipes/stepper-k1', self.edited('recipes/stepper-k1', lambda d: d.update( + model='models/missing')), ('recipes/stepper-k1.json', '/model')) + + def test_refused_when_a_named_output_is_missing(self): + self.assert_refused('recipes/stepper-k2', self.edited('recipes/stepper-k2', lambda d: d['run']['inputs'].update( + start={'from': 'recipes/stepper-k1', 'output': 'nothing'})), + ('recipes/stepper-k2.json', '/run/inputs/start/output')) + # Taking an output away from a producer breaks the definition that names it. + self.assert_refused('steps/solver', self.edited('steps/solver', lambda d: d['run']['outputs'].pop('binary')), + ('datasets/waves.json', '/run/inputs/solver/output')) + + def test_refused_when_it_makes_a_cycle(self): + error = self.assert_refused('steps/solver', self.edited('steps/solver', lambda d: d['run'].update( + inputs={'scenes': 'datasets/waves'})), ('steps/solver.json', '/run/inputs/scenes')) + self.assertTrue(any('cycle' in p.message for p in error.problems)) + + def test_refused_when_a_chart_no_longer_fits_its_benchmark(self): + self.assert_refused('benchmarks/rollout', self.edited('benchmarks/rollout', lambda d: d['metrics'].pop(1)), + ('charts/speed-accuracy.json', '/metric_x')) + + def test_refused_for_a_bad_reference(self): + with self.assertRaises(ProjectError) as caught: + self.project.set_definition('things/waves', self.read('datasets/waves')) + self.assertEqual(caught.exception.code, 'not-found') + + def test_remove_definition(self): + self.project.remove_definition('charts/speed-accuracy') + row = {r['reference']: r for r in self.project.definitions()}['charts/speed-accuracy'] + self.assertTrue(row['removed']) + self.assertNotIn('charts/speed-accuracy', [n['reference'] for n in self.project.graph()['nodes']]) + self.assertEqual(self.project.status()['removed'], ['charts/speed-accuracy']) + self.assertEqual(self.project.summary()['kinds']['chart'], 1) + + def test_remove_refused_while_used(self): + before = self.dump() + with self.assertRaises(ProjectError) as caught: + self.project.remove_definition('datasets/waves') + self.assertEqual(caught.exception.code, 'in-use') + self.assertEqual(caught.exception.references, ['benchmarks/rollout', 'recipes/stepper-k1', 'recipes/stepper-k2']) + self.assertEqual(self.dump(), before) + + def test_removing_a_user_frees_what_it_used(self): + self.project.remove_definition('charts/speed-accuracy') + self.project.remove_definition('charts/rollout-ranking') + self.project.remove_definition('benchmarks/rollout') + self.assertTrue({r['reference']: r for r in self.project.definitions()}['benchmarks/rollout']['removed']) + + def test_open_refuses_a_folder_that_no_longer_fits_unsaved_edits(self): + self.project.set_definition('datasets/waves', self.edited('datasets/waves', lambda d: d['run']['inputs'].update( + log={'from': 'steps/solver', 'output': 'log'}))) + self.close(self.project) + self.write('steps/solver', self.edited('steps/solver', lambda d: d['run']['outputs'].pop('log'))) + self.assertTrue(check.check_folder(self.folder).ok) # the folder alone is fine + before = self.dump() + with self.assertRaises(ProjectError) as caught: + self.open() + self.assertEqual(caught.exception.code, 'invalid') + self.assertIn(('datasets/waves.json', '/run/inputs/log/output'), + [(p.path, p.pointer) for p in caught.exception.problems]) + self.assertEqual(self.dump(), before) + + def test_removing_a_definition_never_saved_forgets_it(self): + extra = json.dumps({'format': 'tuldok_definition_v1', 'kind': 'model', 'title': 'Extra'}) + self.project.set_definition('models/extra', extra) + self.project.remove_definition('models/extra') + self.assertNotIn('models/extra', [r['reference'] for r in self.project.definitions()]) + + +class Save(StoreCase): + + def setUp(self): + super().setUp() + self.project = self.open() + + def test_save_writes_and_deletes_files(self): + waves = self.edited('datasets/waves', lambda d: d.update(title='Waves, saved')) + self.project.set_definition('datasets/waves', waves) + extra = '{"format":"tuldok_definition_v1","kind":"model","title":"Extra"}' + self.project.set_definition('models/extra', extra) + self.project.remove_definition('charts/speed-accuracy') + result = self.project.save() + self.assertEqual(result, {'written': ['datasets/waves', 'models/extra'], 'deleted': ['charts/speed-accuracy']}) + self.assertEqual(self.read('datasets/waves'), waves) + self.assertEqual(self.read('models/extra'), extra) + self.assertFalse((self.folder / 'charts' / 'speed-accuracy.json').exists()) + self.assertEqual(sorted(p.name for p in (self.folder / 'datasets').iterdir()), ['waves.json']) + self.assertEqual(self.project.status(), {'unsaved': [], 'removed': [], 'added': [], 'changed': [], + 'missing': [], 'irregular': []}) + self.assertTrue(check.check_folder(self.folder).ok) + # What was saved is what the database records, so the next open attaches without a check. + self.close(self.project) + checker = self.counting_checker() + reopened = self.open() + checker.assert_not_called() + self.assertFalse(reopened.definition('datasets/waves')['unsaved']) + + def test_save_refuses_when_a_file_changed_on_disk(self): + self.project.set_definition('steps/solver', self.edited('steps/solver', lambda d: d.update(title='Solver 2'))) + self.project.set_definition('datasets/waves', self.edited('datasets/waves', lambda d: d.update(title='W2'))) + self.project.remove_definition('charts/speed-accuracy') + on_disk = self.edited('datasets/waves', lambda d: d.update(title='Changed by hand')) + self.write('datasets/waves', on_disk) + solver = self.read('steps/solver') + self.assertEqual(self.project.status()['changed'], ['datasets/waves']) + with self.assertRaises(ProjectError) as caught: + self.project.save() + self.assertEqual(caught.exception.code, 'changed-on-disk') + self.assertEqual(caught.exception.references, ['datasets/waves']) + self.assertEqual(self.read('datasets/waves'), on_disk) + self.assertEqual(self.read('steps/solver'), solver) + self.assertTrue((self.folder / 'charts' / 'speed-accuracy.json').exists()) + self.assertTrue(self.project.definition('steps/solver')['unsaved']) + + def test_save_refuses_when_a_new_file_appeared_on_disk(self): + self.project.set_definition('models/extra', '{"format":"tuldok_definition_v1","kind":"model","title":"Extra"}') + self.write('models/extra', '{"format":"tuldok_definition_v1","kind":"model","title":"By hand"}') + with self.assertRaises(ProjectError) as caught: + self.project.save() + self.assertEqual(caught.exception.references, ['models/extra']) + + +class Conflict(StoreCase): + + def setUp(self): + super().setUp() + project = self.open() + self.edit = self.edited('datasets/waves', lambda d: d.update(title='Edited in Tuldok')) + project.set_definition('datasets/waves', self.edit) + self.close(project) + self.on_disk = self.edited('datasets/waves', lambda d: d.update(title='Edited by hand')) + self.write('datasets/waves', self.on_disk) + + def test_refused_without_a_choice(self): + before = self.dump() + with self.assertRaises(ProjectError) as caught: + self.open() + self.assertEqual(caught.exception.code, 'conflict') + self.assertEqual(caught.exception.references, ['datasets/waves']) + self.assertEqual(self.dump(), before) + + def test_keep_holds_the_edit_and_save_then_overwrites(self): + project = self.open(on_conflict='keep') + shown = project.definition('datasets/waves') + self.assertEqual(shown['text'], self.edit) + self.assertTrue(shown['unsaved']) + self.assertEqual(project.status()['changed'], []) + project.save() + self.assertEqual(self.read('datasets/waves'), self.edit) + + def test_discard_takes_the_file(self): + project = self.open(on_conflict='discard') + shown = project.definition('datasets/waves') + self.assertEqual(shown['text'], self.on_disk) + self.assertFalse(shown['unsaved']) + + def test_file_removed_on_disk_with_an_unsaved_edit(self): + project = self.open(on_conflict='discard') + chart = self.edited('charts/speed-accuracy', lambda d: d.update(title='Edited chart')) + project.set_definition('charts/speed-accuracy', chart) + self.close(project) + (self.folder / 'charts' / 'speed-accuracy.json').unlink() + with self.assertRaises(ProjectError) as caught: + self.open() + self.assertEqual(caught.exception.references, ['charts/speed-accuracy']) + project = self.open(on_conflict='keep') + self.assertTrue(project.definition('charts/speed-accuracy')['unsaved']) + project.save() + self.assertEqual(self.read('charts/speed-accuracy'), chart) + self.close(project) + (self.folder / 'charts' / 'speed-accuracy.json').unlink() + project = self.open(on_conflict='discard') # the row is clean now: no conflict, the file is just gone + self.assertNotIn('charts/speed-accuracy', [r['reference'] for r in project.definitions()]) + + +class Drop(StoreCase): + + def test_drop_project(self): + self.close(self.open()) + self.assertIsNotNone(self.dump()) + store.drop_project(self.project_id) + self.assertIsNone(self.dump()) + store.drop_project(self.project_id) # dropping what is not there is fine + + def test_drop_refuses_a_bad_id(self): + with self.assertRaises(ValueError): + store.drop_project('project; drop') + + +if __name__ == '__main__': + unittest.main() diff --git a/tuldok_project/graph.py b/tuldok_project/graph.py index b17ee573..8ca9233b 100644 --- a/tuldok_project/graph.py +++ b/tuldok_project/graph.py @@ -175,3 +175,50 @@ def order(definitions): def users_of(definitions, reference): """Return the sorted edges whose target is reference: what uses it, and how.""" return [edge for edge in edges(definitions) if edge.to_ref == reference] + + +# ------------------------------------------------------------ states (4.3) + +# The two states that travel upward through input edges, worst last. +_CARRIED = (None, 'needs-work', 'cannot-rebuild') +_OWN_STATE = {'needs-work': 1, 'no': 2} # earlier_work.rebuild -> index into _CARRIED +_BASE_STATE = {'dataset': 'not-built', 'recipe': 'not-built', 'benchmark': 'not-built', + 'step': 'not-built', 'environment': 'not-set-up', 'model': 'none', 'chart': 'none'} + + +def _kind(reference, document): + parsed = documents.parse_reference(reference) + if parsed is not None: + return documents.KINDS[parsed[0]] + return document.get('kind') if isinstance(document, dict) else None + + +def states(definitions): + """Return {reference: state} for every definition, by section 4.3 of the spec. + + cannot-rebuild and needs-work come from a definition's own + earlier_work.rebuild or from anything it uses through input edges, directly + or further up; the worse of the two wins. Other edges (environment, model, + subjects, cases, chart) carry nothing. Otherwise the state follows the + kind. The table is read in order, so a model marked rebuild "no" is + cannot-rebuild, not none. Cycles are tolerated: the result is the fixed point. + """ + severity = {} + for reference, document in definitions.items(): + earlier = document.get('earlier_work') if isinstance(document, dict) else None + rebuild = earlier.get('rebuild') if isinstance(earlier, dict) else None + severity[reference] = _OWN_STATE.get(rebuild, 0) + users = {reference: [] for reference in definitions} + for edge in edges(definitions): + if edge.role.startswith('input:') and edge.to_ref in users: + users[edge.to_ref].append(edge.from_ref) + # Severity only rises, at most twice per definition, so this ends even on a cycle. + pending = [reference for reference, value in severity.items() if value] + while pending: + reference = pending.pop() + for user in users[reference]: + if severity[user] < severity[reference]: + severity[user] = severity[reference] + pending.append(user) + return {reference: _CARRIED[severity[reference]] or _BASE_STATE.get(_kind(reference, document), 'none') + for reference, document in definitions.items()} diff --git a/tuldok_project/store.py b/tuldok_project/store.py new file mode 100644 index 00000000..eb4646ce --- /dev/null +++ b/tuldok_project/store.py @@ -0,0 +1,639 @@ +"""The database copy of an opened project folder: import, read, edit and save. + +Owns sections 4.1, 4.2, 4.4 and 4.5 of +docs/plans/definition-first-projects/spec-m1-m2.md. Each project lives in its own +Postgres schema, project_, holding the exact text and decoded document of +every definition, the uses-graph as an edge table, and which folder the copy is +bound to. Opening imports what changed on disk (after the checker passes) in +one transaction; an unchanged folder attaches by comparing SHA-256 digests +alone. Edits are validated with the checker's own rules and kept in the +database until save() writes them back. States are never stored: they are +computed by graph.states from the documents. A Project keeps no copy of the +definitions in memory and holds a session advisory lock on its project for as +long as it is open, so one Project at a time owns a project's copy. +""" +from dataclasses import dataclass +import hashlib +import os +import re +import tempfile + +import psycopg +from psycopg import sql +from psycopg.types.json import Jsonb + +from metadata import connection_info + +from . import check, documents, folder as folder_reader, graph +from .documents import Problem + +PROJECT_ID = re.compile(r'^[a-f0-9]{32}$') +CONFLICT_CHOICES = (None, 'keep', 'discard') + +_TABLES = ( + '''CREATE TABLE IF NOT EXISTS {schema}.state ( + singleton boolean PRIMARY KEY DEFAULT true CHECK (singleton), + project_id text NOT NULL, name text NOT NULL, + folder text NOT NULL, code_root text NOT NULL, + imported_at timestamptz NOT NULL)''', + '''CREATE TABLE IF NOT EXISTS {schema}.definitions ( + directory text NOT NULL, name text NOT NULL, + kind text NOT NULL, title text NOT NULL, + text text NOT NULL, document jsonb NOT NULL, + file_sha256 text, + unsaved boolean NOT NULL DEFAULT false, + removed boolean NOT NULL DEFAULT false, + PRIMARY KEY (directory, name))''', + '''CREATE TABLE IF NOT EXISTS {schema}.edges ( + from_ref text NOT NULL, to_ref text NOT NULL, role text NOT NULL, + PRIMARY KEY (from_ref, to_ref, role))''', + 'CREATE INDEX IF NOT EXISTS edges_to ON {schema}.edges (to_ref)', +) +# Later additive changes go here as ALTER TABLE ... ADD COLUMN IF NOT EXISTS. +_MIGRATIONS = () + +_UPSERT = '''INSERT INTO {schema}.definitions + (directory, name, kind, title, text, document, file_sha256, unsaved, removed) + VALUES (%s, %s, %s, %s, %s, %s, %s, %s, false) + ON CONFLICT (directory, name) DO UPDATE SET + kind = EXCLUDED.kind, title = EXCLUDED.title, text = EXCLUDED.text, + document = EXCLUDED.document, file_sha256 = EXCLUDED.file_sha256, + unsaved = EXCLUDED.unsaved, removed = false''' +_REFERENCE_SQL = "directory || '/' || name" + + +class ProjectError(Exception): + """An open, edit or save that was refused; nothing was changed. + + code is one of: invalid (the folder or the edit breaks the format; problems + lists why), conflict (files changed on disk where the database has unsaved + edits), bound-elsewhere, busy, in-use, changed-on-disk, not-found. + references names the definitions concerned. + """ + + def __init__(self, message, code, *, problems=(), references=()): + super().__init__(message) + self.code = code + self.problems = list(problems) + self.references = list(references) + + +# ------------------------------------------------------------ small helpers + +def _lock_key(schema): + """The advisory lock key of one project schema (the first 8 bytes of its SHA-256, signed).""" + return int.from_bytes(hashlib.sha256(schema.encode()).digest()[:8], 'big', signed=True) + + +def _schema(project_id): + if not isinstance(project_id, str) or not PROJECT_ID.fullmatch(project_id): + raise ValueError('A project id is 32 lowercase hex characters.') + return f'project_{project_id}' + + +def _sha(data): + return hashlib.sha256(data).hexdigest() + + +def _split(reference): + parsed = documents.parse_reference(reference) + if parsed is None: + raise ProjectError(f'{reference!r} is not a reference such as datasets/.', 'not-found', + references=[reference]) + return parsed + + +def _definition(reference, text, document): + """A folder.Definition built from database content, so the checker's functions accept it.""" + directory, name = documents.parse_reference(reference) + raw = text.encode('utf-8') + return folder_reader.Definition(path=f'{reference}.json', raw=raw, sha256=_sha(raw), text=text, + document=document, kind=documents.KINDS[directory], name=name) + + +def _errors(problems): + return [problem for problem in problems if problem.severity == 'error'] + + +def _open_root(root): + return os.open(root, os.O_RDONLY | os.O_DIRECTORY | os.O_CLOEXEC) + + +def _read_project_file(root): + """Return tuldok.json decoded and schema-valid, or None when the checker must explain why not.""" + try: + root_fd = _open_root(root) + except OSError: + return None + try: + raw = folder_reader._read(root_fd, folder_reader.PROJECT_FILE, folder_reader.PROJECT_LIMIT) + document = documents.decode(raw) + except (folder_reader._Unsafe, documents.DocumentError): + return None + finally: + os.close(root_fd) + return None if documents.schema_problems('project', document) else document + + +@dataclass(frozen=True) +class DiskListing: + """The definition files on disk: reference -> SHA-256, and paths that are not plain definition files.""" + files: dict + irregular: tuple + + +def _list_definitions(root): + """List the definition files with their SHA-256, without decoding or judging their content. + + Anything the layout rules would refuse (a link, a non-.json entry, a bad + name, an oversize file) is put in irregular, which sends open() to the checker. + """ + files, irregular = {}, [] + root_fd = _open_root(root) + try: + top = dict(folder_reader._entries(root_fd)) + for directory in documents.KINDS: + if directory not in top: + continue + if top[directory] != 'directory': + irregular.append(directory) + continue + fd = os.open(directory, folder_reader._DIRECTORY_FLAGS, dir_fd=root_fd) + try: + for name, entry_kind in folder_reader._entries(fd): + path = f'{directory}/{name}' + stem = name[:-len('.json')] if name.endswith('.json') else None + if entry_kind != 'file' or stem is None or not documents.is_name(stem): + irregular.append(path) + continue + try: + raw = folder_reader._read(fd, name, folder_reader.DEFINITION_LIMIT) + except folder_reader._Unsafe: + irregular.append(path) + continue + files[documents.reference(directory, stem)] = _sha(raw) + finally: + os.close(fd) + finally: + os.close(root_fd) + return DiskListing(files, tuple(irregular)) + + +def _notes(root): + """The set of note paths, as the checker's card rule needs them.""" + found = folder_reader.Folder(root) + try: + root_fd = _open_root(root) + except OSError: + return frozenset() + try: + if os.path.isdir(os.path.join(root, folder_reader.NOTES)): + folder_reader._read_notes(found, root_fd) + finally: + os.close(root_fd) + return found.notes + + +def _cross_problems(merged, unsound=frozenset()): + """Problems across files (references, named outputs, charts, cycles) for {reference: Definition}.""" + problems = [] + + def add(severity, path, pointer, message): + problems.append(Problem(severity, path, pointer, message)) + + check._check_references(merged, add) + check._check_charts(merged, set(unsound), add) + check._check_cycles(merged, add) + return problems + + +# --------------------------------------------------------------- the store + +def drop_project(project_id, dsn=None): + """Drop a project's schema and everything in it; refused while the project is open.""" + schema = _schema(project_id) + with psycopg.connect(connection_info(dsn), autocommit=True) as connection: + if not connection.execute('SELECT pg_try_advisory_lock(%s)', (_lock_key(schema),)).fetchone()[0]: + raise ProjectError('The project is open in another session; close it first.', 'busy') + connection.execute(sql.SQL('DROP SCHEMA IF EXISTS {} CASCADE').format(sql.Identifier(schema))) + + +def open_project(folder, *, rebind=False, on_conflict=None, dsn=None): + """Open the project folder: attach or import it (section 4.2) and return a Project. + + Raises ProjectError when the folder has check errors (problems carries + them), when it is bound to another folder and rebind is false, when files + changed on disk where the database holds unsaved edits and on_conflict is + neither 'keep' nor 'discard', or when the project is open elsewhere. + The database is unchanged whenever it raises. + """ + if on_conflict not in CONFLICT_CHOICES: + raise ValueError("on_conflict must be None, 'keep' or 'discard'.") + root = os.path.realpath(os.fspath(folder)) + project = _read_project_file(root) + if project is None: + report = check.check_folder(root) + raise ProjectError(f'The project folder {root} has errors; fix them and open it again.', 'invalid', + problems=_errors(report.problems) or report.problems) + schema = _schema(project['id']) + connection = psycopg.connect(connection_info(dsn), autocommit=True) + try: + if not connection.execute('SELECT pg_try_advisory_lock(%s)', (_lock_key(schema),)).fetchone()[0]: + raise ProjectError('This project is already open in another session.', 'busy') + opened = Project(connection, schema) + opened._attach(root, project, rebind=rebind, on_conflict=on_conflict) + return opened + except BaseException: + connection.close() + raise + + +class Project: + """One open project, bound to one connection; every read goes to the database.""" + + def __init__(self, connection, schema): + self._connection = connection + self.schema = schema + self.project_id = schema[len('project_'):] + + # ----------------------------------------------------------- plumbing + + def _sql(self, template): + return sql.SQL(template).format(schema=sql.Identifier(self.schema)) + + def _execute(self, template, parameters=None): + return self._connection.execute(self._sql(template), parameters) + + def _schema_exists(self): + return self._connection.execute('SELECT 1 FROM pg_namespace WHERE nspname = %s', + (self.schema,)).fetchone() is not None + + def _create_schema(self): + self._connection.execute(sql.SQL('CREATE SCHEMA IF NOT EXISTS {}').format(sql.Identifier(self.schema))) + for statement in (*_TABLES, *_MIGRATIONS): + self._execute(statement) + + def _state(self): + row = self._execute('SELECT project_id, name, folder, code_root, imported_at FROM {schema}.state').fetchone() + if row is None: + return None + return dict(zip(('project_id', 'name', 'folder', 'code_root', 'imported_at'), row)) + + def _documents(self, *, removed=True): + """{reference: document} for every row (with removed=False, only rows not removed).""" + where = '' if removed else ' WHERE NOT removed' + rows = self._execute(f'SELECT {_REFERENCE_SQL}, document FROM {{schema}}.definitions{where}').fetchall() + return dict(rows) + + def _merged_definitions(self): + """{reference: folder.Definition} for every row not removed, decoded from the exact text.""" + rows = self._execute(f'SELECT {_REFERENCE_SQL}, text FROM {{schema}}.definitions WHERE NOT removed').fetchall() + return {reference: _definition(reference, text, documents.decode(text)) for reference, text in rows} + + def _write_edges(self, rows, references=None): + """Replace the edges of these source references (all when None) with rows of graph.Edge.""" + if references is None: + self._execute('DELETE FROM {schema}.edges') + else: + self._execute('DELETE FROM {schema}.edges WHERE from_ref = ANY(%s)', (list(references),)) + if rows: + with self._connection.cursor() as cursor: + cursor.executemany(self._sql('INSERT INTO {schema}.edges (from_ref, to_ref, role) VALUES (%s, %s, %s)'), + [(edge.from_ref, edge.to_ref, edge.role) for edge in rows]) + + # --------------------------------------------------------------- open + + def _attach(self, root, project, *, rebind, on_conflict): + exists = self._schema_exists() + if exists: + with self._connection.transaction(): + self._create_schema() # brings an older schema up to date; additive only + state = self._state() if exists else None + if state is not None and state['folder'] != root and not rebind: + raise ProjectError(f'This project is bound to {state["folder"]}, not {root}; ' + 'open it with rebind to move it here.', 'bound-elsewhere') + rows = {} + if exists: + for reference, file_sha256, unsaved, removed in self._execute( + f'SELECT {_REFERENCE_SQL}, file_sha256, unsaved, removed FROM {{schema}}.definitions'): + rows[reference] = (file_sha256, unsaved or removed) + listing = _list_definitions(root) + on_disk = {reference: sha for reference, (sha, _) in rows.items() if sha is not None} + code_root = project.get('code_root', '.') + if (state is not None and not listing.irregular and listing.files == on_disk + and state['name'] == project['name'] and state['code_root'] == code_root): + if state['folder'] != root: + self._execute('UPDATE {schema}.state SET folder = %s', (root,)) + return + self._import(root, rows, on_conflict) + + def _import(self, root, rows, on_conflict): + report = check.check_folder(root) + if not report.ok: + raise ProjectError(f'The project folder {root} has errors; fix them and open it again.', 'invalid', + problems=report.problems) + if report.project.get('id') != self.project_id: + raise ProjectError('tuldok.json changed while the folder was being opened; open it again.', 'invalid') + disk = report.definitions + take, delete, reseat, conflicts = [], [], [], [] + for reference in sorted(set(disk) | set(rows)): + disk_sha = disk[reference].sha256 if reference in disk else None + row_sha, pending = rows.get(reference, (None, False)) + if disk_sha == row_sha: + continue + if pending: + conflicts.append(reference) + if on_conflict == 'keep': + reseat.append((reference, disk_sha)) + continue + (take if disk_sha is not None else delete).append(reference) + if conflicts and on_conflict is None: + raise ProjectError('These definitions changed on disk and also have unsaved edits here: ' + + ', '.join(conflicts) + '. Open again keeping or discarding the edits.', + 'conflict', references=conflicts) + + # The project as it will be: the folder, with the unsaved edits the database keeps. + merged = dict(disk) + kept = self._execute(f'SELECT {_REFERENCE_SQL}, text, removed FROM {{schema}}.definitions ' + 'WHERE unsaved OR removed').fetchall() if self._schema_exists() else [] + kept = [(reference, text, removed) for reference, text, removed in kept if reference not in take + and reference not in delete] + for reference, text, removed in kept: + if removed: + merged.pop(reference, None) + else: + merged[reference] = _definition(reference, text, documents.decode(text)) + if kept: + problems = _errors(_cross_problems(merged)) + if problems: + raise ProjectError('The folder no longer fits the unsaved edits held here; ' + 'save or discard them first.', 'invalid', problems=problems) + + project = report.project + with self._connection.transaction(): + self._create_schema() + with self._connection.cursor() as cursor: + if take: + cursor.executemany(self._sql(_UPSERT), [ + (*documents.parse_reference(reference), disk[reference].kind, disk[reference].document['title'], + disk[reference].text, Jsonb(disk[reference].document), disk[reference].sha256, False) + for reference in take]) + if delete: + cursor.executemany(self._sql('DELETE FROM {schema}.definitions WHERE directory = %s AND name = %s'), + [documents.parse_reference(reference) for reference in delete]) + if reseat: + cursor.executemany(self._sql('UPDATE {schema}.definitions SET file_sha256 = %s ' + 'WHERE directory = %s AND name = %s'), + [(sha, *documents.parse_reference(reference)) for reference, sha in reseat]) + self._write_edges(graph.edges({reference: d.document for reference, d in merged.items()})) + self._execute('''INSERT INTO {schema}.state (singleton, project_id, name, folder, code_root, imported_at) + VALUES (true, %s, %s, %s, %s, now()) + ON CONFLICT (singleton) DO UPDATE SET project_id = EXCLUDED.project_id, + name = EXCLUDED.name, folder = EXCLUDED.folder, + code_root = EXCLUDED.code_root, imported_at = EXCLUDED.imported_at''', + (self.project_id, project['name'], root, project.get('code_root', '.'))) + + # ------------------------------------------------------------ reading + + def summary(self): + """Project id, name, folder, code root, and counts per kind and per state (removed rows not counted).""" + state = self._state() + rows = self._execute('SELECT kind, count(*) FROM {schema}.definitions WHERE NOT removed GROUP BY kind').fetchall() + states = {} + for value in graph.states(self._documents(removed=False)).values(): + states[value] = states.get(value, 0) + 1 + return {'project_id': state['project_id'], 'name': state['name'], 'folder': state['folder'], + 'code_root': state['code_root'], 'kinds': dict(sorted(rows)), 'states': dict(sorted(states.items()))} + + def definitions(self, kind=None): + """One row per definition, sorted by reference: reference, kind, title, state, unsaved, removed.""" + states = graph.states(self._documents()) + query = f'SELECT {_REFERENCE_SQL}, kind, title, unsaved, removed FROM {{schema}}.definitions' + rows = (self._execute(query + ' WHERE kind = %s', (kind,)) if kind is not None else self._execute(query)).fetchall() + return [{'reference': reference, 'kind': row_kind, 'title': title, 'state': states[reference], + 'unsaved': unsaved, 'removed': removed} + for reference, row_kind, title, unsaved, removed in sorted(rows)] + + def definition(self, reference): + """The text, document and state of one definition, what it uses and what uses it (with roles).""" + directory, name = _split(reference) + row = self._execute('SELECT kind, title, text, document, unsaved, removed FROM {schema}.definitions ' + 'WHERE directory = %s AND name = %s', (directory, name)).fetchone() + if row is None: + raise ProjectError(f'There is no definition {reference}.', 'not-found', references=[reference]) + kind, title, text, document, unsaved, removed = row + uses = self._execute('SELECT to_ref, role FROM {schema}.edges WHERE from_ref = %s ORDER BY to_ref, role', + (reference,)).fetchall() + used_by = self._execute('SELECT from_ref, role FROM {schema}.edges WHERE to_ref = %s ORDER BY from_ref, role', + (reference,)).fetchall() + return {'reference': reference, 'kind': kind, 'title': title, 'text': text, 'document': document, + 'state': graph.states(self._documents())[reference], 'unsaved': unsaved, 'removed': removed, + 'uses': [{'reference': target, 'role': role} for target, role in uses], + 'used_by': [{'reference': source, 'role': role} for source, role in used_by]} + + def graph(self): + """The definitions not removed, with kind and state, and the edges between them.""" + nodes = self._execute(f'SELECT {_REFERENCE_SQL}, kind FROM {{schema}}.definitions WHERE NOT removed').fetchall() + states = graph.states(self._documents(removed=False)) + edges = self._execute('SELECT from_ref, to_ref, role FROM {schema}.edges ORDER BY 1, 2, 3').fetchall() + return {'nodes': [{'reference': reference, 'kind': kind, 'state': states[reference]} + for reference, kind in sorted(nodes)], + 'edges': [{'from': source, 'to': target, 'role': role} for source, target, role in edges]} + + def order(self): + """The references not removed, each after everything it uses (graph.order).""" + return graph.order(self._documents(removed=False)) + + def status(self): + """Unsaved and removed definitions, and files added, changed or missing on disk since the last import or save.""" + state = self._state() + rows = self._execute(f'SELECT {_REFERENCE_SQL}, file_sha256, unsaved, removed FROM {{schema}}.definitions').fetchall() + listing = _list_definitions(state['folder']) + recorded = {reference: sha for reference, sha, _, _ in rows if sha is not None} + return {'unsaved': sorted(reference for reference, _, unsaved, removed in rows if unsaved and not removed), + 'removed': sorted(reference for reference, _, _, removed in rows if removed), + 'added': sorted(set(listing.files) - set(recorded)), + 'changed': sorted(reference for reference, sha in listing.files.items() + if reference in recorded and recorded[reference] != sha), + 'missing': sorted(set(recorded) - set(listing.files)), + 'irregular': list(listing.irregular)} + + # ------------------------------------------------------------ editing + + def set_definition(self, reference, text): + """Validate text as the definition at reference and store it as an unsaved edit (4.4). + + It is checked alone (strict JSON, schema, kind against directory, card, + placeholders, paths into the code root) and against the project as it + would then be (references, named outputs, charts, cycles). Raises + ProjectError with code 'invalid' and the problems, changing nothing, + when any error is found. + """ + directory, name = _split(reference) + path = f'{reference}.json' + try: + document = documents.decode(text) + except documents.DocumentError as exc: + raise ProjectError(f'{reference} is not valid: {exc}', 'invalid', + problems=[Problem('error', path, '', str(exc))]) from None + state = self._state() + candidate = _definition(reference, text, document) + problems = [] + + def add(severity, where, pointer, message): + problems.append(Problem(severity, where, pointer, message)) + + check._check_definition(candidate, _notes(state['folder']), add) + code_root = os.path.realpath(os.path.join(state['folder'], state['code_root'])) + check._check_code_paths(candidate, code_root if os.path.isdir(code_root) else None, add) + alone = _errors(problems) + with self._connection.transaction(): + merged = self._merged_definitions() + merged[reference] = candidate + errors = alone + _errors(_cross_problems(merged, {path} if alone else ())) + if errors: + raise ProjectError(f'{reference} cannot be set; see the problems.', 'invalid', problems=errors, + references=[reference]) + self._execute('''INSERT INTO {schema}.definitions + (directory, name, kind, title, text, document, unsaved, removed) + VALUES (%s, %s, %s, %s, %s, %s, true, false) + ON CONFLICT (directory, name) DO UPDATE SET + kind = EXCLUDED.kind, title = EXCLUDED.title, text = EXCLUDED.text, + document = EXCLUDED.document, removed = false, + unsaved = {schema}.definitions.unsaved OR {schema}.definitions.removed + OR {schema}.definitions.text IS DISTINCT FROM EXCLUDED.text''', + (directory, name, candidate.kind, document['title'], text, Jsonb(document))) + self._write_edges(graph.edges({reference: document}), [reference]) + + def remove_definition(self, reference): + """Mark a definition removed, to be deleted from disk by save(); refused while anything uses it.""" + directory, name = _split(reference) + with self._connection.transaction(): + row = self._execute('SELECT file_sha256 FROM {schema}.definitions ' + 'WHERE directory = %s AND name = %s AND NOT removed FOR UPDATE', + (directory, name)).fetchone() + if row is None: + raise ProjectError(f'There is no definition {reference}.', 'not-found', references=[reference]) + users = [source for (source,) in self._execute( + 'SELECT DISTINCT from_ref FROM {schema}.edges WHERE to_ref = %s ORDER BY 1', (reference,))] + if users: + raise ProjectError(f'{reference} is used by {", ".join(users)}; change those first.', 'in-use', + references=users) + if row[0] is None: + # Never written to disk: there is no file for save() to delete. + self._execute('DELETE FROM {schema}.definitions WHERE directory = %s AND name = %s', (directory, name)) + else: + self._execute('UPDATE {schema}.definitions SET removed = true WHERE directory = %s AND name = %s', + (directory, name)) + self._write_edges([], [reference]) + + def save(self): + """Write unsaved definitions to their files and delete the files of removed ones (4.4). + + Before anything is written, every file to be replaced or deleted must + still have the SHA-256 recorded at import or last save (or already hold + exactly the text to be written, which is what an interrupted save + leaves). Otherwise nothing is written and ProjectError (code + changed-on-disk) names them. Returns the references written and deleted. + """ + root = self._state()['folder'] + rows = self._execute(f'SELECT {_REFERENCE_SQL}, text, file_sha256, removed FROM {{schema}}.definitions ' + 'WHERE unsaved OR removed ORDER BY 1').fetchall() + changed = [] + for reference, text, file_sha256, removed in rows: + current = _file_sha(root, reference) + done = None if removed else _sha(text.encode('utf-8')) + if current != file_sha256 and current != done: + changed.append(reference) + if changed: + raise ProjectError('These files changed on disk since they were imported: ' + ', '.join(changed) + + '. Open the project again to take or keep the changes.', 'changed-on-disk', + references=changed) + written, deleted = [], [] + for reference, text, _, removed in rows: + if removed: + _delete_file(root, reference) + deleted.append(reference) + else: + _write_file(root, reference, text.encode('utf-8')) + written.append(reference) + with self._connection.transaction(): + with self._connection.cursor() as cursor: + if written: + cursor.executemany(self._sql('UPDATE {schema}.definitions SET unsaved = false, ' + 'file_sha256 = encode(sha256(convert_to(text, \'UTF8\')), \'hex\') ' + 'WHERE directory = %s AND name = %s'), + [documents.parse_reference(reference) for reference in written]) + if deleted: + cursor.executemany(self._sql('DELETE FROM {schema}.definitions WHERE directory = %s AND name = %s'), + [documents.parse_reference(reference) for reference in deleted]) + return {'written': written, 'deleted': deleted} + + def close(self): + """Close the connection, which also releases the project's lock.""" + self._connection.close() + + def __enter__(self): + return self + + def __exit__(self, *exc): + self.close() + + +# --------------------------------------------------------------- files + +def _file_sha(root, reference): + """SHA-256 of the definition file on disk, None when it does not exist, 'unreadable' when it is not a plain file.""" + directory, name = documents.parse_reference(reference) + try: + fd = os.open(os.path.join(root, directory), folder_reader._DIRECTORY_FLAGS) + except FileNotFoundError: + return None + except OSError: + return 'unreadable' + try: + return _sha(folder_reader._read(fd, f'{name}.json', folder_reader.DEFINITION_LIMIT)) + except folder_reader._Unsafe: + if not os.path.lexists(os.path.join(root, directory, f'{name}.json')): + return None + return 'unreadable' + finally: + os.close(fd) + + +def _write_file(root, reference, data): + """Replace the file atomically: a temporary file in the same directory, fsync, rename, fsync the directory.""" + directory, name = documents.parse_reference(reference) + target_directory = os.path.join(root, directory) + os.makedirs(target_directory, exist_ok=True) + fd, temporary = tempfile.mkstemp(dir=target_directory, prefix=f'.{name}.', suffix='.tmp') + try: + with os.fdopen(fd, 'wb') as handle: + handle.write(data) + handle.flush() + os.fsync(handle.fileno()) + os.chmod(temporary, 0o644) + os.replace(temporary, os.path.join(target_directory, f'{name}.json')) + except BaseException: + if os.path.lexists(temporary): + os.unlink(temporary) + raise + _sync_directory(target_directory) + + +def _delete_file(root, reference): + directory, name = documents.parse_reference(reference) + target_directory = os.path.join(root, directory) + try: + os.unlink(os.path.join(target_directory, f'{name}.json')) + except FileNotFoundError: + return + _sync_directory(target_directory) + + +def _sync_directory(path): + fd = os.open(path, os.O_RDONLY | os.O_DIRECTORY | os.O_CLOEXEC) + try: + os.fsync(fd) + finally: + os.close(fd) From 22e89b9f33947951cd2645b685b55ac2a6322172 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Tue, 10 Nov 2026 15:00:45 -0700 Subject: [PATCH 008/131] feat(project): command line for opening, reading and editing a project python -m tuldok_project gains open, list, show, graph, status, set, remove, save and forget on top of the store. Each command opens the project (which imports any change on disk), does its work and releases the project's lock before it exits; reading commands take --json. The helpers the store shares with the reader and the checker are public names now. The contract describes the commands, and the ledger records milestone 2: the lab's 263 definitions open in under a second. Co-Authored-By: Claude Fable 5.2 --- docs/contracts/project-folder.md | 70 ++++- .../execution-ledger.md | 40 +++ tests/test_tuldok_project_cli.py | 272 ++++++++++++++++ tuldok_project/__main__.py | 292 +++++++++++++++++- tuldok_project/check.py | 25 +- tuldok_project/folder.py | 41 +-- tuldok_project/store.py | 32 +- 7 files changed, 714 insertions(+), 58 deletions(-) create mode 100644 tests/test_tuldok_project_cli.py diff --git a/docs/contracts/project-folder.md b/docs/contracts/project-folder.md index 26006907..c871b2b3 100644 --- a/docs/contracts/project-folder.md +++ b/docs/contracts/project-folder.md @@ -544,9 +544,77 @@ One mistake is reported once. A reference into the wrong directory is reported b the field's own rule and not again as a missing definition, and a chart is not compared with a benchmark that has errors of its own. +## Working with the database copy + +Tuldok keeps a working copy of a project folder in Postgres: the exact text of +every definition, the uses between them, and edits that are not yet written back +to the folder. Each project has its own schema, `project_`, named after the +`id` in `tuldok.json`. These commands work on that copy: + +```sh +.venv/bin/python -m tuldok_project COMMAND FOLDER [options] +``` + +| Command | Does | +| --- | --- | +| `open` | Imports the folder into the database, or attaches to the copy when no definition file changed. Prints the number of definitions of each kind and in each state, and how long opening took. | +| `list [--kind K]` | Prints each definition's reference, state and title, one per line. `--kind` keeps one kind. | +| `show REFERENCE` | Prints a definition's reference, title, kind and state, what it uses and what uses it (each with its role), then the definition's text. | +| `graph [--order]` | Prints every definition with its kind and state, then every use as `from role to`. `--order` instead prints the build order: each definition after everything it uses, with its state. | +| `status` | Lists definitions edited or removed in the database and not yet saved, and definition files added, changed or missing on disk since the last import. | +| `set REFERENCE FILE` | Replaces or adds the definition at `REFERENCE` with the text of `FILE`, in the database only. The text is checked on its own and against the rest of the project; an edit with any error is refused and changes nothing. | +| `remove REFERENCE` | Removes the definition in the database only. It is refused while another definition uses it. | +| `save` | Writes every unsaved definition to its file and deletes the files of removed ones. It writes nothing when one of those files changed on disk since it was imported, and names them. | +| `forget` | Drops the project's copy from the database, including unsaved edits. The folder is not touched. | + +Every command except `forget` opens the project first, which imports anything +that changed on disk, so `list`, `show`, `graph` and `status` always describe the +folder as it is now plus the unsaved edits. Opening runs the same check as +`check`; a folder with errors is not imported and the database is left as it was. + +A state is worked out from the definitions, never stored in a file: + +| State | When | +| --- | --- | +| `cannot-rebuild` | its `earlier_work.rebuild` is `no`, or something it uses through an input, directly or further up, is `cannot-rebuild` | +| `needs-work` | not `cannot-rebuild`, and its `earlier_work.rebuild` is `needs-work` or something it uses through an input is `needs-work` | +| `not-built` | any other dataset, recipe, benchmark or step | +| `not-set-up` | an environment | +| `none` | a model or a chart | + +Options: + +| Option | Commands | Meaning | +| --- | --- | --- | +| `--database-url URL` | all but `check` | The Postgres database. Without it, the `TULDOK_DATABASE_URL` environment variable is used; with neither, the command stops with exit status 2. | +| `--json` | `open`, `list`, `show`, `graph`, `status`, `save` | Print one JSON document with the same content as the text. | +| `--rebind` | all that open | The copy is bound to the folder it was first opened from. Opening the same project from another path is refused unless `--rebind` is given, which binds the copy to the new path. | +| `--keep` | all that open | Where a file changed on disk and the same definition has unsaved edits, keep the edits; the changed file becomes the version that `save` replaces. | +| `--discard` | all that open | Where a file changed on disk and the same definition has unsaved edits, drop the edits and take the file. | + +Without `--keep` or `--discard`, such a conflict is refused and names the +definitions concerned. + +An open project holds a lock in the database, so one command at a time works on +a project. Each command releases the lock before it exits. A command started +while the project is open elsewhere is refused. + +The exit status is 0 when the command did its work, 1 when it was refused (the +folder has errors, an edit is not valid, a definition is in use or missing, a +conflict, a file changed on disk, the project is open elsewhere) or the database +failed, and 2 for a usage error, including a missing database setting or a `set` +file that cannot be read. A refusal is printed on standard error as one sentence, +followed by any problems in the same form `check` prints them: + +``` +datasets/waves cannot be set; see the problems. +error datasets/waves.json /title Add the required field 'title'. +``` + ## What the format does not do yet -The folder is checked, nothing more. Tuldok does not yet run any command, +The folder is checked and can be opened, edited and saved through the database +copy, nothing more. Tuldok does not yet run any command, estimate, install an environment, compare installed package versions, write settings files, import results files or read the contents of notes. The `run`, `resources`, `estimate`, `install` and `settings` fields record what a later Tuldok will use. diff --git a/docs/plans/definition-first-projects/execution-ledger.md b/docs/plans/definition-first-projects/execution-ledger.md index b0550683..8c246d92 100644 --- a/docs/plans/definition-first-projects/execution-ledger.md +++ b/docs/plans/definition-first-projects/execution-ledger.md @@ -34,3 +34,43 @@ Command for the Tuldok tests: `.venv/bin/python -m unittest discover -s tests -p **Lab changes the new-work definitions need** (for milestones 4 and 6): a `--json` option on `surrogate.datasets plan`; the benchmark result in Tuldok's results format; `spectral-composition` cannot run on a fresh clone; no lock file yet for the GPU environment; the reference solver needs Rust, which the format's environments do not describe. **Remaining in milestone 1:** slice D1, the format contract under `docs/contracts/`, after the owner has read the folder. + +## 2026-11-10 — milestone 1 follow-up and milestone 2, open and save + +**Owner decisions:** bring the earlier runs' code into the lab; keep the authored comparisons; commit on branches, no push and nothing on `main`; start milestone 2. + +**Commits** (none pushed). Tuldok `feat/definition-first-projects`: plan and spec `d55903f8`, checker and summaries `3297f8dd`, format contract `3e787e06`, store `e027ed3f`, then the commands. Lab `reorg/reproducible-lab-20261102`: folder and build script `d0df92180`, earlier run code and comparisons `89cac8b4d`. + +| Slice | Files | Result | +| --- | --- | --- | +| L2 earlier code (lab) | `lab:earlier-run-code/` (184 files, 1.6 MB), `lab:projects/surrogate-lab/notes/model-groups-and-comparisons.json`, build script and tests | 26 tests pass; `--check` passes; checker 0 errors, 8 warnings (sources of two recipes that are not on this machine) | +| D1 contract | `docs/contracts/project-folder.md`, link in `docs/README.md` | every example in it passes the checker | +| T3, T4 store | `tuldok_project/store.py`, `graph.states`, `tests/test_tuldok_project_store.py` | 37 tests. Independent check: bad edit refused, removal of a used definition refused, save refused after the file changed on disk, reopen with that conflict refused until told to discard, no schema left behind | +| T5 commands | `tuldok_project/__main__.py`, `tests/test_tuldok_project_cli.py`; helpers shared with the store made public in `folder.py` and `check.py` | 16 tests | +| T6 lab check | timing below | targets met | + +Command for all tests: `.venv/bin/python -m unittest discover -s tests -p 'test_tuldok_project_*.py'` with `TULDOK_DATABASE_URL` set to a disposable cluster (168 tests, 16 s; 45 are skipped without a database). + +**Milestone 2 acceptance, on the lab folder** (263 definitions, 2,266 edges): + +| Command | Whole process | Reported by `open` | Target | +| --- | --- | --- | --- | +| first `open`, empty database | 0.93 s | 0.72 s | under 10 s | +| second `open`, nothing changed | 0.20 s | 0.01 s | under 1 s | +| `list`, `graph --order` | 0.2 s each | | | + +States: 216 cannot be rebuilt, 27 need work, 17 not built, 2 environments not set up, 1 model. + +**Earlier models after L2.** With their code in Git, 158 of the 205 are `needs-work` on their own label and 47 are `no` (25 start from weights whose producing model is not identified, 18 miss only arrays or an archive, 2 have no command, 2 name scripts not on this machine). Carried through inputs, 27 need work and 178 cannot be rebuilt, because most read a training set that cannot be rebuilt. + +**Accepted as implemented:** + +- A `Project` holds a session advisory lock while open; a second open, or `forget`, is refused as busy. +- The schema is created inside the import transaction, so a failed first open leaves nothing behind. +- The unchanged-folder fast path compares SHA-256 of definition files only. It does not see changed `results/*.csv`, notes or stray entries; milestone 3 must add results files to it. +- `keep` on a conflict keeps the database text and records the file's new digest, so the next save overwrites the file on purpose. +- `save` accepts a file that already holds the text to be written, so an interrupted save can be retried. +- Every command opens the project first, so the command-line `status` never shows pending disk changes; a conflict appears as a refusal. `Project.status()` remains meaningful for a long-lived process. +- Two settings files copied into `earlier-run-code/` (`fine-tuning.json`, `distillation.json`) carry per-tensor checksums of starting or teacher weights. They are kept as settings; the owner can reverse this in the build script's table. + +**For milestone 3:** import `results/*.csv` into summary tables; result rows from runs; saved charts; the first changes to existing Tuldok files (`app.py`, `agent_api.py`) to serve the new core, with its own start-up flag, route prefix and agent profile. diff --git a/tests/test_tuldok_project_cli.py b/tests/test_tuldok_project_cli.py new file mode 100644 index 00000000..98ca0f55 --- /dev/null +++ b/tests/test_tuldok_project_cli.py @@ -0,0 +1,272 @@ +"""The command line, `python -m tuldok_project FOLDER` (spec section 4.6), run as a child process. + +Database tests run only when TULDOK_DATABASE_URL names a disposable cluster +(see docs/plans/definition-first-projects/spec-m1-m2.md, section 1). Each test +copies tests/fixtures/tuldok_project/minimal into a temporary directory, gives +it a fresh project id and drops that project's schema afterwards. The tests +check the text a person reads, that --json parses, the exit statuses, and +that every command leaves the project closed. +""" +import json +import os +from pathlib import Path +import shutil +import subprocess +import sys +import tempfile +import unittest +import uuid + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) + +import psycopg # noqa: E402 + +from metadata import connection_info # noqa: E402 +from tuldok_project import store # noqa: E402 + +REPOSITORY = Path(__file__).resolve().parents[1] +FIXTURE = REPOSITORY / 'tests' / 'fixtures' / 'tuldok_project' / 'minimal' +DATABASE = os.environ.get('TULDOK_DATABASE_URL') + + +def run(*arguments, database=True, stdin=None): + """Run the command line; return the CompletedProcess with text stdout and stderr.""" + environment = dict(os.environ, PYTHONDONTWRITEBYTECODE='1') + if not database: + environment.pop('TULDOK_DATABASE_URL', None) + return subprocess.run([sys.executable, '-m', 'tuldok_project', *map(str, arguments)], cwd=REPOSITORY, + env=environment, input=stdin, capture_output=True, text=True, timeout=120) + + +class FolderCase(unittest.TestCase): + """A fresh copy of the fixture with its own project id.""" + + def setUp(self): + directory = tempfile.TemporaryDirectory() + self.addCleanup(directory.cleanup) + self.temporary = Path(directory.name) + shutil.copytree(FIXTURE, self.temporary / 'minimal') + self.folder = self.temporary / 'minimal' / 'project' + self.project_id = uuid.uuid4().hex + project_file = self.folder / 'tuldok.json' + document = json.loads(project_file.read_text(encoding='utf-8')) + document['id'] = self.project_id + project_file.write_text(json.dumps(document, indent=2) + '\n', encoding='utf-8') + self.schema = f'project_{self.project_id}' + + def run_ok(self, *arguments): + done = run(*arguments) + self.assertEqual(done.returncode, 0, done.stderr) + self.assertEqual(done.stderr, '') + return done.stdout + + def run_json(self, *arguments): + return json.loads(self.run_ok(*arguments, '--json')) + + +class WithoutDatabase(FolderCase): + + def test_check_still_works_without_a_database(self): + done = run('check', self.folder, database=False) + self.assertEqual(done.returncode, 0, done.stdout) + self.assertTrue(done.stdout.endswith(f'0 errors, 0 warnings in {self.folder}\n')) + report = json.loads(run('check', self.folder, '--json', database=False).stdout) + self.assertTrue(report['ok']) + + def test_store_commands_need_a_database(self): + for arguments in (('open', self.folder), ('list', self.folder), ('show', self.folder, 'models/stepper'), + ('graph', self.folder), ('status', self.folder), ('save', self.folder), + ('forget', self.folder)): + done = run(*arguments, database=False) + self.assertEqual(done.returncode, 2, arguments) + self.assertIn('--database-url', done.stderr) + self.assertIn('TULDOK_DATABASE_URL', done.stderr) + self.assertEqual(done.stdout, '') + + def test_usage_errors_exit_2(self): + for arguments in (('list',), ('frobnicate', self.folder), ('list', self.folder, '--kind', 'thing'), + ('open', self.folder, '--keep', '--discard'), ('show', self.folder)): + done = run(*arguments) + self.assertEqual(done.returncode, 2, arguments) + self.assertIn('usage:', done.stderr) + + +@unittest.skipUnless(DATABASE, 'TULDOK_DATABASE_URL is not set; database tests need a disposable cluster.') +class StoreCommands(FolderCase): + + def setUp(self): + super().setUp() + self.addCleanup(store.drop_project, self.project_id) + + def schema_exists(self): + with psycopg.connect(connection_info(), autocommit=True) as connection: + return connection.execute('SELECT 1 FROM pg_namespace WHERE nspname = %s', + (self.schema,)).fetchone() is not None + + def write_definition(self, path, change): + """Write a changed copy of a fixture definition to path and return the text.""" + document = json.loads((self.folder / 'datasets' / 'waves.json').read_text(encoding='utf-8')) + change(document) + text = json.dumps(document, indent=2) + '\n' + path.write_text(text, encoding='utf-8') + return text + + def test_open_prints_counts_and_time_then_attaches(self): + output = self.run_ok('open', self.folder) + lines = output.splitlines() + self.assertRegex(lines[0], rf'^Opened Minimal surrogate project \({self.project_id}\) from .* in \d+\.\d\d s\.$') + self.assertIn('kind count', lines) + self.assertIn('recipe 3', lines) + self.assertIn('total 10', lines) + self.assertIn('state count', lines) + self.assertIn('cannot-rebuild 1', lines) + self.assertTrue(self.schema_exists()) + again = self.run_json('open', self.folder) + self.assertEqual(again['project_id'], self.project_id) + self.assertEqual(again['kinds']['recipe'], 3) + self.assertEqual(again['states'], {'cannot-rebuild': 1, 'none': 3, 'not-built': 5, 'not-set-up': 1}) + self.assertIsInstance(again['seconds'], float) + + def test_list(self): + lines = self.run_ok('list', self.folder).splitlines() + self.assertEqual(len(lines), 10) + self.assertEqual(lines[0].split(None, 2), ['benchmarks/rollout', 'not-built', 'Rollout error']) + self.assertEqual(len({line.index('not-built') for line in lines if ' not-built ' in line}), 1) # aligned + rows = self.run_json('list', self.folder, '--kind', 'recipe') + self.assertEqual([row['reference'] for row in rows], + ['recipes/early-fit', 'recipes/stepper-k1', 'recipes/stepper-k2']) + self.assertEqual(rows[0]['state'], 'cannot-rebuild') + + def test_show(self): + output = self.run_ok('show', self.folder, 'datasets/waves') + head, text = output.split('\n\n', 1) + lines = head.splitlines() + self.assertEqual(lines[:4], ['reference datasets/waves', 'title Wave scenes', 'kind dataset', + 'state not-built']) + self.assertIn('uses steps/solver input:solver', lines) + self.assertIn('used by recipes/stepper-k1 input:training', lines) + self.assertEqual(text, (self.folder / 'datasets' / 'waves.json').read_text(encoding='utf-8')) + shown = self.run_json('show', self.folder, 'models/stepper') + self.assertEqual(shown['uses'], []) + self.assertIn({'reference': 'recipes/stepper-k1', 'role': 'model'}, shown['used_by']) + self.assertEqual(shown['document']['kind'], 'model') + + def test_show_of_a_missing_definition_exits_1(self): + done = run('show', self.folder, 'datasets/nothing') + self.assertEqual(done.returncode, 1) + self.assertEqual(done.stderr, 'There is no definition datasets/nothing.\n') + + def test_graph_and_order(self): + nodes, edges = self.run_ok('graph', self.folder).split('\n\n') + self.assertEqual(len(nodes.splitlines()), 10) + self.assertIn('recipes/stepper-k2 input:start recipes/stepper-k1', edges.splitlines()) + drawn = self.run_json('graph', self.folder) + self.assertEqual(len(drawn['nodes']), 10) + self.assertEqual(len(drawn['edges']), len(edges.splitlines())) + order = [line.split() for line in self.run_ok('graph', self.folder, '--order').splitlines()] + references = [reference for reference, _ in order] + self.assertLess(references.index('steps/solver'), references.index('datasets/waves')) + self.assertIn(['recipes/early-fit', 'cannot-rebuild'], order) + self.assertEqual([item['reference'] for item in self.run_json('graph', self.folder, '--order')], references) + + def test_set_status_save(self): + edit = self.temporary / 'waves.json' + text = self.write_definition(edit, lambda d: d.update(title='Waves, edited')) + self.assertIn('run save', self.run_ok('set', self.folder, 'datasets/waves', edit)) + self.assertEqual(self.run_ok('status', self.folder), 'unsaved datasets/waves\n') + self.assertEqual(self.run_json('status', self.folder)['unsaved'], ['datasets/waves']) + self.assertIn('not-built (unsaved)', self.run_ok('list', self.folder)) + self.assertEqual(self.run_ok('save', self.folder), 'wrote datasets/waves\n') + self.assertEqual((self.folder / 'datasets' / 'waves.json').read_text(encoding='utf-8'), text) + self.assertEqual(self.run_json('save', self.folder), {'written': [], 'deleted': []}) + self.assertEqual(self.run_ok('status', self.folder), + 'Nothing is unsaved and no file changed on disk since the last import.\n') + + def test_refused_edit_prints_its_problems_and_changes_nothing(self): + before = self.run_json('show', self.folder, 'datasets/waves') + edit = self.temporary / 'waves.json' + self.write_definition(edit, lambda d: (d.pop('title'), d['run']['inputs'].update(more='steps/nothing'))) + done = run('set', self.folder, 'datasets/waves', edit) + self.assertEqual(done.returncode, 1) + self.assertEqual(done.stdout, '') + lines = done.stderr.splitlines() + self.assertEqual(lines[0], 'datasets/waves cannot be set; see the problems.') + self.assertTrue(any(line.startswith('error datasets/waves.json - ') or + line.startswith('error datasets/waves.json /title ') for line in lines[1:]), lines) + self.assertTrue(any(line.startswith('error datasets/waves.json /run/inputs/more ') for line in lines), lines) + self.assertEqual(self.run_json('show', self.folder, 'datasets/waves'), before) + not_json = self.temporary / 'broken.json' + not_json.write_text('{"format": ', encoding='utf-8') + self.assertEqual(run('set', self.folder, 'datasets/waves', not_json).returncode, 1) + missing = run('set', self.folder, 'datasets/waves', self.temporary / 'absent.json') + self.assertEqual(missing.returncode, 2) + self.assertIn('cannot be read', missing.stderr) + + def test_remove_in_use_is_refused_and_unused_is_saved_as_a_deletion(self): + done = run('remove', self.folder, 'steps/solver') + self.assertEqual(done.returncode, 1) + self.assertEqual(done.stderr, 'steps/solver is used by datasets/waves; change those first.\n') + self.assertIn('run save', self.run_ok('remove', self.folder, 'charts/speed-accuracy')) + self.assertEqual(self.run_ok('status', self.folder), 'removed charts/speed-accuracy\n') + self.assertEqual(self.run_ok('save', self.folder), 'deleted charts/speed-accuracy\n') + self.assertFalse((self.folder / 'charts' / 'speed-accuracy.json').exists()) + + def test_folder_with_errors_is_refused_with_its_problems(self): + path = self.folder / 'datasets' / 'waves.json' + document = json.loads(path.read_text(encoding='utf-8')) + document.pop('title') + path.write_text(json.dumps(document), encoding='utf-8') + done = run('list', self.folder) + self.assertEqual(done.returncode, 1) + self.assertEqual(done.stdout, '') + self.assertIn('has errors', done.stderr.splitlines()[0]) + self.assertIn('error datasets/waves.json ', done.stderr) + self.assertFalse(self.schema_exists()) + + def test_conflict_needs_keep_or_discard(self): + edit = self.temporary / 'waves.json' + self.write_definition(edit, lambda d: d.update(title='Edited here')) + self.run_ok('set', self.folder, 'datasets/waves', edit) + self.write_definition(self.folder / 'datasets' / 'waves.json', lambda d: d.update(title='Edited on disk')) + done = run('open', self.folder) + self.assertEqual(done.returncode, 1) + self.assertIn('datasets/waves', done.stderr) + self.assertEqual(self.run_json('show', self.folder, 'datasets/waves', '--keep')['title'], 'Edited here') + # --keep took the disk version as the new base, so the edit stays unsaved and no conflict remains. + self.write_definition(self.folder / 'datasets' / 'waves.json', lambda d: d.update(title='Edited again')) + self.assertEqual(run('list', self.folder).returncode, 1) + self.run_ok('open', self.folder, '--discard') + self.assertEqual(self.run_json('show', self.folder, 'datasets/waves')['title'], 'Edited again') + + def test_a_moved_folder_needs_rebind(self): + self.run_ok('open', self.folder) + moved = self.temporary / 'moved' + shutil.copytree(self.temporary / 'minimal', moved) + done = run('list', moved / 'project') + self.assertEqual(done.returncode, 1) + self.assertIn('rebind', done.stderr) + self.assertEqual(len(self.run_json('list', moved / 'project', '--rebind')), 10) + + def test_open_elsewhere_is_busy_and_every_command_releases_the_lock(self): + for arguments in (('open',), ('list',), ('show', 'models/stepper'), ('graph',), ('status',), ('save',)): + self.run_ok(arguments[0], self.folder, *arguments[1:]) + held = store.open_project(self.folder) # would raise 'busy' if a command had kept the lock + try: + done = run('list', self.folder) + self.assertEqual(done.returncode, 1) + self.assertEqual(done.stderr, 'This project is already open in another session.\n') + self.assertEqual(run('forget', self.folder).returncode, 1) + finally: + held.close() + + def test_forget_drops_the_copy_and_leaves_the_folder(self): + self.run_ok('open', self.folder) + files = sorted(path.relative_to(self.folder) for path in self.folder.rglob('*')) + self.assertIn('holds no copy', self.run_ok('forget', self.folder)) + self.assertFalse(self.schema_exists()) + self.assertEqual(sorted(path.relative_to(self.folder) for path in self.folder.rglob('*')), files) + self.assertIn('holds no copy', self.run_ok('forget', self.folder)) # forgetting twice is fine + + +if __name__ == '__main__': + unittest.main() diff --git a/tuldok_project/__main__.py b/tuldok_project/__main__.py index 4444f085..65a2c52d 100644 --- a/tuldok_project/__main__.py +++ b/tuldok_project/__main__.py @@ -1,15 +1,31 @@ -"""Command line for project folders: `python -m tuldok_project check FOLDER [--no-code] [--json]`. +"""Command line for project folders: `python -m tuldok_project FOLDER ...`. -Owns the command-line surface of the package: parsing arguments, printing a -check report as text lines or JSON, and the exit status (0 no errors, 1 errors, -2 usage error). The checking itself is check.check_folder. +Owns the command-line surface of the package: parsing arguments, printing +reports as aligned text for a person or as one JSON document, and the exit +status (0 done, 1 refused or failed, 2 usage error). `check` reads the folder +alone (check.check_folder). Every other command works on the folder's database +copy through store.open_project: it opens the project (importing what changed +on disk), does its one piece of work and closes the Project before exiting, so +the project's lock is never held past the command. """ import argparse import json +import os import sys +import time +from . import documents, folder as folder_reader from .check import check_folder +DATABASE_VARIABLE = 'TULDOK_DATABASE_URL' +KINDS = tuple(sorted(documents.KINDS.values())) + + +class UsageError(Exception): + """A command that cannot start as given; exit status 2.""" + + +# ------------------------------------------------------------- arguments def _parser(): parser = argparse.ArgumentParser(prog='python -m tuldok_project', @@ -19,28 +35,282 @@ def _parser(): check.add_argument('folder', help='the project folder (the one holding tuldok.json)') check.add_argument('--no-code', action='store_true', help='do not look up paths in the code root') check.add_argument('--json', action='store_true', help='print the report as one JSON object') + + database = argparse.ArgumentParser(add_help=False) + database.add_argument('folder', help='the project folder (the one holding tuldok.json)') + database.add_argument('--database-url', help=f'the Postgres database; default ${DATABASE_VARIABLE}') + + opening = argparse.ArgumentParser(add_help=False, parents=[database]) + opening.add_argument('--rebind', action='store_true', + help='take the copy over from the folder it is bound to and bind it to this one') + conflict = opening.add_mutually_exclusive_group() + conflict.add_argument('--keep', dest='on_conflict', action='store_const', const='keep', + help='where a file changed on disk and has unsaved edits here, keep the edits') + conflict.add_argument('--discard', dest='on_conflict', action='store_const', const='discard', + help='where a file changed on disk and has unsaved edits here, take the file') + + reading = argparse.ArgumentParser(add_help=False, parents=[opening]) + reading.add_argument('--json', action='store_true', help='print one JSON document') + + def add(name, parents, help_text): + return commands.add_parser(name, parents=parents, help=help_text, description=help_text) + + add('open', [reading], 'import the folder into the database, or attach to it when nothing changed') + listing = add('list', [reading], 'list the definitions with their state') + listing.add_argument('--kind', choices=KINDS, help='only definitions of this kind') + show = add('show', [reading], 'show one definition, what it uses and what uses it') + show.add_argument('reference', help='for example recipes/pilot-dense-k1') + graph = add('graph', [reading], 'print the definitions with their state and the uses between them') + graph.add_argument('--order', action='store_true', help='print the build order instead') + add('status', [reading], 'list unsaved edits and files changed on disk since the last import') + setting = add('set', [opening], 'replace or add a definition in the database (not saved to the folder)') + setting.add_argument('reference', help='for example recipes/pilot-dense-k1') + setting.add_argument('file', help='the file holding the new definition text') + removing = add('remove', [opening], 'remove a definition in the database (not saved to the folder)') + removing.add_argument('reference', help='for example recipes/pilot-dense-k1') + add('save', [reading], 'write the unsaved edits to the folder') + add('forget', [database], "drop this project's copy from the database; the folder is not touched") return parser +# ----------------------------------------------------------------- output + def _plural(count, word): return f'{count} {word}' + ('' if count == 1 else 's') -def main(argv=None): - arguments = _parser().parse_args(argv) # exits with status 2 on a usage error +def _columns(rows): + """Print rows of strings as columns separated by two spaces, the last column unpadded.""" + rows = [[str(cell) for cell in row] for row in rows] + if not rows: + return + widths = [max((len(row[index]) for row in rows if index < len(row) - 1), default=0) + for index in range(max(map(len, rows)))] + for row in rows: + cells = [cell.ljust(widths[index]) for index, cell in enumerate(row[:-1])] + row[-1:] + print(' '.join(cells).rstrip()) + + +def _json(value): + json.dump(value, sys.stdout, indent=2, ensure_ascii=False, default=str) + sys.stdout.write('\n') + + +def _problem_line(problem): + return f'{problem.severity} {problem.path} {problem.pointer or "-"} {problem.message}' + + +def _marks(row): + return ' (removed)' if row['removed'] else ' (unsaved)' if row['unsaved'] else '' + + +# --------------------------------------------------------------- commands + +def _check(arguments): report = check_folder(arguments.folder, code=not arguments.no_code) errors, warnings = report.count('error'), report.count('warning') if arguments.json: - json.dump({'folder': report.folder, 'ok': report.ok, 'errors': errors, 'warnings': warnings, - 'problems': [problem.as_dict() for problem in report.problems]}, - sys.stdout, indent=2, ensure_ascii=False) - sys.stdout.write('\n') + _json({'folder': report.folder, 'ok': report.ok, 'errors': errors, 'warnings': warnings, + 'problems': [problem.as_dict() for problem in report.problems]}) else: for problem in report.problems: - print(f'{problem.severity} {problem.path} {problem.pointer or "-"} {problem.message}') + print(_problem_line(problem)) print(f'{_plural(errors, "error")}, {_plural(warnings, "warning")} in {report.folder}') return 0 if report.ok else 1 +def _open(project, arguments): + summary = project.summary() + if arguments.json: + _json({**summary, 'seconds': round(arguments.seconds, 3)}) + return 0 + total = sum(summary['kinds'].values()) + print(f'Opened {summary["name"]} ({summary["project_id"]}) from {summary["folder"]} in {arguments.seconds:.2f} s.') + print() + _columns([('kind', 'count'), *summary['kinds'].items(), ('total', total)]) + print() + _columns([('state', 'count'), *summary['states'].items()]) + return 0 + + +def _list(project, arguments): + rows = project.definitions(kind=arguments.kind) + if arguments.json: + _json(rows) + else: + _columns([(row['reference'], row['state'] + _marks(row), row['title']) for row in rows]) + return 0 + + +def _show(project, arguments): + shown = project.definition(arguments.reference) + if arguments.json: + _json(shown) + return 0 + rows = [('reference', shown['reference']), ('title', shown['title']), ('kind', shown['kind']), + ('state', shown['state'] + _marks(shown))] + rows += [('uses', use['reference'], use['role']) for use in shown['uses']] or [('uses', 'nothing')] + rows += [('used by', user['reference'], user['role']) for user in shown['used_by']] or [('used by', 'nothing')] + _columns(rows) + print() + sys.stdout.write(shown['text'] if shown['text'].endswith('\n') else shown['text'] + '\n') + return 0 + + +def _graph(project, arguments): + if arguments.order: + states = {node['reference']: node['state'] for node in project.graph()['nodes']} + order = [{'reference': reference, 'state': states[reference]} for reference in project.order()] + if arguments.json: + _json(order) + else: + _columns([(item['reference'], item['state']) for item in order]) + return 0 + drawn = project.graph() + if arguments.json: + _json(drawn) + return 0 + _columns([(node['reference'], node['kind'], node['state']) for node in drawn['nodes']]) + print() + _columns([(edge['from'], edge['role'], edge['to']) for edge in drawn['edges']]) + return 0 + + +_STATUS_WORDS = ( + ('unsaved', 'unsaved'), ('removed', 'removed'), ('added', 'added on disk'), + ('changed', 'changed on disk'), ('missing', 'missing on disk'), ('irregular', 'not a definition file'), +) + + +def _status(project, arguments): + status = project.status() + if arguments.json: + _json(status) + return 0 + rows = [(word, reference) for key, word in _STATUS_WORDS for reference in status[key]] + if rows: + _columns(rows) + else: + print('Nothing is unsaved and no file changed on disk since the last import.') + return 0 + + +def _set(project, arguments): + project.set_definition(arguments.reference, arguments.text) + print(f'Set {arguments.reference} in the database; run save to write it to the folder.') + return 0 + + +def _remove(project, arguments): + project.remove_definition(arguments.reference) + print(f'Removed {arguments.reference} in the database; run save to apply it to the folder.') + return 0 + + +def _save(project, arguments): + saved = project.save() + if arguments.json: + _json(saved) + return 0 + rows = [('wrote', reference) for reference in saved['written']] + rows += [('deleted', reference) for reference in saved['deleted']] + if rows: + _columns(rows) + else: + print('Nothing to save.') + return 0 + + +_STORE_COMMANDS = {'open': _open, 'list': _list, 'show': _show, 'graph': _graph, 'status': _status, + 'set': _set, 'remove': _remove, 'save': _save} + + +def _project_id(folder): + """The id in the folder's tuldok.json, without opening or checking anything else.""" + from .store import PROJECT_ID + + path = os.path.join(os.fspath(folder), folder_reader.PROJECT_FILE) + try: + root_fd = os.open(os.fspath(folder), os.O_RDONLY | os.O_DIRECTORY | os.O_CLOEXEC) + except OSError as exc: + raise UsageError(f'The project folder {folder} cannot be opened: {exc.strerror}.') from None + try: + document = documents.decode(folder_reader.read(root_fd, folder_reader.PROJECT_FILE, folder_reader.PROJECT_LIMIT)) + except (folder_reader.Unsafe, documents.DocumentError) as exc: + raise UsageError(f'{path} cannot be read: {exc}') from None + finally: + os.close(root_fd) + project_id = document.get('id') + if not isinstance(project_id, str) or not PROJECT_ID.fullmatch(project_id): + raise UsageError(f'{path} has no valid id; run check on the folder.') + return project_id + + +def _forget(arguments, dsn): + from . import store + + project_id = _project_id(arguments.folder) + store.drop_project(project_id, dsn) + print(f'The database holds no copy of project {project_id} now; the folder was not touched.') + return 0 + + +def _run_store(arguments, dsn): + from . import store + + if arguments.command == 'set': + try: + with open(arguments.file, 'rb') as handle: + arguments.text = handle.read().decode('utf-8') + except OSError as exc: + raise UsageError(f'{arguments.file} cannot be read: {exc.strerror}.') from None + except UnicodeDecodeError as exc: + raise UsageError(f'{arguments.file} is not UTF-8 text (bad byte at offset {exc.start}).') from None + started = time.monotonic() + project = store.open_project(arguments.folder, rebind=arguments.rebind, on_conflict=arguments.on_conflict, + dsn=dsn) + arguments.seconds = time.monotonic() - started + try: + return _STORE_COMMANDS[arguments.command](project, arguments) + finally: + project.close() + + +def _database_command(arguments): + import psycopg + from metadata import StorageError + from .store import ProjectError + + dsn = arguments.database_url or os.environ.get(DATABASE_VARIABLE) + if not dsn: + print(f'No database is set: pass --database-url or set {DATABASE_VARIABLE}.', file=sys.stderr) + return 2 + try: + if arguments.command == 'forget': + return _forget(arguments, dsn) + return _run_store(arguments, dsn) + except UsageError as exc: + print(str(exc), file=sys.stderr) + return 2 + except StorageError as exc: + print(f'The database setting is not usable: {exc}', file=sys.stderr) + return 2 + except ProjectError as exc: + print(str(exc), file=sys.stderr) + for problem in exc.problems: + print(_problem_line(problem), file=sys.stderr) + return 1 + except psycopg.Error as exc: + print(f'The database failed: {str(exc).strip() or type(exc).__name__}', file=sys.stderr) + return 1 + + +def main(argv=None): + arguments = _parser().parse_args(argv) # exits with status 2 on a usage error + if arguments.command == 'check': + return _check(arguments) + return _database_command(arguments) + + if __name__ == '__main__': sys.exit(main()) diff --git a/tuldok_project/check.py b/tuldok_project/check.py index 2d91a5e4..80b0626f 100644 --- a/tuldok_project/check.py +++ b/tuldok_project/check.py @@ -54,7 +54,7 @@ def add(severity, path, pointer, message): definitions = {definition.reference: definition for definition in read.definitions} for definition in read.definitions: if definition.document is not None: - _check_definition(definition, read.notes, add) + check_definition(definition, read.notes, add) # Single-file errors so far decide which benchmarks are sound enough to check results against. unsound = {problem.path for problem in problems if problem.severity == 'error'} @@ -62,11 +62,11 @@ def add(severity, path, pointer, message): code_root = _code_root(project, read.root, add) if code and project is not None else None for definition in read.definitions: if definition.document is not None: - _check_code_paths(definition, code_root, add) + check_code_paths(definition, code_root, add) - _check_references(definitions, add) - _check_charts(definitions, unsound, add) - _check_cycles(definitions, add) + check_references(definitions, add) + check_charts(definitions, unsound, add) + check_cycles(definitions, add) _check_results(read.results, definitions, unsound, add) problems.sort(key=lambda p: (p.path, p.pointer, _SEVERITY_ORDER.get(p.severity, 2), p.message)) @@ -76,7 +76,8 @@ def add(severity, path, pointer, message): # ------------------------------------------------------- one definition -def _check_definition(definition, notes, add): +def check_definition(definition, notes, add): + """Report the single-file rules of one decoded definition: schema, kind, card, placeholders, benchmark rules.""" document, path = definition.document, definition.path for pointer, message in documents.schema_problems(definition.kind, document): add('error', path, pointer, message) @@ -198,7 +199,8 @@ def sources(holder, *prefix): yield '/install/requirements', install['requirements'] -def _check_code_paths(definition, code_root, add): +def check_code_paths(definition, code_root, add): + """Report code-root paths in one definition that are malformed, escape the code root or do not exist (None skips lookups).""" document, path = definition.document, definition.path missing = 'warning' if 'earlier_work' in document else 'error' for pointer, value in _code_paths(document): @@ -219,7 +221,8 @@ def _check_code_paths(definition, code_root, add): # ----------------------------------------------------------- across files -def _check_references(definitions, add): +def check_references(definitions, add): + """Report references to missing definitions and named outputs their producer does not declare.""" for definition in definitions.values(): for use in graph.uses(definition.document): if not graph.is_wellformed(use): @@ -247,7 +250,8 @@ def _sound_benchmark(chart, definitions, unsound): return target.document -def _check_charts(definitions, unsound, add): +def check_charts(definitions, unsound, add): + """Report chart metrics, subjects and groups missing from their benchmark (benchmarks whose path is in unsound are skipped).""" for definition in definitions.values(): chart = definition.document if definition.kind != 'chart' or not isinstance(chart, dict): @@ -276,7 +280,8 @@ def _check_charts(definitions, unsound, add): f'{reference} does not group its summary by {chart["group"]!r}; use one of its summary.group_by.') -def _check_cycles(definitions, add): +def check_cycles(definitions, add): + """Report every definition that is part of a cycle of uses.""" decoded = {reference: d.document for reference, d in definitions.items() if d.document is not None} for group in graph.cycles(decoded): members = set(group) diff --git a/tuldok_project/folder.py b/tuldok_project/folder.py index a141c06f..78c5fe01 100644 --- a/tuldok_project/folder.py +++ b/tuldok_project/folder.py @@ -25,7 +25,8 @@ RESULTS = 'results' NOTES = 'notes' -_DIRECTORY_FLAGS = os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW | os.O_CLOEXEC +# Flags for opening a directory without following a symbolic link. +DIRECTORY_FLAGS = os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW | os.O_CLOEXEC _FILE_FLAGS = os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK | os.O_CLOEXEC @@ -64,24 +65,24 @@ class Folder: problems: list = field(default_factory=list) -class _Unsafe(Exception): +class Unsafe(Exception): """A file that the format does not allow; the message is one sentence for the owner.""" -def _read(directory_fd, name, limit): +def read(directory_fd, name, limit): """Return the bytes of a regular file, refusing links, other file types and oversize files.""" try: fd = os.open(name, _FILE_FLAGS, dir_fd=directory_fd) except OSError as exc: if exc.errno == errno.ELOOP: - raise _Unsafe('This is a symbolic link; replace it with a regular file.') from None - raise _Unsafe(f'The file cannot be opened: {exc.strerror}.') from None + raise Unsafe('This is a symbolic link; replace it with a regular file.') from None + raise Unsafe(f'The file cannot be opened: {exc.strerror}.') from None try: info = os.fstat(fd) if not stat.S_ISREG(info.st_mode): - raise _Unsafe('This is not a regular file; replace it with one.') + raise Unsafe('This is not a regular file; replace it with one.') if info.st_size > limit: - raise _Unsafe(f'The file is {info.st_size} bytes; the limit for this file is {limit} bytes.') + raise Unsafe(f'The file is {info.st_size} bytes; the limit for this file is {limit} bytes.') chunks, size = [], 0 while size <= limit: chunk = os.read(fd, min(1024 * 1024, limit + 1 - size)) @@ -90,13 +91,13 @@ def _read(directory_fd, name, limit): chunks.append(chunk) size += len(chunk) if size > limit: - raise _Unsafe(f'The file grew past the limit of {limit} bytes while it was read.') + raise Unsafe(f'The file grew past the limit of {limit} bytes while it was read.') return b''.join(chunks) finally: os.close(fd) -def _entries(directory_fd): +def entries(directory_fd): """Return (name, kind) for each entry, sorted; kind is 'file', 'directory', 'link' or 'other'.""" found = [] with os.scandir(directory_fd) as listing: @@ -122,8 +123,8 @@ def _wrong_type(kind, wanted): def _load(folder, directory_fd, name, path, limit, *, decode): """Read one file into a File, or record why not and return None.""" try: - raw = _read(directory_fd, name, limit) - except _Unsafe as exc: + raw = read(directory_fd, name, limit) + except Unsafe as exc: folder.problems.append(Problem('error', path, '', str(exc))) return None digest = hashlib.sha256(raw).hexdigest() @@ -143,7 +144,7 @@ def _load(folder, directory_fd, name, path, limit, *, decode): def _open_directory(folder, parent_fd, name, path): try: - return os.open(name, _DIRECTORY_FLAGS, dir_fd=parent_fd) + return os.open(name, DIRECTORY_FLAGS, dir_fd=parent_fd) except OSError as exc: folder.problems.append(Problem('error', path, '', f'The directory cannot be opened: {exc.strerror}.')) return None @@ -155,7 +156,7 @@ def _read_definitions(folder, root_fd, directory): return kind = documents.KINDS[directory] try: - for name, entry_kind in _entries(fd): + for name, entry_kind in entries(fd): path = f'{directory}/{name}' if entry_kind != 'file' or not name.endswith('.json'): message = (_wrong_type(entry_kind, 'file') if entry_kind == 'link' @@ -178,7 +179,7 @@ def _read_results(folder, root_fd): if fd is None: return try: - for name, entry_kind in _entries(fd): + for name, entry_kind in entries(fd): path = f'{RESULTS}/{name}' stem = name[:-len('.csv')] if name.endswith('.csv') else None if entry_kind != 'file' or stem is None or not documents.is_name(stem): @@ -193,7 +194,7 @@ def _read_results(folder, root_fd): os.close(fd) -def _read_notes(folder, root_fd): +def read_notes(folder, root_fd): """Collect the relative paths of every regular file under notes/; contents are not read.""" found = set() top = _open_directory(folder, root_fd, NOTES, NOTES) @@ -203,7 +204,7 @@ def _read_notes(folder, root_fd): while pending: fd, prefix = pending.pop() try: - for name, entry_kind in _entries(fd): + for name, entry_kind in entries(fd): path = f'{prefix}/{name}' if entry_kind == 'file': found.add(path) @@ -228,8 +229,8 @@ def read_folder(path): folder.problems.append(Problem('error', '.', '', f'The project folder {root} cannot be opened: {exc.strerror}.')) return folder try: - entries = dict(_entries(root_fd)) - for name, entry_kind in sorted(entries.items()): + top = dict(entries(root_fd)) + for name, entry_kind in sorted(top.items()): if name == PROJECT_FILE or name in OPTIONAL_FILES: # README.md and .gitignore are allowed but not read; a link is still refused. if entry_kind != 'file': @@ -242,12 +243,12 @@ def read_folder(path): elif name == RESULTS: _read_results(folder, root_fd) elif name == NOTES: - _read_notes(folder, root_fd) + read_notes(folder, root_fd) else: _read_definitions(folder, root_fd, name) else: folder.problems.append(Problem('error', name, '', 'This entry is not part of the project folder format; move it into notes/ or out of the folder.')) - if PROJECT_FILE not in entries: + if PROJECT_FILE not in top: folder.problems.append(Problem('error', PROJECT_FILE, '', 'The folder has no tuldok.json; add one with format, id and name.')) finally: os.close(root_fd) diff --git a/tuldok_project/store.py b/tuldok_project/store.py index eb4646ce..790c87c4 100644 --- a/tuldok_project/store.py +++ b/tuldok_project/store.py @@ -126,9 +126,9 @@ def _read_project_file(root): except OSError: return None try: - raw = folder_reader._read(root_fd, folder_reader.PROJECT_FILE, folder_reader.PROJECT_LIMIT) + raw = folder_reader.read(root_fd, folder_reader.PROJECT_FILE, folder_reader.PROJECT_LIMIT) document = documents.decode(raw) - except (folder_reader._Unsafe, documents.DocumentError): + except (folder_reader.Unsafe, documents.DocumentError): return None finally: os.close(root_fd) @@ -151,24 +151,24 @@ def _list_definitions(root): files, irregular = {}, [] root_fd = _open_root(root) try: - top = dict(folder_reader._entries(root_fd)) + top = dict(folder_reader.entries(root_fd)) for directory in documents.KINDS: if directory not in top: continue if top[directory] != 'directory': irregular.append(directory) continue - fd = os.open(directory, folder_reader._DIRECTORY_FLAGS, dir_fd=root_fd) + fd = os.open(directory, folder_reader.DIRECTORY_FLAGS, dir_fd=root_fd) try: - for name, entry_kind in folder_reader._entries(fd): + for name, entry_kind in folder_reader.entries(fd): path = f'{directory}/{name}' stem = name[:-len('.json')] if name.endswith('.json') else None if entry_kind != 'file' or stem is None or not documents.is_name(stem): irregular.append(path) continue try: - raw = folder_reader._read(fd, name, folder_reader.DEFINITION_LIMIT) - except folder_reader._Unsafe: + raw = folder_reader.read(fd, name, folder_reader.DEFINITION_LIMIT) + except folder_reader.Unsafe: irregular.append(path) continue files[documents.reference(directory, stem)] = _sha(raw) @@ -188,7 +188,7 @@ def _notes(root): return frozenset() try: if os.path.isdir(os.path.join(root, folder_reader.NOTES)): - folder_reader._read_notes(found, root_fd) + folder_reader.read_notes(found, root_fd) finally: os.close(root_fd) return found.notes @@ -201,9 +201,9 @@ def _cross_problems(merged, unsound=frozenset()): def add(severity, path, pointer, message): problems.append(Problem(severity, path, pointer, message)) - check._check_references(merged, add) - check._check_charts(merged, set(unsound), add) - check._check_cycles(merged, add) + check.check_references(merged, add) + check.check_charts(merged, set(unsound), add) + check.check_cycles(merged, add) return problems @@ -483,9 +483,9 @@ def set_definition(self, reference, text): def add(severity, where, pointer, message): problems.append(Problem(severity, where, pointer, message)) - check._check_definition(candidate, _notes(state['folder']), add) + check.check_definition(candidate, _notes(state['folder']), add) code_root = os.path.realpath(os.path.join(state['folder'], state['code_root'])) - check._check_code_paths(candidate, code_root if os.path.isdir(code_root) else None, add) + check.check_code_paths(candidate, code_root if os.path.isdir(code_root) else None, add) alone = _errors(problems) with self._connection.transaction(): merged = self._merged_definitions() @@ -586,14 +586,14 @@ def _file_sha(root, reference): """SHA-256 of the definition file on disk, None when it does not exist, 'unreadable' when it is not a plain file.""" directory, name = documents.parse_reference(reference) try: - fd = os.open(os.path.join(root, directory), folder_reader._DIRECTORY_FLAGS) + fd = os.open(os.path.join(root, directory), folder_reader.DIRECTORY_FLAGS) except FileNotFoundError: return None except OSError: return 'unreadable' try: - return _sha(folder_reader._read(fd, f'{name}.json', folder_reader.DEFINITION_LIMIT)) - except folder_reader._Unsafe: + return _sha(folder_reader.read(fd, f'{name}.json', folder_reader.DEFINITION_LIMIT)) + except folder_reader.Unsafe: if not os.path.lexists(os.path.join(root, directory, f'{name}.json')): return None return 'unreadable' From 5ce6336485a39c542a43ae836a701b3387cd0afc Mon Sep 17 00:00:00 2001 From: MrScripty Date: Tue, 10 Nov 2026 15:25:27 -0700 Subject: [PATCH 009/131] docs(plan): milestone 3 spec for results and charts Co-Authored-By: Claude Fable 5.2 --- .../definition-first-projects/spec-m3.md | 137 ++++++++++++++++++ 1 file changed, 137 insertions(+) create mode 100644 docs/plans/definition-first-projects/spec-m3.md diff --git a/docs/plans/definition-first-projects/spec-m3.md b/docs/plans/definition-first-projects/spec-m3.md new file mode 100644 index 00000000..6f14e84f --- /dev/null +++ b/docs/plans/definition-first-projects/spec-m3.md @@ -0,0 +1,137 @@ +# Implementation spec: milestone 3, results and charts + +This continues [spec-m1-m2.md](spec-m1-m2.md). Section 1 of that file (rules for implementers) applies unchanged, and so does its format section 2. The milestone has two parts: 3a adds results and charts to the new core and its command line, changing no existing Tuldok file; 3b serves the new core from the Tuldok app and gets its own section once 3a is accepted. + +**Done when (3a):** the lab folder opens into an empty database with every summary row of `results/*.csv` in the database; a chart is answered from the summary table without any result file being read; a copy of the lab folder alone, with no `runs/`, draws its charts; and after the lab's per-case values are imported locally, `save` rewrites every `results/*.csv` byte for byte as the lab's build script wrote it. + +## 1. What a benchmark run writes + +One values file per benchmark and subject, format `tuldok_results_v1`: + +```json +{ + "format": "tuldok_results_v1", + "benchmark": "dense-development-240", + "subject": "pilot-dense-k1", + "commit": "", + "produced": "2026-11-10", + "values": [ + {"case": "scene-012", "metric": "velocity_relative_l2", "value": 0.0123, "group": {"cells_per_metre": "32"}}, + {"case": "scene-013", "metric": "velocity_relative_l2", "value": null, "reason": "diverged"} + ] +} +``` + +| Field | Rule | +| --- | --- | +| `format` | exactly `tuldok_results_v1` | +| `benchmark`, `subject` | the benchmark's name and one of its subject names | +| `commit`, `produced` | as in the results file columns of the same names | +| `values[].case` | 1 to 200 characters | +| `values[].metric` | one of the benchmark's metric ids | +| `values[].value` | a finite number, or `null` for a value that was not measured | +| `values[].reason` | required when `value` is `null`, not allowed otherwise; 1 to 400 characters | +| `values[].group` | optional object; keys are from the benchmark's `summary.group_by`; values are strings, numbers or booleans and are stored as text (`true`, `false`, and numbers as written by `repr`) | + +A file is at most 64 MiB, strict JSON as in section 2.2 of the first spec. (case, metric, group) is unique within a file. Unknown fields are refused. + +## 2. Tables + +Added to each project schema, created like the others: + +```sql +CREATE TABLE results_files ( + benchmark text PRIMARY KEY, + file_sha256 text NOT NULL); -- results/.csv as last imported or saved + +CREATE TABLE result_summaries ( + benchmark text NOT NULL, subject text NOT NULL, metric text NOT NULL, grp text NOT NULL, + count integer NOT NULL, unavailable integer NOT NULL, + mean double precision, median double precision, p10 double precision, + p90 double precision, min double precision, max double precision, + commit text NOT NULL, produced text NOT NULL, + origin text NOT NULL CHECK (origin IN ('file', 'values')), + PRIMARY KEY (benchmark, subject, metric, grp)); + +CREATE TABLE result_values ( + benchmark text NOT NULL, subject text NOT NULL, case_id text NOT NULL, + metric text NOT NULL, grp text NOT NULL, -- this value's group fields as 'k=v;k=v', keys sorted; '' if none + value double precision, reason text, + PRIMARY KEY (benchmark, subject, case_id, metric, grp)); +CREATE INDEX result_values_lookup ON result_values (benchmark, metric, subject); +``` + +## 3. Rules + +**Which summaries exist.** For one benchmark, subject and metric there is one row with an empty group, over all that subject's values of the metric, and one row for each single group key and value (`key=value`), over the values that carry that key. There are no rows for combinations of keys. A results file may contain other groups; they are imported as written. + +**Where a subject's summaries come from.** If the database holds values for a (benchmark, subject), its summaries are computed from them with `results.summarise` and have origin `values`. Otherwise they come from `results/.csv` and have origin `file`. + +**Open.** A results file whose SHA-256 differs from `results_files`, or that is new or gone, is part of what makes a folder "changed": the unchanged fast path compares results files as well as definition files. On import, the rows of origin `file` for that benchmark are replaced by the file's rows, except for subjects that have values in the database. + +**Importing values.** `project.import_values(text)` checks the file against its benchmark, then in one transaction replaces that (benchmark, subject)'s rows in `result_values` and its summaries. It refuses a file with any problem and changes nothing. + +**Save.** For each benchmark with summary rows, `save` writes `results/.csv` with `results.write_results` when the text differs from the file on disk, subject to the same changed-on-disk rule as definitions, and records its SHA-256. A benchmark with no rows and an existing file has the file removed. + +**Status.** `status()` gains `results_unsaved` (benchmarks whose database summaries differ from their file) alongside the existing fields. + +**Removing a benchmark definition** also removes its summaries, values and `results_files` row; removing a subject from a benchmark removes that subject's rows when the definition is set. + +## 4. Reading results + +| Member of `Project` | Returns | +| --- | --- | +| `result_summaries(benchmark, subject=None, metric=None, group=None)` | the summary rows as `results.SummaryRow` plus origin; `group=None` means every group, `''` only the ungrouped rows, `'key'` the rows for that key | +| `result_values(benchmark, subject, metric=None, offset=0, limit=200)` | the per-case rows and their total, or an empty list when this machine holds no values for the subject | +| `results_overview()` | per benchmark: subjects with results, subjects with values, rows, and whether it differs from its file | + +## 5. Charts + +`charts.chart_data(project, reference)` answers a chart definition from `result_summaries` and the definitions, with SQL only. It never opens a results or values file. It returns: + +``` +{"chart", "title", "form", "benchmark", "statistic", "group", + "metric": {"id", "title", "units", "better"}, "metric_x": {...} or null, + "series": [{"group": "" or the group value, "points": [...]}], + "missing": [subject names with no usable row]} +``` + +Each point has `subject`, `title`, `recipe` (a reference or null), `value`, `count`, `unavailable` and `produced`. With `group` set on the chart there is one series per value of that key, ordered numerically when every value is a number and as text otherwise; without it there is one series with an empty group. A subject with no row, or a row whose count is 0, is listed in `missing`. + +| Form | Points | +| --- | --- | +| `ranking` | sorted best first by `value` according to the metric's `better` (`lower` ascending, `higher` descending, `none` ascending), ties by subject name | +| `tradeoff` | each also has `x`, the statistic of `metric_x`; a point lacking either value is missing; sorted by `x`; `frontier` is true when no other point in the series is at least as good on both metrics and better on one | +| `progression` | ordered by the `labels.trained_at` of the subject's recipe, ascending, then subjects without one by name; each has `position` from 0 and `best_so_far`, the best `value` up to and including it | +| `comparison` | `series` is replaced by `metrics` (every metric of the benchmark) and `rows`: one per subject with `values`, an object from metric id to the statistic or null; rows follow the chart's `subjects` order, or the ranking order of `metric` when it has none | + +`charts.render_svg(data, *, theme='light') -> str` draws that data as one self-contained SVG document: no scripts, no external references, deterministic output for the same input. + +- Colours and type come from the design tokens in `docs/plans/project-workspace-redesign/README.md` (surface, hairline, ink, secondary ink, accent, and the good colour for the frontier and the running best), in their light and dark values. One hue for marks; no decoration. +- `ranking`: horizontal bars, one row per subject, best at the top, each labelled with the subject's title and its value; the height grows with the number of rows. +- `tradeoff`: points, with a step line through the frontier points and labels on the frontier points only. +- `progression`: points in order with a step line for `best_so_far`. +- `comparison`: a grid of numbers, one row per subject and one column per metric, the best value in each column marked. +- An axis is logarithmic when all its values are positive and the largest is at least 100 times the smallest; otherwise linear from a rounded minimum. Axes carry the metric's title and units. Numbers show three significant digits. +- Missing subjects are counted in a one-line note under the chart. A chart with no points says so in place of the plot. + +## 6. Command line + +| Command | Does | +| --- | --- | +| `results FOLDER [BENCHMARK] [--subject S] [--metric M] [--group G]` | without a benchmark, the overview; with one, its summary rows | +| `values FOLDER BENCHMARK --subject S [--metric M] [--limit N]` | per-case rows, or a sentence saying this machine holds none | +| `import-values FOLDER FILE...` | imports values files; all are checked before any is imported | +| `chart FOLDER CHART [--svg FILE] [--theme light|dark]` | prints the chart's data as text, or as JSON with `--json`; with `--svg` writes the drawing | + +`save` and `status` report results as section 3 says. `--json` applies to `results`, `values` and `chart`. + +## 7. Slices + +| Slice | Files | Notes | +| --- | --- | --- | +| T7 results | `tuldok_project/result_rows.py` (new: the values-file check, the SQL for sections 2 to 4), hooks in `store.py` (tables, open, save, status, definition removal), `results`, `values` and `import-values` in `__main__.py`, `tests/test_tuldok_project_result_rows.py` | database tests | +| T8 charts | `tuldok_project/charts.py` (new), `chart` in `__main__.py`, `tests/test_tuldok_project_charts.py`, and the results, values and chart sections of `docs/contracts/project-folder.md` | after T7 | +| L3 lab | `lab:scripts/build_tuldok_project.py`: results files hold the ungrouped row and one row per single group key and value; with `--values-output DIR` it also writes one `tuldok_results_v1` file per earlier benchmark and subject (outside Git, default `runs/tuldok-results/`); hand-written chart definitions under `lab:projects/surrogate-lab/charts/` | parallel with T7 | + +The fixture gains a values file for its benchmark under `tests/fixtures/tuldok_project/minimal/values/` and a `progression` and a `comparison` chart. From 1bc187b071ea56f48d9c94bd24188e405f0e97cb Mon Sep 17 00:00:00 2001 From: MrScripty Date: Tue, 10 Nov 2026 15:26:58 -0700 Subject: [PATCH 010/131] docs(plan): move app wiring to milestone 7 and add a static report to milestone 3 Co-Authored-By: Claude Fable 5.2 --- docs/plans/definition-first-projects/spec-m1-m2.md | 2 +- docs/plans/definition-first-projects/spec-m3.md | 11 ++++++++--- 2 files changed, 9 insertions(+), 4 deletions(-) diff --git a/docs/plans/definition-first-projects/spec-m1-m2.md b/docs/plans/definition-first-projects/spec-m1-m2.md index 5eb0659c..32a92258 100644 --- a/docs/plans/definition-first-projects/spec-m1-m2.md +++ b/docs/plans/definition-first-projects/spec-m1-m2.md @@ -405,6 +405,6 @@ No change to `app.py`, `agent_api.py`, the browser code or any existing module. ## 6. Already settled for later milestones -- **Wiring into the app (start of milestone 3).** The new core gets its own start-up flag, its own route prefix and its own agent profile, with operations named `project.*`. `app.py` routes by a mode attribute in about eight places and `agent_api.capabilities` filters by profile; both need a third case. The agent contract fixtures under `tests/fixtures/` are pinned and must be regenerated with that change. +- **Wiring into the app (milestone 7; see [spec-m3.md](spec-m3.md) for why it moved from milestone 3).** The new core gets its own start-up flag, its own route prefix and its own agent profile, with operations named `project.*`. `app.py` routes by a mode attribute in about eight places and `agent_api.capabilities` filters by profile; both need a third case. The agent contract fixtures under `tests/fixtures/` are pinned and must be regenerated with that change. - **Environments (milestone 5).** Tuldok has no installer code today. Set-up will use `uv` (a venv for the definition's Python version, then the pinned requirements with the index URLs), or connect an existing interpreter; the check imports each listed package in a child process and compares versions, as the existing run-start checks do. - **Running (milestone 6).** The process custodian in `recipe_process.py` (`launch`, `Handle`, the child-reaping helper) can run a plain command with small local changes: limits from the caller, subdirectories allowed in the output, longer streams truncated and not fatal. The queue in `runs.py` cannot be reused: admission, saving and recovery all require the old recipe material and one-use grants. The new core gets a small queue of its own that shares one capacity object (one GPU slot, the CPU and memory budget) with the existing queue while catalog mode exists, and keeps its safety rules: only the custodian's own end-of-children proof counts as stopped, and a restart never replays started work. diff --git a/docs/plans/definition-first-projects/spec-m3.md b/docs/plans/definition-first-projects/spec-m3.md index 6f14e84f..e739acf7 100644 --- a/docs/plans/definition-first-projects/spec-m3.md +++ b/docs/plans/definition-first-projects/spec-m3.md @@ -1,8 +1,10 @@ # Implementation spec: milestone 3, results and charts -This continues [spec-m1-m2.md](spec-m1-m2.md). Section 1 of that file (rules for implementers) applies unchanged, and so does its format section 2. The milestone has two parts: 3a adds results and charts to the new core and its command line, changing no existing Tuldok file; 3b serves the new core from the Tuldok app and gets its own section once 3a is accepted. +This continues [spec-m1-m2.md](spec-m1-m2.md). Section 1 of that file (rules for implementers) applies unchanged, and so does its format section 2. This milestone adds results and charts to the new core and its command line, and a static report page. It changes no existing Tuldok file. -**Done when (3a):** the lab folder opens into an empty database with every summary row of `results/*.csv` in the database; a chart is answered from the summary table without any result file being read; a copy of the lab folder alone, with no `runs/`, draws its charts; and after the lab's per-case values are imported locally, `save` rewrites every `results/*.csv` byte for byte as the lab's build script wrote it. +**Serving the new core from the Tuldok app moves to milestone 7.** `app.py` routes every request through one handler that branches on the old modes, selects a pinned operation contract and binds the access layer; `agent_api.py` filters operations by profile and its contract fixtures are pinned. Threading a third mode through that is best done once, when every operation of the new core exists (plan, environments, build), so the contracts are registered and the fixtures regenerated a single time. Until then the command line and the report page are the ways to look at a project. + +**Done when:** the lab folder opens into an empty database with every summary row of `results/*.csv` in the database; a chart is answered from the summary table without any result file being read; a copy of the lab folder alone, with no `runs/`, draws its charts; and after the lab's per-case values are imported locally, `save` rewrites every `results/*.csv` byte for byte as the lab's build script wrote it. ## 1. What a benchmark run writes @@ -115,6 +117,8 @@ Each point has `subject`, `title`, `recipe` (a reference or null), `value`, `cou - An axis is logarithmic when all its values are positive and the largest is at least 100 times the smallest; otherwise linear from a rounded minimum. Axes carry the metric's title and units. Numbers show three significant digits. - Missing subjects are counted in a one-line note under the chart. A chart with no points says so in place of the plot. +`charts.render_report(project, *, theme='light') -> str` builds the report page from `summary()`, `definitions()`, `results_overview()`, `chart_data` and `render_svg`. The page has no scripts and no external references, embeds its style, uses the same design tokens, and reads top to bottom: where the project stands, then the charts, then the lists. The 205 earlier recipes make the lists long, so each kind's list is a closed `
` element with its count in the summary line. + ## 6. Command line | Command | Does | @@ -123,6 +127,7 @@ Each point has `subject`, `title`, `recipe` (a reference or null), `value`, `cou | `values FOLDER BENCHMARK --subject S [--metric M] [--limit N]` | per-case rows, or a sentence saying this machine holds none | | `import-values FOLDER FILE...` | imports values files; all are checked before any is imported | | `chart FOLDER CHART [--svg FILE] [--theme light|dark]` | prints the chart's data as text, or as JSON with `--json`; with `--svg` writes the drawing | +| `report FOLDER --output FILE [--theme light|dark]` | writes one self-contained HTML page: the project's name, the counts per kind and state, every chart drawn, the results overview, and the definitions grouped by kind with their states | `save` and `status` report results as section 3 says. `--json` applies to `results`, `values` and `chart`. @@ -131,7 +136,7 @@ Each point has `subject`, `title`, `recipe` (a reference or null), `value`, `cou | Slice | Files | Notes | | --- | --- | --- | | T7 results | `tuldok_project/result_rows.py` (new: the values-file check, the SQL for sections 2 to 4), hooks in `store.py` (tables, open, save, status, definition removal), `results`, `values` and `import-values` in `__main__.py`, `tests/test_tuldok_project_result_rows.py` | database tests | -| T8 charts | `tuldok_project/charts.py` (new), `chart` in `__main__.py`, `tests/test_tuldok_project_charts.py`, and the results, values and chart sections of `docs/contracts/project-folder.md` | after T7 | +| T8 charts and report | `tuldok_project/charts.py` (new), `chart` and `report` in `__main__.py`, `tests/test_tuldok_project_charts.py`, and the results, values, chart and report sections of `docs/contracts/project-folder.md` | after T7 | | L3 lab | `lab:scripts/build_tuldok_project.py`: results files hold the ungrouped row and one row per single group key and value; with `--values-output DIR` it also writes one `tuldok_results_v1` file per earlier benchmark and subject (outside Git, default `runs/tuldok-results/`); hand-written chart definitions under `lab:projects/surrogate-lab/charts/` | parallel with T7 | The fixture gains a values file for its benchmark under `tests/fixtures/tuldok_project/minimal/values/` and a `progression` and a `comparison` chart. From e297f5eeba30047653c00120b2de2097fd97e1a1 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Tue, 10 Nov 2026 15:39:59 -0700 Subject: [PATCH 011/131] feat(project): keep benchmark results in the database Results files are imported on open into a summary table, and are part of what makes a folder changed. A run's per-case values (tuldok_results_v1) can be imported; summaries for that subject are then computed from them, one overall row and one row per single group value, and save writes results/.csv back when it differs. Reading summaries, values and the overview is SQL only. On the lab project, 478,660 values import in 12 s and the recomputed summaries equal the files the lab's build script wrote, byte for byte. Co-Authored-By: Claude Fable 5.2 --- .../minimal/project/results/rollout.csv | 7 +- .../minimal/values/rollout-early-fit.json | 21 + .../minimal/values/rollout-stepper-k1.json | 21 + .../minimal/values/rollout-stepper-k2.json | 21 + tests/test_tuldok_project_check.py | 2 +- tests/test_tuldok_project_cli.py | 3 +- tests/test_tuldok_project_result_rows.py | 525 ++++++++++++++++++ tests/test_tuldok_project_store.py | 15 +- tuldok_project/__main__.py | 128 ++++- tuldok_project/result_rows.py | 431 ++++++++++++++ tuldok_project/store.py | 236 +++++++- 11 files changed, 1377 insertions(+), 33 deletions(-) create mode 100644 tests/fixtures/tuldok_project/minimal/values/rollout-early-fit.json create mode 100644 tests/fixtures/tuldok_project/minimal/values/rollout-stepper-k1.json create mode 100644 tests/fixtures/tuldok_project/minimal/values/rollout-stepper-k2.json create mode 100644 tests/test_tuldok_project_result_rows.py create mode 100644 tuldok_project/result_rows.py diff --git a/tests/fixtures/tuldok_project/minimal/project/results/rollout.csv b/tests/fixtures/tuldok_project/minimal/project/results/rollout.csv index d9210d0c..902e2ecc 100644 --- a/tests/fixtures/tuldok_project/minimal/project/results/rollout.csv +++ b/tests/fixtures/tuldok_project/minimal/project/results/rollout.csv @@ -1,10 +1,13 @@ subject,metric,group,count,unavailable,mean,median,p10,p90,min,max,commit,produced -early-fit,rmse,horizon=1,4,0,0.625,0.625,0.325,0.925,0.25,1.0,0123456789abcdef0123456789abcdef01234567,2026-11-02T10:15:00Z +early-fit,rmse,,4,4,0.625,0.625,0.325,0.925,0.25,1.0,0123456789abcdef0123456789abcdef01234567,2026-11-02 +early-fit,rmse,horizon=1,4,0,0.625,0.625,0.325,0.925,0.25,1.0,0123456789abcdef0123456789abcdef01234567,2026-11-02 early-fit,rmse,horizon=8,0,4,,,,,,,0123456789abcdef0123456789abcdef01234567,2026-11-02 -early-fit,seconds,,2,2,2.5,2.5,2.1,2.9,2.0,3.0,0123456789abcdef0123456789abcdef01234567,2026-11-02T10:15:00Z +early-fit,seconds,,2,2,2.5,2.5,2.1,2.9,2.0,3.0,0123456789abcdef0123456789abcdef01234567,2026-11-02 +stepper-k1,rmse,,8,0,1.25,0.875,0.425,2.65,0.25,3.0,0123456789abcdef0123456789abcdef01234567,2026-11-02T10:15:00Z stepper-k1,rmse,horizon=1,4,0,0.5,0.5,0.325,0.675,0.25,0.75,0123456789abcdef0123456789abcdef01234567,2026-11-02T10:15:00Z stepper-k1,rmse,horizon=8,4,0,2.0,2.0,1.15,2.85,1.0,3.0,0123456789abcdef0123456789abcdef01234567,2026-11-02T10:15:00Z stepper-k1,seconds,,4,0,1.75,1.75,1.15,2.35,1.0,2.5,0123456789abcdef0123456789abcdef01234567,2026-11-02T10:15:00Z +stepper-k2,rmse,,8,0,0.78125,0.5,0.2125,1.65,0.125,2.0,0123456789abcdef0123456789abcdef01234567,2026-11-02T10:15:00Z stepper-k2,rmse,horizon=1,4,0,0.3125,0.3125,0.1625,0.4625,0.125,0.5,0123456789abcdef0123456789abcdef01234567,2026-11-02T10:15:00Z stepper-k2,rmse,horizon=8,4,0,1.25,1.25,0.65,1.85,0.5,2.0,0123456789abcdef0123456789abcdef01234567,2026-11-02T10:15:00Z stepper-k2,seconds,,4,0,1.375,1.375,1.075,1.675,1.0,1.75,0123456789abcdef0123456789abcdef01234567,2026-11-02T10:15:00Z diff --git a/tests/fixtures/tuldok_project/minimal/values/rollout-early-fit.json b/tests/fixtures/tuldok_project/minimal/values/rollout-early-fit.json new file mode 100644 index 00000000..c8f05c59 --- /dev/null +++ b/tests/fixtures/tuldok_project/minimal/values/rollout-early-fit.json @@ -0,0 +1,21 @@ +{ + "format": "tuldok_results_v1", + "benchmark": "rollout", + "subject": "early-fit", + "commit": "0123456789abcdef0123456789abcdef01234567", + "produced": "2026-11-02", + "values": [ + {"case": "scene-01", "metric": "rmse", "value": 0.25, "group": {"horizon": 1}}, + {"case": "scene-01", "metric": "rmse", "value": null, "reason": "diverged before step 8", "group": {"horizon": 8}}, + {"case": "scene-01", "metric": "seconds", "value": 2.0}, + {"case": "scene-02", "metric": "rmse", "value": 0.5, "group": {"horizon": 1}}, + {"case": "scene-02", "metric": "rmse", "value": null, "reason": "diverged before step 8", "group": {"horizon": 8}}, + {"case": "scene-02", "metric": "seconds", "value": null, "reason": "timer not recorded"}, + {"case": "scene-03", "metric": "rmse", "value": 0.75, "group": {"horizon": 1}}, + {"case": "scene-03", "metric": "rmse", "value": null, "reason": "diverged before step 8", "group": {"horizon": 8}}, + {"case": "scene-03", "metric": "seconds", "value": 3.0}, + {"case": "scene-04", "metric": "rmse", "value": 1.0, "group": {"horizon": 1}}, + {"case": "scene-04", "metric": "rmse", "value": null, "reason": "diverged before step 8", "group": {"horizon": 8}}, + {"case": "scene-04", "metric": "seconds", "value": null, "reason": "timer not recorded"} + ] +} diff --git a/tests/fixtures/tuldok_project/minimal/values/rollout-stepper-k1.json b/tests/fixtures/tuldok_project/minimal/values/rollout-stepper-k1.json new file mode 100644 index 00000000..53fb7c51 --- /dev/null +++ b/tests/fixtures/tuldok_project/minimal/values/rollout-stepper-k1.json @@ -0,0 +1,21 @@ +{ + "format": "tuldok_results_v1", + "benchmark": "rollout", + "subject": "stepper-k1", + "commit": "0123456789abcdef0123456789abcdef01234567", + "produced": "2026-11-02T10:15:00Z", + "values": [ + {"case": "scene-01", "metric": "rmse", "value": 0.25, "group": {"horizon": 1}}, + {"case": "scene-01", "metric": "rmse", "value": 1.0, "group": {"horizon": 8}}, + {"case": "scene-01", "metric": "seconds", "value": 1.0}, + {"case": "scene-02", "metric": "rmse", "value": 0.5, "group": {"horizon": 1}}, + {"case": "scene-02", "metric": "rmse", "value": 1.5, "group": {"horizon": 8}}, + {"case": "scene-02", "metric": "seconds", "value": 1.5}, + {"case": "scene-03", "metric": "rmse", "value": 0.5, "group": {"horizon": 1}}, + {"case": "scene-03", "metric": "rmse", "value": 2.5, "group": {"horizon": 8}}, + {"case": "scene-03", "metric": "seconds", "value": 2.0}, + {"case": "scene-04", "metric": "rmse", "value": 0.75, "group": {"horizon": 1}}, + {"case": "scene-04", "metric": "rmse", "value": 3.0, "group": {"horizon": 8}}, + {"case": "scene-04", "metric": "seconds", "value": 2.5} + ] +} diff --git a/tests/fixtures/tuldok_project/minimal/values/rollout-stepper-k2.json b/tests/fixtures/tuldok_project/minimal/values/rollout-stepper-k2.json new file mode 100644 index 00000000..135d61ce --- /dev/null +++ b/tests/fixtures/tuldok_project/minimal/values/rollout-stepper-k2.json @@ -0,0 +1,21 @@ +{ + "format": "tuldok_results_v1", + "benchmark": "rollout", + "subject": "stepper-k2", + "commit": "0123456789abcdef0123456789abcdef01234567", + "produced": "2026-11-02T10:15:00Z", + "values": [ + {"case": "scene-01", "metric": "rmse", "value": 0.125, "group": {"horizon": 1}}, + {"case": "scene-01", "metric": "rmse", "value": 0.5, "group": {"horizon": 8}}, + {"case": "scene-01", "metric": "seconds", "value": 1.0}, + {"case": "scene-02", "metric": "rmse", "value": 0.25, "group": {"horizon": 1}}, + {"case": "scene-02", "metric": "rmse", "value": 1.0, "group": {"horizon": 8}}, + {"case": "scene-02", "metric": "seconds", "value": 1.25}, + {"case": "scene-03", "metric": "rmse", "value": 0.375, "group": {"horizon": 1}}, + {"case": "scene-03", "metric": "rmse", "value": 1.5, "group": {"horizon": 8}}, + {"case": "scene-03", "metric": "seconds", "value": 1.5}, + {"case": "scene-04", "metric": "rmse", "value": 0.5, "group": {"horizon": 1}}, + {"case": "scene-04", "metric": "rmse", "value": 2.0, "group": {"horizon": 8}}, + {"case": "scene-04", "metric": "seconds", "value": 1.75} + ] +} diff --git a/tests/test_tuldok_project_check.py b/tests/test_tuldok_project_check.py index bdea4c5d..7dda2fe8 100644 --- a/tests/test_tuldok_project_check.py +++ b/tests/test_tuldok_project_check.py @@ -549,7 +549,7 @@ def test_fixture_with_its_results_file_has_no_problems(self): def test_problem_in_a_results_row_carries_the_file_path(self): path = self.project / 'results/rollout.csv' - path.write_text(path.read_text().replace('early-fit,rmse,horizon=1', 'nobody,rmse,horizon=1', 1)) + path.write_text(path.read_text().replace('early-fit,rmse,,', 'nobody,rmse,,', 1)) report = check_folder(self.project) problem = self.assertProblem(report, 'results/rollout.csv', 'line 2', alone=False) self.assertIn('nobody', ' '.join(p.message for p in report.problems)) diff --git a/tests/test_tuldok_project_cli.py b/tests/test_tuldok_project_cli.py index 98ca0f55..2ef00f7d 100644 --- a/tests/test_tuldok_project_cli.py +++ b/tests/test_tuldok_project_cli.py @@ -178,7 +178,8 @@ def test_set_status_save(self): self.assertIn('not-built (unsaved)', self.run_ok('list', self.folder)) self.assertEqual(self.run_ok('save', self.folder), 'wrote datasets/waves\n') self.assertEqual((self.folder / 'datasets' / 'waves.json').read_text(encoding='utf-8'), text) - self.assertEqual(self.run_json('save', self.folder), {'written': [], 'deleted': []}) + self.assertEqual(self.run_json('save', self.folder), {'written': [], 'deleted': [], 'results_written': [], + 'results_deleted': []}) self.assertEqual(self.run_ok('status', self.folder), 'Nothing is unsaved and no file changed on disk since the last import.\n') diff --git a/tests/test_tuldok_project_result_rows.py b/tests/test_tuldok_project_result_rows.py new file mode 100644 index 00000000..0e02401d --- /dev/null +++ b/tests/test_tuldok_project_result_rows.py @@ -0,0 +1,525 @@ +"""Benchmark results in the database (spec-m3.md sections 1 to 4, slice T7). + +The values-file check and the summaries computed from values are tested +without a database. Everything else runs only when TULDOK_DATABASE_URL names +a disposable cluster: each test copies tests/fixtures/tuldok_project/minimal +with a fresh project id (test_tuldok_project_store.StoreCase) and drops that +project's schema afterwards. The command-line tests run the commands as a +child process, as test_tuldok_project_cli.py does. +""" +import json +import os +from pathlib import Path +import shutil +import subprocess +import sys +import time +import unittest + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) +sys.path.insert(0, str(Path(__file__).resolve().parent)) + +from tuldok_project import check, result_rows, results # noqa: E402 +from tuldok_project.results import SummaryRow # noqa: E402 +from tuldok_project.store import ProjectError # noqa: E402 +from test_tuldok_project_store import FIXTURE, StoreCase # noqa: E402 + +REPOSITORY = Path(__file__).resolve().parents[1] +VALUES = FIXTURE / 'values' +BENCHMARK = json.loads((FIXTURE / 'project' / 'benchmarks' / 'rollout.json').read_text(encoding='utf-8')) +COMMIT = '0123456789abcdef0123456789abcdef01234567' + + +def values_file(subject='stepper-k1', values=None, **fields): + """The text of a small values file for the fixture's benchmark (the hand-computed case unless values is given).""" + if values is None: + values = [ + {'case': 'a', 'metric': 'rmse', 'value': 1.0, 'group': {'horizon': 1}}, + {'case': 'b', 'metric': 'rmse', 'value': 2.0, 'group': {'horizon': 1}}, + {'case': 'c', 'metric': 'rmse', 'value': None, 'reason': 'diverged', 'group': {'horizon': 1}}, + {'case': 'a', 'metric': 'rmse', 'value': 4.0, 'group': {'horizon': 8}}, + {'case': 'a', 'metric': 'seconds', 'value': 3.0}, + ] + document = {'format': 'tuldok_results_v1', 'benchmark': 'rollout', 'subject': subject, 'commit': COMMIT, + 'produced': '2026-11-10', 'values': values} + document.update(fields) + return json.dumps({key: value for key, value in document.items() if value is not ...}) + + +# The summaries of values_file(), by hand: (metric, group) -> (count, unavailable, mean, median, p10, p90, min, max). +HAND = { + ('rmse', ''): (3, 1, 7 / 3, 2.0, 1.2, 3.6, 1.0, 4.0), # 1, 2, 4 and one null + ('rmse', 'horizon=1'): (2, 1, 1.5, 1.5, 1.1, 1.9, 1.0, 2.0), # 1, 2 and one null + ('rmse', 'horizon=8'): (1, 0, 4.0, 4.0, 4.0, 4.0, 4.0, 4.0), + ('seconds', ''): (1, 0, 3.0, 3.0, 3.0, 3.0, 3.0, 3.0), +} + + +def find(name): + return BENCHMARK if name == 'rollout' else None + + +def summary_numbers(row): + return (row.count, row.unavailable, row.mean, row.median, row.p10, row.p90, row.min, row.max) + + +class ValuesCheck(unittest.TestCase): + """Section 1: one failing case per rule.""" + + def problems(self, text): + found, problems = result_rows.check_values(text, find, path='v.json') + self.assertIsNone(found) + self.assertTrue(problems) + self.assertTrue(all(problem.severity == 'error' and problem.path == 'v.json' for problem in problems)) + return [(problem.pointer, problem.message) for problem in problems] + + def assertPointer(self, text, pointer): + found = self.problems(text) + self.assertIn(pointer, [p for p, _ in found], found) + + def one(self, **change): + """values_file() with one value changed (None in change removes that field).""" + value = {'case': 'a', 'metric': 'rmse', 'value': 1.0, 'group': {'horizon': 1}} + value.update(change) + return values_file(values=[{k: v for k, v in value.items() if v is not ...}]) + + def test_a_good_file_passes(self): + found, problems = result_rows.check_values(values_file(), find) + self.assertEqual(problems, []) + self.assertEqual((found.benchmark, found.subject, found.commit, found.produced), + ('rollout', 'stepper-k1', COMMIT, '2026-11-10')) + self.assertEqual(found.values[0].group, 'horizon=1') + self.assertEqual(found.values[2].reason, 'diverged') + for path in sorted(VALUES.glob('*.json')): + self.assertEqual(result_rows.check_values(path.read_bytes(), find)[1], [], path.name) + + def test_strict_json(self): + self.assertPointer('{"format": "tuldok_results_v1", "format": "tuldok_results_v1"}', '') + self.assertPointer(values_file().replace('1.0', 'NaN', 1), '') + self.assertPointer('[1, 2]', '') + + def test_size_limit(self): + self.assertPointer(b' ' * (result_rows.VALUES_LIMIT + 1), '') + + def test_format(self): + self.assertPointer(values_file(format='tuldok_results_v2'), '/format') + + def test_required_fields(self): + found = self.problems(values_file(commit=...)) + self.assertIn(('', "The field 'commit' is required."), found) + + def test_unknown_fields(self): + self.assertPointer(values_file(extra=1), '/extra') + self.assertPointer(self.one(units='m'), '/values/0/units') + + def test_benchmark_and_subject(self): + self.assertPointer(values_file(benchmark='nothing'), '/benchmark') + self.assertPointer(values_file(subject='nobody'), '/subject') + + def test_commit_and_produced(self): + self.assertPointer(values_file(commit='abc'), '/commit') + self.assertPointer(values_file(produced='2026-13-01'), '/produced') + self.assertPointer(values_file(produced='yesterday'), '/produced') + + def test_values_is_a_non_empty_list(self): + self.assertPointer(values_file(values={}), '/values') + self.assertPointer(values_file(values=[]), '/values') + self.assertPointer(values_file(values=[3]), '/values/0') + + def test_case(self): + self.assertPointer(self.one(case=''), '/values/0/case') + self.assertPointer(self.one(case='x' * 201), '/values/0/case') + self.assertPointer(self.one(case=...), '/values/0/case') + + def test_metric(self): + self.assertPointer(self.one(metric='speed'), '/values/0/metric') + + def test_value(self): + self.assertPointer(self.one(value='1.0'), '/values/0/value') + self.assertPointer(self.one(value=True), '/values/0/value') + self.assertPointer(self.one(value=10 ** 400), '/values/0/value') + self.assertPointer(self.one(value=...), '/values/0') + + def test_reason(self): + self.assertPointer(self.one(value=None), '/values/0/reason') + self.assertPointer(self.one(value=None, reason=''), '/values/0/reason') + self.assertPointer(self.one(value=None, reason='x' * 401), '/values/0/reason') + self.assertPointer(self.one(reason='measured anyway'), '/values/0/reason') + + def test_group(self): + self.assertPointer(self.one(group=[1]), '/values/0/group') + self.assertPointer(self.one(group={'size': 1}), '/values/0/group/size') + self.assertPointer(self.one(group={'horizon': [1]}), '/values/0/group/horizon') + self.assertPointer(self.one(group={'horizon': None}), '/values/0/group/horizon') + self.assertPointer(self.one(group={'horizon': 'a;b'}), '/values/0/group/horizon') + self.assertPointer(self.one(group={'horizon': 'a=b'}), '/values/0/group/horizon') + + def test_group_values_are_stored_as_text(self): + for written, text in ((1, '1'), (1.5, '1.5'), (2.0, '2.0'), (True, 'true'), (False, 'false'), ('x', 'x')): + found, problems = result_rows.check_values(self.one(group={'horizon': written}), find) + self.assertEqual(problems, []) + self.assertEqual(found.values[0].group, f'horizon={text}') + + def test_case_metric_and_group_are_unique(self): + first = {'case': 'a', 'metric': 'rmse', 'value': 1.0, 'group': {'horizon': 1}} + self.assertPointer(values_file(values=[first, dict(first, value=2.0)]), '/values/1') + # The same case and metric in another group is a different value. + found, problems = result_rows.check_values(values_file(values=[first, dict(first, group={'horizon': 8})]), find) + self.assertEqual(problems, []) + + +class SummariesFromValues(unittest.TestCase): + """Section 3, which summaries exist, against hand-computed numbers.""" + + def test_hand_computed(self): + found, _ = result_rows.check_values(values_file(), find) + rows = result_rows.summaries_from_values(found) + self.assertEqual({(row.metric, row.group): summary_numbers(row) for row in rows}, HAND) + self.assertTrue(all(row.subject == 'stepper-k1' and row.commit == COMMIT and row.produced == '2026-11-10' + for row in rows)) + + def test_no_rows_for_combinations(self): + two_keys = dict(BENCHMARK, summary={'group_by': ['horizon', 'size']}) + text = values_file(values=[{'case': 'a', 'metric': 'rmse', 'value': 1.0, 'group': {'horizon': 1, 'size': 's'}}, + {'case': 'b', 'metric': 'rmse', 'value': 3.0, 'group': {'size': 's'}}]) + found, problems = result_rows.check_values(text, lambda name: two_keys) + self.assertEqual(problems, []) + self.assertEqual(found.values[0].group, 'horizon=1;size=s') + rows = {row.group: row.count for row in result_rows.summaries_from_values(found)} + self.assertEqual(rows, {'': 2, 'horizon=1': 1, 'size=s': 2}) + + def test_fixture_results_file_is_made_from_the_fixture_values(self): + rows = [] + for path in sorted(VALUES.glob('*.json')): + rows += result_rows.summaries_from_values(result_rows.check_values(path.read_bytes(), find)[0]) + self.assertEqual(results.write_results(rows), + (FIXTURE / 'project' / 'results' / 'rollout.csv').read_text(encoding='utf-8')) + + +class ResultsCase(StoreCase): + + @property + def csv(self): + return self.folder / 'results' / 'rollout.csv' + + def stored(self, project, **filters): + return {(item.row.subject, item.row.metric, item.row.group): item + for item in project.result_summaries('rollout', **filters)} + + def rewrite_csv(self, change): + """Rewrite the results file with change(rows) applied to its SummaryRow list.""" + rows = results.read_results(self.csv.read_text(encoding='utf-8')) + self.csv.write_text(results.write_results(change(rows)), encoding='utf-8') + + def replace_row(self, subject, metric, group, **fields): + def change(rows): + return [SummaryRow(**{**vars(row), **fields}) if (row.subject, row.metric, row.group) == (subject, metric, group) + else row for row in rows] + self.rewrite_csv(change) + + +class OpenResults(ResultsCase): + + def test_open_imports_every_summary_row(self): + project = self.open() + stored = self.stored(project) + file_rows = results.read_results(self.csv.read_text(encoding='utf-8')) + self.assertEqual([item.row for item in stored.values()], file_rows) + self.assertEqual({item.origin for item in stored.values()}, {'file'}) + self.assertEqual(project.results_overview(), [{ + 'benchmark': 'rollout', 'subjects_with_results': 3, 'subjects_with_values': 0, 'rows': 12, + 'rows_file': 12, 'rows_values': 0, 'differs_from_file': False}]) + self.assertEqual(project.result_values('rollout', 'stepper-k1'), {'total': 0, 'values': []}) + + def test_group_filters(self): + project = self.open() + self.assertEqual(len(project.result_summaries('rollout')), 12) + self.assertEqual({item.row.group for item in project.result_summaries('rollout', group='')}, {''}) + self.assertEqual({item.row.group for item in project.result_summaries('rollout', group='horizon')}, + {'horizon=1', 'horizon=8'}) + self.assertEqual(project.result_summaries('rollout', group='hor'), []) + self.assertEqual(len(project.result_summaries('rollout', subject='early-fit', metric='rmse')), 3) + with self.assertRaises(ProjectError) as caught: + project.result_summaries('nothing') + self.assertEqual(caught.exception.code, 'not-found') + + def test_unchanged_results_attach_without_the_checker(self): + self.close(self.open()) + before = self.dump() + checker = self.counting_checker() + self.open() + checker.assert_not_called() + self.assertEqual(self.dump(), before) + + def test_changed_results_file_is_imported(self): + self.close(self.open()) + self.replace_row('stepper-k2', 'seconds', '', median=1.4) + checker = self.counting_checker() + project = self.open() + checker.assert_called_once() + self.assertEqual(self.stored(project)['stepper-k2', 'seconds', ''].row.median, 1.4) + + def test_removed_and_added_results_file(self): + self.close(self.open()) + text = self.csv.read_text(encoding='utf-8') + self.csv.unlink() + checker = self.counting_checker() + project = self.open() + self.assertEqual(checker.call_count, 1) + self.assertEqual(project.result_summaries('rollout'), []) + self.assertFalse(project.results_overview()[0]['differs_from_file']) + self.close(project) + self.close(self.open()) # unchanged again: no check + self.assertEqual(checker.call_count, 1) + self.csv.write_text(text, encoding='utf-8') + project = self.open() + self.assertEqual(checker.call_count, 2) + self.assertEqual(len(project.result_summaries('rollout')), 12) + + def test_bad_results_file_refuses_the_open_and_changes_nothing(self): + self.close(self.open()) + before = self.dump() + self.csv.write_text(self.csv.read_text(encoding='utf-8').replace('stepper-k1,', 'nobody,', 1), encoding='utf-8') + with self.assertRaises(ProjectError) as caught: + self.open() + self.assertIn('results/rollout.csv', [problem.path for problem in caught.exception.problems]) + self.assertEqual(self.dump(), before) + + def test_floats_round_trip_exactly(self): + awkward = (0.1 + 0.2, 1e-300, 123456789.12345679, -2.5e-07) + self.replace_row('stepper-k1', 'seconds', '', mean=awkward[0], median=awkward[1], p10=awkward[2], + p90=awkward[3]) + project = self.open() + row = self.stored(project)['stepper-k1', 'seconds', ''].row + self.assertEqual((row.mean, row.median, row.p10, row.p90), awkward) + self.assertEqual(project.status()['results_unsaved'], []) # the database makes the same text again + + +class ImportValues(ResultsCase): + + def setUp(self): + super().setUp() + self.project = self.open() + + def test_import_replaces_the_subjects_values_and_summaries(self): + imported = self.project.import_values(values_file()) + self.assertEqual(imported, {'benchmark': 'rollout', 'subject': 'stepper-k1', 'values': 5, 'summaries': 4}) + stored = self.stored(self.project, subject='stepper-k1') + self.assertEqual({(metric, group): summary_numbers(item.row) for (_, metric, group), item in stored.items()}, + HAND) + self.assertEqual({item.origin for item in stored.values()}, {'values'}) + self.assertEqual({item.row.produced for item in stored.values()}, {'2026-11-10'}) + # The other subjects keep the file's rows. + self.assertEqual({item.origin for item in self.project.result_summaries('rollout', subject='stepper-k2')}, + {'file'}) + held = self.project.result_values('rollout', 'stepper-k1') + self.assertEqual(held['total'], 5) + self.assertIn({'case': 'c', 'metric': 'rmse', 'group': 'horizon=1', 'value': None, 'reason': 'diverged'}, + held['values']) + page = self.project.result_values('rollout', 'stepper-k1', metric='rmse', offset=1, limit=2) + self.assertEqual((page['total'], [row['case'] for row in page['values']]), (4, ['a', 'b'])) + overview = self.project.results_overview()[0] + self.assertEqual((overview['subjects_with_values'], overview['rows_file'], overview['rows_values'], + overview['differs_from_file']), (1, 8, 4, True)) + # A second import of the same subject replaces, it does not add. + self.project.import_values(values_file(values=[{'case': 'z', 'metric': 'seconds', 'value': 9.0}])) + self.assertEqual(self.project.result_values('rollout', 'stepper-k1')['total'], 1) + self.assertEqual(list(self.stored(self.project, subject='stepper-k1')), [('stepper-k1', 'seconds', '')]) + + def test_a_file_with_a_problem_changes_nothing(self): + before = self.dump() + bad = values_file(values=[{'case': 'a', 'metric': 'rmse', 'value': 1.0}, + {'case': 'b', 'metric': 'speed', 'value': 1.0}]) + with self.assertRaises(ProjectError) as caught: + self.project.import_values(bad, path='bad.json') + self.assertEqual(caught.exception.code, 'invalid') + self.assertEqual([(p.path, p.pointer) for p in caught.exception.problems], [('bad.json', '/values/1/metric')]) + self.assertEqual(self.dump(), before) + + def test_values_keep_their_summaries_when_the_results_file_is_reimported(self): + self.project.import_values(values_file()) + self.close(self.project) + self.replace_row('stepper-k1', 'seconds', '', median=99.0) + self.replace_row('stepper-k2', 'seconds', '', median=98.0) + project = self.open() + stored = self.stored(project) + self.assertEqual(stored['stepper-k1', 'seconds', ''].origin, 'values') + self.assertEqual(stored['stepper-k1', 'seconds', ''].row.median, 3.0) + self.assertNotIn(('stepper-k1', 'rmse', 'horizon=8'), [k for k, v in stored.items() if v.origin == 'file']) + self.assertEqual(stored['stepper-k2', 'seconds', ''].row.median, 98.0) + self.assertEqual(stored['stepper-k2', 'seconds', ''].origin, 'file') + + def test_many_values_import_quickly(self): + cases = [{'case': f'scene-{index:05d}', 'metric': metric, 'value': index * 0.001, + 'group': {'horizon': index % 2 * 7 + 1}} for index in range(10000) for metric in ('rmse', 'seconds')] + started = time.monotonic() + imported = self.project.import_values(values_file(values=cases)) + self.assertLess(time.monotonic() - started, 20) + self.assertEqual(imported['values'], 20000) + self.assertEqual(self.project.result_values('rollout', 'stepper-k1', limit=5)['total'], 20000) + self.assertEqual(self.stored(self.project)['stepper-k1', 'rmse', 'horizon=8'].row.count, 5000) + + +class SaveAndStatus(ResultsCase): + + def setUp(self): + super().setUp() + self.project = self.open() + + def test_save_writes_the_results_file_and_status_is_clean_after(self): + self.project.import_values(values_file()) + status = self.project.status() + self.assertEqual((status['results_unsaved'], status['results_changed']), (['rollout'], [])) + saved = self.project.save() + self.assertEqual((saved['results_written'], saved['results_deleted']), (['rollout'], [])) + rows = results.read_results(self.csv.read_text(encoding='utf-8')) + self.assertEqual(rows, [item.row for item in self.project.result_summaries('rollout')]) + self.assertEqual(self.project.status()['results_unsaved'], []) + self.assertTrue(check.check_folder(self.folder).ok) + self.assertEqual(self.project.save()['results_written'], []) # same text: nothing written + self.close(self.project) + checker = self.counting_checker() + self.open() + checker.assert_not_called() + + def test_values_matching_the_file_write_nothing(self): + for path in sorted(VALUES.glob('*.json')): + self.project.import_values(path.read_bytes()) + self.assertEqual(self.project.status()['results_unsaved'], []) + modified = self.csv.stat().st_mtime_ns + self.assertEqual(self.project.save()['results_written'], []) + self.assertEqual(self.csv.stat().st_mtime_ns, modified) + + def test_save_refuses_when_the_results_file_changed_on_disk(self): + self.project.import_values(values_file()) + waves = self.edited('datasets/waves', lambda d: d.update(title='Waves, edited')) + self.project.set_definition('datasets/waves', waves) + self.replace_row('stepper-k2', 'seconds', '', median=1.4) + on_disk = self.csv.read_text(encoding='utf-8') + self.assertEqual(self.project.status()['results_changed'], ['results/rollout.csv']) + with self.assertRaises(ProjectError) as caught: + self.project.save() + self.assertEqual(caught.exception.code, 'changed-on-disk') + self.assertEqual(caught.exception.references, ['results/rollout.csv']) + self.assertEqual(self.csv.read_text(encoding='utf-8'), on_disk) + self.assertNotEqual(self.read('datasets/waves'), waves) # nothing at all was written + + def test_removing_the_benchmark_removes_its_results_and_save_deletes_the_file(self): + self.project.import_values(values_file()) + self.project.remove_definition('charts/speed-accuracy') + self.project.remove_definition('charts/rollout-ranking') + self.project.remove_definition('benchmarks/rollout') + connection = self.database() + for table in ('result_summaries', 'result_values'): + count = connection.execute(f'SELECT count(*) FROM {self.schema}.{table}').fetchone()[0] + self.assertEqual(count, 0, table) + self.assertEqual(self.project.status()['results_unsaved'], ['rollout']) + saved = self.project.save() + self.assertEqual(saved['results_deleted'], ['rollout']) + self.assertFalse(self.csv.exists()) + self.assertEqual(connection.execute(f'SELECT count(*) FROM {self.schema}.results_files').fetchone()[0], 0) + self.assertTrue(check.check_folder(self.folder).ok) + self.assertEqual(self.project.status()['results_unsaved'], []) + + def test_removing_a_subject_removes_its_rows(self): + self.project.import_values(values_file(subject='stepper-k2')) + self.project.set_definition('charts/rollout-ranking', self.edited('charts/rollout-ranking', lambda d: d.update( + subjects=['stepper-k1', 'early-fit']))) + benchmark = self.edited('benchmarks/rollout', lambda d: d.update( + subjects=[s for s in d['subjects'] if s['name'] != 'stepper-k2'])) + self.project.set_definition('benchmarks/rollout', benchmark) + self.assertEqual(self.project.result_summaries('rollout', subject='stepper-k2'), []) + self.assertEqual(self.database().execute( + f'SELECT count(*) FROM {self.schema}.result_values').fetchone()[0], 0) + self.assertEqual(len(self.project.result_summaries('rollout')), 8) + self.project.save() + self.assertTrue(check.check_folder(self.folder).ok) + self.assertNotIn('stepper-k2', self.csv.read_text(encoding='utf-8')) + + +def run(*arguments): + environment = dict(os.environ, PYTHONDONTWRITEBYTECODE='1') + return subprocess.run([sys.executable, '-m', 'tuldok_project', *map(str, arguments)], cwd=REPOSITORY, + env=environment, capture_output=True, text=True, timeout=120) + + +class Commands(ResultsCase): + + def setUp(self): + super().setUp() + self.values_files = sorted(self.base.glob('values/*.json')) + + def run_ok(self, *arguments): + done = run(*arguments) + self.assertEqual(done.returncode, 0, done.stderr) + self.assertEqual(done.stderr, '') + return done.stdout + + def test_results(self): + lines = self.run_ok('results', self.folder).splitlines() + self.assertEqual(lines[0].split(), ['benchmark', 'subjects', 'with', 'values', 'rows', 'from', 'file', + 'from', 'values', 'saved']) + self.assertEqual(lines[1].split(), ['rollout', '3', '0', '12', '12', '0', 'yes']) + self.assertEqual(json.loads(self.run_ok('results', self.folder, '--json'))[0]['rows'], 12) + lines = self.run_ok('results', self.folder, 'rollout', '--subject', 'stepper-k1', '--group', '').splitlines() + self.assertEqual(len(lines), 3) + self.assertEqual(lines[1].split()[:4], ['stepper-k1', 'rmse', '-', '8']) + rows = json.loads(self.run_ok('results', self.folder, 'rollout', '--metric', 'rmse', '--group', 'horizon', + '--json')) + self.assertEqual(len(rows), 6) + self.assertEqual(rows[0], {'subject': 'early-fit', 'metric': 'rmse', 'group': 'horizon=1', 'count': 4, + 'unavailable': 0, 'mean': 0.625, 'median': 0.625, 'p10': 0.325, 'p90': 0.925, + 'min': 0.25, 'max': 1.0, 'commit': COMMIT, 'produced': '2026-11-02', + 'origin': 'file'}) + missing = run('results', self.folder, 'nothing') + self.assertEqual((missing.returncode, missing.stderr), (1, 'There is no benchmark benchmarks/nothing.\n')) + + def test_values_before_and_after_import(self): + self.assertIn('holds no per-case values for stepper-k1', + self.run_ok('values', self.folder, 'rollout', '--subject', 'stepper-k1')) + self.assertEqual(json.loads(self.run_ok('values', self.folder, 'rollout', '--subject', 'stepper-k1', '--json')), + {'total': 0, 'values': []}) + output = self.run_ok('import-values', self.folder, *self.values_files) + self.assertEqual(len(output.splitlines()), 3) + self.assertIn('imported benchmarks/rollout early-fit', output) + lines = self.run_ok('values', self.folder, 'rollout', '--subject', 'early-fit', '--limit', '2').splitlines() + self.assertEqual(lines, ['case metric group value', 'scene-01 rmse horizon=1 0.25', + 'scene-01 rmse horizon=8 none (diverged before step 8)', + '2 of 12 values shown; use --limit to see more.']) + held = json.loads(self.run_ok('values', self.folder, 'rollout', '--subject', 'early-fit', '--metric', + 'seconds', '--json')) + self.assertEqual(held['total'], 4) + self.assertEqual(held['values'][1], {'case': 'scene-02', 'metric': 'seconds', 'group': '', 'value': None, + 'reason': 'timer not recorded'}) + overview = json.loads(self.run_ok('results', self.folder, '--json'))[0] + self.assertEqual((overview['rows_values'], overview['differs_from_file']), (12, False)) + self.assertEqual(self.run_ok('status', self.folder), + 'Nothing is unsaved and no file changed on disk since the last import.\n') + + def test_import_values_json_and_refusal(self): + imported = json.loads(self.run_ok('import-values', self.folder, self.values_files[0], '--json')) + self.assertEqual(imported, [{'benchmark': 'rollout', 'subject': 'early-fit', 'values': 12, 'summaries': 4}]) + bad = self.temporary / 'bad.json' + bad.write_text(values_file(subject='stepper-k2', commit='abc'), encoding='utf-8') + before = json.loads(self.run_ok('results', self.folder, '--json')) + done = run('import-values', self.folder, self.values_files[1], bad) + self.assertEqual(done.returncode, 1) + self.assertEqual(done.stdout, '') + self.assertIn(f'error {bad} /commit ', done.stderr) + self.assertIn('Nothing was imported', done.stderr) + self.assertEqual(json.loads(self.run_ok('results', self.folder, '--json')), before) + twice = run('import-values', self.folder, self.values_files[1], self.values_files[1]) + self.assertEqual(twice.returncode, 2) + self.assertIn('same benchmark and subject', twice.stderr) + + def test_save_and_status_report_results(self): + changed = self.temporary / 'k1.json' + changed.write_text(values_file(), encoding='utf-8') + self.run_ok('import-values', self.folder, changed) + self.assertEqual(self.run_ok('status', self.folder), 'results unsaved rollout\n') + self.assertEqual(self.run_ok('save', self.folder), 'wrote results/rollout.csv\n') + self.assertEqual(json.loads(self.run_ok('status', self.folder, '--json'))['results_unsaved'], []) + + +if __name__ == '__main__': + unittest.main() diff --git a/tests/test_tuldok_project_store.py b/tests/test_tuldok_project_store.py index e23b539f..82292b74 100644 --- a/tests/test_tuldok_project_store.py +++ b/tests/test_tuldok_project_store.py @@ -41,6 +41,10 @@ 'steps/solver': 'not-built', } +CLEAN_STATUS = {'unsaved': [], 'removed': [], 'added': [], 'changed': [], 'missing': [], 'irregular': [], + 'results_unsaved': [], 'results_changed': []} + + def _fixture_documents(): project = FIXTURE / 'project' @@ -139,7 +143,7 @@ def dump(self): if connection.execute('SELECT 1 FROM pg_namespace WHERE nspname = %s', (self.schema,)).fetchone() is None: return None tables = {} - for table in ('state', 'definitions', 'edges'): + for table in ('state', 'definitions', 'edges', 'results_files', 'result_summaries', 'result_values'): query = psycopg.sql.SQL('SELECT * FROM {}.{} ORDER BY 1, 2').format( psycopg.sql.Identifier(self.schema), psycopg.sql.Identifier(table)) tables[table] = connection.execute(query).fetchall() @@ -197,8 +201,7 @@ def test_first_open_imports_every_definition(self): order = project.order() self.assertLess(order.index('steps/solver'), order.index('datasets/waves')) self.assertLess(order.index('recipes/stepper-k1'), order.index('recipes/stepper-k2')) - self.assertEqual(project.status(), {'unsaved': [], 'removed': [], 'added': [], 'changed': [], - 'missing': [], 'irregular': []}) + self.assertEqual(project.status(), CLEAN_STATUS) def test_second_open_of_unchanged_folder_does_not_run_the_checker(self): self.close(self.open()) @@ -423,13 +426,13 @@ def test_save_writes_and_deletes_files(self): self.project.set_definition('models/extra', extra) self.project.remove_definition('charts/speed-accuracy') result = self.project.save() - self.assertEqual(result, {'written': ['datasets/waves', 'models/extra'], 'deleted': ['charts/speed-accuracy']}) + self.assertEqual(result, {'written': ['datasets/waves', 'models/extra'], 'deleted': ['charts/speed-accuracy'], + 'results_written': [], 'results_deleted': []}) self.assertEqual(self.read('datasets/waves'), waves) self.assertEqual(self.read('models/extra'), extra) self.assertFalse((self.folder / 'charts' / 'speed-accuracy.json').exists()) self.assertEqual(sorted(p.name for p in (self.folder / 'datasets').iterdir()), ['waves.json']) - self.assertEqual(self.project.status(), {'unsaved': [], 'removed': [], 'added': [], 'changed': [], - 'missing': [], 'irregular': []}) + self.assertEqual(self.project.status(), CLEAN_STATUS) self.assertTrue(check.check_folder(self.folder).ok) # What was saved is what the database records, so the next open attaches without a check. self.close(self.project) diff --git a/tuldok_project/__main__.py b/tuldok_project/__main__.py index 65a2c52d..82d9a7fd 100644 --- a/tuldok_project/__main__.py +++ b/tuldok_project/__main__.py @@ -6,15 +6,18 @@ alone (check.check_folder). Every other command works on the folder's database copy through store.open_project: it opens the project (importing what changed on disk), does its one piece of work and closes the Project before exiting, so -the project's lock is never held past the command. +the project's lock is never held past the command. `results` and `values` read +benchmark results from the database only; `import-values` checks every values +file before it imports any. """ import argparse +import dataclasses import json import os import sys import time -from . import documents, folder as folder_reader +from . import documents, folder as folder_reader, results as results_format from .check import check_folder DATABASE_VARIABLE = 'TULDOK_DATABASE_URL' @@ -69,10 +72,32 @@ def add(name, parents, help_text): removing = add('remove', [opening], 'remove a definition in the database (not saved to the folder)') removing.add_argument('reference', help='for example recipes/pilot-dense-k1') add('save', [reading], 'write the unsaved edits to the folder') + showing = add('results', [reading], "show the benchmarks' results, or one benchmark's summary rows") + showing.add_argument('benchmark', nargs='?', help='a benchmark name, for example rollout') + showing.add_argument('--subject', help='only this subject') + showing.add_argument('--metric', help='only this metric id') + showing.add_argument('--group', help="only this group key; '' for the ungrouped rows") + values = add('values', [reading], "show a subject's per-case values held on this machine") + values.add_argument('benchmark', help='a benchmark name, for example rollout') + values.add_argument('--subject', required=True, help='the subject') + values.add_argument('--metric', help='only this metric id') + values.add_argument('--limit', type=_positive, default=200, help='at most this many rows (default 200)') + importing = add('import-values', [reading], 'import tuldok_results_v1 values files; all are checked first') + importing.add_argument('files', nargs='+', metavar='FILE', help='values files') add('forget', [database], "drop this project's copy from the database; the folder is not touched") return parser +def _positive(text): + try: + value = int(text) + except ValueError: + value = 0 + if value < 1: + raise argparse.ArgumentTypeError(f'{text!r} is not a whole number of at least 1') + return value + + # ----------------------------------------------------------------- output def _plural(count, word): @@ -179,6 +204,7 @@ def _graph(project, arguments): _STATUS_WORDS = ( ('unsaved', 'unsaved'), ('removed', 'removed'), ('added', 'added on disk'), ('changed', 'changed on disk'), ('missing', 'missing on disk'), ('irregular', 'not a definition file'), + ('results_unsaved', 'results unsaved'), ('results_changed', 'results changed on disk'), ) @@ -214,6 +240,8 @@ def _save(project, arguments): return 0 rows = [('wrote', reference) for reference in saved['written']] rows += [('deleted', reference) for reference in saved['deleted']] + rows += [('wrote', f'results/{name}.csv') for name in saved['results_written']] + rows += [('deleted', f'results/{name}.csv') for name in saved['results_deleted']] if rows: _columns(rows) else: @@ -221,8 +249,74 @@ def _save(project, arguments): return 0 +def _number(value): + return '-' if value is None else f'{value:.4g}' + + +def _results(project, arguments): + if arguments.benchmark is None: + overview = project.results_overview() + if arguments.json: + _json(overview) + return 0 + _columns([('benchmark', 'subjects', 'with values', 'rows', 'from file', 'from values', 'saved'), + *((item['benchmark'], item['subjects_with_results'], item['subjects_with_values'], item['rows'], + item['rows_file'], item['rows_values'], 'differs' if item['differs_from_file'] else 'yes' if item['rows'] else '-') + for item in overview)]) + return 0 + stored = project.result_summaries(arguments.benchmark, subject=arguments.subject, metric=arguments.metric, + group=arguments.group) + if arguments.json: + _json([{**dataclasses.asdict(item.row), 'origin': item.origin} for item in stored]) + return 0 + if not stored: + print(f'benchmarks/{arguments.benchmark} has no summary rows that match.') + return 0 + _columns([(*('subject', 'metric', 'group', 'count', 'unavailable'), *results_format.STATISTICS, 'produced', 'origin'), + *((item.row.subject, item.row.metric, item.row.group or '-', item.row.count, item.row.unavailable, + *(_number(getattr(item.row, name)) for name in results_format.STATISTICS), + item.row.produced, item.origin) for item in stored)]) + return 0 + + +def _values(project, arguments): + held = project.result_values(arguments.benchmark, arguments.subject, metric=arguments.metric, + limit=arguments.limit) + if arguments.json: + _json(held) + return 0 + if held['total'] == 0: + print(f'This machine holds no per-case values for {arguments.subject} in benchmarks/{arguments.benchmark}' + + (f' for metric {arguments.metric}' if arguments.metric else '') + '; import them with import-values.') + return 0 + _columns([('case', 'metric', 'group', 'value'), + *((row['case'], row['metric'], row['group'] or '-', + repr(row['value']) if row['value'] is not None else f'none ({row["reason"]})') + for row in held['values'])]) + if held['total'] > len(held['values']): + print(f'{len(held["values"])} of {held["total"]} values shown; use --limit to see more.') + return 0 + + +def _import_values(project, arguments): + problems = [problem for path, text in arguments.texts for problem in project.check_values(text, path=path)] + if problems: + for problem in problems: + print(_problem_line(problem), file=sys.stderr) + print(f'Nothing was imported: {_plural(len(problems), "problem")} in the values files.', file=sys.stderr) + return 1 + imported = [project.import_values(text, path=path) for path, text in arguments.texts] + if arguments.json: + _json(imported) + else: + _columns([(f'imported benchmarks/{item["benchmark"]}', item['subject'], _plural(item['values'], 'value'), + _plural(item['summaries'], 'summary row')) for item in imported]) + return 0 + + _STORE_COMMANDS = {'open': _open, 'list': _list, 'show': _show, 'graph': _graph, 'status': _status, - 'set': _set, 'remove': _remove, 'save': _save} + 'set': _set, 'remove': _remove, 'save': _save, 'results': _results, 'values': _values, + 'import-values': _import_values} def _project_id(folder): @@ -246,6 +340,27 @@ def _project_id(folder): return project_id +def _read_values(path): + """The bytes of a values file, at most the size limit plus one so the check can report an oversize file.""" + from .result_rows import VALUES_LIMIT + + try: + with open(path, 'rb') as handle: + return handle.read(VALUES_LIMIT + 1) + except OSError as exc: + raise UsageError(f'{path} cannot be read: {exc.strerror}.') from None + + +def _values_key(raw): + """(benchmark, subject) of a values file, or None when it cannot be read that far (the check will say why).""" + try: + document = documents.decode(raw) + except documents.DocumentError: + return None + key = (document.get('benchmark'), document.get('subject')) + return key if all(isinstance(part, str) for part in key) else None + + def _forget(arguments, dsn): from . import store @@ -266,6 +381,13 @@ def _run_store(arguments, dsn): raise UsageError(f'{arguments.file} cannot be read: {exc.strerror}.') from None except UnicodeDecodeError as exc: raise UsageError(f'{arguments.file} is not UTF-8 text (bad byte at offset {exc.start}).') from None + if arguments.command == 'import-values': + arguments.texts = [(path, _read_values(path)) for path in arguments.files] + keys = [_values_key(text) for _, text in arguments.texts] + twice = [path for (path, _), key in zip(arguments.texts, keys) if key is not None and keys.count(key) > 1] + if twice: + raise UsageError('These files are for the same benchmark and subject; import one of them: ' + + ', '.join(twice) + '.') started = time.monotonic() project = store.open_project(arguments.folder, rebind=arguments.rebind, on_conflict=arguments.on_conflict, dsn=dsn) diff --git a/tuldok_project/result_rows.py b/tuldok_project/result_rows.py new file mode 100644 index 00000000..6ae0c39a --- /dev/null +++ b/tuldok_project/result_rows.py @@ -0,0 +1,431 @@ +"""Benchmark results in the database: per-case values files, summary rows and their tables. + +Owns sections 1 to 4 of docs/plans/definition-first-projects/spec-m3.md: the +check of a tuldok_results_v1 values file against its benchmark, the three +results tables of a project schema, and the SQL that fills and reads them. +Summaries are computed in Python with results.summarise, never in SQL, so the +numbers are exactly the ones the lab's build script writes; floats travel as +Python floats into double precision columns and back. A subject's summaries +come from its values when the database holds values for it (origin 'values'), +otherwise from results/.csv (origin 'file'). store.py calls these +functions inside its own transactions; nothing here reads a file. +""" +from collections import defaultdict +from dataclasses import dataclass +import hashlib +import math + +from psycopg import sql + +from . import documents, results +from .documents import Problem + +FORMAT = 'tuldok_results_v1' +VALUES_LIMIT = 64 * 1024 * 1024 +ORIGINS = ('file', 'values') + +TABLES = ( + '''CREATE TABLE IF NOT EXISTS {schema}.results_files ( + benchmark text PRIMARY KEY, + file_sha256 text NOT NULL)''', + '''CREATE TABLE IF NOT EXISTS {schema}.result_summaries ( + benchmark text NOT NULL, subject text NOT NULL, metric text NOT NULL, grp text NOT NULL, + count integer NOT NULL, unavailable integer NOT NULL, + mean double precision, median double precision, p10 double precision, + p90 double precision, min double precision, max double precision, + commit text NOT NULL, produced text NOT NULL, + origin text NOT NULL CHECK (origin IN ('file', 'values')), + PRIMARY KEY (benchmark, subject, metric, grp))''', + '''CREATE TABLE IF NOT EXISTS {schema}.result_values ( + benchmark text NOT NULL, subject text NOT NULL, case_id text NOT NULL, + metric text NOT NULL, grp text NOT NULL, + value double precision, reason text, + PRIMARY KEY (benchmark, subject, case_id, metric, grp))''', + 'CREATE INDEX IF NOT EXISTS result_values_lookup ON {schema}.result_values (benchmark, metric, subject)', +) + +_SUMMARY_COLUMNS = ('subject', 'metric', 'grp', 'count', 'unavailable', *results.STATISTICS, 'commit', 'produced') +_INSERT_SUMMARY = ('INSERT INTO {schema}.result_summaries (benchmark, ' + ', '.join(_SUMMARY_COLUMNS) + + ', origin) VALUES (' + ', '.join(['%s'] * (len(_SUMMARY_COLUMNS) + 2)) + ')') +_SELECT_SUMMARY = 'SELECT ' + ', '.join(_SUMMARY_COLUMNS) + ', origin FROM {schema}.result_summaries' +_ORDER = ' ORDER BY subject COLLATE "C", metric COLLATE "C", grp COLLATE "C"' + +_TOP_FIELDS = ('format', 'benchmark', 'subject', 'commit', 'produced', 'values') +_VALUE_FIELDS = ('case', 'metric', 'value', 'reason', 'group') + + +@dataclass(frozen=True) +class Value: + """One per-case value: value is a float, or None with a reason; group is 'k=v;k=v' with keys sorted.""" + case: str + metric: str + group: str + value: float | None + reason: str | None + pairs: tuple = () # the group as ((key, text), ...), keys sorted + + +@dataclass(frozen=True) +class ValuesFile: + """A values file that passed check_values.""" + benchmark: str + subject: str + commit: str + produced: str + values: tuple + + +@dataclass(frozen=True) +class StoredSummary: + """One row of result_summaries: the results.SummaryRow and where it came from ('file' or 'values').""" + row: results.SummaryRow + origin: str + + +def _q(schema, template): + return sql.SQL(template).format(schema=sql.Identifier(schema)) + + +def sha256_text(text): + return hashlib.sha256(text.encode('utf-8')).hexdigest() + + +# ------------------------------------------------------ the values file (1) + +def _group_text(value): + """The stored text of a group value (strings as they are, true/false, numbers by repr), or None if not allowed.""" + if isinstance(value, bool): + return 'true' if value else 'false' + if isinstance(value, (int, float)): + return repr(value) + if isinstance(value, str): + return value + return None + + +def _number(value): + """value as a finite float, or None when it is not a finite number.""" + if isinstance(value, bool) or not isinstance(value, (int, float)): + return None + try: + number = float(value) + except OverflowError: + return None + return number if math.isfinite(number) else None + + +def check_values(text, find_benchmark, *, path=''): + """Check a values file; return (ValuesFile or None, [Problem]). + + text is the file's bytes or str. find_benchmark(name) returns that + benchmark's decoded definition, or None when the project has none. Every + problem is an error; the ValuesFile is returned only when there is none. + """ + problems = [] + + def add(pointer, message): + problems.append(Problem('error', path, pointer, message)) + + size = len(text) if isinstance(text, (bytes, bytearray)) else len(text.encode('utf-8')) + if size > VALUES_LIMIT: + add('', f'The file is {size} bytes; a values file is at most {VALUES_LIMIT} bytes.') + return None, problems + try: + document = documents.decode(text) + except documents.DocumentError as exc: + add('', str(exc)) + return None, problems + + for key in sorted(set(document) - set(_TOP_FIELDS)): + add(documents.pointer(key), f'The field {key!r} is not part of a values file; remove it.') + for key in _TOP_FIELDS: + if key not in document: + add('', f'The field {key!r} is required.') + if 'format' in document and document['format'] != FORMAT: + add('/format', f'The format must be exactly {FORMAT}.') + commit, produced = document.get('commit'), document.get('produced') + if 'commit' in document and not (isinstance(commit, str) and (commit == '' or results._COMMIT.fullmatch(commit))): + add('/commit', 'The commit must be 40 lowercase hexadecimal characters or empty.') + if 'produced' in document and not (isinstance(produced, str) and results._produced_is_valid(produced)): + add('/produced', 'The produced date must be YYYY-MM-DD or YYYY-MM-DDTHH:MM:SSZ.') + + benchmark_name, subject = document.get('benchmark'), document.get('subject') + benchmark = None + if 'benchmark' in document: + benchmark = find_benchmark(benchmark_name) if documents.is_name(benchmark_name) else None + if benchmark is None: + add('/benchmark', f'There is no benchmark {benchmark_name!r} in this project.') + subjects, metrics, group_by, _ = results._benchmark_names(benchmark) + if benchmark is not None and 'subject' in document and subject not in subjects: + add('/subject', f'{subject!r} is not a subject of benchmarks/{benchmark_name}.') + + rows = document.get('values') + if 'values' in document and not isinstance(rows, list): + add('/values', 'The values must be a list.') + rows = [] + elif 'values' in document and not rows: + add('/values', 'The values list is empty; a values file holds at least one value.') + values, seen = [], set() + for index, row in enumerate(rows or []): + found, found_problems = _check_value(row, index, metrics, group_by, benchmark is not None) + for pointer, message in found_problems: + add(pointer, message) + if found is None: + continue + key = (found.case, found.metric, found.group) + if key in seen: + add(documents.pointer('values', index), 'This (case, metric, group) appears earlier in the file.') + seen.add(key) + values.append(found) + if problems: + return None, problems + return ValuesFile(benchmark_name, subject, commit, produced, tuple(values)), problems + + +def _check_value(row, index, metrics, group_by, known): + """Check one entry of values[]; return (Value or None, [(pointer, message)]).""" + problems = [] + here = ('values', index) + + def add(*parts_and_message): + *parts, message = parts_and_message + problems.append((documents.pointer(*here, *parts), message)) + + if not isinstance(row, dict): + add('Each value must be an object.') + return None, problems + for key in sorted(set(row) - set(_VALUE_FIELDS)): + add(key, f'The field {key!r} is not part of a value; remove it.') + case = row.get('case') + if not (isinstance(case, str) and 1 <= len(case) <= 200): + add('case', 'The case must be a string of 1 to 200 characters.') + metric = row.get('metric') + if not isinstance(metric, str) or (known and metric not in metrics): + add('metric', f'The metric {metric!r} is not a metric id of the benchmark.') + value = None + if 'value' not in row: + add("The field 'value' is required: a number, or null with a reason.") + elif row['value'] is not None: + value = _number(row['value']) + if value is None: + add('value', 'The value must be a finite number, or null.') + reason = row.get('reason') + if 'value' in row and row['value'] is None: + if not (isinstance(reason, str) and 1 <= len(reason) <= 400): + add('reason', 'A null value needs a reason of 1 to 400 characters.') + elif 'reason' in row: + add('reason', 'A reason is allowed only when the value is null.') + group = row.get('group', {}) + pairs = [] + if not isinstance(group, dict): + add('group', 'The group must be an object.') + group = {} + for key in sorted(group): + if known and key not in group_by: + add('group', key, f"The group key {key!r} is not in the benchmark's summary.group_by.") + text = _group_text(group[key]) + if text is None: + add('group', key, 'A group value must be a string, a number or a boolean.') + elif any(mark in text for mark in ';=\r\n'): + add('group', key, 'A group value may not contain ";", "=" or a line break.') + else: + pairs.append((key, text)) + if problems: + return None, problems + return Value(case, metric, ';'.join(f'{key}={text}' for key, text in pairs), + value, None if value is not None else reason, tuple(pairs)), problems + + +# ------------------------------------------------------------ summaries (3) + +def summaries_from_values(values_file): + """The SummaryRow items of one values file: per metric, the ungrouped row and one per single key=value.""" + measured, missing = defaultdict(list), defaultdict(int) + for item in values_file.values: + for group in ('', *(f'{key}={text}' for key, text in item.pairs)): + measured[item.metric, group] # every set gets a row, even with nothing measured + if item.value is None: + missing[item.metric, group] += 1 + else: + measured[item.metric, group].append(item.value) + return [results.SummaryRow(subject=values_file.subject, metric=metric, group=group, + commit=values_file.commit, produced=values_file.produced, + **results.summarise(measured[metric, group], missing[metric, group])) + for metric, group in sorted(measured)] + + +def _fits(row, subjects, metrics, group_by): + """True when a summary row still belongs to the benchmark: known subject and metric, group keys in group_by.""" + if row.subject not in subjects or row.metric not in metrics: + return False + return row.group == '' or all(pair.partition('=')[0] in group_by for pair in row.group.split(';')) + + +def _summary_parameters(benchmark, row, origin): + return (benchmark, row.subject, row.metric, row.group, row.count, row.unavailable, + *(None if getattr(row, name) is None else float(getattr(row, name)) for name in results.STATISTICS), + row.commit, row.produced, origin) + + +def subjects_with_values(connection, schema, benchmark): + return {subject for (subject,) in connection.execute( + _q(schema, 'SELECT DISTINCT subject FROM {schema}.result_values WHERE benchmark = %s'), (benchmark,))} + + +def import_file(connection, schema, benchmark, text, document): + """Replace the benchmark's origin-'file' summaries with the rows of its results file and record its digest. + + Subjects with values in the database keep their 'values' summaries; rows + that no longer fit the benchmark document (an unsaved edit) are left out. + """ + subjects, metrics, group_by, _ = results._benchmark_names(document) + keep = subjects_with_values(connection, schema, benchmark) + rows = [row for row in results.read_results(text) + if row.subject not in keep and _fits(row, subjects, metrics, group_by)] + connection.execute(_q(schema, "DELETE FROM {schema}.result_summaries WHERE benchmark = %s AND origin = 'file'"), + (benchmark,)) + if rows: + with connection.cursor() as cursor: + cursor.executemany(_q(schema, _INSERT_SUMMARY), [_summary_parameters(benchmark, row, 'file') for row in rows]) + record_file(connection, schema, benchmark, sha256_text(text)) + + +def forget_file(connection, schema, benchmark): + """The results file is gone: drop its origin-'file' summaries and its digest.""" + connection.execute(_q(schema, "DELETE FROM {schema}.result_summaries WHERE benchmark = %s AND origin = 'file'"), + (benchmark,)) + connection.execute(_q(schema, 'DELETE FROM {schema}.results_files WHERE benchmark = %s'), (benchmark,)) + + +def record_file(connection, schema, benchmark, sha): + connection.execute(_q(schema, '''INSERT INTO {schema}.results_files (benchmark, file_sha256) VALUES (%s, %s) + ON CONFLICT (benchmark) DO UPDATE SET file_sha256 = EXCLUDED.file_sha256'''), + (benchmark, sha)) + + +def replace_values(connection, schema, values_file): + """Replace one (benchmark, subject)'s values and summaries; the caller holds the transaction.""" + key = (values_file.benchmark, values_file.subject) + connection.execute(_q(schema, 'DELETE FROM {schema}.result_values WHERE benchmark = %s AND subject = %s'), key) + connection.execute(_q(schema, 'DELETE FROM {schema}.result_summaries WHERE benchmark = %s AND subject = %s'), key) + with connection.cursor() as cursor: + with cursor.copy(_q(schema, 'COPY {schema}.result_values ' + '(benchmark, subject, case_id, metric, grp, value, reason) FROM STDIN')) as copy: + for item in values_file.values: + copy.write_row((*key, item.case, item.metric, item.group, item.value, item.reason)) + rows = summaries_from_values(values_file) + cursor.executemany(_q(schema, _INSERT_SUMMARY), + [_summary_parameters(values_file.benchmark, row, 'values') for row in rows]) + return {'benchmark': values_file.benchmark, 'subject': values_file.subject, + 'values': len(values_file.values), 'summaries': len(rows)} + + +def remove_benchmark(connection, schema, benchmark): + """Drop a benchmark's summaries and values (its results_files digest stays until save deletes the file).""" + for table in ('result_summaries', 'result_values'): + connection.execute(_q(schema, f'DELETE FROM {{schema}}.{table} WHERE benchmark = %s'), (benchmark,)) + + +def prune(connection, schema, benchmark, document): + """Drop rows that no longer fit the benchmark: unknown subjects or metrics, and summaries of unknown group keys.""" + subjects, metrics, group_by, _ = results._benchmark_names(document) + subjects, metrics = sorted(subjects), sorted(metrics) + for table in ('result_summaries', 'result_values'): + connection.execute(_q(schema, f'DELETE FROM {{schema}}.{table} WHERE benchmark = %s ' + 'AND (NOT subject = ANY(%s) OR NOT metric = ANY(%s))'), + (benchmark, subjects, metrics)) + stale = [(row.subject, row.metric, row.group) for row in (stored.row for stored in summaries(connection, schema, benchmark)) + if not _fits(row, set(subjects), set(metrics), group_by)] + if stale: + with connection.cursor() as cursor: + cursor.executemany(_q(schema, 'DELETE FROM {schema}.result_summaries WHERE benchmark = %s ' + 'AND subject = %s AND metric = %s AND grp = %s'), + [(benchmark, *key) for key in stale]) + + +# --------------------------------------------------------------- reading (4) + +def _stored(record): + *columns, origin = record + fields = dict(zip(_SUMMARY_COLUMNS, columns)) + fields['group'] = fields.pop('grp') + return StoredSummary(results.SummaryRow(**fields), origin) + + +def summaries(connection, schema, benchmark, subject=None, metric=None, group=None): + """StoredSummary rows of a benchmark, sorted by subject, metric and group. + + group None means every group, '' only the ungrouped rows, and a key the + rows whose group is that one key (key=value), not combinations. + """ + where, parameters = ['benchmark = %s'], [benchmark] + if subject is not None: + where.append('subject = %s') + parameters.append(subject) + if metric is not None: + where.append('metric = %s') + parameters.append(metric) + if group == '': + where.append("grp = ''") + elif group is not None: + where.append("left(grp, length(%s) + 1) = %s || '=' AND strpos(grp, ';') = 0") + parameters += [group, group] + query = _SELECT_SUMMARY + ' WHERE ' + ' AND '.join(where) + _ORDER + return [_stored(record) for record in connection.execute(_q(schema, query), parameters)] + + +def values(connection, schema, benchmark, subject, metric=None, offset=0, limit=200): + """{'total', 'values': [{case, metric, group, value, reason}]} for one subject; total 0 when none are held.""" + where, parameters = 'benchmark = %s AND subject = %s', [benchmark, subject] + if metric is not None: + where += ' AND metric = %s' + parameters.append(metric) + total = connection.execute(_q(schema, f'SELECT count(*) FROM {{schema}}.result_values WHERE {where}'), + parameters).fetchone()[0] + rows = connection.execute(_q(schema, f'''SELECT case_id, metric, grp, value, reason FROM {{schema}}.result_values + WHERE {where} ORDER BY metric COLLATE "C", case_id COLLATE "C", grp COLLATE "C" + OFFSET %s LIMIT %s'''), [*parameters, offset, limit]).fetchall() + return {'total': total, 'values': [{'case': case, 'metric': row_metric, 'group': grp, 'value': value, + 'reason': reason} for case, row_metric, grp, value, reason in rows]} + + +def file_texts(connection, schema): + """{benchmark: (text the database's summaries make, or None when it has none; recorded file digest or None)}.""" + grouped = defaultdict(list) + for record in connection.execute(_q(schema, _SELECT_SUMMARY.replace('SELECT ', 'SELECT benchmark, ', 1))): + grouped[record[0]].append(_stored(record[1:]).row) + recorded = dict(connection.execute(_q(schema, 'SELECT benchmark, file_sha256 FROM {schema}.results_files')).fetchall()) + return {benchmark: (results.write_results(grouped[benchmark]) if benchmark in grouped else None, + recorded.get(benchmark)) + for benchmark in sorted(set(grouped) | set(recorded))} + + +def differs(text, recorded): + """True when what the database holds is not the file as last imported or saved.""" + return (None if text is None else sha256_text(text)) != recorded + + +def overview(connection, schema): + """Per benchmark: subjects with results, subjects with values, summary rows per origin, and whether it differs from its file.""" + names = {name for (name,) in connection.execute( + _q(schema, "SELECT name FROM {schema}.definitions WHERE directory = 'benchmarks' AND NOT removed"))} + counts = defaultdict(dict) + for benchmark, subjects, file_rows, value_rows in connection.execute(_q(schema, ''' + SELECT benchmark, count(DISTINCT subject), count(*) FILTER (WHERE origin = 'file'), + count(*) FILTER (WHERE origin = 'values') + FROM {schema}.result_summaries GROUP BY benchmark''')): + counts[benchmark].update(subjects_with_results=subjects, rows_file=file_rows, rows_values=value_rows) + for benchmark, subjects in connection.execute(_q(schema, ''' + SELECT benchmark, count(*) FROM (SELECT DISTINCT benchmark, subject FROM {schema}.result_values) AS held + GROUP BY benchmark''')): + counts[benchmark]['subjects_with_values'] = subjects + texts = file_texts(connection, schema) + found = [] + for benchmark in sorted(names | set(counts) | set(texts)): + count = counts.get(benchmark, {}) + file_rows, value_rows = count.get('rows_file', 0), count.get('rows_values', 0) + found.append({'benchmark': benchmark, 'subjects_with_results': count.get('subjects_with_results', 0), + 'subjects_with_values': count.get('subjects_with_values', 0), + 'rows': file_rows + value_rows, 'rows_file': file_rows, 'rows_values': value_rows, + 'differs_from_file': differs(*texts[benchmark]) if benchmark in texts else False}) + return found diff --git a/tuldok_project/store.py b/tuldok_project/store.py index 790c87c4..8861af89 100644 --- a/tuldok_project/store.py +++ b/tuldok_project/store.py @@ -11,6 +11,9 @@ computed by graph.states from the documents. A Project keeps no copy of the definitions in memory and holds a session advisory lock on its project for as long as it is open, so one Project at a time owns a project's copy. +Benchmark results (spec-m3.md) live in three more tables owned by result_rows: +results files are part of what open compares and imports, and save writes +them back when the database's summaries make a different text. """ from dataclasses import dataclass import hashlib @@ -24,7 +27,7 @@ from metadata import connection_info -from . import check, documents, folder as folder_reader, graph +from . import check, documents, folder as folder_reader, graph, result_rows, results from .documents import Problem PROJECT_ID = re.compile(r'^[a-f0-9]{32}$') @@ -48,6 +51,7 @@ from_ref text NOT NULL, to_ref text NOT NULL, role text NOT NULL, PRIMARY KEY (from_ref, to_ref, role))''', 'CREATE INDEX IF NOT EXISTS edges_to ON {schema}.edges (to_ref)', + *result_rows.TABLES, ) # Later additive changes go here as ALTER TABLE ... ADD COLUMN IF NOT EXISTS. _MIGRATIONS = () @@ -179,6 +183,38 @@ def _list_definitions(root): return DiskListing(files, tuple(irregular)) +def _list_results(root): + """The results files on disk: ({benchmark name: bytes}, paths that are not plain results files).""" + files, irregular = {}, [] + root_fd = _open_root(root) + try: + top = dict(folder_reader.entries(root_fd)) + if folder_reader.RESULTS not in top: + return files, () + if top[folder_reader.RESULTS] != 'directory': + return files, (folder_reader.RESULTS,) + fd = os.open(folder_reader.RESULTS, folder_reader.DIRECTORY_FLAGS, dir_fd=root_fd) + try: + for name, entry_kind in folder_reader.entries(fd): + stem = name[:-len('.csv')] if name.endswith('.csv') else None + if entry_kind != 'file' or stem is None or not documents.is_name(stem): + irregular.append(f'{folder_reader.RESULTS}/{name}') + continue + try: + files[stem] = folder_reader.read(fd, name, folder_reader.RESULTS_LIMIT) + except folder_reader.Unsafe: + irregular.append(f'{folder_reader.RESULTS}/{name}') + finally: + os.close(fd) + finally: + os.close(root_fd) + return files, tuple(irregular) + + +def _results_path(benchmark): + return f'{folder_reader.RESULTS}/{benchmark}.csv' + + def _notes(root): """The set of note paths, as the checker's card rule needs them.""" found = folder_reader.Folder(root) @@ -312,22 +348,26 @@ def _attach(self, root, project, *, rebind, on_conflict): if state is not None and state['folder'] != root and not rebind: raise ProjectError(f'This project is bound to {state["folder"]}, not {root}; ' 'open it with rebind to move it here.', 'bound-elsewhere') - rows = {} + rows, recorded_results = {}, {} if exists: for reference, file_sha256, unsaved, removed in self._execute( f'SELECT {_REFERENCE_SQL}, file_sha256, unsaved, removed FROM {{schema}}.definitions'): rows[reference] = (file_sha256, unsaved or removed) + recorded_results = dict(self._execute('SELECT benchmark, file_sha256 FROM {schema}.results_files')) listing = _list_definitions(root) + results_on_disk, results_irregular = _list_results(root) on_disk = {reference: sha for reference, (sha, _) in rows.items() if sha is not None} code_root = project.get('code_root', '.') if (state is not None and not listing.irregular and listing.files == on_disk + and not results_irregular + and {name: _sha(raw) for name, raw in results_on_disk.items()} == recorded_results and state['name'] == project['name'] and state['code_root'] == code_root): if state['folder'] != root: self._execute('UPDATE {schema}.state SET folder = %s', (root,)) return - self._import(root, rows, on_conflict) + self._import(root, rows, on_conflict, results_on_disk, recorded_results) - def _import(self, root, rows, on_conflict): + def _import(self, root, rows, on_conflict, results_on_disk, recorded_results): report = check.check_folder(root) if not report.ok: raise ProjectError(f'The project folder {root} has errors; fix them and open it again.', 'invalid', @@ -369,6 +409,8 @@ def _import(self, root, rows, on_conflict): raise ProjectError('The folder no longer fits the unsaved edits held here; ' 'save or discard them first.', 'invalid', problems=problems) + changed_results, gone_results = self._results_to_import(disk, merged, results_on_disk, recorded_results) + project = report.project with self._connection.transaction(): self._create_schema() @@ -386,6 +428,19 @@ def _import(self, root, rows, on_conflict): 'WHERE directory = %s AND name = %s'), [(sha, *documents.parse_reference(reference)) for reference, sha in reseat]) self._write_edges(graph.edges({reference: d.document for reference, d in merged.items()})) + for reference in delete: + directory, name = documents.parse_reference(reference) + if directory == 'benchmarks': + result_rows.remove_benchmark(self._connection, self.schema, name) + for reference in take: + directory, name = documents.parse_reference(reference) + if directory == 'benchmarks' and reference in merged: + result_rows.prune(self._connection, self.schema, name, merged[reference].document) + for name in gone_results: + result_rows.forget_file(self._connection, self.schema, name) + for name, text in changed_results.items(): + result_rows.import_file(self._connection, self.schema, name, text, + merged[documents.reference('benchmarks', name)].document) self._execute('''INSERT INTO {schema}.state (singleton, project_id, name, folder, code_root, imported_at) VALUES (true, %s, %s, %s, %s, now()) ON CONFLICT (singleton) DO UPDATE SET project_id = EXCLUDED.project_id, @@ -393,6 +448,34 @@ def _import(self, root, rows, on_conflict): code_root = EXCLUDED.code_root, imported_at = EXCLUDED.imported_at''', (self.project_id, project['name'], root, project.get('code_root', '.'))) + def _results_to_import(self, disk, merged, results_on_disk, recorded_results): + """({benchmark: text} of new or changed results files, [benchmarks whose file is gone]). + + The files were read after the checker ran, so each is checked again + against its benchmark; a file that changed in between and is now wrong + refuses the open. A file whose benchmark is removed in the database + (not yet saved) is not imported. + """ + changed, problems = {}, [] + for name, raw in sorted(results_on_disk.items()): + reference = documents.reference('benchmarks', name) + if _sha(raw) == recorded_results.get(name) or reference not in merged: + continue + found = [Problem(severity, _results_path(name), pointer, message) + for severity, pointer, message in results.check_results( + raw, disk[reference].document if reference in disk else None)] + if reference not in disk: + found.append(Problem('error', _results_path(name), '', f'There is no {reference}.json for this summary.')) + if _errors(found): + problems.extend(_errors(found)) + continue + changed[name] = raw.decode('utf-8') + if problems: + raise ProjectError('A results file changed while the folder was being opened; open it again.', 'invalid', + problems=problems) + gone = sorted(set(recorded_results) - set(results_on_disk)) + return changed, gone + # ------------------------------------------------------------ reading def summary(self): @@ -445,18 +528,33 @@ def order(self): return graph.order(self._documents(removed=False)) def status(self): - """Unsaved and removed definitions, and files added, changed or missing on disk since the last import or save.""" + """Unsaved and removed definitions, and files added, changed or missing on disk since the last import or save. + + results_unsaved names the benchmarks whose summaries in the database + are not the results file as last imported or saved (save would write + or remove it); results_changed names the results files added, changed + or removed on disk since then. + """ state = self._state() rows = self._execute(f'SELECT {_REFERENCE_SQL}, file_sha256, unsaved, removed FROM {{schema}}.definitions').fetchall() listing = _list_definitions(state['folder']) recorded = {reference: sha for reference, sha, _, _ in rows if sha is not None} + texts = result_rows.file_texts(self._connection, self.schema) + results_on_disk, results_irregular = _list_results(state['folder']) + results_recorded = {name: recorded_sha for name, (_, recorded_sha) in texts.items() if recorded_sha is not None} + results_changed = sorted( + _results_path(name) for name in set(results_on_disk) | set(results_recorded) + if (_sha(results_on_disk[name]) if name in results_on_disk else None) != results_recorded.get(name)) return {'unsaved': sorted(reference for reference, _, unsaved, removed in rows if unsaved and not removed), 'removed': sorted(reference for reference, _, _, removed in rows if removed), 'added': sorted(set(listing.files) - set(recorded)), 'changed': sorted(reference for reference, sha in listing.files.items() if reference in recorded and recorded[reference] != sha), 'missing': sorted(set(recorded) - set(listing.files)), - 'irregular': list(listing.irregular)} + 'irregular': list(listing.irregular) + list(results_irregular), + 'results_unsaved': [name for name, (text, recorded_sha) in texts.items() + if result_rows.differs(text, recorded_sha)], + 'results_changed': results_changed} # ------------------------------------------------------------ editing @@ -504,6 +602,8 @@ def add(severity, where, pointer, message): OR {schema}.definitions.text IS DISTINCT FROM EXCLUDED.text''', (directory, name, candidate.kind, document['title'], text, Jsonb(document))) self._write_edges(graph.edges({reference: document}), [reference]) + if directory == 'benchmarks': + result_rows.prune(self._connection, self.schema, name, document) def remove_definition(self, reference): """Mark a definition removed, to be deleted from disk by save(); refused while anything uses it.""" @@ -526,15 +626,22 @@ def remove_definition(self, reference): self._execute('UPDATE {schema}.definitions SET removed = true WHERE directory = %s AND name = %s', (directory, name)) self._write_edges([], [reference]) + if directory == 'benchmarks': + result_rows.remove_benchmark(self._connection, self.schema, name) def save(self): - """Write unsaved definitions to their files and delete the files of removed ones (4.4). - - Before anything is written, every file to be replaced or deleted must - still have the SHA-256 recorded at import or last save (or already hold - exactly the text to be written, which is what an interrupted save - leaves). Otherwise nothing is written and ProjectError (code - changed-on-disk) names them. Returns the references written and deleted. + """Write unsaved definitions and changed results files, and delete the files of removed ones. + + Definitions follow section 4.4 of spec-m1-m2.md; results/.csv + is written with results.write_results when the database's summaries + make a text other than the file on disk, and removed when the + benchmark has no summary rows (spec-m3.md section 3). Before anything + is written, every file to be replaced or deleted must still have the + SHA-256 recorded at import or last save (or already hold exactly what + is to be written, which is what an interrupted save leaves). + Otherwise nothing is written and ProjectError (code changed-on-disk) + names them. Returns the references written and deleted, and the + benchmarks whose results files were written and deleted. """ root = self._state()['folder'] rows = self._execute(f'SELECT {_REFERENCE_SQL}, text, file_sha256, removed FROM {{schema}}.definitions ' @@ -545,6 +652,17 @@ def save(self): done = None if removed else _sha(text.encode('utf-8')) if current != file_sha256 and current != done: changed.append(reference) + results_plan = [] # (benchmark, text to write or None to delete, whether the file must change) + for name, (text, recorded) in result_rows.file_texts(self._connection, self.schema).items(): + current = _path_sha(root, folder_reader.RESULTS, f'{name}.csv', folder_reader.RESULTS_LIMIT) + target = None if text is None else result_rows.sha256_text(text) + if current == target: + if recorded != target: + results_plan.append((name, text, False)) + elif current != recorded: + changed.append(_results_path(name)) + else: + results_plan.append((name, text, True)) if changed: raise ProjectError('These files changed on disk since they were imported: ' + ', '.join(changed) + '. Open the project again to take or keep the changes.', 'changed-on-disk', @@ -557,7 +675,22 @@ def save(self): else: _write_file(root, reference, text.encode('utf-8')) written.append(reference) + results_written, results_deleted = [], [] + for name, text, must_change in results_plan: + if text is None: + if must_change: + _delete_path(root, folder_reader.RESULTS, f'{name}.csv') + results_deleted.append(name) + else: + if must_change: + _write_path(root, folder_reader.RESULTS, f'{name}.csv', text.encode('utf-8')) + results_written.append(name) with self._connection.transaction(): + for name, text, _ in results_plan: + if text is None: + result_rows.forget_file(self._connection, self.schema, name) + else: + result_rows.record_file(self._connection, self.schema, name, result_rows.sha256_text(text)) with self._connection.cursor() as cursor: if written: cursor.executemany(self._sql('UPDATE {schema}.definitions SET unsaved = false, ' @@ -567,7 +700,57 @@ def save(self): if deleted: cursor.executemany(self._sql('DELETE FROM {schema}.definitions WHERE directory = %s AND name = %s'), [documents.parse_reference(reference) for reference in deleted]) - return {'written': written, 'deleted': deleted} + return {'written': written, 'deleted': deleted, + 'results_written': results_written, 'results_deleted': results_deleted} + + # ------------------------------------------------------------ results + + def _benchmark_document(self, name): + row = self._execute("SELECT document FROM {schema}.definitions " + "WHERE directory = 'benchmarks' AND name = %s AND NOT removed", (name,)).fetchone() + return None if row is None else row[0] + + def _require_benchmark(self, benchmark, subject=None): + document = self._benchmark_document(benchmark) if documents.is_name(benchmark) else None + if document is None: + raise ProjectError(f'There is no benchmark benchmarks/{benchmark}.', 'not-found', + references=[f'benchmarks/{benchmark}']) + if subject is not None and subject not in {item.get('name') for item in document.get('subjects', [])}: + raise ProjectError(f'{subject!r} is not a subject of benchmarks/{benchmark}.', 'not-found', + references=[f'benchmarks/{benchmark}']) + return document + + def check_values(self, text, *, path=''): + """The problems of a tuldok_results_v1 values file against its benchmark (spec-m3.md section 1).""" + return result_rows.check_values(text, self._benchmark_document, path=path)[1] + + def import_values(self, text, *, path=''): + """Check a values file, then replace its (benchmark, subject)'s values and summaries in one transaction. + + Raises ProjectError (code invalid, with the problems) and changes + nothing when the file has any problem. Returns the benchmark, the + subject, and how many values and summary rows it now holds. + """ + with self._connection.transaction(): + found, problems = result_rows.check_values(text, self._benchmark_document, path=path) + if problems: + raise ProjectError(f'{path or "The values file"} cannot be imported; see the problems.', 'invalid', + problems=problems) + return result_rows.replace_values(self._connection, self.schema, found) + + def result_summaries(self, benchmark, subject=None, metric=None, group=None): + """The summary rows of a benchmark as result_rows.StoredSummary (a results.SummaryRow and its origin).""" + self._require_benchmark(benchmark) + return result_rows.summaries(self._connection, self.schema, benchmark, subject, metric, group) + + def result_values(self, benchmark, subject, metric=None, offset=0, limit=200): + """{'total', 'values'}: one page of a subject's per-case values; total 0 when this machine holds none.""" + self._require_benchmark(benchmark, subject) + return result_rows.values(self._connection, self.schema, benchmark, subject, metric, offset, limit) + + def results_overview(self): + """Per benchmark: subjects with results, subjects with values, rows, and whether it differs from its file.""" + return result_rows.overview(self._connection, self.schema) def close(self): """Close the connection, which also releases the project's lock.""" @@ -585,6 +768,11 @@ def __exit__(self, *exc): def _file_sha(root, reference): """SHA-256 of the definition file on disk, None when it does not exist, 'unreadable' when it is not a plain file.""" directory, name = documents.parse_reference(reference) + return _path_sha(root, directory, f'{name}.json', folder_reader.DEFINITION_LIMIT) + + +def _path_sha(root, directory, filename, limit): + """SHA-256 of directory/filename on disk, None when it does not exist, 'unreadable' when it is not a plain file.""" try: fd = os.open(os.path.join(root, directory), folder_reader.DIRECTORY_FLAGS) except FileNotFoundError: @@ -592,9 +780,9 @@ def _file_sha(root, reference): except OSError: return 'unreadable' try: - return _sha(folder_reader.read(fd, f'{name}.json', folder_reader.DEFINITION_LIMIT)) + return _sha(folder_reader.read(fd, filename, limit)) except folder_reader.Unsafe: - if not os.path.lexists(os.path.join(root, directory, f'{name}.json')): + if not os.path.lexists(os.path.join(root, directory, filename)): return None return 'unreadable' finally: @@ -602,18 +790,22 @@ def _file_sha(root, reference): def _write_file(root, reference, data): - """Replace the file atomically: a temporary file in the same directory, fsync, rename, fsync the directory.""" directory, name = documents.parse_reference(reference) + _write_path(root, directory, f'{name}.json', data) + + +def _write_path(root, directory, filename, data): + """Replace the file atomically: a temporary file in the same directory, fsync, rename, fsync the directory.""" target_directory = os.path.join(root, directory) os.makedirs(target_directory, exist_ok=True) - fd, temporary = tempfile.mkstemp(dir=target_directory, prefix=f'.{name}.', suffix='.tmp') + fd, temporary = tempfile.mkstemp(dir=target_directory, prefix=f'.{filename}.', suffix='.tmp') try: with os.fdopen(fd, 'wb') as handle: handle.write(data) handle.flush() os.fsync(handle.fileno()) os.chmod(temporary, 0o644) - os.replace(temporary, os.path.join(target_directory, f'{name}.json')) + os.replace(temporary, os.path.join(target_directory, filename)) except BaseException: if os.path.lexists(temporary): os.unlink(temporary) @@ -623,9 +815,13 @@ def _write_file(root, reference, data): def _delete_file(root, reference): directory, name = documents.parse_reference(reference) + _delete_path(root, directory, f'{name}.json') + + +def _delete_path(root, directory, filename): target_directory = os.path.join(root, directory) try: - os.unlink(os.path.join(target_directory, f'{name}.json')) + os.unlink(os.path.join(target_directory, filename)) except FileNotFoundError: return _sync_directory(target_directory) From f352f5ec86dc433156771a852baa7bf5a1610d41 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Tue, 10 Nov 2026 16:06:19 -0700 Subject: [PATCH 012/131] feat(project): answer charts from stored summaries and draw them charts.chart_data answers a chart definition (ranking, tradeoff, progression, comparison) from the summary table with SQL only; a test makes every file read fail while it runs. render_svg draws the data as a self-contained SVG in the workspace design tokens, light or dark, and render_report builds one HTML page for a project: where it stands, every chart, the results overview and the definitions by kind. Command line: chart and report; results, values and chart accept a bare name or a reference. The contract documents results, values files, the chart forms and the commands. Co-Authored-By: Claude Fable 5.2 --- docs/contracts/project-folder.md | 226 ++++- .../project/charts/rollout-comparison.json | 9 + .../project/charts/rollout-progression.json | 8 + tests/test_tuldok_project_charts.py | 327 ++++++ tests/test_tuldok_project_cli.py | 96 +- tests/test_tuldok_project_result_rows.py | 4 +- tests/test_tuldok_project_store.py | 19 +- tuldok_project/__main__.py | 130 ++- tuldok_project/charts.py | 948 ++++++++++++++++++ 9 files changed, 1741 insertions(+), 26 deletions(-) create mode 100644 tests/fixtures/tuldok_project/minimal/project/charts/rollout-comparison.json create mode 100644 tests/fixtures/tuldok_project/minimal/project/charts/rollout-progression.json create mode 100644 tests/test_tuldok_project_charts.py create mode 100644 tuldok_project/charts.py diff --git a/docs/contracts/project-folder.md b/docs/contracts/project-folder.md index c871b2b3..a619d491 100644 --- a/docs/contracts/project-folder.md +++ b/docs/contracts/project-folder.md @@ -2,7 +2,8 @@ Owner: the package `tuldok_project/` (`folder.py` reads the folder, `documents.py` and `schemas/*.json` check single files, `check.py` applies every rule, -`results.py` owns summary files). The format names are `tuldok_project_v1` for +`results.py` owns summary files, `store.py` and `result_rows.py` the database +copy and its results, `charts.py` charts and the report page). The format names are `tuldok_project_v1` for the folder and `tuldok_definition_v1` for each definition. A project folder describes a piece of research as a set of small JSON files that @@ -587,7 +588,7 @@ Options: | Option | Commands | Meaning | | --- | --- | --- | | `--database-url URL` | all but `check` | The Postgres database. Without it, the `TULDOK_DATABASE_URL` environment variable is used; with neither, the command stops with exit status 2. | -| `--json` | `open`, `list`, `show`, `graph`, `status`, `save` | Print one JSON document with the same content as the text. | +| `--json` | `open`, `list`, `show`, `graph`, `status`, `save`, `results`, `values`, `import-values`, `chart` | Print one JSON document with the same content as the text. | | `--rebind` | all that open | The copy is bound to the folder it was first opened from. Opening the same project from another path is refused unless `--rebind` is given, which binds the copy to the new path. | | `--keep` | all that open | Where a file changed on disk and the same definition has unsaved edits, keep the edits; the changed file becomes the version that `save` replaces. | | `--discard` | all that open | Where a file changed on disk and the same definition has unsaved edits, drop the edits and take the file. | @@ -611,12 +612,227 @@ datasets/waves cannot be set; see the problems. error datasets/waves.json /title Add the required field 'title'. ``` +## Results in the database + +When a project is opened, every results file is imported into the database copy +as summary rows, one row per line of the file. Each summary row has an origin: + +| Origin | Where the row comes from | +| --- | --- | +| `file` | the line of `results/.csv` | +| `values` | computed from per-case values imported on this machine (see [Values files](#values-files)), with the statistics of [Results files](#results-files) | + +For one benchmark and subject, when the database holds per-case values, all of +that subject's summary rows are computed from them and have origin `values`; +otherwise they come from the results file. The computed rows are one row with an +empty group over all of the subject's values of a metric, and one row for each +single group key and value (`cells_per_metre=8`) over the values that carry it. +There are no rows for combinations of keys. + +Opening notices a results file that is new, changed or gone, the same way it +notices a changed definition file, and replaces that benchmark's `file` rows +with the file's lines, except for subjects that have values here. + +`save` writes `results/.csv` from the summary rows of each benchmark +whose rows differ from the file, and removes the file of a benchmark that has no +rows left. Like definitions, it writes nothing when a results file changed on +disk since it was imported. `status` lists `results unsaved` (benchmarks whose +rows differ from their file) and `results changed on disk`. Removing a benchmark +removes its summary rows and values; removing a subject from a benchmark removes +that subject's rows. + +Charts and the report read only these rows. A copy of the folder with its +`results/` files draws every chart; no run directory or values file is needed. + +## Values files + +A benchmark run writes one values file per benchmark and subject: the measured +value of every case and metric. Values files are not part of the project folder; +they stay on the machine that ran the benchmark, and `import-values` brings them +into the database copy. Format `tuldok_results_v1`, strict JSON as in +[JSON rules](#json-rules), at most 64 MiB: + +| Field | Rule | +| --- | --- | +| `format` | exactly `tuldok_results_v1` | +| `benchmark` | the name of a benchmark of the project | +| `subject` | one of that benchmark's subject names | +| `commit` | 40 lowercase hexadecimal characters, or empty | +| `produced` | a date `YYYY-MM-DD` or a time `YYYY-MM-DDTHH:MM:SSZ` | +| `values` | a list of at least one value | + +Each value: + +| Field | Required | Rule | +| --- | --- | --- | +| `case` | yes | 1 to 200 characters | +| `metric` | yes | a metric id of the benchmark | +| `value` | yes | a finite number, or `null` for a value that was not measured | +| `reason` | when `value` is `null`; otherwise not allowed | 1 to 400 characters: why there is no value | +| `group` | no | an object whose keys are in the benchmark's `summary.group_by`; each value a string, number or boolean, without `;`, `=` or a line break | + +Group values are stored as text: strings as written, `true` and `false`, and +numbers as Python's `repr` writes them (`8` stays `8`, `8.0` stays `8.0`). +(`case`, `metric`, `group`) is unique within a file. Unknown fields are refused. + +Example, `rollout-stepper-k1.json`: + +```json +{ + "format": "tuldok_results_v1", + "benchmark": "rollout", + "subject": "stepper-k1", + "commit": "0123456789abcdef0123456789abcdef01234567", + "produced": "2026-11-10", + "values": [ + {"case": "scene-01", "metric": "rmse", "value": 0.25, "group": {"horizon": 1}}, + {"case": "scene-01", "metric": "rmse", "value": 1.0, "group": {"horizon": 8}}, + {"case": "scene-01", "metric": "seconds", "value": 1.0}, + {"case": "scene-02", "metric": "rmse", "value": 0.5, "group": {"horizon": 1}}, + {"case": "scene-02", "metric": "rmse", "value": null, "reason": "diverged before step 8", "group": {"horizon": 8}}, + {"case": "scene-02", "metric": "seconds", "value": 1.5} + ] +} +``` + +## Reading results + +| Command | Does | +| --- | --- | +| `results [BENCHMARK] [--subject S] [--metric M] [--group G]` | Without a benchmark, one line per benchmark: subjects with results, subjects with values on this machine, summary rows by origin, and whether the rows differ from the results file. With a benchmark, its summary rows; `--group` keeps the rows of one group key, and `--group ''` the rows over all cases. | +| `values BENCHMARK --subject S [--metric M] [--limit N]` | The per-case values held on this machine for one subject, at most `N` (default 200), or a sentence saying there are none. | +| `import-values FILE...` | Imports values files. Every file is checked first; if any has a problem, the problems are printed and nothing is imported. Each file replaces its subject's values and summary rows in one step. | + +`BENCHMARK` is a benchmark's name (`rollout`) or its reference +(`benchmarks/rollout`). Anything else is a usage error. Example, with the values +file above: + +``` +$ .venv/bin/python -m tuldok_project import-values FOLDER rollout-stepper-k1.json +imported benchmarks/rollout stepper-k1 6 values 4 summary rows +$ .venv/bin/python -m tuldok_project results FOLDER benchmarks/rollout --subject stepper-k1 +subject metric group count unavailable mean median p10 p90 min max produced origin +stepper-k1 rmse - 3 1 0.5833 0.5 0.3 0.9 0.25 1 2026-11-10 values +stepper-k1 rmse horizon=1 2 0 0.375 0.375 0.275 0.475 0.25 0.5 2026-11-10 values +stepper-k1 rmse horizon=8 1 1 1 1 1 1 1 1 2026-11-10 values +stepper-k1 seconds - 2 0 1.25 1.25 1.05 1.45 1 1.5 2026-11-10 values +$ .venv/bin/python -m tuldok_project values FOLDER rollout --subject stepper-k1 --metric rmse +case metric group value +scene-01 rmse horizon=1 0.25 +scene-01 rmse horizon=8 1.0 +scene-02 rmse horizon=1 0.5 +scene-02 rmse horizon=8 none (diverged before step 8) +``` + +A refused import prints each problem on standard error in the form `check` +uses and exits with status 1: + +``` +error bad.json /values/0/reason A null value needs a reason of 1 to 400 characters. +Nothing was imported: 1 problem in the values files. +``` + +## Charts and the report + +| Command | Does | +| --- | --- | +| `chart CHART [--svg FILE] [--theme light\|dark]` | Prints the chart's data as text, or as JSON with `--json`. With `--svg`, also writes the drawing to `FILE`. | +| `report --output FILE [--theme light\|dark]` | Writes one HTML page of the project to `FILE`. | + +`CHART` is a chart's name (`rollout-ranking`) or its reference +(`charts/rollout-ranking`). `--theme` picks the light or the dark colours; +the default is light. + +A chart is answered from the summary rows in the database and the definitions, +never from a file. It uses the chart's `statistic` (default `median`) of each +subject's rows for its `metric`, over all cases, or with `group` set one panel +per value of that group key, ordered as numbers when every value is a number and +as text otherwise. The subjects are the chart's `subjects`, or every subject of +the benchmark. A subject with no row, with a row whose `count` is 0, or whose +row lacks the statistic is not drawn; it is listed as missing, and the drawing +says how many are missing and names them. + +"Best" follows the metric's `better`: `lower` and `none` put the lowest value +first, `higher` the highest. + +| Form | What it shows | +| --- | --- | +| `ranking` | One horizontal bar per subject, best at the top, each labelled with the subject's title and its value. Ties are ordered by subject name. The drawing grows with the number of subjects. | +| `tradeoff` | One point per subject at (`metric_x`, `metric`). A subject lacking either value is missing. The frontier is the set of subjects that no other subject is at least as good as on both metrics and better than on one; a step line joins them, and they carry labels where labels fit without overlapping. | +| `progression` | The subjects in the order they were trained: by the `trained_at` label of the subject's recipe, earliest first, then the subjects without one by name. A step line shows the best value so far, and the subjects that set a new best carry labels where they fit. | +| `comparison` | A table of numbers: one row per subject, one column per metric of the benchmark, the best value in each column marked. Rows follow the chart's `subjects`, or the ranking of `metric` when the chart has none. A subject with no value for any metric is missing. | + +An axis is logarithmic when all its values are positive and the largest is at +least 100 times the smallest; otherwise it is linear (bars always start at +zero). Axes carry the metric's title and units, and numbers show three +significant digits, very small and very large ones as `2.43e-6`. A chart with +no values says so in place of the plot. + +The drawing is one SVG document with no scripts and no links, the same bytes +for the same data. Every bar, point and number carries the subject's full title +and its value as a tooltip; long subject titles are cut with an ellipsis. + +Example: + +``` +$ .venv/bin/python -m tuldok_project chart FOLDER rollout-ranking --svg ranking.svg +chart charts/rollout-ranking ranking +title Rollout error by subject +benchmark benchmarks/rollout +metric rmse: median Rollout RMSE (m/s), lower is better +group horizon + +horizon = 1 +rank subject value count +1 stepper-k2 0.3125 4 +2 stepper-k1 0.375 2 +3 early-fit 0.625 4 + +horizon = 8 +rank subject value count +1 stepper-k1 1 1 +2 stepper-k2 1.25 4 + +1 of 3 subjects has no value: early-fit. +Wrote ranking.svg (6091 bytes). +``` + +With `--json`, `chart` prints one object: + +| Field | Meaning | +| --- | --- | +| `chart`, `title`, `description`, `form`, `benchmark`, `statistic`, `group` | from the chart definition; `group` is null without one | +| `metric`, `metric_x` | `{"id", "title", "units", "better"}`; `metric_x` is null except for a `tradeoff` | +| `subject_count` | how many subjects the chart covers | +| `series` | all forms but `comparison`: one entry per group value (one entry with group `""` without a group), each `{"group", "points", "missing"}` | +| `metrics`, `rows` | `comparison` only: every metric of the benchmark, and one row per subject `{"subject", "title", "recipe", "group", "values"}`, `values` mapping each metric id to its number or null | +| `missing` | the names of the subjects not drawn, in the chart's subject order; with a group, those missing in any panel | + +A point is `{"subject", "title", "recipe", "value", "count", "unavailable", +"produced"}`, where `recipe` is the subject's recipe reference or null. A +`tradeoff` point adds `x` and `frontier`; a `progression` point adds `position` +(from 0), `best_so_far` and `trained_at`. + +The report page, from `report`, reads top to bottom: the project's name, folder +and id; how many definitions there are of each kind and in each state, and how +many benchmarks have results; every chart with its title, a one-line note on +what it shows and how many subjects are missing, and its drawing; the results +overview; then the definitions of each kind with their states, each kind in a +closed section that opens on a click. The page is one file with its style +embedded and its charts drawn inline, no scripts and no links, so it can be +sent or opened anywhere. + +``` +$ .venv/bin/python -m tuldok_project report FOLDER --output report.html --theme dark +Wrote report.html (4 charts, 24626 bytes). +``` + ## What the format does not do yet -The folder is checked and can be opened, edited and saved through the database -copy, nothing more. Tuldok does not yet run any command, +The folder is checked, can be opened, edited and saved through the database +copy, and its results can be read and drawn, nothing more. Tuldok does not yet run any command, estimate, install an environment, compare installed package versions, write -settings files, import results files or read the contents of notes. The `run`, `resources`, +settings files or read the contents of notes. The `run`, `resources`, `estimate`, `install` and `settings` fields record what a later Tuldok will use. Background: [the design notes for this format](../plans/definition-first-projects/). diff --git a/tests/fixtures/tuldok_project/minimal/project/charts/rollout-comparison.json b/tests/fixtures/tuldok_project/minimal/project/charts/rollout-comparison.json new file mode 100644 index 00000000..f0f23938 --- /dev/null +++ b/tests/fixtures/tuldok_project/minimal/project/charts/rollout-comparison.json @@ -0,0 +1,9 @@ +{ + "format": "tuldok_definition_v1", + "kind": "chart", + "title": "Every metric side by side", + "benchmark": "benchmarks/rollout", + "form": "comparison", + "metric": "rmse", + "statistic": "p90" +} diff --git a/tests/fixtures/tuldok_project/minimal/project/charts/rollout-progression.json b/tests/fixtures/tuldok_project/minimal/project/charts/rollout-progression.json new file mode 100644 index 00000000..344da50a --- /dev/null +++ b/tests/fixtures/tuldok_project/minimal/project/charts/rollout-progression.json @@ -0,0 +1,8 @@ +{ + "format": "tuldok_definition_v1", + "kind": "chart", + "title": "Rollout error in training order", + "benchmark": "benchmarks/rollout", + "form": "progression", + "metric": "rmse" +} diff --git a/tests/test_tuldok_project_charts.py b/tests/test_tuldok_project_charts.py new file mode 100644 index 00000000..c35d25c2 --- /dev/null +++ b/tests/test_tuldok_project_charts.py @@ -0,0 +1,327 @@ +"""Charts and the report page (spec-m3.md section 5): chart_data, render_svg and render_report. + +The frontier, number formatting and drawing are tested on hand-made data +without a database. chart_data and the report run only when +TULDOK_DATABASE_URL names a disposable cluster: each test copies +tests/fixtures/tuldok_project/minimal with a fresh project id +(test_tuldok_project_store.StoreCase) and drops that project's schema +afterwards. The expectations were worked out by hand from the fixture's +results/rollout.csv. +""" +import builtins +import io +import json +import os +from pathlib import Path +import sys +import unittest +from unittest import mock +import xml.etree.ElementTree as ElementTree + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) +sys.path.insert(0, str(Path(__file__).resolve().parent)) + +from tuldok_project import charts # noqa: E402 +from tuldok_project.store import ProjectError # noqa: E402 +from test_tuldok_project_store import StoreCase # noqa: E402 + +DATABASE = os.environ.get('TULDOK_DATABASE_URL') +SVG = '{http://www.w3.org/2000/svg}' +METRIC = {'id': 'rmse', 'title': 'Rollout RMSE', 'units': 'm/s', 'better': 'lower'} + + +def point(subject, value, **extra): + return {'subject': subject, 'title': extra.pop('title', subject.title()), 'recipe': None, 'value': value, + 'count': 4, 'unavailable': 0, 'produced': '2026-11-02', **extra} + + +def ranking(points, *, missing=(), title='Error by subject', group=None, series=None): + return {'chart': 'charts/error-ranking', 'title': title, 'description': None, 'form': 'ranking', + 'benchmark': 'benchmarks/rollout', 'statistic': 'median', 'group': group, 'metric': METRIC, + 'metric_x': None, 'subject_count': len(points) + len(missing), + 'series': series or [{'group': '', 'points': points, 'missing': list(missing)}], 'missing': list(missing)} + + +def parse(text): + """The root element of an SVG document; fails the test when it is not well-formed.""" + root = ElementTree.fromstring(text) + assert root.tag == SVG + 'svg', root.tag + return root + + +def shown(element): + """The visible text of an SVG text element, without its tooltip.""" + tooltip = element.find(SVG + 'title') + return (element.text or '') if tooltip is None else (tooltip.tail or '') + + +def texts(root): + return [shown(element) for element in root.iter(SVG + 'text')] + + +class Numbers(unittest.TestCase): + + def test_three_significant_digits_and_compact_small_and_large(self): + cases = {0.0123: '0.0123', 2.4321e-6: '2.43e-6', 0.5: '0.500', 12345: '12300', 123456: '1.23e5', + 9.996: '10.0', -0.00042: '-4.20e-4', 0.0009999: '0.00100', 0: '0', 1.0: '1.00', None: '-'} + for value, text in cases.items(): + self.assertEqual(charts.format_number(value), text, value) + + +class Frontier(unittest.TestCase): + """A point is on the frontier when no other point is at least as good on both and better on one.""" + + def test_lower_is_better_on_both_with_ties(self): + points = [(1.0, 5.0), # fastest + (2.0, 3.0), # on the frontier + (2.0, 3.0), # identical to the previous one: neither beats the other + (2.0, 4.0), # same x as the previous ones, worse y: beaten + (3.0, 3.0), # same y, slower: beaten + (4.0, 1.0), # most accurate + (5.0, 6.0)] # beaten by all + self.assertEqual(charts.frontier(points, 'lower', 'lower'), [True, True, True, False, False, True, False]) + + def test_direction_follows_better_and_none_counts_as_lower(self): + points = [(1.0, 1.0), (2.0, 2.0), (3.0, 0.5)] + self.assertEqual(charts.frontier(points, 'higher', 'lower'), [True, True, False]) + self.assertEqual(charts.frontier(points, 'none', 'none'), [True, False, True]) + self.assertEqual(charts.frontier(points, 'lower', 'higher'), [False, False, True]) + self.assertEqual(charts.frontier([], 'lower', 'lower'), []) + self.assertEqual(charts.frontier([(1.0, 1.0)], 'lower', 'lower'), [True]) + + +class Drawing(unittest.TestCase): + + def test_well_formed_self_contained_and_deterministic_in_both_themes(self): + data = ranking([point('b', 0.3125), point('a', 0.5), point('c', 0.625)], missing=['d']) + light = charts.render_svg(data) + dark = charts.render_svg(data, theme='dark') + self.assertEqual(light, charts.render_svg(json.loads(json.dumps(data)))) + self.assertNotEqual(light, dark) + for text in (light, dark): + root = parse(text) + self.assertTrue(root.get('viewBox').startswith('0 0 ')) + self.assertEqual(root.find(SVG + 'title').text, 'Error by subject') + self.assertTrue(root.get('font-family').startswith("'Ubuntu Sans'")) + self.assertIn('sans-serif', root.get('font-family')) + for forbidden in ('<script', 'href', 'url(', '@import', 'http://', 'https://'): + self.assertNotIn(forbidden, text.replace('xmlns="http://www.w3.org/2000/svg"', ''), forbidden) + self.assertIn('#ffffff', light) # light surface + self.assertIn('#171c22', dark) # dark surface + self.assertIn('#e6eaf0', dark) # dark ink, so text reads on the dark surface + self.assertNotIn('#1b2330', dark) # and no light-theme ink is left behind + shown = texts(parse(light)) + self.assertIn('0.312', shown) + self.assertTrue(any('Not drawn, no value: d' in line for line in shown), shown) + with self.assertRaises(ValueError): + charts.render_svg(data, theme='blue') + + def test_text_is_escaped(self): + data = ranking([point('a', 1.0, title='<b> & "quoted" \x01')], title='Fish & <chips>') + root = parse(charts.render_svg(data)) + self.assertEqual(root.find(SVG + 'title').text, 'Fish & <chips>') + self.assertIn('<b> & "quoted" ', texts(root)) + + def test_an_empty_chart_says_so(self): + for form in ('ranking', 'tradeoff', 'progression'): + data = {**ranking([], missing=['a', 'b']), 'form': form, + 'metric_x': {**METRIC, 'id': 'seconds', 'title': 'Time'} if form == 'tradeoff' else None, + 'series': []} + shown = ' '.join(texts(parse(charts.render_svg(data)))) + self.assertIn('No results yet: none of the 2 subjects of benchmarks/rollout', shown, form) + data = {**ranking([]), 'form': 'comparison', 'metrics': [METRIC], 'rows': [], 'subject_count': 0} + self.assertIn('has no subjects', ' '.join(texts(parse(charts.render_svg(data))))) + + def test_long_labels_are_cut_and_kept_whole_in_the_tooltip(self): + long_title = 'A subject title of exactly one hundred characters, which is far too long for the label column' + '.' * 7 + self.assertEqual(len(long_title), 100) + root = parse(charts.render_svg(ranking([point('a', 1.0, title=long_title), point('b', 2.0)]))) + labels = [element for element in root.iter(SVG + 'text') if element.find(SVG + 'title') is not None + and element.find(SVG + 'title').text.startswith(long_title)] + self.assertEqual(len(labels), 1) + cut = shown(labels[0]) + self.assertTrue(cut.endswith('…'), cut) + self.assertLess(len(cut), 50) + + def test_a_ranking_grows_with_its_rows(self): + def height(count): + data = ranking([point(f's{index:03d}', 10.0 + index) for index in range(count)]) + return float(parse(charts.render_svg(data)).get('height')) + + self.assertGreater(height(150), height(10) + 140 * 17) + root = parse(charts.render_svg(ranking([point(f's{index:03d}', 10.0 + index) for index in range(150)]))) + self.assertEqual(len([element for element in root.iter(SVG + 'path')]), 150) # one bar per subject + + def test_log_axis_when_values_span_a_factor_of_100(self): + log = texts(parse(charts.render_svg(ranking([point('a', 2.43e-6), point('b', 0.5)])))) + self.assertIn('1e-6', log) + self.assertIn('2.43e-6', log) + self.assertTrue(any('log scale' in line for line in log)) + linear = texts(parse(charts.render_svg(ranking([point('a', 2.0), point('b', 150.0)])))) + self.assertFalse(any('log scale' in line for line in linear)) + self.assertIn('0', linear) # bars start from zero on a linear axis + negative = texts(parse(charts.render_svg(ranking([point('a', -1.0), point('b', 500.0)])))) + self.assertFalse(any('log scale' in line for line in negative)) + + def test_grouped_series_draw_one_panel_each(self): + series = [{'group': '1', 'points': [point('a', 1.0), point('b', 2.0)], 'missing': []}, + {'group': '8', 'points': [point('a', 3.0)], 'missing': ['b']}] + shown = texts(parse(charts.render_svg(ranking([], group='horizon', series=series, missing=['b'])))) + self.assertIn('horizon = 1', shown) + self.assertIn('horizon = 8', shown) + self.assertIn('No value: b', shown) + + +@unittest.skipUnless(DATABASE, 'TULDOK_DATABASE_URL is not set; database tests need a disposable cluster.') +class ChartData(StoreCase): + + def setUp(self): + super().setUp() + self.project = self.open() + + def points(self, data, series=0): + return [(item['subject'], item['value']) for item in data['series'][series]['points']] + + def test_ranking_by_group_best_first_with_missing(self): + data = charts.chart_data(self.project, 'charts/rollout-ranking') + self.assertEqual((data['form'], data['benchmark'], data['statistic'], data['group']), + ('ranking', 'benchmarks/rollout', 'median', 'horizon')) + self.assertEqual(data['metric'], METRIC) + self.assertIsNone(data['metric_x']) + self.assertEqual([series['group'] for series in data['series']], ['1', '8']) + self.assertEqual(self.points(data, 0), [('stepper-k2', 0.3125), ('stepper-k1', 0.5), ('early-fit', 0.625)]) + # early-fit's horizon=8 row has count 0: it is missing, not a point at zero. + self.assertEqual(self.points(data, 1), [('stepper-k2', 1.25), ('stepper-k1', 2.0)]) + self.assertEqual(data['series'][1]['missing'], ['early-fit']) + self.assertEqual(data['missing'], ['early-fit']) + first = data['series'][0]['points'][0] + self.assertEqual(first, {'subject': 'stepper-k2', 'title': 'Stepper k2', 'recipe': 'recipes/stepper-k2', + 'value': 0.3125, 'count': 4, 'unavailable': 0, 'produced': '2026-11-02T10:15:00Z'}) + self.assertEqual(charts.chart_data(self.project, 'rollout-ranking'), data) # a bare name works too + + def test_tradeoff_sorted_by_x_with_its_frontier(self): + data = charts.chart_data(self.project, 'charts/speed-accuracy') + self.assertEqual(data['metric_x']['id'], 'seconds') + self.assertEqual(len(data['series']), 1) + self.assertEqual(data['series'][0]['group'], '') + found = [(item['subject'], item['x'], item['value'], item['frontier']) for item in data['series'][0]['points']] + # stepper-k2 is both faster and more accurate than the other two. + self.assertEqual(found, [('stepper-k2', 1.375, 0.5, True), ('stepper-k1', 1.75, 0.875, False), + ('early-fit', 2.5, 0.625, False)]) + self.assertEqual(data['missing'], []) + + def test_progression_in_training_order_with_best_so_far(self): + data = charts.chart_data(self.project, 'charts/rollout-progression') + found = [(item['position'], item['subject'], item['trained_at'], item['value'], item['best_so_far']) + for item in data['series'][0]['points']] + # early-fit has a trained_at label; the two steppers have none and follow by name. + self.assertEqual(found, [(0, 'early-fit', '2026-03-14', 0.625, 0.625), + (1, 'stepper-k1', None, 0.875, 0.625), + (2, 'stepper-k2', None, 0.5, 0.5)]) + + def test_comparison_rows_in_ranking_order_or_the_charts_own(self): + data = charts.chart_data(self.project, 'charts/rollout-comparison') + self.assertNotIn('series', data) + self.assertEqual([metric['id'] for metric in data['metrics']], ['rmse', 'seconds']) + self.assertEqual([(row['subject'], row['values']) for row in data['rows']], + [('early-fit', {'rmse': 0.925, 'seconds': 2.9}), + ('stepper-k2', {'rmse': 1.65, 'seconds': 1.675}), + ('stepper-k1', {'rmse': 2.65, 'seconds': 2.35})]) + self.edit('charts/rollout-comparison', lambda d: d.update(subjects=['stepper-k1', 'early-fit'])) + data = charts.chart_data(self.project, 'charts/rollout-comparison') + self.assertEqual([row['subject'] for row in data['rows']], ['stepper-k1', 'early-fit']) + + def edit(self, reference, change): + path = self.folder / f'{reference}.json' + document = json.loads(path.read_text(encoding='utf-8')) + change(document) + self.project.set_definition(reference, json.dumps(document, indent=2) + '\n') + + def test_higher_is_better_and_a_subject_without_rows(self): + def change(document): + document['metrics'][0]['better'] = 'higher' + document['subjects'].append({'name': 'stepper-k3', 'title': 'Stepper k3'}) + + self.edit('benchmarks/rollout', change) + data = charts.chart_data(self.project, 'charts/rollout-progression') + self.assertEqual([item['best_so_far'] for item in data['series'][0]['points']], [0.625, 0.875, 0.875]) + self.assertEqual(data['missing'], ['stepper-k3']) + self.edit('charts/rollout-ranking', lambda d: d.pop('subjects')) + data = charts.chart_data(self.project, 'charts/rollout-ranking') + self.assertEqual(self.points(data, 0), [('early-fit', 0.625), ('stepper-k1', 0.5), ('stepper-k2', 0.3125)]) + self.assertEqual(data['missing'], ['early-fit', 'stepper-k3']) + tradeoff = charts.chart_data(self.project, 'charts/speed-accuracy') + # Higher error now counts as better: stepper-k1 is faster than early-fit and higher, so it beats it. + self.assertEqual({item['subject']: item['frontier'] for item in tradeoff['series'][0]['points']}, + {'stepper-k2': True, 'stepper-k1': True, 'early-fit': False}) + + def test_values_imported_here_answer_the_same_chart(self): + before = charts.chart_data(self.project, 'charts/speed-accuracy') + for path in sorted((self.base / 'values').glob('*.json')): + self.project.import_values(path.read_text(encoding='utf-8')) + self.assertEqual(charts.chart_data(self.project, 'charts/speed-accuracy'), before) + + def test_unknown_chart(self): + for reference in ('charts/nothing', 'nothing', 'recipes/early-fit', '../x'): + with self.assertRaises(ProjectError) as caught: + charts.chart_data(self.project, reference) + self.assertEqual(caught.exception.code, 'not-found') + + def test_chart_data_opens_no_file(self): + """Every chart is answered while any attempt to open a file fails.""" + references = [row['reference'] for row in self.project.definitions(kind='chart')] + expected = [charts.chart_data(self.project, reference) for reference in references] # also loads lazy imports + opened = [] + + def refuse(*arguments, **keywords): + opened.append(arguments[:1]) + raise AssertionError(f'chart_data opened a file: {arguments[:1]}') + + with mock.patch.object(builtins, 'open', refuse), mock.patch.object(io, 'open', refuse), \ + mock.patch.object(io, 'FileIO', refuse), mock.patch.object(os, 'open', refuse), \ + mock.patch.object(os, 'scandir', refuse), mock.patch.object(os, 'listdir', refuse), \ + mock.patch.object(Path, 'open', refuse), mock.patch.object(Path, 'read_text', refuse), \ + mock.patch.object(Path, 'read_bytes', refuse): + answered = [charts.chart_data(self.project, reference) for reference in references] + self.assertEqual(opened, []) + self.assertEqual(answered, expected) + + +@unittest.skipUnless(DATABASE, 'TULDOK_DATABASE_URL is not set; database tests need a disposable cluster.') +class Report(StoreCase): + + def test_one_self_contained_page_with_every_chart(self): + project = self.open() + light = charts.render_report(project) + dark = charts.render_report(project, theme='dark') + self.assertEqual(light, charts.render_report(project)) + self.assertNotEqual(light, dark) + for page in (light, dark): + root = ElementTree.fromstring(page.split('\n', 1)[1]) # well-formed after the doctype line + self.assertEqual(root.tag, 'html') + self.assertTrue(page.startswith('<!DOCTYPE html>\n')) + body = page.replace('xmlns="http://www.w3.org/2000/svg"', '') + for forbidden in ('<script', 'href', 'src=', 'url(', '@import', 'http://', 'https://', '<link'): + self.assertNotIn(forbidden, body, forbidden) + figures = root.findall('.//figure') + self.assertEqual(len(figures), 4) + self.assertTrue(all(figure.find(SVG + 'svg') is not None for figure in figures)) + headings = [element.text for element in root.iter('h3')] + self.assertEqual(headings, ['Every metric side by side', 'Rollout error in training order', + 'Rollout error by subject', 'Error against time']) + details = root.findall('.//details') + self.assertEqual(len(details), 7) + self.assertTrue(all(element.get('open') is None for element in details)) + sections = [element.text for element in root.iter('h2')] + self.assertEqual(sections, ['Charts ', 'Results ', 'Definitions ']) + self.assertIn('12 definitions', page) + self.assertIn('color-scheme: dark', dark) + self.assertIn('#171c22', dark) + # Where the project stands comes first, then the charts, then the results and the definitions. + self.assertLess(light.index('12 definitions'), light.index('<h2>Charts')) + self.assertLess(light.index('<h2>Charts'), light.index('<h2>Results')) + self.assertLess(light.index('<h2>Results'), light.index('<h2>Definitions')) + + +if __name__ == '__main__': + unittest.main() diff --git a/tests/test_tuldok_project_cli.py b/tests/test_tuldok_project_cli.py index 2ef00f7d..2ce59861 100644 --- a/tests/test_tuldok_project_cli.py +++ b/tests/test_tuldok_project_cli.py @@ -16,6 +16,7 @@ import tempfile import unittest import uuid +import xml.etree.ElementTree as ElementTree sys.path.insert(0, str(Path(__file__).resolve().parents[1])) @@ -117,19 +118,19 @@ def test_open_prints_counts_and_time_then_attaches(self): self.assertRegex(lines[0], rf'^Opened Minimal surrogate project \({self.project_id}\) from .* in \d+\.\d\d s\.$') self.assertIn('kind count', lines) self.assertIn('recipe 3', lines) - self.assertIn('total 10', lines) + self.assertIn('total 12', lines) self.assertIn('state count', lines) self.assertIn('cannot-rebuild 1', lines) self.assertTrue(self.schema_exists()) again = self.run_json('open', self.folder) self.assertEqual(again['project_id'], self.project_id) self.assertEqual(again['kinds']['recipe'], 3) - self.assertEqual(again['states'], {'cannot-rebuild': 1, 'none': 3, 'not-built': 5, 'not-set-up': 1}) + self.assertEqual(again['states'], {'cannot-rebuild': 1, 'none': 5, 'not-built': 5, 'not-set-up': 1}) self.assertIsInstance(again['seconds'], float) def test_list(self): lines = self.run_ok('list', self.folder).splitlines() - self.assertEqual(len(lines), 10) + self.assertEqual(len(lines), 12) self.assertEqual(lines[0].split(None, 2), ['benchmarks/rollout', 'not-built', 'Rollout error']) self.assertEqual(len({line.index('not-built') for line in lines if ' not-built ' in line}), 1) # aligned rows = self.run_json('list', self.folder, '--kind', 'recipe') @@ -158,10 +159,10 @@ def test_show_of_a_missing_definition_exits_1(self): def test_graph_and_order(self): nodes, edges = self.run_ok('graph', self.folder).split('\n\n') - self.assertEqual(len(nodes.splitlines()), 10) - self.assertIn('recipes/stepper-k2 input:start recipes/stepper-k1', edges.splitlines()) + self.assertEqual(len(nodes.splitlines()), 12) + self.assertIn('recipes/stepper-k2 input:start recipes/stepper-k1', edges.splitlines()) drawn = self.run_json('graph', self.folder) - self.assertEqual(len(drawn['nodes']), 10) + self.assertEqual(len(drawn['nodes']), 12) self.assertEqual(len(drawn['edges']), len(edges.splitlines())) order = [line.split() for line in self.run_ok('graph', self.folder, '--order').splitlines()] references = [reference for reference, _ in order] @@ -246,7 +247,7 @@ def test_a_moved_folder_needs_rebind(self): done = run('list', moved / 'project') self.assertEqual(done.returncode, 1) self.assertIn('rebind', done.stderr) - self.assertEqual(len(self.run_json('list', moved / 'project', '--rebind')), 10) + self.assertEqual(len(self.run_json('list', moved / 'project', '--rebind')), 12) def test_open_elsewhere_is_busy_and_every_command_releases_the_lock(self): for arguments in (('open',), ('list',), ('show', 'models/stepper'), ('graph',), ('status',), ('save',)): @@ -269,5 +270,86 @@ def test_forget_drops_the_copy_and_leaves_the_folder(self): self.assertIn('holds no copy', self.run_ok('forget', self.folder)) # forgetting twice is fine + +@unittest.skipUnless(DATABASE, 'TULDOK_DATABASE_URL is not set; database tests need a disposable cluster.') +class ChartCommands(FolderCase): + """chart and report, and the two ways of naming a benchmark or a chart.""" + + def setUp(self): + super().setUp() + self.addCleanup(store.drop_project, self.project_id) + + def test_chart_prints_its_data_as_text_or_json(self): + lines = self.run_ok('chart', self.folder, 'rollout-ranking').splitlines() + self.assertEqual(lines[0].split(), ['chart', 'charts/rollout-ranking', 'ranking']) + self.assertIn('metric rmse: median Rollout RMSE (m/s), lower is better', lines) + self.assertIn('horizon = 8', lines) + self.assertEqual(lines[lines.index('horizon = 1') + 1].split(), ['rank', 'subject', 'value', 'count']) + self.assertEqual(lines[lines.index('horizon = 1') + 2].split(), ['1', 'stepper-k2', '0.3125', '4']) + self.assertEqual(lines[-1], '1 of 3 subjects has no value: early-fit.') + data = self.run_json('chart', self.folder, 'charts/speed-accuracy') + self.assertEqual([(item['subject'], item['frontier']) for item in data['series'][0]['points']], + [('stepper-k2', True), ('stepper-k1', False), ('early-fit', False)]) + progression = self.run_ok('chart', self.folder, 'charts/rollout-progression').splitlines() + self.assertIn(['0', 'early-fit', '0.625', '0.625', '2026-03-14'], [line.split() for line in progression]) + comparison = self.run_ok('chart', self.folder, 'rollout-comparison').splitlines() + self.assertIn(['subject', 'rmse', 'seconds'], [line.split() for line in comparison]) + self.assertEqual(comparison[-1], 'Every one of the 3 subjects has a value.') + + def test_chart_svg_is_written_in_either_theme(self): + light, dark = self.temporary / 'light.svg', self.temporary / 'dark.svg' + output = self.run_ok('chart', self.folder, 'rollout-ranking', '--svg', light) + self.assertTrue(output.endswith(f'Wrote {light} ({light.stat().st_size} bytes).\n')) + data = self.run_json('chart', self.folder, 'rollout-ranking', '--svg', dark, '--theme', 'dark') + self.assertEqual(data['chart'], 'charts/rollout-ranking') # stdout holds the JSON alone + for path in (light, dark): + root = ElementTree.fromstring(path.read_text(encoding='utf-8')) + self.assertEqual(root.find('{http://www.w3.org/2000/svg}title').text, 'Rollout error by subject') + self.assertIn('#171c22', dark.read_text(encoding='utf-8')) + self.assertNotEqual(light.read_bytes(), dark.read_bytes()) + self.run_ok('chart', self.folder, 'charts/rollout-ranking', '--svg', self.temporary / 'again.svg') + self.assertEqual((self.temporary / 'again.svg').read_bytes(), light.read_bytes()) + blocked = run('chart', self.folder, 'rollout-ranking', '--svg', self.temporary / 'absent' / 'x.svg') + self.assertEqual(blocked.returncode, 1) + self.assertIn('cannot be written', blocked.stderr) + + def test_report_writes_one_page(self): + page = self.temporary / 'report.html' + output = self.run_ok('report', self.folder, '--output', page, '--theme', 'dark') + self.assertEqual(output, f'Wrote {page} (4 charts, {page.stat().st_size} bytes).\n') + text = page.read_text(encoding='utf-8') + self.assertTrue(text.startswith('<!DOCTYPE html>')) + self.assertEqual(text.count('<svg '), 4) + self.assertIn('color-scheme: dark', text) + self.assertEqual(run('report', self.folder).returncode, 2) # --output is required + + def test_benchmarks_and_charts_by_name_or_reference(self): + for command in (('results',), ('values', '--subject', 'stepper-k1')): + bare = self.run_json(command[0], self.folder, 'rollout', *command[1:]) + self.assertEqual(self.run_json(command[0], self.folder, 'benchmarks/rollout', *command[1:]), bare) + self.assertEqual(len(self.run_json('results', self.folder, 'benchmarks/rollout')), 12) + self.assertIn('benchmarks/rollout has no summary rows', self.run_ok('results', self.folder, 'benchmarks/rollout', + '--subject', 'nobody')) + self.assertEqual(self.run_json('chart', self.folder, 'charts/speed-accuracy'), + self.run_json('chart', self.folder, 'speed-accuracy')) + for arguments in (('results', 'recipes/early-fit'), ('values', 'charts/x', '--subject', 'a'), + ('chart', 'benchmarks/rollout'), ('chart', 'Bad Name')): + done = run(arguments[0], self.folder, *arguments[1:]) + self.assertEqual(done.returncode, 2, arguments) + self.assertIn('is not a name or a reference', done.stderr) + missing = run('chart', self.folder, 'nothing') + self.assertEqual(missing.returncode, 1) + self.assertEqual(missing.stderr, 'There is no chart charts/nothing.\n') + + def test_chart_of_a_benchmark_without_results_is_empty(self): + (self.folder / 'results' / 'rollout.csv').unlink() + data = self.run_json('chart', self.folder, 'rollout-ranking') + self.assertEqual([series['points'] for series in data['series']], []) + self.assertEqual(data['missing'], ['stepper-k1', 'stepper-k2', 'early-fit']) + drawing = self.temporary / 'empty.svg' + self.run_ok('chart', self.folder, 'rollout-ranking', '--svg', drawing) + self.assertIn('No results yet: none of the 3 subjects of benchmarks/rollout', drawing.read_text(encoding='utf-8')) + + if __name__ == '__main__': unittest.main() diff --git a/tests/test_tuldok_project_result_rows.py b/tests/test_tuldok_project_result_rows.py index 0e02401d..230e1238 100644 --- a/tests/test_tuldok_project_result_rows.py +++ b/tests/test_tuldok_project_result_rows.py @@ -406,8 +406,8 @@ def test_save_refuses_when_the_results_file_changed_on_disk(self): def test_removing_the_benchmark_removes_its_results_and_save_deletes_the_file(self): self.project.import_values(values_file()) - self.project.remove_definition('charts/speed-accuracy') - self.project.remove_definition('charts/rollout-ranking') + for chart in ('speed-accuracy', 'rollout-ranking', 'rollout-progression', 'rollout-comparison'): + self.project.remove_definition(f'charts/{chart}') self.project.remove_definition('benchmarks/rollout') connection = self.database() for table in ('result_summaries', 'result_values'): diff --git a/tests/test_tuldok_project_store.py b/tests/test_tuldok_project_store.py index 82292b74..c6bceda9 100644 --- a/tests/test_tuldok_project_store.py +++ b/tests/test_tuldok_project_store.py @@ -30,6 +30,8 @@ FIXTURE_STATES = { 'benchmarks/rollout': 'not-built', # its early-fit subject carries nothing + 'charts/rollout-comparison': 'none', + 'charts/rollout-progression': 'none', 'charts/rollout-ranking': 'none', 'charts/speed-accuracy': 'none', 'datasets/waves': 'not-built', @@ -178,13 +180,14 @@ def test_first_open_imports_every_definition(self): self.assertEqual(summary['project_id'], self.project_id) self.assertEqual(summary['folder'], os.path.realpath(self.folder)) self.assertEqual(summary['code_root'], '../code') - self.assertEqual(summary['kinds'], {'benchmark': 1, 'chart': 2, 'dataset': 1, 'environment': 1, + self.assertEqual(summary['kinds'], {'benchmark': 1, 'chart': 4, 'dataset': 1, 'environment': 1, 'model': 1, 'recipe': 3, 'step': 1}) - self.assertEqual(summary['states'], {'cannot-rebuild': 1, 'none': 3, 'not-built': 5, 'not-set-up': 1}) + self.assertEqual(summary['states'], {'cannot-rebuild': 1, 'none': 5, 'not-built': 5, 'not-set-up': 1}) rows = project.definitions() self.assertEqual({row['reference']: row['state'] for row in rows}, FIXTURE_STATES) self.assertEqual([row['reference'] for row in project.definitions(kind='chart')], - ['charts/rollout-ranking', 'charts/speed-accuracy']) + ['charts/rollout-comparison', 'charts/rollout-progression', 'charts/rollout-ranking', + 'charts/speed-accuracy']) shown = project.definition('datasets/waves') self.assertEqual(shown['text'], self.read('datasets/waves')) # the exact file text @@ -195,7 +198,7 @@ def test_first_open_imports_every_definition(self): self.assertIn({'reference': 'benchmarks/rollout', 'role': 'cases'}, shown['used_by']) drawn = project.graph() - self.assertEqual(len(drawn['nodes']), 10) + self.assertEqual(len(drawn['nodes']), 12) self.assertIn({'from': 'recipes/stepper-k2', 'to': 'recipes/stepper-k1', 'role': 'input:start'}, drawn['edges']) self.assertEqual(len(drawn['edges']), len(check.check_folder(self.folder).edges)) order = project.order() @@ -210,7 +213,7 @@ def test_second_open_of_unchanged_folder_does_not_run_the_checker(self): project = self.open() checker.assert_not_called() self.assertEqual(self.dump(), before) - self.assertEqual(len(project.definitions()), 10) + self.assertEqual(len(project.definitions()), 12) def test_changed_added_and_removed_files_are_imported(self): self.close(self.open()) @@ -376,7 +379,7 @@ def test_remove_definition(self): self.assertTrue(row['removed']) self.assertNotIn('charts/speed-accuracy', [n['reference'] for n in self.project.graph()['nodes']]) self.assertEqual(self.project.status()['removed'], ['charts/speed-accuracy']) - self.assertEqual(self.project.summary()['kinds']['chart'], 1) + self.assertEqual(self.project.summary()['kinds']['chart'], 3) def test_remove_refused_while_used(self): before = self.dump() @@ -387,8 +390,8 @@ def test_remove_refused_while_used(self): self.assertEqual(self.dump(), before) def test_removing_a_user_frees_what_it_used(self): - self.project.remove_definition('charts/speed-accuracy') - self.project.remove_definition('charts/rollout-ranking') + for chart in ('speed-accuracy', 'rollout-ranking', 'rollout-progression', 'rollout-comparison'): + self.project.remove_definition(f'charts/{chart}') self.project.remove_definition('benchmarks/rollout') self.assertTrue({r['reference']: r for r in self.project.definitions()}['benchmarks/rollout']['removed']) diff --git a/tuldok_project/__main__.py b/tuldok_project/__main__.py index 82d9a7fd..45ce112d 100644 --- a/tuldok_project/__main__.py +++ b/tuldok_project/__main__.py @@ -8,7 +8,9 @@ on disk), does its one piece of work and closes the Project before exiting, so the project's lock is never held past the command. `results` and `values` read benchmark results from the database only; `import-values` checks every values -file before it imports any. +file before it imports any. `chart` and `report` draw from the summary rows in +the database (charts.py) and never read a results or values file. A benchmark +or chart may be named bare (`rollout`) or as a reference (`benchmarks/rollout`). """ import argparse import dataclasses @@ -22,6 +24,7 @@ DATABASE_VARIABLE = 'TULDOK_DATABASE_URL' KINDS = tuple(sorted(documents.KINDS.values())) +THEMES = ('light', 'dark') class UsageError(Exception): @@ -73,17 +76,24 @@ def add(name, parents, help_text): removing.add_argument('reference', help='for example recipes/pilot-dense-k1') add('save', [reading], 'write the unsaved edits to the folder') showing = add('results', [reading], "show the benchmarks' results, or one benchmark's summary rows") - showing.add_argument('benchmark', nargs='?', help='a benchmark name, for example rollout') + showing.add_argument('benchmark', nargs='?', help='a benchmark, for example rollout or benchmarks/rollout') showing.add_argument('--subject', help='only this subject') showing.add_argument('--metric', help='only this metric id') showing.add_argument('--group', help="only this group key; '' for the ungrouped rows") values = add('values', [reading], "show a subject's per-case values held on this machine") - values.add_argument('benchmark', help='a benchmark name, for example rollout') + values.add_argument('benchmark', help='a benchmark, for example rollout or benchmarks/rollout') values.add_argument('--subject', required=True, help='the subject') values.add_argument('--metric', help='only this metric id') values.add_argument('--limit', type=_positive, default=200, help='at most this many rows (default 200)') importing = add('import-values', [reading], 'import tuldok_results_v1 values files; all are checked first') importing.add_argument('files', nargs='+', metavar='FILE', help='values files') + drawing = add('chart', [reading], "print a chart's data from the summary rows, or write its drawing") + drawing.add_argument('chart', help='a chart, for example rollout-ranking or charts/rollout-ranking') + drawing.add_argument('--svg', metavar='FILE', help='write the drawing to this SVG file') + drawing.add_argument('--theme', choices=THEMES, default='light', help='colours of the drawing (default light)') + reporting = add('report', [opening], 'write one self-contained HTML page of the project and its charts') + reporting.add_argument('--output', required=True, metavar='FILE', help='the HTML file to write') + reporting.add_argument('--theme', choices=THEMES, default='light', help='colours of the page (default light)') add('forget', [database], "drop this project's copy from the database; the folder is not touched") return parser @@ -253,6 +263,14 @@ def _number(value): return '-' if value is None else f'{value:.4g}' +def _bare(text, directory): + """The name in a bare name or a <directory>/<name> reference; a usage error for anything else.""" + name = text[len(directory) + 1:] if text.startswith(directory + '/') else text + if not documents.is_name(name): + raise UsageError(f'{text!r} is not a name or a reference such as {directory}/<name>.') + return name + + def _results(project, arguments): if arguments.benchmark is None: overview = project.results_overview() @@ -314,9 +332,109 @@ def _import_values(project, arguments): return 0 +def _write_output(path, text): + """Write text to path through a temporary file in the same directory; the byte count, or None after printing why not.""" + data = text.encode('utf-8') + directory = os.path.dirname(os.path.abspath(path)) + temporary = os.path.join(directory, f'.{os.path.basename(path)}.{os.getpid()}.tmp') + try: + with open(temporary, 'wb') as handle: + handle.write(data) + os.replace(temporary, path) + except OSError as exc: + try: + os.unlink(temporary) + except OSError: + pass + print(f'{path} cannot be written: {exc.strerror}.', file=sys.stderr) + return None + return len(data) + + +def _metric_words(metric, statistic): + units = f' ({metric["units"]})' if metric.get('units') else '' + better = {'lower': 'lower is better', 'higher': 'higher is better'}.get(metric['better'], 'no better direction') + return f'{metric["id"]}: {statistic} {metric["title"]}{units}, {better}' + + +def _chart_lines(data): + """The rows of the text form of a chart's data.""" + rows = [('chart', data['chart'], data['form']), ('title', data['title']), ('benchmark', data['benchmark']), + ('metric', _metric_words(data['metric'], data['statistic']))] + if data['metric_x']: + rows.append(('x metric', _metric_words(data['metric_x'], data['statistic']))) + if data['group']: + rows.append(('group', data['group'])) + _columns(rows) + if data['form'] == 'comparison': + print() + ids = [metric['id'] for metric in data['metrics']] + grouped = bool(data['group']) + _columns([('subject', *(('group',) if grouped else ()), *ids), + *((row['subject'], *((row['group'],) if grouped else ()), *(_number(row['values'][i]) for i in ids)) + for row in data['rows'])]) + for series in data.get('series', []): + print() + if data['group']: + print(f'{data["group"]} = {series["group"]}') + if not series['points']: + print('No subject has a value.') + continue + head = {'ranking': ('rank', 'subject', 'value', 'count'), + 'tradeoff': ('subject', 'x', 'value', 'frontier'), + 'progression': ('position', 'subject', 'value', 'best so far', 'trained')}[data['form']] + lines = [] + for index, point in enumerate(series['points']): + if data['form'] == 'ranking': + lines.append((index + 1, point['subject'], _number(point['value']), point['count'])) + elif data['form'] == 'tradeoff': + lines.append((point['subject'], _number(point['x']), _number(point['value']), + 'yes' if point['frontier'] else '-')) + else: + lines.append((point['position'], point['subject'], _number(point['value']), + _number(point['best_so_far']), point['trained_at'] or '-')) + _columns([head, *lines]) + print() + if data['missing']: + print(f'{len(data["missing"])} of {data["subject_count"]} subjects ' + + ('has' if len(data['missing']) == 1 else 'have') + ' no value: ' + + ', '.join(data['missing']) + '.') + else: + print(f'Every one of the {data["subject_count"]} subjects has a value.') + + +def _chart(project, arguments): + from . import charts + + data = charts.chart_data(project, f'charts/{arguments.chart}') + if arguments.json: + _json(data) + else: + _chart_lines(data) + if arguments.svg: + written = _write_output(arguments.svg, charts.render_svg(data, theme=arguments.theme)) + if written is None: + return 1 + if not arguments.json: + print(f'Wrote {arguments.svg} ({written} bytes).') + return 0 + + +def _report(project, arguments): + from . import charts + + page = charts.render_report(project, theme=arguments.theme) + written = _write_output(arguments.output, page) + if written is None: + return 1 + count = len(project.definitions(kind='chart')) + print(f'Wrote {arguments.output} ({_plural(count, "chart")}, {written} bytes).') + return 0 + + _STORE_COMMANDS = {'open': _open, 'list': _list, 'show': _show, 'graph': _graph, 'status': _status, 'set': _set, 'remove': _remove, 'save': _save, 'results': _results, 'values': _values, - 'import-values': _import_values} + 'import-values': _import_values, 'chart': _chart, 'report': _report} def _project_id(folder): @@ -388,6 +506,10 @@ def _run_store(arguments, dsn): if twice: raise UsageError('These files are for the same benchmark and subject; import one of them: ' + ', '.join(twice) + '.') + if arguments.command in ('results', 'values') and arguments.benchmark is not None: + arguments.benchmark = _bare(arguments.benchmark, 'benchmarks') + if arguments.command == 'chart': + arguments.chart = _bare(arguments.chart, 'charts') started = time.monotonic() project = store.open_project(arguments.folder, rebind=arguments.rebind, on_conflict=arguments.on_conflict, dsn=dsn) diff --git a/tuldok_project/charts.py b/tuldok_project/charts.py new file mode 100644 index 00000000..aa9d1de6 --- /dev/null +++ b/tuldok_project/charts.py @@ -0,0 +1,948 @@ +"""Charts of benchmark results: their data from the summary table, their SVG drawing, and the report page. + +Owns section 5 of docs/plans/definition-first-projects/spec-m3.md. chart_data +answers a chart definition with SQL only, through the Project's reading +methods and a few queries of its own on the project's connection: the chart, +its benchmark and the subjects' recipes come from the definitions table, the +numbers from result_summaries. Nothing here opens a file. render_svg and +render_report are pure functions of what they are given: the same data gives +the same bytes. Colours and type are the design tokens of the project +workspace redesign (docs/plans/project-workspace-redesign/README.md), one hue +for marks and the good colour for the frontier and the running best; text is +drawn in the ink tokens only, never in a mark colour. +""" +import html +import math +import re + +from . import documents +from .store import ProjectError + +DEFAULT_STATISTIC = 'median' +THEMES = ('light', 'dark') + +# Design tokens (project-workspace-redesign/README.md, "Design system"). +_TOKENS = { + 'light': {'page': '#f3f5f7', 'surface': '#ffffff', 'line': '#dfe4ea', 'line_strong': '#c5cdd6', + 'ink': '#1b2330', 'ink2': '#596679', 'ink3': '#8a94a3', 'accent': '#2c5fb8', 'good': '#237c60'}, + 'dark': {'page': '#0f1317', 'surface': '#171c22', 'line': '#2a323c', 'line_strong': '#3a4552', + 'ink': '#e6eaf0', 'ink2': '#aab3c0', 'ink3': '#7c8694', 'accent': '#6a9ae8', 'good': '#4fb68f'}, +} +FONT = "'Ubuntu Sans', 'Noto Sans', system-ui, -apple-system, 'Segoe UI', sans-serif" +MONO = "'Ubuntu Sans Mono', 'Ubuntu Mono', ui-monospace, 'SFMono-Regular', Menlo, monospace" + + +# ================================================================== data + +def _query(project, template, parameters=None): + """Rows of one query on the project's own connection; {schema} names the project's schema.""" + return project._execute(template, parameters).fetchall() + + +def _document(project, directory, name): + rows = _query(project, 'SELECT document FROM {schema}.definitions ' + 'WHERE directory = %s AND name = %s AND NOT removed', (directory, name)) + return rows[0][0] if rows else None + + +def _trained_at(project, recipe_names): + """{recipe name: labels.trained_at} for the recipes that have one.""" + if not recipe_names: + return {} + rows = _query(project, "SELECT name, document->'labels'->>'trained_at' FROM {schema}.definitions " + "WHERE directory = 'recipes' AND NOT removed AND name = ANY(%s)", (sorted(recipe_names),)) + return {name: value for name, value in rows if isinstance(value, str) and value} + + +def chart_reference(text): + """charts/<name> for a chart given as a bare name or as a reference; None when it is neither.""" + name = text[len('charts/'):] if isinstance(text, str) and text.startswith('charts/') else text + return f'charts/{name}' if documents.is_name(name) else None + + +def _lower_first(better): + return better != 'higher' + + +def frontier(points, better_y, better_x): + """For each (x, value) pair, whether no other pair is at least as good on both and better on one. + + better_* is the metric's `better`; `none` counts as lower is better. Two + identical pairs do not beat each other, so both stay on the frontier. + """ + sign_y = 1 if _lower_first(better_y) else -1 + sign_x = 1 if _lower_first(better_x) else -1 + keyed = [(sign_x * x, sign_y * y) for x, y in points] # smaller is better on both + flags = [] + for index, (x, y) in enumerate(keyed): + beaten = any(ox <= x and oy <= y and (ox < x or oy < y) + for other, (ox, oy) in enumerate(keyed) if other != index) + flags.append(not beaten) + return flags + + +def _metric(document, metric_id): + for item in document.get('metrics', []): + if item.get('id') == metric_id: + return {'id': metric_id, 'title': item.get('title', metric_id), 'units': item.get('units'), + 'better': item.get('better', 'none')} + raise ProjectError(f'{metric_id!r} is not a metric of the benchmark.', 'not-found') + + +def _group_order(values): + """Group values sorted numerically when every one is a number, as text otherwise.""" + def number(text): + try: + value = float(text) + except ValueError: + return None + return value if math.isfinite(value) else None + + numbers = [number(value) for value in values] + if values and all(value is not None for value in numbers): + return [value for _, value in sorted(zip(numbers, values))] + return sorted(values) + + +def _value_sort(better): + lower = _lower_first(better) + return lambda point: ((point['value'] if lower else -point['value']), point['subject']) + + +def chart_data(project, reference): + """The data of one chart definition, from the definitions and result_summaries tables only. + + reference is charts/<name> (a bare name is accepted too). Raises + ProjectError (not-found) when the chart or its benchmark does not exist. + """ + chart_ref = chart_reference(reference) + if chart_ref is None: + raise ProjectError(f'{reference!r} is not a chart name or a reference such as charts/<name>.', 'not-found', + references=[str(reference)]) + chart = _document(project, 'charts', chart_ref[len('charts/'):]) + if chart is None: + raise ProjectError(f'There is no chart {chart_ref}.', 'not-found', references=[chart_ref]) + parsed = documents.parse_reference(chart.get('benchmark')) + benchmark = _document(project, *parsed) if parsed and parsed[0] == 'benchmarks' else None + if benchmark is None: + raise ProjectError(f'{chart_ref} names no existing benchmark.', 'not-found', references=[chart_ref]) + benchmark_name = parsed[1] + form = chart['form'] + statistic = chart.get('statistic', DEFAULT_STATISTIC) + group_key = chart.get('group') or '' + metric = _metric(benchmark, chart['metric']) + metric_x = _metric(benchmark, chart['metric_x']) if form == 'tradeoff' else None + + declared = {item['name']: item for item in benchmark.get('subjects', [])} + names = [name for name in chart.get('subjects', list(declared)) if name in declared] + subjects = {name: {'subject': name, 'title': declared[name].get('title') or name, + 'recipe': declared[name].get('recipe')} for name in names} + + # {(subject, metric, group value): (statistic, row)} for the usable rows of this chart's group. + wanted = [metric['id']] + ([metric_x['id']] if metric_x else []) + if form == 'comparison': + wanted = [item['id'] for item in benchmark.get('metrics', [])] + stats, group_values = {}, set() + for metric_id in dict.fromkeys(wanted): + for stored in project.result_summaries(benchmark_name, metric=metric_id, group=group_key): + row = stored.row + if row.subject not in subjects: + continue + value = row.group.split('=', 1)[1] if group_key else '' + group_values.add(value) + number = getattr(row, statistic) + if row.count > 0 and number is not None: + stats[(row.subject, metric_id, value)] = (number, row) + + groups = _group_order(sorted(group_values)) if group_key else [''] + result = {'chart': chart_ref, 'title': chart['title'], 'description': chart.get('description'), + 'form': form, 'benchmark': f'benchmarks/{benchmark_name}', 'statistic': statistic, + 'group': group_key or None, 'metric': metric, 'metric_x': metric_x, 'subject_count': len(names)} + + if form == 'comparison': + return _comparison(result, benchmark, names, subjects, stats, groups, explicit='subjects' in chart) + + trained = _trained_at(project, {item['recipe'].split('/', 1)[1] for item in subjects.values() + if isinstance(item['recipe'], str) and item['recipe'].startswith('recipes/')}) + series, missing = [], set() + for value in groups: + points, lacking = [], [] + for name in names: + found = stats.get((name, metric['id'], value)) + found_x = stats.get((name, metric_x['id'], value)) if metric_x else None + if found is None or (metric_x is not None and found_x is None): + lacking.append(name) + continue + number, row = found + point = {**subjects[name], 'value': number, 'count': row.count, 'unavailable': row.unavailable, + 'produced': row.produced} + if metric_x is not None: + point['x'] = found_x[0] + points.append(point) + missing.update(lacking) + if form == 'ranking': + points.sort(key=_value_sort(metric['better'])) + elif form == 'tradeoff': + on_front = frontier([(point['x'], point['value']) for point in points], metric['better'], metric_x['better']) + for point, flag in zip(points, on_front): + point['frontier'] = flag + by_value = _value_sort(metric['better']) + points.sort(key=lambda point: (point['x'], *by_value(point))) + else: # progression + for point in points: + recipe = point['recipe'] + point['trained_at'] = trained.get(recipe.split('/', 1)[1]) if isinstance(recipe, str) else None + points.sort(key=lambda point: (point['trained_at'] is None, point['trained_at'] or '', point['subject'])) + best = None + pick = min if _lower_first(metric['better']) else max + for position, point in enumerate(points): + best = point['value'] if best is None else pick(best, point['value']) + point['position'] = position + point['best_so_far'] = best + series.append({'group': value, 'points': points, 'missing': lacking}) + if not groups: # a grouped chart with no rows for its group at all + missing.update(names) + result['series'] = series + result['missing'] = [name for name in names if name in missing] + return result + + +def _comparison(result, benchmark, names, subjects, stats, groups, *, explicit): + """Fill metrics, rows and missing of a comparison: one row per subject (and group value) with a value.""" + metrics = [_metric(benchmark, item['id']) for item in benchmark.get('metrics', [])] + metric_id, lower = result['metric']['id'], _lower_first(result['metric']['better']) + rows, held = [], set() + for value in groups: + found = [] + for name in names: + values = {item['id']: stats[(name, item['id'], value)][0] if (name, item['id'], value) in stats else None + for item in metrics} + if any(number is not None for number in values.values()): + held.add(name) + found.append({**subjects[name], 'group': value, 'values': values}) + if not explicit: # the ranking order of the chart's metric; rows without it last, by name + found.sort(key=lambda row: (row['values'][metric_id] is None, + 0 if row['values'][metric_id] is None + else row['values'][metric_id] if lower else -row['values'][metric_id], + row['subject'])) + rows.extend(found) + result['metrics'] = metrics + result['rows'] = rows + result['missing'] = [name for name in names if name not in held] + return result + + +# ============================================================== numbers + +def format_number(value): + """Three significant digits; very small and very large numbers as 2.43e-6 or 1.5e7.""" + if value is None: + return '-' + if value == 0: + return '0' + rounded = float(f'{value:.2e}') + if abs(rounded) < 1e-3 or abs(rounded) >= 1e5: + mantissa, exponent = f'{value:.2e}'.split('e') + return f'{mantissa}e{int(exponent)}' + decimals = max(0, 2 - math.floor(math.log10(abs(rounded)))) + return f'{rounded:.{decimals}f}' + + +def _tick_text(value): + """A tick label: like format_number but without trailing zeros (ticks are round numbers).""" + text = format_number(value) + if 'e' in text: + mantissa, exponent = text.split('e') + if '.' in mantissa: + mantissa = mantissa.rstrip('0').rstrip('.') + return f'{mantissa}e{exponent}' + if '.' in text: + text = text.rstrip('0').rstrip('.') + return '0' if text in ('-0', '') else text + + +class _Scale: + """A value axis: logarithmic when every value is positive and they span a factor of at least 100.""" + + def __init__(self, values, start, end, *, zero=False): + self.start, self.end = start, end + lo, hi = min(values), max(values) + self.log = lo > 0 and hi >= 100 * lo + if self.log: + first, last = math.floor(math.log10(lo)), math.ceil(math.log10(hi)) + step = max(1, math.ceil((last - first) / 8)) + self.lo, self.hi = 10.0 ** first, 10.0 ** last + self.ticks = [10.0 ** power for power in range(first, last + 1, step)] + return + if zero: + lo, hi = min(lo, 0.0), max(hi, 0.0) + if lo == hi: + pad = abs(lo) * 0.1 or 1.0 + lo, hi = lo - pad, hi + pad + raw = (hi - lo) / 5 + power = 10.0 ** math.floor(math.log10(raw)) + step = next(factor * power for factor in (1, 2, 2.5, 5, 10) if factor * power >= raw) + self.lo = math.floor(lo / step + 1e-9) * step + self.hi = math.ceil(hi / step - 1e-9) * step + count = round((self.hi - self.lo) / step) + self.ticks = [self.lo + index * step for index in range(count + 1)] + self.ticks = [0.0 if abs(tick) < step * 1e-9 else float(f'{tick:.12g}') for tick in self.ticks] + + def __call__(self, value): + if self.log: + share = (math.log10(value) - math.log10(self.lo)) / (math.log10(self.hi) - math.log10(self.lo)) + else: + share = (value - self.lo) / (self.hi - self.lo) + return self.start + share * (self.end - self.start) + + +# ================================================================== SVG + +_XML_FORBIDDEN = re.compile('[\x00-\x08\x0b\x0c\x0e-\x1f\ufffe\uffff]') +_CHAR = 0.58 # average advance of a character, in em, for estimating text width + + +def _esc(text): + return html.escape(_XML_FORBIDDEN.sub('', str(text)), quote=True) + + +def _f(number): + text = f'{number:.1f}' + return text[:-2] if text.endswith('.0') else text + + +def _width(text, size): + return len(text) * size * _CHAR + + +def _fit(text, size, width): + """text, cut with an ellipsis so that it fits width at size.""" + text = str(text) + limit = max(1, int(width / (size * _CHAR))) + return text if len(text) <= limit else text[:max(1, limit - 1)].rstrip() + '…' + + +def _units(metric): + """The metric's units for display; '1' (a pure number) shows nothing.""" + units = metric.get('units') + return None if units in (None, '', '1') else units + + +def _sentence(title): + """A metric title inside a sentence: first letter lowered unless it starts an acronym (GPU stays).""" + if len(title) > 1 and title[0].isupper() and not title[1].isupper(): + return title[0].lower() + title[1:] + return title + + +def _metric_label(metric, *, log=False): + units = _units(metric) + text = metric['title'] + (f' ({units})' if units else '') + return text + (', log scale' if log else '') + + +def _better_words(metric): + return {'lower': 'lower is better', 'higher': 'higher is better'}.get(metric['better'], 'no better direction') + + +class _Svg: + """Collects SVG elements; every attribute and text is escaped here.""" + + def __init__(self, colours): + self.c = colours + self.parts = [] + + def add(self, tag, attributes, text=None, tooltip=None): + attrs = ''.join(f' {key.replace("_", "-")}="{_esc(value)}"' for key, value in attributes.items() + if value is not None) + inner = (f'<title>{_esc(tooltip)}' if tooltip else '') + (_esc(text) if text is not None else '') + self.parts.append(f'<{tag}{attrs}>{inner}' if inner else f'<{tag}{attrs}/>') + + def text(self, x, y, text, *, size=12, fill='ink2', anchor=None, weight=None, numeric=False, tooltip=None, + halo=False): + self.add('text', {'x': _f(x), 'y': _f(y), 'font-size': size, 'fill': self.c[fill], 'text-anchor': anchor, + 'font-weight': weight, 'style': 'font-variant-numeric:tabular-nums' if numeric else None, + 'stroke': self.c['surface'] if halo else None, 'stroke-width': 3 if halo else None, + 'paint-order': 'stroke' if halo else None, 'stroke-linejoin': 'round' if halo else None}, + text, tooltip) + + def line(self, x1, y1, x2, y2, colour='line', width=1): + self.add('line', {'x1': _f(x1), 'y1': _f(y1), 'x2': _f(x2), 'y2': _f(y2), 'stroke': self.c[colour], + 'stroke-width': width, 'shape-rendering': 'crispEdges' if width == 1 else None}) + + def dot(self, x, y, colour='accent', tooltip=None, r=4): + self.add('circle', {'cx': _f(x), 'cy': _f(y), 'r': r, 'fill': self.c[colour], 'stroke': self.c['surface'], + 'stroke-width': 2}, tooltip=tooltip) + + def path(self, d, colour, width=2): + self.add('path', {'d': d, 'fill': 'none', 'stroke': self.c[colour], 'stroke-width': width, + 'stroke-linejoin': 'round', 'stroke-linecap': 'round'}) + + def bar(self, x0, x1, y, height, tooltip=None): + """A horizontal bar from x0, square at the baseline and rounded (4px) at its data end.""" + length = x1 - x0 + if length <= 0.5: + self.line(x0, y, x0, y + height, 'accent', 1) + return + r = min(4.0, length, height / 2) + d = (f'M{_f(x0)},{_f(y)}H{_f(x1 - r)}A{_f(r)},{_f(r)} 0 0 1 {_f(x1)},{_f(y + r)}' + f'V{_f(y + height - r)}A{_f(r)},{_f(r)} 0 0 1 {_f(x1 - r)},{_f(y + height)}H{_f(x0)}Z') + self.add('path', {'d': d, 'fill': self.c['accent']}, tooltip=tooltip) + + def document(self, width, height, data, note, heading): + ident = 'chart-' + re.sub('[^a-z0-9_-]', '-', str(data.get('chart', 'chart')).split('/')[-1]) + head = (f'' + f'{_esc(data.get("title", ""))}' + f'{_esc(note)}' + f'') + return head + ''.join(self.parts) + '\n' + + +WIDTH = 760 +_SIDE = 12 + + +def _subtitle(data): + metric, statistic = data['metric'], data['statistic'].capitalize() + if data['form'] == 'tradeoff': + text = (f'{statistic} {_sentence(metric["title"])} against {data["statistic"]} ' + f'{_sentence(data["metric_x"]["title"])}') + elif data['form'] == 'comparison': + text = f'{statistic} of every metric' + else: + text = f'{statistic} {_sentence(metric["title"])}, {_better_words(metric)}' + return text + f' · {data["benchmark"]}' + + +def _lines(svg, x, y, text, *, size, width, lines=2, fill='ink2', step=None): + """Text wrapped at spaces into at most `lines` lines; returns the y below the last line.""" + step = step or round(size * 1.35) + for number, line in enumerate(_wrap(text, size, width, lines)): + svg.text(x, y + number * step, line, size=size, fill=fill, tooltip=text if number == 0 and line != text else None) + return y + (number + 1) * step + + +def describe(data): + """One line on what the chart shows and how many subjects are not drawn.""" + form, metric, total = data['form'], data['metric'], data.get('subject_count', 0) + statistic = data['statistic'] + if form == 'ranking': + shown = f'Subjects ranked by {statistic} {_sentence(metric["title"])}, best first ({_better_words(metric)}).' + elif form == 'tradeoff': + on = sum(point.get('frontier', False) for series in data['series'] for point in series['points']) + shown = (f'{statistic.capitalize()} {_sentence(metric["title"])} against {statistic} ' + f'{_sentence(data["metric_x"]["title"])}; the line joins the ' + + (f'{on} {"subject" if on == 1 else "subjects"} ' if on else 'subjects ') + + 'no other subject beats on both.') + elif form == 'progression': + shown = (f'{statistic.capitalize()} {_sentence(metric["title"])} in the order the subjects were trained, ' + f'with the best so far.') + else: + shown = f'{statistic.capitalize()} of every metric per subject; the best in each column is marked.' + if data.get('group'): + shown = shown[:-1] + f', one panel per {data["group"]}.' + missing = len(data['missing']) + if total == 0: + return shown + ' The benchmark has no subjects.' + if missing == total: + return shown + f' None of the {total} subjects has a result yet.' + if missing: + return shown + f' {missing} of {total} subjects {"has" if missing == 1 else "have"} no value and ' \ + f'{"is" if missing == 1 else "are"} not drawn.' + return shown + f' All {total} subjects are drawn.' + + +def _names_line(names, width, prefix): + """prefix + as many names as fit in width, then 'and N more'.""" + shown = [] + for index, name in enumerate(names): + rest = len(names) - index - 1 + candidate = prefix + ', '.join(shown + [name]) + (f' and {rest} more' if rest else '') + if _width(candidate, 12) > width and shown: + return prefix + ', '.join(shown) + f' and {len(names) - len(shown)} more' + shown.append(name) + return prefix + ', '.join(shown) + + +def render_svg(data, *, theme='light', heading=True): + """One self-contained SVG document drawing chart_data's result; the same input gives the same bytes. + + With heading=False the title and subtitle are left out (the report page + sets them as HTML) and the background is transparent. + """ + if theme not in THEMES: + raise ValueError(f'theme is one of {", ".join(THEMES)}') + svg = _Svg(_TOKENS[theme]) + note = describe(data) + y = 8 + if heading: + svg.text(_SIDE, 28, _fit(data['title'], 16, WIDTH - 2 * _SIDE), size=16, fill='ink', weight=600, + tooltip=data['title']) + y = _lines(svg, _SIDE, 48, _subtitle(data), size=12.5, width=WIDTH - 2 * _SIDE) + 2 + drawers = {'ranking': _ranking, 'tradeoff': _tradeoff, 'progression': _progression, 'comparison': _comparison_grid} + has_points = (bool(data.get('rows')) if data['form'] == 'comparison' + else any(series['points'] for series in data.get('series', []))) + width = WIDTH + if not has_points: + y = _empty(svg, data, y) + else: + y, width = drawers[data['form']](svg, data, y) + if data['missing'] and has_points and not data.get('group'): + y += 8 + svg.text(_SIDE, y + 12, _names_line(data['missing'], width - 2 * _SIDE, + 'Not drawn, no value: '), size=12) + y += 20 + return svg.document(width, y + 12, data, note, heading) + + +def _empty(svg, data, y): + total = data.get('subject_count', 0) + if total == 0: + message = f'Nothing to draw: {data["benchmark"]} has no subjects.' + else: + statistic = data['statistic'] + message = (f'No results yet: none of the {total} subjects of {data["benchmark"]} has a {statistic} ' + f'{_sentence(data["metric"]["title"])}.') + svg.line(_SIDE, y + 8, WIDTH - _SIDE, y + 8) + bottom = _lines(svg, _SIDE, y + 34, message, size=13, width=WIDTH - 2 * _SIDE, lines=3) + svg.line(_SIDE, bottom + 2, WIDTH - _SIDE, bottom + 2) + return bottom + 6 + + +def _series_heading(svg, data, series, y, width): + """A panel heading for a grouped chart, with the subjects it lacks; returns the new y.""" + if not data.get('group'): + return y + svg.text(_SIDE, y + 16, _fit(f'{data["group"]} = {series["group"]}', 13, width - 2 * _SIDE), size=13, + fill='ink', weight=600) + y += 22 + if series['missing']: + svg.text(_SIDE, y + 12, _names_line(series['missing'], width - 2 * _SIDE, 'No value: '), size=12) + y += 18 + return y + 4 + + +def _x_axis_top(svg, scale, y, bottom): + for tick in scale.ticks: + x = scale(tick) + svg.line(x, y + 6, x, bottom, 'line') + svg.text(x, y, _tick_text(tick), size=11, anchor='middle', numeric=True) + + +# ------------------------------------------------------------- ranking + +_ROW = 18 +_BAR = 10 +_LABEL = 250 + + +def _ranking(svg, data, y): + values = [point['value'] for series in data['series'] for point in series['points']] + longest = max(_width(point['title'], 12) for series in data['series'] for point in series['points']) + label_width = min(_LABEL, max(60.0, math.ceil(longest))) + left, right = _SIDE + label_width + 10, WIDTH - _SIDE - 64 + scale = _Scale(values, left, right, zero=True) + for index, series in enumerate(data['series']): + if index: + y += 16 + y = _series_heading(svg, data, series, y, WIDTH) + if not series['points']: + svg.text(_SIDE, y + 14, 'No subject has a value here.', size=12) + y += 24 + continue + svg.text(left, y + 12, _fit(_metric_label(data['metric'], log=scale.log), 12, right - left), size=12) + top = y + 38 + bottom = top + len(series['points']) * _ROW + _x_axis_top(svg, scale, top - 6, bottom) + base = scale(scale.lo) + svg.line(base, top, base, bottom, 'line_strong') + for row, point in enumerate(series['points']): + middle = top + row * _ROW + _ROW / 2 + tip = scale(point['value']) + label = f'{point["title"]}: {format_number(point["value"])} ({point["count"]} values)' + svg.text(_SIDE, middle + 4, _fit(point['title'], 12, label_width), size=12, fill='ink', tooltip=label) + svg.bar(base, tip, middle - _BAR / 2, _BAR, tooltip=label) + svg.text(tip + 6, middle + 4, format_number(point['value']), size=11, numeric=True) + y = bottom + 4 + if len(series['points']) > 30: # a long ranking repeats its scale at the foot + for tick in scale.ticks: + svg.text(scale(tick), bottom + 16, _tick_text(tick), size=11, anchor='middle', numeric=True) + y = bottom + 22 + return y, WIDTH + + +# ------------------------------------------------- scatter (tradeoff, progression) + +_PLOT_HEIGHT = 320 + + +def _boxes_overlap(a, b): + return a[0] < b[2] and b[0] < a[2] and a[1] < b[3] and b[1] < a[3] + + +def _place_labels(svg, items, bounds, taken): + """Label (x, y, text) points where a label fits without touching another; returns how many were left out.""" + left_out = 0 + for x, y, text in items: + width, size = _width(text, 12), 12 + candidates = ((x + 8, y + 4, 'start', (x + 7, y - 9, x + 9 + width, y + 6)), + (x - 8, y + 4, 'end', (x - 9 - width, y - 9, x - 7, y + 6)), + (x, y - 10, 'middle', (x - width / 2, y - 23, x + width / 2, y - 7)), + (x, y + 20, 'middle', (x - width / 2, y + 7, x + width / 2, y + 23)), + (x + 6, y - 10, 'start', (x + 5, y - 23, x + 7 + width, y - 7)), + (x - 6, y - 10, 'end', (x - 7 - width, y - 23, x - 5, y - 7)), + (x + 6, y + 20, 'start', (x + 5, y + 7, x + 7 + width, y + 23)), + (x - 6, y + 20, 'end', (x - 7 - width, y + 7, x - 5, y + 23))) + for tx, ty, anchor, box in candidates: + inside = box[0] >= bounds[0] and box[2] <= bounds[2] and box[1] >= bounds[1] and box[3] <= bounds[3] + if inside and not any(_boxes_overlap(box, other) for other in taken): + svg.text(tx, ty, text, size=size, fill='ink', anchor=anchor, halo=True) + taken.append(box) + break + else: + left_out += 1 + return left_out + + +def _step_boxes(points): + """Thin boxes along a step path through (x, y) screen points, so labels keep off the line.""" + boxes = [] + for (x0, y0), (x1, y1) in zip(points, points[1:]): + boxes.append((min(x0, x1), y0 - 2, max(x0, x1), y0 + 2)) + boxes.append((x1 - 2, min(y0, y1), x1 + 2, max(y0, y1))) + return boxes + + +def _step(points): + """A step path through (x, y) screen points: across, then up or down to the next point.""" + if not points: + return '' + d = f'M{_f(points[0][0])},{_f(points[0][1])}' + for x, y in points[1:]: + d += f'H{_f(x)}V{_f(y)}' + return d + + +def _point_label(point, width=150): + """A point's label: its title when it fits, else its (short) name when that fits, else the title cut.""" + for text in (point['title'], point['subject']): + if _width(text, 12) <= width: + return text + return _fit(point['title'], 12, width) + + +def _scatter_frame(svg, data, values, y): + """The y axis and plot area of one scatter panel: returns (top, bottom, left, right, y_scale).""" + left, right = _SIDE + 58, WIDTH - _SIDE - 8 + top = y + 34 + bottom = top + _PLOT_HEIGHT + y_scale = _Scale(values, bottom - 10, top + 4) # inset, so points on the extremes stay clear of the axis + svg.text(_SIDE, y + 14, _fit(_metric_label(data['metric'], log=y_scale.log), 12, WIDTH - 2 * _SIDE), size=12) + for tick in y_scale.ticks: + ty = y_scale(tick) + svg.line(left, ty, right, ty, 'line') + svg.text(left - 6, ty + 4, _tick_text(tick), size=11, anchor='end', numeric=True) + svg.line(left, bottom, right, bottom, 'line_strong') + return top, bottom, left, right, y_scale + + +def _tradeoff(svg, data, y): + xs = [point['x'] for series in data['series'] for point in series['points']] + for index, series in enumerate(data['series']): + if index: + y += 20 + y = _series_heading(svg, data, series, y, WIDTH) + if not series['points']: + svg.text(_SIDE, y + 14, 'No subject has both values here.', size=12) + y += 24 + continue + top, bottom, left, right, y_scale = _scatter_frame(svg, data, [point['value'] for point in series['points']], y) + x_scale = _Scale(xs, left + 12, right - 12) + for tick in x_scale.ticks: + tx = x_scale(tick) + svg.line(tx, top, tx, bottom, 'line') + svg.text(tx, bottom + 16, _tick_text(tick), size=11, anchor='middle', numeric=True) + svg.text(right, bottom + 36, _fit(_metric_label(data['metric_x'], log=x_scale.log), 12, right - left), + size=12, anchor='end') + front = [point for point in series['points'] if point['frontier']] + screen = [(x_scale(point['x']), y_scale(point['value'])) for point in front] + if len(screen) > 1: + svg.path(_step(screen), 'good') + for point in series['points']: + if not point['frontier']: + svg.dot(x_scale(point['x']), y_scale(point['value']), 'accent', _point_tip(data, point)) + for point in front: + svg.dot(x_scale(point['x']), y_scale(point['value']), 'good', _point_tip(data, point) + ', on the frontier') + taken = [(sx - 5, sy - 5, sx + 5, sy + 5) for sx, sy in + ((x_scale(point['x']), y_scale(point['value'])) for point in series['points'])] + taken += _step_boxes(screen) + left_out = _place_labels(svg, [(sx, sy, _point_label(point)) for (sx, sy), point in zip(screen, front)], + (left, top - 4, right, bottom - 2), taken) + y = bottom + 44 + svg.dot(_SIDE + 4, y + 8, 'good', None) + key = f'On the frontier: no other subject is at least as good on both and better on one ({len(front)}).' + if left_out: + key += f' {left_out} frontier labels left out where they would overlap.' + y = _lines(svg, _SIDE + 14, y + 12, key, size=12, width=WIDTH - 2 * _SIDE - 14) - 8 + return y, WIDTH + + +def _point_tip(data, point): + text = f'{point["title"]}: {format_number(point["value"])}' + if 'x' in point: + text += f' at {format_number(point["x"])}' + return text + + +def _progression(svg, data, y): + for index, series in enumerate(data['series']): + if index: + y += 20 + y = _series_heading(svg, data, series, y, WIDTH) + points = series['points'] + if not points: + svg.text(_SIDE, y + 14, 'No subject has a value here.', size=12) + y += 24 + continue + values = [point['value'] for point in points] + [point['best_so_far'] for point in points] + top, bottom, left, right, y_scale = _scatter_frame(svg, data, values, y) + count = len(points) + span = right - left - 40 + + def x_of(position): + return left + 20 + (span * position / (count - 1) if count > 1 else span / 2) + + # Ticks: up to eight subjects along the order, named by their short name. + every = max(1, math.ceil(count / 8)) + for position in range(0, count, every): + tx = x_of(position) + svg.line(tx, bottom, tx, bottom + 4, 'line_strong') + svg.text(tx, bottom + 16, _fit(points[position]['subject'], 11, span / 8 - 4), size=11, anchor='middle') + undated = next((point['position'] for point in points if point['trained_at'] is None), None) + if undated is not None and undated > 0: + ux = (x_of(undated - 1) + x_of(undated)) / 2 + svg.line(ux, top, ux, bottom, 'line_strong') + svg.text(ux + 6, top + 10, 'no training date from here', size=11) + dated = count if undated is None else undated + axis = f'Training order, earliest first ({dated} of {count} with a training date)' + svg.text(right, bottom + 36, _fit(axis, 12, right - left), size=12, anchor='end') + best = [(x_of(point['position']), y_scale(point['best_so_far'])) for point in points] + svg.path(_step(best), 'good') + records = [point for index, point in enumerate(points) + if index == 0 or point['best_so_far'] != points[index - 1]['best_so_far']] + for point in points: + record = point in records + svg.dot(x_of(point['position']), y_scale(point['value']), 'good' if record else 'accent', + f'{point["title"]}: {format_number(point["value"])}' + + (f', trained {point["trained_at"]}' if point['trained_at'] else '') + + (', a new best' if record else ''), r=4 if record or count <= 60 else 3.5) + taken = [(x_of(p['position']) - 4, y_scale(p['value']) - 4, x_of(p['position']) + 4, y_scale(p['value']) + 4) + for p in points] + _step_boxes(best) + left_out = _place_labels(svg, [(x_of(point['position']), y_scale(point['value']), _point_label(point)) + for point in records], (left, top - 4, right, bottom - 2), taken) + y = bottom + 44 + svg.line(_SIDE, y + 8, _SIDE + 14, y + 8, 'good', 2) + key = f'Best so far; {len(records)} subjects set a new best.' + if left_out: + key += f' {left_out} of their labels left out where they would overlap.' + y = _lines(svg, _SIDE + 20, y + 12, key, size=12, width=WIDTH - 2 * _SIDE - 20) - 8 + return y, WIDTH + + +# ---------------------------------------------------------- comparison + +_CELL = 136 +_NAME = 230 + + +def _wrap(text, size, width, lines): + """Up to `lines` lines of text wrapped at spaces to width; the last one cut with an ellipsis.""" + words, out, current = str(text).split(), [], '' + for word in words: + trial = f'{current} {word}'.strip() + if _width(trial, size) <= width or not current: + current = trial + else: + out.append(current) + current = word + out.append(current) + if len(out) > lines: + out = out[:lines - 1] + [' '.join(out[lines - 1:])] + return [_fit(line, size, width) for line in out] + + +def _comparison_grid(svg, data, y): + metrics, rows = data['metrics'], data['rows'] + grouped = bool(data.get('group')) + name_width = _NAME + (90 if grouped else 0) + width = max(WIDTH, 2 * _SIDE + name_width + _CELL * len(metrics)) + best = {} + for metric in metrics: + numbers = [row['values'][metric['id']] for row in rows if row['values'][metric['id']] is not None] + if numbers and metric['better'] in ('lower', 'higher'): + best[metric['id']] = min(numbers) if metric['better'] == 'lower' else max(numbers) + header_lines = max(len(_wrap(metric['title'], 12, _CELL - 12, 4)) for metric in metrics) + top = y + 8 + svg.text(_SIDE, top + 14, 'Subject', size=12, weight=500) + if grouped: + svg.text(_SIDE + _NAME, top + 14, data['group'], size=12, weight=500) + for column, metric in enumerate(metrics): + right = _SIDE + name_width + _CELL * (column + 1) - 4 + lines = _wrap(metric['title'], 12, _CELL - 12, 4) + for number, line in enumerate(lines): + svg.text(right, top + 14 + 15 * number, line, size=12, fill='ink', weight=500, anchor='end', + tooltip=metric['title'] if number == 0 else None) + hint = {'lower': 'lower is better', 'higher': 'higher is better'}.get(metric['better'], 'no direction') + for number, part in enumerate((_units(metric) or '', hint)): + svg.text(right, top + 14 + 15 * header_lines + 14 * number, _fit(part, 11, _CELL - 8), size=11, + anchor='end') + y = top + 36 + 15 * header_lines + svg.line(_SIDE, y, width - _SIDE, y, 'line_strong') + for row in rows: + svg.text(_SIDE, y + 16, _fit(row['title'], 12, _NAME - 8), size=12, fill='ink', tooltip=row['title']) + if grouped: + svg.text(_SIDE + _NAME, y + 16, _fit(row['group'], 12, 82), size=12) + for column, metric in enumerate(metrics): + right = _SIDE + name_width + _CELL * (column + 1) - 4 + value = row['values'][metric['id']] + is_best = value is not None and best.get(metric['id']) == value + text = format_number(value) + if is_best: + svg.dot(right - _width(text, 12) - 9, y + 12, 'good', None, r=3) + svg.text(right, y + 16, text, size=12, fill='ink' if value is not None else 'ink3', anchor='end', + weight=600 if is_best else None, numeric=True, + tooltip=f'{row["title"]}, {metric["title"]}: {text}' + (' (best)' if is_best else '')) + y += 24 + svg.line(_SIDE, y, width - _SIDE, y, 'line') + y += 10 + svg.dot(_SIDE + 4, y + 8, 'good', None, r=3) + svg.text(_SIDE + 14, y + 12, 'Best in its column; columns with no better direction mark none.', size=12) + return y + 20, width + + +# =============================================================== report + +_PLURALS = {'dataset': 'Datasets', 'model': 'Models', 'recipe': 'Recipes', 'benchmark': 'Benchmarks', + 'step': 'Steps', 'environment': 'Environments', 'chart': 'Charts'} +_STATE_WORDS = {'cannot-rebuild': 'cannot rebuild', 'needs-work': 'needs work', 'not-built': 'not built', + 'not-set-up': 'not set up', 'none': 'no state'} + + +def _style(colours): + c = colours + return f''' +:root {{ color-scheme: {'dark' if c['surface'] == _TOKENS['dark']['surface'] else 'light'}; }} +* {{ box-sizing: border-box; }} +body {{ margin: 0; background: {c['surface']}; color: {c['ink']}; + font: 14px/1.5 {FONT}; }} +main {{ max-width: 1040px; margin: 0 auto; padding: 32px 16px 64px; }} +h1 {{ font-size: 20px; font-weight: 600; margin: 0 0 4px; }} +h2 {{ font-size: 17px; font-weight: 600; margin: 40px 0 8px; padding-top: 16px; border-top: 1px solid {c['line']}; }} +h3 {{ font-size: 16px; font-weight: 600; margin: 32px 0 2px; }} +p {{ max-width: 66ch; margin: 0 0 8px; }} +.sum, .note {{ color: {c['ink2']}; font-weight: 400; }} +.note {{ font-size: 13px; margin-bottom: 12px; }} +.mono, code {{ font-family: {MONO}; font-size: 12.5px; }} +figure {{ margin: 0 -12px; overflow-x: auto; }} +figure svg {{ display: block; max-width: 100%; height: auto; }} +.wide {{ overflow-x: auto; }} +table {{ border-collapse: collapse; font-size: 13px; }} +th, td {{ text-align: left; padding: 4px 20px 4px 0; border-bottom: 1px solid {c['line']}; vertical-align: top; }} +th {{ font-weight: 500; color: {c['ink2']}; }} +td.n, th.n {{ text-align: right; font-variant-numeric: tabular-nums; }} +details {{ border-bottom: 1px solid {c['line']}; padding: 6px 0; }} +details:first-of-type {{ border-top: 1px solid {c['line']}; }} +summary {{ cursor: pointer; font-weight: 500; }} +details table {{ margin: 8px 0 4px; }} +.refused {{ color: {c['ink2']}; }} +''' + + +def _plural(count, word): + return f'{count} {word}' + ('' if count == 1 else 's') + + +def render_report(project, *, theme='light'): + """One self-contained HTML page of the project: where it stands, every chart, the results, the definitions.""" + if theme not in THEMES: + raise ValueError(f'theme is one of {", ".join(THEMES)}') + colours = _TOKENS[theme] + summary = project.summary() + rows = [row for row in project.definitions() if not row['removed']] + overview = project.results_overview() + out = [f'\n\n\n\n' + f'\n' + f'{_esc(summary["name"])}\n\n\n\n
\n'] + out.append(f'

{_esc(summary["name"])}

\n') + # The folder's own name only: a report may be shared, and the full path says where it sits on this machine. + folder_name = summary["folder"].rstrip('/').rsplit('/', 1)[-1] + out.append(f'

{_esc(folder_name)} · project ' + f'{_esc(summary["project_id"])}

\n') + + # Where the project stands. + kinds = summary['kinds'] + total = sum(kinds.values()) + kind_words = ', '.join(_plural(count, kind) for kind, count in kinds.items()) + with_results = sum(1 for item in overview if item['rows']) + differ = sum(1 for item in overview if item['differs_from_file']) + out.append(f'

{_plural(total, "definition")}: {_esc(kind_words)}. ' + f'{with_results} of {_plural(len(overview), "benchmark")} have results in the database' + + (f'; {differ} differ from their results file' if differ else '') + '.

\n') + states = sorted({row['state'] for row in rows}) + table = {} + for row in rows: + table.setdefault(row['kind'], {}).setdefault(row['state'], 0) + table[row['kind']][row['state']] += 1 + out.append('
\n' + + ''.join(f'' for state in states) + + '\n') + for kind in sorted(table): + out.append(f'' + + ''.join(f'' for state in states) + + f'\n') + out.append('
kind{_esc(_STATE_WORDS.get(state, state))}total
{_esc(kind)}{table[kind].get(state, "") or ""}{sum(table[kind].values())}
\n') + + # Charts. + charts = [row for row in rows if row['kind'] == 'chart'] + out.append(f'

Charts {len(charts)}

\n') + if not charts: + out.append('

The project has no chart definitions.

\n') + for row in charts: + out.append(f'

{_esc(row["title"])}

\n') + try: + data = chart_data(project, row['reference']) + except ProjectError as exc: + out.append(f'

{_esc(row["reference"])}: {_esc(exc)}

\n') + continue + out.append(f'

{_esc(row["reference"])} · {_esc(describe(data))}

\n') + out.append('
' + render_svg(data, theme=theme, heading=False).rstrip('\n') + '
\n') + + # Results overview. + out.append(f'

Results {_plural(len(overview), "benchmark")}

\n') + out.append('
\n' + '\n') + for item in overview: + saved = 'differs' if item['differs_from_file'] else 'saved' if item['rows'] else 'none yet' + out.append(f'' + f'' + f'\n') + out.append('
benchmarksubjects with resultswith values heresummary rowsresults file
{_esc(item["benchmark"])}{item["subjects_with_results"]}{item["subjects_with_values"]}{item["rows"]}{saved}
\n') + + # Definitions by kind. + out.append(f'

Definitions {total}

\n') + by_kind = {} + for row in rows: + by_kind.setdefault(row['kind'], []).append(row) + for kind in sorted(by_kind): + items = by_kind[kind] + out.append(f'
{_esc(_PLURALS.get(kind, kind))} {len(items)}\n' + '
\n\n') + for item in items: + mark = ' (unsaved)' if item['unsaved'] else '' + out.append(f'' + f'\n') + out.append('
referencetitlestate
{_esc(item["reference"])}{_esc(item["title"])}{_esc(_STATE_WORDS.get(item["state"], item["state"]) + mark)}
\n') + out.append('
\n\n\n') + return ''.join(out) From bb05521df290d4e3fd808e0228b21fed1f5e8df0 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Tue, 10 Nov 2026 16:06:49 -0700 Subject: [PATCH 013/131] docs(plan): record milestone 3 in the ledger Co-Authored-By: Claude Fable 5.2 --- .../execution-ledger.md | 48 +++++++++++++++++++ docs/plans/definition-first-projects/plan.md | 2 +- 2 files changed, 49 insertions(+), 1 deletion(-) diff --git a/docs/plans/definition-first-projects/execution-ledger.md b/docs/plans/definition-first-projects/execution-ledger.md index 8c246d92..99c07d5d 100644 --- a/docs/plans/definition-first-projects/execution-ledger.md +++ b/docs/plans/definition-first-projects/execution-ledger.md @@ -74,3 +74,51 @@ States: 216 cannot be rebuilt, 27 need work, 17 not built, 2 environments not se - Two settings files copied into `earlier-run-code/` (`fine-tuning.json`, `distillation.json`) carry per-tensor checksums of starting or teacher weights. They are kept as settings; the owner can reverse this in the build script's table. **For milestone 3:** import `results/*.csv` into summary tables; result rows from runs; saved charts; the first changes to existing Tuldok files (`app.py`, `agent_api.py`) to serve the new core, with its own start-up flag, route prefix and agent profile. + +## 2026-11-10 — milestone 3, results and charts + +**Owner instruction:** continue with milestone 3. Spec: [spec-m3.md](spec-m3.md). + +**Scope change.** Serving the new core from the Tuldok app moved from this milestone to milestone 7, where every operation of the new core is registered once and the pinned agent contract fixtures are regenerated once. In its place this milestone has a static report page. The plan's milestone table says so. + +**Commits** (none pushed). Tuldok `feat/definition-first-projects`: spec `5ce63364` and `1bc187b0`, results in the database `e297f5ee`, charts and report `f352f5ec`. Lab `reorg/reproducible-lab-20261102`: summary shape, values files and charts `06c254ee9`, subject titles `fff10a4a1`. + +| Slice | Files | Result | +| --- | --- | --- | +| T7 results | `tuldok_project/result_rows.py`, hooks in `store.py`, `results`, `values`, `import-values` | 39 new tests | +| T8 charts and report | `tuldok_project/charts.py`, `chart`, `report`, contract sections | 24 new tests, including one that makes every file read fail while each chart is answered | +| L3 lab | build script: one ungrouped row and one row per single group value; `--values-output`; eight chart definitions | 32 tests; `--check` passes | + +Command for all Tuldok tests as before: 231 tests, 30 s. + +**Acceptance, on the lab project:** + +| Check | Result | +| --- | --- | +| Open into an empty database imports every summary row | 4,716 rows from 16 results files; first open 1.1 s, second 0.01 s | +| Import of the per-case values | 477 files, 478,660 values, 12 s; 296 MB in the local database | +| `save` after that import rewrites `results/*.csv` byte for byte | Nothing to save; the lab folder unchanged in Git | +| A chart is answered without reading a result file | proven by test; the lab's progression chart of 127 models answers from the summary table | +| An export of the committed lab alone draws its charts | `check` 0 errors, `open` 0.8 s, `report` writes 8 charts (four with data, four for the new benchmarks that have no results yet) | + +The drawings were viewed as rendered images in both themes by the implementing agent and by the orchestrating session. + +**Accepted as implemented:** + +- Removing a benchmark keeps its `results_files` digest until `save` deletes the file, so the changed-on-disk check still applies. +- Setting a benchmark also drops summary rows for removed metrics and removed group keys. +- `status` gained `results_changed`; `save` returns `results_written` and `results_deleted`. +- A values file must have all six top-level fields and at least one value. +- A subject with no row, a count of 0, or no value for the chosen statistic is listed as missing and never drawn. +- Ranking bars on a linear axis start at zero; on a logarithmic axis at the decade below the smallest value. +- A metric's units of `1` are not shown. +- The report shows the folder's name, not its absolute path. + +**Follow-ups, none blocking:** + +- `charts.py` and `result_rows.py` call a few private names of `store.py` and `results.py` (`Project._execute`, `results._COMMIT`, `_produced_is_valid`, `_benchmark_names`); make them public when those files are next touched. +- The `result_values` table costs about 620 bytes a row with its two indexes; revisit if a project holds tens of millions of values. +- Text widths in the drawings are estimated without font metrics. +- The design tokens' "good" colour fails one of the palette validator's checks; it is always accompanied by a line, a label or a key. + +**Next:** milestone 4, the rebuild plan with estimates. It needs the lab's `surrogate.datasets plan` to print JSON. diff --git a/docs/plans/definition-first-projects/plan.md b/docs/plans/definition-first-projects/plan.md index b81d99f1..61ed45fa 100644 --- a/docs/plans/definition-first-projects/plan.md +++ b/docs/plans/definition-first-projects/plan.md @@ -247,7 +247,7 @@ Each milestone ends with a check against the lab. Sizes are relative. | 4 | Plan. The rebuild plan with estimates | Small | Planning the pilot model lists its steps in order with disk estimates and runs nothing | | 5 | Environments. Tuldok installs or connects an environment from its definition and checks it | Medium | On a machine without the lab's environments, Tuldok sets up the CPU and the GPU environment from their definitions and reports the versions it found. The GPU install is a multi-gigabyte download and needs the owner's go-ahead | | 6 | Build. Runs from a commit, per-definition limits, GPU, live progress, results published by the run | Large | On a fresh clone Tuldok builds one tiny dataset, trains one tiny model on the GPU with live progress, benchmarks it and charts it. This run needs the owner's go-ahead | -| 7 | Agent operations and command line for all of the above | Medium | An agent repeats milestone 6 through the interface alone | +| 7 | Serve the new core from the Tuldok app, with agent operations for all of the above | Medium | The app opens a project folder; an agent repeats milestone 6 through the interface alone | | 8 | Convert the lab for good, then retire the old code. Product archive, tracked export replaced, old project-files modules removed | Medium | The lab repository holds the new folder only; the clean-install test in the summary passes. Before any old module is deleted, a written check lists every capability of the old project-files mode as covered, moved or deliberately dropped, and the owner signs it off | The workspace redesign (the Map variant chosen on 2026-11-03) builds on milestones 2 and 3 and gets its own plan. From 58cd0d141e3bca968c66a688a872da6c0d5b359c Mon Sep 17 00:00:00 2001 From: MrScripty Date: Tue, 10 Nov 2026 16:11:31 -0700 Subject: [PATCH 014/131] docs(plan): milestone 4 spec for the rebuild plan Co-Authored-By: Claude Fable 5.2 --- .../definition-first-projects/spec-m4.md | 65 +++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 docs/plans/definition-first-projects/spec-m4.md diff --git a/docs/plans/definition-first-projects/spec-m4.md b/docs/plans/definition-first-projects/spec-m4.md new file mode 100644 index 00000000..f7416c78 --- /dev/null +++ b/docs/plans/definition-first-projects/spec-m4.md @@ -0,0 +1,65 @@ +# Implementation spec: milestone 4, the rebuild plan + +This continues [spec-m1-m2.md](spec-m1-m2.md) and [spec-m3.md](spec-m3.md). Section 1 of the first (rules for implementers) applies unchanged. The milestone changes no existing Tuldok file outside `tuldok_project/`. + +**Done when:** `python -m tuldok_project plan recipes/pilot-dense-k1` lists the steps that build the pilot model in dependency order, with the disk each step declares, and executes nothing; and planning an earlier model that cannot be rebuilt says so and names the cause. + +## 1. What a plan is + +A plan answers: to have this definition's product on this machine, what has to be built, in what order, and what stands in the way. Making a plan reads the database only. It never runs a command, including a definition's `estimate` command: that is project code, and running it is a separate, explicit action that arrives with environments in milestone 5. Until then a step's figures are the ones its definition declares in `resources`. + +## 2. Which definitions are in a plan + +Start from the targets and follow these edges, repeatedly: + +| Edge role | Followed | +| --- | --- | +| `input:` | yes | +| `environment` | yes | +| `subject:` (a benchmark's subject recipe) | yes | +| `model`, `cases` | no; nothing is built for them | +| `benchmark` (from a chart) | a chart target is replaced by its benchmark | + +A `model` or a `chart` is never a step. A target that is a model has an empty plan and a sentence saying a model is not built. + +## 3. Steps + +Steps are in `graph.order` (everything after what it uses), numbered from 1. Each step has: + +| Field | Content | +| --- | --- | +| `reference`, `kind`, `title`, `state` | from the definition and `graph.states` | +| `action` | `set-up` for an environment that is `not-set-up`; `build` for a `not-built` dataset, recipe, step or benchmark; `blocked` for `cannot-rebuild` or `needs-work` | +| `command`, `environment` | from `run`, placeholders not filled in; null when absent | +| `inputs` | for each input name, the reference that provides it and the named output if one is given | +| `resources` | as declared: `gpu`, `cpu_threads`, `memory_gb`, `wall_hours`, `disk_gb` | +| `estimate` | null in this milestone | +| `blocked_by` | for a blocked step: the definitions that are the cause, each with its reference, its own `earlier_work.rebuild` label and its reason. A cause is the step itself or anything it reaches through `input:` edges whose own label is `no` or `needs-work`. At most five are listed, nearest first, with a count of the rest | +| `subjects` | benchmarks only: `run`, the subject names the benchmark would run, and `skipped`, each with a name and a reason. A subject is skipped when its recipe is blocked. A subject with no recipe is run | + +A benchmark is `build` when it is `not-built` and at least one subject would run. It is never blocked by a subject. + +## 4. Summary + +| Field | Content | +| --- | --- | +| `targets` | the references asked for, after replacing charts | +| `buildable` | true when no target is blocked | +| `counts` | steps by action | +| `gpu_steps` | `build` steps that declare `gpu: true` | +| `disk_gb`, `disk_unknown` | the sum of declared `disk_gb` over `build` steps, and how many `build` steps declare none | +| `wall_hours`, `wall_unknown` | the same for `wall_hours` | + +Blocked steps are listed but not counted in the totals. + +## 5. Interface + +- `plan.build_plan(project, targets) -> dict` with `steps` and the summary fields. An unknown reference raises `ProjectError` `not-found`. It reads through the `Project` and holds no state. +- `python -m tuldok_project plan FOLDER TARGET... [--all] [--json]`. `--all` plans every dataset, recipe, step and benchmark. Text output is one opening sentence (what is planned, how many steps to build, to set up and blocked), then one line per step in order with its number, action, reference, what it needs, and GPU, disk and time as declared (`?` when not), then for each blocked target its causes with their reasons, then the totals. Exit status 0 whether or not the plan is buildable; `--json` carries `buildable`. + +## 6. Slices + +| Slice | Files | +| --- | --- | +| T9 plan | `tuldok_project/plan.py` (new), `plan` in `__main__.py`, `tests/test_tuldok_project_plan.py`, a "Planning a build" section in `docs/contracts/project-folder.md` | +| L4 lab | `lab:surrogate/datasets/`: a `--json` option on `plan` that prints one JSON object with `disk_bytes` and `items`, with a test; `lab:projects/surrogate-lab/datasets/*.json` for the two new datasets: `resources.disk_gb` from that command's output | From 75406305fc00ce8588580434d481d26f214990a0 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Tue, 10 Nov 2026 16:30:51 -0700 Subject: [PATCH 015/131] feat(project): plan what has to be built for a definition plan.build_plan lists, in dependency order, the steps that build one or more definitions: environments to set up, steps to build with the GPU, disk and time their definitions declare, and blocked targets with the definitions that cause the block and their reasons. Nothing is followed out of a blocked step, and a benchmark names subjects it would skip. Making a plan reads the database only; a test makes process creation and file opening fail while it runs. Command line: python -m tuldok_project plan FOLDER TARGET... [--all]. Co-Authored-By: Claude Fable 5.2 --- docs/contracts/project-folder.md | 160 +++++++- .../execution-ledger.md | 31 ++ .../definition-first-projects/spec-m4.md | 8 +- tests/test_tuldok_project_cli.py | 73 ++++ tests/test_tuldok_project_plan.py | 367 ++++++++++++++++++ tuldok_project/__main__.py | 149 ++++++- tuldok_project/plan.py | 236 +++++++++++ 7 files changed, 1017 insertions(+), 7 deletions(-) create mode 100644 tests/test_tuldok_project_plan.py create mode 100644 tuldok_project/plan.py diff --git a/docs/contracts/project-folder.md b/docs/contracts/project-folder.md index a619d491..75c0ee4f 100644 --- a/docs/contracts/project-folder.md +++ b/docs/contracts/project-folder.md @@ -588,7 +588,7 @@ Options: | Option | Commands | Meaning | | --- | --- | --- | | `--database-url URL` | all but `check` | The Postgres database. Without it, the `TULDOK_DATABASE_URL` environment variable is used; with neither, the command stops with exit status 2. | -| `--json` | `open`, `list`, `show`, `graph`, `status`, `save`, `results`, `values`, `import-values`, `chart` | Print one JSON document with the same content as the text. | +| `--json` | `open`, `list`, `show`, `graph`, `status`, `save`, `results`, `values`, `import-values`, `chart`, `plan` | Print one JSON document with the same content as the text. | | `--rebind` | all that open | The copy is bound to the folder it was first opened from. Opening the same project from another path is refused unless `--rebind` is given, which binds the copy to the new path. | | `--keep` | all that open | Where a file changed on disk and the same definition has unsaved edits, keep the edits; the changed file becomes the version that `save` replaces. | | `--discard` | all that open | Where a file changed on disk and the same definition has unsaved edits, drop the edits and take the file. | @@ -827,10 +827,166 @@ $ .venv/bin/python -m tuldok_project report FOLDER --output report.html --theme Wrote report.html (4 charts, 24626 bytes). ``` +## Planning a build + +A plan says what has to be built on this machine to have one or more +definitions, in what order, and what stands in the way. Making a plan runs +nothing. It reads the database copy only: it starts no command, including a +definition's `estimate` command, and opens no file of the folder or the code. +The figures in a plan are the ones each definition declares in +`run.resources`. + +| Command | Does | +| --- | --- | +| `plan TARGET... [--all]` | Prints the plan for the named definitions. `--all` plans every dataset, recipe, step and benchmark, together with any `TARGET` given. | + +`TARGET` is a reference such as `recipes/stepper-k2`. A plan that cannot be +built is still a plan: the exit status is 0 whether or not it can be built. +A target that is not a definition of the project exits with status 1 and the +message `There is no definition datasets/nothing.`; no target and no `--all` +is a usage error, status 2. + +### Which definitions are in a plan + +Starting from the targets, the plan follows these uses, again and again: + +| Use | Followed | +| --- | --- | +| `input:` | yes | +| `environment` | yes | +| `subject:` | only when the subject's recipe is not blocked | +| `model`, `cases` | no; nothing is built for them | +| `benchmark` | a chart target is replaced by its benchmark | + +A model or a chart is never a step. A model target adds nothing to the plan and +a sentence saying that a model is not built, only the recipes that train it. + +Nothing is followed out of a blocked step: what it would use is not work anyone +can do. Its causes are still found over the whole graph and reported with it, +but they are not steps unless they are targets themselves. A skipped subject's +recipe is named under the benchmark's subjects and is not a step either. So a +plan lists every step that can and must be done, and each blocked target once. + +### Steps and their actions + +The steps are in build order, each after everything it uses (ties broken by +reference), numbered from 1. Each step has one action: + +| Action | For | +| --- | --- | +| `set-up` | an environment (state `not-set-up`) | +| `build` | a dataset, recipe, step or benchmark in state `not-built` | +| `blocked` | a definition in state `cannot-rebuild` or `needs-work`, and a benchmark with no subject to run | + +A blocked step is explained by its causes: the definitions whose own +`earlier_work.rebuild` is `no` or `needs-work`, among the step itself and +everything it reaches through inputs, directly or further up. A definition +that is blocked only because of what it uses is not a cause. At most five +causes are listed, nearest first (fewest inputs away, then by reference), with +a count of the rest. + +A benchmark runs once per subject. A subject whose recipe is blocked is +skipped, with the reason; a subject with no recipe is run. The benchmark is +`build` when at least one subject would run. It is never blocked because one of +its subjects is; when no subject would run, it is `blocked` with no cause of +its own. + +The plan can be built when no target is blocked. Blocked steps are listed but +not counted in the totals. + +### Totals + +The totals count `build` steps only: + +- how many steps there are to build, and how many of them declare `gpu: true`; +- the sum of the declared `disk_gb`, and how many build steps declare none; +- the sum of the declared `wall_hours`, and how many build steps declare none. + +### Text output + +The text is one opening sentence (how many steps there are to build, to set up +and blocked, and whether the targets can be built), then one line per step with +its number, action, GPU (`yes` for `gpu: true`, otherwise `-`: a step that +does not declare `gpu` needs none), disk and time as declared (`?` when not +declared) and its reference. Under a step are what it uses (each input by name, +with the named output in brackets), the environment it runs in, a benchmark's +subjects, and for a blocked step what blocks it. Then come the causes of each +blocked target with their reasons, and the totals last. + +``` +$ .venv/bin/python -m tuldok_project plan FOLDER recipes/stepper-k2 +4 steps to build, 1 to set up, 0 blocked: recipes/stepper-k2 can be built. + +# action gpu disk time reference +1 set-up - - - environments/lab-cpu +2 build - ? 0.1 h steps/solver + in environments/lab-cpu +3 build - ? ? datasets/waves + solver: steps/solver (binary) + in environments/lab-cpu +4 build - 0.1 GB 0.5 h recipes/stepper-k1 + training: datasets/waves + in environments/lab-cpu +5 build - ? ? recipes/stepper-k2 + start: recipes/stepper-k1 (weights) + training: datasets/waves + in environments/lab-cpu + +To build: 4 steps, 0 on a GPU. +Disk: 0.1 GB declared; 3 of 4 declare none. +Time: 0.6 h declared; 2 of 4 declare none. +Figures are as the definitions declare them; no command was run. +$ .venv/bin/python -m tuldok_project plan FOLDER recipes/early-fit +0 steps to build, 0 to set up, 1 blocked: recipes/early-fit cannot be built. + +# action gpu disk time reference +1 blocked - ? ? recipes/early-fit + blocked: its own label is rebuild no + +recipes/early-fit cannot be built: + no recipes/early-fit + Trained by the earlier study harness; its command and training data were + not recorded. + +Nothing would be built, so there are no totals. +``` + +### JSON output + +With `--json`, `plan` prints one object: + +| Field | Meaning | +| --- | --- | +| `targets` | the references planned, in the order given, with each chart replaced by its benchmark and repeats left out | +| `every` | true with `--all` | +| `buildable` | true when no target is blocked | +| `blocked_targets` | the targets that are blocked | +| `counts` | the number of steps of each action: `{"build", "set-up", "blocked"}` | +| `gpu_steps` | how many build steps declare `gpu: true` | +| `disk_gb`, `disk_unknown` | the sum of the declared `disk_gb` over build steps, and how many build steps declare none | +| `wall_hours`, `wall_unknown` | the same for `wall_hours` | +| `notes` | sentences about targets that are not built themselves: a model, or a chart replaced by its benchmark | +| `steps` | the steps in order | + +Each step: + +| Field | Meaning | +| --- | --- | +| `number` | its place in the order, from 1 | +| `reference`, `kind`, `title`, `state` | from the definition; the state as `list` shows it | +| `action` | `build`, `set-up` or `blocked` | +| `command`, `environment` | from `run`, placeholders not filled in; null when absent | +| `inputs` | each input name to `{"reference", "output"}`; `output` is null for a whole product | +| `resources` | `gpu`, `cpu_threads`, `memory_gb`, `wall_hours`, `disk_gb` as declared; null when not declared (a null `gpu` means no GPU is needed) | +| `estimate` | always null: no estimate command is run | +| `blocked_by` | for a blocked step, up to five causes, each `{"reference", "rebuild", "reason"}`; empty otherwise | +| `blocked_by_more` | how many more causes there are | +| `subjects` | benchmarks only: `run`, the subject names that would run, and `skipped`, each `{"name", "recipe", "reason"}` | + ## What the format does not do yet The folder is checked, can be opened, edited and saved through the database -copy, and its results can be read and drawn, nothing more. Tuldok does not yet run any command, +copy, its results can be read and drawn, and a build can be planned, nothing more. Tuldok does not yet run any command, estimate, install an environment, compare installed package versions, write settings files or read the contents of notes. The `run`, `resources`, `estimate`, `install` and `settings` fields record what a later Tuldok will use. diff --git a/docs/plans/definition-first-projects/execution-ledger.md b/docs/plans/definition-first-projects/execution-ledger.md index 99c07d5d..b2863b71 100644 --- a/docs/plans/definition-first-projects/execution-ledger.md +++ b/docs/plans/definition-first-projects/execution-ledger.md @@ -122,3 +122,34 @@ The drawings were viewed as rendered images in both themes by the implementing a - The design tokens' "good" colour fails one of the palette validator's checks; it is always accompanied by a line, a label or a key. **Next:** milestone 4, the rebuild plan with estimates. It needs the lab's `surrogate.datasets plan` to print JSON. + +## 2026-11-10 — milestone 4, the rebuild plan + +**Owner instruction:** continue with milestone 4. Spec: [spec-m4.md](spec-m4.md). + +**Commits** (none pushed). Tuldok `feat/definition-first-projects`: spec `58cd0d14`, then the plan. Lab `reorg/reproducible-lab-20261102`: `plan --json` and declared disk `391d1e188`. + +| Slice | Files | Result | +| --- | --- | --- | +| T9 plan | `tuldok_project/plan.py`, `plan` in `__main__.py`, `tests/test_tuldok_project_plan.py`, the "Planning a build" contract section | 30 new tests, including one that makes process creation and file opening fail while a plan of every target is made | +| L4 lab | `lab:surrogate/datasets/__main__.py` (`plan --json`), its test, and `resources.disk_gb` in the two new dataset definitions (1.4 GB and 135.2 GB) | the lab's 72 `surrogate` tests pass | + +Command for all Tuldok tests as before: 261 tests. + +**Acceptance, on the lab project:** + +- `plan recipes/pilot-dense-k1`: two environments to set up, then the reference solver, `datasets/sinusoidal-v1` (1.4 GB declared) and the recipe (GPU), in that order; nothing run. +- `plan recipes/water-residual-linear-cuda-training--72953af8f73b705f`: one blocked step, with its two causes and their reasons (its own command needs adapting; its training set has no single command line). +- `plan --all`: 17 steps to build, 2 to set up, 243 of 260 targets blocked; 137 GB of disk declared. + +**Settled during the milestone** (in the spec): + +- Making a plan never runs a definition's `estimate` command. A step's figures are those its definition declares; running estimates is an explicit action that arrives with environments. +- Edges are not followed out of a blocked step, and a benchmark subject whose recipe is blocked is named as skipped without becoming a step. A plan lists work that can be done, and each blocked target once. +- A benchmark with no subject that would run is blocked, with no cause listed. +- An absent `resources.gpu` means no GPU is needed. +- Targets and `--all` can be combined; giving neither is a usage error. + +**Follow-ups, none blocking:** `plan.py` reads all documents through the private `Project._documents`; a public accessor belongs with the other private-name cleanups. No lab definition declares `wall_hours`, so plans show no time. + +**Next:** milestone 5, environments. Its acceptance installs packages (about 1 GB for the CPU environment, several GB for the GPU one), which needs the owner's go-ahead. diff --git a/docs/plans/definition-first-projects/spec-m4.md b/docs/plans/definition-first-projects/spec-m4.md index f7416c78..8d62c761 100644 --- a/docs/plans/definition-first-projects/spec-m4.md +++ b/docs/plans/definition-first-projects/spec-m4.md @@ -16,10 +16,12 @@ Start from the targets and follow these edges, repeatedly: | --- | --- | | `input:` | yes | | `environment` | yes | -| `subject:` (a benchmark's subject recipe) | yes | +| `subject:` (a benchmark's subject recipe) | only when that recipe is not blocked; a skipped subject's recipe is named under `subjects.skipped` and is not a step | | `model`, `cases` | no; nothing is built for them | | `benchmark` (from a chart) | a chart target is replaced by its benchmark | +Edges are not followed out of a blocked step: what it would need is not work anyone can do, and its causes are reported in `blocked_by`, which is worked out from the whole graph. So a plan lists every step that can and must be done, and each blocked target once, without the things that only a blocked step would use. + A `model` or a `chart` is never a step. A target that is a model has an empty plan and a sentence saying a model is not built. ## 3. Steps @@ -32,12 +34,12 @@ Steps are in `graph.order` (everything after what it uses), numbered from 1. Eac | `action` | `set-up` for an environment that is `not-set-up`; `build` for a `not-built` dataset, recipe, step or benchmark; `blocked` for `cannot-rebuild` or `needs-work` | | `command`, `environment` | from `run`, placeholders not filled in; null when absent | | `inputs` | for each input name, the reference that provides it and the named output if one is given | -| `resources` | as declared: `gpu`, `cpu_threads`, `memory_gb`, `wall_hours`, `disk_gb` | +| `resources` | as declared: `gpu`, `cpu_threads`, `memory_gb`, `wall_hours`, `disk_gb`. An absent `gpu` means the step needs none | | `estimate` | null in this milestone | | `blocked_by` | for a blocked step: the definitions that are the cause, each with its reference, its own `earlier_work.rebuild` label and its reason. A cause is the step itself or anything it reaches through `input:` edges whose own label is `no` or `needs-work`. At most five are listed, nearest first, with a count of the rest | | `subjects` | benchmarks only: `run`, the subject names the benchmark would run, and `skipped`, each with a name and a reason. A subject is skipped when its recipe is blocked. A subject with no recipe is run | -A benchmark is `build` when it is `not-built` and at least one subject would run. It is never blocked by a subject. +A benchmark is `build` when it is `not-built` and at least one subject would run. It is never blocked by a subject that has a blocked recipe; when no subject would run at all it is `blocked` with an empty `blocked_by` and the text says no subject would run. ## 4. Summary diff --git a/tests/test_tuldok_project_cli.py b/tests/test_tuldok_project_cli.py index 2ce59861..2769935d 100644 --- a/tests/test_tuldok_project_cli.py +++ b/tests/test_tuldok_project_cli.py @@ -351,5 +351,78 @@ def test_chart_of_a_benchmark_without_results_is_empty(self): self.assertIn('No results yet: none of the 3 subjects of benchmarks/rollout', drawing.read_text(encoding='utf-8')) +@unittest.skipUnless(DATABASE, 'TULDOK_DATABASE_URL is not set; database tests need a disposable cluster.') +class PlanCommand(FolderCase): + """plan: the opening sentence, the steps in order, the causes, the totals; and --json.""" + + def setUp(self): + super().setUp() + self.addCleanup(store.drop_project, self.project_id) + + def test_a_buildable_plan_as_text(self): + lines = self.run_ok('plan', self.folder, 'benchmarks/rollout').splitlines() + self.assertEqual(lines[0], '5 steps to build, 1 to set up, 0 blocked: benchmarks/rollout can be built.') + self.assertEqual(lines[2].split(), ['#', 'action', 'gpu', 'disk', 'time', 'reference']) + rows = [line.split() for line in lines[3:] if line[:1].isdigit()] + self.assertEqual([row[:2] + row[-1:] for row in rows], [ + ['1', 'set-up', 'environments/lab-cpu'], ['2', 'build', 'steps/solver'], ['3', 'build', 'datasets/waves'], + ['4', 'build', 'recipes/stepper-k1'], ['5', 'build', 'recipes/stepper-k2'], + ['6', 'build', 'benchmarks/rollout']]) + self.assertIn(['4', 'build', '-', '0.1', 'GB', '0.5', 'h', 'recipes/stepper-k1'], rows) + self.assertIn(['2', 'build', '-', '?', '0.1', 'h', 'steps/solver'], rows) # no gpu declared: none needed + reference_column = lines[2].index('reference') + self.assertTrue(all(line.index('environments/lab-cpu') == reference_column + for line in lines if line.startswith('1 '))) + self.assertIn('start: recipes/stepper-k1 (weights)', [line.strip() for line in lines]) + self.assertIn('skips 1 whose recipe is blocked: early-fit', [line.strip() for line in lines]) + self.assertEqual(lines[-4:], ['To build: 5 steps, 0 on a GPU.', + 'Disk: 0.1 GB declared; 4 of 5 declare none.', + 'Time: 0.6 h declared; 3 of 5 declare none.', + 'Figures are as the definitions declare them; no command was run.']) + self.assertTrue(all(len(line) <= 80 for line in lines), lines) + + def test_a_blocked_target_names_its_cause_and_still_exits_0(self): + lines = self.run_ok('plan', self.folder, 'recipes/early-fit').splitlines() + self.assertEqual(lines[0], '0 steps to build, 0 to set up, 1 blocked: recipes/early-fit cannot be built.') + start = lines.index('recipes/early-fit cannot be built:') + self.assertEqual(lines[start + 1], ' no recipes/early-fit') + self.assertEqual(' '.join(line.strip() for line in lines[start + 2:start + 4]), + 'Trained by the earlier study harness; its command and training data were not recorded.') + self.assertEqual(lines[-1], 'Nothing would be built, so there are no totals.') + made = self.run_json('plan', self.folder, 'recipes/early-fit') + self.assertFalse(made['buildable']) + self.assertEqual(made['steps'][0]['blocked_by'][0]['rebuild'], 'no') + + def test_json_charts_models_and_all(self): + made = self.run_json('plan', self.folder, 'charts/rollout-ranking', 'models/stepper') + self.assertEqual(made['targets'], ['benchmarks/rollout', 'models/stepper']) + for field in ('buildable', 'counts', 'gpu_steps', 'disk_gb', 'disk_unknown', 'wall_hours', 'wall_unknown', + 'notes', 'steps'): + self.assertIn(field, made) + self.assertTrue(made['buildable']) + self.assertEqual(made['counts'], {'build': 5, 'set-up': 1, 'blocked': 0}) + model = self.run_ok('plan', self.folder, 'models/stepper').splitlines() + self.assertEqual(model[0], 'Nothing to build for models/stepper.') + self.assertEqual(' '.join(model[1:3]), + 'models/stepper is a model; a model is not built, only the recipes that train it.') + self.assertEqual(model[-1], 'Nothing would be built, so there are no totals.') + both = self.run_ok('plan', self.folder, 'steps/solver', 'recipes/stepper-k1').splitlines() + self.assertEqual(both[0], '3 steps to build, 1 to set up, 0 blocked: all 2 targets can be built.') + self.assertIn('Time: 0.6 h declared; 1 of 3 declares none.', both) + alone = self.run_ok('plan', self.folder, 'datasets/waves').splitlines() + self.assertIn('Disk: no step declares it.', alone) + every = self.run_ok('plan', self.folder, '--all').splitlines() + self.assertEqual(every[:2], ['5 steps to build, 1 to set up, 1 blocked: 1 of 6 targets (every dataset,', + 'recipe, step and benchmark) cannot be built.']) + self.assertFalse(self.run_json('plan', self.folder, '--all')['buildable']) + + def test_unknown_references_and_usage(self): + done = run('plan', self.folder, 'steps/solver', 'datasets/nothing') + self.assertEqual((done.returncode, done.stdout, done.stderr), (1, '', 'There is no definition datasets/nothing.\n')) + done = run('plan', self.folder) + self.assertEqual(done.returncode, 2) + self.assertIn('--all', done.stderr) + + if __name__ == '__main__': unittest.main() diff --git a/tests/test_tuldok_project_plan.py b/tests/test_tuldok_project_plan.py new file mode 100644 index 00000000..58a962f2 --- /dev/null +++ b/tests/test_tuldok_project_plan.py @@ -0,0 +1,367 @@ +"""The rebuild plan (docs/plans/definition-first-projects/spec-m4.md). + +make_plan is tested as a pure function over the fixture's decoded +definitions, changed in memory where a test needs another shape of graph. +build_plan is tested against the database copy only when TULDOK_DATABASE_URL +names a disposable cluster (spec-m1-m2.md, section 1); each of those tests +copies tests/fixtures/tuldok_project/minimal, gives it a fresh project id and +drops that project's schema afterwards. One of them makes starting a process +and opening a file fail while the plan is made. +""" +import builtins +import copy +import io +import json +import os +from pathlib import Path +import shutil +import subprocess +import sys +import tempfile +import unittest +from unittest import mock +import uuid + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) + +from tuldok_project import graph, plan, store # noqa: E402 +from tuldok_project.store import ProjectError # noqa: E402 + +REPOSITORY = Path(__file__).resolve().parents[1] +FIXTURE = REPOSITORY / 'tests' / 'fixtures' / 'tuldok_project' / 'minimal' +DATABASE = os.environ.get('TULDOK_DATABASE_URL') + + +def _fixture_documents(): + found = {} + for path in sorted((FIXTURE / 'project').glob('*/*.json')): + found[f'{path.parent.name}/{path.stem}'] = json.loads(path.read_text(encoding='utf-8')) + return found + + +def _references(made): + return [step['reference'] for step in made['steps']] + + +def _step(made, reference): + return next(step for step in made['steps'] if step['reference'] == reference) + + +class PlanCase(unittest.TestCase): + + def setUp(self): + self.documents = _fixture_documents() + + def mark(self, reference, rebuild, reason=None): + self.documents[reference]['earlier_work'] = {'rebuild': rebuild, 'reason': reason or f'{reference} test.'} + + def make(self, *targets, every=False): + return plan.make_plan(self.documents, list(targets), every=every) + + +class Closure(PlanCase): + """Which definitions enter a plan: section 2.""" + + def test_inputs_and_environments_are_followed_models_are_not(self): + made = self.make('recipes/stepper-k2') + self.assertEqual(sorted(_references(made)), ['datasets/waves', 'environments/lab-cpu', 'recipes/stepper-k1', + 'recipes/stepper-k2', 'steps/solver']) + self.assertNotIn('models/stepper', _references(made)) # role model + + def test_subjects_are_followed_cases_and_charts_are_not(self): + other = copy.deepcopy(self.documents['datasets/waves']) + other['title'] = 'Other scenes' + self.documents['datasets/other'] = other + self.documents['benchmarks/rollout']['cases']['dataset'] = 'datasets/other' + references = _references(self.make('benchmarks/rollout')) + for reference in ('recipes/stepper-k1', 'recipes/stepper-k2'): + self.assertIn(reference, references) # role subject: + self.assertNotIn('recipes/early-fit', references) # a blocked subject recipe is not a step + self.assertNotIn('datasets/other', references) # role cases + self.assertFalse([reference for reference in references if reference.startswith(('charts/', 'models/'))]) + + def test_nothing_is_followed_out_of_a_blocked_step(self): + self.mark('datasets/waves', 'no', 'The scenes were made by hand.') + made = self.make('recipes/stepper-k1') + self.assertEqual(_references(made), ['recipes/stepper-k1']) # not its dataset, solver or environment + self.assertEqual(made['counts'], {'build': 0, 'set-up': 0, 'blocked': 1}) + self.assertEqual(made['steps'][0]['blocked_by'], [{'reference': 'datasets/waves', 'rebuild': 'no', + 'reason': 'The scenes were made by hand.'}]) + # A cause is a step when it is a target itself. + both = self.make('recipes/stepper-k1', 'datasets/waves') + self.assertEqual(sorted(_references(both)), ['datasets/waves', 'recipes/stepper-k1']) + + def test_a_blocked_subject_recipe_and_what_only_it_uses_are_not_steps(self): + extra = copy.deepcopy(self.documents['datasets/waves']) + extra['title'] = 'Extra scenes' + self.documents['datasets/extra'] = extra + self.documents['recipes/stepper-k2']['run']['inputs']['extra'] = 'datasets/extra' + self.mark('recipes/stepper-k2', 'needs-work') + made = self.make('benchmarks/rollout') + references = _references(made) + for reference in ('recipes/stepper-k2', 'datasets/extra', 'recipes/early-fit'): + self.assertNotIn(reference, references) + self.assertEqual(sorted(references), ['benchmarks/rollout', 'datasets/waves', 'environments/lab-cpu', + 'recipes/stepper-k1', 'steps/solver']) + skipped = _step(made, 'benchmarks/rollout')['subjects']['skipped'] + self.assertEqual([(item['name'], item['recipe']) for item in skipped], + [('stepper-k2', 'recipes/stepper-k2'), ('early-fit', 'recipes/early-fit')]) + self.assertEqual(made['counts']['blocked'], 0) + + def test_an_environment_alone(self): + made = self.make('environments/lab-cpu') + self.assertEqual([(step['reference'], step['action']) for step in made['steps']], + [('environments/lab-cpu', 'set-up')]) + self.assertTrue(made['buildable']) + + def test_a_chart_is_replaced_by_its_benchmark(self): + made = self.make('charts/rollout-ranking') + self.assertEqual(made['targets'], ['benchmarks/rollout']) + self.assertEqual(made['steps'], self.make('benchmarks/rollout')['steps']) + self.assertEqual(made['notes'], ['charts/rollout-ranking is drawn from benchmarks/rollout, ' + 'which is planned in its place.']) + + def test_a_model_is_not_built(self): + made = self.make('models/stepper') + self.assertEqual(made['targets'], ['models/stepper']) + self.assertEqual(made['steps'], []) + self.assertTrue(made['buildable']) + self.assertEqual(made['counts'], {'build': 0, 'set-up': 0, 'blocked': 0}) + self.assertEqual(made['notes'], ['models/stepper is a model; a model is not built, ' + 'only the recipes that train it.']) + + def test_several_targets_share_their_steps(self): + made = self.make('recipes/stepper-k1', 'steps/solver', 'charts/rollout-ranking', 'benchmarks/rollout') + self.assertEqual(made['targets'], ['recipes/stepper-k1', 'steps/solver', 'benchmarks/rollout']) + references = _references(made) + self.assertEqual(len(references), len(set(references))) + self.assertEqual(sorted(references), sorted(_references(self.make('benchmarks/rollout')))) + self.assertTrue(self.make('recipes/stepper-k1', 'steps/solver')['buildable']) + + def test_every(self): + made = self.make(every=True) + self.assertTrue(made['every']) + self.assertEqual(made['targets'], ['benchmarks/rollout', 'datasets/waves', 'recipes/early-fit', + 'recipes/stepper-k1', 'recipes/stepper-k2', 'steps/solver']) + self.assertEqual(sorted(_references(made)), sorted(made['targets'] + ['environments/lab-cpu'])) + self.assertFalse(made['buildable']) # recipes/early-fit is a target + self.assertEqual(made['blocked_targets'], ['recipes/early-fit']) + + def test_an_unknown_target(self): + with self.assertRaisesRegex(ValueError, 'There is no definition datasets/nothing.'): + self.make('datasets/nothing') + + +class Steps(PlanCase): + """Order, actions and the fields of a step: section 3.""" + + def test_order_puts_each_step_after_what_it_uses(self): + made = self.make('benchmarks/rollout') + references = _references(made) + self.assertEqual([step['number'] for step in made['steps']], list(range(1, len(references) + 1))) + self.assertEqual(references, graph.order({reference: self.documents[reference] for reference in references})) + position = {reference: index for index, reference in enumerate(references)} + for edge in graph.edges(self.documents): + if edge.from_ref in position and edge.to_ref in position: + self.assertLess(position[edge.to_ref], position[edge.from_ref], edge) + + def test_every_action(self): + self.mark('recipes/stepper-k2', 'needs-work') + made = self.make('benchmarks/rollout', 'recipes/stepper-k2', 'recipes/early-fit') + actions = {step['reference']: (step['state'], step['action']) for step in made['steps']} + self.assertEqual(actions, { + 'environments/lab-cpu': ('not-set-up', 'set-up'), + 'steps/solver': ('not-built', 'build'), + 'datasets/waves': ('not-built', 'build'), + 'recipes/stepper-k1': ('not-built', 'build'), + 'recipes/stepper-k2': ('needs-work', 'blocked'), + 'recipes/early-fit': ('cannot-rebuild', 'blocked'), + 'benchmarks/rollout': ('not-built', 'build'), + }) + self.assertEqual(made['counts'], {'build': 4, 'set-up': 1, 'blocked': 2}) + self.assertFalse(made['buildable']) + self.assertEqual(made['blocked_targets'], ['recipes/stepper-k2', 'recipes/early-fit']) + + def test_fields_of_a_step(self): + made = self.make('recipes/stepper-k2') + step = _step(made, 'recipes/stepper-k2') + self.assertEqual(step['kind'], 'recipe') + self.assertEqual(step['title'], 'Stepper fine-tuned from k1') + self.assertEqual(step['command'][:3], ['python', 'lab/train.py', '--start']) + self.assertIn('{inputs.start}', step['command']) # placeholders not filled in + self.assertEqual(step['environment'], 'environments/lab-cpu') + self.assertEqual(step['inputs'], {'start': {'reference': 'recipes/stepper-k1', 'output': 'weights'}, + 'training': {'reference': 'datasets/waves', 'output': None}}) + self.assertEqual(step['resources'], {name: None for name in plan.RESOURCES}) + self.assertIsNone(step['estimate']) + self.assertEqual((step['blocked_by'], step['blocked_by_more']), ([], 0)) + self.assertNotIn('subjects', step) + self.assertEqual(_step(made, 'recipes/stepper-k1')['resources'], + {'gpu': False, 'cpu_threads': 4, 'memory_gb': 2, 'wall_hours': 0.5, 'disk_gb': 0.1}) + environment = _step(made, 'environments/lab-cpu') + self.assertEqual((environment['command'], environment['environment'], environment['inputs']), (None, None, {})) + # A dataset's estimate command is never run: the estimate stays null. + self.assertIsNone(_step(made, 'datasets/waves')['estimate']) + + +class Causes(PlanCase): + """blocked_by: root causes, nearest first, at most five.""" + + def test_a_cause_two_inputs_away_and_no_blocked_ancestor_in_between(self): + self.mark('steps/solver', 'no', 'The solver source was lost.') + made = self.make('recipes/stepper-k1') + self.assertFalse(made['buildable']) + step = _step(made, 'recipes/stepper-k1') + self.assertEqual(step['action'], 'blocked') + # datasets/waves is blocked too, but its own label is not the cause; neither is a step. + self.assertEqual(step['blocked_by'], [{'reference': 'steps/solver', 'rebuild': 'no', + 'reason': 'The solver source was lost.'}]) + self.assertEqual(_references(made), ['recipes/stepper-k1']) + + def test_nearest_first_then_by_reference(self): + self.mark('recipes/stepper-k2', 'needs-work') + self.mark('steps/solver', 'no') + self.mark('recipes/stepper-k1', 'needs-work') + self.mark('datasets/waves', 'needs-work') + step = _step(self.make('recipes/stepper-k2'), 'recipes/stepper-k2') + self.assertEqual([(cause['reference'], cause['rebuild']) for cause in step['blocked_by']], [ + ('recipes/stepper-k2', 'needs-work'), # itself, no edge away + ('datasets/waves', 'needs-work'), # one input away; before recipes/ by reference + ('recipes/stepper-k1', 'needs-work'), # one input away + ('steps/solver', 'no'), # two inputs away by the shortest way + ]) + + def test_at_most_five_with_a_count_of_the_rest(self): + definitions = {'recipes/many': {'kind': 'recipe', 'title': 'Many', 'run': { + 'command': ['true'], 'inputs': {f'in_{index}': f'datasets/d{index}' for index in range(7)}}}} + for index in range(7): + definitions[f'datasets/d{index}'] = {'kind': 'dataset', 'title': f'D{index}', + 'earlier_work': {'rebuild': 'no', 'reason': f'Lost {index}.'}} + step = _step(plan.make_plan(definitions, ['recipes/many']), 'recipes/many') + self.assertEqual([cause['reference'] for cause in step['blocked_by']], + [f'datasets/d{index}' for index in range(5)]) + self.assertEqual(step['blocked_by_more'], 2) + + def test_other_edges_carry_no_cause(self): + self.documents['models/stepper']['earlier_work'] = {'rebuild': 'no', 'reason': 'Lost.'} + made = self.make('recipes/stepper-k1') + self.assertTrue(made['buildable']) + self.assertEqual(_step(made, 'recipes/stepper-k1')['action'], 'build') + + +class Subjects(PlanCase): + """A benchmark runs the subjects it can and is never blocked by one.""" + + def test_a_blocked_recipe_is_skipped_and_a_subject_without_a_recipe_runs(self): + self.documents['benchmarks/rollout']['subjects'].append({'name': 'baseline', 'title': 'Baseline'}) + made = self.make('benchmarks/rollout') + step = _step(made, 'benchmarks/rollout') + self.assertEqual(step['action'], 'build') + self.assertEqual(step['subjects'], { + 'run': ['stepper-k1', 'stepper-k2', 'baseline'], + 'skipped': [{'name': 'early-fit', 'recipe': 'recipes/early-fit', + 'reason': 'its recipe recipes/early-fit is blocked'}]}) + self.assertEqual((step['blocked_by'], step['blocked_by_more']), ([], 0)) + self.assertTrue(made['buildable']) + + def test_one_runnable_subject_is_enough(self): + self.mark('recipes/stepper-k2', 'no') + step = _step(self.make('benchmarks/rollout'), 'benchmarks/rollout') + self.assertEqual((step['action'], step['subjects']['run']), ('build', ['stepper-k1'])) + + def test_no_subject_to_run(self): + self.mark('recipes/stepper-k1', 'no') # blocks stepper-k2 through its input as well + made = self.make('benchmarks/rollout') + step = _step(made, 'benchmarks/rollout') + self.assertEqual(_references(made), ['benchmarks/rollout']) # nothing is followed out of it + self.assertEqual(step['state'], 'not-built') + self.assertEqual(step['action'], 'blocked') + self.assertEqual(step['subjects']['run'], []) + self.assertEqual(step['blocked_by'], []) + self.assertFalse(made['buildable']) + + +class Totals(PlanCase): + """Section 4: build steps only, with how many declare no figure.""" + + def test_fixture_figures(self): + made = self.make('benchmarks/rollout') + self.assertEqual((made['disk_gb'], made['disk_unknown']), (0.1, 4)) + self.assertEqual((made['wall_hours'], made['wall_unknown']), (0.6, 3)) # solver 0.1 + stepper-k1 0.5 + self.assertEqual(made['gpu_steps'], 0) + + def test_every_figure_declared_and_blocked_steps_not_counted(self): + for index, reference in enumerate(('steps/solver', 'datasets/waves', 'recipes/stepper-k1', + 'recipes/stepper-k2', 'benchmarks/rollout'), 1): + self.documents[reference]['run']['resources'] = {'gpu': index % 2 == 0, 'disk_gb': index, + 'wall_hours': index / 4} + self.mark('recipes/stepper-k2', 'needs-work') + made = self.make('benchmarks/rollout') + self.assertEqual(made['counts']['build'], 4) + self.assertEqual((made['disk_gb'], made['disk_unknown']), (1 + 2 + 3 + 5, 0)) + self.assertEqual((made['wall_hours'], made['wall_unknown']), (2.75, 0)) + self.assertEqual(made['gpu_steps'], 1) # datasets/waves; stepper-k2 is blocked + + def test_nothing_to_build(self): + made = self.make('recipes/early-fit') + self.assertEqual((made['disk_gb'], made['disk_unknown'], made['wall_hours'], made['wall_unknown'], + made['gpu_steps']), (0, 0, 0, 0, 0)) + + +@unittest.skipUnless(DATABASE, 'TULDOK_DATABASE_URL is not set; database tests need a disposable cluster.') +class BuildPlan(unittest.TestCase): + """build_plan reads the database copy and nothing else.""" + + def setUp(self): + directory = tempfile.TemporaryDirectory() + self.addCleanup(directory.cleanup) + base = Path(directory.name) / 'minimal' + shutil.copytree(FIXTURE, base) + self.folder = base / 'project' + self.project_id = uuid.uuid4().hex + project_file = self.folder / 'tuldok.json' + document = json.loads(project_file.read_text(encoding='utf-8')) + document['id'] = self.project_id + project_file.write_text(json.dumps(document, indent=2) + '\n', encoding='utf-8') + self.addCleanup(store.drop_project, self.project_id) + self.project = store.open_project(self.folder) + self.addCleanup(self.project.close) + + def test_the_same_plan_as_from_the_files(self): + self.assertEqual(plan.build_plan(self.project, ['benchmarks/rollout']), + plan.make_plan(_fixture_documents(), ['benchmarks/rollout'])) + self.assertEqual(plan.build_plan(self.project, [], every=True)['targets'], + plan.every_target(_fixture_documents())) + + def test_unknown_references(self): + for reference, message in (('datasets/nothing', 'There is no definition datasets/nothing.'), + ('nothing', "'nothing' is not a reference such as datasets/.")): + with self.assertRaises(ProjectError) as raised: + plan.build_plan(self.project, ['steps/solver', reference]) + self.assertEqual((raised.exception.code, str(raised.exception)), ('not-found', message)) + + def test_nothing_is_run_and_no_file_is_opened(self): + def refuse(*args, **kwargs): + raise AssertionError(f'A plan must not run or open anything: {args!r}') + + expected = plan.make_plan(_fixture_documents(), [], every=True) + patches = [mock.patch.object(subprocess, 'Popen', refuse), mock.patch.object(os, 'system', refuse), + mock.patch.object(os, 'fork', refuse), mock.patch.object(os, 'posix_spawn', refuse), + mock.patch.object(os, 'posix_spawnp', refuse), mock.patch.object(os, 'execv', refuse), + mock.patch.object(os, 'execve', refuse), mock.patch.object(os, 'open', refuse), + mock.patch.object(builtins, 'open', refuse), mock.patch.object(io, 'open', refuse)] + for patcher in patches: + patcher.start() + try: + made = plan.build_plan(self.project, [], every=True) + finally: + for patcher in patches: + patcher.stop() + self.assertEqual(made, expected) + with self.assertRaises(AssertionError): # the guard works + with mock.patch.object(builtins, 'open', refuse): + open(self.folder / 'tuldok.json') + + +if __name__ == '__main__': + unittest.main() diff --git a/tuldok_project/__main__.py b/tuldok_project/__main__.py index 45ce112d..e4cf47b0 100644 --- a/tuldok_project/__main__.py +++ b/tuldok_project/__main__.py @@ -9,7 +9,8 @@ the project's lock is never held past the command. `results` and `values` read benchmark results from the database only; `import-values` checks every values file before it imports any. `chart` and `report` draw from the summary rows in -the database (charts.py) and never read a results or values file. A benchmark +the database (charts.py) and never read a results or values file. `plan` lists +what has to be built for some definitions (plan.py) and runs nothing. A benchmark or chart may be named bare (`rollout`) or as a reference (`benchmarks/rollout`). """ import argparse @@ -94,6 +95,9 @@ def add(name, parents, help_text): reporting = add('report', [opening], 'write one self-contained HTML page of the project and its charts') reporting.add_argument('--output', required=True, metavar='FILE', help='the HTML file to write') reporting.add_argument('--theme', choices=THEMES, default='light', help='colours of the page (default light)') + planning = add('plan', [reading], 'list what has to be built, in order, to have these definitions; runs nothing') + planning.add_argument('targets', nargs='*', metavar='TARGET', help='references, for example recipes/pilot-dense-k1') + planning.add_argument('--all', action='store_true', help='plan every dataset, recipe, step and benchmark') add('forget', [database], "drop this project's copy from the database; the folder is not touched") return parser @@ -432,9 +436,148 @@ def _report(project, arguments): return 0 +def _figure(value, unit): + return '?' if value is None else f'{value:.3g}{unit}' + + +def _gpu(step): + if step['action'] == 'set-up': + return '-' + return 'yes' if step['resources']['gpu'] is True else '-' # an absent gpu means none is needed + + +def _step_figures(step): + if step['action'] == 'set-up': + return '-', '-', '-' + return _gpu(step), _figure(step['resources']['disk_gb'], ' GB'), _figure(step['resources']['wall_hours'], ' h') + + +def _wrapped(text, indent, width=78): + import textwrap + + return textwrap.wrap(text, width=width, initial_indent=indent, subsequent_indent=indent, + break_long_words=False, break_on_hyphens=False) or [indent] + + +def _step_details(step): + """The short lines under a step: what it uses, where it runs, its subjects, what blocks it.""" + details = [] + for name, given in step['inputs'].items(): + output = f' ({given["output"]})' if given['output'] else '' + details.append(f'{name}: {given["reference"]}{output}') + if step['environment']: + details.append(f'in {step["environment"]}') + subjects = step.get('subjects') + if subjects is not None: + details.append(f'runs {_plural(len(subjects["run"]), "subject")}') + skipped = [subject['name'] for subject in subjects['skipped']] + if skipped: + shown = ', '.join(skipped[:3]) + (f' and {len(skipped) - 3} more' if len(skipped) > 3 else '') + details.append(f'skips {len(skipped)} whose recipe is blocked: {shown}') + if step['action'] == 'blocked': + own = [cause for cause in step['blocked_by'] if cause['reference'] == step['reference']] + others = [cause['reference'] for cause in step['blocked_by'] if cause['reference'] != step['reference']] + if own: + details.append(f'blocked: its own label is rebuild {own[0]["rebuild"]}') + if others: + more = step['blocked_by_more'] + details.append(('also blocked by ' if own else 'blocked by ') + ', '.join(others) + (f' and {more} more' if more else '')) + elif not own and not step['blocked_by']: + details.append('blocked: no subject would run') + return details + + +def _cause_lines(step): + """Why a blocked target cannot be built, causes spelled out with their reasons.""" + lines = [f'{step["reference"]} cannot be built:'] + if not step['blocked_by']: + subjects = step.get('subjects') or {'skipped': []} + lines += _wrapped('No subject would run: ' + ( + f'each subject\'s recipe is blocked ({_plural(len(subjects["skipped"]), "subject")}).' + if subjects['skipped'] else 'the benchmark has no subjects.'), ' ') + return lines + for cause in step['blocked_by']: + lines.append(f' {cause["rebuild"]} {cause["reference"]}') + lines += _wrapped(cause['reason'] or 'No reason given.', ' ') + if step['blocked_by_more']: + lines.append(f' and {step["blocked_by_more"]} more.') + return lines + + +def _opening(plan): + """One sentence: the step counts first, so a long reference cannot push them away, then the verdict.""" + counts, targets = plan['counts'], plan['targets'] + if not plan['steps']: + return f'Nothing to build for {targets[0] if len(targets) == 1 else _plural(len(targets), "target")}.' + numbers = (f'{_plural(counts["build"], "step")} to build, {counts["set-up"]} to set up, ' + f'{counts["blocked"]} blocked') + every = ' (every dataset, recipe, step and benchmark)' if plan['every'] else '' + blocked = len(plan['blocked_targets']) + if len(targets) == 1 and not every: + return f'{numbers}: {targets[0]} ' + ('can be built.' if plan['buildable'] else 'cannot be built.') + if plan['buildable']: + return f'{numbers}: all {len(targets)} targets{every} can be built.' + return f'{numbers}: {blocked} of {len(targets)} targets{every} cannot be built.' + + +def _totals(plan): + build = plan['counts']['build'] + if not build: + return ['Nothing would be built, so there are no totals.'] + + def declared(total, unknown, unit): + if unknown == build: + return 'no step declares it.' + none = ('every step declares it' if not unknown else + f'{unknown} of {build} declare' + ('s' if unknown == 1 else '') + ' none') + return f'{total:.3g}{unit} declared; {none}.' + + return [f'To build: {_plural(build, "step")}, {plan["gpu_steps"]} on a GPU.', + 'Disk: ' + declared(plan['disk_gb'], plan['disk_unknown'], ' GB'), + 'Time: ' + declared(plan['wall_hours'], plan['wall_unknown'], ' h'), + 'Figures are as the definitions declare them; no command was run.'] + + +def _plan_lines(plan): + """The text form of a plan, for a person deciding whether to start the build.""" + lines = _wrapped(_opening(plan), '') + for note in plan['notes']: + lines += _wrapped(note, '') + if plan['steps']: + lines.append('') + rows = [('#', 'action', 'gpu', 'disk', 'time', 'reference')] + rows += [(step['number'], step['action'], *_step_figures(step), step['reference']) for step in plan['steps']] + widths = [max(len(str(row[index])) for row in rows) for index in range(5)] + indent = ' ' * (sum(widths) + 2 * 5 + 2) + for row, step in zip(rows, [None, *plan['steps']]): + lines.append(' '.join(str(cell).ljust(widths[index]) for index, cell in enumerate(row[:5])) + + ' ' + str(row[5])) + if step is not None: + lines += [indent + detail for detail in _step_details(step)] + blocked = {step['reference']: step for step in plan['steps'] if step['action'] == 'blocked'} + for reference in plan['blocked_targets']: + lines.append('') + lines += _cause_lines(blocked[reference]) + lines.append('') + lines += _totals(plan) + return lines + + +def _plan(project, arguments): + from . import plan + + made = plan.build_plan(project, arguments.targets, every=arguments.all) + if arguments.json: + _json(made) + else: + for line in _plan_lines(made): + print(line.rstrip()) + return 0 + + _STORE_COMMANDS = {'open': _open, 'list': _list, 'show': _show, 'graph': _graph, 'status': _status, 'set': _set, 'remove': _remove, 'save': _save, 'results': _results, 'values': _values, - 'import-values': _import_values, 'chart': _chart, 'report': _report} + 'import-values': _import_values, 'chart': _chart, 'report': _report, 'plan': _plan} def _project_id(folder): @@ -510,6 +653,8 @@ def _run_store(arguments, dsn): arguments.benchmark = _bare(arguments.benchmark, 'benchmarks') if arguments.command == 'chart': arguments.chart = _bare(arguments.chart, 'charts') + if arguments.command == 'plan' and not arguments.targets and not arguments.all: + raise UsageError('Name at least one definition to plan, or pass --all.') started = time.monotonic() project = store.open_project(arguments.folder, rebind=arguments.rebind, on_conflict=arguments.on_conflict, dsn=dsn) diff --git a/tuldok_project/plan.py b/tuldok_project/plan.py new file mode 100644 index 00000000..e3f80cbe --- /dev/null +++ b/tuldok_project/plan.py @@ -0,0 +1,236 @@ +"""The rebuild plan: what has to be built, in what order, to have some definitions, and what stands in the way. + +Owns docs/plans/definition-first-projects/spec-m4.md. make_plan is a pure +function of the decoded definitions (reference -> document): it follows the +input, environment and subject edges from the targets, but never out of a +blocked step or into a blocked subject recipe, puts what it reaches in +graph.order, gives each step an action from graph.states, explains each blocked +step by its root causes, found over the whole graph (definitions whose own earlier_work.rebuild is no or +needs-work), and adds up the figures the build steps declare in +run.resources. build_plan reads the definitions from a Project's database copy +and calls it. Making a plan runs nothing and opens no file: no command, no +estimate command, nothing on disk; an estimate is always null here. +""" +from collections import deque +import math + +from . import documents, graph +from .store import ProjectError + +BUILT_KINDS = ('dataset', 'recipe', 'step', 'benchmark') +ACTIONS = ('build', 'set-up', 'blocked') +RESOURCES = ('gpu', 'cpu_threads', 'memory_gb', 'wall_hours', 'disk_gb') +CAUSE_LIMIT = 5 +_CAUSE_LABELS = ('no', 'needs-work') + + +def _kind(reference): + return documents.KINDS[documents.parse_reference(reference)[0]] + + +def _run(document): + run = document.get('run') + return run if isinstance(run, dict) else {} + + +def _own_label(document): + earlier = document.get('earlier_work') + return earlier if isinstance(earlier, dict) and earlier.get('rebuild') in _CAUSE_LABELS else None + + +def every_target(definitions): + """Every dataset, recipe, step and benchmark, sorted by reference.""" + return sorted(reference for reference in definitions if _kind(reference) in BUILT_KINDS) + + +def _input_targets(edges_from, reference): + return sorted({edge.to_ref for edge in edges_from.get(reference, ()) if edge.role.startswith('input:')}) + + +def _held(state): + """True for a state that blocks a definition by itself (graph.states carries it up through inputs).""" + return state in ('cannot-rebuild', 'needs-work') + + +def _closure(definitions, edges_from, states, starts): + """Every definition reached from starts, starts included (section 2 of spec-m4.md). + + Input and environment edges are followed; a subject edge only when its + recipe is not blocked. Nothing is followed out of a blocked definition, nor + out of a benchmark with no subject to run. + """ + seen, pending = set(), list(starts) + while pending: + reference = pending.pop() + if reference in seen or reference not in definitions: + continue + seen.add(reference) + if _held(states[reference]): + continue + if _kind(reference) == 'benchmark' and not _subjects(definitions[reference], states)['run']: + continue + for edge in edges_from.get(reference, ()): + if edge.role == 'environment' or edge.role.startswith('input:'): + pending.append(edge.to_ref) + elif edge.role.startswith('subject:') and not _held(states.get(edge.to_ref)): + pending.append(edge.to_ref) + return seen + + +def causes(definitions, edges_from, reference): + """The root causes of a blocked definition, nearest first (fewest input edges away, then by reference). + + A cause is the definition itself, or anything it reaches through input + edges, whose own earlier_work.rebuild is no or needs-work. Each is + {reference, rebuild, reason}. + """ + distance = {reference: 0} + queue = deque([reference]) + while queue: + current = queue.popleft() + for target in _input_targets(edges_from, current): + if target in definitions and target not in distance: + distance[target] = distance[current] + 1 + queue.append(target) + found = [] + for item in sorted(distance, key=lambda name: (distance[name], name)): + label = _own_label(definitions[item]) + if label is not None: + found.append({'reference': item, 'rebuild': label['rebuild'], 'reason': label.get('reason')}) + return found + + +def _inputs(document): + """{name: {reference, output}} for the run's inputs, in document order.""" + inputs = _run(document).get('inputs') + if not isinstance(inputs, dict): + return {} + found = {} + for name, value in inputs.items(): + if isinstance(value, str): + found[name] = {'reference': value, 'output': None} + elif isinstance(value, dict): + found[name] = {'reference': value.get('from'), 'output': value.get('output')} + return found + + +def _resources(document): + declared = _run(document).get('resources') + declared = declared if isinstance(declared, dict) else {} + return {name: declared.get(name) for name in RESOURCES} + + +def _subjects(document, states): + """{run, skipped} for a benchmark: a subject is skipped when its recipe is blocked.""" + run, skipped = [], [] + subjects = document.get('subjects') + for subject in subjects if isinstance(subjects, list) else (): + if not isinstance(subject, dict) or not isinstance(subject.get('name'), str): + continue + recipe = subject.get('recipe') + if isinstance(recipe, str) and _held(states.get(recipe)): + skipped.append({'name': subject['name'], 'recipe': recipe, + 'reason': f'its recipe {recipe} is blocked'}) + else: + run.append(subject['name']) + return {'run': run, 'skipped': skipped} + + +def _action(kind, state): + if kind == 'environment': + return 'set-up' if state == 'not-set-up' else None + if state == 'not-built': + return 'build' + if state in ('cannot-rebuild', 'needs-work'): + return 'blocked' + return None + + +def _total(steps, field): + """(sum of the declared figure over build steps, how many build steps declare none).""" + declared = [step['resources'][field] for step in steps if step['action'] == 'build'] + numbers = [value for value in declared if isinstance(value, (int, float)) and not isinstance(value, bool)] + return round(math.fsum(numbers), 6), len(declared) - len(numbers) + + +def make_plan(definitions, targets, *, every=False): + """The plan for targets over {reference: document}, as section 3 and 4 of spec-m4.md describe it. + + every adds every dataset, recipe, step and benchmark to the targets. A + chart target is replaced by its benchmark; a model target adds nothing + and a note saying so. Raises ValueError naming any target that is not a + definition. + """ + asked = list(targets) + (every_target(definitions) if every else []) + unknown = [reference for reference in asked if reference not in definitions] + if unknown: + raise ValueError('There is no definition ' + ', '.join(unknown) + '.') + edges_from = {} + for edge in graph.edges(definitions): + edges_from.setdefault(edge.from_ref, []).append(edge) + resolved, notes = [], [] + for reference in asked: + kind = _kind(reference) + if kind == 'chart': + benchmark = definitions[reference].get('benchmark') + notes.append(f'{reference} is drawn from {benchmark}, which is planned in its place.') + reference = benchmark + elif kind == 'model': + notes.append(f'{reference} is a model; a model is not built, only the recipes that train it.') + if reference not in resolved: + resolved.append(reference) + states = graph.states(definitions) + members = _closure(definitions, edges_from, states, + [reference for reference in resolved if _kind(reference) != 'model']) + members = {reference for reference in members if _kind(reference) not in ('model', 'chart')} + ordered = graph.order({reference: definitions[reference] for reference in members}) + actions = {reference: _action(_kind(reference), states[reference]) for reference in ordered} + + steps = [] + for number, reference in enumerate(ordered, 1): + document, kind = definitions[reference], _kind(reference) + run = _run(document) + action = actions[reference] + step = {'number': number, 'reference': reference, 'kind': kind, 'title': document.get('title'), + 'state': states[reference], 'action': action, + 'command': run.get('command'), 'environment': run.get('environment'), + 'inputs': _inputs(document), 'resources': _resources(document), 'estimate': None, + 'blocked_by': [], 'blocked_by_more': 0} + if kind == 'benchmark': + step['subjects'] = _subjects(document, states) + if action == 'build' and not step['subjects']['run']: + # Nothing would run: blocked, though by no cause of its own. + step['action'] = action = actions[reference] = 'blocked' + if action == 'blocked': + found = causes(definitions, edges_from, reference) + step['blocked_by'] = found[:CAUSE_LIMIT] + step['blocked_by_more'] = max(0, len(found) - CAUSE_LIMIT) + steps.append(step) + + blocked = {step['reference'] for step in steps if step['action'] == 'blocked'} + disk_gb, disk_unknown = _total(steps, 'disk_gb') + wall_hours, wall_unknown = _total(steps, 'wall_hours') + return {'targets': resolved, 'every': every, + 'buildable': not any(reference in blocked for reference in resolved), + 'blocked_targets': [reference for reference in resolved if reference in blocked], + 'counts': {action: sum(step['action'] == action for step in steps) for action in ACTIONS}, + 'gpu_steps': sum(step['action'] == 'build' and step['resources']['gpu'] is True for step in steps), + 'disk_gb': disk_gb, 'disk_unknown': disk_unknown, + 'wall_hours': wall_hours, 'wall_unknown': wall_unknown, + 'notes': notes, 'steps': steps} + + +def build_plan(project, targets, *, every=False): + """The plan for targets in an open Project, from its database copy alone. + + Raises ProjectError (code not-found) naming the first target that is not a + definition of the project. Holds no state; runs and opens nothing. + """ + definitions = project._documents(removed=False) + for reference in targets: + if documents.parse_reference(reference) is None: + raise ProjectError(f'{reference!r} is not a reference such as datasets/.', 'not-found', + references=[reference]) + if reference not in definitions: + raise ProjectError(f'There is no definition {reference}.', 'not-found', references=[reference]) + return make_plan(definitions, targets, every=every) From 1a7884947b7ea5119955657f36e3030b4b4d6f5c Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 12 Nov 2026 00:16:14 -0700 Subject: [PATCH 016/131] docs(plan): milestone 5 spec for environments Co-Authored-By: Claude Fable 5.2 --- .../definition-first-projects/spec-m5.md | 81 +++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 docs/plans/definition-first-projects/spec-m5.md diff --git a/docs/plans/definition-first-projects/spec-m5.md b/docs/plans/definition-first-projects/spec-m5.md new file mode 100644 index 00000000..fe88ec5c --- /dev/null +++ b/docs/plans/definition-first-projects/spec-m5.md @@ -0,0 +1,81 @@ +# Implementation spec: milestone 5, environments + +This continues the earlier specs in this folder. Section 1 of [spec-m1-m2.md](spec-m1-m2.md) (rules for implementers) applies unchanged. The milestone changes no existing Tuldok file outside `tuldok_project/`. + +**Owner decision, 2026-11-12:** code and tests only for now, plus connecting the two environments that already exist on the owner's machine. No package is downloaded or installed in this milestone's acceptance; the install path is exercised with a stand-in installer in tests and with `--dry-run` on the lab. + +**Done when:** on the lab project, `connect` records the lab's existing CPU and GPU interpreters for `environments/lab-cpu` and `environments/cuda-torch`, the check reports the Python and package versions it found and both are `ready`; `set-up --dry-run` prints the commands that would install `environments/lab-cpu`; and `plan` no longer lists a ready environment as something to set up. + +## 1. What is local + +Which interpreter fulfils an environment on this machine is local: it lives in the project's database schema, never in the folder. An environment that Tuldok installs is a directory under the project's local home: + +- **Local home:** `$TULDOK_PROJECT_HOME//`, where `TULDOK_PROJECT_HOME` defaults to `~/.local/share/tuldok/projects`. It is created when first needed. Installed environments go to `/environments//`. Later milestones put products beside it. + +```sql +CREATE TABLE environments ( + name text PRIMARY KEY, -- environments/ + interpreter text NOT NULL, -- absolute path of the Python executable + origin text NOT NULL CHECK (origin IN ('connected', 'installed')), + recorded_at timestamptz NOT NULL, + checked_at timestamptz, + ok boolean, -- result of the last check; NULL before the first + found jsonb, -- what the last check saw + problems jsonb); -- list of sentences from the last check +``` + +## 2. States + +An environment's state comes from that table: `not-set-up` when it has no row, `ready` when its last check passed, `failing` when its last check did not. `graph.states(definitions, local=None)` takes an optional mapping from reference to state that overrides what it computes for environments; `Project` passes the table's states everywhere it reports a state. No other definition's state depends on an environment. + +## 3. The check + +`environments.check(project, reference)` runs the recorded interpreter once, as a child process, and compares what it reports with the definition. + +- **How it runs:** `[interpreter, '-I', '-c', PROBE, ]`, with a minimal environment (`PATH=/usr/bin:/bin`, `LANG=C.UTF-8`, `HOME` set to a fresh temporary directory), that temporary directory as the working directory, and a time limit of 180 seconds. No project code is involved. +- **What the probe reports**, as one JSON object on stdout: the Python version; for each package named in the definition, its installed version from `importlib.metadata` or null; the interpreter's own path. Packages are not imported, with one exception: when the definition's device is `cuda` and `torch` is among its packages, the probe imports `torch` and reports whether CUDA is available, the CUDA version, the first device's name, and the driver line from `/proc/driver/nvidia/version` when it exists. +- **What must hold:** the Python version's `major.minor` equals the definition's `python`; every package's installed version equals the definition's exactly; for device `cuda`, CUDA is available. A device of `cuda` with no `torch` among the packages is a problem that says the check cannot see the GPU. +- **Result:** `ok`, `found` and `problems` are stored with the time. A probe that fails to start, times out, exits with an error or prints something that is not the expected object is a failed check with one problem saying which, and the first 400 characters of its error output. + +The check is an explicit action. Opening a project never runs it. + +## 4. Connect, set up, disconnect + +- **`environments.connect(project, reference, interpreter)`** records an existing interpreter (an absolute path to an executable regular file, after resolving nothing: the path is stored as given) with origin `connected`, then checks it. The record is kept whether or not the check passes, so the problems can be read. +- **`environments.set_up(project, reference, *, dry_run=False, replace=False)`** installs the environment the definition describes and then checks it. + - It needs the definition's `install.requirements`; without it the refusal says to connect an existing interpreter instead. + - The installer is `uv`: the program named by `TULDOK_UV`, else `uv` on `PATH`. If there is none the refusal says so. + - Commands, run in order with the code root as the working directory: + 1. `uv venv --python ` + 2. `uv pip install --python /bin/python -r /` followed by `--extra-index-url ` for each of `install.index_urls` + - `` is `/environments/`. An existing non-empty target is refused unless `replace` is true, in which case it is removed first. + - Output of both commands goes to `.log`. Each command has a time limit of one hour. A failed command leaves the log, removes the half-made target, records nothing and raises with the last lines of the log. + - On success the interpreter `/bin/python` is recorded with origin `installed` and checked. + - `dry_run` returns the commands, the target and the log path and does nothing else: no directory is made, no program is run. +- **`environments.disconnect(project, reference)`** removes the record. It never deletes an installed directory; it returns that directory's path when the origin was `installed`. + +## 5. Plan + +A `ready` environment in a plan has action `ready` and is not counted as something to set up. A `failing` environment has action `set-up`, and the text says its last check failed. + +## 6. Command line + +| Command | Does | +| --- | --- | +| `environments FOLDER` | one row per environment: reference, state, origin, interpreter, when it was last checked, and under it the versions found and any problems | +| `connect FOLDER ENVIRONMENT INTERPRETER` | section 4; exit status 1 when the check fails | +| `check-environment FOLDER [ENVIRONMENT...]` | runs the check again, for all recorded environments when none is named; exit status 1 when any fails | +| `set-up FOLDER ENVIRONMENT [--dry-run] [--replace]` | section 4; with `--dry-run` prints the commands, the target and the log path | +| `disconnect FOLDER ENVIRONMENT` | section 4 | + +`--json` applies to `environments`, `connect`, `check-environment` and `set-up`. An environment may be named bare (`lab-cpu`) or as a reference. + +## 7. Not in this milestone + +Running a definition's `estimate` command. It is project code and belongs with the launcher in milestone 6, where a command runs from a clean copy of a commit. + +## 8. Slice + +| Slice | Files | +| --- | --- | +| T10 environments | `tuldok_project/environments.py` (new), `tuldok_project/local.py` (new: the local home), hooks in `store.py` (the table, states passed through), `graph.states` (the `local` argument), `plan.py` (section 5), the commands in `__main__.py`, `tests/test_tuldok_project_environments.py`, and an "Environments" section in `docs/contracts/project-folder.md` | From f6f06458393a8b5d71cc6b6703485c62a18c3dba Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 12 Nov 2026 00:36:54 -0700 Subject: [PATCH 017/131] feat(project): connect, check and set up environments An environment definition can be fulfilled on this machine by connecting an existing interpreter or by installing one with uv from the definition's requirements. The check runs the interpreter once, reads the Python and package versions without importing them (torch is imported for a cuda environment to confirm the GPU is usable), and stores the result, so an environment is not set up, ready or failing. Plans show a ready environment as ready, not as work to do. Command line: environments, connect, check-environment, set-up (with --dry-run and --replace) and disconnect. Co-Authored-By: Claude Fable 5.2 --- docs/contracts/project-folder.md | 224 +++++- .../execution-ledger.md | 40 ++ tests/test_tuldok_project_cli.py | 2 +- tests/test_tuldok_project_environments.py | 654 ++++++++++++++++++ tests/test_tuldok_project_plan.py | 6 +- tuldok_project/__main__.py | 179 ++++- tuldok_project/environments.py | 473 +++++++++++++ tuldok_project/graph.py | 15 +- tuldok_project/local.py | 41 ++ tuldok_project/plan.py | 19 +- tuldok_project/store.py | 37 +- 11 files changed, 1655 insertions(+), 35 deletions(-) create mode 100644 tests/test_tuldok_project_environments.py create mode 100644 tuldok_project/environments.py create mode 100644 tuldok_project/local.py diff --git a/docs/contracts/project-folder.md b/docs/contracts/project-folder.md index 75c0ee4f..afba5076 100644 --- a/docs/contracts/project-folder.md +++ b/docs/contracts/project-folder.md @@ -580,7 +580,7 @@ A state is worked out from the definitions, never stored in a file: | `cannot-rebuild` | its `earlier_work.rebuild` is `no`, or something it uses through an input, directly or further up, is `cannot-rebuild` | | `needs-work` | not `cannot-rebuild`, and its `earlier_work.rebuild` is `needs-work` or something it uses through an input is `needs-work` | | `not-built` | any other dataset, recipe, benchmark or step | -| `not-set-up` | an environment | +| `not-set-up`, `ready`, `failing` | an environment, by what this machine records for it (see [Environments](#environments)) | | `none` | a model or a chart | Options: @@ -588,7 +588,7 @@ Options: | Option | Commands | Meaning | | --- | --- | --- | | `--database-url URL` | all but `check` | The Postgres database. Without it, the `TULDOK_DATABASE_URL` environment variable is used; with neither, the command stops with exit status 2. | -| `--json` | `open`, `list`, `show`, `graph`, `status`, `save`, `results`, `values`, `import-values`, `chart`, `plan` | Print one JSON document with the same content as the text. | +| `--json` | `open`, `list`, `show`, `graph`, `status`, `save`, `results`, `values`, `import-values`, `chart`, `plan`, `environments`, `connect`, `check-environment`, `set-up` | Print one JSON document with the same content as the text. | | `--rebind` | all that open | The copy is bound to the folder it was first opened from. Opening the same project from another path is refused unless `--rebind` is given, which binds the copy to the new path. | | `--keep` | all that open | Where a file changed on disk and the same definition has unsaved edits, keep the edits; the changed file becomes the version that `save` replaces. | | `--discard` | all that open | Where a file changed on disk and the same definition has unsaved edits, drop the edits and take the file. | @@ -874,7 +874,8 @@ reference), numbered from 1. Each step has one action: | Action | For | | --- | --- | -| `set-up` | an environment (state `not-set-up`) | +| `set-up` | an environment in state `not-set-up`, or `failing` (the text says its last check failed) | +| `ready` | an environment in state `ready`; it is not counted as something to set up | | `build` | a dataset, recipe, step or benchmark in state `not-built` | | `blocked` | a definition in state `cannot-rebuild` or `needs-work`, and a benchmark with no subject to run | @@ -905,7 +906,8 @@ The totals count `build` steps only: ### Text output The text is one opening sentence (how many steps there are to build, to set up -and blocked, and whether the targets can be built), then one line per step with +and blocked, how many environments are ready when any is, and whether the +targets can be built), then one line per step with its number, action, GPU (`yes` for `gpu: true`, otherwise `-`: a step that does not declare `gpu` needs none), disk and time as declared (`?` when not declared) and its reference. Under a step are what it uses (each input by name, @@ -961,7 +963,7 @@ With `--json`, `plan` prints one object: | `every` | true with `--all` | | `buildable` | true when no target is blocked | | `blocked_targets` | the targets that are blocked | -| `counts` | the number of steps of each action: `{"build", "set-up", "blocked"}` | +| `counts` | the number of steps of each action: `{"build", "set-up", "blocked", "ready"}` | | `gpu_steps` | how many build steps declare `gpu: true` | | `disk_gb`, `disk_unknown` | the sum of the declared `disk_gb` over build steps, and how many build steps declare none | | `wall_hours`, `wall_unknown` | the same for `wall_hours` | @@ -974,7 +976,7 @@ Each step: | --- | --- | | `number` | its place in the order, from 1 | | `reference`, `kind`, `title`, `state` | from the definition; the state as `list` shows it | -| `action` | `build`, `set-up` or `blocked` | +| `action` | `build`, `set-up`, `blocked` or `ready` | | `command`, `environment` | from `run`, placeholders not filled in; null when absent | | `inputs` | each input name to `{"reference", "output"}`; `output` is null for a whole product | | `resources` | `gpu`, `cpu_threads`, `memory_gb`, `wall_hours`, `disk_gb` as declared; null when not declared (a null `gpu` means no GPU is needed) | @@ -983,12 +985,216 @@ Each step: | `blocked_by_more` | how many more causes there are | | `subjects` | benchmarks only: `run`, the subject names that would run, and `skipped`, each `{"name", "recipe", "reason"}` | +## Environments + +An `environment` definition says what an interpreter must be: a Python +version, a device and exact package versions. Which interpreter fulfils it is +a fact about one machine, so it is never written to the folder. Tuldok records +it in the project's database schema, in the table `environments`, one row per +environment that has an interpreter on this machine: + +| Column | Content | +| --- | --- | +| `name` | the environment's name, as in `environments/` | +| `interpreter` | the absolute path of the Python executable, exactly as it was given | +| `origin` | `connected` (an existing interpreter was named) or `installed` (Tuldok installed it) | +| `recorded_at` | when the interpreter was recorded | +| `checked_at` | when it was last checked; null before the first check | +| `ok` | whether the last check passed | +| `found` | what the last check saw: the Python version, each package's installed version (null when not installed), the interpreter's own path, and for a `cuda` check what torch says about CUDA | +| `problems` | the sentences saying why the last check failed; empty when it passed | + +Removing an environment definition, or deleting its file, drops its row. The +row never deletes an installed directory. + +Environments that Tuldok installs live in the project's local home, +`$TULDOK_PROJECT_HOME//`, where `TULDOK_PROJECT_HOME` defaults to +`~/.local/share/tuldok/projects`. An installed environment is the directory +`/environments//`, with its log beside it as +`/environments/.log`. The local home is made the first time +something is installed. + +### States + +| State | When | +| --- | --- | +| `not-set-up` | no interpreter is recorded for the environment on this machine | +| `ready` | its last check passed | +| `failing` | its last check did not pass | + +The state comes from the stored result of the last check. Opening a project +never runs a check, so `list`, `show`, `graph` and `plan` show what the last +check found, however long ago it ran; `check-environment` runs it again. No +other definition's state depends on an environment's. A change to an +environment definition does not change the stored result until the next check. + +### The check + +The check runs the recorded interpreter once, as a child process: + +``` +INTERPRETER -I -c PROBE '{"device": ..., "packages": {...}}' +``` + +The child gets an environment of `PATH=/usr/bin:/bin`, `LANG=C.UTF-8` and +`HOME` set to a new empty temporary directory, which is also its working +directory and is removed afterwards. It has 180 seconds. Its output is +captured and never shown as it is. No project code is involved. + +The probe reads each package's installed version with `importlib.metadata` +and imports no package, with one exception: when the device is `cuda` and +`torch` is among the packages, it imports `torch` and reports whether CUDA is +available, the CUDA version, the first device's name and the first line of +`/proc/driver/nvidia/version` when that file exists. It works on Python 3.10 +to 3.14 and prints one JSON object. + +The check passes when all of these hold: + +| Rule | A failure reads | +| --- | --- | +| the Python version's major.minor is the definition's `python` | `Python is 3.11.9; the definition asks for 3.12.` | +| every package is installed | `numpy is not installed; the definition asks for 2.3.5.` | +| every package's version is exactly the definition's | `jsonschema is 4.26.0; the definition asks for 4.25.0.` | +| for device `cuda`, `torch` is among the packages | `The device is cuda but torch is not among the packages, so the check cannot see the GPU.` | +| for device `cuda`, torch reports CUDA as available | `CUDA is not available to torch.` | + +A probe that cannot be started, takes longer than 180 seconds, exits with an +error, or prints anything other than the expected object is a failed check +with one problem saying which, followed by the first 400 characters of its +error output. A failed check is recorded like any other result. + +### Connect + +`connect` records an existing interpreter, with origin `connected`, and then +checks it. The interpreter is named by an absolute path to an executable +file. A symbolic link is allowed, and the path is stored as given, not +resolved, so a virtual environment's `bin/python` stays that environment's. +The record is kept whether or not the check passes, so its problems can be +read with `environments`. + +### Set-up + +`set-up` installs the environment its definition describes, then records it +with origin `installed` and checks it. It needs the definition's +`install.requirements`; without it, the refusal says to connect an existing +interpreter instead. The installer is `uv`: the program named by the +`TULDOK_UV` environment variable, otherwise `uv` on `PATH`; with neither, it is +refused. + +These two commands run in order, with the code root as the working directory +and up to one hour each: + +``` +uv venv --python PYTHON TARGET +uv pip install --python TARGET/bin/python -r CODE_ROOT/REQUIREMENTS [--extra-index-url URL]... +``` + +`TARGET` is `/environments/`, `PYTHON` the definition's +`python`, `REQUIREMENTS` its `install.requirements`, and there is one +`--extra-index-url` for each of its `install.index_urls`. The output of both +goes to `TARGET.log`, which is replaced each time. + +| Option | Meaning | +| --- | --- | +| `--dry-run` | Prints each command on its own line as it would be run, then the target and the log path. Nothing is made and nothing is run. | +| `--replace` | A target that exists and is not empty is refused without this option; with it, the target is removed first. | + +When a command fails or runs out of time, the half-made target is removed, +the log is kept, nothing is recorded, and the refusal ends with the last lines +of the log. Any record the environment had before is left as it was; when +that record was the installed target that `--replace` removed, its next check +fails. + +### Disconnect + +`disconnect` removes the record, so the environment is `not-set-up` again. It +never deletes an installed directory; when the origin was `installed` it +prints that directory's path, to delete by hand when it is no longer needed. + +### Commands + +| Command | Does | +| --- | --- | +| `environments` | Prints one row per environment: reference, state, origin, when it was last checked and the interpreter; under it the versions the last check found (with what the definition asks for where they differ) and its problems, or how to set it up. A closing line says how many are ready. | +| `connect ENVIRONMENT INTERPRETER` | Records and checks an existing interpreter. Exit status 1 when the check fails. | +| `check-environment [ENVIRONMENT...]` | Checks the named environments again, or every recorded one when none is named. Exit status 1 when any fails, or when a named one is not set up. | +| `set-up ENVIRONMENT [--dry-run] [--replace]` | Installs, records and checks the environment, or with `--dry-run` prints what it would run. Exit status 1 when it is refused, a command fails, or the check fails. | +| `disconnect ENVIRONMENT` | Removes the record. | + +An environment may be named bare (`lab-cpu`) or as a reference +(`environments/lab-cpu`). `--json` prints one JSON document for +`environments`, `connect`, `check-environment` and `set-up`; each environment +in it has the definition's `python`, `device` and `packages`, whether it has +an install section (`installable`), its `state`, and the record's columns +(null when there is no record). + +In these examples `FOLDER` is a copy of the test project whose `lab-cpu` +asks for `jsonschema` and is connected to Tuldok's own `.venv/bin/python`. +Long paths are shortened: `VENV` is that `.venv`, `CODE` the code root, +`LOCAL` the project's local home and `UV` the `uv` found on `PATH`. + +``` +$ .venv/bin/python -m tuldok_project environments FOLDER +environment state origin last check interpreter +environments/lab-cpu not-set-up - - - + not set up on this machine; run set-up or connect an interpreter + +0 of 1 environment ready on this machine. +$ .venv/bin/python -m tuldok_project set-up FOLDER lab-cpu --dry-run +Would set up environments/lab-cpu by running, in CODE: +UV venv --python 3.12 LOCAL/environments/lab-cpu +UV pip install --python LOCAL/environments/lab-cpu/bin/python -r CODE/requirements.txt --extra-index-url https://pypi.org/simple +target LOCAL/environments/lab-cpu +log LOCAL/environments/lab-cpu.log +Nothing was run. +$ .venv/bin/python -m tuldok_project connect FOLDER lab-cpu VENV/bin/python +Recorded VENV/bin/python for environments/lab-cpu. +environments/lab-cpu is ready: the check passed. + python 3.12.3 (asks 3.12) + jsonschema 4.26.0 +$ .venv/bin/python -m tuldok_project environments FOLDER +environment state origin last check interpreter +environments/lab-cpu ready connected 2026-11-12 00:31 VENV/bin/python + python 3.12.3 (asks 3.12) + jsonschema 4.26.0 + +1 of 1 environment ready on this machine. +``` + +A path with spaces or other characters the shell would split is quoted in +`--dry-run`'s commands, so a line can be pasted into a shell as it is. When +the check fails, `connect` exits with status 1 and the plan sets the +environment up again: + +``` +$ .venv/bin/python -m tuldok_project connect FOLDER lab-cpu VENV/bin/python +Recorded VENV/bin/python for environments/lab-cpu. +environments/lab-cpu is failing: the check found 1 problem. + python 3.12.3 (asks 3.12) + jsonschema 4.26.0 (asks 4.25.0) + problem: jsonschema is 4.26.0; the definition asks for 4.25.0. +$ .venv/bin/python -m tuldok_project plan FOLDER steps/solver +1 step to build, 1 to set up, 0 blocked: steps/solver can be built. + +# action gpu disk time reference +1 set-up - - - environments/lab-cpu + its last check failed; see environments +2 build - ? 0.1 h steps/solver + in environments/lab-cpu +... +``` + +With the environment ready, the same plan begins +`1 step to build, 0 to set up, 0 blocked, 1 ready: steps/solver can be built.` +and the environment's line has the action `ready`. + ## What the format does not do yet The folder is checked, can be opened, edited and saved through the database -copy, its results can be read and drawn, and a build can be planned, nothing more. Tuldok does not yet run any command, -estimate, install an environment, compare installed package versions, write +copy, its results can be read and drawn, a build can be planned, and its +environments can be connected, checked and installed, nothing more. Tuldok +does not yet run any definition's command or `estimate` command, write settings files or read the contents of notes. The `run`, `resources`, -`estimate`, `install` and `settings` fields record what a later Tuldok will use. +`estimate` and `settings` fields record what a later Tuldok will use. Background: [the design notes for this format](../plans/definition-first-projects/). diff --git a/docs/plans/definition-first-projects/execution-ledger.md b/docs/plans/definition-first-projects/execution-ledger.md index b2863b71..1ffb87a1 100644 --- a/docs/plans/definition-first-projects/execution-ledger.md +++ b/docs/plans/definition-first-projects/execution-ledger.md @@ -153,3 +153,43 @@ Command for all Tuldok tests as before: 261 tests. **Follow-ups, none blocking:** `plan.py` reads all documents through the private `Project._documents`; a public accessor belongs with the other private-name cleanups. No lab definition declares `wall_hours`, so plans show no time. **Next:** milestone 5, environments. Its acceptance installs packages (about 1 GB for the CPU environment, several GB for the GPU one), which needs the owner's go-ahead. + +## 2026-11-12 — milestone 5, environments + +**Owner decision:** code and tests only, plus connecting the two environments that already exist on the owner's machine. Nothing downloaded or installed. Spec: [spec-m5.md](spec-m5.md). + +**Commits** (none pushed). Tuldok `feat/definition-first-projects`: spec `1a788494`, then the environments slice. + +| Slice | Files | Result | +| --- | --- | --- | +| T10 environments | `tuldok_project/environments.py`, `tuldok_project/local.py`, hooks in `store.py`, `graph.states(definitions, local)`, the `ready` action in `plan.py`, five commands, `tests/test_tuldok_project_environments.py`, the "Environments" contract section | 41 new tests; every install in tests runs a stand-in for `uv` | + +Command for all Tuldok tests as before: 302 tests, 71 s. + +**Acceptance, on the lab project** (throwaway database, local home in a scratch directory): + +| Step | Result | +| --- | --- | +| `connect lab-cpu /.venv/bin/python` | ready: Python 3.12.3, numpy 2.3.5, torch 2.8.0+cpu | +| `connect cuda-torch /torch-versions/v2.14.0/venv/bin/python` | ready: Python 3.14.7, numpy 2.5.3, torch 2.14.0+cu132, CUDA 13.2 on the RTX 5090 Laptop GPU | +| `set-up lab-cpu --dry-run` | prints `uv venv --python 3.12 ` and `uv pip install ... -r tuldok/requirements-cpu.lock --extra-index-url https://download.pytorch.org/whl/cpu`; nothing run, nothing created | +| `set-up cuda-torch --dry-run` | refused: the definition has no `install.requirements` | +| `plan recipes/pilot-dense-k1` | both environments `ready`, nothing to set up | + +**Accepted as implemented:** + +- The check reads versions with `importlib.metadata` and imports nothing, except `torch` for a `cuda` environment. +- A failed check is a stored result with problems; the record is kept so they can be read. +- Editing an environment definition does not clear its stored result; the state is as of the last check. +- An environment's record is dropped when its definition is removed. +- A dry run still refuses for a missing `install` section, a missing installer or a non-empty target. +- The installer's commands inherit the caller's environment and run in their own process group with a one-hour limit; the log is replaced on each set-up. +- New `ProjectError` codes: `not-set-up`, `no-install`, `no-installer`, `target-exists`, `install-failed`. + +**Not verified:** a real `uv venv` or `uv pip install`; the probe on Python other than 3.12 and 3.14 (it ran on both in the acceptance run); a failing GPU. + +**One deviation by the implementing agent:** it ran `connect` once against `/usr/bin/python3`, outside the repository's virtual environment, during a manual demonstration. The probe is read-only and the demonstration project was removed. + +**Open:** the lab has no lock file for the GPU environment, so `cuda-torch` can be connected but not installed. Running a definition's `estimate` command moved to milestone 6. + +**Next:** milestone 6, build: runs from a commit, the launcher and queue, products, live progress, results published by the run. Its acceptance trains one tiny model on the GPU, which needs the owner's go-ahead. diff --git a/tests/test_tuldok_project_cli.py b/tests/test_tuldok_project_cli.py index 2769935d..d367d986 100644 --- a/tests/test_tuldok_project_cli.py +++ b/tests/test_tuldok_project_cli.py @@ -400,7 +400,7 @@ def test_json_charts_models_and_all(self): 'notes', 'steps'): self.assertIn(field, made) self.assertTrue(made['buildable']) - self.assertEqual(made['counts'], {'build': 5, 'set-up': 1, 'blocked': 0}) + self.assertEqual(made['counts'], {'build': 5, 'set-up': 1, 'blocked': 0, 'ready': 0}) model = self.run_ok('plan', self.folder, 'models/stepper').splitlines() self.assertEqual(model[0], 'Nothing to build for models/stepper.') self.assertEqual(' '.join(model[1:3]), diff --git a/tests/test_tuldok_project_environments.py b/tests/test_tuldok_project_environments.py new file mode 100644 index 00000000..26b59736 --- /dev/null +++ b/tests/test_tuldok_project_environments.py @@ -0,0 +1,654 @@ +"""Environments on this machine (docs/plans/definition-first-projects/spec-m5.md): records, checks, set-up. + +The comparison is tested as a pure function with made-up probe reports, +including cuda definitions (no GPU is needed or used). The probe is run for +real only in the interpreter running these tests, and with small shell +scripts standing in for broken interpreters. Installing is tested with a +stand-in for uv written into a temporary directory and named in TULDOK_UV: +it records its arguments and, for `venv`, makes /bin/python a link +to the test interpreter (with the test venv's pyvenv.cfg and lib beside it, +so the installed environment sees the same packages). Nothing is downloaded +or installed. Every test points TULDOK_PROJECT_HOME at a temporary +directory. Database tests run only when TULDOK_DATABASE_URL names a +disposable cluster (spec-m1-m2.md, section 1); each copies +tests/fixtures/tuldok_project/minimal, gives it a fresh project id and drops +that project's schema afterwards. +""" +import ast +import json +import os +from pathlib import Path +import shlex +import shutil +import subprocess +import sys +import tempfile +import unittest +from unittest import mock +import uuid +from importlib import metadata + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) + +from tuldok_project import environments, graph, local, plan, store # noqa: E402 +from tuldok_project.store import ProjectError # noqa: E402 + +REPOSITORY = Path(__file__).resolve().parents[1] +FIXTURE = REPOSITORY / 'tests' / 'fixtures' / 'tuldok_project' / 'minimal' +DATABASE = os.environ.get('TULDOK_DATABASE_URL') +PYTHON = sys.executable +JSONSCHEMA = metadata.version('jsonschema') +MINOR = '%d.%d' % sys.version_info[:2] +VENV = sys.prefix if sys.prefix != sys.base_prefix else '' + + +def _cpu(**packages): + return {'kind': 'environment', 'title': 'CPU', 'python': '3.12', 'device': 'cpu', + 'packages': packages or {'numpy': '2.3.5'}} + + +def _report(python='3.12.3', cuda=None, **packages): + found = {'python': python, 'executable': '/env/bin/python', 'packages': packages} + if cuda is not None: + found['cuda'] = cuda + return found + + +class Compare(unittest.TestCase): + """compare(definition, report) -> (ok, problems), section 3.""" + + def test_a_matching_report_passes(self): + self.assertEqual(environments.compare(_cpu(), _report(numpy='2.3.5')), (True, [])) + + def test_python_is_compared_by_major_and_minor(self): + self.assertEqual(environments.compare(_cpu(), _report('3.12.0', numpy='2.3.5')), (True, [])) + self.assertEqual(environments.compare(_cpu(), _report('3.11.9', numpy='2.3.5')), + (False, ['Python is 3.11.9; the definition asks for 3.12.'])) + self.assertEqual(environments.compare(_cpu(), _report('3.1.2', numpy='2.3.5'))[0], False) + self.assertEqual(environments.compare({**_cpu(), 'python': '3.1'}, _report('3.12.3', numpy='2.3.5'))[0], False) + + def test_packages_must_match_exactly(self): + definition = _cpu(numpy='2.3.5', scipy='1.16.0', torch='2.5.1') + ok, problems = environments.compare(definition, _report(numpy='2.3.4', scipy=None, torch='2.5.1+cu124')) + self.assertFalse(ok) + self.assertEqual(problems, ['numpy is 2.3.4; the definition asks for 2.3.5.', + 'scipy is not installed; the definition asks for 1.16.0.', + 'torch is 2.5.1+cu124; the definition asks for 2.5.1.']) + + def test_a_package_missing_from_the_report_counts_as_not_installed(self): + self.assertEqual(environments.compare(_cpu(), _report()), + (False, ['numpy is not installed; the definition asks for 2.3.5.'])) + + def test_cuda_available(self): + definition = {**_cpu(torch='2.5.1'), 'device': 'cuda'} + cuda = {'available': True, 'version': '12.4', 'device': 'NVIDIA RTX', 'driver': 'NVRM 550', 'error': None} + self.assertEqual(environments.compare(definition, _report(torch='2.5.1', cuda=cuda)), (True, [])) + + def test_cuda_not_available(self): + definition = {**_cpu(torch='2.5.1'), 'device': 'cuda'} + cuda = {'available': False, 'version': '12.4', 'device': None, 'driver': None, 'error': None} + self.assertEqual(environments.compare(definition, _report(torch='2.5.1', cuda=cuda)), + (False, ['CUDA is not available to torch.'])) + broken = {**cuda, 'error': 'OSError: libcudart.so.12: cannot open shared object file'} + self.assertEqual(environments.compare(definition, _report(torch='2.5.1', cuda=broken))[1], + ['CUDA is not available to torch (OSError: libcudart.so.12: cannot open shared object file).']) + self.assertEqual(environments.compare(definition, _report(torch='2.5.1'))[1], + ['CUDA is not available to torch.']) + + def test_cuda_without_torch_cannot_see_the_gpu(self): + definition = {**_cpu(numpy='2.3.5'), 'device': 'cuda'} + self.assertEqual(environments.compare(definition, _report(numpy='2.3.5')), + (False, ['The device is cuda but torch is not among the packages, ' + 'so the check cannot see the GPU.'])) + + def test_it_is_pure(self): + definition, report = _cpu(), _report(numpy='1') + before = json.dumps([definition, report]) + environments.compare(definition, report) + self.assertEqual(json.dumps([definition, report]), before) + + +class Probe(unittest.TestCase): + """The probe as a child process: what it reports, how it runs, how it fails.""" + + def setUp(self): + directory = tempfile.TemporaryDirectory() + self.addCleanup(directory.cleanup) + self.temporary = Path(directory.name) + + def script(self, body, name='python'): + path = self.temporary / name + path.write_text('#!/bin/sh\n' + body + '\n', encoding='utf-8') + path.chmod(0o755) + return str(path) + + def test_the_test_interpreter(self): + definition = {'python': MINOR, 'device': 'cpu', + 'packages': {'jsonschema': JSONSCHEMA, 'no-such-package-tuldok': '1.0'}} + found, problems = environments.probe(PYTHON, definition) + self.assertEqual(problems, []) + self.assertEqual(found['python'], '%d.%d.%d' % sys.version_info[:3]) + self.assertEqual(found['packages'], {'jsonschema': JSONSCHEMA, 'no-such-package-tuldok': None}) + self.assertEqual(found['executable'], PYTHON) + self.assertNotIn('cuda', found) + self.assertEqual(environments.compare(definition, found)[1], + ['no-such-package-tuldok is not installed; the definition asks for 1.0.']) + + def test_a_cuda_definition_without_torch_imports_nothing(self): + found, problems = environments.probe(PYTHON, {'python': MINOR, 'device': 'cuda', + 'packages': {'jsonschema': JSONSCHEMA}}) + self.assertEqual(problems, []) + self.assertNotIn('cuda', found) + + def test_a_cuda_definition_with_torch_reports_what_torch_says(self): + # torch is not in the test venv: the import fails and the report says so; no GPU is touched. + found, problems = environments.probe(PYTHON, {'python': MINOR, 'device': 'cuda', + 'packages': {'torch': '2.5.1'}}) + self.assertEqual(problems, []) + self.assertIs(found['cuda']['available'], False) + self.assertIn('ModuleNotFoundError', found['cuda']['error']) + + def test_the_probe_imports_only_what_it_may_and_parses_as_python_3_10(self): + tree = ast.parse(environments.PROBE, feature_version=(3, 10)) + imported = set() + for node in ast.walk(tree): + if isinstance(node, ast.Import): + imported.update(alias.name for alias in node.names) + elif isinstance(node, ast.ImportFrom): + imported.update(f'{node.module}.{alias.name}' for alias in node.names) + self.assertEqual(imported, {'json', 'os', 'sys', 'importlib.metadata', 'torch'}) + + def test_how_the_child_runs(self): + record = self.temporary / 'seen' + interpreter = self.script( + f'{{ printf "%s\\n" "$@"; echo "cwd=$PWD"; echo "home=$HOME"; echo "path=$PATH"; echo "lang=$LANG";' + f' echo "database=$TULDOK_DATABASE_URL"; echo "virtual=$VIRTUAL_ENV"; }} > "{record}"\n' + 'echo noise >&2\n' + 'printf \'{"python": "3.12.1", "executable": "x", "packages": {"numpy": "2.3.5"}}\'') + with mock.patch.dict(os.environ, {'VIRTUAL_ENV': '/somewhere', 'TULDOK_DATABASE_URL': 'postgresql://x'}): + found, problems = environments.probe(interpreter, _cpu()) + self.assertEqual((found['python'], problems), ('3.12.1', [])) + lines = record.read_text(encoding='utf-8').splitlines() + self.assertEqual(lines[:2], ['-I', '-c']) + self.assertEqual(json.loads(lines[-7]), {'device': 'cpu', 'packages': {'numpy': '2.3.5'}}) + seen = dict(line.split('=', 1) for line in lines[-6:]) + self.assertEqual(seen['cwd'], seen['home']) + self.assertTrue(seen['home'].startswith(tempfile.gettempdir())) + self.assertFalse(os.path.exists(seen['home'])) # removed afterwards + self.assertEqual((seen['path'], seen['lang'], seen['database'], seen['virtual']), + ('/usr/bin:/bin', 'C.UTF-8', '', '')) + + def test_a_child_that_exits_with_an_error(self): + found, problems = environments.probe(self.script('echo "Traceback: boom" >&2; exit 3'), _cpu()) + self.assertIsNone(found) + self.assertEqual(problems, ['The check exited with status 3. Its error output began: Traceback: boom']) + + def test_error_output_is_cut_at_400_characters(self): + found, problems = environments.probe(self.script('printf "%0500d" 0 >&2; exit 1'), _cpu()) + self.assertEqual(problems, ['The check exited with status 1. Its error output began: ' + '0' * 400]) + + def test_a_child_that_prints_something_else(self): + for body in ('echo hello', 'echo "[1, 2]"', 'echo \'{"python": "3.12.1"}\'', + 'echo \'{"python": "3.12.1", "executable": "x", "packages": {"scipy": "1"}}\''): + found, problems = environments.probe(self.script(body), _cpu()) + self.assertIsNone(found, body) + self.assertEqual(problems, ['The check printed something other than the report it should print.'], body) + + def test_a_child_that_does_not_start(self): + found, problems = environments.probe(str(self.temporary / 'missing'), _cpu()) + self.assertIsNone(found) + self.assertEqual(len(problems), 1) + self.assertTrue(problems[0].startswith('The interpreter could not be started: '), problems) + + def test_a_child_that_takes_too_long(self): + with mock.patch.object(environments, 'CHECK_SECONDS', 1): + found, problems = environments.probe(self.script('echo started >&2; exec sleep 30'), _cpu()) + self.assertIsNone(found) + self.assertEqual(problems, ['The check did not finish within 1 seconds. Its error output began: started']) + + +class States(unittest.TestCase): + """graph.states(definitions, local) and the plan's actions, section 2 and 5.""" + + def setUp(self): + self.documents = {} + for path in sorted((FIXTURE / 'project').glob('*/*.json')): + self.documents[f'{path.parent.name}/{path.stem}'] = json.loads(path.read_text(encoding='utf-8')) + + def test_local_states_override_environments_only(self): + states = graph.states(self.documents, {'environments/lab-cpu': 'ready', 'steps/solver': 'ready', + 'environments/absent': 'ready'}) + self.assertEqual(states['environments/lab-cpu'], 'ready') + self.assertEqual(states['steps/solver'], 'not-built') + self.assertNotIn('environments/absent', states) + self.assertEqual(graph.states(self.documents)['environments/lab-cpu'], 'not-set-up') + self.assertEqual(graph.states(self.documents, {})['environments/lab-cpu'], 'not-set-up') + failing = graph.states(self.documents, {'environments/lab-cpu': 'failing'}) + self.assertEqual({key: value for key, value in failing.items() if key != 'environments/lab-cpu'}, + {key: value for key, value in states.items() if key != 'environments/lab-cpu'}) + + def test_a_ready_environment_is_not_something_to_set_up(self): + made = plan.make_plan(self.documents, ['steps/solver'], local={'environments/lab-cpu': 'ready'}) + self.assertEqual([(step['reference'], step['state'], step['action']) for step in made['steps']], + [('environments/lab-cpu', 'ready', 'ready'), ('steps/solver', 'not-built', 'build')]) + self.assertEqual(made['counts'], {'build': 1, 'set-up': 0, 'blocked': 0, 'ready': 1}) + + def test_a_failing_environment_is_set_up(self): + made = plan.make_plan(self.documents, ['steps/solver'], local={'environments/lab-cpu': 'failing'}) + self.assertEqual(made['steps'][0]['action'], 'set-up') + self.assertEqual(made['steps'][0]['state'], 'failing') + self.assertEqual(made['counts'], {'build': 1, 'set-up': 1, 'blocked': 0, 'ready': 0}) + + +class Local(unittest.TestCase): + + def test_the_local_home(self): + with tempfile.TemporaryDirectory() as directory: + with mock.patch.dict(os.environ, {local.HOME_VARIABLE: os.path.join(directory, 'h')}): + self.assertEqual(local.environment_target('a' * 32, 'lab-cpu'), + os.path.join(directory, 'h', 'a' * 32, 'environments', 'lab-cpu')) + self.assertFalse(os.path.exists(os.path.join(directory, 'h'))) # nothing made by asking + made = local.environments_directory('a' * 32, create=True) + self.assertTrue(os.path.isdir(made)) + with mock.patch.dict(os.environ, {local.HOME_VARIABLE: ''}): + self.assertEqual(local.projects_home(), os.path.expanduser('~/.local/share/tuldok/projects')) + + +STANDIN = r'''#!/bin/sh +{ printf '%s\n' "$PWD" "$@"; echo '--end--'; } >> "$STANDIN_CALLS" +case "$1" in +venv) + mkdir -p "$4/bin" + ln -s "$STANDIN_PYTHON" "$4/bin/python" + if [ -n "$STANDIN_VENV" ]; then + cp "$STANDIN_VENV/pyvenv.cfg" "$4/pyvenv.cfg" + ln -s "$STANDIN_VENV/lib" "$4/lib" + fi + echo "stand-in made $4" + ;; +pip) + if [ -n "$STANDIN_FAIL_PIP" ]; then + echo "error: stand-in refuses to install" + exit 1 + fi + echo "stand-in installed from $7" + ;; +esac +''' + + +class EnvironmentCase(unittest.TestCase): + """A fresh copy of the fixture whose lab-cpu asks for what the test venv has, a spare environment, a local home.""" + + def setUp(self): + directory = tempfile.TemporaryDirectory() + self.addCleanup(directory.cleanup) + self.temporary = Path(directory.name) + shutil.copytree(FIXTURE, self.temporary / 'minimal') + self.folder = self.temporary / 'minimal' / 'project' + self.code = Path(os.path.realpath(self.temporary / 'minimal' / 'code')) + self.project_id = uuid.uuid4().hex + project_file = self.folder / 'tuldok.json' + document = json.loads(project_file.read_text(encoding='utf-8')) + document['id'] = self.project_id + project_file.write_text(json.dumps(document, indent=2) + '\n', encoding='utf-8') + self.write_environment('lab-cpu', packages={'jsonschema': JSONSCHEMA}) + self.write_environment('spare', install=None) + self.home = self.temporary / 'local home' + self.calls = self.temporary / 'calls' + self.uv = self.temporary / 'bin' / 'uv' + self.uv.parent.mkdir() + self.uv.write_text(STANDIN, encoding='utf-8') + self.uv.chmod(0o755) + self.variables = {local.HOME_VARIABLE: str(self.home), environments.UV_VARIABLE: str(self.uv), + 'STANDIN_CALLS': str(self.calls), 'STANDIN_PYTHON': PYTHON, 'STANDIN_VENV': VENV} + patcher = mock.patch.dict(os.environ, self.variables) + patcher.start() + self.addCleanup(patcher.stop) + self.target = local.environment_target(self.project_id, 'lab-cpu') + + def write_environment(self, name, *, packages=None, install=False): + document = {'format': 'tuldok_definition_v1', 'kind': 'environment', 'title': f'Environment {name}', + 'python': MINOR, 'device': 'cpu', 'packages': packages or {'jsonschema': JSONSCHEMA}} + if install is False: + install = {'requirements': 'requirements.txt', 'index_urls': ['https://example.org/simple']} + if install is not None: + document['install'] = install + (self.folder / 'environments' / f'{name}.json').write_text(json.dumps(document, indent=2) + '\n', + encoding='utf-8') + + def calls_made(self): + """[[cwd, argument, ...], ...] for every run of the stand-in uv.""" + if not self.calls.exists(): + return [] + found, current = [], [] + for line in self.calls.read_text(encoding='utf-8').splitlines(): + if line == '--end--': + found.append(current) + current = [] + else: + current.append(line) + return found + + +@unittest.skipUnless(DATABASE, 'TULDOK_DATABASE_URL is not set; database tests need a disposable cluster.') +class Records(EnvironmentCase): + """connect, check, disconnect and the states the Project reports.""" + + def setUp(self): + super().setUp() + self.addCleanup(store.drop_project, self.project_id) + self.project = self.open() + + def open(self): + project = store.open_project(self.folder) + self.addCleanup(project.close) + return project + + def rows(self): + return self.project._execute('SELECT name, interpreter, origin, ok FROM {schema}.environments ' + 'ORDER BY name').fetchall() + + def test_connect_records_and_checks(self): + shown = environments.connect(self.project, 'environments/lab-cpu', PYTHON) + self.assertEqual((shown['state'], shown['ok'], shown['problems'], shown['origin'], shown['interpreter']), + ('ready', True, [], 'connected', PYTHON)) + self.assertEqual(shown['found']['packages'], {'jsonschema': JSONSCHEMA}) + self.assertIsNotNone(shown['checked_at']) + self.assertEqual(self.rows(), [('lab-cpu', PYTHON, 'connected', True)]) + self.assertEqual(self.project.summary()['states']['ready'], 1) + self.assertEqual({row['reference']: row['state'] for row in self.project.definitions(kind='environment')}, + {'environments/lab-cpu': 'ready', 'environments/spare': 'not-set-up'}) + self.assertEqual(self.project.definition('environments/lab-cpu')['state'], 'ready') + nodes = {node['reference']: node['state'] for node in self.project.graph()['nodes']} + self.assertEqual((nodes['environments/lab-cpu'], nodes['steps/solver']), ('ready', 'not-built')) + self.assertEqual(plan.build_plan(self.project, ['steps/solver'])['steps'][0]['action'], 'ready') + + def test_a_bare_name_is_accepted(self): + self.assertEqual(environments.connect(self.project, 'lab-cpu', PYTHON)['reference'], 'environments/lab-cpu') + + def test_opening_never_runs_a_check(self): + environments.connect(self.project, 'lab-cpu', PYTHON) + self.project.close() + with mock.patch.object(environments, 'probe', side_effect=AssertionError('a check ran')), \ + mock.patch.object(subprocess, 'run', side_effect=AssertionError('a process ran')): + project = self.open() + self.assertEqual(project.definition('environments/lab-cpu')['state'], 'ready') + self.assertEqual(environments.listing(project)[0]['state'], 'ready') + + def test_a_failed_check_is_a_stored_result(self): + text = (self.folder / 'environments' / 'lab-cpu.json').read_text(encoding='utf-8') + self.project.set_definition('environments/lab-cpu', text.replace(JSONSCHEMA, '0.0.1')) + shown = environments.connect(self.project, 'lab-cpu', PYTHON) + self.assertEqual((shown['state'], shown['ok']), ('failing', False)) + self.assertEqual(shown['problems'], [f'jsonschema is {JSONSCHEMA}; the definition asks for 0.0.1.']) + self.assertEqual(self.rows(), [('lab-cpu', PYTHON, 'connected', False)]) + self.assertEqual(self.project.definition('environments/lab-cpu')['state'], 'failing') + made = plan.build_plan(self.project, ['steps/solver']) + self.assertEqual((made['steps'][0]['state'], made['steps'][0]['action']), ('failing', 'set-up')) + # Put right, the next check passes. + self.project.set_definition('environments/lab-cpu', text) + self.assertEqual(environments.check(self.project, 'lab-cpu')['state'], 'ready') + + def test_an_interpreter_that_vanished_fails_its_check(self): + link = self.temporary / 'python-link' + link.symlink_to(PYTHON) + # A link outside the venv is the base interpreter, so this check may fail; it does run. + self.assertIsNotNone(environments.connect(self.project, 'lab-cpu', str(link))['found']) + self.assertEqual(self.rows()[0][1], str(link)) # stored as given, not resolved + link.unlink() + shown = environments.check(self.project, 'lab-cpu') + self.assertEqual(shown['state'], 'failing') + self.assertTrue(shown['problems'][0].startswith('The interpreter could not be started'), shown['problems']) + self.assertIsNone(shown['found']) + + def test_refusals(self): + cases = [ + (lambda: environments.connect(self.project, 'lab-cpu', 'python3'), 'invalid'), + (lambda: environments.connect(self.project, 'lab-cpu', str(self.temporary / 'missing')), 'invalid'), + (lambda: environments.connect(self.project, 'lab-cpu', str(self.folder / 'tuldok.json')), 'invalid'), + (lambda: environments.connect(self.project, 'lab-cpu', str(self.temporary)), 'invalid'), + (lambda: environments.connect(self.project, 'nothing', PYTHON), 'not-found'), + (lambda: environments.connect(self.project, 'steps/solver', PYTHON), 'not-found'), + (lambda: environments.check(self.project, 'lab-cpu'), 'not-set-up'), + (lambda: environments.check(self.project, 'nothing'), 'not-found'), + (lambda: environments.disconnect(self.project, 'lab-cpu'), 'not-set-up'), + ] + for call, code in cases: + with self.assertRaises(ProjectError) as raised: + call() + self.assertEqual(raised.exception.code, code, str(raised.exception)) + self.assertEqual(self.rows(), []) + + def test_disconnect_a_connected_interpreter(self): + environments.connect(self.project, 'lab-cpu', PYTHON) + self.assertEqual(environments.disconnect(self.project, 'lab-cpu'), + {'reference': 'environments/lab-cpu', 'origin': 'connected', 'interpreter': PYTHON, + 'directory': None}) + self.assertEqual(self.rows(), []) + self.assertEqual(self.project.definition('environments/lab-cpu')['state'], 'not-set-up') + + def test_the_record_goes_with_its_definition(self): + environments.connect(self.project, 'spare', PYTHON) + self.project.remove_definition('environments/spare') + self.assertEqual(self.rows(), []) + self.project.save() + # And when the file is deleted on disk, the next open drops the record. + environments.connect(self.project, 'lab-cpu', PYTHON) + self.write_environment('other') + self.project.close() + project = self.open() + environments.connect(project, 'other', PYTHON) + project.close() + (self.folder / 'environments' / 'other.json').unlink() + self.project = self.open() + self.assertEqual([row[0] for row in self.rows()], ['lab-cpu']) + + def test_listing(self): + environments.connect(self.project, 'lab-cpu', PYTHON) + rows = environments.listing(self.project) + self.assertEqual([(row['reference'], row['state'], row['installable']) for row in rows], + [('environments/lab-cpu', 'ready', True), ('environments/spare', 'not-set-up', False)]) + self.assertEqual(environments.recorded(self.project), ['environments/lab-cpu']) + + +@unittest.skipUnless(DATABASE, 'TULDOK_DATABASE_URL is not set; database tests need a disposable cluster.') +class SetUp(EnvironmentCase): + """set_up with the stand-in uv; nothing is downloaded or installed.""" + + def setUp(self): + super().setUp() + self.addCleanup(store.drop_project, self.project_id) + self.project = store.open_project(self.folder) + self.addCleanup(self.project.close) + self.expected = [ + [str(self.code), 'venv', '--python', MINOR, self.target], + [str(self.code), 'pip', 'install', '--python', os.path.join(self.target, 'bin', 'python'), + '-r', str(self.code / 'requirements.txt'), '--extra-index-url', 'https://example.org/simple'], + ] + + def rows(self): + return self.project._execute('SELECT name, interpreter, origin, ok FROM {schema}.environments').fetchall() + + def test_success(self): + done = environments.set_up(self.project, 'lab-cpu') + self.assertEqual(self.calls_made(), self.expected) + interpreter = os.path.join(self.target, 'bin', 'python') + self.assertEqual((done['state'], done['origin'], done['interpreter'], done['problems']), + ('ready', 'installed', interpreter, [])) + self.assertEqual(self.rows(), [('lab-cpu', interpreter, 'installed', True)]) + commands = [[str(self.uv), *call[1:]] for call in self.expected] + self.assertEqual(done['commands'], commands) + log = Path(self.target + '.log').read_text(encoding='utf-8') + self.assertEqual(log, f'$ {shlex.join(commands[0])}\nstand-in made {self.target}\n' + f'$ {shlex.join(commands[1])}\nstand-in installed from {commands[1][7]}\n') + + def test_a_failing_second_command(self): + with mock.patch.dict(os.environ, {'STANDIN_FAIL_PIP': '1'}): + with self.assertRaises(ProjectError) as raised: + environments.set_up(self.project, 'lab-cpu') + self.assertEqual(raised.exception.code, 'install-failed') + message = str(raised.exception) + self.assertIn('exited with status 1', message) + self.assertIn('error: stand-in refuses to install', message) + self.assertIn(self.target + '.log', message) + self.assertFalse(os.path.lexists(self.target)) + self.assertIn('error: stand-in refuses to install', Path(self.target + '.log').read_text(encoding='utf-8')) + self.assertEqual(len(self.calls_made()), 2) + self.assertEqual(self.rows(), []) + + def test_a_missing_installer(self): + empty = self.temporary / 'empty-path' + empty.mkdir() + with mock.patch.dict(os.environ, {'PATH': str(empty)}): + os.environ.pop(environments.UV_VARIABLE) + with self.assertRaises(ProjectError) as raised: + environments.set_up(self.project, 'lab-cpu', dry_run=True) + self.assertEqual(raised.exception.code, 'no-installer') + self.assertIn('uv is not on PATH', str(raised.exception)) + with mock.patch.dict(os.environ, {environments.UV_VARIABLE: str(self.temporary / 'no-uv')}): + with self.assertRaises(ProjectError) as raised: + environments.set_up(self.project, 'lab-cpu') + self.assertEqual(raised.exception.code, 'no-installer') + self.assertEqual(self.calls_made(), []) + self.assertFalse(self.home.exists()) + + def test_a_missing_install_section(self): + with self.assertRaises(ProjectError) as raised: + environments.set_up(self.project, 'spare') + self.assertEqual(raised.exception.code, 'no-install') + self.assertIn('connect', str(raised.exception)) + self.assertEqual(self.calls_made(), []) + + def test_an_existing_target(self): + os.makedirs(self.target) + environments.set_up(self.project, 'lab-cpu', dry_run=True) # an empty target is fine + Path(self.target, 'old').write_text('old', encoding='utf-8') + with self.assertRaises(ProjectError) as raised: + environments.set_up(self.project, 'lab-cpu') + self.assertEqual(raised.exception.code, 'target-exists') + self.assertTrue(os.path.exists(os.path.join(self.target, 'old'))) + self.assertEqual(self.calls_made(), []) + self.assertTrue(environments.set_up(self.project, 'lab-cpu', dry_run=True, replace=True)['replaces']) + self.assertTrue(os.path.exists(os.path.join(self.target, 'old'))) + done = environments.set_up(self.project, 'lab-cpu', replace=True) + self.assertEqual(done['state'], 'ready') + self.assertFalse(os.path.exists(os.path.join(self.target, 'old'))) + + def test_dry_run(self): + done = environments.set_up(self.project, 'environments/lab-cpu', dry_run=True) + self.assertEqual(done, {'reference': 'environments/lab-cpu', + 'commands': [[str(self.uv), *call[1:]] for call in self.expected], + 'cwd': str(self.code), 'target': self.target, 'log': self.target + '.log', + 'replaces': False, 'dry_run': True}) + self.assertEqual(self.calls_made(), []) + self.assertFalse(self.home.exists()) + self.assertEqual(self.rows(), []) + + def test_disconnect_keeps_the_installed_directory(self): + environments.set_up(self.project, 'lab-cpu') + done = environments.disconnect(self.project, 'lab-cpu') + self.assertEqual((done['origin'], done['directory']), ('installed', self.target)) + self.assertTrue(os.path.isdir(self.target)) + self.assertEqual(self.rows(), []) + + +def run(*arguments, variables): + environment = dict(os.environ, PYTHONDONTWRITEBYTECODE='1', **variables) + return subprocess.run([sys.executable, '-m', 'tuldok_project', *map(str, arguments)], cwd=REPOSITORY, + env=environment, capture_output=True, text=True, timeout=300) + + +@unittest.skipUnless(DATABASE, 'TULDOK_DATABASE_URL is not set; database tests need a disposable cluster.') +class Commands(EnvironmentCase): + """The five commands, run as a child process.""" + + def setUp(self): + super().setUp() + self.addCleanup(store.drop_project, self.project_id) + + def command(self, *arguments, status=0): + done = run(*arguments, variables=self.variables) + self.assertEqual(done.returncode, status, done.stdout + done.stderr) + return done + + def test_environments_connect_check_disconnect(self): + lines = self.command('environments', self.folder).stdout.splitlines() + self.assertEqual(lines[0].split(), ['environment', 'state', 'origin', 'last', 'check', 'interpreter']) + self.assertEqual(lines[1].split(), ['environments/lab-cpu', 'not-set-up', '-', '-', '-']) + self.assertEqual(lines[2].strip(), 'not set up on this machine; run set-up or connect an interpreter') + self.assertEqual(lines[4].strip(), 'not set up on this machine; connect an interpreter') + self.assertEqual(lines[-1], '0 of 2 environments ready on this machine.') + + connected = self.command('connect', self.folder, 'lab-cpu', PYTHON).stdout.splitlines() + self.assertEqual(connected, [f'Recorded {PYTHON} for environments/lab-cpu.', + 'environments/lab-cpu is ready: the check passed.', + f' python {"%d.%d.%d" % sys.version_info[:3]} (asks {MINOR})', + f' jsonschema {JSONSCHEMA}']) + lines = self.command('environments', self.folder).stdout.splitlines() + self.assertEqual(lines[1].split()[:3], ['environments/lab-cpu', 'ready', 'connected']) + self.assertTrue(lines[1].endswith(PYTHON)) + self.assertEqual(lines[-1], '1 of 2 environments ready on this machine.') + listed = json.loads(self.command('environments', self.folder, '--json').stdout) + self.assertEqual([item['state'] for item in listed], ['ready', 'not-set-up']) + + checked = self.command('check-environment', self.folder).stdout.splitlines() + self.assertEqual(checked[0], 'environments/lab-cpu is ready: the check passed.') + self.assertEqual(json.loads(self.command('check-environment', self.folder, 'environments/lab-cpu', + '--json').stdout)[0]['ok'], True) + failed = self.command('check-environment', self.folder, 'spare', status=1) + self.assertEqual(failed.stderr, 'environments/spare is not set up on this machine; ' + 'connect an interpreter or run set-up.\n') + self.assertEqual(self.command('connect', self.folder, 'Bad Name', PYTHON, status=2).stdout, '') + + lines = self.command('plan', self.folder, 'steps/solver').stdout.splitlines() + self.assertEqual(lines[0], '1 step to build, 0 to set up, 0 blocked, 1 ready: steps/solver can be built.') + self.assertEqual(lines[3].split(), ['1', 'ready', '-', '-', '-', 'environments/lab-cpu']) + + done = self.command('disconnect', self.folder, 'lab-cpu').stdout + self.assertEqual(done, f'environments/lab-cpu is no longer connected to {PYTHON}.\n') + + def test_a_failing_connect_exits_1_and_says_why(self): + self.write_environment('lab-cpu', packages={'jsonschema': '0.0.1'}) + done = self.command('connect', self.folder, 'lab-cpu', PYTHON, status=1) + self.assertIn('environments/lab-cpu is failing: the check found 1 problem.', done.stdout) + self.assertIn(f' problem: jsonschema is {JSONSCHEMA}; the definition asks for 0.0.1.', done.stdout) + self.assertEqual(json.loads(self.command('connect', self.folder, 'lab-cpu', PYTHON, '--json', + status=1).stdout)['state'], 'failing') + lines = self.command('plan', self.folder, 'steps/solver').stdout.splitlines() + self.assertEqual(lines[3].split()[:2], ['1', 'set-up']) + self.assertEqual(lines[4].strip(), 'its last check failed; see environments') + self.command('check-environment', self.folder, status=1) + + def test_set_up_dry_run_and_real(self): + lines = self.command('set-up', self.folder, 'lab-cpu', '--dry-run').stdout.splitlines() + self.assertEqual(lines[0], f'Would set up environments/lab-cpu by running, in {self.code}:') + self.assertEqual(lines[1], shlex.join([str(self.uv), 'venv', '--python', MINOR, self.target])) + self.assertEqual(shlex.split(lines[2]), [str(self.uv), *self.expected_pip()]) + self.assertEqual(lines[3].split(None, 1), ['target', self.target]) + self.assertEqual(lines[4].split(None, 1), ['log', self.target + '.log']) + self.assertEqual(lines[5], 'Nothing was run.') + self.assertEqual(self.calls_made(), []) + self.assertFalse(self.home.exists()) + planned = json.loads(self.command('set-up', self.folder, 'lab-cpu', '--dry-run', '--json').stdout) + self.assertTrue(planned['dry_run']) + + done = self.command('set-up', self.folder, 'lab-cpu').stdout.splitlines() + self.assertEqual(done[0], f'Installed environments/lab-cpu in {self.target}; the log is {self.target}.log.') + self.assertEqual(done[1], 'environments/lab-cpu is ready: the check passed.') + again = self.command('set-up', self.folder, 'lab-cpu', status=1) + self.assertIn('already exists and is not empty', again.stderr) + self.command('set-up', self.folder, 'lab-cpu', '--replace') + refused = self.command('set-up', self.folder, 'spare', '--dry-run', status=1) + self.assertIn('has no install.requirements', refused.stderr) + done = self.command('disconnect', self.folder, 'lab-cpu').stdout.splitlines() + self.assertEqual(done[1], f'The installed environment in {self.target} was kept; ' + 'delete it yourself when it is not needed.') + + def expected_pip(self): + return ['pip', 'install', '--python', os.path.join(self.target, 'bin', 'python'), + '-r', str(self.code / 'requirements.txt'), '--extra-index-url', 'https://example.org/simple'] + + +if __name__ == '__main__': + unittest.main() diff --git a/tests/test_tuldok_project_plan.py b/tests/test_tuldok_project_plan.py index 58a962f2..e3218d3a 100644 --- a/tests/test_tuldok_project_plan.py +++ b/tests/test_tuldok_project_plan.py @@ -84,7 +84,7 @@ def test_nothing_is_followed_out_of_a_blocked_step(self): self.mark('datasets/waves', 'no', 'The scenes were made by hand.') made = self.make('recipes/stepper-k1') self.assertEqual(_references(made), ['recipes/stepper-k1']) # not its dataset, solver or environment - self.assertEqual(made['counts'], {'build': 0, 'set-up': 0, 'blocked': 1}) + self.assertEqual(made['counts'], {'build': 0, 'set-up': 0, 'blocked': 1, 'ready': 0}) self.assertEqual(made['steps'][0]['blocked_by'], [{'reference': 'datasets/waves', 'rebuild': 'no', 'reason': 'The scenes were made by hand.'}]) # A cause is a step when it is a target itself. @@ -126,7 +126,7 @@ def test_a_model_is_not_built(self): self.assertEqual(made['targets'], ['models/stepper']) self.assertEqual(made['steps'], []) self.assertTrue(made['buildable']) - self.assertEqual(made['counts'], {'build': 0, 'set-up': 0, 'blocked': 0}) + self.assertEqual(made['counts'], {'build': 0, 'set-up': 0, 'blocked': 0, 'ready': 0}) self.assertEqual(made['notes'], ['models/stepper is a model; a model is not built, ' 'only the recipes that train it.']) @@ -178,7 +178,7 @@ def test_every_action(self): 'recipes/early-fit': ('cannot-rebuild', 'blocked'), 'benchmarks/rollout': ('not-built', 'build'), }) - self.assertEqual(made['counts'], {'build': 4, 'set-up': 1, 'blocked': 2}) + self.assertEqual(made['counts'], {'build': 4, 'set-up': 1, 'blocked': 2, 'ready': 0}) self.assertFalse(made['buildable']) self.assertEqual(made['blocked_targets'], ['recipes/stepper-k2', 'recipes/early-fit']) diff --git a/tuldok_project/__main__.py b/tuldok_project/__main__.py index e4cf47b0..7384dffb 100644 --- a/tuldok_project/__main__.py +++ b/tuldok_project/__main__.py @@ -12,6 +12,11 @@ the database (charts.py) and never read a results or values file. `plan` lists what has to be built for some definitions (plan.py) and runs nothing. A benchmark or chart may be named bare (`rollout`) or as a reference (`benchmarks/rollout`). +`environments`, `connect`, `check-environment`, `set-up` and `disconnect` +work with the interpreters that fulfil environments on this machine +(environments.py); an environment may be named bare too. Only +`check-environment`, `connect` and `set-up` run anything, and `set-up +--dry-run` runs nothing. """ import argparse import dataclasses @@ -98,6 +103,18 @@ def add(name, parents, help_text): planning = add('plan', [reading], 'list what has to be built, in order, to have these definitions; runs nothing') planning.add_argument('targets', nargs='*', metavar='TARGET', help='references, for example recipes/pilot-dense-k1') planning.add_argument('--all', action='store_true', help='plan every dataset, recipe, step and benchmark') + add('environments', [reading], 'list the environments: which interpreter fulfils each here and its last check') + connecting = add('connect', [reading], 'record an existing interpreter for an environment, then check it') + connecting.add_argument('environment', help='for example lab-cpu or environments/lab-cpu') + connecting.add_argument('interpreter', help='the absolute path of the Python executable') + checking = add('check-environment', [reading], 'check recorded environments again (all when none is named)') + checking.add_argument('environments', nargs='*', metavar='ENVIRONMENT', help='for example lab-cpu') + setting_up = add('set-up', [reading], "install an environment with uv from its definition's install section") + setting_up.add_argument('environment', help='for example lab-cpu or environments/lab-cpu') + setting_up.add_argument('--dry-run', action='store_true', help='print the commands, the target and the log; run nothing') + setting_up.add_argument('--replace', action='store_true', help='remove an existing target first') + disconnecting = add('disconnect', [opening], "forget an environment's interpreter; an installed one is not deleted") + disconnecting.add_argument('environment', help='for example lab-cpu or environments/lab-cpu') add('forget', [database], "drop this project's copy from the database; the folder is not touched") return parser @@ -441,13 +458,13 @@ def _figure(value, unit): def _gpu(step): - if step['action'] == 'set-up': + if step['action'] in ('set-up', 'ready'): return '-' return 'yes' if step['resources']['gpu'] is True else '-' # an absent gpu means none is needed def _step_figures(step): - if step['action'] == 'set-up': + if step['action'] in ('set-up', 'ready'): return '-', '-', '-' return _gpu(step), _figure(step['resources']['disk_gb'], ' GB'), _figure(step['resources']['wall_hours'], ' h') @@ -467,6 +484,8 @@ def _step_details(step): details.append(f'{name}: {given["reference"]}{output}') if step['environment']: details.append(f'in {step["environment"]}') + if step['kind'] == 'environment' and step['state'] == 'failing': + details.append('its last check failed; see environments') subjects = step.get('subjects') if subjects is not None: details.append(f'runs {_plural(len(subjects["run"]), "subject")}') @@ -510,7 +529,7 @@ def _opening(plan): if not plan['steps']: return f'Nothing to build for {targets[0] if len(targets) == 1 else _plural(len(targets), "target")}.' numbers = (f'{_plural(counts["build"], "step")} to build, {counts["set-up"]} to set up, ' - f'{counts["blocked"]} blocked') + f'{counts["blocked"]} blocked' + (f', {counts["ready"]} ready' if counts['ready'] else '')) every = ' (every dataset, recipe, step and benchmark)' if plan['every'] else '' blocked = len(plan['blocked_targets']) if len(targets) == 1 and not every: @@ -575,9 +594,157 @@ def _plan(project, arguments): return 0 +# ------------------------------------------------------------ environments + +def _when(value): + return '-' if value is None else value.astimezone().strftime('%Y-%m-%d %H:%M') + + +def _found_lines(shown): + """What the last check saw, one short line each: Python, each package, and CUDA when it was looked at.""" + found = shown['found'] + if not found: + return [] + lines = [f'python {found.get("python")} (asks {shown["python"]})'] + for name, asked in shown['packages'].items(): + installed = (found.get('packages') or {}).get(name) + lines.append(f'{name} {installed or "not installed"}' + ('' if installed == asked else f' (asks {asked})')) + cuda = found.get('cuda') + if isinstance(cuda, dict): + if cuda.get('available'): + lines.append(f'cuda {cuda.get("version") or "?"} on {cuda.get("device") or "an unnamed device"}') + else: + lines.append('cuda not available') + if cuda.get('driver'): + lines.append(f'driver: {cuda["driver"]}') + return lines + + +def _environment_lines(shown): + """One environment for a person: a header row, then what was found and why it is not ready.""" + lines = [] + if shown['state'] == 'not-set-up': + how = 'run set-up or connect an interpreter' if shown['installable'] else 'connect an interpreter' + lines.append(f'not set up on this machine; {how}') + else: + lines += _found_lines(shown) + lines += [f'problem: {problem}' for problem in shown['problems']] + return lines + + +def _environment_header(shown): + return (shown['reference'], shown['state'], shown['origin'] or '-', _when(shown['checked_at']), + shown['interpreter'] or '-') + + +def _show_environments(shown_list): + rows = [('environment', 'state', 'origin', 'last check', 'interpreter')] + rows += [_environment_header(shown) for shown in shown_list] + widths = [max(len(str(row[index])) for row in rows) for index in range(4)] + for index, row in enumerate(rows): + print((' '.join(str(cell).ljust(widths[column]) for column, cell in enumerate(row[:4])) + ' ' + row[4]).rstrip()) + if index: + for line in _environment_lines(shown_list[index - 1]): + print(' ' + line) + + +def _environments(project, arguments): + from . import environments + + shown = environments.listing(project) + if arguments.json: + _json(shown) + return 0 + if not shown: + print('The project defines no environment.') + return 0 + _show_environments(shown) + ready = sum(item['state'] == 'ready' for item in shown) + print() + print(f'{ready} of {_plural(len(shown), "environment")} ready on this machine.') + return 0 + + +def _checked_line(shown): + if shown['ok']: + return f'{shown["reference"]} is ready: the check passed.' + return (f'{shown["reference"]} is failing: the check found ' + f'{_plural(len(shown["problems"]), "problem")}.') + + +def _connect(project, arguments): + from . import environments + + shown = environments.connect(project, arguments.environment, arguments.interpreter) + if arguments.json: + _json(shown) + else: + print(f'Recorded {shown["interpreter"]} for {shown["reference"]}.') + print(_checked_line(shown)) + for line in _environment_lines(shown): + print(' ' + line) + return 0 if shown['ok'] else 1 + + +def _check_environment(project, arguments): + from . import environments + + names = arguments.environments or environments.recorded(project) + checked = [environments.check(project, reference) for reference in names] + if arguments.json: + _json(checked) + elif not checked: + print('No environment is recorded on this machine; connect an interpreter or run set-up first.') + else: + for index, shown in enumerate(checked): + if index: + print() + print(_checked_line(shown)) + for line in _environment_lines(shown): + print(' ' + line) + return 0 if all(shown['ok'] for shown in checked) else 1 + + +def _set_up(project, arguments): + import shlex + + from . import environments + + done = environments.set_up(project, arguments.environment, dry_run=arguments.dry_run, replace=arguments.replace) + if arguments.json: + _json(done) + return 0 if done['dry_run'] or done['ok'] else 1 + if done['dry_run']: + print(f'Would set up {done["reference"]} by running, in {done["cwd"]}:') + for command in done['commands']: + print(shlex.join(command)) + if done['replaces']: + print(f'after removing the existing {done["target"]}.') + _columns([('target', done['target']), ('log', done['log'])]) + print('Nothing was run.') + return 0 + print(f'Installed {done["reference"]} in {done["target"]}; the log is {done["log"]}.') + print(_checked_line(done)) + for line in _environment_lines(done): + print(' ' + line) + return 0 if done['ok'] else 1 + + +def _disconnect(project, arguments): + from . import environments + + done = environments.disconnect(project, arguments.environment) + print(f'{done["reference"]} is no longer connected to {done["interpreter"]}.') + if done['directory']: + print(f'The installed environment in {done["directory"]} was kept; delete it yourself when it is not needed.') + return 0 + + _STORE_COMMANDS = {'open': _open, 'list': _list, 'show': _show, 'graph': _graph, 'status': _status, 'set': _set, 'remove': _remove, 'save': _save, 'results': _results, 'values': _values, - 'import-values': _import_values, 'chart': _chart, 'report': _report, 'plan': _plan} + 'import-values': _import_values, 'chart': _chart, 'report': _report, 'plan': _plan, + 'environments': _environments, 'connect': _connect, 'check-environment': _check_environment, + 'set-up': _set_up, 'disconnect': _disconnect} def _project_id(folder): @@ -653,6 +820,10 @@ def _run_store(arguments, dsn): arguments.benchmark = _bare(arguments.benchmark, 'benchmarks') if arguments.command == 'chart': arguments.chart = _bare(arguments.chart, 'charts') + if arguments.command in ('connect', 'set-up', 'disconnect'): + arguments.environment = 'environments/' + _bare(arguments.environment, 'environments') + if arguments.command == 'check-environment': + arguments.environments = ['environments/' + _bare(name, 'environments') for name in arguments.environments] if arguments.command == 'plan' and not arguments.targets and not arguments.all: raise UsageError('Name at least one definition to plan, or pass --all.') started = time.monotonic() diff --git a/tuldok_project/environments.py b/tuldok_project/environments.py new file mode 100644 index 00000000..4cc803c5 --- /dev/null +++ b/tuldok_project/environments.py @@ -0,0 +1,473 @@ +"""Environments on this machine: which interpreter fulfils each one, its check, and installing one with uv. + +Owns sections 2 to 4 of docs/plans/definition-first-projects/spec-m5.md. The +environments table of a project schema records, per environment definition, +the interpreter that fulfils it here, whether it was connected or installed, +and the result of its last check; the state an environment shows (ready, +failing, not-set-up) is read from that stored result, so opening a project +never runs anything. A check runs the recorded interpreter once as an +isolated child process with PROBE, which reports versions through +importlib.metadata without importing packages (torch alone, for a cuda +definition that lists it); compare() judges that report against the +definition as a pure function. A failed check is a stored result with +problems, never an exception: only a check that cannot be attempted at all +raises ProjectError. set_up installs with uv into the project's local home +(local.py) and keeps a log beside the target; nothing here installs anything +unless set_up is called without dry_run. +""" +import json +import os +import shlex +import shutil +import signal +import subprocess +import tempfile + +from psycopg import sql +from psycopg.types.json import Jsonb + +from . import documents, local, store + +DIRECTORY = 'environments' +CHECK_SECONDS = 180 +INSTALL_SECONDS = 3600 +ERROR_CHARACTERS = 400 +LOG_LINES = 20 +UV_VARIABLE = 'TULDOK_UV' + +TABLES = ( + '''CREATE TABLE IF NOT EXISTS {schema}.environments ( + name text PRIMARY KEY, + interpreter text NOT NULL, + origin text NOT NULL CHECK (origin IN ('connected', 'installed')), + recorded_at timestamptz NOT NULL, + checked_at timestamptz, + ok boolean, + found jsonb, + problems jsonb)''', +) + +_COLUMNS = ('name', 'interpreter', 'origin', 'recorded_at', 'checked_at', 'ok', 'found', 'problems') +_SELECT = 'SELECT ' + ', '.join(_COLUMNS) + ' FROM {schema}.environments' + +# Runs inside the environment's own interpreter, Python 3.10 to 3.14, with -I. +# Anything a package prints while torch is imported goes to stderr, so stdout +# carries exactly one JSON object. +PROBE = r''' +import json, os, sys +from importlib import metadata +report_stream = os.fdopen(os.dup(1), "w", encoding="utf-8") +os.dup2(2, 1) +request = json.loads(sys.argv[1]) +packages = request.get("packages") or {} +report = {"python": "%d.%d.%d" % sys.version_info[:3], "executable": sys.executable, "packages": {}} +for name in packages: + try: + report["packages"][name] = metadata.version(name) + except metadata.PackageNotFoundError: + report["packages"][name] = None +if request.get("device") == "cuda" and "torch" in packages: + cuda = {"available": False, "version": None, "device": None, "driver": None, "error": None} + try: + import torch + cuda["available"] = bool(torch.cuda.is_available()) + cuda["version"] = torch.version.cuda + if cuda["available"]: + cuda["device"] = torch.cuda.get_device_name(0) + except BaseException as exc: + cuda["error"] = ("%s: %s" % (type(exc).__name__, exc))[:400] + try: + with open("/proc/driver/nvidia/version", encoding="utf-8", errors="replace") as handle: + cuda["driver"] = handle.readline().strip() or None + except OSError: + pass + report["cuda"] = cuda +sys.stdout.flush() +report_stream.write(json.dumps(report)) +report_stream.flush() +''' + + +# ------------------------------------------------------------ the store's hooks + +def _q(schema, template): + return sql.SQL(template).format(schema=sql.Identifier(schema)) + + +def recorded_states(connection, schema): + """{reference: 'ready' | 'failing'} for every recorded environment; a record never checked is failing.""" + rows = connection.execute(_q(schema, 'SELECT name, ok FROM {schema}.environments')).fetchall() + return {documents.reference(DIRECTORY, name): 'ready' if ok else 'failing' for name, ok in rows} + + +def forget(connection, schema, name): + """Drop the record of one environment (its definition is gone); an installed directory is left alone.""" + connection.execute(_q(schema, 'DELETE FROM {schema}.environments WHERE name = %s'), (name,)) + + +# ------------------------------------------------------------- the comparison + +def _python_line(found): + return found.get('python') if isinstance(found.get('python'), str) else None + + +def compare(definition, found): + """(ok, problems) for what the probe reported against an environment definition. + + Pure: definition is the decoded environment document, found the probe's + report. What must hold (spec-m5.md section 3): the Python version's + major.minor equals the definition's python; every package's installed + version equals the definition's exactly; for device cuda, torch is among + the packages and reports CUDA as available. + """ + problems = [] + asked_python = definition['python'] + python = _python_line(found) + if python is None or '.'.join(python.split('.')[:2]) != asked_python: + problems.append(f'Python is {python or "of an unknown version"}; the definition asks for {asked_python}.') + reported = found.get('packages') if isinstance(found.get('packages'), dict) else {} + for name, version in definition['packages'].items(): + installed = reported.get(name) + if installed is None: + problems.append(f'{name} is not installed; the definition asks for {version}.') + elif installed != version: + problems.append(f'{name} is {installed}; the definition asks for {version}.') + if definition['device'] == 'cuda': + if 'torch' not in definition['packages']: + problems.append('The device is cuda but torch is not among the packages, so the check cannot see the GPU.') + else: + cuda = found.get('cuda') if isinstance(found.get('cuda'), dict) else {} + if cuda.get('available') is not True: + cause = f' ({cuda["error"]})' if cuda.get('error') else '' + problems.append(f'CUDA is not available to torch{cause}.') + return not problems, problems + + +def _is_report(found, definition): + """True when the probe printed the object it promises for this definition.""" + if not isinstance(found, dict) or not isinstance(found.get('python'), str): + return False + if not isinstance(found.get('executable'), str) or not isinstance(found.get('packages'), dict): + return False + if set(found['packages']) != set(definition['packages']): + return False + if not all(value is None or isinstance(value, str) for value in found['packages'].values()): + return False + if definition['device'] == 'cuda' and 'torch' in definition['packages']: + return isinstance(found.get('cuda'), dict) + return True + + +# ------------------------------------------------------------------ the probe + +def _error_text(data): + text = data.decode('utf-8', errors='replace').strip() if data else '' + return text[:ERROR_CHARACTERS] + + +def _with_error(sentence, error): + return f'{sentence} Its error output began: {error}' if error else sentence + + +def probe(interpreter, definition): + """Run PROBE in the interpreter; (found or None, [one problem] or []). + + The child runs with -I, an environment of PATH, LANG and a fresh HOME, + that HOME as its working directory, no input and a time limit of + CHECK_SECONDS. Its stdout and stderr are captured, never shown. + """ + request = json.dumps({'device': definition['device'], 'packages': definition['packages']}) + with tempfile.TemporaryDirectory(prefix='tuldok-check-') as scratch: + environment = {'PATH': '/usr/bin:/bin', 'LANG': 'C.UTF-8', 'HOME': scratch} + try: + done = subprocess.run([interpreter, '-I', '-c', PROBE, request], cwd=scratch, env=environment, + stdin=subprocess.DEVNULL, capture_output=True, timeout=CHECK_SECONDS) + except subprocess.TimeoutExpired as exc: + return None, [_with_error(f'The check did not finish within {CHECK_SECONDS} seconds.', + _error_text(exc.stderr))] + except OSError as exc: + return None, [f'The interpreter could not be started: {exc.strerror or exc}.'] + error = _error_text(done.stderr) + if done.returncode != 0: + return None, [_with_error(f'The check exited with status {done.returncode}.', error)] + try: + found = json.loads(done.stdout.decode('utf-8')) + except (UnicodeDecodeError, ValueError): + found = None + if not _is_report(found, definition): + return None, [_with_error('The check printed something other than the report it should print.', error)] + return found, [] + + +# ------------------------------------------------------------------ records + +def reference_of(text): + """'environments/' for a bare name or a reference; ProjectError not-found for anything else.""" + name = text[len(DIRECTORY) + 1:] if text.startswith(DIRECTORY + '/') else text + if not documents.is_name(name): + raise store.ProjectError(f'{text!r} is not an environment name or a reference such as environments/.', + 'not-found', references=[text]) + return documents.reference(DIRECTORY, name) + + +def _name(reference): + return reference_of(reference)[len(DIRECTORY) + 1:] + + +def _definition(project, reference): + """The decoded environment document; ProjectError not-found when there is none (or it is removed).""" + row = project._execute("SELECT document FROM {schema}.definitions " + "WHERE directory = 'environments' AND name = %s AND NOT removed", + (_name(reference),)).fetchone() + if row is None: + raise store.ProjectError(f'There is no environment {reference}.', 'not-found', references=[reference]) + return row[0] + + +def _record(project, name): + row = project._execute(_SELECT + ' WHERE name = %s', (name,)).fetchone() + return None if row is None else dict(zip(_COLUMNS, row)) + + +def _shown(reference, definition, record): + """One environment as the readers return it: the definition's asks, the record and its last check.""" + state = 'not-set-up' if record is None else 'ready' if record['ok'] else 'failing' + shown = {'reference': reference, 'title': definition.get('title'), 'state': state, + 'python': definition.get('python'), 'device': definition.get('device'), + 'packages': definition.get('packages'), 'installable': _requirements(definition) is not None, + 'origin': None, 'interpreter': None, 'recorded_at': None, 'checked_at': None, + 'ok': None, 'found': None, 'problems': []} + if record is not None: + shown.update({key: record[key] for key in ('origin', 'interpreter', 'recorded_at', 'checked_at', 'ok', 'found')}) + shown['problems'] = record['problems'] if record['problems'] is not None else ( + ['It has not been checked yet.'] if record['checked_at'] is None else []) + return shown + + +def listing(project): + """Every environment definition (not removed), sorted by reference, with its record and last check.""" + definitions = project._execute("SELECT name, document FROM {schema}.definitions " + "WHERE directory = 'environments' AND NOT removed ORDER BY name").fetchall() + records = {row[0]: dict(zip(_COLUMNS, row)) for row in project._execute(_SELECT).fetchall()} + return [_shown(documents.reference(DIRECTORY, name), document, records.get(name)) for name, document in definitions] + + +def show(project, reference): + """One environment as listing() shows it.""" + reference = reference_of(reference) + definition = _definition(project, reference) + return _shown(reference, definition, _record(project, _name(reference))) + + +def recorded(project): + """The references of every recorded environment, sorted.""" + return [documents.reference(DIRECTORY, name) + for (name,) in project._execute('SELECT name FROM {schema}.environments ORDER BY name').fetchall()] + + +def _require_record(project, reference): + record = _record(project, _name(reference)) + if record is None: + raise store.ProjectError(f'{reference} is not set up on this machine; connect an interpreter or run set-up.', + 'not-set-up', references=[reference]) + return record + + +def _store(project, name, interpreter, origin): + project._execute('''INSERT INTO {schema}.environments (name, interpreter, origin, recorded_at) + VALUES (%s, %s, %s, now()) + ON CONFLICT (name) DO UPDATE SET interpreter = EXCLUDED.interpreter, + origin = EXCLUDED.origin, recorded_at = EXCLUDED.recorded_at, + checked_at = NULL, ok = NULL, found = NULL, problems = NULL''', + (name, interpreter, origin)) + + +# ------------------------------------------------------------------ actions + +def check(project, reference): + """Run the check of a recorded environment, store its result and return the environment as show() does. + + Raises ProjectError only when no check can be attempted: there is no such + environment (not-found) or nothing is recorded for it (not-set-up). A + check that fails is returned with ok false and its problems. + """ + reference = reference_of(reference) + definition = _definition(project, reference) + record = _require_record(project, reference) + found, problems = probe(record['interpreter'], definition) + ok = False + if found is not None: + ok, problems = compare(definition, found) + project._execute('UPDATE {schema}.environments SET checked_at = now(), ok = %s, found = %s, problems = %s ' + 'WHERE name = %s AND interpreter = %s', + (ok, Jsonb(found) if found is not None else None, Jsonb(problems), record['name'], + record['interpreter'])) + return show(project, reference) + + +def connect(project, reference, interpreter): + """Record an existing interpreter for the environment (origin connected), then check it. + + interpreter must be an absolute path to an executable regular file; it is + stored exactly as given (a symbolic link is followed to test it, never + resolved in what is stored). The record is kept whether or not the check + passes. Raises ProjectError invalid for an unusable path. + """ + reference = reference_of(reference) + _definition(project, reference) + if not isinstance(interpreter, str) or not os.path.isabs(interpreter): + raise store.ProjectError(f'{interpreter!r} is not an absolute path; name the interpreter by its full path.', + 'invalid', references=[reference]) + if not os.path.isfile(interpreter) or not os.access(interpreter, os.X_OK): + raise store.ProjectError(f'{interpreter} is not an executable file.', 'invalid', references=[reference]) + _store(project, _name(reference), interpreter, 'connected') + return check(project, reference) + + +def _requirements(definition): + install = definition.get('install') + return install.get('requirements') if isinstance(install, dict) else None + + +def find_installer(): + """The uv program to run: $TULDOK_UV, else uv on PATH; None when there is neither. + + Raises ProjectError no-installer when TULDOK_UV names something that is not an executable file. + """ + named = os.environ.get(UV_VARIABLE) + if named: + if not os.path.isfile(named) or not os.access(named, os.X_OK): + raise store.ProjectError(f'{UV_VARIABLE} names {named}, which is not an executable file.', 'no-installer') + return named + return shutil.which('uv') + + +def _is_occupied(path): + """True when path exists and is anything but an empty directory.""" + if not os.path.lexists(path): + return False + if os.path.islink(path) or not os.path.isdir(path): + return True + with os.scandir(path) as entries: + return any(True for _ in entries) + + +def _remove(path): + if os.path.islink(path) or (os.path.lexists(path) and not os.path.isdir(path)): + os.unlink(path) + elif os.path.isdir(path): + shutil.rmtree(path) + + +def _log_tail(log): + try: + with open(log, 'rb') as handle: + lines = handle.read().decode('utf-8', errors='replace').splitlines() + except OSError: + return '' + return '\n'.join(lines[-LOG_LINES:]) + + +def _run_logged(command, cwd, handle): + """Run one install command with its output going to the open log; (ok, sentence).""" + handle.write(f'$ {shlex.join(command)}\n'.encode('utf-8')) + handle.flush() + try: + child = subprocess.Popen(command, cwd=cwd, stdin=subprocess.DEVNULL, stdout=handle, stderr=subprocess.STDOUT, + start_new_session=True) + except OSError as exc: + return False, f'{command[0]} could not be started: {exc.strerror or exc}.' + try: + status = child.wait(timeout=INSTALL_SECONDS) + except subprocess.TimeoutExpired: + try: + os.killpg(child.pid, signal.SIGKILL) + except ProcessLookupError: + pass + child.wait() + return False, f'{shlex.join(command[:3])} did not finish within {INSTALL_SECONDS // 60} minutes.' + if status != 0: + return False, f'{shlex.join(command[:3])} exited with status {status}.' + return True, '' + + +def set_up(project, reference, *, dry_run=False, replace=False): + """Install the environment its definition describes with uv, record it (origin installed) and check it. + + Commands, run in order with the code root as the working directory: + `uv venv --python `, then `uv pip install --python + /bin/python -r /` with --extra-index-url + for each install.index_urls. is /environments/; + their output goes to .log. With dry_run, returns the commands, the + target and the log path and does nothing else. + + Raises ProjectError: no-install (no install.requirements), no-installer + (no uv), target-exists (a non-empty target and replace false), and + install-failed (a command failed; the half-made target is removed, the log + kept, nothing recorded; the message ends with the last lines of the log). + """ + reference = reference_of(reference) + definition = _definition(project, reference) + requirements = _requirements(definition) + if requirements is None: + raise store.ProjectError(f'{reference} has no install.requirements, so Tuldok cannot install it; ' + 'connect an existing interpreter with connect instead.', 'no-install', + references=[reference]) + installer = find_installer() + if installer is None: + raise store.ProjectError(f'No installer was found: uv is not on PATH and {UV_VARIABLE} is not set.', + 'no-installer', references=[reference]) + state = project._state() + code_root = os.path.realpath(os.path.join(state['folder'], state['code_root'])) + name = _name(reference) + target = local.environment_target(project.project_id, name) + log = target + '.log' + install = definition['install'] + commands = [ + [installer, 'venv', '--python', definition['python'], target], + [installer, 'pip', 'install', '--python', os.path.join(target, 'bin', 'python'), + '-r', os.path.join(code_root, requirements), + *(part for url in install.get('index_urls', []) for part in ('--extra-index-url', url))], + ] + occupied = _is_occupied(target) + if occupied and not replace: + raise store.ProjectError(f'{target} already exists and is not empty; set it up again with replace ' + 'to remove it first.', 'target-exists', references=[reference]) + planned = {'reference': reference, 'commands': commands, 'cwd': code_root, 'target': target, 'log': log, + 'replaces': occupied, 'dry_run': dry_run} + if dry_run: + return planned + local.environments_directory(project.project_id, create=True) + if occupied: + _remove(target) + with open(log, 'wb') as handle: + for command in commands: + ok, sentence = _run_logged(command, code_root, handle) + if not ok: + break + if not ok: + _remove(target) + tail = _log_tail(log) + raise store.ProjectError(f'Setting up {reference} failed: {sentence} The target was removed; ' + f'the log is {log}.' + (f' Its last lines:\n{tail}' if tail else ''), + 'install-failed', references=[reference]) + _store(project, name, os.path.join(target, 'bin', 'python'), 'installed') + return {**planned, **check(project, reference)} + + +def disconnect(project, reference): + """Remove the record of an environment; an installed directory is kept and its path returned. + + Returns {reference, origin, interpreter, directory}, directory being the + installed environment's directory when the origin was installed, else + None. Raises ProjectError not-found or not-set-up. + """ + reference = reference_of(reference) + _definition(project, reference) + record = _require_record(project, reference) + forget(project._connection, project.schema, record['name']) + directory = None + if record['origin'] == 'installed': + directory = os.path.dirname(os.path.dirname(record['interpreter'])) + return {'reference': reference, 'origin': record['origin'], 'interpreter': record['interpreter'], + 'directory': directory} diff --git a/tuldok_project/graph.py b/tuldok_project/graph.py index 8ca9233b..555b5010 100644 --- a/tuldok_project/graph.py +++ b/tuldok_project/graph.py @@ -193,9 +193,14 @@ def _kind(reference, document): return document.get('kind') if isinstance(document, dict) else None -def states(definitions): +def states(definitions, local=None): """Return {reference: state} for every definition, by section 4.3 of the spec. + local, when given, maps environment references to the state this machine + records for them (ready, failing or not-set-up; spec-m5.md section 2) and + replaces the not-set-up computed for those environments. It applies to + environments only; no other definition's state depends on one. + cannot-rebuild and needs-work come from a definition's own earlier_work.rebuild or from anything it uses through input edges, directly or further up; the worse of the two wins. Other edges (environment, model, @@ -220,5 +225,9 @@ def states(definitions): if severity[user] < severity[reference]: severity[user] = severity[reference] pending.append(user) - return {reference: _CARRIED[severity[reference]] or _BASE_STATE.get(_kind(reference, document), 'none') - for reference, document in definitions.items()} + found = {reference: _CARRIED[severity[reference]] or _BASE_STATE.get(_kind(reference, document), 'none') + for reference, document in definitions.items()} + for reference, state in (local or {}).items(): + if reference in found and _kind(reference, definitions[reference]) == 'environment': + found[reference] = state + return found diff --git a/tuldok_project/local.py b/tuldok_project/local.py new file mode 100644 index 00000000..6c550def --- /dev/null +++ b/tuldok_project/local.py @@ -0,0 +1,41 @@ +"""Where a project keeps what belongs to this machine alone: its local home. + +Owns section 1 of docs/plans/definition-first-projects/spec-m5.md. The local +home of a project is $TULDOK_PROJECT_HOME//, with +TULDOK_PROJECT_HOME defaulting to ~/.local/share/tuldok/projects. Nothing in +it is part of the project folder. Environments that Tuldok installs go to +/environments//. Working out a path never creates anything; +a directory is made only when a caller asks for it with create=True. +""" +import os + +HOME_VARIABLE = 'TULDOK_PROJECT_HOME' +DEFAULT_HOME = os.path.join('~', '.local', 'share', 'tuldok', 'projects') +ENVIRONMENTS = 'environments' + + +def projects_home(): + """The directory that holds every project's local home, as an absolute path.""" + configured = os.environ.get(HOME_VARIABLE) or DEFAULT_HOME + return os.path.abspath(os.path.expanduser(configured)) + + +def home(project_id, *, create=False): + """The local home of one project; made (with its parents) when create is true.""" + path = os.path.join(projects_home(), project_id) + if create: + os.makedirs(path, exist_ok=True) + return path + + +def environments_directory(project_id, *, create=False): + """/environments, where installed environments go; made when create is true.""" + path = os.path.join(home(project_id), ENVIRONMENTS) + if create: + os.makedirs(path, exist_ok=True) + return path + + +def environment_target(project_id, name): + """/environments/: the directory an installed environment lives in. Creates nothing.""" + return os.path.join(environments_directory(project_id), name) diff --git a/tuldok_project/plan.py b/tuldok_project/plan.py index e3f80cbe..4ae9dfa6 100644 --- a/tuldok_project/plan.py +++ b/tuldok_project/plan.py @@ -4,11 +4,13 @@ function of the decoded definitions (reference -> document): it follows the input, environment and subject edges from the targets, but never out of a blocked step or into a blocked subject recipe, puts what it reaches in -graph.order, gives each step an action from graph.states, explains each blocked +graph.order, gives each step an action from graph.states (with the +environments' states recorded on this machine, spec-m5.md section 5: a ready +environment is not something to set up), explains each blocked step by its root causes, found over the whole graph (definitions whose own earlier_work.rebuild is no or needs-work), and adds up the figures the build steps declare in run.resources. build_plan reads the definitions from a Project's database copy -and calls it. Making a plan runs nothing and opens no file: no command, no +and the recorded environment states and calls it. Making a plan runs nothing and opens no file: no command, no estimate command, nothing on disk; an estimate is always null here. """ from collections import deque @@ -18,7 +20,7 @@ from .store import ProjectError BUILT_KINDS = ('dataset', 'recipe', 'step', 'benchmark') -ACTIONS = ('build', 'set-up', 'blocked') +ACTIONS = ('build', 'set-up', 'blocked', 'ready') RESOURCES = ('gpu', 'cpu_threads', 'memory_gb', 'wall_hours', 'disk_gb') CAUSE_LIMIT = 5 _CAUSE_LABELS = ('no', 'needs-work') @@ -138,7 +140,7 @@ def _subjects(document, states): def _action(kind, state): if kind == 'environment': - return 'set-up' if state == 'not-set-up' else None + return 'ready' if state == 'ready' else 'set-up' # not-set-up, or failing its last check if state == 'not-built': return 'build' if state in ('cannot-rebuild', 'needs-work'): @@ -153,9 +155,12 @@ def _total(steps, field): return round(math.fsum(numbers), 6), len(declared) - len(numbers) -def make_plan(definitions, targets, *, every=False): +def make_plan(definitions, targets, *, every=False, local=None): """The plan for targets over {reference: document}, as section 3 and 4 of spec-m4.md describe it. + local is graph.states' mapping of environment references to the state + recorded on this machine; without it every environment is not-set-up. + every adds every dataset, recipe, step and benchmark to the targets. A chart target is replaced by its benchmark; a model target adds nothing and a note saying so. Raises ValueError naming any target that is not a @@ -179,7 +184,7 @@ def make_plan(definitions, targets, *, every=False): notes.append(f'{reference} is a model; a model is not built, only the recipes that train it.') if reference not in resolved: resolved.append(reference) - states = graph.states(definitions) + states = graph.states(definitions, local) members = _closure(definitions, edges_from, states, [reference for reference in resolved if _kind(reference) != 'model']) members = {reference for reference in members if _kind(reference) not in ('model', 'chart')} @@ -233,4 +238,4 @@ def build_plan(project, targets, *, every=False): references=[reference]) if reference not in definitions: raise ProjectError(f'There is no definition {reference}.', 'not-found', references=[reference]) - return make_plan(definitions, targets, every=every) + return make_plan(definitions, targets, every=every, local=project._local_states()) diff --git a/tuldok_project/store.py b/tuldok_project/store.py index 8861af89..bd4e347b 100644 --- a/tuldok_project/store.py +++ b/tuldok_project/store.py @@ -14,6 +14,10 @@ Benchmark results (spec-m3.md) live in three more tables owned by result_rows: results files are part of what open compares and imports, and save writes them back when the database's summaries make a different text. +Which interpreter fulfils each environment on this machine (spec-m5.md) lives +in one more table owned by environments; the states reported here take the +environments' stored check results, and an environment's record goes when +its definition does. """ from dataclasses import dataclass import hashlib @@ -27,7 +31,7 @@ from metadata import connection_info -from . import check, documents, folder as folder_reader, graph, result_rows, results +from . import check, documents, environments, folder as folder_reader, graph, result_rows, results from .documents import Problem PROJECT_ID = re.compile(r'^[a-f0-9]{32}$') @@ -71,7 +75,9 @@ class ProjectError(Exception): code is one of: invalid (the folder or the edit breaks the format; problems lists why), conflict (files changed on disk where the database has unsaved - edits), bound-elsewhere, busy, in-use, changed-on-disk, not-found. + edits), bound-elsewhere, busy, in-use, changed-on-disk, not-found; and for + environments (environments.py): not-set-up (nothing is recorded for it), + no-install, no-installer, target-exists, install-failed. references names the definitions concerned. """ @@ -306,7 +312,7 @@ def _schema_exists(self): def _create_schema(self): self._connection.execute(sql.SQL('CREATE SCHEMA IF NOT EXISTS {}').format(sql.Identifier(self.schema))) - for statement in (*_TABLES, *_MIGRATIONS): + for statement in (*_TABLES, *environments.TABLES, *_MIGRATIONS): self._execute(statement) def _state(self): @@ -321,6 +327,13 @@ def _documents(self, *, removed=True): rows = self._execute(f'SELECT {_REFERENCE_SQL}, document FROM {{schema}}.definitions{where}').fetchall() return dict(rows) + def _local_states(self): + """{reference: state} of the environments recorded on this machine, for graph.states(local=...).""" + return environments.recorded_states(self._connection, self.schema) + + def _states(self, *, removed=True): + return graph.states(self._documents(removed=removed), self._local_states()) + def _merged_definitions(self): """{reference: folder.Definition} for every row not removed, decoded from the exact text.""" rows = self._execute(f'SELECT {_REFERENCE_SQL}, text FROM {{schema}}.definitions WHERE NOT removed').fetchall() @@ -432,6 +445,8 @@ def _import(self, root, rows, on_conflict, results_on_disk, recorded_results): directory, name = documents.parse_reference(reference) if directory == 'benchmarks': result_rows.remove_benchmark(self._connection, self.schema, name) + if directory == environments.DIRECTORY: + environments.forget(self._connection, self.schema, name) for reference in take: directory, name = documents.parse_reference(reference) if directory == 'benchmarks' and reference in merged: @@ -483,14 +498,14 @@ def summary(self): state = self._state() rows = self._execute('SELECT kind, count(*) FROM {schema}.definitions WHERE NOT removed GROUP BY kind').fetchall() states = {} - for value in graph.states(self._documents(removed=False)).values(): + for value in self._states(removed=False).values(): states[value] = states.get(value, 0) + 1 return {'project_id': state['project_id'], 'name': state['name'], 'folder': state['folder'], 'code_root': state['code_root'], 'kinds': dict(sorted(rows)), 'states': dict(sorted(states.items()))} def definitions(self, kind=None): """One row per definition, sorted by reference: reference, kind, title, state, unsaved, removed.""" - states = graph.states(self._documents()) + states = self._states() query = f'SELECT {_REFERENCE_SQL}, kind, title, unsaved, removed FROM {{schema}}.definitions' rows = (self._execute(query + ' WHERE kind = %s', (kind,)) if kind is not None else self._execute(query)).fetchall() return [{'reference': reference, 'kind': row_kind, 'title': title, 'state': states[reference], @@ -510,14 +525,14 @@ def definition(self, reference): used_by = self._execute('SELECT from_ref, role FROM {schema}.edges WHERE to_ref = %s ORDER BY from_ref, role', (reference,)).fetchall() return {'reference': reference, 'kind': kind, 'title': title, 'text': text, 'document': document, - 'state': graph.states(self._documents())[reference], 'unsaved': unsaved, 'removed': removed, + 'state': self._states()[reference], 'unsaved': unsaved, 'removed': removed, 'uses': [{'reference': target, 'role': role} for target, role in uses], 'used_by': [{'reference': source, 'role': role} for source, role in used_by]} def graph(self): """The definitions not removed, with kind and state, and the edges between them.""" nodes = self._execute(f'SELECT {_REFERENCE_SQL}, kind FROM {{schema}}.definitions WHERE NOT removed').fetchall() - states = graph.states(self._documents(removed=False)) + states = self._states(removed=False) edges = self._execute('SELECT from_ref, to_ref, role FROM {schema}.edges ORDER BY 1, 2, 3').fetchall() return {'nodes': [{'reference': reference, 'kind': kind, 'state': states[reference]} for reference, kind in sorted(nodes)], @@ -606,7 +621,11 @@ def add(severity, where, pointer, message): result_rows.prune(self._connection, self.schema, name, document) def remove_definition(self, reference): - """Mark a definition removed, to be deleted from disk by save(); refused while anything uses it.""" + """Mark a definition removed, to be deleted from disk by save(); refused while anything uses it. + + Removing an environment also drops its record on this machine (an + installed directory is left where it is). + """ directory, name = _split(reference) with self._connection.transaction(): row = self._execute('SELECT file_sha256 FROM {schema}.definitions ' @@ -628,6 +647,8 @@ def remove_definition(self, reference): self._write_edges([], [reference]) if directory == 'benchmarks': result_rows.remove_benchmark(self._connection, self.schema, name) + if directory == environments.DIRECTORY: + environments.forget(self._connection, self.schema, name) def save(self): """Write unsaved definitions and changed results files, and delete the files of removed ones. From fe2dd56ae4ad274538e236108bef2e373f940b48 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 12 Nov 2026 00:43:36 -0700 Subject: [PATCH 018/131] docs(plan): milestone 6 spec for building Co-Authored-By: Claude Fable 5.2 --- .../definition-first-projects/spec-m6.md | 165 ++++++++++++++++++ 1 file changed, 165 insertions(+) create mode 100644 docs/plans/definition-first-projects/spec-m6.md diff --git a/docs/plans/definition-first-projects/spec-m6.md b/docs/plans/definition-first-projects/spec-m6.md new file mode 100644 index 00000000..f9a505f4 --- /dev/null +++ b/docs/plans/definition-first-projects/spec-m6.md @@ -0,0 +1,165 @@ +# Implementation spec: milestone 6, build + +This continues the earlier specs in this folder. Section 1 of [spec-m1-m2.md](spec-m1-m2.md) (rules for implementers) applies unchanged. The milestone changes no existing Tuldok file outside `tuldok_project/`, `tests/`, `docs/` and `examples/`. + +**Owner decision, 2026-11-12:** spec, code and tests, and one tiny real end-to-end build on the GPU as the acceptance run. That run is done by the orchestrating session, not by an implementing agent. Agents run only stand-in commands that train nothing and never use the GPU. + +**Done when:** on the example project in `examples/tiny-project/`, with the owner's two existing environments connected, `build` makes a tiny dataset, trains a tiny model on the GPU while `progress` shows its progress lines, benchmarks it, and `chart` draws the result; a second `build` does nothing because everything is built; and after a change to the recipe's settings the recipe and the benchmark show as out of date. + +## 1. Decisions + +- **The build is a foreground command.** `python -m tuldok_project build` makes the plan, asks for confirmation, runs the steps one after another and exits. There is no background service in this milestone; the queue is the command's own loop. Serving builds from the Tuldok app comes with milestone 7. +- **The launcher is new code in `tuldok_project/`**, not a change to `recipe_process.py`. That file's custodian is bound to the old recipe documents and is used by catalog mode; changing it risks code this plan does not own. The new launcher keeps its safety rules (section 3). This replaces the "reuse the custodian" note in section 6 of the first spec. +- **Every process of a run carries its run id.** The launcher sets `TULDOK_RUN_ID` in the child's environment. Descendants inherit it, so Tuldok can find and stop anything a run left behind, even after its own process died. +- **The project lock is not held while a step runs.** The build opens the project to plan and to record, and closes it while a command is executing, so `progress`, `runs` and `list` work during a build. + +## 2. The code a run sees + +`tuldok.json` gains an optional field: + +| Field | Type | Rule | +| --- | --- | --- | +| `code_paths` | array | 1 to 64 paths relative to the code root, in normal form, no repeats; the parts of the repository a run needs. Absent means the whole code root | + +`snapshot.prepare(code_root, code_paths, *, home) -> Snapshot`: + +1. The code root must be inside a Git work tree; otherwise refuse and say a scratch run is the only option. +2. `commit` is `git rev-parse HEAD`. The run is **clean** when `git status --porcelain --untracked-files=no -- ` prints nothing. +3. A dirty tree is refused, naming up to ten changed files, unless the caller asked for a scratch run. +4. For a clean run the snapshot directory is `/code//`. If it does not exist it is made by `git archive -- ` extracted into a temporary directory beside it, made read-only, then renamed into place. It is shared by every run at that commit. The path of the code root inside the repository is preserved, so the snapshot's code root is `/`. +5. A scratch run uses the code root in place and has `scratch` true. + +`snapshot.changed_since(code_root, commit) -> set of paths` is `git diff --name-only HEAD` plus the paths `git status --porcelain --untracked-files=no` reports, relative to the code root; used for the out-of-date state. + +Git is run with `git -C `, a fixed argument list, no shell, `GIT_OPTIONAL_LOCKS=0`, and a 60 second limit. + +## 3. The launcher + +`launcher.run(argv, *, cwd, env, run_id, directory, limits, on_tick=None) -> Outcome` starts one command and stays with it until every process of the run is gone. + +- **Start:** the child gets a new session, standard input from `/dev/null`, standard output and error appended to `/stdout.log` and `/stderr.log`, and `PR_SET_PDEATHSIG` set to `SIGKILL` so it dies if the launcher does. The launcher makes itself a child subreaper first, so orphaned descendants are reparented to it and can be reaped. +- **Environment:** exactly what the caller passes, plus `TULDOK_RUN_ID`. +- **While it runs,** every half second: has the child exited; is the wall-time limit passed; does `/cancel` exist. Every five seconds: is the size of `` over the disk limit. `on_tick` is called with the elapsed seconds. +- **Stopping** (limit passed, cancel, or the launcher receiving `SIGINT` or `SIGTERM`): `SIGTERM` to the child's process group, up to ten seconds of grace, then `SIGKILL` to the group. +- **After the child has exited, always:** find every process of this user whose environment contains `TULDOK_RUN_ID=` (reading `/proc//environ`), kill them, reap, and repeat until none is left or ten seconds have passed. +- **Outcome:** `state` is `succeeded` (exit status 0, nothing forced), `failed` (non-zero exit), `timed-out`, `over-disk`, `cancelled`, or `unknown` (a process of the run could not be stopped). It also carries the exit status, the elapsed seconds, the number of stray processes that had to be killed, and the directory's final size. A run that left strays behind after a zero exit is still `succeeded`, with the count recorded. + +`launcher.strays(run_id) -> list of pids` and `launcher.stop_strays(run_id)` do the search and kill alone, for a run whose launcher is gone. + +`launcher.progress(directory) -> dict` reads at most the last 8 KiB of each log, without following links, and returns `stdout` and `stderr` as text (invalid bytes replaced, control characters other than newline and tab removed), their total sizes, and `event`: the last complete standard-output line in the existing closed format `{"format": "tuldok_progress_v1", "stage", "completed", "total", "metrics"}` with the same bounds as today (stage and up to eight metric names match `[A-Za-z0-9][A-Za-z0-9_.-]{0,63}`, `0 <= completed <= total <= 1000000`, metrics finite numbers, lines over 4096 bytes ignored), or null. + +## 4. Runs and products + +```sql +CREATE TABLE plans ( + id text PRIMARY KEY, created_at timestamptz NOT NULL, + targets jsonb NOT NULL, steps jsonb NOT NULL, scratch boolean NOT NULL); + +CREATE TABLE runs ( + id text PRIMARY KEY, + reference text NOT NULL, subject text NOT NULL DEFAULT '', -- a benchmark's subject name, else '' + plan_id text NOT NULL, + state text NOT NULL, -- queued, running, succeeded, failed, timed-out, over-disk, cancelled, unknown + scratch boolean NOT NULL, commit text NOT NULL, + definition text NOT NULL, -- the definition file's text as run + settings text, -- the settings file's text as run, when the step has one + inputs jsonb NOT NULL, -- input name -> {reference, run_id, output} + environment jsonb, -- {reference, interpreter, found} + argv jsonb NOT NULL, env jsonb NOT NULL, + directory text NOT NULL, -- /runs/ + owner_pid integer, owner_boot text, + queued_at timestamptz NOT NULL, started_at timestamptz, finished_at timestamptz, + exit_status integer, seconds double precision, bytes bigint, strays integer, + problem text); + +CREATE TABLE products ( + run_id text PRIMARY KEY, + reference text NOT NULL, subject text NOT NULL DEFAULT '', + directory text NOT NULL, -- /output + outputs jsonb NOT NULL, -- output name -> {path, role, bytes} + current boolean NOT NULL); +CREATE UNIQUE INDEX products_current ON products (reference, subject) WHERE current; +``` + +A run directory holds `output/` (what `{output}` names), `settings.json` when the definition has inline `settings`, the two logs, and `cancel` when cancellation was asked for. A product is a succeeded run's `output/`; it stays where it was written. Making a product current makes the previous one for the same reference and subject not current. Nothing is deleted in this milestone. + +**A run that was left `queued` or `running`** by a build whose process is gone (its `owner_pid` is not running, or `owner_boot` is not this boot) becomes `unknown` the next time builds are looked at, with a problem saying so. It is never restarted. `stop RUN` kills its strays. + +## 5. States + +Added to the states a `Project` reports, through the same `local` argument as environments: + +| State | When | +| --- | --- | +| `running` | it has a `queued` or `running` run | +| `built` | it has a current product, and none of the conditions for `out-of-date` holds | +| `out-of-date` | it has a current product, and: the definition's text differs from the run's; or its settings file's text differs; or an input's current product is not the run recorded in `inputs`, or that input has none; or the run was not a scratch run and one of the definition's `sources` (or a path under one) is in `snapshot.changed_since(code root, run commit)` | +| `failed` | it has no current product and its latest run ended `failed`, `timed-out`, `over-disk` or `unknown` | + +A scratch product is `built` with a mark that it is a scratch product; it never becomes out of date because of code. A benchmark has one product per subject: it is `built` when every subject that would run has a current product and none is out of date, `not-built` when none has one, and `out-of-date` otherwise. `cannot-rebuild` and `needs-work` are unchanged and take precedence only when there is no current product. + +`plan` gains the action `built` for a step that is `built`, which is not counted as work; an `out-of-date` or `failed` step is `build`, and the text says why. + +## 6. Running a step + +`builds.execute(project_folder, plan, *, confirm, extra_env=None)` does, for each step in order: + +1. **Environment steps:** check the environment again. If it is not `ready`, stop the build and say to set it up or connect it. +2. **`built` steps:** skip. +3. **`build` steps**, once per subject for a benchmark: + - Resolve placeholders: `{output}` is `/output` (created empty); `{settings}` is `/settings.json` for inline `settings` or `/`; `{inputs.}` is the input's current product directory, or the named output's path inside it; `{subject.name}` is the subject's name; `{subject}` is the subject's `argument` with `{recipe}` replaced by that recipe's current product directory, or the subject's name when it has no `argument`. + - `argv[0]` of `python` becomes the environment's recorded interpreter. Any other program is looked up on `PATH`. + - The child's environment is: `PATH`, `HOME`, `USER`, `LOGNAME`, `LANG`, `LC_ALL` and `TZ` from the caller where set; `PYTHONDONTWRITEBYTECODE=1` and `PYTHONUNBUFFERED=1`; `CUDA_VISIBLE_DEVICES` set to the empty string unless the step declares `gpu: true`, in which case it is left as the caller has it; then the definition's `env` with placeholders filled; then `extra_env`. + - The working directory is the snapshot's code root (or the code root for a scratch run). + - Limits: `wall_hours` as declared, default 24; `disk_gb` as declared, default 50. + - A step that declares `gpu: true` holds an exclusive lock on `$TULDOK_PROJECT_HOME/gpu.lock` while it runs, waiting for it if another build has it. + - The run row is written before the command starts and updated when it ends. The project is closed while the command runs. +4. **After a succeeded run:** every declared output must exist under `output/`; a missing one makes the run `failed` with a problem naming it. For a benchmark, the output with role `results` is read as a `tuldok_results_v1` values file for that benchmark and subject and imported; a file that fails the check makes the run `failed`, with the first problems in the run's `problem`. Then the product is recorded and made current. +5. **Any other outcome** stops the build. Later steps are not run. + +`confirm` is called with the plan before anything runs and returns true to proceed. A plan with a blocked target is refused before `confirm`. + +## 7. Estimates + +`builds.estimate(project_folder, targets)` runs, for each `build` step in the plan that has `run.estimate.command`, that command through the launcher from the same snapshot, with a five minute limit, `{output}` naming a fresh path that does not exist, and the definition's `env`. A step whose estimate command or `env` names an input that has no current product is skipped with that reason. The command's standard output must be one JSON object; its numeric `disk_bytes`, `wall_seconds` and `items` are stored in `estimates(reference PRIMARY KEY, definition_sha256, values jsonb, measured_at)` and shown by `plan` beside the declared figures, marked as estimates, for as long as the definition's text is unchanged. + +## 8. Command line + +| Command | Does | +| --- | --- | +| `build FOLDER TARGET... [--all] [--scratch] [--yes] [--env NAME=VALUE]...` | prints the plan, asks to proceed unless `--yes`, runs it; prints one line when each step starts and ends, with the run id; exit status 0 when every step succeeded or was already built, 1 otherwise | +| `runs FOLDER [REFERENCE]` | the runs, newest first: id, reference, subject, state, started, seconds | +| `run FOLDER RUN` | one run: its row, its outputs, and the last progress event | +| `progress FOLDER RUN [--follow]` | the progress event and the log tails; `--follow` repeats every two seconds until the run ends | +| `cancel FOLDER RUN` | asks a running run to stop by creating its `cancel` file | +| `stop FOLDER RUN` | for a run whose builder is gone: kills its strays and marks it `unknown` | +| `products FOLDER [REFERENCE]` | current products: reference, subject, run, size, directory, scratch | +| `estimate FOLDER TARGET...` | section 7 | + +A run may be named by its id or an unambiguous prefix of at least six characters. `--json` applies to `runs`, `run`, `progress`, `products` and `estimate`. + +## 9. The example project + +`examples/tiny-project/`, with `project/` (the folder) and `code/` (its code root, `code_root` `../code`): + +| Definition | What it does | +| --- | --- | +| `environments/cpu`, `environments/gpu` | Python 3.12 with numpy 2.3.5, and Python 3.14 with torch 2.14.0+cu132 and numpy 2.5.3: the versions of the two environments on the owner's machine. No `install` | +| `datasets/waves` | `python make_waves.py` writes a small `.npz` of noisy sine curves, with train and test splits, from a fixed seed; a second or two on the CPU | +| `models/small-net` | a three-layer network in `net.py` | +| `recipes/small-net-a` | `python train.py` fits it for a number of updates from its settings, printing a `tuldok_progress_v1` line every 50 updates; needs a GPU and refuses to run without CUDA; about a minute | +| `benchmarks/held-out` | `python bench.py` scores one subject on the test split and writes a `tuldok_results_v1` file with a per-case error and a time per case; subjects are `small-net-a` and a `predict-zero` baseline | +| `charts/held-out-ranking`, `charts/held-out-tradeoff` | ranking of the error, and error against time | + +The scripts are short and plain, with no dependencies beyond numpy and torch. A `README.md` says how to connect the two environments and build. + +## 10. Slices + +| Slice | Files | Depends on | +| --- | --- | --- | +| T11 launcher | `tuldok_project/launcher.py`, `tests/test_tuldok_project_launcher.py` | nothing | +| T12 snapshot | `tuldok_project/snapshot.py`, `code_paths` in the `tuldok.json` schema, checker and contract, `tests/test_tuldok_project_snapshot.py` | nothing | +| T13 builds | `tuldok_project/builds.py`, hooks in `store.py`, `plan.py`, the commands, `tests/test_tuldok_project_builds.py`, a "Building" section in the contract | T11, T12 | +| T14 example and estimates | `examples/tiny-project/`, section 7, its command and tests | T13 | + +Tests use stand-in commands run by the test interpreter: scripts that print progress lines, write files, sleep, ignore `SIGTERM`, fork children that outlive them, or fill the disk limit. No test uses a GPU, torch, or the network. From 4191d46ff23d5c6943463e40421dbc316af7aaf8 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 12 Nov 2026 00:50:49 -0700 Subject: [PATCH 019/131] feat(project): run from a read-only copy of a commit snapshot.prepare copies the code a run needs from HEAD into a read-only directory under the project's local home, once per commit and set of code paths, and refuses a tree with uncommitted changes to tracked files unless a scratch run is asked for. tuldok.json gains code_paths, the parts of the repository a run needs. changed_since lists what changed after a commit, for telling when a product is out of date. Co-Authored-By: Claude Fable 5.2 --- docs/contracts/project-folder.md | 5 + .../definition-first-projects/spec-m6.md | 4 +- tests/test_tuldok_project_check.py | 50 +++ tests/test_tuldok_project_snapshot.py | 381 ++++++++++++++++++ tuldok_project/check.py | 47 ++- tuldok_project/schemas/project.schema.json | 11 + tuldok_project/snapshot.py | 331 +++++++++++++++ 7 files changed, 816 insertions(+), 13 deletions(-) create mode 100644 tests/test_tuldok_project_snapshot.py create mode 100644 tuldok_project/snapshot.py diff --git a/docs/contracts/project-folder.md b/docs/contracts/project-folder.md index afba5076..1909acaf 100644 --- a/docs/contracts/project-folder.md +++ b/docs/contracts/project-folder.md @@ -81,6 +81,11 @@ holding one JSON object. The checker refuses: | `id` | yes | 32 lowercase hexadecimal characters; make a new one per project | | `name` | yes | 1 to 120 characters | | `code_root` | no | the path from the project folder to the root of the code that commands run in; default `.`; not empty and not absolute; may contain `..` | +| `code_paths` | no | 1 to 64 paths relative to the code root, in normal form (no `..`, no empty or `.` parts, no trailing `/`), each listed once and each existing under the code root; default: the whole code root | + +`code_paths` names the parts of the repository a run needs: a run sees a +read-only copy of only those paths at the commit it runs from, and only +changes to tracked files under them stop a run that is not a scratch run. The **code root** is the directory that commands run in and that code paths in definitions are relative to. It must be an existing directory. A folder kept at diff --git a/docs/plans/definition-first-projects/spec-m6.md b/docs/plans/definition-first-projects/spec-m6.md index f9a505f4..2546df5c 100644 --- a/docs/plans/definition-first-projects/spec-m6.md +++ b/docs/plans/definition-first-projects/spec-m6.md @@ -26,12 +26,12 @@ This continues the earlier specs in this folder. Section 1 of [spec-m1-m2.md](sp 1. The code root must be inside a Git work tree; otherwise refuse and say a scratch run is the only option. 2. `commit` is `git rev-parse HEAD`. The run is **clean** when `git status --porcelain --untracked-files=no -- ` prints nothing. 3. A dirty tree is refused, naming up to ten changed files, unless the caller asked for a scratch run. -4. For a clean run the snapshot directory is `/code//`. If it does not exist it is made by `git archive -- ` extracted into a temporary directory beside it, made read-only, then renamed into place. It is shared by every run at that commit. The path of the code root inside the repository is preserved, so the snapshot's code root is `/`. +4. For a clean run the snapshot directory is `/code//`, or `/code/-/` when there are `code_paths`, the digest being the first 12 hex characters of the SHA-256 of the sorted paths joined by newlines. If it does not exist it is made by `git archive -- ` extracted into a temporary directory beside it, made read-only, then renamed into place. It is shared by every run at that commit with those paths. The path of the code root inside the repository is preserved, so the snapshot's code root is `/`. 5. A scratch run uses the code root in place and has `scratch` true. `snapshot.changed_since(code_root, commit) -> set of paths` is `git diff --name-only HEAD` plus the paths `git status --porcelain --untracked-files=no` reports, relative to the code root; used for the out-of-date state. -Git is run with `git -C `, a fixed argument list, no shell, `GIT_OPTIONAL_LOCKS=0`, and a 60 second limit. +Git is run with `git -C `, a fixed argument list, no shell, `GIT_OPTIONAL_LOCKS=0`, and a 60 second limit (ten minutes for `git archive`). `prepare` takes a `scratch` keyword, and errors are `SnapshotError` with a code. ## 3. The launcher diff --git a/tests/test_tuldok_project_check.py b/tests/test_tuldok_project_check.py index 7dda2fe8..d487d64d 100644 --- a/tests/test_tuldok_project_check.py +++ b/tests/test_tuldok_project_check.py @@ -538,6 +538,56 @@ def test_no_code_skips_lookups_but_not_path_form(self): self.assertProblem(check_folder(self.project, code=False), 'recipes/stepper-k1.json', '/run/sources/0') +class ProjectCodePaths(FixtureCopy): + """The optional code_paths of tuldok.json (spec-m6.md section 2).""" + + def test_existing_paths_pass(self): + self.edit('tuldok.json', '/code_paths', ['lab', 'configs/stepper.json', 'requirements.txt']) + self.assertClean(check_folder(self.project)) + + def test_must_list_one_to_sixty_four_paths(self): + for label, value in (('empty', []), ('too many', [f'p{i}' for i in range(65)]), ('not a list', 'lab'), + ('not strings', [3])): + with self.subTest(label): + self.setUp() + self.edit('tuldok.json', '/code_paths', value) + pointer = '/code_paths/0' if label == 'not strings' else '/code_paths' + self.assertProblem(check_folder(self.project, code=False), 'tuldok.json', pointer) + + def test_paths_must_be_in_normal_form(self): + for value in ('lab//train.py', './lab', 'lab/', '/abs', '../code/lab'): + with self.subTest(value): + self.setUp() + self.edit('tuldok.json', '/code_paths', ['configs', value]) + self.assertProblem(check_folder(self.project), 'tuldok.json', '/code_paths/1') + + def test_paths_are_listed_once(self): + self.edit('tuldok.json', '/code_paths', ['lab', 'configs', 'lab']) + problem = self.assertProblem(check_folder(self.project), 'tuldok.json', '/code_paths/2') + self.assertIn('more than once', problem.message) + + def test_missing_path_is_an_error(self): + self.edit('tuldok.json', '/code_paths', ['lab', 'missing']) + problem = self.assertProblem(check_folder(self.project), 'tuldok.json', '/code_paths/1') + self.assertIn('does not exist', problem.message) + + def test_path_may_not_escape_through_a_symbolic_link(self): + outside = self.base / 'outside' + outside.mkdir() + os.symlink(outside, self.code / 'escape') + self.edit('tuldok.json', '/code_paths', ['escape']) + self.assertProblem(check_folder(self.project), 'tuldok.json', '/code_paths/0') + + def test_no_code_skips_lookups_but_not_form_or_repeats(self): + self.edit('tuldok.json', '/code_paths', ['missing']) + self.assertClean(check_folder(self.project, code=False)) + self.edit('tuldok.json', '/code_paths', ['missing', 'missing', 'a/../b']) + report = check_folder(self.project, code=False) + self.assertProblem(report, 'tuldok.json', '/code_paths/1', alone=False) + self.assertProblem(report, 'tuldok.json', '/code_paths/2', alone=False) + self.assertEqual(len(report.problems), 2) + + # ------------------------------------------------------------ 2.8 results class ResultsFiles(FixtureCopy): diff --git a/tests/test_tuldok_project_snapshot.py b/tests/test_tuldok_project_snapshot.py new file mode 100644 index 00000000..e0ad4622 --- /dev/null +++ b/tests/test_tuldok_project_snapshot.py @@ -0,0 +1,381 @@ +"""The code a run sees: snapshots of one commit, scratch runs, and what changed since a commit. + +Each test builds a small Git repository in a temporary directory whose path +contains a space, with user.name and user.email set in that repository only, +and points TULDOK_PROJECT_HOME at a temporary directory so nothing is written +under the owner's home. Snapshots are read-only; the clean-up makes them +writable again before the temporary directory is removed. +""" +import hashlib +import io +import os +from pathlib import Path +import stat +import subprocess +import sys +import tarfile +import tempfile +import unittest +from unittest import mock + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) + +from tuldok_project import local, snapshot # noqa: E402 +from tuldok_project.snapshot import SnapshotError # noqa: E402 + +PROJECT_ID = '0123456789abcdef0123456789abcdef' + + +class Repository(unittest.TestCase): + """A fresh repository with a committed tree under 'Linux Software/repo', and an empty local home.""" + + def setUp(self): + directory = tempfile.TemporaryDirectory() + self.addCleanup(directory.cleanup) + self.addCleanup(self._make_writable, Path(directory.name)) + self.base = Path(directory.name) / 'Linux Software' + patcher = mock.patch.dict(os.environ, {local.HOME_VARIABLE: str(self.base / 'tuldok home')}) + patcher.start() + self.addCleanup(patcher.stop) + self.home = Path(local.home(PROJECT_ID)) + self.repo = self.base / 'repo' + self.repo.mkdir(parents=True) + self.git('init', '-q', '-b', 'main') + self.git('config', 'user.name', 'Test') + self.git('config', 'user.email', 'test@example.invalid') + self.git('config', 'commit.gpgsign', 'false') + self.write('README.md', 'top\n') + self.write('lab/train.py', 'print("train")\n') + self.write('lab/run.sh', '#!/bin/sh\necho run\n', executable=True) + self.write('lab/data dir/table one.csv', 'a,b\n1,2\n') + self.write('configs/k1.json', '{}\n') + self.write('other/notes.txt', 'unrelated\n') + os.symlink('train.py', self.repo / 'lab' / 'link.py') + self.commit('first') + + @staticmethod + def _make_writable(root): + for current, directories, files in os.walk(root): + for name in directories: + path = os.path.join(current, name) + if not os.path.islink(path): + os.chmod(path, 0o755) + if root.exists(): + os.chmod(root, 0o755) + + def git(self, *arguments, cwd=None): + environment = {key: value for key, value in os.environ.items() if not key.startswith('GIT_')} + environment.update(GIT_CONFIG_GLOBAL=os.devnull, GIT_CONFIG_NOSYSTEM='1') + done = subprocess.run(['git', '-C', str(cwd or self.repo), *arguments], capture_output=True, text=True, + env=environment, check=True) + return done.stdout.strip() + + def write(self, relative, text, *, executable=False): + path = self.repo / relative + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(text) + if executable: + path.chmod(0o755) + + def commit(self, message): + self.git('add', '-A') + self.git('commit', '-q', '-m', message) + return self.git('rev-parse', 'HEAD') + + def head(self): + return self.git('rev-parse', 'HEAD') + + def prepare(self, code_root=None, code_paths=None, **options): + return snapshot.prepare(code_root or self.repo, code_paths, home=self.home, **options) + + +class Prepare(Repository): + def test_clean_repository_makes_a_snapshot_of_the_commit(self): + made = self.prepare() + commit = self.head() + self.assertEqual(made.commit, commit) + self.assertFalse(made.scratch) + self.assertEqual(made.directory, str(self.home / 'code' / commit)) + self.assertEqual(made.code_root, made.directory) + self.assertEqual(made.prefix, '') + root = Path(made.code_root) + self.assertEqual((root / 'lab' / 'train.py').read_text(), 'print("train")\n') + self.assertEqual((root / 'lab' / 'data dir' / 'table one.csv').read_text(), 'a,b\n1,2\n') + self.assertTrue((root / 'other' / 'notes.txt').exists()) + self.assertEqual(os.readlink(root / 'lab' / 'link.py'), 'train.py') + self.assertEqual(sorted(p.name for p in (self.home / 'code').iterdir()), [commit], 'no partial directory left') + + def test_code_root_in_a_subdirectory_keeps_the_repository_layout(self): + made = self.prepare(self.repo / 'lab') + self.assertEqual(made.prefix, 'lab') + self.assertEqual(made.code_root, os.path.join(made.directory, 'lab')) + self.assertTrue((Path(made.code_root) / 'train.py').is_file()) + self.assertEqual(sorted(os.listdir(made.directory)), ['lab'], 'only the code root is extracted') + + def test_code_paths_limit_what_is_extracted(self): + made = self.prepare(code_paths=['lab/train.py', 'configs']) + root = Path(made.code_root) + self.assertTrue((root / 'lab' / 'train.py').is_file()) + self.assertTrue((root / 'configs' / 'k1.json').is_file()) + self.assertFalse((root / 'lab' / 'run.sh').exists()) + self.assertFalse((root / 'other').exists()) + self.assertFalse((root / 'README.md').exists()) + + def test_code_paths_are_relative_to_a_code_root_in_a_subdirectory(self): + made = self.prepare(self.repo / 'lab', ['data dir']) + self.assertTrue((Path(made.code_root) / 'data dir' / 'table one.csv').is_file()) + self.assertFalse((Path(made.code_root) / 'train.py').exists()) + + def test_code_path_missing_from_the_commit_is_a_clear_error(self): + with self.assertRaises(SnapshotError) as caught: + self.prepare(code_paths=['nowhere']) + self.assertEqual(caught.exception.code, 'git-failed') + self.assertIn('archive', str(caught.exception)) + self.assertIn('nowhere', str(caught.exception)) + self.assertEqual(os.listdir(self.home / 'code'), [], 'the partial directory is removed') + + def test_malformed_code_paths_are_refused(self): + for value in (['../x'], ['a//b'], [], ['lab', 'lab'], ['/abs']): + with self.subTest(value), self.assertRaises(SnapshotError) as caught: + self.prepare(code_paths=value) + self.assertEqual(caught.exception.code, 'invalid') + + def test_snapshot_is_read_only(self): + made = self.prepare() + root = Path(made.code_root) + mode = lambda path: stat.S_IMODE(os.lstat(path).st_mode) # noqa: E731 + self.assertEqual(mode(root), 0o555) + self.assertEqual(mode(root / 'lab'), 0o555) + self.assertEqual(mode(root / 'lab' / 'data dir'), 0o555) + self.assertEqual(mode(root / 'lab' / 'train.py'), 0o444) + self.assertEqual(mode(root / 'lab' / 'run.sh'), 0o555) + if os.geteuid() != 0: + with self.assertRaises(PermissionError): + (root / 'lab' / 'new.py').write_text('x') + + def test_dirty_tracked_file_is_refused_and_named(self): + self.write('lab/train.py', 'print("changed")\n') + with self.assertRaises(SnapshotError) as caught: + self.prepare() + self.assertEqual(caught.exception.code, 'dirty') + self.assertEqual(caught.exception.files, ['lab/train.py']) + self.assertIn('lab/train.py', str(caught.exception)) + self.assertFalse((self.home / 'code').exists(), 'nothing is made for a refused run') + + def test_staged_and_deleted_files_are_dirty_and_named_relative_to_the_code_root(self): + self.write('lab/data dir/table one.csv', 'changed\n') + self.git('add', 'lab/data dir/table one.csv') + (self.repo / 'lab' / 'run.sh').unlink() + with self.assertRaises(SnapshotError) as caught: + self.prepare(self.repo / 'lab') + self.assertEqual(sorted(caught.exception.files), ['data dir/table one.csv', 'run.sh']) + + def test_refusal_names_at_most_ten_files(self): + for index in range(12): + self.write(f'many/f{index:02}.txt', 'a\n') + self.commit('many') + for index in range(12): + self.write(f'many/f{index:02}.txt', 'b\n') + with self.assertRaises(SnapshotError) as caught: + self.prepare() + message = str(caught.exception) + self.assertIn('many/f09.txt', message) + self.assertNotIn('many/f10.txt', message) + self.assertIn('and 2 more', message) + self.assertEqual(len(caught.exception.files), 12) + + def test_changes_outside_the_code_paths_do_not_make_the_run_dirty(self): + self.write('other/notes.txt', 'changed\n') + made = self.prepare(code_paths=['lab']) + self.assertTrue((Path(made.code_root) / 'lab' / 'train.py').is_file()) + with self.assertRaises(SnapshotError): + self.prepare() + + def test_untracked_file_is_ignored(self): + self.write('lab/scratch.py', 'untracked\n') + made = self.prepare() + self.assertFalse((Path(made.code_root) / 'lab' / 'scratch.py').exists()) + + def test_scratch_uses_the_code_root_in_place_and_writes_nothing(self): + self.write('lab/train.py', 'print("changed")\n') + with mock.patch.object(snapshot.subprocess, 'run', wraps=subprocess.run) as run: + made = self.prepare(self.repo / 'lab', scratch=True) + self.assertTrue(made.scratch) + self.assertEqual(made.code_root, str(self.repo / 'lab')) + self.assertIsNone(made.directory) + self.assertEqual(made.commit, self.head()) + self.assertFalse(self.home.exists(), 'a scratch run does not touch the snapshot directory') + self.assertFalse(any('archive' in call.args[0] for call in run.call_args_list)) + + def test_existing_snapshot_is_reused_without_running_git_archive(self): + first = self.prepare() + with mock.patch.object(snapshot.subprocess, 'run', wraps=subprocess.run) as run: + second = self.prepare() + self.assertEqual(first, second) + commands = [call.args[0] for call in run.call_args_list] + self.assertTrue(commands, 'Git is still asked for the commit') + self.assertFalse(any('archive' in command for command in commands), commands) + + def test_different_code_paths_at_one_commit_make_different_snapshots(self): + commit = self.head() + narrow = self.prepare(code_paths=['configs']) + wide = self.prepare(code_paths=['configs', 'lab']) + self.assertNotEqual(narrow.directory, wide.directory) + self.assertRegex(os.path.basename(narrow.directory), f'^{commit}-[0-9a-f]{{12}}$') + self.assertFalse((Path(narrow.code_root) / 'lab').exists()) + self.assertTrue((Path(wide.code_root) / 'lab' / 'train.py').is_file()) + whole = self.prepare() + self.assertEqual(os.path.basename(whole.directory), commit) + self.assertEqual(len(os.listdir(self.home / 'code')), 3) + + def test_same_code_paths_in_another_order_share_one_snapshot(self): + first = self.prepare(code_paths=['lab', 'configs']) + with mock.patch.object(snapshot.subprocess, 'run', wraps=subprocess.run) as run: + second = self.prepare(code_paths=['configs', 'lab']) + self.assertEqual(first.directory, second.directory) + self.assertFalse(any('archive' in call.args[0] for call in run.call_args_list)) + digest = hashlib.sha256(b'configs\nlab').hexdigest()[:12] + self.assertEqual(os.path.basename(first.directory), f'{self.head()}-{digest}') + + def test_leftover_partial_directory_is_not_taken_for_a_snapshot(self): + commit = self.head() + leftover = self.home / 'code' / f'.partial-{commit}-crashed' + leftover.mkdir(parents=True) + (leftover / 'half.txt').write_text('half') + made = self.prepare() + self.assertEqual(made.directory, str(self.home / 'code' / commit)) + self.assertTrue((Path(made.code_root) / 'lab' / 'train.py').is_file()) + self.assertFalse((Path(made.code_root) / 'half.txt').exists()) + + def test_build_that_loses_the_race_uses_the_existing_snapshot(self): + commit = self.head() + real_rename = os.rename + renames = [] + + def rename_after_another_build(source, target): + # Another build finishes first: its complete snapshot is in place before ours is renamed. + renames.append(source) + if len(renames) == 1: + snapshot.prepare(self.repo, None, home=self.home) + return real_rename(source, target) + + with mock.patch.object(snapshot.os, 'rename', side_effect=rename_after_another_build): + made = self.prepare() + self.assertEqual(made.directory, str(self.home / 'code' / commit)) + self.assertEqual(len(renames), 2, 'both builds tried to put their snapshot in place') + self.assertEqual(os.listdir(self.home / 'code'), [commit], 'the losing build discarded its directory') + self.assertTrue((Path(made.code_root) / 'lab' / 'train.py').is_file()) + + def test_directory_outside_a_work_tree_is_refused(self): + outside = self.base / 'not a repo' + outside.mkdir() + with self.assertRaises(SnapshotError) as caught: + self.prepare(outside) + self.assertEqual(caught.exception.code, 'not-in-git') + self.assertIn('scratch', str(caught.exception)) + made = self.prepare(outside, scratch=True) + self.assertTrue(made.scratch) + self.assertEqual(made.commit, '') + + def test_repository_without_a_commit_is_a_clear_error(self): + empty = self.base / 'empty repo' + empty.mkdir() + self.git('init', '-q', cwd=empty) + with self.assertRaises(SnapshotError) as caught: + self.prepare(empty) + self.assertEqual(caught.exception.code, 'no-commit') + self.assertTrue(str(caught.exception).startswith('Git could not read the commit HEAD names')) + + def test_archive_entries_outside_the_snapshot_are_refused(self): + cases = (('../escape.txt', tarfile.REGTYPE), ('/abs.txt', tarfile.REGTYPE), + ('dev', tarfile.CHRTYPE), ('out', tarfile.SYMTYPE)) + for index, (name, kind) in enumerate(cases): + with self.subTest(name): + target = self.base / f'extract {index}' + target.mkdir() + archive = tempfile.TemporaryFile() + self.addCleanup(archive.close) + with tarfile.open(fileobj=archive, mode='w') as tar: + member = tarfile.TarInfo(name) + member.type = kind + if kind == tarfile.SYMTYPE: + member.linkname = '../../outside' + tar.addfile(member, None if kind != tarfile.REGTYPE else io.BytesIO(b'')) + archive.seek(0) + with self.assertRaises(SnapshotError) as caught: + snapshot._extract(archive, str(target)) + self.assertEqual(caught.exception.code, 'unsafe-archive') + self.assertFalse((self.base / 'escape.txt').exists()) + + def test_symbolic_link_inside_the_archive_is_kept(self): + made = self.prepare(code_paths=['lab']) + link = Path(made.code_root) / 'lab' / 'link.py' + self.assertTrue(link.is_symlink()) + self.assertEqual(link.read_text(), 'print("train")\n') + + def test_git_failure_is_an_error_naming_its_purpose(self): + with mock.patch.object(snapshot.subprocess, 'run', + side_effect=subprocess.TimeoutExpired(['git'], snapshot.GIT_SECONDS)): + with self.assertRaises(SnapshotError) as caught: + self.prepare() + self.assertEqual(caught.exception.code, 'not-in-git') + with mock.patch.object(snapshot.subprocess, 'run', side_effect=FileNotFoundError('git')): + with self.assertRaises(SnapshotError) as caught: + snapshot._git(self.repo, 'read the commit', 'rev-parse', 'HEAD') + self.assertIn('read the commit', str(caught.exception)) + self.assertIn('not found', str(caught.exception)) + + def test_git_is_run_without_a_shell_with_locks_off_and_a_time_limit(self): + with mock.patch.object(snapshot.subprocess, 'run', wraps=subprocess.run) as run: + self.prepare() + for call in run.call_args_list: + command = call.args[0] + self.assertIsInstance(command, list) + self.assertEqual(command[:3], ['git', '-C', command[2]]) + self.assertFalse(call.kwargs.get('shell')) + self.assertEqual(call.kwargs['env']['GIT_OPTIONAL_LOCKS'], '0') + self.assertEqual(call.kwargs['timeout'], 600 if 'archive' in command else 60) + self.assertTrue(any('archive' in call.args[0] for call in run.call_args_list)) + + +class ChangedSince(Repository): + def test_no_change(self): + self.assertEqual(snapshot.changed_since(self.repo, self.head()), set()) + + def test_committed_change_relative_to_the_code_root(self): + before = self.head() + self.write('lab/train.py', 'print("new")\n') + self.write('other/notes.txt', 'changed\n') + self.commit('second') + self.assertEqual(snapshot.changed_since(self.repo, before), {'lab/train.py', 'other/notes.txt'}) + self.assertEqual(snapshot.changed_since(self.repo / 'lab', before), {'train.py'}) + + def test_uncommitted_change_to_a_tracked_file(self): + before = self.head() + self.write('lab/data dir/table one.csv', 'changed\n') + self.write('lab/untracked.py', 'new\n') + self.write('other/notes.txt', 'changed\n') + self.assertEqual(snapshot.changed_since(self.repo / 'lab', before), {'data dir/table one.csv'}) + + def test_renamed_file_names_both_paths(self): + before = self.head() + self.git('mv', 'lab/train.py', 'lab/fit.py') + self.assertEqual(snapshot.changed_since(self.repo / 'lab', before), {'train.py', 'fit.py'}) + self.commit('rename') + self.assertEqual(snapshot.changed_since(self.repo / 'lab', before), {'train.py', 'fit.py'}) + + def test_commit_git_no_longer_has(self): + with self.assertRaises(SnapshotError) as caught: + snapshot.changed_since(self.repo, 'f' * 40) + self.assertEqual(caught.exception.code, 'unknown-commit') + self.assertIn('f' * 40, str(caught.exception)) + + def test_commit_must_be_a_full_id(self): + for value in ('HEAD', '--output=x', 'abc'): + with self.subTest(value), self.assertRaises(SnapshotError) as caught: + snapshot.changed_since(self.repo, value) + self.assertEqual(caught.exception.code, 'invalid') + + +if __name__ == '__main__': + unittest.main() diff --git a/tuldok_project/check.py b/tuldok_project/check.py index 80b0626f..3314b4e2 100644 --- a/tuldok_project/check.py +++ b/tuldok_project/check.py @@ -5,7 +5,8 @@ that are neither layout (folder.py), single-field syntax (documents.py and the schemas) nor summary-file content (results.py): kind against directory, cards, placeholders in context, benchmark uniqueness rules, references and named -outputs, charts against their benchmark, cycles, and paths into the code root. +outputs, charts against their benchmark, cycles, and paths into the code root +(in definitions and in the code_paths of tuldok.json). Problems are collected, never raised, so one bad file never hides another. """ from dataclasses import dataclass, field @@ -60,6 +61,8 @@ def add(severity, path, pointer, message): unsound = {problem.path for problem in problems if problem.severity == 'error'} code_root = _code_root(project, read.root, add) if code and project is not None else None + if project is not None: + check_project_code_paths(project, code_root, add) for definition in read.definitions: if definition.document is not None: check_code_paths(definition, code_root, add) @@ -204,19 +207,41 @@ def check_code_paths(definition, code_root, add): document, path = definition.document, definition.path missing = 'warning' if 'earlier_work' in document else 'error' for pointer, value in _code_paths(document): + if isinstance(value, str): + _check_code_path(value, code_root, path, pointer, missing, add) + + +def check_project_code_paths(project, code_root, add): + """Report tuldok.json code_paths that are malformed, repeated, escape the code root or do not exist (None skips lookups).""" + paths = project.get('code_paths') + if not isinstance(paths, list): + return # absent means the whole code root; a wrong type is a schema problem + seen = set() + for index, value in enumerate(paths): if not isinstance(value, str): continue - wrong = documents.relative_path_problem(value) - if wrong: - add('error', path, pointer, f'The path {value!r} {wrong}.') - continue - if code_root is None: + pointer = documents.pointer('code_paths', index) + if value in seen: + add('error', folder_reader.PROJECT_FILE, pointer, + f'The code path {value!r} is listed more than once; list each path once.') continue - resolved = os.path.realpath(os.path.join(code_root, value)) - if resolved != code_root and not resolved.startswith(code_root + os.sep): - add('error', path, pointer, f'The path {value!r} leads outside the code root through a symbolic link; point at a file inside it.') - elif not os.path.exists(resolved): - add(missing, path, pointer, f'The path {value!r} does not exist under the code root; fix the path or add the file.') + seen.add(value) + _check_code_path(value, code_root, folder_reader.PROJECT_FILE, pointer, 'error', add) + + +def _check_code_path(value, code_root, path, pointer, missing, add): + """Report one path relative to the code root: its form, then (unless code_root is None) where it leads.""" + wrong = documents.relative_path_problem(value) + if wrong: + add('error', path, pointer, f'The path {value!r} {wrong}.') + return + if code_root is None: + return + resolved = os.path.realpath(os.path.join(code_root, value)) + if resolved != code_root and not resolved.startswith(code_root + os.sep): + add('error', path, pointer, f'The path {value!r} leads outside the code root through a symbolic link; point at a file inside it.') + elif not os.path.exists(resolved): + add(missing, path, pointer, f'The path {value!r} does not exist under the code root; fix the path or add the file.') # ----------------------------------------------------------- across files diff --git a/tuldok_project/schemas/project.schema.json b/tuldok_project/schemas/project.schema.json index 768bc388..b9903669 100644 --- a/tuldok_project/schemas/project.schema.json +++ b/tuldok_project/schemas/project.schema.json @@ -29,6 +29,17 @@ "minLength": 1, "pattern": "^[^/]", "description": "a relative path from the project folder to the code root, never absolute" + }, + "code_paths": { + "type": "array", + "minItems": 1, + "maxItems": 64, + "description": "1 to 64 paths relative to the code root: the parts of the repository a run needs", + "items": { + "type": "string", + "minLength": 1, + "maxLength": 1024 + } } } } diff --git a/tuldok_project/snapshot.py b/tuldok_project/snapshot.py new file mode 100644 index 00000000..4efc98e7 --- /dev/null +++ b/tuldok_project/snapshot.py @@ -0,0 +1,331 @@ +"""The code a run sees: a read-only copy of one commit, or the code root in place for a scratch run. + +Owns section 2 of docs/plans/definition-first-projects/spec-m6.md. prepare() +finds the commit the code root is at, refuses a tree whose tracked files under +the code paths differ from that commit (unless a scratch run was asked for), +and makes /code// (or -/ +when code_paths limits it) from `git archive` once: extracted into +a temporary directory beside it, made read-only, then renamed into place, so a +directory under that name is always a complete snapshot of exactly those paths +and is shared by every run at that commit with those paths. The snapshot keeps the repository's layout; the +snapshot's code root is /. changed_since() lists what changed under the code root since a +commit, for the out-of-date state. Git is only read, never written: every +call is `git -C ` with a fixed argument list, no shell, optional locks +off, literal pathspecs and a time limit. +""" +from dataclasses import dataclass +import hashlib +import os +import re +import shutil +import stat +import subprocess +import tarfile +import tempfile + +from . import documents + +CODE = 'code' +GIT_SECONDS = 60 +ARCHIVE_SECONDS = 600 +DIGEST_CHARACTERS = 12 +MAX_CODE_PATHS = 64 +NAMED_CHANGES = 10 +_COMMIT = re.compile(r'^(?:[0-9a-f]{40}|[0-9a-f]{64})$') +_PARTIAL = '.partial-' +# Variables that would point Git at another repository, index or object store than the one under -C. +_REPOSITORY_VARIABLES = ( + 'GIT_DIR', 'GIT_WORK_TREE', 'GIT_INDEX_FILE', 'GIT_OBJECT_DIRECTORY', 'GIT_ALTERNATE_OBJECT_DIRECTORIES', + 'GIT_COMMON_DIR', 'GIT_NAMESPACE', 'GIT_PREFIX', 'GIT_IMPLICIT_WORK_TREE', 'GIT_GRAFT_FILE', + 'GIT_REPLACE_REF_BASE', 'GIT_NO_REPLACE_OBJECTS', 'GIT_SHALLOW_FILE', 'GIT_QUARANTINE_PATH', + 'GIT_CONFIG', 'GIT_CONFIG_PARAMETERS', 'GIT_CONFIG_COUNT', 'GIT_GLOB_PATHSPECS', 'GIT_NOGLOB_PATHSPECS', + 'GIT_ICASE_PATHSPECS', +) + + +class SnapshotError(Exception): + """The code for a run could not be prepared or compared; nothing was left half-made. + + code is one of: not-in-git (the code root is not inside a Git work tree; + only a scratch run can use it), no-commit (the repository has no commit + yet), dirty (tracked files under the code paths differ from the commit; + files names them, relative to the code root), unknown-commit (Git no longer + has the commit), invalid (bad code paths or commit id), git-failed (a Git command failed or timed out), unsafe-archive + (the archive held an entry that would land outside the snapshot). + """ + + def __init__(self, message, code, *, files=(), detail=''): + super().__init__(message) + self.code = code + self.files = list(files) + self.detail = detail + + +@dataclass(frozen=True) +class Snapshot: + """The code one run sees. + + code_root is the directory the command runs in: / for a + clean run, the code root itself for a scratch run. directory is + /code/ for a clean run and None for a scratch run. + commit is HEAD of the code root's repository ('' for a scratch run outside + Git); prefix is the code root's path inside the repository ('' at its top). + """ + commit: str + scratch: bool + code_root: str + directory: str | None + prefix: str + + +# ------------------------------------------------------------------- Git + +def _environment(): + environment = {key: value for key, value in os.environ.items() if key not in _REPOSITORY_VARIABLES} + environment['GIT_OPTIONAL_LOCKS'] = '0' + environment['GIT_LITERAL_PATHSPECS'] = '1' + environment['GIT_TERMINAL_PROMPT'] = '0' + environment['LC_ALL'] = 'C' + return environment + + +def _git(directory, purpose, *arguments, stdout=None, code='git-failed', seconds=GIT_SECONDS): + """Run `git -C directory arguments...` and return its standard output (bytes, or None when stdout is a file). + + purpose completes the sentence "Git could not ..." in the error raised on failure. + """ + command = ['git', '-C', os.fspath(directory), *arguments] + try: + done = subprocess.run(command, stdin=subprocess.DEVNULL, stdout=stdout or subprocess.PIPE, + stderr=subprocess.PIPE, env=_environment(), timeout=seconds, check=False) + except FileNotFoundError: + raise SnapshotError(f'Git could not {purpose}: the git program was not found on PATH.', 'git-failed') from None + except subprocess.TimeoutExpired: + raise SnapshotError(f'Git could not {purpose}: it did not finish within {seconds} seconds.', + 'git-failed') from None + if done.returncode != 0: + lines = done.stderr.decode('utf-8', 'replace').strip().splitlines() + first = lines[0].strip() if lines else f'exit status {done.returncode}' + raise SnapshotError(f'Git could not {purpose} in {directory}: {first}', code, detail=first) + return done.stdout + + +def _text(output): + return output.decode('utf-8', 'surrogateescape').rstrip('\n') + + +def _repository(code_root): + """Return (top level, prefix) of the work tree holding code_root; prefix is '' or ends without '/'.""" + try: + inside = _text(_git(code_root, 'tell whether the code root is in a work tree', 'rev-parse', '--is-inside-work-tree')) + except SnapshotError as exc: + inside, reason = 'false', exc.detail or str(exc) + else: + reason = 'it is inside a Git directory, not a work tree' + if inside != 'true': + raise SnapshotError(f'The code root {code_root} is not inside a Git work tree ({reason}); ' + f'only a scratch run can use it.', 'not-in-git') + top = _text(_git(code_root, 'find the top of the repository', 'rev-parse', '--show-toplevel')) + prefix = _text(_git(code_root, "find the code root's place in the repository", 'rev-parse', '--show-prefix')) + return top, prefix.rstrip('/') + + +def _head(code_root): + output = _git(code_root, 'read the commit HEAD names', 'rev-parse', '--verify', '--end-of-options', 'HEAD^{commit}', + code='no-commit') + return _text(output) + + +def _changed_tracked(code_root, pathspecs): + """Return the repository-relative paths of tracked files under pathspecs that differ from HEAD (staged or not).""" + output = _git(code_root, 'list changed tracked files', 'status', '--porcelain=v1', '-z', '--untracked-files=no', + '--no-renames', '--ignore-submodules=none', '--', *pathspecs) + entries = output.decode('utf-8', 'surrogateescape').split('\0') + paths, index = [], 0 + while index < len(entries): + entry = entries[index] + index += 1 + if len(entry) < 4: + continue + paths.append(entry[3:]) + if entry[0] in 'RC': # only without --no-renames; the original path follows + paths.append(entries[index]) + index += 1 + return paths + + +def _under(prefix, path): + """path (repository-relative) relative to the code root at prefix, or None when it is outside.""" + if not prefix: + return path + return path[len(prefix) + 1:] if path.startswith(prefix + '/') else None + + +# -------------------------------------------------------------- prepare + +def _validated(code_paths): + if code_paths is None: + return None + paths = list(code_paths) + if not 1 <= len(paths) <= MAX_CODE_PATHS: + raise SnapshotError(f'code_paths must list 1 to {MAX_CODE_PATHS} paths; it lists {len(paths)}.', 'invalid') + for value in paths: + wrong = documents.relative_path_problem(value) + if wrong: + raise SnapshotError(f'The code path {value!r} {wrong}.', 'invalid') + if len(set(paths)) != len(paths): + raise SnapshotError('code_paths names a path more than once; list each path once.', 'invalid') + return paths + + +def prepare(code_root, code_paths=None, *, home, scratch=False): + """Return the Snapshot a run at code_root sees; code_paths (relative to the code root) limits it, None is all. + + home is the project's local home (local.home). A clean run reuses or makes + /code//. A scratch run uses code_root in place and writes nothing. + Raises SnapshotError when the code cannot be prepared. + """ + code_root = os.path.abspath(os.fspath(code_root)) + paths = _validated(code_paths) + if scratch: + try: + _repository(code_root) + commit = _head(code_root) + except SnapshotError: + commit = '' # a scratch run needs no commit; outside Git it simply has none + return Snapshot(commit, True, code_root, None, '') + + top, prefix = _repository(code_root) + commit = _head(code_root) + changed = _changed_tracked(code_root, paths or ['.']) + if changed: + shown = [_under(prefix, path) or path for path in changed] + listed = ', '.join(shown[:NAMED_CHANGES]) + (f' and {len(shown) - NAMED_CHANGES} more' if len(shown) > NAMED_CHANGES else '') + raise SnapshotError(f'The code has changes that are not committed: {listed}. ' + f'Commit or discard them, or ask for a scratch run.', 'dirty', files=shown) + + directory = os.path.join(os.fspath(home), CODE, snapshot_name(commit, paths)) + if not os.path.isdir(directory): + _build(top, commit, _pathspecs(prefix, paths), directory) + snapshot_root = os.path.join(directory, prefix) if prefix else directory + return Snapshot(commit, False, snapshot_root, directory, prefix) + + +def snapshot_name(commit, code_paths): + """ for the whole code root; -.""" + if code_paths is None: + return commit + digest = hashlib.sha256('\n'.join(sorted(code_paths)).encode('utf-8', 'surrogateescape')).hexdigest() + return f'{commit}-{digest[:DIGEST_CHARACTERS]}' + + +def _pathspecs(prefix, paths): + """Repository-relative pathspecs for git archive run at the top level.""" + if paths is None: + return [prefix] if prefix else [] + return [f'{prefix}/{path}' if prefix else path for path in paths] + + +def _build(top, commit, pathspecs, directory): + """Make directory from `git archive commit -- pathspecs`, atomically; a concurrent build's result wins quietly.""" + parent = os.path.dirname(directory) + os.makedirs(parent, exist_ok=True) + # Partial names start with '.', so they are never a snapshot name ( or -). + partial = tempfile.mkdtemp(prefix=f'{_PARTIAL}{os.path.basename(directory)}-', dir=parent) + try: + with tempfile.TemporaryFile(dir=parent) as archive: + # commit is a full id from rev-parse; '--' keeps the paths from being read as options. + _git(top, f'archive commit {commit}', 'archive', '--format=tar', commit, '--', + *pathspecs, stdout=archive, seconds=ARCHIVE_SECONDS) + archive.seek(0) + _extract(archive, partial) + _make_read_only(partial) + try: + os.rename(partial, directory) + except OSError: + if not os.path.isdir(directory): + raise + # Another build put the same snapshot in place first; ours is discarded below. + else: + partial = None + finally: + if partial is not None: + _remove(partial) + + +def _safe_member(member, destination): + """tarfile filter: the data filter (nothing outside, no devices, links inside only), and no absolute names at all.""" + if member.name.startswith('/') or os.path.isabs(member.name): + raise tarfile.AbsolutePathError(member) # the data filter would strip the '/'; an archive of a commit never has one + if not (member.isfile() or member.isdir() or member.issym()): + raise tarfile.SpecialFileError(member) + return tarfile.data_filter(member, destination) + + +def _extract(archive, destination): + try: + with tarfile.open(fileobj=archive, mode='r:') as tar: + tar.extractall(destination, filter=_safe_member) + except tarfile.FilterError as exc: + raise SnapshotError(f'The archive of the commit holds an entry Tuldok will not extract: {exc}.', + 'unsafe-archive') from None + except tarfile.TarError as exc: + raise SnapshotError(f'The archive of the commit could not be read: {exc}.', 'git-failed') from None + + +def _make_read_only(root): + """Directories 0555; files 0444, or 0555 when the owner may execute them; links are left alone.""" + for current, directories, files in os.walk(root, topdown=False): + for name in files: + path = os.path.join(current, name) + mode = os.lstat(path).st_mode + if stat.S_ISREG(mode): + os.chmod(path, 0o555 if mode & stat.S_IXUSR else 0o444) + for name in directories: + path = os.path.join(current, name) + if not os.path.islink(path): + os.chmod(path, 0o555) + os.chmod(root, 0o555) + + +def _remove(root): + """Remove a (possibly read-only) directory tree that this module made.""" + if not os.path.lexists(root): + return + os.chmod(root, 0o755) + for current, directories, _files in os.walk(root): + for name in directories: + path = os.path.join(current, name) + if not os.path.islink(path): + os.chmod(path, 0o755) + shutil.rmtree(root) + + +# --------------------------------------------------------- changed_since + +def changed_since(code_root, commit): + """Return the paths, relative to code_root, changed since commit: committed up to HEAD, or not yet committed. + + Only tracked files count. Raises SnapshotError (unknown-commit) when Git + no longer has the commit. + """ + code_root = os.path.abspath(os.fspath(code_root)) + if not isinstance(commit, str) or not _COMMIT.match(commit): + raise SnapshotError(f'{commit!r} is not a full commit id.', 'invalid') + _top, prefix = _repository(code_root) + try: + _git(code_root, f'find commit {commit}', 'rev-parse', '--verify', '--quiet', '--end-of-options', + f'{commit}^{{commit}}') + except SnapshotError: + raise SnapshotError(f'The repository of {code_root} no longer has commit {commit} (a rebase or clean-up ' + f'may have removed it), so Tuldok cannot tell what changed since it.', + 'unknown-commit') from None + committed = _git(code_root, f'compare commit {commit} with HEAD', 'diff', '--name-only', '--no-renames', '-z', + '--relative', '--end-of-options', commit, 'HEAD', '--') + changed = {path for path in committed.decode('utf-8', 'surrogateescape').split('\0') if path} + for path in _changed_tracked(code_root, ['.']): + inside = _under(prefix, path) + if inside: + changed.add(inside) + return changed From e49635b9bd968968c18a580d23b0814713eb4162 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 12 Nov 2026 00:51:54 -0700 Subject: [PATCH 020/131] feat(project): run one command and stay until every process of it is gone launcher.run starts a command in its own session with its run id in the environment, watches wall time, disk use and a cancel file, stops it with SIGTERM then SIGKILL, and afterwards finds and kills anything still carrying the run id, reaping what it adopts as a subreaper. strays and stop_strays do the search alone for a run whose launcher is gone, and progress reads the log tails and the last tuldok_progress_v1 line. Co-Authored-By: Claude Fable 5.2 --- tests/test_tuldok_project_launcher.py | 463 ++++++++++++++++++++++ tuldok_project/launcher.py | 548 ++++++++++++++++++++++++++ 2 files changed, 1011 insertions(+) create mode 100644 tests/test_tuldok_project_launcher.py create mode 100644 tuldok_project/launcher.py diff --git a/tests/test_tuldok_project_launcher.py b/tests/test_tuldok_project_launcher.py new file mode 100644 index 00000000..40e0ee6b --- /dev/null +++ b/tests/test_tuldok_project_launcher.py @@ -0,0 +1,463 @@ +"""The launcher (spec-m6.md section 3): run, strays, stop_strays and progress. + +Stand-in commands are small Python scripts run by the test interpreter. The +module's intervals are shortened so the file runs in seconds. Every test +kills whatever carries its run id when it ends, pass or fail, using its own +/proc scan rather than the code under test, and the run tests check that the +test process is left with no zombie child. +""" +import json +import os +from pathlib import Path +import signal +import subprocess +import sys +import tempfile +import textwrap +import threading +import time +import unittest +from unittest import mock +import uuid + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) + +from tuldok_project import launcher # noqa: E402 + +FAST = {'WATCH_INTERVAL': 0.02, 'DISK_INTERVAL': 0.1, 'STOP_GRACE': 0.6, + 'SWEEP_LIMIT': 3.0, 'SWEEP_PAUSE': 0.02} +GENEROUS = {'wall_seconds': 30, 'disk_bytes': 10 ** 9} + + +def _carriers(run_id): + """Pids of live processes with exactly TULDOK_RUN_ID=, found independently of launcher.""" + needle = f'TULDOK_RUN_ID={run_id}'.encode() + found = [] + for name in os.listdir('/proc'): + if not name.isdigit() or int(name) == os.getpid(): + continue + try: + with open(f'/proc/{name}/stat', 'rb') as file: + state = file.read().rsplit(b')', 1)[1].split()[0] + with open(f'/proc/{name}/environ', 'rb') as file: + environ = file.read().split(b'\0') + except OSError: + continue + if state != b'Z' and needle in environ: + found.append(int(name)) + return found + + +def _kill_run(run_id): + for _ in range(100): + pids = _carriers(run_id) + if not pids: + return + for pid in pids: + try: + os.kill(pid, signal.SIGKILL) + except OSError: + pass + time.sleep(0.02) + + +def _zombie_children(): + zombies = [] + for name in os.listdir('/proc'): + if not name.isdigit(): + continue + try: + with open(f'/proc/{name}/stat', 'rb') as file: + fields = file.read().rsplit(b')', 1)[1].split() + except OSError: + continue + if fields[0] == b'Z' and int(fields[1]) == os.getpid(): + zombies.append(int(name)) + return zombies + + +def _alive(pid): + try: + with open(f'/proc/{pid}/stat', 'rb') as file: + return file.read().rsplit(b')', 1)[1].split()[0] not in (b'Z', b'X') + except OSError: + return False + + +class LauncherCase(unittest.TestCase): + def setUp(self): + patcher = mock.patch.multiple(launcher, **FAST) + patcher.start() + self.addCleanup(patcher.stop) + scratch = tempfile.TemporaryDirectory() + self.addCleanup(scratch.cleanup) + self.scratch = Path(scratch.name) + self.directory = self.scratch / 'run' + self.directory.mkdir() + self.run_id = 'test-' + uuid.uuid4().hex + self.addCleanup(_kill_run, self.run_id) + self.handlers = (signal.getsignal(signal.SIGINT), signal.getsignal(signal.SIGTERM)) + + def script(self, body): + path = self.scratch / f'command-{uuid.uuid4().hex[:8]}.py' + path.write_text(textwrap.dedent(body)) + return path + + def env(self): + return {'PATH': os.environ.get('PATH', '/usr/bin:/bin'), 'LANG': 'C.UTF-8', + 'PYTHONDONTWRITEBYTECODE': '1'} + + def run_script(self, body, *, limits=GENEROUS, on_tick=None, args=()): + outcome = launcher.run([sys.executable, str(self.script(body)), *args], + cwd=str(self.scratch), env=self.env(), run_id=self.run_id, + directory=str(self.directory), limits=limits, on_tick=on_tick) + self.assertEqual(_carriers(self.run_id), [], 'a process of the run outlived run()') + self.assertEqual(_zombie_children(), [], 'run() left a zombie child') + self.assertEqual((signal.getsignal(signal.SIGINT), signal.getsignal(signal.SIGTERM)), + self.handlers, 'signal handlers were not restored') + return outcome + + def log(self, name): + return (self.directory / f'{name}.log').read_text() + + def wait_for(self, path, timeout=10): + deadline = time.monotonic() + timeout + while not path.exists() or not path.read_text().strip(): + if time.monotonic() > deadline: + self.fail(f'{path.name} was never written') + time.sleep(0.01) + return int(path.read_text()) + + +class RunTests(LauncherCase): + def test_success_logs_and_environment(self): + outcome = self.run_script(''' + import json, os, sys + print('hello out') + print('hello err', file=sys.stderr) + print(json.dumps(sorted(os.environ))) + print(os.environ['TULDOK_RUN_ID']) + print(sys.stdin.read() == '') + ''') + self.assertEqual(outcome.state, 'succeeded') + self.assertEqual(outcome.exit_status, 0) + self.assertEqual(outcome.strays, 0) + self.assertGreater(outcome.bytes, 0) + lines = self.log('stdout').splitlines() + self.assertEqual(lines[0], 'hello out') + self.assertEqual(json.loads(lines[1]), sorted([*self.env(), 'TULDOK_RUN_ID'])) + self.assertEqual(lines[2], self.run_id) + self.assertEqual(lines[3], 'True') + self.assertEqual(self.log('stderr'), 'hello err\n') + + def test_logs_are_appended(self): + (self.directory / 'stdout.log').write_text('earlier\n') + self.run_script('print("later")') + self.assertEqual(self.log('stdout'), 'earlier\nlater\n') + + def test_new_session(self): + self.run_script('import os; print(os.getsid(0) == os.getpid())') + self.assertEqual(self.log('stdout'), 'True\n') + + def test_non_zero_exit(self): + outcome = self.run_script('import sys; sys.exit(3)') + self.assertEqual((outcome.state, outcome.exit_status), ('failed', 3)) + + def test_wall_time_limit(self): + started = time.monotonic() + outcome = self.run_script('import time; time.sleep(30)', + limits={'wall_seconds': 0.3, 'disk_bytes': 10 ** 9}) + self.assertEqual(outcome.state, 'timed-out') + self.assertEqual(outcome.exit_status, -signal.SIGTERM) + self.assertLess(time.monotonic() - started, 5) + + def test_disk_limit(self): + outcome = self.run_script(f''' + import os, time + os.makedirs({str(self.directory / 'output' / 'deep')!r}) + with open({str(self.directory / 'output' / 'deep' / 'big')!r}, 'wb') as file: + file.write(b'x' * 100000) + time.sleep(30) + ''', limits={'wall_seconds': 30, 'disk_bytes': 50000}) + self.assertEqual(outcome.state, 'over-disk') + self.assertGreaterEqual(outcome.bytes, 100000) + + def test_disk_over_at_exit_is_not_success(self): + outcome = self.run_script(f''' + with open({str(self.directory / 'big')!r}, 'wb') as file: + file.write(b'x' * 100000) + ''', limits={'wall_seconds': 30, 'disk_bytes': 50000}) + self.assertEqual((outcome.state, outcome.exit_status), ('over-disk', 0)) + + def test_cancel_file(self): + def tick(elapsed): + if elapsed > 0.2: + (self.directory / 'cancel').touch() + outcome = self.run_script('import time; time.sleep(30)', on_tick=tick) + self.assertEqual(outcome.state, 'cancelled') + + def test_on_tick_is_given_elapsed_seconds(self): + seen = [] + self.run_script('import time; time.sleep(0.3)', on_tick=seen.append) + self.assertTrue(seen) + self.assertEqual(seen, sorted(seen)) + + def test_on_tick_exception_stops_the_run(self): + def tick(elapsed): + if elapsed > 0.1: + raise RuntimeError('tick failed') + pid_file = self.scratch / 'pid' + with self.assertRaisesRegex(RuntimeError, 'tick failed'): + launcher.run([sys.executable, str(self.script(f''' + import os, time + open({str(pid_file)!r}, 'w').write(str(os.getpid())) + time.sleep(30) + '''))], cwd=str(self.scratch), env=self.env(), run_id=self.run_id, + directory=str(self.directory), limits=GENEROUS, on_tick=tick) + self.assertEqual(_carriers(self.run_id), []) + self.assertEqual(_zombie_children(), []) + self.assertEqual((signal.getsignal(signal.SIGINT), signal.getsignal(signal.SIGTERM)), self.handlers) + + def test_command_ignoring_sigterm_is_killed_after_grace(self): + started = time.monotonic() + outcome = self.run_script(''' + import signal, time + signal.signal(signal.SIGTERM, signal.SIG_IGN) + time.sleep(30) + ''', limits={'wall_seconds': 0.3, 'disk_bytes': 10 ** 9}) + self.assertEqual(outcome.state, 'timed-out') + self.assertEqual(outcome.exit_status, -signal.SIGKILL) + self.assertGreaterEqual(time.monotonic() - started, 0.3 + FAST['STOP_GRACE']) + + def test_child_outliving_the_command_is_a_stray(self): + pid_file = self.scratch / 'pid' + outcome = self.run_script(f''' + import os, time + if os.fork() == 0: + open({str(pid_file)!r}, 'w').write(str(os.getpid())) + time.sleep(30) + os._exit(0) + while not os.path.exists({str(pid_file)!r}): + time.sleep(0.01) + ''') + self.assertEqual(outcome.state, 'succeeded') + self.assertEqual(outcome.strays, 1) + self.assertFalse(_alive(int(pid_file.read_text()))) + + def test_grandchild_in_own_session_ignoring_sigterm(self): + pid_file = self.scratch / 'pid' + body = f''' + import os, signal, sys, time + if os.fork() == 0: + os.setsid() + if os.fork() == 0: + signal.signal(signal.SIGTERM, signal.SIG_IGN) + open({str(pid_file)!r} + '.tmp', 'w').write(str(os.getpid())) + os.rename({str(pid_file)!r} + '.tmp', {str(pid_file)!r}) + time.sleep(30) + os._exit(0) + os.wait() + while not os.path.exists({str(pid_file)!r}): + time.sleep(0.01) + if sys.argv[1] == 'stay': + time.sleep(30) + ''' + for mode, state in (('exit', 'succeeded'), ('stay', 'timed-out')): + with self.subTest(mode=mode): + pid_file.unlink(missing_ok=True) + outcome = self.run_script(body, args=(mode,), + limits={'wall_seconds': 1.0, 'disk_bytes': 10 ** 9}) + self.assertEqual(outcome.state, state) + grandchild = int(pid_file.read_text()) + self.assertFalse(_alive(grandchild)) + if mode == 'exit': + self.assertEqual(outcome.strays, 1) + + def test_sigterm_to_launcher_cancels_and_caller_continues(self): + for signum in (signal.SIGTERM, signal.SIGINT): + with self.subTest(signal=signum.name): + timer = threading.Timer(0.3, os.kill, (os.getpid(), signum)) + timer.start() + self.addCleanup(timer.cancel) + outcome = self.run_script('import time; time.sleep(30)') + timer.join() + self.assertEqual(outcome.state, 'cancelled') + self.assertEqual(outcome.exit_status, -signal.SIGTERM) + + def test_run_from_another_thread(self): + results = [] + thread = threading.Thread(target=lambda: results.append(launcher.run( + [sys.executable, '-c', 'print(1)'], cwd=str(self.scratch), env=self.env(), + run_id=self.run_id, directory=str(self.directory), limits=GENEROUS))) + thread.start() + thread.join(30) + self.assertEqual(results[0].state, 'succeeded') + self.assertEqual(_zombie_children(), []) + + def test_run_id_prefix_is_not_a_match(self): + neighbour = subprocess.Popen([sys.executable, '-c', 'import time; time.sleep(30)'], + env={**self.env(), 'TULDOK_RUN_ID': self.run_id + 'x'}) + self.addCleanup(neighbour.wait) + self.addCleanup(neighbour.kill) + outcome = self.run_script('print(1)') + self.assertEqual((outcome.state, outcome.strays), ('succeeded', 0)) + self.assertIsNone(neighbour.poll()) + + def test_prctl_failure_refuses_to_run(self): + def failing(option, argument): + raise OSError(1, 'refused') + with mock.patch.object(launcher, '_prctl', failing): + with self.assertRaises(OSError): + launcher.run([sys.executable, '-c', 'print(1)'], cwd=str(self.scratch), env=self.env(), + run_id=self.run_id, directory=str(self.directory), limits=GENEROUS) + self.assertFalse((self.directory / 'stdout.log').exists()) + + def test_pdeathsig_failure_in_child_raises(self): + real = launcher._prctl + + def failing_pdeathsig(option, argument): + if option == launcher.PR_SET_PDEATHSIG: + raise OSError(1, 'refused') + return real(option, argument) + with mock.patch.object(launcher, '_prctl', failing_pdeathsig): + with self.assertRaises(subprocess.SubprocessError): + launcher.run([sys.executable, '-c', 'print(1)'], cwd=str(self.scratch), env=self.env(), + run_id=self.run_id, directory=str(self.directory), limits=GENEROUS) + self.assertEqual(_zombie_children(), []) + + def test_bad_arguments(self): + good = dict(cwd=str(self.scratch), env=self.env(), run_id=self.run_id, + directory=str(self.directory), limits=GENEROUS) + for change in ({'limits': {'wall_seconds': 0, 'disk_bytes': 1}}, + {'limits': {'wall_seconds': 1, 'disk_bytes': 1.5}}, + {'limits': {'wall_seconds': 1}}, + {'run_id': ''}, {'run_id': 'a=b'}, + {'directory': str(self.scratch / 'missing')}): + with self.subTest(change=change), self.assertRaises(ValueError): + launcher.run([sys.executable, '-c', 'print(1)'], **{**good, **change}) + + +class StrayTests(LauncherCase): + def start_outside(self, run_id): + process = subprocess.Popen([sys.executable, '-c', 'import time; time.sleep(30)'], + env={**self.env(), 'TULDOK_RUN_ID': run_id}) + self.addCleanup(process.wait) + self.addCleanup(process.kill) + return process + + def test_strays_and_stop_strays(self): + process = self.start_outside(self.run_id) + deadline = time.monotonic() + 10 + while process.pid not in launcher.strays(self.run_id): # environ is set at exec + self.assertLess(time.monotonic(), deadline) + time.sleep(0.01) + self.assertEqual(launcher.strays(self.run_id), [process.pid]) + result = launcher.stop_strays(self.run_id) + self.assertEqual(result, {'killed': 1, 'remaining': []}) + self.assertEqual(process.wait(5), -signal.SIGKILL) + self.assertEqual(launcher.strays(self.run_id), []) + + def test_prefix_and_extension_do_not_match(self): + longer = self.start_outside(self.run_id + 'c') + self.addCleanup(_kill_run, self.run_id + 'c') + deadline = time.monotonic() + 10 + while longer.pid not in launcher.strays(self.run_id + 'c'): + self.assertLess(time.monotonic(), deadline) + time.sleep(0.01) + self.assertEqual(launcher.strays(self.run_id), []) + self.assertEqual(launcher.stop_strays(self.run_id), {'killed': 0, 'remaining': []}) + self.assertIsNone(longer.poll()) + + def test_run_id_is_checked(self): + for bad in ('', 'a\0b', 'a=b', 7): + with self.subTest(run_id=bad), self.assertRaises(ValueError): + launcher.strays(bad) + + +def event(**change): + value = {'format': 'tuldok_progress_v1', 'stage': 'train', 'completed': 5, 'total': 10, + 'metrics': {'loss': 0.5}} + value.update(change) + return json.dumps(value) + + +class ProgressTests(unittest.TestCase): + def setUp(self): + scratch = tempfile.TemporaryDirectory() + self.addCleanup(scratch.cleanup) + self.directory = Path(scratch.name) + + def write(self, name, data): + (self.directory / f'{name}.log').write_bytes(data if type(data) is bytes else data.encode()) + + def test_valid_event(self): + self.write('stdout', 'starting\n' + event() + '\n' + 'plain text\n') + self.write('stderr', 'a warning\n') + result = launcher.progress(str(self.directory)) + self.assertEqual(result['event'], json.loads(event())) + self.assertEqual(result['stderr'], 'a warning\n') + self.assertEqual(result['stderr_bytes'], 10) + self.assertEqual(result['stdout_bytes'], len(result['stdout'])) + + def test_invalid_events_are_skipped(self): + earlier = event(completed=1) + for bad in (event(completed=11), event(stage='-bad'), event(total=1000001), + event(metrics={f'm{i}': 1 for i in range(9)}), event(completed=True), + event(extra=1), event(format='other'), + event()[:-1] + ', "stage": "x"}', + event(metrics={'loss': 1}).replace('1}', 'NaN}'), 'not json', '[]'): + with self.subTest(line=bad): + self.write('stdout', earlier + '\n' + bad + '\n') + self.assertEqual(launcher.progress(str(self.directory))['event'], json.loads(earlier)) + + def test_over_long_line_is_ignored(self): + long_line = event(completed=9)[:-1] + ' ' * 4100 + '}' + self.write('stdout', event() + '\n' + long_line + '\n') + self.assertEqual(launcher.progress(str(self.directory))['event'], json.loads(event())) + + def test_incomplete_last_line_is_ignored(self): + self.write('stdout', event() + '\n' + event(completed=9)) + self.assertEqual(launcher.progress(str(self.directory))['event'], json.loads(event())) + + def test_missing_logs(self): + self.assertEqual(launcher.progress(str(self.directory)), + {'stdout': '', 'stderr': '', 'stdout_bytes': None, 'stderr_bytes': None, + 'event': None}) + self.assertEqual(launcher.progress(str(self.directory / 'absent'))['event'], None) + + def test_symbolic_link_is_not_followed(self): + target = self.directory / 'elsewhere.txt' + target.write_text(event() + '\n') + (self.directory / 'stdout.log').symlink_to(target) + result = launcher.progress(str(self.directory)) + self.assertEqual((result['stdout'], result['stdout_bytes'], result['event']), ('', None, None)) + linked = self.directory.parent / (self.directory.name + '-link') + linked.symlink_to(self.directory) + self.addCleanup(linked.unlink) + self.assertIsNone(launcher.progress(str(linked))['stdout_bytes']) + + def test_large_log_reads_only_the_tail(self): + data = ('x' * 99 + '\n') * 20000 + event() + '\n' + self.write('stdout', data) + with mock.patch('os.pread', wraps=os.pread) as pread: + result = launcher.progress(str(self.directory)) + self.assertTrue(all(call.args[1] <= 8192 for call in pread.call_args_list)) + self.assertEqual(result['stdout_bytes'], len(data)) + self.assertLessEqual(len(result['stdout'].encode()), 8192) + self.assertEqual(result['event'], json.loads(event())) + + def test_cut_first_line_is_not_an_event(self): + # The tail starts inside a long line whose remainder is itself a valid event. + data = 'y' * 300 + event() + '\n' + 'z' * (8192 - len(event()) - 2) + '\n' + self.assertEqual(len(data) - 8192, 300) # the tail begins exactly at the '{' + self.write('stdout', data) + self.assertIsNone(launcher.progress(str(self.directory))['event']) + + def test_text_is_sanitised(self): + self.write('stderr', b'ok\tline\n\x1b[31mred\x00\r\n\xff\xfe end\n') + self.assertEqual(launcher.progress(str(self.directory))['stderr'], + 'ok\tline\n[31mred\n�� end\n') + + +if __name__ == '__main__': + unittest.main() diff --git a/tuldok_project/launcher.py b/tuldok_project/launcher.py new file mode 100644 index 00000000..7822d7b1 --- /dev/null +++ b/tuldok_project/launcher.py @@ -0,0 +1,548 @@ +"""Run one build command and stay with it until every process it started is gone. + +Owns section 3 of docs/plans/definition-first-projects/spec-m6.md. run() starts +the command in a new session with PR_SET_PDEATHSIG set to SIGKILL and +TULDOK_RUN_ID= in its environment, watches the wall-time limit, the +disk limit and the run directory's cancel file, stops the process group when +one of them (or SIGINT or SIGTERM to this process) asks for it, and then +sweeps: every process of this user whose environment carries the run id, or +that is still in the command's process group or session, is killed and reaped +before run() returns. While a run is in progress this process is a child +subreaper, so descendants orphaned by the run are reparented here and reaped. +strays() and stop_strays() do the sweep alone for a run whose launcher is gone. +progress() reads the bounded tail of a run's two logs and its latest +tuldok_progress_v1 line. Linux only. +""" +import ctypes +from dataclasses import dataclass +import json +import math +import os +import re +import select +import signal +import stat +import subprocess +import threading +import time + +WATCH_INTERVAL = 0.5 # seconds between checks of exit, wall time and cancel +DISK_INTERVAL = 5.0 # seconds between measurements of the run directory +STOP_GRACE = 10.0 # seconds between SIGTERM and SIGKILL when a run is stopped +SWEEP_LIMIT = 10.0 # seconds the final sweep may take before the run is unknown +SWEEP_PAUSE = 0.05 # seconds between rounds of a sweep or a stop +LOG_TAIL = 8192 # bytes read from the end of each log by progress() +EVENT_LINE_LIMIT = 4096 # longer stdout lines are never progress events + +RUN_ID_VARIABLE = 'TULDOK_RUN_ID' +CANCEL_FILE = 'cancel' +LOGS = ('stdout', 'stderr') +STATES = ('succeeded', 'failed', 'timed-out', 'over-disk', 'cancelled', 'unknown') + +PR_SET_PDEATHSIG = 1 +PR_SET_CHILD_SUBREAPER = 36 +PR_GET_CHILD_SUBREAPER = 37 + +_RUN_ID = re.compile(r'[A-Za-z0-9][A-Za-z0-9_.-]{0,127}') +_NAME = re.compile(r'[A-Za-z0-9][A-Za-z0-9_.-]{0,63}') +_CONTROL = re.compile('[\x00-\x08\x0b-\x1f\x7f-\x9f]') + + +@dataclass(frozen=True) +class Outcome: + """How a run ended. exit_status is the Popen return code (negative for a + signal), or None when the command could not be reaped; strays counts the + processes the final sweep had to kill; bytes is the run directory's size.""" + state: str + exit_status: int | None + seconds: float + strays: int + bytes: int + + +# --- prctl ------------------------------------------------------------------ + +_libc = None +_subreaper_lock = threading.Lock() +_subreaper_users = 0 +_subreaper_before = 0 + + +def _prctl(option, argument): + global _libc + if _libc is None: + _libc = ctypes.CDLL(None, use_errno=True) + _libc.prctl.argtypes = [ctypes.c_int, ctypes.c_ulong, ctypes.c_ulong, + ctypes.c_ulong, ctypes.c_ulong] + _libc.prctl.restype = ctypes.c_int + if _libc.prctl(option, argument, 0, 0, 0) != 0: + number = ctypes.get_errno() + raise OSError(number, f'prctl({option}) failed: {os.strerror(number)}') + + +def _subreaper_value(): + value = ctypes.c_int(0) + _prctl(PR_GET_CHILD_SUBREAPER, ctypes.addressof(value)) + return value.value + + +def _acquire_subreaper(): + """Make this process a child subreaper; nested and concurrent runs share it.""" + global _subreaper_users, _subreaper_before + with _subreaper_lock: + if _subreaper_users == 0: + _subreaper_before = _subreaper_value() + _prctl(PR_SET_CHILD_SUBREAPER, 1) + _subreaper_users += 1 + + +def _release_subreaper(): + global _subreaper_users + with _subreaper_lock: + _subreaper_users -= 1 + if _subreaper_users == 0 and not _subreaper_before: + _prctl(PR_SET_CHILD_SUBREAPER, 0) + + +def _child_setup(parent): + """Runs in the child between fork and exec: die with the launcher.""" + def setup(): + _prctl(PR_SET_PDEATHSIG, signal.SIGKILL) + if os.getppid() != parent: # the launcher died before prctl took effect + os.kill(os.getpid(), signal.SIGKILL) + return setup + + +# --- /proc -------------------------------------------------------------------- + +def _stat(pid): + """(state, ppid, pgrp, session) of a process, or None when it is gone.""" + try: + with open(f'/proc/{pid}/stat', 'rb') as file: + data = file.read() + fields = data[data.rindex(b')') + 2:].split() + return fields[0].decode('ascii'), int(fields[1]), int(fields[2]), int(fields[3]) + except (OSError, ValueError, IndexError): + return None + + +def _carries(pid, needle, uid): + """Whether a live process of this user has exactly needle among its environment entries.""" + try: + if os.stat(f'/proc/{pid}').st_uid != uid: + return False + with open(f'/proc/{pid}/environ', 'rb') as file: + return needle in file.read().split(b'\0') + except OSError: # not ours, or gone between listing and reading + return False + + +def _pids(): + try: + names = os.listdir('/proc') + except OSError: + return [] + return [int(name) for name in names if name.isdigit()] + + +def _needle(run_id): + return f'{RUN_ID_VARIABLE}={run_id}'.encode() + + +def _check_run_id(run_id): + if type(run_id) is not str or not _RUN_ID.fullmatch(run_id): + raise ValueError('A run id is 1 to 128 letters, digits, ".", "_" or "-", starting with a letter or digit.') + + +class _Sweeper: + """Finds, signals and reaps the processes of one run. + + A process belongs to the run when its environment carries the run id or, + while the command's leader is held unreaped (so its id cannot be reused), + when it is still in the leader's process group or session. + """ + + def __init__(self, run_id, leader=None): + self.needle = _needle(run_id) + self.leader = leader + self.me = os.getpid() + self.uid = os.getuid() + self.seen = set() # pids observed alive as members; their zombies are ours to reap + + def _member(self, pid, info): + if self.leader is not None and self.leader in (info[2], info[3]): + return True + return _carries(pid, self.needle, self.uid) + + def scan(self, *, children_only=False): + """Live members (excluding the leader), after reaping members' zombies that are our children.""" + alive = [] + for pid in _pids(): + if pid in (self.me, self.leader): + continue + info = _stat(pid) + if info is None or (children_only and info[1] != self.me): + continue + if info[0] in 'ZX': + # Only a launcher reaps: its children of the run are orphans it adopted. + # stop_strays() leaves a caller's own children for the caller to wait on. + if self.leader is not None and info[1] == self.me and ( + pid in self.seen or self.leader in (info[2], info[3])): + self._reap(pid) + continue + if self._member(pid, info): + self.seen.add(pid) + alive.append(pid) + return alive + + @staticmethod + def _reap(pid): + try: + os.waitpid(pid, os.WNOHANG) + except ChildProcessError: + pass + + def signal(self, pid, signum): + """Signal pid through a pidfd after checking, on that pidfd, that it is still a member.""" + try: + descriptor = os.pidfd_open(pid) + except (ProcessLookupError, PermissionError): + return False + try: + info = _stat(pid) + if info is None or info[0] in 'ZX' or not self._member(pid, info): + return False + signal.pidfd_send_signal(descriptor, signum) + return True + except (ProcessLookupError, PermissionError): + return False + finally: + os.close(descriptor) + + def sweep(self, limit): + """Kill members until none is alive or limit seconds pass: (killed pids, survivors).""" + deadline = time.monotonic() + limit + killed = set() + while True: + alive = self.scan() + if not alive or time.monotonic() >= deadline: + return killed, alive + for pid in alive: + if self.signal(pid, signal.SIGKILL): + killed.add(pid) + time.sleep(SWEEP_PAUSE) + + +def strays(run_id): + """Pids of live processes of this user whose environment carries TULDOK_RUN_ID=.""" + _check_run_id(run_id) + return sorted(_Sweeper(run_id).scan()) + + +def stop_strays(run_id): + """Kill every stray of a run whose launcher is gone, for up to SWEEP_LIMIT seconds. + + Returns {'killed': number of processes signalled, 'remaining': pids still alive}. + """ + _check_run_id(run_id) + killed, remaining = _Sweeper(run_id).sweep(SWEEP_LIMIT) + return {'killed': len(killed), 'remaining': sorted(remaining)} + + +# --- run ---------------------------------------------------------------------- + +def _directory_size(path): + """Total size of the regular files under path, not following links; tolerant of churn.""" + total = 0 + pending = [path] + while pending: + try: + entries = os.scandir(pending.pop()) + except OSError: + continue + with entries: + while True: + try: + entry = next(entries) + except StopIteration: + break + except OSError: + break + try: + if entry.is_dir(follow_symlinks=False): + pending.append(entry.path) + elif entry.is_file(follow_symlinks=False): + total += entry.stat(follow_symlinks=False).st_size + except OSError: + continue + return total + + +def _check_arguments(argv, env, run_id, directory, limits): + if type(argv) not in (list, tuple) or not argv or any(type(part) is not str for part in argv): + raise ValueError('argv must be a non-empty list of strings.') + if not isinstance(env, dict) or any(type(key) is not str or type(value) is not str + or not key or '=' in key for key, value in env.items()): + raise ValueError('env must map variable names to strings.') + _check_run_id(run_id) + if not os.path.isdir(directory): + raise ValueError(f'The run directory {directory} does not exist.') + if not isinstance(limits, dict) or set(limits) != {'wall_seconds', 'disk_bytes'}: + raise ValueError("limits must be {'wall_seconds': number, 'disk_bytes': integer}.") + wall, disk = limits['wall_seconds'], limits['disk_bytes'] + if type(wall) not in (int, float) or not math.isfinite(wall) or wall <= 0: + raise ValueError('wall_seconds must be a positive number.') + if type(disk) is not int or disk < 0: + raise ValueError('disk_bytes must be a non-negative integer.') + + +def _open_log(directory, name): + return os.open(os.path.join(directory, f'{name}.log'), + os.O_WRONLY | os.O_CREAT | os.O_APPEND | os.O_NOFOLLOW | os.O_CLOEXEC, 0o644) + + +def _install_stop_handlers(requests): + """Route SIGINT and SIGTERM to requests while a run is in progress; main thread only.""" + if threading.current_thread() is not threading.main_thread(): + return {} + previous = {} + try: + for signum in (signal.SIGINT, signal.SIGTERM): + before = signal.getsignal(signum) + if before is None: # installed outside Python; cannot be restored, so left alone + continue + signal.signal(signum, lambda number, frame: requests.append(number)) + previous[signum] = before + except BaseException: + _restore_handlers(previous) + raise + return previous + + +def _restore_handlers(previous): + for signum, handler in previous.items(): + signal.signal(signum, handler) + + +def run(argv, *, cwd, env, run_id, directory, limits, on_tick=None): + """Run argv until it and every process it started are gone; return its Outcome. + + env is the child's whole environment; TULDOK_RUN_ID is added. Standard + output and error are appended to /stdout.log and stderr.log. + on_tick(elapsed_seconds) is called about every WATCH_INTERVAL. Called from + the main thread, SIGINT and SIGTERM to this process cancel the run and the + previous handlers are restored before returning. Called from another + thread, Python cannot install handlers there, so those signals keep their + existing handlers: an exception they raise in the main thread does not + reach this thread, and if they end the process the child dies by its + parent-death signal and its strays are left for stop_strays(). An exception + from on_tick stops the run, sweeps it, and is then raised. + """ + _check_arguments(argv, env, run_id, directory, limits) + child_env = dict(env) + child_env[RUN_ID_VARIABLE] = run_id + cancel_path = os.path.join(directory, CANCEL_FILE) + requests = [] + _acquire_subreaper() + try: + previous = _install_stop_handlers(requests) + try: + return _run(argv, cwd, child_env, run_id, directory, limits, on_tick, + cancel_path, requests) + finally: + _restore_handlers(previous) + finally: + _release_subreaper() + + +def _run(argv, cwd, env, run_id, directory, limits, on_tick, cancel_path, requests): + started = time.monotonic() + stdout = _open_log(directory, 'stdout') + try: + stderr = _open_log(directory, 'stderr') + try: + child = subprocess.Popen( + list(argv), cwd=cwd, env=env, stdin=subprocess.DEVNULL, stdout=stdout, + stderr=stderr, start_new_session=True, close_fds=True, + preexec_fn=_child_setup(os.getpid())) + finally: + os.close(stderr) + finally: + os.close(stdout) + # The leader is never reaped until the sweep is over, so its pid, process + # group and session ids cannot be reused while they are used to find members. + sweeper = _Sweeper(run_id, child.pid) + exited = select.poll() + pidfd = os.pidfd_open(child.pid) + exited.register(pidfd, select.POLLIN) + try: + try: + reason = _watch(exited, sweeper, started, directory, limits, on_tick, + cancel_path, requests) + except BaseException: + _stop(exited, sweeper) + _finish(child, sweeper) + raise + leader_gone = True + if reason is not None: + leader_gone = _stop(exited, sweeper) + killed, survivors, status = _finish(child, sweeper) if leader_gone else (set(), [child.pid], None) + finally: + os.close(pidfd) + size = _directory_size(directory) + if survivors or status is None: + state = 'unknown' + elif reason is not None: + state = reason + elif status != 0: + state = 'failed' + elif size > limits['disk_bytes']: + state = 'over-disk' # finished between two measurements but over the limit + else: + state = 'succeeded' + return Outcome(state, status, round(time.monotonic() - started, 3), len(killed), size) + + +def _leader_exited(exited, timeout=0.0): + return bool(exited.poll(int(timeout * 1000))) + + +def _watch(exited, sweeper, started, directory, limits, on_tick, cancel_path, requests): + """Wait for the leader to exit or for a reason to stop it; return that reason or None.""" + next_disk = started + DISK_INTERVAL + while not _leader_exited(exited): + now = time.monotonic() + elapsed = now - started + if requests or os.path.lexists(cancel_path): + return 'cancelled' + if elapsed > limits['wall_seconds']: + return 'timed-out' + if now >= next_disk: + next_disk = now + DISK_INTERVAL + if _directory_size(directory) > limits['disk_bytes']: + return 'over-disk' + sweeper.scan(children_only=True) # reap orphans adopted as subreaper + if on_tick is not None: + on_tick(elapsed) + _leader_exited(exited, WATCH_INTERVAL) + return None + + +def _signal_run(sweeper, signum): + try: + os.killpg(sweeper.leader, signum) + except (ProcessLookupError, PermissionError): + pass + for pid in sweeper.scan(): + sweeper.signal(pid, signum) + + +def _stop(exited, sweeper): + """SIGTERM to the run, STOP_GRACE seconds, then SIGKILL; whether the leader has exited.""" + _signal_run(sweeper, signal.SIGTERM) + deadline = time.monotonic() + STOP_GRACE + while time.monotonic() < deadline: + if _leader_exited(exited) and not sweeper.scan(): + return True + time.sleep(SWEEP_PAUSE) + _signal_run(sweeper, signal.SIGKILL) + return _leader_exited(exited, SWEEP_LIMIT) + + +def _finish(child, sweeper): + """Sweep the exited run, then reap the leader: (killed pids, survivors, exit status).""" + killed, survivors = sweeper.sweep(SWEEP_LIMIT) + try: + status = child.wait(timeout=SWEEP_LIMIT) + except subprocess.TimeoutExpired: + status = None + return killed, survivors, status + + +# --- progress ----------------------------------------------------------------- + +def _decode_json(raw): + def pairs(items): + result = {} + for key, value in items: + if key in result: + raise ValueError('duplicate key') + result[key] = value + return result + + def refuse(constant): + raise ValueError('non-finite number') + return json.loads(raw, object_pairs_hook=pairs, parse_constant=refuse) + + +def _event(tail, starts_mid_file): + """The last complete, valid tuldok_progress_v1 line in tail, or None.""" + lines = tail.splitlines(keepends=True) + if starts_mid_file and lines: + lines = lines[1:] # the first line was cut by the tail and may be any suffix + for line in reversed(lines): + if len(line) > EVENT_LINE_LIMIT or not line.endswith(b'\n'): + continue + try: + value = _decode_json(line) + if type(value) is not dict or set(value) != {'format', 'stage', 'completed', 'total', 'metrics'}: + continue + if value['format'] != 'tuldok_progress_v1' or type(value['stage']) is not str \ + or not _NAME.fullmatch(value['stage']): + continue + if not (type(value['completed']) is int and type(value['total']) is int + and 0 <= value['completed'] <= value['total'] <= 1000000): + continue + metrics = value['metrics'] + if type(metrics) is not dict or len(metrics) > 8 or any( + not _NAME.fullmatch(name) or type(number) not in (int, float) + or not math.isfinite(number) for name, number in metrics.items()): + continue + return value + except (ValueError, TypeError, OverflowError, RecursionError): + continue + return None + + +def _tail(directory_fd, name): + """(last LOG_TAIL bytes, total size) of a regular log file, or (b'', None).""" + try: + descriptor = os.open(f'{name}.log', os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK | os.O_CLOEXEC, + dir_fd=directory_fd) + except OSError: # missing, a symbolic link, or unreadable + return b'', None + try: + status = os.fstat(descriptor) + if not stat.S_ISREG(status.st_mode): + return b'', None + start = max(0, status.st_size - LOG_TAIL) + return os.pread(descriptor, LOG_TAIL, start), status.st_size + finally: + os.close(descriptor) + + +def progress(directory): + """Log tails and the latest progress event of a run directory. + + Returns {'stdout', 'stderr': text of at most the last LOG_TAIL bytes, + 'stdout_bytes', 'stderr_bytes': total sizes (None when the log is absent + or not a regular file), 'event': the latest valid progress event or None}. + Neither the directory nor the logs are followed when they are links. + """ + result = {'event': None} + for name in LOGS: + result[name], result[f'{name}_bytes'] = '', None + try: + directory_fd = os.open(directory, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW | os.O_CLOEXEC) + except OSError: + return result + try: + for name in LOGS: + raw, size = _tail(directory_fd, name) + result[name] = _CONTROL.sub('', raw.decode('utf-8', errors='replace')) + result[f'{name}_bytes'] = size + if name == 'stdout' and size is not None: + result['event'] = _event(raw, size > len(raw)) + finally: + os.close(directory_fd) + return result From b9d32e9a97350cac3ab57115096fc42240ceb2c1 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 12 Nov 2026 00:52:54 -0700 Subject: [PATCH 021/131] docs(plan): the launcher runs each command under a custodian process Co-Authored-By: Claude Fable 5.2 --- docs/plans/definition-first-projects/spec-m6.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/plans/definition-first-projects/spec-m6.md b/docs/plans/definition-first-projects/spec-m6.md index 2546df5c..731008ef 100644 --- a/docs/plans/definition-first-projects/spec-m6.md +++ b/docs/plans/definition-first-projects/spec-m6.md @@ -37,10 +37,11 @@ Git is run with `git -C `, a fixed argument list, no shell, `GIT_OPTIONAL_L `launcher.run(argv, *, cwd, env, run_id, directory, limits, on_tick=None) -> Outcome` starts one command and stays with it until every process of the run is gone. -- **Start:** the child gets a new session, standard input from `/dev/null`, standard output and error appended to `/stdout.log` and `/stderr.log`, and `PR_SET_PDEATHSIG` set to `SIGKILL` so it dies if the launcher does. The launcher makes itself a child subreaper first, so orphaned descendants are reparented to it and can be reaped. +- **A custodian process per run.** `run` does not start the command itself. It starts a small custodian, `python -m tuldok_project.launcher` with the run's description in a file, and waits for it. The custodian is the child subreaper, starts the command, watches it, stops it and reaps everything it adopts with `waitpid(-1)`, then writes the outcome to `/outcome.json` and exits. This keeps the subreaper's effects out of the calling process, which may have children of its own and other threads; no zombie is left in the caller, and no exit status of the caller's own children can be taken. The custodian has `PR_SET_PDEATHSIG` set to `SIGTERM` and treats that signal as a request to stop the run, so a run is stopped when its caller dies. +- **Start:** the command gets a new session, standard input from `/dev/null`, standard output and error appended to `/stdout.log` and `/stderr.log`, and `PR_SET_PDEATHSIG` set to `SIGKILL` so it dies if the custodian does. - **Environment:** exactly what the caller passes, plus `TULDOK_RUN_ID`. - **While it runs,** every half second: has the child exited; is the wall-time limit passed; does `/cancel` exist. Every five seconds: is the size of `` over the disk limit. `on_tick` is called with the elapsed seconds. -- **Stopping** (limit passed, cancel, or the launcher receiving `SIGINT` or `SIGTERM`): `SIGTERM` to the child's process group, up to ten seconds of grace, then `SIGKILL` to the group. +- **Stopping** (limit passed, cancel, or the custodian receiving `SIGINT` or `SIGTERM`; the caller forwards those two signals to the custodian when it receives them in its main thread): `SIGTERM` to the command's process group and to every other process of the run, up to ten seconds of grace, then `SIGKILL`. - **After the child has exited, always:** find every process of this user whose environment contains `TULDOK_RUN_ID=` (reading `/proc//environ`), kill them, reap, and repeat until none is left or ten seconds have passed. - **Outcome:** `state` is `succeeded` (exit status 0, nothing forced), `failed` (non-zero exit), `timed-out`, `over-disk`, `cancelled`, or `unknown` (a process of the run could not be stopped). It also carries the exit status, the elapsed seconds, the number of stray processes that had to be killed, and the directory's final size. A run that left strays behind after a zero exit is still `succeeded`, with the count recorded. From 35fdafc6e3e2cab18ea49f20089316acf09dda15 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 12 Nov 2026 01:02:22 -0700 Subject: [PATCH 022/131] refactor(project): give each run its own custodian process launcher.run now starts a small custodian (python -m tuldok_project.launcher) that is the child subreaper for one run: it starts the command, watches and stops it, and reaps everything it adopts before writing the outcome. The calling process no longer becomes a subreaper, so it is left with no zombie children and its own unrelated children keep their exit status. A run is stopped and swept when its caller dies, and a custodian that disappears without an outcome gives unknown after a sweep by run id. Co-Authored-By: Claude Fable 5.2 --- tests/test_tuldok_project_launcher.py | 177 ++++++++-- tuldok_project/launcher.py | 464 ++++++++++++++++++-------- 2 files changed, 484 insertions(+), 157 deletions(-) diff --git a/tests/test_tuldok_project_launcher.py b/tests/test_tuldok_project_launcher.py index 40e0ee6b..7fe6cec6 100644 --- a/tests/test_tuldok_project_launcher.py +++ b/tests/test_tuldok_project_launcher.py @@ -1,7 +1,8 @@ """The launcher (spec-m6.md section 3): run, strays, stop_strays and progress. -Stand-in commands are small Python scripts run by the test interpreter. The -module's intervals are shortened so the file runs in seconds. Every test +Stand-in commands are small Python scripts run by the test interpreter under +the real custodian process. The module's intervals are shortened (run() hands +them to the custodian) so the file runs in seconds. Every test kills whatever carries its run id when it ends, pass or fail, using its own /proc scan rather than the code under test, and the run tests check that the test process is left with no zombie child. @@ -20,7 +21,8 @@ from unittest import mock import uuid -sys.path.insert(0, str(Path(__file__).resolve().parents[1])) +ROOT = Path(__file__).resolve().parents[1] +sys.path.insert(0, str(ROOT)) from tuldok_project import launcher # noqa: E402 @@ -61,8 +63,8 @@ def _kill_run(run_id): time.sleep(0.02) -def _zombie_children(): - zombies = [] +def _children(*, zombies=False): + found = [] for name in os.listdir('/proc'): if not name.isdigit(): continue @@ -71,9 +73,13 @@ def _zombie_children(): fields = file.read().rsplit(b')', 1)[1].split() except OSError: continue - if fields[0] == b'Z' and int(fields[1]) == os.getpid(): - zombies.append(int(name)) - return zombies + if int(fields[1]) == os.getpid() and (fields[0] == b'Z') == zombies: + found.append(int(name)) + return found + + +def _zombie_children(): + return _children(zombies=True) def _alive(pid): @@ -115,6 +121,8 @@ def run_script(self, body, *, limits=GENEROUS, on_tick=None, args=()): self.assertEqual(_zombie_children(), [], 'run() left a zombie child') self.assertEqual((signal.getsignal(signal.SIGINT), signal.getsignal(signal.SIGTERM)), self.handlers, 'signal handlers were not restored') + self.assertFalse((self.directory / launcher.DESCRIPTION_FILE).exists(), + 'the description file outlived the run') return outcome def log(self, name): @@ -303,28 +311,145 @@ def test_run_id_prefix_is_not_a_match(self): self.assertEqual((outcome.state, outcome.strays), ('succeeded', 0)) self.assertIsNone(neighbour.poll()) - def test_prctl_failure_refuses_to_run(self): - def failing(option, argument): - raise OSError(1, 'refused') - with mock.patch.object(launcher, '_prctl', failing): - with self.assertRaises(OSError): - launcher.run([sys.executable, '-c', 'print(1)'], cwd=str(self.scratch), env=self.env(), - run_id=self.run_id, directory=str(self.directory), limits=GENEROUS) + def custodian_with_failing_prctl(self, option, argument): + """Run the custodian in a process whose prctl(option, argument) fails; return run()'s result.""" + description = self.directory / launcher.DESCRIPTION_FILE + launcher._write_description(str(description), [sys.executable, '-c', 'print(1)'], + str(self.scratch), self.env(), self.run_id, str(self.directory), GENEROUS) + subprocess.run([sys.executable, '-c', textwrap.dedent(f''' + import sys + sys.path.insert(0, {str(ROOT)!r}) + from tuldok_project import launcher + real = launcher._prctl + def failing(option, argument): + if (option, argument) == ({option}, {argument}): + raise OSError(1, 'refused') + return real(option, argument) + launcher._prctl = failing + sys.exit(launcher._custodian_main([{str(description)!r}])) + ''')], check=True, timeout=30) + self.assertFalse(description.exists()) + return launcher._read_outcome(str(self.directory / launcher.OUTCOME_FILE), 0, self.run_id, + str(self.directory), time.monotonic()) + + def test_subreaper_failure_refuses_to_run(self): + with self.assertRaisesRegex(OSError, 'refused'): + self.custodian_with_failing_prctl(launcher.PR_SET_CHILD_SUBREAPER, 1) self.assertFalse((self.directory / 'stdout.log').exists()) - def test_pdeathsig_failure_in_child_raises(self): - real = launcher._prctl - - def failing_pdeathsig(option, argument): - if option == launcher.PR_SET_PDEATHSIG: - raise OSError(1, 'refused') - return real(option, argument) - with mock.patch.object(launcher, '_prctl', failing_pdeathsig): - with self.assertRaises(subprocess.SubprocessError): - launcher.run([sys.executable, '-c', 'print(1)'], cwd=str(self.scratch), env=self.env(), - run_id=self.run_id, directory=str(self.directory), limits=GENEROUS) + def test_pdeathsig_failure_in_command_raises(self): + with self.assertRaises(subprocess.SubprocessError): + self.custodian_with_failing_prctl(launcher.PR_SET_PDEATHSIG, int(signal.SIGKILL)) + self.assertEqual(self.log('stdout'), '') + self.assertEqual(_carriers(self.run_id), []) + + def test_missing_program_raises(self): + with self.assertRaises(FileNotFoundError): + launcher.run([str(self.scratch / 'no-such-program')], cwd=str(self.scratch), env=self.env(), + run_id=self.run_id, directory=str(self.directory), limits=GENEROUS) + self.assertEqual(_zombie_children(), []) + self.assertFalse((self.directory / launcher.DESCRIPTION_FILE).exists()) + + def test_description_file_is_private(self): + path = self.scratch / 'description.json' + launcher._write_description(str(path), ['true'], str(self.scratch), {'SECRET': 'x'}, + self.run_id, str(self.directory), GENEROUS) + self.assertEqual(path.stat().st_mode & 0o777, 0o600) + + def test_exited_double_fork_intermediate_leaves_no_zombie(self): + daemon_file, background_file = self.scratch / 'daemon', self.scratch / 'background' + outcome = self.run_script(f''' + import os, time + if os.fork() == 0: # the intermediate: leaves the session, forks, exits at once + os.setsid() + if os.fork() == 0: + open({str(daemon_file)!r} + '.tmp', 'w').write(str(os.getpid())) + os.rename({str(daemon_file)!r} + '.tmp', {str(daemon_file)!r}) + time.sleep(30) + os._exit(0) + if os.fork() == 0: # a plain background child + open({str(background_file)!r} + '.tmp', 'w').write(str(os.getpid())) + os.rename({str(background_file)!r} + '.tmp', {str(background_file)!r}) + time.sleep(30) + os._exit(0) + while not (os.path.exists({str(daemon_file)!r}) and os.path.exists({str(background_file)!r})): + time.sleep(0.01) + ''') # the intermediate is never waited for: it is a zombie when the command exits + self.assertEqual((outcome.state, outcome.strays), ('succeeded', 2)) + self.assertFalse(_alive(int(daemon_file.read_text()))) + self.assertFalse(_alive(int(background_file.read_text()))) + + def test_callers_own_child_keeps_its_exit_status(self): + own = subprocess.Popen([sys.executable, '-c', 'import time, sys; time.sleep(0.3); sys.exit(7)']) + self.addCleanup(own.kill) + outcome = launcher.run([sys.executable, '-c', 'import time; time.sleep(1.0)'], + cwd=str(self.scratch), env=self.env(), run_id=self.run_id, + directory=str(self.directory), limits=GENEROUS) + self.assertEqual(outcome.state, 'succeeded') + self.assertEqual(_zombie_children(), [own.pid]) # exited during the run, and still ours to wait on + self.assertEqual(own.wait(5), 7) self.assertEqual(_zombie_children(), []) + def test_caller_killed_mid_run_is_stopped_by_custodian(self): + started_file = self.scratch / 'started' + command = self.script(f''' + import time + open({str(started_file)!r}, 'w').write('1') + time.sleep(30) + ''') + caller = subprocess.Popen([sys.executable, '-c', textwrap.dedent(f''' + import sys + sys.path.insert(0, {str(ROOT)!r}) + from tuldok_project import launcher + for name, value in {FAST!r}.items(): + setattr(launcher, name, value) + launcher.run([sys.executable, {str(command)!r}], cwd={str(self.scratch)!r}, + env={self.env()!r}, run_id={self.run_id!r}, directory={str(self.directory)!r}, + limits={GENEROUS!r}) + ''')]) + self.addCleanup(caller.wait) + self.addCleanup(caller.kill) + deadline = time.monotonic() + 20 + while not started_file.exists(): + self.assertLess(time.monotonic(), deadline) + time.sleep(0.01) + caller.kill() + caller.wait() + outcome_file = self.directory / launcher.OUTCOME_FILE + while not outcome_file.exists(): + self.assertLess(time.monotonic(), deadline) + time.sleep(0.02) + self.assertEqual(json.loads(outcome_file.read_text())['state'], 'cancelled') + self.assertEqual(_carriers(self.run_id), []) + + def test_custodian_killed_mid_run(self): + pid_file = self.scratch / 'pid' + + def kill_custodian(elapsed): + if elapsed > 0.3 and pid_file.exists(): + for pid in _children(): + try: + with open(f'/proc/{pid}/cmdline', 'rb') as file: + if b'tuldok_project.launcher' in file.read(): + os.kill(pid, signal.SIGKILL) + except OSError: + pass + outcome = self.run_script(f''' + import os, time + if os.fork() == 0: + os.setsid() # out of the group, and with no parent-death signal of its own + open({str(pid_file)!r} + '.tmp', 'w').write(str(os.getpid())) + os.rename({str(pid_file)!r} + '.tmp', {str(pid_file)!r}) + time.sleep(30) + os._exit(0) + time.sleep(30) + ''', on_tick=kill_custodian) + self.assertEqual(outcome.state, 'unknown') + self.assertIsNone(outcome.exit_status) + self.assertIn('custodian ended without an outcome', outcome.problem) + self.assertGreaterEqual(outcome.strays, 1) + self.assertFalse(_alive(int(pid_file.read_text()))) + def test_bad_arguments(self): good = dict(cwd=str(self.scratch), env=self.env(), run_id=self.run_id, directory=str(self.directory), limits=GENEROUS) diff --git a/tuldok_project/launcher.py b/tuldok_project/launcher.py index 7822d7b1..35f02ac1 100644 --- a/tuldok_project/launcher.py +++ b/tuldok_project/launcher.py @@ -1,20 +1,26 @@ """Run one build command and stay with it until every process it started is gone. -Owns section 3 of docs/plans/definition-first-projects/spec-m6.md. run() starts -the command in a new session with PR_SET_PDEATHSIG set to SIGKILL and -TULDOK_RUN_ID= in its environment, watches the wall-time limit, the -disk limit and the run directory's cancel file, stops the process group when -one of them (or SIGINT or SIGTERM to this process) asks for it, and then -sweeps: every process of this user whose environment carries the run id, or -that is still in the command's process group or session, is killed and reaped -before run() returns. While a run is in progress this process is a child -subreaper, so descendants orphaned by the run are reparented here and reaped. -strays() and stop_strays() do the sweep alone for a run whose launcher is gone. -progress() reads the bounded tail of a run's two logs and its latest -tuldok_progress_v1 line. Linux only. +Owns section 3 of docs/plans/definition-first-projects/spec-m6.md. run() does +not start the command itself: it writes the run's description to a private +file in the run directory and starts a custodian, `python -m +tuldok_project.launcher `, then waits for it and reads +/outcome.json. The custodian is a child subreaper, so every child +it ever has belongs to the run and it reaps them all; this keeps orphans, +zombies and waitpid() out of the calling process, which may have children and +threads of its own. The custodian starts the command in a new session with +PR_SET_PDEATHSIG set to SIGKILL and TULDOK_RUN_ID= in its environment, +watches the wall-time limit, the disk limit and the run directory's cancel +file, stops the run when one of them (or SIGINT or SIGTERM to the custodian) +asks for it, and then sweeps: every process of this user whose environment +carries the run id, every process still in the command's process group or +session, and every child of the custodian is killed and reaped. The custodian +itself has PR_SET_PDEATHSIG set to SIGTERM, so a run whose caller dies is +stopped and swept. strays() and stop_strays() do the sweep alone for a run +whose custodian is gone. progress() reads the bounded tail of a run's two logs +and its latest tuldok_progress_v1 line. Linux only. """ import ctypes -from dataclasses import dataclass +from dataclasses import asdict, dataclass, fields import json import math import os @@ -23,6 +29,7 @@ import signal import stat import subprocess +import sys import threading import time @@ -36,13 +43,18 @@ RUN_ID_VARIABLE = 'TULDOK_RUN_ID' CANCEL_FILE = 'cancel' +DESCRIPTION_FILE = 'custodian.json' +OUTCOME_FILE = 'outcome.json' LOGS = ('stdout', 'stderr') STATES = ('succeeded', 'failed', 'timed-out', 'over-disk', 'cancelled', 'unknown') PR_SET_PDEATHSIG = 1 PR_SET_CHILD_SUBREAPER = 36 -PR_GET_CHILD_SUBREAPER = 37 +_TIMING = ('WATCH_INTERVAL', 'DISK_INTERVAL', 'STOP_GRACE', 'SWEEP_LIMIT', 'SWEEP_PAUSE') +_STOP_SIGNALS = {signal.SIGINT, signal.SIGTERM} +_DESCRIPTION_LIMIT = 16 * 1024 * 1024 +_OUTCOME_LIMIT = 64 * 1024 _RUN_ID = re.compile(r'[A-Za-z0-9][A-Za-z0-9_.-]{0,127}') _NAME = re.compile(r'[A-Za-z0-9][A-Za-z0-9_.-]{0,63}') _CONTROL = re.compile('[\x00-\x08\x0b-\x1f\x7f-\x9f]') @@ -50,22 +62,21 @@ @dataclass(frozen=True) class Outcome: - """How a run ended. exit_status is the Popen return code (negative for a - signal), or None when the command could not be reaped; strays counts the - processes the final sweep had to kill; bytes is the run directory's size.""" + """How a run ended. exit_status is the command's return code (negative for + a signal), or None when it is not known; strays counts the processes the + final sweep had to kill; bytes is the run directory's size; problem says + why a run is unknown.""" state: str exit_status: int | None seconds: float strays: int bytes: int + problem: str | None = None # --- prctl ------------------------------------------------------------------ _libc = None -_subreaper_lock = threading.Lock() -_subreaper_users = 0 -_subreaper_before = 0 def _prctl(option, argument): @@ -80,35 +91,11 @@ def _prctl(option, argument): raise OSError(number, f'prctl({option}) failed: {os.strerror(number)}') -def _subreaper_value(): - value = ctypes.c_int(0) - _prctl(PR_GET_CHILD_SUBREAPER, ctypes.addressof(value)) - return value.value - - -def _acquire_subreaper(): - """Make this process a child subreaper; nested and concurrent runs share it.""" - global _subreaper_users, _subreaper_before - with _subreaper_lock: - if _subreaper_users == 0: - _subreaper_before = _subreaper_value() - _prctl(PR_SET_CHILD_SUBREAPER, 1) - _subreaper_users += 1 - - -def _release_subreaper(): - global _subreaper_users - with _subreaper_lock: - _subreaper_users -= 1 - if _subreaper_users == 0 and not _subreaper_before: - _prctl(PR_SET_CHILD_SUBREAPER, 0) - - def _child_setup(parent): - """Runs in the child between fork and exec: die with the launcher.""" + """Runs in the command between fork and exec: die with the custodian.""" def setup(): _prctl(PR_SET_PDEATHSIG, signal.SIGKILL) - if os.getppid() != parent: # the launcher died before prctl took effect + if os.getppid() != parent: # the custodian died before prctl took effect os.kill(os.getpid(), signal.SIGKILL) return setup @@ -120,8 +107,8 @@ def _stat(pid): try: with open(f'/proc/{pid}/stat', 'rb') as file: data = file.read() - fields = data[data.rindex(b')') + 2:].split() - return fields[0].decode('ascii'), int(fields[1]), int(fields[2]), int(fields[3]) + fields_ = data[data.rindex(b')') + 2:].split() + return fields_[0].decode('ascii'), int(fields_[1]), int(fields_[2]), int(fields_[3]) except (OSError, ValueError, IndexError): return None @@ -145,37 +132,36 @@ def _pids(): return [int(name) for name in names if name.isdigit()] -def _needle(run_id): - return f'{RUN_ID_VARIABLE}={run_id}'.encode() - - def _check_run_id(run_id): if type(run_id) is not str or not _RUN_ID.fullmatch(run_id): raise ValueError('A run id is 1 to 128 letters, digits, ".", "_" or "-", starting with a letter or digit.') class _Sweeper: - """Finds, signals and reaps the processes of one run. + """Finds, signals and (in the custodian) reaps the processes of one run. - A process belongs to the run when its environment carries the run id or, - while the command's leader is held unreaped (so its id cannot be reused), - when it is still in the leader's process group or session. + A process belongs to the run when its environment carries the run id. In + the custodian (leader given) it also belongs when it is in the leader's + process group or session, which is safe because the leader is held + unreaped until the sweep is over so those ids cannot be reused, and when + it is a child of the custodian, since the custodian has no other children. """ def __init__(self, run_id, leader=None): - self.needle = _needle(run_id) + self.needle = f'{RUN_ID_VARIABLE}={run_id}'.encode() + self.custodian = leader is not None self.leader = leader self.me = os.getpid() self.uid = os.getuid() - self.seen = set() # pids observed alive as members; their zombies are ours to reap def _member(self, pid, info): - if self.leader is not None and self.leader in (info[2], info[3]): + if self.custodian and (info[1] == self.me or ( + self.leader is not None and self.leader in (info[2], info[3]))): return True return _carries(pid, self.needle, self.uid) def scan(self, *, children_only=False): - """Live members (excluding the leader), after reaping members' zombies that are our children.""" + """Live members other than the leader; in the custodian, zombie children are reaped on the way.""" alive = [] for pid in _pids(): if pid in (self.me, self.leader): @@ -184,24 +170,13 @@ def scan(self, *, children_only=False): if info is None or (children_only and info[1] != self.me): continue if info[0] in 'ZX': - # Only a launcher reaps: its children of the run are orphans it adopted. - # stop_strays() leaves a caller's own children for the caller to wait on. - if self.leader is not None and info[1] == self.me and ( - pid in self.seen or self.leader in (info[2], info[3])): - self._reap(pid) + if self.custodian and info[1] == self.me: + _reap(pid) continue if self._member(pid, info): - self.seen.add(pid) alive.append(pid) return alive - @staticmethod - def _reap(pid): - try: - os.waitpid(pid, os.WNOHANG) - except ChildProcessError: - pass - def signal(self, pid, signum): """Signal pid through a pidfd after checking, on that pidfd, that it is still a member.""" try: @@ -219,12 +194,12 @@ def signal(self, pid, signum): finally: os.close(descriptor) - def sweep(self, limit): + def sweep(self, limit, *, children_only=False): """Kill members until none is alive or limit seconds pass: (killed pids, survivors).""" deadline = time.monotonic() + limit killed = set() while True: - alive = self.scan() + alive = self.scan(children_only=children_only) if not alive or time.monotonic() >= deadline: return killed, alive for pid in alive: @@ -233,6 +208,13 @@ def sweep(self, limit): time.sleep(SWEEP_PAUSE) +def _reap(pid): + try: + os.waitpid(pid, os.WNOHANG) + except ChildProcessError: + pass + + def strays(run_id): """Pids of live processes of this user whose environment carries TULDOK_RUN_ID=.""" _check_run_id(run_id) @@ -240,16 +222,17 @@ def strays(run_id): def stop_strays(run_id): - """Kill every stray of a run whose launcher is gone, for up to SWEEP_LIMIT seconds. + """Kill every stray of a run whose custodian is gone, for up to SWEEP_LIMIT seconds. Returns {'killed': number of processes signalled, 'remaining': pids still alive}. + Never reaps: a stray that is the caller's own child is left for the caller to wait on. """ _check_run_id(run_id) killed, remaining = _Sweeper(run_id).sweep(SWEEP_LIMIT) return {'killed': len(killed), 'remaining': sorted(remaining)} -# --- run ---------------------------------------------------------------------- +# --- files -------------------------------------------------------------------- def _directory_size(path): """Total size of the regular files under path, not following links; tolerant of churn.""" @@ -264,9 +247,7 @@ def _directory_size(path): while True: try: entry = next(entries) - except StopIteration: - break - except OSError: + except (StopIteration, OSError): break try: if entry.is_dir(follow_symlinks=False): @@ -278,6 +259,43 @@ def _directory_size(path): return total +def _unlink(path): + try: + os.unlink(path) + except FileNotFoundError: + pass + + +def _write_new(path, data, mode): + """Write a new file without following links; it must not exist.""" + descriptor = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW | os.O_CLOEXEC, mode) + try: + os.fchmod(descriptor, mode) + view = memoryview(data) + while view: + view = view[os.write(descriptor, view):] + os.fsync(descriptor) + finally: + os.close(descriptor) + + +def _read_json(path, limit): + """A JSON value from a regular file of at most limit bytes, not following links.""" + descriptor = os.open(path, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK | os.O_CLOEXEC) + try: + status = os.fstat(descriptor) + if not stat.S_ISREG(status.st_mode) or status.st_size > limit: + raise ValueError(f'{path} is not a regular file of at most {limit} bytes.') + chunks = [] + while chunk := os.read(descriptor, limit + 1 - sum(map(len, chunks))): + chunks.append(chunk) + if sum(map(len, chunks)) > limit: + raise ValueError(f'{path} is over {limit} bytes.') + finally: + os.close(descriptor) + return json.loads(b''.join(chunks)) + + def _check_arguments(argv, env, run_id, directory, limits): if type(argv) not in (list, tuple) or not argv or any(type(part) is not str for part in argv): raise ValueError('argv must be a non-empty list of strings.') @@ -296,22 +314,95 @@ def _check_arguments(argv, env, run_id, directory, limits): raise ValueError('disk_bytes must be a non-negative integer.') -def _open_log(directory, name): - return os.open(os.path.join(directory, f'{name}.log'), - os.O_WRONLY | os.O_CREAT | os.O_APPEND | os.O_NOFOLLOW | os.O_CLOEXEC, 0o644) +# --- the caller's side ---------------------------------------------------------- + +def run(argv, *, cwd, env, run_id, directory, limits, on_tick=None): + """Run argv under a custodian until it and every process it started are gone. + + env is the command's whole environment; TULDOK_RUN_ID is added. Standard + output and error are appended to /stdout.log and stderr.log. + on_tick(elapsed_seconds) is called about every WATCH_INTERVAL. Called from + the main thread, SIGINT and SIGTERM received by this process are forwarded + to the custodian, which cancels the run, and the previous handlers are + restored before returning. Called from another thread, nothing is + installed: those signals keep their existing handlers, and the custodian + still stops the run if this process dies. An exception from on_tick stops + the run, waits for the custodian to sweep it, and is then raised. Problems + the custodian meets before the command runs (prctl refused, the program + not found) are raised here; a custodian that ends without an outcome gives + 'unknown' after stop_strays(run_id). + """ + _check_arguments(argv, env, run_id, directory, limits) + directory = os.path.abspath(directory) + description_path = os.path.join(directory, DESCRIPTION_FILE) + outcome_path = os.path.join(directory, OUTCOME_FILE) + _unlink(description_path) + _unlink(outcome_path) + _write_description(description_path, argv, cwd, env, run_id, directory, limits) + started = time.monotonic() + target = {'pid': None, 'pending': []} + try: + previous = _install_forwarding(target) + try: + custodian = _start_custodian(description_path) + target['pid'] = custodian.pid + for signum in target['pending']: + os.kill(custodian.pid, signum) + try: + _wait(custodian, started, on_tick) + except BaseException: + _abandon(custodian, run_id) + raise + finally: + _restore_handlers(previous) + finally: + _unlink(description_path) + return _read_outcome(outcome_path, custodian.returncode, run_id, directory, started) -def _install_stop_handlers(requests): - """Route SIGINT and SIGTERM to requests while a run is in progress; main thread only.""" +def _write_description(path, argv, cwd, env, run_id, directory, limits): + description = { + 'argv': list(argv), 'cwd': os.path.abspath(cwd), 'env': dict(env), 'run_id': run_id, + 'directory': os.path.abspath(directory), 'limits': dict(limits), 'parent': os.getpid(), + 'timing': {name: globals()[name] for name in _TIMING}} + _write_new(path, json.dumps(description).encode(), 0o600) + + +def _start_custodian(description_path): + package_parent = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) + env = {'PYTHONPATH': package_parent, 'PYTHONDONTWRITEBYTECODE': '1'} + # Blocked here, SIGINT and SIGTERM stay blocked in the custodian until its + # handlers are in place, so a forwarded signal is never lost at startup. + before = signal.pthread_sigmask(signal.SIG_BLOCK, _STOP_SIGNALS) + try: + return subprocess.Popen( + [sys.executable, '-P', '-s', '-m', 'tuldok_project.launcher', description_path], + cwd='/', env=env, stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, + start_new_session=True, close_fds=True) + finally: + signal.pthread_sigmask(signal.SIG_SETMASK, before) + + +def _install_forwarding(target): + """Forward SIGINT and SIGTERM to the custodian while a run is in progress; main thread only.""" if threading.current_thread() is not threading.main_thread(): return {} + + def forward(signum, frame): + if target['pid'] is None: + target['pending'].append(signum) + else: + try: + os.kill(target['pid'], signum) + except ProcessLookupError: + pass previous = {} try: - for signum in (signal.SIGINT, signal.SIGTERM): + for signum in sorted(_STOP_SIGNALS): before = signal.getsignal(signum) if before is None: # installed outside Python; cannot be restored, so left alone continue - signal.signal(signum, lambda number, frame: requests.append(number)) + signal.signal(signum, forward) previous[signum] = before except BaseException: _restore_handlers(previous) @@ -324,38 +415,126 @@ def _restore_handlers(previous): signal.signal(signum, handler) -def run(argv, *, cwd, env, run_id, directory, limits, on_tick=None): - """Run argv until it and every process it started are gone; return its Outcome. +def _wait(custodian, started, on_tick): + while True: + try: + custodian.wait(timeout=WATCH_INTERVAL) + return + except subprocess.TimeoutExpired: + pass + if on_tick is not None: + on_tick(time.monotonic() - started) - env is the child's whole environment; TULDOK_RUN_ID is added. Standard - output and error are appended to /stdout.log and stderr.log. - on_tick(elapsed_seconds) is called about every WATCH_INTERVAL. Called from - the main thread, SIGINT and SIGTERM to this process cancel the run and the - previous handlers are restored before returning. Called from another - thread, Python cannot install handlers there, so those signals keep their - existing handlers: an exception they raise in the main thread does not - reach this thread, and if they end the process the child dies by its - parent-death signal and its strays are left for stop_strays(). An exception - from on_tick stops the run, sweeps it, and is then raised. - """ - _check_arguments(argv, env, run_id, directory, limits) - child_env = dict(env) - child_env[RUN_ID_VARIABLE] = run_id - cancel_path = os.path.join(directory, CANCEL_FILE) + +def _abandon(custodian, run_id): + """Ask the custodian to stop the run and wait for its sweep; kill it if it does not finish.""" + try: + custodian.send_signal(signal.SIGTERM) + custodian.wait(timeout=STOP_GRACE + 3 * SWEEP_LIMIT + 5) + except subprocess.TimeoutExpired: + custodian.kill() + custodian.wait() + stop_strays(run_id) + + +_ERRORS = {'ValueError': ValueError, 'SubprocessError': subprocess.SubprocessError} + + +def _read_outcome(path, custodian_status, run_id, directory, started): + try: + record = _read_json(path, _OUTCOME_LIMIT) + except (OSError, ValueError): + record = None + if type(record) is dict and set(record) == {'error'} and type(record['error']) is dict: + error = record['error'] + message = str(error.get('message')) + if type(error.get('errno')) is int: + raise OSError(error['errno'], message) + raise _ERRORS.get(error.get('type'), RuntimeError)(message) + outcome = _outcome_from(record) + if outcome is not None: + return outcome + result = stop_strays(run_id) + problem = f'The custodian ended without an outcome (exit status {custodian_status}).' + if result['remaining']: + problem += f' Processes of the run still alive: {result["remaining"]}.' + return Outcome('unknown', None, round(time.monotonic() - started, 3), result['killed'], + _directory_size(directory), problem) + + +def _outcome_from(record): + names = {field.name for field in fields(Outcome)} + if type(record) is not dict or set(record) != names or record['state'] not in STATES: + return None + if not (record['exit_status'] is None or type(record['exit_status']) is int) \ + or type(record['seconds']) not in (int, float) or type(record['strays']) is not int \ + or type(record['bytes']) is not int \ + or not (record['problem'] is None or type(record['problem']) is str): + return None + return Outcome(**record) + + +# --- the custodian ------------------------------------------------------------ + +def _custodian_main(arguments): + """Entry point of `python -m tuldok_project.launcher `.""" requests = [] - _acquire_subreaper() + for signum in _STOP_SIGNALS: + signal.signal(signum, lambda number, frame: requests.append(number)) + signal.pthread_sigmask(signal.SIG_UNBLOCK, _STOP_SIGNALS) + if len(arguments) != 1: + print('usage: python -m tuldok_project.launcher ', file=sys.stderr) + return 2 try: - previous = _install_stop_handlers(requests) - try: - return _run(argv, cwd, child_env, run_id, directory, limits, on_tick, - cancel_path, requests) - finally: - _restore_handlers(previous) + description = _read_json(arguments[0], _DESCRIPTION_LIMIT) + directory = description['directory'] + except (OSError, ValueError, TypeError, KeyError) as error: + print(f'custodian: cannot read {arguments[0]}: {error}', file=sys.stderr) + return 2 finally: - _release_subreaper() + _unlink_quietly(arguments[0]) # it may hold secrets from the environment + try: + _prctl(PR_SET_PDEATHSIG, signal.SIGTERM) + if os.getppid() != description['parent']: # the caller died before prctl took effect + requests.append(signal.SIGTERM) + for name, value in description['timing'].items(): + if name in _TIMING and type(value) in (int, float) and value > 0: + globals()[name] = value + _prctl(PR_SET_CHILD_SUBREAPER, 1) + _check_arguments(description['argv'], description['env'], description['run_id'], + directory, description['limits']) + env = dict(description['env']) + env[RUN_ID_VARIABLE] = description['run_id'] + record = asdict(_supervise(description['argv'], description['cwd'], env, description['run_id'], + directory, description['limits'], requests)) + except Exception as error: + record = {'error': {'type': type(error).__name__, 'message': str(error), + 'errno': error.errno if isinstance(error, OSError) else None}} + temporary = os.path.join(directory, f'.{OUTCOME_FILE}.{os.getpid()}') + try: + _write_new(temporary, json.dumps(record).encode(), 0o644) + os.replace(temporary, os.path.join(directory, OUTCOME_FILE)) + except OSError as error: + print(f'custodian: cannot write the outcome: {error}', file=sys.stderr) + _unlink_quietly(temporary) + return 3 + return 0 -def _run(argv, cwd, env, run_id, directory, limits, on_tick, cancel_path, requests): +def _unlink_quietly(path): + try: + os.unlink(path) + except OSError: + pass + + +def _open_log(directory, name): + return os.open(os.path.join(directory, f'{name}.log'), + os.O_WRONLY | os.O_CREAT | os.O_APPEND | os.O_NOFOLLOW | os.O_CLOEXEC, 0o644) + + +def _supervise(argv, cwd, env, run_id, directory, limits, requests): + """Start the command, watch it, stop it if asked, sweep, and return its Outcome.""" started = time.monotonic() stdout = _open_log(directory, 'stdout') try: @@ -369,16 +548,13 @@ def _run(argv, cwd, env, run_id, directory, limits, on_tick, cancel_path, reques os.close(stderr) finally: os.close(stdout) - # The leader is never reaped until the sweep is over, so its pid, process - # group and session ids cannot be reused while they are used to find members. sweeper = _Sweeper(run_id, child.pid) exited = select.poll() pidfd = os.pidfd_open(child.pid) exited.register(pidfd, select.POLLIN) try: try: - reason = _watch(exited, sweeper, started, directory, limits, on_tick, - cancel_path, requests) + reason = _watch(exited, sweeper, started, directory, limits, requests) except BaseException: _stop(exited, sweeper) _finish(child, sweeper) @@ -386,12 +562,18 @@ def _run(argv, cwd, env, run_id, directory, limits, on_tick, cancel_path, reques leader_gone = True if reason is not None: leader_gone = _stop(exited, sweeper) - killed, survivors, status = _finish(child, sweeper) if leader_gone else (set(), [child.pid], None) + if leader_gone: + killed, survivors, status = _finish(child, sweeper) + else: + killed, survivors, status = set(), [child.pid], None finally: os.close(pidfd) size = _directory_size(directory) - if survivors or status is None: - state = 'unknown' + problem = None + if status is None: + state, problem = 'unknown', 'The command could not be stopped.' + elif survivors: + state, problem = 'unknown', f'Processes of the run could not be stopped: {sorted(survivors)}.' elif reason is not None: state = reason elif status != 0: @@ -400,30 +582,28 @@ def _run(argv, cwd, env, run_id, directory, limits, on_tick, cancel_path, reques state = 'over-disk' # finished between two measurements but over the limit else: state = 'succeeded' - return Outcome(state, status, round(time.monotonic() - started, 3), len(killed), size) + return Outcome(state, status, round(time.monotonic() - started, 3), len(killed), size, problem) def _leader_exited(exited, timeout=0.0): return bool(exited.poll(int(timeout * 1000))) -def _watch(exited, sweeper, started, directory, limits, on_tick, cancel_path, requests): +def _watch(exited, sweeper, started, directory, limits, requests): """Wait for the leader to exit or for a reason to stop it; return that reason or None.""" + cancel_path = os.path.join(directory, CANCEL_FILE) next_disk = started + DISK_INTERVAL while not _leader_exited(exited): now = time.monotonic() - elapsed = now - started if requests or os.path.lexists(cancel_path): return 'cancelled' - if elapsed > limits['wall_seconds']: + if now - started > limits['wall_seconds']: return 'timed-out' if now >= next_disk: next_disk = now + DISK_INTERVAL if _directory_size(directory) > limits['disk_bytes']: return 'over-disk' - sweeper.scan(children_only=True) # reap orphans adopted as subreaper - if on_tick is not None: - on_tick(elapsed) + sweeper.scan(children_only=True) # reap adopted orphans as they exit _leader_exited(exited, WATCH_INTERVAL) return None @@ -450,13 +630,31 @@ def _stop(exited, sweeper): def _finish(child, sweeper): - """Sweep the exited run, then reap the leader: (killed pids, survivors, exit status).""" + """Sweep the exited run, reap the leader, then reap every other child until none is left. + + Returns (killed pids, survivors, exit status). + """ + deadline = time.monotonic() + SWEEP_LIMIT killed, survivors = sweeper.sweep(SWEEP_LIMIT) try: - status = child.wait(timeout=SWEEP_LIMIT) + status = child.wait(timeout=max(0.0, deadline - time.monotonic())) except subprocess.TimeoutExpired: - status = None - return killed, survivors, status + return killed, survivors, None + sweeper.leader = None # reaped: its ids may now be reused, so they no longer identify the run + while True: + try: + pid, _ = os.waitpid(-1, os.WNOHANG) + except ChildProcessError: + return killed, survivors, status + if pid: + continue + alive = sweeper.scan(children_only=True) + if time.monotonic() >= deadline: + return killed, sorted(set(survivors) | set(alive)), status + for pid in alive: + if sweeper.signal(pid, signal.SIGKILL): + killed.add(pid) + time.sleep(SWEEP_PAUSE) # --- progress ----------------------------------------------------------------- @@ -546,3 +744,7 @@ def progress(directory): finally: os.close(directory_fd) return result + + +if __name__ == '__main__': + sys.exit(_custodian_main(sys.argv[1:])) From f8367c17b269418e25a40c6c12ba19f9efda3934 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 12 Nov 2026 01:15:14 -0700 Subject: [PATCH 023/131] feat(project): build a plan and record runs and products builds.execute runs a plan's steps in order from the commit's snapshot through the launcher: it resolves placeholders, uses the environment's checked interpreter, records each run and its product, checks declared outputs, and imports a benchmark's results. The project lock is released while a command runs, and a GPU step holds a machine-wide lock. A definition is now running, built, out of date or failed: out of date when its definition, its settings file, an input's product or its code changed since the run, or when something it uses is out of date. Plans show built steps as built and say why a step is out of date. Command line: build (with --scratch, --yes and --env), runs, products. Co-Authored-By: Claude Fable 5.2 --- .../tuldok_project/buildable/code/common.py | 31 + .../tuldok_project/buildable/code/hold.py | 14 + .../buildable/code/make_data.py | 21 + .../tuldok_project/buildable/code/score.py | 35 + .../buildable/code/settings/fit-a.json | 1 + .../tuldok_project/buildable/code/train.py | 25 + .../buildable/project/README.md | 2 + .../buildable/project/benchmarks/score.json | 21 + .../project/charts/score-ranking.json | 9 + .../buildable/project/datasets/numbers.json | 15 + .../project/environments/test-python.json | 8 + .../buildable/project/recipes/fit-a.json | 13 + .../buildable/project/recipes/fit-b.json | 13 + .../buildable/project/steps/gpu-one.json | 12 + .../buildable/project/steps/gpu-two.json | 12 + .../buildable/project/tuldok.json | 6 + tests/test_tuldok_project_builds.py | 672 +++++++++++++++ tests/test_tuldok_project_cli.py | 2 +- tests/test_tuldok_project_environments.py | 4 +- tests/test_tuldok_project_plan.py | 6 +- tuldok_project/__main__.py | 145 +++- tuldok_project/builds.py | 815 ++++++++++++++++++ tuldok_project/graph.py | 24 +- tuldok_project/plan.py | 35 +- tuldok_project/store.py | 28 +- 25 files changed, 1938 insertions(+), 31 deletions(-) create mode 100644 tests/fixtures/tuldok_project/buildable/code/common.py create mode 100644 tests/fixtures/tuldok_project/buildable/code/hold.py create mode 100644 tests/fixtures/tuldok_project/buildable/code/make_data.py create mode 100644 tests/fixtures/tuldok_project/buildable/code/score.py create mode 100644 tests/fixtures/tuldok_project/buildable/code/settings/fit-a.json create mode 100644 tests/fixtures/tuldok_project/buildable/code/train.py create mode 100644 tests/fixtures/tuldok_project/buildable/project/README.md create mode 100644 tests/fixtures/tuldok_project/buildable/project/benchmarks/score.json create mode 100644 tests/fixtures/tuldok_project/buildable/project/charts/score-ranking.json create mode 100644 tests/fixtures/tuldok_project/buildable/project/datasets/numbers.json create mode 100644 tests/fixtures/tuldok_project/buildable/project/environments/test-python.json create mode 100644 tests/fixtures/tuldok_project/buildable/project/recipes/fit-a.json create mode 100644 tests/fixtures/tuldok_project/buildable/project/recipes/fit-b.json create mode 100644 tests/fixtures/tuldok_project/buildable/project/steps/gpu-one.json create mode 100644 tests/fixtures/tuldok_project/buildable/project/steps/gpu-two.json create mode 100644 tests/fixtures/tuldok_project/buildable/project/tuldok.json create mode 100644 tests/test_tuldok_project_builds.py create mode 100644 tuldok_project/builds.py diff --git a/tests/fixtures/tuldok_project/buildable/code/common.py b/tests/fixtures/tuldok_project/buildable/code/common.py new file mode 100644 index 00000000..a1c9bfb7 --- /dev/null +++ b/tests/fixtures/tuldok_project/buildable/code/common.py @@ -0,0 +1,31 @@ +"""Hooks the tests use to make a stand-in command fail, stall, pause or leave out its output. + +Each BUILDABLE_* variable names the scripts it applies to, separated by commas. +""" +import os +import sys +import time + + +def _named(variable, script): + return script in os.environ.get(variable, '').split(',') + + +def before(script): + """Run the hooks that act before a script does its work.""" + if _named('BUILDABLE_FAIL', script): + print(f'{script}: failing as asked', file=sys.stderr) + sys.exit(3) + if _named('BUILDABLE_STALL', script): + time.sleep(60) + hold = os.environ.get('BUILDABLE_HOLD', '') + if hold.startswith(script + ':'): + directory = hold[len(script) + 1:] + open(os.path.join(directory, 'started'), 'w').close() + deadline = time.monotonic() + 30 + while not os.path.exists(os.path.join(directory, 'release')) and time.monotonic() < deadline: + time.sleep(0.05) + + +def skip_output(script): + return _named('BUILDABLE_SKIP_OUTPUT', script) diff --git a/tests/fixtures/tuldok_project/buildable/code/hold.py b/tests/fixtures/tuldok_project/buildable/code/hold.py new file mode 100644 index 00000000..bb08bc5b --- /dev/null +++ b/tests/fixtures/tuldok_project/buildable/code/hold.py @@ -0,0 +1,14 @@ +"""Hold "the GPU" for a moment and write when: the stand-in GPU step. It uses no GPU.""" +import argparse +import json +import os +import time + +parser = argparse.ArgumentParser() +parser.add_argument('--out', required=True) +arguments = parser.parse_args() +started = time.time() +time.sleep(float(os.environ.get('BUILDABLE_HOLD_SECONDS', '0.6'))) +with open(os.path.join(arguments.out, 'times.json'), 'w', encoding='utf-8') as handle: + json.dump({'started': started, 'ended': time.time(), + 'cuda_visible_devices': os.environ.get('CUDA_VISIBLE_DEVICES')}, handle) diff --git a/tests/fixtures/tuldok_project/buildable/code/make_data.py b/tests/fixtures/tuldok_project/buildable/code/make_data.py new file mode 100644 index 00000000..32130e2f --- /dev/null +++ b/tests/fixtures/tuldok_project/buildable/code/make_data.py @@ -0,0 +1,21 @@ +"""Write a few numbers from a seed: the stand-in dataset.""" +import argparse +import json +import os +import random + +import common + +parser = argparse.ArgumentParser() +parser.add_argument('--settings', required=True) +parser.add_argument('--out', required=True) +arguments = parser.parse_args() +common.before('make_data') +with open(arguments.settings, encoding='utf-8') as handle: + settings = json.load(handle) +generator = random.Random(settings['seed']) +numbers = [round(generator.uniform(-1, 1), 6) for _ in range(settings['count'])] +print(os.environ.get('BUILDABLE_LABEL', '')) +if not common.skip_output('make_data'): + with open(os.path.join(arguments.out, 'numbers.json'), 'w', encoding='utf-8') as handle: + json.dump({'numbers': numbers}, handle) diff --git a/tests/fixtures/tuldok_project/buildable/code/score.py b/tests/fixtures/tuldok_project/buildable/code/score.py new file mode 100644 index 00000000..f84e6f5b --- /dev/null +++ b/tests/fixtures/tuldok_project/buildable/code/score.py @@ -0,0 +1,35 @@ +"""Score one subject on the numbers and write a tuldok_results_v1 values file: the stand-in benchmark.""" +import argparse +import json +import os +import time + +import common + +parser = argparse.ArgumentParser() +parser.add_argument('--subject', required=True) +parser.add_argument('--name', required=True) +parser.add_argument('--data', required=True) +parser.add_argument('--out', required=True) +arguments = parser.parse_args() +common.before('score') +with open(arguments.data, encoding='utf-8') as handle: + numbers = json.load(handle)['numbers'] +if arguments.subject.startswith('constant:'): + constant = float(arguments.subject[len('constant:'):]) +else: + with open(arguments.subject, encoding='utf-8') as handle: + constant = json.load(handle)['constant'] +values = [] +for index, number in enumerate(numbers): + started = time.perf_counter() + error = abs(number - constant) + values.append({'case': f'case-{index}', 'metric': 'error', 'value': error}) + values.append({'case': f'case-{index}', 'metric': 'seconds', 'value': time.perf_counter() - started}) +metric = 'unknown-metric' if os.environ.get('BUILDABLE_BAD_RESULTS') else None +if metric: + values[0]['metric'] = metric +document = {'format': 'tuldok_results_v1', 'benchmark': 'score', 'subject': arguments.name, + 'commit': '', 'produced': time.strftime('%Y-%m-%d', time.gmtime()), 'values': values} +with open(os.path.join(arguments.out, 'values.json'), 'w', encoding='utf-8') as handle: + json.dump(document, handle) diff --git a/tests/fixtures/tuldok_project/buildable/code/settings/fit-a.json b/tests/fixtures/tuldok_project/buildable/code/settings/fit-a.json new file mode 100644 index 00000000..c9167fbf --- /dev/null +++ b/tests/fixtures/tuldok_project/buildable/code/settings/fit-a.json @@ -0,0 +1 @@ +{"steps": 4, "scale": 2.0} diff --git a/tests/fixtures/tuldok_project/buildable/code/train.py b/tests/fixtures/tuldok_project/buildable/code/train.py new file mode 100644 index 00000000..d88da73c --- /dev/null +++ b/tests/fixtures/tuldok_project/buildable/code/train.py @@ -0,0 +1,25 @@ +""""Train" a constant from the numbers, printing progress lines: the stand-in recipe.""" +import argparse +import json +import os + +import common + +parser = argparse.ArgumentParser() +parser.add_argument('--data', required=True) +parser.add_argument('--settings', required=True) +parser.add_argument('--out', required=True) +arguments = parser.parse_args() +common.before('train') +with open(arguments.data, encoding='utf-8') as handle: + numbers = json.load(handle)['numbers'] +with open(arguments.settings, encoding='utf-8') as handle: + settings = json.load(handle) +guess = 0.0 +for step in range(1, settings['steps'] + 1): + guess += (sum(numbers) / len(numbers) - guess) * min(1.0, settings['scale'] / 4) + print(json.dumps({'format': 'tuldok_progress_v1', 'stage': 'fit', 'completed': step, + 'total': settings['steps'], 'metrics': {'guess': guess}}), flush=True) +if not common.skip_output('train'): + with open(os.path.join(arguments.out, 'weights.json'), 'w', encoding='utf-8') as handle: + json.dump({'constant': guess, 'settings': settings}, handle) diff --git a/tests/fixtures/tuldok_project/buildable/project/README.md b/tests/fixtures/tuldok_project/buildable/project/README.md new file mode 100644 index 00000000..fde66a96 --- /dev/null +++ b/tests/fixtures/tuldok_project/buildable/project/README.md @@ -0,0 +1,2 @@ +A small project made for building in tests. Its commands are tiny Python +scripts in ../code that need only the standard library. diff --git a/tests/fixtures/tuldok_project/buildable/project/benchmarks/score.json b/tests/fixtures/tuldok_project/buildable/project/benchmarks/score.json new file mode 100644 index 00000000..79896a94 --- /dev/null +++ b/tests/fixtures/tuldok_project/buildable/project/benchmarks/score.json @@ -0,0 +1,21 @@ +{ + "format": "tuldok_definition_v1", + "kind": "benchmark", + "title": "Error on the numbers", + "run": { + "command": ["python", "score.py", "--subject", "{subject}", "--name", "{subject.name}", "--data", "{inputs.data}", "--out", "{output}"], + "environment": "environments/test-python", + "inputs": {"data": {"from": "datasets/numbers", "output": "data"}}, + "outputs": {"results": {"path": "values.json", "role": "results"}}, + "sources": ["score.py", "common.py"] + }, + "metrics": [ + {"id": "error", "title": "Absolute error", "better": "lower"}, + {"id": "seconds", "title": "Time per case", "units": "s", "better": "lower"} + ], + "subjects": [ + {"name": "fit-a", "title": "Fit a", "recipe": "recipes/fit-a", "argument": "{recipe}/weights.json"}, + {"name": "zero", "title": "Always zero", "argument": "constant:0"} + ], + "cases": {"dataset": "datasets/numbers", "split": "test", "count": 6} +} diff --git a/tests/fixtures/tuldok_project/buildable/project/charts/score-ranking.json b/tests/fixtures/tuldok_project/buildable/project/charts/score-ranking.json new file mode 100644 index 00000000..5a99f2d7 --- /dev/null +++ b/tests/fixtures/tuldok_project/buildable/project/charts/score-ranking.json @@ -0,0 +1,9 @@ +{ + "format": "tuldok_definition_v1", + "kind": "chart", + "title": "Error by subject", + "benchmark": "benchmarks/score", + "form": "ranking", + "metric": "error", + "statistic": "mean" +} diff --git a/tests/fixtures/tuldok_project/buildable/project/datasets/numbers.json b/tests/fixtures/tuldok_project/buildable/project/datasets/numbers.json new file mode 100644 index 00000000..387eaa87 --- /dev/null +++ b/tests/fixtures/tuldok_project/buildable/project/datasets/numbers.json @@ -0,0 +1,15 @@ +{ + "format": "tuldok_definition_v1", + "kind": "dataset", + "title": "A few numbers", + "run": { + "command": ["python", "make_data.py", "--settings", "{settings}", "--out", "{output}"], + "environment": "environments/test-python", + "settings": {"count": 6, "seed": 3}, + "env": {"BUILDABLE_LABEL": "numbers in {output}"}, + "outputs": {"data": {"path": "numbers.json", "role": "data"}}, + "resources": {"wall_hours": 0.05, "disk_gb": 0.01}, + "sources": ["make_data.py", "common.py"] + }, + "splits": {"test": 6} +} diff --git a/tests/fixtures/tuldok_project/buildable/project/environments/test-python.json b/tests/fixtures/tuldok_project/buildable/project/environments/test-python.json new file mode 100644 index 00000000..abdf5bae --- /dev/null +++ b/tests/fixtures/tuldok_project/buildable/project/environments/test-python.json @@ -0,0 +1,8 @@ +{ + "format": "tuldok_definition_v1", + "kind": "environment", + "title": "The interpreter running the tests", + "python": "3.12", + "device": "cpu", + "packages": {"jsonschema": "4.26.0"} +} diff --git a/tests/fixtures/tuldok_project/buildable/project/recipes/fit-a.json b/tests/fixtures/tuldok_project/buildable/project/recipes/fit-a.json new file mode 100644 index 00000000..a15c5669 --- /dev/null +++ b/tests/fixtures/tuldok_project/buildable/project/recipes/fit-a.json @@ -0,0 +1,13 @@ +{ + "format": "tuldok_definition_v1", + "kind": "recipe", + "title": "Fit a, from a settings file", + "run": { + "command": ["python", "train.py", "--data", "{inputs.data}", "--settings", "{settings}", "--out", "{output}"], + "environment": "environments/test-python", + "inputs": {"data": {"from": "datasets/numbers", "output": "data"}}, + "settings_file": "settings/fit-a.json", + "outputs": {"weights": {"path": "weights.json", "role": "weights"}}, + "sources": ["train.py", "common.py"] + } +} diff --git a/tests/fixtures/tuldok_project/buildable/project/recipes/fit-b.json b/tests/fixtures/tuldok_project/buildable/project/recipes/fit-b.json new file mode 100644 index 00000000..ddd19f9e --- /dev/null +++ b/tests/fixtures/tuldok_project/buildable/project/recipes/fit-b.json @@ -0,0 +1,13 @@ +{ + "format": "tuldok_definition_v1", + "kind": "recipe", + "title": "Fit b, with inline settings", + "run": { + "command": ["python", "train.py", "--data", "{inputs.data}/numbers.json", "--settings", "{settings}", "--out", "{output}"], + "environment": "environments/test-python", + "inputs": {"data": "datasets/numbers"}, + "settings": {"steps": 3, "scale": 0.5}, + "outputs": {"weights": {"path": "weights.json", "role": "weights"}}, + "sources": ["train.py", "common.py"] + } +} diff --git a/tests/fixtures/tuldok_project/buildable/project/steps/gpu-one.json b/tests/fixtures/tuldok_project/buildable/project/steps/gpu-one.json new file mode 100644 index 00000000..fca23b7b --- /dev/null +++ b/tests/fixtures/tuldok_project/buildable/project/steps/gpu-one.json @@ -0,0 +1,12 @@ +{ + "format": "tuldok_definition_v1", + "kind": "step", + "title": "A stand-in GPU step (one); uses no GPU", + "run": { + "command": ["python", "hold.py", "--out", "{output}"], + "environment": "environments/test-python", + "outputs": {"times": {"path": "times.json", "role": "file"}}, + "resources": {"gpu": true}, + "sources": ["hold.py"] + } +} diff --git a/tests/fixtures/tuldok_project/buildable/project/steps/gpu-two.json b/tests/fixtures/tuldok_project/buildable/project/steps/gpu-two.json new file mode 100644 index 00000000..360d7cc2 --- /dev/null +++ b/tests/fixtures/tuldok_project/buildable/project/steps/gpu-two.json @@ -0,0 +1,12 @@ +{ + "format": "tuldok_definition_v1", + "kind": "step", + "title": "A stand-in GPU step (two); uses no GPU", + "run": { + "command": ["python", "hold.py", "--out", "{output}"], + "environment": "environments/test-python", + "outputs": {"times": {"path": "times.json", "role": "file"}}, + "resources": {"gpu": true}, + "sources": ["hold.py"] + } +} diff --git a/tests/fixtures/tuldok_project/buildable/project/tuldok.json b/tests/fixtures/tuldok_project/buildable/project/tuldok.json new file mode 100644 index 00000000..d60bce64 --- /dev/null +++ b/tests/fixtures/tuldok_project/buildable/project/tuldok.json @@ -0,0 +1,6 @@ +{ + "format": "tuldok_project_v1", + "id": "8739384997054a9380317e1dac0f240f", + "name": "Buildable test project", + "code_root": "../code" +} diff --git a/tests/test_tuldok_project_builds.py b/tests/test_tuldok_project_builds.py new file mode 100644 index 00000000..1ad838f8 --- /dev/null +++ b/tests/test_tuldok_project_builds.py @@ -0,0 +1,672 @@ +"""Building a plan (docs/plans/definition-first-projects/spec-m6.md, sections 4 to 6 and 8): runs, products, states. + +Placeholders and the precedence of build states are tested as pure functions. +Everything else needs a database and runs only when TULDOK_DATABASE_URL names +a disposable cluster (spec-m1-m2.md, section 1). Each of those tests copies +tests/fixtures/tuldok_project/buildable into a temporary directory, gives it +a fresh project id, makes its code a Git repository of its own with one +commit, points TULDOK_PROJECT_HOME at a temporary directory, connects the +fixture's environment to the interpreter running the tests, and drops the +project's schema afterwards. The commands are the fixture's stand-in scripts: +they need only the standard library, finish in well under a second, and are +made to fail, stall, pause or leave out an output through BUILDABLE_* +variables passed as extra environment. No GPU is used: the two "GPU" steps +only declare gpu: true and sleep. +""" +import json +import os +from pathlib import Path +import shutil +import subprocess +import sys +import tempfile +import time +import unittest +from unittest import mock +import uuid + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) + +from tuldok_project import builds, charts, environments, graph, launcher, local, plan, snapshot, store # noqa: E402 +from tuldok_project.store import ProjectError # noqa: E402 + +REPOSITORY = Path(__file__).resolve().parents[1] +FIXTURE = REPOSITORY / 'tests' / 'fixtures' / 'tuldok_project' / 'buildable' +DATABASE = os.environ.get('TULDOK_DATABASE_URL') +GIT = ['git', '-c', 'user.name=Tuldok Test', '-c', 'user.email=test@example.invalid', '-c', 'commit.gpgsign=false'] +TARGETS = ('datasets/numbers', 'recipes/fit-a', 'benchmarks/score') + + +def _documents(): + return {f'{path.parent.name}/{path.stem}': json.loads(path.read_text(encoding='utf-8')) + for path in sorted((FIXTURE / 'project').glob('*/*.json'))} + + +class Fill(unittest.TestCase): + """builds.fill: the placeholder rules of documents.py, with values.""" + + def test_names_and_literal_braces(self): + self.assertEqual(builds.fill('--out={output} {{x}} {inputs.a}/f', {'output': '/o', 'inputs.a': '/a'}), + '--out=/o {x} /a/f') + self.assertEqual(builds.fill('{{{output}}}', {'output': 'o'}), '{o}') + self.assertEqual(builds.fill('plain', {}), 'plain') + + def test_an_unknown_name_and_a_stray_brace(self): + with self.assertRaises(KeyError) as raised: + builds.fill('{inputs.b}', {'output': 'o'}) + self.assertEqual(raised.exception.args[0], 'inputs.b') + for text in ('{output', 'out}', '{a{b}'): + with self.assertRaises(ValueError): + builds.fill(text, {'output': 'o'}) + + +class States(unittest.TestCase): + """graph.states' local argument for build states, and the plan's built action (section 5).""" + + def setUp(self): + self.documents = _documents() + + def test_build_states_override_by_their_precedence(self): + self.documents['recipes/fit-b']['earlier_work'] = {'rebuild': 'needs-work', 'reason': 'Test.'} + local = {'datasets/numbers': 'built', 'recipes/fit-a': 'out-of-date', 'steps/gpu-one': 'running', + 'steps/gpu-two': 'failed', 'recipes/fit-b': 'failed', 'benchmarks/score': 'ready', + 'environments/test-python': 'ready', 'charts/score-ranking': 'built'} + states = graph.states(self.documents, local) + self.assertEqual(states['datasets/numbers'], 'built') + self.assertEqual(states['recipes/fit-a'], 'out-of-date') + self.assertEqual(states['steps/gpu-one'], 'running') + self.assertEqual(states['steps/gpu-two'], 'failed') + self.assertEqual(states['recipes/fit-b'], 'needs-work') # held wins over failed (no product) + self.assertEqual(states['benchmarks/score'], 'not-built') # not a build state: ignored + self.assertEqual(states['environments/test-python'], 'ready') + self.assertEqual(states['charts/score-ranking'], 'none') + built = graph.states(self.documents, {'recipes/fit-b': 'built'}) + self.assertEqual(built['recipes/fit-b'], 'built') # a current product wins over needs-work + + def test_the_built_action_is_not_work(self): + local = {'environments/test-python': 'ready', 'datasets/numbers': 'built', 'recipes/fit-a': 'out-of-date'} + made = plan.make_plan(self.documents, ['recipes/fit-a'], local=local, + built={'recipes/fit-a': {'causes': ['its code changed'], 'scratch': False}, + 'datasets/numbers': {'causes': [], 'scratch': True}}) + actions = {step['reference']: (step['action'], step['reasons'], step['scratch']) for step in made['steps']} + self.assertEqual(actions, {'environments/test-python': ('ready', [], False), + 'datasets/numbers': ('built', [], True), + 'recipes/fit-a': ('build', ['its code changed'], False)}) + self.assertEqual(made['counts'], {'build': 1, 'set-up': 0, 'blocked': 0, 'ready': 1, 'built': 1}) + + +class NoGit(unittest.TestCase): + + def test_a_code_root_outside_git_has_no_code_cause(self): + with tempfile.TemporaryDirectory() as directory: + self.assertEqual(builds._changes(directory, {'a' * 40}), {}) + + +def _writable(root): + for current, directories, _files in os.walk(root): + for name in directories: + path = os.path.join(current, name) + if not os.path.islink(path): + os.chmod(path, 0o755) + if os.path.isdir(root): + os.chmod(root, 0o755) + + +@unittest.skipUnless(DATABASE, 'TULDOK_DATABASE_URL is not set; database tests need a disposable cluster.') +class BuildCase(unittest.TestCase): + """A fresh Git-committed copy of the buildable fixture, its environment connected.""" + + def setUp(self): + directory = tempfile.TemporaryDirectory() + self.addCleanup(directory.cleanup) + self.temporary = Path(directory.name) + self.home = self.temporary / 'home' + self.addCleanup(_writable, self.home) # runs before the directory is removed + patcher = mock.patch.dict(os.environ, {local.HOME_VARIABLE: str(self.home)}) + patcher.start() + self.addCleanup(patcher.stop) + shutil.copytree(FIXTURE, self.temporary / 'buildable') + self.root = self.temporary / 'buildable' + self.folder = self.root / 'project' + self.code = self.root / 'code' + self.project_id = uuid.uuid4().hex + project_file = self.folder / 'tuldok.json' + document = json.loads(project_file.read_text(encoding='utf-8')) + document['id'] = self.project_id + project_file.write_text(json.dumps(document, indent=2) + '\n', encoding='utf-8') + self.git('init', '-q') + self.commit('The fixture.') + self.addCleanup(store.drop_project, self.project_id) + with self.opened() as project: + self.assertTrue(environments.connect(project, 'environments/test-python', sys.executable)['ok']) + + def git(self, *arguments): + subprocess.run([*GIT, '-C', str(self.root), *arguments], check=True, capture_output=True, timeout=60) + + def commit(self, message): + self.git('add', '-A') + self.git('commit', '-q', '-m', message) + + def opened(self): + return store.open_project(self.folder) + + def plan(self, *targets, every=False): + with self.opened() as project: + return plan.build_plan(project, list(targets), every=every) + + def build(self, *targets, extra_env=None, scratch=False, answer=True): + made = self.plan(*targets) + self.asked = [] + + def confirm(given): + self.asked.append(given) + return answer + + return builds.execute(self.folder, made, confirm=confirm, extra_env=extra_env, scratch=scratch) + + def states(self): + with self.opened() as project: + return {row['reference']: row['state'] for row in project.definitions()} + + def runs(self, reference=None): + with self.opened() as project: + return builds.runs(project, reference) + + def products(self, reference=None): + with self.opened() as project: + return builds.products(project, reference) + + def status(self): + with self.opened() as project: + return builds.status(project) + + def ran(self, done): + return [(item['reference'], item['subject'], item['state']) for item in done['steps']] + + def edit(self, reference, change): + with self.opened() as project: + document = project.definition(reference)['document'] + change(document) + project.set_definition(reference, json.dumps(document, indent=2) + '\n') + project.save() + + def write_code(self, path, text): + target = self.code / path + target.write_text(text, encoding='utf-8') + + def build_all(self): + done = self.build('benchmarks/score') + self.assertTrue(done['ok'], done) + return done + + +class FullBuild(BuildCase): + + def test_a_full_build_from_nothing(self): + before = self.states() + self.assertEqual({reference: before[reference] for reference in TARGETS}, + {reference: 'not-built' for reference in TARGETS}) + with mock.patch.object(environments, 'probe', wraps=environments.probe) as probe: + done = self.build('benchmarks/score') + self.assertEqual(probe.call_count, 1) # the environment is checked once per build + self.assertTrue(done['ok']) + self.assertEqual(len(self.asked), 1) + self.assertEqual(self.ran(done), [('datasets/numbers', '', 'succeeded'), ('recipes/fit-a', '', 'succeeded'), + ('benchmarks/score', 'fit-a', 'succeeded'), + ('benchmarks/score', 'zero', 'succeeded')]) + after = self.states() + self.assertEqual({reference: after[reference] for reference in TARGETS}, + {reference: 'built' for reference in TARGETS}) + self.assertEqual(after['recipes/fit-b'], 'not-built') + + products = {(item['reference'], item['subject']): item for item in self.products()} + self.assertEqual(sorted(products), [('benchmarks/score', 'fit-a'), ('benchmarks/score', 'zero'), + ('datasets/numbers', ''), ('recipes/fit-a', '')]) + for item in products.values(): + self.assertFalse(item['scratch']) + self.assertEqual(item['directory'], os.path.join(self.home, self.project_id, 'runs', item['run_id'], 'output')) + for output in item['outputs'].values(): + self.assertEqual(output['bytes'], os.path.getsize(os.path.join(item['directory'], output['path']))) + self.assertEqual(products['recipes/fit-a', '']['outputs'], + {'weights': {'path': 'weights.json', 'role': 'weights', + 'bytes': products['recipes/fit-a', '']['outputs']['weights']['bytes']}}) + + runs = {(row['reference'], row['subject']): row for row in self.runs()} + commit = subprocess.run(['git', '-C', str(self.root), 'rev-parse', 'HEAD'], capture_output=True, + text=True, check=True).stdout.strip() + data, fit = runs['datasets/numbers', ''], runs['recipes/fit-a', ''] + self.assertEqual((fit['commit'], fit['scratch'], fit['owner_pid']), (commit, False, os.getpid())) + self.assertEqual(fit['argv'][0], sys.executable) + self.assertEqual(fit['inputs'], {'data': {'reference': 'datasets/numbers', 'run_id': data['id'], + 'output': 'data'}}) + self.assertEqual(fit['argv'][1:5], ['train.py', '--data', + os.path.join(products['datasets/numbers', '']['directory'], 'numbers.json'), + '--settings']) + snapshot_root = os.path.join(self.home, self.project_id, 'code', commit, 'code') + self.assertEqual(fit['argv'][5], os.path.join(snapshot_root, 'settings/fit-a.json')) + self.assertEqual(fit['environment']['interpreter'], sys.executable) + self.assertEqual(runs['benchmarks/score', 'fit-a']['inputs']['{recipe}']['run_id'], fit['id']) + self.assertIn(os.path.join(products['recipes/fit-a', '']['directory'], 'weights.json'), + runs['benchmarks/score', 'fit-a']['argv']) + self.assertIn('constant:0', runs['benchmarks/score', 'zero']['argv']) + with self.opened() as project: + env = project._execute('SELECT env, settings FROM {schema}.runs WHERE id = %s', (data['id'],)).fetchone() + self.assertEqual(env[0]['CUDA_VISIBLE_DEVICES'], '') + self.assertEqual((env[0]['PYTHONDONTWRITEBYTECODE'], env[0]['PYTHONUNBUFFERED']), ('1', '1')) + self.assertEqual(env[0]['BUILDABLE_LABEL'], f'numbers in {products["datasets/numbers", ""]["directory"]}') + self.assertTrue(set(env[0]) <= {*builds.PASSED_VARIABLES, 'PYTHONDONTWRITEBYTECODE', 'PYTHONUNBUFFERED', + 'CUDA_VISIBLE_DEVICES', 'BUILDABLE_LABEL'}) + settings_path = os.path.join(data['directory'], 'settings.json') + self.assertEqual(json.loads(Path(settings_path).read_text()), {'count': 6, 'seed': 3}) + self.assertEqual(env[1], Path(settings_path).read_text()) + self.assertFalse(os.access(snapshot_root, os.W_OK)) + event = launcher.progress(fit['directory'])['event'] + self.assertEqual((event['stage'], event['completed'], event['total']), ('fit', 4, 4)) + + with self.opened() as project: + summaries = project.result_summaries('score', metric='error') + self.assertEqual(sorted({(item.row.subject, item.origin, item.row.count) for item in summaries}), + [('fit-a', 'values', 6), ('zero', 'values', 6)]) + data_chart = charts.chart_data(project, 'charts/score-ranking') + points = data_chart['series'][0]['points'] + self.assertEqual(sorted(point['subject'] for point in points), ['fit-a', 'zero']) + self.assertEqual(data_chart['missing'], []) + + def test_a_second_build_runs_nothing(self): + self.build_all() + count = len(self.runs()) + made = self.plan('benchmarks/score') + self.assertEqual(made['counts']['build'], 0) + self.assertEqual({step['reference']: step['action'] for step in made['steps']}, + {'environments/test-python': 'ready', 'datasets/numbers': 'built', + 'recipes/fit-a': 'built', 'benchmarks/score': 'built'}) + with mock.patch.object(environments, 'probe', wraps=environments.probe) as probe: + done = self.build('benchmarks/score') + self.assertEqual(probe.call_count, 0) + self.assertTrue(done['ok']) + self.assertEqual(done['steps'], []) + self.assertEqual(done['skipped'], list(TARGETS)) + self.assertEqual(len(self.runs()), count) + + def test_a_product_made_current_replaces_the_earlier_one(self): + self.build_all() + first = {item['reference']: item['run_id'] for item in self.products()} + self.edit('datasets/numbers', lambda document: document['run']['settings'].update(count=5)) + self.build('datasets/numbers') + with self.opened() as project: + rows = project._execute("SELECT run_id, current FROM {schema}.products " + "WHERE reference = 'datasets/numbers'").fetchall() + self.assertEqual(len(rows), 2) + self.assertEqual(dict(rows)[first['datasets/numbers']], False) + self.assertTrue(os.path.isdir(self.runs('datasets/numbers')[1]['directory'])) # nothing deleted + + +class OutOfDate(BuildCase): + """The four causes of section 5, each with the plan's reasons and a rebuild of only what is needed.""" + + def step(self, made, reference): + return next(step for step in made['steps'] if step['reference'] == reference) + + def rebuild(self, expected): + count = len(self.runs()) + done = self.build('benchmarks/score') + self.assertTrue(done['ok'], done) + self.assertEqual(self.ran(done), expected) + self.assertEqual(len(self.runs()), count + len(expected)) + states = self.states() + self.assertEqual({reference: states[reference] for reference in TARGETS}, + {reference: 'built' for reference in TARGETS}) + + def test_the_definition_changed(self): + self.build_all() + self.edit('recipes/fit-a', lambda document: document.update(description='Now described.')) + states = self.states() + self.assertEqual((states['datasets/numbers'], states['recipes/fit-a'], states['benchmarks/score']), + ('built', 'out-of-date', 'out-of-date')) + made = self.plan('benchmarks/score') + fit = self.step(made, 'recipes/fit-a') + self.assertEqual(fit['action'], 'build') + self.assertEqual(len(fit['reasons']), 1) + self.assertTrue(fit['reasons'][0].startswith('its definition changed since run')) + self.assertEqual(self.step(made, 'benchmarks/score')['reasons'], + ['subject fit-a: the recipe recipes/fit-a of its subject is out of date']) + self.assertEqual(self.step(made, 'datasets/numbers')['action'], 'built') + self.rebuild([('recipes/fit-a', '', 'succeeded'), ('benchmarks/score', 'fit-a', 'succeeded')]) + + def test_the_settings_file_changed(self): + self.build_all() + self.write_code('settings/fit-a.json', '{"steps": 2, "scale": 1.0}\n') + self.commit('Fewer steps.') + reasons = self.step(self.plan('benchmarks/score'), 'recipes/fit-a')['reasons'] + self.assertEqual(len(reasons), 1) + self.assertTrue(reasons[0].startswith('its settings file settings/fit-a.json changed since run'), reasons) + self.rebuild([('recipes/fit-a', '', 'succeeded'), ('benchmarks/score', 'fit-a', 'succeeded')]) + fit = self.runs('recipes/fit-a')[0] + self.assertEqual(launcher.progress(fit['directory'])['event']['total'], 2) + + def test_an_input_was_rebuilt(self): + self.build_all() + self.edit('datasets/numbers', lambda document: document['run']['settings'].update(count=4)) + self.assertEqual(self.states()['recipes/fit-a'], 'out-of-date') + self.assertEqual(self.step(self.plan('recipes/fit-a'), 'recipes/fit-a')['reasons'], + ['its input data (datasets/numbers) is out of date']) + done = self.build('datasets/numbers') + self.assertEqual(self.ran(done), [('datasets/numbers', '', 'succeeded')]) + made = self.plan('benchmarks/score') + new_run = self.runs('datasets/numbers')[0]['id'] + self.assertEqual(self.step(made, 'recipes/fit-a')['reasons'], + [f'its input data (datasets/numbers) was rebuilt since (now run {new_run[:12]})']) + score = self.step(made, 'benchmarks/score')['reasons'] + self.assertIn(f'subject zero: its input data (datasets/numbers) was rebuilt since (now run {new_run[:12]})', + score) + self.rebuild([('recipes/fit-a', '', 'succeeded'), ('benchmarks/score', 'fit-a', 'succeeded'), + ('benchmarks/score', 'zero', 'succeeded')]) + + def test_an_input_has_no_current_product(self): + self.build_all() + with self.opened() as project: + project._execute("UPDATE {schema}.products SET current = false WHERE reference = 'datasets/numbers'") + self.assertEqual(builds.status(project)['recipes/fit-a']['causes'], + ['its input data (datasets/numbers) has no current product']) + + def test_the_code_changed(self): + self.build_all() + self.write_code('train.py', (self.code / 'train.py').read_text() + '# changed\n') + self.commit('Change training.') + with mock.patch.object(snapshot, 'changed_since', wraps=snapshot.changed_since) as changed: + states = self.states() + self.assertEqual(changed.call_count, 1) # one distinct commit among the current products + self.assertEqual((states['datasets/numbers'], states['recipes/fit-a'], states['benchmarks/score']), + ('built', 'out-of-date', 'out-of-date')) + made = self.plan('benchmarks/score') + reasons = self.step(made, 'recipes/fit-a')['reasons'] + self.assertEqual(len(reasons), 1) + self.assertTrue(reasons[0].startswith('its code changed since commit') and reasons[0].endswith(': train.py')) + self.rebuild([('recipes/fit-a', '', 'succeeded'), ('benchmarks/score', 'fit-a', 'succeeded')]) + # Two commits now among the current products: one call each. + with mock.patch.object(snapshot, 'changed_since', wraps=snapshot.changed_since) as changed: + self.states() + self.assertEqual(changed.call_count, 2) + + def test_an_uncommitted_change_counts_too(self): + self.build_all() + self.write_code('make_data.py', (self.code / 'make_data.py').read_text() + '# changed\n') + self.assertEqual(self.states()['datasets/numbers'], 'out-of-date') + + +class Scratch(BuildCase): + + def test_a_dirty_tree_is_refused_without_scratch(self): + self.write_code('train.py', (self.code / 'train.py').read_text() + '# not committed\n') + with self.assertRaises(ProjectError) as raised: + self.build('recipes/fit-a') + self.assertEqual((raised.exception.code, raised.exception.files), ('dirty', ['train.py'])) + self.assertEqual(self.asked, []) + self.assertEqual(self.runs(), []) + + def test_a_scratch_build_on_a_dirty_tree_is_marked(self): + self.write_code('train.py', (self.code / 'train.py').read_text() + '# not committed\n') + done = self.build('recipes/fit-a', scratch=True) + self.assertTrue(done['ok'], done) + self.assertEqual(self.states()['recipes/fit-a'], 'built') + self.assertTrue(all(item['scratch'] for item in self.products())) + fit = self.runs('recipes/fit-a')[0] + self.assertTrue(fit['scratch']) + self.assertTrue(fit['argv'][5].startswith(str(self.code))) # the code root in place + made = self.plan('recipes/fit-a') + self.assertEqual({step['reference']: (step['action'], step['scratch']) for step in made['steps']}, + {'environments/test-python': ('ready', False), 'datasets/numbers': ('built', True), + 'recipes/fit-a': ('built', True)}) + self.commit('Now committed.') + self.write_code('train.py', (self.code / 'train.py').read_text() + '# more\n') + self.commit('And changed again.') + self.assertEqual(self.states()['recipes/fit-a'], 'built') # never out of date because of code + + +class Failures(BuildCase): + """A step that does not succeed stops the build; later steps are not run.""" + + def assert_stopped_at_fit(self, done, state): + self.assertFalse(done['ok']) + self.assertEqual(self.ran(done), [('datasets/numbers', '', 'succeeded'), ('recipes/fit-a', '', state)]) + self.assertEqual(self.runs('benchmarks/score'), []) + states = self.states() + self.assertEqual((states['datasets/numbers'], states['recipes/fit-a'], states['benchmarks/score']), + ('built', 'failed', 'not-built')) + self.assertEqual(self.products('recipes/fit-a'), []) + return self.runs('recipes/fit-a')[0] + + def test_a_failing_command(self): + done = self.build('benchmarks/score', extra_env={'BUILDABLE_FAIL': 'train'}) + run = self.assert_stopped_at_fit(done, 'failed') + self.assertEqual(run['exit_status'], 3) + self.assertIn('exited with status 3', run['problem']) + self.assertIn('failing as asked', Path(run['directory'], 'stderr.log').read_text()) + reasons = next(step for step in self.plan('benchmarks/score')['steps'] + if step['reference'] == 'recipes/fit-a')['reasons'] + self.assertTrue(reasons[0].startswith(f'its last run {run["id"][:12]} ended failed'), reasons) + done = self.build('benchmarks/score') # the cause gone, the rest is built + self.assertTrue(done['ok']) + self.assertEqual([item['reference'] for item in done['steps']], + ['recipes/fit-a', 'benchmarks/score', 'benchmarks/score']) + + def test_a_timed_out_command(self): + self.edit('recipes/fit-a', lambda document: document['run'].update(resources={'wall_hours': 0.0003})) + started = time.monotonic() + done = self.build('benchmarks/score', extra_env={'BUILDABLE_STALL': 'train'}) + self.assertLess(time.monotonic() - started, 20) + run = self.assert_stopped_at_fit(done, 'timed-out') + self.assertIn('wall-time limit', run['problem']) + + def test_a_missing_output(self): + done = self.build('benchmarks/score', extra_env={'BUILDABLE_SKIP_OUTPUT': 'train'}) + run = self.assert_stopped_at_fit(done, 'failed') + self.assertEqual(run['problem'], 'The declared output weights (weights.json) was not written.') + self.assertEqual(run['exit_status'], 0) + + def test_a_refused_results_file(self): + done = self.build('benchmarks/score', extra_env={'BUILDABLE_BAD_RESULTS': '1'}) + self.assertFalse(done['ok']) + self.assertEqual(self.ran(done)[-1], ('benchmarks/score', 'fit-a', 'failed')) + self.assertEqual(len(done['steps']), 3) # the subject zero was not run + run = self.runs('benchmarks/score')[0] + self.assertTrue(run['problem'].startswith('The results file values.json was refused: /values/0/metric:'), + run['problem']) + self.assertEqual(self.products('benchmarks/score'), []) + self.assertEqual(self.states()['benchmarks/score'], 'failed') + with self.opened() as project: + self.assertEqual(project.result_summaries('score'), []) + + def test_an_environment_that_is_not_ready(self): + with self.opened() as project: + environments.disconnect(project, 'environments/test-python') + with self.assertRaises(ProjectError) as raised: + self.build('benchmarks/score') + self.assertEqual(raised.exception.code, 'not-ready') + self.assertIn('set it up or connect an interpreter', str(raised.exception)) + self.assertEqual(self.runs(), []) + + def test_a_missing_program_fails_before_anything_runs(self): + self.edit('datasets/numbers', lambda document: document['run'].update( + command=['no-such-program-tuldok', '{output}'])) + done = self.build('benchmarks/score') + self.assertEqual(self.ran(done), [('datasets/numbers', '', 'failed')]) + run = self.runs()[0] + self.assertEqual(run['problem'], 'The program no-such-program-tuldok was not found on PATH.') + self.assertIsNone(run['started_at']) + self.assertFalse(os.path.exists(run['directory'])) + + def test_a_blocked_target_is_refused_before_asking(self): + self.edit('recipes/fit-a', lambda document: document.update( + earlier_work={'rebuild': 'needs-work', 'reason': 'Its command needs a change.'})) + with self.assertRaises(ProjectError) as raised: + self.build('recipes/fit-a') + self.assertEqual(raised.exception.code, 'blocked') + self.assertEqual(self.asked, []) + self.assertEqual(self.runs(), []) + + def test_a_refused_confirmation_runs_nothing(self): + done = self.build('benchmarks/score', answer=False) + self.assertEqual((done['confirmed'], done['ok'], done['steps']), (False, False, [])) + self.assertEqual(self.runs(), []) + + +class Ownership(BuildCase): + """The project lock while a command runs, the GPU lock, orphans, removal.""" + + def cli(self, *arguments, **options): + environment = dict(os.environ, PYTHONDONTWRITEBYTECODE='1') + return subprocess.Popen([sys.executable, '-m', 'tuldok_project', *map(str, arguments)], cwd=REPOSITORY, + env={**environment, **options.pop('env', {})}, stdout=subprocess.PIPE, + stderr=subprocess.PIPE, text=True, **options) + + def test_the_project_is_not_held_while_a_command_runs(self): + hold = self.temporary / 'hold' + hold.mkdir() + child = self.cli('build', self.folder, 'datasets/numbers', '--yes', '--env', f'BUILDABLE_HOLD=make_data:{hold}') + try: + deadline = time.monotonic() + 30 + while not (hold / 'started').exists(): + self.assertIsNone(child.poll(), child.stderr.read() if child.poll() is not None else '') + self.assertLess(time.monotonic(), deadline) + time.sleep(0.05) + with self.opened() as project: # a second connection opens it while the command runs + rows = builds.runs(project) + self.assertEqual([(row['state'], row['owner_pid']) for row in rows], [('running', child.pid)]) + self.assertEqual({row['reference']: row['state'] for row in project.definitions()}['datasets/numbers'], + 'running') + self.assertEqual(plan.build_plan(project, ['datasets/numbers'])['steps'][1]['state'], 'running') + finally: + (hold / 'release').touch() + stdout, stderr = child.communicate(timeout=60) + self.assertEqual(child.returncode, 0, stderr) + self.assertEqual(self.states()['datasets/numbers'], 'built') + + def test_gpu_steps_take_turns(self): + first = self.cli('build', self.folder, 'steps/gpu-one', '--yes', env={'CUDA_VISIBLE_DEVICES': '7', + 'BUILDABLE_HOLD_SECONDS': '1.0'}) + try: + line = '' + while not line.startswith('start'): + line = first.stdout.readline() + self.assertTrue(line, first.stderr.read() if first.poll() is not None else 'no start line') + second = self.cli('build', self.folder, 'steps/gpu-two', '--yes', env={'BUILDABLE_HOLD_SECONDS': '0.2'}) + outputs = [process.communicate(timeout=60) for process in (second,)] + finally: + rest = first.communicate(timeout=60) + self.assertEqual(first.returncode, 0, rest[1]) + self.assertEqual(second.returncode, 0, outputs[0][1]) + times = {} + for item in self.products(): + times[item['reference']] = json.loads(Path(item['directory'], 'times.json').read_text()) + self.assertGreaterEqual(times['steps/gpu-two']['started'], times['steps/gpu-one']['ended']) + self.assertEqual(times['steps/gpu-one']['cuda_visible_devices'], '7') # left as the caller has it + self.assertTrue((self.home / builds.GPU_LOCK).exists()) + + def test_an_orphaned_running_row_becomes_unknown(self): + gone = subprocess.Popen([sys.executable, '-c', 'pass']) + gone.wait() + with self.opened() as project: + for run_id, pid, boot in (('a' * 32, gone.pid, builds.boot_id()), ('b' * 32, os.getpid(), 'another-boot'), + ('c' * 32, os.getpid(), builds.boot_id())): + project._execute('''INSERT INTO {schema}.runs (id, reference, plan_id, state, scratch, commit, + definition, inputs, argv, env, directory, owner_pid, owner_boot, queued_at) + VALUES (%s, 'steps/gpu-one', 'p', 'running', false, '', '{{}}', '{{}}', '[]', + '{{}}', '/nowhere', %s, %s, now())''', (run_id, pid, boot)) + rows = {row['id']: row for row in self.runs()} + self.assertEqual(rows['a' * 32]['state'], 'unknown') + self.assertEqual(rows['b' * 32]['state'], 'unknown') + self.assertIn('is gone', rows['a' * 32]['problem']) + self.assertEqual(rows['c' * 32]['state'], 'running') # this process is alive: left alone + with self.opened() as project: + project._execute("UPDATE {schema}.runs SET owner_pid = %s WHERE id = %s", (gone.pid, 'c' * 32)) + self.assertEqual(self.states()['steps/gpu-one'], 'failed') + self.assertEqual(self.runs()[0]['state'], 'unknown') + + def test_removing_a_definition_removes_its_records_not_its_files(self): + done = self.build('recipes/fit-b', 'steps/gpu-two', extra_env={'BUILDABLE_HOLD_SECONDS': '0'}) + self.assertTrue(done['ok'], done) + directory = self.products('recipes/fit-b')[0]['directory'] + with self.opened() as project: + project.remove_definition('recipes/fit-b') + self.assertEqual(self.runs('recipes/fit-b'), []) + self.assertEqual(self.products('recipes/fit-b'), []) + self.assertTrue(os.path.isdir(directory)) + (self.folder / 'steps' / 'gpu-two.json').unlink() # removed on disk, then opened + self.assertEqual(self.runs('steps/gpu-two'), []) + self.assertEqual(self.products('steps/gpu-two'), []) + self.assertEqual([item['reference'] for item in self.products()], ['datasets/numbers']) + + +class Commands(BuildCase): + """build, runs and products on the command line.""" + + def run_cli(self, *arguments, stdin=''): + environment = dict(os.environ, PYTHONDONTWRITEBYTECODE='1') + return subprocess.run([sys.executable, '-m', 'tuldok_project', *map(str, arguments)], cwd=REPOSITORY, + env=environment, input=stdin, capture_output=True, text=True, timeout=120) + + def test_build_runs_and_products(self): + refused = self.run_cli('build', self.folder, 'benchmarks/score', stdin='n\n') + self.assertEqual(refused.returncode, 1) + self.assertTrue(refused.stdout.endswith('Build this? [y/N] \nNothing was built.\n'), refused.stdout) + self.assertEqual(self.runs(), []) + + done = self.run_cli('build', self.folder, 'benchmarks/score', stdin='y\n') + self.assertEqual(done.returncode, 0, done.stderr) + lines = done.stdout.splitlines() + self.assertEqual(lines[0], '3 steps to build, 0 to set up, 0 blocked, 1 ready: benchmarks/score can be') + starts = [line.split() for line in lines if line.startswith('start')] + ends = [line.split() for line in lines if line.startswith('end')] + self.assertEqual([row[1:3] for row in starts], [['datasets/numbers', 'run'], ['recipes/fit-a', 'run'], + ['benchmarks/score', 'fit-a'], ['benchmarks/score', 'zero']]) + self.assertEqual([row[-3] for row in ends], ['succeeded'] * 4) + self.assertEqual(lines[-1], 'Done: 4 runs succeeded, 0 already built.') + + again = self.run_cli('build', self.folder, 'benchmarks/score') # nothing to do: no question asked + self.assertEqual(again.returncode, 0, again.stderr) + self.assertIn('0 steps to build, 0 to set up, 0 blocked, 1 ready, 3 built', again.stdout) + self.assertEqual(again.stdout.splitlines()[-1], 'Nothing was run: everything asked for is built.') + + runs = self.run_cli('runs', self.folder) + self.assertEqual(runs.returncode, 0, runs.stderr) + table = runs.stdout.splitlines() + self.assertEqual(table[0].split(), ['run', 'reference', 'subject', 'state', 'started', 'seconds']) + self.assertEqual(len(table), 5) + self.assertEqual(table[-1].split()[1:4], ['datasets/numbers', '-', 'succeeded']) + listed = json.loads(self.run_cli('runs', self.folder, 'recipes/fit-a', '--json').stdout) + self.assertEqual([(row['reference'], row['state']) for row in listed], [('recipes/fit-a', 'succeeded')]) + + products = self.run_cli('products', self.folder) + self.assertEqual(products.returncode, 0, products.stderr) + table = products.stdout.splitlines() + self.assertEqual(table[0].split(), ['reference', 'subject', 'run', 'size', 'scratch', 'directory']) + self.assertEqual([row.split()[:2] for row in table[1:]], [['benchmarks/score', 'fit-a'], + ['benchmarks/score', 'zero'], + ['datasets/numbers', '-'], ['recipes/fit-a', '-']]) + listed = json.loads(self.run_cli('products', self.folder, 'benchmarks/score', '--json').stdout) + self.assertEqual([row['subject'] for row in listed], ['fit-a', 'zero']) + self.assertFalse(any(row['scratch'] for row in listed)) + + def test_refusals_on_the_command_line(self): + self.write_code('train.py', (self.code / 'train.py').read_text() + '# not committed\n') + dirty = self.run_cli('build', self.folder, 'recipes/fit-a', '--yes') + self.assertEqual(dirty.returncode, 1) + self.assertIn('changes that are not committed', dirty.stderr) + self.assertIn('changed train.py', dirty.stderr) + scratch = self.run_cli('build', self.folder, 'recipes/fit-a', '--yes', '--scratch') + self.assertEqual(scratch.returncode, 0, scratch.stderr) + self.assertIn('scratch', self.run_cli('products', self.folder, 'recipes/fit-a').stdout.splitlines()[1]) + failed = self.run_cli('build', self.folder, 'benchmarks/score', '--yes', '--scratch', + '--env', 'BUILDABLE_FAIL=score') + self.assertEqual(failed.returncode, 1) + self.assertEqual(failed.stdout.splitlines()[-1], + 'Stopped: benchmarks/score did not succeed; later steps were not run.') + usage = self.run_cli('build', self.folder, 'recipes/fit-a', '--env', 'not a pair') + self.assertEqual(usage.returncode, 2) + none = self.run_cli('build', self.folder) + self.assertEqual(none.returncode, 2) + + +if __name__ == '__main__': + unittest.main() diff --git a/tests/test_tuldok_project_cli.py b/tests/test_tuldok_project_cli.py index d367d986..b09d134a 100644 --- a/tests/test_tuldok_project_cli.py +++ b/tests/test_tuldok_project_cli.py @@ -400,7 +400,7 @@ def test_json_charts_models_and_all(self): 'notes', 'steps'): self.assertIn(field, made) self.assertTrue(made['buildable']) - self.assertEqual(made['counts'], {'build': 5, 'set-up': 1, 'blocked': 0, 'ready': 0}) + self.assertEqual(made['counts'], {'build': 5, 'set-up': 1, 'blocked': 0, 'ready': 0, 'built': 0}) model = self.run_ok('plan', self.folder, 'models/stepper').splitlines() self.assertEqual(model[0], 'Nothing to build for models/stepper.') self.assertEqual(' '.join(model[1:3]), diff --git a/tests/test_tuldok_project_environments.py b/tests/test_tuldok_project_environments.py index 26b59736..5d3adc76 100644 --- a/tests/test_tuldok_project_environments.py +++ b/tests/test_tuldok_project_environments.py @@ -231,13 +231,13 @@ def test_a_ready_environment_is_not_something_to_set_up(self): made = plan.make_plan(self.documents, ['steps/solver'], local={'environments/lab-cpu': 'ready'}) self.assertEqual([(step['reference'], step['state'], step['action']) for step in made['steps']], [('environments/lab-cpu', 'ready', 'ready'), ('steps/solver', 'not-built', 'build')]) - self.assertEqual(made['counts'], {'build': 1, 'set-up': 0, 'blocked': 0, 'ready': 1}) + self.assertEqual(made['counts'], {'build': 1, 'set-up': 0, 'blocked': 0, 'ready': 1, 'built': 0}) def test_a_failing_environment_is_set_up(self): made = plan.make_plan(self.documents, ['steps/solver'], local={'environments/lab-cpu': 'failing'}) self.assertEqual(made['steps'][0]['action'], 'set-up') self.assertEqual(made['steps'][0]['state'], 'failing') - self.assertEqual(made['counts'], {'build': 1, 'set-up': 1, 'blocked': 0, 'ready': 0}) + self.assertEqual(made['counts'], {'build': 1, 'set-up': 1, 'blocked': 0, 'ready': 0, 'built': 0}) class Local(unittest.TestCase): diff --git a/tests/test_tuldok_project_plan.py b/tests/test_tuldok_project_plan.py index e3218d3a..911d1716 100644 --- a/tests/test_tuldok_project_plan.py +++ b/tests/test_tuldok_project_plan.py @@ -84,7 +84,7 @@ def test_nothing_is_followed_out_of_a_blocked_step(self): self.mark('datasets/waves', 'no', 'The scenes were made by hand.') made = self.make('recipes/stepper-k1') self.assertEqual(_references(made), ['recipes/stepper-k1']) # not its dataset, solver or environment - self.assertEqual(made['counts'], {'build': 0, 'set-up': 0, 'blocked': 1, 'ready': 0}) + self.assertEqual(made['counts'], {'build': 0, 'set-up': 0, 'blocked': 1, 'ready': 0, 'built': 0}) self.assertEqual(made['steps'][0]['blocked_by'], [{'reference': 'datasets/waves', 'rebuild': 'no', 'reason': 'The scenes were made by hand.'}]) # A cause is a step when it is a target itself. @@ -126,7 +126,7 @@ def test_a_model_is_not_built(self): self.assertEqual(made['targets'], ['models/stepper']) self.assertEqual(made['steps'], []) self.assertTrue(made['buildable']) - self.assertEqual(made['counts'], {'build': 0, 'set-up': 0, 'blocked': 0, 'ready': 0}) + self.assertEqual(made['counts'], {'build': 0, 'set-up': 0, 'blocked': 0, 'ready': 0, 'built': 0}) self.assertEqual(made['notes'], ['models/stepper is a model; a model is not built, ' 'only the recipes that train it.']) @@ -178,7 +178,7 @@ def test_every_action(self): 'recipes/early-fit': ('cannot-rebuild', 'blocked'), 'benchmarks/rollout': ('not-built', 'build'), }) - self.assertEqual(made['counts'], {'build': 4, 'set-up': 1, 'blocked': 2, 'ready': 0}) + self.assertEqual(made['counts'], {'build': 4, 'set-up': 1, 'blocked': 2, 'ready': 0, 'built': 0}) self.assertFalse(made['buildable']) self.assertEqual(made['blocked_targets'], ['recipes/stepper-k2', 'recipes/early-fit']) diff --git a/tuldok_project/__main__.py b/tuldok_project/__main__.py index 7384dffb..8610c47f 100644 --- a/tuldok_project/__main__.py +++ b/tuldok_project/__main__.py @@ -15,8 +15,10 @@ `environments`, `connect`, `check-environment`, `set-up` and `disconnect` work with the interpreters that fulfil environments on this machine (environments.py); an environment may be named bare too. Only -`check-environment`, `connect` and `set-up` run anything, and `set-up ---dry-run` runs nothing. +`check-environment`, `connect`, `set-up` and `build` run anything, and `set-up +--dry-run` runs nothing. `build` makes the plan, closes the project, asks +for confirmation and runs the plan with builds.execute, which opens the +project only between commands; `runs` and `products` list what was built. """ import argparse import dataclasses @@ -115,6 +117,18 @@ def add(name, parents, help_text): setting_up.add_argument('--replace', action='store_true', help='remove an existing target first') disconnecting = add('disconnect', [opening], "forget an environment's interpreter; an installed one is not deleted") disconnecting.add_argument('environment', help='for example lab-cpu or environments/lab-cpu') + building = add('build', [opening], 'print the plan for these definitions, ask, then build them') + building.add_argument('targets', nargs='*', metavar='TARGET', help='references, for example recipes/pilot-dense-k1') + building.add_argument('--all', action='store_true', help='build every dataset, recipe, step and benchmark') + building.add_argument('--scratch', action='store_true', + help='run from the code root as it is, uncommitted changes included; marks the products') + building.add_argument('--yes', action='store_true', help='do not ask for confirmation') + building.add_argument('--env', action='append', default=[], metavar='NAME=VALUE', + help="add a variable to every command's environment; may be repeated") + listing_runs = add('runs', [reading], 'list the runs, newest first') + listing_runs.add_argument('reference', nargs='?', help='only the runs of this definition') + listing_products = add('products', [reading], 'list the current products') + listing_products.add_argument('reference', nargs='?', help='only the products of this definition') add('forget', [database], "drop this project's copy from the database; the folder is not touched") return parser @@ -493,6 +507,11 @@ def _step_details(step): if skipped: shown = ', '.join(skipped[:3]) + (f' and {len(skipped) - 3} more' if len(skipped) > 3 else '') details.append(f'skips {len(skipped)} whose recipe is blocked: {shown}') + if step['action'] == 'built' and step.get('scratch'): + details.append('built by a scratch run') + if step['action'] == 'build' and step['state'] in ('out-of-date', 'failed', 'running'): + word = {'out-of-date': 'out of date', 'failed': 'failed', 'running': 'running'}[step['state']] + details += [f'{word}: {reason}' for reason in step.get('reasons', [])] or [word] if step['action'] == 'blocked': own = [cause for cause in step['blocked_by'] if cause['reference'] == step['reference']] others = [cause['reference'] for cause in step['blocked_by'] if cause['reference'] != step['reference']] @@ -529,7 +548,8 @@ def _opening(plan): if not plan['steps']: return f'Nothing to build for {targets[0] if len(targets) == 1 else _plural(len(targets), "target")}.' numbers = (f'{_plural(counts["build"], "step")} to build, {counts["set-up"]} to set up, ' - f'{counts["blocked"]} blocked' + (f', {counts["ready"]} ready' if counts['ready'] else '')) + f'{counts["blocked"]} blocked' + (f', {counts["ready"]} ready' if counts['ready'] else '') + + (f', {counts["built"]} built' if counts.get('built') else '')) every = ' (every dataset, recipe, step and benchmark)' if plan['every'] else '' blocked = len(plan['blocked_targets']) if len(targets) == 1 and not every: @@ -594,6 +614,119 @@ def _plan(project, arguments): return 0 +# ----------------------------------------------------------------- builds + +def _seconds(value): + return '-' if value is None else f'{value:.1f} s' + + +def _runs(project, arguments): + from . import builds + + rows = builds.runs(project, arguments.reference) + if arguments.json: + _json(rows) + return 0 + if not rows: + print('Nothing has been run' + (f' for {arguments.reference}.' if arguments.reference else '.')) + return 0 + _columns([('run', 'reference', 'subject', 'state', 'started', 'seconds'), + *((row['id'], row['reference'], row['subject'] or '-', row['state'], _when(row['started_at']), + _seconds(row['seconds'])) for row in rows)]) + return 0 + + +def _size(count): + for unit in ('B', 'KB', 'MB', 'GB'): + if count < 1000 or unit == 'GB': + return f'{count} {unit}' if unit == 'B' else f'{count:.3g} {unit}' + count /= 1000 + + +def _products(project, arguments): + from . import builds + + rows = builds.products(project, arguments.reference) + if arguments.json: + _json(rows) + return 0 + if not rows: + print('Nothing is built' + (f' for {arguments.reference}.' if arguments.reference else '.')) + return 0 + _columns([('reference', 'subject', 'run', 'size', 'scratch', 'directory'), + *((row['reference'], row['subject'] or '-', row['run_id'], _size(row['bytes']), + 'scratch' if row['scratch'] else '-', row['directory']) for row in rows)]) + return 0 + + +def _extra_env(pairs): + import re + + found = {} + for pair in pairs: + name, equals, value = pair.partition('=') + if not equals or not re.fullmatch(r'[A-Za-z_][A-Za-z0-9_]*', name): + raise UsageError(f'--env {pair!r} is not NAME=VALUE.') + found[name] = value + return found + + +def _ask(plan): + print() + sys.stdout.write('Build this? [y/N] ') + sys.stdout.flush() + answer = sys.stdin.readline().strip().lower() + if not sys.stdin.isatty(): + print() # the answer was not echoed: end the question's line + if answer not in ('y', 'yes'): + print('Nothing was built.') + return False + return True + + +def _build_event(kind, item): + subject = f' {item["subject"]}' if item['subject'] else '' + if kind == 'start': + print(f'start {item["reference"]}{subject} run {item["run_id"]}', flush=True) + return + print(f'end {item["reference"]}{subject} run {item["run_id"]} {item["state"]} {_seconds(item["seconds"])}', + flush=True) + if item['problem']: + for line in _wrapped(item['problem'], ' '): + print(line) + + +def _build(arguments, dsn): + from . import builds, plan, store + + if not arguments.targets and not arguments.all: + raise UsageError('Name at least one definition to build, or pass --all.') + extra_env = _extra_env(arguments.env) + project = store.open_project(arguments.folder, rebind=arguments.rebind, on_conflict=arguments.on_conflict, + dsn=dsn) + try: + made = plan.build_plan(project, arguments.targets, every=arguments.all) + finally: + project.close() + for line in _plan_lines(made): + print(line.rstrip()) + nothing = made['counts']['build'] == 0 + confirm = (lambda _plan: True) if arguments.yes or nothing else _ask + done = builds.execute(arguments.folder, made, confirm=confirm, extra_env=extra_env, scratch=arguments.scratch, + dsn=dsn, on_event=_build_event) + if not done['confirmed']: + return 1 + ran = len(done['steps']) + if done['ok'] and nothing: + print('Nothing was run: everything asked for is built.') + return 0 + if done['ok']: + print(f'Done: {_plural(ran, "run")} succeeded, {len(done["skipped"])} already built.') + return 0 + print(f'Stopped: {done["steps"][-1]["reference"]} did not succeed; later steps were not run.') + return 1 + + # ------------------------------------------------------------ environments def _when(value): @@ -744,7 +877,7 @@ def _disconnect(project, arguments): 'set': _set, 'remove': _remove, 'save': _save, 'results': _results, 'values': _values, 'import-values': _import_values, 'chart': _chart, 'report': _report, 'plan': _plan, 'environments': _environments, 'connect': _connect, 'check-environment': _check_environment, - 'set-up': _set_up, 'disconnect': _disconnect} + 'set-up': _set_up, 'disconnect': _disconnect, 'runs': _runs, 'products': _products} def _project_id(folder): @@ -848,6 +981,8 @@ def _database_command(arguments): try: if arguments.command == 'forget': return _forget(arguments, dsn) + if arguments.command == 'build': + return _build(arguments, dsn) return _run_store(arguments, dsn) except UsageError as exc: print(str(exc), file=sys.stderr) @@ -859,6 +994,8 @@ def _database_command(arguments): print(str(exc), file=sys.stderr) for problem in exc.problems: print(_problem_line(problem), file=sys.stderr) + for path in exc.files: + print(f'changed {path}', file=sys.stderr) return 1 except psycopg.Error as exc: print(f'The database failed: {str(exc).strip() or type(exc).__name__}', file=sys.stderr) diff --git a/tuldok_project/builds.py b/tuldok_project/builds.py new file mode 100644 index 00000000..2beca79d --- /dev/null +++ b/tuldok_project/builds.py @@ -0,0 +1,815 @@ +"""Building a plan: running each step from a snapshot of the code, and the runs, products and states that follow. + +Owns sections 4 to 6 of docs/plans/definition-first-projects/spec-m6.md. Three +tables of a project schema record what was built: plans (one row per build +that was confirmed), runs (one row per command started or refused, written +with state running before the command starts) and products (the output +directory of a succeeded run; at most one current per reference and subject). +status() derives from them, the definitions and the code root the states +built, out-of-date, running and failed, with the causes of each; store.py +reports them through graph.states(local=...) and plan.py turns them into +actions. execute() runs a plan: the project is opened to read what a step +needs and to write its run row, closed while the command runs under +launcher.run (so other commands can open it), and opened again to check the +outputs, import a benchmark's results and record the product. A run left +queued or running by a builder that is gone becomes unknown whenever builds +are looked at; nothing is ever restarted. Files are never deleted here. +""" +from contextlib import contextmanager +import fcntl +import json +import os +import shutil +import time +import uuid + +from psycopg import sql +from psycopg.types.json import Jsonb + +from . import documents, environments, graph, launcher, local, result_rows, snapshot, store + +BUILT_KINDS = ('dataset', 'recipe', 'step', 'benchmark') +ACTIVE = ('queued', 'running') +ENDED_BADLY = ('failed', 'timed-out', 'over-disk', 'unknown') +DEFAULT_WALL_HOURS = 24 +DEFAULT_DISK_GB = 50 +GB = 1000 ** 3 +RUNS = 'runs' +OUTPUT = 'output' +SETTINGS_FILE = 'settings.json' +GPU_LOCK = 'gpu.lock' +BOOT_ID = '/proc/sys/kernel/random/boot_id' +PASSED_VARIABLES = ('PATH', 'HOME', 'USER', 'LOGNAME', 'LANG', 'LC_ALL', 'TZ') +RECIPE_INPUT = '{recipe}' # the inputs key of a benchmark subject's recipe; never a valid input name +OPEN_WAIT_SECONDS = 60 # how long execute waits for a project another command has open +PROBLEMS_SHOWN = 5 + +TABLES = ( + '''CREATE TABLE IF NOT EXISTS {schema}.plans ( + id text PRIMARY KEY, created_at timestamptz NOT NULL, + targets jsonb NOT NULL, steps jsonb NOT NULL, scratch boolean NOT NULL)''', + '''CREATE TABLE IF NOT EXISTS {schema}.runs ( + id text PRIMARY KEY, + reference text NOT NULL, subject text NOT NULL DEFAULT '', + plan_id text NOT NULL, + state text NOT NULL, + scratch boolean NOT NULL, commit text NOT NULL, + definition text NOT NULL, settings text, + inputs jsonb NOT NULL, environment jsonb, + argv jsonb NOT NULL, env jsonb NOT NULL, + directory text NOT NULL, + owner_pid integer, owner_boot text, + queued_at timestamptz NOT NULL, started_at timestamptz, finished_at timestamptz, + exit_status integer, seconds double precision, bytes bigint, strays integer, + problem text)''', + 'CREATE INDEX IF NOT EXISTS runs_reference ON {schema}.runs (reference, subject, queued_at)', + '''CREATE TABLE IF NOT EXISTS {schema}.products ( + run_id text PRIMARY KEY, + reference text NOT NULL, subject text NOT NULL DEFAULT '', + directory text NOT NULL, outputs jsonb NOT NULL, + current boolean NOT NULL)''', + 'CREATE UNIQUE INDEX IF NOT EXISTS products_current ON {schema}.products (reference, subject) WHERE current', +) + +_RUN_COLUMNS = ('id', 'reference', 'subject', 'plan_id', 'state', 'scratch', 'commit', 'inputs', 'environment', + 'argv', 'directory', 'owner_pid', 'owner_boot', 'queued_at', 'started_at', 'finished_at', + 'exit_status', 'seconds', 'bytes', 'strays', 'problem') + + +def _q(schema, template): + return sql.SQL(template).format(schema=sql.Identifier(schema)) + + +def _kind(reference): + return documents.KINDS[documents.parse_reference(reference)[0]] + + +def _run_block(document): + run = document.get('run') if isinstance(document, dict) else None + return run if isinstance(run, dict) else {} + + +def _short(run_id): + return run_id[:12] + + +# ----------------------------------------------------------- the store's hooks + +def forget(connection, schema, reference): + """Drop the runs and products records of a definition that is gone; their files are left where they are.""" + connection.execute(_q(schema, 'DELETE FROM {schema}.products WHERE reference = %s'), (reference,)) + connection.execute(_q(schema, 'DELETE FROM {schema}.runs WHERE reference = %s'), (reference,)) + + +def boot_id(): + try: + with open(BOOT_ID, encoding='ascii') as handle: + return handle.read().strip() + except OSError: + return '' + + +def _alive(pid): + try: + os.kill(pid, 0) + except ProcessLookupError: + return False + except PermissionError: + return True + return True + + +def reap_orphans(connection, schema): + """Mark unknown every queued or running run whose builder process is gone (or ran before this boot).""" + rows = connection.execute(_q(schema, 'SELECT id, owner_pid, owner_boot FROM {schema}.runs ' + 'WHERE state = ANY(%s)'), (list(ACTIVE),)).fetchall() + if not rows: + return [] + boot = boot_id() + gone = [(run_id, pid) for run_id, pid, owner_boot in rows + if owner_boot != boot or pid is None or not _alive(pid)] + for run_id, pid in gone: + connection.execute(_q(schema, '''UPDATE {schema}.runs SET state = 'unknown', finished_at = now(), + problem = %s WHERE id = %s AND state = ANY(%s)'''), + (f'The build that ran it (process {pid}) is gone, so how it ended is not known; ' + f'it is never restarted. stop kills anything it left running.', run_id, list(ACTIVE))) + return [run_id for run_id, _ in gone] + + +# -------------------------------------------------------------------- states + +def _code_root(project): + state = project._state() + return os.path.realpath(os.path.join(state['folder'], state['code_root'])) + + +def settings_text(document, code_root): + """The settings text a run of this definition would see: inline settings as written, or the settings file's text. + + None when the run has neither, or when the settings file cannot be read. + """ + run = _run_block(document) + if 'settings' in run: + return json.dumps(run['settings'], indent=2, ensure_ascii=False) + '\n' + if isinstance(run.get('settings_file'), str): + try: + with open(os.path.join(code_root, run['settings_file']), encoding='utf-8') as handle: + return handle.read() + except (OSError, UnicodeDecodeError): + return None + return None + + +def _declared_inputs(document): + """{name: (reference, output or None)} of a definition's run.inputs.""" + found = {} + inputs = _run_block(document).get('inputs') + for name, value in (inputs.items() if isinstance(inputs, dict) else ()): + if isinstance(value, str): + found[name] = (value, None) + elif isinstance(value, dict): + found[name] = (value.get('from'), value.get('output')) + return found + + +def _subjects(document): + subjects = document.get('subjects') if isinstance(document, dict) else None + return [subject for subject in (subjects if isinstance(subjects, list) else ()) + if isinstance(subject, dict) and isinstance(subject.get('name'), str)] + + +def runnable_subjects(document, held_states): + """The subjects of a benchmark that would run: those whose recipe is not cannot-rebuild or needs-work.""" + return [subject for subject in _subjects(document) + if held_states.get(subject.get('recipe')) not in ('cannot-rebuild', 'needs-work')] + + +def _uses(document, subject=None): + """{inputs key: reference} a run of this definition (and subject) records: its inputs and the subject's recipe.""" + uses = {name: reference for name, (reference, _) in _declared_inputs(document).items()} + if subject is not None and isinstance(subject.get('recipe'), str): + uses[RECIPE_INPUT] = subject['recipe'] + return uses + + +def _input_words(key, reference): + return f'the recipe {reference} of its subject' if key == RECIPE_INPUT else f'its input {key} ({reference})' + + +_UNKNOWN_COMMIT = object() + + +def _changes(code_root, commits): + """{commit: set of changed paths, or _UNKNOWN_COMMIT}; empty when the code root is not in Git.""" + found = {} + for commit in sorted(commits): + try: + found[commit] = snapshot.changed_since(code_root, commit) + except snapshot.SnapshotError as exc: + if exc.code == 'not-in-git': + return {} + found[commit] = _UNKNOWN_COMMIT if exc.code in ('unknown-commit', 'invalid') else set() + return found + + +def _under(path, source): + source = source.rstrip('/') + return path == source or path.startswith(source + '/') + + +def _own_causes(document, text, product, current, changes, code_root): + """The out-of-date causes of one current product that do not depend on other definitions' states.""" + causes = [] + if product['definition'] != text: + causes.append(f'its definition changed since run {_short(product["run_id"])}') + settings_file = _run_block(document).get('settings_file') + if isinstance(settings_file, str) and settings_text(document, code_root) != product['settings']: + causes.append(f'its settings file {settings_file} changed since run {_short(product["run_id"])}') + recorded = product['inputs'] or {} + for key, reference in _uses(document, product.get('subject_document')).items(): + now = current.get((reference, '')) + if now is None: + causes.append(f'{_input_words(key, reference)} has no current product') + elif (recorded.get(key) or {}).get('run_id') != now['run_id']: + causes.append(f'{_input_words(key, reference)} was rebuilt since (now run {_short(now["run_id"])})') + if not product['scratch'] and product['commit']: + changed = changes.get(product['commit'], set()) + if changed is _UNKNOWN_COMMIT: + causes.append(f'its commit {product["commit"][:12]} is no longer in the repository, ' + 'so the code may have changed') + else: + sources = [source for source in _run_block(document).get('sources', []) if isinstance(source, str)] + hits = sorted(path for path in changed if any(_under(path, source) for source in sources)) + if hits: + shown = ', '.join(hits[:3]) + (f' and {len(hits) - 3} more' if len(hits) > 3 else '') + causes.append(f'its code changed since commit {product["commit"][:12]}: {shown}') + return causes + + +def status(project): + """{reference: {state, causes, scratch, subjects}} for every dataset, recipe, step and benchmark with runs or products. + + state is running, built, out-of-date or failed (section 5); a definition + absent from the result has none of them. causes are sentences saying why + it is out of date or failed. For a benchmark, subjects maps each subject + that would run to its own {state, causes, run_id}. + """ + connection, schema = project._connection, project.schema + if connection.execute(_q(schema, 'SELECT NOT EXISTS (SELECT 1 FROM {schema}.runs)')).fetchone()[0]: + return {} + reap_orphans(connection, schema) + rows = connection.execute(_q(schema, f'''SELECT {store._REFERENCE_SQL}, text, document FROM {{schema}}.definitions + WHERE NOT removed''')).fetchall() + texts = {reference: text for reference, text, _ in rows} + definitions = {reference: document for reference, _, document in rows} + current = {} + for (run_id, reference, subject, outputs, scratch, commit, definition, settings, inputs) in connection.execute(_q( + schema, '''SELECT p.run_id, p.reference, p.subject, p.outputs, r.scratch, r.commit, r.definition, + r.settings, r.inputs + FROM {schema}.products p JOIN {schema}.runs r ON r.id = p.run_id WHERE p.current''')): + current[reference, subject] = {'run_id': run_id, 'outputs': outputs, 'scratch': scratch, 'commit': commit, + 'definition': definition, 'settings': settings, 'inputs': inputs} + latest = {reference: (run_id, state, problem) for reference, run_id, state, problem in connection.execute(_q( + schema, '''SELECT DISTINCT ON (reference) reference, id, state, problem FROM {schema}.runs + ORDER BY reference, queued_at DESC, id''')).fetchall()} + active = {reference for (reference,) in connection.execute(_q( + schema, 'SELECT DISTINCT reference FROM {schema}.runs WHERE state = ANY(%s)'), (list(ACTIVE),))} + code_root = _code_root(project) if current else None + changes = _changes(code_root, {product['commit'] for product in current.values() + if not product['scratch'] and product['commit']}) if current else {} + held = graph.states(definitions) + + found = {} + out_of_date = set() + + def judge(reference, document, subject=None): + product = current.get((reference, subject['name'] if subject else '')) + if product is None: + return None + product = {**product, 'subject_document': subject} + causes = _own_causes(document, texts[reference], product, current, changes, code_root) + for key, used in _uses(document, subject).items(): + if used in out_of_date and not any(cause.startswith(_input_words(key, used)) for cause in causes): + causes.append(f'{_input_words(key, used)} is out of date') + return {'state': 'out-of-date' if causes else 'built', 'causes': causes, 'run_id': product['run_id'], + 'scratch': product['scratch']} + + for reference in graph.order(definitions): + if reference not in definitions or _kind(reference) not in BUILT_KINDS: + continue + document = definitions[reference] + if _kind(reference) == 'benchmark': + subjects = {subject['name']: judge(reference, document, subject) + for subject in runnable_subjects(document, held)} + judged = {name: item for name, item in subjects.items() if item is not None} + entry = {'subjects': {name: item or {'state': 'not-built', 'causes': [], 'run_id': None, 'scratch': False} + for name, item in subjects.items()}, + 'scratch': any(item['scratch'] for item in judged.values())} + if not subjects or not judged: + entry.update(state=None, causes=[]) + elif len(judged) == len(subjects) and all(item['state'] == 'built' for item in judged.values()): + entry.update(state='built', causes=[]) + else: + causes = [f'subject {name} is not built' if item is None else f'subject {name}: {cause}' + for name, item in subjects.items() if item is None or item['state'] != 'built' + for cause in ([None] if item is None else item['causes'])] + entry.update(state='out-of-date', causes=causes) + else: + judged = judge(reference, document) + entry = {'subjects': None, 'scratch': bool(judged and judged['scratch']), + 'state': judged and judged['state'], 'causes': judged['causes'] if judged else []} + if entry['state'] is None and reference in latest and latest[reference][1] in ENDED_BADLY: + run_id, state, problem = latest[reference] + entry.update(state='failed', causes=[f'its last run {_short(run_id)} ended {state}' + + (f': {problem}' if problem else '')]) + if reference in active: + entry['state'] = 'running' + entry['causes'] = ['it is being built now'] + if entry['state'] == 'out-of-date': + out_of_date.add(reference) + if entry['state'] is not None: + found[reference] = entry + return found + + +def local_states(project): + """{reference: state} of the build states, for graph.states(local=...).""" + return {reference: entry['state'] for reference, entry in status(project).items()} + + +# ------------------------------------------------------------------ listings + +def runs(project, reference=None): + """The runs, newest first, as dicts (after marking orphaned ones unknown).""" + reap_orphans(project._connection, project.schema) + query = 'SELECT ' + ', '.join(_RUN_COLUMNS) + ' FROM {schema}.runs' + parameters = () + if reference is not None: + query += ' WHERE reference = %s' + parameters = (reference,) + query += ' ORDER BY queued_at DESC, id' + return [dict(zip(_RUN_COLUMNS, row)) for row in project._execute(query, parameters).fetchall()] + + +def products(project, reference=None): + """The current products, by reference and subject: run, size of the declared outputs, directory, scratch.""" + reap_orphans(project._connection, project.schema) + query = '''SELECT p.reference, p.subject, p.run_id, p.directory, p.outputs, r.scratch, r.commit, r.finished_at + FROM {schema}.products p JOIN {schema}.runs r ON r.id = p.run_id WHERE p.current''' + parameters = () + if reference is not None: + query += ' AND p.reference = %s' + parameters = (reference,) + query += ' ORDER BY p.reference, p.subject' + found = [] + for reference_, subject, run_id, directory, outputs, scratch, commit, finished in project._execute( + query, parameters).fetchall(): + found.append({'reference': reference_, 'subject': subject, 'run_id': run_id, 'directory': directory, + 'outputs': outputs, 'bytes': sum(item.get('bytes') or 0 for item in outputs.values()), + 'scratch': scratch, 'commit': commit, 'finished_at': finished}) + return found + + +# --------------------------------------------------------------- placeholders + +class StepProblem(Exception): + """A step that cannot be started as its definition stands; it fails before anything runs.""" + + +def fill(text, values): + """text with every {name} replaced from values; '{{' and '}}' become literal braces. + + The text must follow documents.placeholders' rules (ValueError otherwise); + a name missing from values raises KeyError with that name. + """ + documents.placeholders(text) # the same rules as the checker; raises ValueError on a stray brace + out, index = [], 0 + while index < len(text): + char = text[index] + if char == '{': + if text.startswith('{{', index): + out.append('{') + index += 2 + continue + end = text.index('}', index + 1) + out.append(values[text[index + 1:end]]) + index = end + 1 + elif char == '}': + out.append('}') + index += 2 + else: + out.append(char) + index += 1 + return ''.join(out) + + +def _fill(text, values, missing, where): + try: + return fill(text, values) + except KeyError as exc: + name = exc.args[0] + reason = missing.get(name, f'{{{name}}} cannot be filled here') + raise StepProblem(f'{where} uses {{{name}}}, but {reason}.') from None + except ValueError as exc: + raise StepProblem(f'{where} {exc}.') from None + + +# -------------------------------------------------------------------- execute + +@contextmanager +def _opened(folder, dsn): + """Open the project for a moment, waiting while another command has it open.""" + deadline = time.monotonic() + OPEN_WAIT_SECONDS + while True: + try: + project = store.open_project(folder, dsn=dsn) + break + except store.ProjectError as exc: + if exc.code != 'busy' or time.monotonic() > deadline: + raise + time.sleep(0.2) + try: + yield project + finally: + project.close() + + +@contextmanager +def _gpu_lock(needed): + if not needed: + yield + return + home = local.projects_home() + os.makedirs(home, exist_ok=True) + descriptor = os.open(os.path.join(home, GPU_LOCK), os.O_RDWR | os.O_CREAT | os.O_CLOEXEC, 0o644) + try: + fcntl.flock(descriptor, fcntl.LOCK_EX) + yield + finally: + os.close(descriptor) + + +def _size(path): + if os.path.isfile(path) and not os.path.islink(path): + return os.lstat(path).st_size + total = 0 + for current, _directories, files in os.walk(path): + for name in files: + try: + total += os.lstat(os.path.join(current, name)).st_size + except OSError: + pass + return total + + +def _current_product(project, reference, subject=''): + row = project._execute('SELECT run_id, directory, outputs FROM {schema}.products ' + 'WHERE reference = %s AND subject = %s AND current', (reference, subject)).fetchone() + return None if row is None else {'run_id': row[0], 'directory': row[1], 'outputs': row[2]} + + +class _Build: + """One execute(): the snapshot, the environments checked so far, and what each step did.""" + + def __init__(self, folder, plan, *, extra_env, scratch, dsn, on_event): + self.folder = folder + self.plan = plan + self.extra_env = dict(extra_env or {}) + self.scratch = scratch + self.dsn = dsn + self.on_event = on_event or (lambda kind, item: None) + self.code = None + self.environments = {} # reference -> shown environment after a passing check in this build + self.plan_id = uuid.uuid4().hex + self.boot = boot_id() + self.done = [] + + # ------------------------------------------------------------ environment + + def environment(self, project, reference): + """The environment checked once in this build; StepProblem-free stop when it is not ready.""" + if reference in self.environments: + return self.environments[reference] + try: + shown = environments.check(project, reference) + except store.ProjectError as exc: + if exc.code != 'not-set-up': + raise + raise store.ProjectError(f'{reference} is not set up on this machine; set it up or connect an ' + 'interpreter, then build again.', 'not-ready', references=[reference]) from None + if not shown['ok']: + raise store.ProjectError(f'{reference} is not ready: its check found ' + + '; '.join(shown['problems']) + ' Set it up or connect an interpreter ' + 'that matches it, then build again.', 'not-ready', references=[reference]) + self.environments[reference] = shown + return shown + + # ---------------------------------------------------------------- prepare + + def _resolve(self, project, reference, subject): + """Everything a run needs, with the project open: (row values, argv, env, cwd, limits, gpu).""" + directory_name, name = documents.parse_reference(reference) + row = project._execute('SELECT text, document FROM {schema}.definitions ' + 'WHERE directory = %s AND name = %s AND NOT removed', (directory_name, name)).fetchone() + if row is None: + raise store.ProjectError(f'There is no definition {reference}.', 'not-found', references=[reference]) + text, document = row + run = _run_block(document) + run_id = uuid.uuid4().hex + run_directory = os.path.join(local.home(project.project_id), RUNS, run_id) + output = os.path.join(run_directory, OUTPUT) + values, missing, recorded = {'output': output}, {}, {} + + environment_record = None + if isinstance(run.get('environment'), str): + shown = self.environment(project, run['environment']) + environment_record = {'reference': run['environment'], 'interpreter': shown['interpreter'], + 'found': shown['found']} + + prepared = {'id': run_id, 'reference': reference, 'subject': subject['name'] if subject else '', + 'definition': text, 'settings': None, 'environment': environment_record, + 'directory': run_directory, 'argv': list(run.get('command') or []), 'env': {}, + 'problem': None} + try: + if not run.get('command'): + raise StepProblem(f'{reference} has no run.command, so it cannot be built.') + for input_name, (used, output_name) in _declared_inputs(document).items(): + product = _current_product(project, used) + if product is None: + missing[f'inputs.{input_name}'] = f'{used} has no current product' + raise StepProblem(f'Its input {input_name} ({used}) has no current product; build it first.') + path = product['directory'] + if output_name is not None: + declared = (product['outputs'] or {}).get(output_name) + if declared is None: + raise StepProblem(f'Its input {input_name} names the output {output_name} of {used}, ' + f'which run {_short(product["run_id"])} did not record.') + path = os.path.join(path, declared['path']) + values[f'inputs.{input_name}'] = path + recorded[input_name] = {'reference': used, 'run_id': product['run_id'], 'output': output_name} + if subject is not None: + values['subject.name'] = subject['name'] + argument = subject.get('argument') + recipe_values = {} + if isinstance(subject.get('recipe'), str): + product = _current_product(project, subject['recipe']) + if product is None: + raise StepProblem(f'The recipe {subject["recipe"]} of subject {subject["name"]} has no ' + 'current product; build it first.') + recipe_values['recipe'] = product['directory'] + recorded[RECIPE_INPUT] = {'reference': subject['recipe'], 'run_id': product['run_id'], + 'output': None} + values['subject'] = (_fill(argument, recipe_values, {}, f'The argument of subject {subject["name"]}') + if isinstance(argument, str) else subject['name']) + if 'settings' in run: + values['settings'] = os.path.join(run_directory, SETTINGS_FILE) + prepared['settings'] = settings_text(document, self.code.code_root) + elif isinstance(run.get('settings_file'), str): + values['settings'] = os.path.join(self.code.code_root, run['settings_file']) + prepared['settings'] = settings_text(document, self.code.code_root) + if prepared['settings'] is None: + raise StepProblem(f'Its settings file {run["settings_file"]} cannot be read in the code ' + f'at commit {self.code.commit[:12] or "(none)"}.') + argv = [_fill(part, values, missing, f'The command word {part!r}') for part in run['command']] + if run['command'][0] == 'python': + if environment_record is None: + raise StepProblem('The command starts with python but the run names no environment.') + argv[0] = environment_record['interpreter'] + elif '/' in argv[0]: + program = os.path.join(self.code.code_root, argv[0]) + if not (os.path.isfile(program) and os.access(program, os.X_OK)): + raise StepProblem(f'The program {argv[0]} is not an executable file in the code.') + argv[0] = program + else: + program = shutil.which(argv[0], path=os.environ.get('PATH', os.defpath)) + if program is None: + raise StepProblem(f'The program {argv[0]} was not found on PATH.') + argv[0] = program + prepared['argv'] = argv + resources = run.get('resources') if isinstance(run.get('resources'), dict) else {} + gpu = resources.get('gpu') is True + env = {key: os.environ[key] for key in PASSED_VARIABLES if key in os.environ} + env.update(PYTHONDONTWRITEBYTECODE='1', PYTHONUNBUFFERED='1') + if not gpu: + env['CUDA_VISIBLE_DEVICES'] = '' + elif 'CUDA_VISIBLE_DEVICES' in os.environ: + env['CUDA_VISIBLE_DEVICES'] = os.environ['CUDA_VISIBLE_DEVICES'] + for key, value in (run.get('env') or {}).items(): + env[key] = _fill(value, values, missing, f'The value of env {key}') + env.update(self.extra_env) + prepared['env'] = env + wall_hours = resources.get('wall_hours') or DEFAULT_WALL_HOURS + disk_gb = resources.get('disk_gb') or DEFAULT_DISK_GB + prepared['limits'] = {'wall_seconds': float(wall_hours) * 3600, 'disk_bytes': int(float(disk_gb) * GB)} + prepared['gpu'] = gpu + except StepProblem as exc: + prepared['problem'] = str(exc) + prepared['inputs'] = recorded + prepared['outputs'] = run.get('outputs') if isinstance(run.get('outputs'), dict) else {} + prepared['kind'] = _kind(reference) + prepared['inline_settings'] = 'settings' in run + return prepared + + def _insert(self, project, prepared, state): + project._execute('''INSERT INTO {schema}.runs (id, reference, subject, plan_id, state, scratch, commit, + definition, settings, inputs, environment, argv, env, directory, owner_pid, + owner_boot, queued_at, started_at, finished_at, problem) + VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, now(), + CASE WHEN %s = 'running' THEN now() END, + CASE WHEN %s = 'running' THEN NULL ELSE now() END, %s)''', + (prepared['id'], prepared['reference'], prepared['subject'], self.plan_id, state, + self.code.scratch, self.code.commit, prepared['definition'], prepared['settings'], + Jsonb(prepared['inputs']), Jsonb(prepared['environment']) if prepared['environment'] else None, + Jsonb(prepared['argv']), Jsonb(prepared['env']), prepared['directory'], os.getpid(), + self.boot, state, state, prepared['problem'])) + + # ------------------------------------------------------------------- run + + def run_one(self, reference, subject=None): + """Run one step (one subject of a benchmark); return the item reported for it.""" + with _opened(self.folder, self.dsn) as project: + prepared = self._resolve(project, reference, subject) + item = {'reference': reference, 'subject': prepared['subject'], 'run_id': prepared['id'], + 'directory': prepared['directory']} + if prepared['problem'] is not None: + self._insert(project, prepared, 'failed') + item.update(state='failed', problem=prepared['problem'], seconds=None) + return item + os.makedirs(os.path.join(prepared['directory'], OUTPUT)) + if prepared['inline_settings']: + with open(os.path.join(prepared['directory'], SETTINGS_FILE), 'w', encoding='utf-8') as handle: + handle.write(prepared['settings']) + self._insert(project, prepared, 'running') + self.on_event('start', item) + try: + with _gpu_lock(prepared['gpu']): + outcome = launcher.run(prepared['argv'], cwd=self.code.code_root, env=prepared['env'], + run_id=prepared['id'], directory=prepared['directory'], + limits=prepared['limits']) + except Exception as exc: # launcher.run raises only before the command has started + outcome = launcher.Outcome('failed', None, 0.0, 0, _size(prepared['directory'])) + started_problem = str(exc) or f'The command could not be started ({type(exc).__name__}).' + except BaseException: + with _opened(self.folder, self.dsn) as project: + project._execute("UPDATE {schema}.runs SET state = 'unknown', finished_at = now(), " + "problem = 'The build was interrupted while the command ran.' WHERE id = %s", + (prepared['id'],)) + raise + else: + started_problem = None + with _opened(self.folder, self.dsn) as project: + state, problem = self._finish(project, prepared, outcome, started_problem) + item.update(state=state, problem=problem, seconds=outcome.seconds) + return item + + def _finish(self, project, prepared, outcome, problem): + """Check the outputs, import results, record the run's end and its product; (state, problem).""" + state = outcome.state + output = os.path.join(prepared['directory'], OUTPUT) + outputs, results_text = {}, None + if problem is None: + own = _outcome_problem(outcome, prepared) + problem = ' '.join(part for part in (outcome.problem, own) if part) or None + if state == 'succeeded': + for name, declared in prepared['outputs'].items(): + path = os.path.join(output, declared['path']) + if not os.path.exists(path): + state, problem = 'failed', f'The declared output {name} ({declared["path"]}) was not written.' + break + outputs[name] = {'path': declared['path'], 'role': declared['role'], 'bytes': _size(path)} + if declared['role'] == 'results' and prepared['kind'] == 'benchmark': + with open(path, 'rb') as handle: + results_text = handle.read(result_rows.VALUES_LIMIT + 1) + if state == 'succeeded' and results_text is not None: + problem = _results_problem(project, results_text, prepared, outputs) + if problem is not None: + state = 'failed' + with project._connection.transaction(): + if state == 'succeeded': + if results_text is not None: + project.import_values(results_text, path=os.path.join(output, outputs_path(outputs))) + project._execute('UPDATE {schema}.products SET current = false ' + 'WHERE reference = %s AND subject = %s AND current', + (prepared['reference'], prepared['subject'])) + project._execute('INSERT INTO {schema}.products (run_id, reference, subject, directory, outputs, ' + 'current) VALUES (%s, %s, %s, %s, %s, true)', + (prepared['id'], prepared['reference'], prepared['subject'], output, Jsonb(outputs))) + project._execute('''UPDATE {schema}.runs SET state = %s, finished_at = now(), exit_status = %s, + seconds = %s, bytes = %s, strays = %s, problem = %s WHERE id = %s''', + (state, outcome.exit_status, outcome.seconds, outcome.bytes, outcome.strays, problem, + prepared['id'])) + return state, problem + + +def outputs_path(outputs): + return next((item['path'] for item in outputs.values() if item['role'] == 'results'), '') + + +def _results_problem(project, text, prepared, outputs): + """None when the results file is a values file for this benchmark and subject, else the first problems.""" + path = outputs_path(outputs) + found, problems = result_rows.check_values(text, project._benchmark_document, path=path) + messages = [f'{problem.pointer or "-"}: {problem.message}' for problem in problems] + if found is not None: + name = documents.parse_reference(prepared['reference'])[1] + if found.benchmark != name: + messages.append(f'/benchmark: the file is for benchmark {found.benchmark!r}, not {name!r}.') + if found.subject != prepared['subject']: + messages.append(f'/subject: the file is for subject {found.subject!r}, not {prepared["subject"]!r}.') + if not messages: + return None + shown = '; '.join(messages[:PROBLEMS_SHOWN]) + (f'; and {len(messages) - PROBLEMS_SHOWN} more' + if len(messages) > PROBLEMS_SHOWN else '') + return f'The results file {path} was refused: {shown}' + + +def _outcome_problem(outcome, prepared): + logs = os.path.join(prepared['directory'], 'stderr.log') + if outcome.state == 'succeeded': + return None + if outcome.state == 'failed': + return f'The command exited with status {outcome.exit_status}; see {logs}.' + if outcome.state == 'timed-out': + return f'It ran past its wall-time limit of {prepared["limits"]["wall_seconds"] / 3600:.3g} h and was stopped.' + if outcome.state == 'over-disk': + return f'Its run directory grew past its disk limit of {prepared["limits"]["disk_bytes"] / GB:.3g} GB.' + if outcome.state == 'cancelled': + return 'It was cancelled.' + return 'A process of the run could not be stopped, so how it ended is not known.' + + +def _snapshot_error(exc): + return store.ProjectError(str(exc), exc.code, files=exc.files) + + +def execute(project_folder, plan, *, confirm, extra_env=None, scratch=False, dsn=None, on_event=None): + """Run the build steps of plan (plan.build_plan's result) in order; return what was done. + + Refuses (ProjectError, before confirm is called) a plan with a blocked + target (code blocked), with a step another build is running (running), or + whose code cannot be prepared (the SnapshotError's code, with its files: + dirty, not-in-git, ...). confirm(plan) must return true to go on; + otherwise nothing is run or written and confirmed is false. The build + stops at the first step that does not succeed, and at an environment that + is not ready (ProjectError not-ready). on_event(kind, item) is called with + 'start' before each command and 'end' after each step. + + Returns {plan_id, confirmed, ok, steps: [{reference, subject, run_id, + state, problem, seconds}], skipped: [references already built]}. + """ + folder = os.fspath(project_folder) + if plan['blocked_targets']: + raise store.ProjectError('These targets cannot be built: ' + ', '.join(plan['blocked_targets']) + + '. See plan for why.', 'blocked', references=plan['blocked_targets']) + to_build = [step for step in plan['steps'] if step['action'] == 'build'] + running = [step['reference'] for step in to_build if step['state'] == 'running'] + if running: + raise store.ProjectError('Another build is running ' + ', '.join(running) + '; wait for it to end.', + 'running', references=running) + build = _Build(folder, plan, extra_env=extra_env, scratch=scratch, dsn=dsn, on_event=on_event) + if to_build: + with _opened(folder, dsn) as project: + state = project._state() + code_paths = (store._read_project_file(state['folder']) or {}).get('code_paths') + code_root = _code_root(project) + home = local.home(project.project_id, create=True) + try: + build.code = snapshot.prepare(code_root, code_paths, home=home, scratch=scratch) + except snapshot.SnapshotError as exc: + raise _snapshot_error(exc) from None + result = {'plan_id': build.plan_id, 'confirmed': False, 'ok': False, 'steps': build.done, 'skipped': []} + if not confirm(plan): + return result + result['confirmed'] = True + with _opened(folder, dsn) as project: + project._execute('INSERT INTO {schema}.plans (id, created_at, targets, steps, scratch) ' + 'VALUES (%s, now(), %s, %s, %s)', + (build.plan_id, Jsonb(plan['targets']), Jsonb(plan['steps']), scratch)) + needed_environments = {step['environment'] for step in to_build if step['environment']} + for step in plan['steps']: + reference = step['reference'] + if step['kind'] == 'environment': + if reference in needed_environments: + with _opened(folder, dsn) as project: + build.environment(project, reference) + continue + if step['action'] != 'build': + result['skipped'].append(reference) + continue + if step['kind'] == 'benchmark': + with _opened(folder, dsn) as project: + document = project.definition(reference)['document'] + entry = status(project).get(reference) or {} + built = {name for name, item in (entry.get('subjects') or {}).items() if item['state'] == 'built'} + subjects = [subject for subject in _subjects(document) + if subject['name'] in step['subjects']['run'] and subject['name'] not in built] + else: + subjects = [None] + for subject in subjects: + item = build.run_one(reference, subject) + build.done.append(item) + build.on_event('end', item) + if item['state'] != 'succeeded': + return result + result['ok'] = True + return result diff --git a/tuldok_project/graph.py b/tuldok_project/graph.py index 555b5010..fa3d0669 100644 --- a/tuldok_project/graph.py +++ b/tuldok_project/graph.py @@ -184,6 +184,9 @@ def users_of(definitions, reference): _OWN_STATE = {'needs-work': 1, 'no': 2} # earlier_work.rebuild -> index into _CARRIED _BASE_STATE = {'dataset': 'not-built', 'recipe': 'not-built', 'benchmark': 'not-built', 'step': 'not-built', 'environment': 'not-set-up', 'model': 'none', 'chart': 'none'} +_BUILT = ('dataset', 'recipe', 'step', 'benchmark') +_ENVIRONMENT_STATES = ('ready', 'failing', 'not-set-up') +_BUILD_STATES = ('running', 'built', 'out-of-date', 'failed') def _kind(reference, document): @@ -196,10 +199,14 @@ def _kind(reference, document): def states(definitions, local=None): """Return {reference: state} for every definition, by section 4.3 of the spec. - local, when given, maps environment references to the state this machine - records for them (ready, failing or not-set-up; spec-m5.md section 2) and - replaces the not-set-up computed for those environments. It applies to - environments only; no other definition's state depends on one. + local, when given, maps references to the state this machine records for + them, and is applied last. For an environment it is ready, failing or + not-set-up (spec-m5.md section 2) and replaces the computed state. For a + dataset, recipe, step or benchmark it is a build state (spec-m6.md + section 5): running, built or out-of-date replace whatever was computed; + failed replaces not-built only, since cannot-rebuild and needs-work take + precedence when there is no current product. A local state that is not a + state of that kind is ignored, and local states are never carried upward. cannot-rebuild and needs-work come from a definition's own earlier_work.rebuild or from anything it uses through input edges, directly @@ -228,6 +235,13 @@ def states(definitions, local=None): found = {reference: _CARRIED[severity[reference]] or _BASE_STATE.get(_kind(reference, document), 'none') for reference, document in definitions.items()} for reference, state in (local or {}).items(): - if reference in found and _kind(reference, definitions[reference]) == 'environment': + if reference not in found: + continue + kind = _kind(reference, definitions[reference]) + if kind == 'environment' and state in _ENVIRONMENT_STATES: + found[reference] = state + elif kind in _BUILT and state in _BUILD_STATES: + if state == 'failed' and found[reference] in _CARRIED[1:]: + continue found[reference] = state return found diff --git a/tuldok_project/plan.py b/tuldok_project/plan.py index 4ae9dfa6..6b7c0aa5 100644 --- a/tuldok_project/plan.py +++ b/tuldok_project/plan.py @@ -12,6 +12,11 @@ run.resources. build_plan reads the definitions from a Project's database copy and the recorded environment states and calls it. Making a plan runs nothing and opens no file: no command, no estimate command, nothing on disk; an estimate is always null here. +With what was built on this machine (spec-m6.md section 5), a step that is +built has the action built and is not work; one that is out-of-date or failed +is built again, and its reasons say why. build_plan reads those states from +builds.status, which looks at the code root's Git history only when some +product exists. """ from collections import deque import math @@ -20,7 +25,7 @@ from .store import ProjectError BUILT_KINDS = ('dataset', 'recipe', 'step', 'benchmark') -ACTIONS = ('build', 'set-up', 'blocked', 'ready') +ACTIONS = ('build', 'set-up', 'blocked', 'ready', 'built') RESOURCES = ('gpu', 'cpu_threads', 'memory_gb', 'wall_hours', 'disk_gb') CAUSE_LIMIT = 5 _CAUSE_LABELS = ('no', 'needs-work') @@ -141,8 +146,10 @@ def _subjects(document, states): def _action(kind, state): if kind == 'environment': return 'ready' if state == 'ready' else 'set-up' # not-set-up, or failing its last check - if state == 'not-built': - return 'build' + if state in ('not-built', 'out-of-date', 'failed', 'running'): + return 'build' # a running step is refused by builds.execute, never started twice + if state == 'built': + return 'built' if state in ('cannot-rebuild', 'needs-work'): return 'blocked' return None @@ -155,11 +162,14 @@ def _total(steps, field): return round(math.fsum(numbers), 6), len(declared) - len(numbers) -def make_plan(definitions, targets, *, every=False, local=None): +def make_plan(definitions, targets, *, every=False, local=None, built=None): """The plan for targets over {reference: document}, as section 3 and 4 of spec-m4.md describe it. - local is graph.states' mapping of environment references to the state - recorded on this machine; without it every environment is not-set-up. + local is graph.states' mapping of references to the state recorded on + this machine; without it every environment is not-set-up and nothing is + built. built is builds.status' mapping of reference to {causes, scratch}; + each step's reasons are its causes (why it is out of date, failed or + running) and scratch says whether its current product is a scratch one. every adds every dataset, recipe, step and benchmark to the targets. A chart target is replaced by its benchmark; a model target adds nothing @@ -200,7 +210,9 @@ def make_plan(definitions, targets, *, every=False, local=None): 'state': states[reference], 'action': action, 'command': run.get('command'), 'environment': run.get('environment'), 'inputs': _inputs(document), 'resources': _resources(document), 'estimate': None, - 'blocked_by': [], 'blocked_by_more': 0} + 'blocked_by': [], 'blocked_by_more': 0, + 'reasons': list((built or {}).get(reference, {}).get('causes', [])), + 'scratch': bool((built or {}).get(reference, {}).get('scratch', False))} if kind == 'benchmark': step['subjects'] = _subjects(document, states) if action == 'build' and not step['subjects']['run']: @@ -229,8 +241,10 @@ def build_plan(project, targets, *, every=False): """The plan for targets in an open Project, from its database copy alone. Raises ProjectError (code not-found) naming the first target that is not a - definition of the project. Holds no state; runs and opens nothing. + definition of the project. Holds no state; runs nothing and opens no file + unless something was built (then Git is asked what changed, section 5). """ + from . import builds, environments definitions = project._documents(removed=False) for reference in targets: if documents.parse_reference(reference) is None: @@ -238,4 +252,7 @@ def build_plan(project, targets, *, every=False): references=[reference]) if reference not in definitions: raise ProjectError(f'There is no definition {reference}.', 'not-found', references=[reference]) - return make_plan(definitions, targets, every=every, local=project._local_states()) + built = builds.status(project) + local = {**environments.recorded_states(project._connection, project.schema), + **{reference: entry['state'] for reference, entry in built.items()}} + return make_plan(definitions, targets, every=every, local=local, built=built) diff --git a/tuldok_project/store.py b/tuldok_project/store.py index bd4e347b..ef0b5f3c 100644 --- a/tuldok_project/store.py +++ b/tuldok_project/store.py @@ -18,6 +18,10 @@ in one more table owned by environments; the states reported here take the environments' stored check results, and an environment's record goes when its definition does. +What was built (spec-m6.md) lives in three more tables owned by builds: the +states reported here take the build states (built, out-of-date, running, +failed) from them, and a definition's runs and products records go when the +definition does (the files on disk are left). """ from dataclasses import dataclass import hashlib @@ -31,7 +35,7 @@ from metadata import connection_info -from . import check, documents, environments, folder as folder_reader, graph, result_rows, results +from . import builds, check, documents, environments, folder as folder_reader, graph, result_rows, results from .documents import Problem PROJECT_ID = re.compile(r'^[a-f0-9]{32}$') @@ -77,15 +81,18 @@ class ProjectError(Exception): lists why), conflict (files changed on disk where the database has unsaved edits), bound-elsewhere, busy, in-use, changed-on-disk, not-found; and for environments (environments.py): not-set-up (nothing is recorded for it), - no-install, no-installer, target-exists, install-failed. + no-install, no-installer, target-exists, install-failed; and for builds + (builds.py): blocked, running, not-ready, and a snapshot.SnapshotError's + code (dirty, not-in-git, ...), whose files names the changed files. references names the definitions concerned. """ - def __init__(self, message, code, *, problems=(), references=()): + def __init__(self, message, code, *, problems=(), references=(), files=()): super().__init__(message) self.code = code self.problems = list(problems) self.references = list(references) + self.files = list(files) # ------------------------------------------------------------ small helpers @@ -312,7 +319,7 @@ def _schema_exists(self): def _create_schema(self): self._connection.execute(sql.SQL('CREATE SCHEMA IF NOT EXISTS {}').format(sql.Identifier(self.schema))) - for statement in (*_TABLES, *environments.TABLES, *_MIGRATIONS): + for statement in (*_TABLES, *environments.TABLES, *builds.TABLES, *_MIGRATIONS): self._execute(statement) def _state(self): @@ -328,8 +335,12 @@ def _documents(self, *, removed=True): return dict(rows) def _local_states(self): - """{reference: state} of the environments recorded on this machine, for graph.states(local=...).""" - return environments.recorded_states(self._connection, self.schema) + """{reference: state} recorded on this machine, for graph.states(local=...). + + The environments' check results, and the build states of datasets, + recipes, steps and benchmarks (builds.local_states). + """ + return {**environments.recorded_states(self._connection, self.schema), **builds.local_states(self)} def _states(self, *, removed=True): return graph.states(self._documents(removed=removed), self._local_states()) @@ -443,6 +454,7 @@ def _import(self, root, rows, on_conflict, results_on_disk, recorded_results): self._write_edges(graph.edges({reference: d.document for reference, d in merged.items()})) for reference in delete: directory, name = documents.parse_reference(reference) + builds.forget(self._connection, self.schema, reference) if directory == 'benchmarks': result_rows.remove_benchmark(self._connection, self.schema, name) if directory == environments.DIRECTORY: @@ -624,7 +636,8 @@ def remove_definition(self, reference): """Mark a definition removed, to be deleted from disk by save(); refused while anything uses it. Removing an environment also drops its record on this machine (an - installed directory is left where it is). + installed directory is left where it is); removing anything drops its + runs and products records (their directories are left where they are). """ directory, name = _split(reference) with self._connection.transaction(): @@ -645,6 +658,7 @@ def remove_definition(self, reference): self._execute('UPDATE {schema}.definitions SET removed = true WHERE directory = %s AND name = %s', (directory, name)) self._write_edges([], [reference]) + builds.forget(self._connection, self.schema, reference) if directory == 'benchmarks': result_rows.remove_benchmark(self._connection, self.schema, name) if directory == environments.DIRECTORY: From 419d6ed2c8ed52c7b171d91b4a364a9181562509 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 12 Nov 2026 01:38:52 -0700 Subject: [PATCH 024/131] feat(project): look at, follow, cancel and stop runs, and measure estimates Adds run (one run's details), progress (the last progress line and the log tails, with --follow), cancel (asks a running run to stop), and stop (kills what a run left behind when its builder is gone). A run can be named by an unambiguous prefix of its id. estimate runs each step's estimate command from the commit's snapshot under the launcher and stores the figures; plan shows them beside the declared ones while the definition is unchanged. It is the only way an estimate command is ever run. The contract gains a Building section covering snapshots, runs, products, states, limits, the commands and estimates. Co-Authored-By: Claude Fable 5.2 --- docs/contracts/project-folder.md | 554 +++++++++++++++++- .../tuldok_project/buildable/code/estimate.py | 25 + .../buildable/project/recipes/fit-a.json | 3 +- tests/test_tuldok_project_builds_commands.py | 484 +++++++++++++++ tuldok_project/__main__.py | 263 ++++++++- tuldok_project/builds.py | 447 +++++++++++++- tuldok_project/plan.py | 27 +- 7 files changed, 1755 insertions(+), 48 deletions(-) create mode 100644 tests/fixtures/tuldok_project/buildable/code/estimate.py create mode 100644 tests/test_tuldok_project_builds_commands.py diff --git a/docs/contracts/project-folder.md b/docs/contracts/project-folder.md index 1909acaf..161a8521 100644 --- a/docs/contracts/project-folder.md +++ b/docs/contracts/project-folder.md @@ -3,7 +3,9 @@ Owner: the package `tuldok_project/` (`folder.py` reads the folder, `documents.py` and `schemas/*.json` check single files, `check.py` applies every rule, `results.py` owns summary files, `store.py` and `result_rows.py` the database -copy and its results, `charts.py` charts and the report page). The format names are `tuldok_project_v1` for +copy and its results, `charts.py` charts and the report page, `plan.py` +plans, `environments.py` environments, and `builds.py`, `launcher.py` and +`snapshot.py` building). The format names are `tuldok_project_v1` for the folder and `tuldok_definition_v1` for each definition. A project folder describes a piece of research as a set of small JSON files that @@ -585,6 +587,7 @@ A state is worked out from the definitions, never stored in a file: | `cannot-rebuild` | its `earlier_work.rebuild` is `no`, or something it uses through an input, directly or further up, is `cannot-rebuild` | | `needs-work` | not `cannot-rebuild`, and its `earlier_work.rebuild` is `needs-work` or something it uses through an input is `needs-work` | | `not-built` | any other dataset, recipe, benchmark or step | +| `running`, `built`, `out-of-date`, `failed` | a dataset, recipe, benchmark or step, by what was built on this machine (see [Build states](#build-states)) | | `not-set-up`, `ready`, `failing` | an environment, by what this machine records for it (see [Environments](#environments)) | | `none` | a model or a chart | @@ -593,7 +596,7 @@ Options: | Option | Commands | Meaning | | --- | --- | --- | | `--database-url URL` | all but `check` | The Postgres database. Without it, the `TULDOK_DATABASE_URL` environment variable is used; with neither, the command stops with exit status 2. | -| `--json` | `open`, `list`, `show`, `graph`, `status`, `save`, `results`, `values`, `import-values`, `chart`, `plan`, `environments`, `connect`, `check-environment`, `set-up` | Print one JSON document with the same content as the text. | +| `--json` | `open`, `list`, `show`, `graph`, `status`, `save`, `results`, `values`, `import-values`, `chart`, `plan`, `environments`, `connect`, `check-environment`, `set-up`, `runs`, `run`, `progress`, `cancel`, `stop`, `products`, `estimate` | Print one JSON document with the same content as the text. | | `--rebind` | all that open | The copy is bound to the folder it was first opened from. Opening the same project from another path is refused unless `--rebind` is given, which binds the copy to the new path. | | `--keep` | all that open | Where a file changed on disk and the same definition has unsaved edits, keep the edits; the changed file becomes the version that `save` replaces. | | `--discard` | all that open | Where a file changed on disk and the same definition has unsaved edits, drop the edits and take the file. | @@ -837,9 +840,11 @@ Wrote report.html (4 charts, 24626 bytes). A plan says what has to be built on this machine to have one or more definitions, in what order, and what stands in the way. Making a plan runs nothing. It reads the database copy only: it starts no command, including a -definition's `estimate` command, and opens no file of the folder or the code. -The figures in a plan are the ones each definition declares in -`run.resources`. +definition's `estimate` command, and opens no file of the folder; it asks Git +what changed in the code only when something was built (see +[Build states](#build-states)). The figures in a plan are the ones each +definition declares in `run.resources`, and beside them the ones its estimate +command printed when `estimate` last ran it (see [Estimates](#estimates)). | Command | Does | | --- | --- | @@ -881,7 +886,8 @@ reference), numbered from 1. Each step has one action: | --- | --- | | `set-up` | an environment in state `not-set-up`, or `failing` (the text says its last check failed) | | `ready` | an environment in state `ready`; it is not counted as something to set up | -| `build` | a dataset, recipe, step or benchmark in state `not-built` | +| `build` | a dataset, recipe, step or benchmark in state `not-built`, `out-of-date`, `failed` or `running` (the text says why under the step; `build` refuses a step that is running) | +| `built` | a dataset, recipe, step or benchmark in state `built`; it is not counted as work | | `blocked` | a definition in state `cannot-rebuild` or `needs-work`, and a benchmark with no subject to run | A blocked step is explained by its causes: the definitions whose own @@ -906,7 +912,10 @@ The totals count `build` steps only: - how many steps there are to build, and how many of them declare `gpu: true`; - the sum of the declared `disk_gb`, and how many build steps declare none; -- the sum of the declared `wall_hours`, and how many build steps declare none. +- the sum of the declared `wall_hours`, and how many build steps declare none; +- when any build step has an estimate, the sum of the estimated bytes and + seconds, and how many build steps each sum covers. Declared and estimated + figures are never added together. ### Text output @@ -968,10 +977,12 @@ With `--json`, `plan` prints one object: | `every` | true with `--all` | | `buildable` | true when no target is blocked | | `blocked_targets` | the targets that are blocked | -| `counts` | the number of steps of each action: `{"build", "set-up", "blocked", "ready"}` | +| `counts` | the number of steps of each action: `{"build", "set-up", "blocked", "ready", "built"}` | | `gpu_steps` | how many build steps declare `gpu: true` | | `disk_gb`, `disk_unknown` | the sum of the declared `disk_gb` over build steps, and how many build steps declare none | | `wall_hours`, `wall_unknown` | the same for `wall_hours` | +| `estimated_disk_gb`, `estimated_disk_steps` | the sum of the estimated `disk_bytes` over build steps, in units of 10^9 bytes, and how many build steps have one | +| `estimated_wall_hours`, `estimated_wall_steps` | the same for the estimated `wall_seconds`, in hours | | `notes` | sentences about targets that are not built themselves: a model, or a chart replaced by its benchmark | | `steps` | the steps in order | @@ -981,11 +992,13 @@ Each step: | --- | --- | | `number` | its place in the order, from 1 | | `reference`, `kind`, `title`, `state` | from the definition; the state as `list` shows it | -| `action` | `build`, `set-up`, `blocked` or `ready` | +| `action` | `build`, `set-up`, `blocked`, `ready` or `built` | | `command`, `environment` | from `run`, placeholders not filled in; null when absent | | `inputs` | each input name to `{"reference", "output"}`; `output` is null for a whole product | | `resources` | `gpu`, `cpu_threads`, `memory_gb`, `wall_hours`, `disk_gb` as declared; null when not declared (a null `gpu` means no GPU is needed) | -| `estimate` | always null: no estimate command is run | +| `estimate` | the stored estimate, `{"disk_bytes", "wall_seconds", "items", "measured_at"}` with null for a figure the command did not print, while the definition's text is the one it was measured for; otherwise null | +| `reasons` | why a `build` step is out of date, failed or running; empty otherwise | +| `scratch` | true when the step's current product was made by a scratch run | | `blocked_by` | for a blocked step, up to five causes, each `{"reference", "rebuild", "reason"}`; empty otherwise | | `blocked_by_more` | how many more causes there are | | `subjects` | benchmarks only: `run`, the subject names that would run, and `skipped`, each `{"name", "recipe", "reason"}` | @@ -1193,13 +1206,524 @@ With the environment ready, the same plan begins `1 step to build, 0 to set up, 0 blocked, 1 ready: steps/solver can be built.` and the environment's line has the action `ready`. +## Building + +`build` runs the commands of a plan on this machine and records what they +made. What a command writes is a **product**; it stays on this machine, in the +project's local home, and is never written to the folder. Each command that is +started is a **run**, recorded in the project's database schema with its +state, its command line, the code and inputs it used and how it ended. + +### What a build does + +1. It makes the plan for its targets, as `plan` does, and prints it. +2. It refuses the plan, before asking anything, when a target is blocked or + when another build is running one of its steps. +3. When something is to be built, it prepares the code the runs will see (see + below). A tree with uncommitted changes is refused here. +4. It asks `Build this? [y/N]`, unless `--yes` is given or nothing is to be + built. Any answer but `y` or `yes` builds nothing. +5. It records the plan, then takes the steps in order: + - an environment that a step to build runs in is checked again, once per + build; one that is not ready stops the build, with a message saying to + set it up or connect an interpreter; + - a step whose action is `built` is skipped; + - a step whose action is `build` is run, once for each subject of a + benchmark that would run and is not built already. +6. For each run, it fills the placeholders, records the run with state + `running`, and runs the command. The project is closed while the command + runs, so `list`, `plan`, `runs`, `run`, `progress` and the other commands + work during a build; `build` waits up to a minute when another command has + the project open. +7. When the command ends with exit status 0, every declared output must exist + under the output directory, and a benchmark's results are imported. Then + the output directory becomes the definition's current product (one per + subject for a benchmark). +8. A run that does not succeed stops the build. Later steps are not run. + +A step whose command cannot even be started (a program that is not found, an +input with no current product, a settings file that cannot be read) is +recorded as a `failed` run with the reason, and its run directory is not made. + +### The code a run sees + +The code root must be inside a Git work tree. A run uses the commit that +`HEAD` names, and the tree is **clean** when no tracked file under the code +paths (`code_paths` in `tuldok.json`, or the whole code root) differs from that +commit, staged or not. Untracked files do not count. A tree that is not clean +is refused, naming up to ten changed files. + +For a clean tree, the run sees a read-only copy of the commit, the +**snapshot**, made once with `git archive` and shared by every run at that +commit: + +| Code | Snapshot directory | +| --- | --- | +| the whole code root | `/code//` | +| `code_paths` | `/code/-/`, where the digest is the first 12 hexadecimal characters of the SHA-256 of the sorted paths, one per line | + +The snapshot keeps the repository's layout, so the command's working +directory is the code root's place inside it. A settings file named by +`settings_file` is read from the snapshot too. + +A **scratch** run, asked for with `--scratch`, uses the code root in place, +uncommitted changes included, and is allowed outside Git. It records the +commit when there is one. Its product is marked as a scratch product and never +becomes out of date because of the code. + +### The run directory + +Each run has its own directory, `/runs//`, where the run id +is 32 hexadecimal characters: + +| Entry | Content | +| --- | --- | +| `output/` | what `{output}` names, made empty before the command starts; a succeeded run's `output/` is its product | +| `settings.json` | the inline `settings` as the run saw them, when the definition has them | +| `stdout.log`, `stderr.log` | the command's standard output and error | +| `cancel` | present when cancellation was asked for | +| `outcome.json` | how the command ended, written when every process of the run is gone | + +A product stays where its run wrote it. A newer product of the same definition +(and subject) becomes the current one and the earlier one is kept, no longer +current. Tuldok deletes no run directory and no product. Removing a definition +drops its runs, products and estimate from the database and leaves the +directories on disk. + +### The command and its environment + +The command is `run.command` with its placeholders filled. When its first word +is `python`, it is the interpreter recorded for the run's environment. A first +word containing `/` is an executable file under the code root. Any other first +word is looked up on `PATH`. + +The command's environment holds exactly these variables, later ones replacing +earlier ones: + +1. `PATH`, `HOME`, `USER`, `LOGNAME`, `LANG`, `LC_ALL` and `TZ`, from `build`'s + own environment where they are set; +2. `PYTHONDONTWRITEBYTECODE=1` and `PYTHONUNBUFFERED=1`; +3. `CUDA_VISIBLE_DEVICES` set to the empty string, unless the step declares + `gpu: true`, in which case it is passed on as `build` has it (and left + unset when `build` has none); +4. the definition's `env`, with its placeholders filled; +5. every `--env NAME=VALUE` given to `build`; +6. `TULDOK_RUN_ID`, the run id. Every process the command starts inherits it, + which is how Tuldok finds anything a run left behind. + +The working directory is the code root in the snapshot (or the code root +itself for a scratch run). Standard input is `/dev/null`; standard output and +error are appended to the two logs. + +### Placeholders at run time + +| Placeholder | Filled with | +| --- | --- | +| `{output}` | `/output` | +| `{settings}` | `/settings.json` for inline `settings`; the settings file's path in the snapshot for `settings_file` | +| `{inputs.}` | the input's current product directory; for `{"from", "output"}`, the path of that output inside it | +| `{subject.name}` | the subject's name | +| `{subject}` | the subject's `argument`, with `{recipe}` replaced by the current product directory of the subject's recipe; the subject's name when it has no `argument` | + +An input or a subject's recipe with no current product fails the run before it +starts; the plan puts what it needs earlier, so this happens only when that +earlier step was not built. + +### Limits + +| Limit | From | Default | +| --- | --- | --- | +| wall time | `resources.wall_hours` | 24 hours | +| disk | `resources.disk_gb`, in units of 10^9 bytes, for the whole run directory | 50 GB | + +The wall time is looked at every half second and the size of the run +directory every five seconds, and once more when the command has ended. A +run past either limit, a run whose `cancel` file appears, and a run whose +`build` receives `SIGINT` (Ctrl-C) or `SIGTERM` is stopped: `SIGTERM` to every +process of the run, up to ten seconds of grace, then `SIGKILL`. After the +command has ended, however it ended, every process of this user that still +carries the run's `TULDOK_RUN_ID` is killed; such a process does not change a +zero exit status into a failure, but the count is recorded as the run's +strays. + +### The GPU lock + +A step that declares `gpu: true` holds an exclusive lock on +`$TULDOK_PROJECT_HOME/gpu.lock` while its command runs. The lock is shared by +every project on this machine, so two GPU steps never run at the same time; a +build that finds the lock taken waits for it. Steps without `gpu: true` take no +lock. + +### Results published by a benchmark + +A benchmark's output with role `results` must be a values file (see +[Values files](#values-files)) for that benchmark and the subject that was +run. After the command succeeds, the file is checked and imported, replacing +that subject's values and summary rows in the database. A file that fails the +check makes the run `failed`; its problem names the first five problems, and +nothing is imported. `save` writes the new summaries to `results/` like any +others. + +### Run states + +| State | Meaning | +| --- | --- | +| `queued` | recorded and not started yet | +| `running` | its command is running | +| `succeeded` | exit status 0, every declared output written, and a benchmark's results imported | +| `failed` | a non-zero exit status, a missing output, a refused results file, or a command that could not be started | +| `timed-out` | stopped at its wall-time limit | +| `over-disk` | stopped at, or ended over, its disk limit | +| `cancelled` | stopped because cancellation was asked for, with `cancel` or by a signal to `build` | +| `unknown` | how it ended is not known: its build is gone, or a process of the run could not be stopped | + +### Build states + +What was built gives datasets, recipes, steps and benchmarks four more states, +in the place of `not-built`: + +| State | When | +| --- | --- | +| `running` | it has a `queued` or `running` run | +| `built` | it has a current product and nothing makes it out of date | +| `out-of-date` | it has a current product, and one of the causes below holds | +| `failed` | it has no current product, and its latest run ended `failed`, `timed-out`, `over-disk` or `unknown` | + +A current product is **out of date** when: + +- the definition's text differs from the text its run used; +- its `settings_file` reads differently now from what the run used; +- an input, or a benchmark subject's recipe, has a different current product + than the one the run used, or none, or is itself out of date; +- the run was not a scratch run, and one of the definition's `sources` (or a + file under one) changed since the run's commit: in a later commit or as an + uncommitted change to a tracked file. When Git no longer has that commit, + the code is taken to have changed. + +A benchmark has a product per subject. It is `built` when every subject that +would run has a current product that is not out of date, and `out-of-date` +when one of them is out of date or only some have a product. When none has a +product it is `not-built`, or `failed` when its latest run ended badly. A product built by a scratch run is `built`, and +`plan` notes that it is a scratch product. A definition with a current product +is `built` or `out-of-date` even when its label would make it +`cannot-rebuild` or `needs-work`; those take precedence only when there is no +current product. A `cancelled` run never makes a definition `failed`, and a +definition with a current product keeps it. + +In a plan, `built` is the action `built` and is not counted as work; +`out-of-date`, `failed` and `running` are `build`, and the plan says why under +the step. A step another build is running is refused by `build`. + +### When a builder dies + +A run is watched by a small custodian process that `build` starts for each +command. When `build` dies, even by `SIGKILL`, the custodian notices, stops +the run and kills every process that carries its run id. Its row in the +database still says `running`. The next time builds are looked at (`list`, +`plan`, `runs`, `run` and the others), a `queued` or `running` run whose build +process is not running on this boot becomes `unknown`, with a problem saying +so. It is never restarted; build again to make the product. + +`stop` is for a run whose build is gone: it kills every process of this user +that carries the run's id, whatever is left after the custodian, and marks the +run `unknown` when it was still `queued` or `running`. It is refused while the +run's build is alive; use `cancel` for that. + +### Commands + +| Command | Does | +| --- | --- | +| `build TARGET... [--all] [--scratch] [--yes] [--env NAME=VALUE]...` | Prints the plan, asks to proceed unless `--yes`, and runs it. Prints a line when each run starts and ends, with the run id, and a closing line. | +| `runs [REFERENCE]` | The runs, newest first: run id, reference, subject, state, when it started and how long it took. | +| `run RUN` | One run: its row (state, plan, code, environment, command, directory, build process, times, exit status, seconds, size, strays), what it used, its product and outputs when it made one, its last progress event and its problem. | +| `progress RUN [--follow]` | The run's state, its last progress event and the last 8 KiB of each log. `--follow` looks again every two seconds and prints what is new, until the run is no longer `queued` or `running`. | +| `cancel RUN` | Asks a `queued` or `running` run to stop by creating its `cancel` file. The build running it stops it within a second or so and records it as `cancelled`; `cancel` does not wait. | +| `stop RUN` | For a run whose build is gone: kills the processes it left and marks it `unknown`. | +| `products [REFERENCE]` | The current products: reference, subject, run id, size of the declared outputs, whether a scratch run made it, and the directory. | +| `estimate TARGET... [--all] [--scratch] [--env NAME=VALUE]...` | Runs the estimate commands of the steps the plan would build and stores what they print (see [Estimates](#estimates)). | + +`RUN` is a run id or a prefix of at least six of its characters that no other +run's id starts with. A prefix that matches several runs is refused, and the +matching runs are listed. `run`, `progress`, `cancel` and `stop` open the +project only for a moment to find the run, waiting while a build has it open, +and read the logs with the project closed, so they work while another process +builds. `progress --follow` does not hold the project open between passes. + +Options: + +| Option | Commands | Meaning | +| --- | --- | --- | +| `--all` | `build`, `estimate` | every dataset, recipe, step and benchmark, together with any `TARGET` given | +| `--scratch` | `build`, `estimate` | run from the code root as it is, uncommitted changes included | +| `--yes` | `build` | do not ask for confirmation | +| `--env NAME=VALUE` | `build`, `estimate` | add a variable to every command's environment; may be repeated | +| `--follow` | `progress` | repeat until the run ends | +| `--json` | `runs`, `run`, `progress`, `cancel`, `stop`, `products`, `estimate` | print one JSON document; `progress --follow --json` prints one JSON object per line, one per pass | + +Exit statuses: + +| Command | 0 | 1 | +| --- | --- | --- | +| `build` | every step succeeded or was built already | refused (a blocked target, a step being built elsewhere, uncommitted changes, an environment that is not ready), not confirmed, or a run did not succeed | +| `run`, `progress`, `runs`, `products` | shown | no such run, or a prefix that matches several | +| `cancel` | the `cancel` file was made, or was there already | the run is not `queued` or `running`, or no such run | +| `stop` | nothing of the run is left running | its build is alive, a process could not be stopped, or no such run | +| `estimate` | every estimate that ran was measured | an estimate failed, or the code was refused | + +Every command exits with status 2 on a usage error, such as `build` or +`estimate` without a target or an `--env` that is not `NAME=VALUE`. + +In these examples `FOLDER` is a committed copy of Tuldok's test project +`tests/fixtures/tuldok_project/buildable`, whose environment is connected to +Tuldok's own `.venv/bin/python`. `LOCAL` is the project's local home and +`VENV` that `.venv`. + +``` +$ .venv/bin/python -m tuldok_project build FOLDER benchmarks/score --yes +3 steps to build, 0 to set up, 0 blocked, 1 ready: benchmarks/score can be +built. + +# action gpu disk time reference +1 ready - - - environments/test-python +2 build - 0.01 GB 0.05 h datasets/numbers + in environments/test-python +3 build - ? ? recipes/fit-a + data: datasets/numbers (data) + in environments/test-python +4 build - ? ? benchmarks/score + data: datasets/numbers (data) + in environments/test-python + runs 2 subjects + +To build: 3 steps, 0 on a GPU. +Disk: 0.01 GB declared; 2 of 3 declare none. +Time: 0.05 h declared; 2 of 3 declare none. +Figures are as the definitions declare them; no command was run. +start datasets/numbers run 8064e90ac31441bfb72ae1a892fde0b8 +end datasets/numbers run 8064e90ac31441bfb72ae1a892fde0b8 succeeded 0.0 s +start recipes/fit-a run a14415f556a645d8aa209af956504b82 +end recipes/fit-a run a14415f556a645d8aa209af956504b82 succeeded 0.0 s +start benchmarks/score fit-a run aeef824dfaad4c9eb0d95bc684738444 +end benchmarks/score fit-a run aeef824dfaad4c9eb0d95bc684738444 succeeded 0.0 s +start benchmarks/score zero run 9916ff56c61e471b840157155b4bdf83 +end benchmarks/score zero run 9916ff56c61e471b840157155b4bdf83 succeeded 0.0 s +Done: 4 runs succeeded, 0 already built. +$ .venv/bin/python -m tuldok_project runs FOLDER +run reference subject state started seconds +9916ff56c61e471b840157155b4bdf83 benchmarks/score zero succeeded 2026-11-12 01:26 0.0 s +aeef824dfaad4c9eb0d95bc684738444 benchmarks/score fit-a succeeded 2026-11-12 01:26 0.0 s +a14415f556a645d8aa209af956504b82 recipes/fit-a - succeeded 2026-11-12 01:26 0.0 s +8064e90ac31441bfb72ae1a892fde0b8 datasets/numbers - succeeded 2026-11-12 01:26 0.0 s +$ .venv/bin/python -m tuldok_project products FOLDER +reference subject run size scratch directory +benchmarks/score fit-a aeef824dfaad4c9eb0d95bc684738444 955 B - LOCAL/runs/aeef824dfaad4c9eb0d95bc684738444/output +benchmarks/score zero 9916ff56c61e471b840157155b4bdf83 910 B - LOCAL/runs/9916ff56c61e471b840157155b4bdf83/output +datasets/numbers - 8064e90ac31441bfb72ae1a892fde0b8 74 B - LOCAL/runs/8064e90ac31441bfb72ae1a892fde0b8/output +recipes/fit-a - a14415f556a645d8aa209af956504b82 66 B - LOCAL/runs/a14415f556a645d8aa209af956504b82/output +$ .venv/bin/python -m tuldok_project run FOLDER a14415 +run a14415f556a645d8aa209af956504b82 +reference recipes/fit-a +subject - +state succeeded +plan e7bf709a3f2f44b9a743401873dc34ae +code commit 51eb0263cdd0, from its snapshot +environment environments/test-python VENV/bin/python +command VENV/bin/python train.py --data LOCAL/runs/8064e90ac31441bfb72ae1a892fde0b8/output/numbers.json --settings LOCAL/code/51eb0263cdd0954fd47e700e718043887939d6c7/code/settings/fit-a.json --out LOCAL/runs/a14415f556a645d8aa209af956504b82/output +directory LOCAL/runs/a14415f556a645d8aa209af956504b82 +builder process 1362748 +queued 2026-11-12 01:26:54 +started 2026-11-12 01:26:54 +finished 2026-11-12 01:26:54 +exit status 0 +seconds 0.0 s +size 532 B +strays 0 +input data datasets/numbers (data), run 8064e90ac31441bfb72ae1a892fde0b8 +product LOCAL/runs/a14415f556a645d8aa209af956504b82/output +output weights weights.json weights 66 B +progress fit 4 of 4 (100%) guess=-0.1727 +$ .venv/bin/python -m tuldok_project progress FOLDER a14415 +run a14415f556a645d8aa209af956504b82 +reference recipes/fit-a +state succeeded +progress fit 4 of 4 (100%) guess=-0.1727 +stdout.log: 466 B: + {"format": "tuldok_progress_v1", "stage": "fit", "completed": 1, "total": 4, "metrics": {"guess": -0.09211366666666666}} + {"format": "tuldok_progress_v1", "stage": "fit", "completed": 2, "total": 4, "metrics": {"guess": -0.1381705}} + {"format": "tuldok_progress_v1", "stage": "fit", "completed": 3, "total": 4, "metrics": {"guess": -0.16119891666666666}} + {"format": "tuldok_progress_v1", "stage": "fit", "completed": 4, "total": 4, "metrics": {"guess": -0.172713125}} +stderr.log: empty +``` + +The command line in `run` is quoted so it can be pasted into a shell. The +progress event is the last complete line of standard output, within the last +8 KiB, that is exactly one JSON object of this form, at most 4,096 bytes: + +```json +{"format": "tuldok_progress_v1", "stage": "fit", "completed": 3, "total": 4, "metrics": {"guess": -0.16}} +``` + +`stage` and each metric name match `[A-Za-z0-9][A-Za-z0-9_.-]{0,63}`; +`completed` and `total` are whole numbers with `0 <= completed <= total <= +1000000`; `metrics` holds up to eight finite numbers. Any other line is just +output. Invalid bytes in a log are shown replaced, and control characters +other than tab and newline are left out. +`run --json` prints every column of the run's row, including the definition +text and the environment it ran with, plus `product`, `builder_alive` and +`event`. + +While a build runs in another terminal, `progress --follow` prints the run's +first line, then each new line of the logs as it is written (`out` for +standard output, `err` for standard error), a `progress` line when the event +changes, and a last line when the run ends: + +``` +$ .venv/bin/python -m tuldok_project progress FOLDER 3b4a4509 --follow +run 3b4a45097c0f44b3a651763d599289aa recipes/fit-a running +out {"format": "tuldok_progress_v1", "stage": "fit", "completed": 1, "total": 4, "metrics": {"guess": -0.09211366666666666}} +out {"format": "tuldok_progress_v1", "stage": "fit", "completed": 2, "total": 4, "metrics": {"guess": -0.1381705}} +out {"format": "tuldok_progress_v1", "stage": "fit", "completed": 3, "total": 4, "metrics": {"guess": -0.16119891666666666}} +out {"format": "tuldok_progress_v1", "stage": "fit", "completed": 4, "total": 4, "metrics": {"guess": -0.172713125}} +progress fit 4 of 4 (100%) guess=-0.1727 +Run 3b4a45097c0f44b3a651763d599289aa ended succeeded after 4.3 s. +$ .venv/bin/python -m tuldok_project stop FOLDER 3b4a4509 +Run 3b4a45097c0f44b3a651763d599289aa (recipes/fit-a) is still being run by its build (process 1365836); use cancel to stop it. +``` + +(`stop` above was run while the build was still going.) Cancelling a running +build, and what the build prints: + +``` +$ .venv/bin/python -m tuldok_project cancel FOLDER 4cc81737 +Asked run 4cc81737b8b04686942a24d60e39c9bc (recipes/fit-a) to stop: its build stops it within a second or so and records it as cancelled. +``` + +``` +start recipes/fit-a run 4cc81737b8b04686942a24d60e39c9bc +end recipes/fit-a run 4cc81737b8b04686942a24d60e39c9bc cancelled 1.1 s + It was cancelled. +Stopped: recipes/fit-a did not succeed; later steps were not run. +``` + +``` +$ .venv/bin/python -m tuldok_project cancel FOLDER 4cc81737 +Run 4cc81737b8b04686942a24d60e39c9bc (recipes/fit-a) is cancelled; only a queued or running run can be cancelled. +``` + +After the build running `48856079` was killed with `SIGKILL`: + +``` +$ .venv/bin/python -m tuldok_project stop FOLDER 48856079 +No process of the run was left running: run 48856079a1694a8391a8083fafe7fbb1 (recipes/fit-a). +It was running; it is now unknown, and is never restarted. +``` + +### Estimates + +A definition's `run.estimate.command` says how big and how long its build will +be without doing it. `estimate` runs it; `plan` and `build` never do, because +it is project code. For each step the plan would build: + +- a step without an estimate command is skipped; +- the estimate command runs from the same code as a build (a clean commit's + snapshot, or the code root with `--scratch`), with the child environment and + working directory a build step gets, in a throwaway directory + `/estimates//` that is removed afterwards; +- `{output}` names a path that does not exist, `{settings}` and + `{inputs.}` are filled as for a build, and `{subject}` and + `{subject.name}` cannot be used, since an estimate is made once per + definition; +- a step whose estimate command or `env` names an input with no current + product is skipped, with that reason; +- the command has five minutes and may write 100 MB (10^8 bytes) in its + directory; it takes no GPU lock. + +The command's standard output must be exactly one JSON object, at most 64 KiB, +with any of these fields; other fields are ignored: + +| Field | Meaning | +| --- | --- | +| `disk_bytes` | how many bytes the build will write | +| `wall_seconds` | how many seconds the build will take | +| `items` | how many items it will make or read, for example cases or examples | + +Each one present must be a number of at least 0, and at least one must be +present. A command that fails, runs out of time, prints anything else or a +value of the wrong kind is a failed estimate for that step, reported with the +reason; the other steps still run, and an earlier estimate of that step is +kept. A measured estimate replaces the step's earlier one. + +An estimate is stored in the database with the SHA-256 of the definition's +text it was measured for, and `plan` shows it only while the definition's text +is that one. In the text of a plan, the declared figure comes first and the +estimate follows it marked `~... est.`; the totals keep the declared sums and +add a line with the estimated sums, saying how many steps they cover. + +``` +$ .venv/bin/python -m tuldok_project estimate FOLDER recipes/fit-a +Ran from the code at commit 51eb0263cdd0. + +step estimate disk time items +datasets/numbers skipped - - - + It has no estimate command. +recipes/fit-a skipped - - - + It needs {inputs.data}, but its input data (datasets/numbers) has no current + product. + +0 measured, 2 skipped, 0 failed. plan shows each estimate while its definition is unchanged. +``` + +Once `datasets/numbers` is built and `recipes/fit-a` declares +`wall_hours: 0.1`: + +``` +$ .venv/bin/python -m tuldok_project estimate FOLDER recipes/fit-a +Ran from the code at commit 060271be67fe. + +step estimate disk time items +recipes/fit-a measured 4.8 KB 2 s 6 + +1 measured, 0 skipped, 0 failed. plan shows each estimate while its definition is unchanged. +$ .venv/bin/python -m tuldok_project plan FOLDER benchmarks/score +2 steps to build, 0 to set up, 0 blocked, 1 ready, 1 built: benchmarks/score +can be built. + +# action gpu disk time reference +1 ready - - - environments/test-python +2 built - 0.01 GB 0.05 h datasets/numbers + in environments/test-python +3 build - ? ~4.8 KB est. 0.1 h ~2 s est. recipes/fit-a + data: datasets/numbers (data) + in environments/test-python + out of date: its definition changed since run a14415f556a6 +4 build - ? ? benchmarks/score + data: datasets/numbers (data) + in environments/test-python + runs 2 subjects + out of date: subject fit-a: the recipe recipes/fit-a of its subject is out of date + +To build: 2 steps, 0 on a GPU. +Disk: no step declares it. +Time: 0.1 h declared; 1 of 2 declares none. +Estimated: disk ~4.8 KB (1 of 2 steps); time ~2 s (1 of 2 steps). +Declared figures are as the definitions declare them; figures marked est. are +what their estimate commands printed when estimate last ran them. No command +was run now. +``` + +A measured time reads in seconds below 100 s, in minutes below 100 minutes, +and in hours above that. With `--json`, `estimate` prints `{"targets", +"scratch", "commit", "steps"}`, each step `{"reference", "result"` +(`measured`, `skipped` or `failed`), `"reason", "values", "seconds"}`. + ## What the format does not do yet The folder is checked, can be opened, edited and saved through the database -copy, its results can be read and drawn, a build can be planned, and its -environments can be connected, checked and installed, nothing more. Tuldok -does not yet run any definition's command or `estimate` command, write -settings files or read the contents of notes. The `run`, `resources`, -`estimate` and `settings` fields record what a later Tuldok will use. +copy, its results can be read and drawn, its environments can be connected, +checked and installed, and its definitions can be planned, estimated and +built on this machine, one build at a time per step, from the command line. +Tuldok does not yet build from the Tuldok app or in the background, delete +old products or run directories, use `cpu_threads` or `memory_gb` (they are +shown, not enforced), or read the contents of notes. Background: [the design notes for this format](../plans/definition-first-projects/). diff --git a/tests/fixtures/tuldok_project/buildable/code/estimate.py b/tests/fixtures/tuldok_project/buildable/code/estimate.py new file mode 100644 index 00000000..7af7438f --- /dev/null +++ b/tests/fixtures/tuldok_project/buildable/code/estimate.py @@ -0,0 +1,25 @@ +"""Say how much "training" would write and how long it would take, without training: the stand-in estimate command. + +BUILDABLE_ESTIMATE=text makes it print a sentence instead of a JSON object. +""" +import argparse +import json +import os +import sys + +parser = argparse.ArgumentParser() +parser.add_argument('--data', required=True) +parser.add_argument('--settings', required=True) +parser.add_argument('--out', required=True) +arguments = parser.parse_args() +if os.path.exists(arguments.out): + print(f'{arguments.out} exists; an estimate is given a path that does not', file=sys.stderr) + sys.exit(4) +if os.environ.get('BUILDABLE_ESTIMATE') == 'text': + print('About four steps, a few kilobytes.') + sys.exit(0) +with open(arguments.data, encoding='utf-8') as handle: + count = len(json.load(handle)['numbers']) +with open(arguments.settings, encoding='utf-8') as handle: + steps = json.load(handle)['steps'] +print(json.dumps({'disk_bytes': 1200 * steps, 'wall_seconds': 0.5 * steps, 'items': count})) diff --git a/tests/fixtures/tuldok_project/buildable/project/recipes/fit-a.json b/tests/fixtures/tuldok_project/buildable/project/recipes/fit-a.json index a15c5669..f9fc60ba 100644 --- a/tests/fixtures/tuldok_project/buildable/project/recipes/fit-a.json +++ b/tests/fixtures/tuldok_project/buildable/project/recipes/fit-a.json @@ -8,6 +8,7 @@ "inputs": {"data": {"from": "datasets/numbers", "output": "data"}}, "settings_file": "settings/fit-a.json", "outputs": {"weights": {"path": "weights.json", "role": "weights"}}, - "sources": ["train.py", "common.py"] + "sources": ["train.py", "common.py"], + "estimate": {"command": ["python", "estimate.py", "--data", "{inputs.data}", "--settings", "{settings}", "--out", "{output}"]} } } diff --git a/tests/test_tuldok_project_builds_commands.py b/tests/test_tuldok_project_builds_commands.py new file mode 100644 index 00000000..47cf98de --- /dev/null +++ b/tests/test_tuldok_project_builds_commands.py @@ -0,0 +1,484 @@ +"""Looking at runs, cancelling and stopping them, and estimates (spec-m6.md, sections 3, 4, 7 and 8). + +Every test needs a database and runs only when TULDOK_DATABASE_URL names a +disposable cluster. Each one starts from the committed copy of +tests/fixtures/tuldok_project/buildable that test_tuldok_project_builds.BuildCase +makes, with TULDOK_PROJECT_HOME pointing at a temporary directory. A build +"in another process" is the command line started with BUILDABLE_HOLD, which +makes a stand-in script wait for a release file. Whatever a test starts is +stopped in its cleanup: the release file is written, a build still running is +killed, and every process that carries one of the project's run ids is killed, +so no process outlives a test even when it fails. +""" +import json +import os +from pathlib import Path +import signal +import subprocess +import sys +import time +import unittest +import uuid + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) +sys.path.insert(0, str(Path(__file__).resolve().parent)) + +from tuldok_project import builds, launcher, plan # noqa: E402 +from tuldok_project.store import ProjectError # noqa: E402 +import test_tuldok_project_builds as base # noqa: E402 + +REPOSITORY = base.REPOSITORY +WAIT = 30 + + +class CommandCase(base.BuildCase): + """BuildCase with the command line, builds in another process, and a cleanup that leaves no process behind.""" + + def setUp(self): + super().setUp() + self.hold = self.temporary / 'hold' + self.hold.mkdir() + self.children = [] + self.addCleanup(self.stop_everything) + + def stop_everything(self): + (self.hold / 'release').touch() + for child in self.children: + if child.poll() is None: + child.kill() + child.communicate(timeout=60) + try: + with builds.opened(self.folder) as project: + run_ids = [row[0] for row in project._execute('SELECT id FROM {schema}.runs').fetchall()] + except Exception: # the schema may be gone; the processes still carry the run ids found below + run_ids = [] + for run_id in run_ids: + launcher.stop_strays(run_id) + + def environment(self, extra=None): + return {**os.environ, 'PYTHONDONTWRITEBYTECODE': '1', **(extra or {})} + + def cli(self, *arguments, stdin=''): + return subprocess.run([sys.executable, '-m', 'tuldok_project', *map(str, arguments)], cwd=REPOSITORY, + env=self.environment(), input=stdin, capture_output=True, text=True, timeout=120) + + def start(self, *arguments): + child = subprocess.Popen([sys.executable, '-m', 'tuldok_project', *map(str, arguments)], cwd=REPOSITORY, + env=self.environment(), stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True) + self.children.append(child) + return child + + def start_held_build(self, target, script): + """A build in another process, waiting inside script until release; returns (process, run row).""" + child = self.start('build', self.folder, target, '--yes', '--env', f'BUILDABLE_HOLD={script}:{self.hold}') + deadline = time.monotonic() + WAIT + while not (self.hold / 'started').exists(): + if child.poll() is not None: + self.fail(f'The build ended before {script} started: {child.communicate()}') + self.assertLess(time.monotonic(), deadline, f'{script} did not start') + time.sleep(0.05) + with builds.opened(self.folder) as project: + running = [row for row in builds.runs(project) if row['state'] == 'running'] + self.assertEqual(len(running), 1) + return child, running[0] + + def run_of(self, reference): + return self.runs(reference)[0] + + +class Looking(CommandCase): + """run and progress, on a finished run and on one running in another process.""" + + def test_a_finished_run(self): + self.assertTrue(self.build('recipes/fit-a')['ok']) + fit = self.run_of('recipes/fit-a') + prefix = fit['id'][:8] + + shown = self.cli('run', self.folder, prefix) + self.assertEqual(shown.returncode, 0, shown.stderr) + rows = {line.split(' ')[0]: line.split(' ', 1)[1].strip() for line in shown.stdout.splitlines() if line} + self.assertEqual(rows['run'], fit['id']) + self.assertEqual(rows['state'], 'succeeded') + self.assertEqual(rows['exit status'], '0') + self.assertTrue(rows['code'].startswith(f'commit {fit["commit"][:12]}')) + self.assertTrue(rows['output weights'].startswith('weights.json weights ')) + self.assertEqual(rows['progress'].split(' ')[0], 'fit 4 of 4 (100%)') + self.assertEqual(rows['builder'], f'process {os.getpid()}') # this process built it; the run is over + listed = json.loads(self.cli('run', self.folder, prefix, '--json').stdout) + self.assertEqual((listed['id'], listed['state'], listed['event']['completed']), (fit['id'], 'succeeded', 4)) + self.assertEqual(listed['product']['outputs']['weights']['path'], 'weights.json') + self.assertTrue(listed['product']['current']) + self.assertFalse(listed['builder_alive']) + self.assertIn('"estimate"', listed['definition']) + + watched = self.cli('progress', self.folder, prefix) + self.assertEqual(watched.returncode, 0, watched.stderr) + lines = watched.stdout.splitlines() + self.assertEqual(lines[2].split(), ['state', 'succeeded']) + self.assertTrue(lines[4].startswith('stdout.log: ')) + self.assertEqual(sum('"tuldok_progress_v1"' in line for line in lines), 4) + self.assertEqual(lines[-1], 'stderr.log: empty') + found = json.loads(self.cli('progress', self.folder, prefix, '--json').stdout) + self.assertEqual((found['state'], found['event']['stage'], found['stderr_bytes']), ('succeeded', 'fit', 0)) + self.assertEqual(found['stdout_bytes'], len(found['stdout'].encode())) + + started = time.monotonic() + followed = self.cli('progress', self.folder, prefix, '--follow') + self.assertLess(time.monotonic() - started, 10) # an ended run is shown once + self.assertEqual(followed.returncode, 0, followed.stderr) + lines = followed.stdout.splitlines() + self.assertEqual(lines[0], f'run {fit["id"]} recipes/fit-a succeeded') + self.assertEqual(sum(line.startswith('out ') for line in lines), 4) + self.assertTrue(lines[-1].startswith(f'Run {fit["id"]} ended succeeded after ')) + passes = [json.loads(line) for line in self.cli('progress', self.folder, prefix, '--follow', + '--json').stdout.splitlines()] + self.assertEqual(len(passes), 1) + self.assertTrue(passes[0]['ended']) + + def test_a_run_in_another_process(self): + child, row = self.start_held_build('datasets/numbers', 'make_data') + prefix = row['id'][:6] + started = time.monotonic() + shown = self.cli('run', self.folder, prefix) + self.assertEqual(shown.returncode, 0, shown.stderr) + rows = {line.split(' ')[0]: line.split(' ', 1)[1].strip() for line in shown.stdout.splitlines() if line} + self.assertEqual((rows['builder'], rows['state'], rows['progress'], rows['finished']), + (f'process {child.pid} (running)', 'running', 'none yet', '-')) + found = json.loads(self.cli('progress', self.folder, prefix, '--json').stdout) + self.assertEqual((found['state'], found['event'], found['stdout']), ('running', None, '')) + self.assertLess(time.monotonic() - started, 20) + + follower = self.start('progress', self.folder, prefix, '--follow') + self.assertEqual(follower.stdout.readline(), f'run {row["id"]} datasets/numbers running\n') + (self.hold / 'release').touch() + rest, errors = follower.communicate(timeout=WAIT) + self.assertEqual(follower.returncode, 0, errors) + lines = rest.splitlines() + self.assertIn(f'out numbers in {row["directory"]}/output', lines) # printed after the release + self.assertEqual(lines.count(f'out numbers in {row["directory"]}/output'), 1) # once, never repeated + self.assertTrue(lines[-1].startswith(f'Run {row["id"]} ended succeeded'), lines) + child.communicate(timeout=WAIT) + self.assertEqual(child.returncode, 0) + + def test_follow_yields_only_what_is_new(self): + child, row = self.start_held_build('datasets/numbers', 'make_data') + passes = [] + for item in builds.follow(self.folder, row['id'], interval=0.2): + passes.append(item) + if len(passes) == 2: + (self.hold / 'release').touch() + self.assertLess(len(passes), 200) + self.assertTrue(passes[-1]['ended']) + self.assertEqual(passes[-1]['run']['state'], 'succeeded') + self.assertFalse(any(item['ended'] for item in passes[:-1])) + written = ''.join(item['stdout'] for item in passes) + self.assertEqual(written, f'numbers in {row["directory"]}/output\n') + child.communicate(timeout=WAIT) + + +class Prefixes(CommandCase): + + def insert(self, run_id, state='succeeded', pid=None, boot=None): + with builds.opened(self.folder) as project: + project._execute('''INSERT INTO {schema}.runs (id, reference, plan_id, state, scratch, commit, + definition, inputs, argv, env, directory, owner_pid, owner_boot, queued_at) + VALUES (%s, 'steps/gpu-one', 'p', %s, false, '', '{{}}', '{{}}', '[]', '{{}}', + %s, %s, %s, now())''', + (run_id, state, str(self.temporary / 'runs' / run_id), pid, boot)) + + def test_unique_ambiguous_and_too_short(self): + first, second = 'abcdef' + '0' * 25 + '1', 'abcdef' + '0' * 25 + '2' + self.insert(first) + self.insert(second) + with builds.opened(self.folder) as project: + self.assertEqual(builds.find_run(project, first), first) + self.assertEqual(builds.find_run(project, first[:-1] + '1'), first) + self.assertEqual(builds.find_run(project, 'abcdef' + '0' * 25 + '2'), second) + with self.assertRaises(ProjectError) as raised: + builds.find_run(project, 'abcdef0') + self.assertEqual((raised.exception.code, sorted(raised.exception.references)), ('ambiguous', [first, second])) + for text in ('abcde', 'ffffff', 'a b', ''): + with self.assertRaises(ProjectError) as raised: + builds.find_run(project, text) + self.assertEqual(raised.exception.code, 'not-found') + ambiguous = self.cli('run', self.folder, 'abcdef') + self.assertEqual(ambiguous.returncode, 1) + self.assertTrue(ambiguous.stderr.startswith('abcdef is the start of 2 runs; give more of the id:')) + self.assertIn(f' {first} steps/gpu-one - succeeded', ambiguous.stderr) + self.assertIn(f' {second} steps/gpu-one - succeeded', ambiguous.stderr) + short = self.cli('progress', self.folder, 'abcde') + self.assertEqual(short.returncode, 1) + self.assertIn('at least its first 6 characters', short.stderr) + exact = self.cli('run', self.folder, second, '--json') + self.assertEqual(json.loads(exact.stdout)['id'], second) + missing = self.cli('progress', self.folder, second) # a run whose directory was never made + self.assertEqual(missing.returncode, 0, missing.stderr) + self.assertIn('stdout.log: not written', missing.stdout) + + +class Cancelling(CommandCase): + + def test_cancel_stops_a_running_build(self): + child, row = self.start_held_build('benchmarks/score', 'train') + self.assertEqual(row['reference'], 'recipes/fit-a') + started = time.monotonic() + asked = self.cli('cancel', self.folder, row['id'][:10]) + self.assertEqual(asked.returncode, 0, asked.stderr) + self.assertEqual(asked.stdout, f'Asked run {row["id"]} (recipes/fit-a) to stop: its build stops it within ' + 'a second or so and records it as cancelled.\n') + self.assertTrue(os.path.exists(os.path.join(row['directory'], 'cancel'))) + output, errors = child.communicate(timeout=WAIT) + self.assertLess(time.monotonic() - started, 20) + self.assertEqual(child.returncode, 1, errors) + self.assertIn(f'end recipes/fit-a run {row["id"]} cancelled', output) + self.assertEqual(output.splitlines()[-1], 'Stopped: recipes/fit-a did not succeed; later steps were not run.') + fit = self.run_of('recipes/fit-a') + self.assertEqual((fit['state'], fit['problem']), ('cancelled', 'It was cancelled.')) + self.assertEqual(self.runs('benchmarks/score'), []) + self.assertEqual(launcher.strays(row['id']), []) + + finished = self.cli('cancel', self.folder, row['id'][:6]) + self.assertEqual(finished.returncode, 1) + self.assertEqual(finished.stderr, f'Run {row["id"]} (recipes/fit-a) is cancelled; only a queued or running ' + 'run can be cancelled.\n') + + def test_cancel_in_json(self): + child, row = self.start_held_build('datasets/numbers', 'make_data') + asked = json.loads(self.cli('cancel', self.folder, row['id'], '--json').stdout) + self.assertEqual(asked, {'id': row['id'], 'reference': 'datasets/numbers', 'subject': '', 'state': 'running', + 'cancel_file': os.path.join(row['directory'], 'cancel'), 'already_asked': False}) + child.communicate(timeout=WAIT) + self.assertEqual(child.returncode, 1) + self.assertEqual(self.run_of('datasets/numbers')['state'], 'cancelled') + self.assertEqual(self.states()['datasets/numbers'], 'not-built') + + def test_cancel_refuses_a_finished_run(self): + self.assertTrue(self.build('datasets/numbers')['ok']) + run = self.run_of('datasets/numbers') + refused = self.cli('cancel', self.folder, run['id']) + self.assertEqual(refused.returncode, 1) + self.assertIn('is succeeded; only a queued or running run can be cancelled.', refused.stderr) + self.assertFalse(os.path.exists(os.path.join(run['directory'], 'cancel'))) + + +class Stopping(CommandCase): + + def test_stop_is_refused_while_the_builder_lives(self): + child, row = self.start_held_build('datasets/numbers', 'make_data') + refused = self.cli('stop', self.folder, row['id'][:8]) + self.assertEqual(refused.returncode, 1) + self.assertEqual(refused.stderr, f'Run {row["id"]} (datasets/numbers) is still being run by its build ' + f'(process {child.pid}); use cancel to stop it.\n') + (self.hold / 'release').touch() + child.communicate(timeout=WAIT) + self.assertEqual(child.returncode, 0) + self.assertEqual(self.run_of('datasets/numbers')['state'], 'succeeded') + + def test_stop_after_the_builder_was_killed(self): + child, row = self.start_held_build('datasets/numbers', 'make_data') + child.send_signal(signal.SIGKILL) + child.communicate(timeout=WAIT) + # The custodian sees its caller die, stops the run and writes its outcome. + deadline = time.monotonic() + WAIT + while not os.path.exists(os.path.join(row['directory'], launcher.OUTCOME_FILE)): + self.assertLess(time.monotonic(), deadline, 'the custodian did not finish') + time.sleep(0.1) + self.assertEqual(launcher.strays(row['id']), []) + stopped = self.cli('stop', self.folder, row['id'][:8]) + self.assertEqual(stopped.returncode, 0, stopped.stderr) + self.assertEqual(stopped.stdout, f'No process of the run was left running: run {row["id"]} (datasets/numbers).\n' + 'It was running; it is now unknown, and is never restarted.\n') + run = self.run_of('datasets/numbers') + self.assertEqual(run['state'], 'unknown') + self.assertTrue(run['problem'].startswith(f'Stopped with stop: the build that ran it (process {child.pid}) ' + 'was gone; 0 stray processes killed.'), run['problem']) + self.assertEqual(self.states()['datasets/numbers'], 'failed') + + def orphan(self): + """A running row whose builder is gone, and a stray process carrying its run id (this test's child).""" + gone = subprocess.Popen([sys.executable, '-c', 'pass']) + gone.wait() + run_id = uuid.uuid4().hex + with builds.opened(self.folder) as project: + project._execute('''INSERT INTO {schema}.runs (id, reference, plan_id, state, scratch, commit, + definition, inputs, argv, env, directory, owner_pid, owner_boot, queued_at, + started_at) + VALUES (%s, 'steps/gpu-one', 'p', 'running', false, '', '{{}}', '{{}}', '[]', '{{}}', + %s, %s, %s, now(), now())''', + (run_id, str(self.temporary / 'runs' / run_id), gone.pid, builds.boot_id())) + stray = subprocess.Popen([sys.executable, '-c', 'import time; time.sleep(120)'], + env={**os.environ, launcher.RUN_ID_VARIABLE: run_id}) + + def end_stray(): + if stray.poll() is None: + stray.kill() + stray.wait(timeout=30) + self.addCleanup(end_stray) + deadline = time.monotonic() + WAIT + while launcher.strays(run_id) != [stray.pid]: # its environment is readable once it has started + self.assertLess(time.monotonic(), deadline) + time.sleep(0.02) + return run_id, gone.pid, stray + + def test_stop_kills_the_strays_of_an_orphaned_row(self): + run_id, gone, stray = self.orphan() + stopped = self.cli('stop', self.folder, run_id[:7]) + self.assertEqual(stopped.returncode, 0, stopped.stderr) + self.assertEqual(stopped.stdout, f'Killed 1 process of the run: run {run_id} (steps/gpu-one).\n' + 'It was running; it is now unknown, and is never restarted.\n') + self.assertEqual(stray.wait(timeout=WAIT), -signal.SIGKILL) + run = self.runs('steps/gpu-one')[0] + self.assertEqual((run['state'], run['strays']), ('unknown', 1)) + self.assertEqual(run['problem'], f'Stopped with stop: the build that ran it (process {gone}) was gone; ' + '1 stray process killed.') + again = json.loads(self.cli('stop', self.folder, run_id, '--json').stdout) + self.assertEqual({key: again[key] for key in ('was', 'state', 'killed', 'remaining', 'marked_unknown')}, + {'was': 'unknown', 'state': 'unknown', 'killed': 0, 'remaining': [], 'marked_unknown': False}) + + def test_stop_in_process_and_a_live_builder(self): + run_id, _gone, stray = self.orphan() + with builds.opened(self.folder) as project: + project._execute('UPDATE {schema}.runs SET owner_pid = %s WHERE id = %s', (os.getpid(), run_id)) + with self.assertRaises(ProjectError) as raised: + builds.stop(self.folder, run_id) + self.assertEqual(raised.exception.code, 'builder-alive') + self.assertIsNone(stray.poll()) + with builds.opened(self.folder) as project: + project._execute("UPDATE {schema}.runs SET owner_boot = 'another-boot' WHERE id = %s", (run_id,)) + done = builds.stop(self.folder, run_id) + self.assertEqual((done['was'], done['state'], done['killed'], done['marked_unknown']), + ('running', 'unknown', 1, True)) + self.assertEqual(stray.wait(timeout=WAIT), -signal.SIGKILL) + + +class Estimates(CommandCase): + + def step(self, made, reference): + return next(step for step in made['steps'] if step['reference'] == reference) + + def test_skipped_measured_shown_and_stale(self): + done = builds.estimate(self.folder, ['recipes/fit-a']) + self.assertEqual([(item['reference'], item['result']) for item in done['steps']], + [('datasets/numbers', 'skipped'), ('recipes/fit-a', 'skipped')]) + self.assertEqual(done['steps'][0]['reason'], 'It has no estimate command.') + self.assertIn('its input data (datasets/numbers) has no current product', done['steps'][1]['reason']) + self.assertIsNone(self.step(self.plan('recipes/fit-a'), 'recipes/fit-a')['estimate']) + + self.assertTrue(self.build('datasets/numbers')['ok']) + runs_before = len(self.runs()) + done = builds.estimate(self.folder, ['recipes/fit-a']) + self.assertEqual(len(done['steps']), 1) + item = done['steps'][0] + self.assertEqual((item['result'], item['values']), ('measured', {'disk_bytes': 4800, 'wall_seconds': 2.0, + 'items': 6})) + self.assertEqual(len(self.runs()), runs_before) # an estimate is not a run + self.assertEqual(os.listdir(self.home / self.project_id / builds.ESTIMATES), []) # thrown away + made = self.plan('recipes/fit-a') + shown = self.step(made, 'recipes/fit-a')['estimate'] + self.assertEqual({key: shown[key] for key in builds.ESTIMATE_FIELDS}, + {'disk_bytes': 4800, 'wall_seconds': 2.0, 'items': 6}) + self.assertEqual((made['estimated_disk_gb'], made['estimated_disk_steps']), (4.8e-06, 1)) + self.assertEqual((made['estimated_wall_hours'] * 3600, made['estimated_wall_steps']), (2.0, 1)) + self.assertEqual((made['disk_gb'], made['disk_unknown']), (0, 1)) # the declared sums are unchanged + + text = self.cli('plan', self.folder, 'benchmarks/score') + lines = text.stdout.splitlines() + self.assertIn('3 build - ? ~4.8 KB est. ? ~2 s est. recipes/fit-a', lines) + self.assertIn('4 build - ? ? benchmarks/score', lines) + self.assertIn('Disk: no step declares it.', lines) + self.assertIn('Estimated: disk ~4.8 KB (1 of 2 steps); time ~2 s (1 of 2 steps).', lines) + self.assertEqual(lines[-3], 'Declared figures are as the definitions declare them; figures marked est. are') + listed = json.loads(self.cli('plan', self.folder, 'recipes/fit-a', '--json').stdout) + self.assertEqual(self.step(listed, 'recipes/fit-a')['estimate']['items'], 6) + + self.edit('recipes/fit-a', lambda document: document.update(description='Described now.')) + made = self.plan('recipes/fit-a') + self.assertIsNone(self.step(made, 'recipes/fit-a')['estimate']) # measured for another text + self.assertEqual(made['estimated_disk_steps'], 0) + self.assertEqual(self.cli('plan', self.folder, 'recipes/fit-a').stdout.splitlines()[-1], + 'Figures are as the definitions declare them; no command was run.') + + def test_a_command_that_prints_no_json_object(self): + self.assertTrue(self.build('datasets/numbers')['ok']) + self.assertEqual(builds.estimate(self.folder, ['recipes/fit-a'])['steps'][0]['result'], 'measured') + refused = self.cli('estimate', self.folder, 'recipes/fit-a', '--env', 'BUILDABLE_ESTIMATE=text') + self.assertEqual(refused.returncode, 1, refused.stderr) + lines = refused.stdout.splitlines() + self.assertTrue(lines[0].startswith('Ran from the code at commit ')) + self.assertEqual(lines[2].split(), ['step', 'estimate', 'disk', 'time', 'items']) + self.assertEqual(lines[3].split(), ['recipes/fit-a', 'failed', '-', '-', '-']) + self.assertTrue(lines[4].startswith(' Its standard output is not one JSON object'), lines) + self.assertEqual(lines[-1], '0 measured, 0 skipped, 1 failed. plan shows each estimate while its ' + 'definition is unchanged.') + # The failed measurement left the earlier estimate in place. + self.assertEqual(self.step(self.plan('recipes/fit-a'), 'recipes/fit-a')['estimate']['items'], 6) + for document in ('[1, 2]', '{"disk_bytes": -1}', '{"items": "six"}', '{"other": 1}', '{"a": 1} {"b": 2}', + '{"items": NaN}'): + directory = self.temporary / 'printed' + directory.mkdir(exist_ok=True) + (directory / 'stdout.log').write_text(document + '\n') + values, reason = builds._estimate_values(launcher.Outcome('succeeded', 0, 0.1, 0, 0), directory) + self.assertIsNone(values, document) + self.assertTrue(reason, document) + + def test_the_commands_text_and_json(self): + listed = json.loads(self.cli('estimate', self.folder, 'recipes/fit-a', '--json').stdout) + self.assertEqual([(item['reference'], item['result']) for item in listed['steps']], + [('datasets/numbers', 'skipped'), ('recipes/fit-a', 'skipped')]) + self.assertTrue(self.build('datasets/numbers')['ok']) + measured = self.cli('estimate', self.folder, 'recipes/fit-a') + self.assertEqual(measured.returncode, 0, measured.stderr) + self.assertEqual(measured.stdout.splitlines()[2:], [ + 'step estimate disk time items', + 'recipes/fit-a measured 4.8 KB 2 s 6', + '', + '1 measured, 0 skipped, 0 failed. plan shows each estimate while its definition is unchanged.']) + nothing = self.cli('estimate', self.folder, 'datasets/numbers') + self.assertEqual((nothing.returncode, nothing.stdout), + (0, 'Nothing would be built, so there is nothing to estimate.\n')) + self.assertEqual(self.cli('estimate', self.folder).returncode, 2) + + def test_a_dirty_tree_needs_scratch(self): + self.assertTrue(self.build('datasets/numbers')['ok']) + self.write_code('estimate.py', (self.code / 'estimate.py').read_text() + '# not committed\n') + with self.assertRaises(ProjectError) as raised: + builds.estimate(self.folder, ['recipes/fit-a']) + self.assertEqual((raised.exception.code, raised.exception.files), ('dirty', ['estimate.py'])) + done = builds.estimate(self.folder, ['recipes/fit-a'], scratch=True) + self.assertEqual((done['scratch'], done['steps'][0]['result']), (True, 'measured')) + + def test_removing_the_definition_drops_its_estimate(self): + self.assertTrue(self.build('datasets/numbers')['ok']) + self.edit('recipes/fit-b', lambda document: document['run'].update( + estimate={'command': ['python', 'estimate.py', '--data', '{inputs.data}/numbers.json', + '--settings', '{settings}', '--out', '{output}']})) + self.commit('An estimate for fit-b.') + self.assertEqual(builds.estimate(self.folder, ['recipes/fit-b'])['steps'][0]['values']['wall_seconds'], 1.5) + with builds.opened(self.folder) as project: + self.assertIn('recipes/fit-b', builds.stored_estimates(project)) + project.remove_definition('recipes/fit-b') + count = project._execute('SELECT count(*) FROM {schema}.estimates').fetchone()[0] + self.assertEqual(count, 0) + + +class PlanFigures(unittest.TestCase): + """make_plan with estimates, without a database.""" + + def test_estimates_beside_declared_figures(self): + documents = base._documents() + local = {'environments/test-python': 'ready'} + estimates = {'recipes/fit-a': {'disk_bytes': 3e9, 'wall_seconds': 5400, 'items': 6, 'measured_at': 'x'}, + 'datasets/numbers': {'disk_bytes': None, 'wall_seconds': 60, 'items': None, 'measured_at': 'x'}} + made = plan.make_plan(documents, ['recipes/fit-a'], local=local, estimates=estimates) + self.assertEqual((made['estimated_disk_gb'], made['estimated_disk_steps']), (3.0, 1)) + self.assertEqual((made['estimated_wall_hours'], made['estimated_wall_steps']), (1.5 + 60 / 3600, 2)) + self.assertEqual((made['disk_gb'], made['wall_hours']), (0.01, 0.05)) + from tuldok_project import __main__ as cli + lines = cli._plan_lines(made) + self.assertIn('2 build - 0.01 GB 0.05 h ~60 s est. datasets/numbers', lines) + self.assertIn('3 build - ? ~3 GB est. ? ~90 min est. recipes/fit-a', lines) + self.assertIn('Estimated: disk ~3 GB (1 of 2 steps); time ~91 min (2 of 2 steps).', lines) + + +if __name__ == '__main__': + unittest.main() diff --git a/tuldok_project/__main__.py b/tuldok_project/__main__.py index 8610c47f..05d3afce 100644 --- a/tuldok_project/__main__.py +++ b/tuldok_project/__main__.py @@ -19,6 +19,11 @@ --dry-run` runs nothing. `build` makes the plan, closes the project, asks for confirmation and runs the plan with builds.execute, which opens the project only between commands; `runs` and `products` list what was built. +`run`, `progress`, `cancel` and `stop` work on one run, named by its id or a +prefix of it, while a build runs in another process: they open the project +only for a moment (waiting while a build has it open) and read the run's logs +with it closed. `estimate` runs the build steps' estimate commands, the one +command besides `build` that runs project code; `plan` shows what it stored. """ import argparse import dataclasses @@ -129,6 +134,23 @@ def add(name, parents, help_text): listing_runs.add_argument('reference', nargs='?', help='only the runs of this definition') listing_products = add('products', [reading], 'list the current products') listing_products.add_argument('reference', nargs='?', help='only the products of this definition') + showing_run = add('run', [reading], 'show one run: its row, its outputs and its last progress event') + showing_run.add_argument('run', help='a run id, or at least its first six characters') + watching = add('progress', [reading], "show a run's last progress event and the end of its logs") + watching.add_argument('run', help='a run id, or at least its first six characters') + watching.add_argument('--follow', action='store_true', + help='look again every two seconds, printing what is new, until the run ends') + cancelling = add('cancel', [reading], 'ask a queued or running run to stop; does not wait') + cancelling.add_argument('run', help='a run id, or at least its first six characters') + stopping = add('stop', [reading], 'for a run whose build is gone: kill what it left running and mark it unknown') + stopping.add_argument('run', help='a run id, or at least its first six characters') + estimating = add('estimate', [reading], "run the estimate commands of what would be built, and store what they print") + estimating.add_argument('targets', nargs='*', metavar='TARGET', help='references, for example recipes/pilot-dense-k1') + estimating.add_argument('--all', action='store_true', help='estimate every dataset, recipe, step and benchmark') + estimating.add_argument('--scratch', action='store_true', + help='run from the code root as it is, uncommitted changes included') + estimating.add_argument('--env', action='append', default=[], metavar='NAME=VALUE', + help="add a variable to every command's environment; may be repeated") add('forget', [database], "drop this project's copy from the database; the folder is not touched") return parser @@ -477,10 +499,26 @@ def _gpu(step): return 'yes' if step['resources']['gpu'] is True else '-' # an absent gpu means none is needed +def _duration(seconds): + """A measured time in the unit that reads best: seconds, minutes or hours.""" + if seconds < 100: + return f'{seconds:.3g} s' + if seconds < 6000: + return f'{seconds / 60:.3g} min' + return f'{seconds / 3600:.3g} h' + + def _step_figures(step): + """GPU, disk and time of a step: the declared figure, then any estimate marked '~... est.'.""" if step['action'] in ('set-up', 'ready'): return '-', '-', '-' - return _gpu(step), _figure(step['resources']['disk_gb'], ' GB'), _figure(step['resources']['wall_hours'], ' h') + disk, time_ = _figure(step['resources']['disk_gb'], ' GB'), _figure(step['resources']['wall_hours'], ' h') + measured = step.get('estimate') or {} + if measured.get('disk_bytes') is not None: + disk += f' ~{_size(round(measured["disk_bytes"]))} est.' + if measured.get('wall_seconds') is not None: + time_ += f' ~{_duration(measured["wall_seconds"])} est.' + return _gpu(step), disk, time_ def _wrapped(text, indent, width=78): @@ -571,10 +609,21 @@ def declared(total, unknown, unit): f'{unknown} of {build} declare' + ('s' if unknown == 1 else '') + ' none') return f'{total:.3g}{unit} declared; {none}.' - return [f'To build: {_plural(build, "step")}, {plan["gpu_steps"]} on a GPU.', - 'Disk: ' + declared(plan['disk_gb'], plan['disk_unknown'], ' GB'), - 'Time: ' + declared(plan['wall_hours'], plan['wall_unknown'], ' h'), - 'Figures are as the definitions declare them; no command was run.'] + lines = [f'To build: {_plural(build, "step")}, {plan["gpu_steps"]} on a GPU.', + 'Disk: ' + declared(plan['disk_gb'], plan['disk_unknown'], ' GB'), + 'Time: ' + declared(plan['wall_hours'], plan['wall_unknown'], ' h')] + disk_steps, wall_steps = plan.get('estimated_disk_steps', 0), plan.get('estimated_wall_steps', 0) + if not (disk_steps or wall_steps): + return lines + ['Figures are as the definitions declare them; no command was run.'] + parts = [] + if disk_steps: + parts.append(f'disk ~{_size(round(plan["estimated_disk_gb"] * 1000 ** 3))} ({disk_steps} of {build} steps)') + if wall_steps: + parts.append(f'time ~{_duration(plan["estimated_wall_hours"] * 3600)} ({wall_steps} of {build} steps)') + return lines + ['Estimated: ' + '; '.join(parts) + '.', + *_wrapped('Declared figures are as the definitions declare them; figures marked est. are what ' + 'their estimate commands printed when estimate last ran them. No command was run ' + 'now.', '')] def _plan_lines(plan): @@ -659,6 +708,204 @@ def _products(project, arguments): return 0 +def _moment(value): + return '-' if value is None else value.astimezone().strftime('%Y-%m-%d %H:%M:%S') + + +def _event_words(event): + """A progress event in a few words: stage, completed of total, and the metrics.""" + if event is None: + return 'none yet' + share = f' ({100 * event["completed"] / event["total"]:.0f}%)' if event['total'] else '' + metrics = ''.join(f' {name}={value:.4g}' for name, value in event['metrics'].items()) + return f'{event["stage"]} {event["completed"]} of {event["total"]}{share}{metrics}' + + +def _run_name(row): + return row['reference'] + (f' {row["subject"]}' if row['subject'] else '') + + +def _show_run(row, event): + import shlex + + code = ('scratch run, the code root as it was' + (f' at commit {row["commit"][:12]}' if row['commit'] else '') + if row['scratch'] else f'commit {row["commit"][:12]}, from its snapshot') + builder = '-' if row['owner_pid'] is None else ( + f'process {row["owner_pid"]}' + (' (running)' if row['builder_alive'] else '')) + environment = row['environment'] + rows = [('run', row['id']), ('reference', row['reference']), ('subject', row['subject'] or '-'), + ('state', row['state']), ('plan', row['plan_id']), ('code', code), + ('environment', f'{environment["reference"]} {environment["interpreter"]}' if environment else '-'), + ('command', shlex.join(row['argv'])), ('directory', row['directory']), ('builder', builder), + ('queued', _moment(row['queued_at'])), ('started', _moment(row['started_at'])), + ('finished', _moment(row['finished_at'])), + ('exit status', '-' if row['exit_status'] is None else row['exit_status']), + ('seconds', _seconds(row['seconds'])), ('size', '-' if row['bytes'] is None else _size(row['bytes'])), + ('strays', '-' if row['strays'] is None else row['strays'])] + for name, used in sorted((row['inputs'] or {}).items()): + label = 'subject recipe' if name == '{recipe}' else f'input {name}' + output = f' ({used["output"]})' if used.get('output') else '' + rows.append((label, f'{used["reference"]}{output}, run {used["run_id"]}')) + product = row['product'] + if product is not None: + rows.append(('product', product['directory'] + ('' if product['current'] else ' (no longer current)'))) + for name, output in sorted(product['outputs'].items()): + rows.append((f'output {name}', f'{output["path"]} {output["role"]} {_size(output["bytes"])}')) + rows.append(('progress', _event_words(event))) + _columns(rows) + if row['problem']: + print() + for line in _wrapped(row['problem'], ''): + print(line) + + +def _log_section(name, text, size): + if size is None: + print(f'{name}.log: not written') + return + if not size: + print(f'{name}.log: empty') + return + shown = len(text.encode('utf-8')) + print(f'{name}.log: {_size(size)}' + (', the last part:' if size > shown else ':')) + for line in text.rstrip('\n').split('\n'): + print(' ' + line) + + +def _show_progress(found): + _columns([('run', found['id']), ('reference', _run_name(found)), ('state', found['state']), + ('progress', _event_words(found['event']))]) + for name in ('stdout', 'stderr'): + _log_section(name, found[name], found[f'{name}_bytes']) + + +def _follow_pass(item, first): + run = item['run'] + if first: + print(f'run {run["id"]} {_run_name(run)} {run["state"]}', flush=True) + for name, mark in (('stdout', 'out'), ('stderr', 'err')): + if item[f'skipped_{name}'] and not first: + print(f'{mark} ... {_size(item[f"skipped_{name}"])} not shown') + for line in item[name].rstrip('\n').split('\n') if item[name] else (): + print(f'{mark} {line}') + if item['new_event'] and item['event'] is not None: + print(f'progress {_event_words(item["event"])}') + if item['ended']: + print(f'Run {run["id"]} ended {run["state"]}' + (f' after {_seconds(run["seconds"])}.' + if run['seconds'] is not None else '.')) + if run['problem']: + for line in _wrapped(run['problem'], ''): + print(line) + sys.stdout.flush() + + +def _single_run(arguments, dsn): + """run, progress and cancel: open the project for a moment, close it, then read the run's files.""" + from . import builds, launcher + + options = {'rebind': arguments.rebind, 'on_conflict': arguments.on_conflict} + if arguments.command == 'progress' and arguments.follow: + first = True + for item in builds.follow(arguments.folder, arguments.run, dsn=dsn, **options): + if arguments.json: + print(json.dumps(item, ensure_ascii=False, default=str), flush=True) + else: + _follow_pass(item, first) + first = False + return 0 + with builds.opened(arguments.folder, dsn, **options) as project: + if arguments.command == 'cancel': + done = builds.cancel(project, arguments.run) + else: + row = builds.run_details(project, arguments.run) + if arguments.command == 'cancel': + if arguments.json: + _json(done) + elif done['already_asked']: + print(f'Run {done["id"]} ({_run_name(done)}) was already asked to stop; its cancel file is there.') + else: + print(f'Asked run {done["id"]} ({_run_name(done)}) to stop: its build stops it within a second or so ' + 'and records it as cancelled.') + return 0 + found = launcher.progress(row['directory']) + if arguments.command == 'run': + if arguments.json: + _json({**row, 'event': found['event']}) + else: + _show_run(row, found['event']) + return 0 + shown = {**builds.run_summary(row), **found} + if arguments.json: + _json(shown) + else: + _show_progress(shown) + return 0 + + +def _stop(arguments, dsn): + from . import builds + + done = builds.stop(arguments.folder, arguments.run, dsn=dsn, rebind=arguments.rebind, + on_conflict=arguments.on_conflict) + if arguments.json: + _json(done) + return 1 if done['remaining'] else 0 + def processes(count): + return f'{count} process' + ('' if count == 1 else 'es') + + killed = ('No process of the run was left running' if not done['killed'] else + f'Killed {processes(done["killed"])} of the run') + print(f'{killed}: run {done["id"]} ({_run_name(done)}).') + if done['remaining']: + print(f'{processes(len(done["remaining"]))} could not be stopped: ' + + ', '.join(map(str, done['remaining'])) + '.') + if done['marked_unknown']: + print(f'It was {done["was"]}; it is now unknown, and is never restarted.') + else: + print(f'Its state, {done["state"]}, is unchanged.') + return 1 if done['remaining'] else 0 + + +def _estimate(arguments, dsn): + from . import builds + + if not arguments.targets and not arguments.all: + raise UsageError('Name at least one definition to estimate, or pass --all.') + extra_env = _extra_env(arguments.env) + done = builds.estimate(arguments.folder, arguments.targets, every=arguments.all, scratch=arguments.scratch, + extra_env=extra_env, dsn=dsn) + failed = sum(item['result'] == 'failed' for item in done['steps']) + if arguments.json: + _json(done) + return 1 if failed else 0 + if not done['steps']: + print('Nothing would be built, so there is nothing to estimate.') + return 0 + if done['commit'] is not None: + print(('Ran from the code root as it is (scratch)' if done['scratch'] else + f'Ran from the code at commit {done["commit"][:12]}') + '.') + print() + rows = [('step', 'estimate', 'disk', 'time', 'items')] + for item in done['steps']: + values = item['values'] or {} + rows.append((item['reference'], item['result'], + '-' if values.get('disk_bytes') is None else _size(round(values['disk_bytes'])), + '-' if values.get('wall_seconds') is None else _duration(values['wall_seconds']), + '-' if values.get('items') is None else f'{values["items"]:g}')) + widths = [max(len(row[index]) for row in rows) for index in range(4)] + for row, item in zip(rows, [None, *done['steps']]): + print((' '.join(cell.ljust(widths[index]) for index, cell in enumerate(row[:4])) + ' ' + row[4]).rstrip()) + if item is not None and item['reason']: + for line in _wrapped(item['reason'], ' '): + print(line) + counts = {result: sum(item['result'] == result for item in done['steps']) + for result in ('measured', 'skipped', 'failed')} + print() + print(f'{counts["measured"]} measured, {counts["skipped"]} skipped, {counts["failed"]} failed. ' + 'plan shows each estimate while its definition is unchanged.') + return 1 if failed else 0 + + def _extra_env(pairs): import re @@ -983,6 +1230,12 @@ def _database_command(arguments): return _forget(arguments, dsn) if arguments.command == 'build': return _build(arguments, dsn) + if arguments.command in ('run', 'progress', 'cancel'): + return _single_run(arguments, dsn) + if arguments.command == 'stop': + return _stop(arguments, dsn) + if arguments.command == 'estimate': + return _estimate(arguments, dsn) return _run_store(arguments, dsn) except UsageError as exc: print(str(exc), file=sys.stderr) diff --git a/tuldok_project/builds.py b/tuldok_project/builds.py index 2beca79d..4cc4dbee 100644 --- a/tuldok_project/builds.py +++ b/tuldok_project/builds.py @@ -13,13 +13,31 @@ launcher.run (so other commands can open it), and opened again to check the outputs, import a benchmark's results and record the product. A run left queued or running by a builder that is gone becomes unknown whenever builds -are looked at; nothing is ever restarted. Files are never deleted here. +are looked at; nothing is ever restarted. Files are never deleted here, +except an estimate's throwaway directory. + +What a person needs while and after a build runs (sections 7 and 8): a run is +named by its id or an unambiguous prefix of it (find_run); run_details reads +its row, and its logs are read after the project is closed again (read_log, +launcher.progress), so looking works during a build in another process; +follow repeats that until the run ends; cancel writes a running run's cancel +file, which its builder's launcher acts on; stop kills what a +run whose builder is gone left running and marks it unknown. estimate runs +the build steps' estimate commands from the same snapshot a build would use, +each under the launcher with small limits in a throwaway directory, and +stores what they print in a fourth table, estimates, keyed by reference and +the SHA-256 of the definition text it was measured for; stored_estimates +gives plan.py the ones whose definition is unchanged. """ from contextlib import contextmanager import fcntl +import hashlib import json +import math import os +import re import shutil +import stat import time import uuid @@ -43,6 +61,13 @@ RECIPE_INPUT = '{recipe}' # the inputs key of a benchmark subject's recipe; never a valid input name OPEN_WAIT_SECONDS = 60 # how long execute waits for a project another command has open PROBLEMS_SHOWN = 5 +RUN_PREFIX_MINIMUM = 6 # a run may be named by at least this many of its first characters +FOLLOW_SECONDS = 2.0 # how often progress --follow looks again +ESTIMATES = 'estimates' # /estimates//: an estimate's throwaway directory +ESTIMATE_LIMITS = {'wall_seconds': 300.0, 'disk_bytes': 100 * 1000 ** 2} +ESTIMATE_OUTPUT_LIMIT = 64 * 1024 # bytes of standard output an estimate may print +ESTIMATE_FIELDS = ('disk_bytes', 'wall_seconds', 'items') +_RUN_TEXT = re.compile(r'[A-Za-z0-9][A-Za-z0-9_.-]{0,127}') TABLES = ( '''CREATE TABLE IF NOT EXISTS {schema}.plans ( @@ -69,11 +94,15 @@ directory text NOT NULL, outputs jsonb NOT NULL, current boolean NOT NULL)''', 'CREATE UNIQUE INDEX IF NOT EXISTS products_current ON {schema}.products (reference, subject) WHERE current', + '''CREATE TABLE IF NOT EXISTS {schema}.estimates ( + reference text PRIMARY KEY, definition_sha256 text NOT NULL, + "values" jsonb NOT NULL, measured_at timestamptz NOT NULL)''', ) _RUN_COLUMNS = ('id', 'reference', 'subject', 'plan_id', 'state', 'scratch', 'commit', 'inputs', 'environment', 'argv', 'directory', 'owner_pid', 'owner_boot', 'queued_at', 'started_at', 'finished_at', 'exit_status', 'seconds', 'bytes', 'strays', 'problem') +_DETAIL_COLUMNS = _RUN_COLUMNS + ('definition', 'settings', 'env') def _q(schema, template): @@ -96,9 +125,10 @@ def _short(run_id): # ----------------------------------------------------------- the store's hooks def forget(connection, schema, reference): - """Drop the runs and products records of a definition that is gone; their files are left where they are.""" + """Drop the runs, products and estimate records of a definition that is gone; their files are left where they are.""" connection.execute(_q(schema, 'DELETE FROM {schema}.products WHERE reference = %s'), (reference,)) connection.execute(_q(schema, 'DELETE FROM {schema}.runs WHERE reference = %s'), (reference,)) + connection.execute(_q(schema, 'DELETE FROM {schema}.estimates WHERE reference = %s'), (reference,)) def boot_id(): @@ -376,6 +406,10 @@ class StepProblem(Exception): """A step that cannot be started as its definition stands; it fails before anything runs.""" +class MissingInput(StepProblem): + """An estimate command (or the env) names an input that has no current product: the estimate is skipped.""" + + def fill(text, values): """text with every {name} replaced from values; '{{' and '}}' become literal braces. @@ -408,8 +442,11 @@ def _fill(text, values, missing, where): return fill(text, values) except KeyError as exc: name = exc.args[0] - reason = missing.get(name, f'{{{name}}} cannot be filled here') - raise StepProblem(f'{where} uses {{{name}}}, but {reason}.') from None + if name in missing and name.startswith('inputs.'): + raise MissingInput(f'It needs {{{name}}}, but {missing[name]}.') from None + if name in missing: + raise StepProblem(f'{where} uses {{{name}}}, but {missing[name]}.') from None + raise StepProblem(f'{where} uses {{{name}}}, but {{{name}}} cannot be filled here.') from None except ValueError as exc: raise StepProblem(f'{where} {exc}.') from None @@ -417,12 +454,12 @@ def _fill(text, values, missing, where): # -------------------------------------------------------------------- execute @contextmanager -def _opened(folder, dsn): +def opened(folder, dsn=None, *, rebind=False, on_conflict=None): """Open the project for a moment, waiting while another command has it open.""" deadline = time.monotonic() + OPEN_WAIT_SECONDS while True: try: - project = store.open_project(folder, dsn=dsn) + project = store.open_project(folder, dsn=dsn, rebind=rebind, on_conflict=on_conflict) break except store.ProjectError as exc: if exc.code != 'busy' or time.monotonic() > deadline: @@ -506,8 +543,15 @@ def environment(self, project, reference): # ---------------------------------------------------------------- prepare - def _resolve(self, project, reference, subject): - """Everything a run needs, with the project open: (row values, argv, env, cwd, limits, gpu).""" + def _resolve(self, project, reference, subject, *, estimate=False): + """Everything a run needs, with the project open: (row values, argv, env, cwd, limits, gpu). + + With estimate, the command is run.estimate.command, the directory is a + throwaway one under /estimates/, {output} names a path that + does not exist, the limits are ESTIMATE_LIMITS, and an input with no + current product is a problem only when a placeholder names it + (prepared['skipped'] is then true). + """ directory_name, name = documents.parse_reference(reference) row = project._execute('SELECT text, document FROM {schema}.definitions ' 'WHERE directory = %s AND name = %s AND NOT removed', (directory_name, name)).fetchone() @@ -516,8 +560,10 @@ def _resolve(self, project, reference, subject): text, document = row run = _run_block(document) run_id = uuid.uuid4().hex - run_directory = os.path.join(local.home(project.project_id), RUNS, run_id) + run_directory = os.path.join(local.home(project.project_id), ESTIMATES if estimate else RUNS, run_id) output = os.path.join(run_directory, OUTPUT) + estimate_block = run.get('estimate') if isinstance(run.get('estimate'), dict) else {} + command = list(estimate_block.get('command') or []) if estimate else list(run.get('command') or []) values, missing, recorded = {'output': output}, {}, {} environment_record = None @@ -528,15 +574,18 @@ def _resolve(self, project, reference, subject): prepared = {'id': run_id, 'reference': reference, 'subject': subject['name'] if subject else '', 'definition': text, 'settings': None, 'environment': environment_record, - 'directory': run_directory, 'argv': list(run.get('command') or []), 'env': {}, - 'problem': None} + 'directory': run_directory, 'argv': list(command), 'env': {}, + 'problem': None, 'skipped': False} try: - if not run.get('command'): - raise StepProblem(f'{reference} has no run.command, so it cannot be built.') + if not command: + raise StepProblem(f'{reference} has no run.estimate.command.' if estimate else + f'{reference} has no run.command, so it cannot be built.') for input_name, (used, output_name) in _declared_inputs(document).items(): product = _current_product(project, used) if product is None: - missing[f'inputs.{input_name}'] = f'{used} has no current product' + missing[f'inputs.{input_name}'] = f'its input {input_name} ({used}) has no current product' + if estimate: + continue raise StepProblem(f'Its input {input_name} ({used}) has no current product; build it first.') path = product['directory'] if output_name is not None: @@ -561,6 +610,9 @@ def _resolve(self, project, reference, subject): 'output': None} values['subject'] = (_fill(argument, recipe_values, {}, f'The argument of subject {subject["name"]}') if isinstance(argument, str) else subject['name']) + elif estimate: + for name in ('subject', 'subject.name'): + missing[name] = "an estimate is made once for the whole benchmark, not per subject" if 'settings' in run: values['settings'] = os.path.join(run_directory, SETTINGS_FILE) prepared['settings'] = settings_text(document, self.code.code_root) @@ -570,8 +622,8 @@ def _resolve(self, project, reference, subject): if prepared['settings'] is None: raise StepProblem(f'Its settings file {run["settings_file"]} cannot be read in the code ' f'at commit {self.code.commit[:12] or "(none)"}.') - argv = [_fill(part, values, missing, f'The command word {part!r}') for part in run['command']] - if run['command'][0] == 'python': + argv = [_fill(part, values, missing, f'The command word {part!r}') for part in command] + if command[0] == 'python': if environment_record is None: raise StepProblem('The command starts with python but the run names no environment.') argv[0] = environment_record['interpreter'] @@ -601,9 +653,12 @@ def _resolve(self, project, reference, subject): wall_hours = resources.get('wall_hours') or DEFAULT_WALL_HOURS disk_gb = resources.get('disk_gb') or DEFAULT_DISK_GB prepared['limits'] = {'wall_seconds': float(wall_hours) * 3600, 'disk_bytes': int(float(disk_gb) * GB)} + if estimate: + prepared['limits'] = dict(ESTIMATE_LIMITS) prepared['gpu'] = gpu except StepProblem as exc: prepared['problem'] = str(exc) + prepared['skipped'] = isinstance(exc, MissingInput) prepared['inputs'] = recorded prepared['outputs'] = run.get('outputs') if isinstance(run.get('outputs'), dict) else {} prepared['kind'] = _kind(reference) @@ -627,7 +682,7 @@ def _insert(self, project, prepared, state): def run_one(self, reference, subject=None): """Run one step (one subject of a benchmark); return the item reported for it.""" - with _opened(self.folder, self.dsn) as project: + with opened(self.folder, self.dsn) as project: prepared = self._resolve(project, reference, subject) item = {'reference': reference, 'subject': prepared['subject'], 'run_id': prepared['id'], 'directory': prepared['directory']} @@ -650,14 +705,14 @@ def run_one(self, reference, subject=None): outcome = launcher.Outcome('failed', None, 0.0, 0, _size(prepared['directory'])) started_problem = str(exc) or f'The command could not be started ({type(exc).__name__}).' except BaseException: - with _opened(self.folder, self.dsn) as project: + with opened(self.folder, self.dsn) as project: project._execute("UPDATE {schema}.runs SET state = 'unknown', finished_at = now(), " "problem = 'The build was interrupted while the command ran.' WHERE id = %s", (prepared['id'],)) raise else: started_problem = None - with _opened(self.folder, self.dsn) as project: + with opened(self.folder, self.dsn) as project: state, problem = self._finish(project, prepared, outcome, started_problem) item.update(state=state, problem=problem, seconds=outcome.seconds) return item @@ -768,7 +823,7 @@ def execute(project_folder, plan, *, confirm, extra_env=None, scratch=False, dsn 'running', references=running) build = _Build(folder, plan, extra_env=extra_env, scratch=scratch, dsn=dsn, on_event=on_event) if to_build: - with _opened(folder, dsn) as project: + with opened(folder, dsn) as project: state = project._state() code_paths = (store._read_project_file(state['folder']) or {}).get('code_paths') code_root = _code_root(project) @@ -781,7 +836,7 @@ def execute(project_folder, plan, *, confirm, extra_env=None, scratch=False, dsn if not confirm(plan): return result result['confirmed'] = True - with _opened(folder, dsn) as project: + with opened(folder, dsn) as project: project._execute('INSERT INTO {schema}.plans (id, created_at, targets, steps, scratch) ' 'VALUES (%s, now(), %s, %s, %s)', (build.plan_id, Jsonb(plan['targets']), Jsonb(plan['steps']), scratch)) @@ -790,14 +845,14 @@ def execute(project_folder, plan, *, confirm, extra_env=None, scratch=False, dsn reference = step['reference'] if step['kind'] == 'environment': if reference in needed_environments: - with _opened(folder, dsn) as project: + with opened(folder, dsn) as project: build.environment(project, reference) continue if step['action'] != 'build': result['skipped'].append(reference) continue if step['kind'] == 'benchmark': - with _opened(folder, dsn) as project: + with opened(folder, dsn) as project: document = project.definition(reference)['document'] entry = status(project).get(reference) or {} built = {name for name, item in (entry.get('subjects') or {}).items() if item['state'] == 'built'} @@ -813,3 +868,349 @@ def execute(project_folder, plan, *, confirm, extra_env=None, scratch=False, dsn return result result['ok'] = True return result + + +# --------------------------------------------------------- one run, by name + +def find_run(project, text): + """The id of the run named by text: its id, or an unambiguous prefix of at least RUN_PREFIX_MINIMUM characters. + + Raises ProjectError: not-found when nothing matches (or the prefix is too + short), ambiguous when a prefix matches several runs, with them listed. + """ + if not isinstance(text, str) or not _RUN_TEXT.fullmatch(text): + raise store.ProjectError(f'{text!r} is not a run id.', 'not-found') + if project._execute('SELECT 1 FROM {schema}.runs WHERE id = %s', (text,)).fetchone() is not None: + return text + if len(text) < RUN_PREFIX_MINIMUM: + raise store.ProjectError(f'There is no run {text}; name a run by its id or at least its first ' + f'{RUN_PREFIX_MINIMUM} characters.', 'not-found') + rows = project._execute('SELECT id, reference, subject, state FROM {schema}.runs ' + 'WHERE left(id, %s) = %s ORDER BY queued_at DESC, id', (len(text), text)).fetchall() + if not rows: + raise store.ProjectError(f'There is no run {text}.', 'not-found') + if len(rows) > 1: + listed = '\n'.join(f' {run_id} {reference} {subject or "-"} {state}' + for run_id, reference, subject, state in rows) + raise store.ProjectError(f'{text} is the start of {len(rows)} runs; give more of the id:\n{listed}', 'ambiguous', + references=[run_id for run_id, *_ in rows]) + return rows[0][0] + + +def _row(project, run_id): + row = project._execute('SELECT ' + ', '.join(_DETAIL_COLUMNS) + ' FROM {schema}.runs WHERE id = %s', + (run_id,)).fetchone() + return dict(zip(_DETAIL_COLUMNS, row)) + + +def builder_alive(row): + """Whether the build process recorded in a run's row is still running on this boot.""" + return bool(row['owner_pid']) and row['owner_boot'] == boot_id() and _alive(row['owner_pid']) + + +def run_details(project, text): + """One run's row (every column), its product when it made one, and whether its builder is alive. + + Orphaned runs are marked unknown first. The logs are not read here: the + caller reads them from row['directory'] after closing the project. + """ + run_id = find_run(project, text) + reap_orphans(project._connection, project.schema) + row = _row(project, run_id) + product = project._execute('SELECT directory, outputs, current FROM {schema}.products WHERE run_id = %s', + (run_id,)).fetchone() + row['product'] = None if product is None else dict(zip(('directory', 'outputs', 'current'), product)) + row['builder_alive'] = row['state'] in ACTIVE and builder_alive(row) + return row + + +def read_log(directory, name, offset, *, final=False): + """What a run's .log holds from offset on: {text, offset, size, skipped}. + + At most launcher.LOG_TAIL bytes are read; when more were written since + offset, the earlier ones are skipped (counted in skipped) and the first, + cut line is dropped. Unless final, only complete lines are taken, so a + line is never printed in two pieces. Links are not followed; a missing + log reads as empty. + """ + empty = {'text': '', 'offset': offset, 'size': None, 'skipped': 0} + try: + directory_fd = os.open(directory, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW | os.O_CLOEXEC) + except OSError: + return empty + try: + try: + descriptor = os.open(f'{name}.log', os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK | os.O_CLOEXEC, + dir_fd=directory_fd) + except OSError: + return empty + try: + status = os.fstat(descriptor) + if not stat.S_ISREG(status.st_mode): + return empty + size = status.st_size + offset = min(offset, size) + start = max(offset, size - launcher.LOG_TAIL) + data = os.pread(descriptor, size - start, start) + finally: + os.close(descriptor) + finally: + os.close(directory_fd) + if not final: + data = data[:data.rfind(b'\n') + 1] + end = start + len(data) + if start > offset: + cut = data.find(b'\n') + data = data[cut + 1:] if cut >= 0 else b'' + text = launcher._CONTROL.sub('', data.decode('utf-8', errors='replace')) + return {'text': text, 'offset': end, 'size': size, 'skipped': start - offset} + + +def run_summary(row): + """The few fields of a run's row that progress shows beside its logs.""" + return {name: row[name] for name in ('id', 'reference', 'subject', 'state', 'directory', 'started_at', + 'finished_at', 'seconds', 'problem')} + + +def follow(folder, text, *, dsn=None, interval=None, rebind=False, on_conflict=None): + """Yield one pass every interval seconds (FOLLOW_SECONDS) until the run is no longer queued or running. + + Each pass opens the project only to read the run's row, then reads the + logs with it closed: {run (id, reference, subject, state, ...), event (the + latest progress event), new_event (true when it differs from the last + pass), stdout, stderr (text written since the last pass), skipped_stdout, + skipped_stderr (bytes not shown because more was written than one pass + shows), ended}. The first pass shows the last part of each log. + """ + interval = FOLLOW_SECONDS if interval is None else interval + offsets = {name: 0 for name in launcher.LOGS} + last_event, run_id = None, text + while True: + with opened(folder, dsn, rebind=rebind, on_conflict=on_conflict) as project: + row = run_details(project, run_id) + run_id = row['id'] + ended = row['state'] not in ACTIVE + found = launcher.progress(row['directory']) + item = {'run': run_summary(row), 'event': found['event'], 'new_event': found['event'] != last_event, + 'ended': ended} + last_event = found['event'] + for name in launcher.LOGS: + read = read_log(row['directory'], name, offsets[name], final=ended) + offsets[name] = read['offset'] + item[name], item[f'skipped_{name}'] = read['text'], read['skipped'] + yield item + if ended: + return + time.sleep(interval) + + +def cancel(project, text): + """Ask a queued or running run to stop by creating its cancel file; its builder's launcher does the stopping. + + Raises ProjectError (not-active) for a run in any other state. Does not + wait. Returns {id, reference, subject, state, cancel_file, already_asked}. + """ + row = run_details(project, text) + if row['state'] not in ACTIVE: + hint = (' Its build is gone; stop kills anything it left running.' if row['state'] == 'unknown' else '') + raise store.ProjectError(f'Run {row["id"]} ({row["reference"]}) is {row["state"]}; only a queued or running run ' + f'can be cancelled.{hint}', 'not-active', references=[row['reference']]) + os.makedirs(row['directory'], exist_ok=True) # a queued run's directory may not be made yet + path = os.path.join(row['directory'], launcher.CANCEL_FILE) + already = os.path.lexists(path) + if not already: + try: + os.close(os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW | os.O_CLOEXEC, 0o644)) + except FileExistsError: + already = True + return {'id': row['id'], 'reference': row['reference'], 'subject': row['subject'], 'state': row['state'], + 'cancel_file': path, 'already_asked': already} + + +def stop(folder, text, *, dsn=None, rebind=False, on_conflict=None): + """For a run whose builder is gone: kill every process that carries its run id, and mark it unknown. + + Refused (ProjectError builder-alive) while the run is queued or running + and the build process recorded in its row still runs on this boot: that + run is stopped with cancel. The project is closed while the processes are + stopped. Returns {id, reference, subject, was, state, killed, remaining, + marked_unknown}; remaining lists the pids that could not be stopped. + """ + with opened(folder, dsn, rebind=rebind, on_conflict=on_conflict) as project: + row = _row(project, find_run(project, text)) + if row['state'] in ACTIVE and builder_alive(row): + raise store.ProjectError(f'Run {row["id"]} ({row["reference"]}) is still being run by its build (process ' + f'{row["owner_pid"]}); use cancel to stop it.', 'builder-alive', + references=[row['reference']]) + result = launcher.stop_strays(row['id']) + marked = False + with opened(folder, dsn, rebind=rebind, on_conflict=on_conflict) as project: + if row['state'] in ACTIVE: + problem = (f'Stopped with stop: the build that ran it (process {row["owner_pid"]}) was gone; ' + f'{result["killed"]} stray process' + ('' if result['killed'] == 1 else 'es') + + ' killed.') + marked = project._execute('''UPDATE {schema}.runs SET state = 'unknown', problem = %s, + finished_at = coalesce(finished_at, now()), + strays = coalesce(strays, 0) + %s + WHERE id = %s AND state = ANY(%s) RETURNING id''', + (problem, result['killed'], row['id'], list(ACTIVE))).fetchone() is not None + reap_orphans(project._connection, project.schema) + state = project._execute('SELECT state FROM {schema}.runs WHERE id = %s', (row['id'],)).fetchone()[0] + return {'id': row['id'], 'reference': row['reference'], 'subject': row['subject'], 'was': row['state'], + 'state': state, 'killed': result['killed'], 'remaining': result['remaining'], 'marked_unknown': marked} + + +# ------------------------------------------------------------------ estimates + +def _sha256_text(text): + return hashlib.sha256(text.encode('utf-8')).hexdigest() + + +def stored_estimates(project): + """{reference: {disk_bytes, wall_seconds, items, measured_at (ISO 8601 text)}} for the definitions' current text. + + An estimate measured for another text of the definition is left out. + """ + rows = project._execute('''SELECT e.reference, e."values", e.measured_at + FROM {schema}.estimates e JOIN {schema}.definitions d + ON d.directory || '/' || d.name = e.reference AND NOT d.removed + WHERE e.definition_sha256 = encode(sha256(convert_to(d.text, 'UTF8')), 'hex')''') + return {reference: {**{field: values.get(field) for field in ESTIMATE_FIELDS}, + 'measured_at': measured_at.isoformat(timespec='seconds')} + for reference, values, measured_at in rows.fetchall()} + + +def _first_line(directory, name): + text = read_log(directory, name, 0, final=True)['text'].strip() + return text.splitlines()[-1][:400] if text else '' + + +def _estimate_values(outcome, directory): + """(values, None) from what a finished estimate command printed, or (None, why it is not an estimate).""" + if outcome.state != 'succeeded': + said = _first_line(directory, 'stderr') + reason = {'failed': f'The estimate command exited with status {outcome.exit_status}', + 'timed-out': f'The estimate command ran past its limit of ' + f'{ESTIMATE_LIMITS["wall_seconds"] / 60:g} minutes and was stopped', + 'over-disk': f'The estimate command wrote more than ' + f'{ESTIMATE_LIMITS["disk_bytes"] / 1000 ** 2:g} MB and was stopped', + 'cancelled': 'The estimate command was stopped'}.get( + outcome.state, 'A process of the estimate command could not be stopped') + return None, reason + (f'; its last error line: {said}' if said else '.') + try: + with open(os.path.join(directory, 'stdout.log'), 'rb') as handle: + raw = handle.read(ESTIMATE_OUTPUT_LIMIT + 1) + except OSError: + raw = b'' + if len(raw) > ESTIMATE_OUTPUT_LIMIT: + return None, f'It printed more than {ESTIMATE_OUTPUT_LIMIT // 1024} KiB; it must print one JSON object.' + if not raw.strip(): + return None, 'It printed nothing; it must print one JSON object.' + try: + document = launcher._decode_json(raw.decode('utf-8')) + except UnicodeDecodeError: + return None, 'Its standard output is not UTF-8 text; it must print one JSON object.' + except (ValueError, RecursionError) as exc: + return None, f'Its standard output is not one JSON object ({exc}).' + if not isinstance(document, dict): + return None, f'Its standard output is a JSON {type(document).__name__}, not an object.' + values = {} + for field in ESTIMATE_FIELDS: + if field not in document: + continue + value = document[field] + if type(value) not in (int, float) or not math.isfinite(value) or value < 0: + return None, f'Its {field} is {json.dumps(value)}; it must be a number of at least 0.' + values[field] = value + if not values: + return None, 'Its object has none of ' + ', '.join(ESTIMATE_FIELDS) + '.' + return values, None + + +def estimate(project_folder, targets, *, every=False, scratch=False, extra_env=None, dsn=None, on_event=None): + """Run the estimate command of each build step in the plan for targets, and store what each prints (section 7). + + The code is the snapshot a build would use (ProjectError with the + SnapshotError's code when it cannot be prepared: dirty, not-in-git, ...). + Each command runs through launcher.run in /estimates//, + removed afterwards, with ESTIMATE_LIMITS, the child environment a build + step would get and {output} naming a path that does not exist. A step + without an estimate command, or whose estimate command or env names an + input with no current product, is skipped; one whose command fails or + prints anything but one JSON object fails, and the next step still runs. + on_event(item) is called after each step. + + Returns {targets, scratch, commit, steps: [{reference, result (measured, + skipped or failed), reason, values, seconds}]}. + """ + from . import plan as planning + + folder = os.fspath(project_folder) + on_event = on_event or (lambda item: None) + with opened(folder, dsn) as project: + made = planning.build_plan(project, targets, every=every) + state = project._state() + code_paths = (store._read_project_file(state['folder']) or {}).get('code_paths') + code_root = _code_root(project) + home = local.home(project.project_id, create=True) + documents_ = project._documents(removed=False) + build = _Build(folder, made, extra_env=extra_env, scratch=scratch, dsn=dsn, on_event=None) + result = {'targets': made['targets'], 'scratch': scratch, 'commit': None, 'steps': []} + to_build = [step['reference'] for step in made['steps'] if step['action'] == 'build'] + with_command = [reference for reference in to_build + if (_run_block(documents_[reference]).get('estimate') or {}).get('command')] + if with_command: + try: + build.code = snapshot.prepare(code_root, code_paths, home=home, scratch=scratch) + except snapshot.SnapshotError as exc: + raise _snapshot_error(exc) from None + result['commit'] = build.code.commit + for reference in to_build: + item = {'reference': reference, 'result': 'skipped', 'reason': None, 'values': None, 'seconds': None} + if reference not in with_command: + item['reason'] = 'It has no estimate command.' + else: + _estimate_one(build, reference, item) + result['steps'].append(item) + on_event(item) + return result + + +def _estimate_one(build, reference, item): + with opened(build.folder, build.dsn) as project: + try: + prepared = build._resolve(project, reference, None, estimate=True) + except store.ProjectError as exc: + if exc.code != 'not-ready': + raise + item.update(result='failed', reason=str(exc).replace('then build again', 'then estimate again')) + return + if prepared['problem'] is not None: + item.update(result='skipped' if prepared['skipped'] else 'failed', reason=prepared['problem']) + return + directory = prepared['directory'] + os.makedirs(directory) + try: + if prepared['inline_settings']: + with open(os.path.join(directory, SETTINGS_FILE), 'w', encoding='utf-8') as handle: + handle.write(prepared['settings']) + try: + outcome = launcher.run(prepared['argv'], cwd=build.code.code_root, env=prepared['env'], + run_id=prepared['id'], directory=directory, limits=prepared['limits']) + except Exception as exc: # launcher.run raises only before the command has started + item.update(result='failed', reason=str(exc) or f'The command could not be started ({type(exc).__name__}).') + return + item['seconds'] = outcome.seconds + values, reason = _estimate_values(outcome, directory) + finally: + snapshot._remove(directory) + if values is None: + item.update(result='failed', reason=reason) + return + with opened(build.folder, build.dsn) as project: + project._execute('''INSERT INTO {schema}.estimates (reference, definition_sha256, "values", measured_at) + VALUES (%s, %s, %s, now()) + ON CONFLICT (reference) DO UPDATE SET definition_sha256 = EXCLUDED.definition_sha256, + "values" = EXCLUDED."values", measured_at = EXCLUDED.measured_at''', + (reference, _sha256_text(prepared['definition']), Jsonb(values))) + item.update(result='measured', values=values) diff --git a/tuldok_project/plan.py b/tuldok_project/plan.py index 6b7c0aa5..76737469 100644 --- a/tuldok_project/plan.py +++ b/tuldok_project/plan.py @@ -11,7 +11,11 @@ needs-work), and adds up the figures the build steps declare in run.resources. build_plan reads the definitions from a Project's database copy and the recorded environment states and calls it. Making a plan runs nothing and opens no file: no command, no -estimate command, nothing on disk; an estimate is always null here. +estimate command, nothing on disk. A step's estimate is what the estimate +command printed when `estimate` last ran it (spec-m6.md section 7), read from +the database and given only while the definition's text is the one it was +measured for; otherwise null. The totals add up those estimates beside the +declared figures, never mixing the two. With what was built on this machine (spec-m6.md section 5), a step that is built has the action built and is not work; one that is out-of-date or failed is built again, and its reasons say why. build_plan reads those states from @@ -162,7 +166,14 @@ def _total(steps, field): return round(math.fsum(numbers), 6), len(declared) - len(numbers) -def make_plan(definitions, targets, *, every=False, local=None, built=None): +def _estimated(steps, field, scale): + """(sum of the estimated field over build steps that have one, divided by scale; how many have one).""" + values = [step['estimate'][field] for step in steps + if step['action'] == 'build' and step['estimate'] and step['estimate'].get(field) is not None] + return math.fsum(values) / scale, len(values) + + +def make_plan(definitions, targets, *, every=False, local=None, built=None, estimates=None): """The plan for targets over {reference: document}, as section 3 and 4 of spec-m4.md describe it. local is graph.states' mapping of references to the state recorded on @@ -170,6 +181,8 @@ def make_plan(definitions, targets, *, every=False, local=None, built=None): built. built is builds.status' mapping of reference to {causes, scratch}; each step's reasons are its causes (why it is out of date, failed or running) and scratch says whether its current product is a scratch one. + estimates is builds.stored_estimates' mapping of reference to the + current estimate ({disk_bytes, wall_seconds, items, measured_at}). every adds every dataset, recipe, step and benchmark to the targets. A chart target is replaced by its benchmark; a model target adds nothing @@ -209,7 +222,8 @@ def make_plan(definitions, targets, *, every=False, local=None, built=None): step = {'number': number, 'reference': reference, 'kind': kind, 'title': document.get('title'), 'state': states[reference], 'action': action, 'command': run.get('command'), 'environment': run.get('environment'), - 'inputs': _inputs(document), 'resources': _resources(document), 'estimate': None, + 'inputs': _inputs(document), 'resources': _resources(document), + 'estimate': (estimates or {}).get(reference), 'blocked_by': [], 'blocked_by_more': 0, 'reasons': list((built or {}).get(reference, {}).get('causes', [])), 'scratch': bool((built or {}).get(reference, {}).get('scratch', False))} @@ -227,6 +241,8 @@ def make_plan(definitions, targets, *, every=False, local=None, built=None): blocked = {step['reference'] for step in steps if step['action'] == 'blocked'} disk_gb, disk_unknown = _total(steps, 'disk_gb') wall_hours, wall_unknown = _total(steps, 'wall_hours') + estimated_disk_gb, estimated_disk_steps = _estimated(steps, 'disk_bytes', 1000 ** 3) + estimated_wall_hours, estimated_wall_steps = _estimated(steps, 'wall_seconds', 3600) return {'targets': resolved, 'every': every, 'buildable': not any(reference in blocked for reference in resolved), 'blocked_targets': [reference for reference in resolved if reference in blocked], @@ -234,6 +250,8 @@ def make_plan(definitions, targets, *, every=False, local=None, built=None): 'gpu_steps': sum(step['action'] == 'build' and step['resources']['gpu'] is True for step in steps), 'disk_gb': disk_gb, 'disk_unknown': disk_unknown, 'wall_hours': wall_hours, 'wall_unknown': wall_unknown, + 'estimated_disk_gb': estimated_disk_gb, 'estimated_disk_steps': estimated_disk_steps, + 'estimated_wall_hours': estimated_wall_hours, 'estimated_wall_steps': estimated_wall_steps, 'notes': notes, 'steps': steps} @@ -255,4 +273,5 @@ def build_plan(project, targets, *, every=False): built = builds.status(project) local = {**environments.recorded_states(project._connection, project.schema), **{reference: entry['state'] for reference, entry in built.items()}} - return make_plan(definitions, targets, every=every, local=local, built=built) + return make_plan(definitions, targets, every=every, local=local, built=built, + estimates=builds.stored_estimates(project)) From d3340b5f630cf6b2b98ecf168935f215c8bb4586 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 12 Nov 2026 01:38:52 -0700 Subject: [PATCH 025/131] docs(examples): a tiny project that builds end to end examples/tiny-project is the smallest real project for the new format: a dataset of noisy sine curves, a three-layer network trained on a GPU in under a minute, a benchmark against a predict-zero baseline, and two charts. Its README gives the commands to connect two environments, plan, build, follow progress and draw the charts. Co-Authored-By: Claude Fable 5.2 --- examples/tiny-project/README.md | 141 ++++++++++++++++++ examples/tiny-project/code/bench.py | 98 ++++++++++++ examples/tiny-project/code/make_waves.py | 45 ++++++ examples/tiny-project/code/net.py | 11 ++ .../code/settings/small-net-a.json | 6 + examples/tiny-project/code/train.py | 92 ++++++++++++ .../project/benchmarks/held-out.json | 23 +++ .../project/charts/held-out-ranking.json | 8 + .../project/charts/held-out-tradeoff.json | 9 ++ .../tiny-project/project/datasets/waves.json | 14 ++ .../project/environments/cpu.json | 8 + .../project/environments/gpu.json | 8 + .../project/models/small-net.json | 8 + .../project/recipes/small-net-a.json | 20 +++ examples/tiny-project/project/tuldok.json | 6 + 15 files changed, 497 insertions(+) create mode 100644 examples/tiny-project/README.md create mode 100644 examples/tiny-project/code/bench.py create mode 100644 examples/tiny-project/code/make_waves.py create mode 100644 examples/tiny-project/code/net.py create mode 100644 examples/tiny-project/code/settings/small-net-a.json create mode 100644 examples/tiny-project/code/train.py create mode 100644 examples/tiny-project/project/benchmarks/held-out.json create mode 100644 examples/tiny-project/project/charts/held-out-ranking.json create mode 100644 examples/tiny-project/project/charts/held-out-tradeoff.json create mode 100644 examples/tiny-project/project/datasets/waves.json create mode 100644 examples/tiny-project/project/environments/cpu.json create mode 100644 examples/tiny-project/project/environments/gpu.json create mode 100644 examples/tiny-project/project/models/small-net.json create mode 100644 examples/tiny-project/project/recipes/small-net-a.json create mode 100644 examples/tiny-project/project/tuldok.json diff --git a/examples/tiny-project/README.md b/examples/tiny-project/README.md new file mode 100644 index 00000000..01bccdec --- /dev/null +++ b/examples/tiny-project/README.md @@ -0,0 +1,141 @@ +# Tiny project + +The smallest real Tuldok project: a dataset, a network trained on a GPU, a +benchmark and two charts. Building it end to end takes about a minute, and it +uses every part of a build: environments, a command per definition, a product +passed from one definition to the next, progress lines while training, a +benchmark's results imported into the database, and charts drawn from them. +Copy it as the starting point for a project of your own. + +The task: read 64 noisy samples of a sine wave whose amplitude, frequency and +phase are random, and predict the next 16 samples of the clean wave. + +| Folder | Holds | +| --- | --- | +| `project/` | the project folder: `tuldok.json` and the definitions | +| `code/` | the code root (`code_root` is `../code`): the scripts the commands run | + +| Definition | What it does | +| --- | --- | +| `environments/cpu` | Python 3.12 with numpy 2.3.5 | +| `environments/gpu` | Python 3.14 with torch 2.14.0+cu132 and numpy 2.5.3, with CUDA | +| `datasets/waves` | `make_waves.py` writes `waves.npz`: 4,000 training and 400 test waves from seed 7 | +| `models/small-net` | `net.py`'s `SmallNet`: fully connected, 64 to 256 to 256 to 16 | +| `recipes/small-net-a` | `train.py` trains it on the GPU for the updates in `code/settings/small-net-a.json` | +| `benchmarks/held-out` | `bench.py` scores a subject on the 400 test waves: error (RMSE) and time per wave | +| `charts/held-out-ranking` | the subjects ranked by error | +| `charts/held-out-tradeoff` | error against time per wave | + +The benchmark has two subjects: `small-net-a`, the trained network, and +`predict-zero`, which always predicts zero and shows the error any model has to +beat. + +## What it needs + +- Two Python interpreters that already exist on the machine (there is no + `install` section, so Tuldok does not install them; it connects them): + - one with **Python 3.12 and numpy 2.3.5** for `environments/cpu`; + - one with **Python 3.14, torch 2.14.0+cu132 and numpy 2.5.3**, on a machine + where torch sees a CUDA GPU, for `environments/gpu`. + + Versions are checked exactly. If yours differ, edit the two files under + `project/environments/` to match, or the check fails and says what it found. +- A Postgres database for Tuldok's working copy, named by `TULDOK_DATABASE_URL` + (or `--database-url` on every command). +- The example committed to Git. A build runs each command from a read-only copy + of the commit, so uncommitted or untracked changes under `code/` are not seen: + a changed tracked file stops the build, and a file that was never committed is + missing from the copy. `--scratch` runs from the working tree instead and marks + the products as scratch products. + +## Build it + +Run these from the Tuldok repository root. Replace the two interpreter paths +with your own; they must be absolute. + +```sh +export TULDOK_DATABASE_URL=postgresql://... +P=examples/tiny-project/project + +# Check the folder: expect "0 errors, 0 warnings". +.venv/bin/python -m tuldok_project check $P + +# Connect the two interpreters. Each is checked at once; seconds each. +.venv/bin/python -m tuldok_project connect $P cpu /path/to/python3.12-with-numpy/bin/python +.venv/bin/python -m tuldok_project connect $P gpu /path/to/python3.14-with-torch/bin/python +.venv/bin/python -m tuldok_project environments $P + +# See what would be built. Runs nothing. +.venv/bin/python -m tuldok_project plan $P --all + +# Build everything: prints the plan, asks, then runs each step in turn. +.venv/bin/python -m tuldok_project build $P --all +``` + +The plan has three build steps after the two environments: `datasets/waves`, +`recipes/small-net-a`, then `benchmarks/held-out` once for each subject. + +| Step | Time | +| --- | --- | +| `datasets/waves` | about a second on the CPU | +| `recipes/small-net-a` | 6,000 updates; well under a minute on a GPU, much of it starting CUDA. The recipe allows 6 minutes | +| `benchmarks/held-out` | a few seconds per subject, mostly starting torch | + +### Watch the training + +While the recipe runs, in a second terminal: + +```sh +.venv/bin/python -m tuldok_project runs $P +.venv/bin/python -m tuldok_project progress $P RUN --follow +``` + +`RUN` is the run id from `runs` or from the line `build` printed when the step +started; its first six characters are enough. `progress` shows the latest +`tuldok_progress_v1` line (stage `train`, updates done of 6,000, and the loss) +and the ends of the two logs, every two seconds until the run ends. + +### Look at the results + +```sh +.venv/bin/python -m tuldok_project results $P held-out +.venv/bin/python -m tuldok_project chart $P held-out-ranking --svg ranking.svg +.venv/bin/python -m tuldok_project chart $P held-out-tradeoff --svg tradeoff.svg +.venv/bin/python -m tuldok_project report $P --output report.html +.venv/bin/python -m tuldok_project save $P +``` + +`build` imports each subject's `results.json` into the database, so the charts +and the report work straight away. Write the SVG and HTML files somewhere +outside the project folder; `save` writes the benchmark's summary to +`project/results/held-out.csv`, the one built thing that belongs in the folder. + +The trained network's median error should be far below the baseline's: on the +CPU, even 100 updates bring it to about 0.07 against 0.87 for `predict-zero`. + +### Build again + +A second `build $P --all` finds every step `built` and runs nothing. Change +`code/settings/small-net-a.json` (say, `"updates": 3000`) and `plan $P --all` +shows the recipe and the benchmark as out of date; commit the change and build +again to bring them up to date. + +## Running the scripts by hand + +The scripts take everything from their arguments and write only into +`--output`. To try them without a GPU, `train.py` and `bench.py` accept +`--device cpu`, which the definitions never pass; without it they refuse to run +when CUDA is missing. From `code/`, with an interpreter that has numpy and +torch, and an output directory outside the repository (datasets and weights are +never committed): + +```sh +OUT=$(mktemp -d) && mkdir $OUT/data $OUT/train $OUT/bench-net $OUT/bench-zero +python make_waves.py --output $OUT/data --seed 7 +python train.py --data $OUT/data/waves.npz --settings settings/small-net-a.json --output $OUT/train --device cpu +python bench.py --data $OUT/data/waves.npz --subject model:$OUT/train/model.pt --name small-net-a --output $OUT/bench-net --device cpu +python bench.py --data $OUT/data/waves.npz --subject zero --name predict-zero --output $OUT/bench-zero +``` + +On the CPU the 6,000 updates take about ten seconds. Set +`PYTHONDONTWRITEBYTECODE=1` to keep `__pycache__` out of `code/`. diff --git a/examples/tiny-project/code/bench.py b/examples/tiny-project/code/bench.py new file mode 100644 index 00000000..386f932f --- /dev/null +++ b/examples/tiny-project/code/bench.py @@ -0,0 +1,98 @@ +"""Score one subject on the 400 test waves and write results.json (format tuldok_results_v1). + +A subject is either `model:`, a trained SmallNet, or `zero`, +a baseline that always predicts zero: the error a model has to beat. +""" +import argparse +import datetime +import json +import os +import statistics +import sys +import time + +import numpy as np +import torch + +from net import SmallNet + +WARM_UP = 5 # untimed passes first: the first GPU calls pay for start-up, not for the model +REPEATS = 50 # timed passes; their median is the time + + +def model_predictor(path, device): + model = SmallNet() + model.load_state_dict(torch.load(path, map_location='cpu', weights_only=True)) + model = model.to(device).eval() + + def predict(inputs): + with torch.no_grad(): + outputs = model(torch.from_numpy(inputs).to(device)) + return outputs.cpu().numpy() # the copy back waits for the GPU, so the clock sees the whole pass + return predict + + +def zero_predictor(inputs): + return np.zeros((len(inputs), 16), dtype=np.float32) + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument('--data', required=True, help='the waves.npz file') + parser.add_argument('--subject', required=True, help='model:, or zero') + parser.add_argument('--name', required=True, help="the subject's name, written into results.json") + parser.add_argument('--output', required=True, help='the directory to write results.json into') + # As in train.py: the benchmark runs models on the GPU; cpu is for smoke tests. + parser.add_argument('--device', choices=['cuda', 'cpu'], default='cuda') + arguments = parser.parse_args() + + if arguments.subject == 'zero': + predict = zero_predictor # needs no GPU, so it runs anywhere + elif arguments.subject.startswith('model:'): + if arguments.device == 'cuda' and not torch.cuda.is_available(): + sys.exit('bench.py: CUDA is not available to torch, and this benchmark runs models on the GPU. ' + 'Pass --device cpu to smoke-test the script by hand.') + if arguments.device == 'cpu': + torch.set_num_threads(1) # as in train.py: one thread is fastest for a network this small + predict = model_predictor(arguments.subject[len('model:'):], torch.device(arguments.device)) + else: + sys.exit(f'bench.py: unknown subject {arguments.subject!r}; expected model: or zero.') + + with np.load(arguments.data) as waves: + inputs, targets = waves['test_inputs'], waves['test_targets'] + + # Time the whole batch, as a model would be used, and report it per wave. + # Every case of the subject gets the same time; the median of many passes + # keeps one slow pass from deciding it. + for _ in range(WARM_UP): + predict(inputs) + passes = [] + for _ in range(REPEATS): + started = time.perf_counter() + predictions = predict(inputs) + passes.append(time.perf_counter() - started) + time_ms = statistics.median(passes) * 1000.0 / len(inputs) + + errors = np.sqrt(np.mean((predictions.astype(np.float64) - targets) ** 2, axis=1)) + values = [] + for index, error in enumerate(errors): + case = f'test-{index:03d}' + values.append({'case': case, 'metric': 'error', 'value': float(error)}) + values.append({'case': case, 'metric': 'time_ms', 'value': time_ms}) + + document = { + 'format': 'tuldok_results_v1', + 'benchmark': 'held-out', + 'subject': arguments.name, + 'commit': '', # Tuldok records the commit of the run itself + 'produced': datetime.datetime.now(datetime.timezone.utc).date().isoformat(), + 'values': values, + } + with open(os.path.join(arguments.output, 'results.json'), 'w', encoding='utf-8') as handle: + json.dump(document, handle, indent=1) + handle.write('\n') + print(f'{arguments.name}: median error {float(np.median(errors)):.4f}, {time_ms:.6f} ms per wave') + + +if __name__ == '__main__': + main() diff --git a/examples/tiny-project/code/make_waves.py b/examples/tiny-project/code/make_waves.py new file mode 100644 index 00000000..fa831a80 --- /dev/null +++ b/examples/tiny-project/code/make_waves.py @@ -0,0 +1,45 @@ +"""Write waves.npz: noisy sine waves to read, and the clean continuation to predict. + +Every wave has its own amplitude, frequency and phase, so a model has to read +them from the 64 noisy samples it is given before it can continue the wave. +""" +import argparse +import os + +import numpy as np + +SEEN = 64 # noisy samples a model reads +AHEAD = 16 # clean samples it must predict +NOISE = 0.1 # standard deviation of the noise on the samples it reads +COUNTS = {'train': 4000, 'test': 400} + + +def waves(generator, count): + amplitude = generator.uniform(0.5, 2.0, size=(count, 1)) + # Radians per sample: periods from about 16 to 125 samples, so every input + # holds at least half a period and the task is never hopeless. + frequency = generator.uniform(0.05, 0.4, size=(count, 1)) + phase = generator.uniform(0.0, 2.0 * np.pi, size=(count, 1)) + clean = amplitude * np.sin(frequency * np.arange(SEEN + AHEAD) + phase) + noisy = clean[:, :SEEN] + generator.normal(0.0, NOISE, size=(count, SEEN)) + return noisy.astype(np.float32), clean[:, SEEN:].astype(np.float32) + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument('--output', required=True, help='the directory to write waves.npz into') + parser.add_argument('--seed', type=int, required=True) + arguments = parser.parse_args() + + # One generator drawn in a fixed order: the same seed gives the same file. + generator = np.random.default_rng(arguments.seed) + arrays = {} + for split, count in COUNTS.items(): + arrays[f'{split}_inputs'], arrays[f'{split}_targets'] = waves(generator, count) + path = os.path.join(arguments.output, 'waves.npz') + np.savez(path, **arrays) + print(f'wrote {path}: ' + ', '.join(f'{count} {split}' for split, count in COUNTS.items())) + + +if __name__ == '__main__': + main() diff --git a/examples/tiny-project/code/net.py b/examples/tiny-project/code/net.py new file mode 100644 index 00000000..a6bf969b --- /dev/null +++ b/examples/tiny-project/code/net.py @@ -0,0 +1,11 @@ +"""The small network that models/small-net names: 64 samples in, 16 samples out.""" +from torch import nn + + +class SmallNet(nn.Sequential): + def __init__(self, seen=64, hidden=256, ahead=16): + super().__init__( + nn.Linear(seen, hidden), nn.ReLU(), + nn.Linear(hidden, hidden), nn.ReLU(), + nn.Linear(hidden, ahead), + ) diff --git a/examples/tiny-project/code/settings/small-net-a.json b/examples/tiny-project/code/settings/small-net-a.json new file mode 100644 index 00000000..8f43e99b --- /dev/null +++ b/examples/tiny-project/code/settings/small-net-a.json @@ -0,0 +1,6 @@ +{ + "updates": 6000, + "batch": 256, + "learning_rate": 0.001, + "seed": 1 +} diff --git a/examples/tiny-project/code/train.py b/examples/tiny-project/code/train.py new file mode 100644 index 00000000..acbd14b7 --- /dev/null +++ b/examples/tiny-project/code/train.py @@ -0,0 +1,92 @@ +"""Train SmallNet on the training waves and write model.pt and log.json. + +Prints a tuldok_progress_v1 line every 50 updates so Tuldok can show how far +training has come while it runs. +""" +import argparse +import json +import math +import os +import sys +import time + +import numpy as np +import torch + +from net import SmallNet + +EVERY = 50 # updates between progress lines and log entries + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument('--data', required=True, help='the waves.npz file') + parser.add_argument('--settings', required=True, help='a JSON file: updates, batch, learning_rate, seed') + parser.add_argument('--output', required=True, help='the directory to write model.pt and log.json into') + # The recipe trains on the GPU. --device cpu exists only to smoke-test this + # script on a machine without one; the recipe never passes it. + parser.add_argument('--device', choices=['cuda', 'cpu'], default='cuda') + arguments = parser.parse_args() + + if arguments.device == 'cuda' and not torch.cuda.is_available(): + # Refuse rather than fall back: a recipe that says it trains on the GPU + # must not quietly produce a CPU model. + sys.exit('train.py: CUDA is not available to torch, and this recipe trains on the GPU. ' + 'Check the gpu environment (tuldok_project check-environment), ' + 'or pass --device cpu to smoke-test the script by hand.') + device = torch.device(arguments.device) + if arguments.device == 'cpu': + # A network this small runs fastest on one thread; on a many-core machine + # torch's default thread pool makes it a hundred times slower. + torch.set_num_threads(1) + + with open(arguments.settings, encoding='utf-8') as handle: + settings = json.load(handle) + updates, batch = int(settings['updates']), int(settings['batch']) + + # Same seed, same result: the weights are made on the CPU before moving, the + # batches are drawn by a CPU generator, and the GPU is asked for + # deterministic kernels (the recipe sets CUBLAS_WORKSPACE_CONFIG for cuBLAS). + # warn_only keeps a run going if some kernel has no deterministic version. + torch.manual_seed(settings['seed']) + torch.use_deterministic_algorithms(True, warn_only=True) + batches = torch.Generator().manual_seed(settings['seed']) + + with np.load(arguments.data) as waves: + inputs = torch.from_numpy(waves['train_inputs']).to(device) + targets = torch.from_numpy(waves['train_targets']).to(device) + + model = SmallNet().to(device) + optimiser = torch.optim.Adam(model.parameters(), lr=float(settings['learning_rate'])) + loss_function = torch.nn.MSELoss() + log = {'every': EVERY, 'updates': [], 'loss': []} + + started = time.perf_counter() + for update in range(1, updates + 1): + chosen = torch.randint(len(inputs), (batch,), generator=batches).to(device) + loss = loss_function(model(inputs[chosen]), targets[chosen]) + optimiser.zero_grad(set_to_none=True) + loss.backward() + optimiser.step() + if update % EVERY == 0 or update == updates: + value = loss.item() # waits for the GPU only here, not on every update + if not math.isfinite(value): + sys.exit(f'train.py: the loss became {value} at update {update}; stopping.') + log['updates'].append(update) + log['loss'].append(value) + print(json.dumps({'format': 'tuldok_progress_v1', 'stage': 'train', 'completed': update, + 'total': updates, 'metrics': {'loss': value}}), flush=True) + log['seconds'] = time.perf_counter() - started + log['device'] = arguments.device + + # Saved on the CPU so the weights load on any machine. + torch.save({name: tensor.cpu() for name, tensor in model.state_dict().items()}, + os.path.join(arguments.output, 'model.pt')) + with open(os.path.join(arguments.output, 'log.json'), 'w', encoding='utf-8') as handle: + json.dump(log, handle, indent=1) + handle.write('\n') + print(f'trained {updates} updates in {log["seconds"]:.1f} s; final loss {log["loss"][-1]:.5f}') + + +if __name__ == '__main__': + main() diff --git a/examples/tiny-project/project/benchmarks/held-out.json b/examples/tiny-project/project/benchmarks/held-out.json new file mode 100644 index 00000000..44ee9929 --- /dev/null +++ b/examples/tiny-project/project/benchmarks/held-out.json @@ -0,0 +1,23 @@ +{ + "format": "tuldok_definition_v1", + "kind": "benchmark", + "title": "Held-out waves", + "description": "How well each subject predicts the next 16 samples of the 400 test waves, and how long it takes.", + "run": { + "command": ["python", "bench.py", "--data", "{inputs.cases}", "--subject", "{subject}", "--name", "{subject.name}", "--output", "{output}"], + "environment": "environments/gpu", + "inputs": {"cases": {"from": "datasets/waves", "output": "data"}}, + "outputs": {"results": {"path": "results.json", "role": "results"}}, + "resources": {"gpu": true}, + "sources": ["bench.py", "net.py"] + }, + "metrics": [ + {"id": "error", "title": "Prediction error (RMSE)", "better": "lower"}, + {"id": "time_ms", "title": "Time per wave", "units": "ms", "better": "lower"} + ], + "subjects": [ + {"name": "small-net-a", "title": "Small net, 6,000 updates", "recipe": "recipes/small-net-a", "argument": "model:{recipe}/model.pt"}, + {"name": "predict-zero", "title": "Predict zero: the error any model must beat", "argument": "zero"} + ], + "cases": {"dataset": "datasets/waves", "split": "test", "count": 400} +} diff --git a/examples/tiny-project/project/charts/held-out-ranking.json b/examples/tiny-project/project/charts/held-out-ranking.json new file mode 100644 index 00000000..7cd06fb3 --- /dev/null +++ b/examples/tiny-project/project/charts/held-out-ranking.json @@ -0,0 +1,8 @@ +{ + "format": "tuldok_definition_v1", + "kind": "chart", + "title": "Error on the held-out waves", + "benchmark": "benchmarks/held-out", + "form": "ranking", + "metric": "error" +} diff --git a/examples/tiny-project/project/charts/held-out-tradeoff.json b/examples/tiny-project/project/charts/held-out-tradeoff.json new file mode 100644 index 00000000..73e93634 --- /dev/null +++ b/examples/tiny-project/project/charts/held-out-tradeoff.json @@ -0,0 +1,9 @@ +{ + "format": "tuldok_definition_v1", + "kind": "chart", + "title": "Error against time per wave", + "benchmark": "benchmarks/held-out", + "form": "tradeoff", + "metric": "error", + "metric_x": "time_ms" +} diff --git a/examples/tiny-project/project/datasets/waves.json b/examples/tiny-project/project/datasets/waves.json new file mode 100644 index 00000000..3c27c265 --- /dev/null +++ b/examples/tiny-project/project/datasets/waves.json @@ -0,0 +1,14 @@ +{ + "format": "tuldok_definition_v1", + "kind": "dataset", + "title": "Noisy sine waves", + "description": "Each item is 64 samples of a noisy sine wave with a random amplitude, frequency and phase; the target is the next 16 samples of the clean wave.", + "run": { + "command": ["python", "make_waves.py", "--output", "{output}", "--seed", "7"], + "environment": "environments/cpu", + "outputs": {"data": {"path": "waves.npz", "role": "data"}}, + "resources": {"cpu_threads": 1, "wall_hours": 0.05, "disk_gb": 0.1}, + "sources": ["make_waves.py"] + }, + "splits": {"train": 4000, "test": 400} +} diff --git a/examples/tiny-project/project/environments/cpu.json b/examples/tiny-project/project/environments/cpu.json new file mode 100644 index 00000000..604a030f --- /dev/null +++ b/examples/tiny-project/project/environments/cpu.json @@ -0,0 +1,8 @@ +{ + "format": "tuldok_definition_v1", + "kind": "environment", + "title": "Python 3.12 with numpy, on the CPU", + "python": "3.12", + "device": "cpu", + "packages": {"numpy": "2.3.5"} +} diff --git a/examples/tiny-project/project/environments/gpu.json b/examples/tiny-project/project/environments/gpu.json new file mode 100644 index 00000000..1ae0c718 --- /dev/null +++ b/examples/tiny-project/project/environments/gpu.json @@ -0,0 +1,8 @@ +{ + "format": "tuldok_definition_v1", + "kind": "environment", + "title": "Python 3.14 with torch and CUDA", + "python": "3.14", + "device": "cuda", + "packages": {"torch": "2.14.0+cu132", "numpy": "2.5.3"} +} diff --git a/examples/tiny-project/project/models/small-net.json b/examples/tiny-project/project/models/small-net.json new file mode 100644 index 00000000..ebd3f954 --- /dev/null +++ b/examples/tiny-project/project/models/small-net.json @@ -0,0 +1,8 @@ +{ + "format": "tuldok_definition_v1", + "kind": "model", + "title": "Small fully connected network", + "description": "Three fully connected layers, 64 to 256 to 256 to 16, that read 64 samples of a wave and predict the next 16.", + "entry": "net:SmallNet", + "sources": ["net.py"] +} diff --git a/examples/tiny-project/project/recipes/small-net-a.json b/examples/tiny-project/project/recipes/small-net-a.json new file mode 100644 index 00000000..8a467401 --- /dev/null +++ b/examples/tiny-project/project/recipes/small-net-a.json @@ -0,0 +1,20 @@ +{ + "format": "tuldok_definition_v1", + "kind": "recipe", + "title": "Small net, 6,000 updates", + "description": "Trains the small network on the training waves with Adam on mean squared error, on the GPU.", + "model": "models/small-net", + "run": { + "command": ["python", "train.py", "--data", "{inputs.training}", "--settings", "{settings}", "--output", "{output}"], + "environment": "environments/gpu", + "inputs": {"training": {"from": "datasets/waves", "output": "data"}}, + "settings_file": "settings/small-net-a.json", + "env": {"CUBLAS_WORKSPACE_CONFIG": ":4096:8"}, + "outputs": { + "weights": {"path": "model.pt", "role": "weights"}, + "log": {"path": "log.json", "role": "log"} + }, + "resources": {"gpu": true, "wall_hours": 0.1, "disk_gb": 0.1}, + "sources": ["train.py", "net.py"] + } +} diff --git a/examples/tiny-project/project/tuldok.json b/examples/tiny-project/project/tuldok.json new file mode 100644 index 00000000..d44c51b5 --- /dev/null +++ b/examples/tiny-project/project/tuldok.json @@ -0,0 +1,6 @@ +{ + "format": "tuldok_project_v1", + "id": "9a37848258ef4d079bb020f57c8f6dec", + "name": "Tiny project", + "code_root": "../code" +} From 08ffde00c55e88ac11024079a6312bbc677b7bc4 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 12 Nov 2026 01:41:02 -0700 Subject: [PATCH 026/131] docs(plan): record milestone 6 in the ledger Co-Authored-By: Claude Fable 5.2 --- .../execution-ledger.md | 51 +++++++++++++++++++ 1 file changed, 51 insertions(+) diff --git a/docs/plans/definition-first-projects/execution-ledger.md b/docs/plans/definition-first-projects/execution-ledger.md index 1ffb87a1..08f51ae8 100644 --- a/docs/plans/definition-first-projects/execution-ledger.md +++ b/docs/plans/definition-first-projects/execution-ledger.md @@ -193,3 +193,54 @@ Command for all Tuldok tests as before: 302 tests, 71 s. **Open:** the lab has no lock file for the GPU environment, so `cuda-torch` can be connected but not installed. Running a definition's `estimate` command moved to milestone 6. **Next:** milestone 6, build: runs from a commit, the launcher and queue, products, live progress, results published by the run. Its acceptance trains one tiny model on the GPU, which needs the owner's go-ahead. + +## 2026-11-12 — milestone 6, build + +**Owner decision:** spec, code and tests, and one tiny real end-to-end build on the GPU as the acceptance run. Spec: [spec-m6.md](spec-m6.md). No implementing agent used the GPU; the acceptance run was done by the orchestrating session. + +**Commits** (none pushed), Tuldok `feat/definition-first-projects`: spec `fe2dd56a` and `b9d32e9a`; snapshot `4191d46f`; launcher `e49635b9`, then its custodian `35fdafc6`; builds `f8367c17`; run commands and estimates `419d6ed2`; the example project `d3340b5f`. + +| Slice | Files | Result | +| --- | --- | --- | +| T11 launcher | `tuldok_project/launcher.py` | 37 tests | +| T12 snapshot | `tuldok_project/snapshot.py`, `code_paths` in `tuldok.json` | 30 tests | +| T13 builds | `tuldok_project/builds.py`, the states, `build`, `runs`, `products`, the `buildable` fixture | 30 tests | +| T14 run commands and estimates | `run`, `progress`, `cancel`, `stop`, `estimate`, estimates in `plan`, the "Building" contract section | 17 tests | +| T15 example | `examples/tiny-project/` | checker 0 errors; scripts smoke-tested on the CPU | + +Command for all Tuldok tests as before: 423 tests, about 2.5 minutes. + +**Design change found in review.** The first launcher made the calling process a child subreaper. An independent test (a command that double-forks a daemon and leaves a background child) showed everything was stopped, but one zombie per run was left in the caller, and the same mechanism could take the exit status of a caller's unrelated child. Each run now has its own custodian process (`python -m tuldok_project.launcher`), which is the subreaper, reaps everything it adopts and writes the outcome. Repeating the test, with the daemon also clearing its environment: nothing alive, no zombie in the caller, and the caller's unrelated child reported its true exit status. + +**Independent checks of the builds slice** (the `buildable` fixture in a scratch Git repository): first build, 4 runs; second build, nothing run; a committed settings change made the recipe and its benchmark out of date with the reason and rebuilt only those; an uncommitted change was refused without `--scratch`; with `code_paths` the snapshot held exactly the named files and a step whose script was not named failed; a failing step stopped the build; no process left carrying a run id. + +**Acceptance run, `examples/tiny-project`** (throwaway database, local home in a scratch directory, the owner's two existing interpreters connected): + +| Step | Result | +| --- | --- | +| `connect cpu`, `connect gpu` | both ready | +| `build benchmarks/held-out --yes` | exit 0 in 23.4 s: dataset 0.3 s, training 13.9 s on the GPU, benchmark 3.1 s and 1.7 s for its two subjects | +| progress read from another process while training ran | six observations, from update 1,300 to 6,000 of 6,000, loss falling from 0.0020 to 0.0006 | +| the training run's record | from the snapshot of commit `d3340b5f`, exit 0, 0 strays, outputs `model.pt` (349 KB) and `log.json` | +| `chart held-out-ranking` | `small-net-a` median error 0.0376, `predict-zero` 0.871, 400 cases each, from the results the benchmark runs published | +| `chart held-out-tradeoff`, `report` | drawn; the tradeoff drawing was viewed as a rendered image | +| second `build` | nothing run: everything built | +| an uncommitted change to the recipe's settings | the recipe and the benchmark show out of date with the reason; built again after the change was reverted | +| afterwards | no process carrying a run id; the GPU idle with no compute process of the run; the example unchanged in Git | + +**Accepted as implemented:** + +- A definition is also out of date when something it uses is out of date, so one build settles a change. +- A benchmark records its subject's recipe among the run's inputs, and rebuilds only the subjects that are not built. +- `running` takes precedence over every state; a current product over `cannot-rebuild` and `needs-work`. +- The snapshot is prepared before confirmation, so a dirty tree is refused without asking. +- An environment is checked once per build, and only when a step being built uses it. The project stays open during that check. +- `Outcome` has a `problem` text; a launcher that cannot start the command makes the step `failed`. +- Estimates: only `build` steps are measured; a benchmark's estimate command may not use `{subject}`; the disk limit is 100 MB; no GPU lock is taken; the throwaway directory is removed afterwards. +- `stop` refuses only while the run is `queued` or `running` and its builder is alive. + +**Not verified:** cancellation and the disk limit through `build` on a real long run; a real interrupted build beyond a hand check with `SIGINT`; behaviour with Git submodules (not included in snapshots); the GPU lock with two real GPU builds. + +**Known gaps:** leftover `.partial-*` snapshot directories from a crashed build are never removed; nothing is ever deleted from the local home (runs, old products, snapshots), so a `prune` command is needed before long use; the values file's `commit` is whatever the benchmark's command writes, since the command is not told its commit. + +**Next:** milestone 7, serving the new core from the Tuldok app with agent operations; then milestone 8, converting the lab for good and retiring the old project-files code, which needs the owner's two open decisions (where the product archive goes; which earlier models to drop) and sign-off of the capability check. From 1b633ffbbe619627ef1fad98cfa1e3d5009996d7 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 12 Nov 2026 04:28:33 -0700 Subject: [PATCH 027/131] docs(plan): specify milestone 7, the app and the agent interface One project folder per Tuldok process, every operation a POST with its contract selected, builds asked for through the interface as requests the owner approves, and what was built differently recorded in section 12. Co-Authored-By: Claude Fable 5.2 --- .../definition-first-projects/spec-m7.md | 258 ++++++++++++++++++ 1 file changed, 258 insertions(+) create mode 100644 docs/plans/definition-first-projects/spec-m7.md diff --git a/docs/plans/definition-first-projects/spec-m7.md b/docs/plans/definition-first-projects/spec-m7.md new file mode 100644 index 00000000..15e72d05 --- /dev/null +++ b/docs/plans/definition-first-projects/spec-m7.md @@ -0,0 +1,258 @@ +# Implementation spec: milestone 7, the app and the agent interface + +This continues the earlier specs in this folder. Section 1 of [spec-m1-m2.md](spec-m1-m2.md) (rules for implementers) applies, with the two exceptions in section 1 below. This is the first milestone that changes existing Tuldok files: `app.py`, `agent_api.py` and `mcp_stdio.py`, each by a small, additive block. + +**Done when:** Tuldok started with `--project-folder examples/tiny-project/project` serves the project; an agent holding only an agent credential reads the project, asks for the plan, requests a build of `benchmarks/held-out`, the owner approves that request, the agent watches the training's progress and reads the results and the chart, all through the agent interface; and the catalog and old project capability manifests are byte for byte what they were before this milestone. + +## 1. Decisions + +- **One folder per Tuldok process.** `python app.py --project-folder PATH` serves that folder and nothing else. It cannot be combined with `--project-root`, `--project-files-root`, `--project-runtime-source`, `--project-transfer-control` or `--project-transfer-root`. `--data` still names the catalog directory, which holds the credentials. +- **Every operation opens the project for a moment**, as the commands do (`builds.opened`), so files changed on disk are imported before the operation answers and the command line keeps working beside a running app. Nothing holds the project open between operations. +- **Every operation is `POST /api/project/` with a JSON object body**, where `` is the operation's name after `project.`. There are no path or query arguments, so a reference such as `recipes/small-net-a` needs no escaping. Every request must select its contract with the `Tuldok-Operation-Contract` header, as every operation added since the first agent release does. +- **A build asked for through the interface is a build request.** The owner's own request starts by itself. An agent's request waits until the owner approves it, and the approval covers exactly what was shown: section 4. This keeps the plan's rule that nothing runs without the owner's approval. `access.py` already refuses the `execute` scope to agents, so the request path is separate from it. +- **The app runs approved requests one at a time** in one worker thread, with `builds.execute`. A foreground `build` from the command line is unchanged and makes no request. +- **Exceptions to the import rule.** `tuldok_project/host.py` (new) is the one module of the package that imports the app's kept layers: `metadata`, `access` and `agent_api`. `agent_api.py` imports `tuldok_project.operations`, which imports only the standard library. No other module of the package imports from outside it, and nothing imports the old `project_*.py` modules. +- **Not in this milestone:** see section 9. +- **As built:** section 12 lists where the code differs from the sections below. Where they differ, section 12 is right. + +## 2. Operations + +Profile `project_folder`. Each row is one operation `project.`. **Who** is the rule for the caller: + +| Who | Rule | `access.require` call in the host | +| --- | --- | --- | +| inspect | any credential with `inspect` | `require('inspect', name)` | +| edit | any credential with `edit` | `require('edit', name)` | +| cancel | any credential with `cancel` | `require('cancel', name)` | +| request | the owner, or an agent whose credential includes `execute` | `require('inspect', name)`, then the scope list of `identity()` must contain `execute` | +| owner | the owner only | `require('approve-execution', name, owner_only=True)` | + +Arguments marked `?` are optional. A reference is text of 1 to 200 characters. A run or a build request is named by its id or by at least its first 6 characters. Unknown arguments are refused. + +| Name | Who | Arguments | Result (top-level keys) | +| --- | --- | --- | --- | +| `summary` | inspect | none | `project_id`, `name`, `folder`, `code_root`, `kinds`, `states` (`Project.summary()`), and `worker`: `running`, `elsewhere` or `stopped` (section 4) | +| `status` | inspect | none | the keys of `Project.status()` | +| `check` | inspect | none | `ok`, `errors`, `warnings` (counts), `problems` (the first 200, each `severity`, `path`, `pointer`, `message`). Reads the folder on disk with `check.check_folder`; does not open the project, so it answers when the folder has errors | +| `definitions` | inspect | `kind?` | `definitions` (`Project.definitions`) | +| `definition` | inspect | `reference` | the keys of `Project.definition` | +| `graph` | inspect | none | `nodes`, `edges` | +| `results_overview` | inspect | none | `benchmarks` (`Project.results_overview()`) | +| `results` | inspect | `benchmark`, `subject?`, `metric?`, `group?`, `offset?` (0), `limit?` (500, at most 2000) | `rows`, `total` | +| `values` | inspect | `benchmark`, `subject`, `metric?`, `offset?` (0), `limit?` (200, at most 1000) | `rows`, `total` | +| `chart` | inspect | `chart`, `svg?` (false), `theme?` (`light` or `dark`) | `data` (`charts.chart_data`), and `svg` (text) when asked | +| `report` | inspect | `theme?` | `html` | +| `plan` | inspect | `targets` (0 to 50 references), `every?` (false) | the keys of `plan.build_plan` | +| `estimates` | inspect | none | `estimates` (`builds.stored_estimates`) | +| `environments` | inspect | none | `environments` (`environments.listing`) | +| `environment` | inspect | `reference` | the keys of `environments.show` | +| `runs` | inspect | `reference?`, `limit?` (100, at most 500) | `runs`, newest first | +| `run` | inspect | `run` | the run's row, `product`, `builder_alive`. The row's `env` is replaced by `env_names`, the sorted names of its variables: values are never sent | +| `progress` | inspect | `run`, `stdout_offset?`, `stderr_offset?` | `run` (`builds.run_summary`), `event`, `stdout`, `stderr` (each `text`, `offset`, `size`, `skipped`, from `builds.read_log`), `ended`. Without an offset the last part of the log is read | +| `products` | inspect | `reference?` | `products` | +| `build_requests` | inspect | `state?`, `limit?` (100, at most 500) | `requests`, newest first, without their `covers` | +| `build_request` | inspect | `request` | the request (section 4) with `covers`, and `runs`: the runs of its plan | +| `activity` | inspect | `offset?` (0), `limit?` (100, at most 500) | `items`, newest first, `total` | +| `set_definition` | edit | `reference`, `text` | as `definition` | +| `remove_definition` | edit | `reference` | `removed` (the reference) | +| `save` | edit | none | the keys `Project.save()` returns | +| `resolve_conflict` | edit | `choice` (`keep` or `discard`) | as `summary`. Opens the project with that `on_conflict` choice | +| `import_values` | edit | `text` | `benchmark`, `subject`, `values` (count). A request is at most 1 MiB, so larger values files are imported by the command line or published by the run that made them | +| `check_environment` | edit | `reference` | as `environment` | +| `connect_environment` | owner | `reference`, `interpreter` | as `environment` | +| `disconnect_environment` | owner | `reference` | `disconnected` (the reference) | +| `request_build` | request | `targets` (0 to 50 references), `every?` (false), `scratch?` (false) | the request | +| `approve_build` | owner | `request` | the request | +| `decline_build` | owner | `request`, `reason?` (at most 400 characters) | the request | +| `cancel_build` | cancel | `request` | the request | +| `cancel_run` | cancel | `run` | the keys of `builds.cancel` | +| `stop_run` | cancel | `run` | the keys of `builds.stop` | + +**Results are plain JSON.** Times are ISO 8601 text in UTC. A number that is not finite is `null`. A result is an object; the keys listed are always present and others may be. + +**Refusals.** A `ProjectError` becomes `{"error", "code"}` plus, when not empty, `problems` (the first 50, as in `check`), `references` and `files`. The HTTP status is 404 for `not-found`, 400 for `invalid`, 403 for `forbidden`, and 409 for every other code. Codes added by this milestone: `forbidden` (the service's own check of the actor), `nothing-to-build`, `too-many`, `not-awaiting`, `stale`, `not-cancellable`, `unavailable`. + +## 3. The service + +`tuldok_project/operations.py` holds the table above as data: a tuple `OPERATIONS` of frozen `Operation(name, summary, who, mutation, arguments, result)` records, where `arguments` is a JSON Schema object (closed: `additionalProperties` false) and `result` is the tuple of required result keys. `summary` is one plain sentence, shown to agents as the tool's description. `by_name(name)` returns one. `error_status(code)` gives the HTTP status. It imports only the standard library. + +`tuldok_project/service.py`: + +```python +class Service: + def __init__(self, folder, *, dsn=None) # opens the folder once and closes it; raises ProjectError + def start(self) # starts the worker of section 4 + def close(self) # section 4; safe to call twice + def call(self, name, arguments, actor) # returns the result object or raises ProjectError +``` + +- `actor` is `{"actor_id", "kind", "label", "scopes"}`; `kind` is `owner` or `agent`. +- `call` checks, in this order: the operation exists (`not-found`); the actor satisfies its **who** rule from `kind` and `scopes` alone (`forbidden`); the arguments match its schema (`invalid`, with one problem per schema error). It then runs the operation and makes the result JSON-plain. +- Requests are answered one at a time: `call` holds one lock of the service while the project is open, so two requests never wait on each other through the database lock. The worker does not take that lock. +- Every mutating operation writes one row of `activity` (section 5), whether it was done or refused after the actor check. +- The service knows nothing of HTTP, `access` or `agent_api`. + +## 4. Build requests + +New module `tuldok_project/build_requests.py`, and one table in each project schema, created like the others: + +```sql +CREATE TABLE build_requests ( + id text PRIMARY KEY, + state text NOT NULL, + targets jsonb NOT NULL, every boolean NOT NULL, scratch boolean NOT NULL, + covers jsonb NOT NULL, covers_sha256 text NOT NULL, + requested_at timestamptz NOT NULL, requested_by jsonb NOT NULL, + decided_at timestamptz, decided_by jsonb, + started_at timestamptz, finished_at timestamptz, + owner_pid integer, owner_boot text, + plan_id text, cancel_requested boolean NOT NULL DEFAULT false, + result jsonb, problem text); +``` + +`requested_by` and `decided_by` are `{"actor_id", "kind", "label"}`. A request as returned has every column except `owner_pid`, `owner_boot` and `covers_sha256` kept as they are, with `covers` left out of lists. + +**States:** `awaiting-approval`, `queued`, `running`, `succeeded`, `failed`, `cancelled`, `declined`, `expired`. + +**What a request covers.** `covers` is computed from the plan (`plan.build_plan`) and the code root: + +```json +{"targets": [...], "every": false, "scratch": false, + "commit": "", + "steps": [{"reference": "...", "subjects": [...]}], + "definitions": {"": ""}} +``` + +`steps` are the plan's steps whose action is `build`, in plan order, with the benchmark subjects that would run (an empty list for other kinds). `definitions` has every reference that appears in the plan's steps, whatever its action. `covers_sha256` is the SHA-256 of `covers` as JSON with sorted keys and no spaces. + +**Requesting.** The plan is made. A plan with blocked targets is refused (`blocked`, as `execute` does), and a plan with nothing to build is refused (`nothing-to-build`). At most 20 requests may be awaiting approval or queued (`too-many`). The owner's request is stored `queued` with `decided_by` the owner. An agent's is stored `awaiting-approval`. + +**Approving.** Only an `awaiting-approval` request (`not-awaiting`). `covers` is computed again now; if its SHA-256 differs, the request becomes `declined` with a problem naming what changed (the commit, or up to five references), and the call is refused with `stale`. Otherwise the request becomes `queued`. **Declining** makes it `declined` with the reason as its problem. + +**The worker.** One thread per service, started by `start()`. It first takes `//build-requests.lock` with a non-blocking `flock`; if another process holds it, this service runs no requests and `summary` reports `worker: "elsewhere"`. Then, about once a second, with the project open only for the database steps: + +1. Mark as `failed` every `running` request whose owner process is gone (`builds.boot_id`, the pid), with the problem "Tuldok stopped while this was running." +2. Take the oldest `queued` request. If it was decided more than 3600 seconds ago it becomes `expired`. If its `covers`, computed again, has another SHA-256, it becomes `failed` with the problem naming what changed. Otherwise it becomes `running`, with this process recorded. +3. Run `builds.execute(folder, plan, confirm=, scratch=..., dsn=..., expect=covers, stop=...)` with the project closed. +4. Record the outcome: `succeeded` when `ok`; `cancelled` when cancel was requested; otherwise `failed` with the problem of the step that did not succeed, or the message of the `ProjectError` that `execute` raised. `plan_id` and `result` (the steps as `execute` returned them) are stored. + +An exception in the worker other than `ProjectError` marks the request `failed` with its type and message, and the worker goes on. + +**Two additions to `builds.execute`**, both keyword arguments that default to `None` and change nothing when absent: + +- `expect`: a `covers` object. After the code is prepared, a commit that is not `expect["commit"]` (when that is not null) refuses the build with `stale` before anything runs. Before each step is run, every definition the build reads to run it (the step's own, its environment, the step definition it runs with, a benchmark subject's recipe) must have the text whose SHA-256 is in `expect["definitions"]`; otherwise the build stops there with `ProjectError` `stale`, naming the reference. Steps already finished stay as they are. +- `stop`: a function called before each step; when it returns true the build ends there with `ok` false. + +**Cancelling a request.** `awaiting-approval` or `queued` becomes `cancelled`. `running` gets `cancel_requested` set and each active run of its plan is asked to stop with `builds.cancel`; the worker's `stop` function reads the flag. Any other state is refused (`not-cancellable`). + +**Closing.** `Service.close()` requests the cancellation of a running request, waits for the worker up to 30 seconds, and returns. The custodian of a run already stops its run when the process that started it dies. + +`summary`'s `worker` is `running` while this service's worker holds the lock, `elsewhere` when another process does, and `stopped` before `start()` and after `close()`. + +## 5. Activity + +```sql +CREATE TABLE activity ( + id bigserial PRIMARY KEY, at timestamptz NOT NULL, + actor jsonb NOT NULL, operation text NOT NULL, + target text NOT NULL, outcome text NOT NULL, detail text NOT NULL); +``` + +One row for each mutating operation that passed the actor check: `target` is the reference, run or request it named (or empty), `outcome` is `done` or the refusal's code, `detail` is empty or the first 400 characters of the refusal. `approve` and `decline` from the command line (section 8) write a row with the actor `{"actor_id": null, "kind": "owner", "label": "command line"}`. Reads are not recorded. + +## 6. The app + +**`tuldok_project/host.py`:** + +```python +class ProjectHost: + project_folder_mode = True + def __init__(self, data_path, folder, *, dsn=None) # Metadata, Access, Service; starts the worker + def capabilities(self) # agent_api.capabilities(catalog id, profile='project_folder') + def dispatch(self, name, arguments) # -> (status, result) + def close(self) +``` + +It has `db`, `lock` and `access` as `Dataset` and the old project mode have, because `app.py`'s handler uses them for sign-in and credentials. `dispatch` makes the `access.require` call of section 2 inside the caller's bound credential, builds `actor` from `access.identity()`, calls the service, and turns a `ProjectError` into `(status, body)` as section 2 says. Access errors are not caught: `app.py` already answers them. + +**`app.py`,** the smallest change that does this, with no restructuring of what is there: + +| Request | Folder mode | Other modes | +| --- | --- | --- | +| start-up | `--project-folder PATH` builds a `ProjectHost`; a folder that does not open ends start-up with the message and its first problems | unchanged | +| `POST /api/project/` | the body is read as strict JSON with the agent request limit; `agent_api.require_selection` for `project.`; reply with `dispatch`'s status and result | 409 `unavailable`, "Start Tuldok with --project-folder to use this." | +| `GET /api/agent/capabilities` | `host.capabilities()` | unchanged | +| `GET /api/workspace/context` | `{"version": 1, "mode": "real", "dataset_id": ..., "project_folder": true}` | unchanged | +| `/api/access/...` | unchanged | unchanged | +| any other `/api/` route | 409 `unavailable` | unchanged | +| `GET /`, `/workspaces`, `/workbench` | the page below | unchanged | + +**The page.** `static/project-folder.html`, `static/project-folder.js` and `static/project-folder.css`: the existing sign-in bar (`auth.js`, `auth.css`), the project's name and folder, a Reload button, and the report (`project.report`, in the theme the browser prefers) shown in an ` + + + diff --git a/static/project-folder.js b/static/project-folder.js new file mode 100644 index 00000000..0130f7ec --- /dev/null +++ b/static/project-folder.js @@ -0,0 +1,68 @@ +'use strict'; +// A served project folder: its name and folder, and its report. Contract +// versions and hashes are read from /api/agent/capabilities, never pinned here. +(() => { + const $ = id => document.getElementById(id); + const dark = window.matchMedia('(prefers-color-scheme: dark)'); + let contracts = null, loading = false; + + async function json(response) { + const value = await response.json(); + if (!response.ok) throw Error(value.error || 'The request was refused.'); + return value; + } + + async function selection(name) { + if (!contracts) { + const manifest = await json(await window.TuldokAuth.fetch('/api/agent/capabilities', {cache: 'no-store'})); + contracts = new Map(manifest.operations.map(operation => { + const newest = operation.contracts.reduce((a, b) => (b.version > a.version ? b : a)); + return [operation.id, operation.id + '/' + newest.version + '/' + newest.sha256]; + })); + } + if (!contracts.has(name)) throw Error('This Tuldok does not offer ' + name + '.'); + return contracts.get(name); + } + + async function call(name, body) { + const response = await window.TuldokAuth.fetch('/api/project/' + name, { + method: 'POST', cache: 'no-store', + headers: {'Content-Type': 'application/json', 'Tuldok-Operation-Contract': await selection('project.' + name)}, + body: JSON.stringify(body)}); + return json(response); + } + + async function load() { + if (loading) return; + loading = true; + $('project-reload').disabled = true; + $('project-error').hidden = true; + $('project-status').textContent = 'Reading the project…'; + try { + const summary = await call('summary', {}); + $('project-name').textContent = summary.name; + document.title = summary.name + ' · Tuldok'; + $('project-folder').textContent = summary.folder; + const report = await call('report', {theme: dark.matches ? 'dark' : 'light'}); + $('project-report').srcdoc = report.html; + $('project-status').textContent = 'Read at ' + new Date().toLocaleTimeString() + '.'; + } catch (error) { + contracts = null; + $('project-status').textContent = ''; + $('project-error').textContent = error.message; + $('project-error').hidden = false; + } finally { + loading = false; + $('project-reload').disabled = false; + } + } + + function start() { + $('project-reload').addEventListener('click', load); + dark.addEventListener('change', load); + window.addEventListener('tuldok-session', load); + load(); + } + if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', start, {once: true}); + else start(); +})(); diff --git a/tests/test_tuldok_project_http.py b/tests/test_tuldok_project_http.py new file mode 100644 index 00000000..e91251cb --- /dev/null +++ b/tests/test_tuldok_project_http.py @@ -0,0 +1,374 @@ +"""A project folder served by the app (spec-m7.md, sections 6 and 7): contracts, the HTTP routes, the clients, the page. + +The contract tests need no database. Everything else needs one and runs only +when TULDOK_DATABASE_URL names a disposable cluster: each test starts from +test_tuldok_project_builds.BuildCase (a Git-committed copy of the buildable +fixture with its environment connected, dropped afterwards), opens a catalog +in the same temporary directory with a ProjectHost on that copy, and serves it +with app.make_handler on port 0. The owner signs in as the app's tests do +(auth_helpers.ExplicitOwnerFixture) and issues agent credentials. Builds run +the fixture's stand-in scripts; no GPU is used. +""" +import hashlib +from http.server import ThreadingHTTPServer +import json +import os +from pathlib import Path +import subprocess +import sys +import tempfile +import threading +import time +import unittest +from unittest import mock +from urllib.error import HTTPError +from urllib.request import Request, urlopen + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) +sys.path.insert(0, str(Path(__file__).resolve().parent)) + +import agent_api # noqa: E402 +from tuldok_project import operations # noqa: E402 +import test_tuldok_project_builds as builds_base # noqa: E402 + +REPOSITORY = Path(__file__).resolve().parents[1] +PUBLISHED = { + 'catalog': (115, 'b31b7a2b794020622e64d593cd29455226a4170451f15201e28cad5d9edd18f1'), + 'project': (152, '58e4270277a38b58869ca4c6ae4bccffe74387b2ee70d3c178b30821f8d27320'), +} +DISCOVERY = '9c02284ed750bce31c53100d4657deaf40b519c9d17d5e3165b6b6342930b660' +PROJECT_NAMES = {'project.' + operation.name for operation in operations.OPERATIONS} +AGENT_SCOPES = ['inspect', 'edit', 'execute', 'cancel'] + + +def digest(value): + return hashlib.sha256(agent_api.encoded(value)).hexdigest() + + +class Contracts(unittest.TestCase): + """What is published: unchanged for catalogs and old projects, the table for project folders.""" + + def test_the_published_digests_are_unchanged(self): + for profile, (count, expected) in PUBLISHED.items(): + with self.subTest(profile): + value = agent_api.capabilities('b' * 32, profile=profile) + self.assertEqual(len(value['operations']), count) + self.assertEqual(digest(value), expected) + self.assertFalse([item['id'] for item in value['operations'] if item['id'].startswith('project.')]) + self.assertEqual(digest(agent_api.discovery()), DISCOVERY) + + def test_the_project_folder_profile_is_the_table(self): + value = agent_api.capabilities('b' * 32, profile='project_folder') + self.assertEqual(agent_api.negotiate(value, 'b' * 32).keys(), PROJECT_NAMES | {'context.get', 'identity.get'}) + self.assertEqual({item['id'] for item in value['operations']}, PROJECT_NAMES | {'context.get', 'identity.get'}) + self.assertEqual({item['availability'] for item in value['operations']}, {'available'}) + published = {item['id']: item['contracts'] for item in value['operations']} + for operation in operations.OPERATIONS: + with self.subTest(operation.name): + [contract] = published['project.' + operation.name] + self.assertEqual(contract['input_schema'], operation.arguments) + self.assertEqual(contract['authority'], 'owner' if operation.who == 'owner' else 'agent') + self.assertEqual(contract['effects'], 'mutation' if operation.mutation else 'read') + self.assertEqual(contract['retry'], 'never' if operation.mutation else 'read') + success, refusal = contract['output_schema']['oneOf'] + self.assertEqual(success['properties']['result']['required'], list(operation.result)) + self.assertEqual(refusal['properties']['result']['required'], ['error']) + published_operation = agent_api.operation('project.' + operation.name) + self.assertEqual((published_operation['method'], published_operation['path']), + ('POST', '/api/project/' + operation.name)) + self.assertEqual(published_operation['description'], operation.summary) + self.assertEqual(agent_api.operation(published_operation['mcp_name'])['operation_id'], + 'project.' + operation.name) + + def test_a_result_is_checked_against_its_keys(self): + agent_api.validate_output('project.summary', {'status': 200, 'result': { + key: None for key in operations.by_name('summary').result} | {'more': 1}}) + with self.assertRaises(agent_api.AgentAPIError): + agent_api.validate_output('project.summary', {'status': 200, 'result': {'name': 'x'}}) + agent_api.validate_output('project.summary', {'status': 409, 'result': { + 'error': 'No.', 'code': 'not-awaiting', 'problems': [{'message': 'x'}], 'references': ['a/b'], 'files': []}}) + with self.assertRaises(agent_api.AgentAPIError): + agent_api.validate_output('project.summary', {'status': 409, 'result': {'error': 'No.', 'detail': 'x'}}) + + +class Served(builds_base.BuildCase): + """BuildCase with a ProjectHost on the copy, served on port 0, an owner and an agent credential.""" + + def setUp(self): + super().setUp() + from app import make_handler + from auth_helpers import ExplicitOwnerFixture + from tuldok_project.host import ProjectHost + self.host = ProjectHost(self.temporary / 'catalog', self.folder) + self.addCleanup(self.host.close) + self.catalog_id = self.host.db.dataset_id + self.owner = ExplicitOwnerFixture.bootstrap(self.host) + with self.owner.bound(self.host): + self.agent = self.host.access.issue({'label': 'Project agent', 'scopes': AGENT_SCOPES}) + self.reader = self.host.access.issue({'label': 'Reader', 'scopes': ['inspect']}) + self.server = ThreadingHTTPServer(('127.0.0.1', 0), make_handler(self.host)) + thread = threading.Thread(target=self.server.serve_forever, daemon=True) + thread.start() + self.addCleanup(thread.join, 5) + self.addCleanup(self.server.server_close) + self.addCleanup(self.server.shutdown) + self.root = f'http://127.0.0.1:{self.server.server_port}' + + def http(self, path, body=None, token=None, *, contract=None, raw=False): + token = self.agent['token'] if token is None else token + headers = {'Authorization': 'Bearer ' + token} + if body is not None: + headers['Content-Type'] = 'application/json' + if contract is not None: + headers[agent_api.CONTRACT_HEADER] = contract + request = Request(self.root + path, data=None if body is None else json.dumps(body).encode(), headers=headers) + try: + response = urlopen(request, timeout=30) + except HTTPError as error: + response = error + with response: + data = response.read() + if raw: + return response.status, response.headers.get('Content-Type'), data + return response.status, json.loads(data) + + def call(self, name, arguments=None, token=None): + """POST /api/project/ with its contract selected; (status, body).""" + return self.http('/api/project/' + name, arguments or {}, token, + contract=agent_api.selected_header('project.' + name)) + + def ok(self, name, arguments=None, token=None): + status, value = self.call(name, arguments, token) + self.assertEqual(status, 200, value) + return value + + def activity(self): + return self.ok('activity', {'limit': 500})['items'] + + +class Routes(Served): + + def test_a_request_without_its_contract_is_refused(self): + self.assertEqual(self.http('/api/project/summary', {})[0], 409) + status, value = self.http('/api/project/summary', {}) + self.assertEqual(value['code'], 'contract_mismatch') + status, value = self.call('summary') + self.assertEqual(status, 200, value) + self.assertEqual(value['folder'], os.path.realpath(self.folder)) + + def test_an_unknown_operation(self): + status, value = self.http('/api/project/nothing', {}, contract='project.nothing/1/' + 'a' * 64) + self.assertEqual((status, value['code']), (409, 'contract_mismatch')) + status, value = self.http('/api/project/nothing', {}, contract=agent_api.selected_header('project.summary')) + self.assertEqual((status, value['code']), (409, 'contract_mismatch')) + status, value = self.http('/api/project/summary', {}, contract=agent_api.selected_header('project.status')) + self.assertEqual((status, value['code']), (409, 'contract_mismatch')) + + def test_an_agent_calling_an_owner_operation_is_refused_and_nothing_is_done(self): + status, value = self.call('disconnect_environment', {'reference': 'environments/test-python'}) + self.assertEqual((status, value['code']), (403, 'forbidden')) + environment = self.ok('environment', {'reference': 'environments/test-python'}) + self.assertIsNotNone(environment['interpreter']) + self.assertEqual(self.activity(), []) + status, value = self.call('request_build', {'targets': ['datasets/numbers']}, self.reader['token']) + self.assertEqual((status, value['code']), (403, 'forbidden')) + status, value = self.call('set_definition', {'reference': 'datasets/numbers', 'text': '{}'}, + self.reader['token']) + self.assertEqual((status, value['code']), (403, 'forbidden')) + self.assertEqual(self.activity(), []) + done = self.ok('disconnect_environment', {'reference': 'environments/test-python'}, self.owner.token) + self.assertEqual(done['disconnected'], 'environments/test-python') + + def test_invalid_arguments(self): + status, value = self.call('definitions', {'kind': 'nothing', 'more': 1}) + self.assertEqual((status, value['code']), (400, 'invalid'), value) + self.assertEqual(len(value['problems']), 2) + self.assertEqual({problem['severity'] for problem in value['problems']}, {'error'}) + status, value = self.http('/api/project/summary', None, contract=agent_api.selected_header('project.summary')) + self.assertEqual(status, 409) + request = Request(self.root + '/api/project/summary', data=b'{"a":1,"a":2}', headers={ + 'Authorization': 'Bearer ' + self.agent['token'], 'Content-Type': 'application/json', + agent_api.CONTRACT_HEADER: agent_api.selected_header('project.summary')}) + with self.assertRaises(HTTPError) as caught: + urlopen(request, timeout=30) + self.assertEqual(caught.exception.code, 400) + self.assertEqual(json.loads(caught.exception.read())['code'], 'invalid') + + def test_a_refusal_arrives_with_its_code_status_and_problems(self): + status, value = self.call('definition', {'reference': 'recipes/nothing'}) + self.assertEqual((status, value['code']), (404, 'not-found'), value) + status, value = self.call('set_definition', {'reference': 'datasets/numbers', 'text': '{"format": 1}'}) + self.assertEqual((status, value['code']), (400, 'invalid'), value) + self.assertTrue(value['problems']) + self.assertEqual(set(value['problems'][0]), {'severity', 'path', 'pointer', 'message'}) + self.assertEqual(self.activity()[0]['outcome'], 'invalid') + status, value = self.call('approve_build', {'request': 'abcdef'}, self.owner.token) + self.assertEqual(status, operations.error_status(value['code']), value) + + def test_a_result_that_breaks_its_keys_is_not_sent_as_a_success(self): + with mock.patch.object(self.host.service, 'call', return_value={'name': 'Only a name'}): + status, value = self.call('summary') + self.assertEqual((status, value['code']), (502, 'contract_output')) + self.assertNotIn('name', value) + + def test_other_routes_in_folder_mode(self): + for path, body in (('/api/samples', None), ('/api/workspace/runs', None), ('/api/workspace/projects', None), + ('/api/workbench/import', {'text': 'x', 'groups': ['a']}), ('/api/export', None)): + with self.subTest(path): + status, value = self.http(path, body) + self.assertEqual((status, value['code']), (409, 'unavailable'), value) + status, value = self.http('/api/access/session') + self.assertEqual((status, value['kind'], value['label']), (200, 'agent', 'Project agent')) + status, value = self.http('/api/agent/capabilities') + self.assertEqual((status, value), (200, agent_api.capabilities(self.catalog_id, profile='project_folder'))) + status, value = self.http('/api/agent/operations') + self.assertEqual((status, value), (200, agent_api.discovery())) + status, value = self.http('/api/workspace/context') + self.assertEqual((status, value), (200, {'version': 1, 'mode': 'real', 'dataset_id': self.catalog_id, + 'project_folder': True})) + status, value = self.http('/api/access/credentials', {'label': 'Another', 'scopes': ['inspect']}, + self.owner.token) + self.assertEqual(status, 201, value) + + def test_the_page(self): + for path in ('/', '/workspaces', '/workbench'): + status, kind, data = self.http(path, raw=True) + self.assertEqual((status, kind), (200, 'text/html; charset=utf-8')) + self.assertIn(b'/project-folder.js', data) + self.assertIn(b'/project-folder.css', data) + self.assertIn(b'/auth.js', data) + for path, expected in (('/project-folder.js', 'text/javascript'), ('/project-folder.css', 'text/css'), + ('/auth.js', 'text/javascript')): + status, kind, data = self.http(path, raw=True) + self.assertEqual((status, kind), (200, expected + '; charset=utf-8')) + self.assertTrue(data) + script = (REPOSITORY / 'static' / 'project-folder.js').read_text(encoding='utf-8') + self.assertIn('/api/agent/capabilities', script) + self.assertNotRegex(script, '[a-f0-9]{64}') + for name in ('project-folder.html', 'project-folder.js', 'project-folder.css'): + self.assertNotRegex((REPOSITORY / 'static' / name).read_text(encoding='utf-8'), r'https?://') + self.assertIn('prefers-color-scheme:dark', (REPOSITORY / 'static' / 'project-folder.css').read_text()) + + def test_a_folder_that_does_not_open_ends_start_up(self): + (self.folder / 'datasets' / 'numbers.json').write_text('{"format": ', encoding='utf-8') + command = [sys.executable, str(REPOSITORY / 'app.py'), '--data', str(self.temporary / 'catalog-2'), + '--port', '0', '--project-folder', str(self.folder)] + finished = subprocess.run(command, capture_output=True, text=True, timeout=120, cwd=REPOSITORY) + self.assertEqual(finished.returncode, 2, finished.stderr) + self.assertIn('datasets/numbers.json', finished.stderr) + finished = subprocess.run(command + ['--project-root', 'a=/tmp'], capture_output=True, text=True, + timeout=120, cwd=REPOSITORY) + self.assertEqual(finished.returncode, 2, finished.stderr) + self.assertIn('--project-folder', finished.stderr) + + +class Clients(Served): + + def test_an_agent_client_reads_and_edits(self): + client = agent_api.AgentClient(self.root, self.agent['token'], self.catalog_id) + started = client.bootstrap() + self.assertEqual(set(started['operations']), PROJECT_NAMES | {'context.get', 'identity.get'}) + summary = client.call('project.summary', {}) + self.assertEqual(summary['status'], 200, summary) + self.assertEqual(summary['result']['project_id'], self.project_id) + recipes = client.call('project_definitions', {'kind': 'recipe'})['result']['definitions'] + self.assertEqual({row['reference'] for row in recipes}, {'recipes/fit-a', 'recipes/fit-b'}) + planned = client.call('project.plan', {'targets': ['recipes/fit-a']})['result'] + self.assertIn('recipes/fit-a', [step['reference'] for step in planned['steps']]) + definition = client.call('project.definition', {'reference': 'datasets/numbers'})['result'] + document = json.loads(definition['text']) + document['title'] = 'A few numbers, edited by an agent' + edited = client.call('project.set_definition', {'reference': 'datasets/numbers', + 'text': json.dumps(document, indent=2) + '\n'}) + self.assertEqual(edited['status'], 200, edited) + self.assertEqual(edited['result']['title'], 'A few numbers, edited by an agent') + self.assertTrue(edited['result']['unsaved']) + [row] = self.activity() + self.assertEqual((row['operation'], row['outcome'], row['actor']['kind']), ('set_definition', 'done', 'agent')) + refused = client.call('project.definition', {'reference': 'recipes/nothing'}) + self.assertEqual((refused['status'], refused['result']['code']), (404, 'not-found')) + refused = client.call('project.approve_build', {'request': 'abcdef'}) + self.assertEqual((refused['status'], refused['result']['code']), (403, 'forbidden')) + with self.assertRaises(agent_api.AgentAPIError): + client.call('project.definitions', {'kind': 'nothing'}) # refused before anything is sent + + def test_the_owner_client(self): + client = agent_api.ProjectFolderOwnerClient(self.root, self.owner.token, self.catalog_id) + started = client.bootstrap() + self.assertEqual(set(started['operations']), PROJECT_NAMES) + self.assertEqual(client.call('project.summary', {})['status'], 200) + self.assertEqual(client.call('project_environments', {})['status'], 200) + with self.assertRaises(agent_api.AgentAPIError) as caught: + client.call('context.get', {}) + self.assertEqual(caught.exception.code, 'operation_unsupported') + with self.assertRaises(agent_api.AgentAPIError) as caught: + agent_api.ProjectFolderOwnerClient(self.root, self.agent['token'], self.catalog_id).bootstrap() + self.assertEqual(caught.exception.code, 'unauthenticated') + + +class Requests(Served): + + def test_an_agent_requests_a_build_and_the_owner_approves_it(self): + requested = self.ok('request_build', {'targets': ['datasets/numbers']}) + self.assertEqual(requested['state'], 'awaiting-approval') + self.assertEqual(requested['requested_by']['kind'], 'agent') + status, value = self.call('approve_build', {'request': requested['id']}) + self.assertEqual((status, value['code']), (403, 'forbidden')) + approved = self.ok('approve_build', {'request': requested['id']}, self.owner.token) + self.assertEqual(approved['state'], 'queued') + deadline = time.monotonic() + 120 + while True: + shown = self.ok('build_request', {'request': requested['id']}) + if shown['state'] not in ('queued', 'running') or time.monotonic() > deadline: + break + time.sleep(0.3) + self.assertEqual(shown['state'], 'succeeded', shown) + self.assertEqual([row['id'] for row in self.ok('build_requests')['requests']], [requested['id']]) + self.assertTrue(shown['runs']) + run = self.ok('run', {'run': shown['runs'][0]['id']}) + self.assertEqual(run['state'], 'succeeded') + self.assertIn('BUILDABLE_LABEL', run['env_names']) + progress = self.ok('progress', {'run': run['id']}) + self.assertTrue(progress['ended']) + self.assertEqual(progress['run']['id'], run['id']) + status, value = self.call('request_build', {'targets': ['datasets/numbers']}) + self.assertEqual((status, value['code']), (409, 'nothing-to-build'), value) + + +@unittest.skipUnless(builds_base.DATABASE, 'TULDOK_DATABASE_URL is not set; database tests need a disposable cluster.') +class CatalogMode(unittest.TestCase): + + def test_project_operations_are_unavailable(self): + from app import Dataset, make_handler + from auth_helpers import ExplicitOwnerFixture + with tempfile.TemporaryDirectory() as directory: + dataset = Dataset(Path(directory) / 'catalog') + try: + owner = ExplicitOwnerFixture.bootstrap(dataset) + server = ThreadingHTTPServer(('127.0.0.1', 0), make_handler(dataset)) + thread = threading.Thread(target=server.serve_forever, daemon=True) + thread.start() + try: + request = Request(f'http://127.0.0.1:{server.server_port}/api/project/summary', data=b'{}', headers={ + 'Authorization': 'Bearer ' + owner.token, 'Content-Type': 'application/json', + agent_api.CONTRACT_HEADER: agent_api.selected_header('project.summary')}) + with self.assertRaises(HTTPError) as caught: + urlopen(request, timeout=30) + self.assertEqual(caught.exception.code, 409) + self.assertEqual(json.loads(caught.exception.read()), + {'error': 'Start Tuldok with --project-folder to use this.', 'code': 'unavailable'}) + request = Request(f'http://127.0.0.1:{server.server_port}/api/agent/capabilities', + headers={'Authorization': 'Bearer ' + owner.token}) + with urlopen(request, timeout=30) as response: + listed = json.loads(response.read()) + self.assertFalse([item for item in listed['operations'] if item['id'].startswith('project.')]) + finally: + server.shutdown() + server.server_close() + thread.join(5) + finally: + dataset.close() + + +if __name__ == '__main__': + unittest.main() diff --git a/tuldok_project/host.py b/tuldok_project/host.py new file mode 100644 index 00000000..187d8be3 --- /dev/null +++ b/tuldok_project/host.py @@ -0,0 +1,90 @@ +"""The app's side of a served project folder: credentials, the caller's rule, and refusals as HTTP answers. + +Owns section 6 of docs/plans/definition-first-projects/spec-m7.md, apart from +the routes in app.py. A ProjectHost holds the catalog's Metadata and Access +(the credentials the app signs in with, as Dataset does) and one Service for +the folder. dispatch checks the caller's who rule with access.require inside +the credential app.py has bound, passes the caller's identity to the service as +its actor, and turns a ProjectError into a status and a refusal body. This is +the one module of the package that imports the app's kept layers (metadata, +access, agent_api); access errors are left to app.py, which answers them. +""" +from pathlib import Path + +import agent_api +from access import Access, AccessError +from metadata import Metadata + +from . import operations, store +from .service import Service + +REFUSAL_PROBLEMS = 50 +MESSAGE_CHARACTERS = 1000 + + +def refusal(error): + """A ProjectError as (status, body): error and code, and problems, references and files when not empty.""" + body = {'error': (str(error) or error.code)[:MESSAGE_CHARACTERS], 'code': error.code} + if error.problems: + body['problems'] = [problem if isinstance(problem, dict) else problem.as_dict() + for problem in error.problems[:REFUSAL_PROBLEMS]] + if error.references: + body['references'] = [str(reference) for reference in error.references] + if error.files: + body['files'] = [str(name) for name in error.files] + return operations.error_status(error.code), body + + +class ProjectHost: + """One project folder served by app.py; see the module docstring.""" + project_folder_mode = True + + def __init__(self, data_path, folder, *, dsn=None): + """Open the catalog of data_path and the folder, and start the build worker; raises ProjectError.""" + self.path = Path(data_path).resolve() + self.db = Metadata(self.path, dsn=dsn) + self.lock = self.db.lock + self.access = Access(self.db, self.path) + try: + self.service = Service(folder, dsn=dsn) + self.service.start() + except BaseException: + self.db.close() + raise + + @property + def folder(self): + return self.service.folder + + def capabilities(self): + return agent_api.capabilities(self.db.dataset_id, profile='project_folder') + + def dispatch(self, name, arguments): + """Run project. for the bound credential; return (status, result or refusal body).""" + operation = operations.by_name(name) + if operation is not None: + self._require(operation.who, 'project.' + name) + identity = self.access.identity() + actor = {key: identity[key] for key in ('actor_id', 'kind', 'label', 'scopes')} + try: + return 200, self.service.call(name, arguments, actor) + except store.ProjectError as error: + return refusal(error) + + def _require(self, who, action): + if who == 'owner': + self.access.require('approve-execution', action, owner_only=True) + elif who == 'request': + self.access.require('inspect', action) + if 'execute' not in self.access.identity()['scopes']: + error = AccessError('Requesting a build needs a credential with the execute scope.') + self.access.denial(error, action) + raise error + else: + self.access.require(who, action) + + def close(self): + try: + self.service.close() + finally: + self.db.close() From dc05e53502f2ae3c94718800693cbce2b4e6941d Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 12 Nov 2026 04:34:46 -0700 Subject: [PATCH 030/131] docs(plan): record milestone 7 in the ledger Co-Authored-By: Claude Fable 5.2 --- .../execution-ledger.md | 57 +++++++++++++++++++ 1 file changed, 57 insertions(+) diff --git a/docs/plans/definition-first-projects/execution-ledger.md b/docs/plans/definition-first-projects/execution-ledger.md index 08f51ae8..5dce90c3 100644 --- a/docs/plans/definition-first-projects/execution-ledger.md +++ b/docs/plans/definition-first-projects/execution-ledger.md @@ -244,3 +244,60 @@ Command for all Tuldok tests as before: 423 tests, about 2.5 minutes. **Known gaps:** leftover `.partial-*` snapshot directories from a crashed build are never removed; nothing is ever deleted from the local home (runs, old products, snapshots), so a `prune` command is needed before long use; the values file's `commit` is whatever the benchmark's command writes, since the command is not told its commit. **Next:** milestone 7, serving the new core from the Tuldok app with agent operations; then milestone 8, converting the lab for good and retiring the old project-files code, which needs the owner's two open decisions (where the product archive goes; which earlier models to drop) and sign-off of the capability check. + +## 2026-11-12 — milestone 7, the app and the agent interface + +**Owner instruction:** continue, after the milestone 6 report said the next step was this milestone's spec and its implementation in the same way. Spec: [spec-m7.md](spec-m7.md); its section 12 lists where the code differs from the sections before it. + +**Commits** (none pushed), Tuldok `feat/definition-first-projects`: spec `1b633ffb`; the operations table, the service, build requests and the worker `2e1f21d9`; the app, the agent contracts and the page `3f8f0f4b`. + +| Slice | What | Tests | +| --- | --- | --- | +| T13 service | `tuldok_project/operations.py` (36 operations as data), `service.py`, `activity.py` | 25 | +| T14 build requests | `tuldok_project/build_requests.py`, the worker in `service.py`, `expect` and `stop` on `builds.execute`, the commands `requests`, `approve`, `decline` | 18 | +| T15 app | `tuldok_project/host.py`, additive blocks in `app.py` (59 lines), `agent_api.py` (59 lines) and `mcp_stdio.py` (4 lines), the page, the "Serving a project" contract section | 16 | + +All Tuldok project tests: 482, about 3 minutes. The 14 existing agent and contract test modules named in the spec: 173 tests pass with 31 skipped, before the milestone and on its final code (run from the repository root with `PYTHONPATH=tests`). + +**Nothing published changed.** The `catalog` profile (115 operations), the old `project` profile (152 operations) and the legacy discovery document have the SHA-256 digests they had before the milestone; a test pins the three. No pinned contract fixture was regenerated: the earlier note that they would need it was wrong, because they record earlier contracts and this milestone only adds. + +**Changed in review:** + +- `ERROR_STATUS` became `error_status`. +- The worker logs a failure that repeats every pass once, not every second. +- The page's sign-in bar and dialog kept their light colours in a dark browser; they now follow the page. +- Found in the acceptance run: a command such as `requests` failed at once with "already open" when the app had the project open for a moment. The store commands now wait up to 5 seconds, as `build` and `progress` already did. +- From the acceptance agent's remarks: a request has `expires_at` while it is queued, and the descriptions of `progress` and `request_build` say how to read on and where to see the state. + +**One change outside the listed blocks:** `agent_api.AgentClient` accepted only refusal codes without hyphens, so every refusal of the new core reached an agent as a transport error. For a `project.*` selection it now passes on the code, `problems`, `references` and `files`. No existing line changed. + +**Acceptance run, `examples/tiny-project/project`** (throwaway catalog and database, local home in a scratch directory, port 8197): + +| Step | Result | +| --- | --- | +| `python app.py --project-folder ...` | serving in under a second | +| the owner signs in with a one-time code and issues an agent credential over HTTP | owner session; agent credential with `inspect`, `edit`, `execute`, `cancel` | +| the owner connects both environments with `ProjectFolderOwnerClient` | both ready; 36 operations offered | +| an agent given only the agent credential and `agent_api.AgentClient`, told to learn the operations from their descriptions | read the summary and the plan (3 steps to build), requested `benchmarks/held-out`: `awaiting-approval` | +| the owner's side: `approve` on the command line | showed who asked, the commit, the 3 steps and the 5 definitions held to; queued, then started within a second | +| the build | `succeeded` 23 s after approval: dataset 0.3 s, training 14.8 s on the GPU, benchmark 2.2 s and 1.3 s | +| the agent's polling of `progress` during training | 9 distinct events, from update 650 to 6,000 of 6,000, loss 0.0023 to 0.0006 | +| the agent's reading of the results and the ranking chart | `small-net-a` median error 0.0376, `predict-zero` 0.871, 400 cases each; the SVG saved | +| the agent's second request | refused 409 `nothing-to-build`; no request made | +| `activity` | four rows: two connects by the owner, the agent's request, the approval from the command line; then the refused second request | +| the page, in a headless browser as the signed-in owner | name, folder and the report with both charts, in light and dark, no script error, no sideways overflow | +| afterwards | the app stopped on `SIGINT` with exit status 0; no process carrying a run id; the GPU idle; the example unchanged in Git | + +**The lab project through the app** (271 definitions, 18 benchmarks, results from `results/*.csv` only): `summary`, `definitions`, `graph`, `results_overview`, one benchmark's 1,125 summary rows and each chart with its drawing answered in 0.02 to 0.09 s; `report` in 0.18 s; `plan` for everything in 0.09 s; `check` in 0.5 s. A request to build everything was refused as `blocked` and made no request. Nothing of the lab was run. + +**Not verified:** the MCP bridge with `--project-folder-owner` (the `mcp` and `anyio` packages are not installed here; the change is the flag and the client choice); the sign-in dialog typed by hand (the browser check was given the session cookie); a browser other than headless Chromium; cancelling a real long training through `cancel_build`; two apps on one project beyond the test of the worker lock. + +**Known gaps:** + +- While a build checks an environment, which takes a few seconds for the GPU one, every other operation waits. The agent saw one 4 second poll and so never observed `queued`. +- A request has no history of its states, and its runs appear in two shapes (`result` and `runs`). +- `context.get` and `identity.get` keep their generic descriptions; they are part of the pinned legacy discovery document. +- The example's benchmark reports one timing spread over its 400 cases, so `time_ms` has no spread. +- Carried over: the values file's `commit` is empty; nothing is ever deleted from the local home; installing an environment and measuring estimates are command-line only; the catalog queue does not take the GPU lock (spec section 9). + +**Next:** milestone 8, converting the lab for good and retiring the old project-files code. It needs the owner's two open decisions (where the product archive for the earlier weights goes; which earlier models to drop) and sign-off of the written capability check before any old module is deleted. From 5a52bed538f92d526dba2bf4f7574a288e5c24e3 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 12 Nov 2026 07:24:34 -0700 Subject: [PATCH 031/131] docs(plan): the earlier weights stay local, and the capability check for sign-off The owner decided on 2026-11-12 that weights stay with Tuldok on the machine, in its own per-project directory, and never go into Git; the product archive is not built now. capability-check.md lists the old project mode's 150 operations in eleven groups with what replaces each, what is not covered, the 38 modules that only that mode reaches and the eight import lines tying them to catalog mode. It is not signed; nothing is deleted until it is. Co-Authored-By: Claude Fable 5.2 --- .../capability-check.md | 77 +++++++++++++++++++ docs/plans/definition-first-projects/plan.md | 14 +++- 2 files changed, 87 insertions(+), 4 deletions(-) create mode 100644 docs/plans/definition-first-projects/capability-check.md diff --git a/docs/plans/definition-first-projects/capability-check.md b/docs/plans/definition-first-projects/capability-check.md new file mode 100644 index 00000000..6c0b55d5 --- /dev/null +++ b/docs/plans/definition-first-projects/capability-check.md @@ -0,0 +1,77 @@ +# Capability check: what deleting the old project mode removes + +**Status: written 2026-11-12 for the owner's sign-off. Not signed. Nothing is deleted until it is.** + +The [plan](plan.md) deletes the old project-files mode in milestone 8 on one condition: a written check that lists every capability of that mode as covered, moved or deliberately dropped, signed off by the owner. This is that check. It is a list of what Tuldok can do today through `python app.py --project-files-root ...` and what happens to each thing when that mode is gone. + +## The short answer + +For what the lab uses a project for (definitions, runs, results, charts, environments), the new format covers it. Four things are not covered and would be gone from projects: + +1. **Annotated data inside a project.** Records, imports, annotation, review, saved searches, selections and frozen releases exist in the new format nowhere. They stay available in catalog mode, which this plan does not change. A project folder cannot hold them until the annotation plan is written. +2. **The interactive project page.** The old page browses data, the experiment graph, progressions and measurements. The new page shows the report only, until the workspace screens have their plan. +3. **Studies, trials and candidate selection** as records Tuldok keeps. A trial becomes a recipe; the grouping lives in labels and notes. +4. **Reading a run's files through the agent interface.** An agent can read a run's record, its progress and the end of its logs, but not fetch its weights or other outputs; those are files on the same machine. + +## What would be deleted + +| What | Size | +| --- | --- | +| 38 Python modules that only the old mode reaches | 20,854 lines | +| The old project page and the extraction page, with their scripts and styles under `static/` | 3,263 lines in 10 files | +| 145 `project_files.*` and 5 `project_transfer.*` operations in `agent_api.py`, the `project` capability profile, the two owner clients and their `mcp_stdio.py` flags | | +| 74 test files that import one of those modules | 21,791 lines | +| The documentation of the old mode under `docs/contracts/` and its plans | | + +The 38 modules: `project_artifacts`, `project_cli`, `project_composition`, `project_custody`, `project_data`, `project_data_fork`, `project_dispatch`, `project_execution`, `project_extraction`, `project_files`, `project_fork`, `project_fork_composition`, `project_history`, `project_locks`, `project_material`, `project_material_fork`, `project_measurements`, `project_native_execution`, `project_native_preparation`, `project_native_process`, `project_producer_execution`, `project_producers`, `project_projection`, `project_record_dedupe`, `project_runtime`, `project_session`, `project_sources`, `project_store`, `project_study_execution`, `project_text`, `project_transfer`, `project_transfer_controller`, `project_validation_cache`, `project_validation_delta`, `project_working_store`, `project_workspace`, `retained_measurements`, `native_process_bootstrap`. + +**What stays:** catalog mode and everything it uses, including `projects.py` and `project_activity.py` (catalog mode's read-only inspection of project snapshots with `--project-root`), the access layer, the agent registry and clients, and the new `tuldok_project` package. + +**Where the old code is tied to catalog mode.** Eight import lines in three files reach into the 38 modules, so they change before anything is deleted: + +| File | What it imports | What happens | +| --- | --- | --- | +| `app.py` | `project_workspace`, `project_transfer_controller`, `project_transfer.stop_source`, `project_store.ProjectStoreError` | the old mode's start-up flags, routes and error branches are removed | +| `candidate_packages.py` | `ProjectHistory`, `ProjectExecution`, for two `isinstance` branches | the two branches are removed | +| `pipeline.py` | `preparation_owner` (twice), `native_admission_wall_seconds` | the project-only branches are removed; the one small function catalog mode also uses moves into `pipeline.py` | + +## Every capability + +The old mode has 150 operations. They are grouped here by what they do; each group says what replaces it. + +| Group | Operations | What it did | After deletion | +| --- | --- | --- | --- | +| Opening, saving and files on disk | 11: `status`, `new`, `open`, `save`, `close`, `files_inspect`, `file_get`, `file_history`, `file_adopt`, `files_adopt`, `file_adopt_deletion` | Create, open, save and close a project; see and adopt files changed on disk; a file's history | **Covered**, differently. `open`, `save`, `status`, `check`, `resolve_conflict`. Files changed on disk are imported on the next operation. Nothing stays open, so there is no close. History is Git's. **Gap:** no command creates a new folder; one copies the example. A `new` command is added in milestone 8 | +| Forks and composing | 3: `save_as`, `compose`, `fork_info` | Copy a project to an independent fork; merge retained checkpoints of several projects | **Dropped**, as the plan decided: a Git branch is a fork | +| Data records and annotation | 30: `query`, `get`, `import_text`, `annotate`, the `data_*` reads and imports for text, image, audio, mesh, point cloud, volume, sequence and scientific fields, `data_annotate`, `data_rights`, responses and preferences, `source_register`, `source_references` | Hold data records in a project, annotate and review them, record rights, responses and preference judgments | **Not covered. Catalog mode only.** The plan put annotation data out of scope; it needs its own plan before a project folder can hold it | +| Selections, searches, releases | 11: `selections`, `selection_*`, `searches`, `search_*`, `release_preview`, `release_freeze` | Saved selections and searches over records; freezing a dataset release with its splits | **Not covered. Catalog mode only**, with the group above | +| Definitions | 27: `definitions`, `models`, `model_*`, `graphs`, `graph_*`, `recipes`, `recipe_*`, the material reads, `material_intent*`, `dependencies`, `policies`, `policy` | Model drafts, node graphs and recipes with revisions; immutable captured copies ("materials") of each; publishing a model | **Covered**, differently: seven kinds of plain definition file, `definitions`, `definition`, `graph`, `set_definition`, `remove_definition`, `save`. No revisions and no captured copies; Git has the history. **Not covered:** the built-in node graphs (image, text and audio classifier training), which remain in catalog mode | +| Studies, trials, candidates, lineage | 17: `studies`, `study`, `study_create`, `study_save`, `trial`, `trial_prepare`, `candidate`, `candidate_select`, `lineage`, `lineage_record`, `progression`, `progression_origins`, `snapshot`, `evidence`, `package_state`, `publication_result`, `expose_holdout` | A study of trials with a budget; choosing a candidate; recorded lineage between runs; the progression view; recording that held-out test results were looked at | **Partly covered.** Lineage is the graph's edges; progression is a chart form ordered by `trained_at`; evidence is a recipe's card and its results. **Dropped:** studies, trials and budgets as records, candidate selection, snapshots, and the record of held-out exposure. The lab's 205 earlier models keep their study and trial origin as labels and cards | +| Runs and execution | 24: `run`, `runs`, `run_document_segment`, `artifacts`, `artifact_status`, `artifact_resolve`, `execution_health`, the external preflight, approve, submit and cancel, the `execution_study_*` operations, `execution_reconcile_current`, `native_*` | Preflight, owner approval, submission, cancel, retry and recovery of runs; reading a run's documents and artifacts in pieces | **Covered:** `plan`, `request_build`, `approve_build`, `decline_build`, `cancel_build`, `build_requests`, `runs`, `run`, `progress`, `products`, `cancel_run`, `stop_run`. A retry is a new request. **Not covered:** reading a run's output files through the interface | +| Producers | 8: `producers`, `producer`, `execution_producer_*`, `execution_generation_resume`, `execution_grounded_review` | Image generation, grounded review and caption or label proposals run inside a project | **Not covered. Catalog mode only** | +| Measurements and analysis | 9: `measurement_*`, `retained_analysis`, `retained_analysis_export` | Import result sets, query and compare them, inspect one observation with its evidence, export an analysis | **Covered:** `import_values`, `results_overview`, `results`, `values`, `chart` (ranking, tradeoff, progression, comparison), `report`. Summaries are rows in the database, not documents re-read per request. **Not covered:** the pointer from one observation back to its evidence file, and interactive charts | +| Runtimes | 5: `runtime_sources`, `runtime_inspect`, `runtime_capture`, `runtime_status`, `runtime_abandon` | Capture a copy of a Python environment with a listing of its files | **Covered**, differently: `environments`, `environment`, `connect_environment`, `check_environment`, and `set-up` on the command line. Versions are checked; nothing is copied or listed per file | +| Extraction from a catalog | 5: `project_transfer.*` | Stop a legacy catalog and extract it into a project | **Dropped.** The one project that needed converting is the lab, which its own script converts | + +Outside the operations: + +| Capability | After deletion | +| --- | --- | +| The old command line, `project_cli.py` | Replaced by `python -m tuldok_project` | +| Opening the lab's old folder (`projects/rheon-model-portfolio-unified-04`) in Tuldok | Gone. The lab's converter reads that folder's files directly, and the old code stays in Git history | +| Byte-identical save, receipts, custody and checkpoint proofs | Dropped, as the plan decided | + +## Before deletion, in milestone 8 + +These are done first, so the deletion removes nothing the lab still needs: + +1. The lab's earlier weights and prepared inputs are adopted as products into Tuldok's per-project directory (owner decision, 2026-11-12: they stay on this machine and never go into Git). +2. The lab repository holds the new folder only, and the clean-install test of the plan's summary passes. +3. The eight import lines above are cut and catalog mode's tests pass. +4. A `new` command exists. + +## Sign-off + +The owner signs by saying so; the date and the words are recorded here and in the ledger. + +- [ ] I accept that projects lose annotated data, the interactive page, studies and trials, and reading run files through the interface, as listed above, and the old project mode may be deleted. diff --git a/docs/plans/definition-first-projects/plan.md b/docs/plans/definition-first-projects/plan.md index 61ed45fa..c6fe5d43 100644 --- a/docs/plans/definition-first-projects/plan.md +++ b/docs/plans/definition-first-projects/plan.md @@ -56,7 +56,7 @@ Stated by the owner on 2026-11-10: | --- | --- | --- | --- | | Project folder | Definitions, notes and cards, result summaries | Yes | It is the source; Git has it | | Tuldok database | The imported definitions, the graph, run history, result rows and summaries, the activity log | No | Re-import the folder, then re-run or restore products | -| Product store (a local folder) | Generated files: datasets, weights, raw result files, logs | No | Re-run the steps, or restore from a product archive (section 9) | +| Product store (Tuldok's own directory for the project, on the machine) | Generated files: datasets, weights, raw result files, logs | No | Re-run the steps. Files that cannot be regenerated, such as the earlier weights, are single copies (section 9) | The rule for deciding where something goes: if a person or an agent wrote it, it is a definition and belongs in the folder. If a command produced it, it is a product and stays local. The one deliberate exception is the result summary, which Tuldok writes into the folder so the results travel with the project. @@ -189,7 +189,9 @@ Every operation in this plan is available through the agent interface and the co ### 9. Product archive -Some products cannot be regenerated or are expensive to. A product archive is a folder Tuldok writes on request, containing chosen products with their records, which can be copied to another disk or host and restored into another install. It is the answer to "where do the weights live", and it is never Git. +**Decided by the owner on 2026-11-12: not built now.** The weights stay with Tuldok on the local system, in Tuldok's own per-project directory, and never go into the Git repository. That directory is the product store of section 1, so the question this section answered, "where do the weights live", is answered without an archive. + +What the section proposed, kept for when a second machine needs the products: a product archive is a folder Tuldok writes on request, containing chosen products with their records, which can be copied to another disk or host and restored into another install. ### 10. The lab project: conversion and the exception @@ -248,7 +250,7 @@ Each milestone ends with a check against the lab. Sizes are relative. | 5 | Environments. Tuldok installs or connects an environment from its definition and checks it | Medium | On a machine without the lab's environments, Tuldok sets up the CPU and the GPU environment from their definitions and reports the versions it found. The GPU install is a multi-gigabyte download and needs the owner's go-ahead | | 6 | Build. Runs from a commit, per-definition limits, GPU, live progress, results published by the run | Large | On a fresh clone Tuldok builds one tiny dataset, trains one tiny model on the GPU with live progress, benchmarks it and charts it. This run needs the owner's go-ahead | | 7 | Serve the new core from the Tuldok app, with agent operations for all of the above | Medium | The app opens a project folder; an agent repeats milestone 6 through the interface alone | -| 8 | Convert the lab for good, then retire the old code. Product archive, tracked export replaced, old project-files modules removed | Medium | The lab repository holds the new folder only; the clean-install test in the summary passes. Before any old module is deleted, a written check lists every capability of the old project-files mode as covered, moved or deliberately dropped, and the owner signs it off | +| 8 | Convert the lab for good, then retire the old code. Earlier weights adopted into Tuldok's per-project directory, tracked export replaced, old project-files modules removed | Medium | The lab repository holds the new folder only; the clean-install test in the summary passes. Before any old module is deleted, a written check lists every capability of the old project-files mode as covered, moved or deliberately dropped, and the owner signs it off | The workspace redesign (the Map variant chosen on 2026-11-03) builds on milestones 2 and 3 and gets its own plan. @@ -268,10 +270,14 @@ Decided by the owner on 2026-11-10: 2. **Runs require committed code**, with a marked scratch-run escape. 3. **Tuldok installs and configures environments.** This replaces the proposal's "checked, not installed". +Decided by the owner on 2026-11-12: + +4. **The earlier weights stay with Tuldok on the local system**, in Tuldok's own per-project directory, which holds each project's data including its weights. They are not in the Git repository. No product archive is built now (section 9). + Still open, and needed only before milestone 8: -4. **Where the product archive for the earlier weights and raw results goes** (an external disk or a host). 5. **Which earlier models to drop**, if any. +6. **Sign-off of the [capability check](capability-check.md)** before any old module is deleted. ## Risks From 1a9b9e7389287faf0d03fe0a7b2942167c81a718 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 12 Nov 2026 08:50:09 -0700 Subject: [PATCH 032/131] docs(plan): specify milestone 8 part 1, where products live and adopting the earlier ones Co-Authored-By: Claude Fable 5.2 --- .../definition-first-projects/spec-m8.md | 125 ++++++++++++++++++ 1 file changed, 125 insertions(+) create mode 100644 docs/plans/definition-first-projects/spec-m8.md diff --git a/docs/plans/definition-first-projects/spec-m8.md b/docs/plans/definition-first-projects/spec-m8.md new file mode 100644 index 00000000..060f48c1 --- /dev/null +++ b/docs/plans/definition-first-projects/spec-m8.md @@ -0,0 +1,125 @@ +# Implementation spec: milestone 8, part 1: where products live, and adopting the earlier ones + +This continues the earlier specs in this folder. Section 1 of [spec-m1-m2.md](spec-m1-m2.md) (rules for implementers) applies. This part changes nothing outside `tuldok_project/`, `tests/`, `docs/` and the lab's converter. It deletes nothing. + +**Owner decisions, 2026-11-12:** + +- The model weights stay with Tuldok on the local system, in Tuldok's own per-project directory. They are never in the Git repository. No product archive is built. +- On the owner's machine that directory is on the OrangeCream disk. + +**Assumed until the owner says otherwise:** no earlier model is dropped. Keeping a definition is the reversible choice; one can be deleted later. + +**Done when:** the machine's project directory is a saved setting that every command and the app use; `adopt` makes the lab's earlier weights the products of their definitions without copying them; and the definitions that have their weights show as built. + +## 1. The project directory is a saved setting + +Until now the directory that holds every project's local home came from the environment variable `TULDOK_PROJECT_HOME` or a default under the home directory. A forgotten variable would send the next build's products to the default, on another disk, without a word. It becomes a setting. + +**Settings file:** `~/.local/share/tuldok/settings.json`, or the file named by `TULDOK_SETTINGS` (for tests). Strict JSON as in section 2.2 of the first spec, at most 64 KiB: + +```json +{"format": "tuldok_settings_v1", "project_home": "/absolute/path"} +``` + +`project_home` is optional. Unknown fields are refused. + +**Which directory is used,** first that applies: `TULDOK_PROJECT_HOME` when set and not empty; `project_home` of the settings file; `~/.local/share/tuldok/projects`. + +**A settings file that cannot be read or is not valid stops the command** with a message naming the file and the fault. It never falls back to the default. `local.projects_home()` raises `local.SettingsError`; the command line prints it and exits with status 2, and the app ends start-up with it. + +| Command | Does | +| --- | --- | +| `home` | prints the directory in use, where that came from (the environment variable, the settings file or the default), the free space on its disk, and how many project directories it holds. Needs no database | +| `home --set PATH` | `PATH` must be absolute. It is created with its parents when missing, and must be a directory this user can write. The settings file is written through a temporary file renamed into place, mode 0600. Says when the directory used before holds project directories (they are not moved) and when `TULDOK_PROJECT_HOME` is set and so overrides the setting | + +## 2. A new project + +`new FOLDER --name NAME [--code-root PATH]` makes `FOLDER` (which must not exist, or be an empty directory) and writes `tuldok.json` with the format, a new random id, the name and `code_root` (`.` when not given). It writes nothing else and needs no database. It refuses a name the project schema refuses. + +## 3. Adopting existing files as products + +Some files were made before Tuldok could build them and cannot be made again: the lab's earlier weights. Adoption makes such files the product of a definition, so the definition shows as built and later steps can use it as an input. + +**The manifest** is written by whoever knows where the files are (for the lab, its converter). Format `tuldok_adoption_v1`, strict JSON, at most 16 MiB: + +```json +{"format": "tuldok_adoption_v1", + "products": [ + {"reference": "recipes/pilot-a", + "note": "Tuldok run acb748bc of 2026-10-21", + "files": {"weights.npz": "/absolute/path/to/the/file", + "history.json": "/absolute/path/to/another"}} + ]} +``` + +| Field | Rule | +| --- | --- | +| `products` | 1 to 5000 entries; a reference appears once | +| `reference` | a dataset, recipe or step of the project, not removed | +| `note` | optional, 1 to 400 characters; kept as the run's `problem` text, which is where a run's remark is shown | +| `files` | 1 to 200 entries. Each key is a relative path in normal form. When the definition declares outputs, the key is the `path` of one of them or a path under one. When it declares none, its product is the directory as a whole, which is what a step that uses it as an input is given, and any relative path is accepted. Each value is the absolute path of an existing regular file; a link is refused | + +Unknown fields are refused. + +**Checking.** Every entry is checked before anything is adopted, and one refused entry stops the command with nothing adopted. For a definition that declares outputs, an entry none of whose declared outputs has a file is refused; declared outputs without a file are reported as missing, and the entry is still adopted. + +**What adopting an entry does:** + +1. Makes `/runs//output/` holding the files at their keys, as hard links to the sources. A source on another filesystem is copied, and `--copy` copies always. The directory is made under a temporary name and renamed into place. +2. Inserts a run: state `adopted`, no commit, no command, the definition's text as it is now, the note, all three times now, the bytes of the files. +3. Inserts its product, current, with the declared outputs that have a file. A product that was current before stays in the database, no longer current. + +An entry whose definition already has a current product is skipped, unless `--replace`. + +**The state of an adopted product.** A definition whose current product was adopted is `built` and is never out of date: it was not built here, so its definition text, inputs and code are not compared. `status`, `products`, `runs` and `run` show that it was adopted. A real build of the definition replaces it like any other product. Tuldok never writes to an adopted file. + +**No checksum is recorded.** The size of each file is. + +| Command | Does | +| --- | --- | +| `adopt FOLDER MANIFEST [--dry-run] [--copy] [--replace] [--json]` | checks the manifest and prints what it would do: entries to adopt, entries skipped because they have a product, declared outputs missing, files and bytes, and whether they will be linked or copied. Without `--dry-run` it then does it and prints the same with what was done. Exit status 1 when an entry is refused | + +Adoption is a command-line action only: a manifest names files anywhere on the machine. + +## 4. The lab's manifest + +`lab:scripts/build_tuldok_project.py --adoption-output FILE` writes the manifest for the earlier recipes and datasets, from the old project folder it already reads. For each earlier recipe: the files of its old run that are present under the old folder's `artifacts/sha256/`, keyed by the recipe's declared output paths. The earlier datasets have no run of their own and declare no outputs; for each, the files the earlier recipes' runs read from it, keyed by each file's path inside the dataset's directory. Where two different stored files claim one path of a dataset, that path is left out and reported. The file holds absolute paths, so it belongs outside Git, by default under `runs/tuldok-adoption/`. + +It prints how many earlier definitions have every declared output, some, or none; the files and bytes named; and the files in `artifacts/sha256/` that no definition claims, as a count and bytes. It reads the old folder and changes nothing in it. `--check` is unchanged. + +## 5. Acceptance of this part + +Done by the orchestrating session on a throwaway database, with a throwaway project directory on the same filesystem as the lab so that adoption links and does not copy: + +- `home` reports the setting; a command run without the environment variable uses it. +- `adopt --dry-run` on the lab's manifest, then `adopt`: the counts of adopted, skipped and missing; free space on the disk before and after; the states of the lab's definitions before and after; `plan --all` before and after. +- A second `adopt` skips everything. +- Removing the throwaway directory leaves every file of the old folder in place. + +## 6. What follows, each on the owner's word + +1. Adopting into the owner's real project directory and database. +2. The lab repository: the tracked old project folder is replaced by the new one. +3. Deleting the old project mode, after the [capability check](capability-check.md) is signed. + +## 7. Slices + +| Slice | Files | Notes | +| --- | --- | --- | +| T16 settings, new, adopt | `tuldok_project/local.py`, a new `tuldok_project/adoption.py`, the adopted rule in `builds.py`, `home`, `new` and `adopt` in `__main__.py`, tests, and the sections of `docs/contracts/project-folder.md` | database tests on the `buildable` fixture | +| L4 lab manifest | `lab:scripts/build_tuldok_project.py`, `lab:scripts/tests/` | beside T16; reads the old folder only | + +## 8. As built + +Found while implementing; the code and its tests follow this section. + +- **A built definition no longer blocks what uses it.** Until now `cannot-rebuild` and `needs-work` were carried from a definition to everything that uses it as an input, whatever was on the machine (spec-m4). A definition that is built on this machine, by a build or by adoption, now carries nothing to what uses it and nothing through it: its product is there to be used. Without this an adopted dataset could not be the input of a new recipe, which is the point of adopting it. A definition that is out of date still carries. +- **A recipe that is held but has a current product** can be a benchmark subject. +- **The refusal "none of whose declared outputs has a file" cannot occur:** every key lies under a declared output and `files` is not empty. +- **Also refused:** two keys of one entry where one lies under the other, and a source this user cannot read. +- **No command rebuilds an adopted definition.** It is never out of date, so `build` skips it. A way to set an adopted product aside is not written. +- **The settings file is read only when `TULDOK_PROJECT_HOME` does not decide** and only by a command that needs the directory. +- **The directory used before, for `home --set`,** is what the settings file or the default gave, the variable aside. +- **`adopt` holds the project open for its whole run.** With links that is seconds. A failure partway leaves the entries before it adopted, and the command says so. +- **Closing a project now releases its lock by a statement.** Closing the connection alone left the lock held until the server noticed, so a project opened again at once could be refused as already open. The full test run showed it once on a busy machine. +- **The lab's manifest** has one entry per earlier recipe with a run (203) and per earlier dataset that an earlier recipe read (25). A dataset's directory is its one folder, or the deepest directory that holds all its folders. From 3af6b6a6f0b6f8bbf70b98e370a6f5d23ace67b4 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 12 Nov 2026 08:50:09 -0700 Subject: [PATCH 033/131] feat(project): a saved project directory, new projects, and adopting existing files The directory that holds every project's local home is now a setting in ~/.local/share/tuldok/settings.json, shown and set with the home command. TULDOK_PROJECT_HOME still overrides it. A settings file that is not valid stops the command; it never falls back to the default. new makes a project folder. adopt takes a manifest of existing files and makes them the product of their definitions by hard link, so files made before Tuldok could build them (the lab's earlier weights and training data) show as built and can be inputs of later steps. An adopted product is never out of date. A definition that is built on this machine no longer carries cannot-rebuild or needs-work to what uses it. Closing a project now releases its lock by a statement, so it can be opened again at once. Co-Authored-By: Claude Fable 5.2 --- docs/contracts/project-folder.md | 133 +++++++- tests/test_tuldok_project_adoption.py | 368 ++++++++++++++++++++++ tests/test_tuldok_project_builds.py | 14 + tests/test_tuldok_project_environments.py | 4 +- tests/test_tuldok_project_local.py | 249 +++++++++++++++ tuldok_project/__main__.py | 178 ++++++++++- tuldok_project/adoption.py | 252 +++++++++++++++ tuldok_project/builds.py | 41 ++- tuldok_project/graph.py | 14 +- tuldok_project/host.py | 15 +- tuldok_project/local.py | 149 ++++++++- tuldok_project/plan.py | 15 +- tuldok_project/store.py | 16 +- 13 files changed, 1397 insertions(+), 51 deletions(-) create mode 100644 tests/test_tuldok_project_adoption.py create mode 100644 tests/test_tuldok_project_local.py create mode 100644 tuldok_project/adoption.py diff --git a/docs/contracts/project-folder.md b/docs/contracts/project-folder.md index 96deb0eb..e30996d4 100644 --- a/docs/contracts/project-folder.md +++ b/docs/contracts/project-folder.md @@ -1026,8 +1026,8 @@ Removing an environment definition, or deleting its file, drops its row. The row never deletes an installed directory. Environments that Tuldok installs live in the project's local home, -`$TULDOK_PROJECT_HOME//`, where `TULDOK_PROJECT_HOME` defaults to -`~/.local/share/tuldok/projects`. An installed environment is the directory +`//`, where the project directory is the one +[the setting](#the-project-directory-on-this-machine) names. An installed environment is the directory `/environments//`, with its log beside it as `/environments/.log`. The local home is made the first time something is installed. @@ -1349,7 +1349,7 @@ strays. ### The GPU lock A step that declares `gpu: true` holds an exclusive lock on -`$TULDOK_PROJECT_HOME/gpu.lock` while its command runs. The lock is shared by +`/gpu.lock` while its command runs. The lock is shared by every project on this machine, so two GPU steps never run at the same time; a build that finds the lock taken waits for it. Steps without `gpu: true` take no lock. @@ -1376,6 +1376,7 @@ others. | `over-disk` | stopped at, or ended over, its disk limit | | `cancelled` | stopped because cancellation was asked for, with `cancel` or by a signal to `build` | | `unknown` | how it ended is not known: its build is gone, or a process of the run could not be stopped | +| `adopted` | nothing was run: `adopt` made files made elsewhere its product (see [Adopting existing files](#adopting-existing-files)) | ### Build states @@ -1408,7 +1409,9 @@ product it is `not-built`, or `failed` when its latest run ended badly. A produc is `built` or `out-of-date` even when its label would make it `cannot-rebuild` or `needs-work`; those take precedence only when there is no current product. A `cancelled` run never makes a definition `failed`, and a -definition with a current product keeps it. +definition with a current product keeps it. A definition whose current +product was adopted is `built` and never out of date: none of the causes above +is looked at. In a plan, `built` is the action `built` and is not counted as work; `out-of-date`, `failed` and `running` are `build`, and the plan says why under @@ -1845,9 +1848,129 @@ Installing an environment (`set-up`), measuring estimates (`estimate`), variables passed to a build (`build --env`), rebinding and forgetting a project stay command-line actions. +## The project directory on this machine + +Everything a project keeps on one machine alone (installed environments, code +snapshots, run directories and products) is in its local home, +`//`. The project directory is, first that +applies: + +1. the environment variable `TULDOK_PROJECT_HOME`, when it is set and not empty; +2. `project_home` of the settings file; +3. `~/.local/share/tuldok/projects`. + +The settings file is `~/.local/share/tuldok/settings.json`, or the file the +environment variable `TULDOK_SETTINGS` names. It is strict JSON as in +[JSON rules](#json-rules), at most 64 KiB, and has no other fields: + +```json +{"format": "tuldok_settings_v1", "project_home": "/absolute/path"} +``` + +`project_home` is optional and must be absolute. The file is read only when +the environment variable does not decide. A settings file that cannot be read +or is not valid stops the command with a message naming the file and the +fault, exit status 2, and stops the app's start-up; Tuldok never falls back to +the default then. + +| Command | Does | +| --- | --- | +| `home [--json]` | Prints the project directory, where it came from (the environment variable, the settings file or the default), the free space on its disk and how many project directories it holds. Needs no database. | +| `home --set PATH [--json]` | Saves `PATH`, which must be absolute, as `project_home`. `PATH` is made with its parents when missing and must be a directory this user can write. The settings file is written through a temporary file renamed into place, mode 0600. Says when the directory the setting or the default gave before holds project directories (they are not moved), and when `TULDOK_PROJECT_HOME` is set and so overrides the setting. | + +``` +$ .venv/bin/python -m tuldok_project home +directory /mnt/data/tuldok/projects +from the settings file /home/me/.local/share/tuldok/settings.json +free 812 GB on its disk +projects 2 +``` + +## A new project + +`new FOLDER --name NAME [--code-root PATH] [--json]` makes `FOLDER`, which must +not exist or must be an empty directory, and writes `tuldok.json` in it with +the format, a new random id, the name and `code_root` (`.` when not given). It +writes nothing else and needs no database. A name or code root that +[`tuldok.json`](#tuldokjson) does not allow is refused with exit status 2, and +nothing is made. + +## Adopting existing files + +Some files were made before Tuldok could build them and cannot be made again, +such as an earlier model's weights. `adopt` makes such files the product of a +dataset, recipe or step, so it is `built` and what uses it can be built. It is +a command-line action only, since a manifest names files anywhere on the +machine. + +The manifest is strict JSON, at most 16 MiB: + +```json +{"format": "tuldok_adoption_v1", + "products": [ + {"reference": "recipes/pilot-a", + "note": "Tuldok run acb748bc of 2026-10-21", + "files": {"weights.npz": "/absolute/path/to/the/file", + "history.json": "/absolute/path/to/another"}} + ]} +``` + +| Field | Rule | +| --- | --- | +| `products` | 1 to 5000 entries; a reference appears once | +| `reference` | a dataset, recipe or step of the project, not removed | +| `note` | optional, 1 to 400 characters; kept as the run's problem text, where a run's remark is shown | +| `files` | 1 to 200 entries. Each key is a relative path in normal form where the file goes in the product. When the definition declares outputs, the key is the `path` of one of them or a path under one; when it declares none, its product is the directory as a whole (what a step that uses it as an input is given) and any relative path is accepted. No key may have another under it. Each value is the absolute path of an existing regular file this user can read; a link is refused | + +Unknown fields are refused. Every entry is checked before anything is +adopted: one refused entry stops the command, every problem is printed, and +nothing is adopted. Declared outputs without a file are reported as missing, +and the entry is still adopted. An entry whose definition already has a +current product is skipped, unless `--replace`. + +Adopting an entry makes `/runs//output/` holding the files +at their keys, as hard links to the sources; a source on another filesystem +is copied, and `--copy` copies always. The directory is made under a temporary +name and renamed into place. Then a run is recorded in state `adopted`, with +no commit and no command, the definition's text as it is now, the note, all +three times set to now and the total size of the files; and its product, made +current, with the declared outputs that have a file and the size of each. A +product that was current before stays in the database, no longer current. No +checksum is taken, and Tuldok never writes to an adopted file. + +A definition whose current product was adopted is `built` and never out of +date: its text, settings, inputs and code are not compared. `plan` shows it as +`built` (noting `adopted, not built here`) and plans nothing it uses. A +benchmark subject whose recipe has a current product runs even when the +recipe's own label is `no` or `needs-work`. `runs` and `run` show the state +`adopted`; `products` and `run` mark the product `(adopted)`, and their JSON, +like `status` entries and the app's `runs`, `run` and `products` results, +carries `adopted: true`. A real build of the definition replaces it like any +other product. + +| Command | Does | +| --- | --- | +| `adopt FOLDER MANIFEST [--dry-run] [--copy] [--replace] [--json]` | Checks the manifest and prints what it would do: the entries to adopt, those skipped because they have a product, the declared outputs missing, the files and bytes, and whether they are linked or copied. Without `--dry-run` it then does it and prints the same, with each new run id. | + +Exit statuses: 0 done (or, with `--dry-run`, checked); 1 when an entry is +refused, the manifest is not strict JSON, or copying or linking failed (the +entries printed before the failure were adopted); 2 when the manifest cannot +be read. + +``` +$ .venv/bin/python -m tuldok_project adopt FOLDER manifest.json --dry-run +Would adopt 1 entry, skip 0 that already have a product. +1 file, 61 B: 1 to be linked, 0 copied. + +adopt datasets/numbers 1 file 61 B linked + +Nothing was changed (--dry-run). +``` + ## What the format does not do yet -The folder is checked, can be opened, edited and saved through the database +A project folder can be made with `new`, files made elsewhere can be adopted +as products, and the folder is checked, can be opened, edited and saved through the database copy, its results can be read and drawn, its environments can be connected, checked and installed, and its definitions can be planned, estimated and built on this machine, one build at a time per step, from the command line diff --git a/tests/test_tuldok_project_adoption.py b/tests/test_tuldok_project_adoption.py new file mode 100644 index 00000000..3821379d --- /dev/null +++ b/tests/test_tuldok_project_adoption.py @@ -0,0 +1,368 @@ +"""Adopting existing files as products (docs/plans/definition-first-projects/spec-m8.md, section 3). + +Every test needs a database and runs only when TULDOK_DATABASE_URL names a +disposable cluster (spec-m1-m2.md, section 1). Each starts from +test_tuldok_project_builds.BuildCase: a Git-committed copy of the buildable +fixture with its environment connected, TULDOK_PROJECT_HOME pointing at a +temporary directory, dropped afterwards. TULDOK_SETTINGS points at a file in +that directory too, so the real settings file is never read. The files +adopted are written by the tests under the same temporary directory, so they +are on the project directory's filesystem and are linked unless --copy. The +builds run the fixture's stand-in scripts; no GPU is used. +""" +import json +import os +from pathlib import Path +import subprocess +import sys +import unittest +from unittest import mock + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) +sys.path.insert(0, str(Path(__file__).resolve().parent)) + +from tuldok_project import adoption, builds, local, operations # noqa: E402 +from tuldok_project.service import Service # noqa: E402 +import test_tuldok_project_builds as builds_base # noqa: E402 +import test_tuldok_project_service as service_base # noqa: E402 + +NUMBERS = {'numbers': [5.0, 5.0, 5.0, 5.0, 5.0, 5.0]} # the stand-in dataset makes numbers in [-1, 1] + + +class AdoptionCase(builds_base.BuildCase): + + def setUp(self): + super().setUp() + patcher = mock.patch.dict(os.environ, {local.SETTINGS_VARIABLE: str(self.temporary / 'settings.json')}) + patcher.start() + self.addCleanup(patcher.stop) + self.old = self.temporary / 'old' + self.old.mkdir() + self.numbers = self.source('numbers.json', json.dumps(NUMBERS)) + self.weights = self.source('weights.json', json.dumps({'constant': 0.25})) + + def source(self, name, text): + path = self.old / name + path.write_text(text, encoding='utf-8') + return path + + def manifest(self, *entries, **top): + document = {'format': 'tuldok_adoption_v1', 'products': list(entries), **top} + path = self.temporary / 'manifest.json' + path.write_text(json.dumps(document), encoding='utf-8') + return document, path + + def numbers_entry(self, **extra): + return {'reference': 'datasets/numbers', 'note': 'made long ago', 'files': {'numbers.json': str(self.numbers)}, + **extra} + + def adopt(self, *entries, dry_run=False, copy=False, replace=False): + document, _ = self.manifest(*entries) + with self.opened() as project: + made = adoption.make_plan(project, document, copy=copy, replace=replace) + return made if dry_run else adoption.adopt(project, made) + + def refused(self, document): + with self.opened() as project: + with self.assertRaises(adoption.AdoptionError) as caught: + adoption.make_plan(project, document) + return caught.exception.problems + + def run_cli(self, *arguments): + environment = dict(os.environ, PYTHONDONTWRITEBYTECODE='1') + return subprocess.run([sys.executable, '-m', 'tuldok_project', *map(str, arguments)], + cwd=builds_base.REPOSITORY, env=environment, capture_output=True, text=True, timeout=120) + + def nothing_recorded(self): + self.assertEqual(self.runs(), []) + self.assertEqual(self.products(), []) + + +class Adopting(AdoptionCase): + + def test_an_adopted_dataset_is_built_and_used_by_a_real_build(self): + before = (self.numbers.read_bytes(), os.stat(self.numbers)) + done = self.adopt(self.numbers_entry()) + entry = done['entries'][0] + self.assertEqual((entry['action'], entry['missing'], done['counts']['linked'], done['counts']['copied']), + ('adopt', [], 1, 0)) + self.assertEqual(entry['directory'], os.path.join(self.home, self.project_id, 'runs', entry['run_id'], 'output')) + adopted = Path(entry['directory']) / 'numbers.json' + self.assertEqual(os.stat(adopted).st_ino, before[1].st_ino) # a hard link on the same filesystem + self.assertEqual([name for name in os.listdir(self.home / self.project_id / 'runs')], [entry['run_id']]) + + status = self.status()['datasets/numbers'] + self.assertEqual((status['state'], status['adopted'], status['causes']), ('built', True, [])) + self.assertEqual(self.states()['datasets/numbers'], 'built') + run = self.runs('datasets/numbers')[0] + size = len(before[0]) + self.assertEqual((run['state'], run['commit'], run['argv'], run['problem'], run['bytes']), + ('adopted', '', [], 'made long ago', size)) + self.assertIsNotNone(run['started_at']) + self.assertIsNotNone(run['finished_at']) + product = self.products('datasets/numbers')[0] + self.assertTrue(product['adopted']) + self.assertEqual(product['outputs'], {'data': {'path': 'numbers.json', 'role': 'data', 'bytes': size}}) + + made = self.plan('benchmarks/score') + actions = {step['reference']: step['action'] for step in made['steps']} + self.assertEqual(actions, {'environments/test-python': 'ready', 'datasets/numbers': 'built', + 'recipes/fit-a': 'build', 'benchmarks/score': 'build'}) + self.assertTrue(next(step for step in made['steps'] if step['reference'] == 'datasets/numbers')['adopted']) + done = self.build('benchmarks/score') + self.assertTrue(done['ok'], done) + self.assertEqual(self.ran(done), [('recipes/fit-a', '', 'succeeded'), ('benchmarks/score', 'fit-a', 'succeeded'), + ('benchmarks/score', 'zero', 'succeeded')]) + weights = Path(self.products('recipes/fit-a')[0]['directory']) / 'weights.json' + self.assertGreater(json.loads(weights.read_text())['constant'], 1) # trained on the adopted numbers + self.assertEqual({entry['state'] for entry in self.status().values()}, {'built'}) + self.assertEqual((self.numbers.read_bytes(), os.stat(self.numbers).st_mtime_ns, + os.stat(self.numbers).st_mode), (before[0], before[1].st_mtime_ns, before[1].st_mode)) + + def test_a_dataset_that_declares_no_outputs_is_adopted_as_a_directory(self): + def whole(document): # use the dataset's directory as a whole + document['run']['inputs']['data'] = 'datasets/numbers' + command = document['run']['command'] + command[command.index('{inputs.data}')] = '{inputs.data}/numbers.json' + self.edit('recipes/fit-a', whole) + self.edit('benchmarks/score', whole) + self.edit('datasets/numbers', lambda document: document['run'].pop('outputs')) + extra = self.source('notes.txt', 'n' * 7) + done = self.adopt({'reference': 'datasets/numbers', + 'files': {'numbers.json': str(self.numbers), 'any/where/notes.txt': str(extra)}}) + entry = done['entries'][0] + self.assertEqual((entry['outputs'], entry['missing']), ({}, [])) + total = self.numbers.stat().st_size + 7 + self.assertEqual(self.runs('datasets/numbers')[0]['bytes'], total) + product = self.products('datasets/numbers')[0] + self.assertEqual((product['outputs'], product['adopted']), ({}, True)) + self.assertTrue((Path(entry['directory']) / 'any' / 'where' / 'notes.txt').is_file()) + self.assertEqual(self.status()['datasets/numbers']['state'], 'built') + done = self.build('recipes/fit-b') # fit-b reads {inputs.data}/numbers.json + self.assertTrue(done['ok'], done) + self.assertEqual(self.ran(done), [('recipes/fit-b', '', 'succeeded')]) + weights = Path(self.products('recipes/fit-b')[0]['directory']) / 'weights.json' + self.assertGreater(json.loads(weights.read_text())['constant'], 1) # read from the adopted directory + + def test_copy_copies(self): + done = self.adopt(self.numbers_entry(), copy=True) + self.assertEqual((done['counts']['linked'], done['counts']['copied']), (0, 1)) + adopted = Path(done['entries'][0]['directory']) / 'numbers.json' + self.assertNotEqual(os.stat(adopted).st_ino, os.stat(self.numbers).st_ino) + self.assertEqual(adopted.read_bytes(), self.numbers.read_bytes()) + + def test_a_file_under_a_declared_output_and_a_missing_output(self): + def two_outputs(document): + document['run']['outputs'] = {'data': {'path': 'numbers.json', 'role': 'data'}, + 'extra': {'path': 'extra', 'role': 'file'}, + 'more': {'path': 'more.json', 'role': 'file'}} + self.edit('datasets/numbers', two_outputs) + part = self.source('part.bin', 'x' * 10) + done = self.adopt({'reference': 'datasets/numbers', + 'files': {'numbers.json': str(self.numbers), 'extra/deep/part.bin': str(part)}}) + entry = done['entries'][0] + self.assertEqual(entry['missing'], [{'name': 'more', 'path': 'more.json'}]) + self.assertEqual(done['counts']['missing'], 1) + self.assertTrue((Path(entry['directory']) / 'extra' / 'deep' / 'part.bin').is_file()) + product = self.products('datasets/numbers')[0] + self.assertEqual(sorted(product['outputs']), ['data', 'extra']) + self.assertEqual(product['outputs']['extra']['bytes'], 10) + self.assertIsNone(self.runs('datasets/numbers')[0]['problem']) # no note + self.assertEqual(self.status()['datasets/numbers']['state'], 'built') + + def test_dry_run_changes_nothing(self): + done = self.adopt(self.numbers_entry(), dry_run=True) + self.assertEqual(done['counts'], {'adopt': 1, 'skip': 0, 'missing': 0, 'files': 1, + 'bytes': self.numbers.stat().st_size, 'linked': 1, 'copied': 0}) + self.nothing_recorded() + self.assertFalse((self.home / self.project_id / 'runs').exists()) + _, path = self.manifest(self.numbers_entry()) + shown = self.run_cli('adopt', self.folder, path, '--dry-run') + self.assertEqual(shown.returncode, 0, shown.stderr) + self.assertTrue(shown.stdout.startswith('Would adopt 1 entry, skip 0 that already have a product.\n'), + shown.stdout) + self.assertIn('1 file', shown.stdout) + self.assertIn('linked', shown.stdout) + self.assertTrue(shown.stdout.endswith('Nothing was changed (--dry-run).\n')) + self.nothing_recorded() + + def test_a_second_adopt_skips_and_replace_adopts_again(self): + first = self.adopt(self.numbers_entry())['entries'][0]['run_id'] + again = self.adopt(self.numbers_entry()) + self.assertEqual((again['entries'][0]['action'], again['entries'][0]['current_run']), ('skip', first)) + self.assertEqual(again['counts']['adopt'], 0) + self.assertEqual(len(self.runs()), 1) + replaced = self.adopt(self.numbers_entry(), replace=True)['entries'][0]['run_id'] + self.assertNotEqual(replaced, first) + self.assertEqual(self.products('datasets/numbers')[0]['run_id'], replaced) + with self.opened() as project: + rows = project._execute('SELECT run_id, current FROM {schema}.products ORDER BY current').fetchall() + self.assertEqual(rows, [(first, False), (replaced, True)]) # the old product stays, no longer current + + def test_an_adopted_product_is_never_out_of_date(self): + self.adopt(self.numbers_entry(), {'reference': 'recipes/fit-a', 'files': {'weights.json': str(self.weights)}}) + self.assertEqual(self.states()['recipes/fit-a'], 'built') + self.edit('recipes/fit-a', lambda document: document.update(title='Fit a, retitled')) + self.edit('datasets/numbers', lambda document: document['run']['settings'].update(count=7)) + self.write_code('train.py', (self.code / 'train.py').read_text() + '# changed\n') + self.write_code('make_data.py', (self.code / 'make_data.py').read_text() + '# changed\n') + self.commit('Change the code.') + status = self.status() + self.assertEqual({reference: status[reference]['state'] for reference in status}, + {'datasets/numbers': 'built', 'recipes/fit-a': 'built'}) + made = self.plan('datasets/numbers') + made['steps'] = [dict(step, action='build') if step['reference'] == 'datasets/numbers' else step + for step in made['steps']] + made['counts']['build'] = 1 + done = builds.execute(self.folder, made, confirm=lambda given: True) # a real build of the definition + self.assertTrue(done['ok'], done) + self.assertEqual(self.status()['recipes/fit-a']['state'], 'built') # its input was rebuilt: not compared + numbers = self.status()['datasets/numbers'] + self.assertEqual((numbers['state'], numbers['adopted']), ('built', False)) # the build replaced it + self.assertFalse(self.products('datasets/numbers')[0]['adopted']) + self.assertEqual(json.loads(self.numbers.read_text()), NUMBERS) # the old file is untouched + + def test_plan_needs_nothing_an_adopted_definition_uses(self): + self.adopt({'reference': 'recipes/fit-a', 'files': {'weights.json': str(self.weights)}}) + made = self.plan('recipes/fit-a') + self.assertEqual([(step['reference'], step['action']) for step in made['steps']], [('recipes/fit-a', 'built')]) + self.assertEqual(made['counts']['build'], 0) + + def test_a_benchmark_subject_uses_an_adopted_recipe_held_by_its_label(self): + self.edit('recipes/fit-a', lambda document: document.update( + earlier_work={'rebuild': 'no', 'reason': 'Its code is lost.'})) + self.assertEqual(self.plan('benchmarks/score')['steps'][-1]['subjects']['run'], ['zero']) # held before + self.adopt({'reference': 'recipes/fit-a', 'files': {'weights.json': str(self.weights)}}) + made = self.plan('benchmarks/score') + self.assertEqual(made['steps'][-1]['subjects']['run'], ['fit-a', 'zero']) + done = self.build('benchmarks/score') + self.assertTrue(done['ok'], done) + self.assertEqual(self.ran(done), [('datasets/numbers', '', 'succeeded'), ('benchmarks/score', 'fit-a', 'succeeded'), + ('benchmarks/score', 'zero', 'succeeded')]) + score = self.status()['benchmarks/score'] + self.assertEqual((score['state'], sorted(score['subjects'])), ('built', ['fit-a', 'zero'])) + run = self.runs('benchmarks/score') + fit = next(row for row in run if row['subject'] == 'fit-a') + self.assertEqual(fit['inputs']['{recipe}']['run_id'], self.products('recipes/fit-a')[0]['run_id']) + self.assertEqual(self.build('benchmarks/score')['steps'], []) # nothing left to build + + +class Refusals(AdoptionCase): + + def test_every_refusal_stops_the_whole_manifest(self): + good = self.numbers_entry() + link = self.old / 'link.json' + link.symlink_to(self.numbers) + with self.opened() as project: + project.remove_definition('steps/gpu-two') + weights = {'weights.json': str(self.weights)} + cases = { + 'another format': ({'format': 'tuldok_adoption_v2', 'products': [good]}, 'format'), + 'an unknown top field': ({'format': 'tuldok_adoption_v1', 'products': [good], 'x': 1}, "'x'"), + 'no products': ({'format': 'tuldok_adoption_v1', 'products': []}, '1 to 5000'), + 'too many products': ({'format': 'tuldok_adoption_v1', 'products': [good] * 5001}, '1 to 5000'), + 'a reference twice': (self.manifest(good, good)[0], 'more than once'), + 'not a reference': (self.manifest(dict(good, reference='numbers'))[0], 'reference such as'), + 'no such definition': (self.manifest(dict(good, reference='datasets/none'))[0], 'no definition'), + 'a removed definition': (self.manifest({'reference': 'steps/gpu-two', 'files': { + 'times.json': str(self.numbers)}})[0], 'no definition'), + 'a benchmark': (self.manifest({'reference': 'benchmarks/score', 'files': { + 'values.json': str(self.numbers)}})[0], 'only a dataset, recipe or step'), + 'an environment': (self.manifest(dict(good, reference='environments/test-python'))[0], + 'only a dataset, recipe or step'), + 'an unknown entry field': (self.manifest(dict(good, size=3))[0], "'size'"), + 'an empty note': (self.manifest(dict(good, note=''))[0], 'note'), + 'a note too long': (self.manifest(dict(good, note='n' * 401))[0], 'note'), + 'no files': (self.manifest(dict(good, files={}))[0], '1 to 200'), + 'files not an object': (self.manifest(dict(good, files=[str(self.numbers)]))[0], '1 to 200'), + 'too many files': (self.manifest(dict(good, files={f'numbers.json/{index}': str(self.numbers) + for index in range(201)}))[0], '1 to 200'), + 'a key not in normal form': (self.manifest(dict(good, files={'./numbers.json': str(self.numbers)}))[0], + 'normal form'), + 'an absolute key': (self.manifest(dict(good, files={'/numbers.json': str(self.numbers)}))[0], 'absolute'), + 'a key with ..': (self.manifest(dict(good, files={'../numbers.json': str(self.numbers)}))[0], "'..'"), + 'a key that is no declared output': (self.manifest(dict(good, files={'other.json': str(self.numbers)}))[0], + 'not a declared output'), + 'a file with a file under it': (self.manifest({'reference': 'recipes/fit-a', 'files': { + 'weights.json': str(self.weights), 'weights.json/x': str(self.weights)}})[0], 'nothing can be under'), + 'a relative source': (self.manifest(dict(good, files={'numbers.json': 'old/numbers.json'}))[0], + 'absolute path'), + 'a missing source': (self.manifest(dict(good, files={'numbers.json': str(self.old / 'gone.json')}))[0], + 'cannot be read'), + 'a link': (self.manifest(dict(good, files={'numbers.json': str(link)}))[0], 'is a link'), + 'a directory': (self.manifest(dict(good, files={'numbers.json': str(self.old)}))[0], 'not a regular file'), + } + for name, (document, words) in cases.items(): + with self.subTest(name): + if name not in ('another format', 'an unknown top field', 'no products', 'too many products'): + document['products'].append({'reference': 'recipes/fit-a', 'files': weights}) # a good entry too + problems = self.refused(document) + self.assertTrue(any(words in problem for problem in problems), problems) + self.nothing_recorded() + self.assertFalse((self.home / self.project_id / 'runs').exists()) + self.assertEqual(link.resolve(), self.numbers) + + def test_the_command_line_refuses_with_status_1(self): + _, path = self.manifest(self.numbers_entry(), {'reference': 'recipes/fit-a', + 'files': {'weights.json': str(self.old / 'gone')}}) + refused = self.run_cli('adopt', self.folder, path) + self.assertEqual(refused.returncode, 1) + self.assertEqual(refused.stdout, '') + self.assertIn('products[1] (recipes/fit-a): the source of weights.json', refused.stderr) + self.assertIn('Nothing was adopted: 1 problem in the manifest.', refused.stderr) + self.nothing_recorded() + path.write_text('{"format": ', encoding='utf-8') + self.assertEqual(self.run_cli('adopt', self.folder, path).returncode, 1) + missing = self.run_cli('adopt', self.folder, self.temporary / 'none.json') + self.assertEqual(missing.returncode, 2) + self.assertIn('cannot be read', missing.stderr) + + def test_a_broken_settings_file_stops_a_store_command(self): + (self.temporary / 'settings.json').write_text('{"format": "tuldok_settings_v1", "extra": 1}') + _, path = self.manifest(self.numbers_entry()) + with mock.patch.dict(os.environ, {local.HOME_VARIABLE: ''}): + refused = self.run_cli('adopt', self.folder, path, '--dry-run') + self.assertEqual(refused.returncode, 2) + self.assertIn(f'The settings file {self.temporary / "settings.json"} is not valid', refused.stderr) + + +class Shown(AdoptionCase): + + def test_runs_products_run_and_the_app_show_adopted(self): + _, path = self.manifest(self.numbers_entry()) + done = self.run_cli('adopt', self.folder, path) + self.assertEqual(done.returncode, 0, done.stderr) + self.assertTrue(done.stdout.startswith('Adopted 1 entry, skipped 0 that already have a product.\n' + '1 file, '), done.stdout) + run_id = self.runs()[0]['id'] + self.assertIn(f'adopted datasets/numbers 1 file', done.stdout) + self.assertIn(f'run {run_id}', done.stdout) + again = json.loads(self.run_cli('adopt', self.folder, path, '--json').stdout) + self.assertEqual((again['dry_run'], again['counts']['skip'], again['entries'][0]['action']), + (False, 1, 'skip')) + + runs = self.run_cli('runs', self.folder).stdout.splitlines() + self.assertEqual(runs[1].split()[1:4], ['datasets/numbers', '-', 'adopted']) + products = self.run_cli('products', self.folder).stdout.splitlines() + self.assertTrue(products[1].endswith('(adopted)'), products) + self.assertTrue(json.loads(self.run_cli('products', self.folder, '--json').stdout)[0]['adopted']) + shown = self.run_cli('run', self.folder, run_id).stdout + self.assertIn('none: adopted, not built here', shown) + self.assertIn('made long ago', shown) + self.assertIn('(adopted)', shown) + self.assertTrue(json.loads(self.run_cli('run', self.folder, run_id, '--json').stdout)['product']['adopted']) + self.assertIn('adopted, not built here', self.run_cli('plan', self.folder, 'datasets/numbers').stdout) + + service = Service(self.folder) + self.addCleanup(service.close) + for name, arguments in (('runs', {}), ('run', {'run': run_id}), ('products', {})): + result = service.call(name, arguments, service_base.OWNER) + self.assertTrue(set(operations.by_name(name).result) <= set(result), name) + self.assertEqual(service.call('runs', {}, service_base.OWNER)['runs'][0]['state'], 'adopted') + self.assertTrue(service.call('run', {'run': run_id}, service_base.OWNER)['product']['adopted']) + self.assertTrue(service.call('products', {}, service_base.OWNER)['products'][0]['adopted']) + self.assertTrue(service.call('plan', {'targets': ['datasets/numbers']}, service_base.OWNER)['steps'][-1]['adopted']) + + +if __name__ == '__main__': + unittest.main() diff --git a/tests/test_tuldok_project_builds.py b/tests/test_tuldok_project_builds.py index 1ad838f8..84cccbb7 100644 --- a/tests/test_tuldok_project_builds.py +++ b/tests/test_tuldok_project_builds.py @@ -83,6 +83,20 @@ def test_build_states_override_by_their_precedence(self): built = graph.states(self.documents, {'recipes/fit-b': 'built'}) self.assertEqual(built['recipes/fit-b'], 'built') # a current product wins over needs-work + def test_a_built_definition_carries_nothing_to_what_uses_it(self): + self.documents['datasets/numbers']['earlier_work'] = {'rebuild': 'no', 'reason': 'Test.'} + held = graph.states(self.documents) + self.assertEqual((held['datasets/numbers'], held['recipes/fit-a']), ('cannot-rebuild', 'cannot-rebuild')) + there = graph.states(self.documents, {'datasets/numbers': 'built'}) + self.assertEqual((there['datasets/numbers'], there['recipes/fit-a']), ('built', 'not-built')) + stale = graph.states(self.documents, {'datasets/numbers': 'out-of-date'}) + self.assertEqual((stale['datasets/numbers'], stale['recipes/fit-a']), ('out-of-date', 'cannot-rebuild')) + # Nothing passes through a built definition either: fit-b starting from a built fit-a is not held by the dataset. + self.documents['recipes/fit-b']['run']['inputs'] = {'start': 'recipes/fit-a'} + self.assertEqual(graph.states(self.documents)['recipes/fit-b'], 'cannot-rebuild') + through = graph.states(self.documents, {'recipes/fit-a': 'built'}) + self.assertEqual((through['recipes/fit-a'], through['recipes/fit-b']), ('built', 'not-built')) + def test_the_built_action_is_not_work(self): local = {'environments/test-python': 'ready', 'datasets/numbers': 'built', 'recipes/fit-a': 'out-of-date'} made = plan.make_plan(self.documents, ['recipes/fit-a'], local=local, diff --git a/tests/test_tuldok_project_environments.py b/tests/test_tuldok_project_environments.py index 5d3adc76..3396c7a5 100644 --- a/tests/test_tuldok_project_environments.py +++ b/tests/test_tuldok_project_environments.py @@ -250,7 +250,9 @@ def test_the_local_home(self): self.assertFalse(os.path.exists(os.path.join(directory, 'h'))) # nothing made by asking made = local.environments_directory('a' * 32, create=True) self.assertTrue(os.path.isdir(made)) - with mock.patch.dict(os.environ, {local.HOME_VARIABLE: ''}): + # With neither the variable nor a settings file (this machine's own is never read by a test). + with mock.patch.dict(os.environ, {local.HOME_VARIABLE: '', + local.SETTINGS_VARIABLE: os.path.join(directory, 'no-settings.json')}): self.assertEqual(local.projects_home(), os.path.expanduser('~/.local/share/tuldok/projects')) diff --git a/tests/test_tuldok_project_local.py b/tests/test_tuldok_project_local.py new file mode 100644 index 00000000..8b79bd04 --- /dev/null +++ b/tests/test_tuldok_project_local.py @@ -0,0 +1,249 @@ +"""The project directory setting, `home` and `new` (docs/plans/definition-first-projects/spec-m8.md, sections 1 and 2). + +None of these tests needs a database. Every one points TULDOK_SETTINGS at a +file in a temporary directory, so the real ~/.local/share/tuldok/settings.json +is never read or written, and every directory made is under that temporary +directory. Commands run as child processes, as a person runs them. +""" +import json +import os +from pathlib import Path +import stat +import subprocess +import sys +import tempfile +import unittest +from unittest import mock + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) + +from tuldok_project import local, store # noqa: E402 +from tuldok_project.check import check_folder # noqa: E402 + +REPOSITORY = Path(__file__).resolve().parents[1] +PROJECT_ID = 'a' * 32 + + +class SettingsCase(unittest.TestCase): + """A temporary directory, TULDOK_SETTINGS pointing into it and TULDOK_PROJECT_HOME unset.""" + + def setUp(self): + directory = tempfile.TemporaryDirectory() + self.addCleanup(directory.cleanup) + self.temporary = Path(directory.name) + self.settings = self.temporary / 'tuldok' / 'settings.json' + patcher = mock.patch.dict(os.environ, {local.SETTINGS_VARIABLE: str(self.settings)}) + patcher.start() + self.addCleanup(patcher.stop) + os.environ.pop(local.HOME_VARIABLE, None) + + def write_settings(self, value): + self.settings.parent.mkdir(parents=True, exist_ok=True) + self.settings.write_text(value if isinstance(value, str) else json.dumps(value), encoding='utf-8') + + def run_cli(self, *arguments, home=None): + environment = dict(os.environ, PYTHONDONTWRITEBYTECODE='1') + environment[local.SETTINGS_VARIABLE] = str(self.settings) + environment.pop(local.HOME_VARIABLE, None) + environment.pop('TULDOK_DATABASE_URL', None) + if home is not None: + environment[local.HOME_VARIABLE] = str(home) + return subprocess.run([sys.executable, '-m', 'tuldok_project', *map(str, arguments)], cwd=REPOSITORY, + env=environment, capture_output=True, text=True, timeout=120) + + +class Precedence(SettingsCase): + + def test_the_variable_then_the_setting_then_the_default(self): + default = os.path.expanduser('~/.local/share/tuldok/projects') + self.assertEqual(local.projects_home_source(), (default, 'default')) # no settings file + self.write_settings({'format': 'tuldok_settings_v1'}) + self.assertEqual(local.projects_home_source(), (default, 'default')) # a file without project_home + chosen = str(self.temporary / 'chosen') + self.write_settings({'format': 'tuldok_settings_v1', 'project_home': chosen}) + self.assertEqual(local.projects_home_source(), (chosen, 'settings')) + self.assertEqual(local.home(PROJECT_ID), os.path.join(chosen, PROJECT_ID)) + self.assertFalse(os.path.exists(chosen)) # working out a path makes nothing + with mock.patch.dict(os.environ, {local.HOME_VARIABLE: str(self.temporary / 'variable')}): + self.assertEqual(local.projects_home_source(), (str(self.temporary / 'variable'), 'environment')) + with mock.patch.dict(os.environ, {local.HOME_VARIABLE: ''}): # set but empty: not used + self.assertEqual(local.projects_home(), chosen) + + def test_a_broken_file_stops_and_never_falls_back(self): + broken = { + 'not JSON': '{"format": ', + 'a list': '[]', + 'a duplicate key': '{"format": "tuldok_settings_v1", "format": "tuldok_settings_v1"}', + 'NaN': '{"format": "tuldok_settings_v1", "project_home": NaN}', + 'an unknown field': {'format': 'tuldok_settings_v1', 'colour': 'red'}, + 'another format': {'format': 'tuldok_settings_v2'}, + 'no format': {'project_home': '/x'}, + 'a relative project_home': {'format': 'tuldok_settings_v1', 'project_home': 'relative/path'}, + 'a project_home that is not text': {'format': 'tuldok_settings_v1', 'project_home': 3}, + 'too large': '{"format": "tuldok_settings_v1", "project_home": "/' + 'x' * 70000 + '"}', + } + for name, value in broken.items(): + with self.subTest(name): + self.write_settings(value) + with self.assertRaises(local.SettingsError) as caught: + local.projects_home() + self.assertIn(str(self.settings), str(caught.exception)) + with self.assertRaises(local.SettingsError): + local.home(PROJECT_ID, create=True) + self.settings.unlink() + self.settings.mkdir() # a directory where the file should be: cannot be read + with self.assertRaises(local.SettingsError) as caught: + local.projects_home() + self.assertIn('cannot be read', str(caught.exception)) + + def test_the_variable_decides_without_reading_the_file(self): + self.write_settings('{"format": ') + with mock.patch.dict(os.environ, {local.HOME_VARIABLE: str(self.temporary / 'variable')}): + self.assertEqual(local.projects_home(), str(self.temporary / 'variable')) + + def test_commands_stop_with_the_message_and_status_2(self): + self.write_settings({'format': 'tuldok_settings_v1', 'extra': 1}) + shown = self.run_cli('home') + self.assertEqual(shown.returncode, 2) + self.assertEqual(shown.stdout, '') + self.assertIn(f'The settings file {self.settings} is not valid', shown.stderr) + self.assertIn("'extra'", shown.stderr) + setting = self.run_cli('home', '--set', self.temporary / 'new-home') + self.assertEqual(setting.returncode, 2) + self.assertIn('is not valid', setting.stderr) + self.assertFalse((self.temporary / 'new-home').exists()) + self.assertEqual(json.loads(self.settings.read_text())['extra'], 1) # a broken file is not replaced + + def test_the_app_ends_start_up(self): + from tuldok_project.host import ProjectHost + + self.write_settings('not json') + with self.assertRaises(store.ProjectError) as caught: + ProjectHost(self.temporary / 'data', self.temporary / 'folder') + self.assertEqual(caught.exception.code, 'settings') + self.assertIn(str(self.settings), str(caught.exception)) + self.assertFalse((self.temporary / 'data').exists()) # stopped before anything was opened + + +class Home(SettingsCase): + + def test_home_shows_the_directory_its_source_its_disk_and_its_projects(self): + chosen = self.temporary / 'chosen' + (chosen / PROJECT_ID).mkdir(parents=True) + (chosen / ('b' * 32)).mkdir() + (chosen / 'not-a-project').mkdir() + (chosen / 'gpu.lock').write_text('') + self.write_settings({'format': 'tuldok_settings_v1', 'project_home': str(chosen)}) + shown = self.run_cli('home') + self.assertEqual(shown.returncode, 0, shown.stderr) + rows = dict(line.split(None, 1) for line in shown.stdout.splitlines()) + self.assertEqual(rows['directory'], str(chosen)) + self.assertEqual(rows['from'], f'the settings file {self.settings}') + self.assertTrue(rows['free'].endswith(' on its disk'), rows['free']) + self.assertEqual(rows['projects'], '2') + listed = json.loads(self.run_cli('home', '--json').stdout) + self.assertEqual((listed['directory'], listed['source'], listed['projects'], listed['exists']), + (str(chosen), 'settings', 2, True)) + self.assertIsInstance(listed['free_bytes'], int) + variable = json.loads(self.run_cli('home', '--json', home=self.temporary / 'other').stdout) + self.assertEqual((variable['source'], variable['exists'], variable['projects']), ('environment', False, 0)) + self.assertIn('the environment variable TULDOK_PROJECT_HOME', self.run_cli('home', home=chosen).stdout) + self.settings.unlink() + self.assertIn('the default; no setting is saved in', self.run_cli('home').stdout) + + def test_set_makes_the_directory_and_writes_the_file_mode_0600(self): + chosen = self.temporary / 'disk' / 'tuldok' / 'projects' + done = self.run_cli('home', '--set', chosen) + self.assertEqual(done.returncode, 0, done.stderr) + self.assertEqual(done.stdout, f'Saved {chosen} as the project directory in {self.settings}.\n') + self.assertTrue(chosen.is_dir()) + self.assertEqual(json.loads(self.settings.read_text()), + {'format': 'tuldok_settings_v1', 'project_home': str(chosen)}) + self.assertEqual(stat.S_IMODE(os.stat(self.settings).st_mode), 0o600) + self.assertEqual(sorted(os.listdir(self.settings.parent)), ['settings.json']) # no temporary file left + self.assertEqual(local.projects_home(), str(chosen)) # what every command now uses + + def test_set_refuses_a_relative_path_and_a_directory_it_cannot_write(self): + relative = self.run_cli('home', '--set', 'relative/path') + self.assertEqual(relative.returncode, 2) + self.assertIn('is not an absolute path', relative.stderr) + self.assertFalse(self.settings.exists()) + locked = self.temporary / 'locked' + locked.mkdir(mode=0o500) + self.addCleanup(os.chmod, locked, 0o700) + if os.access(locked, os.W_OK): + self.skipTest('this user can write any directory') + refused = self.run_cli('home', '--set', locked) + self.assertEqual(refused.returncode, 2) + self.assertIn('is not a directory this user can write', refused.stderr) + self.assertFalse(self.settings.exists()) + file = self.temporary / 'a-file' + file.write_text('') + self.assertEqual(self.run_cli('home', '--set', file).returncode, 2) + + def test_set_says_when_projects_stay_behind_and_when_the_variable_overrides(self): + before = self.temporary / 'before' + (before / PROJECT_ID).mkdir(parents=True) + self.write_settings({'format': 'tuldok_settings_v1', 'project_home': str(before)}) + after = self.temporary / 'after' + done = self.run_cli('home', '--set', after) + self.assertEqual(done.returncode, 0, done.stderr) + self.assertIn(f'The directory used before, {before}, holds 1 project directory; it was not moved.', + done.stdout) + self.assertNotIn('overrides', done.stdout) + self.assertTrue((before / PROJECT_ID).is_dir()) + again = self.run_cli('home', '--set', self.temporary / 'third', home=self.temporary / 'variable') + self.assertEqual(again.returncode, 0, again.stderr) + self.assertIn('TULDOK_PROJECT_HOME is set, so it overrides this setting while it is set.', again.stdout) + self.assertNotIn('used before', again.stdout) # after holds no project directory + shown = json.loads(self.run_cli('home', '--set', after, '--json').stdout) + self.assertEqual((shown['before'], shown['before_projects'], shown['overridden']), + (str(self.temporary / 'third'), 0, False)) + + +class New(SettingsCase): + + def test_new_writes_tuldok_json_alone(self): + folder = self.temporary / 'projects' / 'mine' + made = self.run_cli('new', folder, '--name', 'My project', '--code-root', '../code') + self.assertEqual(made.returncode, 0, made.stderr) + self.assertEqual(os.listdir(folder), ['tuldok.json']) + document = json.loads((folder / 'tuldok.json').read_text()) + self.assertEqual(set(document), {'format', 'id', 'name', 'code_root'}) + self.assertEqual((document['format'], document['name'], document['code_root']), + ('tuldok_project_v1', 'My project', '../code')) + self.assertRegex(document['id'], '^[0-9a-f]{32}$') + self.assertIn(document['id'], made.stdout) + self.assertTrue(check_folder(folder, code=False).ok) + empty = self.temporary / 'empty' + empty.mkdir() + shown = json.loads(self.run_cli('new', empty, '--name', 'Another', '--json').stdout) + self.assertEqual((shown['folder'], shown['name'], shown['code_root']), (str(empty), 'Another', '.')) + self.assertNotEqual(shown['project_id'], document['id']) + self.assertEqual(json.loads((empty / 'tuldok.json').read_text())['code_root'], '.') + self.assertFalse(self.settings.exists()) # new needs no setting and writes none + + def test_new_refuses_and_makes_nothing(self): + taken = self.temporary / 'taken' + taken.mkdir() + (taken / 'notes.txt').write_text('mine') + file = self.temporary / 'file' + file.write_text('') + cases = { + 'a folder that is not empty': (taken, 'Name', '.'), + 'a file': (file, 'Name', '.'), + 'an empty name': (self.temporary / 'a', '', '.'), + 'a name too long': (self.temporary / 'b', 'n' * 121, '.'), + 'an absolute code root': (self.temporary / 'c', 'Name', '/code'), + } + for name, (folder, project_name, code_root) in cases.items(): + with self.subTest(name): + refused = self.run_cli('new', folder, '--name', project_name, '--code-root', code_root) + self.assertEqual(refused.returncode, 2, refused.stdout) + self.assertTrue(refused.stderr.strip()) + self.assertEqual(os.listdir(taken), ['notes.txt']) + self.assertEqual(sorted(os.listdir(self.temporary)), ['file', 'taken']) + + +if __name__ == '__main__': + unittest.main() diff --git a/tuldok_project/__main__.py b/tuldok_project/__main__.py index 00b3edd2..86955a51 100644 --- a/tuldok_project/__main__.py +++ b/tuldok_project/__main__.py @@ -61,6 +61,18 @@ def _parser(): check.add_argument('folder', help='the project folder (the one holding tuldok.json)') check.add_argument('--no-code', action='store_true', help='do not look up paths in the code root') check.add_argument('--json', action='store_true', help='print the report as one JSON object') + home = commands.add_parser('home', help="show the directory that holds every project's local home", + description="Show the directory that holds every project's local home, or save it " + 'as a setting with --set.') + home.add_argument('--set', metavar='PATH', help='save this absolute path as the setting; made when missing') + home.add_argument('--json', action='store_true', help='print one JSON document') + new = commands.add_parser('new', help='make a new project folder holding tuldok.json alone', + description='Make a new project folder holding tuldok.json alone.') + new.add_argument('folder', help='the folder to make; it must not exist, or be an empty directory') + new.add_argument('--name', required=True, help='the name of the project, 1 to 120 characters') + new.add_argument('--code-root', default='.', metavar='PATH', + help="the code root, relative to the folder (default '.')") + new.add_argument('--json', action='store_true', help='print one JSON document') database = argparse.ArgumentParser(add_help=False) database.add_argument('folder', help='the project folder (the one holding tuldok.json)') @@ -165,6 +177,12 @@ def add(name, parents, help_text): declining = add('decline', [opening], 'decline a build request awaiting approval') declining.add_argument('request', help='a request id, or at least its first six characters') declining.add_argument('--reason', default='', help=f'why, in at most {REASON_CHARACTERS} characters') + adopting = add('adopt', [reading], 'make existing files the products of their definitions, as a manifest says') + adopting.add_argument('manifest', help='the tuldok_adoption_v1 manifest') + adopting.add_argument('--dry-run', action='store_true', help='print what would be done; change nothing') + adopting.add_argument('--copy', action='store_true', help='copy the files instead of linking them') + adopting.add_argument('--replace', action='store_true', + help='adopt also where the definition has a current product, which stays, no longer current') add('forget', [database], "drop this project's copy from the database; the folder is not touched") return parser @@ -561,6 +579,8 @@ def _step_details(step): details.append(f'skips {len(skipped)} whose recipe is blocked: {shown}') if step['action'] == 'built' and step.get('scratch'): details.append('built by a scratch run') + if step['action'] == 'built' and step.get('adopted'): + details.append('adopted, not built here') if step['action'] == 'build' and step['state'] in ('out-of-date', 'failed', 'running'): word = {'out-of-date': 'out of date', 'failed': 'failed', 'running': 'running'}[step['state']] details += [f'{word}: {reason}' for reason in step.get('reasons', [])] or [word] @@ -718,7 +738,8 @@ def _products(project, arguments): return 0 _columns([('reference', 'subject', 'run', 'size', 'scratch', 'directory'), *((row['reference'], row['subject'] or '-', row['run_id'], _size(row['bytes']), - 'scratch' if row['scratch'] else '-', row['directory']) for row in rows)]) + 'scratch' if row['scratch'] else '-', + row['directory'] + (' (adopted)' if row['adopted'] else '')) for row in rows)]) return 0 @@ -742,15 +763,18 @@ def _run_name(row): def _show_run(row, event): import shlex + from . import builds + code = ('scratch run, the code root as it was' + (f' at commit {row["commit"][:12]}' if row['commit'] else '') - if row['scratch'] else f'commit {row["commit"][:12]}, from its snapshot') + if row['scratch'] else 'none: adopted, not built here' if row['state'] == builds.ADOPTED + else f'commit {row["commit"][:12]}, from its snapshot') builder = '-' if row['owner_pid'] is None else ( f'process {row["owner_pid"]}' + (' (running)' if row['builder_alive'] else '')) environment = row['environment'] rows = [('run', row['id']), ('reference', row['reference']), ('subject', row['subject'] or '-'), ('state', row['state']), ('plan', row['plan_id']), ('code', code), ('environment', f'{environment["reference"]} {environment["interpreter"]}' if environment else '-'), - ('command', shlex.join(row['argv'])), ('directory', row['directory']), ('builder', builder), + ('command', shlex.join(row['argv']) or '-'), ('directory', row['directory']), ('builder', builder), ('queued', _moment(row['queued_at'])), ('started', _moment(row['started_at'])), ('finished', _moment(row['finished_at'])), ('exit status', '-' if row['exit_status'] is None else row['exit_status']), @@ -762,7 +786,8 @@ def _show_run(row, event): rows.append((label, f'{used["reference"]}{output}, run {used["run_id"]}')) product = row['product'] if product is not None: - rows.append(('product', product['directory'] + ('' if product['current'] else ' (no longer current)'))) + rows.append(('product', product['directory'] + (' (adopted)' if product['adopted'] else '') + + ('' if product['current'] else ' (no longer current)'))) for name, output in sorted(product['outputs'].items()): rows.append((f'output {name}', f'{output["path"]} {output["role"]} {_size(output["bytes"])}')) rows.append(('progress', _event_words(event))) @@ -1234,12 +1259,133 @@ def _disconnect(project, arguments): return 0 +# ------------------------------------------------- the local home, new, adopt + +_SOURCE_WORDS = {'environment': 'the environment variable TULDOK_PROJECT_HOME', + 'settings': 'the settings file {settings}', 'default': 'the default; no setting is saved in {settings}'} + + +def _home(arguments): + from . import local + + if arguments.set is not None: + try: + done = local.set_project_home(arguments.set) + except ValueError as exc: + raise UsageError(f'--set {exc}') from None + if arguments.json: + _json(done) + return 0 + print(f'Saved {done["project_home"]} as the project directory in {done["settings"]}.') + count = done['before_projects'] + if count: + print(f'The directory used before, {done["before"]}, holds {count} project ' + + ('directory; it was' if count == 1 else 'directories; they were') + ' not moved.') + if done['overridden']: + print(f'{local.HOME_VARIABLE} is set, so it overrides this setting while it is set.') + return 0 + directory, source = local.projects_home_source() + shown = {'directory': directory, 'source': source, 'settings': local.settings_path(), + 'exists': os.path.isdir(directory), 'free_bytes': local.free_bytes(directory), + 'projects': local.project_directories(directory)} + if arguments.json: + _json(shown) + return 0 + free = '?' if shown['free_bytes'] is None else _size(shown['free_bytes']) + _columns([('directory', directory + ('' if shown['exists'] else ' (not made yet)')), + ('from', _SOURCE_WORDS[source].format(settings=shown['settings'])), + ('free', f'{free} on its disk'), ('projects', shown['projects'])]) + return 0 + + +def _new(arguments): + import uuid + + folder = os.path.abspath(arguments.folder) + document = {'format': documents.PROJECT_FORMAT, 'id': uuid.uuid4().hex, 'name': arguments.name, + 'code_root': arguments.code_root} + problems = documents.schema_problems('project', document) + if problems: + raise UsageError(f'The project cannot be made; its {folder_reader.PROJECT_FILE} would break the format: ' + + '; '.join(f'{pointer}: {message}' for pointer, message in problems)) + if os.path.lexists(folder) and not (os.path.isdir(folder) and not os.path.islink(folder) and not os.listdir(folder)): + raise UsageError(f'{folder} exists and is not an empty directory.') + try: + os.makedirs(folder, exist_ok=True) + with open(os.path.join(folder, folder_reader.PROJECT_FILE), 'x', encoding='utf-8') as handle: + handle.write(json.dumps(document, indent=2, ensure_ascii=False) + '\n') + except OSError as exc: + print(f'{folder} cannot be made: {exc.strerror}.', file=sys.stderr) + return 1 + if arguments.json: + _json({'folder': folder, 'project_id': document['id'], 'name': document['name'], + 'code_root': document['code_root']}) + return 0 + print(f'Made project {document["name"]} ({document["id"]}) in {folder}; it holds {folder_reader.PROJECT_FILE} ' + 'alone.') + return 0 + + +def _adoption_lines(done, dry_run): + counts = done['counts'] + entries = f'{counts["adopt"]} ' + ('entry' if counts['adopt'] == 1 else 'entries') + missing = (f'; {_plural(counts["missing"], "declared output")} ' + ('has' if counts['missing'] == 1 else 'have') + + ' no file' if counts['missing'] else '') + lines = [(f'Would adopt {entries}' if dry_run else f'Adopted {entries}') + + f', skip{"" if dry_run else "ped"} {counts["skip"]} that already ' + + ('has' if counts['skip'] == 1 else 'have') + f' a product{missing}.', + f'{_plural(counts["files"], "file")}, {_size(counts["bytes"])}: {counts["linked"]} ' + + ('to be ' if dry_run else '') + f'linked, {counts["copied"]} copied.', ''] + rows = [] + for entry in done['entries']: + if entry['action'] == 'skip': + rows.append(('skip' if dry_run else 'skipped', entry['reference'], + f'has a current product, run {entry["current_run"]}')) + continue + hows = sorted({item['how'] for item in entry['files']}) + rows.append(('adopt' if dry_run else 'adopted', entry['reference'], + f'{_plural(len(entry["files"]), "file")} {_size(entry["bytes"])} ' + + ' and '.join({'link': 'linked', 'copy': 'copied'}[how] for how in hows) + + ('' if dry_run else f' run {entry["run_id"]}'))) + rows += [('', '', f'missing: output {item["name"]} ({item["path"]})') for item in entry['missing']] + return lines, rows + + +def _adopt(project, arguments): + from . import adoption + + try: + made = adoption.make_plan(project, arguments.manifest_document, copy=arguments.copy, replace=arguments.replace) + except adoption.AdoptionError as exc: + for problem in exc.problems: + print(problem, file=sys.stderr) + print(str(exc), file=sys.stderr) + return 1 + if not arguments.dry_run: + try: + adoption.adopt(project, made) + except OSError as exc: + print(f'Adopting stopped: {exc}. The entries listed before it were adopted.', file=sys.stderr) + return 1 + if arguments.json: + _json({**made, 'dry_run': arguments.dry_run}) + return 0 + lines, rows = _adoption_lines(made, arguments.dry_run) + for line in lines: + print(line) + _columns(rows) + if arguments.dry_run: + print() + print('Nothing was changed (--dry-run).') + return 0 + + _STORE_COMMANDS = {'open': _open, 'list': _list, 'show': _show, 'graph': _graph, 'status': _status, 'set': _set, 'remove': _remove, 'save': _save, 'results': _results, 'values': _values, 'import-values': _import_values, 'chart': _chart, 'report': _report, 'plan': _plan, 'environments': _environments, 'connect': _connect, 'check-environment': _check_environment, 'set-up': _set_up, 'disconnect': _disconnect, 'runs': _runs, 'products': _products, - 'requests': _requests} + 'requests': _requests, 'adopt': _adopt} def _project_id(folder): @@ -1319,6 +1465,16 @@ def _run_store(arguments, dsn): arguments.environment = 'environments/' + _bare(arguments.environment, 'environments') if arguments.command == 'check-environment': arguments.environments = ['environments/' + _bare(name, 'environments') for name in arguments.environments] + if arguments.command == 'adopt': + from .adoption import AdoptionError, read_manifest + + try: + arguments.manifest_document = read_manifest(arguments.manifest) + except OSError as exc: + raise UsageError(f'{arguments.manifest} cannot be read: {exc.strerror}.') from None + except AdoptionError as exc: + print(str(exc), file=sys.stderr) + return 1 if arguments.command == 'plan' and not arguments.targets and not arguments.all: raise UsageError('Name at least one definition to plan, or pass --all.') # The app that serves a folder, and a build, open the project for a moment at a time: wait for them. @@ -1332,6 +1488,7 @@ def _run_store(arguments, dsn): def _database_command(arguments): import psycopg from metadata import StorageError + from .local import SettingsError from .store import ProjectError dsn = arguments.database_url or os.environ.get(DATABASE_VARIABLE) @@ -1360,6 +1517,9 @@ def _database_command(arguments): except StorageError as exc: print(f'The database setting is not usable: {exc}', file=sys.stderr) return 2 + except SettingsError as exc: + print(str(exc), file=sys.stderr) + return 2 except ProjectError as exc: print(str(exc), file=sys.stderr) for problem in exc.problems: @@ -1376,6 +1536,14 @@ def main(argv=None): arguments = _parser().parse_args(argv) # exits with status 2 on a usage error if arguments.command == 'check': return _check(arguments) + if arguments.command in ('home', 'new'): + from .local import SettingsError + + try: + return _home(arguments) if arguments.command == 'home' else _new(arguments) + except (UsageError, SettingsError) as exc: + print(str(exc), file=sys.stderr) + return 2 return _database_command(arguments) diff --git a/tuldok_project/adoption.py b/tuldok_project/adoption.py new file mode 100644 index 00000000..8d1c2627 --- /dev/null +++ b/tuldok_project/adoption.py @@ -0,0 +1,252 @@ +"""Adopting files made before Tuldok could build them as the products of their definitions. + +Owns section 3 of docs/plans/definition-first-projects/spec-m8.md. A manifest +(tuldok_adoption_v1) names, for some datasets, recipes and steps, the files +that are their outputs (or, for a definition that declares none, the +directory that is its product as a whole). read_manifest reads it; make_plan checks every entry +against the project and says what adopting would do, refusing the whole +manifest (AdoptionError, with every problem) when one entry is refused; adopt +does it: for each entry to adopt it makes /runs//output/ +holding the files as hard links to the sources (copies when a source is on +another filesystem, or always with copy), under a temporary name renamed into +place, then records a run in state adopted and its product, current. Nothing +is ever written to a source file, and no checksum is taken; the size of each +file is recorded. Adoption is a command-line action only. +""" +import errno +import os +import shutil +import stat +import uuid + +from psycopg.types.json import Jsonb + +from . import builds, documents, local + +FORMAT = 'tuldok_adoption_v1' +MANIFEST_LIMIT = 16 * 1024 * 1024 +ENTRY_LIMIT = 5000 +FILE_LIMIT = 200 +NOTE_CHARACTERS = 400 +ADOPTABLE = ('datasets', 'recipes', 'steps') +_TOP_FIELDS = ('format', 'products') +_ENTRY_FIELDS = ('reference', 'note', 'files') + + +class AdoptionError(Exception): + """A manifest that is refused; problems lists every reason, and nothing was adopted.""" + + def __init__(self, message, problems=()): + super().__init__(message) + self.problems = list(problems) + + +def read_manifest(path): + """The manifest's object; OSError when it cannot be read, AdoptionError when it is not strict JSON or too large.""" + with open(path, 'rb') as handle: + raw = handle.read(MANIFEST_LIMIT + 1) + if len(raw) > MANIFEST_LIMIT: + raise AdoptionError(f'The manifest {path} is larger than {MANIFEST_LIMIT // 1024 // 1024} MiB.') + try: + return documents.decode(raw) + except documents.DocumentError as exc: + raise AdoptionError(f'The manifest {path} is not valid: {exc}') from None + + +def _under(path, output): + return path == output or path.startswith(output + '/') + + +def _device(path): + """st_dev of path, or of its nearest existing parent.""" + while not os.path.exists(path) and os.path.dirname(path) != path: + path = os.path.dirname(path) + return os.stat(path).st_dev + + +def _check_files(files, declared, where, problems): + """[(key, source, bytes, st_dev)] of an entry's files; problems gains a line for each one refused. + + A key must lie under one of the declared outputs; a definition that + declares none has the directory as a whole as its product, and any key in + normal form is accepted. + """ + found = [] + if not isinstance(files, dict) or not 1 <= len(files) <= FILE_LIMIT: + problems.append(f'{where}: files must be an object of 1 to {FILE_LIMIT} entries.') + return found + keys = sorted(files) + for key in keys: + source = files[key] + wrong = documents.relative_path_problem(key) + if wrong is not None: + problems.append(f'{where}: the key {key!r} {wrong}.') + continue + if declared and not any(_under(key, output['path']) for output in declared.values()): + problems.append(f'{where}: {key} is not a declared output of the definition, nor under one.') + continue + if any(other != key and _under(other, key) for other in keys): + problems.append(f'{where}: {key} is a file, so nothing can be under it.') + continue + if not isinstance(source, str) or not os.path.isabs(source) or '\x00' in source: + problems.append(f'{where}: the source of {key} must be an absolute path.') + continue + try: + status = os.lstat(source) + except OSError as exc: + problems.append(f'{where}: the source of {key}, {source}, cannot be read: {exc.strerror}.') + continue + if stat.S_ISLNK(status.st_mode): + problems.append(f'{where}: the source of {key}, {source}, is a link; name the file itself.') + elif not stat.S_ISREG(status.st_mode): + problems.append(f'{where}: the source of {key}, {source}, is not a regular file.') + elif not os.access(source, os.R_OK): + problems.append(f'{where}: the source of {key}, {source}, cannot be read by this user.') + else: + found.append((key, source, status.st_size, status.st_dev)) + return found + + +def make_plan(project, manifest, *, copy=False, replace=False): + """What adopting manifest would do in the open project; raises AdoptionError when an entry is refused. + + Returns {entries: [{reference, action (adopt or skip), note, files: [{path, + source, bytes, how (link or copy)}], outputs: {name: {path, role, bytes}}, + missing: [{name, path}], bytes, current_run}], counts: {adopt, skip, + missing, files, bytes, linked, copied}, copy, replace}. An entry whose + definition has a current product is skipped unless replace. Nothing is + read but the manifest, the definitions and the sources' metadata. + """ + problems = [] + unknown = sorted(set(manifest) - set(_TOP_FIELDS)) + if unknown: + problems.append(f'The manifest has the unknown field {unknown[0]!r}.') + if manifest.get('format') != FORMAT: + problems.append(f'The manifest\'s format must be "{FORMAT}".') + products = manifest.get('products') + if not isinstance(products, list) or not 1 <= len(products) <= ENTRY_LIMIT: + problems.append(f'products must be a list of 1 to {ENTRY_LIMIT} entries.') + products = [] + definitions = project._documents(removed=False) + target = _device(os.path.join(local.home(project.project_id), builds.RUNS)) + seen, entries = set(), [] + for index, entry in enumerate(products): + where = f'products[{index}]' + if not isinstance(entry, dict): + problems.append(f'{where} must be an object.') + continue + reference = entry.get('reference') + where += f' ({reference})' if isinstance(reference, str) else '' + unknown = sorted(set(entry) - set(_ENTRY_FIELDS)) + if unknown: + problems.append(f'{where}: the unknown field {unknown[0]!r}.') + parsed = documents.parse_reference(reference) + if parsed is None: + problems.append(f'{where}: reference must be a reference such as recipes/.') + continue + if reference in seen: + problems.append(f'{where}: {reference} appears more than once.') + continue + seen.add(reference) + if parsed[0] not in ADOPTABLE: + problems.append(f'{where}: only a dataset, recipe or step can be adopted.') + continue + if reference not in definitions: + problems.append(f'{where}: there is no definition {reference}.') + continue + note = entry.get('note') + if 'note' in entry and not (isinstance(note, str) and 1 <= len(note) <= NOTE_CHARACTERS): + problems.append(f'{where}: note must be 1 to {NOTE_CHARACTERS} characters.') + outputs = builds._run_block(definitions[reference]).get('outputs') + declared = {name: output for name, output in (outputs.items() if isinstance(outputs, dict) else ()) + if isinstance(output, dict) and isinstance(output.get('path'), str)} + files = _check_files(entry.get('files'), declared, where, problems) + if not isinstance(entry.get('files'), dict) or len(files) != len(entry['files']): + continue + sizes = {} + for key, _source, size, _device_ in files: + for name, output in declared.items(): + if _under(key, output['path']): + sizes[name] = sizes.get(name, 0) + size + # Every key lies under a declared output (when there are any) and files is not empty, so an entry + # whose definition declares outputs always has a file for at least one of them. + current = builds._current_product(project, reference) + entries.append({ + 'reference': reference, 'note': note, + 'action': 'skip' if current is not None and not replace else 'adopt', + 'current_run': current and current['run_id'], + 'files': [{'path': key, 'source': source, 'bytes': size, + 'how': 'copy' if copy or device != target else 'link'} + for key, source, size, device in files], + 'outputs': {name: {'path': output['path'], 'role': output.get('role'), 'bytes': sizes[name]} + for name, output in declared.items() if name in sizes}, + 'missing': [{'name': name, 'path': output['path']} for name, output in declared.items() + if name not in sizes], + 'bytes': sum(size for _key, _source, size, _device_ in files)}) + if problems: + raise AdoptionError(f'Nothing was adopted: {len(problems)} problem' + ('' if len(problems) == 1 else 's') + + ' in the manifest.', problems) + adopting = [entry for entry in entries if entry['action'] == 'adopt'] + files = [item for entry in adopting for item in entry['files']] + return {'entries': entries, 'copy': copy, 'replace': replace, + 'counts': {'adopt': len(adopting), 'skip': len(entries) - len(adopting), + 'missing': sum(len(entry['missing']) for entry in adopting), 'files': len(files), + 'bytes': sum(item['bytes'] for item in files), + 'linked': sum(item['how'] == 'link' for item in files), + 'copied': sum(item['how'] == 'copy' for item in files)}} + + +def _place(source, target, how): + """Link (or copy) source to target; return how it was done. A link across filesystems becomes a copy.""" + os.makedirs(os.path.dirname(target), exist_ok=True) + if how == 'link': + try: + os.link(source, target, follow_symlinks=False) + return 'link' + except OSError as exc: + if exc.errno != errno.EXDEV: + raise + shutil.copyfile(source, target, follow_symlinks=False) + return 'copy' + + +def adopt(project, plan): + """Do what plan (make_plan's result) says, entry by entry; return plan with run_id and directory per adopted entry. + + Each entry's directory is complete and renamed into place before its run + and product are recorded in one transaction; a product that was current + stays in the database, no longer current. The counts linked and copied + say what was done. + """ + runs = os.path.join(local.home(project.project_id, create=True), builds.RUNS) + os.makedirs(runs, exist_ok=True) + for entry in plan['entries']: + if entry['action'] != 'adopt': + continue + run_id = uuid.uuid4().hex + directory = os.path.join(runs, run_id) + temporary = os.path.join(runs, f'.{run_id}.adopting') + for item in entry['files']: + item['how'] = _place(item['source'], os.path.join(temporary, builds.OUTPUT, item['path']), item['how']) + os.rename(temporary, directory) + output = os.path.join(directory, builds.OUTPUT) + with project._connection.transaction(): + project._execute('''INSERT INTO {schema}.runs (id, reference, subject, plan_id, state, scratch, commit, + definition, settings, inputs, environment, argv, env, directory, queued_at, + started_at, finished_at, bytes, problem) + SELECT %s, %s, '', '', %s, false, '', text, NULL, '{{}}'::jsonb, NULL, + '[]'::jsonb, '{{}}'::jsonb, %s, now(), now(), now(), %s, %s + FROM {schema}.definitions + WHERE directory || '/' || name = %s AND NOT removed''', + (run_id, entry['reference'], builds.ADOPTED, directory, entry['bytes'], entry['note'], + entry['reference'])) + project._execute('UPDATE {schema}.products SET current = false ' + "WHERE reference = %s AND subject = '' AND current", (entry['reference'],)) + project._execute("INSERT INTO {schema}.products (run_id, reference, subject, directory, outputs, current) " + "VALUES (%s, %s, '', %s, %s, true)", + (run_id, entry['reference'], output, Jsonb(entry['outputs']))) + entry.update(run_id=run_id, directory=output) + files = [item for entry in plan['entries'] if entry['action'] == 'adopt' for item in entry['files']] + plan['counts'].update(linked=sum(item['how'] == 'link' for item in files), + copied=sum(item['how'] == 'copy' for item in files)) + return plan diff --git a/tuldok_project/builds.py b/tuldok_project/builds.py index 72bd5a6d..d84b0068 100644 --- a/tuldok_project/builds.py +++ b/tuldok_project/builds.py @@ -14,7 +14,10 @@ outputs, import a benchmark's results and record the product. A run left queued or running by a builder that is gone becomes unknown whenever builds are looked at; nothing is ever restarted. Files are never deleted here, -except an estimate's throwaway directory. +except an estimate's throwaway directory. A run in state adopted ran +nothing: adoption.py recorded files made elsewhere as its product, and +status counts that product built without comparing anything (spec-m8.md +section 3); a later build replaces it like any other. What a person needs while and after a build runs (sections 7 and 8): a run is named by its id or an unambiguous prefix of it (find_run); run_details reads @@ -50,6 +53,7 @@ BUILT_KINDS = ('dataset', 'recipe', 'step', 'benchmark') ACTIVE = ('queued', 'running') ENDED_BADLY = ('failed', 'timed-out', 'over-disk', 'unknown') +ADOPTED = 'adopted' # the state of a run that adopted files made elsewhere (adoption.py) DEFAULT_WALL_HOURS = 24 DEFAULT_DISK_GB = 50 GB = 1000 ** 3 @@ -278,12 +282,15 @@ def _own_causes(document, text, product, current, changes, code_root): def status(project): - """{reference: {state, causes, scratch, subjects}} for every dataset, recipe, step and benchmark with runs or products. + """{reference: {state, causes, scratch, adopted, subjects}} for every dataset, recipe, step and benchmark with runs or products. state is running, built, out-of-date or failed (section 5); a definition absent from the result has none of them. causes are sentences saying why it is out of date or failed. For a benchmark, subjects maps each subject - that would run to its own {state, causes, run_id}. + that would run to its own {state, causes, run_id}. A definition whose + current product was adopted (adoption.py) is built and adopted, and is + never out of date: nothing of it is compared. A subject whose recipe has a + current product would run even when the recipe's label holds it. """ connection, schema = project._connection, project.schema if connection.execute(_q(schema, 'SELECT NOT EXISTS (SELECT 1 FROM {schema}.runs)')).fetchone()[0]: @@ -294,12 +301,13 @@ def status(project): texts = {reference: text for reference, text, _ in rows} definitions = {reference: document for reference, _, document in rows} current = {} - for (run_id, reference, subject, outputs, scratch, commit, definition, settings, inputs) in connection.execute(_q( + for (run_id, reference, subject, outputs, scratch, commit, definition, settings, inputs, state) in connection.execute(_q( schema, '''SELECT p.run_id, p.reference, p.subject, p.outputs, r.scratch, r.commit, r.definition, - r.settings, r.inputs + r.settings, r.inputs, r.state FROM {schema}.products p JOIN {schema}.runs r ON r.id = p.run_id WHERE p.current''')): current[reference, subject] = {'run_id': run_id, 'outputs': outputs, 'scratch': scratch, 'commit': commit, - 'definition': definition, 'settings': settings, 'inputs': inputs} + 'definition': definition, 'settings': settings, 'inputs': inputs, + 'adopted': state == ADOPTED} latest = {reference: (run_id, state, problem) for reference, run_id, state, problem in connection.execute(_q( schema, '''SELECT DISTINCT ON (reference) reference, id, state, problem FROM {schema}.runs ORDER BY reference, queued_at DESC, id''')).fetchall()} @@ -308,7 +316,7 @@ def status(project): code_root = _code_root(project) if current else None changes = _changes(code_root, {product['commit'] for product in current.values() if not product['scratch'] and product['commit']}) if current else {} - held = graph.states(definitions) + held = graph.states(definitions, {reference: 'built' for reference, subject in current if not subject}) found = {} out_of_date = set() @@ -317,13 +325,15 @@ def judge(reference, document, subject=None): product = current.get((reference, subject['name'] if subject else '')) if product is None: return None + if product['adopted']: + return {'state': 'built', 'causes': [], 'run_id': product['run_id'], 'scratch': False, 'adopted': True} product = {**product, 'subject_document': subject} causes = _own_causes(document, texts[reference], product, current, changes, code_root) for key, used in _uses(document, subject).items(): if used in out_of_date and not any(cause.startswith(_input_words(key, used)) for cause in causes): causes.append(f'{_input_words(key, used)} is out of date') return {'state': 'out-of-date' if causes else 'built', 'causes': causes, 'run_id': product['run_id'], - 'scratch': product['scratch']} + 'scratch': product['scratch'], 'adopted': False} for reference in graph.order(definitions): if reference not in definitions or _kind(reference) not in BUILT_KINDS: @@ -335,7 +345,7 @@ def judge(reference, document, subject=None): judged = {name: item for name, item in subjects.items() if item is not None} entry = {'subjects': {name: item or {'state': 'not-built', 'causes': [], 'run_id': None, 'scratch': False} for name, item in subjects.items()}, - 'scratch': any(item['scratch'] for item in judged.values())} + 'scratch': any(item['scratch'] for item in judged.values()), 'adopted': False} if not subjects or not judged: entry.update(state=None, causes=[]) elif len(judged) == len(subjects) and all(item['state'] == 'built' for item in judged.values()): @@ -348,6 +358,7 @@ def judge(reference, document, subject=None): else: judged = judge(reference, document) entry = {'subjects': None, 'scratch': bool(judged and judged['scratch']), + 'adopted': bool(judged and judged['adopted']), 'state': judged and judged['state'], 'causes': judged['causes'] if judged else []} if entry['state'] is None and reference in latest and latest[reference][1] in ENDED_BADLY: run_id, state, problem = latest[reference] @@ -383,9 +394,10 @@ def runs(project, reference=None): def products(project, reference=None): - """The current products, by reference and subject: run, size of the declared outputs, directory, scratch.""" + """The current products, by reference and subject: run, size of the declared outputs, directory, scratch, adopted.""" reap_orphans(project._connection, project.schema) - query = '''SELECT p.reference, p.subject, p.run_id, p.directory, p.outputs, r.scratch, r.commit, r.finished_at + query = '''SELECT p.reference, p.subject, p.run_id, p.directory, p.outputs, r.scratch, r.commit, r.finished_at, + r.state FROM {schema}.products p JOIN {schema}.runs r ON r.id = p.run_id WHERE p.current''' parameters = () if reference is not None: @@ -393,11 +405,11 @@ def products(project, reference=None): parameters = (reference,) query += ' ORDER BY p.reference, p.subject' found = [] - for reference_, subject, run_id, directory, outputs, scratch, commit, finished in project._execute( + for reference_, subject, run_id, directory, outputs, scratch, commit, finished, state in project._execute( query, parameters).fetchall(): found.append({'reference': reference_, 'subject': subject, 'run_id': run_id, 'directory': directory, 'outputs': outputs, 'bytes': sum(item.get('bytes') or 0 for item in outputs.values()), - 'scratch': scratch, 'commit': commit, 'finished_at': finished}) + 'scratch': scratch, 'commit': commit, 'finished_at': finished, 'adopted': state == ADOPTED}) return found @@ -957,7 +969,8 @@ def run_details(project, text): row = _row(project, run_id) product = project._execute('SELECT directory, outputs, current FROM {schema}.products WHERE run_id = %s', (run_id,)).fetchone() - row['product'] = None if product is None else dict(zip(('directory', 'outputs', 'current'), product)) + row['product'] = None if product is None else {**dict(zip(('directory', 'outputs', 'current'), product)), + 'adopted': row['state'] == ADOPTED} row['builder_alive'] = row['state'] in ACTIVE and builder_alive(row) return row diff --git a/tuldok_project/graph.py b/tuldok_project/graph.py index fa3d0669..a35e59e4 100644 --- a/tuldok_project/graph.py +++ b/tuldok_project/graph.py @@ -210,8 +210,11 @@ def states(definitions, local=None): cannot-rebuild and needs-work come from a definition's own earlier_work.rebuild or from anything it uses through input edges, directly - or further up; the worse of the two wins. Other edges (environment, model, - subjects, cases, chart) carry nothing. Otherwise the state follows the + or further up; the worse of the two wins. A definition that local says is + built carries nothing to what uses it, and nothing through it: its product + is on this machine to be used, whether it was built here or adopted + (spec-m8.md section 3). Other edges (environment, model, subjects, cases, + chart) carry nothing. Otherwise the state follows the kind. The table is read in order, so a model marked rebuild "no" is cannot-rebuild, not none. Cycles are tolerated: the result is the fixed point. """ @@ -224,12 +227,15 @@ def states(definitions, local=None): for edge in edges(definitions): if edge.role.startswith('input:') and edge.to_ref in users: users[edge.to_ref].append(edge.from_ref) + built_here = {reference for reference, state in (local or {}).items() + if state == 'built' and reference in definitions + and _kind(reference, definitions[reference]) in _BUILT} # Severity only rises, at most twice per definition, so this ends even on a cycle. - pending = [reference for reference, value in severity.items() if value] + pending = [reference for reference, value in severity.items() if value and reference not in built_here] while pending: reference = pending.pop() for user in users[reference]: - if severity[user] < severity[reference]: + if user not in built_here and severity[user] < severity[reference]: severity[user] = severity[reference] pending.append(user) found = {reference: _CARRIED[severity[reference]] or _BASE_STATE.get(_kind(reference, document), 'none') diff --git a/tuldok_project/host.py b/tuldok_project/host.py index 187d8be3..8b9acdda 100644 --- a/tuldok_project/host.py +++ b/tuldok_project/host.py @@ -15,7 +15,7 @@ from access import Access, AccessError from metadata import Metadata -from . import operations, store +from . import local, operations, store from .service import Service REFUSAL_PROBLEMS = 50 @@ -40,7 +40,16 @@ class ProjectHost: project_folder_mode = True def __init__(self, data_path, folder, *, dsn=None): - """Open the catalog of data_path and the folder, and start the build worker; raises ProjectError.""" + """Open the catalog of data_path and the folder, and start the build worker; raises ProjectError. + + A settings file that is not valid (local.SettingsError) is raised as + ProjectError code settings before anything is opened, so app.py ends + start-up with its message. + """ + try: + local.projects_home() + except local.SettingsError as error: + raise store.ProjectError(str(error), 'settings') from None self.path = Path(data_path).resolve() self.db = Metadata(self.path, dsn=dsn) self.lock = self.db.lock @@ -70,6 +79,8 @@ def dispatch(self, name, arguments): return 200, self.service.call(name, arguments, actor) except store.ProjectError as error: return refusal(error) + except local.SettingsError as error: # the settings file broke while the app runs + return refusal(store.ProjectError(str(error), 'settings')) def _require(self, who, action): if who == 'owner': diff --git a/tuldok_project/local.py b/tuldok_project/local.py index 6c550def..5b64511a 100644 --- a/tuldok_project/local.py +++ b/tuldok_project/local.py @@ -1,23 +1,150 @@ -"""Where a project keeps what belongs to this machine alone: its local home. - -Owns section 1 of docs/plans/definition-first-projects/spec-m5.md. The local -home of a project is $TULDOK_PROJECT_HOME//, with -TULDOK_PROJECT_HOME defaulting to ~/.local/share/tuldok/projects. Nothing in -it is part of the project folder. Environments that Tuldok installs go to -/environments//. Working out a path never creates anything; -a directory is made only when a caller asks for it with create=True. +"""Where a project keeps what belongs to this machine alone: its local home, and the setting that places it. + +Owns section 1 of docs/plans/definition-first-projects/spec-m5.md and section 1 +of spec-m8.md. The local home of a project is //. +The projects home is, first that applies: $TULDOK_PROJECT_HOME when set and +not empty; project_home of the settings file (~/.local/share/tuldok/settings.json, +or the file $TULDOK_SETTINGS names); ~/.local/share/tuldok/projects. The +settings file is read only when the variable does not decide, and a file that +cannot be read or is not valid raises SettingsError: it never falls back to +the default. Nothing in a local home is part of the project folder. +Environments that Tuldok installs go to /environments//. +Working out a path never creates anything; a directory is made only when a +caller asks for it with create=True, or by set_project_home. """ +import json import os +import re +import shutil +import tempfile + +from . import documents HOME_VARIABLE = 'TULDOK_PROJECT_HOME' +SETTINGS_VARIABLE = 'TULDOK_SETTINGS' DEFAULT_HOME = os.path.join('~', '.local', 'share', 'tuldok', 'projects') +DEFAULT_SETTINGS = os.path.join('~', '.local', 'share', 'tuldok', 'settings.json') +SETTINGS_FORMAT = 'tuldok_settings_v1' +SETTINGS_LIMIT = 64 * 1024 +SETTINGS_FIELDS = ('format', 'project_home') ENVIRONMENTS = 'environments' +_PROJECT_DIRECTORY = re.compile(r'^[a-f0-9]{32}$') + + +class SettingsError(Exception): + """The settings file cannot be read or is not valid; the message names the file and the fault.""" + + +def settings_path(): + """The settings file: $TULDOK_SETTINGS when set and not empty, else ~/.local/share/tuldok/settings.json.""" + return os.path.abspath(os.path.expanduser(os.environ.get(SETTINGS_VARIABLE) or DEFAULT_SETTINGS)) + + +def read_settings(): + """The settings file's object; {} when there is no file. Raises SettingsError for anything else wrong.""" + path = settings_path() + try: + with open(path, 'rb') as handle: + raw = handle.read(SETTINGS_LIMIT + 1) + except FileNotFoundError: + return {} + except OSError as exc: + raise SettingsError(f'The settings file {path} cannot be read: {exc.strerror}.') from None + if len(raw) > SETTINGS_LIMIT: + raise SettingsError(f'The settings file {path} is larger than {SETTINGS_LIMIT // 1024} KiB.') + try: + settings = documents.decode(raw) + except documents.DocumentError as exc: + raise SettingsError(f'The settings file {path} is not valid: {exc}') from None + unknown = sorted(set(settings) - set(SETTINGS_FIELDS)) + if unknown: + raise SettingsError(f'The settings file {path} is not valid: it has the unknown field {unknown[0]!r}.') + if settings.get('format') != SETTINGS_FORMAT: + raise SettingsError(f'The settings file {path} is not valid: its format must be "{SETTINGS_FORMAT}".') + home = settings.get('project_home') + if 'project_home' in settings and not (isinstance(home, str) and os.path.isabs(home) and '\x00' not in home): + raise SettingsError(f'The settings file {path} is not valid: its project_home must be an absolute path.') + return settings + + +def projects_home_source(): + """(the directory that holds every project's local home, where it came from: environment, settings or default).""" + configured = os.environ.get(HOME_VARIABLE) + if configured: + return os.path.abspath(os.path.expanduser(configured)), 'environment' + settings = read_settings() + if 'project_home' in settings: + return os.path.normpath(settings['project_home']), 'settings' + return os.path.abspath(os.path.expanduser(DEFAULT_HOME)), 'default' def projects_home(): - """The directory that holds every project's local home, as an absolute path.""" - configured = os.environ.get(HOME_VARIABLE) or DEFAULT_HOME - return os.path.abspath(os.path.expanduser(configured)) + """The directory that holds every project's local home, as an absolute path; raises SettingsError.""" + return projects_home_source()[0] + + +def project_directories(path): + """How many project directories (named by a project id) path holds; 0 when it cannot be listed.""" + try: + with os.scandir(path) as entries: + return sum(1 for entry in entries + if _PROJECT_DIRECTORY.fullmatch(entry.name) and entry.is_dir(follow_symlinks=False)) + except OSError: + return 0 + + +def free_bytes(path): + """The free bytes on the disk of path, or of its nearest existing parent; None when that cannot be told.""" + while not os.path.exists(path) and os.path.dirname(path) != path: + path = os.path.dirname(path) + try: + return shutil.disk_usage(path).free + except OSError: + return None + + +def set_project_home(path): + """Save path as project_home in the settings file; return {project_home, settings, before, before_projects, overridden}. + + path must be absolute (ValueError otherwise). It is made with its parents + when missing and must then be a directory this user can write (ValueError). + A settings file that is not valid is not replaced (SettingsError). The file + is written through a temporary file renamed into place, mode 0600. before is + the directory the settings file or the default gave until now (the + variable aside), before_projects how many project directories it holds + (they are not moved), and overridden whether TULDOK_PROJECT_HOME is set and + so overrides the setting. + """ + if not isinstance(path, str) or not os.path.isabs(path): + raise ValueError(f'{path!r} is not an absolute path.') + path = os.path.normpath(path) + settings = read_settings() + before = (os.path.normpath(settings['project_home']) if 'project_home' in settings + else os.path.abspath(os.path.expanduser(DEFAULT_HOME))) + try: + os.makedirs(path, exist_ok=True) + except OSError as exc: + raise ValueError(f'{path} cannot be made: {exc.strerror}.') from None + if not os.path.isdir(path) or not os.access(path, os.W_OK | os.X_OK): + raise ValueError(f'{path} is not a directory this user can write.') + file = settings_path() + os.makedirs(os.path.dirname(file), exist_ok=True) + text = json.dumps({**settings, 'format': SETTINGS_FORMAT, 'project_home': path}, indent=2, ensure_ascii=False) + '\n' + descriptor, temporary = tempfile.mkstemp(prefix='.settings.', suffix='.tmp', dir=os.path.dirname(file)) + try: + with os.fdopen(descriptor, 'w', encoding='utf-8') as handle: + os.fchmod(handle.fileno(), 0o600) + handle.write(text) + os.replace(temporary, file) + except BaseException: + try: + os.unlink(temporary) + except OSError: + pass + raise + return {'project_home': path, 'settings': file, 'before': before, + 'before_projects': project_directories(before) if before != path else 0, + 'overridden': bool(os.environ.get(HOME_VARIABLE))} def home(project_id, *, create=False): diff --git a/tuldok_project/plan.py b/tuldok_project/plan.py index 76737469..ac8c138a 100644 --- a/tuldok_project/plan.py +++ b/tuldok_project/plan.py @@ -63,12 +63,13 @@ def _held(state): return state in ('cannot-rebuild', 'needs-work') -def _closure(definitions, edges_from, states, starts): +def _closure(definitions, edges_from, states, starts, adopted=frozenset()): """Every definition reached from starts, starts included (section 2 of spec-m4.md). Input and environment edges are followed; a subject edge only when its - recipe is not blocked. Nothing is followed out of a blocked definition, nor - out of a benchmark with no subject to run. + recipe is not blocked. Nothing is followed out of a blocked definition, out + of a benchmark with no subject to run, nor out of a definition whose + current product was adopted (it needs nothing it uses: spec-m8.md section 3). """ seen, pending = set(), list(starts) while pending: @@ -76,7 +77,7 @@ def _closure(definitions, edges_from, states, starts): if reference in seen or reference not in definitions: continue seen.add(reference) - if _held(states[reference]): + if _held(states[reference]) or (reference in adopted and states[reference] == 'built'): continue if _kind(reference) == 'benchmark' and not _subjects(definitions[reference], states)['run']: continue @@ -208,8 +209,9 @@ def make_plan(definitions, targets, *, every=False, local=None, built=None, esti if reference not in resolved: resolved.append(reference) states = graph.states(definitions, local) + adopted = {reference for reference, entry in (built or {}).items() if entry.get('adopted')} members = _closure(definitions, edges_from, states, - [reference for reference in resolved if _kind(reference) != 'model']) + [reference for reference in resolved if _kind(reference) != 'model'], adopted) members = {reference for reference in members if _kind(reference) not in ('model', 'chart')} ordered = graph.order({reference: definitions[reference] for reference in members}) actions = {reference: _action(_kind(reference), states[reference]) for reference in ordered} @@ -226,7 +228,8 @@ def make_plan(definitions, targets, *, every=False, local=None, built=None, esti 'estimate': (estimates or {}).get(reference), 'blocked_by': [], 'blocked_by_more': 0, 'reasons': list((built or {}).get(reference, {}).get('causes', [])), - 'scratch': bool((built or {}).get(reference, {}).get('scratch', False))} + 'scratch': bool((built or {}).get(reference, {}).get('scratch', False)), + 'adopted': reference in adopted} if kind == 'benchmark': step['subjects'] = _subjects(document, states) if action == 'build' and not step['subjects']['run']: diff --git a/tuldok_project/store.py b/tuldok_project/store.py index c8e2a998..3c8ec28a 100644 --- a/tuldok_project/store.py +++ b/tuldok_project/store.py @@ -87,8 +87,8 @@ class ProjectError(Exception): environments (environments.py): not-set-up (nothing is recorded for it), no-install, no-installer, target-exists, install-failed; and for builds (builds.py): blocked, running, not-ready, and a snapshot.SnapshotError's - code (dirty, not-in-git, ...), whose files names the changed files. - references names the definitions concerned. + code (dirty, not-in-git, ...), whose files names the changed files; and + settings, which host.py raises for a local.SettingsError. references names the definitions concerned. """ def __init__(self, message, code, *, problems=(), references=(), files=()): @@ -793,7 +793,17 @@ def results_overview(self): return result_rows.overview(self._connection, self.schema) def close(self): - """Close the connection, which also releases the project's lock.""" + """Release the project's lock, then close the connection. + + The lock is released by a statement, so the project can be opened + again the moment this returns. Closing alone would leave it held + until the server noticed the session had ended. + """ + try: + if not self._connection.closed: + self._connection.execute('SELECT pg_advisory_unlock(%s)', (_lock_key(self.schema),)) + except psycopg.Error: + pass # a connection that is already broken gives the lock up when the server ends its session self._connection.close() def __enter__(self): From a6b118a41873b934bc6acb57e0d326e828b28f57 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 12 Nov 2026 08:54:07 -0700 Subject: [PATCH 034/131] docs(plan): record milestone 8 part 1 in the ledger Co-Authored-By: Claude Fable 5.2 --- .../execution-ledger.md | 56 +++++++++++++++++++ 1 file changed, 56 insertions(+) diff --git a/docs/plans/definition-first-projects/execution-ledger.md b/docs/plans/definition-first-projects/execution-ledger.md index 5dce90c3..d76dc186 100644 --- a/docs/plans/definition-first-projects/execution-ledger.md +++ b/docs/plans/definition-first-projects/execution-ledger.md @@ -301,3 +301,59 @@ All Tuldok project tests: 482, about 3 minutes. The 14 existing agent and contra - Carried over: the values file's `commit` is empty; nothing is ever deleted from the local home; installing an environment and measuring estimates are command-line only; the catalog queue does not take the GPU lock (spec section 9). **Next:** milestone 8, converting the lab for good and retiring the old project-files code. It needs the owner's two open decisions (where the product archive for the earlier weights goes; which earlier models to drop) and sign-off of the written capability check before any old module is deleted. + +## 2026-11-12 — milestone 8, part 1: where products live, and adopting the earlier ones + +**Owner decisions:** "The model weights can stay with tuldok on the loca system. Tuldok should have an internal proj dir to store per project data including the weights. We do not want the weights in the git repo." Then: "yes make orangcream tuldoks project location." Then: "continue". No product archive is built. Spec: [spec-m8.md](spec-m8.md); the [capability check](capability-check.md) was written the same day and is not signed. + +**Commits** (none pushed). Tuldok `feat/definition-first-projects`: the decision and the capability check `5a52bed5`; spec `1a9b9e73`; the setting, `new` and `adopt` `3af6b6a6`. Lab `reorg/reproducible-lab-20261102`: the adoption manifest `6dac9a160`. + +| Slice | What | Tests | +| --- | --- | --- | +| T16 | `tuldok_project/local.py` (the saved setting), `adoption.py`, the adopted rule in `builds.py` and `plan.py`, the commands `home`, `new`, `adopt` | 24 | +| L4 | `lab:scripts/build_tuldok_project.py --adoption-output` | 40 in the lab's converter tests | + +All Tuldok project tests: 507, about 4.5 minutes. + +**Changed in review:** + +- A definition that is built on this machine no longer carries `cannot-rebuild` or `needs-work` to what uses it. As implemented first, a new recipe could not use an adopted dataset as its input, which is what adoption is for. +- Closing a project now releases its lock by a statement. A full test run on a busy machine failed once with "already open" straight after a close; the lock had been left to the server to release when it noticed the session end. +- One existing test read the machine's settings file. The whole suite was then run with a decoy settings file in the environment: every test passed and nothing was written to the decoy directory, so no test can write into the real project directory. +- The spec was widened during the work: a definition that declares no outputs can be adopted as a whole directory. The lab's manifest showed why: the earlier weights are 0.8 GB, and 15 GB of the old folder is training data of 25 earlier datasets, which declare no outputs. + +**What the old folder holds** (`projects/rheon-model-portfolio-unified-04/artifacts/sha256/`, 8,734 files, 16.5 GB, ignored by Git), by the lab's manifest: + +| Part | Files | Size | +| --- | --- | --- | +| Outputs of 203 earlier recipes (weights, histories, receipts) | 2,264 distinct | 0.79 GB | +| Training data of 25 earlier datasets | 177 distinct, 34 of them also a recipe's output | 15.08 GB | +| Named by no entry: old-format records, staged code, custody proofs, outputs of runs with no recipe | 6,327 | 0.69 GB | + +Every declared output of the 203 recipes was found at its recorded size; no dataset path was claimed by two different files. Two earlier recipes have no run and five earlier datasets were read by no recipe, so those seven have nothing to adopt. + +**Acceptance on a throwaway database**, with a throwaway project directory on the OrangeCream disk: + +| Step | Result | +| --- | --- | +| `adopt --dry-run` | would adopt 228 entries, 3,841 files, 16.9 GB, all to be linked; nothing changed | +| `adopt` | 228 adopted in 1.6 s; free space on the disk fell by 2.8 MB | +| The files | all 3,841 are hard links to files of the old folder, 2,407 distinct | +| States | before: 216 cannot rebuild, 27 need work, 17 not built. After: 228 built, 23 cannot rebuild, 9 not built | +| `plan --all` | before: 17 to build, 243 blocked. After: 9 to build, 23 blocked, 228 built | +| A second `adopt` | skipped all 228 | +| Removing the throwaway directory | the old folder still has its 8,734 files and 16,541,094,986 bytes, each with one link again | + +**On the owner's machine** (done after the acceptance, on "continue"): + +- `home --set` saved `/media/jeremy/OrangeCream/Linux Software/workspace/runtime-data/tuldok/projects` in `~/.local/share/tuldok/settings.json`. The path follows the disk's own layout notes, which put app data under `workspace/runtime-data/`. Before, the default was on the system disk with 16.5 GB free. +- The owner's Tuldok database was started, the lab project opened in it for the first time (0.9 s), both environments connected and ready, and the same 228 entries adopted in 0.7 s by link. The database was then stopped again, as it was found. +- The lab project there: 228 built (203 recipes, 25 datasets), 23 cannot rebuild (16 earlier benchmarks, 5 datasets, 2 recipes), 9 to build (the new datasets, the pilot recipe, its two benchmarks and four steps), 2 environments ready. + +**Not verified:** adoption by copy across disks beyond its test; `home --set` when a previous directory holds projects, beyond its test. + +**Known gaps:** no command rebuilds or sets aside an adopted product; the 0.69 GB the manifest does not name exists only in the old folder; the earlier weights and training data are single copies on this machine. + +**Machine note:** the machine restarted during this work, which emptied `/tmp`: the throwaway database was made again, and the screenshots and chart from the milestone 7 acceptance, which were only there, are gone. + +**Next:** part 2, the lab repository stops tracking the old project folder; then the deletion of the old project mode, which waits for the capability check to be signed. From b202fce6447c4ffba51ca5aa07ae8eba03079a39 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 12 Nov 2026 08:54:49 -0700 Subject: [PATCH 035/131] docs(plan): specify milestone 8 part 2, the lab holds the new folder only Co-Authored-By: Claude Fable 5.2 --- docs/plans/definition-first-projects/spec-m8.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/plans/definition-first-projects/spec-m8.md b/docs/plans/definition-first-projects/spec-m8.md index 060f48c1..b9ebcf0f 100644 --- a/docs/plans/definition-first-projects/spec-m8.md +++ b/docs/plans/definition-first-projects/spec-m8.md @@ -123,3 +123,12 @@ Found while implementing; the code and its tests follow this section. - **`adopt` holds the project open for its whole run.** With links that is seconds. A failure partway leaves the entries before it adopted, and the command says so. - **Closing a project now releases its lock by a statement.** Closing the connection alone left the lock held until the server noticed, so a project opened again at once could be refused as already open. The full test run showed it once on a busy machine. - **The lab's manifest** has one entry per earlier recipe with a run (203) and per earlier dataset that an earlier recipe read (25). A dataset's directory is its one folder, or the deepest directory that holds all its folders. + +## 9. Part 2: the lab repository holds the new folder only + +- **The lab stops tracking `projects/rheon-model-portfolio-unified-04/`.** The folder stays on disk where it is, named in `.gitignore`: it is the converter's source and the origin of the adopted files. The orchestrating session removes it from the index; nothing on disk is deleted. +- **`projects/surrogate-lab/` is the lab's Tuldok project from here on.** It is edited directly or through Tuldok and committed like any source. The converter is no longer what that folder must equal, so its equality check stops being a test. The converter stays as the record of how the folder was made, and as the writer of the adoption manifest and the values files; it runs only where the old folder is. +- **The lab's README** says where the project is, how to open it, and that weights and data live in Tuldok's project directory on the machine and are adopted or rebuilt there, never committed. The paragraph that tells the reader to run the two scripts for the old format goes. +- **Tests that need the old folder** skip when it is absent, so a fresh clone's tests pass. + +**Acceptance: the plan's test, on a fresh clone.** A new clone of the lab branch, opened by Tuldok into an empty database with an empty project directory: it opens in seconds; it lists the models, recipes and benchmarks; the report draws the result charts from `results/` alone; and `plan --all` lists the ordered steps for what can be built. The clone holds no old project folder. From 4d9e7411e8a6c7d520c223358f7ebb0f480a52dd Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 12 Nov 2026 09:36:51 -0700 Subject: [PATCH 036/131] docs(plan): record milestone 8 part 2 in the ledger Co-Authored-By: Claude Fable 5.2 --- .../execution-ledger.md | 29 +++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/docs/plans/definition-first-projects/execution-ledger.md b/docs/plans/definition-first-projects/execution-ledger.md index d76dc186..332a65cc 100644 --- a/docs/plans/definition-first-projects/execution-ledger.md +++ b/docs/plans/definition-first-projects/execution-ledger.md @@ -357,3 +357,32 @@ Every declared output of the 203 recipes was found at its recorded size; no data **Machine note:** the machine restarted during this work, which emptied `/tmp`: the throwaway database was made again, and the screenshots and chart from the milestone 7 acceptance, which were only there, are gone. **Next:** part 2, the lab repository stops tracking the old project folder; then the deletion of the old project mode, which waits for the capability check to be signed. + +## 2026-11-12 — milestone 8, part 2: the lab repository holds the new folder only + +**Owner instruction:** "continue". Spec: section 9 of [spec-m8.md](spec-m8.md). + +**Commits** (none pushed). Tuldok `feat/definition-first-projects`: spec `b202fce6`. Lab `reorg/reproducible-lab-20261102`: README, `.gitignore`, the converter's docstring and the removed equality test `076b04c98`; the old folder out of the index `fd18d8202`. + +**What changed in the lab:** + +- `projects/rheon-model-portfolio-unified-04/` is no longer tracked: 55,865 files left the index. All 63,133 files of the folder are still on disk (17 GB), now ignored. The lab tracks 6,987 files, and under `projects/` only `surrogate-lab` (495 files, 12 MB). +- `projects/surrogate-lab/` is the lab's Tuldok project from here on, edited directly or through Tuldok. The test that required it to equal the converter's output is removed; the converter's other 39 tests, all on synthetic folders, pass. +- The README says where the project is, how to check, open, report and plan it, and that weights, datasets and run logs live in Tuldok's project directory on the machine. + +**Acceptance: the plan's test on fresh clones** (a local clone of the lab branch and of the Tuldok branch into a scratch directory, the Tuldok clone's code run with the existing interpreter, an empty database, an empty project directory): + +| Step | Result | +| --- | --- | +| The lab clone | 254 MB working tree, no old project folder, no `runs/` | +| `check` | 0 errors, 81 warnings. 73 of them are earlier recipes naming source files under `runs/`, which only the original machine has; the other 8 are the two recipes already known | +| `open` | 1.4 s | +| `list` | 271 definitions: 206 recipes, 32 datasets, 18 benchmarks, 8 charts, 4 steps, 2 environments, 1 model | +| `report` | 0.5 s; 172 KiB with 8 charts drawn from `results/` alone; no script and no external reference | +| `plan --all` | 0.3 s; 17 steps to build in order, 3 on a GPU, 137 GB of disk declared | + +The clone was not built: that needs the reference solver and the dataset generation, which the owner has not approved. Rheon was not cloned; nothing before a build needs it. + +**Left as they are:** `scripts/track_project_results.py` and `scripts/extract_model_recipes.py`, which served the old format and which nothing current refers to; the historical plans and the migration scripts under `experiments/model-portfolio-migration-v1/` that name the old folder; the README's link to the older `tuldok/` folder, which a reader may confuse with the project. + +**Next:** deleting the old project mode from Tuldok. It waits for the owner to sign the [capability check](capability-check.md). From 55a5ac68c17cb5f2dc2716b59196ee3bd8d2177f Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 12 Nov 2026 10:26:04 -0700 Subject: [PATCH 037/131] docs(plan): the Map workspace plan, approved The Map layout chosen on 2026-11-03 becomes the app's interface for a project folder in three phases: the format fields and operations the map needs, the page read-only, then acting from the page. Annotation and the volume viewers stay out; the old project mode is not deleted before phase 3 is accepted. Co-Authored-By: Claude Fable 5.2 --- .../workspace-plan.md | 73 +++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 docs/plans/definition-first-projects/workspace-plan.md diff --git a/docs/plans/definition-first-projects/workspace-plan.md b/docs/plans/definition-first-projects/workspace-plan.md new file mode 100644 index 00000000..3e31c76a --- /dev/null +++ b/docs/plans/definition-first-projects/workspace-plan.md @@ -0,0 +1,73 @@ +# Plan: the Map workspace, for real + +**Status: approved by the owner on 2026-11-12 ("the plan looks good"), with the three recommended decisions.** + +## Summary + +The interface the owner chose on 3 November, the Map layout of [the workspace redesign](../project-workspace-redesign/README.md), exists only as mockups that run from disk with the lab's content baked into a data file. The Tuldok app has never shown it. What the app shows for a project in the new format is one report page, which was a stand-in. + +This plan makes the Map layout the app's interface for a project folder. The mockup's screens are kept as they were reviewed; what changes is where their content comes from: the operations of the new core, live, in place of the baked data file. + +**The test:** start Tuldok on the lab folder and see the screen of the mockup, with the lab's 206 models on the map, their real results on the Benchmarks tab, and runs and build requests on the Train tab; then approve a build from the screen and watch it run. + +## What the mockup has, and where each part comes from + +| Tab | In the mockup | From the new core | In this plan | +| --- | --- | --- | --- | +| Top bar and status strip | project name, tabs, theme, "Needs you" | name and counts; build requests awaiting approval, files changed on disk, environments not ready, failed runs | Yes. The status sentence is computed, with an optional authored line | +| Map | models left to right in sections and lanes, accuracy track, minimap, list, drawer with the card | recipes ordered by training date; result summaries for the track; the card from `notes/fits/`; runs and products | Yes. Needs groups, the kind of change, and comparisons to become authored fields: see below | +| Branch from here | a planned model drawn on the map, with its training setup | a new recipe written from its parent as an unsaved edit, then a build request | Yes, second phase | +| Train | planned models, every training run, studies | recipes not built, runs with live progress, build requests, environments | Yes, without studies: the new format has none | +| Benchmarks | coverage line, accuracy against time with the frontier, error along the sequence, compare set, all-fits table | result summaries and chart data | Yes | +| Data | dataset cards; records as thumbnails; a volume viewer | dataset definitions, their state and product size | Cards only. The record browser and the volume viewer need Tuldok to read inside products; that is a later plan | +| Annotate | records, labels, review | nothing | No. Annotation data is not in the new format; it has its own plan | +| Analysis | field slices per case; plans with their documents | per-case values | Per-case values only. Field slices come with the volume viewer | +| Overview | where the project stands | summary, definitions by kind and state, activity | Yes | + +## What has to be added to the format + +The map needs three things that today live in a lab notes file Tuldok does not read (`notes/model-groups-and-comparisons.json`) or only in the mockup: + +1. **Groups.** Which section and lane a model belongs to. Proposed: `group` on a recipe, and a `groups` list in `tuldok.json` with each group's title, parent and order. +2. **Kind of change.** The colour of a branch: training policy, architecture, refinement or component. Proposed: `kind` on a group, authored. For the lab I would carry the mockup's rule over as the starting values, for the owner to correct. *Corrected when phase 1 was specified:* in the mockup the kind belongs to each model, not to its group (one group holds 31 architecture and 20 refinement models), so the field is `change` on a recipe, and the lab's starting values are the mockup's own, model by model. +3. **Comparisons.** The dashed arcs. Proposed: `compared_with` on a recipe, a list of the other recipe and the note's explanation. + +Ancestry lines are the graph's existing edges: a recipe that takes another recipe's weights as an input. The mockup inferred three branch points from card text; the real lines will be only what the definitions record, so some may be missing until those inputs are written down. + +The accuracy track and the row bars read one chart definition of the `progression` form, named in `tuldok.json`. + +The lab's folder is changed once more by its converter to move groups and comparisons into these fields, since nobody has edited the folder by hand yet. + +## What has to be added to Tuldok + +- **Operations:** `map` (every model with its group, kind, date, state and track value, the edges, comparisons and groups, in one answer), `note` (one file under `notes/`, bounded), and results for one recipe across benchmarks. +- **The page:** the mockup's `b-map.html`, `screens.js`, `tree.js`, `charts.js` and `base.css` (about 1,900 lines) become the app's page for a project folder, reading from the operations. No build step, no framework, no external reference, as now. Ubuntu Sans is vendored under `static/` as the brief says. The Stages and Ledger variants are not carried over. +- **Live state:** the page asks again only while something is running, about once a second, and shows progress as a hairline. + +## Phases + +| # | Phase | Size | Done when | +| --- | --- | --- | --- | +| 1 | Format fields for groups, kinds and comparisons; the `map`, `note` and per-recipe results operations; the lab folder carries them | Small | The lab's `map` answer has 206 models in their sections with kinds, the 26 comparisons and a track value where a result exists | +| 2 | The page, read-only: top bar, status strip, Map with list and drawer, Benchmarks, Train, Data cards, Overview | Large | The lab opens to the map of the mockup with real content; each tab is checked in a headless browser in light and dark, and the owner looks at it | +| 3 | Acting from the page: approve, decline and cancel build requests; plan and request a build; branch from here; edit and save a definition; resolve a conflict; the "Needs you" list | Medium | On the tiny example, a model is branched, its build requested and approved from the page, and its progress watched there | + +Each phase is specified, built by Opus 5.5 agents at medium effort and reviewed as the milestones were. Phase 3's check runs the same tiny training as before, a few seconds of GPU. + +## Out of scope + +- Annotation, the record browser, the volume viewer and field slices. +- Studies, trials and candidate selection. +- Any change to catalog mode or to the old project page. The old project mode is not deleted before phase 3 is accepted, whatever the capability check says. + +## Decisions needed + +1. **Scope.** Phases 1 to 3 as above, leaving out Annotate and the viewers. Recommended. +2. **Where groups, kinds and comparisons are authored.** In the definitions and `tuldok.json`, as proposed. Recommended, because then they travel with the project and Tuldok needs no lab-specific file. +3. **The mockup folder.** It is not in Git; it exists only on this disk. Its data file holds the lab's model names and notes. Commit all of it to the Tuldok repository, commit it without the data file, or leave it local. Recommended: commit it without the data file, and keep the data file beside it, ignored. + +## Risks + +- **The real lineage is thinner than the mockup's.** Only recorded inputs draw a line. The map will still show sections, lanes and order; branch lines appear as inputs are recorded. +- **206 models with their cards.** The `map` answer must stay one query and well under a megabyte; cards load when a model is opened. +- **The mockup's training curves and field errors were generated for layout.** Where the real project has no such data, the screen says so and draws nothing. From 4af5a74a98fe948724c1d074212df9d7b8aef4c7 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 12 Nov 2026 10:26:04 -0700 Subject: [PATCH 038/131] docs(plan): the workspace redesign brief and its mockups The design brief and the three layout mockups of 2026-11-03, until now only on disk. The mockups' baked data file is left out and ignored: it holds the Rheon Surrogate Lab's own model names and notes. Co-Authored-By: Claude Fable 5.2 --- .gitignore | 3 + .../project-workspace-redesign/README.md | 231 ++++++ .../mockups/a-stages.html | 115 +++ .../mockups/b-map.html | 127 ++++ .../mockups/c-ledger.html | 112 +++ .../mockups/index.html | 36 + .../mockups/preview/a.png | Bin 0 -> 123888 bytes .../mockups/preview/b.png | Bin 0 -> 117225 bytes .../mockups/preview/c.png | Bin 0 -> 109048 bytes .../mockups/shared/base.css | 447 +++++++++++ .../mockups/shared/charts.js | 121 +++ .../mockups/shared/screens.js | 717 ++++++++++++++++++ .../mockups/shared/tree.js | 223 ++++++ 13 files changed, 2132 insertions(+) create mode 100644 docs/plans/project-workspace-redesign/README.md create mode 100644 docs/plans/project-workspace-redesign/mockups/a-stages.html create mode 100644 docs/plans/project-workspace-redesign/mockups/b-map.html create mode 100644 docs/plans/project-workspace-redesign/mockups/c-ledger.html create mode 100644 docs/plans/project-workspace-redesign/mockups/index.html create mode 100644 docs/plans/project-workspace-redesign/mockups/preview/a.png create mode 100644 docs/plans/project-workspace-redesign/mockups/preview/b.png create mode 100644 docs/plans/project-workspace-redesign/mockups/preview/c.png create mode 100644 docs/plans/project-workspace-redesign/mockups/shared/base.css create mode 100644 docs/plans/project-workspace-redesign/mockups/shared/charts.js create mode 100644 docs/plans/project-workspace-redesign/mockups/shared/screens.js create mode 100644 docs/plans/project-workspace-redesign/mockups/shared/tree.js diff --git a/.gitignore b/.gitignore index 8a9476b6..ad6dead7 100644 --- a/.gitignore +++ b/.gitignore @@ -17,3 +17,6 @@ data/ /output/ /test-results/ *.pdf + +# The workspace mockups' baked data file holds the Rheon Surrogate Lab's own model names and notes. +/docs/plans/project-workspace-redesign/mockups/shared/data.js diff --git a/docs/plans/project-workspace-redesign/README.md b/docs/plans/project-workspace-redesign/README.md new file mode 100644 index 00000000..ea6b83ae --- /dev/null +++ b/docs/plans/project-workspace-redesign/README.md @@ -0,0 +1,231 @@ +# Project workspace redesign + +Design brief and local mockups for the screen you see when you open a project. +Today that is `/project-files`: about twenty form panels stacked on one page +(project file, candidate preparation, runtime capture, save-as, scripts and +notes, fork origins, text records, progression, measurements, data and history, +authoring, model and study creation, scientific import, local execution, native +execution, study execution, producers). Every control is present; nothing tells +you where the project stands or how its models came to be. + +The mockups in [`mockups/`](mockups/index.html) show the same project three +ways. They run from disk or from a local `http.server`, use no network, no build +step and no remote fonts, and read real content from the Rheon Surrogate Lab +portfolio (205 recorded fits, 26 authored comparisons, 9 data references, 25 +evidence notes). They are design mockups, not Tuldok code: see +[What is mock](#what-is-mock). + +## Run + +```sh +cd docs/plans/project-workspace-redesign/mockups +python3 -m http.server 8099 --bind 127.0.0.1 +``` + +Open http://127.0.0.1:8099/ or open `mockups/index.html` directly. Add +`?theme=dark` or `?theme=light` to any page to force a theme; the toggle in the +top bar also cycles system, light and dark. + +## Who it is for and what it must do + +One person, running long careful experiments on their own machine, opening the +same project many times a day. The screen has three jobs, in this order: + +1. Say where the project stands and what needs the person, in one glance. +2. Show how the models came to be: the main line, where it branched, why, and + how the measured error moved. Let the person reach any fit in a few seconds. +3. Carry the pipeline end to end: data, annotation, model definition, training, + benchmarks, analysis, for text, audio, 3D and image projects alike. + +## Calm Technology, applied + +The Calm Tech Institute lists eight principles and certifies against six +criteria (attention, periphery, durability, light, sound, materials). The +mockups turn them into rules: + +| Principle | Rule in these mockups | +| --- | --- | +| Require the smallest amount of attention | Status is one sentence from the producer, not a row of tiles. Each stage carries a one-line state so the navigation is also the summary. | +| Inform and create calm | Only three kinds of thing interrupt: approval waiting, source changed, file missing. They are a list with a button each, never a modal or a toast. | +| Make use of the periphery | Variant A keeps stage states in the rail; B keeps the status strip above the map; C keeps counts in the table of contents. Live progress would be a hairline, not a spinner. | +| Amplify the best of technology and of people | The machine sorts, filters, lays out and measures. Judgement stays visible as text: purpose, outcome, lesson, decision, review state. | +| Communicate without speaking | State is a glyph and a word in a muted colour. No sound, no pulsing, no motion that the person did not start. | +| Still work when it fails | Missing, unverified, unavailable and unknown each have a label and a next step. A missing file dims one row; the rest of the project keeps working. The pages work offline. | +| The minimum technology needed | Plain HTML, CSS and SVG, matching Tuldok's no-build-step rule and its `'self'` content security policy. No framework, no chart library. | +| Respect social norms | Keeps Tuldok's vocabulary (Data, Pipeline, Runs, Study, Trial, Run, Candidate) and its refusal to claim more than was measured. | + +## Design system + +**Colour.** Cool, low-chroma surfaces so the data marks are the only saturated +thing on screen. Status colours always sit beside a word. + +| Role | Light | Dark | +| --- | --- | --- | +| Page / surface / hairline | `#f3f5f7` / `#ffffff` / `#dfe4ea` | `#0f1317` / `#171c22` / `#2a323c` | +| Ink / secondary / muted | `#1b2330` / `#596679` / `#8a94a3` | `#e6eaf0` / `#aab3c0` / `#7c8694` | +| Accent (selection, one primary action per view) | `#2c5fb8` | `#6a9ae8` | +| Good / attention / serious | `#237c60` / `#b4700e` / `#b7452b` | `#4fb68f` / `#d9a04a` / `#e07a5f` | +| Branch kind: training policy / architecture / refinement | `#178f74` / `#2e6fcf` / `#d2652f` | `#22a07f` / `#4f8ae0` / `#d96f3c` | +| Branch kind: component | neutral `#8a94a3` | neutral `#7c8694` | + +The three branch hues were checked with the data-visualisation palette +validator on both surfaces, all pairs: worst colour-vision-deficiency +separation ΔE 8.9 light / 9.7 dark (target ≥ 8), worst normal-vision ΔE 19.1 / +18.2 (floor 15), all ≥ 3:1 contrast. A fourth hue did not pass, so the fourth +kind is neutral grey and every kind is always named in text. + +**Type.** Ubuntu Sans for everything, Ubuntu Sans Mono for identifiers, hashes +and paths. It is the face of the platform Tuldok supports, it is already +installed there, and it reads well at 13px in dense lists. The implementation +vendors it under `static/` so the policy stays `'self'`. Scale: 12.5 / 13 / +14 / 16 / 17 / 20 px; weights 400 / 500 / 600; prose at most 66 characters a +line; tabular figures only in columns and axes. + +**Layout.** Left-aligned, hairlines instead of boxes, no shadows, one 4px +radius. Sections are a heading plus a quiet summary line. Lists are the +primitive: references, studies, fits and evidence all use the same row. +Forms do not stack on the page; the action lives on the thing it acts on and +opens in the inspector. + +**Copy.** Sentence case, plain verbs, the same word for an action everywhere. +No explanatory subtext: a heading carries a count or a state, never a sentence +about itself. The chrome holds no project words; metric names, populations, +group names, decisions and evidence come from the project's own data, so the +same screens serve a fluid lab, an image classifier or an audio corpus. + +## The three variants + +| | A · Stages | B · Map | C · Ledger | +| --- | --- | --- | --- | +| Home | Overview: status, needs you, stages, recent studies | The lineage map with the status strip above it | The whole project as one document | +| Navigation | Left rail in pipeline order with a state line per stage | Tabs; the map is first | Sticky table of contents with counts | +| Inspector | Fixed right column | Drawer over the map, Escape closes | Opens beside the selected row, inside the section | +| Lineage | Vertical list with lanes, sticky section headers | Horizontal timeline, branch lanes, metric track, minimap | Vertical list | +| Best for | Stage-by-stage work; projects not mainly about model history | Model-first thinking; long branching histories | Reading end to end; smallest implementation | +| Risk | Rail plus inspector leaves less width for the list on small screens | A long timeline needs the minimap; new users may not see the other stages first | Long page again if sections are not disciplined | + +## Screens (as of the fourth review round) + +Jeremy chose B, Map, on 3 Nov 2026. A and C stay reachable from the Layout +switch; the parts are shared, so every screen below appears in all three. + +- **Map.** Lanes: checkpoints left to right, each branch family in its own + lane labelled where it starts. Height never encodes a number, so edges do not + overlap; an optional Accuracy track beneath the lanes draws the error curve + on the same timeline without branch edges. Hover or focus a node for its name + and numbers. Dashed arcs are the portfolio's authored comparisons for the + selected fit; hovering one shows the note's excerpt. Selecting a fit updates + in place: the target highlights at once, a short run of highlights steps + from the previous selection to the new one in both the list and the map (at + most about half a second, skipped under reduced motion), the views scroll + smoothly and the drawer slides in. +- **Branching.** Select a fit and choose Branch from here. A planned model is + appended to the graph right after its parent, in the parent's lane, drawn + hollow and dashed. Its node holds the training setup: name, kind of change, + recipe (short list), data, runtime, updates and learning rate, attempts and + wall budget, target metric and threshold, intended change, then Prepare + trial. The parent is picked on the graph, never from a list of models. +- **Data.** Datasets as preview cards with kind, record count, grid, size and a + hash glyph; paths open the folder. Opening a dataset shows its records as + thumbnails (paged) with a volume viewer: an isometric stack of slices, a + single slice, field and slice controls, grid, spacing and timestep. Import, + Generate and Release open panels with their inputs. Annotate goes to the + annotation stage. +- **Annotate.** Dataset and task pickers, a filter (all, unreviewed, accepted, + needs work), progress, records with review badges, the same viewer, and a + form for the current record: class labels or tags with number-key + shortcuts, Accept / Needs work / Reject, notes, Save and next, Skip, and the + saved history. Arrow keys step through records; Enter saves. +- **Train.** Planned models first; then every training run (one per fit, in + checkpoint order, with updates, learning rate, seed, loss, device and the + study it belonged to when known); then the seven budgeted studies. A run's + detail shows its recorded training setup and Branch from here. A study's + detail shows baseline, recipe, runtime, data, budget, intended change, the + runs in it, steps and documents. +- **Benchmarks.** A coverage line says how many fits have accuracy and time, + accuracy only, time only, or no retained benchmark, so the smaller plotted + count is explained rather than implied. Population switch, kind filter, + metric, frontier-only, benchmarked-only and search. Accuracy against time + with the Pareto frontier; error along the checkpoint sequence; a compare set + of up to three fits with a delta table and training curves; a sortable + all-fits table with a Benchmark column; study results with reference versus + candidate and the change. A fit without a comparable benchmark offers Run + benchmark through the evaluation recipe. +- **Analysis.** Field comparison per case: native, predicted and signed error + slices for a chosen fit, case and slice, with the per-case error strip. The + slice slider redraws while dragging. Then one row per plan with its outcome + and its documents as three small links. + +Shareable states for review: `?branch=` seeds a prepared planned model +from that fit; `?cmp=,` seeds the compare set; `?theme=dark` forces +the theme. + +## The lineage view + +Both renderings read one graph built from the portfolio note: + +- Order is checkpoint order (C03 to C130), then the complete generators, then + the components. Authored groups become sticky sections or labelled bands. +- A solid line is a derivation. In the mockup it is read from the card text + ("C53 fine-tune", "initialized from exact C53 values"), which finds three + branch points: 15 fits from C53, 3 from C44, 4 from C37. In Tuldok this edge + comes from the Trial lineage sidecar, and historical fits without a sidecar + stay "no recorded ancestry", as the inspector says. +- The faint line is checkpoint order only and makes no ancestry claim. +- A dashed line is an authored comparison; it appears only for the selected + fit so the graph stays quiet. +- Colour is the kind of change on a branch (training policy, architecture, + refinement, component). The mapping from authored group to kind is a mockup + rule; in Tuldok the kind would be an authored field on the portfolio entry. +- Each row carries a small bar for worst pressure relative L2 on a log scale, + so a branch's progress is visible without opening anything. + +## Benchmarks + +Accuracy against time is a scatter of worst pressure (or equation) relative L2 +on a log axis against median GPU milliseconds per call, with the Pareto +frontier drawn through the fits no other fit beats on both. Hover and keyboard +focus read every point; a table view holds every value. The second chart is +the same error along the checkpoint sequence. Both say what population they +plot. Generators are kept off these charts because their task and population +differ, exactly as the portfolio note says. + +## What is mock + +- Studies, the "needs you" items, reference sizes and the missing file are + illustrative; the manifest, evidence list, fits, metrics, aliases, groups and + comparisons are real. +- Evidence previews show a placeholder instead of the bounded text. +- Derivation edges are inferred from card text for the mockup only. +- Training curves and per-case field errors are generated for the layout from + each fit's recorded update count, final loss and worst error; the field + slices are synthetic. The real screens read retained measurements and the + paired-frame dataset. +- Recipes, runtimes, trial rows, annotation tasks and the twelve seeded + annotations are hand-authored. Record thumbnails and volumes are synthetic. +- Buttons do not call anything. "Branch from this fit", "Approve reviewed + Trial" and "Import fields" mark where the existing explicit operations would + be invoked; none of them would start a Run. + +## After the review + +Each page has a Layout switch in its top bar that opens the same screen in the +other two proposals. + +1. Pick a variant, or a combination (the parts are shared, so A's rail with B's + map is a small change). +2. Refine on the chosen one: naming, density, what the first screen shows for + a dataset project rather than a lab project. +3. Write the implementation plan against the existing owners: project files, + model portfolio, experiment lineage, retained measurements and live activity + already expose what these screens need; the lineage kind and the derived + parent are the only new fields. Keep the `'self'` policy, vendor the font, + and extend the browser gate with the desktop and mobile, light and dark + captures it already takes. + +## Sources + +- Calm Tech Institute, principles: https://www.calmtech.institute/calm-tech-principles +- Calm Tech Institute, certification criteria: https://www.calmtech.institute/calm-tech-certification +- Amber Case, "We are not bad at technology, technology is bad at us" (the eight principles with examples): https://oreilly.com/content/principles-calm-technology-we-are-not-bad-at-technology-technology-is-bad-at-us +- Portfolio contract: [`docs/contracts/project-model-portfolio.md`](../../contracts/project-model-portfolio.md); lineage contract: [`docs/contracts/experiment-lineage.md`](../../contracts/experiment-lineage.md); current workspace: [`docs/contracts/project-workspace.md`](../../contracts/project-workspace.md) diff --git a/docs/plans/project-workspace-redesign/mockups/a-stages.html b/docs/plans/project-workspace-redesign/mockups/a-stages.html new file mode 100644 index 00000000..972e71ac --- /dev/null +++ b/docs/plans/project-workspace-redesign/mockups/a-stages.html @@ -0,0 +1,115 @@ + + + + + +Stages · Rheon Surrogate Lab · Tuldok + + + + + +Skip to content +
+ t.Tuldok + Project +
Local
+
+
+ +
+ +
+ + + + + + + diff --git a/docs/plans/project-workspace-redesign/mockups/b-map.html b/docs/plans/project-workspace-redesign/mockups/b-map.html new file mode 100644 index 00000000..44636983 --- /dev/null +++ b/docs/plans/project-workspace-redesign/mockups/b-map.html @@ -0,0 +1,127 @@ + + + + + +Map · Rheon Surrogate Lab · Tuldok + + + + + +Skip to content +
+ t.Tuldok +

+ +
+
+
+
+
+ + +
+ + + + + + + diff --git a/docs/plans/project-workspace-redesign/mockups/c-ledger.html b/docs/plans/project-workspace-redesign/mockups/c-ledger.html new file mode 100644 index 00000000..a2c9a85b --- /dev/null +++ b/docs/plans/project-workspace-redesign/mockups/c-ledger.html @@ -0,0 +1,112 @@ + + + + + +Ledger · Rheon Surrogate Lab · Tuldok + + + + + +Skip to content +
t.Tuldok
+
+ +
+
+ + + + + + + diff --git a/docs/plans/project-workspace-redesign/mockups/index.html b/docs/plans/project-workspace-redesign/mockups/index.html new file mode 100644 index 00000000..93b112a6 --- /dev/null +++ b/docs/plans/project-workspace-redesign/mockups/index.html @@ -0,0 +1,36 @@ + + + + + +Three layouts · Tuldok + + + + + +
+

Three layouts for the project workspace

+

Same screen, same data, three structures. Switch between them from any page.

+ +
+ + diff --git a/docs/plans/project-workspace-redesign/mockups/preview/a.png b/docs/plans/project-workspace-redesign/mockups/preview/a.png new file mode 100644 index 0000000000000000000000000000000000000000..bc913d8ef05cb193bc57dcbfcd03d02e7794d489 GIT binary patch literal 123888 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

&X8l=$%4{vFYM^s`^E!==0epwC)|LsFZ3 zzb7IUu}h1u0)c!8ewq{ETOL6BGY4p(#TYXPfEFnN0um1rMi`$eFhtMrsam4{;)oJ5iMS^m zh}0bi^IoGu`qB&3!ici|nBfqefRdgIvwfnK#S9PRNSQ;GO<^+|PGXKs2!u10pFyFF ztPONim>IXd=%#U8Cggzdf`dW&*K4i&9X#dPkWgBRK$ebJcG*{^)vPm95#6*PQ9ZvPBaXd|pyMdZM9*;2e$7#L+P-^QJf-vb`MnY7x0XS^0xB_N zZHXtI*&u7UDzFK|(Z)ux{FMtCS&7)5BsL^W4tFPE;k7-x@4)a+p5mvIwIwd~#sY5k zNl2F391|1qPf$|wF8VDx9MtDgS`L>v8Dz#M4yHoreXsjeO<}uJ%SVR8`>1#$fB+CP>O&Q*YbdlmXtu6S`8>||CZ489%~AQ%k}}6Tu{^Gz z|IPY2qkVIT@NVFN=4*v%cbIe?p_RV`3t&>m(2E!dr;FF!v-u8#aZKJ7OC)sM4HF)) ze&p2vM{2S<&vVRBRxtCTP^#s{*KG0UBnDyKrPcMtfPSZxah0cHtwZo^KWM8b z1C=W5RUg%!zBC?j41=>bH#T=@!2VBqqZ}8{l7L6QEj!&R2hnW{W^eWewnlhHruvVS zbo0aBz2MK@$-0E-Xq0Y7(xsZW;c7kf^bA`UXd}Gqfv!@(=4#TT^@~{Us2}fd4l{b{ zm?~zN3sK}UV5??Wgo z|7~201jyQ(J4$<2=haWbx!G`yA5jb%T5fHwyr`3eUNHi%^qvfNH10JRulpWl{jb1w zvTQJF6;HhHx7{9jJseAL9*-|YEMjR>n;2MJ+P4R-m0{47p9GaAzO|%jl5V4ENwe`+ zUY+S#RN`J-?kLduqr3N42LeO{Q7#@B-vt5@&}ggYq{+z18B0nxZ!yLnnnYD~=B?A? zR!>F{Z~r=##)zT7!yAE*Fpy^Ey6tl^n74s_xxKTKoV??a;~tnYwut{;k@_@F4E=J5rn zWqd2&Y|4w@z00?T6#w>$r}?+WO8T#_)=tT+jHB3O%Et4&bPMZGSY5b>eeM{ z3OxzE83kG~7)P0szsgD3pv89nKt^CA;iRw-k^A>xc21d!z*iqHYV%41)e+HZhB3q- z(!`b*h!DixgWV_+8urILH=e9qurs3O)bDKU-s(j=U~cW^vDKiin<0&bJSCQRp}o}0lq3v)OxX&ud#1sv3ZB;0dw9SLgkGX7jCnX&{F1yhxxaK3VD?H-^|3xA!@o7 z`cK{&1YllaB3&;y(kL;sOJ*&RWqudbz_wUq1QYzt%HZS5hCQIeRUzJ81L`2F=v?%b@7$)zOTDAIU|WBmAs*#W za%L&>-tddV-DyMH43mQ!{`)fEM>KBHfW^%bJq$Pn9yT)gcN<1Sl-$ahd@dFyvl&zd znW1THSTRP6yI&ALL&$*69N-vI*_&qjVHwII*Tzvr(scmqXNUwoe4=wOjG84%dLhF* z9yMWK+yVt-I8&!;?w<5~Bqd2Db{+wU1rngpk|Vtr|43?(O6&sbe27s7A&SMQ3EPoCM{T7R_&Lsel zDPz}raf;T=7qTa2BpHj5&LZTdS-JA!B*-6m6r1kLyGqNiG}Y@R0Q;<2!Mnl7wX!kJ zF@dr{jL0=ky#3XKx$IIL9==_?)Fo9fV^LT6Ie8)-NqLlNNAz!dWAn8 z?pEa*$U=z#qTnX$G?X#w{jt7#iW0&BJr!u<)2<*Mo+q2g>9|xRM478`FKeEy2Os9= z_IH{Hmxnh=g*-ZvBhiIZSIDM;G0gZQ5vg)lkuiKEs5?t}#3Don0)QvW8egqo1J-dd zbv<*o;e{x&4S?Zi3a$ih_Bx4q=rWH2U`NOM{=Gd#Ag?JAnLI0}!U!)I2+uo%ibWm+ zumr@75fV`Eh+rad(G_B2ii&ix(uvVx2?ert#}Qf#AUWUaBjvorf<&Rb<|rl!5U_|0 z2o834X3E#Fm~ns4-nPj_4$=34gC=YtSdF9MP3kv8m_)dand^aZM|@b433S?YAb1Y9 zMCV9m2Lu?-;`ABLDACl^MME?t+Wi9%9yRgf#ktuSBLf|)ifn9TAjjs`i4IE$AT0?~ z^#4dY>!7Iqw+%0_z|u=eHxkm_-7O#`-67pbhjfF$lF|~QfYROFDV;0b9sBP0_x`&B zGkXT+oX>fl>%Q)x_L6S#YbcPze4l9-Oukmd`Qu*fd16)}n|Q6yUgXrRp8OjA8- zAPTX%g&T)kp5#wTfMUMa}4-N2nWSga?@B8r24c_3_3LBNki6>GBj>m-%h^DjX z%nLC)92BtExn?rm;d>(l|FXQtePCdPE>VIxAMLycbRSJtugEi2ynDu%b2wpwOq- zk2sx9jlMcpR)&Nk`9bCO=JqDx3l}dV15&pASN-~?P)1@Grl<$PPZ2EkyNk6{T`CQx zFMRusSXZ6&ZILc+)~G#;ToeZxe|>*mwLs+AYASh54a+o9qI-5G+dcIgM!EKlTEB1F zZoCdyijdt>IsGu{a6OysxSCQ?z^1gX_*h>Syx0r7UNb!v^sIEhxU5((o}@Z_S6R(H zutNE|hYyvPR7*MUvz%0SxUDq0sEwi&_ubVu1+yD}7*M@x;m~pgprL4676*p!#P$~V z(^k%UzxEAlQy>)*yki+&=*4fnB^R)^b#(aM>SE<7eBj;Hi<*cn*CaEQO{&r8lZ1{v zs6Tk%QJkGtqLJ%B1&JTxe_E2fvrD&r5{(V{!4!ZIcef?!@E>-*&TbgW6gO+ksGiu1 zdbZ~2FuDFKgOmgVcADAI!X?rUQ#{h=ylFLk9vKkzm{jrip*((0a|ygl;(y2wdL-=C zJa6WB?mwxjiuv~DVUO@00P zJFr(w!KjeN$^Dl|GgjiM_N2Qzzk;CTAR=A6!CL8cxNH^;n^7J`J>NlFB_rs%;j6Y- zyFr{l&~^rL9&|!2=ddA1w_iRo0AoS)S72@Qw^8#nPFz{c5FLe;?US}z1AToXiJG<} z13$raE+$m|u{(bLgv5zsF;&J$k?aXXr{ODfnmK%~>3vhv z0vJb9uCedgXI{L+erTu}A$4;S&s z&j`qILkEz?*A6=G4;LFg2rgtipS#M`TlipvNJ-1ayjL0kA*#c%;lDe&@mhI_TA*)Ku;_ZPk6t++r^nlVz76fXmI!_kxnmQBg%`YT#~7YIyQ+Dm zK-5ir7BxX3=9k-*@8}T}f?gC(lds~G1C~TZh(FdkRN!a3&1>rwzGre=YI<~pPI(H} zHnr54NceAiLSy$ZN?&VIN}9a==I8!>PjKDnd3(V_A(r;h%Sp-fEF@RY#1K+?RHm~z zzkSmC-vwSwe8*Qg=+xPAJ<)uZ%u{(##u}IF0mv#N`7hiCsqlyv;;E%Z&@PvB{o5Zi zt!a1lkXNKMzWD*Lyygr^il0~#6Hn5f$4fE$Fgh|$^EtqZ+s?<|nE%1)(T%6DIV2lp zua1?pB{7-_@B60~DUu%jE+%bsEdsRSvNCO@3=m>=nWYqcayf4}SXwRIooSR-Y6{*E zS{qVWb2JwlTkq=+wOZhV<61#J5iFFy*t##U(Xo@2^nwe&^Y(!*Rjo~;0h^G=MF1@* zOR1SjDTD;_Oa^&s9}Zzchode^xD4W1w9dNhm^eINa4||($ z;U#a&dw){e^oom2B{R;>=$n2_+6ArH|IjY$tzS*+VLR_EPIz!_uTuBA^x%qAHkNQW zm9_G{A#}bU4r`IJDDP2Z2I#fzi27{mEuOZHWq290v99N1V<2m$%Z5(cEVXm?Z~j!a zyvT-{l{FKYn_5Xu0 zR}fx%3Zn!Z0(nua4mB|h*BYN{uNR5>P-j|(?mXrnKZp7ef_7rbBB5?1AU`o$%WJr!(Gyh53Cpw zaJuX`yfZ~AUel(r3hwEmf<4Yb>hKEcUH4332ZOGjv{@*~4?;0rvbijN%k0i}_&fOT zz4sm{w2O;{YoEwdl|q@m{dRsAn;MHkXCJf$=G!<^Ea!_iqvxc6YxAVA5dp-*wZqAD zEGtz-)6-~0f=+md`jTV3Lb|eoVieSsNCy|uC~@fSfF0t0JNO7vwal^fXtIkl|mG*YtHB zNvNO$#$o#R!0z+5+u2`#O8u0ZXBO0A;g%CRoNOl!@z1`8>l%Tp^S;|e91ZK2o8_bU zQ11kP*oN5KjmNDN)H9>|_TY!JXSTbIPSK+WJ?wt9rY(5J-b@E=bD-H0)tlUz!@%ds zWy9$9%=GEbeE%s=;`#b~BC5avP5gcZM?G)V*!zykZ$dn9OXwfaeKq#2ECoP{vj5_0b8>Ty2uNzYPp*{)87r;4~FePpQ0pQP&+^6 z*o*nPM>kys!+g$GU}>;`EyvyU$)Fmh^+$;$%1wi}!RNy(CZ8RlRIjrel&=TD_SQL0 z_&-DKji%w8HW8Odb%_XjD3p-FqrOtld;*fRXYRF z*I%_mNqs<0Hucc}d?2I>KG+Htl%v3C+z)52{rn^#9(>ja+xCDOIHjyVT-FR&yUSi@ zIO-cOK3_q-`22VN_JrIyqwT<+i@EdMa5c zMkTA?fnFD>Nx-U-Fe&^`2a)bOgP!vOm@j|&7XUz-y=L+)!2yTs5)Ug+&hJF)Y*|Nb z$c2~MhWMwG-oc)pf_I~no^Lh+&h$r@A#mos1E=Q$Y_l)W^#1aNFU=?LxOA^^&GU3= zny~;S5aG!u=|Mc2=f1?t>D}zl=d;s+jxch#Pj7!XJ(cX}v(@Cm_$Liv`kBTSL@J1^ae67dWXkM>DV1fv;6Gqx?gLg(oV zMELO~1ohbOdo**oUJvp0!*)>g{FXif|G=43x?@AqJhTB2%^Ihylvz9^y?xyb9f4DA zf0(7?3BQp|Uw`^;WD+p)!9*dyx-Dt_0wG7Bm3MH1vjXh8{VZts&s9|LRi3&l@7rvSFFD{><7pk`2{Y!2X3#9RlV7t3PN_a5-Jm8}(geHs!g*%@(nbQ~} za@GWagxO(`Sjpk@w}Yq7)vK5!N6M8A2!BO1t{Gs-!{wvqecTx=pnD&Ozz=L@M2)zc z?8clcg}1Q#gtNJg7gQCD@Fa_snFOEJ z+byFNRs2Ev?(Xez!-B_0oC3VMprb1s&MPNYd8dnvM?^pvlM>>Lm$5*Wg*KYmaQXzo zX0EM?MS3ZpSXx*pT;z?&hc!SG5dtb=wUAll3s;JLXOXYykPNDn{cc|3g-`2PA5&I% zgwl#KZqAqOV-xWEwOZon?DI?e+doo@^chQmzYY$F;F>aDR#FvkyopPHng<|St21DH z^mN&bI-O)H&d(>QgqHc(nfVO}zE3!PiF2uJNa)-Bssp$EG}i5{ese$y z?Vj+MJQbbcqfC=^y*%%R;^gswQF7yGNsjD;A0O79G`vW_bRg@T!#Witu@_DJQTRqe z9m`wd<@xo>lFOjygpsV^^PVi}cHi~X700pD0ptxm+F>pHwB3Leg^XY-vsj-i|FhTS zIpfmRNRA zb|i1$_8REpOc!C)KqmvjG%hEPL5u`*I}j7Z;^885k!0t`I|Ox7*-clt3U_`7l+hN? zY6hEhs1V**Sp_ic-&mt1AEw8pCJR};t9+=dBS4T+wR>A+)Ng=c$cT&s16WM9PwjYRmX>MyUQlZx26=eB#^@QISDw~vLs(JsRdz zZI9XQo|xAw)Q^n1)kd7Ni$dWZ&ZfpQp1)!~yK5JV;jgv_&R!a!Qj%a055HH@aP?EW z9ZrlPXXJE3R#9H9wQH&^Ju5Th_vRzVe1|OX(}3DC2&>}lkIU=D&`<0d1th)PZqDGb z$x^N}lwqMLNY2F9btjU9ZpG{r#LPZdiHI3{;S2Wy|-vhK16p@OE{vOMkye!x* z;P55F47Bv67!;XatI{!-OAFy}7KF-zr;h7r+uHE9$t`Hnv$TX;XWP;lR^P?G1bsnZ zkCE2fF#BZaqb3(4F}ic-CqGbL7jU}jSYSRg>dnFm>iOc&)&uW0*bK>L&^!)G!be~j z^6p&hSHq8q-GFw797ZD4?%p)P3%|_W)@ckV86$I%x=7@Twy*qTF;!=Q`q!Vu5KCIn zR!x4sGgspwXdQLRWVV(CbA{z*D}Ja8phQ4YW=0ZZSwZdT6~Xaw>Vy@0J@BuYfu(7q zi4i73m6~Tyyo9Xe)zYLJ7pr0ge~@4|>Jf%GzX#DU0Nt>OOGEAhOmzA%C8fZ?F%3TQ z_@y@i$N4v1ysQ^NJC$}3$ltuYu;7)Hzah*nH+9y{-<+s*O(Ba5Gw(9yepZfLiIkqM zhYk-P5PPy4zbDSdwjs>?YAr&7w7e`XCQ2Bt&P;*$n$3o>TD~%vS@WGRHB?D$tUiZv zMV>x%f?i5V>P`8z!zfVy-3>*?yD?tX5!ZeGA^7Sp!~+n+1csyTn4nk-l%VHu)5Owm zA>Sl9-}L*MUf~44wyD#H)zYJP9!%iSe0$vWlq`Qw9g*{yI#)76(mB#5OuL(D4?ye4 z5ay4=%b)9bM4COr91fNOfCn<0eo1!q^6;b;3QB`4@o*C1)!Kw|+wn*MG#ZeUsv<)z zg0w#Meb~8lVftcFRxlL$-!7fnLXSv7+PbGVhxg-o#MeKo6xtB?}0!Tc+)Q8Bh>q~Exb=mU&afZ zDkjy-6PB&|h{QP}x~BMy%ONBqtM*vNJYxpT6HM)#;ak~dB=iMK*rJT2wco-dKs{Q0_9EN9Jr%T_SSFcTGA zbQRY&54Lc4Wor~^&`Z}@kahNm_t)UNv(EEzh3pglFJ;APp;=5ZvS4bpBrGhSe5$z= zdVrI!Cmz1+4o_ZSnry^JtIuYhBfFi=XsFN-GeIHlxw)mbtMg_nVLz*l?sC)BU~eYU z0?MVuIdLxhX;t>PZ|$XgX3<|BmV-nbglDG2$-{{IdkZ0o?i0yK)Vm+3C@7r;SA8p8 zzm%1i_cGHad(!d~M!QD?L;npgePH4j=bc;NOXa<< zPRNAJ&hkvBGshx^ih?moFwr8IiiRrq#rTR5EaV4#s6+`BA;~$j+B|4^23LRXiZ4hc zdpSpAuj&KWJt*2K){vmWpFQf@to!{UFXV4xp)7df8ee2U9MMs6F(J^-XVNun+e|XJ z7BadnVmg-%+=JoWt;dKTnJF~5iUe$~P$-IturXOcaZ_rr@NH)7-V^7FpvKjZwNO%V zT;0^xN7NtPDozp)9y8SHaCB4Ji0OT5!BZi6^QlGiW2Oko3yof7#3?3^+-YNbhu z5mFW?qYDa6dwLJ;yZh&Qg9O8(c_M+s>~-*l>FS=;fTV1YM*aagmb%73NDmUylOal7 zU0rJE#lY;EEZ&NG!*!zCcweEZ`q}C%@f>o@fWHFcfPC2p7w<%c6JfvO^X0;nX}9Se z3W<%sOEWyAs{RyKR@}T|!k%T8cD}T`?juf4VwEdGzPFC1l6Q}y*bx1zhCB1lz1+AW zeWR>6Faffbj%J%zFM5tzX?n+L5kdqa4M{6Pgd(*dz8?rMG^b<}?*>2{AVwG|l;rHZ z#~iZ)z>7;j$YBUjI5>#8EW18GjY<%u#_(S)pzOaMGUJ3bQX8%Kp2or*x~iJ(Rw)I# zdFN3U)@t_KQGQz`b7unsw;GihtXSDUZEaI0zjQdhGv6|&t{G}2TQ{!6s>H>@{jxcj zG^|YQ%p=|+6yD`4+9tVrAGFe;y2h_l zg0I1C#ad1>ifpP|oL8U~D@?~kSxvQ+1spyFmXW6Vw zL-O&lby#GzTM$oc19dC+F;Bhq_KND}<~2_9=`cB!SV!&It>KspUPAg-|Irp?y0yS! z{Lt#ZUmL5L@<>UUjhhRB6W8)z4iSA!^@4{h$Ez;?h0@u|%-z;LHKMkxFz|&C&tiI9 z{N-y{S~6QYhkkW5(Iv^xR|HfDZgAjQ`FXTa`LjpFbIE1A8;z}GQK=k_lhfqfc<P2*7w9>Q~ zm@8GknRA0^%;IH^y+z(4s-X#j3hg9)ZV%2CPm13Cw zI>xGfr70%Ii!$CCYirn=8R@-9>_&(P83&e+3aqP;cEH}-o&>*6Tn^$SEXgtr#j5Gx zZb#Z5uJ)xy2wD@2@Gqt&G;VmiGqX3_QSvT(C%L6$kS)ym1G1k&mY;B;*oU129x-3 zfLOE@Ig1>J!fr(_3g15k+^wv9xj)%h#Nw_7?jL^$W7BVmh(Kv!NG+-ppq2Nxpc)w=?i&^E_vhZA21y~VDMC+P6!u9hd)sGLPwT5I!~&~@2Z1>2zCW42Oc6zDz}x4T)!Xz;7u z<}_Q=4$-9uTC##;pqHtqcNbZ3lrn@Z?YULZ;yIpfv-+8N zlFIN4;j`3KGhHuJ_tYr@Lb_D{jt(q0drm!FteIFGh=li3zh&M0Y8o)VJZ z&A=ZmJ3AENxOzw7y$s5Rrc1*avfsA?>-ZhZXdB8rzb{?eykz?SK(|7`|FS1=b#=Z< zW~i2VhW{m37vtxlu>Im^kSn8@MrVo8x(KZs?ov%k)KKyE$ymu(AHW*e*^1sA8@XW0 zwt3#q_#g;=tJD?3Rc4QpLXR76r6nVqET^i*^Mi~We&BDi=Zr?%#xzrsjFiId4$&It zgc>844AJhg{y0cSiulEf20r)v7@j35uZC@{6avnQM5E?aQwH&4y&J+q87s-vOp}Qh z+ykj&CQ`eY#Aw7YYDI(U6jk9(+tffeK$a5CKnNErh?p}CAuPq5n88|CrNP&d7}Xo? z*l+LsY3lrb*K+cvDsnO5JhBt?QE%<{TSIscM%TmMD9hi!@Byo%C70KV#aUuFMH~^K zkGBSaRUEz&w5PgnIpoJgjw4m^lIoib!i3wzrk9b;te~rXxa`i_m~v2PWOoBlm=@#*jU`~=;8x38E&eT z3~X{VXE~XBfC!18tvSvh?S=%uY&v}J?1%e!j}Y*7F3-f)7tyEsW?6Ql6jhXzMVrgX zrHlQy&z;HatZBT$mc&+$>N&RRsa)6N3@i{44uC#&NVc%`y);_L*zd2CUr^k!0lRxicJ6tndhs;O#U_vK&yW|lSxcBwXS3)6&&w_nK z=}=Yd>xNr(JyxT1y1v0}dIi2R?NkkAWHrNvWYM59iSi5JIjcq+i`N}l10l!l zQ$s=9PN%~pMpn#-t{}@+B9z-N8wPx1=ntbd%ToUo4O-8~?oLj-3*6wr4#){ws z_woJr<>3}OinGu6G~za@xMm^E_{Mx0M?`y@Pf|9Wo+ z58D6lgC~k{_)hL#^J9m-Cdo_m`@z0F(KXBd_IsYld3gJvL|7{z;)< z*(G1#K0s$yS*5UCHvk+DcK+ozEQBj9FKmri9UZY|=A#qAC6(-^&ODB}0m1b)v6Ijn*3<0_Ja&Gw2@8{a4W^_zrXGIf}GVJ9_smfw{zUY+yiS&eAAj z18@Tu!oWS>fD;pXM0R@T0y!d0L^7BbBrVK8yDm}$A;7SB$LrSNf)_(eL)>jJ8^r`> zF>dZ(nY~Y8imhXf0Zv-q2Y&@4gk*oFO&KY<&-TBZF*beKOyw~Wy{NhkNciXH6awfR zTi(xaJ2v1s`w~M9#so}h52rhu3^{m1CP&$#4C6laSHAH#_U!%hAr2XAp}p}kmL~B$ ztx>S<#p*EPg)xF3${b#-XvXbeRxaZWeY2=bG#a6yp-!sr%@n4zEb{5!CICc?d2{3C zc_)zf?>bZW{v;w>o;vqi#n4tHe~yGgcdpD3yqp$)sJO6Vhi$E!A!H>Hv~veWZ9GQgo5c(K_tL$#W(P{)q`Un zFw9s!6aoU%>);8_mxtpj!WqJB_`ko8myI0{&#d-r_ir>uZyf@V8EYEPhdSo{xd$q7 z?>WZE;M=|w9Wve6Tr|YObVN`LH6A9iqlc7+H5Sn}9f3YJLURP6OBRe)mM*O- zo5IQe>9%!>BH448rhYr04*tpeH1}wZTr3M|*)S4IeK1<&T!}sb*KWES0PqHAKp>4@ z%)^{@WDj?#GNpCMxV{QAkl(5l^=7w$$ta_VqEor1E8yl42WFC)zwq%-Sy*)v`f<)GrS4L zg&n7yM3y@*j3SIi*lv#Rsu`ta5R9cNT(eQ5S`8;~u#!*%O;#=j@Y`i9U(#Y?FQsMG zKDqU8w{$VpSB->5b>2-%EEDFE6in}BW-BOeH@Y<+VWPRRR`J* zAh|`YjHec+#QdrrDyyLj!(tl;OMM_K@QI$?>CWZGmQ|YB*{VH=9zVeI`|Qqe>M8`@ z{75T|8(rbeN0N^{pqjKul25MTKJ0|g#jrK(masEBDe-tce9(^(i_Y??O2y-(k{CWV zO0m)d%8wrmqalrA>-2@dof-^kB_l=i^sMlwpEDkLu7@Ul-gtrxE41wEvW9r=4!l76 zit)Sqn=$lr$yq|lYO5qilv zhq_Z@pw21|d!ci^+i2(rsxC*hC93@FNlToAeucBqtb?PT13rwIduU*{^HIf4YVxQr zbZ&ZCHei2CNG`I@XOLWwK<%yQYDH_Luf=3;MK2w`lcMO$kRl&H9rkQQM?y-R-ylNq zQ42}YsMgu(O&%pk%j)n?m0qjXtgV0Kx7O=k!%zPH3>c$vKpS`XE#D~9X0n+T?S}$3 zDe@-?7^IcxLuNnfgy{1>ZU5|+H|#Zm53r7hcE;?NAO&iasimn;Hm31<=ASg@Wb(9~^lGU*A#!;IyPvMPBD8M)-|vM+ z-lp6a_4Cz9%745Kdib;<#Fbvn=Jot31i%&*_NrG$>H-uiO84Q-GNVyDd2d)C+eh(q5uEasGWLOc z(~M+{&K>rpAj}a!ge3hEZ}Z?$-&h;M^ORtZY!Y&Bq<-oVKUNyIzK$Mazd}+z#oSCv z%`g-0=Frr?dsU!PteO0z_pO@3Y`iAY=Bi_3byI`0v7Vl$iQzYLp;hv^ki%=X8g}V1 zARwzHe+Cm!XrA?@RL;`awsiF)|1wEhU3j}~i;Zf53YS{%E}+&^@63!k-zGPwEJe{F zK0CFt?n6myFt5255CJt~YjHca4+wQR&Fw;XPd`-$`w|RW*B})ccw1g9C{cCwLB?Zo zN>=}Al?e7KQx%(<-Hn-mxLya{6DwyB^|l-w^*5YMnsa&T+jyBkMMJL8=VTxVgrdT9 zksjfzAm1TZSa0XErTY0j$8GM7HFIlzaOo#bFwazFLRCF-pd-T{$CDQ2PSQAg5Q2=r zjjSDg$@5NUkdTLBhUxOd@n|3o0~#DzZTo#63cGvZfUTd05`{M#Qa(=W6_?{2O9ZJi zncToNR`&eUrVV?u!7sx(l(2`%ffyG4g@$Plq*FNtbwwd?>aDlc%vwcdfm(aDMFL2Re{;5fdnt-mHrz#d=G= zDO9>kje36J!xB)Qxi1~KysFv+$P)-9?{$q;_&3~Uog8#@?A7w0s5&nN zs9r~1o);xx(;I<%WV2Myzkq4e!2akQ^0vcd`1HfG>Z7AA002bj1Hd))49c<9e}Rf5 zK-vKUcrZ>1;EG=OZ=nnVV)*RYPz2)THA7dZZ-d<@WD8!_(MbaiU`bIk?1>l9 zag_w`CUurP|1%7Jg~BdR&R*K7O0jH&Y&U$<^do>ktl8cFyd0a6N?VRGmh`b%n!-?w zAt6aS6G22-+R!p35-7+#EW}(ZI$80TlG+3UlpG&XsCY5Gy8EM6GrPd%CnK#;Q1;x| zPvhV2=D1Mbhrc&|*vCUZ^gA6iPiFWGb=jDh;D%>yqk2y-zl?3R3d81KSsu6Q3WL&J zLIk@;ojKb0l0yjB)==HAZ@vSc+%Y~W*MZ-RvWybxW`57Y;J*v|8ynlhYM>jaPJ*s1 zCl|B9j8XTatxa&zvOGNuW0@BKO&)3v5-=l>w9`s9Og;mDV-#7WlPM8oVNo85tFtz^ zXm$+S)_<>)y5}b16gzsN%lXScz}rzBd3*i2XkMk#YD_30T;-P55mGuLIRLu zuN;-OZ{=bXasFMno=Xh3o&3{~REEAL?QeLenp>ma`fh0><&T+~SIwN~W-|M5Eqw=+ zuJMldR6L+%(Nxz`MJ>^xCV^$dE1WKHA2L|57Tn~PyZ5ri*ueWA?Aab9WxX{7DQm}q z&aGZL^50J3w|Y+N8U7Re?Z2TPR?~5C%Wb`F+ZkZa3F3D$;d1XN57=vI8KY4<31bX4 za6;Q@TH+ADemOf6G@y{vxipeB}GPz^xvbqpSP$!DDf> z^{LzMytlHp5Z}KD0y-cU|Ch6^T0}@x~-#NGu^1_7CWgm11L8`K}nh7g9Fh}8ZJteucO^L0vo029Fel{Ud%i_=JQ*&Y^n=-vU1EZCJlCpe62fD0EC8EI~X_sI=}U`v!?>YTpuDTwPdUWim0 z2!PjI0f~3W0iIlC!QLBVdLidMKB4D-v`bVba?v<|0Gpbber@Y@$J28RJd;%5P_ucq zfK3l?9N9<%4M^HU#nAGKM44p3_vNskC6k>qezDd=vI|p;Jh6l~oGI~{b#ZrzDLK!8 zGADoG7d2j(8XJT^G$f_^Z_^v9Jdkjkcut5aHa&urlo}4zOOIYYY$y1B6!`%=G{jdL z|1B;)!tC|X((mKzCIVhQA+{EGcOxrLEAn?WqMc;i9_|*1BkV~s%H_OL1hv#=*_0#& z8RX7CWvt`lQnN5oZ7e>jn^1BU74r;-6$RA1)e=s#PB|1t*2k-*25muxU1P1St%W|A z+gOMW_dS!li1OxH6=@R+^{MCZatWh5bvR}c#KFyWbT;opvNE!;%iS@qtcNh+;(52? zwRn&P#Sh!b8+DsSR-O&_?IFx&ch%J=Fo5X-7$opjqMt?qW&kf zE%vSTGA%+obh6Pqk;%_mfNf->^{z`c%(25SjZw_++LJ^3#b>pRdv$Srm8afp_`mip z`?{*HIdI_~6nW5kP|D1DvQ3xRacbTNg?a?;T~<)FAc zcD-3vwa3JZ7qravz)qn@kI!a6Dv~7T!yJ**1dh#Np#uoyQg~)dFbfySr44LW;V(Cw zb9{MpwCIY9yZ|=_jOEq7NDp-&u8dh0inS4e9I&a3Oco5@WY`09rnzgT0^s~SZoHpO z4-!C9u}g6g3x#!d3v0QOM6M2N;<{rFPv5BW8db9+J*&HUC4;cQUU;?m;cQJyWGy&I z!{5%>cw&pr_R_&&tRmEHw!>-1y%US-6?C4t!W^g~c)lmlrUheIT z>dsNEH%IO2xfo~{SmUb>)GUNJ3MH(6v*A*4GU5TzSXE%f2^73@jlbAcO?ERe)z&mM z)HK!Z7AnZaws>x7b{4X2sVSeeS1ShqjAuQ2$A(tpZ{R%^B$n`95JGu&ndX2Hl*FI1 z9L4R;df?)lqH<4cTwuBu|EI^|>@r9?!UVi$MHSn2QiEqFwB}RfFaS`01ck@G`P6ur za>xX}+n4a=$$*+F?1e+%u4)7ML@ROH5O8*6&4Dl!AY}(Hf5`z$&vJUE*@!bsPfhXl z?t*&8^mgEbE|OAvHE71)CQUhBdRldq+X8Z<28R?q!W|y`c6_u(ZG@2W)Rs{w3SeoC zl1vfaGN#{lvT#y$Bs<+;f7OEb)5^W%vhTGRT9v`>VW!=%Oi}5WT?UU_M``>oa{VjI z@K2fQT0N{JQr7dP{?q>tbvUfWLegg(3y2Vx7M52QrdJl0F=)na{g?uGDpuM^x~rfl z&)hEV!+zAo^1KXLn>@4RBUpC6)K&wy5jab=aBz%aHhK4v-K&kbHquRaU`^eaW#hOe+6}x zJ>vdHtHKiCeM$X?@M?lZFO$Ka4~n$O_-rRwb0vH%M8a|*VA6vVhlBiI zesy|3tLvxl;d!|2Fdy^UAAbVBw*_fhHw4^XLn?sUj;GcbDy@dUbiseu~f5s0C1 zA?eBFWfntVxWG;sZXyGGpwEsge`7{}aM{FFPTu87OS#xQdDIiqU!;koWI~1(fybVd z1K`0+;GvI=Ce3ZiduJw3O?-3j(SuZ;bPH*${+S2Ky4c-kp(a%3E*La-sBq=25YDZP zRvi_a-HzppVpRdT%2zmRX{K`S9{e5gQE;cVc{KBBZ_c!^`?=N;NvGO zdcD-BaJO$G|L(Vnk)*;E5BG24TGVs@JdF1f#P1Q3xXT_d?xtrWr26H6mPB0Q6#Ezfu=F72ny~fz%Vy~(h zbr}39d_);RJ=R2FUFSJQ!AF$r>jZDh`tLG&xs%~K)JgH7jYpFE-1c3sK{sqiJi%W- zD?InI^%X`V5O$a^URU%)VRLbWISrY;2NaBqXYGM|6Pb6>&LYWIdPLKaO`C(|drRG3juoKzeO3pI-uhl)^H=MIiG}_YQ1%{A*rmf(TM_y)TEQb0& zc@`~MBYKwf_vQt@C@BYUQ^xfRUMN$~Pp?$r&vWd==+C5oFD&KlrB9`W3||?)xM`1F zu!PIV%$CO14%R>G|Ep}dnV~uxsU{;@JwRwO+lM>} z>s=ait52K@8;OjfE^Z6ZD!&H%-%(HvdM%+n&)cu~gvy-({L7hQKAbgJ52wa$=Wp+_ z&qL$V1c%=~FuCQr6G7eG$VI%j84TG|S*x@O-rlZDh5)BArbGKJh*rwl+=E#qHRoyN zQqu1`r~-!AcB}4IJ;Let5Xu748Lp5583(|edn%eBhsbyQr8B{8nJ6{T8nS5W+yj$tp@oULr`cp4T4^ZYH&p*m1);)+tr1S$P zjs+qxGn$ydKYz!K>11r`Lyfg2+cmicb!_Mkcagntcm5G)3@BAqGK@YGgw&0|?b%~A zX}-#fHJk+q;YozwIR7?;gTBTi#20Q>YG~}WOWpLk#o%PqdoT<{M#-1c%%cIN5!Gg? znQmznJp*5B(*fFRF5R}l_a|a6B%N|3ME&r0{K)9{%E<(HGyyhn*~tM9x=hsTOKYd= z_d;_3{kLrOiGb$(?sjOz&Ko zT#`0>xZ__WV3QKhqp-VP*mDvp?4VG{PCqLtF`lc$KAls9M^uys{FeBLKs_hSVKg#q)I6F0;qPg*wIX;7VqN4r>H_^g3)a%H(TyViaPIREBsH1DtSRtx5YMBW+C zQ8fZ}glh-Kk1r{>(ykq?t`VCo3PMleA6DP5vwR>+R3W{i&QjUSFum)TG(vh^l;}tv zxAuNLZjDk%?YR8fdDEq{@%$7Fxs2ASz2xY;PcaR+p~@GBJlwkk4RBs$D0Hl}*Y65+ zoTCn(Yy|sGHib6f{^BM%(}SHSkzF!&z-FDkdk#Z`k4~drZ#fccTauhvf7XD+pI%%N zqO;#Vc1`*ube_@O1#b@UO?gb7Igo%tj)qG=E$R-mc;5)|X}%1p;_2xQ?3fQD)9~ix z3;lvgHvRTiVs#hO{~`6ORQv#{f4;`sg=)uR(V1+d zp?yxrZ?0>p^Mob!KN7xtTKv%Eq!5)UpqDKy=)G&l^zoh6EWXDVeK`EkCGP7^FOnI{ z>X5F5IKN!yPGW`o2TUM0?`l*=4=77a>^P5e2{^Mi`pC7?4t<&=2W84*w>Lf5DY&42 z2zWSy%_;wuxLf5xwGDueFM=QbjmKf|-@63gd^I(oSn4=AKNy~i3O-A6{&dl}`U;s` zGrE~+;HM-1$&N$5_UFWE<3LvYULp8_vGM1R<(na&d_g5~*e5E*>$};R0kRqcxi5?x z1Fr_sOzk~|JAoIK%JKh<&pPY-C|2sA1T&l-?Uw_kI05JKK1D7^6FWS9`Pr1>e1i6U zmFqsEC|o>kQHD);Y^b%4&`y) z!wtua+I6exQxDPWYZdH~sC4MI@4;)G7PrjVhI`MRg@sOCT<_dUiIw-OS--!Yb!yCn z`cS-?%nv>Y9gBd8sq`_0f<|jRMnqVUC_ksZ`Fv|4)aFtg*tFYbw!#k0&%2|?{UYX{ z^bq*^jYiP+OPJGS;pL;;QjW72MI|#1va$oekuksTv7)J-OZGVDwl=bo5Mz8*{vE+y znBS4uSw)u{Ga6ct`KQUW4T|-u){C2hhkJ#B0+E;dB+8D%1%Gk)1Bn*|O!lu1dZDnp zBrABDa|yl_2~p^+$z0PL&8>tuI`gC z_QRyHY-Z3f$!DA%I&x&GV(8#mIX^eAtDE8Zhf?CNTT4yHbTo0K;kuO);G6y9N7Aam zvY!>rDYX2Yf+i+9n#M&6A#XW9wr^E_*GObo_9DwHI4n?ws_2=vpXz@aRD8o>Kxj>= zM@T+m2=y~E&MRjk`rZMyc=>^X?PYMha?`*b_eGMM1Cr~7@S_^8he7Hd7-0BD5|6C5 zXx&oNoS5J>O7HIJsda@MD2$jz+np8h9$k@XGhY^{G64AVotz|(Gpsh+wB9L`R2Z*% zGgh)|q-=)rZof|5K&KR;f2Dm2n>K-Z@dnTnS!fPA4jZQr0h2^VhImpe;(uGx>)b(; z23zKW$A}lP+I>q4c8#PXXn>O3>}XQ)Xwu2RWIR@(yCzvlUumuQCLno?_pQH9?zPUxPjYRnQFVw1|3Z@st9_G3gKGCQbET>7ZS7Z}N zD9G-%>8qwuYnOo*Xz)jKZdIChFsU@}u z-v@xSCOf&;*AZ**qlw>-7YHN9&u+c;*EeO}x4vfP4&d)2R&sthwUVF#;vFNSDH%TI zx6_{5<((rr>Z4{I@?+h~%=WD+gAx0H3jl8Xj_*O=U{n(38F!@ajeL@I| z7_v=AgOIGnIS`R7sXReUq@_#~0hC0iDM|lHfvl*+CoHz)*X9AV_|PWP1irFFVr~Wl z0GhdPptjqIU__~f<fDb=Oth}#BBmi|g;oJujE1G+Jr-AtRc4=TV5S>rgD=-r{W};EOW%O|r z!dx)^Q?$;!gqi36x zF$9^P`M#kDcv6A#oBLAM1%!e8Z1Ea zC}FfY2^`zI^fNTps{Y<};jHz`SjV`6iRfJinQ*&c?ZCGZua&ElS?f-3y=#fr1K5lN ztY_)8T>kff>C=>#NdEIOC&$ZBl#35)QqWb5@r~X_P+6FC3?$t8U)}Zc=b?0pBw7 zeg8daF#IT+e8V`QB5_?PLg#o1H_2MiyL7-e0|U!L0zv;r*jGkH^@Z;aB|{IPAU)D4 zDcvYYNH<6cC`fmAN=kQw)KJnbCDJ)`cS^?)_xStYyVm`3*Zl&VS#u8S)ZXuY-Y2dk zFQ;9XYh- z)okmf5jaYusrJOR-3@SM`?q8GT+7q-=i?Z$CTMrqhKEO00nw<}xn9h;=YIRctiPg` zmiM{U3Str6lFv4~(b@ENX2(TWb8S3X@VNQQsjtsN=yPAM6L`nNY>}tvs*qCx1_rg@ zQu8IT5aMa|+xa=+z{%Zwd4npsPztPkINQry?}*EFg|)9&7~l$V|zzz_;&YZlonb3Xkj*`!b78?TRq+Iz+V z0d6-@c*sM>x3^?Ajqb(?X-U(Mm;n8fa?fS(g_YZ|bA#`_f6<2F%^z;PqM6nc!lwsQ zD+1q(VhYnWZB_y>s_8g{i0fm+g=uzUN6XQ{kxWcpbD0=o4bNiqzfC^h zryjka;COOd`<{O*6w^`j+P}8a*Q>WtQWi*t5SKeW)5gkV%YdI$UU?;(BYyl>87ceP zIv$kc?@wa0HyZNsoSDPJ#X%Ea5T)0?cT^qs7S{#~o0}5@J(00S(-FO6_WQ}UjmAqR z3dn;8<^AnX@e&M;K3}%t#oYL&0KPkNSi1EBFzH2T!_lLlil*FzkLqD9)7F`bZFW`xu?I!u}vBugs&Ysd3R(B#rmqvH*w~Gw#5@jfo!A-fpDS*yFRZw)3n@|Q)qB*Xq<kmRfuJjuOo7nAWTRI+|^J}KE@H^zJ)k?ilBxn#gSyNLZ>Eab1IakW?XExnAU zs?OVPTCo9UsB0E1m%d*H{`C!RJO5MIWq0*d`#fZUui`?578=o0Hj?G$JXos7$No~# z$L_qon~vqpQhPg-DnVswxo&$w`9o(HDjusf^IVI!5R2Xe84$%%Z3|~Cy`NU{{jpft zOQyAGzf@D-))MuW&+DrFfNow9<`AtiNO(!_gf8-YZdU z*E^^4T)(pPz@u02qt~%uz4TO$w*Dq%8+8E*ci#&^Hj%Q)F}M)LV?@LAtut*`d}(+1 z?Zx%eb=D){i)qeZ2UdFRh}74*>cnTxcN>YS`$ge&gA0_XAgd4wadumIY2@wuL~1`v zQq%yfXK}zZ&lT^;n(Yr1BD2`LsN18Yy?|*tAw*UhM?SDOe3t$CRuLO?-rCx&(4q77 zMY?NK$(sIhHR}=+5j8Ik5OQCC10~6#%?a{8tP(iW7&#|+a$U{vHWQ4WsH0B$>;`!uW&=;xR z&V|pYTpyDW+xnP$-qu`_z0e{EQ0rb=(CvpC*71z5BzBsev^3j1ML!6uek3`{j9pu> z)z+fyq%r0G=yRoQ>#($b6E_lGLv7SvI_|3o`D8!DBlUoK`O-fu6mDWPv1RKc9GYyD^NFvLE-$B4oeWlN& zXp+>D5TN*t#Q3=DAg;nL%3iR-kuBoBD--(hD|3my!Ssy~-|~6B)N3}DN|LoUDG6YSQG2ZV12=52aSLU@ShWF0oDuA(vHsvacqkB}M? zsXooObo(guA{pU$i%du$!Pux*MbU2t`4ez74`V2FqG(uklaw31Oz~4bTju~n;r2~I z0WB~Fb>f2LYa|Zl7@5fp8ZPa3YTX9$FxDY=-75BDG54Q}WqR$og?T(bt}k#teE48t zWH&sqKezYky|t8-Fe7SMzp0HSGfH5y2$mf2%1@rfdCqq82ZFThRHvVqVnPlM(#67Y z=*}8+-_IQ@wluBz+3BE-=A_*SO2n#+ZzUg!b0qC`-@A7;lpMSnshRs!K}ZO@x_cXPi)ydrm(#Q=xI(-dEyh~3{uZwS1{ zNk!boP%TU*bMd_L2Smcf7TgfRs5}K`-W_DM7cO5H;6jOXL^}XJm9^Kry~!OP{!>|T zG(q0u2gskb@e1X@=6+c5NHnwoz4F($k2C$X}}ybX>ud%h)s zVk+0)EOd3bX*2t?r*a^`+QLDngsiD&cg8e79j12>U#~IewPJ0>fd0(!-s?|5=~`m~ zFF7(q%{<%9Jb8_e>y_KlpVAYbOBOM2pOq_v{>!RJyed*6ED;e1E8ER9U5^~TNh5Bcovm}|C8OrjRwR08J6%J{5Gt5q5$kegf6 zyzxoPT}sL%$5U|7Wb1j|sgaBMMetESkl<1~A-*>bSngfoC?zK(VY|2##3|KUC^_Lp zDHd_q;gNrK3=^ZofIRm|lt+^23@XR&b-B*=y1&U<@@81*e+IMCJq^}72?a^q+!31$ zHJoR6h{T~nR3du4sPa{j83kDQBO&@mEA(bB2m*(2Q+D`oe=OdCkiizU$x(z8qP-(ri-rF9mKR(2la^EmSIYyRH-^tHly=iNtb=8Zg*JuR-sithsjKDwK= zHeCK5;6$WZX-58}pv(vi6Ih#Yu*ma;pXNsNB_;iVh+P*6Gu!DmcS2Elqvl3L#Fm9_ zQ}Jxw_D@ClmfCI3O-H@fM;}Mv4VTinCf*gITvHv^hS&3DFPxo~taY{Oo^Fi9&5PSW z85E2Ou)CoLc!Twd3Hm;FpbVy&m6-jgv$Pv=E?X$-@8WRp7Tln8Ev@hY3X1S~0-B?V z?fLItOEBD#97JU9?uh zUK7+Z<~19Crp?YeCR5Z>?`4Z3Kz&K5K8celHxew3l+8J{ESLa4kb5Af&i(>of)s_o zR9IVd^&&b~ikr9CIt z(=+g?9vYu)BxreQMOk=gAd)W!`IqvFA0=faV7=Ulh`v(o&Xa3&WM1CqTV`8q&StBN zqs2b}Obi8`c)}v~Na@}U5stCFDL5}wngmn0%q-XUB&0k^%@}U2az{jv*$hQR{Ve}% zDYEE!!XUa>cWI$FZ*J3eZJK?%Yb~`v5+{WH_% zTRPa*I`_|hYx}~-N5+-Eq;3~pQwjRCdeZ6|7*gR4eTY6>T){2pNT(1O<0N>ELm}o6 zd0VE%BaKkX+9e;=NRkQtP)D(w5tfYFvak?3StBfscOtg9%xC;o{?*h{gQH=8f!a%6 z-I$;B`lKq=y^2VLBH z6G<>36{d~uoTsK4VILGJF;H$uPkMK-Tzs(wE zVozOs(J?K~S{l1qEaA1cH7qVQR298>AlhcMG;cvET0l;`nS&J(2&AY|Z;ZT`B z0XI#_6S>M??M=7r5OIVUpR3|1>S=bq4_nP#lM8YTdEYo$ap7A~marA}FEke^T09G> zG$3E;aEvj1tA@Bn-ng1hOgh4RzEb%~GR%b71tiH7R+hpz00YU42lSk>dPQiYu`7=JqKX4j&U zCgd4BCUW?OhHlO8l)?9UD||e<_$tQd#`HSW*Kno7|_ad#N2buk=43zMslY{&Rd%hR>_4hdQ8RDTfST}eK z{OQ{ob7}ov1`GHul%?%@`3yDaz(aB=S)yqw6$P2P;C`!(L5>MODmgL7|5#d3t?dUF z=~YbB=KjGTVO#%)s6reZPX$X-eD-Ld(WBjL1+*PmdgRIu9_Ih9-t<0@S~f z-Ucydp+H5yy|6Wj!XcD}7O1Q!_Y0g0o8JYL#33=XZ%*J~<|g!e}+HI$!yhtiYbnrDa157MN(2_H$<#Z%k10 zFQ>as$HQA`w90i=cHaj9m4&Ehkyt+o;jDhs&$GYB)@r<$KzamuR@%2DxO#}<)w>EM zqAdsQL3LLJTRz@aVBNNSQH0w2?yz^}sM*XCLWGG%zmwjQU1#P#t@c)B86Pk(#4qe& z`4s<>fdn@_Y_!19Kc^!$)$}(Q;S5CufnH&wh6YKRGnhMSa*&*TaU4*W$det5$=QsQ z4`YNb4v!X`wHqljfW)OSm_F@Hpi$zYK_C$0s2l~sL{mnBpMIz$Qhh--pKqN6H@e(d zV^cHh=)!~UWqG?a)mN4MH;}zzA^LKycEfFXjLAmdFpN(>Y64tf=!U+WEO=d?Ix?5& z>zZztiD7526jB7|P9#=1Mi;~_a#RUZmWft8%w$L)88oCsZW=&sO3tdU@eM=b+#dZ! zF>6ptc3M9K3YP5)zVjz~&JX-IqOG>3YIQ?{jvZ_Q| zl1DeMRsMw9-mgZ5pxWlDEZ+_X=Kbi*ZH*2%Dvf}=ZBjm68Y|JojQ~*dGeO2)ODF)H z4>A7x6?`@mldZAZNW_F!wh+qr2W@dVbK!4kgo+Bgk(cj*M&!R|v_2*xPhb4M4~M(z zby0yW9X%0^-XDy~>kwTu+_x%ISEnLZXoZ%=dHNyh6Iw)X1sayzt1-falar_+P^UOa zkopn|GteWC$ZK7gd`7K4$%_ffNedy~mmk5TIy1TCt;kS7tP2rUQXT})ea9e}}a>gkpB=6 z3FQX7l*ZI286|+#$#)ZcmvZJ0?_BSv&J9 zP*56-5Ujqh%r1Jr8i-d~`1g$jh#ZarGAcmM$ZO@pfGVmjT%VtKZCS-oh>RPkYCPUc zt$awktUJvy`w~9D^y8Klr^UtC#33yOsUte|KtWOA{csJos_tatk6e8z6Ay>)#@)8c z3SXd^vIP_!qo}ILVK`Ak3em+_T%;JA=7a(vD56rBSs7W(-~b()HwS2eq63S21Ml@F zWXE>4xoPqVfv%PUGry9;hpjl@qr2(E!meLmO}^4w-99Awo6{HjZP)S)r3wjfVmM_h z^;_5=@)(IjEqO{ABhHda`4~+Q*OaAA$6D=YLJg)2)dIYyzq`fCqMt19eveYkdrd_0 zK5ZG^Utz7>{fYL8Q9Zx{+Q=v!H}GsqIb~_zb9vv4`O6KbEo+TEYdmYJ3EuNs!+X`< z+4>GdWd(AM)iIE4EZX>t<2wB0esI(UdlAqS+D49e9W8YH&i}j9e!<|sZ1Hq-YFZRh zvQ}F==jpqHXDT)7{XopXgR=zOj;Fs4w>L39f;MCwx3?>#?pJzG_0AWQRKC7X;ayfR zE042crNqj{JwBgH6ruK~ORA13>z=g7_18Y0*LaU+7QP?2X|fU79UY}pRWD^qJ)MBA z`wvp!VP-F$*2k1hVzu61LEPhI3(d5amsGYLOd8%TDEcpVAZGk4@B6jtvaHcVGw+9P zLZ5cDG|%gI<_V~|n;zp0@3bcm@fuu0!qM-yxD7%zz3=47jIOgrrbS9wyE=x31eH(${B-prBZD+xO{mI~SxSpUr$ z^{L0WdN_B*eLUjpD82kD;Jk8r?EoU$AkEP6 zn5_hsoNyF?<0GqOm*@zZNg4&wc6RwOiQt*CqJl$M8Jj>5kT}z}!n-`<&25Lsgv7Vb za=dbz_YC4-I*7jP-ubOp5qo1#3JAli3*FPqAAh=YNhWOh(*0_b z$tVvA1d_H9RdXE7CmMGNKpfA$rEH*0JYFFn#H_G680; z*Q)oT_dhodu=MD(y~Xwx{Rr*~E=b4=rWXmaMCvG1qXim_EW3PAP?&PZ3Rj&80(y9^ zL;7|Hjw<_abRzCuPXT*0b@?w2AidR745=aFl6JK_CV^8yL1kbn}Ws}li1gIE$| zMHRG?nX2Xg3|M`3di2& z?jl~P&8^%uZC}udyQTg_Kp-QJC|l;%zqI0P;VB9V+Ee(5ERLZ$sHU>4!BQ0z8uSs$m#ILO`&oze_tCxjs}l4)Iwb2)Zt5|b8aES$cY#lJ z_ojx87T(^pK~JMp-bgn0m!nHfLmW;*=_o;x$4Ge+$M2=j2i6`uuSBlSlVJ~aVs{TM z$)j7sYN2Wygp{Wmi8ApU`M4PBNjJ5QI^v8;8SjG%s=WH}o<;)$yU0YJ_Q(_lbNm#e zl^TDuehU_cKhvJ%sG^8565tk*LZLHL$tL>h_4QX|!dr!ef$b6-*=+~ei*u0=8tf~J ztZm^X>QG+yPaN0P2pe+I8btBJ-SJb;!yxlRJWA$5j8b`r<(Iq;7XQIzSLdZi3WR$> zE62PLw7X%Y3MT9)(`Vj#e^|Y|+1z_dlSybM(dng8cJM2;X{z1yp<&V9`+Aw;eeHg| zRT8OogyU;rpcV+e0kq4wZ`~WVaU@txZ+65;Zuc6#@RJ(2;<)PH^s#WwM1E#9Q8^UM z^5ZAM+#})70?W{l5@gty-)h110GOB3GU~pR7t0Nz+o6U;qp}Ux8L*Jxrp&sKO!G#9eg&DJLS`6WfZnhg)D^Is5PxMi zq9(^dIJ2YXlD-p1{_%wfN*eu+4X256134&P1;;)a!vGGA{h>{qH__+$7etcSpT8Hb zvi&Vt)surR%`&fDnU<1EslNV8-5}pj^@L}aS?yhb^&K`gOh*@Bu(6g{e-1+r2A#SM zDJq&7DK}V1?5(FKh3E1njw;?{s)Z^WZa>J zW1kL-1@~kmzcUBCcfm_Z*12Q`QqRmvAo$25D?rx;z)9vN-B(+D1dmO zqqOQYD{@plzs*`^!Th&(10R*=7y1661A0Pd>gJzOpUv5| zR16JCr%<3zcJPv!tTkBI-dig^R<>aDD~j}?v#=4ohU>Jo2{*{eauXjN&bHfD;_31X z4MYE-6-q2jchCpQhhzDP30&Edm4w%Q<}m)3)S zH=l%SG#-M)1pTGl7(dBG1BtkCW|9z%A8D+j{W@I8J$0cY=t9Ae+(4HXXXm%YEg&Hm zU@mINNc5Fng^|2qBJ=&ink@Le4`qv>^M7vuzO-!P2cz*bXG33X6INkj6-5UL)@-{> zc$O+Yfi}@k3L(*M8Y`0-eJ&l4?t4Faf?9vso=y`F`aQl?aobVyi%KizE?Ea89!!h) z_Y#p+F(V3!7$Vv>&9A=-&A0kIo%Ezu%4L#q$g-Cg*M*HY(6}_efoTk_1>kPd5h}A*k~u zVQf;;ZX~DsM-8)o%MXWMO$XVs8eD2rKUCmqg8Wp$1Fdj*MhLPFqg!m=#l=`|KFTml za?GWY61}5l>nq&t`OtGRKGpy~=LV{5@+gB2d&Q|(>rmWl`ZE~Yn`O5OJ`wvL*P9wz zY!*$QPR4?=(Av5u3DVh|tFP*hwY>-b7=c0NE$sLcb?1Rg6d3qAORL!mf<>bY=Oux~ z9)xI`Ix7Tg;WPd{iwZ?eNb)(B8i}>vt07*G8PtAuYsUdtN)Z*&5tqgRj(~}cALrG+ zJv1SpHn?6Q3xvh+vap|Dc!kihbl5+SQS0x_oMW&WB%1B8)$Z#WQNd38dr66qr_wS_ znJ}_aJrC=6+m$ZdXo=AhA9MtA(KGz1hw2tFH+kuysA7@z5$BAN)|2IhkVlV+x-Wev~54opf% zqc5rUQbUIJ_IE!Yr8libFWBg5V3DW|b0uh5Z1A}sBo;5P>X8w**M*n;tF#mN7C;@B zii|;>j)(foSB@&bcMM)K#h`h0-B1k5ZK!k{Q?67aei&;92L$G>Qlh8f|J)QGwd3ml z3k(JcVZnhZ)V3~HQ_8O(-|jH)N~hsT{rS{8zLw__+ypJm&m5bOuQO&ILLJ|+?r#j8 zr=X4ve}Ve479`Kqe=U#xc`RgC>IhOQa?^;q!%1|-0=Q|x;qm*-&)+t2&A5<91hGYw z*d!)M559Wb+bf{N-te+CVs7|sFR#->g@Mj18IbEYT7zvwC2aSVk*>1IC92m^Kq8Hp zHyPmu9~(NG9&~09*@>H=J~|@9O@gzRvcFZP&U>35SEVFhTx(9dtgW_=7bK6Oj+eyS zcUe8)M6Frh*zV+IM9mag_|4KA6%#`}U1iIl>gq=s^D@12BCzZh_($vKQW96-w9^k^ znr1SG^&?F%ZfBr?NK8|dyM)75Kl?s)s>5pPVY$q5oWH=$(KMXX7(XduR59sXg(Y|+ z{1`tTm#VG1Q@&EqCjlRGAwdDFwgIGHL^N<`)XtC(P!MdxO|rBq7g%Ng46>1J+2af8<9=_k(1MQefHtC$aau(bB4rkr*`ya_~QR0_Eh`l%#S3)>cKo z>vMjhw<-%Vz+vr6EfjzUOg`QVmDr*t1|r#RFHK+zrG0<8{{=|xk<$YBM-jm3{fhkC z+$EmnSrLvJi;D8%tvE6@5)WH^4!q^GEFtW35o~zn(>;!;tXv7AJZFWU8xYE!>G`Os z@e2O$1C;)R7TV~D#=me~Qw8@mLI_?-VlZD>u?MZ*Z@nuy@0MjMT+JZvj#!O+kBy}! z_SltA^Agajl-u2pRqwG%iT??n$A$8nViSB%B^R9G1T&$js>=DVO8(|ndlBGCImzo` zxwD;ZYdy*HOL){&A3o4-kv;2RS2e38NZf1XNV}6^KmAox#a{~GW^z?5#5TVZy0Teu zagv2I?nqwitmVAkhgkP;%0fV8)91amv)24LJz}-<3Owac{8Y z)HjvcxttqjvBa0yG*w_hoyMtm_1Qkx%CDUId4~zYt_((fpW=w$w{oiQ-u)5tww>Zk zVzb_#>)0CKiIKM2H}#2t9xgsj_&)415!iCYFRdU3xa)Psm0@jvZ$>Fsd`k0jC5RSF z?@C8R^eEjA_cl!QBT)xx#TcdMU%(yL|mKF{ehGa<|M<@dY5lDTC@MQ&s9FvLR>GM%}R2|U0Y=O zW1rZ=N`)Su?|Ckp;=xSs=}?UCjru{?(#rkmjGL6m+s;%9uk};|g_`6nA9HFP=2GTy zh0!MjoT@n3-#->8MtN8o-M04oFah@=(F~xkmJlreXOO!M{pmqwwC;G}_SZ7Nq!gZu z$M}=mw&Lq`y_Wg$&Sah-osDLrXmx@Yv$;j(l)jShal-=;-1SMNwWV7dQC$@OP) zMe`9MmAjFK_3YN~6FgLJ{|UDeSv+eWV=6xHTLmsN&k!4c)4K{AvvFHNxBN30i+?+Y za;>#~YGEjthwyeBKphJl&tcDPci6DbZoHm9oZ`SqKxI>i{LALL;t3Dw-C$6vk8Kc1SCc0lF*(Yof8vmf%h<8lyhla8a59No3RPW@Q>DNDO_r#%i;!;{!*{-;jceo7H zkeIj2e#!IRQK~18X4RpbcF!qagDq5I?1R9mg9Y^T+#Y7~j^WU{zr(JJnl|6}lM46Z zg@EUrD}F%p^~X2vhrtY4?nM>0T>84uJ|RkM%-FYjy@`L_c&p&? zCUJPEDCNZu?6ZE#d5_g8Mzw|nccmg6aGRvht2kt!&W#UG6-ZYJC`f=1($4ktOl1u7 z$`!7#SKVayY)t3|9k) zC_T32^LC7XT54?qRXujK`yF2&AMKHe&hh$j!eEgd#)HqmOcDdB1OB-x`Cs=k$*k}w z1*d;rH80pKkvwx`2<75iarF(1oAYkuR{sdsrbyH`8rIS>)FY_;sCgt-^%QHG#8$## zxY$hd^Zrh0(XlQ1?>?E0j+W`6(1c2d`6L^kL0b*G)8TH({507~>ro$Rt=;bCZki(B zlEabZCXvbXrG!Blj7ex|+N{s&1>cN@hUN?pFJcK8UmW2}E(hP!CbZqnoZpt0mlnO+ zu6<>OQ}=u;Q6uqrA@AiSG+x?L*QUkhcI*@-y@7&Vr+Tm6`Lg~1S`g6hStyL+7q@$~ z%ReqvHX?Emx;mSx%NscCy&pciSB3;=^mRl%a7cTWTF+_b-&EY zaFQJE2{;{2*}a>Rz9eq25nALVXDst8Ic)>H3nIGfEf#|`WRQz+?S|?;s6@}7dN#<)v z_mr}|AX<6)vu7Ybuda`7jE-;4UryCq$H?csqz{&q4X1V_PnPN^1lHLQm^6tU5+?zS zCG0~E2m;2%Ft5i6GlsZ->Iae`1Vl6JsBTU=+DbU}?Ov+#Qk)d3vhj0y*_p2rBV>*n zP1Q<*U9Ej6rz)F_-|HYA4MaZdh1%+JiP%|M^&j?`nYFkyXs~`9DtgwR`ZRL@PrR!_ zckbZ3+#Jc;Pk95CkJz;K&duv6$r-Pu5#>aiGt9dzGaBli2aS+gf3IfFnK%qe- z`CsW7K%FEzH3CptNfId7f5_|{lE+OW8N?Cvr9TN`5(LoqNKU=lsR8kb>E?^GdI;oI zqzZdFA+k6sXTVa5wqbqx3}-bYc=NGMuR`g@?>PYpZ;BK#yOB@n{q$2>ofFLGX+?4jBdFT z9H36B=$p>pxmR5p4a-f8?mtzGA=xI|oSdW$@@sjUFk2FnHMYA)JG~9TUhT&De_~V#D?_mj*+1KKG+@vf`?f>mcWRNn355r4o>Q zon6pN@;Zo8`uDxeuy4;VnZR4~m*+zMCMkYcuf>6jY|dEEsQE{D)P7DNGbCB{*DH{^ z>t3=|$UAy-z53%C`4<|}L)BS?3k&qNP3M9QMl{(PYJ|RzvjhGl6i56R-5NNbubfuI z3pLo97AA#A^i;R5zaX+!1TY5Sp}!Y1Y-?H&$}f7DSv+u04pQi@_075jGG*b367mea zeFZy$p#biNHs?_ChCJfTM$Z}wfG3hZ0pok)@8LlAH68Y`uCZyv)V7iPW24855myUb z{K7^z`Gj>x0ADf=GGYn>Mn`@z%piy?6QDN377tjnVtAXQK>M9s4Mz$(5{X3}WMXV7 z85UgPzn-Z&;&VOp^+hPN&*xJg=3dueBiMmG2E=2l$Lw@N`m~puhFA=j-Ai%QS)U!_ z9k7!b;}(mUUQ>cuTCLNY(NyjoKR%JY<5+ark6r$B(+N<0BX&KXC3#Cm5d+$toxfN_=`I7%)A`PFZI_*N&6 zGuSU((HUoi_2XQ^;X&4R*VgbB78OH$)LMZ?(@8=zK}hs&ibVB_GWD4 zC^NpCHYkQdSTG~*G;GV>sJQ6r*jApus#%z8X2toZBagank^A05Xf)LcWw<6B-j7ln zPa|~QfWk6lE`#e7*&{F2A46{Xxc?ky{4t(Eu-`FpYdlxY8eNcKov!Qn>T2yLE8ciF z0sz(&wa34Mov)7;;hcNw@1kaCDln4!Ontfpeg$oPM_f}Kkbii$ZXa*qa?H<>vaMk@ zzJ71J;`o*4NJF#dL$;t#j#W)L?U>K15#n=w5!bxy`px5&|0k~LX_4Qt zvLqwFh?#oBwKZ*hQV2ah-Sk(T~_pi%tr?`uKT`L@y^-SNhWD!Yq{1b4FX= zpYuM(J!UOg=d)-{F~qy~SeF$D3vuqppen`CN+k_}eM<(0+$w}7*h)1Qn`_QGzr7wo zC4;{^PsfW%K(kL9kAx#HlX(z`x(1!!naUwaiBDoQ!{Cm1|q$Vo$@psv5LP&1hpw4fFtcGD3HGwLUv z#s^<>-fVvOWcNEY^W)Fs(x#Do4BZ!hi?DRZ2F#fUX^t}U%aUjQ#cY#&#SOamqK}ah z=3Z#@L7@`0Z#Ftpc=gdhM36^Q*L?U>U78F_X6R=pnw}%Q( zQlBNG0eK;2biW7aCSI}-*fO3A;g(mvR>Ho>AeAR0y-Jzl3E%*zG&6}egxukq`q4Le zm(L$Rl`1c&uP9R@1F6}x;?)xbih`2^*r%ZfWqBEaZaN8D+ut2;?Y@|q&Bkh1Muwiv zUFgq5X=uJhA?1Bgyqp#sjix`3l22Aokls-(5zteg)(BPz;0O^%4)f}gRWqdP&htqD@{X<^6$%p7BuvmH{~By*Q9E77>L4or;||_PD)y8{;B!_)P*sD zpx7vx@3pQj1$}d6dkNI0D!KmTAT1^SKc);MfW&kpWzem)-d)3#sYlmfGEXC_dP(o& zqP@f7PbVh2+ysGO@weS++XS+aMa|6L{3N@q^y^zW&0ltX_I5@^Np;U5{ty1)JR7$J4jAq9?yDJDIPwc08D>*@_C{?h}xXb?l34^3d_#$x41h zm8tDK{U=t|+UImu;bV{-i|+c(cz?E1+;=(+75F7Taq~NkIb|Qfx~3QeKu-W*3l67m5r9hgH2(rqBGtNra&*jvNU!mE`;BC75|?B>W;po?hVcd@i@1(|zG`P`jNP z)C1-~!p{<4n^qAuvwB$iHfJ>!(26*IOh{^D?&4noYWWoNBb+1Pn z{Q{Z5BE8?mHPNHC_>sKW=H@$IxmC|n29YHEFvP0_y)^!jd8AYlu_Q`~r95IG7~@AbInM12dnhNA1UcsP_B|3)Fe+FjQecO`?>5|20rDv_ zFu2T;6Z%>7xN|)r7;>(5PVx#BY0n*-Ib)Xi z0pdyzJuvjeMuy4j4h*M*_kCXnE9;P_KudNDv$}R^+b1R7vDXi(3We zt$Wjs!uL!_v7ia%&SFA0mlT!3JIOxjI`DtHyYU@0pbqX>gYiKiiQVUzl*tef0K0u{ z?~}xY#w80r#Ageq+fgG0aBg$v9(+2Pj1jq8$1o^v1{7Ie-CeYZ--V%IV-Y?9o(t2Q zN1tUqC^sZuDdZ$X+GF@70A_qmjD0UYdc8s=Mg~#y6Ia6CBdNCMoo#6-86xV~w?(R{ zrFY9yT&`N%YG!sa00Ye~+ciSY0NXc$9=)svn`n8!ID;JOaK$cbwDkMxq;cn1$@X9{ zrMZugLG)oQM#M+hIJM_5;+KSP=R`p)!FrBTOy?$F$LVirB+`(VxOX&2@-#PN-_o;J z;KlgmDnHMOV}xDZhPa#qjXHJc(;WrI6uAk`LhsF2MzWtKulYg)MJXHPMs3HnvUZWACwT%2P$7~`bkjU?IsCO^$*N#zVS*|ql=@Xd zj#kzIzUqtoc!+A&OP|N3VEk`tu~@meH}k3EA924}L?KgOWO&WE0K_&qzR9=7my_Lk;3!QiC=Y)ek zt;CCYU#+eVUklsyPhYw?Z01slir9I?>L7I}rN0zD8$PjR*Kwb;^}X=O-a6OQwHJF4 z9yDJsdJoULzVa0HayF>SZ5KV332hL4+?^pzKYse8V|hU=<`FJ5fbO%kvE_2`1W-L5 zx66DlH(bxEN2o*|hfpIcVHljX_sa|Lj*A|ek8^hmaQJ+5CqW%vt#21N*X1DrC)SqryvHcJDv&4Nm`b0)I zI;WVf^^;KsxoEFb{L(^F58emSn))d-qV+U~m@QxNO!kP+Ml&G!h25|+3y%^i=abOP zx}VKLSehR8L%f!!83mW%=mDqm1XQ(-=y>F^b}M~l$%ybx0`{Ts1FqaXL5VSYa#L^)1Jie!|@8b)N1rT*r_?|3#}2X-hd_fe7H z_WJZVgTIs=M*7j8VZ8(BxdcpwL=GM%Zhzir5)uDS*U0=gi{k$c#1s9I^lJeX$xa^+ zJl})i zEiYaGlGm8rzKJKqDx3vw(9v4*tQY~5dA9AhMMYtVWZxUO<67D=F(uh6XWh~Br@!6a z>9CfWY@4TjrD)&vZnCFSrN=4l>n=q$?%>vG+Wf`?Ay zwx7&m6PFXYSw^i2wS;>0R0Ak!lw^k_A53320S;iRSiLk7Lztmgl)_`21)=g%jMo$L zh@vL^q7nZ<>*yEQYS&|HGu7ohpN_}YaFciEqyxUROPYA~JyUz2@D!vkWBw&_bksH( z?Di#y`nN-^kPCT=akJ8=D~dhZH3AMkfuq#nX?(a@l0-C>AXjnX&jhsERDn;yy+eD^ zOx3MSBS(vC-spH)qKXTm+4cXcQ?qSmq$b+w`ImUueN_f*3E()GQD`iqd)?&?6b zw)@M|Gi5kEqNRc2P}*O$o6>zf*mRbP9RrbT`3Q7xo-1XlHqEY~qQqvUl^8hp7u&KS zx<|b!VLngZ>AE!o<2&_-de>{Oy>2U??vBm+UQ^C_RhizoK3!3D+=OPsaBlB(uQO6y ztPTbPp9zgGui z&AG1vIR1=&z@eQhO{%%-uCS(P698xjFze--Y^a?Pd|AqxVu|p!Xx`0L4^dDC*9byy z@rXx@BcVE?5?mOK-wvpl(IF6!)5?&WL|gSDm!g8b%1RFul`ywL6a{5 z&H48^;))8s?)wDf4h|rM?mcDY*mZv=(buKwNx)C zguU>CPkoN}U%2m+@8dqj)u94?wuM9c2yMLF*{5d`)P+u10!ptDlTYU{t{TzzcU1RM zm?7r`tc+{bU`7(VLc$9lrZwFZw&37hVvVSVSJwA|oT&sMfYqwET1OwD3ti(5w zwRYu^N|(n+j-qG&m;Kj=qhFwh+e2tEipWnOB zq8C62?tWF%eS3i}&YtQl|7Tr=kS@NYb&Q#1@I|G*YxnwC{gF(vO>6b|?_<%KP@V`3 zoI5sDBwp|7!Y+Nm%s=yMHKqGM2Iyi5q~+wK1Z8O_DJS$uE&o?#*BuSl*RGE-7$r;u znIJMc!RVrgLG(7tAX;>S=)D^fz4sELOOOz~Cwh$_geW0;5G8~l_vHJ1Yu&Q$ANS55 zvu3Zg_ndR~nc4fi&-*;j3-@M~hcd&Epml0RR%z)DjT>0l`i4I0b5rq%rxHg5OY1=p&Nn>W?9|M^DOKre`Db+qBB!l z+`^)il&LXd@qS~b;(9E~(wfSLJX;V zTEIWI&Tl=jD?GczK6LIU#r^XIi40s+sf6#o9OzR}dvMeF&vMz9(wv~R@R@)^!RL}! zAF$HL5`S3UC0WmWIbV`~dp`K*{1kMpdecqSzP4U}`LxkXtr=tCkSVRIm}wwQ%8YoH z>a$uEd>(P%|HS8{vVM4G!EJ+5^jBB^pMIGibK}9U4;uG>&tlDT&n}+ahckV7%S}?) z(^n?_^Sb#w*6B+zDcf?^A;4<+fMZ22_R-^s7Y~-Lniz~)Jg#e;NS;rDv zFJR~()9GkvXduaC-m5;rp;Q(=AZ~HCO|6IL5TQ!@k_oM%_UxFR7IX!AL9V2WH8a$v zeeGVstT;zV>5Jnd_&%_gr`hhYDX%y)*!>ypux&8I(Sxw$Tb#L^B9$P$I#j2d;i)8( z9d)R#5#axU*vOR?tZid#`B`z(>-KJ_?neF&KLhGzho1sZ>g&qttGW6(DI#y_&a%Kc zwmVI~^@SFF-v+Y@e?09uk~qBDmT)$dnsnVv8tr$u$rHZ~N@B0O-PVNY(k9qyfEPW* z4Ad!gUOX zONDc^$qT5f1rL;gnTjS*g21_+pOZiAM@e`g-PPWyn38*rO# zOw3WfdC^@EkC)jwL`_MiQ&-1Oj5pi`Q|<;zp|5+?vJoA2vl-7-$3HVsz2-xwu6)~E zz5E%P3WTW#*MUh`}##A+rS%Cd@9VPyFzJc7UnWJQ-)30UPpSE()p=@^SVRJN}v zF+?jY#0p$DVrB*{)c7F18uB#jav<>1jd4M-+!dMN8KcH!n*X&PM?)F8$=z)$%H9M#u*k?X?Wi7YmUY|?US+yISue;}UPU17eg z$QP%=R#za}FQdT7h=e`^>5_YEM_BWw*DmSrstoUQQq7xw`H7_AqX~XC?AVLbwTZFp z($vGX4A63cRyqZ;EFS;<+rv(`BR#=C52(d3Z4qC`Tx*|*oEt9feOGRG&=}j-F%_l( z-M)yYvMB#q_Kvz-n@8F}F8W1e;7cx$95NJ9D1Oyad&Gv8uc!MPg)aI!JShU7W&fVi z-}k?)mVY(D*zIrgAG`?s@b4zrZD^i#X~#@u$ZYZ6P{gj3LPyGt`+u5~H_qIL-LH_- z^$GtPRC9iIooO@o{301`y!Sf=8_0=<1x}7VfTL;KLr$^b(9R22xan-v^FIP0g#Ihq z*Z=4P-yaD%`47#GtjH-2(6x~B?@EKc40&dbWeh(m_JOQ9rZ*-=Ww{GT|(;M;R&$CST^2v}J|S|S-k zA|D_V0VcWk0Falg+VmRvPP`Y+sKX4G$xE&a-ouV!53-y$rNfzU9?{4!aaNg*t3+E~ zH6W?*1`txM?K7bg7NAP7s`tLr`9RwJ$!$HwBI7WpxtvtBvvaNmx~f=EvXrz;>D&lv zkX{ToR;N^iE;e-7t55Qw#YNz%&N%i_hV&+$;M$kToW!! zQXxu{1z_qqyzIf3i;>XPz!1u?H>KLK1*yq!w5djJBF5pC_^|al$rk~kd%~^-Rd+Cu zP!^9MCGgJ;GI0!_<)>oe%yDl<#`h#WK1LuqkNkHnlnago|F99@Q)hrHvX;?ByV8Mv zH$ZbIR|>_J2_|wBnh`r&7qqzLVFI@ffy0r90H|mxNwt6$LrL|@dZ+cdI>^WF?vlPQ zIQtGEX3UOc1aNI_(=7wKGwWCmSm@51!@hM)6aXNi!?++pI&S31*GCP1e-5{907@|8 z5E+svpS^*kc-9?kFTPDznYEx{l(1@9!;VSruHdv#v=s{5mCf)YYvc_nJz)UbDga~8 zIpt%dj^inzRDt0Wj;@ms^xp_V;->0XOcl{eg;rUPp@>q#Q1jd)_ZW2y1Q)eb5D~DL zHfy^D2i9Af9Tx@O)6Ed^r_KtHo}p1s{Ed--2UMWJ(unQ)$U%<+i~$2tD=#SwKt1OX z&FAto`#v}Qhy>_C+Db&)6O!o;Y_RY{Xx>QK+i|1};@N5BGi>tw65+0BK(EnZm02Rj zZD|gDWnx1T1jq}1xHVXw2M{hBLmJInfrv|5_mch|g;|-$xw#}ovhHk7`fZY7h3zyNSw-~^a&hexX|5n-gtUAF6_4O$g)zGYZUta{$JTCphM z=M}^#WOj{KF>oX7u(_>gN`MS%ErRXRt>eByl0Mja719eT6Kw>=%D1G4zg4Hy-<}lm zh~;0-YO_4!=@P>Yc#@FI$v*!|btr-_J#3!8LF~()LKO6)n`pY`%FBBZ5UnNxx?t@w zBrW#as|$I7_Ec1Yyr38xap%5ps)NI;O(&_A8cRn93lF<=VLgR}+oD##?^;NEpH`=Q ztxb+9?9PJBkTLU5EzAjKo%$#%gX{RxK~9+pag;)Dw-nJFVQIZgCY8REGFG`W-r%A{hRDa(a}<;_ZemWGbB?{*G8Szr~}(9eTvp z&YfvAe@Yp6HZDF^%&53ocm7SIr^6UqB=t2!_3*Mpz9>siPg#_lKSe!-IypsLijsBJ_=3Ad zZ6&Vbt<#?m9w;NDWQHxNPZHt*erlO-e6+qVx-NfPW@)$(A3lv61C%_Hq&^By8<@;Z zdwqA=80cE&`_Zpb|0Vr)e_tu(?m`*!S{h^A>1hHP`8CbCCIPkIiaI|%sT29}7Atr; z@s4k8&W2uA;ZGKoJuP)IGTXb~^!UlV7W$|&sGIL1^t=30#|>t&oZffq6X8{UZQ{rj zUWV*y2YrjZK1>_v6f6CF4DAO0>SA?pip z*=Ao0_Kts&Qi^mY_xPbZ7M0h&0-L%3A@B5q2=pvp$UHr9ZIm zlFImv>kQmZ9iooo?<>hwwZ=b)lz7rEJ)rYm(6|397zVT+t-m}w-pU^oBVz?O|F8Tg z9I|7e?=e;={V5xp4a6EGHP_rrJnrdj(v!f!UHq#$iko zUzx2tgV7r|WxZJsMD8%{H(oo$lON3H5^3F-&-*Q=^t+jL3Hr`=cYZgrmb*oo|wzP(Ym z_4XR}l>z1sg-H)!U$DGUOCi~eQU~xV@STbGB!!ruF^eOXevkF_h@PiICxR7J^?br z!+NM7di{lMDQgHO&eBqytB;jGRUeaand5xd!Bv1g(a;vX)o?kG|4E6p)32l=~B}Pna5sFr3}&PI+O%?vPh^B zSIoIv0~azR6-?u~+H3BrYu zv2UY+$s9s*mP?M`Z)ktfZ{$Dl5YY=3_{6 z%_W`-UdZA@q-dvcwu0tb9IQWxE=$>-wrF^&*F~ncB+4Rg!kGiK8@NClA)q+)BXV?3 zZH6QGGE6(zV}CKQtnZW4+?4sZ{KeW}i%)C_BuQcQBODNt3LgyhAgKnjdZv_&P-eO@ zp{bRAa=y02IYm3p9jFxz$)6vSwjlj*49qhQ6L$C+%|~AX1Atmzb|XrzY6EZs9bur& ze^vRClt}L0VnBWFUZCGRzrkF3sHDnV`L(0 z=JUw=)aSwEmV)z3P{Nr;UyXMJnw5`b?hwO59!nTQIKLE5zQ@PEyd-Yzkfan*?vF~5 zdv7`TN?j=LnWN&V5>r~%sCa$cPreL#b&1rK7(M5b-6mrtSlo6rN1v!ED0eo9TL|NO z7jqX9&YVKN>Ko}W%#>Hvf3C>ZUy4CJO)_wCEGP^12@uF40QhEZU`SA+M9`wox_xWO zl*jrV1kewj3Viww><|3eZTi`D$irp$=B?pq4h4~ngw(XUo*!THlS01|=P37k7T+?} zy^fHS>Sjdm2Q16LoAP6^X`}gjV$=7fMU!2m0G37*HnGOrY{)6dL}j9^hncUnp_4*e zHIwA5?~BLg9&RGGMsvrTTZMz4+g7PbG(h|$@0R_}9T1y*_w#9y_yCnL4CL5UvqLvx ziIGrCh~;-10e6Dx3Gb%Q9P(cVPbtVxPjYE_?Sxrv*lbnL&Iv4C6@DE5n05Sws(E?z zra8%wmj>ByB5auVij9&dgxCSLGLhs&GFP;=7rteOF3pDjkx~1L%2NeOdNcyL~x>Z2oruSe$+w@ z<+iK^5-3OVf1Auig2gKM3UR+6SBXn}mmP^_ikVQk?x}CHuXr+tjna9!DD0Aw5#uan z7%yulJx@stWdmD3d+68x6XVlmEBnC7=(D#MUY0|2=CW}68NXz{OTp)l#&iv^=~27c8af+M zbAfWb{!3;#W*yFX5~%7*31eJ>+8F4YEi|RYE6Bgmr(*G_^Hv=0rAj~%vraxki=TR3 z6fjX`H~W9_X64cDGi2YbdTgMNHPWX9YoDt5zpbdgYf2eI^kd*xERk}c zWuUGt^NqS>gnFE3b`AqVeKst;A2P}OK9CvAl&I1c6*qeG4IWQ(WxpI!<;lF0rIv9| zh_@yl0Ky9smyjB4)6)`=u#%mOY1utjJd_RI)9vk=#`ax&c!&oZFJ1w(Gbf!L7g=b@ zDJlbv4jV47z7BwpFTH7717ob1Ex}VpHSWMG2ex_F>xHzDGDCvD)#klWMmn~*iW19l zPp1S+^oFe(Nk;ezK}#-w6fBf!pKtO*w0p1Q_@j@u4!u!L)uepWApIBCM~_m^bL(@= z7;KchBYn43<0mzctzJr(USs#n2pDMFMWfZD>F4p}pPM<_j^>+l@7Kl{ie8)KIEi8u zJ7t-I9cC6lKR2wp7TW*Sr^vYIyENNxgG*@fs+$Qjh|#m4UzcXhc*P^?olppNJaX+ zpkU3}ZbP$A?j||JXuAVXPM^htsZZLz8#|(j_I5`bDvm^yqZ~9koQLscJAMZc{rLl- zb{{VV8hVk=MaXhfe#3{|xZ$1)ugJQv;lNVzb#}0t4Q!GlY*VE)_R7`FuxZ$oq zh>SCxUVktl<2GH1D}ZBWI2E*1mcfMycmOgGXga9FU;t+^?uZ!=h78z{$N)<$Y}Gwb zGQ3doE!~HK1ew9hDvCx=`x5k^4 z%jkd;{dzWiTa7dA$-%)(eOqWKyq5_zZj{6ugoh1XjV7g!bq9d%U)K^AuZ!2!wQ;Av zPGwk4T~;-1<|&~(P<5|Y?Q|6lKQ|})MMlFSp)|u*2!qFKzVtT3WUClBuQ+xLB zxp*X;I=6=Bv}_H-8T~ zFE8a~c=(n{yfmm;&Cz`!|LZ5yODC!t!9n zaUJ9BH~}WwLvhWYV>CW*mID9M89RtM`PI#ZRtvVJT~=9bl#*|HhPQIZ zGJCAvvd=zP%}S_fN>PF!qvp9%!H#ckdrmgDGUri)f7VFM#=&sVL_3$w;esh8)!GFG zDQjZaYR1`6slEIR%Ib6j^k}))IMl1kZh9|I1pntdJV=M;Ukkte_!ZjW!Sa4>*Mb6aWAK literal 0 HcmV?d00001 diff --git a/docs/plans/project-workspace-redesign/mockups/preview/b.png b/docs/plans/project-workspace-redesign/mockups/preview/b.png new file mode 100644 index 0000000000000000000000000000000000000000..f436086d3b03c979c7deeeb674dc584e17c4d252 GIT binary patch literal 117225 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%0AJN&GO3ZXa3JS7YScZf(oJr24j;D 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 literal 0 HcmV?d00001 diff --git a/docs/plans/project-workspace-redesign/mockups/preview/c.png b/docs/plans/project-workspace-redesign/mockups/preview/c.png new file mode 100644 index 0000000000000000000000000000000000000000..6d36c220059beb9fcb1f0d77afc5b5b9c8963f21 GIT binary patch literal 109048 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 li { border-top: 1px solid var(--line); } +.rows > li:last-child { border-bottom: 1px solid var(--line); } +.row { + display: grid; align-items: center; gap: 12px; width: 100%; padding: 7px 8px; text-align: left; + border: 0; background: transparent; color: inherit; border-radius: 0; +} +.row:hover { background: var(--surface-2); } +.row[aria-pressed="true"], .row[aria-selected="true"] { background: var(--accent-wash); box-shadow: inset 3px 0 0 var(--accent); } +.row > span { min-width: 0; } +.row > span > .title, .row > span > .sub { display: block; } +.row .title { font-weight: 500; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; } +.row .sub { color: var(--ink-2); font-size: 12.5px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; } + +/* Section heading with a quiet one-line summary. */ +.sect { display: flex; align-items: baseline; gap: 12px; margin: 0 0 10px; } +.sect h2 { flex: none; } +.sect .sum { color: var(--ink-2); font-size: 13px; } +.sect .spacer { flex: 1; } + +/* Definition list for facts. */ +.facts { display: grid; grid-template-columns: max-content 1fr; gap: 4px 16px; margin: 0; font-size: 13px; } +.facts dt { color: var(--ink-2); } +.facts dd { margin: 0; overflow-wrap: anywhere; } + +/* Notes that need the user, listed not shouted. */ +.needs { list-style: none; margin: 0; padding: 0; } +.needs li { display: grid; grid-template-columns: 18px 1fr auto; gap: 10px; align-items: start; padding: 8px 0; border-top: 1px solid var(--line); } +.needs li:last-child { border-bottom: 1px solid var(--line); } +.needs svg { width: 16px; height: 16px; margin-top: 2px; } +.needs .approval svg { color: var(--accent); } +.needs .changed svg { color: var(--warn); } +.needs .missing svg { color: var(--serious); } + +/* Inspector (the right-hand or drawer panel). */ +.inspector { display: flex; flex-direction: column; gap: 18px; } +.inspector header { display: flex; flex-direction: column; gap: 6px; } +.inspector header .kicker { font-family: var(--mono); font-size: 12.5px; color: var(--ink-2); } +.inspector h2 { font-size: 17px; } +.inspector h3 { font-size: 13px; color: var(--ink-2); font-weight: 600; margin-bottom: 6px; } +.inspector p { font-size: 13.5px; line-height: 1.55; max-width: 60ch; } +.inspector .actions { display: flex; flex-wrap: wrap; gap: 8px; } +.inspector .note { font-size: 12.5px; color: var(--ink-3); } +.metrics { display: grid; grid-template-columns: repeat(2, 1fr); gap: 10px 16px; margin: 0; } +.metrics > div { display: flex; flex-direction: column; } +.metrics dt { font-size: 12px; color: var(--ink-2); } +.metrics dd { margin: 0; font-size: 16px; font-weight: 500; font-variant-numeric: tabular-nums; } +.metrics dd small { font-size: 12px; color: var(--ink-3); font-weight: 400; margin-left: 4px; } +.links { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: 4px; } +.links button { text-align: left; padding: 6px 8px; border: 1px solid var(--line); border-radius: var(--radius); background: var(--surface); width: 100%; } +.links button:hover { background: var(--surface-2); } +.links .why { display: block; font-size: 12.5px; color: var(--ink-2); margin-top: 2px; } +.empty { color: var(--ink-2); font-size: 13.5px; max-width: 40ch; } + +/* Metric bar: one neutral mark; log scale from 1 (empty) to 1e-4 (full). */ +.mbar { display: inline-block; width: 56px; height: 6px; background: var(--grid); border-radius: 3px; overflow: hidden; vertical-align: middle; } +.mbar i { display: block; height: 100%; background: var(--mark); border-radius: 3px; } +.row[aria-pressed="true"] .mbar i { background: var(--accent); } + +/* Chart chrome. */ +.chart { position: relative; } +.chart svg { display: block; width: 100%; height: auto; } +.chart .axis text { fill: var(--ink-3); font-size: 11px; font-family: var(--font); } +.chart .axis line, .chart .grid line { stroke: var(--grid); stroke-width: 1; shape-rendering: crispEdges; } +.chart .axis .base { stroke: var(--line-strong); } +.chart .label { fill: var(--ink-2); font-size: 12px; paint-order: stroke; stroke: var(--surface); stroke-width: 3px; stroke-linejoin: round; } +.chart .pt { stroke: var(--surface); stroke-width: 2; } +.chart .pt.training { fill: var(--k-training); } +.chart .pt.architecture { fill: var(--k-architecture); } +.chart .pt.refinement { fill: var(--k-refinement); } +.chart .pt.composition { fill: var(--k-composition); } +.chart .pt.dim { opacity: .18; } +.chart .hit { fill: transparent; cursor: pointer; } +.chart .hit:focus-visible { outline: none; } +.chart .hit:focus-visible + .pt, .chart .hit:hover + .pt { stroke: var(--ink); } +.chart .sel { fill: none; stroke: var(--accent); stroke-width: 2; } +.chart .frontier { fill: none; stroke: var(--ink-3); stroke-width: 1.5; stroke-linejoin: round; } +.chart .line { fill: none; stroke: var(--mark); stroke-width: 2; stroke-linejoin: round; stroke-linecap: round; } +.chart .cross { stroke: var(--line-strong); stroke-width: 1; } +.tip { + position: absolute; z-index: 5; pointer-events: none; min-width: 160px; max-width: 280px; padding: 8px 10px; + background: var(--surface); border: 1px solid var(--line-strong); border-radius: var(--radius); font-size: 12.5px; color: var(--ink-2); +} +.tip b { display: block; color: var(--ink); font-size: 13px; font-weight: 600; } +.tip .v { color: var(--ink); font-weight: 500; font-variant-numeric: tabular-nums; } +.legend { display: flex; flex-wrap: wrap; gap: 14px; margin: 8px 0 0; padding: 0; list-style: none; font-size: 12.5px; color: var(--ink-2); } +.filters { display: flex; flex-wrap: wrap; gap: 8px; align-items: center; margin-bottom: 14px; } +.filters .grp { display: inline-flex; gap: 4px; } +.filters .pop { margin-left: auto; font-size: 12.5px; color: var(--ink-3); } +table.tv { border-collapse: collapse; width: 100%; font-size: 13px; } +table.tv th, table.tv td { text-align: left; padding: 6px 8px; border-top: 1px solid var(--line); } +table.tv th { color: var(--ink-2); font-weight: 500; } +table.tv td.n, table.tv th.n { text-align: right; font-variant-numeric: tabular-nums; } + +/* Lineage list (git-graph style). */ +.tree-list { list-style: none; margin: 0; padding: 0; } +.tree-list .tsect { position: sticky; top: 0; z-index: 2; display: grid; grid-template-columns: var(--graphw, 72px) 1fr auto; gap: 12px; align-items: center; padding: 6px 8px; background: var(--surface); border-top: 1px solid var(--line); border-bottom: 1px solid var(--line); } +.tree-list .tsect h3 { font-size: 13px; font-weight: 600; } +.tree-list .tsect .sum { font-size: 12.5px; color: var(--ink-2); } +.tree-list .tsect svg { display: block; height: 20px; } +.tree-list .trow { display: grid; grid-template-columns: var(--graphw, 72px) 44px minmax(150px, 1fr) minmax(0, 1.4fr) 120px 64px 54px; gap: 12px; align-items: center; width: 100%; padding: 0 8px; min-height: 30px; border: 0; background: transparent; color: inherit; text-align: left; } +.tree-list .trow:hover { background: var(--surface-2); } +.tree-list .trow[aria-selected="true"] { background: var(--accent-wash); box-shadow: inset 3px 0 0 var(--accent); } +.tree-list .trow svg { display: block; height: 30px; } +.tree-list .trow .ck { font-family: var(--mono); font-size: 12.5px; color: var(--ink-2); } +.tree-list .trow .nm { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; } +.tree-list .trow .pu { font-size: 12.5px; color: var(--ink-3); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; } +@media (max-width: 1100px) { .tree-list .trow { grid-template-columns: var(--graphw, 72px) 44px minmax(120px, 1fr) 120px 64px 54px; } .tree-list .trow .pu { display: none; } } +.tree-list .trow .ms { font-variant-numeric: tabular-nums; font-size: 12.5px; color: var(--ink-2); text-align: right; } +.tree-list .trow .rv { font-size: 12px; color: var(--ink-3); } +.tree-list .trow.related { background: var(--surface-2); } +.tree-list .lane0 { stroke: var(--line-strong); stroke-width: 1.5; fill: none; } +.tree-list .lanek { stroke-width: 2; fill: none; } +.tree-list .dot { stroke: var(--surface); stroke-width: 2; } +.tree-list .dot.training { fill: var(--k-training); } +.tree-list .dot.architecture { fill: var(--k-architecture); } +.tree-list .dot.refinement { fill: var(--k-refinement); } +.tree-list .dot.composition { fill: var(--k-composition); } +.tree-list .dot.sel { stroke: var(--accent); } +.lk-training { stroke: var(--k-training); } .lk-architecture { stroke: var(--k-architecture); } .lk-refinement { stroke: var(--k-refinement); } .lk-composition { stroke: var(--k-composition); } + +/* Lineage map (horizontal canvas). */ +.tree-map .tline { fill: none; stroke: var(--mark); stroke-width: 1.5; opacity: .75; } +.tree-map .tgrid { stroke: var(--grid); stroke-width: 1; shape-rendering: crispEdges; } +.tree-map .tlabel { fill: var(--ink-3); font-size: 10px; font-family: var(--font); } +.tree-map .ttitle { fill: var(--ink-2); font-size: 11px; font-family: var(--font); } +.tree-map .tpt { stroke: var(--surface); stroke-width: 1.5; cursor: pointer; } +.tree-map .tpt.training { fill: var(--k-training); } .tree-map .tpt.architecture { fill: var(--k-architecture); } .tree-map .tpt.refinement { fill: var(--k-refinement); } .tree-map .tpt.composition { fill: var(--k-composition); } +.tree-map .tpt.sel { stroke: var(--accent); stroke-width: 3; } +.tree-map .tpt.dim { opacity: .2; } +.tree-map { position: relative; overflow: auto; background: var(--surface); } +.tree-map .inner { transform-origin: 0 0; } +.tree-map svg { display: block; } +.tree-map .band { fill: none; stroke: var(--line); } +.tree-map .bandlabel { fill: var(--ink-2); font-size: 12px; font-weight: 600; } +.tree-map .lanelabel { fill: var(--ink-3); font-size: 11px; } +.tree-map .seq { stroke: var(--line-strong); stroke-width: 1.5; fill: none; } +.tree-map .der { stroke-width: 2; fill: none; opacity: .9; } +.tree-map .cmp { stroke: var(--ink-2); stroke-width: 1.5; stroke-dasharray: 4 4; fill: none; } +.tree-map .node { cursor: pointer; } +.tree-map .node circle { stroke: var(--surface); stroke-width: 2; } +.tree-map .node.training circle { fill: var(--k-training); } +.tree-map .node.architecture circle { fill: var(--k-architecture); } +.tree-map .node.refinement circle { fill: var(--k-refinement); } +.tree-map .node.composition circle { fill: var(--k-composition); } +.tree-map .node text { fill: var(--ink-2); font-size: 10.5px; font-family: var(--mono); text-anchor: middle; pointer-events: none; } +.tree-map .node.sel circle { stroke: var(--accent); stroke-width: 3; } +.tree-map .node.sel text { fill: var(--ink); font-weight: 600; } +.tree-map .node:hover circle, .tree-map .node:focus-visible circle { stroke: var(--ink); } +.tree-map .node:focus-visible { outline: none; } +.tree-map .node.dim { opacity: .25; } +.tree-map .hitr { fill: transparent; } +.minimap { position: absolute; left: 12px; bottom: 12px; width: 220px; height: 56px; background: var(--surface); border: 1px solid var(--line-strong); border-radius: var(--radius); cursor: pointer; } +.minimap svg { width: 100%; height: 100%; display: block; } +.minimap .vp { fill: var(--accent-wash); stroke: var(--accent); stroke-width: 1; opacity: .8; } +.minimap .d { fill: var(--ink-3); } +.zoomctl { display: inline-flex; gap: 4px; } + +@media (prefers-reduced-motion: no-preference) { + .drawer, .rail, .aside { transition: transform .18s ease, opacity .18s ease; } +} + +/* Layout switcher and inspector key. */ +.layouts { display: inline-flex; align-items: center; gap: 2px; font-size: 12.5px; } +.layouts .lbl { color: var(--ink-3); margin-right: 6px; } +.layouts a { padding: 3px 8px; border-radius: var(--radius); color: var(--ink-2); white-space: nowrap; } +.layouts a:hover { background: var(--surface-2); text-decoration: none; } +.layouts a[aria-current="page"] { background: var(--accent-wash); color: var(--ink); } +.layouts a.cmp { margin-left: 6px; color: var(--accent); } +.keylist { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: 8px; font-size: 13px; color: var(--ink-2); } +.keylist li { display: grid; grid-template-columns: 34px 1fr; gap: 10px; align-items: center; } +.keylist i { display: block; height: 0; border-top: 2px solid var(--k-refinement); } +.keylist .k-faint i { border-top: 1.5px solid var(--line-strong); } +.keylist .k-dash i { border-top: 1.5px dashed var(--ink-2); } +.keylist .k-bar i { height: 6px; border: 0; background: linear-gradient(90deg, var(--mark) 60%, var(--grid) 60%); border-radius: 3px; } +.metrics dt.chip { font-size: 12px; } +.ov-row { display: grid; grid-template-columns: minmax(0, 1.5fr) minmax(0, 1fr); gap: 32px; margin: 24px 0 8px; } +.ov-history { margin-top: 24px; } +@media (max-width: 1100px) { .ov-row { grid-template-columns: 1fr; } } + +/* Map node labels, dataset rows, documents, preview. */ +.tree-map .node text.nl { paint-order: stroke; stroke: var(--surface); stroke-width: 3px; stroke-linejoin: round; } +.tree-map .tip { position: absolute; } +.ds-actions { display: flex; gap: 8px; flex-wrap: wrap; margin-bottom: 16px; } +.row.ds { grid-template-columns: 22px minmax(0, 1fr) 90px 70px 20px; } +.row.ds .kind { width: 18px; height: 18px; color: var(--ink-3); } +.row.ds .kind svg { width: 18px; height: 18px; } +.row.ds .path { font-family: var(--mono); font-size: 12px; color: var(--ink-2); } +.row.ds .path:hover { color: var(--accent); text-decoration: underline; } +.row.ds .glyph { display: inline-flex; width: 16px; height: 16px; } +.row.ds .glyph svg { width: 16px; height: 16px; } +.row.ds .glyph.good { color: var(--good); } .row.ds .glyph.neutral { color: var(--ink-3); } .row.ds .glyph.serious { color: var(--serious); } +.preview { width: 100%; aspect-ratio: 16 / 9; border: 1px solid var(--line); border-radius: var(--radius); background: var(--surface-2); display: block; } +.preview-cap { font-size: 12px; color: var(--ink-3); margin-top: 4px; } +.docs { display: inline-flex; gap: 4px; flex-wrap: wrap; } +.docs a, .docs button { font: inherit; font-size: 12.5px; padding: 2px 8px; border: 1px solid var(--line); border-radius: 999px; background: var(--surface); color: var(--ink-2); cursor: pointer; } +.docs a:hover, .docs button:hover { background: var(--surface-2); color: var(--ink); text-decoration: none; } +.docs button[aria-pressed="true"] { background: var(--accent-wash); border-color: var(--accent); color: var(--ink); } +table.tv td .docs { margin-top: 2px; } + +/* Series slots for compare charts (identity by legend, validated hues). */ +.chart .line.s1, .chart .pt.s1 { stroke: var(--k-architecture); } .chart .pt.s1 { fill: var(--k-architecture); stroke: var(--surface); } +.chart .line.s2, .chart .pt.s2 { stroke: var(--k-refinement); } .chart .pt.s2 { fill: var(--k-refinement); stroke: var(--surface); } +.chart .line.s3, .chart .pt.s3 { stroke: var(--k-training); } .chart .pt.s3 { fill: var(--k-training); stroke: var(--surface); } +.legend .key { display: inline-flex; align-items: center; gap: 6px; } +.legend .key::before { content: ""; width: 14px; height: 0; border-top: 2px solid var(--ink-3); } +.legend .key.s1::before { border-color: var(--k-architecture); } .legend .key.s2::before { border-color: var(--k-refinement); } .legend .key.s3::before { border-color: var(--k-training); } +/* Sortable table, compare chips. */ +table.tv th button { font: inherit; color: inherit; background: none; border: 0; padding: 0; cursor: pointer; } +table.tv th button[aria-sort="ascending"]::after { content: " ↑"; color: var(--ink-3); } table.tv th button[aria-sort="descending"]::after { content: " ↓"; color: var(--ink-3); } +table.tv tr.is-sel td { background: var(--accent-wash); } +table.tv tr.rowbtn { cursor: pointer; } table.tv tr.rowbtn:hover td { background: var(--surface-2); } +table.tv td.ck { font-family: var(--mono); font-size: 12.5px; color: var(--ink-2); } +table.tv input[type="checkbox"] { margin: 0; } +.cmp-chips { display: flex; flex-wrap: wrap; gap: 6px; align-items: center; } +.cmp-chips .c { display: inline-flex; align-items: center; gap: 6px; padding: 2px 6px 2px 10px; border: 1px solid var(--line); border-radius: 999px; font-size: 12.5px; background: var(--surface); } +.cmp-chips .c i { width: 10px; height: 10px; border-radius: 50%; display: inline-block; } +.cmp-chips .c button { border: 0; background: none; padding: 0 2px; color: var(--ink-3); font-size: 14px; line-height: 1; cursor: pointer; } +.cmp-chips .c.s1 i { background: var(--k-architecture); } .cmp-chips .c.s2 i { background: var(--k-refinement); } .cmp-chips .c.s3 i { background: var(--k-training); } +table.cmpt td.d { color: var(--ink-2); font-size: 12.5px; } +table.cmpt td.d.better { color: var(--good); } table.cmpt td.d.worse { color: var(--serious); } +/* Train setup and new-training form. */ +.setup { display: grid; grid-template-columns: max-content 1fr; gap: 6px 14px; font-size: 13px; margin: 0; } +.setup dt { color: var(--ink-2); } .setup dd { margin: 0; overflow-wrap: anywhere; } +.setup dd button.btn { vertical-align: middle; } +.form { display: grid; gap: 10px; } +.form label { display: grid; gap: 3px; font-size: 12.5px; color: var(--ink-2); } +.form select, .form input, .form textarea { width: 100%; font: inherit; color: var(--ink); background: var(--surface); border: 1px solid var(--line-strong); border-radius: var(--radius); padding: 5px 8px; } +.form .two { display: grid; grid-template-columns: 1fr 1fr; gap: 10px; } +.form .hint { font-family: var(--mono); font-size: 11.5px; color: var(--ink-3); } +.trials { list-style: none; margin: 0; padding: 0; } .trials li { display: grid; grid-template-columns: 18px 1fr auto; gap: 8px; align-items: center; padding: 5px 0; border-top: 1px solid var(--line); font-size: 13px; } +.row.study { grid-template-columns: 90px minmax(0, 1fr) 70px 100px 90px; } +/* Field comparison viewer. */ +.viewer-bar { display: flex; flex-wrap: wrap; gap: 8px; align-items: center; margin-bottom: 12px; } +.viewer-bar label { display: inline-flex; gap: 6px; align-items: center; font-size: 12.5px; color: var(--ink-2); } +.viewer-bar input[type="range"] { width: 140px; } +.tri { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 14px; } +.tri figure { margin: 0; } +.tri canvas { display: block; width: 100%; aspect-ratio: 1; border: 1px solid var(--line); border-radius: var(--radius); background: var(--surface-2); } +.tri figcaption { font-size: 12.5px; color: var(--ink-2); margin-top: 6px; display: flex; justify-content: space-between; } +.tri figcaption b { color: var(--ink); font-weight: 500; } +.scale { display: flex; align-items: center; gap: 8px; font-size: 12px; color: var(--ink-3); margin-top: 8px; } +.scale i { display: inline-block; width: 120px; height: 8px; border-radius: 4px; background: linear-gradient(90deg, var(--k-architecture), var(--surface-2), var(--k-refinement)); } +.cases { margin-top: 16px; } +.cases svg { display: block; width: 100%; height: 64px; } +.cases .b { fill: var(--mark); } .cases .b.sel { fill: var(--accent); } .cases .b:hover { fill: var(--ink); cursor: pointer; } +.cases .base { stroke: var(--line-strong); } + +.tree-map .der.cold { opacity: .18; } .tree-map .der.hot { opacity: 1; stroke-width: 2.5; } .tree-map .der { opacity: .55; stroke-width: 1.5; } +table.tv td.nowrap, table.tv td.ck { white-space: nowrap; } +table.tv td .chip { white-space: nowrap; } + +/* Planned models, kin emphasis, label visibility, drawer motion. */ +.tree-map .node text.nl.off { display: none; } +.tree-map .node.kin circle { stroke: var(--ink); } +.tree-map .node.planned circle { fill: var(--surface); stroke: var(--accent); stroke-dasharray: 3 2; stroke-width: 2; } +.tree-map .der.hot { opacity: 1; stroke-width: 2.5; } +.tree-list .dot.planned { fill: var(--surface); stroke: var(--accent); stroke-dasharray: 3 2; } +.tree-list .trow.planned .nm { color: var(--accent); } +.ds-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(230px, 1fr)); gap: 14px; } +.ds-card { display: block; text-align: left; padding: 0; border: 1px solid var(--line); border-radius: var(--radius); background: var(--surface); color: inherit; overflow: hidden; } +.ds-card:hover { border-color: var(--line-strong); } +.ds-card[aria-pressed="true"] { border-color: var(--accent); box-shadow: inset 0 0 0 1px var(--accent); } +.ds-card .pv { display: block; width: 100%; aspect-ratio: 16 / 9; background: var(--surface-2); border-bottom: 1px solid var(--line); } +.ds-card .pv.text { display: grid; place-items: center; color: var(--ink-3); font: 12px var(--mono); padding: 10px; white-space: pre; overflow: hidden; } +.ds-card .t { padding: 10px 12px 12px; display: grid; gap: 3px; } +.ds-card .t .title { font-weight: 500; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; } +.ds-card .t .meta { display: flex; gap: 8px; align-items: center; font-size: 12.5px; color: var(--ink-2); } +.ds-card .t .meta .glyph { display: inline-flex; margin-left: auto; } +.ds-card .t .meta .glyph svg { width: 14px; height: 14px; } +.ds-card .t .meta .glyph.good { color: var(--good); } .ds-card .t .meta .glyph.neutral { color: var(--ink-3); } .ds-card .t .meta .glyph.serious { color: var(--serious); } +.ds-card .t .path { font-family: var(--mono); font-size: 11.5px; color: var(--ink-3); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; } +.ds-actions .btn[aria-pressed="true"] { background: var(--accent-wash); border-color: var(--accent); } +.form .radio { display: flex; flex-wrap: wrap; gap: 6px; } +.form .radio label { display: inline-flex; align-items: center; gap: 6px; padding: 4px 10px; border: 1px solid var(--line-strong); border-radius: 999px; color: var(--ink); cursor: pointer; } +.form .radio input { margin: 0; } +.form .radio label:has(input:checked) { background: var(--accent-wash); border-color: var(--accent); } + +/* Selection walk, comparison arcs, record browser and volume viewer. */ +.tree-list .trow.walk { background: var(--accent-wash); } +.tree-map .node.walk circle { stroke: var(--accent); stroke-width: 3; } +.tree-map .cmp { pointer-events: stroke; stroke-width: 1.5; cursor: pointer; } +.tree-map .cmp:hover, .tree-map .cmp:focus-visible { stroke: var(--accent); stroke-width: 2.5; outline: none; } +.ds-head { display: flex; flex-wrap: wrap; align-items: center; gap: 10px 16px; margin-bottom: 14px; } +.ds-head h2 { font-size: 17px; } +.ds-head .meta { display: flex; gap: 12px; align-items: center; font-size: 12.5px; color: var(--ink-2); } +.ds-head .meta .glyph { display: inline-flex; } .ds-head .meta .glyph svg { width: 14px; height: 14px; } +.ds-head .actions { margin-left: auto; display: flex; gap: 8px; } +.ds-body { display: grid; grid-template-columns: minmax(0, 1fr) minmax(360px, 44%); gap: 20px; align-items: start; } +.rec-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(84px, 1fr)); gap: 8px; } +.rec { padding: 0; border: 1px solid var(--line); border-radius: var(--radius); background: var(--surface); overflow: hidden; text-align: left; color: inherit; } +.rec canvas { display: block; width: 100%; aspect-ratio: 1; } +.rec span { display: block; font: 11px var(--mono); color: var(--ink-3); padding: 3px 6px; } +.rec[aria-pressed="true"] { border-color: var(--accent); box-shadow: inset 0 0 0 1px var(--accent); } +.rec:hover { border-color: var(--line-strong); } +.pager { display: flex; gap: 8px; align-items: center; font-size: 12.5px; color: var(--ink-2); margin: 10px 0 0; } +.viewer { border: 1px solid var(--line); border-radius: var(--radius); background: var(--surface); padding: 12px; display: grid; gap: 10px; } +.viewer .vol { display: block; width: 100%; aspect-ratio: 4 / 3; background: var(--surface-2); border-radius: var(--radius); } +.viewer .row2 { display: grid; grid-template-columns: 1fr 1fr; gap: 10px; } +.viewer .sl { display: block; width: 100%; aspect-ratio: 1; background: var(--surface-2); border-radius: var(--radius); } +.viewer .ctl { display: flex; flex-wrap: wrap; gap: 8px 14px; align-items: center; font-size: 12.5px; color: var(--ink-2); } +.viewer .ctl label { display: inline-flex; gap: 6px; align-items: center; } +.viewer .ctl input[type="range"] { width: 120px; } +.viewer .facts { font-size: 12.5px; } +.ds-back { margin-bottom: 10px; } +@media (max-width: 1100px) { .ds-body { grid-template-columns: 1fr; } } + +/* Annotation screen, run rows, benchmark coverage. */ +.ann-body { display: grid; grid-template-columns: minmax(280px, 1fr) minmax(360px, 1.1fr); gap: 20px; align-items: start; } +.ann-bar { display: flex; flex-wrap: wrap; gap: 8px 14px; align-items: center; margin-bottom: 14px; } +.ann-bar label { display: inline-flex; gap: 6px; align-items: center; font-size: 12.5px; color: var(--ink-2); } +.progress { display: inline-flex; align-items: center; gap: 8px; font-size: 12.5px; color: var(--ink-2); } +.progress i { display: inline-block; width: 120px; height: 6px; border-radius: 3px; background: var(--grid); overflow: hidden; } +.progress i b { display: block; height: 100%; background: var(--good); } +.rec .badge { position: absolute; right: 4px; top: 4px; width: 8px; height: 8px; border-radius: 50%; } +.rec { position: relative; } +.rec .badge.accepted { background: var(--good); } .rec .badge.needs { background: var(--warn); } .rec .badge.reject { background: var(--serious); } .rec .badge.labelled { background: var(--accent); } +.seg { display: inline-flex; border: 1px solid var(--line-strong); border-radius: var(--radius); overflow: hidden; } +.seg button { border: 0; background: var(--surface); padding: 5px 10px; font: inherit; color: var(--ink-2); cursor: pointer; } +.seg button + button { border-left: 1px solid var(--line-strong); } +.seg button[aria-pressed="true"] { background: var(--accent-wash); color: var(--ink); } +.seg button.ok[aria-pressed="true"] { background: var(--good-wash); } .seg button.warn[aria-pressed="true"] { background: var(--warn-wash); } .seg button.bad[aria-pressed="true"] { background: var(--serious-wash); } +.hist { list-style: none; margin: 0; padding: 0; font-size: 12.5px; color: var(--ink-2); } +.hist li { padding: 5px 0; border-top: 1px solid var(--line); display: flex; gap: 10px; } +.hist li b { color: var(--ink); font-weight: 500; } +.kbd { font: 11px var(--mono); border: 1px solid var(--line-strong); border-radius: 3px; padding: 0 4px; color: var(--ink-2); } +.row.run { grid-template-columns: 44px minmax(160px, 1fr) 120px 90px 50px 100px; } +.row.run .ck { font-family: var(--mono); font-size: 12.5px; color: var(--ink-2); } +.coverage { display: flex; flex-wrap: wrap; gap: 6px 18px; font-size: 12.5px; color: var(--ink-2); margin: -6px 0 14px; } +.coverage b { color: var(--ink); font-weight: 500; } diff --git a/docs/plans/project-workspace-redesign/mockups/shared/charts.js b/docs/plans/project-workspace-redesign/mockups/shared/charts.js new file mode 100644 index 00000000..45e24504 --- /dev/null +++ b/docs/plans/project-workspace-redesign/mockups/shared/charts.js @@ -0,0 +1,121 @@ +'use strict'; +// Benchmark charts in plain SVG: an accuracy/time scatter with its Pareto +// frontier, and the worst-pressure curve along the checkpoint sequence. +// Every value is also in the table view; tooltips enhance, never gate. +window.LabCharts = (() => { + const svgNS = 'http://www.w3.org/2000/svg'; + const el = (name, attrs = {}, text) => { const n = document.createElementNS(svgNS, name); for (const k in attrs) n.setAttribute(k, attrs[k]); if (text !== undefined) n.textContent = text; return n; }; + const h = (tag, cls, text) => { const n = document.createElement(tag); if (cls) n.className = cls; if (text !== undefined) n.textContent = text; return n; }; + const fmtSci = v => window.LabTree.fmtSci(v); + const logTicks = (lo, hi) => { const out = []; for (let e = Math.ceil(Math.log10(lo)); e <= Math.floor(Math.log10(hi)); e++) out.push(Math.pow(10, e)); return out; }; + const tickLabel = v => v >= 1 ? String(v) : (v >= 0.01 ? v.toString() : '1e' + Math.log10(v)); + + function tooltip(host) { + const t = h('div', 'tip'); t.hidden = true; host.appendChild(t); + return { + show(x, y, rows) { t.textContent = ''; for (const r of rows) { if (r.b) { t.appendChild(h('b', null, r.b)); continue; } const line = h('div'); const v = h('span', 'v', r.v); line.appendChild(v); line.appendChild(document.createTextNode(' ' + r.l)); t.appendChild(line); } t.hidden = false; const W = host.clientWidth; t.style.left = Math.min(x + 14, W - 200) + 'px'; t.style.top = (y + 12) + 'px'; }, + hide() { t.hidden = true; } + }; + } + + function pareto(host, models, { selected = null, onSelect = () => {}, kinds = null, frontierOnly = false, metric = 'worstP', table = false, yLabel = '', xLabel = '', unit = 'ms', xMax = 10 } = {}) { + host.textContent = ''; host.classList.add('chart'); + const pts = models.filter(m => m.ms != null && m.ms <= xMax && m[metric] != null && m[metric] > 0); + const shown = pts.filter(m => !kinds || kinds.has(m.kind)); + const sorted = shown.slice().sort((a, b) => a.ms - b.ms || a[metric] - b[metric]); + const front = []; let best = Infinity; for (const m of sorted) { if (m[metric] < best) { front.push(m); best = m[metric]; } } + const frontSet = new Set(front.map(m => m.id)); + const W = 760, H = 340, L = 56, R = 16, T = 16, B = 40; + const ylo = 1e-4, yhi = 1; + const X = ms => L + (ms / xMax) * (W - L - R), Y = v => T + (Math.log10(yhi) - Math.log10(Math.min(Math.max(v, ylo), yhi))) / (Math.log10(yhi) - Math.log10(ylo)) * (H - T - B); + const svg = el('svg', { viewBox: `0 0 ${W} ${H}`, role: 'img', 'aria-label': yLabel + ' on a log scale against ' + xLabel }); + const grid = el('g', { class: 'grid' }), axis = el('g', { class: 'axis' }); + for (const v of logTicks(ylo, yhi)) { grid.appendChild(el('line', { x1: L, y1: Y(v), x2: W - R, y2: Y(v) })); axis.appendChild(el('text', { x: L - 8, y: Y(v) + 4, 'text-anchor': 'end' }, tickLabel(v))); } + const step = xMax > 10 ? 4 : 2; for (let ms = 0; ms <= xMax; ms += step) { axis.appendChild(el('line', { x1: X(ms), y1: H - B, x2: X(ms), y2: H - B + 4, class: 'base' })); axis.appendChild(el('text', { x: X(ms), y: H - B + 16, 'text-anchor': 'middle' }, ms + (ms + step > xMax ? ' ' + unit : ''))); } + axis.appendChild(el('line', { x1: L, y1: H - B, x2: W - R, y2: H - B, class: 'base' })); + axis.appendChild(el('text', { x: W - R, y: H - 4, 'text-anchor': 'end', class: 'label' }, xLabel)); + axis.appendChild(el('text', { x: L, y: T - 4, class: 'label' }, yLabel)); + svg.appendChild(grid); svg.appendChild(axis); + if (front.length > 1) svg.appendChild(el('path', { class: 'frontier', d: front.map((m, i) => (i ? 'L' : 'M') + X(m.ms) + ',' + Y(m[metric])).join(' ') })); + const tip = tooltip(host); + const order = shown.slice().sort((a, b) => (a.id === selected) - (b.id === selected)); + for (const m of order) { + const dim = frontierOnly && !frontSet.has(m.id); + const g = el('g'); + const hit = el('circle', { cx: X(m.ms), cy: Y(m[metric]), r: 12, class: 'hit', tabindex: 0, role: 'button', 'aria-label': `${m.ck || m.short}, ${fmtSci(m[metric])} at ${m.ms.toFixed(2)} milliseconds${frontSet.has(m.id) ? ', on the frontier' : ''}` }); + const pt = el('circle', { cx: X(m.ms), cy: Y(m[metric]), r: 5, class: 'pt ' + m.kind + (dim ? ' dim' : '') }); + const rows = () => [{ b: (m.ck ? m.ck + ' · ' : '') + m.short }, { v: fmtSci(m[metric]), l: yLabel }, { v: m.ms.toFixed(2) + ' ' + unit, l: xLabel }, { v: window.LabTree.kindLabel(m.kind), l: frontSet.has(m.id) ? '· frontier' : '' }]; + const pos = () => { const r = host.getBoundingClientRect(); const s = svg.getBoundingClientRect(); return [s.left - r.left + X(m.ms) * s.width / W, s.top - r.top + Y(m[metric]) * s.height / H]; }; + hit.addEventListener('pointerenter', () => { const [x, y] = pos(); tip.show(x, y, rows()); }); + hit.addEventListener('focus', () => { const [x, y] = pos(); tip.show(x, y, rows()); }); + hit.addEventListener('pointerleave', () => tip.hide()); hit.addEventListener('blur', () => tip.hide()); + hit.addEventListener('click', () => onSelect(m.id)); hit.addEventListener('keydown', e => { if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); onSelect(m.id); } }); + g.appendChild(hit); g.appendChild(pt); + if (m.id === selected) g.appendChild(el('circle', { cx: X(m.ms), cy: Y(m[metric]), r: 9, class: 'sel' })); + svg.appendChild(g); + } + if (front.length) { const b = front[front.length - 1]; svg.appendChild(el('text', { x: X(b.ms) + 10, y: Y(b[metric]) + 4, class: 'label' }, (b.ck || b.short) + ' · best accuracy')); const f = front[0]; if (f !== b) svg.appendChild(el('text', { x: X(f.ms) + 10, y: Y(f[metric]) + 18, class: 'label' }, (f.ck || f.short) + ' · fastest')); } + host.appendChild(svg); + const legend = h('ul', 'legend'); + for (const k of ['training', 'architecture', 'refinement', 'composition']) { const li = h('li', 'chip ' + k, window.LabTree.kindLabel(k)); legend.appendChild(li); } + const fl = h('li', null, 'Line: Pareto frontier'); legend.appendChild(fl); + host.appendChild(legend); + if (table) { + const tb = h('table', 'tv'); tb.setAttribute('aria-label', 'Plotted fits as a table'); + const thead = h('thead'); const tr = h('tr'); for (const [t, c] of [['Fit', ''], ['Kind', ''], [yLabel, 'n'], [xLabel, 'n'], ['Frontier', '']]) { const th = h('th', c, t); tr.appendChild(th); } thead.appendChild(tr); tb.appendChild(thead); + const tbody = h('tbody'); for (const m of sorted) { const r = h('tr'); r.appendChild(h('td', null, (m.ck ? m.ck + ' · ' : '') + m.short)); r.appendChild(h('td', null, window.LabTree.kindLabel(m.kind))); r.appendChild(h('td', 'n', fmtSci(m[metric]))); r.appendChild(h('td', 'n', m.ms.toFixed(2))); r.appendChild(h('td', null, frontSet.has(m.id) ? 'yes' : '')); tbody.appendChild(r); } tb.appendChild(tbody); host.appendChild(tb); + } + return { count: shown.length, total: pts.length, frontier: front }; + } + + function curve(host, models, { selected = null, onSelect = () => {}, metric = 'worstP', sections = [], yLabel = '', secondary = null } = {}) { + host.textContent = ''; host.classList.add('chart'); + const pts = models.filter(m => m.n != null && m.n <= 124 && m[metric] != null && m[metric] > 0).sort((a, b) => a.n - b.n); + const W = 760, H = 220, L = 56, R = 16, T = 28, B = 34, ylo = 1e-4, yhi = 1, nlo = pts[0].n, nhi = pts[pts.length - 1].n; + const X = n => L + (n - nlo) / (nhi - nlo) * (W - L - R), Y = v => T + (Math.log10(yhi) - Math.log10(Math.min(Math.max(v, ylo), yhi))) / 4 * (H - T - B); + const svg = el('svg', { viewBox: `0 0 ${W} ${H}`, role: 'img', 'aria-label': yLabel + ' for each checkpoint from C' + nlo + ' to C' + nhi }); + const grid = el('g', { class: 'grid' }), axis = el('g', { class: 'axis' }); + for (const v of logTicks(ylo, yhi)) { grid.appendChild(el('line', { x1: L, y1: Y(v), x2: W - R, y2: Y(v) })); axis.appendChild(el('text', { x: L - 8, y: Y(v) + 4, 'text-anchor': 'end' }, tickLabel(v))); } + for (let n = 20; n <= nhi; n += 20) axis.appendChild(el('text', { x: X(n), y: H - B + 16, 'text-anchor': 'middle' }, 'C' + n)); + axis.appendChild(el('line', { x1: L, y1: H - B, x2: W - R, y2: H - B, class: 'base' })); + for (const s of sections) { const a = pts.find(m => m.n >= s.from); if (!a) continue; axis.appendChild(el('line', { x1: X(s.from), y1: T - 8, x2: X(s.from), y2: H - B, class: '' })); axis.appendChild(el('text', { x: X(s.from) + 4, y: T - 12, class: 'label' }, s.label)); } + svg.appendChild(grid); svg.appendChild(axis); + svg.appendChild(el('path', { class: 'line', d: pts.map((m, i) => (i ? 'L' : 'M') + X(m.n) + ',' + Y(m[metric])).join(' ') })); + const cross = el('line', { class: 'cross', x1: 0, y1: T, x2: 0, y2: H - B }); cross.style.visibility = 'hidden'; svg.appendChild(cross); + for (const m of pts) { svg.appendChild(el('circle', { cx: X(m.n), cy: Y(m[metric]), r: 4, class: 'pt ' + m.kind + (m.id === selected ? '' : '') })); if (m.id === selected) svg.appendChild(el('circle', { cx: X(m.n), cy: Y(m[metric]), r: 8, class: 'sel' })); } + const tip = tooltip(host); + const nearest = cx => { let b = pts[0], d = Infinity; for (const m of pts) { const dd = Math.abs(X(m.n) - cx); if (dd < d) { d = dd; b = m; } } return b; }; + const toSvg = e => { const r = svg.getBoundingClientRect(); return [(e.clientX - r.left) * W / r.width, (e.clientY - r.top) * H / r.height]; }; + svg.addEventListener('pointermove', e => { const [cx] = toSvg(e); const m = nearest(cx); cross.setAttribute('x1', X(m.n)); cross.setAttribute('x2', X(m.n)); cross.style.visibility = 'visible'; const r = host.getBoundingClientRect(), s = svg.getBoundingClientRect(); tip.show(s.left - r.left + X(m.n) * s.width / W, s.top - r.top + Y(m[metric]) * s.height / H, [{ b: m.ck + ' · ' + m.short }, { v: fmtSci(m[metric]), l: yLabel }].concat(secondary ? [{ v: m[secondary.id] == null ? '—' : fmtSci(m[secondary.id]), l: secondary.label }] : []).concat([{ v: window.LabTree.kindLabel(m.kind), l: '' }])); }); + svg.addEventListener('pointerleave', () => { cross.style.visibility = 'hidden'; tip.hide(); }); + svg.addEventListener('click', e => { const [cx] = toSvg(e); onSelect(nearest(cx).id); }); + host.appendChild(svg); + return { count: pts.length }; + } + // Multi-series line chart (training curves). series: [{id, label, slot, points: [[x, y]]}] + function lines(host, series, { yLabel = '', xLabel = '', logY = true } = {}) { + host.textContent = ''; host.classList.add('chart'); + const W = 760, H = 240, L = 56, R = 16, T = 16, B = 36; + const all = series.flatMap(s => s.points); if (!all.length) { host.appendChild(h('p', 'empty', 'No curves.')); return; } + const xlo = 0, xhi = Math.max(...all.map(p => p[0])), ylo = Math.min(...all.map(p => p[1])), yhi = Math.max(...all.map(p => p[1])); + const X = x => L + (x - xlo) / (xhi - xlo || 1) * (W - L - R); + const Y = logY ? v => T + (Math.log10(yhi) - Math.log10(v)) / (Math.log10(yhi) - Math.log10(ylo) || 1) * (H - T - B) : v => T + (yhi - v) / (yhi - ylo || 1) * (H - T - B); + const svg = el('svg', { viewBox: `0 0 ${W} ${H}`, role: 'img', 'aria-label': yLabel + ' against ' + xLabel + ' for ' + series.map(s => s.label).join(', ') }); + const grid = el('g', { class: 'grid' }), axis = el('g', { class: 'axis' }); + const ticks = logY ? logTicks(ylo, yhi).filter(v => v >= ylo && v <= yhi) : [ylo, (ylo + yhi) / 2, yhi]; + for (const v of ticks) { grid.appendChild(el('line', { x1: L, y1: Y(v), x2: W - R, y2: Y(v) })); axis.appendChild(el('text', { x: L - 8, y: Y(v) + 4, 'text-anchor': 'end' }, logY ? tickLabel(v) : v.toFixed(2))); } + for (let i = 0; i <= 4; i++) { const x = xlo + (xhi - xlo) * i / 4; axis.appendChild(el('text', { x: X(x), y: H - B + 16, 'text-anchor': 'middle' }, Math.round(x).toLocaleString('en-GB'))); } + axis.appendChild(el('line', { x1: L, y1: H - B, x2: W - R, y2: H - B, class: 'base' })); + axis.appendChild(el('text', { x: W - R, y: H - 4, 'text-anchor': 'end', class: 'label' }, xLabel)); + axis.appendChild(el('text', { x: L, y: T - 4, class: 'label' }, yLabel)); + svg.appendChild(grid); svg.appendChild(axis); + for (const s of series) { svg.appendChild(el('path', { class: 'line s' + s.slot, d: s.points.map((p, i) => (i ? 'L' : 'M') + X(p[0]) + ',' + Y(p[1])).join(' ') })); const last = s.points[s.points.length - 1]; svg.appendChild(el('circle', { cx: X(last[0]), cy: Y(last[1]), r: 4, class: 'pt s' + s.slot })); } + const cross = el('line', { class: 'cross', x1: 0, y1: T, x2: 0, y2: H - B }); cross.style.visibility = 'hidden'; svg.appendChild(cross); + const tip = tooltip(host); + svg.addEventListener('pointermove', e => { const r = svg.getBoundingClientRect(); const cx = (e.clientX - r.left) * W / r.width; const xv = xlo + (cx - L) / (W - L - R) * (xhi - xlo); cross.setAttribute('x1', cx); cross.setAttribute('x2', cx); cross.style.visibility = 'visible'; const rows = [{ b: Math.round(xv).toLocaleString('en-GB') + ' ' + xLabel }]; for (const s of series) { let b = s.points[0]; for (const p of s.points) if (Math.abs(p[0] - xv) < Math.abs(b[0] - xv)) b = p; rows.push({ v: fmtSci(b[1]), l: s.label }); } const hr = host.getBoundingClientRect(); tip.show(e.clientX - hr.left, e.clientY - hr.top - 10, rows); }); + svg.addEventListener('pointerleave', () => { cross.style.visibility = 'hidden'; tip.hide(); }); + host.appendChild(svg); + const legend = h('ul', 'legend'); for (const s of series) { const li = h('li', 'key s' + s.slot, s.label); legend.appendChild(li); } host.appendChild(legend); + } + return { pareto, curve, lines }; +})(); diff --git a/docs/plans/project-workspace-redesign/mockups/shared/screens.js b/docs/plans/project-workspace-redesign/mockups/shared/screens.js new file mode 100644 index 00000000..57b46905 --- /dev/null +++ b/docs/plans/project-workspace-redesign/mockups/shared/screens.js @@ -0,0 +1,717 @@ +'use strict'; +// Screen content shared by every layout. A shell decides where the main +// content and the inspector live; these functions fill them from window.LAB. +// Rule: the chrome holds no project words. Metric names, populations, group +// names and decisions come from the project data. +window.LabScreens = (() => { + const LAB = window.LAB, Tree = window.LabTree, Charts = window.LabCharts; + const h = (tag, cls, text) => { const n = document.createElement(tag); if (cls) n.className = cls; if (text !== undefined) n.textContent = text; return n; }; + const svgNS = 'http://www.w3.org/2000/svg'; + const ICONS = { + check: 'M12 2a10 10 0 1 0 0 20 10 10 0 0 0 0-20zm-1.3 14.2-3.6-3.6 1.4-1.4 2.2 2.2 5.1-5.1 1.4 1.4z', + alert: 'M12 2a10 10 0 1 0 0 20 10 10 0 0 0 0-20zm-1 5h2v6h-2zm0 8h2v2h-2z', + triangle: 'M12 3 1 21h22zm-1 7h2v5h-2zm0 7h2v2h-2z', + minus: 'M12 2a10 10 0 1 0 0 20 10 10 0 0 0 0-20zm-5 9h10v2H7z', + branch: 'M7 3a3 3 0 0 0-1 5.8v6.4A3 3 0 1 0 8 15.2V9.9c1.2 1.3 2.9 2.1 5 2.1 2.8 0 4.4-1.5 5-4.1A3 3 0 1 0 16 7.6c-.5 1.6-1.4 2.4-3 2.4-2.6 0-4.3-1.6-5-3.2A3 3 0 0 0 7 3z', + clock: 'M12 2a10 10 0 1 0 0 20 10 10 0 0 0 0-20zm1 5h-2v6l5 3 1-1.7-4-2.3z', + x: 'M18.3 5.7 12 12l6.3 6.3-1.4 1.4L10.6 13.4 4.3 19.7 2.9 18.3 9.2 12 2.9 5.7l1.4-1.4 6.3 6.3 6.3-6.3z', + theme: 'M12 3a9 9 0 1 0 0 18 9 9 0 0 0 0-18zm0 2v14a7 7 0 0 1 0-14z' + }; + const icon = name => { const s = document.createElementNS(svgNS, 'svg'); s.setAttribute('viewBox', '0 0 24 24'); s.setAttribute('aria-hidden', 'true'); const p = document.createElementNS(svgNS, 'path'); p.setAttribute('d', ICONS[name] || ICONS.minus); p.setAttribute('fill', 'currentColor'); p.setAttribute('fill-rule', 'evenodd'); s.appendChild(p); return s; }; + const stateEl = (kind, text) => { const map = { good: 'check', warn: 'alert', serious: 'triangle', neutral: 'minus', pending: 'clock' }; const s = h('span', 'state ' + (kind === 'pending' ? 'warn' : kind)); s.appendChild(icon(map[kind] || 'minus')); s.appendChild(document.createTextNode(text)); return s; }; + const fmtDate = iso => new Date(iso).toLocaleDateString('en-GB', { day: 'numeric', month: 'short', year: 'numeric' }); + const fmtBytes = b => b == null ? '—' : b > 1e6 ? (b / 1e6).toFixed(1) + ' MB' : b > 1e3 ? Math.round(b / 1e3) + ' KB' : b + ' B'; + let graph = Tree.build(LAB.models, LAB.relationships), byId = graph.byId, plannedVersion = 0; + function setPlanned(list) { + const extra = list.map(pl => { const p = LAB.models.find(m => m.id === pl.parent); return Object.assign({ id: pl.id, ck: null, n: p && p.n != null ? p.n + 0.5 : null, label: 'New model from ' + (p ? (p.ck || p.short) : '?'), short: pl.name || 'new model', alias: null, group: p ? p.group : 'pressure-other', groupLabel: p ? p.groupLabel : '', kind: pl.kind || 'refinement', worstP: null, eq: null, ms: null, params: null, purpose: '', outcome: '', lesson: '', parents: [pl.parent], planned: true, setup: pl.setup }); }); + graph = Tree.build(LAB.models.concat(extra), LAB.relationships); byId = graph.byId; plannedVersion++; + } + const MET = LAB.metrics, ACC = MET.accuracy, TIME = MET.time; + const accLabel = id => (ACC.find(a => a.id === id) || ACC[0]).label; + const benchModels = () => LAB.models.filter(m => m.group !== MET.excludedGroup); + const withBench = LAB.models.filter(m => m[ACC[0].id] != null && m[TIME.id] != null).length; + const KINDS = ['training', 'architecture', 'refinement', 'composition']; + // Checkpoint sections for the sequence chart, read from authored group labels of the form "C16–C25 · name". + const CURVE_SECTIONS = LAB.groups.map(g => { const m = /^C(\d+)[–-]C(\d+)\s*·\s*(.+)$/.exec(g.label); return m ? { from: +m[1], label: m[3].split(/\s+/)[0] } : null; }).filter(Boolean); + const studyState = s => s.state === 'closed' ? 'pending' : s.decision.includes('failed') ? 'serious' : s.decision.includes('no promotion') ? 'neutral' : 'good'; + const sect = (title, sum) => { const d = h('div', 'sect'); d.appendChild(h('h2', null, title)); if (sum) d.appendChild(h('span', 'sum', sum)); return d; }; + const DOC_ROLE = path => /plan\.md$/.test(path) ? 'Plan' : /ledger\.md$/.test(path) ? 'Methods' : /(results?\.md|current\.json|results\.json)$/.test(path) ? 'Results' : null; + const docsOf = plan => { const g = LAB.project.evidence.find(x => x.plan === plan); return g ? g.items.map(([id, label, path]) => ({ id, label: DOC_ROLE(path) || label, path })) : []; }; + const docChips = (plan, sel, onPick) => { const d = h('span', 'docs'); for (const doc of docsOf(plan)) { const b = h('button', null, doc.label); b.type = 'button'; b.title = doc.path; b.setAttribute('aria-pressed', String(doc.id === sel)); b.addEventListener('click', ev => { ev.stopPropagation(); onPick(doc.id); }); d.appendChild(b); } return d; }; + const fileLink = (rel, text) => { const a = h('a', 'path', text || rel); const dir = rel.includes('/') ? rel.slice(0, rel.lastIndexOf('/')) : ''; a.href = 'file://' + LAB.project.rootPath + '/' + dir; a.title = 'Open folder'; a.addEventListener('click', ev => ev.stopPropagation()); return a; }; + const KIND_ICON = { fields: 'M3 3h18v18H3zm2 2v4h4V5zm6 0v4h4V5zm6 0v4h2V5zM5 11v4h4v-4zm6 0v4h4v-4zm6 0v4h2v-4zM5 17v2h4v-2zm6 0v2h4v-2zm6 0v2h2v-2z', records: 'M4 4h16v3H4zm0 5h16v3H4zm0 5h16v3H4zm0 5h10v2H4z', manifest: 'M6 2h9l5 5v15H6zm8 1.5V8h4.5zM8 11h8v2H8zm0 4h8v2H8z', results: 'M3 21V3h2v16h16v2zm4-4 4-6 3 3 5-8 1.5 1-6.5 10-3-3-3 4.5z' }; + const kindIcon = k => { const sv = document.createElementNS(svgNS, 'svg'); sv.setAttribute('viewBox', '0 0 24 24'); sv.setAttribute('aria-hidden', 'true'); const pth = document.createElementNS(svgNS, 'path'); pth.setAttribute('d', KIND_ICON[k] || KIND_ICON.records); pth.setAttribute('fill', 'currentColor'); pth.setAttribute('fill-rule', 'evenodd'); sv.appendChild(pth); return sv; }; + function fieldPreview(canvas, seed) { + const ctx = canvas.getContext('2d'), W = canvas.width = 320, Hh = canvas.height = 180, nx = 32, ny = 18; + const dark = getComputedStyle(document.documentElement).colorScheme === 'dark'; + const mid = dark ? [56, 56, 53] : [240, 239, 236], neg = dark ? [79, 138, 224] : [46, 111, 207], pos = dark ? [217, 111, 60] : [210, 101, 47]; + for (let j = 0; j < ny; j++) for (let i = 0; i < nx; i++) { + const u = i / nx, v = j / ny, val = Math.sin(6.3 * u + seed) * Math.cos(4.7 * v - seed * 0.5) * 0.7 + Math.sin(12 * u * v + seed) * 0.3; + const c = val < 0 ? neg : pos, t = Math.min(1, Math.abs(val)); const rgb = mid.map((m, k) => Math.round(m + (c[k] - m) * t)); + ctx.fillStyle = `rgb(${rgb[0]},${rgb[1]},${rgb[2]})`; ctx.fillRect(i * W / nx, j * Hh / ny, W / nx + 1, Hh / ny + 1); + } + } + const seeded = str => { let x = 0; for (const ch of str) x = (x * 31 + ch.charCodeAt(0)) % 1000003; return () => { x = (x * 1103515245 + 12345) % 2147483648; return x / 2147483648; }; }; + // Training curve for a fit: shaped by its recorded update count and final loss (mock data for the layout). + const curveFor = m => { const U = m.updates || 2000, L = m.loss || (m.worstP ? m.worstP * 2000 : 10), rnd = seeded(m.id), pts = []; for (let i = 0; i <= 40; i++) { const u = U * i / 40; pts.push([u, L * (1 + 30 * Math.exp(-6 * u / U)) * (1 + 0.06 * (rnd() - 0.5))]); } return pts; }; + const recipeOf = id => (LAB.recipes || []).find(r => r.id === id); + const runtimeOf = id => (LAB.runtimes || []).find(r => r.id === id); + const datasetOf = id => LAB.project.data.find(r => r.id === id); + const modelName = m => (m.ck ? m.ck + ' · ' : '') + m.short; + const popOf = state => (MET.populations || []).find(p => p.id === (state.pop || 'pressure')) || { id: 'all', label: 'All' }; + const inPop = (m, pop) => pop.only ? m.group === pop.only : pop.exclude ? m.group !== pop.exclude : true; + const benchState = m => { const a = m[ACC[0].id] != null, t = m[TIME.id] != null; return m.group === MET.excludedGroup ? 'generator benchmark' : a && t ? 'accuracy and time' : a ? 'accuracy only' : t ? 'time only' : 'none retained'; }; + const runStudy = m => { for (const [sid, trials] of Object.entries(LAB.project.trials || {})) for (const t of trials) if (t.run && t.run === m.ck) return LAB.project.studies.find(x => x.id === sid); return null; }; + const cell = (k, v, u) => { const d = h('div'); d.appendChild(h('dt', null, k)); const dd = h('dd', null, v); if (u) dd.appendChild(h('small', null, u)); d.appendChild(dd); return d; }; + + function statusLine() { const a = LAB.project.activity; return { state: a.state, text: a.phase + '. ' + a.message, updated: fmtDate(a.updated), producer: a.producer }; } + function stageSummaries() { + const d = LAB.project.data, verified = d.filter(r => r.integrity === 'verified').length, missing = d.filter(r => r.state === 'missing').length; + const st = LAB.project.studies, pending = st.filter(s => s.state === 'closed').length; + return [ + { id: 'overview', label: 'Overview', sum: `${LAB.project.needs.length} need you` }, + { id: 'data', label: 'Data', sum: `${d.length} datasets` + (missing ? ` · ${missing} missing` : '') }, + { id: 'annotate', label: 'Annotate', sum: 'No records' }, + { id: 'models', label: 'Models', sum: `${LAB.models.length} fits · ${graph.families.length} branch points` }, + { id: 'train', label: 'Train', sum: `${LAB.models.length} runs · ${st.length} studies` + (pending ? ` · ${pending} waiting` : '') }, + { id: 'benchmarks', label: 'Benchmarks', sum: `${withBench} benchmarked` }, + { id: 'analysis', label: 'Analysis', sum: `${LAB.project.evidence.reduce((n, g) => n + g.items.length, 0)} notes` } + ]; + } + + // ---- Overview ------------------------------------------------------------ + function overview(main, aside, state, act) { + main.textContent = ''; aside.textContent = ''; + const s = statusLine(); + const top = h('section', 'ov-status'); + const line = h('div', 'ov-line'); + line.appendChild(stateEl(s.state === 'completed' ? 'good' : s.state === 'failed' ? 'serious' : 'pending', s.state === 'completed' ? 'Completed' : s.state)); + line.appendChild(h('p', 'ov-text', s.text)); top.appendChild(line); + top.appendChild(h('p', 'small faint', `${s.producer} · ${s.updated}`)); + main.appendChild(top); + + const row = h('div', 'ov-row'); + const needs = h('section'); needs.appendChild(sect('Needs you', String(LAB.project.needs.length))); + const ul = h('ul', 'needs'); + for (const n of LAB.project.needs) { + const li = h('li', n.kind); li.appendChild(icon(n.kind === 'approval' ? 'clock' : n.kind === 'changed' ? 'alert' : 'triangle')); + li.appendChild(h('span', null, n.text)); + const b = h('button', 'btn sm', n.kind === 'approval' ? 'Review' : 'Open'); b.type = 'button'; b.addEventListener('click', () => act.go(n.where, n.ref)); li.appendChild(b); + ul.appendChild(li); + } + needs.appendChild(ul); row.appendChild(needs); + const facts = h('section'); facts.appendChild(sect('Project')); + const dl = h('dl', 'facts'); + for (const [k, v, c] of [['Manifest', `${LAB.project.root}/${LAB.project.manifest}`, 'mono'], ['Schema', String(LAB.project.schema)], ['Snapshot', LAB.project.id, 'mono'], ['Requirements', LAB.project.requirements.map(r => r.label).join('; ')], ['Execution', 'inspection only']]) { dl.appendChild(h('dt', null, k)); dl.appendChild(h('dd', c || '', v)); } + facts.appendChild(dl); row.appendChild(facts); main.appendChild(row); + + const cols = h('div', 'ov-cols'); + const st = h('section'); st.appendChild(sect('Stages')); + const sl = h('ul', 'rows'); + for (const g of stageSummaries().filter(x => x.id !== 'overview')) { const li = h('li'); const b = h('button', 'row ov-stage'); b.type = 'button'; b.appendChild(h('span', 'title', g.label)); b.appendChild(h('span', 'sub', g.sum)); b.addEventListener('click', () => act.go(g.id)); li.appendChild(b); sl.appendChild(li); } + st.appendChild(sl); cols.appendChild(st); + const rs = h('section'); rs.appendChild(sect('Studies', 'newest first')); + const rl = h('ul', 'rows'); + for (const s2 of LAB.project.studies.slice().sort((a, b) => b.updated.localeCompare(a.updated)).slice(0, 6)) { + const li = h('li'); const b = h('button', 'row ov-study'); b.type = 'button'; + b.appendChild(stateEl(studyState(s2), '')); + const t = h('span'); t.appendChild(h('span', 'title', s2.label)); t.appendChild(h('span', 'sub', s2.decision)); b.appendChild(t); + b.appendChild(h('span', 'sub num', fmtDate(s2.updated))); + b.addEventListener('click', () => act.go('train', s2.id)); li.appendChild(b); rl.appendChild(li); + } + rs.appendChild(rl); cols.appendChild(rs); main.appendChild(cols); + + const lg = h('section', 'ov-history'); lg.appendChild(sect('Model history', `${accLabel(ACC[0].id)} per checkpoint`)); + const c = h('div'); lg.appendChild(c); + Charts.curve(c, LAB.models, { selected: null, onSelect: id => act.go('models', id), metric: ACC[0].id, sections: CURVE_SECTIONS, yLabel: accLabel(ACC[0].id), secondary: ACC[1] || null }); + const bp = h('div', 'actions'); + for (const f of graph.families) { const pp = byId.get(f.parent); const b = h('button', 'btn sm'); b.type = 'button'; b.appendChild(icon('branch')); b.appendChild(document.createTextNode(` ${pp.ck || pp.short} · ${f.children.length} fits`)); b.addEventListener('click', () => act.go('models', pp.id)); bp.appendChild(b); } + const open = h('button', 'btn sm ghost', 'All models'); open.type = 'button'; open.addEventListener('click', () => act.go('models')); bp.appendChild(open); + lg.appendChild(bp); main.appendChild(lg); + return false; + } + + // ---- Data: datasets, then the records inside one, with a volume viewer ---- + const DIV = () => { const dark = getComputedStyle(document.documentElement).colorScheme === 'dark'; return { mid: dark ? [56, 56, 53] : [240, 239, 236], neg: dark ? [79, 138, 224] : [46, 111, 207], pos: dark ? [217, 111, 60] : [210, 101, 47] }; }; + const SEQ = () => { const dark = getComputedStyle(document.documentElement).colorScheme === 'dark'; return { lo: dark ? [31, 38, 46] : [236, 240, 246], hi: dark ? [79, 138, 224] : [28, 92, 171] }; }; + // Synthetic volume field for the layout: smooth structure that varies by record, field and position. + const volumeFn = (seed, field) => (u, v, w) => { const a = seed * 0.37, b = seed * 0.11; const base = Math.sin(6.3 * u + a) * Math.cos(4.7 * v - b) * Math.cos(3.1 * w + a) * 0.7 + Math.sin(9 * u * v + 5 * w + b) * 0.3; if (/velocity/.test(field)) return Math.abs(base) * 0.9; if (/tracer/.test(field)) return Math.max(0, Math.sin(7 * (u - 0.5) * (v - 0.5) * 8 + w * 4 + a)) * 0.9; if (/error/.test(field)) return Math.sin(17 * u + 3 * a) * Math.cos(13 * v + b) * Math.sin(5 * w) * 0.6; return base; }; + const paint = (val, signed, c, q) => { if (signed) { const col = val < 0 ? c.neg : c.pos, t = Math.min(1, Math.abs(val)); return c.mid.map((m, k) => Math.round(m + (col[k] - m) * t)); } const t = Math.min(1, Math.max(0, val)); return q.lo.map((m, k) => Math.round(m + (q.hi[k] - m) * t)); }; + function drawSlice2(canvas, fn, signed, n, size, w) { + const ctx = canvas.getContext('2d'); canvas.width = size; canvas.height = size; const c = DIV(), q = SEQ(); + for (let j = 0; j < n; j++) for (let i = 0; i < n; i++) { const rgb = paint(fn(i / n, j / n, w), signed, c, q); ctx.fillStyle = `rgb(${rgb[0]},${rgb[1]},${rgb[2]})`; ctx.fillRect(i * size / n, j * size / n, size / n + 1, size / n + 1); } + } + // Isometric stack of slices: a voxel-like impression of the whole grid. + function drawVolume(canvas, fn, signed, dims, wSel) { + const W = canvas.width = 480, H = canvas.height = 360, ctx = canvas.getContext('2d'); ctx.clearRect(0, 0, W, H); const c = DIV(), q = SEQ(); + const [nx, ny, nz] = dims, sx = 16, sy = Math.max(4, Math.round(16 * ny / nx)), nsl = Math.min(nz, 10); + const cw = Math.min(14, 300 / sx), ch = cw * 0.5, dz = Math.min(22, 220 / nsl); + const ox = W / 2 - (sx * cw) / 2 + (sy * cw) / 4, oy = H - 40 - (nsl - 1) * dz - (sy * ch) / 2; + for (let k = 0; k < nsl; k++) { + const w = (k + 0.5) / nsl, hot = wSel != null && Math.abs(w - wSel) < 0.5 / nsl + 1e-6; + ctx.globalAlpha = hot ? 1 : 0.55; + for (let j = 0; j < sy; j++) for (let i = 0; i < sx; i++) { + const rgb = paint(fn(i / sx, j / sy, w), signed, c, q); ctx.fillStyle = `rgb(${rgb[0]},${rgb[1]},${rgb[2]})`; + const px = ox + i * cw - j * (cw / 2), py = oy + (nsl - 1 - k) * dz + j * ch + i * (ch / 2) * 0; + ctx.beginPath(); ctx.moveTo(px, py); ctx.lineTo(px + cw, py); ctx.lineTo(px + cw - cw / 2, py + ch); ctx.lineTo(px - cw / 2, py + ch); ctx.closePath(); ctx.fill(); + } + if (hot) { ctx.globalAlpha = 1; ctx.strokeStyle = getComputedStyle(document.documentElement).getPropertyValue('--accent').trim() || '#2c5fb8'; ctx.lineWidth = 2; const py = oy + (nsl - 1 - k) * dz; ctx.beginPath(); ctx.moveTo(ox, py); ctx.lineTo(ox + sx * cw, py); ctx.lineTo(ox + sx * cw - sy * cw / 2, py + sy * ch); ctx.lineTo(ox - sy * cw / 2, py + sy * ch); ctx.closePath(); ctx.stroke(); } + } + ctx.globalAlpha = 1; + } + function data(main, aside, state, act) { + main.textContent = ''; aside.textContent = ''; + const sel = state.sel.data, d0 = LAB.project.data, ACTIONS = ['import', 'generate', 'release']; + const ds = d0.find(x => x.id === sel); + if (ds && ds.state !== 'missing') return datasetView(main, aside, ds, state, act); + const ac = h('div', 'ds-actions'); + for (const [id, t] of [['import', 'Import'], ['generate', 'Generate'], ['annotate', 'Annotate'], ['release', 'Release']]) { const b = h('button', 'btn', t); b.type = 'button'; b.setAttribute('aria-pressed', String(sel === id)); b.addEventListener('click', () => id === 'annotate' ? act.go('annotate') : act.select(sel === id ? null : id)); ac.appendChild(b); } + main.appendChild(ac); + main.appendChild(sect('Datasets', String(d0.length))); + const grid = h('div', 'ds-grid'); + for (const r of d0) { + const b = h('button', 'ds-card'); b.type = 'button'; b.setAttribute('aria-pressed', String(r.id === sel)); + if (r.state !== 'missing') { const cv = h('canvas', 'pv'); b.appendChild(cv); const fn = volumeFn(r.id.length * 3 + 1, r.fields[0]); const ctx = cv.getContext('2d'); cv.width = 320; cv.height = 180; const c = DIV(), q = SEQ(); const n = 32, m = 18; for (let j = 0; j < m; j++) for (let i = 0; i < n; i++) { const rgb = paint(fn(i / n, j / m, 0.5), !/velocity|tracer/.test(r.fields[0]), c, q); ctx.fillStyle = `rgb(${rgb[0]},${rgb[1]},${rgb[2]})`; ctx.fillRect(i * 10, j * 10, 11, 11); } } + else b.appendChild(h('div', 'pv text', 'file missing')); + const t = h('div', 't'); t.appendChild(h('div', 'title', r.label)); + const meta = h('div', 'meta'); meta.appendChild(h('span', null, r.records.toLocaleString('en-GB') + ' ' + r.recordKind + (r.records === 1 ? '' : 's') + ' · ' + r.grid.join('×'))); meta.appendChild(h('span', null, fmtBytes(r.bytes))); + const g = h('span', 'glyph ' + (r.state === 'missing' ? 'serious' : r.integrity === 'verified' ? 'good' : 'neutral')); g.appendChild(icon(r.state === 'missing' ? 'triangle' : r.integrity === 'verified' ? 'check' : 'minus')); g.title = r.state === 'missing' ? 'Missing' : r.integrity === 'verified' ? 'Hash verified' : 'No declared hash'; meta.appendChild(g); t.appendChild(meta); + t.appendChild(fileLink(r.path)); b.appendChild(t); + b.addEventListener('click', () => act.select(r.id)); grid.appendChild(b); + } + main.appendChild(grid); + if (ACTIONS.includes(sel)) { dataPanel(aside, sel, state, act); return true; } + if (ds && ds.state === 'missing') { + const ins = h('div', 'inspector'); const hd = h('header'); hd.appendChild(h('span', 'kicker', ds.kind + ' · ' + ds.id)); hd.appendChild(h('h2', null, ds.label)); ins.appendChild(hd); + const dl = h('dl', 'metrics'); dl.appendChild(cell('Records', `${ds.records} ${ds.recordKind}s`)); dl.appendChild(cell('Grid', ds.grid.join(' × '))); dl.appendChild(cell('State', 'file missing')); ins.appendChild(dl); + const pa = h('p', 'note'); pa.appendChild(fileLink(ds.path)); ins.appendChild(pa); ins.appendChild(h('p', 'note', 'Restore the file, or open a new snapshot without it.')); aside.appendChild(ins); return true; + } + const ins = h('div', 'inspector'); const dl = h('dl', 'metrics'); + dl.appendChild(cell('Datasets', String(d0.length))); dl.appendChild(cell('Records', d0.reduce((a, x) => a + (x.records || 0), 0).toLocaleString('en-GB'))); dl.appendChild(cell('On disk', fmtBytes(d0.reduce((a, x) => a + (x.bytes || 0), 0)))); dl.appendChild(cell('Missing', String(d0.filter(x => x.state === 'missing').length))); + ins.appendChild(dl); aside.appendChild(ins); return false; + } + function datasetView(main, aside, r, state, act) { + const ui = state.ui || {}, per = 48, page = ui['page:' + r.id] || 0, rec = ui['rec:' + r.id] != null ? ui['rec:' + r.id] : 0, field = ui['field:' + r.id] || r.fields[0], w = ui['w:' + r.id] != null ? ui['w:' + r.id] : 0.5; + const back = h('button', 'btn sm ghost ds-back', '← All datasets'); back.type = 'button'; back.addEventListener('click', () => act.select(null)); main.appendChild(back); + const head = h('div', 'ds-head'); head.appendChild(h('h2', null, r.label)); + const meta = h('div', 'meta'); meta.appendChild(h('span', null, `${r.records.toLocaleString('en-GB')} ${r.recordKind}${r.records === 1 ? '' : 's'}` + (r.scenes ? ` · ${r.scenes} scenes` : ''))); meta.appendChild(h('span', null, r.grid.join(' × ') + ' cells')); meta.appendChild(h('span', null, fmtBytes(r.bytes))); + const g = h('span', 'glyph ' + (r.integrity === 'verified' ? 'good' : 'neutral')); g.appendChild(icon(r.integrity === 'verified' ? 'check' : 'minus')); g.title = r.integrity === 'verified' ? 'Hash verified' : 'No declared hash'; meta.appendChild(g); meta.appendChild(fileLink(r.path)); head.appendChild(meta); + const acts = h('div', 'actions'); const a1 = h('a', 'btn sm', 'Open folder'); a1.href = fileLink(r.path).href; acts.appendChild(a1); const b2 = h('button', 'btn sm', 'Annotate'); b2.type = 'button'; b2.disabled = r.kind !== 'records'; acts.appendChild(b2); const b3 = h('button', 'btn sm', 'Release'); b3.type = 'button'; b3.addEventListener('click', () => { act.setDataAction('dataset', r.id); act.select('release'); }); acts.appendChild(b3); head.appendChild(acts); + main.appendChild(head); + if (r.describes) main.appendChild(h('p', 'small muted', r.describes)).style.marginBottom = '12px'; + const body = h('div', 'ds-body'); + const left = h('div'); left.appendChild(sect(r.recordKind.charAt(0).toUpperCase() + r.recordKind.slice(1) + 's', `${page * per + 1}–${Math.min(r.records, (page + 1) * per)} of ${r.records}`)); + const grid = h('div', 'rec-grid'); + for (let i = page * per; i < Math.min(r.records, (page + 1) * per); i++) { + const b = h('button', 'rec'); b.type = 'button'; b.setAttribute('aria-pressed', String(i === rec)); b.setAttribute('aria-label', r.recordKind + ' ' + (i + 1)); + const cv = h('canvas'); drawSlice2(cv, volumeFn(i + 1, field), !/velocity|tracer/.test(field), 16, 64, 0.5); b.appendChild(cv); b.appendChild(h('span', null, String(i + 1))); + b.addEventListener('click', () => act.setUI('rec:' + r.id, i)); grid.appendChild(b); + } + left.appendChild(grid); + if (r.records > per) { const pg = h('div', 'pager'); const pb = h('button', 'btn sm', 'Previous'); pb.type = 'button'; pb.disabled = page === 0; pb.addEventListener('click', () => act.setUI('page:' + r.id, page - 1)); const nb = h('button', 'btn sm', 'Next'); nb.type = 'button'; nb.disabled = (page + 1) * per >= r.records; nb.addEventListener('click', () => act.setUI('page:' + r.id, page + 1)); pg.appendChild(pb); pg.appendChild(nb); pg.appendChild(h('span', null, `page ${page + 1} of ${Math.ceil(r.records / per)}`)); left.appendChild(pg); } + body.appendChild(left); + const vw = h('div', 'viewer'); + const fn = volumeFn(rec + 1, field), signed = !/velocity|tracer/.test(field); + const vol = h('canvas', 'vol'); vol.setAttribute('role', 'img'); vol.setAttribute('aria-label', `${field} volume of ${r.recordKind} ${rec + 1}, ${r.grid.join(' by ')} cells`); drawVolume(vol, fn, signed, r.grid, w); vw.appendChild(vol); + const row2 = h('div', 'row2'); const sl = h('canvas', 'sl'); sl.setAttribute('role', 'img'); sl.setAttribute('aria-label', 'Slice'); drawSlice2(sl, fn, signed, 32, 240, w); row2.appendChild(sl); + const facts = h('dl', 'facts facts-sm'); for (const [k, v] of [[r.recordKind.charAt(0).toUpperCase() + r.recordKind.slice(1), String(rec + 1) + (r.dt ? ' · t = ' + (rec * (r.dt.includes('/') ? 1 / +r.dt.split('/')[1].replace(/\D/g, '') : +r.dt)).toFixed(3) + ' s' : '')], ['Grid', r.grid.join(' × ')], ['Spacing', r.spacing || '—'], ['Fields', r.fields.join(', ')], ['Slice', 'z = ' + Math.round(w * (r.grid[2] - 1) + 1) + ' of ' + r.grid[2]]]) { facts.appendChild(h('dt', null, k)); facts.appendChild(h('dd', null, v)); } + row2.appendChild(facts); vw.appendChild(row2); + const ctl = h('div', 'ctl'); + const fl = h('label'); fl.appendChild(document.createTextNode('Field')); const fs = h('select'); for (const f of r.fields) { const o = h('option', null, f); o.selected = f === field; fs.appendChild(o); } fs.addEventListener('change', () => act.setUI('field:' + r.id, fs.value)); fl.appendChild(fs); ctl.appendChild(fl); + const zl = h('label'); zl.appendChild(document.createTextNode('Slice')); const zi = h('input'); zi.type = 'range'; zi.min = 0; zi.max = r.grid[2] - 1; zi.value = Math.round(w * (r.grid[2] - 1)); zi.addEventListener('input', () => { const ww = +zi.value / Math.max(1, r.grid[2] - 1); drawVolume(vol, fn, signed, r.grid, ww); drawSlice2(sl, fn, signed, 32, 240, ww); const dd = facts.querySelectorAll('dd'); dd[dd.length - 1].textContent = 'z = ' + (+zi.value + 1) + ' of ' + r.grid[2]; }); zi.addEventListener('change', () => { state.ui['w:' + r.id] = +zi.value / Math.max(1, r.grid[2] - 1); }); zl.appendChild(zi); ctl.appendChild(zl); + const an = h('button', 'btn sm', 'Compare in Analysis'); an.type = 'button'; an.addEventListener('click', () => { act.setCase(rec + 1); act.go('analysis'); }); ctl.appendChild(an); + vw.appendChild(ctl); body.appendChild(vw); main.appendChild(body); + return false; + } + function dataPanel(aside, kind, state, act) { + const n = state.dataAction || {}; + const ins = h('div', 'inspector'); const f = h('div', 'form'); + const field = (label, control, hint) => { const l = h('label'); l.appendChild(document.createTextNode(label)); l.appendChild(control); if (hint) l.appendChild(h('span', 'hint', hint)); return l; }; + const radio = (name, opts, cur, key) => { const r = h('div', 'radio'); for (const [v, t] of opts) { const l = h('label'); const i = h('input'); i.type = 'radio'; i.name = name; i.checked = v === cur; i.addEventListener('change', () => act.setDataAction(key, v)); l.appendChild(i); l.appendChild(document.createTextNode(t)); r.appendChild(l); } return r; }; + const hd = h('header'); + if (kind === 'import') { + hd.appendChild(h('span', 'kicker', 'data')); hd.appendChild(h('h2', null, 'Import')); ins.appendChild(hd); + f.appendChild(field('Source', radio('src', [['files', 'Files or folder'], ['release', 'Catalog release'], ['project', 'Another project']], n.src || 'files', 'src'))); + const pathI = h('input'); pathI.type = 'text'; pathI.placeholder = 'relative to ' + LAB.project.root; pathI.value = n.path || ''; f.appendChild(field('Path', pathI)); + f.appendChild(field('Kind', radio('kind', [['fields', 'Fields'], ['images', 'Images'], ['text', 'Text'], ['audio', 'Audio'], ['mesh', 'Mesh']], n.kind || 'fields', 'kind'))); + const nm = h('input'); nm.type = 'text'; nm.placeholder = 'dataset name'; f.appendChild(field('Name', nm)); + const rights = h('input'); rights.type = 'text'; rights.value = 'unknown'; f.appendChild(field('Rights', rights, 'unknown rights allow local use and deny redistribution')); + ins.appendChild(f); + const acts = h('div', 'actions'); const b = h('button', 'btn primary', 'Import'); b.type = 'button'; acts.appendChild(b); const c = h('button', 'btn ghost', 'Close'); c.type = 'button'; c.addEventListener('click', () => act.select(null)); acts.appendChild(c); ins.appendChild(acts); + ins.appendChild(h('p', 'note', 'Bytes are hashed on import; the dataset keeps the hash and the source path.')); + } else if (kind === 'generate') { + hd.appendChild(h('span', 'kicker', 'data')); hd.appendChild(h('h2', null, 'Generate')); ins.appendChild(hd); + const gens = LAB.generators || []; const gsel = h('select'); for (const g of gens) { const o = h('option', null, g.label); o.value = g.id; o.selected = g.id === (n.generator || (gens[0] && gens[0].id)); gsel.appendChild(o); } gsel.addEventListener('change', () => act.setDataAction('generator', gsel.value)); const g = gens.find(x => x.id === (n.generator || (gens[0] && gens[0].id))); f.appendChild(field('Generator', gsel, g ? g.command : '')); + if (g) for (const prm of g.params) { const i = h('input'); i.type = prm.type || 'text'; i.value = n['p_' + prm.id] != null ? n['p_' + prm.id] : prm.value; i.addEventListener('change', () => act.setDataAction('p_' + prm.id, i.value)); f.appendChild(field(prm.label, i, prm.hint || '')); } + const out = h('input'); out.type = 'text'; out.value = n.out || (g ? g.out : ''); f.appendChild(field('Output dataset', out)); + ins.appendChild(f); + const acts = h('div', 'actions'); const b = h('button', 'btn primary', 'Generate'); b.type = 'button'; acts.appendChild(b); const c = h('button', 'btn ghost', 'Close'); c.type = 'button'; c.addEventListener('click', () => act.select(null)); acts.appendChild(c); ins.appendChild(acts); + ins.appendChild(h('p', 'note', 'Runs as an ordinary recipe. The result appears here as a dataset with its receipt.')); + } else { + hd.appendChild(h('span', 'kicker', 'data')); hd.appendChild(h('h2', null, 'Release')); ins.appendChild(hd); + const dsel = h('select'); for (const r of LAB.project.data) { if (r.state === 'missing') continue; const o = h('option', null, r.label); o.value = r.id; o.selected = r.id === n.dataset; dsel.appendChild(o); } dsel.addEventListener('change', () => act.setDataAction('dataset', dsel.value)); f.appendChild(field('Dataset', dsel)); + const nm = h('input'); nm.type = 'text'; nm.placeholder = 'release name'; nm.value = n.releaseName || ''; f.appendChild(field('Name', nm)); + const three = h('div', 'two'); three.style.gridTemplateColumns = '1fr 1fr 1fr'; for (const [k, v] of [['Train %', 70], ['Validation %', 15], ['Test %', 15]]) { const i = h('input'); i.type = 'number'; i.min = 0; i.max = 100; i.value = v; three.appendChild(field(k, i)); } f.appendChild(three); + f.appendChild(field('Selection', radio('selr', [['all', 'All records'], ['saved', 'Saved selection']], n.selr || 'all', 'selr'))); + ins.appendChild(f); + const acts = h('div', 'actions'); const b = h('button', 'btn primary', 'Freeze release'); b.type = 'button'; acts.appendChild(b); const c = h('button', 'btn ghost', 'Close'); c.type = 'button'; c.addEventListener('click', () => act.select(null)); acts.appendChild(c); ins.appendChild(acts); + ins.appendChild(h('p', 'note', 'A release freezes exact revisions. Training reads releases, never live records.')); + } + aside.appendChild(ins); + } + + // ---- Annotate: records, viewer, labels, review, history -------------------- + function annotate(main, aside, state, act) { + main.textContent = ''; aside.textContent = ''; + const A = LAB.annotation || { tasks: [] }, ui = state.ui || {}, ann = state.annotations || {}; + const sets = LAB.project.data.filter(r => r.state !== 'missing'); + const dsId = ui['ann:ds'] || A.defaultDataset || (sets[0] && sets[0].id), r = sets.find(x => x.id === dsId) || sets[0]; + const task = A.tasks.find(t => t.id === (ui['ann:task'] || (A.tasks[0] && A.tasks[0].id))) || A.tasks[0]; + const per = 48, page = ui['ann:page'] || 0, rec = ui['ann:rec'] != null ? ui['ann:rec'] : 0, filter = ui['ann:filter'] || 'all'; + const store = ann[r.id] || {}; const seedOf = i => { const sd = (A.seed || {})[r.id]; return sd && i < sd.reviewed ? { label: sd.labels[i], review: sd.labels[i] === 'needs work' ? 'needs' : 'accepted', revisions: [{ at: 'imported', label: sd.labels[i], review: 'accepted' }] } : null; }; + const recOf = i => store[i] || seedOf(i) || null; + const reviewed = Array.from({ length: r.records }, (_, i) => recOf(i)).filter(Boolean).length; + const bar = h('div', 'ann-bar'); + const dl = h('label'); dl.appendChild(document.createTextNode('Dataset')); const dsel = h('select'); for (const x of sets) { const o = h('option', null, x.label); o.value = x.id; o.selected = x.id === r.id; dsel.appendChild(o); } dsel.addEventListener('change', () => { act.setUI('ann:rec', 0); act.setUI('ann:page', 0); act.setUI('ann:ds', dsel.value); }); dl.appendChild(dsel); bar.appendChild(dl); + const tl = h('label'); tl.appendChild(document.createTextNode('Task')); const tsel = h('select'); for (const t of A.tasks) { const o = h('option', null, t.label); o.value = t.id; o.selected = t.id === task.id; tsel.appendChild(o); } tsel.addEventListener('change', () => act.setUI('ann:task', tsel.value)); tl.appendChild(tsel); bar.appendChild(tl); + const seg = h('div', 'seg'); for (const [v, t] of [['all', 'All'], ['unreviewed', 'Unreviewed'], ['accepted', 'Accepted'], ['needs', 'Needs work']]) { const b = h('button', null, t); b.type = 'button'; b.setAttribute('aria-pressed', String(filter === v)); b.addEventListener('click', () => { act.setUI('ann:page', 0); act.setUI('ann:filter', v); }); seg.appendChild(b); } bar.appendChild(seg); + const pr = h('span', 'progress'); const pi = h('i'); const pb = h('b'); pb.style.width = Math.round(100 * reviewed / r.records) + '%'; pi.appendChild(pb); pr.appendChild(pi); pr.appendChild(document.createTextNode(`${reviewed} of ${r.records} reviewed`)); bar.appendChild(pr); + const kb = h('span', 'small faint'); kb.appendChild(h('span', 'kbd', '←')); kb.appendChild(document.createTextNode(' ')); kb.appendChild(h('span', 'kbd', '→')); kb.appendChild(document.createTextNode(' move · ')); kb.appendChild(h('span', 'kbd', '1')); kb.appendChild(document.createTextNode('–')); kb.appendChild(h('span', 'kbd', String((task.classes || task.options || []).length))); kb.appendChild(document.createTextNode(' label · ')); kb.appendChild(h('span', 'kbd', 'Enter')); kb.appendChild(document.createTextNode(' save and next')); bar.appendChild(kb); + main.appendChild(bar); + const all = Array.from({ length: r.records }, (_, i) => i).filter(i => { const a = recOf(i); return filter === 'all' ? true : filter === 'unreviewed' ? !a : filter === 'accepted' ? a && a.review === 'accepted' : a && a.review === 'needs'; }); + const body = h('div', 'ann-body'); + const left = h('div'); left.appendChild(sect(r.recordKind.charAt(0).toUpperCase() + r.recordKind.slice(1) + 's', all.length ? `${page * per + 1}–${Math.min(all.length, (page + 1) * per)} of ${all.length}` : '0')); + const grid = h('div', 'rec-grid'); + for (const i of all.slice(page * per, (page + 1) * per)) { + const b = h('button', 'rec'); b.type = 'button'; b.setAttribute('aria-pressed', String(i === rec)); const a = recOf(i); b.setAttribute('aria-label', r.recordKind + ' ' + (i + 1) + (a ? ', ' + (a.label || '') + ' ' + a.review : ', unreviewed')); + const cv = h('canvas'); drawSlice2(cv, volumeFn(i + 1, r.fields[0]), !/velocity|tracer/.test(r.fields[0]), 16, 64, 0.5); b.appendChild(cv); b.appendChild(h('span', null, String(i + 1))); + if (a) b.appendChild(h('i', 'badge ' + (a.review || 'labelled'))); + b.addEventListener('click', () => act.setUI('ann:rec', i)); grid.appendChild(b); + } + left.appendChild(grid); + if (all.length > per) { const pg = h('div', 'pager'); const pb2 = h('button', 'btn sm', 'Previous'); pb2.type = 'button'; pb2.disabled = page === 0; pb2.addEventListener('click', () => act.setUI('ann:page', page - 1)); const nb = h('button', 'btn sm', 'Next'); nb.type = 'button'; nb.disabled = (page + 1) * per >= all.length; nb.addEventListener('click', () => act.setUI('ann:page', page + 1)); pg.appendChild(pb2); pg.appendChild(nb); pg.appendChild(h('span', null, `page ${page + 1} of ${Math.ceil(all.length / per)}`)); left.appendChild(pg); } + body.appendChild(left); + const vw = h('div', 'viewer'); const fn = volumeFn(rec + 1, r.fields[0]), signed = !/velocity|tracer/.test(r.fields[0]); + let w = ui['ann:w'] != null ? ui['ann:w'] : 0.5; + const vol = h('canvas', 'vol'); vol.setAttribute('role', 'img'); vol.setAttribute('aria-label', `${r.fields[0]} volume of ${r.recordKind} ${rec + 1}`); drawVolume(vol, fn, signed, r.grid, w); vw.appendChild(vol); + const row2 = h('div', 'row2'); const sl = h('canvas', 'sl'); sl.setAttribute('role', 'img'); sl.setAttribute('aria-label', 'Slice'); drawSlice2(sl, fn, signed, 32, 240, w); row2.appendChild(sl); + const facts = h('dl', 'facts'); const sliceDd = h('dd', null, 'z = ' + Math.round(w * (r.grid[2] - 1) + 1) + ' of ' + r.grid[2]); + for (const [k, v] of [[r.recordKind.charAt(0).toUpperCase() + r.recordKind.slice(1), String(rec + 1) + ' of ' + r.records], ['Grid', r.grid.join(' × ')], ['Fields', r.fields.join(', ')]]) { facts.appendChild(h('dt', null, k)); facts.appendChild(h('dd', null, v)); } facts.appendChild(h('dt', null, 'Slice')); facts.appendChild(sliceDd); + row2.appendChild(facts); vw.appendChild(row2); + const ctl = h('div', 'ctl'); const zl = h('label'); zl.appendChild(document.createTextNode('Slice')); const zi = h('input'); zi.type = 'range'; zi.min = 0; zi.max = r.grid[2] - 1; zi.value = Math.round(w * (r.grid[2] - 1)); + zi.addEventListener('input', () => { w = +zi.value / Math.max(1, r.grid[2] - 1); drawVolume(vol, fn, signed, r.grid, w); drawSlice2(sl, fn, signed, 32, 240, w); sliceDd.textContent = 'z = ' + (+zi.value + 1) + ' of ' + r.grid[2]; }); + zi.addEventListener('change', () => { state.ui['ann:w'] = w; }); zl.appendChild(zi); ctl.appendChild(zl); + const prev = h('button', 'btn sm', 'Previous'); prev.type = 'button'; prev.disabled = rec === 0; prev.addEventListener('click', () => act.setUI('ann:rec', rec - 1)); const next = h('button', 'btn sm', 'Next'); next.type = 'button'; next.disabled = rec >= r.records - 1; next.addEventListener('click', () => act.setUI('ann:rec', rec + 1)); ctl.appendChild(prev); ctl.appendChild(next); + vw.appendChild(ctl); body.appendChild(vw); main.appendChild(body); + // Form for the current record. + const cur = recOf(rec) || {}, draft = Object.assign({ label: cur.label || null, tags: cur.tags || [], review: cur.review || null, notes: cur.notes || '' }, state.draft && state.draft.key === r.id + ':' + rec ? state.draft.v : {}); + const ins = h('div', 'inspector'); + const hd = h('header'); hd.appendChild(h('span', 'kicker', r.label)); hd.appendChild(h('h2', null, r.recordKind.charAt(0).toUpperCase() + r.recordKind.slice(1) + ' ' + (rec + 1))); const meta = h('div', 'ins-meta'); meta.appendChild(cur.review ? stateEl(cur.review === 'accepted' ? 'good' : cur.review === 'needs' ? 'warn' : 'serious', cur.review === 'needs' ? 'needs work' : cur.review) : stateEl('neutral', 'unreviewed')); hd.appendChild(meta); ins.appendChild(hd); + const f = h('div', 'form'); + const field = (label, control) => { const l = h('div'); l.appendChild(h('h3', null, label)); l.appendChild(control); return l; }; + const setDraft = (k, v) => { state.draft = { key: r.id + ':' + rec, v: Object.assign({}, draft, { [k]: v }) }; act.setUI('ann:tick', (ui['ann:tick'] || 0) + 1); }; + if (task.type === 'class') { const rd = h('div', 'radio'); task.classes.forEach((c, i) => { const l = h('label'); const inp = h('input'); inp.type = 'radio'; inp.name = 'lbl'; inp.checked = draft.label === c; inp.addEventListener('change', () => setDraft('label', c)); l.appendChild(inp); l.appendChild(document.createTextNode(c)); l.appendChild(h('span', 'kbd', String(i + 1))); rd.appendChild(l); }); f.appendChild(field(task.label, rd)); } + else { const rd = h('div', 'radio'); task.options.forEach((c, i) => { const l = h('label'); const inp = h('input'); inp.type = 'checkbox'; inp.checked = draft.tags.includes(c); inp.addEventListener('change', () => setDraft('tags', inp.checked ? draft.tags.concat([c]) : draft.tags.filter(x => x !== c))); l.appendChild(inp); l.appendChild(document.createTextNode(c)); l.appendChild(h('span', 'kbd', String(i + 1))); rd.appendChild(l); }); f.appendChild(field(task.label, rd)); } + const rv = h('div', 'seg'); for (const [v, t, c] of [['accepted', 'Accept', 'ok'], ['needs', 'Needs work', 'warn'], ['reject', 'Reject', 'bad']]) { const b = h('button', c, t); b.type = 'button'; b.setAttribute('aria-pressed', String(draft.review === v)); b.addEventListener('click', () => setDraft('review', v)); rv.appendChild(b); } f.appendChild(field('Review', rv)); + const notes = h('textarea'); notes.rows = 2; notes.value = draft.notes; notes.placeholder = 'notes'; notes.addEventListener('change', () => setDraft('notes', notes.value)); f.appendChild(field('Notes', notes)); + ins.appendChild(f); + const acts = h('div', 'actions'); const save = h('button', 'btn primary', 'Save and next'); save.type = 'button'; save.disabled = !draft.review && !draft.label && !draft.tags.length; save.addEventListener('click', () => act.saveAnnotation(r.id, rec, draft)); acts.appendChild(save); const skip = h('button', 'btn ghost', 'Skip'); skip.type = 'button'; skip.addEventListener('click', () => act.setUI('ann:rec', Math.min(r.records - 1, rec + 1))); acts.appendChild(skip); ins.appendChild(acts); + const hist = cur.revisions || []; if (hist.length) { const d = h('div'); d.appendChild(h('h3', null, 'History')); const ul = h('ul', 'hist'); for (const rv2 of hist.slice().reverse()) { const li = h('li'); li.appendChild(h('b', null, rv2.at)); li.appendChild(document.createTextNode((rv2.label || (rv2.tags || []).join(', ') || '—') + ' · ' + (rv2.review === 'needs' ? 'needs work' : rv2.review || ''))); ul.appendChild(li); } d.appendChild(ul); ins.appendChild(d); } + aside.appendChild(ins); + main.tabIndex = -1; + main.onkeydown = ev => { if (ev.target.tagName === 'TEXTAREA' || ev.target.tagName === 'INPUT' || ev.target.tagName === 'SELECT') return; if (ev.key === 'ArrowRight') { act.setUI('ann:rec', Math.min(r.records - 1, rec + 1)); ev.preventDefault(); } else if (ev.key === 'ArrowLeft') { act.setUI('ann:rec', Math.max(0, rec - 1)); ev.preventDefault(); } else if (/^[1-9]$/.test(ev.key)) { const opts = task.classes || task.options; const c = opts[+ev.key - 1]; if (c) { if (task.type === 'class') setDraft('label', c); else setDraft('tags', draft.tags.includes(c) ? draft.tags.filter(x => x !== c) : draft.tags.concat([c])); } } else if (ev.key === 'Enter' && !save.disabled) act.saveAnnotation(r.id, rec, draft); }; + return true; + } + + // ---- Models -------------------------------------------------------------- + function models(main, aside, state, act, opts = {}) { + aside.textContent = ''; + const sel = state.sel.models; + const buildBar = () => { + const bar = h('div', 'filters'); + const q = h('input'); q.type = 'search'; q.placeholder = 'Find a fit'; q.value = state.query || ''; q.setAttribute('aria-label', 'Find a fit'); q.addEventListener('input', () => act.setQuery(q.value)); bar.appendChild(q); + const grp = h('div', 'grp'); grp.setAttribute('role', 'group'); grp.setAttribute('aria-label', 'Kind of change'); + for (const k of KINDS) { const b = h('button', 'btn sm chip ' + k, Tree.kindLabel(k)); b.type = 'button'; b.setAttribute('aria-pressed', String(!state.kinds || state.kinds.has(k))); b.addEventListener('click', () => act.toggleKind(k)); grp.appendChild(b); } + bar.appendChild(grp); + const showMap = opts.stacked || state.view === 'map'; + if (!opts.stacked && opts.views && opts.views.length > 1) { const vg = h('div', 'grp'); vg.setAttribute('role', 'group'); vg.setAttribute('aria-label', 'View'); for (const v of opts.views) { const b = h('button', 'btn sm', v === 'list' ? 'List' : 'Map'); b.type = 'button'; b.setAttribute('aria-pressed', String(state.view === v)); b.addEventListener('click', () => act.setView(v)); vg.appendChild(b); } bar.appendChild(vg); } + if (showMap) { + const tb = h('button', 'btn sm', 'Accuracy track'); tb.type = 'button'; tb.setAttribute('aria-pressed', String(!!state.track)); tb.addEventListener('click', () => act.toggleTrack()); bar.appendChild(tb); + const z = h('div', 'zoomctl'); for (const [t, d, l] of [['−', -0.2, 'Zoom out'], ['+', 0.2, 'Zoom in']]) { const b = h('button', 'btn sm', t); b.type = 'button'; b.setAttribute('aria-label', l); b.addEventListener('click', () => act.zoom(d)); z.appendChild(b); } bar.appendChild(z); + } + if (sel && byId.get(sel) && !byId.get(sel).planned) { const bb = h('button', 'btn sm primary'); bb.type = 'button'; bb.appendChild(icon('branch')); bb.appendChild(document.createTextNode(' Branch from ' + (byId.get(sel).ck || byId.get(sel).short))); bb.addEventListener('click', () => act.branch(sel)); bar.appendChild(bb); } + bar.appendChild(h('span', 'pop', `${LAB.models.length} fits · ${withBench} benchmarked`)); + return bar; + }; + const sig = JSON.stringify([state.kinds ? [...state.kinds] : null, state.query || '', state.zoom || 1, !!state.track, !!opts.stacked, state.view, plannedVersion]); + const prev = main._tree; + const common = { onSelect: id => act.select(id), kinds: state.kinds, query: state.query, barLabel: accLabel(ACC[0].id), unit: TIME.unit, trackLabel: accLabel(ACC[0].id) + ', lower is better', metric: ACC[0].id, timeId: TIME.id }; + if (prev && prev.sig === sig && main.contains(prev.bar)) { + const bar = buildBar(); prev.bar.replaceWith(bar); prev.bar = bar; + if (prev.map) prev.map.select(sel); if (prev.list) prev.list.select(sel); + if (sel && sel !== prev.sel) { if (prev.map) prev.map.scrollTo(sel, true); if (prev.list) prev.list.scrollTo(sel, true); } + prev.sel = sel; + } else { + main.textContent = ''; const bar = buildBar(); main.appendChild(bar); + const inst = { sig, bar, sel, map: null, list: null }; + const mapOpts = Object.assign({ selected: sel, zoom: state.zoom || 1, track: !!state.track }, common); + if (opts.stacked) { const mh = h('div', 'tree-map'); main.appendChild(mh); inst.map = Tree.renderMap(mh, graph, mapOpts); const lh = h('div', 'tree-host'); main.appendChild(lh); inst.list = Tree.renderList(lh, graph, Object.assign({ selected: sel }, common)); } + else { const host = h('div', state.view === 'map' ? 'tree-map' : 'tree-host'); main.appendChild(host); if (state.view === 'map') inst.map = Tree.renderMap(host, graph, mapOpts); else inst.list = Tree.renderList(host, graph, Object.assign({ selected: sel }, common)); } + if (sel) { if (inst.map) inst.map.scrollTo(sel, false); if (inst.list) inst.list.scrollTo(sel, false); } + main._tree = inst; + } + if (sel && byId.get(sel)) { if (byId.get(sel).planned) inspectorPlanned(aside, sel, state, act); else inspectorModel(aside, sel, act); return true; } + modelsGuide(aside, act); return false; + } + function modelsGuide(aside, act) { + const ins = h('div', 'inspector'); + const key = h('ul', 'keylist'); + for (const [cls, t] of [['k-solid', 'Derived from an earlier fit'], ['k-faint', 'Checkpoint order'], ['k-dash', 'Compared with (selected fit)'], ['k-bar', accLabel(ACC[0].id) + ', log scale, longer is better']]) { const li = h('li', cls); li.appendChild(h('i')); li.appendChild(h('span', null, t)); key.appendChild(li); } + ins.appendChild(key); + const d = h('div'); d.appendChild(h('h3', null, 'Branch points')); + const ul = h('ul', 'links'); + for (const f of graph.families) { const p = byId.get(f.parent); const first = byId.get(f.children[0]), last = byId.get(f.children[f.children.length - 1]); const li = h('li'); const b = h('button'); b.type = 'button'; b.appendChild(document.createTextNode(`${p.ck || p.short} · ${f.children.length} fits`)); b.appendChild(h('span', 'why', `${first.ck || first.short} to ${last.ck || last.short} · ${Tree.kindLabel(first.kind).toLowerCase()}`)); b.addEventListener('click', () => act.select(p.id)); li.appendChild(b); ul.appendChild(li); } + d.appendChild(ul); ins.appendChild(d); + const k = h('div'); k.appendChild(h('h3', null, 'Kinds of change')); + const dl = h('dl', 'metrics'); + for (const kind of KINDS) { const c = h('div'); c.appendChild(h('dt', 'chip ' + kind, Tree.kindLabel(kind))); c.appendChild(h('dd', null, String(LAB.models.filter(m => m.kind === kind).length))); dl.appendChild(c); } + k.appendChild(dl); ins.appendChild(k); + aside.appendChild(ins); + } + // A planned model: configured on its node, trained from Train. + function inspectorPlanned(aside, id, state, act) { + aside.textContent = ''; + const m = byId.get(id), p = byId.get(m.parent), n = m.setup || {}; + const ins = h('div', 'inspector'); + const hd = h('header'); hd.appendChild(h('span', 'kicker', 'planned · from ' + (p.ck || p.short))); hd.appendChild(h('h2', null, m.label)); + const meta = h('div', 'ins-meta'); meta.appendChild(stateEl(n.prepared ? 'good' : 'pending', n.prepared ? 'trial prepared' : 'not prepared')); hd.appendChild(meta); ins.appendChild(hd); + const lin = h('div', 'actions'); const pb = h('button', 'btn sm ghost'); pb.type = 'button'; pb.appendChild(icon('branch')); pb.appendChild(document.createTextNode(' From ' + (p.ck || p.short) + (p.worstP ? ' · ' + Tree.fmtSci(p.worstP) : ''))); pb.addEventListener('click', () => act.select(p.id)); lin.appendChild(pb); ins.appendChild(lin); + const f = h('div', 'form'); + const field = (label, control, hint) => { const l = h('label'); l.appendChild(document.createTextNode(label)); l.appendChild(control); if (hint) l.appendChild(h('span', 'hint', hint)); return l; }; + const nm = h('input'); nm.type = 'text'; nm.value = n.name || ''; nm.placeholder = 'name'; nm.addEventListener('change', () => act.setPlan(id, 'name', nm.value)); f.appendChild(field('Name', nm)); + const kr = h('div', 'radio'); for (const k of KINDS.slice(0, 3)) { const l = h('label'); const r = h('input'); r.type = 'radio'; r.name = 'kind-' + id; r.checked = (n.kind || 'refinement') === k; r.addEventListener('change', () => act.setPlan(id, 'kind', k)); l.appendChild(r); l.appendChild(document.createTextNode(Tree.kindLabel(k))); kr.appendChild(l); } f.appendChild(field('Kind of change', kr)); + const selRecipe = h('select'); for (const r of LAB.recipes || []) { if (r.kind === 'evaluation') continue; const o = h('option', null, r.label); o.value = r.id; o.selected = r.id === (n.recipe || 'run-study'); selRecipe.appendChild(o); } selRecipe.addEventListener('change', () => act.setPlan(id, 'recipe', selRecipe.value)); const rc = recipeOf(n.recipe || 'run-study'); f.appendChild(field('Recipe', selRecipe, rc ? rc.path + (rc.config ? ' · ' + rc.config : '') : '')); + const selData = h('select'); for (const r of LAB.project.data) { if (r.state === 'missing') continue; const o = h('option', null, r.label); o.value = r.id; o.selected = r.id === (n.data || 'water-capture'); selData.appendChild(o); } selData.addEventListener('change', () => act.setPlan(id, 'data', selData.value)); f.appendChild(field('Data', selData)); + const rr = h('div', 'radio'); for (const r of LAB.runtimes || []) { const l = h('label'); const i = h('input'); i.type = 'radio'; i.name = 'rt-' + id; i.checked = (n.runtime || (rc && rc.runtime)) === r.id; i.addEventListener('change', () => act.setPlan(id, 'runtime', r.id)); l.appendChild(i); l.appendChild(document.createTextNode(r.label)); rr.appendChild(l); } f.appendChild(field('Runtime', rr)); + const two = h('div', 'two'); const upd = h('input'); upd.type = 'number'; upd.min = 1; upd.value = n.updates || p.updates || 1600; upd.addEventListener('change', () => act.setPlan(id, 'updates', +upd.value)); two.appendChild(field('Updates', upd)); const lr = h('input'); lr.type = 'text'; lr.value = n.lr || p.lr || '1e-5'; lr.addEventListener('change', () => act.setPlan(id, 'lr', lr.value)); two.appendChild(field('Learning rate', lr)); f.appendChild(two); + const two2 = h('div', 'two'); const att = h('input'); att.type = 'number'; att.min = 1; att.value = n.attempts || 2; att.addEventListener('change', () => act.setPlan(id, 'attempts', +att.value)); two2.appendChild(field('Attempts', att)); const wall = h('input'); wall.type = 'number'; wall.min = 1; wall.value = n.wall || 90; wall.addEventListener('change', () => act.setPlan(id, 'wall', +wall.value)); two2.appendChild(field('Wall minutes', wall)); f.appendChild(two2); + const two3 = h('div', 'two'); const tm = h('select'); for (const a of ACC) { const o = h('option', null, a.label); o.value = a.id; o.selected = (n.target || ACC[0].id) === a.id; tm.appendChild(o); } tm.addEventListener('change', () => act.setPlan(id, 'target', tm.value)); two3.appendChild(field('Target', tm)); const th = h('input'); th.type = 'text'; th.value = n.threshold || ''; th.placeholder = p.worstP ? 'below ' + Tree.fmtSci(p.worstP) : ''; th.addEventListener('change', () => act.setPlan(id, 'threshold', th.value)); two3.appendChild(field('Threshold', th)); f.appendChild(two3); + const ch = h('textarea'); ch.rows = 2; ch.value = n.change || ''; ch.placeholder = 'What this model changes'; ch.addEventListener('change', () => act.setPlan(id, 'change', ch.value)); f.appendChild(field('Intended change', ch)); + ins.appendChild(f); + const steps = h('ol', 'steps'); + for (const [t, done] of [['Prepared', !!n.prepared], ['Reviewed', false], ['Approved', false], ['Started', false]]) { const li = h('li', done ? 'done' : 'todo'); li.appendChild(stateEl(done ? 'good' : 'neutral', '')); li.appendChild(h('span', 'title', t)); steps.appendChild(li); } + ins.appendChild(steps); + const acts = h('div', 'actions'); + if (!n.prepared) { const b = h('button', 'btn primary', 'Prepare trial'); b.type = 'button'; b.addEventListener('click', () => act.setPlan(id, 'prepared', true)); acts.appendChild(b); } + else { const b = h('button', 'btn primary', 'Open in Train'); b.type = 'button'; b.addEventListener('click', () => act.go('train', id)); acts.appendChild(b); } + const d = h('button', 'btn ghost', 'Discard'); d.type = 'button'; d.addEventListener('click', () => act.discardPlan(id)); acts.appendChild(d); + ins.appendChild(acts); + aside.appendChild(ins); + } + + function inspectorModel(aside, id, act, { compact = false } = {}) { + aside.textContent = ''; + const m = byId.get(id); if (!m) return; + const ins = h('div', 'inspector'); + const hd = h('header'); hd.appendChild(h('span', 'kicker', (m.ck ? m.ck + ' · ' : '') + m.groupLabel)); hd.appendChild(h('h2', null, m.short)); + const meta = h('div', 'ins-meta'); meta.appendChild(h('span', 'chip ' + m.kind, Tree.kindLabel(m.kind))); meta.appendChild(stateEl('good', 'source reviewed')); + if (m.alias && m.alias !== m.ck) meta.appendChild(h('span', 'small faint', m.alias)); hd.appendChild(meta); ins.appendChild(hd); + const lin = h('div', 'actions'); + if (m.parent) { const p = byId.get(m.parent); const b = h('button', 'btn sm ghost'); b.type = 'button'; b.appendChild(icon('branch')); b.appendChild(document.createTextNode(' From ' + (p.ck || p.short))); b.addEventListener('click', () => act.select(p.id)); lin.appendChild(b); } + else lin.appendChild(h('span', 'small faint', 'No recorded ancestry')); + const kids = graph.families.find(f => f.parent === m.id); if (kids) { const b = h('button', 'btn sm ghost', `${kids.children.length} fits branch here`); b.type = 'button'; b.addEventListener('click', () => act.select(kids.children[0])); lin.appendChild(b); } + ins.appendChild(lin); + const dl = h('dl', 'metrics'); + for (const a of ACC) dl.appendChild(cell(a.label, m[a.id] == null ? '—' : Tree.fmtSci(m[a.id]))); + dl.appendChild(cell(TIME.label, m[TIME.id] == null ? '—' : m[TIME.id].toFixed(2), m[TIME.id] == null ? '' : TIME.unit)); + dl.appendChild(cell('Parameters', m.params == null ? '—' : m.params.toLocaleString('en-GB'))); + ins.appendChild(dl); + ins.appendChild(h('p', 'note', MET.population)); + if (!compact) for (const [k, v] of [['Purpose', m.purpose], ['Outcome', m.outcome], ['Lesson', m.lesson]]) { if (!v) continue; const d = h('div'); d.appendChild(h('h3', null, k)); d.appendChild(h('p', null, v + (v.length >= 200 ? '…' : ''))); ins.appendChild(d); } + const cmp = Tree.comparisons(graph, m.id); + if (cmp.length) { const d = h('div'); d.appendChild(h('h3', null, 'Compared with')); const ul = h('ul', 'links'); for (const c of cmp) { const o = byId.get(c.other); const li = h('li'); const b = h('button'); b.type = 'button'; b.appendChild(document.createTextNode((o.ck ? o.ck + ' · ' : '') + o.short)); if (!compact) b.appendChild(h('span', 'why', c.excerpt.slice(0, 140) + (c.excerpt.length > 140 ? '…' : ''))); b.addEventListener('click', () => act.select(o.id)); li.appendChild(b); ul.appendChild(li); } d.appendChild(ul); ins.appendChild(d); } + const ac = h('div', 'actions'); + const b1 = h('button', 'btn primary'); b1.type = 'button'; b1.appendChild(icon('branch')); b1.appendChild(document.createTextNode(' Branch from here')); b1.addEventListener('click', () => act.branch(m.id)); ac.appendChild(b1); + const b2 = h('button', 'btn', 'Benchmark'); b2.type = 'button'; b2.addEventListener('click', () => act.go('benchmarks', m.id)); ac.appendChild(b2); + const b3 = h('button', 'btn ghost', 'Card'); b3.type = 'button'; ac.appendChild(b3); + ins.appendChild(ac); + aside.appendChild(ins); + } + + // ---- Train: planned models, every training run, then the budgeted studies -- + function train(main, aside, state, act) { + main.textContent = ''; aside.textContent = ''; + const sel = state.sel.train, studies = LAB.project.studies, planned = (state.planned || []); + if (planned.length) { + main.appendChild(sect('Planned', String(planned.length))); + const pl = h('ul', 'rows'); + for (const pn of planned) { const m = byId.get(pn.id), p = byId.get(pn.parent); if (!m) continue; const li = h('li'); const b = h('button', 'row study'); b.type = 'button'; b.setAttribute('aria-pressed', String(pn.id === sel)); b.appendChild(stateEl(pn.setup.started ? 'pending' : pn.setup.prepared ? 'pending' : 'neutral', pn.setup.started ? 'running' : pn.setup.prepared ? 'prepared' : 'planned')); const t = h('span'); t.appendChild(h('span', 'title', m.label)); t.appendChild(h('span', 'sub', pn.setup.change || 'not configured')); b.appendChild(t); b.appendChild(h('span', 'sub mono', p ? (p.ck || p.short) : '')); b.appendChild(h('span', 'sub num', 'attempts 0 of ' + (pn.setup.attempts || 2))); b.appendChild(h('span', 'sub num', 'today')); b.addEventListener('click', () => act.select(pn.id)); li.appendChild(b); pl.appendChild(li); } + main.appendChild(pl); + } + const bar = h('div', 'filters'); if (planned.length) bar.style.marginTop = '20px'; + const q = h('input'); q.type = 'search'; q.placeholder = 'Find a run'; q.value = state.query || ''; q.setAttribute('aria-label', 'Find a run'); q.addEventListener('input', () => act.setQuery(q.value)); bar.appendChild(q); + const grp = h('div', 'grp'); for (const k of KINDS) { const b = h('button', 'btn sm chip ' + k, Tree.kindLabel(k)); b.type = 'button'; b.setAttribute('aria-pressed', String(!state.kinds || state.kinds.has(k))); b.addEventListener('click', () => act.toggleKind(k)); grp.appendChild(b); } bar.appendChild(grp); + if (!planned.length) { const hint = h('span', 'pop'); hint.appendChild(document.createTextNode('To train a new model, branch from a fit on the ')); const a = h('a', null, 'map'); a.href = '#models'; hint.appendChild(a); bar.appendChild(hint); } + main.appendChild(bar); + const runs = graph.nodes.filter(m => !m.planned && (!state.kinds || state.kinds.has(m.kind)) && (!state.query || Tree.matches(m, state.query))); + main.appendChild(sect('Runs', `${runs.length} of ${LAB.models.length}`)); + const ul = h('ul', 'rows'); let lastGroup = null; + for (const m of runs) { + if (m.group !== lastGroup) { lastGroup = m.group; const gh = h('li'); const hh = h('div', 'tsect'); hh.style.gridTemplateColumns = '1fr auto'; hh.appendChild(h('h3', null, m.groupLabel)); gh.appendChild(hh); ul.appendChild(gh); } + const st = runStudy(m), li = h('li'); const b = h('button', 'row run'); b.type = 'button'; b.setAttribute('aria-pressed', String(m.id === sel)); + b.appendChild(h('span', 'ck', m.ck || '—')); + const t = h('span'); t.appendChild(h('span', 'title', m.short)); t.appendChild(h('span', 'sub', [m.updates && m.updates.toLocaleString('en-GB') + ' updates', m.lr && 'lr ' + m.lr, m.seed && 'seed ' + m.seed, st && st.label].filter(Boolean).join(' · ') || 'recorded in the card')); b.appendChild(t); + b.appendChild(h('span', 'chip ' + m.kind, Tree.kindLabel(m.kind))); + b.appendChild(h('span', 'sub num', m.loss == null ? '' : 'loss ' + Tree.fmtSci(m.loss))); + b.appendChild(h('span', 'sub', m.device || '')); + b.appendChild(stateEl('good', 'completed')); + b.addEventListener('click', () => act.select(m.id)); li.appendChild(b); ul.appendChild(li); + } + main.appendChild(ul); + const sh = sect('Studies', String(studies.length)); sh.style.marginTop = '28px'; main.appendChild(sh); + const sul = h('ul', 'rows'); + for (const s of studies) { + const li = h('li'); const b = h('button', 'row study'); b.type = 'button'; b.setAttribute('aria-pressed', String(s.id === sel)); + b.appendChild(stateEl(studyState(s), s.state === 'closed' ? 'waiting' : s.state)); + const t = h('span'); t.appendChild(h('span', 'title', s.label)); t.appendChild(h('span', 'sub', s.decision)); b.appendChild(t); + const mm = s.model && byId.get(s.model); b.appendChild(h('span', 'sub mono', mm ? (mm.ck || mm.short) : '')); + b.appendChild(h('span', 'sub num', 'attempts ' + s.attempts)); b.appendChild(h('span', 'sub num', fmtDate(s.updated))); + b.addEventListener('click', () => act.select(s.id)); li.appendChild(b); sul.appendChild(li); + } + main.appendChild(sul); + const pn = planned.find(x => x.id === sel); + if (pn) return inspectorPlannedRun(aside, pn, act); + const run = sel && byId.get(sel); + if (run && !run.planned) return inspectorRun(aside, run, act); + const s = studies.find(x => x.id === sel); + if (!s) { + const used = studies.reduce((a, x) => { const m = /^(\d+) of (\d+)/.exec(x.attempts); if (m) { a[0] += +m[1]; a[1] += +m[2]; } return a; }, [0, 0]); + const ins = h('div', 'inspector'); const dl = h('dl', 'metrics'); + dl.appendChild(cell('Runs', String(LAB.models.length))); dl.appendChild(cell('On CUDA', String(LAB.models.filter(m => m.device === 'CUDA').length))); dl.appendChild(cell('Waiting', String(studies.filter(x => x.state === 'closed').length + planned.filter(x => x.setup.prepared && !x.setup.started).length))); dl.appendChild(cell('Live', String(planned.filter(x => x.setup.started).length))); + ins.appendChild(dl); + const rl = h('div'); rl.appendChild(h('h3', null, 'Recipes')); const rul = h('ul', 'links'); + for (const r of LAB.recipes || []) { const li = h('li'); const sp = h('button'); sp.type = 'button'; sp.appendChild(document.createTextNode(r.label)); sp.appendChild(h('span', 'why', r.path + ' · ' + (runtimeOf(r.runtime) || {}).label + ' · ' + r.kind)); li.appendChild(sp); rul.appendChild(li); } + rl.appendChild(rul); ins.appendChild(rl); + aside.appendChild(ins); return false; + } + return inspectorStudy(aside, s, act); + } + function inspectorRun(aside, m, act) { + const ins = h('div', 'inspector'), st = runStudy(m), p = m.parent && byId.get(m.parent); + const hd = h('header'); hd.appendChild(h('span', 'kicker', (m.ck ? m.ck + ' · ' : '') + m.groupLabel)); hd.appendChild(h('h2', null, m.short)); const meta = h('div', 'ins-meta'); meta.appendChild(h('span', 'chip ' + m.kind, Tree.kindLabel(m.kind))); meta.appendChild(stateEl('good', 'completed')); hd.appendChild(meta); ins.appendChild(hd); + const su = h('dl', 'setup'); const put = (k, node) => { su.appendChild(h('dt', null, k)); const dd = h('dd'); if (typeof node === 'string') dd.textContent = node; else dd.appendChild(node); su.appendChild(dd); }; + if (p) { const b = h('button', 'btn sm ghost', 'From ' + (p.ck || p.short)); b.type = 'button'; b.addEventListener('click', () => act.go('models', p.id)); put('Start', b); } else put('Start', 'no recorded ancestry'); + put('Updates', m.updates ? m.updates.toLocaleString('en-GB') : '—'); put('Learning rate', m.lr ? String(m.lr) : '—'); put('Seed', m.seed ? String(m.seed) : '—'); + put('Device', m.device || '—'); put('Final loss', m.loss == null ? '—' : Tree.fmtSci(m.loss)); put('Parameters', m.params == null ? '—' : m.params.toLocaleString('en-GB')); + if (st) { const b = h('button', 'btn sm ghost', st.label); b.type = 'button'; b.addEventListener('click', () => act.select(st.id)); put('Study', b); } + ins.appendChild(su); + if (m.experiment) { const d = h('div'); d.appendChild(h('h3', null, 'As recorded')); d.appendChild(h('p', null, m.experiment + (m.experiment.length >= 300 ? '…' : ''))); ins.appendChild(d); } + const acts = h('div', 'actions'); const b1 = h('button', 'btn primary'); b1.type = 'button'; b1.appendChild(icon('branch')); b1.appendChild(document.createTextNode(' Branch from here')); b1.addEventListener('click', () => act.branch(m.id)); acts.appendChild(b1); const b2 = h('button', 'btn', 'On the map'); b2.type = 'button'; b2.addEventListener('click', () => act.go('models', m.id)); acts.appendChild(b2); const b3 = h('button', 'btn ghost', 'Benchmark'); b3.type = 'button'; b3.addEventListener('click', () => act.go('benchmarks', m.id)); acts.appendChild(b3); ins.appendChild(acts); + aside.appendChild(ins); return true; + } + function inspectorPlannedRun(aside, pn, act) { + const m = byId.get(pn.id), p = byId.get(pn.parent), n = pn.setup, rc = recipeOf(n.recipe || 'run-study'), rt = runtimeOf(n.runtime || (rc && rc.runtime)), ds = datasetOf(n.data || 'water-capture'); + const ins = h('div', 'inspector'); + const hd = h('header'); hd.appendChild(h('span', 'kicker', 'planned · from ' + (p.ck || p.short))); hd.appendChild(h('h2', null, m.label)); const meta = h('div', 'ins-meta'); meta.appendChild(stateEl(n.started ? 'pending' : n.prepared ? 'pending' : 'neutral', n.started ? 'running' : n.prepared ? 'prepared, waiting for review' : 'not prepared')); hd.appendChild(meta); ins.appendChild(hd); + const su = h('dl', 'setup'); const put = (k, node) => { su.appendChild(h('dt', null, k)); const dd = h('dd'); if (typeof node === 'string') dd.textContent = node; else dd.appendChild(node); su.appendChild(dd); }; + const pb = h('button', 'btn sm ghost', modelName(p)); pb.type = 'button'; pb.addEventListener('click', () => act.go('models', p.id)); put('From', pb); + if (rc) { const sp = h('span'); sp.appendChild(document.createTextNode(rc.label + ' · ')); sp.appendChild(fileLink(rc.path, rc.path)); put('Recipe', sp); } + if (rt) put('Runtime', rt.label); if (ds) put('Data', ds.label); + put('Training', `${(n.updates || p.updates || 1600).toLocaleString('en-GB')} updates · lr ${n.lr || p.lr || '1e-5'}`); + put('Budget', `${n.attempts || 2} attempts · ${n.wall || 90} min wall`); + if (n.change) put('Intended change', n.change); + ins.appendChild(su); + const steps = h('ol', 'steps'); for (const [t, done] of [['Prepared', !!n.prepared], ['Reviewed', !!n.reviewed], ['Approved', !!n.approved], ['Started', !!n.started]]) { const li = h('li', done ? 'done' : 'todo'); li.appendChild(stateEl(done ? 'good' : 'pending', '')); li.appendChild(h('span', 'title', t)); steps.appendChild(li); } ins.appendChild(steps); + const acts = h('div', 'actions'); + if (!n.prepared) { const b = h('button', 'btn primary', 'Configure on the map'); b.type = 'button'; b.addEventListener('click', () => act.go('models', pn.id)); acts.appendChild(b); } + else if (!n.reviewed) { const b = h('button', 'btn primary', 'Review material'); b.type = 'button'; b.addEventListener('click', () => act.setPlan(pn.id, 'reviewed', true)); acts.appendChild(b); } + else if (!n.approved) { const b = h('button', 'btn primary', 'Approve'); b.type = 'button'; b.addEventListener('click', () => act.setPlan(pn.id, 'approved', true)); acts.appendChild(b); const b2 = h('button', 'btn', 'Start training'); b2.type = 'button'; b2.disabled = true; acts.appendChild(b2); } + else if (!n.started) { const b = h('button', 'btn primary', 'Start training'); b.type = 'button'; b.addEventListener('click', () => act.setPlan(pn.id, 'started', true)); acts.appendChild(b); } + else acts.appendChild(stateEl('good', 'running · attempt 1 of ' + (n.attempts || 2))); + const d = h('button', 'btn ghost', 'Discard'); d.type = 'button'; d.addEventListener('click', () => act.discardPlan(pn.id)); acts.appendChild(d); + ins.appendChild(acts); aside.appendChild(ins); return true; + } + function inspectorStudy(aside, s, act) { + const ins = h('div', 'inspector'); + const hd = h('header'); hd.appendChild(h('span', 'kicker', 'study · ' + s.id)); hd.appendChild(h('h2', null, s.label)); const meta = h('div', 'ins-meta'); meta.appendChild(stateEl(studyState(s), s.state === 'closed' ? 'waiting for approval' : s.state + ' · ' + s.decision)); hd.appendChild(meta); ins.appendChild(hd); + const mm = s.model && byId.get(s.model), rc = recipeOf(s.recipe), rt = runtimeOf(s.runtime), ds = datasetOf(s.data); + const su = h('dl', 'setup'); const put = (k, node) => { su.appendChild(h('dt', null, k)); const dd = h('dd'); if (typeof node === 'string') dd.textContent = node; else dd.appendChild(node); su.appendChild(dd); }; + if (mm) { const b = h('button', 'btn sm ghost', modelName(mm)); b.type = 'button'; b.addEventListener('click', () => act.go('models', mm.id)); put('Baseline', b); } + if (rc) { const sp = h('span'); sp.appendChild(document.createTextNode(rc.label + ' · ')); sp.appendChild(fileLink(rc.path, rc.path)); if (rc.config) { sp.appendChild(document.createTextNode(' · ')); sp.appendChild(fileLink(rc.config, rc.config)); } put('Recipe', sp); } + if (rt) put('Runtime', rt.label); + if (ds) { const b = h('button', 'btn sm ghost', ds.label); b.type = 'button'; b.addEventListener('click', () => act.go('data', ds.id)); put('Data', b); } + put('Budget', `${s.attempts} attempts · ${s.wall || '—'} wall`); + if (s.change) put('Intended change', s.change); + ins.appendChild(su); + const trials = (LAB.project.trials || {})[s.id] || Array.from({ length: s.trials }, (_, i) => ({ id: 't' + (i + 1), label: 'trial ' + (i + 1), state: s.state === 'completed' ? 'completed' : 'prepared' })); + if (trials.length) { const d = h('div'); d.appendChild(h('h3', null, 'Runs in this study')); const tl = h('ul', 'trials'); for (const t of trials) { const li = h('li'); li.appendChild(stateEl(t.state === 'completed' ? 'good' : t.state === 'failed' ? 'serious' : 'pending', '')); li.appendChild(h('span', null, t.label + ' · ' + t.state)); const r = t.run && LAB.models.find(m => m.ck === t.run); if (r) { const b = h('button', 'btn sm ghost', r.ck); b.type = 'button'; b.addEventListener('click', () => act.select(r.id)); li.appendChild(b); } else li.appendChild(h('span')); tl.appendChild(li); } d.appendChild(tl); ins.appendChild(d); } + const pending = s.state === 'closed'; + const steps = h('ol', 'steps'); for (const [t, done] of [['Prepared', true], ['Reviewed', true], ['Approved', !pending], ['Started', !pending]]) { const li = h('li', done ? 'done' : 'todo'); li.appendChild(stateEl(done ? 'good' : 'pending', '')); li.appendChild(h('span', 'title', t)); steps.appendChild(li); } ins.appendChild(steps); + const acts = h('div', 'actions'); + if (pending) { const b = h('button', 'btn primary', 'Approve'); b.type = 'button'; acts.appendChild(b); const b2 = h('button', 'btn', 'Start training'); b2.type = 'button'; b2.disabled = true; b2.title = 'Approve first'; acts.appendChild(b2); } + else if (mm) { const b = h('button', 'btn primary'); b.type = 'button'; b.appendChild(icon('branch')); b.appendChild(document.createTextNode(' Branch from ' + (mm.ck || mm.short))); b.addEventListener('click', () => act.branch(mm.id)); acts.appendChild(b); const b2 = h('button', 'btn ghost', 'Results'); b2.type = 'button'; b2.addEventListener('click', () => act.go('benchmarks', s.model)); acts.appendChild(b2); } + ins.appendChild(acts); + const docs = docsOf(s.label); if (docs.length) { const dd = h('div'); dd.appendChild(h('h3', null, 'Documents')); dd.appendChild(docChips(s.label, null, id => act.go('analysis', id))); ins.appendChild(dd); } + aside.appendChild(ins); return true; + } + + // ---- Benchmarks ---------------------------------------------------------- + function benchmarks(main, aside, state, act) { + main.textContent = ''; aside.textContent = ''; + const sel = state.sel.benchmarks, metric = state.metric || ACC[0].id, pop = popOf(state), cmp = state.cmp || new Set(); + const popModels = LAB.models.filter(m => inPop(m, pop)); + const bar = h('div', 'filters'); + const ps = h('select'); ps.setAttribute('aria-label', 'Population'); for (const pp of MET.populations || []) { const o = h('option', null, pp.label); o.value = pp.id; o.selected = pp.id === pop.id; ps.appendChild(o); } ps.addEventListener('change', () => act.setPop(ps.value)); bar.appendChild(ps); + const grp = h('div', 'grp'); grp.setAttribute('role', 'group'); grp.setAttribute('aria-label', 'Kind of change'); + for (const k of KINDS) { const b = h('button', 'btn sm chip ' + k, Tree.kindLabel(k)); b.type = 'button'; b.setAttribute('aria-pressed', String(!state.kinds || state.kinds.has(k))); b.addEventListener('click', () => act.toggleKind(k)); grp.appendChild(b); } + bar.appendChild(grp); + const ms = h('select'); ms.setAttribute('aria-label', 'Metric'); for (const a of ACC) { const o = h('option', null, a.label); o.value = a.id; o.selected = metric === a.id; ms.appendChild(o); } ms.addEventListener('change', () => act.setMetric(ms.value)); bar.appendChild(ms); + const fb = h('button', 'btn sm', 'Frontier only'); fb.type = 'button'; fb.setAttribute('aria-pressed', String(!!state.frontierOnly)); fb.addEventListener('click', () => act.toggleFrontier()); bar.appendChild(fb); + const bo = h('button', 'btn sm', 'Benchmarked only'); bo.type = 'button'; bo.setAttribute('aria-pressed', String(!!state.benchOnly)); bo.addEventListener('click', () => act.setUI('benchOnly', !state.ui.benchOnly)); bar.appendChild(bo); + const q = h('input'); q.type = 'search'; q.placeholder = 'Find a fit'; q.value = state.query || ''; q.setAttribute('aria-label', 'Find a fit'); q.addEventListener('input', () => act.setQuery(q.value)); bar.appendChild(q); + main.appendChild(bar); + { const both = popModels.filter(m => benchState(m) === 'accuracy and time').length, ao = popModels.filter(m => benchState(m) === 'accuracy only').length, to = popModels.filter(m => benchState(m) === 'time only').length, none = popModels.filter(m => benchState(m) === 'none retained').length, gb = popModels.filter(m => benchState(m) === 'generator benchmark').length; + const cov = h('div', 'coverage'); const add = (n, t) => { const sp = h('span'); sp.appendChild(h('b', null, String(n))); sp.appendChild(document.createTextNode(' ' + t)); cov.appendChild(sp); }; + add(popModels.length, 'fits'); if (gb) add(gb, 'with the generator benchmark'); if (both) add(both, 'with accuracy and time'); if (ao) add(ao, 'accuracy only'); if (to) add(to, 'time only'); if (none) add(none, 'no retained benchmark'); main.appendChild(cov); } + + const s1 = h('section'); const h1 = sect('Accuracy against time'); s1.appendChild(h1); const c1 = h('div'); s1.appendChild(c1); main.appendChild(s1); + const xMax = Math.max(10, ...popModels.filter(m => m[TIME.id] != null).map(m => Math.ceil(m[TIME.id]))); + const r = Charts.pareto(c1, popModels, { selected: sel, onSelect: id => act.select(id), kinds: state.kinds, frontierOnly: state.frontierOnly, metric, yLabel: accLabel(metric), xLabel: TIME.axis, unit: TIME.unit, xMax: pop.only ? xMax : 10 }); + h1.appendChild(h('span', 'sum', `${r.count} of ${r.total} · ${r.frontier.length} on the frontier · ${pop.note || ''}`)); + if (!pop.only) { const s2 = h('section'); s2.style.marginTop = '28px'; s2.appendChild(sect('Along the checkpoint sequence', accLabel(ACC[0].id))); const c2 = h('div'); s2.appendChild(c2); main.appendChild(s2); Charts.curve(c2, LAB.models, { selected: sel, onSelect: id => act.select(id), metric: ACC[0].id, sections: CURVE_SECTIONS, yLabel: accLabel(ACC[0].id), secondary: ACC[1] || null }); } + + if (cmp.size) { + const sc = h('section'); sc.style.marginTop = '28px'; const hc = sect('Compare', `${cmp.size} of 3`); sc.appendChild(hc); + const chips = h('div', 'cmp-chips'); const list = [...cmp].map(id => byId.get(id)).filter(Boolean); + list.forEach((m, i) => { const c = h('span', 'c s' + (i + 1)); c.appendChild(h('i')); c.appendChild(document.createTextNode(modelName(m))); const x = h('button', null, '×'); x.type = 'button'; x.setAttribute('aria-label', 'Remove ' + modelName(m)); x.addEventListener('click', () => act.toggleCompare(m.id)); c.appendChild(x); chips.appendChild(c); }); + const clr = h('button', 'btn sm ghost', 'Clear'); clr.type = 'button'; clr.addEventListener('click', () => act.clearCompare()); chips.appendChild(clr); sc.appendChild(chips); + const tb = h('table', 'tv cmpt'); tb.style.marginTop = '12px'; const thead = h('thead'); const tr = h('tr'); tr.appendChild(h('th', null, '')); list.forEach(m => tr.appendChild(h('th', 'n', modelName(m)))); thead.appendChild(tr); tb.appendChild(thead); + const tbody = h('tbody'); const base = list[0]; + const rowsDef = [...ACC.map(a => [a.label, a.id, 'lower']), [TIME.label + ' (' + TIME.unit + ')', TIME.id, 'lower'], ['Parameters', 'params', null], ['Updates', 'updates', null], ['Learning rate', 'lr', null]]; + for (const [label, key, better] of rowsDef) { const row = h('tr'); row.appendChild(h('td', null, label)); list.forEach((m, i) => { const v = m[key]; const td = h('td', 'n'); td.textContent = v == null ? '—' : (key === 'params' || key === 'updates') ? v.toLocaleString('en-GB') : key === 'lr' ? String(v) : key === TIME.id ? v.toFixed(2) : Tree.fmtSci(v); if (i > 0 && better && v != null && base[key] != null) { const d = (v - base[key]) / base[key]; const sp = h('span', 'd ' + (d < 0 ? 'better' : d > 0 ? 'worse' : ''), ' ' + (d > 0 ? '+' : '') + (d * 100).toFixed(1) + '%'); td.appendChild(sp); } row.appendChild(td); }); tbody.appendChild(row); } + tb.appendChild(tbody); sc.appendChild(tb); + const cc = h('div'); cc.style.marginTop = '14px'; sc.appendChild(cc); + Charts.lines(cc, list.map((m, i) => ({ id: m.id, label: modelName(m), slot: i + 1, points: curveFor(m) })), { yLabel: 'Training loss', xLabel: 'updates', logY: true }); + main.appendChild(sc); + } + + const st = h('section'); st.style.marginTop = '28px'; + const vis = popModels.filter(m => (!state.kinds || state.kinds.has(m.kind)) && (!state.query || Tree.matches(m, state.query)) && (!state.ui.benchOnly || benchState(m) === 'accuracy and time' || benchState(m) === 'generator benchmark')); + const sort = state.sort || { key: 'n', dir: 1 }; + const cols = [['', 'cmp'], ['', 'ck'], ['Fit', 'short'], ['Kind', 'kind'], ['Group', 'groupLabel'], ...ACC.map(a => [a.label, a.id]), [TIME.label, TIME.id], ['Parameters', 'params'], ['Benchmark', 'bench']]; + vis.sort((a, b) => { const ka = a[sort.key], kb = b[sort.key]; if (ka == null && kb == null) return 0; if (ka == null) return 1; if (kb == null) return -1; return (typeof ka === 'number' ? ka - kb : String(ka).localeCompare(String(kb))) * sort.dir; }); + st.appendChild(sect('All fits', `${vis.length} of ${popModels.length}`)); + const tb = h('table', 'tv'); const thead = h('thead'); const tr = h('tr'); + for (const [label, key] of cols) { const th = h('th', ['ck', 'short', 'kind', 'groupLabel', 'cmp', 'bench'].includes(key) ? '' : 'n'); if (label && key !== 'bench') { const b = h('button', null, label); b.type = 'button'; if (sort.key === key) b.setAttribute('aria-sort', sort.dir > 0 ? 'ascending' : 'descending'); b.addEventListener('click', () => act.setSort(key)); th.appendChild(b); } else th.textContent = label; tr.appendChild(th); } + thead.appendChild(tr); tb.appendChild(thead); + const tbody = h('tbody'); + for (const m of vis) { + const row = h('tr', 'rowbtn' + (m.id === sel ? ' is-sel' : '')); row.addEventListener('click', () => act.select(m.id)); + const tdc = h('td'); const cb = h('input'); cb.type = 'checkbox'; cb.checked = cmp.has(m.id); cb.disabled = !cmp.has(m.id) && cmp.size >= 3; cb.setAttribute('aria-label', 'Compare ' + modelName(m)); cb.addEventListener('click', ev => { ev.stopPropagation(); act.toggleCompare(m.id); }); tdc.appendChild(cb); row.appendChild(tdc); + row.appendChild(h('td', 'ck', m.ck || '')); row.appendChild(h('td', null, m.short)); const kt = h('td'); kt.appendChild(h('span', 'chip ' + m.kind, Tree.kindLabel(m.kind))); row.appendChild(kt); row.appendChild(h('td', 'small faint nowrap', m.groupLabel.replace(/^C\d+[–-]C\d+\s*·\s*/, ''))); + for (const a of ACC) row.appendChild(h('td', 'n', m[a.id] == null ? '' : Tree.fmtSci(m[a.id]))); + row.appendChild(h('td', 'n', m[TIME.id] == null ? '' : m[TIME.id].toFixed(2))); row.appendChild(h('td', 'n', m.params == null ? '' : m.params.toLocaleString('en-GB'))); row.appendChild(h('td', 'small faint nowrap', benchState(m))); + tbody.appendChild(row); + } + tb.appendChild(tbody); st.appendChild(tb); main.appendChild(st); + + const decisions = LAB.project.decisions || []; + if (decisions.length) { + const sd = h('section'); sd.style.marginTop = '28px'; sd.appendChild(sect('Study results', String(decisions.length))); + const dt = h('table', 'tv'); const dh = h('thead'); const dtr = h('tr'); for (const [t, c] of [['Study', ''], ['Decision', ''], ['Reference', 'n'], ['Candidate', 'n'], ['Change', 'n']]) dtr.appendChild(h('th', c, t)); dh.appendChild(dtr); dt.appendChild(dh); + const db = h('tbody'); for (const d of decisions) { const row = h('tr', 'rowbtn'); const stu = LAB.project.studies.find(x => x.label === d.plan); if (stu) row.addEventListener('click', () => act.go('train', stu.id)); row.appendChild(h('td', null, d.plan)); const td = h('td'); td.appendChild(stateEl(d.decision.includes('failed') ? 'serious' : d.decision.includes('pass') ? 'good' : 'neutral', d.decision)); if (d.note) td.appendChild(h('span', 'small faint', ' · ' + d.note)); row.appendChild(td); const isAcc = ACC.some(a => a.id === d.metric); row.appendChild(h('td', 'n', d.ref == null ? '—' : isAcc ? Tree.fmtSci(d.ref) : String(d.ref))); row.appendChild(h('td', 'n', d.cand == null ? '—' : isAcc ? Tree.fmtSci(d.cand) : String(d.cand))); const ch = h('td', 'n'); if (d.ref != null && d.cand != null && isAcc) { const dd = (d.cand - d.ref) / d.ref; ch.appendChild(h('span', 'd ' + (dd < 0 ? 'better' : 'worse'), (dd > 0 ? '+' : '') + (Math.abs(dd) > 9 ? (dd * 100).toFixed(0) : (dd * 100).toFixed(1)) + '%')); } row.appendChild(ch); db.appendChild(row); } + dt.appendChild(db); sd.appendChild(dt); main.appendChild(sd); + } + + if (sel) { inspectorModel(aside, sel, act, { compact: true }); const bs = benchState(byId.get(sel)); if (bs === 'none retained' || bs === 'accuracy only' || bs === 'time only') { const ev = (LAB.recipes || []).find(r => r.kind === 'evaluation'); const nb = h('p', 'note', 'No comparable benchmark retained for this fit' + (bs === 'none retained' ? '' : ' (' + bs + ')') + '.'); aside.querySelector('.inspector').insertBefore(nb, aside.querySelector('.actions')); if (ev) { const rb = h('button', 'btn', 'Run ' + ev.label.toLowerCase()); rb.type = 'button'; rb.title = ev.path; aside.querySelector('.actions').appendChild(rb); } } const acts = aside.querySelector('.actions:last-child'); const b = h('button', 'btn', cmp.has(sel) ? 'Remove from compare' : 'Compare'); b.type = 'button'; b.disabled = !cmp.has(sel) && cmp.size >= 3; b.addEventListener('click', () => act.toggleCompare(sel)); acts.insertBefore(b, acts.firstChild); const b2 = h('button', 'btn ghost', 'In Models'); b2.type = 'button'; b2.addEventListener('click', () => act.go('models', sel)); acts.appendChild(b2); return true; } + const ins = h('div', 'inspector'); const hd = h('header'); hd.appendChild(h('h2', null, 'Frontier')); hd.appendChild(h('span', 'small muted', 'fastest first')); ins.appendChild(hd); + const ul = h('ul', 'links'); + for (const m of r.frontier) { const li = h('li'); const b = h('button'); b.type = 'button'; b.appendChild(document.createTextNode(modelName(m))); b.appendChild(h('span', 'why', `${Tree.fmtSci(m[metric])} · ${m[TIME.id].toFixed(2)} ${TIME.unit} · ${Tree.kindLabel(m.kind).toLowerCase()}`)); b.addEventListener('click', () => act.select(m.id)); li.appendChild(b); ul.appendChild(li); } + ins.appendChild(ul); aside.appendChild(ins); + return false; + } + + // ---- Analysis: field comparison per case, and the reports ----------------- + function drawField(canvas, fn) { + const ctx = canvas.getContext('2d'), W = canvas.width = 240, Hh = canvas.height = 240, n = 32; + const dark = getComputedStyle(document.documentElement).colorScheme === 'dark'; + const mid = dark ? [56, 56, 53] : [240, 239, 236], neg = dark ? [79, 138, 224] : [46, 111, 207], pos = dark ? [217, 111, 60] : [210, 101, 47]; + for (let j = 0; j < n; j++) for (let i = 0; i < n; i++) { const val = fn(i / n, j / n); const c = val < 0 ? neg : pos, t = Math.min(1, Math.abs(val)); const rgb = mid.map((m, k) => Math.round(m + (c[k] - m) * t)); ctx.fillStyle = `rgb(${rgb[0]},${rgb[1]},${rgb[2]})`; ctx.fillRect(i * W / n, j * Hh / n, W / n + 1, Hh / n + 1); } + } + const caseErr = (m, c) => { const rnd = seeded(m.id + ':' + c); const base = m.worstP || 0.01; return base * (0.35 + 0.65 * Math.pow(rnd(), 2.2)); }; + function analysis(main, aside, state, act) { + main.textContent = ''; aside.textContent = ''; + const sel = state.sel.analysis, cases = LAB.cases || { count: 0 }, ds = datasetOf(cases.dataset); + const cands = LAB.models.filter(m => m.worstP != null && m.group !== MET.excludedGroup); + const fit = byId.get(state.fit) || byId.get('fit-9a6432c54d9f9434') || cands[0]; + const cn = state.caseN || 1, z = state.slice || Math.round((cases.slices || 16) / 2); + const vs = h('section'); vs.appendChild(sect('Field comparison', ds ? ds.label : '')); + const vb = h('div', 'viewer-bar'); + const fsel = h('select'); fsel.setAttribute('aria-label', 'Fit'); for (const m of cands) { const o = h('option', null, modelName(m)); o.value = m.id; o.selected = m.id === fit.id; fsel.appendChild(o); } fsel.addEventListener('change', () => act.setFit(fsel.value)); vb.appendChild(fsel); + const cl = h('label'); cl.appendChild(document.createTextNode('Case')); const ci = h('input'); ci.type = 'number'; ci.min = 1; ci.max = cases.count; ci.value = cn; ci.style.width = '64px'; ci.addEventListener('change', () => act.setCase(+ci.value)); cl.appendChild(ci); cl.appendChild(document.createTextNode('of ' + cases.count)); vb.appendChild(cl); + const zl = h('label'); zl.appendChild(document.createTextNode('Slice z')); const zi = h('input'); zi.type = 'range'; zi.min = 1; zi.max = cases.slices || 16; zi.value = z; zi.addEventListener('change', () => act.setSlice(+zi.value)); zl.appendChild(zi); zl.appendChild(h('span', 'num', String(z))); vb.appendChild(zl); + const fl = h('label'); fl.appendChild(document.createTextNode('Field')); const fs = h('select'); for (const f of cases.fields || ['pressure']) fs.appendChild(h('option', null, f)); fl.appendChild(fs); vb.appendChild(fl); + vs.appendChild(vb); + const tri = h('div', 'tri'); const err = caseErr(fit, cn), eqv = fit.eq ? fit.eq * (err / (fit.worstP || err)) : null; + const seed = cn * 0.37 + z * 0.11; + const native = (u, v) => Math.sin(6.3 * u + seed) * Math.cos(4.7 * v - seed * 0.5) * 0.7 + Math.sin(12 * u * v + seed) * 0.3; + const amp = Math.min(0.9, Math.sqrt(err) * 6), pred = (u, v) => native(u, v) + amp * 0.5 * Math.sin(17 * u + 3 * seed) * Math.cos(13 * v + seed); + const canvases = []; + for (const [title, fn, cap] of [['Native', native, 'reference solve'], ['Predicted', pred, modelName(fit)], ['Signed error', (u, v) => (pred(u, v) - native(u, v)) / Math.max(amp, 0.05), 'rel. L2 ' + Tree.fmtSci(err)]]) { const fg = h('figure'); const cv = h('canvas'); cv.setAttribute('role', 'img'); cv.setAttribute('aria-label', title + ' field, case ' + cn + ', slice ' + z); fg.appendChild(cv); drawField(cv, fn); const fc = h('figcaption'); fc.appendChild(h('b', null, title)); fc.appendChild(h('span', null, cap)); fg.appendChild(fc); tri.appendChild(fg); canvases.push([cv, title]); } + const redraw = zz => { const sd = cn * 0.37 + zz * 0.11; const nat = (u, v) => Math.sin(6.3 * u + sd) * Math.cos(4.7 * v - sd * 0.5) * 0.7 + Math.sin(12 * u * v + sd) * 0.3, pr = (u, v) => nat(u, v) + amp * 0.5 * Math.sin(17 * u + 3 * sd) * Math.cos(13 * v + sd); drawField(canvases[0][0], nat); drawField(canvases[1][0], pr); drawField(canvases[2][0], (u, v) => (pr(u, v) - nat(u, v)) / Math.max(amp, 0.05)); }; + zi.addEventListener('input', () => { redraw(+zi.value); zl.querySelector('.num').textContent = zi.value; }); + vs.appendChild(tri); + const sc = h('div', 'scale'); sc.appendChild(document.createTextNode('−')); sc.appendChild(h('i')); sc.appendChild(document.createTextNode('+ · case ' + cn + ' · z ' + z + ' · ' + accLabel(ACC[0].id) + ' ' + Tree.fmtSci(err) + (eqv ? ' · ' + accLabel(ACC[1].id) + ' ' + Tree.fmtSci(eqv) : ''))); vs.appendChild(sc); + const pc = h('div', 'cases'); const ph = sect('Per case', accLabel(ACC[0].id) + ' · ' + modelName(fit)); ph.style.marginTop = '16px'; pc.appendChild(ph); + const Wc = 760, Hc = 64, errs = Array.from({ length: cases.count }, (_, i) => caseErr(fit, i + 1)), emax = Math.max(...errs); + const svg = document.createElementNS(svgNS, 'svg'); svg.setAttribute('viewBox', `0 0 ${Wc} ${Hc}`); svg.setAttribute('role', 'img'); svg.setAttribute('aria-label', 'Error per case; the selected case is highlighted'); + const bw = Math.max(2, Wc / cases.count - 2); + errs.forEach((e, i) => { const rect = document.createElementNS(svgNS, 'rect'); rect.setAttribute('x', i * Wc / cases.count); rect.setAttribute('y', Hc - 8 - (e / emax) * (Hc - 12)); rect.setAttribute('width', bw); rect.setAttribute('height', (e / emax) * (Hc - 12)); rect.setAttribute('rx', 1.5); rect.setAttribute('class', 'b' + (i + 1 === cn ? ' sel' : '')); const t = document.createElementNS(svgNS, 'title'); t.textContent = 'case ' + (i + 1) + ' · ' + Tree.fmtSci(e); rect.appendChild(t); rect.addEventListener('click', () => act.setCase(i + 1)); svg.appendChild(rect); }); + const base = document.createElementNS(svgNS, 'line'); base.setAttribute('x1', 0); base.setAttribute('x2', Wc); base.setAttribute('y1', Hc - 8); base.setAttribute('y2', Hc - 8); base.setAttribute('class', 'base'); svg.appendChild(base); + pc.appendChild(svg); vs.appendChild(pc); main.appendChild(vs); + + const rp = h('section'); rp.style.marginTop = '28px'; const plans = LAB.project.evidence.map(g => g.plan); rp.appendChild(sect('Reports', String(plans.length))); + const tb = h('table', 'tv'); const thead = h('thead'); const tr = h('tr'); for (const t of ['Plan', 'Outcome', 'Documents']) tr.appendChild(h('th', null, t)); thead.appendChild(tr); tb.appendChild(thead); + const tbody = h('tbody'); + for (const plan of plans) { const stu = LAB.project.studies.find(x => x.label === plan); const row = h('tr'); row.appendChild(h('td', null, plan)); const od = h('td'); if (stu) od.appendChild(stateEl(studyState(stu), stu.decision)); else od.appendChild(h('span', 'faint', '—')); row.appendChild(od); const dd = h('td'); dd.appendChild(docChips(plan, sel, id => act.select(id))); row.appendChild(dd); tbody.appendChild(row); } + tb.appendChild(tbody); rp.appendChild(tb); main.appendChild(rp); + + const ins = h('div', 'inspector'); + if (sel) { + const item = LAB.project.evidence.flatMap(g => g.items.map(i => [g.plan, ...i])).find(x => x[1] === sel); + const hd = h('header'); hd.appendChild(h('span', 'kicker', item ? item[0] : sel)); hd.appendChild(h('h2', null, item ? (DOC_ROLE(item[3]) || item[2]) : sel)); ins.appendChild(hd); + if (item) { const pa = h('p', 'note'); pa.appendChild(fileLink(item[3], item[3])); ins.appendChild(pa); } + ins.appendChild(h('pre', 'evtext', item ? `(text of ${item[3].split('/').pop()}, first 64 KiB)\n\nsha256: measured on open` : '')); + aside.appendChild(ins); return true; + } + const hd = h('header'); hd.appendChild(h('span', 'kicker', 'case ' + cn)); hd.appendChild(h('h2', null, modelName(fit))); ins.appendChild(hd); + const dl = h('dl', 'metrics'); dl.appendChild(cell(accLabel(ACC[0].id), Tree.fmtSci(err))); if (eqv) dl.appendChild(cell(accLabel(ACC[1].id), Tree.fmtSci(eqv))); dl.appendChild(cell('Worst of ' + cases.count, Tree.fmtSci(Math.max(...errs)))); dl.appendChild(cell('Median', Tree.fmtSci(errs.slice().sort((a, b) => a - b)[Math.floor(errs.length / 2)]))); ins.appendChild(dl); + const acts = h('div', 'actions'); const b1 = h('button', 'btn', 'Open fit'); b1.type = 'button'; b1.addEventListener('click', () => act.go('models', fit.id)); acts.appendChild(b1); const b2 = h('button', 'btn ghost', 'Benchmark'); b2.type = 'button'; b2.addEventListener('click', () => act.go('benchmarks', fit.id)); acts.appendChild(b2); ins.appendChild(acts); + if (ds) { const pa = h('p', 'note'); pa.appendChild(fileLink(ds.path, ds.path)); ins.appendChild(pa); } + aside.appendChild(ins); return false; + } + + // ---- Layout switcher: the three pages are proposals for the same screen. + const LAYOUTS = [['a-stages.html', 'A', 'Stages'], ['b-map.html', 'B', 'Map'], ['c-ledger.html', 'C', 'Ledger']]; + function layoutSwitch(container, current) { + const nav = h('nav', 'layouts'); nav.setAttribute('aria-label', 'Layout proposal'); nav.appendChild(h('span', 'lbl', 'Layout')); + const links = LAYOUTS.map(([file, k, label]) => { const a = h('a'); a.href = file; a.textContent = k + ' ' + label; if (file === current) a.setAttribute('aria-current', 'page'); nav.appendChild(a); return [a, file]; }); + const cmp = h('a', 'cmp', 'All three'); cmp.href = 'index.html'; nav.appendChild(cmp); + const update = () => { const r = (window.mockRoute && window.mockRoute()) || {}; const screen = r.screen || 'overview'; for (const [a, file] of links) a.href = file + (file === 'c-ledger.html' ? '#s-' + screen : '#' + screen + (r.id ? '/' + encodeURIComponent(r.id) : '')); }; + container.textContent = ''; container.appendChild(nav); update(); window.addEventListener('hashchange', update); return { update }; + } + + // ---- Theme toggle -------------------------------------------------------- + const theme = { + init(btn) { + let cur = 'auto'; try { cur = localStorage.getItem('tuldok-mock-theme') || 'auto'; } catch (e) {} + const q = new URLSearchParams(location.search).get('theme'); if (q === 'light' || q === 'dark') cur = q; + const apply = () => { if (cur === 'auto') document.documentElement.removeAttribute('data-theme'); else document.documentElement.setAttribute('data-theme', cur); btn.textContent = ''; btn.appendChild(icon('theme')); btn.appendChild(document.createTextNode(' ' + { auto: 'System', light: 'Light', dark: 'Dark' }[cur])); btn.setAttribute('aria-label', 'Theme: ' + cur); }; + btn.addEventListener('click', () => { cur = { auto: 'light', light: 'dark', dark: 'auto' }[cur]; try { localStorage.setItem('tuldok-mock-theme', cur); } catch (e) {} apply(); }); + apply(); + } + }; + window.addEventListener('error', e => { const b = document.createElement('div'); b.setAttribute('role', 'alert'); b.style.cssText = 'position:fixed;left:8px;bottom:8px;z-index:99;padding:8px 12px;background:#fff;border:2px solid #b7452b;color:#1b2330;font:13px monospace;max-width:80vw'; b.textContent = 'Mockup script error: ' + e.message + ' (' + (e.filename || '').split('/').pop() + ':' + e.lineno + ')'; document.body.appendChild(b); }); + + return { overview, data, annotate, models, train, benchmarks, analysis, inspectorModel, setPlanned, statusLine, stageSummaries, icon, stateEl, theme, layoutSwitch, graph, KINDS, kindLabel: Tree.kindLabel }; +})(); diff --git a/docs/plans/project-workspace-redesign/mockups/shared/tree.js b/docs/plans/project-workspace-redesign/mockups/shared/tree.js new file mode 100644 index 00000000..d052ae7b --- /dev/null +++ b/docs/plans/project-workspace-redesign/mockups/shared/tree.js @@ -0,0 +1,223 @@ +'use strict'; +// Model lineage: one graph built from the portfolio plus any planned models, +// rendered as a vertical list (git-graph style) or a horizontal lane map. +// Solid lanes are derivations read from the model cards; the faint line is +// checkpoint order only; dashed edges are authored comparisons for the +// selected fit. Both renderers return select() and scrollTo() so a selection +// change never rebuilds the view. +window.LabTree = (() => { + const GROUP_ORDER = ['pressure-inputs','pressure-stability','pressure-multigrid','pressure-direction','pressure-variants','pressure-successors','pressure-other','full_state_generator','pressure_head_component','pressure_component','pressure_request_component','guided_pressure_component','guided_shared_component','full_state_correction_component','full_state_readout_component','recurrent_transport_component','transport_component','viscosity_component']; + const gi = id => { const i = GROUP_ORDER.indexOf(id); return i < 0 ? 99 : i; }; + const svgNS = 'http://www.w3.org/2000/svg'; + const el = (name, attrs = {}, text) => { const n = document.createElementNS(svgNS, name); for (const k in attrs) n.setAttribute(k, attrs[k]); if (text !== undefined) n.textContent = text; return n; }; + const h = (tag, cls, text) => { const n = document.createElement(tag); if (cls) n.className = cls; if (text !== undefined) n.textContent = text; return n; }; + const reduced = () => window.matchMedia && window.matchMedia('(prefers-reduced-motion: reduce)').matches; + // A short run of highlights from the previous selection to the new one, so + // the eye can follow the change. Never longer than ~450 ms; skipped when the + // viewer prefers reduced motion. + function walker() { + let timers = []; + return (ordered, fromId, toId, mark) => { + for (const t of timers) clearTimeout(t); timers = []; + if (reduced() || !fromId || !toId || fromId === toId) return; + const i0 = ordered.indexOf(fromId), i1 = ordered.indexOf(toId); if (i0 < 0 || i1 < 0) return; + let steps = i1 > i0 ? ordered.slice(i0 + 1, i1) : ordered.slice(i1 + 1, i0).reverse(); + if (steps.length > 22) { const out = []; for (let k = 0; k < 22; k++) out.push(steps[Math.round(k * (steps.length - 1) / 21)]); steps = out; } + const delay = Math.min(34, 420 / Math.max(1, steps.length)); + steps.forEach((id, k) => { timers.push(setTimeout(() => { mark(id, true); timers.push(setTimeout(() => mark(id, false), 170)); }, k * delay)); }); + }; + } + + function build(models, relationships) { + const nodes = models.map(m => Object.assign({}, m)).sort((a, b) => gi(a.group) - gi(b.group) || ((a.n ?? 9999) - (b.n ?? 9999)) || a.label.localeCompare(b.label)); + nodes.forEach((m, i) => { m.t = i; }); + const byId = new Map(nodes.map(m => [m.id, m])); + const families = new Map(); const laneLast = [0]; + for (const m of nodes) { + const p = m.parents.find(id => byId.has(id)); + m.parent = p || null; + if (!p) { m.lane = 0; continue; } + if (!families.has(p)) { + let lane = 1; const pt = byId.get(p).t; + while (laneLast[lane] !== undefined && laneLast[lane] >= pt) lane++; + families.set(p, { lane, parent: p, children: [], start: pt, end: pt }); + } + const f = families.get(p); m.lane = f.lane; f.children.push(m.id); f.end = m.t; laneLast[f.lane] = m.t; + } + const edges = []; let prev = null; + for (const m of nodes) { + if (m.lane !== 0) continue; + if (prev && ((prev.n != null && m.n != null) || prev.group === m.group)) edges.push({ from: prev.id, to: m.id, kind: 'sequence' }); + prev = m; + } + for (const m of nodes) if (m.parent) edges.push({ from: m.parent, to: m.id, kind: 'derivation' }); + for (const r of relationships) if (byId.has(r.from) && byId.has(r.to)) edges.push({ from: r.from, to: r.to, kind: 'comparison', explanation: r.explanation, excerpt: r.excerpt }); + const sections = []; + for (const m of nodes) { const s = sections[sections.length - 1]; if (!s || s.group !== m.group) sections.push({ group: m.group, label: m.groupLabel, start: m.t, end: m.t, count: 1 }); else { s.end = m.t; s.count++; } } + const seqSpan = new Array(nodes.length).fill(false); + for (const e of edges) if (e.kind === 'sequence') for (let t = byId.get(e.from).t + 1; t < byId.get(e.to).t; t++) seqSpan[t] = true; + const seqIn = new Set(edges.filter(e => e.kind === 'sequence').map(e => e.to)); + const seqOut = new Set(edges.filter(e => e.kind === 'sequence').map(e => e.from)); + return { nodes, byId, edges, sections, families: [...families.values()], laneCount: laneLast.length, seqIn, seqOut, seqSpan }; + } + function related(graph, id) { const out = new Set(); for (const e of graph.edges) if (e.kind !== 'sequence' && (e.from === id || e.to === id)) out.add(e.from === id ? e.to : e.from); return out; } + function comparisons(graph, id) { return graph.edges.filter(e => e.kind === 'comparison' && (e.from === id || e.to === id)).map(e => ({ other: e.from === id ? e.to : e.from, explanation: e.explanation, excerpt: e.excerpt })); } + function metricFill(v) { if (v == null || !(v > 0)) return 0; const f = (Math.log10(1) - Math.log10(Math.max(v, 1e-4))) / 4; return Math.max(0, Math.min(1, f)); } + function matches(m, q) { if (!q) return true; q = q.toLowerCase(); return m.label.toLowerCase().includes(q) || (m.alias || '').toLowerCase().includes(q) || (m.ck || '').toLowerCase().includes(q) || m.groupLabel.toLowerCase().includes(q); } + function kindLabel(k) { return { training: 'Training policy', architecture: 'Architecture', refinement: 'Refinement', composition: 'Component' }[k] || k; } + function fmtSci(v) { if (v == null) return '—'; if (v >= 0.01) return v.toFixed(3); const e = Math.floor(Math.log10(v)); return (v / Math.pow(10, e)).toFixed(2) + 'e' + e; } + + // ---- Vertical list ------------------------------------------------------- + function renderList(container, graph, { selected = null, onSelect = () => {}, kinds = null, query = '', barLabel = 'Accuracy', unit = 'ms' } = {}) { + container.textContent = ''; + const laneW = 16, pad = 10, gw = pad * 2 + laneW * Math.max(1, graph.laneCount - 1) + 8, rowH = 30; + container.style.setProperty('--graphw', gw + 'px'); + const ul = h('ul', 'tree-list'); ul.setAttribute('role', 'listbox'); ul.setAttribute('aria-label', 'Models in checkpoint order'); + const active = t => graph.families.filter(f => f.start < t && t <= f.end); + const laneX = l => pad + 4 + l * laneW; + const visible = m => (!kinds || kinds.has(m.kind)) && matches(m, query); + const rows = new Map(); let shown = 0; + for (const s of graph.sections) { + const list = graph.nodes.slice(s.start, s.end + 1).filter(visible); + if (!list.length) continue; + const li = h('li'); const head = h('div', 'tsect'); + const hs = el('svg', { width: gw, height: 20, 'aria-hidden': 'true' }); + for (const f of active(s.start)) hs.appendChild(el('line', { x1: laneX(f.lane), y1: 0, x2: laneX(f.lane), y2: 20, class: 'lanek lk-' + graph.byId.get(f.children[0]).kind })); + if (graph.seqIn.has(graph.nodes[s.start].id) || graph.seqSpan[s.start]) hs.appendChild(el('line', { x1: laneX(0), y1: 0, x2: laneX(0), y2: 20, class: 'lane0' })); + head.appendChild(hs); head.appendChild(h('h3', null, s.label)); + const fam = graph.families.filter(f => graph.byId.get(f.parent).t >= s.start && graph.byId.get(f.parent).t <= s.end); + head.appendChild(h('span', 'sum', list.length + (list.length === s.count ? '' : ' of ' + s.count) + (fam.length ? ' · ' + fam.map(f => f.children.length + ' from ' + (graph.byId.get(f.parent).ck || graph.byId.get(f.parent).short)).join(', ') : ''))); + li.appendChild(head); ul.appendChild(li); + for (const m of list) { + shown++; + const row = h('li'); const b = h('button', 'trow' + (m.planned ? ' planned' : '')); b.type = 'button'; b.setAttribute('role', 'option'); b.setAttribute('aria-selected', 'false'); b.dataset.id = m.id; b.id = 'tree-' + m.id; + const svg = el('svg', { width: gw, height: rowH, 'aria-hidden': 'true' }); + const x0 = laneX(0), mid = rowH / 2; + if (graph.seqSpan[m.t]) svg.appendChild(el('line', { x1: x0, y1: 0, x2: x0, y2: rowH, class: 'lane0' })); + if (graph.seqIn.has(m.id)) svg.appendChild(el('line', { x1: x0, y1: 0, x2: x0, y2: mid, class: 'lane0' })); + if (graph.seqOut.has(m.id)) svg.appendChild(el('line', { x1: x0, y1: mid, x2: x0, y2: rowH, class: 'lane0' })); + for (const f of active(m.t)) { + const k = 'lanek lk-' + graph.byId.get(f.children[0]).kind, x = laneX(f.lane), isChild = f.children.includes(m.id); + svg.appendChild(el('line', { x1: x, y1: 0, x2: x, y2: isChild ? mid : rowH, class: k })); + if (isChild && m.t < f.end) svg.appendChild(el('line', { x1: x, y1: mid, x2: x, y2: rowH, class: k })); + } + for (const f of graph.families.filter(f => f.parent === m.id)) { const x = laneX(f.lane), k = 'lanek lk-' + graph.byId.get(f.children[0]).kind; svg.appendChild(el('path', { d: `M${x0},${mid} C${x0},${rowH} ${x},${mid} ${x},${rowH}`, class: k })); } + const dot = el('circle', { cx: laneX(m.lane), cy: mid, r: 5, class: 'dot ' + m.kind + (m.planned ? ' planned' : '') }); + svg.appendChild(dot); b.appendChild(svg); + b.appendChild(h('span', 'ck', m.planned ? 'new' : (m.ck || '—'))); + b.appendChild(h('span', 'nm', m.short)); + b.appendChild(h('span', 'pu', m.planned ? (m.setup && m.setup.change || 'not configured') : (m.purpose || ''))); + b.appendChild(h('span', 'chip ' + m.kind, m.planned ? (m.setup && m.setup.prepared ? 'prepared' : 'planned') : kindLabel(m.kind))); + const bar = h('span', 'mbar'); const fill = h('i'); fill.style.width = Math.round(metricFill(m.worstP) * 100) + '%'; bar.appendChild(fill); bar.title = m.worstP == null ? 'No benchmark' : barLabel + ' ' + fmtSci(m.worstP); b.appendChild(bar); + b.appendChild(h('span', 'ms', m.ms == null ? '' : m.ms.toFixed(2) + ' ' + unit)); + b.addEventListener('click', () => onSelect(m.id)); + row.appendChild(b); ul.appendChild(row); rows.set(m.id, { b, dot }); + } + } + ul.addEventListener('keydown', e => { if (e.key !== 'ArrowDown' && e.key !== 'ArrowUp') return; const opts = [...ul.querySelectorAll('.trow')]; const i = opts.indexOf(document.activeElement); if (i < 0) return; const n = opts[i + (e.key === 'ArrowDown' ? 1 : -1)]; if (n) { n.focus(); e.preventDefault(); } }); + container.appendChild(ul); + if (!shown) container.appendChild(h('p', 'empty', 'No models match.')); + let current = null; const walk = walker(); const order = [...rows.keys()]; + const api = { + shown, + select(id) { const rel = id ? related(graph, id) : new Set(); for (const [mid, r] of rows) { r.b.setAttribute('aria-selected', String(mid === id)); r.b.classList.toggle('related', rel.has(mid)); r.dot.classList.toggle('sel', mid === id); } walk(order, current, id, (mid, on) => { const r = rows.get(mid); if (r) r.b.classList.toggle('walk', on); }); current = id; }, + scrollTo(id, smooth) { const r = rows.get(id); if (!r) return; r.b.scrollIntoView({ block: 'center', behavior: smooth && !reduced() ? 'smooth' : 'auto' }); } + }; + api.select(selected); return api; + } + + // ---- Horizontal lane map, with an optional accuracy track ----------------- + function renderMap(container, graph, { selected = null, onSelect = () => {}, kinds = null, query = '', zoom = 1, track = false, metric = 'worstP', trackLabel = 'Accuracy, lower is better', unit = 'ms', timeId = 'ms' } = {}) { + container.textContent = ''; + const dx = 30, left = 70, top = 44, laneH = 52, plotH = 120; + const W = left + graph.nodes.length * dx + 60; + const lanesH = top + 20 + graph.laneCount * laneH; + const trackTop = lanesH + 40, H = track ? trackTop + plotH + 34 : lanesH + 30; + const has = m => m[metric] != null && m[metric] > 0; + const ty = v => trackTop + (0 - Math.log10(Math.min(Math.max(v, 1e-4), 1))) / 4 * plotH; + const x = m => left + m.t * dx, y = m => top + 20 + m.lane * laneH; + const inner = h('div', 'inner'); inner.style.width = W + 'px'; inner.style.height = H + 'px'; inner.style.transform = 'scale(' + zoom + ')'; + const svg = el('svg', { width: W, height: H, viewBox: `0 0 ${W} ${H}`, role: 'img', 'aria-label': 'Model lineage: checkpoints left to right, branches in lanes' + (track ? ', with ' + trackLabel + ' beneath' : '') }); + const visible = m => (!kinds || kinds.has(m.kind)) && matches(m, query); + for (const s of graph.sections) { + const x1 = left + s.start * dx - dx / 2; + svg.appendChild(el('line', { x1, y1: 8, x2: x1, y2: H - 8, class: 'band' })); + svg.appendChild(el('text', { x: x1 + 8, y: 22, class: 'bandlabel' }, s.label)); + if (track) { svg.appendChild(el('text', { x: x1 + 8, y: trackTop - 14, class: 'ttitle' }, trackLabel)); for (const v of [1, 0.01, 0.0001]) svg.appendChild(el('text', { x: x1 + 8, y: ty(v) - 3, class: 'tlabel' }, v >= 0.01 ? String(v) : '1e' + Math.log10(v))); } + } + for (const e of graph.edges) { if (e.kind !== 'sequence') continue; const a = graph.byId.get(e.from), b = graph.byId.get(e.to); svg.appendChild(el('line', { x1: x(a), y1: y(a), x2: x(b), y2: y(b), class: 'seq' })); } + for (const f of graph.families) { + const p = graph.byId.get(f.parent), last = graph.byId.get(f.children[f.children.length - 1]), ly = y(graph.byId.get(f.children[0])), k = graph.byId.get(f.children[0]).kind; + const x0 = x(p), xb = x0 + dx * 1.6; + svg.appendChild(el('path', { d: `M${x0},${y(p)} C${x0 + dx * 0.6},${y(p)} ${xb - dx * 0.6},${ly} ${xb},${ly} L${x(last)},${ly}`, class: 'der lk-' + k, 'data-family': f.parent })); + svg.appendChild(el('text', { x: xb + 4, y: ly - 7, class: 'lanelabel' }, 'from ' + (p.ck || p.short))); + } + const gCmp = el('g', { class: 'cmp-layer' }); svg.appendChild(gCmp); + const trackPts = new Map(); + if (track) { + for (const v of [1, 0.1, 0.01, 0.001, 0.0001]) svg.appendChild(el('line', { x1: left - 16, y1: ty(v), x2: W - 20, y2: ty(v), class: 'tgrid' })); + let d = '', prevT = null; + for (const m of graph.nodes) { if (m.lane !== 0 || !has(m) || m.n == null) continue; d += (prevT !== null && m.t - prevT <= 3 ? 'L' : 'M') + x(m) + ',' + ty(m[metric]) + ' '; prevT = m.t; } + if (d) svg.appendChild(el('path', { d: d.trim(), class: 'tline' })); + for (const m of graph.nodes) { + if (!has(m)) continue; + const c = el('circle', { cx: x(m), cy: ty(m[metric]), r: 3.5, class: 'tpt ' + m.kind + (visible(m) ? '' : ' dim'), tabindex: 0, role: 'button', 'aria-label': (m.ck || m.short) + ', ' + fmtSci(m[metric]) }); + const t = el('title'); t.textContent = (m.ck ? m.ck + ' · ' : '') + m.short + ' · ' + fmtSci(m[metric]); c.appendChild(t); + c.addEventListener('click', () => onSelect(m.id)); c.addEventListener('keydown', ev => { if (ev.key === 'Enter' || ev.key === ' ') { ev.preventDefault(); onSelect(m.id); } }); + svg.appendChild(c); trackPts.set(m.id, c); + } + } + const host = container.parentElement; host.style.position = 'relative'; + host.querySelectorAll('.minimap, .tip').forEach(n => n.remove()); + const tip = h('div', 'tip'); tip.hidden = true; host.appendChild(tip); + const showTip = (m, ev) => { + tip.textContent = ''; tip.appendChild(h('b', null, (m.ck ? m.ck + ' · ' : '') + m.short)); + const rows = m.planned ? [[m.setup && m.setup.prepared ? 'prepared' : 'planned', 'from ' + (graph.byId.get(m.parent).ck || graph.byId.get(m.parent).short)]] : [[has(m) ? fmtSci(m[metric]) : '—', trackLabel.split(',')[0]], [m[timeId] == null ? '—' : m[timeId].toFixed(2) + ' ' + unit, 'per call'], [kindLabel(m.kind), m.parent ? 'from ' + (graph.byId.get(m.parent).ck || graph.byId.get(m.parent).short) : '']]; + for (const [v, l] of rows) { const d = h('div'); d.appendChild(h('span', 'v', v)); d.appendChild(document.createTextNode(' ' + l)); tip.appendChild(d); } + const r = host.getBoundingClientRect(); tip.hidden = false; tip.style.left = Math.min(ev.clientX - r.left + 14, host.clientWidth - 240) + 'px'; tip.style.top = Math.min(ev.clientY - r.top + 12, host.clientHeight - 90) + 'px'; + }; + const nodeEls = new Map(); + for (const m of graph.nodes) { + const g = el('g', { class: 'node ' + m.kind + (m.planned ? ' planned' : '') + (visible(m) ? '' : ' dim'), tabindex: 0, role: 'button', 'aria-label': (m.ck ? m.ck + ' ' : '') + m.short, 'data-id': m.id }); + g.appendChild(el('rect', { x: x(m) - 14, y: y(m) - 14, width: 28, height: 28, class: 'hitr' })); + g.appendChild(el('circle', { cx: x(m), cy: y(m), r: 5.5 })); + const lbl = el('text', { x: x(m), y: y(m) + 18, class: 'nl' }, m.planned ? 'new' : (m.ck || m.short.slice(0, 10))); if (!(m.ck ? m.n % 2 === 1 : m.t % 2 === 1)) lbl.classList.add('off'); g.appendChild(lbl); + g.addEventListener('click', () => onSelect(m.id)); + g.addEventListener('keydown', ev => { if (ev.key === 'Enter' || ev.key === ' ') { ev.preventDefault(); onSelect(m.id); } }); + g.addEventListener('pointerenter', ev => showTip(m, ev)); g.addEventListener('pointermove', ev => showTip(m, ev)); g.addEventListener('pointerleave', () => { tip.hidden = true; }); + g.addEventListener('focus', () => { const r = g.getBoundingClientRect(); showTip(m, { clientX: r.left + 14, clientY: r.top + 14 }); }); g.addEventListener('blur', () => { tip.hidden = true; }); + svg.appendChild(g); nodeEls.set(m.id, { g, lbl }); + } + inner.appendChild(svg); container.appendChild(inner); + const mini = h('div', 'minimap'); mini.setAttribute('role', 'img'); mini.setAttribute('aria-label', 'Whole map; click to move'); + const ms = el('svg', { viewBox: `0 0 ${W} ${H}`, preserveAspectRatio: 'none' }); + for (const m of graph.nodes) ms.appendChild(el('circle', { cx: x(m), cy: y(m), r: 7, class: 'd' })); + const vp = el('rect', { class: 'vp', x: 0, y: 0, width: 10, height: 10 }); ms.appendChild(vp); mini.appendChild(ms); host.appendChild(mini); + const sync = () => { vp.setAttribute('x', container.scrollLeft / zoom); vp.setAttribute('y', container.scrollTop / zoom); vp.setAttribute('width', container.clientWidth / zoom); vp.setAttribute('height', container.clientHeight / zoom); }; + container.addEventListener('scroll', sync); sync(); + mini.addEventListener('click', ev => { const r = mini.getBoundingClientRect(); container.scrollTo({ left: ((ev.clientX - r.left) / r.width) * W * zoom - container.clientWidth / 2, top: ((ev.clientY - r.top) / r.height) * H * zoom - container.clientHeight / 2, behavior: reduced() ? 'auto' : 'smooth' }); }); + let current = null; const walk = walker(); const order = graph.nodes.map(m => m.id); + const api = { + select(id) { + const sel = graph.byId.get(id); + gCmp.textContent = ''; + walk(order, current, id, (mid, on) => { const n = nodeEls.get(mid); if (n) n.g.classList.toggle('walk', on); }); current = id; + for (const [mid, n] of nodeEls) { const m = graph.byId.get(mid); const on = mid === id; n.g.classList.toggle('sel', on); n.g.querySelector('circle').setAttribute('r', on ? 7 : 5.5); const fam = sel && (m.parent === id || mid === sel.parent || (sel.parent && m.parent === sel.parent)); n.lbl.classList.toggle('off', !(on || fam || (m.ck ? m.n % 2 === 1 : m.t % 2 === 1))); n.g.classList.toggle('kin', !!fam && !on); } + for (const p of svg.querySelectorAll('.der')) p.classList.toggle('hot', !!sel && (p.dataset.family === id || p.dataset.family === sel.parent)); + for (const [mid, c] of trackPts) c.classList.toggle('sel', mid === id); + if (sel) for (const e of graph.edges) if (e.kind === 'comparison' && (e.from === id || e.to === id)) { + const a = graph.byId.get(e.from), b = graph.byId.get(e.to), other = e.from === id ? b : a; + const path = el('path', { d: `M${x(a)},${y(a)} C${x(a)},${Math.min(y(a), y(b)) - 34} ${x(b)},${Math.min(y(a), y(b)) - 34} ${x(b)},${y(b)}`, class: 'cmp', tabindex: 0, role: 'link', 'aria-label': 'Compared with ' + (other.ck || other.short) }); + const t = el('title'); t.textContent = 'Compared with ' + (other.ck || other.short) + ': ' + (e.excerpt || e.explanation || ''); path.appendChild(t); + const show = ev => { tip.textContent = ''; tip.appendChild(h('b', null, 'Compared with ' + (other.ck || other.short))); tip.appendChild(h('div', null, (e.excerpt || e.explanation || '').slice(0, 160) + ((e.excerpt || '').length > 160 ? '…' : ''))); const r = host.getBoundingClientRect(); tip.hidden = false; tip.style.left = Math.min(ev.clientX - r.left + 14, host.clientWidth - 240) + 'px'; tip.style.top = Math.min(ev.clientY - r.top + 12, host.clientHeight - 90) + 'px'; }; + path.addEventListener('pointerenter', show); path.addEventListener('pointermove', show); path.addEventListener('pointerleave', () => { tip.hidden = true; }); + path.addEventListener('click', () => onSelect(other.id)); path.addEventListener('keydown', ev => { if (ev.key === 'Enter') onSelect(other.id); }); + gCmp.appendChild(path); + } + }, + scrollTo(id, smooth) { const m = graph.byId.get(id); if (!m) return; container.scrollTo({ left: x(m) * zoom - container.clientWidth / 2, top: Math.max(0, y(m) * zoom - container.clientHeight / 2), behavior: smooth && !reduced() ? 'smooth' : 'auto' }); } + }; + api.select(selected); return api; + } + return { build, renderList, renderMap, related, comparisons, kindLabel, fmtSci, metricFill, matches }; +})(); From ecca58d10d918430919db928722910be156a8833 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 12 Nov 2026 11:00:21 -0700 Subject: [PATCH 039/131] docs(plan): specify the Map workspace, phase 1: what the map reads Co-Authored-By: Claude Fable 5.2 --- .../definition-first-projects/spec-w1.md | 69 +++++++++++++++++++ 1 file changed, 69 insertions(+) create mode 100644 docs/plans/definition-first-projects/spec-w1.md diff --git a/docs/plans/definition-first-projects/spec-w1.md b/docs/plans/definition-first-projects/spec-w1.md new file mode 100644 index 00000000..7b56507f --- /dev/null +++ b/docs/plans/definition-first-projects/spec-w1.md @@ -0,0 +1,69 @@ +# Implementation spec: the Map workspace, phase 1: what the map reads + +This is phase 1 of [the Map workspace plan](workspace-plan.md). Section 1 of [spec-m1-m2.md](spec-m1-m2.md) (rules for implementers) applies, with the import rule as amended by [spec-m7.md](spec-m7.md). This phase adds fields to the project folder format and three read operations. It adds no page. + +**Done when:** for the lab folder, one `map` answer holds its 206 models in their sections with the kind of change of each, the lines from a model to the one it was derived from, the 26 authored comparisons, and a track value for every model that has a result on the track's benchmark; `note` returns a model's card; and `recipe_results` returns one model's results across benchmarks. + +## 1. Fields added to the format + +All are optional. A folder without them is as valid as before. + +**`tuldok.json`:** + +| Field | Type | Rule | +| --- | --- | --- | +| `groups` | array | 0 to 200 objects, in the order their sections are shown. Each: `id` (1 to 64 characters, `[A-Za-z0-9][A-Za-z0-9_.-]*`, once), `title` (1 to 200 characters), `parent` (optional: the `id` of another group; a group is never its own ancestor), `description` (optional, at most 2000 characters). Unknown fields are refused | +| `map` | object | `chart`: the reference of a chart definition whose form is `progression`. Its benchmark, metric and statistic are the map's track. Unknown fields are refused | + +**A recipe:** + +| Field | Type | Rule | +| --- | --- | --- | +| `group` | text | the `id` of one of the project's groups | +| `change` | text | `training-policy`, `architecture`, `refinement` or `component`: the kind of change this model makes | +| `derived_from` | reference | another recipe: the model this one was branched from. Never itself, and following `derived_from` never returns to where it started | +| `compared_with` | array | at most 50 objects, each `recipe` (the reference of another recipe, once in the list), `explanation` (1 to 2000 characters) and `excerpt` (optional, at most 2000 characters). Unknown fields are refused | + +The label `short`, when a recipe has it, is the text of its node on the map (at most 16 characters are shown). It is a label like `trained_at`, not a new field. + +**The checker** reports as errors: a `group` that is no group of the project; a group whose `parent` is unknown or that is its own ancestor; a `derived_from` or a compared `recipe` that is not a recipe of the project or is the recipe itself; a loop of `derived_from`; a `map.chart` that is not a chart of the form `progression`. + +**The graph** gains two edge roles, `derived` and `compared`, from the recipe that carries the field to the recipe it names. They appear in a definition's `uses` and `used_by`. They carry no state, the plan does not follow them, and `order` ignores them: a comparison may run both ways. + +## 2. Operations + +Three operations of the `project_folder` profile, all for a credential with `inspect`, none a mutation. + +**`map`**, no arguments. Result: + +| Key | Holds | +| --- | --- | +| `groups` | the project's groups in their order, each with `id`, `title`, `parent`, `description` and `models`, the number of recipes that name it | +| `models` | one object per recipe, ordered by the label `trained_at` ascending, then those without one, by name. Each: `reference`, `title`, `short` (the label, or null), `group`, `change`, `derived_from` (each null when absent), `trained_at` (or null), `state`, `adopted`, `card` (the recipe's `card` path, or null), `value` and `count` (the track's statistic for this recipe and how many cases it summarises, or null), `benchmarks` (in how many benchmarks it has result rows) | +| `edges` | `{from, to, kind}`: `derived` for each `derived_from`, and `input` for each recipe that uses another recipe as an input | +| `comparisons` | `{from, to, explanation, excerpt}` for each compared pair, as authored | +| `track` | null, or `{chart, benchmark, metric: {id, title, units, better}, statistic}` from `map.chart` | + +The answer is made from the definitions and the summary rows in the database with a fixed number of queries. No results file, values file or note is read. When a recipe is the subject of the track's benchmark under several subject names, the best value by the metric's `better` is its value. + +**`note`**, argument `path`: a path relative to the folder's `notes/` directory, in normal form. Result `{path, text}`. The file is read from the folder on disk without opening the project: a regular file, no link in the path, at most 1 MiB, UTF-8. Anything else is refused `not-found`. + +**`recipe_results`**, arguments `recipe` (a reference) and optional `group` (as in `results`; absent means the ungrouped rows only). Result: `rows`, the summary rows of every benchmark subject whose recipe this is, each row as in `results` with `benchmark` and `subject` added, ordered by benchmark, subject and metric; and `benchmarks`, the names of those benchmarks. + +**Command line:** `map FOLDER [--json]` prints, per group in order, its title, how many models it has and how many of each kind, then the totals, the lines and comparisons counted, and the track. `note FOLDER PATH` prints a note. + +## 3. The lab folder + +The lab's converter writes the new fields, and the notes file that held groups and comparisons (`notes/model-groups-and-comparisons.json`) is no longer written: + +- `groups` in `tuldok.json`, from the groups it already extracts, in their order, and `group` on each recipe. +- `compared_with` on each recipe that has comparisons. +- `change`, `derived_from` and the label `short`, from a seed file in the lab, `scripts/earlier-model-map.json`, made once from the workspace mockup's data file: for each earlier fit, the mockup's short label (`C74`), its kind (`training` becomes `training-policy`, `composition` becomes `component`) and the first of its parents. The seed says where it came from: the mockup inferred kinds and parents from the text of the model cards, so they are starting values for the owner to correct in the definitions. +- `map.chart`: the lab's chart of the form `progression` for the benchmark the mockup's accuracy track used (worst pressure relative L2 on the consumed fitting requests), or a new chart definition for it when none of the lab's eight charts is that. + +## 4. Slices + +| Slice | Files | Notes | +| --- | --- | --- | +| T17 | the schemas, `check.py`, `graph.py`, a new `tuldok_project/workspace.py` for the three operations, their rows in `operations.py` and `service.py`, `map` and `note` in `__main__.py`, tests, and the sections of `docs/contracts/project-folder.md` | the `minimal` fixture gains groups, a derivation, a comparison and a `map.chart` | +| L6 | `lab:scripts/build_tuldok_project.py`, `lab:scripts/earlier-model-map.json`, `lab:scripts/tests/`, the regenerated `lab:projects/surrogate-lab/` | after T17 | From a4047b689ab28f6768c6109e455e210815c0e10f Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 12 Nov 2026 11:00:21 -0700 Subject: [PATCH 040/131] feat(project): the fields and operations the Map workspace reads tuldok.json may list groups and name the chart that is the map's track. A recipe may name its group, the kind of change it makes, the model it was derived from and the models it is compared with. The checker enforces them, and the graph shows derivations and comparisons as edges that carry no state and that the plan and the build order ignore. Three read operations: map (every model with its group, kind, state and track value, the lines between models, the comparisons and the groups, in a fixed number of queries), note (one file under notes/) and recipe_results (one model's results across benchmarks). tuldok.json is now kept in the database so the map needs no file. Co-Authored-By: Claude Fable 5.2 --- docs/contracts/project-folder.md | 58 +- .../minimal/project/recipes/early-fit.json | 6 +- .../minimal/project/recipes/stepper-k1.json | 7 + .../minimal/project/recipes/stepper-k2.json | 8 + .../minimal/project/tuldok.json | 7 +- tests/test_tuldok_project_check.py | 15 +- tests/test_tuldok_project_result_rows.py | 11 + tests/test_tuldok_project_service.py | 6 +- tests/test_tuldok_project_store.py | 7 + tests/test_tuldok_project_workspace.py | 604 ++++++++++++++++++ tuldok_project/__main__.py | 65 +- tuldok_project/check.py | 86 ++- tuldok_project/documents.py | 6 +- tuldok_project/graph.py | 42 +- tuldok_project/operations.py | 12 +- tuldok_project/schemas/project.schema.json | 53 ++ tuldok_project/schemas/recipe.schema.json | 49 ++ tuldok_project/service.py | 14 +- tuldok_project/store.py | 41 +- tuldok_project/workspace.py | 216 +++++++ 20 files changed, 1282 insertions(+), 31 deletions(-) create mode 100644 tests/test_tuldok_project_workspace.py create mode 100644 tuldok_project/workspace.py diff --git a/docs/contracts/project-folder.md b/docs/contracts/project-folder.md index e30996d4..5d2edbfa 100644 --- a/docs/contracts/project-folder.md +++ b/docs/contracts/project-folder.md @@ -84,6 +84,8 @@ holding one JSON object. The checker refuses: | `name` | yes | 1 to 120 characters | | `code_root` | no | the path from the project folder to the root of the code that commands run in; default `.`; not empty and not absolute; may contain `..` | | `code_paths` | no | 1 to 64 paths relative to the code root, in normal form (no `..`, no empty or `.` parts, no trailing `/`), each listed once and each existing under the code root; default: the whole code root | +| `groups` | no | 0 to 200 objects, in the order their sections are shown on the map. Each: `id` (1 to 64 characters, `[A-Za-z0-9][A-Za-z0-9_.-]*`, each id once), `title` (1 to 200 characters), `parent` (optional: the `id` of another group; a group is never its own ancestor), `description` (optional, at most 2,000 characters); no other field | +| `map` | no | `{"chart": }`, no other field: a chart of the form `progression`, whose benchmark, metric and statistic are the map's track | `code_paths` names the parts of the repository a run needs: a run sees a read-only copy of only those paths at the commit it runs from, and only @@ -275,6 +277,15 @@ A recipe trains a model; its product is weights. | --- | --- | --- | | `run` | unless `earlier_work.rebuild` is `no` | see the `run` block | | `model` | no | reference to `models/` | +| `group` | no | the `id` of one of the project's `groups` in `tuldok.json`: the section of the map it is shown in | +| `change` | no | `training-policy`, `architecture`, `refinement` or `component`: the kind of change this model makes | +| `derived_from` | no | reference to another recipe in `recipes/`: the model this one was branched from. Never the recipe itself, and following `derived_from` never comes back to where it started | +| `compared_with` | no | at most 50 objects, each `recipe` (reference to another recipe, each once in the list), `explanation` (1 to 2,000 characters) and `excerpt` (optional, at most 2,000 characters); no other field | + +The label `short`, when a recipe has it, is the text of its node on the map +(at most 16 characters are shown). `derived_from` and `compared_with` say how +recipes relate on the map; they are not inputs, so building never follows +them, and a comparison may run both ways. Example, `recipes/pilot-dense-k1.json`: @@ -506,9 +517,22 @@ pilot-dense-k1,velocity_error_final,cells_per_metre=8,4,0,0.195,0.175,0.129,0.27 | a benchmark's `cases.dataset` | `cases` | | a chart's `benchmark` | `benchmark` | + Two more fields of a recipe are edges with a role, shown in a definition's + uses and used-by, but are not uses in this sense: they may run both ways, + carry no state, and the plan and the build order do not follow them. + + | Field | Role of the edge | + | --- | --- | + | a recipe's `derived_from` | `derived` | + | a recipe's `compared_with[].recipe` | `compared` | + 4. A chart's `metric`, `metric_x`, `subjects` and `group` exist in its benchmark. 5. Code paths exist under the code root (see the `run` block). 6. Every results file has its benchmark and follows the rules above. +7. A recipe's `group` is a group of `tuldok.json`; a group's `parent` is another + group and no group is its own ancestor; a recipe is never derived from or + compared with itself; following `derived_from` never comes back to where it + started; `map.chart` is a chart of the form `progression`. ## Checking a folder @@ -571,10 +595,17 @@ to the folder. Each project has its own schema, `project_`, named after the | `graph [--order]` | Prints every definition with its kind and state, then every use as `from role to`. `--order` instead prints the build order: each definition after everything it uses, with its state. | | `status` | Lists definitions edited or removed in the database and not yet saved, and definition files added, changed or missing on disk since the last import. | | `set REFERENCE FILE` | Replaces or adds the definition at `REFERENCE` with the text of `FILE`, in the database only. The text is checked on its own and against the rest of the project; an edit with any error is refused and changes nothing. | -| `remove REFERENCE` | Removes the definition in the database only. It is refused while another definition uses it. | +| `remove REFERENCE` | Removes the definition in the database only. It is refused while another definition uses it, or while it is the chart `tuldok.json` names in `map.chart`. | +| `map` | Prints the project's map: per group in order, its title, how many models (recipes) it has and how many of each kind of change, then the models in no group and the totals, then how many lines (`derived_from`, and recipes used as inputs by recipes) and comparisons there are, and the track. Reads the database only, never a results file, values file or note. | | `save` | Writes every unsaved definition to its file and deletes the files of removed ones. It writes nothing when one of those files changed on disk since it was imported, and names them. | | `forget` | Drops the project's copy from the database, including unsaved edits. The folder is not touched. | +`note FOLDER PATH` prints one file under the folder's `notes/` directory, +`PATH` being relative to `notes/` (for example `fits/early-fit.md`). Like +`check`, it needs no database: it reads the folder on disk, refusing a path +not in normal form, a link anywhere on the way, a file that is not regular, +larger than 1 MiB or not UTF-8 (exit status 1). + Every command except `forget` opens the project first, which imports anything that changed on disk, so `list`, `show`, `graph` and `status` always describe the folder as it is now plus the unsaved edits. Opening runs the same check as @@ -595,8 +626,8 @@ Options: | Option | Commands | Meaning | | --- | --- | --- | -| `--database-url URL` | all but `check` | The Postgres database. Without it, the `TULDOK_DATABASE_URL` environment variable is used; with neither, the command stops with exit status 2. | -| `--json` | `open`, `list`, `show`, `graph`, `status`, `save`, `results`, `values`, `import-values`, `chart`, `plan`, `environments`, `connect`, `check-environment`, `set-up`, `runs`, `run`, `progress`, `cancel`, `stop`, `products`, `estimate` | Print one JSON document with the same content as the text. | +| `--database-url URL` | all but `check` and `note` | The Postgres database. Without it, the `TULDOK_DATABASE_URL` environment variable is used; with neither, the command stops with exit status 2. | +| `--json` | `open`, `list`, `show`, `graph`, `map`, `status`, `save`, `results`, `values`, `import-values`, `chart`, `plan`, `environments`, `connect`, `check-environment`, `set-up`, `runs`, `run`, `progress`, `cancel`, `stop`, `products`, `estimate` | Print one JSON document with the same content as the text. | | `--rebind` | all that open | The copy is bound to the folder it was first opened from. Opening the same project from another path is refused unless `--rebind` is given, which binds the copy to the new path. | | `--keep` | all that open | Where a file changed on disk and the same definition has unsaved edits, keep the edits; the changed file becomes the version that `save` replaces. | | `--discard` | all that open | Where a file changed on disk and the same definition has unsaved edits, drop the edits and take the file. | @@ -1829,6 +1860,9 @@ and result keys of each operation are in its contract. | `build_requests` | inspect | List the build requests, newest first, optionally in one state. | | `build_request` | inspect | Read one build request with what it covers and the runs of its build. | | `activity` | inspect | List the changes asked of this project through the interface, newest first, and how each ended. | +| `map` | inspect | Read the map of the project: its groups, every recipe as a model with its group, kind of change, state and track value, the lines between them and the comparisons. | +| `note` | inspect | Read one file under the notes directory of the project folder, given relative to it. | +| `recipe_results` | inspect | Read the summary rows of every benchmark subject made from one recipe, ungrouped or for one group. | | `set_definition` | edit | Check a definition's text and keep it as an unsaved edit. | | `remove_definition` | edit | Mark a definition that nothing uses as removed, until the project is saved. | | `save` | edit | Write the unsaved edits and changed results files to the project folder. | @@ -1844,6 +1878,24 @@ and result keys of each operation are in its contract. | `cancel_run` | cancel | Ask a queued or running run to stop. | | `stop_run` | cancel | Kill what a run whose build is gone left running, and mark it unknown. | +`map` answers `groups` (in their order, each with `id`, `title`, `parent`, +`description` and `models`, the number of recipes naming it), `models` (one per +recipe, by the label `trained_at` and then by name: `reference`, `title`, +`short`, `group`, `change`, `derived_from`, `trained_at`, `state`, `adopted`, +`card`, `value` and `count`, `benchmarks`), `edges` (`{from, to, kind}`, +`derived` or `input`), `comparisons` (`{from, to, explanation, excerpt}` as +authored) and `track` (null, or `{chart, benchmark, metric, statistic}` from +`map.chart`). A model's `value` and `count` are the track's statistic on the +ungrouped row of its subject and how many cases it summarises; when a recipe +is the subject under several names, the best by the metric's `better` is +taken. `map` runs the same few queries whatever the number of recipes and +reads no file. `note` takes `path`, relative to `notes/`, and reads it from +the folder without opening the project; anything it refuses is `not-found`. +`recipe_results` takes `recipe` and an optional `group` (absent: the +ungrouped rows only) and answers `rows`, each as in `results` with +`benchmark` added, ordered by benchmark, subject and metric, and +`benchmarks`, the benchmarks with a subject made from that recipe. + Installing an environment (`set-up`), measuring estimates (`estimate`), variables passed to a build (`build --env`), rebinding and forgetting a project stay command-line actions. diff --git a/tests/fixtures/tuldok_project/minimal/project/recipes/early-fit.json b/tests/fixtures/tuldok_project/minimal/project/recipes/early-fit.json index bb92cd60..07cd2d8b 100644 --- a/tests/fixtures/tuldok_project/minimal/project/recipes/early-fit.json +++ b/tests/fixtures/tuldok_project/minimal/project/recipes/early-fit.json @@ -4,7 +4,9 @@ "title": "Early fit (fit-0042)", "description": "A stepper trained before this format; only its weights and measurements remain.", "card": "notes/fits/early-fit.md", - "labels": {"fit_id": "fit-0042", "trained_at": "2026-03-14", "device": "cuda"}, + "labels": {"fit_id": "fit-0042", "trained_at": "2026-03-14", "device": "cuda", "short": "F42"}, "earlier_work": {"rebuild": "no", "reason": "Trained by the earlier study harness; its command and training data were not recorded."}, - "model": "models/stepper" + "model": "models/stepper", + "group": "steppers", + "change": "architecture" } diff --git a/tests/fixtures/tuldok_project/minimal/project/recipes/stepper-k1.json b/tests/fixtures/tuldok_project/minimal/project/recipes/stepper-k1.json index dec6f995..688e7083 100644 --- a/tests/fixtures/tuldok_project/minimal/project/recipes/stepper-k1.json +++ b/tests/fixtures/tuldok_project/minimal/project/recipes/stepper-k1.json @@ -3,6 +3,13 @@ "kind": "recipe", "title": "Stepper on wave scenes", "model": "models/stepper", + "labels": {"short": "K1"}, + "group": "steppers", + "change": "training-policy", + "derived_from": "recipes/early-fit", + "compared_with": [ + {"recipe": "recipes/early-fit", "explanation": "Same stepper, trained again with a recorded command and data."} + ], "run": { "command": ["python", "lab/train.py", "--data", "{inputs.training}", "--settings", "{settings}", "--out", "{output}"], "environment": "environments/lab-cpu", diff --git a/tests/fixtures/tuldok_project/minimal/project/recipes/stepper-k2.json b/tests/fixtures/tuldok_project/minimal/project/recipes/stepper-k2.json index 1b80683f..1e8bf807 100644 --- a/tests/fixtures/tuldok_project/minimal/project/recipes/stepper-k2.json +++ b/tests/fixtures/tuldok_project/minimal/project/recipes/stepper-k2.json @@ -3,6 +3,14 @@ "kind": "recipe", "title": "Stepper fine-tuned from k1", "model": "models/stepper", + "labels": {"short": "K2"}, + "group": "fine-tuned", + "change": "refinement", + "derived_from": "recipes/stepper-k1", + "compared_with": [ + {"recipe": "recipes/stepper-k1", "explanation": "Fine-tuning lowers the rollout error at both horizons.", + "excerpt": "k2 halves the median error at horizon 1."} + ], "run": { "command": ["python", "lab/train.py", "--start", "{inputs.start}", "--data", "{inputs.training}", "--settings", "{settings}", "--out", "{output}"], "environment": "environments/lab-cpu", diff --git a/tests/fixtures/tuldok_project/minimal/project/tuldok.json b/tests/fixtures/tuldok_project/minimal/project/tuldok.json index cf2e440e..ebfbd167 100644 --- a/tests/fixtures/tuldok_project/minimal/project/tuldok.json +++ b/tests/fixtures/tuldok_project/minimal/project/tuldok.json @@ -2,5 +2,10 @@ "format": "tuldok_project_v1", "id": "3f9c2a1b7d4e4f60a8b1c2d3e4f50617", "name": "Minimal surrogate project", - "code_root": "../code" + "code_root": "../code", + "groups": [ + {"id": "steppers", "title": "Steppers", "description": "Every stepper trained on wave scenes."}, + {"id": "fine-tuned", "title": "Fine-tuned steppers", "parent": "steppers"} + ], + "map": {"chart": "charts/rollout-progression"} } diff --git a/tests/test_tuldok_project_check.py b/tests/test_tuldok_project_check.py index d487d64d..d6a62ff8 100644 --- a/tests/test_tuldok_project_check.py +++ b/tests/test_tuldok_project_check.py @@ -127,6 +127,7 @@ def test_readme_and_gitignore_are_allowed(self): def test_definition_directory_may_be_absent(self): shutil.rmtree(self.project / 'charts') + self.edit('tuldok.json', '/map', DELETE) # map.chart names a chart (spec-w1.md) self.assertClean(check_folder(self.project)) def test_definition_directory_holds_only_json(self): @@ -144,7 +145,11 @@ def test_definition_file_name_follows_the_name_rule(self): def test_definition_directory_must_be_a_directory(self): shutil.rmtree(self.project / 'charts') self.write('charts', 'x') - self.assertProblem(check_folder(self.project), 'charts', '') + report = check_folder(self.project) + self.assertProblem(report, 'charts', '', alone=False) + # tuldok.json's map.chart names a chart, which is then not there (spec-w1.md). + self.assertProblem(report, 'tuldok.json', '/map/chart', alone=False) + self.assertEqual(len(report.problems), 2) def test_definition_file_may_not_be_a_symbolic_link(self): os.symlink('speed-accuracy.json', self.project / 'charts/copy.json') @@ -153,7 +158,11 @@ def test_definition_file_may_not_be_a_symbolic_link(self): def test_definition_directory_may_not_be_a_symbolic_link(self): shutil.move(self.project / 'charts', self.base / 'charts') os.symlink(self.base / 'charts', self.project / 'charts') - self.assertProblem(check_folder(self.project), 'charts', '') + report = check_folder(self.project) + self.assertProblem(report, 'charts', '', alone=False) + # tuldok.json's map.chart names a chart, which is then not there (spec-w1.md). + self.assertProblem(report, 'tuldok.json', '/map/chart', alone=False) + self.assertEqual(len(report.problems), 2) def test_project_file_may_not_be_a_symbolic_link(self): shutil.move(self.project / 'tuldok.json', self.base / 'tuldok.json') @@ -640,6 +649,8 @@ def test_order_puts_dependencies_first_with_ties_by_reference(self): def test_users_of(self): users = graph.users_of(self.definitions, 'recipes/stepper-k1') self.assertEqual(users, [graph.Edge('benchmarks/rollout', 'recipes/stepper-k1', 'subject:stepper-k1'), + graph.Edge('recipes/stepper-k2', 'recipes/stepper-k1', 'compared'), + graph.Edge('recipes/stepper-k2', 'recipes/stepper-k1', 'derived'), graph.Edge('recipes/stepper-k2', 'recipes/stepper-k1', 'input:start')]) def test_cycles_and_order_refuses_them(self): diff --git a/tests/test_tuldok_project_result_rows.py b/tests/test_tuldok_project_result_rows.py index 230e1238..3fa95af4 100644 --- a/tests/test_tuldok_project_result_rows.py +++ b/tests/test_tuldok_project_result_rows.py @@ -22,6 +22,7 @@ from tuldok_project import check, result_rows, results # noqa: E402 from tuldok_project.results import SummaryRow # noqa: E402 from tuldok_project.store import ProjectError # noqa: E402 +from tuldok_project.store import ProjectError # noqa: E402 from test_tuldok_project_store import FIXTURE, StoreCase # noqa: E402 REPOSITORY = Path(__file__).resolve().parents[1] @@ -405,6 +406,16 @@ def test_save_refuses_when_the_results_file_changed_on_disk(self): self.assertNotEqual(self.read('datasets/waves'), waves) # nothing at all was written def test_removing_the_benchmark_removes_its_results_and_save_deletes_the_file(self): + # tuldok.json's map.chart uses charts/rollout-progression (spec-w1.md): drop it first. + with self.assertRaises(ProjectError) as caught: + self.project.remove_definition('charts/rollout-progression') + self.assertEqual((caught.exception.code, caught.exception.references), ('in-use', ['tuldok.json'])) + self.close(self.project) + project_file = self.folder / 'tuldok.json' + document = json.loads(project_file.read_text(encoding='utf-8')) + del document['map'] + project_file.write_text(json.dumps(document, indent=2) + '\n', encoding='utf-8') + self.project = self.open() self.project.import_values(values_file()) for chart in ('speed-accuracy', 'rollout-ranking', 'rollout-progression', 'rollout-comparison'): self.project.remove_definition(f'charts/{chart}') diff --git a/tests/test_tuldok_project_service.py b/tests/test_tuldok_project_service.py index 5ff524d4..5213596e 100644 --- a/tests/test_tuldok_project_service.py +++ b/tests/test_tuldok_project_service.py @@ -48,7 +48,7 @@ class Table(unittest.TestCase): def test_every_operation_is_declared_once(self): names = [operation.name for operation in operations.OPERATIONS] - self.assertEqual(len(names), 36) # the rows of spec-m7.md section 2 + self.assertEqual(len(names), 39) # the rows of spec-m7.md section 2 and of spec-w1.md section 2 self.assertEqual(len(set(names)), len(names)) for name in REQUEST_OPERATIONS: self.assertIsNotNone(operations.by_name(name)) @@ -203,6 +203,7 @@ def test_every_read(self): 'plan': {'targets': ['benchmarks/score']}, 'estimates': {}, 'environments': {}, 'environment': {'reference': 'environments/test-python'}, 'runs': {'limit': 2}, 'run': {'run': run_id}, 'progress': {'run': run_id[:8]}, 'products': {}, 'activity': {}, + 'map': {}, 'note': {'path': 'missing.md'}, 'recipe_results': {'recipe': 'recipes/fit-a'}, } reads = [operation for operation in operations.OPERATIONS if not operation.mutation] arguments['build_requests'] = {'state': 'queued', 'limit': 5} @@ -212,6 +213,9 @@ def test_every_read(self): if operation.name == 'build_request': # tested with a request in test_tuldok_project_build_requests self.assertEqual(self.refused(operation.name, {'request': 'abcdef12'}).code, 'not-found') continue + if operation.name == 'note': # this fixture has no notes; read in test_tuldok_project_workspace + self.assertEqual(self.refused(operation.name, arguments['note']).code, 'not-found') + continue result = self.call(operation.name, arguments[operation.name], actor=agent('inspect')) self.assertTrue(set(operation.result) <= set(result), set(operation.result) - set(result)) self.assertEqual(self.activity(), []) # reads are not recorded diff --git a/tests/test_tuldok_project_store.py b/tests/test_tuldok_project_store.py index c6bceda9..5709dabf 100644 --- a/tests/test_tuldok_project_store.py +++ b/tests/test_tuldok_project_store.py @@ -390,6 +390,13 @@ def test_remove_refused_while_used(self): self.assertEqual(self.dump(), before) def test_removing_a_user_frees_what_it_used(self): + # tuldok.json's map.chart uses charts/rollout-progression (spec-w1.md): drop it first. + self.close(self.project) + project_file = self.folder / 'tuldok.json' + document = json.loads(project_file.read_text(encoding='utf-8')) + del document['map'] + project_file.write_text(json.dumps(document, indent=2) + '\n', encoding='utf-8') + self.project = self.open() for chart in ('speed-accuracy', 'rollout-ranking', 'rollout-progression', 'rollout-comparison'): self.project.remove_definition(f'charts/{chart}') self.project.remove_definition('benchmarks/rollout') diff --git a/tests/test_tuldok_project_workspace.py b/tests/test_tuldok_project_workspace.py new file mode 100644 index 00000000..64266ac9 --- /dev/null +++ b/tests/test_tuldok_project_workspace.py @@ -0,0 +1,604 @@ +"""The Map workspace's reading (docs/plans/definition-first-projects/spec-w1.md): format fields and three operations. + +The checker rules and the graph roles are tested without a database, on a +copy of tests/fixtures/tuldok_project/minimal (FixtureCopy of the checker's +tests). read_note needs no database either. Everything else runs only when +TULDOK_DATABASE_URL names a disposable cluster (spec-m1-m2.md, section 1): +map and recipe_results on a copy of the minimal fixture (StoreCase), the +operations through Service.call and the two commands, and one build of the +buildable fixture (BuildCase) with comparisons and a derivation added, which +must build exactly as without them. Anything that could reach the local +project home points TULDOK_PROJECT_HOME at a temporary directory. +""" +import copy +import json +import os +from pathlib import Path +import shutil +import subprocess +import sys +import tempfile +import unittest +from unittest import mock + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) +sys.path.insert(0, str(Path(__file__).resolve().parent)) + +from tuldok_project import build_requests, graph, local, plan, workspace # noqa: E402 +from tuldok_project.check import check_folder # noqa: E402 +from tuldok_project.service import Service # noqa: E402 +from tuldok_project.store import ProjectError # noqa: E402 +import test_tuldok_project_builds as builds_base # noqa: E402 +import test_tuldok_project_check as check_base # noqa: E402 +import test_tuldok_project_store as store_base # noqa: E402 + +REPOSITORY = Path(__file__).resolve().parents[1] +FIXTURE = REPOSITORY / 'tests' / 'fixtures' / 'tuldok_project' / 'minimal' +DATABASE = os.environ.get('TULDOK_DATABASE_URL') +INSPECTOR = {'actor_id': 'agent-inspect', 'kind': 'agent', 'label': 'An agent', 'scopes': ['inspect']} +NOBODY = {'actor_id': 'agent-none', 'kind': 'agent', 'label': 'An agent', 'scopes': []} +COMMIT = '0123456789abcdef0123456789abcdef01234567' + +FIXTURE_MAP = { + 'groups': [ + {'id': 'steppers', 'title': 'Steppers', 'parent': None, + 'description': 'Every stepper trained on wave scenes.', 'models': 2}, + {'id': 'fine-tuned', 'title': 'Fine-tuned steppers', 'parent': 'steppers', 'description': None, 'models': 1}, + ], + 'models': [ + {'reference': 'recipes/early-fit', 'title': 'Early fit (fit-0042)', 'short': 'F42', 'group': 'steppers', + 'change': 'architecture', 'derived_from': None, 'trained_at': '2026-03-14', 'state': 'cannot-rebuild', + 'adopted': False, 'card': 'notes/fits/early-fit.md', 'value': 0.625, 'count': 4, 'benchmarks': 1}, + {'reference': 'recipes/stepper-k1', 'title': 'Stepper on wave scenes', 'short': 'K1', 'group': 'steppers', + 'change': 'training-policy', 'derived_from': 'recipes/early-fit', 'trained_at': None, 'state': 'not-built', + 'adopted': False, 'card': None, 'value': 0.875, 'count': 8, 'benchmarks': 1}, + {'reference': 'recipes/stepper-k2', 'title': 'Stepper fine-tuned from k1', 'short': 'K2', + 'group': 'fine-tuned', 'change': 'refinement', 'derived_from': 'recipes/stepper-k1', 'trained_at': None, + 'state': 'not-built', 'adopted': False, 'card': None, 'value': 0.5, 'count': 8, 'benchmarks': 1}, + ], + 'edges': [ + {'from': 'recipes/stepper-k1', 'to': 'recipes/early-fit', 'kind': 'derived'}, + {'from': 'recipes/stepper-k2', 'to': 'recipes/stepper-k1', 'kind': 'derived'}, + {'from': 'recipes/stepper-k2', 'to': 'recipes/stepper-k1', 'kind': 'input'}, + ], + 'comparisons': [ + {'from': 'recipes/stepper-k1', 'to': 'recipes/early-fit', + 'explanation': 'Same stepper, trained again with a recorded command and data.', 'excerpt': None}, + {'from': 'recipes/stepper-k2', 'to': 'recipes/stepper-k1', + 'explanation': 'Fine-tuning lowers the rollout error at both horizons.', + 'excerpt': 'k2 halves the median error at horizon 1.'}, + ], + 'track': {'chart': 'charts/rollout-progression', 'benchmark': 'benchmarks/rollout', + 'metric': {'id': 'rmse', 'title': 'Rollout RMSE', 'units': 'm/s', 'better': 'lower'}, + 'statistic': 'median'}, +} + + +def _strip_map_fields(documents): + """The documents without derived_from and compared_with.""" + stripped = copy.deepcopy(documents) + for document in stripped.values(): + document.pop('derived_from', None) + document.pop('compared_with', None) + return stripped + + +# ----------------------------------------------------------- the checker + +class MapFields(check_base.FixtureCopy): + """Section 1: each new error, in the checker's style.""" + + def test_the_fixture_with_every_field_is_valid(self): + report = check_folder(self.project) + self.assertClean(report) + self.assertEqual([group['id'] for group in report.project['groups']], ['steppers', 'fine-tuned']) + + def test_a_folder_without_the_fields_is_valid(self): + self.edit('tuldok.json', '/groups', check_base.DELETE) + self.edit('tuldok.json', '/map', check_base.DELETE) + for name in ('early-fit', 'stepper-k1', 'stepper-k2'): + for field in ('group', 'change', 'derived_from', 'compared_with'): + path = self.project / 'recipes' / f'{name}.json' + if field in json.loads(path.read_text(encoding='utf-8')): + self.edit(f'recipes/{name}.json', f'/{field}', check_base.DELETE) + self.assertClean(check_folder(self.project)) + + def test_a_recipe_group_that_is_no_group(self): + self.edit('recipes/stepper-k1.json', '/group', 'missing') + problem = self.assertProblem(check_folder(self.project), 'recipes/stepper-k1.json', '/group') + self.assertIn("'missing' is not a group of this project", problem.message) + + def test_a_recipe_group_when_the_project_has_no_groups(self): + self.edit('tuldok.json', '/groups', check_base.DELETE) + report = check_folder(self.project) + for name in ('early-fit', 'stepper-k1', 'stepper-k2'): + self.assertProblem(report, f'recipes/{name}.json', '/group', alone=False) + self.assertEqual(len(report.problems), 3) + + def test_a_group_parent_that_is_unknown(self): + self.edit('tuldok.json', '/groups/1/parent', 'nobody') + problem = self.assertProblem(check_folder(self.project), 'tuldok.json', '/groups/1/parent') + self.assertIn("'nobody' is not a group", problem.message) + + def test_a_group_that_is_its_own_parent(self): + self.edit('tuldok.json', '/groups/0/parent', 'steppers') + problem = self.assertProblem(check_folder(self.project), 'tuldok.json', '/groups/0/parent') + self.assertIn('its own ancestor', problem.message) + + def test_a_group_that_is_its_own_ancestor(self): + self.edit('tuldok.json', '/groups/0/parent', 'fine-tuned') + report = check_folder(self.project) + self.assertProblem(report, 'tuldok.json', '/groups/0/parent', alone=False) + self.assertProblem(report, 'tuldok.json', '/groups/1/parent', alone=False) + self.assertEqual(len(report.problems), 2) + + def test_a_group_id_used_twice(self): + self.edit('tuldok.json', '/groups/2', {'id': 'steppers', 'title': 'Again'}) + problem = self.assertProblem(check_folder(self.project), 'tuldok.json', '/groups/2/id') + self.assertIn('used more than once', problem.message) + + def test_group_and_map_fields_follow_the_schema(self): + cases = [ + ('tuldok.json', '/groups/0/colour', 'blue', '/groups/0/colour'), + ('tuldok.json', '/groups/2', {'id': '-bad', 'title': 'Bad'}, '/groups/2/id'), + ('tuldok.json', '/groups/0/title', '', '/groups/0/title'), + ('tuldok.json', '/groups/0/description', 'x' * 2001, '/groups/0/description'), + ('tuldok.json', '/map/size', 3, '/map/size'), + ('tuldok.json', '/map/chart', 'benchmarks/rollout', '/map/chart'), + ('recipes/stepper-k1.json', '/change', 'colour', '/change'), + ('recipes/stepper-k1.json', '/derived_from', 'datasets/waves', '/derived_from'), + ('recipes/stepper-k1.json', '/compared_with/0/explanation', '', '/compared_with/0/explanation'), + ('recipes/stepper-k1.json', '/compared_with/0/note', 'x', '/compared_with/0/note'), + ('recipes/stepper-k1.json', '/compared_with/0/excerpt', 'x' * 2001, '/compared_with/0/excerpt'), + ] + for relative, pointer, value, expected in cases: + with self.subTest(pointer=pointer): + self.setUp() + self.edit(relative, pointer, value) + self.assertProblem(check_folder(self.project), relative, expected) + + def test_more_than_200_groups_or_50_comparisons(self): + self.edit('tuldok.json', '/groups', [{'id': f'g{index}', 'title': 'G'} for index in range(201)] + + [{'id': 'steppers', 'title': 'S'}, {'id': 'fine-tuned', 'title': 'F'}]) + self.assertProblem(check_folder(self.project), 'tuldok.json', '/groups') + self.setUp() + self.edit('recipes/stepper-k1.json', '/compared_with', + [{'recipe': 'recipes/early-fit', 'explanation': 'x'}] * 51) + report = check_folder(self.project) + self.assertProblem(report, 'recipes/stepper-k1.json', '/compared_with', alone=False) + + def test_derived_from_a_recipe_that_does_not_exist(self): + self.edit('recipes/stepper-k1.json', '/derived_from', 'recipes/missing') + problem = self.assertProblem(check_folder(self.project), 'recipes/stepper-k1.json', '/derived_from') + self.assertIn('recipes/missing does not exist', problem.message) + + def test_derived_from_itself(self): + self.edit('recipes/stepper-k1.json', '/derived_from', 'recipes/stepper-k1') + problem = self.assertProblem(check_folder(self.project), 'recipes/stepper-k1.json', '/derived_from') + self.assertIn('cannot be derived from itself', problem.message) + + def test_a_loop_of_derived_from_is_reported_on_each_member(self): + self.edit('recipes/early-fit.json', '/derived_from', 'recipes/stepper-k2') + report = check_folder(self.project) + for name in ('early-fit', 'stepper-k1', 'stepper-k2'): + problem = self.assertProblem(report, f'recipes/{name}.json', '/derived_from', alone=False) + self.assertIn('recipes/early-fit, recipes/stepper-k1, recipes/stepper-k2', problem.message) + self.assertEqual(len(report.problems), 3) + + def test_compared_with_a_recipe_that_does_not_exist(self): + self.edit('recipes/stepper-k2.json', '/compared_with/0/recipe', 'recipes/missing') + self.assertProblem(check_folder(self.project), 'recipes/stepper-k2.json', '/compared_with/0/recipe') + + def test_compared_with_itself(self): + self.edit('recipes/stepper-k2.json', '/compared_with/0/recipe', 'recipes/stepper-k2') + problem = self.assertProblem(check_folder(self.project), 'recipes/stepper-k2.json', '/compared_with/0/recipe') + self.assertIn('cannot be compared with itself', problem.message) + + def test_compared_with_the_same_recipe_twice(self): + self.edit('recipes/stepper-k2.json', '/compared_with/1', {'recipe': 'recipes/stepper-k1', 'explanation': 'x'}) + problem = self.assertProblem(check_folder(self.project), 'recipes/stepper-k2.json', '/compared_with/1/recipe') + self.assertIn('compared more than once', problem.message) + + def test_a_mutual_comparison_is_not_a_cycle(self): + self.edit('recipes/stepper-k1.json', '/compared_with/1', {'recipe': 'recipes/stepper-k2', 'explanation': 'x'}) + self.assertClean(check_folder(self.project)) + + def test_map_chart_must_be_a_progression_chart(self): + self.edit('tuldok.json', '/map/chart', 'charts/rollout-ranking') + problem = self.assertProblem(check_folder(self.project), 'tuldok.json', '/map/chart') + self.assertIn("form 'ranking', not progression", problem.message) + + def test_map_chart_must_exist(self): + self.edit('tuldok.json', '/map/chart', 'charts/missing') + problem = self.assertProblem(check_folder(self.project), 'tuldok.json', '/map/chart') + self.assertIn('charts/missing does not exist', problem.message) + + +# ------------------------------------------------------------- the graph + +class Roles(unittest.TestCase): + """Section 1: the derived and compared roles are edges, and nothing else.""" + + def setUp(self): + self.documents = store_base._fixture_documents() + # A mutual comparison on top of the fixture's. + self.documents['recipes/stepper-k1']['compared_with'].append( + {'recipe': 'recipes/stepper-k2', 'explanation': 'The other way.'}) + + def test_both_roles_are_edges(self): + found = graph.edges(self.documents) + for edge in (graph.Edge('recipes/stepper-k1', 'recipes/early-fit', 'derived'), + graph.Edge('recipes/stepper-k1', 'recipes/early-fit', 'compared'), + graph.Edge('recipes/stepper-k1', 'recipes/stepper-k2', 'compared'), + graph.Edge('recipes/stepper-k2', 'recipes/stepper-k1', 'derived'), + graph.Edge('recipes/stepper-k2', 'recipes/stepper-k1', 'compared')): + self.assertIn(edge, found) + uses = graph.uses(self.documents['recipes/stepper-k1']) + self.assertIn(graph.Use('derived', '/derived_from', 'recipes/early-fit'), uses) + self.assertIn(graph.Use('compared', '/compared_with/1/recipe', 'recipes/stepper-k2'), uses) + + def test_order_cycles_and_states_ignore_them(self): + stripped = _strip_map_fields(self.documents) + self.assertEqual(graph.cycles(self.documents), []) + self.assertEqual(graph.order(self.documents), graph.order(stripped)) + self.assertEqual(graph.states(self.documents), graph.states(stripped)) + self.assertEqual(graph.states(self.documents)['recipes/stepper-k1'], 'not-built') # early-fit is "no" + + def test_a_derived_loop_is_not_a_cycle_of_uses(self): + self.documents['recipes/early-fit']['derived_from'] = 'recipes/stepper-k2' + self.assertEqual(graph.cycles(self.documents), []) + self.assertEqual(graph.derived_loops(self.documents), + [('recipes/early-fit', 'recipes/stepper-k1', 'recipes/stepper-k2')]) + self.assertEqual(graph.derived_loops(store_base._fixture_documents()), []) + self.assertEqual(graph.derived_loops({'recipes/a': {'kind': 'recipe', 'derived_from': 'recipes/a'}}), []) + + def test_the_plan_is_the_same(self): + stripped = _strip_map_fields(self.documents) + targets = plan.every_target(self.documents) + self.assertEqual(plan.make_plan(self.documents, targets), plan.make_plan(stripped, targets)) + + +# ----------------------------------------------------------------- notes + +class Notes(unittest.TestCase): + """read_note: the folder on disk, read as carefully as folder.py reads it.""" + + def setUp(self): + directory = tempfile.TemporaryDirectory() + self.addCleanup(directory.cleanup) + self.folder = Path(directory.name) / 'project' + shutil.copytree(FIXTURE / 'project', self.folder) + self.notes = self.folder / 'notes' + + def refused(self, path): + with self.assertRaises(ProjectError) as caught: + workspace.read_note(self.folder, path) + self.assertEqual(caught.exception.code, 'not-found') + return caught.exception + + def test_a_card(self): + expected = (self.notes / 'fits' / 'early-fit.md').read_text(encoding='utf-8') + self.assertEqual(workspace.read_note(self.folder, 'fits/early-fit.md'), + {'path': 'fits/early-fit.md', 'text': expected}) + + def test_a_missing_file_or_a_directory(self): + self.refused('fits/missing.md') + self.refused('missing/early-fit.md') + self.refused('fits') + + def test_paths_not_in_normal_form(self): + for path in ('../tuldok.json', 'fits/../decisions.md', '/etc/passwd', 'fits//early-fit.md', './decisions.md', + 'fits/', '', 'a\x00b'): + with self.subTest(path=path): + self.refused(path) + + def test_a_link_anywhere_in_the_path(self): + (self.notes / 'linked.md').symlink_to(self.notes / 'decisions.md') + self.refused('linked.md') + (self.notes / 'linked').symlink_to(self.notes / 'fits') + self.refused('linked/early-fit.md') + os.rename(self.notes, self.folder.parent / 'real-notes') + self.notes.symlink_to(self.folder.parent / 'real-notes') + self.refused('decisions.md') + + def test_a_file_over_the_limit(self): + (self.notes / 'big.md').write_bytes(b'a' * (workspace.NOTE_LIMIT + 1)) + self.refused('big.md') + (self.notes / 'full.md').write_bytes(b'a' * workspace.NOTE_LIMIT) + self.assertEqual(len(workspace.read_note(self.folder, 'full.md')['text']), workspace.NOTE_LIMIT) + + def test_bytes_that_are_not_utf8(self): + (self.notes / 'latin.md').write_bytes('café'.encode('latin-1')) + self.assertIn('not UTF-8', str(self.refused('latin.md'))) + + +# ------------------------------------------------------------ the database + +def _append_subject(folder, name, recipe, row): + """Add a benchmark subject for recipe and one ungrouped rmse row to results/rollout.csv, in order.""" + path = folder / 'benchmarks' / 'rollout.json' + document = json.loads(path.read_text(encoding='utf-8')) + document['subjects'].append({'name': name, 'title': name, 'recipe': recipe, 'argument': '{recipe}/model.pt'}) + path.write_text(json.dumps(document, indent=2) + '\n', encoding='utf-8') + results_path = folder / 'results' / 'rollout.csv' + header, *lines = results_path.read_text(encoding='utf-8').splitlines() + lines.append(f'{name},rmse,,{row},{COMMIT},2026-11-02') + lines.sort(key=lambda line: line.split(',')[:3]) + results_path.write_text('\n'.join([header, *lines]) + '\n', encoding='utf-8') + + +def _add_recipe(folder, name, **fields): + document = {'format': 'tuldok_definition_v1', 'kind': 'recipe', 'title': f'Recipe {name}', + 'earlier_work': {'rebuild': 'no', 'reason': 'Test.'}, 'model': 'models/stepper', **fields} + (folder / 'recipes' / f'{name}.json').write_text(json.dumps(document, indent=2) + '\n', encoding='utf-8') + + +class _Counting: + """Counts the statements run on a psycopg connection: every execute goes through a cursor of its factory.""" + + def __init__(self, connection): + counter = self + self.count = 0 + + class Cursor(connection.cursor_factory): + def execute(self, *arguments, **options): + counter.count += 1 + return super().execute(*arguments, **options) + + def executemany(self, *arguments, **options): + counter.count += 1 + return super().executemany(*arguments, **options) + + connection.cursor_factory = Cursor + + +@unittest.skipUnless(DATABASE, 'TULDOK_DATABASE_URL is not set; database tests need a disposable cluster.') +class Map(store_base.StoreCase): + """map and recipe_results on the minimal fixture.""" + + def test_the_fixture(self): + found = workspace.project_map(self.open()) + self.assertEqual(found, FIXTURE_MAP) + json.dumps(found, allow_nan=False) + + def test_a_recipe_under_two_subject_names_and_one_with_no_result(self): + # stepper-k2 is also the subject k2-long, with a better median (0.25 < 0.5) from 3 cases; and a worse one. + _append_subject(self.folder, 'k2-long', 'recipes/stepper-k2', '3,0,0.3,0.25,0.1,0.5,0.1,0.6') + _append_subject(self.folder, 'k2-short', 'recipes/stepper-k2', '2,0,0.9,0.9,0.8,1.0,0.8,1.0') + _add_recipe(self.folder, 'stepper-k3', derived_from='recipes/stepper-k2', change='refinement', + labels={'trained_at': '2026-01-01'}) + found = workspace.project_map(self.open()) + models = {model['reference']: model for model in found['models']} + self.assertEqual((models['recipes/stepper-k2']['value'], models['recipes/stepper-k2']['count']), (0.25, 3)) + self.assertEqual(models['recipes/stepper-k2']['benchmarks'], 1) + k3 = models['recipes/stepper-k3'] + self.assertEqual((k3['value'], k3['count'], k3['benchmarks'], k3['group'], k3['state']), + (None, None, 0, None, 'cannot-rebuild')) + self.assertEqual([model['reference'] for model in found['models']], + ['recipes/stepper-k3', 'recipes/early-fit', 'recipes/stepper-k1', 'recipes/stepper-k2']) + self.assertIn({'from': 'recipes/stepper-k3', 'to': 'recipes/stepper-k2', 'kind': 'derived'}, found['edges']) + self.assertEqual([group['models'] for group in found['groups']], [2, 1]) + + def test_higher_is_better_picks_the_highest(self): + path = self.folder / 'benchmarks' / 'rollout.json' + document = json.loads(path.read_text(encoding='utf-8')) + document['metrics'][0]['better'] = 'higher' + path.write_text(json.dumps(document), encoding='utf-8') + _append_subject(self.folder, 'k2-long', 'recipes/stepper-k2', '3,0,0.3,0.25,0.1,0.5,0.1,0.6') + models = {model['reference']: model for model in workspace.project_map(self.open())['models']} + self.assertEqual(models['recipes/stepper-k2']['value'], 0.5) + + def test_no_track_without_map_chart(self): + path = self.folder / 'tuldok.json' + document = json.loads(path.read_text(encoding='utf-8')) + del document['map'] + path.write_text(json.dumps(document), encoding='utf-8') + found = workspace.project_map(self.open()) + self.assertIsNone(found['track']) + self.assertEqual({model['value'] for model in found['models']}, {None}) + self.assertEqual([model['benchmarks'] for model in found['models']], [1, 1, 1]) + + def test_a_change_to_tuldok_json_alone_is_imported(self): + self.close(self.open()) + path = self.folder / 'tuldok.json' + document = json.loads(path.read_text(encoding='utf-8')) + document['groups'][0]['title'] = 'Every stepper' + path.write_text(json.dumps(document), encoding='utf-8') + self.assertEqual(workspace.project_map(self.open())['groups'][0]['title'], 'Every stepper') + + def test_an_edit_naming_an_unknown_group_is_refused(self): + project = self.open() + text = (self.folder / 'recipes' / 'stepper-k1.json').read_text(encoding='utf-8') + with self.assertRaises(ProjectError) as caught: + project.set_definition('recipes/stepper-k1', text.replace('"group": "steppers"', '"group": "nobody"')) + self.assertEqual([(p.path, p.pointer) for p in caught.exception.problems], + [('recipes/stepper-k1.json', '/group')]) + + def test_uses_and_used_by_show_the_new_edges(self): + shown = self.open().definition('recipes/stepper-k1') + self.assertIn({'reference': 'recipes/early-fit', 'role': 'derived'}, shown['uses']) + self.assertIn({'reference': 'recipes/early-fit', 'role': 'compared'}, shown['uses']) + self.assertIn({'reference': 'recipes/stepper-k2', 'role': 'derived'}, shown['used_by']) + self.assertIn({'reference': 'recipes/stepper-k2', 'role': 'compared'}, shown['used_by']) + + def test_the_number_of_queries_does_not_grow_with_the_recipes(self): + project = self.open() + counting = _Counting(project._connection) + self.assertEqual(workspace.project_map(project), FIXTURE_MAP) + few = counting.count + self.close(project) + for index in range(8): + _add_recipe(self.folder, f'more-{index}', group='steppers', change='component', + derived_from='recipes/stepper-k1', + compared_with=[{'recipe': 'recipes/stepper-k2', 'explanation': 'x'}]) + _append_subject(self.folder, f'more-{index}', f'recipes/more-{index}', '1,0,1,1,1,1,1,1') + project = self.open() + counting = _Counting(project._connection) + found = workspace.project_map(project) + self.assertEqual(len(found['models']), 11) + self.assertEqual(counting.count, few) + self.assertGreater(few, 0) + + def test_recipe_results(self): + project = self.open() + found = workspace.recipe_results(project, 'recipes/stepper-k1') + self.assertEqual(found['benchmarks'], ['rollout']) + self.assertEqual([(row['benchmark'], row['subject'], row['metric'], row['group']) for row in found['rows']], + [('rollout', 'stepper-k1', 'rmse', ''), ('rollout', 'stepper-k1', 'seconds', '')]) + self.assertEqual(found['rows'][0], { + 'benchmark': 'rollout', 'subject': 'stepper-k1', 'metric': 'rmse', 'group': '', 'count': 8, + 'unavailable': 0, 'mean': 1.25, 'median': 0.875, 'p10': 0.425, 'p90': 2.65, 'min': 0.25, 'max': 3.0, + 'commit': COMMIT, 'produced': '2026-11-02T10:15:00Z', 'origin': 'file'}) + grouped = workspace.recipe_results(project, 'recipes/stepper-k1', 'horizon') + self.assertEqual([row['group'] for row in grouped['rows']], ['horizon=1', 'horizon=8']) + self.assertEqual(workspace.recipe_results(project, 'recipes/stepper-k1', 'nothing')['rows'], []) + for missing in ('recipes/missing', 'models/stepper', 'nonsense'): + with self.assertRaises(ProjectError) as caught: + workspace.recipe_results(project, missing) + self.assertEqual(caught.exception.code, 'not-found') + + def test_recipe_results_under_two_names_and_with_none(self): + _append_subject(self.folder, 'k2-long', 'recipes/stepper-k2', '3,0,0.3,0.25,0.1,0.5,0.1,0.6') + _add_recipe(self.folder, 'stepper-k3') + project = self.open() + found = workspace.recipe_results(project, 'recipes/stepper-k2') + self.assertEqual([(row['subject'], row['metric']) for row in found['rows']], + [('k2-long', 'rmse'), ('stepper-k2', 'rmse'), ('stepper-k2', 'seconds')]) + self.assertEqual(workspace.recipe_results(project, 'recipes/stepper-k3'), {'rows': [], 'benchmarks': []}) + + +@unittest.skipUnless(DATABASE, 'TULDOK_DATABASE_URL is not set; database tests need a disposable cluster.') +class Operations(store_base.StoreCase): + """The three operations through Service.call, for an inspect credential.""" + + def setUp(self): + super().setUp() + patcher = mock.patch.dict(os.environ, {local.HOME_VARIABLE: str(self.temporary / 'home')}) + patcher.start() + self.addCleanup(patcher.stop) + self.service = Service(self.folder) + self.addCleanup(self.service.close) + + def call(self, name, arguments): + result = self.service.call(name, arguments, INSPECTOR) + json.dumps(result, allow_nan=False) + return result + + def refused(self, name, arguments, actor=INSPECTOR): + with self.assertRaises(ProjectError) as caught: + self.service.call(name, arguments, actor) + return caught.exception.code + + def test_map(self): + self.assertEqual(self.call('map', {}), FIXTURE_MAP) + self.assertEqual(self.refused('map', {}, NOBODY), 'forbidden') + self.assertEqual(self.refused('map', {'extra': 1}), 'invalid') + + def test_note(self): + found = self.call('note', {'path': 'fits/early-fit.md'}) + self.assertEqual(found['text'], (self.folder / 'notes/fits/early-fit.md').read_text(encoding='utf-8')) + self.assertEqual(self.refused('note', {'path': '../tuldok.json'}), 'not-found') + self.assertEqual(self.refused('note', {'path': 'missing.md'}), 'not-found') + self.assertEqual(self.refused('note', {}), 'invalid') + self.assertEqual(self.refused('note', {'path': 'decisions.md'}, NOBODY), 'forbidden') + + def test_note_does_not_open_the_project(self): + with mock.patch('tuldok_project.builds.opened', side_effect=AssertionError('opened')): + self.assertEqual(self.call('note', {'path': 'decisions.md'})['path'], 'decisions.md') + + def test_recipe_results(self): + found = self.call('recipe_results', {'recipe': 'recipes/early-fit'}) + self.assertEqual(found['benchmarks'], ['rollout']) + self.assertEqual(len(found['rows']), 2) + self.assertEqual(len(self.call('recipe_results', {'recipe': 'early-fit', 'group': 'horizon'})['rows']), 2) + self.assertEqual(self.refused('recipe_results', {'recipe': 'recipes/missing'}), 'not-found') + self.assertEqual(self.refused('recipe_results', {}), 'invalid') + + def test_none_writes_activity(self): + self.call('map', {}) + self.call('note', {'path': 'decisions.md'}) + self.call('recipe_results', {'recipe': 'recipes/early-fit'}) + self.assertEqual(self.service.call('activity', {}, INSPECTOR)['total'], 0) + + +def _run(*arguments, home): + environment = dict(os.environ, PYTHONDONTWRITEBYTECODE='1', **{local.HOME_VARIABLE: str(home)}) + return subprocess.run([sys.executable, '-m', 'tuldok_project', *map(str, arguments)], cwd=REPOSITORY, + env=environment, capture_output=True, text=True, timeout=120) + + +@unittest.skipUnless(DATABASE, 'TULDOK_DATABASE_URL is not set; database tests need a disposable cluster.') +class Commands(store_base.StoreCase): + + def test_map(self): + done = _run('map', self.folder, home=self.temporary / 'home') + self.assertEqual(done.returncode, 0, done.stderr) + lines = done.stdout.splitlines() + self.assertEqual(lines[0].split(), ['group', 'models', 'training-policy', 'architecture', 'refinement', + 'component', 'no', 'kind']) + self.assertEqual(lines[1].split(), ['Steppers', '2', '1', '1', '0', '0', '0']) + self.assertEqual(lines[2].split(), ['Fine-tuned', 'steppers', '1', '0', '0', '1', '0', '0']) + self.assertEqual(lines[3].split(), ['total', '3', '1', '1', '1', '0', '0']) + self.assertIn('3 lines (2 derived, 1 input), 2 comparisons.', done.stdout) + self.assertIn('Track charts/rollout-progression on benchmarks/rollout: rmse: median Rollout RMSE (m/s), ' + 'lower is better; 3 of 3 models have a value.', done.stdout) + shown = _run('map', self.folder, '--json', home=self.temporary / 'home') + self.assertEqual(json.loads(shown.stdout), FIXTURE_MAP) + + def test_note(self): + done = _run('note', self.folder, 'fits/early-fit.md', home=self.temporary / 'home') + self.assertEqual(done.returncode, 0, done.stderr) + self.assertEqual(done.stdout, (self.folder / 'notes/fits/early-fit.md').read_text(encoding='utf-8')) + missing = _run('note', self.folder, '../tuldok.json', home=self.temporary / 'home') + self.assertEqual((missing.returncode, missing.stdout), (1, '')) + self.assertIn("There is no note '../tuldok.json'", missing.stderr) + self.assertEqual(_run('note', self.folder, home=self.temporary / 'home').returncode, 2) + + +# ------------------------------------------------------- building as before + +class BuildsAsBefore(builds_base.BuildCase): + """A derivation and a mutual comparison change nothing about building (section 1).""" + + def add_map_fields(self): + for name, fields in (('fit-a', {'compared_with': [{'recipe': 'recipes/fit-b', 'explanation': 'A to b.'}]}), + ('fit-b', {'derived_from': 'recipes/fit-a', + 'compared_with': [{'recipe': 'recipes/fit-a', 'explanation': 'B to a.'}]})): + path = self.folder / 'recipes' / f'{name}.json' + document = json.loads(path.read_text(encoding='utf-8')) + document.update(fields) + path.write_text(json.dumps(document, indent=2) + '\n', encoding='utf-8') + self.commit('Map fields.') + + def shape(self, made): + return [(step['reference'], step['action'], step['reasons'], step.get('subjects')) for step in made['steps']] + + def covered(self, made): + with self.opened() as project: + return build_requests.covers(project, made, [], every=True, scratch=False)['steps'] + + def test_plan_covers_order_and_build_are_unchanged(self): + before = self.plan(every=True) + covers_before = self.covered(before) + with self.opened() as project: + order_before = project.order() + self.add_map_fields() + after = self.plan(every=True) + self.assertEqual(self.shape(after), self.shape(before)) + self.assertEqual(self.covered(after), covers_before) + with self.opened() as project: + self.assertEqual(project.order(), order_before) + self.assertIn({'reference': 'recipes/fit-a', 'role': 'derived'}, + project.definition('recipes/fit-b')['uses']) + self.assertIn({'reference': 'recipes/fit-b', 'role': 'compared'}, + project.definition('recipes/fit-a')['used_by']) + done = builds_base.builds.execute(self.folder, after, confirm=lambda _plan: True) + self.assertTrue(done) + states = self.states() + for reference in ('datasets/numbers', 'recipes/fit-a', 'recipes/fit-b'): + self.assertEqual(states[reference], 'built', reference) + self.assertEqual(self.plan(every=True)['counts']['build'], 0) + + +if __name__ == '__main__': + unittest.main() diff --git a/tuldok_project/__main__.py b/tuldok_project/__main__.py index 86955a51..831fcf48 100644 --- a/tuldok_project/__main__.py +++ b/tuldok_project/__main__.py @@ -24,6 +24,10 @@ only for a moment (waiting while a build has it open) and read the run's logs with it closed. `estimate` runs the build steps' estimate commands, the one command besides `build` that runs project code; `plan` shows what it stored. +`map` prints the project's map (workspace.py): its groups with how many +models of each kind of change they hold, the lines, the comparisons and the +track, from the database only. `note` prints one file under notes/, read +from the folder on disk without the database. `requests`, `approve` and `decline` work on the build requests asked through the app (build_requests.py); approving and declining act as the owner, as the actor "command line", and write an activity row each. An approved @@ -73,6 +77,10 @@ def _parser(): new.add_argument('--code-root', default='.', metavar='PATH', help="the code root, relative to the folder (default '.')") new.add_argument('--json', action='store_true', help='print one JSON document') + note = commands.add_parser('note', help='print one file under the notes directory of a project folder', + description='Print one file under the notes directory of a project folder.') + note.add_argument('folder', help='the project folder (the one holding tuldok.json)') + note.add_argument('path', help='the path relative to notes/, for example fits/early-fit.md') database = argparse.ArgumentParser(add_help=False) database.add_argument('folder', help='the project folder (the one holding tuldok.json)') @@ -101,6 +109,7 @@ def add(name, parents, help_text): graph = add('graph', [reading], 'print the definitions with their state and the uses between them') graph.add_argument('--order', action='store_true', help='print the build order instead') add('status', [reading], 'list unsaved edits and files changed on disk since the last import') + add('map', [reading], 'print the groups with their models by kind of change, the lines, comparisons and track') setting = add('set', [opening], 'replace or add a definition in the database (not saved to the folder)') setting.add_argument('reference', help='for example recipes/pilot-dense-k1') setting.add_argument('file', help='the file holding the new definition text') @@ -509,6 +518,58 @@ def _chart(project, arguments): return 0 +_CHANGES = ('training-policy', 'architecture', 'refinement', 'component') + + +def _map(project, arguments): + from . import workspace + + drawn = workspace.project_map(project) + if arguments.json: + _json(drawn) + return 0 + + def counted(title, models): + kinds = [sum(1 for model in models if model['change'] == kind) for kind in _CHANGES] + return (title, len(models), *kinds, len(models) - sum(kinds)) + + models = drawn['models'] + rows = [('group', 'models', *_CHANGES, 'no kind')] + rows += [counted(group['title'], [model for model in models if model['group'] == group['id']]) + for group in drawn['groups']] + known = {group['id'] for group in drawn['groups']} + outside = [model for model in models if model['group'] not in known] + if outside: + rows.append(counted('(no group)', outside)) + rows.append(counted('total', models)) + _columns(rows) + print() + derived = sum(1 for edge in drawn['edges'] if edge['kind'] == 'derived') + print(f'{_plural(len(drawn["edges"]), "line")} ({derived} derived, {len(drawn["edges"]) - derived} input), ' + f'{_plural(len(drawn["comparisons"]), "comparison")}.') + track = drawn['track'] + if track is None: + print('No track: tuldok.json names no chart of the form progression in map.chart.') + else: + valued = sum(1 for model in models if model['value'] is not None) + print(f'Track {track["chart"]} on {track["benchmark"]}: {_metric_words(track["metric"], track["statistic"])}; ' + f'{valued} of {_plural(len(models), "model")} have a value.') + return 0 + + +def _note(arguments): + from . import workspace + from .store import ProjectError + + try: + shown = workspace.read_note(os.path.realpath(arguments.folder), arguments.path) + except ProjectError as exc: + print(str(exc), file=sys.stderr) + return 1 + sys.stdout.write(shown['text'] if shown['text'].endswith('\n') or not shown['text'] else shown['text'] + '\n') + return 0 + + def _report(project, arguments): from . import charts @@ -1380,7 +1441,7 @@ def _adopt(project, arguments): return 0 -_STORE_COMMANDS = {'open': _open, 'list': _list, 'show': _show, 'graph': _graph, 'status': _status, +_STORE_COMMANDS = {'open': _open, 'list': _list, 'show': _show, 'graph': _graph, 'status': _status, 'map': _map, 'set': _set, 'remove': _remove, 'save': _save, 'results': _results, 'values': _values, 'import-values': _import_values, 'chart': _chart, 'report': _report, 'plan': _plan, 'environments': _environments, 'connect': _connect, 'check-environment': _check_environment, @@ -1536,6 +1597,8 @@ def main(argv=None): arguments = _parser().parse_args(argv) # exits with status 2 on a usage error if arguments.command == 'check': return _check(arguments) + if arguments.command == 'note': + return _note(arguments) if arguments.command in ('home', 'new'): from .local import SettingsError diff --git a/tuldok_project/check.py b/tuldok_project/check.py index 3314b4e2..f626501e 100644 --- a/tuldok_project/check.py +++ b/tuldok_project/check.py @@ -5,8 +5,10 @@ that are neither layout (folder.py), single-field syntax (documents.py and the schemas) nor summary-file content (results.py): kind against directory, cards, placeholders in context, benchmark uniqueness rules, references and named -outputs, charts against their benchmark, cycles, and paths into the code root -(in definitions and in the code_paths of tuldok.json). +outputs, charts against their benchmark, cycles, paths into the code root +(in definitions and in the code_paths of tuldok.json), and the map's fields +(spec-w1.md section 1): groups, a recipe's group, derived_from and +compared_with, and map.chart. Problems are collected, never raised, so one bad file never hides another. """ from dataclasses import dataclass, field @@ -70,6 +72,7 @@ def add(severity, path, pointer, message): check_references(definitions, add) check_charts(definitions, unsound, add) check_cycles(definitions, add) + check_map(project, definitions, add) _check_results(read.results, definitions, unsound, add) problems.sort(key=lambda p: (p.path, p.pointer, _SEVERITY_ORDER.get(p.severity, 2), p.message)) @@ -313,11 +316,88 @@ def check_cycles(definitions, add): listed = ', '.join(group) for reference in group: definition = definitions[reference] - pointer = next((use.pointer for use in graph.uses(definition.document) if use.target in members), '') + pointer = next((use.pointer for use in graph.uses(definition.document) + if use.target in members and use.role not in graph.MAP_ROLES), '') add('error', definition.path, pointer, f'This definition is in a cycle of uses ({listed}); remove one of the references to break it.') +def _group_problems(groups, add): + """Report repeated group ids, unknown parents and groups that are their own ancestor; return the ids.""" + parents, ids = {}, set() + for index, group in enumerate(groups): + if not isinstance(group, dict) or not isinstance(group.get('id'), str): + continue + if group['id'] in ids: + add('error', folder_reader.PROJECT_FILE, documents.pointer('groups', index, 'id'), + f'The group id {group["id"]!r} is used more than once; give each group its own id.') + continue + ids.add(group['id']) + if isinstance(group.get('parent'), str): + parents[group['id']] = (index, group['parent']) + for group_id, (index, parent) in parents.items(): + where = documents.pointer('groups', index, 'parent') + if parent not in ids: + add('error', folder_reader.PROJECT_FILE, where, + f'The parent {parent!r} is not a group of this project; use the id of another group or remove parent.') + continue + seen, current = set(), parent + while current != group_id and current in parents and current not in seen: + seen.add(current) + current = parents[current][1] + if current == group_id: + add('error', folder_reader.PROJECT_FILE, where, + f'The group {group_id!r} is its own ancestor through parent; change a parent to break the loop.') + return ids + + +def check_map(project, definitions, add): + """Report the map's fields (spec-w1.md section 1): groups, recipe group, derived_from, compared_with, map.chart. + + project is the decoded tuldok.json, or None, in which case the rules that + need it (groups, a recipe's group, map.chart) are skipped. A reference to + a missing recipe is check_references' problem. + """ + groups = project.get('groups') if isinstance(project, dict) else None + ids = _group_problems(groups, add) if isinstance(groups, list) else set() + for reference, definition in definitions.items(): + document = definition.document + if definition.kind != 'recipe' or not isinstance(document, dict): + continue + group = document.get('group') + if project is not None and isinstance(group, str) and group not in ids: + add('error', definition.path, '/group', + f'{group!r} is not a group of this project; use the id of a group in tuldok.json or add the group there.') + if document.get('derived_from') == reference: + add('error', definition.path, '/derived_from', + 'A recipe cannot be derived from itself; name the recipe it was branched from or remove derived_from.') + compared = document.get('compared_with') + if isinstance(compared, list): + for index, value in _first_repeats(compared, 'recipe'): + add('error', definition.path, documents.pointer('compared_with', index, 'recipe'), + f'{value} is compared more than once; keep one entry for it.') + for index, item in enumerate(compared): + if isinstance(item, dict) and item.get('recipe') == reference: + add('error', definition.path, documents.pointer('compared_with', index, 'recipe'), + 'A recipe cannot be compared with itself; name another recipe or remove the entry.') + decoded = {reference: d.document for reference, d in definitions.items() if d.document is not None} + for loop in graph.derived_loops(decoded): + listed = ', '.join(loop) + for reference in loop: + add('error', definitions[reference].path, '/derived_from', + f'Following derived_from from here comes back here ({listed}); remove one derived_from to break the loop.') + chart = project.get('map', {}).get('chart') if isinstance(project, dict) and isinstance(project.get('map'), dict) else None + if isinstance(chart, str) and documents.parse_reference(chart) is not None and chart.startswith('charts/'): + target = definitions.get(chart) + if target is None: + add('error', folder_reader.PROJECT_FILE, '/map/chart', + f'{chart} does not exist; name a chart of the form progression or add {chart}.json.') + elif isinstance(target.document, dict) and target.document.get('form') != 'progression': + add('error', folder_reader.PROJECT_FILE, '/map/chart', + f'{chart} has the form {target.document.get("form")!r}, not progression; ' + 'name a chart of the form progression.') + + def _check_results(files, definitions, unsound, add): for file in files: name = file.path[len('results/'):-len('.csv')] diff --git a/tuldok_project/documents.py b/tuldok_project/documents.py index 06f426ee..f4174780 100644 --- a/tuldok_project/documents.py +++ b/tuldok_project/documents.py @@ -32,7 +32,9 @@ KINDS = {directory: kind for kind, directory in DIRECTORIES.items()} # Which directories each reference-taking field accepts (2.6, 2.7). The keys -# are the edge roles of 2.9 without their ":" suffix. +# are the edge roles of 2.9 without their ":" suffix, and the two roles +# of a recipe's place on the map (spec-w1.md section 1): derived_from and +# compared_with. ACCEPTS = { 'input': ('datasets', 'recipes', 'steps'), 'environment': ('environments',), @@ -40,6 +42,8 @@ 'subject': ('recipes',), 'cases': ('datasets',), 'benchmark': ('benchmarks',), + 'derived': ('recipes',), + 'compared': ('recipes',), } STATISTICS = ('mean', 'median', 'p10', 'p90', 'min', 'max') diff --git a/tuldok_project/graph.py b/tuldok_project/graph.py index a35e59e4..a9e39c35 100644 --- a/tuldok_project/graph.py +++ b/tuldok_project/graph.py @@ -5,13 +5,20 @@ 'datasets/x') to decoded document. Documents need not be valid: fields of the wrong type are skipped, so the graph can be read even from a folder with problems. Edges whose target is not in `definitions` are kept by edges() and uses() but -ignored by order() and cycles(). +ignored by order() and cycles(). The two roles of a recipe's place on the map +(spec-w1.md section 1), derived and compared, are edges like the others for +uses(), edges() and users_of(), but say nothing about building: order() and +cycles() ignore them (a comparison may run both ways) and states() carries +nothing over them. """ from dataclasses import dataclass import heapq from . import documents +# Roles that record how recipes relate on the map, not what a build needs. +MAP_ROLES = ('derived', 'compared') + @dataclass(frozen=True, order=True) class Edge: @@ -55,6 +62,12 @@ def uses(document): kind = document.get('kind') if kind == 'recipe' and isinstance(document.get('model'), str): found.append(Use('model', '/model', document['model'])) + if kind == 'recipe' and isinstance(document.get('derived_from'), str): + found.append(Use('derived', '/derived_from', document['derived_from'])) + if kind == 'recipe' and isinstance(document.get('compared_with'), list): + for index, item in enumerate(document['compared_with']): + if isinstance(item, dict) and isinstance(item.get('recipe'), str): + found.append(Use('compared', documents.pointer('compared_with', index, 'recipe'), item['recipe'])) if kind == 'benchmark': subjects = document.get('subjects') if isinstance(subjects, list): @@ -86,10 +99,10 @@ def edges(definitions): def _adjacency(definitions): - """Return {reference: sorted targets} restricted to references present in definitions.""" + """Return {reference: sorted targets} restricted to references present in definitions, map roles left out.""" adjacency = {reference: set() for reference in definitions} for edge in edges(definitions): - if edge.to_ref in adjacency: + if edge.to_ref in adjacency and edge.role not in MAP_ROLES: adjacency[edge.from_ref].add(edge.to_ref) return {reference: sorted(targets) for reference, targets in adjacency.items()} @@ -145,6 +158,29 @@ def cycles(definitions): return sorted(groups) +def derived_loops(definitions): + """Return each loop of derived_from among definitions (two or more recipes), as sorted tuples, sorted. + + A recipe that names itself is not a loop here: the checker reports it on its own. + """ + parent = {} + for edge in edges(definitions): + if edge.role == 'derived' and edge.to_ref in definitions and edge.to_ref != edge.from_ref: + parent[edge.from_ref] = edge.to_ref + done, loops = set(), [] + for start in sorted(parent): + path, position = [], {} + current = start + while current in parent and current not in done and current not in position: + position[current] = len(path) + path.append(current) + current = parent[current] + if current in position: + loops.append(tuple(sorted(path[position[current]:]))) + done.update(path) + return sorted(loops) + + def order(definitions): """Return every reference with each one after everything it uses; ties broken by reference string. diff --git a/tuldok_project/operations.py b/tuldok_project/operations.py index 59aac19b..279a0b64 100644 --- a/tuldok_project/operations.py +++ b/tuldok_project/operations.py @@ -1,6 +1,7 @@ """The operations a served project folder offers, as data: names, who may call them, arguments and results. -Owns the table of section 2 of docs/plans/definition-first-projects/spec-m7.md. +Owns the table of section 2 of docs/plans/definition-first-projects/spec-m7.md, with the three +rows of section 2 of spec-w1.md (map, note, recipe_results). Each Operation names one operation project., the rule its caller must satisfy (who), whether it changes anything (mutation), a closed JSON Schema of its arguments and the result keys that are always present. service.py checks @@ -119,6 +120,15 @@ def _arguments(required=(), **properties): False, _arguments(['request'], request=_REQUEST), REQUEST + ('runs',)), Operation('activity', 'List the changes asked of this project through the interface, newest first, and how ' 'each ended.', 'inspect', False, _arguments(offset=_OFFSET, limit=_limit(500)), ('items', 'total')), + Operation('map', 'Read the map of the project: its groups, every recipe as a model with its group, kind of ' + 'change, state and track value, the lines between them and the comparisons.', 'inspect', False, + _arguments(), ('groups', 'models', 'edges', 'comparisons', 'track')), + Operation('note', 'Read one file under the notes directory of the project folder, given relative to it.', + 'inspect', False, _arguments(['path'], path={'type': 'string', 'minLength': 1, 'maxLength': 1024}), + ('path', 'text')), + Operation('recipe_results', "Read the summary rows of every benchmark subject made from one recipe, ungrouped " + 'or for one group.', 'inspect', False, _arguments(['recipe'], recipe=_REFERENCE, group=_TEXT), + ('rows', 'benchmarks')), Operation('set_definition', "Check a definition's text and keep it as an unsaved edit.", 'edit', True, _arguments(['reference', 'text'], reference=_REFERENCE, text=_TEXT), DEFINITION), Operation('remove_definition', 'Mark a definition that nothing uses as removed, until the project is saved.', diff --git a/tuldok_project/schemas/project.schema.json b/tuldok_project/schemas/project.schema.json index b9903669..a516d388 100644 --- a/tuldok_project/schemas/project.schema.json +++ b/tuldok_project/schemas/project.schema.json @@ -40,6 +40,59 @@ "minLength": 1, "maxLength": 1024 } + }, + "groups": { + "type": "array", + "maxItems": 200, + "description": "0 to 200 groups, in the order their sections are shown", + "items": { + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "title" + ], + "properties": { + "id": { + "$ref": "#/$defs/group_id" + }, + "title": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "parent": { + "$ref": "#/$defs/group_id" + }, + "description": { + "type": "string", + "maxLength": 2000 + } + } + } + }, + "map": { + "type": "object", + "additionalProperties": false, + "required": [ + "chart" + ], + "properties": { + "chart": { + "type": "string", + "pattern": "^charts/[a-z0-9][a-z0-9._-]{0,119}$", + "description": "a reference to a chart of the form progression, such as charts/" + } + } + } + }, + "$defs": { + "group_id": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]*$", + "description": "a group id of letters, digits, '_', '.' or '-' that starts with a letter or digit, at most 64 characters" } } } diff --git a/tuldok_project/schemas/recipe.schema.json b/tuldok_project/schemas/recipe.schema.json index 055a32a3..7a886aa5 100644 --- a/tuldok_project/schemas/recipe.schema.json +++ b/tuldok_project/schemas/recipe.schema.json @@ -47,6 +47,50 @@ "type": "string", "pattern": "^models/[a-z0-9][a-z0-9._-]{0,119}$", "description": "a reference to a model, such as models/" + }, + "group": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]*$", + "description": "the id of one of the project's groups: letters, digits, '_', '.' or '-', starting with a letter or digit, at most 64 characters" + }, + "change": { + "enum": [ + "training-policy", + "architecture", + "refinement", + "component" + ] + }, + "derived_from": { + "$ref": "#/$defs/recipe_reference" + }, + "compared_with": { + "type": "array", + "maxItems": 50, + "items": { + "type": "object", + "additionalProperties": false, + "required": [ + "recipe", + "explanation" + ], + "properties": { + "recipe": { + "$ref": "#/$defs/recipe_reference" + }, + "explanation": { + "type": "string", + "minLength": 1, + "maxLength": 2000 + }, + "excerpt": { + "type": "string", + "maxLength": 2000 + } + } + } } }, "if": { @@ -333,6 +377,11 @@ "environment" ] } + }, + "recipe_reference": { + "type": "string", + "pattern": "^recipes/[a-z0-9][a-z0-9._-]{0,119}$", + "description": "a reference to a recipe, such as recipes/" } } } diff --git a/tuldok_project/service.py b/tuldok_project/service.py index a49938d7..0112e1ea 100644 --- a/tuldok_project/service.py +++ b/tuldok_project/service.py @@ -34,7 +34,7 @@ import psycopg from . import (activity, build_requests, builds, charts, check, environments, launcher, local, operations, plan, - store) + store, workspace) from .documents import Problem CHECK_PROBLEMS = 200 @@ -405,6 +405,18 @@ def _activity(self, arguments, actor): return activity.items(project._connection, project.schema, arguments.get('offset', 0), arguments.get('limit', 100)) + def _map(self, arguments, actor): + with self._open() as project: + return workspace.project_map(project) + + def _note(self, arguments, actor): + return workspace.read_note(self.folder, arguments['path']) # from disk; the project is not opened + + def _recipe_results(self, arguments, actor): + recipe = 'recipes/' + _bare(arguments['recipe'], 'recipes') + with self._open() as project: + return workspace.recipe_results(project, recipe, arguments.get('group')) + # ------------------------------------------------------------- changes def _set_definition(self, arguments, actor): diff --git a/tuldok_project/store.py b/tuldok_project/store.py index 3c8ec28a..35f135ce 100644 --- a/tuldok_project/store.py +++ b/tuldok_project/store.py @@ -25,6 +25,9 @@ The record of changes asked through the service (spec-m7.md section 5) lives in one more table owned by activity, and the build requests (section 4) in one owned by build_requests. +The state row also keeps tuldok.json as last imported (spec-w1.md: the map's +groups and track are read from it); a change to it alone imports the folder +again, and the chart its map.chart names cannot be removed. """ from dataclasses import dataclass import hashlib @@ -66,7 +69,8 @@ *result_rows.TABLES, ) # Later additive changes go here as ALTER TABLE ... ADD COLUMN IF NOT EXISTS. -_MIGRATIONS = () +# state.project: tuldok.json as last imported, for the map's groups and track (spec-w1.md). +_MIGRATIONS = ('ALTER TABLE {schema}.state ADD COLUMN IF NOT EXISTS project jsonb',) _UPSERT = '''INSERT INTO {schema}.definitions (directory, name, kind, title, text, document, file_sha256, unsaved, removed) @@ -247,8 +251,11 @@ def _notes(root): return found.notes -def _cross_problems(merged, unsound=frozenset()): - """Problems across files (references, named outputs, charts, cycles) for {reference: Definition}.""" +def _cross_problems(merged, unsound=frozenset(), project=None): + """Problems across files (references, named outputs, charts, cycles, the map's fields) for {reference: Definition}. + + project is the decoded tuldok.json; without it the map rules that need it are skipped. + """ problems = [] def add(severity, path, pointer, message): @@ -257,6 +264,7 @@ def add(severity, path, pointer, message): check.check_references(merged, add) check.check_charts(merged, set(unsound), add) check.check_cycles(merged, add) + check.check_map(project, merged, add) return problems @@ -328,10 +336,11 @@ def _create_schema(self): self._execute(statement) def _state(self): - row = self._execute('SELECT project_id, name, folder, code_root, imported_at FROM {schema}.state').fetchone() + row = self._execute('SELECT project_id, name, folder, code_root, imported_at, project ' + 'FROM {schema}.state').fetchone() if row is None: return None - return dict(zip(('project_id', 'name', 'folder', 'code_root', 'imported_at'), row)) + return dict(zip(('project_id', 'name', 'folder', 'code_root', 'imported_at', 'project'), row)) def _documents(self, *, removed=True): """{reference: document} for every row (with removed=False, only rows not removed).""" @@ -390,7 +399,8 @@ def _attach(self, root, project, *, rebind, on_conflict): if (state is not None and not listing.irregular and listing.files == on_disk and not results_irregular and {name: _sha(raw) for name, raw in results_on_disk.items()} == recorded_results - and state['name'] == project['name'] and state['code_root'] == code_root): + and state['name'] == project['name'] and state['code_root'] == code_root + and state['project'] == project): if state['folder'] != root: self._execute('UPDATE {schema}.state SET folder = %s', (root,)) return @@ -433,7 +443,7 @@ def _import(self, root, rows, on_conflict, results_on_disk, recorded_results): else: merged[reference] = _definition(reference, text, documents.decode(text)) if kept: - problems = _errors(_cross_problems(merged)) + problems = _errors(_cross_problems(merged, project=report.project)) if problems: raise ProjectError('The folder no longer fits the unsaved edits held here; ' 'save or discard them first.', 'invalid', problems=problems) @@ -473,12 +483,14 @@ def _import(self, root, rows, on_conflict, results_on_disk, recorded_results): for name, text in changed_results.items(): result_rows.import_file(self._connection, self.schema, name, text, merged[documents.reference('benchmarks', name)].document) - self._execute('''INSERT INTO {schema}.state (singleton, project_id, name, folder, code_root, imported_at) - VALUES (true, %s, %s, %s, %s, now()) + self._execute('''INSERT INTO {schema}.state (singleton, project_id, name, folder, code_root, imported_at, + project) + VALUES (true, %s, %s, %s, %s, now(), %s) ON CONFLICT (singleton) DO UPDATE SET project_id = EXCLUDED.project_id, name = EXCLUDED.name, folder = EXCLUDED.folder, - code_root = EXCLUDED.code_root, imported_at = EXCLUDED.imported_at''', - (self.project_id, project['name'], root, project.get('code_root', '.'))) + code_root = EXCLUDED.code_root, imported_at = EXCLUDED.imported_at, + project = EXCLUDED.project''', + (self.project_id, project['name'], root, project.get('code_root', '.'), Jsonb(project))) def _results_to_import(self, disk, merged, results_on_disk, recorded_results): """({benchmark: text} of new or changed results files, [benchmarks whose file is gone]). @@ -620,7 +632,7 @@ def add(severity, where, pointer, message): with self._connection.transaction(): merged = self._merged_definitions() merged[reference] = candidate - errors = alone + _errors(_cross_problems(merged, {path} if alone else ())) + errors = alone + _errors(_cross_problems(merged, {path} if alone else (), state['project'])) if errors: raise ProjectError(f'{reference} cannot be set; see the problems.', 'invalid', problems=errors, references=[reference]) @@ -640,6 +652,8 @@ def add(severity, where, pointer, message): def remove_definition(self, reference): """Mark a definition removed, to be deleted from disk by save(); refused while anything uses it. + The chart that tuldok.json names in map.chart counts as used. + Removing an environment also drops its record on this machine (an installed directory is left where it is); removing anything drops its runs and products records (their directories are left where they are). @@ -653,6 +667,9 @@ def remove_definition(self, reference): raise ProjectError(f'There is no definition {reference}.', 'not-found', references=[reference]) users = [source for (source,) in self._execute( 'SELECT DISTINCT from_ref FROM {schema}.edges WHERE to_ref = %s ORDER BY 1', (reference,))] + project = self._state()['project'] or {} + if isinstance(project.get('map'), dict) and project['map'].get('chart') == reference: + users.append(folder_reader.PROJECT_FILE) # its map.chart (spec-w1.md section 1) if users: raise ProjectError(f'{reference} is used by {", ".join(users)}; change those first.', 'in-use', references=users) diff --git a/tuldok_project/workspace.py b/tuldok_project/workspace.py new file mode 100644 index 00000000..0040a387 --- /dev/null +++ b/tuldok_project/workspace.py @@ -0,0 +1,216 @@ +"""What the Map workspace reads: the map of a project, one note, and one recipe's results. + +Owns section 2 of docs/plans/definition-first-projects/spec-w1.md. project_map +answers from the definitions, tuldok.json as last imported (store's state +row), the build and environment states and the summary rows, with the same +few queries however many recipes there are; it reads no file of the folder. +read_note reads one file under notes/ straight from the folder, the way +folder.py reads: through directory descriptors that refuse links, a +regular file of at most NOTE_LIMIT bytes, strict UTF-8; it opens no project. +recipe_results reads the summary rows of every benchmark subject made from +one recipe. +""" +import dataclasses +import os + +from psycopg import sql + +from . import builds, charts, documents, environments, folder as folder_reader, graph, result_rows, results +from .store import ProjectError, _REFERENCE_SQL + +NOTE_LIMIT = 1024 * 1024 + + +def _labels(document): + labels = document.get('labels') + return labels if isinstance(labels, dict) else {} + + +def _text(value): + return value if isinstance(value, str) and value else None + + +def _better(metric, value, best): + """True when value beats best by the metric's better (none counts as lower is better, as in charts).""" + return best is None or (value > best if metric['better'] == 'higher' else value < best) + + +def _subject_recipes(benchmark): + """{subject name: recipe reference} for the subjects of a benchmark document that name a recipe.""" + subjects = benchmark.get('subjects') if isinstance(benchmark.get('subjects'), list) else [] + return {item['name']: item['recipe'] for item in subjects + if isinstance(item, dict) and isinstance(item.get('name'), str) and isinstance(item.get('recipe'), str)} + + +def _track(project, chart_reference, definitions): + """(track, {recipe: (value, count)}) for map.chart, or (None, {}) when the chart is not a usable progression.""" + chart = definitions.get(chart_reference) if isinstance(chart_reference, str) else None + chart = chart and chart['document'] + if not isinstance(chart, dict) or chart.get('form') != 'progression': + return None, {} + benchmark = definitions.get(chart.get('benchmark')) + if benchmark is None: + return None, {} + statistic = chart.get('statistic', charts.DEFAULT_STATISTIC) + if statistic not in results.STATISTICS: + return None, {} + metric = charts._metric(benchmark['document'], chart['metric']) + name = chart['benchmark'].split('/', 1)[1] + recipes = _subject_recipes(benchmark['document']) + rows = project._connection.execute( + sql.SQL("SELECT subject, count, {statistic} FROM {schema}.result_summaries " + "WHERE benchmark = %s AND metric = %s AND grp = ''").format( + statistic=sql.Identifier(statistic), schema=sql.Identifier(project.schema)), + (name, metric['id'])).fetchall() + values = {} + for subject, count, value in sorted(rows, key=lambda row: row[0]): + recipe = recipes.get(subject) + if recipe is None or count <= 0 or value is None: + continue + if _better(metric, value, values.get(recipe, (None,))[0]): + values[recipe] = (value, count) + track = {'chart': chart_reference, 'benchmark': chart['benchmark'], 'metric': metric, 'statistic': statistic} + return track, values + + +def project_map(project): + """The map of an open project (spec-w1.md section 2): groups, models, edges, comparisons and the track.""" + rows = project._execute(f'SELECT {_REFERENCE_SQL}, kind, title, document FROM {{schema}}.definitions ' + 'WHERE NOT removed').fetchall() + definitions = {reference: {'kind': kind, 'title': title, 'document': document} + for reference, kind, title, document in rows} + documents_by_reference = {reference: item['document'] for reference, item in definitions.items()} + state = project._state() + tuldok = state['project'] or {} + status = builds.status(project) + local = {**environments.recorded_states(project._connection, project.schema), + **{reference: entry['state'] for reference, entry in status.items()}} + states = graph.states(documents_by_reference, local) + + map_block = tuldok.get('map') if isinstance(tuldok.get('map'), dict) else {} + track, values = _track(project, map_block.get('chart'), definitions) + + subjects = {} # (benchmark name, subject) -> recipe + for reference, item in definitions.items(): + if item['kind'] == 'benchmark': + for subject, recipe in _subject_recipes(item['document']).items(): + subjects[reference.split('/', 1)[1], subject] = recipe + with_rows = {} + for benchmark, subject in project._execute('SELECT DISTINCT benchmark, subject FROM {schema}.result_summaries'): + recipe = subjects.get((benchmark, subject)) + if recipe is not None: + with_rows.setdefault(recipe, set()).add(benchmark) + + recipes = sorted(reference for reference, item in definitions.items() if item['kind'] == 'recipe') + models = [] + for reference in recipes: + document = definitions[reference]['document'] + value, count = values.get(reference, (None, None)) + models.append({ + 'reference': reference, 'title': definitions[reference]['title'], + 'short': _text(_labels(document).get('short')), + 'group': _text(document.get('group')), 'change': _text(document.get('change')), + 'derived_from': _text(document.get('derived_from')), + 'trained_at': _text(_labels(document).get('trained_at')), + 'state': states[reference], 'adopted': bool((status.get(reference) or {}).get('adopted')), + 'card': _text(document.get('card')), 'value': value, 'count': count, + 'benchmarks': len(with_rows.get(reference, ())), + }) + models.sort(key=lambda model: (model['trained_at'] is None, model['trained_at'] or '', model['reference'])) + + recipe_documents = {reference: definitions[reference]['document'] for reference in recipes} + edges = [] + for edge in graph.edges(recipe_documents): + if edge.to_ref not in recipe_documents: + continue + kind = 'derived' if edge.role == 'derived' else 'input' if edge.role.startswith('input:') else None + if kind is not None and {'from': edge.from_ref, 'to': edge.to_ref, 'kind': kind} not in edges: + edges.append({'from': edge.from_ref, 'to': edge.to_ref, 'kind': kind}) + + comparisons = [] + for reference in recipes: + compared = recipe_documents[reference].get('compared_with') + for item in compared if isinstance(compared, list) else []: + if isinstance(item, dict) and isinstance(item.get('recipe'), str): + comparisons.append({'from': reference, 'to': item['recipe'], 'explanation': item.get('explanation'), + 'excerpt': item.get('excerpt')}) + + counts = {} + for model in models: + if model['group'] is not None: + counts[model['group']] = counts.get(model['group'], 0) + 1 + groups = [{'id': group['id'], 'title': group['title'], 'parent': group.get('parent'), + 'description': group.get('description'), 'models': counts.get(group['id'], 0)} + for group in tuldok.get('groups', []) if isinstance(group, dict)] + return {'groups': groups, 'models': models, 'edges': edges, 'comparisons': comparisons, 'track': track} + + +def read_note(folder, path): + """{path, text} of notes/ in the folder on disk; ProjectError not-found for anything else. + + path is relative to notes/ and in normal form. Every directory on the + way and the file itself are opened without following a link; the file + must be regular, at most NOTE_LIMIT bytes and UTF-8. + """ + def refused(why): + return ProjectError(f'There is no note {path!r}: {why}', 'not-found', references=[str(path)]) + + wrong = documents.relative_path_problem(path) + if wrong: + raise refused(f'the path {wrong}.') + *directories, name = path.split('/') + try: + fd = os.open(os.fspath(folder), os.O_RDONLY | os.O_DIRECTORY | os.O_CLOEXEC) + except OSError as exc: + raise refused(f'the project folder cannot be opened ({exc.strerror}).') from None + try: + for part in (folder_reader.NOTES, *directories): + try: + child = os.open(part, folder_reader.DIRECTORY_FLAGS, dir_fd=fd) + except OSError: + raise refused(f'{part} is not a directory of the folder (a link is not followed).') from None + os.close(fd) + fd = child + try: + raw = folder_reader.read(fd, name, NOTE_LIMIT) + except folder_reader.Unsafe as exc: + raise refused(str(exc)) from None + finally: + os.close(fd) + try: + text = raw.decode('utf-8') + except UnicodeDecodeError as exc: + raise refused(f'the file is not UTF-8 text (bad byte at offset {exc.start}).') from None + return {'path': path, 'text': text} + + +def recipe_results(project, recipe, group=None): + """{rows, benchmarks}: the summary rows of every benchmark subject made from recipe (spec-w1.md section 2). + + group None means the ungrouped rows only; a key, the rows grouped by that + one key (as the results operation reads it). benchmarks names the + benchmarks with a subject made from recipe, whether or not it has rows. + """ + parsed = documents.parse_reference(recipe) + found = project._execute("SELECT 1 FROM {schema}.definitions WHERE directory = 'recipes' AND name = %s " + 'AND NOT removed', (parsed[1],)).fetchone() if parsed and parsed[0] == 'recipes' else None + if found is None: + raise ProjectError(f'There is no recipe {recipe}.', 'not-found', references=[recipe]) + pairs = [] + for name, document in project._execute("SELECT name, document FROM {schema}.definitions " + "WHERE directory = 'benchmarks' AND NOT removed ORDER BY name"): + pairs += [(name, subject) for subject, used in sorted(_subject_recipes(document).items()) if used == recipe] + where, parameters = ['(benchmark, subject) IN (SELECT * FROM unnest(%s::text[], %s::text[]))'], \ + [[benchmark for benchmark, _ in pairs], [subject for _, subject in pairs]] + if group is None or group == '': + where.append("grp = ''") + else: + where.append("left(grp, length(%s) + 1) = %s || '=' AND strpos(grp, ';') = 0") + parameters += [group, group] + query = (result_rows._SELECT_SUMMARY.replace('SELECT ', 'SELECT benchmark, ', 1) + ' WHERE ' + ' AND '.join(where) + + ' ORDER BY benchmark COLLATE "C", subject COLLATE "C", metric COLLATE "C", grp COLLATE "C"') + rows = [] + for record in project._execute(query, parameters): + stored = result_rows._stored(record[1:]) + rows.append({'benchmark': record[0], **dataclasses.asdict(stored.row), 'origin': stored.origin}) + return {'rows': rows, 'benchmarks': sorted({benchmark for benchmark, _ in pairs})} From 5d3981674b0f319ff8f478e253dcaaef49166ec8 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 12 Nov 2026 11:10:17 -0700 Subject: [PATCH 041/131] docs(plan): record the interface review, the link repair and Map phase 1 in the ledger Co-Authored-By: Claude Fable 5.2 --- .../execution-ledger.md | 44 +++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/docs/plans/definition-first-projects/execution-ledger.md b/docs/plans/definition-first-projects/execution-ledger.md index 332a65cc..49726ddc 100644 --- a/docs/plans/definition-first-projects/execution-ledger.md +++ b/docs/plans/definition-first-projects/execution-ledger.md @@ -386,3 +386,47 @@ The clone was not built: that needs the reference solver and the dataset generat **Left as they are:** `scripts/track_project_results.py` and `scripts/extract_model_recipes.py`, which served the old format and which nothing current refers to; the historical plans and the migration scripts under `experiments/model-portfolio-migration-v1/` that name the old folder; the README's link to the older `tuldok/` folder, which a reader may confuse with the project. **Next:** deleting the old project mode from Tuldok. It waits for the owner to sign the [capability check](capability-check.md). + +## 2026-11-12 — the owner looks at the interface; the Map workspace plan + +**What happened.** The owner asked to see the project open in the Tuldok interface. Tuldok was started on the lab folder in the new project-folder mode, whose only page is the report. The owner: "wtf happened to tuldoks ui? It doesnt have any of the pages it used to have." Started again the way it had been run before (`--project-files-root`), it showed the form-panel project page; the owner: "that is not the GUI it had before either", and described tabs along the top, a bench page and a model page with a horizontal ancestry tree. That is the Map layout of [the workspace redesign](../project-workspace-redesign/README.md), chosen on 2026-11-03, which exists only as mockups run from disk and was never part of the app. Shown the mockup, the owner confirmed: "yes, thts the gui i remember". + +**What this changes.** Nothing had been deleted, but the new format has no real screens, and that was not made plain before the owner looked. [The Map workspace plan](workspace-plan.md) builds the Map layout into the app in three phases; the owner approved it the same day ("the plan looks good") with its three recommended decisions. The old project mode is not deleted before phase 3 is accepted, which replaces the earlier advice to sign the capability check. + +**A fault found and repaired.** Adoption had hard-linked 2,407 files of the old project folder into Tuldok's project directory. The old project code refuses a stored file that has a second name ("Artifact source must be an ordinary file without hard-link aliases"), so those weights and training data would have been refused by the old mode. Each was replaced in Tuldok's directory by a real copy, compared byte for byte, and every file of the old folder has one name again. Cost: 15.9 GB on the OrangeCream disk. The old lab project was then opened in the old mode to check: it opened, in 166 s. The files' change times moved, so the old mode re-verifies them on first read. Adoption by link stays the command's default; a source that another tool manages should be adopted with `--copy`. + +**Commits** (none pushed), Tuldok: the plan `55a5ac68`; the brief and mockups, without the baked data file, `4af5a74a`. + +## 2026-11-12 — the Map workspace, phase 1: what the map reads + +**Owner instruction:** "the plan looks good". Spec: [spec-w1.md](spec-w1.md). + +**Commits** (none pushed). Tuldok `feat/definition-first-projects`: spec `ecca58d1`; the fields and operations `a4047b68`. Lab `reorg/reproducible-lab-20261102`: the fields on the lab's models `d9e8960a0`. + +| Slice | What | Tests | +| --- | --- | --- | +| T17 | `groups` and `map.chart` in `tuldok.json`; `group`, `change`, `derived_from`, `compared_with` on a recipe; the checker's rules; graph roles `derived` and `compared`; `tuldok_project/workspace.py` with the operations `map`, `note`, `recipe_results`; the commands `map` and `note` | 47 new; 554 in all, about 4 minutes | +| L6 | the lab's converter writes the fields; `scripts/earlier-model-map.json`; a ninth chart for the track; the folder regenerated | 44 in the lab's converter tests | + +**As built, beyond the spec:** + +- The kind of change is `change` on a recipe, not a field of a group as the plan first said: in the mockup one group holds 31 architecture and 20 refinement models. +- `derived_from` was added. The plan had lines come only from recorded inputs; a model branched from another without taking its weights has no such input, and "Branch from here" needs the field. +- `tuldok.json` is now kept in the database (a new column of the state row), so `map` reads no file; a change to `tuldok.json` alone now imports the folder again. +- Removing the chart that `map.chart` names is refused. +- `note` takes a path relative to `notes/`; a recipe's `card` value starts with `notes/`. + +**Acceptance on the lab** (throwaway database): + +| Check | Result | +| --- | --- | +| `map` through the service | 0.04 s, 133 KiB: 206 models, 19 groups, 43 derived and 63 input lines, 26 comparisons | +| Kinds | 48 training policy, 95 architecture, 36 refinement, 26 component, 1 with none (the new pilot model) | +| Track | worst pressure error on the 128 consumed requests; 150 of 206 models have a value | +| C53 | 36 models derived from it; its card read by `note` (28,684 characters); `recipe_results` gives 15 rows over 3 benchmarks | +| The plan for everything, on an empty machine | unchanged: 17 to build, 243 blocked | +| The lab folder | `tuldok.json` and 205 recipes changed, one chart added, the notes file removed; every other file byte-identical; checker 0 errors and the same 8 warnings | + +**Starting values to correct.** Kinds, parents and short labels were carried from the mockup, which inferred kinds and parents from card text: 128 models have a short label, 43 a parent (36 from C53, 4 from C37, 3 from C44). The group "Pressure proposal fits" has no model of its own, only child groups. + +**Next:** phase 2, the page, read-only. From e7eae1942bdd7a39e0b85fa35e82e07f5566d8b0 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 12 Nov 2026 11:12:19 -0700 Subject: [PATCH 042/131] docs(plan): specify the Map workspace, phase 2: the page, read-only Co-Authored-By: Claude Fable 5.2 --- .../definition-first-projects/spec-w2.md | 56 +++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 docs/plans/definition-first-projects/spec-w2.md diff --git a/docs/plans/definition-first-projects/spec-w2.md b/docs/plans/definition-first-projects/spec-w2.md new file mode 100644 index 00000000..369a8489 --- /dev/null +++ b/docs/plans/definition-first-projects/spec-w2.md @@ -0,0 +1,56 @@ +# Implementation spec: the Map workspace, phase 2: the page, read-only + +This is phase 2 of [the Map workspace plan](workspace-plan.md); [spec-w1.md](spec-w1.md) is phase 1. Section 1 of [spec-m1-m2.md](spec-m1-m2.md) (rules for implementers) applies, with the import rule as amended by [spec-m7.md](spec-m7.md). + +**The reference is the mockup the owner chose and remembers:** `docs/plans/project-workspace-redesign/mockups/b-map.html` with `shared/base.css`, `tree.js`, `charts.js` and `screens.js`, its brief `docs/plans/project-workspace-redesign/README.md`, and the picture `mockups/preview/b.png`. The page built here must be recognisably that screen: the same top bar, tabs, status strip, map, list, drawer, type, colour and spacing. What changes is where the content comes from. + +**Done when:** Tuldok started with `--project-folder` on the lab folder opens to the map with the lab's 206 models in their sections and lanes, their lines, comparisons and accuracy track; a model opens its card in the drawer; the Benchmarks, Train, Data, Analysis and Overview tabs show the project's real content; every tab is captured in a headless browser in light and dark with no script error; and nothing on the page changes the project. + +## 1. Decisions + +- **The mockup's code is the starting point, not a picture to imitate.** Its shell, style sheet, map, charts and screens are copied into `static/` and changed only where the content's shape differs or where a part is not in this phase. The mockup read one baked object, `window.LAB`; the page builds what the screens read from the project's operations. +- **The page replaces the stand-in report page** for `/`, `/workspaces` and `/workbench` in folder mode. `static/project-folder.html`, `.js` and `.css` are removed. The report stays reachable as a link on the Overview tab. +- **Not in this phase:** Annotate (no tab); Branch from here, planned models and every other control that changes something (phase 3: such controls are not drawn, not drawn disabled); studies; the record browser and volume viewer; field slices; the Stages and Ledger layouts and the layout switch; anything the mockup generated for layout only (training curves, per-case field errors, illustrative "needs you" items, reference sizes). +- **Where the project has nothing, the screen says so in a sentence** and draws no placeholder data. +- **No build step, no framework, no external reference**, and no markup made from project text: text reaches the page through text nodes. A model's card is Markdown; it is shown by a small renderer of the page's own that makes headings, paragraphs, emphasis, lists, tables and code from it as elements. +- **Type.** Ubuntu Sans and Ubuntu Sans Mono are vendored under `static/vendor/ubuntu-sans/` with their licence, as the brief says, when the files are on the machine and allowed by that licence; otherwise the page uses the installed faces with the brief's fallbacks and the report says so. +- **Signing in** uses the existing `auth.js`. Its identity and buttons sit in the top bar's right side, styled with the page's own tokens in both themes. + +## 2. What each part reads + +One addition to phase 1: each model of `map` also has `description`, the first 300 characters of the recipe's description cut at a word. + +| Part | Reads | Shows | +| --- | --- | --- | +| Top bar | `summary` | the project's name, the tabs Map, Data, Train, Benchmarks, Analysis, Overview, the theme control, the session | +| Status strip | `summary`, `status`, `build_requests`, `environments`, `runs` | one computed sentence of where the project stands (how many models are built, to build and cannot be rebuilt; what is running), when it was read, and "Needs you" with a count | +| Needs you | the same | a list, each item a sentence: a build request awaiting approval, files changed on disk or unsaved edits, an environment not ready, a definition whose last run ended badly, a worker that is elsewhere or stopped. No buttons in this phase | +| Map | `map` | sections from the groups that have models; a model's lane from what it was derived from; solid lines for derivations and inputs; the faint line for order; dashed arcs for the selected model's comparisons with the excerpt on hover; colour by kind of change, with the kind always named; the accuracy track from the track's values; the minimap; filters by kind and by text; the list under the map with each model's short label, title, description, kind and a bar for its track value | +| Drawer | `definition`, `note`, `recipe_results`, `runs`, `products` for the selected model | title, state, kind, group, what it was derived from and what derives from it, its comparisons, its results across benchmarks, its runs and product, then its card | +| Benchmarks | `results_overview`, `definitions` of kind benchmark and chart, `chart`, `results` | a benchmark picker; the coverage line (how many models have a result there); the benchmark's charts by their form (accuracy against time with the frontier, error along the sequence, ranking, comparison), drawn by the page from chart data so points can be hovered and focused; the all-models table, sortable; a compare set of up to three models with their values side by side | +| Train | `definitions` of kind recipe, `runs`, `build_requests`, `environments`, `progress` | models not built yet; build requests with their state; runs newest first with state, time and device, and for a running one its latest progress as a hairline and a line of text; environments with their state | +| Data | `definitions` of kind dataset, `products` | a card per dataset: title, state, whether its files were adopted, their size and count, what uses it; opening one shows its definition and its files' paths | +| Analysis | `results_overview`, `values` | a benchmark and model picker, then the per-case values as a table and a strip of one mark per case | +| Overview | `summary`, `definitions`, `environments`, `activity` | counts by kind and state, the environments, the latest activity, and a link that opens the report page | + +**Refreshing.** The page reads once when opened and when the window regains focus. While a build request is queued or running it asks again every two seconds for what can change (`summary`, `runs`, `build_requests`, and `progress` of a running run), and stops when nothing runs. + +**Speed.** The first screen needs `summary` and `map` only; the other tabs read when first opened; a card reads when its model is opened. + +## 3. The lab folder + +A model's list row shows its description. The lab's converter wrote the same conversion sentence into every earlier recipe's description. It now leads with the card's **Purpose** paragraph when the card has one, followed by the sentences it wrote before. + +## 4. Checking the page + +- **HTTP tests** in `tests/test_tuldok_project_http.py`: the page and each of its files are served in folder mode and nothing else is at `/`; the stand-in's paths are gone. +- **A browser check**, `tests/browser_project_workspace.cjs`, in the way of the existing `tests/browser_*.cjs` checks: starts the app on a fixture project with results (and, given `--lab-root`, on a copy of the lab folder), signs in, opens every tab in light and dark at 1440 by 900, opens a model, hovers a map node, sorts the table, and fails on any script error, failed request, sideways overflow or empty main area. It writes its screenshots where the other checks write theirs. +- The orchestrating session runs the browser check on the lab folder and looks at every screenshot against the mockup's. + +## 5. Slices + +| Slice | Files | Notes | +| --- | --- | --- | +| T18 shell and map | `static/project-workspace.html`, `static/project-workspace/` (style, map, the adapter, the Map and Overview screens, the drawer, the status strip and Needs you), the vendored faces, the asset rows in `app.py`, `description` in `workspace.py`, the removal of the stand-in page, the HTTP tests, the browser check for these parts | first | +| T19 other tabs | Benchmarks, Train, Data, Analysis in `static/project-workspace/`, the browser check extended to them | after T18 | +| L7 lab | `lab:scripts/build_tuldok_project.py`, its tests, the regenerated descriptions | beside T18 | From 1f66f5a01ac860c104972f8d27d43c15148269ec Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 12 Nov 2026 11:51:10 -0700 Subject: [PATCH 043/131] feat(app): the Map workspace is the page of a project folder The Map layout chosen on 2026-11-03, until now a mockup run from disk, replaces the stand-in report page. Its shell, style, map and drawer are the mockup's, reading the project's operations in place of a baked data file: the top bar and tabs, the status strip with what needs the owner, the map with sections, lanes, lines, comparisons, minimap and track, the list under it, and a drawer with a model's results, runs and card. The Overview tab shows counts, environments, activity and the report. Nothing on the page changes the project. Benchmarks, Train, Data and Analysis follow. Ubuntu Sans is vendored with its licence. A browser check opens every tab in light and dark on a fixture or on a real project. Co-Authored-By: Claude Fable 5.2 --- app.py | 18 +- static/project-folder.css | 17 - static/project-folder.html | 26 -- static/project-folder.js | 68 --- static/project-workspace.html | 34 ++ static/project-workspace/adapter.js | 173 ++++++++ static/project-workspace/app.js | 137 ++++++ static/project-workspace/base.css | 408 ++++++++++++++++++ static/project-workspace/charts.js | 68 +++ static/project-workspace/markdown.js | 222 ++++++++++ static/project-workspace/screens.js | 221 ++++++++++ static/project-workspace/tree.js | 280 ++++++++++++ static/vendor/ubuntu-sans/LICENCE.txt | 108 +++++ .../UbuntuSans-Italic[wdth,wght].ttf | Bin 0 -> 738444 bytes .../UbuntuSansMono-Italic[wght].ttf | Bin 0 -> 186356 bytes .../ubuntu-sans/UbuntuSansMono[wght].ttf | Bin 0 -> 230324 bytes .../ubuntu-sans/UbuntuSans[wdth,wght].ttf | Bin 0 -> 1080900 bytes tests/browser_project_workspace.cjs | 296 +++++++++++++ tests/test_tuldok_project_http.py | 66 ++- tests/test_tuldok_project_workspace.py | 43 +- tuldok_project/workspace.py | 19 +- 21 files changed, 2071 insertions(+), 133 deletions(-) delete mode 100644 static/project-folder.css delete mode 100644 static/project-folder.html delete mode 100644 static/project-folder.js create mode 100644 static/project-workspace.html create mode 100644 static/project-workspace/adapter.js create mode 100644 static/project-workspace/app.js create mode 100644 static/project-workspace/base.css create mode 100644 static/project-workspace/charts.js create mode 100644 static/project-workspace/markdown.js create mode 100644 static/project-workspace/screens.js create mode 100644 static/project-workspace/tree.js create mode 100644 static/vendor/ubuntu-sans/LICENCE.txt create mode 100644 static/vendor/ubuntu-sans/UbuntuSans-Italic[wdth,wght].ttf create mode 100644 static/vendor/ubuntu-sans/UbuntuSansMono-Italic[wght].ttf create mode 100644 static/vendor/ubuntu-sans/UbuntuSansMono[wght].ttf create mode 100644 static/vendor/ubuntu-sans/UbuntuSans[wdth,wght].ttf create mode 100644 tests/browser_project_workspace.cjs diff --git a/app.py b/app.py index 663f4bd9..95fe3508 100644 --- a/app.py +++ b/app.py @@ -984,11 +984,21 @@ def _get(self): }) if getattr(dataset, 'project_files_mode', False) and path in ('/', '/workspaces', '/workbench'): path = '/project-files' - assets.update({'/project-folder': ('project-folder.html', 'text/html'), - '/project-folder.js': ('project-folder.js', 'text/javascript'), - '/project-folder.css': ('project-folder.css', 'text/css')}) + assets.update({'/project-workspace': ('project-workspace.html', 'text/html'), + '/project-workspace/base.css': ('project-workspace/base.css', 'text/css'), + '/project-workspace/adapter.js': ('project-workspace/adapter.js', 'text/javascript'), + '/project-workspace/charts.js': ('project-workspace/charts.js', 'text/javascript'), + '/project-workspace/markdown.js': ('project-workspace/markdown.js', 'text/javascript'), + '/project-workspace/tree.js': ('project-workspace/tree.js', 'text/javascript'), + '/project-workspace/screens.js': ('project-workspace/screens.js', 'text/javascript'), + '/project-workspace/app.js': ('project-workspace/app.js', 'text/javascript'), + '/static/vendor/ubuntu-sans/UbuntuSans[wdth,wght].ttf': ('vendor/ubuntu-sans/UbuntuSans[wdth,wght].ttf', 'font/ttf'), + '/static/vendor/ubuntu-sans/UbuntuSans-Italic[wdth,wght].ttf': ('vendor/ubuntu-sans/UbuntuSans-Italic[wdth,wght].ttf', 'font/ttf'), + '/static/vendor/ubuntu-sans/UbuntuSansMono[wght].ttf': ('vendor/ubuntu-sans/UbuntuSansMono[wght].ttf', 'font/ttf'), + '/static/vendor/ubuntu-sans/UbuntuSansMono-Italic[wght].ttf': ('vendor/ubuntu-sans/UbuntuSansMono-Italic[wght].ttf', 'font/ttf'), + '/static/vendor/ubuntu-sans/LICENCE.txt': ('vendor/ubuntu-sans/LICENCE.txt', 'text/plain')}) if getattr(dataset, 'project_folder_mode', False) and path in ('/', '/workspaces', '/workbench'): - path = '/project-folder' + path = '/project-workspace' if path in assets: name, kind = assets[path] return self.reply((ROOT / 'static' / name).read_bytes(), content_type=kind + '; charset=utf-8') diff --git a/static/project-folder.css b/static/project-folder.css deleted file mode 100644 index 66c91489..00000000 --- a/static/project-folder.css +++ /dev/null @@ -1,17 +0,0 @@ -:root{color-scheme:light dark;--bg:#f5f6f8;--panel:#fff;--ink:#172333;--muted:#4c5b6c;--line:#b9c3cf;--accent:#1648a2;--error:#8a1720} -@media(prefers-color-scheme:dark){:root{--bg:#10171f;--panel:#19232e;--ink:#ecf0f5;--muted:#b7c5d5;--line:#647487;--accent:#99bbff;--error:#ffabb2}} -*{box-sizing:border-box} -body{margin:0;background:var(--bg);color:var(--ink);font:16px/1.5 system-ui,sans-serif} -main{max-width:1200px;margin:0 auto;padding:1.5rem 1rem 3rem} -.eyebrow{margin:0;font-size:.85rem;text-transform:uppercase;letter-spacing:.08em;color:var(--muted)} -h1{margin:.2rem 0;line-height:1.15;font-size:clamp(1.6rem,3.5vw,2.4rem);overflow-wrap:anywhere} -.folder{margin:.2rem 0 .8rem;color:var(--muted);font-family:ui-monospace,monospace;font-size:.9rem;overflow-wrap:anywhere} -button{font:inherit;padding:.45rem .8rem;cursor:pointer;border:1px solid var(--accent);border-radius:.3rem;color:var(--accent);background:var(--panel)} -button:disabled{opacity:.5;cursor:default} -:focus-visible{outline:3px solid var(--accent);outline-offset:3px} -#project-error{padding:.8rem;border:2px solid var(--error);color:var(--error);background:var(--panel);overflow-wrap:anywhere} -#project-report{display:block;width:100%;height:calc(100vh - 12rem);min-height:24rem;border:1px solid var(--line);border-radius:.4rem;background:var(--panel)} -.session-bar{background:var(--panel);color:var(--ink);border-bottom:1px solid var(--line)} -#session-dialog{background:var(--panel);color:var(--ink);border-color:var(--line)} -#session-token{font:inherit;padding:.4rem;color:var(--ink);background:var(--bg);border:1px solid var(--line);border-radius:.3rem} -[hidden]{display:none!important} diff --git a/static/project-folder.html b/static/project-folder.html deleted file mode 100644 index 55e4dfe4..00000000 --- a/static/project-folder.html +++ /dev/null @@ -1,26 +0,0 @@ - - - - - - Project · Tuldok - - - - - - - -

-
-

Tuldok / project folder

-

Project

-

- -
-

Reading the project…

- - -
- - diff --git a/static/project-folder.js b/static/project-folder.js deleted file mode 100644 index 0130f7ec..00000000 --- a/static/project-folder.js +++ /dev/null @@ -1,68 +0,0 @@ -'use strict'; -// A served project folder: its name and folder, and its report. Contract -// versions and hashes are read from /api/agent/capabilities, never pinned here. -(() => { - const $ = id => document.getElementById(id); - const dark = window.matchMedia('(prefers-color-scheme: dark)'); - let contracts = null, loading = false; - - async function json(response) { - const value = await response.json(); - if (!response.ok) throw Error(value.error || 'The request was refused.'); - return value; - } - - async function selection(name) { - if (!contracts) { - const manifest = await json(await window.TuldokAuth.fetch('/api/agent/capabilities', {cache: 'no-store'})); - contracts = new Map(manifest.operations.map(operation => { - const newest = operation.contracts.reduce((a, b) => (b.version > a.version ? b : a)); - return [operation.id, operation.id + '/' + newest.version + '/' + newest.sha256]; - })); - } - if (!contracts.has(name)) throw Error('This Tuldok does not offer ' + name + '.'); - return contracts.get(name); - } - - async function call(name, body) { - const response = await window.TuldokAuth.fetch('/api/project/' + name, { - method: 'POST', cache: 'no-store', - headers: {'Content-Type': 'application/json', 'Tuldok-Operation-Contract': await selection('project.' + name)}, - body: JSON.stringify(body)}); - return json(response); - } - - async function load() { - if (loading) return; - loading = true; - $('project-reload').disabled = true; - $('project-error').hidden = true; - $('project-status').textContent = 'Reading the project…'; - try { - const summary = await call('summary', {}); - $('project-name').textContent = summary.name; - document.title = summary.name + ' · Tuldok'; - $('project-folder').textContent = summary.folder; - const report = await call('report', {theme: dark.matches ? 'dark' : 'light'}); - $('project-report').srcdoc = report.html; - $('project-status').textContent = 'Read at ' + new Date().toLocaleTimeString() + '.'; - } catch (error) { - contracts = null; - $('project-status').textContent = ''; - $('project-error').textContent = error.message; - $('project-error').hidden = false; - } finally { - loading = false; - $('project-reload').disabled = false; - } - } - - function start() { - $('project-reload').addEventListener('click', load); - dark.addEventListener('change', load); - window.addEventListener('tuldok-session', load); - load(); - } - if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', start, {once: true}); - else start(); -})(); diff --git a/static/project-workspace.html b/static/project-workspace.html new file mode 100644 index 00000000..5c2f7dbc --- /dev/null +++ b/static/project-workspace.html @@ -0,0 +1,34 @@ + + + + + + +Map · Tuldok + + + + + + + + + + + + +Skip to content +
+ t.Tuldok +

+ +
+
+
+
+
+ + +
+ + diff --git a/static/project-workspace/adapter.js b/static/project-workspace/adapter.js new file mode 100644 index 00000000..0750bdb8 --- /dev/null +++ b/static/project-workspace/adapter.js @@ -0,0 +1,173 @@ +'use strict'; +// The page's one way to the project. It calls the project's operations +// (POST /api/project/) with the contract the server publishes at +// /api/agent/capabilities (never pinned here), keeps each answer until it is +// read again, and shapes what the screens read: the map's sections, models +// and lines, the sentence of where the project stands, and what needs the +// person. It only reads: no operation that changes the project is called. +window.TuldokProject = (() => { + // Kinds of change, by the project format's names, with the brief's labels. + const KINDS = [ + { id: 'training-policy', label: 'Training policy' }, + { id: 'architecture', label: 'Architecture' }, + { id: 'refinement', label: 'Refinement' }, + { id: 'component', label: 'Component' } + ]; + const UNSET = 'unset'; // the class and filter key of a model without a kind of change + const kindLabel = id => (KINDS.find(k => k.id === id) || { label: 'Kind not set' }).label; + // A model's state, as a word and the tone of its mark. + const STATES = { + built: ['built', 'good'], running: ['running', 'pending'], 'out-of-date': ['out of date', 'warn'], + failed: ['failed', 'serious'], 'not-built': ['not built', 'neutral'], 'needs-work': ['needs work', 'warn'], + 'cannot-rebuild': ['cannot be rebuilt', 'neutral'], none: ['nothing to build', 'neutral'], + ready: ['ready', 'good'], failing: ['failing', 'serious'], 'not-set-up': ['not set up', 'warn'] + }; + const stateWord = s => (STATES[s] || [s || 'unknown', 'neutral']); + const ENDED_BADLY = { failed: 'failed', 'timed-out': 'ran out of time', 'over-disk': 'went over its disk budget', unknown: 'ended in an unknown state' }; + + // ---- Calls -------------------------------------------------------------- + let contracts = null; + async function json(response) { + let value; + try { value = await response.json(); } catch (e) { throw Error('The server answered ' + response.status + ' without JSON.'); } + if (!response.ok) throw Object.assign(Error(value.error || 'The request was refused.'), { code: value.code }); + return value; + } + async function selection(name) { + if (!contracts) { + const manifest = await json(await window.TuldokAuth.fetch('/api/agent/capabilities', { cache: 'no-store' })); + contracts = new Map(manifest.operations.map(operation => { + const newest = operation.contracts.reduce((a, b) => (b.version > a.version ? b : a)); + return [operation.id, operation.id + '/' + newest.version + '/' + newest.sha256]; + })); + } + if (!contracts.has(name)) throw Error('This Tuldok does not offer ' + name + '.'); + return contracts.get(name); + } + async function call(name, body = {}) { + try { + const response = await window.TuldokAuth.fetch('/api/project/' + name, { + method: 'POST', cache: 'no-store', + headers: { 'Content-Type': 'application/json', 'Tuldok-Operation-Contract': await selection('project.' + name) }, + body: JSON.stringify(body) + }); + return await json(response); + } catch (error) { contracts = null; throw error; } + } + + // Answers are kept by operation and arguments until forgotten. + const kept = new Map(); + function read(name, args = {}) { + const key = name + ' ' + JSON.stringify(args); + if (!kept.has(key)) kept.set(key, call(name, args).catch(error => { kept.delete(key); throw error; })); + return kept.get(key); + } + function forget(names) { for (const key of [...kept.keys()]) if (names.includes(key.split(' ')[0])) kept.delete(key); } + + // ---- The map ------------------------------------------------------------ + /** + * What the Map tab and the drawer read, from the answer of `map`: + * sections (one per group that has models, the group tree read depth + * first in authored order, then one section "Not in a group" when a model + * names no group), models in section order and, within a section, in the + * map's order (training date, then those without one), inputs as lines, + * comparisons and the track with its scale. + */ + function shapeMap(raw) { + const groups = new Map(raw.groups.map(g => [g.id, g])); + const children = new Map(), roots = []; + for (const g of raw.groups) { + if (g.parent && groups.has(g.parent)) { if (!children.has(g.parent)) children.set(g.parent, []); children.get(g.parent).push(g); } + else roots.push(g); + } + const order = [], seen = new Set(); + const visit = (g, up) => { if (seen.has(g.id)) return; seen.add(g.id); order.push({ group: g, up }); for (const c of children.get(g.id) || []) visit(c, up.concat([g.title])); }; + roots.forEach(g => visit(g, [])); + const kinds = new Set(KINDS.map(k => k.id)); + const models = raw.models.map(m => ({ + id: m.reference, title: m.title, short: m.short, description: m.description || '', + group: groups.has(m.group) ? m.group : null, kind: kinds.has(m.change) ? m.change : UNSET, + parent: m.derived_from || null, trainedAt: m.trained_at, state: m.state, adopted: m.adopted, card: m.card, + value: m.value, count: m.count, benchmarks: m.benchmarks + })); + const byId = new Map(models.map(m => [m.id, m])); + for (const m of models) if (m.parent && !byId.has(m.parent)) m.parent = null; + const sections = []; + for (const { group, up } of order) { + const list = models.filter(m => m.group === group.id); + if (list.length) sections.push({ id: group.id, title: group.title, up, description: group.description, models: list }); + } + const loose = models.filter(m => m.group === null); + if (loose.length) sections.push({ id: null, title: 'Not in a group', up: [], loose: true, models: loose }); + for (const s of sections) for (const m of s.models) m.groupTitle = s.title; + const derived = new Set(raw.edges.filter(e => e.kind === 'derived').map(e => e.from + ' ' + e.to)); + const inputs = raw.edges.filter(e => e.kind === 'input' && !derived.has(e.from + ' ' + e.to) && byId.has(e.from) && byId.has(e.to)) + .map(e => ({ from: e.to, to: e.from })); // drawn from the input to the model that uses it + const comparisons = raw.comparisons.filter(c => byId.has(c.from) && byId.has(c.to)); + const track = raw.track; + const trackScale = track ? window.LabCharts.scale(models.map(m => m.value), track.metric.better) : null; + return { sections, models: sections.flatMap(s => s.models), byId, inputs, comparisons, track, trackScale, groups: raw.groups }; + } + let mapRaw = null, mapShaped = null; + async function map() { + const raw = await read('map'); + if (raw !== mapRaw) { mapRaw = raw; mapShaped = shapeMap(raw); } + return mapShaped; + } + const trackName = track => track ? track.metric.title + ' · ' + track.statistic : ''; + const better = track => track && track.metric.better === 'higher' ? 'higher is better' : 'lower is better'; + const units = track => track && track.metric.units && track.metric.units !== '1' ? ' ' + track.metric.units : ''; + + // ---- Where the project stands ------------------------------------------- + const plural = (n, one, many) => n + ' ' + (n === 1 ? one : many); + function titleOf(shaped, reference) { const m = shaped && shaped.byId.get(reference); return m ? (m.short ? m.short + ' · ' : '') + m.title : reference; } + /** + * {tone, word, text}: the one sentence of the status strip. Reads the map's + * model states and, once read, the runs and build requests. + */ + function standing(shaped, runs, requests) { + const count = s => shaped.models.filter(m => s.includes(m.state)).length; + const built = count(['built']), toBuild = count(['not-built', 'out-of-date', 'failed']), cannot = count(['cannot-rebuild']), work = count(['needs-work']); + const parts = [(built ? built : 'none') + ' built', toBuild + ' to build', cannot + ' cannot be rebuilt']; + if (work) parts.push(work + (work === 1 ? ' needs' : ' need') + ' work'); + let text = plural(shaped.models.length, 'model', 'models') + ': ' + parts.join(', ') + '.'; + const running = (runs || []).filter(r => r.state === 'running'), queued = (requests || []).filter(r => r.state === 'queued' || r.state === 'running'); + let tone = 'good', word = 'Idle'; + if (running.length) { tone = 'pending'; word = 'Building'; text += ' Running ' + running.map(r => titleOf(shaped, r.reference) + (r.subject ? ' (' + r.subject + ')' : '')).join(', ') + '.'; } + else if (queued.length) { tone = 'pending'; word = 'Queued'; text += ' ' + plural(queued.length, 'build request is', 'build requests are') + ' queued.'; } + else if (runs && requests) text += ' Nothing is running.'; + return { tone, word, text }; + } + + const day = iso => iso ? new Date(iso).toLocaleDateString('en-GB', { day: 'numeric', month: 'short', year: 'numeric' }) : ''; + const listed = (items, most = 3) => items.slice(0, most).join(', ') + (items.length > most ? ' and ' + (items.length - most) + ' more' : ''); + /** + * What needs the person, each a sentence with a kind ('approval', 'changed' + * or 'missing', which sets its mark): build requests awaiting approval, + * unsaved edits and files changed on disk, environments not ready, the + * definitions whose last run ended badly, a build worker stopped or elsewhere. + */ + function needs({ summary, status, requests, environments, runs, shaped }) { + const out = []; + for (const r of requests) if (r.state === 'awaiting-approval') { + const who = r.requested_by && (r.requested_by.label || r.requested_by.kind) || 'someone'; + out.push({ kind: 'approval', text: 'A build of ' + (r.every ? 'everything buildable' : listed(r.targets || [])) + ', asked by ' + who + ' on ' + day(r.requested_at) + ', awaits your approval.' }); + } + if (status.unsaved.length) out.push({ kind: 'changed', text: plural(status.unsaved.length, 'definition has', 'definitions have') + ' unsaved edits: ' + listed(status.unsaved.map(String)) + '.' }); + if (status.removed.length) out.push({ kind: 'changed', text: plural(status.removed.length, 'definition is', 'definitions are') + ' marked removed and not yet saved: ' + listed(status.removed.map(String)) + '.' }); + const disk = [].concat(status.added, status.changed, status.missing).map(String); + if (disk.length) out.push({ kind: 'changed', text: plural(disk.length, 'file changed', 'files changed') + ' on disk since the project was last read: ' + listed(disk) + '.' }); + if (status.irregular.length) out.push({ kind: 'missing', text: plural(status.irregular.length, 'file is', 'files are') + ' not regular files and are not read: ' + listed(status.irregular.map(String)) + '.' }); + const results = [].concat(status.results_unsaved, status.results_changed).map(String); + if (results.length) out.push({ kind: 'changed', text: 'Results differ from their files: ' + listed(results) + '.' }); + for (const e of environments) if (e.state !== 'ready') out.push({ kind: e.state === 'failing' ? 'missing' : 'changed', text: 'The environment ' + e.title + (e.state === 'failing' ? ' failed its last check.' : ' is not set up on this machine.') }); + const last = new Map(); + for (const r of runs) if (!last.has(r.reference)) last.set(r.reference, r); // runs come newest first + for (const [reference, r] of last) if (ENDED_BADLY[r.state]) out.push({ kind: 'missing', text: 'The last run of ' + titleOf(shaped, reference) + ' ' + ENDED_BADLY[r.state] + (r.finished_at ? ' on ' + day(r.finished_at) : '') + '.' }); + if (summary.worker === 'stopped') out.push({ kind: 'changed', text: 'The build worker is stopped: queued builds will not start.' }); + if (summary.worker === 'elsewhere') out.push({ kind: 'changed', text: 'Another Tuldok process runs the builds of this project.' }); + return out; + } + + return { KINDS, UNSET, kindLabel, stateWord, call, read, forget, map, trackName, better, units, standing, needs, titleOf, day }; +})(); diff --git a/static/project-workspace/app.js b/static/project-workspace/app.js new file mode 100644 index 00000000..eefa8d10 --- /dev/null +++ b/static/project-workspace/app.js @@ -0,0 +1,137 @@ +'use strict'; +// The shell of the project workspace (the mockup's b-map.html script): tabs, +// routing by hash (#/), the status strip and Needs you, the +// drawer, and when the project is read. The first screen reads summary and +// map; the strip's other sources are read right after; a tab reads what it +// needs when it is first shown; everything is read again when the window +// regains focus, and while a build is queued or running the strip asks again +// every two seconds for what can change. +(() => { + const P = window.TuldokProject, S = window.LabScreens; + const TABS = [['map', 'Map'], ['data', 'Data'], ['train', 'Train'], ['benchmarks', 'Benchmarks'], ['analysis', 'Analysis'], ['overview', 'Overview']]; + const POLL_MS = 2000; + const $ = id => document.getElementById(id); + const state = { screen: 'map', sel: {}, kinds: null, query: '', zoom: 1, track: false }; + const data = { summary: null, map: null, standing: null, needs: null, readAt: '', polling: false }; + let failed = null, mapText = null, pollTimer = null; + const clock = () => new Date().toLocaleTimeString('en-GB', { hour: '2-digit', minute: '2-digit' }); + + function parse() { + const hash = location.hash.replace(/^#/, ''), cut = hash.indexOf('/'); + const screen = cut < 0 ? hash : hash.slice(0, cut), id = cut < 0 ? '' : decodeURIComponent(hash.slice(cut + 1)); + state.screen = TABS.some(t => t[0] === screen) ? screen : 'map'; + if (id) state.sel[state.screen] = id; else delete state.sel[state.screen]; + } + function go(screen, id) { const next = '#' + screen + (id ? '/' + encodeURIComponent(id) : ''); if (location.hash === next) { parse(); render(); } else location.hash = next; } + const act = { + go, select: id => go(state.screen, id || undefined), + setQuery: q => { state.query = q; render(); }, + zoom: d => { state.zoom = Math.round(Math.min(1.6, Math.max(0.5, (state.zoom || 1) + d)) * 10) / 10; render(); }, + toggleKind: (k, all) => { if (!state.kinds) state.kinds = new Set([k]); else if (state.kinds.has(k)) { state.kinds.delete(k); if (!state.kinds.size) state.kinds = null; } else { state.kinds.add(k); if (state.kinds.size === all.length) state.kinds = null; } render(); }, + toggleTrack: () => { state.track = !state.track; render(); } + }; + + // ---- The status strip and Needs you --------------------------------------- + function strip() { + const el = $('strip'); el.textContent = ''; + if (failed) { el.appendChild(S.stateEl('serious', 'Not read')); el.appendChild(Object.assign(document.createElement('span'), { className: 'msg', textContent: failed })); return; } + if (!data.standing) { el.appendChild(Object.assign(document.createElement('span'), { className: 'msg', textContent: 'Reading the project…' })); return; } + el.appendChild(S.stateEl(data.standing.tone, data.standing.word)); + if (data.progress) { const hair = document.createElement('span'); hair.className = 'hair'; const i = document.createElement('i'); i.style.width = Math.round(100 * data.progress.completed / Math.max(1, data.progress.total)) + '%'; hair.appendChild(i); hair.title = data.progress.stage + ' ' + data.progress.completed + ' of ' + data.progress.total; el.appendChild(hair); } + const m = document.createElement('span'); m.className = 'msg'; + m.textContent = data.standing.text + (data.progress ? ' ' + data.progress.stage + ': ' + data.progress.completed + ' of ' + data.progress.total + '.' : '') + ' Read at ' + data.readAt + '.'; + el.appendChild(m); + const b = document.createElement('button'); b.className = 'btn sm needs-btn'; b.type = 'button'; b.id = 'needs-btn'; + b.textContent = 'Needs you · ' + (data.needs ? data.needs.length : '…'); b.disabled = !data.needs; + const panel = $('needs-panel'); b.setAttribute('aria-expanded', String(!panel.hidden)); b.setAttribute('aria-controls', 'needs-panel'); + b.addEventListener('click', () => { panel.hidden = !panel.hidden; b.setAttribute('aria-expanded', String(!panel.hidden)); fillNeeds(); }); + el.appendChild(b); + fillNeeds(); + } + function fillNeeds() { const panel = $('needs-panel'); if (panel.hidden || !data.needs) return; panel.textContent = ''; panel.appendChild(S.needsList(data.needs)); } + + // ---- Rendering -------------------------------------------------------------- + function render() { + const tabs = $('tabs'); tabs.textContent = ''; + for (const [id, label] of TABS) { const a = document.createElement('a'); a.href = '#' + id; a.textContent = label; if (id === state.screen) a.setAttribute('aria-current', 'page'); tabs.appendChild(a); } + const main = $('main'), aside = $('aside'), drawer = $('drawer'); + const name = data.summary ? data.summary.name : ''; + document.title = TABS.find(t => t[0] === state.screen)[1] + (name ? ' · ' + name : '') + ' · Tuldok'; + if (failed || !data.map) { + main.className = 'content'; main.textContent = ''; main._tree = null; + const p = document.createElement('p'); p.className = failed ? 'failure' : 'note'; p.textContent = failed || 'Reading the project…'; main.appendChild(p); + drawer.classList.remove('open'); drawer.setAttribute('aria-hidden', 'true'); main.classList.remove('with-drawer'); + return; + } + const wasMap = main.classList.contains('map'), view = state.screen + '/' + (state.screen === 'map' ? '' : state.sel[state.screen] || ''); + main.className = state.screen === 'map' ? 'map' : 'content'; + if (state.screen !== 'map' && wasMap) main._tree = null; + if (main._view !== view) { main.scrollTop = 0; main.scrollLeft = 0; main._view = view; } // a new screen starts at its top + const has = S[state.screen](main, aside, state, act, data); + drawer.classList.toggle('open', !!has); drawer.setAttribute('aria-hidden', String(!has)); main.classList.toggle('with-drawer', !!has); + if (!has) aside._for = null; + } + + // ---- Reading ------------------------------------------------------------------ + async function first() { + try { + data.summary = await P.read('summary'); + $('projname').textContent = data.summary.name; + data.map = await P.map(); mapText = JSON.stringify(await P.read('map')); + data.standing = P.standing(data.map, null, null); data.readAt = clock(); failed = null; + } catch (error) { failed = error.message; } + strip(); render(); + if (!failed) await standing(); + } + /** The strip's other sources: status, build requests, environments and runs. */ + async function standing() { + try { + const [status, requests, environments, runs] = await Promise.all([P.read('status'), P.read('build_requests'), P.read('environments'), P.read('runs')]); + data.standing = P.standing(data.map, runs.runs, requests.requests); + data.needs = P.needs({ summary: data.summary, status, requests: requests.requests, environments: environments.environments, runs: runs.runs, shaped: data.map }); + const running = runs.runs.find(r => r.state === 'running'); + data.progress = running ? (await P.call('progress', { run: running.id })).event : null; + data.readAt = clock(); + const busy = !!running || requests.requests.some(r => r.state === 'queued' || r.state === 'running'); + if (busy && !pollTimer) pollTimer = setTimeout(poll, POLL_MS); + } catch (error) { data.needs = null; data.standing = Object.assign({}, data.standing, { text: data.standing.text + ' ' + error.message }); } + strip(); + if (state.screen === 'overview') render(); + } + async function poll() { + pollTimer = null; + P.forget(['summary', 'runs', 'build_requests']); + try { data.summary = await P.read('summary'); } catch (error) { /* the strip says what failed below */ } + await standing(); + } + /** Everything again, when the window regains focus; the map is redrawn only when it changed. */ + async function again() { + if (failed) { P.forget(['summary', 'map']); return first(); } + P.forget(['summary', 'status', 'build_requests', 'environments', 'runs', 'map', 'activity', 'definitions', 'definition', 'recipe_results', 'products', 'note']); + try { + data.summary = await P.read('summary'); + const text = JSON.stringify(await P.read('map')); + if (text !== mapText) { mapText = text; data.map = await P.map(); $('aside')._for = null; render(); } + else if (state.screen === 'overview') render(); + } catch (error) { failed = error.message; render(); } + await standing(); + } + + function start() { + // auth.js puts its session controls first in the body; they belong at the right of the top bar. + const session = document.querySelector('body > .session-bar'); if (session) $('top-right').appendChild(session); + S.theme.init($('theme')); + $('close').appendChild(S.icon('x')); + $('close').addEventListener('click', () => go(state.screen)); + window.addEventListener('keydown', e => { + if (e.key !== 'Escape') return; + if (!$('needs-panel').hidden) { $('needs-panel').hidden = true; const b = $('needs-btn'); if (b) { b.setAttribute('aria-expanded', 'false'); b.focus(); } return; } + if ($('drawer').classList.contains('open') && state.sel[state.screen]) go(state.screen); + }); + window.addEventListener('hashchange', () => { parse(); render(); }); + window.addEventListener('focus', () => { if (data.summary || failed) again(); }); + window.addEventListener('tuldok-session', () => { if (failed) again(); }); + parse(); strip(); render(); first(); + } + if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', start, { once: true }); else start(); +})(); diff --git a/static/project-workspace/base.css b/static/project-workspace/base.css new file mode 100644 index 00000000..60ed417a --- /dev/null +++ b/static/project-workspace/base.css @@ -0,0 +1,408 @@ +/* The project workspace: tokens, primitives and the shell. Started from the + chosen mockup (docs/plans/project-workspace-redesign/mockups/shared/base.css + and the style block of b-map.html); class names are the mockup's, kinds of + change are named as in the project format. The faces are vendored under + /static/vendor/ubuntu-sans/ with their licence. */ +@font-face { font-family: "Ubuntu Sans"; font-style: normal; font-weight: 100 800; font-stretch: 75% 100%; font-display: swap; src: url("/static/vendor/ubuntu-sans/UbuntuSans[wdth,wght].ttf") format("truetype"); } +@font-face { font-family: "Ubuntu Sans"; font-style: italic; font-weight: 100 800; font-stretch: 75% 100%; font-display: swap; src: url("/static/vendor/ubuntu-sans/UbuntuSans-Italic[wdth,wght].ttf") format("truetype"); } +@font-face { font-family: "Ubuntu Sans Mono"; font-style: normal; font-weight: 400 700; font-display: swap; src: url("/static/vendor/ubuntu-sans/UbuntuSansMono[wght].ttf") format("truetype"); } +@font-face { font-family: "Ubuntu Sans Mono"; font-style: italic; font-weight: 400 700; font-display: swap; src: url("/static/vendor/ubuntu-sans/UbuntuSansMono-Italic[wght].ttf") format("truetype"); } +:root { + color-scheme: light; + --page: #f3f5f7; + --surface: #ffffff; + --surface-2: #eef1f4; + --line: #dfe4ea; + --line-strong: #c5cdd6; + --ink: #1b2330; + --ink-2: #596679; + --ink-3: #8a94a3; + --accent: #2c5fb8; + --accent-ink: #ffffff; + --accent-wash: #e8eef9; + --focus: #2c5fb8; + --good: #237c60; + --warn: #b4700e; + --serious: #b7452b; + --good-wash: #e4f2ec; + --warn-wash: #fbf0dd; + --serious-wash: #f9e6e1; + --k-training-policy: #178f74; + --k-architecture: #2e6fcf; + --k-refinement: #d2652f; + --k-component: #8a94a3; + --mark: #2e6fcf; + --grid: #e6eaef; + --font: "Ubuntu Sans", "Noto Sans", system-ui, sans-serif; + --mono: "Ubuntu Sans Mono", "Ubuntu Mono", ui-monospace, monospace; + --radius: 4px; +} +@media (prefers-color-scheme: dark) { + :root:not([data-theme="light"]) { + color-scheme: dark; + --page: #0f1317; --surface: #171c22; --surface-2: #1f262e; + --line: #2a323c; --line-strong: #3a4552; + --ink: #e6eaf0; --ink-2: #aab3c0; --ink-3: #7c8694; + --accent: #6a9ae8; --accent-ink: #0f1317; --accent-wash: #1d2a40; --focus: #8db4f5; + --good: #4fb68f; --warn: #d9a04a; --serious: #e07a5f; + --good-wash: #15302a; --warn-wash: #342a16; --serious-wash: #3a2320; + --k-training-policy: #22a07f; --k-architecture: #4f8ae0; --k-refinement: #d96f3c; --k-component: #7c8694; + --mark: #4f8ae0; --grid: #222a33; + } +} +:root[data-theme="dark"] { + color-scheme: dark; + --page: #0f1317; --surface: #171c22; --surface-2: #1f262e; + --line: #2a323c; --line-strong: #3a4552; + --ink: #e6eaf0; --ink-2: #aab3c0; --ink-3: #7c8694; + --accent: #6a9ae8; --accent-ink: #0f1317; --accent-wash: #1d2a40; --focus: #8db4f5; + --good: #4fb68f; --warn: #d9a04a; --serious: #e07a5f; + --good-wash: #15302a; --warn-wash: #342a16; --serious-wash: #3a2320; + --k-training-policy: #22a07f; --k-architecture: #4f8ae0; --k-refinement: #d96f3c; --k-component: #7c8694; + --mark: #4f8ae0; --grid: #222a33; +} + +* { box-sizing: border-box; } +html, body { height: 100%; } +body { + margin: 0; background: var(--page); color: var(--ink); + font: 14px/1.5 var(--font); -webkit-font-smoothing: antialiased; +} +[hidden] { display: none !important; } +h1, h2, h3, h4 { margin: 0; font-weight: 600; letter-spacing: -0.01em; line-height: 1.25; } +h1 { font-size: 20px; } +h2 { font-size: 16px; } +h3 { font-size: 14px; } +p { margin: 0; max-width: 66ch; } +a { color: var(--accent); text-decoration: none; } +a:hover { text-decoration: underline; } +button, input, select { font: inherit; color: inherit; } +button { cursor: pointer; } +.sr-only { position: absolute; width: 1px; height: 1px; overflow: hidden; clip: rect(0 0 0 0); white-space: nowrap; } +:focus-visible { outline: 2px solid var(--focus); outline-offset: 2px; border-radius: 2px; } +.mono { font-family: var(--mono); font-size: 12.5px; } +.num { font-variant-numeric: tabular-nums; } +.muted { color: var(--ink-2); } +.faint { color: var(--ink-3); } +.small { font-size: 12.5px; } + +/* Buttons: quiet by default. */ +.btn { + display: inline-flex; align-items: center; gap: 6px; min-height: 30px; padding: 4px 10px; + border: 1px solid var(--line-strong); border-radius: var(--radius); background: var(--surface); color: var(--ink); +} +.btn:hover { background: var(--surface-2); } +.btn.ghost { border-color: transparent; background: transparent; } +.btn.ghost:hover { background: var(--surface-2); } +.btn[disabled] { opacity: .5; cursor: not-allowed; } +.btn svg { width: 14px; height: 14px; flex: none; } +.btn.sm { min-height: 26px; padding: 2px 8px; font-size: 13px; } +.btn[aria-pressed="true"] { background: var(--accent-wash); border-color: var(--accent); } +input[type="search"], input[type="text"], select { + min-height: 30px; padding: 4px 8px; border: 1px solid var(--line-strong); border-radius: var(--radius); + background: var(--surface); color: var(--ink); +} +input::placeholder { color: var(--ink-3); } + +/* Kind and state marks: identity by a dot and a word, never colour alone. + A model without a kind of change has a hollow dot and the words "kind not set". */ +.chip { display: inline-flex; align-items: center; gap: 6px; font-size: 12.5px; color: var(--ink-2); white-space: nowrap; } +.chip::before { content: ""; width: 8px; height: 8px; border-radius: 50%; background: var(--k-component); flex: none; } +.chip.training-policy::before { background: var(--k-training-policy); } +.chip.architecture::before { background: var(--k-architecture); } +.chip.refinement::before { background: var(--k-refinement); } +.chip.component::before { background: var(--k-component); } +.chip.unset::before { background: transparent; box-shadow: inset 0 0 0 1.5px var(--ink-3); } +.chip.unset { color: var(--ink-3); } +.state { display: inline-flex; align-items: center; gap: 6px; font-size: 12.5px; color: var(--ink-2); white-space: nowrap; } +.state svg { width: 14px; height: 14px; flex: none; } +.state.good { color: var(--good); } +.state.warn { color: var(--warn); } +.state.serious { color: var(--serious); } +.state.neutral { color: var(--ink-3); } + +/* Rows: the dense list primitive. */ +.rows { list-style: none; margin: 0; padding: 0; } +.rows > li { border-top: 1px solid var(--line); } +.rows > li:last-child { border-bottom: 1px solid var(--line); } +.row { + display: grid; align-items: center; gap: 12px; width: 100%; padding: 7px 8px; text-align: left; + border: 0; background: transparent; color: inherit; border-radius: 0; +} +button.row:hover { background: var(--surface-2); } +.row[aria-pressed="true"], .row[aria-selected="true"] { background: var(--accent-wash); box-shadow: inset 3px 0 0 var(--accent); } +.row > span { min-width: 0; } +.row > span > .title, .row > span > .sub { display: block; } +.row .title { font-weight: 500; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; } +.row .sub { color: var(--ink-2); font-size: 12.5px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; } + +/* Section heading with a quiet one-line summary. */ +.sect { display: flex; align-items: baseline; gap: 12px; margin: 0 0 10px; } +.sect h2 { flex: none; } +.sect .sum { color: var(--ink-2); font-size: 13px; } +.sect .spacer { flex: 1; } + +/* Definition list for facts. */ +.facts { display: grid; grid-template-columns: max-content 1fr; gap: 4px 16px; margin: 0; font-size: 13px; } +.facts dt { color: var(--ink-2); } +.facts dd { margin: 0; overflow-wrap: anywhere; min-width: 0; } + +/* Notes that need the user, listed not shouted. */ +.needs { list-style: none; margin: 0; padding: 0; } +.needs li { display: grid; grid-template-columns: 18px 1fr; gap: 10px; align-items: start; padding: 8px 0; border-top: 1px solid var(--line); font-size: 13.5px; } +.needs li:last-child { border-bottom: 1px solid var(--line); } +.needs svg { width: 16px; height: 16px; margin-top: 2px; } +.needs .approval svg { color: var(--accent); } +.needs .changed svg { color: var(--warn); } +.needs .missing svg { color: var(--serious); } +.needs .empty { display: block; padding: 8px 0; border: 0; } + +/* Inspector (the drawer). */ +.inspector { display: flex; flex-direction: column; gap: 18px; } +.inspector header { display: flex; flex-direction: column; gap: 6px; } +.inspector header .kicker { font-family: var(--mono); font-size: 12.5px; color: var(--ink-2); overflow-wrap: anywhere; } +.inspector h2 { font-size: 17px; overflow-wrap: anywhere; } +.inspector h3 { font-size: 13px; color: var(--ink-2); font-weight: 600; margin-bottom: 6px; } +.inspector p { font-size: 13.5px; line-height: 1.55; max-width: 60ch; } +.inspector .actions { display: flex; flex-wrap: wrap; gap: 8px; } +.inspector .note { font-size: 12.5px; color: var(--ink-3); } +.ins-meta { display: flex; gap: 12px; flex-wrap: wrap; align-items: center; } +.metrics { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 10px 16px; margin: 0; } +.metrics > div { display: flex; flex-direction: column; min-width: 0; } +.metrics dt { font-size: 12px; color: var(--ink-2); } +.metrics dd { margin: 0; font-size: 16px; font-weight: 500; font-variant-numeric: tabular-nums; overflow-wrap: anywhere; } +.metrics dd small { font-size: 12px; color: var(--ink-3); font-weight: 400; margin-left: 4px; } +.links { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: 4px; } +.links button { text-align: left; padding: 6px 8px; border: 1px solid var(--line); border-radius: var(--radius); background: var(--surface); width: 100%; } +.links button:hover { background: var(--surface-2); } +.links .why { display: block; font-size: 12.5px; color: var(--ink-2); margin-top: 2px; } +.empty { color: var(--ink-2); font-size: 13.5px; max-width: 60ch; } + +/* Track bar: one neutral mark on the track's log scale; empty when the model has no value. */ +.mbar { display: inline-block; width: 56px; height: 6px; background: var(--grid); border-radius: 3px; overflow: hidden; vertical-align: middle; } +.mbar i { display: block; height: 100%; background: var(--mark); border-radius: 3px; } +.mbar.none { background: transparent; box-shadow: inset 0 0 0 1px var(--grid); } +.trow[aria-selected="true"] .mbar i { background: var(--accent); } + +/* Chart chrome (shared by the track and the charts of the other tabs). */ +.chart { position: relative; } +.chart svg { display: block; width: 100%; height: auto; } +.chart .axis text { fill: var(--ink-3); font-size: 11px; font-family: var(--font); } +.chart .axis line, .chart .grid line { stroke: var(--grid); stroke-width: 1; shape-rendering: crispEdges; } +.chart .axis .base { stroke: var(--line-strong); } +.chart .label { fill: var(--ink-2); font-size: 12px; paint-order: stroke; stroke: var(--surface); stroke-width: 3px; stroke-linejoin: round; } +.chart .pt { stroke: var(--surface); stroke-width: 2; } +.chart .pt.training-policy { fill: var(--k-training-policy); } +.chart .pt.architecture { fill: var(--k-architecture); } +.chart .pt.refinement { fill: var(--k-refinement); } +.chart .pt.component { fill: var(--k-component); } +.chart .pt.unset { fill: var(--surface); stroke: var(--ink-3); stroke-width: 1.5; } +.chart .pt.dim { opacity: .18; } +.chart .hit { fill: transparent; cursor: pointer; } +.chart .hit:focus-visible { outline: none; } +.chart .hit:focus-visible + .pt, .chart .hit:hover + .pt { stroke: var(--ink); } +.chart .sel { fill: none; stroke: var(--accent); stroke-width: 2; } +.chart .frontier { fill: none; stroke: var(--ink-3); stroke-width: 1.5; stroke-linejoin: round; } +.chart .line { fill: none; stroke: var(--mark); stroke-width: 2; stroke-linejoin: round; stroke-linecap: round; } +.chart .cross { stroke: var(--line-strong); stroke-width: 1; } +.tip { + position: absolute; z-index: 5; pointer-events: none; min-width: 160px; max-width: 280px; padding: 8px 10px; + background: var(--surface); border: 1px solid var(--line-strong); border-radius: var(--radius); font-size: 12.5px; color: var(--ink-2); + overflow-wrap: anywhere; +} +.tip b { display: block; color: var(--ink); font-size: 13px; font-weight: 600; } +.tip .v { color: var(--ink); font-weight: 500; font-variant-numeric: tabular-nums; } +.legend { display: flex; flex-wrap: wrap; gap: 14px; margin: 8px 0 0; padding: 0; list-style: none; font-size: 12.5px; color: var(--ink-2); } +.filters { display: flex; flex-wrap: wrap; gap: 8px; align-items: center; margin-bottom: 14px; } +.filters .grp { display: inline-flex; gap: 4px; flex-wrap: wrap; } +.filters .pop { margin-left: auto; font-size: 12.5px; color: var(--ink-3); } +table.tv { border-collapse: collapse; width: 100%; font-size: 13px; } +table.tv th, table.tv td { text-align: left; padding: 6px 8px; border-top: 1px solid var(--line); vertical-align: top; } +table.tv th { color: var(--ink-2); font-weight: 500; } +table.tv td.n, table.tv th.n { text-align: right; font-variant-numeric: tabular-nums; } +table.tv td.ck { font-family: var(--mono); font-size: 12.5px; color: var(--ink-2); } +table.tv td.nowrap, table.tv td.ck { white-space: nowrap; } + +/* Lineage list (git-graph style). */ +.tree-list { list-style: none; margin: 0; padding: 0; } +.tree-list .tsect { position: sticky; top: 0; z-index: 2; display: grid; grid-template-columns: var(--graphw, 72px) minmax(0, 1fr) auto; gap: 12px; align-items: center; padding: 6px 8px; background: var(--surface); border-top: 1px solid var(--line); border-bottom: 1px solid var(--line); } +.tree-list .tsect h3 { font-size: 13px; font-weight: 600; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; } +.tree-list .tsect h3 .up { color: var(--ink-3); font-weight: 400; } +.tree-list .tsect.loose h3 { color: var(--ink-2); font-style: italic; } +.tree-list .tsect .sum { font-size: 12.5px; color: var(--ink-2); white-space: nowrap; } +.tree-list .tsect svg { display: block; height: 20px; } +.tree-list .trow { display: grid; grid-template-columns: var(--graphw, 72px) var(--ckw, 44px) minmax(150px, 1fr) minmax(0, 1.4fr) 120px 64px 64px; gap: 12px; align-items: center; width: 100%; padding: 0 8px; min-height: 30px; border: 0; background: transparent; color: inherit; text-align: left; } +.tree-list .trow:hover { background: var(--surface-2); } +.tree-list .trow[aria-selected="true"] { background: var(--accent-wash); box-shadow: inset 3px 0 0 var(--accent); } +.tree-list .trow svg { display: block; height: 30px; } +.tree-list .trow .ck { font-family: var(--mono); font-size: 12.5px; color: var(--ink-2); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; } +.tree-list .trow .nm { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; } +.tree-list .trow .pu { font-size: 12.5px; color: var(--ink-3); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; } +@media (max-width: 1100px) { .tree-list .trow { grid-template-columns: var(--graphw, 72px) var(--ckw, 44px) minmax(120px, 1fr) 120px 64px 64px; } .tree-list .trow .pu { display: none; } } +.tree-list .trow .ms { font-variant-numeric: tabular-nums; font-size: 12.5px; color: var(--ink-2); text-align: right; white-space: nowrap; } +.tree-list .trow .ms.none { color: var(--ink-3); } +.tree-list .trow.related { background: var(--surface-2); } +.tree-list .trow.walk { background: var(--accent-wash); } +.tree-list .lane0 { stroke: var(--line-strong); stroke-width: 1.5; fill: none; } +.tree-list .lanek { stroke-width: 2; fill: none; } +.tree-list .dot { stroke: var(--surface); stroke-width: 2; fill: var(--k-component); } +.tree-list .dot.training-policy { fill: var(--k-training-policy); } +.tree-list .dot.architecture { fill: var(--k-architecture); } +.tree-list .dot.refinement { fill: var(--k-refinement); } +.tree-list .dot.component { fill: var(--k-component); } +.tree-list .dot.unset { fill: var(--surface); stroke: var(--ink-3); stroke-width: 1.5; } +.tree-list .dot.sel { stroke: var(--accent); stroke-width: 2; } +.lk-training-policy { stroke: var(--k-training-policy); } .lk-architecture { stroke: var(--k-architecture); } .lk-refinement { stroke: var(--k-refinement); } .lk-component { stroke: var(--k-component); } .lk-unset { stroke: var(--ink-3); } + +/* Lineage map (horizontal canvas). */ +.tree-map { position: relative; overflow: auto; background: var(--surface); } +.tree-map .inner { transform-origin: 0 0; } +.tree-map svg { display: block; } +.tree-map .tline { fill: none; stroke: var(--mark); stroke-width: 1.5; opacity: .75; } +.tree-map .tgrid { stroke: var(--grid); stroke-width: 1; shape-rendering: crispEdges; } +.tree-map .tlabel { fill: var(--ink-3); font-size: 10px; font-family: var(--font); } +.tree-map .ttitle { fill: var(--ink-2); font-size: 11px; font-family: var(--font); } +.tree-map .tpt { stroke: var(--surface); stroke-width: 1.5; cursor: pointer; fill: var(--k-component); } +.tree-map .tpt.training-policy { fill: var(--k-training-policy); } .tree-map .tpt.architecture { fill: var(--k-architecture); } .tree-map .tpt.refinement { fill: var(--k-refinement); } .tree-map .tpt.component { fill: var(--k-component); } +.tree-map .tpt.unset { fill: var(--surface); stroke: var(--ink-3); } +.tree-map .tpt.sel { stroke: var(--accent); stroke-width: 3; } +.tree-map .tpt.dim { opacity: .2; } +.tree-map .band { fill: none; stroke: var(--line); } +.tree-map .bandlabel { fill: var(--ink-2); font-size: 12px; font-weight: 600; font-family: var(--font); } +.tree-map .bandlabel.loose { font-style: italic; font-weight: 500; } +.tree-map .lanelabel { fill: var(--ink-3); font-size: 11px; font-family: var(--font); } +.tree-map .seq { stroke: var(--line-strong); stroke-width: 1.5; fill: none; } +.tree-map .der { fill: none; opacity: .55; stroke-width: 1.5; } +.tree-map .der.cold { opacity: .18; } +.tree-map .der.hot { opacity: 1; stroke-width: 2.5; } +.tree-map .inp { fill: none; stroke: var(--ink-2); stroke-width: 1.5; } +.tree-map .cmp { stroke: var(--ink-2); stroke-width: 1.5; stroke-dasharray: 4 4; fill: none; pointer-events: stroke; cursor: pointer; } +.tree-map .cmp:hover, .tree-map .cmp:focus-visible { stroke: var(--accent); stroke-width: 2.5; outline: none; } +.tree-map .node { cursor: pointer; } +.tree-map .node circle { stroke: var(--surface); stroke-width: 2; fill: var(--k-component); } +.tree-map .node.training-policy circle { fill: var(--k-training-policy); } +.tree-map .node.architecture circle { fill: var(--k-architecture); } +.tree-map .node.refinement circle { fill: var(--k-refinement); } +.tree-map .node.component circle { fill: var(--k-component); } +.tree-map .node.unset circle { fill: var(--surface); stroke: var(--ink-3); stroke-width: 1.5; } +.tree-map .node text { fill: var(--ink-2); font-size: 10.5px; font-family: var(--mono); text-anchor: middle; pointer-events: none; } +.tree-map .node text.nl { paint-order: stroke; stroke: var(--surface); stroke-width: 3px; stroke-linejoin: round; } +.tree-map .node text.nl.off { display: none; } +.tree-map .node.sel circle { stroke: var(--accent); stroke-width: 3; } +.tree-map .node.sel text { fill: var(--ink); font-weight: 600; } +.tree-map .node:hover circle, .tree-map .node:focus-visible circle { stroke: var(--ink); } +.tree-map .node:focus, .tree-map .node:focus-visible, .tree-map .tpt:focus { outline: none; } +.tree-map .node.dim { opacity: .25; } +.tree-map .node.kin circle { stroke: var(--ink); } +.tree-map .node.walk circle { stroke: var(--accent); stroke-width: 3; } +.tree-map .hitr { fill: transparent; } +.minimap { position: absolute; left: 12px; bottom: 12px; width: 220px; height: 56px; background: var(--surface); border: 1px solid var(--line-strong); border-radius: var(--radius); cursor: pointer; z-index: 2; } +.minimap svg { width: 100%; height: 100%; display: block; } +.minimap .vp { fill: var(--accent-wash); stroke: var(--accent); stroke-width: 1; opacity: .8; } +.minimap .d { fill: var(--ink-3); } +.zoomctl { display: inline-flex; gap: 4px; } + +/* Dataset cards and run rows (the Data and Train tabs build on these). */ +.ds-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(230px, 1fr)); gap: 14px; } +.ds-card { display: block; text-align: left; padding: 0; border: 1px solid var(--line); border-radius: var(--radius); background: var(--surface); color: inherit; overflow: hidden; } +.ds-card:hover { border-color: var(--line-strong); } +.ds-card[aria-pressed="true"] { border-color: var(--accent); box-shadow: inset 0 0 0 1px var(--accent); } +.ds-card .t { padding: 10px 12px 12px; display: grid; gap: 3px; } +.ds-card .t .title { font-weight: 500; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; } +.ds-card .t .meta { display: flex; gap: 8px; align-items: center; font-size: 12.5px; color: var(--ink-2); } +.ds-card .t .path { font-family: var(--mono); font-size: 11.5px; color: var(--ink-3); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; } +.row.run { grid-template-columns: 44px minmax(160px, 1fr) 120px 90px 50px 100px; } +.row.run .ck { font-family: var(--mono); font-size: 12.5px; color: var(--ink-2); } +.coverage { display: flex; flex-wrap: wrap; gap: 6px 18px; font-size: 12.5px; color: var(--ink-2); margin: -6px 0 14px; } +.coverage b { color: var(--ink); font-weight: 500; } +.cases svg { display: block; width: 100%; height: 64px; } +.cases .b { fill: var(--mark); } .cases .b.sel { fill: var(--accent); } +.cases .base { stroke: var(--line-strong); } + +/* ---- The shell: top bar, tabs, status strip, stage, drawer (b-map.html). ---- */ +body.shell { height: 100vh; display: grid; grid-template-rows: 48px auto 1fr; overflow: clip; } /* clip: not even a script or scrollIntoView can scroll the shell */ +.top { display: flex; align-items: center; gap: 22px; padding: 0 20px; border-bottom: 1px solid var(--line); background: var(--surface); min-width: 0; } +.brand { display: inline-flex; align-items: center; gap: 8px; font-weight: 600; color: var(--ink); flex: none; } +.brand:hover { text-decoration: none; } +.brand .mark { display: inline-grid; place-items: center; width: 22px; height: 22px; border-radius: 5px; background: var(--ink); color: var(--page); font-family: var(--mono); font-size: 13px; } +.top h1 { font-size: 15px; font-weight: 600; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; min-width: 0; flex: 0 1 auto; } +.tabs { display: flex; gap: 2px; margin-left: 8px; flex: none; } +.tabs a { padding: 6px 10px; border-radius: var(--radius); color: var(--ink-2); } +.tabs a:hover { background: var(--surface-2); text-decoration: none; } +.tabs a[aria-current="page"] { color: var(--ink); background: var(--accent-wash); } +.top .right { margin-left: auto; display: flex; gap: 14px; align-items: center; flex: none; } +/* The session controls of auth.js, moved into the top bar and drawn with the page's tokens. */ +.top .session-bar { display: inline-flex; align-items: center; gap: 6px; padding: 0; background: transparent; color: var(--ink-2); font: 12.5px var(--font); flex-wrap: nowrap; } +.top .session-bar button { min-height: 26px; padding: 2px 8px; font: 13px var(--font); color: var(--ink); background: transparent; border: 1px solid transparent; border-radius: var(--radius); } +.top .session-bar button:hover { background: var(--surface-2); } +#session-dialog { color: var(--ink); background: var(--surface); border: 1px solid var(--line-strong); border-radius: var(--radius); font: 14px/1.5 var(--font); } +#session-dialog::backdrop { background: rgba(15, 19, 23, .45); } +#session-dialog h2 { margin-bottom: 10px; } +#session-dialog button { min-height: 30px; padding: 4px 10px; border: 1px solid var(--line-strong); border-radius: var(--radius); background: var(--surface); color: var(--ink); } +#session-token { min-height: 30px; padding: 4px 8px; border: 1px solid var(--line-strong); border-radius: var(--radius); background: var(--surface); color: var(--ink); } +#session-status, .session-help { font: 13px/1.5 var(--font); color: var(--ink-2); } +.strip { display: flex; align-items: center; gap: 14px; padding: 8px 20px; border-bottom: 1px solid var(--line); background: var(--surface); font-size: 13px; min-width: 0; } +.strip .state { font-weight: 600; } +.strip .msg { color: var(--ink-2); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; min-width: 0; } +.strip .needs-btn { margin-left: auto; flex: none; } +.strip .needs-btn[aria-expanded="true"] { background: var(--accent-wash); } +.strip .hair { position: relative; width: 120px; height: 2px; background: var(--grid); flex: none; } +.strip .hair i { position: absolute; left: 0; top: 0; bottom: 0; background: var(--accent); } +#needs-panel { margin: 12px 20px 0; padding: 4px 16px; background: var(--surface); border: 1px solid var(--line); border-radius: var(--radius); z-index: 4; position: absolute; right: 0; top: 0; width: min(560px, calc(100vw - 40px)); max-height: calc(100% - 24px); overflow: auto; } +#needs-panel .needs li:first-child { border-top: 0; } +#needs-panel .needs li:last-child { border-bottom: 0; } +.stage { position: relative; min-height: 0; overflow: clip; display: grid; } +main { overflow: auto; padding: 18px 20px 40px; min-height: 0; min-width: 0; } +main.map { padding: 10px 20px 12px; display: grid; grid-template-rows: auto auto minmax(0, 1fr); overflow: hidden; } +main.map .tree-host { overflow: auto; min-height: 0; border: 1px solid var(--line); border-top: 0; border-radius: 0 0 var(--radius) var(--radius); background: var(--surface); } +main.map > .filters { margin-bottom: 10px; } +main.map > .empty { margin-top: 12px; } +.tree-map { height: auto; max-height: 46vh; border: 1px solid var(--line); border-radius: var(--radius) var(--radius) 0 0; } +.tree-list .tsect { top: 0; } +main.with-drawer { padding-right: calc(min(420px, 92vw) + 20px); } +.drawer { position: absolute; top: 0; right: 0; bottom: 0; width: min(420px, 92vw); background: var(--surface); border-left: 1px solid var(--line); padding: 18px 20px 40px; overflow: auto; z-index: 3; } +.drawer { transform: translateX(100%); visibility: hidden; } +.drawer.open { transform: none; visibility: visible; } +@media (prefers-reduced-motion: no-preference) { .drawer { transition: transform .2s ease, visibility .2s; } main { transition: padding-right .2s ease; } } +.drawer .close { position: absolute; right: 10px; top: 10px; } +.drawer .close svg { width: 16px; height: 16px; } +.content { max-width: none; } +.notyet { color: var(--ink-2); font-size: 14px; } +.failure { color: var(--serious); font-size: 13.5px; max-width: 80ch; overflow-wrap: anywhere; } + +/* Overview. */ +.ov-status { margin-bottom: 28px; } +.ov-line { display: flex; gap: 12px; align-items: baseline; } +.ov-line .state { font-size: 14px; font-weight: 600; } +.ov-text { font-size: 17px; line-height: 1.4; max-width: 70ch; } +.ov-row { display: grid; grid-template-columns: minmax(0, 1.5fr) minmax(0, 1fr); gap: 32px; margin: 24px 0 8px; } +.ov-cols { display: grid; grid-template-columns: minmax(0, 1fr) minmax(0, 1fr); gap: 32px; margin: 28px 0; } +.ov-history { margin-top: 24px; } +.row.ov-env { grid-template-columns: minmax(0, 1fr) auto; } +.row.ov-act { grid-template-columns: 150px minmax(0, 1fr) auto; } +table.tv.kinds td, table.tv.kinds th { white-space: nowrap; } +.report-frame { display: block; width: 100%; height: calc(100vh - 210px); min-height: 360px; border: 1px solid var(--line); border-radius: var(--radius); background: var(--surface); } +.report-bar { display: flex; gap: 12px; align-items: center; margin-bottom: 12px; } +@media (max-width: 1100px) { .ov-row { grid-template-columns: 1fr; } } +@media (max-width: 900px) { .ov-cols { grid-template-columns: 1fr; } .tabs a { padding: 6px 7px; } } + +/* A model's card, built as elements by markdown.js. */ +.card-md { font-size: 13.5px; line-height: 1.55; overflow-wrap: anywhere; } +.card-md > * + * { margin-top: 10px; } +.card-md h1, .card-md h2, .card-md h3, .card-md h4, .card-md h5, .card-md h6 { color: var(--ink); margin-top: 16px; } +.card-md h1 { font-size: 16px; } .card-md h2 { font-size: 15px; } .card-md h3 { font-size: 14px; color: var(--ink); margin-bottom: 0; } .card-md h4, .card-md h5, .card-md h6 { font-size: 13.5px; } +.card-md > :first-child { margin-top: 0; } +.card-md p { max-width: 66ch; } +.card-md ul, .card-md ol { margin: 0; padding-left: 20px; } +.card-md li + li { margin-top: 3px; } +.card-md code { font-family: var(--mono); font-size: 12.5px; background: var(--surface-2); border-radius: 3px; padding: 0 3px; } +.card-md pre { margin: 0; padding: 10px; background: var(--surface-2); border-radius: var(--radius); overflow: auto; font: 12.5px/1.5 var(--mono); white-space: pre; } +.card-md pre code { background: none; padding: 0; } +.card-md blockquote { margin: 0; padding-left: 12px; border-left: 3px solid var(--line-strong); color: var(--ink-2); } +.card-md hr { border: 0; border-top: 1px solid var(--line); } +.card-md .tbl { overflow-x: auto; } +.card-md table { border-collapse: collapse; font-size: 12.5px; } +.card-md th, .card-md td { padding: 4px 8px; border-top: 1px solid var(--line); text-align: left; vertical-align: top; overflow-wrap: normal; } +.card-md th { color: var(--ink-2); font-weight: 500; } +.card-md .link { color: var(--ink); text-decoration: underline dotted var(--ink-3); } +.card-md .link .href { color: var(--ink-3); font-family: var(--mono); font-size: 11.5px; } diff --git a/static/project-workspace/charts.js b/static/project-workspace/charts.js new file mode 100644 index 00000000..716acde8 --- /dev/null +++ b/static/project-workspace/charts.js @@ -0,0 +1,68 @@ +'use strict'; +// Chart helpers in plain SVG, shared by the map's track and the charts of the +// other tabs: element builders, a value scale fitted to the values it shows, +// number formats and the hover tip. Every value a chart draws is also written +// as text somewhere on the page; tips enhance, never gate. +window.LabCharts = (() => { + const svgNS = 'http://www.w3.org/2000/svg'; + const el = (name, attrs = {}, text) => { const n = document.createElementNS(svgNS, name); for (const k in attrs) n.setAttribute(k, attrs[k]); if (text !== undefined) n.textContent = text; return n; }; + const h = (tag, cls, text) => { const n = document.createElement(tag); if (cls) n.className = cls; if (text !== undefined) n.textContent = text; return n; }; + + /** A number in at most four significant figures, scientific below 0.01 and from 1e5. */ + function fmtSci(v) { + if (v == null || !Number.isFinite(v)) return '—'; + const a = Math.abs(v); + if (a === 0) return '0'; + if (a >= 0.01 && a < 1e5) return a >= 100 ? String(Math.round(v * 10) / 10) : v.toPrecision(3).replace(/(\.\d*?)0+$/, '$1').replace(/\.$/, ''); + const e = Math.floor(Math.log10(a)); + return (v / Math.pow(10, e)).toFixed(2) + 'e' + e; + } + const tickLabel = v => v >= 0.01 && v < 1e5 ? String(v) : '1e' + Math.round(Math.log10(v)); + + /** + * A scale for values: logarithmic over whole decades when every value is + * positive, linear from zero otherwise. at(v) is 0 at the low end and 1 at + * the high end; good(v) is the share of the scale that is better than the + * worst end, by better ('lower' or 'higher'), for bars that grow as a value + * improves. + */ + function scale(values, better = 'lower') { + const xs = values.filter(v => v != null && Number.isFinite(v)); + if (!xs.length) return null; + const positive = xs.every(v => v > 0); + let lo, hi, at, ticks; + if (positive) { + lo = Math.floor(Math.log10(Math.min(...xs))); hi = Math.ceil(Math.log10(Math.max(...xs))); + if (hi === lo) hi = lo + 1; + at = v => (Math.log10(Math.min(Math.max(v, Math.pow(10, lo)), Math.pow(10, hi))) - lo) / (hi - lo); + const step = Math.ceil((hi - lo) / 5); ticks = []; + for (let e = hi; e >= lo; e -= step) ticks.push(Math.pow(10, e)); + } else { + lo = Math.min(0, ...xs); hi = Math.max(...xs); if (hi === lo) hi = lo + 1; + at = v => (v - lo) / (hi - lo); + ticks = [hi, (hi + lo) / 2, lo]; + } + return { log: positive, at, ticks, label: positive ? tickLabel : fmtSci, good: v => better === 'higher' ? at(v) : 1 - at(v) }; + } + + /** A tip inside host, placed near (x, y) in host coordinates and kept inside it. */ + function tooltip(host) { + const t = h('div', 'tip'); t.hidden = true; host.appendChild(t); + return { + node: t, + show(x, y, rows) { + t.textContent = ''; + for (const r of rows) { + if (r.b) { t.appendChild(h('b', null, r.b)); continue; } + const line = h('div'); if (r.v) { line.appendChild(h('span', 'v', r.v)); line.appendChild(document.createTextNode(' ')); } + line.appendChild(document.createTextNode(r.l || '')); t.appendChild(line); + } + t.hidden = false; + t.style.left = Math.max(4, Math.min(x + 14, host.clientWidth - t.offsetWidth - 8)) + 'px'; + t.style.top = Math.max(4, Math.min(y + 12, host.clientHeight - t.offsetHeight - 8)) + 'px'; + }, + hide() { t.hidden = true; } + }; + } + return { el, h, fmtSci, scale, tooltip }; +})(); diff --git a/static/project-workspace/markdown.js b/static/project-workspace/markdown.js new file mode 100644 index 00000000..1ac1273d --- /dev/null +++ b/static/project-workspace/markdown.js @@ -0,0 +1,222 @@ +'use strict'; +// A small Markdown renderer for a model's card. It builds elements and text +// nodes only: no project text is ever assigned as markup. It covers what the +// cards use: ATX and setext headings, paragraphs, bold and italic, inline +// code, fenced code blocks, nested lists, block quotes, rules and tables. +// Links and images are shown as their text (a link's address is its title); +// nothing on the page is fetched or opened from a card. +window.TuldokMarkdown = (() => { + const h = (tag, cls) => { const n = document.createElement(tag); if (cls) n.className = cls; return n; }; + const BLANK = /^\s*$/; + const FENCE = /^( {0,3})(`{3,}|~{3,})(.*)$/; + const HEADING = /^ {0,3}(#{1,6})(?:[ \t]+(.*?))?(?:[ \t]+#+)?[ \t]*$/; + const RULE = /^ {0,3}([-*_])(?:[ \t]*\1){2,}[ \t]*$/; + const QUOTE = /^ {0,3}> ?/; + const ITEM = /^( {0,3})([-*+]|\d{1,9}[.)])([ \t]+|$)(.*)$/; + const SETEXT = /^ {0,3}(=+|-+)[ \t]*$/; + const ESCAPABLE = /[\\`*_{}[\]()#+\-.!|>~<]/; + const indentOf = line => line.match(/^ */)[0].length; + const detab = line => line.replace(/\t/g, ' '); + + // ---- Inline ------------------------------------------------------------- + function closer(text, delimiter, from) { + for (let j = text.indexOf(delimiter, from); j >= 0; j = text.indexOf(delimiter, j + 1)) { + if (j === from || /\s/.test(text[j - 1])) continue; + const after = text[j + delimiter.length]; + if (delimiter.length === 1 && after === delimiter) { j++; continue; } // part of a double + if (delimiter[0] === '_' && after && /[A-Za-z0-9]/.test(after)) continue; // intraword underscore + return j; + } + return -1; + } + function bracket(text, from) { // index of the ] that closes the [ at from, or -1 + let depth = 0; + for (let j = from; j < text.length; j++) { + if (text[j] === '\\') { j++; continue; } + if (text[j] === '[') depth++; + else if (text[j] === ']' && --depth === 0) return j; + } + return -1; + } + function inline(text, parent) { + let buffer = '', i = 0; + const flush = () => { if (buffer) { parent.appendChild(document.createTextNode(buffer)); buffer = ''; } }; + while (i < text.length) { + const c = text[i]; + if (c === '\\' && i + 1 < text.length && ESCAPABLE.test(text[i + 1])) { buffer += text[i + 1]; i += 2; continue; } + if (c === '`') { + let n = 1; while (text[i + n] === '`') n++; + const fence = '`'.repeat(n); + let end = text.indexOf(fence, i + n); + while (end >= 0 && text[end + n] === '`') { let k = end; while (text[k] === '`') k++; end = text.indexOf(fence, k); } + if (end < 0) { buffer += fence; i += n; continue; } + let body = text.slice(i + n, end).replace(/\n/g, ' '); + if (body.length > 2 && body[0] === ' ' && body[body.length - 1] === ' ' && body.trim()) body = body.slice(1, -1); + flush(); const code = h('code'); code.textContent = body; parent.appendChild(code); i = end + n; continue; + } + if (c === '*' || c === '_') { + let n = 1; while (text[i + n] === c && n < 3) n++; + const before = text[i - 1], next = text[i + n]; + const opens = next && !/\s/.test(next) && !(c === '_' && before && /[A-Za-z0-9]/.test(before)); + let done = false; + for (let size = n; opens && size >= 1 && !done; size--) { + const delimiter = c.repeat(size), end = closer(text, delimiter, i + size); + if (end < 0 || end === i + size) continue; + flush(); + const inner = text.slice(i + size, end); + let outer, target; + if (size === 3) { outer = h('strong'); target = h('em'); outer.appendChild(target); } + else { outer = target = h(size === 2 ? 'strong' : 'em'); } + inline(inner, target); parent.appendChild(outer); i = end + size; done = true; + } + if (!done) { buffer += c.repeat(n); i += n; } + continue; + } + if (c === '[' || (c === '!' && text[i + 1] === '[')) { + const open = c === '!' ? i + 1 : i, close = bracket(text, open); + if (close > 0 && text[close + 1] === '(') { + const end = text.indexOf(')', close + 2); + if (end > 0) { + const label = text.slice(open + 1, close), target = text.slice(close + 2, end).trim().split(/\s+/)[0] || ''; + flush(); + const span = h('span', 'link'); span.title = target; + if (c === '!') span.appendChild(document.createTextNode('image: ' + (label || target))); + else inline(label, span); + parent.appendChild(span); i = end + 1; continue; + } + } + buffer += c; i++; continue; + } + if (c === '<') { + const auto = /^<((?:https?|mailto|file):[^\s<>]+)>/.exec(text.slice(i)); + if (auto) { flush(); const span = h('span', 'link'); span.title = auto[1]; span.textContent = auto[1]; parent.appendChild(span); i += auto[0].length; continue; } + } + if (c === '\n') { + if (/ {2,}$/.test(buffer)) { buffer = buffer.replace(/ +$/, ''); flush(); parent.appendChild(h('br')); } + else buffer += ' '; + i++; continue; + } + buffer += c; i++; + } + flush(); + } + + // ---- Tables ------------------------------------------------------------- + function cells(line) { + let row = line.trim(); + if (row.startsWith('|')) row = row.slice(1); + if (row.endsWith('|') && !row.endsWith('\\|')) row = row.slice(0, -1); + const out = []; let cell = '', code = 0; + for (let i = 0; i < row.length; i++) { + const c = row[i]; + if (c === '\\' && row[i + 1] === '|') { cell += '|'; i++; continue; } + if (c === '`') code = code ? 0 : 1; + if (c === '|' && !code) { out.push(cell.trim()); cell = ''; continue; } + cell += c; + } + out.push(cell.trim()); + return out; + } + const isDelimiterRow = line => line.includes('-') && /^[\s|:-]+$/.test(line) && cells(line).every(cell => /^:?-+:?$/.test(cell)); + function startsTable(lines, i) { return lines[i].includes('|') && i + 1 < lines.length && isDelimiterRow(lines[i + 1]) && cells(lines[i]).length === cells(lines[i + 1]).length; } + function table(lines, i, parent) { + const head = cells(lines[i]), align = cells(lines[i + 1]).map(cell => cell.startsWith(':') && cell.endsWith(':') ? 'center' : cell.endsWith(':') ? 'right' : ''); + const wrap = h('div', 'tbl'), t = h('table'), thead = h('thead'), tr = h('tr'); + head.forEach((cell, k) => { const th = h('th'); if (align[k]) th.style.textAlign = align[k]; inline(cell, th); tr.appendChild(th); }); + thead.appendChild(tr); t.appendChild(thead); + const tbody = h('tbody'); i += 2; + for (; i < lines.length && !BLANK.test(lines[i]) && lines[i].includes('|'); i++) { + const row = cells(lines[i]), r = h('tr'); + for (let k = 0; k < head.length; k++) { const td = h('td'); if (align[k]) td.style.textAlign = align[k]; inline(row[k] || '', td); r.appendChild(td); } + tbody.appendChild(r); + } + t.appendChild(tbody); wrap.appendChild(t); parent.appendChild(wrap); + return i; + } + + // ---- Lists -------------------------------------------------------------- + function list(lines, i, parent) { + const first = ITEM.exec(lines[i]), base = first[1].length, ordered = /\d/.test(first[2]); + const node = h(ordered ? 'ol' : 'ul'); + if (ordered && parseInt(first[2], 10) !== 1) node.start = parseInt(first[2], 10); + let loose = false; + while (i < lines.length) { + const m = ITEM.exec(lines[i]); + if (!m || m[1].length !== base || /\d/.test(m[2]) !== ordered) break; + const offset = m[1].length + m[2].length + Math.min(Math.max(m[3].length, 1), 4); + const body = [m[4]]; i++; + let blankRun = 0; + while (i < lines.length) { + const line = lines[i]; + if (BLANK.test(line)) { blankRun++; body.push(''); i++; continue; } + const indent = indentOf(line); + if (indent >= offset || (indent > base && !ITEM.test(line))) { body.push(line.slice(Math.min(indent, offset))); blankRun = 0; i++; continue; } + if (indent > base && ITEM.test(line)) { body.push(line.slice(Math.min(indent, offset))); blankRun = 0; i++; continue; } + if (!blankRun && !ITEM.test(line) && !FENCE.test(line) && !HEADING.test(line) && !QUOTE.test(line) && !RULE.test(line)) { body.push(line.trim()); i++; continue; } // lazy continuation + break; + } + while (body.length && body[body.length - 1] === '') body.pop(); + if (blankRun && i < lines.length && ITEM.test(lines[i])) loose = true; + const li = h('li'); blocks(body, li); node.appendChild(li); + } + if (!loose) for (const li of node.children) { // a tight item shows its first paragraph without the paragraph box + const p = li.firstElementChild; + if (p && p.tagName === 'P') { while (p.firstChild) li.insertBefore(p.firstChild, p); p.remove(); } + } + parent.appendChild(node); + return i; + } + + // ---- Blocks ------------------------------------------------------------- + function interrupts(lines, i) { + const line = lines[i]; + return FENCE.test(line) || HEADING.test(line) || RULE.test(line) || QUOTE.test(line) || ITEM.test(line) || startsTable(lines, i); + } + function blocks(lines, parent) { + let i = 0; + while (i < lines.length) { + const line = lines[i]; + if (BLANK.test(line)) { i++; continue; } + let m = FENCE.exec(line); + if (m) { + const indent = m[1].length, mark = m[2], body = []; + i++; + while (i < lines.length) { + const close = FENCE.exec(lines[i]); + if (close && close[2][0] === mark[0] && close[2].length >= mark.length && !close[3].trim()) { i++; break; } + body.push(lines[i].slice(Math.min(indentOf(lines[i]), indent))); i++; + } + const pre = h('pre'), code = h('code'); code.textContent = body.join('\n'); + const language = m[3].trim().split(/\s+/)[0]; if (language) code.dataset.language = language; + pre.appendChild(code); parent.appendChild(pre); continue; + } + m = HEADING.exec(line); + if (m) { const n = h('h' + m[1].length); inline(m[2] || '', n); parent.appendChild(n); i++; continue; } + if (RULE.test(line)) { parent.appendChild(h('hr')); i++; continue; } + if (QUOTE.test(line)) { + const body = []; + while (i < lines.length && !BLANK.test(lines[i]) && (QUOTE.test(lines[i]) || !interrupts(lines, i))) { body.push(lines[i].replace(QUOTE, '')); i++; } + const quote = h('blockquote'); blocks(body, quote); parent.appendChild(quote); continue; + } + if (startsTable(lines, i)) { i = table(lines, i, parent); continue; } + if (ITEM.test(line)) { i = list(lines, i, parent); continue; } + const body = [line.trim()]; i++; + let level = 0; + while (i < lines.length && !BLANK.test(lines[i])) { + const s = SETEXT.exec(lines[i]); + if (s) { level = s[1][0] === '=' ? 1 : 2; i++; break; } + if (interrupts(lines, i)) break; + body.push(lines[i].replace(/^\s+/, '')); i++; + } + const n = h(level ? 'h' + level : 'p'); inline(body.join('\n'), n); parent.appendChild(n); + } + } + + /** A div.card-md holding text rendered as elements. */ + function render(text) { + const root = h('div', 'card-md'); + blocks(String(text).replace(/\r\n?/g, '\n').split('\n').map(detab), root); + return root; + } + return { render }; +})(); diff --git a/static/project-workspace/screens.js b/static/project-workspace/screens.js new file mode 100644 index 00000000..3e7f6c56 --- /dev/null +++ b/static/project-workspace/screens.js @@ -0,0 +1,221 @@ +'use strict'; +// The screens, from the mockup's screens.js. A screen is one function +// (main, aside, state, act) that fills the main area, fills the drawer when it +// has something to show there, and returns whether the drawer is open. It +// reads the project only through window.TuldokProject. Rule: the chrome holds +// no project words; names, groups, metrics and text come from the project. +window.LabScreens = (() => { + const P = window.TuldokProject, Tree = window.LabTree, C = window.LabCharts, h = C.h; + const svgNS = 'http://www.w3.org/2000/svg'; + const ICONS = { + check: 'M12 2a10 10 0 1 0 0 20 10 10 0 0 0 0-20zm-1.3 14.2-3.6-3.6 1.4-1.4 2.2 2.2 5.1-5.1 1.4 1.4z', + alert: 'M12 2a10 10 0 1 0 0 20 10 10 0 0 0 0-20zm-1 5h2v6h-2zm0 8h2v2h-2z', + triangle: 'M12 3 1 21h22zm-1 7h2v5h-2zm0 7h2v2h-2z', + minus: 'M12 2a10 10 0 1 0 0 20 10 10 0 0 0 0-20zm-5 9h10v2H7z', + branch: 'M7 3a3 3 0 0 0-1 5.8v6.4A3 3 0 1 0 8 15.2V9.9c1.2 1.3 2.9 2.1 5 2.1 2.8 0 4.4-1.5 5-4.1A3 3 0 1 0 16 7.6c-.5 1.6-1.4 2.4-3 2.4-2.6 0-4.3-1.6-5-3.2A3 3 0 0 0 7 3z', + clock: 'M12 2a10 10 0 1 0 0 20 10 10 0 0 0 0-20zm1 5h-2v6l5 3 1-1.7-4-2.3z', + x: 'M18.3 5.7 12 12l6.3 6.3-1.4 1.4L10.6 13.4 4.3 19.7 2.9 18.3 9.2 12 2.9 5.7l1.4-1.4 6.3 6.3 6.3-6.3z', + theme: 'M12 3a9 9 0 1 0 0 18 9 9 0 0 0 0-18zm0 2v14a7 7 0 0 1 0-14z' + }; + const icon = name => { const s = document.createElementNS(svgNS, 'svg'); s.setAttribute('viewBox', '0 0 24 24'); s.setAttribute('aria-hidden', 'true'); const p = document.createElementNS(svgNS, 'path'); p.setAttribute('d', ICONS[name] || ICONS.minus); p.setAttribute('fill', 'currentColor'); p.setAttribute('fill-rule', 'evenodd'); s.appendChild(p); return s; }; + const stateEl = (kind, text) => { const map = { good: 'check', warn: 'alert', serious: 'triangle', neutral: 'minus', pending: 'clock' }; const s = h('span', 'state ' + (kind === 'pending' ? 'warn' : kind)); s.appendChild(icon(map[kind] || 'minus')); s.appendChild(document.createTextNode(text)); return s; }; + const modelState = s => { const [word, tone] = P.stateWord(s); return stateEl(tone, word); }; + const sect = (title, sum) => { const d = h('div', 'sect'); d.appendChild(h('h2', null, title)); if (sum !== undefined) d.appendChild(h('span', 'sum', sum)); return d; }; + const cell = (k, v, u) => { const d = h('div'); d.appendChild(h('dt', null, k)); const dd = h('dd', null, v); if (u) dd.appendChild(h('small', null, u)); d.appendChild(dd); return d; }; + const block = (title, ...children) => { const d = h('div'); d.appendChild(h('h3', null, title)); for (const c of children) if (c) d.appendChild(c); return d; }; + const time = iso => iso ? new Date(iso).toLocaleString('en-GB', { day: 'numeric', month: 'short', year: 'numeric', hour: '2-digit', minute: '2-digit' }) : '—'; + const bytes = b => b == null ? '—' : b >= 1e9 ? (b / 1e9).toFixed(1) + ' GB' : b >= 1e6 ? (b / 1e6).toFixed(1) + ' MB' : b >= 1e3 ? Math.round(b / 1e3) + ' KB' : b + ' B'; + const failure = (parent, error) => { parent.appendChild(h('p', 'failure', error.message || String(error))); }; + const NEEDS_ICON = { approval: 'clock', changed: 'alert', missing: 'triangle' }; + function needsList(items) { + const ul = h('ul', 'needs'); + if (!items.length) { ul.appendChild(h('li', 'empty', 'Nothing needs you.')); return ul; } + for (const n of items) { const li = h('li', n.kind); li.appendChild(icon(NEEDS_ICON[n.kind])); li.appendChild(h('span', null, n.text)); ul.appendChild(li); } + return ul; + } + + // ---- Map ----------------------------------------------------------------- + let graph = null, graphOf = null; + function graphFor(shaped) { if (graphOf !== shaped) { graph = Tree.build(shaped); graphOf = shaped; } return graph; } + function map(main, aside, state, act, data) { + const shaped = data.map, g = graphFor(shaped), sel = state.sel.map && g.byId.has(state.sel.map) ? state.sel.map : null; + const kinds = P.KINDS.map(k => k.id).concat(g.nodes.some(m => m.kind === P.UNSET) ? [P.UNSET] : []); + const withValue = g.nodes.filter(m => m.value != null).length; + const buildBar = () => { + const bar = h('div', 'filters'); + const q = h('input'); q.type = 'search'; q.placeholder = 'Find a model'; q.value = state.query || ''; q.setAttribute('aria-label', 'Find a model'); q.addEventListener('input', () => act.setQuery(q.value)); bar.appendChild(q); + const grp = h('div', 'grp'); grp.setAttribute('role', 'group'); grp.setAttribute('aria-label', 'Kind of change'); + for (const k of kinds) { const b = h('button', 'btn sm chip ' + k, P.kindLabel(k)); b.type = 'button'; b.dataset.kind = k; b.setAttribute('aria-pressed', String(!state.kinds || state.kinds.has(k))); b.addEventListener('click', () => act.toggleKind(k, kinds)); grp.appendChild(b); } + bar.appendChild(grp); + if (g.track) { const tb = h('button', 'btn sm', 'Accuracy track'); tb.type = 'button'; tb.title = P.trackName(g.track) + ', ' + P.better(g.track); tb.setAttribute('aria-pressed', String(!!state.track)); tb.addEventListener('click', () => act.toggleTrack()); bar.appendChild(tb); } + const z = h('div', 'zoomctl'); for (const [t, d, l] of [['−', -0.2, 'Zoom out'], ['+', 0.2, 'Zoom in']]) { const b = h('button', 'btn sm', t); b.type = 'button'; b.setAttribute('aria-label', l); b.addEventListener('click', () => act.zoom(d)); z.appendChild(b); } bar.appendChild(z); + bar.appendChild(h('span', 'pop', g.nodes.length + ' models · ' + (g.track ? withValue + ' on the track' : 'no track'))); + return bar; + }; + if (!g.nodes.length) { main.textContent = ''; main._tree = null; main.appendChild(h('p', 'empty', 'This project has no recipes, so there are no models to map.')); aside.textContent = ''; return false; } + const sig = JSON.stringify([state.kinds ? [...state.kinds] : null, state.query || '', state.zoom || 1, !!state.track]); + const prev = main._tree; + const common = { onSelect: id => act.select(id), kinds: state.kinds, query: state.query }; + if (prev && prev.sig === sig && prev.shaped === shaped && main.contains(prev.bar)) { + if (sel && sel !== prev.sel) { prev.map.scrollTo(sel, true); prev.list.scrollTo(sel, true); } + prev.map.select(sel); prev.list.select(sel); prev.sel = sel; + } else { + const focused = prev && prev.bar && prev.bar.contains(document.activeElement) && document.activeElement.type === 'search' ? document.activeElement.selectionStart : null; + main.textContent = ''; const bar = buildBar(); main.appendChild(bar); + const mh = h('div', 'tree-map'); main.appendChild(mh); + const inst = { sig, bar, sel, shaped, map: null, list: null }; + inst.map = Tree.renderMap(mh, g, Object.assign({ selected: sel, zoom: state.zoom || 1, track: !!state.track }, common)); + const lh = h('div', 'tree-host'); main.appendChild(lh); inst.list = Tree.renderList(lh, g, Object.assign({ selected: sel }, common)); + if (sel) { inst.map.scrollTo(sel, false); inst.list.scrollTo(sel, false); } + if (focused !== null) { const q = bar.querySelector('input[type="search"]'); q.focus(); q.setSelectionRange(focused, focused); } + main._tree = inst; + } + if (sel) { inspectorModel(aside, sel, act, data); return true; } + aside.textContent = ''; aside._for = null; return false; + } + + // ---- Drawer: one model --------------------------------------------------- + function inspectorModel(aside, id, act, data) { + if (aside._for === id) return; + aside._for = id; aside.textContent = ''; + const g = graphFor(data.map), m = g.byId.get(id); + const ins = h('div', 'inspector'); + const hd = h('header'); + hd.appendChild(h('span', 'kicker', (m.short ? m.short + ' · ' : '') + (m.groupTitle || ''))); + hd.appendChild(h('h2', null, m.title)); + const meta = h('div', 'ins-meta'); meta.appendChild(h('span', 'chip ' + m.kind, P.kindLabel(m.kind))); meta.appendChild(modelState(m.state)); + meta.appendChild(h('span', 'small faint', m.trainedAt ? 'trained ' + P.day(m.trainedAt) : 'no training date')); + hd.appendChild(meta); ins.appendChild(hd); + // Lineage: what it was derived from, what derives from it, what it takes as input. + const lin = h('div', 'actions'); + const jump = (target, text) => { const b = h('button', 'btn sm ghost'); b.type = 'button'; b.appendChild(icon('branch')); b.appendChild(document.createTextNode(' ' + text)); b.addEventListener('click', () => act.select(target.id)); return b; }; + if (m.parent) lin.appendChild(jump(g.byId.get(m.parent), 'From ' + Tree.refName(g.byId.get(m.parent)))); + else lin.appendChild(h('span', 'small faint', 'No recorded ancestry')); + const kids = g.nodes.filter(n => n.parent === m.id); + if (kids.length === 1) lin.appendChild(jump(kids[0], Tree.refName(kids[0]) + ' derives from it')); + else if (kids.length) { const b = h('button', 'btn sm ghost', kids.length + ' models derive from it'); b.type = 'button'; b.addEventListener('click', () => act.select(kids[0].id)); lin.appendChild(b); } + ins.appendChild(lin); + const uses = g.edges.filter(e => e.kind === 'input' && e.to === m.id).map(e => g.byId.get(e.from)); + const usedBy = g.edges.filter(e => e.kind === 'input' && e.from === m.id).map(e => g.byId.get(e.to)); + for (const [title, list] of [['Takes as input', uses], ['Is an input of', usedBy]]) if (list.length) { + const ul = h('ul', 'links'); for (const o of list) { const li = h('li'); const b = h('button'); b.type = 'button'; b.textContent = Tree.nameOf(o); b.addEventListener('click', () => act.select(o.id)); li.appendChild(b); ul.appendChild(li); } + ins.appendChild(block(title, ul)); + } + // The track value. + const dl = h('dl', 'metrics'); + if (g.track) dl.appendChild(cell(g.track.metric.title, m.value == null ? '—' : C.fmtSci(m.value), m.value == null ? '' : P.units(g.track).trim())); + dl.appendChild(cell('Cases', m.count == null ? '—' : m.count.toLocaleString('en-GB'))); + dl.appendChild(cell('Benchmarks with results', String(m.benchmarks))); + dl.appendChild(cell('State', P.stateWord(m.state)[0] + (m.adopted ? ', adopted' : ''))); + ins.appendChild(dl); + ins.appendChild(h('p', 'note', g.track ? (m.value == null ? 'No result on ' + g.track.benchmark + ' for this model.' : 'The ' + g.track.statistic + ' over ' + m.count + ' cases of ' + g.track.benchmark + ', ' + P.better(g.track) + '.') : 'The project names no track for the map.')); + if (m.description) ins.appendChild(block('Description', h('p', null, m.description))); + const cmp = Tree.comparisons(g, m.id); + if (cmp.length) { + const ul = h('ul', 'links'); + for (const c of cmp) { const o = g.byId.get(c.other); const li = h('li'); const b = h('button'); b.type = 'button'; b.appendChild(document.createTextNode(Tree.nameOf(o))); const said = c.excerpt || c.explanation || ''; b.appendChild(h('span', 'why', said.slice(0, 140) + (said.length > 140 ? '…' : ''))); b.title = c.explanation || ''; b.addEventListener('click', () => act.select(o.id)); li.appendChild(b); ul.appendChild(li); } + ins.appendChild(block('Compared with', ul)); + } + // What is read when the model is opened. + const results = block('Results'), runs = block('Runs and product'), uses2 = block('Uses'), card = block('Card'); + for (const b of [results, runs, uses2, card]) { b.appendChild(h('p', 'note', 'Reading…')); ins.appendChild(b); } + aside.appendChild(ins); + const fill = (b, build) => p => { if (aside._for !== id) return; b.lastChild.remove(); try { build(b, p); } catch (error) { failure(b, error); } }; + const fail = b => error => { if (aside._for !== id) return; b.lastChild.remove(); failure(b, error); }; + Promise.all([P.read('recipe_results', { recipe: m.id }), P.read('definitions', { kind: 'benchmark' }).catch(() => ({ definitions: [] }))]) + .then(fill(results, (b, [found, defs]) => { + if (!found.rows.length) { b.appendChild(h('p', 'empty', found.benchmarks.length ? 'Named in ' + found.benchmarks.length + ' benchmarks, with no results yet.' : 'No benchmark measures this model.')); return; } + const titles = new Map(defs.definitions.map(d => [d.reference.split('/').slice(1).join('/'), d.title])); + const byBench = new Map(); for (const r of found.rows) { if (!byBench.has(r.benchmark)) byBench.set(r.benchmark, []); byBench.get(r.benchmark).push(r); } + for (const [bench, rows] of byBench) { + b.appendChild(h('p', 'small muted', titles.get(bench) || bench)); + const t = h('table', 'tv'); const hr = h('tr'); for (const [c, k] of [['Metric', ''], ['Median', 'n'], ['Cases', 'n']]) hr.appendChild(h('th', k, c)); const th = h('thead'); th.appendChild(hr); t.appendChild(th); + const tb = h('tbody'); for (const r of rows) { const tr = h('tr'); tr.appendChild(h('td', 'ck', r.metric)); tr.appendChild(h('td', 'n', C.fmtSci(r.median))); tr.appendChild(h('td', 'n', String(r.count))); tb.appendChild(tr); } t.appendChild(tb); b.appendChild(t); + } + }), fail(results)); + Promise.all([P.read('runs', { reference: m.id }), P.read('products', { reference: m.id })]) + .then(fill(runs, (b, [r, p]) => { + if (!r.runs.length) b.appendChild(h('p', 'empty', 'No run of this model in this project.')); + else { const ul = h('ul', 'rows'); for (const run of r.runs.slice(0, 8)) { const li = h('li'); const row = h('div', 'row'); row.style.gridTemplateColumns = 'minmax(0, 1fr) auto'; const t = h('span'); t.appendChild(h('span', 'title', (run.subject ? run.subject + ' · ' : '') + time(run.finished_at || run.started_at || run.queued_at))); t.appendChild(h('span', 'sub', [run.seconds != null ? Math.round(run.seconds) + ' s' : null, run.bytes != null ? bytes(run.bytes) : null, run.scratch ? 'scratch' : null].filter(Boolean).join(' · ') || run.id)); row.appendChild(t); row.appendChild(modelState(run.state)); li.appendChild(row); ul.appendChild(li); } b.appendChild(ul); if (r.runs.length > 8) b.appendChild(h('p', 'note', (r.runs.length - 8) + ' earlier runs are not listed.')); } + if (!p.products.length) b.appendChild(h('p', 'note', 'No product on this machine.')); + else { const dl = h('dl', 'facts'); for (const pr of p.products) { dl.appendChild(h('dt', null, (pr.subject || 'Product') + (pr.adopted ? ' (adopted)' : ''))); dl.appendChild(h('dd', 'mono', pr.directory + ' · ' + bytes(pr.bytes))); } b.appendChild(dl); } + }), fail(runs)); + P.read('definition', { reference: m.id }) + .then(fill(uses2, (b, d) => { + const other = d.uses.filter(u => !u.reference.startsWith('recipes/')); + if (!other.length) { b.appendChild(h('p', 'empty', 'It uses no dataset, model or environment.')); return; } + const dl = h('dl', 'facts'); for (const u of other) { dl.appendChild(h('dt', null, u.role)); dl.appendChild(h('dd', 'mono', u.reference)); } b.appendChild(dl); + }), fail(uses2)); + if (!m.card) fill(card, b => b.appendChild(h('p', 'empty', 'This model has no card.')))(); + else if (!m.card.startsWith('notes/')) fill(card, b => b.appendChild(h('p', 'empty', 'Its card ' + m.card + ' is not under notes/ and is not read.')))(); + else P.read('note', { path: m.card.slice('notes/'.length) }).then(fill(card, (b, note) => { b.appendChild(h('p', 'note mono', m.card)); b.appendChild(window.TuldokMarkdown.render(note.text)); }), fail(card)); + } + + // ---- Overview -------------------------------------------------------------- + function overview(main, aside, state, act, data) { + main.textContent = ''; aside.textContent = ''; aside._for = null; + if (state.sel.overview === 'report') return report(main, data); + const standing = data.standing; + const top = h('section', 'ov-status'); + const line = h('div', 'ov-line'); line.appendChild(stateEl(standing.tone, standing.word)); line.appendChild(h('p', 'ov-text', standing.text)); top.appendChild(line); + top.appendChild(h('p', 'small faint', 'Read at ' + data.readAt)); + main.appendChild(top); + const row = h('div', 'ov-row'); + const needs = h('section'); needs.appendChild(sect('Needs you', data.needs ? String(data.needs.length) : '…')); + if (data.needs) needs.appendChild(needsList(data.needs)); else needs.appendChild(h('p', 'note', 'Reading…')); + row.appendChild(needs); + const facts = h('section'); facts.appendChild(sect('Project')); + const dl = h('dl', 'facts'), s = data.summary; + for (const [k, v, c] of [['Folder', s.folder, 'mono'], ['Code root', s.code_root, 'mono'], ['Project', s.project_id, 'mono'], ['Build worker', s.worker]]) { dl.appendChild(h('dt', null, k)); dl.appendChild(h('dd', c || '', v)); } + dl.appendChild(h('dt', null, 'Report')); const dd = h('dd'); const a = h('a', null, 'Open the report'); a.href = '#overview/report'; dd.appendChild(a); dl.appendChild(dd); + facts.appendChild(dl); row.appendChild(facts); main.appendChild(row); + const cols = h('div', 'ov-cols'); + const defs = h('section'); defs.appendChild(sect('Definitions', String(Object.values(s.kinds).reduce((a, b) => a + b, 0)))); cols.appendChild(defs); + const envs = h('section'); envs.appendChild(sect('Environments', String(s.kinds.environment || 0))); cols.appendChild(envs); + main.appendChild(cols); + const act2 = h('section', 'ov-history'); act2.appendChild(sect('Latest activity')); main.appendChild(act2); + const pending = (b, promise, build) => { const note = h('p', 'note', 'Reading…'); b.appendChild(note); promise.then(v => { note.remove(); build(b, v); }, error => { note.remove(); failure(b, error); }); }; + pending(defs, P.read('definitions'), (b, d) => { + const states = [...new Set(d.definitions.map(x => x.state))].sort(); + const kinds = [...new Set(d.definitions.map(x => x.kind))].sort(); + if (!kinds.length) { b.appendChild(h('p', 'empty', 'The project has no definitions.')); return; } + const t = h('table', 'tv kinds'), th = h('thead'), hr = h('tr'); hr.appendChild(h('th', null, 'Kind')); for (const st of states) hr.appendChild(h('th', 'n', P.stateWord(st)[0])); hr.appendChild(h('th', 'n', 'All')); th.appendChild(hr); t.appendChild(th); + const tb = h('tbody'); for (const k of kinds) { const tr = h('tr'); tr.appendChild(h('td', null, k)); const mine = d.definitions.filter(x => x.kind === k); for (const st of states) { const n = mine.filter(x => x.state === st).length; tr.appendChild(h('td', 'n' + (n ? '' : ' faint'), n ? String(n) : '·')); } tr.appendChild(h('td', 'n', String(mine.length))); tb.appendChild(tr); } t.appendChild(tb); + const wrap = h('div'); wrap.style.overflowX = 'auto'; wrap.appendChild(t); b.appendChild(wrap); + }); + pending(envs, P.read('environments'), (b, e) => { + if (!e.environments.length) { b.appendChild(h('p', 'empty', 'The project defines no environment.')); return; } + const ul = h('ul', 'rows'); for (const env of e.environments) { const li = h('li'); const r = h('div', 'row ov-env'); const t = h('span'); t.appendChild(h('span', 'title', env.title)); t.appendChild(h('span', 'sub', ['Python ' + env.python, env.device, Object.keys(env.packages || {}).length + ' packages', env.checked_at ? 'checked ' + P.day(env.checked_at) : 'never checked'].filter(Boolean).join(' · '))); r.appendChild(t); r.appendChild(modelState(env.state)); li.appendChild(r); ul.appendChild(li); } b.appendChild(ul); + }); + pending(act2, P.read('activity', { limit: 12 }), (b, a) => { + if (!a.items.length) { b.appendChild(h('p', 'empty', 'Nothing has been asked of this project through Tuldok yet.')); return; } + const ul = h('ul', 'rows'); for (const it of a.items) { const li = h('li'); const r = h('div', 'row ov-act'); r.appendChild(h('span', 'sub num', time(it.at))); const t = h('span'); t.appendChild(h('span', 'title', it.operation + (it.target ? ' · ' + it.target : ''))); t.appendChild(h('span', 'sub', [(it.actor && (it.actor.label || it.actor.kind)) || '', it.detail].filter(Boolean).join(' · '))); r.appendChild(t); r.appendChild(stateEl(it.outcome === 'done' ? 'good' : 'serious', it.outcome)); li.appendChild(r); ul.appendChild(li); } + b.appendChild(ul); if (a.total > a.items.length) b.appendChild(h('p', 'note', (a.total - a.items.length) + ' earlier entries are not shown.')); + }); + return false; + } + function report(main, data) { + const bar = h('div', 'report-bar'); const back = h('a', 'btn sm ghost', '← Overview'); back.href = '#overview'; bar.appendChild(back); bar.appendChild(h('h2', null, 'Report')); main.appendChild(bar); + const frame = h('iframe', 'report-frame'); frame.title = 'Project report'; frame.setAttribute('sandbox', ''); + const note = h('p', 'note', 'Reading…'); main.appendChild(note); + const theme = getComputedStyle(document.documentElement).colorScheme === 'dark' ? 'dark' : 'light'; + P.call('report', { theme }).then(r => { note.remove(); frame.srcdoc = r.html; main.appendChild(frame); }, error => { note.remove(); failure(main, error); }); + return false; + } + + // ---- Tabs of the next slice ---------------------------------------------- + const notYet = label => (main, aside) => { main.textContent = ''; aside.textContent = ''; aside._for = null; main.appendChild(h('p', 'notyet', 'The ' + label + ' tab is not built yet.')); return false; }; + + // ---- Theme toggle (system, light, dark) ----------------------------------- + const theme = { + init(btn) { + let cur = 'auto'; try { cur = localStorage.getItem('tuldok-theme') || 'auto'; } catch (e) { /* storage refused: the system theme */ } + const q = new URLSearchParams(location.search).get('theme'); if (q === 'light' || q === 'dark') cur = q; + const apply = () => { if (cur === 'auto') document.documentElement.removeAttribute('data-theme'); else document.documentElement.setAttribute('data-theme', cur); btn.textContent = ''; btn.appendChild(icon('theme')); btn.appendChild(document.createTextNode(' ' + { auto: 'System', light: 'Light', dark: 'Dark' }[cur])); btn.setAttribute('aria-label', 'Theme: ' + { auto: 'system', light: 'light', dark: 'dark' }[cur]); }; + btn.addEventListener('click', () => { cur = { auto: 'light', light: 'dark', dark: 'auto' }[cur]; try { localStorage.setItem('tuldok-theme', cur); } catch (e) { /* kept for this page only */ } apply(); }); + apply(); + } + }; + + return { map, overview, data: notYet('Data'), train: notYet('Train'), benchmarks: notYet('Benchmarks'), analysis: notYet('Analysis'), inspectorModel, needsList, icon, stateEl, theme }; +})(); diff --git a/static/project-workspace/tree.js b/static/project-workspace/tree.js new file mode 100644 index 00000000..46f40479 --- /dev/null +++ b/static/project-workspace/tree.js @@ -0,0 +1,280 @@ +'use strict'; +// Model lineage, from the mockup's tree.js: one graph built from the project's +// map, rendered as a horizontal lane map (with the track beneath it when +// asked) and as a vertical list (git-graph style) under it. A model's lane +// comes from what it was derived from; solid lines are derivations (always) +// and inputs (of the selected model); the faint line is training order only +// and makes no ancestry claim; dashed arcs are the authored comparisons of +// the selected model. +// Both renderers return select() and scrollTo() so a selection change never +// rebuilds the view. +window.LabTree = (() => { + const P = window.TuldokProject, C = window.LabCharts, el = C.el, h = C.h; + const reduced = () => window.matchMedia && window.matchMedia('(prefers-reduced-motion: reduce)').matches; + const SHORT = 16; // characters of a short label shown on the map (spec-w1 section 1) + const shortOf = m => m.short ? m.short.slice(0, SHORT) : null; + const nameOf = m => (m.short ? m.short + ' · ' : '') + m.title; + const refName = m => m.short || (m.title.length > 24 ? m.title.slice(0, 23) + '…' : m.title); + // A short run of highlights from the previous selection to the new one, so + // the eye can follow the change. Never longer than ~450 ms; skipped when the + // viewer prefers reduced motion. + function walker() { + let timers = []; + return (ordered, fromId, toId, mark) => { + for (const t of timers) clearTimeout(t); timers = []; + if (reduced() || !fromId || !toId || fromId === toId) return; + const i0 = ordered.indexOf(fromId), i1 = ordered.indexOf(toId); if (i0 < 0 || i1 < 0) return; + let steps = i1 > i0 ? ordered.slice(i0 + 1, i1) : ordered.slice(i1 + 1, i0).reverse(); + if (steps.length > 22) { const out = []; for (let k = 0; k < 22; k++) out.push(steps[Math.round(k * (steps.length - 1) / 21)]); steps = out; } + const delay = Math.min(34, 420 / Math.max(1, steps.length)); + steps.forEach((id, k) => { timers.push(setTimeout(() => { mark(id, true); timers.push(setTimeout(() => mark(id, false), 170)); }, k * delay)); }); + }; + } + + /** + * The graph of a shaped map: nodes in section order with their index t and + * lane, families (the models derived from one model share a lane, lanes + * reused once free), the order line (consecutive models of the main lane + * whose training dates go forward), derivations, inputs and comparisons. + */ + function build(shaped) { + const nodes = shaped.models.map((m, t) => Object.assign({}, m, { t, lane: 0 })); + const byId = new Map(nodes.map(m => [m.id, m])); + const sections = []; let t = 0; + for (const s of shaped.sections) { sections.push({ id: s.id, label: s.title, up: s.up, loose: !!s.loose, start: t, end: t + s.models.length - 1, count: s.models.length }); for (const m of s.models) byId.get(m.id).section = sections.length - 1; t += s.models.length; } + const byParent = new Map(); + for (const m of nodes) if (m.parent && byId.has(m.parent)) { if (!byParent.has(m.parent)) byParent.set(m.parent, []); byParent.get(m.parent).push(m.id); } + const families = [...byParent].map(([parent, children]) => { + const ts = children.map(id => byId.get(id).t).concat([byId.get(parent).t]); + return { parent, children, start: Math.min(...ts), end: Math.max(...ts), lane: 0 }; + }).sort((a, b) => a.start - b.start || a.end - b.end); + const laneLast = [Infinity]; + for (const f of families) { + let lane = 1; while (laneLast[lane] !== undefined && laneLast[lane] >= f.start) lane++; + f.lane = lane; laneLast[lane] = f.end; + for (const id of f.children) byId.get(id).lane = lane; + } + // The order line joins consecutive models of the main lane whose training dates go forward, within a + // section or across neighbouring sections of the same parent group (as the mockup's checkpoint line did). + const sameParent = (a, b) => a === b || (Math.abs(a - b) === 1 && sections[a].up.length > 0 && sections[a].up.join('/') === sections[b].up.join('/')); + const edges = []; let prev = null; + for (const m of nodes) { + if (m.lane !== 0) continue; + if (prev && prev.trainedAt && m.trainedAt && prev.trainedAt <= m.trainedAt && sameParent(prev.section, m.section)) edges.push({ from: prev.id, to: m.id, kind: 'sequence' }); + prev = m; + } + for (const m of nodes) if (m.parent && byId.has(m.parent)) edges.push({ from: m.parent, to: m.id, kind: 'derivation' }); + for (const e of shaped.inputs) edges.push({ from: e.from, to: e.to, kind: 'input' }); + for (const r of shaped.comparisons) edges.push({ from: r.from, to: r.to, kind: 'comparison', explanation: r.explanation, excerpt: r.excerpt }); + const seqSpan = new Array(nodes.length).fill(false); + for (const e of edges) if (e.kind === 'sequence') for (let k = byId.get(e.from).t + 1; k < byId.get(e.to).t; k++) seqSpan[k] = true; + const seqIn = new Set(edges.filter(e => e.kind === 'sequence').map(e => e.to)); + const seqOut = new Set(edges.filter(e => e.kind === 'sequence').map(e => e.from)); + return { nodes, byId, edges, sections, families, laneCount: laneLast.length, seqIn, seqOut, seqSpan, track: shaped.track, scale: shaped.trackScale }; + } + function related(graph, id) { const out = new Set(); for (const e of graph.edges) if (e.kind !== 'sequence' && (e.from === id || e.to === id)) out.add(e.from === id ? e.to : e.from); return out; } + function comparisons(graph, id) { return graph.edges.filter(e => e.kind === 'comparison' && (e.from === id || e.to === id)).map(e => ({ other: e.from === id ? e.to : e.from, explanation: e.explanation, excerpt: e.excerpt })); } + function matches(m, q) { + if (!q) return true; q = q.toLowerCase(); + return [m.title, m.short, m.description, m.groupTitle, m.id].some(s => s && s.toLowerCase().includes(q)); + } + const visibleFor = (kinds, query) => m => (!kinds || kinds.has(m.kind)) && matches(m, query); + const trackText = (graph, m) => m.value == null ? 'no value' : C.fmtSci(m.value) + P.units(graph.track); + + // ---- Vertical list ------------------------------------------------------- + function renderList(container, graph, { selected = null, onSelect = () => {}, kinds = null, query = '' } = {}) { + container.textContent = ''; + const laneW = 16, pad = 10, gw = pad * 2 + laneW * Math.max(1, graph.laneCount - 1) + 8, rowH = 30; + const shortest = Math.max(3, ...graph.nodes.map(m => (shortOf(m) || '').length)); + container.style.setProperty('--graphw', gw + 'px'); + container.style.setProperty('--ckw', Math.ceil(shortest * 7 + 4) + 'px'); + const ul = h('ul', 'tree-list'); ul.setAttribute('role', 'listbox'); ul.setAttribute('aria-label', 'Models by section, in training order'); + const active = t => graph.families.filter(f => f.start < t && t <= f.end); + const laneX = l => pad + 4 + l * laneW; + const visible = visibleFor(kinds, query); + const rows = new Map(); let shown = 0; + for (const s of graph.sections) { + const list = graph.nodes.slice(s.start, s.end + 1).filter(visible); + if (!list.length) continue; + const li = h('li'); const head = h('div', 'tsect' + (s.loose ? ' loose' : '')); + const hs = el('svg', { width: gw, height: 20, 'aria-hidden': 'true' }); + for (const f of active(s.start)) hs.appendChild(el('line', { x1: laneX(f.lane), y1: 0, x2: laneX(f.lane), y2: 20, class: 'lanek lk-' + graph.byId.get(f.children[0]).kind })); + if (graph.seqIn.has(graph.nodes[s.start].id) || graph.seqSpan[s.start]) hs.appendChild(el('line', { x1: laneX(0), y1: 0, x2: laneX(0), y2: 20, class: 'lane0' })); + head.appendChild(hs); + const title = h('h3'); if (s.up.length) title.appendChild(h('span', 'up', s.up.join(' / ') + ' / ')); title.appendChild(document.createTextNode(s.label)); title.title = s.up.concat([s.label]).join(' / '); head.appendChild(title); + const fam = graph.families.filter(f => graph.byId.get(f.parent).section === graph.sections.indexOf(s)); + head.appendChild(h('span', 'sum', list.length + (list.length === s.count ? '' : ' of ' + s.count) + (fam.length ? ' · ' + fam.map(f => f.children.length + ' from ' + refName(graph.byId.get(f.parent))).join(', ') : ''))); + li.appendChild(head); ul.appendChild(li); + for (const m of list) { + shown++; + const row = h('li'); const b = h('button', 'trow'); b.type = 'button'; b.setAttribute('role', 'option'); b.setAttribute('aria-selected', 'false'); b.dataset.id = m.id; + const svg = el('svg', { width: gw, height: rowH, 'aria-hidden': 'true' }); + const x0 = laneX(0), mid = rowH / 2; + if (graph.seqSpan[m.t]) svg.appendChild(el('line', { x1: x0, y1: 0, x2: x0, y2: rowH, class: 'lane0' })); + if (graph.seqIn.has(m.id)) svg.appendChild(el('line', { x1: x0, y1: 0, x2: x0, y2: mid, class: 'lane0' })); + if (graph.seqOut.has(m.id)) svg.appendChild(el('line', { x1: x0, y1: mid, x2: x0, y2: rowH, class: 'lane0' })); + for (const f of active(m.t)) { + const k = 'lanek lk-' + graph.byId.get(f.children[0]).kind, x = laneX(f.lane), isChild = f.children.includes(m.id); + svg.appendChild(el('line', { x1: x, y1: 0, x2: x, y2: isChild && m.t === f.end ? mid : rowH, class: k })); + } + for (const f of graph.families.filter(f => f.parent === m.id)) { const x = laneX(f.lane), k = 'lanek lk-' + graph.byId.get(f.children[0]).kind; svg.appendChild(el('path', { d: `M${laneX(m.lane)},${mid} C${laneX(m.lane)},${rowH} ${x},${mid} ${x},${rowH}`, class: k })); } + const dot = el('circle', { cx: laneX(m.lane), cy: mid, r: 5, class: 'dot ' + m.kind }); + svg.appendChild(dot); b.appendChild(svg); + b.appendChild(h('span', 'ck', shortOf(m) || '—')); + b.appendChild(h('span', 'nm', m.title)); + b.appendChild(h('span', 'pu', m.description)); + b.appendChild(h('span', 'chip ' + m.kind, P.kindLabel(m.kind))); + const bar = h('span', 'mbar' + (m.value == null ? ' none' : '')); + if (m.value != null && graph.scale) { const fill = h('i'); fill.style.width = Math.round(graph.scale.good(m.value) * 100) + '%'; bar.appendChild(fill); } + bar.title = graph.track ? P.trackName(graph.track) + ': ' + trackText(graph, m) : 'The project names no track'; + b.appendChild(bar); + b.appendChild(h('span', 'ms' + (m.value == null ? ' none' : ''), graph.track ? (m.value == null ? '—' : C.fmtSci(m.value)) : '')); + b.title = nameOf(m); + b.addEventListener('click', () => onSelect(m.id)); + row.appendChild(b); ul.appendChild(row); rows.set(m.id, { b, dot }); + } + } + ul.addEventListener('keydown', e => { if (e.key !== 'ArrowDown' && e.key !== 'ArrowUp') return; const opts = [...ul.querySelectorAll('.trow')]; const i = opts.indexOf(document.activeElement); if (i < 0) return; const n = opts[i + (e.key === 'ArrowDown' ? 1 : -1)]; if (n) { n.focus(); e.preventDefault(); } }); + container.appendChild(ul); + if (!shown) container.appendChild(h('p', 'empty', 'No models match.')); + let current = null; const walk = walker(); const order = [...rows.keys()]; + const api = { + shown, + select(id) { const rel = id ? related(graph, id) : new Set(); for (const [mid, r] of rows) { r.b.setAttribute('aria-selected', String(mid === id)); r.b.classList.toggle('related', rel.has(mid)); r.dot.classList.toggle('sel', mid === id); } walk(order, current, id, (mid, on) => { const r = rows.get(mid); if (r) r.b.classList.toggle('walk', on); }); current = id; }, + scrollTo(id, smooth) { const r = rows.get(id); if (!r) return; const box = r.b.getBoundingClientRect(), frame = container.getBoundingClientRect(); const top = container.scrollTop + box.top - frame.top - container.clientHeight / 2 + box.height / 2; container.scrollTo({ top: Math.max(0, top), behavior: smooth && !reduced() ? 'smooth' : 'auto' }); } + }; + api.select(selected); return api; + } + + // ---- Horizontal lane map, with the track beneath when asked ---------------- + const labelWidth = text => text.length * 7 + 24; // 12px semibold section titles, with room + const nodeLabelWidth = text => text.length * 6.4; // 10.5px mono + function renderMap(container, graph, { selected = null, onSelect = () => {}, kinds = null, query = '', zoom = 1, track = false } = {}) { + container.textContent = ''; + const dx = 30, left = 70, top = 44, laneH = 52, plotH = 120; + // Each section is as wide as its models or its title, whichever is wider. + const sx = []; let cursor = left - dx / 2; + for (const s of graph.sections) { sx.push(cursor); cursor += Math.max(s.count * dx, labelWidth(s.label)); } + const xOf = new Map(graph.nodes.map(m => [m.id, sx[m.section] + dx / 2 + (m.t - graph.sections[m.section].start) * dx])); + const W = cursor + 60; + const lanesH = top + 20 + graph.laneCount * laneH; + const showTrack = track && graph.track && graph.scale; + const trackTop = lanesH + 40, H = showTrack ? trackTop + plotH + 34 : lanesH + 30; + const trackLabel = graph.track ? P.trackName(graph.track) + ', ' + P.better(graph.track) : ''; + const ty = v => trackTop + (1 - graph.scale.at(v)) * plotH; + const x = m => xOf.get(m.id), y = m => top + 20 + m.lane * laneH; + const inner = h('div', 'inner'); inner.style.width = W + 'px'; inner.style.height = H + 'px'; inner.style.transform = 'scale(' + zoom + ')'; + const svg = el('svg', { width: W, height: H, viewBox: `0 0 ${W} ${H}`, role: 'img', 'aria-label': 'Model lineage: sections left to right in training order, branches in lanes' + (showTrack ? ', with ' + trackLabel + ' beneath' : '') }); + const visible = visibleFor(kinds, query); + graph.sections.forEach((s, i) => { + const x1 = sx[i], width = (sx[i + 1] || cursor) - x1; + svg.appendChild(el('line', { x1, y1: 8, x2: x1, y2: H - 8, class: 'band' })); + const t = el('text', { x: x1 + 8, y: 22, class: 'bandlabel' + (s.loose ? ' loose' : '') }, s.label); t.appendChild(el('title', {}, s.up.concat([s.label]).join(' / '))); svg.appendChild(t); + if (showTrack) { + if (i === 0 || width >= labelWidth(trackLabel) * 0.85) svg.appendChild(el('text', { x: x1 + 8, y: trackTop - 14, class: 'ttitle' }, trackLabel)); + if (i === 0 || width >= 60) for (const v of graph.scale.ticks) svg.appendChild(el('text', { x: x1 + 8, y: ty(v) - 3, class: 'tlabel' }, graph.scale.label(v))); + } + }); + for (const e of graph.edges) { if (e.kind !== 'sequence') continue; const a = graph.byId.get(e.from), b = graph.byId.get(e.to); svg.appendChild(el('line', { x1: x(a), y1: y(a), x2: x(b), y2: y(b), class: 'seq' })); } + for (const f of graph.families) { + const p = graph.byId.get(f.parent), kids = f.children.map(id => graph.byId.get(id)), k = kids[0].kind, ly = y(kids[0]); + const x0 = x(p), forward = kids.some(c => x(c) > x0), xb = x0 + (forward ? 1 : -1) * dx * 1.6; + const xs = kids.map(x).concat([xb]), a = Math.min(...xs), b = Math.max(...xs); + svg.appendChild(el('path', { d: `M${x0},${y(p)} C${x0 + (xb - x0) * 0.4},${y(p)} ${xb - (xb - x0) * 0.4},${ly} ${xb},${ly} M${a},${ly} L${b},${ly}`, class: 'der lk-' + k, 'data-family': f.parent })); + svg.appendChild(el('text', { x: Math.max(xb, a) + 4, y: ly - 7, class: 'lanelabel' }, 'from ' + refName(p))); + } + const gInp = el('g', { class: 'inp-layer' }); svg.appendChild(gInp); + const gCmp = el('g', { class: 'cmp-layer' }); svg.appendChild(gCmp); + const trackPts = new Map(); + if (showTrack) { + for (const v of graph.scale.ticks) svg.appendChild(el('line', { x1: left - 16, y1: ty(v), x2: W - 20, y2: ty(v), class: 'tgrid' })); + let d = '', prev = null; + for (const m of graph.nodes) { if (m.lane !== 0 || m.value == null) continue; d += (prev && prev.section === m.section && m.t - prev.t <= 3 ? 'L' : 'M') + x(m) + ',' + ty(m.value) + ' '; prev = m; } + if (d) svg.appendChild(el('path', { d: d.trim(), class: 'tline' })); + for (const m of graph.nodes) { + if (m.value == null) continue; + const c = el('circle', { cx: x(m), cy: ty(m.value), r: 3.5, class: 'tpt ' + m.kind + (visible(m) ? '' : ' dim'), tabindex: 0, role: 'button', 'aria-label': refName(m) + ', ' + trackText(graph, m) }); + c.appendChild(el('title', {}, nameOf(m) + ' · ' + trackText(graph, m))); + c.addEventListener('click', () => onSelect(m.id)); c.addEventListener('keydown', ev => { if (ev.key === 'Enter' || ev.key === ' ') { ev.preventDefault(); onSelect(m.id); } }); + svg.appendChild(c); trackPts.set(m.id, c); + } + } + const host = container.parentElement; host.style.position = 'relative'; + host.querySelectorAll(':scope > .minimap, :scope > .tip').forEach(n => n.remove()); + const tip = C.tooltip(host); + const at = ev => { const r = host.getBoundingClientRect(); return [ev.clientX - r.left, ev.clientY - r.top]; }; + const showTip = (m, ev) => { + const rows = [{ b: nameOf(m) }]; + rows.push(graph.track ? { v: m.value == null ? '—' : C.fmtSci(m.value) + P.units(graph.track), l: P.trackName(graph.track) } : { l: 'The project names no track' }); + rows.push({ l: m.trainedAt ? 'trained ' + P.day(m.trainedAt) : 'no training date' }); + rows.push({ v: P.kindLabel(m.kind), l: m.parent ? 'from ' + refName(graph.byId.get(m.parent)) : '' }); + const [px, py] = at(ev); tip.show(px, py, rows); + }; + const nodeEls = new Map(); + // A node's short label is shown when it does not crowd the last label shown in its lane. + const laneLabelEnd = new Map(), labelled = new Set(); + for (const m of graph.nodes) { + const text = shortOf(m); if (!text) continue; + const w = nodeLabelWidth(text), last = laneLabelEnd.get(m.lane); + if (last === undefined || x(m) - w / 2 >= last + 14) { labelled.add(m.id); laneLabelEnd.set(m.lane, x(m) + w / 2); } + } + for (const m of graph.nodes) { + const g = el('g', { class: 'node ' + m.kind + (visible(m) ? '' : ' dim'), tabindex: 0, role: 'button', 'aria-label': nameOf(m), 'data-id': m.id }); + g.appendChild(el('rect', { x: x(m) - 14, y: y(m) - 14, width: 28, height: 28, class: 'hitr' })); + g.appendChild(el('circle', { cx: x(m), cy: y(m), r: 5.5 })); + const text = shortOf(m); + const lbl = text ? el('text', { x: x(m), y: y(m) + 18, class: 'nl' + (labelled.has(m.id) ? '' : ' off') }, text) : null; + if (lbl) g.appendChild(lbl); + g.addEventListener('click', () => onSelect(m.id)); + g.addEventListener('keydown', ev => { if (ev.key === 'Enter' || ev.key === ' ') { ev.preventDefault(); onSelect(m.id); } }); + g.addEventListener('pointerenter', ev => showTip(m, ev)); g.addEventListener('pointermove', ev => showTip(m, ev)); g.addEventListener('pointerleave', () => tip.hide()); + g.addEventListener('focus', () => { const r = g.getBoundingClientRect(); showTip(m, { clientX: r.left + 14, clientY: r.top + 14 }); }); g.addEventListener('blur', () => tip.hide()); + svg.appendChild(g); nodeEls.set(m.id, { g, lbl }); + } + inner.appendChild(svg); container.appendChild(inner); + const mini = h('div', 'minimap'); mini.setAttribute('role', 'img'); mini.setAttribute('aria-label', 'Whole map; click to move'); + const ms = el('svg', { viewBox: `0 0 ${W} ${H}`, preserveAspectRatio: 'none' }); + for (const m of graph.nodes) ms.appendChild(el('circle', { cx: x(m), cy: y(m), r: 7, class: 'd' })); + const vp = el('rect', { class: 'vp', x: 0, y: 0, width: 10, height: 10 }); ms.appendChild(vp); mini.appendChild(ms); host.appendChild(mini); + const sync = () => { vp.setAttribute('x', container.scrollLeft / zoom); vp.setAttribute('y', container.scrollTop / zoom); vp.setAttribute('width', container.clientWidth / zoom); vp.setAttribute('height', container.clientHeight / zoom); }; + container.addEventListener('scroll', sync); sync(); + new ResizeObserver(sync).observe(container); + mini.addEventListener('click', ev => { const r = mini.getBoundingClientRect(); container.scrollTo({ left: ((ev.clientX - r.left) / r.width) * W * zoom - container.clientWidth / 2, top: ((ev.clientY - r.top) / r.height) * H * zoom - container.clientHeight / 2, behavior: reduced() ? 'auto' : 'smooth' }); }); + let current = null; const walk = walker(); const order = graph.nodes.map(m => m.id); + const api = { + select(id) { + const sel = graph.byId.get(id); + gCmp.textContent = ''; + walk(order, current, id, (mid, on) => { const n = nodeEls.get(mid); if (n) n.g.classList.toggle('walk', on); }); current = id; + for (const [mid, n] of nodeEls) { + const m = graph.byId.get(mid), on = mid === id; + n.g.classList.toggle('sel', on); n.g.querySelector('circle').setAttribute('r', on ? 7 : 5.5); + const fam = !!sel && (m.parent === id || mid === sel.parent || (!!sel.parent && m.parent === sel.parent)); + if (n.lbl) n.lbl.classList.toggle('off', !(on || fam || labelled.has(mid))); + n.g.classList.toggle('kin', fam && !on); + } + for (const p of svg.querySelectorAll('.der')) p.classList.toggle('hot', !!sel && (p.dataset.family === id || p.dataset.family === sel.parent)); + // Inputs are drawn for the selected model only, so that the map stays quiet (63 in the lab's project). + gInp.textContent = ''; + if (sel) for (const e of graph.edges) if (e.kind === 'input' && (e.from === id || e.to === id)) { + const a = graph.byId.get(e.from), b = graph.byId.get(e.to), lift = Math.min(40, 10 + Math.abs(x(b) - x(a)) / 20); + gInp.appendChild(el('path', { d: `M${x(a)},${y(a)} C${x(a)},${y(a) + lift} ${x(b)},${y(b) + lift} ${x(b)},${y(b)}`, class: 'inp' })); + } + for (const [mid, c] of trackPts) c.classList.toggle('sel', mid === id); + if (sel) for (const e of graph.edges) if (e.kind === 'comparison' && (e.from === id || e.to === id)) { + const a = graph.byId.get(e.from), b = graph.byId.get(e.to), other = e.from === id ? b : a; + const path = el('path', { d: `M${x(a)},${y(a)} C${x(a)},${Math.min(y(a), y(b)) - 34} ${x(b)},${Math.min(y(a), y(b)) - 34} ${x(b)},${y(b)}`, class: 'cmp', tabindex: 0, role: 'link', 'aria-label': 'Compared with ' + refName(other) }); + const said = e.excerpt || e.explanation || ''; + path.appendChild(el('title', {}, 'Compared with ' + nameOf(other) + ': ' + said)); + const show = ev => { const [px, py] = at(ev); tip.show(px, py, [{ b: 'Compared with ' + nameOf(other) }, { l: said.slice(0, 160) + (said.length > 160 ? '…' : '') }]); }; + path.addEventListener('pointerenter', show); path.addEventListener('pointermove', show); path.addEventListener('pointerleave', () => tip.hide()); + path.addEventListener('click', () => onSelect(other.id)); path.addEventListener('keydown', ev => { if (ev.key === 'Enter') onSelect(other.id); }); + gCmp.appendChild(path); + } + }, + scrollTo(id, smooth) { const m = graph.byId.get(id); if (!m) return; container.scrollTo({ left: x(m) * zoom - container.clientWidth / 2, top: Math.max(0, y(m) * zoom - container.clientHeight / 2), behavior: smooth && !reduced() ? 'smooth' : 'auto' }); } + }; + api.select(selected); return api; + } + return { build, renderList, renderMap, related, comparisons, matches, nameOf, refName }; +})(); diff --git a/static/vendor/ubuntu-sans/LICENCE.txt b/static/vendor/ubuntu-sans/LICENCE.txt new file mode 100644 index 00000000..2d881d1d --- /dev/null +++ b/static/vendor/ubuntu-sans/LICENCE.txt @@ -0,0 +1,108 @@ +Ubuntu Sans and Ubuntu Sans Mono (the four .ttf files in this directory) +Copyright 2010-2022 Canonical Ltd + +These files are copied unmodified, with their original names, from the +Ubuntu package fonts-ubuntu 0.869+git20240321-0ubuntu1 (/usr/share/fonts/truetype/ubuntu/). They are +distributed under the Ubuntu Font Licence 1.0 below, and under no other licence. + +Ubuntu and Canonical are registered trademarks of Canonical Ltd. + +The licence accompanying these works does not grant any rights +under trademark law and all such rights are reserved. + +------------------------------- +UBUNTU FONT LICENCE Version 1.0 +------------------------------- + +PREAMBLE +This licence allows the licensed fonts to be used, studied, modified and +redistributed freely. The fonts, including any derivative works, can be +bundled, embedded, and redistributed provided the terms of this licence +are met. The fonts and derivatives, however, cannot be released under +any other licence. The requirement for fonts to remain under this +licence does not require any document created using the fonts or their +derivatives to be published under this licence, as long as the primary +purpose of the document is not to be a vehicle for the distribution of +the fonts. + +DEFINITIONS +"Font Software" refers to the set of files released by the Copyright +Holder(s) under this licence and clearly marked as such. This may +include source files, build scripts and documentation. + +"Original Version" refers to the collection of Font Software components +as received under this licence. + +"Modified Version" refers to any derivative made by adding to, deleting, +or substituting -- in part or in whole -- any of the components of the +Original Version, by changing formats or by porting the Font Software to +a new environment. + +"Copyright Holder(s)" refers to all individuals and companies who have a +copyright ownership of the Font Software. + +"Substantially Changed" refers to Modified Versions which can be easily +identified as dissimilar to the Font Software by users of the Font +Software comparing the Original Version with the Modified Version. + +To "Propagate" a work means to do anything with it that, without +permission, would make you directly or secondarily liable for +infringement under applicable copyright law, except executing it on a +computer or modifying a private copy. Propagation includes copying, +distribution (with or without modification and with or without charging +a redistribution fee), making available to the public, and in some +countries other activities as well. + +PERMISSION & CONDITIONS +This licence does not grant any rights under trademark law and all such +rights are reserved. + +Permission is hereby granted, free of charge, to any person obtaining a +copy of the Font Software, to propagate the Font Software, subject to +the below conditions: + +1) Each copy of the Font Software must contain the above copyright +notice and this licence. These can be included either as stand-alone +text files, human-readable headers or in the appropriate machine- +readable metadata fields within text or binary files as long as those +fields can be easily viewed by the user. + +2) The font name complies with the following: +(a) The Original Version must retain its name, unmodified. +(b) Modified Versions which are Substantially Changed must be renamed to +avoid use of the name of the Original Version or similar names entirely. +(c) Modified Versions which are not Substantially Changed must be +renamed to both (i) retain the name of the Original Version and (ii) add +additional naming elements to distinguish the Modified Version from the +Original Version. The name of such Modified Versions must be the name of +the Original Version, with "derivative X" where X represents the name of +the new work, appended to that name. + +3) The name(s) of the Copyright Holder(s) and any contributor to the +Font Software shall not be used to promote, endorse or advertise any +Modified Version, except (i) as required by this licence, (ii) to +acknowledge the contribution(s) of the Copyright Holder(s) or (iii) with +their explicit written permission. + +4) The Font Software, modified or unmodified, in part or in whole, must +be distributed entirely under this licence, and must not be distributed +under any other licence. The requirement for fonts to remain under this +licence does not affect any document created using the Font Software, +except any version of the Font Software extracted from a document +created using the Font Software may only be distributed under this +licence. + +TERMINATION +This licence becomes null and void if any of the above conditions are +not met. + +DISCLAIMER +THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF +COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE +COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL +DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM OTHER +DEALINGS IN THE FONT SOFTWARE. diff --git a/static/vendor/ubuntu-sans/UbuntuSans-Italic[wdth,wght].ttf b/static/vendor/ubuntu-sans/UbuntuSans-Italic[wdth,wght].ttf new file mode 100644 index 0000000000000000000000000000000000000000..5391d7d9e1082c74478d16a894dd95d12b65d28b GIT binary patch literal 738444 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

aw7CytKHkGR4(cAZ}Kd)Y^;b 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

nRQjrn@-*jSdz4~}Ezn!m0;SkuOU(Xl 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

5hD1R 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

p5aKj#0PQ;FNqx)X_v(A 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


Sl;4to9bwloXhoW?&-v} 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 B9v1)r literal 0 HcmV?d00001 diff --git a/static/vendor/ubuntu-sans/UbuntuSansMono-Italic[wght].ttf b/static/vendor/ubuntu-sans/UbuntuSansMono-Italic[wght].ttf new file mode 100644 index 0000000000000000000000000000000000000000..f4ff323c8b074a6be7d48a45c053f918773efb4e GIT binary patch literal 186356 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%0D&m`GvBHg93q>B*1R{^HW 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

gW5wdXzs88`Pdkph7lQQj@5@8+H+QXuy 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

Huxw{6-E;;!7t}V~3U4GjMRpTS0!M1ZQ80`8z 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 z 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
  • 3ViW>%ZV*Y%qf)c9;p?|-&k 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 z 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

    w&bWYkCgPUDdn*dcskOBaERp4wz@cP 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]#_ij)okC* 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

    +
    diff --git a/static/project-workspace/actions.js b/static/project-workspace/actions.js new file mode 100644 index 00000000..c2d2a852 --- /dev/null +++ b/static/project-workspace/actions.js @@ -0,0 +1,333 @@ +'use strict'; +// The controls that change the project (spec-w3.md section 3.1), and the +// plumbing every such control shares: who may use one (the rules of +// service._allowed, from the signed-in identity), a group of buttons bound to +// one key whose state outlives a re-render (waiting for an answer, the +// two-press "Confirm" state, typed text, the last refusal), and the views +// built of them: the plan view, the conflict panel, the controls of Needs +// you and the strip's Save. A control calls one operation; while it waits it +// is disabled and says so; when the answer comes every kept answer is +// forgotten and the page reads again (hooks.changed, set by app.js); a +// refusal is shown under the control in the server's words, with its +// problems listed. Nothing is retried on its own. Text goes in through text +// nodes only. +window.LabActions = (() => { + const P = window.TuldokProject, h = window.LabCharts.h; + + // ---- Who may use a control ------------------------------------------------ + const identity = () => (window.TuldokAuth && window.TuldokAuth.identity()) || null; + /** Whether the session satisfies an operation's who rule (inspect, edit, cancel, request, owner). */ + function may(who) { + const id = identity(); + if (!id || !['owner', 'agent'].includes(id.kind) || !Array.isArray(id.scopes)) return false; + const scopes = id.scopes; + if (who === 'inspect' || who === 'edit' || who === 'cancel') return scopes.includes(who); + if (who === 'request') return scopes.includes('inspect') && (id.kind === 'owner' || scopes.includes('execute')); + if (who === 'owner') return id.kind === 'owner' && scopes.includes('approve-execution'); + return false; + } + const isAgent = () => (identity() || {}).kind === 'agent'; + + let hooks = { changed: async () => {}, refused: async () => {}, reread: async () => {} }; + /** app.js: changed() reads everything again after an answer, refused() after a refusal, reread() on request. */ + function connect(given) { hooks = Object.assign({}, hooks, given); } + + // ---- Groups of controls ---------------------------------------------------- + // A group's state, by its key: busy (the item waiting), confirming (the item + // in its two-press state), refusal ({error, item}) and text (typed, by field). + const slots = new Map(); + const slot = key => { if (!slots.has(key)) slots.set(key, { busy: null, confirming: null, refusal: null, text: {} }); return slots.get(key); }; + const groups = key => [...document.querySelectorAll('.act-group')].filter(g => g._key === key); + const btn = (cls, text, key) => { const b = h('button', cls, text); b.type = 'button'; if (key) b.dataset.key = key; return b; }; + + /** + * A group of controls bound to key: an element that draws its items from + * the group's state whenever it changes and on every re-render. An item is + * { id, label, cls, who, op, args(slot) -> arguments, busy (the words while + * waiting), confirm (words: the item takes two presses), input ({name, + * label, placeholder, max, always}: a field shown always, or in the + * confirm state), done(result), extra(error) (more under a refusal), + * hidden } or a plain control { id, label, cls, onClick }. Items whose who + * the session does not satisfy are not drawn; a group with none is empty. + * options.refusalIn: the element that shows the refusal instead of the group. + */ + function group(key, items, options = {}) { + const el = h('div', 'act-group' + (options.inline ? ' inline' : '')); + el._key = key; el._items = items; el._options = options; el.dataset.group = key; + fill(el); + return el; + } + const shown = el => el._items.filter(i => !i.hidden && (!i.who || may(i.who))); + function fill(el) { + const key = el._key, s = slot(key), items = shown(el), opts = el._options; + el.textContent = ''; + if (!items.length) { el.hidden = true; return; } + el.hidden = false; + const row = h('div', 'actions'); + const confirming = s.confirming && items.find(i => i.id === s.confirming); + if (confirming) { + const it = confirming; + if (it.input && !it.input.always) el.appendChild(field(key, it.input, s)); + el.appendChild(h('p', 'confirm-words', it.confirm)); + const ok = btn('btn primary act', s.busy ? (it.busy || 'Waiting…') : 'Confirm', key + ':' + it.id + ':confirm'); + ok.disabled = !!s.busy; if (s.busy) ok.setAttribute('aria-busy', 'true'); + ok.addEventListener('click', () => press(key, it, true)); + const back = btn('btn ghost act', 'Back', key + ':' + it.id + ':back'); back.disabled = !!s.busy; + back.addEventListener('click', () => leave(key)); + row.appendChild(ok); row.appendChild(back); + } else { + for (const it of items) { + if (it.input && it.input.always) row.appendChild(field(key, it.input, s)); + const b = btn((it.cls || 'btn sm') + (it.op || it.who ? ' act' : ''), s.busy === it.id ? (it.busy || 'Waiting…') : it.label, key + ':' + it.id); + if (it.title) b.title = it.title; + if (s.busy) { b.disabled = true; if (s.busy === it.id) b.setAttribute('aria-busy', 'true'); } + b.addEventListener('click', () => it.onClick ? it.onClick() : press(key, it, false)); + row.appendChild(b); + } + } + el.appendChild(row); + const host = opts.refusalIn || el; + if (opts.refusalIn) opts.refusalIn.textContent = ''; + if (s.refusal && items.some(i => i.id === s.refusal.item)) { + const it = items.find(i => i.id === s.refusal.item); + host.appendChild(refusal(s.refusal.error, it.extra ? it.extra(s.refusal.error) : null)); + } + } + function field(key, input, s) { + const l = h('label', 'act-field'); + l.appendChild(document.createTextNode(input.label)); + const area = input.lines ? h('textarea') : h('input'); + if (input.lines) area.rows = input.lines; else area.type = 'text'; + if (input.max) area.maxLength = input.max; + if (input.placeholder) area.placeholder = input.placeholder; + area.value = s.text[input.name] || ''; area.dataset.key = key + ':field:' + input.name; area.disabled = !!s.busy; + area.autocomplete = 'off'; area.spellcheck = false; + area.addEventListener('input', () => { s.text[input.name] = area.value; }); + area.addEventListener('keydown', e => { if (e.key === 'Enter' && !input.lines) { e.preventDefault(); const b = area.closest('.act-group').querySelector('button.act'); if (b && !b.disabled) b.click(); } }); + l.appendChild(area); + if (input.max && input.max <= 1000) l.appendChild(h('span', 'hint', 'at most ' + input.max + ' characters')); + return l; + } + function refill(key) { for (const g of groups(key)) fill(g); } + function focusKey(dataKey) { const e = [...document.querySelectorAll('[data-key]')].find(x => x.dataset.key === dataKey && x.offsetParent !== null); if (e) { e.focus(); return true; } return false; } + function leave(key) { const s = slot(key), was = s.confirming; s.confirming = null; refill(key); if (was) focusKey(key + ':' + was); } + /** Escape: leaves every two-press state not waiting for its answer; true when one was left. */ + function escape() { + let left = false; + for (const [key, s] of slots) if (s.confirming && !s.busy) { leave(key); left = true; } + return left; + } + async function press(key, it, confirmed) { + const s = slot(key); + if (s.busy) return; + if (it.confirm && !confirmed) { s.confirming = it.id; s.refusal = null; refill(key); focusKey(key + ':' + (it.input && !it.input.always ? 'field:' + it.input.name : it.id + ':confirm')); return; } + s.busy = it.id; s.refusal = null; refill(key); + let result, error = null; + try { result = await P.call(it.op, it.args ? it.args(s) : {}); } catch (e) { error = e; } + s.busy = null; + if (error) { + s.refusal = { error, item: it.id }; refill(key); + focusKey(key + ':' + it.id) || focusKey(key + ':' + it.id + ':confirm'); + await hooks.refused({ key, item: it, error }); + return; + } + s.confirming = null; s.text = {}; refill(key); + P.forgetAll(); + if (it.done) it.done(result); + await hooks.changed({ key, item: it, result, focus: key + ':' + it.id }); + } + + /** A refusal in the server's words: its sentence, its problems, what it names; extra under them. */ + function refusal(error, extra) { + const box = h('div', 'failure refusal'); box.setAttribute('role', 'alert'); + box.appendChild(h('p', null, error.message || String(error))); + const problems = error.problems || []; + if (problems.length) { + const ul = h('ul'); + for (const p of problems) { + const where = [p.path, p.pointer].filter(x => x && x !== '/').join(' '); + ul.appendChild(h('li', null, (p.severity === 'warning' ? 'Warning: ' : '') + (where ? where + ': ' : '') + (p.message || ''))); + } + box.appendChild(ul); + } + if (error.references && error.references.length) box.appendChild(h('p', 'small', 'Named: ' + error.references.join(', ') + '.')); + if (error.files && error.files.length) box.appendChild(h('p', 'small', 'Files: ' + error.files.join(', ') + '.')); + if (extra) box.appendChild(extra); + return box; + } + + // ---- The strip's Save and the controls of Needs you --------------------------- + const plural = (n, one, many) => n + ' ' + (n === 1 ? one : many); + /** Save, with a refusal changed-on-disk offering to read the project again. */ + const saveItem = () => ({ + id: 'save', label: 'Save', cls: 'btn sm', who: 'edit', op: 'save', busy: 'Saving…', + extra: error => { if (error.code !== 'changed-on-disk') return null; const b = btn('btn sm', 'Read the project again', 'reread'); b.addEventListener('click', () => hooks.reread()); const d = h('div', 'actions'); d.appendChild(b); return d; } + }); + /** The strip's part: how many definitions are unsaved or marked removed, and Save. */ + function stripSave(status, note) { + const n = status.unsaved.length + status.removed.length; + if (!n) { if (note) note.textContent = ''; return null; } + const box = h('span', 'unsaved'); + box.appendChild(h('span', 'count', plural(n, 'definition', 'definitions') + ' unsaved')); + box.appendChild(group('save', [saveItem()], { inline: true, refusalIn: note })); + return box; + } + /** The controls under one item of Needs you (adapter.needs): go(screen, id) opens a place. */ + function needControls(n, go) { + const items = []; + if (n.request) { + const id = n.request.id; + items.push({ id: 'approve', label: 'Approve', cls: 'btn sm primary', who: 'owner', op: 'approve_build', args: () => ({ request: id }), busy: 'Approving…' }); + items.push(declineItem(id)); + items.push({ id: 'open', label: 'Open on Train', cls: 'btn sm ghost', onClick: () => go('train', 'request:' + id) }); + } else if (n.save) { + items.push(saveItem()); + for (const ref of n.references.slice(0, 6)) { + const where = ref.startsWith('recipes/') ? 'map' : ref.startsWith('datasets/') ? 'data' : null; + if (where) items.push({ id: 'open-' + ref, label: ref, cls: 'btn sm ghost', onClick: () => go(where, ref) }); + } + } else if (n.environment) { + const e = n.environment; + if (e.interpreter) items.push(checkItem(e.reference)); + items.push({ id: 'open', label: 'On Train', cls: 'btn sm ghost', onClick: () => go('train', 'env:' + e.reference) }); + } else if (n.run) { + items.push({ id: 'run', label: 'The run', cls: 'btn sm ghost', onClick: () => go('train', 'run:' + n.run.id) }); + items.push({ id: 'plan', label: 'Plan build', cls: 'btn sm', who: 'request', onClick: () => go('train', 'plan:' + n.reference) }); + } + if (!items.length) return null; + return group('need:' + (n.save ? 'save' : n.key), items); + } + const declineItem = id => ({ id: 'decline', label: 'Decline', cls: 'btn sm', who: 'owner', op: 'decline_build', busy: 'Declining…', + confirm: 'Decline this request; the reason is kept with it and shown to whoever asked.', + input: { name: 'reason', label: 'Reason (optional)', max: 400, lines: 2 }, + args: s => ({ request: id, reason: (s.text.reason || '').trim() }) }); + const checkItem = reference => ({ id: 'check', label: 'Check again', cls: 'btn sm', who: 'edit', op: 'check_environment', args: () => ({ reference }), busy: 'Checking…' }); + + // ---- The plan view ------------------------------------------------------------ + const ACTION = { + build: ['pending', 'Build'], built: ['good', 'Built already'], ready: ['good', 'Ready'], + 'set-up': ['warn', 'Set up first'], blocked: ['serious', 'Blocked'] + }; + const gb = x => (x >= 100 ? Math.round(x) : x >= 1 ? x.toFixed(1) : x >= 0.01 ? x.toFixed(2) : x > 0 ? x.toExponential(1) : '0') + ' GB'; + const hours = x => x >= 1 ? x.toFixed(1) + ' h' : x * 60 >= 1 ? Math.round(x * 60) + ' min' : x > 0 ? Math.max(1, Math.round(x * 3600)) + ' s' : '0 h'; + /** What one step would do, in sentences. */ + function stepWords(st) { + const out = []; + if (st.action === 'build') { + out.push({ 'not-built': 'Not built yet: it will be built.', 'out-of-date': 'Out of date: it will be built again.', failed: 'Its last run failed: it will be built again.', running: 'Running now: a build will not start it a second time.' }[st.state] || 'It will be built.'); + for (const r of st.reasons || []) out.push(r); + } else if (st.action === 'built') out.push('Built already' + (st.adopted ? ' (adopted)' : '') + (st.scratch ? ', by a run from the code as it was on disk' : '') + ': nothing to do.'); + else if (st.action === 'ready') out.push('Ready on this machine.'); + else if (st.action === 'set-up') out.push(st.state === 'failing' ? 'Its last check failed: check it or connect another interpreter on Train before building.' : 'Not set up on this machine: connect an interpreter on Train, or set it up from the command line, before building.'); + else if (st.action === 'blocked') { + if (!st.blocked_by.length) out.push(st.kind === 'benchmark' ? 'Blocked: none of its subjects would run.' : 'Blocked.'); + for (const c of st.blocked_by) out.push('Blocked: ' + (c.reference === st.reference ? 'it is' : c.reference + ' is') + ' labelled rebuild ' + c.rebuild + (c.reason ? ' (' + c.reason + ')' : '') + '.'); + if (st.blocked_by_more) out.push('And ' + plural(st.blocked_by_more, 'more cause', 'more causes') + '.'); + } + const uses = Object.entries(st.inputs || {}).map(([name, i]) => name + ' from ' + i.reference + (i.output ? ' (' + i.output + ')' : '')); + if (uses.length) out.push('Uses ' + uses.join(', ') + '.'); + if (st.environment && st.kind !== 'environment') out.push('Runs in ' + st.environment + '.'); + if (st.subjects) { + if (st.subjects.run.length) out.push('Runs the subjects ' + st.subjects.run.join(', ') + '.'); + for (const k of st.subjects.skipped) out.push('Skips ' + k.name + ': ' + k.reason + '.'); + } + if (st.action === 'build') { + const r = st.resources || {}, said = []; + if (r.gpu === true) said.push('uses the GPU'); + if (typeof r.disk_gb === 'number') said.push(gb(r.disk_gb) + ' of disk'); if (typeof r.wall_hours === 'number') said.push(hours(r.wall_hours)); + out.push(said.length ? 'Declares: ' + said.join(', ') + '.' : 'Declares no GPU, disk or time.'); + const e = st.estimate; + if (e) { const est = []; if (e.disk_bytes != null) est.push(gb(e.disk_bytes / 1e9) + ' of disk'); if (e.wall_seconds != null) est.push(hours(e.wall_seconds / 3600)); if (est.length) out.push('Estimated: ' + est.join(', ') + '.'); } + } + return out; + } + /** The totals of a plan: GPU steps, disk and time as stated, estimated or unknown. */ + function totals(plan) { + const n = plan.counts.build, out = []; + if (!n) return ['Nothing would be built, so there are no totals.']; + out.push('To build: ' + plural(n, 'step', 'steps') + ', ' + (plan.gpu_steps ? plan.gpu_steps + ' of them on the GPU' : 'none on the GPU') + '.'); + for (const [name, sum, unknown, est, estSteps, fmt] of [['Disk', plan.disk_gb, plan.disk_unknown, plan.estimated_disk_gb, plan.estimated_disk_steps, gb], ['Time', plan.wall_hours, plan.wall_unknown, plan.estimated_wall_hours, plan.estimated_wall_steps, hours]]) { + let t = name + ': ' + (unknown === n ? 'unknown, no step states it' : fmt(sum) + ' stated' + (unknown ? '; ' + unknown + ' of ' + n + ' state none, so it is more' : '')); + t += estSteps ? '; estimated ' + fmt(est) + ' for ' + plural(estSteps, 'step', 'steps') + ' that were measured.' : '; no estimate was measured.'; + out.push(t); + } + out.push('The figures are as the definitions state them; nothing was run to make this plan.'); + return out; + } + /** + * The plan view in the drawer, for sel 'plan:,' or + * 'plan:*' (everything buildable): read with `plan`, shown in sentences, + * with the scratch box and Request build. back(): leaves the view. + */ + function planView(aside, sel, go, back) { + if (aside._for === sel) return; + aside._for = sel; aside.textContent = ''; + const every = sel === 'plan:*', targets = every ? [] : sel.slice(5).split(',').filter(Boolean); + aside.appendChild(h('p', 'note', 'Reading…')); + P.read('plan', { targets, every }).then(plan => { + if (aside._for !== sel) return; + aside.textContent = ''; + const ins = h('div', 'inspector plan-view'); + const hd = h('header'); hd.appendChild(h('span', 'kicker', 'plan · nothing runs until it is requested')); + const title = h('h2', null, every ? 'A build of everything buildable' : 'A build of ' + plan.targets.join(', ')); title.tabIndex = -1; hd.appendChild(title); + const c = plan.counts, meta = h('div', 'ins-meta'); + meta.appendChild(window.LabScreens.stateEl(plan.buildable ? (c.build ? 'good' : 'neutral') : 'serious', plan.buildable ? (c.build ? 'can be built' : 'nothing to build') : 'cannot be built')); + hd.appendChild(meta); ins.appendChild(hd); + if (back) { const a = h('div', 'actions'); const b = btn('btn sm ghost', '← Back', 'plan-back'); b.addEventListener('click', back); a.appendChild(b); ins.appendChild(a); } + const parts = [plural(c.build, 'step', 'steps') + ' to build', c['set-up'] + ' to set up', c.blocked + ' blocked']; + if (c.ready) parts.push(plural(c.ready, 'environment', 'environments') + ' ready'); + if (c.built) parts.push(c.built + ' built already'); + ins.appendChild(h('p', 'plan-lead', parts.join(', ') + ': ' + (plan.buildable ? (every ? 'everything buildable' : plan.targets.join(', ')) + (c.build ? ' can be built.' : ' is built already.') : (plan.blocked_targets.join(', ') + (plan.blocked_targets.length === 1 ? ' cannot' : ' cannot') + ' be built.')))); + if (plan.blocked_targets.length) ins.appendChild(h('p', 'failure', 'Blocked ' + (plan.blocked_targets.length === 1 ? 'target' : 'targets') + ': ' + plan.blocked_targets.join(', ') + '. A build is refused while any target is blocked; the steps below say why.')); + const d = h('div'); d.appendChild(h('h3', null, 'Steps, in the order they would run')); + if (!plan.steps.length) d.appendChild(h('p', 'note', 'No step: nothing here is built by Tuldok.')); + const ol = h('ol', 'steps'); + for (const st of plan.steps) { + const [tone, word] = ACTION[st.action] || ['neutral', st.action]; + const li = h('li', st.action === 'build' ? 'todo' : st.action === 'blocked' ? 'blocked' : 'done'); li.dataset.step = st.reference; + li.appendChild(window.LabScreens.stateEl(tone, '')); + const t = h('span'); t.appendChild(h('span', 'title', st.number + '. ' + word + ' · ' + (st.title || st.reference))); + t.appendChild(h('span', 'sub mono', st.reference + (st.action === 'build' && st.resources && st.resources.gpu === true ? ' · GPU' : ''))); + for (const line of stepWords(st)) t.appendChild(h('span', 'sub', line)); + li.appendChild(t); ol.appendChild(li); + } + d.appendChild(ol); ins.appendChild(d); + const tt = h('div'); tt.appendChild(h('h3', null, 'What it takes')); for (const line of totals(plan)) tt.appendChild(h('p', 'small', line)); ins.appendChild(tt); + if (plan.notes.length) { const nd = h('div'); nd.appendChild(h('h3', null, 'Notes')); for (const n of plan.notes) nd.appendChild(h('p', 'small', n)); ins.appendChild(nd); } + if (may('request')) { + const key = 'request:' + sel, s = slot(key); + const f = h('div', 'form'); + const lab = h('label', 'check'); const box = h('input'); box.type = 'checkbox'; box.checked = !!s.text.scratch; box.dataset.key = key + ':scratch'; + box.addEventListener('change', () => { s.text.scratch = box.checked; }); + lab.appendChild(box); lab.appendChild(document.createTextNode(' Run from the code as it is on disk; the product is marked scratch')); + f.appendChild(lab); ins.appendChild(f); + const label = isAgent() ? 'Ask the owner for this build' : 'Request build'; + ins.appendChild(group(key, [{ id: 'request', label, cls: 'btn primary', who: 'request', op: 'request_build', busy: isAgent() ? 'Asking…' : 'Requesting…', + args: st => ({ targets, every, scratch: !!st.text.scratch }), done: r => go('train', 'request:' + r.id) }])); + ins.appendChild(h('p', 'note', isAgent() ? 'The owner approves or declines what you ask for; nothing runs before.' : 'Your request is queued at once and runs when the build worker takes it.')); + } + aside.appendChild(ins); + }, error => { if (aside._for !== sel) return; aside.textContent = ''; aside.appendChild(refusal(error)); }); + } + + // ---- The conflict panel -------------------------------------------------------- + /** The main area when a read was refused conflict: the server's sentence, the definitions, and the two ways out. */ + function conflictPanel(main, error) { + const sec = h('section', 'conflict'); + const t = h('h2', null, 'Files changed on disk where Tuldok holds unsaved edits'); t.tabIndex = -1; sec.appendChild(t); + sec.appendChild(h('p', null, error.message)); + const refs = error.references || []; + if (refs.length) { const ul = h('ul', 'conflict-refs'); for (const r of refs) ul.appendChild(h('li', 'mono', r)); sec.appendChild(ul); } + sec.appendChild(h('p', 'note', 'Keep my edits: the unsaved edits stay and replace those files when you save. Take the files: the unsaved edits of ' + (refs.length === 1 ? 'this definition are' : 'these definitions are') + ' dropped and the files are read as they are now.')); + const g = group('conflict', [ + { id: 'keep', label: 'Keep my edits', cls: 'btn primary', who: 'edit', op: 'resolve_conflict', args: () => ({ choice: 'keep' }), busy: 'Keeping…' }, + { id: 'discard', label: 'Take the files', cls: 'btn', who: 'edit', op: 'resolve_conflict', args: () => ({ choice: 'discard' }), busy: 'Taking the files…', + confirm: 'Drop the unsaved edits of ' + (refs.length ? refs.join(', ') : 'these definitions') + ' and take the files on disk.' } + ]); + sec.appendChild(g); + if (g.hidden) sec.appendChild(h('p', 'note', 'Someone who may edit this project has to choose; until then the project cannot be read.')); + main.appendChild(sec); + } + + return { may, isAgent, connect, group, slot, escape, refusal, stripSave, needControls, planView, conflictPanel, declineItem, checkItem, focusKey }; +})(); diff --git a/static/project-workspace/adapter.js b/static/project-workspace/adapter.js index 0750bdb8..b920e083 100644 --- a/static/project-workspace/adapter.js +++ b/static/project-workspace/adapter.js @@ -4,7 +4,10 @@ // /api/agent/capabilities (never pinned here), keeps each answer until it is // read again, and shapes what the screens read: the map's sections, models // and lines, the sentence of where the project stands, and what needs the -// person. It only reads: no operation that changes the project is called. +// person. It reads on its own; an operation that changes the project is +// called only by a control the person pressed (actions.js), after which every +// kept answer is forgotten. A refusal is thrown as an Error carrying the +// server's code, problems, references and files. window.TuldokProject = (() => { // Kinds of change, by the project format's names, with the brief's labels. const KINDS = [ @@ -30,7 +33,8 @@ window.TuldokProject = (() => { async function json(response) { let value; try { value = await response.json(); } catch (e) { throw Error('The server answered ' + response.status + ' without JSON.'); } - if (!response.ok) throw Object.assign(Error(value.error || 'The request was refused.'), { code: value.code }); + if (!response.ok) throw Object.assign(Error(value.error || 'The request was refused.'), { code: value.code, status: response.status, + problems: Array.isArray(value.problems) ? value.problems : [], references: Array.isArray(value.references) ? value.references : [], files: Array.isArray(value.files) ? value.files : [] }); return value; } async function selection(name) { @@ -63,6 +67,7 @@ window.TuldokProject = (() => { return kept.get(key); } function forget(names) { for (const key of [...kept.keys()]) if (names.includes(key.split(' ')[0])) kept.delete(key); } + function forgetAll() { kept.clear(); } // ---- The map ------------------------------------------------------------ /** @@ -151,23 +156,23 @@ window.TuldokProject = (() => { const out = []; for (const r of requests) if (r.state === 'awaiting-approval') { const who = r.requested_by && (r.requested_by.label || r.requested_by.kind) || 'someone'; - out.push({ kind: 'approval', text: 'A build of ' + (r.every ? 'everything buildable' : listed(r.targets || [])) + ', asked by ' + who + ' on ' + day(r.requested_at) + ', awaits your approval.' }); + out.push({ kind: 'approval', key: 'request:' + r.id, request: r, text: 'A build of ' + (r.every ? 'everything buildable' : listed(r.targets || [])) + ', asked by ' + who + ' on ' + day(r.requested_at) + ', awaits your approval.' }); } - if (status.unsaved.length) out.push({ kind: 'changed', text: plural(status.unsaved.length, 'definition has', 'definitions have') + ' unsaved edits: ' + listed(status.unsaved.map(String)) + '.' }); - if (status.removed.length) out.push({ kind: 'changed', text: plural(status.removed.length, 'definition is', 'definitions are') + ' marked removed and not yet saved: ' + listed(status.removed.map(String)) + '.' }); + if (status.unsaved.length) out.push({ kind: 'changed', key: 'unsaved', save: true, references: status.unsaved.map(String), text: plural(status.unsaved.length, 'definition has', 'definitions have') + ' unsaved edits: ' + listed(status.unsaved.map(String)) + '.' }); + if (status.removed.length) out.push({ kind: 'changed', key: 'removed', save: true, references: status.removed.map(String), text: plural(status.removed.length, 'definition is', 'definitions are') + ' marked removed and not yet saved: ' + listed(status.removed.map(String)) + '.' }); const disk = [].concat(status.added, status.changed, status.missing).map(String); if (disk.length) out.push({ kind: 'changed', text: plural(disk.length, 'file changed', 'files changed') + ' on disk since the project was last read: ' + listed(disk) + '.' }); if (status.irregular.length) out.push({ kind: 'missing', text: plural(status.irregular.length, 'file is', 'files are') + ' not regular files and are not read: ' + listed(status.irregular.map(String)) + '.' }); const results = [].concat(status.results_unsaved, status.results_changed).map(String); if (results.length) out.push({ kind: 'changed', text: 'Results differ from their files: ' + listed(results) + '.' }); - for (const e of environments) if (e.state !== 'ready') out.push({ kind: e.state === 'failing' ? 'missing' : 'changed', text: 'The environment ' + e.title + (e.state === 'failing' ? ' failed its last check.' : ' is not set up on this machine.') }); + for (const e of environments) if (e.state !== 'ready') out.push({ kind: e.state === 'failing' ? 'missing' : 'changed', key: 'env:' + e.reference, environment: e, text: 'The environment ' + e.title + (e.state === 'failing' ? ' failed its last check.' : ' is not set up on this machine.') }); const last = new Map(); for (const r of runs) if (!last.has(r.reference)) last.set(r.reference, r); // runs come newest first - for (const [reference, r] of last) if (ENDED_BADLY[r.state]) out.push({ kind: 'missing', text: 'The last run of ' + titleOf(shaped, reference) + ' ' + ENDED_BADLY[r.state] + (r.finished_at ? ' on ' + day(r.finished_at) : '') + '.' }); + for (const [reference, r] of last) if (ENDED_BADLY[r.state]) out.push({ kind: 'missing', key: 'run:' + r.id, run: r, reference, text: 'The last run of ' + titleOf(shaped, reference) + ' ' + ENDED_BADLY[r.state] + (r.finished_at ? ' on ' + day(r.finished_at) : '') + '.' }); if (summary.worker === 'stopped') out.push({ kind: 'changed', text: 'The build worker is stopped: queued builds will not start.' }); if (summary.worker === 'elsewhere') out.push({ kind: 'changed', text: 'Another Tuldok process runs the builds of this project.' }); return out; } - return { KINDS, UNSET, kindLabel, stateWord, call, read, forget, map, trackName, better, units, standing, needs, titleOf, day }; + return { KINDS, UNSET, kindLabel, stateWord, call, read, forget, forgetAll, map, trackName, better, units, standing, needs, titleOf, day }; })(); diff --git a/static/project-workspace/app.js b/static/project-workspace/app.js index bb843cca..ebe4ab1b 100644 --- a/static/project-workspace/app.js +++ b/static/project-workspace/app.js @@ -4,16 +4,20 @@ // drawer, and when the project is read. The first screen reads summary and // map; the strip's other sources are read right after; a tab reads what it // needs when it is first shown; everything is read again when the window -// regains focus, and while a build is queued or running the strip asks again -// every two seconds for what can change. +// regains focus and after a control's answer (actions.js). While a build is +// queued or running the strip asks again every two seconds for what can +// change, the open run reads on its progress and logs, and when a run ends +// the map and everything else is read again, so a model turns to built +// without a reload. A read refused conflict shows the conflict panel. (() => { - const P = window.TuldokProject, S = window.LabScreens; + const P = window.TuldokProject, S = window.LabScreens, A = window.LabActions; const TABS = [['map', 'Map'], ['data', 'Data'], ['train', 'Train'], ['benchmarks', 'Benchmarks'], ['analysis', 'Analysis'], ['overview', 'Overview']]; const POLL_MS = 2000; + const ACTIVE_RUN = ['queued', 'running'], ACTIVE_REQUEST = ['queued', 'running']; const $ = id => document.getElementById(id); const state = { screen: 'map', sel: {}, kinds: null, query: '', zoom: 1, track: false, ui: {}, benchmark: null, cmp: [] }; - const data = { summary: null, map: null, standing: null, needs: null, readAt: '', polling: false }; - let failed = null, mapText = null, pollTimer = null; + const data = { summary: null, map: null, standing: null, needs: null, status: null, readAt: '', polling: false }; + let failed = null, conflict = null, mapText = null, pollTimer = null, states = null, opener = null; const clock = () => new Date().toLocaleTimeString('en-GB', { hour: '2-digit', minute: '2-digit' }); function parse() { @@ -22,7 +26,14 @@ state.screen = TABS.some(t => t[0] === screen) ? screen : 'map'; if (id) state.sel[state.screen] = id; else delete state.sel[state.screen]; } - function go(screen, id) { const next = '#' + screen + (id ? '/' + encodeURIComponent(id) : ''); if (location.hash === next) { parse(); render(); } else location.hash = next; } + function go(screen, id) { + // What opened a drawer gets the focus back when it closes. + if (id && !state.sel[screen]) opener = document.activeElement && document.activeElement.dataset ? { key: document.activeElement.dataset.key || null, el: document.activeElement } : null; + const closing = !id && state.sel[screen]; + const next = '#' + screen + (id ? '/' + encodeURIComponent(id) : ''); + if (location.hash === next) { parse(); render(); } else location.hash = next; + if (closing && opener) { const o = opener; opener = null; setTimeout(() => { if (o.el && o.el.isConnected) o.el.focus(); else if (o.key) A.focusKey(o.key); }, 0); } + } const act = { go, select: id => go(state.screen, id || undefined), setQuery: q => { state.query = q; render(); }, @@ -33,7 +44,9 @@ setUI: (k, v) => { state.ui[k] = v; render(); }, setBenchmark: name => { state.benchmark = name; state.cmp = []; address(); render(); }, toggleCompare: id => { const i = state.cmp.indexOf(id); if (i >= 0) state.cmp.splice(i, 1); else if (state.cmp.length < 3) state.cmp.push(id); address(); render(); }, - clearCompare: () => { state.cmp = []; address(); render(); } + clearCompare: () => { state.cmp = []; address(); render(); }, + /** Reads everything again (a control's answer came, or a view asks for it). */ + refresh: () => changed() }; /** Writes the benchmark and compare set into the address without reloading, so the view can be shared. */ function address() { @@ -44,24 +57,43 @@ history.replaceState(null, '', location.pathname + (text ? '?' + text : '') + location.hash); } + /** Rebuilds container with build(), giving back the focused control (by data-key), its caret and the scroll. */ + function keepFocus(container, build) { + const active = document.activeElement, key = active && container.contains(active) && active.dataset ? active.dataset.key : null; + const caret = key && typeof active.selectionStart === 'number' ? active.selectionStart : null, top = container.scrollTop; + build(); + container.scrollTop = top; + if (key) { const again = [...container.querySelectorAll('[data-key]')].find(e => e.dataset.key === key); if (again) { again.focus({ preventScroll: true }); if (caret !== null && again.setSelectionRange) again.setSelectionRange(caret, caret); } } + } + // ---- The status strip and Needs you --------------------------------------- function strip() { - const el = $('strip'); el.textContent = ''; - if (failed) { el.appendChild(S.stateEl('serious', 'Not read')); el.appendChild(Object.assign(document.createElement('span'), { className: 'msg', textContent: failed })); return; } - if (!data.standing) { el.appendChild(Object.assign(document.createElement('span'), { className: 'msg', textContent: 'Reading the project…' })); return; } - el.appendChild(S.stateEl(data.standing.tone, data.standing.word)); - if (data.progress) { const hair = document.createElement('span'); hair.className = 'hair'; const i = document.createElement('i'); i.style.width = Math.round(100 * data.progress.completed / Math.max(1, data.progress.total)) + '%'; hair.appendChild(i); hair.title = data.progress.stage + ' ' + data.progress.completed + ' of ' + data.progress.total; el.appendChild(hair); } - const m = document.createElement('span'); m.className = 'msg'; - m.textContent = data.standing.text + (data.progress ? ' ' + data.progress.stage + ': ' + data.progress.completed + ' of ' + data.progress.total + '.' : '') + ' Read at ' + data.readAt + '.'; - el.appendChild(m); - const b = document.createElement('button'); b.className = 'btn sm needs-btn'; b.type = 'button'; b.id = 'needs-btn'; - b.textContent = 'Needs you · ' + (data.needs ? data.needs.length : '…'); b.disabled = !data.needs; - const panel = $('needs-panel'); b.setAttribute('aria-expanded', String(!panel.hidden)); b.setAttribute('aria-controls', 'needs-panel'); - b.addEventListener('click', () => { panel.hidden = !panel.hidden; b.setAttribute('aria-expanded', String(!panel.hidden)); fillNeeds(); }); - el.appendChild(b); + const el = $('strip'); + keepFocus(el, () => { + el.textContent = ''; + if (failed) { el.appendChild(S.stateEl('serious', conflict ? 'Conflict' : 'Not read')); el.appendChild(Object.assign(document.createElement('span'), { className: 'msg', textContent: failed })); return; } + if (!data.standing) { el.appendChild(Object.assign(document.createElement('span'), { className: 'msg', textContent: 'Reading the project…' })); return; } + el.appendChild(S.stateEl(data.standing.tone, data.standing.word)); + if (data.progress) { const hair = document.createElement('span'); hair.className = 'hair'; const i = document.createElement('i'); i.style.width = Math.round(100 * data.progress.completed / Math.max(1, data.progress.total)) + '%'; hair.appendChild(i); hair.title = data.progress.stage + ' ' + data.progress.completed + ' of ' + data.progress.total; hair.setAttribute('role', 'progressbar'); hair.setAttribute('aria-valuemin', '0'); hair.setAttribute('aria-valuemax', String(data.progress.total)); hair.setAttribute('aria-valuenow', String(data.progress.completed)); el.appendChild(hair); } + const m = document.createElement('span'); m.className = 'msg'; + m.textContent = data.standing.text + (data.progress ? ' ' + data.progress.stage + ': ' + data.progress.completed + ' of ' + data.progress.total + '.' : '') + ' Read at ' + data.readAt + '.'; + el.appendChild(m); + const save = data.status ? A.stripSave(data.status, $('strip-note')) : null; + if (save) el.appendChild(save); else $('strip-note').textContent = ''; + const b = document.createElement('button'); b.className = 'btn sm needs-btn'; b.type = 'button'; b.id = 'needs-btn'; b.dataset.key = 'needs-btn'; + b.textContent = 'Needs you · ' + (data.needs ? data.needs.length : '…'); b.disabled = !data.needs; + const panel = $('needs-panel'); b.setAttribute('aria-expanded', String(!panel.hidden)); b.setAttribute('aria-controls', 'needs-panel'); + b.addEventListener('click', () => { panel.hidden = !panel.hidden; b.setAttribute('aria-expanded', String(!panel.hidden)); fillNeeds(); }); + el.appendChild(b); + }); fillNeeds(); } - function fillNeeds() { const panel = $('needs-panel'); if (panel.hidden || !data.needs) return; panel.textContent = ''; panel.appendChild(S.needsList(data.needs)); } + /** Places Needs you sends to: the panel closes and the focus goes to the drawer that opens. */ + function needsGo(screen, id) { const panel = $('needs-panel'); panel.hidden = true; const b = $('needs-btn'); if (b) b.setAttribute('aria-expanded', 'false'); opener = { key: 'needs-btn', el: null }; go(screen, id); } + function fillNeeds() { + const panel = $('needs-panel'); if (panel.hidden || !data.needs) return; + keepFocus(panel, () => { panel.textContent = ''; panel.appendChild(S.needsList(data.needs, n => A.needControls(n, needsGo))); }); + } // ---- Rendering -------------------------------------------------------------- function render() { @@ -71,9 +103,10 @@ const name = data.summary ? data.summary.name : ''; document.title = TABS.find(t => t[0] === state.screen)[1] + (name ? ' · ' + name : '') + ' · Tuldok'; if (failed || !data.map) { - main.className = 'content'; main.textContent = ''; main._tree = null; - const p = document.createElement('p'); p.className = failed ? 'failure' : 'note'; p.textContent = failed || 'Reading the project…'; main.appendChild(p); - drawer.classList.remove('open'); drawer.setAttribute('aria-hidden', 'true'); main.classList.remove('with-drawer'); + main.className = 'content'; main.textContent = ''; main._tree = null; main._view = null; main._painted = null; + if (conflict) A.conflictPanel(main, conflict); + else { const p = document.createElement('p'); p.className = failed ? 'failure' : 'note'; p.textContent = failed || 'Reading the project…'; main.appendChild(p); } + drawer.classList.remove('open'); drawer.setAttribute('aria-hidden', 'true'); main.classList.remove('with-drawer'); aside.textContent = ''; aside._for = null; return; } const wasMap = main.classList.contains('map'), view = state.screen + '/' + (state.screen === 'overview' ? state.sel.overview || '' : ''); // a selection elsewhere opens the drawer and keeps the place @@ -84,6 +117,7 @@ drawer.classList.toggle('open', !!has); drawer.setAttribute('aria-hidden', String(!has)); main.classList.toggle('with-drawer', !!has); if (!has) aside._for = null; } + function fail(error) { failed = error.message; conflict = error.code === 'conflict' ? error : null; } // ---- Reading ------------------------------------------------------------------ async function first() { @@ -91,45 +125,96 @@ data.summary = await P.read('summary'); $('projname').textContent = data.summary.name; data.map = await P.map(); mapText = JSON.stringify(await P.read('map')); - data.standing = P.standing(data.map, null, null); data.readAt = clock(); failed = null; - } catch (error) { failed = error.message; } + data.standing = P.standing(data.map, null, null); data.readAt = clock(); failed = null; conflict = null; + } catch (error) { fail(error); } strip(); render(); if (!failed) await standing(); } - /** The strip's other sources: status, build requests, environments and runs. */ + /** + * The strip's other sources: status, build requests, environments and runs. + * Asks again in two seconds while a build is queued or running. Compares + * the states of the runs and requests with the last reading: when a run + * has ended everything is read again (the map too); when the open run or + * request changed state, its drawer is drawn again. + */ async function standing() { + let ended = false, moved = new Set(), lists = null; try { const [status, requests, environments, runs] = await Promise.all([P.read('status'), P.read('build_requests'), P.read('environments'), P.read('runs')]); + lists = [runs.runs, requests.requests]; + data.status = status; data.standing = P.standing(data.map, runs.runs, requests.requests); data.needs = P.needs({ summary: data.summary, status, requests: requests.requests, environments: environments.environments, runs: runs.runs, shaped: data.map }); const running = runs.runs.find(r => r.state === 'running'); data.progress = running ? (await P.call('progress', { run: running.id })).event : null; data.readAt = clock(); - const busy = !!running || requests.requests.some(r => r.state === 'queued' || r.state === 'running'); + const now = new Map(runs.runs.map(r => ['run:' + r.id, r.state]).concat(requests.requests.map(r => ['request:' + r.id, r.state]))); + if (states) for (const [key, st] of now) { + const was = states.get(key); + if (was !== st) moved.add(key); + // A run or a request that was active and is no more, or a run that came and went between two readings. + if (key.startsWith('run:') ? (was === undefined || ACTIVE_RUN.includes(was)) && !ACTIVE_RUN.includes(st) : ACTIVE_REQUEST.includes(was) && !ACTIVE_REQUEST.includes(st)) ended = true; + } + states = now; + const busy = runs.runs.some(r => ACTIVE_RUN.includes(r.state)) || requests.requests.some(r => ACTIVE_REQUEST.includes(r.state)); if (busy && !pollTimer) pollTimer = setTimeout(poll, POLL_MS); - } catch (error) { data.needs = null; data.standing = Object.assign({}, data.standing, { text: data.standing.text + ' ' + error.message }); } + } catch (error) { + if (error.code === 'conflict') { fail(error); strip(); render(); return; } + data.needs = null; data.standing = Object.assign({}, data.standing, { text: data.standing.text + ' ' + error.message }); + } + const aside = $('aside'); + if (ended) { + // A run ended: what it made changes the map, the lists and the drawers. + for (const name of ['summary', 'map', 'definitions', 'definition', 'products', 'recipe_results', 'results_overview', 'results', 'values', 'chart', 'graph', 'activity', 'run', 'build_request', 'plan', 'estimates']) + P.forget([name]); + try { + data.summary = await P.read('summary'); + const text = JSON.stringify(await P.read('map')); + if (text !== mapText) { mapText = text; data.map = await P.map(); aside._for = null; if (lists) data.standing = P.standing(data.map, ...lists); } + } catch (error) { fail(error); strip(); render(); return; } + } + let redraw = ended; + if (aside._for && moved.has(aside._for)) { P.forget(['run', 'build_request']); aside._for = null; redraw = true; } strip(); - if (state.screen === 'overview' || state.screen === 'train') render(); + if (redraw || ['overview', 'train'].includes(state.screen)) render(); } async function poll() { pollTimer = null; P.forget(['summary', 'runs', 'build_requests']); try { data.summary = await P.read('summary'); } catch (error) { /* the strip says what failed below */ } await standing(); + if (S.tick) await S.tick(); } /** Everything again, when the window regains focus; the map is redrawn only when it changed. */ async function again() { - if (failed) { P.forget(['summary', 'map']); return first(); } - P.forget(['summary', 'status', 'build_requests', 'environments', 'runs', 'map', 'activity', 'definitions', 'definition', 'recipe_results', 'products', 'note', - 'graph', 'results_overview', 'results', 'chart', 'values', 'build_request', 'run']); + if (failed) { P.forgetAll(); return first(); } + P.forgetAll(); try { data.summary = await P.read('summary'); const text = JSON.stringify(await P.read('map')); if (text !== mapText) { mapText = text; data.map = await P.map(); $('aside')._for = null; render(); } else if (state.screen !== 'map') render(); - } catch (error) { failed = error.message; render(); } + } catch (error) { fail(error); strip(); render(); return; } await standing(); } + /** After a control's answer: forget everything, read again, draw the drawer afresh; the focus stays on the control when it is still there. */ + async function changed(info) { + P.forgetAll(); + if (failed) { await first(); } + else { + try { + data.summary = await P.read('summary'); + const text = JSON.stringify(await P.read('map')); + if (text !== mapText) { mapText = text; data.map = await P.map(); } + } catch (error) { fail(error); strip(); render(); return; } + $('aside')._for = null; render(); + await standing(); + } + if (info && info.focus && (!document.activeElement || document.activeElement === document.body)) { + if (!A.focusKey(info.focus)) setTimeout(() => { if (document.activeElement === document.body) { const t = $('aside').querySelector('h2') || $('main'); if (t.tabIndex < 0 && t !== $('main')) t.tabIndex = -1; t.focus(); } }, 300); + } + } + A.connect({ changed, refused: () => standing(), reread: () => changed() }); function start() { // auth.js puts its session controls first in the body; they belong at the right of the top bar. @@ -139,12 +224,14 @@ $('close').addEventListener('click', () => go(state.screen)); window.addEventListener('keydown', e => { if (e.key !== 'Escape') return; + if (A.escape()) return; if (!$('needs-panel').hidden) { $('needs-panel').hidden = true; const b = $('needs-btn'); if (b) { b.setAttribute('aria-expanded', 'false'); b.focus(); } return; } if ($('drawer').classList.contains('open') && state.sel[state.screen]) go(state.screen); }); window.addEventListener('hashchange', () => { parse(); render(); }); window.addEventListener('focus', () => { if (data.summary || failed) again(); }); - window.addEventListener('tuldok-session', () => { if (failed) again(); }); + // Who may use a control comes from the session: draw the controls again when it changes. + window.addEventListener('tuldok-session', () => { if (failed) again(); else { $('aside')._for = null; strip(); render(); } }); { const q = new URLSearchParams(location.search); state.benchmark = q.get('benchmark') || null; state.cmp = (q.get('cmp') || '').split(',').filter(Boolean).slice(0, 3); } parse(); strip(); render(); first(); } diff --git a/static/project-workspace/base.css b/static/project-workspace/base.css index 726a4ca8..f86ac31a 100644 --- a/static/project-workspace/base.css +++ b/static/project-workspace/base.css @@ -92,13 +92,15 @@ button { cursor: pointer; } border: 1px solid var(--line-strong); border-radius: var(--radius); background: var(--surface); color: var(--ink); } .btn:hover { background: var(--surface-2); } +.btn.primary { background: var(--accent); border-color: var(--accent); color: var(--accent-ink); } +.btn.primary:hover { filter: brightness(1.05); } .btn.ghost { border-color: transparent; background: transparent; } .btn.ghost:hover { background: var(--surface-2); } .btn[disabled] { opacity: .5; cursor: not-allowed; } .btn svg { width: 14px; height: 14px; flex: none; } .btn.sm { min-height: 26px; padding: 2px 8px; font-size: 13px; } .btn[aria-pressed="true"] { background: var(--accent-wash); border-color: var(--accent); } -input[type="search"], input[type="text"], select { +input[type="search"], input[type="text"], select, textarea { min-height: 30px; padding: 4px 8px; border: 1px solid var(--line-strong); border-radius: var(--radius); background: var(--surface); color: var(--ink); } @@ -390,7 +392,7 @@ table.cases-t { margin-top: 8px; } @media (max-width: 1100px) { .row.run { grid-template-columns: 90px minmax(0, 1fr) 70px 130px; } .row.run > .chip { display: none; } } /* ---- The shell: top bar, tabs, status strip, stage, drawer (b-map.html). ---- */ -body.shell { height: 100vh; display: grid; grid-template-rows: 48px auto 1fr; overflow: clip; } /* clip: not even a script or scrollIntoView can scroll the shell */ +body.shell { height: 100vh; display: grid; grid-template-rows: 48px auto auto 1fr; overflow: clip; } /* clip: not even a script or scrollIntoView can scroll the shell */ .top { display: flex; align-items: center; gap: 22px; padding: 0 20px; border-bottom: 1px solid var(--line); background: var(--surface); min-width: 0; } .brand { display: inline-flex; align-items: center; gap: 8px; font-weight: 600; color: var(--ink); flex: none; } .brand:hover { text-decoration: none; } @@ -476,3 +478,61 @@ table.tv.kinds td, table.tv.kinds th { white-space: nowrap; } .card-md th { color: var(--ink-2); font-weight: 500; } .card-md .link { color: var(--ink); text-decoration: underline dotted var(--ink-3); } .card-md .link .href { color: var(--ink-3); font-family: var(--mono); font-size: 11.5px; } + +/* ---- Controls that change the project (actions.js, spec-w3 section 3.1). ---- */ +/* From the mockup's base.css and b-map.html: forms, radios, two columns, steps. */ +textarea { font: inherit; resize: vertical; } +.form { display: grid; gap: 10px; } +.form label { display: grid; gap: 3px; font-size: 12.5px; color: var(--ink-2); } +.form select, .form input[type="text"], .form textarea { width: 100%; font: inherit; color: var(--ink); background: var(--surface); border: 1px solid var(--line-strong); border-radius: var(--radius); padding: 5px 8px; } +.form .two { display: grid; grid-template-columns: 1fr 1fr; gap: 10px; } +.form .hint, .act-field .hint { font-family: var(--mono); font-size: 11.5px; color: var(--ink-3); } +.form .radio { display: flex; flex-wrap: wrap; gap: 6px; } +.form .radio label { display: inline-flex; align-items: center; gap: 6px; padding: 4px 10px; border: 1px solid var(--line-strong); border-radius: 999px; color: var(--ink); cursor: pointer; } +.form .radio input { margin: 0; } +.form .radio label:has(input:checked) { background: var(--accent-wash); border-color: var(--accent); } +.form label.check { display: flex; align-items: flex-start; gap: 8px; color: var(--ink); font-size: 13px; } +.form label.check input { margin: 3px 0 0; flex: none; } +.steps { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: 8px; } +.steps li { display: grid; grid-template-columns: 18px minmax(0, 1fr); gap: 10px; } +.steps li > .state { align-self: start; margin-top: 2px; } +.steps .title { display: block; font-weight: 500; overflow-wrap: anywhere; } +.steps .sub { display: block; font-size: 12.5px; color: var(--ink-2); overflow-wrap: anywhere; } +.steps .sub.mono { font-size: 11.5px; color: var(--ink-3); } +.steps .done .title { color: var(--ink-2); } +.steps .blocked .title { color: var(--serious); } +.act-group { display: grid; gap: 8px; min-width: 0; } +.act-group .actions { display: flex; flex-wrap: wrap; gap: 8px; align-items: flex-end; } +.act-group.inline { display: inline-flex; gap: 8px; align-items: center; } +.act-group.inline > .actions { flex-wrap: nowrap; } +.act-field { display: grid; gap: 3px; font-size: 12.5px; color: var(--ink-2); flex: 1 1 220px; min-width: 0; } +.act-field input, .act-field textarea { width: 100%; min-width: 0; } +.confirm-words { font-size: 13px; color: var(--ink); max-width: 60ch; } +.btn[aria-busy="true"] { cursor: progress; } +.refusal { display: grid; gap: 4px; padding: 8px 10px; border: 1px solid var(--serious); border-radius: var(--radius); background: var(--serious-wash); color: var(--ink); font-size: 13px; } +.refusal > p:first-child { color: var(--serious); font-weight: 500; } +.refusal ul { margin: 0; padding-left: 18px; color: var(--ink); } +.refusal .actions { margin-top: 4px; } +.rows > li.with-act { display: flex; align-items: center; gap: 8px; } +.rows > li.with-act > .row { flex: 1 1 auto; min-width: 0; } +.rows > li.with-act > .act-group { flex: none; margin-right: 8px; } +.sect .act-group { align-self: center; } +.hair { position: relative; display: inline-block; width: 120px; height: 2px; background: var(--grid); flex: none; vertical-align: middle; } +.hair i { position: absolute; left: 0; top: 0; bottom: 0; background: var(--accent); } +.progress-line { display: flex; align-items: center; gap: 10px; flex-wrap: wrap; } +.progress-line .hair { width: 160px; } +.live-note { margin-top: -8px; } +.need { display: grid; gap: 8px; min-width: 0; } +.need .act-group .actions { gap: 6px; } +.strip .unsaved { display: inline-flex; align-items: center; gap: 8px; flex: none; color: var(--warn); font-size: 12.5px; white-space: nowrap; } +.strip .unsaved + .needs-btn { margin-left: 0; } +.strip .unsaved { margin-left: auto; } +.strip-note:not(:empty) { padding: 8px 20px; border-bottom: 1px solid var(--line); background: var(--surface); } +.strip-note .refusal { max-width: 900px; } +.reason { padding: 8px 10px; border-left: 3px solid var(--line-strong); background: var(--surface-2); border-radius: 0 var(--radius) var(--radius) 0; font-size: 13.5px; } +.plan-lead { font-size: 14px; color: var(--ink); } +.conflict { display: grid; gap: 14px; max-width: 760px; } +.conflict h2 { font-size: 17px; } +.conflict-refs { margin: 0; padding-left: 18px; } +.plain { list-style: none; margin: 0; padding: 0; display: grid; gap: 4px; } +.warnline { color: var(--warn); } diff --git a/static/project-workspace/screens.js b/static/project-workspace/screens.js index 968b6546..9f485b5a 100644 --- a/static/project-workspace/screens.js +++ b/static/project-workspace/screens.js @@ -27,10 +27,16 @@ window.LabScreens = (() => { const bytes = b => b == null ? '—' : b >= 1e9 ? (b / 1e9).toFixed(1) + ' GB' : b >= 1e6 ? (b / 1e6).toFixed(1) + ' MB' : b >= 1e3 ? Math.round(b / 1e3) + ' KB' : b + ' B'; const failure = (parent, error) => { parent.appendChild(h('p', 'failure', error.message || String(error))); }; const NEEDS_ICON = { approval: 'clock', changed: 'alert', missing: 'triangle' }; - function needsList(items) { + /** What needs the person, one sentence each; controls(item) gives the controls drawn under a sentence. */ + function needsList(items, controls) { const ul = h('ul', 'needs'); if (!items.length) { ul.appendChild(h('li', 'empty', 'Nothing needs you.')); return ul; } - for (const n of items) { const li = h('li', n.kind); li.appendChild(icon(NEEDS_ICON[n.kind])); li.appendChild(h('span', null, n.text)); ul.appendChild(li); } + for (const n of items) { + const li = h('li', n.kind); li.appendChild(icon(NEEDS_ICON[n.kind])); + const body = h('div', 'need'); body.appendChild(h('span', null, n.text)); + const c = controls ? controls(n) : null; if (c) body.appendChild(c); + li.appendChild(body); ul.appendChild(li); + } return ul; } @@ -38,7 +44,9 @@ window.LabScreens = (() => { let graph = null, graphOf = null; function graphFor(shaped) { if (graphOf !== shaped) { graph = Tree.build(shaped); graphOf = shaped; } return graph; } function map(main, aside, state, act, data) { - const shaped = data.map, g = graphFor(shaped), sel = state.sel.map && g.byId.has(state.sel.map) ? state.sel.map : null; + // A selection 'plan:' is the plan view in the drawer, with its first target selected on the map. + const shaped = data.map, g = graphFor(shaped), raw = state.sel.map || '', planSel = raw.startsWith('plan:') ? raw : null; + const focus = planSel ? planSel.slice(5).split(',')[0] : raw, sel = focus && g.byId.has(focus) ? focus : null; const kinds = P.KINDS.map(k => k.id).concat(g.nodes.some(m => m.kind === P.UNSET) ? [P.UNSET] : []); const withValue = g.nodes.filter(m => m.value != null).length; const buildBar = () => { @@ -70,11 +78,13 @@ window.LabScreens = (() => { if (focused !== null) { const q = bar.querySelector('input[type="search"]'); q.focus(); q.setSelectionRange(focused, focused); } main._tree = inst; } + if (planSel) { window.LabActions.planView(aside, planSel, act.go, sel ? () => act.select(sel) : null); return true; } if (sel) { inspectorModel(aside, sel, act, data); return true; } aside.textContent = ''; aside._for = null; return false; } // ---- Drawer: one model --------------------------------------------------- + const TO_BUILD = ['not-built', 'out-of-date', 'failed']; function inspectorModel(aside, id, act, data) { if (aside._for === id) return; aside._for = id; aside.textContent = ''; @@ -86,6 +96,8 @@ window.LabScreens = (() => { const meta = h('div', 'ins-meta'); meta.appendChild(h('span', 'chip ' + m.kind, P.kindLabel(m.kind))); meta.appendChild(modelState(m.state)); meta.appendChild(h('span', 'small faint', m.trainedAt ? 'trained ' + P.day(m.trainedAt) : 'no training date')); hd.appendChild(meta); ins.appendChild(hd); + // Plan build, for a model to build (spec-w3 section 3.1): the plan view, never a request from here. + if (TO_BUILD.includes(m.state)) ins.appendChild(window.LabActions.group('model:' + m.id, [{ id: 'plan', label: 'Plan build', cls: 'btn primary', who: 'request', onClick: () => act.select('plan:' + m.id) }])); // Lineage: what it was derived from, what derives from it, what it takes as input. const lin = h('div', 'actions'); const jump = (target, text) => { const b = h('button', 'btn sm ghost'); b.type = 'button'; b.appendChild(icon('branch')); b.appendChild(document.createTextNode(' ' + text)); b.addEventListener('click', () => act.select(target.id)); return b; }; @@ -152,45 +164,48 @@ window.LabScreens = (() => { } // ---- Overview -------------------------------------------------------------- + // Read once and built off the page (tabs.js's paint), so the refresh while a build runs keeps the place. function overview(main, aside, state, act, data) { - main.textContent = ''; aside.textContent = ''; aside._for = null; - if (state.sel.overview === 'report') return report(main, data); - const standing = data.standing; - const top = h('section', 'ov-status'); - const line = h('div', 'ov-line'); line.appendChild(stateEl(standing.tone, standing.word)); line.appendChild(h('p', 'ov-text', standing.text)); top.appendChild(line); - top.appendChild(h('p', 'small faint', 'Read at ' + data.readAt)); - main.appendChild(top); - const row = h('div', 'ov-row'); - const needs = h('section'); needs.appendChild(sect('Needs you', data.needs ? String(data.needs.length) : '…')); - if (data.needs) needs.appendChild(needsList(data.needs)); else needs.appendChild(h('p', 'note', 'Reading…')); - row.appendChild(needs); - const facts = h('section'); facts.appendChild(sect('Project')); - const dl = h('dl', 'facts'), s = data.summary; - for (const [k, v, c] of [['Folder', s.folder, 'mono'], ['Code root', s.code_root, 'mono'], ['Project', s.project_id, 'mono'], ['Build worker', s.worker]]) { dl.appendChild(h('dt', null, k)); dl.appendChild(h('dd', c || '', v)); } - dl.appendChild(h('dt', null, 'Report')); const dd = h('dd'); const a = h('a', null, 'Open the report'); a.href = '#overview/report'; dd.appendChild(a); dl.appendChild(dd); - facts.appendChild(dl); row.appendChild(facts); main.appendChild(row); - const cols = h('div', 'ov-cols'); - const defs = h('section'); defs.appendChild(sect('Definitions', String(Object.values(s.kinds).reduce((a, b) => a + b, 0)))); cols.appendChild(defs); - const envs = h('section'); envs.appendChild(sect('Environments', String(s.kinds.environment || 0))); cols.appendChild(envs); - main.appendChild(cols); - const act2 = h('section', 'ov-history'); act2.appendChild(sect('Latest activity')); main.appendChild(act2); - const pending = (b, promise, build) => { const note = h('p', 'note', 'Reading…'); b.appendChild(note); promise.then(v => { note.remove(); build(b, v); }, error => { note.remove(); failure(b, error); }); }; - pending(defs, P.read('definitions'), (b, d) => { - const states = [...new Set(d.definitions.map(x => x.state))].sort(); - const kinds = [...new Set(d.definitions.map(x => x.kind))].sort(); - if (!kinds.length) { b.appendChild(h('p', 'empty', 'The project has no definitions.')); return; } - const t = h('table', 'tv kinds'), th = h('thead'), hr = h('tr'); hr.appendChild(h('th', null, 'Kind')); for (const st of states) hr.appendChild(h('th', 'n', P.stateWord(st)[0])); hr.appendChild(h('th', 'n', 'All')); th.appendChild(hr); t.appendChild(th); - const tb = h('tbody'); for (const k of kinds) { const tr = h('tr'); tr.appendChild(h('td', null, k)); const mine = d.definitions.filter(x => x.kind === k); for (const st of states) { const n = mine.filter(x => x.state === st).length; tr.appendChild(h('td', 'n' + (n ? '' : ' faint'), n ? String(n) : '·')); } tr.appendChild(h('td', 'n', String(mine.length))); tb.appendChild(tr); } t.appendChild(tb); - const wrap = h('div'); wrap.style.overflowX = 'auto'; wrap.appendChild(t); b.appendChild(wrap); - }); - pending(envs, P.read('environments'), (b, e) => { - if (!e.environments.length) { b.appendChild(h('p', 'empty', 'The project defines no environment.')); return; } - const ul = h('ul', 'rows'); for (const env of e.environments) { const li = h('li'); const r = h('div', 'row ov-env'); const t = h('span'); t.appendChild(h('span', 'title', env.title)); t.appendChild(h('span', 'sub', ['Python ' + env.python, env.device, Object.keys(env.packages || {}).length + ' packages', env.checked_at ? 'checked ' + P.day(env.checked_at) : 'never checked'].filter(Boolean).join(' · '))); r.appendChild(t); r.appendChild(modelState(env.state)); li.appendChild(r); ul.appendChild(li); } b.appendChild(ul); - }); - pending(act2, P.read('activity', { limit: 12 }), (b, a) => { - if (!a.items.length) { b.appendChild(h('p', 'empty', 'Nothing has been asked of this project through Tuldok yet.')); return; } - const ul = h('ul', 'rows'); for (const it of a.items) { const li = h('li'); const r = h('div', 'row ov-act'); r.appendChild(h('span', 'sub num', time(it.at))); const t = h('span'); t.appendChild(h('span', 'title', it.operation + (it.target ? ' · ' + it.target : ''))); t.appendChild(h('span', 'sub', [(it.actor && (it.actor.label || it.actor.kind)) || '', it.detail].filter(Boolean).join(' · '))); r.appendChild(t); r.appendChild(stateEl(it.outcome === 'done' ? 'good' : 'serious', it.outcome)); li.appendChild(r); ul.appendChild(li); } - b.appendChild(ul); if (a.total > a.items.length) b.appendChild(h('p', 'note', (a.total - a.items.length) + ' earlier entries are not shown.')); + aside.textContent = ''; aside._for = null; + if (state.sel.overview === 'report') { main.textContent = ''; main._painted = null; return report(main, data); } + S.paint(main, () => Promise.all([P.read('definitions'), P.read('environments'), P.read('activity', { limit: 12 })].map(p => p.then(v => ({ v }), error => ({ error })))), (frag, [d, e, a]) => { + const standing = data.standing; + const top = h('section', 'ov-status'); + const line = h('div', 'ov-line'); line.appendChild(stateEl(standing.tone, standing.word)); line.appendChild(h('p', 'ov-text', standing.text)); top.appendChild(line); + top.appendChild(h('p', 'small faint', 'Read at ' + data.readAt)); + frag.appendChild(top); + const row = h('div', 'ov-row'); + const needs = h('section'); needs.appendChild(sect('Needs you', data.needs ? String(data.needs.length) : '…')); + if (data.needs) needs.appendChild(needsList(data.needs, n => window.LabActions.needControls(n, act.go))); else needs.appendChild(h('p', 'note', 'Reading…')); + row.appendChild(needs); + const facts = h('section'); facts.appendChild(sect('Project')); + const dl = h('dl', 'facts'), s = data.summary; + for (const [k, v, c] of [['Folder', s.folder, 'mono'], ['Code root', s.code_root, 'mono'], ['Project', s.project_id, 'mono'], ['Build worker', s.worker]]) { dl.appendChild(h('dt', null, k)); dl.appendChild(h('dd', c || '', v)); } + dl.appendChild(h('dt', null, 'Report')); const dd = h('dd'); const link = h('a', null, 'Open the report'); link.href = '#overview/report'; dd.appendChild(link); dl.appendChild(dd); + facts.appendChild(dl); row.appendChild(facts); frag.appendChild(row); + const cols = h('div', 'ov-cols'); + const defs = h('section'); defs.appendChild(sect('Definitions', String(Object.values(s.kinds).reduce((x, y) => x + y, 0)))); cols.appendChild(defs); + const envs = h('section'); envs.appendChild(sect('Environments', String(s.kinds.environment || 0))); cols.appendChild(envs); + frag.appendChild(cols); + const act2 = h('section', 'ov-history'); act2.appendChild(sect('Latest activity')); frag.appendChild(act2); + const fill = (b, got, build) => { if (got.error) failure(b, got.error); else build(b, got.v); }; + fill(defs, d, (b, d) => { + const states = [...new Set(d.definitions.map(x => x.state))].sort(); + const kinds = [...new Set(d.definitions.map(x => x.kind))].sort(); + if (!kinds.length) { b.appendChild(h('p', 'empty', 'The project has no definitions.')); return; } + const t = h('table', 'tv kinds'), th = h('thead'), hr = h('tr'); hr.appendChild(h('th', null, 'Kind')); for (const st of states) hr.appendChild(h('th', 'n', P.stateWord(st)[0])); hr.appendChild(h('th', 'n', 'All')); th.appendChild(hr); t.appendChild(th); + const tb = h('tbody'); for (const k of kinds) { const tr = h('tr'); tr.appendChild(h('td', null, k)); const mine = d.definitions.filter(x => x.kind === k); for (const st of states) { const n = mine.filter(x => x.state === st).length; tr.appendChild(h('td', 'n' + (n ? '' : ' faint'), n ? String(n) : '·')); } tr.appendChild(h('td', 'n', String(mine.length))); tb.appendChild(tr); } t.appendChild(tb); + const wrap = h('div'); wrap.style.overflowX = 'auto'; wrap.appendChild(t); b.appendChild(wrap); + }); + fill(envs, e, (b, e) => { + if (!e.environments.length) { b.appendChild(h('p', 'empty', 'The project defines no environment.')); return; } + const ul = h('ul', 'rows'); for (const env of e.environments) { const li = h('li'); const r = h('div', 'row ov-env'); const t = h('span'); t.appendChild(h('span', 'title', env.title)); t.appendChild(h('span', 'sub', ['Python ' + env.python, env.device, Object.keys(env.packages || {}).length + ' packages', env.checked_at ? 'checked ' + P.day(env.checked_at) : 'never checked'].filter(Boolean).join(' · '))); r.appendChild(t); r.appendChild(modelState(env.state)); li.appendChild(r); ul.appendChild(li); } b.appendChild(ul); + }); + fill(act2, a, (b, a) => { + if (!a.items.length) { b.appendChild(h('p', 'empty', 'Nothing has been asked of this project through Tuldok yet.')); return; } + const ul = h('ul', 'rows'); for (const it of a.items) { const li = h('li'); const r = h('div', 'row ov-act'); r.appendChild(h('span', 'sub num', time(it.at))); const t = h('span'); t.appendChild(h('span', 'title', it.operation + (it.target ? ' · ' + it.target : ''))); t.appendChild(h('span', 'sub', [(it.actor && (it.actor.label || it.actor.kind)) || '', it.detail].filter(Boolean).join(' · '))); r.appendChild(t); r.appendChild(stateEl(it.outcome === 'done' ? 'good' : 'serious', it.outcome)); li.appendChild(r); ul.appendChild(li); } + b.appendChild(ul); if (a.total > a.items.length) b.appendChild(h('p', 'note', (a.total - a.items.length) + ' earlier entries are not shown.')); + }); }); return false; } @@ -216,5 +231,6 @@ window.LabScreens = (() => { // The Data, Train, Benchmarks and Analysis screens are added by tabs.js, which builds with these parts. const parts = { sect, cell, block, time, bytes, failure, modelState, graphFor }; - return { map, overview, inspectorModel, needsList, icon, stateEl, theme, parts }; + const S = { map, overview, inspectorModel, needsList, icon, stateEl, theme, parts }; + return S; })(); diff --git a/static/project-workspace/tabs.js b/static/project-workspace/tabs.js index f3fe44e5..da3157b0 100644 --- a/static/project-workspace/tabs.js +++ b/static/project-workspace/tabs.js @@ -4,11 +4,14 @@ // (main, aside, state, act, data): it shows "Reading…" the first time, reads // what it needs through window.TuldokProject, then builds its content off the // page and swaps it in, so a re-render (a sort, a filter, the refresh while a -// build runs) keeps the scroll and the focus. Every one of them only reads; -// none draws a control that would change the project. Rule: the chrome holds -// no project words; titles, metrics and text come from the project. +// build runs) keeps the scroll and the focus. Data, Benchmarks and Analysis +// only read. Train draws the controls of spec-w3.md section 3.1 (actions.js): +// Plan build, a build request's Approve, Decline and Cancel, a run's Cancel +// run and Stop, an environment's Check again, Connect and Disconnect, and it +// shows a running run live. Rule: the chrome holds no project words; titles, +// metrics and text come from the project. (() => { - const S = window.LabScreens, P = window.TuldokProject, Tree = window.LabTree, C = window.LabCharts, h = C.h; + const S = window.LabScreens, P = window.TuldokProject, Tree = window.LabTree, C = window.LabCharts, h = C.h, A = window.LabActions; const { sect, cell, block, time, bytes, failure, modelState, graphFor } = S.parts; const fmt = C.fmtSci; const STATISTICS = ['median', 'mean', 'p10', 'p90', 'min', 'max']; @@ -343,7 +346,9 @@ const g = graphFor(data.map), deviceOf = new Map(envs.map(e => [e.reference, e.device])); // Models not built yet. const todo = recipes.filter(d => !d.removed && TO_BUILD.includes(d.state)); - frag.appendChild(sect('To build', todo.length + ' of ' + plural(recipes.length, 'model'))); + const th = sect('To build', todo.length + ' of ' + plural(recipes.length, 'model')); th.appendChild(h('span', 'spacer')); + th.appendChild(A.group('train:every', [{ id: 'plan', label: 'Plan everything buildable', cls: 'btn sm', who: 'request', onClick: () => act.select('plan:*') }], { inline: true })); + frag.appendChild(th); if (!todo.length) frag.appendChild(h('p', 'empty', 'Every model is built, or cannot be rebuilt from its definition.')); else { const ul = h('ul', 'rows'); @@ -351,7 +356,10 @@ const m = g.byId.get(d.reference), li = h('li'), b = button('row todo'); b.setAttribute('aria-pressed', String(d.reference === sel)); b.dataset.key = 'open-' + d.reference; b.appendChild(modelState(d.state)); const t = h('span'); t.appendChild(h('span', 'title', m ? Tree.nameOf(m) : d.title)); t.appendChild(h('span', 'sub', m ? m.groupTitle + (m.description ? ' · ' + m.description : '') : d.reference)); b.appendChild(t); b.appendChild(m ? h('span', 'chip ' + m.kind, P.kindLabel(m.kind)) : h('span')); - b.addEventListener('click', () => act.select(d.reference === sel ? null : d.reference)); li.appendChild(b); ul.appendChild(li); + b.addEventListener('click', () => act.select(d.reference === sel ? null : d.reference)); li.appendChild(b); + const plan = A.group('todo:' + d.reference, [{ id: 'plan', label: 'Plan build', cls: 'btn sm', who: 'request', onClick: () => act.select('plan:' + d.reference) }], { inline: true }); + if (!plan.hidden) { li.classList.add('with-act'); li.appendChild(plan); } + ul.appendChild(li); } frag.appendChild(ul); } @@ -402,7 +410,8 @@ else { const ul = h('ul', 'rows'); for (const e of envs) { - const li = h('li'), r = h('div', 'row env'); r.appendChild(modelState(e.state)); + const li = h('li'), key = 'env:' + e.reference, r = button('row env'); r.appendChild(modelState(e.state)); r.setAttribute('aria-pressed', String(key === sel)); r.dataset.key = 'open-' + key; r.dataset.env = e.reference; + r.addEventListener('click', () => act.select(key === sel ? null : key)); const t = h('span'); t.appendChild(h('span', 'title', e.title)); const asks = ['asks Python ' + (e.python || '—'), e.device, plural(Object.keys(e.packages || {}).length, 'package')].filter(Boolean).join(', '); const found = e.found ? 'found Python ' + (e.found.python || '?') + ', ' + plural(Object.keys(e.found.packages || {}).length, 'package') : e.interpreter ? 'not checked' : 'no interpreter recorded here'; @@ -416,6 +425,8 @@ if (!sel) return closeDrawer(aside); if (sel.startsWith('run:')) runDrawer(aside, sel, act, data); else if (sel.startsWith('request:')) requestDrawer(aside, sel, act, data); + else if (sel.startsWith('plan:')) A.planView(aside, sel, act.go, () => { const one = sel.slice(5); act.select(data.map.byId.has(one) ? one : null); }); + else if (sel.startsWith('env:')) envDrawer(aside, sel, act, data); else if (data.map.byId.has(sel)) S.inspectorModel(aside, sel, act, data); else { aside.textContent = ''; aside._for = sel; aside.appendChild(h('p', 'empty', 'There is no ' + sel + ' here.')); } return true; @@ -424,13 +435,38 @@ /** A definition's value in one line: a list of words as a command line, an object as key: value pairs. */ const brief = v => v == null ? '—' : typeof v !== 'object' ? String(v) : Array.isArray(v) ? (v.every(x => typeof x === 'string') ? v.join(' ') : v.map(brief).join(', ')) : Object.entries(v).map(([k, x]) => k + ': ' + (x && typeof x === 'object' && !Array.isArray(x) ? '{' + brief(x) + '}' : brief(x))).join(', '); const json = v => { if (typeof v === 'string') { try { v = JSON.parse(v); } catch (e) { return v; } } return brief(v); }; + const ACTIVE = ['queued', 'running']; + const LOG_LINES = 200; // lines of each log kept on the page while a run is read live + const hairOf = ev => { const hair = h('span', 'hair'); const i = h('i'); i.style.width = Math.round(100 * ev.completed / Math.max(1, ev.total)) + '%'; hair.appendChild(i); hair.setAttribute('role', 'progressbar'); hair.setAttribute('aria-valuemin', '0'); hair.setAttribute('aria-valuemax', String(ev.total)); hair.setAttribute('aria-valuenow', String(ev.completed)); return hair; }; + const eventText = ev => ev.stage + ': ' + ev.completed + ' of ' + ev.total + Object.entries(ev.metrics).map(([k, v]) => ' · ' + k + ' ' + fmt(v)).join(''); + let live = null; // the open run read live: {key, run, offsets, update(progress)} + /** One step of the live run (app.js calls it every two seconds while a build runs): its progress and its logs from the offsets. */ + S.tick = async () => { + const aside = document.getElementById('aside'); + if (!live || aside._for !== live.key) { live = null; return; } + const mine = live; + try { + const pr = await P.call('progress', { run: mine.run, stdout_offset: mine.offsets.stdout, stderr_offset: mine.offsets.stderr }); + if (live !== mine || aside._for !== mine.key) return; + mine.update(pr); + if (pr.ended) { live = null; aside._for = null; mine.ended(); } + } catch (error) { /* the next tick asks again; the strip says what fails */ } + }; function runDrawer(aside, key, act, data) { const id = key.slice(4); drawer(aside, key, () => Promise.all([P.read('run', { run: id }), P.call('progress', { run: id })]), (ins, [r, pr]) => { const m = graphFor(data.map).byId.get(r.reference); - const hd = h('header'); hd.appendChild(h('span', 'kicker', 'run ' + r.id)); hd.appendChild(h('h2', null, (m ? Tree.nameOf(m) : r.reference) + (r.subject ? ' · ' + r.subject : ''))); + const hd = h('header'); hd.appendChild(h('span', 'kicker', 'run ' + r.id)); const t2 = h('h2', null, (m ? Tree.nameOf(m) : r.reference) + (r.subject ? ' · ' + r.subject : '')); t2.tabIndex = -1; hd.appendChild(t2); const meta = h('div', 'ins-meta'); if (m) meta.appendChild(h('span', 'chip ' + m.kind, P.kindLabel(m.kind))); meta.appendChild(runState(r.state)); if (r.scratch) meta.appendChild(h('span', 'small faint', 'from the code as it is')); hd.appendChild(meta); ins.appendChild(hd); if (m) { const acts = h('div', 'actions'); acts.appendChild(button('btn sm ghost', 'On the map', () => act.go('map', m.id))); acts.appendChild(button('btn sm ghost', 'Its model', () => act.select(m.id))); ins.appendChild(acts); } + // Cancel run while it is queued or running; Stop what it left running when its build is gone. + const active = ACTIVE.includes(r.state), orphan = active && r.builder_alive === false; + ins.appendChild(A.group('run:' + r.id, [ + { id: 'cancel', label: 'Cancel run', cls: 'btn', who: 'cancel', op: 'cancel_run', args: () => ({ run: r.id }), busy: 'Cancelling…', hidden: !active || orphan, + confirm: 'Ask this run to stop. It ends cancelled and leaves no product.' }, + { id: 'stop', label: 'Stop what it left running', cls: 'btn', who: 'cancel', op: 'stop_run', args: () => ({ run: r.id }), busy: 'Stopping…', hidden: !orphan, + confirm: 'Kill every process this run left behind and mark it unknown; its build is gone.' } + ])); const su = setup(); su.put('Definition', r.reference, 'mono'); if (r.subject) su.put('Subject', r.subject); @@ -447,11 +483,33 @@ else su.put('Product', 'none'); if (r.bytes != null) su.put('Size', bytes(r.bytes)); if (r.problem) su.put('Problem', r.problem); - ins.appendChild(su.dl); - if (pr.event) { const ev = pr.event; const p = h('p', 'small'); p.textContent = ev.stage + ': ' + ev.completed + ' of ' + ev.total + Object.entries(ev.metrics).map(([k, v]) => ' · ' + k + ' ' + fmt(v)).join(''); ins.appendChild(block('Latest progress', p)); } + // The latest progress: a hairline and its line, kept current while the run is read live. + const prog = h('div', 'progress-line'); + const showEvent = ev => { prog.textContent = ''; if (ev) { prog.appendChild(hairOf(ev)); prog.appendChild(h('span', 'small', eventText(ev))); } else prog.appendChild(h('p', 'note', active ? 'No progress reported yet.' : 'No progress was reported.')); }; + showEvent(pr.event); + const progBlock = block('Latest progress', prog); if (!pr.event && !active) progBlock.hidden = true; + // A run read live shows its progress and logs first; an ended one its record first. + ins.appendChild(progBlock); + if (!active) ins.appendChild(su.dl); + const logs = {}; for (const [name, title] of [['stdout', 'Standard output'], ['stderr', 'Standard error']]) { - const log = pr[name] || { text: '' }; - ins.appendChild(block(title + (log.size != null ? ' · ' + bytes(log.size) : ''), log.text ? h('pre', 'evtext', tail(log.text, 40)) : h('p', 'note', log.size == null ? 'No log on this machine.' : 'Empty.'))); + const log = pr[name] || { text: '' }, b = h('div'), head = h('h3', null, title + (log.size != null ? ' · ' + bytes(log.size) : '')); + b.appendChild(head); + const pre = h('pre', 'evtext'); pre.dataset.log = name; let lines = log.text ? log.text.replace(/\n$/, '').split('\n').slice(-LOG_LINES) : []; + const note = h('p', 'note', log.size == null ? 'No log on this machine.' : 'Empty.'); + const paintLog = () => { pre.textContent = (lines.length >= LOG_LINES ? '…\n' : '') + lines.join('\n'); pre.hidden = !lines.length; note.hidden = !!lines.length; pre.scrollTop = pre.scrollHeight; }; + b.appendChild(pre); b.appendChild(note); paintLog(); ins.appendChild(b); + logs[name] = { head, title, add: text => { if (!text) return; lines = lines.concat(text.replace(/\n$/, '').split('\n')).slice(-LOG_LINES); paintLog(); } }; + } + if (active) ins.appendChild(su.dl); + if (active) { + live = { key, run: r.id, offsets: { stdout: (pr.stdout || {}).offset || 0, stderr: (pr.stderr || {}).offset || 0 }, + update: p => { + showEvent(p.event); progBlock.hidden = false; + for (const name of ['stdout', 'stderr']) { const log = p[name]; if (!log) continue; logs[name].add(log.text); live.offsets[name] = log.offset; if (log.size != null) logs[name].head.textContent = logs[name].title + ' · ' + bytes(log.size); } + }, + ended: () => act.refresh() }; + ins.appendChild(h('p', 'note live-note', 'Read live every two seconds while it runs.')); } }); } @@ -460,13 +518,24 @@ drawer(aside, key, () => P.read('build_request', { request: id }), (ins, r) => { const hd = h('header'); hd.appendChild(h('span', 'kicker', 'build request ' + r.id)); hd.appendChild(h('h2', null, 'A build of ' + covering(r))); const meta = h('div', 'ins-meta'); meta.appendChild(requestState(r.state)); hd.appendChild(meta); ins.appendChild(hd); + if (r.state === 'declined' && r.problem) ins.appendChild(h('p', 'reason', 'Declined: ' + r.problem)); + // Approve and Decline while it awaits approval; Cancel while it awaits approval, is queued or runs. + const waiting = r.state === 'awaiting-approval', cancellable = ['awaiting-approval', 'queued', 'running'].includes(r.state); + ins.appendChild(A.group('request:' + r.id, [ + { id: 'approve', label: 'Approve', cls: 'btn primary', who: 'owner', op: 'approve_build', args: () => ({ request: r.id }), busy: 'Approving…', hidden: !waiting }, + Object.assign(A.declineItem(r.id), { cls: 'btn', hidden: !waiting }), + { id: 'cancel', label: 'Cancel', cls: 'btn ghost', who: 'cancel', op: 'cancel_build', args: () => ({ request: r.id }), busy: 'Cancelling…', hidden: !cancellable, + confirm: r.state === 'running' ? 'Cancel this build: its running step is asked to stop and nothing after it runs.' : 'Cancel this build request; nothing of it runs.' } + ])); const su = setup(); su.put('Asked by', who(r.requested_by) + ' · ' + time(r.requested_at)); + su.put('Targets', r.every ? 'everything buildable' + ((r.targets || []).length ? ', and ' + r.targets.join(', ') : '') : (r.targets || []).join(', ') || '—', 'mono'); if (r.decided_at) su.put('Decided by', who(r.decided_by) + ' · ' + time(r.decided_at)); if (r.started_at) su.put('Started', time(r.started_at)); if (r.finished_at) su.put('Finished', time(r.finished_at)); if (r.expires_at) su.put('Expires', time(r.expires_at)); - su.put('Code', r.scratch ? 'as it is, uncommitted changes included' : (r.covers && r.covers.commit ? 'commit ' + r.covers.commit : 'committed'), 'mono'); - if (r.problem) su.put('Problem', r.problem); + su.put('Code', r.scratch ? 'as it is on disk, uncommitted changes included; the product is marked scratch' : (r.covers && r.covers.commit ? 'commit ' + r.covers.commit : 'committed'), 'mono'); + if (r.covers && r.covers.definitions) su.put('Definitions', plural(Object.keys(r.covers.definitions).length, 'definition') + ', as they stand when it is asked'); + if (r.problem) su.put(r.state === 'declined' ? 'Reason' : 'Problem', r.problem); if (r.result) su.put('Result', json(r.result), 'mono'); ins.appendChild(su.dl); const steps = (r.covers && r.covers.steps) || []; @@ -595,5 +664,37 @@ return closeDrawer(aside); } + /** An environment: what it asks, what was found on this machine, and Check again, Connect and Disconnect. */ + function envDrawer(aside, key, act, data) { + const ref = key.slice(4); + drawer(aside, key, () => P.read('environment', { reference: ref }), (ins, e) => { + const hd = h('header'); hd.appendChild(h('span', 'kicker', 'environment · ' + e.reference)); const t = h('h2', null, e.title); t.tabIndex = -1; hd.appendChild(t); + const meta = h('div', 'ins-meta'); meta.appendChild(modelState(e.state)); if (e.origin) meta.appendChild(h('span', 'small faint', e.origin)); hd.appendChild(meta); ins.appendChild(hd); + const su = setup(); + su.put('Asks', ['Python ' + (e.python || '—'), e.device, plural(Object.keys(e.packages || {}).length, 'package')].filter(Boolean).join(', ')); + if (Object.keys(e.packages || {}).length) su.put('Packages', Object.entries(e.packages).map(([k, v]) => k + ' ' + v).join(', '), 'mono'); + su.put('Interpreter', e.interpreter || 'none recorded on this machine', e.interpreter ? 'mono' : null); + if (e.found) su.put('Found', 'Python ' + (e.found.python || '?') + ', ' + plural(Object.keys(e.found.packages || {}).length, 'package')); + su.put('Checked', e.checked_at ? time(e.checked_at) + (e.ok === false ? ', failed' : e.ok ? ', passed' : '') : 'never'); + if (e.recorded_at) su.put('Recorded', time(e.recorded_at)); + ins.appendChild(su.dl); + if (e.problems && e.problems.length) { const ul = h('ul', 'plain'); for (const p of e.problems) ul.appendChild(h('li', 'small warnline', typeof p === 'string' ? p : p.message || JSON.stringify(p))); ins.appendChild(block('What the check found', ul)); } + const connected = !!e.interpreter; + ins.appendChild(A.group('envcheck:' + ref, [Object.assign(A.checkItem(ref), { cls: 'btn', hidden: !connected })])); + if (A.may('owner')) { + const d = h('div'); d.appendChild(h('h3', null, connected ? 'Connect another interpreter' : 'Connect an interpreter')); + d.appendChild(h('p', 'note', 'An existing Python on this machine, by its absolute path; Tuldok records it for this project and checks it. Nothing is installed.')); + const f = h('div', 'form'); + f.appendChild(A.group('envconnect:' + ref, [{ id: 'connect', label: 'Connect', cls: 'btn', who: 'owner', op: 'connect_environment', busy: 'Connecting…', + input: { name: 'interpreter', label: 'Interpreter (absolute path)', placeholder: '/path/to/python', max: 4096, always: true }, + args: s => ({ reference: ref, interpreter: (s.text.interpreter || '').trim() }) }])); + d.appendChild(f); ins.appendChild(d); + if (connected) ins.appendChild(A.group('envdisconnect:' + ref, [{ id: 'disconnect', label: 'Disconnect', cls: 'btn ghost', who: 'owner', op: 'disconnect_environment', args: () => ({ reference: ref }), busy: 'Disconnecting…', + confirm: 'Forget the interpreter recorded for ' + e.title + ' on this machine; nothing is deleted.' }])); + } + }); + } + + S.paint = paint; Object.assign(S, { benchmarks, train, data: data_, analysis }); })(); diff --git a/tests/browser_project_workspace.cjs b/tests/browser_project_workspace.cjs index cd1abafa..53c24d53 100644 --- a/tests/browser_project_workspace.cjs +++ b/tests/browser_project_workspace.cjs @@ -10,8 +10,10 @@ // the kind and text filters, the track, the status strip and Needs you; on Benchmarks picks a benchmark, hovers // and focuses a point, sorts the table and makes a compare set of two that the address keeps; opens a run and a // build request on Train, a dataset on Data, picks a metric on Analysis; and fails on any script error, failed -// request, sideways overflow or empty main area. Nothing may be asked of the project that changes it: its -// activity log gains nothing while the page is open and the fixture copy is unchanged byte for byte. +// request, sideways overflow or empty main area. The page is signed in with a credential that may only inspect, so +// it draws no control (spec-w3.md section 1); browser_project_workspace_actions.cjs checks the controls. Nothing may +// be asked of the project that changes it: its activity log gains nothing while the page is open and the fixture +// copy is unchanged byte for byte. // node tests/browser_project_workspace.cjs [--lab-root ] const assert = require('node:assert/strict'), fs = require('node:fs'), os = require('node:os'), path = require('node:path'), crypto = require('node:crypto'); const { spawn, execFileSync } = require('node:child_process'), { once } = require('node:events'); @@ -290,7 +292,11 @@ assert service.Service(sys.argv[1]).call('request_build', {'targets': ['recipes/ evaluate = async expression => { const result = await send('Runtime.evaluate', { expression, awaitPromise: true, returnByValue: true }); if (result.exceptionDetails) throw Error(JSON.stringify(result.exceptionDetails)); return result.result.value; }; await send('Page.enable'); await send('Runtime.enable'); await send('Network.enable'); await send('Log.enable'); await send('Emulation.setDeviceMetricsOverride', { width: WIDTH, height: HEIGHT, deviceScaleFactor: 1, mobile: false }); - await auth.browser(send, origin); + // The page is signed in with a credential that may only inspect: it draws no control that changes the project + // (spec-w3.md section 1), so this check sees the page of phase 2. The check's own calls stay the owner's. + const issued = await auth.fetch(origin + '/api/access/credentials', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ label: 'A read-only browser check', scopes: ['inspect'], ttl_seconds: 3600 }) }); + const inspector = await issued.json(); assert.equal(issued.status, 201, JSON.stringify(inspector)); + assert.notEqual((await send('Network.setCookie', { name: 'tuldok_session', value: inspector.token, url: origin + '/', httpOnly: true, sameSite: 'Strict', path: '/' })).success, false); for (const theme of ['light', 'dark']) { await open(theme, 'map'); diff --git a/tests/browser_project_workspace_actions.cjs b/tests/browser_project_workspace_actions.cjs new file mode 100644 index 00000000..72d31a36 --- /dev/null +++ b/tests/browser_project_workspace_actions.cjs @@ -0,0 +1,467 @@ +'use strict'; +// The controls of the project workspace (docs/plans/definition-first-projects/spec-w3.md section 3.1, slice T21) in a +// headless browser. Tuldok runs with --project-folder on a copy of the minimal fixture with the buildable fixture's +// definitions beside it, committed to a Git repository of its own so builds run from a commit. Two more recipes have +// stand-in commands that train nothing: recipes/slow prints a progress line every half second for about four +// seconds; recipes/hold prints one every half second until it is cancelled. An agent credential asks for two builds. +// Signed in as the owner the check: approves one from Needs you and, with the model's drawer open on the Map, sees +// the strip's hairline partly filled while it runs and then the model built, without a reload; declines the other +// with a reason and sees the reason; plans the hold recipe from Train and requests it, and reads its run live (the +// hairline, the progress line, the log growing); while that runs, plans a model from its drawer and one from Train, +// requests each and cancels each with two presses (Escape leaves the two-press state, and the state outlives the +// two-second refresh); provokes a refusal (a plan with a blocked target, an interpreter path that is not absolute) +// and sees it inline; cancels the running run; connects an environment and checks one again; saves an unsaved edit +// from the strip; makes a conflict twice and resolves it both ways. Signed in with a credential that may only +// inspect, no control is drawn. Each new surface is captured in light and dark. It fails on any script error, any +// failed request other than the refusals it provokes, sideways overflow, or a control left disabled. +// node tests/browser_project_workspace_actions.cjs +const assert = require('node:assert/strict'), fs = require('node:fs'), os = require('node:os'), path = require('node:path'); +const { spawn, execFileSync } = require('node:child_process'), { once } = require('node:events'); +const { authenticatedFixture } = require('./auth_helpers.cjs'), { waitForDebugger } = require('./browser_startup.cjs'), { cdpSession } = require('./browser_cdp_session.cjs'), { qaDirectory, screenshotOptions } = require('./qa_artifacts.cjs'); + +const root = path.resolve(__dirname, '..'); +assert.ok(process.env.TULDOK_DATABASE_URL, 'TULDOK_DATABASE_URL must name a disposable PostgreSQL cluster'); +const venv = path.join(root, '.venv', 'bin'); +if (fs.existsSync(path.join(venv, 'python'))) process.env.PATH = venv + path.delimiter + process.env.PATH; // auth_helpers runs python3 +const python = fs.existsSync(path.join(venv, 'python')) ? path.join(venv, 'python') : 'python3'; +const WIDTH = 1440, HEIGHT = 900; + +const temporary = fs.mkdtempSync(path.join(os.tmpdir(), 'tuldok-actions-browser-')); +const report = qaDirectory(root, 'project-workspace-actions'); +const children = [], checks = [], errors = [], failures = [], allowed = [], bounds = []; +let server, serverErrors = '', origin, auth, socket, session, send, evaluate, folder, owned = null; +const pause = ms => new Promise(resolve => setTimeout(resolve, ms)); +async function until(fn, label, tries = 300) { for (let i = 0; i < tries; i++) { const value = await fn(); if (value) return value; await pause(100); } throw Error('Timed out: ' + label); } +function check(text) { checks.push(text); console.log('PASS ' + text); } +function launch(command, args, options) { const child = spawn(command, args, options); children.push(child); return child; } +async function stop(child) { if (!child || child.exitCode !== null || child.signalCode !== null) return; const exited = once(child, 'exit'); child.kill('SIGTERM'); await Promise.race([exited, pause(10000)]); if (child.exitCode === null && child.signalCode === null) { child.kill('SIGKILL'); await exited; } } +function findBrowser() { + const candidates = [process.env.BROWSER, '/usr/bin/chromium', '/usr/bin/chromium-browser', '/usr/bin/google-chrome']; + const cache = path.join(os.homedir(), '.cache', 'ms-playwright'); + if (fs.existsSync(cache)) for (const name of fs.readdirSync(cache).filter(n => n.startsWith('chromium_headless_shell-')).sort().reverse()) candidates.push(path.join(cache, name, 'chrome-headless-shell-linux64', 'chrome-headless-shell')); + const found = candidates.find(candidate => candidate && fs.existsSync(candidate)); + assert.ok(found, 'No headless browser: set BROWSER'); + return found; +} +/** Drops the project's schema and the catalog's from the disposable database, so each run imports afresh. */ +function dropOwned(folder, catalog) { + const id = JSON.parse(fs.readFileSync(path.join(folder, 'tuldok.json'), 'utf8')).id; + execFileSync(python, ['-c', `import json, os, pathlib, sys, psycopg +from psycopg import sql +from tuldok_project import store +store.drop_project(sys.argv[1], os.environ['TULDOK_DATABASE_URL']) +root = pathlib.Path(sys.argv[2]) +if root.exists(): + with psycopg.connect(os.environ['TULDOK_DATABASE_URL'], autocommit=True) as c: + for p in root.rglob('.tuldok.json'): + v = json.loads(p.read_text()) + name = 'projection_' + v['projection_id'] if v.get('version') == 2 else 'catalog_' + v['dataset_id'] + c.execute(sql.SQL('DROP SCHEMA IF EXISTS {} CASCADE').format(sql.Identifier(name))) +`, id, catalog], { cwd: root, stdio: ['ignore', 'pipe', 'pipe'] }); +} +async function contract(name) { + const capabilities = await (await auth.fetch(origin + '/api/agent/capabilities')).json(); + const operation = capabilities.operations.find(item => item.id === 'project.' + name), c = operation.contracts[operation.contracts.length - 1]; + return 'project.' + name + '/' + c.version + '/' + c.sha256; +} +/** An operation as the owner (the fixture's session); bearer: as that agent credential instead. */ +async function api(name, body = {}, bearer = null) { + const headers = { 'Content-Type': 'application/json', 'Tuldok-Operation-Contract': await contract(name) }; + const response = bearer ? await globalThis.fetch(origin + '/api/project/' + name, { method: 'POST', headers: { ...headers, Authorization: 'Bearer ' + bearer }, body: JSON.stringify(body) }) + : await auth.fetch(origin + '/api/project/' + name, { method: 'POST', headers, body: JSON.stringify(body) }); + const value = await response.json(); assert.equal(response.status, 200, name + ': ' + JSON.stringify(value)); return value; +} +async function credential(label, scopes) { + const response = await auth.fetch(origin + '/api/access/credentials', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ label, scopes, ttl_seconds: 3600 }) }); + const value = await response.json(); assert.equal(response.status, 201, JSON.stringify(value)); return value.token; +} + +// ---- The page ------------------------------------------------------------------ +/** Refusals provoked on purpose: a failed request is allowed while its window is open and it matches. */ +function allow(re, status) { const entry = { re, status, from: Date.now(), to: Infinity, seen: 0 }; allowed.push(entry); return entry; } +function close(entry) { entry.to = Date.now() + 500; } +function failure(url, status, text) { + const at = Date.now(), entry = allowed.slice().reverse().find(a => a.re.test(url || '') && (a.status === null || a.status === status) && a.from <= at && at <= a.to); + if (entry) entry.seen++; else failures.push({ url, status, text }); +} +async function shot(name) { + await evaluate('new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve)))'); + fs.writeFileSync(path.join(report, name + '.jpg'), Buffer.from((await send('Page.captureScreenshot', screenshotOptions)).data, 'base64')); +} +/** The same view in light and dark, switched in place (a reload would lose a two-press state). */ +async function shots(name) { + for (const theme of ['light', 'dark']) { + await evaluate(`(() => { document.documentElement.setAttribute('data-theme', '${theme}'); const b = document.getElementById('theme'); b.lastChild.textContent = ' ${theme === 'dark' ? 'Dark' : 'Light'}'; })()`); + await inspect(theme + ' ' + name); await shot(theme + '-' + name); + } + await evaluate(`(() => { document.documentElement.setAttribute('data-theme', 'light'); document.getElementById('theme').lastChild.textContent = ' Light'; })()`); +} +/** No sideways overflow (page, main, top bar, strip, drawer), no control left disabled or waiting, nothing outside the drawer. */ +async function inspect(label) { + const value = await evaluate(`(() => { + const main = document.getElementById('main'), top = document.querySelector('.top'), strip = document.getElementById('strip'), drawer = document.getElementById('drawer'); + const open = drawer.classList.contains('open'), dr = drawer.getBoundingClientRect(); + const outside = open ? [...drawer.querySelectorAll('button, input, textarea, select, p, li, h2, h3')].filter(e => e.offsetParent !== null).map(e => [e, e.getBoundingClientRect()]).filter(([e, r]) => r.width && (r.right > dr.right + 1 || r.left < dr.left - 1)).map(([e]) => e.textContent.slice(0, 40)) : []; + return { label: ${JSON.stringify(label)}, viewport: innerWidth, page: document.documentElement.scrollWidth, body: document.body.scrollWidth, + main: main.classList.contains('map') ? null : [main.scrollWidth, main.clientWidth], top: [top.scrollWidth, top.clientWidth], strip: [strip.scrollWidth, strip.clientWidth], + drawer: open ? [drawer.scrollWidth, drawer.clientWidth] : null, outside, + stuck: [...document.querySelectorAll('.act-group button')].filter(b => b.disabled || b.getAttribute('aria-busy')).map(b => b.textContent) }; + })()`); + bounds.push(value); + assert.ok(value.page <= value.viewport && value.body <= value.viewport, 'Sideways overflow of the page: ' + JSON.stringify(value)); + assert.ok(!value.main || value.main[0] <= value.main[1] + 1, 'Sideways overflow of the main area: ' + JSON.stringify(value)); + assert.ok(value.top[0] <= value.top[1] + 1 && value.strip[0] <= value.strip[1] + 1, 'Sideways overflow of the top bar or strip: ' + JSON.stringify(value)); + assert.ok(!value.drawer || value.drawer[0] <= value.drawer[1] + 1, 'Sideways overflow of the drawer: ' + JSON.stringify(value)); + assert.deepEqual(value.outside, [], 'Controls outside the drawer: ' + label); + assert.deepEqual(value.stuck, [], 'A control left disabled: ' + label); +} +async function open(hash) { + await send('Page.navigate', { url: origin + '/?theme=light#' + hash }); + await until(() => evaluate(`document.readyState === 'complete' && !!document.getElementById('needs-btn') && !document.getElementById('needs-btn').disabled`), 'the project read (' + hash + ')'); + await settled('opened ' + hash); +} +async function hash(value) { await evaluate(`location.hash = ${JSON.stringify('#' + value)}`); await settled('#' + value); } +async function mouse(x, y, click = false) { + await send('Input.dispatchMouseEvent', { type: 'mouseMoved', x, y }); + if (click) { await send('Input.dispatchMouseEvent', { type: 'mousePressed', x, y, button: 'left', clickCount: 1 }); await send('Input.dispatchMouseEvent', { type: 'mouseReleased', x, y, button: 'left', clickCount: 1 }); } +} +const byKey = key => `[data-key=${JSON.stringify(key)}]`; +async function centre(selector) { + const box = await until(() => evaluate(`(() => { const e = [...document.querySelectorAll(${JSON.stringify(selector)})].find(e => e.offsetParent !== null); if (!e) return null; e.scrollIntoView({ block: 'nearest', inline: 'nearest' }); const r = e.getBoundingClientRect(); return { x: r.left + r.width / 2, y: r.top + r.height / 2 }; })()`), 'shown: ' + selector, 100); + return box; +} +async function press(selector) { const { x, y } = await centre(selector); await mouse(x, y, true); } +async function key(name, code = name, keyCode = 0) { await send('Input.dispatchKeyEvent', { type: 'keyDown', key: name, code, windowsVirtualKeyCode: keyCode }); await send('Input.dispatchKeyEvent', { type: 'keyUp', key: name, code, windowsVirtualKeyCode: keyCode }); } +async function type(selector, text) { + await press(selector); + await evaluate(`(() => { const e = document.activeElement; e.select && e.select(); })()`); + await key('Delete', 'Delete', 46); + await send('Input.insertText', { text }); +} +/** Waits until nothing reads and no control waits for its answer. */ +async function settled(label) { + await until(() => evaluate(`(() => { const reading = e => [...e.querySelectorAll('.note')].some(n => n.textContent === 'Reading…'); return !reading(document.getElementById('main')) && !reading(document.getElementById('aside')) && !document.getElementById('main').hasAttribute('aria-busy') && !document.querySelector('.act-group [aria-busy]'); })()`), label); + await pause(150); +} +async function drawerText() { return evaluate(`document.getElementById('aside').innerText`); } +const drawerState = () => evaluate(`[...document.querySelectorAll('#aside header .state')].map(e => e.textContent.trim()).join(' ')`); + +(async () => { + // ---- The fixture: minimal + buildable + two stand-in recipes, in Git ---------------- + fs.cpSync(path.join(root, 'tests', 'fixtures', 'tuldok_project', 'minimal'), path.join(temporary, 'fixture'), { recursive: true }); + folder = path.join(temporary, 'fixture', 'project'); + const code = path.join(temporary, 'fixture', 'code'); + const buildable = path.join(root, 'tests', 'fixtures', 'tuldok_project', 'buildable'); + for (const kind of ['environments', 'datasets', 'recipes', 'benchmarks', 'charts']) for (const name of fs.readdirSync(path.join(buildable, 'project', kind))) fs.copyFileSync(path.join(buildable, 'project', kind, name), path.join(folder, kind, name)); + for (const name of fs.readdirSync(path.join(buildable, 'code'))) fs.cpSync(path.join(buildable, 'code', name), path.join(code, name), { recursive: true }); + const progress = `import json, os, sys, time +def line(completed, total, value): + print(json.dumps({'format': 'tuldok_progress_v1', 'stage': 'fit', 'completed': completed, 'total': total, 'metrics': {'loss': value}}), flush=True) +`; + // About four seconds: eight progress lines, half a second apart. + fs.writeFileSync(path.join(code, 'slow.py'), progress + `out = sys.argv[sys.argv.index('--out') + 1] +for step in range(1, 9): + line(step, 8, 1.0 / step) + print('step', step, 'of 8', file=sys.stderr, flush=True) + time.sleep(0.5) +with open(os.path.join(out, 'weights.json'), 'w') as handle: + json.dump({'constant': 1.0}, handle) +`); + // Until it is cancelled (at most two minutes): a progress line every half second. + fs.writeFileSync(path.join(code, 'hold_run.py'), progress + `out = sys.argv[sys.argv.index('--out') + 1] +for step in range(1, 241): + line(step, 240, 1.0 / step) + time.sleep(0.5) +with open(os.path.join(out, 'weights.json'), 'w') as handle: + json.dump({'constant': 2.0}, handle) +`); + const recipe = (title, script, extra) => JSON.stringify({ format: 'tuldok_definition_v1', kind: 'recipe', title, ...extra, + run: { command: ['python', script, '--out', '{output}'], environment: 'environments/test-python', outputs: { weights: { path: 'weights.json', role: 'weights' } }, sources: [script] } }, null, 2) + '\n'; + fs.writeFileSync(path.join(folder, 'recipes', 'slow.json'), recipe('Slow fit, four seconds', 'slow.py', { labels: { short: 'SLOW' }, change: 'refinement', derived_from: 'recipes/fit-a' })); + fs.writeFileSync(path.join(folder, 'recipes', 'hold.json'), recipe('Held fit, runs until cancelled', 'hold_run.py', { labels: { short: 'HOLD' }, change: 'training-policy' })); + const git = ['-c', 'user.name=Tuldok Test', '-c', 'user.email=test@example.invalid', '-c', 'commit.gpgsign=false', '-c', 'init.defaultBranch=main', '-C', path.join(temporary, 'fixture')]; + execFileSync('git', [...git, 'init', '-q']); execFileSync('git', [...git, 'add', '-A']); execFileSync('git', [...git, 'commit', '-q', '-m', 'The fixture.']); + + const home = path.join(temporary, 'home'), catalog = path.join(temporary, 'catalog'); fs.mkdirSync(home); + const env = { ...process.env, TULDOK_PROJECT_HOME: home, TULDOK_SETTINGS: path.join(temporary, 'settings.json') }; + owned = [folder, catalog]; dropOwned(folder, catalog); + const cli = (...args) => execFileSync(python, ['-m', 'tuldok_project', ...args], { cwd: root, env, stdio: ['ignore', 'pipe', 'pipe'] }).toString(); + cli('connect', folder, 'test-python', python); + cli('build', folder, 'datasets/numbers', '--yes'); + + let output = ''; + server = launch(python, ['-u', 'app.py', '--port', '0', '--data', catalog, '--project-folder', folder], { cwd: root, env, stdio: ['ignore', 'pipe', 'pipe'] }); + server.stdout.on('data', chunk => { output += chunk; }); server.stderr.on('data', chunk => { serverErrors += chunk; }); + const port = await until(() => { if (server.exitCode !== null) throw Error('Tuldok exited: ' + serverErrors); return output.match(/127\.0\.0\.1:(\d+)/)?.[1]; }, 'Tuldok start-up', 1800); + origin = 'http://127.0.0.1:' + port; + auth = authenticatedFixture(); await auth.register(origin, catalog, root); + // An agent that may ask for builds asks for two; an inspector that may only read. + const agent = await credential('A browser check agent', ['inspect', 'execute']); + const inspector = await credential('A browser check inspector', ['inspect']); + const slowAsk = await api('request_build', { targets: ['recipes/slow'] }, agent); + const fitAsk = await api('request_build', { targets: ['recipes/fit-b'] }, agent); + assert.equal(slowAsk.state, 'awaiting-approval'); assert.equal(fitAsk.state, 'awaiting-approval'); + check('Tuldok serves the fixture copy in Git; an agent asked for builds of recipes/slow (' + slowAsk.id.slice(0, 8) + ') and recipes/fit-b (' + fitAsk.id.slice(0, 8) + '), both awaiting approval'); + + const browser = launch(findBrowser(), ['--headless', '--no-sandbox', '--disable-gpu', '--no-first-run', '--hide-scrollbars', '--remote-debugging-port=0', `--window-size=${WIDTH},${HEIGHT}`, '--user-data-dir=' + path.join(temporary, 'browser'), 'about:blank'], { stdio: 'ignore', env: { ...process.env, XDG_CONFIG_HOME: temporary, XDG_CACHE_HOME: temporary } }); + const debugPort = await waitForDebugger(browser, path.join(temporary, 'browser', 'DevToolsActivePort')); + const target = (await (await fetch('http://127.0.0.1:' + debugPort + '/json')).json()).find(item => item.type === 'page'); + socket = new WebSocket(target.webSocketDebuggerUrl); await once(socket, 'open'); + session = cdpSession(socket, { timeoutMs: 60000, onEvent: event => { + if (event.method === 'Runtime.exceptionThrown') errors.push(event.params.exceptionDetails.exception?.description || event.params.exceptionDetails.text); + if (event.method === 'Runtime.consoleAPICalled' && event.params.type === 'error') errors.push(event.params.args.map(a => a.value ?? a.description).join(' ')); + if (event.method === 'Log.entryAdded' && event.params.entry.level === 'error') { + const status = Number((event.params.entry.text.match(/status of (\d{3})/) || [])[1]); + if (status) failure(event.params.entry.url, status, event.params.entry.text); else errors.push(event.params.entry.text + ' ' + (event.params.entry.url || '')); + } + if (event.method === 'Network.loadingFailed' && !event.params.canceled) failures.push({ id: event.params.requestId, error: event.params.errorText }); + if (event.method === 'Network.responseReceived' && event.params.response.status >= 400) failure(event.params.response.url, event.params.response.status, 'response'); + } }); + send = session.send; + evaluate = async expression => { const result = await send('Runtime.evaluate', { expression, awaitPromise: true, returnByValue: true }); if (result.exceptionDetails) throw Error(JSON.stringify(result.exceptionDetails)); return result.result.value; }; + await send('Page.enable'); await send('Runtime.enable'); await send('Network.enable'); await send('Log.enable'); + await send('Emulation.setDeviceMetricsOverride', { width: WIDTH, height: HEIGHT, deviceScaleFactor: 1, mobile: false }); + await send('Emulation.setEmulatedMedia', { features: [{ name: 'prefers-color-scheme', value: 'light' }, { name: 'prefers-reduced-motion', value: 'reduce' }] }); + await auth.browser(send, origin); + + // ---- Needs you, with its controls ------------------------------------------------ + await open('map/recipes%2Fslow'); + assert.equal(await drawerState(), 'not built'); + await press('#needs-btn'); + await until(() => evaluate(`!!document.querySelector('#needs-panel ${byKey('need:request:' + slowAsk.id + ':approve')}')`), 'Needs you with Approve'); + const needs = await evaluate(`[...document.querySelectorAll('#needs-panel .needs > li')].map(li => [li.querySelector('.need > span').textContent, [...li.querySelectorAll('button')].map(b => b.textContent)])`); + assert.ok(needs.filter(([, b]) => b.includes('Approve') && b.includes('Decline') && b.includes('Open on Train')).length === 2, 'Each request awaiting approval has Approve, Decline and a link: ' + JSON.stringify(needs)); + await shots('needs-you'); + check('Needs you lists ' + needs.length + ' items with their controls: ' + needs.map(([t, b]) => t.slice(0, 50) + '… [' + b.join(', ') + ']').join(' | ')); + + // ---- Approve from Needs you; the hairline partly filled; the model built on the Map, no reload ---- + await evaluate(`window.__noReload = 1`); + await press(byKey('need:request:' + slowAsk.id + ':approve')); + const widths = []; + const partly = await until(async () => { const w = await evaluate(`(() => { const i = document.querySelector('#strip .hair i'); return i ? parseFloat(i.style.width) : null; })()`); if (w !== null && !widths.includes(w)) widths.push(w); return w > 0 && w < 100 ? w : null; }, 'the strip hairline partly filled', 300); + const stripText = await evaluate(`document.getElementById('strip').innerText.replace(/\\n/g, ' ')`); + await shot('light-strip-hairline'); + await until(async () => (await drawerState()) === 'built', 'the model built in its drawer on the Map', 400); + assert.equal(await evaluate(`window.__noReload`), 1, 'The page was not reloaded'); + assert.equal(await evaluate(`location.hash`), '#map/recipes%2Fslow'); + const slowRuns = (await api('runs', { reference: 'recipes/slow' })).runs; + assert.equal(slowRuns[0].state, 'succeeded'); assert.equal((await api('build_request', { request: slowAsk.id })).state, 'succeeded'); + await key('Escape', 'Escape', 27); await until(() => evaluate(`document.getElementById('needs-panel').hidden`), 'Needs you closed'); + await settled('slow built'); + assert.match(await evaluate(`document.getElementById('aside').innerText`), /trained \d/); + check('Approved from Needs you: the strip hairline read ' + widths.join(', ') + ' % (partly filled at ' + partly + ' %: "' + stripText.slice(0, 120) + '"), then the run succeeded and the drawer on the Map shows recipes/slow built, without a reload'); + + // ---- A request awaiting approval: its controls; decline with a reason --------------- + await hash('train/request:' + fitAsk.id); + const buttons = await evaluate(`[...document.querySelectorAll('#aside .act-group button')].map(b => b.textContent)`); + assert.deepEqual(buttons, ['Approve', 'Decline', 'Cancel']); + await shots('request-awaiting'); + await press(byKey('request:' + fitAsk.id + ':decline')); + await until(() => evaluate(`document.activeElement && document.activeElement.dataset.key === ${JSON.stringify('request:' + fitAsk.id + ':field:reason')}`), 'the reason field focused'); + const reason = 'Not now: fit-b waits for the new numbers.'; + await send('Input.insertText', { text: reason }); + await shots('decline-reason'); + await press(byKey('request:' + fitAsk.id + ':decline:confirm')); + await until(async () => (await drawerText()).includes('Declined: ' + reason), 'the reason on the request'); + await settled('declined'); + const declined = await api('build_request', { request: fitAsk.id }); + assert.equal(declined.state, 'declined'); assert.equal(declined.problem, reason); + assert.deepEqual(await evaluate(`[...document.querySelectorAll('#aside .act-group button')].map(b => b.textContent)`), []); + check('Declined ' + fitAsk.id.slice(0, 8) + ' with the reason "' + reason + '", shown on the request; it has no control left'); + + // ---- Plan the hold recipe from Train, request it, read its run live ------------------ + await hash('train'); + await press(byKey('todo:recipes/hold:plan')); + await until(() => evaluate(`location.hash === '#train/plan%3Arecipes%2Fhold' && !!document.querySelector('#aside .plan-view')`), 'the plan view of recipes/hold'); + await settled('plan'); + const plan = await evaluate(`({ lead: document.querySelector('#aside .plan-lead').textContent, steps: [...document.querySelectorAll('#aside .steps > li')].map(li => li.querySelector('.title').textContent), totals: [...document.querySelectorAll('#aside .plan-view h3 + p, #aside .plan-view h3 ~ p.small')].map(p => p.textContent), scratch: !!document.querySelector('#aside input[type="checkbox"]'), request: document.querySelector('#aside .act-group button').textContent })`); + assert.ok(plan.steps.some(t => /Build · Held fit/.test(t)), JSON.stringify(plan)); assert.ok(plan.scratch); assert.equal(plan.request, 'Request build'); + await shots('plan-view'); + await press(byKey('request:plan:recipes/hold:request')); + await until(() => evaluate(`location.hash.startsWith('#train/request%3A')`), 'the request opened'); + const holdId = decodeURIComponent(await evaluate(`location.hash`)).slice('#train/request:'.length); + const holdRun = await until(async () => { const r = await api('build_request', { request: holdId }); return r.runs.find(x => x.state === 'running'); }, 'the hold run running', 300); + await hash('train/run:' + holdRun.id); + const firstLines = await until(() => evaluate(`(() => { const p = document.querySelector('#aside pre[data-log="stdout"]'); const i = document.querySelector('#aside .progress-line .hair i'); return p && i && !p.hidden && parseFloat(i.style.width) > 0 ? p.textContent.split('\\n').length : 0; })()`), 'the run drawer with its hairline and log', 200); + const grown = await until(() => evaluate(`(() => { const n = document.querySelector('#aside pre[data-log="stdout"]').textContent.split('\\n').length; return n > ${firstLines} ? n : 0; })()`), 'the log read on', 100); + const liveLine = await evaluate(`document.querySelector('#aside .progress-line').innerText`); + assert.ok(await evaluate(`[...document.querySelectorAll('#aside .act-group button')].some(b => b.textContent === 'Cancel run')`)); + await shots('run-live'); + check('Planned recipes/hold from Train (' + plan.steps.length + ' steps: ' + plan.steps.join(' | ') + '; "' + plan.lead + '"), requested it (' + holdId.slice(0, 8) + '); its run drawer reads on live: "' + liveLine + '", the log grew from ' + firstLines + ' to ' + grown + ' lines'); + + // ---- While it runs: plan a model from its drawer on the Map, request, cancel with two presses ---- + await hash('map/recipes/fit-a'); + await press(byKey('model:recipes/fit-a:plan')); + await until(() => evaluate(`location.hash === '#map/plan%3Arecipes%2Ffit-a' && !!document.querySelector('#aside .plan-view')`), 'the plan view from the drawer'); + await settled('plan from drawer'); + await shot('light-plan-view-map'); + await press(byKey('request:plan:recipes/fit-a:request')); + await until(() => evaluate(`location.hash.startsWith('#train/request%3A')`), 'the fit-a request opened'); await settled('fit-a request'); + const fitAId = decodeURIComponent(await evaluate(`location.hash`)).slice('#train/request:'.length); + assert.equal((await api('build_request', { request: fitAId })).state, 'queued'); + await press(byKey('request:' + fitAId + ':cancel')); + await until(() => evaluate(`!!document.querySelector('#aside ${byKey('request:' + fitAId + ':cancel:confirm')}')`), 'the two-press state'); + assert.equal(await evaluate(`document.activeElement.dataset.key`), 'request:' + fitAId + ':cancel:confirm'); + const words = await evaluate(`document.querySelector('#aside .confirm-words').textContent`); + await shots('two-press'); + await key('Escape', 'Escape', 27); + await until(() => evaluate(`!document.querySelector('#aside .confirm-words') && document.activeElement.dataset.key === ${JSON.stringify('request:' + fitAId + ':cancel')}`), 'Escape leaves the two-press state and the focus is back on Cancel'); + assert.ok(await evaluate(`document.getElementById('drawer').classList.contains('open')`), 'Escape left the two-press state, not the drawer'); + await press(byKey('request:' + fitAId + ':cancel')); + await until(() => evaluate(`!!document.querySelector('#aside ${byKey('request:' + fitAId + ':cancel:confirm')}')`), 'the two-press state again'); + await pause(4500); // two refreshes of the strip and the tab while the hold run runs + assert.equal(await evaluate(`document.activeElement.dataset.key`), 'request:' + fitAId + ':cancel:confirm', 'The two-press state and its focus outlive the refresh'); + await press(byKey('request:' + fitAId + ':cancel:confirm')); + await until(async () => (await drawerState()) === 'cancelled', 'the fit-a request cancelled'); await settled('cancelled'); + assert.equal((await api('build_request', { request: fitAId })).state, 'cancelled'); + check('Planned recipes/fit-a from its drawer on the Map, requested it (queued behind the hold run), pressed Cancel: "' + words + '"; Escape left that state, which outlived two refreshes; Confirm cancelled it'); + + // ---- A refusal shown inline: a plan with blocked targets --------------------------------- + await hash('train'); + await press(byKey('train:every:plan')); + await until(() => evaluate(`location.hash === '#train/plan%3A*' && !!document.querySelector('#aside .plan-view')`), 'the plan of everything'); await settled('plan everything'); + const blocked = await evaluate(`document.querySelector('#aside .plan-view .failure').textContent`); + const refused = allow(/\/api\/project\/request_build$/, 409); + await press(byKey('request:plan:*:request')); + const refusal = await until(() => evaluate(`(() => { const r = document.querySelector('#aside .refusal'); return r && r.innerText; })()`), 'the refusal inline'); + close(refused); + assert.match(refusal, /cannot be built/); + assert.equal(await evaluate(`document.activeElement.dataset.key`), 'request:plan:*:request', 'The focus stays on the refused control'); + await evaluate(`document.querySelector('#aside .refusal').scrollIntoView({ block: 'center' })`); + await shots('refusal'); + check('Plan everything buildable says "' + blocked.slice(0, 90) + '…"; Request build was refused inline: "' + refusal.replace(/\n/g, ' ').slice(0, 160) + '"'); + + // ---- Plan from a Train row, request, cancel --------------------------------------------------- + await hash('train'); + await press(byKey('todo:recipes/fit-b:plan')); + await until(() => evaluate(`!!document.querySelector('#aside .plan-view') && location.hash === '#train/plan%3Arecipes%2Ffit-b'`), 'the plan of fit-b'); await settled('plan fit-b'); + await press(byKey('request:plan:recipes/fit-b:request')); + await until(() => evaluate(`location.hash.startsWith('#train/request%3A')`), 'the fit-b request opened'); await settled('fit-b request'); + const fitBId = decodeURIComponent(await evaluate(`location.hash`)).slice('#train/request:'.length); + await press(byKey('request:' + fitBId + ':cancel')); await press(byKey('request:' + fitBId + ':cancel:confirm')); + await until(async () => (await drawerState()) === 'cancelled', 'the fit-b request cancelled'); await settled('cancelled b'); + assert.equal((await api('build_request', { request: fitBId })).state, 'cancelled'); + await inspect('fit-b cancelled'); + check('Planned recipes/fit-b from its row on Train, requested and cancelled it with two presses'); + + // ---- Cancel the running run ------------------------------------------------------------------ + await hash('train/run:' + holdRun.id); + await press(byKey('run:' + holdRun.id + ':cancel')); + const runWords = await evaluate(`document.querySelector('#aside .confirm-words').textContent`); + await press(byKey('run:' + holdRun.id + ':cancel:confirm')); + await until(async () => (await drawerState()) === 'cancelled', 'the hold run cancelled in its drawer', 300); await settled('run cancelled'); + assert.equal((await api('run', { run: holdRun.id })).state, 'cancelled'); + await until(async () => !['queued', 'running'].includes((await api('build_request', { request: holdId })).state), 'the hold request ended'); + await inspect('run cancelled'); + check('Cancelled the running run ' + holdRun.id.slice(0, 8) + ' ("' + runWords + '"); its drawer turned to cancelled on its own'); + + // ---- Environments: connect one (a refusal first), check one again --------------------------- + await hash('train/env:environments/lab-cpu'); + const field = byKey('envconnect:environments/lab-cpu:field:interpreter'); + await type(field, 'python'); + const invalid = allow(/\/api\/project\/connect_environment$/, 400); + await press(byKey('envconnect:environments/lab-cpu:connect')); + const notAbsolute = await until(() => evaluate(`(() => { const r = document.querySelector('#aside .refusal'); return r && r.innerText; })()`), 'the connect refusal'); + close(invalid); + assert.equal(await evaluate(`document.querySelector(${JSON.stringify('#aside ' + field)}).value`), 'python', 'The typed path stays after the refusal'); + await type(field, python); + await press(byKey('envconnect:environments/lab-cpu:connect')); + await until(async () => (await drawerText()).includes(python) && !(await evaluate(`!!document.querySelector('#aside .refusal')`)), 'lab-cpu connected'); await settled('connected'); + const labCpu = await api('environment', { reference: 'environments/lab-cpu' }); + assert.equal(labCpu.interpreter, python); assert.ok(labCpu.checked_at); + assert.ok(await evaluate(`[...document.querySelectorAll('#aside .act-group button')].map(b => b.textContent).join() === 'Check again,Connect,Disconnect'`), 'Check again, Connect and Disconnect on a connected environment'); + await inspect('env connected'); await shot('light-environment'); + const before = (await api('environment', { reference: 'environments/test-python' })).checked_at; + await pause(1100); + await hash('train/env:environments/test-python'); + await press(byKey('envcheck:environments/test-python:check')); + await until(async () => (await api('environment', { reference: 'environments/test-python' })).checked_at !== before, 'test-python checked again'); await settled('checked'); + await inspect('env checked'); + await hash('train/env:environments/lab-cpu'); + await press(byKey('envdisconnect:environments/lab-cpu:disconnect')); + const forget = await evaluate(`document.querySelector('#aside .confirm-words').textContent`); + await press(byKey('envdisconnect:environments/lab-cpu:disconnect:confirm')); + await until(async () => (await drawerText()).includes('none recorded on this machine'), 'lab-cpu disconnected'); await settled('disconnected'); + assert.equal((await api('environment', { reference: 'environments/lab-cpu' })).interpreter, null); + await inspect('env disconnected'); + check('lab-cpu: "python" was refused inline ("' + notAbsolute.replace(/\n/g, ' ') + '"), then ' + python + ' connected (' + labCpu.state + ') and disconnected again ("' + forget + '"); test-python checked again (' + before + ' → newer)'); + + // ---- Save from the strip ---------------------------------------------------------------------- + const fitBText = (await api('definition', { reference: 'recipes/fit-b' })).text; + await api('set_definition', { reference: 'recipes/fit-b', text: fitBText.replace('"Fit b, with inline settings"', '"Fit b, saved from the strip"') }); + await evaluate(`window.dispatchEvent(new Event('focus'))`); + await until(() => evaluate(`!!document.querySelector('#strip ${byKey('save:save')}')`), 'Save on the strip'); + const unsaved = await evaluate(`document.querySelector('#strip .unsaved .count').textContent`); + await shot('light-strip-save'); + await press('#strip ' + byKey('save:save')); + await until(() => evaluate(`!document.querySelector('#strip .unsaved')`), 'nothing unsaved'); await settled('saved'); + assert.match(fs.readFileSync(path.join(folder, 'recipes', 'fit-b.json'), 'utf8'), /Fit b, saved from the strip/); + await inspect('saved'); + check('The strip said "' + unsaved + '"; Save wrote recipes/fit-b.json'); + + // ---- A conflict, resolved both ways -------------------------------------------------------------- + const fitAFile = path.join(folder, 'recipes', 'fit-a.json'), fitAText = fs.readFileSync(fitAFile, 'utf8'); + await api('set_definition', { reference: 'recipes/fit-a', text: fitAText.replace('"Fit a, from a settings file"', '"Fit a, my edit"') }); + fs.writeFileSync(fitAFile, fitAText.replace('"Fit a, from a settings file"', '"Fit a, changed on disk"')); + let conflicted = allow(/\/api\/project\//, 409); + await evaluate(`window.dispatchEvent(new Event('focus'))`); + const panel = await until(() => evaluate(`(() => { const c = document.querySelector('#main .conflict'); return c && c.innerText; })()`), 'the conflict panel'); + assert.match(panel, /recipes\/fit-a/); + await shots('conflict'); + await press(byKey('conflict:keep')); + await until(() => evaluate(`!document.querySelector('#main .conflict') && !!document.querySelector('#strip .unsaved')`), 'the project read with my edit kept'); close(conflicted); await settled('kept'); + let fitA = await api('definition', { reference: 'recipes/fit-a' }); + assert.equal(fitA.title, 'Fit a, my edit'); assert.equal(fitA.unsaved, true); + fs.writeFileSync(fitAFile, fitAText.replace('"Fit a, from a settings file"', '"Fit a, changed on disk again"')); + conflicted = allow(/\/api\/project\//, 409); + await evaluate(`window.dispatchEvent(new Event('focus'))`); + await until(() => evaluate(`!!document.querySelector('#main .conflict')`), 'the conflict panel again'); + await press(byKey('conflict:discard')); + const takeWords = await evaluate(`document.querySelector('#main .confirm-words').textContent`); + await press(byKey('conflict:discard:confirm')); + await until(() => evaluate(`!document.querySelector('#main .conflict') && !document.querySelector('#strip .unsaved')`), 'the project read with the files taken'); close(conflicted); await settled('taken'); + fitA = await api('definition', { reference: 'recipes/fit-a' }); + assert.equal(fitA.title, 'Fit a, changed on disk again'); assert.equal(fitA.unsaved, false); + await inspect('conflict resolved'); + check('A conflict on recipes/fit-a: the panel named it; Keep my edits kept "Fit a, my edit" unsaved; a second one, Take the files ("' + takeWords + '"), took "Fit a, changed on disk again"'); + + // ---- A session that may only inspect: no control is drawn --------------------------------------------- + await send('Page.navigate', { url: 'about:blank' }); + await send('Network.clearBrowserCookies'); + const result = await send('Network.setCookie', { name: 'tuldok_session', value: inspector, url: origin + '/', httpOnly: true, sameSite: 'Strict', path: '/' }); + assert.notEqual(result.success, false); + const cookies = (await send('Network.getCookies', { urls: [origin + '/'] })).cookies.filter(c => c.name === 'tuldok_session'); + assert.deepEqual(cookies.map(c => c.value === inspector), [true], 'The browser holds the inspector\'s credential alone'); + const seen = []; + for (const place of ['map/recipes%2Ffit-b', 'train', 'train/request:' + fitAsk.id, 'train/request:' + holdId, 'train/run:' + holdRun.id, 'train/env:environments%2Flab-cpu', 'train/plan:recipes%2Ffit-b', 'overview']) { + await open(place); + assert.equal(await evaluate(`document.getElementById('session-identity').textContent`), 'A browser check inspector · agent'); + if (place === 'train') { await press('#needs-btn'); await until(() => evaluate(`!document.getElementById('needs-panel').hidden`), 'Needs you'); } + const drawn = await evaluate(`[...document.querySelectorAll('button.act, #aside input[type="checkbox"], .act-field')].filter(e => e.offsetParent !== null || e.closest('#needs-panel')).map(b => b.textContent || b.type)`); + assert.deepEqual(drawn, [], 'No control for an inspector on ' + place); + seen.push(place); + } + await shot('light-inspector-overview'); + check('Signed in with a credential that may only inspect: no control on ' + seen.join(', ')); + + // ---- Nothing failed but what was provoked --------------------------------------------------------------- + assert.deepEqual(errors, [], 'Script errors'); + assert.deepEqual(failures, [], 'Failed requests'); + for (const a of allowed) assert.ok(a.seen > 0, 'A provoked refusal was seen: ' + a.re); + check('No script error, no failed request but the ' + allowed.reduce((n, a) => n + a.seen, 0) + ' provoked refusals, no overflow, no control left disabled'); + fs.writeFileSync(path.join(report, 'receipt.json'), JSON.stringify({ status: 'pass', folder, checks, bounds }, null, 2) + '\n'); + console.log('Screenshots and receipt in ' + report); +})().catch(async error => { + process.exitCode = 1; + console.error(error); if (serverErrors) console.error('Server:', serverErrors.slice(-4000)); + console.error('Script errors:', JSON.stringify(errors)); console.error('Failed requests:', JSON.stringify(failures)); + try { if (evaluate) { await shot('failure'); console.error('Page:', (await evaluate('document.body.innerText')).slice(0, 3000)); } } catch (_) { /* the page is gone */ } + fs.writeFileSync(path.join(report, 'failure.json'), JSON.stringify({ status: 'failed', error: String(error && error.stack || error), checks, bounds, errors, failures }, null, 2) + '\n'); + console.error('Screenshots in ' + report); +}).finally(async () => { + try { session?.close(); } catch (_) { /* closed */ } + for (const child of children.reverse()) await stop(child); + if (owned) try { dropOwned(...owned); } catch (error) { console.error('Dropping the disposable schemas failed:', error.message); process.exitCode = 1; } + try { execFileSync('chmod', ['-R', 'u+w', temporary]); } catch (_) { /* nothing was made read-only */ } // finished runs leave their directories read-only + fs.rmSync(temporary, { recursive: true, force: true }); +}); diff --git a/tests/test_tuldok_project_http.py b/tests/test_tuldok_project_http.py index 53e96d21..dae01fae 100644 --- a/tests/test_tuldok_project_http.py +++ b/tests/test_tuldok_project_http.py @@ -47,6 +47,7 @@ '/project-workspace/markdown.js': 'text/javascript', '/project-workspace/tree.js': 'text/javascript', '/project-workspace/screens.js': 'text/javascript', + '/project-workspace/actions.js': 'text/javascript', '/project-workspace/tabs.js': 'text/javascript', '/project-workspace/app.js': 'text/javascript', '/static/vendor/ubuntu-sans/UbuntuSans[wdth,wght].ttf': 'font/ttf', From 597452df283b65b4dd0dedd3e1356b3538c13840 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 12 Nov 2026 15:58:51 -0700 Subject: [PATCH 049/131] feat(app): edit definitions and branch a model from the workspace The editor opens in the drawer for any definition: a text view for every kind and a form for recipes (title, short label, group, kind of change, parent picked on the map, description, environment, dataset inputs, settings, resources). Keep stores an unsaved edit, Save writes the folder, Discard edit reverts. Branch from here drafts a new model from its parent, drawn hollow and dashed on the map until it is built, with the steps from draft to built and one button for the next step. The idle page now asks again every fifteen seconds, so a build an agent asks for reaches Needs you while the page is open. The acceptance run of spec-w3 is tests/acceptance_project_workspace.cjs. Co-Authored-By: Claude Fable 5.2 --- app.py | 1 + .../definition-first-projects/spec-w3.md | 2 +- static/project-workspace.html | 1 + static/project-workspace/actions.js | 11 +- static/project-workspace/adapter.js | 64 ++- static/project-workspace/app.js | 30 +- static/project-workspace/base.css | 60 ++- static/project-workspace/editor.js | 488 ++++++++++++++++++ static/project-workspace/screens.js | 46 +- static/project-workspace/tabs.js | 61 ++- static/project-workspace/tree.js | 24 +- tests/acceptance_project_workspace.cjs | 281 ++++++++++ tests/browser_project_workspace_actions.cjs | 283 +++++++++- tests/test_tuldok_project_http.py | 1 + 14 files changed, 1287 insertions(+), 66 deletions(-) create mode 100644 static/project-workspace/editor.js create mode 100644 tests/acceptance_project_workspace.cjs diff --git a/app.py b/app.py index ab1eef59..040e5698 100644 --- a/app.py +++ b/app.py @@ -992,6 +992,7 @@ def _get(self): '/project-workspace/tree.js': ('project-workspace/tree.js', 'text/javascript'), '/project-workspace/screens.js': ('project-workspace/screens.js', 'text/javascript'), '/project-workspace/actions.js': ('project-workspace/actions.js', 'text/javascript'), + '/project-workspace/editor.js': ('project-workspace/editor.js', 'text/javascript'), '/project-workspace/tabs.js': ('project-workspace/tabs.js', 'text/javascript'), '/project-workspace/app.js': ('project-workspace/app.js', 'text/javascript'), '/static/vendor/ubuntu-sans/UbuntuSans[wdth,wght].ttf': ('vendor/ubuntu-sans/UbuntuSans[wdth,wght].ttf', 'font/ttf'), diff --git a/docs/plans/definition-first-projects/spec-w3.md b/docs/plans/definition-first-projects/spec-w3.md index b52690ff..b9f2a53e 100644 --- a/docs/plans/definition-first-projects/spec-w3.md +++ b/docs/plans/definition-first-projects/spec-w3.md @@ -50,7 +50,7 @@ The contract document gains both operations, the `map` additions and the two com | A model's drawer (Map) | **Plan build** when the model is not built, out of date or failed | | Conflict | When a read is refused `conflict`, the main area shows the server's sentence, the definitions named, and **Keep my edits** and **Take the files** (`resolve_conflict` with `keep` or `discard`); then everything is read again | -While a build request is queued or running the page asks again every two seconds, as in phase 2, and now also for the open run's progress and logs and for `map` when a run ends, so a model turns to built without a reload. +While a build request is queued or running the page asks again every two seconds, as in phase 2, and now also for the open run's progress and logs and for `map` when a run ends, so a model turns to built without a reload. While nothing is queued or running it asks again every fifteen seconds for the build requests, runs, status and environments, so a build an agent asks for reaches Needs you while the page is open. *Added at the acceptance run:* phase 2 read again only when the window regained focus. ### 3.2 Editing and branching (slice T22) diff --git a/static/project-workspace.html b/static/project-workspace.html index 0387577c..4b729afe 100644 --- a/static/project-workspace.html +++ b/static/project-workspace.html @@ -15,6 +15,7 @@ + diff --git a/static/project-workspace/actions.js b/static/project-workspace/actions.js index c2d2a852..1b4035bc 100644 --- a/static/project-workspace/actions.js +++ b/static/project-workspace/actions.js @@ -43,7 +43,9 @@ window.LabActions = (() => { /** * A group of controls bound to key: an element that draws its items from * the group's state whenever it changes and on every re-render. An item is - * { id, label, cls, who, op, args(slot) -> arguments, busy (the words while + * { id, label, cls, who, op, args(slot) -> arguments (or run(slot), a step + * of the page that throws to refuse; with local, nothing is read again + * after it), busy (the words while * waiting), confirm (words: the item takes two presses), input ({name, * label, placeholder, max, always}: a field shown always, or in the * confirm state), done(result), extra(error) (more under a refusal), @@ -123,15 +125,18 @@ window.LabActions = (() => { if (it.confirm && !confirmed) { s.confirming = it.id; s.refusal = null; refill(key); focusKey(key + ':' + (it.input && !it.input.always ? 'field:' + it.input.name : it.id + ':confirm')); return; } s.busy = it.id; s.refusal = null; refill(key); let result, error = null; - try { result = await P.call(it.op, it.args ? it.args(s) : {}); } catch (e) { error = e; } + // run(slot): a step of the page itself (editor.js), which may call operations; it throws to refuse. + try { result = it.run ? await it.run(s) : await P.call(it.op, it.args ? it.args(s) : {}); } catch (e) { error = e; } s.busy = null; if (error) { s.refusal = { error, item: it.id }; refill(key); focusKey(key + ':' + it.id) || focusKey(key + ':' + it.id + ':confirm'); - await hooks.refused({ key, item: it, error }); + if (!it.local) await hooks.refused({ key, item: it, error }); return; } s.confirming = null; s.text = {}; refill(key); + // local: nothing in the project changed, so nothing is read again. + if (it.local) { if (it.done) it.done(result); return; } P.forgetAll(); if (it.done) it.done(result); await hooks.changed({ key, item: it, result, focus: key + ':' + it.id }); diff --git a/static/project-workspace/adapter.js b/static/project-workspace/adapter.js index b920e083..10cf975e 100644 --- a/static/project-workspace/adapter.js +++ b/static/project-workspace/adapter.js @@ -75,10 +75,12 @@ window.TuldokProject = (() => { * sections (one per group that has models, the group tree read depth * first in authored order, then one section "Not in a group" when a model * names no group), models in section order and, within a section, in the - * map's order (training date, then those without one), inputs as lines, - * comparisons and the track with its scale. + * map's order (training date, then those without one) except that one + * without a date naming a parent comes right after it (placed()), inputs + * as lines, comparisons and the track with its scale. The page's drafts + * (editor.js) are models too, marked draft. */ - function shapeMap(raw) { + function shapeMap(raw, drafts = []) { const groups = new Map(raw.groups.map(g => [g.id, g])); const children = new Map(), roots = []; for (const g of raw.groups) { @@ -93,16 +95,25 @@ window.TuldokProject = (() => { id: m.reference, title: m.title, short: m.short, description: m.description || '', group: groups.has(m.group) ? m.group : null, kind: kinds.has(m.change) ? m.change : UNSET, parent: m.derived_from || null, trainedAt: m.trained_at, state: m.state, adopted: m.adopted, card: m.card, - value: m.value, count: m.count, benchmarks: m.benchmarks + value: m.value, count: m.count, benchmarks: m.benchmarks, unsaved: !!m.unsaved, + // Never built: drawn hollow and dashed (spec-w3 section 3.2). + planned: m.state === 'not-built' && !m.adopted && !m.trained_at })); + // A draft (editor.js) is a model of the page only, after its parent's models. + for (const d of drafts) models.push({ + id: d.reference, title: d.title, short: d.short || null, description: d.description || '', + group: groups.has(d.group) ? d.group : null, kind: kinds.has(d.change) ? d.change : UNSET, + parent: d.parent, trainedAt: null, state: 'draft', adopted: false, card: null, + value: null, count: null, benchmarks: 0, unsaved: false, planned: true, draft: true + }); const byId = new Map(models.map(m => [m.id, m])); for (const m of models) if (m.parent && !byId.has(m.parent)) m.parent = null; const sections = []; for (const { group, up } of order) { - const list = models.filter(m => m.group === group.id); + const list = placed(models.filter(m => m.group === group.id)); if (list.length) sections.push({ id: group.id, title: group.title, up, description: group.description, models: list }); } - const loose = models.filter(m => m.group === null); + const loose = placed(models.filter(m => m.group === null)); if (loose.length) sections.push({ id: null, title: 'Not in a group', up: [], loose: true, models: loose }); for (const s of sections) for (const m of s.models) m.groupTitle = s.title; const derived = new Set(raw.edges.filter(e => e.kind === 'derived').map(e => e.from + ' ' + e.to)); @@ -113,10 +124,40 @@ window.TuldokProject = (() => { const trackScale = track ? window.LabCharts.scale(models.map(m => m.value), track.metric.better) : null; return { sections, models: sections.flatMap(s => s.models), byId, inputs, comparisons, track, trackScale, groups: raw.groups }; } - let mapRaw = null, mapShaped = null; + /** + * One section's models in the map's order, except that a model without a + * date naming a parent in the same section comes right after that parent, + * after the parent's earlier such children (spec-w3 section 3.2). Linear. + */ + function placed(list) { + const here = new Set(list.map(m => m.id)), after = new Map(), moved = new Set(); + for (const m of list) if (!m.trainedAt && m.parent && m.parent !== m.id && here.has(m.parent)) { + if (!after.has(m.parent)) after.set(m.parent, []); + after.get(m.parent).push(m); moved.add(m.id); + } + if (!moved.size) return list; + const out = [], seen = new Set(); + const emit = m => { if (seen.has(m.id)) return; seen.add(m.id); out.push(m); for (const c of after.get(m.id) || []) emit(c); }; + for (const m of list) if (!moved.has(m.id)) emit(m); + for (const m of list) emit(m); // a loop of parents without dates (never stored): kept, in the map's order + return out; + } + // The drafts of the page (editor.js): drawn on the map, never sent anywhere. A draft + // whose parent is gone, or whose reference the project now has, is dropped + // (onDrop tells editor.js); a session that may not edit draws none. + let drafts = [], draftsVersion = 0, onDrop = () => {}; + function setDrafts(list, dropped) { drafts = list.slice(); draftsVersion++; if (dropped) onDrop = dropped; } + let mapRaw = null, mapShaped = null, mapKey = ''; async function map() { const raw = await read('map'); - if (raw !== mapRaw) { mapRaw = raw; mapShaped = shapeMap(raw); } + const editing = !!(window.LabActions && window.LabActions.may('edit')), key = draftsVersion + ' ' + editing; + if (raw !== mapRaw || key !== mapKey) { + const refs = new Set(raw.models.map(m => m.reference)); + const gone = drafts.filter(d => !refs.has(d.parent) || refs.has(d.reference)); + const shown = editing ? drafts.filter(d => !gone.includes(d)) : []; + mapRaw = raw; mapKey = key; mapShaped = shapeMap(raw, shown); + if (gone.length) onDrop(gone); + } return mapShaped; } const trackName = track => track ? track.metric.title + ' · ' + track.statistic : ''; @@ -131,14 +172,15 @@ window.TuldokProject = (() => { * model states and, once read, the runs and build requests. */ function standing(shaped, runs, requests) { - const count = s => shaped.models.filter(m => s.includes(m.state)).length; + const models = shaped.models.filter(m => !m.draft), count = s => models.filter(m => s.includes(m.state)).length; const built = count(['built']), toBuild = count(['not-built', 'out-of-date', 'failed']), cannot = count(['cannot-rebuild']), work = count(['needs-work']); const parts = [(built ? built : 'none') + ' built', toBuild + ' to build', cannot + ' cannot be rebuilt']; if (work) parts.push(work + (work === 1 ? ' needs' : ' need') + ' work'); - let text = plural(shaped.models.length, 'model', 'models') + ': ' + parts.join(', ') + '.'; + let text = plural(models.length, 'model', 'models') + ': ' + parts.join(', ') + '.'; const running = (runs || []).filter(r => r.state === 'running'), queued = (requests || []).filter(r => r.state === 'queued' || r.state === 'running'); let tone = 'good', word = 'Idle'; if (running.length) { tone = 'pending'; word = 'Building'; text += ' Running ' + running.map(r => titleOf(shaped, r.reference) + (r.subject ? ' (' + r.subject + ')' : '')).join(', ') + '.'; } + else if (queued.some(r => r.state === 'running')) { tone = 'pending'; word = 'Building'; text += ' A build is between two of its steps.'; } // a request runs, none of its runs does at this moment else if (queued.length) { tone = 'pending'; word = 'Queued'; text += ' ' + plural(queued.length, 'build request is', 'build requests are') + ' queued.'; } else if (runs && requests) text += ' Nothing is running.'; return { tone, word, text }; @@ -174,5 +216,5 @@ window.TuldokProject = (() => { return out; } - return { KINDS, UNSET, kindLabel, stateWord, call, read, forget, forgetAll, map, trackName, better, units, standing, needs, titleOf, day }; + return { KINDS, UNSET, kindLabel, stateWord, call, read, forget, forgetAll, map, setDrafts, trackName, better, units, standing, needs, titleOf, day }; })(); diff --git a/static/project-workspace/app.js b/static/project-workspace/app.js index ebe4ab1b..311fb2da 100644 --- a/static/project-workspace/app.js +++ b/static/project-workspace/app.js @@ -8,16 +8,18 @@ // queued or running the strip asks again every two seconds for what can // change, the open run reads on its progress and logs, and when a run ends // the map and everything else is read again, so a model turns to built -// without a reload. A read refused conflict shows the conflict panel. +// without a reload. While nothing builds it asks again every fifteen seconds, +// so a build an agent asks for shows in Needs you while the page is open. +// A read refused conflict shows the conflict panel. (() => { const P = window.TuldokProject, S = window.LabScreens, A = window.LabActions; const TABS = [['map', 'Map'], ['data', 'Data'], ['train', 'Train'], ['benchmarks', 'Benchmarks'], ['analysis', 'Analysis'], ['overview', 'Overview']]; - const POLL_MS = 2000; + const POLL_MS = 2000, IDLE_MS = 15000; // how often the page asks again while something builds, and while nothing does const ACTIVE_RUN = ['queued', 'running'], ACTIVE_REQUEST = ['queued', 'running']; const $ = id => document.getElementById(id); const state = { screen: 'map', sel: {}, kinds: null, query: '', zoom: 1, track: false, ui: {}, benchmark: null, cmp: [] }; const data = { summary: null, map: null, standing: null, needs: null, status: null, readAt: '', polling: false }; - let failed = null, conflict = null, mapText = null, pollTimer = null, states = null, opener = null; + let failed = null, conflict = null, mapText = null, pollTimer = null, pollFast = false, states = null, opener = null; const clock = () => new Date().toLocaleTimeString('en-GB', { hour: '2-digit', minute: '2-digit' }); function parse() { @@ -46,7 +48,11 @@ toggleCompare: id => { const i = state.cmp.indexOf(id); if (i >= 0) state.cmp.splice(i, 1); else if (state.cmp.length < 3) state.cmp.push(id); address(); render(); }, clearCompare: () => { state.cmp = []; address(); render(); }, /** Reads everything again (a control's answer came, or a view asks for it). */ - refresh: () => changed() + refresh: () => changed(), + /** Draws the map again from what is read (the page's drafts changed, editor.js); the drawer is kept. */ + redraw: async () => { try { data.map = await P.map(); } catch (error) { fail(error); } strip(); render(); }, + /** Draws the drawer afresh. */ + reopen: () => { $('aside')._for = null; render(); } }; /** Writes the benchmark and compare set into the address without reloading, so the view can be shared. */ function address() { @@ -109,7 +115,7 @@ drawer.classList.remove('open'); drawer.setAttribute('aria-hidden', 'true'); main.classList.remove('with-drawer'); aside.textContent = ''; aside._for = null; return; } - const wasMap = main.classList.contains('map'), view = state.screen + '/' + (state.screen === 'overview' ? state.sel.overview || '' : ''); // a selection elsewhere opens the drawer and keeps the place + const wasMap = main.classList.contains('map'), view = state.screen + '/' + (state.screen === 'overview' && state.sel.overview === 'report' ? 'report' : ''); // a selection opens the drawer and keeps the place; the report is its own view main.className = state.screen === 'map' ? 'map' : 'content'; if (state.screen !== 'map' && wasMap) main._tree = null; if (main._view !== view) { main.scrollTop = 0; main.scrollLeft = 0; main._view = view; } // a new screen starts at its top @@ -124,6 +130,7 @@ try { data.summary = await P.read('summary'); $('projname').textContent = data.summary.name; + if (window.LabEditor) window.LabEditor.load(data.summary.project_id); // the drafts of this project, kept for this tab data.map = await P.map(); mapText = JSON.stringify(await P.read('map')); data.standing = P.standing(data.map, null, null); data.readAt = clock(); failed = null; conflict = null; } catch (error) { fail(error); } @@ -157,10 +164,11 @@ } states = now; const busy = runs.runs.some(r => ACTIVE_RUN.includes(r.state)) || requests.requests.some(r => ACTIVE_REQUEST.includes(r.state)); - if (busy && !pollTimer) pollTimer = setTimeout(poll, POLL_MS); + later(busy); } catch (error) { if (error.code === 'conflict') { fail(error); strip(); render(); return; } data.needs = null; data.standing = Object.assign({}, data.standing, { text: data.standing.text + ' ' + error.message }); + later(false); } const aside = $('aside'); if (ended) { @@ -178,9 +186,14 @@ strip(); if (redraw || ['overview', 'train'].includes(state.screen)) render(); } + /** Asks again later: in two seconds while something builds, otherwise in fifteen, so a request an agent makes or an edit made elsewhere shows without the window losing and regaining focus. */ + function later(busy) { + if (pollTimer && busy && !pollFast) { clearTimeout(pollTimer); pollTimer = null; } + if (!pollTimer) { pollFast = busy; pollTimer = setTimeout(poll, busy ? POLL_MS : IDLE_MS); } + } async function poll() { pollTimer = null; - P.forget(['summary', 'runs', 'build_requests']); + P.forget(['summary', 'runs', 'build_requests'].concat(pollFast ? [] : ['status', 'environments'])); try { data.summary = await P.read('summary'); } catch (error) { /* the strip says what failed below */ } await standing(); if (S.tick) await S.tick(); @@ -225,13 +238,14 @@ window.addEventListener('keydown', e => { if (e.key !== 'Escape') return; if (A.escape()) return; + if (window.LabEditor && window.LabEditor.escape()) return; if (!$('needs-panel').hidden) { $('needs-panel').hidden = true; const b = $('needs-btn'); if (b) { b.setAttribute('aria-expanded', 'false'); b.focus(); } return; } if ($('drawer').classList.contains('open') && state.sel[state.screen]) go(state.screen); }); window.addEventListener('hashchange', () => { parse(); render(); }); window.addEventListener('focus', () => { if (data.summary || failed) again(); }); // Who may use a control comes from the session: draw the controls again when it changes. - window.addEventListener('tuldok-session', () => { if (failed) again(); else { $('aside')._for = null; strip(); render(); } }); + window.addEventListener('tuldok-session', () => { if (failed) again(); else { $('aside')._for = null; if (data.map) act.redraw(); else { strip(); render(); } } }); { const q = new URLSearchParams(location.search); state.benchmark = q.get('benchmark') || null; state.cmp = (q.get('cmp') || '').split(',').filter(Boolean).slice(0, 3); } parse(); strip(); render(); first(); } diff --git a/static/project-workspace/base.css b/static/project-workspace/base.css index f86ac31a..3b038e6a 100644 --- a/static/project-workspace/base.css +++ b/static/project-workspace/base.css @@ -485,7 +485,7 @@ textarea { font: inherit; resize: vertical; } .form { display: grid; gap: 10px; } .form label { display: grid; gap: 3px; font-size: 12.5px; color: var(--ink-2); } .form select, .form input[type="text"], .form textarea { width: 100%; font: inherit; color: var(--ink); background: var(--surface); border: 1px solid var(--line-strong); border-radius: var(--radius); padding: 5px 8px; } -.form .two { display: grid; grid-template-columns: 1fr 1fr; gap: 10px; } +.form .two { display: grid; grid-template-columns: 1fr 1fr; gap: 10px; align-items: start; } /* a field with a hint beside one without: both start at the top */ .form .hint, .act-field .hint { font-family: var(--mono); font-size: 11.5px; color: var(--ink-3); } .form .radio { display: flex; flex-wrap: wrap; gap: 6px; } .form .radio label { display: inline-flex; align-items: center; gap: 6px; padding: 4px 10px; border: 1px solid var(--line-strong); border-radius: 999px; color: var(--ink); cursor: pointer; } @@ -536,3 +536,61 @@ textarea { font: inherit; resize: vertical; } .conflict-refs { margin: 0; padding-left: 18px; } .plain { list-style: none; margin: 0; padding: 0; display: grid; gap: 4px; } .warnline { color: var(--warn); } + +/* ---- Editing and branching (editor.js, spec-w3 section 3.2). ---- */ +/* A model never built: hollow and dashed, in its kind's colour; a draft is labelled "new" (the mockup's planned model). */ +.tree-map .node.planned circle { fill: var(--surface); stroke: var(--k-component); stroke-dasharray: 3 2; stroke-width: 2; } +.tree-map .node.planned.training-policy circle { stroke: var(--k-training-policy); } +.tree-map .node.planned.architecture circle { stroke: var(--k-architecture); } +.tree-map .node.planned.refinement circle { stroke: var(--k-refinement); } +.tree-map .node.planned.unset circle { stroke: var(--ink-3); } +.tree-map .node.planned.sel circle { stroke: var(--accent); stroke-width: 3; } +.tree-map .node.draft text.nl { fill: var(--accent); font-weight: 600; } +.tree-map .unsaved-dot { fill: var(--warn); stroke: var(--surface); stroke-width: 1; } +.tree-list .dot.planned { fill: var(--surface); stroke: var(--k-component); stroke-dasharray: 3 2; stroke-width: 2; } +.tree-list .dot.planned.training-policy { stroke: var(--k-training-policy); } +.tree-list .dot.planned.architecture { stroke: var(--k-architecture); } +.tree-list .dot.planned.refinement { stroke: var(--k-refinement); } +.tree-list .dot.planned.unset { stroke: var(--ink-3); } +.tree-list .dot.planned.sel { stroke: var(--accent); } +.tree-list .trow.draft .nm, .tree-list .trow.draft .ck { color: var(--accent); } +.chip.draft { color: var(--accent); font-weight: 500; } +.chip.draft::before { background: transparent; box-shadow: none; border: 1.5px dashed var(--accent); width: 6px; height: 6px; } +/* The unsaved mark, and "not kept yet" where something typed is not kept. */ +.umark { font-size: 11.5px; color: var(--warn); font-weight: 500; white-space: nowrap; } +.umark:empty { display: none; } +.umark.typed { color: var(--accent); } +.tree-list .trow .nm .umark, .row .title .umark { margin-left: 8px; } +/* The editor. */ +.editor .seg { align-self: flex-start; } +.seg { display: inline-flex; border: 1px solid var(--line-strong); border-radius: var(--radius); overflow: hidden; } +.seg button { border: 0; background: var(--surface); padding: 4px 12px; font: inherit; font-size: 13px; color: var(--ink-2); cursor: pointer; } +.seg button + button { border-left: 1px solid var(--line-strong); } +.seg button[aria-pressed="true"] { background: var(--accent-wash); color: var(--ink); } +.code-field { display: grid; gap: 4px; min-width: 0; } +textarea.code { width: 100%; min-width: 0; font: 12px/1.5 var(--mono); white-space: pre; overflow: auto; tab-size: 2; padding: 8px; } +.form input[type="number"] { width: 100%; min-width: 0; font: inherit; color: var(--ink); background: var(--surface); border: 1px solid var(--line-strong); border-radius: var(--radius); padding: 5px 8px; min-height: 30px; } +.form .two > * { min-width: 0; } +.form .radio label.chip-radio { padding: 3px 9px; } +.form .radio label.chip-radio .chip { color: var(--ink); } +.form .derived { display: flex; flex-wrap: wrap; gap: 6px; align-items: center; } +.form .derived-name { color: var(--ink); font-size: 13px; flex: 1 1 140px; min-width: 0; overflow-wrap: anywhere; } +.form .settings { display: grid; gap: 8px; padding-top: 6px; border-top: 1px solid var(--line); } +.form .settings h3 { margin: 0; } +.form .settings .note { font-size: 12.5px; color: var(--ink-3); overflow-wrap: anywhere; } +.problems { display: grid; gap: 4px; padding: 8px 10px; border-radius: var(--radius); font-size: 13px; } +.problems ul { margin: 0; padding-left: 18px; } +.problems.warnings { border: 1px solid var(--warn); background: var(--warn-wash); } +.picking { display: grid; gap: 6px; justify-items: start; padding: 8px 10px; border: 1px dashed var(--accent); border-radius: var(--radius); background: var(--accent-wash); } +.picking p:first-child { font-weight: 500; color: var(--ink); } +.new-steps { display: grid; gap: 10px; padding-top: 10px; border-top: 1px solid var(--line); } +.new-steps h3 { margin: 0; } +.steps-box:empty { display: none; } +/* The Overview's list of every definition, and Train's Planned. */ +.ov-defs { margin: 28px 0; } +.ov-defs h3.ov-kind { font-size: 13px; color: var(--ink-2); margin: 14px 0 4px; } +.row.def { grid-template-columns: minmax(120px, 0.7fr) minmax(0, 1.3fr) 150px 90px; } +.row.def .name { color: var(--ink-2); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; } +.row.def > .title { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; } +div.row.def { cursor: default; } +@media (max-width: 900px) { .row.def { grid-template-columns: minmax(0, 1fr) minmax(0, 1fr) 110px; } .row.def .umark { display: none; } } diff --git a/static/project-workspace/editor.js b/static/project-workspace/editor.js new file mode 100644 index 00000000..3283435b --- /dev/null +++ b/static/project-workspace/editor.js @@ -0,0 +1,488 @@ +'use strict'; +// Editing and branching (spec-w3.md section 3.2, slice T22): the editor in the +// drawer, with two views of one text (Text for every kind, Form for a +// recipe); Keep, Discard edit, Remove and Save through actions.js; Pick on the +// map; Branch from here and the drafts it makes; the steps of a new model; the +// Overview's list of every definition. What is typed is kept in page memory +// per definition until it is kept or discarded, so leaving the drawer or a +// re-render loses nothing; a draft is kept in sessionStorage under the +// project's id, so it survives a reload of the tab. The form changes only the +// fields touched and writes the JSON back with the indentation the text had. +// Nothing here writes to disk: Keep stores an unsaved edit, Save writes them. +// Text goes in through text nodes only. +window.LabEditor = (() => { + const P = window.TuldokProject, A = window.LabActions, S = window.LabScreens, Tree = window.LabTree, h = window.LabCharts.h; + const { sect, modelState } = S.parts; + const isObject = v => !!v && typeof v === 'object' && !Array.isArray(v); + const button = (cls, text, key, onClick) => { const b = h('button', cls, text); b.type = 'button'; if (key) b.dataset.key = key; if (onClick) b.addEventListener('click', onClick); return b; }; + const KIND_ORDER = ['recipe', 'dataset', 'model', 'step', 'benchmark', 'chart', 'environment']; + const KIND_TITLE = { recipe: 'Recipes', dataset: 'Datasets', model: 'Models', step: 'Steps', benchmark: 'Benchmarks', chart: 'Charts', environment: 'Environments' }; + + // ---- Page memory ------------------------------------------------------------ + const buffers = new Map(); // reference -> { text, base }: typed and not kept yet + const views = new Map(); // reference -> 'form' | 'text' + let drafts = []; // { reference, parent, text, inlined, problems }: branches not kept yet + let followed = []; // references branched in this tab and kept: their drawer keeps the steps + let project = null, picking = null, pickNote = '', current = null; + + const storeKey = () => 'tuldok-drafts:' + project; + function persist() { if (!project) return; try { sessionStorage.setItem(storeKey(), JSON.stringify({ drafts, followed })); } catch (e) { /* kept for this page only */ } } + const validDraft = d => isObject(d) && typeof d.reference === 'string' && d.reference.startsWith('recipes/') && typeof d.parent === 'string' && typeof d.text === 'string'; + /** app.js, once the summary is read: the drafts of this project kept in this tab. */ + function load(id) { + if (project === id) return; + project = id; + let saved = null; try { saved = JSON.parse(sessionStorage.getItem(storeKey()) || 'null'); } catch (e) { saved = null; } + drafts = saved && Array.isArray(saved.drafts) ? saved.drafts.filter(validDraft).map(d => ({ reference: d.reference, parent: d.parent, text: d.text, inlined: typeof d.inlined === 'string' ? d.inlined : null, problems: Array.isArray(d.problems) ? d.problems : [] })) : []; + followed = saved && Array.isArray(saved.followed) ? saved.followed.filter(x => typeof x === 'string') : []; + publish(); + } + /** What the map draws of each draft (adapter.js); a draft whose parent is gone, or whose reference is taken, is dropped. */ + function publish() { P.setDrafts(drafts.map(drawn), dropped); } + function dropped(gone) { + const refs = new Set(gone.map(d => d.reference)); + drafts = drafts.filter(d => !refs.has(d.reference)); persist(); P.setDrafts(drafts.map(drawn)); + } + function drawn(d) { + const doc = parse(d.text).doc || {}, str = v => typeof v === 'string' ? v : null; + return { reference: d.reference, parent: d.parent, title: str(doc.title) || d.reference.slice(8), short: isObject(doc.labels) ? str(doc.labels.short) : null, + description: str(doc.description), group: str(doc.group), change: str(doc.change) }; + } + const draftOf = ref => drafts.find(d => d.reference === ref) || null; + const isDraft = ref => A.may('edit') && !!draftOf(ref); + + // ---- One text --------------------------------------------------------------------- + function parse(text) { + try { const doc = JSON.parse(text); return isObject(doc) ? { doc } : { error: 'The text is JSON but not an object.' }; } + catch (e) { return { error: e.message }; } + } + /** The indentation of the text: that of its first indented line, else two spaces. */ + const indentOf = text => { const m = /\n([ \t]+)\S/.exec(text || ''); return m ? m[1] : ' '; }; + const textOf = (ref, def) => { const d = draftOf(ref); return buffers.has(ref) ? buffers.get(ref).text : d ? d.text : def ? def.text : ''; }; + /** Keeps typed text: a draft's own text, else a buffer until it is kept or discarded (none when it is the definition's text again). */ + function setText(ref, text, base) { + const d = draftOf(ref); + if (d) { d.text = text; persist(); return; } + const had = buffers.has(ref); + if (text === base) buffers.delete(ref); else buffers.set(ref, { text, base }); + if (had !== buffers.has(ref)) { decorate(document); if (current && current.ref === ref && current.controls) current.controls(); } + } + /** A change made in the form: the text parsed, fn(document) applied, written back with the text's indentation. */ + function edit(ref, base, fn) { + const text = textOf(ref, base === null ? null : { text: base }), p = parse(text); + if (!p.doc) return; + fn(p.doc); + setText(ref, JSON.stringify(p.doc, null, indentOf(text)) + '\n', base); + } + + /** The marks after names (tree.js's mark): "not kept yet" where something typed is not kept, else "unsaved" or "removed". */ + function decorate(root) { + for (const s of (root || document).querySelectorAll('.umark[data-ref]')) { + const typed = buffers.has(s.dataset.ref) || s.dataset.draft === '1'; + s.textContent = typed ? 'not kept yet' : s.dataset.removed === '1' ? 'removed' : s.dataset.unsaved === '1' ? 'unsaved' : ''; + s.classList.toggle('typed', typed); + } + } + + // ---- Selections ------------------------------------------------------------------- + const prefixes = ['edit:', 'branch:']; + /** The reference a selection is about: 'edit:' and 'branch:' are about . */ + function subject(sel) { for (const p of prefixes) if (sel && sel.startsWith(p)) return sel.slice(p.length); return sel; } + /** Whether a selection is this module's drawer: the editor, the branch form or a draft, for a session that may edit. */ + function owns(sel, data) { return !!sel && A.may('edit') && (prefixes.some(p => sel.startsWith(p)) || !!draftOf(sel)); } + function drawer(aside, sel, act, data, screen) { + if (sel.startsWith('branch:')) return branchForm(aside, sel, sel.slice(7), act, data); + return editor(aside, sel, subject(sel), act, data, screen); + } + /** Puts node in the drawer, giving back the focused control (by data-key), its caret and the scroll; else the heading takes the focus when the focus was in the drawer. */ + function swapInto(aside, node) { + const active = document.activeElement, inside = !!active && aside.contains(active), key = inside && active.dataset ? active.dataset.key : null; + let caret = null; try { caret = key && typeof active.selectionStart === 'number' ? [active.selectionStart, active.selectionEnd, active.scrollTop] : null; } catch (e) { caret = null; } + const scroller = aside.parentElement, top = scroller.scrollTop; + aside.textContent = ''; aside.appendChild(node); scroller.scrollTop = top; + const again = key && [...aside.querySelectorAll('[data-key]')].find(e => e.dataset.key === key); + if (again) { again.focus({ preventScroll: true }); if (caret && again.setSelectionRange) { again.setSelectionRange(caret[0], caret[1]); again.scrollTop = caret[2]; } } + else if (inside || !active || active === document.body) { const t = aside.querySelector('h2'); if (t && aside.closest('.drawer.open')) t.focus({ preventScroll: true }); } + } + + // ---- The editor --------------------------------------------------------------------- + function editor(aside, sel, ref, act, data, screen) { + const key = 'editor:' + sel; + if (aside._for === key) return true; + aside._for = key; + const draft = draftOf(ref); + if (!(aside._editing === ref && aside.querySelector('.editor'))) { aside.textContent = ''; aside.appendChild(h('p', 'note', 'Reading…')); } + aside._editing = ref; + Promise.all([draft ? null : P.read('definition', { reference: ref }), P.read('definitions')]).then(([def, all]) => { + if (aside._for !== key) return; + const here = { aside, key, ref, controls: null }; + current = here; + const rebuild = () => { if (aside._for === key) { aside._for = null; editor(aside, sel, ref, act, data, screen); } }; + here.rebuild = rebuild; + swapInto(aside, editorView(here, ref, draft ? null : def, all.definitions, act, data, screen, sel)); + }, error => { if (aside._for !== key) return; aside._editing = null; aside.textContent = ''; aside.appendChild(A.refusal(error)); }); + return true; + } + function editorView(here, ref, def, all, act, data, screen, sel) { + const draft = draftOf(ref), kind = def ? def.kind : 'recipe', base = def ? def.text : null, text = textOf(ref, def), p = parse(text); + const doc = p.doc || (def && def.document) || {}; + const view = kind === 'recipe' && p.doc ? (views.get(ref) || 'form') : 'text'; + const ins = h('div', 'inspector editor'); ins.dataset.ref = ref; + // The header: what it is, its state, and its marks. + const hd = h('header'), parent = draft ? data.map.byId.get(draft.parent) : null; + hd.appendChild(h('span', 'kicker', draft ? 'draft · from ' + (parent ? Tree.nameOf(parent) : draft.parent) : (kind === 'recipe' ? 'editing · ' : 'editing ' + kind + ' · ') + ref)); + const t = h('h2', null, (typeof doc.title === 'string' && doc.title) || (def && def.title) || ref); t.tabIndex = -1; hd.appendChild(t); + const meta = h('div', 'ins-meta'); + if (draft) meta.appendChild(h('span', 'chip ' + (P.KINDS.some(k => k.id === doc.change) ? doc.change : P.UNSET) + ' draft', 'draft')); + else meta.appendChild(modelState(def.state)); + const mark = Tree.mark({ id: ref, unsaved: !!(def && def.unsaved), draft: !!draft }); if (def && def.removed) mark.dataset.removed = '1'; meta.appendChild(mark); + hd.appendChild(meta); ins.appendChild(hd); + // Back to what it was opened from. + const back = h('div', 'actions'); + if (draft) { if (parent) back.appendChild(button('btn sm ghost', 'From ' + Tree.refName(parent), 'editor:' + ref + ':parent', () => act.go('map', parent.id))); } + else if (screen === 'map' && data.map.byId.has(ref)) back.appendChild(button('btn sm ghost', '← The model', 'editor:' + ref + ':back', () => act.select(ref))); + else if (screen === 'data') back.appendChild(button('btn sm ghost', '← The dataset', 'editor:' + ref + ':back', () => act.select(ref))); + if (back.children.length) ins.appendChild(back); + if (picking && picking.reference === ref) ins.appendChild(pickingBanner(act)); + // The two views of the one text. + const seg = h('div', 'seg'); seg.setAttribute('role', 'group'); seg.setAttribute('aria-label', 'View'); + if (kind === 'recipe' && p.doc) for (const [v, label] of [['form', 'Form'], ['text', 'Text']]) { + const b = button(null, label, 'editor:' + ref + ':view-' + v, () => { views.set(ref, v); here.rebuild(); }); b.setAttribute('aria-pressed', String(view === v)); seg.appendChild(b); + } + if (seg.children.length) ins.appendChild(seg); + if (kind === 'recipe' && !p.doc) ins.appendChild(h('p', 'failure', 'The text is not valid JSON, so the form cannot show it: ' + p.error + ' Correct it in the text below.')); + // A draft opens with what keeping it would find, and with where its settings came from. + if (draft && draft.problems.length) ins.appendChild(problemList(draft.problems, 'When it was drafted, keeping it would have found:')); + if (draft && draft.inlined) ins.appendChild(h('p', 'note', 'The settings were copied from ' + draft.inlined + ' so that they can be changed here; that file is not changed.')); + ins.appendChild(view === 'form' ? recipeForm(ref, base, p.doc, all, data, act, sel) : textView(ref, base, text)); + if (draft) ins.appendChild(stepsBlock(ref, { kept: false }, act, data, null)); + else { + // Keep, Discard edit, Remove and Save; drawn again when typing starts or ends (Discard edit then applies). + const box = h('div'); + const controls = () => { + const typed = buffers.has(ref), edited = def.unsaved || def.removed; + box.textContent = ''; + box.appendChild(A.group('edit:' + ref, [ + { id: 'keep', label: 'Keep', cls: 'btn primary', who: 'edit', op: 'set_definition', busy: 'Keeping…', args: () => ({ reference: ref, text: textOf(ref, def) }), done: () => buffers.delete(ref) }, + { id: 'discard', label: 'Discard edit', cls: 'btn', who: 'edit', busy: 'Discarding…', hidden: !typed && !edited, + confirm: (typed && edited ? 'Drop what was typed here, and put back' : typed ? 'Drop what was typed here; the definition stays as it is kept.' : 'Put back') + (edited ? ' the file in the project folder in place of the unsaved ' + (def.removed ? 'removal' : 'edit') + '; a definition the folder has no file for is dropped.' : ''), + // Whether there is an unsaved edit to put back is read afresh: this drawer may have been drawn before a Keep. + run: async () => { + buffers.delete(ref); decorate(document); + const now = await P.call('definition', { reference: ref }); + return now.unsaved || now.removed ? P.call('revert_definition', { reference: ref }) : { reference: ref, dropped: false }; + }, + done: r => { if (r && r.dropped) act.select(null); } }, + { id: 'remove', label: 'Remove', cls: 'btn ghost', who: 'edit', op: 'remove_definition', busy: 'Removing…', hidden: !!def.removed, args: () => ({ reference: ref }), + confirm: 'Remove ' + ref + ': it is marked removed and its file is deleted when the project is saved; one never saved is dropped now.', + done: () => { buffers.delete(ref); act.select(null); } }, + { id: 'save', label: 'Save', cls: 'btn', who: 'edit', op: 'save', busy: 'Saving…', hidden: !edited } + ])); + box.appendChild(h('p', 'note', 'Keep checks the text and keeps it in Tuldok as an unsaved edit; Save writes every unsaved edit to the project folder.')); + }; + here.controls = controls; controls(); ins.appendChild(box); + } + decorate(ins); + return ins; + } + function textView(ref, base, text) { + const l = h('label', 'code-field'); + l.appendChild(h('span', 'small muted', 'The definition, as JSON')); + const area = h('textarea', 'code'); area.value = text; area.spellcheck = false; area.autocomplete = 'off'; area.wrap = 'off'; + area.rows = Math.min(28, Math.max(10, text.split('\n').length + 1)); area.dataset.key = 'editor:' + ref + ':text'; + area.addEventListener('input', () => setText(ref, area.value, base)); + l.appendChild(area); + return l; + } + function problemList(problems, lead) { + const errors = problems.some(p => p.severity !== 'warning'); + const box = h('div', errors ? 'failure refusal problems' : 'problems warnings'); + box.appendChild(h('p', null, lead)); + const ul = h('ul'); + for (const p of problems) { const where = [p.path, p.pointer].filter(x => x && x !== '/').join(' '); ul.appendChild(h('li', null, (p.severity === 'warning' ? 'Warning: ' : '') + (where ? where + ': ' : '') + (p.message || ''))); } + box.appendChild(ul); + box.appendChild(h('p', 'small', 'Keep checks the text again and lists what is still wrong.')); + return box; + } + + // ---- The form of a recipe --------------------------------------------------------------- + function recipeForm(ref, base, doc, all, data, act, sel) { + const f = h('div', 'form editor-form'), k = name => 'editor:' + ref + ':' + name, upd = fn => edit(ref, base, fn); + const field = (label, control, hint) => { const l = h('label'); l.appendChild(document.createTextNode(label)); l.appendChild(control); if (hint) l.appendChild(h('span', 'hint', hint)); return l; }; + const input = (type, value, name, max) => { const i = h('input'); i.type = type; if (value !== undefined && value !== null) i.value = String(value); if (max) i.maxLength = max; i.dataset.key = k(name); i.autocomplete = 'off'; if (type === 'text') i.spellcheck = false; return i; }; + const choose = (options, value, name, label) => { const s = h('select'); s.dataset.key = k(name); s.setAttribute('aria-label', label); for (const [v, t] of options) { const o = h('option', null, t); o.value = v; o.selected = v === value; s.appendChild(o); } return s; }; + const asNumber = text => { const t = text.trim(); if (!t) return null; const n = Number(t); return Number.isFinite(n) ? n : undefined; }; + // A draft's node on the map follows its title, group and kind when such a field is left. + const isDraftRef = !!draftOf(ref), redraw = () => { if (isDraftRef) { publish(); act.redraw(); } }; + + const title = input('text', doc.title, 'title', 200); title.required = true; + title.addEventListener('input', () => upd(d => { d.title = title.value; })); title.addEventListener('change', redraw); + f.appendChild(field('Title', title)); + const two = h('div', 'two'); + const short = input('text', isObject(doc.labels) && typeof doc.labels.short === 'string' ? doc.labels.short : '', 'short', 16); + short.addEventListener('input', () => upd(d => { + if (short.value) { if (!isObject(d.labels)) d.labels = {}; d.labels.short = short.value; } + else if (isObject(d.labels)) { delete d.labels.short; if (!Object.keys(d.labels).length) delete d.labels; } + })); + short.addEventListener('change', redraw); + two.appendChild(field('Short label', short, 'at most 16 characters')); + const groups = (data.map.groups || []).map(g => { const up = []; let at = g; const byId = new Map(data.map.groups.map(x => [x.id, x])); while (at.parent && byId.has(at.parent) && up.length < 8) { at = byId.get(at.parent); up.unshift(at.title); } return [g.id, up.concat([g.title]).join(' / ')]; }); + const groupValue = typeof doc.group === 'string' ? doc.group : ''; + if (groupValue && !groups.some(g => g[0] === groupValue)) groups.push([groupValue, groupValue + ' (not a group of the project)']); + const grp = choose([['', 'None']].concat(groups), groupValue, 'group', 'Group'); + grp.addEventListener('change', () => { upd(d => { if (grp.value) d.group = grp.value; else delete d.group; }); redraw(); }); + two.appendChild(field('Group', grp)); + f.appendChild(two); + // Kind of change: the four kinds, or not set. + const kinds = h('div', 'radio'); kinds.setAttribute('role', 'radiogroup'); kinds.setAttribute('aria-label', 'Kind of change'); + const changeValue = P.KINDS.some(x => x.id === doc.change) ? doc.change : ''; + for (const [v, label] of P.KINDS.map(x => [x.id, x.label]).concat([['', 'Not set']])) { + const l = h('label', 'chip-radio'); const r = h('input'); r.type = 'radio'; r.name = 'change-' + ref; r.value = v; r.checked = v === changeValue; r.dataset.key = k('change-' + (v || 'unset')); + r.addEventListener('change', () => { if (!r.checked) return; upd(d => { if (v) d.change = v; else delete d.change; }); redraw(); }); + l.appendChild(r); l.appendChild(h('span', 'chip ' + (v || P.UNSET), label)); kinds.appendChild(l); + } + f.appendChild(field('Kind of change', kinds)); + // Derived from: the parent's name, Pick on the map, Clear. + const parentRef = typeof doc.derived_from === 'string' ? doc.derived_from : null, pm = parentRef && data.map.byId.get(parentRef); + const der = h('div', 'derived'); + der.appendChild(h('span', 'derived-name' + (parentRef ? '' : ' faint'), parentRef ? (pm ? Tree.nameOf(pm) : parentRef) : 'none')); + der.appendChild(button('btn sm', 'Pick on the map', k('pick'), () => startPicking(ref, base, sel, act))); + if (parentRef) der.appendChild(button('btn sm ghost', 'Clear', k('clear'), () => { upd(d => { delete d.derived_from; }); if (current && current.rebuild) current.rebuild(); })); + f.appendChild(field('Derived from', der)); + const desc = h('textarea'); desc.rows = 3; desc.maxLength = 4000; desc.value = typeof doc.description === 'string' ? doc.description : ''; desc.dataset.key = k('description'); + desc.addEventListener('input', () => upd(d => { if (desc.value) d.description = desc.value; else delete d.description; })); + f.appendChild(field('What this model changes', desc, 'at most 4,000 characters')); + if (!isObject(doc.run)) { f.appendChild(h('p', 'note', 'This recipe has no run: it is earlier work, or its run is to be written in the text view.')); return f; } + const run = doc.run, defs = all.filter(d => !d.removed), env = typeof run.environment === 'string' ? run.environment : ''; + const envs = defs.filter(d => d.kind === 'environment').map(d => [d.reference, d.title + ' · ' + d.reference]); + if (env && !envs.some(e => e[0] === env)) envs.push([env, env + ' (not an environment of the project)']); + const es = choose((env ? [] : [['', 'None']]).concat(envs), env, 'environment', 'Environment'); + es.addEventListener('change', () => upd(d => { if (!isObject(d.run)) return; if (es.value) d.run.environment = es.value; else delete d.run.environment; })); + f.appendChild(field('Environment', es)); + // Each input from a dataset: another dataset, keeping a named output. + const sets = defs.filter(d => d.kind === 'dataset').map(d => [d.reference, d.title + ' · ' + d.reference]); + for (const [name, v] of Object.entries(isObject(run.inputs) ? run.inputs : {})) { + const from = typeof v === 'string' ? v : isObject(v) && typeof v.from === 'string' ? v.from : null; + if (!from || !from.startsWith('datasets/')) continue; + const options = sets.some(s => s[0] === from) ? sets : sets.concat([[from, from]]); + const s = choose(options, from, 'input-' + name, 'Input ' + name); + s.addEventListener('change', () => upd(d => { const ins = isObject(d.run) && isObject(d.run.inputs) ? d.run.inputs : null; if (!ins) return; if (isObject(ins[name])) ins[name].from = s.value; else ins[name] = s.value; })); + f.appendChild(field('Input ' + name + (isObject(v) && v.output ? ' · its output ' + v.output : ''), s)); + } + // Settings: one field per top-level number, text or true/false; the rest are edited in the text. + const st = h('div', 'settings'); st.appendChild(h('h3', null, 'Settings')); + if (isObject(run.settings)) { + const grid = h('div', 'two'), rest = []; + for (const [name, v] of Object.entries(run.settings)) { + const set = fn => upd(d => { if (isObject(d.run) && isObject(d.run.settings)) fn(d.run.settings); }); + if (typeof v === 'number') { + const i = input('number', v, 'setting-' + name); i.step = 'any'; + i.addEventListener('input', () => { const n = asNumber(i.value); if (n === null || n === undefined) return; set(s => { s[name] = n; }); }); + grid.appendChild(field(name, i)); + } else if (typeof v === 'string') { + const i = input('text', v, 'setting-' + name); i.addEventListener('input', () => set(s => { s[name] = i.value; })); grid.appendChild(field(name, i)); + } else if (typeof v === 'boolean') { + const l = h('label', 'check'); const c = h('input'); c.type = 'checkbox'; c.checked = v; c.dataset.key = k('setting-' + name); + c.addEventListener('change', () => set(s => { s[name] = c.checked; })); l.appendChild(c); l.appendChild(document.createTextNode(' ' + name)); grid.appendChild(l); + } else rest.push(name); + } + if (grid.children.length) st.appendChild(grid); else st.appendChild(h('p', 'note', 'No setting is a number, a text or true/false.')); + if (rest.length) st.appendChild(h('p', 'note', 'Edited in the text: ' + rest.join(', ') + '.')); + } else if (typeof run.settings_file === 'string') { + st.appendChild(h('p', 'note mono', run.settings_file)); + st.appendChild(h('p', 'note', 'Its settings are in this file, which is changed in the code. A branch of this model carries its own copy of them, which its form can change.')); + } else st.appendChild(h('p', 'note', 'It has no settings.')); + f.appendChild(st); + // Resources. + const rs = h('div', 'settings'); rs.appendChild(h('h3', null, 'Resources')); + const res = isObject(run.resources) ? run.resources : {}; + const setRes = fn => upd(d => { if (!isObject(d.run)) return; if (!isObject(d.run.resources)) d.run.resources = {}; fn(d.run.resources); if (!Object.keys(d.run.resources).length) delete d.run.resources; }); + const gl = h('label', 'check'); const gpu = h('input'); gpu.type = 'checkbox'; gpu.checked = res.gpu === true; gpu.dataset.key = k('gpu'); + gpu.addEventListener('change', () => setRes(r => { if (gpu.checked) r.gpu = true; else if ('gpu' in r) r.gpu = false; })); + gl.appendChild(gpu); gl.appendChild(document.createTextNode(' Uses the GPU')); rs.appendChild(gl); + const rg = h('div', 'two'); + for (const [name, label] of [['wall_hours', 'Wall hours'], ['disk_gb', 'Disk (GB)']]) { + const i = input('number', typeof res[name] === 'number' ? res[name] : '', name); i.step = 'any'; i.min = '0'; + i.addEventListener('input', () => { const n = asNumber(i.value); if (n === undefined) return; setRes(r => { if (n === null) delete r[name]; else r[name] = n; }); }); + rg.appendChild(field(label, i, 'empty: not stated')); + } + rs.appendChild(rg); f.appendChild(rs); + return f; + } + + // ---- Pick on the map -------------------------------------------------------------------- + function startPicking(ref, base, sel, act) { + picking = { reference: ref, base, sel: draftOf(ref) ? ref : 'edit:' + ref }; pickNote = ''; + if (location.hash.startsWith('#map/')) act.reopen(); else act.go('map', picking.sel); + setTimeout(() => A.focusKey('editor:' + ref + ':stop-picking'), 0); + } + function pickingBanner(act) { + const box = h('div', 'picking'); box.setAttribute('role', 'status'); + box.appendChild(h('p', null, 'Press a model on the map to make it the parent · Escape to stop')); + if (pickNote) box.appendChild(h('p', 'small warnline', pickNote)); + box.appendChild(button('btn sm', 'Stop', 'editor:' + picking.reference + ':stop-picking', () => { stopPicking(act); })); + return box; + } + function stopPicking(act) { const was = picking; picking = null; pickNote = ''; act.reopen(); if (was) setTimeout(() => A.focusKey('editor:' + was.reference + ':pick'), 0); } + /** screens.js, when a model is pressed on the map: true when it was taken as the parent being picked. */ + function picked(id, act) { + if (!picking) return false; + if (id === picking.reference) { pickNote = 'A model is not derived from itself: press another one.'; act.reopen(); return true; } + if (draftOf(id)) { pickNote = 'A draft cannot be a parent before it is kept: press another one.'; act.reopen(); return true; } + const { reference, base, sel } = picking; picking = null; pickNote = ''; + edit(reference, base, d => { d.derived_from = id; }); + if (draftOf(reference)) publish(); + act.go('map', sel); act.reopen(); + setTimeout(() => A.focusKey('editor:' + reference + ':pick'), 0); + return true; + } + /** app.js, on Escape: leaves the picking state; true when it was in it. */ + function escape() { if (!picking) return false; const was = picking; picking = null; pickNote = ''; if (current) current.rebuild && current.rebuild(); setTimeout(() => A.focusKey('editor:' + was.reference + ':pick'), 0); return true; } + + // ---- Branch from here ------------------------------------------------------------------- + function branchForm(aside, sel, parentRef, act, data) { + if (aside._for === sel) return true; + aside._for = sel; aside._editing = null; + const m = data.map.byId.get(parentRef); + const ins = h('div', 'inspector branch'); + if (!m || m.draft) { ins.appendChild(h('p', 'empty', 'There is no model ' + parentRef + ' on the map to branch from.')); swapInto(aside, ins); return true; } + const key = 'branch:' + parentRef, s = A.slot(key); + if (s.text.change === undefined) s.text.change = m.kind === P.UNSET ? '' : m.kind; + const hd = h('header'); hd.appendChild(h('span', 'kicker', 'branch · from ' + Tree.nameOf(m))); + const t = h('h2', null, 'A new model from ' + Tree.refName(m)); t.tabIndex = -1; hd.appendChild(t); ins.appendChild(hd); + ins.appendChild(h('p', 'note', 'A new recipe written from this one, with its model, group, run and settings, derived from it. It is a draft in this page until it is kept.')); + const f = h('div', 'form'); + const field = (label, control, hint) => { const l = h('label'); l.appendChild(document.createTextNode(label)); l.appendChild(control); if (hint) l.appendChild(h('span', 'hint', hint)); return l; }; + const title = h('input'); title.type = 'text'; title.maxLength = 200; title.required = true; title.value = s.text.title || ''; title.dataset.key = key + ':field:title'; title.autocomplete = 'off'; + title.placeholder = 'What the new model is'; + title.addEventListener('input', () => { + s.text.title = title.value; + // A refusal for a missing title is over once one is typed. + if (s.refusal && title.value.trim() && /title/.test(s.refusal.error.message)) { s.refusal = null; const r = ins.querySelector('.act-group .refusal'); if (r) r.remove(); } + }); + title.addEventListener('keydown', e => { if (e.key === 'Enter') { e.preventDefault(); A.focusKey(key + ':create'); const b = ins.querySelector('[data-key="' + CSS.escape(key + ':create') + '"]'); if (b && !b.disabled) b.click(); } }); + f.appendChild(field('Title (required)', title, 'at most 200 characters')); + const kinds = h('div', 'radio'); kinds.setAttribute('role', 'radiogroup'); kinds.setAttribute('aria-label', 'Kind of change'); + for (const [v, label] of P.KINDS.map(x => [x.id, x.label]).concat([['', 'Not set']])) { + const l = h('label', 'chip-radio'); const r = h('input'); r.type = 'radio'; r.name = key + ':change'; r.value = v; r.checked = (s.text.change || '') === v; r.dataset.key = key + ':change-' + (v || 'unset'); + r.addEventListener('change', () => { if (r.checked) s.text.change = v; }); + l.appendChild(r); l.appendChild(h('span', 'chip ' + (v || P.UNSET), label)); kinds.appendChild(l); + } + f.appendChild(field('Kind of change', kinds, m.kind === P.UNSET ? 'its parent names none' : 'its parent\'s to begin with')); + const desc = h('textarea'); desc.rows = 3; desc.maxLength = 4000; desc.value = s.text.description || ''; desc.dataset.key = key + ':field:description'; + desc.addEventListener('input', () => { s.text.description = desc.value; }); + f.appendChild(field('What the model changes', desc, 'at most 4,000 characters')); + ins.appendChild(f); + ins.appendChild(A.group(key, [ + { id: 'create', label: 'Create', cls: 'btn primary', who: 'edit', busy: 'Creating…', local: true, + run: async st => { + const wanted = (st.text.title || '').trim(); + if (!wanted) throw Error('A branch needs a title.'); + const args = { recipe: parentRef, title: wanted.slice(0, 200) }; + if (st.text.change) args.change = st.text.change; + const about = (st.text.description || '').trim(); if (about) args.description = about.slice(0, 4000); + let answer = await P.call('draft_branch', args); + // A draft of this page holds the name already: the next free one. + const stem = answer.reference.slice('recipes/'.length).replace(/-\d+$/, '').slice(0, 110); + for (let n = 2; draftOf(answer.reference) && n < 200; n++) { + if (draftOf('recipes/' + stem + '-' + n)) continue; + try { answer = await P.call('draft_branch', Object.assign({}, args, { name: stem + '-' + n })); } catch (error) { if (error.code !== 'invalid') throw error; } + } + if (draftOf(answer.reference)) throw Error('No free name was found for the branch; give it another title.'); + return answer; + }, + done: answer => { + drafts.push({ reference: answer.reference, parent: parentRef, text: answer.text, inlined: answer.inlined || null, problems: answer.problems || [] }); + views.set(answer.reference, 'form'); persist(); publish(); + act.redraw().then(() => act.go('map', answer.reference)); + } }, + { id: 'back', label: 'Back', cls: 'btn ghost', onClick: () => act.go('map', parentRef) } + ])); + swapInto(aside, ins); + return true; + } + + // ---- The steps of a new model ---------------------------------------------------------------- + /** Whether a model's drawer shows the steps of a new model: a draft, one branched here, or one never built (unless it is earlier work). */ + const followsSteps = m => !!m && (m.draft || m.planned || followed.includes(m.id)); + /** + * The steps of a model of the map (screens.js): read its definition, runs and + * the build requests; earlier work gets planGroup() instead (as phase 2). + */ + function steps(box, m, act, data, planGroup) { + Promise.all([P.read('definition', { reference: m.id }), P.read('runs', { reference: m.id }), P.read('build_requests')]).then(([def, runs, requests]) => { + if (!box.isConnected) return; + box.textContent = ''; + if (isObject(def.document) && def.document.earlier_work && !followed.includes(m.id)) { if (['not-built', 'out-of-date', 'failed'].includes(m.state)) box.appendChild(planGroup()); return; } + const asked = requests.requests.filter(r => (r.targets || []).includes(m.id) && !['declined', 'cancelled', 'expired'].includes(r.state)); + const runList = runs.runs, started = runList.filter(r => r.started_at || ['running', 'succeeded', 'failed'].includes(r.state)); + box.appendChild(stepsBlock(m.id, { + kept: true, saved: !def.unsaved, requested: asked.length > 0 || runList.length > 0, running: started.length > 0, + runningNow: runList.some(r => r.state === 'running'), built: ['built', 'out-of-date'].includes(m.state), unsaved: def.unsaved, + request: asked[0] || null, run: runList[0] || null, state: m.state + }, act, data, planGroup)); + }, error => { if (box.isConnected) { box.textContent = ''; box.appendChild(A.refusal(error)); } }); + } + function stepsBlock(ref, f, act, data) { + const wrap = h('div', 'new-steps'); + wrap.appendChild(h('h3', null, 'From draft to built')); + const ol = h('ol', 'steps'); + const rows = [ + ['Kept', f.kept, f.kept ? 'Kept in Tuldok as a definition.' : 'Not kept yet: it is in this page only, and Keep checks it.'], + ['Saved', f.saved, f.saved ? 'Written to the project folder.' : f.kept ? 'An unsaved edit: Save writes it to the project folder.' : 'Not in the project folder.'], + ['Build requested', f.requested, f.request ? 'Asked for' + (f.request.state === 'awaiting-approval' ? ', awaiting approval.' : ' · ' + f.request.state + '.') : f.requested ? 'Asked for.' : 'Not asked for: plan its build first.'], + ['Running', f.running, f.runningNow ? 'Running now.' : f.running ? 'Its build has run' + (f.run ? ' · ' + f.run.state : '') + '.' : 'Not started.'], + ['Built', f.built, f.built ? 'Built: its product is on this machine.' : 'No product yet.'] + ]; + let next = false; + for (const [title, done, sub] of rows) { + const now = !done && !next; if (now) next = true; + const li = h('li', done ? 'done' : 'todo'); li.dataset.step = title; + li.appendChild(S.stateEl(done ? 'good' : now && (title === 'Running' && f.runningNow) ? 'pending' : 'neutral', '')); + const t = h('span'); t.appendChild(h('span', 'title', title)); t.appendChild(h('span', 'sub', sub)); li.appendChild(t); ol.appendChild(li); + } + wrap.appendChild(ol); + // One primary button, the next step; and Discard. + const items = []; + if (!f.kept) { + items.push({ id: 'keep', label: 'Keep', cls: 'btn primary', who: 'edit', op: 'set_definition', busy: 'Keeping…', args: () => ({ reference: ref, text: textOf(ref, null) }), + done: () => { drafts = drafts.filter(d => d.reference !== ref); if (!followed.includes(ref)) followed.push(ref); persist(); publish(); } }); + items.push({ id: 'discard', label: 'Discard', cls: 'btn ghost', who: 'edit', local: true, confirm: 'Drop this draft; nothing of it was kept.', run: async () => true, + done: () => { const d = draftOf(ref); drafts = drafts.filter(x => x.reference !== ref); persist(); publish(); act.redraw().then(() => act.go('map', d ? d.parent : undefined)); } }); + } else { + if (!f.saved) items.push({ id: 'save', label: 'Save', cls: 'btn primary', who: 'edit', op: 'save', busy: 'Saving…' }); + else if (!f.requested) items.push({ id: 'plan', label: 'Plan build', cls: 'btn primary', who: 'request', onClick: () => act.select('plan:' + ref) }); + else items.push({ id: 'train', label: 'Open in Train', cls: 'btn primary', onClick: () => act.go('train', f.request && !f.run ? 'request:' + f.request.id : f.run ? 'run:' + f.run.id : undefined) }); + if (f.unsaved) items.push({ id: 'discard', label: 'Discard', cls: 'btn ghost', who: 'edit', op: 'revert_definition', busy: 'Discarding…', args: () => ({ reference: ref }), + confirm: 'Put back the file in the project folder in place of the unsaved edit; a model never saved is dropped.', done: r => { if (r && r.dropped) act.select(null); } }); + } + wrap.appendChild(A.group(f.kept ? 'model:' + ref : 'draft:' + ref, items)); + return wrap; + } + + // ---- The Overview's list of every definition ---------------------------------------------------- + function definitionList(box, defs, sel, act) { + const can = A.may('edit'); + box.appendChild(sect('Every definition', defs.length + (can ? ' · each opens the editor' : ''))); + if (!defs.length) { box.appendChild(h('p', 'empty', 'The project has no definitions.')); return; } + const kinds = KIND_ORDER.concat([...new Set(defs.map(d => d.kind))].filter(k => !KIND_ORDER.includes(k))); + for (const kind of kinds) { + const mine = defs.filter(d => d.kind === kind); if (!mine.length) continue; + box.appendChild(h('h3', 'ov-kind', (KIND_TITLE[kind] || kind) + ' · ' + mine.length)); + const ul = h('ul', 'rows defs'); + for (const d of mine) { + const li = h('li'), row = can ? button('row def', null, 'open-edit:' + d.reference, () => act.select(sel === 'edit:' + d.reference ? null : 'edit:' + d.reference)) : h('div', 'row def'); + if (can) row.setAttribute('aria-pressed', String(sel === 'edit:' + d.reference)); + row.dataset.ref = d.reference; + row.appendChild(h('span', 'mono name', d.reference.slice(d.reference.indexOf('/') + 1))); + row.appendChild(h('span', 'title', d.title)); + row.appendChild(modelState(d.state)); + const mark = Tree.mark({ id: d.reference, unsaved: d.unsaved }); if (d.removed) mark.dataset.removed = '1'; row.appendChild(mark); + li.appendChild(row); ul.appendChild(li); + } + box.appendChild(ul); + } + } + + return { load, subject, owns, drawer, isDraft, picked, escape, decorate, followsSteps, steps, definitionList }; +})(); diff --git a/static/project-workspace/screens.js b/static/project-workspace/screens.js index 9f485b5a..35dbbebb 100644 --- a/static/project-workspace/screens.js +++ b/static/project-workspace/screens.js @@ -4,6 +4,8 @@ // has something to show there, and returns whether the drawer is open. It // reads the project only through window.TuldokProject. Rule: the chrome holds // no project words; names, groups, metrics and text come from the project. +// The editor, the branch form, a draft's drawer, the steps of a new model and +// the Overview's list of every definition are editor.js's (window.LabEditor). window.LabScreens = (() => { const P = window.TuldokProject, Tree = window.LabTree, C = window.LabCharts, h = C.h; const svgNS = 'http://www.w3.org/2000/svg'; @@ -44,9 +46,10 @@ window.LabScreens = (() => { let graph = null, graphOf = null; function graphFor(shaped) { if (graphOf !== shaped) { graph = Tree.build(shaped); graphOf = shaped; } return graph; } function map(main, aside, state, act, data) { - // A selection 'plan:' is the plan view in the drawer, with its first target selected on the map. - const shaped = data.map, g = graphFor(shaped), raw = state.sel.map || '', planSel = raw.startsWith('plan:') ? raw : null; - const focus = planSel ? planSel.slice(5).split(',')[0] : raw, sel = focus && g.byId.has(focus) ? focus : null; + // A selection 'plan:' is the plan view in the drawer, with its first target selected on the map; + // 'edit:' and 'branch:' are the editor and the branch form (editor.js), with that model selected. + const shaped = data.map, g = graphFor(shaped), raw = state.sel.map || '', planSel = raw.startsWith('plan:') ? raw : null, E = window.LabEditor; + const focus = planSel ? planSel.slice(5).split(',')[0] : E ? E.subject(raw) : raw, sel = focus && g.byId.has(focus) ? focus : null; const kinds = P.KINDS.map(k => k.id).concat(g.nodes.some(m => m.kind === P.UNSET) ? [P.UNSET] : []); const withValue = g.nodes.filter(m => m.value != null).length; const buildBar = () => { @@ -63,7 +66,8 @@ window.LabScreens = (() => { if (!g.nodes.length) { main.textContent = ''; main._tree = null; main.appendChild(h('p', 'empty', 'This project has no recipes, so there are no models to map.')); aside.textContent = ''; return false; } const sig = JSON.stringify([state.kinds ? [...state.kinds] : null, state.query || '', state.zoom || 1, !!state.track]); const prev = main._tree; - const common = { onSelect: id => act.select(id), kinds: state.kinds, query: state.query }; + // While a parent is being picked (editor.js), the next model pressed is the parent instead. + const common = { onSelect: id => { if (!(E && E.picked(id, act))) act.select(id); }, kinds: state.kinds, query: state.query }; if (prev && prev.sig === sig && prev.shaped === shaped && main.contains(prev.bar)) { if (sel && sel !== prev.sel) { prev.map.scrollTo(sel, true); prev.list.scrollTo(sel, true); } prev.map.select(sel); prev.list.select(sel); prev.sel = sel; @@ -78,7 +82,9 @@ window.LabScreens = (() => { if (focused !== null) { const q = bar.querySelector('input[type="search"]'); q.focus(); q.setSelectionRange(focused, focused); } main._tree = inst; } + if (E) E.decorate(main); if (planSel) { window.LabActions.planView(aside, planSel, act.go, sel ? () => act.select(sel) : null); return true; } + if (E && E.owns(raw, data)) { E.drawer(aside, raw, act, data, 'map'); return true; } if (sel) { inspectorModel(aside, sel, act, data); return true; } aside.textContent = ''; aside._for = null; return false; } @@ -86,18 +92,30 @@ window.LabScreens = (() => { // ---- Drawer: one model --------------------------------------------------- const TO_BUILD = ['not-built', 'out-of-date', 'failed']; function inspectorModel(aside, id, act, data) { + const E = window.LabEditor, A = window.LabActions; + if (E && E.isDraft(id)) return E.drawer(aside, id, act, data, 'map'); // a draft's drawer is the editor if (aside._for === id) return; aside._for = id; aside.textContent = ''; const g = graphFor(data.map), m = g.byId.get(id); const ins = h('div', 'inspector'); const hd = h('header'); hd.appendChild(h('span', 'kicker', (m.short ? m.short + ' · ' : '') + (m.groupTitle || ''))); - hd.appendChild(h('h2', null, m.title)); + const t = h('h2', null, m.title); t.tabIndex = -1; hd.appendChild(t); const meta = h('div', 'ins-meta'); meta.appendChild(h('span', 'chip ' + m.kind, P.kindLabel(m.kind))); meta.appendChild(modelState(m.state)); - meta.appendChild(h('span', 'small faint', m.trainedAt ? 'trained ' + P.day(m.trainedAt) : 'no training date')); + meta.appendChild(h('span', 'small faint', m.trainedAt ? 'trained ' + P.day(m.trainedAt) : m.planned ? 'never built' : 'no training date')); + meta.appendChild(Tree.mark(m)); hd.appendChild(meta); ins.appendChild(hd); - // Plan build, for a model to build (spec-w3 section 3.1): the plan view, never a request from here. - if (TO_BUILD.includes(m.state)) ins.appendChild(window.LabActions.group('model:' + m.id, [{ id: 'plan', label: 'Plan build', cls: 'btn primary', who: 'request', onClick: () => act.select('plan:' + m.id) }])); + if (E) E.decorate(hd); + // Plan build, for a model to build (spec-w3 section 3.1): the plan view, never a request from here. A model + // never built that is not earlier work has the steps of a new model instead (editor.js), whose next step it is. + const planGroup = () => A.group('model:' + m.id, [{ id: 'plan', label: 'Plan build', cls: 'btn primary', who: 'request', onClick: () => act.select('plan:' + m.id) }]); + if (E && E.followsSteps(m)) { const box = h('div', 'steps-box'); box.appendChild(h('p', 'note', 'Reading…')); ins.appendChild(box); E.steps(box, m, act, data, planGroup); } + else if (TO_BUILD.includes(m.state)) ins.appendChild(planGroup()); + // Edit and Branch from here (spec-w3 section 3.2), for a session that may edit. + ins.appendChild(A.group('modelact:' + m.id, [ + { id: 'edit', label: 'Edit', cls: 'btn sm', who: 'edit', onClick: () => act.go('map', 'edit:' + m.id) }, + { id: 'branch', label: 'Branch from here', cls: 'btn sm', who: 'edit', onClick: () => act.go('map', 'branch:' + m.id) } + ], { inline: true })); // Lineage: what it was derived from, what derives from it, what it takes as input. const lin = h('div', 'actions'); const jump = (target, text) => { const b = h('button', 'btn sm ghost'); b.type = 'button'; b.appendChild(icon('branch')); b.appendChild(document.createTextNode(' ' + text)); b.addEventListener('click', () => act.select(target.id)); return b; }; @@ -166,8 +184,10 @@ window.LabScreens = (() => { // ---- Overview -------------------------------------------------------------- // Read once and built off the page (tabs.js's paint), so the refresh while a build runs keeps the place. function overview(main, aside, state, act, data) { - aside.textContent = ''; aside._for = null; - if (state.sel.overview === 'report') { main.textContent = ''; main._painted = null; return report(main, data); } + const E = window.LabEditor, sel = state.sel.overview || ''; + if (sel === 'report') { aside.textContent = ''; aside._for = null; main.textContent = ''; main._painted = null; return report(main, data); } + const editing = !!(E && E.owns(sel, data)); + if (editing) E.drawer(aside, sel, act, data, 'overview'); else { aside.textContent = ''; aside._for = null; } S.paint(main, () => Promise.all([P.read('definitions'), P.read('environments'), P.read('activity', { limit: 12 })].map(p => p.then(v => ({ v }), error => ({ error })))), (frag, [d, e, a]) => { const standing = data.standing; const top = h('section', 'ov-status'); @@ -187,6 +207,8 @@ window.LabScreens = (() => { const defs = h('section'); defs.appendChild(sect('Definitions', String(Object.values(s.kinds).reduce((x, y) => x + y, 0)))); cols.appendChild(defs); const envs = h('section'); envs.appendChild(sect('Environments', String(s.kinds.environment || 0))); cols.appendChild(envs); frag.appendChild(cols); + // Every definition by kind, each opening the editor (editor.js) for a session that may edit. + const every = h('section', 'ov-defs'); frag.appendChild(every); const act2 = h('section', 'ov-history'); act2.appendChild(sect('Latest activity')); frag.appendChild(act2); const fill = (b, got, build) => { if (got.error) failure(b, got.error); else build(b, got.v); }; fill(defs, d, (b, d) => { @@ -197,6 +219,7 @@ window.LabScreens = (() => { const tb = h('tbody'); for (const k of kinds) { const tr = h('tr'); tr.appendChild(h('td', null, k)); const mine = d.definitions.filter(x => x.kind === k); for (const st of states) { const n = mine.filter(x => x.state === st).length; tr.appendChild(h('td', 'n' + (n ? '' : ' faint'), n ? String(n) : '·')); } tr.appendChild(h('td', 'n', String(mine.length))); tb.appendChild(tr); } t.appendChild(tb); const wrap = h('div'); wrap.style.overflowX = 'auto'; wrap.appendChild(t); b.appendChild(wrap); }); + fill(every, d, (b, d) => { if (E) E.definitionList(b, d.definitions, sel, act); }); fill(envs, e, (b, e) => { if (!e.environments.length) { b.appendChild(h('p', 'empty', 'The project defines no environment.')); return; } const ul = h('ul', 'rows'); for (const env of e.environments) { const li = h('li'); const r = h('div', 'row ov-env'); const t = h('span'); t.appendChild(h('span', 'title', env.title)); t.appendChild(h('span', 'sub', ['Python ' + env.python, env.device, Object.keys(env.packages || {}).length + ' packages', env.checked_at ? 'checked ' + P.day(env.checked_at) : 'never checked'].filter(Boolean).join(' · '))); r.appendChild(t); r.appendChild(modelState(env.state)); li.appendChild(r); ul.appendChild(li); } b.appendChild(ul); @@ -206,8 +229,9 @@ window.LabScreens = (() => { const ul = h('ul', 'rows'); for (const it of a.items) { const li = h('li'); const r = h('div', 'row ov-act'); r.appendChild(h('span', 'sub num', time(it.at))); const t = h('span'); t.appendChild(h('span', 'title', it.operation + (it.target ? ' · ' + it.target : ''))); t.appendChild(h('span', 'sub', [(it.actor && (it.actor.label || it.actor.kind)) || '', it.detail].filter(Boolean).join(' · '))); r.appendChild(t); r.appendChild(stateEl(it.outcome === 'done' ? 'good' : 'serious', it.outcome)); li.appendChild(r); ul.appendChild(li); } b.appendChild(ul); if (a.total > a.items.length) b.appendChild(h('p', 'note', (a.total - a.items.length) + ' earlier entries are not shown.')); }); + if (E) E.decorate(frag); }); - return false; + return editing; } function report(main, data) { const bar = h('div', 'report-bar'); const back = h('a', 'btn sm ghost', '← Overview'); back.href = '#overview'; bar.appendChild(back); bar.appendChild(h('h2', null, 'Report')); main.appendChild(bar); diff --git a/static/project-workspace/tabs.js b/static/project-workspace/tabs.js index da3157b0..0fb218bb 100644 --- a/static/project-workspace/tabs.js +++ b/static/project-workspace/tabs.js @@ -8,7 +8,9 @@ // only read. Train draws the controls of spec-w3.md section 3.1 (actions.js): // Plan build, a build request's Approve, Decline and Cancel, a run's Cancel // run and Stop, an environment's Check again, Connect and Disconnect, and it -// shows a running run live. Rule: the chrome holds no project words; titles, +// shows a running run live; it lists first what is planned (the page's drafts +// and the models never built, spec-w3 section 3.2). Data's drawer has Edit; +// the editor itself is editor.js's. Rule: the chrome holds no project words; titles, // metrics and text come from the project. (() => { const S = window.LabScreens, P = window.TuldokProject, Tree = window.LabTree, C = window.LabCharts, h = C.h, A = window.LabActions; @@ -344,23 +346,32 @@ return { recipes: recipes.definitions, runs: runs.runs, requests: requests.requests, envs: envs.environments, progress }; }, (frag, { recipes, runs, requests, envs, progress }) => { const g = graphFor(data.map), deviceOf = new Map(envs.map(e => [e.reference, e.device])); - // Models not built yet. - const todo = recipes.filter(d => !d.removed && TO_BUILD.includes(d.state)); - const th = sect('To build', todo.length + ' of ' + plural(recipes.length, 'model')); th.appendChild(h('span', 'spacer')); + // Planned (spec-w3 section 3.2): the drafts of this page, then the models never built. + const E = window.LabEditor, drafts = g.nodes.filter(m => m.draft); + const never = recipes.filter(d => !d.removed && d.state === 'not-built' && (!g.byId.has(d.reference) || g.byId.get(d.reference).planned)); + const neverRefs = new Set(never.map(d => d.reference)); + frag.appendChild(sect('Planned', String(drafts.length + never.length))); + if (!drafts.length && !never.length) frag.appendChild(h('p', 'empty', 'Nothing is planned. Branch from a model on the map to plan a new one.')); + else { + const ul = h('ul', 'rows planned'); + for (const m of drafts) { + const li = h('li'), b = button('row todo'); b.dataset.key = 'open-' + m.id; b.dataset.draft = m.id; + b.appendChild(S.stateEl('neutral', 'not kept yet')); const t = h('span'); t.appendChild(h('span', 'title', m.title)); t.appendChild(h('span', 'sub', 'from ' + (g.byId.has(m.parent) ? Tree.nameOf(g.byId.get(m.parent)) : m.parent) + ' · on the map until it is kept')); b.appendChild(t); + b.appendChild(h('span', 'chip ' + m.kind + ' draft', 'draft')); + b.addEventListener('click', () => act.go('map', m.id)); li.appendChild(b); ul.appendChild(li); + } + for (const d of never) ul.appendChild(todoRow(d, g, sel, act)); + frag.appendChild(ul); + } + // Models to build again: out of date or failed. + const todo = recipes.filter(d => !d.removed && TO_BUILD.includes(d.state) && !neverRefs.has(d.reference)); + const th = sect('To build', todo.length + ' of ' + plural(recipes.length, 'model')); th.classList.add('gap'); th.appendChild(h('span', 'spacer')); th.appendChild(A.group('train:every', [{ id: 'plan', label: 'Plan everything buildable', cls: 'btn sm', who: 'request', onClick: () => act.select('plan:*') }], { inline: true })); frag.appendChild(th); - if (!todo.length) frag.appendChild(h('p', 'empty', 'Every model is built, or cannot be rebuilt from its definition.')); + if (!todo.length) frag.appendChild(h('p', 'empty', 'No model is out of date or failed.')); else { const ul = h('ul', 'rows'); - for (const d of todo) { - const m = g.byId.get(d.reference), li = h('li'), b = button('row todo'); b.setAttribute('aria-pressed', String(d.reference === sel)); b.dataset.key = 'open-' + d.reference; - b.appendChild(modelState(d.state)); const t = h('span'); t.appendChild(h('span', 'title', m ? Tree.nameOf(m) : d.title)); t.appendChild(h('span', 'sub', m ? m.groupTitle + (m.description ? ' · ' + m.description : '') : d.reference)); b.appendChild(t); - b.appendChild(m ? h('span', 'chip ' + m.kind, P.kindLabel(m.kind)) : h('span')); - b.addEventListener('click', () => act.select(d.reference === sel ? null : d.reference)); li.appendChild(b); - const plan = A.group('todo:' + d.reference, [{ id: 'plan', label: 'Plan build', cls: 'btn sm', who: 'request', onClick: () => act.select('plan:' + d.reference) }], { inline: true }); - if (!plan.hidden) { li.classList.add('with-act'); li.appendChild(plan); } - ul.appendChild(li); - } + for (const d of todo) ul.appendChild(todoRow(d, g, sel, act)); frag.appendChild(ul); } // Build requests. @@ -427,10 +438,22 @@ else if (sel.startsWith('request:')) requestDrawer(aside, sel, act, data); else if (sel.startsWith('plan:')) A.planView(aside, sel, act.go, () => { const one = sel.slice(5); act.select(data.map.byId.has(one) ? one : null); }); else if (sel.startsWith('env:')) envDrawer(aside, sel, act, data); + else if (window.LabEditor && window.LabEditor.owns(sel, data)) window.LabEditor.drawer(aside, sel, act, data, 'train'); else if (data.map.byId.has(sel)) S.inspectorModel(aside, sel, act, data); else { aside.textContent = ''; aside._for = sel; aside.appendChild(h('p', 'empty', 'There is no ' + sel + ' here.')); } return true; } + /** A row of a model to build, opening its drawer, with Plan build. */ + function todoRow(d, g, sel, act) { + const m = g.byId.get(d.reference), li = h('li'), b = button('row todo'); b.setAttribute('aria-pressed', String(d.reference === sel)); b.dataset.key = 'open-' + d.reference; + b.appendChild(modelState(d.state)); const t = h('span'); const title = h('span', 'title', m ? Tree.nameOf(m) : d.title); if (m) title.appendChild(Tree.mark(m)); t.appendChild(title); t.appendChild(h('span', 'sub', m ? m.groupTitle + (m.description ? ' · ' + m.description : '') : d.reference)); b.appendChild(t); + b.appendChild(m ? h('span', 'chip ' + m.kind, P.kindLabel(m.kind)) : h('span')); + b.addEventListener('click', () => act.select(d.reference === sel ? null : d.reference)); li.appendChild(b); + const plan = A.group('todo:' + d.reference, [{ id: 'plan', label: 'Plan build', cls: 'btn sm', who: 'request', onClick: () => act.select('plan:' + d.reference) }], { inline: true }); + if (!plan.hidden) { li.classList.add('with-act'); li.appendChild(plan); } + if (window.LabEditor) window.LabEditor.decorate(li); + return li; + } const tail = (text, lines) => { const all = text.replace(/\n$/, '').split('\n'); return (all.length > lines ? '…\n' : '') + all.slice(-lines).join('\n'); }; /** A definition's value in one line: a list of words as a command line, an object as key: value pairs. */ const brief = v => v == null ? '—' : typeof v !== 'object' ? String(v) : Array.isArray(v) ? (v.every(x => typeof x === 'string') ? v.join(' ') : v.map(brief).join(', ')) : Object.entries(v).map(([k, x]) => k + ': ' + (x && typeof x === 'object' && !Array.isArray(x) ? '{' + brief(x) + '}' : brief(x))).join(', '); @@ -551,7 +574,7 @@ // ---- Data ----------------------------------------------------------------------- function data_(main, aside, state, act, data) { - const sel = state.sel.data || null; + const E = window.LabEditor, raw = state.sel.data || null, sel = raw && E ? E.subject(raw) : raw; paint(main, () => Promise.all([P.read('definitions', { kind: 'dataset' }), P.read('products'), P.read('graph')]), (frag, [defs, products, graph]) => { const sets = defs.definitions.filter(d => !d.removed), byRef = new Map(); for (const p of products.products) { if (!byRef.has(p.reference)) byRef.set(p.reference, []); byRef.get(p.reference).push(p); } @@ -581,9 +604,13 @@ frag.appendChild(grid); }); if (!sel) return closeDrawer(aside); + if (E && E.owns(raw, data)) { E.drawer(aside, raw, act, data, 'data'); return true; } drawer(aside, sel, () => Promise.all([P.read('definition', { reference: sel }), P.read('products', { reference: sel })]), (ins, [d, p]) => { - const hd = h('header'); hd.appendChild(h('span', 'kicker', d.reference)); hd.appendChild(h('h2', null, d.title)); - const meta = h('div', 'ins-meta'); meta.appendChild(p.products.some(x => x.adopted) ? S.stateEl('good', 'adopted') : modelState(d.state)); if (d.unsaved) meta.appendChild(h('span', 'small faint', 'unsaved edit')); hd.appendChild(meta); ins.appendChild(hd); + const hd = h('header'); hd.appendChild(h('span', 'kicker', d.reference)); const t2 = h('h2', null, d.title); t2.tabIndex = -1; hd.appendChild(t2); + const meta = h('div', 'ins-meta'); meta.appendChild(p.products.some(x => x.adopted) ? S.stateEl('good', 'adopted') : modelState(d.state)); meta.appendChild(Tree.mark({ id: d.reference, unsaved: d.unsaved })); hd.appendChild(meta); ins.appendChild(hd); + // Edit (spec-w3 section 3.2): the editor, in the text view. + ins.appendChild(A.group('dataedit:' + d.reference, [{ id: 'edit', label: 'Edit', cls: 'btn sm', who: 'edit', onClick: () => act.select('edit:' + d.reference) }])); + if (E) E.decorate(hd); const doc = d.document || {}; ins.appendChild(block('Description', doc.description ? h('p', null, doc.description) : h('p', 'note', 'The definition has no description.'))); const su = setup(); const skip = new Set(['format', 'kind', 'title', 'description']); diff --git a/static/project-workspace/tree.js b/static/project-workspace/tree.js index 46f40479..a15444e8 100644 --- a/static/project-workspace/tree.js +++ b/static/project-workspace/tree.js @@ -12,7 +12,7 @@ window.LabTree = (() => { const P = window.TuldokProject, C = window.LabCharts, el = C.el, h = C.h; const reduced = () => window.matchMedia && window.matchMedia('(prefers-reduced-motion: reduce)').matches; const SHORT = 16; // characters of a short label shown on the map (spec-w1 section 1) - const shortOf = m => m.short ? m.short.slice(0, SHORT) : null; + const shortOf = m => m.draft ? 'new' : m.short ? m.short.slice(0, SHORT) : null; const nameOf = m => (m.short ? m.short + ' · ' : '') + m.title; const refName = m => m.short || (m.title.length > 24 ? m.title.slice(0, 23) + '…' : m.title); // A short run of highlights from the previous selection to the new one, so @@ -72,6 +72,8 @@ window.LabTree = (() => { const seqOut = new Set(edges.filter(e => e.kind === 'sequence').map(e => e.from)); return { nodes, byId, edges, sections, families, laneCount: laneLast.length, seqIn, seqOut, seqSpan, track: shaped.track, scale: shaped.trackScale }; } + /** The mark after a model's name: "unsaved" for an unsaved edit; editor.js writes "not kept yet" into it (data-ref). */ + function mark(m) { const s = h('span', 'umark', m.unsaved ? 'unsaved' : ''); s.dataset.ref = m.id; if (m.unsaved) s.dataset.unsaved = '1'; if (m.draft) s.dataset.draft = '1'; return s; } function related(graph, id) { const out = new Set(); for (const e of graph.edges) if (e.kind !== 'sequence' && (e.from === id || e.to === id)) out.add(e.from === id ? e.to : e.from); return out; } function comparisons(graph, id) { return graph.edges.filter(e => e.kind === 'comparison' && (e.from === id || e.to === id)).map(e => ({ other: e.from === id ? e.to : e.from, explanation: e.explanation, excerpt: e.excerpt })); } function matches(m, q) { @@ -107,7 +109,7 @@ window.LabTree = (() => { li.appendChild(head); ul.appendChild(li); for (const m of list) { shown++; - const row = h('li'); const b = h('button', 'trow'); b.type = 'button'; b.setAttribute('role', 'option'); b.setAttribute('aria-selected', 'false'); b.dataset.id = m.id; + const row = h('li'); const b = h('button', 'trow' + (m.planned ? ' planned' : '') + (m.draft ? ' draft' : '')); b.type = 'button'; b.setAttribute('role', 'option'); b.setAttribute('aria-selected', 'false'); b.dataset.id = m.id; const svg = el('svg', { width: gw, height: rowH, 'aria-hidden': 'true' }); const x0 = laneX(0), mid = rowH / 2; if (graph.seqSpan[m.t]) svg.appendChild(el('line', { x1: x0, y1: 0, x2: x0, y2: rowH, class: 'lane0' })); @@ -118,12 +120,13 @@ window.LabTree = (() => { svg.appendChild(el('line', { x1: x, y1: 0, x2: x, y2: isChild && m.t === f.end ? mid : rowH, class: k })); } for (const f of graph.families.filter(f => f.parent === m.id)) { const x = laneX(f.lane), k = 'lanek lk-' + graph.byId.get(f.children[0]).kind; svg.appendChild(el('path', { d: `M${laneX(m.lane)},${mid} C${laneX(m.lane)},${rowH} ${x},${mid} ${x},${rowH}`, class: k })); } - const dot = el('circle', { cx: laneX(m.lane), cy: mid, r: 5, class: 'dot ' + m.kind }); + const dot = el('circle', { cx: laneX(m.lane), cy: mid, r: 5, class: 'dot ' + m.kind + (m.planned ? ' planned' : '') }); svg.appendChild(dot); b.appendChild(svg); b.appendChild(h('span', 'ck', shortOf(m) || '—')); - b.appendChild(h('span', 'nm', m.title)); + // The name, with the mark of an unsaved edit (or, from editor.js, of typing not kept yet). + const nm = h('span', 'nm'); nm.appendChild(document.createTextNode(m.title)); nm.appendChild(mark(m)); b.appendChild(nm); b.appendChild(h('span', 'pu', m.description)); - b.appendChild(h('span', 'chip ' + m.kind, P.kindLabel(m.kind))); + b.appendChild(h('span', 'chip ' + m.kind + (m.draft ? ' draft' : ''), m.draft ? 'draft' : P.kindLabel(m.kind))); const bar = h('span', 'mbar' + (m.value == null ? ' none' : '')); if (m.value != null && graph.scale) { const fill = h('i'); fill.style.width = Math.round(graph.scale.good(m.value) * 100) + '%'; bar.appendChild(fill); } bar.title = graph.track ? P.trackName(graph.track) + ': ' + trackText(graph, m) : 'The project names no track'; @@ -206,7 +209,7 @@ window.LabTree = (() => { const showTip = (m, ev) => { const rows = [{ b: nameOf(m) }]; rows.push(graph.track ? { v: m.value == null ? '—' : C.fmtSci(m.value) + P.units(graph.track), l: P.trackName(graph.track) } : { l: 'The project names no track' }); - rows.push({ l: m.trainedAt ? 'trained ' + P.day(m.trainedAt) : 'no training date' }); + rows.push({ l: m.draft ? 'a draft, not kept yet' : m.trainedAt ? 'trained ' + P.day(m.trainedAt) : m.planned ? 'never built' : 'no training date' }); rows.push({ v: P.kindLabel(m.kind), l: m.parent ? 'from ' + refName(graph.byId.get(m.parent)) : '' }); const [px, py] = at(ev); tip.show(px, py, rows); }; @@ -219,11 +222,12 @@ window.LabTree = (() => { if (last === undefined || x(m) - w / 2 >= last + 14) { labelled.add(m.id); laneLabelEnd.set(m.lane, x(m) + w / 2); } } for (const m of graph.nodes) { - const g = el('g', { class: 'node ' + m.kind + (visible(m) ? '' : ' dim'), tabindex: 0, role: 'button', 'aria-label': nameOf(m), 'data-id': m.id }); + const g = el('g', { class: 'node ' + m.kind + (m.planned ? ' planned' : '') + (m.draft ? ' draft' : '') + (visible(m) ? '' : ' dim'), tabindex: 0, role: 'button', 'aria-label': nameOf(m) + (m.draft ? ', a draft' : m.planned ? ', never built' : '') + (m.unsaved ? ', unsaved' : ''), 'data-id': m.id }); g.appendChild(el('rect', { x: x(m) - 14, y: y(m) - 14, width: 28, height: 28, class: 'hitr' })); g.appendChild(el('circle', { cx: x(m), cy: y(m), r: 5.5 })); + if (m.unsaved) { const u = el('circle', { cx: x(m) + 7, cy: y(m) - 7, r: 2.5, class: 'unsaved-dot' }); u.appendChild(el('title', {}, 'unsaved')); g.appendChild(u); } const text = shortOf(m); - const lbl = text ? el('text', { x: x(m), y: y(m) + 18, class: 'nl' + (labelled.has(m.id) ? '' : ' off') }, text) : null; + const lbl = text ? el('text', { x: x(m), y: y(m) + 18, class: 'nl' + (labelled.has(m.id) || m.draft ? '' : ' off') }, text) : null; if (lbl) g.appendChild(lbl); g.addEventListener('click', () => onSelect(m.id)); g.addEventListener('keydown', ev => { if (ev.key === 'Enter' || ev.key === ' ') { ev.preventDefault(); onSelect(m.id); } }); @@ -250,7 +254,7 @@ window.LabTree = (() => { const m = graph.byId.get(mid), on = mid === id; n.g.classList.toggle('sel', on); n.g.querySelector('circle').setAttribute('r', on ? 7 : 5.5); const fam = !!sel && (m.parent === id || mid === sel.parent || (!!sel.parent && m.parent === sel.parent)); - if (n.lbl) n.lbl.classList.toggle('off', !(on || fam || labelled.has(mid))); + if (n.lbl) n.lbl.classList.toggle('off', !(on || fam || labelled.has(mid) || m.draft)); n.g.classList.toggle('kin', fam && !on); } for (const p of svg.querySelectorAll('.der')) p.classList.toggle('hot', !!sel && (p.dataset.family === id || p.dataset.family === sel.parent)); @@ -276,5 +280,5 @@ window.LabTree = (() => { }; api.select(selected); return api; } - return { build, renderList, renderMap, related, comparisons, matches, nameOf, refName }; + return { build, renderList, renderMap, related, comparisons, matches, nameOf, refName, mark }; })(); diff --git a/tests/acceptance_project_workspace.cjs b/tests/acceptance_project_workspace.cjs new file mode 100644 index 00000000..134ffa7e --- /dev/null +++ b/tests/acceptance_project_workspace.cjs @@ -0,0 +1,281 @@ +'use strict'; +// The acceptance run of docs/plans/definition-first-projects/spec-w3.md ("Done when"): the project workspace on a +// copy of examples/tiny-project with real interpreters and a GPU, driven in a headless browser. After Tuldok +// starts, everything is done on the page: the owner connects the two interpreters, plans and requests a build of +// everything and watches the training's progress, branches the trained model, changes a setting in the form, +// keeps, saves, plans and requests the branch and sees it built on the map without a reload, adds it to the +// benchmark in the text view, and approves from Needs you a build an agent asked for (noticed by the idle page). +// Only the agent's request and the read-backs that check each step are made beside the page. +// It trains two small networks (seconds each on a GPU) and WRITES INTO THE PROJECT FOLDER it is given: give it a +// copy of examples/tiny-project committed to a Git repository of its own, with its own id in tuldok.json, and +// set TULDOK_DATABASE_URL (a disposable cluster), TULDOK_PROJECT_HOME and TULDOK_SETTINGS (scratch places). +// node tests/acceptance_project_workspace.cjs [output directory] +const assert = require('node:assert/strict'), fs = require('node:fs'), os = require('node:os'), path = require('node:path'); +const { spawn } = require('node:child_process'), { once } = require('node:events'); +const root = path.resolve(__dirname, '..'), tests = __dirname; +const { authenticatedFixture } = require('./auth_helpers.cjs'), { waitForDebugger } = require('./browser_startup.cjs'), { cdpSession } = require('./browser_cdp_session.cjs'), { qaDirectory } = require('./qa_artifacts.cjs'); +assert.ok(process.argv.length >= 5, 'usage: node tests/acceptance_project_workspace.cjs [output directory]'); +const [folder, CPU, GPU] = process.argv.slice(2, 5).map(p => path.resolve(p)); +const out = process.argv[5] ? path.resolve(process.argv[5]) : qaDirectory(root, 'project-workspace-acceptance'); +assert.ok(process.env.TULDOK_DATABASE_URL && process.env.TULDOK_PROJECT_HOME && process.env.TULDOK_SETTINGS, 'Set TULDOK_DATABASE_URL to a disposable cluster and TULDOK_PROJECT_HOME and TULDOK_SETTINGS to scratch places.'); +assert.ok(fs.existsSync(path.join(folder, 'tuldok.json')), 'The first argument is a project folder (it holds tuldok.json).'); +const venv = path.join(root, '.venv', 'bin'); +if (fs.existsSync(path.join(venv, 'python'))) process.env.PATH = venv + path.delimiter + process.env.PATH; // auth_helpers runs python3 +const python = fs.existsSync(path.join(venv, 'python')) ? path.join(venv, 'python') : 'python3'; +const WIDTH = 1440, HEIGHT = 900; +const temporary = fs.mkdtempSync(path.join(os.tmpdir(), 'tuldok-accept-')); +fs.mkdirSync(out, { recursive: true }); +const children = [], errors = [], failures = [], log = []; +let server, serverErrors = '', origin, auth, socket, send, evaluate; +const pause = ms => new Promise(resolve => setTimeout(resolve, ms)); +async function until(fn, label, tries = 300, every = 100) { for (let i = 0; i < tries; i++) { const value = await fn(); if (value) return value; await pause(every); } throw Error('Timed out: ' + label); } +function done(text) { log.push(text); console.log('DONE ' + text); } +function launch(command, args, options) { const child = spawn(command, args, options); children.push(child); return child; } +async function stop(child) { if (!child || child.exitCode !== null || child.signalCode !== null) return; const exited = once(child, 'exit'); child.kill('SIGTERM'); await Promise.race([exited, pause(40000)]); if (child.exitCode === null && child.signalCode === null) child.kill('SIGKILL'); } +function findBrowser() { + const candidates = [process.env.BROWSER, '/usr/bin/chromium', '/usr/bin/chromium-browser', '/usr/bin/google-chrome']; + const cache = path.join(os.homedir(), '.cache', 'ms-playwright'); + if (fs.existsSync(cache)) for (const name of fs.readdirSync(cache).filter(n => n.startsWith('chromium_headless_shell-')).sort().reverse()) candidates.push(path.join(cache, name, 'chrome-headless-shell-linux64', 'chrome-headless-shell')); + const found = candidates.find(candidate => candidate && fs.existsSync(candidate)); assert.ok(found, 'No headless browser'); return found; +} +async function contract(name) { + const capabilities = await (await auth.fetch(origin + '/api/agent/capabilities')).json(); + const operation = capabilities.operations.find(item => item.id === 'project.' + name), c = operation.contracts[operation.contracts.length - 1]; + return 'project.' + name + '/' + c.version + '/' + c.sha256; +} +async function api(name, body = {}, bearer = null) { + const headers = { 'Content-Type': 'application/json', 'Tuldok-Operation-Contract': await contract(name) }; + const response = bearer ? await globalThis.fetch(origin + '/api/project/' + name, { method: 'POST', headers: { ...headers, Authorization: 'Bearer ' + bearer }, body: JSON.stringify(body) }) + : await auth.fetch(origin + '/api/project/' + name, { method: 'POST', headers, body: JSON.stringify(body) }); + const value = await response.json(); assert.equal(response.status, 200, name + ': ' + JSON.stringify(value)); return value; +} +async function credential(label, scopes) { + const response = await auth.fetch(origin + '/api/access/credentials', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ label, scopes, ttl_seconds: 3600 }) }); + const value = await response.json(); assert.equal(response.status, 201, JSON.stringify(value)); return value.token; +} +let shotNumber = 0; +async function shot(name) { + await evaluate('new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve)))'); + const file = path.join(out, String(++shotNumber).padStart(2, '0') + '-' + name + '.jpg'); + fs.writeFileSync(file, Buffer.from((await send('Page.captureScreenshot', { format: 'jpeg', quality: 88, captureBeyondViewport: false })).data, 'base64')); + return file; +} +async function theme(name) { await evaluate(`(() => { document.documentElement.setAttribute('data-theme', '${name}'); document.getElementById('theme').lastChild.textContent = ' ${name === 'dark' ? 'Dark' : 'Light'}'; })()`); } +async function settled(label) { + await until(() => evaluate(`(() => { const reading = e => [...e.querySelectorAll('.note')].some(n => n.textContent === 'Reading…'); return !reading(document.getElementById('main')) && !reading(document.getElementById('aside')) && !document.getElementById('main').hasAttribute('aria-busy') && !document.querySelector('.act-group [aria-busy]'); })()`), label, 1200); + await pause(200); +} +async function open(hash) { + await send('Page.navigate', { url: origin + '/?theme=light#' + hash }); + await until(() => evaluate(`document.readyState === 'complete' && !!document.getElementById('needs-btn') && !document.getElementById('needs-btn').disabled`), 'the project read (' + hash + ')', 600); + await settled('opened ' + hash); +} +async function hash(value) { await evaluate(`location.hash = ${JSON.stringify('#' + value)}`); await settled('#' + value); } +async function mouse(x, y, click = false) { + await send('Input.dispatchMouseEvent', { type: 'mouseMoved', x, y }); + if (click) { await send('Input.dispatchMouseEvent', { type: 'mousePressed', x, y, button: 'left', clickCount: 1 }); await send('Input.dispatchMouseEvent', { type: 'mouseReleased', x, y, button: 'left', clickCount: 1 }); } +} +const byKey = key => `[data-key=${JSON.stringify(key)}]`; +const enc = encodeURIComponent; +async function centre(selector) { + return until(() => evaluate(`(() => { const e = [...document.querySelectorAll(${JSON.stringify(selector)})].find(e => e.offsetParent !== null); if (!e) return null; e.scrollIntoView({ block: 'nearest', inline: 'nearest' }); const r = e.getBoundingClientRect(); return { x: r.left + r.width / 2, y: r.top + r.height / 2 }; })()`), 'shown: ' + selector, 200); +} +async function press(selector) { const { x, y } = await centre(selector); await mouse(x, y, true); } +async function key(name, code = name, keyCode = 0) { await send('Input.dispatchKeyEvent', { type: 'keyDown', key: name, code, windowsVirtualKeyCode: keyCode }); await send('Input.dispatchKeyEvent', { type: 'keyUp', key: name, code, windowsVirtualKeyCode: keyCode }); } +async function replace(selector, text) { + await press(selector); + await send('Input.dispatchKeyEvent', { type: 'keyDown', key: 'a', code: 'KeyA', windowsVirtualKeyCode: 65, modifiers: 2, commands: ['selectAll'] }); + await send('Input.dispatchKeyEvent', { type: 'keyUp', key: 'a', code: 'KeyA', windowsVirtualKeyCode: 65, modifiers: 2 }); + await key('Delete', 'Delete', 46); + if (text) await send('Input.insertText', { text }); +} +const drawerText = () => evaluate(`document.getElementById('aside').innerText`); +const stripText = () => evaluate(`document.getElementById('strip').innerText`); +const drawerState = () => evaluate(`[...document.querySelectorAll('#aside header .state')].map(e => e.textContent.trim()).join(' | ')`); +const isBuilt = async () => { const t = await drawerState(); return /(^|\| )built($| \|)/.test(t) ? t : null; }; +/** The width of the strip's hairline as a number of percent, or null when it is not drawn. */ +const stripHair = () => evaluate(`(() => { const i = document.querySelector('#strip .hair i'); return i ? parseFloat(i.style.width) : null; })()`); +const drawerHair = () => evaluate(`(() => { const i = document.querySelector('#aside .hair i'); return i ? parseFloat(i.style.width) : null; })()`); +const requestState = async id => (await api('build_request', { request: id })).state; +const newestRequest = async () => (await api('build_requests', { limit: 1 })).requests[0]; + +(async () => { + let output = ''; + const catalog = path.join(temporary, 'catalog'); + server = launch(python, ['-u', 'app.py', '--port', '0', '--data', catalog, '--project-folder', folder], { cwd: root, env: process.env, stdio: ['ignore', 'pipe', 'pipe'] }); + server.stdout.on('data', chunk => { output += chunk; }); server.stderr.on('data', chunk => { serverErrors += chunk; }); + const port = await until(() => { if (server.exitCode !== null) throw Error('Tuldok exited: ' + serverErrors); return output.match(/127\.0\.0\.1:(\d+)/)?.[1]; }, 'Tuldok start-up', 1800); + origin = 'http://127.0.0.1:' + port; + auth = authenticatedFixture(); await auth.register(origin, catalog, root); + const browser = launch(findBrowser(), ['--headless', '--no-sandbox', '--disable-gpu', '--no-first-run', '--hide-scrollbars', '--remote-debugging-port=0', `--window-size=${WIDTH},${HEIGHT}`, '--user-data-dir=' + path.join(temporary, 'browser'), 'about:blank'], { stdio: 'ignore', env: { ...process.env, XDG_CONFIG_HOME: temporary, XDG_CACHE_HOME: temporary } }); + const debugPort = await waitForDebugger(browser, path.join(temporary, 'browser', 'DevToolsActivePort')); + const target = (await (await fetch('http://127.0.0.1:' + debugPort + '/json')).json()).find(item => item.type === 'page'); + socket = new WebSocket(target.webSocketDebuggerUrl); await once(socket, 'open'); + const session = cdpSession(socket, { timeoutMs: 120000, onEvent: event => { + if (event.method === 'Runtime.exceptionThrown') errors.push(event.params.exceptionDetails.exception?.description || event.params.exceptionDetails.text); + if (event.method === 'Runtime.consoleAPICalled' && event.params.type === 'error') errors.push(event.params.args.map(a => a.value ?? a.description).join(' ')); + if (event.method === 'Network.loadingFailed' && !event.params.canceled) failures.push({ error: event.params.errorText }); + if (event.method === 'Network.responseReceived' && event.params.response.status >= 400) failures.push({ url: event.params.response.url, status: event.params.response.status }); + } }); + send = session.send; + evaluate = async expression => { const result = await send('Runtime.evaluate', { expression, awaitPromise: true, returnByValue: true }); if (result.exceptionDetails) throw Error(JSON.stringify(result.exceptionDetails)); return result.result.value; }; + for (const domain of ['Page', 'Runtime', 'Network', 'Log']) await send(domain + '.enable'); + await send('Emulation.setDeviceMetricsOverride', { width: WIDTH, height: HEIGHT, deviceScaleFactor: 1, mobile: false }); + await auth.browser(send, origin); + + // ---- 1. The page opens on a project with nothing built; the owner connects the two interpreters ---------- + await open('map'); + done('Opened: ' + (await stripText()).replace(/\s+/g, ' ').slice(0, 160)); + await shot('map-nothing-built'); + for (const [name, interpreter] of [['cpu', CPU], ['gpu', GPU]]) { + const ref = 'environments/' + name; + await hash('train/env:' + enc(ref)); + await replace(byKey('envconnect:' + ref + ':field:interpreter'), interpreter); + await press(byKey('envconnect:' + ref + ':connect')); + await until(async () => (await api('environment', { reference: ref })).state === 'ready', ref + ' ready', 900); + await settled(ref + ' connected'); + done('Connected ' + ref + ' from the page: ' + (await api('environment', { reference: ref })).found.python); + } + await shot('environments-connected'); + + // ---- 2. Plan and request a build of everything; watch the training on the page ---------------------------- + await hash('train'); + await press(byKey('train:every:plan')); await settled('plan of everything'); + await shot('plan-everything'); + await press(byKey('request:plan:*:request')); + const first = await until(async () => { const r = await newestRequest(); return r && r.every ? r : null; }, 'the request of everything', 100); + let seen = null; + await until(async () => { + const runs = (await api('runs')).runs, run = runs.find(r => r.state === 'running' && r.reference === 'recipes/small-net-a'); + if (run && !seen) { + await hash('train/run:' + run.id); + const width = await until(async () => { const w = await drawerHair(); return (w > 0 && w < 100) ? w : ((await api('run', { run: run.id })).state !== 'running' ? -1 : null); }, 'a hairline partly filled', 600); + if (width > 0) { seen = { width, strip: await stripHair(), text: (await stripText()).replace(/\s+/g, ' ') }; await shot('training-small-net-a-running'); } + } + return ['succeeded', 'failed', 'cancelled'].includes(await requestState(first.id)); + }, 'the build of everything to end', 3600, 250); + const firstEnd = await api('build_request', { request: first.id }); + assert.equal(firstEnd.state, 'succeeded', JSON.stringify(firstEnd)); + assert.ok(seen, 'the training was never seen running on the page'); + done('Built everything from the page (request ' + first.id.slice(0, 8) + ', ' + firstEnd.runs.length + ' runs). While small-net-a trained the run drawer hairline stood at ' + seen.width + '% and the strip at ' + seen.strip + '%: "' + seen.text.slice(0, 200) + '"'); + await hash('map/' + enc('recipes/small-net-a')); await until(isBuilt, 'small-net-a built in its drawer', 200); + await shot('map-small-net-a-built'); + await hash('benchmarks'); await shot('benchmarks-two-subjects'); + + // ---- 3. Branch from here: a draft, a changed setting, kept, saved --------------------------------------- + const parent = 'recipes/small-net-a', ref = 'recipes/small-net-3-000-updates'; + await hash('map/' + enc(parent)); + await press(byKey('modelact:' + parent + ':branch')); await settled('the branch form'); + await replace(byKey('branch:' + parent + ':field:title'), 'Small net, 3,000 updates'); + await press(byKey('branch:' + parent + ':change-training-policy')); + await replace(byKey('branch:' + parent + ':field:description'), 'Half the updates, to see how much accuracy that costs.'); + await shot('branch-form'); + await press(byKey('branch:' + parent + ':create')); + await centre(byKey('draft:' + ref + ':keep')); await settled('the draft'); + const updates = await evaluate(`document.querySelector(${JSON.stringify(byKey('editor:' + ref + ':setting-updates'))}).value`); + assert.equal(updates, '6000', 'the parent settings were copied into the draft'); + await evaluate(`document.getElementById('aside').scrollTop = 0`); + await shot('draft-on-map'); + await replace(byKey('editor:' + ref + ':setting-updates'), '3000'); await key('Tab', 'Tab', 9); + await shot('draft-updates-changed'); + assert.equal(fs.existsSync(path.join(folder, 'recipes', 'small-net-3-000-updates.json')), false); + await press(byKey('draft:' + ref + ':keep')); await settled('kept'); + assert.equal((await api('definition', { reference: ref })).unsaved, true); + done('Branched ' + parent + ' on the page, changed updates 6000 → 3000 in the form, kept: ' + ref + ' is an unsaved definition; strip: "' + (await stripText()).replace(/\s+/g, ' ').slice(0, 140) + '"'); + await shot('draft-kept-unsaved'); + await press(byKey('model:' + ref + ':save')); await settled('saved'); + const saved = JSON.parse(fs.readFileSync(path.join(folder, 'recipes', 'small-net-3-000-updates.json'), 'utf8')); + assert.equal(saved.derived_from, parent); assert.equal(saved.run.settings.updates, 3000); assert.equal(saved.run.settings.learning_rate, 0.001); assert.equal(saved.change, 'training-policy'); + assert.ok(!('settings_file' in saved.run) && !('labels' in saved) && !('card' in saved)); + done('Saved from the page: recipes/small-net-3-000-updates.json is in the folder with derived_from, change and settings.updates 3000'); + + // ---- 4. Plan, request, watch it train, see it built on the map --------------------------------------------- + await press(byKey('model:' + ref + ':plan')); await settled('the plan of the branch'); + await shot('plan-branch'); + await press(byKey('request:plan:' + ref + ':request')); + const second = await until(async () => { const r = await newestRequest(); return r && r.id !== first.id ? r : null; }, 'the request of the branch', 100); + seen = null; + await until(async () => { + const run = (await api('runs', { reference: ref })).runs.find(r => r.state === 'running'); + if (run && !seen) { + await hash('train/run:' + run.id); + const width = await until(async () => { const w = await drawerHair(); return (w > 0 && w < 100) ? w : ((await api('run', { run: run.id })).state !== 'running' ? -1 : null); }, 'a hairline partly filled', 600); + if (width > 0) { seen = { width, strip: await stripHair(), text: (await drawerText()).replace(/\s+/g, ' ') }; await shot('training-branch-running'); await theme('dark'); await shot('training-branch-running-dark'); await theme('light'); } + } + return ['succeeded', 'failed', 'cancelled'].includes(await requestState(second.id)); + }, 'the build of the branch to end', 3600, 250); + assert.equal(await requestState(second.id), 'succeeded'); + assert.ok(seen, 'the branch was never seen training on the page'); + const marker = await evaluate(`(window.__acceptance = window.__acceptance || Math.random())`); + await hash('map/' + enc(ref)); + const turned = Date.now(); await until(isBuilt, 'the branch built in its drawer', 300); + const turnedIn = Date.now() - turned; + await until(async () => /^Idle/.test((await stripText()).trim()), 'the strip idle after the branch', 100); + assert.equal(await evaluate('window.__acceptance'), marker, 'the page was not reloaded'); + const node = await evaluate(`(() => { const g = document.querySelector('#main svg g.node[data-id=${JSON.stringify(ref)}]'); return g ? g.getAttribute('class') : null; })()`); + const model = (await api('map')).models.find(m => m.reference === ref); + assert.equal(model.state, 'built'); assert.equal(model.derived_from, parent); assert.equal(model.unsaved, false); assert.ok(model.trained_at); + done('Requested from the plan view; the branch trained on the GPU (hairline at ' + seen.width + '% in the run drawer); request ' + second.id.slice(0, 8) + ' succeeded; ' + turnedIn + ' ms later, with no reload, the drawer said built; the map shows it built, dated by its run ' + model.trained_at + ', node class "' + node + '"'); + await evaluate(`document.getElementById('aside').scrollTop = 0`); + await shot('map-branch-built'); await theme('dark'); await shot('map-branch-built-dark'); await theme('light'); + + // ---- 5. Edit another definition in the text view: the benchmark gains the new model as a subject ------------ + await hash('overview'); await press(byKey('open-edit:benchmarks/held-out')); await settled('the benchmark editor'); + const text = await evaluate(`document.querySelector(${JSON.stringify(byKey('editor:benchmarks/held-out:text'))}).value`); + const subject = ' {"name": "small-net-b", "title": "Small net, 3,000 updates", "recipe": "' + ref + '", "argument": "model:{recipe}/model.pt"},\n'; + const changed = text.replace(' {"name": "predict-zero"', subject + ' {"name": "predict-zero"'); + assert.notEqual(changed, text); + await replace(byKey('editor:benchmarks/held-out:text'), changed); + await press(byKey('edit:benchmarks/held-out:keep')); await settled('the benchmark kept'); + await shot('benchmark-edited-unsaved'); + await press(byKey('save:save')); await settled('the benchmark saved'); + assert.equal(fs.readFileSync(path.join(folder, 'benchmarks', 'held-out.json'), 'utf8'), changed); + done('Edited benchmarks/held-out in the text view (a third subject), kept and saved from the strip: the file is the text typed, byte for byte'); + + // ---- 6. An agent asks for the benchmark; the owner approves it from Needs you ------------------------------ + const agent = await credential('Acceptance agent', ['inspect', 'execute']); + const asked = await api('request_build', { targets: ['benchmarks/held-out'] }, agent); + assert.equal(asked.state, 'awaiting-approval'); + // The page is open and idle; nothing tells it but its own fifteen-second look. + const before = await evaluate(`document.getElementById('needs-btn').textContent`), mark = await evaluate('window.__acceptance'); + const noticed = Date.now(); + await until(() => evaluate(`document.getElementById('needs-btn').textContent !== ${JSON.stringify(before)}`), 'Needs you to count the agent request without a reload', 400); + assert.equal(await evaluate('window.__acceptance'), mark, 'the page was not reloaded'); + done('The idle page noticed the agent request by itself after ' + Math.round((Date.now() - noticed) / 1000) + ' s: "' + before + '" became "' + await evaluate(`document.getElementById('needs-btn').textContent`) + '"'); + await press('#needs-btn'); await centre(byKey('need:request:' + asked.id + ':approve')); + await shot('needs-you-agent-request'); + await press(byKey('need:request:' + asked.id + ':approve')); + const t0 = Date.now(), seenStrip = []; + const sample = async () => { const t = (await stripText()).replace(/\s+/g, ' ').replace(/ Read at.*$/, '').slice(0, 110); if (!seenStrip.length || seenStrip[seenStrip.length - 1][1] !== t) seenStrip.push([Date.now() - t0, t]); }; + await until(async () => { await sample(); return ['succeeded', 'failed', 'cancelled'].includes(await requestState(asked.id)); }, 'the agent build to end', 3600, 250); + const ended = Date.now() - t0; + await until(async () => { await sample(); return /^Idle/.test(seenStrip[seenStrip.length - 1][1]); }, 'the strip idle after the agent build: ' + JSON.stringify(seenStrip), 60, 250); + done('The strip while the agent build ran (ms after Approve; the request ended at ' + ended + '): ' + seenStrip.map(([at, t]) => at + ' "' + t + '"').join(' → ')); + const agentEnd = await api('build_request', { request: asked.id }); + assert.equal(agentEnd.state, 'succeeded', JSON.stringify(agentEnd)); + await key('Escape', 'Escape', 27); + await hash('benchmarks'); await settled('benchmarks'); + const rows = (await api('results', { benchmark: 'held-out', metric: 'error' })).rows; + const errorOf = name => (rows.find(r => r.subject === name) || {}).median; + assert.ok(errorOf('small-net-b') != null, 'the new model has a result: ' + JSON.stringify(rows.map(r => r.subject))); + done('An agent asked for benchmarks/held-out (awaiting approval); approved from Needs you on the page; it ran ' + agentEnd.runs.length + ' run(s) and succeeded. Median error: small-net-a ' + errorOf('small-net-a') + ', small-net-b (3,000 updates) ' + errorOf('small-net-b') + ', predict-zero ' + errorOf('predict-zero')); + await shot('benchmarks-three-subjects'); await theme('dark'); await shot('benchmarks-three-subjects-dark'); await theme('light'); + await hash('train'); await shot('train-after'); + await hash('map'); await shot('map-after'); + + const summary = await api('summary'), activity = await api('activity', { limit: 100 }); + done('In the end: states ' + JSON.stringify(summary.states) + '; activity: ' + activity.items.map(i => i.operation || i.name).reverse().join(', ')); + assert.deepEqual(errors, [], 'script errors: ' + JSON.stringify(errors)); + assert.deepEqual(failures, [], 'failed requests: ' + JSON.stringify(failures)); + done('No script error and no failed request in the whole run'); + fs.writeFileSync(path.join(out, 'receipt.json'), JSON.stringify({ at: new Date().toISOString(), log }, null, 2) + '\n'); +})().catch(async error => { + console.error('FAILED', error.stack || error); console.error('script errors', JSON.stringify(errors).slice(0, 2000)); console.error('failed requests', JSON.stringify(failures).slice(0, 2000)); + console.error('server stderr tail', serverErrors.slice(-3000)); + try { await shot('failure'); } catch (e) { /* no page */ } + process.exitCode = 1; +}).finally(async () => { + try { socket && socket.close(); } catch (e) { /* closed */ } + for (const child of children.slice().reverse()) await stop(child); + fs.rmSync(temporary, { recursive: true, force: true }); +}); diff --git a/tests/browser_project_workspace_actions.cjs b/tests/browser_project_workspace_actions.cjs index 72d31a36..ae7f1a16 100644 --- a/tests/browser_project_workspace_actions.cjs +++ b/tests/browser_project_workspace_actions.cjs @@ -143,6 +143,14 @@ async function settled(label) { await until(() => evaluate(`(() => { const reading = e => [...e.querySelectorAll('.note')].some(n => n.textContent === 'Reading…'); return !reading(document.getElementById('main')) && !reading(document.getElementById('aside')) && !document.getElementById('main').hasAttribute('aria-busy') && !document.querySelector('.act-group [aria-busy]'); })()`), label); await pause(150); } +/** Replaces the whole value of a field (a number field too): select all, delete, then the text. */ +async function replace(selector, text) { + await press(selector); + await send('Input.dispatchKeyEvent', { type: 'keyDown', key: 'a', code: 'KeyA', windowsVirtualKeyCode: 65, modifiers: 2, commands: ['selectAll'] }); + await send('Input.dispatchKeyEvent', { type: 'keyUp', key: 'a', code: 'KeyA', windowsVirtualKeyCode: 65, modifiers: 2 }); + await key('Delete', 'Delete', 46); + if (text) await send('Input.insertText', { text }); +} async function drawerText() { return evaluate(`document.getElementById('aside').innerText`); } const drawerState = () => evaluate(`[...document.querySelectorAll('#aside header .state')].map(e => e.textContent.trim()).join(' ')`); @@ -175,9 +183,12 @@ for step in range(1, 241): with open(os.path.join(out, 'weights.json'), 'w') as handle: json.dump({'constant': 2.0}, handle) `); - const recipe = (title, script, extra) => JSON.stringify({ format: 'tuldok_definition_v1', kind: 'recipe', title, ...extra, - run: { command: ['python', script, '--out', '{output}'], environment: 'environments/test-python', outputs: { weights: { path: 'weights.json', role: 'weights' } }, sources: [script] } }, null, 2) + '\n'; - fs.writeFileSync(path.join(folder, 'recipes', 'slow.json'), recipe('Slow fit, four seconds', 'slow.py', { labels: { short: 'SLOW' }, change: 'refinement', derived_from: 'recipes/fit-a' })); + const recipe = (title, script, extra, settingsFile) => JSON.stringify({ format: 'tuldok_definition_v1', kind: 'recipe', title, ...extra, + run: { command: ['python', script].concat(settingsFile ? ['--settings', '{settings}'] : [], ['--out', '{output}']), environment: 'environments/test-python', ...(settingsFile ? { settings_file: settingsFile } : {}), + outputs: { weights: { path: 'weights.json', role: 'weights' } }, sources: [script] } }, null, 2) + '\n'; + // The slow recipe reads its settings from a file holding a JSON object, so a branch of it carries them inline (T22). + fs.writeFileSync(path.join(code, 'slow-settings.json'), JSON.stringify({ steps: 8, rate: 0.001, label: 'slow', schedule: [1, 2] }) + '\n'); + fs.writeFileSync(path.join(folder, 'recipes', 'slow.json'), recipe('Slow fit, four seconds', 'slow.py', { labels: { short: 'SLOW' }, change: 'refinement', derived_from: 'recipes/fit-a' }, 'slow-settings.json')); fs.writeFileSync(path.join(folder, 'recipes', 'hold.json'), recipe('Held fit, runs until cancelled', 'hold_run.py', { labels: { short: 'HOLD' }, change: 'training-policy' })); const git = ['-c', 'user.name=Tuldok Test', '-c', 'user.email=test@example.invalid', '-c', 'commit.gpgsign=false', '-c', 'init.defaultBranch=main', '-C', path.join(temporary, 'fixture')]; execFileSync('git', [...git, 'init', '-q']); execFileSync('git', [...git, 'add', '-A']); execFileSync('git', [...git, 'commit', '-q', '-m', 'The fixture.']); @@ -425,6 +436,267 @@ with open(os.path.join(out, 'weights.json'), 'w') as handle: await inspect('conflict resolved'); check('A conflict on recipes/fit-a: the panel named it; Keep my edits kept "Fit a, my edit" unsaved; a second one, Take the files ("' + takeWords + '"), took "Fit a, changed on disk again"'); + // ==== Editing and branching (spec-w3 section 3.2, slice T22) =========================================== + const projectId = JSON.parse(fs.readFileSync(path.join(folder, 'tuldok.json'), 'utf8')).id; + const stored = () => evaluate(`JSON.parse(sessionStorage.getItem(${JSON.stringify('tuldok-drafts:' + projectId)}) || '{"drafts": []}').drafts`); + const onDisk = name => fs.existsSync(path.join(folder, name)) ? fs.readFileSync(path.join(folder, name), 'utf8') : null; + const stripUnsaved = () => evaluate(`(() => { const c = document.querySelector('#strip .unsaved .count'); return c ? c.textContent : ''; })()`); + const mapNodes = () => evaluate(`[...document.querySelectorAll('.tree-map .node')].map(g => { const c = g.querySelector('circle'); return { id: g.dataset.id, x: +c.getAttribute('cx'), y: +c.getAttribute('cy'), cls: g.getAttribute('class'), dash: getComputedStyle(c).strokeDasharray, fill: getComputedStyle(c).fill, label: (g.querySelector('text') || {}).textContent || '' }; })`); + const listRows = () => evaluate(`[...document.querySelectorAll('.tree-list .trow')].map(b => ({ id: b.dataset.id, chip: b.querySelector('.chip').textContent, mark: b.querySelector('.umark').textContent, cls: b.className }))`); + const editorValue = name => evaluate(`(() => { const e = [...document.querySelectorAll('#aside [data-key]')].find(e => e.dataset.key === ${JSON.stringify(name)}); return e ? e.value : null; })()`); + const refusalText = () => evaluate(`(() => { const r = document.querySelector('#aside .refusal'); return r && r.innerText; })()`); + + // ---- Branch a built model: the draft on the map, after its parent; it survives a reload ----------------- + await hash('map/recipes%2Fslow'); + assert.equal(await drawerState(), 'built'); + await press(byKey('modelact:recipes/slow:branch')); + await until(() => evaluate(`location.hash === '#map/branch%3Arecipes%2Fslow' && !!document.querySelector('#aside .branch')`), 'the branch form'); + const branchKinds = await evaluate(`[...document.querySelectorAll('#aside .branch input[type="radio"]')].filter(r => r.checked).map(r => r.value)`); + assert.deepEqual(branchKinds, ['refinement'], 'The kind of change is the parent\'s to begin with'); + // Create without a title is refused in place. + await press(byKey('branch:recipes/slow:create')); + assert.match(await until(refusalText, 'the title refusal'), /needs a title/); + await type(byKey('branch:recipes/slow:field:title'), 'Slow fit, a faster rate'); + await type(byKey('branch:recipes/slow:field:description'), 'Doubles the rate of the slow fit.'); + await shots('branch-form'); + await press(byKey('branch:recipes/slow:create')); + const draftRef = 'recipes/slow-fit-a-faster-rate'; + await until(() => evaluate(`location.hash === '#map/' + encodeURIComponent(${JSON.stringify(draftRef)}) && !!document.querySelector('#aside .editor')`), 'the draft selected, its drawer the editor'); await settled('draft'); + const placeDraft = async () => { + const nodes = await mapNodes(), rows = await listRows(), slow = nodes.find(n => n.id === 'recipes/slow'), draft = nodes.find(n => n.id === draftRef); + assert.ok(draft, 'The draft is on the map'); + assert.equal(rows.findIndex(r => r.id === draftRef), rows.findIndex(r => r.id === 'recipes/slow') + 1, 'The draft is listed right after its parent'); + assert.equal(Math.min(...nodes.filter(n => n.x > slow.x).map(n => n.x)), draft.x, 'The draft is drawn right after its parent'); + assert.notEqual(draft.y, slow.y, 'The draft is in the lane of its parent\'s branches'); + assert.ok(await evaluate(`!!document.querySelector('.tree-map .der[data-family="recipes/slow"]')`), 'Its line from the parent'); + assert.equal(new Set(nodes.map(n => n.x + ',' + n.y)).size, nodes.length, 'No node is drawn on another'); + assert.match(draft.cls, /\bplanned\b/); assert.match(draft.cls, /\bdraft\b/); assert.notEqual(draft.dash, 'none', 'dashed'); assert.equal(draft.label, 'new'); + assert.equal(rows.find(r => r.id === draftRef).chip, 'draft'); + return { draft, slow, rows: rows.length }; + }; + const placed = await placeDraft(); + const drawerForm = await evaluate(`({ view: [...document.querySelectorAll('#aside .seg button')].map(b => b.textContent + '=' + b.getAttribute('aria-pressed')), inlined: [...document.querySelectorAll('#aside p.note')].map(p => p.textContent).find(t => t.includes('copied from')) || '', steps: [...document.querySelectorAll('#aside .new-steps li')].map(li => li.dataset.step + ':' + li.className), buttons: [...document.querySelectorAll('#aside .act-group button')].map(b => b.textContent) })`); + assert.deepEqual(drawerForm.view, ['Form=true', 'Text=false']); assert.match(drawerForm.inlined, /slow-settings\.json/); + assert.deepEqual(drawerForm.steps, ['Kept:todo', 'Saved:todo', 'Build requested:todo', 'Running:todo', 'Built:todo']); assert.deepEqual(drawerForm.buttons, ['Keep', 'Discard']); + assert.equal((await stored()).map(d => d.reference).join(), draftRef); + await open('map/' + encodeURIComponent(draftRef)); + await until(() => evaluate(`!!document.querySelector('#aside .editor')`), 'the draft drawer after a reload'); await settled('reloaded'); + await placeDraft(); + check('Branched recipes/slow ("' + drawerForm.inlined + '"): the draft ' + draftRef + ' is drawn hollow and dashed, labelled new, right after its parent (x ' + placed.slow.x + ' → ' + placed.draft.x + ', lane below), listed after it with the chip "draft", its drawer the form with the steps ' + drawerForm.steps.join(', ') + '; still there after a reload'); + + // ---- Change a setting (a number stays a number), keep, save ------------------------------------------------------ + assert.equal(await editorValue('editor:' + draftRef + ':setting-rate'), '0.001'); + await replace(byKey('editor:' + draftRef + ':setting-rate'), '0.002'); + await until(async () => /"rate": 0\.002\b/.test((await stored())[0].text), 'the setting in the draft text'); + const draftText = (await stored())[0].text; + assert.equal(JSON.parse(draftText).run.settings.rate, 0.002); assert.equal(JSON.parse(draftText).run.settings.steps, 8); + assert.match(draftText, /\n "run": \{\n "command"/, 'Written with the indentation the text had'); assert.ok(draftText.endsWith('}\n')); + await evaluate(`document.querySelector('#aside .new-steps').scrollIntoView({ block: 'end' })`); + await shots('draft-on-map'); + await press(byKey('draft:' + draftRef + ':keep')); + await until(async () => (await stripUnsaved()) === '1 definition unsaved', 'the strip says 1 unsaved'); await settled('kept'); + const keptView = await evaluate(`({ steps: [...document.querySelectorAll('#aside .new-steps li')].map(li => li.dataset.step + ':' + li.className), next: [...document.querySelectorAll('#aside .new-steps .act-group button')].map(b => b.textContent), mark: document.querySelector('#aside header .umark').textContent, node: !!document.querySelector('.tree-map .node[data-id="${draftRef}"] .unsaved-dot'), row: [...document.querySelectorAll('.tree-list .trow')].find(b => b.dataset.id === '${draftRef}').querySelector('.umark').textContent })`); + assert.deepEqual(keptView.steps.slice(0, 2), ['Kept:done', 'Saved:todo']); assert.deepEqual(keptView.next, ['Save', 'Discard']); + assert.equal(keptView.mark, 'unsaved'); assert.ok(keptView.node, 'The unsaved mark on the map node'); assert.equal(keptView.row, 'unsaved'); + assert.deepEqual(await stored(), [], 'A kept draft is no longer a draft'); + await press(byKey('model:' + draftRef + ':save')); + await until(async () => (await stripUnsaved()) === '', 'nothing unsaved after Save'); await settled('saved branch'); + const savedBranch = JSON.parse(onDisk('recipes/slow-fit-a-faster-rate.json')); + assert.equal(savedBranch.derived_from, 'recipes/slow'); assert.equal(savedBranch.run.settings.rate, 0.002); assert.equal(savedBranch.title, 'Slow fit, a faster rate'); + assert.equal(savedBranch.labels, undefined); assert.equal(savedBranch.card, undefined); assert.equal(savedBranch.run.settings_file, undefined); + check('Changed the rate in the form (0.001 → 0.002, a number; steps stays 8), kept it (the strip said 1 unsaved; the drawer, list row and node marked unsaved; next step ' + keptView.next[0] + '), saved: ' + draftRef + '.json has derived_from, the setting and the title, and no labels or card'); + + // ---- Plan build, request it: the model drawn built with its line, without a reload ------------------------------- + await evaluate(`window.__noReload = 2`); + await press(byKey('model:' + draftRef + ':plan')); + await until(() => evaluate(`location.hash === '#map/' + encodeURIComponent('plan:${draftRef}') && !!document.querySelector('#aside .plan-view')`), 'the plan view of the branch'); await settled('plan branch'); + await press(byKey('request:plan:' + draftRef + ':request')); + await until(() => evaluate(`location.hash.startsWith('#train/request%3A')`), 'the branch request opened'); + const branchRequest = decodeURIComponent(await evaluate(`location.hash`)).slice('#train/request:'.length); + await hash('map/' + encodeURIComponent(draftRef)); + await until(async () => { const n = (await mapNodes()).find(x => x.id === draftRef); return n && !/\bplanned\b/.test(n.cls) && n.dash === 'none'; }, 'the branch drawn built', 400); + await until(() => evaluate(`!!document.querySelector('#aside .new-steps li[data-step="Built"].done')`), 'its steps say Built', 200); await settled('branch built'); + assert.equal(await evaluate(`window.__noReload`), 2, 'The page was not reloaded'); + assert.equal((await api('build_request', { request: branchRequest })).state, 'succeeded'); + assert.ok(await evaluate(`!!document.querySelector('.tree-map .der[data-family="recipes/slow"]')`), 'Its line from the parent'); + const builtSteps = await evaluate(`[...document.querySelectorAll('#aside .new-steps li')].map(li => li.dataset.step + ':' + li.className).join(', ')`); + await shots('branch-built'); + check('Planned and requested the branch (' + branchRequest.slice(0, 8) + '); without a reload it is drawn built (solid) with its line from recipes/slow, and its steps read ' + builtSteps); + + // ---- A draft discarded is gone from the map, the list and sessionStorage ---------------------------------------------- + await hash('map/branch:recipes%2Fslow'); + await type(byKey('branch:recipes/slow:field:title'), 'A branch to throw away'); + await press(byKey('branch:recipes/slow:create')); + const throwaway = 'recipes/a-branch-to-throw-away'; + await until(() => evaluate(`location.hash === '#map/' + encodeURIComponent('${throwaway}')`), 'the second draft'); await settled('second draft'); + assert.ok((await mapNodes()).some(n => n.id === throwaway)); + await press(byKey('draft:' + throwaway + ':discard')); + const dropWords = await evaluate(`document.querySelector('#aside .confirm-words').textContent`); + await press(byKey('draft:' + throwaway + ':discard:confirm')); + await until(async () => !(await mapNodes()).some(n => n.id === throwaway), 'the draft gone from the map'); await settled('discarded'); + assert.ok(!(await listRows()).some(r => r.id === throwaway)); assert.deepEqual(await stored(), []); + check('A second draft, discarded with two presses ("' + dropWords + '"), is gone from the map, the list and sessionStorage'); + + // ---- A branch whose draft has errors: the problems, and Keep refused with them ------------------------------------------ + await hash('map/branch:recipes%2Fearly-fit'); + await type(byKey('branch:recipes/early-fit:field:title'), 'Early fit, run again'); + await press(byKey('branch:recipes/early-fit:create')); + const broken = 'recipes/early-fit-run-again'; + await until(() => evaluate(`location.hash === '#map/' + encodeURIComponent('${broken}') && !!document.querySelector('#aside .editor')`), 'the earlier-work draft'); await settled('broken draft'); + const problems = await evaluate(`document.querySelector('#aside .problems').innerText`); + assert.match(problems, /run/); + const keepRefused = allow(/\/api\/project\/set_definition$/, 400); + await press(byKey('draft:' + broken + ':keep')); + const keepRefusal = await until(refusalText, 'Keep refused'); close(keepRefused); + assert.ok(!(await api('definitions', { kind: 'recipe' })).definitions.some(d => d.reference === broken), 'Nothing stored'); + check('A branch of earlier work without run opens with its problems ("' + problems.replace(/\n/g, ' ').slice(0, 120) + '…"); Keep was refused with them ("' + keepRefusal.replace(/\n/g, ' ').slice(0, 120) + '…") and nothing was stored'); + + // ---- Edit an existing recipe in the form; leave and come back; keep; discard the edit --------------------------------- + const k1File = onDisk('recipes/stepper-k1.json'); + await hash('map/recipes%2Fstepper-k1'); + await press(byKey('modelact:recipes/stepper-k1:edit')); + await until(() => evaluate(`location.hash === '#map/edit%3Arecipes%2Fstepper-k1' && !!document.querySelector('#aside .editor-form')`), 'the editor of stepper-k1'); await settled('editor k1'); + await type(byKey('editor:recipes/stepper-k1:description'), 'Trained again with a recorded command.'); + await until(() => evaluate(`document.querySelector('#aside header .umark').textContent === 'not kept yet'`), 'not kept yet in the header'); + await shots('editor-form'); + await hash('train'); await hash('map/edit%3Arecipes%2Fstepper-k1'); + const back = await evaluate(`({ value: document.querySelector('#aside [data-key="editor:recipes/stepper-k1:description"]').value, header: document.querySelector('#aside header .umark').textContent, row: [...document.querySelectorAll('.tree-list .trow')].find(b => b.dataset.id === 'recipes/stepper-k1').querySelector('.umark').textContent })`); + assert.deepEqual(back, { value: 'Trained again with a recorded command.', header: 'not kept yet', row: 'not kept yet' }); + await press(byKey('edit:recipes/stepper-k1:keep')); + await until(async () => (await api('definition', { reference: 'recipes/stepper-k1' })).unsaved, 'stepper-k1 kept'); await settled('k1 kept'); + assert.equal((await api('definition', { reference: 'recipes/stepper-k1' })).document.description, 'Trained again with a recorded command.'); + assert.equal(await evaluate(`document.querySelector('#aside header .umark').textContent`), 'unsaved'); + await press(byKey('edit:recipes/stepper-k1:discard')); + const revertWords = await evaluate(`document.querySelector('#aside .confirm-words').textContent`); + await press(byKey('edit:recipes/stepper-k1:discard:confirm')); + await until(async () => !(await api('definition', { reference: 'recipes/stepper-k1' })).unsaved, 'stepper-k1 reverted'); await settled('k1 reverted'); + assert.equal((await api('definition', { reference: 'recipes/stepper-k1' })).text, k1File, 'The definition is the file again'); + check('Edited stepper-k1\'s description in the form; after Train and back the typing was there, marked "not kept yet" in the drawer and its row; kept (unsaved), then Discard edit with two presses ("' + revertWords + '") put the file back'); + + // ---- Change a kind of change, keep, save -------------------------------------------------------------------------------- + await hash('map/edit%3Arecipes%2Fstepper-k2'); + await press(byKey('editor:recipes/stepper-k2:change-architecture')); + await press(byKey('edit:recipes/stepper-k2:keep')); + await until(async () => (await api('definition', { reference: 'recipes/stepper-k2' })).document.change === 'architecture', 'k2 kept'); await settled('k2 kept'); + await press(byKey('edit:recipes/stepper-k2:save')); + await until(async () => (await stripUnsaved()) === '', 'k2 saved'); await settled('k2 saved'); + const k2 = JSON.parse(onDisk('recipes/stepper-k2.json')); + assert.equal(k2.change, 'architecture'); assert.equal(k2.labels.short, 'K2'); assert.equal(k2.run.settings.learning_rate, 0.0005); + const k2Node = (await mapNodes()).find(n => n.id === 'recipes/stepper-k2'); + assert.match(k2Node.cls, /\barchitecture\b/); assert.doesNotMatch(k2Node.cls, /\brefinement\b/); + check('Changed stepper-k2\'s kind of change to Architecture, kept and saved: the file says "change": "architecture" (its other fields as they were) and its node is ' + k2Node.cls); + + // ---- The text view: invalid JSON refused with the problem, nothing kept; then a valid change kept -------------------------- + const fitBDef = await api('definition', { reference: 'recipes/fit-b' }); + await hash('map/edit%3Arecipes%2Ffit-b'); + await press(byKey('editor:recipes/fit-b:view-text')); + await until(() => evaluate(`!!document.querySelector('#aside textarea.code')`), 'the text view'); + await replace(byKey('editor:recipes/fit-b:text'), fitBDef.text.replace('"title": "Fit b, saved from the strip",', '"title": "Fit b, broken",,')); + const invalidRefused = allow(/\/api\/project\/set_definition$/, 400); + await press(byKey('edit:recipes/fit-b:keep')); + const invalidRefusal = await until(refusalText, 'the invalid JSON refused'); close(invalidRefused); + assert.match(invalidRefusal, /not valid|JSON/i); + assert.equal((await api('definition', { reference: 'recipes/fit-b' })).text, fitBDef.text, 'Nothing was kept'); + await evaluate(`document.querySelector('#aside .refusal').scrollIntoView({ block: 'center' })`); + await shots('text-problem'); + await replace(byKey('editor:recipes/fit-b:text'), fitBDef.text.replace('"Fit b, saved from the strip"', '"Fit b, from the text view"')); + await press(byKey('edit:recipes/fit-b:keep')); + await until(async () => (await api('definition', { reference: 'recipes/fit-b' })).title === 'Fit b, from the text view', 'the text kept'); await settled('text kept'); + check('In the text view, invalid JSON was refused with the problem shown ("' + invalidRefusal.replace(/\n/g, ' ').slice(0, 120) + '") and nothing kept; then a valid change was kept'); + + // ---- Pick on the map: Escape leaves the state; a pick sets the parent; its line is drawn ------------------------------------- + await hash('map/edit%3Arecipes%2Fhold'); + await press(byKey('editor:recipes/hold:pick')); + await until(() => evaluate(`!!document.querySelector('#aside .picking')`), 'the picking state'); + const pickWords = await evaluate(`document.querySelector('#aside .picking p').textContent`); + await shots('picking'); + await key('Escape', 'Escape', 27); + await until(() => evaluate(`!document.querySelector('#aside .picking') && document.getElementById('drawer').classList.contains('open')`), 'Escape left the picking state, not the drawer'); + await press(byKey('editor:recipes/hold:pick')); + await until(() => evaluate(`!!document.querySelector('#aside .picking')`), 'the picking state again'); + await press('.tree-map .node[data-id="recipes/hold"]'); + assert.match(await until(() => evaluate(`(() => { const p = document.querySelector('#aside .picking .warnline'); return p && p.textContent; })()`), 'itself refused'), /not derived from itself/); + await press('.tree-map .node[data-id="recipes/fit-b"]'); + await until(() => evaluate(`!document.querySelector('#aside .picking') && document.querySelector('#aside .derived-name').textContent.includes('Fit b')`), 'fit-b as the parent'); await settled('picked'); + assert.equal(await evaluate(`location.hash`), '#map/edit%3Arecipes%2Fhold'); + await press(byKey('edit:recipes/hold:keep')); + await until(async () => (await api('definition', { reference: 'recipes/hold' })).document.derived_from === 'recipes/fit-b', 'hold kept with its parent'); await settled('hold kept'); + await until(() => evaluate(`!!document.querySelector('.tree-map .der[data-family="recipes/fit-b"]')`), 'the derivation line from fit-b'); + await press('#strip ' + byKey('save:save')); await until(async () => (await stripUnsaved()) === '', 'saved'); await settled('saved hold'); + check('Pick on the map ("' + pickWords + '"): Escape left it; pressing hold itself was refused in place; pressing fit-b made it the parent, kept, with its line drawn'); + + // ---- Remove: one nothing uses, and one in use (the refusal names its users) ------------------------------------------------ + await hash('overview'); + await until(() => evaluate(`!!document.querySelector('#main .ov-defs .row.def')`), 'the list of every definition'); + const listed = await evaluate(`[...document.querySelectorAll('#main .ov-defs h3')].map(e => e.textContent)`); + await evaluate(`document.querySelector('#main .ov-defs').scrollIntoView({ block: 'start' })`); + await shots('overview-list'); + await press(byKey('open-edit:charts/rollout-ranking')); + await until(() => evaluate(`location.hash === '#overview/edit%3Acharts%2Frollout-ranking' && !!document.querySelector('#aside textarea.code')`), 'the chart in the text view'); await settled('chart editor'); + const chartText = (await api('definition', { reference: 'charts/rollout-ranking' })).text; + await replace(byKey('editor:charts/rollout-ranking:text'), chartText.replace('"Rollout error by subject"', '"Rollout error, each subject"')); + await press(byKey('edit:charts/rollout-ranking:keep')); + await until(async () => (await api('definition', { reference: 'charts/rollout-ranking' })).title === 'Rollout error, each subject', 'the chart kept'); await settled('chart kept'); + await press(byKey('edit:charts/rollout-ranking:remove')); + const removeWords = await evaluate(`document.querySelector('#aside .confirm-words').textContent`); + await press(byKey('edit:charts/rollout-ranking:remove:confirm')); + await until(async () => (await api('definition', { reference: 'charts/rollout-ranking' })).removed, 'the chart marked removed'); await settled('removed'); + assert.equal(await evaluate(`[...document.querySelectorAll('#main .ov-defs .row.def')].find(r => r.dataset.ref === 'charts/rollout-ranking').querySelector('.umark').textContent`), 'removed'); + await press(byKey('open-edit:datasets/waves')); + await until(() => evaluate(`location.hash === '#overview/edit%3Adatasets%2Fwaves' && !!document.querySelector('#aside textarea.code')`), 'the waves dataset'); await settled('waves'); + const inUse = allow(/\/api\/project\/remove_definition$/, 409); + await press(byKey('edit:datasets/waves:remove')); await press(byKey('edit:datasets/waves:remove:confirm')); + const usedBy = await until(refusalText, 'the in-use refusal'); close(inUse); + assert.match(usedBy, /recipes\/stepper-k1/); + assert.equal((await api('definition', { reference: 'datasets/waves' })).removed, false); + await hash('overview/edit%3Acharts%2Frollout-ranking'); + await press(byKey('edit:charts/rollout-ranking:discard')); await press(byKey('edit:charts/rollout-ranking:discard:confirm')); + await until(async () => { const d = await api('definition', { reference: 'charts/rollout-ranking' }); return !d.removed && !d.unsaved; }, 'the chart back'); await settled('chart back'); + check('Overview lists every definition by kind (' + listed.join(', ') + '); a chart edited in the text view and kept, then removed with two presses ("' + removeWords + '") and put back; removing datasets/waves was refused naming its users ("' + usedBy.replace(/\n/g, ' ').slice(0, 140) + '")'); + + // ---- Edit a dataset from the Data tab, in the text view -------------------------------------------------------------------- + await hash('data/datasets%2Fnumbers'); + await press(byKey('dataedit:datasets/numbers:edit')); + await until(() => evaluate(`location.hash === '#data/edit%3Adatasets%2Fnumbers' && !!document.querySelector('#aside textarea.code')`), 'the dataset in the text view'); await settled('dataset editor'); + const numbersText = (await api('definition', { reference: 'datasets/numbers' })).text; + await replace(byKey('editor:datasets/numbers:text'), numbersText.replace('"A few numbers"', '"A few numbers, renamed"')); + await press(byKey('edit:datasets/numbers:keep')); + await until(async () => (await api('definition', { reference: 'datasets/numbers' })).title === 'A few numbers, renamed', 'the dataset kept'); await settled('dataset kept'); + await press(byKey('edit:datasets/numbers:discard')); await press(byKey('edit:datasets/numbers:discard:confirm')); + await until(async () => (await api('definition', { reference: 'datasets/numbers' })).text === numbersText, 'the dataset back'); await settled('dataset back'); + await inspect('dataset back'); + check('Edited datasets/numbers from the Data tab in the text view, kept it, and discarded the edit'); + + // ---- Typed text and focus outlive the refresh while a build runs, and the end of that build ----------------------------------- + const holdAgain = await api('request_build', { targets: ['recipes/hold'] }); + await until(async () => (await api('build_request', { request: holdAgain.id })).state === 'running', 'hold running again', 300); + await hash('map/edit%3Arecipes%2Ffit-a'); + await press(byKey('editor:recipes/fit-a:description')); + await send('Input.insertText', { text: 'Typed while a build runs' }); + await pause(4500); + const kept1 = await evaluate(`({ key: document.activeElement.dataset.key, value: document.activeElement.value, caret: document.activeElement.selectionStart })`); + assert.deepEqual(kept1, { key: 'editor:recipes/fit-a:description', value: 'Typed while a build runs', caret: 24 }, 'Typing and focus outlive the two-second refresh'); + await api('cancel_build', { request: holdAgain.id }); + await until(async () => !['queued', 'running'].includes((await api('build_request', { request: holdAgain.id })).state), 'hold cancelled'); + await pause(3000); + await send('Input.insertText', { text: '.' }); + const kept2 = await evaluate(`({ key: document.activeElement.dataset.key, value: document.activeElement.value })`); + assert.deepEqual(kept2, { key: 'editor:recipes/fit-a:description', value: 'Typed while a build runs.' }, 'Typing and focus outlive the end of the build'); + await press(byKey('edit:recipes/fit-a:discard')); await press(byKey('edit:recipes/fit-a:discard:confirm')); + await until(() => evaluate(`document.querySelector('#aside [data-key="editor:recipes/fit-a:description"]').value === '' && document.querySelector('#aside header .umark').textContent === ''`), 'the typing discarded'); await settled('typing discarded'); + check('Typed into fit-a\'s description while a build ran: the text, focus and caret outlived two refreshes and the end of the build; Discard edit dropped the typing'); + + // ---- Train: Planned first --------------------------------------------------------------------------------------------------- + await hash('train'); + const planned = await evaluate(`[...document.querySelectorAll('#main .rows.planned > li')].map(li => li.innerText.replace(/\\n/g, ' '))`); + assert.ok(planned.some(t => t.includes('Early fit, run again') && t.includes('draft')), 'The draft is planned: ' + JSON.stringify(planned)); + const toBuild = await evaluate(`[...document.querySelectorAll('#main .sect h2')].map(e => e.textContent)`); + assert.equal(toBuild[0], 'Planned'); assert.equal(toBuild[1], 'To build'); + const twice = await evaluate(`(() => { const keys = [...document.querySelectorAll('#main .row.todo')].map(b => b.dataset.key); return keys.filter((k, i) => keys.indexOf(k) !== i); })()`); + assert.deepEqual(twice, [], 'No model listed twice'); + await shots('train-planned'); + check('Train lists Planned first: ' + planned.map(t => t.slice(0, 50)).join(' | ')); + // ---- A session that may only inspect: no control is drawn --------------------------------------------- await send('Page.navigate', { url: 'about:blank' }); await send('Network.clearBrowserCookies'); @@ -433,12 +705,15 @@ with open(os.path.join(out, 'weights.json'), 'w') as handle: const cookies = (await send('Network.getCookies', { urls: [origin + '/'] })).cookies.filter(c => c.name === 'tuldok_session'); assert.deepEqual(cookies.map(c => c.value === inspector), [true], 'The browser holds the inspector\'s credential alone'); const seen = []; - for (const place of ['map/recipes%2Ffit-b', 'train', 'train/request:' + fitAsk.id, 'train/request:' + holdId, 'train/run:' + holdRun.id, 'train/env:environments%2Flab-cpu', 'train/plan:recipes%2Ffit-b', 'overview']) { + for (const place of ['map/recipes%2Ffit-b', 'map/edit:recipes%2Ffit-b', 'map/branch:recipes%2Fslow', 'map/' + encodeURIComponent(broken), 'data/edit:datasets%2Fnumbers', 'overview/edit:charts%2Frollout-ranking', 'train', 'train/request:' + fitAsk.id, 'train/request:' + holdId, 'train/run:' + holdRun.id, 'train/env:environments%2Flab-cpu', 'train/plan:recipes%2Ffit-b', 'overview']) { await open(place); assert.equal(await evaluate(`document.getElementById('session-identity').textContent`), 'A browser check inspector · agent'); if (place === 'train') { await press('#needs-btn'); await until(() => evaluate(`!document.getElementById('needs-panel').hidden`), 'Needs you'); } const drawn = await evaluate(`[...document.querySelectorAll('button.act, #aside input[type="checkbox"], .act-field')].filter(e => e.offsetParent !== null || e.closest('#needs-panel')).map(b => b.textContent || b.type)`); assert.deepEqual(drawn, [], 'No control for an inspector on ' + place); + // T22: no editor, no branch form, no draft, no Edit, Branch from here, Keep, Save or Remove, and a list that opens nothing. + const editing = await evaluate(`({ editor: !!document.querySelector('#aside .editor, #aside .branch'), labels: [...document.querySelectorAll('button')].filter(b => b.offsetParent !== null).map(b => b.textContent).filter(t => ['Edit', 'Branch from here', 'Keep', 'Save', 'Remove', 'Discard edit', 'Discard', 'Create', 'Pick on the map'].includes(t)), drafts: document.querySelectorAll('.tree-map .node.draft').length, rows: document.querySelectorAll('#main .ov-defs button.row').length })`); + assert.deepEqual(editing, { editor: false, labels: [], drafts: 0, rows: 0 }, 'No editing for an inspector on ' + place); seen.push(place); } await shot('light-inspector-overview'); diff --git a/tests/test_tuldok_project_http.py b/tests/test_tuldok_project_http.py index dae01fae..9d93f4fe 100644 --- a/tests/test_tuldok_project_http.py +++ b/tests/test_tuldok_project_http.py @@ -48,6 +48,7 @@ '/project-workspace/tree.js': 'text/javascript', '/project-workspace/screens.js': 'text/javascript', '/project-workspace/actions.js': 'text/javascript', + '/project-workspace/editor.js': 'text/javascript', '/project-workspace/tabs.js': 'text/javascript', '/project-workspace/app.js': 'text/javascript', '/static/vendor/ubuntu-sans/UbuntuSans[wdth,wght].ttf': 'font/ttf', From 37a57b6d8f67a28de899523e45b32e0d1ed7d15c Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 12 Nov 2026 15:59:34 -0700 Subject: [PATCH 050/131] docs(plan): record Map phase 3 in the ledger Co-Authored-By: Claude Fable 5.2 --- .../execution-ledger.md | 54 +++++++++++++++++++ 1 file changed, 54 insertions(+) diff --git a/docs/plans/definition-first-projects/execution-ledger.md b/docs/plans/definition-first-projects/execution-ledger.md index 1ce1dbd2..d6b2a22b 100644 --- a/docs/plans/definition-first-projects/execution-ledger.md +++ b/docs/plans/definition-first-projects/execution-ledger.md @@ -459,3 +459,57 @@ Tuldok project tests: 561, about 4 minutes. The browser check passes on its fixt **On the owner's machine.** A preview of the committed page runs from an export of the commit in `workspace/scratch/tuldok-preview` on port 8092, on the owner's database, catalog and project directory; the older page still runs on port 8091. **Next:** phase 3, acting from the page, after the owner has looked at phase 2. + +## 2026-11-12 — the Map workspace, phase 3: acting from the page + +Spec: [spec-w3.md](spec-w3.md). The owner looked at phase 2 and said to continue ("its ok so far, continue"). + +**Commits** (none pushed), Tuldok `feat/definition-first-projects`: spec `b15c979d`; the core additions `0864c98c`; the build controls `a7ed05ea`; the editor, branching, the idle refresh and the acceptance script `597452df`. + +| Slice | What | +| --- | --- | +| T20 | operations `draft_branch` (writes a new recipe from one of the project's, storing nothing, with the parent's settings file carried as its own settings and the problems keeping it would find) and `revert_definition` (the folder's file back in place of an unsaved edit or a removal; a definition never saved is dropped); `map` says which models are unsaved and dates a model without a `trained_at` label by the run of its current product; commands `branch` and `revert`; 41 operations | +| T21 | `static/project-workspace/actions.js`: who may use a control, one way to call a changing operation (waiting, the two-press state, typed text and the refusal survive every redraw), the plan view, the conflict panel, Needs you and the strip's Save; Train: Plan build, a request's Approve, Decline with a reason and Cancel, a run's Cancel and Stop, an environment's Check again, Connect and Disconnect; the live run (hairline, progress line, both logs read on) | +| T22 | `static/project-workspace/editor.js`: the editor (text for every kind, form for recipes), Pick on the map, Branch from here with drafts kept in the page and drawn hollow and dashed, the steps from draft to built, the Overview's list of every definition; Train's Planned section | + +Tuldok project tests: 585 (561 before), about 4 minutes; the kept agent interface tests 44 pass (4 skipped). The pinned digests did not change: none of them is of the `project_folder` profile, which is checked against the operations table. + +**Browser checks.** `tests/browser_project_workspace_actions.cjs` (new, about 1 min 45 s): on a fixture copy in a Git repository of its own with stand-in commands, every control of the spec's section 4 as the owner, fourteen refusals provoked on purpose, and with a credential that may only inspect no control drawn. `tests/browser_project_workspace.cjs` (the read-only check) now signs the browser in with an inspect-only credential, because the owner's page has controls its assertions forbid; its assertions are unchanged, and it passes on its fixture and on the lab folder. + +**Acceptance run** (`tests/acceptance_project_workspace.cjs`, on a committed copy of `examples/tiny-project`, the owner's two interpreters, a throwaway database, a headless browser; everything after start-up done on the page): + +| Step | Result | +| --- | --- | +| Connect `environments/cpu` and `environments/gpu` from Train | ready: Python 3.12.3 and 3.14.7 | +| Plan everything buildable, Request build | 4 runs succeeded; while `small-net-a` trained the hairline of the strip and of the run drawer stood between 3 % and 19 % with "train: 200 of 6000" and the like | +| Branch from here on `small-net-a`, title, kind, description | a draft on the map after its parent, hollow and dashed, its form holding the parent's settings copied from `settings/small-net-a.json` | +| Updates 6000 to 3000 in the form, Keep, Save | `recipes/small-net-3-000-updates.json` in the folder with `derived_from`, `change` and `settings.updates` 3000 as a number | +| Plan build, Request build | trained on the GPU with its progress on the page; the model drawn built with its line from the parent, without a reload, dated by its run | +| The benchmark edited in the text view (a third subject), Keep, Save from the strip | the file is the text typed, byte for byte | +| An agent asks for `benchmarks/held-out` | the idle page counted it in Needs you by itself after 13 s; Approve there; 3 runs succeeded | +| Results | median error 0.0376 (6,000 updates), 0.0407 (3,000 updates), 0.871 (predict zero); all three on the Benchmarks tab | +| The whole run | no script error, no failed request; 1 min 40 s; two small trainings and three benchmark runs on the GPU | + +Screenshots: `build/qa/project-workspace-acceptance/final/` (21) and, for the owner's view of the lab folder at full size against the throwaway database with nothing kept or saved, `build/qa/project-workspace-acceptance/lab-owner-view/`: the map opens in 0.6 s, the editor of C53 in 0.2 s, a draft branched from C53 in 0.4 s, the lab's activity log empty afterwards and its folder unchanged. + +**Found at the acceptance run and changed:** + +- An idle page read again only when the window regained focus, so a build an agent asked for while the owner was looking at the page did not reach Needs you. The page now also asks again every fifteen seconds while nothing builds (summary, runs, build requests, status, environments: 13 to 60 ms each on the lab folder). +- Between two steps of a running build the strip said the request was queued. It now says a build is between two of its steps. +- A field with a hint beside one without (Short label and Group) stood at different heights. + +**Deviations from the spec, kept:** + +- `branch` does not take the other commands' `--keep` and `--discard` for a conflict; its own `--keep` stores the draft. +- Reverting a removed benchmark imports its results file again when it is still the file last imported; otherwise the next save would have deleted the file. +- A model that names a parent and has no date is drawn in the lane of its parent's branches, right after the parent, when it is in the parent's group. +- A never-built node is outlined in its kind's colour, not the accent, so the kind stays readable; a draft is labelled "new". +- Models branched and kept in this browser tab keep their steps list after they are built. +- The form writes the whole document again with the text's indentation: values and key order are kept, compact one-line objects are spread over lines. +- Environments on Train open a drawer for their controls; Decline takes two steps because its reason field opens on the first. + +**Not verified:** Stop what a run left running (it needs a run whose builder died); Save refused `changed-on-disk` (the opening import reports a changed file as a conflict first); widths other than 1440 by 900. The read-only check once stopped early on the lab folder while the full test suite ran beside it, and passed the next four times: it presses before a view has painted when the machine is loaded. + +**Seen, not Tuldok's:** this machine's zone is America/Vancouver, which the system clock gives as UTC−7 in November; the headless browser and Node carry older zone data and show times an hour earlier. A browser with current zone data shows the right hour. + +**Next:** the owner looks at phase 3 on the lab project. Then the capability check can be signed and the old project mode deleted (milestone 8, part 3). From 4f206bbd354abef63e28a2b2ac0a1175c15ce682 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 12 Nov 2026 18:19:39 -0700 Subject: [PATCH 051/131] docs(plan): the workspace updates in place; the deletion of the old mode specified; capability check brought up to date The owner looked at phase 3 of the Map workspace ("looks ok. continue") and reported a full redraw where the page should update in place. spec-w4.md records what was measured and the rules that repair it. spec-m8.md gains part 3, the deletion of the old project mode, prepared on a side branch until the capability check is signed. The check now reflects the Map workspace and what is still not covered. Co-Authored-By: Claude Fable 5.2 --- .../capability-check.md | 35 +++++---- .../definition-first-projects/spec-m8.md | 51 +++++++++++++ .../definition-first-projects/spec-w4.md | 74 +++++++++++++++++++ 3 files changed, 146 insertions(+), 14 deletions(-) create mode 100644 docs/plans/definition-first-projects/spec-w4.md diff --git a/docs/plans/definition-first-projects/capability-check.md b/docs/plans/definition-first-projects/capability-check.md index 6c0b55d5..03202a2d 100644 --- a/docs/plans/definition-first-projects/capability-check.md +++ b/docs/plans/definition-first-projects/capability-check.md @@ -1,17 +1,22 @@ # Capability check: what deleting the old project mode removes -**Status: written 2026-11-12 for the owner's sign-off. Not signed. Nothing is deleted until it is.** +**Status: written 2026-11-12 for the owner's sign-off, and brought up to date the same evening after the Map workspace was built and the owner had looked at it. Not signed. Nothing is deleted until it is.** The [plan](plan.md) deletes the old project-files mode in milestone 8 on one condition: a written check that lists every capability of that mode as covered, moved or deliberately dropped, signed off by the owner. This is that check. It is a list of what Tuldok can do today through `python app.py --project-files-root ...` and what happens to each thing when that mode is gone. ## The short answer -For what the lab uses a project for (definitions, runs, results, charts, environments), the new format covers it. Four things are not covered and would be gone from projects: +For what the lab uses a project for (definitions, runs, results, charts, environments), the new format covers it, and since 2026-11-12 it has its own interface: the Map workspace ([plan](workspace-plan.md)), with the tabs Map, Data, Train, Benchmarks, Analysis and Overview, from which builds are planned, requested and approved and definitions are edited, branched and saved. The owner looked at it on the lab project that day ("looks ok. continue") and reported one fault, a full redraw where the page should update in place, which [spec-w4.md](spec-w4.md) repairs. + +Five things are not covered and would be gone from projects: 1. **Annotated data inside a project.** Records, imports, annotation, review, saved searches, selections and frozen releases exist in the new format nowhere. They stay available in catalog mode, which this plan does not change. A project folder cannot hold them until the annotation plan is written. -2. **The interactive project page.** The old page browses data, the experiment graph, progressions and measurements. The new page shows the report only, until the workspace screens have their plan. +2. **Looking inside the data from the project page.** The old page lists a project's records. The Map workspace shows each dataset as a card with its state and size; the record browser, the volume viewer, field slices and the Annotate tab of the mockup are not built (the workspace plan left them out, for a later plan). 3. **Studies, trials and candidate selection** as records Tuldok keeps. A trial becomes a recipe; the grouping lives in labels and notes. -4. **Reading a run's files through the agent interface.** An agent can read a run's record, its progress and the end of its logs, but not fetch its weights or other outputs; those are files on the same machine. +4. **Producers and the built-in training graphs inside a project** (image generation, grounded review, caption and label proposals; the image, text and audio classifier trainings). Catalog mode keeps them. +5. **Reading a run's files through the agent interface.** An agent can read a run's record, its progress and the end of its logs, but not fetch its weights or other outputs; those are files on the same machine. + +Two more follow from the deletion itself: the lab's old project folder (`projects/rheon-model-portfolio-unified-04`, still on this disk, no longer tracked) can no longer be opened by Tuldok, and forks and composing of projects go (a Git branch is a fork). The old code stays in Git history. Nothing in the database is dropped: the old project's working copy stays in PostgreSQL, unread. ## What would be deleted @@ -21,11 +26,11 @@ For what the lab uses a project for (definitions, runs, results, charts, environ | The old project page and the extraction page, with their scripts and styles under `static/` | 3,263 lines in 10 files | | 145 `project_files.*` and 5 `project_transfer.*` operations in `agent_api.py`, the `project` capability profile, the two owner clients and their `mcp_stdio.py` flags | | | 74 test files that import one of those modules | 21,791 lines | -| The documentation of the old mode under `docs/contracts/` and its plans | | +| The documentation of the old mode under `docs/contracts/`, the runbooks and the READMEs. Its plans and ledgers under `docs/plans/` stay, as the record | | The 38 modules: `project_artifacts`, `project_cli`, `project_composition`, `project_custody`, `project_data`, `project_data_fork`, `project_dispatch`, `project_execution`, `project_extraction`, `project_files`, `project_fork`, `project_fork_composition`, `project_history`, `project_locks`, `project_material`, `project_material_fork`, `project_measurements`, `project_native_execution`, `project_native_preparation`, `project_native_process`, `project_producer_execution`, `project_producers`, `project_projection`, `project_record_dedupe`, `project_runtime`, `project_session`, `project_sources`, `project_store`, `project_study_execution`, `project_text`, `project_transfer`, `project_transfer_controller`, `project_validation_cache`, `project_validation_delta`, `project_working_store`, `project_workspace`, `retained_measurements`, `native_process_bootstrap`. -**What stays:** catalog mode and everything it uses, including `projects.py` and `project_activity.py` (catalog mode's read-only inspection of project snapshots with `--project-root`), the access layer, the agent registry and clients, and the new `tuldok_project` package. +**What stays:** every remaining operation's contract, unchanged; catalog mode and everything it uses, including `projects.py` and `project_activity.py` (catalog mode's read-only inspection of project snapshots with `--project-root`), the access layer, the agent registry and clients, and the new `tuldok_project` package. **Where the old code is tied to catalog mode.** Eight import lines in three files reach into the 38 modules, so they change before anything is deleted: @@ -41,7 +46,7 @@ The old mode has 150 operations. They are grouped here by what they do; each gro | Group | Operations | What it did | After deletion | | --- | --- | --- | --- | -| Opening, saving and files on disk | 11: `status`, `new`, `open`, `save`, `close`, `files_inspect`, `file_get`, `file_history`, `file_adopt`, `files_adopt`, `file_adopt_deletion` | Create, open, save and close a project; see and adopt files changed on disk; a file's history | **Covered**, differently. `open`, `save`, `status`, `check`, `resolve_conflict`. Files changed on disk are imported on the next operation. Nothing stays open, so there is no close. History is Git's. **Gap:** no command creates a new folder; one copies the example. A `new` command is added in milestone 8 | +| Opening, saving and files on disk | 11: `status`, `new`, `open`, `save`, `close`, `files_inspect`, `file_get`, `file_history`, `file_adopt`, `files_adopt`, `file_adopt_deletion` | Create, open, save and close a project; see and adopt files changed on disk; a file's history | **Covered**, differently. `open`, `save`, `status`, `check`, `resolve_conflict`. Files changed on disk are imported on the next operation. Nothing stays open, so there is no close. History is Git's. A new folder is made by `new` | | Forks and composing | 3: `save_as`, `compose`, `fork_info` | Copy a project to an independent fork; merge retained checkpoints of several projects | **Dropped**, as the plan decided: a Git branch is a fork | | Data records and annotation | 30: `query`, `get`, `import_text`, `annotate`, the `data_*` reads and imports for text, image, audio, mesh, point cloud, volume, sequence and scientific fields, `data_annotate`, `data_rights`, responses and preferences, `source_register`, `source_references` | Hold data records in a project, annotate and review them, record rights, responses and preference judgments | **Not covered. Catalog mode only.** The plan put annotation data out of scope; it needs its own plan before a project folder can hold it | | Selections, searches, releases | 11: `selections`, `selection_*`, `searches`, `search_*`, `release_preview`, `release_freeze` | Saved selections and searches over records; freezing a dataset release with its splits | **Not covered. Catalog mode only**, with the group above | @@ -49,7 +54,7 @@ The old mode has 150 operations. They are grouped here by what they do; each gro | Studies, trials, candidates, lineage | 17: `studies`, `study`, `study_create`, `study_save`, `trial`, `trial_prepare`, `candidate`, `candidate_select`, `lineage`, `lineage_record`, `progression`, `progression_origins`, `snapshot`, `evidence`, `package_state`, `publication_result`, `expose_holdout` | A study of trials with a budget; choosing a candidate; recorded lineage between runs; the progression view; recording that held-out test results were looked at | **Partly covered.** Lineage is the graph's edges; progression is a chart form ordered by `trained_at`; evidence is a recipe's card and its results. **Dropped:** studies, trials and budgets as records, candidate selection, snapshots, and the record of held-out exposure. The lab's 205 earlier models keep their study and trial origin as labels and cards | | Runs and execution | 24: `run`, `runs`, `run_document_segment`, `artifacts`, `artifact_status`, `artifact_resolve`, `execution_health`, the external preflight, approve, submit and cancel, the `execution_study_*` operations, `execution_reconcile_current`, `native_*` | Preflight, owner approval, submission, cancel, retry and recovery of runs; reading a run's documents and artifacts in pieces | **Covered:** `plan`, `request_build`, `approve_build`, `decline_build`, `cancel_build`, `build_requests`, `runs`, `run`, `progress`, `products`, `cancel_run`, `stop_run`. A retry is a new request. **Not covered:** reading a run's output files through the interface | | Producers | 8: `producers`, `producer`, `execution_producer_*`, `execution_generation_resume`, `execution_grounded_review` | Image generation, grounded review and caption or label proposals run inside a project | **Not covered. Catalog mode only** | -| Measurements and analysis | 9: `measurement_*`, `retained_analysis`, `retained_analysis_export` | Import result sets, query and compare them, inspect one observation with its evidence, export an analysis | **Covered:** `import_values`, `results_overview`, `results`, `values`, `chart` (ranking, tradeoff, progression, comparison), `report`. Summaries are rows in the database, not documents re-read per request. **Not covered:** the pointer from one observation back to its evidence file, and interactive charts | +| Measurements and analysis | 9: `measurement_*`, `retained_analysis`, `retained_analysis_export` | Import result sets, query and compare them, inspect one observation with its evidence, export an analysis | **Covered:** `import_values`, `results_overview`, `results`, `values`, `chart` (ranking, tradeoff, progression, comparison), `report`. Summaries are rows in the database, not documents re-read per request. On the page: the Benchmarks tab (accuracy against time with the frontier, error along the sequence, a compare set, the table of every fit) and the per-case values of the Analysis tab. **Not covered:** the pointer from one observation back to its evidence file | | Runtimes | 5: `runtime_sources`, `runtime_inspect`, `runtime_capture`, `runtime_status`, `runtime_abandon` | Capture a copy of a Python environment with a listing of its files | **Covered**, differently: `environments`, `environment`, `connect_environment`, `check_environment`, and `set-up` on the command line. Versions are checked; nothing is copied or listed per file | | Extraction from a catalog | 5: `project_transfer.*` | Stop a legacy catalog and extract it into a project | **Dropped.** The one project that needed converting is the lab, which its own script converts | @@ -59,19 +64,21 @@ Outside the operations: | --- | --- | | The old command line, `project_cli.py` | Replaced by `python -m tuldok_project` | | Opening the lab's old folder (`projects/rheon-model-portfolio-unified-04`) in Tuldok | Gone. The lab's converter reads that folder's files directly, and the old code stays in Git history | +| The old project page (`/project-files`), about twenty stacked form panels | Gone. The Map workspace is the project's interface | | Byte-identical save, receipts, custody and checkpoint proofs | Dropped, as the plan decided | ## Before deletion, in milestone 8 -These are done first, so the deletion removes nothing the lab still needs: +These come first, so the deletion removes nothing the lab still needs: -1. The lab's earlier weights and prepared inputs are adopted as products into Tuldok's per-project directory (owner decision, 2026-11-12: they stay on this machine and never go into Git). -2. The lab repository holds the new folder only, and the clean-install test of the plan's summary passes. -3. The eight import lines above are cut and catalog mode's tests pass. -4. A `new` command exists. +1. **Done.** The lab's earlier weights and prepared inputs are adopted as products into Tuldok's per-project directory (owner decision, 2026-11-12: they stay on this machine and never go into Git): 203 recipes' outputs and 25 datasets' training data, 16.9 GB. +2. **Done.** The lab repository holds the new folder only, and the clean-install test of the plan's summary passed on fresh clones. +3. **Done.** A `new` command exists. +4. **Done.** The Map workspace is built in three phases and the owner has looked at each. +5. **Part of the deletion.** The eight import lines above are cut and catalog mode's tests pass. ## Sign-off The owner signs by saying so; the date and the words are recorded here and in the ledger. -- [ ] I accept that projects lose annotated data, the interactive page, studies and trials, and reading run files through the interface, as listed above, and the old project mode may be deleted. +- [ ] I accept that projects lose annotated data, looking inside the data from the project page, studies and trials, producers and the built-in training graphs, reading run files through the interface, forks, and opening the lab's old folder, as listed above, and the old project mode may be deleted. diff --git a/docs/plans/definition-first-projects/spec-m8.md b/docs/plans/definition-first-projects/spec-m8.md index b9ebcf0f..ad726754 100644 --- a/docs/plans/definition-first-projects/spec-m8.md +++ b/docs/plans/definition-first-projects/spec-m8.md @@ -132,3 +132,54 @@ Found while implementing; the code and its tests follow this section. - **Tests that need the old folder** skip when it is absent, so a fresh clone's tests pass. **Acceptance: the plan's test, on a fresh clone.** A new clone of the lab branch, opened by Tuldok into an empty database with an empty project directory: it opens in seconds; it lists the models, recipes and benchmarks; the report draws the result charts from `results/` alone; and `plan --all` lists the ordered steps for what can be built. The clone holds no old project folder. + +## 10. Part 3: the old project mode is deleted + +**Gate.** The plan deletes nothing before the owner signs the [capability check](capability-check.md). This part is therefore prepared on a side branch, `chore/retire-old-project-mode`, in a working tree of its own, and reaches `feat/definition-first-projects` only on the owner's word. Until then that branch, the running old-mode app and the owner's database are as they were. + +**After this part** Tuldok has two ways to start: catalog mode, unchanged, and a project folder (`--project-folder`). `--project-files-root` and everything only it reaches is gone. + +### 10.1 What goes + +What the capability check lists, measured again when the work starts: + +- The 38 modules it names. +- `app.py`: the flags `--project-files-root`, `--project-runtime-source`, `--project-transfer-control` and `--project-transfer-root`, their routes, pages and error branches. `--project-root` (catalog mode's read-only look at project snapshots, `projects.py` and `project_activity.py`) stays. +- `candidate_packages.py` and `pipeline.py`: the branches for the old project objects. The one small function catalog mode also uses moves into `pipeline.py`. +- `agent_api.py`: the `project_files.*` and `project_transfer.*` operations, the `project` capability profile, `ProjectFilesOwnerClient` and `ProjectTransferOwnerClient`; `mcp_stdio.py`: `--project-files-owner` and `--project-transfer-owner`. +- `static/`: the old project page, the extraction page and the scripts and styles only they load. +- Every test file, fixture, fake and qualification script that exists for the old mode, and the steps of `.github/workflows/` that run them. +- `scripts/generate_project_files_contracts.py`, and what it generates. +- Under `docs/contracts/`, `docs/runbooks/`, `docs/reference/` and the READMEs: what describes the old mode as something Tuldok does. A document that covers both loses the old mode's part. + +### 10.2 What stays exactly as it is + +- **Every remaining operation's contract.** For each operation id still offered, the entry in the capability manifest of the `catalog` and of the `project_folder` profile (versions, digests, schemas) is the same before and after, byte for byte. Where a catalog operation's contract is built from an old operation's (as `graphs.create` is from `project_files.graph_create`), the shared shape is kept under a name of its own. The ids that disappear are exactly those beginning `project_files.` and `project_transfer.`. Asking for the `project` profile is refused as unsupported. +- **Catalog mode's behaviour**, its pages and its tests. +- **`tuldok_project/`, the Map workspace and their tests.** Not touched. +- **The database.** Nothing is dropped, migrated or rewritten. The old project's schemas stay where they are, unread. +- **`docs/plans/`.** The plans and ledgers of the old mode are the record of what was built; they stay. (The capability check said they would go; keeping them deletes less.) +- **The lab repository.** Not touched. + +### 10.3 Order + +1. **Baseline, before any change:** the capability manifests of both profiles saved to a scratch file; the whole Python suite run once with its counts (passed, failed, skipped) and time; the remaining suites' names. +2. **Cut the eight import lines** (`app.py`, `candidate_packages.py`, `pipeline.py`) and remove what they served. Catalog mode's tests pass. +3. **Delete** modules, operations, clients, flags, pages, tests, scripts, workflow steps, documents. +4. **Look for what is left:** no import of a deleted module; outside `docs/plans/` and Git history, no mention of `project_files`, `project-files`, `project_transfer`, `project-transfer`, `--project-files-root` or a deleted module's name. + +### 10.4 Done when + +| Check | Passes when | +| --- | --- | +| Contracts | a script compares the saved manifests with the new ones as 10.2 says and prints the ids removed | +| Python suite | `python -m unittest discover -s tests` passes; its count is the baseline's less the tests of the deleted files; no test that passed before fails or is newly skipped | +| Project suite | the `test_tuldok_project_*.py` count is unchanged | +| JavaScript | every remaining `tests/test_*.cjs` passes; `node --check` on every remaining script under `static/` | +| Browser | the workspace checks pass on their fixture and on the lab folder read only; the catalog-mode browser checks that the workflow runs and that need no download or GPU pass, and those not run are named | +| Start-up | `python app.py --help` shows none of the removed flags; a removed flag is an argument error; Tuldok starts in catalog mode on an empty data directory and with `--project-folder` on the tiny example | +| Size | the lines and files removed, by kind, reported beside the capability check's figures | + +### 10.5 Landing + +On the owner's sign-off: their words and the date go into the capability check and the ledger; the old-mode app left running on port 8091 for comparison is stopped (its pages would be gone from under it); the side branch is brought onto `feat/definition-first-projects` without rewriting that branch's history. Nothing is pushed. diff --git a/docs/plans/definition-first-projects/spec-w4.md b/docs/plans/definition-first-projects/spec-w4.md new file mode 100644 index 00000000..95119d9e --- /dev/null +++ b/docs/plans/definition-first-projects/spec-w4.md @@ -0,0 +1,74 @@ +# Implementation spec: the workspace updates in place + +This continues [spec-w3.md](spec-w3.md). Section 1 of [spec-m1-m2.md](spec-m1-m2.md) (rules for implementers) applies. It changes the page only: `static/project-workspace/`, one new browser check, and the paragraph of `docs/contracts/project-folder.md` that says when the page reads. No operation, no format and no server code changes. + +**Owner's report, 2026-11-12, on looking at phase 3:** "there is a full page reset when it should just be updating info on the page instead". + +## 1. What was measured + +The lab folder (206 models), owner signed in, nothing in the project changing. "Rebuilt" counts the elements of the main area that are new nodes afterwards. + +| Tab | On return to the window | Every 15 s while idle | +| --- | --- | --- | +| Map (also with a model open, and with the editor open) | nothing | nothing | +| Data | all 356 rebuilt | nothing | +| Train | all 64 rebuilt | all 64 rebuilt | +| Benchmarks | all 2,109 rebuilt | nothing | +| Analysis | all 159 rebuilt | nothing | +| Overview | all 2,336 rebuilt | all 2,336 rebuilt | + +In every rebuild the sideways scroll of the tables inside the main area went back to the start. The tab bar was rebuilt with each of them, and the status strip was rebuilt on every reading on every tab. The answers themselves were identical between readings (`summary`, `status`, `build_requests`, `environments`, `runs`, `map`, `definitions`, `products`, `activity`). + +The causes, in `app.js`: returning to the window forgets every kept answer and redraws any tab but Map; the reading every 15 seconds (added at phase 3's acceptance) redraws Train and Overview whether or not anything changed; `render()` rebuilds the tab bar; `strip()` rebuilds the strip. And a drawer that is read again is emptied to "Reading…" first. + +## 2. The rules + +**R1. One way of reading again.** The page reads again in three cases: on its timer (every 2 seconds while a build is queued or running, every 15 otherwise), when the window regains focus, and after a control's answer. Each asks again for what the page watches: `summary`, `status`, `build_requests`, `environments` and `runs` (each with no arguments), and `map` as well on focus, after a control's answer, when a run or a request ended, and when `status` changed. Nothing kept is forgotten first. The adapter asks, and compares the text of each answer with the text of the kept one: an equal answer leaves the kept object as it is. + +**R2. Nothing changed: nothing is redrawn.** When every watched answer is equal to the kept one, the page touches no element of the tab bar, the strip, the main area, the drawer or Needs you. One exception: the time in the strip's "Read at" is replaced, as text, when its minute changes. + +**R3. Something changed: what is on screen is brought up to date, in place.** Every kept answer that is not watched is forgotten, so it is read again when next needed. Then: + +- the strip is redrawn, and Needs you when it is open; +- the main area of the tab on screen is built off the page from fresh answers and put in place in one step; +- an open drawer is built off the page the same way and put in place in one step, except a drawer that holds the editor or the branch form, which a reading on the timer or on focus never touches (what is typed there stays; the server reports a conflict on Keep or Save, as now). + +"Reading…" is shown only for a tab or a drawer subject that is not on screen yet. A control's answer always counts as a change. + +**R4. What putting in place keeps.** The scroll of the main area in both directions; the scroll of every scrolling element inside the main area and inside the drawer (matched by its place in the tree: the same path of child indexes and the same tag); the drawer's own scroll; the focus and the caret, by `data-key` as now; whether Needs you is open; the selection on the map and in the lists. + +**R5. The tab bar is built once.** Changing tab sets `aria-current` on the links that exist. + +**R6. The map.** An unchanged `map` answer never rebuilds the tree (as now). A changed one rebuilds it in one step and keeps the scroll of the map and of the list, and the selection. + +**R7. Live progress stays as it is.** While a run runs, the strip's hairline and its sentence, and the open run's progress and logs, are updated on each reading. Progress alone never redraws the main area. + +**R8. The person's own actions redraw as now.** A sort, a filter, a tab, a selection: the tab draws again at once, by the same putting in place (R4). + +## 3. Parts + +**`adapter.js`.** Each kept answer is kept with its text. `again(names)` asks again for the kept answer of each named operation with no arguments (asking for the first time when none is kept) and resolves to the names whose answer differs from the kept one; for those the kept answer is replaced. A refusal with code `conflict` is thrown (the page shows the conflict panel, as now); another refusal drops the kept answer and counts as a change. `forgetBut(names)` forgets every kept answer whose operation is not named. `map()` keeps returning the same shaped object while the raw answer is the same object. + +**`app.js`.** `poll`, `again` and the reading part of `changed` become one routine following R1 to R3. The strip is drawn by parts that are updated only when their content differs. `render()` no longer touches the tab bar beyond R5. + +**`tabs.js`.** `swap` keeps what R4 lists. `drawer(aside, id, load, build)` keeps the content on screen while it reads the same subject again, and replaces it in one step. + +**`screens.js`, `actions.js`, `editor.js`.** The model's drawer, the plan view and the steps of a new model follow the same rule: read again for the subject already shown, they stay on screen until the new content is complete, then are replaced in one step with the drawer's scroll kept. The map keeps its scroll when rebuilt (R6). + +No element is kept from an older drawing when its content is drawn again: what is replaced is replaced whole, so a control never acts on answers older than the ones it was drawn from. + +## 4. The check + +A new `tests/browser_project_workspace_still.cjs`, on the same fixture as `browser_project_workspace_actions.cjs` (owner signed in, stand-in commands, no GPU) and, with `--lab-root`, on a real folder read only. It counts added and removed nodes with a `MutationObserver` on the tab bar, the strip, the main area, the drawer and Needs you, marks the elements on screen so new ones can be told apart, and samples the page every 50 ms for "Reading…". + +1. **Nothing changed.** On every tab, and with a model's drawer, a run's drawer, a build request's drawer, a dataset's drawer, the plan view and the editor open: after the window regains focus, no node is added or removed anywhere and every scroll position is what it was (main, sideways tables, the map, the list, the drawer). On Train and on Overview the same holds across one reading on the 15-second timer. Needs you open stays open and untouched. +2. **Something changed elsewhere.** With the page on Train, scrolled, and a control focused, a second session asks for a build (so it awaits approval): within one reading the strip's count and the Train list show it, "Reading…" is never shown, the scroll and the focus are what they were. With that request's drawer open, the second session approves it: the drawer shows the new state without ever showing "Reading…" and keeps its scroll. +3. **A build runs.** While the stand-in build runs, the hairline moves and the open run's drawer updates; the main area of the Map tab gains no node until the run ends, and then the model is drawn built with the map's scroll kept. +4. **The editor is left alone.** With text typed into a field of the editor and not kept, a change elsewhere (step 2's request) does not touch the drawer: the typed text and the caret are there. +5. The three existing browser checks pass unchanged in what they assert. + +With `--lab-root` only step 1 runs, and nothing is asked of the project that changes it. + +## 5. Out of scope + +Patching single values inside a tab's content (only the nodes that differ): a tab whose answers changed is replaced whole, in one step. Server-side change tokens. Any change of what a tab shows. From ac50ea56eeb27d121c759c1d1c97151fd94db874 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 12 Nov 2026 19:22:35 -0700 Subject: [PATCH 052/131] fix(app): the workspace updates in place instead of redrawing itself MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The owner reported a full page reset where the page should update the information on it. Measured on the lab folder with nothing changing: Train and Overview rebuilt every element every fifteen seconds, every tab but Map rebuilt on each return to the window, the tab bar and the strip on every draw, and sideways scroll was lost each time. The page now reads again in one way (timer, focus, a control's answer), compares each watched answer with the one it holds and touches nothing when none differs. When one does, the tab and the open drawer are built off the page and put in place in one step, keeping every scroll position and the focus; Reading… shows only for something not on screen yet. The progress of a running run and the time of the last reading are set in place. A reading that fails leaves the page as it is and the strip says so. An open editor or branch form is left alone by a timer or focus reading. tests/browser_project_workspace_still.cjs counts what the page touches: nothing, on every tab and with each drawer open, on the fixture and on the lab folder. The controls check now waits for the page's own requests before it asserts. Co-Authored-By: Claude Fable 5.2 --- docs/contracts/project-folder.md | 12 +- .../definition-first-projects/spec-w4.md | 28 +- static/project-workspace/actions.js | 24 +- static/project-workspace/adapter.js | 52 ++- static/project-workspace/app.js | 292 +++++++----- static/project-workspace/editor.js | 31 +- static/project-workspace/screens.js | 104 +++-- static/project-workspace/tabs.js | 87 ++-- tests/browser_project_workspace_actions.cjs | 13 +- tests/browser_project_workspace_still.cjs | 417 ++++++++++++++++++ 10 files changed, 854 insertions(+), 206 deletions(-) create mode 100644 tests/browser_project_workspace_still.cjs diff --git a/docs/contracts/project-folder.md b/docs/contracts/project-folder.md index a4298d87..ed683dd2 100644 --- a/docs/contracts/project-folder.md +++ b/docs/contracts/project-folder.md @@ -1774,7 +1774,17 @@ The page at `/` is the Map workspace: the tabs Map, Data, Train, Benchmarks, Analysis and Overview over the project, read through the operations below. Each of its controls calls one operation and is drawn only for a session that may call it, so a credential that may only inspect sees a page that changes -nothing. The report is linked from the Overview tab. +nothing. The report is linked from the Overview tab. The page reads again +every two seconds while a build is queued or running and every fifteen +seconds otherwise, when its window regains focus, and after a control's +answer: it asks again for `summary`, `status`, `build_requests`, +`environments` and `runs` (and `map`, except on the timer unless a run or a +request ended or `status` changed) and compares each answer with the one it +holds. When none differs nothing on the page is drawn again but the time it +was read and the progress of a running build; when one does, what is on screen is drawn again in place, keeping +the scroll and the focus, and a drawer holding the editor or the branch form +is left alone except after a control's answer. A reading that fails leaves +the page as it is; the status strip says the project was not read, and why. ### Signing in and issuing an agent credential diff --git a/docs/plans/definition-first-projects/spec-w4.md b/docs/plans/definition-first-projects/spec-w4.md index 95119d9e..6c6813c2 100644 --- a/docs/plans/definition-first-projects/spec-w4.md +++ b/docs/plans/definition-first-projects/spec-w4.md @@ -41,13 +41,13 @@ The causes, in `app.js`: returning to the window forgets every kept answer and r **R6. The map.** An unchanged `map` answer never rebuilds the tree (as now). A changed one rebuilds it in one step and keeps the scroll of the map and of the list, and the selection. -**R7. Live progress stays as it is.** While a run runs, the strip's hairline and its sentence, and the open run's progress and logs, are updated on each reading. Progress alone never redraws the main area. +**R7. Live progress stays as it is.** While a run runs, the strip's hairline and its sentence, the open run's progress and logs, and the progress line of the run's row in Train's list are updated on each reading, as text and width set in place. Progress alone never redraws the main area. **R8. The person's own actions redraw as now.** A sort, a filter, a tab, a selection: the tab draws again at once, by the same putting in place (R4). ## 3. Parts -**`adapter.js`.** Each kept answer is kept with its text. `again(names)` asks again for the kept answer of each named operation with no arguments (asking for the first time when none is kept) and resolves to the names whose answer differs from the kept one; for those the kept answer is replaced. A refusal with code `conflict` is thrown (the page shows the conflict panel, as now); another refusal drops the kept answer and counts as a change. `forgetBut(names)` forgets every kept answer whose operation is not named. `map()` keeps returning the same shaped object while the raw answer is the same object. +**`adapter.js`.** Each kept answer is kept with its text. `again(names)` asks again for the kept answer of each named operation with no arguments (asking for the first time when none is kept) and resolves to the names whose answer differs from the kept one; for those the kept answer is replaced. When any of them is refused or does not arrive, the error is thrown and nothing kept is replaced: a refusal with code `conflict` shows the conflict panel, as now; anything else leaves the page as it is, the strip says the project was not read and why, and the page asks again on its timer. (First written as "another refusal drops the kept answer and counts as a change"; that emptied the tab on screen whenever the server could not be reached for a moment.) `forgetBut(names)` forgets every kept answer whose operation is not named. `map()` keeps returning the same shaped object while the raw answer is the same object. **`app.js`.** `poll`, `again` and the reading part of `changed` become one routine following R1 to R3. The strip is drawn by parts that are updated only when their content differs. `render()` no longer touches the tab bar beyond R5. @@ -63,12 +63,32 @@ A new `tests/browser_project_workspace_still.cjs`, on the same fixture as `brows 1. **Nothing changed.** On every tab, and with a model's drawer, a run's drawer, a build request's drawer, a dataset's drawer, the plan view and the editor open: after the window regains focus, no node is added or removed anywhere and every scroll position is what it was (main, sideways tables, the map, the list, the drawer). On Train and on Overview the same holds across one reading on the 15-second timer. Needs you open stays open and untouched. 2. **Something changed elsewhere.** With the page on Train, scrolled, and a control focused, a second session asks for a build (so it awaits approval): within one reading the strip's count and the Train list show it, "Reading…" is never shown, the scroll and the focus are what they were. With that request's drawer open, the second session approves it: the drawer shows the new state without ever showing "Reading…" and keeps its scroll. -3. **A build runs.** While the stand-in build runs, the hairline moves and the open run's drawer updates; the main area of the Map tab gains no node until the run ends, and then the model is drawn built with the map's scroll kept. +3. **A build runs.** While the stand-in build runs, the hairline moves, the open run's drawer updates, and the run's row in Train's list shows its latest progress with no node added or removed; the main area of the Map tab gains no node until the run ends, and then the model is drawn built with the map's scroll kept. 4. **The editor is left alone.** With text typed into a field of the editor and not kept, a change elsewhere (step 2's request) does not touch the drawer: the typed text and the caret are there. -5. The three existing browser checks pass unchanged in what they assert. +5. **A reading fails.** Cut off from the server, the page keeps what it shows and the strip says the project was not read; when the server answers again the strip says where the project stands, and nothing else was touched. +6. The existing browser checks pass unchanged in what they assert. With `--lab-root` only step 1 runs, and nothing is asked of the project that changes it. ## 5. Out of scope Patching single values inside a tab's content (only the nodes that differ): a tab whose answers changed is replaced whole, in one step. Server-side change tokens. Any change of what a tab shows. + +## As built + +What differs from the text above, and what was found while building it. + +- **Needs you is redrawn only when what it lists differs.** R3 says it is redrawn whenever something changed and it is open; it is drawn again when its items (kind, key and sentence of each) or the signed-in identity differ, and when it is opened. A reading that changed something else leaves it untouched. +- **The map is rebuilt in the page, not off it.** R6's rebuild runs synchronously in the main area (the lane map needs its container on the page to measure itself), so it is one step for the viewer; the scroll of the map and of the list is put back when the filters are the same, and a new selection or a change of filter or zoom still scrolls to the selected model as before. An unchanged tree draws only a selection that differs (it used to redraw the comparison and input arcs on every render). +- **The model's drawer, read again, waits for every block** (Results, Runs and product, Uses, Card and the steps of a new model) before it is put in place; `steps()` in `editor.js` now returns its promise and fills its box whether or not it is on the page yet. The Benchmarks tab passes its Compare buttons to `inspectorModel` so that a drawer put in place later carries them. +- **The report** (Overview → Open the report) keeps the frame on screen while it reads again and puts the new one in its place; "Reading…" only the first time. +- **After a control's answer** `press()` (`actions.js`) forgets what is not watched before its `done` step, instead of every kept answer, so that the watched answers can be compared by the reading that follows. A view `done` opens (a new build request, say) is drawn from fresh answers for its own subject; the tab's lists may show the watched answers of a moment earlier until that reading, which follows at once, puts them in place. +- **A refusal reads again as on focus** (the watched answers and `map`, no forced change); it used to recompute from the kept answers without asking. +- **When the open run ends** its drawer is no longer emptied: the reading that follows (as after a control's answer) draws it again in place. +- **One reading at a time.** A timer, focus or control reading that arrives while one runs waits for it; of several waiting, the strongest cause is kept (control over focus over timer). +- **Two things are set in place on every reading though nothing changed** (found in review: as first built they went stale until a watched answer changed): the progress line of a running run's row in Train's list (`S.progress` in `tabs.js`: the hairline's width and the line's text; the row's first progress replaces its one line) and the "Read at" time on the Overview tab. `app.js` reads the latest progress of every running run on each reading. +- **A reading that fails changes nothing** (found in review). `again()` asks for all the named answers before it replaces any, and throws when one is refused or does not arrive. The page then keeps everything on screen, the strip says "Not read" with the reason and the time of the last reading that succeeded, and the timer asks again. When the failed reading followed a control's answer, the next one that succeeds counts as a change. +- **Needs you's key** also holds the references behind an item, so its controls are never older than its sentence. +- **`docs/contracts/project-folder.md` had no paragraph on when the page reads;** two sentences were added to the paragraph that describes the page. +- **The controls check waits for the page's requests.** `tests/browser_project_workspace_actions.cjs` asserted the editor's header the moment a control stopped being busy; the drawer is now drawn again by the reading that follows, a few milliseconds later, and the check failed twice in a row on a busy machine. Its `settled()` now also waits until the page has no call of the project in flight. No assertion changed. +- **The check** (`tests/browser_project_workspace_still.cjs`) waits for a reading by the page's own requests (the watched operations answered after a moment, then nothing asked for 700 ms), and changes the viewport height for two sub-steps so that the request's drawer, the map and the list scroll on the small fixture. It counts attribute and text changes as well as nodes; in step 1 every one is zero except the "Read at" text. Once, before the viewport for step 3 was made shorter, the list's scroll was found clamped by the browser (43 to 9 px) before the map was rebuilt: the list's scroll range shrank when the run ended, so the page had no larger value to put back. The cause of the layout change was not found (the strip's height was the same before and after in the run that measured it). diff --git a/static/project-workspace/actions.js b/static/project-workspace/actions.js index 1b4035bc..29dbd259 100644 --- a/static/project-workspace/actions.js +++ b/static/project-workspace/actions.js @@ -6,8 +6,8 @@ // two-press "Confirm" state, typed text, the last refusal), and the views // built of them: the plan view, the conflict panel, the controls of Needs // you and the strip's Save. A control calls one operation; while it waits it -// is disabled and says so; when the answer comes every kept answer is -// forgotten and the page reads again (hooks.changed, set by app.js); a +// is disabled and says so; when the answer comes what it can have changed +// is forgotten and the page reads again (hooks.changed, set by app.js); a // refusal is shown under the control in the server's words, with its // problems listed. Nothing is retried on its own. Text goes in through text // nodes only. @@ -137,7 +137,7 @@ window.LabActions = (() => { s.confirming = null; s.text = {}; refill(key); // local: nothing in the project changed, so nothing is read again. if (it.local) { if (it.done) it.done(result); return; } - P.forgetAll(); + P.forgetBut(P.WATCHED); // what it can have changed is read afresh; the watched answers are read again by hooks.changed and compared if (it.done) it.done(result); await hooks.changed({ key, item: it, result, focus: key + ':' + it.id }); } @@ -262,16 +262,18 @@ window.LabActions = (() => { /** * The plan view in the drawer, for sel 'plan:,' or * 'plan:*' (everything buildable): read with `plan`, shown in sentences, - * with the scratch box and Request build. back(): leaves the view. + * with the scratch box and Request build. back(): leaves the view. Read + * again for the plan on screen (aside._again), it stays until the new one + * is built off the page and put in its place in one step. */ function planView(aside, sel, go, back) { - if (aside._for === sel) return; - aside._for = sel; aside.textContent = ''; + if (aside._for === sel && !aside._again) return; + const S = window.LabScreens, same = aside._for === sel && !!aside.firstChild, mine = S.parts.turn(aside), live = () => aside._turn === mine && aside._for === sel; + aside._for = sel; const every = sel === 'plan:*', targets = every ? [] : sel.slice(5).split(',').filter(Boolean); - aside.appendChild(h('p', 'note', 'Reading…')); + if (!same) { aside.textContent = ''; aside.appendChild(h('p', 'note', 'Reading…')); } P.read('plan', { targets, every }).then(plan => { - if (aside._for !== sel) return; - aside.textContent = ''; + if (!live()) return; const ins = h('div', 'inspector plan-view'); const hd = h('header'); hd.appendChild(h('span', 'kicker', 'plan · nothing runs until it is requested')); const title = h('h2', null, every ? 'A build of everything buildable' : 'A build of ' + plan.targets.join(', ')); title.tabIndex = -1; hd.appendChild(title); @@ -311,8 +313,8 @@ window.LabActions = (() => { args: st => ({ targets, every, scratch: !!st.text.scratch }), done: r => go('train', 'request:' + r.id) }])); ins.appendChild(h('p', 'note', isAgent() ? 'The owner approves or declines what you ask for; nothing runs before.' : 'Your request is queued at once and runs when the build worker takes it.')); } - aside.appendChild(ins); - }, error => { if (aside._for !== sel) return; aside.textContent = ''; aside.appendChild(refusal(error)); }); + S.parts.putDrawer(aside, ins); + }, error => { if (live()) S.parts.putDrawer(aside, refusal(error)); }); } // ---- The conflict panel -------------------------------------------------------- diff --git a/static/project-workspace/adapter.js b/static/project-workspace/adapter.js index 10cf975e..36b73d07 100644 --- a/static/project-workspace/adapter.js +++ b/static/project-workspace/adapter.js @@ -5,9 +5,11 @@ // read again, and shapes what the screens read: the map's sections, models // and lines, the sentence of where the project stands, and what needs the // person. It reads on its own; an operation that changes the project is -// called only by a control the person pressed (actions.js), after which every -// kept answer is forgotten. A refusal is thrown as an Error carrying the -// server's code, problems, references and files. +// called only by a control the person pressed (actions.js). Reading again +// (again()) compares each answer's text with the kept one, so the page can +// leave alone what did not change; what is not watched is forgotten when +// something changed (forgetBut()). A refusal is thrown as an Error carrying +// the server's code, problems, references and files. window.TuldokProject = (() => { // Kinds of change, by the project format's names, with the brief's labels. const KINDS = [ @@ -59,15 +61,47 @@ window.TuldokProject = (() => { } catch (error) { contracts = null; throw error; } } - // Answers are kept by operation and arguments until forgotten. - const kept = new Map(); + // Answers are kept by operation and arguments until forgotten, each with its text, so a reading + // again can tell an answer that changed from one that did not. + const kept = new Map(); // key -> { answer: promise, text: the answer as JSON once it came } + const keyOf = (name, args) => name + ' ' + JSON.stringify(args); function read(name, args = {}) { - const key = name + ' ' + JSON.stringify(args); - if (!kept.has(key)) kept.set(key, call(name, args).catch(error => { kept.delete(key); throw error; })); - return kept.get(key); + const key = keyOf(name, args); + if (!kept.has(key)) { + const entry = { text: null }; + entry.answer = call(name, args).then(value => { entry.text = JSON.stringify(value); return value; }, error => { if (kept.get(key) === entry) kept.delete(key); throw error; }); + kept.set(key, entry); + } + return kept.get(key).answer; + } + /** + * Asks again for the kept answer of each named operation (no arguments), + * asking for the first time when none is kept, and resolves to the names + * whose answer differs from the kept one; for those the kept answer is + * replaced, and an equal answer leaves the kept object as it is. When any + * of them is refused or does not arrive, the error is thrown and nothing + * kept is replaced: a reading that failed changes nothing. + */ + async function again(names) { + const got = await Promise.all(names.map(async name => { + const key = keyOf(name, {}), had = kept.get(key); + const before = had ? await had.answer.then(() => had.text, () => null) : null; + const value = await call(name, {}); + return { name, key, had, before, value, text: JSON.stringify(value) }; + })); + const changed = []; + for (const g of got) { + if (g.before !== null && g.text === g.before && kept.get(g.key) === g.had) continue; + kept.set(g.key, { answer: Promise.resolve(g.value), text: g.text }); changed.push(g.name); + } + return changed; } function forget(names) { for (const key of [...kept.keys()]) if (names.includes(key.split(' ')[0])) kept.delete(key); } + /** Forgets every kept answer whose operation is not named. */ + function forgetBut(names) { for (const key of [...kept.keys()]) if (!names.includes(key.split(' ')[0])) kept.delete(key); } function forgetAll() { kept.clear(); } + // What the page watches: asked again on every reading ('map' on some, app.js), kept across a change. + const WATCHED = ['summary', 'status', 'build_requests', 'environments', 'runs', 'map']; // ---- The map ------------------------------------------------------------ /** @@ -216,5 +250,5 @@ window.TuldokProject = (() => { return out; } - return { KINDS, UNSET, kindLabel, stateWord, call, read, forget, forgetAll, map, setDrafts, trackName, better, units, standing, needs, titleOf, day }; + return { KINDS, UNSET, WATCHED, kindLabel, stateWord, call, read, again, forget, forgetBut, forgetAll, map, setDrafts, trackName, better, units, standing, needs, titleOf, day }; })(); diff --git a/static/project-workspace/app.js b/static/project-workspace/app.js index 311fb2da..2105eaf5 100644 --- a/static/project-workspace/app.js +++ b/static/project-workspace/app.js @@ -3,14 +3,20 @@ // routing by hash (#/), the status strip and Needs you, the // drawer, and when the project is read. The first screen reads summary and // map; the strip's other sources are read right after; a tab reads what it -// needs when it is first shown; everything is read again when the window -// regains focus and after a control's answer (actions.js). While a build is -// queued or running the strip asks again every two seconds for what can -// change, the open run reads on its progress and logs, and when a run ends -// the map and everything else is read again, so a model turns to built -// without a reload. While nothing builds it asks again every fifteen seconds, -// so a build an agent asks for shows in Needs you while the page is open. -// A read refused conflict shows the conflict panel. +// needs when it is first shown. The page reads again in one way (reread(), +// spec-w4.md): on its timer (every two seconds while a build is queued or +// running, every fifteen otherwise), when the window regains focus and after +// a control's answer (actions.js), asking again for what it watches (summary, +// status, build requests, environments, runs, and the map except on the +// timer unless a run or request ended or status changed). When no answer +// differs nothing is drawn again; only the progress of a running run (the +// strip's and its row's in Train's list) and the minute of "Read at" are set +// in place. When one does, what is not watched is forgotten and the strip, +// the tab and the open drawer are drawn again in place, keeping the scroll +// and the focus, so a model turns to built without a reload. The open run +// reads on its progress and logs on every reading. A reading that fails +// leaves the page as it is and the strip says so; a read refused conflict +// shows the conflict panel. (() => { const P = window.TuldokProject, S = window.LabScreens, A = window.LabActions; const TABS = [['map', 'Map'], ['data', 'Data'], ['train', 'Train'], ['benchmarks', 'Benchmarks'], ['analysis', 'Analysis'], ['overview', 'Overview']]; @@ -19,7 +25,7 @@ const $ = id => document.getElementById(id); const state = { screen: 'map', sel: {}, kinds: null, query: '', zoom: 1, track: false, ui: {}, benchmark: null, cmp: [] }; const data = { summary: null, map: null, standing: null, needs: null, status: null, readAt: '', polling: false }; - let failed = null, conflict = null, mapText = null, pollTimer = null, pollFast = false, states = null, opener = null; + let failed = null, conflict = null, pollTimer = null, pollFast = false, states = null, opener = null; const clock = () => new Date().toLocaleTimeString('en-GB', { hour: '2-digit', minute: '2-digit' }); function parse() { @@ -73,38 +79,75 @@ } // ---- The status strip and Needs you --------------------------------------- + // The strip is drawn by parts, each made again only when what it shows differs (spec-w4 R2): a reading + // that changed nothing touches no element of it but the text of "Read at", when its minute changes. + const parts = {}; // by name: { key, el } + const part = (name, key, make) => { const p = parts[name]; if (p && p.key === key) return p.el; const el = make(); parts[name] = { key, el }; return el; }; + const span = (cls, text) => Object.assign(document.createElement('span'), { className: cls, textContent: text }); + const setText = (node, text) => { if (node.data !== text) node.data = text; }; + function hairline(p) { + const hair = span('hair', ''), i = document.createElement('i'); i.style.width = Math.round(100 * p.completed / Math.max(1, p.total)) + '%'; hair.appendChild(i); + hair.title = p.stage + ' ' + p.completed + ' of ' + p.total; hair.setAttribute('role', 'progressbar'); hair.setAttribute('aria-valuemin', '0'); hair.setAttribute('aria-valuemax', String(p.total)); hair.setAttribute('aria-valuenow', String(p.completed)); + return hair; + } + /** The Needs you button: made once, its words, state and aria-expanded set when they differ. */ + function needsButton() { + if (!parts.needs) { + const b = document.createElement('button'); b.className = 'btn sm needs-btn'; b.type = 'button'; b.id = 'needs-btn'; b.dataset.key = 'needs-btn'; b.setAttribute('aria-controls', 'needs-panel'); + b.addEventListener('click', () => { const panel = $('needs-panel'); panel.hidden = !panel.hidden; b.setAttribute('aria-expanded', String(!panel.hidden)); fillNeeds(true); }); + parts.needs = { key: null, el: b }; + } + const b = parts.needs.el, text = 'Needs you · ' + (data.needs ? data.needs.length : '…'), open = String(!$('needs-panel').hidden); + if (b.textContent !== text) b.textContent = text; + if (b.disabled !== !data.needs) b.disabled = !data.needs; + if (b.getAttribute('aria-expanded') !== open) b.setAttribute('aria-expanded', open); + return b; + } function strip() { - const el = $('strip'); - keepFocus(el, () => { - el.textContent = ''; - if (failed) { el.appendChild(S.stateEl('serious', conflict ? 'Conflict' : 'Not read')); el.appendChild(Object.assign(document.createElement('span'), { className: 'msg', textContent: failed })); return; } - if (!data.standing) { el.appendChild(Object.assign(document.createElement('span'), { className: 'msg', textContent: 'Reading the project…' })); return; } - el.appendChild(S.stateEl(data.standing.tone, data.standing.word)); - if (data.progress) { const hair = document.createElement('span'); hair.className = 'hair'; const i = document.createElement('i'); i.style.width = Math.round(100 * data.progress.completed / Math.max(1, data.progress.total)) + '%'; hair.appendChild(i); hair.title = data.progress.stage + ' ' + data.progress.completed + ' of ' + data.progress.total; hair.setAttribute('role', 'progressbar'); hair.setAttribute('aria-valuemin', '0'); hair.setAttribute('aria-valuemax', String(data.progress.total)); hair.setAttribute('aria-valuenow', String(data.progress.completed)); el.appendChild(hair); } - const m = document.createElement('span'); m.className = 'msg'; - m.textContent = data.standing.text + (data.progress ? ' ' + data.progress.stage + ': ' + data.progress.completed + ' of ' + data.progress.total + '.' : '') + ' Read at ' + data.readAt + '.'; - el.appendChild(m); - const save = data.status ? A.stripSave(data.status, $('strip-note')) : null; - if (save) el.appendChild(save); else $('strip-note').textContent = ''; - const b = document.createElement('button'); b.className = 'btn sm needs-btn'; b.type = 'button'; b.id = 'needs-btn'; b.dataset.key = 'needs-btn'; - b.textContent = 'Needs you · ' + (data.needs ? data.needs.length : '…'); b.disabled = !data.needs; - const panel = $('needs-panel'); b.setAttribute('aria-expanded', String(!panel.hidden)); b.setAttribute('aria-controls', 'needs-panel'); - b.addEventListener('click', () => { panel.hidden = !panel.hidden; b.setAttribute('aria-expanded', String(!panel.hidden)); fillNeeds(); }); - el.appendChild(b); + const el = $('strip'), want = []; + if (failed) { want.push(part('state', 'failed ' + !!conflict, () => S.stateEl('serious', conflict ? 'Conflict' : 'Not read'))); want.push(part('msg', 'failed ' + failed, () => span('msg', failed))); } + else if (!data.standing) want.push(part('msg', 'reading', () => span('msg', 'Reading the project…'))); + else { + const { tone, word, text } = data.standing, p = data.progress; + want.push(part('state', tone + ' ' + word, () => S.stateEl(tone, word))); + if (p) want.push(part('hair', [p.stage, p.completed, p.total].join(' '), () => hairline(p))); + const m = part('msg', 'standing', () => { const s = span('msg', ''); s.append(document.createTextNode(''), document.createTextNode('')); return s; }); + setText(m.firstChild, text + (p ? ' ' + p.stage + ': ' + p.completed + ' of ' + p.total + '.' : '')); + setText(m.lastChild, ' Read at ' + data.readAt + '.'); + want.push(m); + const n = data.status ? data.status.unsaved.length + data.status.removed.length : 0; + if (n) want.push(part('save', n + ' ' + A.may('edit'), () => A.stripSave(data.status, $('strip-note')))); + else if ($('strip-note').firstChild) $('strip-note').textContent = ''; + want.push(needsButton()); + } + const now = [...el.children]; + if (now.length !== want.length || want.some((e, i) => now[i] !== e)) keepFocus(el, () => { + want.forEach((e, i) => { if (el.children[i] !== e) el.insertBefore(e, el.children[i] || null); }); + while (el.children.length > want.length) el.lastElementChild.remove(); }); fillNeeds(); } /** Places Needs you sends to: the panel closes and the focus goes to the drawer that opens. */ function needsGo(screen, id) { const panel = $('needs-panel'); panel.hidden = true; const b = $('needs-btn'); if (b) b.setAttribute('aria-expanded', 'false'); opener = { key: 'needs-btn', el: null }; go(screen, id); } - function fillNeeds() { + /** Needs you, when open: drawn again when what it lists (or who may use its controls) differs, or when it is opened (force). */ + function fillNeeds(force) { const panel = $('needs-panel'); if (panel.hidden || !data.needs) return; + const key = JSON.stringify([data.needs.map(n => [n.kind, n.key || '', n.text, n.references || null]), (window.TuldokAuth && window.TuldokAuth.identity()) || null]); + if (!force && panel._key === key) return; + panel._key = key; keepFocus(panel, () => { panel.textContent = ''; panel.appendChild(S.needsList(data.needs, n => A.needControls(n, needsGo))); }); } // ---- Rendering -------------------------------------------------------------- + /** + * Draws the tab on screen. The tab bar is built once (start()); this sets + * which link is current. The drawer is drawn again in place when app.js + * marked it (aside._again: 'data' after a reading that changed something, + * 'control' after a control's answer, which the editor and the branch form + * take too); otherwise a drawer already showing its subject is left alone. + */ function render() { - const tabs = $('tabs'); tabs.textContent = ''; - for (const [id, label] of TABS) { const a = document.createElement('a'); a.href = '#' + id; a.textContent = label; if (id === state.screen) a.setAttribute('aria-current', 'page'); tabs.appendChild(a); } + for (const a of $('tabs').children) { const on = a.dataset.tab === state.screen; if (on !== a.hasAttribute('aria-current')) { if (on) a.setAttribute('aria-current', 'page'); else a.removeAttribute('aria-current'); } } const main = $('main'), aside = $('aside'), drawer = $('drawer'); const name = data.summary ? data.summary.name : ''; document.title = TABS.find(t => t[0] === state.screen)[1] + (name ? ' · ' + name : '') + ' · Tuldok'; @@ -112,7 +155,7 @@ main.className = 'content'; main.textContent = ''; main._tree = null; main._view = null; main._painted = null; if (conflict) A.conflictPanel(main, conflict); else { const p = document.createElement('p'); p.className = failed ? 'failure' : 'note'; p.textContent = failed || 'Reading the project…'; main.appendChild(p); } - drawer.classList.remove('open'); drawer.setAttribute('aria-hidden', 'true'); main.classList.remove('with-drawer'); aside.textContent = ''; aside._for = null; + drawer.classList.remove('open'); drawer.setAttribute('aria-hidden', 'true'); main.classList.remove('with-drawer'); aside.textContent = ''; aside._for = null; aside._again = false; return; } const wasMap = main.classList.contains('map'), view = state.screen + '/' + (state.screen === 'overview' && state.sel.overview === 'report' ? 'report' : ''); // a selection opens the drawer and keeps the place; the report is its own view @@ -120,114 +163,141 @@ if (state.screen !== 'map' && wasMap) main._tree = null; if (main._view !== view) { main.scrollTop = 0; main.scrollLeft = 0; main._view = view; } // a new screen starts at its top const has = S[state.screen](main, aside, state, act, data); + aside._again = false; drawer.classList.toggle('open', !!has); drawer.setAttribute('aria-hidden', String(!has)); main.classList.toggle('with-drawer', !!has); if (!has) aside._for = null; } function fail(error) { failed = error.message; conflict = error.code === 'conflict' ? error : null; } // ---- Reading ------------------------------------------------------------------ + const WATCH = P.WATCHED.filter(n => n !== 'map'); // asked again on every reading; the map too on some (step()) async function first() { try { data.summary = await P.read('summary'); $('projname').textContent = data.summary.name; if (window.LabEditor) window.LabEditor.load(data.summary.project_id); // the drafts of this project, kept for this tab - data.map = await P.map(); mapText = JSON.stringify(await P.read('map')); + data.map = await P.map(); data.standing = P.standing(data.map, null, null); data.readAt = clock(); failed = null; conflict = null; } catch (error) { fail(error); } strip(); render(); - if (!failed) await standing(); + if (failed) return; + const read = await sources(); + if (read.error && read.error.code === 'conflict') { fail(read.error); strip(); render(); return; } + ended(read); await stand(read); + strip(); + if (state.screen === 'overview') render(); // it shows where the project stands and Needs you } - /** - * The strip's other sources: status, build requests, environments and runs. - * Asks again in two seconds while a build is queued or running. Compares - * the states of the runs and requests with the last reading: when a run - * has ended everything is read again (the map too); when the open run or - * request changed state, its drawer is drawn again. - */ - async function standing() { - let ended = false, moved = new Set(), lists = null; + /** The strip's other sources, as kept: status, build requests, environments and runs. */ + async function sources() { + try { const [status, requests, environments, runs] = await Promise.all([P.read('status'), P.read('build_requests'), P.read('environments'), P.read('runs')]); return { status, requests: requests.requests, environments: environments.environments, runs: runs.runs }; } + catch (error) { return { error }; } + } + /** Whether a run or a build request that was active is no more (or a run came and went) since the last reading. */ + function ended(read) { + if (read.error) return false; + const now = new Map(read.runs.map(r => ['run:' + r.id, r.state]).concat(read.requests.map(r => ['request:' + r.id, r.state]))); + let gone = false; + if (states) for (const [key, st] of now) { + const was = states.get(key); + if (key.startsWith('run:') ? (was === undefined || ACTIVE_RUN.includes(was)) && !ACTIVE_RUN.includes(st) : ACTIVE_REQUEST.includes(was) && !ACTIVE_REQUEST.includes(st)) gone = true; + } + states = now; + return gone; + } + /** Where the project stands, Needs you and the running run's progress, from the sources; asks again later (in two seconds while something builds). */ + async function stand(read) { try { - const [status, requests, environments, runs] = await Promise.all([P.read('status'), P.read('build_requests'), P.read('environments'), P.read('runs')]); - lists = [runs.runs, requests.requests]; - data.status = status; - data.standing = P.standing(data.map, runs.runs, requests.requests); - data.needs = P.needs({ summary: data.summary, status, requests: requests.requests, environments: environments.environments, runs: runs.runs, shaped: data.map }); - const running = runs.runs.find(r => r.state === 'running'); - data.progress = running ? (await P.call('progress', { run: running.id })).event : null; + if (read.error) throw read.error; + data.status = read.status; + data.standing = P.standing(data.map, read.runs, read.requests); + data.needs = P.needs({ summary: data.summary, status: read.status, requests: read.requests, environments: read.environments, runs: read.runs, shaped: data.map }); + // The latest progress of each running run: the first is the strip's, all are set into Train's rows (tabs.js's S.progress). + const running = read.runs.filter(r => r.state === 'running'); + data.progressOf = new Map(await Promise.all(running.map(r => P.call('progress', { run: r.id }).then(p => [r.id, p.event], () => [r.id, null])))); + data.progress = running.length ? data.progressOf.get(running[0].id) : null; data.readAt = clock(); - const now = new Map(runs.runs.map(r => ['run:' + r.id, r.state]).concat(requests.requests.map(r => ['request:' + r.id, r.state]))); - if (states) for (const [key, st] of now) { - const was = states.get(key); - if (was !== st) moved.add(key); - // A run or a request that was active and is no more, or a run that came and went between two readings. - if (key.startsWith('run:') ? (was === undefined || ACTIVE_RUN.includes(was)) && !ACTIVE_RUN.includes(st) : ACTIVE_REQUEST.includes(was) && !ACTIVE_REQUEST.includes(st)) ended = true; - } - states = now; - const busy = runs.runs.some(r => ACTIVE_RUN.includes(r.state)) || requests.requests.some(r => ACTIVE_REQUEST.includes(r.state)); - later(busy); + later(read.runs.some(r => ACTIVE_RUN.includes(r.state)) || read.requests.some(r => ACTIVE_REQUEST.includes(r.state))); } catch (error) { - if (error.code === 'conflict') { fail(error); strip(); render(); return; } - data.needs = null; data.standing = Object.assign({}, data.standing, { text: data.standing.text + ' ' + error.message }); - later(false); - } - const aside = $('aside'); - if (ended) { - // A run ended: what it made changes the map, the lists and the drawers. - for (const name of ['summary', 'map', 'definitions', 'definition', 'products', 'recipe_results', 'results_overview', 'results', 'values', 'chart', 'graph', 'activity', 'run', 'build_request', 'plan', 'estimates']) - P.forget([name]); - try { - data.summary = await P.read('summary'); - const text = JSON.stringify(await P.read('map')); - if (text !== mapText) { mapText = text; data.map = await P.map(); aside._for = null; if (lists) data.standing = P.standing(data.map, ...lists); } - } catch (error) { fail(error); strip(); render(); return; } + unread(error); } - let redraw = ended; - if (aside._for && moved.has(aside._for)) { P.forget(['run', 'build_request']); aside._for = null; redraw = true; } - strip(); - if (redraw || ['overview', 'train'].includes(state.screen)) render(); + } + /** A reading that failed (not a conflict): what is on screen stays, the strip says the project was not read and why, and it is asked again later. */ + function unread(error) { + data.progress = null; data.progressOf = new Map(); + data.standing = { tone: 'serious', word: 'Not read', text: P.standing(data.map, null, null).text + ' The last reading failed: ' + error.message.replace(/\.$/, '') + '.' }; + later(false); + } + /** What a reading sets in place in the main area whether or not anything changed: Overview's "Read at" and the progress of the running runs in Train's list. */ + function current() { + const at = $('main').querySelector('[data-read-at]'), text = 'Read at ' + data.readAt; + if (at && at.firstChild) setText(at.firstChild, text); + if (S.progress && data.progressOf) S.progress(data.progressOf); } /** Asks again later: in two seconds while something builds, otherwise in fifteen, so a request an agent makes or an edit made elsewhere shows without the window losing and regaining focus. */ function later(busy) { if (pollTimer && busy && !pollFast) { clearTimeout(pollTimer); pollTimer = null; } - if (!pollTimer) { pollFast = busy; pollTimer = setTimeout(poll, busy ? POLL_MS : IDLE_MS); } + if (!pollTimer) { pollFast = busy; pollTimer = setTimeout(() => { pollTimer = null; reread('timer'); }, busy ? POLL_MS : IDLE_MS); } } - async function poll() { - pollTimer = null; - P.forget(['summary', 'runs', 'build_requests'].concat(pollFast ? [] : ['status', 'environments'])); - try { data.summary = await P.read('summary'); } catch (error) { /* the strip says what failed below */ } - await standing(); - if (S.tick) await S.tick(); + /** + * The one way of reading again (spec-w4 R1 to R3), for a cause: 'timer', + * 'focus' (the window regained it, or a control was refused) or 'control' + * (a control's answer, which always counts as a change). One reading at a + * time: a cause arriving meanwhile waits, the strongest of those waiting kept. + */ + const RANK = { timer: 0, focus: 1, control: 2 }; + let reading = null, waiting = null, owed = false; // owed: a control was answered and the reading after it failed, so the next one counts as a change + function reread(cause, info) { + if (!reading) { reading = step(cause, info).catch(error => console.error(error)).finally(() => { reading = null; }); return reading; } + if (!waiting) { const w = waiting = { cause, info }; w.done = reading.then(() => { waiting = null; return reread(w.cause, w.info); }); } + else if (RANK[cause] > RANK[waiting.cause] || (cause === waiting.cause && info)) Object.assign(waiting, { cause, info }); + return waiting.done; } - /** Everything again, when the window regains focus; the map is redrawn only when it changed. */ - async function again() { - if (failed) { P.forgetAll(); return first(); } - P.forgetAll(); + /** + * One reading: asks again for what the page watches (the map too, except + * on the timer unless a run or request ended or status changed). Nothing + * changed: only the strip's parts that differ (the progress, the minute of + * "Read at") and the same two in the main area are touched. A reading that + * failed touches nothing but the strip, which says so. Something changed: what is not watched is + * forgotten, and the strip, the tab and the open drawer are drawn again in + * place (a drawer holding the editor or the branch form only after a + * control). The open run reads on (tabs.js's S.tick). + */ + async function step(cause, info) { + if (failed) { if (cause === 'timer') return; P.forgetAll(); await first(); return settleFocus(info); } + const control = cause === 'control'; + let changed; try { - data.summary = await P.read('summary'); - const text = JSON.stringify(await P.read('map')); - if (text !== mapText) { mapText = text; data.map = await P.map(); $('aside')._for = null; render(); } - else if (state.screen !== 'map') render(); - } catch (error) { fail(error); strip(); render(); return; } - await standing(); - } - /** After a control's answer: forget everything, read again, draw the drawer afresh; the focus stays on the control when it is still there. */ - async function changed(info) { - P.forgetAll(); - if (failed) { await first(); } - else { - try { - data.summary = await P.read('summary'); - const text = JSON.stringify(await P.read('map')); - if (text !== mapText) { mapText = text; data.map = await P.map(); } - } catch (error) { fail(error); strip(); render(); return; } - $('aside')._for = null; render(); - await standing(); - } + changed = await P.again(cause === 'timer' ? WATCH : P.WATCHED); + if (changed.includes('map')) data.map = await P.map(); + } catch (error) { return notRead(error, control); } + if (changed.includes('summary')) try { data.summary = await P.read('summary'); } catch (error) { /* the strip says what failed */ } + const read = await sources(); + if (read.error && read.error.code === 'conflict') return notRead(read.error, control); + if (cause === 'timer' && (ended(read) || changed.includes('status'))) { + try { if ((await P.again(['map'])).length) { changed = changed.concat(['map']); data.map = await P.map(); } } catch (error) { return notRead(error, control); } + } else if (cause !== 'timer') ended(read); + await stand(read); + const anything = control || owed || changed.length > 0; owed = false; + if (anything) P.forgetBut(P.WATCHED); + strip(); + if (anything) { $('aside')._again = control ? 'control' : 'data'; render(); } else current(); + if (S.tick) await S.tick(); + if (control) settleFocus(info); + } + /** A reading that could not be made: a conflict shows the conflict panel; anything else leaves the page as it is and says so in the strip. */ + function notRead(error, control) { + if (error.code === 'conflict') { fail(error); strip(); render(); return; } + if (control) owed = true; + unread(error); strip(); + } + /** After a control's answer: the focus stays on the control when it is still there, else goes to the drawer's heading. */ + function settleFocus(info) { if (info && info.focus && (!document.activeElement || document.activeElement === document.body)) { if (!A.focusKey(info.focus)) setTimeout(() => { if (document.activeElement === document.body) { const t = $('aside').querySelector('h2') || $('main'); if (t.tabIndex < 0 && t !== $('main')) t.tabIndex = -1; t.focus(); } }, 300); } } - A.connect({ changed, refused: () => standing(), reread: () => changed() }); + const changed = info => reread('control', info); + A.connect({ changed, refused: () => reread('focus'), reread: () => reread('control') }); function start() { // auth.js puts its session controls first in the body; they belong at the right of the top bar. @@ -243,10 +313,12 @@ if ($('drawer').classList.contains('open') && state.sel[state.screen]) go(state.screen); }); window.addEventListener('hashchange', () => { parse(); render(); }); - window.addEventListener('focus', () => { if (data.summary || failed) again(); }); + window.addEventListener('focus', () => { if (data.summary || failed) reread('focus'); }); // Who may use a control comes from the session: draw the controls again when it changes. - window.addEventListener('tuldok-session', () => { if (failed) again(); else { $('aside')._for = null; if (data.map) act.redraw(); else { strip(); render(); } } }); + window.addEventListener('tuldok-session', () => { if (failed) reread('focus'); else { $('aside')._for = null; if (data.map) act.redraw(); else { strip(); render(); } } }); { const q = new URLSearchParams(location.search); state.benchmark = q.get('benchmark') || null; state.cmp = (q.get('cmp') || '').split(',').filter(Boolean).slice(0, 3); } + // The tab bar, once (spec-w4 R5): render() sets which link is current. + for (const [id, label] of TABS) { const a = document.createElement('a'); a.href = '#' + id; a.textContent = label; a.dataset.tab = id; $('tabs').appendChild(a); } parse(); strip(); render(); first(); } if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', start, { once: true }); else start(); diff --git a/static/project-workspace/editor.js b/static/project-workspace/editor.js index 3283435b..0763145a 100644 --- a/static/project-workspace/editor.js +++ b/static/project-workspace/editor.js @@ -5,7 +5,8 @@ // map; Branch from here and the drafts it makes; the steps of a new model; the // Overview's list of every definition. What is typed is kept in page memory // per definition until it is kept or discarded, so leaving the drawer or a -// re-render loses nothing; a draft is kept in sessionStorage under the +// re-render loses nothing, and a reading on the timer or on focus leaves the +// editor and the branch form alone; a draft is kept in sessionStorage under the // project's id, so it survives a reload of the tab. The form changes only the // fields touched and writes the JSON back with the indentation the text had. // Nothing here writes to disk: Keep stores an unsaved edit, Save writes them. @@ -79,7 +80,8 @@ window.LabEditor = (() => { function decorate(root) { for (const s of (root || document).querySelectorAll('.umark[data-ref]')) { const typed = buffers.has(s.dataset.ref) || s.dataset.draft === '1'; - s.textContent = typed ? 'not kept yet' : s.dataset.removed === '1' ? 'removed' : s.dataset.unsaved === '1' ? 'unsaved' : ''; + const text = typed ? 'not kept yet' : s.dataset.removed === '1' ? 'removed' : s.dataset.unsaved === '1' ? 'unsaved' : ''; + if (s.textContent !== text) s.textContent = text; // a mark already right is not touched (spec-w4 R2) s.classList.toggle('typed', typed); } } @@ -94,21 +96,19 @@ window.LabEditor = (() => { if (sel.startsWith('branch:')) return branchForm(aside, sel, sel.slice(7), act, data); return editor(aside, sel, subject(sel), act, data, screen); } - /** Puts node in the drawer, giving back the focused control (by data-key), its caret and the scroll; else the heading takes the focus when the focus was in the drawer. */ + /** Puts node in the drawer in one step (screens.js's putInPlace: the focused control by data-key, its caret and the scroll given back); else the heading takes the focus when the focus was in the drawer or nowhere. */ function swapInto(aside, node) { - const active = document.activeElement, inside = !!active && aside.contains(active), key = inside && active.dataset ? active.dataset.key : null; - let caret = null; try { caret = key && typeof active.selectionStart === 'number' ? [active.selectionStart, active.selectionEnd, active.scrollTop] : null; } catch (e) { caret = null; } - const scroller = aside.parentElement, top = scroller.scrollTop; - aside.textContent = ''; aside.appendChild(node); scroller.scrollTop = top; - const again = key && [...aside.querySelectorAll('[data-key]')].find(e => e.dataset.key === key); - if (again) { again.focus({ preventScroll: true }); if (caret && again.setSelectionRange) { again.setSelectionRange(caret[0], caret[1]); again.scrollTop = caret[2]; } } - else if (inside || !active || active === document.body) { const t = aside.querySelector('h2'); if (t && aside.closest('.drawer.open')) t.focus({ preventScroll: true }); } + const active = document.activeElement, nowhere = !active || active === document.body; + const r = S.parts.putInPlace(aside, node, aside.parentElement); + if (!r.found && (r.inside || nowhere)) { const t = aside.querySelector('h2'); if (t && aside.closest('.drawer.open')) t.focus({ preventScroll: true }); } } // ---- The editor --------------------------------------------------------------------- + // A reading on the timer or on focus never touches the editor or the branch form (spec-w4 R3): what is typed stays. + // After a control's answer (aside._again 'control') they are drawn again in place. function editor(aside, sel, ref, act, data, screen) { const key = 'editor:' + sel; - if (aside._for === key) return true; + if (aside._for === key && aside._again !== 'control') return true; aside._for = key; const draft = draftOf(ref); if (!(aside._editing === ref && aside.querySelector('.editor'))) { aside.textContent = ''; aside.appendChild(h('p', 'note', 'Reading…')); } @@ -341,7 +341,7 @@ window.LabEditor = (() => { // ---- Branch from here ------------------------------------------------------------------- function branchForm(aside, sel, parentRef, act, data) { - if (aside._for === sel) return true; + if (aside._for === sel && aside._again !== 'control') return true; aside._for = sel; aside._editing = null; const m = data.map.byId.get(parentRef); const ins = h('div', 'inspector branch'); @@ -408,10 +408,11 @@ window.LabEditor = (() => { /** * The steps of a model of the map (screens.js): read its definition, runs and * the build requests; earlier work gets planGroup() instead (as phase 2). + * Fills box, on the page or not yet (a drawer read again is built off the + * page), and resolves once it is filled. */ function steps(box, m, act, data, planGroup) { - Promise.all([P.read('definition', { reference: m.id }), P.read('runs', { reference: m.id }), P.read('build_requests')]).then(([def, runs, requests]) => { - if (!box.isConnected) return; + return Promise.all([P.read('definition', { reference: m.id }), P.read('runs', { reference: m.id }), P.read('build_requests')]).then(([def, runs, requests]) => { box.textContent = ''; if (isObject(def.document) && def.document.earlier_work && !followed.includes(m.id)) { if (['not-built', 'out-of-date', 'failed'].includes(m.state)) box.appendChild(planGroup()); return; } const asked = requests.requests.filter(r => (r.targets || []).includes(m.id) && !['declined', 'cancelled', 'expired'].includes(r.state)); @@ -421,7 +422,7 @@ window.LabEditor = (() => { runningNow: runList.some(r => r.state === 'running'), built: ['built', 'out-of-date'].includes(m.state), unsaved: def.unsaved, request: asked[0] || null, run: runList[0] || null, state: m.state }, act, data, planGroup)); - }, error => { if (box.isConnected) { box.textContent = ''; box.appendChild(A.refusal(error)); } }); + }, error => { box.textContent = ''; box.appendChild(A.refusal(error)); }); } function stepsBlock(ref, f, act, data) { const wrap = h('div', 'new-steps'); diff --git a/static/project-workspace/screens.js b/static/project-workspace/screens.js index 35dbbebb..b6f5f5a2 100644 --- a/static/project-workspace/screens.js +++ b/static/project-workspace/screens.js @@ -4,7 +4,10 @@ // has something to show there, and returns whether the drawer is open. It // reads the project only through window.TuldokProject. Rule: the chrome holds // no project words; names, groups, metrics and text come from the project. -// The editor, the branch form, a draft's drawer, the steps of a new model and +// What is drawn again is built off the page and put in place whole, in one +// step, keeping the scroll and the focus (putInPlace, spec-w4.md); the map +// keeps its tree while its answer is unchanged, and keeps its place when +// rebuilt. The editor, the branch form, a draft's drawer, the steps of a new model and // the Overview's list of every definition are editor.js's (window.LabEditor). window.LabScreens = (() => { const P = window.TuldokProject, Tree = window.LabTree, C = window.LabCharts, h = C.h; @@ -28,6 +31,39 @@ window.LabScreens = (() => { const time = iso => iso ? new Date(iso).toLocaleString('en-GB', { day: 'numeric', month: 'short', year: 'numeric', hour: '2-digit', minute: '2-digit' }) : '—'; const bytes = b => b == null ? '—' : b >= 1e9 ? (b / 1e9).toFixed(1) + ' GB' : b >= 1e6 ? (b / 1e6).toFixed(1) + ' MB' : b >= 1e3 ? Math.round(b / 1e3) + ' KB' : b + ' B'; const failure = (parent, error) => { parent.appendChild(h('p', 'failure', error.message || String(error))); }; + // ---- Putting in place (spec-w4 R4) ------------------------------------------ + /** Every element under root that is scrolled, by its path of child indexes and its tag. */ + function scrolls(root) { + const out = []; + const walk = (el, path) => { for (let i = 0; i < el.children.length; i++) { const c = el.children[i], p = path.concat([i]); if (c.scrollTop || c.scrollLeft) out.push({ path: p, tag: c.tagName, top: c.scrollTop, left: c.scrollLeft }); walk(c, p); } }; + walk(root, []); return out; + } + /** + * Puts content, built off the page, in box in one step in place of what it + * holds, keeping the scroll of scroller (box unless named) in both + * directions, the scroll of every scrolled element inside box (the same + * path and tag), and the focused control (by data-key) with its caret. + * Returns whether the focus was inside and whether its control was found. + */ + function putInPlace(box, content, scroller = box) { + const active = document.activeElement, inside = !!active && box.contains(active), key = inside && active.dataset ? active.dataset.key : null; + let caret = null; try { caret = key && typeof active.selectionStart === 'number' ? [active.selectionStart, active.selectionEnd, active.scrollTop] : null; } catch (e) { caret = null; } + const top = scroller.scrollTop, left = scroller.scrollLeft, inner = scrolls(box); + box.replaceChildren(content); + scroller.scrollTop = top; scroller.scrollLeft = left; + for (const s of inner) { let e = box; for (const i of s.path) { e = e.children[i]; if (!e) break; } if (e && e.tagName === s.tag) { e.scrollTop = s.top; e.scrollLeft = s.left; } } + const again = key && [...box.querySelectorAll('[data-key]')].find(e => e.dataset.key === key); + if (again) { again.focus({ preventScroll: true }); if (caret && again.setSelectionRange) { try { again.setSelectionRange(caret[0], caret[1]); } catch (e) { /* not a text field */ } again.scrollTop = caret[2]; } } + return { inside, found: !!again }; + } + /** Puts a drawer's content in place (the drawer's own scroll kept); when the focused control is gone, the heading takes the focus. */ + function putDrawer(aside, content) { + const r = putInPlace(aside, content, aside.parentElement); + if (r.inside && !r.found) { const t = aside.querySelector('h2'); if (t) t.focus({ preventScroll: true }); } + } + /** A new turn of the drawer: a read started for an older turn puts nothing in it. */ + const turn = aside => (aside._turn = (aside._turn || 0) + 1); + const NEEDS_ICON = { approval: 'clock', changed: 'alert', missing: 'triangle' }; /** What needs the person, one sentence each; controls(item) gives the controls drawn under a sentence. */ function needsList(items, controls) { @@ -69,16 +105,19 @@ window.LabScreens = (() => { // While a parent is being picked (editor.js), the next model pressed is the parent instead. const common = { onSelect: id => { if (!(E && E.picked(id, act))) act.select(id); }, kinds: state.kinds, query: state.query }; if (prev && prev.sig === sig && prev.shaped === shaped && main.contains(prev.bar)) { - if (sel && sel !== prev.sel) { prev.map.scrollTo(sel, true); prev.list.scrollTo(sel, true); } - prev.map.select(sel); prev.list.select(sel); prev.sel = sel; + // The same tree: only a new selection is drawn (spec-w4 R2, R6). + if (sel !== prev.sel) { if (sel) { prev.map.scrollTo(sel, true); prev.list.scrollTo(sel, true); } prev.map.select(sel); prev.list.select(sel); prev.sel = sel; } } else { const focused = prev && prev.bar && prev.bar.contains(document.activeElement) && document.activeElement.type === 'search' ? document.activeElement.selectionStart : null; + // A changed map (the same filters) is rebuilt where it was: the scroll of the map and of the list kept (R6). + const place = prev && prev.sig === sig && main.contains(prev.bar) ? [main.querySelector('.tree-map'), main.querySelector('.tree-host')].map(e => e ? [e.scrollLeft, e.scrollTop] : null) : null; main.textContent = ''; const bar = buildBar(); main.appendChild(bar); const mh = h('div', 'tree-map'); main.appendChild(mh); const inst = { sig, bar, sel, shaped, map: null, list: null }; inst.map = Tree.renderMap(mh, g, Object.assign({ selected: sel, zoom: state.zoom || 1, track: !!state.track }, common)); const lh = h('div', 'tree-host'); main.appendChild(lh); inst.list = Tree.renderList(lh, g, Object.assign({ selected: sel }, common)); - if (sel) { inst.map.scrollTo(sel, false); inst.list.scrollTo(sel, false); } + if (place) { for (const [e, at] of [[mh, place[0]], [lh, place[1]]]) if (at) { e.scrollLeft = at[0]; e.scrollTop = at[1]; } } + else if (sel) { inst.map.scrollTo(sel, false); inst.list.scrollTo(sel, false); } if (focused !== null) { const q = bar.querySelector('input[type="search"]'); q.focus(); q.setSelectionRange(focused, focused); } main._tree = inst; } @@ -91,11 +130,21 @@ window.LabScreens = (() => { // ---- Drawer: one model --------------------------------------------------- const TO_BUILD = ['not-built', 'out-of-date', 'failed']; - function inspectorModel(aside, id, act, data) { + /** + * The drawer of one model: its header, controls and lineage at once, and + * four blocks filled as their reads arrive (Results, Runs and product, Uses, + * Card; and the steps of a new model). Read again for the model on screen + * (aside._again), the new drawer is built off the page and put in place in + * one step once every block is filled. more(ins): added by the caller to + * each drawing (the Benchmarks tab's Compare). + */ + function inspectorModel(aside, id, act, data, more) { const E = window.LabEditor, A = window.LabActions; if (E && E.isDraft(id)) return E.drawer(aside, id, act, data, 'map'); // a draft's drawer is the editor - if (aside._for === id) return; - aside._for = id; aside.textContent = ''; + if (aside._for === id && !aside._again) return; + const same = aside._for === id && !!aside.firstChild, mine = turn(aside); + aside._for = id; if (!same) aside.textContent = ''; + const live = () => aside._turn === mine && aside._for === id, reads = []; const g = graphFor(data.map), m = g.byId.get(id); const ins = h('div', 'inspector'); const hd = h('header'); @@ -109,7 +158,7 @@ window.LabScreens = (() => { // Plan build, for a model to build (spec-w3 section 3.1): the plan view, never a request from here. A model // never built that is not earlier work has the steps of a new model instead (editor.js), whose next step it is. const planGroup = () => A.group('model:' + m.id, [{ id: 'plan', label: 'Plan build', cls: 'btn primary', who: 'request', onClick: () => act.select('plan:' + m.id) }]); - if (E && E.followsSteps(m)) { const box = h('div', 'steps-box'); box.appendChild(h('p', 'note', 'Reading…')); ins.appendChild(box); E.steps(box, m, act, data, planGroup); } + if (E && E.followsSteps(m)) { const box = h('div', 'steps-box'); box.appendChild(h('p', 'note', 'Reading…')); ins.appendChild(box); reads.push(E.steps(box, m, act, data, planGroup)); } else if (TO_BUILD.includes(m.state)) ins.appendChild(planGroup()); // Edit and Branch from here (spec-w3 section 3.2), for a session that may edit. ins.appendChild(A.group('modelact:' + m.id, [ @@ -149,10 +198,11 @@ window.LabScreens = (() => { // What is read when the model is opened. const results = block('Results'), runs = block('Runs and product'), uses2 = block('Uses'), card = block('Card'); for (const b of [results, runs, uses2, card]) { b.appendChild(h('p', 'note', 'Reading…')); ins.appendChild(b); } - aside.appendChild(ins); - const fill = (b, build) => p => { if (aside._for !== id) return; b.lastChild.remove(); try { build(b, p); } catch (error) { failure(b, error); } }; - const fail = b => error => { if (aside._for !== id) return; b.lastChild.remove(); failure(b, error); }; - Promise.all([P.read('recipe_results', { recipe: m.id }), P.read('definitions', { kind: 'benchmark' }).catch(() => ({ definitions: [] }))]) + if (more) more(ins); + if (!same) aside.appendChild(ins); // first shown: at once, its blocks filled as they come + const fill = (b, build) => p => { if (!live()) return; b.lastChild.remove(); try { build(b, p); } catch (error) { failure(b, error); } }; + const fail = b => error => { if (!live()) return; b.lastChild.remove(); failure(b, error); }; + reads.push(Promise.all([P.read('recipe_results', { recipe: m.id }), P.read('definitions', { kind: 'benchmark' }).catch(() => ({ definitions: [] }))]) .then(fill(results, (b, [found, defs]) => { if (!found.rows.length) { b.appendChild(h('p', 'empty', found.benchmarks.length ? 'Named in ' + found.benchmarks.length + ' benchmarks, with no results yet.' : 'No benchmark measures this model.')); return; } const titles = new Map(defs.definitions.map(d => [d.reference.split('/').slice(1).join('/'), d.title])); @@ -162,37 +212,39 @@ window.LabScreens = (() => { const t = h('table', 'tv'); const hr = h('tr'); for (const [c, k] of [['Metric', ''], ['Median', 'n'], ['Cases', 'n']]) hr.appendChild(h('th', k, c)); const th = h('thead'); th.appendChild(hr); t.appendChild(th); const tb = h('tbody'); for (const r of rows) { const tr = h('tr'); tr.appendChild(h('td', 'ck', r.metric)); tr.appendChild(h('td', 'n', C.fmtSci(r.median))); tr.appendChild(h('td', 'n', String(r.count))); tb.appendChild(tr); } t.appendChild(tb); b.appendChild(t); } - }), fail(results)); - Promise.all([P.read('runs', { reference: m.id }), P.read('products', { reference: m.id })]) + }), fail(results))); + reads.push(Promise.all([P.read('runs', { reference: m.id }), P.read('products', { reference: m.id })]) .then(fill(runs, (b, [r, p]) => { if (!r.runs.length) b.appendChild(h('p', 'empty', 'No run of this model in this project.')); else { const ul = h('ul', 'rows'); for (const run of r.runs.slice(0, 8)) { const li = h('li'); const row = h('div', 'row'); row.style.gridTemplateColumns = 'minmax(0, 1fr) auto'; const t = h('span'); t.appendChild(h('span', 'title', (run.subject ? run.subject + ' · ' : '') + time(run.finished_at || run.started_at || run.queued_at))); t.appendChild(h('span', 'sub', [run.seconds != null ? Math.round(run.seconds) + ' s' : null, run.bytes != null ? bytes(run.bytes) : null, run.scratch ? 'scratch' : null].filter(Boolean).join(' · ') || run.id)); row.appendChild(t); row.appendChild(modelState(run.state)); li.appendChild(row); ul.appendChild(li); } b.appendChild(ul); if (r.runs.length > 8) b.appendChild(h('p', 'note', (r.runs.length - 8) + ' earlier runs are not listed.')); } if (!p.products.length) b.appendChild(h('p', 'note', 'No product on this machine.')); else { const dl = h('dl', 'facts'); for (const pr of p.products) { dl.appendChild(h('dt', null, (pr.subject || 'Product') + (pr.adopted ? ' (adopted)' : ''))); dl.appendChild(h('dd', 'mono', pr.directory + ' · ' + bytes(pr.bytes))); } b.appendChild(dl); } - }), fail(runs)); - P.read('definition', { reference: m.id }) + }), fail(runs))); + reads.push(P.read('definition', { reference: m.id }) .then(fill(uses2, (b, d) => { const other = d.uses.filter(u => !u.reference.startsWith('recipes/')); if (!other.length) { b.appendChild(h('p', 'empty', 'It uses no dataset, model or environment.')); return; } const dl = h('dl', 'facts'); for (const u of other) { dl.appendChild(h('dt', null, u.role)); dl.appendChild(h('dd', 'mono', u.reference)); } b.appendChild(dl); - }), fail(uses2)); + }), fail(uses2))); if (!m.card) fill(card, b => b.appendChild(h('p', 'empty', 'This model has no card.')))(); else if (!m.card.startsWith('notes/')) fill(card, b => b.appendChild(h('p', 'empty', 'Its card ' + m.card + ' is not under notes/ and is not read.')))(); - else P.read('note', { path: m.card.slice('notes/'.length) }).then(fill(card, (b, note) => { b.appendChild(h('p', 'note mono', m.card)); b.appendChild(window.TuldokMarkdown.render(note.text)); }), fail(card)); + else reads.push(P.read('note', { path: m.card.slice('notes/'.length) }).then(fill(card, (b, note) => { b.appendChild(h('p', 'note mono', m.card)); b.appendChild(window.TuldokMarkdown.render(note.text)); }), fail(card))); + // Read again: the drawer on screen stays until the new one is complete. + if (same) Promise.all(reads).then(() => { if (live()) putDrawer(aside, ins); }); } // ---- Overview -------------------------------------------------------------- // Read once and built off the page (tabs.js's paint), so the refresh while a build runs keeps the place. function overview(main, aside, state, act, data) { const E = window.LabEditor, sel = state.sel.overview || ''; - if (sel === 'report') { aside.textContent = ''; aside._for = null; main.textContent = ''; main._painted = null; return report(main, data); } + if (sel === 'report') { aside.textContent = ''; aside._for = null; return report(main, data); } const editing = !!(E && E.owns(sel, data)); if (editing) E.drawer(aside, sel, act, data, 'overview'); else { aside.textContent = ''; aside._for = null; } S.paint(main, () => Promise.all([P.read('definitions'), P.read('environments'), P.read('activity', { limit: 12 })].map(p => p.then(v => ({ v }), error => ({ error })))), (frag, [d, e, a]) => { const standing = data.standing; const top = h('section', 'ov-status'); const line = h('div', 'ov-line'); line.appendChild(stateEl(standing.tone, standing.word)); line.appendChild(h('p', 'ov-text', standing.text)); top.appendChild(line); - top.appendChild(h('p', 'small faint', 'Read at ' + data.readAt)); + const at = h('p', 'small faint', 'Read at ' + data.readAt); at.dataset.readAt = '1'; top.appendChild(at); // set in place on every reading (app.js) frag.appendChild(top); const row = h('div', 'ov-row'); const needs = h('section'); needs.appendChild(sect('Needs you', data.needs ? String(data.needs.length) : '…')); @@ -233,12 +285,14 @@ window.LabScreens = (() => { }); return editing; } + /** The report in a frame: "Reading…" the first time; read again, the frame on screen stays until the new one is put in its place. */ function report(main, data) { - const bar = h('div', 'report-bar'); const back = h('a', 'btn sm ghost', '← Overview'); back.href = '#overview'; bar.appendChild(back); bar.appendChild(h('h2', null, 'Report')); main.appendChild(bar); - const frame = h('iframe', 'report-frame'); frame.title = 'Project report'; frame.setAttribute('sandbox', ''); - const note = h('p', 'note', 'Reading…'); main.appendChild(note); + const view = main._view, mine = main._paint = (main._paint || 0) + 1; + const head = () => { const bar = h('div', 'report-bar'); const back = h('a', 'btn sm ghost', '← Overview'); back.href = '#overview'; bar.appendChild(back); bar.appendChild(h('h2', null, 'Report')); return bar; }; + if (main._painted !== view) { main.textContent = ''; main.appendChild(head()); main.appendChild(h('p', 'note', 'Reading…')); } const theme = getComputedStyle(document.documentElement).colorScheme === 'dark' ? 'dark' : 'light'; - P.call('report', { theme }).then(r => { note.remove(); frame.srcdoc = r.html; main.appendChild(frame); }, error => { note.remove(); failure(main, error); }); + const put = add => { if (main._paint !== mine || main._view !== view) return; const frag = document.createDocumentFragment(); frag.appendChild(head()); add(frag); putInPlace(main, frag); main._painted = view; }; + P.call('report', { theme }).then(r => put(frag => { const frame = h('iframe', 'report-frame'); frame.title = 'Project report'; frame.setAttribute('sandbox', ''); frame.srcdoc = r.html; frag.appendChild(frame); }), error => put(frag => failure(frag, error))); return false; } @@ -254,7 +308,7 @@ window.LabScreens = (() => { }; // The Data, Train, Benchmarks and Analysis screens are added by tabs.js, which builds with these parts. - const parts = { sect, cell, block, time, bytes, failure, modelState, graphFor }; + const parts = { sect, cell, block, time, bytes, failure, modelState, graphFor, putInPlace, putDrawer, turn }; const S = { map, overview, inspectorModel, needsList, icon, stateEl, theme, parts }; return S; })(); diff --git a/static/project-workspace/tabs.js b/static/project-workspace/tabs.js index 0fb218bb..3b6614bf 100644 --- a/static/project-workspace/tabs.js +++ b/static/project-workspace/tabs.js @@ -3,8 +3,10 @@ // screens.js, added to window.LabScreens. Each is a screen like the others // (main, aside, state, act, data): it shows "Reading…" the first time, reads // what it needs through window.TuldokProject, then builds its content off the -// page and swaps it in, so a re-render (a sort, a filter, the refresh while a -// build runs) keeps the scroll and the focus. Data, Benchmarks and Analysis +// page and puts it in place in one step, so a re-render (a sort, a filter, a +// reading that found something changed) keeps the scroll, inside tables too, +// and the focus; a drawer read again for its subject stays on screen until +// its new content replaces it whole (spec-w4.md). Data, Benchmarks and Analysis // only read. Train draws the controls of spec-w3.md section 3.1 (actions.js): // Plan build, a build request's Approve, Decline and Cancel, a run's Cancel // run and Stop, an environment's Check again, Connect and Disconnect, and it @@ -14,7 +16,7 @@ // metrics and text come from the project. (() => { const S = window.LabScreens, P = window.TuldokProject, Tree = window.LabTree, C = window.LabCharts, h = C.h, A = window.LabActions; - const { sect, cell, block, time, bytes, failure, modelState, graphFor } = S.parts; + const { sect, cell, block, time, bytes, failure, modelState, graphFor, putInPlace, putDrawer, turn } = S.parts; const fmt = C.fmtSci; const STATISTICS = ['median', 'mean', 'p10', 'p90', 'min', 'max']; const plural = (n, one, many) => n.toLocaleString('en-GB') + ' ' + (n === 1 ? one : many || one + 's'); @@ -34,8 +36,10 @@ /** * Fills main from load() (a promise of what build reads): "Reading…" only * when this view has not been painted, the content built off the page and - * swapped in when it is still the newest render of the same view; the - * focused control (by data-key) and its caret are given back. + * put in place in one step when it is still the newest render of the same + * view, keeping what spec-w4 R4 lists (screens.js's putInPlace): the scroll + * of main and of every scrolled element in it, and the focused control (by + * data-key) with its caret. */ function paint(main, load, build) { const view = main._view, mine = main._paint = (main._paint || 0) + 1; @@ -49,23 +53,25 @@ swap(main, frag); main._painted = view; }, error => { done(); if (main._paint !== mine || main._view !== view) return; - main.textContent = ''; failure(main, error); main._painted = view; + const frag = document.createDocumentFragment(); failure(frag, error); swap(main, frag); main._painted = view; }); } - function swap(main, frag) { - const active = document.activeElement, key = active && main.contains(active) && active.dataset ? active.dataset.key : null; - const caret = key && typeof active.selectionStart === 'number' ? active.selectionStart : null; - const top = main.scrollTop; - main.textContent = ''; main.appendChild(frag); main.scrollTop = top; - if (key) { const again = main.querySelector('[data-key="' + CSS.escape(key) + '"]'); if (again) { again.focus({ preventScroll: true }); if (caret !== null && again.setSelectionRange) again.setSelectionRange(caret, caret); } } - } - /** Fills the drawer from load() once per id; build(ins, value). */ + const swap = (main, frag) => putInPlace(main, frag); + /** + * Fills the drawer from load() for the subject id; build(ins, value). Once + * per id; read again for the subject on screen (app.js marks the drawer + * with _again after a change), what is on screen stays until the new + * content is built off the page, then is replaced in one step with the + * drawer's scroll kept. "Reading…" only for a subject not on screen yet. + */ function drawer(aside, id, load, build) { - if (aside._for === id) return; - aside._for = id; aside.textContent = ''; - const note = h('p', 'note', 'Reading…'); aside.appendChild(note); - load().then(value => { if (aside._for !== id) return; aside.textContent = ''; const ins = h('div', 'inspector'); try { build(ins, value); } catch (error) { failure(ins, error); } aside.appendChild(ins); }, - error => { if (aside._for !== id) return; aside.textContent = ''; failure(aside, error); }); + if (aside._for === id && !aside._again) return; + const same = aside._for === id && !!aside.firstChild, mine = turn(aside); + aside._for = id; + if (!same) { aside.textContent = ''; aside.appendChild(h('p', 'note', 'Reading…')); } + const live = () => aside._turn === mine && aside._for === id; + load().then(value => { if (!live()) return; const ins = h('div', 'inspector'); try { build(ins, value); } catch (error) { failure(ins, error); } putDrawer(aside, ins); }, + error => { if (!live()) return; const frag = document.createDocumentFragment(); failure(frag, error); putDrawer(aside, frag); }); } const closeDrawer = aside => { aside.textContent = ''; aside._for = null; return false; }; const setup = () => { const dl = h('dl', 'setup'); return { dl, put(k, v, cls) { dl.appendChild(h('dt', null, k)); const dd = h('dd', cls || null); if (typeof v === 'string') dd.textContent = v; else if (v) dd.appendChild(v); dl.appendChild(dd); } }; }; @@ -165,8 +171,8 @@ /** The drawer of a selected subject: the model's drawer when it is made from a recipe of the map, with Compare. */ function benchmarkDrawer(aside, sel, state, act, data) { const isModel = data.map.byId.has(sel); - if (isModel) S.inspectorModel(aside, sel, act, data); - else if (aside._for !== sel) { + if (isModel) S.inspectorModel(aside, sel, act, data, ins => compareActs(ins, sel, state, act, true)); + else if (aside._for !== sel || aside._again) { const name = sel.startsWith('subject:') ? sel.slice('subject:'.length) : sel; drawer(aside, sel, async () => { const list = await benchmarkList(); const b = pickBenchmark(list, state.benchmark); return b ? benchmarkView(b.benchmark, data.map) : null; }, (ins, view) => { const s = view && view.byName.get(name); @@ -402,10 +408,8 @@ b.appendChild(h('span', 'ck', m ? Tree.refName(m) : nameOfRef(r.reference))); const t = h('span'); t.appendChild(h('span', 'title', (m ? m.title : r.reference) + (r.subject ? ' · ' + r.subject : ''))); const when = r.finished_at || r.started_at || r.queued_at, ev = progress.get(r.id); - if (r.state === 'running' && ev) { - const line = h('span', 'sub live'); const hair = h('span', 'hair'); const i = h('i'); i.style.width = Math.round(100 * ev.completed / Math.max(1, ev.total)) + '%'; hair.appendChild(i); line.appendChild(hair); - line.appendChild(document.createTextNode(ev.stage + ' ' + ev.completed + ' of ' + ev.total + Object.entries(ev.metrics).slice(0, 2).map(([k, v]) => ' · ' + k + ' ' + fmt(v)).join(''))); t.appendChild(line); - } else t.appendChild(h('span', 'sub', [r.state === 'running' ? 'started ' + time(r.started_at) + ' · no progress reported yet' : time(when), seconds(r.seconds), r.bytes != null ? bytes(r.bytes) : null, r.scratch ? 'from the code as it is' : null].filter(Boolean).join(' · '))); + if (r.state === 'running' && ev) t.appendChild(rowProgress(ev)); + else t.appendChild(h('span', 'sub', [r.state === 'running' ? 'started ' + time(r.started_at) + ' · no progress reported yet' : time(when), seconds(r.seconds), r.bytes != null ? bytes(r.bytes) : null, r.scratch ? 'from the code as it is' : null].filter(Boolean).join(' · '))); b.appendChild(t); b.appendChild(m ? h('span', 'chip ' + m.kind, P.kindLabel(m.kind)) : h('span', 'small faint', nameOfRef(r.reference).length ? r.reference.split('/')[0].replace(/s$/, '') : '')); b.appendChild(h('span', 'sub', (r.environment && deviceOf.get(r.environment.reference)) || '—')); @@ -440,7 +444,7 @@ else if (sel.startsWith('env:')) envDrawer(aside, sel, act, data); else if (window.LabEditor && window.LabEditor.owns(sel, data)) window.LabEditor.drawer(aside, sel, act, data, 'train'); else if (data.map.byId.has(sel)) S.inspectorModel(aside, sel, act, data); - else { aside.textContent = ''; aside._for = sel; aside.appendChild(h('p', 'empty', 'There is no ' + sel + ' here.')); } + else if (aside._for !== sel) { aside.textContent = ''; aside._for = sel; aside.appendChild(h('p', 'empty', 'There is no ' + sel + ' here.')); } return true; } /** A row of a model to build, opening its drawer, with Plan build. */ @@ -462,8 +466,32 @@ const LOG_LINES = 200; // lines of each log kept on the page while a run is read live const hairOf = ev => { const hair = h('span', 'hair'); const i = h('i'); i.style.width = Math.round(100 * ev.completed / Math.max(1, ev.total)) + '%'; hair.appendChild(i); hair.setAttribute('role', 'progressbar'); hair.setAttribute('aria-valuemin', '0'); hair.setAttribute('aria-valuemax', String(ev.total)); hair.setAttribute('aria-valuenow', String(ev.completed)); return hair; }; const eventText = ev => ev.stage + ': ' + ev.completed + ' of ' + ev.total + Object.entries(ev.metrics).map(([k, v]) => ' · ' + k + ' ' + fmt(v)).join(''); - let live = null; // the open run read live: {key, run, offsets, update(progress)} - /** One step of the live run (app.js calls it every two seconds while a build runs): its progress and its logs from the offsets. */ + // A running run's progress in its row of Train's list: a hairline and a line. + const rowWidth = ev => Math.round(100 * ev.completed / Math.max(1, ev.total)) + '%'; + const rowText = ev => ev.stage + ' ' + ev.completed + ' of ' + ev.total + Object.entries(ev.metrics).slice(0, 2).map(([k, v]) => ' · ' + k + ' ' + fmt(v)).join(''); + function rowProgress(ev) { const line = h('span', 'sub live'); const hair = h('span', 'hair'); const i = h('i'); i.style.width = rowWidth(ev); hair.appendChild(i); line.appendChild(hair); line.appendChild(document.createTextNode(rowText(ev))); return line; } + /** + * Sets the latest progress of the running runs (a Map of run id to event, + * app.js on every reading) into their rows of Train's list, in place: the + * hairline's width and the line's text, when they differ (spec-w4 R7). + */ + S.progress = events => { + for (const b of document.querySelectorAll('#main button.row.run[data-run]')) { + const ev = events.get(b.dataset.run); if (!ev) continue; + const line = b.querySelector('.sub.live'); + if (!line) { const sub = b.children[1] && b.children[1].querySelector('.sub'); if (sub) sub.replaceWith(rowProgress(ev)); continue; } // its first progress + const i = line.querySelector('i'), width = rowWidth(ev), text = rowText(ev); + if (i.style.width !== width) i.style.width = width; + if (line.lastChild.data !== text) line.lastChild.data = text; + } + }; + let live = null; // the open run read live: {key, run, offsets, update(progress), ended()} + /** + * One step of the live run (app.js calls it on every reading, every two + * seconds while a build runs): its progress and its logs from the offsets, + * updated in place (spec-w4 R7). When it has ended, the project is read + * again and its drawer is drawn again in place. + */ S.tick = async () => { const aside = document.getElementById('aside'); if (!live || aside._for !== live.key) { live = null; return; } @@ -472,7 +500,7 @@ const pr = await P.call('progress', { run: mine.run, stdout_offset: mine.offsets.stdout, stderr_offset: mine.offsets.stderr }); if (live !== mine || aside._for !== mine.key) return; mine.update(pr); - if (pr.ended) { live = null; aside._for = null; mine.ended(); } + if (pr.ended) { live = null; mine.ended(); } // not awaited: the reading it starts waits for the one calling this } catch (error) { /* the next tick asks again; the strip says what fails */ } }; function runDrawer(aside, key, act, data) { @@ -525,6 +553,7 @@ logs[name] = { head, title, add: text => { if (!text) return; lines = lines.concat(text.replace(/\n$/, '').split('\n')).slice(-LOG_LINES); paintLog(); } }; } if (active) ins.appendChild(su.dl); + if (!active && live && live.key === key) live = null; // drawn again once it ended if (active) { live = { key, run: r.id, offsets: { stdout: (pr.stdout || {}).offset || 0, stderr: (pr.stderr || {}).offset || 0 }, update: p => { diff --git a/tests/browser_project_workspace_actions.cjs b/tests/browser_project_workspace_actions.cjs index ae7f1a16..1c72df90 100644 --- a/tests/browser_project_workspace_actions.cjs +++ b/tests/browser_project_workspace_actions.cjs @@ -138,9 +138,17 @@ async function type(selector, text) { await key('Delete', 'Delete', 46); await send('Input.insertText', { text }); } -/** Waits until nothing reads and no control waits for its answer. */ +// The page's own calls of the project's operations: a control's answer is followed by a reading that draws the tab +// and the drawer again in place (spec-w4.md), so settled() also waits until none is in flight. +const inflight = new Set(); let lastAnswer = 0; +function network(event) { + const p = event.params; + if (event.method === 'Network.requestWillBeSent' && /\/api\/project\/[a-z_]+$/.test(p.request.url)) inflight.add(p.requestId); + if ((event.method === 'Network.loadingFinished' || event.method === 'Network.loadingFailed') && inflight.delete(p.requestId)) lastAnswer = Date.now(); +} +/** Waits until nothing reads, no control waits for its answer, and the page has asked nothing of the project for a moment. */ async function settled(label) { - await until(() => evaluate(`(() => { const reading = e => [...e.querySelectorAll('.note')].some(n => n.textContent === 'Reading…'); return !reading(document.getElementById('main')) && !reading(document.getElementById('aside')) && !document.getElementById('main').hasAttribute('aria-busy') && !document.querySelector('.act-group [aria-busy]'); })()`), label); + await until(async () => !inflight.size && Date.now() - lastAnswer > 120 && await evaluate(`(() => { const reading = e => [...e.querySelectorAll('.note')].some(n => n.textContent === 'Reading…'); return !reading(document.getElementById('main')) && !reading(document.getElementById('aside')) && !document.getElementById('main').hasAttribute('aria-busy') && !document.querySelector('.act-group [aria-busy]'); })()`), label); await pause(150); } /** Replaces the whole value of a field (a number field too): select all, delete, then the text. */ @@ -219,6 +227,7 @@ with open(os.path.join(out, 'weights.json'), 'w') as handle: const target = (await (await fetch('http://127.0.0.1:' + debugPort + '/json')).json()).find(item => item.type === 'page'); socket = new WebSocket(target.webSocketDebuggerUrl); await once(socket, 'open'); session = cdpSession(socket, { timeoutMs: 60000, onEvent: event => { + network(event); if (event.method === 'Runtime.exceptionThrown') errors.push(event.params.exceptionDetails.exception?.description || event.params.exceptionDetails.text); if (event.method === 'Runtime.consoleAPICalled' && event.params.type === 'error') errors.push(event.params.args.map(a => a.value ?? a.description).join(' ')); if (event.method === 'Log.entryAdded' && event.params.entry.level === 'error') { diff --git a/tests/browser_project_workspace_still.cjs b/tests/browser_project_workspace_still.cjs new file mode 100644 index 00000000..7c23cb4c --- /dev/null +++ b/tests/browser_project_workspace_still.cjs @@ -0,0 +1,417 @@ +'use strict'; +// The project workspace updates in place (docs/plans/definition-first-projects/spec-w4.md section 4) in a headless +// browser, signed in as the owner. Tuldok runs with --project-folder on a copy of the minimal fixture with the +// buildable fixture's definitions beside it, in a Git repository of its own, and one more recipe with a stand-in +// command that trains nothing: recipes/steady prints a progress line every half second for about a minute. The page +// is watched with a MutationObserver on the tab bar, the strip, the main area, the drawer and Needs you; the elements +// on screen are marked so that new ones can be told apart; and the page is sampled every 50 ms for "Reading…". +// 1. Nothing changed: on every tab, and with a model's, a run's, a build request's and a dataset's drawer, the plan +// view and the editor open, the window regaining focus adds, removes and changes no node anywhere (but the +// minute of "Read at") and every scroll position stays (the main area both ways, every scrolled element inside +// it and the drawer, the map, the list, the drawer). On Train and on Overview the same holds across a reading on +// the fifteen-second timer; Needs you open stays open and untouched. +// 2. Something changed elsewhere: on Train, scrolled, a control focused, a second session (an agent credential) +// asks for a build; within one reading the strip's count and the Train list show it, "Reading…" is never shown, +// the scroll and the focus stay. With that request's drawer open, scrolled, the owner approves it from outside +// the page: the drawer shows the new state without "Reading…" and keeps its scroll. +// 3. A build runs: the strip's hairline moves, the open run's drawer reads on, and the run's row in Train's list +// reads on with no node added or removed; on the Map tab, with the model's drawer open, the main area gains no +// node until the run ends; then the model is drawn built, the map's and the list's scroll kept, and "Reading…" +// never shown. +// 4. The editor is left alone: with text typed into a field of the editor and not kept, a change elsewhere (a +// second request) and the window regaining focus do not touch the drawer; the typed text, the focus and the +// caret stay. +// 5. A reading that fails: cut off from the server, the page keeps what it shows and the strip says the project +// was not read; when the server answers again the strip says where the project stands, and nothing else was +// touched. +// With --lab-root only step 1 runs, on that folder opened in place, and nothing is asked of the +// project that changes it. It fails on any script error or failed request. +// node tests/browser_project_workspace_still.cjs [--lab-root ] +const assert = require('node:assert/strict'), fs = require('node:fs'), os = require('node:os'), path = require('node:path'); +const { spawn, execFileSync } = require('node:child_process'), { once } = require('node:events'); +const { authenticatedFixture } = require('./auth_helpers.cjs'), { waitForDebugger } = require('./browser_startup.cjs'), { cdpSession } = require('./browser_cdp_session.cjs'), { qaDirectory } = require('./qa_artifacts.cjs'); + +const root = path.resolve(__dirname, '..'); +const argv = process.argv.slice(2), labAt = argv.indexOf('--lab-root'); +const labRoot = labAt >= 0 ? path.resolve(argv[labAt + 1] || '') : null; +if (labAt >= 0) assert.ok(argv[labAt + 1] && fs.existsSync(path.join(labRoot, 'tuldok.json')), '--lab-root names a project folder (it holds tuldok.json)'); +assert.ok(process.env.TULDOK_DATABASE_URL, 'TULDOK_DATABASE_URL must name a disposable PostgreSQL cluster'); +const venv = path.join(root, '.venv', 'bin'); +if (fs.existsSync(path.join(venv, 'python'))) process.env.PATH = venv + path.delimiter + process.env.PATH; // auth_helpers runs python3 +const python = fs.existsSync(path.join(venv, 'python')) ? path.join(venv, 'python') : 'python3'; +const WIDTH = 1280, HEIGHT = 680; // short enough that Train, the drawers and the list scroll on the fixture +const IDLE_MS = 15000; // the page's reading while nothing builds (app.js) +const WATCHED = ['summary', 'status', 'build_requests', 'environments', 'runs']; + +const temporary = fs.mkdtempSync(path.join(os.tmpdir(), 'tuldok-still-browser-')); +const report = qaDirectory(root, labRoot ? 'project-workspace-still-lab' : 'project-workspace-still'); +const children = [], checks = [], errors = [], failures = []; +let offline = false; // step 5 cuts the page off from the server on purpose: what fails then is not a fault +let server, serverErrors = '', origin, auth, socket, session, send, evaluate, owned = null; +const pause = ms => new Promise(resolve => setTimeout(resolve, ms)); +async function until(fn, label, tries = 300) { for (let i = 0; i < tries; i++) { const value = await fn(); if (value) return value; await pause(100); } throw Error('Timed out: ' + label); } +function check(text) { checks.push(text); console.log('PASS ' + text); } +function launch(command, args, options) { const child = spawn(command, args, options); children.push(child); return child; } +async function stop(child) { if (!child || child.exitCode !== null || child.signalCode !== null) return; const exited = once(child, 'exit'); child.kill('SIGTERM'); await Promise.race([exited, pause(10000)]); if (child.exitCode === null && child.signalCode === null) { child.kill('SIGKILL'); await exited; } } +function findBrowser() { + const candidates = [process.env.BROWSER, '/usr/bin/chromium', '/usr/bin/chromium-browser', '/usr/bin/google-chrome']; + const cache = path.join(os.homedir(), '.cache', 'ms-playwright'); + if (fs.existsSync(cache)) for (const name of fs.readdirSync(cache).filter(n => n.startsWith('chromium_headless_shell-')).sort().reverse()) candidates.push(path.join(cache, name, 'chrome-headless-shell-linux64', 'chrome-headless-shell')); + const found = candidates.find(candidate => candidate && fs.existsSync(candidate)); + assert.ok(found, 'No headless browser: set BROWSER'); + return found; +} +/** Drops the project's schema and the catalog's from the disposable database, so each run imports afresh. */ +function dropOwned(folder, catalog) { + const id = JSON.parse(fs.readFileSync(path.join(folder, 'tuldok.json'), 'utf8')).id; + execFileSync(python, ['-c', `import json, os, pathlib, sys, psycopg +from psycopg import sql +from tuldok_project import store +store.drop_project(sys.argv[1], os.environ['TULDOK_DATABASE_URL']) +root = pathlib.Path(sys.argv[2]) +if root.exists(): + with psycopg.connect(os.environ['TULDOK_DATABASE_URL'], autocommit=True) as c: + for p in root.rglob('.tuldok.json'): + v = json.loads(p.read_text()) + name = 'projection_' + v['projection_id'] if v.get('version') == 2 else 'catalog_' + v['dataset_id'] + c.execute(sql.SQL('DROP SCHEMA IF EXISTS {} CASCADE').format(sql.Identifier(name))) +`, id, catalog], { cwd: root, stdio: ['ignore', 'pipe', 'pipe'] }); +} +async function contract(name) { + const capabilities = await (await auth.fetch(origin + '/api/agent/capabilities')).json(); + const operation = capabilities.operations.find(item => item.id === 'project.' + name), c = operation.contracts[operation.contracts.length - 1]; + return 'project.' + name + '/' + c.version + '/' + c.sha256; +} +/** An operation as the owner (the fixture's session, not the page); bearer: as that agent credential instead. */ +async function api(name, body = {}, bearer = null) { + const headers = { 'Content-Type': 'application/json', 'Tuldok-Operation-Contract': await contract(name) }; + const response = bearer ? await globalThis.fetch(origin + '/api/project/' + name, { method: 'POST', headers: { ...headers, Authorization: 'Bearer ' + bearer }, body: JSON.stringify(body) }) + : await auth.fetch(origin + '/api/project/' + name, { method: 'POST', headers, body: JSON.stringify(body) }); + const value = await response.json(); assert.equal(response.status, 200, name + ': ' + JSON.stringify(value)); return value; +} +async function credential(label, scopes) { + const response = await auth.fetch(origin + '/api/access/credentials', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ label, scopes, ttl_seconds: 3600 }) }); + const value = await response.json(); assert.equal(response.status, 201, JSON.stringify(value)); return value.token; +} + +// ---- The page's readings, from the browser's network ----------------------------- +// Each call of an operation the page makes, by name, with when it was sent and when it finished. +const calls = new Map(), finished = []; +function network(event) { + const p = event.params; + if (event.method === 'Network.requestWillBeSent' && /\/api\/project\/[a-z_]+$/.test(p.request.url)) calls.set(p.requestId, { name: p.request.url.split('/').pop(), sent: Date.now() }); + if ((event.method === 'Network.loadingFinished' || event.method === 'Network.loadingFailed') && calls.has(p.requestId)) { finished.push(Object.assign(calls.get(p.requestId), { done: Date.now() })); calls.delete(p.requestId); } +} +/** Waits for a reading begun after since: each of names asked for and answered, then nothing asked for 700 ms, then the page settled. */ +async function reading(since, names, label, tries = 300) { + await until(() => names.every(name => finished.some(f => f.name === name && f.sent >= since)), 'a reading: ' + label, tries); + await until(() => !calls.size && Date.now() - Math.max(0, ...finished.map(f => f.done)) > 700, 'the reading done: ' + label, 300); + await settled(label); +} +/** Waits until nothing reads and no control waits for its answer. */ +async function settled(label) { + await until(() => evaluate(`(() => { const reading = e => [...e.querySelectorAll('.note')].some(n => n.textContent === 'Reading…'); return !reading(document.getElementById('main')) && !reading(document.getElementById('aside')) && !document.getElementById('main').hasAttribute('aria-busy') && !document.querySelector('.act-group [aria-busy]'); })()`), 'settled: ' + label); + await pause(150); +} +async function hash(value) { await evaluate(`location.hash = ${JSON.stringify('#' + value)}`); await settled('#' + value); await pause(250); await settled('#' + value); } +const byKey = key => `[data-key=${JSON.stringify(key)}]`; +async function press(selector) { + const { x, y } = await until(() => evaluate(`(() => { const e = [...document.querySelectorAll(${JSON.stringify(selector)})].find(e => e.offsetParent !== null); if (!e) return null; e.scrollIntoView({ block: 'nearest', inline: 'nearest' }); const r = e.getBoundingClientRect(); return { x: r.left + r.width / 2, y: r.top + r.height / 2 }; })()`), 'shown: ' + selector, 100); + await send('Input.dispatchMouseEvent', { type: 'mouseMoved', x, y }); + await send('Input.dispatchMouseEvent', { type: 'mousePressed', x, y, button: 'left', clickCount: 1 }); await send('Input.dispatchMouseEvent', { type: 'mouseReleased', x, y, button: 'left', clickCount: 1 }); +} +const drawerState = () => evaluate(`[...document.querySelectorAll('#aside header .state')].map(e => e.textContent.trim()).join(' ')`); +const needsCount = () => evaluate(`Number((document.getElementById('needs-btn').textContent.match(/(\\d+)$/) || [])[1])`); + +// The watcher in the page: the observer starts counting at start(), so a record queued before it is not counted. +const WATCHER = `window.__still = (() => { + const ids = ['tabs', 'strip', 'main', 'aside', 'needs-panel'], el = id => document.getElementById(id); + let counts = null, flash = 0, timer = null; + const name = n => !n ? '?' : n.nodeType === 1 ? n.tagName.toLowerCase() + (typeof n.className === 'string' && n.className ? '.' + n.className.trim().split(/\\s+/).join('.') : '') : '#text ' + JSON.stringify(String(n.data || '').slice(0, 30)); + for (const id of ids) new MutationObserver(list => { + if (!counts) return; + const c = counts[id]; + for (const r of list) { + if (r.type === 'childList') { c.added += r.addedNodes.length; c.removed += r.removedNodes.length; for (const n of [...r.addedNodes, ...r.removedNodes]) if (c.what.length < 6) c.what.push(name(n) + ' in ' + name(r.target)); } + else if (r.type === 'characterData') { const msg = el('strip').querySelector('.msg'), parent = r.target.parentNode; if ((msg && r.target === msg.lastChild) || (parent && parent.dataset && parent.dataset.readAt)) c.readAt++; else { c.text++; if (c.what.length < 6) c.what.push('text of ' + name(r.target.parentNode) + ': ' + String(r.target.data).slice(0, 40)); } } + else { c.attrs++; if (c.what.length < 6) c.what.push('@' + r.attributeName + ' on ' + name(r.target)); } + } + }).observe(el(id), { childList: true, subtree: true, characterData: true, attributes: true }); + const where = (e, top) => { const p = []; while (e && e !== top) { p.unshift(e.tagName.toLowerCase() + ':' + [...e.parentElement.children].indexOf(e)); e = e.parentElement; } return p.join('>'); }; + function scrolls() { + const main = el('main'), drawer = el('drawer'), out = { main: [main.scrollLeft, main.scrollTop].map(Math.round), drawer: [drawer.scrollLeft, drawer.scrollTop].map(Math.round) }; + for (const [id, top] of [['main', main], ['aside', el('aside')]]) for (const e of top.querySelectorAll('*')) if (e.scrollLeft || e.scrollTop) out[id + ' ' + where(e, top)] = [Math.round(e.scrollLeft), Math.round(e.scrollTop)]; + return out; + } + return { + start() { counts = {}; for (const id of ids) { counts[id] = { added: 0, removed: 0, attrs: 0, text: 0, readAt: 0, what: [] }; for (const e of el(id).querySelectorAll('*')) e.__seen = 1; } flash = 0; clearInterval(timer); timer = setInterval(() => { if ((el('main').textContent + el('aside').textContent).includes('Reading…')) flash++; }, 50); }, + peek() { return { counts: JSON.parse(JSON.stringify(counts)), flash }; }, + stop() { clearInterval(timer); const fresh = {}; for (const id of ids) fresh[id] = [...el(id).querySelectorAll('*')].filter(e => !e.__seen).length; const r = { counts, flash, fresh, scrolls: scrolls(), needsOpen: !el('needs-panel').hidden }; counts = null; return r; }, + scrolls, + /** Scrolls the main area, every element in it and in the drawer that overflows (a little), and the drawer. */ + scrollAll() { + const main = el('main'), drawer = el('drawer'), bit = (e, x, y) => { if (e.scrollWidth > e.clientWidth + 1) e.scrollLeft = Math.min(x, e.scrollWidth - e.clientWidth); if (e.scrollHeight > e.clientHeight + 1) e.scrollTop = Math.min(y, e.scrollHeight - e.clientHeight); }; + for (const top of [main, el('aside')]) for (const e of top.querySelectorAll('*')) bit(e, 37, 41); + bit(main, 23, 160); if (drawer.classList.contains('open')) bit(drawer, 0, 90); + return scrolls(); + } + }; +})(); true`; +async function start() { await evaluate(`window.__still.start(); true`); } +async function stopWatch() { return evaluate(`window.__still.stop()`); } +const touched = (r, ids) => ids.filter(id => { const c = r.counts[id]; return c.added || c.removed || c.attrs || c.text || r.fresh[id]; }).map(id => id + ' ' + JSON.stringify(r.counts[id]) + ' new ' + r.fresh[id]); + +(async () => { + let folder; + if (labRoot) folder = labRoot; + else { + // ---- The fixture: minimal + buildable + a stand-in recipe of about a minute, in Git ---------------- + fs.cpSync(path.join(root, 'tests', 'fixtures', 'tuldok_project', 'minimal'), path.join(temporary, 'fixture'), { recursive: true }); + folder = path.join(temporary, 'fixture', 'project'); + const code = path.join(temporary, 'fixture', 'code'), buildable = path.join(root, 'tests', 'fixtures', 'tuldok_project', 'buildable'); + for (const kind of ['environments', 'datasets', 'recipes', 'benchmarks', 'charts']) for (const name of fs.readdirSync(path.join(buildable, 'project', kind))) fs.copyFileSync(path.join(buildable, 'project', kind, name), path.join(folder, kind, name)); + for (const name of fs.readdirSync(path.join(buildable, 'code'))) fs.cpSync(path.join(buildable, 'code', name), path.join(code, name), { recursive: true }); + fs.writeFileSync(path.join(code, 'steady.py'), `import json, os, sys, time +out = sys.argv[sys.argv.index('--out') + 1] +for step in range(1, 121): + print(json.dumps({'format': 'tuldok_progress_v1', 'stage': 'fit', 'completed': step, 'total': 120, 'metrics': {'loss': 1.0 / step}}), flush=True) + print('step', step, 'of 120', file=sys.stderr, flush=True) + time.sleep(0.5) +with open(os.path.join(out, 'weights.json'), 'w') as handle: + json.dump({'constant': 3.0}, handle) +`); + fs.writeFileSync(path.join(folder, 'recipes', 'steady.json'), JSON.stringify({ format: 'tuldok_definition_v1', kind: 'recipe', title: 'Steady fit, about a minute', labels: { short: 'STEADY' }, change: 'refinement', derived_from: 'recipes/fit-a', + run: { command: ['python', 'steady.py', '--out', '{output}'], environment: 'environments/test-python', outputs: { weights: { path: 'weights.json', role: 'weights' } }, sources: ['steady.py'] } }, null, 2) + '\n'); + const git = ['-c', 'user.name=Tuldok Test', '-c', 'user.email=test@example.invalid', '-c', 'commit.gpgsign=false', '-c', 'init.defaultBranch=main', '-C', path.join(temporary, 'fixture')]; + execFileSync('git', [...git, 'init', '-q']); execFileSync('git', [...git, 'add', '-A']); execFileSync('git', [...git, 'commit', '-q', '-m', 'The fixture.']); + } + const home = path.join(temporary, 'home'), catalog = path.join(temporary, 'catalog'); fs.mkdirSync(home); + const env = { ...process.env, TULDOK_PROJECT_HOME: home, TULDOK_SETTINGS: path.join(temporary, 'settings.json') }; + owned = [folder, catalog]; dropOwned(folder, catalog); + if (!labRoot) { + const cli = (...args) => execFileSync(python, ['-m', 'tuldok_project', ...args], { cwd: root, env, stdio: ['ignore', 'pipe', 'pipe'] }).toString(); + cli('connect', folder, 'test-python', python); + cli('build', folder, 'datasets/numbers', '--yes'); // a run and a product, for the run's and the dataset's drawers + } + let output = ''; + server = launch(python, ['-u', 'app.py', '--port', '0', '--data', catalog, '--project-folder', folder], { cwd: root, env, stdio: ['ignore', 'pipe', 'pipe'] }); + server.stdout.on('data', chunk => { output += chunk; }); server.stderr.on('data', chunk => { serverErrors += chunk; }); + const port = await until(() => { if (server.exitCode !== null) throw Error('Tuldok exited: ' + serverErrors); return output.match(/127\.0\.0\.1:(\d+)/)?.[1]; }, 'Tuldok start-up', 3000); + origin = 'http://127.0.0.1:' + port; + auth = authenticatedFixture(); await auth.register(origin, catalog, root); + // A second session: an agent that may ask for builds (the fixture only). + const agent = labRoot ? null : await credential('A second session', ['inspect', 'execute']); + const firstAsk = agent ? await api('request_build', { targets: ['recipes/fit-b'] }, agent) : null; + if (firstAsk) assert.equal(firstAsk.state, 'awaiting-approval'); + + const browser = launch(findBrowser(), ['--headless', '--no-sandbox', '--disable-gpu', '--no-first-run', '--hide-scrollbars', '--remote-debugging-port=0', `--window-size=${WIDTH},${HEIGHT}`, '--user-data-dir=' + path.join(temporary, 'browser'), 'about:blank'], { stdio: 'ignore', env: { ...process.env, XDG_CONFIG_HOME: temporary, XDG_CACHE_HOME: temporary } }); + const debugPort = await waitForDebugger(browser, path.join(temporary, 'browser', 'DevToolsActivePort')); + const target = (await (await fetch('http://127.0.0.1:' + debugPort + '/json')).json()).find(item => item.type === 'page'); + socket = new WebSocket(target.webSocketDebuggerUrl); await once(socket, 'open'); + session = cdpSession(socket, { timeoutMs: 60000, onEvent: event => { + network(event); + if (event.method === 'Runtime.exceptionThrown') errors.push(event.params.exceptionDetails.exception?.description || event.params.exceptionDetails.text); + if (event.method === 'Runtime.consoleAPICalled' && event.params.type === 'error') errors.push(event.params.args.map(a => a.value ?? a.description).join(' ')); + if (event.method === 'Log.entryAdded' && event.params.entry.level === 'error' && !offline) errors.push(event.params.entry.text + ' ' + (event.params.entry.url || '')); + if (event.method === 'Network.loadingFailed' && !event.params.canceled && !offline) failures.push({ id: event.params.requestId, error: event.params.errorText }); + if (event.method === 'Network.responseReceived' && event.params.response.status >= 400) failures.push({ url: event.params.response.url, status: event.params.response.status }); + } }); + send = session.send; + evaluate = async expression => { const result = await send('Runtime.evaluate', { expression, awaitPromise: true, returnByValue: true }); if (result.exceptionDetails) throw Error(JSON.stringify(result.exceptionDetails)); return result.result.value; }; + await send('Page.enable'); await send('Runtime.enable'); await send('Network.enable'); await send('Log.enable'); + await send('Emulation.setDeviceMetricsOverride', { width: WIDTH, height: HEIGHT, deviceScaleFactor: 1, mobile: false }); + await send('Emulation.setEmulatedMedia', { features: [{ name: 'prefers-reduced-motion', value: 'reduce' }] }); + await auth.browser(send, origin); // the owner's session, so the controls are drawn + await send('Page.navigate', { url: origin + '/?theme=light#map' }); + await until(() => evaluate(`document.readyState === 'complete' && !!document.getElementById('needs-btn') && !document.getElementById('needs-btn').disabled`), 'the project read', 1200); + await settled('opened'); + await evaluate(WATCHER); + + // ---- 1. Nothing changed ------------------------------------------------------------------------ + const map = await api('map'), runs = (await api('runs')).runs, requests = (await api('build_requests')).requests; + const datasets = (await api('definitions', { kind: 'dataset' })).definitions.filter(d => !d.removed); + const model = (map.models[Math.min(40, map.models.length - 1)] || {}).reference; + const enc = s => encodeURIComponent(s); + const places = [ + ['Map', 'map'], ['Map, a model\'s drawer', 'map/' + enc(model)], ['Map, the editor', 'map/' + enc('edit:' + model)], ['Map, the plan view', 'map/' + enc('plan:' + model)], + ['Data', 'data'], datasets.length ? ['Data, a dataset\'s drawer', 'data/' + enc(datasets[0].reference)] : null, + ['Train', 'train'], runs.length ? ['Train, a run\'s drawer', 'train/' + enc('run:' + runs[0].id)] : null, requests.length ? ['Train, a build request\'s drawer', 'train/' + enc('request:' + requests[0].id)] : null, + ['Benchmarks', 'benchmarks'], ['Analysis', 'analysis'], ['Overview', 'overview'] + ].filter(Boolean); + const skipped = [!datasets.length && 'a dataset\'s drawer (no dataset)', !runs.length && 'a run\'s drawer (no run)', !requests.length && 'a build request\'s drawer (no request)'].filter(Boolean); + const ALL = ['tabs', 'strip', 'main', 'aside', 'needs-panel']; + const rows = []; + async function still(label, cause) { + const before = await evaluate(`window.__still.scrolls()`), since = Date.now(); + await start(); + if (cause === 'focus') { await evaluate(`window.dispatchEvent(new Event('focus')); true`); await reading(since, WATCHED.concat(['map']), label + ' on focus'); } + else await reading(since, WATCHED, label + ' on the timer', Math.round((IDLE_MS + 15000) / 100)); + const r = await stopWatch(); + assert.deepEqual(touched(r, ALL), [], label + ', ' + cause + ': nothing is touched'); + assert.equal(r.flash, 0, label + ', ' + cause + ': "Reading…" is never shown'); + assert.deepEqual(r.scrolls, before, label + ', ' + cause + ': every scroll position stays'); + rows.push(label + ' · ' + cause + ': 0 nodes added or removed, ' + Object.keys(before).length + ' scroll positions kept' + (r.counts.strip.readAt ? ', "Read at" ticked' : '')); + return { r, before }; + } + for (const [label, place] of places) { + await hash(place); + if (place === 'map' || place.startsWith('map/')) await evaluate(`(() => { const t = document.querySelector('#main .tree-map'); if (t) { t.scrollLeft = 2000; t.scrollTop = 30; } const l = document.querySelector('#main .tree-host'); if (l) l.scrollTop = 400; return true; })()`); + const set = await evaluate(`window.__still.scrollAll()`); + await pause(200); + await still(label + ' (' + Object.keys(set).length + ' scrolled)', 'focus'); + if (place === 'train') await still(label, 'timer'); + if (place === 'overview') { + await press('#needs-btn'); await until(() => evaluate(`!document.getElementById('needs-panel').hidden && !!document.querySelector('#needs-panel .needs')`), 'Needs you open'); await pause(200); + await evaluate(`document.getElementById('needs-panel').scrollTop = 20; true`); + for (const cause of ['focus', 'timer']) { const { r } = await still('Overview with Needs you open', cause); assert.ok(r.needsOpen, 'Needs you stays open'); } + await press('#needs-btn'); await until(() => evaluate(`document.getElementById('needs-panel').hidden`), 'Needs you closed'); + } + } + check('1. Nothing changed (' + places.length + ' places' + (skipped.length ? '; not on this project: ' + skipped.join(', ') : '') + '):\n ' + rows.join('\n ')); + + if (!labRoot) { + // ---- 2. Something changed elsewhere ---------------------------------------------------------- + await hash('train'); + const trainScroll = await evaluate(`(() => { const m = document.getElementById('main'); m.scrollTop = Math.min(140, m.scrollHeight - m.clientHeight); return [m.scrollLeft, m.scrollTop]; })()`); + assert.ok(trainScroll[1] > 0, 'Train scrolls at this size: ' + JSON.stringify(trainScroll)); + const focusKey = await evaluate(`(() => { const b = [...document.querySelectorAll('#main .act-group button')].find(b => { const r = b.getBoundingClientRect(); return r.top > 120 && r.bottom < innerHeight; }) || document.querySelector('#main .act-group button'); b.focus({ preventScroll: true }); return b.dataset.key; })()`); + assert.ok(focusKey, 'A control of Train is focused'); + const count0 = await needsCount(); + await start(); const asked = Date.now(); + const second = await api('request_build', { targets: ['recipes/steady'] }, agent); + assert.equal(second.state, 'awaiting-approval'); + await until(async () => (await needsCount()) === count0 + 1 && await evaluate(`!!document.querySelector('#main ${byKey('open-request:' + second.id)}')`), 'the strip and Train show the request', Math.round((IDLE_MS + 10000) / 100)); + const shownAfter = Date.now() - asked; + await settled('shown'); await pause(300); + const r2 = await stopWatch(); + assert.equal(r2.flash, 0, '"Reading…" is never shown on Train'); + assert.deepEqual(r2.scrolls.main, trainScroll, 'The scroll of Train stays'); + assert.equal(await evaluate(`document.activeElement && document.activeElement.dataset.key`), focusKey, 'The focus stays on the control'); + assert.ok(r2.counts.main.added > 0 && r2.counts.tabs.added === 0, 'Train was drawn again in place, the tab bar was not: ' + JSON.stringify([r2.counts.main, r2.counts.tabs])); + await send('Emulation.setDeviceMetricsOverride', { width: WIDTH, height: 420, deviceScaleFactor: 1, mobile: false }); // so the request's drawer scrolls + await hash('train/' + enc('request:' + second.id)); + assert.equal(await drawerState(), 'awaiting approval'); + const drawerScroll = await evaluate(`(() => { const d = document.getElementById('drawer'); d.scrollTop = Math.min(60, d.scrollHeight - d.clientHeight); return d.scrollTop; })()`); + assert.ok(drawerScroll > 0, 'The request\'s drawer scrolls at this size'); + await start(); + await api('approve_build', { request: second.id }); + const seen = await until(async () => { const s = await drawerState(); return s !== 'awaiting approval' ? s : null; }, 'the drawer shows the request approved', Math.round((IDLE_MS + 10000) / 100)); + await settled('approved'); await pause(300); + const r3 = await stopWatch(); + assert.equal(r3.flash, 0, '"Reading…" is never shown in the drawer'); + assert.equal(r3.scrolls.drawer[1], drawerScroll, 'The drawer keeps its scroll'); + await send('Emulation.setDeviceMetricsOverride', { width: WIDTH, height: HEIGHT, deviceScaleFactor: 1, mobile: false }); + check('2. A second session asked for a build (' + second.id.slice(0, 8) + '): within ' + (shownAfter / 1000).toFixed(1) + ' s (one reading) the strip said "Needs you · ' + (count0 + 1) + '" and Train listed it, with no "Reading…", the scroll (' + trainScroll.join(',') + ') and the focus (' + focusKey + ') kept; approved from outside the page, its drawer turned to "' + seen + '" in place, its scroll (' + drawerScroll + ') kept'); + + // ---- 3. A build runs ------------------------------------------------------------------------------ + const run = await until(async () => (await api('build_request', { request: second.id })).runs.find(x => x.state === 'running'), 'the steady run running', 600); + await hash('train/' + enc('run:' + run.id)); + const stripWidths = new Set(), drawerLines = new Set(); + for (let i = 0; i < 40 && (stripWidths.size < 3 || drawerLines.size < 3); i++) { + const v = await evaluate(`(() => { const s = document.querySelector('#strip .hair i'), p = document.querySelector('#aside .progress-line'); return [s ? s.style.width : null, p ? p.textContent : null]; })()`); + if (v[0]) stripWidths.add(v[0]); if (v[1]) drawerLines.add(v[1]); + await pause(500); + } + assert.ok(stripWidths.size >= 2, 'The strip\'s hairline moves: ' + [...stripWidths]); + assert.ok(drawerLines.size >= 2, 'The run\'s drawer reads on: ' + [...drawerLines]); + const logLines = await evaluate(`document.querySelector('#aside pre[data-log="stdout"]').textContent.split('\\n').length`); + // The run's row in Train's list reads on too, in place: its line changes and no node is added or removed. + await hash('train'); + const rowLine = `(() => { const l = document.querySelector('#main button.row.run[data-run=${JSON.stringify(run.id)}] .sub.live'); return l ? l.textContent : null; })()`; + await until(() => evaluate(rowLine), 'the run\'s row shows its progress', 100); + await start(); + const rowLines = new Set(); + for (let i = 0; i < 30 && rowLines.size < 3; i++) { const v = await evaluate(rowLine); if (v) rowLines.add(v); await pause(500); } + const rRow = await stopWatch(); + assert.ok(rowLines.size >= 2, 'The run\'s row in Train\'s list reads on: ' + [...rowLines]); + assert.equal(rRow.counts.main.added + rRow.counts.main.removed + rRow.fresh.main, 0, 'Train\'s list gains no node while its row reads on: ' + JSON.stringify(rRow.counts.main)); + assert.equal(rRow.flash, 0, '"Reading…" is never shown on Train while the run runs'); + // Short and zoomed in, so the map and the list scroll with room to spare when the strip changes height as the run ends. + await send('Emulation.setDeviceMetricsOverride', { width: WIDTH, height: 520, deviceScaleFactor: 1, mobile: false }); + await hash('map/' + enc('recipes/steady')); + for (let i = 0; i < 3; i++) { await press('#main .zoomctl button[aria-label="Zoom in"]'); await settled('zoom'); } + const stripRunning = await evaluate(`document.getElementById('strip').offsetHeight`); + await evaluate(`(() => { const set = (e, x, y) => { e.scrollLeft = Math.max(0, Math.min(x, e.scrollWidth - e.clientWidth - 60)); e.scrollTop = Math.max(0, Math.min(y, e.scrollHeight - e.clientHeight - 60)); }; set(document.querySelector('#main .tree-map'), 120, 20); set(document.querySelector('#main .tree-host'), 0, 60); return true; })()`); + const mapScroll = await evaluate(`[document.querySelector('#main .tree-map'), document.querySelector('#main .tree-host')].map(e => [Math.round(e.scrollLeft), Math.round(e.scrollTop)])`); + assert.ok(mapScroll.some(([x, y]) => x || y), 'The map or the list scrolls at this size: ' + JSON.stringify(mapScroll)); + const planned = () => evaluate(`/\\bplanned\\b/.test(document.querySelector('#main .tree-map .node[data-id="recipes/steady"]').getAttribute('class'))`); + assert.ok(await planned(), 'The steady model is drawn never built while it runs'); + await start(); + // A sample of the page taken before the server still says running was taken while the run ran. + let last = null, samples = 0; + await until(async () => { + const v = await evaluate(`(() => { const n = document.querySelector('#main .tree-map .node[data-id="recipes/steady"]'); return { planned: !!n && /\\bplanned\\b/.test(n.getAttribute('class')), main: window.__still.peek().counts.main }; })()`); + const st = (await api('run', { run: run.id })).state; + if (['queued', 'running'].includes(st)) { samples++; assert.equal(v.main.added + v.main.removed, 0, 'The main area of the Map gains no node while the run runs: ' + JSON.stringify(v.main)); last = v; return false; } + return !v.planned; + }, 'the steady model drawn built', 1500); + await until(async () => (await drawerState()).startsWith('built'), 'its drawer says built', 200); + await settled('built'); + const r4 = await stopWatch(); + const after = await evaluate(`[document.querySelector('#main .tree-map'), document.querySelector('#main .tree-host')].map(e => [Math.round(e.scrollLeft), Math.round(e.scrollTop)])`); + const stripEnded = await evaluate(`document.getElementById('strip').offsetHeight`); + assert.deepEqual(after, mapScroll, 'The map and the list keep their scroll when the map is drawn again'); + await send('Emulation.setDeviceMetricsOverride', { width: WIDTH, height: HEIGHT, deviceScaleFactor: 1, mobile: false }); + assert.equal(r4.flash, 0, '"Reading…" is never shown while the run ends'); + assert.equal((await api('run', { run: run.id })).state, 'succeeded'); + check('3. While the steady build ran, the strip\'s hairline read ' + [...stripWidths].join(', ') + ' and the run\'s drawer read on (' + drawerLines.size + ' progress lines, ' + logLines + ' log lines); its row in Train\'s list read on in place (' + rowLines.size + ' lines, no node added or removed); on the Map tab the main area gained no node over ' + samples + ' samples until the run ended (attributes changed: ' + (last ? last.main.attrs : 0) + '); then the model was drawn built, the map and the list kept their scroll ' + JSON.stringify(after) + ' (the strip ' + stripRunning + ' px high while it ran, ' + stripEnded + ' px after), and "Reading…" was never shown'); + + // ---- 4. The editor is left alone ------------------------------------------------------------------ + await hash('map/' + enc('edit:recipes/fit-a')); + await press(byKey('editor:recipes/fit-a:description')); + await send('Input.insertText', { text: 'Typed here and not kept.' }); + await evaluate(`(() => { const e = document.activeElement; e.setSelectionRange(5, 5); return true; })()`); + const typed = await evaluate(`({ key: document.activeElement.dataset.key, value: document.activeElement.value, caret: document.activeElement.selectionStart })`); + const count1 = await needsCount(); + await start(); + const third = await api('request_build', { targets: ['recipes/fit-a'] }, agent); + await until(async () => (await needsCount()) === count1 + 1, 'the strip shows the second request', Math.round((IDLE_MS + 10000) / 100)); + await settled('third'); await pause(300); + const since = Date.now(); await evaluate(`window.dispatchEvent(new Event('focus')); true`); await reading(since, WATCHED.concat(['map']), 'focus with the editor'); + const r5 = await stopWatch(); + assert.deepEqual(touched(r5, ['aside']), [], 'The editor\'s drawer is not touched'); + assert.ok(r5.counts.strip.added > 0, 'The strip was drawn again'); + assert.deepEqual(await evaluate(`({ key: document.activeElement.dataset.key, value: document.activeElement.value, caret: document.activeElement.selectionStart })`), typed, 'The typed text, the focus and the caret stay'); + check('4. With "' + typed.value + '" typed into fit-a\'s description (caret at ' + typed.caret + '), a second request (' + third.id.slice(0, 8) + ') reached the strip and the window regained focus: the drawer was not touched, the text, focus and caret are there'); + void firstAsk; + + // ---- 5. A reading that fails leaves the page alone ------------------------------------------------ + await hash('overview'); + await evaluate(`window.__still.scrollAll()`); await pause(200); + const before5 = await evaluate(`window.__still.scrolls()`); + await start(); + offline = true; + await send('Network.emulateNetworkConditions', { offline: true, latency: 0, downloadThroughput: -1, uploadThroughput: -1 }); + await evaluate(`window.dispatchEvent(new Event('focus')); true`); + await until(() => evaluate(`/Not read/.test(document.getElementById('strip').textContent)`), 'the strip says the project was not read', 200); + const said = await evaluate(`document.getElementById('strip').textContent.trim().replace(/\\s+/g, ' ')`); + await send('Network.emulateNetworkConditions', { offline: false, latency: 0, downloadThroughput: -1, uploadThroughput: -1 }); + await pause(500); offline = false; + const back = Date.now(); await evaluate(`window.dispatchEvent(new Event('focus')); true`); await reading(back, WATCHED.concat(['map']), 'focus once the server answers again'); + await until(() => evaluate(`!/Not read/.test(document.getElementById('strip').textContent)`), 'the strip says where the project stands again', 100); + const r6 = await stopWatch(); + assert.deepEqual(touched(r6, ['tabs', 'main', 'aside', 'needs-panel']), [], 'A reading that failed, and the one after it, touch nothing but the strip'); + assert.equal(r6.flash, 0, '"Reading…" is never shown when a reading fails'); + assert.deepEqual(r6.scrolls, before5, 'Every scroll position stays when a reading fails'); + check('5. Cut off from the server, the page kept Overview as it was and the strip said: "' + said.slice(0, 160) + '"; when the server answered again the strip said where the project stands, and nothing else was touched'); + } + + // ---- Nothing failed ------------------------------------------------------------------------------ + assert.deepEqual(errors, [], 'Script errors'); + assert.deepEqual(failures, [], 'Failed requests'); + check('No script error, no failed request'); + fs.writeFileSync(path.join(report, 'receipt.json'), JSON.stringify({ status: 'pass', folder, checks }, null, 2) + '\n'); + console.log('Receipt in ' + report); +})().catch(async error => { + process.exitCode = 1; + console.error(error); if (serverErrors) console.error('Server:', serverErrors.slice(-4000)); + console.error('Script errors:', JSON.stringify(errors)); console.error('Failed requests:', JSON.stringify(failures)); + try { if (evaluate) console.error('Page:', (await evaluate('document.body.innerText')).slice(0, 2000)); } catch (_) { /* the page is gone */ } + fs.writeFileSync(path.join(report, 'failure.json'), JSON.stringify({ status: 'failed', error: String(error && error.stack || error), checks, errors, failures }, null, 2) + '\n'); +}).finally(async () => { + try { session?.close(); } catch (_) { /* closed */ } + for (const child of children.reverse()) await stop(child); + if (owned) try { dropOwned(...owned); } catch (error) { console.error('Dropping the disposable schemas failed:', error.message); process.exitCode = 1; } + try { execFileSync('chmod', ['-R', 'u+w', temporary]); } catch (_) { /* nothing was made read-only */ } // finished runs leave their directories read-only + fs.rmSync(temporary, { recursive: true, force: true }); +}); From 68a012af487481007fad1a9f6d38dae4527c1614 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 12 Nov 2026 19:22:36 -0700 Subject: [PATCH 053/131] docs(plan): record the in-place update of the workspace in the ledger Co-Authored-By: Claude Fable 5.2 --- .../execution-ledger.md | 35 +++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/docs/plans/definition-first-projects/execution-ledger.md b/docs/plans/definition-first-projects/execution-ledger.md index d6b2a22b..b16dbf2c 100644 --- a/docs/plans/definition-first-projects/execution-ledger.md +++ b/docs/plans/definition-first-projects/execution-ledger.md @@ -513,3 +513,38 @@ Screenshots: `build/qa/project-workspace-acceptance/final/` (21) and, for the ow **Seen, not Tuldok's:** this machine's zone is America/Vancouver, which the system clock gives as UTC−7 in November; the headless browser and Node carry older zone data and show times an hour earlier. A browser with current zone data shows the right hour. **Next:** the owner looks at phase 3 on the lab project. Then the capability check can be signed and the old project mode deleted (milestone 8, part 3). + +## 2026-11-12 — the owner looks at phase 3; the workspace updates in place + +**Owner, on phase 3 on the lab project:** "looks ok. continue", and then: "one thing, im noticing there is a full page reset when it should just be updating info on the page instead". Phase 3 is accepted with that one fault. The capability check is not signed by these words; it was brought up to date and its losses put to the owner again. + +Spec: [spec-w4.md](spec-w4.md). **Commits** (none pushed), Tuldok `feat/definition-first-projects`: the spec, part 3 of [spec-m8.md](spec-m8.md) and the capability check `4f206bbd`; the fix and its check, the commit before this entry. + +**What was measured before** (the lab folder, owner signed in, nothing changing; elements of the main area that were new nodes afterwards): + +| Tab | On return to the window | Every 15 s while idle | +| --- | --- | --- | +| Map | none | none | +| Data | all 356 | none | +| Train | all 64 | all 64 | +| Benchmarks | all 2,109 | none | +| Analysis | all 159 | none | +| Overview | all 2,336 | all 2,336 | + +The tab bar was rebuilt with each of those, the strip on every reading, and the sideways scroll inside tables was lost. The reading every fifteen seconds had been added at phase 3's acceptance, where only its cost was measured, not what it redrew. + +**After:** none, in every cell, with the model's drawer and the editor open as well; no strip or tab-bar node added; every scroll position kept. The same measurement is now a check, `tests/browser_project_workspace_still.cjs` (about 2 min 40 s on the fixture, 1 min on the lab folder read only): nothing touched on twelve places when nothing changed; a build asked for by a second session shown within one reading with the scroll and the focus kept and no "Reading…"; a drawer brought up to date in place; a running build's progress set in place in the strip, the run's drawer and its row of Train's list while the Map gains no node; the editor with typed text left alone; and the page kept as it is when the server cannot be reached. + +**How.** One slice by an agent, then review. The page compares the text of each watched answer (`summary`, `status`, `build_requests`, `environments`, `runs`, and `map` when it can have changed) with the one it holds, and draws nothing when none differs. When one does, the tab and the drawer are built off the page and put in place whole, in one step. No element is kept from an older drawing when its content is drawn again, so a control never acts on older answers than it was drawn from. + +**Changed in review:** + +- As first built, a running run's progress line in Train's list and Overview's "Read at" went stale until a watched answer changed. Both are now set in place on every reading. +- As first specified, a watched answer that was refused counted as a change, which emptied the tab on screen whenever the server could not be reached for a moment. A reading that fails now changes nothing: the page stays, the strip says "Not read" and why, and the timer asks again. +- `tests/browser_project_workspace_actions.cjs` failed twice in a row at one assertion made the moment a control stopped being busy; the drawer is now redrawn by the reading that follows, a few milliseconds later. Its `settled()` waits for the page's own requests; no assertion changed, and it then passed twice. + +**Tests on the final code:** project suite 585; agent interface 44 (4 skipped); HTTP 17; `browser_project_workspace.cjs` on its fixture and on the lab folder; `browser_project_workspace_actions.cjs` (27 steps, twice); `browser_project_workspace_still.cjs` on its fixture (twice) and on the lab folder. The lab folder was unchanged throughout. + +**Not verified:** the new check in the dark theme; a reading that fails while a build runs; widths other than those the checks use (1280 and 1440). Each browser check asserts at one moment after waiting; on a busy machine a wait may still prove short. + +**Next:** the owner looks at the page again. The deletion of the old project mode is being prepared on the side branch `chore/retire-old-project-mode` and lands only when the capability check is signed. From a6993c009c224e87ad2eec1a83a302b0c068fba7 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 12 Nov 2026 22:05:58 -0700 Subject: [PATCH 054/131] docs(plan): the capability check as the prepared deletion found it The deletion of the old project mode is prepared on the side branch chore/retire-old-project-mode. Preparing it corrected three figures here: project_cli.py is also catalog mode's command line and stays (37 modules go, not 38); twelve import statements tie the old code to catalog mode, not eight; the tests of the old mode are 72 Python and 18 JavaScript files. A new section says what the prepared deletion removes and how it was checked. Not signed; nothing is deleted on this branch. Co-Authored-By: Claude Fable 5.2 --- .../capability-check.md | 34 ++++++++++++++----- 1 file changed, 26 insertions(+), 8 deletions(-) diff --git a/docs/plans/definition-first-projects/capability-check.md b/docs/plans/definition-first-projects/capability-check.md index 03202a2d..46bebe12 100644 --- a/docs/plans/definition-first-projects/capability-check.md +++ b/docs/plans/definition-first-projects/capability-check.md @@ -1,6 +1,6 @@ # Capability check: what deleting the old project mode removes -**Status: written 2026-11-12 for the owner's sign-off, and brought up to date the same evening after the Map workspace was built and the owner had looked at it. Not signed. Nothing is deleted until it is.** +**Status: written 2026-11-12 for the owner's sign-off, and brought up to date the same evening after the Map workspace was built and the owner had looked at it. Not signed. Nothing is deleted until it is. The deletion is prepared and checked on a side branch ("The deletion as prepared", below) and reaches this branch only on sign-off.** The [plan](plan.md) deletes the old project-files mode in milestone 8 on one condition: a written check that lists every capability of that mode as covered, moved or deliberately dropped, signed off by the owner. This is that check. It is a list of what Tuldok can do today through `python app.py --project-files-root ...` and what happens to each thing when that mode is gone. @@ -22,17 +22,19 @@ Two more follow from the deletion itself: the lab's old project folder (`project | What | Size | | --- | --- | -| 38 Python modules that only the old mode reaches | 20,854 lines | -| The old project page and the extraction page, with their scripts and styles under `static/` | 3,263 lines in 10 files | +| 37 Python modules that only the old mode reaches | 20,437 lines | +| The old project page and the extraction page, with their scripts and styles under `static/` | 3,264 lines in 11 files | | 145 `project_files.*` and 5 `project_transfer.*` operations in `agent_api.py`, the `project` capability profile, the two owner clients and their `mcp_stdio.py` flags | | -| 74 test files that import one of those modules | 21,791 lines | +| The old mode's tests: 72 Python files and 18 JavaScript files | 22,675 lines | | The documentation of the old mode under `docs/contracts/`, the runbooks and the READMEs. Its plans and ledgers under `docs/plans/` stay, as the record | | -The 38 modules: `project_artifacts`, `project_cli`, `project_composition`, `project_custody`, `project_data`, `project_data_fork`, `project_dispatch`, `project_execution`, `project_extraction`, `project_files`, `project_fork`, `project_fork_composition`, `project_history`, `project_locks`, `project_material`, `project_material_fork`, `project_measurements`, `project_native_execution`, `project_native_preparation`, `project_native_process`, `project_producer_execution`, `project_producers`, `project_projection`, `project_record_dedupe`, `project_runtime`, `project_session`, `project_sources`, `project_store`, `project_study_execution`, `project_text`, `project_transfer`, `project_transfer_controller`, `project_validation_cache`, `project_validation_delta`, `project_working_store`, `project_workspace`, `retained_measurements`, `native_process_bootstrap`. +The 37 modules: `project_artifacts`, `project_composition`, `project_custody`, `project_data`, `project_data_fork`, `project_dispatch`, `project_execution`, `project_extraction`, `project_files`, `project_fork`, `project_fork_composition`, `project_history`, `project_locks`, `project_material`, `project_material_fork`, `project_measurements`, `project_native_execution`, `project_native_preparation`, `project_native_process`, `project_producer_execution`, `project_producers`, `project_projection`, `project_record_dedupe`, `project_runtime`, `project_session`, `project_sources`, `project_store`, `project_study_execution`, `project_text`, `project_transfer`, `project_transfer_controller`, `project_validation_cache`, `project_validation_delta`, `project_working_store`, `project_workspace`, `retained_measurements`, `native_process_bootstrap`. + +`project_cli.py` was listed here as a 38th module until the deletion was prepared. It stays: it is also catalog mode's command line for agents (`open`, `inspect`, `preflight`, `submit`, `status`, `download` and the rest), and tests that stay use it. It loses only the old mode's commands, `file-*` and `project-transfer`, and the flag `--owner-project-files`. **What stays:** every remaining operation's contract, unchanged; catalog mode and everything it uses, including `projects.py` and `project_activity.py` (catalog mode's read-only inspection of project snapshots with `--project-root`), the access layer, the agent registry and clients, and the new `tuldok_project` package. -**Where the old code is tied to catalog mode.** Eight import lines in three files reach into the 38 modules, so they change before anything is deleted: +**Where the old code is tied to catalog mode.** Twelve import statements in three files reach into the 37 modules, so they change before anything is deleted: | File | What it imports | What happens | | --- | --- | --- | @@ -62,7 +64,7 @@ Outside the operations: | Capability | After deletion | | --- | --- | -| The old command line, `project_cli.py` | Replaced by `python -m tuldok_project` | +| The old mode's commands in `project_cli.py` (`file-*`, `project-transfer`) | Gone. A project folder has `python -m tuldok_project`. The rest of `project_cli.py` is catalog mode's and stays | | Opening the lab's old folder (`projects/rheon-model-portfolio-unified-04`) in Tuldok | Gone. The lab's converter reads that folder's files directly, and the old code stays in Git history | | The old project page (`/project-files`), about twenty stacked form panels | Gone. The Map workspace is the project's interface | | Byte-identical save, receipts, custody and checkpoint proofs | Dropped, as the plan decided | @@ -75,7 +77,23 @@ These come first, so the deletion removes nothing the lab still needs: 2. **Done.** The lab repository holds the new folder only, and the clean-install test of the plan's summary passed on fresh clones. 3. **Done.** A `new` command exists. 4. **Done.** The Map workspace is built in three phases and the owner has looked at each. -5. **Part of the deletion.** The eight import lines above are cut and catalog mode's tests pass. +5. **Part of the deletion.** The twelve import statements above are cut and catalog mode's tests pass. + +## The deletion as prepared + +Prepared 2026-11-12 on the branch `chore/retire-old-project-mode`, in a working tree of its own. It is not on this branch. What it changes file by file, and each check with its result, is section 10.6 of [spec-m8.md](spec-m8.md) on that branch. In short: + +| | | +| --- | --- | +| Removed | 143 files, 47,099 lines: 37 modules, 72 Python and 18 JavaScript test files, 11 files under `static/`, one script, four documents. 2,446 more lines are cut from 16 files that stay | +| Contracts | Every operation that remains is published byte for byte as before, in the `catalog` and the `project_folder` profile. The catalog's list goes from 115 operations to 110: the five `project_transfer.*` entries, which it listed as unavailable. The `project` profile is refused. The 145 `project_files.*` and 5 `project_transfer.*` operations are offered nowhere | +| Python tests | 3,149 before; 2,397 after, which is 3,149 less the 751 tests of the deleted files and one test of a deleted client class. No test that stays is newly skipped. One test that stays had to change: it pinned the digest of the whole catalog list and of the `project` profile, so it now pins the list without the five entries and checks that the old profile is refused. 23 tests fail before and after alike, none of them from the change: this machine has no training environment (numpy, scikit-learn), the test database's user may not create databases, and three tests of the CPU snapshot refuse this machine's Python directories | +| Project folder tests | 585 before, 586 after (the new test of the refused profile), all passing | +| JavaScript | All 49 remaining `tests/test_*.cjs` pass; `node --check` passes on all 54 scripts under `static/` | +| Browser | The workspace checks pass on their fixture and on the lab folder, read only. Of the 62 catalog checks the workflow runs, 49 ran here and 45 pass. One fails in its own clean-up of a temporary directory, the same way on the unchanged code; three need packages only the workflow installs. 13 were not run: they need training, a GPU or generated fixtures | +| Start-up | `--help` shows none of the removed flags and each is an argument error; Tuldok starts in catalog mode on an empty data directory and with `--project-folder` on the tiny example | + +**Left for a later change.** About thirty lines in ten of catalog mode's files (`runs.py`, `synthetic.py`, the proposal modules and others) still ask the catalog for an attribute only the deleted modules set (`project_execution`, `project_sources`, `project_asset`, `project_availability`, `project_study_execution`). They can no longer be reached. They run through the code that starts and recovers runs, so removing them is its own reviewed change. `docs/decisions/external-project-authority.md`, the decision record of the old mode, stays as a record. ## Sign-off From 11a9d25aa494178846b03fed583b5a9e51a61fc4 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 12 Nov 2026 22:10:18 -0700 Subject: [PATCH 055/131] docs(plan): record that the deletion of the old project mode is prepared The deletion is on the side branch chore/retire-old-project-mode and is not landed: the capability check is unsigned. The ledger records how it was prepared and checked, what preparing it found, and what was not verified. Co-Authored-By: Claude Fable 5.2 --- .../capability-check.md | 2 +- .../execution-ledger.md | 29 +++++++++++++++++++ 2 files changed, 30 insertions(+), 1 deletion(-) diff --git a/docs/plans/definition-first-projects/capability-check.md b/docs/plans/definition-first-projects/capability-check.md index 46bebe12..44afbd02 100644 --- a/docs/plans/definition-first-projects/capability-check.md +++ b/docs/plans/definition-first-projects/capability-check.md @@ -85,7 +85,7 @@ Prepared 2026-11-12 on the branch `chore/retire-old-project-mode`, in a working | | | | --- | --- | -| Removed | 143 files, 47,099 lines: 37 modules, 72 Python and 18 JavaScript test files, 11 files under `static/`, one script, four documents. 2,446 more lines are cut from 16 files that stay | +| Removed | 143 files, 47,099 lines: 37 modules, 72 Python and 18 JavaScript test files, 11 files under `static/`, one script, four documents. 2,450 more lines are cut from 17 files that stay | | Contracts | Every operation that remains is published byte for byte as before, in the `catalog` and the `project_folder` profile. The catalog's list goes from 115 operations to 110: the five `project_transfer.*` entries, which it listed as unavailable. The `project` profile is refused. The 145 `project_files.*` and 5 `project_transfer.*` operations are offered nowhere | | Python tests | 3,149 before; 2,397 after, which is 3,149 less the 751 tests of the deleted files and one test of a deleted client class. No test that stays is newly skipped. One test that stays had to change: it pinned the digest of the whole catalog list and of the `project` profile, so it now pins the list without the five entries and checks that the old profile is refused. 23 tests fail before and after alike, none of them from the change: this machine has no training environment (numpy, scikit-learn), the test database's user may not create databases, and three tests of the CPU snapshot refuse this machine's Python directories | | Project folder tests | 585 before, 586 after (the new test of the refused profile), all passing | diff --git a/docs/plans/definition-first-projects/execution-ledger.md b/docs/plans/definition-first-projects/execution-ledger.md index b16dbf2c..2859624f 100644 --- a/docs/plans/definition-first-projects/execution-ledger.md +++ b/docs/plans/definition-first-projects/execution-ledger.md @@ -548,3 +548,32 @@ The tab bar was rebuilt with each of those, the strip on every reading, and the **Not verified:** the new check in the dark theme; a reading that fails while a build runs; widths other than those the checks use (1280 and 1440). Each browser check asserts at one moment after waiting; on a busy machine a wait may still prove short. **Next:** the owner looks at the page again. The deletion of the old project mode is being prepared on the side branch `chore/retire-old-project-mode` and lands only when the capability check is signed. + +## 2026-11-12 — milestone 8, part 3: the deletion of the old project mode is prepared, not landed + +**Status: prepared and checked on the side branch `chore/retire-old-project-mode`, one commit on top of this one. Nothing is deleted on this branch. The capability check is not signed.** + +**Why it is not landed.** The plan deletes the old mode only when the owner signs the capability check, and the owner signs by saying so. The owner was told twice that the deletion lands on the word "signed"; the replies were "continue", which is taken as leave to prepare it and not as the sign-off. + +**How.** Section 10 of [spec-m8.md](spec-m8.md). First the baseline: the capability manifests of both profiles saved, and the whole Python suite run on the unchanged branch. An agent cut the import statements that tied the old code to catalog mode; the machine was restarted at that point, which lost the agent and the first baseline run and kept the working tree. A second agent checked that first step, deleted, searched for what was left and gathered the evidence. In review every changed file's diff was read, the changed Python files were linted (no undefined name; the same warnings before and after), the manifests were compared again by a script of the reviewer's own, and the workflow file was parsed. + +**Found while preparing** (each is corrected in the capability check and in section 10.6 of the spec on the side branch): + +- `project_cli.py` is also catalog mode's command line, so it stays without its old-mode commands: 37 modules go, not 38. +- Twelve import statements tied the old code to catalog mode, not eight. +- A test of the kept code, `tests/test_tuldok_project_http.py`, pinned the digest of the whole catalog manifest and of the `project` profile, which the deletion changes by its own rule. It now pins the manifest without the five `project_transfer.*` entries (shown equal, entry by entry, to the earlier manifest with those five taken out) and a new test checks that the old profile is refused. +- About thirty lines in ten of catalog mode's files read an attribute that only the deleted modules set. They cannot be reached any more and are left for a change of their own, since they run through the code that starts and recovers runs. + +**Size:** 143 files and 47,099 lines deleted; 2,450 lines cut from 17 files that stay. + +**Tests:** + +- Contracts: every remaining operation published byte for byte as before in both profiles; the catalog's list 115 to 110 (the five `project_transfer.*` entries, listed as unavailable before); the `project` profile refused. +- Whole Python suite: 3,149 tests before with 40 not passing; 2,397 after with 25 not passing, of which 23 are the same tests failing for the same reasons of this machine (no training environment, a database user that may not create databases, three CPU snapshot tests) and two lines are the pinned digest. After that test was changed: project suite 586, agent interface and command line 67 (4 skipped). The whole suite was not run again after that change. +- JavaScript: all 49 remaining `tests/test_*.cjs`; `node --check` on 54 scripts. +- Browser: the three workspace checks on the fixture, two of them on the lab folder read only (unchanged before and after); 45 of the 49 catalog checks that can run here. +- Start-up: the removed flags are argument errors; catalog mode and `--project-folder` both start. + +**Not verified:** 13 catalog browser checks that need training, a GPU or generated fixtures, and three that need packages only the workflow installs; one catalog check fails removing its own temporary directory, on the unchanged code as well. The browser checks used Playwright's headless shell. Nothing ran on GitHub: nothing is pushed. + +**Next:** the owner's sign-off of the capability check. Then section 10.5: the words and the date recorded there and here, and the side branch brought onto this one. Separately, the unreachable lines in catalog mode's run code. From 8562c834e6103ece1101b90ee19b62ff05198706 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 12 Nov 2026 22:10:41 -0700 Subject: [PATCH 056/131] chore!: delete the old project-files mode Tuldok starts in two ways from here: catalog mode, unchanged, and a definition-first project folder (--project-folder). The old project mode (--project-files-root and what only it reached) is gone, as milestone 8 of docs/plans/definition-first-projects/plan.md decides. Prepared on this side branch; it reaches feat/definition-first-projects only when the owner signs the capability check. Removed: 37 modules that only the old mode reached; the project_files.* and project_transfer.* operations, the project capability profile and the two owner clients in agent_api.py with their mcp_stdio.py flags; the file-* and project-transfer commands of project_cli.py; the clients in tuldok_client.py; app.py's four start-up flags, routes and pages; the old pages under static/; the tests, script, workflow steps and documents of the old mode. 143 files and 47,099 lines deleted, 2,450 lines cut from 17 files that stay. Unchanged: every remaining operation is published byte for byte as before in the catalog and project_folder profiles. The catalog's list goes from 115 operations to 110 (the five project_transfer entries it listed as unavailable), so the test that pinned its digest pins the new one and a new test checks that the project profile is refused. Nothing in the database is dropped. project_cli.py stays: it is also catalog mode's command line. pipeline.py takes over native_admission_wall_seconds, which catalog mode also used. Lines in catalog mode's run code that read attributes only the deleted modules set are left for a change of their own. Section 10.6 of spec-m8.md records each check and its result. BREAKING CHANGE: --project-files-root, --project-runtime-source, --project-transfer-control and --project-transfer-root are no longer accepted, and the project_files.* and project_transfer.* operations no longer exist. Co-Authored-By: Claude Fable 5.2 --- .github/workflows/tests.yml | 125 -- agent_api.py | 1283 +---------- app.py | 294 +-- candidate_packages.py | 12 - docs/README.md | 1 - docs/contracts/project-cli.md | 5 - docs/contracts/project-files.md | 292 --- docs/contracts/project-folder.md | 6 +- docs/contracts/project-model-portfolio.md | 87 - docs/contracts/scientific-fields.md | 38 +- .../definition-first-projects/spec-m8.md | 36 + docs/runbooks/external-project-extraction.md | 255 --- docs/runbooks/project-composition.md | 54 - mcp_stdio.py | 15 +- native_process_bootstrap.py | 115 - pipeline.py | 28 +- project_artifacts.py | 463 ---- project_cli.py | 74 +- project_composition.py | 328 --- project_custody.py | 511 ----- project_data.py | 1466 ------------ project_data_fork.py | 275 --- project_dispatch.py | 451 ---- project_execution.py | 1057 --------- project_extraction.py | 836 ------- project_files.py | 522 ----- project_fork.py | 529 ----- project_fork_composition.py | 180 -- project_history.py | 1392 ------------ project_locks.py | 66 - project_material.py | 827 ------- project_material_fork.py | 202 -- project_measurements.py | 260 --- project_native_execution.py | 902 -------- project_native_preparation.py | 430 ---- project_native_process.py | 445 ---- project_producer_execution.py | 447 ---- project_producers.py | 1247 ----------- project_projection.py | 434 ---- project_record_dedupe.py | 124 -- project_runtime.py | 320 --- project_session.py | 656 ------ project_sources.py | 238 -- project_store.py | 1286 ----------- project_study_execution.py | 811 ------- project_text.py | 375 ---- project_transfer.py | 783 ------- project_transfer_controller.py | 309 --- project_validation_cache.py | 155 -- project_validation_delta.py | 119 - project_working_store.py | 634 ------ project_workspace.py | 763 ------- retained_measurements.py | 479 ---- scripts/generate_project_files_contracts.py | 35 - static/project-files.css | 22 - static/project-files.html | 347 --- static/project-files.js | 1956 ----------------- static/project-measurements.css | 14 - static/project-measurements.js | 323 --- static/project-model-portfolio.js | 188 -- static/project-progression.js | 117 - static/project-transfer.css | 2 - static/project-transfer.html | 91 - static/project-transfer.js | 203 -- static/retained-measurement-maxima.vl.json | 1 - tests/browser_model_portfolio.cjs | 129 -- tests/browser_project_file_deletion.cjs | 127 -- tests/browser_project_files.cjs | 187 -- tests/browser_project_files_m2.cjs | 273 --- tests/browser_project_files_m3.cjs | 128 -- tests/browser_project_files_m4.cjs | 115 - tests/browser_project_files_native.cjs | 105 - tests/browser_pumas_typed_server.py | 4 +- ...er_text_classification_proposals_server.py | 4 +- tests/model_portfolio_fixture.cjs | 16 - tests/test_agent_api.py | 8 - tests/test_measurement_comparison.py | 119 - tests/test_project_artifacts.py | 514 ----- tests/test_project_candidate_clients.py | 58 - tests/test_project_composition.py | 136 -- tests/test_project_composition_publication.py | 172 -- tests/test_project_composition_workspace.py | 87 - tests/test_project_control_paths.py | 121 - tests/test_project_custody.py | 364 --- tests/test_project_data.py | 458 ---- tests/test_project_data_fork.py | 123 -- tests/test_project_dispatch.py | 334 --- tests/test_project_execution.py | 569 ----- tests/test_project_execution_http.py | 283 --- tests/test_project_extraction.py | 681 ------ tests/test_project_file_deletion_clients.py | 84 - ...test_project_file_deletion_clients_http.py | 143 -- tests/test_project_files.py | 294 --- tests/test_project_files_clients.py | 574 ----- tests/test_project_files_fork_contracts.py | 62 - tests/test_project_files_http.py | 463 ---- tests/test_project_files_m2_http.py | 453 ---- tests/test_project_files_m4_clients.py | 255 --- tests/test_project_files_m4_clients_http.py | 202 -- tests/test_project_files_m4_http.py | 161 -- tests/test_project_files_material_http.py | 197 -- tests/test_project_files_owner_mcp.py | 264 --- tests/test_project_fork.py | 398 ---- tests/test_project_fork_composition.py | 365 --- tests/test_project_history.py | 825 ------- tests/test_project_material.py | 523 ----- tests/test_project_material_fork.py | 303 --- ...est_project_measurement_comparison_http.py | 73 - tests/test_project_measurement_reads.py | 108 - tests/test_project_measurements.py | 226 -- tests/test_project_measurements_clients.py | 115 - tests/test_project_model_portfolio.cjs | 47 - tests/test_project_model_portfolio_http.py | 84 - tests/test_project_native_clients.py | 131 -- tests/test_project_native_clients_http.py | 297 --- tests/test_project_native_execution.py | 721 ------ tests/test_project_native_extraction.py | 164 -- tests/test_project_native_preparation.py | 293 --- tests/test_project_native_process.py | 512 ----- tests/test_project_native_run.py | 292 --- tests/test_project_native_study.py | 517 ----- tests/test_project_note_deletion.py | 219 -- tests/test_project_producer_execution.py | 537 ----- tests/test_project_producers.py | 414 ---- tests/test_project_projection.py | 185 -- tests/test_project_publication_recovery.py | 116 - tests/test_project_receipt_validation.py | 204 -- tests/test_project_record_dedupe.py | 150 -- tests/test_project_runtime.py | 264 --- tests/test_project_runtime_clients.py | 119 - tests/test_project_runtime_http.py | 83 - tests/test_project_runtime_recovery_http.py | 242 -- tests/test_project_session.py | 380 ---- tests/test_project_session_freshness.py | 139 -- tests/test_project_sources.py | 244 -- tests/test_project_store.py | 758 ------- tests/test_project_study_execution.py | 716 ------ tests/test_project_text.py | 419 ---- tests/test_project_text_tag.py | 52 - tests/test_project_transfer.py | 533 ----- tests/test_project_transfer_clients.py | 156 -- tests/test_project_transfer_clients_http.py | 235 -- tests/test_project_transfer_controller.py | 345 --- tests/test_project_validation_cache.py | 105 - tests/test_project_validation_delta.py | 67 - tests/test_project_working_store.py | 231 -- tests/test_project_workspace.py | 350 --- tests/test_project_workspace_custody.py | 197 -- tests/test_retained_measurements.py | 154 -- tests/test_torch_runtime.py | 5 - tests/test_tuldok_project_http.py | 22 +- tests/test_workspace_project_candidate.cjs | 25 - .../test_workspace_project_file_deletion.cjs | 43 - tests/test_workspace_project_files.cjs | 267 --- tests/test_workspace_project_files_m4.cjs | 102 - tests/test_workspace_project_fork_text.cjs | 27 - tests/test_workspace_project_native.cjs | 41 - ...st_workspace_project_native_validation.cjs | 32 - tests/test_workspace_project_runtime.cjs | 47 - tests/test_workspace_project_transfer.cjs | 232 -- tuldok_client.py | 591 +---- 161 files changed, 101 insertions(+), 49549 deletions(-) delete mode 100644 docs/contracts/project-files.md delete mode 100644 docs/contracts/project-model-portfolio.md delete mode 100644 docs/runbooks/external-project-extraction.md delete mode 100644 docs/runbooks/project-composition.md delete mode 100644 native_process_bootstrap.py delete mode 100644 project_artifacts.py delete mode 100644 project_composition.py delete mode 100644 project_custody.py delete mode 100644 project_data.py delete mode 100644 project_data_fork.py delete mode 100644 project_dispatch.py delete mode 100644 project_execution.py delete mode 100644 project_extraction.py delete mode 100644 project_files.py delete mode 100644 project_fork.py delete mode 100644 project_fork_composition.py delete mode 100644 project_history.py delete mode 100644 project_locks.py delete mode 100644 project_material.py delete mode 100644 project_material_fork.py delete mode 100644 project_measurements.py delete mode 100644 project_native_execution.py delete mode 100644 project_native_preparation.py delete mode 100644 project_native_process.py delete mode 100644 project_producer_execution.py delete mode 100644 project_producers.py delete mode 100644 project_projection.py delete mode 100644 project_record_dedupe.py delete mode 100644 project_runtime.py delete mode 100644 project_session.py delete mode 100644 project_sources.py delete mode 100644 project_store.py delete mode 100644 project_study_execution.py delete mode 100644 project_text.py delete mode 100644 project_transfer.py delete mode 100644 project_transfer_controller.py delete mode 100644 project_validation_cache.py delete mode 100644 project_validation_delta.py delete mode 100644 project_working_store.py delete mode 100644 project_workspace.py delete mode 100644 retained_measurements.py delete mode 100644 scripts/generate_project_files_contracts.py delete mode 100644 static/project-files.css delete mode 100644 static/project-files.html delete mode 100644 static/project-files.js delete mode 100644 static/project-measurements.css delete mode 100644 static/project-measurements.js delete mode 100644 static/project-model-portfolio.js delete mode 100644 static/project-progression.js delete mode 100644 static/project-transfer.css delete mode 100644 static/project-transfer.html delete mode 100644 static/project-transfer.js delete mode 100644 static/retained-measurement-maxima.vl.json delete mode 100644 tests/browser_model_portfolio.cjs delete mode 100644 tests/browser_project_file_deletion.cjs delete mode 100644 tests/browser_project_files.cjs delete mode 100644 tests/browser_project_files_m2.cjs delete mode 100644 tests/browser_project_files_m3.cjs delete mode 100644 tests/browser_project_files_m4.cjs delete mode 100644 tests/browser_project_files_native.cjs delete mode 100644 tests/model_portfolio_fixture.cjs delete mode 100644 tests/test_measurement_comparison.py delete mode 100644 tests/test_project_artifacts.py delete mode 100644 tests/test_project_candidate_clients.py delete mode 100644 tests/test_project_composition.py delete mode 100644 tests/test_project_composition_publication.py delete mode 100644 tests/test_project_composition_workspace.py delete mode 100644 tests/test_project_control_paths.py delete mode 100644 tests/test_project_custody.py delete mode 100644 tests/test_project_data.py delete mode 100644 tests/test_project_data_fork.py delete mode 100644 tests/test_project_dispatch.py delete mode 100644 tests/test_project_execution.py delete mode 100644 tests/test_project_execution_http.py delete mode 100644 tests/test_project_extraction.py delete mode 100644 tests/test_project_file_deletion_clients.py delete mode 100644 tests/test_project_file_deletion_clients_http.py delete mode 100644 tests/test_project_files.py delete mode 100644 tests/test_project_files_clients.py delete mode 100644 tests/test_project_files_fork_contracts.py delete mode 100644 tests/test_project_files_http.py delete mode 100644 tests/test_project_files_m2_http.py delete mode 100644 tests/test_project_files_m4_clients.py delete mode 100644 tests/test_project_files_m4_clients_http.py delete mode 100644 tests/test_project_files_m4_http.py delete mode 100644 tests/test_project_files_material_http.py delete mode 100644 tests/test_project_files_owner_mcp.py delete mode 100644 tests/test_project_fork.py delete mode 100644 tests/test_project_fork_composition.py delete mode 100644 tests/test_project_history.py delete mode 100644 tests/test_project_material.py delete mode 100644 tests/test_project_material_fork.py delete mode 100644 tests/test_project_measurement_comparison_http.py delete mode 100644 tests/test_project_measurement_reads.py delete mode 100644 tests/test_project_measurements.py delete mode 100644 tests/test_project_measurements_clients.py delete mode 100644 tests/test_project_model_portfolio.cjs delete mode 100644 tests/test_project_model_portfolio_http.py delete mode 100644 tests/test_project_native_clients.py delete mode 100644 tests/test_project_native_clients_http.py delete mode 100644 tests/test_project_native_execution.py delete mode 100644 tests/test_project_native_extraction.py delete mode 100644 tests/test_project_native_preparation.py delete mode 100644 tests/test_project_native_process.py delete mode 100644 tests/test_project_native_run.py delete mode 100644 tests/test_project_native_study.py delete mode 100644 tests/test_project_note_deletion.py delete mode 100644 tests/test_project_producer_execution.py delete mode 100644 tests/test_project_producers.py delete mode 100644 tests/test_project_projection.py delete mode 100644 tests/test_project_publication_recovery.py delete mode 100644 tests/test_project_receipt_validation.py delete mode 100644 tests/test_project_record_dedupe.py delete mode 100644 tests/test_project_runtime.py delete mode 100644 tests/test_project_runtime_clients.py delete mode 100644 tests/test_project_runtime_http.py delete mode 100644 tests/test_project_runtime_recovery_http.py delete mode 100644 tests/test_project_session.py delete mode 100644 tests/test_project_session_freshness.py delete mode 100644 tests/test_project_sources.py delete mode 100644 tests/test_project_store.py delete mode 100644 tests/test_project_study_execution.py delete mode 100644 tests/test_project_text.py delete mode 100644 tests/test_project_text_tag.py delete mode 100644 tests/test_project_transfer.py delete mode 100644 tests/test_project_transfer_clients.py delete mode 100644 tests/test_project_transfer_clients_http.py delete mode 100644 tests/test_project_transfer_controller.py delete mode 100644 tests/test_project_validation_cache.py delete mode 100644 tests/test_project_validation_delta.py delete mode 100644 tests/test_project_working_store.py delete mode 100644 tests/test_project_workspace.py delete mode 100644 tests/test_project_workspace_custody.py delete mode 100644 tests/test_retained_measurements.py delete mode 100644 tests/test_workspace_project_candidate.cjs delete mode 100644 tests/test_workspace_project_file_deletion.cjs delete mode 100644 tests/test_workspace_project_files.cjs delete mode 100644 tests/test_workspace_project_files_m4.cjs delete mode 100644 tests/test_workspace_project_fork_text.cjs delete mode 100644 tests/test_workspace_project_native.cjs delete mode 100644 tests/test_workspace_project_native_validation.cjs delete mode 100644 tests/test_workspace_project_runtime.cjs delete mode 100644 tests/test_workspace_project_transfer.cjs diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index a9bfc24f..e8d3d028 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -111,27 +111,6 @@ jobs: - run: build/workspace-training/bin/python -m unittest discover -s tests -p test_volume_assets.py - run: build/workspace-training/bin/python -m unittest discover -s tests -p test_rheon_cpu_training.py - run: build/workspace-training/bin/python -m unittest discover -s tests -p test_rheon_evaluation.py - - name: Verify actual native project Run fork Study custody and cold accounting - env: - PYTHONPATH: tests - TULDOK_NATIVE_PROJECT_GO: '1' - TULDOK_NATIVE_RETENTION_DIR: ${{ github.workspace }}/build/qa/external-project/native-retained - run: | - build/workspace-training/bin/python - <<'PY' - import os, sys, unittest - import numpy, sklearn, psycopg, torch - assert os.environ['TULDOK_TRAINING_PYTHON'] == sys.executable - names = [ - 'test_project_native_run.NativeRunSaveAsTests.test_one_actual_native_run_save_as_cold_role_and_metadata_only_git_clone', - 'test_project_native_study.NativeStudyCustodyTests.test_actual_native_study_spent_budget_and_cold_history_require_fresh_admission', - 'test_project_native_study.NativeStudyCustodyTests.test_native_study_admission_canonical_ack_then_sql_failure_never_starts_training', - ] - loader = unittest.TestLoader() - suite = loader.loadTestsFromNames(names) - assert not loader.errors and suite.countTestCases() == len(names) - result = unittest.TextTestRunner(verbosity=2).run(suite) - sys.exit(0 if result.wasSuccessful() and result.testsRun == len(names) and not result.skipped else 1) - PY - name: Create isolated optional agent verification environment run: python -m venv build/workspace-agent - run: build/workspace-agent/bin/python -m pip install -r requirements.txt @@ -145,111 +124,7 @@ jobs: - run: node --check static/experiment-lineage.js - run: node tests/test_experiment_lineage_controller.cjs - run: build/workspace-agent/bin/python -m unittest discover -s tests -p test_artifact_segments.py - - name: Verify real external-project SDK CLI MCP and current authority - env: - PYTHONPATH: tests - run: | - build/workspace-agent/bin/python - <<'PY' - import mcp, sys, unittest - loader = unittest.TestLoader() - suite = loader.loadTestsFromName('test_project_files_m2_http.ProjectFilesM2HTTP.test_real_sdk_cli_mcp_roles_lost_reply_and_stale_binding') - assert not loader.errors and suite.countTestCases() == 1 - result = unittest.TextTestRunner(verbosity=2).run(suite) - sys.exit(0 if result.wasSuccessful() and result.testsRun == 1 and not result.skipped else 1) - PY - - name: Verify independent fork and extraction across actual owner transports - env: - PYTHONPATH: tests - run: | - build/workspace-agent/bin/python - <<'PY' - import mcp, sys, unittest - names = [ - 'test_project_files_m4_clients_http.ProjectFilesM4ClientsHTTP.test_exact_file_revisions_save_as_and_current_role_through_sdk_cli_mcp', - 'test_project_transfer_clients_http.ProjectTransferClientsHTTP.test_owner_handoff_and_single_extraction_through_sdk_cli_and_real_mcp', - ] - loader = unittest.TestLoader() - suite = loader.loadTestsFromNames(names) - assert not loader.errors and suite.countTestCases() == len(names) - result = unittest.TextTestRunner(verbosity=2).run(suite) - sys.exit(0 if result.wasSuccessful() and result.testsRun == len(names) and not result.skipped else 1) - PY - - name: Verify finite owner MCP modes and denial boundaries - env: - PYTHONPATH: tests - run: | - build/workspace-agent/bin/python - <<'PY' - import mcp, sys, unittest - loader = unittest.TestLoader() - suite = loader.loadTestsFromName('test_project_files_owner_mcp') - selected = suite.countTestCases() - assert not loader.errors and selected > 0 - result = unittest.TextTestRunner(verbosity=2).run(suite) - sys.exit(0 if result.wasSuccessful() and result.testsRun == selected and not result.skipped else 1) - PY - - name: Verify real native project SDK CLI MCP and zero-GO recovery - env: - PYTHONPATH: tests - TULDOK_NATIVE_PROJECT_GO: '1' - run: | - build/workspace-agent/bin/python - <<'PY' - import mcp, sys, unittest - loader = unittest.TestLoader() - suite = loader.loadTestsFromName('test_project_native_clients_http.NativePublicClientsHTTP.test_real_native_preflight_replay_zero_go_failure_and_original_phase_recovery') - assert not loader.errors and suite.countTestCases() == 1 - result = unittest.TextTestRunner(verbosity=2).run(suite) - sys.exit(0 if result.wasSuccessful() and result.testsRun == 1 and not result.skipped else 1) - PY - - name: Verify explicit note deletion history and cold fork across owner transports - env: - PYTHONPATH: tests - TULDOK_NOTE_DELETION_GO: '1' - run: | - build/workspace-agent/bin/python - <<'PY' - import mcp, sys, unittest - loader = unittest.TestLoader() - suite = loader.loadTestsFromName('test_project_file_deletion_clients_http.NoteDeletionClientsHTTP.test_real_note_deletion_restore_history_and_cold_independent_fork') - assert not loader.errors and suite.countTestCases() == 1 - result = unittest.TextTestRunner(verbosity=2).run(suite) - sys.exit(0 if result.wasSuccessful() and result.testsRun == 1 and not result.skipped else 1) - PY - run: python -m unittest discover -s tests - - name: Verify external-project authoring and cold reconstruction in Chromium - run: node tests/browser_project_files_m2.cjs - env: - BROWSER: /usr/bin/google-chrome - - name: Verify named independent fork and inert cold clone in Chromium - run: node tests/browser_project_files_m4.cjs - env: - BROWSER: /usr/bin/google-chrome - - name: Verify explicit runtime failure recovery and inert cold Open in Chromium - run: node tests/browser_project_files_m3.cjs - env: - BROWSER: /usr/bin/google-chrome - - name: Verify source stop and independent extraction handoff in Chromium - run: node tests/test_workspace_project_transfer.cjs --browser - env: - BROWSER: /usr/bin/google-chrome - TULDOK_M5_UI_BROWSER_GO: '1' - - name: Verify named native preflight and original-phase recovery in Chromium - run: node tests/browser_project_files_native.cjs - env: - BROWSER: /usr/bin/google-chrome - TULDOK_NATIVE_PROJECT_GO: '1' - - name: Verify explicit note deletion restore and inert cold fork in Chromium - run: node tests/browser_project_file_deletion.cjs - env: - BROWSER: /usr/bin/google-chrome - TULDOK_NOTE_DELETION_GO: '1' - - name: Verify external-project working file and recovery controls - run: | - node tests/test_workspace_project_files_m4.cjs - node tests/test_workspace_project_fork_text.cjs - node tests/test_workspace_project_runtime.cjs - node tests/test_workspace_project_candidate.cjs - node tests/test_workspace_project_transfer.cjs - node tests/test_workspace_project_native.cjs - node tests/test_workspace_project_native_validation.cjs - node tests/test_workspace_project_file_deletion.cjs - run: node --check static/auth.js - run: node tests/test_auth_helpers.cjs - run: node tests/test_auth_controller.cjs diff --git a/agent_api.py b/agent_api.py index ff75c783..edd203c3 100644 --- a/agent_api.py +++ b/agent_api.py @@ -729,744 +729,6 @@ def model_operation(name,method,path,properties=None,required=None,*,output=None 'point':obj({'field_id':REF, **{axis:integer(0,127) for axis in 'xyz'}})}, output=JSON_OBJECT, description='Read exact retained validation field-point diagnostics and scalar compatibility; no scientific criterion or compute is invented.') -# External file projects have independent lifecycle and text-only contracts. -# Keep these additive operations outside the installed legacy registry projection. -_PROJECT_FILES_ACTIONS = ['new', 'open', 'save', 'close', 'query', 'get', 'import_text', 'annotate'] -_PROJECT_FILES_GROUPS = dict(GROUPS, uniqueItems=True) -_PROJECT_FILES_PARENTS = dict(array(text(120), 30), uniqueItems=True) -_PROJECT_FILES_PROVENANCE = obj({'method': const('import'), 'rights': text(1000), - 'normalization': const('NFC; LF newlines')}) -_PROJECT_FILES_RECORD_FIELDS = { - 'id': ID, 'kind': const('text'), 'name': text(200), 'text': text(200000), - 'groups': _PROJECT_FILES_GROUPS, 'parents': _PROJECT_FILES_PARENTS, - 'provenance': _PROJECT_FILES_PROVENANCE, 'review': {'enum': ['draft', 'human_reviewed']}, - 'revision': SAFE_POS, 'source_revision': const(1), - 'created_at': text(80), 'updated_at': text(80)} -_PROJECT_FILES_TASKS = ('text_classification', 'text_entities', 'text_corpus') -PROJECT_FILES_RECORD = {'oneOf': [obj(dict(_PROJECT_FILES_RECORD_FIELDS, - task=const(task), annotation={'oneOf': [{'type': 'null'}, ANNOTATIONS[task]]})) - for task in _PROJECT_FILES_TASKS]} -PROJECT_FILES_SUMMARY = obj({key: _PROJECT_FILES_RECORD_FIELDS[key] for key in - ('id', 'kind', 'name', 'review', 'revision', 'source_revision', 'created_at', 'updated_at')} | - {'task': {'enum': list(_PROJECT_FILES_TASKS)}}) -_PROJECT_FILES_PROJECT = obj({'project_id': ID, 'name': text(200), 'checkpoint': SHA}) -_PROJECT_FILES_RECOVERY = obj({'action': const('open'), 'root': text(160), 'directory': text(512), - 'reason': {'enum': ['unknown_publication', 'projection_unavailable']}, - 'request_key': {'oneOf': [KEY, {'type': 'null'}]}}) -PROJECT_FILES_RECEIPT = {'oneOf': [ - obj({'committed': const(True), 'selected': const(True), 'project_id': ID, - 'checkpoint': SHA, 'request_key': KEY}), - obj({'committed': const(True), 'selected': const(False), 'project_id': ID, - 'checkpoint': SHA, 'request_key': KEY, 'root': text(160), 'directory': text(512)})]} -_PROJECT_FILES_STATE_FIELDS = {'format': const('project_files_state_v1'), 'binding': ID, - 'roots': dict(array(text(160), 100), uniqueItems=True), - 'available_actions': dict(array({'enum': _PROJECT_FILES_ACTIONS}, 8), uniqueItems=True)} -PROJECT_FILES_STATE = {'oneOf': [ - obj(dict(_PROJECT_FILES_STATE_FIELDS, state=const('no_project_open'), project={'type': 'null'})), - obj(dict(_PROJECT_FILES_STATE_FIELDS, state=const('open'), - project=_PROJECT_FILES_PROJECT)), - obj(dict(_PROJECT_FILES_STATE_FIELDS, state=const('recovery_required'), - project=_PROJECT_FILES_PROJECT, recovery=_PROJECT_FILES_RECOVERY, - available_actions=const(['open'])))]} -_PROJECT_FILES_BOUND_RESULT = {'binding': ID, 'project_id': ID, 'checkpoint': SHA} -PROJECT_FILES_RECORD_RESULT = obj(dict(_PROJECT_FILES_BOUND_RESULT, record=PROJECT_FILES_RECORD, - history=array(PROJECT_FILES_RECORD, 4), - next_history_before_revision={'oneOf': [SAFE_POS, {'type': 'null'}]})) -_PROJECT_FILES_MUTATION = {'binding': ID, 'expected_checkpoint': SHA, 'request_key': KEY} -model_operation('project_files.status', 'GET', '/api/workspace/project-files', output=PROJECT_FILES_STATE) -for _action in ('new', 'open'): - _fields = dict(_PROJECT_FILES_MUTATION, expected_checkpoint={'oneOf': [SHA, {'type': 'null'}]}, - root=text(160), directory=text(512)) - if _action == 'new': - _fields['name'] = text(200) - model_operation('project_files.' + _action, 'POST', '/api/workspace/project-files/' + _action, - _fields, output=PROJECT_FILES_STATE, scopes=('inspect', 'edit'), mutation=True, - description='Explicit file project ' + _action + '; requires the current process binding and checkpoint. Never executes project code.') -for _action in ('save', 'close'): - model_operation('project_files.' + _action, 'POST', '/api/workspace/project-files/' + _action, - _PROJECT_FILES_MUTATION, output=PROJECT_FILES_STATE, scopes=('inspect', 'edit'), mutation=True) -model_operation('project_files.query', 'GET', '/api/workspace/project-files/records', - {'binding': ID, 'checkpoint': SHA, 'after_id': ID, 'limit': integer(1, 100)}, - required=['binding', 'checkpoint'], query=('binding', 'checkpoint', 'after_id', 'limit'), - output=obj(dict(_PROJECT_FILES_BOUND_RESULT, items=array(PROJECT_FILES_SUMMARY, 100), - next_after_id={'oneOf': [ID, {'type': 'null'}]}))) -model_operation('project_files.get', 'GET', '/api/workspace/project-files/records/{record_id}', - {'record_id': ID, 'binding': ID, 'checkpoint': SHA, 'before_revision': SAFE_POS, - 'history_limit': integer(1, 4)}, required=['record_id', 'binding', 'checkpoint'], - query=('binding', 'checkpoint', 'before_revision', 'history_limit'), output=PROJECT_FILES_RECORD_RESULT) -model_operation('project_files.import_text', 'POST', '/api/workspace/project-files/import-text', - dict(_PROJECT_FILES_MUTATION, asset=obj({'text': text(200000), 'name': text(200), - 'groups': _PROJECT_FILES_GROUPS, 'parents': _PROJECT_FILES_PARENTS, 'rights': text(1000)}, - required=['text', 'groups'])), output=PROJECT_FILES_RECORD_RESULT, - scopes=('inspect', 'edit'), mutation=True) -model_operation('project_files.annotate', 'POST', '/api/workspace/project-files/records/{record_id}', - dict(_PROJECT_FILES_MUTATION, record_id=ID, annotation={'oneOf': [obj({ - 'revision': SAFE_POS, 'source_revision': const(1), 'task': const(task), - 'annotation': ANNOTATIONS[task], 'groups': _PROJECT_FILES_GROUPS, - 'review': {'enum': ['draft', 'human_reviewed']}}) for task in _PROJECT_FILES_TASKS]}), - output=PROJECT_FILES_RECORD_RESULT, scopes=('inspect', 'edit'), mutation=True, - description='Save ordinary human text annotation or review at the exact checkpoint. Human review additionally requires the existing owner approve-review authority.') -_PROJECT_FILES_RECEIPT_IDS = frozenset('project_files.' + action - for action in ('new', 'open', 'save', 'close', 'import_text', 'annotate')) -_MODEL_RECEIPT_IDS.update(_PROJECT_FILES_RECEIPT_IDS) -_OWNER_OPERATION_IDS.update('project_files.' + action for action in ('new', 'open', 'save', 'close')) -for _op in _OPERATIONS: - if _op['operation_id'].startswith('project_files.'): - _op['outputSchema']['oneOf'][1]['properties']['result']['properties']['receipt'] = PROJECT_FILES_RECEIPT - -# M2 operations are fixed domain projections. Domain owners validate versioned -# documents; the public boundary owns selection, bounds and outcome correlation. -PROJECT_FILES_M2 = set() -PROJECT_FILES_M3 = set() -PROJECT_FILES_M4 = set() -_PROJECT_FILES_PAGE_INPUT = {'offset': integer(0, 1000000), 'limit': integer(1, 40)} -_PROJECT_FILES_PAGE = obj({'items': array(JSON_OBJECT, 40), 'offset': integer(0, 1000000), - 'total': integer(0, 1000000), 'limit': integer(1, 40)}) -_PROJECT_FILES_READ = {'binding': ID, 'checkpoint': SHA} -_PROJECT_FILES_ORIGIN = {'origin_catalog_id': ID} - - -def _project_file_operation(action, method, suffix, fields=None, *, required=None, - output=JSON_OBJECT, mutation=False, owner=False, scopes=None, - domain=None, page=False, milestone=2, receipt=True): - fields = copy.deepcopy(fields or {}) - needed = list(fields) if required is None else list(required) - if domain is not None: - original = next(op for op in _OPERATIONS if op['operation_id'] == domain) - fields.update(copy.deepcopy(original['inputSchema'].get('properties', {}))) - needed += original['inputSchema'].get('required', []) - bound = (_PROJECT_FILES_MUTATION if receipt else {"binding": ID, "expected_checkpoint": SHA}) if mutation else _PROJECT_FILES_READ - fields.update(bound) - needed = list(dict.fromkeys(needed + list(bound))) - if action == 'data_query': - fields['limit'] = integer(1, 40) - if page: - fields.update(copy.deepcopy(_PROJECT_FILES_PAGE_INPUT)) - output = copy.deepcopy(_PROJECT_FILES_PAGE) - if action in ('data_history', 'data_response_history', 'data_preference_history'): - fields['limit'] = integer(1, 4) - output['properties']['items']['maxItems'] = 4 - output['properties']['limit'] = integer(1, 4) - name = 'project_files.' + action - model_operation(name, method, '/api/workspace/project-files' + suffix, - fields, needed, output=obj(dict(_PROJECT_FILES_BOUND_RESULT, value=output)), - query=tuple(key for key in fields if '{' + key + '}' not in suffix) if method == 'GET' else (), - scopes=scopes or (('inspect', 'edit') if mutation else ('inspect',)), mutation=mutation, - description=action.replace('_', ' ') + '; exact selected project checkpoint, existing domain authorization and validation.' + (' Historical content never grants current execution permission.' if milestone == 3 else ' No execution.')) - if domain is not None: - _OPERATIONS[-1]['binary_fields'] = copy.deepcopy(original['binary_fields']) - {2:PROJECT_FILES_M2,3:PROJECT_FILES_M3,4:PROJECT_FILES_M4}[milestone].add(name) - if mutation and receipt: - _MODEL_RECEIPT_IDS.add(name) - if owner: - _OWNER_OPERATION_IDS.add(name) - _OPERATIONS[-1]['outputSchema']['oneOf'][1]['properties']['result']['properties']['receipt'] = PROJECT_FILES_RECEIPT - - -_project_file_operation('definitions', 'GET', '/definitions') - -# Actual data and its authored histories. Inline source imports retain the -# existing decoded-byte bound; compound sources use their existing parsers. -_project_file_operation('data_query', 'GET', '/data', domain='data.query') -_project_file_operation('data_scientific', 'GET', '/data/{record_id}/scientific', - {'content_hash': SHA}, domain='data.scientific') -_project_file_operation('data_get', 'GET', '/data/{record_id}', {'record_id': ID}) -_project_file_operation('data_availability', 'GET', '/data/{record_id}/availability', {'record_id': ID}) -for _action, _suffix in [('data_history', 'history'), ('data_responses', 'responses'), - ('data_response_history', 'response-history'), ('data_preferences', 'preferences'), - ('data_preference_history', 'preference-history')]: - _project_file_operation(_action, 'GET', '/data/{record_id}/' + _suffix, {'record_id': ID}, page=True) -for _kind in ('text', 'image', 'audio', 'mesh', 'pointcloud', 'volume', 'sequence'): - _project_file_operation('data_import_' + _kind, 'POST', '/data/import-' + _kind, - domain='data.import_' + _kind, mutation=True) -_project_file_operation('source_register', 'POST', '/sources/register', - {'root': text(160), 'manifest_path': text(512)}, mutation=True, owner=True) -_project_file_operation('data_import_scientific', 'POST', '/data/import-scientific', { - 'snapshot': obj({'origin_catalog_id': ID, 'project_id': ID, 'manifest_sha256': SHA}), - 'reference_id': REF, 'expected_sha256': SHA, - 'document': obj(OPTIONAL_META, required=['groups'])}, mutation=True) -# Retained scalar packets use their own fixed native owner. Definitions and -# original JSON evidence stay producer-authored data, never executable specs. -_MEASUREMENT_ID = {'type':'string','pattern':'^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$'} -_MEASUREMENT_SCALAR = {'type':['string','number','boolean','null']} -_MEASUREMENT_DIMENSIONS = {'type':'object','maxProperties':32,'additionalProperties':_MEASUREMENT_SCALAR} -_MEASUREMENT_REF = obj({'source_id':_MEASUREMENT_ID,'pointer':{'oneOf':[text(512,True),_NULL]}}) -_MEASUREMENT_DEFINITION = obj(dict(_MEASUREMENT_REF['properties'],sha256=SHA)) -_MEASUREMENT_SCOPE = obj({'id':_MEASUREMENT_ID,'label':text(240), - 'population':{'enum':['training','consumed','independent','reserved','unknown']},'definition':_MEASUREMENT_DEFINITION}) -_MEASUREMENT_METRIC = obj({'id':_MEASUREMENT_ID,'label':text(240), - 'units':text(120),'definition':_MEASUREMENT_DEFINITION}) -_MEASUREMENT_SUBJECT = obj({'id':_MEASUREMENT_ID,'label':text(240), - 'dimensions':_MEASUREMENT_DIMENSIONS,'reference':_MEASUREMENT_REF}) -_MEASUREMENT_CASE = obj({'id':_MEASUREMENT_ID,'dimensions':_MEASUREMENT_DIMENSIONS,'reference':_MEASUREMENT_REF}) -_MEASUREMENT_STATE = {'enum':['measured','failed','unsupported','unavailable']} -_MEASUREMENT_OBSERVATION = obj({'id':_MEASUREMENT_ID,'subject_id':_MEASUREMENT_ID, - 'case_id':_MEASUREMENT_ID,'metric_id':_MEASUREMENT_ID,'state':_MEASUREMENT_STATE, - 'value':{'type':['number','null']},'reason':{'oneOf':[text(1000),_NULL]}, - 'dimensions':_MEASUREMENT_DIMENSIONS,'reference':_MEASUREMENT_REF}) -_MEASUREMENT_CAPTURE = obj({'origin_catalog_id':ID,'project_id':ID,'manifest_sha256':SHA, - 'reference_id':REF,'path':text(512),'measured_sha256':SHA}) -_MEASUREMENT_SOURCE = obj({'format':const('project_measurement_source_v1'),'origin_catalog_id':ID, - 'id':SHA,'title':text(240),'blob':obj({'sha256':SHA,'bytes':integer(1,32*1024*1024)}), - 'source':_MEASUREMENT_CAPTURE,'actor_id':ID,'imported_at':text(80)}) -_MEASUREMENT_AVAILABILITY = obj({'state':{'enum':['unverified','missing']}, - 'expected_sha256':SHA,'expected_bytes':SAFE_NAT,'observed_sha256':const(None), - 'observed_bytes':{'oneOf':[SAFE_NAT,_NULL]}}) -_MEASUREMENT_SOURCE_ITEM = obj(dict(_MEASUREMENT_SOURCE['properties'],availability=_MEASUREMENT_AVAILABILITY)) -_MEASUREMENT_HEADER = obj({'format':const('retained_measurements_v1'),'packet_sha256':SHA,'title':text(240), - 'scope':_MEASUREMENT_SCOPE,'scope_definition':{'type':'object'}, - 'dimensions':array(obj({'id':_MEASUREMENT_ID,'label':text(240),'type':{'enum':['string','number','integer','boolean']}, - 'units':{'oneOf':[text(120),_NULL]},'scope':{'enum':['subject','case','observation']}}),32), - 'metrics':array(_MEASUREMENT_METRIC,32),'subject_count':integer(1,100000),'case_count':integer(1,4096), - 'observation_count':integer(1,100000),'source_count':integer(1,256)}) -_MEASUREMENT_SUMMARY = obj({'subject_id':_MEASUREMENT_ID,'count':SAFE_NAT, - 'states':obj({state:SAFE_NAT for state in ('measured','failed','unsupported','unavailable')}), - 'maximum':{'oneOf':[obj({'id':_MEASUREMENT_ID,'case_id':_MEASUREMENT_ID,'value':{'type':'number'}}),_NULL]}}) -_MEASUREMENT_QUERY = obj({'format':const('retained_measurement_query_v1'),'packet_sha256':SHA, - 'scope':_MEASUREMENT_SCOPE,'metric':_MEASUREMENT_METRIC,'scope_definition':{'type':'object'},'definition':{'type':'object'}, - 'filters':_MEASUREMENT_DIMENSIONS,'subject_ids':array(_MEASUREMENT_ID,100000,1), - 'summary':array(_MEASUREMENT_SUMMARY,100000),'rows':array(_MEASUREMENT_OBSERVATION,100), - 'total':SAFE_NAT,'offset':SAFE_NAT,'limit':integer(1,100),'sampling':const('none')}) -_MEASUREMENT_EVIDENCE = obj({'reference':_MEASUREMENT_REF,'source_sha256':SHA, - 'state':{'enum':['included','opaque','exceeds_inspection_bound']},'value':{}}) -_MEASUREMENT_INSPECTION = obj({'packet_sha256':SHA,'observation':_MEASUREMENT_OBSERVATION, - 'case':_MEASUREMENT_CASE,'subject':_MEASUREMENT_SUBJECT,'metric':_MEASUREMENT_METRIC, - 'scope':_MEASUREMENT_SCOPE,'scope_definition':{'type':'object'},'case_evidence':_MEASUREMENT_EVIDENCE, - 'scalar_evidence':_MEASUREMENT_EVIDENCE,'source':obj({'id':_MEASUREMENT_ID,'label':text(240), - 'kind':{'enum':['json','opaque']},'bytes':integer(1,8*1024*1024),'sha256':SHA})}) -_MEASUREMENT_SELECTION = {'origin_catalog_id':ID,'packet_sha256':SHA} -_MEASUREMENT_BOUND = lambda value:obj({'source':_MEASUREMENT_SOURCE,'value':value}) -_project_file_operation('measurement_import','POST','/measurements/import', - {'snapshot':obj({'origin_catalog_id':ID,'project_id':ID,'manifest_sha256':SHA}), - 'reference_id':REF,'expected_sha256':SHA},mutation=True,output=_MEASUREMENT_SOURCE) -_project_file_operation('measurement_sources','GET','/measurements',_PROJECT_FILES_PAGE_INPUT,required=[], - output=obj({'items':array(_MEASUREMENT_SOURCE_ITEM,40),'offset':SAFE_NAT,'limit':integer(1,40),'total':SAFE_NAT})) -_project_file_operation('measurement_metadata','GET','/measurements/{packet_sha256}',_MEASUREMENT_SELECTION, - output=_MEASUREMENT_BOUND(_MEASUREMENT_HEADER)) -_project_file_operation('measurement_subjects','GET','/measurements/{packet_sha256}/subjects', - dict(_MEASUREMENT_SELECTION,**_PROJECT_FILES_PAGE_INPUT),required=list(_MEASUREMENT_SELECTION), - output=_MEASUREMENT_BOUND(obj({'items':array(_MEASUREMENT_SUBJECT,40),'offset':SAFE_NAT,'limit':integer(1,40),'total':SAFE_NAT}))) -_project_file_operation('measurement_query','POST','/measurements/{packet_sha256}/query', - dict(_MEASUREMENT_SELECTION,metric_id=_MEASUREMENT_ID,subject_ids=array(_MEASUREMENT_ID,100000,1), - filters=_MEASUREMENT_DIMENSIONS,offset=SAFE_NAT,limit=integer(1,100)), - required=[*list(_MEASUREMENT_SELECTION),'metric_id'],output=_MEASUREMENT_BOUND(_MEASUREMENT_QUERY)) -_project_file_operation('measurement_inspect','GET','/measurements/{packet_sha256}/observations/{observation_id}', - dict(_MEASUREMENT_SELECTION,observation_id=_MEASUREMENT_ID),output=_MEASUREMENT_BOUND(_MEASUREMENT_INSPECTION)) - -_COMPARISON_QUERY = obj(dict( - {key:_MEASUREMENT_QUERY['properties'][key] for key in ('metric','definition','filters','subject_ids','total','offset','limit','sampling')}, - subject_ids=array(_MEASUREMENT_ID,256,1), - summary=array(obj(dict(_MEASUREMENT_SUMMARY['properties'],source=obj(_MEASUREMENT_SELECTION))),256), - rows=array(obj(dict(_MEASUREMENT_OBSERVATION['properties'],source=obj(_MEASUREMENT_SELECTION))),100))) -_COMPARISON_VALUE = obj({'format':const('retained_measurement_comparison_v1'), - 'scope':_MEASUREMENT_SCOPE,'scope_definition':{'type':'object'}, - 'dimensions':_MEASUREMENT_HEADER['properties']['dimensions'],'metrics':array(_MEASUREMENT_METRIC,32,1), - 'definition_source':obj(_MEASUREMENT_SELECTION),'case_population_sha256':SHA, - 'case_count':integer(1,4096),'observation_count':integer(1,100000), - 'subjects':array(obj(dict(_MEASUREMENT_SUBJECT['properties'],source=obj(_MEASUREMENT_SELECTION))),256,1), - 'query':{'oneOf':[_COMPARISON_QUERY,_NULL]}}) -_project_file_operation('measurement_compare','POST','/measurements/compare', - dict(sources=array(obj(_MEASUREMENT_SELECTION),16,1),metric_id=_MEASUREMENT_ID, - subject_ids=array(_MEASUREMENT_ID,256,1),filters=_MEASUREMENT_DIMENSIONS,offset=SAFE_NAT,limit=integer(1,100)), - required=['sources'],output=obj({'sources':array(_MEASUREMENT_SOURCE,16,1),'value':_COMPARISON_VALUE})) -_project_file_operation('data_annotate', 'POST', '/data/{record_id}', { - 'record_id': ID, 'revision': SAFE_POS, 'source_revision': SAFE_POS, - 'task': {'enum': list(ANNOTATIONS)}, 'annotation': JSON_OBJECT, - 'groups': _PROJECT_FILES_GROUPS, 'review': {'enum': ['draft', 'human_reviewed']}}, mutation=True) -_project_file_operation('data_rights', 'POST', '/data/{record_id}/rights', { - 'record_id': ID, 'revision': SAFE_POS, 'source_revision': SAFE_POS, - 'note': text(1000, True)}, mutation=True) -for _action, _suffix in [('data_source_save', '/source'), ('data_source_delete', '/source/delete')]: - _project_file_operation(_action, 'POST', '/data/{record_id}' + _suffix, - {'record_id': ID, 'document': JSON_OBJECT}, mutation=True, - scopes=('inspect', 'edit', 'approve-review') if _action == 'data_source_save' else ('inspect', 'edit')) -_project_file_operation('data_response_save', 'POST', '/responses', { - 'document': obj({'id': ID, 'prompt_id': ID, 'revision': SAFE_NAT, - 'parent_revision': SAFE_POS, 'source_revision': SAFE_POS, 'completion': text(200000), - 'review': {'enum': ['draft', 'human_reviewed']}})}, mutation=True) -for _action, _suffix in [('data_preference_save', ''), ('data_preference_delete', '/delete')]: - _project_file_operation(_action, 'POST', '/preferences' + _suffix, - {'document': JSON_OBJECT}, mutation=True) -for _singular, _plural, _key in [('selection', 'selections', 'selection_id'), ('search', 'searches', 'search_id')]: - _project_file_operation(_plural, 'GET', '/' + _plural, page=True) - if _singular == 'selection': - _project_file_operation('selection_get', 'GET', '/selections/{selection_id}', {'selection_id': ID}) - _project_file_operation(_singular + '_create', 'POST', '/' + _plural, - {'document': JSON_OBJECT}, mutation=True) - for _verb in ('rename', 'delete'): - _project_file_operation(_singular + '_' + _verb, 'POST', '/' + _plural + '/{' + _key + '}' + ('/delete' if _verb == 'delete' else ''), - {_key: ID, 'revision': SAFE_POS, **({'name': text(120)} if _verb == 'rename' else {})}, mutation=True) -for _action in ('preview', 'freeze'): - _project_file_operation('release_' + _action, 'POST', '/releases/' + _action, - domain='releases.' + _action, mutation=_action == 'freeze', - scopes=('inspect', 'freeze') if _action == 'freeze' else ('inspect',)) - -# Current metadata uses the same Model/Pipeline validators, with canonical -# publication wrapped by the project session. Runtime capture remains absent. -for _plural, _key, _domain in [('models', 'model_id', 'models'), ('graphs', 'graph_id', 'graphs')]: - _project_file_operation(_plural, 'GET', '/' + _plural, page=True) - for _verb in ('get', 'create', 'save'): - _project_file_operation(('model_' if _plural == 'models' else 'graph_') + _verb, - 'GET' if _verb == 'get' else 'POST', '/' + _plural + ('/{' + _key + '}' if _verb != 'create' else ''), - domain=_domain + '.' + _verb, mutation=_verb != 'get') -_project_file_operation('graph_create_external', 'POST', '/graphs/external', - domain='graphs.create_external', mutation=True) -_project_file_operation('graph_clone', 'POST', '/graphs/{graph_id}/clone', domain='graphs.clone', mutation=True) -_project_file_operation('model_publish', 'POST', '/models/{model_id}/publish', domain='models.publish', mutation=True) -_project_file_operation('recipes', 'GET', '/recipes', page=True) -for _verb in ('get', 'create', 'save'): - _project_file_operation('recipe_' + _verb, 'GET' if _verb == 'get' else 'POST', - '/recipes' + ('/{recipe_id}' if _verb != 'create' else ''), domain='recipes.' + _verb, - mutation=_verb != 'get') -_project_file_operation('recipe_prepare', 'POST', '/recipes/{graph_id}/prepare', { - 'graph_id': ID, 'revision': SAFE_POS, 'model': MODEL_REF, - 'builtin': {'type': 'boolean'}, 'reconcile_capture': {'type': 'boolean'}}, - required=['graph_id', 'revision', 'model'], mutation=True) -for _kind, _ref in [('model', MODEL_REF), ('recipe', MATERIAL_REF), ('runtime', material_ref('runtime'))]: - _project_file_operation(_kind + '_material', 'POST', '/materials/' + _kind, - {'ref': _ref, 'verify': {'type': 'boolean'}}, required=['ref']) -_project_file_operation('snapshot', 'POST', '/materials/snapshot', { - 'project_id': ID, 'manifest_sha256': SHA, 'origin_catalog_id': ID, 'verify': {'type': 'boolean'}}, - required=['project_id', 'manifest_sha256', 'origin_catalog_id']) - -# Imported origin identity is an explicit selector, never a current grant. -for _action, _suffix, _key in [('study', 'studies', 'study_id'), ('trial', 'trials', 'trial_id'), - ('run', 'runs', 'run_id'), ('candidate', 'candidates', 'candidate_id')]: - _project_file_operation(_action, 'GET', '/' + _suffix + '/{' + _key + '}', - {_key: ID, **_PROJECT_FILES_ORIGIN, **({'verify': {'type': 'boolean'}} if _action == 'candidate' else {})}, - required=[_key, 'origin_catalog_id']) -# Study reservations are independently bounded while charge totals remain complete. -_study_operation = next(op for op in _OPERATIONS if op['operation_id'] == 'project_files.study') -_study_operation['inputSchema']['properties'].update(_PROJECT_FILES_PAGE_INPUT | {'revision': SAFE_POS}) -_study_operation['query'].extend(['offset', 'limit', 'revision']) -_run_operation = next(op for op in _OPERATIONS if op['operation_id'] == 'project_files.run') -_run_operation['inputSchema']['properties'].update(_PROJECT_FILES_PAGE_INPUT) -_run_operation['query'].extend(['offset', 'limit']) -_PROJECT_RUN_DOCUMENT_SEGMENT = obj({'format': const('project_run_document_segment_v1'), - 'origin_catalog_id': ID, 'run_id': ID, 'sha256': SHA, 'bytes': SAFE_NAT, - 'offset': SAFE_NAT, 'limit': integer(1, 262144), - 'base64': {'type': 'string', 'maxLength': 349528, 'pattern': '^[A-Za-z0-9+/]*={0,2}$'}, - 'next_offset': {'oneOf': [SAFE_NAT, {'type': 'null'}]}}) -_project_file_operation('run_document_segment', 'GET', '/runs/{run_id}/document-segment', - {'run_id': ID, 'origin_catalog_id': ID, 'expected_sha256': SHA, - 'offset': SAFE_NAT, 'limit': integer(1, 262144)}, - required=['run_id', 'origin_catalog_id', 'expected_sha256', 'offset', 'limit'], - output=_PROJECT_RUN_DOCUMENT_SEGMENT) -_project_file_operation('source_references', 'GET', '/sources/{project_id}/references', - {'origin_catalog_id': ID, 'project_id': ID, 'manifest_sha256': SHA}, page=True) -_project_file_operation('publication_result', 'GET', '/runs/{run_id}/publication-result', - {'run_id': ID, **_PROJECT_FILES_ORIGIN}) -_project_file_operation('package_state', 'GET', '/candidates/{candidate_id}/package-state', - {'candidate_id': ID, **_PROJECT_FILES_ORIGIN}) -_project_file_operation('dependencies', 'GET', '/runs/{run_id}/dependencies', - {'run_id': ID, **_PROJECT_FILES_ORIGIN, **_PROJECT_FILES_PAGE_INPUT}, - required=['run_id', 'origin_catalog_id']) -for _action in ('studies', 'runs', 'lineage', 'policies', 'artifacts', 'materials'): - _project_file_operation(_action, 'GET', '/' + _action, _PROJECT_FILES_ORIGIN, - required=[] if _action in ('studies', 'runs', 'artifacts', 'materials') else ['origin_catalog_id'], page=True) -# Intrinsic artifact identities span all origins in the selected project. -_artifacts_operation = next(op for op in _OPERATIONS if op['operation_id'] == 'project_files.artifacts') -_artifacts_operation['inputSchema']['properties'].pop('origin_catalog_id') -_artifacts_operation['query'].remove('origin_catalog_id') -_project_file_operation('policy', 'POST', '/policies/get', {'ref': POLICY_REF}) -for _verb in ('create', 'save'): - _project_file_operation('study_' + _verb, 'POST', '/studies' + ('/{study_id}' if _verb == 'save' else ''), - domain='studies.' + _verb, mutation=True, owner=True) -_project_file_operation('trial_prepare', 'POST', '/studies/{study_id}/trials', { - 'study_id': ID, 'revision': SAFE_POS, 'material': MATERIAL_REF, 'replicate': SAFE_NAT}, mutation=True) -_project_file_operation('lineage_record', 'POST', '/lineage', {'trial': _LINEAGE_REF, 'intent': _LINEAGE_INTENT}, mutation=True) -_PROJECT_PROGRESSION_ORIGIN = obj({'origin_catalog_id':ID,'study_count':SAFE_NAT,'trial_count':SAFE_NAT}) -_PROJECT_PROGRESSION_RUN = obj({key:value for key,value in _LINEAGE_RUN['properties'].items() if key!='validation'}) -_PROJECT_PROGRESSION_NODE = obj({'trial':_TRIAL,'lineage':{'oneOf':[_LINEAGE_RECORD,_NULL]}, - 'study':obj({'id':ID,'name':text(120)}),'attempt_count':SAFE_NAT, - 'runs':array(_PROJECT_PROGRESSION_RUN,5),'runs_truncated':{'type':'boolean'}}) -_project_file_operation('progression_origins','GET','/progression/origins',_PROJECT_FILES_PAGE_INPUT,required=[], - output=obj({'items':array(_PROJECT_PROGRESSION_ORIGIN,40),'offset':SAFE_NAT,'limit':integer(1,40),'total':SAFE_NAT})) -_project_file_operation('progression','GET','/progression', - {'origin_catalog_id':ID,'offset':SAFE_NAT,'limit':integer(1,20),'cohort':text(120)},required=['origin_catalog_id'], - output=obj({'origin_catalog_id':ID,'evidence':const('saved_metadata_only'),'historical':const(True), - 'execution_available':const(False),'nodes':array(_PROJECT_PROGRESSION_NODE,20),'related':array(_LINEAGE_REF,40), - 'offset':SAFE_NAT,'limit':integer(1,20),'total':SAFE_NAT,'cohort':{'oneOf':[text(120),_NULL]}})) -_project_file_operation('candidate_select', 'POST', '/studies/{study_id}/candidates', - domain='studies.select_candidate', mutation=True) -_project_file_operation('evidence', 'POST', '/runs/{run_id}/evidence', { - 'run_id': ID, **_PROJECT_FILES_ORIGIN, 'selectors': JSON_OBJECT}, - required=['run_id', 'origin_catalog_id'], output=_EVIDENCE_RESULT) -for _action, _suffix in [('retained_analysis', ''), ('retained_analysis_export', '/export')]: - _project_file_operation(_action, 'POST', '/runs/{run_id}/analysis' + _suffix, - {**_retained_request['properties'], **_PROJECT_FILES_ORIGIN}, - required=[*_retained_request['required'], 'origin_catalog_id'], output=_retained_result) -_project_file_operation('artifact_status', 'POST', '/artifacts/status', {'sha256': SHA}) -_project_file_operation('artifact_resolve', 'POST', '/artifacts/resolve', - {'sha256': SHA, 'root': text(160), 'path': text(512)}, mutation=True, owner=True, - output=obj({'format': const('project_artifact_resolution_v1'), 'sha256': SHA, 'bytes': SAFE_NAT, - 'actor_id': ID, 'observed_at': text(80)})) -_project_file_operation('expose_holdout', 'POST', '/runs/{run_id}/disclose', - {'run_id': ID, **_PROJECT_FILES_ORIGIN, 'reason': text(500)}, mutation=True, - scopes=('inspect', 'expose-holdout')) -_PROJECT_FILES_PRODUCER_FAMILY = {'enum': ['generation_history', 'grounded_history', 'caption_proposal_history', 'text_proposal_history']} -_project_file_operation('producers', 'GET', '/producers', - {'family': _PROJECT_FILES_PRODUCER_FAMILY, **_PROJECT_FILES_ORIGIN}, required=['family'], page=True) -_project_file_operation('producer', 'GET', '/producers/{origin_catalog_id}/{producer_id}', - {'family': _PROJECT_FILES_PRODUCER_FAMILY, 'origin_catalog_id': ID, 'producer_id': ID, - 'entries_offset': integer(0, 1000000), 'entries_limit': integer(1, 40)}, - required=['family', 'origin_catalog_id', 'producer_id']) -PROJECT_FILES_M2 = frozenset(PROJECT_FILES_M2) -_PROJECT_FILES_RECEIPT_IDS = _PROJECT_FILES_RECEIPT_IDS | frozenset( - name for name in PROJECT_FILES_M2 if next(op for op in _OPERATIONS if op['operation_id'] == name)['side_effects']) - -# Explicit current-local execution is separate from imported history. -_PROJECT_CURRENT_GRANT = obj({'id': ID, 'catalog_id': ID, 'approver_actor_id': ID, - 'approver_credential_id': {'oneOf': [ID, {'type': 'null'}]}, 'consumer_actor_id': ID, - 'material_sha256': SHA, 'created_at': SAFE_NAT, 'expires_at': SAFE_NAT, - 'revoked_at': {'oneOf': [SAFE_NAT, {'type': 'null'}]}}) -PROJECT_CURRENT_APPROVAL = obj({'format': const('project_current_execution_approval_v1'), - 'current_local': const(True), 'grant': _PROJECT_CURRENT_GRANT}) -PROJECT_RUN_ADMISSION = obj({'format': const('project_run_admission_v1'), - 'origin_catalog_id': ID, 'run_id': ID, 'request_sha256': SHA}) -_PROJECT_EXECUTION_HEALTH = obj({'format': const('project_execution_health_v1'), - 'active_run_ids': array(ID, 40), 'active_count': SAFE_NAT, 'offset': SAFE_NAT, - 'limit': integer(1, 40), 'local_owner_active': {'type': 'boolean'}, 'available': {'type': 'boolean'}, - 'drain_required': {'type': 'boolean'}}) -_project_file_operation('execution_health', 'GET', '/execution', _PROJECT_FILES_PAGE_INPUT, - required=[], output=_PROJECT_EXECUTION_HEALTH, milestone=3) -_project_file_operation('execution_preflight_external', 'POST', '/execution/preflight', - {'graph_id': ID, 'revision': SAFE_POS}, milestone=3) -_project_file_operation('execution_approve_external', 'POST', '/execution/approvals', - {'graph_id': ID, 'graph_revision': SAFE_POS, 'expected_digest': SHA, - 'consumer_actor_id': ID, 'ttl_seconds': integer(60, 3600)}, - required=['graph_id', 'graph_revision', 'expected_digest', 'consumer_actor_id'], - output=PROJECT_CURRENT_APPROVAL, mutation=True, owner=True, - scopes=('inspect', 'approve-execution'), milestone=3) -_project_file_operation('execution_submit_external', 'POST', '/execution/runs', - {'graph_id': ID, 'graph_revision': SAFE_POS, 'expected_digest': SHA, 'approval_id': ID}, - required=['graph_id', 'graph_revision', 'expected_digest'], output=PROJECT_RUN_ADMISSION, - mutation=True, scopes=('inspect', 'execute'), milestone=3) -_OPERATIONS[-1]['inputSchema']['properties']['request_key'] = copy.deepcopy(next(op for op in _OPERATIONS if op['operation_id'] == 'runs.submit_external')['inputSchema']['properties']['request_key']) -_project_file_operation('execution_cancel', 'POST', '/execution/runs/{run_id}/cancel', - {'run_id': ID}, output=PROJECT_RUN_ADMISSION, mutation=True, - scopes=('inspect', 'cancel'), milestone=3) -_project_file_operation('execution_study_continue', 'POST', '/execution/studies/{study_id}/continue', - {'study_id': ID, 'revision': SAFE_POS, 'admission_epoch': SAFE_NAT}, output=_STUDY, - mutation=True, owner=True, scopes=('inspect', 'execute'), milestone=3) -_project_file_operation('execution_study_approve', 'POST', '/execution/studies/{study_id}/approvals', - {'study_id': ID, 'trial_id': ID, 'expected_material_sha256': SHA, 'consumer_actor_id': ID, - 'ttl_seconds': integer(60, 3600)}, - required=['study_id', 'trial_id', 'expected_material_sha256', 'consumer_actor_id'], - output=PROJECT_CURRENT_APPROVAL, mutation=True, owner=True, - scopes=('inspect', 'approve-execution'), milestone=3) -_project_file_operation('execution_study_admit', 'POST', '/execution/studies/{study_id}/runs', - {'study_id': ID, 'revision': SAFE_POS, 'admission_epoch': SAFE_NAT, 'trial_id': ID, - 'approval_id': ID, 'parent_run_id': ID}, - required=['study_id', 'revision', 'admission_epoch', 'trial_id'], - output=obj({'format': const('project_study_admission_v1'), 'origin_catalog_id': ID, - 'study_id': ID, 'trial_id': ID, 'run_id': ID, 'reservation': _RESERVATION}), - mutation=True, scopes=('inspect', 'execute'), milestone=3) -_project_file_operation('execution_study_stop', 'POST', '/execution/studies/{study_id}/stop', - {'study_id': ID, 'revision': SAFE_POS}, - output=obj({'format': const('project_study_stop_v1'), 'origin_catalog_id': ID, - 'study_id': ID, 'receipt': obj({'study_id': ID, 'stop_receipt_id': ID, - 'admission_epoch': SAFE_NAT, 'run_ids': array(ID, 100000)}), - 'study_revision': SAFE_POS, 'state': {'enum': ['draft', 'open', 'stopping', 'stopped', 'unknown']}, - 'open': {'type': 'boolean'}}), mutation=True, scopes=('inspect', 'cancel'), milestone=3) -_project_file_operation('execution_reconcile_current', 'POST', '/execution/reconcile-current', - output=obj({'format': const('project_execution_reconciliation_v1'), 'origin_catalog_id': ID, - 'run_ids': array(ID, 100000), 'available': {'type': 'boolean'}}), - mutation=True, receipt=False, owner=True, scopes=('inspect', 'cancel'), milestone=3) - -# Finite native producer grammars. Each closed document remains validated by -# its domain owner; no operation name or callable can be supplied by a client. -_PROJECT_PRODUCER_MODE = {'protocol': const('pumas_typed_v1'), - 'profile': {'oneOf': [{'type': 'null'}, {'type': 'string', 'maxLength': 128, 'pattern': '^[A-Za-z0-9_.-]*$'}]}} -_PROJECT_PRODUCER_SOURCE = {'source_id': ID, 'revision': SAFE_POS, 'source_revision': SAFE_POS, - 'server_url': text(2048), 'model': text(256), 'instruction': text(2000), - 'seed': {'oneOf': [integer(0, 4294967295), {'type': 'null'}]}} -_PROJECT_PRODUCER_LABELS = array(text(80), 30, 1) -_PROJECT_PRODUCER_START_DOCUMENTS = { - 'generation_history': obj({'server_url': text(2048), 'model': text(256), 'prompt': text(4000), - 'count': integer(1, 10000), 'strategy': {'enum': ['varied', 'repeat']}, 'session_id': text(120), - 'width': SAFE_POS, 'height': SAFE_POS, 'seed': integer(0, 4294967295), - 'prompt_url': text(2048), 'prompt_model': text(256), 'book_id': text(120, True), - 'split': {'enum': ['unassigned', 'train', 'validation', 'test']}, **_PROJECT_PRODUCER_MODE}, - required=['server_url', 'model', 'prompt', 'count', 'strategy', 'session_id']), - 'grounded_history': obj(dict(_PROJECT_PRODUCER_SOURCE, count=integer(1, 10), **_PROJECT_PRODUCER_MODE), - required=[*_PROJECT_PRODUCER_SOURCE, 'count']), - 'caption_proposal_history': obj(dict(_PROJECT_PRODUCER_SOURCE, request_id=ID, **_PROJECT_PRODUCER_MODE), - required=[*_PROJECT_PRODUCER_SOURCE, 'request_id']), - 'text_proposal_history': obj(dict(_PROJECT_PRODUCER_SOURCE, request_id=ID, - labels=_PROJECT_PRODUCER_LABELS, **_PROJECT_PRODUCER_MODE), - required=[*_PROJECT_PRODUCER_SOURCE, 'request_id', 'labels'])} -for _document in _PROJECT_PRODUCER_START_DOCUMENTS.values(): - _document['dependentRequired'] = {'protocol': ['profile'], 'profile': ['protocol']} -_PROJECT_PRODUCER_ACTION = obj({'format': const('project_producer_action_v1'), - 'family': _PROJECT_FILES_PRODUCER_FAMILY, 'origin_catalog_id': ID, 'producer_id': ID, - 'action': {'enum': ['start', 'resume', 'review', 'decide', 'cancel']}}) -_project_file_operation('execution_producer_start', 'POST', '/execution/producers', - {'family': _PROJECT_FILES_PRODUCER_FAMILY, 'document': JSON_OBJECT}, - output=_PROJECT_PRODUCER_ACTION, mutation=True, owner=True, scopes=('inspect', 'execute'), milestone=3) -_OPERATIONS[-1]['inputSchema']['allOf'] = [ - {'if': {'properties': {'family': const(family)}}, - 'then': {'properties': {'document': document}}} - for family, document in _PROJECT_PRODUCER_START_DOCUMENTS.items()] -_project_file_operation('execution_generation_resume', 'POST', '/execution/generation/{producer_id}/resume', - {'producer_id': ID}, output=_PROJECT_PRODUCER_ACTION, mutation=True, owner=True, - scopes=('inspect', 'execute'), milestone=3) -_project_file_operation('execution_grounded_review', 'POST', '/execution/grounded/{producer_id}/review', - {'producer_id': ID, 'document': obj({'revision': SAFE_POS, 'candidate_id': ID, - 'decision': {'enum': ['reject', 'admit_draft']}, 'note': text(1000)})}, - output=_PROJECT_PRODUCER_ACTION, mutation=True, scopes=('inspect', 'edit'), milestone=3) -_project_file_operation('execution_producer_decide', 'POST', '/execution/producers/{producer_id}/decide', - {'family': {'enum': ['caption_proposal_history', 'text_proposal_history']}, 'producer_id': ID, - 'document': obj({'revision': SAFE_POS, 'decision': {'enum': ['reject', 'apply_draft']}, - 'labels': _PROJECT_PRODUCER_LABELS}, required=['revision', 'decision'])}, - output=_PROJECT_PRODUCER_ACTION, mutation=True, scopes=('inspect', 'edit'), milestone=3) -_project_file_operation('execution_producer_cancel', 'POST', '/execution/producers/{producer_id}/cancel', - {'family': _PROJECT_FILES_PRODUCER_FAMILY, 'producer_id': ID}, output=_PROJECT_PRODUCER_ACTION, - mutation=True, scopes=('inspect', 'cancel'), milestone=3) -_project_file_operation('execution_producer_health', 'GET', '/execution/producers/health', - _PROJECT_FILES_PAGE_INPUT, required=[], - output=obj({'format': const('project_producer_health_v1'), - 'items': array(obj({'family': _PROJECT_FILES_PRODUCER_FAMILY, 'producer_id': ID, - 'status': text(120), 'provider_outcome': {'oneOf': [{'type': 'null'}, text(120)]}, - 'worker_alive': {'type': 'boolean'}}), 40), - 'total': SAFE_NAT, 'offset': SAFE_NAT, 'limit': integer(1, 40), 'fenced': {'type': 'boolean'}}), milestone=3) -# Fixed current-host CPU capture projections. Bounds mirror runtime_snapshots -# and recipe_process; native inventories stay canonical, never transport grants. -_PROJECT_RUNTIME_SOURCE = {'type':'string','pattern':'^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$'} -_PROJECT_RUNTIME_FILE = obj({'path':text(1024),'bytes':integer(0,512*1024*1024), - 'sha256':SHA,'mode':{'enum':[0o400,0o500]},'kind':{'enum':['data','elf']}}) -_PROJECT_RUNTIME_LAUNCH = obj({**{field:text(1024) for field in ('python','loader','home','stdlib','dynload','packages')}, - 'library_dirs':dict(array(text(1024),32,1),uniqueItems=True)}) -_PROJECT_RUNTIME_REF = obj({'kind':const('runtime'),'catalog_id':ID,'id':SHA,'sha256':SHA}) -_PROJECT_RUNTIME_SUMMARY = {'project_id':ID,'manifest_sha256':SHA,'file_count':integer(1,40000), - 'total_bytes':integer(0,2*1024*1024*1024),'actor_id':ID,'observed_at':text(80),'request_key':KEY} -_PROJECT_RUNTIME_INTENT = obj(dict(_PROJECT_RUNTIME_SUMMARY,format=const('project_runtime_capture_intent_v1'))) -_PROJECT_RUNTIME_CAPTURE = obj(dict(_PROJECT_RUNTIME_SUMMARY,format=const('project_runtime_capture_v1'),runtime_ref=_PROJECT_RUNTIME_REF)) -_project_file_operation('runtime_sources','GET','/runtime/sources',_PROJECT_FILES_PAGE_INPUT,required=[], - output=obj(dict(_PROJECT_FILES_PAGE['properties'],items=array(obj({'source':_PROJECT_RUNTIME_SOURCE}),40))), - owner=True,scopes=('inspect','admin'),milestone=3) -_project_file_operation('runtime_inspect','GET','/runtime/inspect',{'source':_PROJECT_RUNTIME_SOURCE,**_PROJECT_FILES_PAGE_INPUT},required=['source'], - output=obj({'format':const('project_runtime_inspection_v1'),'source':_PROJECT_RUNTIME_SOURCE,'inventory_sha256':SHA, - 'profile':const('captured_cpu_python_v1'),'python_version':const('3.12'),'file_count':integer(1,40000), - 'total_bytes':integer(1,2*1024*1024*1024),'manifest_bytes':integer(1,16*1024*1024),'free_bytes':SAFE_NAT, - 'packages':array(obj({'name':text(128),'version':text(128)}),256,2),'launch':_PROJECT_RUNTIME_LAUNCH, - 'files':obj(dict(_PROJECT_FILES_PAGE['properties'],items=array(_PROJECT_RUNTIME_FILE,40)))}), - owner=True,scopes=('inspect','admin'),milestone=3) -_project_file_operation('runtime_capture','POST','/runtime/capture',{'source':_PROJECT_RUNTIME_SOURCE, - 'expected_inventory_sha256':SHA,'reserve_bytes':SAFE_NAT},required=['source','expected_inventory_sha256'], - output=_PROJECT_RUNTIME_CAPTURE,mutation=True,owner=True,scopes=('inspect','admin'),milestone=3) -_project_file_operation('runtime_status','GET','/runtime/status',{'capture_key':KEY}, - output=obj({'state':{'enum':['absent','intent_recorded','captured']}, - 'intent':{'oneOf':[{'type':'null'},_PROJECT_RUNTIME_INTENT]}, - 'result':{'oneOf':[{'type':'null'},_PROJECT_RUNTIME_CAPTURE]}}),milestone=3) -# Current Candidate package preparation is distinct from approval/admission. -_PROJECT_PREPARATION_KEY={'type':'string','pattern':'^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$'} -_PROJECT_PREPARATION_NAME={'type':'string','pattern':'^[A-Za-z0-9][A-Za-z0-9_.-]{0,119}$'} -for _kind,_suffix in (('package','packages'),('verifier','verifiers')): - _result=dict(_PACKAGE_PREPARED_FIELDS) - if _kind=='verifier':_result.update(package_run_id=ID,package_sha256=SHA) - _project_file_operation('execution_study_prepare_'+_kind,'POST','/execution/studies/{study_id}/'+_suffix, - domain='studies.prepare_'+_kind,output=obj(_result),mutation=True,owner=True,scopes=('inspect','edit'),milestone=3) - _OPERATIONS[-1]['inputSchema']['properties']['directory']=_PROJECT_PREPARATION_NAME -_PROJECT_PREPARATION_ABANDON=obj({'format':const('project_candidate_preparation_abandon_v1'), - 'origin_catalog_id':ID,'study_id':ID,'preparation_key':_PROJECT_PREPARATION_KEY, - 'preparation_operation':{'enum':['study_execution.prepare_package','study_execution.prepare_verifier']}, - 'input_sha256':SHA,'candidate':material_ref('candidate'),'actor_id':ID,'reason':text(1000), - 'observed_checkpoint':SHA,'occurred_at':text(80),'state':const('abandoned')}) -_project_file_operation('execution_study_abandon_preparation','POST','/execution/studies/{study_id}/preparations/abandon', - {'study_id':ID,'preparation_key':_PROJECT_PREPARATION_KEY,'reason':text(1000)}, - output=_PROJECT_PREPARATION_ABANDON,mutation=True,owner=True,scopes=('inspect','cancel'),milestone=3) -_PROJECT_PREPARATION_COMPLETED={'oneOf':[obj(_PACKAGE_PREPARED_FIELDS),obj(dict(_PACKAGE_PREPARED_FIELDS,package_run_id=ID,package_sha256=SHA))]} -_project_file_operation('execution_study_reconcile_preparation','POST','/execution/studies/{study_id}/preparations/reconcile', - {'study_id':ID,'preparation_key':_PROJECT_PREPARATION_KEY},output=_PROJECT_PREPARATION_COMPLETED, - mutation=True,owner=True,scopes=('inspect','cancel'),milestone=3,receipt=False) -# Explicitly abandon only a current local stopped copy, retaining its science. -_PROJECT_RUNTIME_ABANDON=obj({'format':const('project_runtime_capture_abandon_v1'),'project_id':ID, - 'capture_key':KEY,'input_sha256':SHA,'manifest_sha256':SHA,'actor_id':ID,'reason':text(1000), - 'observed_checkpoint':SHA,'observed_at':text(80)}) -_project_file_operation('runtime_abandon','POST','/runtime/abandon',{'capture_key':KEY,'reason':text(1000)}, - output=_PROJECT_RUNTIME_ABANDON,mutation=True,owner=True,scopes=('inspect','admin'),milestone=3) -_runtime_status=next(op for op in _OPERATIONS if op['operation_id']=='project_files.runtime_status') -_runtime_status_value=_runtime_status['outputSchema']['oneOf'][0]['properties']['result']['properties']['value'] -_runtime_status['outputSchema']['oneOf'][0]['properties']['result']['properties']['value']={'oneOf':[ - copy.deepcopy(_runtime_status_value),obj({'state':const('abandoned'),'intent':_PROJECT_RUNTIME_INTENT, - 'result':const(None),'abandonment':_PROJECT_RUNTIME_ABANDON})]} -# Explicit current native probes and Runs. Current operator runtime is selected -# by the native owner; no imported descriptor or serialized probe is authority. -_PROJECT_NATIVE_PHASE = obj({'format':const('project_native_phase_v1'),'origin_catalog_id':ID, - 'phase_id':ID,'phase':{'enum':['probe','train','verify']},'run_id':{'oneOf':[const(None),ID]}, - 'state':{'enum':['prepared','ready','go_intent','completed','failed','unknown']}, - 'spec_sha256':SHA,'receipt_sha256':{'oneOf':[const(None),SHA]}}) -_project_file_operation('native_preflight','POST','/execution/native/preflight', - {'graph_id':ID,'revision':SAFE_POS},mutation=True,owner=True,scopes=('inspect','execute'),milestone=3) -_project_file_operation('native_submit','POST','/execution/native/runs', - {'graph_id':ID,'graph_revision':SAFE_POS,'validation_token':SHA},output=PROJECT_RUN_ADMISSION, - mutation=True,owner=True,scopes=('inspect','execute'),milestone=3) -_project_file_operation('native_retry','POST','/execution/native/runs/{run_id}/retry', - {'run_id':ID},output=PROJECT_RUN_ADMISSION,mutation=True,owner=True,scopes=('inspect','execute'),milestone=3) -_project_file_operation('native_reconcile','POST','/execution/native/phases/{phase_id}/reconcile', - {'phase_id':ID},output=_PROJECT_NATIVE_PHASE,mutation=True,owner=True, - scopes=('inspect','cancel'),milestone=3,receipt=False) -PROJECT_FILES_M3 = frozenset(PROJECT_FILES_M3) -_PROJECT_FILES_RECEIPT_IDS |= frozenset(name for name in PROJECT_FILES_M3 - if next(op for op in _OPERATIONS if op['operation_id'] == name)['side_effects'] and name not in ('project_files.execution_reconcile_current','project_files.execution_study_reconcile_preparation','project_files.native_reconcile')) - -# M4 adds independent Save As and explicit inert working-file adoption without -# changing the frozen lifecycle state/actions or earlier per-operation pins. -_PROJECT_FILE_KIND={'enum':['script','note']} -_PROJECT_FILE_VERSION_META={'revision':SAFE_POS,'sha256':SHA,'bytes':integer(0,1048576), - 'adopted_at':text(80),'actor_id':ID} -_PROJECT_FILE_DELETED_META={'revision':integer(2,9007199254740991),'deleted':const(True),'sha256':{'type':'null'}, - 'bytes':const(0),'adopted_at':text(80),'actor_id':ID} -_PROJECT_FILE_RESULT=obj({'id':SHA,'project_id':ID,'kind':_PROJECT_FILE_KIND,'path':text(512), - 'revision':SAFE_POS,'sha256':SHA,'bytes':integer(0,1048576),'adopted_at':text(80),'changed':{'type':'boolean'}}) -_PROJECT_FORK_RESULT=obj({'source_project_id':ID,'source_checkpoint':SHA,'project_id':ID,'checkpoint':SHA, - 'root':text(160),'directory':text(512),'request_key':KEY,'reconciled':{'type':'boolean'}, - 'mapping_count':SAFE_NAT,'copied_count':SAFE_NAT,'missing_regenerable_count':SAFE_NAT}) -model_operation('project_files.save_as','POST','/api/workspace/project-files/save-as', - dict(_PROJECT_FILES_MUTATION,root=text(160),directory=text(512),name=text(200)), - output=obj({'state':PROJECT_FILES_STATE,'fork':_PROJECT_FORK_RESULT}), - scopes=('inspect','edit'),mutation=True,description='Create an independent idle project fork at an explicit configured local destination; retain inert origins and exact copy completeness.') -_OPERATIONS[-1]['outputSchema']['oneOf'][1]['properties']['result']['properties']['receipt']=PROJECT_FILES_RECEIPT -PROJECT_FILES_M4.add('project_files.save_as');_OWNER_OPERATION_IDS.add('project_files.save_as');_MODEL_RECEIPT_IDS.add('project_files.save_as') -# Composition is a new owner-only operation; existing Save As pins/state stay frozen. -_PROJECT_COMPOSITION_SOURCE=obj({'root':text(160),'directory':text(512),'project_id':ID,'checkpoint':SHA}) -model_operation('project_files.compose','POST','/api/workspace/project-files/compose', - dict(_PROJECT_FILES_MUTATION,root=text(160),directory=text(512),name=text(200), - sources=array(_PROJECT_COMPOSITION_SOURCE,15,1)), - output=obj({'state':PROJECT_FILES_STATE,'fork':_PROJECT_FORK_RESULT, - 'sources':array(obj({'project_id':ID,'checkpoint':SHA}),16,2)}), - scopes=('inspect','edit'),mutation=True, - description='Compose explicit retained project checkpoints with the current editable primary into one independent inert project.') -_OPERATIONS[-1]['outputSchema']['oneOf'][1]['properties']['result']['properties']['receipt']=PROJECT_FILES_RECEIPT -PROJECT_FILES_M4.add('project_files.compose');_OWNER_OPERATION_IDS.add('project_files.compose');_MODEL_RECEIPT_IDS.add('project_files.compose') -_PROJECT_FILE_INSPECTION=obj({'id':SHA,'kind':_PROJECT_FILE_KIND,'path':text(512),'revision':SAFE_POS, - 'expected_sha256':{'oneOf':[SHA,{'type':'null'}]},'expected_bytes':integer(0,1048576), - 'observed_sha256':{'oneOf':[SHA,{'type':'null'}]},'observed_bytes':{'oneOf':[integer(0,1048576),{'type':'null'}]}, - 'state':{'enum':['unchanged','changed','missing','invalid','deleted']}, - 'reason':{'oneOf':[{'type':'null'},{'enum':['missing','unsafe_path','too_large','invalid_utf8','unreadable','unstable']}]}}) -_project_file_operation('files_inspect','GET','/files',_PROJECT_FILES_PAGE_INPUT,required=[], - output=obj(dict(_PROJECT_FILES_PAGE['properties'],items=array(_PROJECT_FILE_INSPECTION,40))),milestone=4) -_project_file_operation('file_get','GET','/files/{file_id}',{'file_id':SHA,'revision':SAFE_POS},required=['file_id'], - output=obj({'id':SHA,'project_id':ID,'kind':_PROJECT_FILE_KIND,'path':text(512), - 'version':{'oneOf':[obj(dict(_PROJECT_FILE_VERSION_META,text=text(1048576,empty=True))), - obj(dict(_PROJECT_FILE_DELETED_META,text={'type':'null'}))]}}),milestone=4) -_project_file_operation('file_history','GET','/files/{file_id}/history',{'file_id':SHA,**_PROJECT_FILES_PAGE_INPUT},required=['file_id'], - output=obj(dict(_PROJECT_FILES_PAGE['properties'],id=SHA,items=array({'oneOf':[obj(_PROJECT_FILE_VERSION_META),obj(_PROJECT_FILE_DELETED_META)]},40))),milestone=4) -_project_file_operation('file_adopt','POST','/files/adopt',{'kind':_PROJECT_FILE_KIND,'path':text(512), - 'expected_revision':SAFE_NAT,'expected_sha256':SHA},output=_PROJECT_FILE_RESULT,mutation=True,milestone=4) -_project_file_operation('files_adopt','POST','/files/adopt-many',{'items':array(obj({'kind':_PROJECT_FILE_KIND, - 'path':text(512),'expected_revision':SAFE_NAT,'expected_sha256':SHA}),40,1)}, - output=obj({'items':array(_PROJECT_FILE_RESULT,40,1),'changed_count':integer(0,40)}),mutation=True,milestone=4) -_project_file_operation('file_adopt_deletion','POST','/files/adopt-deletion',{'path':text(512), - 'expected_revision':SAFE_POS,'expected_sha256':SHA},output=obj(dict(_PROJECT_FILE_RESULT['properties'], - kind=const('note'),revision=integer(2,9007199254740991),deleted=const(True),sha256={'type':'null'},bytes=const(0),changed=const(True))), - mutation=True,milestone=4) -_PROJECT_INTENT_FAMILY={'enum':['model_definition','pipeline_graph','recipe_definition']} -_PROJECT_INTENT_FIELDS={'enum':['task','specification','source_selector','preprocessing_policy','output_policy', - 'recipe_source','inputs','runtime','release','nodes','data','evaluation_profile','model','trainer']} -_PROJECT_INTENT_RESELECT=dict(array(_PROJECT_INTENT_FIELDS,14),uniqueItems=True) -_PROJECT_FORK_ORIGIN=obj({'project_id':ID,'checkpoint':SHA,'family':_PROJECT_INTENT_FAMILY, - 'id':text(512),'revision':SAFE_POS,'created_at':text(80)}) -_PROJECT_INTENT_CURRENT=obj({'format':const('project_material_fork_intent_v1'),'catalog_id':ID,'id':ID, - 'revision':const(1),'name':text(200),'definition_family':_PROJECT_INTENT_FAMILY, - 'definition':JSON_OBJECT,'required_reselection':_PROJECT_INTENT_RESELECT}) -_project_file_operation('material_intents','GET','/material-intents',_PROJECT_FILES_PAGE_INPUT,required=[], - output=obj(dict(_PROJECT_FILES_PAGE['properties'],items=array(obj({'family':_PROJECT_INTENT_FAMILY, - 'id':text(65),'catalog_id':ID,'definition_id':ID,'name':text(200),'revision':const(1), - 'required_reselection':_PROJECT_INTENT_RESELECT,'fork_origin':_PROJECT_FORK_ORIGIN}),40))),milestone=4) -_project_file_operation('material_intent','GET','/material-intents/{family}/{definition_id}', - {'family':_PROJECT_INTENT_FAMILY,'definition_id':ID},output=obj({'family':_PROJECT_INTENT_FAMILY, - 'id':text(65),'current':_PROJECT_INTENT_CURRENT,'fork_origin':_PROJECT_FORK_ORIGIN}),milestone=4) -_project_file_operation('material_intent_capabilities','GET','/material-intents/capabilities',_PROJECT_FILES_PAGE_INPUT,required=[], - output=obj(dict(_PROJECT_FILES_PAGE['properties'],items=array(obj({'family':_PROJECT_INTENT_FAMILY, - 'id':text(65),'requires_reselection':_PROJECT_INTENT_RESELECT}),40))),milestone=4) -_PROJECT_FORK_MAPPING=obj({'family':text(80),'source_id':text(512),'source_revision':{'oneOf':[SAFE_POS,{'type':'null'}]},'destination_id':text(512)}) -_project_file_operation('fork_info','GET','/fork',_PROJECT_FILES_PAGE_INPUT,required=[],output=obj({ - 'source':{'oneOf':[{'type':'null'},obj({'project_id':ID,'checkpoint':SHA})]},'project_id':ID, - 'mapping':obj(dict(_PROJECT_FILES_PAGE['properties'],items=array(_PROJECT_FORK_MAPPING,40))), - 'archived_count':SAFE_NAT,'copied_count':SAFE_NAT,'missing_regenerable_count':SAFE_NAT}),milestone=4) -PROJECT_FILES_M4=frozenset(PROJECT_FILES_M4) -_PROJECT_FILES_RECEIPT_IDS |= frozenset(name for name in PROJECT_FILES_M4 if next(op for op in _OPERATIONS if op['operation_id']==name)['side_effects']) - -# M5 is a separate current-owner controller, never a project-open authority. -PROJECT_TRANSFER_OPERATIONS=frozenset('project_transfer.'+action for action in ('status','preview','report_page','stop','extract')) -_PROJECT_TRANSFER_KEY={'type':'string','pattern':'^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$'} -_PROJECT_TRANSFER_ALIAS={'type':'string','pattern':'^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$'} -_PROJECT_TRANSFER_DIRECTORY={'type':'string','minLength':1,'maxLength':200,'pattern':r'^[^/\\\x00-\x1f]+$','not':{'enum':['.','..']}} -_PROJECT_TRANSFER_ROOTS={ - 'records':ID,'responses':ID,'preferences':ID,'selections':ID,'searches':ID,'graphs':ID, - 'recipe_drafts':ID,'model_definitions':ID,'studies':ID,'runs':ID,'releases':SHA,'exposures':ID, - 'model_materials':SHA,'recipe_materials':SHA,'runtime_materials':SHA} -_PROJECT_TRANSFER_FAMILIES=['workbench_record','workbench_response','workbench_preference','saved_selection','saved_search', - 'pipeline_graph','recipe_definition','model_definition','study_history','run_history','dataset_release','dataset_exposure', - 'model_material','recipe_material','runtime_material','trial_history','candidate_history','project_snapshot', - 'generation_history','grounded_history','caption_proposal_history','text_proposal_history','project_artifact','project_file'] -_PROJECT_TRANSFER_SECTION={'enum':['included','required','unassigned','excluded','blockers','warnings','artifacts','working_files']} -_PROJECT_TRANSFER_LOCATOR={'family':{'enum':_PROJECT_TRANSFER_FAMILIES},'id':text(128)} -_PROJECT_TRANSFER_SELECTION=obj({'project_snapshot':obj({'id':ID,'manifest_sha256':SHA}), - 'roots':obj({**{name:dict(array(schema,10000),uniqueItems=True) for name,schema in _PROJECT_TRANSFER_ROOTS.items()}, - 'producer_jobs':dict(array(obj({'kind':{'enum':['generation','grounded','caption','text_proposal']},'id':ID}),10000),uniqueItems=True), - 'working_files':dict(array(obj({'kind':{'enum':['script','note']},'path':text(512)}),1000),uniqueItems=True)},required=[]), - 'decisions':array(obj(dict(_PROJECT_TRANSFER_LOCATOR,include={'type':'boolean'},reason=text(1000))),10000)}) -_PROJECT_TRANSFER_SOURCE=obj({'catalog_id':ID,'schema_version':const(10),'catalog_signature':SHA, - 'snapshot_sha256':SHA,'backup_receipt_sha256':{'oneOf':[SHA,{'type':'null'}]},'external_inventory_sha256':SHA}) -_PROJECT_TRANSFER_COUNTS=obj({name:SAFE_NAT for name in _PROJECT_TRANSFER_SECTION['enum']}) -_PROJECT_TRANSFER_REPORT=obj({'report_sha256':SHA,'selection_sha256':SHA,'source':_PROJECT_TRANSFER_SOURCE, - 'can_extract':{'type':'boolean'},'counts':_PROJECT_TRANSFER_COUNTS}) -_PROJECT_TRANSFER_RECEIPT=obj({'format':const('project_transfer_receipt_v1'),'committed':const(True), - 'project_id':ID,'checkpoint':SHA,'request_key':_PROJECT_TRANSFER_KEY,'input_sha256':SHA,'report_sha256':SHA, - 'source':_PROJECT_TRANSFER_SOURCE,'artifacts':obj({'copied_count':SAFE_NAT,'missing_regenerable_count':SAFE_NAT}), - 'verification':obj({'checkpoint':SHA,'active_data_records':SAFE_NAT}),'replayed':{'type':'boolean'}}) -_PROJECT_TRANSFER_PARTIAL=obj({'committed':const(True),'selected':const(False),'project_id':ID,'checkpoint':SHA, - 'request_key':_PROJECT_TRANSFER_KEY,'directory':_PROJECT_TRANSFER_DIRECTORY}) -_PROJECT_TRANSFER_FAILURE=obj({'action':{'enum':['stop','extract']},'code':text(120),'detail':text(1000,empty=True), - 'staging_directory':text(200)},required=['action','code','detail']) -PROJECT_TRANSFER_STATE=obj({'format':const('project_transfer_state_v1'),'binding':ID, - 'phase':{'enum':['source_live','source_stopped','source_fenced']},'source_catalog_id':ID,'control_catalog_id':ID, - 'roots':dict(array(_PROJECT_TRANSFER_ALIAS,100),uniqueItems=True), - 'available_actions':dict(array({'enum':['status','preview','report_page','stop','extract']},5,1),uniqueItems=True), - 'report':{'oneOf':[{'type':'null'},_PROJECT_TRANSFER_REPORT]}, - 'backup':{'oneOf':[{'type':'null'},obj({'root':_PROJECT_TRANSFER_ALIAS,'directory':_PROJECT_TRANSFER_DIRECTORY,'receipt_sha256':SHA})]}, - 'destination':{'oneOf':[{'type':'null'},obj({'root':_PROJECT_TRANSFER_ALIAS,'directory':_PROJECT_TRANSFER_DIRECTORY})]}, - 'failure':{'oneOf':[{'type':'null'},_PROJECT_TRANSFER_FAILURE]}, - 'last_receipt':{'oneOf':[{'type':'null'},_PROJECT_TRANSFER_RECEIPT,_PROJECT_TRANSFER_PARTIAL]}}) -_PROJECT_TRANSFER_ITEMS={ - 'included':obj(dict(_PROJECT_TRANSFER_LOCATOR,revision={'oneOf':[SAFE_POS,{'type':'null'}]})), - 'unassigned':obj(dict(_PROJECT_TRANSFER_LOCATOR,revision={'oneOf':[SAFE_POS,{'type':'null'}]})), - 'required':obj(_PROJECT_TRANSFER_LOCATOR),'excluded':obj(_PROJECT_TRANSFER_LOCATOR), - 'blockers':obj({'family':{'enum':_PROJECT_TRANSFER_FAMILIES+['source','closure']},'id':text(128),'code':text(120),'detail':text(1000,empty=True)}), - 'warnings':obj({'family':{'enum':_PROJECT_TRANSFER_FAMILIES+['source','closure']},'id':text(128),'code':text(120),'detail':text(1000,empty=True)}), - 'artifacts':obj({'sha256':SHA,'bytes':integer(0,2**63-1),'preservation':{'enum':['unique','regenerable']},'state':{'enum':['verified','missing','corrupt']}}), - 'working_files':obj({'kind':{'enum':['script','note']},'path':text(512),'sha256':SHA,'bytes':integer(0,1048576)})} -_PROJECT_TRANSFER_PAGE=obj({'format':const('project_transfer_report_page_v1'),'binding':ID,'report_sha256':SHA, - 'section':_PROJECT_TRANSFER_SECTION,'items':array({'oneOf':list(_PROJECT_TRANSFER_ITEMS.values())},40), - 'offset':integer(0,1000000),'limit':integer(1,40),'total':SAFE_NAT}) -# Some sections share item schemas; section-specific validation below selects one. -_PROJECT_TRANSFER_PAGE['properties']['items']['items']={} -_PROJECT_TRANSFER_PAGE['allOf']=[{'if':{'properties':{'section':const(section)}},'then':{'properties':{'items':array(schema,40)}}} - for section,schema in _PROJECT_TRANSFER_ITEMS.items()] -_PROJECT_TRANSFER_RESULT=obj({'format':const('project_transfer_extraction_result_v1'),'binding':ID, - 'receipt':_PROJECT_TRANSFER_RECEIPT,'selection':obj({'selected':{'type':'boolean'}, - 'state':{'oneOf':[{'type':'null'},PROJECT_FILES_STATE]}, - 'error':{'oneOf':[{'type':'null'},obj({'code':text(120),'detail':text(1000,empty=True)})]}})}) -for _action,_method,_suffix,_fields,_needed,_output,_mutation in ( - ('status','GET','',{},[],PROJECT_TRANSFER_STATE,False), - ('preview','POST','/preview',{'binding':ID,'selection':_PROJECT_TRANSFER_SELECTION},None,PROJECT_TRANSFER_STATE,True), - ('report_page','GET','/report',{'binding':ID,'report_sha256':SHA,'section':_PROJECT_TRANSFER_SECTION, - 'offset':integer(0,1000000),'limit':integer(1,40)},['binding','report_sha256','section'],_PROJECT_TRANSFER_PAGE,False), - ('stop','POST','/stop',{'binding':ID,'report_sha256':SHA,'backup_root':_PROJECT_TRANSFER_ALIAS, - 'backup_directory':_PROJECT_TRANSFER_DIRECTORY,'destination_root':_PROJECT_TRANSFER_ALIAS,'directory':_PROJECT_TRANSFER_DIRECTORY},None,PROJECT_TRANSFER_STATE,True), - ('extract','POST','/extract',{'binding':ID,'report_sha256':SHA,'destination_root':_PROJECT_TRANSFER_ALIAS, - 'directory':_PROJECT_TRANSFER_DIRECTORY,'name':text(200),'request_key':_PROJECT_TRANSFER_KEY},None,_PROJECT_TRANSFER_RESULT,True)): - _name='project_transfer.'+_action - model_operation(_name,_method,'/api/workspace/project-transfer'+_suffix,_fields,_needed, - output=_output,scopes=('inspect','admin'),mutation=_mutation,query=tuple(_fields) if _method=='GET' else (), - description='Explicit current-owner legacy extraction '+_action.replace('_',' ')+'. Source and control authority remain separate; no execution or credential transfer.') - _OPERATIONS[-1]['outputSchema']['oneOf'][1]['properties']['result']['properties']['receipt']=_PROJECT_TRANSFER_PARTIAL - _OWNER_OPERATION_IDS.add(_name) -_MODEL_RECEIPT_IDS.add('project_transfer.extract') - _OWNER_SNAPSHOT_HTTP_IDS=frozenset(('project_snapshots.list','project_snapshots.get','project_snapshots.open')) # A served definition-first project folder (spec-m7.md, section 7): one contract # per row of tuldok_project.operations, offered only by the project_folder profile. @@ -1489,36 +751,6 @@ def _project_file_operation(action, method, suffix, fields=None, *, required=Non _LOOKUP = {key: operation for operation in _OPERATIONS for key in (operation['operation_id'], operation['mcp_name'])} # Explicit locally implemented versions. No remotely supplied code or routes. _CONTRACTS = {op['operation_id']: {1: copy.deepcopy(op)} for op in _OPERATIONS} -# Keep the installed v1 bounds/hash exact. Version 2 admits complete larger -# comparisons; each individual packet and every response page retain their caps. -_comparison_capacity=copy.deepcopy(_CONTRACTS['project_files.measurement_compare'][1]) -_comparison_value=_comparison_capacity['outputSchema']['oneOf'][0]['properties']['result']['properties']['value']['properties']['value']['properties'] -_comparison_value['observation_count']=integer(1,250000) -_comparison_value['query']['oneOf'][0]['properties']['total']=integer(0,250000) -_CONTRACTS['project_files.measurement_compare'][2]=_comparison_capacity -# v1 remains the closed Run-only current custody view. v2 additionally exposes -# bounded original local native phases; imported history never populates it. -_native_health=copy.deepcopy(_CONTRACTS['project_files.execution_health'][1]) -_native_health_value=_native_health['outputSchema']['oneOf'][0]['properties']['result']['properties']['value'] -_native_health_value['properties']['native_phases']=obj({'items':array(_PROJECT_NATIVE_PHASE,40), - 'total':SAFE_NAT,'offset':SAFE_NAT,'limit':integer(1,40)}) -_native_health_value['required'].append('native_phases') -_CONTRACTS['project_files.execution_health'][2]=_native_health - -# Fork-origin text requires an additive result contract; import-only v1 remains -# exact. Both record and each historical revision retain the actual origin. -_PROJECT_FILES_FORK_PROVENANCE=obj({'method':const('project_fork'),'rights':text(1000), - 'origin':obj({'project_id':ID,'checkpoint':SHA,'family':{'enum':['workbench_text','workbench_record']}, - 'id':ID,'revision':SAFE_POS,'source_revision':SAFE_POS})}) -for _name in ('project_files.get','project_files.annotate'): - _fork_text=copy.deepcopy(_CONTRACTS[_name][1]) - _fork_text['description']+=' Version 2 retains exact independent-fork provenance.' - _result=_fork_text['outputSchema']['oneOf'][0]['properties']['result']['properties'] - for _record_schema in (_result['record'],_result['history']['items']): - for _variant in _record_schema['oneOf']: - _variant['properties']['provenance']={'oneOf':[copy.deepcopy(_PROJECT_FILES_PROVENANCE),copy.deepcopy(_PROJECT_FILES_FORK_PROVENANCE)]} - _CONTRACTS[_name][2]=_fork_text - # Activity changes the closed output schema, so installed snapshot v1 contracts # retain their exact identity and wire projection. for _name in ('project_snapshots.get','project_snapshots.open'): @@ -1746,19 +978,6 @@ def _project_file_operation(action, method, suffix, fields=None, *, required=Non obj({'actor_id': ID, 'request_key': KEY, 'request_sha256': SHA})]} _publication_status_output['required'].append('continuation_request') _CONTRACTS['runs.publication_status'][2] = _publication_status_request -# Project mode is an additive consumer of the current fixed graph grammars. -# Copy only inputs after the domain versions have been composed; installed -# legacy graph contracts and all project binding/outcome fields retain owners. -for _project_name, _domain_name in ( - ('project_files.graph_create', 'graphs.create'), - ('project_files.graph_create_external', 'graphs.create_external'), - ('project_files.graph_save', 'graphs.save')): - _current_graph_input = copy.deepcopy(_CONTRACTS[_domain_name][max(_CONTRACTS[_domain_name])]['inputSchema']) - _current_graph_input['properties'].update(copy.deepcopy(_PROJECT_FILES_MUTATION)) - _current_graph_input['required'] = list(dict.fromkeys( - _current_graph_input['required'] + list(_PROJECT_FILES_MUTATION))) - _CONTRACTS[_project_name][1]['inputSchema'] = _current_graph_input - CONTRACT_HEADER = 'Tuldok-Operation-Contract' CAPABILITIES_LIMIT = 1024 * 1024 MAX_OPERATIONS = 256 @@ -1802,7 +1021,6 @@ def contract(name, version=1): 'authority': 'owner' if name in _OWNER_OPERATION_IDS else 'agent', 'effects': 'mutation' if op['side_effects'] else 'read', 'retry': retry, 'bounds': {'request_bytes': REQUEST_LIMIT, 'response_bytes': RESPONSE_LIMIT, 'inline_decoded_bytes': INLINE_LIMIT, 'json_depth': DEPTH_LIMIT}} - if name in PROJECT_TRANSFER_OPERATIONS:public['bounds']['response_bytes']=REQUEST_LIMIT identity = dict(public, id=name, method=op['method'], path=op['path'], query=op['query'], injected=op['injected'], binary_fields=op['binary_fields'], mcp_name=op['mcp_name']) public['sha256'] = hashlib.sha256(encoded(identity)).hexdigest() @@ -1827,24 +1045,20 @@ def capabilities(catalog_id, profile='catalog'): raise AgentAPIError('Invalid capability catalog identity.', 'registry_invalid', 503) if profile == 'project_folder': return _project_folder_capabilities(catalog_id) - if profile not in ('catalog','project'): + if profile != 'catalog': raise AgentAPIError('Unsupported capability profile.','registry_invalid',503) operations = [] for name, versions in _CONTRACTS.items(): if name in PROJECT_FOLDER_OPERATIONS: continue - if (profile=='catalog' and name.startswith('project_files.') - or profile=='project' and not name.startswith(('project_files.','project_transfer.')) and name not in ('context.get','identity.get')): - continue # The protocol bound applies to this advertised profile, just as the - # receiver checks its one manifest. Disjoint catalog/project contracts - # are not all transmitted together. Keep the installed 256-op limit. + # receiver checks its one manifest. Keep the installed 256-op limit. if len(operations) >= MAX_OPERATIONS: raise AgentAPIError('Operation profile exceeds its capability bound.', 'registry_invalid', 503) if not 1 <= len(versions) <= MAX_CONTRACTS: raise AgentAPIError('Contract version count exceeds its bound.', 'registry_invalid', 503) operations.append({'id': name, 'contracts': [contract(name, version) for version in sorted(versions)], - 'availability': 'unavailable' if name in PROJECT_TRANSFER_OPERATIONS else 'available'}) + 'availability': 'available'}) value = {'format': 'agent_capabilities_v1', 'envelope_version': 1, 'catalog_id': catalog_id, 'operations': operations, 'limits': {'request_bytes': REQUEST_LIMIT, 'response_bytes': RESPONSE_LIMIT, 'max_operations': MAX_OPERATIONS}} @@ -2016,39 +1230,6 @@ def operation(name, version=None): return copy.deepcopy(versions[max(versions) if version is None else version]) -def measurement_comparison_row_limit(version=None): - """Return the selected immutable public contract's comparison budget.""" - selected=operation('project_files.measurement_compare',version) - return selected['outputSchema']['oneOf'][0]['properties']['result']['properties']['value']['properties']['value']['properties']['observation_count']['maximum'] - - -def _native_validation_result_ok(value, revision): - """Check the finite public truth fields without interpreting native runtime data. - - The native owner validates its scientific release/runtime observation. This - transport check prevents contradictory success and coercion into an ACK. - """ - fields={'status','valid','errors','validation_token','graph_revision','execution_sha256','release','runtime'} - def sha(raw): - return type(raw) is str and re.fullmatch('[a-f0-9]{64}',raw) is not None - if (type(value) is not dict or not fields.issubset(value) or set(value)-fields-{'selection_policy'} - or type(value['graph_revision']) is not int or value['graph_revision']!=revision - or type(value['valid']) is not bool or type(value['status']) is not str - or not value['status'].strip() or len(value['status'])>120 - or not sha(value['execution_sha256']) or type(value['errors']) is not list or len(value['errors'])>100 - or any(type(value[field]) is not dict and value[field] is not None for field in ('release','runtime'))): - return False - errors=value['errors'] - if any(type(error) is not dict or set(error)!={'path','message','code'} - or any(type(part) is not str or len(part)>2000 for part in error.values()) for error in errors): - return False - if value['valid']: - return (value['status']=='valid' and not errors and sha(value['validation_token']) - and value['release'] is not None and value['runtime'] is not None - and value['runtime'].get('available') is True) - return bool(errors) and value['status']==errors[0]['code'] and value['validation_token'] is None - - def _finite(value, depth=0, *, nul_path=None, _path=()): if depth > DEPTH_LIMIT: raise AgentAPIError('JSON nesting exceeds the transport bound.') @@ -2159,54 +1340,9 @@ def validate_registry(*, checkpoint=None): def validate_output(name, envelope, version=None): op = operation(name, version) - # A captured UTF-8 file is an exact inert byte witness, including NUL. This - # exception never admits NUL in input, metadata, error or other operation. - nul_path = ('result','value','version','text') if (op['operation_id']=='project_files.file_get' - and type(envelope) is dict and type(envelope.get('status')) is int and envelope['status']<400) else None - _finite(envelope, nul_path=nul_path) + _finite(envelope) if next(_validator(op['outputSchema']).iter_errors(envelope), None) is not None: raise AgentAPIError('HTTP result does not match its operation envelope.', 'transport', 502) - if op['operation_id'] in PROJECT_TRANSFER_OPERATIONS and envelope['status']<400: - value=envelope['result'] - if op['operation_id'] in ('project_transfer.status','project_transfer.preview','project_transfer.stop'): - phase,report=value['phase'],value['report'] - actions=['status'] - if phase in ('source_live','source_stopped'):actions+=['preview','report_page'] - if phase=='source_live' and report is not None:actions.append('stop') - if phase=='source_stopped' and report is not None:actions.append('extract') - if (value['source_catalog_id']==value['control_catalog_id'] or value['roots']!=sorted(set(value['roots'])) - or value['available_actions']!=actions - or phase=='source_stopped' and (value['backup'] is None or value['destination'] is None) - or phase=='source_fenced' and report is not None - or report is not None and (report['source']['catalog_id']!=value['source_catalog_id'] - or report['can_extract']!=(report['counts']['blockers']==0) - or phase=='source_live' and report['can_extract'] - or phase=='source_stopped' and report['source']['backup_receipt_sha256']!=value['backup']['receipt_sha256'])): - raise AgentAPIError('Extraction state differs from its source, phase or stopped backup.','transport',502) - if op['operation_id']=='project_transfer.extract': - receipt,selection=value['receipt'],value['selection'] - if (receipt['project_id']==receipt['source']['catalog_id'] or receipt['verification']['checkpoint']!=receipt['checkpoint'] - or selection['selected'] and (selection['error'] is not None or selection['state'] is None - or selection['state']['state']!='open' or selection['state']['project']['project_id']!=receipt['project_id'] - or selection['state']['project']['checkpoint']!=receipt['checkpoint']) - or not selection['selected'] and selection['error'] is None): - raise AgentAPIError('Extraction receipt differs from its independent project or selected state.','transport',502) - if op['operation_id'].startswith('project_files.') and envelope['status'] < 400: - value = envelope['result'] - if 'record' in value: - record, history = value['record'], value['history'] - revisions = [item['revision'] for item in history] - cursor = value['next_history_before_revision'] - if (any(item['id'] != record['id'] or item['revision'] > record['revision'] for item in history) - or revisions != sorted(set(revisions), reverse=True) - or cursor is not None and (not history or cursor != history[-1]['revision'])): - raise AgentAPIError('Project annotation history differs from its record.', 'transport', 502) - if 'items' in value: - identities = [item['id'] for item in value['items']] - cursor = value['next_after_id'] - if (identities != sorted(set(identities)) - or cursor is not None and (not identities or cursor != identities[-1])): - raise AgentAPIError('Project record page identity or continuation differs.', 'transport', 502) if op['operation_id'] == 'runs.artifact_segments' and envelope['status'] < 400: validate_artifact_segments(envelope['result']) if op['operation_id'] in ('runs.phase_timings', 'graphs.preparation_timings') and envelope['status'] < 400: @@ -2352,7 +1488,7 @@ def content_sha(value): def validate_arguments(name, arguments, version=None): op = operation(name, version) _finite(arguments) - if len(encoded(arguments, ensure_ascii=not op['operation_id'].startswith('project_files.'))) > REQUEST_LIMIT: + if len(encoded(arguments)) > REQUEST_LIMIT: raise AgentAPIError('Request exceeds the agent transport bound.', 'too_large', 413) if (op['operation_id'] == 'data.import_sequence' and type(arguments) is dict and type(arguments.get('files')) is dict @@ -2525,7 +1661,7 @@ def watch_read(): timer.daemon = True timer.start() try: - raw = encoded(body, ensure_ascii=not (selection is not None and selection[0].startswith('project_files.'))) if body is not None else None + raw = encoded(body) if body is not None else None if raw is not None and len(raw) > REQUEST_LIMIT: raise AgentAPIError('Request exceeds the agent transport bound.', 'too_large', 413) headers = {'Authorization': 'Bearer '+self._token, 'Accept': 'application/json', 'Accept-Encoding': 'identity', 'Connection': 'close'} @@ -2555,7 +1691,7 @@ def watch_read(): or response.getheader('Content-Type', '').split(';')[0].strip() != 'application/json'): raise AgentAPIError('HTTP response framing or content type is unsupported.', 'transport', 502) length = int(lengths[0]) - receive_limit=CAPABILITIES_LIMIT if path=='/api/agent/capabilities' or selection is not None and selection[0] in PROJECT_TRANSFER_OPERATIONS else RESPONSE_LIMIT + receive_limit=CAPABILITIES_LIMIT if path=='/api/agent/capabilities' else RESPONSE_LIMIT if length > receive_limit: raise AgentAPIError('HTTP response exceeds the agent receive bound.', 'response_too_large', 413) data = bytearray() @@ -2572,9 +1708,7 @@ def watch_read(): data.extend(chunk) if time.monotonic() > deadline: raise TimeoutError() - nul_path = ('value','version','text') if (selection is not None - and selection[0]=='project_files.file_get' and response.status<400) else None - value = decode(data, nul_path=nul_path) + value = decode(data) self._check_read_budget() if response.status >= 400: if not isinstance(value, dict) or not isinstance(value.get('error'), str): @@ -2594,20 +1728,7 @@ def watch_read(): report = value['preflight_report'] if has_report else None if has_report and self._token in json.dumps(report, ensure_ascii=False): raise AgentAPIError('Preflight report contains credential material.', 'transport', 502) - receipt = None - if selection is not None and selection[0].startswith('project_files.') and 'receipt' in value: - receipt = value['receipt'] - if (next(_validator(PROJECT_FILES_RECEIPT).iter_errors(receipt), None) is not None - or self._token in json.dumps(receipt, ensure_ascii=False)): - raise AgentAPIError('Malformed project outcome receipt.', 'transport', 502) - if selection is not None and selection[0] in PROJECT_TRANSFER_OPERATIONS and 'receipt' in value: - receipt=value['receipt'] - if (next(_validator(_PROJECT_TRANSFER_PARTIAL).iter_errors(receipt),None) is not None - or self._token in json.dumps(receipt,ensure_ascii=False)): - raise AgentAPIError('Malformed extraction outcome receipt.','transport',502) value = {'code': code, 'error': value['error'].replace(self._token, '[redacted]')[:1000]} - if receipt is not None: - value['receipt'] = copy.deepcopy(receipt) if has_report: value['preflight_report'] = report return {'status': response.status, 'result': value} @@ -2713,253 +1834,6 @@ def call(self, name, arguments, *, observer=None, observation=None): envelope = self._request(method, path, body, selection=selection) result = validate_output(name, envelope, version) self._check_read_budget() - if op['operation_id'] in PROJECT_TRANSFER_OPERATIONS: - value=result['result'];action=op['operation_id'].split('.')[1] - if result['status']>=400: - if value.get('receipt') is not None and value['receipt']['request_key']!=arguments.get('request_key'): - raise AgentAPIError('Extraction outcome belongs to a different request.','transport',502) - elif action in ('status','preview','stop'): - if action=='stop': - if (value['source_catalog_id']!=self.catalog_id or value['phase']!='source_stopped' - or value['binding']==arguments['binding'] or value['report'] is not None - or value['backup']['root']!=arguments['backup_root'] or value['backup']['directory']!=arguments['backup_directory'] - or value['destination']!={'root':arguments['destination_root'],'directory':arguments['directory']}): - raise AgentAPIError('Stopped-source result differs from the explicit backup or destination.','transport',502) - else: - current=value['source_catalog_id'] if value['phase']=='source_live' else value['control_catalog_id'] - if current!=self.catalog_id or action=='preview' and (value['binding']!=arguments['binding'] or value['report'] is None): - raise AgentAPIError('Extraction state belongs to another current host or process binding.','transport',502) - elif action=='report_page': - offset,limit=arguments.get('offset',0),arguments.get('limit',40) - if (any(value[field]!=arguments[field] for field in ('binding','report_sha256','section')) - or value['offset']!=offset or value['limit']!=limit - or len(value['items'])!=min(limit,max(0,value['total']-offset))): - raise AgentAPIError('Extraction report page differs from its reviewed report or continuation.','transport',502) - elif (value['binding']!=arguments['binding'] or value['receipt']['request_key']!=arguments['request_key'] - or value['receipt']['report_sha256']!=arguments['report_sha256']): - raise AgentAPIError('Extraction receipt belongs to another controller report or request.','transport',502) - if op['operation_id'] in ('project_files.save_as','project_files.compose') and result['status']<400: - value=result['result'];fork=value['fork'];state=value['state'] - if (state['state']!='open' or state['project']['project_id']!=fork['project_id'] - or state['project']['checkpoint']!=fork['checkpoint'] or state['project']['name']!=arguments['name'] or state['binding']==arguments['binding'] - or fork['project_id']==fork['source_project_id'] - or fork['source_checkpoint']!=arguments['expected_checkpoint'] - or any(fork[field]!=arguments[field] for field in ('root','directory','request_key'))): - raise AgentAPIError('Save As result differs from its source, destination or selected state.','transport',502) - if op['operation_id']=='project_files.compose': - expected=[dict(project_id=fork['source_project_id'],checkpoint=arguments['expected_checkpoint'])] - expected.extend({key:item[key] for key in ('project_id','checkpoint')} for item in arguments['sources']) - if value['sources']!=expected: - raise AgentAPIError('Composition result differs from its exact ordered sources.','transport',502) - elif op['operation_id'] in PROJECT_FILES_M2 | PROJECT_FILES_M3 | PROJECT_FILES_M4: - value = result['result'] - if result['status'] >= 400: - receipt = value.get('receipt') - if receipt is not None and receipt['request_key'] != arguments.get('request_key'): - raise AgentAPIError('Project receipt belongs to a different request.', 'transport', 502) - else: - if value['binding'] != arguments['binding']: - raise AgentAPIError('Project response belongs to a different session binding.', 'transport', 502) - if not op['side_effects'] and value['checkpoint'] != arguments['checkpoint']: - raise AgentAPIError('Project read response belongs to a different checkpoint.', 'transport', 502) - page = value['value'] - action=op['operation_id'].removeprefix('project_files.') - if action=='files_adopt': - if (len(page['items'])!=len(arguments['items']) - or page['changed_count']!=sum(item['changed'] for item in page['items']) - or sum(item['bytes'] for item in page['items'])>8*1024*1024): - raise AgentAPIError('Batch adoption count or capture bound differs.','transport',502) - for item,reviewed in zip(page['items'],arguments['items']): - identity=hashlib.sha256((value['project_id']+'\0'+reviewed['kind']+'\0'+reviewed['path']).encode()).hexdigest() - if (item['id']!=identity or item['project_id']!=value['project_id'] - or item['kind']!=reviewed['kind'] or item['path']!=reviewed['path'] - or item['sha256']!=reviewed['expected_sha256'] - or item['revision']!=reviewed['expected_revision']+int(item['changed'])): - raise AgentAPIError('Batch adoption differs from its reviewed files.','transport',502) - if action in ('file_get','file_adopt','file_adopt_deletion'): - kind,path=page['kind'],page['path'] - expected_id=hashlib.sha256((value['project_id']+'\0'+kind+'\0'+path).encode()).hexdigest() - if page['id']!=expected_id or page['project_id']!=value['project_id']: - raise AgentAPIError('Working file belongs to a different project or path.','transport',502) - if action=='file_get': - version=page['version'];deleted=version.get('deleted') is True - raw=None if deleted else version['text'].encode('utf-8') - if (deleted and kind!='note' or page['id']!=arguments['file_id'] or arguments.get('revision',version['revision'])!=version['revision'] - or not deleted and (len(raw)!=version['bytes'] or len(raw)>1048576 or hashlib.sha256(raw).hexdigest()!=version['sha256'])): - raise AgentAPIError('Captured working file differs from its exact revision or bytes.','transport',502) - elif action=='file_adopt_deletion': - if (kind!='note' or path!=arguments['path'] or page['revision']!=arguments['expected_revision']+1): - raise AgentAPIError('Note deletion differs from the reviewed path or revision.','transport',502) - elif (kind!=arguments['kind'] or path!=arguments['path'] or page['sha256']!=arguments['expected_sha256'] - or page['revision']!=arguments['expected_revision']+int(page['changed'])): - raise AgentAPIError('Working-file adoption differs from the reviewed current bytes.','transport',502) - if action=='file_history' and page['id']!=arguments['file_id']: - raise AgentAPIError('Working-file history belongs to another file.','transport',502) - if action=='files_inspect': - for item in page['items']: - identity=hashlib.sha256((value['project_id']+'\0'+item['kind']+'\0'+item['path']).encode()).hexdigest() - if (item['id']!=identity or item['state']=='unchanged' and (item['observed_sha256']!=item['expected_sha256'] - or item['observed_bytes']!=item['expected_bytes'] or item['reason'] is not None) - or item['expected_sha256'] is None and (item['kind']!='note' or item['expected_bytes']!=0 or item['state'] in ('unchanged','missing')) - or item['state']=='deleted' and (item['expected_sha256'] is not None or item['observed_sha256'] is not None or item['observed_bytes'] is not None or item['reason'] is not None)): - raise AgentAPIError('Working-file observation differs from its selected identity or declared bytes.','transport',502) - if action=='material_intents': - for item in page['items']: - if (item['catalog_id']!=value['project_id'] or item['id']!=value['project_id']+'.'+item['definition_id'] - or item['fork_origin']['family']!=item['family']): - raise AgentAPIError('Material intent summary belongs to another definition.','transport',502) - if action=='material_intent_capabilities' and any(not item['id'].startswith(value['project_id']+'.') - or not re.fullmatch('[a-f0-9]{32}',item['id'][33:]) for item in page['items']): - raise AgentAPIError('Material readiness belongs to another selected project.','transport',502) - if action=='material_intent' and (page['family']!=arguments['family'] or page['current']['id']!=arguments['definition_id'] - or page['current']['definition_family']!=arguments['family'] or page['fork_origin']['family']!=arguments['family'] - or page['current']['catalog_id']!=value['project_id'] or page['id']!=value['project_id']+'.'+arguments['definition_id']): - raise AgentAPIError('Material intent belongs to a different definition.','transport',502) - if action=='fork_info': - if page['project_id']!=value['project_id']: - raise AgentAPIError('Fork mapping belongs to a different selected project.','transport',502) - mapping=page['mapping'];offset=arguments.get('offset',0);limit=arguments.get('limit',40) - if (mapping['offset']!=offset or mapping['limit']!=limit - or len(mapping['items'])!=min(limit,max(0,mapping['total']-offset))): - raise AgentAPIError('Fork mapping differs from its requested continuation.','transport',502) - if isinstance(page, dict) and {'items', 'offset', 'limit', 'total'} <= page.keys(): - requested = arguments.get('limit', 1 if op['operation_id'] in ('project_files.data_history', 'project_files.data_response_history', 'project_files.data_preference_history') else 40) - if (page['offset'] != arguments.get('offset', 0) or page['limit'] != requested - or len(page['items']) > requested or (len(page['items']) > 0 and page['total'] < page['offset'] + len(page['items'])) - or len(page['items']) != min(requested, max(0, page['total'] - page['offset']))): - raise AgentAPIError('Project page differs from its requested continuation.', 'transport', 502) - if 'origin_catalog_id' in arguments and isinstance(page, dict) and 'origin_catalog_id' in page: - if page['origin_catalog_id'] != arguments['origin_catalog_id']: - raise AgentAPIError('Historical response belongs to a different origin.', 'transport', 502) - action = op['operation_id'].split('.')[1] - if action == 'execution_health': - requested = arguments.get('limit', 40) - if (page['offset'] != arguments.get('offset', 0) or page['limit'] != requested - or page['active_run_ids'] != sorted(set(page['active_run_ids'])) - or len(page['active_run_ids']) != min(requested, max(0, page['active_count'] - page['offset']))): - raise AgentAPIError('Current custody page differs from its requested continuation.', 'transport', 502) - if version>=2: - phases=page['native_phases'];identities=[item['phase_id'] for item in phases['items']] - if (phases['offset']!=arguments.get('offset',0) or phases['limit']!=requested - or len(phases['items'])!=min(requested,max(0,phases['total']-phases['offset'])) - or identities!=sorted(set(identities)) - or any(item['origin_catalog_id']!=value['project_id'] for item in phases['items'])): - raise AgentAPIError('Current native phase page differs from its selected project or continuation.','transport',502) - if action in ('execution_study_prepare_package','execution_study_prepare_verifier','execution_study_reconcile_preparation'): - if (page['trial']['study_id']!=arguments['study_id'] or page['trial']['material']['catalog_id']!=value['project_id'] - or page['model']['catalog_id']!=value['project_id'] - or action!='execution_study_reconcile_preparation' and (page['candidate_id']!=arguments['candidate_id'] - or page['runtime_snapshot_sha256']!=arguments['runtime_snapshot_sha256']) - or action=='execution_study_prepare_verifier' and any(page[field]!=arguments[field] for field in ('package_run_id','package_sha256'))): - raise AgentAPIError('Candidate preparation belongs to a different Study, Candidate or reviewed runtime.','transport',502) - if action=='execution_study_abandon_preparation' and (page['origin_catalog_id']!=value['project_id'] - or page['study_id']!=arguments['study_id'] or page['preparation_key']!=arguments['preparation_key'] - or page['reason']!=arguments['reason'] or page['candidate']['catalog_id']!=value['project_id']): - raise AgentAPIError('Preparation abandonment differs from its current exact intent and reason.','transport',502) - if action=='runtime_inspect': - inventory=page['files'];offset=arguments.get('offset',0);limit=arguments.get('limit',40) - if (page['source']!=arguments['source'] or inventory['offset']!=offset or inventory['limit']!=limit - or inventory['total']!=page['file_count'] - or len(inventory['items'])!=min(limit,max(0,inventory['total']-offset)) - or [item['path'] for item in inventory['items']]!=sorted(set(item['path'] for item in inventory['items'])) - or [item['name'] for item in page['packages']]!=sorted(set(item['name'] for item in page['packages']))): - raise AgentAPIError('Runtime inventory differs from its configured source or continuation.','transport',502) - if action=='runtime_capture': - ref=page['runtime_ref'] - if (page['project_id']!=value['project_id'] or page['manifest_sha256']!=arguments['expected_inventory_sha256'] - or page['request_key']!=arguments['request_key'] or ref['catalog_id']!=value['project_id'] or ref['id']!=ref['sha256']): - raise AgentAPIError('Runtime capture differs from its exact reviewed inventory or request.','transport',502) - if action=='runtime_abandon' and (page['project_id']!=value['project_id'] - or page['capture_key']!=arguments['capture_key'] or page['reason']!=arguments['reason']): - raise AgentAPIError('Runtime abandonment differs from its current exact capture and reason.','transport',502) - if action=='runtime_status': - intent,complete=page['intent'],page['result'] - abandonment=page.get('abandonment') - expected='abandoned' if abandonment is not None else 'captured' if complete is not None else 'intent_recorded' if intent is not None else 'absent' - if (page['state']!=expected or complete is not None and intent is None - or abandonment is not None and (intent is None or complete is not None - or abandonment['project_id']!=value['project_id'] or abandonment['capture_key']!=arguments['capture_key'] - or abandonment['manifest_sha256']!=intent['manifest_sha256']) - or any(item['project_id']!=value['project_id'] or item['request_key']!=arguments['capture_key'] - for item in (intent,complete) if item is not None) - or complete is not None and (any(intent[field]!=complete[field] for field in - ('project_id','manifest_sha256','file_count','total_bytes','request_key')) - or complete['runtime_ref']['catalog_id']!=value['project_id'] - or complete['runtime_ref']['id']!=complete['runtime_ref']['sha256'])): - raise AgentAPIError('Runtime status differs from its retained capture request.','transport',502) - if action=='native_preflight' and not _native_validation_result_ok(page,arguments['revision']): - raise AgentAPIError('Native validation differs from the saved graph revision or result.','transport',502) - if action=='native_reconcile' and (page['origin_catalog_id']!=value['project_id'] or page['phase_id']!=arguments['phase_id']): - raise AgentAPIError('Native phase observation differs from the selected current phase.','transport',502) - if action in ('native_submit','native_retry') and (page['origin_catalog_id']!=value['project_id'] - or action=='native_retry' and page['run_id']==arguments['run_id']): - raise AgentAPIError('Native admission differs from the selected project.','transport',502) - if action in ('execution_approve_external', 'execution_study_approve'): - grant = page['grant'] - expected = arguments['expected_digest'] if action == 'execution_approve_external' else arguments['expected_material_sha256'] - if (grant['catalog_id'] != value['project_id'] or grant['material_sha256'] != expected - or grant['consumer_actor_id'] != arguments['consumer_actor_id'] - or grant['revoked_at'] is not None or grant['expires_at'] <= grant['created_at']): - raise AgentAPIError('Current local approval differs from its reviewed material or actor.', 'transport', 502) - if action in ('execution_submit_external', 'execution_cancel', 'execution_reconcile_current', - 'execution_study_admit', 'execution_study_stop') or action.startswith('execution_producer_') or action in ('execution_generation_resume', 'execution_grounded_review'): - if 'origin_catalog_id' in page and page['origin_catalog_id'] != value['project_id']: - raise AgentAPIError('Current execution acknowledgement belongs to another project.', 'transport', 502) - if action == 'execution_cancel' and page['run_id'] != arguments['run_id']: - raise AgentAPIError('Cancellation acknowledgement belongs to another Run.', 'transport', 502) - if action == 'execution_study_continue' and page['id'] != arguments['study_id']: - raise AgentAPIError('Study continuation belongs to another Study.', 'transport', 502) - if action in ('execution_study_admit', 'execution_study_stop') and page['study_id'] != arguments['study_id']: - raise AgentAPIError('Study acknowledgement belongs to another Study.', 'transport', 502) - if action == 'execution_study_admit' and (page['trial_id'] != arguments['trial_id'] - or page['reservation']['trial_id'] != page['trial_id'] or page['reservation']['run_id'] != page['run_id']): - raise AgentAPIError('Study admission differs from its selected Trial reservation.', 'transport', 502) - if action == 'execution_study_stop' and (page['receipt']['study_id'] != page['study_id'] - or len(page['receipt']['run_ids']) != len(set(page['receipt']['run_ids']))): - raise AgentAPIError('Study epoch closure receipt is inconsistent.', 'transport', 502) - producer_actions = {'execution_producer_start': 'start', 'execution_generation_resume': 'resume', - 'execution_grounded_review': 'review', 'execution_producer_decide': 'decide', 'execution_producer_cancel': 'cancel'} - if action in producer_actions: - family = arguments.get('family', 'generation_history' if action == 'execution_generation_resume' else 'grounded_history') - if (page['family'] != family or page['action'] != producer_actions[action] - or 'producer_id' in arguments and page['producer_id'] != arguments['producer_id'] - or action == 'execution_producer_start' and 'request_id' in arguments['document'] and page['producer_id'] != arguments['document']['request_id']): - raise AgentAPIError('Producer acknowledgement differs from its exact current action.', 'transport', 502) - if op['operation_id'] == 'project_files.run_document_segment': - try: - segment = base64.b64decode(page['base64'], validate=True) - except (ValueError, binascii.Error): - raise AgentAPIError('Invalid retained Run document segment bytes.', 'transport', 502) from None - end = arguments['offset'] + len(segment) - if (page['origin_catalog_id'] != arguments['origin_catalog_id'] or page['run_id'] != arguments['run_id'] - or page['sha256'] != arguments['expected_sha256'] or page['offset'] != arguments['offset'] - or page['limit'] != arguments['limit'] or page['offset'] > page['bytes'] - or len(segment) != min(page['limit'], page['bytes'] - page['offset']) - or page['next_offset'] != (end if end < page['bytes'] else None)): - raise AgentAPIError('Retained Run document segment differs from its exact selection.', 'transport', 502) - if action.startswith('measurement_'): - _validate_measurement_selection(action,page,arguments,value['project_id']) - target_key = {'data_get': 'record_id', 'model_get': 'model_id', 'graph_get': 'graph_id', - 'recipe_get': 'recipe_id', 'trial': 'trial_id'}.get(op['operation_id'].split('.')[1]) - if target_key and page.get('id') != arguments[target_key]: - raise AgentAPIError('Project response belongs to a different record.', 'transport', 502) - if op['operation_id'].startswith('project_files.') and result['status'] < 400: - value = result['result']; action = op['operation_id'].split('.')[1] - if action in ('query', 'get', 'import_text', 'annotate', 'save') and value['binding'] != arguments['binding']: - raise AgentAPIError('Project response belongs to a different session binding.', 'transport', 502) - if action in ('query', 'get') and value['checkpoint'] != arguments['checkpoint']: - raise AgentAPIError('Project read response belongs to a different checkpoint.', 'transport', 502) - if action == 'query' and (len(value['items']) > arguments.get('limit', 40) - or any(item['id'] <= arguments.get('after_id', '') for item in value['items'])): - raise AgentAPIError('Project record page differs from its requested continuation.', 'transport', 502) - if action in ('get', 'import_text', 'annotate'): - if (len(value['history']) > arguments.get('history_limit', 1) - or 'before_revision' in arguments and any(item['revision'] >= arguments['before_revision'] for item in value['history'])): - raise AgentAPIError('Project history page differs from its requested continuation.', 'transport', 502) - if action in ('get', 'annotate') and value['record']['id'] != arguments['record_id']: - raise AgentAPIError('Project response belongs to a different record.', 'transport', 502) - if action == 'save' and (value['state'] != 'open' or value['project']['checkpoint'] != arguments['expected_checkpoint']): - raise AgentAPIError('Project Save response differs from its selected checkpoint.', 'transport', 502) if op['operation_id'] in ('runs.coordinator_health', 'runs.recover_coordinator') and result['status'] < 400: value = result['result']; request = value['recovery_request'] if value['catalog_id'] != self.catalog_id: @@ -3071,147 +1945,6 @@ def call(self, name, arguments, *, observer=None, observation=None): return result -class ProjectFilesOwnerClient(AgentClient): - """Explicit owner file-project access; no unrelated owner operations.""" - # Large retained projects may outlast the generic transport's five minutes. - # Only an explicit owner configuration opts into a longer absolute wait. - MAX_TIMEOUT_SECONDS = 7200 - - OPERATIONS = frozenset('project_files.' + action for action in - ('status', 'new', 'open', 'save', 'close', 'query', 'get', 'import_text', 'annotate')) | PROJECT_FILES_M2 | PROJECT_FILES_M3 | PROJECT_FILES_M4 - - def bootstrap(self): - result = self._bootstrap('owner') - self._selected = {name: version for name, version in self._selected.items() if name in self.OPERATIONS} - result['operations'] = sorted(self._selected) - return result - - def call(self, name, arguments, **kwargs): - if name not in self.OPERATIONS: - raise AgentAPIError('Owner project client only supports explicit file-project operations.', 'operation_unsupported', 409) - return super().call(name, arguments, **kwargs) - - -class ProjectTransferOwnerClient(AgentClient): - """Five current-owner extraction calls, with explicit authority handoff. - - After a dispatched Stop, discard this client. Construct another instance - with the independently obtained current host credential and catalog ID. - """ - OPERATIONS=PROJECT_TRANSFER_OPERATIONS - - def __init__(self,*args,**kwargs): - super().__init__(*args,**kwargs) - self._handoff_required=False - - def bootstrap(self): - if self._handoff_required: - raise AgentAPIError('Stop requires an independently authenticated current-host client.','authentication_handoff',409) - result=self._bootstrap('owner') - self._selected={name:version for name,version in self._selected.items() if name in self.OPERATIONS} - result['operations']=sorted(self._selected) - return result - - def call(self,name,arguments,**kwargs): - if name not in self.OPERATIONS: - raise AgentAPIError('Transfer owner client only supports five explicit extraction operations.','operation_unsupported',409) - if self._handoff_required: - raise AgentAPIError('Discard the source client and authenticate the current host independently.','authentication_handoff',409) - try: - result=super().call(name,arguments,**kwargs) - except AgentAPIError as error: - if name=='project_transfer.stop' and (error.status>=500 or error.code in ('transport','unknown','outcome_unknown')): - self._handoff_required=True - raise - if name=='project_transfer.stop': - # Even a failed stop can rotate binding or close source authority. - # No response causes an automatic credential/catalog substitution. - self._handoff_required=True - return result - - -def _validate_measurement_selection(action, page, arguments, project_id): - """Correlate fixed scalar replies; scientific validity remains upstream.""" - def refuse(): - raise AgentAPIError('Retained measurements differ from the selected source or continuation.', 'transport', 502) - if action=='measurement_compare': - return _validate_comparison_selection(page, arguments) - if action=='measurement_sources': - offset,limit=arguments.get('offset',0),arguments.get('limit',40) - keys=[(d['origin_catalog_id'],d['id']) for d in page['items']] - if (page['offset']!=offset or page['limit']!=limit or keys!=sorted(set(keys)) - or len(keys)!=min(limit,max(0,page['total']-offset))):refuse() - return - if action=='measurement_import': - source=page['source'] - if (page['origin_catalog_id']!=project_id or page['id']!=arguments['expected_sha256'] - or page['blob']['sha256']!=page['id'] or source['measured_sha256']!=page['id'] - or source['reference_id']!=arguments['reference_id'] - or any(source[k]!=v for k,v in arguments['snapshot'].items())):refuse() - return - source,result=page['source'],page['value'] - if (source['origin_catalog_id']!=arguments['origin_catalog_id'] or source['id']!=arguments['packet_sha256'] - or source['blob']['sha256']!=source['id'] or source['source']['measured_sha256']!=source['id']):refuse() - if action!='measurement_subjects' and result['packet_sha256']!=source['id']:refuse() - if action=='measurement_inspect' and result['observation']['id']!=arguments['observation_id']:refuse() - if action=='measurement_metadata' and result['title']!=source['title']:refuse() - if action in ('measurement_query','measurement_subjects'): - offset,limit=arguments.get('offset',0),arguments.get('limit',50 if action=='measurement_query' else 40) - rows=result['rows' if action=='measurement_query' else 'items'] - if (result['offset']!=offset or result['limit']!=limit - or len(rows)!=min(limit,max(0,result['total']-offset))):refuse() - if action=='measurement_query': - subjects=result['subject_ids'] - if (result['metric']['id']!=arguments['metric_id'] or result['filters']!=arguments.get('filters',{}) - or 'subject_ids' in arguments and subjects!=arguments['subject_ids'] - or len(subjects)!=len(set(subjects)) or [s['subject_id'] for s in result['summary']]!=subjects - or any(r['metric_id']!=arguments['metric_id'] or r['subject_id'] not in subjects for r in result['rows'])):refuse() - - -def _validate_comparison_selection(page, arguments): - """Bind aggregate replies to reviewed packets, subjects and exact page intent.""" - def refuse(): - raise AgentAPIError('Measurement comparison differs from its selected packets or continuation.', 'transport', 502) - def key(locator): - return locator['origin_catalog_id'], locator['packet_sha256'] - selected = arguments['sources'] - keys = [key(item) for item in selected] - documents, value = page['sources'], page['value'] - if (len(keys)!=len(set(keys)) or len(documents)!=len(keys) - or [(doc['origin_catalog_id'],doc['id']) for doc in documents]!=keys - or any(doc['blob']['sha256']!=doc['id'] or doc['source']['measured_sha256']!=doc['id'] for doc in documents) - or sum(doc['blob']['bytes'] for doc in documents)>128*1024*1024 - or value['definition_source']!=selected[0]):refuse() - subjects = value['subjects'] - identities = [subject['id'] for subject in subjects] - if (len(identities)!=len(set(identities)) or any(key(subject['source']) not in keys for subject in subjects) - or value['observation_count']!=len(subjects)*value['case_count']*len(value['metrics'])):refuse() - owners = {subject['id']:subject['source'] for subject in subjects} - query = value['query'] - if 'metric_id' not in arguments: - if query is not None:refuse() - return - if query is None:refuse() - wanted = arguments.get('subject_ids', identities) - offset,limit = arguments.get('offset',0),arguments.get('limit',50) - metrics = [metric for metric in value['metrics'] if metric['id']==arguments['metric_id']] - if (len(metrics)!=1 or query['metric']!=metrics[0] or query['subject_ids']!=wanted - or len(wanted)!=len(set(wanted)) or any(identity not in owners for identity in wanted) - or query['filters']!=arguments.get('filters',{}) - or query['offset']!=offset or query['limit']!=limit - or len(query['rows'])!=min(limit,max(0,query['total']-offset)) - or [summary['subject_id'] for summary in query['summary']]!=wanted - or sum(summary['count'] for summary in query['summary'])!=query['total']):refuse() - for summary in query['summary']: - if (summary['source']!=owners[summary['subject_id']] - or sum(summary['states'].values())!=summary['count'] - or (summary['maximum'] is None)!=(summary['states']['measured']==0)):refuse() - for row in query['rows']: - if (row['subject_id'] not in wanted or row['metric_id']!=arguments['metric_id'] - or row['source']!=owners[row['subject_id']] - or (row['value'] is None)!=(row['state']!='measured')):refuse() - - class PublicationOwnerClient(AgentClient): """Explicit owner publication actions only; ordinary AgentClient stays agent-only.""" OPERATIONS = frozenset(('runs.publication_status', 'runs.recover_publication', 'runs.cancel_publication', diff --git a/app.py b/app.py index 040e5698..274d3a27 100644 --- a/app.py +++ b/app.py @@ -1,6 +1,5 @@ """Tuldok: local image capture and corner-label dataset workspace.""" import argparse -from contextlib import contextmanager import psycopg import ai import ai_codex @@ -42,16 +41,12 @@ import io import ipaddress import json -import math import re import shutil from metadata import Metadata, StorageError, CommitOutcomeUnknown, CatalogBusy -from project_store import ProjectStoreError from image_sources import ImageSources, Conflict, now, metadata, validate_annotation, CORNERS, VISIBILITY, SPLITS import tempfile import threading -import time -import uuid import zipfile from datetime import datetime, timezone from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer @@ -68,13 +63,6 @@ class Dataset(ImageSources): def __init__(self, path, *, dsn=None, project_roots=None): self._close_lock = threading.RLock() self._closed = False - self._extraction_condition = threading.Condition() - self._extraction_requests = {} - self._extraction_stopping = False - self._extraction_binding = uuid.uuid4().hex - self._extraction_guard = None - self._extraction_closer = None - self._extraction_close_error = None self.path = Path(path).resolve() self.path.mkdir(parents=True, exist_ok=True) (self.path / 'images').mkdir(exist_ok=True) @@ -123,76 +111,6 @@ def close(self): self.db.close() self._closed = True - def close_for_project_extraction(self, *, deadline): - """Bound this explicit stop without treating a timeout as cessation.""" - guard = self._extraction_guard - if guard is None: - raise workbench.WorkbenchError('A drained original controller is required.', 'source_busy', 409) - guard.require(self) - if type(deadline) not in (int, float) or not math.isfinite(deadline): - raise workbench.WorkbenchError('An exact stop deadline is required.') - with self._extraction_condition: - if self._extraction_closer is None: - def close_owned(): - try: - self.close() - except BaseException as error: - self._extraction_close_error = error - self._extraction_closer = threading.Thread( - target=close_owned, name='tuldok-legacy-extraction-close', daemon=True) - try: - self._extraction_closer.start() - except BaseException as error: - self._extraction_close_error = error - raise workbench.WorkbenchError('Owned legacy closure could not start; source remains fenced.', 'unknown', 503) from error - closer = self._extraction_closer - closer.join(max(0, deadline - time.monotonic())) - if closer.is_alive(): - raise workbench.WorkbenchError('Owned legacy workers have not drained; source remains fenced.', 'source_busy', 409) - if self._extraction_close_error is not None: - raise workbench.WorkbenchError('Owned legacy closure failed; source remains fenced.', 'unknown', 503) from self._extraction_close_error - if not self._closed: - raise workbench.WorkbenchError('Owned legacy closure is unconfirmed; source remains fenced.', 'unknown', 503) - guard.require(self) - - @contextmanager - def _project_request(self): - """Fence new legacy handlers before an explicit extraction stop.""" - identity = threading.get_ident() - with self._extraction_condition: - if self._extraction_stopping: - raise workbench.WorkbenchError('This catalog is stopped for project extraction.', 'source_stopping', 409) - self._extraction_requests[identity] = self._extraction_requests.get(identity, 0) + 1 - try: - yield - finally: - with self._extraction_condition: - self._extraction_requests[identity] -= 1 - if not self._extraction_requests[identity]: - del self._extraction_requests[identity] - self._extraction_condition.notify_all() - - def stop_for_project_extraction(self, backup_parent_fd, backup_directory, external_roots=None): - """Explicit owner action; ordinary preview/Open never enters this path.""" - deadline = time.monotonic() + 60 - identity = threading.get_ident() - with self._extraction_condition: - if self._extraction_stopping: - raise workbench.WorkbenchError('Catalog extraction stop already has an owner.', 'source_stopping', 409) - self.access.require('admin', 'project_transfer.stop_source', owner_only=True) - self._extraction_stopping = True - guard = _LegacyExtractionGuard(self, self._extraction_binding, identity) - self._extraction_guard = guard - while any(thread != identity and count for thread, count in self._extraction_requests.items()): - remaining = deadline - time.monotonic() - if remaining <= 0: - raise workbench.WorkbenchError('Existing requests have not drained; catalog remains fenced.', 'source_busy', 409) - self._extraction_condition.wait(min(.1, remaining)) - from project_transfer import stop_source - return stop_source(self, backup_parent_fd=backup_parent_fd, backup_directory=backup_directory, - external_roots=external_roots, controller_guard=guard) - - @authorized('execute', 'dataset.suggest', owner_only=True) def suggest(self, body): sample_id = body.get('sample_id') @@ -248,27 +166,12 @@ def _export(self): raise -class _LegacyExtractionGuard: - """An in-process controller proof, never a transport or project record.""" - def __init__(self, dataset, binding, owner_thread): - self.dataset, self.binding, self.owner_thread = dataset, binding, owner_thread - - def require(self, dataset): - with dataset._extraction_condition: - if (dataset is not self.dataset or dataset._extraction_guard is not self - or dataset._extraction_binding != self.binding or not dataset._extraction_stopping - or threading.get_ident() != self.owner_thread - or any(thread != self.owner_thread and count for thread, count in dataset._extraction_requests.items())): - raise workbench.WorkbenchError('Extraction requires the drained original catalog controller.', 'source_busy', 409) - - -def make_handler(dataset, observer=None, *, transfer_controller=None): +def make_handler(dataset, observer=None): class Handler(BaseHTTPRequestHandler): def log_message(self, *_): pass def _observe_request(self, handler): - self._handoff_stopped_source() name, version = (agent_api.observation_operation(self.command, self.path, self.headers) if observer is not None else (None, None)) self._observation_operation, self._observation_version = name, version @@ -276,13 +179,9 @@ def _observe_request(self, handler): self._observation_finished = False self._contract_selection = None try: - if (urlsplit(self.path).path == '/api/workspace/project-transfer' - or urlsplit(self.path).path.startswith('/api/workspace/project-transfer/')): - return self._handle_project_transfer() if isinstance(dataset, Dataset): try: - with dataset._project_request(): - return handler() + return handler() except workbench.WorkbenchError as error: return self.reply({'error': str(error), 'code': error.code}, error.status) return handler() @@ -291,71 +190,6 @@ def _observe_request(self, handler): observe_stage(observer, self._observation, 'terminal', outcome='unknown', delivery='incomplete') self._observation_finished = True - def _handoff_stopped_source(self): - nonlocal dataset - if transfer_controller is None or transfer_controller.phase == 'source_live': - return - source = transfer_controller.dataset - # A failed stop may still have old handlers draining. Keep their - # original Dataset closure until the source's request gate proves - # them absent; new ordinary requests remain fenced meanwhile. - with source._extraction_condition: - if source._extraction_stopping and not any(source._extraction_requests.values()): - dataset = transfer_controller.control_workspace - - def _handle_project_transfer(self): - """One explicit source-to-control authority transition, never Open.""" - nonlocal dataset - routes = {('GET', '/api/workspace/project-transfer'): 'status', - ('POST', '/api/workspace/project-transfer/preview'): 'preview', - ('GET', '/api/workspace/project-transfer/report'): 'report_page', - ('POST', '/api/workspace/project-transfer/stop'): 'stop', - ('POST', '/api/workspace/project-transfer/extract'): 'extract'} - try: - if transfer_controller is None: - raise workbench.WorkbenchError('Configure an explicit existing legacy extraction controller first.', 'unavailable', 409) - action = routes.get((self.command, urlsplit(self.path).path)) - if action is None: - raise workbench.WorkbenchError('Unknown extraction operation.', 'unsupported', 404) - name = 'project_transfer.' + action - token, bearer = self._credential() - authority = transfer_controller.access - with authority.bind(token): - self._same_origin(self.command == 'POST' and not bearer) - selected = self._select_contract() - agent_api.require_selection(selected, name) - body = None - if self.command == 'POST': - if self.headers.get_content_type() != 'application/json': - raise agent_api.AgentAPIError('Send a bounded JSON request.', 'invalid', 400) - length = int(self.headers.get('Content-Length', '0')) - if not 0 < length <= agent_api.REQUEST_LIMIT: - raise agent_api.AgentAPIError('Extraction request exceeds its bound.', 'too_large', 413) - raw = self.rfile.read(length) - observe_request_bytes(observer, self._observation, len(raw)) - body = agent_api.decode(raw) - arguments = agent_api.validate_selected(selected, self.command, self.path, body) - self._observe_dispatch(body) - try: - if action == 'status': value = transfer_controller.status() - elif action == 'preview': value = transfer_controller.preview(**arguments) - elif action == 'report_page': value = transfer_controller.report_page(**arguments) - elif action == 'stop': value = transfer_controller.stop(**arguments) - else: value = transfer_controller.extract(**arguments) - finally: - self._handoff_stopped_source() - return self.reply(value) - except (workbench.WorkbenchError, ProjectStoreError, agent_api.AgentAPIError, access.AccessError) as error: - result = {'error': str(error), 'code': error.code} - if hasattr(error, 'receipt'): - result['receipt'] = error.receipt - return self.reply(result, error.status) - except (CommitOutcomeUnknown, psycopg.Error): - return self.reply({'error': 'Extraction outcome requires explicit inspection.', 'code': 'storage'}, 503) - except OSError: - return self.reply({'error': 'Extraction storage outcome requires explicit status inspection; retained staging was not removed.', - 'code': 'storage'}, 503) - def _observe_dispatch(self, body=None): observe_selection(observer, getattr(self, '_observation', None), self._observation_operation, body, self._observation_version) @@ -416,12 +250,7 @@ def reply(self, data, status=200, content_type='application/json', headers=()): self._write_observed((data,), status) def project_error(self, error): - value = {'error': str(error), 'code': error.code} - # Only the typed project boundary can attach a non-secret durable - # receipt. Selected output validation checks its closed schema. - if getattr(dataset, 'project_files_mode', False) and hasattr(error, 'receipt'): - value['receipt'] = error.receipt - return self.reply(value, error.status) + return self.reply({'error': str(error), 'code': error.code}, error.status) def reply_stream(self, stream, metadata): # The owner has already verified a private spool before HTTP success. @@ -658,10 +487,6 @@ def _handle_POST(self): if path.startswith('/api/access/credentials/') and path.endswith('/revoke'): self._access_body() return self.reply(dataset.access.revoke(path.split('/')[-2])) - if (getattr(dataset, 'project_files_mode', False) and - not path.startswith('/api/workspace/project-files/')): - return self.reply({'error': 'This domain is unavailable until its canonical project publication is implemented.', - 'code': 'unavailable'}, 409) if path.startswith('/api/access/execution-grants/') and path.endswith('/revoke'): projects.closed(self._access_body(), ()) return self.reply(dataset.access.revoke_execution(path.split('/')[-2])) @@ -693,31 +518,7 @@ def _get(self): if path == '/api/agent/operations': return self.reply(agent_api.discovery()) if path == '/api/agent/capabilities': - capabilities = (dataset.capabilities() if getattr(dataset, 'project_files_mode', False) - else agent_api.capabilities(dataset.db.dataset_id)) - if not getattr(dataset, 'project_files_mode', False): - for operation in capabilities['operations']: - if operation['id'].startswith('project_files.'): - operation['availability'] = 'unavailable' - if operation['id'].startswith('project_transfer.'): - operation['availability'] = ('available' if transfer_controller is not None - else 'unavailable') - return self.reply(capabilities) - if path == '/api/workspace/context' and getattr(dataset, 'project_files_mode', False): - # Bootstrap identifies the installation that owns this - # credential, without constructing a legacy domain owner. - return self.reply({'version': 1, 'mode': 'real', 'dataset_id': dataset.db.dataset_id, - 'project_files': True}) - if path == '/api/workspace/project-files' or path.startswith('/api/workspace/project-files/'): - if not getattr(dataset, 'project_files_mode', False): - raise workbench.WorkbenchError('Start explicit project-file mode to use this capability.', 'unavailable', 409) - from project_workspace import http_arguments - name, arguments = http_arguments('GET', self.path) - return self.reply(dataset.dispatch(name, arguments, - selected_version=self._contract_selection[1] if self._contract_selection else None)) - if getattr(dataset, 'project_files_mode', False) and path.startswith('/api/'): - raise workbench.WorkbenchError('This domain is unavailable until its canonical project publication is implemented.', - 'unavailable', 409) + return self.reply(agent_api.capabilities(dataset.db.dataset_id)) if (path == '/api/workspace/projects' or path.startswith('/api/workspace/projects/') or path == '/api/workspace/project-snapshots' or path.startswith('/api/workspace/project-snapshots/')): self.project_access() @@ -933,12 +734,6 @@ def _get(self): assets = {'/native-detection-import.js': ('native_detection_import.js', 'text/javascript'), '/saved-searches.js': ('saved-searches.js', 'text/javascript'), '/sequence-batch.js': ('sequence-batch.js', 'text/javascript'), '/pumas-typed.js': ('pumas-typed.js', 'text/javascript'), '/pumas-gateways.js': ('pumas-gateways.js', 'text/javascript'), '/meshes.js': ('meshes.js', 'text/javascript'), '/sequences.js': ('sequences.js', 'text/javascript'), '/text-classification-proposals.js': ('text-classification-proposals.js', 'text/javascript'), '/caption-proposals.js': ('caption-proposals.js', 'text/javascript'), '/curation.js': ('curation.js', 'text/javascript'), '/caption-import.js': ('caption_import.js', 'text/javascript'), '/bulk-import.js': ('bulk_import.js', 'text/javascript'), '/saved-selections.js': ('saved-selections.js', 'text/javascript'), '/workbench': ('workbench.html', 'text/html'), '/workbench.js': ('workbench.js', 'text/javascript'), '/workbench.css': ('workbench.css', 'text/css'), '/': ('index.html', 'text/html'), '/app.js': ('app.js', 'text/javascript'), '/style.css': ('style.css', 'text/css'), '/rights-note.js': ('rights-note.js', 'text/javascript'), '/preferences.js': ('preferences.js', 'text/javascript'), '/instruction-responses.js': ('instruction-responses.js', 'text/javascript'), '/native-text-import.js': ('native_text_import.js', 'text/javascript')} # Opt-in workspace shell keeps fixture and real service boundaries distinct. assets.update({ - '/project-files': ('project-files.html', 'text/html'), - '/project-files.js': ('project-files.js', 'text/javascript'), - '/project-files.css': ('project-files.css', 'text/css'), - '/project-transfer': ('project-transfer.html', 'text/html'), - '/project-transfer.js': ('project-transfer.js', 'text/javascript'), - '/project-transfer.css': ('project-transfer.css', 'text/css'), '/auth.js': ('auth.js', 'text/javascript'), '/auth.css': ('auth.css', 'text/css'), '/workspace-project-activity.js': ('workspace-project-activity.js', 'text/javascript'), @@ -957,10 +752,6 @@ def _get(self): '/workspaces.css': ('workspaces.css', 'text/css'), '/workspaces.js': ('workspaces.js', 'text/javascript'), '/experiment-graph.js': ('experiment-graph.js', 'text/javascript'), - '/project-progression.js': ('project-progression.js', 'text/javascript'), - '/project-model-portfolio.js': ('project-model-portfolio.js', 'text/javascript'), - '/project-measurements.js': ('project-measurements.js', 'text/javascript'), - '/project-measurements.css': ('project-measurements.css', 'text/css'), '/experiment-lineage.js': ('experiment-lineage.js', 'text/javascript'), '/experiment-lineage.css': ('experiment-lineage.css', 'text/css'), '/workspace-real.js': ('workspace-real.js', 'text/javascript'), @@ -970,7 +761,6 @@ def _get(self): '/static/retained-analysis.js': ('retained-analysis.js', 'text/javascript'), '/static/retained-chart.js': ('retained-chart.js', 'text/javascript'), '/static/retained-checkpoint-curve.vl.json': ('retained-checkpoint-curve.vl.json', 'application/json'), - '/static/retained-measurement-maxima.vl.json': ('retained-measurement-maxima.vl.json', 'application/json'), '/static/vendor/retained-analysis/vega.min.js': ('vendor/retained-analysis/vega.min.js', 'text/javascript'), '/static/vendor/retained-analysis/vega-lite.min.js': ('vendor/retained-analysis/vega-lite.min.js', 'text/javascript'), '/static/vendor/retained-analysis/vega-embed.min.js': ('vendor/retained-analysis/vega-embed.min.js', 'text/javascript'), @@ -982,8 +772,6 @@ def _get(self): '/workspaces-data.js': ('workspaces-data.js', 'text/javascript'), '/workspaces-data.css': ('workspaces-data.css', 'text/css'), }) - if getattr(dataset, 'project_files_mode', False) and path in ('/', '/workspaces', '/workbench'): - path = '/project-files' assets.update({'/project-workspace': ('project-workspace.html', 'text/html'), '/project-workspace/base.css': ('project-workspace/base.css', 'text/css'), '/project-workspace/adapter.js': ('project-workspace/adapter.js', 'text/javascript'), @@ -1016,8 +804,6 @@ def _get(self): return self.reply({'error': str(error), 'code': error.code}, error.status) except workbench.WorkbenchError as error: return self.project_error(error) - except ProjectStoreError as error: - return self.project_error(error) except (ValueError, OSError) as error: return self.reply({'error': str(error)}, 400) @@ -1040,8 +826,6 @@ def _post(self): limit = spatial_assets.MAX_REQUEST if path.startswith('/api/workspace/'): limit = 256 * 1024 - if path == '/api/workspace/project-files' or path.startswith('/api/workspace/project-files/'): - limit = agent_api.REQUEST_LIMIT if not 0 < length <= limit: raise ValueError('Request is too large or empty.') raw_body = self.rfile.read(length) @@ -1051,22 +835,10 @@ def _post(self): # Strict JSON at the selected boundary, preserving ordinary HTTP semantics. body = agent_api.decode(raw_body) agent_api.validate_selected(self._contract_selection, self.command, self.path, body) - elif path == '/api/workspace/project-files' or path.startswith('/api/workspace/project-files/'): - body = agent_api.decode(raw_body) if not isinstance(body, dict): raise ValueError('Expected an object.') self._observe_dispatch(body) path = urlsplit(self.path).path - if path == '/api/workspace/project-files' or path.startswith('/api/workspace/project-files/'): - if not getattr(dataset, 'project_files_mode', False): - raise workbench.WorkbenchError('Start explicit project-file mode to use this capability.', 'unavailable', 409) - from project_workspace import http_arguments - name, body = http_arguments('POST', self.path, body) - return self.reply(dataset.dispatch(name, body, - selected_version=self._contract_selection[1] if self._contract_selection else None)) - if getattr(dataset, 'project_files_mode', False): - raise workbench.WorkbenchError('This domain is unavailable until its canonical project publication is implemented.', - 'unavailable', 409) if path.startswith('/api/workspace/'): parts = path.removeprefix('/api/workspace/').split('/') if parts == ['scientific-comparison']: @@ -1400,8 +1172,6 @@ def graph_guard(graph): return self.reply({'error': str(error), 'code': error.code}, error.status) except workbench.WorkbenchError as error: return self.project_error(error) - except ProjectStoreError as error: - return self.project_error(error) except Conflict as error: return self.reply({'error': str(error)}, 409) except FileNotFoundError: @@ -1419,14 +1189,6 @@ def main(): parser.add_argument('--port', type=int, default=8091) parser.add_argument('--project-root', action='append', default=[], metavar='ALIAS=PATH', help='Allow read-only project inspection beneath a local directory; repeat for multiple roots.') - parser.add_argument('--project-files-root', action='append', default=[], metavar='ALIAS=PATH', - help='Use inert external text-project mode beneath explicit local roots; other domain writes are unavailable.') - parser.add_argument('--project-runtime-source', action='append', default=[], metavar='ALIAS=CONFIG_FILE', - help='Allow explicit offline CPU runtime capture from an operator-owned local configuration; never capture on Open.') - parser.add_argument('--project-transfer-control', type=Path, - help='Enable explicit stopped extraction from this existing legacy controller into a separate local authority host.') - parser.add_argument('--project-transfer-root', action='append', default=[], metavar='ALIAS=PATH', - help='Configure backup and destination roots for explicit legacy extraction; requires --project-transfer-control.') parser.add_argument('--project-folder', type=Path, metavar='PATH', help='Serve this definition-first project folder and nothing else.') args = parser.parse_args() @@ -1436,11 +1198,9 @@ def main(): if not separator or not location or alias in roots: parser.error('Each project root needs a unique ALIAS=PATH.') roots[alias] = location - transfer_controller = control_workspace = None try: if args.project_folder is not None: - if (roots or args.project_files_root or args.project_runtime_source or args.project_transfer_control - or args.project_transfer_root): + if roots: parser.error('--project-folder serves one folder; it cannot be combined with other project options.') from tuldok_project.host import ProjectHost, refusal from tuldok_project.store import ProjectError @@ -1450,47 +1210,12 @@ def main(): problems = ''.join(' ' + ' '.join(part for part in (item['path'], item['pointer']) if part) + ': ' + item['message'] + '\n' for item in refusal(error)[1].get('problems', [])[:10]) parser.exit(2, str(error) + '\n' + problems) - elif args.project_files_root: - if roots or args.project_transfer_control or args.project_transfer_root: - parser.error('Choose project-file mode or legacy snapshot inspection roots, not both.') - file_roots = {} - for binding in args.project_files_root: - alias, separator, location = binding.partition('=') - if not separator or not location or alias in file_roots: - parser.error('Each project-file root needs a unique ALIAS=PATH.') - file_roots[alias] = location - from project_workspace import ProjectWorkspace - runtime_sources = {} - from recipe_process import read_regular, decode - for binding in args.project_runtime_source: - alias, separator, location = binding.partition('=') - if not separator or not location or alias in runtime_sources: - parser.error('Each runtime source needs a unique ALIAS=CONFIG_FILE.') - runtime_sources[alias] = decode(read_regular(Path(location).expanduser(), 65536)) - dataset = ProjectWorkspace(args.data, file_roots, runtime_sources=runtime_sources) else: - if args.project_runtime_source: - parser.error('Project runtime sources require external project-file mode.') dataset = Dataset(args.data, project_roots=roots) - if args.project_transfer_control: - transfer_roots = {} - for binding in args.project_transfer_root: - alias, separator, location = binding.partition('=') - if not separator or not location or alias in transfer_roots: - parser.error('Each extraction root needs a unique ALIAS=PATH.') - transfer_roots[alias] = location - from project_workspace import ProjectWorkspace - from project_transfer_controller import ProjectTransferController - control_workspace = ProjectWorkspace(args.project_transfer_control, transfer_roots) - transfer_controller = ProjectTransferController(dataset, control_workspace) - control_workspace.transfer_controller = transfer_controller - elif args.project_transfer_root: - parser.error('Extraction roots require --project-transfer-control.') except (StorageError, workbench.WorkbenchError) as error: parser.exit(2, str(error) + "\n") observer = configured_interface(args, 'http') - server = ThreadingHTTPServer((args.host, args.port), make_handler(dataset, observer, - transfer_controller=transfer_controller)) + server = ThreadingHTTPServer((args.host, args.port), make_handler(dataset, observer)) print('Tuldok: http://' + args.host + ':' + str(server.server_port), flush=True) try: server.serve_forever() @@ -1498,19 +1223,14 @@ def main(): pass finally: server.server_close() - if transfer_controller is not None: - transfer_controller.close() - if control_workspace is not None: - control_workspace.close() dataset.close() if observer is not None: observe_close(observer) if __name__ == '__main__': - # Trusted controller capabilities use exact app-owned class identities. # Executing this file must not create a second imported app module with - # distinct Dataset/guard classes during the explicit extraction workflow. + # distinct classes when another module later imports app. import sys sys.modules['app'] = sys.modules[__name__] main() diff --git a/candidate_packages.py b/candidate_packages.py index 2c9413c5..74e0a4b7 100644 --- a/candidate_packages.py +++ b/candidate_packages.py @@ -1233,18 +1233,6 @@ def authorize_transitive_inputs(runs, run, *, seen=None): def authorize_material_inputs(runs,material,*,seen=None): """Reauthorize an exact retained input material without inventing a Run.""" from workbench import WorkbenchError - # Project producers remain inert observations. Resolve their exact input - # proof through the fixed history owner, never through Runs._load recovery - # rows or a general historical fallback on the live Run owner. - from project_history import ProjectHistory - if isinstance(runs,ProjectHistory): - return runs.authorize_material_inputs(material) - from project_execution import ProjectExecution - execution=getattr(runs,'project_execution',None) - if isinstance(execution,ProjectExecution): - if execution._runs is not runs or not isinstance(execution.projection.history,ProjectHistory): - raise WorkbenchError('Current project Run input owner differs.','unavailable',409) - return execution.projection.history.authorize_material_inputs(material) seen=set() if seen is None else seen for item in material['inputs'].values(): if item.get('kind') != 'run_artifact': diff --git a/docs/README.md b/docs/README.md index eb187806..7be1667a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -10,7 +10,6 @@ Start with the [root README](../README.md) for installation and the Data → Pip - [Agent operations and MCP](contracts/agent-operations.md) - [Optional MCP observations and privacy](contracts/mcp-observer.md) - [Project manifests and read-only inspection](contracts/projects.md) -- [External text project files and current milestone limits](contracts/project-files.md) - [Project command line](contracts/project-cli.md) - [Project folder format and checker](contracts/project-folder.md) diff --git a/docs/contracts/project-cli.md b/docs/contracts/project-cli.md index 4cb3d3f4..d788385b 100644 --- a/docs/contracts/project-cli.md +++ b/docs/contracts/project-cli.md @@ -1,10 +1,5 @@ # Project execution CLI -The separate `file-*` commands operate on the explicit external text-project -mode. See [project files](project-files.md) for its canonical authority, owner -selection, checkpoint binding and current milestone limits. Registration `open` -below keeps its existing meaning. - `project_cli.py` uses the existing authenticated agent operations. Saved graphs, execution grants, Run custody, progress, cancellation and artifacts keep their existing owners and remain visible in `/workspaces` → Current local catalog → diff --git a/docs/contracts/project-files.md b/docs/contracts/project-files.md deleted file mode 100644 index 387c9bc6..00000000 --- a/docs/contracts/project-files.md +++ /dev/null @@ -1,292 +0,0 @@ -# External project files - -The [external project plan](../plans/external-project-save-load/plan.md) owns current -milestone acceptance. This contract covers the external-directory format and -its finite owner operations. Execution/recovery, independent Save As and -extraction have separate acceptance evidence; an unavailable capability must -refuse before effects. An in-progress draft is not final feature acceptance. -The [authority decision](../decisions/external-project-authority.md) explains the -canonical boundary. - -Start an explicit project-file service with a separate installation control -directory and one or more existing trusted root directories: - -```sh -python app.py --data /private/tuldok-control \ - --project-files-root research=/home/me/research -``` - -Use the service's normal local owner bootstrap, then visit `/project-files`. -New creates a previously absent relative directory under a configured alias. -Open chooses an existing project directory. Root aliases and credentials stay -local. Historical snapshots may retain inert root identities or runtime path -strings as evidence; they never establish a current filesystem binding. Tokens, -token hashes and live credential records are excluded. This mode cannot be -combined with legacy `--project-root`. - -## Canonical format - -`.tuldok/project.json` has format `tuldok_project_v1`. It is the sole current -checkpoint: project UUID, display name, membership roots, sorted record inventory, -request receipts and a SHA256 checkpoint. Its digest covers canonical bytes of -the document with `checkpoint` omitted. The store supports only its declared -format and family; malformed and future versions fail before projection writes. -The canonical checkpoint index is limited to 64 MiB, separately from the -100,000-record, 40 MiB-per-record and 2 GiB-total-record limits. The aggregate -budget covers canonical record bytes, excluding artifact payloads; scientific -catalogs retain original runtime/file observations across many Runs. Commit -and cold Open enforce the same aggregate budget. Commit checks -the index size before staging immutable records. This format is unchanged; -older installations with the former 16 MiB index or 256 MiB aggregate limit cannot open larger -checkpoints and must be upgraded before consuming them. - -Verified stopped-source backups and ordinary catalog backups share identical -file contents only inside their fresh private backup tree, and only when byte -count, SHA256 and POSIX permission mode all match. The first copy has an -independent inode; no original source file is hard-linked into the backup. -Both source and copied content are verified before a duplicate link is made, -and the complete tree/hash/mode checks still run before backup publication. -The existing backup format remains a complete ordinary-file tree. Restore -copies every path into an independent file, preserving bytes and modes without -introducing writable aliases into the restored catalog. Backup trees are -immutable custody and must not be edited as working catalogs. - -Each inventory entry identifies a rooted immutable file -`.tuldok/records///.json`, its format, namespace, -byte count and SHA256. Original `workbench_text_v1` preserves original source, current -Workbench record, every annotation revision, non-secret audit facts and operation -receipts. New operation receipts use `project_operation_v2`, whose identity -includes the current project UUID. Old v1 receipts remain exact historical -facts; a fork cannot reactivate their request authority. Canonical JSON is -UTF-8, sorted keys, two-space indentation, LF ending, -finite bounded values, and no duplicate keys. The namespace equals the logical -project UUID. Historical domain catalog IDs, record identities and hash inputs -remain exact within those envelopes. No generic recursive ID rewriting is permitted. - -The finite additional families cover Workbench data/source/annotation/response/ -preference histories and tombstones; saved selections/searches; frozen releases -and exposures; model/graph/recipe revisions and immutable materials; project and -runtime snapshots; Study/Trial/Run/candidate/lineage facts; and four producer -history families. Owner decoders validate their complete reference closure. -Unknown families, future formats and unclassified authority-bearing fields fail -before reconstruction. Older text is not silently upgraded on Open. - -New stages and fsyncs a complete project in a sibling directory, then publishes -it with atomic no-replace rename. An edit publishes and fsyncs new immutable -records before atomic replacement of the checkpoint. Unreferenced staged records -are not current authority. A failure with uncertain checkpoint publication fences -further use until explicit recovery. No cleanup deletes published history. - -Save verifies/fsyncs the full selected closure and returns a durability barrier. -A no-op Save leaves canonical bytes unchanged. Close drains synchronous project -requests, performs the barrier, releases the projection and file lock, and rotates -the binding. Active or unknown local Run, producer, runtime-copy and package -writers block Close, replacement and fork. A drained thread alone does not prove -that an external provider has ceased. Open/New replacement -validates an incoming inert projection before releasing healthy current custody. - -The generated `.gitignore` excludes `/artifacts/`, `/.tuldok-local/`, `/.venv/`, -`/__pycache__/`, `/PGDATA/` and `/output/`. New does not initialize Git. Authored -records and the checkpoint are suitable for Git; database binaries, model weights, -caches and large generated data stay outside tracked content. Intrinsic -`project_artifact_v1` records contain SHA256 and byte count; domain edges classify -role, media type, unique/regenerable preservation and required operations. -Present bytes live at `artifacts/sha256/` or an explicitly supplied local -resolution. Git transports canonical text and manifests; an independent payload -transfer supplies untracked bytes. Missing payloads remain visible. Consumers -verify exact captured bytes before use; they never regenerate historical evidence. - -## Consumers and outcomes - -The shared operation registry owns `project_files.*` contracts and exact contract -hashes. Browser, SDK, CLI and MCP negotiate those contracts. Lifecycle selection -requires current owner authority. Scoped agents may inspect data and submit draft -annotations; human review still requires the owner. Every project action is bound -to an opaque workspace generation and its expected canonical checkpoint. - -Use `ProjectFilesOwnerClient` only for the narrow owner project-file operations. -Its explicit `timeout` configuration may be up to 7,200 seconds for large retained -projects; the default remains 120 seconds. The absolute request watchdog still -applies and a transport timeout never authorizes an automatic mutation retry. -Generic clients retain their 300-second maximum. This wait budget is not an -execution deadline or a cancellation request. - -Browser contract tables derive from the local `agent_api` registry. Regenerate -them with `python scripts/generate_project_files_contracts.py`; add `--check` -to verify that the installed v1 pins, all supported version pins and fixed -routes match that registry. Remote schemas remain opaque discovery data. -`ProjectFilesClient` wraps a negotiated client. CLI domain `file-*` commands take -`--arguments` JSON files; lifecycle commands use explicit flags and select -`--owner-project-files` with a -private owner configuration. Generic AgentClient remains agent-only. Keep request -keys across lost replies; the same key with changed input conflicts. Canonical -receipts survive SQL loss and return the originally committed domain result. -Current permissions and any stronger owner/disclosure requirement are checked -before replay. SQL failure after canonical publication returns a durable receipt -and fences the projection until explicit recovery. - -M2 domain operations return `{binding, project_id, checkpoint, value}`. Ordinary -list pages use offset/limit (default 40, maximum 40); heavy data-history pages -default to one and permit at most four. The original M1 text paging below stays -compatible. Historical Study metadata separates membership/reservation pages -from complete charge totals. Run summaries omit frozen source content. Exact -Run documents use digest-bound bounded byte segments, with current explicit -disclosure required before protected document bytes or evidence are read. -Imported disclosures remain historical observations and grant no current access. - -Explicit source registration captures the original manifest and establishes a -current installation-local rooted binding. Open restores no such binding. A -fresh explicit registration may renew a moved, unchanged manifest. Reference -inspection is bounded and reports observed SHA256 separately from a declared -expected digest. An unpinned reference is labeled unverified; a declared mismatch -is refused. Scientific import requires the selected exact observed bytes and the -existing scientific owner interprets them. Project scripts provide integrations; -opening or registering a manifest does not execute them. - -Owner-only artifact resolution selects an existing file relative to a configured -root. It verifies and durably copies the exact declared bytes. The receipt is a -past resolution observation; `artifact_status` reports current availability. -No network fetch, runtime installation, dependency activation or regeneration -is performed. For supported built-in graphs, explicit recipe preparation performs -a guarded current native probe before retaining the immutable material. Reading -retained native materials or historical evidence does not launch that probe. - -## Explicit execution and recovery - -Generic project scripts own domain integrations. Current external-script Run and -Study approval/admission use current local policy and grants. Admission and GO -intent are canonical before worker acknowledgement or GO. Measured terminal -evidence, spent budget and lineage remain project facts. Imported history supplies -no approval, admission epoch, cancellation right or resumable process. Producer -requests and candidate preparation follow the same intent-before-effects rule. - -For supported native graphs, the current owner explicitly calls -`project_files.native_preflight` with the saved graph ID and revision. A valid -result binds its validation token to that exact graph and measured runtime. -`native_submit` takes the graph ID, graph revision and token; admission rechecks -current inputs and authority before launching a native Run. `native_retry` -requires an actual current local Run and creates a new attempt. These actions -require current owner execute permission, the workspace binding, expected -checkpoint and a request key. `native_reconcile` instead selects an original -current local phase with the binding and expected checkpoint, requires current -owner cancel permission, and never sends GO. Its phase ID is available through -the current native-phase page of execution health v2; imported phases are history, -not current custody. - -Native execution uses the current operator's `TULDOK_TRAINING_PYTHON`, or the -service interpreter when unset. Its installed packages remain an operator trust -assumption; a runtime observation does not prove a complete dependency closure or -model quality. Open and ordinary inspection do not probe, install, train, resume -or activate a runtime. Retained validation, admission and phase facts do not grant -execution authority after a cold Open. - -An optional current operator binding selects runtime sources: - -```sh -python app.py --data /private/tuldok-control \ - --project-files-root research=/home/me/research \ - --project-runtime-source cpu=/private/cpu-runtime.json -``` - -The configuration uses the existing runtime-snapshot configuration schema. -`runtime_sources` lists aliases. Explicit Inspect measures that selected source; -Capture requires the exact inspected inventory and a stable request key, records -an intent, and copies bytes without launching them. Status distinguishes absent, -intent recorded, captured and abandoned. A cold Open has no configured alias or -cache merely because a historical descriptor contains a path. - -Recovery preserves the last acknowledged binding/checkpoint. Generic Run/producer -reconciliation requires exact original local custody and proof of drain. Runtime -retry and package reconciliation additionally require the exact original physical -writer journal and canonical intent; imported intent alone is insufficient. -Explicit abandonment records the owner reason with a separate key and retains -partial bytes and scientific facts. A completed package is reconciled rather than -silently rewritten. Recovery never sends GO or executes project code. - -The status endpoint is available before any project is open. It reports current -binding, local root aliases, project identity/checkpoint when selected, and -available actions. A stale binding or checkpoint is a conflict. Corrupt canonical -bytes cannot be blessed by Save. Missing unsupported families are never silently -omitted or auto-generated. - -Query returns summaries sorted by ID, with `limit` (1–100, default 40), exclusive -`after_id`, and `next_after_id`. Get returns the current full record and newest -history first, with `history_limit` (1–4, default 1), exclusive `before_revision`, -and `next_history_before_revision`. The same checkpoint binds all pages. Mutation -results include their committed revision and its first history page; replay never -mixes that historical result with newer revisions. The UI exposes explicit controls -to load more records and older history. - -Status may report `recovery_required`, its last acknowledged project identity, -and the selected root/directory to reopen. Explicit Open of the selected -directory is guarded by the current binding and last checkpoint. Ordinary -recovery validates canonical bytes, builds a fresh inert SQL projection and -rotates the binding. If original local custody remains, the named execution/file -recovery action must settle it first. That same-selection recovery preserves the -binding so its reply remains correlated with the caller. A failed recovery keeps the prior -custody and the recovery action available. A creation that committed but could not -be selected reports `selected:false` with the destination identity and request -receipt. Exact New retry reconciles that receipt without overwriting a different -existing destination. - -Errors distinguish invalid/unsupported format, stale selection, -writer contention, unavailable projection and unknown publication. A definite -canonical commit followed by projection failure returns its durable receipt. -Inspect/reconcile that receipt instead of minting another request key. Recovery -reopens the selected directory and reconstructs the projection without scripts. - -When changing Git revisions, close the project first. Open revalidates the complete -checkpoint; edits to canonical immutable files, unresolved conflict text and -inconsistent inventory fail. A changed checkout fences an already-open projection; -explicit reload reconstructs it without scripts. Git conflict resolution is manual. - -## Working files and independent Save As - -Adopt explicitly captures the exact UTF-8 bytes of a selected script or note, -including its history and measured hash. Merely editing a working file does not -replace an immutable scientific capture. Open never executes, repairs or restores -working files. Save As refuses an adopted file that is missing or changed until -its intended current bytes or an eligible note deletion are explicitly adopted. -A missing script remains protected: note-deletion adoption cannot remove its -captured script or make a missing script eligible for Save As. - -`project_files.file_adopt_deletion` is -`POST /api/workspace/project-files/files/adopt-deletion`. It requires current edit -permission and the usual `binding`, `expected_checkpoint` and `request_key`, plus -`path`, `expected_revision` and `expected_sha256`. The path must identify an -already adopted note that is safely absent. The revision and digest must match -its current positive captured revision; an existing file, changed canonical -revision/digest or unsafe path is refused. This action records absence; it never -deletes a filesystem entry. Inspection and Open never adopt a deletion. - -The first adopted deletion changes that note's document to `project_file_v2`. -All earlier positive revisions retain their exact original fields and text. A -closed deletion revision adds `deleted:true` and contains `revision`, -`sha256:null`, `bytes:0`, `text:null`, `adopted_at` and `actor_id`. This is distinct -from an empty positive file, whose text is `""` and whose SHA256 is the empty-byte -digest. `file_get` can select either revision; paged `file_history` returns -metadata, including the deletion marker, without embedding full texts. Current -inspection reports `deleted` only while that note remains safely absent, with -null expected/observed digests and zero expected bytes. - -Save As retains the complete note history and deletion marker and leaves its -current note path absent in the new destination. If a note is later recreated, -inspection reports its changed current bytes. Explicit `file_adopt` with the -tombstone's expected revision and the recreated file's measured SHA256 appends a -positive revision; it preserves the deletion and earlier text in history. Open -does not recreate the note or adopt its restoration. - -Save As publishes into a new absent directory, creates a new logical project and -editable identities, retains original hashed envelopes and records origin maps. -It copies required unique payloads and materializes captured working files only -into that new destination. Historical catalog IDs and material hashes remain -exact; unresolved bound drafts become explicit re-selection intents. Known -regenerable runtime binaries may remain missing with an explicit inventory; -missing unique evidence blocks a complete fork. Source bytes are unchanged. -Publication followed by selection failure reports `committed:true, selected:false`; -retry the exact request to select the already-published destination. - -The [extraction runbook](../runbooks/external-project-extraction.md) covers explicit -legacy selection, stopped backup, independent control credentials and the five -transfer operations. A whole-catalog backup is private recovery custody, not this -portable project format. diff --git a/docs/contracts/project-folder.md b/docs/contracts/project-folder.md index ed683dd2..38daf5ad 100644 --- a/docs/contracts/project-folder.md +++ b/docs/contracts/project-folder.md @@ -1762,10 +1762,8 @@ python app.py --data CATALOG --project-folder FOLDER `--data` names the catalog directory, which holds the credentials; the database is the one `TULDOK_DATABASE_URL` names. One app serves one folder and -nothing else: `--project-folder` cannot be combined with `--project-root`, -`--project-files-root`, `--project-runtime-source`, -`--project-transfer-control` or `--project-transfer-root`. A folder that -does not open stops start-up with the message and its first problems, exit +nothing else: `--project-folder` cannot be combined with `--project-root`. +A folder that does not open stops start-up with the message and its first problems, exit status 2. The app opens the project only for each operation, as the commands do, so files changed on disk are imported before an operation answers and the command line keeps working beside the app. diff --git a/docs/contracts/project-model-portfolio.md b/docs/contracts/project-model-portfolio.md deleted file mode 100644 index d7a0a991..00000000 --- a/docs/contracts/project-model-portfolio.md +++ /dev/null @@ -1,87 +0,0 @@ -# Authored model organization - -The project workspace can display an adopted `.portfolio.json` note as an -authored guide to model fits/components. This is separate from **Experiment -progression**, which retains genuine Study/Trial ancestry. Group edges mean -authored grouping; they do not establish derivation, admission or scientific -acceptance. Relationship notes have explicit comparison/parameter meanings and -source excerpts. Missing historical Trial ancestry stays unknown. - -## Retained document - -`project_model_portfolio_v1` is a UTF-8 JSON note of at most1MiB with exactly: - -- `format`: the fixed string above; `project_id`: the owning32hex project ID; -- `title` (1–200characters), `description` (1–8,000characters), and - `authorship`: `retrospective`; -- `groups`: at most64records with exact fields `id`, `label`, `parent`, - `description`. IDs are unique, parent is null or another group, and grouping - is acyclic; -- `models`:1–1,000records with exact fields `id`, `label`, `group_id`, `aliases`, - `review`, `card`, `summary`. Each unique ID names an authored model entry, - not necessarily a complete generator, Trial or unique parameter state; -- `relationships`: at most2,000records with exact fields `from`, `to`, `kind`, - `explanation`, `evidence_model`, `excerpt`. All model references exist, endpoints - differ, and each ordered endpoint/kind tuple is unique. - -Group/model IDs contain1–160ASCII letters/digits or `._:/-`, beginning with a -letter/digit. Group labels are at most200characters, model labels/aliases500. -Each model has at most128unique aliases. A card reference has exact fields -`file_id` (64hex), `path` (a relative `notes/` path up to512characters without -empty/dot/dot-dot components), positive integer `revision`, and64hex `sha256`. -These are exact captured note references, never source-reading capabilities. - -Review is `source_reviewed` or `review_pending`. Reviewed summaries have exactly -six nonempty strings, each up to16,384characters: `method`, `purpose`, -`experiment`, `outcome`, `lesson`, `reproduction`. Pending summaries are null. -This status is an author's source-review statement, not numerical qualification. -Relationship kind is `comparison` or `parameter_derivation`; the latter points -from derived model to parameter source and must be acyclic. Explanation is at -most8,000characters and exact excerpt at most16,384. Comparisons are authored -context, not permission to combine incompatible metrics/populations. - -## Ownership and reads - -The ordinary project-file owner captures/revises the note, authenticates reads, -verifies captured UTF-8 bytes/hashes and retains previous revisions. There is no -new canonical family, SQL table, execution grant, recipe or mutation interface. -Existing `files_inspect` and `file_get` contracts are unchanged. Save/load keeps -the original guide and referenced note history. A fork whose new project/note -identities differ requires an explicitly re-authored guide; the reader refuses -foreign identities instead of retargeting them silently. - -`ProjectModelPortfolioDocument` owns the presentation-document decoder and -cross-reference/literal checks. `ProjectModelPortfolio` owns selection, -presentation and its pending reads. Its injected `read` must be the host's -already negotiated, current-authority, byte-verified project-file reader. -The host owns transport/hash validation and context identity. The controller -checks the exact model card ID/path/revision/SHA/project, and that all six -summary strings and that card's relationship excerpts occur literally in its -captured text before displaying a selected summary. Text is inert; no markup, -scripts, parameter loading, scientific scoring or source execution occurs. - -Only explicit actions read notes/cards. Discovery visits40adopted files per -page; no hidden scan/retry/polling occurs. The guide holds at most1,000models, -shows20per graph window with their ancestor groups, and reports exact total, -reviewed and filtered counts. Group/name/alias/review filters, paging and -textual relationship controls select the same entries as graph buttons. -Paragraphs wrap; exact source text remains in a disclosure. - -The host's binding/project/checkpoint/credential/generation context owns every -read. A context change, permission loss or teardown aborts pending work, clears -old content and restores focus to the host status when needed. Late replies -cannot publish into another context. Errors show their declared diagnostic and -clear old detail instead of displaying a previous model as the new selection. -Unsupported format or foreign-project binding is `unsupported`; malformed -document/reference/summary is `invalid`; transport/availability failures retain -their owning diagnostic. No success or empty-data fallback substitutes for a -failed read. - -## Verification scope - -Pure codec tests cover contract decisions using literal fixtures. Controlled -read and real-browser tests cover selection, unavailable/obsolete responses, -repeated invocation, focus, keyboard activation and wrapping on desktop/mobile. -Those fixtures do not establish real project capture or save/load. Native -acceptance additionally requires an actual adopted guide, exact original cards, -current authority, real project reads and retained checkpoint/custody evidence. diff --git a/docs/contracts/scientific-fields.md b/docs/contracts/scientific-fields.md index cf31a01a..a0b61374 100644 --- a/docs/contracts/scientific-fields.md +++ b/docs/contracts/scientific-fields.md @@ -159,38 +159,6 @@ project import and slice inspection. Native producer observations and independen NumPy qualification are recorded separately; these tests are not physics, training, or model acceptance. -## Native external-project inspection - -`project_files.data_scientific/1` reads the same bounded numeric slice through -the native project session. It requires the current `binding`, canonical -`checkpoint`, `record_id` and exact `content_hash`; `frame`, `field`, `axis` and -`index` retain the existing inspector's selection grammar. ProjectData checks -current inspect authority, the project session and source identity before using -ScientificAssets. The scientific owner verifies retained artifact bytes and -metadata. Stale bindings/checkpoints, changed content, missing/corrupt artifacts -and revoked credentials refuse; no source-path or cached-array fallback runs. -The read changes no project records and grants no execution authority. - -The native project explorer mounts the same `ScientificFieldInspector` used by -the workbench. That module owns slice validation, numeric probing, display-only -grayscale rendering and cancellation. Each page supplies its authoritative -selection predicate and slice reader; the workbench separately owns its source -download and review-note editor. The native project reader uses negotiated -project operations rather than the legacy workbench URLs. Native project -annotation stays with its existing data-note owner. - -Changing the selected record, project/checkpoint or session clears the native -view and aborts pending reads. A superseded reply cannot repaint it. Page teardown -also aborts reads. Hidden or loading canvases do not display old pixels. Field -units, producer stage, original clock and grid coordinates remain explicit; -opening a scientific data record does not qualify its physical meaning or turn -an authored diagnostic into an accepted model result. - -`test_project_sources` covers exact content and cold projection reads without -the original source root. `test_project_files_m2_http` covers real selected -transport, stale/refused reads and artifact corruption. The existing -`browser_scientific_fields.cjs` exercises the shared module through the original -workbench with its browser sandbox enabled. Lab qualification additionally -inspects unchanged retained pressure fields through native project operations -and independent relocated cold Open. Scalar Run comparisons and Experiment -progression remain separately owned interfaces. +The existing `browser_scientific_fields.cjs` exercises the inspector module through +the workbench with its browser sandbox enabled. Scalar Run comparisons and +Experiment progression remain separately owned interfaces. diff --git a/docs/plans/definition-first-projects/spec-m8.md b/docs/plans/definition-first-projects/spec-m8.md index ad726754..410d124b 100644 --- a/docs/plans/definition-first-projects/spec-m8.md +++ b/docs/plans/definition-first-projects/spec-m8.md @@ -183,3 +183,39 @@ What the capability check lists, measured again when the work starts: ### 10.5 Landing On the owner's sign-off: their words and the date go into the capability check and the ledger; the old-mode app left running on port 8091 for comparison is stopped (its pages would be gone from under it); the side branch is brought onto `feat/definition-first-projects` without rewriting that branch's history. Nothing is pushed. + +### 10.6 As prepared + +Prepared 2026-11-12 on `chore/retire-old-project-mode`. This is what differs from 10.1 to 10.4 and what each check found. The logs are kept outside the repository, in the scratch directory `tuldok-retire-evidence`. + +**What differs from the text above.** + +- **`project_cli.py` stays; 37 modules go, not 38.** It is also catalog mode's command line for agents (`open`, `inspect`, `preflight`, `submit`, `status`, `download`, the publication and coordinator commands, `call`, the workflows); `mcp_observer.py` lists it as a runtime source and about twenty tests and qualification scripts that stay use it. It loses `--owner-project-files`, the `file-*` commands and `project-transfer`. +- **Twelve import statements, not eight,** tied the old code to catalog mode: seven in `app.py`, two in `candidate_packages.py`, three in `pipeline.py`. In `pipeline.py` both `preparation_owner` branches went (the function answered `None` in catalog mode), so `_prepare_builtin_recipe_material_current` is folded into `_prepare_builtin_recipe_material`; `native_admission_wall_seconds` and its two constants moved in and answer 990 seconds as before. +- **No shared shape needed a name of its own.** 10.2 says `graphs.create` is built from `project_files.graph_create`. It was the other way round: the old operations copied their input from `graphs.*`. +- **In catalog mode `/api/agent/capabilities` now returns the registry's answer as it is.** The code removed from `app.py` only switched the old operations between available and unavailable. +- **One test of the kept code changed,** against 10.2's "not touched". `tests/test_tuldok_project_http.py` pinned the digest of the whole catalog manifest (115 operations) and of the `project` profile (152), and 10.2 itself changes both. It now pins the catalog manifest of 110 operations, which is the earlier manifest with its five `project_transfer.*` entries taken out (compared entry by entry with the manifest saved before the change: none added, none changed, order kept), and a new test checks that the `project` profile is refused and that no `project_files.*` or `project_transfer.*` operation is published or known. +- **Two tests that stay lose a part.** `tests/test_agent_api.py` loses the one test of `ProjectFilesOwnerClient`'s own timeout; `tests/test_torch_runtime.py` loses one assertion that called `project_material.decode_runtime_material`. +- **Under `static/`** `retained-measurement-maxima.vl.json` goes with the page that loaded it. `workspace-project-activity.js` and `workspace-projects.js` stay: catalog mode's `workspaces.html` loads them. +- **`.github/workflows/tests.yml` loses 13 steps** (the training step of the native project, five steps of the agent environment, six Chromium steps and one Node step of the old mode). It parses, with 166 steps. It has not run on GitHub: nothing is pushed. +- **Step 4 of 10.3 is not met in full.** Outside `docs/plans/` these mentions remain: + - About thirty lines in `runs.py`, `synthetic.py`, `caption_proposals.py`, `grounded_candidates.py`, `text_classification_proposals.py`, `experiments.py`, `audio_assets.py`, `immutable_assets.py`, `scientific_fields.py` and `workbench.py` read an attribute of the catalog that only the deleted modules set (`project_execution`, `project_sources`, `project_asset`, `project_availability`, `project_study_execution`). Nothing reaches them now. They run through the code that starts and recovers runs, and 10.1 does not name those files, so they are left for a change of their own. + - The docstring of `tuldok_project/__init__.py` names the older modules. + - `project_files` is a dictionary key in four qualification scripts of the extension system, where it means the files of an extension's project. + - `docs/decisions/external-project-authority.md`, the decision record of the old mode, stays as a record. + +**What the checks found.** + +| Check | Result | +| --- | --- | +| Contracts | Pass. `catalog`: 115 operations before, 110 after; removed `project_transfer.extract`, `.preview`, `.report_page`, `.status`, `.stop` (each listed as unavailable before); none added, none changed, the rest of the manifest equal, order kept. `project_folder`: 43 before and after, identical. `project`: refused, "Unsupported capability profile". Of its 152 operations, the 145 `project_files.*` and 5 `project_transfer.*` are offered by no profile; `context.get` and `identity.get` remain. The discovery digest is unchanged | +| Python suite | Before: 3,149 tests, 40 not passing, 146 skipped, 92 minutes (two suites were running). After: 2,397 tests, 25 not passing, 122 skipped, 53 minutes. 3,149 less 751 tests of the deleted files less one removed test is 2,397; the tests that stay are the same set. No test is newly skipped (24 of the skips were in deleted files). One test that passed failed after: the pinned digest, above. With it changed and the new test added, the project suite and the agent tests were run again (below); the whole suite was not | +| The 23 that fail before and after | None from the change. No training environment on this machine (numpy, scikit-learn, `TULDOK_TRAINING_PYTHON`): `test_audio_training` (9), `test_one_fit_studies` (2), `test_text_training` (2), `test_runs.RealCPURunTests` (1), and `test_extension_canonical_release`, which cannot be imported. The test database's user may not create databases: one test each in `test_experiment_lineage`, `test_extension_http`, `test_extension_retention`, `test_integrated_retention_restore`, `test_run_publication_recovery`. "CPU snapshot contains unsafe or unlisted directories": `test_recipe_process.CpuSnapshotContractTests` (3). The other 17 failures of the baseline were in six deleted files | +| Project suite | 585 before. After, with the new test: 586 | +| JavaScript | `node --check`: 54 scripts under `static/`, none fails. All 49 remaining `tests/test_*.cjs` pass | +| Browser, workspace | `browser_project_workspace.cjs`, `browser_project_workspace_actions.cjs` and `browser_project_workspace_still.cjs` pass on the fixture; the first and the last pass on the lab folder, whose `git status` is empty before and after. `browser_project_workspace.cjs` failed once, while two whole suites ran beside it (a link of the Overview tab not yet drawn in the dark theme), and passed twice after | +| Browser, catalog | Of the 62 checks the workflow runs, 49 ran and 45 pass. `browser_saved_searches.cjs` passes every assertion and then fails removing its temporary directory, the same on the unchanged code. `browser_instruction_responses.cjs`, `browser_combined_workbench.cjs` and `browser_preferences.cjs` need packages the workflow installs. Not run, for want of training, a GPU, numpy or generated fixtures: `candidate_package`, `model_development`, `one_fit_model_evidence`, `retained_analysis_actual`, `scientific_fields`, `workspace_image_run`, `workspace_audio_run`, `workspace_mesh_run`, `workspace_sequence_run`, `workspace_export_run`, `workspace_project`, `workspace_spatial`, `workspace_text` | +| Start-up | `python app.py --help` shows none of the four flags; each is "unrecognized arguments", exit status 2, as are `mcp_stdio.py`'s two. Catalog mode on an empty data directory answers `/` ("Dataset studio"); `--project-folder` on a copy of `examples/tiny-project/project` in a Git repository of its own answers `/` ("Map · Tuldok"); `--project-folder` with `--project-root` is still refused | +| Size | 143 files deleted, 47,099 lines: 37 modules (20,437), 72 Python test files (20,732), 18 JavaScript tests and helpers (1,943), 11 files under `static/` (3,264), one script (35), four documents (688). 2,450 lines cut from the 17 other files that changed (65 added). The capability check had 38 modules (20,854 lines), 10 static files and 74 test files (21,791 lines): six of those 74 stay (five use `project_cli`, one lost an assertion), and four tests of the old mode that import none of the modules go | + +**Not verified.** The browser checks used Playwright's headless shell, not the Chrome the workflow installs. The catalog checks named above were not run. Nothing ran on GitHub. diff --git a/docs/runbooks/external-project-extraction.md b/docs/runbooks/external-project-extraction.md deleted file mode 100644 index 682a689b..00000000 --- a/docs/runbooks/external-project-extraction.md +++ /dev/null @@ -1,255 +0,0 @@ -# Extracting a legacy project into a portable directory - -This runbook describes the M5 extraction contract under implementation. It is -not an instruction to migrate a personal catalog before the extraction gate is -accepted. Work on a disposable representative fixture first. Do not inspect or -migrate a user's local lab as a product acceptance test. - -An extraction keeps the original stopped source and creates a new, independent -project. It is neither a database migration nor a generic SQL export. Historical -materials, Runs, Trials, source observations and their hashes retain their -original namespace. Editable copies receive destination identities through -their domain owners. No credentials, live grants, admissions, process control or -resumable operation authority enter the destination. - -## Preview first - -Preview uses a read-only, repeatable-read PostgreSQL view and pinned filesystem -capabilities. It does not construct `Metadata`, `Dataset`, Jobs or Runs; the -legacy `Metadata` constructor can append `.metadata-init.lock`, even with -`create=False`. Preview does not repair schema, enroll images, execute scripts, -install dependencies, contact producers, or regenerate missing bytes. - -Select one exact registered project snapshot and explicit roots from the finite -families: data records, responses, preferences, saved selections and searches, -graphs, recipe drafts, model definitions, Studies, Runs, producer histories and -working files. A registration snapshot identifies captured external files; it -does not establish ownership of otherwise global data, Studies or Runs. - -Review the report's required dependency closure, shared dependencies, unassigned -global records, ambiguities, missing payloads and unsupported source facts. -Parent/baseline lineage can require another Study as historical provenance. That -expansion is visible in the report and must not be presented as inferred -ownership. A required dependency cannot be excluded while claiming a complete -extraction. A saved search preserves entered criteria; its current search -results are not implicitly selected membership. - -The report binds the exact selection, source schema and snapshot, backup and -external inventory. Extraction requires the same report digest and selection. -An unresolved or incomplete report is not successful empty-project creation. - -When the selected content and unique payloads are available, Preview validates -the captured native domain composition while the source is still live. Domain -refusals appear before an owner has to stop the source to discover them. This -does not satisfy cessation: the independent `cessation_proof_unavailable` -blocker remains until the existing trusted owner completes Stop and capture. - -## Stop through the existing owner - -The explicit stop operation belongs to the currently opened legacy controller. -It first fences new requests and drains existing request handlers. It verifies -that this instance owns all five known runtime claims, drains the four producer -workers and standalone image requests, and asks the existing Run owner to prove -local worker and external custodian drainage. A peer's runtime ownership, -unconfirmed descendant cessation, failed drain, unknown outcome or lost lock -prevents a stopped-source capability from being issued. - -An old backup receipt, `quiesced=True`, a process ID, an idle activity message or -a stored terminal state is not this proof. A newly opened application without -the original live owners can still preview, but reports -`cessation_proof_unavailable` until a trusted owner performs stop and capture. - -The controller issues an opaque, local stopped-source lease only after confirmed -drainage, peer exclusion, read-only snapshot pinning, a verified backup and an -external payload inventory. The lease owns its connection and directory -capabilities. It cannot be reconstructed from JSON or imported project facts. - -Stopping can legitimately persist cancellations or interruptions through the -existing runtime owners. The source-unchanged baseline is recorded **after** -that explicit stop and verified backup. Extraction itself must preserve that -baseline exactly. - -## Preserve original evidence - -Verify required unique payload bytes, including native BYTEA bundles, original -images/audio/scientific sources, release ZIPs, execution inputs and outputs, -runtime manifests and captured scripts. Resolve files only through current -explicit capabilities; historical absolute paths are inert evidence. - -Missing original bytes cannot be replaced by running a producer, re-exporting a -release, recreating a manifest's formatting or remeasuring a result. Declared -regenerable dependencies retain visible availability. Missing required unique -bytes block a complete extraction. - -Legacy storage has genuine history gaps. Saved selections/searches retain only -their current row, and image source revisions are not a complete source event -stream. A report must identify absent historical revisions, timestamps or -bindings. It must not invent earlier names, source revisions, audit events or -complete-history claims. An observed-history representation requires explicit -domain support; otherwise extraction remains blocked for that case. - -## Publish and verify the destination - -Use a new destination under an authorized root. Source, stopped backup, -destination and task-owned staging must not overlap. Existing destinations are -not overwritten or merged. Stage validated domain records and immutable payloads -without writable hard links, then publish atomically through the project store. -Project-owned scripts and notes remain ordinary inert UTF-8 files; copying them -does not execute them. - -The extraction receipt binds the source, selection/report, request identity, -destination project/checkpoint, identity mappings, artifact completeness and -independent cold reconstruction. The deciding test opens the new project with a -fresh physical PostgreSQL projection and checks retained identities, hashes, -history, closure and source preservation. Current permissions come from the new -installation, never the imported source's access tables. - -## Use the process-local transfer controller - -The transfer controller takes the already running legacy Dataset and a separate, -inert control workspace. Configure publication root aliases for the verified -backup and destination; the destination alias must also be a root of the control -workspace. Root paths are pinned directory capabilities, and backup and project -names are single relative directory names. Symlink roots, publication roots -inside the source catalog, overlapping targets and existing backup targets are -refused before Stop. - -The five fixed controller actions are `project_transfer.status`, `preview`, -`report_page`, `stop` and `extract`. These are controller methods; the application -transport exposes only its corresponding validated routes. An ordinary Open or -preview cannot stop a source or create a stopped-source lease. - -1. Authenticate as the current legacy owner with administration permission. Read - Status and submit the explicit snapshot, root selection and decisions to - Preview with that process binding. Preview remains read only. Its summary - gives the report digest and counts; Report Page exposes one of `included`, - `required`, `unassigned`, `excluded`, `blockers`, `warnings`, `artifacts` or - `working_files` in pages of at most 40 items. Keep the same report digest while - reviewing pages. -2. Request Stop with the reviewed live report digest, backup root/directory and - proposed destination root/directory. Stop validates both target locations, - drains the actual source owner and creates the private verified backup. A - successful Stop rotates the process binding and clears the live report. -3. Sign in explicitly using credentials issued independently by the control - workspace. Source credentials are not copied, rebound or accepted as control - credentials. The stopped source's authentication database may already be - closed. Refresh Status and Preview the same explicit selection again; the - stopped-source report now binds the verified backup and cessation capability. -4. Extract using that exact stopped report digest, configured destination, - display name and a stable request key. Publication first produces a durable - independent project. The controller then attempts an ordinary inert Open in - the control workspace. Inspect the separate `selection.selected` result; - committed publication is preserved if workspace selection fails. - -The controller binding is an opaque process-local correlation value. Neither a -request nor a stored report contains the stopped-source capability. Restarting -the process does not reconstruct that capability from JSON. A failed stop after -the native source fence keeps the source fenced and exposes the failure through -independently authenticated control Status. If existing handlers have not yet -drained, the application delays its ordinary-route authentication handoff until -they finish. A native authorization denial before installation of that fence -leaves the source phase live and requires a refreshed report. - -The bounded public receipt gives publication identity, source/report/input -digests, copied/missing artifact counts and independent verification. Artifact -declarations remain available through report pages. Its checkpoint and -verification describe the **current verified destination head** on an exact-key -retry, including legitimate later destination edits. The source, selection, -report and input digests remain immutable birth facts; retry does not extract -again. A changed body with the same key conflicts. - -Keep the exact key after a lost publication acknowledgement. A typed unknown -outcome may already carry `committed: true` and `selected: false`; controller -Status retains that partial receipt. Retry reconciles the actual destination. -If publication failed before rename, preserve the reported staging directory for -inspection. Do not substitute a new key or assume the destination is absent. - -On retry, reconcile the exact request key and input digest before attempting -another publication. Keep a published destination. If publication is uncertain, -retain task-owned staging and receipts until its outcome is checked; do not -delete a destination to make a retry appear clean. Report the exact known or -uncertain outcome and preserve the original stopped source. - -## Current owner API - -These are internal owner interfaces. They do not add a public HTTP, SDK, MCP or -CLI capability until those consumers have been qualified against the same -selection, completeness and outcome contracts. - -```python -# Use the already opened legacy controller and its authenticated current actor. -# parent_fd is a caller-owned directory capability outside the source catalog. -from project_transfer import ProjectTransfer, preview_source - -selection = { - 'project_snapshot': {'id': registered_id, 'manifest_sha256': manifest_hash}, - 'roots': {'records': [chosen_record_id], 'studies': [chosen_study_id]}, - 'decisions': [], -} -with preview_source(existing_dataset) as view: - review = ProjectTransfer(view).preview(selection) -# This first report can inspect closure but cannot claim cessation proof. - -with existing_dataset.stop_for_project_extraction(parent_fd, 'stopped-backup') as source: - transfer = ProjectTransfer(source) - report = transfer.preview(selection) - # Review can_extract/blockers, required dependencies and unassigned inventory. - receipt = transfer.extract(selection, report['report_sha256'], parent_fd, - 'new-project', 'New independent project', - 'caller-owned-extraction-key') -``` - -The selection accepts only the finite root arrays `records`, `responses`, -`preferences`, `selections`, `searches`, `graphs`, `recipe_drafts`, -`model_definitions`, `studies`, `runs`, `releases`, `exposures`, `model_materials`, -`recipe_materials`, `runtime_materials`, `producer_jobs` and `working_files`. -Omitted arrays are empty. Producer roots identify one known kind and job ID; -working files identify `script`/`note` plus an exact `scripts/...`/`notes/...` -path. Explicit decisions identify a known family and exact canonical ID, an -include/exclude choice and the entered reason. They do not authorize omitting a -required dependency. - -The stopped backup is private legacy custody and includes the original access -rows. Portable domain records exclude those rows. The canonical extraction -manifest retains only non-secret source digests, the normalized selection, -actual first-adoption observations for selected working files, fixed-family -population counts and copied/missing-regenerable artifact identities. - -A successful receipt has `committed: true` and `selected: false`: publication -creates a project without changing the application's selection. A lost final -acknowledgement returns an `unknown` error carrying its known committed identity -when that identity can be proven. Inspect that destination and repeat the exact -key/input. Before publication, failure retains `staging_directory`; it does not -claim the destination exists. A missing unique payload, absent legacy history, -unknown cessation, unsupported schema or required exclusion stays a blocker. - -Current focused evidence uses disposable PostgreSQL 17 fixtures and private -filesystem roots. It covers ordinary cold Open under a different installation, -current scoped inspection and revocation, actual handler drainage, peer -exclusion, exact source/archive preservation, malformed or missing source facts, -required closure, failed publication and lost-reply reconciliation. Historical -fixture custody is not a claim that an imported process was executed again or -that an old scientific result was remeasured. - -The extraction-only closer has a bounded deadline. If an existing owner does not -finish closing, the controller returns `source_busy`, keeps new requests fenced -and issues no stopped-source lease. Its single owned closer may finish later; -that does not turn a timed-out request into a successful extraction or revive -ordinary requests. A closure failure or unconfirmed descendant remains unknown. -The ordinary application's `close()` semantics are unchanged. - -The focused owner gate is: - -```sh -# Run from the repository root with a disposable PostgreSQL fixture DSN only. -PYTHONPATH="tests:.:${PYTHONPATH:-}" python -m unittest test_project_transfer -v -``` - -The current owner checkpoint passed **20 tests in 17.495 seconds** on the private -PostgreSQL 17.11 fixture. The cross-Study case retains two Studies, two Trials, -parent and baseline lineage, a settled reservation, a candidate, native Run -artifacts, model and recipe materials, a frozen release and shared source bytes. -A separate ordinary Open uses a different current installation and fresh -physical SQL projection, while constructor tripwires verify that Jobs and Runs -do not start. The historical case establishes custody and reconstruction only; -current-host preflight and actual execution have their own gates. diff --git a/docs/runbooks/project-composition.md b/docs/runbooks/project-composition.md deleted file mode 100644 index 76757fd6..00000000 --- a/docs/runbooks/project-composition.md +++ /dev/null @@ -1,54 +0,0 @@ -# Compose retained projects - -The owner operation `project_files.compose` creates one independent project from -an open editable primary and one or more explicit retained project checkpoints. -It preserves the original scientific evidence and forks the primary editable -notes, data and definitions through the same owners as Save As. Secondary drafts -and operation receipts remain inert historical sources. No source project is -modified and no imported program, runtime or credential becomes active. - -Negotiate the operation's version-1 contract through the native project owner -client. The route is `POST /api/workspace/project-files/compose`. In addition to -the current `binding`, `expected_checkpoint` and one fresh `request_key`, supply: - -- `root`, `directory` and `name` for a new destination under a configured root; -- `sources`, an ordered list of additional selections, each containing `root`, - `directory`, `project_id` and `checkpoint`. - -The current project is implicitly the first source. At most 15 additional -sources are accepted by the HTTP contract. All source projects must be idle and -available for native exclusive store ownership. The primary's captured working -files must be clean. The destination cannot contain, lie inside or alias any -source, and existing unrelated destinations are never overwritten. - -Equal canonical envelopes share one retained representation. Same-ID conflicts -are rejected except for Run documents that differ only in their historical -approval grant/consumption while retaining the same admission and every other -field. The complete alternate document is retained as a native Run observation; -it does not become a second Run or create a disclosure. Both documents remain -subject to the history owner's proof and payload validation. - -The persisted `project_composition_v1` record binds the ordered source identities -and exact canonical envelope hashes to the destination's ordinary fork overlay. -A source membership explicitly identifies any alternate Run observation needed -to recover that source's document. Its decoder rejects missing, altered or -contradictory memberships. Subsequent ordinary forks preserve and archive this -provenance. Older software that does not support this family must reject the -project explicitly; records must not be dropped for compatibility. - -Payloads are verified and copied as independent ordinary files. A missing copy -can be supplied by another source with the same verified declaration; a corrupt -selected source is rejected. Unique bytes cannot be omitted. Only dependencies -classified as regenerable by their domain owners can remain explicitly missing. - -On success, `state` describes the newly selected project, `fork` reports the -primary origin and copy completeness, and `sources` lists every selected source -identity/checkpoint in order. The local owner installation retains its own -credentials. Existing Save As and lifecycle-state contracts are unchanged. - -Retain a request before dispatch. An interrupted publication can leave an inert -stage or a complete unselected destination. Inspect the original request and -owner state before reconciling with the same key and arguments. Native receipts -bind reconciliation to the complete ordered source set. A timeout does not -justify another request key or deleting a retained stage. Selection failure -returns a durable unselected receipt while preserving the current primary. diff --git a/mcp_stdio.py b/mcp_stdio.py index bef82f12..e342381d 100644 --- a/mcp_stdio.py +++ b/mcp_stdio.py @@ -236,12 +236,7 @@ async def call_tool(name, arguments): try: agent_api.validate_arguments(name, arguments, contract_version(name)) observe('dispatch', pending_observation) - # The explicit owner clients admit canonical operation IDs only; - # MCP names are transport aliases, validated by the fixed profile. - dispatch_name = (agent_api.operation(name)['operation_id'] - if isinstance(client, (agent_api.ProjectFilesOwnerClient, - agent_api.ProjectTransferOwnerClient)) else name) - envelope = await anyio.to_thread.run_sync(client.call, dispatch_name, arguments) + envelope = await anyio.to_thread.run_sync(client.call, name, arguments) pending_http_status = envelope.get('status') if isinstance(envelope, dict) else None agent_api.validate_output(name, envelope, contract_version(name)) pending_outcome = ('permission-refusal' if envelope['status'] in (401, 403) @@ -412,10 +407,6 @@ def main(argv=None): parser = argparse.ArgumentParser(description=__doc__) parser.add_argument('--config', required=True, help='Private SDK JSON configuration file') owner_profile = parser.add_mutually_exclusive_group() - owner_profile.add_argument('--project-files-owner', action='store_true', - help='Explicit current owner credential; expose only finite project-file operations') - owner_profile.add_argument('--project-transfer-owner', action='store_true', - help='Explicit current host owner; expose only the five project-transfer operations') owner_profile.add_argument('--project-folder-owner', action='store_true', help='Explicit owner of a served project folder; expose only the project folder operations') parser.add_argument('--observe-v2-database', help='Explicit operator opt-in to a fresh private v2 interface store') @@ -430,9 +421,7 @@ def main(argv=None): import mcp # noqa: F401 - explicit optional consumer boundary import jsonschema # noqa: F401 import agent_api - client_type = (agent_api.ProjectFilesOwnerClient if args.project_files_owner else - agent_api.ProjectTransferOwnerClient if args.project_transfer_owner else - agent_api.ProjectFolderOwnerClient if args.project_folder_owner else agent_api.AgentClient) + client_type = agent_api.ProjectFolderOwnerClient if args.project_folder_owner else agent_api.AgentClient client = client_type.from_config(args.config) client.bootstrap() if args.observe_database is not None or args.observe_v2_database is not None: diff --git a/native_process_bootstrap.py b/native_process_bootstrap.py deleted file mode 100644 index 56466b41..00000000 --- a/native_process_bootstrap.py +++ /dev/null @@ -1,115 +0,0 @@ -"""Closed native job launch, entered only behind the existing custodian GO. - -The custodian arms parent-death kill before exec. This module rechecks and -retains that exact parent before importing a captured native worker. It creates -new execution evidence; the original job template is never modified. -""" -import ctypes -import hashlib -import json -import os -from pathlib import Path -import signal -import stat -import sys - -WORKERS = frozenset(('image_training.py', 'text_training.py', 'audio_training.py')) -TEMPLATE_LIMIT = 64 * 1024 - - -def encoded(value): - return json.dumps(value, sort_keys=True, separators=(',', ':'), ensure_ascii=True, - allow_nan=False).encode('utf-8') - - -def pairs(items): - value = {} - for key, item in items: - if key in value: raise ValueError('Duplicate native template member.') - value[key] = item - return value - - -def read_regular(path): - descriptor = os.open(path, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK) - with os.fdopen(descriptor, 'rb') as source: - before = os.fstat(source.fileno()) - if (not stat.S_ISREG(before.st_mode) or before.st_nlink != 1 - or before.st_uid != os.getuid() or before.st_mode & 0o222 - or before.st_size > TEMPLATE_LIMIT): - raise ValueError('Native template is not an owned immutable file.') - raw = source.read(TEMPLATE_LIMIT + 1) - after = os.fstat(source.fileno()) - if (before.st_dev, before.st_ino, before.st_size, before.st_mtime_ns, before.st_ctime_ns) != ( - after.st_dev, after.st_ino, after.st_size, after.st_mtime_ns, after.st_ctime_ns): - raise ValueError('Native template changed.') - if len(raw) > TEMPLATE_LIMIT: raise ValueError('Native template exceeds its bound.') - return raw - - -def parent_identity(): - parent = os.getppid() - if parent <= 1: raise ValueError('Native custodian parent is unavailable.') - libc = ctypes.CDLL(None, use_errno=True) - if libc.prctl(1, signal.SIGKILL, 0, 0, 0): - raise ValueError('Native parent-death protection is unavailable.') - fields = Path('/proc/' + str(parent) + '/stat').read_text().rsplit(')', 1)[1].split() - value = dict(pid=parent, start_ticks=fields[19], - boot_id=Path('/proc/sys/kernel/random/boot_id').read_text().strip()) - if os.getppid() != parent: raise ValueError('Native custodian parent changed.') - return value - - -def write_once(directory, name, raw): - descriptor = os.open(name, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, - 0o400, dir_fd=directory) - with os.fdopen(descriptor, 'wb') as target: - target.write(raw); target.flush(); os.fsync(target.fileno()) - os.fsync(directory) - - -def main(argv=None): - arguments = sys.argv[1:] if argv is None else argv - if len(arguments) != 2 or arguments[0] not in ('train', 'verify'): - raise ValueError('Unsupported native launch phase.') - # The helper already armed this death signal before executing Python. - # Re-arm and observe it before runpy or any native worker import. - parent = parent_identity() - root = Path.cwd() - template = Path(arguments[1]) - if template != root / 'native-job-template.json': - raise ValueError('Native template path differs.') - raw = read_regular(template) - value = json.loads(raw, object_pairs_hook=pairs, - parse_constant=lambda _: (_ for _ in ()).throw(ValueError('Nonfinite native value.'))) - if (type(value) is not dict or set(value) != {'format', 'phase', 'worker', 'attempt_id', 'request_sha256', 'job'} - or value['format'] != 'native_parent_binding_v1' or value['phase'] != arguments[0] - or value['worker'] not in WORKERS or type(value['job']) is not dict - or type(value['job'].get('parent_pid')) is not int or value['job']['parent_pid'] != 1 - or encoded(value) != raw): - raise ValueError('Native job template differs from the closed contract.') - job = dict(value['job'], parent_pid=parent['pid']) - effective = encoded(job) - observation = encoded(dict(format='native_parent_observation_v1', attempt_id=value['attempt_id'], - request_sha256=value['request_sha256'], template_sha256=hashlib.sha256(raw).hexdigest(), - effective_job_sha256=hashlib.sha256(effective).hexdigest(), helper=parent)) - directory = os.open(root, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW) - try: - write_once(directory, 'effective-job.json', effective) - write_once(directory, 'native-parent-observation.json', observation) - finally: - os.close(directory) - worker = Path(__file__).resolve().parent / value['worker'] - sys.path.insert(0, str(worker.parent)) - sys.argv[:] = [str(worker), '--job' if value['phase'] == 'train' else '--verify-evidence', - str(root / 'effective-job.json')] - import runpy - runpy.run_path(str(worker), run_name='__main__') - - -if __name__ == '__main__': - try: - main() - except Exception: - print('Native launch binding failed.', file=sys.stderr, flush=True) - raise SystemExit(2) diff --git a/pipeline.py b/pipeline.py index d9c9894c..2a21bdd8 100644 --- a/pipeline.py +++ b/pipeline.py @@ -546,6 +546,23 @@ def decode_probe_observation(recipe,value,*,with_definition=False): return copy.deepcopy(value) +# Finite wall-clock allowance of each phase of a built-in recipe's native run. +NATIVE_PHASE_WALL_SECONDS = {'probe': 45, 'train': 600, 'verify': 90} +NATIVE_PARENT_DRAIN_ALLOWANCE = 5 + + +def native_admission_wall_seconds(): + """New material's finite probe/train/verifier and custody time allowance. + + This budgets child/custodian phases, not a storage availability guarantee. + Cleanup already includes the custodian's TERM grace interval. + """ + import recipe_process + overhead = (recipe_process.READY_SECONDS + recipe_process.GO_WAIT_SECONDS + recipe_process.CLEANUP_SECONDS + + NATIVE_PARENT_DRAIN_ALLOWANCE) + return sum(NATIVE_PHASE_WALL_SECONDS.values()) + len(NATIVE_PHASE_WALL_SECONDS) * overhead + + class Pipelines: def __init__(self, dataset): self.access = dataset.access @@ -937,10 +954,6 @@ def probe(self, recipe='image_classification'): # A native interpreter launch is execution even when its command only # reports runtime capability. Pure integrity recipes above never spawn. self.access.require('execute', 'pipeline.probe_native', recipe) - from project_native_preparation import preparation_owner - current=preparation_owner(self) - if current is not None: - return current.probe(self,recipe) worker_path = Path(adapter.__file__).resolve() executable = os.environ.get('TULDOK_TRAINING_PYTHON') or sys.executable try: @@ -1205,7 +1218,6 @@ def prepare_builtin_material(self, graph_id, revision, model_ref, *, reconcile_c capture_bytes=sum(map(len,payloads.values())) model_bytes=sum(item['blob']['bytes'] for item in model_body['source_closure'])+sum(model_body[key]['bytes'] for key in ('specification','preprocessing_policy','output_policy')) output_bytes=64*1024**2 - from project_native_execution import native_admission_wall_seconds envelope={'attempt_slots':1,'admitted_wall_seconds':native_admission_wall_seconds(),'retained_bytes':capture_bytes+model_bytes+output_bytes+256*1024, 'peak_staging_bytes':2*capture_bytes+model_bytes+2*output_bytes+256*1024} material={'format':'recipe_material_v1','catalog_id':self.db.dataset_id,'recipe_id':graph_id,'recipe_revision':revision, @@ -1227,12 +1239,6 @@ def prepare_builtin_material(self, graph_id, revision, model_ref, *, reconcile_c shutil.rmtree(staging,ignore_errors=True);raise def _prepare_builtin_recipe_material(self, value): - from project_native_preparation import preparation_owner - current=preparation_owner(self) - if current is not None:return current.current(self).capture_builtin(self,value) - return self._prepare_builtin_recipe_material_current(value) - - def _prepare_builtin_recipe_material_current(self, value): from model_definitions import read_owned_blob, retained_json material=value['material'];sha=value['ref']['sha256'] snapshot=retained_json(read_owned_blob(self.material_path,sha,material['recipe_document'],2*1024**2).decode(),2*1024**2) diff --git a/project_artifacts.py b/project_artifacts.py deleted file mode 100644 index fe2a0ee0..00000000 --- a/project_artifacts.py +++ /dev/null @@ -1,463 +0,0 @@ -"""Exact project payload custody, separate from domain role and retention policy. - -Declarations contain intrinsic byte identity only. Domain records own origin, -media type, unique/regenerable policy and permission. Publishing never deletes a -final payload on SQL rollback: unreferenced immutable bytes remain inert. Local -resolution capabilities never enter portable records, and no source is executed. -""" -from contextlib import contextmanager -import copy -import errno -import hashlib -import os -import re -import stat -import threading -import uuid - -from project_store import (ProjectStoreError, anchored_directory, DIR_FLAGS, FILE_FLAGS, - _directory, _physical, _relative_parts, _rename_noreplace, _walk) - -FORMAT = 'project_artifact_v1' -MAX_BYTES = 2 ** 63 - 1 -DEFAULT_READ_BYTES = 40 * 1024 * 1024 -CHUNK_BYTES = 1024 * 1024 - - -class ProjectArtifactError(ProjectStoreError): - pass - - -class _Missing(Exception): - pass - - -def _fail(message, code='invalid', status=400): - raise ProjectArtifactError(message, code, status) - - -def validate_declaration(value): - if type(value) is not dict: - _fail('Artifact declaration must be an object.') - if value.get('format') != FORMAT: - if type(value.get('format')) is str and re.fullmatch(r'project_artifact_v[1-9][0-9]*', value['format']): - _fail('Unsupported artifact declaration format.', 'unsupported', 422) - _fail('Invalid artifact declaration format.') - if set(value) != {'format', 'sha256', 'bytes'}: - _fail('Artifact declarations contain only format, SHA256 and byte count.') - digest, size = value['sha256'], value['bytes'] - if type(digest) is not str or len(digest) != 64 or any(c not in '0123456789abcdef' for c in digest): - _fail('Artifact requires a SHA256 digest.') - if type(size) is not int or not 0 <= size <= MAX_BYTES: - _fail('Artifact byte count must fit a nonnegative signed 64-bit integer.') - return dict(format=FORMAT, sha256=digest, bytes=size) - - -def _maximum(declaration, maximum_bytes): - if maximum_bytes is not None: - if type(maximum_bytes) is not int or not 0 <= maximum_bytes <= MAX_BYTES: - _fail('Artifact caller byte bound must be a nonnegative integer.') - if declaration['bytes'] > maximum_bytes: - _fail('Artifact exceeds the consuming operation byte bound.', 'too_large', 413) - - -def _info(fd, *, rooted=False): - info = os.fstat(fd) - # An explicit caller fd or our unlinked private snapshot can have no name. - # Rooted selected files must have exactly one name; aliases are never accepted. - if not stat.S_ISREG(info.st_mode) or info.st_nlink > 1 or (rooted and info.st_nlink != 1): - _fail('Artifact source must be an ordinary file without hard-link aliases.') - return info - - -def _identity(info): - return info.st_dev, info.st_ino, info.st_size, info.st_mtime_ns, info.st_ctime_ns - - -def _write(fd, raw): - view = memoryview(raw) - while view: - written = os.write(fd, view) - if not written: - raise OSError(errno.EIO, 'short artifact write') - view = view[written:] - - -def _observe(fd, declaration, *, output=None): - """Observe one bounded source and optionally capture the exact observed bytes.""" - before = _info(fd) - if before.st_size != declaration['bytes']: - return dict(state='corrupt', expected_sha256=declaration['sha256'], expected_bytes=declaration['bytes'], - observed_sha256=None, observed_bytes=before.st_size) - digest, count = hashlib.sha256(), 0 - while True: - raw = os.pread(fd, min(CHUNK_BYTES, declaration['bytes'] + 1 - count), count) - if not raw: - break - count += len(raw) - digest.update(raw) - if output is not None: - _write(output, raw) - if count > declaration['bytes']: - break - after = _info(fd) - if _identity(before) != _identity(after): - _fail('Artifact source changed during observation.', 'stale', 409) - observed = digest.hexdigest() - return dict(state='verified' if count == declaration['bytes'] and observed == declaration['sha256'] else 'corrupt', - expected_sha256=declaration['sha256'], expected_bytes=declaration['bytes'], - observed_sha256=observed, observed_bytes=count) - - -def _verified(observation): - if observation['state'] != 'verified': - failure = ProjectArtifactError('Artifact bytes disagree with their exact declaration.', 'invalid', 400) - failure.observation = observation - raise failure - - -def _io(error, *, published=False): - if published: - raise ProjectArtifactError('Artifact publication durability is unknown; retain bytes and retry the same identity.', - 'unknown', 503) from error - if error.errno in (errno.ELOOP, errno.ENOTDIR, errno.ENXIO): - raise ProjectArtifactError('Unsafe artifact filesystem object.') from error - if error.errno in (errno.EXDEV, errno.ENOSYS, errno.EOPNOTSUPP): - raise ProjectArtifactError('Required artifact filesystem mechanism is unsupported.', 'unsupported', 422) from error - raise ProjectArtifactError('Artifact bytes are unavailable.', 'unavailable', 503) from error - - -class ProjectArtifacts: - def __init__(self, store, *, resolutions=None): - """Bind optional explicit SHA -> {root_fd, root_path, relative} locations. - - Overrides choose one local source explicitly; a corrupt selected source - never silently falls back to another copy. The caller retains its fds; - this owner duplicates and releases only its own root capabilities. - """ - self.store = store - self._mutex = threading.RLock() - self._closed = False - self._resolutions = {} - try: - if resolutions is not None and type(resolutions) is not dict: - _fail('Artifact resolutions must be an explicit mapping.') - for digest, location in (resolutions or {}).items(): - validate_declaration(dict(format=FORMAT, sha256=digest, bytes=0)) - if type(location) is not dict or set(location) != {'root_fd', 'root_path', 'relative'}: - _fail('Invalid local artifact resolution fields.') - if type(location['root_fd']) is not int or location['root_fd'] < 0: - _fail('Local artifact resolution needs a directory capability.') - parts = _relative_parts(location['relative']) - with anchored_directory(location['root_fd'], root_path=location['root_path']): - owned = os.dup(location['root_fd']) - self._resolutions[digest] = dict(root_fd=owned, root_path=location['root_path'], parts=parts) - except OSError as error: - self.close() - _io(error) - except BaseException: - self.close() - raise - - def _ensure_open(self): - if self._closed: - _fail('Artifact owner is closed.', 'unavailable', 409) - - @contextmanager - def _source(self, root_fd, declaration): - override = self._resolutions.get(declaration['sha256']) - if override is None: - parts = ['artifacts', 'sha256', declaration['sha256']] - yield from self._source_at(root_fd, parts) - else: - with anchored_directory(override['root_fd'], root_path=override['root_path']) as external: - yield from self._source_at(external, override['parts']) - - def _source_at(self, root_fd, parts): - parent = source = None - try: - try: - parent = _walk(root_fd, parts[:-1]) - source = os.open(parts[-1], FILE_FLAGS, dir_fd=parent) - except FileNotFoundError as error: - raise _Missing() from error - _info(source, rooted=True) - yield source - # Path replacement cannot redirect a pinned fd, but it invalidates - # the selected source location and must not be called current. - current = _walk(root_fd, parts[:-1]) - try: - if _physical(current) != _physical(parent): - _fail('Artifact source directory changed.', 'stale', 409) - selected = os.stat(parts[-1], dir_fd=current, follow_symlinks=False) - if (selected.st_dev, selected.st_ino) != _physical(source): - _fail('Artifact source location changed.', 'stale', 409) - finally: - os.close(current) - finally: - if source is not None: - os.close(source) - if parent is not None: - os.close(parent) - - def inspect(self, declaration): - """Presence is unverified; it never claims a hash was checked.""" - declaration = validate_declaration(declaration) - with self._mutex: - self._ensure_open() - try: - with self.store.root_directory() as root: - return self._inspect_at(root, declaration) - except OSError as error: - _io(error) - - def _inspect_at(self, root, declaration): - try: - with self._source(root, declaration) as source: - observed = _info(source, rooted=True).st_size - state = 'unverified' - except _Missing: - observed, state = None, 'missing' - return dict(state=state, expected_sha256=declaration['sha256'], expected_bytes=declaration['bytes'], - observed_sha256=None, observed_bytes=observed) - - def inspect_many(self, declarations): - """Observe a finite owner-supplied page under one verified root scope. - - Each file still receives the same anchored ordinary-file checks as - inspect. Validate the canonical closure before AND after the group; - metadata corruption or a checkpoint change cannot produce a result. - Presence remains unverified and never claims a payload hash was read. - """ - if type(declarations) is not list: - _fail('Artifact inspection pages must be explicit finite lists.') - declarations = [validate_declaration(value) for value in declarations] - with self._mutex: - self._ensure_open() - try: - with self.store.root_directory(verify_after=True) as root: - result = [self._inspect_at(root, value) for value in declarations] - return result - except OSError as error: - _io(error) - - def status(self, declaration): - declaration = validate_declaration(declaration) - with self._mutex: - self._ensure_open() - try: - with self.store.root_directory() as root: - return self._status_at(root, declaration) - except OSError as error: - _io(error) - - def _status_at(self, root, declaration): - try: - with self._source(root, declaration) as source: - return _observe(source, declaration) - except _Missing: - return dict(state='missing', expected_sha256=declaration['sha256'], expected_bytes=declaration['bytes'], - observed_sha256=None, observed_bytes=None) - - def status_many(self, declarations): - """Hash each explicit artifact under one before/after-verified root. - - Unlike presence inspection, these observations verify present payload - hashes. An unchanged canonical closure is proved for the entire group; - every individual file retains its anchored source-location checks. - """ - if type(declarations) is not list: - _fail('Artifact status groups must be explicit finite lists.') - declarations = [validate_declaration(value) for value in declarations] - with self._mutex: - self._ensure_open() - try: - with self.store.root_directory(verify_after=True) as root: - result = [self._status_at(root, value) for value in declarations] - return result - except OSError as error: - _io(error) - - @contextmanager - def _payload_directory(self, root): - artifacts = payloads = None - try: - artifacts = _directory(root, 'artifacts', create=True) - payloads = _directory(artifacts, 'sha256', create=True) - yield artifacts, payloads - finally: - if payloads is not None: - os.close(payloads) - if artifacts is not None: - os.close(artifacts) - - def _publish(self, declaration, capture): - with self._mutex: - self._ensure_open() - published = False - try: - with self.store.root_directory() as root, self._payload_directory(root) as (artifacts, payloads): - temporary = '.artifact-' + uuid.uuid4().hex + '.tmp' - output = os.open(temporary, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW | os.O_CLOEXEC, - 0o600, dir_fd=payloads) - try: - capture(output) - os.fchmod(output, 0o400) - os.fsync(output) - finally: - os.close(output) - try: - _rename_noreplace(payloads, temporary, declaration['sha256']) - published = True - except FileExistsError: - existing = os.open(declaration['sha256'], FILE_FLAGS, dir_fd=payloads) - try: - _info(existing, rooted=True) - _verified(_observe(existing, declaration)) - os.fsync(existing) - finally: - os.close(existing) - os.unlink(temporary, dir_fd=payloads) - published = True - os.fsync(payloads) - os.fsync(artifacts) - os.fsync(root) - return copy.deepcopy(declaration) - except OSError as error: - _io(error, published=published) - # Failed staging remains inert. No callback owns deletion of final bytes. - - def publish_bytes(self, raw, declaration, *, maximum_bytes=None): - declaration = validate_declaration(declaration) - _maximum(declaration, maximum_bytes) - if type(raw) is not bytes: - _fail('Artifact publication requires exact bytes.') - if len(raw) != declaration['bytes'] or hashlib.sha256(raw).hexdigest() != declaration['sha256']: - _fail('Artifact input differs from its declaration.') - return self._publish(declaration, lambda output: _write(output, raw)) - - def publish_fd(self, source_fd, declaration, *, maximum_bytes=None): - declaration = validate_declaration(declaration) - _maximum(declaration, maximum_bytes) - if type(source_fd) is not int or source_fd < 0: - _fail('Artifact publication requires an explicit file capability.') - def capture(output): - _verified(_observe(source_fd, declaration, output=output)) - return self._publish(declaration, capture) - - def _snapshot(self, declaration): - snapshot = None - try: - with self.store.root_directory() as root: - snapshot = self._snapshot_at(root, declaration) - return snapshot - except BaseException: - if snapshot is not None: - os.close(snapshot) - raise - - def _snapshot_at(self, root, declaration): - snapshot = None - try: - local = staging = None - try: - with self._source(root, declaration) as source: - local = _directory(root, '.tuldok-local', create=True) - staging = _directory(local, 'artifact-snapshots', create=True) - temporary = '.snapshot-' + uuid.uuid4().hex + '.tmp' - output = os.open(temporary, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW | os.O_CLOEXEC, - 0o600, dir_fd=staging) - try: - _verified(_observe(source, declaration, output=output)) - os.fchmod(output, 0o400) - os.fsync(output) - finally: - os.close(output) - snapshot = os.open(temporary, FILE_FLAGS, dir_fd=staging) - _info(snapshot, rooted=True) - os.unlink(temporary, dir_fd=staging) - except _Missing as error: - raise ProjectArtifactError('Required artifact bytes are missing.', 'unavailable', 404) from error - finally: - if staging is not None: - os.close(staging) - if local is not None: - os.close(local) - return snapshot - except BaseException: - if snapshot is not None: - os.close(snapshot) - raise - - def copy_many_to(self, destination, declarations): - """Copy a finite inventory with one before/after-verified source root. - - Each payload uses its own verified unlinked snapshot and ordinary atomic - destination publication. Only one temporary payload is retained at once. - A later failure can leave earlier verified destination blobs inert; the - caller owns publication of the complete destination project. - """ - if not isinstance(destination, ProjectArtifacts) or destination is self: - _fail('Artifact copying requires a distinct destination owner.') - if type(declarations) is not list: - _fail('Artifact copy groups must be explicit finite lists.') - declarations = [validate_declaration(value) for value in declarations] - first, second = sorted((self, destination), key=id) - with first._mutex, second._mutex: - self._ensure_open() - destination._ensure_open() - try: - with self.store.root_directory(verify_after=True) as root: - for declaration in declarations: - snapshot = self._snapshot_at(root, declaration) - try: - destination.publish_fd(snapshot, declaration, maximum_bytes=declaration['bytes']) - finally: - os.close(snapshot) - except OSError as error: - _io(error) - - @contextmanager - def open_verified(self, declaration, *, maximum_bytes=None): - """Borrow a verified unlinked read-only snapshot, not a mutable source fd.""" - declaration = validate_declaration(declaration) - _maximum(declaration, maximum_bytes) - with self._mutex: - self._ensure_open() - try: - snapshot = self._snapshot(declaration) - except OSError as error: - _io(error) - # Release owner/project locks before consumer work. Source resolution - # roots can close while this independent byte snapshot remains borrowed. - try: - yield snapshot - finally: - os.close(snapshot) - - def read_blob(self, descriptor, *, maximum_bytes=DEFAULT_READ_BYTES): - if type(descriptor) is not dict or set(descriptor) != {'sha256', 'bytes'}: - _fail('Blob references contain exactly SHA256 and byte count.') - declaration = dict(format=FORMAT, **descriptor) - with self.open_verified(declaration, maximum_bytes=maximum_bytes) as source: - chunks = [] - while True: - raw = os.read(source, CHUNK_BYTES) - if not raw: - break - chunks.append(raw) - return b''.join(chunks) - - def close(self): - with self._mutex: - if not self._closed: - for location in self._resolutions.values(): - os.close(location['root_fd']) - self._resolutions.clear() - self._closed = True - - def __enter__(self): - return self - - def __exit__(self, *error): - self.close() diff --git a/project_cli.py b/project_cli.py index 1d54389b..5b8132d7 100644 --- a/project_cli.py +++ b/project_cli.py @@ -12,8 +12,8 @@ import signal import threading -from agent_api import (AgentAPIError, AgentClient, ProjectFilesOwnerClient, ProjectTransferOwnerClient, PublicationOwnerClient, CoordinatorOwnerClient, REQUEST_LIMIT, decode, - validate_arguments, verify_artifact, verify_publication_artifact, PROJECT_FILES_M2, PROJECT_FILES_M3, PROJECT_FILES_M4) +from agent_api import (AgentAPIError, AgentClient, PublicationOwnerClient, CoordinatorOwnerClient, REQUEST_LIMIT, decode, + validate_arguments, verify_artifact, verify_publication_artifact) from tuldok_client import WorkflowClient, download from mcp_observer import (add_interface_options, configured_interface, observe_begin, observe_stage, observe_selection, observe_close, outcome) @@ -51,48 +51,8 @@ def parser(): result = argparse.ArgumentParser(description=__doc__) result.add_argument('--config', type=Path, required=True, help='Private existing AgentClient endpoint/catalog/token-file configuration') - result.add_argument('--owner-project-files', action='store_true', - help='Use an existing owner credential, restricted to file-* commands') add_interface_options(result) commands = result.add_subparsers(dest='command', required=True) - commands.add_parser('file-status', help='Inspect the active external file project and process binding') - for action in ('new', 'open', 'save', 'close', 'save-as'): - command = commands.add_parser('file-' + action, help='Explicit external project ' + action) - command.add_argument('--binding', required=True) - command.add_argument('--expected-checkpoint', required=True, - help='Exact SHA256; use null only when no project is open for New/Open') - command.add_argument('--request-key', required=True) - if action in ('new', 'open', 'save-as'): - command.add_argument('--root', required=True) - command.add_argument('--directory', required=True) - if action in ('new','save-as'): - command.add_argument('--name', required=True) - for action in ('query', 'get', 'import-text', 'annotate'): - command = commands.add_parser('file-' + action, help='Checkpoint-bound project text ' + action) - command.add_argument('--arguments', type=Path, required=True, - help='Exact project_files operation JSON arguments including binding/checkpoint') - for operation in sorted((PROJECT_FILES_M2 | PROJECT_FILES_M3 | PROJECT_FILES_M4)-{'project_files.save_as'}): - action = operation.split('.')[1].replace('_', '-') - command = commands.add_parser('file-' + action, help='Checkpoint-bound project ' + action) - command.add_argument('--arguments', type=Path, required=True, - help='Exact selected project operation arguments') - transfer=commands.add_parser('project-transfer',help='Explicit owner extraction; Stop requires new current-host credentials') - actions=transfer.add_subparsers(dest='transfer_action',required=True) - actions.add_parser('status',help='Inspect current source/control phase and controller binding') - for action in ('preview','report-page','stop','extract'): - command=actions.add_parser(action,help='Explicit extraction '+action) - command.add_argument('--binding',required=True) - if action=='preview':command.add_argument('--selection',type=Path,required=True,help='Closed native ownership selection JSON file; no credentials or cessation proof') - else:command.add_argument('--report-sha256',required=True) - if action=='report-page': - command.add_argument('--section',required=True,choices=('included','required','unassigned','excluded','blockers','warnings','artifacts','working_files')) - command.add_argument('--offset',type=int,default=0);command.add_argument('--limit',type=int,default=40) - if action=='stop': - command.add_argument('--backup-root',required=True);command.add_argument('--backup-directory',required=True) - if action in ('stop','extract'): - command.add_argument('--destination-root',required=True);command.add_argument('--directory',required=True) - if action=='extract': - command.add_argument('--name',required=True);command.add_argument('--request-key',required=True) opening = commands.add_parser('open', help='Register/inspect a project without executing its code') opening.add_argument('--root', required=True) opening.add_argument('--manifest', required=True) @@ -291,13 +251,8 @@ def main(argv=None, *, observer=None): try: status, http_status = 200, None client_type = PublicationOwnerClient if args.command in ('recover-publication', 'cancel-publication') else AgentClient - if args.command=='project-transfer':client_type=ProjectTransferOwnerClient if args.command == 'recover-coordinator': client_type = CoordinatorOwnerClient - if args.owner_project_files: - if not args.command.startswith('file-'): - raise AgentAPIError('--owner-project-files is restricted to file-* commands.', 'configuration') - client_type = ProjectFilesOwnerClient client = client_type.from_config(args.config) if args.command in WORKFLOW_COMMANDS: result, success = workflow_command(client, args) @@ -316,30 +271,7 @@ def main(argv=None, *, observer=None): observe_stage(observer, observation, phase) result = download(client, run_id, args.name, args.expected_sha256, args.out, result_ref=ref) else: - if args.command=='project-transfer': - action=args.transfer_action.replace('-','_');operation='project_transfer.'+action;arguments={} - if action!='status':arguments['binding']=args.binding - if action=='preview':arguments['selection']=read_arguments(args.selection) - if action in ('report_page','stop','extract'):arguments['report_sha256']=args.report_sha256 - if action=='report_page':arguments.update(section=args.section,offset=args.offset,limit=args.limit) - if action=='stop':arguments.update(backup_root=args.backup_root,backup_directory=args.backup_directory) - if action in ('stop','extract'):arguments.update(destination_root=args.destination_root,directory=args.directory) - if action=='extract':arguments.update(name=args.name,request_key=args.request_key) - elif args.command == 'file-status': - operation, arguments = 'project_files.status', {} - elif args.command.startswith('file-'): - action = args.command[5:].replace('-', '_') - operation = 'project_files.' + action - if action in ('new', 'open', 'save', 'close', 'save_as'): - arguments = dict(binding=args.binding, request_key=args.request_key, - expected_checkpoint=None if args.expected_checkpoint == 'null' else args.expected_checkpoint) - if action in ('new', 'open', 'save_as'): - arguments.update(root=args.root, directory=args.directory) - if action in ('new','save_as'): - arguments['name'] = args.name - else: - arguments = read_arguments(args.arguments) - elif args.command == 'call': + if args.command == 'call': operation, arguments = args.operation, read_arguments(args.arguments) elif args.command == 'phase-timings': operation, arguments = 'runs.phase_timings', {'run_id': args.run_id} diff --git a/project_composition.py b/project_composition.py deleted file mode 100644 index ee667167..00000000 --- a/project_composition.py +++ /dev/null @@ -1,328 +0,0 @@ -"""Pure retained-source assembly for native independent project composition. - -Sources are ordered: the primary supplies the base envelope for an overlapping -identity. Exact duplicates share custody. Only admission-proof grant/consumption -variants of otherwise byte-identical Runs can coexist as native Run observations. -No source root, catalog permission, runtime or editable overlay is activated here. -The lifecycle owner must validate each source and the complete final candidate, -clone primary edits and publish all required bytes through the native owners. -""" -import contextvars -from contextlib import contextmanager -import hashlib - -from project_fork import ARCHIVE_FAMILIES, _sha, _uuid, decode_fork -from project_history import capture_run_observation -from project_store import (MAX_RECORDS, MAX_TOTAL_BYTES, ProjectStoreError, - _encode, _records) - - -class ProjectCompositionError(ProjectStoreError): - pass - - -def _fail(message, code='invalid', status=400): - raise ProjectCompositionError(message, code, status) - - -_KNOWN_ENVELOPES = contextvars.ContextVar('known_envelope_digests', default=None) - - -@contextmanager -def known_envelope_digests(known): - """Supply verified envelope digests for exact record objects during validation. - - known maps id(record) -> (record, digest) for envelopes whose document is the - stored canonical revision. Only that same object uses its digest; any other - envelope (for example a constructed observation variant) is encoded. - """ - token = _KNOWN_ENVELOPES.set(known) - try: - yield - finally: - _KNOWN_ENVELOPES.reset(token) - - -def _record_sha(record): - known = _KNOWN_ENVELOPES.get() - if known is not None: - entry = known.get(id(record)) - if entry is not None and entry[0] is record: - return entry[1] - return hashlib.sha256(_encode(record)).hexdigest() - - -def _approval_variant(original, alternate): - if original['family'] != 'run_history': - return False - left, right = original['document'], alternate['document'] - if _encode({k:v for k,v in left.items() if k != 'admission_proof'}) != _encode( - {k:v for k,v in right.items() if k != 'admission_proof'}): - return False - left, right = left.get('admission_proof'), right.get('admission_proof') - fields = {'grant', 'consumption', 'admission'} - return (type(left) is dict and type(right) is dict and set(left) == fields and set(right) == fields - and _encode(left['admission']) == _encode(right['admission'])) - - -def merge_retained_sources(snapshots): - """Return owned originals, exact source memberships and inactive dispositions. - - This internal construction step is not a publication or a fresh domain - admission boundary. Each source must already have passed its domain owners. - Store shape/size checks are retained here. Sources may be supplied lazily - to keep one temporary source snapshot in memory at a time. Same-ID conflicts outside the one - explicit Run-proof case are rejected; nothing is renamed or overwritten. - Membership digests cover complete canonical envelopes, not Python equality. - """ - try: - snapshots = iter(snapshots) - except TypeError: - _fail('Composition requires explicit complete source snapshots.') - projects, indexed, hashes, sizes = set(), {}, {}, {} - memberships, archived = [], set() - for snapshot in snapshots: - if type(snapshot) is not dict or set(snapshot) != {'project_id','name','checkpoint','records'}: - _fail('Composition requires complete canonical source snapshots.') - _uuid(snapshot['project_id']); _sha(snapshot['checkpoint']) - if snapshot['project_id'] in projects: - _fail('Composition source project identity repeats.', 'conflict', 409) - projects.add(snapshot['project_id']) - if type(snapshot['name']) is not str or not snapshot['name'].strip() or len(snapshot['name']) > 200: - _fail('Composition source name differs from the project contract.') - previous = decode_fork(snapshot['records'], project_id=snapshot['project_id']) - if previous is not None: - archived.update((item['family'], item['id']) for item in previous['archived']) - membership = dict(project_id=snapshot['project_id'], name=snapshot['name'], - checkpoint=snapshot['checkpoint'], records={}, run_observations={}) - if len(snapshot['records']) > MAX_RECORDS: - _fail('Composition source exceeds the project record budget.', 'too_large', 413) - source_bytes = 0 - for original in snapshot['records']: - # Validate/copy one envelope at a time. Holding another complete - # source-sized serialized/deep-copy list is unnecessary for custody. - family, identity, document, raw = _records([original])[0] - source_bytes += len(raw) - if source_bytes > MAX_TOTAL_BYTES: - _fail('Composition source exceeds the project byte budget.', 'too_large', 413) - record = dict(family=family, id=identity, document=document) - key = family, identity - sha = _record_sha(record) - membership['records'].setdefault(family, {})[identity] = sha - if family in ARCHIVE_FAMILIES: - archived.add(key) - if key not in indexed: - indexed[key], hashes[key], sizes[key] = record, sha, len(raw) - elif hashes[key] != sha: - if not _approval_variant(indexed[key], record): - _fail('Composition has conflicting retained envelopes: '+family+'/'+identity+'.', 'conflict', 409) - observation = capture_run_observation(document) - observation_key = observation['family'], observation['id'] - observation_sha = _record_sha(observation) - if observation_key in indexed and hashes[observation_key] != observation_sha: - _fail('Composition Run observation identity conflicts.', 'conflict', 409) - indexed[observation_key], hashes[observation_key] = observation, observation_sha - sizes[observation_key] = len(_records([observation])[0][3]) - membership['run_observations'][identity] = observation['id'] - memberships.append(membership) - del snapshot - if len(projects) < 2: - _fail('Composition requires at least two explicit complete source snapshots.') - if len(indexed) > MAX_RECORDS or sum(sizes.values()) > MAX_TOTAL_BYTES: - _fail('Composed retained sources exceed the project record budget.', 'too_large', 413) - return dict(records=[indexed[key] for key in sorted(indexed)], sources=memberships, - archived=[dict(family=family,id=identity) for family,identity in sorted(archived)]) - - -FAMILY = 'project_composition' -FORMAT = 'project_composition_v1' - - -def composition_input(sources, directory, name, request_key): - return dict(format='project_composition_request_v1', - sources=[dict(project_id=s['project_id'],checkpoint=s['checkpoint']) for s in sources], - directory=directory,name=name,request_key=request_key) - - -def _request_digest(sources, directory, name, request_key): - return hashlib.sha256(_encode(composition_input(sources,directory,name,request_key))).hexdigest() - - -def _shape(value, fields, label): - if type(value) is not dict or set(value) != set(fields): - _fail('Invalid composition '+label+' fields.') - - -def _decode_memberships(document, indexed): - from project_store import REQUEST_KEY, _identifier, _relative_parts - _shape(document,('format','destination_project_id','directory','name','request_key','request_sha256','sources'),'provenance') - if document['format'] != FORMAT: - _fail('Unsupported composition provenance format.','unsupported',422) - _uuid(document['destination_project_id']);_relative_parts(document['directory']) - if type(document['name']) is not str or not document['name'].strip() or len(document['name'])>200: - _fail('Invalid composition name.') - if type(document['request_key']) is not str or not REQUEST_KEY.fullmatch(document['request_key']): - _fail('Invalid composition request key.') - _sha(document['request_sha256']) - sources=document['sources'] - if type(sources) is not list or len(sources)<2: - _fail('Composition provenance needs at least two sources.') - seen=set() - for source in sources: - _shape(source,('project_id','name','checkpoint','records','run_observations'),'source membership') - _uuid(source['project_id']);_sha(source['checkpoint']) - if source['project_id'] in seen or source['project_id']==document['destination_project_id']: - _fail('Composition source identities repeat or alias the destination.') - seen.add(source['project_id']) - if type(source['name']) is not str or not source['name'].strip() or len(source['name'])>200: - _fail('Invalid composition source name.') - if type(source['records']) is not dict or type(source['run_observations']) is not dict: - _fail('Composition membership must use explicit inventories.') - runs=source['records'].get('run_history',{}) - if type(runs) is not dict:_fail('Composition Run membership must be an object.') - for identity,sha in source['run_observations'].items(): - _identifier(identity,'Composition original Run ID');_sha(sha) - if not set(source['run_observations'])<=set(runs): - _fail('Composition has an observation mapping without an original Run.') - for family,members in source['records'].items(): - _identifier(family,'Composition member family') - if type(members) is not dict or not members: - _fail('Composition family membership must be a nonempty object.') - for identity,sha in members.items(): - _identifier(identity,'Composition member ID');_sha(sha) - alternate=source['run_observations'].get(identity) if family=='run_history' else None - if alternate is None: - retained=indexed.get((family,identity)) - if retained is None:_fail('Composition source member is missing.','unavailable',409) - else: - from project_history import _observation_document - _sha(alternate) - wrapped=indexed.get(('run_observation',alternate)) - if wrapped is None:_fail('Composition source observation is missing.','unavailable',409) - observed=_observation_document(wrapped) - retained=dict(family='run_history',id=identity,document=observed['observation']) - base=indexed.get(('run_history',identity)) - if (base is None or not _approval_variant(base,retained) - or _record_sha(base)==_record_sha(retained)): - _fail('Composition alternate observation is not an admission-proof-only variant.') - if _record_sha(retained)!=sha: - _fail('Composition source membership differs from its exact retained envelope.') - if document['request_sha256']!=_request_digest(sources,document['directory'],document['name'],document['request_key']): - _fail('Composition request receipt differs from its exact sources.') - - -def decode_records(records, *, project_id=None): - """Validate inert source provenance and its independently owned fork binding.""" - from project_fork import _decode_document - indexed={(r['family'],r['id']):r for r in records} - if len(indexed)!=len(records):_fail('Composition record identity repeats.') - result={} - for record in records: - if record['family']!=FAMILY:continue - document=record['document'];_decode_memberships(document,indexed) - if record['id']!=document['destination_project_id']: - _fail('Composition envelope belongs to a different destination.') - fork=indexed.get(('project_fork',record['id'])) - if fork is None:_fail('Composition has no native fork overlay.','unavailable',409) - _decode_document(fork['document'],record['id'],indexed) - overlay=fork['document'];primary=document['sources'][0] - if (overlay['source']!={key:primary[key] for key in ('project_id','checkpoint')} - or any(overlay[key]!=document[key] for key in ('directory','name','request_key'))): - _fail('Composition provenance differs from its primary fork binding.') - archived={(r['family'],r['id']) for r in overlay['archived']} - required={(family,identity) for source in document['sources'] for family,members in source['records'].items() - for identity in members if family in ARCHIVE_FAMILIES} - if not required<=archived: - _fail('Composition must archive all source editable values and operation receipts.') - result[record['id']]=document - if project_id is not None: - current=decode_fork(records,project_id=project_id) - archived=set() if current is None else {(r['family'],r['id']) for r in current['archived']} - if any(identity!=project_id and (FAMILY,identity) not in archived for identity in result): - _fail('Prior composition provenance must remain explicitly archived.') - return result - - -def validate_source_memberships(records, snapshots, destination_project_id): - """Bind a constructed candidate to the actual owner-selected complete inputs.""" - document=next((r['document'] for r in records if r['family']==FAMILY and r['id']==destination_project_id),None) - if document is None:_fail('Composition candidate has no destination provenance.') - if len(document['sources'])!=len(snapshots):_fail('Composition candidate source count differs.') - for membership,snapshot in zip(document['sources'],snapshots): - if any(membership[key]!=snapshot[key] for key in ('project_id','name','checkpoint')): - _fail('Composition candidate belongs to different source identities.') - expected={} - for record in snapshot['records']: - expected.setdefault(record['family'],{})[record['id']]=_record_sha(record) - if membership['records']!=expected: - _fail('Composition candidate does not preserve the complete source membership.') - _decode_memberships(document,{(r['family'],r['id']):r for r in records}) - - -def build_candidate(snapshots, destination_project_id, *, created_at, id_factory, - directory, name, request_key): - """Preserve all sources and independently fork only the primary editable state.""" - import copy - from project_fork_composition import build_candidate as fork_candidate, artifact_plan - from project_fork import ID - merged=merge_retained_sources(snapshots) - _uuid(destination_project_id) - used={s['project_id'] for s in snapshots} - if destination_project_id in used:_fail('Composition destination must have a fresh identity.') - used.update(r['id'] for r in merged['records'] if ID.fullmatch(r['id'])) - used.update(r['document']['current']['id'] for r in merged['records'] - if r['family'] in ('model_definition','pipeline_graph','recipe_definition')) - used.add(destination_project_id) - def allocate(family,identity,revision): - value=id_factory(family,identity,revision);_uuid(value) - if value in used:_fail('Composition allocator reused a source or allocated identity.') - used.add(value);return value - fork=fork_candidate(snapshots[0],destination_project_id,created_at=created_at,id_factory=allocate) - indexed={(r['family'],r['id']):r for r in merged['records']} - for record in fork['records']: - key=record['family'],record['id'] - if key in indexed: - if _record_sha(indexed[key])!=_record_sha(record):_fail('Primary fork changed an original envelope.') - else:indexed[key]=record - document=dict(format=FORMAT,destination_project_id=destination_project_id,directory=directory,name=name, - request_key=request_key,request_sha256=_request_digest(merged['sources'],directory,name,request_key), - sources=merged['sources']) - record=dict(family=FAMILY,id=destination_project_id,document=document) - if (FAMILY,destination_project_id) in indexed:_fail('Composition provenance identity collides.') - indexed[(FAMILY,destination_project_id)]=record - records=[indexed[key] for key in sorted(indexed)] - validate_source_memberships(records,snapshots,destination_project_id) - archived={(r['family'],r['id']) for r in merged['archived']+fork['archived']} - # Every input has its own valid current fork. The combined records receive - # their one new current overlay only in the publication owner. Ask each - # source owner for its preservation policy before combining those roots; - # independent editable forks introduce no new payload identities. - plans={} - inventories=[fork['artifacts']] - inventories.extend(artifact_plan(source['records']) for source in snapshots[1:]) - for inventory in inventories: - for edge in inventory: - sha=edge['declaration']['sha256'];previous=plans.get(sha) - if previous is not None and previous['declaration']!=edge['declaration']: - _fail('Composition source artifact declarations conflict.') - if previous is None or edge['preservation']=='unique': - plans[sha]=copy.deepcopy(edge) - return dict(records=records,mapping=copy.deepcopy(fork['mapping']), - archived=[dict(family=f,id=i) for f,i in sorted(archived)], - artifacts=[plans[sha] for sha in sorted(plans)]) - - -def publish_composition(primary_store, primary_artifacts, retained_sources, trusted_root_fd, directory, - *, root_path, name, expected_checkpoint, request_key, quiescent, - created_at, id_factory, validate_candidate): - """Publish through the native fork lifecycle with explicit additional owners.""" - from functools import partial - from project_fork import _publish_project - if type(retained_sources) not in (list,tuple) or not retained_sources: - _fail('Composition requires at least one explicit secondary source owner.') - return _publish_project(primary_store,primary_artifacts,trusted_root_fd,directory, - root_path=root_path,name=name,expected_checkpoint=expected_checkpoint,request_key=request_key, - quiescent=quiescent,retained_sources=retained_sources, - build_candidate=partial(build_candidate,created_at=created_at,id_factory=id_factory, - directory=directory,name=name,request_key=request_key), - validate_candidate=validate_candidate) diff --git a/project_custody.py b/project_custody.py deleted file mode 100644 index 1a188f1d..00000000 --- a/project_custody.py +++ /dev/null @@ -1,511 +0,0 @@ -"""Private original-host custody index; never part of a portable project. - -Only fixed Run and producer facts are recorded. These files can fence a local -physical projection and identify its exact receipts; they never grant execution, -select a PID to signal, or restore a Run/admission from project history. -""" -import copy -import hashlib -import json -import os -from pathlib import Path -import re -import stat -import threading -import uuid -from run_capacity import MAX_ATTEMPTS - -NATIVE_PHASE_LIMIT=3*MAX_ATTEMPTS+1 - -import agent_api -from workbench import WorkbenchError - -LIMIT = 1024 * 1024 -ID = re.compile(r'^[a-f0-9]{32}$') -SHA = re.compile(r'^[a-f0-9]{64}$') -PRODUCERS = frozenset(('generation_history','grounded_history','caption_proposal_history','text_proposal_history')) -PHASES = ('admitted','launch_intent','launched','ready','go_intent','drained') -DIR_FLAGS = os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW | os.O_CLOEXEC -FILE_FLAGS = os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK | os.O_CLOEXEC - - -def _fail(message, code='local_custody_unavailable'): - raise WorkbenchError(message, code, 409) - - -def _id(value): - if type(value) is not str or not ID.fullmatch(value):_fail('Invalid local custody identity.') - return value - - -def _sha(value): - if type(value) is not str or not SHA.fullmatch(value):_fail('Invalid local custody digest.') - return value - - -def _shape(value, fields): - if type(value) is not dict or set(value) != set(fields):_fail('Unclassified local custody fields.') - - -def records_sha256(records): - return hashlib.sha256(agent_api.encoded(records)).hexdigest() - - -def validate(value): - version=value.get('format') if type(value) is dict else None - fields=('format','host_catalog_id','project_id','root_identity','projection_id', - 'project_name','selected_checkpoint','attempted','runs','producers','runtime_effects','package_effects') - _shape(value,(*fields,*(['native_phases'] if version in ('project_local_custody_v2','project_local_custody_v3') else []), - *(['native_admissions'] if version=='project_local_custody_v3' else []))) - if version not in ('project_local_custody_v1','project_local_custody_v2','project_local_custody_v3'):_fail('Unsupported local custody format.') - for key in ('host_catalog_id','project_id','projection_id'):_id(value[key]) - if type(value['project_name']) is not str or not value['project_name'].strip() or len(value['project_name'])>200: - _fail('Invalid retained local project name.') - root=value['root_identity'] - if type(root) is not list or len(root)!=2 or any(type(n) is not int or n<0 for n in root): - _fail('Invalid local project physical identity.') - _sha(value['selected_checkpoint']) - if value['attempted'] is not None: - attempt=value['attempted'];_shape(attempt,('records_sha256','request_key','input_sha256')) - _sha(attempt['records_sha256']);_sha(attempt['input_sha256']) - if type(attempt['request_key']) is not str or not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}',attempt['request_key']): - _fail('Invalid local canonical publication request.') - if type(value['runs']) is not list or len(value['runs'])>16:_fail('Too many unresolved local Runs.') - seen=set() - for run in value['runs']: - _shape(run,('run_id','admission_id','request_sha256','spec_sha256','phase','custody_identity','receipt_sha256')) - _id(run['run_id']);_id(run['admission_id']);_sha(run['request_sha256']);_sha(run['spec_sha256']) - if run['run_id'] in seen or run['phase'] not in PHASES:_fail('Invalid or duplicate local Run custody.') - seen.add(run['run_id']) - identity=run['custody_identity'] - if identity is not None: - _shape(identity,('attempt_id','request_sha256','spec_sha256','helper')) - from recipe_process import valid_identity - if (identity['attempt_id']!=run['run_id'] or identity['request_sha256']!=run['request_sha256'] - or identity['spec_sha256']!=run['spec_sha256'] or not valid_identity(identity['helper'])): - _fail('Local helper identity differs from its admitted specification.') - if run['phase'] in ('launched','ready','go_intent','drained') and identity is None: - _fail('Local launched Run requires its observed helper identity.') - if run['receipt_sha256'] is not None:_sha(run['receipt_sha256']) - if run['receipt_sha256'] is not None and run['phase']!='drained':_fail('Drain receipt precedes drainage.') - if type(value['producers']) is not list or len(value['producers'])>16:_fail('Too many unresolved local producers.') - seen=set() - for producer in value['producers']: - _shape(producer,('family','producer_id','admission_id','request_sha256','phase','provider_outcome','worker_drained')) - if producer['family'] not in PRODUCERS:_fail('Unsupported local producer custody family.') - for key in ('producer_id','admission_id'):_id(producer[key]) - _sha(producer['request_sha256']) - identity=producer['family'],producer['producer_id'] - if identity in seen or producer['phase'] not in ('admitted','effect_intent','unknown'): - _fail('Invalid or duplicate current producer custody.') - seen.add(identity) - if producer['provider_outcome'] not in ('not_admitted','unknown','result_received') or type(producer['worker_drained']) is not bool: - _fail('Invalid current producer outcome.') - for family,identity_field in (('runtime_effects','manifest_sha256'),('package_effects','material_sha256')): - entries=value[family] - if type(entries) is not list or len(entries)>8:_fail('Too many unresolved local file writers.') - seen=set() - for entry in entries: - _shape(entry,('request_key','input_sha256',identity_field)) - key=entry['request_key'] - if type(key) is not str or not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}',key) or key in seen: - _fail('Invalid local file writer request.') - seen.add(key) - for field in ('input_sha256',identity_field): - if entry[field] is not None:_sha(entry[field]) - native=value.get('native_phases',[]) - if type(native) is not list or len(native)>(NATIVE_PHASE_LIMIT if version=='project_local_custody_v3' else 16):_fail('Too many unresolved native phases.') - seen=set() - for phase in native: - _shape(phase,('phase_id','phase','run_id','request_sha256','spec_sha256','state','helper','receipt_sha256')) - _id(phase['phase_id']);_sha(phase['request_sha256']);_sha(phase['spec_sha256']) - if phase['phase_id'] in seen or phase['phase'] not in ('probe','train','verify'): - _fail('Invalid or duplicate native phase custody.') - seen.add(phase['phase_id']) - if phase['phase']!='probe' and phase['run_id'] is None:_fail('Native phase Run association differs.') - if phase['run_id'] is not None:_id(phase['run_id']) - if phase['state'] not in ('prepared','launch_intent','launched','ready','go_intent','completed','failed','unknown'): - _fail('Unclassified native custody state.') - from recipe_process import valid_identity - if phase['helper'] is not None and not valid_identity(phase['helper']):_fail('Invalid native helper observation.') - if phase['state'] in ('launched','ready','go_intent','completed') and phase['helper'] is None: - _fail('Native launched custody lacks its actual helper identity.') - if phase['receipt_sha256'] is not None: - _sha(phase['receipt_sha256']) - if phase['state'] not in ('completed','failed') or phase['helper'] is None: - _fail('Native terminal receipt lacks exact helper drainage.') - if phase['state']=='completed' and phase['receipt_sha256'] is None:_fail('Native completion requires drainage proof.') - admissions=value.get('native_admissions',[]) - if type(admissions) is not list or len(admissions)>16:_fail('Too many unresolved native admissions.') - seen=set() - for admission in admissions: - _shape(admission,('run_id','admission_id','request_sha256','graph_sha256','release_sha256','runtime_sha256','phase_started')) - for key in ('run_id','admission_id'):_id(admission[key]) - for key in ('request_sha256','graph_sha256','release_sha256','runtime_sha256'):_sha(admission[key]) - if admission['run_id'] in seen or type(admission['phase_started']) is not bool: - _fail('Invalid or duplicate native admission custody.') - seen.add(admission['run_id']) - return copy.deepcopy(value) - - -def _read(directory, name): - try:descriptor=os.open(name,FILE_FLAGS,dir_fd=directory) - except FileNotFoundError:return None - except OSError:_fail('Local custody index is not an anchored ordinary file.') - try: - before=os.fstat(descriptor) - if (not stat.S_ISREG(before.st_mode) or before.st_uid!=os.getuid() or before.st_nlink!=1 - or before.st_mode & 0o077 or before.st_size>LIMIT):_fail('Unsafe local custody index file.') - chunks=[];size=0 - while size<=LIMIT: - chunk=os.read(descriptor,min(65536,LIMIT+1-size)) - if not chunk:break - chunks.append(chunk);size+=len(chunk) - raw=b''.join(chunks);after=os.fstat(descriptor) - if len(raw)>LIMIT or (before.st_dev,before.st_ino,before.st_size,before.st_mtime_ns,before.st_ctime_ns)!=( - after.st_dev,after.st_ino,after.st_size,after.st_mtime_ns,after.st_ctime_ns):_fail('Local custody changed while reading.') - def pairs(items): - result={} - for key,item in items: - if key in result:_fail('Duplicate local custody JSON field.') - result[key]=item - return result - return validate(json.loads(raw,object_pairs_hook=pairs)) - except (OSError,UnicodeError,ValueError,RecursionError): - _fail('Local custody index cannot be read safely.') - finally:os.close(descriptor) - - -class ProjectCustody: - """Original host's private index, using only configured control directory.""" - def __init__(self, control_path, host_catalog_id): - self.path=Path(control_path);self.host_catalog_id=_id(host_catalog_id) - self.lock=threading.RLock() - - def _directory(self, create=False): - parent=os.open(self.path,DIR_FLAGS) - try: - if create: - try:os.mkdir('.project-custody',0o700,dir_fd=parent);os.fsync(parent) - except FileExistsError:pass - try:directory=os.open('.project-custody',DIR_FLAGS,dir_fd=parent) - except FileNotFoundError:return None - info=os.fstat(directory) - if not stat.S_ISDIR(info.st_mode) or info.st_uid!=os.getuid() or info.st_mode&0o077: - os.close(directory);_fail('Unsafe original-host custody directory.') - return directory - finally:os.close(parent) - - def _binding(self, store, projection_id): - snapshot=store.summary() - with store.root_directory() as descriptor: - info=os.fstat(descriptor) - return dict(host_catalog_id=self.host_catalog_id,project_id=snapshot['project_id'], - root_identity=[info.st_dev,info.st_ino],projection_id=_id(projection_id)) - - @staticmethod - def _name(binding): - return binding['host_catalog_id']+'.'+binding['project_id']+'.'+binding['projection_id']+'.json' - - def for_projection(self, store, projection_id): - return CustodyJournal(self,store,self._binding(store,projection_id)) - - def pending(self, store): - """Read only; no SQL owner, directory creation or worker recovery.""" - binding=self._binding(store,'0'*32);directory=self._directory() - if directory is None:return [] - result=[] - try: - names=os.listdir(directory) - if len(names)>10000:_fail('Original-host custody index requires explicit maintenance.') - # Local custody belongs to the physical root. A different valid - # project UUID at that same inode cannot erase an unresolved effect. - prefix=self.host_catalog_id+'.' - for name in sorted(names): - if not name.startswith(prefix):continue - if not re.fullmatch(r'[a-f0-9]{32}\.[a-f0-9]{32}\.[a-f0-9]{32}\.json',name): - _fail('Unclassified original-host custody index filename.') - value=_read(directory,name) - if value is None:continue - if self._name(value)!=name or value['host_catalog_id']!=self.host_catalog_id: - _fail('Local custody filename differs from its host binding.') - if value['root_identity']!=binding['root_identity']:continue - if value['runs'] or value['producers'] or value['runtime_effects'] or value['package_effects'] or value.get('native_phases') or value.get('native_admissions'): - result.append({key:copy.deepcopy(value[key]) for key in ('host_catalog_id','project_id','root_identity','projection_id')}) - return result - finally:os.close(directory) - - -class CustodyJournal: - def __init__(self, owner, store, binding): - self.owner,self.store,self.binding=owner,store,binding - self.name=owner._name(binding);self.lock=threading.RLock() - directory=owner._directory() - try:value=_read(directory,self.name) if directory is not None else None - finally: - if directory is not None:os.close(directory) - persisted=value is not None - if value is None: - value=dict(format='project_local_custody_v1',**binding, - project_name=store.summary()['name'],selected_checkpoint=store.summary()['checkpoint'], - attempted=None,runs=[],producers=[],runtime_effects=[],package_effects=[]) - if any(value[key]!=item for key,item in binding.items()):_fail('Original physical custody binding differs.') - self.value=validate(value) - self._persisted=persisted - - @property - def has_pending(self): - with self.lock:return bool(self.value['runs'] or self.value['producers'] or self.value['runtime_effects'] or self.value['package_effects'] or self.value.get('native_phases') or self.value.get('native_admissions')) - - def snapshot(self): - with self.lock:return copy.deepcopy(self.value) - - def refresh(self): - """Read this exact private binding after an uncertain journal ACK. - - This neither reads a canonical checkout nor clears an effect. The - execution owner separately proves selection and current authority. - """ - with self.owner.lock,self.lock: - directory=self.owner._directory() - try:current=_read(directory,self.name) if directory is not None else None - finally: - if directory is not None:os.close(directory) - if current is None: - if self._persisted:_fail('Original physical custody index is missing.') - return self.snapshot() - if any(current[key]!=value for key,value in self.binding.items()): - _fail('Original physical custody binding changed.') - self.value=current;self._persisted=True - return self.snapshot() - - def _write(self, value): - value=validate(value);raw=agent_api.encoded(value) - if len(raw)>LIMIT:_fail('Local custody exceeds its bounded format.') - directory=self.owner._directory(create=True);temporary='.custody-'+uuid.uuid4().hex - try: - descriptor=os.open(temporary,os.O_WRONLY|os.O_CREAT|os.O_EXCL|os.O_NOFOLLOW|os.O_CLOEXEC,0o600,dir_fd=directory) - try: - os.fchmod(descriptor,0o600);view=memoryview(raw) - while view: - count=os.write(descriptor,view) - if not count:raise OSError('Short local custody write') - view=view[count:] - os.fsync(descriptor) - finally:os.close(descriptor) - os.replace(temporary,self.name,src_dir_fd=directory,dst_dir_fd=directory);os.fsync(directory) - self.value=value - self._persisted=True - except OSError as error: - raise WorkbenchError('Local custody publication outcome is uncertain. Execution remains fenced.','outcome_unknown',409) from error - finally: - try:os.unlink(temporary,dir_fd=directory) - except OSError:pass - os.close(directory) - - def _change(self, change): - with self.owner.lock,self.lock: - directory=self.owner._directory() - try:current=_read(directory,self.name) if directory is not None else None - finally: - if directory is not None:os.close(directory) - if current is not None and current!=self.value or current is None and self._persisted: - _fail('Original-host custody changed; refuse to replace another writer.','outcome_unknown') - value=copy.deepcopy(self.value);change(value);self._write(value) - - def expect_publication(self, before, records, key, sha): - if not self.has_pending:return - def change(value): - value['selected_checkpoint']=before['checkpoint'] - value['attempted']=dict(records_sha256=records_sha256(records),request_key=key,input_sha256=sha) - self._change(change) - - def acknowledge(self, snapshot): - def change(value):value.update(selected_checkpoint=snapshot['checkpoint'],attempted=None) - self._change(change) - - def validate_selection(self, snapshot): - value=self.snapshot();attempt=value['attempted'] - if snapshot['project_id']!=value['project_id'] or snapshot['name']!=value['project_name']: - _fail('Current canonical project differs from local custody.') - if snapshot['checkpoint']==value['selected_checkpoint']:return - if (attempt is not None and records_sha256(snapshot['records'])==attempt['records_sha256'] - and self.store.reconcile(attempt['request_key'],attempt['input_sha256']) is not None):return - _fail('Canonical checkout differs from this original-host custody outcome.','stale_project') - - def observe_run(self, run, *, receipt_sha256=None): - from recipe_process import encoded - spec_sha=hashlib.sha256(encoded(run['spec'])).hexdigest() - def change(value): - old=next((item for item in value['runs'] if item['run_id']==run['id']),None) - immutable=dict(run_id=run['id'],admission_id=run['admission_id'],request_sha256=run['request_sha256'],spec_sha256=spec_sha) - if old is None: - old=dict(**immutable,phase='admitted',custody_identity=None,receipt_sha256=None);value['runs'].append(old) - if any(old[key]!=item for key,item in immutable.items()):_fail('Current Run differs from its local admission journal.') - phase={'prepared':'admitted','barrier_ready':'ready','go_intent':'go_intent','drained':'drained'}[run['custody_phase']] - if PHASES.index(phase)>PHASES.index(old['phase']):old['phase']=phase - identity=run.get('custody_identity') - if identity is not None: - if old['custody_identity'] is not None and old['custody_identity']!=identity:_fail('Current helper identity changed.') - old['custody_identity']=copy.deepcopy(identity) - if receipt_sha256 is not None:old['receipt_sha256']=receipt_sha256 - value['runs'].sort(key=lambda item:item['run_id']) - self._change(change) - - def launch_intent(self, run_id): - def change(value): - run=next((item for item in value['runs'] if item['run_id']==run_id),None) - if run is None or run['phase']!='admitted':_fail('Launch requires its acknowledged current admission.') - run['phase']='launch_intent' - self._change(change) - - def launched(self, run_id, helper): - from recipe_process import valid_identity - if not valid_identity(helper):_fail('Current spawned custodian identity is unavailable.') - def change(value): - run=next((item for item in value['runs'] if item['run_id']==run_id),None) - if run is None or run['phase']!='launch_intent':_fail('Custodian has no current launch intent.') - run['phase']='launched' - run['custody_identity']=dict(attempt_id=run_id,request_sha256=run['request_sha256'],spec_sha256=run['spec_sha256'],helper=copy.deepcopy(helper)) - self._change(change) - - def settle_run(self, run_id): - def change(value):value['runs']=[item for item in value['runs'] if item['run_id']!=run_id] - self._change(change) - - def observe_native_admission(self,run): - """Original physical admission intent; never a replay/GO capability.""" - from pipeline import digest - entry=dict(run_id=run['id'],admission_id=run['admission_id'],request_sha256=run['request_sha256'], - graph_sha256=run['graph_sha256'],release_sha256=run['release_sha256'],runtime_sha256=digest(run['runtime'])) - def change(value): - value['format']='project_local_custody_v3';value.setdefault('native_phases',[]) - rows=value.setdefault('native_admissions',[]) - old=next((item for item in rows if item['run_id']==run['id']),None) - if old is None:rows.append(dict(entry,phase_started=False)) - elif any(old[key]!=item for key,item in entry.items()):_fail('Native admission differs from its original physical intent.') - rows.sort(key=lambda row:row['run_id']) - self._change(change) - - def settle_native_admission(self,run_id): - def change(value): - if any(row['run_id']==run_id for row in value.get('native_phases',[])): - _fail('Native admission still has unresolved phase custody.') - value['native_admissions']=[row for row in value.get('native_admissions',[]) if row['run_id']!=run_id] - self._change(change) - - def native_prepared(self, phase): - """Fence one acknowledged, current native phase on this physical host.""" - from recipe_process import encoded - entry=dict(phase_id=phase['phase_id'],phase=phase['phase'],run_id=phase['run_id'], - request_sha256=phase['request_sha256'],spec_sha256=hashlib.sha256(encoded(phase['spec'])).hexdigest(), - state='prepared',helper=None,receipt_sha256=None) - def change(value): - if value['format']=='project_local_custody_v1':value['format']='project_local_custody_v2' - value.setdefault('native_phases',[]) - if entry['run_id'] is not None: - admission=next((row for row in value.get('native_admissions',[]) if row['run_id']==entry['run_id']),None) - if admission is None:_fail('A current native Run phase requires its original physical admission.') - admission['phase_started']=True - old=next((row for row in value['native_phases'] if row['phase_id']==entry['phase_id']),None) - if old is not None:_fail('A native phase cannot register another current launch.') - value['native_phases'].append(entry);value['native_phases'].sort(key=lambda row:row['phase_id']) - self._change(change) - - def native_launch_intent(self, phase_id): - def change(value): - row=next((row for row in value.get('native_phases',[]) if row['phase_id']==phase_id),None) - if row is None or row['state']!='prepared':_fail('Native launch requires its current acknowledged specification.') - row['state']='launch_intent' - self._change(change) - - def native_launched(self, phase_id, helper): - def change(value): - row=next((row for row in value.get('native_phases',[]) if row['phase_id']==phase_id),None) - if row is None or row['state']!='launch_intent':_fail('Native helper has no current launch intent.') - row.update(state='launched',helper=copy.deepcopy(helper)) - self._change(change) - - def native_observed(self, phase): - from recipe_process import encoded - def change(value): - row=next((row for row in value.get('native_phases',[]) if row['phase_id']==phase['phase_id']),None) - if row is None:_fail('Native observation has no original local phase.') - event=phase['events'][-1] - if (row['request_sha256']!=phase['request_sha256'] or row['phase']!=phase['phase'] - or row['run_id']!=phase['run_id'] or event['helper']!=row['helper'] - or row['spec_sha256']!=hashlib.sha256(encoded(phase['spec'])).hexdigest()): - _fail('Native observation differs from original local custody.') - transitions={'prepared':('failed',),'launch_intent':('failed',), - 'launched':('ready','failed','unknown'),'ready':('go_intent','failed','unknown'), - 'go_intent':('completed','failed','unknown')} - if event['state'] not in transitions.get(row['state'],()): - _fail('Native custody observation cannot skip or replay its acknowledged phase.') - row.update(state=event['state'],receipt_sha256=event['receipt_sha256']) - self._change(change) - - def native_confirmed(self, phase_id): - def change(value): - row=next((row for row in value.get('native_phases',[]) if row['phase_id']==phase_id),None) - if row is None or row['state'] not in ('completed','failed') or row['receipt_sha256'] is None: - _fail('Native phase cannot settle without acknowledged terminal drainage.') - value['native_phases']=[item for item in value['native_phases'] if item['phase_id']!=phase_id] - self._change(change) - - def native_not_launched(self,phase_id): - """Settle only the caller's proven never-entered launch boundary.""" - def change(value): - row=next((item for item in value.get('native_phases',[]) if item['phase_id']==phase_id),None) - if row is None or row['state']!='failed' or row['helper'] is not None or row['receipt_sha256'] is not None: - _fail('Never-launched native settlement requires its acknowledged failed non-process fact.') - value['native_phases']=[item for item in value['native_phases'] if item['phase_id']!=phase_id] - if row['run_id'] is not None and not any(item['run_id']==row['run_id'] for item in value['native_phases']): - admission=next((item for item in value.get('native_admissions',[]) if item['run_id']==row['run_id']),None) - if admission is not None:admission['phase_started']=False - self._change(change) - - def register_producer(self, family, producer_id, admission_id, request_digest): - def change(value): - item=dict(family=family,producer_id=producer_id,admission_id=admission_id,request_sha256=request_digest, - phase='admitted',provider_outcome='not_admitted',worker_drained=False) - previous=next((row for row in value['producers'] if (row['family'],row['producer_id'])==(family,producer_id)),None) - if previous is not None: - if any(previous[key]!=item[key] for key in ('family','producer_id','admission_id','request_sha256')):_fail('Producer admission changed.') - else:value['producers'].append(item) - self._change(change) - - def producer_effect_intent(self, family, producer_id): - def change(value): - item=next((row for row in value['producers'] if (row['family'],row['producer_id'])==(family,producer_id)),None) - if item is None:_fail('Provider request has no current admission journal.') - item.update(phase='effect_intent',provider_outcome='unknown',worker_drained=False) - self._change(change) - - def producer_outcome(self, family, producer_id, provider_outcome, worker_drained): - def change(value): - item=next((row for row in value['producers'] if (row['family'],row['producer_id'])==(family,producer_id)),None) - if item is None:_fail('Provider result has no current admission journal.') - item.update(provider_outcome=provider_outcome,worker_drained=worker_drained) - if provider_outcome=='unknown':item['phase']='unknown' - elif worker_drained:value['producers'].remove(item) - self._change(change) - - def runtime_started(self, key, input_sha256=None, manifest_sha256=None): - self._file_started('runtime_effects',dict(request_key=key,input_sha256=input_sha256,manifest_sha256=manifest_sha256)) - - def package_started(self, key, input_sha256=None, material_sha256=None): - self._file_started('package_effects',dict(request_key=key,input_sha256=input_sha256,material_sha256=material_sha256)) - - def _file_started(self, family, entry): - def change(value): - previous=next((item for item in value[family] if item['request_key']==entry['request_key']),None) - if previous is not None and previous!=entry:_fail('File writer key has different retained input.','conflict') - if previous is None:value[family].append(entry) - self._change(change) - - def runtime_confirmed(self, key):self._file_confirmed('runtime_effects',key) - def package_confirmed(self, key):self._file_confirmed('package_effects',key) - - def _file_confirmed(self, family, key): - def change(value):value[family]=[item for item in value[family] if item['request_key']!=key] - self._change(change) diff --git a/project_data.py b/project_data.py deleted file mode 100644 index 1b58eae6..00000000 --- a/project_data.py +++ /dev/null @@ -1,1466 +0,0 @@ -"""Workbench-owned project data and history, composed by ProjectSession. - -Each family below has a closed semantic decoder. SQL is a disposable projection; -the adapter supplies changed owned documents to the shared session, never a -replacement inventory or an independent commit. Existing domain owners admit -mutations and immutable artifact storage owns exact source bytes. -""" -import copy -from contextlib import contextmanager -from datetime import datetime -import hashlib -import json -import re -from types import SimpleNamespace -import unicodedata - -from workbench import (Workbench, WorkbenchError, IDENTIFIER, TASKS, REVIEWS, MAX_TEXT, - encode, encode_retained, strings, text_value, timestamp, validate_annotation) -from project_text import decode_records as decode_text_records, SNAPSHOT_FIELDS -from saved_searches import SavedSearches, criteria -from saved_selections import SavedSelections -from dataset_releases import Releases -from project_session import session_active, session_records, session_records_for - -FAMILIES = { - 'workbench_record': 'workbench_record_v1', - 'workbench_response': 'workbench_response_v1', - 'workbench_preference': 'workbench_preference_v1', - 'saved_selection': 'saved_selection_v1', - 'saved_search': 'saved_search_v1', - 'dataset_release': 'dataset_release_v1', - 'dataset_exposure': 'dataset_exposure_v1', -} -SHA = re.compile(r'^[a-f0-9]{64}$') -ASSET_KINDS = ('sequence', 'mesh', 'pointcloud', 'volume', 'audio', 'field_sequence') -SOURCE_FIELDS = set('id sha256 filename width height book_id session_id split created_at updated_at revision annotation'.split()) -RESPONSE_FIELDS = set('id prompt_id revision completion review provenance created_at updated_at'.split()) -JUDGMENT_FIELDS = set('id prompt_id parent_revision source_revision left_id left_revision right_id right_revision revision outcome rationale review deleted created_at updated_at provenance'.split()) - - -def fail(message, code='invalid', status=400): - raise WorkbenchError(message, code, status) - - -def closed(value, fields, name): - if type(value) is not dict or set(value) != set(fields): - fail('Invalid ' + name + ' fields.') - - -def identity(value, name='identity'): - if type(value) is not str or not IDENTIFIER.fullmatch(value): - fail('Invalid project data ' + name + '.') - return value - - -def sha(value): - if type(value) is not str or not SHA.fullmatch(value): - fail('Invalid project data digest.') - return value - - -def natural(value, minimum=1): - if type(value) is not int or not minimum <= value <= 2**53 - 1: - fail('Invalid project data revision/count.') - return value - - -def date(value): - text_value(value, 'Timestamp', 80) - try: - parsed = datetime.fromisoformat(value) - if parsed.utcoffset() is None: - raise ValueError() - return parsed - except (ValueError, TypeError): - fail('Invalid project data timestamp.') - - -def digest(value): - return hashlib.sha256(encode_retained(value).encode()).hexdigest() - - -def _audit(facts): - if type(facts) is not list: - fail('Data audit must be a list.') - for fact in facts: - closed(fact, {'action', 'target', 'details', 'result', 'actor_id', 'occurred_at'}, 'data audit') - if type(fact['action']) is not str or fact['action'] not in DATA_ACTIONS or fact['result'] != 'success' or type(fact['details']) is not dict: - fail('Invalid data audit action/result.') - identity(fact['actor_id'], 'historical actor') - if fact['target'] is not None: - text_value(fact['target'], 'Audit target', 128) - date(fact['occurred_at']) - # The current domain owners publish hashes/revisions, never credentials. - if set(fact['details']) & {'credential_id', 'token', 'admission_id', 'grant_id'}: - fail('Current access authority cannot enter data audit facts.') - - -def _events(events): - if type(events) is not list: - fail('Data events must be a list.') - for event in events: - closed(event, {'operation', 'request_key', 'record_revision', 'source_revision', 'deleted', 'occurred_at', 'snapshot'}, 'data event') - if type(event['operation']) is not str or event['operation'] not in DATA_OPERATIONS|RUNTIME_DATA_OPERATIONS or type(event['deleted']) is not bool: - fail('Invalid data lifecycle event.') - text_value(event['request_key'], 'Operation key', 128) - natural(event['record_revision']) - if event['source_revision'] is not None: - natural(event['source_revision']) - date(event['occurred_at']) - state=event['snapshot'];validate_record_snapshot(state) - if state['revision']!=event['record_revision'] or state['source_revision']!=event['source_revision']: - fail('Lifecycle event snapshot revision differs.') - - -def _edge(value, declarations, kind, role): - closed(value, {'artifact', 'media_type', 'kind', 'role', 'preservation', 'required_for'}, 'artifact edge') - closed(value['artifact'], {'namespace', 'sha256'}, 'artifact reference') - identity(value['artifact']['namespace'], 'artifact namespace') - sha(value['artifact']['sha256']) - if value['kind'] != kind or value['role'] != role or value['preservation'] not in ('unique', 'regenerable'): - fail('Artifact edge meaning differs from its data owner.') - text_value(value['media_type'], 'Media type', 120) - if value['required_for'] != ['inspect', 'release']: - fail('Unsupported data artifact required operations.') - declaration = declarations.get(value['artifact']['sha256']) - if declaration is None: - fail('Data artifact declaration is missing.') - return declaration - - -def _source_row(row, record_id): - closed(row, SOURCE_FIELDS, 'image source snapshot') - if row['id'] != record_id: - fail('Image source identity differs.') - sha(row['sha256']); natural(row['revision']) - natural(row['width']); natural(row['height']) - if row['width'] * row['height'] > 40_000_000: - fail('Image geometry exceeds owner limit.') - text_value(row['filename'], 'Filename', 200) - from image_sources import metadata, validate_annotation as validate_corners - if metadata(row) != {key: row[key] for key in ('book_id', 'session_id', 'split')}: - fail('Image source metadata is not canonical.') - if row['annotation'] is not None and validate_corners(row['annotation']) != row['annotation']: - fail('Image corner annotation is not canonical.') - if date(row['updated_at']) < date(row['created_at']): - fail('Image source update precedes creation.') - - -def _source_metadata(kind,value): - if kind=='sequence': - from sequence_assets import SequenceAssets - SequenceAssets.validate_project_metadata(value) - elif kind=='mesh': - from meshes import MeshAssets - MeshAssets.validate_project_metadata(value) - elif kind in ('pointcloud','volume'): - from spatial_assets import SpatialAssets - SpatialAssets.validate_project_metadata(kind,value) - elif kind=='audio': - from audio_assets import validate_project_metadata - validate_project_metadata(value) - else: - from scientific_fields import validate_project_metadata - validate_project_metadata(value) - - -def _acquisition(value,record,source,records): - """Only the finite receipts produced by the existing import owners.""" - if record['kind']=='sequence': - from sequence_assets import SequenceAssets - SequenceAssets.validate_project_acquisition(value,source['metadata']) - return - if type(value) is not dict:fail('Acquisition facts must be an object.') - from bulk_import import leaf_name, REQUEST_ID, MAX_ROWS - if type(value.get('request_id')) is not str or not REQUEST_ID.fullmatch(value['request_id']):fail('Invalid retained import request marker.') - format_name=value.get('format');declared=value.get('declared') - if format_name=='tuldok_assets_jsonl_v1': - closed(value,{'format','request_id','row_sha256','declared'},'JSONL acquisition') - fields={'manifest_name','row_number'}|({'image_file'} if record['kind']=='image' else set()) - closed(declared,fields,'JSONL source declaration');leaf_name(declared['manifest_name'],'Manifest name') - if record['kind']=='image':leaf_name(declared['image_file'],'Image filename') - if type(declared['row_number']) is not int or not 1<=declared['row_number']<=MAX_ROWS:fail('Invalid retained JSONL row number.') - sha(value['row_sha256']);return - if format_name=='image_caption_v1': - from caption_import import snapshot, SNAPSHOT_KEYS, RECORD_KEYS - closed(value,{'format','request_id','row_sha256','observed','declared'},'caption acquisition') - closed(value['observed'],{'manifest_sha256','metadata_sha256','asset_sha256','pixel_sha256'},'caption observed hashes') - closed(declared,{'manifest_name','metadata_path','row_number','image_file','origin_record','protected_component'},'caption declaration') - if declared['manifest_name']!='manifest.json' or declared['metadata_path'] not in ('train/metadata.jsonl','val/metadata.jsonl','test/metadata.jsonl'):fail('Invalid retained caption metadata location.') - upstream=declared['origin_record'];closed(upstream,RECORD_KEYS,'caption origin record') - members=declared['protected_component'] - if type(members) is not list or not 1<=len(members)<=30:fail('Invalid retained protected caption component.') - for member in members:snapshot(member) - if not any(member=={k:upstream[k] for k in SNAPSHOT_KEYS} for member in members):fail('Caption source is absent from its declared component.') - for digest_value in value['observed'].values():sha(digest_value) - elif format_name=='canonical_v1': - text_source=record['kind']=='text' - fields={'format','request_id','archive_sha256','manifest_sha256','row_sha256','asset_sha256','input_sha256','input_basis','declared'} - fields|={'metadata_sha256'} if text_source else {'coco_sha256','row_hash_basis','pixel_sha256','upstream_graph'} - closed(value,fields,'native acquisition') - closed(declared,{'archive_name','metadata_path','row_number','asset','upstream'},'native source declaration') - leaf_name(declared['archive_name'],'Archive filename') - closed(declared['upstream'],{'record','original_status'},'native upstream declaration') - if declared['upstream']['original_status']!='unavailable':fail('Native imported original status differs.') - upstream=declared['upstream']['record'] - from native_text_import import RECORD_KEYS - closed(upstream,RECORD_KEYS,'native origin record') - if text_source: - sha(value['metadata_sha256']) - if value['input_basis']!='consumed_exported_text' or declared['metadata_path'] not in ('train/records.jsonl','validation/records.jsonl','test/records.jsonl'):fail('Invalid retained native text input.') - else: - closed(value['coco_sha256'],{'train','validation','test'},'native COCO hashes') - for item in value['coco_sha256'].values():sha(item) - sha(value['pixel_sha256']) - if value['input_basis']!='consumed_exported_png' or value['row_hash_basis']!='canonical_parsed_manifest_record' or value['upstream_graph']!='selected_declared_links_only' or declared['metadata_path']!='manifest.json':fail('Invalid retained native image input.') - for field in ('archive_sha256','manifest_sha256','asset_sha256','input_sha256'):sha(value[field]) - else:fail('Unsupported retained acquisition format.','unsupported',409) - sha(value['row_sha256']) - if type(declared['row_number']) is not int or not 1<=declared['row_number']<=1000:fail('Invalid retained source row number.') - path=declared['image_file'] if format_name=='image_caption_v1' else declared['asset'] - if type(path) is not str or path!=upstream['asset'] or any(part in ('','.','..') for part in path.split('/')) or '\\' in path or path.startswith('/'):fail('Invalid retained source asset reference.') - captured={k:upstream[k] for k in SNAPSHOT_FIELDS} - _record(captured,identity(captured['id'])) - foreign_source=dict(kind=captured['kind'],original={'artifact':{'sha256':captured['source_sha256']}}) - origin=dict(captured['provenance']);origin.pop('rights_note_correction',None) - _origin(origin,captured,foreign_source,records) - - -def _origin(value,record,source,records): - kind=record['kind'] - method=value.get('method') - if method=='project_fork': - from project_data_fork import validate_origin - validate_origin(value,record,source,records) - return - if method in ('model_generated','model_grounded_rewrite'): - from project_producers import validate_record_origin - validate_record_origin(value,record,records) - return - if method=='procedural': - closed(value,{'method','recipe','recipe_version','seed','ordinal','factors','rights','verification'},'procedural origin') - from dataset_recipes import RECIPES - if value['recipe'] not in RECIPES or RECIPES[value['recipe']]['kind']!=kind or type(value['recipe_version']) is not int or value['recipe_version']!=1 or type(value['seed']) is not int or not 0<=value['seed']<=2**32-1 or type(value['ordinal']) is not int or not 0<=value['ordinal']<100 or type(value['factors']) is not dict: - fail('Invalid retained procedural origin.') - factors=value['factors'] - if kind=='image': - closed(factors,{'canvas','objects','occlusion'},'procedural image factors') - if factors['canvas']!=[128,96] or any(type(n) is not int for n in factors['canvas']) or type(factors['objects']) is not int or factors['objects']!=value['ordinal']%4 or type(factors['occlusion']) is not int or factors['occlusion']!=0:fail('Procedural image factors differ from the owned recipe.') - else: - from dataset_recipes import TEMPLATES - closed(factors,{'topic','day','hour','template'},'procedural text factors') - if factors['topic'] not in ('design review','project planning','reading group','demo','studio session') or factors['day'] not in ('Monday','Tuesday','Wednesday','Thursday','Friday') or type(factors['hour']) is not str or not re.fullmatch(r'(?:[89]|1[0-8]):(?:00|15|30|45)',factors['hour']) or type(factors['template']) is not int or factors['template']!=value['ordinal']%len(TEMPLATES):fail('Procedural text factors differ from the owned recipe.') - if value['verification']!='Targets derived from authored scene/template state; no human review or real-world quality claim.':fail('Procedural verification declaration differs.') - return - if kind=='text': - fields={'method','rights','normalization'} - if 'acquisition' in value:fields.add('acquisition') - closed(value,fields,'text origin') - if method!='import' or value['normalization']!='NFC; LF newlines':fail('Unsupported text origin.','unsupported',409) - elif kind=='image': - fields={'method','rights','source_sha256'} - if 'acquisition' in value:fields.add('acquisition') - closed(value,fields,'image origin') - if method!='import' or value['source_sha256']!=source['original']['artifact']['sha256']:fail('Image origin differs from its original bytes.') - elif kind=='sequence': - fields={'method','rights','adapter','run_sha256','frames_sha256'} - if 'sequence_acquisition' in value:fields.add('sequence_acquisition') - closed(value,fields,'sequence origin');meta=source['metadata'] - if method!='simulation_import' or value['adapter']!=meta['adapter'] or value['run_sha256']!=meta['run_sha256'] or value['frames_sha256']!=meta['manifest']['frames_sha256']:fail('Sequence origin differs from its owner metadata.') - elif kind in ('mesh','pointcloud','volume'): - fields={'method','rights','format','manifest_sha256'}|({'geometry_sha256'} if kind=='mesh' else set()) - closed(value,fields,'native source origin');meta=source['metadata'] - if method!=kind+'_import' or value['format']!=meta['manifest']['format'] or value['manifest_sha256']!=meta['manifest_sha256'] or kind=='mesh' and value['geometry_sha256']!=meta['manifest']['geometry_sha256']:fail('Native source provenance differs from its metadata.') - elif kind=='audio': - closed(value,{'method','rights','audio','source_sha256','transform'},'audio origin') - if method!='import' or value['audio']!=source['metadata'] or value['source_sha256']!=source['asset']['artifact']['sha256'] or value['transform']!='none; original interleaved PCM WAV bytes preserved':fail('Audio origin differs from its original source.') - else: - key='project_source' if method=='project_data_import' else 'run_source' - closed(value,{'method','rights','field_sequence','source_sha256',key},'scientific origin') - if value['field_sequence']!=source['metadata'] or value['source_sha256']!=source['asset']['artifact']['sha256']:fail('Scientific source origin differs.') - from scientific_fields import validate_source_declaration - validate_source_declaration(method,value[key],value['source_sha256'],source['metadata']['source_bytes']) - acquisition=value.get('acquisition',value.get('sequence_acquisition')) - if 'acquisition' in value or 'sequence_acquisition' in value: - _acquisition(acquisition,record,source,records) - - -def _record(row, record_id, source=None): - if type(row) is not dict or row.get('kind') not in ('image', 'text', *ASSET_KINDS): - fail('Unsupported data record kind.', 'unsupported', 409) - extra = {row['kind']} if row['kind'] in ASSET_KINDS else set() - optional = {'target_proposal'} if 'target_proposal' in row else set() - closed(row, SNAPSHOT_FIELDS | extra | optional, 'Workbench record') - if row['id'] != record_id: - fail('Workbench record identity differs.') - natural(row['revision']); sha(row['content_hash']) - if row['source_revision'] is not None: - natural(row['source_revision']) - if row['source_sha256'] is not None: - sha(row['source_sha256']) - if row['pixel_hash'] is not None: - sha(row['pixel_hash']) - text_value(row['name'], 'Name') - if strings(row['groups'], 'Groups') != row['groups'] or not row['groups'] or strings(row['parents'], 'Parents') != row['parents']: - fail('Invalid Workbench groups or parents.') - for parent in row['parents']: - identity(parent, 'parent') - if row['task'] not in TASKS or not row['task'].startswith(row['kind'] + '_') or row['review'] not in REVIEWS: - fail('Invalid Workbench task or review.') - if type(row['source_available']) is not bool or type(row['source_lineage_known']) is not bool: - fail('Invalid historical source availability.') - if type(row['provenance']) is not dict: - fail('Invalid Workbench provenance.') - text_value(row['provenance'].get('rights'), 'Rights note', 1000) - correction = row['provenance'].get('rights_note_correction') - if correction is not None: - closed(correction, {'note', 'revision'}, 'rights correction') - text_value(correction['note'], 'Rights note', 1000) - natural(correction['revision']) - if correction['revision'] > row['revision']: - fail('Rights correction is newer than its record.') - annotation_record = row - deleted_geometry = row['task'] == 'image_detection' and (row['width'] is None or row['height'] is None) - if deleted_geometry and source is not None: - # Source deletion removes the live join, not the retained image geometry. - # The complete codec validates this source history before acknowledging it. - geometry = source['revisions'][-1] - annotation_record = dict(row, width=geometry['width'], height=geometry['height']) - # A standalone tombstone frame has no geometry to prove box fit. Its full - # record decoder supplies retained source geometry; receipt validation also - # requires an exact match to that fully validated retained state. - if row['annotation'] is not None and not (deleted_geometry and source is None): - if validate_annotation(row['task'], row['annotation'], annotation_record) != row['annotation']: - fail('Workbench annotation is not canonical.') - if row['review'] != 'draft' and row['annotation'] is None: - fail('Reviewed record has no annotation.') - if row['kind'] == 'text': - text_value(row['text'], 'Text', MAX_TEXT) - if hashlib.sha256(row['text'].encode()).hexdigest() != row['content_hash']: - fail('Normalized text digest differs.') - elif row['text'] is not None: - fail('Non-text record contains text source.') - if date(row['updated_at']) < date(row['created_at']): - fail('Workbench update precedes creation.') - return row - - -def validate_record_snapshot(record): - """Pure Workbench capture validation for the producer history owner.""" - if type(record) is not dict: - fail('Captured record must be an object.') - _record(record, identity(record.get('id'))) - return copy.deepcopy(record) - - -def _response(row, record_id): - closed(row, RESPONSE_FIELDS, 'response') - if row['id'] != record_id: - fail('Response identity differs.') - identity(row['prompt_id'], 'prompt'); natural(row['revision']) - text_value(row['completion'], 'Completion', MAX_TEXT) - if row['review'] not in ('draft', 'human_reviewed'): - fail('Invalid response review.') - closed(row['provenance'], {'method', 'prompt_id', 'prompt_sha256', 'source_sha256'}, 'response provenance') - if row['provenance']['method'] not in ('human_authored', 'agent_authored') or row['provenance']['prompt_id'] != row['prompt_id']: - fail('Invalid response origin.') - sha(row['provenance']['prompt_sha256']); sha(row['provenance']['source_sha256']) - if date(row['updated_at']) < date(row['created_at']): - fail('Response update precedes creation.') - - -def _judgment(row, record_id): - closed(row, JUDGMENT_FIELDS, 'preference') - if row['id'] != record_id: - fail('Preference identity differs.') - for key in ('id', 'prompt_id', 'left_id', 'right_id'): - identity(row[key], key) - for key in ('revision', 'parent_revision', 'source_revision', 'left_revision', 'right_revision'): - natural(row[key]) - if row['left_id'] == row['right_id'] or row['outcome'] not in ('left', 'right', 'tie', 'abstain') or row['review'] not in ('draft', 'human_reviewed') or type(row['deleted']) is not bool: - fail('Invalid preference meaning.') - text_value(row['rationale'], 'Rationale', 4000) - closed(row['provenance'], {'method'}, 'preference provenance') - if row['provenance']['method'] != ('human_comparative_judgment' if row['review'] == 'human_reviewed' else 'draft_comparative_judgment'): - fail('Preference origin differs from review.') - if date(row['updated_at']) < date(row['created_at']): - fail('Preference update precedes creation.') - - -def _audit_bindings(family,record_id,doc): - """Audit hashes describe exact owner snapshots, never free-standing claims.""" - for fact in doc.get('audit',[]): - action,details=fact['action'],fact['details'] - if action=='dataset.add_generated' and family=='workbench_record': - origin=doc['origin'] - if origin.get('method')!='model_generated' or fact['target']!=origin['generation']['job_id']: - fail('Generated source audit differs from its exact producer job.') - elif fact['target']!=record_id:fail('Data audit target differs from its owning record.') - expected=None - if family=='workbench_record': - states=[doc['current'],*doc['history'],*(e['snapshot'] for e in doc['events'])] - if action.startswith('workbench.'): - candidates=[s for s in states if s['revision']==details.get('revision') and s['source_revision']==details.get('source_revision') and digest(s)==details.get('content_sha256')] - if not candidates:fail('Workbench audit snapshot is not retained.') - state=candidates[0] - expected=dict(revision=state['revision'],source_revision=state['source_revision'],content_sha256=digest(state)) - if action in ('workbench.save','workbench.approve_review','workbench.verify','workbench.correct_rights_note'): - expected.update(before_revision=state['revision']-1,before_source_revision=state['source_revision']) - elif action in ('dataset.add','dataset.add_generated'): - source=doc['source'] - if source['kind']!='image':fail('Image audit is attached to another modality.') - expected=dict(sample_id=record_id,revision=1,source_sha256=source['revisions'][0]['sha256']) - elif action=='dataset.save': - source=doc['source'];sample=next((r for r in source.get('revisions',[]) if r['revision']==details.get('revision')),None) - if sample is None:fail('Image audit source revision is not retained.') - expected=dict(before_revision=sample['revision']-1,revision=sample['revision'],annotation_sha256=digest(sample['annotation'])) - elif action=='dataset.delete': - if not doc['source'].get('deleted'):fail('Image deletion audit lacks its tombstone.') - expected={} - elif action in ('immutable_assets.admit','audio_assets.admit','scientific_fields.admit'): - expected=dict(revision=1,source_sha256=doc['current']['content_hash']) - elif family=='workbench_response': - state=next((h for h in doc['history'] if h['response']['revision']==details.get('revision')),None) - if state and action in ('workbench.save_response','workbench.approve_response'): - r,p=state['response'],state['parent'] - expected=dict(before_revision=r['revision']-1,revision=r['revision'],prompt_id=p['id'],parent_revision=p['revision'],source_revision=p['source_revision'],content_sha256=digest(state)) - elif family=='workbench_preference': - state=next((h for h in doc['history'] if h['judgment']['revision']==details.get('revision')),None) - if state and action in ('preferences.save','preferences.delete'): - expected=dict(revision=state['judgment']['revision'],review=state['judgment']['review'],binding_sha256=digest(state)) - elif family in ('saved_selection','saved_search'): - owner='saved_selections' if family=='saved_selection' else 'saved_searches' - state=next((h for h in doc['history'] if h['revision']==details.get('revision')),None) - if state: - if action==owner+'.create':expected=dict(revision=1,content_sha256=digest(state['items'] if family=='saved_selection' else state['criteria'])) - elif action==owner+'.rename':expected=dict(revision=state['revision'],name_sha256=hashlib.sha256(state['name'].encode()).hexdigest()) - elif action==owner+'.delete' and doc['deleted']:expected=dict(revision=state['revision'],retired_sha256=digest(state)) - elif family=='dataset_release' and action=='dataset_releases.create': - expected=dict(release_sha256=record_id,format=doc['release_format']) - if expected is None or encode_retained(expected)!=encode_retained(details): - fail('Data audit details do not match the retained owner facts.') - - -def _decode_data_records(records): - """Validate complete owned closure, without opening missing payloads or SQL.""" - if type(records) is not list or any(type(r) is not dict for r in records): - fail('Project records must be a list.') - owned, assets, responses, declarations, seen = [], {}, {}, {}, set() - legacy = [r for r in records if r.get('family') == 'workbench_text'] - # Legacy parent closure may cross to a new record; validate each legacy - # record locally, then check parent closure across all data families below. - for item in legacy: - single = copy.deepcopy(item) - parents = single['document']['current']['parents'] - if parents: - # The unchanged M1 decoder requires its family-local parent set. - # Supply the legacy set, whose already-admitted parents stay v1. - decode_text_records(legacy) - break - decode_text_records([single]) - for item in legacy: - assets[item['id']] = item['document'] - for envelope in records: - if type(envelope) is not dict: - fail('Invalid project envelope.') - family = envelope.get('family') - if family not in FAMILIES: - continue - closed(envelope, {'family', 'id', 'document'}, 'data envelope') - record_id, doc = envelope['id'], envelope['document'] - if family in ('dataset_release', 'dataset_exposure'): - sha(record_id) if family == 'dataset_release' else identity(record_id) - else: - identity(record_id) - if (family, record_id) in seen: - fail('Duplicate data envelope.') - seen.add((family, record_id)) - if type(doc) is not dict or doc.get('format') != FAMILIES[family]: - fail('Unsupported data document format.', 'unsupported', 409) - owned.append(envelope) - if family == 'workbench_record': - if record_id in assets: - fail('An asset has more than one current domain family.') - assets[record_id] = doc - elif family == 'workbench_response': - responses[record_id] = doc - for envelope in records: - if envelope.get('family') == 'project_artifact': - declaration = envelope['document'] - closed(declaration, {'format', 'sha256', 'bytes'}, 'artifact declaration') - if declaration['format'] != 'project_artifact_v1' or declaration['sha256'] != envelope['id']: - fail('Artifact declaration identity differs.') - sha(declaration['sha256']) - if type(declaration['bytes']) is not int or not 0<=declaration['bytes']<=2**63-1:fail('Invalid artifact declared byte count.') - declarations[envelope['id']] = declaration - def binding(parent): - _record(parent, identity(parent.get('id'))) - retained = assets.get(parent['id']) - if retained is None: - fail('Captured prompt/source is missing from data closure.') - candidates = [retained['current'], *retained['history'], *(e['snapshot'] for e in retained.get('events',[]))] - if not any(state == parent for state in candidates): - fail('Captured prompt/source snapshot differs from its retained revision.') - for envelope in owned: - family, record_id, doc = envelope['family'], envelope['id'], envelope['document'] - if family == 'workbench_record': - closed(doc, {'format', 'origin', 'source', 'current', 'history', 'events', 'audit'}, 'data record document') - source, current, history = doc['source'], doc['current'], doc['history'] - if type(source) is not dict or source.get('kind') not in ('image', 'text', *ASSET_KINDS): - fail('Invalid data source kind.') - kind = source['kind'] - _record(current, record_id, source) - if current['kind'] != kind or type(doc['origin']) is not dict or 'rights_note_correction' in doc['origin']: - fail('Record source/origin differs.') - if kind == 'text': - closed(source, {'kind', 'original_text'}, 'text source') - text_value(source['original_text'], 'Original text', MAX_TEXT) - normalized = unicodedata.normalize('NFC', source['original_text'].replace('\r\n', '\n').replace('\r', '\n')) - if current['text'] != normalized or current['source_sha256'] != hashlib.sha256(source['original_text'].encode()).hexdigest(): - fail('Original text normalization/source hash differs.') - elif kind == 'image': - closed(source, {'kind', 'original', 'oriented', 'revisions', 'deleted'}, 'image source') - original = _edge(source['original'], declarations, kind, 'original') - oriented = _edge(source['oriented'], declarations, kind, 'oriented') - if type(source['deleted']) is not bool or type(source['revisions']) is not list or not source['revisions']: - fail('Invalid image source lifecycle.') - previous = 0 - for row in source['revisions']: - _source_row(row, record_id) - if row['revision'] != previous + 1 or row['sha256'] != original['sha256'] or any(row[k] != source['revisions'][0][k] for k in ('width','height','created_at')): - fail('Image source revisions or original hash differ.') - previous = row['revision'] - if current['content_hash'] != oriented['sha256']: - fail('Oriented image identity differs.') - else: - closed(source, {'kind', 'asset', 'metadata'}, 'immutable source') - declaration = _edge(source['asset'], declarations, kind, 'original') - if current['content_hash'] != declaration['sha256'] or current[kind] != source['metadata']: - fail('Immutable source metadata or content identity differs.') - if type(source['metadata']) is not dict: - fail('Immutable metadata must be an object.') - _source_metadata(kind,source['metadata']) - expected_bytes=source['metadata'].get('bundle_bytes',source['metadata'].get('source_bytes')) - if expected_bytes!=declaration['bytes'] or not set(source['metadata']['protected_groups'])<=set(current['groups']): - fail('Immutable byte count or protected groups differ.') - _origin(doc['origin'],current,source,records) - if type(history) is not list or not history: - fail('Workbench annotation history is missing.') - for revision, state in enumerate(history, 1): - _record(state, record_id, source) - if state['revision'] != revision or state['kind'] != kind or state['content_hash'] != current['content_hash']: - fail('Workbench immutable identity/history revisions differ.') - if state['created_at']!=current['created_at'] or state['parents']!=current['parents'] or state['pixel_hash']!=current['pixel_hash']: - fail('Workbench history rewrites immutable source lineage.') - if revision>1 and date(state['updated_at'])1 and date(state['response']['updated_at'])1:fail('Fork asset has ambiguous destination mappings.') - return values[0]['destination_id'] if values else None - def asset_row(record_id): - new_id=asset_mapping(record_id) - return indexed[('workbench_record',new_id)]['document']['history'][0] if new_id else None - for mapping in own: - family=mapping['family'];original=indexed[(family,mapping['source_id'])] - destination=indexed[(_destination_family(family),mapping['destination_id'])] - doc=destination['document'] - initial=doc['history'][0] - row=initial['response'] if family=='workbench_response' else initial['judgment'] if family=='workbench_preference' else initial - now=row['created_at'];date(now) - if family in ('workbench_record','workbench_text'): - if mapping['source_revision']!=_revision(original):fail('Fork source domain revision differs.') - expected=_asset(original,destination['id'],overlay['source']['project_id'],overlay['source']['checkpoint'],now,asset_mapping)['document'] - if initial!=expected['history'][0] or doc['origin']!=expected['origin']: - fail('Fork initial Workbench snapshot differs from its exact derived draft.') - if doc['source']['kind']=='image': - if doc['source']['revisions'][0]!=expected['source']['revisions'][0]:fail('Fork initial image source differs.') - elif doc['source']!=expected['source']:fail('Fork immutable source differs.') - elif family=='workbench_response': - revision=mapping['source_revision'];natural(revision) - source_row=next((h['response'] for h in original['document']['history'] if h['response']['revision']==revision),None) - if source_row is None:fail('Fork response source revision is missing.') - parent=asset_row(source_row['prompt_id']) - if parent is None:fail('Fork response lost its current prompt.') - expected=_response(original,revision,destination['id'],parent,now)['document'] - if initial!=expected['history'][0]:fail('Fork initial response binding differs.') - elif family=='workbench_preference': - if mapping['source_revision']!=_revision(original):fail('Fork judgment source revision differs.') - source_row=original['document']['current'];parent=asset_row(source_row['prompt_id']);answers=[] - for side in ('left','right'): - answer=by_source.get(('workbench_response',source_row[side+'_id'],source_row[side+'_revision'])) - if answer is None:fail('Fork judgment exact answer revision is missing.') - answers.append(indexed[('workbench_response',answer['destination_id'])]['document']['history'][0]['response']) - expected=_preference(original,destination['id'],parent,*answers,now)['document'] - if initial!=expected['history'][0]:fail('Fork initial preference binding differs.') - else: - if mapping['source_revision']!=_revision(original):fail('Fork saved intent source revision differs.') - expected=_intent(original,destination['id'],now,asset_row)['document'] - if initial!=expected['history'][0]:fail('Fork initial saved intent differs.') - return True - - -def source_origin(origin, records): - """Follow only validated inert fork facts to a subtype source declaration.""" - indexed=_index(records);seen=set();value=origin - while value.get('method')=='project_fork': - ref=value['origin'];key=ref['family'],ref['id'] - if key in seen or key not in indexed:fail('Fork source provenance is cyclic or unavailable.') - seen.add(key);doc=indexed[key]['document'] - value=doc.get('origin',doc['current']['provenance']) - return copy.deepcopy(value) diff --git a/project_dispatch.py b/project_dispatch.py deleted file mode 100644 index e517c2e6..00000000 --- a/project_dispatch.py +++ /dev/null @@ -1,451 +0,0 @@ -"""Fixed M2 public-to-owner dispatch for one already bound project projection. - -The workspace validates selection, binding, checkpoint and the HTTP envelope. -This module projects bounded pages and calls existing domain methods. It neither -constructs live owners nor interprets scientific records or imported authority. -""" -import base64 -import binascii -import copy - -from workbench import WorkbenchError -from project_session import session_records - - -_BOUND_FIELDS = frozenset(('binding', 'checkpoint', 'expected_checkpoint', 'request_key')) -_DATA_ACTIONS = frozenset(('data_query', 'data_get', 'data_scientific', 'data_availability', 'data_history', - 'data_responses', 'data_response_history', 'data_preferences', 'data_preference_history', - 'data_import_text', 'data_import_image', 'data_import_audio', 'data_import_mesh', - 'data_import_pointcloud', 'data_import_volume', 'data_import_sequence', 'data_import_scientific', - 'data_annotate', 'data_rights', 'data_source_save', 'data_source_delete', 'data_response_save', - 'data_preference_save', 'data_preference_delete', 'selections', 'selection_get', 'selection_create', - 'selection_rename', 'selection_delete', 'searches', 'search_create', 'search_rename', - 'search_delete', 'release_preview', 'release_freeze')) -_MATERIAL_ACTIONS = frozenset(('definitions', 'models', 'model_get', 'model_create', 'model_save', - 'model_publish', 'graphs', 'graph_get', 'graph_create', 'graph_create_external', 'graph_save', 'graph_clone', 'recipes', - 'recipe_get', 'recipe_create', 'recipe_save', 'recipe_prepare', 'model_material', - 'recipe_material', 'runtime_material', 'snapshot', 'materials')) -_HISTORY_ACTIONS = frozenset(('studies', 'study', 'study_create', 'study_save', 'trial', 'trial_prepare', - 'lineage', 'lineage_record', 'progression_origins', 'progression', 'run', 'runs', 'candidate', 'candidate_select', 'evidence', - 'retained_analysis', 'retained_analysis_export', 'policies', 'policy', 'dependencies', - 'publication_result', 'package_state', 'expose_holdout', 'run_document_segment')) -_OTHER_ACTIONS = frozenset(('artifacts', 'artifact_status', 'artifact_resolve', 'producers', 'producer', 'source_register', 'source_references')) -_EXECUTION_ACTIONS = frozenset(('native_preflight','native_submit','native_retry','native_reconcile','execution_health', 'execution_preflight_external', 'execution_approve_external', - 'execution_submit_external', 'execution_cancel', 'execution_study_continue', 'execution_study_approve', - 'execution_study_admit', 'execution_study_stop', 'execution_reconcile_current', - 'execution_producer_start', 'execution_generation_resume', 'execution_grounded_review', - 'execution_producer_decide', 'execution_producer_cancel', 'execution_producer_health', - 'execution_study_prepare_package','execution_study_prepare_verifier','execution_study_abandon_preparation','execution_study_reconcile_preparation')) -_RUNTIME_ACTIONS=frozenset(('runtime_sources','runtime_inspect','runtime_capture','runtime_status','runtime_abandon')) -_MEASUREMENT_ACTIONS=frozenset(('measurement_import','measurement_sources','measurement_metadata', - 'measurement_subjects','measurement_query','measurement_inspect','measurement_compare')) -_M4_ACTIONS=frozenset(('files_inspect','file_get','file_history','file_adopt','files_adopt','file_adopt_deletion','material_intents','material_intent','material_intent_capabilities','fork_info')) -SUPPORTED_OPERATIONS = frozenset('project_files.' + action for action in - _DATA_ACTIONS | _MATERIAL_ACTIONS | _HISTORY_ACTIONS | _OTHER_ACTIONS | _EXECUTION_ACTIONS | _M4_ACTIONS | _RUNTIME_ACTIONS | _MEASUREMENT_ACTIONS) - - -def _body(arguments, *omit): - return {key: copy.deepcopy(value) for key, value in arguments.items() - if key not in _BOUND_FIELDS and key not in omit} - - -def _page(items, arguments, *, default=40): - offset, limit = arguments.get('offset', 0), arguments.get('limit', default) - if type(offset) is not int or offset < 0 or type(limit) is not int or not 1 <= limit <= (4 if default == 1 else 40): - raise WorkbenchError('Invalid project page bounds.') - return dict(items=copy.deepcopy(items[offset:offset + limit]), total=len(items), offset=offset, limit=limit) - - -def _origin_items(items, arguments): - origin = arguments.get('origin_catalog_id') - return [item for item in items if origin is None or item['origin_catalog_id'] == origin] - - -def _declarations(projection): - return {item['id']: item['document'] for item in session_records(projection.session, 'project_artifact')} - - -def _artifact(projection, sha): - declaration = _declarations(projection).get(sha) - if declaration is None: - raise WorkbenchError('Project artifact declaration is unavailable.', 'unavailable', 404) - return declaration - - -def _bundle(projection, kind, arguments): - """Existing native parsers alone assign bundle meaning, before publication.""" - body = _body(arguments) - files = body['files'] - try: - if kind == 'mesh': - import meshes - prepared = meshes.prepare(meshes.decode_file(files['mesh.ply'], meshes.PLY_LIMIT, 'mesh.ply'), - meshes.decode_file(files['mesh.json'], meshes.MANIFEST_LIMIT, 'mesh.json')) - elif kind in ('pointcloud', 'volume'): - import spatial_assets - parser, names, caps = spatial_assets.profile(kind) - raw = [] - for name, cap in zip(names, caps): - value = base64.b64decode(files[name], validate=True) - if not 0 < len(value) <= cap: - raise ValueError() - raw.append(value) - prepared = parser.prepare(*raw) - elif kind == 'sequence': - prepared = projection.data.workbench.sequences.prepare_project_files(files) - else: - raise WorkbenchError('Unsupported native project import.', 'unsupported', 409) - except WorkbenchError: - raise - except (ValueError, binascii.Error, KeyError, TypeError): - raise WorkbenchError('Invalid native project import bundle.') from None - return projection.data.import_bundle(kind, prepared, body, arguments['expected_checkpoint'], arguments['request_key']) - - -def _data(projection, action, a): - data = projection.data - if action == 'data_query': return data.query(_body(a)) - if action == 'data_get': return data.get(a['record_id']) - if action == 'data_scientific': return data.scientific(a['record_id'], a['content_hash'], - **{key: a[key] for key in ('frame', 'field', 'axis', 'index') if key in a}) - if action == 'data_availability': return data.availability(a['record_id']) - if action == 'data_history': return _page(data.history(a['record_id']), a, default=1) - if action == 'data_responses': return _page(data.responses(a['record_id'])['responses'], a) - if action == 'data_response_history': - return _page(sorted(data.response_history(a['record_id'])['history'], key=lambda item: item['revision'], reverse=True), a, default=1) - if action == 'data_preferences': return _page(data.preferences(a['record_id'])['judgments'], a) - if action == 'data_preference_history': - return _page(sorted(data.preference_history(a['record_id'])['history'], key=lambda item: item['revision'], reverse=True), a, default=1) - if action == 'selections': return _page(sorted(data.list_selections()['selections'], key=lambda item: item['id']), a) - if action == 'searches': return _page(sorted(data.list_searches()['searches'], key=lambda item: item['id']), a) - if action == 'selection_get': return data.load_selection(a['selection_id']) - if action == 'release_preview': return data.preview_release(_body(a)) - cp, key = a['expected_checkpoint'], a['request_key'] - if action == 'data_import_text': return data.import_text(_body(a), cp, key) - if action == 'data_import_image': return data.import_image(_body(a), cp, key) - if action == 'data_import_audio': return data.import_audio(_body(a), cp, key) - if action == 'data_import_mesh': return _bundle(projection, 'mesh', a) - if action == 'data_import_pointcloud': return _bundle(projection, 'pointcloud', a) - if action == 'data_import_volume': return _bundle(projection, 'volume', a) - if action == 'data_import_sequence': return _bundle(projection, 'sequence', a) - if action == 'data_import_scientific': return projection.source_adapter.import_scientific(_body(a), cp, key) - if action == 'data_annotate': return data.annotate(a['record_id'], _body(a, 'record_id'), cp, key) - if action == 'data_rights': return data.correct_rights_note(a['record_id'], _body(a, 'record_id'), cp, key) - if action == 'data_source_save': return data.save_image_source(a['record_id'], a['document'], cp, key) - if action == 'data_source_delete': return data.delete_image_source(a['record_id'], a['document'], cp, key) - if action == 'data_response_save': return data.save_response(a['document'], cp, key) - if action == 'data_preference_save': return data.save_preference(a['document'], cp, key) - if action == 'data_preference_delete': return data.delete_preference(a['document'], cp, key) - if action == 'selection_create': return data.create_selection(a['document'], cp, key) - if action == 'selection_rename': return data.rename_selection(a['selection_id'], _body(a, 'selection_id'), cp, key) - if action == 'selection_delete': return data.delete_selection(a['selection_id'], _body(a, 'selection_id'), cp, key) - if action == 'search_create': return data.create_search(a['document'], cp, key) - if action == 'search_rename': return data.rename_search(a['search_id'], _body(a, 'search_id'), cp, key) - if action == 'search_delete': return data.delete_search(a['search_id'], _body(a, 'search_id'), cp, key) - if action == 'release_freeze': return data.freeze_release(_body(a), cp, key) - raise AssertionError('Closed data dispatch is incomplete.') - - -def _definitions(projection, family, a): - docs = projection.materials._documents() - values = [doc['current'] for (kind, _), doc in docs.items() - if kind == family and doc['origin_catalog_id'] == projection.session.summary['project_id']] - return _page(sorted(values, key=lambda item: item['id']), a) - - -def _material(projection, action, a): - materials, models, pipelines = projection.materials, projection.context.models, projection.context.pipelines - if action == 'definitions': return pipelines.definitions() - if action == 'models': return _definitions(projection, 'model_definition', a) - if action == 'graphs': return _definitions(projection, 'pipeline_graph', a) - if action == 'recipes': return _definitions(projection, 'recipe_definition', a) - if action == 'model_get': return models.get(a['model_id']) - if action == 'graph_get': return pipelines.get(a['graph_id']) - if action == 'recipe_get': return pipelines.get_recipe(a['recipe_id']) - if action == 'model_material': return materials.model(a['ref'], verify=a.get('verify', False)) - if action == 'recipe_material': return materials.recipe(a['ref'], verify=a.get('verify', False)) - if action == 'runtime_material': return materials.runtime(a['ref'], verify=a.get('verify', False)) - if action == 'snapshot': return materials.snapshot_ref(a['project_id'], a['manifest_sha256'], - catalog_id=a['origin_catalog_id'], verify=a.get('verify', False)) - if action == 'materials': - items = [] - for (family, _), doc in materials._documents().items(): - if family not in ('model_material', 'recipe_material', 'runtime_material', 'project_snapshot'): continue - value = doc['value'] - identity = value.get('ref', {}).get('id', value.get('id')) - item = dict(family=family, origin_catalog_id=doc['origin_catalog_id'], id=identity, - format=value.get('material', value).get('format')) - if 'ref' in value: item['ref'] = copy.deepcopy(value['ref']) - else: item['manifest_sha256'] = value['manifest_sha256'] - items.append(item) - return _page(sorted(_origin_items(items, a), key=lambda item: (item['origin_catalog_id'], item['family'], item['id'])), a) - cp, key = a['expected_checkpoint'], a['request_key'] - if action == 'model_create': - body = _body(a) - return materials.mutate_definition('model_definition', 'models.create', None, body, cp, key, lambda: models.create(body)) - if action == 'model_save': - body = _body(a, 'model_id') - return materials.mutate_definition('model_definition', 'models.save', a['model_id'], body, cp, key, lambda: models.save(a['model_id'], body)) - if action == 'model_publish': return materials.publish_model(models, a['model_id'], _body(a, 'model_id'), cp, key) - if action == 'graph_create': - body = _body(a) - return materials.mutate_definition('pipeline_graph', 'graphs.create', None, body, cp, key, lambda: pipelines.create(body)) - if action == 'graph_create_external': - body = _body(a) - return materials.mutate_definition('pipeline_graph', 'graphs.create_external', None, body, cp, key, lambda: pipelines.create_external(body)) - if action == 'graph_save': - body = _body(a, 'graph_id') - return materials.mutate_definition('pipeline_graph', 'graphs.save', a['graph_id'], body, cp, key, lambda: pipelines.save(a['graph_id'], body)) - if action == 'graph_clone': - body = _body(a, 'graph_id') - return materials.mutate_definition('pipeline_graph', 'graphs.clone', a['graph_id'], body, cp, key, lambda: pipelines.clone(a['graph_id'], body)) - if action == 'recipe_create': - body = _body(a) - return materials.mutate_definition('recipe_definition', 'recipes.create', None, body, cp, key, lambda: pipelines.create_recipe(body)) - if action == 'recipe_save': - body = _body(a, 'recipe_id') - return materials.mutate_definition('recipe_definition', 'recipes.save', a['recipe_id'], body, cp, key, lambda: pipelines.save_recipe(a['recipe_id'], body)) - if action == 'recipe_prepare': - from pipeline import model_aware_graph - graph=pipelines.get(a['graph_id']);builtin=model_aware_graph(graph) - if graph.get('recipe')!='external_recipe' and not builtin: - raise WorkbenchError('This native graph does not support composed model material.','unsupported',409) - if 'builtin' in a and a['builtin'] is not builtin: - raise WorkbenchError('Recipe preparation kind differs from the saved graph.','conflict',409) - return materials.prepare_recipe(pipelines, a['graph_id'], a['revision'], a['model'], cp, key, - builtin=builtin, reconcile_capture=a.get('reconcile_capture', False), - runtime_manifest=projection.runtime_manifest) - raise AssertionError('Closed material dispatch is incomplete.') - - -def _study_summary(study): - summary = copy.deepcopy(study) - trial_ids = summary.pop('trial_ids') - summary['source_format'] = summary.pop('format') - summary['format'] = 'project_study_summary_v1' - summary['trial_count'] = len(trial_ids) - return summary - - -def _study_page(history, arguments): - value = history.study(arguments['study_id'], origin_catalog_id=arguments['origin_catalog_id'], - offset=arguments.get('offset', 0), limit=arguments.get('limit', 40), revision=arguments.get('revision')) - result = copy.deepcopy(value) - result['study'] = _study_summary(value['study']) - result['trials'] = _page([{'id': identity} for identity in value['study']['trial_ids']], arguments) - return result - - -def _run_page(history, arguments): - value = history.run(arguments['run_id'], origin_catalog_id=arguments['origin_catalog_id'], - offset=arguments.get('offset', 0), limit=arguments.get('limit', 40)) - # The Run owner applies the shared disclosure projection first. Large - # captured documents and collections remain exact through document segments. - run = value['run'] - fields = ('mode', 'id', 'dataset_id', 'request_key', 'state', 'created_at', 'started_at', - 'finished_at', 'graph_revision', 'graph_sha256', 'attempt', 'parent_run_id', - 'quality_claim', 'execution_kind', 'result_kind', 'material_sha256', - 'approval_id', 'actor_id', 'custody_phase', 'release_id', 'release_sha256', 'release_bytes') - summary = {key: copy.deepcopy(run[key]) for key in fields if key in run} - summary.update(format='project_run_summary_v1', source_schema_version=run['schema_version'], - available_fields=sorted(run), - collection_counts={key: len(run[key]) for key in - ('events', 'artifacts', 'node_attempts', 'exposure_events', 'prior_test_exposure', '_phase_timings') - if isinstance(run.get(key), list)}) - result = {key: copy.deepcopy(item) for key, item in value.items() if key != 'run'} - result['run'] = summary - return result - - -def _history(projection, action, a): - history = projection.history - origin = a.get('origin_catalog_id') - if action == 'studies': - return _page([dict(origin_catalog_id=item['origin_catalog_id'], study=_study_summary(item['study'])) - for item in _origin_items(history.studies()['studies'], a)], a) - if action == 'study': return _study_page(history, a) - if action == 'trial': return history.trial(a['trial_id'], origin_catalog_id=origin) - if action == 'run': return _run_page(history, a) - if action == 'run_document_segment': return history.run_document_segment(a['run_id'], - origin_catalog_id=origin, expected_sha256=a['expected_sha256'], offset=a['offset'], limit=a['limit']) - if action == 'candidate': return history.candidate(a['candidate_id'], origin_catalog_id=origin, verify=a.get('verify', False)) - if action == 'lineage': return _page(history.lineage(origin_catalog_id=origin)['records'], a) - if action == 'progression_origins': return history.progression_origins(offset=a.get('offset',0),limit=a.get('limit',40)) - if action == 'progression': return history.progression(origin,offset=a.get('offset',0),limit=a.get('limit',20),cohort=a.get('cohort')) - if action == 'policies': return _page(history.policies(origin_catalog_id=origin)['policies'], a) - if action == 'policy': return history.policy(a['ref']) - if action == 'runs': - items = [] - for (catalog, identity), doc in sorted(history._facts().runs.items()): - run = doc['run'] - summary = {key: copy.deepcopy(run[key]) for key in ('id', 'name', 'state', 'created_at', 'finished_at', 'execution_kind') if key in run} - items.append(dict(origin_catalog_id=catalog, run=summary)) - return _page(_origin_items(items, a), a) - if action == 'dependencies': return history.dependencies(a['run_id'], origin_catalog_id=origin, - offset=a.get('offset', 0), limit=a.get('limit', 40)) - if action == 'publication_result': return history.publication_result(a['run_id'], origin_catalog_id=origin) - if action == 'package_state': return history.package_state(a['candidate_id'], origin_catalog_id=origin) - if action == 'evidence': return history.evidence(a['run_id'], a.get('selectors'), origin_catalog_id=origin) - if action in ('retained_analysis', 'retained_analysis_export'): - return history.retained_analysis(origin, _body(a, 'origin_catalog_id'), export=action == 'retained_analysis_export') - cp, key = a['expected_checkpoint'], a['request_key'] - if action == 'study_create': return history.create_study(_body(a), cp, key) - if action == 'study_save': return history.save_study(a['study_id'], _body(a, 'study_id'), cp, key) - if action == 'trial_prepare': return history.prepare_trial_from_material(a['study_id'], _body(a, 'study_id'), cp, key) - if action == 'candidate_select': return history.select_candidate(a['study_id'], _body(a, 'study_id'), cp, key) - if action == 'lineage_record': return history.record_lineage(_body(a), cp, key) - if action == 'expose_holdout': return projection.disclose(a['run_id'], _body(a, 'run_id'), cp, key) - raise AssertionError('Closed historical dispatch is incomplete.') - - -def _execution(projection, action, a): - execution = projection.execution - if execution is None: - raise WorkbenchError('Current execution is unavailable for this project.', 'unavailable', 409) - if action == 'execution_health': return execution.health(offset=a.get('offset', 0), limit=a.get('limit', 40)) - if action == 'execution_preflight_external': return execution.preflight_external(a['graph_id'], a['revision']) - if action == 'execution_reconcile_current': return execution.reconcile_current() - if action == 'execution_producer_health': - if execution.producer_execution is None: - raise WorkbenchError('Current producer execution is unavailable.', 'unavailable', 409) - return execution.producer_execution.status(offset=a.get('offset', 0), limit=a.get('limit', 40)) - if action=='execution_study_reconcile_preparation': - if execution.study_execution is None:raise WorkbenchError('Current Study execution is unavailable.','unavailable',409) - return execution.study_execution.reconcile_preparation(a['study_id'],_body(a,'study_id'),a['expected_checkpoint']) - if action=='native_reconcile':return execution.native_reconcile(a['phase_id'],a['expected_checkpoint']) - cp, key = a['expected_checkpoint'], a['request_key'] - if action=='native_preflight':return execution.native_preflight(a['graph_id'],a['revision'],cp,key) - if action=='native_submit':return execution.native_submit(_body(a),cp,key) - if action=='native_retry':return execution.native_retry(a['run_id'],cp,key) - if action == 'execution_producer_start' or action in ('execution_generation_resume', 'execution_grounded_review', 'execution_producer_decide', 'execution_producer_cancel'): - producers = execution.producer_execution - if producers is None: - raise WorkbenchError('Current producer execution is unavailable.', 'unavailable', 409) - if action == 'execution_producer_start': return producers.start(a['family'], a['document'], cp, key) - if action == 'execution_generation_resume': return producers.resume_generation(a['producer_id'], cp, key) - if action == 'execution_grounded_review': return producers.review_grounded(a['producer_id'], a['document'], cp, key) - if action == 'execution_producer_decide': return producers.decide(a['family'], a['producer_id'], a['document'], cp, key) - return producers.cancel(a['family'], a['producer_id'], cp, key) - if action == 'execution_approve_external': return execution.approve_external(_body(a), cp, key) - if action == 'execution_submit_external': return execution.submit_external(_body(a), cp, key) - if action == 'execution_cancel': return execution.cancel_run(a['run_id'], cp, key) - studies = execution.study_execution - if studies is None: - raise WorkbenchError('Current Study execution is unavailable.', 'unavailable', 409) - if action=='execution_study_prepare_package':return studies.prepare_package(a['study_id'],_body(a,'study_id'),cp,key) - if action=='execution_study_prepare_verifier':return studies.prepare_verifier(a['study_id'],_body(a,'study_id'),cp,key) - if action=='execution_study_abandon_preparation':return studies.abandon_preparation(a['study_id'],_body(a,'study_id'),cp,key) - if action == 'execution_study_continue': return studies.continue_study(a['study_id'], _body(a, 'study_id'), cp, key) - if action == 'execution_study_approve': return studies.approve(a['study_id'], _body(a, 'study_id'), cp, key) - if action == 'execution_study_admit': return studies.admit(a['study_id'], _body(a, 'study_id'), cp, key) - if action == 'execution_study_stop': return studies.stop(a['study_id'], _body(a, 'study_id'), cp, key) - raise AssertionError('Closed execution dispatch is incomplete.') - - -def _runtime(projection, action, a): - if action=='runtime_sources': - return _page([dict(source=alias) for alias in projection.runtime_sources()['sources']],a) - if action=='runtime_inspect': - value=projection.runtime.inspect({'source':a['source']});manifest=value['manifest'] - return dict(format='project_runtime_inspection_v1',source=a['source'], - **{field:copy.deepcopy(value[field]) for field in ('inventory_sha256','file_count','total_bytes','manifest_bytes','free_bytes')}, - profile=manifest['profile'],python_version=manifest['python_version'],launch=copy.deepcopy(manifest['launch']), - packages=[dict(name=name,version=version) for name,version in sorted(manifest['packages'].items())], - files=_page(manifest['files'],a)) - if action=='runtime_status':return projection.runtime.status(a['capture_key']) - if action=='runtime_abandon':return projection.runtime.abandon(a['capture_key'],a['reason'],a['expected_checkpoint'],a['request_key']) - if action=='runtime_capture': - options={'reserve_bytes':a['reserve_bytes']} if 'reserve_bytes' in a else {} - return projection.runtime.capture({'source':a['source']},a['expected_inventory_sha256'], - a['expected_checkpoint'],a['request_key'],**options) - raise AssertionError('Closed runtime dispatch is incomplete.') - - -def _m4(projection,action,a): - session=projection.session - if action=='file_adopt': - return projection.files.adopt(_body(a),a['expected_checkpoint'],a['request_key']) - if action=='files_adopt': - return projection.files.adopt_many(_body(a),a['expected_checkpoint'],a['request_key']) - if action=='file_adopt_deletion': - return projection.files.adopt_deletion(_body(a),a['expected_checkpoint'],a['request_key']) - with session.access.lock,session.lock,session.db.lock: - session.access.require('inspect','project_files.'+action) - if action=='fork_info': - snapshot=session.check() - from project_fork import decode_fork - overlay=decode_fork(snapshot['records'],project_id=snapshot['project_id']) - return dict(source=overlay['source'] if overlay else None,project_id=snapshot['project_id'], - mapping=_page(overlay['mapping'] if overlay else [],a),archived_count=len(overlay['archived']) if overlay else 0, - copied_count=len(overlay['artifacts']['copied']) if overlay else 0, - missing_regenerable_count=len(overlay['artifacts']['missing_regenerable']) if overlay else 0) - session.check_current() - if action=='files_inspect':return _page(projection.files.inspect()['items'],a) - if action=='file_get':return projection.files.read(a['file_id'],a.get('revision')) - if action=='file_history': - values=projection.files.history(a['file_id']) - return dict(id=a['file_id'],**_page([{k:v[k] for k in ('revision','sha256','bytes','adopted_at','actor_id',*(['deleted'] if v.get('deleted') is True else []))} for v in values],a)) - if action in ('material_intents','material_intent'): - intents=projection.materials.intents() - if action=='material_intent': - result=next((item for item in intents if item['family']==a['family'] and item['current']['id']==a['definition_id']),None) - if result is None:raise WorkbenchError('Unresolved material intent is unavailable.','unavailable',404) - return result - return _page([dict(family=item['family'],id=item['id'],catalog_id=item['current']['catalog_id'], - definition_id=item['current']['id'],name=item['current']['name'],revision=item['current']['revision'], - required_reselection=item['current']['required_reselection'],fork_origin=item['fork_origin']) for item in intents],a) - if action=='material_intent_capabilities': - value=projection.materials.intent_capabilities() - items=[dict(item,requires_reselection=[]) for item in value['editable']] - items.extend(dict(family=item['family'],id=item['id'],requires_reselection=item['fields']) for item in value['requires_reselection']) - return _page(sorted(items,key=lambda item:(item['family'],item['id'])),a) - raise AssertionError('Closed M4 dispatch is incomplete.') - - -def dispatch(projection, name, arguments): - if name not in SUPPORTED_OPERATIONS: - raise WorkbenchError('Unsupported external-project operation.', 'unsupported', 409) - action = name.split('.')[1] - projection.session.access.require('inspect', name) - if action in _MEASUREMENT_ACTIONS:return _measurements(projection,action,arguments) - if action in _RUNTIME_ACTIONS:return _runtime(projection,action,arguments) - if action in _M4_ACTIONS:return _m4(projection,action,arguments) - if action in _EXECUTION_ACTIONS: return _execution(projection, action, arguments) - if action in _DATA_ACTIONS: return _data(projection, action, arguments) - if action in _MATERIAL_ACTIONS: return _material(projection, action, arguments) - if action in _HISTORY_ACTIONS: return _history(projection, action, arguments) - if action == 'artifacts': - items = [dict(copy.deepcopy(declaration), availability=projection.artifacts.inspect(declaration)) - for _, declaration in sorted(_declarations(projection).items())] - return _page(items, arguments) - if action == 'artifact_status': return projection.artifacts.status(_artifact(projection, arguments['sha256'])) - if action == 'artifact_resolve': - projection.session.access.require('edit', 'project_files.artifact_resolve', arguments['sha256'], owner_only=True) - return projection.resolve_artifact(_body(arguments), arguments['expected_checkpoint'], arguments['request_key']) - if action == 'producers': return projection.producers.list(arguments['family'], - origin_catalog_id=arguments.get('origin_catalog_id'), offset=arguments.get('offset', 0), limit=arguments.get('limit', 40)) - if action == 'producer': return projection.producers.get(arguments['family'], arguments['producer_id'], - origin_catalog_id=arguments['origin_catalog_id'], entries_offset=arguments.get('entries_offset', 0), - entries_limit=arguments.get('entries_limit', 40)) - if action == 'source_references': - return projection.source_adapter.references( - {key: arguments[key] for key in ('origin_catalog_id', 'project_id', 'manifest_sha256')}, - offset=arguments.get('offset', 0), limit=arguments.get('limit', 40)) - if action == 'source_register': - projection.session.access.require('edit', 'project_files.source_register', owner_only=True) - return projection.source_adapter.register(_body(arguments), arguments['expected_checkpoint'], arguments['request_key']) - raise AssertionError('Closed project dispatch is incomplete.') - - -def _measurements(projection,action,a): - owner=projection.measurements - if action=='measurement_import': - return projection.source_adapter.import_measurements(_body(a),a['expected_checkpoint'],a['request_key']) - if action=='measurement_sources':return owner.sources(offset=a.get('offset',0),limit=a.get('limit',40)) - if action=='measurement_compare':return owner.compare(a['sources'],**_body(a,'sources')) - origin,packet=a['origin_catalog_id'],a['packet_sha256'] - if action=='measurement_metadata':return owner.metadata(origin,packet) - if action=='measurement_subjects':return owner.subjects(origin,packet,offset=a.get('offset',0),limit=a.get('limit',40)) - if action=='measurement_query':return owner.query(origin,packet,**_body(a,'origin_catalog_id','packet_sha256')) - if action=='measurement_inspect':return owner.inspect(origin,packet,a['observation_id']) - raise AssertionError('Closed measurement dispatch is incomplete.') diff --git a/project_execution.py b/project_execution.py deleted file mode 100644 index 9f7a5878..00000000 --- a/project_execution.py +++ /dev/null @@ -1,1057 +0,0 @@ -"""Current-host project execution, separate from inert imported Run history. - -Construction installs transaction capture hooks but never constructs Runs, -claims runtime ownership, recovers a process or wakes a queue. Only an explicit -currently authorized action may create the local execution owner. -""" -import copy -from contextlib import contextmanager -import hashlib -import json -import os -import re -import threading -import time -import uuid - -import agent_api -from access import Access, AccessError -from model_definitions import natural -from pipeline import closed, digest, identifier -from project_history import capture_run, declarations -from project_session import operation_records -from workbench import WorkbenchError -from project_session import session_operations - - -OPERATIONS = frozenset(('runs.submit_external', 'runs.submit', 'runs.retry', 'runs.cancel', 'runs.approve_external')) - - -class _FileEffect: - """One of the two named nonexecuting filesystem publication guards.""" - def __init__(self, execution, kind, key, input_sha256, content_sha256): - self.execution,self.kind,self.key=execution,kind,key - self.input_sha256,self.content_sha256=input_sha256,content_sha256 - self.started=False;self.done=False - - def publication_started(self): - execution=self.execution - pending=execution._runtime_pending if self.kind=='runtime' else execution._package_pending - identity_field='manifest_sha256' if self.kind=='runtime' else 'material_sha256' - entry=dict(request_key=self.key,input_sha256=self.input_sha256,**{identity_field:self.content_sha256}) - previous=pending.get(self.key) - if previous is not None and previous!=entry: - raise WorkbenchError('File publication key has different current input.','conflict',409) - # Retain a conservative local fence even if journal fsync acknowledgement - # fails. No owner filesystem write follows an unacknowledged start. - pending[self.key]=entry;self.started=True - if execution.custody is not None: - with execution._journal_guard(): - if not execution.custody.has_pending:execution.custody.acknowledge(execution.session.snapshot) - if self.kind=='runtime':execution.custody.runtime_started(self.key,self.input_sha256,self.content_sha256) - else:execution.custody.package_started(self.key,self.input_sha256,self.content_sha256) - - def confirmed(self): - if not self.started:raise RuntimeError('File publication must have a durable start before confirmation.') - execution=self.execution;execution.session.check_current() - if execution.db.in_transaction: - raise RuntimeError('File publication confirms only after its canonical and outer SQL acknowledgement.') - if execution.custody is not None: - with execution._journal_guard(): - if self.kind=='runtime':execution.custody.runtime_confirmed(self.key) - else:execution.custody.package_confirmed(self.key) - pending=execution._runtime_pending if self.kind=='runtime' else execution._package_pending - pending.pop(self.key,None);self.done=True - - -def _admission_result(run): - return dict(format='project_run_admission_v1', origin_catalog_id=run['dataset_id'], - run_id=run['id'], request_sha256=run['request_sha256']) - - -def validate_operation_result(operation, result, records=None): - """Validate inert operation facts, never a live grant or resume instruction.""" - if operation not in OPERATIONS: - return False - if operation == 'runs.approve_external': - closed(result, ('format','origin_catalog_id','approval_id','material_sha256', - 'consumer_actor_id','approver_actor_id','created_at','expires_at')) - if result['format'] != 'project_execution_approval_v1': - raise WorkbenchError('Invalid project approval observation.') - for key in ('origin_catalog_id','approval_id','consumer_actor_id','approver_actor_id'): - identifier(result[key], key) - if type(result['material_sha256']) is not str or not re.fullmatch('[a-f0-9]{64}', result['material_sha256']): - raise WorkbenchError('Invalid approved material identity.') - natural(result['created_at'], 'Approval time');natural(result['expires_at'], 'Approval expiry') - if not result['created_at'] < result['expires_at'] <= result['created_at'] + 3600: - raise WorkbenchError('Invalid approval observation lifetime.') - return True - closed(result, ('format','origin_catalog_id','run_id','request_sha256')) - if result['format'] != 'project_run_admission_v1': - raise WorkbenchError('Invalid project Run observation.') - identifier(result['origin_catalog_id'], 'Run origin');identifier(result['run_id'], 'Run ID') - if type(result['request_sha256']) is not str or not re.fullmatch('[a-f0-9]{64}', result['request_sha256']): - raise WorkbenchError('Invalid Run request digest.') - if records is not None: - matches = [item['document']['run'] for item in records if item['family'] == 'run_history' - and item['id'] == result['origin_catalog_id']+'.'+result['run_id']] - if len(matches) != 1 or _admission_result(matches[0]) != result: - raise WorkbenchError('Run operation observation differs from its retained Run.') - return True - - -class ProjectExecution: - def __init__(self, projection): - self.projection = projection - self.session, self.db = projection.session, projection.db - self.access = projection.access - self.custody = getattr(projection, 'custody', None) - local=self.custody.snapshot() if self.custody is not None else dict(runtime_effects=[],package_effects=[]) - self._runtime_pending={item['request_key']:item for item in local['runtime_effects']} - self._package_pending={item['request_key']:item for item in local['package_effects']} - self._runtime_active=self._package_active=None - self._journal_publication_pending=False - self.runtime_access = Access(self.db, self.db.path, authority=self.access) - self.session.runtime_access = self.runtime_access - self._runs = None - self._constructing = False - self._reconstructing = False - self._dirty_runs = set() - self._pending_studies = set() - self._pending_producers = {kind:set() for kind in ('generation','grounded','caption','text_proposal')} - self.study_execution = None - self.producer_execution = None - self._custody_lock = threading.RLock() - self._handles = {} - self._active_attempts = set() - from project_native_execution import ProjectNativeExecution - self.native=ProjectNativeExecution(self) - self.session.extra_capture = self.capture_dirty - if self.custody is not None:self.session.publication_intent=self._publication_intent - self.db.set_project_hooks(self.before_commit, self.outcome) - - def attach_runs(self, owner): - if not self._constructing or owner.project_execution is not self or self._runs is not None: - raise RuntimeError('Only explicit local construction can attach a Run owner.') - self._runs = owner - - @contextmanager - def _journal_guard(self): - """A failed private custody acknowledgement fences every SQL outcome.""" - try: - yield - except BaseException: - self.session.available = False - if self._runs is not None:self._runs._fence_coordinator() - raise - - def attempt_started(self, identity): - with self._custody_lock:self._active_attempts.add(identity) - - def attempt_finished(self, identity): - with self._custody_lock:self._active_attempts.discard(identity) - - def register_custody(self, identity, handle): - if handle.spec['attempt_id'] != identity: - raise RuntimeError('Current custodian differs from its Run.') - with self._custody_lock: - if identity in self._handles: - raise RuntimeError('A current Run cannot replace its custodian.') - self._handles[identity] = handle - if self.custody is not None: - from recipe_process import identity as process_identity - with self._journal_guard(): - self.custody.launched(identity,process_identity(handle.process.pid)) - - def before_launch(self, identity): - with self.db.lock: - self.session.check_current();run=self.runs._load(identity);self._proof(run) - self.runtime_access.require_job('runs',identity,run['admission_id'],run['request_sha256']) - if self.custody is not None: - with self._journal_guard():self.custody.launch_intent(identity) - - def _publication_intent(self, before, records, key, sha): - if self.custody is not None and self.custody.has_pending: - with self._journal_guard():self.custody.expect_publication(before,records,key,sha) - self._journal_publication_pending=True - - def _local_owner(self, *, recover=True): - """Construct execution only after the caller checked exact authority.""" - self.session.check_current() - if self._runs is None: - from runs import Runs - from pipeline import Pipelines - context = copy.copy(self.projection.context) - context.access, context.lock = self.runtime_access, self.db.lock - context.project_execution = self - pipelines = Pipelines(context) - context.pipelines = pipelines - self._constructing = True - try: - with self.runtime_access._reconcile(): - owner = Runs(context, pipelines, recover=recover) - finally: - self._constructing = False - self._runs = owner - context.runs = owner - return self._runs - - @property - def runs(self): - """An already activated owner, never an implicit constructor.""" - if self._runs is None: - raise WorkbenchError('No current local execution owner is active.', 'unavailable', 409) - return self._runs - - @property - def has_local_custody(self): - """Observe only current physical owners and their unresolved local index.""" - with self._custody_lock: - return (self._runs is not None or bool(self._handles) - or self.native.has_local_custody - or self.producer_execution is not None and self.producer_execution.has_local_custody - or bool(self._runtime_pending or self._package_pending or self._runtime_active or self._package_active) - or self.custody is not None and self.custody.has_pending) - - @contextmanager - def runtime_inspection(self): - with self.access.lock,self.session.lock,self.db.lock: - self.assert_quiescent() - self._runtime_active='inspection' - try:yield - finally:self._runtime_active=None - - def runtime_effect(self, request_key, input_sha256=None, manifest_sha256=None): - return self._file_effect('runtime',request_key,input_sha256,manifest_sha256) - - def package_effect(self, request_key, input_sha256=None, material_sha256=None): - return self._file_effect('package',request_key,input_sha256,material_sha256) - - @contextmanager - def package_reconciliation(self, request_key, input_sha256, material_sha256, expected_checkpoint): - """Rebind one stopped original physical package writer; never rerun it. - - The caller publishes its fixed final/abandonment fact before confirming - this guard. Imported intent alone cannot select or clear local custody. - """ - with self._file_reconciliation('package',request_key,input_sha256,material_sha256,expected_checkpoint) as effect: - yield effect - - @contextmanager - def runtime_reconciliation(self, request_key, input_sha256, manifest_sha256, expected_checkpoint): - """Hold one original stopped runtime capture for a canonical owner decision.""" - with self._file_reconciliation('runtime',request_key,input_sha256,manifest_sha256,expected_checkpoint) as effect: - yield effect - - @contextmanager - def _file_reconciliation(self, kind, request_key, input_sha256, content_sha256, expected_checkpoint): - with self.access.lock,self.session.lock,self.db.lock: - self._restore_file_writer(kind,request_key,input_sha256,content_sha256,expected_checkpoint) - if kind=='runtime':self._runtime_active=request_key - else:self._package_active=request_key - effect=_FileEffect(self,kind,request_key,input_sha256,content_sha256) - effect.started=True - try: - yield effect - finally: - if kind=='runtime':self._runtime_active=None - else:self._package_active=None - - def runtime_pending(self, request_key): - """Observe one current-host private runtime marker, never an imported intent.""" - self.access.require('admin','project_execution.runtime_pending',owner_only=True) - if type(request_key) is not str or not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}',request_key): - raise WorkbenchError('Invalid current runtime publication key.') - with self.access.lock,self.session.lock,self.db.lock: - self.access.require('admin','project_execution.runtime_pending',owner_only=True) - if self.custody is None:return None - with self._journal_guard():journal=self.custody.refresh() - return next((copy.deepcopy(entry) for entry in journal['runtime_effects'] - if entry['request_key']==request_key),None) - - def prepare_runtime_reconciliation(self, request_key, input_sha256, manifest_sha256, expected_checkpoint): - """Restore one stopped capture before an explicit normal owner retry. - - No active file guard or marker is changed. The caller must still verify - its actual target and acknowledge normal canonical completion. - """ - return self._restore_file_writer('runtime',request_key,input_sha256,manifest_sha256,expected_checkpoint) - - def _restore_file_writer(self, kind, request_key, input_sha256, content_sha256, expected_checkpoint): - # Exactly the two admitted synchronous filesystem owners share this - # physical-custody proof. There is no extensible effect registry. - if kind=='runtime': - authority,scope,action=self.access,'admin','project_execution.runtime_reconciliation' - field='manifest_sha256' - elif kind=='package': - authority,scope,action=self.runtime_access,'cancel','project_execution.package_reconciliation' - field='material_sha256' - else:raise RuntimeError('Unsupported file reconciliation owner.') - authority.require(scope,action,owner_only=True) - if type(request_key) is not str or not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}',request_key): - raise WorkbenchError('Invalid current file publication key.') - for value in (input_sha256,content_sha256,expected_checkpoint): - if type(value) is not str or not re.fullmatch('[a-f0-9]{64}',value): - raise WorkbenchError('File reconciliation requires exact input and checkpoint digests.') - with self.access.lock,self.session.lock,self.db.lock: - authority.require(scope,action,owner_only=True) - if self.db.in_transaction: - raise RuntimeError('File reconciliation requires no outer SQL transaction.') - if self.session.summary['checkpoint']!=expected_checkpoint: - raise WorkbenchError('Expected current file checkpoint changed.','stale_project',409) - if self.custody is None: - raise WorkbenchError('No original physical file custody exists.','unavailable',409) - if self._runtime_active or self._package_active: - raise WorkbenchError('A current runtime or package writer is active.','busy',409) - expected=dict(request_key=request_key,input_sha256=input_sha256,**{field:content_sha256}) - with self._journal_guard():journal=self.custody.refresh() - own,other=(('runtime_effects','package_effects') if kind=='runtime' else ('package_effects','runtime_effects')) - pending=self._runtime_pending if kind=='runtime' else self._package_pending - other_pending=self._package_pending if kind=='runtime' else self._runtime_pending - if expected not in journal[own]: - raise WorkbenchError('No exact original file writer matches this request.','unavailable',409) - if (journal['runs'] or journal['producers'] or journal.get('native_phases') or journal.get('native_admissions') or journal[other] - or journal[own]!=[expected] or other_pending - or any(key!=request_key or value!=expected for key,value in pending.items())): - raise WorkbenchError('Other original local custody remains unresolved.','outcome_unknown',409) - self._assert_run_drained() - self.native.assert_quiescent() - if self.producer_execution is not None:self.producer_execution.assert_quiescent() - binding=self.custody.binding - if (binding['projection_id']!=self.db.projection_id or binding['project_id']!=self.db.dataset_id - or binding['host_catalog_id']!=self.access.catalog_id): - raise WorkbenchError('File custody belongs to another physical owner.','local_custody_unavailable',409) - # Recovery remains fenced until every fixed inert owner has been - # reconstructed from this exact acknowledged/attempted selection. - self.session.available=False - snapshot=self.session.store.recover_checkpoint() - with self.session.store.root_directory() as descriptor: - info=os.fstat(descriptor) - if [info.st_dev,info.st_ino]!=binding['root_identity']: - raise WorkbenchError('File custody belongs to another physical root.','local_custody_unavailable',409) - self.custody.validate_selection(snapshot) - self.projection.reconcile_inert(snapshot) - pending[request_key]=expected - self.assert_quiescent(_allow_file=(kind,request_key)) - return self.session.snapshot - - @contextmanager - def _file_effect(self, kind, key, input_sha256, content_sha256): - if type(key) is not str or not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}',key): - raise WorkbenchError('Invalid current file publication key.') - for value in (input_sha256,content_sha256): - if value is not None and (type(value) is not str or not re.fullmatch('[a-f0-9]{64}',value)): - raise WorkbenchError('Invalid current file publication digest.') - with self.access.lock,self.session.lock,self.db.lock: - self.assert_quiescent(_allow_file=(kind,key)) - if kind=='runtime':self._runtime_active=key - else:self._package_active=key - effect=_FileEffect(self,kind,key,input_sha256,content_sha256) - try:yield effect - finally: - if kind=='runtime':self._runtime_active=None - else:self._package_active=None - - def mark_run(self, run_id): - identifier(run_id, 'Dirty Run ID') - if not self.db.in_transaction: - raise RuntimeError('Run changes require their owned SQL transaction.') - self._dirty_runs.add(run_id) - - def mark_study(self, study_id): - identifier(study_id, 'Dirty Study ID') - if not self.db.in_transaction: - raise RuntimeError('Study changes require their owned SQL transaction.') - if self.study_execution is None: - self._pending_studies.add(study_id) - else: - self.study_execution.mark_study(study_id) - - def _mark_producer(self, kind, identity): - identifier(identity, 'Dirty producer ID') - if not self.db.in_transaction: - raise RuntimeError('Producer changes require their owned SQL transaction.') - if self.producer_execution is None: - self._pending_producers[kind].add(identity) - else: - getattr(self.producer_execution, 'mark_'+kind)(identity) - - def mark_generation(self, identity):self._mark_producer('generation', identity) - def mark_grounded(self, identity):self._mark_producer('grounded', identity) - def mark_caption(self, identity):self._mark_producer('caption', identity) - def mark_text_proposal(self, identity):self._mark_producer('text_proposal', identity) - - def _producer_authority(self, family, identity, admission_id, request_digest): - from project_producer_execution import JOB_KINDS, FINISH - from access import current_context - if family not in JOB_KINDS:raise WorkbenchError('Unsupported producer custody family.') - row=self.db.execute('SELECT * FROM access_admissions WHERE id=%s',(admission_id,)).fetchone() - if (row is None or row['catalog_id']!=self.db.dataset_id or row['kind']!=JOB_KINDS[family] - or row['job_id']!=identity or row['request_digest']!=request_digest): - raise AccessError('Producer custody requires its exact current local admission.') - context=current_context() - if context is not None and context.mode=='job': - self.runtime_access.require_job(JOB_KINDS[family],identity,admission_id,request_digest) - self.runtime_access.require('edit',FINISH[family],identity) - elif context is not None and context.mode=='system': - self.runtime_access.require('cancel',JOB_KINDS[family]+'.reconcile',identity) - else:self.runtime_access.require('inspect','producers.custody',identity) - - def register_producer(self, family, identity, admission_id, request_digest): - with self.db.lock: - self.session.check_current();self._producer_authority(family,identity,admission_id,request_digest) - if self.custody is not None: - with self._journal_guard(): - if not self.custody.has_pending:self.custody.acknowledge(self.session.snapshot) - self.custody.register_producer(family,identity,admission_id,request_digest) - - def producer_effect_intent(self, family, identity): - with self.db.lock: - self.session.check_current() - if self.custody is not None: - value=next((item for item in self.custody.snapshot()['producers'] - if (item['family'],item['producer_id'])==(family,identity)),None) - if value is None:raise AccessError('Provider dispatch has no original-host custody admission.') - self._producer_authority(family,identity,value['admission_id'],value['request_sha256']) - with self._journal_guard():self.custody.producer_effect_intent(family,identity) - - def update_producer_outcome(self, family, identity, provider_outcome, worker_drained): - with self.db.lock: - self.session.check_current() - if self.custody is not None: - value=next((item for item in self.custody.snapshot()['producers'] - if (item['family'],item['producer_id'])==(family,identity)),None) - if value is None:return - self._producer_authority(family,identity,value['admission_id'],value['request_sha256']) - with self._journal_guard():self.custody.producer_outcome(family,identity,provider_outcome,worker_drained) - - def _proof(self, run): - admission = self.db.execute('SELECT * FROM access_admissions WHERE id=%s', (run['admission_id'],)).fetchone() - if admission is None: - raise AccessError('Current local Run admission is unavailable.') - admission = dict(admission) - admission['effects'] = json.loads(admission.pop('effects_json')) - if (admission['catalog_id'] != self.db.dataset_id or admission['kind'] != 'runs' - or admission['job_id'] != run['id'] or admission['request_digest'] != run['request_sha256']): - raise AccessError('Current local admission differs from its Run.') - grant = consumption = None - if run.get('execution_kind') == 'external_recipe': - grant = self.db.execute('SELECT * FROM access_execution_grants WHERE id=%s', (run['approval_id'],)).fetchone() - consumption = self.db.execute('SELECT * FROM access_execution_consumptions WHERE grant_id=%s', (run['approval_id'],)).fetchone() - if grant is None or consumption is None: - raise AccessError('Current local execution consumption is unavailable.') - return dict(grant=dict(grant) if grant is not None else None, - consumption=dict(consumption) if consumption is not None else None, admission=admission) - - def _authorize_observation(self): - self.native.authorize_dirty() - context = self.runtime_access._context() if self._dirty_runs else None - for identity in self._dirty_runs: - row = self.db.execute('SELECT document FROM workspace_runs WHERE id=%s', (identity,)).fetchone() - if row is None: - raise AccessError('Current local Run is unavailable.') - run = json.loads(row['document']) - proof = self._proof(run) - if context.mode == 'job': - self.runtime_access.require_job('runs', identity, run['admission_id'], run['request_sha256']) - self.runtime_access.require('edit', 'runs.update', identity) - elif context.mode == 'system': - if self._runs is None and not self._constructing: - raise AccessError('Reconciliation requires the current local execution owner.') - if not self._runs.runtime_owner or not self.db.runtime_owned('workspace_runs'): - raise AccessError('Current local runtime custody ownership is unavailable.') - self.runtime_access.require('cancel', 'runs.reconcile', identity) - else: - # The domain owner has already checked submit/cancel authority; - # recheck live host credentials without inventing a worker owner. - self.runtime_access.require('inspect', 'runs.observe', identity) - if proof['admission']['catalog_id'] != self.session.summary['project_id']: - raise AccessError('Local custody belongs to another project.') - - def _capture_run(self, identity): - owner = self.runs - run = owner._load(identity) - proof = self._proof(run) - payloads = owner._capture_project_payloads(run, self.session.artifacts) - record = capture_run(run, admission_proof=proof, payloads=payloads) - records = [record, *declarations(record)] - if run.get('execution_kind') == 'external_recipe': - environment = run['material'].get('torch_runtime', run['material'].get('cpu_snapshot', run['material']['runtime'])) - descriptor = environment if environment.get('profile') in ('captured_cpu_python_v1','managed_torch_python_v1') else None - sha = digest(environment) - ref = dict(kind='runtime', catalog_id=run['dataset_id'], id=sha, sha256=sha) - from project_material import decode_records - if ('runtime_material', ref['catalog_id']+'.'+sha) not in decode_records(self.session.snapshot['records']): - raw = self.projection.runtime_manifest(descriptor) if descriptor is not None else None - manifest = None - if raw is not None: - from recipe_process import decode - manifest = decode(raw) - runtime = self.projection.materials.capture_runtime(dict(ref=ref, descriptor=descriptor, - environment=None if descriptor is not None else environment, manifest=manifest), raw) - records.extend([runtime, *self.projection.materials.declarations(runtime)]) - if self.custody is not None and run.get('execution_kind')=='external_recipe': - with self._journal_guard(): - if not self.custody.has_pending:self.custody.acknowledge(self.session.snapshot) - receipt=next((edge['blob']['sha256'] for edge in payloads if edge['name']=='custody-receipt.json'),None) - self.custody.observe_run(run,receipt_sha256=receipt) - elif self.custody is not None: - with self._journal_guard(): - if not self.custody.has_pending:self.custody.acknowledge(self.session.snapshot) - if run['state'] in ('queued','running','cancelling','unknown'): - self.custody.observe_native_admission(run) - return records - - def capture_dirty(self, before_records): - """The finite owner capture seam used by foreground and background TXs.""" - if self._reconstructing: - return [] - if self._pending_studies or any(self._pending_producers.values()): - raise WorkbenchError('The changed execution family has no installed capture owner.', 'unavailable', 409) - if self.study_execution is not None: - self.study_execution.settle_runs(self._dirty_runs) - self._authorize_observation() - records = [] - for identity in sorted(self._dirty_runs): - records.extend(self._capture_run(identity)) - if self.study_execution is not None: - records.extend(self.study_execution.capture_dirty(before_records)) - if self.producer_execution is not None: - records.extend(self.producer_execution.capture_dirty(before_records)) - records.extend(self.native.capture_dirty(before_records)) - # Shared immutable blobs can appear on several domain edges. - merged = {} - for record in records: - identity = record['family'], record['id'] - if identity in merged and merged[identity] != record: - raise WorkbenchError('Execution captures disagree on shared project facts.') - merged[identity] = record - return list(merged.values()) - - def _capture_pending(self): - """Whether capture_dirty could return any record (see its owners).""" - if self._dirty_runs or self._pending_studies or any(self._pending_producers.values()) or self.native.has_dirty: - return True - study = self.study_execution - if study is not None and (study._dirty or study._package_records): - return True - producers = self.producer_execution - if producers is not None and (producers._runtime_data is not None or any(producers._dirty.values())): - return True - return False - - def before_commit(self): - if self._reconstructing or self.session.foreground_publication: - return - if not self._dirty_runs and not self._pending_studies and not any(self._pending_producers.values()) and not self.native.has_dirty and self.study_execution is None and self.producer_execution is None: - return - if not self._capture_pending(): - # Nothing can be captured; never materialize the record set. - return - snapshot = self.session.snapshot - records = self.capture_dirty(snapshot['records']) - if records: - key = 'execution-observation-' + uuid.uuid4().hex - sha = hashlib.sha256(agent_api.encoded(records)).hexdigest() - self.session._publish_observation(records, key, sha, authorize=self._authorize_observation) - - def outcome(self, outcome): - if outcome not in ('committed','rolled_back','unknown'): - raise ValueError('Unsupported project SQL outcome.') - if self._reconstructing: - return - self.session._observation_outcome(outcome) - self.native.outcome(outcome) - if self.custody is not None and outcome=='committed': - try: - if self._journal_publication_pending:self.custody.acknowledge(self.session.snapshot) - for identity in sorted(self._dirty_runs): - run=self.runs._load(identity) - self.native.settle_run(run) - if run.get('execution_kind')!='external_recipe' and run['state'] in ('completed','failed','cancelled','interrupted'): - if any(row['run_id']==identity for row in self.custody.snapshot().get('native_admissions',[])): - self.custody.settle_native_admission(identity) - entry=next((item for item in self.custody.snapshot()['runs'] if item['run_id']==identity),None) - if entry is not None and run['state'] in ('completed','failed','cancelled','interrupted') and ( - run['custody_phase']=='drained' and entry['receipt_sha256'] is not None - or entry['phase']=='admitted' and run.get('custody_identity') is None): - self.custody.settle_run(identity) - except BaseException: - self.session.available=False - if self._runs is not None:self._runs._fence_coordinator() - raise - self._journal_publication_pending=False - self._dirty_runs.clear();self._pending_studies.clear() - for values in self._pending_producers.values():values.clear() - for adapter in (self.study_execution, self.producer_execution): - if adapter is not None:adapter.outcome(outcome) - if outcome == 'unknown':self.session.available = False - if not self.session.available: - if self._runs is not None:self._runs._fence_coordinator() - - def abandon_pending(self): - """Discard failed capture bookkeeping, never an admission or grant.""" - if not self._reconstructing: - raise RuntimeError('Pending execution capture may clear only during guarded inert reconstruction.') - self._dirty_runs.clear();self._pending_studies.clear() - self.native.abandon_pending() - for values in self._pending_producers.values():values.clear() - - def mutate(self, operation, target, body, expected_checkpoint, key, invoke, capture, *, scope='edit'): - try: - return self.session.mutate(operation, target, body, expected_checkpoint, key, invoke, capture, scope=scope) - except BaseException: - if not self.session.available and self._runs is not None:self._runs._fence_coordinator() - raise - - def preflight_external(self, graph_id, revision): - self.runtime_access.require('inspect', 'pipeline.preflight_external', graph_id) - with self.access.lock, self.session.lock, self.db.lock: - self.session.check_current() - return self.projection.pipelines.preflight_external(graph_id, revision) - - def native_preflight(self,graph_id,revision,expected_checkpoint,key): - self.runtime_access.require('execute','runs.native_preflight',graph_id,owner_only=True) - return self.projection.native_preparation.validate_graph(self.projection.pipelines, - graph_id,revision,expected_checkpoint,key) - - def _native_replay(self,operation,target,body,expected_checkpoint,key): - prior=session_operations(self.session).get(key) - if prior is None:return None - if (prior['operation']!=operation or self.db.execute('SELECT id FROM workspace_runs WHERE id=%s', - (prior['result'].get('run_id'),)).fetchone() is None): - raise WorkbenchError('A retained native receipt cannot create current local execution.','unavailable',409) - def forbidden():raise RuntimeError('Native admission replay attempted another qualification.') - return self.mutate(operation,target,body,expected_checkpoint,key,forbidden, - lambda value,before:dict(records=[],result=value),scope='execute') - - def native_submit(self,body,expected_checkpoint,key): - from pipeline import closed - closed(body,('graph_id','graph_revision','validation_token')) - actor=self.runtime_access.require('execute','runs.submit',body['graph_id'],owner_only=True) - effective=dict(body,actor_id=actor.actor_id) - with self.db.lock: - self.session.check_current() - replay=self._native_replay('runs.submit',body['graph_id'],effective,expected_checkpoint,key) - if replay is not None:return replay - with self.projection.native_preparation.current_graph(self.projection.pipelines,body['graph_id'], - body['graph_revision'],expected_checkpoint,key) as context: - if context.validation['validation_token']!=body['validation_token']: - raise WorkbenchError('Native validation is stale. Explicitly validate this saved graph.','stale',409) - def invoke(): - context.consume_admission() - owner=self._local_owner();public=owner.submit(dict(body,request_key=key)) - return _admission_result(owner._load(public['id'])) - return self.mutate('runs.submit',body['graph_id'],effective,self.session.summary['checkpoint'],key, - invoke,lambda value,before:dict(records=[],result=value),scope='execute') - - def native_retry(self,run_id,expected_checkpoint,key): - actor=self.runtime_access.require('execute','runs.retry',run_id,owner_only=True) - body=dict(actor_id=actor.actor_id) - with self.db.lock: - self.session.check_current() - replay=self._native_replay('runs.retry',run_id,body,expected_checkpoint,key) - if replay is not None:return replay - if self._runs is None:raise WorkbenchError('Retry requires the actual current local Run owner.','unavailable',409) - parent=self._runs._load(run_id) - if self._runs._external(parent) or parent['state'] not in ('failed','cancelled','interrupted'): - raise WorkbenchError('Choose a drained failed/cancelled/interrupted current native Run.','conflict',409) - with self.projection.native_preparation.current_graph(self.projection.pipelines,parent['graph']['id'], - parent['graph_revision'],expected_checkpoint,key) as context: - def invoke(): - context.consume_admission() - owner=self.runs;public=owner.retry(run_id,dict(request_key=key)) - return _admission_result(owner._load(public['id'])) - return self.mutate('runs.retry',run_id,body,self.session.summary['checkpoint'],key, - invoke,lambda value,before:dict(records=[],result=value),scope='execute') - - def native_reconcile(self,phase_id,expected_checkpoint): - return self.native.reconcile(phase_id,expected_checkpoint) - - def submit_external(self, body, expected_checkpoint, key): - authority = self.runtime_access.require_external_submission() - with self.access.lock, self.session.lock, self.db.lock: - self.session.check_current() - prior = session_operations(self.session).get(key) - if prior is None and expected_checkpoint != self.session.summary['checkpoint']: - raise WorkbenchError('Expected project checkpoint changed.', 'stale_project', 409) - if prior is not None: - # A retained request never recreates a local Run/admission or wakes - # imported queue state. A same-host local receipt can reconcile. - result = prior['result'] - if (prior['operation'] != 'runs.submit_external' or - self.db.execute('SELECT id FROM workspace_runs WHERE id=%s', (result.get('run_id'),)).fetchone() is None): - raise WorkbenchError('This saved request has no current local Run admission.', 'unavailable', 409) - request = dict(body, request_key=key) - def invoke(): - owner = self._local_owner() - public = owner.submit_external(request) - return _admission_result(owner._load(public['id'])) - effective = dict(body, actor_id=authority.actor_id) - return self.mutate('runs.submit_external', body.get('graph_id'), effective, expected_checkpoint, key, - invoke, lambda value,before:dict(records=[], result=value), scope='inspect') - - def approve_external(self, body, expected_checkpoint, key): - authority = self.runtime_access.require('approve-execution', 'runs.approve_external', owner_only=True) - with self.access.lock, self.session.lock, self.db.lock: - self.session.check_current() - prior = session_operations(self.session).get(key) - if prior is None and expected_checkpoint != self.session.summary['checkpoint']: - raise WorkbenchError('Expected project checkpoint changed.', 'stale_project', 409) - if prior is not None: - value = prior['result'] - if prior['operation'] != 'runs.approve_external' or self.db.execute( - 'SELECT id FROM access_execution_grants WHERE id=%s', (value.get('approval_id'),)).fetchone() is None: - raise WorkbenchError('This approval is historical; approve explicitly under current authority.', 'unavailable', 409) - def invoke(): - owner = self._local_owner() - grant = owner.approve_external(body) - return dict(format='project_execution_approval_v1', origin_catalog_id=grant['catalog_id'], - approval_id=grant['id'], **{key:grant[key] for key in ('material_sha256','consumer_actor_id', - 'approver_actor_id','created_at','expires_at')}) - effective = dict(body, approver_actor_id=authority.actor_id) - value = self.mutate('runs.approve_external', body.get('graph_id'), effective, expected_checkpoint, key, - invoke, lambda result,before:dict(records=[], result=result), scope='approve-execution') - grant = self.db.execute('SELECT * FROM access_execution_grants WHERE id=%s', (value['approval_id'],)).fetchone() - if grant is None: - raise WorkbenchError('Current local execution approval is unavailable.', 'unavailable', 409) - fields = ('material_sha256','consumer_actor_id','approver_actor_id','created_at','expires_at') - if (grant['catalog_id'] != value['origin_catalog_id'] or grant['id'] != value['approval_id'] - or any(grant[field] != value[field] for field in fields) - or grant['approver_actor_id'] != authority.actor_id or grant['revoked_at'] is not None - or grant['expires_at'] <= int(time.time())): - raise WorkbenchError('This historical approval has no exact current live grant. Use a fresh key.', 'unavailable', 409) - return dict(format='project_current_execution_approval_v1', current_local=True, grant=dict(grant)) - - def cancel_run(self, run_id, expected_checkpoint, key): - self.runtime_access.require('cancel', 'runs.cancel', run_id) - with self.access.lock, self.session.lock, self.db.lock: - if self._runs is None or self.db.execute('SELECT id FROM workspace_runs WHERE id=%s', (run_id,)).fetchone() is None: - raise WorkbenchError('A historical Run has no current local process to cancel.', 'unavailable', 409) - def invoke(): - self.runs.cancel(run_id) - return _admission_result(self.runs._load(run_id)) - return self.mutate('runs.cancel', run_id, {}, expected_checkpoint, key, invoke, - lambda result,before:dict(records=[], result=result), scope='cancel') - - def health(self, offset=0, limit=40): - self.access.require('inspect', 'project_execution.health') - natural(offset,'Execution offset',0,100000);natural(limit,'Execution limit',1,40) - with self.db.lock: - rows = [json.loads(row['document']) for row in self.db.execute('SELECT document FROM workspace_runs')] - active = {row['id'] for row in rows if row['state'] in ('queued','running','cancelling','unknown')} - with self._custody_lock:active.update(self._active_attempts) - native=self.custody.snapshot().get('native_phases',[]) if self.custody is not None else [] - native=sorted(native,key=lambda item:item['phase_id']) - phases=[dict(format='project_native_phase_v1',origin_catalog_id=self.db.dataset_id, - phase_id=item['phase_id'],phase=item['phase'],run_id=item['run_id'], - state='prepared' if item['state'] in ('launch_intent','launched') else item['state'], - spec_sha256=item['spec_sha256'],receipt_sha256=item['receipt_sha256']) for item in native[offset:offset+limit]] - return dict(format='project_execution_health_v1', active_run_ids=sorted(active)[offset:offset+limit], - active_count=len(active), offset=offset, limit=limit, - native_phases=dict(items=phases,total=len(native),offset=offset,limit=limit), - local_owner_active=self._runs is not None, - available=self.session.available and self.db.dataset_id != self.access.catalog_id, - drain_required=bool(self.custody is not None and self.custody.has_pending - or self.native.has_local_custody - or self._runtime_active or self._package_active - or self._runs is not None and self._runs._thread is not None and self._runs._thread.is_alive())) - - def assert_quiescent(self, *, _allow_file=None): - with self.db.lock: - if not self.session.available: - raise WorkbenchError('Current execution outcome requires explicit reconciliation.', 'projection_unavailable', 503) - if self._runtime_active or self._package_active: - raise WorkbenchError('A current runtime or package file writer is active.','busy',409) - for kind,pending in (('runtime',self._runtime_pending),('package',self._package_pending)): - if any(_allow_file!=(kind,key) for key in pending): - raise WorkbenchError('A current runtime or package publication requires exact reconciliation.','outcome_unknown',409) - self._assert_run_drained() - self.native.assert_quiescent() - for adapter in (self.study_execution,self.producer_execution): - if adapter is not None:adapter.assert_quiescent() - if self.custody is not None: - journal=self.custody.snapshot() - if journal['runs'] or journal['producers'] or journal.get('native_phases') or journal.get('native_admissions'): - raise WorkbenchError('Original local custody remains unresolved.','outcome_unknown',409) - - def _assert_run_drained(self): - """Check only actual current Run effects, including an idle supervisor.""" - rows = self.db.execute("SELECT id FROM workspace_runs WHERE document::jsonb->>'state' IN ('queued','running','cancelling','unknown')").fetchall() - if rows: - raise WorkbenchError('Drain or cancel current local Runs before closing or copying this project.', 'busy', 409) - with self._custody_lock: - if self._active_attempts or any(handle.process.poll() is None for handle in self._handles.values()): - raise WorkbenchError('Current local custodians are still draining.', 'busy', 409) - if self._runs is not None and self._runs._thread is not None and self._runs._thread.is_alive(): - raise WorkbenchError('Reconcile current local custody to stop its idle supervisor before closing.', 'busy', 409) - if self._runs is not None and (self._runs._publication_active is not None or self._runs._publication_lock.locked()): - raise WorkbenchError('Current Run publication has not drained.', 'busy', 409) - - def close(self): - if not self.has_local_custody: - return - self.assert_quiescent() - if self._runs is not None: - with self.runtime_access._reconcile():self._runs.close() - if self.producer_execution is not None:self.producer_execution.close() - - def shutdown(self): - """Explicit application shutdown, outside project command locks. - - Existing local continuations own cancellation and final observations. - This neither constructs an owner nor creates human execution authority. - """ - if self.db.lock.owned_by_current_thread or self.db.in_transaction: - raise WorkbenchError('Shutdown must drain outside the project command lock.', 'busy', 409) - try: - if self._runs is not None: - with self.runtime_access._reconcile():self._runs.close() - finally: - if self.producer_execution is not None:self.producer_execution.shutdown() - - def reconcile_current(self): - """Reconcile only retained current-local custody, never imported handles.""" - self.runtime_access.require('cancel', 'project_execution.reconcile', owner_only=True) - self._require_no_native_phase_reconciliation() - if self._runs is None: - raise WorkbenchError('No current local custody owner exists to reconcile.', 'unavailable', 409) - if self.db.lock.owned_by_current_thread or self.db.in_transaction: - raise WorkbenchError('Drain current custody outside the project command lock.', 'busy', 409) - owner = self._runs - owner._fence_coordinator() - with self._custody_lock:handles = dict(self._handles) - receipts = {} - # Only actual Handle objects retained by this application's launch path - # close control channels. Saved PID/spec/receipt text never selects one. - for identity, handle in handles.items(): - receipt = handle.close_control() - if not receipt or not receipt.get('drained'): - raise WorkbenchError('Current custodian drainage is still unconfirmed.', 'unknown', 409) - receipts[identity] = receipt - deadline = time.monotonic() + 60 - thread = owner._thread - if thread is not None: - thread.join(max(0, deadline-time.monotonic())) - if thread.is_alive(): - raise WorkbenchError('Current execution supervisor has not drained.', 'busy', 409) - with self._custody_lock: - if self._active_attempts: - raise WorkbenchError('Current execution attempts have not drained.', 'busy', 409) - if self.producer_execution is not None:self.producer_execution.assert_quiescent() - with self.access.lock, self.session.lock, self.db.lock: - self.runtime_access.require('cancel','project_execution.reconcile',owner_only=True) - self._require_no_native_phase_reconciliation() - snapshot = self.session.store.recover_checkpoint() - self.projection.reconcile_inert(snapshot) - canonical = {item['document']['run']['id']:item['document']['run'] for item in snapshot['records'] - if item['family']=='run_history' and item['document']['origin_catalog_id']==self.db.dataset_id} - reconciled = [] - try: - with self.runtime_access._reconcile(), self.db.transaction(): - for row in self.db.execute('SELECT id FROM workspace_runs'): - local = owner._load(row['id']) - if local['state'] not in ('queued','running','cancelling','unknown'): - continue - self._proof(local) - retained = canonical.get(local['id']) - if retained is None or any(retained.get(key)!=local.get(key) for key in ( - 'dataset_id','id','request_sha256','admission_id','approval_id','material_sha256','spec')): - raise WorkbenchError('Current local admission differs from canonical custody.', 'unknown', 409) - run = copy.deepcopy(retained) - handle = handles.get(run['id']) - if run.get('execution_kind')!='external_recipe': - # No native phase can launch without first entering - # the private phase journal. A drained original - # supervisor plus a never-started native admission - # may therefore terminate without inventing receipt - # or interpreting an external custody specification. - self._native_never_started(local,retained) - owner._event(run,'interrupted','Original native admission ended before phase dispatch; execution was not replayed.') - from runs import LOCAL_RUN_FIELDS - run.update({key:copy.deepcopy(value) for key,value in local.items() if key in LOCAL_RUN_FIELDS}) - owner._save(run);reconciled.append(run['id']);continue - if handle is None: - if run['custody_phase']!='prepared' or run.get('custody_identity') is not None: - raise WorkbenchError('Canonical execution has no current local custody proof.', 'unknown', 409) - state = 'cancelled' - else: - receipt = receipts[run['id']] - if (handle.expected_identity['attempt_id']!=run['id'] or - handle.expected_identity['request_sha256']!=run['request_sha256'] or - run.get('custody_identity') not in (None,handle.expected_identity)): - raise WorkbenchError('Current custodian differs from its canonical admission.', 'unknown', 409) - run['custody_identity'] = copy.deepcopy(handle.expected_identity) - run['custody_phase'] = 'drained' - if run['state']=='completed': - owner._verify_external_artifacts(run) - state = 'completed' - else: - state = 'cancelled' if receipt['outcome']=='cancelled' else 'interrupted' - owner._event(run,state,'Explicit current-host reconciliation confirmed custody drainage; execution was not replayed.') - owner._save(run) - reconciled.append(run['id']) - # A foreground canonical admission may have survived a rolled - # back SQL admission. Clearing that original non-effect intent - # neither restores SQL authority nor rewrites historical state. - for entry in self.custody.snapshot().get('native_admissions',[]) if self.custody is not None else []: - if self.db.execute('SELECT id FROM workspace_runs WHERE id=%s',(entry['run_id'],)).fetchone() is None: - self._native_unacknowledged(entry,canonical.get(entry['run_id'])) - with self._journal_guard():self.custody.settle_native_admission(entry['run_id']) - self.assert_quiescent() - except BaseException: - self.session.available = False - owner._fence_coordinator() - raise - return dict(format='project_execution_reconciliation_v1', origin_catalog_id=self.db.dataset_id, - run_ids=sorted(reconciled), available=self.session.available) - - def _require_no_native_phase_reconciliation(self): - if self.native.has_local_custody or self.custody is not None and self.custody.snapshot().get('native_phases'): - raise WorkbenchError('Reconcile the exact current native phase with native_reconcile before generic Run reconciliation.','unavailable',409) - - def _native_never_started(self,local,retained): - """Prove absence of phase dispatch from the original private journal.""" - entry=next((row for row in self.custody.snapshot().get('native_admissions',[]) - if row['run_id']==local['id']),None) if self.custody is not None else None - if (entry is None or entry['phase_started'] or local.get('process_phase')!='not_started' - or local.get('worker') is not None or local.get('execution_kind')=='external_recipe' - or any(retained.get(key)!=local.get(key) for key in - ('id','dataset_id','admission_id','request_sha256','graph_sha256','release_sha256','runtime')) - or entry['admission_id']!=local['admission_id'] or entry['request_sha256']!=local['request_sha256'] - or entry['graph_sha256']!=local['graph_sha256'] or entry['release_sha256']!=local['release_sha256'] - or entry['runtime_sha256']!=digest(local['runtime'])): - raise WorkbenchError('Native admission lacks original never-dispatched phase proof.','unknown',409) - - def _native_unacknowledged(self,entry,retained): - if entry['phase_started']: - raise WorkbenchError('A native phase may have dispatched; its current receipt is required.','unknown',409) - if self.db.execute('SELECT id FROM access_admissions WHERE id=%s',(entry['admission_id'],)).fetchone() is not None: - raise WorkbenchError('An incomplete original native SQL admission needs investigation.','unknown',409) - if retained is not None and (retained.get('execution_kind')=='external_recipe' or retained['state']!='queued' - or any(entry[key]!=retained[key] for key in ('admission_id','request_sha256','graph_sha256','release_sha256')) - or entry['runtime_sha256']!=digest(retained['runtime'])): - raise WorkbenchError('Original unacknowledged native admission differs from canonical history.','unknown',409) - - def reconcile_original(self, *, expected_checkpoint, timeout=15): - """Explicit original-host receipt reconciliation, without PID control. - - The Workspace supplies only an indexed existing physical projection. - Imported history never selects that projection or creates admissions. - No Run owner exists until all journal/local-SQL/receipt proofs pass. - """ - self.runtime_access.require('cancel','project_execution.reconcile_original',owner_only=True) - self._require_no_native_phase_reconciliation() - if self.custody is None or self._runs is not None: - raise WorkbenchError('Original custody requires its indexed inactive physical projection.','local_custody_unavailable',409) - if self.db.lock.owned_by_current_thread or self.db.in_transaction: - raise WorkbenchError('Original custody must drain outside command locks.','busy',409) - if type(timeout) not in (int,float) or not 0<=timeout<=30: - raise WorkbenchError('Original receipt wait must be zero through thirty seconds.') - journal=self.custody.snapshot();snapshot=self.session.store.recover_checkpoint() - if snapshot['checkpoint']!=expected_checkpoint: - raise WorkbenchError('Expected original project checkpoint changed.','stale_project',409) - self.custody.validate_selection(snapshot) - canonical={item['document']['run']['id']:item['document']['run'] for item in snapshot['records'] - if item['family']=='run_history' and item['document']['origin_catalog_id']==self.db.dataset_id} - plans=[];unacknowledged=[];receipts={} - with self.db.lock: - if (journal['runs'] or journal.get('native_admissions')) and not self.db.claim_runtime('workspace_runs'): - raise WorkbenchError('The original Run application still owns this physical projection.','busy',409) - from project_producer_execution import TABLES as PRODUCER_TABLES - for producer in journal['producers']: - if not self.db.claim_runtime(PRODUCER_TABLES[producer['family']]): - raise WorkbenchError('An original producer application still owns this physical projection.','busy',409) - if producer['phase']!='admitted' or producer['provider_outcome']!='not_admitted': - raise WorkbenchError('Original provider outcome remains unknown; a closed local worker is not cessation proof.','outcome_unknown',409) - for entry in journal['runs']: - row=self.db.execute('SELECT document FROM workspace_runs WHERE id=%s',(entry['run_id'],)).fetchone() - if row is None: - if entry['phase']!='admitted': - raise WorkbenchError('Launched custody has no original local admission.','local_custody_unavailable',409) - unacknowledged.append(entry['run_id']);continue - local=json.loads(row['document']);retained=canonical.get(entry['run_id']) - self._proof(local) - from recipe_process import encoded - if (retained is None or local['id']!=entry['run_id'] or local['admission_id']!=entry['admission_id'] - or local['request_sha256']!=entry['request_sha256'] or local['dataset_id']!=self.db.dataset_id - or hashlib.sha256(encoded(local['spec'])).hexdigest()!=entry['spec_sha256'] - or any(retained.get(key)!=local.get(key) for key in ( - 'id','dataset_id','admission_id','request_sha256','approval_id','material_sha256','spec')) - or local['spec']['cwd']!=str(self.db.path/'workspace-runs'/('.external-'+local['id']))): - raise WorkbenchError('Original local admission/specification differs from its indexed canonical observation.','local_custody_unavailable',409) - if entry['phase']!='admitted' and entry['custody_identity'] is None: - raise WorkbenchError('Original spawn window lacks an observed helper identity; cessation remains unknown.','unknown',409) - plans.append((entry,copy.deepcopy(retained))) - native_plans=[] - for entry in journal.get('native_admissions',[]): - row=self.db.execute('SELECT document FROM workspace_runs WHERE id=%s',(entry['run_id'],)).fetchone() - if row is None: - self._native_unacknowledged(entry,canonical.get(entry['run_id'])) - unacknowledged.append(entry['run_id']);continue - local=json.loads(row['document']);retained=canonical.get(entry['run_id']) - self._proof(local) - if retained is None:raise WorkbenchError('Original native Run is missing its canonical admission.','unknown',409) - self._native_never_started(local,retained) - native_plans.append((local,copy.deepcopy(retained))) - # Poll only exact original local receipt files. Never signal a stored PID, - # import a controller handle, replay GO or execute a project script. - if any(entry['custody_identity'] is not None for entry,run in plans): - from projects import Projects - from recipe_process import validate_receipt - reader=Projects(self.projection.context,{'original_runs':self.db.path/'workspace-runs'}) - deadline=time.monotonic()+timeout - try: - for entry,run in plans: - if entry['custody_identity'] is None:continue - while True: - try: - raw=reader._read('original_runs','.external-'+run['id']+'/custody/receipt.json',16384) - receipt=validate_receipt(raw,entry['custody_identity']) - if not receipt['drained']: - raise WorkbenchError('Original custodian has not established drainage.','unknown',409) - receipts[run['id']]=receipt;break - except FileNotFoundError: - if time.monotonic()>=deadline: - raise WorkbenchError('Original exact drain receipt is not available yet.','unknown',409) from None - time.sleep(min(.1,max(0,deadline-time.monotonic()))) - finally:reader.close() - with self.access.lock,self.session.lock,self.db.lock: - self.runtime_access.require('cancel','project_execution.reconcile_original',owner_only=True) - self.custody.validate_selection(self.session.store.snapshot()) - self.projection.reconcile_inert(snapshot) - owner=self._local_owner(recover=False) if plans or native_plans else None - if owner is not None:owner._fence_coordinator() - try: - if owner is not None: - # Verification uses the current human's existing disclosure - # policy. The following system scope owns only terminal SQL. - for entry,run in plans: - if run['state']=='completed':owner._verify_external_artifacts(run) - with self.runtime_access._reconcile(),self.db.transaction(): - for entry,run in plans: - if entry['custody_identity'] is not None: - run['custody_identity']=copy.deepcopy(entry['custody_identity']);run['custody_phase']='drained' - state=run['state'] if run['state']=='completed' else ( - 'cancelled' if receipts[run['id']]['outcome']=='cancelled' else 'interrupted') - else:state='cancelled' - owner._event(run,state,'Original-host exact local custody reconciled; execution was not resumed.') - owner._save(run) - for local,run in native_plans: - from runs import LOCAL_RUN_FIELDS - run.update({key:copy.deepcopy(value) for key,value in local.items() if key in LOCAL_RUN_FIELDS}) - owner._event(run,'interrupted','Original native admission ended before phase dispatch; execution was not resumed.') - owner._save(run) - for identity in unacknowledged: - if any(row['run_id']==identity for row in journal.get('native_admissions',[])): - self.custody.settle_native_admission(identity) - else:self.custody.settle_run(identity) - for producer in journal['producers']: - self.custody.producer_outcome(producer['family'],producer['producer_id'],'not_admitted',True) - self.custody.acknowledge(self.session.snapshot) - except BaseException: - self.session.available=False - if owner is not None:owner._fence_coordinator() - raise - return dict(format='project_execution_reconciliation_v1',origin_catalog_id=self.db.dataset_id, - run_ids=sorted([run['id'] for entry,run in plans]+[run['id'] for local,run in native_plans]),available=self.session.available) diff --git a/project_extraction.py b/project_extraction.py deleted file mode 100644 index 461b0d0f..00000000 --- a/project_extraction.py +++ /dev/null @@ -1,836 +0,0 @@ -"""Finite read-only legacy capture for an explicitly selected project. - -The caller owns the repeatable-read PostgreSQL transaction, pinned directory -capabilities and stopped-source proof. This module never opens a catalog, -constructs runtime owners, enrolls records or writes source metadata. Scientific -shapes are admitted by their existing project/domain codecs. Missing observations -are reported; they are never replaced with invented history or regenerated bytes. -""" -import copy -from collections import deque -from datetime import datetime, timezone -import hashlib -import json -from types import SimpleNamespace - -from workbench import Workbench, WorkbenchError -import project_data as data_codec -import project_material as material_codec -import project_history as history_codec -import project_producers as producer_codec -from projects import decode_retained_snapshot, decode_retained_manifest, decode as decode_manifest, relative_path -from project_files import file_id, MAX_FILE_BYTES - -MAX_PAYLOAD = 40 * 1024 * 1024 -MAX_RECORDS = 100000 -ROOT_FAMILIES = { - 'records': 'workbench_record', 'responses': 'workbench_response', - 'preferences': 'workbench_preference', 'selections': 'saved_selection', - 'searches': 'saved_search', 'graphs': 'pipeline_graph', - 'recipe_drafts': 'recipe_definition', 'model_definitions': 'model_definition', - 'studies': 'study_history', 'runs': 'run_history', 'releases': 'dataset_release', - 'exposures': 'dataset_exposure', 'model_materials': 'model_material', - 'recipe_materials': 'recipe_material', 'runtime_materials': 'runtime_material', -} -PRODUCERS = {'generation': 'generation_history', 'grounded': 'grounded_history', - 'caption': 'caption_proposal_history', 'text_proposal': 'text_proposal_history'} -NAMESPACED = frozenset(material_codec.FAMILIES) | frozenset(history_codec.FAMILY_FORMATS) | frozenset(producer_codec.FAMILIES) - - -def _json(value): - return json.loads(value) if isinstance(value, str) else copy.deepcopy(value) - - -def _missing(detail): - raise WorkbenchError(detail, 'missing_source', 409) - - -class _ReadAccess: - """An internal read-view guard, never an imported actor or grant.""" - def require(self, scope, *args, **kwargs): - if scope != 'inspect': - raise WorkbenchError('Extraction source views are read-only.', 'forbidden', 403) - def audit(self, *args, **kwargs): - raise WorkbenchError('Extraction cannot append source audit.', 'forbidden', 403) - - -class _Capture: - def __init__(self, source): - self.source, self.db = source, source.db - self.origin = data_codec.identity(self.db.dataset_id) - self.records, self.inventory, self.dependencies = {}, {}, {} - self.blockers, self.warnings, self.working_files = [], [], [] - # Preserve emitted order without scanning prior runtime diagnostics. - self._issue_keys = {False: set(), True: set()} - self.anchor = None - self.queue, self.visited, self.queued = deque(), set(), set() - self.snapshot_by_id = {} - self.raw_cache = {} - self.payload_gaps = [] - self.deleted_intents = set() - self.session = SimpleNamespace(snapshot=source.snapshot, db=self.db, - artifacts=source.artifacts, check_current=lambda: None) - # Workbench and each metadata-view constructor only assign references; - # none runs SQL, creates directories or constructs Dataset/Jobs/Runs. - # Never call get/history: those public owners may enroll images. - dataset = SimpleNamespace(db=self.db, lock=self.db.lock, access=_ReadAccess(), - path=self.db.path, project_sources={}, project_availability=self._available) - self.reader = Workbench(dataset) - # Scientific metadata must use the caller's pinned catalog FD reader. - self.reader.scientific._capture = lambda identity: self._catalog_source('field_sequence', identity) - - def locator(self, family, identity): - if type(identity) is not str: - raise WorkbenchError('Source identities must be exact strings.') - bare = identity - if family in NAMESPACED and identity.startswith(self.origin + '.'): - bare = identity[len(self.origin) + 1:] - if family in ('project_artifact', 'dataset_release', 'project_file', 'model_material', - 'recipe_material', 'runtime_material', 'project_snapshot'): - data_codec.sha(bare) - else: - data_codec.identity(bare) - return self.origin + '.' + bare if family in NAMESPACED else bare - - def bare(self, family, identity): - if family in NAMESPACED: - prefix = self.origin + '.' - if not identity.startswith(prefix): - raise WorkbenchError('Source dependency belongs to another catalog.', 'unsupported', 409) - return identity[len(prefix):] - return identity - - def observe(self, family, identity, revision=None): - key = family, self.locator(family, identity) - previous = self.inventory.get(key) - value = dict(family=key[0], id=key[1], revision=revision) - if previous is not None and previous != value and revision is not None: - raise WorkbenchError('Source inventory identity has conflicting revisions.', 'invalid', 409) - if previous is None or revision is not None: - if previous is None and len(self.inventory) >= MAX_RECORDS: - raise WorkbenchError('Legacy source exceeds the supported finite inventory.', 'too_large', 413) - self.inventory[key] = value - return key - - def need(self, family, identity, parent=None, reason='required scientific dependency'): - target = self.observe(family, identity) - if parent is not None: - source = dict(family=parent[0], id=parent[1]) - edge = dict(source=source, target=dict(family=target[0], id=target[1]), reason=reason) - self.dependencies[(parent, target, reason)] = edge - if target not in self.visited and target not in self.queued: - self.queue.append(target);self.queued.add(target) - return target - - def issue(self, key, code, detail, *, warning=False): - detail = str(detail)[:1000] - identity = key[0], key[1], code, detail - seen = self._issue_keys[bool(warning)] - if identity not in seen: - seen.add(identity) - destination = self.warnings if warning else self.blockers - destination.append(dict(family=key[0], id=key[1], code=code, detail=detail)) - - def add(self, record): - key = record['family'], record['id'] - if key in self.records and self.records[key] != record: - raise WorkbenchError('Two source owners disagree about the same retained fact.', 'invalid', 409) - self.records[key] = copy.deepcopy(record) - self.observe(*key) - - def intrinsic(self, parent, blob, *, preservation='unique', role='source', raw=None): - sha, size = blob['sha256'], blob['bytes'] - data_codec.sha(sha) - if type(size) is not int or not 0 <= size <= 2**63 - 1: - raise WorkbenchError('Invalid source payload size.') - declaration = dict(format='project_artifact_v1', sha256=sha, bytes=size) - self.add(dict(family='project_artifact', id=sha, document=declaration)) - self.need('project_artifact', sha, parent, preservation + ':' + role) - try: - if raw is None: - if sha in self.raw_cache: - raw = self.raw_cache[sha] - elif size > MAX_PAYLOAD and hasattr(self.source, 'payload_fd'): - with self.source.payload_fd(sha, size) as handle: - descriptor = handle[0] if isinstance(handle, tuple) else handle - self.source.artifacts.publish_fd(descriptor, declaration, maximum_bytes=size) - return - else: - raw = self.source.resolve_payload(sha, size) - if type(raw) is not bytes or len(raw) != size or hashlib.sha256(raw).hexdigest() != sha: - raise WorkbenchError('Original payload differs from its declared byte identity.', 'corrupt_payload', 409) - self.source.artifacts.publish_bytes(raw, declaration, maximum_bytes=max(size, 1)) - except (OSError, WorkbenchError) as error: - self.payload_gaps.append((parent, sha, 'missing_regenerable' if preservation == 'regenerable' else getattr(error, 'code', 'missing_payload'), role + ': ' + str(error), preservation)) - - def raw(self, parent, raw, role, *, media='application/octet-stream', kind=None): - blob = dict(sha256=hashlib.sha256(raw).hexdigest(), bytes=len(raw)) - self.raw_cache[blob['sha256']] = raw - self.intrinsic(parent, blob, raw=raw, role=role) - if kind is None: - return blob - return dict(artifact=dict(namespace=self.origin, sha256=blob['sha256']), media_type=media, - kind=kind, role=role, preservation='unique', required_for=['inspect', 'release']) - - def _catalog_source(self, kind, identity): - folder, name = {'audio': ('audio', 'source.wav'), 'field_sequence': ('field_sequence', 'source.zip')}[kind] - return self.source.read_catalog(folder + '/' + identity + '/' + name, MAX_PAYLOAD) - - def _available(self, identity): - row = self.db.execute('SELECT kind FROM workbench_records WHERE id=%s', (identity,)).fetchone() - if row is None: - return False - try: - self._catalog_source(row[0], identity) - return True - except (OSError, WorkbenchError): - return False - - def _audit(self, target, actions, *, include_denied=False): - values = [] - for row in self.db.execute('SELECT actor_id,action,target_json,details_json,result,created_at FROM access_audit WHERE target_json::jsonb=%s::jsonb ORDER BY created_at,id', (json.dumps(target),)): - if row['action'] not in actions or row['result'] != 'success' and not include_denied: - continue - values.append(dict(actor_id=row['actor_id'], action=row['action'], target=_json(row['target_json']), - details=_json(row['details_json']), result=row['result'], - occurred_at=datetime.fromtimestamp(row['created_at'], timezone.utc).isoformat())) - return values - - def discover(self): - # Only identity/revision columns are read for unrelated global rows. - for row in self.db.execute('SELECT id,revision FROM workbench_records ORDER BY id'): - self.observe('workbench_record', row[0], row[1]) - for family, statement in ( - ('workbench_response', 'SELECT id,revision FROM workbench_responses ORDER BY id'), - ('workbench_preference', 'SELECT id,revision FROM workbench_preferences ORDER BY id'), - ('saved_selection', 'SELECT id,revision FROM saved_selections ORDER BY id'), - ('saved_search', 'SELECT id,revision FROM saved_searches ORDER BY id'), - ('pipeline_graph', 'SELECT id,revision FROM workspace_graphs ORDER BY id'), - ('recipe_definition', 'SELECT id,revision FROM workspace_recipe_drafts ORDER BY id'), - ('model_definition', 'SELECT id,revision FROM model_definition_drafts ORDER BY id'), - ('study_history', 'SELECT id,revision FROM model_studies ORDER BY id'), - ('run_history', 'SELECT id,NULL FROM workspace_runs ORDER BY id'), - ('trial_history', 'SELECT id,NULL FROM model_trials ORDER BY id'), - ('candidate_history', 'SELECT id,NULL FROM model_candidates ORDER BY id'), - ('model_material', 'SELECT sha256,revision FROM model_materials ORDER BY sha256'), - ('recipe_material', 'SELECT sha256,recipe_revision FROM workspace_recipe_materials ORDER BY sha256'), - ('dataset_exposure', 'SELECT id,NULL FROM workspace_exposures ORDER BY id'), - ('generation_history', 'SELECT id,NULL FROM generation_jobs ORDER BY id'), - ('grounded_history', 'SELECT id,NULL FROM grounded_jobs ORDER BY id'), - ('caption_proposal_history', 'SELECT id,NULL FROM caption_proposals ORDER BY id'), - ('text_proposal_history', 'SELECT id,NULL FROM text_classification_proposals ORDER BY id')): - for row in self.db.execute(statement): - self.observe(family, row[0], row[1]) - # These two owners remove the current row on deletion. Their closed - # successful audit facts retain a known identity, not its lost contents. - # Keep those identities visible in the global selection report. - for row in self.db.execute("SELECT action,target_json,details_json FROM access_audit WHERE result='success' AND action IN ('saved_selections.delete','saved_searches.delete') ORDER BY created_at,id"): - family = 'saved_selection' if row[0] == 'saved_selections.delete' else 'saved_search' - try: - identity, details = _json(row[1]), _json(row[2]) - data_codec.identity(identity) - if type(details) is not dict or set(details) != {'revision', 'retired_sha256'} or type(details['revision']) is not int or details['revision'] < 1: - continue - data_codec.sha(details['retired_sha256']) - except (WorkbenchError, ValueError, TypeError): - continue - key = family, identity - if key not in self.inventory: - self.observe(family, identity, details['revision']) - self.deleted_intents.add(key) - if len(self.inventory) > MAX_RECORDS: - raise WorkbenchError('Legacy source exceeds the supported finite inventory.', 'too_large', 413) - - def capture_record(self, identity, key): - current = Workbench._get(self.reader, identity) - history = [_json(row[0]) for row in self.db.execute('SELECT snapshot FROM workbench_history WHERE id=%s ORDER BY revision', (identity,))] - origin = _json(self.db.execute('SELECT provenance_json FROM workbench_records WHERE id=%s', (identity,)).fetchone()[0]) - kind = current['kind'] - if kind == 'text': - original = self.db.execute('SELECT original_text FROM workbench_records WHERE id=%s', (identity,)).fetchone()[0] - source = dict(kind=kind, original_text=original) - elif kind == 'image': - row = self.db.execute('SELECT * FROM samples WHERE id=%s', (identity,)).fetchone() - if row is None: - _missing('The deleted image has no preserved original source row or source geometry.') - sample = dict(row); sample['annotation'] = _json(sample['annotation']) - original = self.source.read_catalog('images/' + identity + '/source', MAX_PAYLOAD) - oriented = self.source.read_catalog('images/' + identity + '/image.png', MAX_PAYLOAD) - if hashlib.sha256(original).hexdigest() != sample['sha256'] or hashlib.sha256(oriented).hexdigest() != current['content_hash']: - raise WorkbenchError('Original image bytes changed outside their recorded identity.', 'corrupt_payload', 409) - source = dict(kind=kind, original=self.raw(key, original, 'original', kind=kind), - oriented=self.raw(key, oriented, 'oriented', media='image/png', kind=kind), revisions=[sample], deleted=False) - if sample['revision'] != 1: - self.issue(key, 'source_history_unavailable', 'Earlier image source revisions were not retained by the legacy catalog.') - return - elif kind in ('sequence', 'mesh', 'pointcloud', 'volume'): - statements = {'sequence': 'SELECT bundle FROM workbench_sequence_assets WHERE id=%s', - 'mesh': 'SELECT bundle FROM workbench_mesh_assets WHERE id=%s', - 'pointcloud': 'SELECT bundle FROM workbench_pointcloud_assets WHERE id=%s', - 'volume': 'SELECT bundle FROM workbench_volume_assets WHERE id=%s'} - row = self.db.execute(statements[kind], (identity,)).fetchone() - if row is None: - _missing('Original immutable BYTEA bundle is missing.') - raw = bytes(row[0]) - if hashlib.sha256(raw).hexdigest() != current['content_hash']: - raise WorkbenchError('Original immutable BYTEA identity differs.', 'corrupt_payload', 409) - source = dict(kind=kind, asset=self.raw(key, raw, 'original', media='application/zip', kind=kind), metadata=copy.deepcopy(current[kind])) - elif kind in ('audio', 'field_sequence'): - raw = self._catalog_source(kind, identity) - if hashlib.sha256(raw).hexdigest() != current['content_hash']: - raise WorkbenchError('Original scientific/audio source identity differs.', 'corrupt_payload', 409) - source = dict(kind=kind, asset=self.raw(key, raw, 'original', kind=kind, - media='audio/wav' if kind == 'audio' else 'application/zip'), metadata=copy.deepcopy(current[kind])) - else: - raise WorkbenchError('Unsupported source data kind.', 'unsupported', 409) - doc = dict(format='workbench_record_v1', origin=origin, source=source, current=current, - history=history, events=[], audit=self._audit(identity, data_codec.DATA_ACTIONS)) - self.add(dict(family='workbench_record', id=identity, document=doc)) - for parent in current['parents']: - self.need('workbench_record', parent, key, 'immutable data parent') - for response in self.db.execute('SELECT id FROM workbench_responses WHERE prompt_id=%s ORDER BY id', (identity,)): - self.need('workbench_response', response[0], key, 'captured response to selected prompt') - for preference in self.db.execute('SELECT id FROM workbench_preferences WHERE prompt_id=%s ORDER BY id', (identity,)): - self.need('workbench_preference', preference[0], key, 'captured preference for selected prompt') - provenance = origin - generation = provenance.get('generation') - if generation is not None: - self.need('generation_history', generation['job_id'], key, 'exact generating producer') - for field, family in (('caption_proposal', 'caption_proposal_history'), ('text_classification_proposal', 'text_proposal_history'), ('grounded', 'grounded_history')): - if field in provenance and isinstance(provenance[field], dict) and 'job_id' in provenance[field]: - self.need(family, provenance[field]['job_id'], key, 'exact source producer evidence') - - def capture_response(self, identity, key): - current = Workbench._response(self.reader, identity) - history = [_json(row[0]) for row in self.db.execute('SELECT snapshot FROM workbench_response_history WHERE id=%s ORDER BY revision', (identity,))] - self.add(dict(family='workbench_response', id=identity, document=dict(format='workbench_response_v1', - current=current, history=history, audit=self._audit(identity, data_codec.DATA_ACTIONS)))) - self.need('workbench_record', current['prompt_id'], key, 'exact captured response prompt') - - def capture_preference(self, identity, key): - from preferences import Preferences - current = Preferences._get(SimpleNamespace(db=self.db), identity) - history = [_json(row[0]) for row in self.db.execute('SELECT snapshot FROM workbench_preference_history WHERE id=%s ORDER BY revision', (identity,))] - self.add(dict(family='workbench_preference', id=identity, document=dict(format='workbench_preference_v1', - current=current, history=history, audit=self._audit(identity, data_codec.DATA_ACTIONS)))) - self.need('workbench_record', current['prompt_id'], key, 'exact captured preference prompt') - for response in (current['left_id'], current['right_id']): - self.need('workbench_response', response, key, 'exact captured preference answer') - - def capture_saved(self, family, identity, key): - from saved_selections import SavedSelections - from saved_searches import SavedSearches - if key in self.deleted_intents: - self.issue(key, 'intent_history_unavailable', 'A successful legacy deletion retains this identity and retired hash, but its original name and criteria/membership history are unavailable.') - return - current = (SavedSelections if family == 'saved_selection' else SavedSearches)._get(SimpleNamespace(db=self.db), identity) - if family == 'saved_selection': - for member in current['items']: - self.need('workbench_record', member['id'], key, 'saved exact membership') - if current['revision'] != 1: - self.issue(key, 'intent_history_unavailable', 'Legacy storage retains only the current saved name and criteria/membership, not its earlier revisions.') - return - self.add(dict(family=family, id=identity, document=dict(format=data_codec.FAMILIES[family], - current=current, history=[copy.deepcopy(current)], deleted=False, audit=self._audit(identity, data_codec.DATA_ACTIONS)))) - - def capture_definition(self, family, identity, key): - statement = {'pipeline_graph': 'SELECT document FROM workspace_graphs WHERE id=%s', - 'model_definition': 'SELECT document FROM model_definition_drafts WHERE id=%s', - 'recipe_definition': 'SELECT document FROM workspace_recipe_drafts WHERE id=%s'}[family] - row = self.db.execute(statement, (identity,)).fetchone() - if row is None: - _missing('Selected editable definition is missing.') - value = material_codec._definition(family, _json(row[0]), self.origin) - audits = [] - for fact in self._audit(identity, material_codec.AUDIT_ACTIONS): - try: - material_codec._definition_audit(family, value, fact, self.origin) - except WorkbenchError: - continue - audits.append(fact) - if len(audits) != 1: - _missing('The current editable definition has no unique exact original audit fact.') - record = dict(family=family, id=key[1], document=dict(format=material_codec.FAMILIES[family], - origin_catalog_id=self.origin, current=value, revisions=[copy.deepcopy(value)], audit=audits)) - material_codec.decode_records([record]);self.add(record) - if value['revision'] > 1: - self.issue(key, 'observed_history_incomplete', 'Only the actual retained current definition and its exact audit are available; earlier definition documents were not stored.', warning=True) - selector = value.get('source_selector') - if selector is not None: - self.snapshot_dependency(selector['project_id'], key) - if family == 'pipeline_graph': - # Graph-specific dependency extraction is delegated to the existing - # graph grammar below rather than inferred from arbitrary JSON. - for node in value['nodes']: - if node['type'] == 'release': - self.need('dataset_release', node['parameters']['release_id'], key, 'frozen graph input release') - elif node['type'] == 'input' and value['recipe'] == 'external_recipe': - self.snapshot_dependency(node['parameters']['project_id'], key) - - def snapshot_dependency(self, identity, parent): - row = self.db.execute('SELECT document FROM workspace_projects WHERE id=%s', (identity,)).fetchone() - if row is None: - _missing('Required registered project snapshot is missing.') - saved = decode_retained_snapshot(_json(row[0]));self.snapshot_by_id[identity] = saved - self.need('project_snapshot', saved['manifest_sha256'], parent, 'exact retained source registration') - - def capture_snapshot(self, sha, key): - matches = [value for value in self.snapshot_by_id.values() if value['manifest_sha256'] == sha] - if len(matches) != 1: - _missing('An exact selected project snapshot is not available in this pinned source.') - saved = matches[0] - # Explicitly recovered bytes retain the original registration as inert - # history. Its former directory/inode is not current read authority. - raw = self.source.read_bound_payload(sha, maximum_bytes=65536) - if raw is None: - root = self.source.roots.get(saved['root']) - if root is None or list(root[1]) != saved['root_identity']: - _missing('The retained registration has no matching current explicit source-root capability.') - raw = self.source.read_root(saved['root'], saved['manifest_path'], 65536) - if hashlib.sha256(raw).hexdigest() != sha or decode_retained_manifest(decode_manifest(raw)) != saved['manifest']: - raise WorkbenchError('Original registered manifest bytes differ.', 'corrupt_payload', 409) - blob = self.raw(key, raw, 'project_manifest') - record = dict(family='project_snapshot', id=key[1], document=dict(format=material_codec.FAMILIES['project_snapshot'], - origin_catalog_id=self.origin, value=saved, artifacts=material_codec._edges([dict(name=saved['manifest_path'], **blob)], 'project_snapshot'), audit=[])) - material_codec.decode_records([record]);self.add(record) - - def capture_material(self, family, sha, key): - statement = ('SELECT document FROM model_materials WHERE sha256=%s' if family == 'model_material' - else 'SELECT document FROM workspace_recipe_materials WHERE sha256=%s') - row = self.db.execute(statement, (sha,)).fetchone() - if row is None: - _missing('Required immutable material is missing.') - value = _json(row[0]);inventory = material_codec._inventory(family, value) - target = value['ref']['id'] if family == 'model_material' else sha - action = 'models.publish' if family == 'model_material' else 'recipes.material' - expected = (dict(revision=value['ref']['revision'], material_sha256=sha) if family == 'model_material' - else dict(recipe_id=value['material']['recipe_id'], revision=value['material']['recipe_revision'])) - audits = [fact for fact in self._audit(target, {action}) if fact['details'] == expected] - record = dict(family=family, id=key[1], document=dict(format=material_codec.FAMILIES[family], - origin_catalog_id=self.origin, value=value, artifacts=material_codec._edges(inventory, family), audit=audits)) - material_codec.decode_records([record]);self.add(record) - folder = 'model-materials' if family == 'model_material' else 'workspace-recipe-materials' - for item in inventory: - try: - raw = self.source.read_catalog(folder + '/' + sha + '/' + item['name'], min(MAX_PAYLOAD, max(item['bytes'], 1))) - except (OSError, WorkbenchError): - raw = None - self.intrinsic(key, item, role=item['name'], raw=raw) - material = value['material'] - if family == 'model_material': - self.need('model_definition', material['model_definition_id'], key, 'original editable model definition') - if material['source_selector'] is not None: - self.snapshot_dependency(material['source_selector']['project_id'], key) - else: - self.need('model_material', material['model']['sha256'], key, 'exact composed model material') - self.need('pipeline_graph', material['recipe_id'], key, 'original editable composition graph') - for release in material['data']: - self.need('dataset_release', release['id'], key, 'exact frozen composition data') - recipe = material['recipe_document'] - raw = self.source.resolve_payload(recipe['sha256'], recipe['bytes']) - snapshot = _json(raw.decode('utf-8')) - if snapshot['format'] == 'builtin_recipe_snapshot_v1': - environment = snapshot['validation']['runtime'] - else: - execution = snapshot['preflight']['material'] - environment = execution.get('torch_runtime', execution.get('cpu_snapshot', execution['runtime'])) - self.capture_runtime(environment, key) - - def capture_runtime(self, environment, parent): - from pipeline import digest - from recipe_process import decode - sha = digest(environment);key = self.need('runtime_material', sha, parent, 'original measured runtime material') - if key in self.records: - return - descriptor = environment if environment.get('profile') in ('captured_cpu_python_v1', 'managed_torch_python_v1') else None - raw = self.source.resolve_payload(descriptor['manifest_sha256'], descriptor['manifest_bytes']) if descriptor else None - decoded = decode(raw) if raw is not None else None - value = dict(ref=dict(kind='runtime', catalog_id=self.origin, id=sha, sha256=sha), descriptor=descriptor, - environment=environment if descriptor is None else None, manifest=decoded) - value = material_codec.decode_runtime_material(value, catalog_id=self.origin) - inventory = ([dict(name='manifest.json', sha256=descriptor['manifest_sha256'], bytes=descriptor['manifest_bytes'])] + - [dict(name=item['path'], sha256=item['sha256'], bytes=item['bytes']) for item in decoded['files']]) if descriptor else [] - record = dict(family='runtime_material', id=key[1], document=dict(format=material_codec.FAMILIES['runtime_material'], - origin_catalog_id=self.origin, value=value, artifacts=material_codec._edges(inventory, 'runtime_material'), audit=[])) - material_codec.decode_records([record]);self.add(record) - for item in record['document']['artifacts']: - self.intrinsic(key, item['blob'], preservation=item['preservation'], role=item['name'], raw=raw if item['name'] == 'manifest.json' else None) - - def capture_study(self, identity, key): - row = self.db.execute('SELECT document FROM model_studies WHERE id=%s', (identity,)).fetchone() - if row is None:_missing('Selected Study is missing.') - study = _json(row[0]);ref = study['policy'] - policy_row = self.db.execute('SELECT document FROM model_selection_policies WHERE sha256=%s', (ref['sha256'],)).fetchone() - if policy_row is None:_missing('Exact Study policy is missing.') - memberships = [dict(revision=row[0], trial_ids=_json(row[1])['trial_ids']) for row in self.db.execute( - 'SELECT revision,document FROM model_study_memberships WHERE study_id=%s ORDER BY revision', (identity,))] - reservations = [_json(row[0]) for row in self.db.execute('SELECT document FROM model_attempt_reservations WHERE study_id=%s ORDER BY id', (identity,))] - doc = dict(format=history_codec.FAMILY_FORMATS['study_history'], origin_catalog_id=self.origin, study=study, - memberships=memberships, policies=[dict(ref=ref, policy=_json(policy_row[0]))], reservations=reservations, - operations=[], revisions=[copy.deepcopy(study)], audit=[], revision_history_complete=study['revision'] == 1) - # Native operation receipts contain scientific results, not replay - # instructions in the destination. Classify them through the existing - # Study owner's finite result-to-Study projection. - from project_study_execution import ProjectStudyExecution - def original_trial(trial_id): - selected = self.db.execute('SELECT document FROM model_trials WHERE id=%s', (trial_id,)).fetchone() - if selected is None:_missing('Native lineage operation lost its original Trial.') - return _json(selected[0]) - classifier = SimpleNamespace(studies=SimpleNamespace(trial=original_trial)) - observed_revisions = {study['revision']: copy.deepcopy(study)} - policies = {ref['sha256']: doc['policies'][0]} - for row in self.db.execute('SELECT actor_id,operation_id,request_key,request_sha256,document FROM model_operation_receipts ORDER BY actor_id,operation_id,request_key'): - if row['operation_id'] not in history_codec.OPERATIONS: - continue - try: - result = _json(row['document']) - belongs = ProjectStudyExecution._operation_study(classifier, row['operation_id'], result) - except (WorkbenchError, KeyError, TypeError, ValueError): - self.issue(key, 'unassigned_operation_unreadable', 'A native operation result cannot be assigned to a Study: ' + row['operation_id'] + '/' + row['request_key'], warning=True) - continue - if belongs != identity: - continue - fact = dict(actor_id=row['actor_id'], operation_id=row['operation_id'], request_key=row['request_key'], - request_sha256=row['request_sha256'], result=result) - history_codec._operations([fact], self.origin) - doc['operations'].append(fact) - if row['operation_id'] in ('studies.create', 'studies.save', 'studies.continue'): - previous = observed_revisions.get(result['revision']) - if previous is not None and previous != result: - raise WorkbenchError('Native Study receipts disagree about an observed revision.') - observed_revisions[result['revision']] = copy.deepcopy(result) - policy_ref = result['policy'] - policy_row = self.db.execute('SELECT document FROM model_selection_policies WHERE sha256=%s', (policy_ref['sha256'],)).fetchone() - if policy_row is None:_missing('Observed Study revision lost its exact policy.') - policies[policy_ref['sha256']] = dict(ref=policy_ref, policy=_json(policy_row[0])) - doc['revisions'] = [observed_revisions[revision] for revision in sorted(observed_revisions)] - doc['policies'] = [policies[sha] for sha in sorted(policies)] - doc['revision_history_complete'] = sorted(observed_revisions) == list(range(1, study['revision'] + 1)) - for trial in study['trial_ids']: - self.need('trial_history', trial, key, 'immutable Study Trial membership') - for reservation in reservations: - self.need('run_history', reservation['run_id'], key, 'spent or reserved scientific attempt') - candidate_ids = [] - for row in self.db.execute('SELECT id,document FROM model_candidates WHERE study_id=%s ORDER BY id', (identity,)): - self.need('candidate_history', row[0], key, 'retained scientific candidate') - candidate_ids.append(row[0]);candidate = _json(row[1]);policy_ref = candidate['policy'] - if policy_ref['sha256'] not in policies: - policy_row = self.db.execute('SELECT document FROM model_selection_policies WHERE sha256=%s', (policy_ref['sha256'],)).fetchone() - if policy_row is None:_missing('Candidate lost its exact historical selection policy.') - policies[policy_ref['sha256']] = dict(ref=policy_ref, policy=_json(policy_row[0])) - doc['policies'] = [policies[sha] for sha in sorted(policies)] - targets = {identity, *study['trial_ids'], *candidate_ids, *(item['run_id'] for item in reservations)} - for target in sorted(targets): - doc['audit'].extend(self._audit(target, history_codec.OPERATIONS | {'studies.admit', 'studies.approve', 'studies.reconcile', 'studies.candidate_selected', 'studies.lineage.record', 'runs.admit', 'runs.admit_external', 'runs.update', 'runs.reconcile', 'runs.expose_test'})) - history_codec._audit(doc['audit']) - self.add(history_codec.envelope('study_history', self.origin, identity, doc)) - if not doc['revision_history_complete']: - self.issue(key, 'observed_history_incomplete', 'The legacy catalog retained only this Study revision; immutable memberships, policies, Trials and reservations are preserved.', warning=True) - - def capture_trial(self, identity, key): - row = self.db.execute('SELECT document FROM model_trials WHERE id=%s', (identity,)).fetchone() - if row is None:_missing('Required historical Trial is missing.') - trial = _json(row[0]);lineage_row = self.db.execute('SELECT document FROM model_trial_lineage WHERE trial_id=%s', (identity,)).fetchone() - lineage = _json(lineage_row[0]) if lineage_row is not None else None - self.add(history_codec.envelope('trial_history', self.origin, identity, dict(format=history_codec.FAMILY_FORMATS['trial_history'], - origin_catalog_id=self.origin, trial=trial, lineage=lineage))) - self.need('study_history', trial['study_id'], key, 'original Trial Study') - self.need('recipe_material', trial['material']['sha256'], key, 'exact immutable Trial composition') - if lineage is not None: - for relation in ('parent', 'baseline'): - ref = lineage['intent'][relation] - if ref is not None: - if ref['catalog_id'] != self.origin: - self.issue(key, 'unsupported_origin', 'Lineage crosses a source catalog not supplied by this read capability.') - else:self.need('trial_history', ref['trial_id'], key, 'explicit ' + relation + ' lineage') - - def capture_candidate(self, identity, key): - row = self.db.execute('SELECT document FROM model_candidates WHERE id=%s', (identity,)).fetchone() - if row is None:_missing('Required candidate observation is missing.') - candidate = _json(row[0]) - self.add(history_codec.envelope('candidate_history', self.origin, identity, dict(format=history_codec.FAMILY_FORMATS['candidate_history'], - origin_catalog_id=self.origin, candidate=candidate))) - self.need('study_history', candidate['study_id'], key, 'original candidate Study') - self.need('trial_history', candidate['trial_id'], key, 'original candidate Trial') - self.need('run_history', candidate['run_id'], key, 'original candidate Run evidence') - - def capture_run(self, identity, key): - row = self.db.execute('SELECT document FROM workspace_runs WHERE id=%s', (identity,)).fetchone() - if row is None:_missing('Selected historical Run is missing.') - run = _json(row[0]);history_codec.project_run_projection(run) - admission = self.db.execute('SELECT * FROM access_admissions WHERE id=%s', (run['admission_id'],)).fetchone() - grant = consumption = None - if run.get('approval_id') is not None: - grant = self.db.execute('SELECT * FROM access_execution_grants WHERE id=%s', (run['approval_id'],)).fetchone() - consumption = self.db.execute('SELECT * FROM access_execution_consumptions WHERE grant_id=%s', (run['approval_id'],)).fetchone() - proof = None - if admission is not None: - admission = dict(admission);admission['effects'] = _json(admission.pop('effects_json')) - proof = dict(grant=dict(grant) if grant is not None else None, consumption=dict(consumption) if consumption is not None else None, admission=admission) - history_codec._approval(proof, run) - payloads = [] - def payload(name, blob, role, population='unknown', raw=None, preservation='unique'): - self.intrinsic(key, blob, role=name, raw=raw, preservation=preservation) - payloads.append(dict(name=name, blob={field:blob[field] for field in ('sha256', 'bytes')}, population=population, - role=role, preservation=preservation, required_for=['scientific_inspection', 'execution_proof'])) - external = run.get('execution_kind') == 'external_recipe' - if external: - for name, item in run['material']['captures'].items(): - try:raw = self.source.read_catalog('workspace-runs/.external-' + identity + '/' + name, min(MAX_PAYLOAD, max(item['bytes'], 1))) - except (OSError, WorkbenchError):raw = None - payload(name, item, 'execution_source', raw=raw) - environment = run['material'].get('torch_runtime', run['material'].get('cpu_snapshot', run['material']['runtime'])) - self.capture_runtime(environment, key) - for ordinal, (name, item) in enumerate(sorted(run['material']['runtime'].get('files', {}).items())): - payload('runtime-files/' + str(ordinal), item, 'historical_runtime', preservation='regenerable') - for name, sha in sorted(run['material']['host_files'].items()): - declared = self.records.get(('project_artifact', sha)) - candidates = {declared['document']['bytes']} if declared is not None else { - item['bytes'] for item in self.source.external_inventory if item['sha256'] == sha} - if len(candidates) != 1: - self.issue(key, 'source_byte_count_unavailable', 'Original host source ' + name + ' retains a hash without original byte-count/custody evidence.') - else: - payload('host-sources/' + name, dict(sha256=sha, bytes=candidates.pop()), 'historical_host_source') - if run['state'] == 'completed': - receipt = self.source.read_catalog('workspace-runs/' + identity + '/custody-receipt.json', 16384) - inventory = self.source.read_catalog('workspace-runs/' + identity + '/artifact-manifest.json', 65536) - from runs import validate_external_artifact_inventory - validate_external_artifact_inventory(run, receipt, inventory) - payload('custody-receipt.json', dict(sha256=hashlib.sha256(receipt).hexdigest(), bytes=len(receipt)), 'custody_proof', raw=receipt) - payload('artifact-manifest.json', dict(sha256=hashlib.sha256(inventory).hexdigest(), bytes=len(inventory)), 'custody_proof', raw=inventory) - else: - payload('release.zip', dict(sha256=run['release_sha256'], bytes=run['release_bytes']), 'frozen_input') - self.need('dataset_release', run['release_id'], key, 'exact native frozen input') - for source in run['source_records']: - self.need('workbench_record', source['id'], key, 'retained native scientific input') - from pipeline import adapter_for_graph, decode_probe_observation - import release_validation - # Whole-asset integrity runs execute in-process and do not create - # the training source staging directory. Trainable native runs do; - # only those original, hash-bound copies prove their implementation. - if adapter_for_graph(run['graph']) is not release_validation: - if 'definition_files' not in run['runtime']: - self.issue(key, 'source_identity_unavailable', 'Native training Run has no retained original source inventory.') - else: - observation = decode_probe_observation(run['graph'].get('recipe', 'image_classification'), - run['runtime'], with_definition=True) - for name, expected in sorted(observation['definition_files'].items()): - try: - raw = self.source.read_catalog('workspace-runs/.staging-' + identity + '/' + name, MAX_PAYLOAD) - except (OSError, WorkbenchError): - self.issue(key, 'missing_source', 'Original native training source ' + name + ' is unavailable.') - continue - if hashlib.sha256(raw).hexdigest() != expected: - self.issue(key, 'corrupt_source', 'Original native training source ' + name + ' differs from its retained hash.') - continue - payload('source/' + name, dict(sha256=expected, bytes=len(raw)), 'execution_source', raw=raw) - for item in run['artifacts']: - try:raw = self.source.read_catalog('workspace-runs/' + identity + '/' + item['name'], min(MAX_PAYLOAD, max(item['bytes'], 1))) - except (OSError, WorkbenchError):raw = None - payload(item['name'], item, item.get('role', 'output'), item.get('split', 'unknown'), raw=raw) - if run.get('approval_material_sha256') is not None: - self.need('recipe_material', run['approval_material_sha256'], key, 'original approved composition') - if run.get('parent_run_id') is not None:self.need('run_history', run['parent_run_id'], key, 'original retry parent') - for association in self.db.execute('SELECT trial_id,study_id FROM model_attempt_reservations WHERE run_id=%s', (identity,)): - self.need('study_history', association[1], key, 'original budget association') - self.need('trial_history', association[0], key, 'original attempt Trial') - if external: - for item in run['material']['inputs'].values() if isinstance(run['material'].get('inputs'), dict) else []: - source = item.get('source', {}) - if item.get('kind') == 'run_artifact': - if source.get('catalog_id') != self.origin: - self.issue(key, 'unsupported_origin', 'Run artifact input crosses a source catalog not supplied by this read capability.') - else: - self.need('run_history', source['run_id'], key, 'exact producer Run input') - publication = None - if run.get('publication_continuation') is not None: - publication = dict(continuation=copy.deepcopy(run['publication_continuation']), source=None, result=None) - if run.get('publication_source') is not None: - from run_publication import validate_publication_source, validate_publication_result, MAX_DOCUMENT_BYTES - raw = self.source.read_catalog('workspace-runs/.external-' + identity + '/publication-source-v1.json', MAX_DOCUMENT_BYTES) - source_proof = validate_publication_source(raw, run=run) - blob = dict(sha256=hashlib.sha256(raw).hexdigest(), bytes=len(raw)) - payload('publication-source-v1.json', blob, 'publication_proof', raw=raw) - if publication is not None: - publication['source'] = blob - continuation = publication['continuation'];result_ref = continuation.get('result_ref') - if result_ref is not None: - result_raw = self.source.read_catalog('workspace-runs/.external-' + identity + '/publication-result-v1.json', MAX_DOCUMENT_BYTES) - validate_publication_result(result_raw, run=run, source=source_proof, ref=result_ref, continuation=continuation) - result_blob = dict(sha256=hashlib.sha256(result_raw).hexdigest(), bytes=len(result_raw)) - payload('publication-result-v1.json', result_blob, 'publication_result', raw=result_raw) - publication['result'] = result_blob - self.add(history_codec.capture_run(run, admission_proof=proof, payloads=payloads, publication=publication)) - - def capture_producer(self, family, identity, key): - statements = {'generation_history': 'SELECT data,ordinal FROM generation_jobs WHERE id=%s', - 'grounded_history': 'SELECT data,ordinal FROM grounded_jobs WHERE id=%s', - 'caption_proposal_history': 'SELECT data,ordinal FROM caption_proposals WHERE id=%s', - 'text_proposal_history': 'SELECT data,ordinal FROM text_classification_proposals WHERE id=%s'} - row = self.db.execute(statements[family], (identity,)).fetchone() - if row is None:_missing('Selected producer history is missing.') - original = _json(row[0]);entries = [] - if original.get('id') != identity:raise WorkbenchError('Producer row identity differs.') - if family == 'generation_history': - for entry in self.db.execute('SELECT data,storage_order FROM generation_entries WHERE job_id=%s ORDER BY storage_order', (identity,)): - entries.append((_json(entry[0]), entry[1])) - owner = SimpleNamespace(_origin=self.origin, _pending_payloads={}, _artifacts={}, session=self.session) - record = producer_codec._capture_job(owner, family, original, row[1], entries) - self.add(record) - for sha, declaration in owner._artifacts.items():self.intrinsic(key, declaration, role='producer_evidence', raw=owner._pending_payloads[sha]) - source = original.get('source') - if source is not None:self.need('workbench_record', source['id'], key, 'exact captured producer source') - if family == 'generation_history': - for entry, _ in entries: - if entry.get('sample_id') is not None:self.need('workbench_record', entry['sample_id'], key, 'retained generated source') - - def capture_release(self, identity, key): - # A release is immutable original ZIP evidence, never re-exported from - # current SQL. Its hash is its identity; inventory supplies original size. - from dataset_releases import Releases - raw = self.source.read_catalog('releases/' + identity + '.zip', MAX_PAYLOAD) - if hashlib.sha256(raw).hexdigest() != identity: - raise WorkbenchError('Original frozen release hash differs.', 'corrupt_payload', 409) - manifest_value = Releases.project_manifest(raw) - edge = self.raw(key, raw, 'frozen_archive', kind='release', media='application/zip') - self.add(dict(family='dataset_release', id=identity, document=dict(format='dataset_release_v1', asset=edge, - manifest=manifest_value, release_format=manifest_value.get('format', 'canonical_v1'), audit=self._audit(identity, data_codec.DATA_ACTIONS)))) - for item in manifest_value.get('records', manifest_value.get('prompts', [])): - self.need('workbench_record', item['id'], key, 'original frozen release record') - for item in manifest_value.get('responses', []): - self.need('workbench_response', item['id'], key, 'original frozen response') - for item in manifest_value.get('judgments', []): - self.need('workbench_preference', item['id'], key, 'original frozen preference') - - def capture_exposure(self, identity, key): - row = self.db.execute('SELECT * FROM workspace_exposures WHERE id=%s', (identity,)).fetchone() - if row is None:_missing('Selected disclosure observation is missing.') - value = dict(row);self.add(dict(family='dataset_exposure', id=identity, document=dict(format='dataset_exposure_v1', **value))) - self.need('workbench_record', value['record_id'], key, 'original exposed data') - self.need('run_history', value['run_id'], key, 'original disclosure Run') - self.need('dataset_release', value['release_id'], key, 'original exposed input Release') - - def working(self, item, saved): - kind, path = item['kind'], item['path'] - identity = file_id(self.origin, kind, path);key = self.observe('project_file', identity) - relative = saved['manifest_path'].rsplit('/', 1)[0] + '/' + path if '/' in saved['manifest_path'] else path - root = self.source.roots.get(saved['root']) - if root is None or list(root[1]) != saved['root_identity']: - _missing('Working files require the exact current registered root capability.') - raw = self.source.read_root(saved['root'], relative, MAX_FILE_BYTES) - text = raw.decode('utf-8', 'strict');blob = self.raw(key, raw, 'selected_working_file') - self.working_files.append(dict(kind=kind, path=path, sha256=blob['sha256'], bytes=blob['bytes'], text=text)) - - def execute(self, key): - family, locator = key;identity = self.bare(family, locator) - if key in self.records:return - if family == 'project_artifact': - match = [item for item in self.source.external_inventory if item['sha256'] == identity] - if not match:_missing('Selected artifact has no original byte-count inventory.') - sizes = {item['bytes'] for item in match} - if len(sizes) != 1:raise WorkbenchError('Selected artifact byte-count observations disagree.') - self.intrinsic(key, dict(sha256=identity, bytes=sizes.pop()), role='explicit_selected_artifact') - return - if family == 'workbench_record':return self.capture_record(identity, key) - if family == 'workbench_response':return self.capture_response(identity, key) - if family == 'workbench_preference':return self.capture_preference(identity, key) - if family in ('saved_selection', 'saved_search'):return self.capture_saved(family, identity, key) - if family in material_codec.EDITABLE:return self.capture_definition(family, identity, key) - if family == 'project_snapshot':return self.capture_snapshot(identity, key) - if family in ('model_material', 'recipe_material'):return self.capture_material(family, identity, key) - if family == 'project_file':_missing('Working-file adoption requires its explicit selected kind and path, not an inferred identifier.') - if family == 'runtime_material':_missing('Runtime material has no exact owning recipe/Run descriptor in the selected source closure.') - if family == 'study_history':return self.capture_study(identity, key) - if family == 'trial_history':return self.capture_trial(identity, key) - if family == 'candidate_history':return self.capture_candidate(identity, key) - if family == 'run_history':return self.capture_run(identity, key) - if family in producer_codec.FAMILIES:return self.capture_producer(family, identity, key) - if family == 'dataset_release':return self.capture_release(identity, key) - if family == 'dataset_exposure':return self.capture_exposure(identity, key) - raise WorkbenchError('Unsupported extraction family.', 'unsupported', 409) - - def validate(self): - for parent, sha, code, detail, preservation in self.payload_gaps: - declaration = self.records[('project_artifact', sha)]['document'] - if self.source.artifacts.status(declaration)['state'] != 'verified': - self.issue(parent, code, detail, warning=preservation == 'regenerable') - records = list(self.records.values()) - # Failed dependencies remain explicit blockers. Do not turn their - # absence into a fabricated valid empty closure. - if self.blockers:return - try: - data_codec.decode_data_records(records) - materials = material_codec.MaterialSnapshot(records) - history_codec.decode_records(records, materials=materials) - producer_codec.decode_records(records, artifacts=self.source.artifacts) - except WorkbenchError as error: - self.issue(self.anchor, error.code, str(error)) - - -def capture_legacy(source, selection): - """Capture selected facts from a caller-owned immutable read capability. - - All returned locators use exact canonical envelope identities. Global - inventory is distinct from selected closure. Source credentials, current - admissions and runtime owners are never reconstructed in the destination. - """ - if source.db.schema_version != 10: - raise WorkbenchError('Only the qualified legacy schema 10 can be extracted.', 'unsupported', 409) - if type(selection) is not dict or set(selection) - {'project_snapshot', 'roots', 'decisions'}: - raise WorkbenchError('Invalid finite extraction selection.') - snapshot = selection.get('project_snapshot') - if type(snapshot) is not dict or set(snapshot) != {'id', 'manifest_sha256'}: - raise WorkbenchError('Select one exact registered project snapshot.') - roots = selection.get('roots', {}) - if type(roots) is not dict or set(roots) - set(ROOT_FAMILIES) - {'producer_jobs', 'working_files'}: - raise WorkbenchError('Unknown extraction root family.') - source.require() - proof = source.db.execute("SELECT current_setting('transaction_read_only'),current_setting('transaction_isolation')").fetchone() - if tuple(proof) != ('on', 'repeatable read'): - raise WorkbenchError('Extraction requires a pinned repeatable-read READ ONLY source.', 'unavailable', 409) - capture = _Capture(source) - with source.db.lock: - capture.discover() - capture.snapshot_dependency(snapshot['id'], None) - saved = capture.snapshot_by_id[snapshot['id']] - if saved['manifest_sha256'] != snapshot['manifest_sha256']: - raise WorkbenchError('Selected registered snapshot digest changed.', 'stale', 409) - capture.anchor = capture.need('project_snapshot', saved['manifest_sha256']) - for root, family in ROOT_FAMILIES.items(): - values = roots.get(root, []) - if type(values) is not list or len(values) > MAX_RECORDS: - raise WorkbenchError('Extraction roots must be bounded lists.') - for identity in values: - if not isinstance(identity, str):raise WorkbenchError('Invalid selected identity.') - capture.need(family, identity) - decisions = selection.get('decisions', []) - if type(decisions) is not list or len(decisions) > MAX_RECORDS: - raise WorkbenchError('Ownership decisions must be bounded lists.') - supported = set(ROOT_FAMILIES.values()) | NAMESPACED | {'project_artifact', 'project_file', 'trial_history', 'candidate_history'} - for decision in decisions: - if (type(decision) is not dict or set(decision) != {'family', 'id', 'include', 'reason'} - or decision['family'] not in supported or type(decision['include']) is not bool): - raise WorkbenchError('Invalid explicit ownership decision.') - if decision['include']: - capture.need(decision['family'], decision['id']) - for item in roots.get('producer_jobs', []): - if type(item) is not dict or set(item) != {'kind', 'id'} or item['kind'] not in PRODUCERS: - raise WorkbenchError('Invalid selected producer family.') - capture.need(PRODUCERS[item['kind']], item['id']) - for item in roots.get('working_files', []): - try:capture.working(item, saved) - except (OSError, WorkbenchError, UnicodeError) as error: - capture.issue(('project_file', file_id(capture.origin, item['kind'], item['path'])), getattr(error, 'code', 'missing_source'), str(error)) - while capture.queue: - key = capture.queue.popleft();capture.queued.discard(key) - if key in capture.visited:continue - capture.visited.add(key) - if len(capture.visited) > MAX_RECORDS:raise WorkbenchError('Extraction closure exceeds its bound.', 'too_large', 413) - try:capture.execute(key) - except (OSError, WorkbenchError, KeyError, TypeError, ValueError) as error: - capture.issue(key, getattr(error, 'code', 'invalid_source'), str(error)) - capture.validate() - return dict(records=[capture.records[key] for key in sorted(capture.records)], - inventory=[capture.inventory[key] for key in sorted(capture.inventory)], - dependencies=[capture.dependencies[key] for key in sorted(capture.dependencies)], - blockers=capture.blockers, working_files=capture.working_files, warnings=capture.warnings) diff --git a/project_files.py b/project_files.py deleted file mode 100644 index ad0f6b3f..00000000 --- a/project_files.py +++ /dev/null @@ -1,522 +0,0 @@ -"""Project-owned scripts and notes: inert working files, explicit adoption. - -Captured UTF-8 text is immutable checkpoint history. Inspecting a working tree -never rewrites it, restores a missing file, executes a script, or installs tools. -""" -import copy -from datetime import datetime -from functools import cache, partial -import errno -import hashlib -import os -import stat - -from project_store import DIR_FLAGS -from workbench import WorkbenchError, timestamp - -FAMILY='project_file' -FORMAT='project_file_v1' -DELETION_FORMAT='project_file_v2' -MAX_FILE_BYTES=1024*1024 -MAX_FILES=1000 -MAX_ADOPT_ITEMS=40 -MAX_ADOPT_BYTES=8*1024*1024 -KINDS={'script':'scripts','note':'notes'} -VERSION_FIELDS={'revision','sha256','bytes','text','adopted_at','actor_id'} -RESULT_FIELDS={'id','project_id','kind','path','revision','sha256','bytes','adopted_at','changed'} - - -def fail(message,code='invalid',status=400): - raise WorkbenchError(message,code,status) - - -def closed(value,fields,label): - if type(value) is not dict or set(value)!=fields:fail('Invalid '+label+' fields.') - - -def digest(raw):return hashlib.sha256(raw).hexdigest() - - -def sha(value): - if type(value) is not str or len(value)!=64 or any(c not in '0123456789abcdef' for c in value):fail('Invalid working-file digest.') - - -def _path(kind,path): - if type(kind) is not str or kind not in KINDS or type(path) is not str or len(path)>512 or '\\' in path or any(ord(c)<32 for c in path): - fail('Choose a bounded relative script or note path.') - try:path.encode('utf-8') - except UnicodeEncodeError:fail('Working-file path must be strict UTF-8.') - parts=path.split('/') - if not 2<=len(parts)<=16 or parts[0]!=KINDS[kind] or any(part in ('','.','..') or len(part.encode('utf-8'))>255 for part in parts): - fail('Working-file path must remain inside its scripts or notes root.') - return parts - - -def _project_id(value): - if type(value) is not str or len(value)!=32 or any(c not in '0123456789abcdef' for c in value):fail('Invalid working-file project identity.') - - -def file_id(project_id,kind,path): - _project_id(project_id) - _path(kind,path) - return digest((project_id+'\0'+kind+'\0'+path).encode('utf-8')) - - -def _date(value): - try: - if type(value) is not str or len(value)>80:raise ValueError() - parsed=datetime.fromisoformat(value) - if parsed.utcoffset() is None:raise ValueError() - return parsed - except (ValueError,TypeError):fail('Invalid adoption timestamp.') - - -def _version(value,*,allow_deleted=False): - deleted=allow_deleted and type(value) is dict and value.get('deleted') is True - closed(value,VERSION_FIELDS|{'deleted'} if deleted else VERSION_FIELDS,'adopted working-file revision') - if type(value['revision']) is not int or not 1<=value['revision']<=2**53-1:fail('Invalid adoption revision.') - if deleted: - if value['text'] is not None or value['sha256'] is not None or type(value['bytes']) is not int or value['bytes']!=0: - fail('A deleted note revision must retain an exact absence marker.') - else: - if type(value['text']) is not str:fail('Adopted source must be UTF-8 text.') - try:raw=value['text'].encode('utf-8') - except UnicodeEncodeError:fail('Adopted source must be strict UTF-8.') - sha(value['sha256']) - if type(value['bytes']) is not int or value['bytes']!=len(raw) or len(raw)>MAX_FILE_BYTES or digest(raw)!=value['sha256']: - fail('Adopted text bytes differ from their exact identity.') - if type(value['actor_id']) is not str or len(value['actor_id'])!=32 or any(c not in '0123456789abcdef' for c in value['actor_id']):fail('Invalid historical adoption actor.') - _date(value['adopted_at']) - - -def decode_records(records): - if type(records) is not list:fail('Working-file inventory must be a list.') - owned=[];seen=set() - for envelope in records: - if type(envelope) is not dict:fail('Invalid working-file envelope.') - if envelope.get('family')!=FAMILY:continue - closed(envelope,{'family','id','document'},'working-file envelope') - doc=envelope['document'] - if type(doc) is not dict or doc.get('format') not in (FORMAT,DELETION_FORMAT):fail('Unsupported working-file format.','unsupported',409) - closed(doc,{'format','project_id','kind','path','current','history','origin'},'working-file document') - expected=file_id(doc['project_id'],doc['kind'],doc['path']) - if envelope['id']!=expected or expected in seen:fail('Duplicate or mismatched working-file identity.') - seen.add(expected) - if type(doc['history']) is not list or not doc['history']:fail('Working-file history is missing.') - previous=None;previous_deleted=False;has_deletion=False - for revision,value in enumerate(doc['history'],1): - _version(value,allow_deleted=doc['format']==DELETION_FORMAT) - deleted=value.get('deleted') is True - if deleted and (doc['kind']!='note' or revision==1 or previous_deleted):fail('Only an adopted, present note can acquire a deleted revision.') - if value['revision']!=revision or previous is not None and _date(value['adopted_at'])MAX_FILES for count in counts.values()):fail('Project tracks more than 1,000 working files.','too_large',413) - _validate_forks(owned,records) - return owned - - -def _result(envelope,changed): - doc=envelope['document'];value=doc['current'] - result=dict(id=envelope['id'],project_id=doc['project_id'],kind=doc['kind'],path=doc['path'],changed=changed, - **{key:value[key] for key in ('revision','sha256','bytes','adopted_at')}) - if value.get('deleted') is True:result['deleted']=True - return result - - -def _validate_result(operation,result,lookup=None): - if operation=='files.adopt_many': - closed(result,{'items','changed_count'},'batch adoption result') - if type(result['items']) is not list or not 1<=len(result['items'])<=MAX_ADOPT_ITEMS: - fail('Invalid batch adoption result size.') - seen=set();projects=set() - for item in result['items']: - _validate_result('files.adopt',item,lookup) - if item['id'] in seen:fail('Batch adoption result repeats a file.') - seen.add(item['id']);projects.add(item['project_id']) - if (len(projects)!=1 or type(result['changed_count']) is not int - or result['changed_count']!=sum(item['changed'] for item in result['items']) - or sum(item['bytes'] for item in result['items'])>MAX_ADOPT_BYTES): - fail('Batch adoption result count or project differs.') - return True - if operation not in ('files.adopt','files.adopt_deletion'):return False - deleted=operation=='files.adopt_deletion' - closed(result,RESULT_FIELDS|{'deleted'} if deleted else RESULT_FIELDS,'adoption result') - if result['id']!=file_id(result['project_id'],result['kind'],result['path']) or type(result['changed']) is not bool:fail('Invalid adoption result identity.') - if deleted: - if result['deleted'] is not True or result['kind']!='note' or result['sha256'] is not None or result['bytes']!=0 or result['changed'] is not True or type(result['revision']) is not int or result['revision']<2: - fail('Invalid deleted note result.') - else:sha(result['sha256']) - _date(result['adopted_at']) - if type(result['revision']) is not int or not 1<=result['revision']<=2**53-1 or type(result['bytes']) is not int or not 0<=result['bytes']<=MAX_FILE_BYTES:fail('Invalid adoption result bounds.') - if lookup is not None: - envelope=lookup(result['id']) - if envelope is None or not any((value.get('deleted') is True)==deleted and all(value[key]==result[key] for key in ('revision','sha256','bytes','adopted_at')) for value in envelope['document']['history']): - fail('Adoption result is not an exact retained working-file revision.') - return True - - -def receipt_validator(records): - """Own one decoded candidate's file histories for its receipt checks. - - The returned validator has no live Session or publication authority. It - owns copied records, so caller mutation cannot change this fixed view. - A different candidate requires a new validator. - """ - owned = {record['id']: record for record in decode_records(records)} - return partial(_validate_result, lookup=owned.get) - - -def validate_operation_result(operation, result, records=None): - # Keep standalone shape/error ordering, and share only this call's lookup - # across batch items. There is no retained cache between invocations. - @cache - def owned(): - return {record['id']: record for record in decode_records(records)} - lookup = None if records is None else lambda identity: owned().get(identity) - return _validate_result(operation, result, lookup) - - -class _WorkingError(Exception): - def __init__(self,state):self.state=state - - -def _missing(root,parts): - """Confirm absence beneath the actual root, never through an unsafe alias.""" - parents=[os.dup(root)];missing=None - try: - for part in parts[:-1]: - try:child=os.open(part,DIR_FLAGS,dir_fd=parents[-1]) - except FileNotFoundError: - missing=part;break - parents.append(child) - if missing is None: - try: - entry=os.stat(parts[-1],dir_fd=parents[-1],follow_symlinks=False) - if not stat.S_ISREG(entry.st_mode) or entry.st_nlink!=1:raise _WorkingError('unsafe_path') - except FileNotFoundError:missing=parts[-1] - for index in range(1,len(parents)): - entry=os.stat(parts[index-1],dir_fd=parents[index-1],follow_symlinks=False) - if not os.path.samestat(entry,os.fstat(parents[index])):raise _WorkingError('unstable') - if missing is not None: - try:os.stat(missing,dir_fd=parents[-1],follow_symlinks=False) - except FileNotFoundError:return True - raise _WorkingError('unstable') - return False - except OSError as error: - state='unsafe_path' if error.errno in (errno.ELOOP,errno.ENOTDIR) else 'unstable' if error.errno==errno.ENOENT else 'unreadable' - raise _WorkingError(state) from None - finally: - for descriptor in reversed(parents):os.close(descriptor) - - -def _read(root,parts): - parent=os.dup(root);descriptor=None - try: - for part in parts[:-1]: - child=os.open(part,DIR_FLAGS,dir_fd=parent);os.close(parent);parent=child - descriptor=os.open(parts[-1],os.O_RDONLY|os.O_NOFOLLOW|os.O_CLOEXEC|os.O_NONBLOCK,dir_fd=parent) - before=os.fstat(descriptor) - if not stat.S_ISREG(before.st_mode) or before.st_nlink!=1:raise _WorkingError('unsafe_path') - if before.st_size>MAX_FILE_BYTES:raise _WorkingError('too_large') - chunks=[];total=0 - while True: - block=os.read(descriptor,min(65536,MAX_FILE_BYTES+1-total)) - if not block:break - chunks.append(block);total+=len(block) - if total>MAX_FILE_BYTES:raise _WorkingError('too_large') - after=os.fstat(descriptor);entry=os.stat(parts[-1],dir_fd=parent,follow_symlinks=False) - fields=lambda value:(value.st_dev,value.st_ino,value.st_mode,value.st_nlink,value.st_size,value.st_mtime_ns,value.st_ctime_ns) - if fields(before)!=fields(after) or fields(after)!=fields(entry):raise _WorkingError('unstable') - current=os.dup(root) - try: - for part in parts[:-1]: - child=os.open(part,DIR_FLAGS,dir_fd=current);os.close(current);current=child - if (os.fstat(current).st_dev,os.fstat(current).st_ino)!=(os.fstat(parent).st_dev,os.fstat(parent).st_ino): - raise _WorkingError('unstable') - finally:os.close(current) - raw=b''.join(chunks) - try:text=raw.decode('utf-8') - except UnicodeDecodeError:raise _WorkingError('invalid_utf8') from None - return text,digest(raw),len(raw) - except OSError as error: - state='missing' if error.errno==errno.ENOENT else 'unsafe_path' if error.errno in (errno.ELOOP,errno.ENOTDIR) else 'unreadable' - raise _WorkingError(state) from None - finally: - if descriptor is not None:os.close(descriptor) - os.close(parent) - - -def inspect_captured(records, project_id, root): - """Observe captured working files using only a locked project capability.""" - return _inspect_validated(decode_records(records), project_id, root) - - -def _inspect_validated(records, project_id, root): - """Consume full-decoder output or fresh values from a validated Session.""" - owned=[r for r in records if r['document']['project_id']==project_id] - items=[] - for envelope in sorted(owned,key=lambda r:r['document']['path']): - doc=envelope['document'];value=doc['current'] - observation=dict(id=envelope['id'],kind=doc['kind'],path=doc['path'],revision=value['revision'], - expected_sha256=value['sha256'],expected_bytes=value['bytes'],observed_sha256=None,observed_bytes=None,state='missing',reason=None) - try: - parts=_path(doc['kind'],doc['path']) - if value.get('deleted') is True and _missing(root,parts): - observation['state']='deleted' - else: - if value.get('deleted') is True:observation['state']='changed' - _,observed,size=_read(root,parts) - observation.update(observed_sha256=observed,observed_bytes=size,state='unchanged' if observed==value['sha256'] else 'changed') - except _WorkingError as error: - if value.get('deleted') is True: - observation.update(state='changed' if error.state in ('invalid_utf8','too_large') else 'invalid',reason=error.state) - else:observation.update(state='missing' if error.state=='missing' else 'invalid',reason=error.state) - items.append(observation) - return items - - -class ProjectFiles: - def __init__(self,session): - self.session,self.access,self.db,self.store=session,session.access,session.db,session.store - - def inspect(self): - with self.access.lock,self.session.lock,self.db.lock: - self.access.require('inspect','files.inspect');snapshot=self.session.check_records(FAMILY) - with self.store.root_directory() as root: - items=_inspect_validated(snapshot['records'],snapshot['project_id'],root) - self.session.check_current() - return dict(items=items,project_id=snapshot['project_id'],checkpoint=snapshot['checkpoint']) - - def read(self,record_id,revision=None): - with self.access.lock,self.session.lock,self.db.lock: - self.access.require('inspect','files.read',record_id);snapshot=self.session.check_records(FAMILY) - envelope=next((r for r in snapshot['records'] if r['id']==record_id),None) - if envelope is None:fail('Adopted working file is unavailable.','unavailable',404) - values=envelope['document']['history'] - if revision is None:value=values[-1] - elif type(revision) is int and 1<=revision<=len(values):value=values[revision-1] - else:fail('Adopted working-file revision is unavailable.','unavailable',404) - return dict(id=record_id,project_id=envelope['document']['project_id'],kind=envelope['document']['kind'],path=envelope['document']['path'],version=copy.deepcopy(value)) - - def history(self,record_id): - with self.access.lock,self.session.lock,self.db.lock: - self.access.require('inspect','files.history',record_id);snapshot=self.session.check_records(FAMILY) - envelope=next((r for r in snapshot['records'] if r['id']==record_id),None) - if envelope is None:fail('Adopted working file is unavailable.','unavailable',404) - return copy.deepcopy(envelope['document']['history']) - - def require_clean(self): - """Save As must not silently discard unadopted or missing source files.""" - report=self.inspect() - if any(item['state'] not in ('unchanged','deleted') for item in report['items']): - error=WorkbenchError('Adopt or restore changed, missing or invalid working files before Save As.','working_files_changed',409) - error.report=report - raise error - return report - - @staticmethod - def materialize_captured(records,project_id,root_fd): - return materialize_captured(records,project_id,root_fd) - - def _adoption_intent(self,body): - closed(body,{'kind','path','expected_revision','expected_sha256'},'working-file adoption') - parts=_path(body['kind'],body['path']);project_id=self.session.summary['project_id'];record_id=file_id(project_id,body['kind'],body['path']);sha(body['expected_sha256']) - if type(body['expected_revision']) is not int or not 0<=body['expected_revision']<=2**53-1:fail('Invalid expected adoption revision.') - return dict(body),parts,record_id - - def _capture_adoption(self,intent,prior,root): - body,parts,record_id=intent - revision=prior['document']['current']['revision'] if prior else 0 - if revision!=body['expected_revision']:fail('Working-file adoption revision changed.','conflict',409) - try:text,observed,size=_read(root,parts) - except _WorkingError as error:fail('Working file is '+error.state+'.','unavailable' if error.state=='missing' else 'invalid',404 if error.state=='missing' else 400) - if observed!=body['expected_sha256']:fail('Working file changed after review.','conflict',409) - if prior is not None and observed==prior['document']['current']['sha256']:return _result(prior,False),None,size - actor=self.access.require('edit','files.adopt',record_id) - value=dict(revision=revision+1,sha256=observed,bytes=size,text=text,adopted_at=timestamp(),actor_id=actor.actor_id) - history=copy.deepcopy(prior['document']['history']) if prior else [];history.append(value) - envelope=dict(family=FAMILY,id=record_id,document=dict(format=prior['document']['format'] if prior else FORMAT, - project_id=self.session.summary['project_id'],kind=body['kind'],path=body['path'],current=copy.deepcopy(value), - history=history,origin=copy.deepcopy(prior['document']['origin']) if prior else None)) - return _result(envelope,True),envelope,size - - def adopt(self,body,expected_checkpoint,key): - intent=self._adoption_intent(body);body,parts,record_id=intent;project_id=self.session.summary['project_id'] - pending=[] - with self.access.lock: - self.access.require('edit','files.adopt',record_id) - def invoke(): - snapshot=self.session.snapshot;owned=[r for r in decode_records(snapshot['records']) if r['document']['project_id']==project_id] - prior=next((r for r in owned if r['id']==record_id),None) - if prior is None and len(owned)>=MAX_FILES:fail('Project already tracks 1,000 working files.','too_large',413) - with self.store.root_directory() as root: - result,envelope,_=self._capture_adoption(intent,prior,root) - if envelope is not None: - decode_records([r for r in snapshot['records'] if not (r['family']==FAMILY and r['id']==record_id)]+[envelope]);pending.append(envelope) - return result - return self.session.mutate('files.adopt',record_id,body,expected_checkpoint,key,invoke, - lambda result,before:dict(records=copy.deepcopy(pending),result=copy.deepcopy(result))) - - def adopt_many(self,body,expected_checkpoint,key): - """Capture one bounded, all-or-nothing group through ordinary adoption. - - Every file retains its permission/revision/hash and anchored read checks. - One verified root scope and one canonical publication cover the group. - No working file is rewritten, even when another input rejects the group. - """ - closed(body,{'items'},'batch working-file adoption') - if type(body['items']) is not list or not 1<=len(body['items'])<=MAX_ADOPT_ITEMS: - fail('Choose 1 through 40 working files for adoption.','too_large',413) - intents=[self._adoption_intent(item) for item in body['items']] - ids=[intent[2] for intent in intents] - if len(set(ids))!=len(ids):fail('Batch adoption repeats a working-file path.') - body=dict(items=[intent[0] for intent in intents]);project_id=self.session.summary['project_id'] - target=digest('\0'.join(ids).encode());pending=[] - with self.access.lock: - for identity in ids:self.access.require('edit','files.adopt',identity) - def invoke(): - snapshot=self.session.snapshot - owned={r['id']:r for r in decode_records(snapshot['records']) if r['document']['project_id']==project_id} - if len(owned)+sum(identity not in owned for identity in ids)>MAX_FILES: - fail('Project already tracks 1,000 working files.','too_large',413) - results=[];total=0 - with self.store.root_directory(verify_after=True) as root: - for intent in intents: - result,envelope,size=self._capture_adoption(intent,owned.get(intent[2]),root) - total+=size - if total>MAX_ADOPT_BYTES:fail('Batch working-file capture exceeds 8 MiB.','too_large',413) - if envelope is not None:pending.append(envelope) - results.append(result) - changed={r['id'] for r in pending} - decode_records([r for r in snapshot['records'] if not (r['family']==FAMILY and r['id'] in changed)]+pending) - return dict(items=results,changed_count=sum(item['changed'] for item in results)) - return self.session.mutate('files.adopt_many',target,body,expected_checkpoint,key,invoke, - lambda result,before:dict(records=copy.deepcopy(pending),result=copy.deepcopy(result))) - - def adopt_deletion(self,body,expected_checkpoint,key): - closed(body,{'path','expected_revision','expected_sha256'},'note deletion adoption') - parts=_path('note',body['path']);sha(body['expected_sha256']) - if type(body['expected_revision']) is not int or not 1<=body['expected_revision']<=2**53-1:fail('Invalid expected note revision.') - project_id=self.session.summary['project_id'];record_id=file_id(project_id,'note',body['path']);pending=[] - with self.access.lock: - self.access.require('edit','files.adopt_deletion',record_id) - def invoke(): - snapshot=self.session.snapshot - prior=next((r for r in decode_records(snapshot['records']) if r['id']==record_id),None) - if prior is None:fail('Only an already adopted note can acquire a deletion.','unavailable',404) - current=prior['document']['current'] - if current['revision']!=body['expected_revision'] or current['sha256']!=body['expected_sha256'] or current.get('deleted') is True: - fail('Canonical note revision or digest changed.','conflict',409) - with self.store.root_directory() as root: - try:missing=_missing(root,parts) - except _WorkingError as error:fail('Note path is '+error.state+'.','invalid',400) - if not missing:fail('The reviewed note still exists; deletion cannot be adopted.','conflict',409) - actor=self.access.require('edit','files.adopt_deletion',record_id) - value=dict(revision=current['revision']+1,deleted=True,sha256=None,bytes=0,text=None, - adopted_at=timestamp(),actor_id=actor.actor_id) - envelope=copy.deepcopy(prior);doc=envelope['document'] - doc['format']=DELETION_FORMAT;doc['history'].append(value);doc['current']=copy.deepcopy(value) - decode_records([r for r in snapshot['records'] if not (r['family']==FAMILY and r['id']==record_id)]+[envelope]);pending.append(envelope) - return _result(envelope,True) - return self.session.mutate('files.adopt_deletion',record_id,body,expected_checkpoint,key,invoke, - lambda result,before:dict(records=copy.deepcopy(pending),result=copy.deepcopy(result))) - - -def _validate_forks(owned,records): - indexed={r['id']:r for r in owned} - overlays=[r['document'] for r in records if r.get('family')=='project_fork'] - if overlays: - from project_fork import decode_fork - decode_fork(records) - for envelope in owned: - doc=envelope['document'];origin=doc['origin'] - if origin is None:continue - closed(origin,{'project_id','checkpoint','id','revision'},'working-file fork origin') - _project_id(origin['project_id']);sha(origin['checkpoint']);sha(origin['id']) - if type(origin['revision']) is not int or not 1<=origin['revision']<=2**53-1:fail('Invalid original working-file revision.') - original=indexed.get(origin['id']) - if original is None:fail('Working-file fork original is unavailable.') - source=original['document'] - if source['project_id']!=origin['project_id'] or source['kind']!=doc['kind'] or source['path']!=doc['path'] or source['current']['revision']!=origin['revision']: - fail('Working-file fork origin differs from its exact archived source.') - mapping=dict(family=FAMILY,source_id=origin['id'],source_revision=origin['revision'],destination_id=envelope['id']) - matches=[o for o in overlays if o['source']==dict(project_id=origin['project_id'],checkpoint=origin['checkpoint']) and o['destination_project_id']==doc['project_id'] and mapping in o['mapping']] - if len(matches)!=1 or doc['history'][:origin['revision']]!=source['history']: - fail('Working-file fork requires its exact archived history and origin mapping.') - - -def fork_records(records,source_project_id,source_checkpoint,destination_project_id): - """Independent file identity; preserve actual historical adoptions exactly.""" - _project_id(source_project_id);_project_id(destination_project_id);sha(source_checkpoint) - if source_project_id==destination_project_id:fail('An independent working-file fork needs a new project.') - decoded=decode_records(records) - from project_fork import active_records - active={(r['family'],r['id']) for r in active_records(records,project_id=source_project_id)} - owned=[r for r in decoded if (r['family'],r['id']) in active] - made=[];mapping=[] - for envelope in owned: - doc=envelope['document'] - if doc['project_id']!=source_project_id:fail('Current working-file scope differs from the selected project.') - new_id=file_id(destination_project_id,doc['kind'],doc['path']) - if any(r['family']==FAMILY and r['id']==new_id for r in records):fail('Working-file destination identity already exists.') - fresh=copy.deepcopy(envelope);fresh['id']=new_id - fresh['document'].update(project_id=destination_project_id,origin=dict(project_id=source_project_id,checkpoint=source_checkpoint,id=envelope['id'],revision=doc['current']['revision'])) - made.append(fresh);mapping.append(dict(family=FAMILY,source_id=envelope['id'],source_revision=doc['current']['revision'],destination_id=new_id)) - made.sort(key=lambda r:r['id']);mapping.sort(key=lambda m:(m['family'],m['source_id'],m['source_revision'],m['destination_id'])) - return dict(records=made,mapping=mapping) - - -def materialize_captured(records,project_id,root_fd): - """Write exact declared text only into the caller's new staging capability. - - The fork owner verifies destination non-overlap and owns all staging cleanup - and publication. O_EXCL never replaces an existing working file. A partial - failed staging tree is not a published fork and must not be acknowledged. - """ - _project_id(project_id) - if type(root_fd) is not int or not stat.S_ISDIR(os.fstat(root_fd).st_mode):fail('A staging directory capability is required.') - owned=[r for r in decode_records(records) if r['document']['project_id']==project_id] - copied=[] - try: - for envelope in sorted(owned,key=lambda r:r['document']['path']): - doc=envelope['document'];value=doc['current'];parts=_path(doc['kind'],doc['path']) - if value.get('deleted') is True:continue - parent=os.dup(root_fd);descriptor=None - try: - for part in parts[:-1]: - try:os.mkdir(part,0o700,dir_fd=parent);os.fsync(parent) - except FileExistsError:pass - child=os.open(part,DIR_FLAGS,dir_fd=parent);os.close(parent);parent=child - descriptor=os.open(parts[-1],os.O_WRONLY|os.O_CREAT|os.O_EXCL|os.O_NOFOLLOW|os.O_CLOEXEC,0o600,dir_fd=parent) - captured=os.fstat(descriptor) - if not stat.S_ISREG(captured.st_mode) or captured.st_nlink!=1:fail('Unsafe staging working file.') - raw=value['text'].encode('utf-8');remaining=memoryview(raw) - while remaining: - count=os.write(descriptor,remaining) - if count<=0:raise OSError(errno.EIO,'Working-file staging write failed') - remaining=remaining[count:] - os.fsync(descriptor) - entry=os.stat(parts[-1],dir_fd=parent,follow_symlinks=False) - after=os.fstat(descriptor) - if (entry.st_dev,entry.st_ino,entry.st_nlink,entry.st_size)!=(captured.st_dev,captured.st_ino,1,len(raw)) or after.st_size!=len(raw):fail('Working-file staging entry changed.','stale_project',409) - check=os.dup(root_fd) - try: - for part in parts[:-1]: - child=os.open(part,DIR_FLAGS,dir_fd=check);os.close(check);check=child - if (os.fstat(check).st_dev,os.fstat(check).st_ino)!=(os.fstat(parent).st_dev,os.fstat(parent).st_ino):fail('Working-file staging directory changed.','stale_project',409) - finally:os.close(check) - os.fsync(parent) - copied.append(dict(id=envelope['id'],path=doc['path'],sha256=value['sha256'],bytes=value['bytes'])) - finally: - if descriptor is not None:os.close(descriptor) - os.close(parent) - os.fsync(root_fd) - except OSError: - fail('Working-file staging failed; no complete fork was published.','storage',500) - return copied diff --git a/project_fork.py b/project_fork.py deleted file mode 100644 index f35b9812..00000000 --- a/project_fork.py +++ /dev/null @@ -1,529 +0,0 @@ -"""Independent fork publication and its explicit inert-origin overlay. - -Domain owners construct new editable values and their revision-specific origin -mappings. This owner never rewrites domain documents. It preserves source -records, verifies declared payload custody, and atomically publishes a complete -new directory. Runtime quiescence and current authorization belong to the caller. -""" -import copy -import errno -import hashlib -import os -import re -import stat -import uuid - -from project_artifacts import ProjectArtifacts, validate_declaration -from project_store import (ProjectStore, ProjectStoreError, REQUEST_KEY, anchored_directory, - DIR_FLAGS, _encode, _identifier, _physical, _relative_parts, - _rename_noreplace, _walk) - -FAMILY = 'project_fork' -FORMAT = 'project_fork_v1' -# Immutable scientific evidence stays origin-scoped and inspectable. Only these -# formerly active values/receipts become inactive through the fork overlay. -ARCHIVE_FAMILIES = frozenset(('workbench_text', 'workbench_record', 'workbench_response', - 'workbench_preference', 'saved_selection', 'saved_search', 'model_definition', - 'pipeline_graph', 'recipe_definition', 'project_file', 'project_operation', 'project_composition', FAMILY)) -ID = re.compile(r'^[a-f0-9]{32}$') -SHA = re.compile(r'^[a-f0-9]{64}$') - - -class ProjectForkError(ProjectStoreError): - pass - - -def _fail(message, code='invalid', status=400): - raise ProjectForkError(message, code, status) - - -def _shape(value, fields, label): - if type(value) is not dict or set(value) != set(fields): - _fail('Invalid fork ' + label + ' fields.') - - -def _uuid(value): - if type(value) is not str or not ID.fullmatch(value): - _fail('Fork project identity must be a UUID.') - - -def _sha(value): - if type(value) is not str or not SHA.fullmatch(value): - _fail('Fork checkpoint must be a SHA256 digest.') - - -def _input(source, directory, name, key): - return dict(source=source, directory=directory, name=name, request_key=key) - - -def _digest(value): - return hashlib.sha256(_encode(value)).hexdigest() - - -def _locator(value): - _shape(value, ('family', 'id'), 'archive locator') - _identifier(value['family'], 'Fork record family') - _identifier(value['id'], 'Fork record ID') - return value['family'], value['id'] - - -def _mapping_key(value): - return value['family'], value['source_id'], value['source_revision'] or 0, value['destination_id'] - - -def _decode_document(value, identity, indexed): - _shape(value, ('format', 'source', 'destination_project_id', 'request_key', 'request_sha256', - 'directory', 'name', 'mapping', 'archived', 'artifacts'), 'origin overlay') - if value['format'] != FORMAT: - _fail('Unsupported fork overlay format.', 'unsupported', 422) - _shape(value['source'], ('project_id', 'checkpoint'), 'source identity') - _uuid(value['source']['project_id']) - _sha(value['source']['checkpoint']) - _uuid(value['destination_project_id']) - if identity != value['destination_project_id'] or identity == value['source']['project_id']: - _fail('Fork source and destination identities must be independent.') - if type(value['request_key']) is not str or not REQUEST_KEY.fullmatch(value['request_key']): - _fail('Invalid fork request key.') - _sha(value['request_sha256']) - _relative_parts(value['directory']) - if type(value['name']) is not str or not value['name'].strip() or len(value['name']) > 200: - _fail('Invalid fork display name.') - if value['request_sha256'] != _digest(_input(value['source'], value['directory'], value['name'], value['request_key'])): - _fail('Fork request receipt differs from its exact input.') - if type(value['archived']) is not list: - _fail('Fork archive inventory must be a list.') - archived = [_locator(item) for item in value['archived']] - if archived != sorted(set(archived)) or any(key not in indexed for key in archived): - _fail('Fork archive must be sorted, unique and refer to retained records.') - if (FAMILY, identity) in archived: - _fail('Current fork overlay cannot archive itself.') - archived = set(archived) - if type(value['mapping']) is not list: - _fail('Fork mappings must be a list.') - sources, destinations, keys = set(), set(), [] - for item in value['mapping']: - _shape(item, ('family', 'source_id', 'source_revision', 'destination_id'), 'editable mapping') - _identifier(item['family'], 'Fork mapping family') - _identifier(item['source_id'], 'Fork source record ID') - _identifier(item['destination_id'], 'Fork destination record ID') - revision = item['source_revision'] - if revision is not None and (type(revision) is not int or revision < 1): - _fail('Fork source revision must be positive or null.') - source = (item['family'], item['source_id']) - destination_family = 'workbench_record' if item['family'] == 'workbench_text' else item['family'] - destination = (destination_family, item['destination_id']) - if (source not in archived or destination not in indexed or destination in archived or - item['source_id'] == item['destination_id'] or (source, revision) in sources or destination in destinations): - _fail('Fork mapping must bind an archived source revision to a unique new current record.') - sources.add((source, revision)) - destinations.add(destination) - keys.append(_mapping_key(item)) - if keys != sorted(keys): - _fail('Fork mappings must be sorted.') - _shape(value['artifacts'], ('copied', 'missing_regenerable'), 'artifact completeness') - listed = set() - for field in ('copied', 'missing_regenerable'): - items = value['artifacts'][field] - if type(items) is not list: - _fail('Fork artifact completeness must use lists.') - for digest in items: - _sha(digest) - if items != sorted(set(items)) or listed.intersection(items): - _fail('Fork artifact completeness must be disjoint, sorted and unique.') - if any(('project_artifact', digest) not in indexed for digest in items): - _fail('Fork payload completeness has no intrinsic declaration.') - listed.update(items) - return archived - - -def decode_fork(records, *, project_id=None): - """Decode the one current overlay; originals remain independently validated. - - Pure owner decoders consume all records for historical closure. Projection - and receipt owners use active_records only when constructing current state. - """ - if type(records) is not list: - _fail('Fork records must be a list.') - indexed, overlays = {}, {} - for item in records: - _shape(item, ('family', 'id', 'document'), 'record envelope') - _identifier(item['family'], 'Fork record family') - _identifier(item['id'], 'Fork record ID') - key = item['family'], item['id'] - if key in indexed: - _fail('Duplicate fork record identity.') - indexed[key] = item - if item['family'] == FAMILY: - overlays[key] = item['document'] - if project_id is not None: - _uuid(project_id) - if not overlays: - return None - archives = {key: _decode_document(doc, key[1], indexed) for key, doc in overlays.items()} - archived_overlays = {key for values in archives.values() for key in values if key[0] == FAMILY} - candidates = set(overlays) - archived_overlays - if len(candidates) != 1: - _fail('Fork history must have exactly one current origin overlay.') - current = next(iter(candidates)) - if project_id is not None and current[1] != project_id: - _fail('Fork overlay belongs to a different current project.') - archive = archives[current] - for key, previous in archives.items(): - if key != current and (key not in archive or not previous <= archive): - _fail('Current fork must preserve all prior archived dispositions.') - return copy.deepcopy(overlays[current]) - - -def active_records(records, *, project_id=None, families=None): - """Own selected active copies while validating the complete fork history.""" - if families is not None: - if type(families) is not frozenset: - _fail('Active record families must be an explicit frozenset.') - for family in families:_identifier(family,'Active record family') - overlay = decode_fork(records, project_id=project_id) - archived = set() if overlay is None else {(item['family'], item['id']) for item in overlay['archived']} - return [copy.deepcopy(item) for item in records - if (families is None or item['family'] in families) and (item['family'], item['id']) not in archived] - - -def _inside(candidate_fd, ancestor_fd): - """Compare physical ancestry, including directory aliases; never string-prefix.""" - current = os.dup(candidate_fd) - try: - expected = _physical(ancestor_fd) - while True: - if _physical(current) == expected: - return True - parent = os.open('..', DIR_FLAGS, dir_fd=current) - if _physical(parent) == _physical(current): - os.close(parent) - return False - os.close(current) - current = parent - finally: - os.close(current) - - -def _declarations(records): - result = {} - for item in records: - if item['family'] == 'project_artifact': - value = validate_declaration(item['document']) - if item['id'] != value['sha256'] or item['id'] in result: - _fail('Fork artifact declaration identity differs or repeats.') - result[item['id']] = value - return result - - -def _artifact_plan(items, declarations): - if type(items) is not list: - _fail('Fork requires an explicit payload preservation plan.') - plan = {} - for item in items: - _shape(item, ('declaration', 'preservation'), 'payload preservation edge') - value = validate_declaration(item['declaration']) - if item['preservation'] not in ('unique', 'regenerable') or declarations.get(value['sha256']) != value: - _fail('Fork payload policy refers to an undeclared or changed artifact.') - previous = plan.get(value['sha256']) - if previous is None or item['preservation'] == 'unique': - plan[value['sha256']] = item['preservation'] - if set(plan) != set(declarations): - _fail('Every retained artifact declaration needs an explicit fork preservation disposition.') - return plan - - -def _source_current(store, source): - current = store.snapshot() - if current['project_id'] != source['project_id'] or current['checkpoint'] != source['checkpoint']: - _fail('Source project changed during fork preparation.', 'stale', 409) - - -def _result(snapshot, overlay, reconciled): - return dict(snapshot=copy.deepcopy(snapshot), fork=copy.deepcopy(overlay), reconciled=reconciled) - - -def _reconcile_existing(sources, trusted_root_fd, relative, root_path, - expected_input, request_key, digest, validate_candidate, *, composed): - with ProjectStore.open_at(trusted_root_fd, relative, root_path=root_path) as destination: - snapshot = destination.snapshot() - overlay = decode_fork(snapshot['records'], project_id=snapshot['project_id']) - if composed: - from project_composition import decode_records, composition_input - document = decode_records(snapshot['records'],project_id=snapshot['project_id']).get(snapshot['project_id']) - observed_input = None if document is None else composition_input(document['sources'],document['directory'],document['name'],document['request_key']) - observed_digest = None if document is None else document['request_sha256'] - else: - observed_input = None if overlay is None else _input(overlay['source'],overlay['directory'],overlay['name'],overlay['request_key']) - observed_digest = None if overlay is None else overlay['request_sha256'] - if observed_input != expected_input or observed_digest != digest: - _fail('Existing destination does not belong to this exact fork request.', 'conflict', 409) - if destination.reconcile(request_key, digest) is None: - _fail('Existing destination lacks the canonical fork publication receipt.', 'conflict', 409) - declarations = _declarations(snapshot['records']) - with ProjectArtifacts(destination) as artifacts: - validate_candidate(copy.deepcopy(snapshot['records']),snapshot['project_id'],artifacts) - for identity in overlay['artifacts']['copied']: - if artifacts.status(declarations[identity])['state'] != 'verified': - _fail('Previously copied fork payloads are missing or corrupt.', 'unavailable', 409) - for item in sources: - _source_current(item['store'],item['identity']) - destination.save(snapshot['checkpoint']) - result = _result(destination.snapshot(),overlay,True) - if composed:result['composition']=copy.deepcopy(document) - return result - - -def publish_fork(source_store, source_artifacts, trusted_root_fd, relative, *, root_path, - name, expected_checkpoint, request_key, quiescent, build_candidate, - validate_candidate): - """Publish an independent single-source fork through the shared lifecycle.""" - if not callable(validate_candidate): - _fail('Fork requires complete validation.','unavailable',503) - return _publish_project(source_store,source_artifacts,trusted_root_fd,relative, - root_path=root_path,name=name,expected_checkpoint=expected_checkpoint,request_key=request_key, - quiescent=quiescent,build_candidate=build_candidate, - validate_candidate=lambda records,identity,_artifacts:validate_candidate(records,identity)) - - -def recover_committed_publication(trusted_root_fd, staging, relative, *, root_path, - expected_project_id, expected_checkpoint, - expected_request, quiescent): - """Publish one explicitly selected committed stage without rebuilding it. - - This operator recovery accepts a frozen historical snapshot, not a new read - of its original sources. The caller owns current filesystem authority and - cessation of the former process. The store's exclusive root lock, complete - domain validation, exact original request/commit receipt, payload custody, - and clean captured files are required before a no-overwrite rename. No SQL - projection, source permission, source runtime or worker is restored here. - After an uncertain rename, repeat this exact recovery to inspect the final - destination; never repeat composition or create another stage. - """ - if quiescent is not True: - _fail('Recovery requires proven cessation of the former publication owner.', 'busy', 409) - _uuid(expected_project_id);_sha(expected_checkpoint) - stage_parts=_relative_parts(staging);parts=_relative_parts(relative) - if (stage_parts[:-1]!=parts[:-1] - or not re.fullmatch(r'\.tuldok-fork-[a-f0-9]{32}',stage_parts[-1]) - or stage_parts==parts): - _fail('Recovery requires an explicit fork stage beside its original destination.') - if type(expected_request) is not dict or expected_request.get('directory')!=relative: - _fail('Recovery requires the exact original publication request.') - key=expected_request.get('request_key') - if type(key) is not str or not REQUEST_KEY.fullmatch(key): - _fail('Recovery requires the original publication request key.') - digest=_digest(expected_request) - published=False - try: - with anchored_directory(trusted_root_fd,'/'.join(parts[:-1]),root_path=root_path) as parent: - def exists(name): - try:os.stat(name,dir_fd=parent,follow_symlinks=False);return True - except FileNotFoundError:return False - stage_exists,final_exists=exists(stage_parts[-1]),exists(parts[-1]) - if stage_exists and final_exists: - _fail('Both stage and destination exist; neither was replaced.', 'conflict', 409) - if not stage_exists and not final_exists: - _fail('Neither the selected stage nor its destination is available.', 'unavailable', 409) - selected=relative if final_exists else staging - with ProjectStore.open_at(trusted_root_fd,selected,root_path=root_path) as store: - snapshot=store.snapshot() - if (snapshot['project_id']!=expected_project_id - or snapshot['checkpoint']!=expected_checkpoint): - _fail('Recovery project identity or checkpoint differs.', 'stale', 409) - overlay=decode_fork(snapshot['records'],project_id=expected_project_id) - if overlay is None:_fail('Recovery requires a committed independent publication.') - from project_composition import decode_records, composition_input - composition=decode_records(snapshot['records'],project_id=expected_project_id).get(expected_project_id) - observed=(composition_input(composition['sources'],composition['directory'],composition['name'],composition['request_key']) - if composition is not None else _input(overlay['source'],overlay['directory'],overlay['name'],overlay['request_key'])) - if observed!=expected_request or store.reconcile(key,digest) is None: - _fail('Committed stage does not match the original request and receipt.', 'conflict', 409) - from project_projection import validate_project_records - from project_files import inspect_captured - declarations=_declarations(snapshot['records']) - with ProjectArtifacts(store) as artifacts: - validate_project_records(snapshot['records'],project_id=expected_project_id,artifacts=artifacts) - checks=artifacts.status_many([declarations[identity] for identity in overlay['artifacts']['copied']]) - if any(item['state']!='verified' for item in checks): - _fail('Committed publication payloads are missing or corrupt.', 'unavailable', 409) - with store.root_directory() as project_root: - if any(item['state'] not in ('unchanged','deleted') - for item in inspect_captured(snapshot['records'],expected_project_id,project_root)): - _fail('Committed stage has changed or missing working files.', 'working_files_changed', 409) - store.save(expected_checkpoint) - if not final_exists: - # Recheck the selected directory entry while the store root - # remains locked; an external rename must not substitute it. - with store.root_directory() as project_root: - entry=os.stat(stage_parts[-1],dir_fd=parent,follow_symlinks=False) - actual=os.fstat(project_root) - if (entry.st_dev,entry.st_ino)!=(actual.st_dev,actual.st_ino): - _fail('Selected stage directory changed.', 'stale', 409) - _rename_noreplace(parent,stage_parts[-1],parts[-1]);published=True - os.fsync(parent) - return dict(project_id=expected_project_id,checkpoint=expected_checkpoint, - directory=relative,request_key=key,reconciled=final_exists, - payloads_copied=0,selected=False) - except BaseException as error: - # Anchored directory owners also translate IO failures. Preserve the - # uncertain post-rename outcome through either exception representation. - if published: - raise ProjectForkError('Committed publication was renamed but acknowledgement is uncertain; reconcile this exact recovery.', - 'unknown',503) from error - if isinstance(error,OSError): - code='conflict' if error.errno==errno.EEXIST else 'unavailable' - raise ProjectForkError('Committed publication recovery is unavailable; no stage was rebuilt.', - code,503 if code!='conflict' else 409) from error - raise - - -def _publish_project(source_store, source_artifacts, trusted_root_fd, relative, *, root_path, - name, expected_checkpoint, request_key, quiescent, build_candidate, - validate_candidate, retained_sources=()): - """One native stage/commit/no-clobber lifecycle for forks and composition. - - The workspace owns authorization, quiescence and all borrowed source owners. - Every source is pinned and rechecked. Composed candidates additionally prove - complete source provenance. Validators receive the actual source/destination - artifact owner; no imported runtime, permission or source path is activated. - No failed or unknown stage is deleted or selected by this owner. - """ - if quiescent is not True: - _fail('Fork requires proven quiescence under the workspace lifecycle guard.', 'busy', 409) - if not callable(build_candidate) or not callable(validate_candidate): - _fail('Fork requires pure domain construction and complete validation.', 'unavailable', 503) - if type(retained_sources) not in (tuple,list):_fail('Explicit retained source owners required.') - if type(request_key) is not str or not REQUEST_KEY.fullmatch(request_key):_fail('Invalid fork request key.') - _sha(expected_checkpoint) - if type(name) is not str or not name.strip() or len(name)>200:_fail('Fork name must contain 1–200 characters.') - _encode(name);parts=_relative_parts(relative) - owners=[dict(store=source_store,artifacts=source_artifacts,checkpoint=expected_checkpoint)] - for item in retained_sources: - _shape(item,('store','artifacts','checkpoint'),'retained source owner') - _sha(item['checkpoint']);owners.append(dict(item)) - sources=[];snapshots=[];seen=set() - for item in owners: - snapshot=item['store'].snapshot() - if snapshot['checkpoint']!=item['checkpoint']:_fail('Expected source checkpoint changed.','stale',409) - if snapshot['project_id'] in seen:_fail('Retained source project identity repeats.','conflict',409) - seen.add(snapshot['project_id']) - validate_candidate(copy.deepcopy(snapshot['records']),snapshot['project_id'],item['artifacts']) - identity={key:snapshot[key] for key in ('project_id','checkpoint')} - sources.append(dict(store=item['store'],artifacts=item['artifacts'],identity=identity)) - snapshots.append(snapshot) - composed=bool(retained_sources);source=sources[0]['identity'] - if composed: - from project_composition import composition_input - expected_input=composition_input(snapshots,relative,name,request_key) - else:expected_input=_input(source,relative,name,request_key) - digest=_digest(expected_input) - source_roots=[];staged=artifacts=None;staging_relative=None;committed=None;published=False - def sources_current(): - for item in sources:_source_current(item['store'],item['identity']) - try: - for item in sources: - with item['store'].root_directory() as borrowed:source_roots.append(os.dup(borrowed)) - with anchored_directory(trusted_root_fd,'/'.join(parts[:-1]),root_path=root_path) as parent: - if any(_inside(parent,root) for root in source_roots):_fail('Fork destination cannot overlap any source project.') - try:existing=os.stat(parts[-1],dir_fd=parent,follow_symlinks=False) - except FileNotFoundError:existing=None - if existing is not None: - if not stat.S_ISDIR(existing.st_mode):_fail('Fork destination is an existing or unsafe filesystem object.','conflict',409) - selected=os.open(parts[-1],DIR_FLAGS,dir_fd=parent) - try: - if any(_inside(root,selected) or _inside(selected,root) for root in source_roots): - _fail('Fork destination aliases or overlaps a source project.') - finally:os.close(selected) - return _reconcile_existing(sources,trusted_root_fd,relative,root_path, - expected_input,request_key,digest,validate_candidate,composed=composed) - staging_name='.tuldok-fork-'+uuid.uuid4().hex - staging_relative='/'.join([*parts[:-1],staging_name]) - staged=ProjectStore.create_at(trusted_root_fd,staging_relative,name, - 'fork-stage.'+hashlib.sha256(request_key.encode()).hexdigest(),digest,root_path=root_path) - destination_id=staged.snapshot()['project_id'] - if destination_id in seen:_fail('Fork destination identity must be new.') - candidate=build_candidate(copy.deepcopy(snapshots if composed else snapshots[0]),destination_id) - _shape(candidate,('records','mapping','archived','artifacts'),'owned candidate') - if type(candidate['records']) is not list:_fail('Fork candidate records must be a list.') - records=copy.deepcopy(candidate['records']);indexed={} - for item in records: - _shape(item,('family','id','document'),'candidate envelope') - _identifier(item['family'],'Fork candidate family');_identifier(item['id'],'Fork candidate record ID') - key=item['family'],item['id'] - if key in indexed:_fail('Fork candidate repeats a record identity.') - indexed[key]=item - source_index={(r['family'],r['id']):r for snapshot in snapshots for r in snapshot['records']} - if composed: - from project_composition import validate_source_memberships - validate_source_memberships(records,snapshots,destination_id) - else: - for identity,original in source_index.items(): - if identity not in indexed or _encode(indexed[identity])!=_encode(original): - _fail('Fork must preserve every original canonical envelope exactly.') - archived=[_locator(item) for item in candidate['archived']] - if not set(archived)<=set(source_index):_fail('Fork may archive only retained source records.') - required={key for key in source_index if key[0] in ARCHIVE_FAMILIES} - for snapshot in snapshots: - previous=decode_fork(snapshot['records'],project_id=snapshot['project_id']) - if previous is not None:required.update(_locator(item) for item in previous['archived']) - if not required<=set(archived):_fail('Fork must archive every source editable value and operation receipt.') - declarations=_declarations(records);expected_declarations={} - for snapshot in snapshots: - for identity,value in _declarations(snapshot['records']).items(): - if identity in expected_declarations and expected_declarations[identity]!=value: - _fail('Source artifact declarations conflict.') - expected_declarations[identity]=value - if declarations!=expected_declarations:_fail('Fork must retain the source payload inventory without regenerating bytes.') - plan=_artifact_plan(candidate['artifacts'],declarations);selected={} - for number,item in enumerate(sources): - own=_declarations(snapshots[number]['records']);identities=sorted(own) - observations=item['artifacts'].status_many([own[key] for key in identities]) - for identity,observation in zip(identities,observations): - status=observation['state'] - if status=='corrupt':_fail('Source fork payload is corrupt.','invalid',400) - if status=='verified':selected.setdefault(identity,number) - elif status!='missing':_fail('Fork requires verified payload custody.','unavailable',409) - copied=sorted(selected);missing=sorted(set(plan)-set(selected)) - if any(plan[key]=='unique' for key in missing): - _fail('Irreplaceable source bytes are missing; complete fork is unavailable.','unavailable',409) - overlay=dict(format=FORMAT,source=source,destination_project_id=destination_id, - request_key=request_key,request_sha256=_digest(_input(source,relative,name,request_key)),directory=relative,name=name, - mapping=copy.deepcopy(candidate['mapping']),archived=copy.deepcopy(candidate['archived']), - artifacts=dict(copied=copied,missing_regenerable=missing)) - records.append(dict(family=FAMILY,id=destination_id,document=overlay)) - decode_fork(records,project_id=destination_id) - validate_candidate(copy.deepcopy(records),destination_id,source_artifacts) - sources_current();artifacts=ProjectArtifacts(staged) - for number,item in enumerate(sources): - group=[declarations[key] for key in copied if selected[key]==number] - if group:item['artifacts'].copy_many_to(artifacts,group) - from project_files import materialize_captured - with staged.root_directory() as destination_root:materialize_captured(records,destination_id,destination_root) - sources_current();validate_candidate(copy.deepcopy(records),destination_id,artifacts) - committed=staged.commit(records,staged.snapshot()['checkpoint'],request_key,digest) - staged.save(committed['checkpoint']);sources_current() - try:_rename_noreplace(parent,staging_name,parts[-1]) - except FileExistsError as error: - raise ProjectForkError('Fork destination appeared during publication; it was not overwritten.','conflict',409) from error - published=True;os.fsync(parent);sources_current() - result=_result(committed,overlay,False) - if composed: - from project_composition import decode_records - result['composition']=copy.deepcopy(decode_records(records,project_id=destination_id)[destination_id]) - return result - except BaseException as error: - if published: - failure=ProjectForkError('Fork destination was published but acknowledgement is uncertain; retry this exact request.','unknown',503) - if committed is not None: - failure.receipt=dict(committed=True,selected=False,project_id=committed['project_id'],checkpoint=committed['checkpoint'],request_key=request_key,directory=relative) - raise failure from error - if isinstance(error,OSError): - code='conflict' if error.errno==errno.EEXIST else 'unavailable' - failure=ProjectForkError('Fork publication is unavailable; retained staging has not been selected.',code,409 if code=='conflict' else 503) - failure.staging_directory=staging_relative;raise failure from error - if staging_relative is not None:error.staging_directory=staging_relative - raise - finally: - if artifacts is not None:artifacts.close() - if staged is not None:staged.close() - for descriptor in source_roots:os.close(descriptor) diff --git a/project_fork_composition.py b/project_fork_composition.py deleted file mode 100644 index ee13410a..00000000 --- a/project_fork_composition.py +++ /dev/null @@ -1,180 +0,0 @@ -"""Pure fixed-owner composition for an independent project fork. - -The lifecycle owner supplies a validated source checkpoint, creation fact and -fresh ID allocator. This module never opens files, SQL, runtimes or permissions. -The publication owner adds the fork overlay and verifies actual payload custody. -""" -import copy - -from project_artifacts import validate_declaration -from project_data_fork import fork_records as fork_data -from project_material_fork import fork_records as fork_material, OWNED as MATERIAL_EDITABLE -from project_files import fork_records as fork_files -from project_fork import ARCHIVE_FAMILIES, ProjectForkError, decode_fork, ID, _uuid, _sha -from project_store import _records - - -def _fail(message, code='invalid', status=400): - raise ProjectForkError(message, code, status) - - -def artifact_plan(records): - """Give every intrinsic declaration a conservative explicit disposition. - - Runtime files alone can be regenerable. Any unique owner edge to the same - bytes wins, including archived sources and past producer wire observations. - Unclassified declarations remain unique; no filename/path guesses are used. - """ - try: - declarations = {} - for item in records: - if item['family'] != 'project_artifact': continue - declaration = validate_declaration(item['document']) - sha = declaration['sha256'] - if item['id'] != sha or sha in declarations: - _fail('Fork artifact declaration identity differs or repeats.') - declarations[sha] = declaration - unique, regenerable, missing = set(), set(), [] - - def mark(sha, record, role, name, size=None, *, policy='unique'): - _sha(sha) - declaration = declarations.get(sha) - if declaration is None: - if policy == 'unique': - missing.append(dict(family=record['family'],id=record['id'],role=role,name=name, - sha256=sha,bytes=size)) - return - if size is not None and declaration['bytes'] != size: - _fail('Fork owner byte count differs from its intrinsic declaration.') - (unique if policy == 'unique' else regenerable).add(sha) - - # Finite Workbench source fields. Both original and oriented image bytes - # are historical identity; re-encoding does not reproduce their hashes. - for record in records: - family, doc = record['family'], record['document'] - edges = [] - if family == 'workbench_record': - source = doc['source'] - if source['kind'] == 'image': edges = [source['original'],source['oriented']] - elif source['kind'] != 'text': edges = [source['asset']] - elif family == 'dataset_release': edges = [doc['asset']] - for edge in edges: - mark(edge['artifact']['sha256'],record,edge['role'],edge['role']) - - # The material owner has already closed and correlated these inventories - # with its hashed model, recipe, snapshot and runtime definitions. - from project_material import decode_records as material_records - for (family, locator), doc in material_records(records).items(): - record = dict(family=family,id=locator) - for edge in doc.get('artifacts',[]): - runtime_file = family == 'runtime_material' and edge['role'] == 'runtime_file' and edge['preservation'] == 'regenerable' - mark(edge['blob']['sha256'],record,edge['role'],edge['name'],edge['blob']['bytes'], - policy='regenerable' if runtime_file else 'unique') - - # The history owner distinguishes recorded runtime dependencies from - # outputs/proofs/host sources; a weaker payload label alone grants none. - from project_history import declarations as run_declarations, fork_preservation - for record in records: - if record['family'] not in ('run_history', 'run_observation'): continue - doc = (record['document']['observation'] if record['family'] == 'run_observation' - else record['document']) - by_sha = {edge['blob']['sha256']:edge['name'] for edge in doc['payloads']} - publication = doc['publication'] - preservation = fork_preservation(doc) - if publication is not None: - for name in ('source','result'): - if publication[name] is not None: by_sha[publication[name]['sha256']] = 'publication.'+name - for declaration in run_declarations(dict(family='run_history', id=record['id'], document=doc)): - blob = declaration['document'] - mark(blob['sha256'],record,'run_payload',by_sha[blob['sha256']],blob['bytes'], - policy=preservation[blob['sha256']]) - run = doc['run'] - if run.get('execution_kind') == 'external_recipe': - for name, sha in run['material']['host_files'].items(): - mark(sha,record,'host_source',name) - - # Native measured proof/source/output bytes retain unique custody even - # when identical bytes also occur in a regenerable runtime dependency. - for record in records: - if record['family'] != 'native_execution_history': continue - for edge in record['document']['payloads']: - mark(edge['blob']['sha256'],record,edge['role'],edge['name'],edge['blob']['bytes']) - - # Scalar sources are immutable original evidence, including when the - # same bytes are also declared by a regenerable runtime dependency. - from project_measurements import decode_records as measurement_records, FAMILY as MEASUREMENT_FAMILY - for locator, doc in measurement_records(records).items(): - blob = doc['blob'] - mark(blob['sha256'], dict(family=MEASUREMENT_FAMILY, id=locator), - 'measurement_packet', 'measurements.json', blob['bytes']) - - # Existing pure getter covers the four producer families, entry history - # payload maps, and variation prompt-batch request/response observations. - from project_producers import FAMILIES as PRODUCER_FAMILIES, _referenced_artifacts - for record in records: - if record['family'] in PRODUCER_FAMILIES: - for sha in _referenced_artifacts([record]): - mark(sha,record,'producer_wire','producer_wire') - if missing: - failure = ProjectForkError('Complete fork requires declarations for unique historical payloads.', - 'missing_unique',409) - failure.missing_unique = sorted(missing,key=lambda item:(item['family'],item['id'],item['role'],item['name'],item['sha256'])) - raise failure - return [dict(declaration=copy.deepcopy(declarations[sha]), - preservation='regenerable' if sha in regenerable and sha not in unique else 'unique') - for sha in sorted(declarations)] - except ProjectForkError: raise - except (KeyError, TypeError, ValueError, AttributeError, OverflowError, RecursionError): - _fail('Malformed fixed-owner fork artifact closure.') - - -def build_candidate(snapshot, destination_project_id, *, created_at, id_factory): - """Compose originals, independent editable drafts and complete byte policy. - - id_factory(family, source_envelope_id, source_revision) must return fresh UUID - strings. Domain owners retain their own version, provenance and binding rules. - No historical ID, origin catalog or hash-bearing document is rewritten. - """ - if type(snapshot) is not dict or set(snapshot) != {'project_id','name','checkpoint','records'}: - _fail('Fork requires one complete canonical source snapshot.') - _uuid(snapshot['project_id']); _uuid(destination_project_id); _sha(snapshot['checkpoint']) - if destination_project_id == snapshot['project_id'] or not callable(id_factory): - _fail('Fork requires an independent destination identity and explicit ID allocator.') - _records(snapshot['records']) - source = copy.deepcopy(snapshot['records']) - previous = decode_fork(source,project_id=snapshot['project_id']) - used = {snapshot['project_id'],destination_project_id} - used.update(r['id'] for r in source if ID.fullmatch(r['id'])) - used.update(r['document']['current']['id'] for r in source if r['family'] in MATERIAL_EDITABLE) - allocated = {} - - def allocate(family, source_id, revision): - key = family,source_id,revision - if key not in allocated: - identity = id_factory(*key) - _uuid(identity) - if identity in used: _fail('Fork allocator reused an existing or allocated editable identity.') - used.add(identity); allocated[key] = identity - return allocated[key] - - parts = [fork_data(source,snapshot['project_id'],snapshot['checkpoint'],destination_project_id, - id_factory=allocate,created_at=created_at), - fork_material(source,snapshot['project_id'],snapshot['checkpoint'],destination_project_id, - id_factory=allocate,created_at=created_at), - fork_files(source,snapshot['project_id'],snapshot['checkpoint'],destination_project_id)] - indexed = {(r['family'],r['id']):r for r in source} - mapping = [] - for part in parts: - mapping.extend(copy.deepcopy(part['mapping'])) - for record in part['records']: - key = record['family'],record['id'] - if key in indexed: _fail('Fork owner generated a colliding canonical record.') - indexed[key] = copy.deepcopy(record) - records = [indexed[key] for key in sorted(indexed)] - _records(records) - archived = {(r['family'],r['id']) for r in source if r['family'] in ARCHIVE_FAMILIES} - if previous is not None: archived.update((item['family'],item['id']) for item in previous['archived']) - mapping.sort(key=lambda item:(item['family'],item['source_id'],item['source_revision'] or 0,item['destination_id'])) - return dict(records=records,mapping=mapping, - archived=[dict(family=family,id=identity) for family,identity in sorted(archived)], - artifacts=artifact_plan(source)) diff --git a/project_history.py b/project_history.py deleted file mode 100644 index e3b1c7c7..00000000 --- a/project_history.py +++ /dev/null @@ -1,1392 +0,0 @@ -"""Inert project Study, lineage and Run facts, with owner-shared validation. - -Historical identity is always (origin catalog, original ID). No imported fact is -inserted into a worker, admission, grant or request replay table. The optional -SQL connection is only a query engine for bounded supplied immutable JSON. -""" -import base64 -from collections.abc import Mapping -import copy -import hashlib -import re -import uuid - -import agent_api - -from experiments import (DIMENSIONS, Experiments, budget, request_key, - select_retained_checkpoint, reservation_totals, validate_candidate_evidence, new_study_document, edit_study_document, new_trial_document, new_candidate_document, validate_retained_candidate, - validate_retained_policy, validate_retained_reservation, - validate_retained_study, validate_retained_trial) -from experiment_lineage import (INTENT_LIMIT, validate_retained_ancestry, - validate_retained_intent, validate_retained_lineage) -from model_definitions import checked_json, natural, reference, text -from pipeline import closed, digest, identifier, model_aware_graph, source_content_hash -from project_session import operation_documents, operation_records -from projects import relative_path -from runs import (ACTIVE, TERMINAL, TEST_FILES, MAX_ARTIFACT_BYTES, validate_retained_run, - project_run_projection, public_run_projection, artifact_capture_source, validate_external_artifact_inventory) -from workbench import WorkbenchError, timestamp -from project_session import session_derived, session_operations, session_record, session_records, session_records_for - -FAMILY_FORMATS = { - 'study_history': 'project_study_history_v1', - 'trial_history': 'project_trial_history_v1', - 'run_history': 'project_run_history_v1', - 'run_observation': 'project_run_observation_v1', - 'candidate_history': 'project_candidate_history_v1', -} -MAX_HISTORY_BYTES = 40 * 1024**2 -MAX_HISTORY_RECORDS = 100_000 -NAME = re.compile(r'^[A-Za-z0-9][A-Za-z0-9_.-]{0,119}$') -SHA = re.compile(r'^[a-f0-9]{64}$') -RUN_OBSERVATION_IDENTITY = ('dataset_id','id','request_key','request_sha256','graph_sha256','graph_document_sha256', - 'material_sha256','release_id','release_sha256','release_bytes','admission_id','approval_id', - 'approval_material_sha256','actor_id','parent_run_id','attempt','created_at','execution_kind','result_kind') - -OPERATIONS = frozenset(('studies.create','studies.save','studies.prepare_trial','studies.record_lineage', - 'studies.branch_trial','studies.prepare_branch','studies.select_candidate','studies.prepare_package', - 'studies.prepare_verifier','studies.continue','studies.stop')) - - -def _invalid(message, code='invalid'): - raise WorkbenchError(message, code, 409) - - -def _shape(value, fields, name): - if type(value) is not dict or set(value) != set(fields): - _invalid('Invalid '+name+' fields.') - - -def _items(value, name, maximum=10000): - if type(value) is not list or len(value)>maximum: - _invalid(name+' must be a bounded list.') - return value - - -def _sha(value): - if type(value) is not str or not SHA.fullmatch(value): - _invalid('Historical digest must be an exact SHA256.') - return value - - -def envelope(family, origin, identity, document): - identifier(origin,'Origin catalog');identifier(identity,'Historical identity') - return {'family':family,'id':origin+'.'+identity,'document':document} - - -def _audit(facts): - """Retain classified scientific audit facts, never arbitrary access payloads.""" - for fact in _items(facts,'Scientific audit',100000): - _shape(fact,('actor_id','action','target','details','result','occurred_at'),'scientific audit') - if fact['actor_id'] is not None:identifier(fact['actor_id'],'Historical actor') - action=fact['action'];details=fact['details'] - text(fact['occurred_at'],'Audit time',80);identifier(fact['target'],'Audit target') - allowed=OPERATIONS|{'studies.admit','studies.approve','studies.reconcile','studies.candidate_selected','studies.lineage.record', - 'runs.admit','runs.admit_external','runs.update','runs.reconcile','runs.expose_test'} - if action not in allowed:_invalid('Unclassified historical scientific audit action.','unsupported') - if fact['result'] in ('denied','failed'): - closed(details,('code',)) - if details['code'] not in ('invalid','unavailable','unsupported','stale','conflict','not_found','denied', - 'forbidden','unknown','failed','cancelled','busy','interrupted'):_invalid('Unclassified historical failure code.') - continue - if fact['result'] not in ('success','interrupted'):_invalid('Unsupported historical audit result.') - keys=set(details) if type(details) is dict else set() - if action=='studies.create': - closed(details,('policy_sha256','limits'));_sha(details['policy_sha256']);budget(details['limits']) - elif action in ('studies.save','studies.continue','studies.stop'): - if keys not in ({'revision'},{'revision','epoch'}):_invalid('Unclassified Study transition audit.') - elif action=='studies.reconcile': - if keys not in ({'revision','epoch'},{'state'}):_invalid('Unclassified Study recovery audit.') - elif action=='studies.prepare_trial': - if keys not in ({'trial_id'},{'trial_id','revision','epoch'}):_invalid('Unclassified Trial preparation audit.') - elif action=='studies.admit':closed(details,('run_id','reservation_id','request_sha256','revision','epoch')) - elif action=='studies.approve': - if keys not in ({'trial_id','material_sha256','approval_id'}, - {'trial_id','material_sha256','approval_id','consumer_actor_id','created_at','expires_at'}): - _invalid('Unclassified Study approval audit.') - if 'created_at' in details: - from access import MAX_APPROVAL_TTL - if (type(details['created_at']) is not int or type(details['expires_at']) is not int or - not details['created_at']=64:_invalid('Historical Run ancestry exceeds its bound.','unsupported') - run=facts.runs[key]['run'];next_path=path|{key} - if run.get('parent_run_id') is not None:visit_run((key[0],run['parent_run_id']),next_path) - if run.get('execution_kind')=='external_recipe': - for item in run['material']['inputs'].values(): - if item.get('kind')=='run_artifact': - source=item['source'];visit_run((source['catalog_id'],source['run_id']),next_path) - for key in facts.runs:visit_run(key,set()) - for (origin,_identity),reservation in facts.reservations.items(): - trial=facts.trials[(origin,reservation['trial_id'])]['trial'] - run=facts.runs.get((origin,reservation['run_id'])) - if run is None:_invalid('Historical reservation Run is missing.','unavailable') - validate_retained_reservation(reservation,trial=trial,composition=materials.recipe(trial['material']),run=run['run']) - for (origin,_identity),doc in facts.candidates.items(): - value=doc['candidate'];trial=facts.trials.get((origin,value.get('trial_id'))) - reservation=facts.reservations.get((origin,value.get('run_id'))) - if trial is None or reservation is None:_invalid('Candidate dependency closure is missing.','unavailable') - ref=value['policy'];policy=facts.policies.get((origin,ref['id'],ref['revision'],ref['sha256'])) - if policy is None:_invalid('Candidate policy closure is missing.','unavailable') - validate_retained_candidate(value,catalog_id=origin,trial=trial['trial'],policy=policy,reservation=reservation) - for (origin,_),doc in facts.studies.items(): - for operation in doc['operations']: - validate_operation_result(operation['operation_id'],operation['result'],records) - validate_data_exposures(records,facts) - for record in records: - if record.get('family')=='project_operation': - value=record['document'];validate_operation_result(value['operation'],value['result'],records) - return facts - - -def assemble_validated_facts(records, *, owned=False): - """Collect HistoryFacts from records whose complete validation is on record. - - decode_records validates and collects exactly these values: each history - document (as a checked JSON copy), Run observations, and the policy and - reservation indexes taken from Study documents. Only for a checkpoint that - already passed complete domain validation (which runs decode_records over - these same records) may the collection be repeated without re-running the - validators. tests/test_project_history.py and the portfolio equivalence - check compare this against decode_records field by field. owned=True means - the caller supplies independent copies the facts may keep without recopying. - """ - facts=HistoryFacts() - for record in records: - family=record.get('family') - if family not in FAMILY_FORMATS:continue - if family=='run_observation': - doc=_observation_document(record) - facts.observations[(doc['origin_catalog_id'],doc['run_id'],doc['sha256'])]=doc - continue - doc=record['document'] if owned else checked_json(record['document'],MAX_HISTORY_BYTES) - origin=doc['origin_catalog_id'] - if family=='study_history':target,identity=facts.studies,doc['study']['id'] - elif family=='trial_history':target,identity=facts.trials,doc['trial']['id'] - elif family=='run_history':target,identity=facts.runs,doc['run']['id'] - else:target,identity=facts.candidates,doc['candidate']['id'] - target[(origin,identity)]=doc - for (origin,_identity),doc in facts.studies.items(): - for item in doc['policies']: - ref=item['ref'];facts.policies[(origin,ref['id'],ref['revision'],ref['sha256'])]=item['policy'] - for reservation in doc['reservations']: - facts.reservations[(origin,reservation.get('run_id'))]=reservation - return facts - - -class _LazyRuns(Mapping): - """Validated Run history documents by (origin, run_id), loaded on first use. - - Keys come from verified record identities (origin + '.' + run_id); each - document is read from the working copy once per checkpoint and shared like - every other fact (callers copy what they return). - """ - def __init__(self, identities, load): - self._identities = identities - self._load = load - self._documents = {} - - def __getitem__(self, key): - if key not in self._identities: - raise KeyError(key) - if key not in self._documents: - envelope = self._load(self._identities[key]) - if envelope is None: - _invalid('Historical Run is unavailable.', 'unavailable') - self._documents[key] = envelope['document'] - return self._documents[key] - - def __iter__(self): - return iter(self._identities) - - def __len__(self): - return len(self._identities) - - -def checkpoint_facts(session, materials): - """Decoded history of the session's bound checkpoint, shared by its owners. - - Decoded once per checkpoint; callers copy any part they return. When the - session records that this exact checkpoint passed complete validation, - the facts are collected without repeating the validators. - """ - def compute(): - validated=getattr(session,'validated_checkpoint',None) - if validated is not None and validated==session.summary['checkpoint'] and getattr(session,'_lazy',False): - # A working copy serves Run documents on demand: decode everything - # except Run history now, and keep only Run identities. - selected=('study_history','trial_history','run_observation','candidate_history') - view=session_records_for(session,*selected) - facts=assemble_validated_facts([r for r in view if r['family'] in selected],owned=True) - identities={} - for envelope in view: - if envelope['family']=='run_history': - origin,run_id=envelope['id'].split('.',1) - identities[(origin,run_id)]=envelope['id'] - facts.runs=_LazyRuns(identities,lambda record_id:session_record(session,'run_history',record_id)) - return facts - if validated is not None and validated==session.summary['checkpoint']: - # records_for returns independent copies of exactly these families. - return assemble_validated_facts(session_records_for(session,*FAMILY_FORMATS),owned=True) - records=session.snapshot['records'] - return decode_records(records,materials=materials.read_view(records)) - return session_derived(session, 'history_facts',compute) - - -def decode_records(records, *, materials=None, artifacts=None): - try: - return _decode_records(records,materials=materials,artifacts=artifacts) - except WorkbenchError: - raise - except (KeyError,TypeError,ValueError,AttributeError,RecursionError): - _invalid('Invalid or incomplete project history document.') - - -def _validate_operation_shape(operation,result): - if operation=='history.disclose': - validate_disclosure_fact(result);return True - if operation in ('studies.create','studies.save'): - closed(result,('format','id','revision','name','admission_epoch','open','state','limits','policy', - 'membership_revision','trial_ids','stop_receipt_id')) - if result['format']!='study_v1':_invalid('Historical Study operation result differs.') - identifier(result['id']);natural(result['revision'],'Study revision',1);budget(result['limits']) - reference(result['policy'],'selection_policy',result['policy']['catalog_id']) - return True - if operation in ('studies.prepare_trial','studies.prepare_branch'): - validate_retained_trial(result,catalog_id=result['material']['catalog_id']);return True - if operation=='studies.record_lineage': - closed(result,('format','trial','intent','actor_id','recorded_at','timing')) - if result['format']!='trial_lineage_v1':_invalid('Historical lineage operation result differs.') - return True - if operation=='studies.select_candidate': - closed(result,('ref','candidate','run_id','checkpoint')) - ref=reference(result['ref'],'candidate',result['ref']['catalog_id']) - if (ref['sha256']!=digest(result['candidate']) or ref['id']!=result['candidate']['id'] or - result['run_id']!=result['candidate']['run_id'] or result['checkpoint']['sha256']!=result['candidate']['checkpoint_sha256']): - _invalid('Historical candidate operation identity differs.') - return True - if operation=='studies.continue': - return _validate_operation_shape('studies.save',result) - if operation=='studies.stop': - closed(result,('study_id','stop_receipt_id','admission_epoch','run_ids')) - identifier(result['study_id']);identifier(result['stop_receipt_id']);natural(result['admission_epoch'],'Admission epoch') - for run_id in _items(result['run_ids'],'Stopped Run ids'):identifier(run_id) - return True - if operation in ('studies.prepare_package','studies.prepare_verifier'): - from candidate_packages import decode_preparation_receipt - origin=result['trial']['material']['catalog_id'] - decode_preparation_receipt(operation,result,catalog_id=origin, - validate_trial=lambda value:validate_retained_trial(value,catalog_id=origin)) - return True - if operation=='studies.branch_trial': - from pipeline import decode_graph - closed(result,('request_key','graph','model','parent','intent','study_id','source')) - request_key(result['request_key']);decode_graph(result['graph']);identifier(result['study_id']) - reference(result['model'],'model',result['model']['catalog_id']) - closed(result['source'],('id','revision','material'));identifier(result['source']['id']) - natural(result['source']['revision'],'Source graph revision',1) - reference(result['source']['material'],'recipe_material',result['model']['catalog_id']) - closed(result['parent'],('catalog_id','trial_id','material_sha256')) - identifier(result['parent']['catalog_id']);identifier(result['parent']['trial_id']);_sha(result['parent']['material_sha256']) - if result['intent']['parent']!=result['parent']:_invalid('Branch parent differs from retained intent.') - # Exact lineage intent is checked with the complete Trial closure below. - def ref(value): - closed(value,('catalog_id','trial_id','material_sha256')) - identifier(value['catalog_id']);identifier(value['trial_id']);_sha(value['material_sha256']) - validate_retained_intent(result['intent'],resolve=ref) - return True - if operation=='studies.admit': - # The legacy owner replays admission from reservations and never calls - # _save_receipt for this operation. M3 must own any future publication - # receipt; an invented public Run snapshot is not a portable v1 fact. - _invalid('Portable admission operation receipts are unsupported; retain exact reservation and Run proof.','unsupported') - return False - - -def _bind_operation_result(operation,result,records): - def document(family,origin,identity): - matches=[item['document'] for item in records if item.get('family')==family and item.get('id')==origin+'.'+identity] - if len(matches)!=1:_invalid('Operation result has no unique canonical history fact.') - return matches[0] - if operation=='history.disclose': - doc=document('run_history',result['origin_catalog_id'],result['run_id']) - if result['format']=='project_disclosure_v2': - matches=[item for item in records if item.get('family')=='run_observation' - and item.get('id')==result['observation_sha256']] - if len(matches)!=1:_invalid('Disclosure has no unique retained Run observation.') - saved=_observation_document(matches[0]) - if (saved['origin_catalog_id']!=result['origin_catalog_id'] or saved['run_id']!=result['run_id'] - or saved['sha256']!=result['observation_sha256']): - _invalid('Disclosure Run observation identity differs.') - observation=saved['observation'] - for field in RUN_OBSERVATION_IDENTITY: - if observation['run'].get(field)!=doc['run'].get(field): - _invalid('Disclosure Run observation immutable identity differs.') - declarations={item['id']:item['document'] for item in records if item.get('family')=='project_artifact'} - for edge in _payloads(observation['payloads']).values(): - if declarations.get(edge['blob']['sha256'])!={'format':'project_artifact_v1',**edge['blob']}: - _invalid('Disclosure observation artifact declaration is missing or contradictory.','unavailable') - doc=observation - if result['payload_set_sha256']!=payload_set_sha256(doc['origin_catalog_id'],doc['run']['id'],doc['payloads']): - _invalid('Disclosure observation does not identify the retained Run payload set.') - elif operation in ('studies.create','studies.save'): - doc=document('study_history',result['policy']['catalog_id'],result['id']) - if result not in doc['revisions']:_invalid('Study operation result has no retained revision.') - elif operation in ('studies.prepare_trial','studies.prepare_branch'): - doc=document('trial_history',result['material']['catalog_id'],result['id']) - if doc['trial']!=result:_invalid('Trial operation result has no retained Trial.') - elif operation=='studies.record_lineage': - ref=result['trial'];doc=document('trial_history',ref['catalog_id'],ref['trial_id']) - if doc['lineage']!=result:_invalid('Lineage operation result has no retained sidecar.') - elif operation=='studies.select_candidate': - ref=result['ref'];doc=document('candidate_history',ref['catalog_id'],ref['id']) - if doc['candidate']!=result['candidate']:_invalid('Candidate operation result has no retained decision.') - run=document('run_history',ref['catalog_id'],result['run_id'])['run'] - checkpoint=result['checkpoint'] - if not any(all(item.get(key)==checkpoint.get(key) for key in ('name','sha256','bytes','media_type')) - for item in run['artifacts']): - _invalid('Candidate operation checkpoint differs from its canonical Run artifact.') - - elif operation=='studies.continue': - _bind_operation_result('studies.save',result,records) - elif operation=='studies.stop': - docs=[item['document'] for item in records if item.get('family')=='study_history' - and item['document']['study']['id']==result['study_id']] - matches=[doc for doc in docs if any(value['stop_receipt_id']==result['stop_receipt_id'] - and value['admission_epoch']==result['admission_epoch'] for value in doc['revisions'])] - if len(matches)!=1:_invalid('Stop receipt has no unique retained epoch fact.') - members={value['run_id'] for value in matches[0]['reservations']} - if not set(result['run_ids'])<=members:_invalid('Stop receipt references an unrelated Run.') - elif operation in ('studies.prepare_package','studies.prepare_verifier'): - origin=result['trial']['material']['catalog_id'] - _bind_operation_result('studies.prepare_trial',result['trial'],records) - document('candidate_history',origin,result['candidate_id']) - graph_docs=[item['document'] for item in records if item.get('family')=='pipeline_graph' - and item['document']['origin_catalog_id']==origin] - if not any(result['graph'] in doc['revisions'] for doc in graph_docs): - _invalid('Preparation graph has no retained revision.') - if operation=='studies.prepare_verifier':document('run_history',origin,result['package_run_id']) - elif operation=='studies.branch_trial': - ref=result['parent'];origin=ref['catalog_id'];parent=document('trial_history',origin,ref['trial_id'])['trial'] - if parent['material']['sha256']!=ref['material_sha256']:_invalid('Branch parent material differs.') - resolve=lambda value:document('trial_history',value['catalog_id'],value['trial_id'])['trial'] - validate_retained_intent(result['intent'],resolve=resolve) - document('study_history',origin,result['study_id']) - graph_docs=[item['document'] for item in records if item.get('family')=='pipeline_graph' - and item['document']['origin_catalog_id']==origin] - if not any(result['graph'] in doc['revisions'] for doc in graph_docs):_invalid('Branch graph has no retained revision.') - -def validate_operation_result(operation,result,records=None): - """Validate exact returned meaning and, when supplied, its canonical fact.""" - try: - claimed=_validate_operation_shape(operation,result) - if claimed and records is not None:_bind_operation_result(operation,result,records) - return claimed - except WorkbenchError: - raise - except (KeyError,TypeError,ValueError,AttributeError): - _invalid('Invalid historical operation result or fact binding.') - - -def validate_data_exposures(records,history): - """Exposure is a historical Run/source fact, never present permission.""" - try: - for item in records: - if item.get('family')!='dataset_exposure':continue - doc=item['document'] - _shape(doc,('format','id','record_id','source_hash','reason','run_id','release_id','created_at'),'dataset exposure') - if doc['format']!='dataset_exposure_v1':_invalid('Unsupported dataset exposure.','unsupported') - matches=[] - for (origin,run_id),saved in history.runs.items(): - run=saved['run'] - if run_id!=doc['run_id'] or run.get('release_id')!=doc['release_id']:continue - sources=[source for source in run.get('source_records',[]) if source.get('id')==doc['record_id'] - and source.get('split')=='test' and source_content_hash(source)==doc['source_hash']] - events=[event for event in run.get('exposure_events',[]) if event.get('created_at')==doc['created_at'] - and event.get('reason')==doc['reason']] - if len(sources)==1 and events:matches.append(origin) - if len(matches)!=1:_invalid('Dataset exposure has no unique exact historical Run/source/release binding.') - return True - except WorkbenchError: - raise - except (KeyError,TypeError,ValueError,AttributeError): - _invalid('Invalid historical dataset exposure binding.') - - -class ProjectHistory: - """Read-only imported facts plus canonical, non-executing Study metadata edits.""" - def __init__(self,session,*,materials=None,authorize_disclosure=None): - self.session=session;self.access=session.access;self.artifacts=session.artifacts - if materials is None: - from project_material import ProjectMaterial - materials=ProjectMaterial(session) - self.materials=materials;self.authorize_disclosure=authorize_disclosure - self._decoded_checkpoint=None - self._decoded_facts=None - - def _facts(self): - self.session.check_current() - # Current canonical bytes are guarded on every call. A ProjectSession - # shares decoded metadata per checkpoint with the Study owner; other - # snapshot views keep this owner's private per-checkpoint cache. - # Returned values and permissions remain each read's responsibility. - if callable(getattr(self.session,'derived',None)): - return checkpoint_facts(self.session,self.materials) - summary=self.session.summary - checkpoint=(summary['project_id'],summary['checkpoint']) - if self._decoded_checkpoint==checkpoint: - return self._decoded_facts - records=self.session.snapshot['records'] - facts=decode_records(records,materials=self.materials.read_view(records),artifacts=self.artifacts) - self._decoded_facts=facts - self._decoded_checkpoint=checkpoint - return facts - - def _authorize(self,action,target=None): - self.access.require('inspect',action,target) - - def _origin(self,origin): - return self.session.summary['project_id'] if origin is None else origin - - def _record(self,collection,identity,origin=None): - origin=self._origin(origin);identifier(origin,'Origin catalog');identifier(identity) - result=collection.get((origin,identity)) - if result is None:_invalid('Historical record is unavailable.','not_found') - return result - - def study(self,study_id,*,origin_catalog_id=None,offset=0,limit=100,revision=None): - self._authorize('studies.get',study_id) - natural(offset,'Reservation offset');natural(limit,'Reservation limit',1,100) - facts=self._facts();doc=self._record(facts.studies,study_id,origin_catalog_id) - if offset and revision is None:_invalid('Later reservation pages require a Study revision.') - if revision is not None and revision!=doc['study']['revision']:_invalid('Study changed between pages.','stale') - totals=reservation_totals(doc['reservations']) - self._authorize('studies.get',study_id) - end=min(offset+limit,len(doc['reservations'])) - return {'study':copy.deepcopy(doc['study']),'reservations':copy.deepcopy(doc['reservations'][offset:end]), - 'charged':totals,'revision_history_complete':doc['revision_history_complete'], - 'page':{'offset':offset,'limit':limit,'total':len(doc['reservations']), - 'study_revision':doc['study']['revision'],'next_offset':end if end5}) - visible={node['trial']['id'] for node in nodes};related={} - for node in nodes: - for kind in ('parent','baseline'): - ref=(node['lineage'] or {}).get('intent',{}).get(kind) - if ref is not None and (ref['catalog_id']!=origin or ref['trial_id'] not in visible): - related[(ref['catalog_id'],ref['trial_id'])]=copy.deepcopy(ref) - self._authorize('studies.lineage') - return {'origin_catalog_id':origin,'evidence':'saved_metadata_only','historical':True, - 'execution_available':False,'nodes':nodes,'related':[related[key] for key in sorted(related)], - 'offset':offset,'limit':limit,'total':len(documents),'cohort':cohort} - - def run(self,run_id,*,origin_catalog_id=None,offset=None,limit=None): - self._authorize('runs.get',run_id) - facts=self._facts();doc=self._record(facts.runs,run_id,origin_catalog_id) - self._transitive(facts,doc) - public=public_run_projection(doc['run']) - public.pop('exposure_events',None) - disclosures=self.disclosure_facts(run_id,origin_catalog_id=doc['origin_catalog_id']) - payloads=doc['payloads'];page=None - if offset is not None or limit is not None: - offset=0 if offset is None else offset;limit=40 if limit is None else limit - natural(offset,'Run payload offset');natural(limit,'Run payload limit',1,100) - end=min(offset+limit,len(payloads));disclosure_end=min(offset+limit,len(disclosures)) - page={'offset':offset,'limit':limit,'total':len(payloads), - 'next_offset':end if endlen(raw):_invalid('Run document offset exceeds its size.') - end=min(offset+limit,len(raw)) - result={'format':'project_run_document_segment_v1','origin_catalog_id':doc['origin_catalog_id'], - 'run_id':run_id,**descriptor,'offset':offset,'limit':limit, - 'base64':base64.b64encode(raw[offset:end]).decode('ascii'), - 'next_offset':end if end=64:_invalid('Historical Run input lineage exceeds its bound.','unsupported') - seen=seen|{key} - if run.get('execution_kind')!='external_recipe':return - for item in run['material']['inputs'].values(): - if item.get('kind')!='run_artifact':continue - source=item['source'];parent=facts.runs[(source['catalog_id'],source['run_id'])] - self._authorize('runs.artifact',source['run_id']) - edge=next(edge for edge in parent['payloads'] if edge['name']==source['artifact_name']) - self._disclose(parent['run'],edge['population'],edge['name']);self._transitive(facts,parent,seen) - - def _read(self,doc,name,maximum): - edges=_payloads(doc['payloads']);edge=edges.get(name) - if edge is None:_invalid('Historical artifact is unavailable.','not_found') - self._authorize('runs.artifact',doc['run']['id']);self._disclose(doc['run'],edge['population'],name) - raw=self.artifacts.read_blob(edge['blob'],maximum_bytes=maximum) - self._authorize('runs.artifact',doc['run']['id']);self._disclose(doc['run'],edge['population'],name) - return raw - - def artifact(self,run_id,name,*,origin_catalog_id=None,maximum_bytes=40*1024**2): - facts=self._facts();doc=self._record(facts.runs,run_id,origin_catalog_id) - self._transitive(facts,doc) - return self._read(doc,name,maximum_bytes) - - def authorize_material_inputs(self,material): - """Bind retained producer receipts under present disclosure authority.""" - from recipe_contract import validate_material - material=validate_material(copy.deepcopy(material)) - for name,item in material['inputs'].items(): - if item.get('kind')!='run_artifact':continue - source=item['source'] - _raw,actual=self.capture_artifact(source['run_id'],source['artifact_name'],source['measured_sha256'], - max_bytes=material['recipe']['inputs'][name]['max_bytes'],origin_catalog_id=source['catalog_id']) - if actual!=source:_invalid('Retained producer proof differs from the captured input receipt.','unavailable') - - def capture_artifact(self,run_id,name,expected_sha256,*,max_bytes=MAX_ARTIFACT_BYTES,origin_catalog_id=None): - """Capture an exact completed input without live recovery or admissions.""" - self._authorize('runs.capture_artifact',run_id);_sha(expected_sha256) - natural(max_bytes,'Artifact input byte bound',1,MAX_ARTIFACT_BYTES) - facts=self._facts();doc=self._record(facts.runs,run_id,origin_catalog_id);run=doc['run'] - self._transitive(facts,doc) - if run['state']!='completed':_invalid('Only completed Runs provide artifact inputs.','unavailable') - external=run.get('execution_kind')=='external_recipe' - if not external and (run.get('graph',{}).get('recipe')!='image_classification_model_v2' or name=='release.zip'): - _invalid('Capture requires qualified classifier evidence or an external Run.','unsupported') - item=next((item for item in run['artifacts'] if item['name']==name),None) - if item is None or item['bytes']>max_bytes:_invalid('Artifact input is unavailable or exceeds its bound.','unavailable') - if item['sha256']!=expected_sha256:_invalid('Artifact differs from expected SHA256.','conflict') - if external: - self._disclose(run,'unknown') - receipt=self._read(doc,'custody-receipt.json',16384) - manifest=self._read(doc,'artifact-manifest.json',65536) - try:validate_external_artifact_inventory(run,receipt,manifest) - except (ValueError,TypeError,KeyError) as error: - raise WorkbenchError('Retained external inventory differs.','unavailable',409) from error - if run.get('extension_context') is not None:self.evidence(run_id,origin_catalog_id=doc['origin_catalog_id']) - if not run['material']['recipe']['resources'].get('profile')=='captured_cpu_large_outputs_v1': - for artifact in run['artifacts']:self._read(doc,artifact['name'],MAX_ARTIFACT_BYTES) - proof=receipt - else: - # Shared model evidence verifies the full frozen prediction/checkpoint closure. - self.evidence(run_id,origin_catalog_id=doc['origin_catalog_id']) - proof=self._read(doc,'artifact-manifest.json',65536) - raw=self._read(doc,name,max_bytes) - source=artifact_capture_source(run,item,raw,proof) - self._authorize('runs.capture_artifact',run_id) - return raw,source - - def evidence(self,run_id,selectors=None,*,origin_catalog_id=None): - self._authorize('runs.model_evidence',run_id) - facts=self._facts();doc=self._record(facts.runs,run_id,origin_catalog_id) - self._transitive(facts,doc) - if doc['run'].get('execution_kind')=='external_recipe':self._disclose(doc['run'],'unknown') - result=self.materials.evidence(doc['run'],selectors or {}, - read_blob=lambda name,maximum:self._read(doc,name,maximum)) - self._authorize('runs.model_evidence',run_id) - return result - - def candidate(self,candidate_id,*,origin_catalog_id=None,verify=False): - self._authorize('studies.candidate',candidate_id) - facts=self._facts();doc=self._record(facts.candidates,candidate_id,origin_catalog_id);value=doc['candidate'] - result={'ref':{'kind':'candidate','catalog_id':doc['origin_catalog_id'],'id':candidate_id,'sha256':digest(value)}, - 'candidate':copy.deepcopy(value),'run_id':value['run_id'],'evidence':'unverified'} - if verify: - evidence=self.evidence(value['run_id'],{'checkpoint_sha256':value['checkpoint_sha256']}, - origin_catalog_id=doc['origin_catalog_id']) - trial=facts.trials[(doc['origin_catalog_id'],value['trial_id'])]['trial'] - validate_candidate_evidence(evidence,trial) - ref=value['policy'];policy=facts.policies[(doc['origin_catalog_id'],ref['id'],ref['revision'],ref['sha256'])] - checkpoint=select_retained_checkpoint(evidence,policy,value['checkpoint_sha256']) - run=facts.runs[(doc['origin_catalog_id'],value['run_id'])]['run'] - evaluation='model-evidence.json' if run.get('extension_context') is not None else 'metrics.json' - if not any(item['name']==evaluation and item['sha256']==value['evaluation_sha256'] for item in run['artifacts']): - _invalid('Candidate evaluation identity differs.') - result.update(checkpoint=checkpoint,evidence='verified') - return result - - def package_state(self,candidate_id,*,origin_catalog_id=None): - from candidate_packages import retained_package_state - self._authorize('studies.package_state',candidate_id) - facts=self._facts();origin=self._origin(origin_catalog_id) - candidate=self.candidate(candidate_id,origin_catalog_id=origin,verify=True) - preparations=[] - for (namespace,_),doc in facts.studies.items(): - if namespace!=origin:continue - for operation in doc['operations']: - if operation['operation_id'] in ('studies.prepare_package','studies.prepare_verifier') and operation['result'].get('candidate_id')==candidate_id: - preparations.append({'operation_id':operation['operation_id'],'result':operation['result']}) - def runs_for_trial(trial_id): - result=[] - for (namespace,run_id),reservation in sorted(facts.reservations.items()): - if namespace==origin and reservation['trial_id']==trial_id: - self._authorize('runs.get',run_id) - doc=facts.runs[(origin,run_id)];self._transitive(facts,doc);result.append(copy.deepcopy(doc['run'])) - return result - result=retained_package_state(candidate,preparations,runs_for_trial=runs_for_trial, - read_artifact=lambda run_id,name:self.artifact(run_id,name,origin_catalog_id=origin)) - self._authorize('studies.package_state',candidate_id) - return result - - def retained_analysis(self,origin_catalog_id,body,*,export=False): - from retained_analysis import query_history - run_id=body['run_id'];doc=self._record(self._facts().runs,run_id,origin_catalog_id) - evidence=self.evidence(run_id,{'checkpoint_sha256':body['checkpoint_sha256']},origin_catalog_id=origin_catalog_id) - return query_history(self.session.db,doc['run'],evidence,body,authorize=self.access.require,export=export) - - def _mutate(self,operation,target,body,expected_checkpoint,key,build): - prepared={} - def invoke(): - self.access.require('edit',operation,target) - facts=self._facts();records,result=build(facts) - prepared['records']=records - return result - def capture(result,before_records): - adapter=getattr(self,'study_execution',None) - if adapter is not None: - # Authoring rows are a disposable projection of THIS pending - # canonical change. Update them inside the same SQL boundary so - # a background local Run cannot later publish stale Study intent. - merged={(item['family'],item['id']):item for item in before_records} - merged.update(((item['family'],item['id']),item) for item in prepared['records']) - adapter.refresh_authoring(list(merged.values())) - return {'records':prepared['records'],'result':result} - self.access.require('edit',operation,target,owner_only=operation in ('studies.create','studies.save')) - return self.session.mutate(operation,target,body,expected_checkpoint,key,invoke,capture) - - def _audit_fact(self,action,target,details): - return {'actor_id':self.access._context().actor_id,'action':action,'target':target,'details':copy.deepcopy(details), - 'result':'success','occurred_at':timestamp()} - - def create_study(self,body,expected_checkpoint,request_key): - closed(body,('name','limits','policy'));body=checked_json(body) - text(body['name'],'Study name');limits=budget(body['limits']);policy=validate_retained_policy(body['policy']) - def build(facts): - origin=self.session.summary['project_id'];identity=uuid.uuid4().hex;sha=digest(policy) - prior=next((key for key,value in facts.policies.items() if key[0]==origin and key[3]==sha),None) - policy_id=prior[1] if prior else uuid.uuid4().hex - ref={'kind':'selection_policy','catalog_id':origin,'id':policy_id,'revision':1,'sha256':sha} - study=new_study_document(body,catalog_id=origin,study_id=identity,policy_id=policy_id) - doc={'format':FAMILY_FORMATS['study_history'],'origin_catalog_id':origin,'study':study, - 'memberships':[{'revision':1,'trial_ids':[]}],'policies':[{'ref':ref,'policy':policy}], - 'reservations':[],'operations':[],'revisions':[copy.deepcopy(study)], - 'audit':[self._audit_fact('studies.create',identity,{'policy_sha256':sha,'limits':limits})], - 'revision_history_complete':True} - return [envelope('study_history',origin,identity,doc)],study - return self._mutate('studies.create',None,body,expected_checkpoint,request_key,build) - - def save_study(self,study_id,body,expected_checkpoint,request_key): - closed(body,('revision','name','limits','policy'));body=checked_json(body) - text(body['name'],'Study name');limits=budget(body['limits']) - def build(facts): - origin=self.session.summary['project_id'];doc=copy.deepcopy(self._record(facts.studies,study_id,origin));study=doc['study'] - if body['revision']!=study['revision']:_invalid('Study changed. Reload.','stale') - ref=reference(body['policy'],'selection_policy',origin) - policy=facts.policies.get((origin,ref['id'],ref['revision'],ref['sha256'])) - if policy is None:_invalid('Selection policy is unavailable.','unavailable') - totals=reservation_totals(doc['reservations']) - study=edit_study_document(study,body,policy=policy,charged=totals,catalog_id=origin) - study['revision']=natural(study['revision']+1,'Study revision',1);doc['study']=study - if not any(item['ref']==ref for item in doc['policies']):doc['policies'].append({'ref':ref,'policy':policy}) - doc['revisions'].append(copy.deepcopy(study));doc['audit'].append(self._audit_fact('studies.save',study_id,{'revision':study['revision']})) - return [envelope('study_history',origin,study_id,doc)],study - return self._mutate('studies.save',study_id,body,expected_checkpoint,request_key,build) - - def prepare_trial_from_material(self,study_id,body,expected_checkpoint,request_key): - """Attach a fully retained composition without capture, approval or execution.""" - closed(body,('revision','material','replicate'));body=checked_json(body) - natural(body['replicate'],'Replicate') - self.access.require('edit','studies.prepare_trial',study_id) - if request_key not in session_operations(self.session): - self.materials.recipe(body['material'],verify=True) - def build(facts): - origin=self.session.summary['project_id'];doc=copy.deepcopy(self._record(facts.studies,study_id,origin)) - study=doc['study'] - if body['revision']!=study['revision']:_invalid('Study changed. Reload.','stale') - ref=reference(body['material'],'recipe_material',origin);self.materials.recipe(ref) - for (namespace,_),other in facts.trials.items(): - trial=other['trial'] - if namespace==origin and trial['study_id']==study_id and trial['material']==ref and trial['replicate']==body['replicate']: - _invalid('Material/replicate already belongs to this study.','conflict') - trial=new_trial_document(study,ref,body['replicate'],trial_id=uuid.uuid4().hex) - study['trial_ids'].append(trial['id']);study['membership_revision']+=1 - study['revision']=natural(study['revision']+1,'Study revision',1) - doc['memberships'].append({'revision':study['membership_revision'],'trial_ids':copy.deepcopy(study['trial_ids'])}) - doc['revisions'].append(copy.deepcopy(study)) - doc['audit'].append(self._audit_fact('studies.prepare_trial',study_id,{'trial_id':trial['id']})) - trial_doc={'format':FAMILY_FORMATS['trial_history'],'origin_catalog_id':origin,'trial':trial,'lineage':None} - return [envelope('study_history',origin,study_id,doc),envelope('trial_history',origin,trial['id'],trial_doc)],trial - return self._mutate('studies.prepare_trial',study_id,body,expected_checkpoint,request_key,build) - - def select_candidate(self,study_id,body,expected_checkpoint,request_key): - closed(body,('revision','trial_id','run_id'),('checkpoint_sha256',));body=checked_json(body) - identifier(body['trial_id']);identifier(body['run_id']) - # Expensive semantic proof precedes the write transaction. All exact - # associations and selected policy are checked again under publication. - origin=self.session.summary['project_id'] - self.access.require('edit','studies.select_candidate',study_id) - evidence=(self.evidence(body['run_id'],{},origin_catalog_id=origin) - if request_key not in session_operations(self.session) else None) - def build(facts): - doc=copy.deepcopy(self._record(facts.studies,study_id,origin));study=doc['study'] - if body['revision']!=study['revision']:_invalid('Study changed. Reload.','stale') - trial=self._record(facts.trials,body['trial_id'],origin)['trial'] - reservation=facts.reservations.get((origin,body['run_id'])) - if reservation is None or reservation['trial_id']!=trial['id']:_invalid('Run does not belong to the selected trial.') - validate_candidate_evidence(evidence,trial) - ref=study['policy'];policy=facts.policies[(origin,ref['id'],ref['revision'],ref['sha256'])] - checkpoint=select_retained_checkpoint(evidence,policy,body.get('checkpoint_sha256')) - run=facts.runs[(origin,body['run_id'])]['run'] - name='model-evidence.json' if run.get('extension_context') is not None else 'metrics.json' - evaluation=next((item for item in run['artifacts'] if item['name']==name),None) - candidate=new_candidate_document(study,trial,run,checkpoint,evaluation,candidate_id=uuid.uuid4().hex) - study['revision']=natural(study['revision']+1,'Study revision',1) - doc['revisions'].append(copy.deepcopy(study));doc['audit'].append(self._audit_fact( - 'studies.select_candidate',candidate['id'],{'study_id':study_id,'run_id':run['id'],'checkpoint_sha256':checkpoint['sha256']})) - candidate_doc={'format':FAMILY_FORMATS['candidate_history'],'origin_catalog_id':origin,'candidate':candidate} - result={'ref':{'kind':'candidate','catalog_id':origin,'id':candidate['id'],'sha256':digest(candidate)}, - 'candidate':candidate,'run_id':run['id'],'checkpoint':checkpoint} - return [envelope('study_history',origin,study_id,doc), - envelope('candidate_history',origin,candidate['id'],candidate_doc)],result - return self._mutate('studies.select_candidate',study_id,body,expected_checkpoint,request_key,build) - - def record_lineage(self,body,expected_checkpoint,request_key): - closed(body,('trial','intent'));body=checked_json(body,INTENT_LIMIT+4096) - def build(facts): - origin=self.session.summary['project_id'];trial=facts.trial_ref(body['trial']) - if body['trial']['catalog_id']!=origin:_invalid('Inherited Trials remain immutable historical evidence.','conflict') - doc=copy.deepcopy(facts.trials[(origin,trial['id'])]) - if doc['lineage'] is not None:_invalid('Trial lineage is already recorded and immutable.','conflict') - intent=validate_retained_intent(body['intent'],resolve=facts.trial_ref) - value={'format':'trial_lineage_v1','trial':copy.deepcopy(body['trial']),'intent':intent, - 'actor_id':self.access._context().actor_id,'recorded_at':timestamp(), - 'timing':'retrospective' if any(item['trial_id']==trial['id'] for item in facts.reservations.values()) else 'before_admission'} - validate_retained_lineage(value,trial=trial,resolve=facts.trial_ref) - parent=(intent['parent'] or {}).get('trial_id') - validate_retained_ancestry(trial['id'],parent,parent_of=lambda identity: - (facts.trials[(origin,identity)]['lineage']['intent']['parent'] or {}).get('trial_id') - if facts.trials[(origin,identity)]['lineage'] else None) - doc['lineage']=value - study_doc=copy.deepcopy(facts.studies[(origin,trial['study_id'])]) - study_doc['audit'].append(self._audit_fact('studies.lineage.record',trial['id'],{'intent_sha256':digest(intent)})) - return [envelope('trial_history',origin,trial['id'],doc), - envelope('study_history',origin,trial['study_id'],study_doc)],value - return self._mutate('studies.record_lineage',body.get('trial',{}).get('trial_id'),body,expected_checkpoint,request_key,build) - - def unavailable_execution(self,*args,**kwargs): - _invalid('Project execution and candidate preparation require the M3 custody boundary.','unavailable') - - approve=admit=continue_study=stop=prepare_package=prepare_verifier=unavailable_execution diff --git a/project_locks.py b/project_locks.py deleted file mode 100644 index ed906d8a..00000000 --- a/project_locks.py +++ /dev/null @@ -1,66 +0,0 @@ -"""Preserve host -> project session -> projection command lock ordering.""" -from contextlib import contextmanager, ExitStack -import threading -import time - -from metadata import CATALOG_LOCAL_TIMEOUT, CatalogBusy - - -class ProjectLock: - """CatalogLock interface for owners that begin at the projection lock. - - Owners retain the actual PostgreSQL advisory lock and its deadlines. Every - entry also owns the host authorization connection before the project - session, including background workers which have no foreground request. - """ - def __init__(self, host, session, projection): - self.host, self.session, self.projection = host, session, projection - self._local = threading.local() - - @property - def depth(self): - return self.projection.depth - - @property - def mutex(self): - return self.projection.mutex - - @property - def owned_by_current_thread(self): - return bool(getattr(self._local, 'stacks', ()) or getattr(self._local, 'bounded_depth', 0)) - - def __enter__(self): - stack = ExitStack() - try: - stack.enter_context(self.host) - if not self.session.acquire(timeout=CATALOG_LOCAL_TIMEOUT): - raise CatalogBusy('Project command ownership did not become available within its local wait bound.') - stack.callback(self.session.release) - stack.enter_context(self.projection) - if not hasattr(self._local, 'stacks'): - self._local.stacks = [] - self._local.stacks.append(stack) - return self - except BaseException: - stack.close() - raise - - def __exit__(self, kind, error, tb): - return self._local.stacks.pop().__exit__(kind, error, tb) - - @contextmanager - def bounded(self, deadline, cancelled=None): - with ExitStack() as stack: - stack.enter_context(self.host.bounded(deadline, cancelled)) - while not self.session.acquire(timeout=min(.1, max(0, deadline-time.monotonic()))): - if (cancelled and cancelled()) or time.monotonic() >= deadline: - raise CatalogBusy('Project command ownership reached its recovery deadline.') - stack.callback(self.session.release) - if (cancelled and cancelled()) or time.monotonic() >= deadline: - raise CatalogBusy('Project command ownership was cancelled or reached its recovery deadline.') - stack.enter_context(self.projection.bounded(deadline, cancelled)) - self._local.bounded_depth = getattr(self._local, 'bounded_depth', 0) + 1 - try: - yield self - finally: - self._local.bounded_depth -= 1 diff --git a/project_material.py b/project_material.py deleted file mode 100644 index 75af5b96..00000000 --- a/project_material.py +++ /dev/null @@ -1,827 +0,0 @@ -"""Portable model/source/recipe facts, using their existing semantic owners. - -Open decodes inert metadata. Only explicit publication reads projection-local -captures and snapshots their exact bytes before Session publishes a checkpoint. -No runtime is provisioned, captured source imported, or model state loaded here. -""" -import copy -import hashlib -import os -import re -import shutil -import tempfile -from functools import wraps -from datetime import datetime -from pathlib import Path - -from workbench import WorkbenchError, timestamp, encode -from model_definitions import (decode_model_draft, decode_model_material, verify_model_closure, - reference, natural, retained_json, MAX_SOURCE_BYTES) -from pipeline import decode_graph, decode_recipe_draft, decode_recipe_material, verify_recipe_closure, digest, execution_digest -from project_store import ProjectStoreError -from project_session import session_active, session_records_for - -FAMILIES = { - 'model_definition': 'model_definition_history_v1', - 'pipeline_graph': 'pipeline_graph_history_v1', - 'recipe_definition': 'recipe_definition_history_v1', - 'model_material': 'retained_model_material_v1', - 'recipe_material': 'retained_recipe_material_v1', - 'project_snapshot': 'retained_project_snapshot_v1', - 'runtime_material': 'retained_runtime_material_v1', -} -EDITABLE = ('model_definition', 'pipeline_graph', 'recipe_definition') -ID = re.compile(r'^[a-f0-9]{32}$') -SHA = re.compile(r'^[a-f0-9]{64}$') -AUDIT_FIELDS = {'action','target','details','result','actor_id','occurred_at'} -AUDIT_DETAILS = { - 'models.create':('revision','document_sha256'), - 'models.save':('revision','document_sha256'), - 'models.publish':('revision','material_sha256'), - 'pipeline.create':('revision','document_sha256','execution_sha256'), - 'pipeline.create_external':('revision','document_sha256','execution_sha256'), - 'pipeline.save':('revision','document_sha256','execution_sha256'), - 'pipeline.clone':('source_graph_id','revision','document_sha256','execution_sha256'), - 'pipeline.clone_retained':('id','revision','material'), - 'recipes.create':('revision','document_sha256'), - 'recipes.save':('revision','document_sha256'), - 'recipes.material':('recipe_id','revision'), -} -AUDIT_ACTIONS = frozenset(AUDIT_DETAILS) - - -def _boundary(function): - @wraps(function) - def checked(*args, **kwargs): - try:return function(*args, **kwargs) - except (WorkbenchError,ProjectStoreError):raise - except ImportError: - raise WorkbenchError('Retained material validator is unavailable.','unavailable',409) from None - except (KeyError, TypeError, ValueError, AttributeError, OverflowError, RecursionError, UnicodeError): - raise WorkbenchError('Malformed retained material document.','invalid',400) from None - return checked - - -def _closed(value, fields, label): - if type(value) is not dict or set(value) != set(fields): - raise WorkbenchError('Invalid retained ' + label + ' fields.') - - -def _catalog(value): - if type(value) is not str or not ID.fullmatch(value): - raise WorkbenchError('Invalid retained origin catalog.') - return value - - -def _intrinsic(item): - return {'sha256': item['sha256'], 'bytes': item['bytes']} - - -def _declaration(item): - return dict(format='project_artifact_v1', **_intrinsic(item)) - - -def _edges(items, family): - required = 'execution' if family == 'runtime_material' else 'snapshot_verification' if family == 'project_snapshot' else 'material_verification' if family == 'model_material' else 'composition_verification' - result=[] - for item in items: - runtime_file=family=='runtime_material' and item['name']!='manifest.json' - role='runtime_file' if runtime_file else 'runtime_manifest' if family=='runtime_material' else 'project_manifest' if family=='project_snapshot' else 'model_source' if family=='model_material' and item['name'].startswith('source-') else 'model_policy' if family=='model_material' else 'recipe_capture' if item['name'].startswith('capture-') else 'recipe_document' - result.append(dict(name=item['name'],blob=_intrinsic(item),role=role, - preservation='regenerable' if runtime_file else 'unique',required_for=[required])) - return result - - -def _inventory(family, value): - if family == 'model_material': - material = value['material'] - return [*(material[key] for key in ('specification', 'preprocessing_policy', 'output_policy')), - *(item['blob'] for item in material['source_closure'])] - if family == 'recipe_material': - material = value['material'] - return [material['recipe_document'], material['resolved_profile'], *material['captures']] - return [] - - -def _definition(family, value, catalog_id): - if family == 'model_definition': return decode_model_draft(value, catalog_id=catalog_id) - if family == 'recipe_definition': return decode_recipe_draft(value, catalog_id=catalog_id) - if family == 'pipeline_graph': return copy.deepcopy(decode_graph(value)) - raise WorkbenchError('Unsupported material definition family.', 'unsupported', 409) - - -def _audit(value): - _closed(value,AUDIT_FIELDS,'material audit') - if (value['action'] not in AUDIT_ACTIONS or value['result']!='success' or - type(value['target']) is not str or not 1<=len(value['target'])<=128 or - value['actor_id'] is not None and (type(value['actor_id']) is not str or not ID.fullmatch(value['actor_id'])) or - type(value['occurred_at']) is not str or len(value['occurred_at'])>80): - raise WorkbenchError('Invalid material audit fact.') - target_pattern=SHA if value['action']=='recipes.material' else ID - if not target_pattern.fullmatch(value['target']):raise WorkbenchError('Invalid material audit target.') - details=value['details'];_closed(details,AUDIT_DETAILS[value['action']],'material action details') - natural(details['revision'],'Audit revision',1) - for key,item in details.items(): - if key.endswith('_sha256') and (type(item) is not str or not SHA.fullmatch(item)): - raise WorkbenchError('Invalid material audit digest.') - if key in ('id','recipe_id','source_graph_id') and (type(item) is not str or not ID.fullmatch(item)): - raise WorkbenchError('Invalid material audit source identity.') - if 'material' in details: - _catalog(details['material']['catalog_id']) - reference(details['material'],'recipe_material',details['material']['catalog_id']) - instant=datetime.fromisoformat(value['occurred_at']) - if instant.utcoffset() is None:raise WorkbenchError('Material audit requires an offset timestamp.') - - -def _definition_audit(family,value,audit,catalog_id): - _audit(audit) - actions={'model_definition':('models.create','models.save'), - 'recipe_definition':('recipes.create','recipes.save'), - 'pipeline_graph':('pipeline.create','pipeline.create_external','pipeline.save','pipeline.clone','pipeline.clone_retained')} - if audit['action'] not in actions[family] or audit['target']!=value['id']: - raise WorkbenchError('Definition audit action or identity differs.') - details=audit['details'] - if audit['action']=='pipeline.clone_retained': - _closed(details,('id','revision','material'),'retained clone audit') - if not ID.fullmatch(details['id']) or value['revision']!=1: - raise WorkbenchError('Retained clone audit identity differs.') - natural(details['revision'],'Source recipe revision',1) - reference(details['material'],'recipe_material',catalog_id) - elif details.get('revision')!=value['revision']: - raise WorkbenchError('Definition audit revision differs.') - if audit['action'].endswith(('.create','.create_external','.clone','.clone_retained')) and value['revision']!=1: - raise WorkbenchError('Created definition audit must identify its initial revision.') - if audit['action'].endswith('.save') and value['revision']<2: - raise WorkbenchError('Saved definition audit requires a successor revision.') - if 'document_sha256' in details and details['document_sha256']!=digest(value): - raise WorkbenchError('Definition audit document hash differs.') - if 'execution_sha256' in details and details['execution_sha256']!=execution_digest(value): - raise WorkbenchError('Definition audit execution hash differs.') - - -class _MaterialAccess: - """Host authorization plus transaction-scoped inert scientific audit facts.""" - def __init__(self,session):self.session=session;self.host=session.access;self.facts=[];self.registered=False - def require(self,*args,**kwargs):return self.host.require(*args,**kwargs) - def denial(self,*args,**kwargs):return self.host.denial(*args,**kwargs) - def _context(self):return self.host._context() - @property - def lock(self):return self.host.lock - def audit(self,action,target=None,details=None,result='success'): - if action not in AUDIT_ACTIONS or result!='success' or not self.session.db.in_transaction: - raise WorkbenchError('Material audit must share its canonical mutation.','unavailable',409) - actor=self.host.require('edit',action,target) - fact=dict(action=action,target=target,details=copy.deepcopy(details or {}),result=result, - actor_id=actor.actor_id,occurred_at=timestamp()) - _audit(fact) - if not self.registered: - self.registered=True - def clear():self.facts.clear();self.registered=False - self.session.db.on_commit(clear);self.session.db.on_rollback(clear) - self.facts.append(fact) - - -@_boundary -def decode_records(records): - """Closed family-local metadata checks; missing payloads do not erase facts.""" - result = {} - for envelope in records: - if envelope.get('family') not in FAMILIES: - continue - _closed(envelope, ('family', 'id', 'document'), 'material envelope') - family, doc = envelope['family'], envelope['document'] - if family in EDITABLE: - _closed(doc, ('format', 'origin_catalog_id', 'current', 'revisions', 'audit') + - (('fork_origin',) if 'fork_origin' in doc else ()), 'definition history') - else: - _closed(doc, ('format', 'origin_catalog_id', 'value', 'artifacts','audit'), 'immutable material') - if doc['format'] != FAMILIES[family]: - raise WorkbenchError('Unsupported material document format.', 'unsupported', 409) - catalog_id = _catalog(doc['origin_catalog_id']) - if family in EDITABLE: - revisions = doc['revisions'] - forked = 'fork_origin' in doc - if (type(revisions) is not list or not revisions or type(doc['audit']) is not list or - len(doc['audit']) != len(revisions) - int(forked)): - raise WorkbenchError('Definition history must retain its observed revisions and audit.') - previous = None - for index, value in enumerate(revisions): - from project_material_fork import is_intent, decode_intent - if is_intent(value): - if not forked or index != 0 or len(revisions) != 1: - raise WorkbenchError('Unresolved fork intents cannot acquire owner revisions.') - value = decode_intent(value, family, catalog_id) - else: - value = _definition(family, value, catalog_id) - if previous and (value['id'] != previous['id'] or value['revision'] != previous['revision'] + 1): - raise WorkbenchError('Definition history identity or revision changed.') - if not forked or index: - _definition_audit(family, value, doc['audit'][index - int(forked)], catalog_id) - previous = value - if doc['current'] != revisions[-1]: - raise WorkbenchError('Definition current value differs from its history.') - expected = catalog_id + '.' + doc['current']['id'] - else: - if type(doc['audit']) is not list:raise WorkbenchError('Material audit must retain its fact list.') - for audit in doc['audit']:_audit(audit) - value = doc['value'] - if family == 'model_material': value = decode_model_material(value, catalog_id=catalog_id) - elif family == 'recipe_material': value = decode_recipe_material(value, catalog_id=catalog_id) - elif family == 'project_snapshot': - from projects import decode_retained_snapshot - value = decode_retained_snapshot(value) - else: - value = decode_runtime_material(value, catalog_id=catalog_id) - for audit in doc['audit']: - if family=='model_material': - if (audit['action']!='models.publish' or audit['target']!=value['ref']['id'] or - audit['details']!={'revision':value['ref']['revision'],'material_sha256':value['ref']['sha256']}): - raise WorkbenchError('Published Model audit differs.') - elif family=='recipe_material': - if (audit['action']!='recipes.material' or audit['target']!=value['ref']['sha256'] or - audit['details']!={'recipe_id':value['material']['recipe_id'],'revision':value['material']['recipe_revision']}): - raise WorkbenchError('Retained Recipe audit differs.') - else:raise WorkbenchError('Unsupported immutable material audit fact.') - inventory = _inventory(family, value) - if family == 'project_snapshot': - if type(doc['artifacts']) is not list or len(doc['artifacts'])!=1:raise WorkbenchError('Snapshot requires its exact manifest edge.') - size=doc['artifacts'][0]['blob']['bytes'];natural(size,'Manifest bytes',1,64*1024) - inventory=[dict(name=value['manifest_path'],sha256=value['manifest_sha256'],bytes=size)] - if family == 'runtime_material': - inventory=([dict(name='manifest.json',sha256=value['descriptor']['manifest_sha256'],bytes=value['descriptor']['manifest_bytes'])]+ - [dict(name=item['path'],sha256=item['sha256'],bytes=item['bytes']) for item in value['manifest']['files']]) if value['descriptor'] is not None else [] - if type(doc['artifacts']) is not list or doc['artifacts'] != _edges(inventory,family): - raise WorkbenchError('Retained material artifact edges differ from the owner inventory.') - expected = catalog_id + '.' + (value['manifest_sha256'] if family == 'project_snapshot' else value['ref']['sha256']) - if envelope['id'] != expected or (family, expected) in result: - raise WorkbenchError('Retained material locator differs or repeats.') - result[(family, expected)] = copy.deepcopy(doc) - from project_material_fork import validate_records - validate_records(records) - return result - - -@_boundary -def decode_runtime_material(value, *, catalog_id): - """Keep original physical descriptors as historical facts, never live bindings.""" - _closed(value, ('ref', 'descriptor', 'environment','manifest'), 'runtime material') - reference(value['ref'], 'runtime', catalog_id) - descriptor = value['descriptor'] - if descriptor is None: - if value['manifest'] is not None:raise WorkbenchError('Built-in environment cannot carry an external runtime manifest.') - if type(value['environment']) is not dict or digest(value['environment']) != value['ref']['sha256']: - raise WorkbenchError('Retained built-in runtime identity differs.') - else: - if value['environment'] is not None: - raise WorkbenchError('Retained runtime cannot mix descriptor and environment.') - if descriptor.get('profile') == 'captured_cpu_python_v1': - from recipe_process import validate_cpu_snapshot_manifest,encoded - manifest=validate_cpu_snapshot_manifest(descriptor,value['manifest']) - elif descriptor.get('profile') == 'managed_torch_python_v1': - from torch_runtime import verify_retained_descriptor,encoded - manifest=verify_retained_descriptor(descriptor,value['manifest']) - else: raise WorkbenchError('Unsupported retained runtime profile.', 'unsupported', 409) - raw=encoded(manifest) - if len(raw)!=descriptor['manifest_bytes'] or hashlib.sha256(raw).hexdigest()!=descriptor['manifest_sha256']: - raise WorkbenchError('Retained runtime manifest identity differs.') - if descriptor['catalog_id'] != catalog_id or digest(descriptor) != value['ref']['sha256']: - raise WorkbenchError('Retained runtime descriptor identity differs.') - return copy.deepcopy(value) - - -@_boundary -def validate_operation_result(operation, result, records=None): - """True for a validated owned result; False for another fixed owner.""" - if operation in ('models.create','models.save'): - decode_model_draft(result,catalog_id=result['task']['catalog_id']);family='model_definition' - elif operation=='models.publish': - decode_model_material(result,catalog_id=result['ref']['catalog_id']);family='model_material' - elif operation in ('graphs.create','graphs.create_external','graphs.save','graphs.clone'): - decode_graph(result);family='pipeline_graph' - elif operation in ('recipes.create','recipes.save'): - decode_recipe_draft(result,catalog_id=result['task']['catalog_id']);family='recipe_definition' - elif operation in ('recipes.material','recipes.prepare_external_material','recipes.prepare_builtin_material'): - decode_recipe_material(result,catalog_id=result['ref']['catalog_id']);family='recipe_material' - else:return False - if family in EDITABLE: - create=operation.endswith(('.create','.create_external','.clone')) - if create and result['revision']!=1 or not create and result['revision']<2: - raise WorkbenchError('Retained definition result revision differs from its operation.') - if records is not None: - documents=decode_records(records) - values=[value for (owned,_),doc in documents.items() if owned==family - for value in (doc['revisions'] if family in EDITABLE else [doc['value']])] - if not any(encode(value)==encode(result) for value in values): - raise WorkbenchError('Material operation result differs from its retained family closure.') - return True - - -def _retained_value(get_documents, family, ref): - catalog_id = _catalog(ref['catalog_id']) - reference(ref, {'model_material':'model', 'recipe_material':'recipe_material', - 'runtime_material':'runtime'}[family], catalog_id) - key = catalog_id + '.' + ref['sha256'] - document = get_documents().get((family, key)) - if document is None: - raise WorkbenchError('Retained material is unavailable.', 'unavailable', 409) - if document['value']['ref'] != ref: - raise WorkbenchError('Retained material reference differs.', 'invalid', 400) - # Decoded retained values are plain JSON: an exact independent copy. - from project_store import copy_validated_json - return copy_validated_json(document['value']) - - -class MaterialSnapshot: - """Owned, validated material facts for one fixed checkpoint read. - - The decoder copies the selected documents. Neither input mutation nor a - returned value can alter this view. It has no live Session, artifact reader, - publication operation or current execution authority. - """ - @_boundary - def __init__(self, records): - self.__documents = decode_records(records) - - @_boundary - def recipe(self, ref): - return _retained_value(lambda: self.__documents, 'recipe_material', ref) - - @_boundary - def runtime(self, ref): - return _retained_value(lambda: self.__documents, 'runtime_material', ref) - - def artifact_blobs(self): - for document in self.__documents.values(): - for edge in document.get('artifacts', []): - yield copy.deepcopy(edge['blob']) - - -class ProjectMaterial: - def __init__(self, session): - self.session = session - self.owner_access = _MaterialAccess(session) if hasattr(session,'access') else None - - def _documents(self): - self.session.check_current() - return decode_records(session_records_for(self.session, *FAMILIES, 'project_fork')) - - def read_view(self, records): - """Own validated material facts from one guarded checkpoint read. - - The history reader supplies its selected records. This view carries no - live publication, verification or execution capability; later reads - must select their own checkpoint and construct a new view. - """ - self.session.check_current() - return MaterialSnapshot(records) - - @_boundary - def intents(self): - """Inspect unresolved active definitions; they confer no execution binding.""" - if self.owner_access: - self.session.access.require('inspect', 'project_material.intents') - from project_fork import active_records - from project_material_fork import is_intent - documents = self._documents() - active = {(r['family'], r['id']) for r in session_active(self.session, - *FAMILIES, project_id=self.session.summary['project_id'])} - return [dict(family=family, id=locator, current=copy.deepcopy(doc['current']), - fork_origin=copy.deepcopy(doc['fork_origin'])) - for (family, locator), doc in sorted(documents.items()) - if (family, locator) in active and family in EDITABLE and is_intent(doc['current'])] - - @_boundary - def intent_capabilities(self): - intents = self.intents() - unresolved = {(r['family'],r['id']) for r in intents} - from project_fork import active_records - active = session_active(self.session, *EDITABLE, project_id=self.session.summary['project_id']) - return dict(requires_reselection=[dict(family=r['family'],id=r['id'],fields=r['current']['required_reselection']) for r in intents], - editable=[dict(family=r['family'],id=r['id']) for r in active - if r['family'] in EDITABLE and (r['family'],r['id']) not in unresolved]) - - def _require_resolved(self, family, identity): - for intent in self.intents(): - if intent['family'] == family and intent['current']['id'] == identity: - raise WorkbenchError('Fork intent requires explicit binding reselection.', 'requires_reselection', 409) - - @_boundary - def _value(self, family, ref): - return _retained_value(self._documents, family, ref) - - @_boundary - def model(self, ref, *, verify=False): - value = self._value('model_material', ref) - if verify: verify_model_closure(value, read_blob=lambda item, maximum: self.blob(ref, item, maximum)) - return value - - @_boundary - def recipe(self, ref, *, verify=False): - value = self._value('recipe_material', ref) - if verify: self.composition_closure(ref) - return value - - @_boundary - def blob(self, ref, item, maximum=40*1024**2): - family = 'model_material' if ref['kind'] == 'model' else 'recipe_material' - value = self._value(family, ref) - if item not in _inventory(family, value): raise WorkbenchError('Undeclared material blob.', 'invalid', 400) - return self.session.artifacts.read_blob(_intrinsic(item), maximum_bytes=maximum) - - @_boundary - def composition_closure(self, ref): - value = self.recipe(ref) - return verify_recipe_closure(value, self.model(value['material']['model']), read_blob=self.blob) - - @_boundary - def runtime(self, ref, *, verify=False): - value = self._value('runtime_material', ref) - if verify and value['descriptor'] is not None: - descriptor = value['descriptor'] - raw = self.session.artifacts.read_blob({'sha256': descriptor['manifest_sha256'], 'bytes': descriptor['manifest_bytes']}, maximum_bytes=32*1024**2) - if descriptor['profile'] == 'captured_cpu_python_v1': - from recipe_process import decode, encoded, validate_cpu_manifest - manifest = validate_cpu_manifest(decode(raw)) - else: - from torch_runtime import decode, encoded, validate_retained_manifest - manifest = validate_retained_manifest(decode(raw)) - if encoded(manifest) != raw: raise WorkbenchError('Retained runtime manifest encoding differs.', 'invalid', 400) - return value - - @_boundary - def snapshot_ref(self, project_id, manifest_sha256, *, catalog_id=None, verify=False): - candidates = [doc for (family, _), doc in self._documents().items() if family == 'project_snapshot' and - doc['value']['id'] == project_id and doc['value']['manifest_sha256'] == manifest_sha256 and - (catalog_id is None or doc['origin_catalog_id'] == catalog_id)] - if len(candidates) != 1: raise WorkbenchError('Retained project snapshot is unavailable or ambiguous.', 'unavailable', 409) - doc = candidates[0] - if verify: - from projects import decode, decode_retained_manifest - edge = doc['artifacts'][0]['blob'] - raw = self.session.artifacts.read_blob(edge, maximum_bytes=64*1024) - if decode_retained_manifest(decode(raw)) != doc['value']['manifest']: - raise WorkbenchError('Retained project manifest differs.', 'invalid', 400) - return copy.deepcopy(doc['value']) - - def capture_definition(self, family, value, before_records, *, action, actor_id=None, audit_facts=None): - catalog_id = self.session.summary['project_id'] - value = _definition(family, value, catalog_id) - key = catalog_id + '.' + value['id'] - prior = decode_records(before_records).get((family, key)) - revisions = copy.deepcopy(prior['revisions']) if prior else [] - audits = copy.deepcopy(prior['audit']) if prior else [] - if revisions and value == revisions[-1]: - return {'family': family, 'id': key, 'document': prior} - if revisions and value['revision'] != revisions[-1]['revision'] + 1: - raise WorkbenchError('Definition changed outside its canonical history.', 'stale', 409) - details={'revision':value['revision'],'document_sha256':digest(value)} - if family=='pipeline_graph':details['execution_sha256']=execution_digest(value) - facts=copy.deepcopy(audit_facts) if audit_facts is not None else [dict(action=action,target=value['id'],details=details,result='success',actor_id=actor_id,occurred_at=timestamp())] - if len(facts)!=1:raise WorkbenchError('A definition revision requires its exact owner audit fact.') - revisions.append(copy.deepcopy(value));audits.extend(facts) - record = dict(family=family, id=key, document=dict(format=FAMILIES[family], origin_catalog_id=catalog_id, - current=copy.deepcopy(value), revisions=revisions, audit=audits)) - if prior and 'fork_origin' in prior: - from project_material_fork import is_intent - if is_intent(prior['current']): - raise WorkbenchError('Fork intent requires explicit binding reselection.', 'requires_reselection', 409) - record['document']['fork_origin'] = copy.deepcopy(prior['fork_origin']) - decode_records([r for r in before_records if (r['family'],r['id']) != (family,key)] + [record]) - else: - decode_records([record]) - return record - - def _capture_material(self, family, value, root): - catalog_id = value['ref']['catalog_id'] - value = decode_model_material(value, catalog_id=catalog_id) if family == 'model_material' else decode_recipe_material(value, catalog_id=catalog_id) - inventory = _inventory(family, value) - root_fd = material_fd = None - try: - root_fd = os.open(root, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW) - material_fd = os.open(value['ref']['sha256'], os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=root_fd) - for item in inventory: - fd = os.open(item['name'], os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK, dir_fd=material_fd) - try: self.session.artifacts.publish_fd(fd, _declaration(item), maximum_bytes=item['bytes']) - finally: os.close(fd) - except OSError: - raise WorkbenchError('Projection-local material capture is unavailable.','unavailable',409) from None - finally: - if material_fd is not None: os.close(material_fd) - if root_fd is not None: os.close(root_fd) - record = dict(family=family, id=catalog_id+'.'+value['ref']['sha256'], document=dict( - format=FAMILIES[family], origin_catalog_id=catalog_id, value=copy.deepcopy(value), artifacts=_edges(inventory,family), - audit=copy.deepcopy([fact for fact in self.owner_access.facts - if fact['action']==('models.publish' if family=='model_material' else 'recipes.material') - and fact['target'] in (value['ref'].get('id'),value['ref']['sha256'])]) if self.owner_access else [])) - prior=decode_records(session_records_for(self.session, *FAMILIES, 'project_fork')).get((family,record['id'])) - if prior is not None: - if prior['value']!=record['document']['value'] or prior['artifacts']!=record['document']['artifacts']: - raise WorkbenchError('Retained immutable material changed.','invalid',400) - facts=copy.deepcopy(prior['audit']) - facts.extend(fact for fact in record['document']['audit'] if fact not in facts) - record['document']['audit']=facts - decode_records([record]); return record - - @staticmethod - def declarations(record): - """Explicit intrinsic declaration upserts, coalesced without hidden state.""" - result={} - for edge in record['document'].get('artifacts',[]): - item=edge['blob']; declaration=_declaration(item) - if item['sha256'] in result and result[item['sha256']]['document']!=declaration: - raise WorkbenchError('Artifact declarations disagree.','invalid',400) - result[item['sha256']]=dict(family='project_artifact',id=item['sha256'],document=declaration) - return list(result.values()) - - def capture_model_material(self, value, root): return self._capture_material('model_material', value, root) - def capture_recipe_material(self, value, root): return self._capture_material('recipe_material', value, root) - - @staticmethod - def _coalesce(records): - result={} - for record in records: - key=record['family'],record['id'] - if key in result and result[key]!=record: - raise WorkbenchError('Owned material upserts disagree.','invalid',400) - result[key]=record - return list(result.values()) - - @_boundary - def capture_recipe_dependencies(self,record,before_records,*,runtime_manifest=None): - """Retain exact measured runtime facts without using origin paths. - - Captured runtime manifests must be supplied by an explicit trusted - current-runtime reader, or already be part of the canonical checkpoint. - This method never provisions or captures runtime binaries. - """ - value=record['document']['value'];ref=value['material']['runtime'] - snapshot=retained_json(self.session.artifacts.read_blob( - _intrinsic(value['material']['recipe_document']),maximum_bytes=2*1024**2).decode(),2*1024**2) - if snapshot['format']=='builtin_recipe_snapshot_v1':environment=snapshot['validation']['runtime'] - else: - execution=snapshot['preflight']['material'] - environment=execution.get('torch_runtime',execution.get('cpu_snapshot',execution['runtime'])) - descriptor=environment if environment.get('profile') in ('captured_cpu_python_v1','managed_torch_python_v1') else None - prior=decode_records(before_records).get(('runtime_material',ref['catalog_id']+'.'+ref['sha256'])) - if prior is not None: - expected=prior['value']['descriptor'] if descriptor is not None else prior['value']['environment'] - if expected!=environment or prior['value']['ref']!=ref: - raise WorkbenchError('Recipe and retained runtime identity differ.','invalid',400) - if descriptor is not None: - if runtime_manifest is not None: - raw=runtime_manifest(copy.deepcopy(descriptor)) if callable(runtime_manifest) else runtime_manifest - retained=self.capture_runtime(prior['value'],raw) - return [*self.declarations(retained),retained] - self.session.artifacts.read_blob({'sha256':descriptor['manifest_sha256'],'bytes':descriptor['manifest_bytes']},maximum_bytes=32*1024**2) - return [] - manifest=None - manifest_raw=None - if descriptor is not None: - manifest_raw=runtime_manifest(copy.deepcopy(descriptor)) if callable(runtime_manifest) else runtime_manifest - if type(manifest_raw) is not bytes: - raise WorkbenchError('Explicit captured runtime manifest is unavailable.','unavailable',409) - if descriptor['profile']=='captured_cpu_python_v1': - from recipe_process import decode,validate_cpu_manifest - manifest=validate_cpu_manifest(decode(manifest_raw)) - else: - from torch_runtime import decode,validate_retained_manifest - manifest=validate_retained_manifest(decode(manifest_raw)) - runtime=self.capture_runtime(dict(ref=ref,descriptor=descriptor, - environment=None if descriptor is not None else environment,manifest=manifest),manifest_raw) - return [*self.declarations(runtime),runtime] - - @_boundary - def capture_snapshot(self, value, raw, *, catalog_id): - from projects import decode_retained_snapshot,decode,decode_retained_manifest - value=decode_retained_snapshot(value);_catalog(catalog_id) - if type(raw) is not bytes or len(raw)>64*1024 or hashlib.sha256(raw).hexdigest()!=value['manifest_sha256'] or decode_retained_manifest(decode(raw))!=value['manifest']: - raise WorkbenchError('Exact original project manifest bytes differ.') - key=catalog_id+'.'+value['manifest_sha256'] - prior=decode_records(session_records_for(self.session, *FAMILIES, 'project_fork')).get(('project_snapshot',key)) - if prior is not None: - original=prior['value'] - if any(original[field]!=value[field] for field in ('id','name','manifest_sha256','manifest')): - raise WorkbenchError('Original snapshot identity differs.','invalid',400) - # Explicit current root registration may move. It cannot replace - # original historical root/path identity facts at the same hash. - return dict(family='project_snapshot',id=key,document=prior) - item=dict(name=value['manifest_path'],sha256=value['manifest_sha256'],bytes=len(raw)) - self.session.artifacts.publish_bytes(raw,_declaration(item),maximum_bytes=64*1024) - record=dict(family='project_snapshot',id=catalog_id+'.'+value['manifest_sha256'],document=dict( - format=FAMILIES['project_snapshot'],origin_catalog_id=catalog_id,value=value,artifacts=_edges([item],'project_snapshot'),audit=[])) - decode_records([record]);return record - - @_boundary - def capture_runtime(self,value,manifest_raw=None): - value=decode_runtime_material(value,catalog_id=value['ref']['catalog_id']) - items=[] - if value['descriptor'] is not None: - descriptor=value['descriptor'] - if type(manifest_raw) is not bytes or len(manifest_raw)!=descriptor['manifest_bytes'] or hashlib.sha256(manifest_raw).hexdigest()!=descriptor['manifest_sha256']: - raise WorkbenchError('Exact original runtime manifest bytes differ.') - item=dict(name='manifest.json',sha256=descriptor['manifest_sha256'],bytes=len(manifest_raw)) - self.session.artifacts.publish_bytes(manifest_raw,_declaration(item),maximum_bytes=32*1024**2) - items=[item,*[dict(name=row['path'],sha256=row['sha256'],bytes=row['bytes']) for row in value['manifest']['files']]] - record=dict(family='runtime_material',id=value['ref']['catalog_id']+'.'+value['ref']['sha256'],document=dict( - format=FAMILIES['runtime_material'],origin_catalog_id=value['ref']['catalog_id'],value=value,artifacts=_edges(items,'runtime_material'),audit=[])) - decode_records([record]);return record - - def restore(self): - """Rebuild only current-namespace SQL values, without mutable owners.""" - documents=self._documents();catalog_id=self.session.db.dataset_id - from project_fork import active_records - from project_material_fork import is_intent - active={(r['family'],r['id']) for r in session_active(self.session, *FAMILIES,project_id=catalog_id)} - with self.session.db.transaction(): - for table in ('model_definition_drafts','workspace_graphs','workspace_recipe_drafts','model_materials','workspace_recipe_materials'): - self.session.db.execute('DELETE FROM '+table) - for (family,locator),doc in documents.items(): - if (family,locator) not in active or doc['origin_catalog_id']!=catalog_id:continue - if family in EDITABLE and is_intent(doc['current']):continue - if family in EDITABLE: - value=doc['current'] - table={'model_definition':'model_definition_drafts','pipeline_graph':'workspace_graphs','recipe_definition':'workspace_recipe_drafts'}[family] - self.session.db.execute('INSERT INTO '+table+' VALUES(%s,%s,%s)',(value['id'],value['revision'],encode(value))) - elif family=='model_material': - value=doc['value'];ref=value['ref'] - self.session.db.execute('INSERT INTO model_materials VALUES(%s,%s,%s,%s)',(ref['id'],ref['revision'],ref['sha256'],encode(value))) - elif family=='recipe_material': - value=doc['value'];material=value['material'] - self.session.db.execute('INSERT INTO workspace_recipe_materials VALUES(%s,%s,%s,%s)',(value['ref']['sha256'],material['recipe_id'],material['recipe_revision'],encode(value))) - - def reconcile_projection(self): - """Restore selected canonical material facts without deleting local custody. - - The caller holds projection/session/access guards and has drained custody. - Immutable SQL conflicts fence recovery instead of replacing hash identity. - """ - documents = self._documents() - catalog_id = self.session.db.dataset_id - from project_fork import active_records - from project_material_fork import is_intent - active = {(r['family'], r['id']) for r in session_active(self.session, *FAMILIES, project_id=catalog_id)} - with self.session.db.transaction(): - for (family, locator), doc in documents.items(): - if (family, locator) not in active or doc['origin_catalog_id'] != catalog_id: - continue - if family in EDITABLE: - value = doc['current'] - if is_intent(value): continue - table = {'model_definition':'model_definition_drafts', 'pipeline_graph':'workspace_graphs', - 'recipe_definition':'workspace_recipe_drafts'}[family] - self.session.db.execute('INSERT INTO '+table+'(id,revision,document) VALUES(%s,%s,%s) ' - 'ON CONFLICT(id) DO UPDATE SET revision=EXCLUDED.revision,document=EXCLUDED.document', - (value['id'], value['revision'], encode(value))) - elif family in ('model_material', 'recipe_material'): - value = doc['value']; ref = value['ref'] - table = 'model_materials' if family == 'model_material' else 'workspace_recipe_materials' - if family == 'model_material': - rows = self.session.db.execute('SELECT id,revision,sha256,document FROM model_materials ' - 'WHERE sha256=%s OR (id=%s AND revision=%s)', - (ref['sha256'],ref['id'],ref['revision'])).fetchall() - consistent = len(rows) == 1 and tuple(rows[0][:3]) == (ref['id'],ref['revision'],ref['sha256']) and retained_json(rows[0][3]) == value - else: - rows = self.session.db.execute('SELECT recipe_id,recipe_revision,document FROM workspace_recipe_materials ' - 'WHERE sha256=%s', (ref['sha256'],)).fetchall() - consistent = len(rows) == 1 and tuple(rows[0][:2]) == (value['material']['recipe_id'],value['material']['recipe_revision']) and retained_json(rows[0][2]) == value - if rows: - if not consistent: - raise WorkbenchError('Immutable projection material differs from its canonical hash.', - 'projection_unavailable', 503) - continue - if family == 'model_material': - self.session.db.execute('INSERT INTO model_materials(id,revision,sha256,document) VALUES(%s,%s,%s,%s)', - (ref['id'], ref['revision'], ref['sha256'], encode(value))) - else: - material = value['material'] - self.session.db.execute('INSERT INTO workspace_recipe_materials(sha256,recipe_id,recipe_revision,document) ' - 'VALUES(%s,%s,%s,%s)', (ref['sha256'],material['recipe_id'],material['recipe_revision'],encode(value))) - - def materialize_projection(self,ref,root): - """Explicit preparation may recreate a disposable owner byte cache. - - The destination must live inside the current physical SQL projection. - Canonical files and original runtime paths are never cleanup targets. - """ - root=Path(root) - if not root.resolve().is_relative_to(Path(self.session.db.path).resolve()): - raise WorkbenchError('Material cache must belong to the disposable projection.','invalid',400) - value=self.model(ref) if ref['kind']=='model' else self.recipe(ref) - family='model_material' if ref['kind']=='model' else 'recipe_material' - inventory=_inventory(family,value) - root.mkdir(mode=0o700,parents=True,exist_ok=True) - target=root/ref['sha256'] - if target.exists(): - from model_definitions import read_owned_blob - if target.is_symlink() or set(os.listdir(target))!={item['name'] for item in inventory}: - raise WorkbenchError('Disposable material cache differs.','unavailable',409) - for item in inventory:read_owned_blob(root,ref['sha256'],item,item['bytes']) - return target - staging=Path(tempfile.mkdtemp(prefix='.material-rebuild-',dir=root)) - try: - for item in inventory: - with self.session.artifacts.open_verified(_declaration(item),maximum_bytes=item['bytes']) as source: - with (staging/item['name']).open('xb') as destination: - while True: - raw=os.read(source,1024**2) - if not raw:break - destination.write(raw) - destination.flush();os.fchmod(destination.fileno(),0o400);os.fsync(destination.fileno()) - from metadata import _sync_directory - _sync_directory(staging) - # The Session lock serializes owner cache publication. An externally - # created target is refused, never adopted or overwritten. - if os.path.lexists(target):raise WorkbenchError('Material cache changed during reconstruction.','stale',409) - os.rename(staging,target);_sync_directory(root) - return target - finally: - if staging.exists():shutil.rmtree(staging) - - def prepare_recipe(self,owner,graph_id,revision,model_ref,expected_checkpoint,key,*,builtin=False,reconcile_capture=False,runtime_manifest=None): - self._require_resolved('pipeline_graph', graph_id) - operation='recipes.prepare_builtin_material' if builtin else 'recipes.prepare_external_material' - self.session.access.require('edit',operation,graph_id,owner_only=reconcile_capture and not builtin) - if builtin: - if reconcile_capture: - raise WorkbenchError('Built-in orphan capture reconciliation is unsupported.','unsupported',409) - from project_native_preparation import preparation_owner - current=preparation_owner(owner) - if current is None:raise WorkbenchError('Current project preparation for the runtime probe is unavailable.','unavailable',409) - return current.prepare_recipe(owner,graph_id,revision,model_ref,expected_checkpoint,key) - body=dict(graph_id=graph_id,revision=revision,model=model_ref,reconcile_capture=reconcile_capture) - def invoke(): - self.materialize_projection(model_ref,owner.dataset.models.path) - prepare=owner.prepare_builtin_material if builtin else owner.prepare_external_material - prepared=prepare(graph_id,revision,model_ref,reconcile_capture=reconcile_capture) - return owner._retain_material(prepared) - def capture(result,before): - record=self.capture_recipe_material(result,owner.material_path) - return {'records':self._coalesce([*self.declarations(record),record, - *self.capture_recipe_dependencies(record,before,runtime_manifest=runtime_manifest)]),'result':result} - return self.session.mutate(operation,graph_id,body,expected_checkpoint,key,invoke,capture) - - def mutate_definition(self, family, operation, target, body, expected_checkpoint, key, invoke): - authority = self.session.access.require('edit', operation, target) - def capture(result, before): - validate_operation_result(operation, result) - return {'records': [self.capture_definition(family,result,before,action=operation,actor_id=authority.actor_id, - audit_facts=[fact for fact in self.owner_access.facts if fact['target']==result['id']])], 'result': result} - return self.session.mutate(operation, target, body, expected_checkpoint, key, invoke, capture) - - def publish_model(self, owner, model_id, body, expected_checkpoint, key): - self._require_resolved('model_definition', model_id) - self.session.access.require('edit', 'models.publish', model_id, owner_only=body.get('reconcile_capture', False)) - def capture(result, before): - record=self.capture_model_material(result,owner.path) - return {'records': [*self.declarations(record),record], 'result': result} - return self.session.mutate('models.publish', model_id, body, expected_checkpoint, key, - lambda: owner.publish(model_id, body), capture) - - def retain_recipe(self, owner, prepared, expected_checkpoint, key, *, runtime_manifest=None): - value = prepared['document']; target = value['material']['recipe_id'] - self.session.access.require('edit', 'recipes.prepare_external_material', target, - owner_only=prepared.get('reconcile_capture', False)) - body = {'ref': value['ref']} - def capture(result, before): - record=self.capture_recipe_material(result,owner.material_path) - return {'records': self._coalesce([*self.declarations(record),record, - *self.capture_recipe_dependencies(record,before,runtime_manifest=runtime_manifest)]), 'result': result} - return self.session.mutate('recipes.material', target, body, expected_checkpoint, key, - lambda: owner._retain_material(prepared), capture) - - @_boundary - def evidence(self, run, selectors=None, *, read_blob=None): - import model_evidence - import recipe_contract - selectors = {} if selectors is None else selectors - inventory = {item['name']: item for item in run['artifacts']} - def read(name, maximum): - if name not in inventory: raise WorkbenchError('Evidence artifact is unavailable.', 'unavailable', 409) - item = inventory[name] - raw = read_blob(name, maximum) if read_blob else self.session.artifacts.read_blob(_intrinsic(item), maximum_bytes=maximum) - if type(raw) is not bytes or len(raw)>maximum or len(raw)!=item['bytes'] or hashlib.sha256(raw).hexdigest()!=item['sha256']: - raise WorkbenchError('Evidence artifact differs.', 'invalid', 400) - return raw - if run.get('extension_context') is not None: - import extension_evidence - ref = {'kind': 'recipe_material', 'catalog_id': run['dataset_id'], 'id': run['approval_material_sha256'], 'sha256': run['approval_material_sha256']} - composition = self.recipe(ref); closure = self.composition_closure(ref) - context = extension_evidence.validate_context(run['extension_context'], run, composition, closure['static_context']) - verified = extension_evidence.verify_blobs(run, context, read_blob=read, captured=closure['captured_inputs']) - return extension_evidence.query(verified, selectors) - from pipeline import adapter_for_graph, model_aware_graph - import image_training - if not model_aware_graph(run['graph']): return {'state': 'unsupported', 'reason': 'This retained adapter did not capture model_evidence_v1.'} - if set(selectors) - {'checkpoint_sha256', 'split'} or selectors.get('split', 'validation') != 'validation': - raise WorkbenchError('Unsupported retained evidence selector.', 'unsupported', 409) - if adapter_for_graph(run['graph']) is image_training: evaluator = model_evidence - else: - import one_fit_evidence as evaluator - result, descriptors, predictions = evaluator.verify_blobs(run, run['metrics'], read_blob=read) - result.update(checkpoint=None, predictions=None, metric_definition_hashes={item['id']: model_evidence.digest(item) for item in result['metric_definitions']}) - selected = selectors.get('checkpoint_sha256') - if selected is not None: - matches = [index for index, entry in enumerate(result['checkpoint_index']['entries']) if entry['checkpoint']['sha256'] == selected] - if not matches: raise WorkbenchError('Checkpoint does not belong to this Run.', 'not_found', 404) - result.update(checkpoint=descriptors[matches[0]], predictions=predictions[matches[0]]) - return result diff --git a/project_material_fork.py b/project_material_fork.py deleted file mode 100644 index deb35c8c..00000000 --- a/project_material_fork.py +++ /dev/null @@ -1,202 +0,0 @@ -"""Pure, finite reconstruction of editable materials for an independent fork. - -Original definitions and hash-bearing materials remain unchanged in the archive. -Unresolved bindings are retained as inert, inspectable intents, never SQL drafts. -""" -import copy -from datetime import datetime - -from workbench import WorkbenchError - -INTENT_FORMAT = 'project_material_fork_intent_v1' -OWNED = ('model_definition', 'pipeline_graph', 'recipe_definition') - - -def _fail(message): - raise WorkbenchError(message, 'invalid', 400) - - -def _date(value): - if type(value) is not str or len(value) > 80: - _fail('Fork creation requires an offset timestamp.') - try: - instant = datetime.fromisoformat(value) - if instant.utcoffset() is None: raise ValueError() - except ValueError: - _fail('Fork creation requires an offset timestamp.') - - -def is_intent(value): - return type(value) is dict and value.get('format') == INTENT_FORMAT - - -def _model_bindings(value, destination): - """Qualify only exact pure templates accepted by the existing task owners.""" - import image_training - import model_evidence - import one_fit_evidence - import text_training - import audio_training - task = value['task'] - owners = [(model_evidence, image_training), - (one_fit_evidence.contract(text_training), text_training), - (one_fit_evidence.contract(audio_training), audio_training)] - for owner, adapter in owners: - if task != owner.task_ref(task['catalog_id']): continue - required = [] - definition = None - specification = value['specification'] - try: - if adapter is image_training: - if specification.get('template') != 'tinycnn_v2': raise ValueError() - architecture = image_training.validate_architecture( - {k:v for k,v in specification.items() if k != 'template'}) - definition = dict(specification=dict(template='tinycnn_v2', **architecture), - preprocessing_policy=image_training.transform_for_parameters(architecture), - output_policy=model_evidence.OUTPUT_POLICY) - else: - if specification.get('template') != owner.template: raise ValueError() - definition = owner.model_definition({k:v for k,v in specification.items() if k != 'template'}) - except ValueError: - required.append('specification') - if definition is not None: - required.extend(field for field in ('specification','preprocessing_policy','output_policy') - if value[field] != definition[field]) - elif value['output_policy'] != owner.OUTPUT_POLICY: - required.append('output_policy') - return owner.task_ref(destination), sorted(set(required)) - return None, ['task'] - - -def _construct(family, source, identity, catalog): - """Rebuild only explicitly understood bindings; retain every other field.""" - from project_material import _definition - original = copy.deepcopy(source['definition'] if is_intent(source) else source) - required = [] - if family == 'model_definition': - task, required = _model_bindings(original, catalog) - if original['kind'] != 'template': required.append('source_selector') - if not required: - value = dict(original, id=identity, revision=1, task=task) - return _definition(family, value, catalog) - elif family == 'pipeline_graph': - if original.get('recipe') == 'external_recipe': - required = ['recipe_source', 'inputs', 'runtime'] - elif any(node['type'] == 'release' for node in original['nodes']): - required = ['release'] - elif any(node['type'] not in ('train', 'evaluate', 'validate', 'publish') or - node['type'] != 'train' and node['parameters'] for node in original['nodes']): - required = ['nodes'] - else: - # The graph owner owns its closed structure and adapter selection. - # No release, recipe-source or external input binding is adopted. - from pipeline import adapter_for_graph, types_for_graph - import image_training - adapter = adapter_for_graph(original) - try: - for node in original['nodes']: - if node['type'] not in types_for_graph(original): raise ValueError() - if node['type'] == 'train': - validate = (image_training.validate_model_parameters if original.get('recipe') == image_training.MODEL_RECIPE - else adapter.validate_parameters) - validate(node['parameters']) - except ValueError: - required = ['nodes'] - else: - return _definition(family, dict(original, id=identity, revision=1), catalog) - elif family == 'recipe_definition': - required = ['data', 'evaluation_profile', 'model', 'runtime', 'task', 'trainer'] - else: - _fail('Unsupported editable material fork family.') - return dict(format=INTENT_FORMAT, catalog_id=catalog, id=identity, revision=1, - name=original['name'], definition_family=family, definition=original, - required_reselection=sorted(required)) - - -def decode_intent(value, family, catalog): - from project_material import _closed, _catalog, _definition, ID - _closed(value, ('format', 'catalog_id', 'id', 'revision', 'name', - 'definition_family', 'definition', 'required_reselection'), 'fork intent') - if (value['format'] != INTENT_FORMAT or value['catalog_id'] != catalog or - value['definition_family'] != family or type(value['id']) is not str or - not ID.fullmatch(value['id']) or type(value['revision']) is not int or value['revision'] != 1): - _fail('Invalid material fork intent identity.') - old = value['definition'] - origin = old['task']['catalog_id'] if family != 'pipeline_graph' else catalog - _catalog(origin) - _definition(family, old, origin) - if _construct(family, old, value['id'], catalog) != value: - _fail('Material fork intent differs from its exact unresolved definition.') - return copy.deepcopy(value) - - -def fork_records(records, source_project_id, source_checkpoint, destination_project_id, *, id_factory, created_at): - from project_material import decode_records, FAMILIES, _catalog, SHA, ID - from project_fork import active_records - _catalog(source_project_id); _catalog(destination_project_id); _date(created_at) - if source_project_id == destination_project_id or type(source_checkpoint) is not str or not SHA.fullmatch(source_checkpoint): - _fail('Independent material fork requires a distinct identity and source checkpoint.') - decode_records(records) - active = active_records(records, project_id=source_project_id) - existing = {r['document']['current']['id'] for r in records if r['family'] in OWNED} - fresh, mapping = [], [] - for envelope in sorted(active, key=lambda r: (r['family'], r['id'])): - family = envelope['family'] - if family not in OWNED: continue - old = envelope['document']['current'] - identity = id_factory(family, envelope['id'], old['revision']) - if type(identity) is not str or not ID.fullmatch(identity) or identity in existing: - _fail('Material fork allocator must supply a fresh editable UUID.') - existing.add(identity) - value = _construct(family, old, identity, destination_project_id) - locator = destination_project_id + '.' + identity - fresh.append(dict(family=family, id=locator, document=dict(format=FAMILIES[family], - origin_catalog_id=destination_project_id, current=value, revisions=[copy.deepcopy(value)], audit=[], - fork_origin=dict(project_id=source_project_id, checkpoint=source_checkpoint, family=family, - id=envelope['id'], revision=old['revision'], created_at=created_at)))) - mapping.append(dict(family=family, source_id=envelope['id'], source_revision=old['revision'], destination_id=locator)) - mapping.sort(key=lambda m: (m['family'],m['source_id'],m['source_revision'],m['destination_id'])) - return dict(records=fresh, mapping=mapping) - - -def validate_records(records): - """Prove each fork's unaudited initial revision from exact retained owners.""" - from project_material import _closed, _catalog, SHA - from project_fork import decode_fork - if not any(r.get('family') == 'project_fork' or - r.get('family') in OWNED and 'fork_origin' in r.get('document', {}) for r in records): - return - decode_fork(records) - indexed = {(r['family'],r['id']):r for r in records} - overlays = [r['document'] for r in records if r['family'] == 'project_fork'] - mapped = {} - for overlay in overlays: - for mapping in overlay['mapping']: - if mapping['family'] in OWNED: - key = mapping['family'],mapping['destination_id'] - if key in mapped: _fail('Material fork target repeats across origin overlays.') - mapped[key] = (overlay, mapping) - for record in records: - if record['family'] not in OWNED: continue - doc = record['document']; key = record['family'],record['id'] - origin = doc.get('fork_origin') - if origin is None: - if key in mapped: _fail('Mapped material draft lacks its explicit fork origin.') - continue - _closed(origin, ('project_id','checkpoint','family','id','revision','created_at'), 'material fork origin') - _catalog(origin['project_id']); _date(origin['created_at']) - if type(origin['checkpoint']) is not str or not SHA.fullmatch(origin['checkpoint']): - _fail('Invalid material fork source checkpoint.') - if key not in mapped: _fail('Material fork origin lacks a retained mapping.') - overlay, mapping = mapped[key] - expected = dict(project_id=overlay['source']['project_id'], checkpoint=overlay['source']['checkpoint'], - family=mapping['family'], id=mapping['source_id'], revision=mapping['source_revision'], - created_at=origin['created_at']) - if origin != expected or doc['origin_catalog_id'] != overlay['destination_project_id']: - _fail('Material fork origin differs from its archived source mapping.') - original = indexed[(mapping['family'],mapping['source_id'])]['document']['current'] - if original['revision'] != origin['revision']: - _fail('Material fork source revision differs from its archived current value.') - initial = _construct(record['family'], original, doc['current']['id'], doc['origin_catalog_id']) - if doc['revisions'][0] != initial: - _fail('Material fork initial revision differs from its owner reconstruction.') diff --git a/project_measurements.py b/project_measurements.py deleted file mode 100644 index e64a307e..00000000 --- a/project_measurements.py +++ /dev/null @@ -1,260 +0,0 @@ -"""Native custody and current access for immutable retained scalar packets. - -The scalar owner interprets the packet. ProjectArtifacts owns bytes and -ProjectSession owns publication/receipts. Retained source paths are facts only; -reads after Open need no current source registration or producer execution. -""" -import copy -from datetime import datetime -from functools import cache, partial - -from project_artifacts import validate_declaration -from project_material import decode_records as material_records -from projects import ID, NAME, SHA, relative_path -from retained_measurements import (MeasurementTable, MeasurementComparison, MAX_BYTES, MAX_RESPONSE_BYTES, - MAX_COMPARISON_SOURCES, MAX_COMPARISON_BYTES, encode, text) -from workbench import WorkbenchError, timestamp - - -FAMILY = 'measurement_source' -FORMAT = 'project_measurement_source_v1' -FIELDS = {'format', 'origin_catalog_id', 'id', 'title', 'blob', 'source', 'actor_id', 'imported_at'} - - -def _closed(value, fields): - if type(value) is not dict or set(value) != set(fields): - raise WorkbenchError('Invalid native measurement source fields.') - - -def _identity(value, pattern): - if type(value) is not str or not pattern.fullmatch(value): - raise WorkbenchError('Invalid native measurement source identity.') - return value - - -def declaration(blob): - return validate_declaration(dict(format='project_artifact_v1', **blob)) - - -def _document(value): - _closed(value, FIELDS) - if value['format'] != FORMAT: - raise WorkbenchError('Unsupported native measurement source format.', 'unsupported', 409) - for key in ('origin_catalog_id', 'actor_id'): - _identity(value[key], ID) - _identity(value['id'], SHA) - text(value['title']) - _closed(value['blob'], ('sha256', 'bytes')) - blob = declaration(value['blob']) - if not 0 < blob['bytes'] <= MAX_BYTES or blob['sha256'] != value['id']: - raise WorkbenchError('Measurement packet identity or byte bound differs.') - source = value['source'] - _closed(source, ('origin_catalog_id', 'project_id', 'manifest_sha256', 'reference_id', 'path', 'measured_sha256')) - for key in ('origin_catalog_id', 'project_id'): - _identity(source[key], ID) - for key in ('manifest_sha256', 'measured_sha256'): - _identity(source[key], SHA) - _identity(source['reference_id'], NAME) - relative_path(source['path']) - if source['measured_sha256'] != blob['sha256']: - raise WorkbenchError('Measurement source capture hash differs from its packet.') - try: - if type(value['imported_at']) is not str or len(value['imported_at']) > 80: - raise ValueError() - if datetime.fromisoformat(value['imported_at']).utcoffset() is None: - raise ValueError() - except ValueError: - raise WorkbenchError('Measurement import requires an attributed timestamp.') from None - return value - - -def decode_records(records, *, artifacts=None): - """Validate candidate closure, including exact available packet bytes. - - Missing payloads remain discoverable as missing. They never yield numerical - results. Present payloads must pass custody and scalar-source validation. - """ - declarations = {item['id']: item['document'] for item in records if item['family'] == 'project_artifact'} - snapshots = material_records(records) - result = {} - for item in records: - if item['family'] != FAMILY: - continue - doc = _document(item['document']) - identity = doc['origin_catalog_id'] + '.' + doc['id'] - if item['id'] != identity or identity in result: - raise WorkbenchError('Duplicate or inconsistent native measurement identity.') - if declarations.get(doc['blob']['sha256']) != declaration(doc['blob']): - raise WorkbenchError('Measurement artifact declaration is missing or inconsistent.') - source = doc['source'] - snapshot = snapshots.get(('project_snapshot', source['origin_catalog_id'] + '.' + source['manifest_sha256'])) - if snapshot is None or snapshot['value']['id'] != source['project_id']: - raise WorkbenchError('Measurement source snapshot is missing or inconsistent.') - reference = next((r for r in snapshot['value']['manifest']['data'] if r['id'] == source['reference_id']), None) - if (reference is None or reference['path'] != source['path'] - or reference.get('sha256', source['measured_sha256']) != source['measured_sha256']): - raise WorkbenchError('Measurement capture differs from its retained source reference.') - if artifacts is not None and artifacts.inspect(declaration(doc['blob']))['state'] != 'missing': - table = MeasurementTable(artifacts.read_blob(doc['blob'], maximum_bytes=MAX_BYTES)) - if table.metadata()['title'] != doc['title']: - raise WorkbenchError('Measurement title differs from the exact retained packet.') - result[identity] = copy.deepcopy(doc) - return result - - -def _validate_result(operation, result, lookup=None): - if operation != 'measurements.import': - return False - _document(result) - if lookup is not None: - identity = result['origin_catalog_id'] + '.' + result['id'] - if lookup(identity) != result: - raise WorkbenchError('Measurement receipt has no exact retained source.') - return True - - -def receipt_validator(records, *, artifacts=None): - """Own one candidate's validated source bindings and packet custody. - - Decode and copy every retained measurement once, including current available - packet bytes when supplied. The returned receipt checker is fixed to those - facts; it carries no live source or publication capability. - """ - owned = decode_records(records, artifacts=artifacts) - return partial(_validate_result, lookup=owned.get) - - -def validate_operation_result(operation, result, records=None): - @cache - def owned(): - return decode_records(records) - lookup = None if records is None else lambda identity: owned().get(identity) - return _validate_result(operation, result, lookup) - - -class ProjectMeasurements: - def __init__(self, session): - self.session, self.artifacts = session, session.artifacts - self.access, self.db = session.access, session.db - - def _documents(self): - # Session adoption/publication already validates the complete candidate. - # Verify current canonical bytes, then own only the measurement family. - records = self.session.check_records(FAMILY)['records'] - return {item['id']: item['document'] for item in records} - - def import_packet(self, raw, source, expected_checkpoint, key): - """Called only after SourceAdapter's explicit current rooted capture.""" - with self.access.lock, self.session.lock, self.db.lock: - actor = self.access.require('edit', 'measurements.import') - self.session.check_current() - table = MeasurementTable(raw) - blob = dict(sha256=table.sha256, bytes=len(raw)) - origin = self.session.summary['project_id'] - request = dict(blob=blob, source=copy.deepcopy(source)) - - def invoke(): - prior = self._documents().get(origin + '.' + table.sha256) - if prior is not None: - if prior['source'] != source: - raise WorkbenchError('This packet already has different retained capture facts.', 'conflict', 409) - return prior - self.artifacts.publish_bytes(raw, declaration(blob), maximum_bytes=MAX_BYTES) - return dict(format=FORMAT, origin_catalog_id=origin, id=table.sha256, - title=table.metadata()['title'], blob=blob, source=copy.deepcopy(source), - actor_id=actor.actor_id, imported_at=timestamp()) - - def capture(result, before): - return dict(records=[dict(family='project_artifact', id=table.sha256, document=declaration(blob)), - dict(family=FAMILY, id=origin + '.' + table.sha256, document=result)], result=result) - - return self.session.mutate('measurements.import', table.sha256, request, expected_checkpoint, key, invoke, capture) - - def sources(self, *, offset=0, limit=40): - if type(offset) is not int or not 0 <= offset <= 2**53-1 or type(limit) is not int or not 1 <= limit <= 40: - raise WorkbenchError('Invalid measurement source page.') - with self.access.lock, self.session.lock, self.db.lock: - self.access.require('inspect', 'measurements.sources') - self.session.check_current() - docs = sorted(self._documents().values(), key=lambda d: (d['origin_catalog_id'], d['id'])) - items = [dict(doc, availability=self.artifacts.inspect(declaration(doc['blob']))) - for doc in docs[offset:offset+limit]] - self.session.check_current() - self.access.require('inspect', 'measurements.sources') - return self._bounded(dict(items=items, total=len(docs), offset=offset, limit=limit)) - - @staticmethod - def _bounded(value): - if len(encode(value)) > MAX_RESPONSE_BYTES: - raise WorkbenchError('Measurement response exceeds its bound; select a smaller page.', 'too_large', 413) - return value - - def _read(self, origin_catalog_id, packet_sha256, action, select): - _identity(origin_catalog_id, ID) - _identity(packet_sha256, SHA) - target = origin_catalog_id + '.' + packet_sha256 - with self.access.lock, self.session.lock, self.db.lock: - self.access.require('inspect', action, target) - self.session.check_current() - doc = self._documents().get(target) - if doc is None: - raise WorkbenchError('Measurement source is unavailable.', 'not_found', 404) - raw = self.artifacts.read_blob(doc['blob'], maximum_bytes=MAX_BYTES) - table = MeasurementTable(raw) - if table.metadata()['title'] != doc['title']: - raise WorkbenchError('Measurement title differs from the exact retained packet.') - value = self._bounded(dict(source=doc, value=select(table))) - self.session.check_current() - self.access.require('inspect', action, target) - return value - - def metadata(self, origin_catalog_id, packet_sha256): - return self._read(origin_catalog_id, packet_sha256, 'measurements.metadata', lambda table: table.metadata()) - - def subjects(self, origin_catalog_id, packet_sha256, *, offset=0, limit=40): - return self._read(origin_catalog_id, packet_sha256, 'measurements.subjects', - lambda table: table.subjects(offset=offset, limit=limit)) - - def query(self, origin_catalog_id, packet_sha256, metric_id, **selection): - return self._read(origin_catalog_id, packet_sha256, 'measurements.query', - lambda table: table.query(metric_id, **selection)) - - def inspect(self, origin_catalog_id, packet_sha256, observation_id): - return self._read(origin_catalog_id, packet_sha256, 'measurements.inspect', - lambda table: table.inspect(observation_id)) - - def compare(self, sources, metric_id=None, **selection): - """Read one checkpoint's bounded group with every original source intact.""" - if type(sources) is not list or not 1 <= len(sources) <= MAX_COMPARISON_SOURCES: - raise WorkbenchError('Choose 1 through 16 native measurement sources.', 'too_large', 413) - targets = [] - for source in sources: - _closed(source, ('origin_catalog_id','packet_sha256')) - _identity(source['origin_catalog_id'], ID) - _identity(source['packet_sha256'], SHA) - targets.append(source['origin_catalog_id'] + '.' + source['packet_sha256']) - if len(set(targets)) != len(targets): - raise WorkbenchError('Native comparison repeats a measurement source.') - with self.access.lock, self.session.lock, self.db.lock: - for target in targets: - self.access.require('inspect', 'measurements.compare', target) - self.session.check_current() - documents = self._documents() - if any(target not in documents for target in targets): - raise WorkbenchError('A comparison source is unavailable.', 'not_found', 404) - chosen = [documents[target] for target in targets] - if sum(doc['blob']['bytes'] for doc in chosen) > MAX_COMPARISON_BYTES: - raise WorkbenchError('Native comparison exceeds 128 MiB of original packets.', 'too_large', 413) - tables = [] - for locator, doc in zip(sources, chosen): - raw = self.artifacts.read_blob(doc['blob'], maximum_bytes=MAX_BYTES) - table = MeasurementTable(raw) - if table.metadata()['title'] != doc['title']: - raise WorkbenchError('Comparison title differs from its original packet.') - tables.append((locator, table)) - value = MeasurementComparison(tables).read(metric_id, **selection) - result = self._bounded(dict(sources=chosen, value=value)) - self.session.check_current() - for target in targets: - self.access.require('inspect', 'measurements.compare', target) - return result diff --git a/project_native_execution.py b/project_native_execution.py deleted file mode 100644 index b2ff98ea..00000000 --- a/project_native_execution.py +++ /dev/null @@ -1,902 +0,0 @@ -"""Current native probe/train/verifier phases; retained phases are inert facts. - -Only an explicitly authorized preparation or an actual local Run continuation -may call the phase owner. Reading a checkpoint validates these documents and -their immutable evidence without preparing files, importing workers, or GO. -""" -import copy -from datetime import datetime -import hashlib -import os -from pathlib import Path -import stat -import sys -import time -import uuid - -import agent_api -import recipe_process -from pipeline import adapter_for_graph, adapter_identity_for_graph, decode_probe_observation, digest -from project_native_process import ENVIRONMENT, PHASES, WORKERS, prepare, validate_prepared_spec, validate_job_evidence -from project_session import REQUEST_KEY -from workbench import WorkbenchError, timestamp -from project_session import session_record, session_records - -FAMILY = 'native_execution_history' -FORMAT = 'native_execution_history_v1' -STATES = ('prepared', 'ready', 'go_intent', 'completed', 'failed', 'unknown') -FIELDS = {'format','origin_catalog_id','phase_id','phase','run_id','recipe', - 'request_key','request_sha256','actor_id','definition_identity','spec','events','payloads','observations','probe_result'} -OBSERVATIONS = {'job_template':('native-job-template.json',65536), - 'effective_job':('effective-job.json',65536),'parent_observation':('native-parent-observation.json',65536), - 'drain_receipt':('receipt.json',16384),'probe_stdout':('stdout.log',32768)} -PHASE_WALL_SECONDS = {'probe':45,'train':600,'verify':90} -PARENT_DRAIN_ALLOWANCE = 5 - - -def native_admission_wall_seconds(): - """New material's finite probe/train/verifier and custody time allowance. - - This budgets child/custodian phases, not a storage availability guarantee. - Cleanup already includes the custodian's TERM grace interval. - """ - overhead=recipe_process.READY_SECONDS+recipe_process.GO_WAIT_SECONDS+recipe_process.CLEANUP_SECONDS+PARENT_DRAIN_ALLOWANCE - return sum(PHASE_WALL_SECONDS.values())+len(PHASE_WALL_SECONDS)*overhead - - -def _fail(message, code='invalid'): - raise WorkbenchError(message, code, 409 if code != 'invalid' else 400) - - -def _id(value): - if type(value) is not str or recipe_process.ID.fullmatch(value) is None: - _fail('Invalid native execution identity.') - - -def _sha(value): - if type(value) is not str or recipe_process.HASH.fullmatch(value) is None: - _fail('Invalid native execution digest.') - - -def phase_reference(value): - event=value['events'][-1] - return dict(format='project_native_phase_v1',origin_catalog_id=value['origin_catalog_id'], - phase_id=value['phase_id'],phase=value['phase'],run_id=value['run_id'],state=event['state'], - spec_sha256=hashlib.sha256(recipe_process.encoded(value['spec'])).hexdigest(), - receipt_sha256=event['receipt_sha256']) - - -def classify_probe(recipe,raw): - """Process drainage and a valid native runtime observation are distinct.""" - result=dict(stdout=dict(sha256=hashlib.sha256(raw).hexdigest(),bytes=len(raw))) - if len(raw)>32768:return dict(result,outcome='too_large') - try:text=raw.decode('utf8') - except UnicodeError:return dict(result,outcome='invalid_utf8') - try:decode_probe_observation(recipe,recipe_process.decode(text)) - except (WorkbenchError,recipe_process.ProcessError):return dict(result,outcome='invalid_observation') - return dict(result,outcome='valid') - - -def decode_records(records, *, artifacts=None): - """Check exact finite phase/evidence closure, never local process state.""" - result={} - availability={} - declarations={r['id']:r['document'] for r in records if r['family']=='project_artifact'} - try: - for record in records: - if record['family']!=FAMILY:continue - value=record['document'] - if type(value) is not dict or set(value)!=FIELDS or value['format']!=FORMAT: - _fail('Invalid native phase document.') - for key in ('origin_catalog_id','phase_id','actor_id'):_id(value[key]) - if record['id']!=value['origin_catalog_id']+'.'+value['phase_id'] or record['id'] in result: - _fail('Native phase envelope identity differs.') - if value['phase'] not in PHASES or value['phase']!='probe' and value['run_id'] is None: - _fail('Native phase does not match its Run association.') - if value['run_id'] is not None:_id(value['run_id']) - if type(value['request_key']) is not str or REQUEST_KEY.fullmatch(value['request_key']) is None: - _fail('Invalid native phase request key.') - _sha(value['request_sha256']) - adapter_identity_for_graph(dict(recipe=value['recipe'])) - definition=value['definition_identity'] - if (type(definition) is not dict or set(definition)!={'definition_files','adapter_definition_sha256'} - or type(definition['definition_files']) is not dict or not definition['definition_files'] - or len(definition['definition_files'])>120 - or digest(definition['definition_files'])!=definition['adapter_definition_sha256']): - _fail('Native definition identity differs.') - for name,sha in definition['definition_files'].items(): - if (type(name) is not str or '/' in name or '\\' in name or not name.endswith('.py')): - _fail('Invalid native definition source name.') - _sha(sha) - worker=Path(adapter_for_graph(dict(recipe=value['recipe'])).__file__).name - spec=validate_prepared_spec(value['spec'],phase=value['phase'],worker=worker) - if (spec['attempt_id']!=value['phase_id'] or spec['request_sha256']!=value['request_sha256'] - or spec['env']!=ENVIRONMENT or spec.get('native_loader_policy')!='glibc_x86_64_no_preload_v1' - or spec['wall_seconds']!=PHASE_WALL_SECONDS[value['phase']] - or spec['max_output_bytes']!=64*1024*1024 or not 1<=len(spec['runtime_files'])<=3): - _fail('Native phase specification differs from its exact owner identity or environment.') - events=value['events'] - if type(events) is not list or not 1<=len(events)<=4: - _fail('Native phase has invalid bounded transitions.') - previous=None;helper=None - for index,event in enumerate(events): - if type(event) is not dict or set(event)!={'state','at','actor_id','helper','receipt_sha256'}: - _fail('Unclassified native phase event.') - _id(event['actor_id']) - state=event['state'] - allowed={'prepared':{'ready','failed','unknown'},'ready':{'go_intent','failed','unknown'}, - 'go_intent':{'completed','failed','unknown'}} - if (index==0 and state!='prepared' or index>0 and state not in allowed.get(previous,set())): - _fail('Invalid native phase transition.') - if type(event['at']) is not str or len(event['at'])>80 or datetime.fromisoformat(event['at']).utcoffset() is None: - _fail('Native phase requires an offset timestamp.') - if event['helper'] is not None: - if not recipe_process.valid_identity(event['helper']) or helper is not None and helper!=event['helper']: - _fail('Native phase helper identity changed.') - helper=event['helper'] - if state in ('ready','go_intent','completed') and event['helper'] is None: - _fail('Native phase lacks its actual READY helper observation.') - if event['receipt_sha256'] is not None: - _sha(event['receipt_sha256']) - if state not in ('completed','failed'):_fail('Native drainage proof precedes terminal observation.') - if state=='completed' and event['receipt_sha256'] is None: - _fail('Native completed phase requires its exact drainage proof.') - previous=state - payloads=value['payloads'] - if type(payloads) is not list or len(payloads)>180:_fail('Native payload inventory exceeds its bound.') - runs=[];output_names=set() - if value['run_id'] is not None: - runs=[r['document']['run'] for r in records if r['family']=='run_history' - and r['id']==value['origin_catalog_id']+'.'+value['run_id']] - if len(runs)!=1:_fail('Native phase lacks its exact retained Run.') - from runs import native_payload_names - output_names={'output/'+name for name in native_payload_names(runs[0])|{'artifact-manifest.json'}} - names=set();byname={} - for edge in payloads: - if (type(edge) is not dict or set(edge)!={'name','blob','role','preservation','required_for'} - or edge['role'] not in ('execution_source','execution_spec','custody_proof','measured_job','measured_stream','measured_output') - or edge['preservation']!='unique' or edge['required_for']!=['execution_proof'] - or type(edge['name']) is not str or edge['name'] in names): - _fail('Invalid native phase evidence edge.') - name=edge['name'];names.add(name);blob=edge['blob'] - if (name not in ('spec.json','native-job-template.json','effective-job.json','native-parent-observation.json', - 'stdout.log','stderr.log','receipt.json') and - not (name.startswith('source/') and name[7:] in {*definition['definition_files'],'native_process_bootstrap.py'}) - and name not in output_names): - _fail('Unsupported native phase evidence path.') - role=('execution_source' if name.startswith('source/') else 'measured_output' if name.startswith('output/') - else 'execution_spec' if name in ('spec.json','native-job-template.json') - else 'measured_stream' if name in ('stdout.log','stderr.log') - else 'custody_proof' if name=='receipt.json' else 'measured_job') - if edge['role']!=role:_fail('Native evidence edge has a different finite role.') - if type(blob) is not dict or set(blob)!={'sha256','bytes'}:_fail('Invalid native evidence blob.') - _sha(blob['sha256']) - if type(blob['bytes']) is not int or not 0<=blob['bytes']<=64*1024*1024: - _fail('Native evidence exceeds its owner bound.') - if declarations.get(blob['sha256'])!=dict(format='project_artifact_v1',**blob): - _fail('Native evidence declaration is missing or differs.') - byname[name]=blob - if artifacts is not None and blob['sha256'] not in availability: - observed=artifacts.status(dict(format='project_artifact_v1',**blob)) - if observed['state']=='corrupt':_fail('Present native evidence differs from its declared bytes.') - availability[blob['sha256']]=observed['state']=='verified' - observations=value['observations'] - if type(observations) is not dict or set(observations)!=set(OBSERVATIONS): - _fail('Native phase has unclassified canonical observations.') - proofs={} - for key,(name,maximum) in OBSERVATIONS.items(): - text=observations[key] - if text is not None: - if type(text) is not str:_fail('Native proof must retain its exact UTF8 observation.') - raw=text.encode('utf8') - if len(raw)>maximum or byname.get(name)!=dict(sha256=hashlib.sha256(raw).hexdigest(),bytes=len(raw)): - _fail('Canonical native observation differs from its exact evidence edge.') - proofs[key]=raw - spec_raw=recipe_process.encoded(spec) - if byname.get('spec.json')!=dict(sha256=hashlib.sha256(spec_raw).hexdigest(),bytes=len(spec_raw)): - _fail('Native phase lacks its exact prepared specification.') - for name,sha in definition['definition_files'].items(): - if byname.get('source/'+name,{}).get('sha256')!=sha: - _fail('Native phase lacks exact qualified source bytes.') - captures={str(Path(item['path']).relative_to(spec['cwd'])):dict(sha256=item['sha256'],bytes=item['bytes']) - for item in spec['captured_files']} - if set(captures)!={'source/'+name for name in definition['definition_files']}|( - {'source/native_process_bootstrap.py','native-job-template.json'} if value['phase']!='probe' else set()): - _fail('Native phase capture inventory differs from its finite definition closure.') - for name,blob in captures.items(): - if byname.get(name)!=blob:_fail('Native phase lacks exact immutable capture evidence.') - if value['run_id'] is not None: - if (len(runs)!=1 or runs[0]['graph']['recipe']!=value['recipe'] - or runs[0]['runtime']['definition_files']!=definition['definition_files']): - _fail('Native phase differs from its retained Run and exact adapter.') - if (value['phase']=='probe')!=(observations['job_template'] is None): - _fail('Native job template observation differs from its phase.') - if value['phase']!='probe' and observations['probe_stdout'] is not None: - _fail('Training/verifier logs are not probe runtime observations.') - if (observations['effective_job'] is None)!=(observations['parent_observation'] is None): - _fail('Native measured parent/job observations must be retained together.') - if value['phase']!='probe': - template=recipe_process.decode(proofs['job_template']) - if (type(template) is not dict or set(template)!={'format','phase','worker','attempt_id','request_sha256','job'} - or template['format']!='native_parent_binding_v1' or template['phase']!=value['phase'] - or template['worker']!=worker or template['attempt_id']!=value['phase_id'] - or template['request_sha256']!=value['request_sha256']): - _fail('Native job template differs from its exact phase.') - job=adapter_for_graph(dict(recipe=value['recipe']))._checked_job(template['job']) - run=runs[0] - from pipeline import model_aware_graph - import image_training - expected_job=dict(schema_version=1,dataset_id=run['dataset_id'],run_id=run['id'], - graph_sha256=run['graph_sha256'],release_id=run['release_id'],release_sha256=run['release_sha256'], - release_path=job['release_path'],output_dir=spec['output_dir'],parameters=run['parameters'],parent_pid=1) - if value['recipe']==image_training.MODEL_RECIPE: - expected_job.update(schema_version=2,evidence_context=run['evidence_context']) - elif model_aware_graph(run['graph']): - from one_fit_evidence import job_for_run - expected_job=job_for_run(run,spec['output_dir']) - # Historical Run projection deliberately carries no live - # release path. Its absolute template observation is inert; - # scientific release identity and all evidence selections - # remain exact projections of the retained Run owner. - expected_job['release_path']=job['release_path'] - if (agent_api.encoded(job)!=agent_api.encoded(template['job']) - or agent_api.encoded(job)!=agent_api.encoded(expected_job)): - _fail('Native job template differs from its exact scientific Run inputs.') - receipt_sha=events[-1]['receipt_sha256'] - if (receipt_sha is None)!=(observations['drain_receipt'] is None): - _fail('Native terminal receipt observation differs from its acknowledged phase.') - if receipt_sha is not None: - if byname.get('receipt.json',{}).get('sha256')!=receipt_sha: - _fail('Native terminal observation differs from its retained receipt.') - if observations['drain_receipt'] is not None: - raw=proofs['drain_receipt'] - expected=dict(attempt_id=value['phase_id'],request_sha256=value['request_sha256'], - spec_sha256=hashlib.sha256(spec_raw).hexdigest(),helper=helper) - receipt=recipe_process.validate_receipt(raw,expected) - validate_job_evidence(spec,phase=value['phase'],helper=helper, - template=proofs.get('job_template'),effective_job=proofs.get('effective_job'), - parent_observation=proofs.get('parent_observation'),receipt=receipt) - if not receipt['drained'] or (previous=='completed')!=(receipt['outcome']=='completed'): - _fail('Native terminal state differs from measured drainage.') - for stream in ('stdout','stderr'): - if byname.get(stream+'.log')!=receipt['streams'][stream]: - _fail('Native measured stream differs from its exact receipt.') - if value['phase']=='probe': - classified=value['probe_result'] - if (type(classified) is not dict or set(classified)!={'outcome','stdout'} - or classified['outcome'] not in ('valid','invalid_utf8','invalid_observation','too_large') - or classified['stdout']!=byname.get('stdout.log')): - _fail('Native probe protocol observation differs from measured stdout.') - if observations['probe_stdout'] is not None: - if classify_probe(value['recipe'],proofs['probe_stdout'])!=classified: - _fail('Canonical native probe classification differs from exact stdout.') - elif classified['outcome'] not in ('invalid_utf8','too_large'): - _fail('A bounded UTF8 native probe requires its exact canonical stdout.') - if (classified['outcome']=='too_large')!=(classified['stdout']['bytes']>32768): - _fail('Native oversized probe observation has a different bound.') - if artifacts is not None and availability.get(classified['stdout']['sha256']): - actual=artifacts.read_blob(classified['stdout'],maximum_bytes=recipe_process.STREAM_LIMIT) - if classify_probe(value['recipe'],actual)!=classified: - _fail('Present native probe bytes differ from the classified observation.') - elif value['probe_result'] is not None: - _fail('Native probe protocol result precedes its measured terminal receipt.') - if value['phase']!='probe' and value['probe_result'] is not None: - _fail('Only a probe phase may classify a runtime response.') - result[record['id']]=copy.deepcopy(value) - return result - except WorkbenchError:raise - except (ValueError,TypeError,KeyError,AttributeError,OverflowError,RecursionError): - _fail('Malformed retained native execution phase.') - - -class _RunAuthority: - """One actual current SQL admission, never constructed from a checkpoint.""" - def __init__(self,native,run_id): - self.native=native;self.run_id=run_id - self.recipe=native.execution.runs._load(run_id)['graph']['recipe'] - - def authorize_probe(self,recipe): - execution=self.native.execution;owner=execution.runs - with execution.db.lock: - run=owner._load(self.run_id);execution._proof(run) - context=execution.runtime_access.require_job('runs',run['id'],run['admission_id'],run['request_sha256']) - execution.runtime_access.require('edit','runs.update',run['id']) - execution.runtime_access.require('execute','pipeline.probe_native',recipe) - if recipe!=self.recipe or run['state'] not in ('queued','running','cancelling'): - _fail('Current native Run cannot observe this phase.','unavailable') - inputs=self.native._run_inputs.get(run['id']) - if inputs is None:_fail('A retained native Run has no current one-use qualification.','unavailable') - if (os.environ.get('TULDOK_TRAINING_PYTHON') or sys.executable)!=inputs['runtime']['executable']: - _fail('Configured native interpreter changed after admission.','stale') - from project_native_process import current_runtime - if current_runtime(inputs['runtime']['executable'])!=inputs['runtime']: - _fail('Current native interpreter changed after admission.','stale') - if owner.pipelines.definition_identity(recipe)!=inputs['definition_identity']: - _fail('Native adapter changed after admission.','stale') - return context - - def dispatch_allowed(self): - owner=self.native.execution.runs;run=owner._load(self.run_id) - if run['state'] not in ('queued','running') or owner._stop.is_set() or owner._blocked: - _fail('Current native Run no longer permits dispatch.','unavailable') - - -class _ReconciliationAuthority: - def __init__(self,native,recipe):self.native=native;self.recipe=recipe - def authorize_probe(self,recipe): - if recipe!=self.recipe:_fail('Native reconciliation phase changed.','conflict') - return self.native.access.require('cancel','native_execution.reconcile',owner_only=True) - - -class ProjectNativeExecution: - """The fixed current phase owner; construction is entirely inert.""" - def __init__(self, execution): - self.execution=execution;self.projection=execution.projection - self.session=execution.session;self.db=execution.db;self.access=execution.runtime_access - self._dirty={};self._handles={};self._prepared={};self._contexts={};self._active=set();self._run_inputs={} - self._never_launched=set() - self._foreground_phase=None - - @property - def has_dirty(self):return bool(self._dirty) - - @property - def has_local_custody(self): - return bool(self._active or self._handles) - - def capture_dirty(self, before_records): - records=[] - for phase_id,document in self._dirty.items(): - self._authorize(phase_id) - records.append(dict(family=FAMILY,id=document['origin_catalog_id']+'.'+phase_id,document=copy.deepcopy(document))) - records.extend(dict(family='project_artifact',id=edge['blob']['sha256'], - document=dict(format='project_artifact_v1',**edge['blob'])) for edge in document['payloads']) - return records - - def outcome(self, outcome): - if outcome not in ('committed','rolled_back','unknown'):raise ValueError('Invalid native SQL outcome.') - self._dirty.clear() - if outcome=='unknown' or not self.session.available: - for handle in self._handles.values():handle.close_control(wait=False) - - def abandon_pending(self): - if not self.execution._reconstructing:raise RuntimeError('Native pending capture clears only during guarded reconstruction.') - self._dirty.clear() - - def _authorize(self, phase_id): - context=self._contexts.get(phase_id) - if context is None:_fail('Native phase has no actual current preparation context.','unavailable') - return context.authorize_probe(context.recipe) - - def authorize_dirty(self): - for phase_id in self._dirty:self._authorize(phase_id) - - def _dispatch_authorized(self,phase_id): - actor=self._authorize(phase_id) - context=self._contexts[phase_id] - if isinstance(context,_RunAuthority):context.dispatch_allowed() - return actor - - def _retain(self, document, name, raw, role): - declaration=dict(format='project_artifact_v1',sha256=hashlib.sha256(raw).hexdigest(),bytes=len(raw)) - self.session.artifacts.publish_bytes(raw,declaration,maximum_bytes=64*1024*1024) - document['payloads'].append(dict(name=name,blob={k:declaration[k] for k in ('sha256','bytes')}, - role=role,preservation='unique',required_for=['execution_proof'])) - for key,(filename,maximum) in OBSERVATIONS.items(): - if name==filename and (key!='probe_stdout' or document['phase']=='probe'): - if key=='probe_stdout': - document['probe_result']=classify_probe(document['recipe'],raw) - try:text=raw.decode('utf8') if len(raw)<=maximum else None - except UnicodeError:text=None - document['observations'][key]=text - else: - if len(raw)>maximum:_fail('Native canonical observation exceeds its fixed bound.') - document['observations'][key]=raw.decode('utf8') - - def _retain_outputs(self,document,*,run=None,output=None): - """Preserve measured native outputs without claiming their validity.""" - if document['phase']=='probe':return - from runs import native_payload_names - run=run if run is not None else self.execution.runs._load(document['run_id']) - allowed=native_payload_names(run)|{'artifact-manifest.json'} - # A saved pathname is an observation, never a directory capability. - # Select only this physical projection's exact phase stage, including - # the earlier training stage explicitly associated with a verifier. - from project_store import DIR_FLAGS, FILE_FLAGS, ProjectStoreError, _open_directory_path, anchored_directory - stage_id=document['phase_id'] - if document['phase']=='verify': - matches=[row['document'] for row in session_records(self.session, FAMILY) - if row['family']==FAMILY and row['document']['phase']=='train' - and row['document']['origin_catalog_id']==self.db.dataset_id - and row['document']['run_id']==document['run_id']] - if len(matches)!=1:_fail('Native verifier lacks its exact training stage.','unknown') - stage_id=matches[0]['phase_id'] - _id(stage_id) - relative='project-native-phases/'+stage_id+'/output' - expected=self.db.path/relative - if document['spec']['output_dir']!=str(expected) or output is not None and Path(output)!=expected: - _fail('Native measured output is not its original local stage.','unknown') - root=None;captured=[];total=0 - def identity(info): - return info.st_dev,info.st_ino,info.st_size,info.st_mtime_ns,info.st_ctime_ns - try: - root_path,root=_open_directory_path(self.db.path) - with anchored_directory(root,relative,root_path=root_path) as directory: - before=os.fstat(directory);names=sorted(os.listdir(directory)) - for name in names: - if name not in allowed:_fail('Native worker produced an unclassified output; retain local custody.','unknown') - descriptor=os.open(name,FILE_FLAGS,dir_fd=directory) - try: - info=os.fstat(descriptor) - if not stat.S_ISREG(info.st_mode) or info.st_size>document['spec']['max_output_bytes']: - _fail('Native output is not an admitted bounded regular file.','unknown') - chunks=[];remaining=document['spec']['max_output_bytes']-total+1 - while remaining: - chunk=os.read(descriptor,min(remaining,65536)) - if not chunk:break - chunks.append(chunk);remaining-=len(chunk) - raw=b''.join(chunks);total+=len(raw) - if (total>document['spec']['max_output_bytes'] or identity(info)!=identity(os.fstat(descriptor)) - or identity(info)!=identity(os.stat(name,dir_fd=directory,follow_symlinks=False))): - _fail('Native output changed during its measured observation.','unknown') - captured.append((name,raw)) - finally:os.close(descriptor) - if identity(before)!=identity(os.fstat(directory)) or names!=sorted(os.listdir(directory)): - _fail('Native output directory changed during observation.','unknown') - # The anchored context rechecks the complete directory binding - # before any bytes receive canonical measured-output attribution. - for name,raw in captured:self._retain(document,'output/'+name,raw,'measured_output') - except (OSError,ProjectStoreError) as error: - raise WorkbenchError('Native output stage is unavailable or changed; retain local custody.','unknown',409) from error - finally: - if root is not None:os.close(root) - - def _publish(self, document, state, *, helper=None, receipt_sha256=None): - with self.db.lock,self.db.transaction(): - self.session.check_current();actor=self._authorize(document['phase_id']) - document['events'].append(dict(state=state,at=timestamp(),actor_id=actor.actor_id, - helper=copy.deepcopy(helper),receipt_sha256=receipt_sha256)) - self._dirty[document['phase_id']]=copy.deepcopy(document) - if state!='prepared' and self.execution.custody is not None: - with self.execution._journal_guard():self.execution.custody.native_observed(document) - - def assert_quiescent(self): - if self.has_local_custody:_fail('Current native phase custody requires explicit drainage.','busy') - - def reconcile(self,phase_id,expected_checkpoint): - """Observe exact original-host drainage; never prepare, import or GO.""" - import json - from project_native_process import read_phase_evidence - _id(phase_id);_sha(expected_checkpoint) - self.access.require('cancel','native_execution.reconcile',phase_id,owner_only=True) - if self.db.lock.owned_by_current_thread or self.db.in_transaction: - _fail('Native custody reconciliation must drain outside command locks.','busy') - execution=self.execution;journal=execution.custody - if journal is None:_fail('There is no original local native custody.','unavailable') - with self.db.lock: - if self.session.summary['checkpoint']!=expected_checkpoint:_fail('Expected native recovery checkpoint changed.','stale_project') - local=journal.refresh() - selected=next((row for row in local.get('native_phases',[]) if row['phase_id']==phase_id),None) - if selected is None:_fail('A retained phase alone cannot select current native custody.','unavailable') - if (local['runs'] or local['producers'] or local['runtime_effects'] or local['package_effects'] - or any(row['run_id']!=selected['run_id'] for row in local.get('native_admissions',[])) - or execution._runtime_active or execution._package_active): - _fail('Other current effect owners must reconcile first.','busy') - entries=[row for row in local['native_phases'] - if row['phase_id']==phase_id or selected['run_id'] is not None and row['run_id']==selected['run_id']] - if len(entries)!=len(local['native_phases']):_fail('Other native custody remains unresolved.','busy') - if not self.db.claim_runtime('project_native_phases'):_fail('The original native application is still active.','busy') - other=self.db.execute("SELECT id FROM workspace_runs WHERE document::jsonb->>'state' IN ('queued','running','cancelling','unknown') AND id<>%s", - (selected['run_id'] or '',)).fetchall() - if other:_fail('Another current Run must drain before native recovery.','busy') - owner=execution._runs - if owner is not None:owner._fence_coordinator() - for entry in entries: - handle=self._handles.get(entry['phase_id']) - if handle is not None: - receipt=handle.close_control() - if not receipt or not receipt.get('drained'):_fail('Actual native helper has not drained.','unknown') - if owner is not None and owner._thread is not None: - owner._thread.join(60) - if owner._thread.is_alive():_fail('Current native supervisor has not drained.','busy') - if self._active:_fail('Current native owner has not finished its bounded observation.','busy') - with execution.access.lock,self.session.lock,self.db.lock: - self.access.require('cancel','native_execution.reconcile',phase_id,owner_only=True) - if self.session.summary['checkpoint']!=expected_checkpoint:_fail('Native checkpoint changed while draining.','stale_project') - if journal.refresh()!=local:_fail('Original native custody changed while draining.','stale_project') - binding=journal.binding - if (binding['project_id']!=self.db.dataset_id or binding['projection_id']!=self.db.projection_id - or binding['host_catalog_id']!=execution.access.catalog_id): - _fail('Native custody belongs to another physical owner.','local_custody_unavailable') - self.session.available=False - snapshot=self.session.store.recover_checkpoint();journal.validate_selection(snapshot) - with self.session.store.root_directory() as descriptor: - info=os.fstat(descriptor) - if [info.st_dev,info.st_ino]!=binding['root_identity']: - _fail('Native custody belongs to another physical project root.','local_custody_unavailable') - documents=decode_records(snapshot['records'],artifacts=self.session.artifacts) - phases=[];local_run=None;retained_run=None - if selected['run_id'] is not None: - if owner is None and not self.db.claim_runtime('workspace_runs'): - _fail('The original Run application still owns this projection.','busy') - row=self.db.execute('SELECT document FROM workspace_runs WHERE id=%s',(selected['run_id'],)).fetchone() - if row is None:_fail('Native custody has no original local Run admission.','local_custody_unavailable') - local_run=json.loads(row['document']);execution._proof(local_run) - retained_run=next((row['document']['run'] for row in snapshot['records'] if row['family']=='run_history' - and row['id']==self.db.dataset_id+'.'+selected['run_id']),None) - immutable=('id','dataset_id','request_key','request_sha256','admission_id','graph_sha256','release_sha256','runtime') - if retained_run is None or any(local_run.get(key)!=retained_run.get(key) for key in immutable): - _fail('Original native Run admission differs from retained science.','local_custody_unavailable') - for entry in entries: - document=copy.deepcopy(documents.get(self.db.dataset_id+'.'+entry['phase_id'])) - stage=self.db.path/'project-native-phases'/entry['phase_id'] - if (document is None or document['run_id']!=entry['run_id'] or document['phase']!=entry['phase'] - or document['request_sha256']!=entry['request_sha256'] or document['spec']['cwd']!=str(stage) - or hashlib.sha256(recipe_process.encoded(document['spec'])).hexdigest()!=entry['spec_sha256']): - _fail('Original native phase differs from its exact physical journal.','local_custody_unavailable') - if entry['helper'] is None: - # A prepared journal has not acknowledged launch intent. - # After intent, only this process's retained call boundary - # proves Popen was never entered; a restarted owner cannot - # convert that ambiguous spawn window into cessation. - if entry['state']!='prepared' and not (entry['state']=='launch_intent' and entry['phase_id'] in self._never_launched): - _fail('Original native launch lacks an exact helper drainage identity.','unknown') - evidence=None - else:evidence=read_phase_evidence(stage,document['spec'],phase=entry['phase'],helper=entry['helper']) - phases.append((entry,document,evidence)) - # Fixed cache reconstruction happens only after every actual/local - # effect has a complete drain receipt. It restores no Run or grant. - self.projection.reconcile_inert(snapshot) - try: - for entry,document,evidence in phases: - identity=entry['phase_id'];self._contexts[identity]=_ReconciliationAuthority(self,document['recipe']) - if evidence is None: - if document['events'][-1]['state']!='failed':self._publish(document,'failed') - elif entry['state']!='failed': - with execution._journal_guard():journal.native_observed(document) - with execution._journal_guard():journal.native_not_launched(identity) - self._never_launched.discard(identity) - continue - names={edge['name'] for edge in document['payloads']} - for name,raw,role in (('stdout.log',evidence['stdout'],'measured_stream'), - ('stderr.log',evidence['stderr'],'measured_stream'), - ('receipt.json',recipe_process.encoded(evidence['receipt']),'custody_proof'), - ('effective-job.json',evidence['effective_job'],'measured_job'), - ('native-parent-observation.json',evidence['parent_observation'],'measured_job')): - if raw is not None and name not in names:self._retain(document,name,raw,role) - if document['phase']!='probe' and not any(name.startswith('output/') for name in names): - output=stage/'output' - if document['phase']=='verify': - train=next((value for value in documents.values() if value['run_id']==document['run_id'] - and value['phase']=='train'),None) - if train is None:_fail('Original verifier has no exact retained training phase.','unknown') - output=self.db.path/'project-native-phases'/train['phase_id']/'output' - if document['spec']['output_dir']!=str(output):_fail('Native output path differs from original local custody.','unknown') - if output.exists():self._retain_outputs(document,run=retained_run,output=output) - receipt_sha=hashlib.sha256(recipe_process.encoded(evidence['receipt'])).hexdigest() - if document['events'][-1]['state'] not in ('completed','failed'): - state='completed' if evidence['receipt']['outcome']=='completed' else 'failed' - self._publish(document,state,helper=entry['helper'],receipt_sha256=receipt_sha) - elif document['events'][-1]['receipt_sha256']!=receipt_sha: - _fail('Original native terminal receipt changed.','unknown') - elif entry['state'] not in ('completed','failed'): - with execution._journal_guard():journal.native_observed(document) - self._handles.pop(identity,None) - if retained_run is not None: - current=copy.deepcopy(retained_run) - from runs import LOCAL_RUN_FIELDS - current.update({key:copy.deepcopy(value) for key,value in local_run.items() if key in LOCAL_RUN_FIELDS}) - owner=execution._local_owner(recover=False) if owner is None else owner - owner._fence_coordinator() - with self.db.transaction(): - execution._proof(current) - state='completed' if current['state']=='completed' else 'interrupted' - owner._event(current,state,'Original native custody drained; no phase was resumed or regenerated.') - owner._save(current) - elif evidence is not None: - journal.native_confirmed(phase_id) - journal.acknowledge(self.session.snapshot) - return phase_reference(next(document for entry,document,evidence in phases if entry['phase_id']==phase_id)) - except BaseException: - self.session.available=False - if owner is not None:owner._fence_coordinator() - raise - - def settle_run(self,run): - if self.execution.custody is None or run['state'] not in ('completed','failed','cancelled','interrupted'):return - for entry in self.execution.custody.snapshot().get('native_phases',[]): - if entry['run_id']==run['id'] and entry['state'] in ('completed','failed') and entry['receipt_sha256'] is not None: - self.execution.custody.native_confirmed(entry['phase_id']) - - def bind_run(self,run): - """Retain a private measured qualification only during actual admission.""" - if not self.db.in_transaction:_fail('Native qualification binds only inside its admission transaction.') - if self.execution.runs._validation_run(run):return - context=self.projection.native_preparation.current(self.execution.runs.pipelines) - _actor,inputs=self._inputs(run['graph']['recipe'],context) - if (run['runtime']['definition_files']!=inputs['definition_identity']['definition_files'] - or run['runtime']['adapter_definition_sha256']!=inputs['definition_identity']['adapter_definition_sha256']): - _fail('Native Run differs from its qualified adapter.','stale') - if run['id'] in self._run_inputs:_fail('A native Run qualification cannot be replaced.','conflict') - self._run_inputs[run['id']]=copy.deepcopy(inputs) - self.db.on_rollback(lambda:self._run_inputs.pop(run['id'],None)) - - def probe_current_run(self,owner,recipe): - from access import current_context - context=current_context() - if (context is None or context.mode!='job' or context.kind!='runs' - or context.catalog_id!=self.db.dataset_id or owner.db is not self.db): - _fail('Native runtime probing requires its exact current local Run.','unavailable') - authority=_RunAuthority(self,context.job_id);actor=authority.authorize_probe(recipe) - inputs=self._run_inputs[context.job_id] - result=self._run_phase('probe',recipe,'native-run-probe-'+context.job_id,actor,inputs,authority,run_id=context.job_id) - return dict(runtime=self._probe_result(recipe,inputs,result['evidence']),phase=phase_reference(result['document'])) - - def capture_run_payloads(self,run,artifacts): - """Copy a newly admitted frozen native input, then reuse exact custody.""" - from projects import Projects - prior=session_record(self.session, 'run_history',run['dataset_id']+'.'+run['id']) - prior=None if prior is None else prior['document'] - if prior is not None: - retained=[copy.deepcopy(edge) for edge in prior['payloads'] - if edge['name']=='release.zip' or edge['name'].startswith('source/')] - expected={'release.zip':run['release_sha256'], - **{'source/'+name:sha for name,sha in run['runtime']['definition_files'].items()}} - if {edge['name']:edge['blob']['sha256'] for edge in retained}!=expected: - _fail('Native Run input/source custody is incomplete.','unavailable') - for edge in retained: - with artifacts.open_verified(dict(format='project_artifact_v1',**edge['blob'])):pass - return retained - if run['state']!='queued':_fail('Only an actual newly admitted native Run may capture inputs.','unavailable') - edges=[] - release=Path(run['release_path']) - reader=Projects(self.execution.runs.dataset,{'native_release':release.parent}) - try: - declaration=dict(format='project_artifact_v1',sha256=run['release_sha256'],bytes=run['release_bytes']) - with reader._file('native_release',release.name) as (descriptor,_info):artifacts.publish_fd(descriptor,declaration) - edges.append(dict(name='release.zip',blob={key:declaration[key] for key in ('sha256','bytes')}, - population='unknown',role='captured_input',preservation='unique',required_for=['scientific_inspection','execution_proof'])) - finally:reader.close() - inputs=self._run_inputs.get(run['id']) - if self.execution.runs._validation_run(run): - sources={name:(self.execution.runs.pipelines.source_path/name).read_bytes() - for name in run['runtime']['definition_files']} - elif inputs is None:_fail('Native input capture has no current qualification.','unavailable') - else:sources=inputs['sources'] - for name,raw in sorted(sources.items()): - if hashlib.sha256(raw).hexdigest()!=run['runtime']['definition_files'][name]: - _fail('Native source changed before canonical admission.','stale') - declaration=dict(format='project_artifact_v1',sha256=hashlib.sha256(raw).hexdigest(),bytes=len(raw)) - artifacts.publish_bytes(raw,declaration) - edges.append(dict(name='source/'+name,blob={key:declaration[key] for key in ('sha256','bytes')}, - population='unknown',role='execution_source',preservation='unique',required_for=['scientific_inspection','execution_proof'])) - return edges - - def execute_run(self,run_id): - """Run the existing CPU owners through three fixed custody phases.""" - from pipeline import model_aware_graph - from types import SimpleNamespace - from runs import _sync - owner=self.execution.runs - with self.db.lock,self.db.transaction(): - run=owner._load(run_id) - self.access.require_job('runs',run_id,run['admission_id'],run['request_sha256']) - if run['state']!='queued' or owner._stop.is_set() or owner._blocked:return - owner._event(run,'running','Verifying exact frozen native inputs before current CPU phases.') - run['started_at']=timestamp();run['progress']['stage']='validate';owner._save(run) - try: - if owner._validation_run(run):return owner._execute_validation(run) - runtime=owner.pipelines.probe(run['graph']['recipe']) - if not runtime['available'] or runtime!=run['runtime']:_fail('Native runtime changed after admission.','stale') - release=owner.pipelines.inspect_release(run['release_id'],private=True,recipe=run['graph']['recipe']) - if release['sha256']!=run['release_sha256']:_fail('Native frozen release changed after admission.','stale') - authority=_RunAuthority(self,run_id);actor=authority.authorize_probe(run['graph']['recipe']) - phase_id=uuid.uuid4().hex;output=self.db.path/'project-native-phases'/phase_id/'output' - job=dict(schema_version=1,dataset_id=run['dataset_id'],run_id=run_id,graph_sha256=run['graph_sha256'], - release_id=run['release_id'],release_sha256=run['release_sha256'],release_path=release['path'], - output_dir=str(output),parameters=run['parameters'],parent_pid=1) - if run['graph']['recipe']=='image_classification_model_v2': - job.update(schema_version=2,evidence_context=run['evidence_context']) - elif model_aware_graph(run['graph']): - from one_fit_evidence import job_for_run - job.update(job_for_run(run,output),parent_pid=1,release_path=release['path']) - with self.db.lock,self.db.transaction(): - current=owner._load(run_id);current['progress']['stage']='train' - current['execution_test_exposure']=owner.pipelines.exposures(current['source_records']) - for node in current['node_attempts']: - node['state']='completed' if node['type'] in ('release','validate') else 'running' if node['type']=='train' else 'pending' - owner._save(current) - trained=self._run_phase('train',run['graph']['recipe'],'native-train-'+run_id,actor, - self._run_inputs[run_id],authority,run_id=run_id,job=job,phase_id=phase_id) - if trained['evidence']['receipt']['outcome']!='completed': - state='cancelled' if trained['evidence']['receipt']['outcome']=='cancelled' else 'failed' - return owner._finish(run_id,state,'Native trainer drained without publishing results.') - with (trained['prepared'].stage/'custody/stdout.log').open('rb') as stream: - owner._read_progress(SimpleNamespace(stdout=stream),run,dict(buffer=b'',bytes=0,epoch=0)) - artifacts,metrics=owner._verify_directory(run,output) - if model_aware_graph(run['graph']): - verified=self._run_phase('verify',run['graph']['recipe'],'native-verify-'+run_id,actor, - self._run_inputs[run_id],authority,run_id=run_id,job=job) - if verified['evidence']['receipt']['outcome']!='completed': - state='cancelled' if verified['evidence']['receipt']['outcome']=='cancelled' else 'failed' - return owner._finish(run_id,state,'Independent checkpoint verification drained without accepting outputs.') - for path in output.iterdir(): - with path.open('rb') as source:os.fsync(source.fileno()) - _sync(output) - with self.db.lock,self.db.transaction(): - current=owner._load(run_id) - if current['state']=='cancelling' or owner._stop.is_set(): - owner._event(current,'cancelled','Native workers drained before final publication.');owner._save(current);return - os.rename(output,owner.path/run_id);_sync(owner.path) - current['artifacts']=artifacts;current['metrics']=metrics - for node in current['node_attempts']:node['state']='completed' - owner._event(current,'completed','Measured native CPU outputs and independent evidence published after custody drainage.') - owner._save(current) - except (WorkbenchError,recipe_process.ProcessError) as error: - state='unknown' if error.code in ('unknown','outcome_unknown') else 'failed' - owner._finish(run_id,state,str(error),error.code) - - def _inputs(self, recipe, preparation): - from project_native_preparation import NativePreparationContext - if type(preparation) is not NativePreparationContext or preparation.recipe!=recipe: - _fail('Native probing requires its actual current preparation context.','unavailable') - actor=preparation.authorize_probe(recipe) - inputs=preparation.native_inputs(recipe) - if type(inputs) is not dict or set(inputs)!={'runtime','worker','sources','model_aware','definition_identity'}: - _fail('Native preparation supplied unclassified phase inputs.') - if inputs['worker'] not in WORKERS or type(inputs['model_aware']) is not bool: - _fail('Native preparation supplied an unsupported adapter.') - definition=inputs['definition_identity'] - if (type(definition) is not dict or set(definition)!={'definition_files','adapter_definition_sha256'} - or type(inputs['sources']) is not dict or set(inputs['sources'])!=set(definition['definition_files']) - or digest(definition['definition_files'])!=definition['adapter_definition_sha256'] - or any(type(raw) is not bytes or hashlib.sha256(raw).hexdigest()!=definition['definition_files'][name] - for name,raw in inputs['sources'].items())): - _fail('Native measured sources differ from their exact definition.','stale') - return actor,inputs - - def probe(self, recipe, *, expected_checkpoint, request_key, preparation): - """Explicitly measure a native runtime behind canonical launch/GO ACKs.""" - if self.db.in_transaction: - _fail('Native probing must precede the foreground admission transaction.','busy') - if type(request_key) is not str or REQUEST_KEY.fullmatch(request_key) is None: - _fail('Invalid native probe request key.') - with self.db.lock: - current=self.session.check() - if current['checkpoint']!=expected_checkpoint:_fail('Native preparation checkpoint changed.','stale_project') - actor,inputs=self._inputs(recipe,preparation) - prior=[value for value in decode_records(current['records']).values() - if value['origin_catalog_id']==self.session.project_id and value['request_key']==request_key] - if prior: - _fail('A previous native probe is historical; start a fresh explicit preparation.','unavailable') - result=self._run_phase('probe',recipe,request_key,actor,inputs,preparation) - return dict(runtime=self._probe_result(recipe,inputs,result['evidence']),phase=phase_reference(result['document'])) - - @staticmethod - def _probe_result(recipe, inputs, evidence): - receipt=evidence['receipt'] - if not receipt['go_received'] or receipt['outcome'] not in ('completed','failed'): - _fail('The native runtime probe did not produce an acknowledged observation.','unavailable') - if classify_probe(recipe,evidence['stdout'])['outcome']!='valid': - _fail('The native runtime probe returned an invalid bounded observation.','unavailable') - try:probe=decode_probe_observation(recipe,recipe_process.decode(evidence['stdout'])) - except (WorkbenchError,recipe_process.ProcessError): - _fail('The native runtime probe did not return its bounded observation.','unavailable') - if receipt['leader_returncode'] and probe['available']: - _fail('Failed native runtime probe claimed availability.','invalid') - return dict(probe,**inputs['definition_identity']) - - def _run_phase(self, phase, recipe, request_key, actor, inputs, authority, *, run_id=None, job=None, phase_id=None): - if self.db.in_transaction:_fail('Native phase cannot launch inside a metadata transaction.','busy') - with self.db.lock: - self.session.check_current() - if run_id is None and self._foreground_phase is not None: - _fail('Another explicit native preparation phase is active.','busy') - if not self.db.claim_runtime('project_native_phases'):_fail('Another current native phase owner is active.','busy') - phase_id=phase_id or uuid.uuid4().hex - if run_id is None:self._foreground_phase=phase_id - self._active.add(phase_id);self._contexts[phase_id]=authority - document=None;handle=None - self._never_launched.add(phase_id) - try: - parent=self.db.path/'project-native-phases';parent.mkdir(mode=0o700,exist_ok=True) - request_sha=hashlib.sha256(agent_api.encoded(dict(recipe=recipe,phase=phase,run_id=run_id,job=job,runtime=inputs['runtime'], - definition_identity=inputs['definition_identity'],request_key=request_key))).hexdigest() - prepared=prepare(parent/phase_id,phase=phase,attempt_id=phase_id,request_sha256=request_sha, - runtime=inputs['runtime'],worker=inputs['worker'],sources=inputs['sources'],model_aware=inputs['model_aware'],job=job) - self._prepared[phase_id]=prepared - document=dict(format=FORMAT,origin_catalog_id=self.session.project_id,phase_id=phase_id,phase=phase, - run_id=run_id,recipe=recipe,request_key=request_key,request_sha256=request_sha,actor_id=actor.actor_id, - definition_identity=copy.deepcopy(inputs['definition_identity']),spec=prepared.spec,events=[],payloads=[], - observations=dict.fromkeys(OBSERVATIONS),probe_result=None) - self._retain(document,'spec.json',recipe_process.encoded(prepared.spec),'execution_spec') - for item in prepared.spec['captured_files']: - name=str(Path(item['path']).relative_to(prepared.stage)) - raw=recipe_process.read_regular(item['path'],64*1024*1024) - if len(raw)!=item['bytes'] or hashlib.sha256(raw).hexdigest()!=item['sha256']: - _fail('Prepared native source or job changed before acknowledgement.','stale') - self._retain(document,name,raw,'execution_spec' if name=='native-job-template.json' else 'execution_source') - self._publish(document,'prepared') - if self.execution.custody is None:_fail('Native launch requires its original physical custody journal.','unavailable') - with self.db.lock,self.execution._journal_guard(): - self._dispatch_authorized(phase_id);self.session.check_current() - if not self.execution.custody.has_pending:self.execution.custody.acknowledge(self.session.snapshot) - self.execution.custody.native_prepared(document) - self.execution.custody.native_launch_intent(phase_id) - self._dispatch_authorized(phase_id) - # Once the foundation launch call is entered, failure may mean a - # spawned helper whose identity ACK was lost. Never infer no launch - # from an exception, absent Handle, or a saved PID scan. - handle=prepared.launch(prepared.stage/'custody', - _before_spawn=lambda:self._never_launched.discard(phase_id)) - self._handles[phase_id]=handle - with self.execution._journal_guard(): - helper=recipe_process.identity(handle.process.pid) - self.execution.custody.native_launched(phase_id,helper) - until=time.monotonic()+recipe_process.preparation_seconds(prepared.spec)+2 - terminal=False - while not terminal: - for event in handle.poll(): - if event['type']=='ready': - self._publish(document,'ready',helper=handle.ready) - try:self._dispatch_authorized(phase_id) - except WorkbenchError: - handle.cancel('cancelled') - until=time.monotonic()+recipe_process.CLEANUP_SECONDS+PARENT_DRAIN_ALLOWANCE - continue - self._publish(document,'go_intent',helper=handle.ready) - # Recheck actual authority after both durable ACKs. A - # saved GO intent is never permission to retry this send. - with self.db.lock: - self.session.check_current();self._dispatch_authorized(phase_id) - if not self.execution.custody.has_pending:_fail('Native local custody disappeared.','unknown') - prepared.check_current_runtime() - handle.go(handle.ready) - until=(time.monotonic()+prepared.spec['wall_seconds'] - +recipe_process.verification_seconds(prepared.spec)+recipe_process.CLEANUP_SECONDS+5) - elif event['type']=='terminal':terminal=True - elif event['type']=='lost':_fail('Native custodian control closed without its measured receipt.','unknown') - if run_id is not None: - with self.db.lock: - current=self.execution.runs._load(run_id) - if current['state']=='cancelling' or self.execution.runs._stop.is_set():handle.cancel('cancelled') - if time.monotonic()>until:_fail('Native phase exceeded its bounded custody deadline.','unknown') - if not terminal:time.sleep(.02) - evidence=prepared.evidence(handle) - self._retain_outputs(document) - for name,raw in (('stdout.log',evidence['stdout']),('stderr.log',evidence['stderr']), - ('receipt.json',recipe_process.encoded(evidence['receipt']))): - self._retain(document,name,raw,'custody_proof' if name=='receipt.json' else 'measured_stream') - for name,key in (('effective-job.json','effective_job'),('native-parent-observation.json','parent_observation')): - if evidence[key] is not None:self._retain(document,name,evidence[key],'measured_job') - receipt_sha=hashlib.sha256(recipe_process.encoded(evidence['receipt'])).hexdigest() - state='completed' if evidence['receipt']['outcome']=='completed' else 'failed' - self._publish(document,state,helper=handle.ready,receipt_sha256=receipt_sha) - if run_id is None: - with self.execution._journal_guard():self.execution.custody.native_confirmed(phase_id) - return dict(document=document,evidence=evidence,prepared=prepared) - except BaseException as error: - # An unacknowledged phase cannot send GO or publish a successful - # terminal fact. Close only this process's actual control channel. - if handle is not None: - try:handle.close_control() - except (OSError,recipe_process.ProcessError):pass - if phase_id not in self._never_launched: - retained=session_record(self.session, FAMILY,self.session.project_id+'.'+phase_id) - retained=None if retained is None else retained['document'] - acknowledged=(self.session.available and retained is not None - and retained['events'][-1]['state'] in ('completed','failed') - and retained['events'][-1]['receipt_sha256'] is not None) - if not acknowledged: - already_fenced=not self.session.available - self.session.available=False - if self.execution._runs is not None:self.execution._runs._fence_coordinator() - if not already_fenced: - raise WorkbenchError('Native spawn outcome is uncertain; reconcile exact original custody before further dispatch.', - 'outcome_unknown',409) from error - raise - finally: - self._active.discard(phase_id) - if self._foreground_phase==phase_id:self._foreground_phase=None - if handle is not None and handle.process.poll() is not None and handle.terminal: - self._handles.pop(phase_id,None) diff --git a/project_native_preparation.py b/project_native_preparation.py deleted file mode 100644 index ee4195a8..00000000 --- a/project_native_preparation.py +++ /dev/null @@ -1,430 +0,0 @@ -"""Explicit current native qualification, before the short admission transaction. - -The configured interpreter and installed packages are operator-managed inputs. -Measured interpreter/source bytes and observed package versions are evidence; -they do not promise a complete package closure or scientific reproducibility. -No serialized validation result can become this process-local preparation. -""" -import copy -from contextlib import contextmanager -from contextvars import ContextVar -import hashlib -import os -from pathlib import Path -import shutil -import sys - -from model_definitions import checked_json, natural, reference -from pipeline import (adapter_for_graph, decode_graph, digest, execution_digest, - identifier, model_aware_graph, closed, decode_probe_observation) -from project_session import operation_records -from workbench import WorkbenchError, timestamp -from project_session import session_operations - - -OPERATIONS=frozenset(('native_preparation.intent','native_preparation.validate')) -_CURRENT=ContextVar('project_native_preparation',default=None) - - -def _fail(message,code='unavailable'): - raise WorkbenchError(message,code,409) - - -def _sha(value): - if type(value) is not str or len(value)!=64 or any(c not in '0123456789abcdef' for c in value): - _fail('Native preparation requires an exact SHA256.','invalid') - - -def _key(operation,key): - from experiments import request_key - request_key(key) - return 'native-'+digest(dict(operation=operation,key=key)) - - -def _validation_observation(result,records): - closed(result,('status','valid','errors','validation_token','graph_revision','execution_sha256','release','runtime'),('selection_policy',)) - if type(result['valid']) is not bool or type(result['errors']) is not list or len(result['errors'])>100: - _fail('Invalid native validation result.','invalid') - natural(result['graph_revision'],'Graph revision',1);_sha(result['execution_sha256']) - if result['validation_token'] is not None:_sha(result['validation_token']) - for error in result['errors']: - closed(error,('path','message','code')) - if any(type(error[k]) is not str or len(error[k])>2000 for k in error):_fail('Invalid native validation error.','invalid') - if (result['valid'] and (result['errors'] or result['status']!='valid' or result['validation_token'] is None) - or not result['valid'] and (not result['errors'] or result['status']!=result['errors'][0]['code'] or result['validation_token'] is not None)): - _fail('Contradictory native validation result.','invalid') - release=result['release'] - if release is not None: - import release_validation - integrity=release.get('recipe') in release_validation.RECIPES - fields=('id','sha256','format','recipe','allowed_recipes','records','split_counts','prior_test_exposure','status') - if integrity: - fields+=('result_kind','validation_summary') - if release['recipe'] in release_validation.CLASSIFICATION_RECIPES:fields+=('class_vocabulary',) - closed(release,fields) - if release['result_kind']!='release_validation':_fail('Invalid integrity release result kind.','invalid') - else:closed(release,(*fields,'class_vocabulary'),('audio_summary',)) - _sha(release['id']);_sha(release['sha256']) - if release['id']!=release['sha256'] or release['status']!='available':_fail('Invalid frozen input observation.','invalid') - for name in ('format','recipe'): - if type(release[name]) is not str or not 1<=len(release[name])<=120:_fail('Invalid release task.','invalid') - for name in ('allowed_recipes',): - if type(release[name]) is not list or len(release[name])>10000 or any(type(v) is not str or len(v)>1000 for v in release[name]): - _fail('Invalid release vocabulary.','invalid') - if 'class_vocabulary' in release: - manifests=[] if records is None else [record['document']['manifest'] for record in records - if record['family']=='dataset_release' and record['id']==release['id']] - release_validation.decode_class_vocabulary(release['class_vocabulary'],release['recipe'], - manifest=manifests[0] if len(manifests)==1 else None) - natural(release['records'],'Frozen record count');closed(release['split_counts'],('train','validation','test')) - for count in release['split_counts'].values():natural(count,'Split count') - exposure=release['prior_test_exposure'];closed(exposure,('exposed','events')) - if type(exposure['exposed']) is not bool or type(exposure['events']) is not list or len(exposure['events'])>100000: - _fail('Invalid prior disclosure observations.','invalid') - for event in exposure['events']: - closed(event,('id','record_id','source_hash','reason','run_id','release_id','created_at')) - for field in ('id','run_id'):identifier(event[field]) - for field in ('source_hash','release_id'):_sha(event[field]) - for field in ('record_id','reason','created_at'): - if type(event[field]) is not str or len(event[field])>1000:_fail('Invalid disclosure observation text.','invalid') - if 'audio_summary' in release: - audio=release['audio_summary'];closed(audio,('sample_rates_hz','analyzed_frames','coordinate_contract')) - if type(audio['sample_rates_hz']) is not list or len(audio['sample_rates_hz'])>1000:_fail('Invalid audio rate inventory.','invalid') - for rate in audio['sample_rates_hz']:natural(rate,'Sample rate',1) - natural(audio['analyzed_frames'],'Analyzed frames') - if type(audio['coordinate_contract']) is not str or len(audio['coordinate_contract'])>1000:_fail('Invalid audio coordinate contract.','invalid') - if integrity: - matches=[] if records is None else [record['document']['manifest'] for record in records - if record['family']=='dataset_release' and record['id']==release['id']] - if len(matches)!=1:_fail('Integrity validation needs its exact retained frozen manifest.') - manifest=matches[0] - summary=release_validation.decode_summary(release['validation_summary'],release['recipe'], - manifest=manifest,release_id=release['id']) - if (release['records']!=len(manifest['records']) or release['split_counts']!=summary['split_counts'] - or release['format']!=manifest.get('format','canonical_v1')): - _fail('Integrity release header differs from its frozen summary.','invalid') - if release['recipe'] in release_validation.CLASSIFICATION_RECIPES: - if release['class_vocabulary']!=summary['class_vocabulary']:_fail('Integrity class vocabulary differs.','invalid') - runtime=result['runtime'] - recipes=[] - if runtime is not None: - import release_validation - from pipeline import MODEL_RECIPES - for recipe in ('image_classification','text_classification','audio_classification',*MODEL_RECIPES,*release_validation.RECIPES): - try:decode_probe_observation(recipe,runtime,with_definition=True) - except (WorkbenchError,TypeError,ValueError):continue - recipes.append(recipe) - if len(recipes)!=1:_fail('Unclassified native validation runtime.','invalid') - if 'selection_policy' in result: - from experiments import validate_retained_policy - validate_retained_policy(result['selection_policy']) - if result['valid']: - if release is None or runtime is None or not runtime['available'] or release['recipe']!=recipes[0]: - _fail('Native validation lacks its exact runtime and frozen input.','invalid') - if records is not None: - from project_material_fork import is_intent - matches=[] - for record in records: - if record['family']!='pipeline_graph':continue - for graph in record['document']['revisions']: - if is_intent(graph):continue - if graph['revision']!=result['graph_revision'] or execution_digest(graph)!=result['execution_sha256']:continue - token=digest(dict(graph_id=graph['id'],revision=graph['revision'],execution_sha256=execution_digest(graph), - release_sha256=release['sha256'],runtime=runtime)) - release_id=next((node['parameters']['release_id'] for node in graph['nodes'] if node['type']=='release'),None) - if graph['recipe']==recipes[0] and token==result['validation_token'] and release_id==release['id']:matches.append(graph) - if not matches:_fail('Native validation has no exact retained graph/runtime binding.','invalid') - - -def preparation_owner(owner): - """Select only the fixed current project owner; legacy paths stay legacy.""" - from project_material import _MaterialAccess - from project_execution import ProjectExecution - adapter=getattr(owner.dataset,'project_native_preparation',None) - project=isinstance(owner.access,_MaterialAccess) or isinstance(getattr(owner.dataset,'project_execution',None),ProjectExecution) - if not project and adapter is None:return None - if not isinstance(adapter,ProjectNativePreparation) or adapter.db is not owner.db: - _fail('Current native preparation for the runtime probe is unavailable.') - return adapter - - -def validate_operation_result(operation,result,records=None): - if operation not in OPERATIONS:return False - try: - if operation=='native_preparation.intent': - closed(result,('format','origin_catalog_id','actor_id','purpose','graph','model','composition', - 'release_id','definition_identity','runtime','occurred_at')) - if result['format']!='project_native_preparation_intent_v1' or result['purpose'] not in ('material','validation','admission'): - _fail('Unsupported native preparation intent.','unsupported') - for field in ('origin_catalog_id','actor_id'):identifier(result[field]) - graph=result['graph'];closed(graph,('id','revision','document_sha256','execution_sha256')) - identifier(graph['id']);natural(graph['revision'],'Graph revision',1) - for field in ('document_sha256','execution_sha256'):_sha(graph[field]) - _sha(result['release_id']) - if result['model'] is not None:reference(result['model'],'model',result['origin_catalog_id']) - if result['composition'] is not None:reference(result['composition'],'recipe_material',result['origin_catalog_id']) - identity=result['definition_identity'];closed(identity,('definition_files','adapter_definition_sha256')) - if type(identity['definition_files']) is not dict or not 1<=len(identity['definition_files'])<=120: - _fail('Invalid native definition inventory.','invalid') - from project_native_process import WORKERS, validate_current_runtime - for name,sha in identity['definition_files'].items(): - if type(name) is not str or Path(name).name!=name or not name.endswith('.py'): - _fail('Invalid native definition filename.','invalid') - _sha(sha) - if not set(identity['definition_files'])&WORKERS or digest(identity['definition_files'])!=identity['adapter_definition_sha256']: - _fail('Native definition identity differs.','invalid') - validate_current_runtime(result['runtime']) - from datetime import datetime - if datetime.fromisoformat(result['occurred_at']).utcoffset() is None:_fail('Native intent time requires an offset.','invalid') - if records is not None: - matches=[r['document'] for r in records if r['family']=='pipeline_graph' - and r['document']['origin_catalog_id']==result['origin_catalog_id'] - and r['document']['current']['id']==graph['id']] - if len(matches)!=1 or not any(v['revision']==graph['revision'] and digest(v)==graph['document_sha256'] - and execution_digest(v)==graph['execution_sha256'] for v in matches[0]['revisions']): - _fail('Native intent has no exact retained graph.','invalid') - actual=next(v for v in matches[0]['revisions'] if v['revision']==graph['revision']) - if (next((node['parameters']['release_id'] for node in actual['nodes'] if node['type']=='release'),None)!=result['release_id'] - or Path(adapter_for_graph(actual).__file__).name not in identity['definition_files']): - _fail('Native intent source or frozen input differs from its graph.','invalid') - from types import SimpleNamespace - from project_material import ProjectMaterial - retained=ProjectMaterial(SimpleNamespace(snapshot=dict(records=records),check_current=lambda:None)) - if result['model'] is not None:retained.model(result['model']) - if result['composition'] is not None: - composition=retained.recipe(result['composition'])['material'] - if (composition['model']!=result['model'] or composition['recipe_id']!=graph['id'] - or composition['recipe_revision']!=graph['revision']): - _fail('Native admission intent differs from its retained composition.','invalid') - else: - _validation_observation(result,records) - checked_json(result,1024**2) - return True - except WorkbenchError:raise - except (ValueError,TypeError,KeyError,AttributeError,ImportError): - _fail('Invalid native preparation observation.','invalid') - - -class NativePreparationContext: - """A lexical current qualification, never a portable admission capability.""" - def __init__(self,adapter,owner,graph,model,composition,purpose,key): - self.adapter,self.owner=adapter,owner - self.graph=copy.deepcopy(decode_graph(graph));self.model=copy.deepcopy(model) - self.recipe=self.graph['recipe'] - self.composition=copy.deepcopy(composition);self.purpose=purpose;self.key=key - self.actor=adapter.access.require('execute','pipeline.probe_native',self.graph['recipe'],owner_only=True) - self.configured_executable=os.environ.get('TULDOK_TRAINING_PYTHON') or sys.executable - self.definition=owner.definition_identity(self.graph['recipe']) - self.sources={name:(owner.source_path/name).read_bytes() for name in self.definition['definition_files']} - self.release_id=next(node['parameters']['release_id'] for node in self.graph['nodes'] if node['type']=='release') - self.release=owner.inspect_release(self.release_id,private=True,recipe=self.graph['recipe']) - self.model_value=adapter.materials.model(model,verify=True) if model is not None else None - if model is not None: - current_model,_definition=owner._builtin_model_for_graph(self.graph,model) - if current_model!=self.model_value or {item['import_path']:item['blob']['sha256'] - for item in current_model['material']['source_closure']}!=self.definition['definition_files']: - _fail('Published native model differs from its graph or current source.','stale') - from project_native_process import current_runtime - self.runtime=current_runtime(self.configured_executable) - self._active=False;self._probe=None;self._prepared=None;self._consumed=False;self.phase=None - - def _check(self,recipe): - if not self._active or _CURRENT.get() is not self or recipe!=self.graph['recipe']: - _fail('An explicit current native preparation is required.') - self.adapter.session.check_current() - actor=self.adapter.access.require('execute','pipeline.probe_native',recipe,owner_only=True) - if actor.actor_id!=self.actor.actor_id:_fail('Native preparation caller changed.','conflict') - if (os.environ.get('TULDOK_TRAINING_PYTHON') or sys.executable)!=self.configured_executable: - _fail('Configured native interpreter changed.','stale') - if self.owner.get(self.graph['id'])!=self.graph or self.owner.definition_identity(recipe)!=self.definition: - _fail('Native graph or source changed during qualification.','stale') - if any(hashlib.sha256((self.owner.source_path/name).read_bytes()).hexdigest()!=sha - for name,sha in self.definition['definition_files'].items()): - _fail('Native source bytes changed.','stale') - current=self.owner.inspect_release(self.release_id,private=True,recipe=recipe) - if current!=self.release:_fail('Native frozen input observation changed.','stale') - if self.model is not None and self.adapter.materials.model(self.model,verify=True)!=self.model_value: - _fail('Native model observation changed.','stale') - from project_native_process import current_runtime - if current_runtime(self.configured_executable)!=self.runtime:_fail('Configured native interpreter identity changed.','stale') - return actor - - def authorize_probe(self,recipe): - return self._check(recipe) - - def native_inputs(self,recipe): - self.authorize_probe(recipe) - return dict(runtime=copy.deepcopy(self.runtime),worker=Path(adapter_for_graph(self.graph).__file__).name, - sources=copy.deepcopy(self.sources),model_aware=model_aware_graph(self.graph),definition_identity=copy.deepcopy(self.definition)) - - def probe(self,owner,recipe): - if owner.db is not self.adapter.db:_fail('Native preparation belongs to another projection.') - self._check(recipe) - if self._probe is None: - if self.adapter.db.in_transaction:_fail('Native probe cannot run inside a metadata transaction.','unsupported') - self.authorize_probe(recipe) - result=self.adapter.execution.native.probe(recipe,expected_checkpoint=self.adapter.session.summary['checkpoint'], - request_key=self.key+'.probe',preparation=self) - self._probe=copy.deepcopy(result['runtime']);self.phase=copy.deepcopy(result['phase']) - return copy.deepcopy(self._probe) - - def capture_builtin(self,owner,value): - self._check(self.graph['recipe']) - if self.composition is None or value!=self.composition:_fail('Prepared native material differs.','stale') - if self.adapter.db.in_transaction: - if self._prepared is None or self._consumed:_fail('Native qualification is missing or already consumed.') - self._consumed=True - return copy.deepcopy(self._prepared) - if self._prepared is None:self._prepared=owner._prepare_builtin_recipe_material_current(value) - return copy.deepcopy(self._prepared) - - def consume_admission(self): - self._check(self.recipe) - if self._consumed:_fail('Native qualification has already been consumed.') - self._consumed=True - - -class PurePreparationContext: - """Current integrity qualification; it cannot authorize a child phase.""" - def __init__(self,adapter,owner,graph): - self.adapter,self.owner=adapter,owner;self.graph=copy.deepcopy(graph) - self.recipe=graph['recipe'];self.definition=owner.definition_identity(self.recipe) - self.actor=adapter.access.require('execute','pipeline.snapshot',graph['id'],owner_only=True) - self.validation=owner.validate_graph(graph) - if not self.validation['valid']: - first=self.validation['errors'][0];_fail(first['message'],first['code']) - self.release=owner.inspect_release(self.validation['release']['id'],private=True,recipe=self.recipe) - self._consumed=False;self._active=True - - def consume_admission(self): - if not self._active or self._consumed:_fail('Current integrity qualification has already been consumed.') - self.adapter.session.check_current() - actor=self.adapter.access.require('execute','pipeline.snapshot',self.graph['id'],owner_only=True) - if actor.actor_id!=self.actor.actor_id:_fail('Current integrity caller changed.','conflict') - if self.owner.get(self.graph['id'])!=self.graph or self.owner.definition_identity(self.recipe)!=self.definition: - _fail('Current integrity graph or source changed.','stale') - if self.owner.inspect_release(self.release['id'],private=True,recipe=self.recipe)!=self.release: - _fail('Current integrity frozen input changed.','stale') - self._consumed=True - - -class ProjectNativePreparation: - def __init__(self,projection): - self.projection=projection;self.session=projection.session;self.db=projection.db - self.access=projection.execution.runtime_access;self.execution=projection.execution;self.materials=projection.materials - - def current(self,owner): - context=_CURRENT.get() - if not isinstance(context,NativePreparationContext) or context.adapter is not self or owner.db is not self.db: - _fail('Native qualification requires an explicit current preparation.') - return context - - def probe(self,owner,recipe): - actor=self.access._context() - if actor.mode=='job': - if actor.kind!='runs' or actor.catalog_id!=self.session.project_id: - _fail('Native probe requires its exact current Run admission.') - self.access.require('execute','pipeline.probe_native',recipe) - result=self.execution.native.probe_current_run(owner,recipe) - return copy.deepcopy(result['runtime']) - return self.current(owner).probe(owner,recipe) - - @contextmanager - def _scope(self,owner,graph,model,composition,purpose,expected_checkpoint,key): - if self.db.in_transaction:_fail('Native preparation must precede the metadata transaction.','unsupported') - if _CURRENT.get() is not None:_fail('A native preparation is already active.','busy') - self.access.require('edit','native_preparation.'+purpose,graph['id'],owner_only=True) - self.session.check_current() - if self.session.summary['checkpoint']!=expected_checkpoint:_fail('Expected project checkpoint changed.','stale_project') - context=NativePreparationContext(self,owner,graph,model,composition,purpose,_key(purpose,key)) - result=dict(format='project_native_preparation_intent_v1',origin_catalog_id=self.session.project_id, - actor_id=context.actor.actor_id,purpose=purpose,graph=dict(id=graph['id'],revision=graph['revision'], - document_sha256=digest(graph),execution_sha256=execution_digest(graph)),model=model, - composition=None if composition is None else composition['ref'],release_id=context.release_id, - definition_identity=context.definition,runtime=context.runtime,occurred_at=timestamp()) - body={name:copy.deepcopy(value) for name,value in result.items() if name not in ('format','occurred_at')} - self.session.mutate('native_preparation.intent',graph['id'],body,expected_checkpoint,context.key, - lambda:copy.deepcopy(result),lambda value,before:dict(records=[],result=value),scope='execute') - context._active=True;token=_CURRENT.set(context) - try:yield context - finally:_CURRENT.reset(token);context._active=False;context._prepared=None - - def validate_graph(self,owner,graph_id,revision,expected_checkpoint,key): - self.access.require('edit','native_preparation.validation',graph_id,owner_only=True) - self.access.require('execute','pipeline.probe_native',graph_id,owner_only=True) - body=dict(graph_id=graph_id,revision=revision) - prior=session_operations(self.session).get(key) - if prior is not None: - return self.session.mutate('native_preparation.validate',graph_id,body,expected_checkpoint,key, - lambda:(_ for _ in ()).throw(RuntimeError('Native validation replay launched a probe.')), - lambda value,before:dict(records=[],result=value),scope='execute') - graph=owner.get(graph_id) - if graph['revision']!=revision:_fail('Graph changed before native validation.','stale') - import release_validation - if adapter_for_graph(graph) is release_validation: - self.session.check_current() - if self.session.summary['checkpoint']!=expected_checkpoint:_fail('Expected project checkpoint changed.','stale_project') - value=owner.validate_graph(graph) - return self.session.mutate('native_preparation.validate',graph_id,body,expected_checkpoint,key, - lambda:copy.deepcopy(value),lambda value,before:dict(records=[],result=value),scope='execute') - with self._scope(owner,graph,None,None,'validation',expected_checkpoint,key) as context: - value=owner.validate_graph(graph);context._check(graph['recipe']) - return self.session.mutate('native_preparation.validate',graph_id,body,self.session.summary['checkpoint'],key, - lambda:copy.deepcopy(value),lambda value,before:dict(records=[],result=value),scope='execute') - - @contextmanager - def current_graph(self,owner,graph_id,revision,expected_checkpoint,key): - if self.db.in_transaction:_fail('Current native validation must precede admission.','unsupported') - self.access.require('edit','native_preparation.admission',graph_id,owner_only=True) - self.session.check_current() - if self.session.summary['checkpoint']!=expected_checkpoint:_fail('Expected project checkpoint changed.','stale_project') - graph=owner.get(graph_id) - if graph['revision']!=revision:_fail('Graph changed before native admission.','stale') - import release_validation - if adapter_for_graph(graph) is release_validation: - context=PurePreparationContext(self,owner,graph) - try:yield context - finally:context._active=False - return - with self._scope(owner,graph,None,None,'admission',expected_checkpoint,key) as context: - context.validation=owner.validate_graph(graph) - if not context.validation['valid']: - first=context.validation['errors'][0];_fail(first['message'],first['code']) - context._check(graph['recipe']) - yield context - - def prepare_recipe(self,owner,graph_id,revision,model_ref,expected_checkpoint,key): - self.materials._require_resolved('pipeline_graph',graph_id) - self.access.require('edit','recipes.prepare_builtin_material',graph_id,owner_only=True) - self.access.require('execute','pipeline.probe_native',graph_id,owner_only=True) - body=dict(graph_id=graph_id,revision=revision,model=model_ref,reconcile_capture=False) - operation='recipes.prepare_builtin_material' - if key in session_operations(self.session): - return self.session.mutate(operation,graph_id,body,expected_checkpoint,key, - lambda:(_ for _ in ()).throw(RuntimeError('Material replay launched a native probe.')), - lambda value,before:dict(records=[],result=value)) - graph=owner.get(graph_id) - if graph['revision']!=revision or not model_aware_graph(graph):_fail('Exact model-aware graph is unavailable.','stale') - self.materials.materialize_projection(model_ref,owner.dataset.models.path) - with self._scope(owner,graph,model_ref,None,'material',expected_checkpoint,key) as context: - prepared=owner.prepare_builtin_material(graph_id,revision,model_ref) - try: - context._check(graph['recipe']) - def capture(value,before): - record=self.materials.capture_recipe_material(value,owner.material_path) - return dict(records=self.materials._coalesce([record,*self.materials.declarations(record), - *self.materials.capture_recipe_dependencies(record,before)]),result=value) - return self.session.mutate(operation,graph_id,body,self.session.summary['checkpoint'],key, - lambda:owner._retain_material(prepared),capture) - finally: - if prepared['staging'].exists():shutil.rmtree(prepared['staging']) - - @contextmanager - def admission(self,owner,material_ref,expected_checkpoint,key): - value=self.materials.recipe(material_ref,verify=True) - import json - snapshot=json.loads(self.materials.blob(material_ref,value['material']['recipe_document'],2*1024**2)) - graph=decode_graph(snapshot['graph']) - with self._scope(owner,graph,value['material']['model'],value,'admission',expected_checkpoint,key) as context: - context.capture_builtin(owner,value) - yield context diff --git a/project_native_process.py b/project_native_process.py deleted file mode 100644 index 41b28f38..00000000 --- a/project_native_process.py +++ /dev/null @@ -1,445 +0,0 @@ -"""Finite native probe/train/verifier preparation over the existing custodian. - -Only the current native domain owner supplies measured runtime and source bytes. -Preparation owns new disposable files, not SQL, portable publication, authority, -or GO. The caller acknowledges READY through its canonical boundary, then uses -the returned ordinary recipe_process.Handle explicitly. -""" -import copy -import hashlib -import os -from pathlib import Path -import re -import stat - -import recipe_process as custody - -WORKERS = frozenset(('image_training.py', 'text_training.py', 'audio_training.py')) -PHASES = frozenset(('probe', 'train', 'verify')) -TEMPLATE_FORMAT = 'native_parent_binding_v1' -TEMPLATE_LIMIT = 64 * 1024 -BOOTSTRAP = Path(__file__).with_name('native_process_bootstrap.py') -ENVIRONMENT = dict(PATH='/usr/bin:/bin', LANG='C.UTF-8', CUDA_VISIBLE_DEVICES='', - OMP_NUM_THREADS='1', MKL_NUM_THREADS='1', OPENBLAS_NUM_THREADS='1', BLIS_NUM_THREADS='1', - VECLIB_MAXIMUM_THREADS='1', NUMEXPR_NUM_THREADS='1', PYTHONDONTWRITEBYTECODE='1') - - -def _fail(message, code='invalid'): - raise custody.ProcessError(message, code) - - -def validate_current_runtime(value): - """Pure observed runtime metadata, not a complete package/library closure.""" - if (type(value) is not dict or set(value) != {'executable', 'executable_source', 'executable_sha256', - 'trusted_install_owner_uid', 'files'} - or type(value['files']) is not dict or not 1 <= len(value['files']) <= 3 - or type(value['trusted_install_owner_uid']) is not int or value['trusted_install_owner_uid'] < 0): - _fail('Invalid observed current native runtime.') - for key in ('executable', 'executable_source'): - path = value[key] - if (type(path) is not str or not 1 <= len(path) <= 4096 or '\0' in path - or not Path(path).is_absolute() or str(Path(path)) != path or '..' in Path(path).parts): - _fail('Invalid observed native interpreter path.') - if type(value['executable_sha256']) is not str or custody.HASH.fullmatch(value['executable_sha256']) is None: - _fail('Invalid observed native interpreter hash.') - allowed = {value['executable_source'], str(Path(value['executable']).parent/'pyvenv.cfg'), - str(Path(value['executable']).parent.parent/'pyvenv.cfg')} - for path, row in value['files'].items(): - if (path not in allowed or type(row) is not dict or set(row) != {'sha256', 'bytes'} - or type(row['sha256']) is not str or custody.HASH.fullmatch(row['sha256']) is None - or type(row['bytes']) is not int or not 0 <= row['bytes'] <= 64*1024*1024): - _fail('Invalid observed native runtime file.') - if value['files'].get(value['executable_source'], {}).get('sha256') != value['executable_sha256']: - _fail('Observed native interpreter source differs.') - return copy.deepcopy(value) - - -def current_runtime(executable): - """Measure only the explicit current interpreter and venv configuration. - - Installed packages and native libraries remain operator-managed dependencies; - the actual native probe observes their reported versions. No executable runs - here and no alternative interpreter is selected. - """ - if type(executable) is not str or not executable or '\0' in executable: - _fail('Choose the explicitly configured native interpreter.') - configured = Path(os.path.abspath(executable)) - try: - physical = configured.resolve(strict=True) - files = {} - for path in dict.fromkeys((physical, configured.parent/'pyvenv.cfg', configured.parent.parent/'pyvenv.cfg')): - if path != physical and not os.path.lexists(path): continue - raw = custody.read_regular(path, 64*1024*1024) - files[str(path)] = dict(sha256=hashlib.sha256(raw).hexdigest(), bytes=len(raw)) - if configured.resolve(strict=True) != physical or not os.path.samestat(configured.stat(),physical.stat()): - _fail('Configured native interpreter alias changed.', 'stale') - return validate_current_runtime(dict(executable=str(configured), executable_source=str(physical), - executable_sha256=files[str(physical)]['sha256'], trusted_install_owner_uid=os.stat('/usr').st_uid, - files=files)) - except OSError: - _fail('Configured current native interpreter is unavailable.', 'unavailable') - - -def validate_prepared_spec(value, *, phase, worker): - """Pure finite native invocation grammar; never a current runtime resolver.""" - value = custody.decode_retained_spec(value) - if (type(phase) is not str or phase not in PHASES or type(worker) is not str or worker not in WORKERS - or value['schema_version'] != 1 or value['env'] != ENVIRONMENT - or value.get('native_loader_policy') != 'glibc_x86_64_no_preload_v1' - or any(key in value for key in ('cpu_snapshot', 'torch_runtime', 'resource_profile'))): - _fail('Unsupported retained native phase specification.') - root = Path(value['cwd']) - if str(root) != value['cwd'] or '..' in root.parts: - _fail('Retained native working directory differs.') - source = root / 'source' - captures = {row['path'] for row in value['captured_files']} - template = str(root / 'native-job-template.json') - bootstrap = str(source / BOOTSTRAP.name) - for path in captures: - item = Path(path) - if path == template and phase != 'probe': continue - if (item.parent != source or str(item) != path - or re.fullmatch(r'[A-Za-z_][A-Za-z0-9_]{0,119}\.py', item.name) is None - or item.name == BOOTSTRAP.name and phase == 'probe'): - _fail('Unclassified retained native capture path.') - if str(source / worker) not in captures: - _fail('Retained native worker capture is missing.') - executable = value['argv'][0] - if phase == 'probe': - expected = [executable, '-B', str(source / worker), '--probe'] - if value['argv'] not in (expected, expected + ['--model-aware']): - _fail('Retained native probe argument vector differs.') - elif (value['argv'] != [executable, '-I', '-B', bootstrap, phase, template] - or not {bootstrap, template} <= captures): - _fail('Retained native job bootstrap differs.') - if phase in ('probe', 'train') and value['output_dir'] != str(root / 'output'): - _fail('Retained native output directory differs.') - return value - - -def _job_template(spec, phase, template): - if (type(template) is not bytes or not 1 <= len(template) <= TEMPLATE_LIMIT): - _fail('Native retained job template is unavailable or exceeds its bound.', 'stale') - frame = custody.decode(template) - if (type(frame) is not dict or set(frame) != {'format','phase','worker','attempt_id','request_sha256','job'} - or frame['format'] != TEMPLATE_FORMAT or frame['phase'] != phase - or frame['attempt_id'] != spec['attempt_id'] or frame['request_sha256'] != spec['request_sha256'] - or type(frame['job']) is not dict or type(frame['job'].get('parent_pid')) is not int - or frame['job']['parent_pid'] != 1 or custody.encoded(frame) != template): - _fail('Native retained job template differs from its phase.', 'stale') - return frame - - -def validate_job_evidence(spec, *, phase, helper, template, effective_job, parent_observation, receipt): - """Pure exact native job proof for inline history or current measured bytes. - - The existing native worker still owns scientific job semantics. This seam - binds only the immutable template, qualified helper, distinct effective job - and closed custodian receipt; it confers no current execution authority. - """ - spec = custody.decode_retained_spec(spec) - if type(phase) is not str or phase not in PHASES or not custody.valid_identity(helper): - _fail('Invalid native job evidence phase or helper.') - if phase == 'probe': - if any(value is not None for value in (template,effective_job,parent_observation)): - _fail('Native probe cannot carry job execution evidence.', 'stale') - worker = Path(spec['argv'][2]).name if len(spec['argv']) > 2 else '' - frame = None - else: - frame = _job_template(spec,phase,template) - worker = frame['worker'] - spec = validate_prepared_spec(spec,phase=phase,worker=worker) - expected = dict(attempt_id=spec['attempt_id'],request_sha256=spec['request_sha256'], - spec_sha256=hashlib.sha256(custody.encoded(spec)).hexdigest(),helper=helper) - if type(receipt) is not dict:_fail('Native job evidence requires its closed custody receipt.') - receipt = custody.validate_receipt(custody.encoded(receipt),expected) - if not receipt['drained']:_fail('Native descendant drainage is unconfirmed.', 'unknown') - if frame is not None: - row = next(item for item in spec['captured_files'] if item['path'] == str(Path(spec['cwd'])/'native-job-template.json')) - if len(template) != row['bytes'] or hashlib.sha256(template).hexdigest() != row['sha256']: - _fail('Native retained job template differs from its captured identity.', 'stale') - if effective_job is not None or parent_observation is not None: - if (type(effective_job) is not bytes or type(parent_observation) is not bytes - or not 1 <= len(effective_job) <= TEMPLATE_LIMIT - or not 1 <= len(parent_observation) <= TEMPLATE_LIMIT): - _fail('Native measured job evidence is incomplete or exceeds its bound.', 'unknown') - expected_job = dict(frame['job'],parent_pid=helper['pid']) - expected_observation = dict(format='native_parent_observation_v1', - attempt_id=spec['attempt_id'],request_sha256=spec['request_sha256'], - template_sha256=hashlib.sha256(template).hexdigest(), - effective_job_sha256=hashlib.sha256(effective_job).hexdigest(),helper=helper) - if (effective_job != custody.encoded(expected_job) or parent_observation != custody.encoded(expected_observation) - or not receipt['go_received']): - _fail('Native effective job differs from its exact qualified parent.', 'stale') - elif receipt['outcome'] == 'completed': - _fail('Completed native phase lacks measured job evidence.', 'unknown') - return dict(receipt=receipt,template=template,effective_job=effective_job,parent_observation=parent_observation) - - -def _record(path, raw): - return dict(path=str(path), sha256=hashlib.sha256(raw).hexdigest(), bytes=len(raw)) - - -def _write(directory, name, raw): - descriptor = os.open(name, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, - 0o400, dir_fd=directory) - with os.fdopen(descriptor, 'wb') as target: - target.write(raw); target.flush(); os.fsync(target.fileno()) - - -def _parent(path): - """Walk the caller's explicit current path without directory symlinks.""" - if not path.is_absolute() or '..' in path.parts or path.name in ('', '.', '..'): - _fail('Native staging requires an absolute new path.') - descriptor = os.open('/', os.O_RDONLY | os.O_DIRECTORY) - try: - for component in path.parent.parts[1:]: - following = os.open(component, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=descriptor) - os.close(descriptor); descriptor = following - return descriptor - except BaseException: - os.close(descriptor); raise - - -def _directory(path): - parent = _parent(path) - try: - descriptor = os.open(path.name, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=parent) - finally:os.close(parent) - info = os.fstat(descriptor) - if info.st_uid != os.getuid() or info.st_mode & 0o077: - os.close(descriptor) - _fail('Native phase evidence requires its current private physical directory.', 'stale') - return descriptor - - -def _read_at(directory, name, maximum, *, immutable=False): - descriptor = os.open(name, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK, dir_fd=directory) - with os.fdopen(descriptor, 'rb') as source: - before = os.fstat(source.fileno()) - if (not stat.S_ISREG(before.st_mode) or before.st_nlink != 1 or before.st_uid != os.getuid() - or before.st_size > maximum or immutable and before.st_mode & 0o222): - _fail('Native phase evidence file is unsafe or exceeds its bound.', 'stale') - raw = source.read(maximum + 1) - after = os.fstat(source.fileno()) - identity = lambda row: (row.st_dev,row.st_ino,row.st_mode,row.st_nlink,row.st_uid, - row.st_size,row.st_mtime_ns,row.st_ctime_ns) - if (len(raw) > maximum or identity(before) != identity(after) - or identity(after) != identity(os.stat(name, dir_fd=directory, follow_symlinks=False))): - _fail('Native phase evidence changed during observation.', 'stale') - return raw - - -def read_phase_evidence(stage, spec, *, phase, helper): - """Read one caller-qualified original physical phase, never restore custody. - - The caller must first prove its current original-host/root/projection journal - binding. This function uses only that explicit stage and its custody child; - retained absolute paths cannot select another filesystem root. No runtime - lookup, process observation, signal, launch or GO occurs here. - """ - return _read_phase_evidence(stage, spec, phase=phase, helper=helper, - custody_directory=Path(stage) / 'custody') - - -def _read_phase_evidence(stage, spec, *, phase, helper, custody_directory): - stage = Path(stage) - spec = custody.decode_retained_spec(spec) - if spec['cwd'] != str(stage) or not custody.valid_identity(helper): - _fail('Native phase evidence differs from its qualified physical stage or helper.', 'stale') - if type(phase) is not str or phase not in PHASES: - _fail('Unsupported native phase evidence.') - root = source = owner = None - try: - root = _directory(stage) - template = None - if phase == 'probe': - worker = Path(spec['argv'][2]).name if len(spec['argv']) > 2 else '' - else: - template = _read_at(root, 'native-job-template.json', TEMPLATE_LIMIT, immutable=True) - frame = _job_template(spec,phase,template) - worker = frame['worker'] - spec = validate_prepared_spec(spec, phase=phase, worker=worker) - source = os.open('source', os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=root) - for item in spec['captured_files']: - name = Path(item['path']).name - raw = template if item['path'] == str(stage/'native-job-template.json') else _read_at( - source, name, item['bytes'], immutable=True) - if raw is None or len(raw) != item['bytes'] or hashlib.sha256(raw).hexdigest() != item['sha256']: - _fail('Native retained capture differs from its exact specification.', 'stale') - expected = dict(attempt_id=spec['attempt_id'],request_sha256=spec['request_sha256'], - spec_sha256=hashlib.sha256(custody.encoded(spec)).hexdigest(),helper=helper) - try: - owner = _directory(Path(custody_directory)) - receipt_raw = _read_at(owner,'receipt.json',16384) - receipt = custody.validate_receipt(receipt_raw,expected) - if custody.encoded(receipt) != receipt_raw: - _fail('Native custody receipt lost its exact canonical bytes.', 'stale') - except (OSError,custody.ProcessError): - _fail('Native phase has no exact drainage receipt.', 'unknown') - if not receipt['drained']: _fail('Native descendant drainage is unconfirmed.', 'unknown') - streams = {} - for name in ('stdout','stderr'): - row = receipt['streams'][name] - raw = _read_at(owner,name+'.log',custody.STREAM_LIMIT) - if len(raw) != row['bytes'] or hashlib.sha256(raw).hexdigest() != row['sha256']: - _fail('Native measured stream differs from its custody receipt.', 'stale') - streams[name] = raw - effective = observation = None - if template is not None: - present = [] - for name in ('effective-job.json','native-parent-observation.json'): - try:os.stat(name,dir_fd=root,follow_symlinks=False);present.append(True) - except FileNotFoundError:present.append(False) - if any(present): - if not all(present): _fail('Native measured job evidence is incomplete.', 'unknown') - effective = _read_at(root,'effective-job.json',TEMPLATE_LIMIT,immutable=True) - observation = _read_at(root,'native-parent-observation.json',TEMPLATE_LIMIT,immutable=True) - proof = validate_job_evidence(spec,phase=phase,helper=helper,template=template, - effective_job=effective,parent_observation=observation,receipt=receipt) - if not os.path.samestat(os.fstat(root),os.stat(stage,follow_symlinks=False)): - _fail('Native physical phase changed during observation.', 'stale') - if (not os.path.samestat(os.fstat(source),os.stat('source',dir_fd=root,follow_symlinks=False)) - or not os.path.samestat(os.fstat(owner),os.stat(custody_directory,follow_symlinks=False))): - _fail('Native phase evidence directory changed during observation.', 'stale') - return dict(proof,stdout=streams['stdout'],stderr=streams['stderr']) - finally: - for descriptor in (owner,source,root): - if descriptor is not None:os.close(descriptor) - - -class PreparedNative: - """A fixed phase specification and its new files; never an execution grant.""" - def __init__(self, stage, phase, spec, template, runtime=None): - self.stage, self.phase = stage, phase - self._spec, self.template = copy.deepcopy(spec), template - self._runtime = copy.deepcopy(runtime) - - @property - def spec(self): - return copy.deepcopy(self._spec) - - def launch(self, custody_directory, *, _before_spawn=None): - """Return a READY/GO Handle. This method never sends GO.""" - if self._runtime is None: - return custody.launch(self.spec, custody_directory, _before_spawn=_before_spawn) - self.check_current_runtime() - descriptor = os.open(self._runtime['executable_source'], os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK) - try: - if not os.path.samestat(os.fstat(descriptor), os.stat(self._runtime['executable'])): - _fail('Configured interpreter alias changed before launch.', 'stale') - return custody.launch(self.spec, custody_directory, executable_fd=descriptor, - _before_spawn=_before_spawn) - finally:os.close(descriptor) - - def check_current_runtime(self): - """Explicit owner check before GO; never dispatches or grants permission.""" - if self._runtime is not None and current_runtime(self._runtime['executable']) != self._runtime: - _fail('Current native interpreter or venv configuration changed.', 'stale') - return copy.deepcopy(self._runtime) - - def evidence(self, handle): - """Read the same exact phase proof used by original-host recovery.""" - if handle.spec != self._spec or handle.ready is None: - _fail('Native phase handle differs from its prepared specification.', 'unknown') - result = _read_phase_evidence(self.stage, self._spec, phase=self.phase, - helper=handle.ready, custody_directory=handle.directory) - if result['template'] != self.template: - _fail('Native immutable job template differs from its prepared value.', 'stale') - return result - - -def prepare(stage, *, phase, attempt_id, request_sha256, runtime, worker, sources, - job=None, model_aware=False, wall_seconds=None, max_output_bytes=64 * 1024 * 1024): - """Create one new phase, using only caller-supplied current measurements. - - runtime is current_runtime's explicit interpreter/venv observation, or the - four-field regular-file input executable/executable_sha256/ - trusted_install_owner_uid/files. These are observed files, not complete - installed package/library closure. sources maps bounded Python - basenames to exact captured bytes. The existing worker owns job semantics; - this boundary requires parent_pid=1 and retains the whole template exactly. - A verifier may inspect the preceding training phase's private output folder. - """ - if (type(phase) is not str or phase not in PHASES or type(worker) is not str - or worker not in WORKERS or type(model_aware) is not bool - or type(attempt_id) is not str or custody.ID.fullmatch(attempt_id) is None - or type(request_sha256) is not str or custody.HASH.fullmatch(request_sha256) is None): - _fail('Invalid fixed native phase identity.') - if (type(runtime) is not dict or set(runtime) not in ( - {'executable', 'executable_sha256', 'trusted_install_owner_uid', 'files'}, - {'executable', 'executable_source', 'executable_sha256', 'trusted_install_owner_uid', 'files'}) - or type(runtime['files']) is not dict or not runtime['files']): - _fail('Supply an explicitly measured current native runtime.') - measured = validate_current_runtime(runtime) if 'executable_source' in runtime else None - if (type(sources) is not dict or worker not in sources or not 1 <= len(sources) <= 120 - or any(type(name) is not str or re.fullmatch(r'[A-Za-z_][A-Za-z0-9_]{0,119}\.py', name) is None - or name == BOOTSTRAP.name or type(raw) is not bytes for name, raw in sources.items())): - _fail('Supply the exact finite native worker source closure.') - if sum(map(len, sources.values())) > 64 * 1024 * 1024 - TEMPLATE_LIMIT: - _fail('Native source closure exceeds its custody bound.') - stage = Path(stage) - if phase == 'probe': - if job is not None: _fail('Native probe cannot accept a job.') - template = None - output = stage / 'output' - else: - if type(job) is not dict or type(job.get('parent_pid')) is not int or job['parent_pid'] != 1: - _fail('Native job must retain its parent_pid=1 template.') - if type(job.get('output_dir')) is not str or not Path(job['output_dir']).is_absolute(): - _fail('Native job requires its current private output directory.') - output = Path(job['output_dir']) - if phase == 'train' and output != stage / 'output': - _fail('Native training output must belong to its new phase.') - template = custody.encoded(dict(format=TEMPLATE_FORMAT, phase=phase, worker=worker, - attempt_id=attempt_id, request_sha256=request_sha256, job=job)) - if len(template) > TEMPLATE_LIMIT: _fail('Native job template exceeds 64 KiB.') - files = [] - for path, item in runtime['files'].items(): - if (type(path) is not str or not Path(path).is_absolute() or type(item) is not dict - or set(item) != {'sha256', 'bytes'}): _fail('Invalid measured native runtime file.') - files.append(dict(path=path, **item)) - executable = runtime['executable'] - executable_source = runtime.get('executable_source', executable) - if (executable_source not in runtime['files'] or runtime['files'][executable_source]['sha256'] != runtime['executable_sha256']): - _fail('Native interpreter is absent from its measured runtime closure.') - captures = [_record(stage / 'source' / name, raw) for name, raw in sorted(sources.items())] - if template is not None: - bootstrap = BOOTSTRAP.read_bytes() - captures.extend((_record(stage / 'source' / BOOTSTRAP.name, bootstrap), - _record(stage / 'native-job-template.json', template))) - argv = [executable, '-I', '-B', str(stage / 'source' / BOOTSTRAP.name), phase, - str(stage / 'native-job-template.json')] - else: - argv = [executable, '-B', str(stage / 'source' / worker), '--probe', - *(['--model-aware'] if model_aware else [])] - spec = custody.validate_spec(dict(schema_version=1, attempt_id=attempt_id, request_sha256=request_sha256, - argv=argv, env=ENVIRONMENT.copy(), cwd=str(stage), stdin_base64='', - wall_seconds=wall_seconds if wall_seconds is not None else {'probe':45, 'train':600, 'verify':90}[phase], - executable_sha256=runtime['executable_sha256'], max_output_bytes=max_output_bytes, - output_dir=str(output), captured_files=captures, runtime_files=sorted(files, key=lambda row:row['path']), - trusted_install_owner_uid=runtime['trusted_install_owner_uid'], native_loader_policy='glibc_x86_64_no_preload_v1')) - parent = _parent(stage) - directory = source = None - try: - os.mkdir(stage.name, 0o700, dir_fd=parent) - directory = os.open(stage.name, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=parent) - os.mkdir('source', 0o700, dir_fd=directory) - source = os.open('source', os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=directory) - if output == stage / 'output': os.mkdir('output', 0o700, dir_fd=directory) - elif phase == 'verify': - check = os.open(output, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW) - try: - info = os.fstat(check) - if info.st_uid != os.getuid() or info.st_mode & 0o077: - _fail('Native verifier output must be a current private directory.') - finally: os.close(check) - for name, raw in sorted(sources.items()): _write(source, name, raw) - if template is not None: - _write(source, BOOTSTRAP.name, bootstrap) - _write(directory, 'native-job-template.json', template) - os.fsync(source); os.fsync(directory); os.fsync(parent) - finally: - for descriptor in (source, directory, parent): - if descriptor is not None: os.close(descriptor) - return PreparedNative(stage, phase, spec, template, measured) diff --git a/project_producer_execution.py b/project_producer_execution.py deleted file mode 100644 index c8833909..00000000 --- a/project_producer_execution.py +++ /dev/null @@ -1,447 +0,0 @@ -"""Explicit current-host producers over inert canonical producer history. - -No owner is constructed by this adapter's constructor. Preparation is part of -Session's canonical foreground transaction; worker launch requires its confirmed -acknowledgement and is never inferred from a saved receipt or imported history. -""" -import copy -import json -import threading -import uuid - -from access import AccessError, current_context -from image_sources import ImageSources -from project_producers import (FAMILIES, TABLES, ProjectProducers, _capture_job, - _CapturedEvidence, _composed, _declarations, _referenced_artifacts, decode_records, - identity, shape) -from workbench import WorkbenchError -from project_session import session_record, session_records - -KINDS = {'generation_history':'generation', 'grounded_history':'grounded', - 'caption_proposal_history':'caption', 'text_proposal_history':'text_proposal'} -JOB_KINDS = {'generation_history':'synthetic', 'grounded_history':'grounded', - 'caption_proposal_history':'caption', 'text_proposal_history':'text_classification'} -FINISH = {'generation_history':'synthetic.finish', 'grounded_history':'grounded.finish', - 'caption_proposal_history':'caption.finish', 'text_proposal_history':'text_classification.finish'} -ACTIONS = frozenset(('start','resume','review','decide','cancel')) -OPERATIONS = frozenset('producers.'+value for value in ACTIONS) - - -def validate_operation_result(operation, target, result, records): - if operation not in OPERATIONS: - return False - shape(result, {'format','family','origin_catalog_id','producer_id','action'}) - if (result['format'] != 'project_producer_action_v1' or result['family'] not in FAMILIES - or result['action'] not in ACTIONS or operation != 'producers.'+result['action']): - raise WorkbenchError('Invalid retained producer action.') - if ((result['action']=='resume' and result['family']!='generation_history') - or (result['action']=='review' and result['family']!='grounded_history') - or (result['action']=='decide' and result['family'] not in ('caption_proposal_history','text_proposal_history'))): - raise WorkbenchError('Producer action does not belong to this finite family.') - identity(result['origin_catalog_id']);identity(result['producer_id']) - if target != result['producer_id'] and not (result['action']=='start' and target is None): - raise WorkbenchError('Producer action target differs.') - if not any(r['family']==result['family'] and r['id']==result['origin_catalog_id']+'.'+result['producer_id'] for r in records): - raise WorkbenchError('Producer action has no retained scientific history.') - return True - - -class _LiveContext: - def __init__(self, adapter): - self.adapter = adapter - self.access = adapter.runtime_access - self.project_execution = adapter.execution - def __getattr__(self, name): - return getattr(self.adapter.data.context, name) - - -class ProjectProducerExecution: - def __init__(self, session, data, archive, runtime_access=None, *, execution=None): - self.session, self.db, self.data, self.archive = session, session.db, data, archive - self.runtime_access = runtime_access or session.runtime_access - self.execution = execution or self - self._owners = {} - self._custody_lock = threading.RLock() - self._journaled = set() - self._journal_observations = {} - self._dirty = {family:set() for family in FAMILIES} - self._runtime_data = None - self._fenced = False - - def _family(self, family): - if family not in FAMILIES: - raise WorkbenchError('Unsupported project producer family.') - return family - - def _owner(self, family): - self._family(family);self.session.check_current() - if self._fenced: - raise WorkbenchError('Current producer custody is uncertain. Reopen for inert inspection.', 'outcome_unknown', 409) - self._refuse_unknown_provider() - if family not in self._owners: - # Imported science retains its physical ordering. A fresh local - # authority table must allocate beyond those observed ordinals. - table=TABLES[family] - observed=max((r['document']['ordinal'] for r in session_records(self.session, family) - if r['family']==family and r['document']['origin_catalog_id']==self.db.dataset_id),default=0) - current=self.db.execute('SELECT COALESCE(max(ordinal),0) FROM '+table).fetchone()[0] - maximum=max(observed,current) - self.db.execute('SELECT setval(pg_get_serial_sequence(%s,%s),%s,%s)',(table,'ordinal',max(1,maximum),maximum>0)) - # The calling action has checked current host authority. Never restore - # archived jobs into these local authority tables. - context = _LiveContext(self) - workbench = copy.copy(self.data.workbench) - workbench.dataset = context - if family == 'generation_history': - from synthetic import Jobs - from image_generation import ImageRequests - context.image_requests = ImageRequests(self.runtime_access) - context.workbench = workbench - image_context = _LiveContext(self) - image_context.access = self.data._authority - image_context.workbench = workbench - images = ImageSources(image_context) - def add(body, generation=None): - if generation is None: - raise WorkbenchError('Current producer context only accepts admitted output.') - with self.db.lock, self.db.transaction(): - key = 'generated-image-'+uuid.uuid4().hex - with self.data.runtime_mutation('data.runtime_generated_image', key): - self._runtime_data = ('data.runtime_generated_image', key) - return images.add(body, generation=generation) - context.add = add - owner = Jobs(context) - context.generation_jobs = owner - image_context.generation_jobs = owner - else: - if family == 'grounded_history': - from grounded_candidates import Proposals as Owner - elif family == 'caption_proposal_history': - from caption_proposals import CaptionProposals as Owner - else: - from text_classification_proposals import TextClassificationProposals as Owner - owner = Owner(workbench) - self._owners[family] = owner - return self._owners[family] - - def _mark(self, family, producer_id): - identity(producer_id) - if not self.db.in_transaction: - raise RuntimeError('Producer writes require their owned SQL transaction.') - self._dirty[family].add(producer_id) - - def mark_generation(self, producer_id):self._mark('generation_history', producer_id) - def mark_grounded(self, producer_id):self._mark('grounded_history', producer_id) - def mark_caption(self, producer_id):self._mark('caption_proposal_history', producer_id) - def mark_text_proposal(self, producer_id):self._mark('text_proposal_history', producer_id) - - def _proof(self, family, job): - row = self.db.execute('SELECT * FROM access_admissions WHERE id=%s', (job.get('admission_id'),)).fetchone() - if row is None: - raise AccessError('Current local producer admission is unavailable.') - row = dict(row) - if (row['catalog_id'] != self.db.dataset_id or row['kind'] != JOB_KINDS[family] - or row['job_id'] != job['id'] or row['request_digest'] != job.get('request_digest')): - raise AccessError('Current producer admission differs from its retained request.') - context = current_context() - if context is None: - raise AccessError('Producer observation requires current authority.') - if context.mode == 'job': - self.runtime_access.require_job(JOB_KINDS[family], job['id'], job['admission_id'], job['request_digest']) - self.runtime_access.require('edit', FINISH[family], job['id']) - elif context.mode == 'system': - # Only a constructed local owner can reconcile its own table. - self.runtime_access.require('cancel', JOB_KINDS[family]+'.reconcile', job['id']) - else: - self.runtime_access.require('inspect', 'producers.observe', job['id']) - - def capture_dirty(self, before_records): - result = [] - if self._runtime_data is not None: - operation, key = self._runtime_data - result.extend(self.data.capture_runtime_changes(before_records, operation=operation, key=key)) - if not any(self._dirty.values()): - return result - capture = copy.copy(self.archive) - capture._origin = self.db.dataset_id - capture._artifacts = {} - capture._pending_payloads = {} - for family, ids in self._dirty.items(): - for producer_id in sorted(ids): - row = self.db.execute('SELECT data,ordinal FROM '+TABLES[family]+' WHERE id=%s', (producer_id,)).fetchone() - if row is None: - raise WorkbenchError('Current producer row disappeared.') - job = json.loads(row[0]);self._proof(family, job) - entries = [] - if family == 'generation_history': - entries = [(json.loads(raw),order) for raw,order in self.db.execute( - 'SELECT data,storage_order FROM generation_entries WHERE job_id=%s ORDER BY ordinal',(producer_id,))] - record = _capture_job(capture, family, job, row[1], entries) - # Keep all observed entry facts across explicit continuation and - # deletion; the current view remains the final observation. - previous = next((r for r in before_records if r['family']==family and r['id']==record['id']),None) - if previous is not None and family == 'generation_history': - old = {v['entry']['id']:v for v in previous['document']['entries']} - for value in record['document']['entries']: - if value['entry']['id'] in old: - history = copy.deepcopy(old[value['entry']['id']]['history']) - payload_history=copy.deepcopy(old[value['entry']['id']].get('history_payloads', - [old[value['entry']['id']]['payloads'] for _ in history])) - if history[-1] != value['entry']: - history.append(copy.deepcopy(value['entry'])) - payload_history.append(copy.deepcopy(value['payloads'])) - value['history'] = history - value['history_payloads'] = payload_history - result.append(record) - result.extend(dict(family='project_artifact',id=sha,document=decl) for sha,decl in capture._artifacts.items()) - decode_records(_composed(before_records,result), artifacts=_CapturedEvidence(capture)) - for sha,raw in capture._pending_payloads.items(): - self.session.artifacts.publish_bytes(raw,capture._artifacts[sha],maximum_bytes=32*1024*1024) - return result - - def outcome(self, outcome): - if outcome not in ('committed','rolled_back','unknown'): - raise ValueError('Invalid producer transaction outcome.') - for values in self._dirty.values():values.clear() - if self._runtime_data is not None: - self.data.finish_runtime_mutation() - self._runtime_data = None - if outcome == 'unknown' or not self.session.available: - self._fenced = True - # Unknown acknowledgement fences authority. It never authorizes an - # unacknowledged cancellation signal to a current worker. - if outcome == 'committed': - from project_session import session_records - records = session_records(self.session, *FAMILIES, 'project_artifact') - self.archive._records = copy.deepcopy([r for r in records if r['family'] in FAMILIES]) - declarations = _declarations(records) - self.archive._artifacts = {sha:declarations[sha] for sha in _referenced_artifacts(self.archive._records)} - - def _ack(self, family, producer_id, action): - return dict(format='project_producer_action_v1',family=family, - origin_catalog_id=self.db.dataset_id,producer_id=producer_id,action=action) - - def _mutate(self, action, family, producer_id, body, checkpoint, key, invoke, *, scope='edit'): - return self.session.mutate('producers.'+action,producer_id,dict(family=family,document=body),checkpoint,key, - invoke,lambda result,before:dict(records=[],result=result),scope=scope) - - def _dispatch_prepared(self, family, owner, job): - try: - # Host-local custody must be durable before any worker can perform - # capability discovery or inference. Saved project receipts cannot - # recreate this registration or launch a worker. - self.execution.register_producer(family,job['id'],job['admission_id'],job['request_digest']) - self._journaled.add((family,job['id'])) - self.execution.producer_effect_intent(family,job['id']) - with self._custody_lock: - owner._project_worker_id=job['id'] - owner._launch(job) - except BaseException: - self._fenced=True - self.session.available=False - raise - - def _settle_drained(self): - if not self.session.available: - return - records=self.session.snapshot['records'] - for family,owner in self._owners.items(): - producer_id=getattr(owner,'_project_worker_id',None) - identity_key=(family,producer_id) - if identity_key not in self._journaled or owner.worker is not None and owner.worker.is_alive(): - continue - doc=next((r['document'] for r in records if r['family']==family and r['id']==self.db.dataset_id+'.'+producer_id),None) - if doc is None or doc['job']['status'] in ('preparing','generating','stopping'): - continue - job=doc['job'];outcome=job.get('provider_outcome') - entries=[v['entry'] for v in doc.get('entries',[])] - batches=[v['batch'] for v in doc.get('prompt_batches',[])] - if (outcome=='unknown' or any(e.get('provider_outcome')=='unknown' for e in entries) - or any(b['status']=='requesting' for b in batches)): - outcome='unknown' - elif (outcome=='result_received' or any(e.get('provider_outcome')=='result_received' for e in entries) - or any(b['response_sha256'] is not None for b in batches)): - outcome='result_received' - else: - # Every effectful request is preceded by canonical uncertainty; - # a terminal job with no such request is known not admitted. - outcome='not_admitted' - observation=(outcome,True,self.session.summary['checkpoint']) - if self._journal_observations.get(identity_key)!=observation: - self.execution.update_producer_outcome(family,producer_id,outcome,True) - self._journal_observations[identity_key]=observation - if outcome!='unknown':self._journaled.discard(identity_key) - - def start(self, family, body, expected_checkpoint, key): - self._family(family) - if family == 'generation_history': - shape(body, {'server_url','model','prompt','count','strategy','session_id'}, - {'width','height','seed','protocol','profile','prompt_url','prompt_model','book_id','split'}) - self.runtime_access.require('execute','producers.start',owner_only=True) - prepared = [] - def invoke(): - requested = body.get('request_id') if type(body) is dict else None - if requested is not None and session_record(self.session, family,self.db.dataset_id+'.'+requested) is not None: - if self.db.execute('SELECT id FROM '+TABLES[family]+' WHERE id=%s',(requested,)).fetchone() is None: - raise WorkbenchError('A retained producer identity cannot acquire current admission. Start with a new identity.','unavailable',409) - owner = self._owner(family) - job, launch = owner._prepare_start(body) - if launch:prepared.append((owner,copy.deepcopy(job))) - return self._ack(family,job['id'],'start') - with self.session.access.lock, self.session.lock, self.db.lock: - self._settle_drained() - result = self._mutate('start',family,None,body,expected_checkpoint,key,invoke,scope='execute') - # Replays never invoke preparation. Unknown/failed commits never reach - # this line. Hold custody locks until the local worker is installed. - for owner,job in prepared: - self._dispatch_prepared(family,owner,job) - return result - - def resume_generation(self, producer_id, expected_checkpoint, key): - identity(producer_id) - self.runtime_access.require('execute','producers.resume',owner_only=True) - prepared=[] - def invoke(): - self._refuse_unknown_provider() - owner=self._owners.get('generation_history') - if owner is None: - raise WorkbenchError('Only a current local generation queue can continue. Imported history is inert.','unavailable',409) - job,launch=owner._prepare_resume(producer_id) - if launch:prepared.append((owner,copy.deepcopy(job))) - return self._ack('generation_history',producer_id,'resume') - with self.session.access.lock,self.session.lock,self.db.lock: - self._settle_drained() - result=self._mutate('resume','generation_history',producer_id,{},expected_checkpoint,key,invoke,scope='execute') - for owner,job in prepared: - self._dispatch_prepared('generation_history',owner,job) - return result - - def _decision(self, action, family, producer_id, body, checkpoint, key): - self._family(family);identity(producer_id) - self.runtime_access.require('edit','producers.'+action,producer_id) - def invoke(): - owner=self._owners.get(family) - if owner is None: - raise WorkbenchError('Imported producer history cannot be applied as current authority.','unavailable',409) - operation={'grounded_history':'data.runtime_grounded_text','caption_proposal_history':'data.runtime_caption', - 'text_proposal_history':'data.runtime_text_classification'}[family] - with self.data.runtime_mutation(operation,key): - self._runtime_data=(operation,key) - if action=='review':owner.review(producer_id,body) - else:owner.decide(producer_id,body) - return self._ack(family,producer_id,action) - return self._mutate(action,family,producer_id,body,checkpoint,key,invoke) - - def review_grounded(self, producer_id, body, expected_checkpoint, key): - return self._decision('review','grounded_history',producer_id,body,expected_checkpoint,key) - - def decide(self, family, producer_id, body, expected_checkpoint, key): - if family not in ('caption_proposal_history','text_proposal_history'): - raise WorkbenchError('Only caption/classification proposals accept a decision.') - return self._decision('decide',family,producer_id,body,expected_checkpoint,key) - - def cancel(self, family, producer_id, expected_checkpoint, key, *, drain_timeout=10): - self._family(family);identity(producer_id) - self.runtime_access.require('cancel','producers.cancel',producer_id) - if getattr(self.db.lock,'owned_by_current_thread',False): - raise WorkbenchError('Cancellation must signal and drain outside project command locks.','producer_active',409) - prepared=[] - def invoke(): - owner=self._owners.get(family) - if owner is None: - raise WorkbenchError('No current local producer custody exists for this history.','unavailable',409) - _result,pending=owner._prepare_cancel(producer_id) - if pending is not None:prepared.append((owner,pending)) - return self._ack(family,producer_id,'cancel') - result=self._mutate('cancel',family,producer_id,{},expected_checkpoint,key,invoke,scope='cancel') - # A replay never invokes preparation. Failure or uncertain COMMIT never - # reaches this point, and therefore never stops transport or a worker. - for owner,pending in prepared: - with self._custody_lock: - signalled=owner._signal_cancel(pending) - # The image transport owner audits through host/SQL locks. Never - # hold the custody mutex while entering those ordered guards. - if signalled and family=='generation_history':owner._cancel_transport(pending) - worker=pending[0] - if worker is not None: - worker.join(drain_timeout) - if worker.is_alive(): - raise WorkbenchError('Cancellation intent is saved; current worker has not drained.','producer_draining',409) - return result - - def _refuse_unknown_provider(self): - for family in self._owners: - for raw, in self.db.execute('SELECT data FROM '+TABLES[family]): - job=json.loads(raw) - if (job.get('provider_outcome')=='unknown' - or any(v['status']=='requesting' for v in job.get('prompt_batches',[]))): - raise WorkbenchError('Downstream producer outcome is unknown; local drainage is not provider cessation.','outcome_unknown',409) - if family=='generation_history': - if any(json.loads(row[0]).get('provider_outcome')=='unknown' for row in self.db.execute('SELECT data FROM generation_entries WHERE job_id=%s',(job['id'],))): - raise WorkbenchError('Image provider outcome is unknown.','outcome_unknown',409) - - def abandon_pending(self): - if not getattr(self.execution,'_reconstructing',False): - raise RuntimeError('Pending producer facts can be abandoned only by explicit current reconstruction.') - for owner in self._owners.values(): - if owner.worker is not None and owner.worker.is_alive(): - raise WorkbenchError('Actual local producer custody has not drained.','producer_active',409) - self._refuse_unknown_provider() - for values in self._dirty.values():values.clear() - self.data.finish_runtime_mutation() - self._runtime_data=None - self._fenced=False - - def assert_quiescent(self): - if not self.has_local_custody: - return - self._settle_drained() - for family,owner in self._owners.items(): - if owner.worker is not None and owner.worker.is_alive(): - raise WorkbenchError('Stop and drain the current producer before changing project.','producer_active',409) - self._refuse_unknown_provider() - for raw, in self.db.execute('SELECT data FROM '+TABLES[family]): - job=json.loads(raw) - if job['status'] in ('preparing','generating','stopping') or job.get('provider_outcome')=='unknown': - raise WorkbenchError('Current producer is active or its provider outcome is unknown.','producer_active',409) - - def close(self): - # Project lifecycle refuses active/unknown custody; it never turns Close - # into an implicit cancellation or recovery instruction. - self.assert_quiescent() - - @property - def has_local_custody(self): - return bool(self._owners) - - def shutdown(self): - """Explicit application shutdown drains only actual constructed owners. - - Historical rows, process IDs and endpoints never select a custodian. - Shutdown is separate from ordinary project Close, which refuses work. - """ - if getattr(self.db.lock,'owned_by_current_thread',self.db.lock.depth) or self.db.in_transaction: - raise WorkbenchError('Producer shutdown must drain outside project command locks.','producer_active',409) - for owner in self._owners.values(): - with self.runtime_access._reconcile():owner.close() - with self.runtime_access._reconcile():self._settle_drained() - - def status(self, *, offset=0, limit=40): - if type(offset) is not int or not 0<=offset<=1_000_000 or type(limit) is not int or not 1<=limit<=40: - raise WorkbenchError('Invalid current producer health page.') - with self.session.access.lock,self.session.lock,self.db.lock: - self.session.access.require('inspect','producers.health') - self.session.check_current() - self._settle_drained() - items=[] - for family,owner in self._owners.items(): - for raw, in self.db.execute('SELECT data FROM '+TABLES[family]+' ORDER BY ordinal'): - job=json.loads(raw) - observed=job.get('provider_outcome') - if any(v['status']=='requesting' for v in job.get('prompt_batches',[])):observed='unknown' - if family=='generation_history' and any(json.loads(row[0]).get('provider_outcome')=='unknown' for row in self.db.execute('SELECT data FROM generation_entries WHERE job_id=%s',(job['id'],))):observed='unknown' - items.append(dict(family=family,producer_id=job['id'],status=job['status'], - provider_outcome=observed,worker_alive=bool(owner.worker - and owner.worker.is_alive() and getattr(owner,'_project_worker_id',None)==job['id']))) - return dict(format='project_producer_health_v1',items=items[offset:offset+limit],total=len(items), - offset=offset,limit=limit,fenced=bool(self._fenced or self.runtime_access.catalog_id==self.session.access.catalog_id or any(v['provider_outcome']=='unknown' for v in items))) diff --git a/project_producers.py b/project_producers.py deleted file mode 100644 index 8e052b34..00000000 --- a/project_producers.py +++ /dev/null @@ -1,1247 +0,0 @@ -"""Inert, origin-scoped producer observations and exact evidence payloads. - -No producer constructor, admission, worker, cancellation or resume API enters this -owner. Four closed codecs preserve the scientific observations their existing -owners validate. Local transport configuration and admission envelopes have an -explicit exclusion; unknown fields fail instead of disappearing during export. -""" -import base64 -import copy -from datetime import datetime -import hashlib -import json -import re - -from access import authorized -import caption_proposals -import grounded_candidates -import image_generation -import pumas_operations as pumas -import synthetic -import text_classification_proposals -from workbench import WorkbenchError, encode, text_value, validate_annotation - -FAMILIES = { - 'generation_history': 'project_generation_history_v1', - 'grounded_history': 'project_grounded_history_v1', - 'caption_proposal_history': 'project_caption_proposal_history_v1', - 'text_proposal_history': 'project_text_proposal_history_v1', -} -TABLES = {'generation_history': 'generation_jobs', 'grounded_history': 'grounded_jobs', - 'caption_proposal_history': 'caption_proposals', 'text_proposal_history': 'text_classification_proposals'} -ID = re.compile(r'^[a-f0-9]{32}$') -SHA = re.compile(r'^[a-f0-9]{64}$') -MAX_RECORDS = 100_000 -MAX_RESPONSE = 256 * 1024 -LOCAL_JOB_FIELDS = {'admission_id', 'request_digest'} -LOCAL_CONFIG_FIELDS = {'server_url', 'requested_server_url', 'prompt_url'} -AUTHORITY_FIELDS = {'token', 'token_sha256', 'access_token', 'refresh_token', 'api_key', 'password', - 'authorization', 'cookie', 'set-cookie', 'credentials', 'admission_id', 'grant_id'} -EVIDENCE_FIELDS = {'response_sha256', 'capability_observation', 'producer_contract_source', 'canonical_request', - 'provider_outcome', 'provider_error_code', 'provider_http_status', 'build_observation', 'canonical_request_sha256'} -JOB_COMMON = {'schema_version', 'id', 'revision', 'status', 'error', 'created_at', 'updated_at', - 'source', 'config', 'system_prompt', 'prompt_version', 'prompt_sha256', - 'canonical_request_sha256', 'response_sha256', 'verification'} -JOB_OPTIONAL = {'reported_model', 'catalog_qualification', 'listed_models'} | EVIDENCE_FIELDS -PAYLOAD_FIELDS = {'raw_response_base64': 'raw_response', 'canonical_request': 'canonical_request', - 'input_image_base64': 'input_image'} -ENTRY_REQUIRED = {'id', 'job_id', 'ordinal', 'prompt', 'status', 'sample_id', 'error', 'model', - 'width', 'height', 'requested_seed'} -ENTRY_OPTIONAL = {'size', 'metadata', 'deleted_at', 'request_id', 'provider_outcome', 'attempt_evidence'} - - -def fail(message, code='invalid', status=400): - raise WorkbenchError(message, code, status) - - -def shape(value, required, optional=(), name='producer'): - if type(value) is not dict or not set(required) <= value.keys() or value.keys() - set(required) - set(optional): - fail('Unsupported ' + name + ' fields.') - - -def identity(value): - if type(value) is not str or not ID.fullmatch(value): - fail('Invalid producer historical identity.') - return value - - -def digest(value): - if type(value) is not str or not SHA.fullmatch(value): - fail('Invalid producer digest.') - return value - - -def integer(value, minimum=0, maximum=2**53-1): - if type(value) is not int or not minimum <= value <= maximum: - fail('Invalid producer count/revision.') - return value - - -def date(value): - try: - if type(value) is not str or len(value) > 80: - raise ValueError() - parsed = datetime.fromisoformat(value) - if parsed.utcoffset() is None: - raise ValueError() - return parsed - except ValueError: - fail('Invalid producer observation timestamp.') - - -def _safe(value, depth=0): - if depth > 64: - fail('Producer evidence exceeds its nesting bound.') - if type(value) is dict: - if any(type(key) is not str or key.lower() in AUTHORITY_FIELDS for key in value): - fail('Producer evidence contains live credential or admission material.') - for child in value.values(): - _safe(child, depth+1) - elif type(value) is list: - for child in value: - _safe(child, depth+1) - elif type(value) not in (str, int, float, bool, type(None)): - fail('Producer evidence is not finite JSON.') - try: - if depth == 0: - json.dumps(value, allow_nan=False, ensure_ascii=False).encode('utf-8') - except (ValueError, UnicodeError, OverflowError): - fail('Producer evidence contains invalid Unicode or nonfinite values.') - - -def _sha(raw): - return hashlib.sha256(raw).hexdigest() - - -def _bytes(value, maximum): - try: - if type(value) is not str or len(value) > 4*((maximum+2)//3): - raise ValueError() - raw = base64.b64decode(value, validate=True) - if len(raw) > maximum or base64.b64encode(raw).decode('ascii') != value: - raise ValueError() - return raw - except ValueError: - fail('Producer payload requires bounded exact base64 bytes.') - - -def _observations(job): - for field in ('canonical_request_sha256', 'response_sha256'): - if job.get(field) is not None: - digest(job[field]) - if 'capability_observation' in job: - observed = job['capability_observation'] - shape(observed, {'capabilities', 'observed_sha256'}, name='capability observation') - # The original wire digest is retained independently: the manifest is an - # already-decoded observation and cannot recreate its original spacing. - pumas.validate_manifest(encode(observed['capabilities']).encode()) - digest(observed['observed_sha256']) - if observed['capabilities']['model'] != job['config']['model']: - fail('Producer capability observation belongs to another model.') - if 'producer_contract_source' in job: - source = job['producer_contract_source'] - if type(source) is not str or not re.fullmatch('[a-f0-9]{40}', source): - fail('Invalid producer contract source identity.') - if 'provider_outcome' in job and job['provider_outcome'] not in ('not_admitted', 'unknown', 'result_received'): - fail('Unsupported historical provider outcome.') - if job.get('provider_http_status') is not None: - integer(job['provider_http_status'], 100, 599) - if job.get('provider_error_code') is not None: - text_value(job['provider_error_code'], 'Provider error code', 200) - if 'build_observation' in job: - import pumas_gateway_descriptor as descriptor - build = job['build_observation'] - # Build observation interpretation stays with its existing owner. - shape(build, {'advertisement', 'observed_sha256'}, name='retained build observation') - descriptor.decode(encode(build['advertisement']).encode()) - digest(build['observed_sha256']) - - -def _config(family, config): - if family == 'generation_history': - required = {'model', 'prompt', 'width', 'height', 'count', 'strategy'} - optional = {'seed', 'protocol', 'profile', 'prompt_model', 'size'} - else: - required = {'model', 'instruction', 'seed'} - optional = {'protocol', 'profile'} - if family != 'grounded_history': - required.add('provider') - if family == 'grounded_history': - required.add('count') - if family == 'text_proposal_history': - required |= {'labels', 'requested_model'} - shape(config, required, optional, 'producer configuration') - pumas.alias(config['model']) - mode = pumas.configuration(config, image=family == 'generation_history') - if (family == 'generation_history' and config.get('seed') is not None - or family != 'generation_history' and not mode): - integer(config.get('seed'), 0, 2**32-1) - if family == 'generation_history': - dimensions = synthetic.saved_dimensions(config) - if (dimensions['width'], dimensions['height']) != (config['width'], config['height']): - fail('Saved producer geometry differs.') - integer(config['count'], 1, 10000) - text_value(config['prompt'], 'Generation prompt', 4000) - if config['strategy'] not in ('varied', 'repeat') or mode and config['strategy'] != 'repeat': - fail('Unsupported saved prompt strategy.') - if config['strategy'] == 'varied': - pumas.alias(config.get('prompt_model')) - else: - text_value(config['instruction'], 'Producer guidance', 2000) - if family == 'grounded_history': - integer(config['count'], 1, 10) - if family == 'text_proposal_history': - text_classification_proposals.validate_labels(config['labels']) - text_value(config['requested_model'], 'Requested model identity', 200) - if family != 'grounded_history' and config['provider'] not in ( - 'pumas_chat_compatible', 'pumas_image_to_text', pumas.PROTOCOL): - fail('Unsupported producer identity.') - - -def _entry(entry, job): - shape(entry, ENTRY_REQUIRED, ENTRY_OPTIONAL, 'generation entry') - identity(entry['id']); identity(entry['job_id']) - if entry['job_id'] != job['id'] or entry['model'] != job['config']['model']: - fail('Generation entry belongs to another job/model.') - integer(entry['ordinal'], 0, job['config']['count']-1) - dimensions = synthetic.saved_dimensions(entry) - if (dimensions['width'], dimensions['height']) != (job['config']['width'], job['config']['height']): - fail('Generation entry geometry differs from its job.') - text_value(entry['prompt'], 'Saved generation prompt', 4000) - text_value(entry['error'], 'Generation error', 800, empty=True) - if entry['status'] not in ('pending', 'generating', 'completed', 'failed', 'deleted'): - fail('Unsupported saved generation entry status.') - if entry['sample_id'] is not None: - identity(entry['sample_id']) - if ((entry['status'] == 'completed') != (entry['sample_id'] is not None)): - fail('Generation entry source/deletion state differs.') - expected_seed = ((job['config']['seed'] + entry['ordinal']) % 2**32 - if job['config'].get('seed') is not None else None) - if entry['requested_seed'] != expected_seed: - fail('Generation entry seed differs from its saved ordinal.') - if 'deleted_at' in entry: - date(entry['deleted_at']) - if 'request_id' in entry: - identity(entry['request_id']) - if 'provider_outcome' in entry and entry['provider_outcome'] not in ('not_admitted', 'unknown', 'result_received'): - fail('Unsupported generation provider outcome.') - for field in ('metadata', 'attempt_evidence'): - if field in entry: - value = entry[field] - optional = {'seed', 'steps', 'guidance', 'duration_seconds', 'memory_policy', 'protocol'} | EVIDENCE_FIELDS - shape(value, (), optional if field == 'metadata' else EVIDENCE_FIELDS, 'generation result evidence') - for number in ('seed', 'steps', 'guidance', 'duration_seconds'): - if number in value and type(value[number]) not in (int, float): - fail('Generation numeric observation differs from its owner.') - if 'memory_policy' in value and value['memory_policy'] not in ('sequential_cpu_offload', 'model_cpu_offload', 'gpu'): - fail('Unsupported generation memory policy observation.') - if 'protocol' in value and value['protocol'] != pumas.PROTOCOL: - fail('Unsupported generation protocol observation.') - _observations(dict(value, config=job['config'])) - _safe(value) - _safe(entry) - - -def _validate_job_value(family, job): - if family == 'generation_history': - shape(job, {'id', 'config', 'meta', 'status', 'error', 'completed'}, EVIDENCE_FIELDS, - 'generation job') - from image_sources import metadata - if metadata(job['meta']) != job['meta']: - fail('Generation source metadata differs from its owner.') - _config(family, job['config']) - integer(job['completed'], 0, job['config']['count']) - states = ('preparing', 'generating', 'stopping', 'completed', 'failed', 'cancelled', 'interrupted') - else: - extra = {'candidates', 'raw_response_text_available'} if family == 'grounded_history' else {'intent_sha256', 'annotation', 'application'} - if family == 'caption_proposal_history': - extra.add('input_image') - if family == 'text_proposal_history': - extra |= {'labels_sha256', 'source_text_sha256'} - shape(job, JOB_COMMON | extra, JOB_OPTIONAL - {'canonical_request'}, 'proposal history') - if job['schema_version'] != 1: - fail('Unsupported producer schema version.', 'unsupported', 422) - _config(family, job['config']) - integer(job['revision'], 1) - if date(job['updated_at']) < date(job['created_at']): - fail('Producer update precedes creation.') - from project_data import validate_record_snapshot - validate_record_snapshot(job['source']) - expected_kind = 'image' if family == 'caption_proposal_history' else 'text' - if job['source']['kind'] != expected_kind: - fail('Captured source has the wrong producer modality.') - text_value(job['system_prompt'], 'Captured system prompt', 20000) - module = {'grounded_history': grounded_candidates, 'caption_proposal_history': caption_proposals, 'text_proposal_history': text_classification_proposals}[family] - if job['prompt_version'] != module.PROMPT_VERSION or job['system_prompt'] != module.SYSTEM_PROMPT: - fail('Unsupported historical producer prompt contract.', 'unsupported', 422) - if _sha(job['system_prompt'].encode()) != job['prompt_sha256']: - fail('Captured system prompt digest differs.') - digest(job['canonical_request_sha256']) - if job['response_sha256'] is not None: - digest(job['response_sha256']) - if family == 'text_proposal_history': - if _sha(encode(job['config']['labels']).encode()) != job['labels_sha256'] or _sha(job['source']['text'].encode()) != job['source_text_sha256']: - fail('Frozen labels or source text digest differs.') - if family != 'grounded_history': - digest(job['intent_sha256']) - text_value(job['verification'], 'Producer verification qualification', 2000) - if job.get('reported_model') is not None: - text_value(job['reported_model'], 'Reported model', 200) - if 'catalog_qualification' in job: - text_value(job['catalog_qualification'], 'Model catalog qualification', 2000) - if 'listed_models' in job: - if type(job['listed_models']) is not list or len(job['listed_models']) > 10000: - fail('Invalid observed serving model catalog.') - for model in job['listed_models']: - text_value(model, 'Observed serving model', 256) - if family == 'grounded_history': - if type(job['raw_response_text_available']) is not bool: - fail('Invalid exact-response text-view observation.') - if job['source']['task'] != 'text_classification' or job['source']['review'] != 'human_reviewed' or job['source']['annotation'] is None: - fail('Grounded source lacks its captured human-reviewed class.') - if len(job['source']['text']) > grounded_candidates.MAX_SOURCE: - fail('Captured grounded source exceeds its owner bound.') - _candidates(job) - elif job['application'] is not None: - shape(job['application'], {'record_id', 'revision', 'source_revision'}, name='proposal application') - application = job['application'] - if (application['record_id'] != job['source']['id'] or application['revision'] != job['source']['revision']+1 - or application['source_revision'] != job['source']['source_revision'] or job['status'] != 'applied'): - fail('Proposal application differs from its captured revisions.') - elif job['status'] == 'applied': - fail('Applied producer observation lacks its application facts.') - if family == 'caption_proposal_history': - shape(job['input_image'], {'mime', 'size', 'bytes', 'sha256', 'preparation'}, name='prepared image') - image = job['input_image'] - if image['mime'] != 'image/jpeg' or type(image['size']) is not list or len(image['size']) != 2: - fail('Invalid prepared image format.') - for size in image['size']: - integer(size, 1, 1600) - integer(image['bytes'], 1, caption_proposals.MAX_IMAGE); digest(image['sha256']) - if image['preparation'] != 'oriented canonical RGB; thumbnail max 1600; JPEG quality 95': - fail('Unsupported prepared image procedure.', 'unsupported', 422) - if job['annotation'] is not None: - validate_annotation('image_caption', job['annotation'], job['source']) - if family == 'text_proposal_history' and job['annotation'] is not None: - if job['annotation'] not in [{'label': label} for label in job['config']['labels']]: - fail('Saved target is outside its frozen label set.') - states = ('preparing', 'generating', 'stopping', 'completed', 'failed', 'cancelled', 'interrupted', 'applied', 'rejected') - if family == 'text_proposal_history': - states += ('abstained',) - identity(job['id']) - if job['status'] not in states: - fail('Unsupported producer lifecycle observation.') - text_value(job['error'], 'Producer error observation', 800, empty=True) - _observations(job); _safe(job) - - -def _job(family, job): - try: - _validate_job_value(family, job) - except WorkbenchError: - raise - except (ValueError, TypeError, KeyError, AttributeError, OverflowError): - fail('Invalid retained producer value.') - - -def _candidates(job): - values = job['candidates'] - if type(values) is not list or len(values) > job['config']['count']: - fail('Invalid retained grounded candidate list.') - if job['status'] == 'completed' and len(values) != job['config']['count']: - fail('Completed grounded output is incomplete.') - seen, texts = set(), {job['source']['text']} - for candidate in values: - shape(candidate, {'id', 'text', 'label', 'evidence', 'status', 'record_id', 'review_note'}, name='grounded candidate') - identity(candidate['id']) - if candidate['id'] in seen: - fail('Duplicate grounded candidate identity.') - seen.add(candidate['id']) - grounded_candidates.validate_candidate_values([candidate], job['source'], existing_texts=texts) - texts.add(candidate['text']) - if candidate['status'] not in ('pending_review', 'admitted', 'rejected'): - fail('Invalid grounded review disposition.') - if candidate['record_id'] is not None: - identity(candidate['record_id']) - if (candidate['status'] == 'admitted') != (candidate['record_id'] is not None): - fail('Grounded admission identity differs from its disposition.') - text_value(candidate['review_note'], 'Grounded review note', 1000, empty=True) - - -def _declarations(records): - result = {} - for envelope in records: - if envelope.get('family') == 'project_artifact': - from project_artifacts import validate_declaration - declaration = validate_declaration(envelope['document']) - if envelope['id'] != declaration['sha256'] or declaration['sha256'] in result: - fail('Invalid duplicate producer artifact declaration.') - result[declaration['sha256']] = declaration - return result - - -def _edge(edge, declarations, role): - shape(edge, {'artifact', 'media_type', 'kind', 'role', 'preservation', 'required_for'}, name='producer artifact edge') - shape(edge['artifact'], {'namespace', 'sha256'}, name='producer artifact identity') - identity(edge['artifact']['namespace']); digest(edge['artifact']['sha256']) - if edge['kind'] != 'producer_evidence' or edge['role'] != role or edge['preservation'] != 'unique' or edge['required_for'] != ['verify_producer']: - fail('Producer payload role or retention differs.') - expected_media = 'image/jpeg' if role == 'input_image' else 'application/octet-stream' if role == 'raw_response' else 'application/json' - if edge['media_type'] != expected_media: - fail('Producer payload media type differs from its role.') - declaration = declarations.get(edge['artifact']['sha256']) - if declaration is None: - fail('Producer payload declaration is missing.') - return declaration - - -def _payloads(value, declarations, roles): - shape(value, (), roles, 'producer payloads') - for role, edge in value.items(): - _edge(edge, declarations, role) - - -def decode_records(records, *, artifacts=None): - """Validate four fixed history families; absent payloads remain declared. - - With an artifact capability, every available payload is decoded by its - original owner. Missing bytes permit metadata inspection, never inference - or a new verified result. Corrupt available bytes fail closed. - """ - if type(records) is not list or len(records) > MAX_RECORDS or any(type(item) is not dict for item in records): - fail('Producer inventory exceeds its record bound.') - declarations = _declarations(records) - result = [] - seen, observed_order = set(), set() - for envelope in records: - family = envelope.get('family') - if family not in FAMILIES: - continue - shape(envelope, {'family', 'id', 'document'}, name='producer envelope') - doc = envelope['document'] - shape(doc, {'format', 'origin_catalog_id', 'ordinal', 'job', 'payloads', 'observation_integrity'} | ({'entries'} if family == 'generation_history' else set()), {'prompt_batches'} if family == 'generation_history' else (), name='producer document') - if doc['format'] != FAMILIES[family]: - fail('Unsupported producer document format.', 'unsupported', 422) - identity(doc['origin_catalog_id']); _job(family, doc['job']) - integer(doc['ordinal'], 1, 2**63-1) - order_key = (family, doc['origin_catalog_id'], doc['ordinal']) - if order_key in observed_order: - fail('Duplicate historical producer ordering.') - observed_order.add(order_key) - if doc['observation_integrity'] != _observation_integrity(doc['job']): - fail('Producer observation wire-integrity classification differs.') - if envelope['id'] != doc['origin_catalog_id'] + '.' + doc['job']['id'] or (family, envelope['id']) in seen: - fail('Producer origin/identity differs or repeats.') - seen.add((family, envelope['id'])) - roles = {'raw_response', 'canonical_request'} | ({'input_image'} if family == 'caption_proposal_history' else set()) - _payloads(doc['payloads'], declarations, roles) - if family != 'generation_history' and 'canonical_request' not in doc['payloads']: - fail('Producer canonical request declaration is missing.') - if doc['job'].get('response_sha256') is not None and 'raw_response' not in doc['payloads']: - fail('Producer response declaration is missing.') - if family == 'caption_proposal_history' and 'input_image' not in doc['payloads']: - fail('Prepared producer input declaration is missing.') - if family == 'generation_history': - _prompt_batches(doc,declarations) - if type(doc['entries']) is not list or len(doc['entries']) > doc['job']['config']['count']: - fail('Invalid generation queue closure.') - ordinals, identities, storage_orders = set(), set(), set() - for value in doc['entries']: - shape(value, {'entry', 'history', 'payloads', 'observation_integrity', 'storage_order'}, {'history_payloads'}, name='generation entry history') - integer(value['storage_order'], 1, 2**63-1) - if value['storage_order'] in storage_orders: - fail('Duplicate historical generation storage ordering.') - storage_orders.add(value['storage_order']) - if value['observation_integrity'] != _entry_integrity(value['entry']): - fail('Generation observation wire-integrity classification differs.') - _entry_history(value, doc['job']) - _entry(value['entry'], doc['job']) - ordinal, entry_id = value['entry']['ordinal'], value['entry']['id'] - if ordinal in ordinals or entry_id in identities: - fail('Duplicate generation queue entry.') - ordinals.add(ordinal); identities.add(entry_id) - _payloads(value['payloads'], declarations, {'attempt_request', 'result_request'}) - histories=value.get('history_payloads',[value['payloads'] for _ in value['history']]) - if type(histories) is not list or len(histories)!=len(value['history']) or histories[-1]!=value['payloads']: - fail('Generation evidence history differs from its observations.') - for entry,mapping in zip(value['history'],histories): - _payloads(mapping,declarations,{'attempt_request','result_request'}) - for field,role in (('attempt_evidence','attempt_request'),('metadata','result_request')): - sha=entry.get(field,{}).get('canonical_request_sha256') - if sha is not None and (role not in mapping or mapping[role]['artifact']['sha256']!=sha): - fail('Generation request declaration is missing or differs.') - if sorted(ordinals) != list(range(len(ordinals))): - fail('Generation queue ordinals have a gap.') - if doc['job']['completed'] != sum(value['entry']['status'] in ('completed', 'deleted') for value in doc['entries']): - fail('Generation completed count differs from its retained entries.') - if doc['job']['status'] == 'completed' and doc['job']['completed'] != doc['job']['config']['count']: - fail('Completed generation job lacks its complete queue.') - try: - synthetic.validate_saved_queue(doc['job'], [value['entry'] for value in doc['entries']]) - except ValueError: - fail('Retained generation geometry differs from its queue owner.') - if artifacts is not None: - _verify_payloads(family, doc, declarations, artifacts) - result.append(copy.deepcopy(envelope)) - _source_closure(result, records) - return result - - -def _read(edge, declarations, artifacts, maximum): - declaration = declarations[edge['artifact']['sha256']] - state = artifacts.status(declaration)['state'] - if state == 'missing': - return None - if state != 'verified': - fail('Producer evidence payload is corrupt.', 'integrity', 409) - return artifacts.read_blob({'sha256': declaration['sha256'], 'bytes': declaration['bytes']}, maximum_bytes=maximum) - - -def _verify_payloads(family, doc, declarations, artifacts): - job = copy.deepcopy(doc['job']) - payloads = doc['payloads'] - for role in ('raw_response', 'canonical_request', 'input_image'): - if role not in payloads: - continue - maximum = caption_proposals.MAX_IMAGE if role == 'input_image' else 32*1024*1024 if role == 'canonical_request' else image_generation.MAX_JSON if family == 'generation_history' else MAX_RESPONSE - raw = _read(payloads[role], declarations, artifacts, maximum) - if raw is None: - continue - if role == 'canonical_request': - parsed = pumas.strict_json(raw); _safe(parsed) - if _sha(raw) != job.get('canonical_request_sha256'): - fail('Canonical producer request digest differs.') - job['canonical_request'] = parsed - elif role == 'input_image': - if _sha(raw) != job['input_image']['sha256'] or len(raw) != job['input_image']['bytes']: - fail('Prepared producer image differs from its observation.') - job['input_image_base64'] = base64.b64encode(raw).decode('ascii') - else: - if _sha(raw) != job.get('response_sha256'): - fail('Producer response digest differs.') - _response_values(raw) - job['raw_response_base64'] = base64.b64encode(raw).decode('ascii') - if family == 'generation_history': - _verify_prompt_batches(doc,declarations,artifacts) - for wrapper in doc['entries']: - histories=wrapper.get('history_payloads',[wrapper['payloads'] for _ in wrapper['history']]) - for entry,mapping in zip(wrapper['history'],histories): - for field,role in (('attempt_evidence','attempt_request'),('metadata','result_request')): - if role not in mapping:continue - raw=_read(mapping[role],declarations,artifacts,32*1024*1024) - if raw is None:continue - evidence=copy.deepcopy(entry.get(field,{})) - evidence['canonical_request']=pumas.strict_json(raw) - _safe(evidence) - try:synthetic.validate_retained_attempt(job,entry,evidence) - except (ValueError,TypeError,KeyError):fail('Generation request differs from its retained entry intent.') - - else: - module = {'grounded_history': grounded_candidates, 'caption_proposal_history': caption_proposals, - 'text_proposal_history': text_classification_proposals}[family] - module.validate_retained_result(job) - if family != 'caption_proposal_history' or 'input_image_base64' in job: - expected = module.request_payload(job) if family == 'grounded_history' else module.payload(job) - if pumas.typed(job['config']) and 'capability_observation' in job: - expected['profile'] = job['capability_observation']['capabilities']['profile'] - if _sha(encode(expected).encode()) != job['canonical_request_sha256']: - fail('Producer request differs from its captured source/configuration.') - if 'canonical_request' in job and expected != job['canonical_request']: - fail('Retained producer request body differs from its owner.') - - -class InertGenerationEntries: - """Source-deletion projection; deliberately has no Jobs lifecycle methods.""" - def __init__(self, owner): - self.owner, self.db, self.access = owner, owner.session.db, owner.session.access - self.lock = self.db.lock - - @authorized('inspect', 'synthetic.snapshot') - def snapshot(self): - with self.lock: - jobs = [copy.deepcopy(item['document']['job']) for item in sorted(self.owner._records, - key=lambda item: (item['document']['origin_catalog_id'], item['document']['ordinal'])) - if item['family'] == 'generation_history'] - entries = [json.loads(row[0]) for row in self.db.execute('SELECT data FROM generation_entries ORDER BY storage_order')] - return {'jobs': jobs, 'entries': entries} - - def capture_records(self): - return self.owner.capture() - - def _entry(self, entry): - self.access.require('edit', 'dataset.delete', entry.get('sample_id')) - previous = self.db.execute('SELECT data FROM generation_entries WHERE id=%s', (entry.get('id'),)).fetchone() - if previous is None: - fail('Only an existing inert generation entry can be changed.') - old = json.loads(previous[0]) - expected = dict(old, status='deleted', sample_id=None, deleted_at=entry.get('deleted_at')) - if entry != expected or old['status'] not in ('completed', 'deleted'): - fail('Only source-deletion facts may change an inert generation entry.') - date(entry['deleted_at']) - self.db.execute('UPDATE generation_entries SET data=%s WHERE id=%s', (encode(entry), entry['id'])) - - -class ProjectProducers: - def __init__(self, session): - self.session = session - self._records, self._artifacts = [], {} - self._pending_payloads = {} - self.generation_jobs = InertGenerationEntries(self) - self.generation_entries = self.generation_jobs - - def _read(self, action, invoke): - with self.session.access.lock, self.session.lock, self.session.db.lock: - self.session.access.require('inspect', action) - self.session.check_current() - result = invoke(self.session.snapshot['records']) - self.session.check_current() - return result - - def list(self, family, *, origin_catalog_id=None, offset=0, limit=40): - if family not in FAMILIES: - fail('Unsupported producer family.') - if origin_catalog_id is not None: - identity(origin_catalog_id) - integer(offset); integer(limit, 1, 100) - def read(records): - values = sorted((item['document'] for item in records if item['family'] == family - and (origin_catalog_id is None or item['document']['origin_catalog_id'] == origin_catalog_id)), - key=lambda doc: (doc['origin_catalog_id'], doc['ordinal'])) - return dict(items=[_summary(family, doc) for doc in values[offset:offset+limit]], - total=len(values), offset=offset, limit=limit) - return self._read('project_files.producers', read) - - def get(self, family, id, *, origin_catalog_id, entries_offset=0, entries_limit=40): - if family not in FAMILIES: - fail('Unsupported producer family.') - identity(id); identity(origin_catalog_id) - integer(entries_offset); integer(entries_limit, 1, 100) - def read(records): - doc = next((item['document'] for item in records if item['family'] == family - and item['id'] == origin_catalog_id + '.' + id), None) - if doc is None: - fail('Historical producer was not found.', 'not_found', 404) - declarations = _declarations(records) - result = _summary(family, doc) - result['job'] = {key:copy.deepcopy(value) for key,value in doc['job'].items() if key != 'source'} - source = doc['job'].get('source') - result['source_reference'] = ({key:source[key] for key in - ('id','kind','revision','source_revision','content_hash','source_sha256')} if source else None) - result['payloads'] = self._payload_status(doc['payloads'], declarations) - result['observation_integrity'] = copy.deepcopy(doc['observation_integrity']) - entries = doc.get('entries', []) - page, used = [], 0 - for value in entries[entries_offset:entries_offset+entries_limit]: - item = copy.deepcopy(value) - item['payloads'] = self._payload_status(item['payloads'], declarations) - if 'history_payloads' in item:item['history_payloads']=[self._payload_status(value,declarations) for value in item['history_payloads']] - size = len(encode(item).encode()) - if used + size > 8*1024*1024: - break - page.append(item); used += size - next_offset = entries_offset + len(page) - batches=[] - for value in doc.get('prompt_batches',[])[entries_offset:entries_offset+entries_limit]: - item=copy.deepcopy(value) - item['payloads']=self._payload_status(item['payloads'],declarations) - if len(encode(batches+[item]).encode())>8*1024*1024:break - batches.append(item) - next_batch=entries_offset+len(batches) - result['prompt_batches']=dict(items=batches,total=len(doc.get('prompt_batches',[])),offset=entries_offset,limit=entries_limit, - next_offset=next_batch if next_batch0)) - self._records = records - all_declarations = _declarations(snapshot['records']) - referenced = _referenced_artifacts(records) - self._artifacts = {sha: all_declarations[sha] for sha in referenced} - return self - - def refresh(self, snapshot): - """Refresh canonical science after proven current custody drainage. - - This never creates producer jobs/admissions, deletes a local job table, - or turns a retained endpoint/identity into current execution authority. - """ - records=decode_records(snapshot['records'],artifacts=self.session.artifacts) - seen=set();orders=set() - for envelope in records: - if envelope['family']=='generation_history': - for value in envelope['document']['entries']: - if value['entry']['id'] in seen or value['storage_order'] in orders: - fail('Ambiguous generation entry identity across origins.','unsupported',422) - seen.add(value['entry']['id']);orders.add(value['storage_order']) - with self.session.db.transaction(): - for envelope in records: - if envelope['family']!='generation_history':continue - for value in envelope['document']['entries']: - entry=value['entry'] - self.session.db.execute('INSERT INTO generation_entries(id,job_id,ordinal,data,storage_order) VALUES(%s,%s,%s,%s,%s) ON CONFLICT(id) DO UPDATE SET job_id=excluded.job_id,ordinal=excluded.ordinal,data=excluded.data,storage_order=excluded.storage_order', - (entry['id'],entry['job_id'],entry['ordinal'],encode(entry),value['storage_order'])) - maximum=self.session.db.execute('SELECT COALESCE(max(storage_order),0) FROM generation_entries').fetchone()[0] - self.session.db.execute('SELECT setval(pg_get_serial_sequence(%s,%s),%s,%s)',('generation_entries','storage_order',max(1,maximum),maximum>0)) - self._records=records - declarations=_declarations(snapshot['records']) - self._artifacts={sha:declarations[sha] for sha in _referenced_artifacts(records)} - return self - - def capture(self): - result = copy.deepcopy(self._records) - by_id = {entry['id']: entry for entry in [json.loads(row[0]) for row in self.session.db.execute('SELECT data FROM generation_entries ORDER BY storage_order')]} - for envelope in result: - if envelope['family'] == 'generation_history': - for value in envelope['document']['entries']: - if value['entry']['id'] not in by_id: - fail('An inert generation entry disappeared from its projection.') - current = copy.deepcopy(by_id.pop(value['entry']['id'])) - if current != value['entry']: - value['history'].append(current) - if 'history_payloads' in value:value['history_payloads'].append(copy.deepcopy(value['payloads'])) - value['entry'] = current - if by_id: - fail('Unclassified generation entries appeared in the project projection.') - result.extend(dict(family='project_artifact', id=sha, document=copy.deepcopy(value)) for sha, value in sorted(self._artifacts.items())) - decode_records(_composed(self.session.snapshot['records'], result), artifacts=self.session.artifacts) - return result - - -def _summary(family, document): - job = document['job'] - return dict(family=family, origin_catalog_id=document['origin_catalog_id'], id=job['id'], - format=document['format'], ordinal=document['ordinal'], status=job['status'], - revision=job.get('revision'), created_at=job.get('created_at'), updated_at=job.get('updated_at'), - entry_count=len(document.get('entries', [])), candidate_count=len(job.get('candidates', [])), - prompt_batch_count=len(document.get('prompt_batches',[]))) - - -def _observation_integrity(value): - return {key: 'unverified_missing_original_wire' for key in ('capability_observation', 'build_observation') if key in value} - - -def _entry_integrity(entry): - result = {field + '.' + key: state for field in ('metadata', 'attempt_evidence') - for key, state in _observation_integrity(entry.get(field, {})).items()} - # Live image generation retains the successful response digest and decoded - # PNG, but not the original response envelope. Do not invent that envelope. - for field in ('metadata', 'attempt_evidence'): - if entry.get(field, {}).get('response_sha256') is not None: - result[field + '.response_sha256'] = 'unverified_missing_original_wire' - return result - - -def _entry_history(value, job): - history = value['history'] - if type(history) is not list or not 1 <= len(history) <= 100_000 or history[-1] != value['entry']: - fail('Invalid generation observation history.') - for entry in history: - _entry(entry, job) - if any(entry[k] != history[0][k] for k in ('id', 'job_id', 'ordinal', 'prompt', 'model', 'width', 'height', 'requested_seed')): - fail('Generation history rewrites its immutable producer intent.') - for previous, current in zip(history, history[1:]): - if previous['status'] == 'deleted': - fail('Deleted generation history cannot resume.') - if current['status'] == 'deleted': - expected = dict(previous, status='deleted', sample_id=None, deleted_at=current.get('deleted_at')) - if previous['status'] != 'completed' or current != expected: - fail('Unsupported generation deletion transition.') - elif previous['status'] == 'completed': - fail('Completed generation history cannot be rewritten.') - - -def _prompt_batches(doc, declarations): - values=doc.get('prompt_batches',[]) - if type(values) is not list or len(values)>10000: - fail('Generation prompt batch observations exceed their bound.') - if values and doc['job']['config']['strategy']!='varied': - fail('Repeat generation cannot import variation observations.') - seen=set();last_offset=0 - for wrapper in values: - shape(wrapper,{'batch','payloads'},name='prompt batch observation') - batch=wrapper['batch'] - shape(batch,{'id','offset','count','status','error','request_sha256','response_sha256','prompts'},name='prompt batch') - identity(batch['id']);digest(batch['request_sha256']) - if batch['id'] in seen:fail('Prompt batch identity repeats.') - seen.add(batch['id']) - integer(batch['offset'],0,doc['job']['config']['count']-1) - integer(batch['count'],1,min(synthetic.BATCH_SIZE,doc['job']['config']['count']-batch['offset'])) - if batch['offset']4000 or p!=p.strip() for p in batch['prompts'])): - fail('Prompt batch result shape differs.') - elif batch['prompts'] is not None or not batch['error']: - fail('Failed prompt batch claims valid prompts.') - _safe(batch) - roles={'canonical_request'} | ({'raw_response'} if batch['response_sha256'] is not None else set()) - if set(wrapper['payloads'])!=roles:fail('Prompt batch exact payload declarations differ.') - _payloads(wrapper['payloads'],declarations,roles) - for role,field in (('canonical_request','request_sha256'),('raw_response','response_sha256')): - if role in wrapper['payloads'] and wrapper['payloads'][role]['artifact']['sha256']!=batch[field]: - fail('Prompt batch payload digest differs.') - - -def _verify_prompt_batches(doc,declarations,artifacts): - entries=[v['entry'] for v in doc['entries']] - expected=None;available=True - for wrapper in doc.get('prompt_batches',[]): - batch=wrapper['batch'] - request=_read(wrapper['payloads']['canonical_request'],declarations,artifacts,32*1024*1024) - response=(_read(wrapper['payloads']['raw_response'],declarations,artifacts,256*1024) - if 'raw_response' in wrapper['payloads'] else None) - if response is not None:_response_values(response) - if request is None: - available=False;continue - parsed=caption_proposals.strict_json(request);_safe(parsed) - try:synthetic.validate_retained_prompt_batch(doc['job']['config'],batch,parsed,response) - except (ValueError,KeyError,TypeError,IndexError):fail('Retained prompt batch wire differs from its queue intent.') - if expected is None:expected=[v['prompt'] for v in entries[:batch['offset']]] - if available and batch['offset']!=len(expected):fail('Prompt batch offset differs from retained unique results.') - if available and json.loads(parsed['messages'][1]['content'])['recent_prompts_to_avoid']!=expected[-synthetic.BATCH_SIZE:]: - fail('Prompt batch context differs from preceding retained queue prompts.') - if batch['status']=='completed' and available: - seen={' '.join(value.casefold().split()) for value in expected} - for prompt in batch['prompts']: - key=' '.join(prompt.casefold().split()) - if key not in seen:expected.append(prompt);seen.add(key) - if available and expected is not None and [v['prompt'] for v in entries]!=expected[:len(entries)]: - fail('Saved generation prompts differ from exact variation results.') - - -def _capture_prompt_batches(owner,job,batches): - result=[] - for original in batches: - batch=copy.deepcopy(original) - request=batch.pop('canonical_request') - raw=batch.pop('raw_response_base64') - synthetic.validate_retained_prompt_batch(job['config'],batch,request,_bytes(raw,256*1024) if raw is not None else None) - _safe(request) - payloads={'canonical_request':_publish(owner,encode(request).encode(),'canonical_request')} - if raw is not None: - data=_bytes(raw,256*1024);_response_values(data) - payloads['raw_response']=_publish(owner,data,'raw_response','application/octet-stream') - result.append(dict(batch=batch,payloads=payloads)) - return result - - -def _referenced_artifacts(records): - result = set() - for envelope in records: - doc = envelope['document'] - mappings = [doc['payloads']] - mappings.extend(value['payloads'] for value in doc.get('prompt_batches',[])) - if envelope['family'] == 'generation_history': - mappings.extend(value['payloads'] for value in doc['entries']) - mappings.extend(mapping for value in doc['entries'] for mapping in value.get('history_payloads',[])) - result.update(edge['artifact']['sha256'] for mapping in mappings for edge in mapping.values()) - return result - - -def _portable_observations(value): - value = copy.deepcopy(value) - if 'build_observation' in value: - build = value['build_observation'] - shape(build, {'advertisement', 'observed_sha256'}, {'server_url'}, 'stored build observation') - build.pop('server_url', None) - return value - - -def _historical_urls(value): - """Known attribution URLs are historical facts, never current resolvers.""" - if type(value) is dict: - for key, child in value.items(): - if key in ('server_url', 'requested_server_url', 'prompt_url'): - import ai_http - ai_http.validate_url('llamacpp', child) - _historical_urls(child) - elif type(value) is list: - for child in value: - _historical_urls(child) - - -def _publish(owner, raw, role, media='application/json'): - declaration = dict(format='project_artifact_v1', sha256=_sha(raw), bytes=len(raw)) - previous = owner._pending_payloads.get(declaration['sha256']) - if previous is not None and previous != raw: - fail('Conflicting exact producer payload bytes.') - owner._pending_payloads[declaration['sha256']] = raw - owner._artifacts[declaration['sha256']] = declaration - return dict(artifact=dict(namespace=owner.session.summary['project_id'], sha256=declaration['sha256']), - media_type=media, kind='producer_evidence', role=role, - preservation='unique', required_for=['verify_producer']) - - -def _capture_payloads(owner, family, job): - payloads = {} - for field, role in PAYLOAD_FIELDS.items(): - value = job.pop(field, None) - if value is None: - continue - if field == 'canonical_request': - _safe(value) - raw = encode(value).encode() - else: - maximum = caption_proposals.MAX_IMAGE if role == 'input_image' else image_generation.MAX_JSON if family == 'generation_history' else MAX_RESPONSE - raw = _bytes(value, maximum) - if role == 'raw_response': - _response_values(raw) - payloads[role] = _publish(owner, raw, role, 'image/jpeg' if role == 'input_image' else 'application/octet-stream' if role == 'raw_response' else 'application/json') - return payloads - - -def _response_values(raw): - try: - # The existing chat owner accepts JSON's historical UTF-16 byte - # encodings too. Inspect values without rewriting original bytes. - parsed = caption_proposals.strict_json(raw) - except (UnicodeError, ValueError, RecursionError): - fail('Opaque provider response bytes lack a supported credential-free classification.', 'unsupported', 422) - _safe(parsed) - return parsed - - -def _capture_entry(owner, entry, storage_order): - result, payloads = copy.deepcopy(entry), {} - for field, role in (('attempt_evidence', 'attempt_request'), ('metadata', 'result_request')): - if field in result: - result[field] = _portable_observations(result[field]) - request = result[field].pop('canonical_request', None) - if request is not None: - _safe(request) - raw = encode(request).encode() - if _sha(raw) != result[field]['canonical_request_sha256']: - fail('Generation request body digest differs.') - payloads[role] = _publish(owner, raw, role) - return dict(entry=result, history=[copy.deepcopy(result)], payloads=payloads, storage_order=storage_order, - observation_integrity=_entry_integrity(result)) - - -def _capture_job(owner, family, original, ordinal, entries): - job = copy.deepcopy(original) - prompt_batches = job.pop('prompt_batches',None) if family == 'generation_history' else None - # These are the complete classified local fields, not a denylist fallback. - # All remaining source fields must satisfy the owned closed codec below. - for key in LOCAL_JOB_FIELDS: - if key in job: - (identity if key == 'admission_id' else digest)(job[key]) - job.pop(key, None) - if type(job.get('config')) is not dict: - fail('Missing producer configuration.') - for field in LOCAL_CONFIG_FIELDS: - if field in job['config']: - import ai_http - ai_http.validate_url('llamacpp', job['config'][field]) - job['config'].pop(field, None) - if family != 'caption_proposal_history' and 'input_image_base64' in job: - fail('Unexpected image payload in this producer family.') - job = _portable_observations(job) - if 'source' in job: - _historical_urls(job['source']) - if family == 'grounded_history': - view = job.pop('raw_response', None) - job['raw_response_text_available'] = view is not None - if view is not None: - if type(view) is not str: - fail('Invalid retained grounded response view.') - raw = _bytes(job['raw_response_base64'], MAX_RESPONSE) - if raw.decode('utf-8') != view: - fail('Grounded response text view differs from its exact bytes.') - if family != 'generation_history' and 'canonical_request' not in job: - module = {'grounded_history': grounded_candidates, 'caption_proposal_history': caption_proposals, - 'text_proposal_history': text_classification_proposals}[family] - job['canonical_request'] = module.request_payload(job) if family == 'grounded_history' else module.payload(job) - if _sha(encode(job['canonical_request']).encode()) != job['canonical_request_sha256']: - fail('Reconstructed canonical producer request differs from its stored identity.') - payloads = _capture_payloads(owner, family, job) - document = dict(format=FAMILIES[family], origin_catalog_id=owner._origin, ordinal=ordinal, - job=job, payloads=payloads, observation_integrity=_observation_integrity(job)) - if prompt_batches is not None: - document['prompt_batches'] = _capture_prompt_batches(owner,job,prompt_batches) - if family == 'generation_history': - document['entries'] = [_capture_entry(owner, entry, storage_order) for entry, storage_order in entries if entry['job_id'] == job['id']] - return dict(family=family, id=owner._origin+'.'+job['id'], document=document) - - -def _capture_source(self, *, origin_catalog_id=None): - """Explicit historical extraction primitive; never called by inert Open. - - Reads the five named producer tables. It may publish exact evidence bytes, - but neither alters the source rows nor constructs any producer supervisor. - """ - self._origin = identity(origin_catalog_id or self.session.db.dataset_id) - self._pending_payloads = {} - entries = [] - for row_id, job_id, ordinal, raw, storage_order in self.session.db.execute( - 'SELECT id,job_id,ordinal,data,storage_order FROM generation_entries ORDER BY storage_order'): - entry = json.loads(raw) - if (entry.get('id'), entry.get('job_id'), entry.get('ordinal')) != (row_id, job_id, ordinal): - fail('Generation row identity differs from its observed document.') - entries.append((entry, storage_order)) - records = [] - for family, table in TABLES.items(): - for row_id, raw, ordinal in self.session.db.execute('SELECT id,data,ordinal FROM ' + table + ' ORDER BY ordinal'): - job = json.loads(raw) - if job.get('id') != row_id: - fail('Producer row identity differs from its observed document.') - records.append(_capture_job(self, family, job, ordinal, entries)) - known_jobs = {item['document']['job']['id'] for item in records if item['family'] == 'generation_history'} - if any(entry['job_id'] not in known_jobs for entry, _ in entries): - fail('Generation entry has no retained producer job.') - records.extend(dict(family='project_artifact', id=sha, document=copy.deepcopy(declaration)) - for sha, declaration in sorted(self._artifacts.items())) - composed = _composed(self.session.snapshot['records'], records) - decode_records(composed, artifacts=_CapturedEvidence(self)) - for sha, raw in self._pending_payloads.items(): - self.session.artifacts.publish_bytes(raw, self._artifacts[sha], maximum_bytes=32*1024*1024) - self._pending_payloads = {} - return records - - - -def _producer_document(records, family, job_id, source_id=None): - candidates = [item['document'] for item in decode_records(records) - if item['family'] == family and item['document']['job']['id'] == job_id - and (source_id is None or item['document']['job'].get('source', {}).get('id') == source_id)] - if len(candidates) != 1: - fail('Producer evidence has a missing or ambiguous historical producer closure.') - return candidates[0] - - -def _same_payload(value, document, role): - edge = document['payloads'].get(role) - if edge is None or _sha(encode(value).encode()) != edge['artifact']['sha256']: - fail('Retained request evidence differs from its declared producer payload.') - - -def validate_target_proposal(evidence, record, records): - """Validate owner-generated draft evidence, never mint current approval.""" - if type(evidence) is not dict: - fail('Applied target proposal evidence must be an object.') - text_target = 'source_text_sha256' in evidence - required = {'job_id', 'applied_revision', 'captured_revision', 'source_revision', 'source_sha256', - 'config', 'prompt_version', 'prompt_sha256', 'canonical_request_sha256', - 'response_sha256', 'reported_model', 'verification'} - required |= {'source_text_sha256', 'labels_sha256'} if text_target else {'canonical_image_sha256', 'input_image'} - shape(evidence, required, EVIDENCE_FIELDS - required, 'applied proposal evidence') - _safe(evidence); _historical_urls(evidence) - family = 'text_proposal_history' if text_target else 'caption_proposal_history' - doc = _producer_document(records, family, identity(evidence['job_id']), record['id']) - expected_verification = ('Exact label shape only; applied as draft, never approved.' if text_target - else 'Caption shape only; applied as draft, never approved.') - if evidence['verification'] != expected_verification: - fail('Applied target verification qualification differs from its owner.') - job, source = doc['job'], doc['job']['source'] - for key in ('prompt_version', 'prompt_sha256', 'canonical_request_sha256', 'response_sha256'): - if evidence[key] != job[key]: - fail('Applied target evidence differs from its producer ' + key + '.') - if type(evidence['config']) is not dict: - fail('Applied target configuration must be an object.') - config = {key: value for key, value in evidence['config'].items() if key not in LOCAL_CONFIG_FIELDS} - if config != job['config'] or evidence['reported_model'] != job.get('reported_model'): - fail('Applied target evidence rewrites its producer configuration/result.') - if (type(evidence['applied_revision']) is not int or evidence['applied_revision'] != source['revision'] + 1 - or evidence['captured_revision'] != source['revision'] - or evidence['source_revision'] != source['source_revision'] - or evidence['source_sha256'] != source['source_sha256'] - or evidence['applied_revision'] > record['revision']): - fail('Applied target evidence belongs to different captured revisions.') - if job['status'] != 'applied' or job['application'] != { - 'record_id': record['id'], 'revision': evidence['applied_revision'], 'source_revision': evidence['source_revision']}: - fail('Applied target lacks its historical application disposition.') - if record['revision'] == evidence['applied_revision'] and ( - record['annotation'] != job['annotation'] or record['review'] != 'draft' - or record['task'] != ('text_classification' if text_target else 'image_caption')): - fail('A proposal application cannot establish human review or a different target.') - if text_target: - if evidence['source_text_sha256'] != job['source_text_sha256'] or evidence['labels_sha256'] != job['labels_sha256']: - fail('Applied target source/label identity differs.') - elif evidence['canonical_image_sha256'] != source['content_hash'] or evidence['input_image'] != job['input_image']: - fail('Applied target prepared/oriented image identity differs.') - for key in EVIDENCE_FIELDS - {'canonical_request', 'canonical_request_sha256', 'response_sha256'}: - if key in evidence and evidence[key] != job.get(key): - fail('Applied target provider observation differs.') - if 'canonical_request' in evidence: - _same_payload(evidence['canonical_request'], doc, 'canonical_request') - return True - - -def validate_record_origin(origin, record, records): - """Recognize only the two producer provenance variants owned here.""" - if type(origin) is not dict or origin.get('method') not in ('model_generated', 'model_grounded_rewrite'): - return False - _safe(origin); _historical_urls(origin) - if origin['method'] == 'model_generated': - shape(origin, {'method', 'source_sha256', 'rights', 'generation'}, {'rights_note_correction'}, 'generated source provenance') - generation = origin['generation'] - shape(generation, {'job_id', 'ordinal', 'prompt', 'model', 'width', 'height', 'requested_seed'}, {'metadata', 'size'}, 'generated source binding') - docs = [item['document'] for item in decode_records(records) if item['family'] == 'generation_history' - and item['document']['job']['id'] == generation['job_id']] - matched = [] - for doc in docs: - for wrapper in doc['entries']: - for entry in wrapper['history']: - if entry['sample_id'] == record['id'] and entry['ordinal'] == generation['ordinal']: - matched.append((wrapper, entry)) - if len(matched) != 1: - fail('Generated source lacks an exact producer entry/source closure.') - wrapper, entry = matched[0] - for key in ('job_id', 'ordinal', 'prompt', 'model', 'width', 'height', 'requested_seed', 'size'): - if key in generation and generation[key] != entry.get(key): - fail('Generated source intent differs from its retained entry.') - if 'metadata' in generation: - metadata = copy.deepcopy(generation['metadata']) - request = metadata.pop('canonical_request', None) - if request is not None: - edge = wrapper['payloads'].get('result_request') - if edge is None or _sha(encode(request).encode()) != edge['artifact']['sha256']: - fail('Generated source result request differs.') - if _portable_observations(metadata) != entry.get('metadata'): - fail('Generated source result metadata differs.') - if record['kind'] != 'image' or origin['source_sha256'] not in {record['source_sha256'], *( - row['sha256'] for item in records if item['family'] == 'workbench_record' and item['id'] == record['id'] - for row in item['document']['source'].get('revisions', []))}: - fail('Generated source hash differs from its retained image lineage.') - else: - required = {'method', 'rights', 'normalization', 'provider', 'server_url', 'requested_model', 'requested_seed', - 'instruction', 'system_prompt', 'prompt_version', 'prompt_sha256', 'reported_model', - 'canonical_request_sha256', 'requested_count', 'max_tokens', 'job_id', 'candidate_id', - 'response_sha256', 'source', 'evidence', 'verification', 'admission_note'} - shape(origin, required, EVIDENCE_FIELDS | {'profile', 'rights_note_correction'}, 'grounded source provenance') - doc = _producer_document(records, 'grounded_history', identity(origin['job_id'])) - job = doc['job'] - values = [candidate for candidate in job['candidates'] if candidate['id'] == origin['candidate_id']] - if len(values) != 1: - fail('Grounded source candidate closure is missing.') - candidate = values[0] - if candidate['status'] != 'admitted' or candidate['record_id'] != record['id'] or candidate['text'] != record['text']: - fail('Grounded source differs from its reviewed candidate.') - for key, expected in {'requested_model': job['config']['model'], 'requested_seed': job['config']['seed'], - 'instruction': job['config']['instruction'], 'requested_count': job['config']['count'], 'max_tokens': 6000, - 'system_prompt': job['system_prompt'], 'prompt_version': job['prompt_version'], - 'prompt_sha256': job['prompt_sha256'], 'canonical_request_sha256': job['canonical_request_sha256'], - 'response_sha256': job['response_sha256'], 'reported_model': job.get('reported_model'), - 'evidence': candidate['evidence'], 'admission_note': candidate['review_note'], 'verification': job['verification']}.items(): - if origin[key] != expected: - fail('Grounded source provenance differs from its producer ' + key + '.') - if (origin['provider'] != (pumas.PROTOCOL if pumas.typed(job['config']) else 'pumas_chat_compatible') - or origin['normalization'] != 'NFC; LF newlines' - or pumas.typed(job['config']) and origin.get('profile') != job['config'].get('profile')): - fail('Grounded source producer or normalization attribution differs.') - if record['revision'] == 1 and (record['review'] != 'draft' or record['task'] != 'text_classification' - or record['annotation'] != {'label':candidate['label']}): - fail('Grounded admission cannot establish human review or a different target.') - for key in EVIDENCE_FIELDS - {'canonical_request', 'canonical_request_sha256', 'response_sha256'}: - if key in origin and origin[key] != job.get(key): - fail('Grounded source provider observation differs.') - expected_source = {key: job['source'][key] for key in ('id', 'revision', 'source_revision', 'content_hash', 'text', 'annotation')} - if origin['source'] != expected_source: - fail('Grounded source provenance rewrites its captured input.') - if 'canonical_request' in origin: - _same_payload(origin['canonical_request'], doc, 'canonical_request') - return True - - -def validate_operation_result(operation, target, result, records): - from project_producer_execution import validate_operation_result as validate_action - return validate_action(operation, target, result, records) - - -def _composed(current, upserts): - result = {(item['family'], item['id']): item for item in current} - result.update({(item['family'], item['id']): item for item in upserts}) - return [result[key] for key in sorted(result)] - - -def _source_closure(producers, records): - assets = {item['id']: item['document'] for item in records - if item['family'] in ('workbench_record', 'workbench_text')} - for envelope in producers: - doc, family = envelope['document'], envelope['family'] - job = doc['job'] - if family == 'generation_history': - for wrapper in doc['entries']: - for entry in wrapper['history']: - if entry['sample_id'] is not None and entry['sample_id'] not in assets: - fail('Generated source canonical record is missing.') - continue - source = job['source'] - asset = assets.get(source['id']) - if asset is None or source not in asset.get('history', []): - fail('Producer captured source differs from its retained Workbench history.') - if family == 'grounded_history': - for candidate in job['candidates']: - if candidate['record_id'] is not None: - target = assets.get(candidate['record_id']) - if target is None or target['current']['text'] != candidate['text']: - fail('Admitted grounded candidate canonical record is missing or differs.') - - -class _CapturedEvidence: - """Immutable source buffers prove owner semantics before any publication.""" - def __init__(self, owner): - self.owner = owner - - def status(self, declaration): - raw = self.owner._pending_payloads.get(declaration['sha256']) - if raw is None: - return self.owner.session.artifacts.status(declaration) - if len(raw) != declaration['bytes'] or _sha(raw) != declaration['sha256']: - fail('Captured producer payload identity differs.') - return {'state': 'verified'} - - def read_blob(self, descriptor, *, maximum_bytes): - raw = self.owner._pending_payloads.get(descriptor['sha256']) - if raw is None: - return self.owner.session.artifacts.read_blob(descriptor, maximum_bytes=maximum_bytes) - if len(raw) != descriptor['bytes'] or len(raw) > maximum_bytes: - fail('Captured producer payload exceeds its owner bound.') - return raw diff --git a/project_projection.py b/project_projection.py deleted file mode 100644 index e7aa8366..00000000 --- a/project_projection.py +++ /dev/null @@ -1,434 +0,0 @@ -"""Concrete inert composition of external-project projection owners. - -No registry, worker constructor, process recovery, dependency installation or -project-script import belongs here. The fixed codecs validate the same candidate -checkpoint before reconstruction and before each canonical publication. -""" -import copy -import hashlib -from datetime import datetime -import re -from types import SimpleNamespace - -from project_artifacts import ProjectArtifacts, validate_declaration -from project_data import ProjectData, FAMILIES as DATA_FAMILIES, decode_data_records -from project_data import validate_operation_result as validate_data_result -from project_history import ProjectHistory, FAMILY_FORMATS as HISTORY_FAMILIES -from project_history import decode_records as decode_history_records -from project_history import validate_operation_result as validate_history_result -from project_material import ProjectMaterial, MaterialSnapshot, FAMILIES as MATERIAL_FAMILIES -from project_material import validate_operation_result as validate_material_result -from project_producers import ProjectProducers, FAMILIES as PRODUCER_FAMILIES -from project_producers import decode_records as decode_producer_records -from project_session import session_records_for -from project_session import ProjectSession, operation_documents, operation_records -from project_locks import ProjectLock -from project_execution import ProjectExecution, validate_operation_result as validate_execution_result -from project_producer_execution import ProjectProducerExecution, validate_operation_result as validate_producer_result -from project_files import ProjectFiles, decode_records as decode_file_records -from project_files import validate_operation_result as validate_file_result -from project_files import receipt_validator as file_receipt_validator -from project_study_execution import ProjectStudyExecution, validate_operation_result as validate_study_execution_result -from project_runtime import ProjectRuntime, validate_operation_result as validate_runtime_result -from project_native_execution import FAMILY as NATIVE_FAMILY, decode_records as decode_native_records -from project_native_preparation import ProjectNativePreparation, validate_operation_result as validate_preparation_result -from project_sources import SourceAdapter, validate_operation_result as validate_source_result -from project_sources import receipt_validator as source_receipt_validator -from project_measurements import ProjectMeasurements, FAMILY as MEASUREMENT_FAMILY -from project_measurements import decode_records as decode_measurement_records -from project_measurements import validate_operation_result as validate_measurement_result -from project_measurements import receipt_validator as measurement_receipt_validator -from workbench import WorkbenchError -from workbench import timestamp -from project_session import session_record - - -def validate_artifact_resolution(operation, result, records): - if operation != 'artifacts.resolve': - return False - if (type(result) is not dict or set(result) != { - 'format', 'sha256', 'bytes', 'actor_id', 'observed_at'} - or result['format'] != 'project_artifact_resolution_v1' - or type(result['actor_id']) is not str or not re.fullmatch('[a-f0-9]{32}', result['actor_id']) - or type(result['observed_at']) is not str): - raise WorkbenchError('Invalid artifact resolution observation.') - try: - if datetime.fromisoformat(result['observed_at']).utcoffset() is None: - raise ValueError() - except ValueError: - raise WorkbenchError('Artifact observation timestamp requires an offset.') from None - declaration = validate_declaration(dict(format='project_artifact_v1', sha256=result['sha256'], bytes=result['bytes'])) - if not any(item['family'] == 'project_artifact' and item['id'] == declaration['sha256'] - and item['document'] == declaration for item in records): - raise WorkbenchError('Artifact resolution observation has no exact declaration.') - return True - - -def validate_project_records(records, *, project_id, artifacts): - """Validate one inert candidate through every owning domain, without SQL reconstruction. - - Under an edit delta (project_validation_delta.edit_delta) the candidate is - a validated base checkpoint plus changed records; components and receipts - that cannot be affected are skipped. TULDOK_VALIDATION_CROSSCHECK=1 also - runs complete validation and requires the same outcome. - """ - from project_validation_delta import current_delta - delta = current_delta() - if delta is None: - return _validate_project_records(records, project_id=project_id, artifacts=artifacts, delta=None) - import os - if os.environ.get('TULDOK_VALIDATION_CROSSCHECK') == '1': - full_error = scoped_error = None - try: - _validate_project_records(records, project_id=project_id, artifacts=artifacts, delta=None) - except Exception as error: - full_error = error - try: - _validate_project_records(records, project_id=project_id, artifacts=artifacts, delta=delta) - except Exception as error: - scoped_error = error - if (full_error is None) != (scoped_error is None): - raise AssertionError(f'Edit-scoped validation disagrees with complete validation: ' - f'complete={full_error!r} scoped={scoped_error!r}') - if full_error is not None: - raise full_error - return None - return _validate_project_records(records, project_id=project_id, artifacts=artifacts, delta=delta) - - -def _composition_members(records): - members = set() - for item in records: - if item['family'] != 'project_composition': - continue - for source in item['document'].get('sources', ()): - for family, entries in source.get('records', {}).items(): - members.update((family, identity) for identity in entries) - members.update(('run_observation', sha) for sha in source.get('run_observations', {}).values()) - return members - - -def _validate_project_records(records, *, project_id, artifacts, delta): - def needed(component): - return delta is None or delta.touches(component) - claimed = {'workbench_text', 'project_artifact', 'project_operation', 'project_file', 'project_fork', 'project_composition', 'project_extraction', NATIVE_FAMILY, MEASUREMENT_FAMILY} | set(DATA_FAMILIES) | set( - MATERIAL_FAMILIES) | set(HISTORY_FAMILIES) | set(PRODUCER_FAMILIES) - identities = set() - declarations = {} - for item in records: - identity = (item['family'], item['id']) - if item['family'] not in claimed or identity in identities: - raise WorkbenchError('Unknown or duplicate owned project family.', 'unsupported', 409) - identities.add(identity) - if item['family'] == 'project_artifact': - declaration = validate_declaration(item['document']) - if declaration['sha256'] != item['id']: - raise WorkbenchError('Artifact inventory identity differs.') - declarations[item['id']] = declaration - if needed('data'): - decode_data_records(records) - from project_fork import decode_fork - decode_fork(records, project_id=project_id) - if needed('composition') or (delta is not None and delta.changed & _composition_members(records)): - from project_composition import decode_records as decode_compositions - decode_compositions(records, project_id=project_id) - if needed('extraction'): - from project_transfer import decode_records as decode_extraction_records - decode_extraction_records(records) - operation_records(records, project_id=project_id) - if needed('native'): - decode_native_records(records,artifacts=artifacts) - material_cache = [] - def materials(): - if not material_cache: - material_cache.append(MaterialSnapshot(records)) - return material_cache[0] - if needed('material'): - for blob in materials().artifact_blobs(): - if declarations.get(blob['sha256']) != dict(format='project_artifact_v1', **blob): - raise WorkbenchError('Material artifact declaration is missing or inconsistent.') - # Resolve every cross-owner reference against THIS candidate, rather - # than a resolver that still sees the preceding committed checkpoint. - if needed('producers'): - decode_producer_records(records, artifacts=artifacts) - if needed('history') or (delta is not None and delta.history_receipt_added()): - decode_history_records(records, materials=materials(), artifacts=artifacts) - validators = {} - def lazy(name, component, claims, build): - # claims(operation) is exactly what the built validator can accept; - # for any other operation it would return False, so it is not built. - def validate(operation, result): - if not claims(operation): - return False - if name not in validators: - validators[name] = build() - return validators[name](operation, result) - if delta is None or needed(component): - validators[name] = build() - return validate - validate_file_receipt = lazy('file', 'files', lambda op: op.startswith('files.'), - lambda: file_receipt_validator(records)) - validate_measurement_receipt = lazy('measurement', 'measurements', lambda op: op == 'measurements.import', - lambda: measurement_receipt_validator(records, artifacts=artifacts)) - validate_source_receipt = lazy('source', 'sources', lambda op: op == 'source.register', - lambda: source_receipt_validator(records)) - from project_session import OPERATION_FAMILY - for receipt in operation_documents(records): - operation, result = receipt['operation'], receipt['result'] - if delta is not None: - identity = (OPERATION_FAMILY, receipt['project_id'] + '.' + hashlib.sha256(receipt['request_key'].encode('utf-8')).hexdigest() - if receipt.get('format') == 'project_operation_v2' else - hashlib.sha256(receipt['request_key'].encode('utf-8')).hexdigest()) - if not delta.receipt_needed(operation, identity): - continue - if (validate_data_result(operation, result, records) - or validate_material_result(operation, result, records) - or validate_history_result(operation, result, records) - or validate_source_receipt(operation, result) - or validate_measurement_receipt(operation, result) - or validate_execution_result(operation, result, records) - or validate_producer_result(operation, receipt['target'], result, records) - or validate_file_receipt(operation, result) - or validate_study_execution_result(operation, result, records) - or validate_runtime_result(operation, result, records) - or validate_preparation_result(operation, result, records) - or validate_artifact_resolution(operation, result, records)): - continue - raise WorkbenchError('No project owner accepts this operation receipt.', 'unsupported', 409) - - -class ProjectProjection: - def __init__(self, store, db, access, roots, *, custody=None, restore=True, runtime_sources=None, - validation_cache=None): - self.store, self.db, self.access = store, db, access - self.custody = custody - self.pending_original = [] - self.project_id = store.summary()['project_id'] - self.artifacts = ProjectArtifacts(store) - self.sources = None - self._disclosures = set() - # Only installation configuration supplies these aliases. Neither a - # project descriptor nor an HTTP request supplies filesystem roots. - self._runtime_sources = copy.deepcopy(runtime_sources or {}) - try: - self.session = ProjectSession(store, db, access, self.artifacts, - validate_records=self.validate_records, - validation_cache=validation_cache) - # Install before domain constructors retain their lock references. - db.lock = ProjectLock(access.lock, self.session.lock, db.lock) - self.producers = ProjectProducers(self.session) - self.data = ProjectData(self.session, generation_entries=self.producers.generation_jobs) - self.materials = ProjectMaterial(self.session) - self.measurements = ProjectMeasurements(self.session) - self.history = ProjectHistory(self.session, materials=self.materials, - authorize_disclosure=self.authorize_disclosure) - if restore: - # Producer restore reads its families, declarations and forks. - self.producers.restore(dict(records=session_records_for( - self.session, *PRODUCER_FAMILIES, 'project_artifact', 'project_fork'))) - self.data.restore() - self.materials.restore() - # These owners create only disposable local directories. Their - # semantic capture/preparation methods run solely on explicit calls. - from projects import Projects - from model_definitions import ModelDefinitions - from pipeline import Pipelines - self.context = SimpleNamespace(path=db.path, db=db, lock=db.lock, - access=self.materials.owner_access, - workbench=self.data.workbench, - releases=self.data.releases, runs=self.history) - self.sources = Projects(self.context, roots) - self.context.projects = self.sources - self.context.pipelines = self.pipelines = Pipelines(self.context) - self.context.models = self.models = ModelDefinitions(self.context) - self.source_adapter = SourceAdapter(self) - self.text = _TextView(self) - self.execution = ProjectExecution(self) - self.native_preparation=ProjectNativePreparation(self) - self.context.project_native_preparation=self.native_preparation - self.runtime = ProjectRuntime(self, resolve_configuration=self.runtime_configuration) - self.execution.producer_execution = ProjectProducerExecution( - self.session, self.data, self.producers, - runtime_access=self.execution.runtime_access, execution=self.execution) - self.files = ProjectFiles(self.session) - self.study_execution = ProjectStudyExecution(self, self.execution) - if restore: - self.study_execution.restore_authoring() - else: - # Explicit original-host recovery validates custody before any - # science cache reconstruction or local execution constructor. - self.session.available = False - except BaseException: - self.close() - raise - - @property - def schema(self): - return self.db.schema - - def execute(self, *args, **kwargs): - return self.db.execute(*args, **kwargs) - - def validate_records(self, records, *, project_id=None, artifacts=None): - return validate_project_records(records, - project_id=self.project_id if project_id is None else project_id, - artifacts=self.artifacts if artifacts is None else artifacts) - - def resolve_artifact(self, body, expected_checkpoint, key): - """Explicitly supply exact bytes from a configured current local root.""" - if type(body) is not dict or set(body) != {'sha256', 'root', 'path'}: - raise WorkbenchError('Choose one declared artifact and a current rooted file.') - with self.access.lock, self.session.lock, self.db.lock: - actor = self.access.require('edit', 'artifacts.resolve', body['sha256'], owner_only=True) - self.session.check_current() - declaration = session_record(self.session, 'project_artifact', body['sha256']) - declaration = None if declaration is None else declaration['document'] - if declaration is None: - raise WorkbenchError('Artifact is not declared by this project.', 'not_found', 404) - def invoke(): - with self.sources._file(body['root'], body['path']) as (descriptor, info): - if info.st_size != declaration['bytes']: - raise WorkbenchError('Supplied file length differs from the declared artifact.', 'conflict', 409) - self.artifacts.publish_fd(descriptor, declaration) - return dict(format='project_artifact_resolution_v1', sha256=declaration['sha256'], - bytes=declaration['bytes'], actor_id=actor.actor_id, observed_at=timestamp()) - return self.session.mutate('artifacts.resolve', body['sha256'], body, expected_checkpoint, key, - invoke, lambda result, before: dict(records=[], result=result)) - - def runtime_manifest(self, descriptor): - """Read only a current local registration during explicit preparation. - - An imported descriptor's root is never a filesystem capability. Captured - manifests already in canonical artifacts need no current registration. - """ - from pathlib import Path - import hashlib - if descriptor.get('catalog_id') != self.project_id: - raise WorkbenchError('Register this runtime under the current project before preparation.', - 'unavailable', 409) - if descriptor.get('profile') == 'captured_cpu_python_v1': - from runtime_snapshots import RuntimeSnapshots - from recipe_process import read_regular, CPU_MANIFEST_LIMIT - with self.execution.runtime_inspection(): - current = RuntimeSnapshots(self.db, self.execution.runtime_access, self.db.path).get( - descriptor['manifest_sha256'], verify=False) - if current != descriptor: - raise WorkbenchError('Current runtime registration differs from the selected descriptor.', 'stale', 409) - raw = read_regular(Path(current['root']) / 'manifest.json', CPU_MANIFEST_LIMIT) - elif descriptor.get('profile') == 'managed_torch_python_v1': - from torch_runtimes import TorchRuntimes - current, raw = TorchRuntimes(self.db, self.access, self.db.path).get( - descriptor['manifest_sha256'], verify=False) - if current != descriptor: - raise WorkbenchError('Current runtime registration differs from the selected descriptor.', 'stale', 409) - else: - raise WorkbenchError('Unsupported current runtime registration.', 'unsupported', 409) - if len(raw) != descriptor['manifest_bytes'] or hashlib.sha256(raw).hexdigest() != descriptor['manifest_sha256']: - raise WorkbenchError('Current runtime manifest changed during capture.', 'stale', 409) - return raw - - def runtime_configuration(self, request): - if (type(request) is not dict or set(request) != {'source'} - or type(request['source']) is not str or request['source'] not in self._runtime_sources): - raise WorkbenchError('Choose an explicitly configured current runtime source.', 'unavailable', 409) - return copy.deepcopy(self._runtime_sources[request['source']]) - - def runtime_sources(self): - with self.access.lock, self.session.lock, self.db.lock: - self.access.require('admin', 'runtime.sources', owner_only=True) - self.session.check_current() - return dict(sources=sorted(self._runtime_sources)) - - def authorize_disclosure(self, run, population): - self.access.require('inspect', 'project_history.artifact', run['id']) - self.access.require('expose-holdout', 'project_history.disclosure', run['id']) - origin = run['dataset_id'] - digest = self.history.payload_set_sha256(run['id'], origin_catalog_id=origin) - actor = self.access._context().actor_id - if (actor, origin, run['id'], digest) not in self._disclosures: - raise WorkbenchError('Explicitly disclose this retained Run under current local authority first.', - 'forbidden', 403) - - def disclose(self, run_id, body, expected_checkpoint, key): - with self.access.lock, self.session.lock, self.db.lock: - result = self.history.record_disclosure(run_id, body, expected_checkpoint, key) - actor = self.access._context().actor_id - self._disclosures.add((actor, result['origin_catalog_id'], run_id, result['payload_set_sha256'])) - return result - - def reconcile_inert(self, snapshot): - """Rebuild selected science after actual local custody has drained. - - This preserves existing local Run/admission rows solely for the current - reconciler's terminal proof. No imported authority table is populated. - """ - execution = self.execution - with self.access.lock, self.session.lock, self.db.lock: - if execution._reconstructing: - raise RuntimeError('Project reconstruction already has an owner.') - execution._reconstructing = True - try: - self.session.reconcile_selection(snapshot) - execution.abandon_pending() - self.study_execution.abandon_pending() - execution.producer_execution.abandon_pending() - self.producers.refresh(snapshot) - self.data.restore(snapshot) - self.materials.reconcile_projection() - self.study_execution.restore_authoring(snapshot['records']) - except BaseException: - self.session.available = False - raise - finally: - execution._reconstructing = False - - def close(self): - execution = getattr(self, 'execution', None) - if execution is not None: - execution.close() - if self.sources is not None: - self.sources.close() - self.artifacts.close() - self._disclosures.clear() - self.db.close() - - -class _TextView: - """Preserve the M1 text wire projection over the complete data owner.""" - def __init__(self, projection): - self.projection = projection - - @property - def available(self): - return self.projection.session.available - - def _tag(self, value): - summary = self.projection.session.summary - return dict(value, project_id=summary['project_id'], checkpoint=summary['checkpoint']) - - def records(self): - self.projection.session.check_current() - from project_fork import active_records - snapshot = self.projection.session.snapshot - records = active_records(snapshot['records'], project_id=snapshot['project_id'], - families=frozenset(('workbench_record', 'workbench_text'))) - return self._tag(dict(items=[copy.deepcopy(item['document']['current']) for item in records - if item['family'] in ('workbench_record', 'workbench_text') - and item['document']['current']['kind'] == 'text'])) - - def get(self, identity): - result = self.projection.data.get(identity) - if result['kind'] != 'text': - raise WorkbenchError('Use the modality-aware data operation for this record.', 'unsupported', 409) - return self._tag(result) - - def history(self, identity): - self.get(identity) - return self.projection.data.history(identity) - - def import_text(self, body, expected_checkpoint, key): - return self._tag(self.projection.data.import_text(body, expected_checkpoint, key)) - - def annotate(self, identity, body, expected_checkpoint, key): - self.get(identity) - return self._tag(self.projection.data.annotate(identity, body, expected_checkpoint, key)) diff --git a/project_record_dedupe.py b/project_record_dedupe.py deleted file mode 100644 index aff3948d..00000000 --- a/project_record_dedupe.py +++ /dev/null @@ -1,124 +0,0 @@ -"""Physical deduplication of retained runtime closures in Run history records. - -Retained external-recipe Runs each embed the same captured runtime closure three -times: run.spec.runtime_files, run.material.runtime and a contiguous block of -'historical_runtime' payload edges (about 2.5 MB per Run). The store keeps one -content-addressed `run_runtime_closure` record and a compact Run document -(`project_run_history_v2`) that references it. Stores expand compact Runs back -to the exact logical v1 document on read, so domain owners and validators see -unchanged documents. A Run is compacted only when expansion reproduces its -canonical bytes exactly. -""" -import copy -import hashlib - -RUN_FAMILY = 'run_history' -RUN_V1 = 'project_run_history_v1' -RUN_V2 = 'project_run_history_v2' -CLOSURE_FAMILY = 'run_runtime_closure' -CLOSURE_FORMAT = 'project_run_runtime_closure_v1' -RUNTIME_ROLE = 'historical_runtime' - - -def _encode(value): - from project_store import _encode as canonical - return canonical(value) - - -def closure_id(closure): - """Content address of a closure document.""" - return hashlib.sha256(_encode(closure)).hexdigest() - - -def compact(document): - """(compact v2 document, closure document) or None when not exactly reversible.""" - if type(document) is not dict or document.get('format') != RUN_V1: - return None - run = document.get('run') - payloads = document.get('payloads') - if type(run) is not dict or type(payloads) is not list: - return None - spec, material = run.get('spec'), run.get('material') - if (type(spec) is not dict or type(material) is not dict or 'runtime_files' not in spec - or 'runtime' not in material or 'runtime_closure' in document): - return None - positions = [index for index, edge in enumerate(payloads) - if type(edge) is dict and edge.get('role') == RUNTIME_ROLE] - if not positions or positions != list(range(positions[0], positions[-1] + 1)): - return None - start, end = positions[0], positions[-1] + 1 - closure = dict(format=CLOSURE_FORMAT, runtime_files=copy.deepcopy(spec['runtime_files']), - runtime=copy.deepcopy(material['runtime']), payload_block=copy.deepcopy(payloads[start:end])) - reduced = copy.deepcopy(document) - del reduced['run']['spec']['runtime_files'] - del reduced['run']['material']['runtime'] - reduced['payloads'] = reduced['payloads'][:start] + reduced['payloads'][end:] - reduced['format'] = RUN_V2 - reduced['runtime_closure'] = dict(id=closure_id(closure), payload_index=start) - if _encode(expand(reduced, closure)) != _encode(document): - return None - return reduced, closure - - -def expand(document, closure): - """The exact logical v1 Run document of a compact v2 document.""" - reference = document['runtime_closure'] - if closure.get('format') != CLOSURE_FORMAT or closure_id(closure) != reference['id']: - from project_store import _fail - _fail('Run runtime closure differs from its reference.') - result = copy.deepcopy(document) - del result['runtime_closure'] - result['format'] = RUN_V1 - result['run']['spec']['runtime_files'] = copy.deepcopy(closure['runtime_files']) - result['run']['material']['runtime'] = copy.deepcopy(closure['runtime']) - index = reference['payload_index'] - if type(index) is not int or not 0 <= index <= len(result['payloads']): - from project_store import _fail - _fail('Invalid Run runtime closure position.') - result['payloads'] = result['payloads'][:index] + copy.deepcopy(closure['payload_block']) + result['payloads'][index:] - return result - - -def is_compact(family, document): - return family == RUN_FAMILY and type(document) is dict and document.get('format') == RUN_V2 - - -def logical_records(physical): - """Logical envelopes of physical records: closures hidden, compact Runs expanded.""" - closures = {item['id']: item['document'] for item in physical if item['family'] == CLOSURE_FAMILY} - result = [] - for item in physical: - if item['family'] == CLOSURE_FAMILY: - continue - document = item['document'] - if is_compact(item['family'], document): - closure = closures.get(document['runtime_closure']['id']) - if closure is None: - from project_store import _fail - _fail('Compact Run references a missing runtime closure.') - document = expand(document, closure) - result.append(dict(family=item['family'], id=item['id'], document=document)) - return result - - -def physical_records(logical, *, existing_closures=None): - """Physical envelopes for logical records, compacting Runs where exact. - - existing_closures maps closure id -> document already stored; compacted - Runs reference them and every referenced closure is included once. - """ - closures = dict(existing_closures or {}) - used = set() - result = [] - for item in logical: - document = item['document'] - if item['family'] == RUN_FAMILY: - compacted = compact(document) - if compacted is not None: - document, closure = compacted - identity = document['runtime_closure']['id'] - closures.setdefault(identity, closure) - used.add(identity) - result.append(dict(family=item['family'], id=item['id'], document=document)) - result.extend(dict(family=CLOSURE_FAMILY, id=identity, document=closures[identity]) for identity in sorted(used)) - return sorted(result, key=lambda item: (item['family'], item['id'])) diff --git a/project_runtime.py b/project_runtime.py deleted file mode 100644 index d14c59d4..00000000 --- a/project_runtime.py +++ /dev/null @@ -1,320 +0,0 @@ -"""Explicit current-host CPU runtime capture through a canonical effect intent. - -Open never constructs this adapter's filesystem capabilities from retained roots. -The injected resolver supplies current trusted local configuration only. Captured -binaries remain an ignored local cache; portable metadata declares exact bytes. -""" -import copy -from datetime import datetime -import hashlib -import os - -import agent_api -from model_definitions import reference -from project_material import decode_records as material_records -from project_session import operation_records, REQUEST_KEY, _digest as operation_digest -from runtime_snapshots import RuntimeSnapshots, DEFAULT_RESERVE, MAX_FILES, MAX_BYTES, MAX_MANIFEST -from workbench import WorkbenchError, timestamp -from project_session import session_operations - -OPERATIONS = frozenset(('runtime.capture_intent', 'runtime.capture', 'runtime.abandon')) -RESULT_FIELDS = frozenset(('format','project_id','manifest_sha256','file_count','total_bytes', - 'actor_id','observed_at','request_key')) - - -def _fail(message, code='invalid', status=400): - raise WorkbenchError(message, code, status) - - -def _sha(value): - if type(value) is not str or len(value) != 64 or any(c not in '0123456789abcdef' for c in value): - _fail('Runtime capture requires an exact SHA256.') - - -def _id(value): - if type(value) is not str or len(value) != 32 or any(c not in '0123456789abcdef' for c in value): - _fail('Runtime capture requires a project or actor UUID.') - - -def _key(value): - if type(value) is not str or not REQUEST_KEY.fullmatch(value): - _fail('Invalid runtime capture request key.') - - -def _intent_key(key): - return 'runtime-intent.' + hashlib.sha256(key.encode('utf-8')).hexdigest() - - -def _body(config_request, expected_inventory_sha256, reserve_bytes): - _sha(expected_inventory_sha256) - if type(reserve_bytes) is not int or not 0 <= reserve_bytes <= 2**63-1: - _fail('Runtime capture reserve must be a nonnegative integer.') - try: - if type(config_request) is not dict or len(agent_api.encoded(config_request)) > 65536: - raise ValueError() - except (agent_api.AgentAPIError, TypeError, ValueError, RecursionError, UnicodeError): - _fail('Runtime capture requires a bounded current-local configuration request.') - return dict(configuration=copy.deepcopy(config_request), expected_inventory_sha256=expected_inventory_sha256, - reserve_bytes=reserve_bytes) - - -def _intent_input(body): - """Use the canonical intent owner's exact request identity for local custody.""" - return operation_digest(dict(operation='runtime.capture_intent', - target=body['expected_inventory_sha256'], body=body)) - - -def _summary(project_id, observed, actor_id, key, *, runtime_ref=None): - value = dict(format='project_runtime_capture_intent_v1' if runtime_ref is None else 'project_runtime_capture_v1', - project_id=project_id,manifest_sha256=observed['inventory_sha256'],file_count=observed['file_count'], - total_bytes=observed['total_bytes'],actor_id=actor_id,observed_at=timestamp(),request_key=key) - if runtime_ref is not None: value['runtime_ref'] = copy.deepcopy(runtime_ref) - return value - - -def validate_operation_result(operation, result, records=None): - """Validate inert capture facts; no retained path becomes a local binding.""" - if operation not in OPERATIONS: return False - try: - if operation == 'runtime.abandon': - fields = {'format','project_id','capture_key','input_sha256','manifest_sha256', - 'actor_id','reason','observed_checkpoint','observed_at'} - if type(result) is not dict or set(result) != fields or result['format'] != 'project_runtime_capture_abandon_v1': - _fail('Invalid runtime abandonment observation.') - _id(result['project_id']); _id(result['actor_id']); _key(result['capture_key']) - for field in ('input_sha256','manifest_sha256','observed_checkpoint'): _sha(result[field]) - if type(result['reason']) is not str or not result['reason'].strip() or len(result['reason']) > 1000: - _fail('Runtime abandonment requires the retained owner reason.') - if type(result['observed_at']) is not str or datetime.fromisoformat(result['observed_at']).utcoffset() is None: - _fail('Runtime abandonment requires an offset timestamp.') - if records is not None: - intents = [r['document'] for r in records if r['family']=='project_operation' - and r['document']['operation']=='runtime.capture_intent' - and r['document']['request_key']==_intent_key(result['capture_key']) - and r['document']['input_sha256']==result['input_sha256'] - and r['document']['result'].get('project_id')==result['project_id'] - and r['document']['result'].get('manifest_sha256')==result['manifest_sha256']] - if len(intents) != 1: _fail('Runtime abandonment has no exact original capture intent.') - if any(r['family']=='project_operation' - and r['document']['operation']=='runtime.capture' - and r['document']['request_key']==result['capture_key'] - and r['document']['result'].get('project_id')==result['project_id'] - for r in records): - _fail('Completed runtime capture cannot be abandoned.') - return True - complete = operation == 'runtime.capture' - fields = RESULT_FIELDS | ({'runtime_ref'} if complete else set()) - if type(result) is not dict or set(result) != fields: - _fail('Invalid runtime capture observation fields.') - expected_format = 'project_runtime_capture_v1' if complete else 'project_runtime_capture_intent_v1' - if result['format'] != expected_format: _fail('Unsupported runtime capture observation.') - _id(result['project_id']); _id(result['actor_id']); _sha(result['manifest_sha256']); _key(result['request_key']) - if (type(result['file_count']) is not int or not 1 <= result['file_count'] <= MAX_FILES or - type(result['total_bytes']) is not int or not 0 <= result['total_bytes'] <= MAX_BYTES): - _fail('Runtime capture observation exceeds the owner inventory bounds.') - instant = result['observed_at'] - if type(instant) is not str or len(instant) > 80 or datetime.fromisoformat(instant).utcoffset() is None: - _fail('Runtime capture observation requires an offset timestamp.') - if not complete: return True - ref = reference(result['runtime_ref'], 'runtime', result['project_id']) - if records is None: return True - doc = material_records(records).get(('runtime_material', result['project_id']+'.'+ref['sha256'])) - descriptor = None if doc is None else doc['value']['descriptor'] - if (doc is None or doc['value']['ref'] != ref or descriptor is None or - descriptor['profile'] != 'captured_cpu_python_v1' or - any(descriptor[field] != result[field] for field in ('manifest_sha256','file_count','total_bytes'))): - _fail('Runtime capture observation differs from its exact retained material.') - declarations = {r['id']:r['document'] for r in records if r['family']=='project_artifact'} - for edge in doc['artifacts']: - if declarations.get(edge['blob']['sha256']) != dict(format='project_artifact_v1', **edge['blob']): - _fail('Runtime capture lacks its complete exact artifact declarations.') - intents = [r['document']['result'] for r in records if r['family']=='project_operation' - and r['document']['operation']=='runtime.capture_intent' - and r['document']['request_key']==_intent_key(result['request_key'])] - matching = [intent for intent in intents if all(intent.get(field)==result[field] - for field in ('project_id','manifest_sha256','file_count','total_bytes','request_key'))] - if len(matching) != 1: _fail('Runtime capture lacks its unique durable publication intent.') - validate_operation_result('runtime.capture_intent', matching[0]) - return True - except WorkbenchError: raise - except (ValueError, TypeError, KeyError, AttributeError, OverflowError, RecursionError): - _fail('Malformed runtime capture observation.') - - -class ProjectRuntime: - def __init__(self, projection, *, resolve_configuration): - if not callable(resolve_configuration): - raise TypeError('An explicit current-local runtime configuration resolver is required.') - self.projection = projection - self.session, self.db, self.access = projection.session, projection.db, projection.access - self.execution, self.materials = projection.execution, projection.materials - self.resolve_configuration = resolve_configuration - self.owner = RuntimeSnapshots(self.db, self.execution.runtime_access, self.db.path) - - def _authorize(self, action): - return self.access.require('admin', action, owner_only=True) - - def inspect(self, config_request): - """Read an explicitly selected current source; never provision or execute.""" - with self.access.lock, self.session.lock, self.db.lock: - self._authorize('runtime_snapshots.inspect'); self.session.check_current() - _body(config_request, '0'*64, 0) - with self.execution.runtime_inspection(): - return self.owner.inspect(self.resolve_configuration(copy.deepcopy(config_request))) - - def status(self, key): - """Read historical outcome only; captured does not claim local readiness.""" - _key(key) - with self.access.lock, self.session.lock, self.db.lock: - self.access.require('inspect', 'runtime.capture_status'); self.session.check_current() - receipts = session_operations(self.session) - intent = receipts.get(_intent_key(key)); complete = receipts.get(key) - if intent is not None and intent['operation'] != 'runtime.capture_intent': intent = None - if complete is not None and complete['operation'] != 'runtime.capture': complete = None - abandoned = next((r['result'] for r in receipts.values() if r['operation']=='runtime.abandon' - and r['result']['capture_key']==key), None) - if abandoned is not None: - return dict(state='abandoned',intent=copy.deepcopy(intent['result']) if intent else None, - result=None,abandonment=copy.deepcopy(abandoned)) - return dict(state='captured' if complete else 'intent_recorded' if intent else 'absent', - intent=copy.deepcopy(intent['result']) if intent else None, - result=copy.deepcopy(complete['result']) if complete else None) - - def recover_capture(self, config_request, expected_inventory_sha256, expected_checkpoint, key, *, reserve_bytes=DEFAULT_RESERVE): - """Explicitly restore one original local copy before its exact retry.""" - body = _body(config_request, expected_inventory_sha256, reserve_bytes) - body_sha = _intent_input(body) - self._authorize('runtime_snapshots.create') - self.execution.prepare_runtime_reconciliation(key, body_sha, expected_inventory_sha256, expected_checkpoint) - return self.capture(config_request, expected_inventory_sha256, self.session.summary['checkpoint'], key, - reserve_bytes=reserve_bytes) - - def abandon(self, capture_key, reason, expected_checkpoint, key): - """Preserve partial bytes and acknowledge one stopped local copy.""" - _key(capture_key); _key(key); _sha(expected_checkpoint) - if key == capture_key or type(reason) is not str or not reason.strip() or len(reason) > 1000: - _fail('Use a separate abandonment key and a retained reason.') - actor = self._authorize('runtime.capture_abandon') - body = dict(capture_key=capture_key, reason=reason, actor_id=actor.actor_id) - marker = self.execution.runtime_pending(capture_key) - if marker is None: - # Pure receipt replay cannot clear a local writer or run anything. - def forbidden(): _fail('No original local runtime copy exists to abandon.', 'unavailable', 409) - return self.session.mutate('runtime.abandon', capture_key, body, expected_checkpoint, key, - forbidden, lambda *args: forbidden(), scope='admin') - with self.execution.runtime_reconciliation(capture_key, marker['input_sha256'], - marker['manifest_sha256'], expected_checkpoint) as guard: - receipts = session_operations(self.session) - intent = receipts.get(_intent_key(capture_key)) - if (intent is None or intent['operation']!='runtime.capture_intent' - or intent['input_sha256']!=marker['input_sha256'] - or intent['result']['project_id']!=self.session.project_id - or intent['result']['manifest_sha256']!=marker['manifest_sha256']): - _fail('Runtime intent differs from its exact original local writer.', 'conflict', 409) - if capture_key in receipts: - _fail('Capture completed; reconcile its acknowledgement with the exact capture request.', 'conflict', 409) - observed = self.session.summary['checkpoint'] - def invoke(): - current = self._authorize('runtime.capture_abandon') - if current.actor_id != actor.actor_id: _fail('Runtime abandonment caller changed.', 'conflict', 409) - return dict(format='project_runtime_capture_abandon_v1',project_id=self.session.project_id, - capture_key=capture_key,input_sha256=marker['input_sha256'],manifest_sha256=marker['manifest_sha256'], - actor_id=actor.actor_id,reason=reason,observed_checkpoint=observed,observed_at=timestamp()) - result = self.session.mutate('runtime.abandon', capture_key, body, observed, key, invoke, - lambda value,before:dict(records=[],result=value),scope='admin') - guard.confirmed() - return result - - def _barrier(self, descriptor): - # Native creation fsyncs all staged files before its atomic rename. This - # explicit barrier also closes a previous parent-fsync unknown outcome. - from runtime_snapshots import sync_directory - root = self.owner.path / descriptor['manifest_sha256'] - if descriptor['root'] != str(root): _fail('Current runtime binding differs.', 'stale', 409) - for directory in (root, self.owner.path, self.owner.path.parent): sync_directory(directory) - - def _replay(self, key, body, expected_checkpoint): - def forbidden(): _fail('Runtime replay has no canonical receipt.', 'unavailable', 409) - return self.session.mutate('runtime.capture', body['expected_inventory_sha256'], body, - expected_checkpoint, key, forbidden, lambda *args: forbidden(), scope='admin') - - def capture(self, config_request, expected_inventory_sha256, expected_checkpoint, key, *, reserve_bytes=DEFAULT_RESERVE): - """Explicitly capture bytes after durable intent and current quiescence. - - The resolver is trusted current-host configuration authority. It must not - derive source directories from canonical descriptors or historical roots. - """ - _key(key); _sha(expected_checkpoint) - body = _body(config_request, expected_inventory_sha256, reserve_bytes) - body_sha = _intent_input(body) - intent = None - with self.access.lock, self.session.lock, self.db.lock: - actor = self._authorize('runtime_snapshots.create'); self.session.check_current() - receipts = session_operations(self.session) - if any(r['operation']=='runtime.abandon' and r['result']['capture_key']==key for r in receipts.values()): - _fail('This capture was abandoned; use a fresh key for a new measurement.', 'conflict', 409) - if (_intent_key(key) in receipts and key not in receipts - and self.execution.runtime_pending(key) is None): - _fail('This incomplete capture intent is inert history; use a fresh key for a new capture.', 'unavailable', 409) - try: - with self.execution.runtime_effect(key, body_sha, expected_inventory_sha256) as guard: - receipts = session_operations(self.session) - if key in receipts: - result = self._replay(key, body, expected_checkpoint) - descriptor = self.owner.get(expected_inventory_sha256) - from pipeline import digest - if digest(descriptor) != result['runtime_ref']['sha256']: - _fail('Acknowledged runtime belongs to a different local binding; capture with a new key.', 'unavailable', 409) - guard.publication_started() - self._barrier(descriptor); guard.confirmed() - return result - config = None - if _intent_key(key) in receipts: - def invalid(): _fail('Runtime intent replay is unavailable.', 'unavailable', 409) - intent = self.session.mutate('runtime.capture_intent', expected_inventory_sha256, body, - expected_checkpoint, _intent_key(key), invalid, lambda *args: invalid(), scope='admin') - else: - if expected_checkpoint != self.session.summary['checkpoint']: - _fail('Expected project checkpoint changed.', 'stale_project', 409) - config = self.resolve_configuration(copy.deepcopy(config_request)) - observed = self.owner.inspect(config) - if observed['inventory_sha256'] != expected_inventory_sha256: - _fail('Runtime inventory changed after inspection.', 'stale', 409) - intent = self.session.mutate('runtime.capture_intent', expected_inventory_sha256, body, - expected_checkpoint, _intent_key(key), - lambda:_summary(self.session.summary['project_id'], observed, actor.actor_id, key), - lambda result,before:dict(records=[],result=result), scope='admin') - guard.publication_started() - if os.path.lexists(self.owner.path / expected_inventory_sha256): - descriptor = self.owner.get(expected_inventory_sha256) - else: - if config is None: config = self.resolve_configuration(copy.deepcopy(config_request)) - descriptor = self.owner.create(config, expected_inventory_sha256, quiesced=True, reserve_bytes=reserve_bytes) - self._barrier(descriptor) - from recipe_process import read_regular, decode - from pipeline import digest - from pathlib import Path - raw = read_regular(Path(descriptor['root'])/'manifest.json', MAX_MANIFEST) - runtime_ref = dict(kind='runtime',catalog_id=self.session.summary['project_id'], - id=digest(descriptor),sha256=digest(descriptor)) - value = dict(ref=runtime_ref,descriptor=descriptor,environment=None,manifest=decode(raw)) - observed = dict(inventory_sha256=descriptor['manifest_sha256'],file_count=descriptor['file_count'],total_bytes=descriptor['total_bytes']) - def capture(result, before): - record = self.materials.capture_runtime(value, raw) - return dict(records=[*self.materials.declarations(record),record],result=result) - result = self.session.mutate('runtime.capture', expected_inventory_sha256, body, - self.session.summary['checkpoint'], key, - lambda:_summary(self.session.summary['project_id'], observed, actor.actor_id, key, runtime_ref=runtime_ref), capture, scope='admin') - guard.confirmed() - return result - except BaseException as error: - if isinstance(error, (OSError, RuntimeError)): - failure = WorkbenchError('Runtime capture outcome requires explicit same-key reconciliation.', - 'outcome_unknown' if intent else 'unavailable', 503) - else: failure = error - if intent is not None and not hasattr(failure, 'receipt'): - snapshot = self.session.snapshot - failure.receipt = dict(committed=True,selected=True,project_id=snapshot['project_id'], - checkpoint=snapshot['checkpoint'],request_key=key) - if failure is error: raise - raise failure from error diff --git a/project_session.py b/project_session.py deleted file mode 100644 index cfd60555..00000000 --- a/project_session.py +++ /dev/null @@ -1,656 +0,0 @@ -"""Canonical publication shared by the fixed external-project domain owners. - -The supplied validator composes those owners' closed codecs and reference -closure. This boundary owns transaction ordering and receipts, not domain policy. -""" -import copy -import hashlib -import re -import threading - -import agent_api -from project_store import copy_validated_json -from workbench import WorkbenchError - - -OPERATION_FAMILY = 'project_operation' -OPERATION_FORMAT = 'project_operation_v2' -REQUEST_KEY = re.compile(r'^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$') -SHA = re.compile(r'^[a-f0-9]{64}$') -OPERATION = re.compile(r'^[a-z][a-z0-9_.]{0,119}$') - - -class ProjectSessionError(WorkbenchError): - pass - - -def _digest(value): - return hashlib.sha256(agent_api.encoded(value)).hexdigest() - - -def operation_documents(records): - """Validate all historical receipts without collapsing independent keys.""" - result, seen = [], set() - for envelope in records: - if envelope['family'] != OPERATION_FAMILY: - continue - value = envelope['document'] - base = {'format', 'operation', 'target', 'request_key', 'input_sha256', 'result'} - namespaced = type(value) is dict and value.get('format') == 'project_operation_v2' - if (type(value) is not dict or set(value) != base | ({'project_id'} if namespaced else set()) - or value['format'] not in ('project_operation_v1', 'project_operation_v2') - or type(value['operation']) is not str or not OPERATION.fullmatch(value['operation']) - or value['target'] is not None and (type(value['target']) is not str or len(value['target']) > 512) - or type(value['request_key']) is not str or not REQUEST_KEY.fullmatch(value['request_key']) - or type(value['input_sha256']) is not str or not SHA.fullmatch(value['input_sha256'])): - raise ProjectSessionError('Invalid canonical project operation receipt.') - identity = hashlib.sha256(value['request_key'].encode('utf-8')).hexdigest() - if namespaced: - if type(value['project_id']) is not str or not re.fullmatch('[a-f0-9]{32}', value['project_id']): - raise ProjectSessionError('Invalid project operation namespace.') - identity = value['project_id'] + '.' + identity - if envelope['id'] != identity or identity in seen: - raise ProjectSessionError('Invalid or duplicate canonical project operation identity.') - seen.add(identity) - if len(agent_api.encoded(value['result'])) > agent_api.RESPONSE_LIMIT: - raise ProjectSessionError('Canonical operation result exceeds its transport bound.', 'too_large', 413) - result.append(copy.deepcopy(value)) - return result - - -def operation_records(records, *, project_id=None): - """Current request keys are independent of exactly retained fork history.""" - operation_documents(records) - from project_fork import active_records, decode_fork - overlay = decode_fork(records, project_id=project_id) - if project_id is None and overlay is not None: - project_id = overlay['destination_project_id'] - result = {} - for value in operation_documents(active_records(records, project_id=project_id, - families=frozenset({OPERATION_FAMILY}))): - if overlay is not None and value['format'] == 'project_operation_v1': - raise ProjectSessionError('A fork must retain legacy operation receipts as archived historical facts.') - if project_id is not None and value.get('project_id', project_id) != project_id: - raise ProjectSessionError('Active project operation belongs to another namespace.') - if value['request_key'] in result: - raise ProjectSessionError('Duplicate active project operation request key.') - result[value['request_key']] = value - return result - - -class ProjectSession: - # Sessions over a database working copy hold no record set (see __init__). - _lazy = False - - def __init__(self, store, db, access, artifacts, *, validate_records, validation_cache=None): - if not callable(validate_records): - raise TypeError('A complete owner-codec validator is required.') - self.store, self.db, self.access, self.artifacts = store, db, access, artifacts - self.lock = threading.RLock() - self._validate = validate_records - self.validation_cache = validation_cache - # Checkpoint whose exact records passed complete domain validation. - self.validated_checkpoint = None - self.available = False - self._snapshot = None - self.project_id = store.summary()['project_id'] - self.extra_capture = None - self.publication_intent = None - self.runtime_access = None - self._foreground_publication = False - self._pending_observation = None - self._recovery_records = None - self._recovery_request = None - # A database working copy serves record reads directly; the session - # then binds checkpoint metadata only and holds no record set. - self._lazy = callable(getattr(store, 'records_view', None)) - if self._lazy: - self._adopt_working_copy() - else: - self.adopt(store.snapshot(), _owned=True) - - def _adopt_working_copy(self): - """Bind the working copy's checkpoint; validate its records only if unknown.""" - with self.access.lock, self.lock, self.db.lock: - summary = self.store.summary() - cache = getattr(self, 'validation_cache', None) - if cache is not None and cache.known(self.project_id, summary['checkpoint']): - self.validated_checkpoint = summary['checkpoint'] - else: - snapshot = self.store.snapshot() - if snapshot['checkpoint'] != summary['checkpoint']: - raise ProjectSessionError('Project changed while binding its projection.', 'stale_project', 409) - with self._known_envelopes(snapshot['records']): - self._validated(snapshot['records'], snapshot['checkpoint']) - del snapshot - if self.store.summary()['checkpoint'] != summary['checkpoint']: - raise ProjectSessionError('Project changed while binding its projection.', 'stale_project', 409) - self._bind(summary) - self.available = True - - def _known_envelopes(self, records, changed=frozenset()): - """Validation context with stored envelope digests for unchanged records.""" - from contextlib import nullcontext - if not self._lazy or not callable(getattr(self.store, 'envelope_digests', None)): - return nullcontext() - from project_composition import known_envelope_digests - digests = self.store.envelope_digests() - known = {} - for record in records: - identity = (record['family'], record['id']) - if identity not in changed and identity in digests and digests[identity] is not None: - known[id(record)] = (record, digests[identity]) - return known_envelope_digests(known) - - def _edit_scope(self, base_checkpoint, changed, operations=(), base_records=None): - """Validate only what this edit can affect when its base is validated. - - The candidate is the base checkpoint's records plus changed identities - (never deletions); see project_validation_delta. - """ - from contextlib import nullcontext - if getattr(self, 'validated_checkpoint', None) != base_checkpoint: - return nullcontext() - from project_validation_delta import ValidationDelta, edit_delta - base = set() if base_records is None else {(item['family'], item['id']) for item in base_records} - added = frozenset(identity for identity in changed if base_records is not None and identity not in base) - return edit_delta(ValidationDelta(frozenset(changed), frozenset(operations), added)) - - def _bind(self, snapshot): - """Bind a committed checkpoint; a lazy session keeps only its metadata.""" - if self._lazy: - self._snapshot = dict(project_id=snapshot['project_id'], name=snapshot['name'], - checkpoint=snapshot['checkpoint'], records=None) - else: - self._snapshot = snapshot - - def _fresh_store(self): - """The working copy must still be at the bound checkpoint.""" - if self.store.summary()['checkpoint'] != self._snapshot['checkpoint']: - raise ProjectSessionError('Canonical project changed. Close and reopen it.', 'stale_project', 409) - return self.store - - @property - def foreground_publication(self): - return self._foreground_publication - - @staticmethod - def _merge(records, upserts, *, owned=False): - """Candidate record map: base records plus copied upserts. - - owned=True means the caller owns these base records (a fresh working - copy read), so they are used without another whole-project copy. - """ - merged = ({(item['family'], item['id']): item for item in records} if owned else - {(item['family'], item['id']): copy.deepcopy(item) for item in records}) - seen = {} - for item in upserts: - if type(item) is not dict or set(item) != {'family', 'id', 'document'}: - raise ProjectSessionError('Invalid owned project envelope.') - identity = (item['family'], item['id']) - if item['family'] == OPERATION_FAMILY: - raise ProjectSessionError('Owned capture cannot replace a project operation receipt.') - if identity in seen and seen[identity] != item: - raise ProjectSessionError('Owned captures disagree about the same project record.') - seen[identity] = item - merged[identity] = copy.deepcopy(item) - return merged - - def _publish_observation(self, records, key, digest, *, authorize): - """Publish fixed background science while its owned SQL TX is open. - - This is a private trusted-owner seam, not a transport operation or an - imported receipt capability. The callback verifies current local job - custody/admission. SQL outcome selects or fences the resulting cache. - """ - if (self.foreground_publication or not self.db.in_transaction - or not self.db.lock.depth or self._pending_observation is not None): - raise ProjectSessionError('Background publication requires its own outer project transaction.') - if (type(records) is not list or type(key) is not str or not REQUEST_KEY.fullmatch(key) - or type(digest) is not str or not SHA.fullmatch(digest) or not callable(authorize)): - raise ProjectSessionError('Invalid background publication identity.') - authorize() - current = self.check() - merged = self._merge(current['records'], records, owned=self._lazy) - candidate = [merged[identity] for identity in sorted(merged)] - changed = {(item['family'], item['id']) for item in records} - with self._known_envelopes(candidate, changed), \ - self._edit_scope(current['checkpoint'], changed, base_records=current['records']): - self._validated(candidate) - if self.publication_intent is not None: - self.publication_intent(copy.deepcopy(current), copy.deepcopy(candidate), key, digest) - try: - if self._lazy: - changed = {(item['family'], item['id']) for item in records} - self._pending_observation = self.store.commit(candidate, current['checkpoint'], key, digest, - changed=changed) - else: - self._pending_observation = self.store.commit(candidate, current['checkpoint'], key, digest) - except BaseException as error: - if getattr(error, 'code', None) in ('unknown', 'outcome_unknown'): - self.available = False - self._recovery_records = copy.deepcopy(candidate) - self._recovery_request = (key, digest) - raise - self._remember_validated(self._pending_observation['checkpoint']) - return copy.deepcopy(self._pending_observation) - - def _observation_outcome(self, outcome): - if outcome not in ('committed', 'rolled_back', 'unknown'): - raise ValueError('Invalid project SQL outcome.') - pending, self._pending_observation = self._pending_observation, None - if pending is not None and self._atomic_store() and outcome == 'rolled_back': - # The record commit rolled back with the SQL transaction, so the - # bound checkpoint is still exactly current. Background local - # effects (for example a live phase) may have advanced, so their - # custody is reconciled explicitly before further use. A foreground - # mutate reports its own definite rollback and stays available. - if not self._foreground_publication: - self.available = False - return - if pending is not None: - self._bind(pending) - if outcome != 'committed': - self.available = False - if outcome == 'unknown': - self.available = False - - def _atomic_store(self): - """Whether record commits share this session's SQL transactions.""" - bound = getattr(self.store, '_db', None) - return bound is not None and bound is self.db - - def reconcile_selection(self, snapshot): - """Bind only this owner's selected or uncertain publication, never a checkout. - - The execution controller first proves local cessation. Callers retain - all ordered guards until fixed inert reconstruction succeeds or fences. - """ - with self.access.lock, self.lock, self.db.lock: - if self._lazy: - known = all(snapshot[key] == self._snapshot[key] for key in ('project_id', 'name', 'checkpoint')) - else: - known = snapshot == self._snapshot - attempted = (self._recovery_records is not None - and snapshot['project_id'] == self._snapshot['project_id'] - and snapshot['name'] == self._snapshot['name'] - and snapshot['records'] == self._recovery_records - and self._recovery_request is not None - and self.store.reconcile(*self._recovery_request) is not None) - if not known and not attempted: - raise ProjectSessionError('Canonical selection differs from this local execution outcome.', 'stale_project', 409) - self.adopt(snapshot) - self._recovery_records = None - self._recovery_request = None - - @property - def summary(self): - """Scalar metadata for the same bound checkpoint as snapshot.""" - with self.lock: - return {key: self._snapshot[key] for key in ('project_id', 'name', 'checkpoint')} - - @property - def snapshot(self): - with self.lock: - if self._lazy: - # Complete independent record set from the working copy (costly). - current = self._fresh_store().snapshot() - if current['checkpoint'] != self._snapshot['checkpoint']: - raise ProjectSessionError('Canonical project changed. Close and reopen it.', 'stale_project', 409) - return current - return copy_validated_json(self._snapshot) - - def records(self, *families): - """Independent copies of only the selected families at the bound checkpoint. - - Equivalent to filtering a complete snapshot copy, without copying the - unselected families (most bytes are usually retained Run history). - """ - if not families or any(type(family) is not str for family in families): - raise TypeError('Select one or more record families by name.') - selected = frozenset(families) - with self.lock: - if self._lazy: - return self._fresh_store().records(*families) - return copy_validated_json([item for item in self._snapshot['records'] - if item['family'] in selected]) - - def records_for(self, *families): - """Every bound record, in order, for one owner's pure decoder. - - Envelopes of the selected families are independent copies the owner - may keep or mutate. Every other envelope is a fresh envelope sharing its - verified document read-only, so fork/membership validators still see - the complete record set without copying unrelated Run history. Owners - must not mutate documents outside their selected families. - """ - if not families or any(type(family) is not str for family in families): - raise TypeError('Select one or more record families by name.') - selected = frozenset(families) - with self.lock: - if self._lazy: - # Unselected envelopes carry document None (identity only). - return self._fresh_store().records_view(*families) - return [copy_validated_json(item) if item['family'] in selected else - dict(family=item['family'], id=item['id'], document=item['document']) - for item in self._snapshot['records']] - - def active(self, *families, project_id=None): - """active_records for selected families over the bound checkpoint. - - Validates the complete fork history against every bound identity, but - copies only the selected active envelopes. - """ - if not families or any(type(family) is not str for family in families): - raise TypeError('Select one or more record families by name.') - from project_fork import active_records - with self.lock: - if self._lazy: - return active_records(self._fresh_store().records_view(*families, 'project_fork'), - project_id=self.project_id if project_id is None else project_id, - families=frozenset(families)) - return active_records(self._snapshot['records'], - project_id=self.project_id if project_id is None else project_id, - families=frozenset(families)) - - def derived(self, name, compute): - """Memoize one owner-derived read-only fact set per bound checkpoint. - - compute() must be a pure function of the bound records. Owners share - the result; they must copy any part they return or mutate. - """ - if type(name) is not str or not callable(compute): - raise TypeError('Derived facts need a name and a compute function.') - with self.lock: - checkpoint = self._snapshot['checkpoint'] - cache = getattr(self, '_derived_cache', None) - if cache is None or cache[0] != checkpoint: - cache = (checkpoint, {}) - self._derived_cache = cache - if name not in cache[1]: - value = compute() - if self._snapshot['checkpoint'] != checkpoint: - raise ProjectSessionError('Project changed while deriving facts.', 'stale_project', 409) - cache[1][name] = value - return cache[1][name] - - def record(self, family, record_id): - """An independent copy of one bound record envelope, or None.""" - if type(family) is not str or type(record_id) is not str: - raise TypeError('Select a record by family and ID.') - with self.lock: - if self._lazy: - return self._fresh_store().record(family, record_id) - index = getattr(self, '_record_index', None) - if index is None or index[0] != self._snapshot['checkpoint']: - index = (self._snapshot['checkpoint'], - {(item['family'], item['id']): item for item in self._snapshot['records']}) - self._record_index = index - found = index[1].get((family, record_id)) - return None if found is None else copy_validated_json(found) - - def operations(self, *, project_id=None): - """operation_records over the bound checkpoint, computed once per checkpoint. - - The bound records are immutable for a checkpoint, so the result is a - pure function of (checkpoint, project_id). Callers receive independent - copies, exactly as from operation_records(self.snapshot['records']). - """ - with self.lock: - key = (self._snapshot['checkpoint'], project_id) - cached = getattr(self, '_operations_cache', None) - if cached is None or cached[0] != key: - # operation_records copies what it returns and never mutates input. - records = (self._fresh_store().records_view(OPERATION_FAMILY, 'project_fork') if self._lazy - else self._snapshot['records']) - cached = (key, operation_records(records, project_id=project_id)) - self._operations_cache = cached - return copy.deepcopy(cached[1]) - - def _validated(self, records, checkpoint=None): - """Completely validate records; reuse an exact earlier success. - - checkpoint, when given, must be the Store checkpoint naming exactly - these records. Only then can a remembered validation be reused. - """ - cache = getattr(self, 'validation_cache', None) - if checkpoint is not None and cache is not None and cache.known(self.project_id, checkpoint): - self.validated_checkpoint = checkpoint - return - operation_records(records, project_id=self.project_id) - self._validate(records) - if checkpoint is not None: - self.validated_checkpoint = checkpoint - if cache is not None: - cache.remember(self.project_id, checkpoint) - - def _remember_validated(self, checkpoint): - # The caller completely validated exactly the records this names. - self.validated_checkpoint = checkpoint - cache = getattr(self, 'validation_cache', None) - if cache is not None: - cache.remember(self.project_id, checkpoint) - - def adopt(self, snapshot, *, _owned=False): - """Bind a fully validated checkpoint after inert reconstruction/cutover. - - The caller owns SQL reconstruction. This method never repairs or writes - canonical bytes, and is not authorization to trust an imported receipt. - _owned marks a snapshot this session just read from its own Store: its - checkpoint then names its records, so freshness is a checkpoint check - and the independent snapshot needs no second copy or full comparison. - """ - with self.access.lock, self.lock, self.db.lock: - if _owned: - self._validated(snapshot['records'], snapshot['checkpoint']) - if self.store.summary()['checkpoint'] != snapshot['checkpoint']: - raise ProjectSessionError('Project changed while binding its projection.', 'stale_project', 409) - self._bind(snapshot) - self.available = True - return - self._validated(snapshot['records']) - current = self.store.snapshot() - if current != snapshot: - raise ProjectSessionError('Project changed while binding its projection.', 'stale_project', 409) - self._remember_validated(snapshot['checkpoint']) - self._bind(copy_validated_json(snapshot) if not self._lazy else snapshot) - self.available = True - - def _checked(self, read): - if not self.available: - raise ProjectSessionError('Reopen this project to reconstruct its projection.', 'projection_unavailable', 503) - current = read() - if current['checkpoint'] != self._snapshot['checkpoint']: - raise ProjectSessionError('Canonical project changed. Close and reopen it.', 'stale_project', 409) - return current - - def check_current(self): - """Verify actual canonical bytes without returning an unused record graph. - - The caller holds the same host/session/projection guards as check(). - Store.summary reads and hashes all current records before returning. - """ - self._checked(self.store.summary) - - def check(self): - """Return independent current records under caller-owned projection guards.""" - return self._checked(self.store.snapshot) - - def check_records(self, family): - """Verify every canonical record, then copy one bound record family. - - The complete snapshot, including cross-family closure, was validated - and isolated by adopt/publication. Returned copies retain that validity - inside the trusted owner boundary; they are not new imported raw input. - Exact current bytes and checkpoint must still match before using it. - Callers hold the same ordered guards as check(); no cached alias escapes. - """ - if type(family) is not str: - raise TypeError('Record-family selection requires a string.') - current = self._checked(self.store.summary) - if self._lazy: - current['records'] = self.store.records(family) - return current - current['records'] = copy.deepcopy([ - item for item in self._snapshot['records'] if item['family'] == family]) - return current - - def mutate(self, operation, target, body, expected_checkpoint, key, invoke, capture, *, scope='edit'): - """Invoke existing policy, capture fixed-owner upserts, publish, commit SQL. - - invoke() returns the owner's result. capture(result, before_records) - returns {'records': upserts, 'result': original bounded domain result}. - Wrappers check any stronger scope/owner/disclosure requirement before - entering, including before replay. The supplied current scope belongs to - the wrapper's existing policy (for example freeze rather than edit). - """ - if (type(operation) is not str or not OPERATION.fullmatch(operation) - or target is not None and (type(target) is not str or len(target) > 512) - or type(key) is not str or not REQUEST_KEY.fullmatch(key) - or type(expected_checkpoint) is not str or not SHA.fullmatch(expected_checkpoint)): - raise ProjectSessionError('Invalid project mutation identity.') - digest = _digest(dict(operation=operation, target=target, body=body)) - committed = None - attempted_records = None - with self.access.lock, self.lock, self.db.lock: - self.access.require(scope, operation, target) - current = self.check() - if self.db.in_transaction: - raise ProjectSessionError('Project mutation must own its outer SQL transaction.', 'unavailable', 409) - receipts = operation_records(current['records']) - prior = receipts.get(key) - if prior is not None: - if prior['operation'] != operation or prior['input_sha256'] != digest or prior['target'] != target: - raise ProjectSessionError('Request key already has different input.', 'conflict', 409) - # The current composed codec validates the exact historical - # result too; receipt facts can never authorize execution. - self._validated(current['records'], current['checkpoint']) - return copy.deepcopy(prior['result']) - if self.store.reconcile(key, digest) is not None: - raise ProjectSessionError('Request key belongs to another canonical operation.', 'conflict', 409) - if expected_checkpoint != current['checkpoint']: - raise ProjectSessionError('Expected project checkpoint changed.', 'stale_project', 409) - try: - self._foreground_publication = True - with self.db.transaction(): - result = invoke() - # A working-copy read is already this mutation's own fresh - # copy; owner captures read it and copy what they change. - before = current['records'] if self._lazy else copy.deepcopy(current['records']) - captured = capture(result, before) - if type(captured) is not dict or set(captured) != {'records', 'result'} or type(captured['records']) is not list: - raise ProjectSessionError('Invalid owned project capture.') - if len(agent_api.encoded(captured['result'])) > agent_api.RESPONSE_LIMIT: - raise ProjectSessionError('Project result exceeds its transport bound.', 'too_large', 413) - upserts = captured['records'] - if self.extra_capture is not None: - extra = self.extra_capture(current['records'] if self._lazy else copy.deepcopy(current['records'])) - if type(extra) is not list: - raise ProjectSessionError('Invalid fixed runtime capture.') - upserts = upserts + extra - merged = self._merge(current['records'], upserts, owned=self._lazy) - document = dict(format=OPERATION_FORMAT, project_id=self.project_id, operation=operation, target=target, - request_key=key, input_sha256=digest, result=copy.deepcopy(captured['result'])) - identity = (OPERATION_FAMILY, self.project_id + '.' + hashlib.sha256(key.encode('utf-8')).hexdigest()) - merged[identity] = dict(family=identity[0], id=identity[1], document=document) - records = [merged[identity] for identity in sorted(merged)] - changed = {(item['family'], item['id']) for item in upserts} | {identity} - with self._known_envelopes(records, changed), \ - self._edit_scope(current['checkpoint'], changed, (operation,), - base_records=current['records']): - self._validated(records) - # Unique payloads have already reached artifact custody; - # SQL callbacks can delete only disposable projection files. - attempted_records = records - if self.publication_intent is not None: - self.publication_intent(copy.deepcopy(current), copy.deepcopy(records), key, digest) - if self._lazy: - # Only the captured upserts and this receipt can differ. - changed = {(item['family'], item['id']) for item in upserts} | {identity} - committed = self.store.commit(records, current['checkpoint'], key, digest, changed=changed) - else: - committed = self.store.commit(records, current['checkpoint'], key, digest) - # Outcome hooks see canonical selection before SQL outcome - # and before any deferred dispatch/wake can run. - self._pending_observation = committed - self._bind(committed) - # These exact records were completely validated as the candidate. - self._remember_validated(committed['checkpoint']) - return copy.deepcopy(captured['result']) - except BaseException as error: - if committed is not None and self._atomic_store(): - from metadata import CommitOutcomeUnknown - if isinstance(error, CommitOutcomeUnknown): - # PostgreSQL may or may not have committed both the - # records and the projection; reopening reads the outcome. - self.available = False - raise ProjectSessionError('PostgreSQL did not confirm this edit. Reopen the project to see whether it was saved.', - 'unknown', 503) from error - # Records and projection rolled back together; nothing changed. - if isinstance(error, ProjectSessionError): - raise - raise ProjectSessionError('PostgreSQL rejected this edit; nothing was saved.', - 'rejected', 409) from error - if committed is not None: - self._bind(committed) - self.available = False - failure = ProjectSessionError('Canonical operation committed; reopen to reconstruct the projection.', - 'projection_unavailable', 503) - failure.receipt = dict(committed=True, selected=True, project_id=committed['project_id'], - checkpoint=committed['checkpoint'], request_key=key) - raise failure from error - if getattr(error, 'code', None) in ('unknown', 'outcome_unknown'): - self.available = False - if attempted_records is not None: - self._recovery_records = copy.deepcopy(attempted_records) - self._recovery_request = (key, digest) - raise - finally: - self._foreground_publication = False - self._pending_observation = None - - -# Owners also accept lightweight snapshot views (for example inert candidate or -# retained-material views that expose only snapshot/check_current). These -# helpers use a ProjectSession's copy-avoiding bound reads when available and -# otherwise compute exactly the same values from the view's snapshot. - -def session_records(session, *families): - if hasattr(session, 'records') and callable(session.records): - return session.records(*families) - return [item for item in session.snapshot['records'] if item['family'] in families] - - -def session_record(session, family, record_id): - if hasattr(session, 'record') and callable(session.record): - return session.record(family, record_id) - return next((item for item in session.snapshot['records'] - if item['family'] == family and item['id'] == record_id), None) - - -def session_records_for(session, *families): - if hasattr(session, 'records_for') and callable(session.records_for): - return session.records_for(*families) - return session.snapshot['records'] - - -def session_active(session, *families, project_id=None): - if hasattr(session, 'active') and callable(session.active): - return session.active(*families, project_id=project_id) - from project_fork import active_records - snapshot = session.snapshot - return active_records(snapshot['records'], - project_id=session.project_id if project_id is None else project_id, - families=frozenset(families)) - - -def session_operations(session, *, project_id=None): - if hasattr(session, 'operations') and callable(session.operations): - return session.operations(project_id=project_id) - return operation_records(session.snapshot['records'], project_id=project_id) - - -def session_derived(session, name, compute): - if hasattr(session, 'derived') and callable(session.derived): - return session.derived(name, compute) - return compute() diff --git a/project_sources.py b/project_sources.py deleted file mode 100644 index a17b02a5..00000000 --- a/project_sources.py +++ /dev/null @@ -1,238 +0,0 @@ -"""Explicit current source bindings, separate from portable snapshot facts. - -Opening a project never restores workspace_projects. Only an authenticated owner -registering an anchored current manifest can create that disposable binding. -Canonical receipts describe retained facts; they are not filesystem capabilities. -""" -import copy -from datetime import datetime -from functools import cache, partial -import hashlib -import os - -from project_material import decode_records as material_records -from project_session import ProjectSessionError, REQUEST_KEY -from projects import (DATA_LIMIT, ID, INSPECTION_LIMIT, MANIFEST_LIMIT, NAME, SHA, decode, - decode_retained_snapshot, manifest, relative_path, text) -from workbench import WorkbenchError, encode, timestamp - -RESULT_FIELDS = frozenset(('origin_catalog_id','project_id','manifest_sha256','name', - 'schema_version','actor_id','registered_at')) - - -def _closed(value, fields): - if type(value) is not dict or set(value)!=set(fields): - raise WorkbenchError('Invalid explicit source operation fields.') - - -def _identity(value, pattern, label): - if type(value) is not str or not pattern.fullmatch(value): - raise WorkbenchError('Invalid source '+label+'.') - return value - - -def _summary(saved, origin): - return dict(origin_catalog_id=origin,project_id=saved['id'], - manifest_sha256=saved['manifest_sha256'],name=saved['name'], - schema_version=saved['manifest']['schema_version']) - - -def _validate_result(operation,result,lookup=None): - """Validate the fixed source receipt against its exact retained snapshot.""" - if operation!='source.register':return False - try: - _closed(result,RESULT_FIELDS) - for key in ('origin_catalog_id','project_id','actor_id'):_identity(result[key],ID,key) - _identity(result['manifest_sha256'],SHA,'manifest SHA256') - text(result['name'],'Source project name',120) - if type(result['schema_version']) is not int or result['schema_version'] not in (1,2): - raise WorkbenchError('Unsupported source registration schema.','unsupported',400) - if type(result['registered_at']) is not str or len(result['registered_at'])>80: - raise WorkbenchError('Source registration requires an attributed timestamp.') - if datetime.fromisoformat(result['registered_at']).utcoffset() is None: - raise WorkbenchError('Source registration timestamp requires an offset.') - if lookup is not None: - document=lookup(('project_snapshot',result['origin_catalog_id']+'.'+result['manifest_sha256'])) - expected={key:result[key] for key in ('origin_catalog_id','project_id','manifest_sha256','name','schema_version')} - if document is None or _summary(document['value'],document['origin_catalog_id'])!=expected: - raise WorkbenchError('Source receipt differs from its exact retained snapshot.') - return True - except WorkbenchError:raise - except (ValueError,TypeError,KeyError,AttributeError,OverflowError,RecursionError): - raise WorkbenchError('Malformed retained source operation result.') from None - - -def receipt_validator(records): - """Own one candidate's retained material facts for source receipt checks.""" - owned = material_records(records) - return partial(_validate_result, lookup=owned.get) - - -def validate_operation_result(operation, result, records=None): - @cache - def owned(): - return material_records(records) - lookup = None if records is None else lambda identity: owned().get(identity) - return _validate_result(operation, result, lookup) - - -class SourceAdapter: - def __init__(self,projection): - self.projection=projection - self.session=projection.session - self.db,self.access=self.session.db,self.session.access - self.sources,self.materials,self.data=projection.sources,projection.materials,projection.data - - @staticmethod - def _mutation_identity(expected_checkpoint,key): - _identity(expected_checkpoint,SHA,'expected checkpoint') - _identity(key,REQUEST_KEY,'request key') - - @staticmethod - def _snapshot_reference(snapshot): - _closed(snapshot,('origin_catalog_id','project_id','manifest_sha256')) - for field in ('origin_catalog_id','project_id'):_identity(snapshot[field],ID,field) - _identity(snapshot['manifest_sha256'],SHA,'manifest SHA256') - return snapshot - - def _read_registration(self,body): - _closed(body,('root','manifest_path')) - root=_identity(body['root'],NAME,'root alias');path=relative_path(body['manifest_path']) - entry=self.sources.roots.get(root) - if entry is None:raise WorkbenchError('Choose a currently configured source root.','unavailable',409) - self.access.require('inspect','projects.open') - try: - actual=os.fstat(entry[0]);identity=[actual.st_dev,actual.st_ino] - if identity!=entry[1]:raise WorkbenchError('Configured source root identity changed.','stale',409) - # Reuse Projects' anchored before/after identity and no-follow read. - raw=self.sources._read_snapshot_file(dict(root=root,root_identity=identity),path,MANIFEST_LIMIT) - except OSError: - raise WorkbenchError('Current source manifest is unavailable.','unavailable',409) from None - value=manifest(decode(raw)) - saved=dict(id=value['id'],name=value['name'],root=root,root_identity=identity, - manifest_path=path,manifest_sha256=hashlib.sha256(raw).hexdigest(),manifest=value) - return decode_retained_snapshot(saved),raw - - def _bind(self,saved,raw): - if not self.db.in_transaction:raise RuntimeError('Source binding requires its outer SQL transaction.') - if self.sources._read_snapshot_file(saved,saved['manifest_path'],MANIFEST_LIMIT)!=raw: - raise WorkbenchError('Source manifest changed before current registration.','stale',409) - row=self.db.execute('SELECT document FROM workspace_projects WHERE id=%s',(saved['id'],)).fetchone() - if row is not None: - prior=decode_retained_snapshot(decode(row[0].encode())) - if prior['manifest_sha256']!=saved['manifest_sha256']: - raise WorkbenchError('This source ID already names a different current snapshot.','conflict',409) - if prior==saved:return - # Explicit same-manifest registration can renew a moved root. The - # original canonical registration facts are never rewritten. - self.db.execute('UPDATE workspace_projects SET document=%s WHERE id=%s',(encode(saved),saved['id'])) - else:self.db.execute('INSERT INTO workspace_projects VALUES(%s,%s)',(saved['id'],encode(saved))) - - def register(self,body,expected_checkpoint,key): - self._mutation_identity(expected_checkpoint,key) - with self.access.lock,self.session.lock,self.db.lock: - actor=self.access.require('edit','source.register',owner_only=True) - self.session.check_current() - saved,raw=self._read_registration(body) - origin=self.session.summary['project_id'];invoked=False - def invoke(): - nonlocal invoked - invoked=True;self._bind(saved,raw) - return dict(_summary(saved,origin),actor_id=actor.actor_id,registered_at=timestamp()) - def capture(result,before): - record=self.materials.capture_snapshot(saved,raw,catalog_id=origin) - return dict(records=[*self.materials.declarations(record),record],result=result) - result=self.session.mutate('source.register',saved['id'],copy.deepcopy(body),expected_checkpoint,key,invoke,capture) - if any(result[field]!=value for field,value in _summary(saved,origin).items()): - raise WorkbenchError('Current source manifest differs from the acknowledged registration.','stale',409) - if not invoked: - # Replay itself does not run invoke. This explicit owner action - # may renew a verified current binding after a cold Open; it is - # not a new historical registration event or canonical write. - try: - with self.db.transaction():self._bind(saved,raw) - except WorkbenchError:raise - except BaseException as error: - self.session.available=False - failure=ProjectSessionError('Source registration was acknowledged; reopen before binding its current root.', - 'projection_unavailable',503) - snapshot=self.session.snapshot - failure.receipt=dict(committed=True,selected=True,project_id=snapshot['project_id'], - checkpoint=snapshot['checkpoint'],request_key=key) - raise failure from error - return result - - def references(self,snapshotref,offset=0,limit=40): - snapshot=self._snapshot_reference(snapshotref) - if type(offset) is not int or not 0<=offset<=2**53-1 or type(limit) is not int or not 1<=limit<=40: - raise WorkbenchError('Invalid bounded source reference page.') - with self.access.lock,self.session.lock,self.db.lock: - self.access.require('inspect','source.references',snapshot['project_id']) - self.session.check_current() - historical=self.materials.snapshot_ref(snapshot['project_id'],snapshot['manifest_sha256'], - catalog_id=snapshot['origin_catalog_id']) - try:current=self.sources._saved(snapshot['project_id'],extensions=True) - except WorkbenchError as error: - if error.code=='not_found': - raise WorkbenchError('Explicitly register a current source root before inspecting its references.','unavailable',409) from None - raise - # Check current binding and exact retained selection before reading - # even the live manifest. Historical root/path fields grant nothing. - if not self.sources._bound(current): - raise WorkbenchError('The selected source has no current root binding.','unavailable',409) - if current['manifest_sha256']!=snapshot['manifest_sha256'] or current['manifest']!=historical['manifest']: - raise WorkbenchError('Current source registration differs from the selected snapshot.','stale',409) - self.sources.read_snapshot_manifest(snapshot['project_id'],snapshot['manifest_sha256']) - selected=current['manifest']['data'][offset:offset+limit];budget=[INSPECTION_LIMIT] - items=[self.sources._inspect(current['root'],copy.deepcopy(ref),budget,DATA_LIMIT) for ref in selected] - self.sources.read_snapshot_manifest(snapshot['project_id'],snapshot['manifest_sha256']) - self.session.check_current();self.access.require('inspect','source.references',snapshot['project_id']) - return dict(items=items,total=len(current['manifest']['data']),offset=offset,limit=limit) - - def import_scientific(self,body,expected_checkpoint,key): - self._mutation_identity(expected_checkpoint,key) - _closed(body,('snapshot','reference_id','expected_sha256','document')) - snapshot=self._snapshot_reference(body['snapshot']) - _identity(body['reference_id'],NAME,'data reference') - _identity(body['expected_sha256'],SHA,'data SHA256') - if type(body['document']) is not dict:raise WorkbenchError('Scientific import metadata must be an object.') - with self.access.lock,self.session.lock,self.db.lock: - self.access.require('edit','source.import_scientific',snapshot['project_id']) - self.session.check_current() - raw,source=self._capture_reference(snapshot,body['reference_id'],body['expected_sha256'],DATA_LIMIT) - # ProjectData owns the one canonical mutation and native parser; - # current rooted reads above never become an imported capability. - return self.data.import_scientific(raw,copy.deepcopy(body['document']),source,expected_checkpoint,key) - - def _capture_reference(self,snapshot,reference_id,expected_sha256,maximum_bytes): - """One rooted capture policy shared by the two fixed native consumers. - - Caller holds current access/session/database locks and authorizes the - action before any source read. Returned paths remain historical facts. - """ - historical=self.materials.snapshot_ref(snapshot['project_id'],snapshot['manifest_sha256'], - catalog_id=snapshot['origin_catalog_id']) - current,_raw=self.sources.read_snapshot_manifest(snapshot['project_id'],snapshot['manifest_sha256']) - if current['manifest']!=historical['manifest']: - raise WorkbenchError('Current source differs from the selected retained snapshot.','stale',409) - raw,source=self.sources.read_snapshot_data_reference(snapshot['project_id'],reference_id, - expected_sha256,maximum_bytes) - if source['manifest_sha256']!=snapshot['manifest_sha256']: - raise WorkbenchError('Current source snapshot changed during capture.','stale',409) - self.session.check_current() - return raw,source - - def import_measurements(self,body,expected_checkpoint,key): - self._mutation_identity(expected_checkpoint,key) - _closed(body,('snapshot','reference_id','expected_sha256')) - snapshot=self._snapshot_reference(body['snapshot']) - _identity(body['reference_id'],NAME,'data reference') - _identity(body['expected_sha256'],SHA,'data SHA256') - from retained_measurements import MAX_BYTES - with self.access.lock,self.session.lock,self.db.lock: - self.access.require('edit','source.import_measurements',snapshot['project_id']) - self.session.check_current() - raw,source=self._capture_reference(snapshot,body['reference_id'],body['expected_sha256'],MAX_BYTES) - source=dict(source,origin_catalog_id=snapshot['origin_catalog_id']) - self.access.require('edit','source.import_measurements',snapshot['project_id']) - return self.projection.measurements.import_packet(raw,source,expected_checkpoint,key) diff --git a/project_store.py b/project_store.py deleted file mode 100644 index 826a5ab7..00000000 --- a/project_store.py +++ /dev/null @@ -1,1286 +0,0 @@ -"""Canonical POSIX-local project checkpoints; domain codecs own document meaning. - -Only the inventory in .tuldok/project.json confers authority. Immutable revisions -are durable before its atomic replacement. The directory flock excludes cooperating -writers by physical root identity, including alternate spellings of the same root. -Uncooperative checkout/edit operations are forbidden while open and detected before -publication. An uncertain publication is reconciled by reopening and its receipt. -""" -import copy -import ctypes -from contextlib import contextmanager -import errno -import fcntl -import hashlib -import json -import math -import os -from pathlib import Path -import re -import stat -import threading -import uuid - -FORMAT = 'tuldok_project_v1' -GITIGNORE = b'/artifacts/\n/.tuldok-local/\n/.venv/\n/__pycache__/\n/PGDATA/\n/output/\n' -MAX_RECORD_BYTES = 40 * 1024 * 1024 -# A retained scientific runtime can declare tens of thousands of small files. -# Their index is bounded separately from the actual record/payload byte budgets. -MAX_MANIFEST_BYTES = 64 * 1024 * 1024 -# Coordinated internal codecs; adding a family requires its owning decoder. -SUPPORTED_FORMATS = { - 'workbench_text': 'workbench_text_v1', - 'workbench_record': 'workbench_record_v1', - 'workbench_response': 'workbench_response_v1', - 'workbench_preference': 'workbench_preference_v1', - 'saved_selection': 'saved_selection_v1', - 'saved_search': 'saved_search_v1', - 'dataset_release': 'dataset_release_v1', - 'dataset_exposure': 'dataset_exposure_v1', - 'model_definition': 'model_definition_history_v1', - 'pipeline_graph': 'pipeline_graph_history_v1', - 'recipe_definition': 'recipe_definition_history_v1', - 'model_material': 'retained_model_material_v1', - 'recipe_material': 'retained_recipe_material_v1', - 'project_snapshot': 'retained_project_snapshot_v1', - 'measurement_source': 'project_measurement_source_v1', - 'runtime_material': 'retained_runtime_material_v1', - 'study_history': 'project_study_history_v1', - 'trial_history': 'project_trial_history_v1', - 'run_history': 'project_run_history_v1', - 'run_observation': 'project_run_observation_v1', - 'native_execution_history': 'native_execution_history_v1', - 'candidate_history': 'project_candidate_history_v1', - 'project_artifact': 'project_artifact_v1', - 'project_operation': 'project_operation_v1', - 'project_fork': 'project_fork_v1', - 'project_composition': 'project_composition_v1', - 'project_file': 'project_file_v1', - 'project_extraction': 'project_extraction_v1', - 'generation_history': 'project_generation_history_v1', - 'grounded_history': 'project_grounded_history_v1', - 'caption_proposal_history': 'project_caption_proposal_history_v1', - 'text_proposal_history': 'project_text_proposal_history_v1', - # Store-only: one shared retained runtime closure for compact Runs - # (project_record_dedupe); never visible to domain owners. - 'run_runtime_closure': 'project_run_runtime_closure_v1', -} -MAX_RECORDS = 100_000 -# Scientific history can retain original runtime/file observations in hundreds -# of Runs. Bound the whole local checkpoint separately from each document. -MAX_TOTAL_BYTES = 2 * 1024 * 1024 * 1024 -IDENTIFIER = re.compile(r'^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$') -REQUEST_KEY = re.compile(r'^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$') -DOMAIN_FORMAT = re.compile(r'^[a-z][a-z0-9_]{0,95}_v([1-9][0-9]*)$') -SHA256 = re.compile(r'^[a-f0-9]{64}$') -DIR_FLAGS = os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW | os.O_CLOEXEC -FILE_FLAGS = os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK | os.O_CLOEXEC - - -class ProjectStoreError(ValueError): - def __init__(self, message, code='invalid', status=400): - super().__init__(message) - self.code, self.status = code, status - - -def _fail(message, code='invalid', status=400): - raise ProjectStoreError(message, code, status) - - -def _sha(raw): - return hashlib.sha256(raw).hexdigest() - - -def _json_value(value, depth=0): - if depth > 64: - _fail('Project JSON exceeds its nesting limit.') - if value is None or type(value) is bool: - return - if type(value) is int: - if not -(2 ** 63) <= value < 2 ** 63: - _fail('Project JSON integer exceeds signed 64-bit range.') - return - if type(value) is float and math.isfinite(value): - return - if type(value) is str: - if not value.isascii(): - try: - value.encode('utf-8') - except UnicodeEncodeError: - _fail('Project JSON contains an invalid Unicode surrogate.') - return - if type(value) is list: - for item in value: - _json_value(item, depth + 1) - return - if type(value) is dict and all(type(key) is str for key in value): - for key, item in value.items(): - _json_value(key, depth + 1) - _json_value(item, depth + 1) - return - _fail('Project value must contain finite JSON values.') - - -def _encode(value): - _json_value(value) - return (json.dumps(value, ensure_ascii=False, sort_keys=True, indent=2, - allow_nan=False) + '\n').encode('utf-8') - - -def copy_validated_json(value): - """Own another tree of already validated JSON without Python graph copying. - - Canonical Store/Session values contain only JSON scalars, lists and string - keyed dictionaries. This is a copy operation inside that proof boundary, - never an input decoder or a substitute for freshness/codec validation. - """ - return json.loads(json.dumps(value, ensure_ascii=True, allow_nan=False, - separators=(',', ':'))) - - -def _manifest_raw(manifest): - raw = _encode(manifest) - if len(raw) > MAX_MANIFEST_BYTES: - _fail('Project checkpoint exceeds its byte limit.') - return raw - - -def _pairs(pairs): - result = {} - for key, value in pairs: - if key in result: - _fail('Project JSON contains duplicate object keys.') - result[key] = value - return result - - -def _decode(raw): - try: - value = json.loads(raw.decode('utf-8'), object_pairs_hook=_pairs, - parse_constant=lambda _: _fail('Project JSON contains a nonfinite number.')) - if _encode(value) != raw: - _fail('Project JSON must use canonical UTF-8, sorted keys, two-space indentation and LF.') - return value - except ProjectStoreError: - raise - except (ValueError, RecursionError, OverflowError) as exc: - raise ProjectStoreError('Malformed project JSON.') from exc - - -def _keys(value, keys, label): - if type(value) is not dict or set(value) != set(keys): - _fail(f'{label} has invalid or unknown fields.') - - -def _identifier(value, label): - if type(value) is not str or not IDENTIFIER.fullmatch(value) or value in ('.', '..'): - _fail(f'{label} must be a bounded path-free identifier.') - - -def _digest(value, label): - if type(value) is not str or not SHA256.fullmatch(value): - _fail(f'{label} must be a SHA256 digest.') - - -def _domain_format(value, family): - match = DOMAIN_FORMAT.fullmatch(value) if type(value) is str else None - if not match: - _fail('Domain document requires a versioned format.') - if value != SUPPORTED_FORMATS[family] and not ( - family == 'project_operation' and value == 'project_operation_v2' - or family == 'project_file' and value == 'project_file_v2' - or family == 'run_history' and value == 'project_run_history_v2'): - _fail('Unsupported domain document format.', 'unsupported', 422) - - -def _compact(value): - # CPython's C encoder is used only without indent; it distinguishes 1, 1.0, - # True and 0.0/-0.0, which Python == equality does not. - return json.dumps(value, ensure_ascii=False, sort_keys=True, allow_nan=False, - separators=(',', ':')) - - -def _same_json(candidate, verified): - """Exact JSON value equality: same types, float bits and key sets.""" - if candidate is verified: - return True - if candidate != verified: - return False - try: - return _compact(candidate) == _compact(verified) - except (TypeError, ValueError, RecursionError): - return False - - -def _prepared_records(records, unchanged=None): - """Validate and canonically encode a complete candidate record set. - - unchanged maps (family, id) -> (verified current document, inventory entry). - A candidate document equal to its verified current revision reuses that - revision's known canonical byte count and digest instead of re-encoding it; - its raw slot is None and the caller must not rewrite it. - """ - if type(records) is not list or len(records) > MAX_RECORDS: - _fail('Project records must be a bounded list.') - unchanged = unchanged or {} - result, seen, total = [], set(), 0 - for record in records: - _keys(record, ('family', 'id', 'document'), 'Project record') - family, identity, document = (record[k] for k in ('family', 'id', 'document')) - _identifier(family, 'Record family') - if family not in SUPPORTED_FORMATS: - _fail('Unsupported project record family.', 'unsupported', 422) - _identifier(identity, 'Record ID') - if (family, identity) in seen: - _fail('Duplicate project record identity.') - seen.add((family, identity)) - if type(document) is not dict: - _fail('Domain document must be an object.') - _domain_format(document.get('format'), family) - current = unchanged.get((family, identity)) - if current is not None and _same_json(document, current[0]) \ - and current[1]['format'] == document['format']: - # Exactly equal JSON values have identical canonical bytes; share the - # already verified current document (never handed out by alias). - total += current[1]['bytes'] - if total > MAX_TOTAL_BYTES: - _fail('Project records exceed the synchronous byte limit.') - result.append((family, identity, current[0], None, current[1])) - continue - document = copy.deepcopy(document) - raw = _encode(document) - total += len(raw) - if len(raw) > MAX_RECORD_BYTES or total > MAX_TOTAL_BYTES: - _fail('Project records exceed the synchronous byte limit.') - result.append((family, identity, document, raw, None)) - return sorted(result, key=lambda item: (item[0], item[1])) - - -_NESTED_DOCUMENT = b'\n' + b' ' * 4 - - -class _RecordsDigest: - """Incremental SHA256 of _encode([dict(family, id, document), ...]). - - add() takes each record's own canonical _encode(document) bytes, in record - order. Canonical JSON never contains a literal newline inside a string, so - a document nested two levels deep differs from its standalone encoding only - by four extra spaces after each newline. The result is byte-identical to - hashing the complete re-encoded list, without re-encoding any document. - """ - def __init__(self): - self._digest = hashlib.sha256() - self._first = True - - def add(self, family, identity, raw): - if not raw.endswith(b'\n'): - _fail('Canonical record bytes must end with LF.') - self._digest.update(b'[\n {\n "document": ' if self._first else b',\n {\n "document": ') - self._first = False - self._digest.update(raw[:-1].replace(b'\n', _NESTED_DOCUMENT)) - self._digest.update(b',\n "family": ') - self._digest.update(json.dumps(family, ensure_ascii=False).encode('utf-8')) - self._digest.update(b',\n "id": ') - self._digest.update(json.dumps(identity, ensure_ascii=False).encode('utf-8')) - self._digest.update(b'\n }') - - def hexdigest(self): - final = self._digest.copy() - final.update(b'[]\n' if self._first else b'\n]\n') - return final.hexdigest() - - -def envelope_digest(family, identity, raw): - """SHA256 of _encode(dict(family, id, document)) from the document's canonical bytes. - - Canonical JSON has no literal newline inside strings, so the document nested - one level deep differs from its standalone encoding only by two spaces after - each newline. - """ - if not raw.endswith(b'\n'): - _fail('Canonical record bytes must end with LF.') - digest = hashlib.sha256(b'{\n "document": ') - digest.update(raw[:-1].replace(b'\n', b'\n ')) - digest.update(b',\n "family": ' + json.dumps(family, ensure_ascii=False).encode('utf-8')) - digest.update(b',\n "id": ' + json.dumps(identity, ensure_ascii=False).encode('utf-8') + b'\n}\n') - return digest.hexdigest() - - -def _records_digest(rows): - """Digest of (family, id, canonical raw) rows; see _RecordsDigest.""" - digest = _RecordsDigest() - for family, identity, raw in rows: - digest.add(family, identity, raw) - return digest.hexdigest() - - -def _records(records): - """Complete canonical encoding as (family, id, document, raw) tuples.""" - return [(family, identity, document, raw) - for family, identity, document, raw, _entry in _prepared_records(records)] - - -def _physical_candidates(records, logical, physical): - """Physical envelopes for a logical candidate record set. - - A candidate equal to its current logical document reuses the current - physical document (so its verified revision is kept). Changed Runs are - compacted to a shared runtime closure when exactly reversible; every - referenced closure is included once. Returns (physical candidates, logical - result in record order) or (records, None) for malformed input, which - _prepared_records then rejects with its usual errors. - """ - from project_record_dedupe import CLOSURE_FAMILY, RUN_FAMILY, compact, is_compact - if type(records) is not list or any(type(item) is not dict or set(item) != {'family', 'id', 'document'} - or type(item['family']) is not str or type(item['id']) is not str - for item in records): - return records, None - if any(item['family'] == CLOSURE_FAMILY for item in records): - _fail('Runtime closures are store-owned records.', 'unsupported', 422) - current_logical = {(item['family'], item['id']): item['document'] for item in logical} - current_physical = {(item['family'], item['id']): item['document'] for item in physical} - closures = {item['id']: item['document'] for item in physical if item['family'] == CLOSURE_FAMILY} - candidates, logical_out, referenced = [], [], set() - for item in records: - key = (item['family'], item['id']) - document = item['document'] - if key in current_logical and _same_json(document, current_logical[key]): - stored = current_physical[key] - candidates.append(dict(family=key[0], id=key[1], document=stored)) - logical_out.append(dict(family=key[0], id=key[1], document=current_logical[key])) - if is_compact(key[0], stored): - referenced.add(stored['runtime_closure']['id']) - continue - owned = copy.deepcopy(document) - logical_out.append(dict(family=key[0], id=key[1], document=owned)) - compacted = compact(owned) if key[0] == RUN_FAMILY else None - if compacted is not None: - reduced, closure = compacted - identity = reduced['runtime_closure']['id'] - closures.setdefault(identity, closure) - referenced.add(identity) - candidates.append(dict(family=key[0], id=key[1], document=reduced)) - else: - candidates.append(dict(family=key[0], id=key[1], document=owned)) - candidates.extend(dict(family=CLOSURE_FAMILY, id=identity, document=closures[identity]) for identity in sorted(referenced)) - logical_out.sort(key=lambda item: (item['family'], item['id'])) - return candidates, logical_out - - -def _request(key, digest): - if type(key) is not str or not REQUEST_KEY.fullmatch(key): - _fail('Request key must contain 1–128 supported characters.') - _digest(digest, 'Request body digest') - - -def checked_manifest(raw): - """Decode and check a project checkpoint without reading any record file. - - Verifies format, identity, the checkpoint digest, every inventory entry's - shape, ordering, rooted path and byte bounds, membership roots and receipt - structure. Record bytes and the latest receipt's records digest are checked - by whoever reads the records. - """ - manifest = _decode(raw) - if type(manifest) is not dict: - _fail('Project checkpoint must be an object.') - if manifest.get('format') != FORMAT: - if type(manifest.get('format')) is str and re.fullmatch(r'tuldok_project_v[1-9][0-9]*', manifest['format']): - _fail('Unsupported project format.', 'unsupported', 422) - _fail('Invalid project format.') - _keys(manifest, ('format', 'project_id', 'name', 'checkpoint', 'roots', 'inventory', 'receipts'), 'Project checkpoint') - identity = manifest['project_id'] - if type(identity) is not str or not re.fullmatch('[a-f0-9]{32}', identity): - _fail('Invalid project UUID.') - if type(manifest['name']) is not str or not manifest['name'].strip() or len(manifest['name']) > 200: - _fail('Invalid project display name.') - _digest(manifest['checkpoint'], 'Checkpoint') - core = {k: v for k, v in manifest.items() if k != 'checkpoint'} - if _sha(_encode(core)) != manifest['checkpoint']: - _fail('Project checkpoint digest does not match its contents.') - inventory = manifest['inventory'] - if type(inventory) is not list or len(inventory) > MAX_RECORDS: - _fail('Invalid project inventory.') - roots, total, previous = [], 0, None - for entry in inventory: - _keys(entry, ('family', 'id', 'format', 'namespace', 'path', 'bytes', 'sha256'), 'Inventory entry') - family, record_id, digest = entry['family'], entry['id'], entry['sha256'] - _identifier(family, 'Record family') - if family not in SUPPORTED_FORMATS: - _fail('Unsupported project record family.', 'unsupported', 422) - _identifier(record_id, 'Record ID') - _digest(digest, 'Record digest') - _domain_format(entry['format'], family) - key = (family, record_id) - if previous is not None and key <= previous: - _fail('Inventory must have unique sorted record identities.') - previous = key - if entry['namespace'] != identity or entry['path'] != f'records/{family}/{record_id}/{digest}.json': - _fail('Invalid inventory namespace or rooted record path.') - if type(entry['bytes']) is not int or not 0 < entry['bytes'] <= MAX_RECORD_BYTES: - _fail('Invalid inventory record byte count.') - total += entry['bytes'] - if total > MAX_TOTAL_BYTES: - _fail('Project records exceed their total byte limit.') - roots.append(dict(family=family, id=record_id)) - if manifest['roots'] != roots: - _fail('Project membership roots disagree with the inventory.') - if type(manifest['receipts']) is not list or not manifest['receipts']: - _fail('Project requires operation receipts.') - seen = set() - for receipt in manifest['receipts']: - _keys(receipt, ('request_key', 'request_sha256', 'records_sha256'), 'Operation receipt') - _request(receipt['request_key'], receipt['request_sha256']) - _digest(receipt['records_sha256'], 'Receipt records digest') - if receipt['request_key'] in seen: - _fail('Duplicate operation receipt key.') - seen.add(receipt['request_key']) - return manifest - - -def _path_string(path): - try: - value = os.fspath(path) - except TypeError as exc: - raise ProjectStoreError('Project path must be text.') from exc - if type(value) is not str: - _fail('Project path must be text.') - return value - - -def _open_directory_path(path): - """Walk every component without following symlinks, retaining the final fd.""" - try: - raw = _path_string(path) - if type(raw) is not str or '\x00' in raw or '..' in raw.split('/'): - _fail('Unsafe project root path.') - absolute = os.path.abspath(raw) - fd = os.open('/', DIR_FLAGS) - try: - for component in absolute.split('/'): - if not component: - continue - next_fd = os.open(component, DIR_FLAGS, dir_fd=fd) - os.close(fd) - fd = next_fd - return absolute, fd - except BaseException: - os.close(fd) - raise - except OSError as exc: - _io_error(exc, 'resolve project root') - - -def _relative_parts(relative): - if type(relative) is not str or not relative or len(relative) > 4096 or '\x00' in relative: - _fail('Invalid relative project directory.') - parts = relative.split('/') - if any(part in ('', '.', '..') for part in parts): - _fail('Project directory must remain beneath its configured root.') - return parts - - -def _walk(root_fd, parts): - fd = os.dup(root_fd) - try: - for component in parts: - next_fd = _directory(fd, component) - os.close(fd) - fd = next_fd - return fd - except BaseException: - os.close(fd) - raise - - -def _verify_origin(root_fd, root_path): - absolute, check = _open_directory_path(root_path) - try: - if _physical(check) != _physical(root_fd): - _fail('Configured project root changed.', 'stale', 409) - finally: - os.close(check) - return absolute - - -@contextmanager -def anchored_directory(trusted_root_fd, relative='', *, root_path): - """Borrow a rooted no-follow directory capability; caller retains root fd.""" - parts = _relative_parts(relative) if relative else [] - descriptor = None - try: - _verify_origin(trusted_root_fd, root_path) - descriptor = _walk(trusted_root_fd, parts) - yield descriptor - _verify_origin(trusted_root_fd, root_path) - current = _walk(trusted_root_fd, parts) - try: - if _physical(current) != _physical(descriptor): - _fail('Anchored directory changed during use.', 'stale', 409) - finally: - os.close(current) - except OSError as exc: - _io_error(exc, 'access anchored directory') - finally: - if descriptor is not None: - os.close(descriptor) - - -def _directory_inside(candidate_fd, ancestor_fd): - """Compare physical directory ancestry without following path aliases.""" - current = os.dup(candidate_fd) - try: - ancestor = _physical(ancestor_fd) - while True: - if _physical(current) == ancestor: - return True - parent = os.open('..', DIR_FLAGS, dir_fd=current) - if _physical(parent) == _physical(current): - os.close(parent) - return False - os.close(current) - current = parent - finally: - os.close(current) - - -def assert_separate_project_control(trusted_root_fd, relative, *, root_path, control_path): - """Reject portable project/control overlap before creating any destination. - - The caller retains its configured root handle. Existing targets must be - physically disjoint from control in both directions; for an absent leaf, - its existing anchored parent must be outside control. A broad root may - still contain disjoint project and control siblings. - """ - parts = _relative_parts(relative) - control_fd = target_fd = None - try: - _, control_fd = _open_directory_path(control_path) - with anchored_directory(trusted_root_fd, '/'.join(parts[:-1]), root_path=root_path) as parent_fd: - try: - target_fd = _directory(parent_fd, parts[-1]) - except FileNotFoundError: - overlap = _directory_inside(parent_fd, control_fd) - else: - overlap = (_directory_inside(target_fd, control_fd) or - _directory_inside(control_fd, target_fd)) - if overlap: - _fail('Keep the private workspace control directory separate from portable project directories.', 'conflict', 409) - if target_fd is not None: - current = _directory(parent_fd, parts[-1]) - try: - if _physical(current) != _physical(target_fd): - _fail('Project directory changed during control separation check.', 'stale', 409) - finally: - os.close(current) - _verify_origin(control_fd, control_path) - except OSError as error: - _io_error(error, 'verify project/control separation') - finally: - if target_fd is not None: - os.close(target_fd) - if control_fd is not None: - os.close(control_fd) - - -def _rename_noreplace(parent_fd, staging, destination): - # Linux's RENAME_NOREPLACE provides the required atomic no-overwrite promise. - libc = ctypes.CDLL(None, use_errno=True) - rename = getattr(libc, 'renameat2', None) - if rename is None: - _fail('Atomic no-replace publication is unsupported.', 'unsupported', 422) - rename.argtypes = (ctypes.c_int, ctypes.c_char_p, ctypes.c_int, ctypes.c_char_p, ctypes.c_uint) - rename.restype = ctypes.c_int - if rename(parent_fd, os.fsencode(staging), parent_fd, os.fsencode(destination), 1): - number = ctypes.get_errno() - if number in (errno.ENOSYS, errno.EINVAL, errno.EOPNOTSUPP): - _fail('Filesystem lacks atomic no-replace publication.', 'unsupported', 422) - raise OSError(number, os.strerror(number)) - - -def _publish_directory(parent_fd, staging, destination): - _rename_noreplace(parent_fd, staging, destination) - - -def _io_error(exc, operation, unknown=False): - if unknown: - raise ProjectStoreError(f'Project publication outcome is unknown ({operation}); reopen and reconcile the request.', - 'unknown', 503) from exc - if exc.errno in (errno.ELOOP, errno.ENOTDIR, errno.ENXIO): - raise ProjectStoreError(f'Unsafe filesystem object during {operation}.') from exc - raise ProjectStoreError(f'Cannot {operation}.', 'unavailable', 503) from exc - - -def _physical(fd): - info = os.fstat(fd) - return info.st_dev, info.st_ino - - -def _regular(fd): - info = os.fstat(fd) - if not stat.S_ISREG(info.st_mode) or info.st_nlink != 1: - _fail('Project files must be ordinary files with no hard-link aliases.') - return info - - -def _read(directory, name, maximum): - fd = os.open(name, FILE_FLAGS, dir_fd=directory) - try: - info = _regular(fd) - if info.st_size > maximum: - _fail('Project file exceeds its byte limit.') - chunks, size = [], 0 - while True: - chunk = os.read(fd, min(1024 * 1024, maximum + 1 - size)) - if not chunk: - break - chunks.append(chunk) - size += len(chunk) - if size > maximum: - _fail('Project file exceeds its byte limit.') - after = _regular(fd) - if (info.st_size, info.st_mtime_ns, info.st_ctime_ns) != (after.st_size, after.st_mtime_ns, after.st_ctime_ns): - _fail('Project file changed while reading.', 'stale', 409) - return b''.join(chunks) - finally: - os.close(fd) - - -def _sync_file(directory, name): - fd = os.open(name, FILE_FLAGS, dir_fd=directory) - try: - _regular(fd) - os.fsync(fd) - finally: - os.close(fd) - - -def _directory(parent, name, create=False): - if create: - try: - os.mkdir(name, 0o700, dir_fd=parent) - os.fsync(parent) - except FileExistsError: - pass - return os.open(name, DIR_FLAGS, dir_fd=parent) - - -def _write_file(directory, name, raw): - fd = os.open(name, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW | os.O_CLOEXEC, - 0o600, dir_fd=directory) - try: - _regular(fd) - remaining = memoryview(raw) - while remaining: - written = os.write(fd, remaining) - if not written: - raise OSError(errno.EIO, 'short project write') - remaining = remaining[written:] - os.fsync(fd) - finally: - os.close(fd) - - -class ProjectStore: - """Own one writable physical project root until close(). - - commit replaces the complete current record set. Retained unreferenced - revisions are never pruned. Callers validate domain semantics before commit - and after Open; this owner validates only the generic JSON/inventory contract. - """ - def __init__(self, path, root_fd, origin_fd, relative_parts, origin_path, canonical_digests=None): - self.path = Path(path) - # Optional private set of digests already proven canonical; see _load. - self._canonical_digests = canonical_digests - self._root_fd = root_fd - self._origin_fd = origin_fd - self._relative_parts = relative_parts - self._origin_path = Path(origin_path) - self._meta_fd = None - self._manifest = None - self._read_cache = None - self._mutex = threading.RLock() - self._unknown = False - self._folder_mode = False - try: - fcntl.flock(root_fd, fcntl.LOCK_EX | fcntl.LOCK_NB) - except OSError as exc: - os.close(root_fd) - os.close(origin_fd) - self._origin_fd = None - self._root_fd = None - if exc.errno in (errno.EACCES, errno.EAGAIN): - raise ProjectStoreError('Project already has a writer.', 'busy', 409) from exc - _io_error(exc, 'lock project root') - - @classmethod - def create(cls, path, name, request_key, request_sha256): - raw = _path_string(path) - if type(raw) is not str or '\x00' in raw or '..' in raw.split('/'): - _fail('Unsafe project destination.') - absolute = os.path.abspath(raw) - parent, leaf = os.path.split(absolute) - _, parent_fd = _open_directory_path(parent) - try: - return cls.create_at(parent_fd, leaf, name, request_key, request_sha256, root_path=parent) - finally: - os.close(parent_fd) - - @classmethod - def create_at(cls, trusted_root_fd, relative, name, request_key, request_sha256, *, root_path): - """Create under a configured root capability; duplicate its fd for store lifetime.""" - _request(request_key, request_sha256) - if type(name) is not str or not name.strip() or len(name) > 200: - _fail('Project name must contain 1–200 characters.') - _json_value(name) - parts = _relative_parts(relative) - absolute = _verify_origin(trusted_root_fd, root_path) - origin_fd = os.dup(trusted_root_fd) - parent_fd = None - store = None - published = False - try: - parent_fd = _walk(origin_fd, parts[:-1]) - # Existing destinations, including symlinks, are never merged or replaced. - try: - os.stat(parts[-1], dir_fd=parent_fd, follow_symlinks=False) - except FileNotFoundError: - pass - else: - _fail('Project destination already exists.', 'conflict', 409) - staging = '.tuldok-new-' + uuid.uuid4().hex - os.mkdir(staging, 0o700, dir_fd=parent_fd) - root_fd = _directory(parent_fd, staging) - owned_origin, origin_fd = origin_fd, None - store = cls(Path(absolute).joinpath(*parts), root_fd, owned_origin, - parts[:-1] + [staging], absolute) - store._meta_fd = _directory(root_fd, '.tuldok', create=True) - records_fd = _directory(store._meta_fd, 'records', create=True) - os.close(records_fd) - _write_file(root_fd, '.gitignore', GITIGNORE) - os.fsync(root_fd) - manifest = dict(format=FORMAT, project_id=uuid.uuid4().hex, name=name, - roots=[], inventory=[], receipts=[dict(request_key=request_key, - request_sha256=request_sha256, records_sha256=_sha(_encode([])))]) - manifest['checkpoint'] = _sha(_encode(manifest)) - store._publish(manifest, creating=True) - store._manifest = manifest - store._binding() - _publish_directory(parent_fd, staging, parts[-1]) - published = True - store._relative_parts = parts - os.fsync(parent_fd) - store._binding() - return store - except FileExistsError as exc: - if store is not None: - store.close() - raise ProjectStoreError('Project destination already exists.', 'conflict', 409) from exc - except ProjectStoreError as exc: - if store is not None: - store.close() - if published: - raise ProjectStoreError('Project destination was published but its binding changed; reopen and reconcile the request.', - 'unknown', 503) from exc - raise - except OSError as exc: - if store is not None: - store.close() - _io_error(exc, 'create project', unknown=published) - except BaseException: - if store is not None: - store.close() - raise - finally: - if parent_fd is not None: - os.close(parent_fd) - if origin_fd is not None: - os.close(origin_fd) - - @classmethod - def open(cls, path, *, canonical_digests=None): - raw = _path_string(path) - if type(raw) is not str or '\x00' in raw or '..' in raw.split('/'): - _fail('Unsafe project root path.') - absolute = os.path.abspath(raw) - parent, leaf = os.path.split(absolute) - _, parent_fd = _open_directory_path(parent) - try: - return cls.open_at(parent_fd, leaf, root_path=parent, canonical_digests=canonical_digests) - finally: - os.close(parent_fd) - - @classmethod - def open_at(cls, trusted_root_fd, relative, *, root_path, canonical_digests=None): - """Open a descendant without following any configured-root or child alias.""" - parts = _relative_parts(relative) - absolute = _verify_origin(trusted_root_fd, root_path) - origin_fd = os.dup(trusted_root_fd) - store = None - try: - fd = _walk(origin_fd, parts) - owned_origin, origin_fd = origin_fd, None - store = cls(Path(absolute).joinpath(*parts), fd, owned_origin, parts, absolute, - canonical_digests=canonical_digests) - store._meta_fd = _directory(fd, '.tuldok') - store._manifest, _ = store._load() - return store - except OSError as exc: - if store is not None: - store.close() - _io_error(exc, 'open project') - except BaseException: - if store is not None: - store.close() - raise - finally: - if origin_fd is not None: - os.close(origin_fd) - - # ---- Folder mode: the external project as an import source/export target. - # A folder-mode Store holds the writer lock and root binding but never - # loads the record set; the database working copy owns current records. - - @classmethod - def open_folder_at(cls, trusted_root_fd, relative, *, root_path): - """Bind an existing external project folder without reading its records.""" - parts = _relative_parts(relative) - absolute = _verify_origin(trusted_root_fd, root_path) - origin_fd = os.dup(trusted_root_fd) - store = None - try: - fd = _walk(origin_fd, parts) - owned_origin, origin_fd = origin_fd, None - store = cls(Path(absolute).joinpath(*parts), fd, owned_origin, parts, absolute) - store._meta_fd = _directory(fd, '.tuldok') - store._folder_mode = True - return store - except OSError as exc: - if store is not None: - store.close() - _io_error(exc, 'open project folder') - except BaseException: - if store is not None: - store.close() - raise - finally: - if origin_fd is not None: - os.close(origin_fd) - - def folder_checkpoint(self): - """(raw bytes, checked manifest) of the folder's current project.json.""" - with self._mutex: - self._binding() - try: - raw = _read(self._meta_fd, 'project.json', MAX_MANIFEST_BYTES) - except OSError as exc: - _io_error(exc, 'read project checkpoint') - return raw, checked_manifest(raw) - - def folder_record(self, entry): - """One inventory entry's exact bytes after length/SHA256 verification.""" - with self._mutex: - try: - raw = self._record_file(entry['family'], entry['id'], entry['sha256']) - except OSError as exc: - _io_error(exc, 'read project record') - if len(raw) != entry['bytes'] or _sha(raw) != entry['sha256']: - _fail('Canonical record bytes changed or are corrupt.') - return raw - - def folder_has_record(self, entry): - """Whether the content-addressed revision file exists with its byte length.""" - with self._mutex: - fds = [] - try: - parent = self._meta_fd - for part in ('records', entry['family'], entry['id']): - parent = _directory(parent, part) - fds.append(parent) - info = os.stat(entry['sha256'] + '.json', dir_fd=parent, follow_symlinks=False) - return stat.S_ISREG(info.st_mode) and info.st_size == entry['bytes'] - except FileNotFoundError: - return False - except OSError as exc: - _io_error(exc, 'inspect project record') - finally: - for fd in reversed(fds): - os.close(fd) - - def folder_write_record(self, family, record_id, digest, raw): - """Durably publish one immutable revision; existing bytes must be identical.""" - with self._mutex: - try: - written = self._record_file(family, record_id, digest, raw) - except OSError as exc: - _io_error(exc, 'write project record') - if written != raw: - _fail('Immutable project revision already has different bytes.') - - def folder_publish(self, raw, expected_raw): - """Atomically replace project.json only if it still has expected_raw. - - expected_raw None means the folder has no checkpoint yet. Refuses to - overwrite a checkpoint someone else published since import/export. - """ - if len(raw) > MAX_MANIFEST_BYTES: - _fail('Project checkpoint exceeds its byte limit.') - with self._mutex: - temporary = '.checkpoint-' + uuid.uuid4().hex + '.tmp' - replaced = False - try: - _write_file(self._meta_fd, temporary, raw) - self._binding() - try: - current = _read(self._meta_fd, 'project.json', MAX_MANIFEST_BYTES) - except FileNotFoundError: - current = None - if current != expected_raw: - os.unlink(temporary, dir_fd=self._meta_fd) - _fail('The external project changed since Tuldok last imported or saved it.', 'conflict', 409) - os.replace(temporary, 'project.json', src_dir_fd=self._meta_fd, dst_dir_fd=self._meta_fd) - replaced = True - os.fsync(self._meta_fd) - os.fsync(self._root_fd) - except OSError as exc: - self._unknown = replaced - _io_error(exc, 'publish checkpoint', unknown=replaced) - - def _binding(self): - if self._root_fd is None: - _fail('Project store is closed.', 'unavailable', 409) - if self._unknown: - _fail('Reopen project to reconcile an unknown publication.', 'unknown', 503) - _verify_origin(self._origin_fd, self._origin_path) - check = _walk(self._origin_fd, self._relative_parts) - try: - if _physical(check) != _physical(self._root_fd): - _fail('Project root changed; close and reopen.', 'stale', 409) - meta = _directory(check, '.tuldok') - try: - if _physical(meta) != _physical(self._meta_fd): - _fail('Project metadata directory changed.', 'stale', 409) - finally: - os.close(meta) - finally: - os.close(check) - - @contextmanager - def root_directory(self, *, verify_after=False): - """Borrow this project's physical root while its writer binding is pinned.""" - if type(verify_after) is not bool: - _fail('Root read verification must be an explicit boolean.') - with self._mutex: - before = self._current()[0]['checkpoint'] - descriptor = os.dup(self._root_fd) - try: - yield descriptor - self._binding() - if verify_after and self._current()[0]['checkpoint'] != before: - _fail('Project checkpoint changed during the bounded root read.', 'stale', 409) - finally: - os.close(descriptor) - - def _load(self): - self._binding() - raw = _read(self._meta_fd, 'project.json', MAX_MANIFEST_BYTES) - cached = self._read_cache - if cached is not None and raw == cached[0]: - # Record files are content-addressed by their inventory digest and - # are never rewritten, and every one was length/SHA256 verified when - # this Store decoded it. Byte-identical checkpoint bytes therefore - # name the same verified record set; re-hashing every record on each - # freshness check is redundant. On-disk corruption after that point - # is still refused by Save (verify_records) and by every reopen. - self._binding() - return cached[1], cached[2] - manifest = checked_manifest(raw) - loaded = [] - records_digest = _RecordsDigest() - known = self._canonical_digests - proven = [] - for entry in manifest['inventory']: - family, record_id, digest = entry['family'], entry['id'], entry['sha256'] - record_raw = self._verified_record_bytes(entry) - if known is not None and digest in known: - # These exact bytes (named by their verified SHA256) were already - # proven to be their value's canonical encoding, which excludes - # duplicate keys and non-finite numbers; a plain parse is exact. - document = json.loads(record_raw) - else: - document = _decode(record_raw) - proven.append(digest) - if type(document) is not dict or document.get('format') != entry['format']: - _fail('Domain document format disagrees with its inventory.') - records_digest.add(family, record_id, record_raw) - loaded.append(dict(family=family, id=record_id, document=document)) - # _decode proved each raw revision is its document's canonical encoding. - if manifest['receipts'][-1]['records_sha256'] != records_digest.hexdigest(): - _fail('Latest operation receipt disagrees with the current record set.') - # A second pointer read detects checkout/replacement during closure validation. - if _read(self._meta_fd, 'project.json', MAX_MANIFEST_BYTES) != raw: - _fail('Project checkpoint changed while reading.', 'stale', 409) - self._binding() - if known is not None and proven: - known.add_many(proven) - # Domain owners see logical records: shared runtime closures hidden and - # compact Runs expanded to their exact original documents. - from project_record_dedupe import logical_records - logical = logical_records(loaded) - self._read_cache = (raw, manifest, logical, loaded) - return manifest, logical - - def _verified_record_bytes(self, entry): - raw = self._record_file(entry['family'], entry['id'], entry['sha256']) - if len(raw) != entry['bytes'] or _sha(raw) != entry['sha256']: - _fail('Canonical record bytes changed or are corrupt.', - 'stale' if self._manifest else 'invalid', 409 if self._manifest else 400) - return raw - - def _record_file(self, family, record_id, digest, raw=None, sync=False): - fds = [] - try: - parent = self._meta_fd - for part in ('records', family, record_id): - parent = _directory(parent, part, create=raw is not None) - fds.append(parent) - name = digest + '.json' - if raw is not None: - try: - existing = _read(parent, name, MAX_RECORD_BYTES) - except FileNotFoundError: - temporary = '.record-' + uuid.uuid4().hex + '.tmp' - _write_file(parent, temporary, raw) - try: - _rename_noreplace(parent, temporary, name) - except FileExistsError: - if _read(parent, name, MAX_RECORD_BYTES) != raw: - _fail('Immutable project revision already has different bytes.') - os.unlink(temporary, dir_fd=parent) - else: - if existing != raw: - _fail('Immutable project revision already has different bytes.') - # Existing revisions can come from a copied project or an - # interrupted earlier commit. Retain all ordinary sync checks; - # only the disposable write/rename/unlink cycle is avoided. - sync = True - if sync: - _sync_file(parent, name) - for fd in reversed(fds): - os.fsync(fd) - os.fsync(self._meta_fd) - return _read(parent, name, MAX_RECORD_BYTES) - finally: - for fd in reversed(fds): - os.close(fd) - - def _publish(self, manifest, creating=False): - raw = _manifest_raw(manifest) - temporary = '.checkpoint-' + uuid.uuid4().hex + '.tmp' - replaced = False - try: - _write_file(self._meta_fd, temporary, raw) - self._binding() - if not creating: - current, _ = self._load() - if current != self._manifest: - _fail('Project checkpoint changed before publication.', 'stale', 409) - # Creation owns a new exclusive directory; commit owns its root flock. - if creating: - _rename_noreplace(self._meta_fd, temporary, 'project.json') - replaced = True - else: - os.replace(temporary, 'project.json', src_dir_fd=self._meta_fd, dst_dir_fd=self._meta_fd) - replaced = True - os.fsync(self._meta_fd) - os.fsync(self._root_fd) - except OSError as exc: - self._unknown = replaced - _io_error(exc, 'publish checkpoint', unknown=replaced) - return raw - # Temporary/orphan files remain inert after failures and process interruption. - - def _snapshot(self, manifest, records): - return dict(project_id=manifest['project_id'], name=manifest['name'], - checkpoint=manifest['checkpoint'], records=copy_validated_json(records)) - - def _current(self): - try: - manifest, records = self._load() - if manifest != self._manifest: - _fail('Project checkpoint changed; close and reopen.', 'stale', 409) - return manifest, records - except OSError as exc: - _io_error(exc, 'read project snapshot') - - def verify_records(self): - """Re-read and SHA256-check every referenced canonical revision on disk. - - Ordinary freshness checks compare checkpoint bytes only; this explicit - pass detects later same-length corruption of already-decoded revisions. - """ - with self._mutex: - manifest, _records = self._current() - try: - for entry in manifest['inventory']: - self._verified_record_bytes(entry) - except OSError as exc: - _io_error(exc, 'verify project records') - if self._current()[0] != manifest: - _fail('Project checkpoint changed during verification.', 'stale', 409) - - def summary(self): - """Return scalar metadata after the checkpoint freshness check.""" - with self._mutex: - manifest, _records = self._current() - return {key: manifest[key] for key in ('project_id', 'name', 'checkpoint')} - - def snapshot(self): - with self._mutex: - manifest, records = self._current() - return self._snapshot(manifest, records) - - def reconcile(self, request_key, request_sha256): - """Inspect retry identity before a domain mutation; never repeat effects.""" - _request(request_key, request_sha256) - with self._mutex: - snapshot = self.snapshot() - for receipt in self._manifest['receipts']: - if receipt['request_key'] == request_key: - if receipt['request_sha256'] != request_sha256: - _fail('Request key was already used with different input.', 'conflict', 409) - return snapshot - return None - - def commit(self, records, expected_checkpoint, request_key, request_sha256): - _request(request_key, request_sha256) - _digest(expected_checkpoint, 'Expected checkpoint') - with self._mutex: - try: - current, loaded = self._load() - if current != self._manifest: - _fail('Project checkpoint changed; close and reopen.', 'stale', 409) - physical = self._read_cache[3] - # Unchanged records keep their verified canonical revision: no - # re-encoding, rewrite or read-back of identical immutable bytes. - entries = {(entry['family'], entry['id']): entry for entry in current['inventory']} - unchanged = {(item['family'], item['id']): (item['document'], entries[(item['family'], item['id'])]) - for item in physical} - candidates, logical_out = _physical_candidates(records, loaded, physical) - prepared = _prepared_records(candidates, unchanged) - if logical_out is None: - logical_out = [dict(family=f, id=i, document=d) for f, i, d, _, _ in prepared] - digest_rows = _RecordsDigest() - for family, identity, _document, raw, entry in prepared: - if raw is None: - raw = self._verified_record_bytes(entry) - digest_rows.add(family, identity, raw) - records_digest = digest_rows.hexdigest() - for receipt in current['receipts']: - if receipt['request_key'] == request_key: - if receipt['request_sha256'] != request_sha256 or receipt['records_sha256'] != records_digest: - _fail('Request key was already used with different input.', 'conflict', 409) - return self._snapshot(current, loaded) - if expected_checkpoint != current['checkpoint']: - _fail('Expected project checkpoint is stale.', 'stale', 409) - manifest = copy.deepcopy(current) - inventory = [] - for family, identity, document, raw, entry in prepared: - if raw is None: - inventory.append(copy.deepcopy(entry)) - continue - digest = _sha(raw) - inventory.append(dict(family=family, id=identity, format=document['format'], - namespace=current['project_id'], path=f'records/{family}/{identity}/{digest}.json', - bytes=len(raw), sha256=digest)) - manifest['inventory'] = inventory - manifest['roots'] = [dict(family=f, id=i) for f, i, _, _, _ in prepared] - manifest['receipts'].append(dict(request_key=request_key, - request_sha256=request_sha256, records_sha256=records_digest)) - del manifest['checkpoint'] - manifest['checkpoint'] = _sha(_encode(manifest)) - # Refuse before record staging. The final publication also - # rechecks this bound after the immutable files are durable. - _manifest_raw(manifest) - for family, identity, document, raw, _entry in prepared: - if raw is not None: - self._record_file(family, identity, _sha(raw), raw) - published = self._publish(manifest) - self._manifest = manifest - if self._canonical_digests is not None: - # Freshly written revisions are canonical by construction. - self._canonical_digests.add_many( - [_sha(raw) for _f, _i, _d, raw, _e in prepared if raw is not None]) - # Every committed revision is either freshly written and read - # back byte-for-byte or an unchanged verified revision. - self._read_cache = (published, manifest, logical_out, - [dict(family=f, id=i, document=d) for f, i, d, _, _ in prepared]) - return self._snapshot(manifest, logical_out) - except OSError as exc: - _io_error(exc, 'commit project records') - - def save(self, expected_checkpoint): - _digest(expected_checkpoint, 'Expected checkpoint') - with self._mutex: - snapshot = self.snapshot() - if expected_checkpoint != snapshot['checkpoint']: - _fail('Expected project checkpoint is stale.', 'stale', 409) - try: - # Save is the explicit durability and integrity boundary: sync and - # re-verify every referenced canonical revision's actual bytes. - for entry in self._manifest['inventory']: - raw = self._record_file(entry['family'], entry['id'], entry['sha256'], sync=True) - if len(raw) != entry['bytes'] or _sha(raw) != entry['sha256']: - _fail('Canonical record bytes changed or are corrupt.', 'stale', 409) - _sync_file(self._meta_fd, 'project.json') - os.fsync(self._meta_fd) - os.fsync(self._root_fd) - # Imported/copied roots may not yet have a durable directory entry. - parent_fd = _walk(self._origin_fd, self._relative_parts[:-1]) - try: - os.fsync(parent_fd) - finally: - os.close(parent_fd) - if self.snapshot() != snapshot: - _fail('Project changed during Save.', 'stale', 409) - except OSError as exc: - _io_error(exc, 'save project checkpoint') - return snapshot - - def recover_checkpoint(self): - """Explicitly re-read and sync this retained physical writer binding. - - Execution callers must first fence dispatch and drain actual local - custody. This method resolves only filesystem publication uncertainty; - it does not select a SQL outcome or authorize any work to resume. - """ - with self._mutex: - self._unknown = False - try: - manifest, records = self._load() - self._manifest = manifest - return self.save(self._snapshot(manifest, records)['checkpoint']) - except BaseException: - self._unknown = True - raise - - def close(self): - with self._mutex: - self._read_cache = None - if self._meta_fd is not None: - os.close(self._meta_fd) - self._meta_fd = None - if self._root_fd is not None: - # Closing releases the flock. Explicit unlock would release it in - # an inherited descriptor shared by a forked process too. - os.close(self._root_fd) - self._root_fd = None - if self._origin_fd is not None: - os.close(self._origin_fd) - self._origin_fd = None - - def __enter__(self): - return self - - def __exit__(self, *exc): - self.close() diff --git a/project_study_execution.py b/project_study_execution.py deleted file mode 100644 index af7ed930..00000000 --- a/project_study_execution.py +++ /dev/null @@ -1,811 +0,0 @@ -"""Current Study execution composed with exact inert project accounting. - -Only authoring metadata is reconstructed. Historical reservations and Runs stay -in canonical history; they contribute charges but never become worker, grant, -admission, replay, or cancellation rows in this physical runtime. -""" -import copy -from datetime import datetime, timezone -import hashlib -import json -import time -from types import SimpleNamespace - -from experiments import (Experiments, budget, request_key, validate_retained_reservation) -from model_definitions import natural, text -from pipeline import closed, identifier, digest -from project_history import (FAMILY_FORMATS, _audit, _sha, envelope, - decode_records as history_records) -from project_material import ProjectMaterial, MaterialSnapshot -from project_session import operation_records -from workbench import WorkbenchError, encode, timestamp -from project_session import session_operations, session_records - -PREPARATIONS={'study_execution.prepare_package':'studies.prepare_package', - 'study_execution.prepare_verifier':'studies.prepare_verifier'} -INTENTS={operation+'_intent':native for operation,native in PREPARATIONS.items()} -ABANDON='study_execution.abandon_preparation' -OPERATIONS=frozenset(('study_execution.admit','study_execution.stop','study_execution.approve',ABANDON,*PREPARATIONS,*INTENTS)) -GRANT_FIELDS=('id','catalog_id','approver_actor_id','approver_credential_id','consumer_actor_id', - 'material_sha256','created_at','expires_at','revoked_at') -RESERVATION_FIELDS=('id','study_id','admission_epoch','request_key','actor_id','trial_id','parent_run_id', - 'run_id','request_sha256','material_sha256','envelope','state','settled') - - -def _invalid(message,code='invalid'): - raise WorkbenchError(message,code,409) - - -def _facts(records): - return history_records(records,materials=MaterialSnapshot(records)) - - -def _intent_key(operation,key): - return 'candidate-'+digest(dict(key=key,operation=operation))+'-intent' - - -def _preparation_body(intent,key): - body=dict(request_key=key,revision=intent['study_revision'],candidate_id=intent['candidate']['id'], - root=intent['root'],directory=intent['directory'],runtime_snapshot_sha256=intent['runtime_snapshot_sha256']) - if 'package_run_id' in intent: - body.update(package_run_id=intent['package_run_id'],package_sha256=intent['package_sha256']) - return body - - -def _preparation_reference(records,study_id,key): - receipts=operation_records(records) - matches=[(operation,receipts[_intent_key(operation,key)]) for operation in PREPARATIONS - if _intent_key(operation,key) in receipts] - if len(matches)!=1:_invalid('Preparation requires one exact retained intent.','unavailable') - operation,receipt=matches[0] - if receipt['operation']!=operation+'_intent' or receipt['result']['study_id']!=study_id: - _invalid('Preparation intent belongs to another operation or Study.','conflict') - intent=receipt['result'];complete=receipts.get(key) - if complete is None: - # The native final Trial transaction publishes its exact scientific - # receipt before the outer transport acknowledgement. That fact closes - # preparation even when the later wrapper receipt was never published. - native_sha=digest(dict(study_id=study_id,body=_preparation_body(intent,key))) - native=[] - for record in records: - if record['family']!='study_history':continue - doc=record['document'] - if doc['origin_catalog_id']!=intent['origin_catalog_id'] or doc['study']['id']!=study_id:continue - native.extend(value for value in doc['operations'] if value['actor_id']==intent['actor_id'] - and value['operation_id']==PREPARATIONS[operation] and value['request_key']==key) - if len(native)>1:_invalid('Preparation has duplicate native completion facts.') - if native: - if native[0]['request_sha256']!=native_sha:_invalid('Native preparation completion differs from its exact intent.','conflict') - validate_operation_result(operation,native[0]['result'],records) - complete=dict(operation=operation,result=copy.deepcopy(native[0]['result']),native_receipt=True) - return operation,intent,complete - - -def _validate_abandon(result,records): - closed(result,('format','origin_catalog_id','study_id','preparation_key','preparation_operation', - 'input_sha256','candidate','actor_id','reason','observed_checkpoint','occurred_at','state')) - if result['format']!='project_candidate_preparation_abandon_v1' or result['state']!='abandoned': - _invalid('Unsupported candidate preparation abandonment.','unsupported') - for field in ('origin_catalog_id','study_id','actor_id'):identifier(result[field]) - request_key(result['preparation_key']);text(result['reason'],'Abandonment reason',1000) - for field in ('input_sha256','observed_checkpoint'):_sha(result[field]) - if result['preparation_operation'] not in PREPARATIONS:_invalid('Unknown preparation operation.') - from model_definitions import reference - reference(result['candidate'],'candidate',result['origin_catalog_id']) - if datetime.fromisoformat(result['occurred_at']).utcoffset() is None:_invalid('Abandonment time requires an offset.') - if records is not None: - operation,intent,complete=_preparation_reference(records,result['study_id'],result['preparation_key']) - if (operation!=result['preparation_operation'] or intent['origin_catalog_id']!=result['origin_catalog_id'] - or intent['candidate']!=result['candidate'] or intent['request_sha256']!=result['input_sha256']): - _invalid('Abandonment differs from its exact retained preparation intent.') - if complete is not None:_invalid('Completed scientific preparation cannot be abandoned.') - return True - - -def _validate_preparation(operation,result,records): - from candidate_packages import NAME,decode_preparation_receipt - from experiments import validate_retained_trial - from model_definitions import reference - intent=operation in INTENTS;native=INTENTS[operation] if intent else PREPARATIONS[operation] - if intent: - fields=('format','origin_catalog_id','study_id','study_revision','candidate','actor_id', - 'request_sha256','root','directory','runtime_snapshot_sha256') - if native=='studies.prepare_verifier':fields+=('package_run_id','package_sha256') - closed(result,fields) - if result['format']!='project_candidate_preparation_intent_v1':_invalid('Unsupported candidate preparation intent.','unsupported') - for field in ('origin_catalog_id','study_id','actor_id'):identifier(result[field]) - natural(result['study_revision'],'Study revision',1) - for field in ('request_sha256','runtime_snapshot_sha256'):_sha(result[field]) - reference(result['candidate'],'candidate',result['origin_catalog_id']) - for field in ('root','directory'): - if type(result[field]) is not str or NAME.fullmatch(result[field]) is None:_invalid('Invalid preparation location.') - if native=='studies.prepare_verifier':identifier(result['package_run_id']);_sha(result['package_sha256']) - else: - origin=result['trial']['material']['catalog_id'] - decode_preparation_receipt(native,result,catalog_id=origin, - validate_trial=lambda value:validate_retained_trial(value,catalog_id=origin)) - if records is None:return True - facts=_facts(records) - if intent: - origin=result['origin_catalog_id'];candidate=facts.candidates[(origin,result['candidate']['id'])]['candidate'] - if candidate['study_id']!=result['study_id'] or digest(candidate)!=result['candidate']['sha256']: - _invalid('Preparation intent differs from its immutable candidate.') - study=facts.studies[(origin,result['study_id'])] - if not any(value['revision']==result['study_revision'] for value in study['revisions']): - _invalid('Preparation intent lacks its exact Study revision.') - if native=='studies.prepare_verifier': - run=facts.runs[(origin,result['package_run_id'])]['run'] - if not any(item['name']=='package.zip' and item['sha256']==result['package_sha256'] for item in run['artifacts']): - _invalid('Verifier intent differs from the retained package bytes.') - else: - from project_history import validate_operation_result as validate_history_result - validate_history_result(native,result,records) - trial=result['trial'];origin=trial['material']['catalog_id'] - candidate=facts.candidates[(origin,result['candidate_id'])]['candidate'] - if candidate['study_id']!=trial['study_id']:_invalid('Preparation candidate belongs to another Study.') - materials=ProjectMaterial(SimpleNamespace(snapshot={'records':records},check_current=lambda:None)) - composition=materials.recipe(trial['material'])['material'] - if (composition['model']!=result['model'] or composition['recipe_id']!=result['graph']['id'] - or composition['recipe_revision']!=result['graph']['revision']): - _invalid('Preparation model or graph differs from its retained composition.') - descriptor=materials.runtime(composition['runtime'])['descriptor'] - if descriptor is None or descriptor['manifest_sha256']!=result['runtime_snapshot_sha256']: - _invalid('Preparation runtime differs from its retained composition.') - return True - - -def validate_operation_result(operation,result,records=None): - """Closed scientific acknowledgements; none grants current authority.""" - if operation not in OPERATIONS:return False - try: - if operation==ABANDON:return _validate_abandon(result,records) - if operation in PREPARATIONS or operation in INTENTS: - return _validate_preparation(operation,result,records) - if operation=='study_execution.admit': - closed(result,('format','origin_catalog_id','study_id','trial_id','run_id','reservation')) - if result['format']!='project_study_admission_v1':_invalid('Unsupported Study admission receipt.','unsupported') - for key in ('origin_catalog_id','study_id','trial_id','run_id'):identifier(result[key]) - reservation=result['reservation'];closed(reservation,RESERVATION_FIELDS) - for key in ('id','study_id','actor_id','trial_id','run_id'):identifier(reservation[key]) - if reservation['parent_run_id'] is not None:identifier(reservation['parent_run_id']) - natural(reservation['admission_epoch'],'Admission epoch');request_key(reservation['request_key']) - for key in ('request_sha256','material_sha256'):_sha(reservation[key]) - budget(reservation['envelope']) - if reservation['state'] not in ('reserved','running','settled','unknown'):_invalid('Invalid reservation observation.') - if reservation['settled'] is not None:budget(reservation['settled']) - if any(result[key]!=reservation[key] for key in ('study_id','trial_id','run_id')): - _invalid('Study admission references differ from their reservation.') - elif operation=='study_execution.stop': - closed(result,('format','origin_catalog_id','study_id','receipt','study_revision','state','open')) - if result['format']!='project_study_stop_v1':_invalid('Unsupported Study stop receipt.','unsupported') - identifier(result['origin_catalog_id']);identifier(result['study_id']);natural(result['study_revision'],'Study revision',1) - receipt=result['receipt'];closed(receipt,('study_id','stop_receipt_id','admission_epoch','run_ids')) - identifier(receipt['study_id']);identifier(receipt['stop_receipt_id']);natural(receipt['admission_epoch'],'Stop epoch') - if (receipt['study_id']!=result['study_id'] or result['open'] is not False - or result['state'] not in ('stopping','stopped','unknown') - or type(receipt['run_ids']) is not list or len(receipt['run_ids'])>10000):_invalid('Invalid Study epoch closure.') - for identity in receipt['run_ids']:identifier(identity) - if len(set(receipt['run_ids']))!=len(receipt['run_ids']):_invalid('Duplicate stopped Run identity.') - else: - closed(result,('format','origin_catalog_id','study_id','trial_id','approval_id','material_sha256', - 'consumer_actor_id','approver_actor_id','created_at','expires_at')) - if result['format']!='project_study_approval_v1':_invalid('Unsupported Study approval observation.','unsupported') - identifier(result['study_id']);identifier(result['trial_id']) - from project_execution import validate_operation_result as validate_execution_result - base={key:result[key] for key in ('origin_catalog_id','approval_id','material_sha256', - 'consumer_actor_id','approver_actor_id','created_at','expires_at')} - validate_execution_result('runs.approve_external',dict(format='project_execution_approval_v1',**base)) - if records is None:return True - facts=_facts(records) - if operation=='study_execution.admit': - origin=result['origin_catalog_id'];reservation=result['reservation'] - saved=facts.reservations.get((origin,result['run_id'])) - if saved is None or any(saved[key]!=reservation[key] for key in RESERVATION_FIELDS if key not in ('state','settled')): - _invalid('Admission receipt has no exact canonical reservation.') - trial=facts.trials[(origin,result['trial_id'])]['trial'];run=facts.runs[(origin,result['run_id'])]['run'] - view=SimpleNamespace(snapshot={'records':records},check_current=lambda:None) - validate_retained_reservation(reservation,trial=trial, - composition=ProjectMaterial(view).recipe(trial['material']),run=run) - elif operation=='study_execution.stop': - doc=facts.studies[(result['origin_catalog_id'],result['study_id'])];receipt=result['receipt'] - matches=[value for value in doc['revisions'] if value['revision']==result['study_revision']] - if (len(matches)!=1 or matches[0]['stop_receipt_id']!=receipt['stop_receipt_id'] - or matches[0]['admission_epoch']!=receipt['admission_epoch'] - or matches[0]['state']!=result['state'] or matches[0]['open']!=result['open']): - _invalid('Stop receipt has no exact retained epoch closure.') - if not set(receipt['run_ids'])<={value['run_id'] for value in doc['reservations']}: - _invalid('Stop receipt targets an unrelated Run.') - else: - origin=result['origin_catalog_id'];doc=facts.studies[(origin,result['study_id'])] - trial=facts.trials[(origin,result['trial_id'])]['trial'] - if trial['study_id']!=result['study_id'] or trial['material']['sha256']!=result['material_sha256']: - _invalid('Approval observation differs from its exact retained Trial.') - expected={key:result[key] for key in ('trial_id','material_sha256','approval_id','consumer_actor_id','created_at','expires_at')} - matches=[fact for fact in doc['audit'] if fact['action']=='studies.approve' - and fact['target']==result['study_id'] and fact['actor_id']==result['approver_actor_id'] - and fact['details']==expected] - if len(matches)!=1:_invalid('Approval receipt has no exact historical Study approval observation.') - return True - except WorkbenchError:raise - except (KeyError,TypeError,ValueError,AttributeError,OverflowError): - _invalid('Malformed current Study operation receipt.') - - -class _LocalRunsReference: - """Refer only to an explicitly activated local owner; never construct one.""" - def __init__(self,execution):self.execution=execution - def __getattr__(self,name):return getattr(self.execution.runs,name) - - -class _PreparationRuns: - """Scientific inputs only; this object cannot allocate or recover Runs.""" - def __init__(self,adapter):self.adapter=adapter;self.access=adapter.session.access - def _load(self,run_id): - history=self.adapter.history;history._authorize('runs.get',run_id) - facts=history._facts();doc=history._record(facts.runs,run_id,self.adapter.origin) - history._transitive(facts,doc);history._disclose(doc['run'],'unknown') - return copy.deepcopy(doc['run']) - @staticmethod - def _external(run):return run.get('execution_kind')=='external_recipe' - @staticmethod - def _extension(run): - from recipe_contract import is_evidence - return run.get('execution_kind')=='external_recipe' and is_evidence(run['material']['recipe']) - def artifact(self,run_id,name): - raw=self.adapter.history.artifact(run_id,name,origin_catalog_id=self.adapter.origin, - maximum_bytes=512*1024**2) - return raw,'application/octet-stream' - def model_evidence(self,run_id,selectors,*,contract_version=2): - if contract_version!=2:_invalid('Candidate preparation requires model evidence version 2.','unsupported') - return self.adapter.history.evidence(run_id,selectors,origin_catalog_id=self.adapter.origin) - def capture_artifact(self,*args,**kwargs):return self.adapter.history.capture_artifact(*args,**kwargs) - - -class _PreparationProjects: - def __init__(self,adapter,phase): - self.adapter,self.phase=adapter,phase;self.source=adapter.projection.sources - self.access=adapter.access - def __getattr__(self,name):return getattr(self.source,name) - def open(self,body): - return self.adapter.projection.source_adapter.register(body, - self.adapter.session.summary['checkpoint'],self.phase+'-source') - - -class _PreparationModels: - def __init__(self,adapter,phase):self.adapter,self.phase=adapter,phase - def material(self,ref,*,verify=False):return self.adapter.materials.model(ref,verify=verify) - def read_blob(self,ref,item):return self.adapter.materials.blob(ref,item) - def _read_blob(self,ref,item,maximum=40*1024**2):return self.adapter.materials.blob(ref,item,maximum) - def create(self,body): - adapter=self.adapter - return adapter.materials.mutate_definition('model_definition','models.create',None,body, - adapter.session.summary['checkpoint'],self.phase+'-model',lambda:adapter.projection.models.create(body)) - def publish(self,identity,body): - adapter=self.adapter - return adapter.materials.publish_model(adapter.projection.models,identity,body, - adapter.session.summary['checkpoint'],self.phase+'-publish') - - -class _PreparationPipelines: - def __init__(self,adapter,phase,context): - from pipeline import Pipelines - self.adapter,self.phase=adapter,phase;self.owner=Pipelines(context) - self.material_path=self.owner.material_path - def get(self,*args,**kwargs):return self.owner.get(*args,**kwargs) - def recipe_material(self,ref,*,verify=False):return self.adapter.materials.recipe(ref,verify=verify) - def create_external(self,body): - adapter=self.adapter - return adapter.materials.mutate_definition('pipeline_graph','graphs.create_external',None,body, - adapter.session.summary['checkpoint'],self.phase+'-graph',lambda:self.owner.create_external(body)) - def prepare_external_material(self,*args,**kwargs):return self.owner.prepare_external_material(*args,**kwargs) - def _retain_material(self,prepared): - adapter=self.adapter;value=self.owner._retain_material(prepared) - record=adapter.materials.capture_recipe_material(value,self.owner.material_path) - adapter._package_records.extend([record,*adapter.materials.declarations(record), - *adapter.materials.capture_recipe_dependencies(record,adapter.session.snapshot['records'])]) - return value - - -class ProjectStudyExecution: - def __init__(self,projection,execution): - self.projection,self.execution=projection,execution - self.session,self.db,self.history=projection.session,projection.db,projection.history - self.materials=projection.materials;self.access=execution.runtime_access - self.origin=self.session.summary['project_id'] - self._dirty=set();self._revisions={};self._epochs={};self._pending_epochs={} - self._package_records=[] - self.context=copy.copy(projection.context) - self.context.access,self.context.runs=self.access,_LocalRunsReference(execution) - self.context.project_study_execution=self - self.context.project_execution=execution - self.studies=Experiments(self.context) - execution.study_execution=self - projection.study_execution=self - self.history.study_execution=self - - def _canonical(self,records=None): - if records is None and callable(getattr(self.session,'derived',None)): - from project_history import checkpoint_facts - return checkpoint_facts(self.session,self.materials) - records=self.session.snapshot['records'] if records is None else records - return history_records(records,materials=self.materials.read_view(records)) - - def _authoring_facts(self,records=None): - """Studies and Trials of the bound checkpoint for SQL authoring. - - For a checkpoint whose complete validation is on record, only the Study - and Trial documents are needed and collected (no Run history); this is - exactly the studies/trials part of the complete decode. - """ - if records is None: - validated=getattr(self.session,'validated_checkpoint',None) - if validated is not None and validated==self.session.summary['checkpoint']: - from project_history import assemble_validated_facts - return assemble_validated_facts(session_records(self.session,'study_history','trial_history'),owned=True) - return self._canonical(records) - - def restore_authoring(self,records=None): - """Reconstruct intent only, under the current project guard.""" - with self.session.access.lock,self.session.lock,self.db.lock: - self.session.check_current();facts=self._authoring_facts(records) - with self.db.transaction(): - for (origin,identity),doc in sorted(facts.studies.items()): - if origin!=self.origin:continue - for item in doc['policies']: - ref=item['ref'] - self.db.execute('INSERT INTO model_selection_policies VALUES(%s,%s,%s,%s) ON CONFLICT(id,revision) DO UPDATE SET sha256=EXCLUDED.sha256,document=EXCLUDED.document', - (ref['id'],ref['revision'],ref['sha256'],encode(item['policy']))) - value=doc['study'] - self.db.execute('INSERT INTO model_studies VALUES(%s,%s,%s,%s) ON CONFLICT(id) DO UPDATE SET revision=EXCLUDED.revision,admission_epoch=EXCLUDED.admission_epoch,document=EXCLUDED.document', - (identity,value['revision'],value['admission_epoch'],encode(value))) - for member in doc['memberships']: - self.db.execute('INSERT INTO model_study_memberships VALUES(%s,%s,%s) ON CONFLICT(study_id,revision) DO UPDATE SET document=EXCLUDED.document', - (identity,member['revision'],encode({'trial_ids':member['trial_ids']}))) - for (origin,identity),doc in sorted(facts.trials.items()): - if origin!=self.origin:continue - value=doc['trial'] - self.db.execute('INSERT INTO model_trials VALUES(%s,%s,%s,%s,%s) ON CONFLICT(id) DO UPDATE SET document=EXCLUDED.document', - (identity,value['study_id'],value['material']['sha256'],value['replicate'],encode(value))) - for (origin,identity),doc in sorted(facts.trials.items()): - if origin!=self.origin or doc['lineage'] is None:continue - value=doc['lineage'];intent=value['intent'] - # Native current authoring only supports same-project SQL - # parent FKs; foreign history remains in the canonical view. - if any(ref is not None and ref['catalog_id']!=self.origin for ref in (intent['parent'],intent['baseline'])):continue - self.db.execute('INSERT INTO model_trial_lineage VALUES(%s,%s,%s,%s) ON CONFLICT(trial_id) DO UPDATE SET document=EXCLUDED.document', - (identity,(intent['parent'] or {}).get('trial_id'),(intent['baseline'] or {}).get('trial_id'),encode(value))) - return None - - refresh_authoring=restore_authoring - - def local_run_ids(self): - return {row[0] for row in self.db.execute('SELECT run_id FROM model_attempt_reservations')} - - def historical_reservations(self,study_id): - doc=self._canonical().studies.get((self.origin,study_id)) - if doc is None:return [] - local=self.local_run_ids() - return [copy.deepcopy(value) for value in doc['reservations'] if value['run_id'] not in local] - - def reject_historical_request(self,study_id,actor,key,sha): - for value in self.historical_reservations(study_id): - if value['request_key']==key: - _invalid('This request identifies an inert historical attempt; use a fresh key for new execution.','conflict') - - def run_fact(self,run_id): - identifier(run_id) - if self.db.execute('SELECT id FROM workspace_runs WHERE id=%s',(run_id,)).fetchone() is not None: - return copy.deepcopy(self.execution.runs._load(run_id)) - value=self._canonical().runs.get((self.origin,run_id)) - if value is None:_invalid('Retained Run observation is unavailable.','not_found') - return copy.deepcopy(value['run']) - - def lineage_fact(self,trial_id): - value=self._canonical().trials.get((self.origin,trial_id)) - return copy.deepcopy(value['lineage']) if value is not None else None - - def epoch_current(self,study): - return study['open'] and self._epochs.get(study['id'])==study['admission_epoch'] - - def require_current_epoch(self,study): - if not self.epoch_current(study): - _invalid('Explicitly continue this Study in the current runtime before admission.','unavailable') - - def external_blocked(self): - owner=getattr(self.execution,'_runs',None) - return bool(owner is not None and owner._external_blocked) - - def mark_study(self,study_id): - identifier(study_id) - if not self.db.in_transaction:raise RuntimeError('Study publication requires its owning SQL transaction.') - value=self.studies._study(study_id) - self._dirty.add(study_id) - versions=self._revisions.setdefault(study_id,{}) - prior=versions.get(value['revision']) - if prior is not None and prior!=value:_invalid('A Study revision changed inside its publication transaction.') - versions[value['revision']]=copy.deepcopy(value) - - def _operation_study(self,operation,result): - if operation in ('studies.create','studies.save','studies.continue'):return result['id'] - if operation in ('studies.prepare_trial','studies.prepare_branch'):return result['study_id'] - if operation in ('studies.branch_trial','studies.stop'):return result['study_id'] - if operation=='studies.select_candidate':return result['candidate']['study_id'] - if operation in ('studies.prepare_package','studies.prepare_verifier'):return result['trial']['study_id'] - if operation=='studies.record_lineage':return self.studies.trial(result['trial']['trial_id'])['study_id'] - _invalid('Unclassified native Study operation result.','unsupported') - - def mark_operation(self,operation,result): - self.mark_study(self._operation_study(operation,result)) - - def settle_runs(self,run_ids): - if not run_ids:return - if not self.db.in_transaction:raise RuntimeError('Reservation settlement must share Run publication.') - studies={row['study_id'] for row in self.db.execute('SELECT study_id,run_id FROM model_attempt_reservations') if row['run_id'] in run_ids} - if studies: - with self.access._reconcile(): - for identity in sorted(studies):self.studies._reconcile_local(identity) - - @staticmethod - def _audit_fact(row): - return dict(actor_id=row['actor_id'],action=row['action'],target=json.loads(row['target_json']), - details=json.loads(row['details_json']),result=row['result'], - occurred_at=datetime.fromtimestamp(row['created_at'],timezone.utc).isoformat()) - - def capture_dirty(self,before_records): - # Execution has already qualified this observation against current - # local custody. These finite metadata reads must not ask the child - # continuation to acquire unrelated Study/policy capabilities. - with self.access._reconcile(): - return self._capture_dirty(before_records) - - def _capture_dirty(self,before_records): - if not self._dirty:return copy.deepcopy(self._package_records) - facts=self._canonical(before_records);records=copy.deepcopy(self._package_records) - audit_rows=list(self.db.execute('SELECT actor_id,action,target_json,details_json,result,created_at FROM access_audit ORDER BY created_at,id')) - operation_rows=list(self.db.execute('SELECT actor_id,operation_id,request_key,request_sha256,document FROM model_operation_receipts ORDER BY actor_id,operation_id,request_key')) - for study_id in sorted(self._dirty): - old=facts.studies.get((self.origin,study_id));value=self.studies._study(study_id) - doc=copy.deepcopy(old) if old is not None else dict(format=FAMILY_FORMATS['study_history'],origin_catalog_id=self.origin, - study=value,memberships=[],policies=[],reservations=[],operations=[],revisions=[],audit=[],revision_history_complete=True) - revisions={item['revision']:item for item in doc['revisions']} - for revision,item in self._revisions.get(study_id,{}).items(): - if revision in revisions and revisions[revision]!=item:_invalid('Published Study revision cannot change.') - revisions[revision]=copy.deepcopy(item) - if value['revision'] in revisions and revisions[value['revision']]!=value:_invalid('Current Study differs from captured revision.') - revisions[value['revision']]=copy.deepcopy(value) - doc['study']=copy.deepcopy(value);doc['revisions']=[revisions[key] for key in sorted(revisions)] - if old is None and min(revisions)!=1:doc['revision_history_complete']=False - doc['memberships']=[dict(revision=row['revision'],trial_ids=json.loads(row['document'])['trial_ids']) - for row in self.db.execute('SELECT revision,document FROM model_study_memberships WHERE study_id=%s ORDER BY revision',(study_id,))] - policies={item['ref']['sha256']:item for item in doc['policies']} - ref=value['policy'];policies[ref['sha256']]=dict(ref=copy.deepcopy(ref),policy=self.studies.policy(ref)) - doc['policies']=[policies[key] for key in sorted(policies)] - reservations={item['run_id']:item for item in doc['reservations']} - reservations.update((item['run_id'],item) for item in self.studies._local_reservations(study_id)) - doc['reservations']=sorted(reservations.values(),key=lambda item:item['id']) - operations={(item['actor_id'],item['operation_id'],item['request_key']):item for item in doc['operations']} - for row in operation_rows: - result=json.loads(row['document']) - if self._operation_study(row['operation_id'],result)!=study_id:continue - item=dict(actor_id=row['actor_id'],operation_id=row['operation_id'],request_key=row['request_key'], - request_sha256=row['request_sha256'],result=result) - key=item['actor_id'],item['operation_id'],item['request_key'] - if key in operations and operations[key]!=item:_invalid('A retained native operation fact changed.') - operations[key]=item - doc['operations']=[operations[key] for key in sorted(operations)] - targets={study_id,*value['trial_ids'],*(item['run_id'] for item in doc['reservations'])} - candidates=[] - for row in self.db.execute('SELECT id,document FROM model_candidates WHERE study_id=%s',(study_id,)): - candidate=json.loads(row['document']);targets.add(candidate['id']) - candidates.append(envelope('candidate_history',self.origin,candidate['id'],dict( - format=FAMILY_FORMATS['candidate_history'],origin_catalog_id=self.origin,candidate=candidate))) - for row in audit_rows: - if not (row['action'].startswith('studies.') or row['action'].startswith('runs.')):continue - fact=self._audit_fact(row) - if fact['target'] not in targets:continue - _audit([fact]) - if fact not in doc['audit']:doc['audit'].append(fact) - records.append(envelope('study_history',self.origin,study_id,doc));records.extend(candidates) - for trial_id in value['trial_ids']: - trial=self.studies.trial(trial_id) - row=self.db.execute('SELECT document FROM model_trial_lineage WHERE trial_id=%s',(trial_id,)).fetchone() - prior=facts.trials.get((self.origin,trial_id));lineage=json.loads(row[0]) if row is not None else (prior['lineage'] if prior else None) - records.append(envelope('trial_history',self.origin,trial_id,dict(format=FAMILY_FORMATS['trial_history'], - origin_catalog_id=self.origin,trial=trial,lineage=lineage))) - return records - - def abandon_pending(self): - """Discard only unpublished projection bookkeeping during guarded repair. - - This cannot activate an imported epoch or recreate any execution right. - The root recovery owner separately qualifies custody and exact selection. - """ - self._dirty.clear();self._revisions.clear();self._pending_epochs.clear() - self._package_records.clear() - - def outcome(self,outcome): - if outcome not in ('committed','rolled_back','unknown'):raise ValueError('Unsupported Study SQL outcome.') - if outcome=='unknown':return - if outcome=='committed':self._epochs.update(self._pending_epochs) - self._dirty.clear();self._revisions.clear();self._pending_epochs.clear() - self._package_records.clear() - - def _mutate(self,operation,study_id,body,expected_checkpoint,key,invoke,scope): - return self.execution.mutate(operation,study_id,body,expected_checkpoint,key,invoke, - lambda result,before:dict(records=[],result=result),scope=scope) - - def continue_study(self,study_id,body,expected_checkpoint,key): - closed(body,('revision','admission_epoch'));request_key(key) - self.access.require('execute','studies.continue',study_id,owner_only=True) - with self.session.access.lock,self.session.lock,self.db.lock: - self.refresh_authoring() - prior=session_operations(self.session).get(key) - if prior is not None and not self.epoch_current(self.studies._study(study_id)): - _invalid('A historical Continue receipt cannot activate this runtime; use a fresh key.','unavailable') - def invoke(): - value=self.studies.continue_study(study_id,dict(body,request_key=key)) - self._pending_epochs[study_id]=value['admission_epoch'] - return value - return self._mutate('studies.continue',study_id,body,expected_checkpoint,key,invoke,'execute') - - def _current_grant(self,value,approver): - row=self.db.execute('SELECT * FROM access_execution_grants WHERE id=%s',(value['approval_id'],)).fetchone() - if row is None:_invalid('This approval is historical; approve explicitly with a fresh key.','unavailable') - grant=dict(row);closed(grant,GRANT_FIELDS) - expected=dict(origin_catalog_id=grant['catalog_id'],approval_id=grant['id'], - **{key:grant[key] for key in ('material_sha256','consumer_actor_id','approver_actor_id','created_at','expires_at')}) - if (any(value[key]!=item for key,item in expected.items()) or grant['approver_actor_id']!=approver - or grant['revoked_at'] is not None or grant['expires_at']<=int(time.time())): - _invalid('An exact current local execution approval is unavailable.','unavailable') - return grant - - def _materialize_trial(self,study_id,trial_id,expected_sha256=None): - """Explicit preparation reconstructs only the current private caches.""" - study=self.studies._study(study_id);trial=self.studies.trial(trial_id) - if trial['study_id']!=study_id or trial_id not in study['trial_ids']: - _invalid('Prepare an exact member Trial.') - if expected_sha256 is not None and trial['material']['sha256']!=expected_sha256: - _invalid('Composed material differs. Review the exact Trial.','stale') - value=self.materials.recipe(trial['material']);material=value['material'] - snapshot=json.loads(self.materials.blob(trial['material'],material['recipe_document'],2*1024**2)) - if snapshot['format']!='builtin_recipe_snapshot_v1': - # Current permission is independent from the original input proof. - # Verify every protected producer before rebuilding captured bytes. - for item in snapshot['preflight']['material']['inputs'].values(): - if item.get('kind')=='run_artifact': - source=item['source'] - self.history.capture_artifact(source['run_id'],source['artifact_name'],source['measured_sha256'], - origin_catalog_id=source['catalog_id']) - self.materials.materialize_projection(material['model'],self.projection.models.path) - self.materials.materialize_projection(trial['material'],self.projection.pipelines.material_path) - return trial - - def approve(self,study_id,body,expected_checkpoint,key): - closed(body,('trial_id','expected_material_sha256','consumer_actor_id'),('ttl_seconds',));request_key(key) - current=self.access.require('approve-execution','studies.approve',study_id,owner_only=True) - effective=dict(body,approver_actor_id=current.actor_id) - with self.session.access.lock,self.session.lock,self.db.lock: - self.refresh_authoring();prior=session_operations(self.session).get(key) - if prior is not None: - if prior['operation']!='study_execution.approve':_invalid('Request key has another operation.','conflict') - validate_operation_result(prior['operation'],prior['result'],self.session.snapshot['records']) - self._current_grant(prior['result'],current.actor_id) - else: - if expected_checkpoint!=self.session.summary['checkpoint']:_invalid('Expected project checkpoint changed.','stale_project') - self._materialize_trial(study_id,body['trial_id'],body['expected_material_sha256']) - def invoke(): - grant=self.studies.approve(study_id,body) - return dict(format='project_study_approval_v1',origin_catalog_id=grant['catalog_id'], - study_id=study_id,trial_id=body['trial_id'],approval_id=grant['id'], - **{key:grant[key] for key in ('material_sha256','consumer_actor_id','approver_actor_id','created_at','expires_at')}) - value=self._mutate('study_execution.approve',study_id,effective,expected_checkpoint,key,invoke,'approve-execution') - grant=self._current_grant(value,current.actor_id) - return dict(format='project_current_execution_approval_v1',current_local=True,grant=grant) - - def admit(self,study_id,body,expected_checkpoint,key): - closed(body,('revision','admission_epoch','trial_id'),('approval_id','parent_run_id'));request_key(key) - authority=self.access.require_external_submission() - with self.session.access.lock,self.session.lock,self.db.lock: - builtin=None - self.session.check_current();self.refresh_authoring() - prior=session_operations(self.session).get(key) - if prior is not None: - result=prior['result'] - if (prior['operation']!='study_execution.admit' or self.db.execute( - 'SELECT run_id FROM model_attempt_reservations WHERE run_id=%s',(result.get('run_id'),)).fetchone() is None): - _invalid('A historical admission receipt cannot create a current local attempt.','unavailable') - else: - if expected_checkpoint!=self.session.summary['checkpoint']:_invalid('Expected project checkpoint changed.','stale_project') - self.require_current_epoch(self.studies._study(study_id)) - self.reject_historical_request(study_id,authority.actor_id,key,None) - trial=self._materialize_trial(study_id,body['trial_id']) - from pipeline import BUILTIN_TRAINERS - material=self.materials.recipe(trial['material']) - if material['material']['trainer']['id'] in BUILTIN_TRAINERS: - self.access.require('execute','studies.admit_builtin',study_id,owner_only=True) - from project_native_execution import native_admission_wall_seconds - if material['material']['resource_envelope']['admitted_wall_seconds'] 64: - _invalid('Invalid text timestamp.') - try: - parsed = datetime.fromisoformat(value) - if parsed.utcoffset() is None: - raise ValueError() - return parsed - except (ValueError, OverflowError): - _invalid('Invalid text timestamp.') - - -SNAPSHOT_FIELDS = set('id kind name text content_hash pixel_hash groups parents provenance task annotation review revision created_at updated_at width height source_revision source_sha256 book_id session_id source_split corner_annotation source_available source_lineage_known'.split()) -IMMUTABLE_FIELDS = set('id kind name text content_hash pixel_hash parents provenance created_at width height source_revision source_sha256 book_id session_id source_split corner_annotation source_available source_lineage_known'.split()) -AUDIT_ACTIONS = {'workbench.import_asset', 'workbench.save', 'workbench.approve_review'} -SHA256 = re.compile(r'^[a-f0-9]{64}$') -REQUEST_KEY = re.compile(r'^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$') - - -def _snapshot(value, identity, original): - _shape(value, SNAPSHOT_FIELDS, 'text snapshot') - if value['id'] != identity or value['kind'] != 'text': - _invalid('Text snapshot identity mismatch.') - if type(value['revision']) is not int or value['revision'] < 1: - _invalid('Invalid text revision.') - if type(value['source_revision']) is not int or value['source_revision'] != 1: - _invalid('Invalid text source revision.') - if any(value[key] is not None for key in ('pixel_hash', 'width', 'height', 'book_id', 'session_id', 'corner_annotation')): - _invalid('Text snapshot contains non-text source fields.') - if value['source_available'] is not True or value['source_lineage_known'] is not True or value['source_split'] != 'unassigned': - _invalid('Invalid text source state.') - if text_value(value['name'], 'Name') != value['name']: - _invalid('Text name must retain canonical spelling.') - normalized = unicodedata.normalize('NFC', original.replace('\r\n', '\n').replace('\r', '\n')) - if value['text'] != normalized or value['content_hash'] != _sha(normalized) or value['source_sha256'] != _sha(original): - _invalid('Text source, normalization or hash mismatch.') - for key in ('groups', 'parents'): - if strings(value[key], key) != value[key] or (key == 'groups' and not value[key]): - _invalid('Invalid text ' + key + '.') - if any(not IDENTIFIER.fullmatch(parent) for parent in value['parents']): - _invalid('Invalid text parent identity.') - origin = value['provenance'] - _shape(origin, {'method', 'rights', 'normalization'}, 'text provenance') - if origin['method'] != 'import' or origin['normalization'] != 'NFC; LF newlines' or text_value(origin['rights'], 'Rights', 1000) != origin['rights']: - _invalid('Unsupported text provenance.') - if value['task'] not in ('text_classification', 'text_entities', 'text_corpus') or value['review'] not in ('draft', 'human_reviewed'): - _invalid('Invalid text task or review.') - if value['annotation'] is None: - if value['revision'] != 1 or value['task'] != 'text_classification' or value['review'] != 'draft': - _invalid('Missing text annotation after import.') - elif validate_annotation(value['task'], value['annotation'], value) != value['annotation']: - _invalid('Text annotation is not canonical.') - if _time(value['updated_at']) < _time(value['created_at']): - _invalid('Text update precedes creation.') - - -def decode_records(records): - """Validate complete text closure before any SQL write; return an owned copy.""" - if type(records) is not list or len(records) > 100_000: - _invalid('Project text records must be a bounded list.') - documents, operations, hashes = {}, set(), set() - for envelope in records: - _shape(envelope, {'family', 'id', 'document'}, 'text envelope') - if envelope['family'] != 'workbench_text': - raise ProjectTextError('Unsupported project record family.', 'unsupported', 409) - identity, document = envelope['id'], envelope['document'] - if type(identity) is not str or not IDENTIFIER.fullmatch(identity) or identity in documents: - _invalid('Invalid or duplicate text identity.') - if type(document) is not dict: - _invalid('Text document must be an object.') - if document.get('format') != 'workbench_text_v1': - raise ProjectTextError('Unsupported text document format.', 'unsupported', 409) - _shape(document, {'format', 'original_text', 'current', 'history', 'audit', 'operations'}, 'text document') - original = document['original_text'] - text_value(original, 'Original text', MAX_TEXT) - history = document['history'] - if type(history) is not list or not history: - _invalid('Text history must contain every revision.') - previous = None - for revision, state in enumerate(history, 1): - _snapshot(state, identity, original) - if state['revision'] != revision: - _invalid('Text history revisions must be contiguous.') - if previous and (any(state[key] != previous[key] for key in IMMUTABLE_FIELDS) or _time(state['updated_at']) < _time(previous['updated_at'])): - _invalid('Text history changes immutable source or reverses time.') - previous = state - _snapshot(document['current'], identity, original) - if document['current'] != history[-1] or history[0]['annotation'] is not None: - _invalid('Text current value or initial history is inconsistent.') - if document['current']['content_hash'] in hashes: - _invalid('Duplicate canonical text.') - hashes.add(document['current']['content_hash']) - audit, receipts = document['audit'], document['operations'] - if type(audit) is not list or type(receipts) is not list or len(audit) != len(history) or len(receipts) != len(history): - _invalid('Every text revision requires its audit and operation facts.') - for revision, (fact, receipt, state) in enumerate(zip(audit, receipts, history), 1): - _shape(fact, {'action', 'target', 'details', 'result', 'actor_id', 'occurred_at'}, 'text audit') - expected_action = 'workbench.import_asset' if revision == 1 else 'workbench.approve_review' if state['review'] == 'human_reviewed' else 'workbench.save' - details = {'revision': revision, 'source_revision': 1, 'content_sha256': _sha(encode(state))} - if revision > 1: - details.update(before_revision=revision - 1, before_source_revision=1) - _shape(fact['details'], details, 'text audit details') - if any(type(fact['details'][key]) is not type(expected) for key, expected in details.items()): - _invalid('Invalid text audit detail types.') - if fact['action'] != expected_action or fact['target'] != identity or fact['details'] != details or fact['result'] != 'success': - _invalid('Invalid text audit evidence.') - if type(fact['actor_id']) is not str or not IDENTIFIER.fullmatch(fact['actor_id']): - _invalid('Invalid historical text actor identity.') - if _time(fact['occurred_at']) < _time(state['updated_at']): - _invalid('Text audit precedes its mutation.') - _shape(receipt, {'request_key', 'request_sha256', 'action', 'target', 'revision'}, 'text operation') - key, digest = receipt['request_key'], receipt['request_sha256'] - if type(key) is not str or not REQUEST_KEY.fullmatch(key) or key in operations or type(digest) is not str or not SHA256.fullmatch(digest): - _invalid('Invalid or duplicate text operation identity.') - if receipt['target'] != identity or type(receipt['revision']) is not int or receipt['revision'] != revision or receipt['action'] != ('import_text' if revision == 1 else 'annotate'): - _invalid('Text operation revision or target mismatch.') - operations.add(key) - documents[identity] = document - # Parents are authored source lineage. They must exist, precede children, - # and form a closed acyclic graph; no foreign family can supply authority. - for identity, document in documents.items(): - current = document['current'] - for parent in current['parents']: - if parent not in documents or _time(documents[parent]['current']['created_at']) > _time(current['created_at']): - _invalid('Text parent reference is missing or newer than its child.') - visiting, visited = set(), set() - for identity in documents: - stack = [(identity, False)] - while stack: - node, leaving = stack.pop() - if leaving: - visiting.remove(node) - visited.add(node) - elif node not in visited: - if node in visiting: - _invalid('Text parent lineage contains a cycle.') - visiting.add(node) - stack.append((node, True)) - stack.extend((parent, False) for parent in documents[node]['current']['parents']) - return copy.deepcopy(records) - - -class _HostAccess: - """Current authorization stays at the installation; only inert facts travel.""" - def __init__(self, host): - self.host, self.facts = host, None - - def require(self, *args, **kwargs): - return self.host.require(*args, **kwargs) - - def denial(self, *args, **kwargs): - return self.host.denial(*args, **kwargs) - - def audit(self, action, target=None, details=None, result='success'): - if self.facts is None or action not in AUDIT_ACTIONS or result != 'success': - raise ProjectTextError('This project operation is unavailable in M1.', 'unavailable', 409) - context = self.host.require('edit', action, target) - self.facts.append(dict(action=action, target=target, details=copy.deepcopy(details or {}), - result=result, actor_id=context.actor_id, occurred_at=timestamp())) - - -class ProjectText: - def __init__(self, store, db, access): - self.store, self.db, self.access = store, db, access - self._lock = threading.RLock() - self._authority = _HostAccess(access) - inert = SimpleNamespace(db=db, lock=db.lock, path=db.path, access=self._authority) - self._workbench = Workbench(inert) - self._snapshot = None - self.available = False - - @property - def checkpoint(self): - return self._snapshot['checkpoint'] if self._snapshot else None - - def _authorize(self, scope, action, target=None): - self.access.require(scope, action, target) - - def _bound(self): - if not self.available: - raise ProjectTextError('Project projection requires reconstruction.', 'projection_unavailable', 503) - current = self.store.snapshot() - if current['checkpoint'] != self.checkpoint: - raise ProjectTextError('Project changed outside this projection. Reload it.', 'stale_project', 409) - return current - - def _tag(self, value, request_key=None): - result = dict(value, project_id=self._snapshot['project_id'], checkpoint=self.checkpoint) - if request_key is not None: - result['request_key'] = request_key - return result - - def restore(self, snapshot=None): - """Replace only this disposable text projection after full validation.""" - with self._lock, self.db.lock: - if self.db.in_transaction: - raise ProjectTextError('Reconstruction must own its SQL transaction.', 'unavailable', 409) - current = self.store.snapshot() - if snapshot is not None and snapshot != current: - raise ProjectTextError('Restore snapshot is stale.', 'stale_project', 409) - records = decode_records(current['records']) - self.available = False - with self.db.transaction(): - if self.db.execute("SELECT 1 FROM workbench_records WHERE kind<>'text' LIMIT 1").fetchone() or self.db.execute('SELECT 1 FROM samples LIMIT 1').fetchone(): - raise ProjectTextError('M1 requires an isolated text projection.', 'unavailable', 409) - self.db.execute('DELETE FROM workbench_history') - self.db.execute('DELETE FROM workbench_rights_notes') - self.db.execute('DELETE FROM workbench_target_proposals') - self.db.execute('DELETE FROM workbench_records') - for envelope in records: - doc, row = envelope['document'], envelope['document']['current'] - self.db.execute('''INSERT INTO workbench_records - (id,kind,name,text,original_text,content_hash,pixel_hash,groups_json,parents_json,provenance_json,task,annotation_json,review,revision,created_at,updated_at) - VALUES (%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s)''', - (row['id'], 'text', row['name'], row['text'], doc['original_text'], row['content_hash'], None, - encode(row['groups']), encode(row['parents']), encode(row['provenance']), row['task'], - encode(row['annotation']) if row['annotation'] is not None else None, row['review'], row['revision'], row['created_at'], row['updated_at'])) - for state in doc['history']: - self._workbench._history(state) - if self.store.summary()['checkpoint'] != current['checkpoint']: - raise ProjectTextError('Project changed during reconstruction.', 'stale_project', 409) - self._snapshot, self.available = current, True - return copy.deepcopy(current) - - def query(self, options=None): - with self.access.lock, self._lock, self.db.lock: - self._authorize('inspect', 'workbench.query') - self._bound() - result = self._workbench.query(options or {}) - self._bound() - return self._tag(result) - - def records(self): - """Full current values for the controller's bounded public projection. - - Canonical values come from one verified snapshot, avoiding pagination - truncation and repeated full inventory reads for each individual row. - """ - with self.access.lock, self._lock, self.db.lock: - self._authorize('inspect', 'workbench.query') - current = self._bound() - return self._tag({'items': [envelope['document']['current'] for envelope in current['records']]}) - - def get(self, record_id): - with self.access.lock, self._lock, self.db.lock: - self._authorize('inspect', 'workbench.get', record_id) - self._bound() - result = self._workbench.get(record_id) - self._bound() - return self._tag(result) - - def history(self, record_id): - with self.access.lock, self._lock, self.db.lock: - self._authorize('inspect', 'workbench.history', record_id) - self._bound() - result = self._workbench.history(record_id) - self._bound() - return [self._tag(state) for state in result] - - def import_text(self, body, expected_checkpoint, request_key): - if type(body) is not dict or set(body) - {'kind', 'text', 'name', 'groups', 'parents', 'rights'} or body.get('kind', 'text') != 'text': - raise ProjectTextError('Only text import is available in M1.', 'unavailable', 409) - return self._mutate('import_text', None, body, expected_checkpoint, request_key) - - def annotate(self, record_id, body, expected_checkpoint, request_key): - _shape(body, {'revision', 'source_revision', 'task', 'annotation', 'groups', 'review'}, 'annotation request') - if body['task'] not in ('text_classification', 'text_entities', 'text_corpus') or body['review'] not in ('draft', 'human_reviewed'): - raise ProjectTextError('This annotation operation is unavailable in M1.', 'unavailable', 409) - return self._mutate('annotate', record_id, body, expected_checkpoint, request_key) - - def _mutate(self, action, record_id, body, expected_checkpoint, request_key): - # Current owner permission cannot be revoked between authorization and - # canonical publication. Match the controller's host-before-projection - # lock order, including standalone callers of this domain adapter. - with self.access.lock: - return self._mutate_authorized(action, record_id, body, expected_checkpoint, request_key) - - def _mutate_authorized(self, action, record_id, body, expected_checkpoint, request_key): - self._authorize('edit', 'workbench.import_asset' if action == 'import_text' else 'workbench.save', record_id) - if type(request_key) is not str or not REQUEST_KEY.fullmatch(request_key): - _invalid('Supply a bounded operation request key.') - body = copy.deepcopy(body) - try: - digest = _sha(encode(dict(action=action, target=record_id, body=body))) - except (ValueError, TypeError, UnicodeError): - _invalid('Project mutation must contain valid finite JSON.') - with self._lock, self.db.lock: - if self.db.in_transaction: - raise ProjectTextError('Project mutation must own its SQL transaction.', 'unavailable', 409) - current = self._bound() - replay = self.store.reconcile(request_key, digest) - if replay is not None: - for envelope in current['records']: - doc = envelope['document'] - for receipt in doc['operations']: - if receipt['request_key'] == request_key and receipt['request_sha256'] == digest: - return self._tag(doc['history'][receipt['revision'] - 1], request_key) - _invalid('Project operation receipt has no text result.') - if expected_checkpoint != self.checkpoint: - raise ProjectTextError('Expected project checkpoint changed.', 'conflict', 409) - committed = None - self._authority.facts = [] - try: - with self.db.transaction(): - result = (self._workbench.import_asset(dict(body, kind='text')) if action == 'import_text' - else self._workbench.save(record_id, body)) - identity = result['id'] - records = copy.deepcopy(current['records']) - envelope = next((item for item in records if item['id'] == identity), None) - if envelope is None: - original = self.db.execute('SELECT original_text FROM workbench_records WHERE id=%s', (identity,)).fetchone()[0] - envelope = dict(family='workbench_text', id=identity, - document=dict(format='workbench_text_v1', original_text=original, current=None, history=[], audit=[], operations=[])) - records.append(envelope) - document = envelope['document'] - document['current'] = result - document['history'].append(result) - document['audit'].extend(self._authority.facts) - document['operations'].append(dict(request_key=request_key, request_sha256=digest, action=action, - target=identity, revision=result['revision'])) - records = decode_records(records) - # Canonical publication is inside the outer SQL transaction, - # so Workbench savepoints cannot acknowledge DB-only work. - committed = self.store.commit(records, self.checkpoint, request_key, digest) - self._snapshot = committed - return self._tag(result, request_key) - except BaseException as error: - if committed is not None: - self._snapshot, self.available = committed, False - failure = ProjectTextError('Canonical edit committed; reconstruct the unavailable SQL projection.', 'projection_unavailable', 503) - failure.committed, failure.project_id = True, committed['project_id'] - failure.checkpoint, failure.request_key = committed['checkpoint'], request_key - failure.receipt = dict(committed=True, selected=True, project_id=committed['project_id'], - checkpoint=committed['checkpoint'], request_key=request_key) - raise failure from error - if getattr(error, 'code', None) in ('unknown', 'outcome_unknown'): - self.available = False - raise - finally: - self._authority.facts = None diff --git a/project_transfer.py b/project_transfer.py deleted file mode 100644 index 2fb1d3ec..00000000 --- a/project_transfer.py +++ /dev/null @@ -1,783 +0,0 @@ -"""Explicit, report-first extraction of a stopped legacy catalog. - -Preview creates no domain supervisors and writes no source files. Only the -currently owned controller can stop and hand over a live stopped-source lease. -The private backup remains a legacy backup, never a portable authority dump. -""" -import copy -from contextlib import contextmanager -import hashlib -import json -import os -from pathlib import Path -import re -import stat -import threading -import time -import uuid -import weakref - -import psycopg -from psycopg import sql - -from metadata import Metadata, SCHEMA_VERSION, row_factory, _key -from project_store import (DIR_FLAGS, FILE_FLAGS, ProjectStore, - _rename_noreplace, _encode) -from project_artifacts import ProjectArtifacts, validate_declaration -from workbench import WorkbenchError, timestamp - -UUID=re.compile(r'^[a-f0-9]{32}$') -SHA=re.compile(r'^[a-f0-9]{64}$') -ALIAS=re.compile(r'^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$') -ROOT_FAMILIES={ - 'records':'workbench_record','responses':'workbench_response','preferences':'workbench_preference', - 'selections':'saved_selection','searches':'saved_search','graphs':'pipeline_graph', - 'recipe_drafts':'recipe_definition','model_definitions':'model_definition','studies':'study_history', - 'runs':'run_history','releases':'dataset_release','exposures':'dataset_exposure', - 'model_materials':'model_material','recipe_materials':'recipe_material','runtime_materials':'runtime_material'} -NAMESPACED={'pipeline_graph','recipe_definition','model_definition','study_history','trial_history', - 'run_history','candidate_history','model_material','recipe_material','runtime_material','project_snapshot', - 'generation_history','grounded_history','caption_proposal_history','text_proposal_history'} -PRODUCERS={'generation':'generation_history','grounded':'grounded_history', - 'caption':'caption_proposal_history','text_proposal':'text_proposal_history'} -RUNTIME_NAMES=('generation_jobs','grounded_jobs','caption_proposals','text_classification_proposals','workspace_runs') -_LEASE_TOKEN=object() -_ISSUED_STOPPED=weakref.WeakSet() -MAX_SOURCE_FILE=40*1024*1024 - - -def fail(message,code='invalid',status=400):raise WorkbenchError(message,code,status) -def closed(value,fields,label): - if type(value) is not dict or set(value)!=set(fields):fail('Invalid '+label+' fields.') -def digest(raw):return hashlib.sha256(raw).hexdigest() -def canonical(value):return _encode(value) -def sha(value): - if type(value) is not str or not SHA.fullmatch(value):fail('Invalid extraction digest.') -def identity(value): - if type(value) is not str or not UUID.fullmatch(value):fail('Invalid extraction identity.') -def leaf(value): - if type(value) is not str or not 1<=len(value)<=200 or value in ('.','..') or any(c in value for c in '/\\') or any(ord(c)<32 for c in value):fail('Choose one exact destination directory name.') - return value - -def parts(value): - if type(value) is not str or len(value)>512 or '\\' in value or any(ord(c)<32 for c in value):fail('Invalid source-relative path.') - result=value.split('/') - if not 1<=len(result)<=16 or any(p in ('','.','..') for p in result):fail('Source reference must remain inside its configured root.') - return result - - -def _fd_identity(fd): - value=os.fstat(fd) - return value.st_dev,value.st_ino - - -@contextmanager -def _file(root,relative,maximum): - path=parts(relative);parent=os.dup(root);descriptor=None - try: - for name in path[:-1]: - child=os.open(name,DIR_FLAGS,dir_fd=parent);os.close(parent);parent=child - descriptor=os.open(path[-1],FILE_FLAGS,dir_fd=parent) - before=os.fstat(descriptor) - if not stat.S_ISREG(before.st_mode) or before.st_nlink!=1 or before.st_size>maximum:fail('Source payload is unsafe or exceeds its owner bound.','unavailable',409) - yield descriptor,before - after=os.fstat(descriptor);current=os.stat(path[-1],dir_fd=parent,follow_symlinks=False) - key=lambda v:(v.st_dev,v.st_ino,v.st_mode,v.st_nlink,v.st_size,v.st_mtime_ns,v.st_ctime_ns) - if key(before)!=key(after) or key(after)!=key(current):fail('Source payload changed during capture.','stale_source',409) - except OSError:fail('Source payload is missing or unsafe.','unavailable',409) - finally: - if descriptor is not None:os.close(descriptor) - os.close(parent) - - -def _read(root,relative,maximum): - with _file(root,relative,maximum) as (fd,info): - chunks=[];remaining=maximum+1 - while remaining: - raw=os.read(fd,min(65536,remaining)) - if not raw:break - chunks.append(raw);remaining-=len(raw) - result=b''.join(chunks) - if len(result)!=info.st_size or len(result)>maximum:fail('Source payload changed or exceeds its owner bound.','unavailable',409) - return result - - -class ReadonlyCatalog: - """The exact schema proof, without Metadata construction or source writes.""" - _signature=Metadata._signature - validate_schema=Metadata.validate_schema - def __init__(self,dsn,schema,catalog_id,path,*,exclude_peers=False): - identity(catalog_id) - if schema!='catalog_'+catalog_id:fail('Only a current legacy catalog can be extracted.','unsupported',409) - self.dsn,self.schema,self.dataset_id,self.path=dsn,schema,catalog_id,Path(path) - self.schema_version=SCHEMA_VERSION;self.lock=threading.RLock() - self.connection=psycopg.connect(dsn,autocommit=True,row_factory=row_factory) - try: - self.connection.execute(sql.SQL('SET search_path TO {}').format(sql.Identifier(schema))) - self.connection.execute("SET statement_timeout='60000'") - self.connection.execute("SET lock_timeout='1000'") - if exclude_peers: - for key in [_key(schema),*(_key(schema+':worker:'+name) for name in RUNTIME_NAMES)]: - if not self.connection.execute('SELECT pg_try_advisory_lock(%s)',(key,)).fetchone()[0]: - fail('A peer acquired legacy catalog ownership after stop.','busy',409) - self.connection.execute('BEGIN ISOLATION LEVEL REPEATABLE READ READ ONLY') - self.validate_schema() - except BaseException:self.connection.close();raise - def execute(self,query,parameters=None): - # PostgreSQL READ ONLY is the enforcement boundary, including CTEs. - return self.connection.execute(query,parameters) - @property - def tables(self): - from metadata import tables_for_version - return tables_for_version(self.schema_version) - def close(self):self.connection.close() - - -class CapturedArtifacts: - """Private verified evidence custody; no preview file publication.""" - def __init__(self):self.payloads={};self.declarations={} - def publish_bytes(self,raw,declaration,*,maximum_bytes=None): - declaration=validate_declaration(declaration) - if type(raw) is not bytes or len(raw)!=declaration['bytes'] or digest(raw)!=declaration['sha256']:fail('Captured source bytes differ from their declaration.') - if maximum_bytes is not None and len(raw)>maximum_bytes:fail('Captured source exceeds its owner bound.','too_large',413) - self._add(declaration,raw);return copy.deepcopy(declaration) - def publish_fd(self,descriptor,declaration,*,maximum_bytes=None): - declaration=validate_declaration(declaration);info=os.fstat(descriptor) - if not stat.S_ISREG(info.st_mode) or info.st_size!=declaration['bytes'] or maximum_bytes is not None and info.st_size>maximum_bytes:fail('Captured source descriptor differs.') - hasher=hashlib.sha256();offset=0 - while offsetmaximum_bytes:fail('Captured source bytes are unavailable.','unavailable',409) - payload=self.payloads[key] - raw=payload if type(payload) is bytes else os.pread(payload,value['bytes'],0) - if len(raw)!=value['bytes'] or digest(raw)!=key:fail('Captured source changed.','stale_source',409) - return raw - def status(self,declaration): - value=validate_declaration(declaration);actual=self.declarations.get(value['sha256']);present=value['sha256'] in self.payloads - state='missing' if not present else 'verified' if actual==value else 'corrupt' - return dict(state=state,expected_sha256=value['sha256'],expected_bytes=value['bytes'],observed_sha256=actual['sha256'] if present else None,observed_bytes=actual['bytes'] if present else None) - inspect=status - @contextmanager - def open_verified(self,declaration,*,maximum_bytes=None): - value=validate_declaration(declaration);payload=self.payloads.get(value['sha256']) - if payload is None or self.declarations.get(value['sha256'])!=value:fail('Unique source payload is missing or differs.','unavailable',409) - if maximum_bytes is not None and value['bytes']>maximum_bytes:fail('Captured payload exceeds its owner bound.','too_large',413) - if type(payload) is bytes: - import tempfile - with tempfile.TemporaryFile() as temporary: - temporary.write(payload);temporary.flush();temporary.seek(0) - yield temporary.fileno() - else: - self.publish_fd(payload,value,maximum_bytes=maximum_bytes) - duplicate=os.dup(payload) - try:yield duplicate - finally:os.close(duplicate) - def close(self): - for value in self.payloads.values(): - if type(value) is int:os.close(value) - self.payloads.clear() - - -class SourceView: - def __init__(self,db,root_fd,root_path,roots,*,actor_id,captured_at=None): - self.db,self.root_fd,self.root_path=db,root_fd,Path(root_path) - self.roots=roots;self.actor_id=actor_id;self.captured_at=captured_at or timestamp() - self.artifacts=CapturedArtifacts();self._closed=False;self._payload_locations={};self._authorize=None - self.snapshot=dict(project_id=db.dataset_id,checkpoint='0'*64,records=[]) - self.fingerprint=None;self.backup_receipt=None;self.external_inventory=[];self._observed_roots={} - def require(self): - if self._authorize is not None:self._authorize() - if self._closed or self.db.connection.closed:fail('Source snapshot lease is closed.','unavailable',409) - current=os.open(self.root_path,DIR_FLAGS) - try: - if _fd_identity(current)!=_fd_identity(self.root_fd):fail('Source catalog root changed.','stale_source',409) - finally:os.close(current) - def read_catalog(self,relative,maximum_bytes=MAX_SOURCE_FILE): - self.require();return _read(self.root_fd,relative,maximum_bytes) - def read_root(self,alias,relative,maximum_bytes=MAX_SOURCE_FILE): - self.require();entry=self.roots.get(alias) - if entry is None:fail('An explicit source root binding is required.','unavailable',409) - raw=_read(entry[0],relative,maximum_bytes) - key=(alias,relative);observation=(len(raw),digest(raw)) - if key in self._observed_roots and self._observed_roots[key]!=observation:fail('External source bytes changed after capture.','stale_source',409) - self._observed_roots[key]=observation - fact=dict(root=alias,relative=relative,sha256=observation[1],bytes=observation[0]) - if fact not in self.external_inventory:self.external_inventory.append(fact) - return raw - def resolve_payload(self,sha256,size): - sha(sha256) - if sha256 in self.artifacts.declarations:return self.artifacts.read_blob(dict(sha256=sha256,bytes=size)) - location=self._payload_locations.get(sha256) - if location is None or location['bytes']!=size:fail('An explicit external payload inventory binding is required.','unavailable',409) - raw=self.read_root(location['root'],location['relative'],MAX_SOURCE_FILE) - if len(raw)!=size or digest(raw)!=sha256:fail('External source payload differs from its declaration.') - return raw - def read_bound_payload(self,sha256,*,maximum_bytes=MAX_SOURCE_FILE): - """Read exact operator-bound bytes; None means no explicit binding. - - Historical paths or root identities never create this capability. A - changed, oversized or unavailable bound file remains an error, even if - another working file exists at the original historical location. - """ - self.require();sha(sha256) - location=self._payload_locations.get(sha256) - if location is None:return None - if location['bytes']>maximum_bytes:fail('Bound original source exceeds its owner bound.','too_large',413) - return self.resolve_payload(sha256,location['bytes']) - @contextmanager - def payload_fd(self,sha256,size): - sha(sha256) - location=self._payload_locations.get(sha256) - if location is None or location['bytes']!=size:fail('An explicit payload descriptor binding is required.','unavailable',409) - with _file(self.roots[location['root']][0],location['relative'],size) as (fd,info): - declaration=dict(format='project_artifact_v1',sha256=sha256,bytes=size) - self.artifacts.publish_fd(fd,declaration,maximum_bytes=size) - yield fd - - def bind_payload(self,sha256,size,root,relative): - # Internal capability owner call, never inferred from a historical path. - self.require();sha(sha256) - if type(size) is not int or not 0<=size<=2**63-1 or root not in self.roots:fail('Invalid external payload binding.') - with _file(self.roots[root][0],relative,max(size,1)) as (fd,info): - if info.st_size!=size:fail('External payload binding differs.') - self.artifacts.publish_fd(fd,dict(format='project_artifact_v1',sha256=sha256,bytes=size),maximum_bytes=size) - self._observed_roots[(root,relative)]=(size,sha256) - self._payload_locations[sha256]=dict(root=root,relative=relative,bytes=size) - fact=dict(root=root,relative=relative,sha256=sha256,bytes=size) - if fact not in self.external_inventory:self.external_inventory.append(fact) - def close(self): - if self._closed:return - self._closed=True;self.artifacts.close();self.db.close();os.close(self.root_fd) - for fd,_ in self.roots.values():os.close(fd) - self.roots.clear() - def __enter__(self):self.require();return self - def __exit__(self,*exc):self.close() - - -class StoppedSourceLease(SourceView): - def __init__(self,*args,_token=None,**kwargs): - if _token is not _LEASE_TOKEN:fail('A stopped source must be issued by its current trusted owner.','forbidden',403) - super().__init__(*args,**kwargs) - def require(self): - super().require() - if self not in _ISSUED_STOPPED or self.backup_receipt is None:fail('Verified stopped backup is unavailable.','unavailable',409) - - -def preview_source(dataset): - """Read a currently opened source without constructing or stopping owners.""" - actor=dataset.access.require('inspect','project_transfer.preview') - root=os.open(dataset.path,DIR_FLAGS);roots={} - try: - for alias,(fd,value) in dataset.projects.roots.items():roots[alias]=(os.dup(fd),list(value)) - view=ReadonlyCatalog(dataset.db.dsn,dataset.db.schema,dataset.db.dataset_id,dataset.path) - source=SourceView(view,root,dataset.path,roots,actor_id=actor.actor_id) - source._authorize=lambda:dataset.access.require('inspect','project_transfer.preview') - return source - except BaseException: - os.close(root) - for fd,_ in roots.values():os.close(fd) - raise - - -def _snapshot(view): - from backup_metadata import read_catalog,read_sequences,summaries - tables=read_catalog(view.db);sequences=read_sequences(view.db) - return tables,sequences,digest(canonical(dict(tables=summaries(tables),sequences=sequences))) - - -def _verified_backup(source,parent_fd,directory): - from backup_metadata import tree_manifest,copy_tree,tree_modes,summaries - leaf(directory) - from project_fork import _inside - if _inside(parent_fd,source.root_fd):fail('Backup cannot overlap its source.','conflict',409) - stage='.tuldok-extraction-backup-'+uuid.uuid4().hex - os.mkdir(stage,0o700,dir_fd=parent_fd) - path=Path('/proc/self/fd')/str(parent_fd)/stage - tables,sequences,fingerprint=_snapshot(source) - before=tree_manifest(source.root_path) - copy_tree(source.root_path,path/'catalog',before,deduplicate=True) - metadata=dict(format_version=1,schema_version=source.db.schema_version,dataset_id=source.db.dataset_id,tables=tables,sequences=sequences) - from backup_metadata import write_json,file_hash - write_json(path/'metadata.json',metadata) - receipt=dict(format_version=1,kind='postgresql',schema_version=source.db.schema_version,dataset_id=source.db.dataset_id, - postgresql_server_version=source.db.connection.info.server_version,driver='psycopg '+psycopg.__version__, - restore_privileges='CONNECT and CREATE on a new PostgreSQL database; catalog schema must be absent', - metadata_sha256=file_hash(path/'metadata.json'),files=before,tables=summaries(tables),sequences=sequences) - write_json(path/'backup-receipt.json',receipt) - source.require() - if before!=tree_manifest(source.root_path) or before!=tree_manifest(path/'catalog') or tree_modes(source.root_path,before)!=tree_modes(path/'catalog',before):fail('Source changed while capturing its stopped backup.','stale_source',409) - directory_fd=os.open(stage,DIR_FLAGS,dir_fd=parent_fd) - try:os.fsync(directory_fd) - finally:os.close(directory_fd) - _rename_noreplace(parent_fd,stage,directory);os.fsync(parent_fd) - return receipt,fingerprint - - -def stop_source(dataset,*,backup_parent_fd,backup_directory,external_roots=None,controller_guard): - """Only the already running, explicitly gated owner may mint this lease.""" - from app import Dataset, _LegacyExtractionGuard - if not isinstance(dataset,Dataset) or type(controller_guard) is not _LegacyExtractionGuard or dataset._extraction_guard is not controller_guard: - fail('An exclusive current-controller stop guard is required.','forbidden',403) - controller_guard.require(dataset) - actor=dataset.access.require('admin','project_transfer.stop_source',owner_only=True) - leaf(backup_directory) - if not stat.S_ISDIR(os.fstat(backup_parent_fd).st_mode):fail('A backup parent capability is required.') - try:os.stat(backup_directory,dir_fd=backup_parent_fd,follow_symlinks=False) - except FileNotFoundError:pass - else:fail('Stopped backup destination already exists.','conflict',409) - if any(not dataset.db.runtime_owned(name) for name in RUNTIME_NAMES):fail('A peer owns a legacy runtime; stop its actual owner first.','busy',409) - if dataset.runs._blocked or dataset.runs._external_blocked:fail('Legacy worker cessation remains unknown.','unknown',409) - root=os.open(dataset.path,DIR_FLAGS);roots={};source=None - dsn,schema,catalog_id=dataset.db.dsn,dataset.db.schema,dataset.db.dataset_id - try: - for alias,(fd,value) in (external_roots if external_roots is not None else dataset.projects.roots).items(): - if type(alias) is not str or not ALIAS.fullmatch(alias) or list(_fd_identity(fd))!=list(value):fail('Invalid explicit external root capability.') - roots[alias]=(os.dup(fd),list(value)) - with dataset.image_requests.lock:pending=list(dataset.image_requests.active.items()) - for request_id,operation in pending:operation.cancel() - deadline=time.monotonic()+60 - for request_id,operation in pending: - if not operation.done.wait(max(0,deadline-time.monotonic())):fail('An owned image request did not drain.','unknown',409) - controller_guard.require(dataset) - # Existing owner close may change lifecycle observations. The preservation - # baseline is captured afterwards, never before this explicit stop. - dataset.close_for_project_extraction(deadline=deadline) - for owner in (dataset.generation_jobs,dataset.grounded,dataset.caption_proposals,dataset.text_classification_proposals): - worker=getattr(owner,'worker',None) - if worker is not None and worker.is_alive():fail('A legacy producer did not drain.','unknown',409) - if dataset.runs._blocked or dataset.runs._external_blocked:fail('Legacy process cessation is unknown.','unknown',409) - with dataset.image_requests.lock: - if dataset.image_requests.active:fail('An image request remains active.','unknown',409) - controller_guard.require(dataset) - db=ReadonlyCatalog(dsn,schema,catalog_id,dataset.path,exclude_peers=True) - # Base view permits backup verification before the stopped lease is minted. - source=SourceView(db,root,dataset.path,roots,actor_id=actor.actor_id) - import recipe_process - for row in db.execute('SELECT document FROM workspace_runs'): - run=json.loads(row[0]);custody=run.get('custody_identity') - if custody is None:continue - if run.get('state')=='completed': - raw=source.read_catalog('workspace-runs/'+run['id']+'/custody-receipt.json',16384) - receipt=recipe_process.validate_receipt(raw,custody) - else:receipt=dataset.runs._external_drain_receipt(run) - if receipt is None or not receipt['drained']:fail('An external custodian has no exact drained receipt.','unknown',409) - receipt,fingerprint=_verified_backup(source,backup_parent_fd,backup_directory) - source.backup_receipt=receipt;source.fingerprint=fingerprint;source.snapshot['checkpoint']=fingerprint - source.__class__=StoppedSourceLease - _ISSUED_STOPPED.add(source) - source.require() - return source - except BaseException: - if source is not None:source.close() - else: - os.close(root) - for fd,_ in roots.values():os.close(fd) - raise - - -def normalize_selection(selection): - closed(selection,{'project_snapshot','roots','decisions'},'extraction selection') - snapshot=selection['project_snapshot'];closed(snapshot,{'id','manifest_sha256'},'selected project snapshot') - identity(snapshot['id']);sha(snapshot['manifest_sha256']) - roots=selection['roots'];known=set(ROOT_FAMILIES)|{'producer_jobs','working_files'} - if type(roots) is not dict or set(roots)-known:fail('Unsupported extraction root family.') - normalized={} - for name in ROOT_FAMILIES: - values=roots.get(name,[]) - if type(values) is not list or len(values)>10000 or any(type(v) is not str for v in values) or len(set(values))!=len(values):fail('Extraction roots must be bounded unique identifiers.') - for value in values: - sha(value) if name in ('releases','model_materials','recipe_materials','runtime_materials') else identity(value) - normalized[name]=sorted(values) - jobs=roots.get('producer_jobs',[]) - if type(jobs) is not list or len(jobs)>10000:fail('Invalid producer selection.') - seen=set();normalized_jobs=[] - for value in jobs: - closed(value,{'kind','id'},'producer selection');identity(value['id']) - if value['kind'] not in PRODUCERS or (value['kind'],value['id']) in seen:fail('Unsupported or duplicate producer root.') - seen.add((value['kind'],value['id']));normalized_jobs.append(copy.deepcopy(value)) - normalized['producer_jobs']=sorted(normalized_jobs,key=lambda v:(v['kind'],v['id'])) - files=roots.get('working_files',[]) - if type(files) is not list or len(files)>1000:fail('Invalid working-file selection.') - from project_files import _path - seen=set();normalized_files=[] - for value in files: - closed(value,{'kind','path'},'working-file selection');_path(value['kind'],value['path']) - if (value['kind'],value['path']) in seen:fail('Duplicate working-file selection.') - seen.add((value['kind'],value['path']));normalized_files.append(copy.deepcopy(value)) - normalized['working_files']=sorted(normalized_files,key=lambda v:(v['kind'],v['path'])) - decisions=selection['decisions'] - if type(decisions) is not list or len(decisions)>10000:fail('Invalid ownership decisions.') - allowed=set(ROOT_FAMILIES.values())|NAMESPACED|{'project_artifact','project_file','trial_history','candidate_history'} - fixed=[];seen=set() - for value in decisions: - closed(value,{'family','id','include','reason'},'ownership decision') - if value['family'] not in allowed or type(value['id']) is not str or not 1<=len(value['id'])<=128 or type(value['include']) is not bool or type(value['reason']) is not str or not 1<=len(value['reason'])<=1000 or (value['family'],value['id']) in seen:fail('Invalid explicit ownership decision.') - seen.add((value['family'],value['id']));fixed.append(copy.deepcopy(value)) - return dict(project_snapshot=copy.deepcopy(snapshot),roots=normalized,decisions=sorted(fixed,key=lambda v:(v['family'],v['id']))) - - -def _seeds(selection,catalog_id): - selected={('project_snapshot',catalog_id+'.'+selection['project_snapshot']['manifest_sha256'])} - for root,family in ROOT_FAMILIES.items(): - for value in selection['roots'][root]:selected.add((family,catalog_id+'.'+value if family in NAMESPACED else value)) - for value in selection['roots']['producer_jobs']:selected.add((PRODUCERS[value['kind']],catalog_id+'.'+value['id'])) - from project_files import file_id - for value in selection['roots']['working_files']:selected.add(('project_file',file_id(catalog_id,value['kind'],value['path']))) - for value in selection['decisions']: - if value['include']:selected.add((value['family'],value['id'])) - return selected - - -def _capture(source,selection): - from project_extraction import capture_legacy - captured=capture_legacy(source,selection) - closed(captured,{'records','inventory','dependencies','blockers','working_files','warnings'},'legacy capture') - for field in captured: - if type(captured[field]) is not list:fail('Legacy capture fields must be finite lists.') - return captured - - -def _validate_candidate(records,project_id,artifacts): - from project_projection import ProjectProjection - from types import SimpleNamespace - ProjectProjection.validate_records(SimpleNamespace(project_id=project_id,artifacts=artifacts),records,project_id=project_id) - - -class ProjectTransfer: - def __init__(self,source): - if not isinstance(source,SourceView):fail('A pinned read-only source capability is required.','forbidden',403) - self.source=source;self._reports={};self.lock=threading.RLock() - - def extract(self,selection,expected_report_sha256,destination_parent_fd,directory,name,request_key,*,opened_store=None): - with self.lock:return _extract(self,selection,expected_report_sha256,destination_parent_fd,directory,name,request_key,opened_store=opened_store) - - def preview(self,selection): - with self.lock:return self._preview(selection) - - def _preview(self,selection): - source=self.source;source.require();selection=normalize_selection(selection) - if source.fingerprint is None: - _,_,source.fingerprint=_snapshot(source);source.snapshot['checkpoint']=source.fingerprint - captured=_capture(source,selection) - inventory={} - for item in captured['inventory']: - closed(item,{'family','id','revision'},'legacy inventory item') - key=item['family'],item['id'] - if key in inventory:fail('Legacy inventory repeats an identity.') - inventory[key]=item - required=_seeds(selection,source.db.dataset_id);direct=set(required);edges={} - for edge in captured['dependencies']: - closed(edge,{'source','target','reason'},'legacy dependency') - for field in ('source','target'):closed(edge[field],{'family','id'},'dependency locator') - edges.setdefault((edge['source']['family'],edge['source']['id']),[]).append((edge['target']['family'],edge['target']['id'])) - pending=list(required) - while pending: - for key in edges.get(pending.pop(),[]): - if key not in required:required.add(key);pending.append(key) - excluded={(v['family'],v['id']) for v in selection['decisions'] if not v['include']} - blockers=[copy.deepcopy(v) for v in captured['blockers'] if (v['family'],v['id']) in required] - for family,record_id in sorted(required-inventory.keys()):blockers.append(dict(family=family,id=record_id,code='missing_dependency',detail='Selected or required source fact is unavailable.')) - for family,record_id in sorted(required&excluded):blockers.append(dict(family=family,id=record_id,code='required_dependency_excluded',detail='Required closure cannot be excluded.')) - declared={(r['family'],r['id']):r for r in captured['records']} - records=[copy.deepcopy(declared[k]) for k in sorted(required) if k in declared] - artifact_report=[] - artifact_policies={} - for edge in captured['dependencies']: - target=(edge['target']['family'],edge['target']['id']) - parent=(edge['source']['family'],edge['source']['id']) - if parent in required and target[0]=='project_artifact': - policy='regenerable' if edge['reason'].startswith('regenerable:') else 'unique' - if artifact_policies.get(target[1])!='unique':artifact_policies[target[1]]=policy - for record in records: - if record['family']=='project_artifact': - state=source.artifacts.status(record['document'])['state'] - preservation=artifact_policies.get(record['id'],'unique') - artifact_report.append(dict(sha256=record['id'],bytes=record['document']['bytes'],preservation=preservation,state=state)) - if state!='verified' and preservation=='unique':blockers.append(dict(family='project_artifact',id=record['id'],code='missing_unique_payload',detail='Original required bytes cannot be regenerated during extraction.')) - file_observations=[] - from project_files import file_id - for value in captured['working_files']: - closed(value,{'kind','path','sha256','bytes','text'},'observed working file') - if ('project_file',file_id(source.db.dataset_id,value['kind'],value['path'])) in required:file_observations.append(copy.deepcopy(value)) - if not blockers: - try:_validate_candidate(records,source.db.dataset_id,source.artifacts) - except WorkbenchError as error:blockers.append(dict(family='closure',id=source.db.dataset_id,code=getattr(error,'code','invalid'),detail=str(error))) - if not isinstance(source,StoppedSourceLease):blockers.append(dict(family='source',id=source.db.dataset_id,code='cessation_proof_unavailable',detail='The current trusted owner must explicitly stop and capture this source.')) - report=dict(format='project_transfer_report_v1',source=dict(catalog_id=source.db.dataset_id,schema_version=source.db.schema_version, - catalog_signature=source.db._signature(),snapshot_sha256=source.fingerprint, - backup_receipt_sha256=digest(canonical(source.backup_receipt)) if source.backup_receipt is not None else None, - external_inventory_sha256=digest(canonical(sorted(source.external_inventory,key=lambda v:(v['root'],v['relative']))))), - selection=selection,included=[copy.deepcopy(inventory[k]) for k in sorted(required&inventory.keys())], - required=[dict(family=f,id=i) for f,i in sorted(required-direct)], - unassigned=[copy.deepcopy(inventory[k]) for k in sorted(inventory.keys()-required-excluded)], - excluded=[dict(family=f,id=i) for f,i in sorted(excluded)],blockers=blockers, - warnings=[copy.deepcopy(v) for v in captured['warnings'] if (v['family'],v['id']) in required], - artifacts=artifact_report,working_files=[{k:v[k] for k in ('kind','path','sha256','bytes')} for v in file_observations],can_extract=not blockers) - report_hash=digest(canonical(report));report['report_sha256']=report_hash - self._reports[report_hash]=dict(report=copy.deepcopy(report),records=records,working_files=file_observations) - source.require();return report - - -FAMILY='project_extraction' -FORMAT='project_extraction_v1' -SOURCE_FIELDS={'catalog_id','schema_version','catalog_signature','backup_receipt_sha256','external_inventory_sha256','snapshot_sha256'} - - -def decode_records(records): - from project_store import SUPPORTED_FORMATS - from project_files import file_id - indexed={(r['family'],r['id']):r for r in records} - counts={} - for r in records:counts[r['family']]=counts.get(r['family'],0)+1 - seen=set();result=[] - for envelope in records: - if envelope.get('family')!=FAMILY:continue - closed(envelope,{'family','id','document'},'extraction envelope');doc=envelope['document'] - closed(doc,{'format','source','selection','report_sha256','request_key','input_sha256','destination_project_id','working_files','counts','artifacts'},'extraction manifest') - if doc['format']!=FORMAT:fail('Unsupported extraction manifest format.','unsupported',409) - identity(envelope['id']);identity(doc['destination_project_id']) - if envelope['id']!=doc['destination_project_id'] or envelope['id'] in seen:fail('Duplicate or mismatched extraction identity.') - seen.add(envelope['id']);source=doc['source'];closed(source,SOURCE_FIELDS,'extraction source') - identity(source['catalog_id']) - if source['catalog_id']==doc['destination_project_id'] or type(source['schema_version']) is not int or source['schema_version']!=SCHEMA_VERSION:fail('Extraction source namespace or schema differs.') - for field in SOURCE_FIELDS-{'catalog_id','schema_version'}:sha(source[field]) - sha(doc['report_sha256']);sha(doc['input_sha256']) - overlay=indexed.get(('project_fork',doc['destination_project_id'])) - if overlay is None:fail('Extraction lacks its independent identity overlay.') - overlay=overlay['document'] - if overlay['source']!=dict(project_id=source['catalog_id'],checkpoint=source['snapshot_sha256']) or overlay['request_key']!=doc['request_key'] or overlay['artifacts']!=doc['artifacts']:fail('Extraction manifest differs from its retained identity transition.') - if digest(canonical(_input(source,doc['selection'],doc['report_sha256'],overlay['directory'],overlay['name'],doc['request_key'])))!=doc['input_sha256']:fail('Extraction input digest differs from its exact publication request.') - registered=indexed.get(('project_snapshot',source['catalog_id']+'.'+doc['selection']['project_snapshot']['manifest_sha256'])) - if registered is None or registered['document']['value']['id']!=doc['selection']['project_snapshot']['id']:fail('Extraction lacks its exact selected registered snapshot.') - if normalize_selection(doc['selection'])!=doc['selection']:fail('Extraction selection is not normalized.') - from project_store import REQUEST_KEY - if type(doc['request_key']) is not str or not REQUEST_KEY.fullmatch(doc['request_key']):fail('Invalid extraction request key.') - if type(doc['counts']) is not dict or any(f not in SUPPORTED_FORMATS or type(n) is not int or n<1 or counts.get(f,0)200:fail('Invalid extraction request identity.') - report=self.preview(selection) - if report['report_sha256']!=expected_report_sha256:fail('The extraction report changed; review the exact source closure again.','stale_source',409) - if not report['can_extract']: - error=WorkbenchError('Selected legacy project has unresolved extraction blockers.','extraction_blocked',409);error.report=report;raise error - cache=self._reports[expected_report_sha256];records=copy.deepcopy(cache['records']) - _assert_unchanged(source) - source_ref=report['source'];request_digest=digest(canonical(_input(source_ref,selection,expected_report_sha256,directory,name,request_key))) - from project_fork import (_inside,ARCHIVE_FAMILIES,_digest as fork_digest,_input as fork_input) - if _inside(destination_parent_fd,source.root_fd):fail('Extraction destination cannot overlap its source.','conflict',409) - root_path=Path(os.readlink('/proc/self/fd/'+str(destination_parent_fd))) - try:existing=os.stat(directory,dir_fd=destination_parent_fd,follow_symlinks=False) - except FileNotFoundError:existing=None - def replay(opened): - snapshot=opened.reconcile(request_key,request_digest) - if snapshot is None:fail('Extraction destination belongs to another request.','conflict',409) - manifest=next((r['document'] for r in snapshot['records'] if r['family']==FAMILY and r['id']==snapshot['project_id']),None) - if manifest is None or manifest['input_sha256']!=request_digest:fail('Extraction receipt is unavailable or differs.') - with ProjectArtifacts(opened) as current_artifacts: - _validate_candidate(snapshot['records'],snapshot['project_id'],current_artifacts) - verification=_cold_verify(opened,source);_assert_unchanged(source) - return _receipt(snapshot,manifest,verification,replayed=True) - if opened_store is not None: - # Trusted controller-only capability. Its caller pins workspace, - # authority, selected session and SQL ownership through this replay. - from project_working_store import WorkingProjectStore - if not isinstance(opened_store,(ProjectStore,WorkingProjectStore)) or existing is None: - fail('Current selected destination is unavailable.','stale',409) - with opened_store.root_directory() as owned_fd: - try:target_fd=os.open(directory,DIR_FLAGS,dir_fd=destination_parent_fd) - except OSError:fail('Selected destination binding changed.','stale',409) - try: - if _fd_identity(target_fd)!=_fd_identity(owned_fd):fail('Selected store differs from the extraction destination.','conflict',409) - finally:os.close(target_fd) - return replay(opened_store) - if existing is not None: - with ProjectStore.open_at(destination_parent_fd,directory,root_path=root_path) as opened: - return replay(opened) - stage_name='.tuldok-extraction-'+uuid.uuid4().hex - store=None;artifacts=None;committed=None;published=False;stage_identity=None - try: - store=ProjectStore.create_at(destination_parent_fd,stage_name,name,'extraction-stage.'+digest(request_key.encode())[:32],request_digest,root_path=root_path) - with store.root_directory() as owned_fd:stage_identity=_fd_identity(owned_fd) - destination=store.summary()['project_id'];created_at=timestamp() - from project_data_fork import fork_records as fork_data - from project_material_fork import fork_records as fork_material - original=copy.deepcopy(records);mappings=[] - allocator=lambda *args:uuid.uuid4().hex - for builder in (fork_data,fork_material): - made=builder(original,source.db.dataset_id,source.fingerprint,destination,id_factory=allocator,created_at=created_at) - records.extend(made['records']);mappings.extend(made['mapping']) - working=[] - from project_files import file_id,materialize_captured - for observed in cache['working_files']: - file_identity=file_id(destination,observed['kind'],observed['path']) - version=dict(revision=1,sha256=observed['sha256'],bytes=observed['bytes'],text=observed['text'],adopted_at=created_at,actor_id=source.actor_id) - records.append(dict(family='project_file',id=file_identity,document=dict(format='project_file_v1',project_id=destination,kind=observed['kind'],path=observed['path'],current=copy.deepcopy(version),history=[version],origin=None))) - working.append(dict(kind=observed['kind'],path=observed['path'],sha256=observed['sha256'],bytes=observed['bytes'],source_catalog_id=source.db.dataset_id,source_snapshot_sha256=source.fingerprint,destination_id=file_identity,adopted_at=created_at,actor_id=source.actor_id)) - declarations={r['id']:r['document'] for r in records if r['family']=='project_artifact'} - copied=sorted(v['sha256'] for v in report['artifacts'] if v['state']=='verified') - missing_regenerable=sorted(v['sha256'] for v in report['artifacts'] if v['state']!='verified' and v['preservation']=='regenerable') - fork_source=dict(project_id=source.db.dataset_id,checkpoint=source.fingerprint) - overlay=dict(format='project_fork_v1',source=fork_source,destination_project_id=destination, - request_key=request_key,request_sha256=fork_digest(fork_input(fork_source,directory,name,request_key)),directory=directory,name=name, - mapping=sorted(mappings,key=lambda m:(m['family'],m['source_id'],m['source_revision'] or 0,m['destination_id'])), - archived=sorted([dict(family=r['family'],id=r['id']) for r in original if r['family'] in ARCHIVE_FAMILIES],key=lambda v:(v['family'],v['id'])), - artifacts=dict(copied=copied,missing_regenerable=missing_regenerable)) - records.append(dict(family='project_fork',id=destination,document=overlay)) - counts={FAMILY:1} - for r in records:counts[r['family']]=counts.get(r['family'],0)+1 - manifest=dict(format=FORMAT,source=copy.deepcopy(source_ref),selection=selection,report_sha256=expected_report_sha256,request_key=request_key,input_sha256=request_digest,destination_project_id=destination,working_files=working,counts=counts,artifacts=dict(copied=copied,missing_regenerable=missing_regenerable)) - records.append(dict(family=FAMILY,id=destination,document=manifest)) - artifacts=ProjectArtifacts(store) - for value in declarations.values(): - if value['sha256'] in missing_regenerable:continue - with source.artifacts.open_verified(value,maximum_bytes=value['bytes']) as fd:artifacts.publish_fd(fd,value,maximum_bytes=value['bytes']) - with store.root_directory() as fd:materialize_captured(records,destination,fd) - _validate_candidate(records,destination,artifacts) - committed=store.commit(records,store.summary()['checkpoint'],request_key,request_digest) - verification=_cold_verify(store,source) - store.save(committed['checkpoint']);_assert_unchanged(source) - _rename_noreplace(destination_parent_fd,stage_name,directory);published=True;os.fsync(destination_parent_fd) - _assert_unchanged(source) - return _receipt(committed,manifest,verification) - except BaseException as error: - if not published and store is not None and committed is not None: - try: - final=os.stat(directory,dir_fd=destination_parent_fd,follow_symlinks=False) - published=(final.st_dev,final.st_ino)==stage_identity - except FileNotFoundError:pass - except OSError: - failure=WorkbenchError('Extraction publication outcome cannot be inspected.','unknown',503) - failure.staging_directory=stage_name - raise failure from error - if published: - failure=WorkbenchError('Extraction was published; acknowledgement requires reconciliation.','unknown',503) - failure.receipt=dict(committed=True,selected=False,project_id=committed['project_id'],checkpoint=committed['checkpoint'],request_key=request_key,directory=directory) - raise failure from error - error.staging_directory=stage_name - raise - finally: - if artifacts is not None:artifacts.close() - if store is not None:store.close() diff --git a/project_transfer_controller.py b/project_transfer_controller.py deleted file mode 100644 index 3ece224e..00000000 --- a/project_transfer_controller.py +++ /dev/null @@ -1,309 +0,0 @@ -"""Explicit process-local legacy extraction and independent workspace selection. - -The live Dataset is supplied by its existing controller. Stopping never imports -its credentials into the separate control host. Only that Dataset can issue a -StoppedSourceLease; requests carry a controller binding and report hashes, never -serialized cessation evidence or filesystem descriptors. -""" -import copy -from contextlib import ExitStack -import hashlib -import os -from pathlib import Path -import re -import threading -import uuid - -from project_store import _open_directory_path, _verify_origin, REQUEST_KEY -from project_transfer import ProjectTransfer, preview_source, normalize_selection, canonical, leaf, sha -from project_fork import _inside -from workbench import WorkbenchError - -SECTIONS = frozenset(('included', 'required', 'unassigned', 'excluded', 'blockers', 'warnings', 'artifacts', 'working_files')) -OPERATIONS = frozenset('project_transfer.' + name for name in ('status', 'preview', 'report_page', 'stop', 'extract')) -MAX_RESPONSE = 1024 * 1024 - - -def fail(message, code='invalid', status=400): - raise WorkbenchError(message, code, status) - - -def _identity(descriptor): - value = os.fstat(descriptor) - return value.st_dev, value.st_ino - - -def _bounded(value): - if len(canonical(value)) > MAX_RESPONSE: - fail('Extraction controller response exceeds its bounded interface.', 'too_large', 413) - return value - - -def _receipt_summary(value): - if value.get('format') != 'project_extraction_receipt_v1': - fields = ('committed', 'selected', 'project_id', 'checkpoint', 'request_key', 'directory') - return {key: copy.deepcopy(value[key]) for key in fields if key in value} - return dict(format='project_transfer_receipt_v1', committed=value['committed'], - project_id=value['project_id'], checkpoint=value['checkpoint'], request_key=value['request_key'], - input_sha256=value['input_sha256'], report_sha256=value['report_sha256'], source=copy.deepcopy(value['source']), - artifacts=dict(copied_count=len(value['artifacts']['copied']), missing_regenerable_count=len(value['artifacts']['missing_regenerable'])), - verification=copy.deepcopy(value['verification']), replayed=value['replayed']) - - -class ProjectTransferController: - def __init__(self, dataset, control_workspace, roots=None): - from app import Dataset - from project_workspace import ProjectWorkspace - if not isinstance(dataset, Dataset) or not isinstance(control_workspace, ProjectWorkspace): - fail('Extraction requires an existing legacy controller and a separate control workspace.', 'forbidden', 403) - if dataset.db.dataset_id == control_workspace.db.dataset_id or dataset.db is control_workspace.db: - fail('The control host must have independent current local authority.', 'forbidden', 403) - self.dataset, self.workspace = dataset, control_workspace - self._lock = threading.RLock() - self._binding = uuid.uuid4().hex - self._phase = 'source_live' - self._closed = False - self._roots = {} - self._source = self._transfer = self._report = self._selection = None - self._backup = self._destination = self._last_receipt = self._failure = None - configured = roots if roots is not None else {alias: value[0] for alias, value in control_workspace._roots.items()} - try: - if type(configured) is not dict or not 1 <= len(configured) <= 100: - fail('Configure one to 100 extraction publication roots.') - for alias, path in configured.items(): - if type(alias) is not str or not re.fullmatch('[A-Za-z0-9][A-Za-z0-9_.-]{0,63}', alias): - fail('Invalid extraction publication root alias.') - absolute, descriptor = _open_directory_path(path) - self._roots[alias] = (Path(absolute), descriptor) - # Publication parents may contain the source as a sibling, but may - # never be inside it. Nonexistent leaf targets are checked at Stop. - _, source_fd = _open_directory_path(dataset.path) - try: - if any(_inside(descriptor, source_fd) for _, descriptor in self._roots.values()): - fail('Extraction publication roots cannot be inside the source catalog.', 'conflict', 409) - finally: - os.close(source_fd) - except BaseException: - self.close() - raise - - @property - def control_workspace(self): - return self.workspace - - @property - def phase(self): - """Trusted root dispatch uses this only to choose request authentication.""" - return self._phase - - @property - def access(self): - return self.dataset.access if self._phase == 'source_live' else self.workspace.access - - def _authorize(self, action): - if self._closed: - fail('Extraction controller is closed.', 'unavailable', 503) - self.access.require('admin', 'project_transfer.' + action, owner_only=True) - - def _bound(self, binding): - if type(binding) is not str or binding != self._binding: - fail('Extraction controller changed. Refresh its process binding.', 'stale', 409) - - def _root(self, alias): - if type(alias) is not str or alias not in self._roots: - fail('Choose a configured extraction publication root.') - path, descriptor = self._roots[alias] - _verify_origin(descriptor, path) - return descriptor - - def _target(self, root, directory, *, may_exist=False, selectable=False): - leaf(directory) - descriptor = self._root(root) - if selectable: - configured = self.workspace._root(root, directory) - if _identity(configured[1]) != _identity(descriptor): - fail('The destination root must also be configured in the control workspace.', 'conflict', 409) - try: - os.stat(directory, dir_fd=descriptor, follow_symlinks=False) - except FileNotFoundError: - pass - else: - if not may_exist: - fail('Extraction publication destination already exists.', 'conflict', 409) - return descriptor - - def _summary(self): - if self._report is None: - return None - return dict(report_sha256=self._report['report_sha256'], - selection_sha256=hashlib.sha256(canonical(self._selection)).hexdigest(), - source=copy.deepcopy(self._report['source']), can_extract=self._report['can_extract'], - counts={section: len(self._report[section]) for section in sorted(SECTIONS)}) - - def _state(self): - actions = ['status'] - if self._phase in ('source_live', 'source_stopped'): - actions += ['preview', 'report_page'] - if self._phase == 'source_live' and self._report is not None: - actions.append('stop') - if self._phase == 'source_stopped' and self._report is not None: - actions.append('extract') - return _bounded(dict(format='project_transfer_state_v1', binding=self._binding, - phase=self._phase, source_catalog_id=self.dataset.db.dataset_id, - control_catalog_id=self.workspace.db.dataset_id, roots=sorted(self._roots), - available_actions=actions, report=self._summary(), backup=copy.deepcopy(self._backup), - destination=copy.deepcopy(self._destination), failure=copy.deepcopy(self._failure), - last_receipt=copy.deepcopy(self._last_receipt))) - - def status(self): - with self._lock: - self._authorize('status') - return self._state() - - def preview(self, binding, selection): - with self._lock: - self._authorize('preview');self._bound(binding) - if self._phase not in ('source_live', 'source_stopped'): - fail('The original controller remains fenced after an unsuccessful stop.', 'source_fenced', 409) - normalized = normalize_selection(selection) - if len(canonical(normalized)) > MAX_RESPONSE: - fail('Extraction selection exceeds the request bound.', 'too_large', 413) - if self._phase == 'source_live': - if self._source is not None: - self._source.close() - self._source = self._transfer = self._report = self._selection = None - self._source = preview_source(self.dataset) - # Retain only the reviewed report, rather than accumulating a - # stopped transfer's full report cache across selection changes. - self._selection = self._report = None - self._transfer = ProjectTransfer(self._source) - report = self._transfer.preview(normalized) - self._selection, self._report = normalized, report - self._failure = None - return self._state() - - def report_page(self, binding, report_sha256, section, offset=0, limit=40): - with self._lock: - self._authorize('report_page');self._bound(binding);sha(report_sha256) - if self._report is None or report_sha256 != self._report['report_sha256']: - fail('The extraction report changed. Review the current report.', 'stale', 409) - if type(section) is not str or section not in SECTIONS or type(offset) is not int or not 0 <= offset <= 1000000 or type(limit) is not int or not 1 <= limit <= 40: - fail('Choose a known report section and bounded page.') - values = self._report[section] - return _bounded(dict(format='project_transfer_report_page_v1', binding=self._binding, - report_sha256=report_sha256, section=section, items=copy.deepcopy(values[offset:offset + limit]), - offset=offset, limit=limit, total=len(values))) - - def stop(self, binding, report_sha256, backup_root, backup_directory, destination_root, directory): - with self._lock: - self._authorize('stop');self._bound(binding);sha(report_sha256) - if self._phase != 'source_live' or self._report is None or self._report['report_sha256'] != report_sha256: - fail('Review this live source before its explicit stop.', 'stale', 409) - backup_fd = self._target(backup_root, backup_directory) - destination_fd = self._target(destination_root, directory, selectable=True) - if _identity(backup_fd) == _identity(destination_fd) and backup_directory == directory: - fail('Stopped backup and extracted project require different destinations.', 'conflict', 409) - if self._source is not None: - self._source.close();self._source = self._transfer = None - # After any stop attempt, source authentication may be closed and - # ordinary legacy routes remain fenced. No DTO can mint a lease. - self._phase = 'source_fenced';self._binding = uuid.uuid4().hex - self._report = None - try: - source = self.dataset.stop_for_project_extraction(backup_fd, backup_directory) - except BaseException as error: - # Native authorization can fail before it installs the source - # request fence. Do not claim a stopped/fenced source or switch - # authentication in that no-effect case. - if not self.dataset._extraction_stopping: - self._phase = 'source_live' - self._failure = dict(action='stop', code=getattr(error, 'code', 'unknown'), detail=str(error)[:1000]) - raise - self._source, self._transfer = source, ProjectTransfer(source) - self._phase = 'source_stopped' - self._backup = dict(root=backup_root, directory=backup_directory, - receipt_sha256=hashlib.sha256(canonical(source.backup_receipt)).hexdigest()) - self._destination = dict(root=destination_root, directory=directory) - self._failure = None - return self._state() - - def extract(self, binding, report_sha256, destination_root, directory, name, request_key): - with self._lock: - self._authorize('extract');self._bound(binding);sha(report_sha256) - if self._phase != 'source_stopped' or self._transfer is None: - fail('A trusted stopped source is required before extraction.', 'source_fenced', 409) - if self._report is None or report_sha256 != self._report['report_sha256']: - fail('Review the exact stopped-source report before extraction.', 'stale', 409) - if type(name) is not str or not name.strip() or len(name) > 200 or type(request_key) is not str or not REQUEST_KEY.fullmatch(request_key): - fail('Choose an extraction name and exact request key.') - destination_fd = self._target(destination_root, directory, may_exist=True, selectable=True) - if self._backup is not None and _identity(destination_fd) == _identity(self._root(self._backup['root'])) and directory == self._backup['directory']: - fail('Extraction cannot replace its stopped backup.', 'conflict', 409) - # Pin selection before authority, matching Workspace's lock order. - # An already selected destination owns its Store writer lock; only - # its actual pinned Store can reconcile that exact destination. - try: - with self.workspace._mutex, self.workspace.access.lock, ExitStack() as guards: - self._authorize('extract') - opened = None - if self.workspace._selection == (destination_root, directory) and self.workspace._store is not None: - projection = self.workspace._projection - if projection is None or self.workspace._recovery is not None: - fail('Recover the selected workspace before reconciling extraction.', 'projection_unavailable', 503) - guards.enter_context(projection.session.lock) - guards.enter_context(projection.db.lock) - projection.session.check_current() - opened = self.workspace._store - receipt = self._transfer.extract(self._selection, report_sha256, destination_fd, directory, name, request_key, opened_store=opened) - except BaseException as error: - self._failure = dict(action='extract', code=getattr(error, 'code', 'unknown'), detail=str(error)[:1000]) - if getattr(error, 'receipt', None) is not None: - self._last_receipt = _receipt_summary(error.receipt) - if getattr(error, 'staging_directory', None) is not None: - self._failure['staging_directory'] = error.staging_directory - raise - self._last_receipt = _receipt_summary(receipt) - self._destination = dict(root=destination_root, directory=directory) - self._failure = None - selected, state, selection_error = False, None, None - try: - state = self.workspace.dispatch('project_files.status', {}) - arguments = dict(binding=state['binding'], expected_checkpoint=state['project']['checkpoint'] if state['project'] else None, - root=destination_root, directory=directory, request_key='extract-open.' + hashlib.sha256(request_key.encode()).hexdigest()[:32]) - state = self.workspace.dispatch('project_files.open', arguments) - if state['project'] is None or state['project']['project_id'] != receipt['project_id']: - fail('Workspace selected a different project.', 'project_selection_unavailable', 503) - selected = True - except BaseException as error: - selection_error = dict(code=getattr(error, 'code', 'unknown'), detail=str(error)[:1000]) - return _bounded(dict(format='project_transfer_extraction_result_v1', binding=self._binding, - receipt=_receipt_summary(receipt), selection=dict(selected=selected, state=state, error=selection_error))) - - def dispatch(self, name, arguments): - """The root transport admits only these five named, closed methods.""" - fields = { - 'project_transfer.status': set(), - 'project_transfer.preview': {'binding', 'selection'}, - 'project_transfer.report_page': {'binding', 'report_sha256', 'section', 'offset', 'limit'}, - 'project_transfer.stop': {'binding', 'report_sha256', 'backup_root', 'backup_directory', 'destination_root', 'directory'}, - 'project_transfer.extract': {'binding', 'report_sha256', 'destination_root', 'directory', 'name', 'request_key'}} - if type(name) is not str or name not in OPERATIONS or type(arguments) is not dict or set(arguments) - fields[name]: - fail('Unsupported extraction controller action.', 'unsupported', 409) - required = fields[name] - ({'offset', 'limit'} if name == 'project_transfer.report_page' else set()) - if not required <= set(arguments): - fail('Missing extraction controller arguments.') - if name == 'project_transfer.status':return self.status() - if name == 'project_transfer.preview':return self.preview(arguments['binding'], arguments['selection']) - if name == 'project_transfer.report_page':return self.report_page(arguments['binding'], arguments['report_sha256'], arguments['section'], arguments.get('offset', 0), arguments.get('limit', 40)) - if name == 'project_transfer.stop':return self.stop(arguments['binding'], arguments['report_sha256'], arguments['backup_root'], arguments['backup_directory'], arguments['destination_root'], arguments['directory']) - return self.extract(arguments['binding'], arguments['report_sha256'], arguments['destination_root'], arguments['directory'], arguments['name'], arguments['request_key']) - - def close(self): - with self._lock: - if self._closed:return - self._closed = True - try: - if self._source is not None:self._source.close() - finally: - for _, descriptor in self._roots.values():os.close(descriptor) - self._roots.clear() diff --git a/project_validation_cache.py b/project_validation_cache.py deleted file mode 100644 index 4d06760e..00000000 --- a/project_validation_cache.py +++ /dev/null @@ -1,155 +0,0 @@ -"""Remember complete domain validation of exact project checkpoints. - -A project checkpoint digest covers its manifest, which names every canonical -record revision by length and SHA256. Records are verified against those -digests before use, so (project ID, checkpoint) identifies the exact record set. -Complete cross-domain validation of that set is a pure function of those -records and the validating source code, so an earlier success can be reused -when both are identical. - -Markers live only in the private local workspace control directory; a portable -project folder never carries validation authority. The validator fingerprint -covers every Tuldok Python module and extension schema plus the optional -validator package versions, so any code or dependency change revalidates. -""" -import hashlib -import importlib.metadata -import json -import os -from pathlib import Path -import re -import sys -import threading -import uuid - -FORMAT = 'project_validation_marker_v1' -_HEX32 = re.compile(r'^[a-f0-9]{32}$') -_HEX64 = re.compile(r'^[a-f0-9]{64}$') -_SOURCE = Path(__file__).resolve().parent -_fingerprint = None -_fingerprint_lock = threading.Lock() - - -def _package_version(name): - try: - return importlib.metadata.version(name) - except importlib.metadata.PackageNotFoundError: - return None - - -def validator_fingerprint(): - """SHA256 over validating source bytes, schemas and optional validators.""" - global _fingerprint - with _fingerprint_lock: - if _fingerprint is None: - digest = hashlib.sha256(b'tuldok-validator-fingerprint-v1\0') - paths = sorted(path for path in _SOURCE.glob('*.py')) - schemas = _SOURCE / 'extension_schemas' - if schemas.is_dir(): - paths += sorted(path for path in schemas.rglob('*') if path.is_file()) - for path in paths: - digest.update(str(path.relative_to(_SOURCE)).encode('utf-8') + b'\0') - digest.update(hashlib.sha256(path.read_bytes()).digest()) - environment = dict(python=sys.version, jsonschema=_package_version('jsonschema'), - referencing=_package_version('referencing')) - digest.update(json.dumps(environment, sort_keys=True).encode('utf-8')) - _fingerprint = digest.hexdigest() - return _fingerprint - - -class ProjectValidationCache: - """Private per-workspace markers of fully validated project checkpoints.""" - def __init__(self, control_path, *, fingerprint=None): - self.path = Path(control_path) / '.project-validation' - self.fingerprint = fingerprint or validator_fingerprint() - - def _marker(self, project_id, checkpoint): - if (type(project_id) is not str or not _HEX32.fullmatch(project_id) - or type(checkpoint) is not str or not _HEX64.fullmatch(checkpoint)): - raise ValueError('Invalid project validation identity.') - name = hashlib.sha256(f'{project_id}:{checkpoint}:{self.fingerprint}'.encode()).hexdigest() - return self.path / f'{name}.json', dict(format=FORMAT, project_id=project_id, - checkpoint=checkpoint, fingerprint=self.fingerprint) - - def known(self, project_id, checkpoint): - path, expected = self._marker(project_id, checkpoint) - try: - with open(path, 'rb') as stream: - return json.loads(stream.read(4096)) == expected - except (OSError, ValueError): - return False - - def remember(self, project_id, checkpoint): - """Best effort: a missing marker only means the next Open revalidates.""" - path, marker = self._marker(project_id, checkpoint) - try: - self.path.mkdir(mode=0o700, exist_ok=True) - temporary = self.path / f'.{uuid.uuid4().hex}.tmp' - descriptor = os.open(temporary, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o600) - try: - os.write(descriptor, json.dumps(marker, sort_keys=True).encode('utf-8')) - os.fsync(descriptor) - finally: - os.close(descriptor) - os.replace(temporary, path) - except OSError: - pass - - -class CanonicalDigestCache: - """Private set of record digests whose bytes were proven canonical JSON. - - Canonicality is a property of the bytes alone, and record files are named - by their SHA256, so a proof for one digest holds for every project that - contains those exact bytes. The set is versioned by the canonical codec's - own source, so any change to the encoding rules starts a fresh set. - """ - def __init__(self, control_path): - import inspect - import project_store - codec = ''.join(inspect.getsource(function) for function in ( - project_store._json_value, project_store._encode, project_store._pairs, project_store._decode)) - version = hashlib.sha256((codec + json.__version__).encode('utf-8')).hexdigest()[:32] - self.path = Path(control_path) / '.canonical-digests' / f'{version}.bin' - self._known = None - self._lock = threading.Lock() - - def _load(self): - if self._known is None: - known = set() - try: - with open(self.path, 'rb') as stream: - raw = stream.read() - if len(raw) % 32 == 0: - known = {raw[index:index + 32] for index in range(0, len(raw), 32)} - except OSError: - pass - self._known = known - return self._known - - def __contains__(self, digest): - with self._lock: - return bytes.fromhex(digest) in self._load() - - def add_many(self, digests): - """Best effort: a lost update only means those records are re-proven.""" - with self._lock: - known = self._load() - fresh = {bytes.fromhex(digest) for digest in digests} - known - if not fresh: - return - known |= fresh - try: - self.path.parent.mkdir(mode=0o700, parents=True, exist_ok=True) - temporary = self.path.parent / f'.{uuid.uuid4().hex}.tmp' - descriptor = os.open(temporary, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o600) - try: - remaining = memoryview(b''.join(sorted(known))) - while remaining: - remaining = remaining[os.write(descriptor, remaining):] - os.fsync(descriptor) - finally: - os.close(descriptor) - os.replace(temporary, self.path) - except OSError: - pass diff --git a/project_validation_delta.py b/project_validation_delta.py deleted file mode 100644 index d63814c5..00000000 --- a/project_validation_delta.py +++ /dev/null @@ -1,119 +0,0 @@ -"""Edit-scoped validation: re-check only what a mutation can affect. - -A mutation's candidate is the previous, completely validated checkpoint plus -changed/added records (no deletions) and its new operation receipt. Each -validation component of validate_project_records is a pure function of the -documents and identities of a known set of record families (see the audit in -docs/plans/database-working-store.md, stage 4). A component whose input -families contain no changed record has the same outcome as for the previous -checkpoint, so it is skipped. Old operation receipts are re-checked only when -records they bind to changed or a new receipt shares their key space. - -Anything not classified here is always validated. TULDOK_VALIDATION_CROSSCHECK=1 -additionally runs complete validation and requires the same outcome. -""" -import contextvars -from contextlib import contextmanager -from dataclasses import dataclass - -from project_data import FAMILIES as _DATA -from project_history import FAMILY_FORMATS as _HISTORY -from project_material import FAMILIES as _MATERIAL -from project_producers import FAMILIES as _PRODUCERS - -DATA = frozenset(_DATA) -HISTORY = frozenset(_HISTORY) -MATERIAL = frozenset(_MATERIAL) -PRODUCERS = frozenset(_PRODUCERS) - -# Families whose documents or identities each component reads. -COMPONENTS = { - 'data': DATA | {'workbench_text', 'project_artifact', 'project_fork'} | PRODUCERS, - 'fork': frozenset({'project_fork'}), - 'composition': frozenset({'project_composition', 'project_fork', 'run_observation'}), - 'extraction': frozenset({'project_extraction', 'project_fork', 'project_snapshot', 'project_file', 'project_artifact'}), - 'files': frozenset({'project_file', 'project_fork'}), - 'native': frozenset({'native_execution_history', 'project_artifact', 'run_history'}), - 'material': MATERIAL | {'project_fork', 'project_artifact'}, - 'producers': PRODUCERS | {'project_artifact', 'workbench_record', 'workbench_text'}, - 'history': HISTORY | MATERIAL | {'project_artifact', 'dataset_exposure', 'pipeline_graph'}, - 'measurements': frozenset({'measurement_source', 'project_artifact', 'project_snapshot'}), - 'sources': frozenset({'project_snapshot'}), -} - -# Operation-receipt prefixes -> families their result binds to. A prefix -# mapped to an empty set binds only immutable or append-only facts. -RECEIPT_BINDINGS = { - 'data.': DATA | {'workbench_text'}, - 'models.': frozenset(), 'graphs.': frozenset(), 'recipes.': frozenset(), - 'studies.': HISTORY | {'pipeline_graph', 'project_artifact'}, - 'history.disclose': HISTORY | {'pipeline_graph', 'project_artifact'}, - 'source.': frozenset(), - 'measurements.': frozenset({'measurement_source'}), - 'runs.': frozenset({'run_history'}), - 'producers.': frozenset(), - 'files.': frozenset(), - 'study_execution.': HISTORY | MATERIAL, - 'runtime.': frozenset({'runtime_material', 'project_artifact'}), - 'native_preparation.': MATERIAL | {'pipeline_graph', 'dataset_release'}, - 'artifacts.resolve': frozenset(), -} -# A new receipt in these key spaces can change the meaning of older ones. -SHARED_KEY_SPACES = ('study_execution.', 'runtime.') -# Receipts these prefixes claim are also validated inside history decoding. -HISTORY_RECEIPTS = ('studies.', 'history.disclose') - - -def _prefix(operation): - return next((prefix for prefix in RECEIPT_BINDINGS if operation.startswith(prefix)), None) - - -@dataclass(frozen=True) -class ValidationDelta: - """Identities a mutation changed relative to its validated base checkpoint.""" - changed: frozenset - operations: frozenset = frozenset() # operation names of new/changed receipts - added: frozenset = frozenset() # changed identities absent from the base - - @property - def families(self): - # A newly added artifact declaration cannot change any component: an - # unchanged record referencing an undeclared blob already failed base - # validation. New declarations are still checked by the claim loop. - return frozenset(family for family, identity in self.changed - if not (family == 'project_artifact' and (family, identity) in self.added)) - - def touches(self, component): - return bool(self.families & COMPONENTS[component]) - - def history_receipt_added(self): - return any(operation.startswith(HISTORY_RECEIPTS) for operation in self.operations) - - def receipt_needed(self, operation, identity): - if identity in self.changed: - return True - prefix = _prefix(operation) - if prefix is None: - return True - if self.families & RECEIPT_BINDINGS[prefix]: - return True - if prefix in SHARED_KEY_SPACES and any(op.startswith(prefix) for op in self.operations): - return True - return False - - -_DELTA = contextvars.ContextVar('validation_delta', default=None) - - -@contextmanager -def edit_delta(delta): - """Validate the enclosed candidate relative to its validated base checkpoint.""" - token = _DELTA.set(delta) - try: - yield - finally: - _DELTA.reset(token) - - -def current_delta(): - return _DELTA.get() diff --git a/project_working_store.py b/project_working_store.py deleted file mode 100644 index 03d35f5e..00000000 --- a/project_working_store.py +++ /dev/null @@ -1,634 +0,0 @@ -"""Persistent PostgreSQL working copy of one external project folder. - -The database holds the current record set of an opened project and is kept -across sessions. The external folder (`.tuldok/project.json` plus -content-addressed `records/`, tracked in Git) is an import source, read only -when its checkpoint changed since Tuldok last imported or saved it, and an -export target written only by save(). See docs/plans/database-working-store.md. - -Records are kept exactly as their canonical bytes with their SHA256, so the -working copy has the same manifest, checkpoint digest and receipts as the file -format and save() writes byte-identical files. This store keeps no record state -in memory: inventory, receipts and bodies are read from PostgreSQL, so an outer -transaction rollback can never leave a stale in-process copy. - -Interface parity with ProjectStore (summary, snapshot, commit, save, -reconcile, root_directory, verify_records, recover_checkpoint, close, path) -lets Session, owners, artifacts and custody use either store. -""" -from contextlib import contextmanager, nullcontext -import json -import os -from pathlib import Path -import re -import threading -import uuid - -import psycopg -from psycopg import sql - -from metadata import _key, connection_info -from project_record_dedupe import CLOSURE_FAMILY, RUN_FAMILY, compact, expand, is_compact -from project_store import (FORMAT, MAX_RECORD_BYTES, MAX_RECORDS, MAX_TOTAL_BYTES, SUPPORTED_FORMATS, - ProjectStoreError, _RecordsDigest, _decode, _digest, _domain_format, _encode, - _fail, _identifier, _keys, _manifest_raw, _request, _sha, envelope_digest) - -WORKING_ID = re.compile(r'^[a-f0-9]{32}$') -_TABLES = ( - '''CREATE TABLE IF NOT EXISTS {schema}.state ( - singleton boolean PRIMARY KEY DEFAULT true CHECK (singleton), - project_id text NOT NULL, name text NOT NULL, checkpoint text NOT NULL, - receipts bytea NOT NULL, external_sha256 text, dirty boolean NOT NULL)''', - '''CREATE TABLE IF NOT EXISTS {schema}.records ( - family text COLLATE "C" NOT NULL, id text COLLATE "C" NOT NULL, - format text NOT NULL, bytes integer NOT NULL, sha256 text NOT NULL, - raw bytea NOT NULL, PRIMARY KEY (family, id))''', -) -_MIGRATIONS = ( - # SHA256 of the canonical {family, id, document} envelope (see envelope_digest). - 'ALTER TABLE {schema}.records ADD COLUMN IF NOT EXISTS envelope_sha256 text', - # Shared runtime closure referenced by a compact Run row (project_record_dedupe). - 'ALTER TABLE {schema}.records ADD COLUMN IF NOT EXISTS closure_id text', -) -_ORDER = sql.SQL('ORDER BY family COLLATE "C", id COLLATE "C"') - - -class WorkingProjectStore: - """One exclusive owner of a project's database working copy.""" - - def __init__(self, folder, working_id, *, dsn=None, canonical_digests=None): - if type(working_id) is not str or not WORKING_ID.fullmatch(working_id): - raise ValueError('Invalid working copy identity.') - self._folder = folder - self.working_id = working_id - self.schema = 'working_' + working_id - self._canonical_digests = canonical_digests - self._mutex = threading.RLock() - self._db = None - self._closed = False - try: - self._own = psycopg.connect(connection_info(dsn), autocommit=True) - except psycopg.Error: - raise ProjectStoreError('Local PostgreSQL is unavailable.', 'unavailable', 503) from None - try: - # One Tuldok process owns a working copy at a time. - if not self._own.execute('SELECT pg_try_advisory_lock(%s)', (_key(self.schema),)).fetchone()[0]: - raise ProjectStoreError('This project is already open in another Tuldok session.', 'busy', 409) - with self._own.transaction(): - self._own.execute(sql.SQL('CREATE SCHEMA IF NOT EXISTS {}').format(sql.Identifier(self.schema))) - for statement in (*_TABLES, *_MIGRATIONS): - self._own.execute(sql.SQL(statement).format(schema=sql.Identifier(self.schema))) - except BaseException: - self._own.close() - raise - - # ---- Connection: own until bound to the projection, then shared so - # record commits are atomic with the projection's SQL writes. - - def bind(self, db): - """Use the projection database's connection and transactions.""" - with self._locked(): - self._db = db - - @contextmanager - def _locked(self): - """Store ownership in one global order: projection lock, then this mutex. - - A bound projection connection is shared with Session/owner threads that - hold the projection lock across their transactions, so store work never - takes its own mutex first and then waits for that lock. - """ - if self._db is not None: - with self._catalog_lock(), self._mutex: - yield - else: - with self._mutex: - yield - - def _catalog_lock(self): - # The projection may install a composite host -> session -> catalog - # lock; the store is innermost, so it takes only the catalog lock. - lock = self._db.lock - return getattr(lock, 'projection', lock) - - def _joined(self): - # Join the projection only inside its open transaction (Session.mutate, - # background publication), so record and projection rows commit - # atomically. Other commits use this store's own connection and never - # fire the projection's commit hooks. - return self._db is not None and self._db.in_transaction - - def _connection(self): - return self._db.connection if self._joined() else self._own - - def _guard(self): - # A bound projection connection is shared; its catalog lock serializes - # every command and transaction on it across threads. - return self._catalog_lock() if self._joined() else nullcontext() - - @contextmanager - def _transaction(self): - if self._joined(): - with self._catalog_lock(), self._db.transaction(): - yield - else: - with self._own.transaction(): - yield - - def _execute(self, statement, parameters=None): - if self._closed: - _fail('Project store is closed.', 'unavailable', 409) - with self._guard(): - return self._connection().execute(statement, parameters) - - def _q(self, text): - return sql.SQL(text).format(state=sql.Identifier(self.schema, 'state'), - records=sql.Identifier(self.schema, 'records'), order=_ORDER) - - # ---- Open: attach, import or refuse. - - @classmethod - def open(cls, folder, working_id, *, dsn=None, canonical_digests=None): - """Attach the working copy, importing the folder only if it changed.""" - store = cls(folder, working_id, dsn=dsn, canonical_digests=canonical_digests) - try: - raw, manifest = folder.folder_checkpoint() - external = _sha(raw) - state = store._state(required=False) - if state is not None and state['project_id'] != manifest['project_id']: - _fail('This working copy belongs to a different project.', 'conflict', 409) - if state is None or state['external_sha256'] != external: - if state is not None and state['dirty']: - _fail('The external project changed while this workspace has unsaved changes. ' - 'Save over it or discard the working copy and import again.', 'conflict', 409) - store._import(raw, manifest) - return store - except BaseException: - store.close() - raise - - def _state(self, *, required=True): - row = self._execute(self._q('SELECT project_id, name, checkpoint, receipts, external_sha256, dirty FROM {state}')).fetchone() - if row is None: - if required: - _fail('Project working copy is missing.', 'unavailable', 409) - return None - return dict(project_id=row[0], name=row[1], checkpoint=row[2], receipts=json.loads(bytes(row[3])), - external_sha256=row[4], dirty=row[5]) - - def _import(self, raw, manifest): - """Bring the working copy to the folder's checkpoint, reading only new revisions.""" - with self._locked(), self._transaction(): - existing = {(row[0], row[1]): row[2] for row in - self._execute(self._q('SELECT family, id, sha256 FROM {records}'))} - wanted = {} - proven = [] - known = self._canonical_digests - for entry in manifest['inventory']: - identity = (entry['family'], entry['id']) - wanted[identity] = entry - if existing.get(identity) == entry['sha256']: - continue - body = self._folder.folder_record(entry) - if known is not None and entry['sha256'] in known: - document = json.loads(body) - else: - document = _decode(body) - proven.append(entry['sha256']) - if type(document) is not dict or document.get('format') != entry['format']: - _fail('Domain document format disagrees with its inventory.') - compact_run = is_compact(entry['family'], document) - self._execute(self._q( - 'INSERT INTO {records} (family, id, format, bytes, sha256, raw, envelope_sha256, closure_id) ' - 'VALUES (%s,%s,%s,%s,%s,%s,%s,%s) ' - 'ON CONFLICT (family, id) DO UPDATE SET format=EXCLUDED.format, bytes=EXCLUDED.bytes, ' - 'sha256=EXCLUDED.sha256, raw=EXCLUDED.raw, envelope_sha256=EXCLUDED.envelope_sha256, ' - 'closure_id=EXCLUDED.closure_id'), - (entry['family'], entry['id'], entry['format'], entry['bytes'], entry['sha256'], body, - # A compact Run's logical envelope digest is filled from its expansion. - None if compact_run or entry['family'] == CLOSURE_FAMILY else envelope_digest(entry['family'], entry['id'], body), - document['runtime_closure']['id'] if compact_run else None)) - for family, record_id in set(existing) - set(wanted): - self._execute(self._q('DELETE FROM {records} WHERE family=%s AND id=%s'), (family, record_id)) - if self._records_digest() != manifest['receipts'][-1]['records_sha256']: - _fail('Latest operation receipt disagrees with the current record set.') - self._write_state(manifest, external_sha256=_sha(raw), dirty=False) - if known is not None and proven: - known.add_many(proven) - - def _write_state(self, manifest, *, external_sha256, dirty): - receipts = _encode(manifest['receipts']) - self._execute(self._q('DELETE FROM {state}')) - self._execute(self._q('INSERT INTO {state} (project_id, name, checkpoint, receipts, external_sha256, dirty) ' - 'VALUES (%s,%s,%s,%s,%s,%s)'), - (manifest['project_id'], manifest['name'], manifest['checkpoint'], receipts, - external_sha256, dirty)) - - def _rows(self, statement, parameters=None): - """Stream (family, id, raw) rows through a server-side cursor. - - Bodies are fetched in small batches, never the whole record set at once. - """ - if self._closed: - _fail('Project store is closed.', 'unavailable', 409) - with self._guard(): - connection = self._connection() - idle = connection.info.transaction_status == psycopg.pq.TransactionStatus.IDLE - with (connection.transaction() if idle else nullcontext()), \ - connection.cursor(name='working_' + uuid.uuid4().hex) as cursor: - cursor.itersize = 64 - cursor.execute(statement, parameters) - for row in cursor: - yield row[0], row[1], bytes(row[2]) - - def _records_digest(self, replacements=None, identities=None): - """Streamed receipt digest over the stored (or a candidate) record set.""" - digest = _RecordsDigest() - replacements = replacements or {} - if identities is None: - for family, record_id, raw in self._rows(self._q('SELECT family, id, raw FROM {records} {order}')): - digest.add(family, record_id, raw) - return digest.hexdigest() - stored = self._rows(self._q('SELECT family, id, raw FROM {records} {order}')) - pending = next(stored, None) - for identity in identities: - while pending is not None and (pending[0], pending[1]) < identity: - pending = next(stored, None) - if identity in replacements: - digest.add(identity[0], identity[1], replacements[identity]) - elif pending is not None and (pending[0], pending[1]) == identity: - digest.add(identity[0], identity[1], pending[2]) - else: - _fail('Unchanged candidate record is missing from the working copy.') - return digest.hexdigest() - - # ---- Logical documents: closures hidden, compact Runs expanded. - - def _closure(self, identity): - cache = self.__dict__.setdefault('_closures', {}) - if identity not in cache: - row = self._execute(self._q('SELECT raw FROM {records} WHERE family=%s AND id=%s'), - (CLOSURE_FAMILY, identity)).fetchone() - if row is None: - _fail('Compact Run references a missing runtime closure.') - cache[identity] = json.loads(bytes(row[0])) - return cache[identity] - - def _logical(self, family, raw): - document = json.loads(raw) - if is_compact(family, document): - document = expand(document, self._closure(document['runtime_closure']['id'])) - return document - - # ---- Manifest identity, identical to the file format. - - def _inventory(self): - return [(row[0], row[1], row[2], row[3], row[4]) for row in - self._execute(self._q('SELECT family, id, format, bytes, sha256 FROM {records} {order}'))] - - @staticmethod - def _manifest(state, inventory): - manifest = dict(format=FORMAT, project_id=state['project_id'], name=state['name'], - roots=[dict(family=f, id=i) for f, i, _fmt, _b, _s in inventory], - inventory=[dict(family=f, id=i, format=fmt, namespace=state['project_id'], - path=f'records/{f}/{i}/{sha}.json', bytes=size, sha256=sha) - for f, i, fmt, size, sha in inventory], - receipts=state['receipts']) - manifest['checkpoint'] = _sha(_encode(manifest)) - return manifest - - # ---- ProjectStore interface. - - @property - def path(self): - return self._folder.path - - @property - def _root_fd(self): - """The external folder's locked physical root (read-only).""" - return self._folder._root_fd - - def summary(self): - with self._locked(): - state = self._state() - return {key: state[key] for key in ('project_id', 'name', 'checkpoint')} - - def manifest_raw(self): - """Canonical project.json bytes of the working copy's current checkpoint.""" - with self._locked(): - return _manifest_raw(self._manifest(self._state(), self._inventory())) - - def dirty(self): - """Whether the working copy has changes not yet saved to the folder.""" - with self._locked(): - return self._state()['dirty'] - - def snapshot(self): - """Complete independent record set (costly for large projects).""" - with self._locked(): - state = self._state() - records = [dict(family=f, id=i, document=self._logical(f, raw)) for f, i, raw in self._rows( - self._q('SELECT family, id, raw FROM {records} WHERE family <> %s {order}'), (CLOSURE_FAMILY,))] - return dict(project_id=state['project_id'], name=state['name'], - checkpoint=state['checkpoint'], records=records) - - def records(self, *families): - """Independent decoded envelopes of the selected families, in record order.""" - if not families or any(type(family) is not str for family in families): - raise TypeError('Select one or more record families by name.') - with self._locked(): - selected = [family for family in families if family != CLOSURE_FAMILY] - return [dict(family=f, id=i, document=self._logical(f, raw)) for f, i, raw in self._rows( - self._q('SELECT family, id, raw FROM {records} WHERE family = ANY(%s) {order}'), (selected,))] - - def envelope_digests(self): - """(family, id) -> canonical envelope SHA256 for every stored revision. - - Rows imported before this column existed are filled once from their - stored canonical bytes. - """ - with self._locked(): - missing = self._execute(self._q('SELECT count(*) FROM {records} WHERE envelope_sha256 IS NULL AND family <> %s'), - (CLOSURE_FAMILY,)).fetchone()[0] - if missing: - with self._transaction(): - # Logical envelopes: a compact Run hashes its exact expansion. - digests = [(envelope_digest(family, record_id, _encode(self._logical(family, raw)) - if family == RUN_FAMILY else raw), family, record_id) - for family, record_id, raw in self._rows(self._q( - 'SELECT family, id, raw FROM {records} WHERE envelope_sha256 IS NULL AND family <> %s {order}'), - (CLOSURE_FAMILY,))] - with self._guard(): - with self._connection().cursor() as cursor: - cursor.executemany(self._q('UPDATE {records} SET envelope_sha256=%s WHERE family=%s AND id=%s'), - digests) - return {(row[0], row[1]): row[2] for row in - self._execute(self._q('SELECT family, id, envelope_sha256 FROM {records} WHERE family <> %s'), - (CLOSURE_FAMILY,))} - - def records_view(self, *families): - """Every record identity in order; documents decoded only for selected families. - - Unselected envelopes carry document None. Fork and membership - validators need every identity but only read their own families. - """ - if not families or any(type(family) is not str for family in families): - raise TypeError('Select one or more record families by name.') - with self._locked(): - connection = self._connection() - idle = connection.info.transaction_status == psycopg.pq.TransactionStatus.IDLE - result = [] - with (connection.transaction() if idle else nullcontext()), \ - connection.cursor(name='working_' + uuid.uuid4().hex) as cursor: - cursor.itersize = 256 - cursor.execute(self._q('SELECT family, id, CASE WHEN family = ANY(%s) THEN raw END ' - 'FROM {records} WHERE family <> %s {order}'), (list(families), CLOSURE_FAMILY)) - rows = [(family, record_id, None if raw is None else bytes(raw)) for family, record_id, raw in cursor] - for family, record_id, raw in rows: - result.append(dict(family=family, id=record_id, - document=None if raw is None else self._logical(family, raw))) - return result - - def record(self, family, record_id): - if family == CLOSURE_FAMILY: - return None - with self._locked(): - row = self._execute(self._q('SELECT raw FROM {records} WHERE family=%s AND id=%s'), - (family, record_id)).fetchone() - return None if row is None else dict(family=family, id=record_id, document=self._logical(family, bytes(row[0]))) - - def reconcile(self, request_key, request_sha256): - _request(request_key, request_sha256) - with self._locked(): - for receipt in self._state()['receipts']: - if receipt['request_key'] == request_key: - if receipt['request_sha256'] != request_sha256: - _fail('Request key was already used with different input.', 'conflict', 409) - return self.snapshot() - return None - - def commit(self, records, expected_checkpoint, request_key, request_sha256, *, changed=None): - """Replace the complete current record set in the working copy. - - changed, when given, names every (family, id) whose document may differ - from the stored revision; all other candidate records are the caller's - unmodified copies of stored revisions (Session.mutate constructs them - so). Without it every candidate is compared exactly with its revision. - Returns the committed snapshot, sharing the caller's record list. - """ - _request(request_key, request_sha256) - _digest(expected_checkpoint, 'Expected checkpoint') - if type(records) is not list or len(records) > MAX_RECORDS: - _fail('Project records must be a bounded list.') - with self._locked(), self._transaction(): - state = self._state() - inventory = {(f, i): (fmt, size, sha) for f, i, fmt, size, sha in self._inventory()} - candidates = {} - for record in records: - _keys(record, ('family', 'id', 'document'), 'Project record') - family, identity, document = record['family'], record['id'], record['document'] - _identifier(family, 'Record family') - if family not in SUPPORTED_FORMATS: - _fail('Unsupported project record family.', 'unsupported', 422) - if family == CLOSURE_FAMILY: - _fail('Runtime closures are store-owned records.', 'unsupported', 422) - _identifier(identity, 'Record ID') - if (family, identity) in candidates: - _fail('Duplicate project record identity.') - if type(document) is not dict: - _fail('Domain document must be an object.') - _domain_format(document.get('format'), family) - candidates[(family, identity)] = document - replacements, entries, total = {}, {}, 0 - closure_rows = {row[1]: row[2] for row in self._execute(self._q( - 'SELECT family, id, closure_id FROM {records} WHERE closure_id IS NOT NULL'))} - new_closures, row_closures, logical_raw, referenced = {}, {}, {}, set() - for identity in sorted(candidates): - document = candidates[identity] - current = inventory.get(identity) - if current is not None and changed is not None and identity not in changed \ - and current[0] in (document['format'], 'project_run_history_v2'): - entries[identity] = current - total += current[1] - if identity[1] in closure_rows and identity[0] == RUN_FAMILY: - referenced.add(closure_rows[identity[1]]) - continue - physical = document - if (identity[0] == RUN_FAMILY and changed is None and current is not None - and current[0] == document['format'] and _sha(_encode(document)) == current[2]): - # An unchanged uncompacted Run keeps its verified revision (as in - # ProjectStore); compact_run_closures migrates explicitly. - entries[identity] = current - total += current[1] - continue - if identity[0] == RUN_FAMILY: - compacted = compact(document) - if compacted is not None: - physical, closure = compacted - closure_id = physical['runtime_closure']['id'] - new_closures.setdefault(closure_id, closure) - referenced.add(closure_id) - row_closures[identity] = closure_id - logical_raw[identity] = _encode(document) - raw = _encode(physical) - if len(raw) > MAX_RECORD_BYTES: - _fail('Project records exceed the synchronous byte limit.') - digest = _sha(raw) - if current is None or current[2] != digest: - replacements[identity] = raw - entries[identity] = (physical['format'], len(raw), digest) - total += len(raw) - if total > MAX_TOTAL_BYTES: - _fail('Project records exceed the synchronous byte limit.') - # Exactly the closures referenced by stored compact Runs are kept. - for closure_id in sorted(referenced): - identity = (CLOSURE_FAMILY, closure_id) - if identity in inventory: - entries[identity] = inventory[identity] - total += inventory[identity][1] - continue - raw = _encode(new_closures[closure_id]) - replacements[identity] = raw - entries[identity] = (new_closures[closure_id]['format'], len(raw), _sha(raw)) - total += len(raw) - if total > MAX_TOTAL_BYTES: - _fail('Project records exceed the synchronous byte limit.') - records_digest = self._records_digest(replacements, sorted(entries)) - for receipt in state['receipts']: - if receipt['request_key'] == request_key: - if receipt['request_sha256'] != request_sha256 or receipt['records_sha256'] != records_digest: - _fail('Request key was already used with different input.', 'conflict', 409) - return self.snapshot() - if expected_checkpoint != state['checkpoint']: - _fail('Expected project checkpoint is stale.', 'stale', 409) - receipts = state['receipts'] + [dict(request_key=request_key, request_sha256=request_sha256, - records_sha256=records_digest)] - manifest = self._manifest(dict(state, receipts=receipts), - [(f, i, *entries[(f, i)]) for f, i in sorted(entries)]) - _manifest_raw(manifest) - for (family, identity), raw in replacements.items(): - fmt, size, digest = entries[(family, identity)] - key = (family, identity) - envelope = (None if family == CLOSURE_FAMILY else - envelope_digest(family, identity, logical_raw.get(key, raw))) - self._execute(self._q( - 'INSERT INTO {records} (family, id, format, bytes, sha256, raw, envelope_sha256, closure_id) ' - 'VALUES (%s,%s,%s,%s,%s,%s,%s,%s) ' - 'ON CONFLICT (family, id) DO UPDATE SET format=EXCLUDED.format, bytes=EXCLUDED.bytes, ' - 'sha256=EXCLUDED.sha256, raw=EXCLUDED.raw, envelope_sha256=EXCLUDED.envelope_sha256, ' - 'closure_id=EXCLUDED.closure_id'), - (family, identity, fmt, size, digest, raw, envelope, row_closures.get(key))) - for family, identity in set(inventory) - set(entries): - self._execute(self._q('DELETE FROM {records} WHERE family=%s AND id=%s'), (family, identity)) - self._write_state(manifest, external_sha256=state['external_sha256'], dirty=True) - if self._canonical_digests is not None and replacements: - self._canonical_digests.add_many([_sha(raw) for raw in replacements.values()]) - return dict(project_id=state['project_id'], name=state['name'], checkpoint=manifest['checkpoint'], - records=[dict(family=f, id=i, document=candidates[(f, i)]) for f, i in sorted(candidates)]) - - def compact_run_closures(self, request_key, request_sha256): - """Format migration: store every compactable Run against a shared closure. - - The logical record set is unchanged (each compaction is checked to expand - to the exact original bytes); only the physical records and checkpoint - change. Returns (previous checkpoint, committed snapshot summary). - """ - with self._locked(): - state = self._state() - uncompacted = {(row[0], row[1]) for row in self._execute(self._q( - "SELECT family, id FROM {records} WHERE family=%s AND format='project_run_history_v1'"), (RUN_FAMILY,))} - snapshot = self.snapshot() - committed = self.commit(snapshot['records'], state['checkpoint'], request_key, request_sha256, - changed=uncompacted) - return state['checkpoint'], {key: committed[key] for key in ('project_id', 'name', 'checkpoint')} - - def save(self, expected_checkpoint): - """Export the working copy to the external folder (the only folder write).""" - _digest(expected_checkpoint, 'Expected checkpoint') - with self._locked(): - state = self._state() - if expected_checkpoint != state['checkpoint']: - _fail('Expected project checkpoint is stale.', 'stale', 409) - try: - external_raw, _external = self._folder.folder_checkpoint() - except ProjectStoreError: - external_raw = None - if (state['external_sha256'] is not None and - (external_raw is None or _sha(external_raw) != state['external_sha256'])): - _fail('The external project changed since Tuldok last imported or saved it.', 'conflict', 409) - manifest = self._manifest(state, self._inventory()) - if manifest['checkpoint'] != state['checkpoint']: - _fail('Working copy checkpoint disagrees with its records.', 'invalid', 409) - raw = _manifest_raw(manifest) - if state['external_sha256'] != _sha(raw): - for entry in manifest['inventory']: - if not self._folder.folder_has_record(entry): - body = self._execute(self._q('SELECT raw FROM {records} WHERE family=%s AND id=%s'), - (entry['family'], entry['id'])).fetchone() - body = bytes(body[0]) - if len(body) != entry['bytes'] or _sha(body) != entry['sha256']: - _fail('Working copy record bytes are corrupt.', 'invalid', 409) - self._folder.folder_write_record(entry['family'], entry['id'], entry['sha256'], body) - self._folder.folder_publish(raw, external_raw) - with self._transaction(): - self._write_state(manifest, external_sha256=_sha(raw), dirty=False) - return {key: state[key] for key in ('project_id', 'name', 'checkpoint')} - - def verify_records(self): - """Re-check every stored revision's bytes against its SHA256 and length.""" - with self._locked(): - inventory = {(f, i): (size, sha) for f, i, _fmt, size, sha in self._inventory()} - for family, record_id, raw in self._rows(self._q('SELECT family, id, raw FROM {records} {order}')): - size, digest = inventory[(family, record_id)] - if len(raw) != size or _sha(raw) != digest: - _fail('Canonical record bytes changed or are corrupt.', 'stale', 409) - - def recover_checkpoint(self): - """Database commits are atomic; return the committed record set.""" - return self.snapshot() - - @contextmanager - def root_directory(self, *, verify_after=False): - """Borrow the external folder's physical root (payload artifacts live there).""" - if type(verify_after) is not bool: - _fail('Root read verification must be an explicit boolean.') - with self._locked(): - before = self._state()['checkpoint'] - descriptor = os.dup(self._folder._root_fd) - try: - yield descriptor - self._folder._binding() - if verify_after and self._state()['checkpoint'] != before: - _fail('Project checkpoint changed during the bounded root read.', 'stale', 409) - finally: - os.close(descriptor) - - def close(self): - # The projection (and its lock's connection) may already be closed. - with self._mutex: - if self._closed: - return - self._closed = True - try: - self._folder.close() - finally: - self._own.close() - - def __enter__(self): - return self - - def __exit__(self, *exc): - self.close() - - -def registered_schemas(control_path): - """Working-copy schemas registered by a workspace control directory.""" - schemas = [] - for path in sorted(Path(control_path).glob('.project-working/*.json')): - try: - identity = json.loads(path.read_bytes()).get('working_id') - except (OSError, ValueError, AttributeError): - continue - if type(identity) is str and WORKING_ID.fullmatch(identity): - schemas.append('working_' + identity) - return schemas diff --git a/project_workspace.py b/project_workspace.py deleted file mode 100644 index b6f61256..00000000 --- a/project_workspace.py +++ /dev/null @@ -1,763 +0,0 @@ -"""One inert external-project workspace and its installation-local authority. - -Only explicit project-files operations enter this owner. Legacy domain routes -are unavailable in this mode until their canonical publication is implemented. -The installation catalog holds local credentials; it is never portable content. -""" -import copy -from contextlib import ExitStack -import hashlib -import json -import os -from pathlib import Path -import re -import threading -import uuid - -from access import Access -import agent_api -from metadata import Metadata -from project_store import ProjectStore, ProjectStoreError -from project_projection import ProjectProjection -from project_custody import ProjectCustody -from project_validation_cache import CanonicalDigestCache, ProjectValidationCache -from project_working_store import WORKING_ID, WorkingProjectStore -from workbench import WorkbenchError - - -PUBLIC_RECORD_FIELDS = ('id', 'kind', 'name', 'text', 'groups', 'parents', 'provenance', - 'task', 'annotation', 'review', 'revision', 'source_revision', - 'created_at', 'updated_at') -SUMMARY_FIELDS = ('id', 'kind', 'name', 'task', 'review', 'revision', 'source_revision', - 'created_at', 'updated_at') -PROJECT_ACTIONS = ('new', 'open', 'save', 'close', 'query', 'get', 'import_text', 'annotate') -# Set only after the complete finite dispatcher is integrated. A capability is -# a promise that the route reaches canonical publication, not an API wishlist. -M2_ENABLED = True -M3_ENABLED = True -M4_ENABLED = True -_RECOVERY_OPERATIONS = frozenset(('project_files.execution_reconcile_current', - 'project_files.native_reconcile', - 'project_files.runtime_capture', 'project_files.runtime_abandon', - 'project_files.execution_study_abandon_preparation', 'project_files.execution_study_reconcile_preparation')) -_DRAINING_OPERATIONS = _RECOVERY_OPERATIONS | frozenset(('project_files.execution_producer_cancel', - 'project_files.execution_study_stop')) -DIR_FLAGS = os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW | os.O_CLOEXEC - - -def public_record(value): - """Project owned values into the closed public contract; do not infer policy.""" - return {key: copy.deepcopy(value[key]) for key in PUBLIC_RECORD_FIELDS} - - -def _digest(value): - return hashlib.sha256(agent_api.encoded(value)).hexdigest() - - -def http_arguments(method, target, body=None): - """Use the fixed operation contracts for identical HTTP and SDK routing.""" - names = ['project_files.status', *('project_files.' + action for action in PROJECT_ACTIONS)] - names.extend(sorted(agent_api.PROJECT_FILES_M2 | agent_api.PROJECT_FILES_M3 | agent_api.PROJECT_FILES_M4)) - operations = {name: agent_api.operation(name) for name in names} - # A literal import route wins over a record-id placeholder. Contract - # validation still rejects an unexpected path/body/query representation. - ordered = sorted(operations.items(), key=lambda item: (item[1]['path'].count('{'), item[0])) - for name, operation in ordered: - if agent_api._route_matches(operation, method, target): - selected = (name, 1, agent_api.contract(name, 1)['sha256']) - return name, agent_api.validate_selected(selected, method, target, body) - raise WorkbenchError('Unknown project-file operation.', 'unsupported', 404) - - -class ProjectWorkspace: - project_files_mode = True - - def __init__(self, control_path, roots, *, dsn=None, runtime_sources=None): - from runtime_snapshots import configuration - configured = {} - for alias, config in (runtime_sources or {}).items(): - if (type(alias) is not str or not re.fullmatch('[A-Za-z0-9][A-Za-z0-9_.-]{0,63}', alias) - or len(configured) >= 100): - raise WorkbenchError('Configure at most 100 named current runtime sources.') - configured[alias] = copy.deepcopy(configuration(config)) - self.path = Path(control_path).resolve() - self.db = Metadata(self.path, dsn=dsn) - self.lock = self.db.lock - self.access = Access(self.db, self.path) - self.custody = ProjectCustody(self.path, self.db.dataset_id) - self.validation_cache = ProjectValidationCache(self.path) - self.canonical_digests = CanonicalDigestCache(self.path) - self._retained_recovery = None - self._dsn = dsn - self._runtime_sources = configured - self._mutex = threading.RLock() - self._roots = {} - self._store = self._text = self._projection = None - self._selection = None - self._last_project = None - self._recovery = None - self._binding = uuid.uuid4().hex - self._closed = False - self._receipts = {} - try: - if not roots or len(roots) > 100: - raise WorkbenchError('Configure between one and 100 local project-file roots.') - for alias, path in roots.items(): - if type(alias) is not str or not re.fullmatch('[A-Za-z0-9][A-Za-z0-9_.-]{0,63}', alias): - raise WorkbenchError('Invalid local project-file root alias.') - location = Path(path).expanduser().resolve(strict=True) - descriptor = os.open(location, DIR_FLAGS) - self._roots[alias] = (location, descriptor) - except BaseException: - self.close() - raise - - def _ensure_open(self): - if self._closed: - raise WorkbenchError('Project workspace is closed.', 'unavailable', 503) - - def _recovery_required(self, reason, request_key=None): - if self._recovery is None and self._selection is not None and self._last_project is not None: - self._recovery = dict(action='open', root=self._selection[0], directory=self._selection[1], - reason=reason, request_key=request_key) - - def _state(self): - self._ensure_open() - project = None - if self._recovery is None and self._store is not None: - try: - snapshot = self._store.summary() - except ProjectStoreError as error: - if error.code not in ('unknown', 'outcome_unknown', 'stale', 'stale_project', - 'invalid', 'unsupported', 'unavailable'): - raise - self._recovery_required('unknown_publication' if error.code in ('unknown', 'outcome_unknown') - else 'projection_unavailable') - else: - if self._text is not None and not self._text.available: - self._recovery_required('projection_unavailable') - else: - project = {key: snapshot[key] for key in ('project_id', 'name', 'checkpoint')} - self._last_project = copy.deepcopy(project) - if self._recovery is not None: - return dict(format='project_files_state_v1', binding=self._binding, state='recovery_required', - roots=sorted(self._roots), project=copy.deepcopy(self._last_project), - available_actions=['open'], recovery=copy.deepcopy(self._recovery)) - return dict(format='project_files_state_v1', binding=self._binding, - state='open' if project is not None else 'no_project_open', - roots=sorted(self._roots), project=project, - available_actions=list(PROJECT_ACTIONS if project is not None else ('new', 'open'))) - - def status(self): - with self._mutex, self.access.lock: - self.access.require('inspect', 'project_files.status') - return self._state() - - def capabilities(self): - value = agent_api.capabilities(self.db.dataset_id, profile='project') - for operation in value['operations']: - if operation['id'].startswith('project_transfer.'): - operation['availability'] = ('available' if getattr(self, 'transfer_controller', None) - is not None else 'unavailable') - continue - if operation['id'] in agent_api.PROJECT_FILES_M2 and not M2_ENABLED: - operation['availability'] = 'unavailable' - if operation['id'] in agent_api.PROJECT_FILES_M3 and not M3_ENABLED: - operation['availability'] = 'unavailable' - if operation['id'] in agent_api.PROJECT_FILES_M4 and not M4_ENABLED: - operation['availability'] = 'unavailable' - if not operation['id'].startswith('project_files.') and operation['id'] not in ('context.get', 'identity.get'): - operation['availability'] = 'unavailable' - return value - - def _bound(self, arguments, *, may_be_empty=False, check_checkpoint=True, allow_recovery=False): - self._ensure_open() - if arguments['binding'] != self._binding: - raise WorkbenchError('The project workspace changed. Refresh its binding before acting.', - 'stale_project', 409) - if self._recovery is not None: - if not allow_recovery: - raise WorkbenchError('Explicitly reopen the current project to reconcile its canonical outcome.', - 'projection_unavailable', 503) - if arguments.get('expected_checkpoint') != self._last_project['checkpoint']: - raise WorkbenchError('Recovery requires the last acknowledged checkpoint.', 'stale_project', 409) - return - if self._store is None: - if not may_be_empty: - raise WorkbenchError('Open an external project first.', 'unavailable', 409) - if arguments.get('expected_checkpoint') is not None: - raise WorkbenchError('The empty workspace has no checkpoint.', 'stale_project', 409) - return - snapshot = self._store.summary() - expected = arguments.get('expected_checkpoint', arguments.get('checkpoint')) - if check_checkpoint and expected != snapshot['checkpoint']: - raise WorkbenchError('The project checkpoint changed. Refresh before acting.', 'stale_project', 409) - - def _root(self, alias, relative): - if alias not in self._roots: - raise WorkbenchError('Choose a configured local project-file root.', 'unavailable', 409) - # Store create_at/open_at retains this handle through all actual use. - if (type(relative) is not str or not relative or len(relative) > 512 or - relative.startswith('/') or '\\' in relative or '\x00' in relative or - any(part in ('', '.', '..') for part in relative.split('/')) or - len(relative.split('/')) > 16): - raise WorkbenchError('Use a project directory relative to its configured root, without traversal.') - root_path, root_fd = self._roots[alias] - from project_store import assert_separate_project_control - assert_separate_project_control(root_fd, relative, root_path=root_path, control_path=self.path) - return self._roots[alias] - - def _working_identity(self, alias, directory, project_id): - """The persistent working copy for one project folder (private registry).""" - key = hashlib.sha256(f'{alias}\0{directory}'.encode('utf-8')).hexdigest() - registry = self.path / '.project-working' - path = registry / f'{key}.json' - try: - value = json.loads(path.read_bytes()) - if (value.get('project_id') == project_id and type(value.get('working_id')) is str - and WORKING_ID.fullmatch(value['working_id'])): - return value['working_id'] - except (OSError, ValueError, AttributeError): - pass - working_id = uuid.uuid4().hex - registry.mkdir(mode=0o700, exist_ok=True) - temporary = registry / f'.{uuid.uuid4().hex}.tmp' - temporary.write_bytes(json.dumps(dict(format='project_working_registration_v1', root=alias, - directory=directory, project_id=project_id, working_id=working_id), sort_keys=True).encode('utf-8')) - os.chmod(temporary, 0o600) - os.replace(temporary, path) - return working_id - - def _open_working(self, root_fd, root_path, alias, directory): - """Attach the folder's working copy, importing only if the folder changed.""" - folder = ProjectStore.open_folder_at(root_fd, directory, root_path=root_path) - try: - _raw, manifest = folder.folder_checkpoint() - working_id = self._working_identity(alias, directory, manifest['project_id']) - return WorkingProjectStore.open(folder, working_id, dsn=self._dsn, - canonical_digests=self.canonical_digests) - except BaseException: - folder.close() - raise - - def _projection_for(self, store): - identity = uuid.uuid4().hex - path = self.path / '.project-projections' / identity - snapshot = store.summary() - projection = Metadata(path, dsn=self._dsn, dataset_id=snapshot['project_id'], projection_id=identity) - if hasattr(store, 'bind'): - # Record commits share the projection's transactions. - store.bind(projection) - try: - owner = ProjectProjection(store, projection, self.access, - {alias: value[0] for alias, value in self._roots.items()}, - custody=self.custody.for_projection(store, identity), - runtime_sources=self._runtime_sources, - validation_cache=self.validation_cache) - owner.pending_original = self.custody.pending(store) - if owner.pending_original: - owner.session.available = False - return owner, owner.text - except BaseException: - projection.close() - # Disposable failed projections remain identified for diagnosis; - # no authoritative bytes or an uncertain outcome is deleted. - raise - - def _retained_projection_for(self, store, projection_id): - if type(projection_id) is not str or not re.fullmatch('[a-f0-9]{32}', projection_id): - raise WorkbenchError('Invalid original local projection identity.', 'unavailable', 409) - db = Metadata(self.path / '.project-projections' / projection_id, dsn=self._dsn, - create=False, dataset_id=store.summary()['project_id'], projection_id=projection_id) - if hasattr(store, 'bind'): - store.bind(db) - try: - return ProjectProjection(store, db, self.access, - {alias: value[0] for alias, value in self._roots.items()}, - custody=self.custody.for_projection(store, projection_id), restore=False, - runtime_sources=self._runtime_sources, validation_cache=self.validation_cache) - except BaseException: - db.close() - raise - - def _detach(self): - """Release only a project whose current local effects have drained.""" - if self._projection is not None: - self._projection.execution.assert_quiescent() - # Closing keeps unsaved work in the database working copy; only an - # explicit Save writes the external folder. - if self._projection is not None: - self._projection.close() - if self._store is not None: - self._store.close() - self._store = self._text = self._projection = None - self._selection = None - self._last_project = self._recovery = None - - def _recover_current(self, arguments): - self._bound(arguments, allow_recovery=True) - if (arguments['root'], arguments['directory']) != self._selection: - raise WorkbenchError('Recover the current project before switching destinations.', 'projection_unavailable', 503) - if self._projection is not None and self._projection.pending_original: - raise WorkbenchError('Explicitly reconcile original-host custody before reopening this project.', - 'projection_unavailable', 503) - if self._projection is not None and self._projection.execution.has_local_custody: - # Retain actual local custody until the explicit execution recovery - # boundary proves cessation; imported history can never do so. - self._projection.execution.assert_quiescent() - root_path, root_fd = self._root(*self._selection) - # Keep the old projection and generation until a fresh inert projection - # is ready. Releasing the uncertain writer lock is necessary to reread it. - if self._store is not None: - self._store.close() - self._store = None - store = projection = None - try: - store = self._open_working(root_fd, root_path, *self._selection) - snapshot = store.summary() - if snapshot['project_id'] != self._last_project['project_id']: - raise WorkbenchError('Recovery destination has a different project identity.', 'stale_project', 409) - # Database commits are atomic: reattaching the working copy - # reconciles the outcome without writing the external folder. - projection, text = self._projection_for(store) - snapshot = store.summary() - if self._projection is not None: - self._projection.close() - self._store, self._projection, self._text = store, projection, text - self._last_project = {key: snapshot[key] for key in ('project_id', 'name', 'checkpoint')} - self._recovery = None - self._binding = uuid.uuid4().hex - return self._state() - except BaseException: - if projection is not None and projection is not self._projection: - projection.close() - if store is not None and store is not self._store: - store.close() - raise - - def _select(self, action, arguments): - if self._recovery is not None: - if action != 'open': - raise WorkbenchError('Reopen the current project before creating another.', 'projection_unavailable', 503) - return self._recover_current(arguments) - self._bound(arguments, may_be_empty=True) - root_path, root_fd = self._root(arguments['root'], arguments['directory']) - selection = (arguments['root'], arguments['directory']) - if action == 'open' and selection == self._selection: - return self._state() - if self._projection is not None: - self._projection.execution.assert_quiescent() - # Validate and construct the incoming inert projection before releasing - # the existing binding. An invalid Open cannot strand current custody. - store = None - projection = None - created = None - try: - if action == 'new': - request = {key: arguments[key] for key in ('root', 'directory', 'name', 'request_key')} - digest = _digest(request) - reconciled = False - try: - store = ProjectStore.create_at(root_fd, arguments['directory'], arguments['name'], - arguments['request_key'], digest, root_path=root_path) - except ProjectStoreError as error: - if error.code not in ('conflict', 'unknown', 'outcome_unknown'): - raise - # A lost creation reply or restart may leave a complete, - # unselected destination. Only its exact receipt authorizes - # treating it as this New; unrelated folders remain conflicts. - try: - store = ProjectStore.open_at(root_fd, arguments['directory'], root_path=root_path, canonical_digests=self.canonical_digests) - except ProjectStoreError: - raise error - if store.reconcile(arguments['request_key'], digest) is None: - store.close() - raise error - reconciled = True - snapshot = store.summary() - if reconciled: - store.save(snapshot['checkpoint']) - created = snapshot - # The new folder becomes this workspace's working copy. - store.close() - store = self._open_working(root_fd, root_path, arguments['root'], arguments['directory']) - else: - store = self._open_working(root_fd, root_path, arguments['root'], arguments['directory']) - projection, text = self._projection_for(store) - self._detach() - self._store, self._projection, self._text = store, projection, text - self._selection = selection - snapshot = store.summary() - self._last_project = {key: snapshot[key] for key in ('project_id', 'name', 'checkpoint')} - self._recovery = None - self._binding = uuid.uuid4().hex - return self._state() - except BaseException as error: - if projection is not None and projection is not self._projection: - projection.close() - if store is not None and store is not self._store: - store.close() - if created is not None and self._store is not store: - failure = WorkbenchError('Project was created but could not be selected; retry this exact New to reconcile its destination.', - 'project_selection_unavailable', 503) - failure.committed, failure.selected = True, False - failure.project_id, failure.checkpoint = created['project_id'], created['checkpoint'] - failure.request_key = arguments['request_key'] - failure.root, failure.directory = arguments['root'], arguments['directory'] - failure.receipt = dict(committed=True, selected=False, project_id=created['project_id'], - checkpoint=created['checkpoint'], request_key=arguments['request_key'], - root=arguments['root'], directory=arguments['directory']) - raise failure from error - raise - - def _record_result(self, record, *, before_revision=None, history_limit=1): - snapshot = self._store.summary() - history = [item for item in self._text.history(record['id']) - if item['revision'] <= record['revision'] and - (before_revision is None or item['revision'] < before_revision)] - history.sort(key=lambda item: item['revision'], reverse=True) - page = history[:history_limit] - self._last_project = {key: snapshot[key] for key in ('project_id', 'name', 'checkpoint')} - return dict(binding=self._binding, project_id=snapshot['project_id'], checkpoint=snapshot['checkpoint'], - record=public_record(record), history=[public_record(item) for item in page], - next_history_before_revision=page[-1]['revision'] if len(history) > len(page) else None) - - def _save_as(self, arguments): - return self._publish_independent(arguments) - - def _compose(self, arguments): - return self._publish_independent(arguments, composed=True) - - def _publish_independent(self, arguments, *, composed=False): - """Publish a new independent project, then select a fresh inert cache.""" - from functools import partial - from project_fork import publish_fork - from project_fork_composition import build_candidate - from workbench import timestamp - self._bound(arguments) - root_path, root_fd = self._root(arguments['root'], arguments['directory']) - source = self._projection - source.execution.assert_quiescent() - source.files.require_clean() - published = None - incoming = projection = None - retained = ExitStack() - try: - if composed: - from project_composition import publish_composition - from project_artifacts import ProjectArtifacts - others=[];identities={self._store.summary()['project_id']} - for selected in arguments['sources']: - if selected['project_id'] in identities: - raise WorkbenchError('Composition source identity repeats.','conflict',409) - identities.add(selected['project_id']) - directory,descriptor=self._root(selected['root'],selected['directory']) - store=retained.enter_context(ProjectStore.open_at(descriptor,selected['directory'],root_path=directory, canonical_digests=self.canonical_digests)) - actual=store.summary() - if actual['project_id']!=selected['project_id'] or actual['checkpoint']!=selected['checkpoint']: - raise WorkbenchError('Selected composition source checkpoint differs.','stale_project',409) - artifacts=retained.enter_context(ProjectArtifacts(store)) - others.append(dict(store=store,artifacts=artifacts,checkpoint=selected['checkpoint'])) - published=publish_composition(self._store,source.artifacts,others,root_fd,arguments['directory'], - root_path=root_path,name=arguments['name'],expected_checkpoint=arguments['expected_checkpoint'], - request_key=arguments['request_key'],quiescent=True,created_at=timestamp(), - id_factory=lambda *_:uuid.uuid4().hex, - validate_candidate=lambda records,identity,artifacts:source.validate_records(records,project_id=identity,artifacts=artifacts)) - else: - published = publish_fork(self._store, source.artifacts, root_fd, arguments['directory'], - root_path=root_path, name=arguments['name'], - expected_checkpoint=arguments['expected_checkpoint'], request_key=arguments['request_key'], - quiescent=True, build_candidate=partial(build_candidate, created_at=timestamp(), - id_factory=lambda _family, _source_id, _revision: uuid.uuid4().hex), - validate_candidate=lambda records, identity: source.validate_records(records, project_id=identity)) - # A filesystem editor can act outside the workspace lock. Leave the - # complete fork unselected if its source working files changed. - source.files.require_clean() - incoming = self._open_working(root_fd, root_path, arguments['root'], arguments['directory']) - projection, text = self._projection_for(incoming) - snapshot, overlay = published['snapshot'], published['fork'] - self._detach() - self._store, self._projection, self._text = incoming, projection, text - self._selection = arguments['root'], arguments['directory'] - self._last_project = {key: snapshot[key] for key in ('project_id', 'name', 'checkpoint')} - self._recovery = None - self._binding = uuid.uuid4().hex - summary = dict(source_project_id=overlay['source']['project_id'], - source_checkpoint=overlay['source']['checkpoint'], project_id=snapshot['project_id'], - checkpoint=snapshot['checkpoint'], root=arguments['root'], directory=arguments['directory'], - request_key=arguments['request_key'], reconciled=published['reconciled'], - mapping_count=len(overlay['mapping']), copied_count=len(overlay['artifacts']['copied']), - missing_regenerable_count=len(overlay['artifacts']['missing_regenerable'])) - result=dict(state=self._state(), fork=summary) - if composed: - result['sources']=[{key:item[key] for key in ('project_id','checkpoint')} for item in published['composition']['sources']] - return result - except BaseException as error: - if projection is not None and projection is not self._projection: - projection.close() - if incoming is not None and incoming is not self._store: - incoming.close() - receipt = getattr(error, 'receipt', None) - if published is not None: - snapshot = published['snapshot'] - receipt = dict(committed=True, selected=False, project_id=snapshot['project_id'], - checkpoint=snapshot['checkpoint'], request_key=arguments['request_key'], - root=arguments['root'], directory=arguments['directory']) - elif receipt is not None: - receipt = dict(receipt, root=arguments['root']) - if receipt is not None: - failure = WorkbenchError('Independent project was published but could not be selected; reconcile this exact request.', - 'project_selection_unavailable', 503) - failure.receipt = receipt - raise failure from error - raise - finally: - retained.close() - - def dispatch(self, name, arguments, *, selected_version=None): - """Pin workspace -> current host authority -> projection through return. - - An old request cannot observe a new Dataset alias. Revocation cannot - complete before an already-authorized canonical publication finishes. - """ - agent_api.validate_arguments(name, arguments) - if not name.startswith('project_files.'): - raise WorkbenchError('This domain is unavailable in external text-project mode.', 'unavailable', 409) - if name == 'project_files.execution_health': - return self._execution_health(arguments, selected_version=selected_version) - if name in _DRAINING_OPERATIONS: - return self._dispatch_draining(name, arguments) - action = name.removeprefix('project_files.') - with self._mutex, self.access.lock: - self._ensure_open() - operation = agent_api.operation(name) - for scope in operation['scopes']: - if scope == 'execute' and action in ('execution_submit_external', 'execution_study_admit'): - self.access.require_external_submission() - else: - self.access.require(scope, name, owner_only=action in ('new', 'open', 'save', 'save_as', 'compose', 'close')) - if selected_version == 1 and action in ('get', 'annotate'): - self._bound(arguments, check_checkpoint=action == 'get') - record = self._projection.data._require_record(arguments['record_id']) - if record['document']['current']['provenance'].get('method') != 'import': - raise WorkbenchError('This retained text provenance requires project text contract version 2.', - 'unsupported', 409) - if name in agent_api.PROJECT_FILES_M4 and not M4_ENABLED: - raise WorkbenchError('This project capability is not yet available.', 'unavailable', 409) - if name in (agent_api.PROJECT_FILES_M2 | agent_api.PROJECT_FILES_M3 | agent_api.PROJECT_FILES_M4) - {'project_files.save_as','project_files.compose'}: - if ((name in agent_api.PROJECT_FILES_M2 and not M2_ENABLED) - or (name in agent_api.PROJECT_FILES_M3 and not M3_ENABLED) - or (name in agent_api.PROJECT_FILES_M4 and not M4_ENABLED)): - raise WorkbenchError('This project capability is not yet available.', 'unavailable', 409) - self._bound(arguments, check_checkpoint=not operation['side_effects']) - from project_dispatch import dispatch - try: - value = dispatch(self._projection, name, arguments) - if (name=='project_files.measurement_compare' - and value['value']['observation_count']>agent_api.measurement_comparison_row_limit(selected_version)): - raise WorkbenchError('Comparison exceeds the selected API version observation budget. Select comparison contract version 2 for larger complete populations.', - 'too_large',413) - if name == 'project_files.execution_health' and selected_version == 1: - value = {key: item for key, item in value.items() if key != 'native_phases'} - except BaseException as error: - if getattr(error, 'code', None) in ('unknown', 'outcome_unknown', 'projection_unavailable'): - self._recovery_required('projection_unavailable', arguments.get('request_key')) - raise - snapshot = self._store.summary() - self._last_project = {key: snapshot[key] for key in ('project_id', 'name', 'checkpoint')} - result = dict(binding=self._binding, project_id=snapshot['project_id'], - checkpoint=snapshot['checkpoint'], value=value) - elif action == 'status': - result = self._state() - else: - # Lifecycle receipts are process-binding scoped. Domain edit - # receipts are canonical and survive any originating DB loss. - key = (name, arguments.get('binding'), arguments.get('request_key')) - signature = _digest(arguments) - prior = self._receipts.get(key) if arguments.get('request_key') else None - if prior is not None: - if prior[0] != signature: - raise WorkbenchError('Request key already has different input.', 'conflict', 409) - prior_state = prior[1]['state'] if action in ('save_as','compose') else prior[1] - if prior_state != self._state(): - raise WorkbenchError('This lifecycle receipt belongs to an obsolete workspace state.', 'stale_project', 409) - result = copy.deepcopy(prior[1]) - else: - try: - if action in ('new', 'open'): - result = self._select(action, arguments) - elif action == 'save': - self._bound(arguments) - self._store.save(arguments['expected_checkpoint']) - result = self._state() - elif action == 'save_as': - result = self._save_as(arguments) - elif action == 'compose': - result = self._compose(arguments) - elif action == 'close': - self._bound(arguments) - self._detach() - self._binding = uuid.uuid4().hex - result = self._state() - elif action == 'query': - self._bound(arguments) - value = self._text.records() - items = sorted(value['items'], key=lambda item: item['id']) - if arguments.get('after_id') is not None: - items = [item for item in items if item['id'] > arguments['after_id']] - page = items[:arguments.get('limit', 40)] - result = dict(binding=self._binding, project_id=value['project_id'], checkpoint=value['checkpoint'], - items=[{key: copy.deepcopy(item[key]) for key in SUMMARY_FIELDS} for item in page], - next_after_id=page[-1]['id'] if len(items) > len(page) else None) - elif action == 'get': - self._bound(arguments) - result = self._record_result(self._text.get(arguments['record_id']), - before_revision=arguments.get('before_revision'), history_limit=arguments.get('history_limit', 1)) - elif action in ('import_text', 'annotate'): - # Canonical domain receipts reconcile before CAS. - self._bound(arguments, check_checkpoint=False) - if action == 'import_text': - record = self._text.import_text(arguments['asset'], arguments['expected_checkpoint'], arguments['request_key']) - else: - record = self._text.annotate(arguments['record_id'], arguments['annotation'], - arguments['expected_checkpoint'], arguments['request_key']) - result = self._record_result(record) - else: - raise WorkbenchError('Unsupported project-file operation.', 'unsupported', 400) - except BaseException as error: - code = getattr(error, 'code', None) - if action not in ('save_as','compose') and code in ('unknown', 'outcome_unknown', 'projection_unavailable'): - reason = 'unknown_publication' if code in ('unknown', 'outcome_unknown') else 'projection_unavailable' - self._recovery_required(reason, arguments.get('request_key')) - raise - if arguments.get('request_key') and action in ('new', 'open', 'save', 'save_as', 'compose', 'close'): - self._receipts[key] = (signature, copy.deepcopy(result)) - if len(agent_api.encoded(result)) > agent_api.RESPONSE_LIMIT: - raise WorkbenchError('This project result exceeds the synchronous response bound; canonical work is retained.', - 'too_large', 413) - agent_api.validate_output(name, {'status': 200, 'result': result},version=selected_version) - return result - - def _dispatch_draining(self, name, arguments): - """Keep workspace selection pinned while descendants drain without SQL locks.""" - with self._mutex: - with self.access.lock: - self._ensure_open() - if not M3_ENABLED: - raise WorkbenchError('This project capability is not yet available.', 'unavailable', 409) - operation = agent_api.operation(name) - for scope in operation['scopes']: - self.access.require(scope, name, owner_only=name in _RECOVERY_OPERATIONS) - recovery_operation = name in _RECOVERY_OPERATIONS - if recovery_operation and self._projection is not None and not self._projection.session.available: - self._recovery_required('projection_unavailable', arguments.get('request_key')) - self._bound(arguments, check_checkpoint=recovery_operation and name != 'project_files.runtime_capture', - allow_recovery=recovery_operation) - projection = self._projection - recovering = self._recovery is not None or not projection.session.available - from project_dispatch import dispatch - try: - incoming = projection - if recovery_operation and projection.pending_original: - if len(projection.pending_original) != 1: - raise WorkbenchError('More than one original local custody binding needs explicit review.', - 'local_custody_unavailable', 409) - binding = projection.pending_original[0] - if binding['project_id'] != projection.session.project_id: - raise WorkbenchError('Restore the original project identity before reconciling this physical folder custody.', - 'local_custody_unavailable', 409) - if self._retained_recovery is None: - self._retained_recovery = self._retained_projection_for(self._store, binding['projection_id']) - incoming = self._retained_recovery - if incoming.db.projection_id != binding['projection_id']: - raise WorkbenchError('The retained physical recovery owner changed.', 'local_custody_unavailable', 409) - recovering = True - if incoming is not projection and name == 'project_files.execution_reconcile_current': - value = incoming.execution.reconcile_original(expected_checkpoint=incoming.session.summary['checkpoint']) - else: - internal = arguments - if recovery_operation and recovering and name != 'project_files.execution_reconcile_current': - # Public CAS above uses the last acknowledged workspace - # view. Only this qualified local owner sees its exact - # selected/attempted checkpoint for finite recovery. - internal = dict(arguments, expected_checkpoint=incoming.session.summary['checkpoint']) - if name == 'project_files.runtime_capture' and recovering: - options = {'reserve_bytes': internal['reserve_bytes']} if 'reserve_bytes' in internal else {} - value = incoming.runtime.recover_capture({'source': internal['source']}, - internal['expected_inventory_sha256'], internal['expected_checkpoint'], - internal['request_key'], **options) - else: - value = dispatch(incoming, name, internal) - if recovery_operation: - if not incoming.session.available or incoming.custody is not None and incoming.custody.has_pending: - raise WorkbenchError('Original writer custody remains unresolved.', 'outcome_unknown', 409) - if incoming is not projection: - incoming.execution.assert_quiescent() - projection.close() - projection = self._projection = incoming - self._text = incoming.text - self._retained_recovery = None - # Physical cache repair retains this same selected - # project and workspace generation; it is not Open. - except BaseException as error: - if getattr(error, 'code', None) in ('unknown', 'outcome_unknown', 'projection_unavailable'): - self._recovery_required('projection_unavailable', arguments.get('request_key')) - raise - with self.access.lock, projection.session.lock, projection.db.lock: - snapshot = self._store.summary() - self._last_project = {key: snapshot[key] for key in ('project_id', 'name', 'checkpoint')} - if name in _RECOVERY_OPERATIONS: - self._recovery = None - result = dict(binding=self._binding, project_id=snapshot['project_id'], - checkpoint=snapshot['checkpoint'], value=value) - if len(agent_api.encoded(result)) > agent_api.RESPONSE_LIMIT: - raise WorkbenchError('Project drainage result exceeds its response bound.', 'too_large', 413) - agent_api.validate_output(name, {'status': 200, 'result': result}) - return result - - def _execution_health(self, arguments, *, selected_version=None): - """Read only indexed current-local custody, including a fenced owner.""" - name='project_files.execution_health' - with self._mutex,self.access.lock: - self._ensure_open() - if not M3_ENABLED:raise WorkbenchError('This project capability is not yet available.','unavailable',409) - self.access.require('inspect',name) - if self._projection is not None and not self._projection.session.available: - self._recovery_required('projection_unavailable') - self._bound(dict(arguments,expected_checkpoint=arguments['checkpoint']),allow_recovery=True) - incoming=self._projection - if incoming.pending_original: - if len(incoming.pending_original)!=1 or incoming.pending_original[0]['project_id']!=incoming.session.project_id: - raise WorkbenchError('Original local custody requires its exact project identity.','local_custody_unavailable',409) - identity=incoming.pending_original[0]['projection_id'] - if self._retained_recovery is None: - self._retained_recovery=self._retained_projection_for(self._store,identity) - incoming=self._retained_recovery - if incoming.db.projection_id!=identity: - raise WorkbenchError('Original physical custody changed.','local_custody_unavailable',409) - value=incoming.execution.health(arguments.get('offset',0),arguments.get('limit',40)) - if selected_version==1:value={key:item for key,item in value.items() if key!='native_phases'} - result=dict(binding=self._binding,project_id=incoming.session.project_id, - checkpoint=arguments['checkpoint'],value=value) - if len(agent_api.encoded(result))>agent_api.RESPONSE_LIMIT: - raise WorkbenchError('Current custody health exceeds its response bound.','too_large',413) - agent_api.validate_output(name,dict(status=200,result=result),version=selected_version) - return result - - def close(self): - with self._mutex: - if self._closed: - return - # Shutdown always releases handles, including a stale/unknown store; - # actual local workers drain before any database handle is closed. - if self._projection is not None: - self._projection.execution.shutdown() - self._projection.close() - if self._store is not None: - self._store.close() - self._projection = self._text = self._store = None - for _path, fd in self._roots.values(): - os.close(fd) - self._roots.clear() - self.db.close() - self._closed = True diff --git a/retained_measurements.py b/retained_measurements.py deleted file mode 100644 index 4eefa6d5..00000000 --- a/retained_measurements.py +++ /dev/null @@ -1,479 +0,0 @@ -"""Finite retained scalar tables, exact source bindings and explicit missingness. - -This owner validates data representation and performs fixed selections/reductions. -Producers own metric definitions, comparison scope and scientific interpretation. -It reads no paths, runs no producer and grants no evidence/disclosure authority. -""" -import base64 -import binascii -import copy -from decimal import Decimal -import hashlib -import json -import math -import re -import struct - -from workbench import WorkbenchError - - -FORMAT = 'retained_measurements_v1' -MAX_BYTES = 32 * 1024 * 1024 -MAX_SOURCE_BYTES = 8 * 1024 * 1024 -MAX_SOURCE_TOTAL = 16 * 1024 * 1024 -MAX_RESPONSE_BYTES = 256 * 1024 -MAX_ROWS = 100000 -MAX_COMPARISON_SOURCES = 16 -MAX_COMPARISON_SUBJECTS = 256 -MAX_COMPARISON_BYTES = 128 * 1024 * 1024 -MAX_COMPARISON_ROWS = 250000 -STATES = ('measured', 'failed', 'unsupported', 'unavailable') -ID = re.compile(r'^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$') -SHA = re.compile(r'^[a-f0-9]{64}$') - - -def fail(message, code='invalid', status=400): - raise WorkbenchError('Retained measurements: ' + message, code, status) - - -def exact(value, fields): - if type(value) is not dict or set(value) != set(fields): - fail('Object fields differ from schema 1.') - - -def text(value, maximum=240): - if (type(value) is not str or not value.strip() or len(value) > maximum - or any(ord(c) < 32 or 127 <= ord(c) <= 159 for c in value)): - fail('Bounded nonempty display text required.') - try: - value.encode('utf-8') - except UnicodeError: - fail('Text must contain valid Unicode scalars.') - return value - - -def identifier(value): - if type(value) is not str or not ID.fullmatch(value): - fail('Invalid declared identity.') - return value - - -def number(value): - return (type(value) is int and abs(value) <= 2**53-1 - or type(value) is float and math.isfinite(value)) - - -def encode(value): - return json.dumps(value, sort_keys=True, separators=(',', ':'), ensure_ascii=False, allow_nan=False).encode('utf-8') - - -def digest(value): - return hashlib.sha256(encode(value)).hexdigest() - - -def decode(raw): - def pairs(items): - result = {} - for key, value in items: - if key in result: - fail('Duplicate JSON key.') - result[key] = value - return result - def floating(value): - result = float(value) - if not math.isfinite(result) or result == 0 and Decimal(value) != 0: - fail('JSON number exceeds finite binary64 range.') - return result - def constant(_value): - fail('Nonfinite JSON constants are unsupported.') - try: - value = json.loads(raw.decode('utf-8'), object_pairs_hook=pairs, - parse_float=floating, parse_constant=constant) - pending = [(value, 0)] - while pending: - item, depth = pending.pop() - if depth > 24: - fail('JSON nesting exceeds the supported bound.', 'too_large', 413) - if type(item) is dict: - pending.extend((v, depth+1) for v in item.values()) - for key in item: - key.encode('utf-8') - elif type(item) is list: - pending.extend((v, depth+1) for v in item) - elif type(item) is str: - item.encode('utf-8') - return value - except (ValueError, UnicodeError, RecursionError): - fail('Unique-key finite UTF-8 JSON required.') - - -def collection(values, maximum): - if type(values) is not list or not values: - fail('Nonempty declared collection required.') - if len(values) > maximum: - fail('Declared collection exceeds its supported bound.', 'too_large', 413) - result = {} - for value in values: - if type(value) is not dict: - fail('Declared entries must be objects.') - identity = identifier(value.get('id')) - if identity in result: - fail('Duplicate declared identity.') - result[identity] = value - return result - - -def cell(kind, value): - if value is None: - return True - if kind == 'string': - return type(value) is str and len(value) <= 256 - if kind == 'boolean': - return type(value) is bool - if kind == 'integer': - return type(value) is int and abs(value) <= 2**53-1 - return kind == 'number' and number(value) - - -class MeasurementTable: - """Own an immutable input snapshot; returned projections are independent.""" - def __init__(self, raw): - if type(raw) is not bytes or not 0 < len(raw) <= MAX_BYTES: - fail('A bounded complete byte snapshot is required.', 'too_large', 413) - self.sha256 = hashlib.sha256(raw).hexdigest() - self.bytes = len(raw) - doc = decode(raw) - exact(doc, ('format', 'schema_version', 'title', 'scope', 'dimensions', 'subjects', - 'cases', 'metrics', 'observations', 'sources')) - if doc['format'] != FORMAT or type(doc['schema_version']) is not int or doc['schema_version'] != 1: - fail('Unsupported measurement schema.', 'unsupported', 409) - text(doc['title']) - self._doc = doc - self._sources = collection(doc['sources'], 256) - self._json = {} - total = 0 - for identity, source in self._sources.items(): - exact(source, ('id', 'label', 'kind', 'bytes', 'sha256', 'data_base64')) - text(source['label']) - if source['kind'] not in ('json', 'opaque'): - fail('Unsupported retained source kind.', 'unsupported', 409) - if type(source['bytes']) is not int or not 0 < source['bytes'] <= MAX_SOURCE_BYTES: - fail('Source byte declaration exceeds its bound.', 'too_large', 413) - total += source['bytes'] - if total > MAX_SOURCE_TOTAL: - fail('Source collection exceeds its decoded byte bound.', 'too_large', 413) - if type(source['sha256']) is not str or not SHA.fullmatch(source['sha256']): - fail('Source requires an exact SHA256.') - value = source['data_base64'] - if type(value) is not str or len(value) != 4*((source['bytes']+2)//3): - fail('Source encoding differs from its byte declaration.') - try: - payload = base64.b64decode(value, validate=True) - except (ValueError, binascii.Error): - fail('Invalid source base64.') - if (len(payload) != source['bytes'] or hashlib.sha256(payload).hexdigest() != source['sha256'] - or base64.b64encode(payload).decode('ascii') != value): - fail('Retained source bytes differ from their declaration.') - if source['kind'] == 'json': - self._json[identity] = decode(payload) - scope = doc['scope'] - exact(scope, ('id', 'label', 'population', 'definition')) - identifier(scope['id']);text(scope['label']) - if scope['population'] not in ('training', 'consumed', 'independent', 'reserved', 'unknown'): - fail('Unsupported declared population.', 'unsupported', 409) - self._definition(scope, ('id', 'label', 'population')) - if type(doc['dimensions']) is not list or len(doc['dimensions']) > 32: - fail('Invalid dimension collection.') - self._dimensions = collection(doc['dimensions'], 32) if doc['dimensions'] else {} - for dimension in self._dimensions.values(): - exact(dimension, ('id', 'label', 'type', 'units', 'scope')) - text(dimension['label']) - if dimension['scope'] not in ('subject', 'case', 'observation'): - fail('Unsupported dimension owner.', 'unsupported', 409) - if dimension['type'] not in ('string', 'number', 'integer', 'boolean'): - fail('Unsupported dimension type.', 'unsupported', 409) - if dimension['units'] is not None: - text(dimension['units'], 120) - self._subjects = collection(doc['subjects'], MAX_ROWS) - self._cases = collection(doc['cases'], 4096) - self._metrics = collection(doc['metrics'], 32) - expected = len(self._subjects)*len(self._cases)*len(self._metrics) - if expected > MAX_ROWS: - fail('Complete subject/case/metric matrix exceeds its row bound.', 'too_large', 413) - for subject in self._subjects.values(): - exact(subject, ('id', 'label', 'dimensions', 'reference'));text(subject['label']);self._reference(subject['reference']) - self._dimension_values('subject',subject['dimensions']) - for case in self._cases.values(): - exact(case, ('id', 'dimensions', 'reference')) - self._dimension_values('case',case['dimensions']) - self._reference(case['reference']) - for metric in self._metrics.values(): - exact(metric, ('id', 'label', 'units', 'definition'));text(metric['label']);text(metric['units'], 120) - self._definition(metric, ('id', 'label', 'units')) - observations = doc['observations'] - if type(observations) is not list or len(observations) != expected: - fail('Every subject/case/metric needs one explicit result, including missing or failed results.') - self._observations = collection(observations, MAX_ROWS) - pairs = set() - for observation in observations: - exact(observation, ('id', 'subject_id', 'case_id', 'metric_id', 'state', 'value', 'reason', 'dimensions', 'reference')) - self._dimension_values('observation',observation['dimensions']) - identity = observation['subject_id'], observation['case_id'], observation['metric_id'] - for value in identity: - identifier(value) - if (identity in pairs or identity[0] not in self._subjects or identity[1] not in self._cases - or identity[2] not in self._metrics): - fail('Duplicate or unresolved measurement identity.') - pairs.add(identity) - if observation['state'] not in STATES: - fail('Unsupported observation state.', 'unsupported', 409) - source_value = self._reference(observation['reference']) - if observation['state'] == 'measured': - value = observation['value'] - if (not number(value) or not number(source_value) or observation['reason'] is not None - or struct.pack('!d', float(value)) != struct.pack('!d', float(source_value))): - fail('Measured scalar differs from its exact retained source value.') - else: - if observation['value'] is not None: - fail('Unmeasured results require an explicit null value.') - text(observation['reason'], 1000) - - def _dimension_values(self,scope,values): - columns={k:d for k,d in self._dimensions.items() if d['scope']==scope} - if type(values) is not dict or set(values)!=set(columns): - fail('Dimension values differ from their declared owner and columns.') - if any(not cell(columns[k]['type'],v) for k,v in values.items()): - fail('Dimension value differs from its declared type.') - - def _row_dimensions(self,row): - return {**self._subjects[row['subject_id']]['dimensions'], - **self._cases[row['case_id']]['dimensions'],**row['dimensions']} - - def _reference(self, reference, *, hashed=False): - exact(reference, ('source_id', 'pointer', 'sha256') if hashed else ('source_id', 'pointer')) - source = self._sources.get(identifier(reference['source_id'])) - if source is None: - fail('Source reference is unresolved.') - pointer = reference['pointer'] - if pointer is None and not hashed: - return None - if (type(pointer) is not str or len(pointer) > 512 or pointer and not pointer.startswith('/') - or re.search(r'~(?:[^01]|$)', pointer) or source['kind'] != 'json'): - fail('A bounded existing JSON pointer is required.') - value = self._json[source['id']] - try: - for part in pointer[1:].split('/') if pointer else (): - part = part.replace('~1', '/').replace('~0', '~') - if type(value) is dict: - value = value[part] - elif type(value) is list and re.fullmatch(r'0|[1-9][0-9]*', part): - value = value[int(part)] - else: - fail('Source pointer does not identify a retained value.') - except (KeyError, IndexError): - fail('Source pointer does not identify a retained value.') - if hashed and reference['sha256'] != digest(value): - fail('Declared definition digest differs from its retained source.') - return value - - def _definition(self, descriptor, fields): - value = self._reference(descriptor['definition'], hashed=True) - if type(value) is not dict or len(encode(value)) > 16384 or any(value.get(k) != descriptor[k] for k in fields): - fail('Definition metadata differs from its exact retained document.') - return value - - def metadata(self): - return copy.deepcopy({'format': FORMAT, 'packet_sha256': self.sha256, 'title': self._doc['title'], - 'scope': self._doc['scope'], 'scope_definition':self._definition(self._doc['scope'],('id','label','population')), - 'dimensions': self._doc['dimensions'], 'metrics': self._doc['metrics'], - 'subject_count':len(self._subjects),'case_count': len(self._cases), - 'observation_count': len(self._observations),'source_count':len(self._sources)}) - - def subjects(self, *, offset=0, limit=40): - if type(offset) is not int or not 0<=offset<=2**53-1 or type(limit) is not int or not 1<=limit<=40: - fail('Invalid subject page bounds.') - return copy.deepcopy({'items':list(self._subjects.values())[offset:offset+limit], - 'offset':offset,'limit':limit,'total':len(self._subjects)}) - - def query(self, metric_id, *, subject_ids=None, filters=None, offset=0, limit=50): - identifier(metric_id) - if metric_id not in self._metrics: - fail('Metric is unavailable.', 'not_found', 404) - selected = list(self._subjects) if subject_ids is None else subject_ids - if (type(selected) is not list or not selected or len(selected)>MAX_ROWS or any(type(v) is not str for v in selected) - or len(set(selected)) != len(selected) or any(v not in self._subjects for v in selected)): - fail('Choose existing unique subjects.') - filters = {} if filters is None else filters - if (type(filters) is not dict or any(k not in self._dimensions or not cell(self._dimensions[k]['type'],v) - for k,v in filters.items())): - fail('Filters must use declared dimensions and typed scalar values.') - if type(offset) is not int or not 0<=offset<=2**53-1 or type(limit) is not int or not 1<=limit<=100: - fail('Page bounds must be explicit finite integers.') - # One pass over observations; set membership and per-subject grouping - # replace the former subjects x rows rescans. Output is unchanged: - # rows keep packet order and ties keep the first maximal observation. - chosen = set(selected) - rows = [] - for v in self._doc['observations']: - if v['metric_id']!=metric_id or v['subject_id'] not in chosen: - continue - if filters: - dimensions = self._row_dimensions(v) - if not all(dimensions[k]==wanted for k,wanted in filters.items()): - continue - rows.append(v) - grouped = {identity:{'count':0,'states':{state:0 for state in STATES},'maximum':None} for identity in selected} - for v in rows: - own = grouped[v['subject_id']] - own['count'] += 1 - if v['state'] in own['states']: - own['states'][v['state']] += 1 - if v['state']=='measured' and (own['maximum'] is None or v['value'] > own['maximum']['value']): - own['maximum'] = v - summaries = [] - for identity in selected: - own = grouped[identity];maximum = own['maximum'] - summaries.append({'subject_id':identity,'count':own['count'],'states':own['states'], - 'maximum':None if maximum is None else {k:maximum[k] for k in ('id','case_id','value')}}) - result = {'format':'retained_measurement_query_v1','packet_sha256':self.sha256, - 'scope':copy.deepcopy(self._doc['scope']),'metric':copy.deepcopy(self._metrics[metric_id]), - 'scope_definition':copy.deepcopy(self._definition(self._doc['scope'],('id','label','population'))), - 'definition':copy.deepcopy(self._definition(self._metrics[metric_id],('id','label','units'))), - 'filters':copy.deepcopy(filters),'subject_ids':list(selected),'summary':summaries, - 'rows':[dict(copy.deepcopy(v),dimensions=copy.deepcopy(self._row_dimensions(v))) - for v in rows[offset:offset+limit]], - 'total':len(rows),'offset':offset,'limit':limit,'sampling':'none'} - if len(encode(result)) > MAX_RESPONSE_BYTES: - fail('Selected response exceeds its bound; choose a smaller page.', 'too_large', 413) - return result - - def inspect(self, observation_id): - identifier(observation_id) - observation = self._observations.get(observation_id) - if observation is None: - fail('Observation is unavailable.', 'not_found', 404) - reference = observation['reference'];source = self._sources[reference['source_id']] - return copy.deepcopy({'packet_sha256':self.sha256,'observation':observation, - 'case':self._cases[observation['case_id']],'subject':self._subjects[observation['subject_id']], - 'metric':self._metrics[observation['metric_id']],'scope':self._doc['scope'], - 'scope_definition':self._definition(self._doc['scope'],('id','label','population')), - 'case_evidence':self._inspection_reference(self._cases[observation['case_id']]['reference']), - 'scalar_evidence':self._inspection_reference(reference), - 'source':{k:v for k,v in source.items() if k!='data_base64'}}) - - def _inspection_reference(self,reference): - value=self._reference(reference) - state='opaque' if reference['pointer'] is None else 'included' - if state=='included' and len(encode(value))>16384: - state='exceeds_inspection_bound';value=None - return {'reference':copy.deepcopy(reference),'source_sha256':self._sources[reference['source_id']]['sha256'], - 'state':state,'value':value} - - -class MeasurementComparison: - """One bounded scientific comparison over immutable, source-bound tables. - - The native custody owner supplies validated locator/table pairs. Compatibility - depends on original definitions and actual case evidence, not display names. - Returned rows keep their packet locator; no observations or counts are pooled - across subjects. Pagination affects rows only, never the maximum denominator. - """ - def __init__(self, tables): - if type(tables) is not list or not 1 <= len(tables) <= MAX_COMPARISON_SOURCES: - fail('Choose 1 through 16 comparison sources.', 'too_large', 413) - self._tables = [] - self._subjects = {} - seen = set() - basis = None - observations = raw_bytes = 0 - for locator, table in tables: - exact(locator, ('origin_catalog_id', 'packet_sha256')) - if (type(locator['origin_catalog_id']) is not str - or not re.fullmatch('[a-f0-9]{32}', locator['origin_catalog_id']) - or not isinstance(table, MeasurementTable) or locator['packet_sha256'] != table.sha256): - fail('Comparison source differs from its validated packet.') - key = (locator['origin_catalog_id'], locator['packet_sha256']) - if key in seen: - fail('Comparison repeats a source.') - seen.add(key) - raw_bytes += table.bytes - if raw_bytes > MAX_COMPARISON_BYTES: - fail('Comparison exceeds 128 MiB of original packets.', 'too_large', 413) - metadata = table.metadata() - cases = [] - for case in table._cases.values(): - reference = case['reference'] - evidence = table._reference(reference) - cases.append(dict(id=case['id'], dimensions=case['dimensions'], evidence=evidence, - opaque_source_sha256=table._sources[reference['source_id']]['sha256'] - if reference['pointer'] is None else None)) - current = dict(scope=metadata['scope_definition'], dimensions=metadata['dimensions'], - metrics=[table._definition(metric, ('id','label','units')) for metric in table._metrics.values()], - cases=cases) - # Canonical source bytes distinguish Boolean/numeric values too; - # ordinary Python equality is not the scientific identity relation. - identity = digest(current) - if basis is None: - basis = identity - self._header = dict(format='retained_measurement_comparison_v1', - scope=metadata['scope'], scope_definition=metadata['scope_definition'], - dimensions=metadata['dimensions'], metrics=metadata['metrics'], - definition_source=copy.deepcopy(locator), case_population_sha256=digest(cases), - case_count=metadata['case_count']) - elif identity != basis: - fail('Comparison sources have different scope, metric, dimension or original case definitions.', 'incompatible', 409) - for subject in table._subjects.values(): - if subject['id'] in self._subjects: - fail('Comparison sources overlap a subject identity.', 'conflict', 409) - self._subjects[subject['id']] = dict(copy.deepcopy(subject), source=copy.deepcopy(locator)) - observations += metadata['observation_count'] - if len(self._subjects) > MAX_COMPARISON_SUBJECTS or observations > MAX_COMPARISON_ROWS: - fail('Comparison exceeds 256 subjects or 250,000 observations.', 'too_large', 413) - self._tables.append((copy.deepcopy(locator), table)) - self._header.update(subjects=list(self._subjects.values()), observation_count=observations) - - def read(self, metric_id=None, *, subject_ids=None, filters=None, offset=0, limit=50): - result = copy.deepcopy(self._header) - result['query'] = None - if metric_id is None: - if subject_ids is not None or filters is not None or offset != 0 or limit != 50: - fail('A comparison selection requires an explicit metric.') - return self._bounded(result) - selected = list(self._subjects) if subject_ids is None else subject_ids - if (type(selected) is not list or not selected - or any(type(value) is not str or value not in self._subjects for value in selected) - or len(set(selected)) != len(selected)): - fail('Choose existing unique comparison subjects.') - if type(offset) is not int or not 0 <= offset <= 2**53-1 or type(limit) is not int or not 1 <= limit <= 100: - fail('Comparison page bounds must be finite integers.') - summaries = {} - rows = [] - total = 0 - template = None - for locator, table in self._tables: - own = [identity for identity in selected if identity in table._subjects] - if not own: - continue - page = table.query(metric_id, subject_ids=own, filters=filters, offset=0, limit=1) - if template is None: - template = page - for summary in page['summary']: - summaries[summary['subject_id']] = dict(summary, source=copy.deepcopy(locator)) - start = max(0, offset-total) - if total+page['total'] > offset and len(rows) < limit: - current = table.query(metric_id, subject_ids=own, filters=filters, - offset=start, limit=limit-len(rows)) - rows.extend(dict(row, source=copy.deepcopy(locator)) for row in current['rows']) - total += page['total'] - metric = next(item for item in self._header['metrics'] if item['id'] == metric_id) - result['query'] = dict(metric=copy.deepcopy(metric), definition=template['definition'], - filters=template['filters'], subject_ids=list(selected), - summary=[summaries[identity] for identity in selected], rows=rows, - total=total, offset=offset, limit=limit, sampling='none') - return self._bounded(result) - - @staticmethod - def _bounded(value): - if len(encode(value)) > MAX_RESPONSE_BYTES: - fail('Comparison response exceeds its bound; choose fewer sources or a smaller page.', 'too_large', 413) - return value diff --git a/scripts/generate_project_files_contracts.py b/scripts/generate_project_files_contracts.py deleted file mode 100644 index ac373e53..00000000 --- a/scripts/generate_project_files_contracts.py +++ /dev/null @@ -1,35 +0,0 @@ -"""Derive installed browser pins/routes from the local canonical API registry.""" -import argparse -import json -from pathlib import Path -import re -import sys - -ROOT=Path(__file__).resolve().parents[1] -sys.path.insert(0,str(ROOT)) -import agent_api - - -def render(original): - names=sorted(name for name in agent_api._CONTRACTS if name.startswith('project_files.')) - tables={ - 'CONTRACTS':{name:agent_api.contract(name,1)['sha256'] for name in names}, - 'VERSIONS':{name:{str(v):agent_api.contract(name,v)['sha256'] for v in sorted(agent_api._CONTRACTS[name])} - for name in names if len(agent_api._CONTRACTS[name])>1}, - 'ROUTES':{name:{'method':agent_api.operation(name)['method'],'path':agent_api.operation(name)['path'], - 'mutation':agent_api.operation(name)['side_effects']} - for name in sorted(agent_api.PROJECT_FILES_M2|agent_api.PROJECT_FILES_M3|agent_api.PROJECT_FILES_M4)}} - for label,value in tables.items(): - pattern=r'(/\* PROJECT_FILES_'+label+r'_START \*/\s*)(.*?)(\s*/\* PROJECT_FILES_'+label+r'_END \*/)' - generated=json.dumps(value,sort_keys=True,indent=2) - original,count=re.subn(pattern,lambda m:m[1]+generated+m[3],original,flags=re.S) - if count!=1:raise ValueError('Exactly one installed '+label+' table required') - return original - - -if __name__=='__main__': - parser=argparse.ArgumentParser(description=__doc__);parser.add_argument('--check',action='store_true') - args=parser.parse_args();path=ROOT/'static/project-files.js';original=path.read_text();expected=render(original) - if args.check: - if original!=expected:raise SystemExit('Installed project-file browser contracts are stale') - elif original!=expected:path.write_text(expected) diff --git a/static/project-files.css b/static/project-files.css deleted file mode 100644 index c18e2e30..00000000 --- a/static/project-files.css +++ /dev/null @@ -1,22 +0,0 @@ -:root{font-family:system-ui,sans-serif;color:#1c2929;background:#f3f5ef;font-size:16px;line-height:1.5}*{box-sizing:border-box}body{margin:0}main{max-width:1200px;margin:auto;padding:2rem 1.5rem 4rem}header{max-width:800px;margin-bottom:2rem}h1{font-size:2.5rem;line-height:1.15;letter-spacing:-.04em}h2{margin-top:0}.eyebrow{font-size:.8rem;text-transform:uppercase;letter-spacing:.12em;color:#375957}section{padding:1.5rem;background:#fff;border:1px solid #c6d0c7;border-radius:12px}label{display:block;font-weight:600;margin:.75rem 0 .3rem}input,textarea,select,button{font:inherit}input,textarea,select{display:block;width:100%;margin-top:.3rem;padding:.6rem;border:1px solid #7d9288;border-radius:5px;color:inherit;background:#fff}textarea{resize:vertical}button{padding:.6rem .9rem;border:1px solid #315d52;border-radius:5px;background:#edf3ee;color:#183c32;cursor:pointer}button:hover:enabled{background:#dceae0}button:disabled{opacity:.55;cursor:default}button[aria-current=true]{background:#204f43;color:white}.actions{display:flex;flex-wrap:wrap;gap:.6rem;margin:1rem 0}.project-location{display:grid;grid-template-columns:1fr 2fr 2fr;gap:1rem}.workspace-grid{display:grid;grid-template-columns:1fr 1.2fr;gap:1.2rem;margin-top:1.5rem}.help{font-size:.9rem;color:#43564f;margin-top:.3rem}.scope{padding:1rem;border-left:4px solid #527467}fieldset{border:0;margin:0;padding:0}legend{font-weight:600}#records-list{padding:0;list-style:none}#records-list li{margin:.5rem 0}#records-list button{width:100%;text-align:left}#project-files-error{border:2px solid #9c2f29;background:#fff0eb;padding:1rem;color:#76241f}#project-files-status{min-height:1.5rem}#project-files-summary,#project-files-receipt,#project-files-error{overflow-wrap:anywhere}#record-history{padding-left:1.5rem}#record-history pre{white-space:pre-wrap;overflow-wrap:anywhere}#record-heading{scroll-margin-top:1rem}:focus-visible{outline:3px solid #b35208;outline-offset:3px}.skip-link{position:absolute;left:1rem;top:-5rem;padding:.7rem;background:white;z-index:3}.skip-link:focus{top:1rem}.session-bar{padding:.65rem 1.5rem;border-bottom:1px solid #c6d0c7;background:#fff}@media(max-width:760px){.workspace-grid,.project-location{grid-template-columns:1fr}main{padding:1.2rem .8rem}h1{font-size:2rem}section{padding:1rem}} - -.project-history-panel{margin-top:1.5rem}.project-fact-list{list-style:none;padding:0;max-height:42rem;overflow:auto}.project-fact-list>li{padding:.65rem 0;border-bottom:1px solid #dce4de}.project-fact-list button{width:100%;text-align:left}.project-facts{overflow-wrap:anywhere}.project-facts dl{margin:.4rem 0 .8rem;border-left:2px solid #dce4de;padding-left:.7rem}.project-facts dt{font-weight:600;text-transform:capitalize}.project-facts dd{margin:0 0 .6rem;white-space:pre-wrap;max-height:18rem;overflow:auto}.project-facts details{margin:.5rem 0}.project-facts summary{cursor:pointer;font-weight:600}.project-history-panel form{margin:1rem 0}.project-history-panel legend{padding-top:.5rem} -/* History rows share the detail viewer's hash wrapping and intrinsic width. */ -#project-detail-history-list{overflow-wrap:anywhere} -.check-row{display:flex;gap:.6rem;align-items:flex-start}.check-row input{width:auto;flex:none;margin-top:.35rem} - -#project-working-summary,#project-save-as-summary,#project-fork-summary,#project-working-list,#project-working-history-list,#project-fork-list,#project-intents-list,#project-intent-detail{overflow-wrap:anywhere;min-width:0}#project-intent-detail{white-space:pre-wrap;max-height:32rem;overflow:auto}#project-working-text{white-space:pre;overflow:auto} - -#project-runtime-files,#project-runtime-summary,#project-runtime-pending,#project-runtime-layout,#project-runtime-status{overflow-wrap:anywhere;min-width:0}#project-runtime-layout,#project-runtime-status{white-space:pre-wrap;max-height:32rem;overflow:auto} - -#project-candidate-preparation-result,#project-candidate-preparation-status{overflow-wrap:anywhere;min-width:0}#project-candidate-preparation-result{white-space:pre-wrap;max-height:32rem;overflow:auto} - -#project-portfolio-source,#project-portfolio-detail,#project-portfolio-count{overflow-wrap:anywhere;min-width:0} -#project-portfolio-detail p{white-space:pre-wrap;max-width:85ch} -#project-portfolio-detail pre{white-space:pre-wrap;overflow-wrap:anywhere;max-height:32rem;overflow:auto} -#project-portfolio-detail details{margin:1rem 0} -#project-portfolio-detail h4{margin-bottom:.25rem} -#project-portfolio-detail h3{scroll-margin-top:1rem} -#project-portfolio-filter-form{display:grid;grid-template-columns:1fr 2fr 1fr;gap:.7rem;align-items:end} -#project-portfolio-filter-form button{justify-self:start} -@media(max-width:760px){#project-portfolio-filter-form{grid-template-columns:1fr}} diff --git a/static/project-files.html b/static/project-files.html deleted file mode 100644 index 52f1ccca..00000000 --- a/static/project-files.html +++ /dev/null @@ -1,347 +0,0 @@ - - - - - - Projects · Tuldok - - - - - - - - - - - - - - - - - - - - -
    -
    -

    Tuldok / external projects

    Project workspace

    -

    Create or open a project folder to work with data, models and experiment history.

    -
    -

    Reading project status…

    - - -
    -

    Project file

    -

    No project status available.

    -
    - - - -
    -

    Use a relative directory within this root. New creates a new directory; Open reads an existing project. Close the current project before opening another.

    -
    - - - - - - -
    -

    No unsubmitted edits.

    -
    - -
    -

    Prepare a Candidate package or verifier

    -

    Choose a current Study, Candidate and captured CPU runtime. Preparation saves an inert Trial and exact sources; approval and Run admission remain separate actions.

    -
    Explicit Candidate preparation - - - - - - - -

    
    -      
    Resolve this installation's pending preparation -

    These actions require the original current local custody marker. Imported intent or completion history does not authorize reconciliation. Neither action deletes staging files or starts a Run.

    - - - - -
    -
    -
    -

    Capture a current CPU runtime

    -

    An operator configures the source aliases on this installation. Inspect the selected source, review its exact inventory, then explicitly capture it. These controls copy bytes without executing Python, installing packages or granting permission to run a project.

    - - - -

      -
      Capture reviewed inventory - - - -

      - -
      Abandon this installation's stopped partial capture -

      This requires its original current local custody marker. The decision preserves every partial file, retained intent and scientific fact; imported history does not authorize it.

      - - - -
      -
      Inspect retained capture facts - -

      This outcome is historical. “Captured” does not establish that a current local runtime is present or ready. Reopening a project does not capture or provision it.

      
      -    
      -
      -

      Save As an independent project

      -

      Use a new directory. Historical results keep their original identities; editable definitions receive new identities. Changed working files and unresolved current work must be resolved first.

      -
      - Fork destination - - - -

      -
      -
      -

      Scripts and notes

      -

      Inspect files already adopted into this project, or explicitly adopt exact current UTF-8 bytes. Captured scripts are displayed as text and never run by these controls.

      -
      -
        -
        Adopt current file bytes - - - - - -

        This picker calculates a digest in your browser. Adoption reads the existing file at the relative project path; it does not upload or replace it.

        -
        -
        Adopt a missing note as a deletion -

        Inspect and select a known missing note first. This action records its absence and keeps all captured revisions.

        - - -
        -

        Select a captured file revision

        -

        - -
          -
          -
          -

          Fork origins and bindings

          -
          -

              -

              Select an unresolved binding

              Review its original parameters and binding fields below. Recreate a current definition with the named model or graph controls; this history never rebinds or grants execution.

              -
              
              -    
              -

              Authored edits are saved to the project before acknowledgement. Historical materials and artifacts remain inspectable when payloads are missing. Execution requires explicit current local permission through available controls. Independent Save As and explicit working-file adoption are available when their negotiated controls are enabled. Migration remains unavailable.

              -
              -
              -

              Author text

              -
              - New text record - - - -

              Comma-separated group IDs; keep at least one. These preserve source grouping.

              - - -
              -

              Text records

              -
                - -
                -
                -

                Select a text record

                -

                - -

                Source text is immutable. Submit a new record to author different text.

                -
                - Annotation and human review - - - -

                Enter one classification label, up to 80 characters.

                - - - -
                -

                Saved annotation history

                -
                  - -
                  -
                  - - -
                  -

                  Project data and scientific history

                  -

                  Inspect saved records, models, Studies, Runs and their exact artifact availability. Opening a project never starts computation or restores permission to disclose held-out data.

                  -
                  - - - -
                  - -
                  -

                  -
                  -
                    -
                    -

                    Choose a saved record

                    - -
                    - -
                    -
                      - - - - - - - -
                      -
                      -
                      -
                      -

                      Add data and saved intent

                      -
                      -
                      Import an image or audio source - - - - - - -
                      -
                      Save the entered data search -

                      Save the search text and data kind entered above. This records intent; it does not freeze a dataset.

                      - -
                      -
                      -
                      -
                      -

                      Create a model definition

                      -

                      Choose an available template from this installation. Saving a definition and publishing its source material never start training.

                      - -
                      New model - -
                      -
                      -
                      -

                      Plan a Study

                      -

                      Save scientific selection criteria and finite budget metadata. Continue and admit prepared Trials explicitly through current Study execution controls when available.

                      -
                      New Study - - -

                      Use the exact saved metric definition from retained evidence. This does not create or infer a metric.

                      -
                      - -
                      - -
                      -
                      -
                      -

                      Import declared scientific data

                      -

                      Choose a local source manifest, then one declared data reference. Tuldok reads the exact existing bytes without executing project code.

                      -
                      Register a local source -

                      The local root selected at the top of this page applies.

                      - -
                      -
                      Import a declared reference - - -
                      -
                      -
                      -

                      Current local execution

                      -

                      Review the exact current recipe before granting permission. Approvals apply to this installation and actor. Saved historical admissions and approvals never restart execution when a project is opened.

                      -
                      -

                      -
                      Review current recipe - -
                      -
                      Approve reviewed material locally - - - - -
                      -
                      Start explicitly approved execution

                      No current local approval selected.

                      -
                      Cancel a current local Run
                      -
                      -
                      -

                      Current native CPU execution

                      -

                      These explicit owner actions use this installation's operator-selected Python environment. Installed packages remain operator trust; a successful probe does not establish model quality or a complete software closure. Opening saved history never probes or starts a Run.

                      - -
                      Validate with a current native probe - - - -
                      -
                      Start the validated native Run - - -
                      -
                      Retry a current native attempt - - - -
                      -
                      Reconcile an original current phase - - -
                      - -

                      Use “Refresh current custody” above to inspect original local phase IDs. Select a phase below, then explicitly reconcile it.

                        -

                        -
                        -
                        -

                        Current Study execution

                        -

                        Select a Study in the scientific history view, then load its current epoch and prepared Trials. Closing an epoch saves cancellation intent; it does not prove that its child processes have ceased.

                        -

                        -
                        Open a current epoch
                        - -
                        Approve this Trial locally
                        -
                        Admit a Trial under the current budget
                        -
                        Close the current epoch
                        -
                        -
                        -

                        Current model producers

                        -

                        These actions contact the model endpoint you choose now. Captured requests and results remain historical facts; opening them never contacts a model or resumes a queue.

                        -

                        -
                        Start an explicit model request - -

                        Select an image or text record in saved data first.

                        - - - - - - - - - -
                        -

                        -
                        Continue a current image queue
                        -
                        Review a caption or class proposal
                        -
                        Review a grounded candidate
                        -
                        Cancel this current local producer
                        -
                        -
                        - - diff --git a/static/project-files.js b/static/project-files.js deleted file mode 100644 index 3146719e..00000000 --- a/static/project-files.js +++ /dev/null @@ -1,1956 +0,0 @@ -'use strict'; -// One page owns this projection. The server owns project state and every edit. -(()=>{ - const $=id=>document.getElementById(id), base='/api/workspace/project-files'; - const actions=['new','open','save','close','query','get','import_text','annotate']; - const tasks=['text_classification','text_entities','text_corpus']; - // Generated from agent_api; freshness is checked by the client contract tests. - const pins = /* PROJECT_FILES_CONTRACTS_START */ -{ - "project_files.annotate": "70feae2ad14c49c4ae95b5bb69b4a50fbf93191cde840544cf89b6cbe8dc5c58", - "project_files.artifact_resolve": "0df477e294b4e0729a707d7dfb6038414fc354e1ae50155eaacfa82b3a55f51f", - "project_files.artifact_status": "8dd0343f5f882c96cf023f8274734ca57175ae986e82b3bb1188cb5864784834", - "project_files.artifacts": "20a4031d189058721d09b8bf694ea9b1583eea410afd381f58fe6c70d0a0c339", - "project_files.candidate": "c519ff04bc06d5e538d36b7f278862d8f282d0e7b97dd7f262444c384a50f854", - "project_files.candidate_select": "f043be6923760a208ca50d02a1ff4b60eadf09d48a034acdb18749806a537080", - "project_files.close": "95d0099ec2a378a1bbb65676799dd3baae2f36b838301f7aa165b116fba5edf6", - "project_files.compose": "b1dcbbd4ad7ebe17b17e11238f99a93408da24d0d411527e187900cc0f089105", - "project_files.data_annotate": "289270f5cb946765c5ced22fbbd18765bb55743145014c81cf54d7a6ba3025ea", - "project_files.data_availability": "92332c04973a4fa45d47e384717152ebc4a9ca08e7eb487669688ccd2ed42cbb", - "project_files.data_get": "0d19505995cbd8c12e3938cd89cf05955a2a63488a220711d29dd24b27c0c8c8", - "project_files.data_history": "b9e9e13389befe5f531d33d4d4d893649cb076f3eff98aa6ee85a4c46f03148a", - "project_files.data_import_audio": "51b511a068bed6ec024bd70bf08a48a23a94906362d54e0f3eb1223e325c237e", - "project_files.data_import_image": "e9f86ce62d29d267090c7955e0deb084f6ad6a936d1418baf5d807aa6d84ea3e", - "project_files.data_import_mesh": "840d6e1d6ab326d144b63e275d60d304277b5d4867c9c170c6dde5e117b46107", - "project_files.data_import_pointcloud": "c171b1342a5844fc1862947e20ae675395b8c3e24b44bff1179e0e8e6df70f53", - "project_files.data_import_scientific": "a39ce46384bb2f0c3cdb9a6bbf881316ce166a26208fc41b4a88bb307af32d63", - "project_files.data_import_sequence": "da8b91c9fd76d951fddc33acf6cca56287e0d7a29319b46032629b777af1f1ee", - "project_files.data_import_text": "c2db90c749154cb5489e13494d5a4404fdaf5a14895679fe2075fdfdc39e899d", - "project_files.data_import_volume": "c6e509d797970afd7da9e2069c29736e290ada8e7034326b31e1cb707aa572e2", - "project_files.data_preference_delete": "900538c7d8f74f04ed93387a864c8235b4162902345f6864b8d325527f63da5f", - "project_files.data_preference_history": "5ee7d60ce5e4aa09ea3496e9212b3404820d619cc2d47425faa94a3506d9ad07", - "project_files.data_preference_save": "eacdaa8b32cac556f8a591c4ca3f1191d83182623bd425a5619e1c6920c17782", - "project_files.data_preferences": "35b9bff0cba8bf453d446a8b62a6d003cc49f6abb8a12b55bfb76a112c3f2067", - "project_files.data_query": "0a7585ed5c41ed28eee2505e95773741a7af82c74b5265b8ed4ebf2beb72e394", - "project_files.data_response_history": "1bd46a162efae7213ff7c8a7b77dfe843e952a629fd7c24af3b5298e04140224", - "project_files.data_response_save": "fa5b92afe529520fe8206d629bd88085a68f4f9b399cd40dd05fd3948d3592f0", - "project_files.data_responses": "3e0c009244cad04fca4356cf3647bfd2b42cfc0d6a2ac31bb8de25cdb3c60ec8", - "project_files.data_rights": "ead16cca68b03533daa81bf06148e1918ce40dbc823ee060bd9908581f788653", - "project_files.data_scientific": "c954a680440fdb822a0f895f7e14b90e05dca82535478b1271dfb33cfbfdada9", - "project_files.data_source_delete": "457618e618cca92a71b668ffb9f68b0db87e51c417c2e5f41dcde76d71a23985", - "project_files.data_source_save": "0d50c45d445b2ce1014a696c3bc95965f0b548ded939f4a650f985f34e1ce849", - "project_files.definitions": "3516fcf8764382780c7da699218a05ff1f811634656cc81722ef547f21159698", - "project_files.dependencies": "615e173c6e7cb811dc5e51ef6c368975b4dd06de14d6cf69fbd8c4bb01e3f9e4", - "project_files.evidence": "440d7dba608d633a4a42479018360ef2fa6609a47148e7edfdf5246f84c020ef", - "project_files.execution_approve_external": "b35cec1a8bc5faad9e437ee04b6fb3bc9d575e8b7c4dd0444401fa8f551fa301", - "project_files.execution_cancel": "5fff1a68bfaeefcf426c573f4f128e76c96163171f31580922be3178080ffcd0", - "project_files.execution_generation_resume": "cfadef988f4510fcea1e64e1a8a4ca60794bec26a2d1c116b35e678971cc33ae", - "project_files.execution_grounded_review": "de971104eebe46acb67edfb77f1c0df98e8302528ef446ad51c772c13e67458b", - "project_files.execution_health": "c3b1d0017f5a49cf69c3a4c5c33e1d3db9846404d12627563d97ef40de7404a5", - "project_files.execution_preflight_external": "f754d712ac7da823375408fbcec63f7006c972a6e0885d69bae6772f2b850fea", - "project_files.execution_producer_cancel": "af114f7ed941f80ec565577863a6fffc4ec1c7d7069af6715350e8489526fd61", - "project_files.execution_producer_decide": "38bd7d1a1a052d62f6fc74cc16fcaf9e3c243f97dc3c39e38cdef03ca272a5d8", - "project_files.execution_producer_health": "297c6160a07cef60a8d4a50a690805f30a75b7e1bf6543e6da3a7befcb133b7e", - "project_files.execution_producer_start": "e7ee70a06346026980ba0fbf808b6d61ff3e7ac57a6619d72cd1b8b77e9662f7", - "project_files.execution_reconcile_current": "5ed3f998f053fd6333804e604f758c58e1b862c6f92f4de4272495916cef77de", - "project_files.execution_study_abandon_preparation": "650e7f85ea3ff476448422077ecc51fc06e270e975967886d5a6c726aee5af73", - "project_files.execution_study_admit": "381cacfa7582db321520cbc0d0e0be6bd187e1e3ff98cdbde371244b5994adba", - "project_files.execution_study_approve": "0a49e0d1b8e789a96969b73565f127d5cbb2c6cc39fea40fff33029f2ddbd7e2", - "project_files.execution_study_continue": "d421a59a95fb2a6b8d4e65d652000a13177054d34bafff3d0a3e30eeae00fb75", - "project_files.execution_study_prepare_package": "6687819b4cad1fa89ca1ec874422ea04f52cbc3685691dc3c612f122933c89b2", - "project_files.execution_study_prepare_verifier": "1c28024ab764c1f5747f17b90e73a95fb1666be4f94af040f376ec6241e12421", - "project_files.execution_study_reconcile_preparation": "c5a301fd6e3159de684f5700d557ccd13dd704e617d4779015e9b5ca93d76075", - "project_files.execution_study_stop": "84d103019c80b8e7bd3b59e0259c3947de4f4f48cc05c3076cf16112d8671911", - "project_files.execution_submit_external": "fc33d4eac346c1f08423ccb5d593db43b561124629d53f2a8896ff9838db99f3", - "project_files.expose_holdout": "d69478ed54267ee1f1966f423f412a32f90b95a55997c6dc7d8348e3cdd78fd7", - "project_files.file_adopt": "a190326d5c54296f8359be594996908fa28acbbd125168821c3fa1f520ef9b07", - "project_files.file_adopt_deletion": "7b6d661856a614d1b83d8011d1ffc7f9e2619853495faf9250888739f880685c", - "project_files.file_get": "a22c27e2fd890ffcb479e0aa8ea40a0cb32d06d1e5750b970b40f27915fe4d24", - "project_files.file_history": "c83477f7b0f8616c96ad79cebaf0eb3887fe289567f5d5ceb1d1502bebed7423", - "project_files.files_adopt": "62215260bf40bfa5db2521f908413bb6dfe47656fb8ea30b38039d637e5daf51", - "project_files.files_inspect": "0c2ff3ed93109ea19b5c92ffa24ac8f67e4bcfa3fe386921e984b5dfa3bfe7eb", - "project_files.fork_info": "958bc1aa269b5459c7e2d9c6bcb6725c06f7055502d73c49a95330cc4065aea4", - "project_files.get": "6b0f4e16a00aa119b86cbb5493be0bac945ff08a5e63773a8f2c2f9296658d5b", - "project_files.graph_clone": "8f9b460530f0f136900734345fc338a1993ffdaddf5f4d90faf352c39f397514", - "project_files.graph_create": "8fcb6d573b849ac03b5ee0ae192f274c11b9b5303451410ee46013f4cb0d83dc", - "project_files.graph_create_external": "93d88731f66062c9d0ac15d38897e731e25e39df7f9b141e5f3277f2d07b4205", - "project_files.graph_get": "77eea46e63758f0ca172cd23595cf5a42fe9820dbc82f3aefb7f5b6c22dc23d9", - "project_files.graph_save": "5a9745e4041cda6be46f63b83cb1f89d102d10c8810e41261a326cf0ef6821f4", - "project_files.graphs": "4892c990da89bc193d408537761e2e2db19694840ee652e64cba64a3bf57dbdb", - "project_files.import_text": "0f168320abb858892a2724b0b59862475bec653d1670ce754d61f2d82c912538", - "project_files.lineage": "750c173b42b113b6b82542fe4d82f8652cf07e1efe5cafde4c3e776d6afc3683", - "project_files.lineage_record": "16fd6cbd20bcd3743e4ac889dc6c398e714152f57d3c65cbd013f047c4267708", - "project_files.material_intent": "79d1ee6c3d8bc1313f2e51ff1d7d4ea489f5f3e82a6fd2e00ed93e1f7613bfbd", - "project_files.material_intent_capabilities": "86e90e2d0f094beb1c277a680da9a35e28d78c827390ac1c4e51fc3003c1ce32", - "project_files.material_intents": "6431fd2780d706c77d2c4dd82f15794017368fd3bade28ac62bbdff5c8b0c547", - "project_files.materials": "92a6a6a1750fed89aef9574ab6e82be2c6c6351bfa89fbfcb1f3866d4ea3cb13", - "project_files.measurement_compare": "abbb5e406a3c95155e90f08e8a071f330425190b25275f0f6512de08b8afb929", - "project_files.measurement_import": "c8e500396138fc60a31fc916c441bb95454f410231a6508609a7ebba5cd31f18", - "project_files.measurement_inspect": "fcbe9846ca49c3da4713b54a3cb4a8237189d8eea5799f275d33992ef268914f", - "project_files.measurement_metadata": "5a92ed5259f8876a3c5b8fd1886a9e0f44f0aea8e53d7f63902ac765ddac0de7", - "project_files.measurement_query": "65b1456a6870dd6d4b7499669777a2c66157142ccc27cac1864a995664220e1c", - "project_files.measurement_sources": "7805e9c5a6b2e2ab566ca134c18697116c89e08a1991b5192b0b5c152a34041d", - "project_files.measurement_subjects": "37bd3f717c7158e34b9c221bfa1dbce79490b9d55248803d13dab2ea17b35ea5", - "project_files.model_create": "34cf790fb2a3355ccab7c3a6c7174ced8dae861812d9479582fd8d5a9212745c", - "project_files.model_get": "95cc198ab6f084b596324f7251803ad4670a9f8e786e1a9639f1b9ed041798c3", - "project_files.model_material": "46afde2b06e0e5b08565f12ec86d2d7ec43ef6b63d97c86c264fc9c2f451f20b", - "project_files.model_publish": "97c0ec706fd663d322764a2dd72bd920e7e7ac8defaee2d23624502ed239fc62", - "project_files.model_save": "a90f8d985578191dee672824c9178559452f8b0dd759f74ed91337a96ca670e8", - "project_files.models": "92e13621050d7f229a4785ed6845df2f191a9e037bcdf377fa7fb0ba796aebe3", - "project_files.native_preflight": "494c907dac56a3126d26f064ec20bb980f918bded8e7f727c1fdaaa118059b13", - "project_files.native_reconcile": "74299207459fbd08d23ad7e8c1db205a4297f014415fd463c9857ba60dda4c7e", - "project_files.native_retry": "489655b49dadc184d95d6455ad2662bd5e7fd2cde2170fd303a92b2de77471c1", - "project_files.native_submit": "82468f35f04306fd4f39a0cc94a487fc05ae739e28f24f0be49ed35644639643", - "project_files.new": "672373f8ddc0b89fea15165798aab97cf4ac2cdf678a04d96839512cc8976b6f", - "project_files.open": "fd4b9f97c03cd7050981cfafd1177bff8c86351bb603b8f7980aaa149d2b0368", - "project_files.package_state": "6f0369eafab3b8ed1db71ffb12e7d5a2bbcf400b46315d46ba1e2fb13e63baf7", - "project_files.policies": "629b61ae9bd9c65d04cd3e89fb50fb62dd455b9f75bcaf9db08b7890bb5516f5", - "project_files.policy": "5bdb86600f2ec387fde721b22fdd0afa3ed47660126847c2908c1bb9de0421cb", - "project_files.producer": "6187a9eb1e32cb3bcf13d283492b1ad909c32753aa5ed97fbc12a9708523d9e3", - "project_files.producers": "65b2f4dff355c3bf5a023bf4f9dc116e302eda85ad90e6afaa2f21f0aa0667b5", - "project_files.progression": "4b70964ce2509f3526b2915cb5bd1ec086f7f553d82d8cf43c87d524cc3db7f3", - "project_files.progression_origins": "380b9ae9931faf5f161bcbd0e689dd93525be22ae2d9b00a524ce48d377d8c95", - "project_files.publication_result": "10b4a5f3d4f37343322327024ddbedf5b6b69672c785e208ec48534d7b40c867", - "project_files.query": "9a8b0d3a99adf5d7d53b62261dfac83e8b3ea44c10cb2f6c7a9c3d79422fef08", - "project_files.recipe_create": "53a6760f03675d4d8a8d3a0ffd5b56689975667bbc136b1edf8a206307c18651", - "project_files.recipe_get": "23837c51032b7c7ae6a365616f66cab9ae0d191108027291ad49898b2c421e2a", - "project_files.recipe_material": "c384acbf2333d7dd360991d72c8e1e218dc3ad3291af76e09f76efe25ea69cc0", - "project_files.recipe_prepare": "e91344f3032bf3e6abf50e5f5399252439498bce999c1f732322fd70a5eda1cf", - "project_files.recipe_save": "7fb9708aaba280ae437ee2554ecdaef3f724f3a7f4e55b49e54e1ef186691a7e", - "project_files.recipes": "3217c2033f60242c661c6689d6f9f634ea9d3a9b188a9465edcdc0bea572bc6c", - "project_files.release_freeze": "93a1b5b3c6bf11f63c92571113ce536743e7fd07b0b77ae8aee6e909230245df", - "project_files.release_preview": "0b6e2f0c2d7e3503fa29391fc20d27f058d0d3ad61e4547aee9845633ba6c5d8", - "project_files.retained_analysis": "05959a0e49a623318d6d70ded4f86df5df5d9bf29c411fcfcd1d9c0148b650cc", - "project_files.retained_analysis_export": "fa5d97e094484da053a1374131040deefdac429ec8360d671f57b12353d69359", - "project_files.run": "3cd94d46587596c36da4d1187b4648442cf6f216d2972daa496b7879e294ddec", - "project_files.run_document_segment": "bd6599cb89b106ba0be4141fc5d38ad5e07b2c57c5b24e1fcf91802ba9ff9006", - "project_files.runs": "cab46b11c5376ba641a717ceb1ce2bbe3693b7ac264e41192849f8522eb5d61d", - "project_files.runtime_abandon": "21086c2a92f23a8d42085678a7b99a69897bacb5e84341d482b0d2e9d6b69df8", - "project_files.runtime_capture": "2d787e49e7f911820d4341b33b4738219fa773a783bb2fb5a674d05dbfbb173a", - "project_files.runtime_inspect": "ece28c002151d36b9a415d4b7692536318765d1a7f742e3fd1f60c53b3a28204", - "project_files.runtime_material": "da48c927442878373434e93bb97fc65fc7056bd8e5a4b97e8a18627eb768cb07", - "project_files.runtime_sources": "6b94cbb5c712fbbea5645cbb64f8fd8b7f72c28042ddeacd96aaaad828a81460", - "project_files.runtime_status": "80931340bab620ca52c05277bc0380c97b7e9191a808312caedabc30f4ab7e96", - "project_files.save": "38572e376db36f81582dc6419fded35ff9d7c9185f5af2cdaafd74c94790f90a", - "project_files.save_as": "2b0558049ca0055a9682bcda6eb81ce9f48358b7cf804b5d499067a5594e2d33", - "project_files.search_create": "ae5c51158d849cda199cc007c42ea7a1cb62cd15a7ca8957bd32df813548e942", - "project_files.search_delete": "518037dbe9464fd327df53f7801a3c1ba30bb822467c091a2bc684542a58495c", - "project_files.search_rename": "78ca2aed2cd34c278ee1a9858dc76ebf8d39111de36bd48ada43f0407af5ff70", - "project_files.searches": "061be81df13158c18c2a124419da07db9564b44c239c8ca80cbf65a7ad26c1bd", - "project_files.selection_create": "87f60aeb83a497e7c6adab524f3ddc4776a6820497aa676f50ab3e1104b62ba2", - "project_files.selection_delete": "cb021e6e1d7b4df1db1e4ca614067c3b26820737eca92dbc7168b3ff45b0894f", - "project_files.selection_get": "c99e320815d54b60d0ddb3179a0ee62fa5eca938ac71011813296ce93bb085b0", - "project_files.selection_rename": "7e3fe9853cc593e4c0464162b3c9137208500650a125a46704f1e38d49b6f5a1", - "project_files.selections": "fd9cc6a94144a349232e99aa1ad4890cb7cb4b023de8bf4e8249374aa29ec39d", - "project_files.snapshot": "1eacdfeb7843bc432d62c6a94890dc07f618074faecb5e22589df9c9377e5030", - "project_files.source_references": "36a6d5b97efd63268d393b456e3bfec45cc696335acf652eff503b64a4ca0869", - "project_files.source_register": "04390ea427cb9958f5a0a1118de5cf8f91434d12e9c241621cf11465d804c64e", - "project_files.status": "1d0c4b64caaab8369d4addefd72e53cc8c7d0be4c07729fa04b358febe643b6a", - "project_files.studies": "5c45e0938cef51c271d1e82b28e878bc831f5a9272773440e39022074e6e87b6", - "project_files.study": "b268a20042efe9c8bc260f74309688dc7bbbd60486d30a33621a68e1a92fa3d7", - "project_files.study_create": "8d2aac7c073a6a7b3ebb41227b5b466cf03606625404f93a59b325038a4ad7a1", - "project_files.study_save": "5bf3fb814588fd7d9c35836e9d964a64481b3cc4169caf76cad6ce776ff0fe15", - "project_files.trial": "79afa4bed6d0907f3d4116cc04cb784e94e5a24ab89725ec24f5d7bce70e869f", - "project_files.trial_prepare": "e1f6973536fd4c356c4a92fc674d6766f7df0d8a113b8ee71bb05d0adc40b04f" -} -/* PROJECT_FILES_CONTRACTS_END */; - // Generated fixed operation routes from agent_api; remote schemas are never executed. - const versionPins = /* PROJECT_FILES_VERSIONS_START */ -{ - "project_files.annotate": { - "1": "70feae2ad14c49c4ae95b5bb69b4a50fbf93191cde840544cf89b6cbe8dc5c58", - "2": "2ae39dd621161500061bc8f57bb465e90fed04cfaf921e0dc368f82bd50cd107" - }, - "project_files.execution_health": { - "1": "c3b1d0017f5a49cf69c3a4c5c33e1d3db9846404d12627563d97ef40de7404a5", - "2": "6b7a834881da36960c0a0ee393c0c26e0d918b857d30791e8e5af79c2ae4a73e" - }, - "project_files.get": { - "1": "6b0f4e16a00aa119b86cbb5493be0bac945ff08a5e63773a8f2c2f9296658d5b", - "2": "fdc0858fc03a0866bb743b04251ea5f9a3c1e6be1b211366db7e0652166736ea" - }, - "project_files.measurement_compare": { - "1": "abbb5e406a3c95155e90f08e8a071f330425190b25275f0f6512de08b8afb929", - "2": "d2de9763a9109d0e4599f50e038a3fda0e6bf7c9c60684434825d0108019bc6f" - } -} -/* PROJECT_FILES_VERSIONS_END */; - let selectedVersions=new Map(); - const selectedHeader=operation=>operation+'/'+selectedVersions.get(operation)+'/'+(versionPins[operation]?.[selectedVersions.get(operation)]??pins[operation]); - const m2Operations = /* PROJECT_FILES_ROUTES_START */ -{ - "project_files.artifact_resolve": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/artifacts/resolve" - }, - "project_files.artifact_status": { - "method": "POST", - "mutation": false, - "path": "/api/workspace/project-files/artifacts/status" - }, - "project_files.artifacts": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/artifacts" - }, - "project_files.candidate": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/candidates/{candidate_id}" - }, - "project_files.candidate_select": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/studies/{study_id}/candidates" - }, - "project_files.compose": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/compose" - }, - "project_files.data_annotate": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/data/{record_id}" - }, - "project_files.data_availability": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/data/{record_id}/availability" - }, - "project_files.data_get": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/data/{record_id}" - }, - "project_files.data_history": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/data/{record_id}/history" - }, - "project_files.data_import_audio": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/data/import-audio" - }, - "project_files.data_import_image": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/data/import-image" - }, - "project_files.data_import_mesh": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/data/import-mesh" - }, - "project_files.data_import_pointcloud": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/data/import-pointcloud" - }, - "project_files.data_import_scientific": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/data/import-scientific" - }, - "project_files.data_import_sequence": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/data/import-sequence" - }, - "project_files.data_import_text": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/data/import-text" - }, - "project_files.data_import_volume": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/data/import-volume" - }, - "project_files.data_preference_delete": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/preferences/delete" - }, - "project_files.data_preference_history": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/data/{record_id}/preference-history" - }, - "project_files.data_preference_save": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/preferences" - }, - "project_files.data_preferences": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/data/{record_id}/preferences" - }, - "project_files.data_query": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/data" - }, - "project_files.data_response_history": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/data/{record_id}/response-history" - }, - "project_files.data_response_save": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/responses" - }, - "project_files.data_responses": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/data/{record_id}/responses" - }, - "project_files.data_rights": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/data/{record_id}/rights" - }, - "project_files.data_scientific": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/data/{record_id}/scientific" - }, - "project_files.data_source_delete": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/data/{record_id}/source/delete" - }, - "project_files.data_source_save": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/data/{record_id}/source" - }, - "project_files.definitions": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/definitions" - }, - "project_files.dependencies": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/runs/{run_id}/dependencies" - }, - "project_files.evidence": { - "method": "POST", - "mutation": false, - "path": "/api/workspace/project-files/runs/{run_id}/evidence" - }, - "project_files.execution_approve_external": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/execution/approvals" - }, - "project_files.execution_cancel": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/execution/runs/{run_id}/cancel" - }, - "project_files.execution_generation_resume": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/execution/generation/{producer_id}/resume" - }, - "project_files.execution_grounded_review": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/execution/grounded/{producer_id}/review" - }, - "project_files.execution_health": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/execution" - }, - "project_files.execution_preflight_external": { - "method": "POST", - "mutation": false, - "path": "/api/workspace/project-files/execution/preflight" - }, - "project_files.execution_producer_cancel": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/execution/producers/{producer_id}/cancel" - }, - "project_files.execution_producer_decide": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/execution/producers/{producer_id}/decide" - }, - "project_files.execution_producer_health": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/execution/producers/health" - }, - "project_files.execution_producer_start": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/execution/producers" - }, - "project_files.execution_reconcile_current": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/execution/reconcile-current" - }, - "project_files.execution_study_abandon_preparation": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/execution/studies/{study_id}/preparations/abandon" - }, - "project_files.execution_study_admit": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/execution/studies/{study_id}/runs" - }, - "project_files.execution_study_approve": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/execution/studies/{study_id}/approvals" - }, - "project_files.execution_study_continue": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/execution/studies/{study_id}/continue" - }, - "project_files.execution_study_prepare_package": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/execution/studies/{study_id}/packages" - }, - "project_files.execution_study_prepare_verifier": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/execution/studies/{study_id}/verifiers" - }, - "project_files.execution_study_reconcile_preparation": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/execution/studies/{study_id}/preparations/reconcile" - }, - "project_files.execution_study_stop": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/execution/studies/{study_id}/stop" - }, - "project_files.execution_submit_external": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/execution/runs" - }, - "project_files.expose_holdout": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/runs/{run_id}/disclose" - }, - "project_files.file_adopt": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/files/adopt" - }, - "project_files.file_adopt_deletion": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/files/adopt-deletion" - }, - "project_files.file_get": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/files/{file_id}" - }, - "project_files.file_history": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/files/{file_id}/history" - }, - "project_files.files_adopt": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/files/adopt-many" - }, - "project_files.files_inspect": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/files" - }, - "project_files.fork_info": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/fork" - }, - "project_files.graph_clone": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/graphs/{graph_id}/clone" - }, - "project_files.graph_create": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/graphs" - }, - "project_files.graph_create_external": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/graphs/external" - }, - "project_files.graph_get": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/graphs/{graph_id}" - }, - "project_files.graph_save": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/graphs/{graph_id}" - }, - "project_files.graphs": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/graphs" - }, - "project_files.lineage": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/lineage" - }, - "project_files.lineage_record": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/lineage" - }, - "project_files.material_intent": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/material-intents/{family}/{definition_id}" - }, - "project_files.material_intent_capabilities": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/material-intents/capabilities" - }, - "project_files.material_intents": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/material-intents" - }, - "project_files.materials": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/materials" - }, - "project_files.measurement_compare": { - "method": "POST", - "mutation": false, - "path": "/api/workspace/project-files/measurements/compare" - }, - "project_files.measurement_import": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/measurements/import" - }, - "project_files.measurement_inspect": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/measurements/{packet_sha256}/observations/{observation_id}" - }, - "project_files.measurement_metadata": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/measurements/{packet_sha256}" - }, - "project_files.measurement_query": { - "method": "POST", - "mutation": false, - "path": "/api/workspace/project-files/measurements/{packet_sha256}/query" - }, - "project_files.measurement_sources": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/measurements" - }, - "project_files.measurement_subjects": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/measurements/{packet_sha256}/subjects" - }, - "project_files.model_create": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/models" - }, - "project_files.model_get": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/models/{model_id}" - }, - "project_files.model_material": { - "method": "POST", - "mutation": false, - "path": "/api/workspace/project-files/materials/model" - }, - "project_files.model_publish": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/models/{model_id}/publish" - }, - "project_files.model_save": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/models/{model_id}" - }, - "project_files.models": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/models" - }, - "project_files.native_preflight": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/execution/native/preflight" - }, - "project_files.native_reconcile": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/execution/native/phases/{phase_id}/reconcile" - }, - "project_files.native_retry": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/execution/native/runs/{run_id}/retry" - }, - "project_files.native_submit": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/execution/native/runs" - }, - "project_files.package_state": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/candidates/{candidate_id}/package-state" - }, - "project_files.policies": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/policies" - }, - "project_files.policy": { - "method": "POST", - "mutation": false, - "path": "/api/workspace/project-files/policies/get" - }, - "project_files.producer": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/producers/{origin_catalog_id}/{producer_id}" - }, - "project_files.producers": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/producers" - }, - "project_files.progression": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/progression" - }, - "project_files.progression_origins": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/progression/origins" - }, - "project_files.publication_result": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/runs/{run_id}/publication-result" - }, - "project_files.recipe_create": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/recipes" - }, - "project_files.recipe_get": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/recipes/{recipe_id}" - }, - "project_files.recipe_material": { - "method": "POST", - "mutation": false, - "path": "/api/workspace/project-files/materials/recipe" - }, - "project_files.recipe_prepare": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/recipes/{graph_id}/prepare" - }, - "project_files.recipe_save": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/recipes/{recipe_id}" - }, - "project_files.recipes": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/recipes" - }, - "project_files.release_freeze": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/releases/freeze" - }, - "project_files.release_preview": { - "method": "POST", - "mutation": false, - "path": "/api/workspace/project-files/releases/preview" - }, - "project_files.retained_analysis": { - "method": "POST", - "mutation": false, - "path": "/api/workspace/project-files/runs/{run_id}/analysis" - }, - "project_files.retained_analysis_export": { - "method": "POST", - "mutation": false, - "path": "/api/workspace/project-files/runs/{run_id}/analysis/export" - }, - "project_files.run": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/runs/{run_id}" - }, - "project_files.run_document_segment": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/runs/{run_id}/document-segment" - }, - "project_files.runs": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/runs" - }, - "project_files.runtime_abandon": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/runtime/abandon" - }, - "project_files.runtime_capture": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/runtime/capture" - }, - "project_files.runtime_inspect": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/runtime/inspect" - }, - "project_files.runtime_material": { - "method": "POST", - "mutation": false, - "path": "/api/workspace/project-files/materials/runtime" - }, - "project_files.runtime_sources": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/runtime/sources" - }, - "project_files.runtime_status": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/runtime/status" - }, - "project_files.save_as": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/save-as" - }, - "project_files.search_create": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/searches" - }, - "project_files.search_delete": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/searches/{search_id}/delete" - }, - "project_files.search_rename": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/searches/{search_id}" - }, - "project_files.searches": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/searches" - }, - "project_files.selection_create": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/selections" - }, - "project_files.selection_delete": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/selections/{selection_id}/delete" - }, - "project_files.selection_get": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/selections/{selection_id}" - }, - "project_files.selection_rename": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/selections/{selection_id}" - }, - "project_files.selections": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/selections" - }, - "project_files.snapshot": { - "method": "POST", - "mutation": false, - "path": "/api/workspace/project-files/materials/snapshot" - }, - "project_files.source_references": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/sources/{project_id}/references" - }, - "project_files.source_register": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/sources/register" - }, - "project_files.studies": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/studies" - }, - "project_files.study": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/studies/{study_id}" - }, - "project_files.study_create": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/studies" - }, - "project_files.study_save": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/studies/{study_id}" - }, - "project_files.trial": { - "method": "GET", - "mutation": false, - "path": "/api/workspace/project-files/trials/{trial_id}" - }, - "project_files.trial_prepare": { - "method": "POST", - "mutation": true, - "path": "/api/workspace/project-files/studies/{study_id}/trials" - } -} -/* PROJECT_FILES_ROUTES_END */; - let selectedContracts=new Set(); - let state=null, selected=null, history=[], summaries=[], nextRecord=null, nextHistory=null, epoch=0, busy=false, blocked=false; - let importDirty=false, annotationDirty=false, m2Dirty=false, pending=null; - let registeredSource=null,modelTemplates=[],templateBinding=null; - let runtimeInspection=null,runtimePending=null,runtimeSourceOffset=0,runtimeSourceTotal=0,runtimeFileOffset=0,runtimeFileTotal=0; - let forkPending=null,workingSelection=null,workingDeletion=null,workingOffset=0,workingTotal=0,workingHistoryOffset=0,workingHistoryTotal=0,intentsOffset=0,intentsTotal=0,forkOffset=0,forkTotal=0,intentCapsOffset=0,intentCapsTotal=0; - let nativeGraphs=[],nativePrepared=null,nativePending=null,nativeOffset=0,nativeTotal=0; - let executionGraphs=[],executionPrepared=null,executionApproval=null,executionBinding=null,executionOffset=0,executionTotal=0,executionStudy=null,executionTrials=[],studyApproval=null,executionGraphOffset=0,executionGraphTotal=0,studyTrialOffset=0,studyTrialTotal=0,producerSource=null,producerCurrent=null,producerHealthOffset=0,producerHealthTotal=0; - let explored=null,exploreOffset=0,exploreTotal=0,historyOffset=0,historyTotal=0; - const m2DirtyForms=new Set(); - const m2PagedActions=new Set(['data_query','data_history','data_responses','data_response_history', - 'data_preferences','data_preference_history','models','graphs','recipes','studies','runs', - 'lineage','policies','artifacts','materials','selections','searches','producers','source_references','execution_producer_health','files_inspect','file_history','material_intents','material_intent_capabilities','runtime_sources']); - const m2HistoryActions=new Set(['data_history','data_response_history','data_preference_history']); - const dirty=()=>importDirty||annotationDirty||m2Dirty; - const checkpoint=()=>state?.project?.checkpoint??null; - let scientificEpoch=null; - const projectScientific=window.ScientificFieldInspector({ - root:$('scientific-inspection'), - isCurrent:record=>scientificEpoch===epoch&&!blocked&&state?.state==='open'&&explored?.category==='data_query'&&explored.id===record.id&&explored.value.content_hash===record.content_hash&&explored.checkpoint===checkpoint(), - async readSlice(record,selection,signal){ - const result=await m2Request('data_scientific',{record_id:record.id,content_hash:record.content_hash,...selection},epoch,{signal}); - if(result===null)throw new DOMException('Project selection changed.','AbortError'); - return result; - } - }); - function clearScientific(){scientificEpoch=null;projectScientific.clear();} - const projectProgression=window.ProjectExperimentProgression({ - root:$('project-progression'), - async read(action,args,signal){ - if(!m2Allowed(action))throw Error('History inspection is unavailable for the selected project.'); - const value=await m2Request(action,args,epoch,{signal}); - if(value===null)throw new DOMException('Project selection changed.','AbortError'); - return value; - }, - inspectStudy:(origin,id)=>run(ticket=>inspectItem('studies',{id},origin,ticket),{clean:true}), - inspectTrial:(origin,id)=>run(ticket=>inspectItem('trials',{id},origin,ticket),{clean:true}), - inspectRun:(origin,id)=>run(ticket=>inspectItem('runs',{id},origin,ticket),{clean:true}), - onContextFocusLost:()=>$('project-files-status').focus() - }); - window.addEventListener('pagehide',()=>projectProgression.clear()); - const projectPortfolio=window.ProjectModelPortfolio({ - root:$('project-model-portfolio'), - async read(action,args,signal){ - if(!m2Allowed(action))throw Error('Model organization inspection is unavailable for the selected project.'); - const value=await m2Request(action,args,epoch,{signal}); - if(value===null)throw new DOMException('Project selection changed.','AbortError'); - return value; - }, - onContextFocusLost:()=>$('project-files-status').focus() - }); - window.addEventListener('pagehide',()=>projectPortfolio.clear()); - const projectMeasurements=window.ProjectMeasurements({ - root:$('project-measurements'), - async read(action,args,signal){ - if(!m2Allowed(action))throw Error('Measurement inspection is unavailable for the selected project.'); - const value=await m2Request(action,args,epoch,{signal}); - if(value===null)throw new DOMException('Project selection changed.','AbortError'); - return value; - },onContextFocusLost:()=>$('project-files-status').focus() - }); - window.addEventListener('pagehide',()=>projectMeasurements.clear()); - window.addEventListener('pagehide',clearScientific); - const exact=(value,keys)=>value!==null&&typeof value==='object'&&!Array.isArray(value)&&Object.keys(value).length===keys.length&&keys.every(key=>Object.hasOwn(value,key)); - const str=(value,max,empty=false)=>typeof value==='string'&&Array.from(value).length<=max&&(empty||/\S/u.test(value)); - const id=value=>typeof value==='string'&&/^[a-f0-9]{32}$/.test(value); - const sha=value=>typeof value==='string'&&/^[a-f0-9]{64}$/.test(value); - const texts=(value,max,min=0,length=120)=>Array.isArray(value)&&value.length>=min&&value.length<=max&&new Set(value).size===value.length&&value.every(item=>str(item,length)); - const positive=value=>Number.isSafeInteger(value)&&value>0; - function annotationOK(task,value,nullable=false){ - if(value===null)return nullable; - if(task==='text_classification')return exact(value,['label'])&&str(value.label,80); - if(task==='text_corpus')return exact(value,['note'])&&str(value.note,4000); - return exact(value,['spans'])&&Array.isArray(value.spans)&&value.spans.length<=500&&value.spans.every(span=>exact(span,['label','start','end'])&&str(span.label,80)&&Number.isSafeInteger(span.start)&&span.start>=0&&positive(span.end)&&span.end>span.start); - } - function provenanceOK(value){ - if(exact(value,['method','rights','normalization'])&&value.method==='import'&&str(value.rights,1000)&&value.normalization==='NFC; LF newlines')return true; - const origin=value?.origin; - return exact(value,['method','rights','origin'])&&value.method==='project_fork'&&str(value.rights,1000)&&exact(origin,['project_id','checkpoint','family','id','revision','source_revision'])&&id(origin.project_id)&&sha(origin.checkpoint)&&['workbench_text','workbench_record'].includes(origin.family)&&id(origin.id)&&positive(origin.revision)&&positive(origin.source_revision); - } - function recordOK(value){ - const fields=['id','kind','name','text','groups','parents','provenance','task','annotation','review','revision','source_revision','created_at','updated_at']; - return exact(value,fields)&&id(value.id)&&value.kind==='text'&&str(value.name,200)&&str(value.text,200000)&&texts(value.groups,30,1)&&texts(value.parents,30)&&provenanceOK(value.provenance)&&tasks.includes(value.task)&&annotationOK(value.task,value.annotation,true)&&['draft','human_reviewed'].includes(value.review)&&positive(value.revision)&&value.source_revision===1&&str(value.created_at,80)&&str(value.updated_at,80); - } - function projectOK(value){return exact(value,['project_id','name','checkpoint'])&&id(value.project_id)&&str(value.name,200)&&sha(value.checkpoint);} - function summaryOK(value){ - return exact(value,['id','kind','name','task','review','revision','source_revision','created_at','updated_at'])&&id(value.id)&&value.kind==='text'&&str(value.name,200)&&tasks.includes(value.task)&&['draft','human_reviewed'].includes(value.review)&&positive(value.revision)&&value.source_revision===1&&str(value.created_at,80)&&str(value.updated_at,80); - } - function receiptOK(value){ - const fields=['committed','selected','project_id','checkpoint','request_key']; - return exact(value,value?.selected===false?[...fields,'root','directory']:fields)&&value.committed===true&&typeof value.selected==='boolean'&&id(value.project_id)&&sha(value.checkpoint)&&typeof value.request_key==='string'&&/^[A-Za-z0-9][A-Za-z0-9_.:-]{7,127}$/.test(value.request_key)&&(value.selected||(str(value.root,160)&&str(value.directory,512))); - } - function stateOK(value){ - const fields=['format','binding','state','roots','project','available_actions']; - if(!exact(value,value?.state==='recovery_required'?[...fields,'recovery']:fields)||value.format!=='project_files_state_v1'||!id(value.binding)||!texts(value.roots,100,0,160)||!Array.isArray(value.available_actions)||value.available_actions.length>8||new Set(value.available_actions).size!==value.available_actions.length||!value.available_actions.every(action=>actions.includes(action)))return false; - if(value.state==='no_project_open')return value.project===null; - if(!projectOK(value.project))return false; - if(value.state==='open')return true; - const recovery=value.recovery; - return value.state==='recovery_required'&&exact(recovery,['action','root','directory','reason','request_key'])&&recovery.action==='open'&&str(recovery.root,160)&&str(recovery.directory,512)&&['unknown_publication','projection_unavailable'].includes(recovery.reason)&&(recovery.request_key===null||typeof recovery.request_key==='string'&&/^[A-Za-z0-9][A-Za-z0-9_.:-]{7,127}$/.test(recovery.request_key))&&value.available_actions.length===1&&value.available_actions[0]==='open'; - } - function boundOK(value,kind){ - const fields=kind==='query'?['binding','project_id','checkpoint','items','next_after_id']:['binding','project_id','checkpoint','record','history','next_history_before_revision']; - if(!exact(value,fields)||!id(value.binding)||!id(value.project_id)||!sha(value.checkpoint))return false; - if(kind==='query')return Array.isArray(value.items)&&value.items.length<=100&&value.items.every(summaryOK)&&(value.next_after_id===null||id(value.next_after_id)&&value.items.at(-1)?.id===value.next_after_id)&&value.items.every((item,index)=>index===0||item.id>value.items[index-1].id); - return recordOK(value.record)&&Array.isArray(value.history)&&value.history.length<=4&&value.history.every(recordOK)&&value.history.every((item,index)=>item.id===value.record.id&&item.revision<=value.record.revision&&(index===0||item.revision!busy&&!blocked&&selectedContracts.has('project_files.'+action)&&state?.available_actions.includes(action); - for(const action of ['new','open','save','close'])$('project-files-'+action).disabled=!allowed(action); - $('project-files-refresh').disabled=busy; - $('project-files-root').disabled=busy||state?.state==='recovery_required'; - $('project-files-directory').disabled=busy||state?.state==='recovery_required'; - $('project-files-name').disabled=busy||state?.state==='recovery_required'; - $('text-import-fields').disabled=!open||!allowed('import_text'); - $('annotation-fields').disabled=!selected||!allowed('annotate'); - $('import-text').disabled=!allowed('import_text'); - $('annotation-save').disabled=!selected||!allowed('annotate'); - $('project-files-discard').disabled=busy||!dirty(); - $('records-more').hidden=nextRecord===null;$('records-more').disabled=!allowed('query'); - $('record-history-more').hidden=nextHistory===null;$('record-history-more').disabled=!selected||!allowed('get'); - $('project-files-open').textContent=state?.state==='recovery_required'?'Reopen to reconcile':'Open project'; - for(const button of $('records-list').querySelectorAll('button'))button.disabled=busy||blocked; - $('project-files-dirty').textContent=dirty()?'This tab has unsent or unacknowledged edits. After an error, inspect saved state before retrying; explicitly discard these edits before closing. Unsent annotations must be resolved before selecting a different record.':'No unsubmitted edits.'; - m2Controls();m4Controls();runtimeControls();candidateControls(); - if(window.TuldokAuth&&!window.TuldokAuth.canReview())$('record-review').value='draft'; - } - function showState(){ - if(executionBinding!==state.binding){nativeGraphs=[];nativePrepared=null;nativePending=null;nativeOffset=nativeTotal=0;$('project-native-graph').replaceChildren();$('project-native-phases').replaceChildren();executionBinding=state.binding;executionPrepared=null;executionApproval=null;executionStudy=null;studyApproval=null;executionGraphs=[];executionTrials=[];producerSource=null;producerCurrent=null;$('project-execution-grant').textContent='No current local approval selected.';} - const root=$('project-files-root'), previous=root.value;root.replaceChildren(); - for(const alias of state.roots){const option=document.createElement('option');option.value=alias;option.textContent=alias;root.append(option);} - if(state.roots.includes(previous))root.value=previous; - const destination=$('project-save-as-root'),oldDestination=destination.value;destination.replaceChildren(); - for(const alias of state.roots){const option=document.createElement('option');option.value=alias;option.textContent=alias;destination.append(option);} - if(state.roots.includes(oldDestination))destination.value=oldDestination; - const candidateRoot=$('project-candidate-root'),oldCandidateRoot=candidateRoot.value;candidateRoot.replaceChildren();for(const alias of state.roots){const option=document.createElement('option');option.value=alias;option.textContent=alias;candidateRoot.append(option);}if(state.roots.includes(oldCandidateRoot))candidateRoot.value=oldCandidateRoot; - const recovery=state.state==='recovery_required'; - $('project-files-summary').textContent=state.project?`${state.project.name} · ${state.project.project_id} · ${recovery?'last acknowledged':'saved'} checkpoint ${state.project.checkpoint}${recovery?' · Reopen this project to reconcile its saved state.':''}`:'No project open.'; - if(recovery){root.value=state.recovery.root;$('project-files-directory').value=state.recovery.directory;} - controls(); - } - function annotationHelp(){ - const task=$('annotation-task').value; - $('annotation-label').textContent=task==='text_classification'?'Class label':task==='text_corpus'?'Corpus note':'Entity spans (JSON)'; - $('annotation-help').textContent=task==='text_classification'?'Enter one classification label, up to 80 characters.':task==='text_corpus'?'Enter a human-authored corpus note, up to 4,000 characters.':'Enter {"spans":[{"label":"person","start":0,"end":4}]}. Offsets count Unicode code points; an empty spans array records a negative.'; - $('annotation-value').maxLength=task==='text_classification'?80:task==='text_corpus'?4000:200000; - } - function showRecord(focus=false){ - $('record-heading').textContent=selected?selected.name:'Select a text record'; - $('record-summary').textContent=selected?`Revision ${selected.revision} · ${selected.review} · source revision ${selected.source_revision}`:''; - $('record-text').value=selected?.text??''; - $('annotation-task').value=selected?.task??'text_classification'; - const value=selected?.annotation; - $('annotation-value').value=value?(selected.task==='text_entities'?JSON.stringify(value,null,2):value.label??value.note):''; - $('annotation-groups').value=selected?.groups.join(', ')??''; - $('record-review').value=selected?.review??'draft'; - annotationHelp(); - showHistory();controls();if(focus)$('record-heading').focus(); - } - function showHistory(){ - const list=$('record-history');list.replaceChildren(); - for(const snapshot of history){const item=document.createElement('li'),title=document.createElement('p'),body=document.createElement('pre');title.textContent=`Revision ${snapshot.revision} · ${snapshot.review} · ${snapshot.task}`;body.textContent=JSON.stringify(snapshot.annotation,null,2);item.append(title,body);list.append(item);} - controls(); - } - function showRecords(items){ - const list=$('records-list');list.replaceChildren(); - if(!items.length){const item=document.createElement('li');item.textContent='No text records yet.';list.append(item);} - for(const record of items){const item=document.createElement('li'),button=document.createElement('button');button.type='button';button.dataset.recordId=record.id;button.textContent=`${record.name} · ${record.review} · revision ${record.revision}`;button.setAttribute('aria-current',String(record.id===selected?.id));button.onclick=()=>select(record.id);item.append(button);list.append(item);} - controls(); - } - function needClean(){if(!dirty())return true;error('This tab has unsent or unacknowledged edits. Inspect saved state after an error, then submit or choose “Discard unsubmitted edits” before this action.');return false;} - async function discover(ticket){ - let response,value; - try{response=await window.TuldokAuth.fetch('/api/agent/capabilities',{cache:'no-store'});value=await response.json();} - catch(_){const failure=Error('Project contracts unavailable. Refresh status before continuing.');failure.code='transport';throw failure;} - if(ticket!==epoch)return false; - if(!response.ok){const failure=Error(value?.error??'Project contracts unavailable. Sign in and refresh status.');failure.status=response.status;throw failure;} - if(!exact(value,['format','envelope_version','catalog_id','operations','limits'])||value.format!=='agent_capabilities_v1'||value.envelope_version!==1||!id(value.catalog_id)||!Array.isArray(value.operations)||value.operations.length>256||JSON.stringify(value).length>1048576||!exact(value.limits,['request_bytes','response_bytes','max_operations'])||value.limits.request_bytes!==1048576||value.limits.response_bytes!==16777216||value.limits.max_operations!==256)throw Error('Unsupported project capability envelope.'); - const identity=window.TuldokAuth.identity?.(); - if(identity?.catalog_id&&identity.catalog_id!==value.catalog_id)throw Error('Project capability catalog differs from the current session.'); - const names=new Set(),chosen=new Set(),versionsChosen=new Map(); - for(const operation of value.operations){ - if(!exact(operation,['id','contracts','availability'])||typeof operation.id!=='string'||!/^[a-z][a-z0-9_.]{0,79}$/.test(operation.id)||names.has(operation.id)||!['available','unavailable','unsupported'].includes(operation.availability)||!Array.isArray(operation.contracts)||!operation.contracts.length||operation.contracts.length>4)throw Error('Unsupported operation capability.'); - names.add(operation.id);const versions=new Set(); - for(const contract of operation.contracts){ - if(!exact(contract,['version','sha256','input_schema','output_schema','scopes','authority','effects','retry','bounds'])||!positive(contract.version)||versions.has(contract.version)||!sha(contract.sha256)||!contract.input_schema||typeof contract.input_schema!=='object'||Array.isArray(contract.input_schema)||!contract.output_schema||typeof contract.output_schema!=='object'||Array.isArray(contract.output_schema)||!texts(contract.scopes,16,0,40)||!['agent','owner'].includes(contract.authority)||!['read','mutation'].includes(contract.effects)||!['read','cas','receipt','never'].includes(contract.retry)||!exact(contract.bounds,['request_bytes','response_bytes','inline_decoded_bytes','json_depth'])||!Object.values(contract.bounds).every(positive))throw Error('Unsupported operation contract.'); - versions.add(contract.version); - // Remote schemas are opaque discovery data; only installed local pins - // select behavior. Every request lets the owner verify this exact pin. - const local=versionPins[operation.id]??(Object.hasOwn(pins,operation.id)?{'1':pins[operation.id]}:{}); - if(operation.availability==='available'&&local[contract.version]===contract.sha256&&contract.version>(versionsChosen.get(operation.id)??0)){chosen.add(operation.id);versionsChosen.set(operation.id,contract.version);} - } - } - selectedContracts=chosen;selectedVersions=versionsChosen; - if(!chosen.has('project_files.status')){const failure=Error('No compatible project status contract is available.');failure.code='contract_mismatch';throw failure;} - return true; - } - async function request(path,{body,kind='state',ticket=epoch,read=false,recordId}={}){ - const binding=state?.binding, expected=checkpoint(), project=state?.project?.project_id; - const action=path===''?'status':path.startsWith('/records?')?'query':path.startsWith('/records/')?(body===undefined?'get':'annotate'):path.slice(1).replaceAll('-','_'); - const operation='project_files.'+action; - if(!selectedContracts.has(operation)){const failure=Error('No compatible contract is available for '+action+'. Refresh project status.');failure.code='contract_mismatch';throw failure;} - let response,value; - try{ - response=await window.TuldokAuth.fetch(base+path,{method:body===undefined?'GET':'POST',headers:{'Tuldok-Operation-Contract':selectedHeader(operation),...(body===undefined?{}:{'Content-Type':'application/json'})},body:body===undefined?undefined:JSON.stringify(body),cache:'no-store'}); - value=await response.json(); - }catch(_){const failure=Error(body===undefined?'Project response unavailable. Refresh status to recover.':'Acknowledgement unavailable; the edit may already be saved. Keep your edits and refresh status before retrying.');failure.code='transport';throw failure;} - if(ticket!==epoch){message('A superseded project response was ignored. The current view is unchanged.');return null;} - if(!response.ok){const fields=['error',...(Object.hasOwn(value??{},'code')?['code']:[]),...(Object.hasOwn(value??{},'receipt')?['receipt']:[])];const valid=exact(value,fields)&&str(value.error,1000)&&(!Object.hasOwn(value,'code')||str(value.code,120))&&(!Object.hasOwn(value,'receipt')||receiptOK(value.receipt));const failure=Error(valid?`${value.code??'error'}: ${value.error}`:'Invalid project error response. Refresh status.');failure.code=valid?(value.code??'http_error'):'transport';failure.status=response.status;if(valid&&value.receipt)failure.receipt=value.receipt;throw failure;} - if(!(kind==='state'?stateOK(value):kind==='fork'?forkOK(value,body):boundOK(value,kind))){const failure=Error('Unsupported project response. The current state is unknown; refresh status before continuing.');failure.code='transport';throw failure;} - if(kind==='record'&&selectedVersions.get(operation)===1&&[value.record,...value.history].some(record=>record.provenance.method!=='import')){const failure=Error('Version 1 cannot represent retained fork provenance. Refresh contracts.');failure.code='transport';throw failure;} - if(kind!=='state'&&kind!=='fork'&&(value.binding!==binding||value.project_id!==project||(read&&value.checkpoint!==expected)||(recordId&&value.record?.id!==recordId))){const failure=Error('stale: Response belongs to a different project or checkpoint. Your unsubmitted edits remain here. Refresh status.');failure.code='stale';throw failure;} - return value; - } - async function run(work,{clean=false}={}){ - if(busy)return;if(clean&&!needClean())return; - const ticket=++epoch;busy=true;clearError();controls(); - let nextFocus=null; - try{nextFocus=await work(ticket);}catch(failure){ - if(ticket===epoch){ - if(failure.status===409||failure.status>=500||['stale','conflict','binding_mismatch','transport','projection_unavailable','stale_binding','stale_checkpoint','too_large'].includes(failure.code))blocked=true; - if(failure.receipt){const receipt=failure.receipt;$('project-files-receipt').hidden=false;$('project-files-receipt').textContent=`Saved to project ${receipt.project_id} at checkpoint ${receipt.checkpoint}; request ${receipt.request_key}. ${receipt.selected?'Refresh status and reopen to restore the local view.':'The project was created but is not selected. Refresh status, then Open its directory.'}`;if(!receipt.selected){$('project-files-root').value=receipt.root;$('project-files-directory').value=receipt.directory;}} - error(failure.message); - } - }finally{if(ticket===epoch){busy=false;controls();if(nextFocus)nextFocus.focus();}} - } - async function query(ticket,append=false){ - if(state?.state!=='open'){summaries=[];nextRecord=null;showRecords([]);return;} - const cursor=append?nextRecord:null,parameters={binding:state.binding,checkpoint:checkpoint()}; - if(cursor!==null)parameters.after_id=cursor; - const result=await request('/records?'+new URLSearchParams(parameters),{kind:'query',ticket,read:true}); - if(result){if(cursor!==null&&result.items.some(item=>item.id<=cursor))throw Error('Invalid record-page continuation. Refresh status.');summaries=append?[...summaries,...result.items]:result.items;nextRecord=result.next_after_id;showRecords(summaries);} - } - function olderHistory(){return run(async ticket=>{ - if(!selected||nextHistory===null)return; - const before=nextHistory; - const result=await request('/records/'+selected.id+'?'+new URLSearchParams({binding:state.binding,checkpoint:checkpoint(),before_revision:before}),{kind:'record',ticket,read:true,recordId:selected.id}); - if(!result)return; - if(result.record.revision!==selected.revision||result.history.some(item=>item.revision>=before))throw Error('Invalid history-page continuation. Refresh status.'); - history=[...history,...result.history];nextHistory=result.next_history_before_revision;showHistory();message('Older saved annotation history loaded.');return nextHistory===null?$('record-history-title'):$('record-history-more'); - });} - function refresh(){return run(async ticket=>{ - if(!await discover(ticket))return; - const value=await request('',{ticket});if(!value)return; - const changed=state?.binding!==value.binding||checkpoint()!==value.project?.checkpoint; - state=value;blocked=false; - if(changed){m4Reset();clearExploration();selected=null;history=[];nextHistory=null;if(!annotationDirty)showRecord();else{$('record-heading').textContent='Unsubmitted annotation from a prior checkpoint';$('record-summary').textContent='Project changed. Your unsubmitted annotation remains below; discard it before selecting a saved record.';$('record-text').value='';}} - showState();await query(ticket);message(dirty()?'Project status refreshed. Unsubmitted edits remain in this tab.':'Project status refreshed.'); - });} - function select(recordId){if(annotationDirty){error('The annotation editor has unsent or unacknowledged edits. Submit or explicitly discard that annotation before selecting a saved record.');return;}return run(async ticket=>{ - const result=await request('/records/'+recordId+'?'+new URLSearchParams({binding:state.binding,checkpoint:checkpoint()}),{kind:'record',ticket,read:true,recordId}); - if(!result)return;selected=result.record;history=result.history;nextHistory=result.next_history_before_revision;annotationDirty=false;showRecord(true);await query(ticket);message('Saved text and annotation history loaded.'); - });} - function key(){return crypto.randomUUID().replaceAll('-','');} - function mutationBody(path,fields){ - const body={binding:state.binding,expected_checkpoint:checkpoint(),...fields}; - const signature=JSON.stringify({path,body}); - if(!pending||pending.signature!==signature)pending={signature,key:key()}; - return {...body,request_key:pending.key}; - } - function lifecycle(action){const recovering=action==='open'&&state?.state==='recovery_required';return run(async ticket=>{ - const fields={}; - if(['new','open'].includes(action)){ - if(!$('project-files-root').value||!$('project-files-directory').value.trim())throw Error('Choose a local root and relative project directory.'); - fields.root=$('project-files-root').value;fields.directory=$('project-files-directory').value; - if(action==='new'){if(!$('project-files-name').value.trim())throw Error('Enter a name for the new project.');fields.name=$('project-files-name').value;} - } - const value=await request('/'+action,{ticket,body:mutationBody('/'+action,fields)});if(!value)return; - state=value;pending=null;if(action!=='save'){m4Reset();clearExploration();selected=null;history=[];nextHistory=null;}showState();if(action!=='save'&&!annotationDirty)showRecord();else if(recovering&&annotationDirty){$('record-heading').textContent='Preserved unsubmitted annotation';$('record-text').value='';}await query(ticket);message(action==='save'?'Project checkpoint is saved.':action==='close'?'Project closed.':`Project ${action==='new'?'created':'opened'}.`); - return action==='save'?$('project-files-save'):(state.state==='open'?$('text-name'):$('project-files-directory')); - },{clean:!recovering});} - function groups(value){const result=value.split(',').map(item=>item.trim()).filter(Boolean);if(!texts(result,30,1))throw Error('Supply 1–30 distinct protected group IDs, each up to 120 characters.');return result;} - async function acceptRecord(value,ticket){ - state={...state,project:{...state.project,checkpoint:value.checkpoint}};selected=value.record;history=value.history;nextHistory=value.next_history_before_revision;pending=null;annotationDirty=false;showState();showRecord(true);await query(ticket); - } - $('text-import-form').onsubmit=event=>{ - event.preventDefault();if(annotationDirty){error('Submit or discard the current annotation before creating another text record.');return;} - run(async ticket=>{ - const asset={name:$('text-name').value,text:$('text-content').value,groups:groups($('text-groups').value),rights:$('text-rights').value}; - if(!str(asset.name,200)||!str(asset.text,200000)||!str(asset.rights,1000))throw Error('Enter a name, text and rights note within the displayed limits.'); - const value=await request('/import-text',{kind:'record',ticket,body:mutationBody('/import-text',{asset})});if(!value)return; - importDirty=false;$('text-name').value='';$('text-content').value='';await acceptRecord(value,ticket);message('Text submitted and saved to the project.'); - }); - }; - $('annotation-form').onsubmit=event=>{ - event.preventDefault();run(async ticket=>{ - if(!selected)throw Error('Select a saved text record first.'); - const task=$('annotation-task').value,raw=$('annotation-value').value; - let annotation;if(task==='text_entities'){try{annotation=JSON.parse(raw);}catch(_){throw Error('Entity spans must be valid JSON.');}}else annotation=task==='text_corpus'?{note:raw}:{label:raw}; - if(!annotationOK(task,annotation))throw Error('The annotation does not match this task. Follow the instructions above the editor.'); - const body={revision:selected.revision,source_revision:selected.source_revision,task,annotation,groups:groups($('annotation-groups').value),review:$('record-review').value}; - const value=await request('/records/'+selected.id,{kind:'record',ticket,recordId:selected.id,body:mutationBody('/records/'+selected.id,{annotation:body})});if(!value)return; - await acceptRecord(value,ticket);message('Annotation submitted and saved to the project.'); - }); - }; - function projectValue(value,depth=0){ - const box=document.createElement('div'); - if(value===null||typeof value!=='object'){box.textContent=value===null?'Not recorded':String(value);return box;} - if(depth>5){box.textContent='Further saved details available through the project API.';return box;} - const entries=Array.isArray(value)?value.map((item,index)=>[String(index+1),item]):Object.entries(value); - const list=document.createElement('dl'); - for(const [name,item] of entries){ - const term=document.createElement('dt'),definition=document.createElement('dd');term.textContent=name.replaceAll('_',' '); - if(item!==null&&typeof item==='object'){ - const details=document.createElement('details'),summary=document.createElement('summary');summary.textContent=Array.isArray(item)?`${item.length} saved items`:'Saved details';details.append(summary,projectValue(item,depth+1));definition.append(details); - }else definition.textContent=item===null?'Not recorded':String(item); - list.append(term,definition); - } - box.append(list);return box; - } - const m2Allowed=action=>!busy&&!blocked&&state?.state==='open'&&selectedContracts.has('project_files.'+action); - function m2Controls(){ - projectPortfolio.setContext({key:JSON.stringify([state?.binding,state?.project?.project_id,checkpoint(),window.TuldokAuth?.identity?.()?.credential_id,epoch]), - project_id:state?.project?.project_id,enabled:m2Allowed('files_inspect')&&m2Allowed('file_get')}); - projectProgression.setContext({key:JSON.stringify([state?.binding,state?.project?.project_id,checkpoint(),window.TuldokAuth?.identity?.()?.credential_id,epoch]), - project_id:state?.project?.project_id,enabled:m2Allowed('progression')&&m2Allowed('progression_origins')}); - projectMeasurements.setContext({key:JSON.stringify([state?.binding,state?.project?.project_id,checkpoint(),window.TuldokAuth?.identity?.()?.credential_id,epoch]), - enabled:['measurement_sources','measurement_compare','measurement_inspect'].every(m2Allowed)}); - if(blocked||state?.state!=='open'||scientificEpoch!==null&&(scientificEpoch!==epoch||explored?.checkpoint!==checkpoint()))clearScientific(); - const action=$('project-explore-kind').value; - $('project-explore-load').disabled=!m2Allowed(action); - $('project-explore-more').disabled=!m2Allowed(action); - for(const [field,operation] of [['project-source-fields','data_import_'+$('project-source-kind').value],['project-search-fields','search_create'],['project-selection-fields','selection_create'],['project-rights-fields','data_rights'],['project-data-note-fields','data_annotate']])$(field).disabled=!m2Allowed(operation)||(['project-selection-fields','project-rights-fields','project-data-note-fields'].includes(field)&&(!explored||explored.checkpoint!==checkpoint())); - $('project-definitions-load').disabled=!m2Allowed('definitions'); - $('project-model-create-fields').disabled=!modelTemplates.length||templateBinding!==state?.binding||!m2Allowed('model_create'); - $('project-model-publish').disabled=!explored||explored.category!=='models'||explored.checkpoint!==checkpoint()||!m2Allowed('model_publish'); - $('project-study-create-fields').disabled=!m2Allowed('study_create'); - $('project-register-fields').disabled=!m2Allowed('source_register'); - $('project-source-references-more').disabled=!m2Allowed('source_references'); - $('project-scientific-fields').disabled=!registeredSource||registeredSource.binding!==state?.binding||!m2Allowed('data_import_scientific'); - executionControls(); - $('project-artifact-status').disabled=!explored||explored.category!=='artifacts'||!m2Allowed('artifact_status'); - $('project-artifact-resolve-fields').disabled=!explored||explored.category!=='artifacts'||!m2Allowed('artifact_resolve'); - $('project-metadata-fields').disabled=!explored||explored.checkpoint!==checkpoint()||!m2Allowed(explored.saveAction); - for(const name of ['project-detail-history','project-detail-availability','project-run-evidence','project-run-document','project-run-disclose','project-detail-history-more'])$(name).disabled=busy||blocked||state?.state!=='open'; - for(const button of $('project-explore-list').querySelectorAll('button'))button.disabled=busy||blocked; - } - function clearExploration(){ - clearScientific(); - explored=null;exploreOffset=0;exploreTotal=0;historyOffset=0;historyTotal=0; - $('project-explore-list').replaceChildren();$('project-detail-facts').replaceChildren();$('project-detail-history-list').replaceChildren(); - $('project-detail-title').textContent='Choose a saved record';$('project-explore-summary').textContent=''; - for(const name of ['project-metadata-form','project-data-note-form','project-rights-form','project-selection-form','project-detail-history','project-detail-history-more','project-detail-availability','project-run-evidence','project-run-document','project-run-disclose','project-disclosure-label','project-model-publish','project-artifact-status','project-artifact-resolve-form','project-explore-more'])if(!m2DirtyForms.has(name))$(name).hidden=true; - if(m2Dirty)$('project-detail-title').textContent='Preserved unsubmitted metadata; discard it before selecting a saved record.'; - } - async function m4Response(action,value,args,project){ - const invalid=()=>{const failure=Error('Saved file or fork response differs from its selected identity, revision or exact bytes.');failure.code='transport';throw failure;}; - const natural=value=>Number.isSafeInteger(value)&&value>=0; - const safeText=(value,max,empty=false)=>str(value,max,empty)&&!value.includes('\0')&&!Array.from(value).some(ch=>ch.length===1&&ch.charCodeAt(0)>=0xd800&&ch.charCodeAt(0)<=0xdfff); - const filePath=(kind,path)=>['script','note'].includes(kind)&&safeText(path,512)&&path.startsWith((kind==='script'?'scripts':'notes')+'/')&&!path.includes('\\')&&path.split('/').every(part=>part!==''&&part!=='.'&&part!=='..')&&!/[\x00-\x1f]/.test(path); - const shaBytes=async raw=>Array.from(new Uint8Array(await crypto.subtle.digest('SHA-256',raw)),n=>n.toString(16).padStart(2,'0')).join(''); - const fileID=async value=>shaBytes(new TextEncoder().encode(project+'\0'+value.kind+'\0'+value.path)); - const metadata=value=>exact(value,['revision','sha256','bytes','adopted_at','actor_id'])&&positive(value.revision)&&sha(value.sha256)&&natural(value.bytes)&&value.bytes<=1048576&&safeText(value.adopted_at,80)&&id(value.actor_id); - const deletedMetadata=value=>exact(value,['revision','deleted','sha256','bytes','adopted_at','actor_id'])&&positive(value.revision)&&value.revision>=2&&value.deleted===true&&value.sha256===null&&value.bytes===0&&safeText(value.adopted_at,80)&&id(value.actor_id); - const families=['model_definition','pipeline_graph','recipe_definition']; - const fields=['task','specification','source_selector','preprocessing_policy','output_policy','recipe_source','inputs','runtime','release','nodes','data','evaluation_profile','model','trainer']; - const reselection=value=>Array.isArray(value)&&value.length<=14&&new Set(value).size===value.length&&value.every(field=>fields.includes(field)); - const origin=value=>exact(value,['project_id','checkpoint','family','id','revision','created_at'])&&id(value.project_id)&&sha(value.checkpoint)&&families.includes(value.family)&&safeText(value.id,512)&&positive(value.revision)&&safeText(value.created_at,80); - if(['file_get','file_adopt','file_adopt_deletion'].includes(action)){ - const keys=action==='file_get'?['id','project_id','kind','path','version']:['id','project_id','kind','path','revision','sha256','bytes','adopted_at','changed',...(action==='file_adopt_deletion'?['deleted']:[])]; - if(!exact(value,keys)||!sha(value.id)||value.project_id!==project||!filePath(value.kind,value.path)||value.id!==await fileID(value))invalid(); - if(action==='file_get'){ - const v=value.version,deleted=v?.deleted===true,meta=Object.fromEntries(Object.entries(v??{}).filter(([k])=>k!=='text')); - if(deleted){if(value.kind!=='note'||!exact(v,['revision','deleted','sha256','bytes','adopted_at','actor_id','text'])||!deletedMetadata(meta)||v.text!==null)invalid();} - else{if(!exact(v,['revision','sha256','bytes','adopted_at','actor_id','text'])||!metadata(meta)||typeof v.text!=='string'||Array.from(v.text).some(ch=>ch.length===1&&ch.charCodeAt(0)>=0xd800&&ch.charCodeAt(0)<=0xdfff))invalid(); - const bytes=new TextEncoder().encode(v.text);if(bytes.length>1048576||bytes.length!==v.bytes||await shaBytes(bytes)!==v.sha256)invalid();} - if(value.id!==args.file_id||(args.revision!==undefined&&args.revision!==v.revision))invalid(); - }else if(action==='file_adopt_deletion'){ - if(value.kind!=='note'||value.path!==args.path||value.deleted!==true||value.sha256!==null||value.bytes!==0||value.changed!==true||value.revision!==args.expected_revision+1||!safeText(value.adopted_at,80))invalid(); - }else if(value.kind!==args.kind||value.path!==args.path||value.sha256!==args.expected_sha256||!positive(value.revision)||typeof value.changed!=='boolean'||value.revision!==args.expected_revision+Number(value.changed)||!natural(value.bytes)||value.bytes>1048576||!safeText(value.adopted_at,80))invalid(); - } - if(action==='file_history'&&(!exact(value,['id','items','total','offset','limit'])||value.id!==args.file_id||!value.items.every(item=>metadata(item)||deletedMetadata(item))))invalid(); - if(action==='files_inspect')for(const item of value.items){ - if(!exact(item,['id','kind','path','revision','expected_sha256','expected_bytes','observed_sha256','observed_bytes','state','reason'])||!filePath(item.kind,item.path)||item.id!==await fileID(item)||!positive(item.revision)||!(item.expected_sha256===null||sha(item.expected_sha256))||!natural(item.expected_bytes)||item.expected_bytes>1048576||!(item.observed_sha256===null||sha(item.observed_sha256))||!(item.observed_bytes===null||natural(item.observed_bytes)&&item.observed_bytes<=1048576)||!['unchanged','changed','missing','invalid','deleted'].includes(item.state)||!(item.reason===null||['missing','unsafe_path','too_large','invalid_utf8','unreadable','unstable'].includes(item.reason)))invalid(); - if(item.expected_sha256===null&&(item.kind!=='note'||item.expected_bytes!==0||['unchanged','missing'].includes(item.state)))invalid(); - if(item.state==='deleted'&&(item.expected_sha256!==null||item.observed_sha256!==null||item.observed_bytes!==null||item.reason!==null))invalid(); - if(item.state==='unchanged'&&(item.observed_sha256!==item.expected_sha256||item.observed_bytes!==item.expected_bytes||item.reason!==null))invalid(); - } - if(action==='material_intents')for(const item of value.items)if(!exact(item,['family','id','catalog_id','definition_id','name','revision','required_reselection','fork_origin'])||!families.includes(item.family)||item.catalog_id!==project||!id(item.definition_id)||item.id!==project+'.'+item.definition_id||!safeText(item.name,200)||item.revision!==1||!reselection(item.required_reselection)||!origin(item.fork_origin)||item.fork_origin.family!==item.family)invalid(); - if(action==='material_intent'){ - const current=value.current; - if(!exact(value,['family','id','current','fork_origin'])||value.family!==args.family||value.id!==project+'.'+args.definition_id||!exact(current,['format','catalog_id','id','revision','name','definition_family','definition','required_reselection'])||current.format!=='project_material_fork_intent_v1'||current.catalog_id!==project||current.id!==args.definition_id||current.revision!==1||!safeText(current.name,200)||current.definition_family!==args.family||current.definition===null||typeof current.definition!=='object'||Array.isArray(current.definition)||!reselection(current.required_reselection)||!origin(value.fork_origin)||value.fork_origin.family!==args.family)invalid(); - } - if(action==='material_intent_capabilities')for(const item of value.items)if(!exact(item,['family','id','requires_reselection'])||!families.includes(item.family)||typeof item.id!=='string'||!item.id.startsWith(project+'.')||!id(item.id.slice(33))||!reselection(item.requires_reselection))invalid(); - if(action==='fork_info'){ - const page=value.mapping,offset=args.offset??0,limit=args.limit??40; - if(!exact(value,['source','project_id','mapping','archived_count','copied_count','missing_regenerable_count'])||value.project_id!==project||!(value.source===null||exact(value.source,['project_id','checkpoint'])&&id(value.source.project_id)&&sha(value.source.checkpoint))||!['archived_count','copied_count','missing_regenerable_count'].every(k=>natural(value[k]))||!exact(page,['items','total','offset','limit'])||!natural(page.total)||page.offset!==offset||page.limit!==limit||!Array.isArray(page.items)||page.items.length!==Math.min(limit,Math.max(0,page.total-offset)))invalid(); - for(const item of page.items)if(!exact(item,['family','source_id','source_revision','destination_id'])||!safeText(item.family,80)||!safeText(item.source_id,512)||!(item.source_revision===null||positive(item.source_revision))||!safeText(item.destination_id,512))invalid(); - } - } - async function m2Request(action,arguments_,ticket,{signal}={}){ - const operation='project_files.'+action,definition=m2Operations[operation]; - if(!definition||!selectedContracts.has(operation))throw Error('This operation is unavailable for the selected project.'); - const binding=state.binding,cp=checkpoint(),project=state.project.project_id; - let values={binding,[definition.mutation?'expected_checkpoint':'checkpoint']:cp,...arguments_}; - let path=definition.path; - for(const [name,value] of Object.entries(values))path=path.replace('{'+name+'}',encodeURIComponent(value)); - const remaining=Object.fromEntries(Object.entries(values).filter(([name])=>!definition.path.includes('{'+name+'}'))); - const options={method:definition.method,cache:'no-store',signal,headers:{'Tuldok-Operation-Contract':selectedHeader(operation)}}; - if(definition.method==='GET')path+='?'+new URLSearchParams(remaining); - else{ - if(definition.mutation&&!['execution_reconcile_current','execution_study_reconcile_preparation','native_reconcile'].includes(action)){ - let prepared; - if(action==='runtime_capture'){ - const signature=JSON.stringify(arguments_); - if(runtimePending&&(runtimePending.signature!==signature||runtimePending.body.binding!==binding))throw Error('Inspect the pending runtime capture outcome, then keep its exact request or explicitly discard the capture form before changing source, inventory or reserve.'); - if(!runtimePending)runtimePending={signature,body:mutationBody(path,arguments_)}; - prepared=runtimePending.body;$('project-runtime-status-key').value=prepared.request_key;$('project-runtime-abandon-key').value=prepared.request_key; - $('project-runtime-pending').textContent=`Pending capture ${prepared.request_key}: source ${prepared.source}, inventory ${prepared.expected_inventory_sha256}, reserve ${prepared.reserve_bytes??6442450944} bytes. Retry uses these exact fields. Preserve the key until its retained outcome is known.`; - Object.assign(remaining,prepared); - }else if(['native_preflight','native_submit','native_retry'].includes(action)){ - const signature=JSON.stringify({action,arguments_}); - if(nativePending&&(nativePending.signature!==signature||nativePending.body.binding!==binding))throw Error('Keep the exact pending native request until its outcome is known, or explicitly discard unsubmitted fields before choosing a different action.'); - if(!nativePending)nativePending={action,signature,body:mutationBody(path,arguments_)}; - prepared=nativePending.body;Object.assign(remaining,Object.fromEntries(Object.entries(prepared).filter(([field])=>!definition.path.includes('{'+field+'}')))); - $('project-native-pending').textContent=`Pending ${action}: request ${prepared.request_key}. Keep this exact key and fields after a lost acknowledgement. No automatic retry is performed.`; - }else prepared=mutationBody(path,arguments_); - values={...values,...prepared};remaining.request_key=prepared.request_key; - } - if(['execution_study_prepare_package','execution_study_prepare_verifier'].includes(action)){$('project-candidate-recovery-study').value=arguments_.study_id;$('project-candidate-recovery-key').value=values.request_key;$('project-candidate-preparation-status').textContent=`Pending preparation ${values.request_key}. Preserve this key until its outcome is known.`;} - options.headers['Content-Type']='application/json';options.body=JSON.stringify(remaining); - if(new TextEncoder().encode(options.body).length>1048576)throw Error('This source exceeds the synchronous import limit. Choose a smaller source.'); - } - let response,value; - try{response=await window.TuldokAuth.fetch(path,options);value=await response.json();} - catch(problem){if(problem.name==='AbortError')throw problem;const failure=Error(definition.mutation?'Acknowledgement unavailable; this change may already be saved. Keep your edits and refresh project status.':'Saved history is unavailable. Refresh project status.');failure.code='transport';throw failure;} - if(ticket!==epoch)return null; - if(!response.ok){ - const failure=Error(str(value?.error,1000)?value.error:'Unsupported project error response.');failure.code=value?.code??'transport';failure.status=response.status; - if(value?.receipt){if(!receiptOK(value.receipt)||value.receipt.request_key!==values.request_key||value.receipt.project_id!==project||!value.receipt.selected){const invalid=Error('Project receipt belongs to a different request.');invalid.code='transport';throw invalid;}failure.receipt=value.receipt;} - throw failure; - } - if(!exact(value,['binding','project_id','checkpoint','value'])||value.binding!==binding||value.project_id!==project||!sha(value.checkpoint)||(!definition.mutation&&value.checkpoint!==cp)||!value.value||typeof value.value!=='object'||Array.isArray(value.value)){ - const failure=Error('Saved response belongs to a different project or checkpoint. Refresh project status.');failure.code='transport';throw failure; - } - if(m2PagedActions.has(action)){ - const page=value.value,limit=arguments_.limit??(m2HistoryActions.has(action)?1:40),offset=arguments_.offset??0; - if(!Array.isArray(page.items)||page.items.length>limit||page.offset!==offset||page.limit!==limit||!Number.isSafeInteger(page.total)||page.total<0||page.items.length!==Math.min(limit,Math.max(0,page.total-offset))){const failure=Error('Saved page differs from its requested continuation.');failure.code='transport';throw failure;} - } - if(['files_inspect','file_get','file_history','file_adopt','file_adopt_deletion','material_intents','material_intent','material_intent_capabilities','fork_info'].includes(action)){await m4Response(action,value.value,arguments_,project);if(ticket!==epoch)return null;} - if(action.startsWith('execution_')){ - const result=value.value,invalid=()=>{const failure=Error('Current execution response differs from the selected project, material or action.');failure.code='transport';throw failure;}; - if(Object.hasOwn(result,'origin_catalog_id')&&result.origin_catalog_id!==project)invalid(); - if(['execution_approve_external','execution_study_approve'].includes(action)){ - const grant=result.grant,expected=arguments_.expected_digest??arguments_.expected_material_sha256; - if(result.format!=='project_current_execution_approval_v1'||result.current_local!==true||!id(grant?.id)||grant.catalog_id!==project||grant.consumer_actor_id!==arguments_.consumer_actor_id||grant.material_sha256!==expected||grant.revoked_at!==null||!Number.isSafeInteger(grant.created_at)||!Number.isSafeInteger(grant.expires_at)||grant.expires_at<=grant.created_at)invalid(); - } - if(action==='execution_cancel'&&result.run_id!==arguments_.run_id)invalid(); - if(['execution_study_admit','execution_study_stop'].includes(action)&&result.study_id!==arguments_.study_id)invalid(); - if(action==='execution_study_admit'&&(result.trial_id!==arguments_.trial_id||result.reservation?.trial_id!==result.trial_id||result.reservation?.run_id!==result.run_id))invalid(); - const actions={execution_producer_start:'start',execution_generation_resume:'resume',execution_grounded_review:'review',execution_producer_decide:'decide',execution_producer_cancel:'cancel'}; - if(Object.hasOwn(actions,action)){ - const family=arguments_.family??(action==='execution_generation_resume'?'generation_history':'grounded_history'); - if(result.format!=='project_producer_action_v1'||result.family!==family||result.action!==actions[action]||!id(result.producer_id)||(arguments_.producer_id&&result.producer_id!==arguments_.producer_id)||(arguments_.document?.request_id&&result.producer_id!==arguments_.document.request_id))invalid(); - } - } - if(definition.mutation){state={...state,project:{...state.project,checkpoint:value.checkpoint}};pending=null;showState();} - return value.value; - } - async function explore(ticket,more=false){ - const action=$('project-explore-kind').value,offset=more?exploreOffset:0,args={offset,limit:40}; - if(['policies','lineage'].includes(action))args.origin_catalog_id=state.project.project_id; - if(action==='producers')args.family=$('project-producer-family').value; - if(action==='data_query'){if($('project-data-search').value)args.q=$('project-data-search').value;if($('project-data-kind').value)args.kind=$('project-data-kind').value;} - const value=await m2Request(action,args,ticket);if(!value)return; - if(!more)$('project-explore-list').replaceChildren(); - for(const item of value.items){ - const row=document.createElement('li'),button=document.createElement('button');button.type='button'; - const fact=item.study??item.run??item.current??item.value??item,origin=item.origin_catalog_id??fact.ref?.catalog_id??state.project.project_id; - button.textContent=[fact.name??fact.id??item.sha256??item.id??'Saved record',fact.kind??fact.format??item.family??'',fact.state??fact.review??item.availability?.status??'',fact.revision?`revision ${fact.revision}`:''].filter(Boolean).join(' · '); - button.onclick=()=>run(ticket=>inspectItem(action,item,origin,ticket),{clean:true});row.append(button);$('project-explore-list').append(row); - } - exploreOffset=value.offset+value.items.length;exploreTotal=value.total;$('project-explore-more').hidden=exploreOffset>=exploreTotal; - $('project-explore-summary').textContent=`Showing ${value.total?offset+1:0}–${exploreOffset} of ${exploreTotal} saved records.`; - } - async function inspectItem(category,item,origin,ticket){ - const fact=item.study??item.run??item.current??item.value??item; - const entry={category,origin,id:fact.id??item.id,value:fact,checkpoint:checkpoint()}; - const request={data_query:['data_get','record_id'],models:['model_get','model_id'],graphs:['graph_get','graph_id'],recipes:['recipe_get','recipe_id'],studies:['study','study_id'],trials:['trial','trial_id'],runs:['run','run_id'],selections:['selection_get','selection_id']}[category]; - let detail=fact; - if(category==='producers'){detail=await m2Request('producer',{origin_catalog_id:origin,producer_id:entry.id,family:$('project-producer-family').value},ticket);if(!detail)return;} - if(request){const args={[request[1]]:entry.id};if(['studies','trials','runs'].includes(category))args.origin_catalog_id=origin;detail=await m2Request(request[0],args,ticket);if(!detail)return;} - clearExplorationDetail();entry.value=detail.study??detail;entry.saveAction={models:'model_save',graphs:'graph_save',recipes:'recipe_save',studies:'study_save'}[category];explored=entry; - $('project-detail-title').textContent=entry.value.name??`${category==='runs'?'Historical Run':category==='trials'?'Historical Trial':'Saved record'} ${entry.id??''}`; - $('project-detail-facts').append(projectValue(detail)); - if(category==='artifacts'){entry.artifactSha=detail.sha256;$('project-artifact-status').hidden=false;artifactResolutionForm(detail.availability?.state);} - if(category==='models')$('project-model-publish').hidden=false; - if(entry.saveAction&&origin===state.project.project_id){$('project-metadata-form').hidden=false;$('project-metadata-name').value=entry.value.name??'';} - if(category==='data_query'){ - if(entry.value.kind==='field_sequence'){scientificEpoch=ticket;projectScientific.show(entry.value);} - $('project-detail-history').hidden=false;$('project-detail-availability').hidden=false;$('project-rights-form').hidden=false;$('project-selection-form').hidden=false; - $('project-rights-note').value=entry.value.provenance?.rights_note_correction?.note??entry.value.provenance?.rights??'unknown'; - const key=entry.value.task?.endsWith('_classification')?'label':entry.value.task==='image_caption'?'caption':entry.value.task==='text_corpus'||['sequence','mesh','pointcloud','volume','field_sequence'].includes(entry.value.kind)?'note':null; - if(key){entry.annotationKey=key;$('project-data-note-form').hidden=false;$('project-data-note').value=entry.value.annotation?.[key]??'';$('project-data-note-help').textContent=`${entry.value.task.replaceAll('_',' ')} · save a ${key==='label'?'class label':key}.`;$('project-data-note').maxLength=key==='label'?80:4000;$('project-data-review').value=entry.value.review==='human_reviewed'?'human_reviewed':'draft';} - } - if(category==='runs'){entry.document=detail.document;$('project-run-document').hidden=!detail.document;$('project-run-evidence').hidden=false;$('project-run-disclose').hidden=!selectedContracts.has('project_files.expose_holdout');$('project-disclosure-label').hidden=$('project-run-disclose').hidden;} - controls();$('project-detail-title').focus(); - } - function clearExplorationDetail(){ - clearScientific(); - explored=null;historyOffset=0;historyTotal=0;$('project-detail-facts').replaceChildren();$('project-detail-history-list').replaceChildren(); - for(const name of ['project-metadata-form','project-data-note-form','project-rights-form','project-selection-form','project-detail-history','project-detail-history-more','project-detail-availability','project-run-evidence','project-run-document','project-run-disclose','project-disclosure-label','project-model-publish','project-artifact-status','project-artifact-resolve-form'])$(name).hidden=true; - } - async function dataHistory(ticket,more=false){ - if(!explored||explored.category!=='data_query')throw Error('Select saved data first.'); - const value=await m2Request('data_history',{record_id:explored.id,offset:more?historyOffset:0,limit:1},ticket);if(!value)return; - if(!more)$('project-detail-history-list').replaceChildren(); - for(const snapshot of value.items){const row=document.createElement('li');row.append(projectValue(snapshot));$('project-detail-history-list').append(row);} - historyOffset=value.offset+value.items.length;historyTotal=value.total;$('project-detail-history-more').hidden=historyOffset>=historyTotal; - message(`Saved revisions loaded: ${historyOffset} of ${historyTotal}.`); - } - async function metadataSaved(ticket,action,args){ - const value=await m2Request(action,args,ticket);if(!value)return; - const form={model_save:'project-metadata-form',graph_save:'project-metadata-form',recipe_save:'project-metadata-form',study_save:'project-metadata-form',data_annotate:'project-data-note-form',data_rights:'project-rights-form',selection_create:'project-selection-form',search_create:'project-search-form',data_import_image:'project-source-form',data_import_audio:'project-source-form',model_create:'project-model-create-form',study_create:'project-study-create-form',data_import_scientific:'project-scientific-form'}[action]; - if(form)for(const field of $(form).querySelectorAll('input'))if(!['number','file'].includes(field.type))field.value=''; - m2DirtyForms.delete(form);m2Dirty=m2DirtyForms.size>0; - if(!m2Dirty)clearExplorationDetail();await query(ticket);message('Change saved to the project. Load saved records to inspect the new revision.');controls(); - } - $('project-explore-load').onclick=()=>run(ticket=>explore(ticket),{clean:true}); - $('project-explore-more').onclick=()=>run(ticket=>explore(ticket,true),{clean:true}); - $('project-detail-history').onclick=()=>run(ticket=>dataHistory(ticket)); - $('project-detail-history-more').onclick=()=>run(ticket=>dataHistory(ticket,true)); - function artifactResolutionForm(availability){ - $('project-artifact-resolve-form').hidden=availability!=='missing'; - const roots=$('project-artifact-root'),previous=roots.value;roots.replaceChildren(); - for(const root of state.roots){const option=document.createElement('option');option.value=root;option.textContent=root;roots.append(option);} - if(state.roots.includes(previous))roots.value=previous; - } - async function artifactStatus(ticket){ - if(!explored?.artifactSha)throw Error('Select a saved artifact first.'); - const value=await m2Request('artifact_status',{sha256:explored.artifactSha},ticket);if(!value)return; - $('project-detail-facts').append(projectValue(value));artifactResolutionForm(value.state);controls(); - } - $('project-artifact-status').onclick=()=>run(artifactStatus); - $('project-artifact-resolve-form').onsubmit=event=>{event.preventDefault();run(async ticket=>{ - if(!explored?.artifactSha)throw Error('Select a missing artifact first.'); - const expected=explored.artifactSha,value=await m2Request('artifact_resolve',{sha256:expected,root:$('project-artifact-root').value,path:$('project-artifact-path').value},ticket);if(!value)return; - if(value.format!=='project_artifact_resolution_v1'||value.sha256!==expected)throw Error('Artifact resolution observation differs from this artifact.'); - m2DirtyForms.delete('project-artifact-resolve-form');m2Dirty=m2DirtyForms.size>0;$('project-artifact-path').value=''; - $('project-detail-facts').append(projectValue(value));await artifactStatus(ticket);message('Artifact resolution observation saved. Current availability refreshed.'); - });}; - for(const field of ['project-artifact-root','project-artifact-path'])$(field).addEventListener('input',()=>{m2DirtyForms.add('project-artifact-resolve-form');m2Dirty=true;controls();}); - $('project-detail-availability').onclick=()=>run(async ticket=>{const value=await m2Request('data_availability',{record_id:explored.id},ticket);if(value)$('project-detail-facts').append(projectValue(value));}); - $('project-run-evidence').onclick=()=>run(async ticket=>{const value=await m2Request('evidence',{run_id:explored.id,origin_catalog_id:explored.origin},ticket);if(value){$('project-detail-facts').append(projectValue(value));message('Retained evidence read through current disclosure and integrity checks.');}}); - $('project-run-disclose').onclick=()=>run(async ticket=>{const value=await m2Request('expose_holdout',{run_id:explored.id,origin_catalog_id:explored.origin,reason:$('project-disclosure-reason').value},ticket);if(value){$('project-detail-facts').append(projectValue(value));message('Held-out disclosure allowed for this Run on this installation.');}},{clean:true}); - $('project-metadata-form').onsubmit=event=>{event.preventDefault();run(async ticket=>{ - const value=explored.value,name=$('project-metadata-name').value;if(!str(name,120))throw Error('Enter a name up to 120 characters.'); - const args=explored.category==='studies'?{study_id:explored.id,revision:value.revision,name,limits:value.limits,policy:value.policy}:{[{models:'model_id',graphs:'graph_id',recipes:'recipe_id'}[explored.category]]:explored.id,revision:value.revision,document:{...value,name}}; - await metadataSaved(ticket,explored.saveAction,args); - });}; - $('project-data-note-form').onsubmit=event=>{event.preventDefault();run(ticket=>metadataSaved(ticket,'data_annotate',{record_id:explored.id,revision:explored.value.revision,source_revision:explored.value.source_revision,task:explored.value.task,annotation:{[explored.annotationKey]:$('project-data-note').value},groups:explored.value.groups,review:$('project-data-review').value}));}; - $('project-rights-form').onsubmit=event=>{event.preventDefault();run(ticket=>metadataSaved(ticket,'data_rights',{record_id:explored.id,revision:explored.value.revision,source_revision:explored.value.source_revision,note:$('project-rights-note').value}));}; - $('project-selection-form').onsubmit=event=>{event.preventDefault();run(ticket=>metadataSaved(ticket,'selection_create',{document:{name:$('project-selection-name').value,items:[{id:explored.id,revision:explored.value.revision,source_revision:explored.value.source_revision}]}}));}; - $('project-search-form').onsubmit=event=>{event.preventDefault();run(ticket=>metadataSaved(ticket,'search_create',{document:{name:$('project-search-name').value,criteria:{q:$('project-data-search').value,kind:$('project-data-kind').value,review:'',sort:'',task:'',label:'',group:'',rights:''}}}));}; - $('project-source-form').onsubmit=event=>{event.preventDefault();run(async ticket=>{ - const file=$('project-source-file').files?.[0];if(!file||file.size>524288)throw Error('Choose a source file of at most 512 KiB.'); - const bytes=new Uint8Array(await file.arrayBuffer());let raw='';for(const byte of bytes)raw+=String.fromCharCode(byte); - if(ticket!==epoch)return; - const kind=$('project-source-kind').value,args={name:$('project-source-name').value,groups:groups($('project-source-groups').value),rights:$('project-source-rights').value,[kind==='audio'?'wav':'image']:btoa(raw)}; - await metadataSaved(ticket,'data_import_'+kind,args);$('project-source-file').value='';$('project-source-name').value=''; - });}; - for(const field of ['project-metadata-name','project-data-note','project-data-review','project-rights-note','project-selection-name','project-search-name','project-source-file','project-source-name','project-source-groups','project-source-rights'])$(field).addEventListener('input',()=>{const form=field.startsWith('project-source-')?'project-source-form':field.startsWith('project-metadata-')?'project-metadata-form':field.startsWith('project-data-')?'project-data-note-form':field.startsWith('project-rights-')?'project-rights-form':field.startsWith('project-selection-')?'project-selection-form':'project-search-form';m2DirtyForms.add(form);m2Dirty=true;controls();}); - $('project-source-kind').addEventListener('change',()=>{m2DirtyForms.add('project-source-form');m2Dirty=true;controls();}); - $('project-explore-kind').addEventListener('change',controls); - $('project-definitions-load').onclick=()=>run(async ticket=>{ - const value=await m2Request('definitions',{},ticket);if(!value)return; - if(!Array.isArray(value.recipes))throw Error('No model template definitions are available.'); - modelTemplates=value.recipes.filter(item=>item.model_template).map(item=>item.model_template);templateBinding=state.binding; - $('project-model-template').replaceChildren(); - for(const [index,template] of modelTemplates.entries()){const option=document.createElement('option');option.value=String(index);option.textContent=template.name;$('project-model-template').append(option);} - controls();message(modelTemplates.length?'Available model templates loaded.':'This installation has no model templates.'); - },{clean:true}); - $('project-model-create-form').onsubmit=event=>{event.preventDefault();run(async ticket=>{ - if(templateBinding!==state.binding)throw Error('Load model templates for this project first.'); - const template=modelTemplates[Number($('project-model-template').value)];if(!template)throw Error('Choose a model template.'); - const document=JSON.parse(JSON.stringify(template));document.name=$('project-model-create-name').value; - await metadataSaved(ticket,'model_create',document); - });}; - $('project-model-publish').onclick=()=>run(ticket=>metadataSaved(ticket,'model_publish',{model_id:explored.id,revision:explored.value.revision}),{clean:true}); - for(const field of ['project-model-template','project-model-create-name'])$(field).addEventListener('input',()=>{m2DirtyForms.add('project-model-create-form');m2Dirty=true;controls();}); - $('project-study-create-form').onsubmit=event=>{event.preventDefault();run(async ticket=>{ - const limits={};for(const [key,field] of [['attempt_slots','attempts'],['admitted_wall_seconds','seconds'],['retained_bytes','retained'],['peak_staging_bytes','staging']]){const value=Number($('project-study-'+field).value);if(!Number.isSafeInteger(value)||value<1)throw Error('Study budget values must be positive whole numbers.');limits[key]=value;} - const metric=$('project-study-metric').value;if(!sha(metric))throw Error('Use the exact SHA256 of a saved metric definition.'); - await metadataSaved(ticket,'study_create',{name:$('project-study-create-name').value,limits,policy:{format:'selection_policy_v1',metric_definition_sha256:metric,checkpoint_rule:$('project-study-checkpoint').value,replicate_reduce:$('project-study-replicates').value,required_capabilities:[],numerical_acceptance:$('project-study-numerical').value,tie_break:'trial_id'}}); - });}; - function scientificReferenceHash(reference){ - if(reference.status!=='available'||!sha(reference.observed_sha256))return null; - if(Object.hasOwn(reference,'sha256'))return sha(reference.sha256)&&reference.integrity==='verified'&&reference.observed_sha256===reference.sha256?reference.observed_sha256:null; - return reference.integrity==='unverified'?reference.observed_sha256:null; - } - async function sourceReferences(ticket,more){ - if(!registeredSource||registeredSource.binding!==state.binding)throw Error('Register this source for the current project binding first.'); - const {origin_catalog_id,project_id,manifest_sha256}=registeredSource; - const value=await m2Request('source_references',{origin_catalog_id,project_id,manifest_sha256,offset:more?registeredSource.next_offset:0,limit:40},ticket);if(!value)return; - if(!more){registeredSource.references=[];$('project-scientific-reference').replaceChildren();} - for(const reference of value.items){ - registeredSource.references.push(reference);const observed=scientificReferenceHash(reference),option=document.createElement('option');option.value=reference.id;option.disabled=observed===null; - const integrity=observed?(Object.hasOwn(reference,'sha256')?'declared digest verified':'observed digest unverified; not pinned in the manifest'):(reference.integrity==='mismatch'?'declared digest mismatch':reference.status??'unavailable'); - option.textContent=`${reference.label??reference.id} · ${integrity}`;$('project-scientific-reference').append(option); - } - registeredSource.next_offset=value.offset+value.items.length;$('project-source-references-more').hidden=registeredSource.next_offset>=value.total; - } - $('project-source-references-more').onclick=()=>run(ticket=>sourceReferences(ticket,true)); - $('project-run-document').onclick=()=>run(async ticket=>{ - const descriptor=explored?.document;if(!descriptor||!sha(descriptor.sha256)||!Number.isSafeInteger(descriptor.bytes)||descriptor.bytes<0||descriptor.bytes>64*1024*1024)throw Error('This retained document cannot be downloaded in this browser. Use its exact project API segments.'); - const pieces=[];let offset=0; - do{ - const limit=262144,value=await m2Request('run_document_segment',{run_id:explored.id,origin_catalog_id:explored.origin,expected_sha256:descriptor.sha256,offset,limit},ticket);if(!value)return; - if(value.format!=='project_run_document_segment_v1'||value.origin_catalog_id!==explored.origin||value.run_id!==explored.id||value.sha256!==descriptor.sha256||value.bytes!==descriptor.bytes||value.offset!==offset||value.limit!==limit||typeof value.base64!=='string')throw Error('Retained document segment differs from the selected document.'); - const raw=atob(value.base64),bytes=Uint8Array.from(raw,char=>char.charCodeAt(0)); - if(bytes.length!==Math.min(limit,descriptor.bytes-offset)||value.next_offset!==(offset+bytes.lengthbyte.toString(16).padStart(2,'0')).join('')!==descriptor.sha256)throw Error('Retained document integrity differs; no download was created.'); - const link=document.createElement('a'),url=URL.createObjectURL(blob);link.href=url;link.download='retained-run-'+explored.id+'.json';link.click();URL.revokeObjectURL(url);message('Exact retained Run document downloaded and verified.'); - }); - $('project-register-form').onsubmit=event=>{event.preventDefault();run(async ticket=>{ - const value=await m2Request('source_register',{root:$('project-files-root').value,manifest_path:$('project-register-path').value},ticket);if(!value)return; - if(!id(value.project_id)||!id(value.origin_catalog_id)||!sha(value.manifest_sha256))throw Error('The registered source identity is unavailable.'); - registeredSource={binding:state.binding,origin_catalog_id:value.origin_catalog_id,project_id:value.project_id,manifest_sha256:value.manifest_sha256,references:[],next_offset:0}; - await sourceReferences(ticket,false); - m2DirtyForms.delete('project-register-form');m2Dirty=m2DirtyForms.size>0;controls();message('Source manifest saved. Select one exact declared data reference to import.'); - });}; - $('project-scientific-form').onsubmit=event=>{event.preventDefault();run(async ticket=>{ - if(!registeredSource||registeredSource.binding!==state.binding)throw Error('Register a local source for this project binding first.'); - const reference=registeredSource.references.find(item=>item.id===$('project-scientific-reference').value),observed=reference&&scientificReferenceHash(reference);if(!observed)throw Error('Choose an available data reference with a current observed digest. Declared digests must match and be verified.'); - const {origin_catalog_id,project_id,manifest_sha256}=registeredSource; - await metadataSaved(ticket,'data_import_scientific',{snapshot:{origin_catalog_id,project_id,manifest_sha256},reference_id:reference.id,expected_sha256:observed,document:{name:$('project-scientific-name').value,groups:groups($('project-scientific-groups').value),rights:$('project-scientific-rights').value}}); - });}; - for(const [form,fields] of [['project-study-create-form',['project-study-create-name','project-study-metric','project-study-attempts','project-study-seconds','project-study-retained','project-study-staging','project-study-checkpoint','project-study-replicates','project-study-numerical']],['project-register-form',['project-register-path']],['project-scientific-form',['project-scientific-reference','project-scientific-name','project-scientific-groups','project-scientific-rights']]])for(const field of fields)$(field).addEventListener('input',()=>{m2DirtyForms.add(form);m2Dirty=true;controls();}); - function executionControls(){ - const prepared=!!executionPrepared&&executionPrepared.binding===state?.binding,approved=!!executionApproval&&executionApproval.binding===state?.binding; - producerControls();nativeControls(); - $('project-execution-reconcile').disabled=busy||blocked||!state?.project||!['open','recovery_required'].includes(state.state)||!selectedContracts.has('project_files.execution_reconcile_current'); - $('project-execution-graphs-more').disabled=!m2Allowed('graphs');$('project-execution-graphs-more').hidden=executionGraphOffset>=executionGraphTotal; - $('project-study-trials-more').disabled=!executionStudy||!m2Allowed('study');$('project-study-trials-more').hidden=studyTrialOffset>=studyTrialTotal; - $('project-execution-health').disabled=!preparationRecoveryAllowed('execution_health'); - $('project-execution-health-more').disabled=!preparationRecoveryAllowed('execution_health');$('project-execution-health-more').hidden=executionOffset>=executionTotal; - $('project-execution-graphs').disabled=!m2Allowed('graphs'); - $('project-execution-preflight-fields').disabled=!executionGraphs.length||!m2Allowed('execution_preflight_external'); - $('project-execution-approval-fields').disabled=!prepared||!m2Allowed('execution_approve_external'); - $('project-execution-submit-fields').disabled=!prepared||!approved||!m2Allowed('execution_submit_external'); - $('project-execution-cancel-fields').disabled=!m2Allowed('execution_cancel'); - $('project-study-execution-load').disabled=explored?.category!=='studies'||!m2Allowed('study'); - $('project-study-continue-fields').disabled=!executionStudy||!m2Allowed('execution_study_continue'); - $('project-study-approval-fields').disabled=!executionStudy||!executionTrials.length||!m2Allowed('execution_study_approve'); - $('project-study-admit-fields').disabled=!executionStudy||!studyApproval||!m2Allowed('execution_study_admit'); - $('project-study-stop-fields').disabled=!executionStudy||!m2Allowed('execution_study_stop'); - } - function executionFact(value){$('project-execution-facts').replaceChildren(projectValue(value));} - function nativePhaseOK(value,phaseId=null){ - return exact(value,['format','origin_catalog_id','phase_id','phase','run_id','state','spec_sha256','receipt_sha256'])&&value.format==='project_native_phase_v1'&&value.origin_catalog_id===state.project.project_id&&id(value.phase_id)&&(!phaseId||value.phase_id===phaseId)&&['probe','train','verify'].includes(value.phase)&&(value.run_id===null||id(value.run_id))&&['prepared','ready','go_intent','completed','failed','unknown'].includes(value.state)&&sha(value.spec_sha256)&&(value.receipt_sha256===null||sha(value.receipt_sha256)); - } - function nativeValidationOK(value,revision){ - const fields=['status','valid','errors','validation_token','graph_revision','execution_sha256','release','runtime']; - if(!value||typeof value!=='object'||Array.isArray(value)||!fields.every(field=>Object.hasOwn(value,field))||!Object.keys(value).every(field=>fields.includes(field)||field==='selection_policy')||!str(value.status,120)||typeof value.valid!=='boolean'||!Array.isArray(value.errors)||value.errors.length>100||!positive(value.graph_revision)||value.graph_revision!==revision||!sha(value.execution_sha256)||!['release','runtime'].every(field=>value[field]===null||typeof value[field]==='object'&&!Array.isArray(value[field])))return false; - if(!value.errors.every(error=>exact(error,['path','message','code'])&&Object.values(error).every(part=>str(part,2000,true))))return false; - return value.valid?value.status==='valid'&&value.errors.length===0&&sha(value.validation_token)&&value.release!==null&&value.runtime!==null&&value.runtime.available===true:value.errors.length>0&&value.status===value.errors[0].code&&value.validation_token===null; - } - function nativeAdmissionOK(value){return exact(value,['format','origin_catalog_id','run_id','request_sha256'])&&value.format==='project_run_admission_v1'&&value.origin_catalog_id===state.project.project_id&&id(value.run_id)&&sha(value.request_sha256);} - function nativeControls(){ - $('project-native-graphs').disabled=!m2Allowed('graphs');$('project-native-more').disabled=!m2Allowed('graphs');$('project-native-more').hidden=nativeOffset>=nativeTotal; - $('project-native-preflight-fields').disabled=!nativeGraphs.length||!m2Allowed('native_preflight'); - $('project-native-submit-fields').disabled=!nativePrepared||nativePrepared.binding!==state?.binding||nativePrepared.checkpoint!==checkpoint()||!m2Allowed('native_submit'); - $('project-native-retry-fields').disabled=!m2Allowed('native_retry'); - $('project-native-reconcile-fields').disabled=!preparationRecoveryAllowed('native_reconcile'); - $('project-native-pending-retry').disabled=!nativePending||nativePending.body.binding!==state?.binding||!preparationRecoveryAllowed(nativePending.action); - } - async function loadNativeGraphs(ticket,more=false){ - const value=await m2Request('graphs',{offset:more?nativeOffset:0,limit:40},ticket);if(!value)return; - if(!more){nativeGraphs=[];nativePrepared=null;$('project-native-graph').replaceChildren();} - for(const graph of value.items.filter(graph=>graph.recipe!=='external_recipe')){if(!id(graph.id)||!positive(graph.revision))throw Error('Saved native graph has invalid identity.');nativeGraphs.push(graph);const option=document.createElement('option');option.value=graph.id;option.textContent=`${graph.name??graph.id} · ${graph.recipe??'native'} · revision ${graph.revision}`;$('project-native-graph').append(option);} - nativeOffset=value.offset+value.items.length;nativeTotal=value.total;controls();message('Saved graph metadata loaded. No native probe or Run started.'); - } - $('project-native-graphs').onclick=()=>run(ticket=>loadNativeGraphs(ticket));$('project-native-more').onclick=()=>run(ticket=>loadNativeGraphs(ticket,true)); - $('project-native-graph').addEventListener('change',()=>{nativePrepared=null;$('project-native-probe-confirm').checked=false;$('project-native-submit-confirm').checked=false;controls();}); - $('project-native-preflight-form').onsubmit=event=>{event.preventDefault();run(async ticket=>{ - const graph=nativeGraphs.find(value=>value.id===$('project-native-graph').value);if(!graph||!$('project-native-probe-confirm').checked)throw Error('Select a saved native graph and explicitly authorize its current CPU probe.'); - nativePrepared=null;controls(); - const value=await m2Request('native_preflight',{graph_id:graph.id,revision:graph.revision},ticket);if(!value)return; - if(!nativeValidationOK(value,graph.revision))throw Error('Native validation differs from the selected saved graph.'); - nativePending=null;nativePrepared=value.valid?{binding:state.binding,checkpoint:checkpoint(),graph_id:graph.id,revision:graph.revision,validation_token:value.validation_token}:null; - executionFormSaved('project-native-preflight-form');$('project-native-probe-confirm').checked=false;$('project-native-submit-confirm').checked=false;$('project-native-facts').replaceChildren(projectValue(value));$('project-native-pending').textContent='Native validation acknowledgement saved.';controls();message(value.valid?'Native validation succeeded. Starting a Run requires a separate explicit action.':'Native validation reported errors. No Run was started.'); - });}; - $('project-native-submit-form').onsubmit=event=>{event.preventDefault();run(async ticket=>{ - if(!nativePrepared||nativePrepared.binding!==state.binding||nativePrepared.checkpoint!==checkpoint()||!$('project-native-submit-confirm').checked)throw Error('Validate this current graph and separately authorize starting its Run.'); - const value=await m2Request('native_submit',{graph_id:nativePrepared.graph_id,graph_revision:nativePrepared.revision,validation_token:nativePrepared.validation_token},ticket);if(!value)return;if(!nativeAdmissionOK(value))throw Error('Native admission differs from the selected project.'); - nativePending=null;nativePrepared=null;$('project-native-run-id').value=value.run_id;$('project-execution-run-id').value=value.run_id;$('project-native-submit-confirm').checked=false;executionFormSaved('project-native-submit-form');$('project-native-facts').replaceChildren(projectValue(value));$('project-native-pending').textContent='Native admission acknowledged. Refresh current custody to inspect execution.';controls();message($('project-native-pending').textContent); - });}; - $('project-native-retry-form').onsubmit=event=>{event.preventDefault();run(async ticket=>{ - const run_id=$('project-native-run-id').value;if(!id(run_id)||!$('project-native-retry-confirm').checked)throw Error('Enter a current native Run ID and explicitly authorize a new attempt.'); - const value=await m2Request('native_retry',{run_id},ticket);if(!value)return;if(!nativeAdmissionOK(value)||value.run_id===run_id)throw Error('Native retry admission differs from the selected project.'); - nativePending=null;$('project-native-run-id').value=value.run_id;$('project-execution-run-id').value=value.run_id;$('project-native-retry-confirm').checked=false;executionFormSaved('project-native-retry-form');$('project-native-facts').replaceChildren(projectValue(value));$('project-native-pending').textContent='Native retry admission acknowledged. A saved admission is not proof of completion.';controls();message($('project-native-pending').textContent); - });}; - $('project-native-pending-retry').onclick=()=>run(async ticket=>{ - if(!nativePending||nativePending.body.binding!==state.binding)throw Error('This tab has no exact current pending native request.'); - const saved=nativePending,{binding,expected_checkpoint,request_key,...args}=saved.body;if(saved.action==='native_preflight'){nativePrepared=null;controls();}const value=await m2Request(saved.action,args,ticket);if(!value)return; - if(saved.action==='native_preflight'){ - if(!nativeValidationOK(value,args.revision))throw Error('Native validation differs from the original saved graph.'); - nativePrepared=value.valid?{binding:state.binding,checkpoint:checkpoint(),graph_id:args.graph_id,revision:args.revision,validation_token:value.validation_token}:null; - executionFormSaved('project-native-preflight-form');$('project-native-probe-confirm').checked=false; - }else{ - if(!nativeAdmissionOK(value)||saved.action==='native_retry'&&value.run_id===args.run_id)throw Error('Native acknowledgement differs from the selected project.');nativePrepared=null;$('project-native-run-id').value=value.run_id;$('project-execution-run-id').value=value.run_id; - const kind=saved.action==='native_submit'?'submit':'retry';executionFormSaved('project-native-'+kind+'-form');$('project-native-'+kind+'-confirm').checked=false; - } - nativePending=null;$('project-native-facts').replaceChildren(projectValue(value));$('project-native-pending').textContent='Exact pending native request acknowledged. No new request key was created.';controls();message($('project-native-pending').textContent); - }); - $('project-native-reconcile-form').onsubmit=event=>{event.preventDefault();run(async ticket=>{ - const phase_id=$('project-native-phase-id').value;if(!id(phase_id))throw Error('Enter the original current local phase ID.'); - const value=await m2Request('native_reconcile',{phase_id},ticket);if(!value)return;if(!nativePhaseOK(value,phase_id))throw Error('Native reconciliation differs from the original phase.'); - executionFormSaved('project-native-reconcile-form');$('project-native-facts').replaceChildren(projectValue(value));message('Original current native phase observed. Reconciliation does not start or resume it. Refresh project status before another action.'); - });}; - for(const [form,fields] of [['project-native-preflight-form',['project-native-probe-confirm']],['project-native-submit-form',['project-native-submit-confirm']],['project-native-retry-form',['project-native-run-id','project-native-retry-confirm']],['project-native-reconcile-form',['project-native-phase-id']]])for(const field of fields)$(field).addEventListener(field.endsWith('confirm')?'change':'input',()=>{m2DirtyForms.add(form);m2Dirty=true;controls();}); - function localConsumer(){const actor=window.TuldokAuth.identity?.()?.actor_id;return id(actor)?actor:'';} - async function currentHealth(ticket,more=false){ - const value=await m2Request('execution_health',{offset:more?executionOffset:0,limit:40},ticket);if(!value)return; - if(value.format!=='project_execution_health_v1'||!Array.isArray(value.active_run_ids)||typeof value.drain_required!=='boolean'||value.offset!==(more?executionOffset:0)||value.limit!==40||value.active_run_ids.length!==Math.min(40,Math.max(0,value.active_count-value.offset)))throw Error('Unsupported current custody observation.'); - let nativeTotal=0; - if(selectedVersions.get('project_files.execution_health')>=2){ - const page=value.native_phases,ids=page?.items?.map(item=>item.phase_id); - if(!page||!exact(page,['items','total','offset','limit'])||!Array.isArray(page.items)||!Number.isSafeInteger(page.total)||page.total<0||page.offset!==(more?executionOffset:0)||page.limit!==40||page.items.length!==Math.min(40,Math.max(0,page.total-page.offset))||!page.items.every(item=>nativePhaseOK(item))||ids.join()!==[...new Set(ids)].sort().join())throw Error('Current native phases differ from the selected project or continuation.'); - nativeTotal=page.total;if(!more)$('project-native-phases').replaceChildren(); - for(const phase of page.items){const li=document.createElement('li'),button=document.createElement('button');button.type='button';button.textContent=`${phase.phase_id} · ${phase.phase} · ${phase.state}`;button.onclick=()=>{$('project-native-phase-id').value=phase.phase_id;$('project-native-phase-id').focus();};li.append(button);$('project-native-phases').append(li);} - }else if(Object.hasOwn(value,'native_phases'))throw Error('Version 1 cannot represent native phase custody. Refresh contracts.'); - executionOffset=(more?executionOffset:0)+40;executionTotal=Math.max(value.active_count,nativeTotal);executionFact(value); - $('project-execution-summary').textContent=`${value.active_count} current active or unresolved Runs; ${nativeTotal} original current native phases. Local owner ${value.local_owner_active?'active':'inactive'}. ${value.drain_required?'Explicit reconciliation must drain current custody before closing or extracting.':value.available?'The project projection is available.':'The current outcome needs explicit reconciliation.'}`; - if(value.active_run_ids.length)$('project-execution-run-id').value=value.active_run_ids[0];controls(); - } - $('project-execution-health').onclick=()=>run(ticket=>currentHealth(ticket)); - $('project-execution-health-more').onclick=()=>run(ticket=>currentHealth(ticket,true)); - $('project-execution-reconcile').onclick=()=>run(async ticket=>{const value=await m2Request('execution_reconcile_current',{},ticket);if(!value)return;executionApproval=null;studyApproval=null;executionFact(value);controls();message(value.available?'Current local custody reconciled and drained. No imported admission was started.':'Current reconciliation remains unavailable; custody is still fenced.');}); - async function loadExecutionGraphs(ticket,more=false){ - const value=await m2Request('graphs',{offset:more?executionGraphOffset:0,limit:40},ticket);if(!value)return; - if(!more){executionGraphs=[];$('project-execution-graph').replaceChildren();}const graphs=value.items.filter(graph=>graph.recipe==='external_recipe');executionGraphs.push(...graphs);executionGraphOffset=value.offset+value.items.length;executionGraphTotal=value.total;executionPrepared=null;executionApproval=null; - for(const graph of graphs){const option=document.createElement('option');option.value=graph.id;option.textContent=`${graph.name} · revision ${graph.revision}`;$('project-execution-graph').append(option);} - $('project-execution-consumer').value=localConsumer();$('project-study-consumer').value=localConsumer();controls();message(executionGraphs.length?'Select an external graph and inspect its exact current material.':'No external graphs on this page. Create one through the named external graph operation.'); - } - $('project-execution-graphs').onclick=()=>run(ticket=>loadExecutionGraphs(ticket),{clean:true}); - $('project-execution-graphs-more').onclick=()=>run(ticket=>loadExecutionGraphs(ticket,true),{clean:true}); - $('project-execution-graph').addEventListener('change',()=>{executionPrepared=null;executionApproval=null;$('project-execution-grant').textContent='No current local approval selected.';controls();}); - $('project-execution-preflight-form').onsubmit=event=>{event.preventDefault();run(async ticket=>{ - const graph=executionGraphs.find(value=>value.id===$('project-execution-graph').value);if(!graph)throw Error('Select a saved external graph.'); - const value=await m2Request('execution_preflight_external',{graph_id:graph.id,revision:graph.revision},ticket);if(!value)return; - if(!sha(value.material_sha256)||value.graph_revision!==graph.revision)throw Error('Current material does not match the selected graph revision.'); - executionPrepared={binding:state.binding,graph_id:graph.id,graph_revision:graph.revision,expected_digest:value.material_sha256};executionApproval=null;$('project-execution-confirm').checked=false;executionFact(value);controls(); - message('Exact current material inspected. Review its sources, inputs and runtime before approving. No Run has been admitted.'); - });}; - $('project-execution-approval-form').onsubmit=event=>{event.preventDefault();run(async ticket=>{ - if(!executionPrepared||executionPrepared.binding!==state.binding)throw Error('Inspect the exact current material first.'); - if(!$('project-execution-confirm').checked)throw Error('Explicitly approve the reviewed material before granting permission.'); - const consumer=$('project-execution-consumer').value,ttl=Number($('project-execution-ttl').value);if(!id(consumer)||!Number.isInteger(ttl)||ttl<60||ttl>3600)throw Error('Choose the current execution actor and an approval lifetime of 60–3600 seconds.'); - const {binding,...prepared}=executionPrepared,value=await m2Request('execution_approve_external',{...prepared,consumer_actor_id:consumer,ttl_seconds:ttl},ticket);if(!value)return; - if(value.format!=='project_current_execution_approval_v1'||value.current_local!==true||value.grant?.material_sha256!==prepared.expected_digest||value.grant.consumer_actor_id!==consumer||!id(value.grant.id))throw Error('Current local approval does not match the reviewed request.'); - executionFormSaved('project-execution-approval-form');executionApproval={binding:state.binding,grant:value.grant};$('project-execution-grant').textContent=`Current local approval ${value.grant.id} for actor ${consumer}, expires ${new Date(value.grant.expires_at*1000).toLocaleString()}.`; - controls();message('Current local approval granted. Starting the Run is a separate explicit action.'); - });}; - $('project-execution-submit-form').onsubmit=event=>{event.preventDefault();run(async ticket=>{ - if(executionPrepared?.binding!==state.binding||executionApproval?.binding!==state.binding)throw Error('Review and approve the current material on this installation first.'); - const {binding,...prepared}=executionPrepared,value=await m2Request('execution_submit_external',{...prepared,approval_id:executionApproval.grant.id},ticket);if(!value)return; - $('project-execution-run-id').value=value.run_id;executionApproval=null;executionFact(value);controls();message(`Admission saved for Run ${value.run_id}. This acknowledges durable intent; refresh current custody to inspect execution.`); - });}; - $('project-execution-cancel-form').onsubmit=event=>{event.preventDefault();run(async ticket=>{ - const run_id=$('project-execution-run-id').value;if(!id(run_id))throw Error('Choose a current local Run ID.'); - const value=await m2Request('execution_cancel',{run_id},ticket);if(!value)return;executionFact(value);message('Cancellation intent saved. Refresh current custody to establish whether execution has ceased.'); - });}; - $('project-study-execution-load').onclick=()=>run(async ticket=>{ - if(explored?.category!=='studies'||explored.origin!==state.project.project_id)throw Error('Select a current-namespace Study in the scientific history view.'); - const value=await m2Request('study',{study_id:explored.id,origin_catalog_id:explored.origin,offset:0,limit:40},ticket);if(!value)return; - executionStudy=value.study;studyApproval=null;executionTrials=value.trials.items;studyTrialOffset=value.trials.offset+value.trials.items.length;studyTrialTotal=value.trials.total;$('project-study-execution-trial').replaceChildren(); - for(const trial of executionTrials){const option=document.createElement('option');option.value=trial.id;option.textContent=trial.id;$('project-study-execution-trial').append(option);} - $('project-study-consumer').value=localConsumer();$('project-study-execution-summary').textContent=`${executionStudy.name} · revision ${executionStudy.revision} · epoch ${executionStudy.admission_epoch} · ${executionStudy.state}. ${value.trials.total} prepared Trials.`;controls(); - },{clean:true}); - $('project-study-trials-more').onclick=()=>run(async ticket=>{const value=await m2Request('study',{study_id:executionStudy.id,origin_catalog_id:state.project.project_id,revision:executionStudy.revision,offset:studyTrialOffset,limit:40},ticket);if(!value)return;for(const trial of value.trials.items){executionTrials.push(trial);const option=document.createElement('option');option.value=trial.id;option.textContent=trial.id;$('project-study-execution-trial').append(option);}studyTrialOffset=value.trials.offset+value.trials.items.length;studyTrialTotal=value.trials.total;controls();}); - $('project-study-execution-trial').addEventListener('change',()=>{studyApproval=null;controls();}); - $('project-study-continue-form').onsubmit=event=>{event.preventDefault();run(async ticket=>{ - const value=await m2Request('execution_study_continue',{study_id:executionStudy.id,revision:executionStudy.revision,admission_epoch:executionStudy.admission_epoch},ticket);if(!value)return;executionStudy=value;controls();$('project-study-execution-summary').textContent=`Current epoch ${value.admission_epoch} · revision ${value.revision} · ${value.state}.`;message('Current Study epoch saved. No Trial has been admitted by this action.'); - });}; - $('project-study-approval-form').onsubmit=event=>{event.preventDefault();run(async ticket=>{ - const trial_id=$('project-study-execution-trial').value,consumer_actor_id=$('project-study-consumer').value;if(!id(trial_id)||!id(consumer_actor_id))throw Error('Select a prepared Trial and current execution actor.'); - const trial=await m2Request('trial',{trial_id,origin_catalog_id:state.project.project_id},ticket);if(!trial)return; - const value=await m2Request('execution_study_approve',{study_id:executionStudy.id,trial_id,expected_material_sha256:trial.material.sha256,consumer_actor_id},ticket);if(!value)return;executionFormSaved('project-study-approval-form');studyApproval={binding:state.binding,trial_id,grant:value.grant};executionFact(value);controls();message('Exact Trial material approved locally. Admission is a separate explicit action.'); - });}; - $('project-study-admit-form').onsubmit=event=>{event.preventDefault();run(async ticket=>{ - if(studyApproval?.binding!==state.binding||studyApproval.trial_id!==$('project-study-execution-trial').value)throw Error('Approve this exact Trial under current local authority first.'); - const value=await m2Request('execution_study_admit',{study_id:executionStudy.id,revision:executionStudy.revision,admission_epoch:executionStudy.admission_epoch,trial_id:studyApproval.trial_id,approval_id:studyApproval.grant.id},ticket);if(!value)return; - $('project-execution-run-id').value=value.run_id;studyApproval=null;executionStudy=null;executionFact(value);controls();message('Trial admission and budget reservation saved. Reload the Study before another epoch action; refresh current custody for execution status.'); - });}; - $('project-study-stop-form').onsubmit=event=>{event.preventDefault();run(async ticket=>{ - const value=await m2Request('execution_study_stop',{study_id:executionStudy.id,revision:executionStudy.revision},ticket);if(!value)return;executionStudy=null;studyApproval=null;executionFact(value);controls();message('Finite Study epoch closure saved and cancellation requested. Current child custody must still prove cessation.'); - });}; - function producerControls(){ - const family=$('project-producer-task').value,current=!!producerCurrent&&producerCurrent.binding===state?.binding; - $('project-producer-health').disabled=!m2Allowed('execution_producer_health');$('project-producer-health-more').disabled=!m2Allowed('execution_producer_health');$('project-producer-health-more').hidden=producerHealthOffset>=producerHealthTotal; - $('project-producer-start-fields').disabled=!m2Allowed('execution_producer_start'); - $('project-producer-source-load').disabled=explored?.category!=='data_query'||!m2Allowed('data_get'); - $('project-producer-current-load').disabled=explored?.category!=='producers'||explored.origin!==state?.project?.project_id||!m2Allowed('producer'); - $('project-producer-label-fields').hidden=family!=='text_proposal_history'; - $('project-producer-count-fields').hidden=!['generation_history','grounded_history'].includes(family); - $('project-producer-generation-fields').hidden=family!=='generation_history'; - $('project-producer-resume-fields').disabled=!current||producerCurrent.family!=='generation_history'||!m2Allowed('execution_generation_resume'); - $('project-producer-review-fields').disabled=!current||producerCurrent.family!=='grounded_history'||!m2Allowed('execution_grounded_review'); - $('project-producer-decision-fields').disabled=!current||!['caption_proposal_history','text_proposal_history'].includes(producerCurrent.family)||!m2Allowed('execution_producer_decide'); - $('project-producer-cancel-fields').disabled=!current||!m2Allowed('execution_producer_cancel'); - } - async function producerHealth(ticket,more=false){const value=await m2Request('execution_producer_health',{offset:more?producerHealthOffset:0,limit:40},ticket);if(!value)return;producerHealthOffset=value.offset+value.items.length;producerHealthTotal=value.total;executionFact(value);$('project-producer-health-summary').textContent=`${value.total} current local producer admissions. ${value.fenced?'Current custody is fenced.':'Inspect each current worker and provider outcome before closing.'}`;controls();} - $('project-producer-health').onclick=()=>run(ticket=>producerHealth(ticket)); - $('project-producer-health-more').onclick=()=>run(ticket=>producerHealth(ticket,true)); - function executionFormSaved(form){m2DirtyForms.delete(form);m2Dirty=m2DirtyForms.size>0;} - $('project-producer-task').addEventListener('change',()=>{producerSource=null;$('project-producer-source-summary').textContent='Select matching saved data as source.';controls();}); - $('project-producer-source-load').onclick=()=>run(async ticket=>{ - if(explored?.category!=='data_query')throw Error('Select saved data in the scientific history view.'); - const value=await m2Request('data_get',{record_id:explored.id},ticket);if(!value)return; - const family=$('project-producer-task').value,kind=family==='caption_proposal_history'?'image':'text'; - if(family==='generation_history'||value.kind!==kind)throw Error(`This task requires selected ${kind} data.`); - producerSource={binding:state.binding,source_id:value.id,revision:value.revision,source_revision:value.source_revision};$('project-producer-source-summary').textContent=`${value.name} · revision ${value.revision} · source revision ${value.source_revision}`;controls(); - }); - $('project-producer-start-form').onsubmit=event=>{event.preventDefault();run(async ticket=>{ - const family=$('project-producer-task').value;if(!$('project-producer-confirm').checked)throw Error('Explicitly authorize this model request.'); - const instruction=$('project-producer-instruction').value,seed=Number($('project-producer-seed').value); - if(!Number.isInteger(seed)||seed<0||seed>4294967295)throw Error('Use a nonnegative 32-bit seed.'); - const document={server_url:$('project-producer-url').value,model:$('project-producer-model').value,seed}; - if($('project-producer-transport').value==='typed'){document.protocol='pumas_typed_v1';document.profile=$('project-producer-profile').value||null;if(family!=='generation_history')document.seed=null;} - if(family==='generation_history'){ - Object.assign(document,{prompt:instruction,count:Number($('project-producer-count').value),strategy:$('project-producer-strategy').value,session_id:$('project-producer-session').value,width:Number($('project-producer-width').value),height:Number($('project-producer-height').value)}); - if(document.strategy==='varied'){document.prompt_url=$('project-producer-prompt-url').value;document.prompt_model=$('project-producer-prompt-model').value;} - }else{ - if(producerSource?.binding!==state.binding)throw Error('Load exact saved source revisions for this project first.'); - const {binding,...source}=producerSource;Object.assign(document,source,{instruction}); - if(family==='grounded_history')document.count=Number($('project-producer-count').value);else document.request_id=key(); - if(family==='text_proposal_history')document.labels=$('project-producer-labels').value.split('\n').filter(value=>value!==''); - } - const value=await m2Request('execution_producer_start',{family,document},ticket);if(!value)return; - executionFormSaved('project-producer-start-form');$('project-producer-confirm').checked=false;producerCurrent=null;executionFact(value);controls();message(`Producer admission saved: ${value.producer_id}. Read its saved history for captured results and current observations.`); - });}; - $('project-producer-current-load').onclick=()=>run(async ticket=>{ - if(explored?.category!=='producers'||explored.origin!==state.project.project_id)throw Error('Select current-namespace producer history first.'); - const family=explored.value.family,value=await m2Request('producer',{family,producer_id:explored.id,origin_catalog_id:explored.origin,entries_offset:0,entries_limit:40},ticket);if(!value)return; - producerCurrent={binding:state.binding,family,producer_id:explored.id,job:value.job};$('project-producer-current-summary').textContent=`${family.replaceAll('_',' ')} · ${explored.id} · ${value.status}. Retained history alone does not grant current authority.`; - $('project-producer-candidate').replaceChildren();for(const candidate of value.job.candidates??[]){const option=document.createElement('option');option.value=candidate.id;option.textContent=`${candidate.text} · ${candidate.status}`;$('project-producer-candidate').append(option);}controls(); - },{clean:true}); - async function producerAction(ticket,action,document){ - if(producerCurrent?.binding!==state.binding)throw Error('Load a current-namespace producer first.'); - const {family,producer_id}=producerCurrent,args={producer_id};if(!['execution_generation_resume','execution_grounded_review'].includes(action))args.family=family;if(document)args.document=document; - const value=await m2Request(action,args,ticket);if(!value)return; - for(const form of ['project-producer-review-form','project-producer-decision-form'])executionFormSaved(form); - producerCurrent=null;executionFact(value);controls();message(action==='execution_producer_cancel'?'Cancellation intent saved. Refresh current producer custody; a retained acknowledgement does not prove cessation.':'Scientific producer action saved. Reload its history before another action.'); - } - $('project-producer-resume-form').onsubmit=event=>{event.preventDefault();run(ticket=>producerAction(ticket,'execution_generation_resume'));}; - $('project-producer-cancel-form').onsubmit=event=>{event.preventDefault();run(ticket=>producerAction(ticket,'execution_producer_cancel'));}; - $('project-producer-decision-form').onsubmit=event=>{event.preventDefault();run(ticket=>{ - const document={revision:producerCurrent.job.revision,decision:$('project-producer-decision').value};if(producerCurrent.family==='text_proposal_history'&&document.decision==='apply_draft')document.labels=producerCurrent.job.config.labels;return producerAction(ticket,'execution_producer_decide',document); - });}; - $('project-producer-review-form').onsubmit=event=>{event.preventDefault();run(ticket=>producerAction(ticket,'execution_grounded_review',{revision:producerCurrent.job.revision,candidate_id:$('project-producer-candidate').value,decision:$('project-producer-review-decision').value,note:$('project-producer-note').value}));}; - - const preparationRecoveryAllowed=action=>!busy&&!!state?.project&&['open','recovery_required'].includes(state.state)&&selectedContracts.has('project_files.'+action); - function candidateControls(){ - const kind=$('project-candidate-kind').value||'package';$('project-candidate-verifier-fields').hidden=kind!=='verifier'; - $('project-candidate-prepare-fields').disabled=!m2Allowed('execution_study_prepare_'+kind); - const reconcile=preparationRecoveryAllowed('execution_study_reconcile_preparation'),abandon=preparationRecoveryAllowed('execution_study_abandon_preparation'); - $('project-candidate-recovery-fields').disabled=!(reconcile||abandon);$('project-candidate-reconcile').disabled=!reconcile;$('project-candidate-abandon').disabled=!abandon; - } - function candidatePreparedOK(value,study,candidate=null,runtime=null){ - const keys=['state','candidate_id','trial','graph','model','runtime_snapshot_sha256',...(Object.hasOwn(value??{},'package_run_id')?['package_run_id','package_sha256']:[])]; - return exact(value,keys)&&value.state==='prepared'&&id(value.candidate_id)&&(!candidate||value.candidate_id===candidate)&&sha(value.runtime_snapshot_sha256)&&(!runtime||value.runtime_snapshot_sha256===runtime)&&value.trial?.study_id===study&&id(value.trial?.id)&&value.trial.material?.catalog_id===state.project.project_id&&value.model?.catalog_id===state.project.project_id&&id(value.graph?.id)&&positive(value.graph?.revision)&&(!Object.hasOwn(value,'package_run_id')||id(value.package_run_id)&&sha(value.package_sha256)); - } - $('project-candidate-prepare-form').onsubmit=event=>{event.preventDefault();run(async ticket=>{ - const study_id=$('project-candidate-study').value,candidate_id=$('project-candidate-id').value,revision=Number($('project-candidate-revision').value),runtime_snapshot_sha256=$('project-candidate-runtime').value,root=$('project-candidate-root').value,directory=$('project-candidate-directory').value,kind=$('project-candidate-kind').value; - if(!id(study_id)||!id(candidate_id)||!positive(revision)||!sha(runtime_snapshot_sha256)||!root||!/^[A-Za-z0-9][A-Za-z0-9_.-]{0,119}$/.test(directory)||!['package','verifier'].includes(kind))throw Error('Choose exact current Study/Candidate identities, revision, publication directory and captured runtime digest.'); - const args={study_id,candidate_id,revision,root,directory,runtime_snapshot_sha256}; - if(kind==='verifier'){args.package_run_id=$('project-candidate-package-run').value;args.package_sha256=$('project-candidate-package-sha').value;if(!id(args.package_run_id)||!sha(args.package_sha256))throw Error('Choose the exact completed package Run and SHA256.');} - const value=await m2Request('execution_study_prepare_'+kind,args,ticket);if(!value)return; - if(!candidatePreparedOK(value,study_id,candidate_id,runtime_snapshot_sha256)||kind==='verifier'&&(value.package_run_id!==args.package_run_id||value.package_sha256!==args.package_sha256))throw Error('Preparation result differs from its current Study, Candidate or captured runtime.'); - executionFormSaved('project-candidate-prepare-form');$('project-candidate-preparation-result').textContent=JSON.stringify(value,null,2);$('project-candidate-preparation-status').textContent='Preparation acknowledged. This saved Trial still requires current local approval and a separate explicit admission.';message('Candidate preparation saved. No Run was launched.'); - });}; - async function candidateRecover(ticket,abandon){ - const study_id=$('project-candidate-recovery-study').value,preparation_key=$('project-candidate-recovery-key').value; - if(!id(study_id)||!/^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/.test(preparation_key))throw Error('Choose the exact current Study and original preparation request key.'); - const action='execution_study_'+(abandon?'abandon':'reconcile')+'_preparation';if(!state?.project||!['open','recovery_required'].includes(state.state)||!selectedContracts.has('project_files.'+action))throw Error('Current preparation recovery is unavailable.'); - const args={study_id,preparation_key};if(abandon){args.reason=$('project-candidate-abandon-reason').value;if(!str(args.reason,1000))throw Error('Enter an explicit reason before abandoning the stopped partial preparation.');} - const value=await m2Request(action,args,ticket);if(!value)return; - if(abandon){if(value.format!=='project_candidate_preparation_abandon_v1'||value.state!=='abandoned'||value.origin_catalog_id!==state.project.project_id||value.study_id!==study_id||value.preparation_key!==preparation_key||value.reason!==args.reason||!sha(value.input_sha256)||!sha(value.observed_checkpoint)||value.candidate?.catalog_id!==state.project.project_id)throw Error('Abandonment differs from the exact current preparation intent.');executionFormSaved('project-candidate-recovery-form');} - else if(!candidatePreparedOK(value,study_id))throw Error('Reconciled preparation belongs to another Study.'); - executionFormSaved('project-candidate-prepare-form');$('project-candidate-preparation-result').textContent=JSON.stringify(value,null,2);$('project-candidate-preparation-status').textContent=abandon?'Stopped partial preparation abandoned; original staging and scientific facts remain. Refresh project status.':'Final preparation acknowledged; no writer was replayed and no Run was launched. Refresh project status.';message($('project-candidate-preparation-status').textContent); - } - $('project-candidate-reconcile').onclick=()=>run(ticket=>candidateRecover(ticket,false));$('project-candidate-abandon').onclick=()=>run(ticket=>candidateRecover(ticket,true)); - for(const [form,fields] of [['project-candidate-prepare-form',['project-candidate-study','project-candidate-revision','project-candidate-id','project-candidate-kind','project-candidate-root','project-candidate-directory','project-candidate-runtime','project-candidate-package-run','project-candidate-package-sha']],['project-candidate-recovery-form',['project-candidate-recovery-study','project-candidate-recovery-key','project-candidate-abandon-reason']]])for(const field of fields)$(field).addEventListener(field==='project-candidate-kind'?'change':'input',()=>{m2DirtyForms.add(form);m2Dirty=true;controls();}); - - function runtimeSummaryOK(value,complete=false){ - const keys=['format','project_id','manifest_sha256','file_count','total_bytes','actor_id','observed_at','request_key',...(complete?['runtime_ref']:[])]; - return exact(value,keys)&&value.format===(complete?'project_runtime_capture_v1':'project_runtime_capture_intent_v1')&&id(value.project_id)&&sha(value.manifest_sha256)&&positive(value.file_count)&&value.file_count<=40000&&Number.isSafeInteger(value.total_bytes)&&value.total_bytes>=0&&value.total_bytes<=2147483648&&id(value.actor_id)&&str(value.observed_at,80)&&typeof value.request_key==='string'&&/^[A-Za-z0-9][A-Za-z0-9_.:-]{7,127}$/.test(value.request_key)&&(!complete||exact(value.runtime_ref,['kind','catalog_id','id','sha256'])&&value.runtime_ref.kind==='runtime'&&value.runtime_ref.catalog_id===value.project_id&&sha(value.runtime_ref.id)&&value.runtime_ref.id===value.runtime_ref.sha256); - } - function runtimeControls(){ - $('project-runtime-sources').disabled=!m2Allowed('runtime_sources');$('project-runtime-sources-more').disabled=!m2Allowed('runtime_sources'); - $('project-runtime-inspect').disabled=!$('project-runtime-source').value||!m2Allowed('runtime_inspect'); - $('project-runtime-source').disabled=!m2Allowed('runtime_inspect'); - $('project-runtime-files-more').disabled=!runtimeInspection||runtimeInspection.binding!==state?.binding||!m2Allowed('runtime_inspect'); - $('project-runtime-capture-fields').disabled=!runtimeInspection||runtimeInspection.binding!==state?.binding||!m2Allowed('runtime_capture'); - $('project-runtime-capture').disabled=$('project-runtime-capture-fields').disabled||!$('project-runtime-confirm').checked; - $('project-runtime-status-fields').disabled=!preparationRecoveryAllowed('runtime_status'); - $('project-runtime-abandon-fields').disabled=!preparationRecoveryAllowed('runtime_abandon'); - $('project-runtime-retry').disabled=!runtimePending||runtimePending.body.binding!==state?.binding||!preparationRecoveryAllowed('runtime_capture'); - } - async function runtimeSources(ticket,more=false){ - const offset=more?runtimeSourceOffset:0,value=await m2Request('runtime_sources',{offset,limit:40},ticket);if(!value)return; - if(!value.items.every(item=>exact(item,['source'])&&typeof item.source==='string'&&/^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/.test(item.source)))throw Error('Unsupported configured runtime source page.'); - if(!more){$('project-runtime-source').replaceChildren();runtimeInspection=null;$('project-runtime-confirm').checked=false;} - for(const item of value.items){const option=document.createElement('option');option.value=item.source;option.textContent=item.source;$('project-runtime-source').append(option);} - runtimeSourceOffset=offset+value.items.length;runtimeSourceTotal=value.total;$('project-runtime-sources-more').hidden=runtimeSourceOffset>=runtimeSourceTotal;controls(); - message(value.total?'Choose a current source and explicitly inspect it. No runtime has been captured.':'No current runtime sources are configured on this installation.'); - } - async function runtimeInspect(ticket,more=false){ - const source=$('project-runtime-source').value;if(!source)throw Error('Choose a configured source alias.'); - const offset=more?runtimeFileOffset:0,value=await m2Request('runtime_inspect',{source,offset,limit:40},ticket);if(!value)return; - const page=value.files; - if(!exact(value,['format','source','inventory_sha256','profile','python_version','file_count','total_bytes','manifest_bytes','free_bytes','packages','launch','files'])||value.format!=='project_runtime_inspection_v1'||value.source!==source||!sha(value.inventory_sha256)||value.profile!=='captured_cpu_python_v1'||value.python_version!=='3.12'||!positive(value.file_count)||value.file_count>40000||!positive(value.total_bytes)||value.total_bytes>2147483648||!positive(value.manifest_bytes)||value.manifest_bytes>16777216||!Number.isSafeInteger(value.free_bytes)||value.free_bytes<0||!Array.isArray(value.packages)||value.packages.length<2||value.packages.length>256||!value.packages.every(item=>exact(item,['name','version'])&&str(item.name,128)&&str(item.version,128))||!exact(page,['items','total','offset','limit'])||page.total!==value.file_count||page.offset!==offset||page.limit!==40||!Array.isArray(page.items)||page.items.length!==Math.min(40,Math.max(0,page.total-offset)))throw Error('Runtime inventory differs from the reviewed source or continuation.'); - if(!page.items.every(item=>exact(item,['path','bytes','sha256','mode','kind'])&&str(item.path,1024)&&Number.isSafeInteger(item.bytes)&&item.bytes>=0&&item.bytes<=536870912&&sha(item.sha256)&&[256,320].includes(item.mode)&&['data','elf'].includes(item.kind)))throw Error('Unsupported runtime file inventory.'); - if(more&&(!runtimeInspection||runtimeInspection.binding!==state.binding||runtimeInspection.source!==source||runtimeInspection.inventory_sha256!==value.inventory_sha256))throw Error('Current runtime inventory changed between pages. Inspect it again before capture.'); - if(!more){runtimeInspection={binding:state.binding,source,inventory_sha256:value.inventory_sha256};$('project-runtime-files').replaceChildren();$('project-runtime-confirm').checked=false;} - $('project-runtime-summary').textContent=`Current configured source ${source} · ${value.inventory_sha256} · ${value.file_count} files · ${value.total_bytes} bytes · ${value.free_bytes} bytes currently free. This observation does not capture a runtime.`; - $('project-runtime-layout').textContent=JSON.stringify({python_version:value.python_version,packages:value.packages,launch:value.launch},null,2); - for(const item of page.items){const li=document.createElement('li');li.textContent=`${item.path} · ${item.kind} · ${item.bytes} bytes · ${item.sha256}`;$('project-runtime-files').append(li);} - runtimeFileOffset=offset+page.items.length;runtimeFileTotal=page.total;$('project-runtime-files-more').hidden=runtimeFileOffset>=runtimeFileTotal;controls(); - } - $('project-runtime-sources').onclick=()=>run(ticket=>runtimeSources(ticket));$('project-runtime-sources-more').onclick=()=>run(ticket=>runtimeSources(ticket,true)); - $('project-runtime-inspect').onclick=()=>run(ticket=>runtimeInspect(ticket));$('project-runtime-files-more').onclick=()=>run(ticket=>runtimeInspect(ticket,true)); - $('project-runtime-source').addEventListener('change',()=>{runtimeInspection=null;$('project-runtime-confirm').checked=false;controls();}); - function runtimeAbandonmentOK(value,key,reason=null){ - return exact(value,['format','project_id','capture_key','input_sha256','manifest_sha256','actor_id','reason','observed_checkpoint','observed_at'])&&value.format==='project_runtime_capture_abandon_v1'&&value.project_id===state.project.project_id&&value.capture_key===key&&sha(value.input_sha256)&&sha(value.manifest_sha256)&&id(value.actor_id)&&str(value.reason,1000)&&(reason===null||value.reason===reason)&&sha(value.observed_checkpoint)&&str(value.observed_at,80); - } - async function captureRuntime(ticket,retry=false){ - let args; - if(retry){ - if(!runtimePending||runtimePending.body.binding!==state.binding)throw Error('This tab has no exact current pending capture request. Inspect retained status before choosing a new action.'); - const {binding,expected_checkpoint,request_key,...saved}=runtimePending.body;args=saved; - }else{ - if(runtimeInspection?.binding!==state.binding||!$('project-runtime-confirm').checked)throw Error('Inspect and explicitly confirm the current source inventory before capture.'); - const reserve_bytes=Number($('project-runtime-reserve').value);if(!Number.isSafeInteger(reserve_bytes)||reserve_bytes<0)throw Error('Choose a nonnegative safe integer disk reserve.'); - args={source:runtimeInspection.source,expected_inventory_sha256:runtimeInspection.inventory_sha256,reserve_bytes}; - } - const value=await m2Request('runtime_capture',args,ticket);if(!value)return; - if(!runtimeSummaryOK(value,true)||value.project_id!==state.project.project_id||value.manifest_sha256!==args.expected_inventory_sha256||value.request_key!==runtimePending?.body.request_key)throw Error('Runtime capture acknowledgement differs from the reviewed inventory or pending request.'); - $('project-runtime-status-key').value=value.request_key;runtimePending=null; - if(Number($('project-runtime-reserve').value)===args.reserve_bytes)executionFormSaved('project-runtime-capture-form');$('project-runtime-confirm').checked=false; - $('project-runtime-pending').textContent=`Capture request ${value.request_key} acknowledged. Retained capture facts do not grant permission to execute.`;$('project-runtime-status').textContent=JSON.stringify(value,null,2);controls();message('Reviewed runtime bytes captured locally and scientific metadata saved. No project execution started.'); - } - $('project-runtime-capture-form').onsubmit=event=>{event.preventDefault();run(ticket=>captureRuntime(ticket));}; - $('project-runtime-retry').onclick=()=>run(ticket=>captureRuntime(ticket,true)); - $('project-runtime-abandon-form').onsubmit=event=>{event.preventDefault();run(async ticket=>{ - const capture_key=$('project-runtime-abandon-key').value,reason=$('project-runtime-abandon-reason').value; - if(!/^[A-Za-z0-9][A-Za-z0-9_.:-]{7,127}$/.test(capture_key)||!str(reason,1000))throw Error('Choose the exact current capture key and an explicit abandonment reason.'); - const value=await m2Request('runtime_abandon',{capture_key,reason},ticket);if(!value)return; - if(!runtimeAbandonmentOK(value,capture_key,reason))throw Error('Runtime abandonment differs from the current exact capture and reason.'); - if(runtimePending?.body.request_key===capture_key){if(Number($('project-runtime-reserve').value)===runtimePending.body.reserve_bytes)executionFormSaved('project-runtime-capture-form');runtimePending=null;} - executionFormSaved('project-runtime-abandon-form');$('project-runtime-status-key').value=capture_key;$('project-runtime-status').textContent=JSON.stringify(value,null,2);$('project-runtime-pending').textContent='Stopped partial capture abandoned. Original partial bytes and scientific intent remain. Refresh project status.';message($('project-runtime-pending').textContent);controls(); - });}; - $('project-runtime-status-form').onsubmit=event=>{event.preventDefault();run(async ticket=>{ - const capture_key=$('project-runtime-status-key').value;if(!/^[A-Za-z0-9][A-Za-z0-9_.:-]{7,127}$/.test(capture_key))throw Error('Choose the exact retained capture request key.'); - const value=await m2Request('runtime_status',{capture_key},ticket);if(!value)return; - const abandoned=value?.state==='abandoned'; - if(!exact(value,abandoned?['state','intent','result','abandonment']:['state','intent','result'])||!['absent','intent_recorded','captured','abandoned'].includes(value.state)||value.state!==(abandoned?'abandoned':value.result?'captured':value.intent?'intent_recorded':'absent')||value.result&&!value.intent||value.intent!==null&&!runtimeSummaryOK(value.intent)||value.result!==null&&!runtimeSummaryOK(value.result,true)||[value.intent,value.result].some(item=>item!==null&&(item.project_id!==state.project.project_id||item.request_key!==capture_key))||value.result&&['project_id','manifest_sha256','file_count','total_bytes','request_key'].some(field=>value.intent[field]!==value.result[field])||abandoned&&(!value.intent||value.result!==null||!runtimeAbandonmentOK(value.abandonment,capture_key)||value.abandonment.manifest_sha256!==value.intent.manifest_sha256))throw Error('Retained runtime status differs from the selected capture request.'); - $('project-runtime-status').textContent=JSON.stringify(value,null,2);message('Retained capture outcome loaded. Current local readiness was not inspected.'); - });}; - for(const field of ['project-runtime-abandon-key','project-runtime-abandon-reason'])$(field).addEventListener('input',()=>{m2DirtyForms.add('project-runtime-abandon-form');m2Dirty=true;controls();}); - for(const field of ['project-runtime-reserve','project-runtime-confirm'])$(field).addEventListener(field.endsWith('confirm')?'change':'input',()=>{m2DirtyForms.add('project-runtime-capture-form');m2Dirty=true;controls();}); - - function m4Controls(){ - $('project-save-as-fields').disabled=!m2Allowed('save_as'); - $('project-working-load').disabled=!m2Allowed('files_inspect');$('project-working-more').disabled=!m2Allowed('files_inspect'); - $('project-working-adopt-fields').disabled=!m2Allowed('file_adopt'); - $('project-working-delete-fields').disabled=!m2Allowed('file_adopt_deletion')||!workingDeletion||workingDeletion.binding!==state?.binding||workingDeletion.checkpoint!==checkpoint(); - $('project-working-history').disabled=!workingSelection||workingSelection.binding!==state?.binding||!m2Allowed('file_history'); - $('project-working-history-more').disabled=!m2Allowed('file_history'); - for(const [button,action] of [['project-fork-load','fork_info'],['project-fork-more','fork_info'],['project-intents-load','material_intents'],['project-intents-more','material_intents'],['project-intent-capabilities','material_intent_capabilities'],['project-intent-capabilities-more','material_intent_capabilities']])$(button).disabled=!m2Allowed(action); - } - function m4Reset(){ - runtimeInspection=null;runtimeSourceOffset=runtimeSourceTotal=runtimeFileOffset=runtimeFileTotal=0;$('project-runtime-source').replaceChildren();$('project-runtime-files').replaceChildren();$('project-runtime-layout').textContent='';$('project-runtime-summary').textContent='';$('project-runtime-confirm').checked=false; - workingSelection=null;clearWorkingDeletion();workingOffset=workingTotal=workingHistoryOffset=workingHistoryTotal=intentsOffset=intentsTotal=forkOffset=forkTotal=intentCapsOffset=intentCapsTotal=0; - for(const name of ['project-working-list','project-working-history-list','project-fork-list','project-intents-list'])$(name).replaceChildren(); - $('project-working-text').value='';$('project-working-summary').textContent='';$('project-intent-detail').textContent=''; - for(const name of ['project-working-more','project-working-history-more','project-fork-more','project-intents-more','project-intent-capabilities-more'])$(name).hidden=true; - } - function forkOK(value,body){ - if(!exact(value,['state','fork'])||!stateOK(value.state)||value.state.state!=='open')return false; - const f=value.fork; - return exact(f,['source_project_id','source_checkpoint','project_id','checkpoint','root','directory','request_key','reconciled','mapping_count','copied_count','missing_regenerable_count'])&& - id(f.source_project_id)&&id(f.project_id)&&f.source_project_id!==f.project_id&&sha(f.source_checkpoint)&&sha(f.checkpoint)&& - f.source_checkpoint===body.expected_checkpoint&&f.source_project_id===forkPending?.source_project_id&& - ['root','directory','request_key'].every(field=>f[field]===body[field])&&typeof f.reconciled==='boolean'&& - ['mapping_count','copied_count','missing_regenerable_count'].every(field=>Number.isSafeInteger(f[field])&&f[field]>=0)&& - value.state.binding!==body.binding&&value.state.project.project_id===f.project_id&&value.state.project.checkpoint===f.checkpoint&&value.state.project.name===body.name; - } - $('project-save-as-form').onsubmit=event=>{event.preventDefault();run(async ticket=>{ - if(importDirty||annotationDirty||[...m2DirtyForms].some(form=>form!=='project-save-as-form'))throw Error('Submit or discard other unsubmitted edits before Save As.'); - const fields={root:$('project-save-as-root').value,directory:$('project-save-as-directory').value,name:$('project-save-as-name').value.trim()},signature=JSON.stringify(fields); - if(!fields.root||!fields.directory||!fields.name)throw Error('Choose a new root, relative directory and project name.'); - if(forkPending&&forkPending.signature!==signature)throw Error('Inspect the pending Save As destination, then keep its exact request or explicitly discard this form before choosing another destination.'); - if(!forkPending)forkPending={signature,source_project_id:state.project.project_id,body:mutationBody('/save-as',fields)}; - const result=await request('/save-as',{body:forkPending.body,ticket,kind:'fork'});if(!result)return; - state=result.state;forkPending=null;pending=null;executionFormSaved('project-save-as-form');m4Reset();clearExploration();selected=null;history=[];nextHistory=null;showRecord();showState(); - const f=result.fork;$('project-save-as-summary').textContent=`Independent project ${f.project_id}; ${f.mapping_count} editable mappings, ${f.copied_count} copied payloads, ${f.missing_regenerable_count} missing regenerable payloads. Source checkpoint ${f.source_checkpoint} is retained as its origin.`; - await query(ticket);message('Independent project created and selected. Review its fork origins and binding readiness.');return $('project-fork-load'); - });}; - async function inspectWorking(ticket,more=false){ - const offset=more?workingOffset:0,value=await m2Request('files_inspect',{offset,limit:40},ticket);if(!value)return; - clearWorkingDeletion();if(!more)$('project-working-list').replaceChildren(); - for(const item of value.items){const li=document.createElement('li'),button=document.createElement('button');button.type='button';button.textContent=`${item.path} · ${item.state} · captured revision ${item.revision}`;button.onclick=()=>run(async next=>{ - const version=await m2Request('file_get',{file_id:item.id},next);if(!version)return;showWorking(version); - if(item.kind==='note'&&item.state==='missing'&&sha(item.expected_sha256)){workingDeletion={binding:state.binding,checkpoint:checkpoint(),path:item.path,revision:item.revision,sha256:item.expected_sha256};$('project-working-delete-summary').textContent=`Missing note ${item.path} · captured revision ${item.revision} · SHA256 ${item.expected_sha256}. Earlier text will remain in revision history.`;} - controls();$('project-working-kind').value=item.kind;$('project-working-path').value=item.path;$('project-working-revision').value=String(item.revision);$('project-working-sha').value=item.observed_sha256??''; - message(item.state==='unchanged'?'Captured bytes match the current file.':'Current file differs or is unavailable. Review its exact current digest before adoption.');return $('project-working-heading'); - },{clean:true});li.append(button);$('project-working-list').append(li);} - workingOffset=offset+value.items.length;workingTotal=value.total;$('project-working-more').hidden=workingOffset>=workingTotal; - } - function clearWorkingDeletion(){ - workingDeletion=null;$('project-working-delete-confirm').checked=false;executionFormSaved('project-working-delete-form'); - $('project-working-delete-summary').textContent='Inspect and select a known missing note first. This action records its absence and keeps all captured revisions.'; - } - function showWorking(value){ - clearWorkingDeletion(); - workingSelection={id:value.id,binding:state.binding};$('project-working-heading').textContent=value.path; - $('project-working-summary').textContent=value.version.deleted===true?`Captured revision ${value.version.revision} · note deletion retained. No text is present in this revision; select an earlier revision to read its captured text.`:`Captured revision ${value.version.revision} · ${value.version.sha256} · ${value.version.bytes} bytes${value.version.bytes===0?' · empty file':''}.`; - $('project-working-text').value=value.version.deleted===true?'':value.version.text;controls(); - } - async function workingHistory(ticket,more=false){ - if(!workingSelection||workingSelection.binding!==state.binding)throw Error('Select a file from the current project first.'); - const offset=more?workingHistoryOffset:0,value=await m2Request('file_history',{file_id:workingSelection.id,offset,limit:40},ticket);if(!value)return; - if(value.id!==workingSelection.id)throw Error('Working-file history belongs to another file.'); - if(!more)$('project-working-history-list').replaceChildren(); - for(const version of value.items){const li=document.createElement('li'),button=document.createElement('button');button.type='button';button.textContent=`Revision ${version.revision} · ${version.deleted===true?'note deletion':version.sha256} · ${version.adopted_at}`;button.onclick=()=>run(async next=>{const result=await m2Request('file_get',{file_id:workingSelection.id,revision:version.revision},next);if(result)showWorking(result);return $('project-working-heading');});li.append(button);$('project-working-history-list').append(li);} - workingHistoryOffset=offset+value.items.length;workingHistoryTotal=value.total;$('project-working-history-more').hidden=workingHistoryOffset>=workingHistoryTotal; - } - $('project-working-local').addEventListener('change',()=>run(async()=>{ - const file=$('project-working-local').files?.[0];if(!file)return;if(file.size>1048576)throw Error('Choose a UTF-8 file of at most 1 MiB.'); - const bytes=await file.arrayBuffer();new TextDecoder('utf-8',{fatal:true}).decode(bytes); - $('project-working-sha').value=Array.from(new Uint8Array(await crypto.subtle.digest('SHA-256',bytes)),value=>value.toString(16).padStart(2,'0')).join(''); - m2DirtyForms.add('project-working-adopt-form');m2Dirty=true;message('Matching local file digest calculated. Review the server project path and expected adopted revision before adoption.'); - })); - $('project-working-adopt-form').onsubmit=event=>{event.preventDefault();run(async ticket=>{ - const args={kind:$('project-working-kind').value,path:$('project-working-path').value,expected_revision:Number($('project-working-revision').value),expected_sha256:$('project-working-sha').value}; - const result=await m2Request('file_adopt',args,ticket);if(!result)return;executionFormSaved('project-working-adopt-form');$('project-working-revision').value=String(result.revision); - await inspectWorking(ticket);const saved=await m2Request('file_get',{file_id:result.id,revision:result.revision},ticket);if(saved)showWorking(saved);message('Exact working-file bytes adopted. The captured text remains inert.');return $('project-working-heading'); - });}; - $('project-working-delete-confirm').addEventListener('change',()=>{m2DirtyForms.add('project-working-delete-form');m2Dirty=true;controls();}); - $('project-working-delete-form').onsubmit=event=>{event.preventDefault();run(async ticket=>{ - const selected=workingDeletion;if(!selected||selected.binding!==state.binding||selected.checkpoint!==checkpoint()||!$('project-working-delete-confirm').checked)throw Error('Inspect and select a known missing note, then explicitly confirm its deletion revision.'); - const result=await m2Request('file_adopt_deletion',{path:selected.path,expected_revision:selected.revision,expected_sha256:selected.sha256},ticket);if(!result)return; - executionFormSaved('project-working-delete-form');clearWorkingDeletion();await inspectWorking(ticket); - const saved=await m2Request('file_get',{file_id:result.id,revision:result.revision},ticket);if(saved)showWorking(saved); - message('Note deletion retained. Earlier captured text remains available in revision history.');return $('project-working-heading'); - });}; - async function forkInfo(ticket,more=false){ - const offset=more?forkOffset:0,value=await m2Request('fork_info',{offset,limit:40},ticket);if(!value)return; - const page=value.mapping;if(!exact(page,['items','total','offset','limit'])||page.offset!==offset||page.limit!==40||!Array.isArray(page.items)||page.items.length!==Math.min(40,Math.max(0,page.total-offset)))throw Error('Fork mapping continuation differs.'); - if(!more)$('project-fork-list').replaceChildren();$('project-fork-summary').textContent=value.source?`Fork origin ${value.source.project_id} at ${value.source.checkpoint}; ${value.archived_count} archived records, ${value.copied_count} copied payloads, ${value.missing_regenerable_count} missing regenerable payloads.`:'This project has no independent-fork origin overlay.'; - for(const mapping of page.items){const li=document.createElement('li');li.textContent=`${mapping.family}: ${mapping.source_id} revision ${mapping.source_revision??'none'} → ${mapping.destination_id}`;$('project-fork-list').append(li);} - forkOffset=offset+page.items.length;forkTotal=page.total;$('project-fork-more').hidden=forkOffset>=forkTotal; - } - async function intentList(ticket,more=false,capabilities=false){ - const offset=more?(capabilities?intentCapsOffset:intentsOffset):0,action=capabilities?'material_intent_capabilities':'material_intents'; - const value=await m2Request(action,{offset,limit:40},ticket);if(!value)return;if(!more)$('project-intents-list').replaceChildren(); - for(const item of value.items){const li=document.createElement('li'),fields=capabilities?item.requires_reselection:item.required_reselection; - if(capabilities)li.textContent=`${item.family} · ${item.id} · ${fields.length?'Reselect '+fields.join(', '):'Current editable definition; execution still requires current permission.'}`; - else{const button=document.createElement('button');button.type='button';button.textContent=`${item.name} · ${item.family} · reselect ${fields.join(', ')}`;button.onclick=()=>run(async next=>{const detail=await m2Request('material_intent',{family:item.family,definition_id:item.definition_id},next);if(!detail)return;$('project-intent-title').textContent=detail.current.name;$('project-intent-detail').textContent=JSON.stringify(detail,null,2);return $('project-intent-title');});li.append(button);} - $('project-intents-list').append(li);} - if(capabilities){intentCapsOffset=offset+value.items.length;intentCapsTotal=value.total;$('project-intent-capabilities-more').hidden=intentCapsOffset>=intentCapsTotal;} - else{intentsOffset=offset+value.items.length;intentsTotal=value.total;$('project-intents-more').hidden=intentsOffset>=intentsTotal;} - } - $('project-working-load').onclick=()=>run(ticket=>inspectWorking(ticket),{clean:true});$('project-working-more').onclick=()=>run(ticket=>inspectWorking(ticket,true)); - $('project-working-history').onclick=()=>run(ticket=>workingHistory(ticket));$('project-working-history-more').onclick=()=>run(ticket=>workingHistory(ticket,true)); - $('project-fork-load').onclick=()=>run(ticket=>forkInfo(ticket));$('project-fork-more').onclick=()=>run(ticket=>forkInfo(ticket,true)); - $('project-intents-load').onclick=()=>run(ticket=>intentList(ticket));$('project-intents-more').onclick=()=>run(ticket=>intentList(ticket,true)); - $('project-intent-capabilities').onclick=()=>run(ticket=>intentList(ticket,false,true));$('project-intent-capabilities-more').onclick=()=>run(ticket=>intentList(ticket,true,true)); - for(const [form,fields] of [['project-save-as-form',['project-save-as-directory','project-save-as-name','project-save-as-root']],['project-working-adopt-form',['project-working-path','project-working-revision','project-working-sha','project-working-kind']]])for(const field of fields)$(field).addEventListener('input',()=>{m2DirtyForms.add(form);m2Dirty=true;controls();}); - - for(const [form,fields] of [['project-producer-start-form',['project-producer-url','project-producer-model','project-producer-instruction','project-producer-labels','project-producer-seed','project-producer-profile','project-producer-session','project-producer-width','project-producer-height','project-producer-count','project-producer-prompt-url','project-producer-prompt-model']],['project-producer-review-form',['project-producer-note']],['project-execution-approval-form',['project-execution-consumer','project-execution-ttl']],['project-study-approval-form',['project-study-consumer']]])for(const field of fields)$(field).addEventListener('input',()=>{m2DirtyForms.add(form);m2Dirty=true;controls();}); - for(const action of ['new','open','save','close'])$('project-files-'+action).onclick=()=>lifecycle(action); - $('project-files-refresh').onclick=refresh; - $('records-more').onclick=()=>run(async ticket=>{await query(ticket,true);message('More text records loaded.');return nextRecord===null?$('records-title'):$('records-more');}); - $('record-history-more').onclick=olderHistory; - $('project-files-discard').onclick=()=>{importDirty=false;annotationDirty=false;m2Dirty=false;m2DirtyForms.clear();clearWorkingDeletion();nativePending=null;nativePrepared=null;for(const field of ['project-native-probe-confirm','project-native-submit-confirm','project-native-retry-confirm'])$(field).checked=false;forkPending=null;runtimePending=null;runtimeInspection=null;for(const field of ['project-candidate-study','project-candidate-id','project-candidate-directory','project-candidate-runtime','project-candidate-package-run','project-candidate-package-sha','project-candidate-recovery-study','project-candidate-recovery-key','project-candidate-abandon-reason','project-runtime-abandon-key','project-runtime-abandon-reason'])$(field).value='';$('project-runtime-confirm').checked=false;$('project-runtime-pending').textContent='';for(const field of ['project-save-as-directory','project-save-as-name','project-working-path','project-working-sha','project-working-local'])$(field).value='';$('project-working-revision').value='0';executionApproval=null;studyApproval=null;producerCurrent=null;for(const field of ['project-producer-url','project-producer-model','project-producer-instruction','project-producer-labels','project-producer-note','project-producer-profile','project-producer-session','project-producer-prompt-url','project-producer-prompt-model'])$(field).value='';$('project-producer-confirm').checked=false;$('project-execution-confirm').checked=false;$('project-artifact-path').value='';for(const form of ['project-model-create-form','project-study-create-form','project-register-form','project-scientific-form'])for(const field of $(form).querySelectorAll('input'))field.value=field.defaultValue??'';clearExplorationDetail();$('project-source-file').value='';$('project-source-name').value='';$('project-search-name').value='';$('project-selection-name').value='';$('text-name').value='';$('text-content').value='';$('text-groups').value='project';$('text-rights').value='unknown';showRecord();clearError();message('Unsubmitted edits discarded. Saved project records are unchanged.');}; - for(const field of ['text-name','text-content','text-groups','text-rights'])$(field).addEventListener('input',()=>{importDirty=true;controls();}); - for(const field of ['annotation-value','annotation-groups','record-review','annotation-task'])$(field).addEventListener(field==='annotation-task'||field==='record-review'?'change':'input',()=>{annotationDirty=true;annotationHelp();controls();}); - window.addEventListener('beforeunload',event=>{if(dirty()){event.preventDefault();event.returnValue='';}}); - window.addEventListener('tuldok-session',()=>{++epoch;busy=false;blocked=true;selectedContracts=new Set();controls();message('Session changed. Refreshing project status; your unsubmitted edits remain here.');refresh();}); - controls();refresh(); -})(); diff --git a/static/project-measurements.css b/static/project-measurements.css deleted file mode 100644 index d1ba5ff3..00000000 --- a/static/project-measurements.css +++ /dev/null @@ -1,14 +0,0 @@ -#project-measurements{overflow-wrap:anywhere;min-width:0} -#project-measurements section{margin-top:1rem;padding:1rem} -#project-measurements table{width:100%;border-collapse:collapse;margin:1rem 0} -#project-measurements caption{text-align:left;font-weight:600;padding:.5rem 0} -#project-measurements th,#project-measurements td{border-bottom:1px solid #c6d0c7;padding:.6rem;text-align:left;vertical-align:top} -#project-measurements pre{white-space:pre-wrap;max-height:28rem;overflow:auto;font-size:.9rem} -#project-measurements dl{margin:.5rem 0}#project-measurements dt{font-weight:600}#project-measurements dd{margin:0 0 .5rem} -#project-measurements details{margin:.75rem 0}#project-measurements summary{cursor:pointer;font-weight:600} -#project-measurements-filters{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:1rem;margin:1rem 0} -#project-measurements-filters fieldset{border:1px solid #c6d0c7;padding:.75rem} -#project-measurements-chart{min-height:5rem;min-width:0;width:100%} -#project-measurements-chart .vega-embed{width:100%} -#project-measurements-maxima,#project-measurements-rows{overflow:auto;min-width:0} -@media(max-width:760px){#project-measurements-filters{grid-template-columns:1fr}#project-measurements table{min-width:34rem}} diff --git a/static/project-measurements.js b/static/project-measurements.js deleted file mode 100644 index 64e3f9c0..00000000 --- a/static/project-measurements.js +++ /dev/null @@ -1,323 +0,0 @@ -/* Native scalar selection/inspection. The host owns current access and reads. */ -(() => { - 'use strict'; - const STATES = ['measured', 'failed', 'unsupported', 'unavailable']; - const hash = value => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value); - const identity = value => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/.test(value); - const natural = value => Number.isSafeInteger(value) && value >= 0; - const finite = value => typeof value === 'number' && Number.isFinite(value); - const display = value => value === null ? 'Unknown' : Object.is(value, -0) ? '-0' : String(value); - const node = (tag, text) => { const value = document.createElement(tag); if (text !== undefined) value.textContent = text; return value; }; - const button = (text, invoke) => { const value = node('button', text); value.type = 'button'; value.onclick = invoke; return value; }; - const sourceKey = source => source.origin_catalog_id + '.' + source.id; - const spec = {path: '/static/retained-measurement-maxima.vl.json', sha256: 'c9440bbe90d215afb15d47a5f12c5aefcb20dc1d3ddba19d72fe5ba3adb1cd92'}; - function page(value, offset, limit, items) { - if (!value || value.offset !== offset || value.limit !== limit || !natural(value.total) || !Array.isArray(items) - || items.length !== Math.min(limit, Math.max(0, value.total - offset))) throw Error('Measurement page differs from the selected continuation.'); - } - function jsonDetails(title, value, open = false) { - const details = node('details'); details.open = open; - details.append(node('summary', title), node('pre', JSON.stringify(value, null, 2))); return details; - } - window.ProjectMeasurements = function({root, read, onContextFocusLost = () => {}}) { - root.innerHTML = '

                        Retained measurements

                        Compare exact saved scalars and inspect their original cases. Maxima use every matching case; failed and unavailable observations remain counted.

                        '; - const $ = name => root.querySelector('#project-measurements-' + name); - let context = null, generation = 0, plotGeneration = 0, pending, busy = false, pendingFocus = false; - let sources = [], sourceOffset = 0, sourceTotal = 0, selected = null, descriptors = null, metadata = null; - let subjects = [], subjectOffset = 0, subjectTotal = 0, filters = new Map(), applied = null, query = null, selectedSubjects = new Set(); - const renderer = window.RetainedChart.mount($('chart'), spec, {onError: error => { - const ownsFocus = root.contains(document.activeElement); clearResults(); $('status').textContent = error.message; controls(); - if (ownsFocus) $('compare').focus(); - }}); - function clearInspection() { $('inspection').replaceChildren(); $('inspection').hidden = true; } - function clearResults() { - ++plotGeneration; renderer.clear(); query = null; applied = null; - $('results').hidden = true; $('maxima').replaceChildren(); $('rows').replaceChildren(); clearInspection(); - } - function controls() { - for (const control of root.querySelectorAll('input,select,button')) control.disabled = !context?.enabled || busy; - $('sources-prev').hidden = sourceOffset === 0; $('sources-next').hidden = sourceOffset + sources.length >= sourceTotal; - $('source').disabled ||= !sources.length; $('source-all').disabled ||= !sources.length || sources.length > 16; - $('load').disabled ||= !$('source').selectedOptions.length || $('source').selectedOptions.length > 16; - $('subjects-prev').hidden = subjectOffset === 0; $('subjects-next').hidden = subjectOffset + 40 >= subjectTotal; - $('compare').disabled ||= !metadata || !selectedSubjects.size; - $('subjects-all').disabled ||= !metadata; $('subjects-clear').disabled ||= !metadata; - $('prev').disabled ||= !query || query.offset === 0; - $('next').disabled ||= !query || query.offset + query.rows.length >= query.total; - root.setAttribute('aria-busy', String(busy)); - } - function clearSource() { - selected = descriptors = metadata = null; subjects = []; selectedSubjects.clear(); subjectOffset = subjectTotal = 0; filters.clear(); - $('form').hidden = true; $('context').replaceChildren(); $('filters').replaceChildren(); - $('metric').replaceChildren(); $('subjects').replaceChildren(); clearResults(); - } - function reset() { - ++generation; pending?.abort(); pending = undefined; busy = false; pendingFocus = false; - clearSource(); sources = []; sourceOffset = sourceTotal = 0; - $('source').replaceChildren(); $('source-page').textContent = ''; $('status').textContent = ''; controls(); - } - const ownsFocus = () => root.contains(document.activeElement) - || busy && pendingFocus && document.activeElement === document.body; - async function perform(work) { - if (!context?.enabled || busy) return; - const ticket = ++generation, authority = context.key; - pending = new AbortController(); const signal = pending.signal; - const active = () => ticket === generation && context?.key === authority && context.enabled && !signal.aborted; - pendingFocus = root.contains(document.activeElement); busy = true; controls(); - let focus; - try { focus = await work(active, signal, authority); } - catch (error) { - if (active()) { - const ownedFocus = ownsFocus(); reset(); $('status').textContent = error.message; - if (ownedFocus) $('sources').focus(); - } - } finally { if (active()) { busy = false; pending = undefined; pendingFocus = false; controls(); focus?.focus(); } } - } - async function loadSources(offset = 0) { - clearSource(); - return perform(async(active, signal) => { - const value = await read('measurement_sources', {offset, limit: 40}, signal); if (!active()) return; - page(value, offset, 40, value.items); - const seen = new Set(); - for (const item of value.items) { - const key = sourceKey(item); - if (!hash(item.id) || !/^[a-f0-9]{32}$/.test(item.origin_catalog_id) || seen.has(key) - || item.blob?.sha256 !== item.id || typeof item.title !== 'string') throw Error('Invalid retained measurement source.'); - seen.add(key); - } - sources = value.items; sourceOffset = offset; sourceTotal = value.total; $('source').replaceChildren(); - for (const [index, item] of sources.entries()) { - const option = node('option', item.title + ' · ' + item.id.slice(0, 12) + (item.availability?.state === 'missing' ? ' · missing packet' : '')); - option.value = sourceKey(item); option.selected = index === 0; $('source').append(option); - } - $('source-page').textContent = `${sources.length ? offset + 1 : 0}–${offset + sources.length} of ${sourceTotal} sources`; - $('status').textContent = sources.length ? 'Choose compatible sources and load their exact retained metadata.' : 'No retained measurement sources in this project.'; - return $('source'); - }); - } - const same = (left, right) => { - if (Object.is(left, right)) return true; - if (!left || !right || typeof left !== 'object' || typeof right !== 'object' || Array.isArray(left) !== Array.isArray(right)) return false; - const keys = Object.keys(left); - return keys.length === Object.keys(right).length && keys.every(key => Object.hasOwn(right, key) && same(left[key], right[key])); - }; - const locatorKey = value => value.origin_catalog_id + '.' + value.packet_sha256; - const selection = () => ({sources:selected.map(item => ({origin_catalog_id:item.origin_catalog_id, packet_sha256:item.id}))}); - function checkComparison(response) { - if (!response || !Array.isArray(response.sources) || response.sources.length !== selected.length - || new TextEncoder().encode(JSON.stringify(response)).length > 256 * 1024) throw Error('Comparison differs from selected sources.'); - for (const [index, source] of response.sources.entries()) { - const expected = selected[index]; - if (source.origin_catalog_id !== expected.origin_catalog_id || source.id !== expected.id - || source.title !== expected.title || source.blob?.sha256 !== source.id || source.blob.bytes !== expected.blob.bytes - || source.source?.measured_sha256 !== source.id) throw Error('Comparison source identity changed.'); - } - if (descriptors && !same(descriptors, response.sources)) throw Error('Original comparison capture facts changed.'); - const value = response.value, keys = selected.map(sourceKey); - if (value?.format !== 'retained_measurement_comparison_v1' || !hash(value.case_population_sha256) - || !Array.isArray(value.subjects) || !value.subjects.length || value.subjects.length > 256 - || !natural(value.case_count) || !value.case_count || !natural(value.observation_count) - || !Array.isArray(value.metrics) || !value.metrics.length || value.metrics.length > 32 - || !Array.isArray(value.dimensions) || value.dimensions.length > 32 - || value.observation_count !== value.subjects.length * value.case_count * value.metrics.length - || locatorKey(value.definition_source) !== keys[0] - || value.subjects.some(item => !identity(item.id) || typeof item.label !== 'string' || !keys.includes(locatorKey(item.source))) - || new Set(value.subjects.map(item => item.id)).size !== value.subjects.length) throw Error('Invalid comparison metadata.'); - if (metadata && ['scope','scope_definition','dimensions','metrics','definition_source','case_population_sha256','case_count','observation_count','subjects'].some(key => !same(value[key], metadata[key]))) throw Error('Comparison population changed.'); - return value; - } - function checkRead(response, source) { - const original = descriptors.find(item => sourceKey(item) === locatorKey(source)); - if (!original || response?.source?.origin_catalog_id !== source.origin_catalog_id || response.source.id !== source.packet_sha256 - || response.source.blob?.sha256 !== source.packet_sha256 || !same(response.source, original) - || new TextEncoder().encode(JSON.stringify(response)).length > 256 * 1024) throw Error('Observation differs from its original packet.'); - return response.value; - } - function subjectPage(offset) { - if (!metadata || !natural(offset) || offset > subjectTotal) throw Error('Invalid comparison subject page.'); - subjectOffset = offset; $('subjects').replaceChildren(); - const items = subjects.slice(offset, offset + 40); - for (const item of items) { - const option = node('option', item.label + ' · ' + item.id); option.value = item.id; - option.selected = selectedSubjects.has(item.id); $('subjects').append(option); - } - subjectSelectionStatus(); - return $('subjects'); - } - function subjectSelectionStatus() { - const count = Math.min(40, subjectTotal - subjectOffset); - $('subject-page').textContent = `Subjects ${count ? subjectOffset + 1 : 0}–${subjectOffset + count} of ${subjectTotal}. ${selectedSubjects.size} selected across all pages; selection is retained when paging.`; - } - function dimensions() { - filters.clear(); $('filters').replaceChildren(); - for (const [index, dimension] of metadata.dimensions.entries()) { - const field = node('fieldset'), legend = node('legend', `${dimension.label}${dimension.units ? ' · ' + dimension.units : ''} (${dimension.scope})`); - const mode = node('select'); mode.id = 'project-measurements-filter-mode-' + index; - for (const [value, label] of [['any','Any recorded value'],['value','Exact value'],['unknown','Unknown only']]) { const option = node('option', label); option.value = value; mode.append(option); } - const label = node('label', 'Match'); label.htmlFor = mode.id; label.append(mode); - let input; - if (dimension.type === 'boolean') { input = node('select'); for (const value of ['true','false']) { const option = node('option', value); option.value = value; input.append(option); } } - else { input = node('input'); input.type = dimension.type === 'string' ? 'text' : 'number'; input.maxLength = 256; input.step = dimension.type === 'integer' ? '1' : 'any'; } - input.id = 'project-measurements-filter-value-' + index; - const valueLabel = node('label', 'Exact recorded value'); valueLabel.htmlFor = input.id; valueLabel.append(input); - field.append(legend, label, valueLabel); $('filters').append(field); filters.set(dimension.id, {dimension, mode, input}); - mode.onchange = invalidate; input.oninput = invalidate; - } - } - function filterValues() { - const values = {}; - for (const [id, {dimension, mode, input}] of filters) { - if (mode.value === 'any') continue; - if (mode.value === 'unknown') { values[id] = null; continue; } - if (mode.value !== 'value' || !input.value.length) throw Error('Enter an exact filter value or choose Any recorded value.'); - const value = dimension.type === 'boolean' ? input.value === 'true' : dimension.type === 'string' ? input.value : Number(input.value); - if ((dimension.type === 'number' && !finite(value)) || (dimension.type === 'integer' && !Number.isSafeInteger(value))) throw Error('Filter values must match the declared numeric type.'); - values[id] = value; - } - return values; - } - function invalidate() { - ++generation; pending?.abort(); pending = undefined; busy = false; clearResults(); - $('status').textContent = 'Selection edited. Compare metric to apply it.'; controls(); - } - function attributes(title, values) { - const details = node('details'); details.append(node('summary', title)); - const list = node('dl'); - for (const [key, value] of Object.entries(values)) { - const dimension = metadata.dimensions.find(item => item.id === key); - list.append(node('dt', dimension?.label ?? key), node('dd', display(value) + (dimension?.units ? ' ' + dimension.units : ''))); - } - details.append(list); return details; - } - function table(caption, headings) { - const result = node('table'), row = node('tr'), head = node('thead'), body = node('tbody'); - for (const text of headings) { const cell = node('th', text); cell.scope = 'col'; row.append(cell); } - head.append(row); result.append(node('caption', caption), head, body); return {result, body}; - } - async function inspect(observation_id, source) { - clearInspection(); - return perform(async(active, signal) => { - const value = checkRead(await read('measurement_inspect', {...source, observation_id}, signal), source); if (!active()) return; - if (value.packet_sha256 !== source.packet_sha256 || value.observation?.id !== observation_id - || value.observation.metric_id !== applied?.metric_id || !applied.subject_ids.includes(value.observation.subject_id) - || !same(subjects.find(item => item.id === value.observation.subject_id)?.source, source)) throw Error('Observation differs from the selected comparison.'); - const heading = node('h3', value.subject.label + ' · ' + value.case.id); heading.tabIndex = -1; - const observation = value.observation; - $('inspection').append(heading, node('p', `${value.metric.label} · ${value.metric.units} · ${observation.state} · ${observation.value === null ? observation.reason : display(observation.value)}`), - attributes('Case attributes, including grid density and domain cell counts', value.case.dimensions), - attributes('Subject execution attributes', value.subject.dimensions), attributes('Observation work attributes', observation.dimensions), - jsonDetails('Original case evidence', value.case_evidence, true), jsonDetails('Original scalar evidence', value.scalar_evidence, true), - jsonDetails('Exact observation, metric, source and scope', value)); - $('inspection').hidden = false; heading.focus(); $('status').textContent = 'Exact retained observation and original source evidence.'; - }); - } - async function showQuery(value, request, active, signal, authority) { - if (!value || value.metric?.id !== request.metric_id - || !same(value.metric, metadata.metrics.find(metric => metric.id === request.metric_id)) - || JSON.stringify(value.subject_ids) !== JSON.stringify(request.subject_ids) - || !value.filters || Object.keys(value.filters).length !== Object.keys(request.filters).length - || Object.entries(request.filters).some(([key, wanted]) => !Object.hasOwn(value.filters, key) || value.filters[key] !== wanted) - || !Array.isArray(value.summary) || value.summary.length !== request.subject_ids.length || value.sampling !== 'none') throw Error('Measurement comparison differs from its requested selection.'); - page(value, request.offset, request.limit, value.rows); - if (value.summary.reduce((count, summary) => count + summary.count, 0) !== value.total) throw Error('Comparison denominator differs from its complete summaries.'); - const maxima = table('Maximum over all matching cases, including every observation status', ['Subject / execution attributes','Maximum','Measured','Failed','Unsupported','Unavailable']); - const points = [], inspections = new Map(); - for (const [index, summary] of value.summary.entries()) { - if (summary.subject_id !== request.subject_ids[index] || !natural(summary.count) || STATES.some(state => !natural(summary.states?.[state])) - || STATES.reduce((sum, state) => sum + summary.states[state], 0) !== summary.count - || (summary.maximum === null) !== (summary.states.measured === 0)) throw Error('Invalid complete measurement summary.'); - const subject = subjects.find(item => item.id === summary.subject_id); if (!subject || !same(subject.source, summary.source)) throw Error('Subject differs from its original comparison packet.'); - const row = node('tr'), label = node('td'); label.append(node('strong', subject.label), attributes('Execution attributes', subject.dimensions)); - const maximum = node('td'); - if (summary.maximum === null) maximum.textContent = 'No measured value'; - else { - const point = summary.maximum; - if (!finite(point.value) || !identity(point.id) || !identity(point.case_id)) throw Error('Invalid retained maximum.'); - maximum.append(button(display(point.value) + ' · inspect maximum for ' + subject.label, () => void inspect(point.id, summary.source))); - const token = JSON.stringify([summary.source.origin_catalog_id, summary.source.packet_sha256, point.id]); - inspections.set(token, {id:point.id, source:summary.source}); - points.push({subject_id:subject.id, value:point.value, observation_id:token}); - } - row.append(label, maximum, ...STATES.map(state => node('td', String(summary.states[state])))); maxima.body.append(row); - } - const observations = table('Exact observations on this page', ['Subject','Case','Value / status','Inspection']); - for (const observation of value.rows) { - if (!request.subject_ids.includes(observation.subject_id) || observation.metric_id !== request.metric_id || !identity(observation.id) - || !STATES.includes(observation.state) || (observation.state === 'measured' ? !finite(observation.value) : observation.value !== null)) throw Error('Invalid retained observation row.'); - const subject = subjects.find(item => item.id === observation.subject_id), row = node('tr'), detail = node('td'); - if (!subject || !same(subject.source, observation.source)) throw Error('Observation belongs to another packet.'); - detail.append(button('Inspect ' + observation.id, () => void inspect(observation.id, observation.source)), attributes('Case and execution attributes', observation.dimensions)); - row.append(node('td', subject.label), node('td', observation.case_id), node('td', observation.value === null ? observation.state + ': ' + observation.reason : display(observation.value)), detail); observations.body.append(row); - } - query = value; applied = structuredClone(request); $('results').hidden = false; - $('heading').textContent = value.metric.label + ' · ' + value.metric.units; - $('counts').textContent = `${request.subject_ids.length} selected subjects of ${subjectTotal}; ${value.total} matching observations. Showing ${value.rows.length ? value.offset + 1 : 0}–${value.offset + value.rows.length}. Maxima use every matching case, independent of this page.`; - $('maxima').replaceChildren(maxima.result); $('rows').replaceChildren(observations.result); - const plotTicket = ++plotGeneration; - if (points.length) await renderer.render({maxima:points}, {signal, - isCurrent: () => context?.enabled && context.key === authority && plotTicket === plotGeneration, - onSignal:{measurement_select: selection => { const id = selection?.observation_id?.[0]; const original = inspections.get(id); if (original) void inspect(original.id, original.source); }}}); - else { renderer.clear(); $('chart').append(node('p', 'No measured values for this selection. Missing and failed observations remain counted below.')); } - if (active()) { $('heading').focus(); $('status').textContent = 'Exact retained comparison. Metric and scope definitions are available above.'; } - } - function compare(offset = 0, saved = null) { - return perform(async(active, signal, authority) => { - const request = saved ? {...saved, offset} : {metric_id:$('metric').value, - subject_ids:subjects.filter(item => selectedSubjects.has(item.id)).map(item => item.id), filters:filterValues(), offset, limit:50}; - if (!request.subject_ids.length) throw Error('Choose at least one subject.'); - clearResults(); - const value = checkComparison(await read('measurement_compare', {...selection(), ...request}, signal)).query; if (!active()) return; - await showQuery(value, request, active, signal, authority); - }); - } - $('sources').onclick = () => void loadSources(); - $('sources-prev').onclick = () => void loadSources(Math.max(0, sourceOffset - 40)); - $('sources-next').onclick = () => void loadSources(sourceOffset + 40); - $('source').onchange = () => { invalidate(); clearSource(); $('status').textContent = 'Load the selected compatible sources.'; controls(); }; - $('source-form').onsubmit = event => { - event.preventDefault(); - void perform(async(active, signal) => { - const chosen = [...$('source').selectedOptions].map(option => sources.find(item => sourceKey(item) === option.value)); - clearSource(); selected = chosen; - if (!selected.length || selected.length > 16 || selected.some(item => !item)) throw Error('Choose 1 through 16 retained sources.'); - const response = await read('measurement_compare', selection(), signal); if (!active()) return; - metadata = checkComparison(response); descriptors = response.sources; - if (metadata.query !== null) throw Error('Metadata reply unexpectedly contains a query.'); - subjects = metadata.subjects; subjectTotal = subjects.length; selectedSubjects = new Set(subjects.map(item => item.id)); - $('context').append(node('h3', `Comparison of ${selected.length} retained sources`), node('p', metadata.scope.label + ' · population: ' + metadata.scope.population), - node('p', typeof metadata.scope_definition.task === 'string' ? metadata.scope_definition.task : 'Interpret results using the retained scope definition.'), - jsonDetails('Exact compatible scope, metric definitions and original packet sources', {metadata, sources:descriptors})); - for (const metric of metadata.metrics) { const option = node('option', metric.label + ' · ' + metric.units); option.value = metric.id; $('metric').append(option); } - dimensions(); subjectPage(0); if (!active()) return; - $('form').hidden = false; $('status').textContent = 'Choose a metric, subjects and optional exact attribute filters.'; return $('metric'); - }); - }; - $('source-all').onclick = () => { - for (const option of $('source').options) option.selected = true; - $('source').onchange(); - }; - $('metric').onchange = invalidate; - $('subjects').onchange = () => { - for (const option of $('subjects').options) { - if (option.selected) selectedSubjects.add(option.value); else selectedSubjects.delete(option.value); - } - invalidate(); subjectSelectionStatus(); controls(); - }; - for (const [name, all] of [['subjects-all',true],['subjects-clear',false]]) $(name).onclick = () => { - selectedSubjects = new Set(all ? subjects.map(item => item.id) : []); - invalidate(); subjectPage(subjectOffset); controls(); - }; - for (const [name, direction] of [['subjects-prev',-1],['subjects-next',1]]) $(name).onclick = () => { - void perform(() => subjectPage(subjectOffset + direction * 40)); - }; - $('form').onsubmit = event => { event.preventDefault(); void compare(); }; - $('prev').onclick = () => void compare(Math.max(0, query.offset - query.limit), applied); - $('next').onclick = () => void compare(query.offset + query.limit, applied); - controls(); - return {setContext(value) { - if (value.key !== context?.key || context?.enabled && !value.enabled) { const ownedFocus = ownsFocus(); context = value; reset(); if (ownedFocus) onContextFocusLost(); } - else context = value; - root.hidden = !value.enabled; controls(); - }, clear() { context = null; reset(); root.hidden = true; }}; - }; -})(); diff --git a/static/project-model-portfolio.js b/static/project-model-portfolio.js deleted file mode 100644 index 4f1b7fa3..00000000 --- a/static/project-model-portfolio.js +++ /dev/null @@ -1,188 +0,0 @@ -'use strict'; -// Authored organization is a retained note, not Trial lineage or qualification. -// This module owns its document contract, finite view and cancellable reads. -(() => { - const fields=['method','purpose','experiment','outcome','lesson','reproduction']; - const exact=(value,keys)=>value&&typeof value==='object'&&!Array.isArray(value)&& - Object.keys(value).length===keys.length&&keys.every(key=>Object.hasOwn(value,key)); - const text=(value,limit)=>typeof value==='string'&&value.length>0&&value.length<=limit; - const identity=value=>text(value,160)&&/^[A-Za-z0-9][A-Za-z0-9._:/-]*$/.test(value); - const sha=value=>typeof value==='string'&&/^[a-f0-9]{64}$/.test(value); - const natural=value=>Number.isSafeInteger(value)&&value>=0; - function fail(message,code='invalid'){throw Object.assign(Error(message),{code});} - function noteRef(value){ - if(!exact(value,['file_id','path','revision','sha256'])||!sha(value.file_id)||!sha(value.sha256)|| - !natural(value.revision)||value.revision<1||!text(value.path,512)||!value.path.startsWith('notes/')|| - value.path.split('/').some(part=>!part||part==='.'||part==='..'))fail('Invalid captured model-note reference.'); - } - function decode(raw){ - if(typeof raw!=='string'||new TextEncoder().encode(raw).length>1048576)fail('Organization note exceeds its retained text limit.'); - let value;try{value=JSON.parse(raw);}catch{fail('Organization note is not valid JSON.');} - if(value?.format!=='project_model_portfolio_v1')fail('Unsupported model-organization document format.','unsupported'); - if(!exact(value,['format','project_id','title','description','authorship','groups','models','relationships'])|| - !/^[a-f0-9]{32}$/.test(value.project_id)||!text(value.title,200)||!text(value.description,8000)|| - value.authorship!=='retrospective'||!Array.isArray(value.groups)||value.groups.length>64|| - !Array.isArray(value.models)||!value.models.length||value.models.length>1000|| - !Array.isArray(value.relationships)||value.relationships.length>2000)fail('Invalid model-organization document.'); - const groups=new Map(),models=new Map(); - for(const group of value.groups){ - if(!exact(group,['id','label','parent','description'])||!identity(group.id)||groups.has(group.id)|| - !text(group.label,200)||!text(group.description,8000)||group.parent!==null&&!identity(group.parent))fail('Invalid or duplicate organization group.'); - groups.set(group.id,group); - } - for(const group of groups.values()){ - const visited=new Set([group.id]);let parent=group.parent; - while(parent!==null){if(!groups.has(parent))fail('Organization group parent is unavailable.'); - if(visited.has(parent))fail('Organization grouping contains a cycle.');visited.add(parent);parent=groups.get(parent).parent;} - } - for(const model of value.models){ - if(!exact(model,['id','label','group_id','aliases','review','card','summary'])||!identity(model.id)||models.has(model.id)|| - !text(model.label,500)||!groups.has(model.group_id)||!Array.isArray(model.aliases)||model.aliases.length>128|| - new Set(model.aliases).size!==model.aliases.length||model.aliases.some(alias=>!text(alias,500))|| - !['source_reviewed','review_pending'].includes(model.review))fail('Invalid or duplicate organized model.'); - noteRef(model.card); - if(model.review==='source_reviewed'){ - if(!exact(model.summary,fields)||fields.some(field=>!text(model.summary[field],16384)))fail('Reviewed model requires all six authored summary fields.'); - }else if(model.summary!==null)fail('Pending review cannot expose a reviewed summary.'); - models.set(model.id,model); - } - const pairs=new Set(); - for(const relation of value.relationships){ - if(!exact(relation,['from','to','kind','explanation','evidence_model','excerpt'])|| - !models.has(relation.from)||!models.has(relation.to)||relation.from===relation.to|| - !['comparison','parameter_derivation'].includes(relation.kind)||!text(relation.explanation,8000)|| - !models.has(relation.evidence_model)||!text(relation.excerpt,16384))fail('Invalid authored model relationship.'); - const key=JSON.stringify([relation.from,relation.to,relation.kind]);if(pairs.has(key))fail('Duplicate authored model relationship.');pairs.add(key); - } - const parents=new Map(),complete=new Set(),visiting=new Set(); - for(const relation of value.relationships)if(relation.kind==='parameter_derivation'){ - if(!parents.has(relation.from))parents.set(relation.from,[]);parents.get(relation.from).push(relation.to); - } - function visit(id){if(complete.has(id))return;if(visiting.has(id))fail('Authored parameter derivation contains a cycle.'); - visiting.add(id);for(const parent of parents.get(id)||[])visit(parent);visiting.delete(id);complete.add(id);} - for(const id of parents.keys())visit(id); - return value; - } - function checkCard(document,model,result){ - const ref=model.card,version=result?.version; - if(result?.project_id!==document.project_id||result.id!==ref.file_id||result.path!==ref.path||result.kind!=='note'|| - version?.deleted===true||version?.revision!==ref.revision||version.sha256!==ref.sha256||typeof version.text!=='string') - fail('Model card differs from its exact retained organization reference.'); - if(model.summary&&fields.some(field=>!version.text.includes(model.summary[field])))fail('Authored summary differs from the captured model card.'); - for(const relation of document.relationships)if(relation.evidence_model===model.id&&!version.text.includes(relation.excerpt)) - fail('Authored relationship excerpt differs from its captured model card.'); - return version.text; - } - window.ProjectModelPortfolioDocument=Object.freeze({decode,checkCard}); - const node=(tag,value)=>{const element=document.createElement(tag);if(value!==undefined)element.textContent=value;return element;}; - window.ProjectModelPortfolio=function({root,read,onContextFocusLost=()=>{}}){ - root.innerHTML='

                        Authored model organization

                        Browse a retained guide to models and their methods. Grouping and retrospective comparison notes are separate from recorded Trial ancestry and scientific qualification.

                        '; - const $=name=>root.querySelector('#project-portfolio-'+name); - let context=null,generation=0,pending=null,busy=false,notes=new Map(),noteOffset=0,noteTotal=0; - let guide=null,groups=new Map(),models=new Map(),applied={group:'',search:'',review:''},offset=0,selected=''; - const pageSize=20; - function controls(){ - const enabled=!!context?.enabled; - for(const name of ['notes','notes-more','note','load','group','search','review','prev','next'])$(name).disabled=!enabled||busy; - $('note').disabled ||= !notes.size;$('load').disabled ||= !notes.has($('note').value); - $('notes-more').hidden=noteOffset>=noteTotal;$('notes-more').disabled ||= noteOffset>=noteTotal; - $('prev').disabled ||= !guide||offset===0;$('next').disabled ||= !guide||offset+pageSize>=filtered().length; - for(const button of root.querySelectorAll('#project-portfolio-filter-form button,[data-lineage-node],#project-portfolio-detail button'))button.disabled=!enabled||busy; - root.setAttribute('aria-busy',String(busy)); - } - function clearGuide(){guide=null;groups.clear();models.clear();selected='';offset=0;applied={group:'',search:'',review:''};$('content').hidden=true;$('detail').replaceChildren();$('graph').replaceChildren();$('search').value='';$('review').value='';$('group').replaceChildren();} - function reset(){++generation;pending?.abort();pending=null;busy=false;notes.clear();noteOffset=noteTotal=0;$('note').replaceChildren();$('note-count').textContent='';$('status').textContent='';clearGuide();controls();} - async function perform(work){ - if(!context?.enabled||busy)return; - const ticket=++generation,key=context.key;pending=new AbortController();const signal=pending.signal;busy=true;controls(); - const active=()=>ticket===generation&&context?.enabled&&context.key===key&&!signal.aborted; - try{await work(active,signal);}catch(error){if(active()){$('detail').replaceChildren();$('status').textContent=(error.code?error.code+': ':'')+error.message;$('status').focus();}} - finally{if(active()){busy=false;pending=null;controls();}} - } - async function findNotes(more=false){ - return perform(async(active,signal)=>{ - const requested=more?noteOffset:0,value=await read('files_inspect',{offset:requested,limit:40},signal);if(!active())return; - if(value?.offset!==requested||value.limit!==40||!natural(value.total)||!Array.isArray(value.items)|| - value.items.length!==Math.min(40,Math.max(0,value.total-requested)))fail('Organization note page differs from its continuation.'); - if(!more){clearGuide();notes.clear();$('note').replaceChildren();} - for(const item of value.items)if(item.kind==='note'&&item.path?.endsWith('.portfolio.json')){ - if(!sha(item.id)||!natural(item.revision)||item.revision<1||!sha(item.expected_sha256)||notes.has(item.id))fail('Invalid organization note selection.'); - notes.set(item.id,structuredClone(item));const option=node('option',item.path+' · revision '+item.revision);option.value=item.id;$('note').append(option); - } - noteOffset=requested+value.items.length;noteTotal=value.total; - $('note-count').textContent=`${notes.size} organization notes found; inspected ${noteOffset} of ${noteTotal} adopted files.`; - $('status').textContent=notes.size?'Choose a retained organization note.':'No organization note on these pages. Adopt a .portfolio.json note or inspect the next page.'; - }); - } - function inGroup(model,wanted){let id=model.group_id;while(id!==null){if(id===wanted)return true;id=groups.get(id).parent;}return false;} - function filtered(){if(!guide)return [];return guide.models.filter(model=>(!applied.group||inGroup(model,applied.group))&& - (!applied.review||model.review===applied.review)&&(!applied.search||[model.label,...model.aliases].some(value=>value.toLocaleLowerCase().includes(applied.search))));} - function render(){ - if(!guide)return; - const focused=$('graph').contains(document.activeElement)?document.activeElement.id:null; - const matching=filtered(),shown=matching.slice(offset,offset+pageSize),included=new Set(); - for(const model of shown){let id=model.group_id;while(id!==null){included.add(id);id=groups.get(id).parent;}} - const graphNodes=[...included].map(id=>{const group=groups.get(id);return {id:'group/'+id,title:group.label,recordedAt:'',parent:group.parent===null?null:'group/'+group.parent,baseline:null,lines:['Authored method group']};}); - graphNodes.push(...shown.map(model=>({id:'model/'+model.id,title:model.label,recordedAt:'',parent:'group/'+model.group_id,baseline:null, - lines:[model.aliases.slice(0,3).join(' · ')||model.id,model.review==='source_reviewed'?'Source reviewed · authored summary':'Source review pending']}))); - $('graph').innerHTML=window.WorkspaceExperimentGraph.render(graphNodes,{selected:selected?'model/'+selected:'',zoom:1}).html; - for(const button of $('graph').querySelectorAll('[data-lineage-node]')){ - const value=button.dataset.lineageNode; - button.onclick=()=>{if(value.startsWith('model/'))void selectModel(value.slice(6));else{$('group').value=value.slice(6);applyFilters();}}; - } - $('count').textContent=`${guide.models.length} models in this guide; ${guide.models.filter(model=>model.review==='source_reviewed').length} source reviewed. ${matching.length} match the applied filters. Showing ${shown.length?offset+1:0}–${offset+shown.length}.`; - controls(); - if(focused){const replacement=$('graph').querySelector('#'+CSS.escape(focused)); - if(replacement)replacement.focus({preventScroll:true});else{$('count').tabIndex=-1;$('count').focus();}} - } - function applyFilters(){if(!guide||busy)return;applied={group:$('group').value,search:$('search').value.trim().toLocaleLowerCase(),review:$('review').value}; - if(applied.group&&!groups.has(applied.group))return;offset=0;selected='';$('detail').replaceChildren();render();$('status').textContent='Applied model filters.';} - async function loadGuide(){ - const choice=notes.get($('note').value);if(!choice)return; - return perform(async(active,signal)=>{ - clearGuide();const value=await read('file_get',{file_id:choice.id,revision:choice.revision},signal);if(!active())return; - if(value?.id!==choice.id||value.project_id!==context.project_id||value.kind!=='note'||value.path!==choice.path|| - value.version?.revision!==choice.revision||value.version.sha256!==choice.expected_sha256||value.version.deleted===true)fail('Organization note differs from the selected captured revision.'); - const parsed=decode(value.version.text); - if(parsed.project_id!==context.project_id)fail('This guide belongs to another project; re-author its captured note bindings.','unsupported'); - guide=parsed;groups=new Map(guide.groups.map(group=>[group.id,group]));models=new Map(guide.models.map(model=>[model.id,model])); - $('title').textContent=guide.title;$('description').textContent=guide.description; - $('source').textContent=`Retrospective authored guide · ${choice.path} · revision ${choice.revision} · SHA256 ${choice.expected_sha256}`; - const all=node('option','All groups');all.value='';$('group').append(all); - for(const group of guide.groups){const option=node('option',group.label);option.value=group.id;$('group').append(option);} - $('content').hidden=false;render();$('status').textContent='Loaded retained authored model organization.'; - }); - } - async function selectModel(id){ - const model=models.get(id);if(!model||busy)return; - return perform(async(active,signal)=>{ - if(!filtered().some(item=>item.id===id)){ - applied={group:'',search:'',review:''};$('group').value='';$('search').value='';$('review').value=''; - } - offset=Math.floor(filtered().findIndex(item=>item.id===id)/pageSize)*pageSize; - selected=id;$('detail').replaceChildren();render(); - const value=await read('file_get',{file_id:model.card.file_id,revision:model.card.revision},signal);if(!active())return; - const captured=checkCard(guide,model,value),heading=node('h3',model.label);heading.id='project-portfolio-model-heading';heading.tabIndex=-1;$('detail').append(heading); - $('detail').append(node('p',(model.aliases.join(' · ')||model.id)+' · '+(model.review==='source_reviewed'?'Source reviewed':'Source review pending'))); - if(model.summary){const labels={method:'Method',purpose:'Purpose',experiment:'Training and experiment',outcome:'Observed outcome',lesson:'Lesson',reproduction:'Reproduction'}; - for(const field of fields){$('detail').append(node('h4',labels[field]),node('p',model.summary[field]));}} - else $('detail').append(node('p','A source-reviewed interpretation has not been recorded for this fit. Its original captured card remains available below.')); - const relations=guide.relationships.filter(relation=>relation.from===id||relation.to===id); - if(relations.length){$('detail').append(node('h4','Authored model relationships')); - for(const relation of relations){const box=node('div'),other=models.get(relation.from===id?relation.to:relation.from),button=node('button', - (relation.kind==='comparison'?'Comparison: ':relation.from===id?'Parameters from: ':'Derived model: ')+other.label);button.type='button';button.onclick=()=>void selectModel(other.id); - box.append(button,node('p',relation.explanation));const evidence=node('details');evidence.append(node('summary','Exact retained relationship excerpt'),node('p',relation.excerpt)); - const source=node('button','Read evidence card: '+models.get(relation.evidence_model).label);source.type='button';source.onclick=()=>void selectModel(relation.evidence_model);evidence.append(source);box.append(evidence);$('detail').append(box);}} - const raw=node('details'),summary=node('summary','Exact captured card and original receipts');raw.append(summary,node('p',`${model.card.path} · revision ${model.card.revision} · SHA256 ${model.card.sha256}`),node('pre',captured));$('detail').append(raw); - $('status').textContent='Exact retained model summary and captured evidence.';heading.focus(); - }); - } - $('notes').onclick=()=>void findNotes();$('notes-more').onclick=()=>void findNotes(true); - $('note').onchange=()=>{clearGuide();controls();}; - $('source-form').onsubmit=event=>{event.preventDefault();void loadGuide();}; - $('filter-form').onsubmit=event=>{event.preventDefault();applyFilters();}; - for(const [name,direction] of [['prev',-1],['next',1]])$(name).onclick=()=>{if(busy||!guide)return;offset=Math.max(0,offset+direction*pageSize);selected='';$('detail').replaceChildren();render();}; - controls(); - return {setContext(value){if(value.key!==context?.key||context?.enabled&&!value.enabled){const owned=root.contains(document.activeElement);context=value;reset();if(owned)onContextFocusLost();}else context=value;root.hidden=!value.enabled;controls();},clear(){context=null;reset();root.hidden=true;}}; - }; -})(); diff --git a/static/project-progression.js b/static/project-progression.js deleted file mode 100644 index ae2fa97e..00000000 --- a/static/project-progression.js +++ /dev/null @@ -1,117 +0,0 @@ -'use strict'; -// The native host owns binding/checkpoint/credential changes and exact reads. -// This controller owns source choice, its finite graph window and pending reads. -(() => { - const id=value=>typeof value==='string'&&/^[a-f0-9]{32}$/.test(value); - const natural=value=>Number.isSafeInteger(value)&&value>=0; - const short=value=>String(value).slice(0,12); - const key=(origin,trial)=>origin+'.'+trial; - const element=(tag,text)=>{const e=document.createElement(tag);if(text!==undefined)e.textContent=text;return e;}; - window.ProjectExperimentProgression=function({root,read,inspectStudy,inspectTrial,inspectRun,onContextFocusLost=()=>{}}) { - root.innerHTML='

                        Experiment progression

                        Explore recorded relationships across saved Studies. Solid edges show derivation; dashed edges show comparison baselines. Run states are saved outcomes.

                        '; - const $=name=>root.querySelector('#project-progression-'+name); - let context=null,generation=0,pending=null,busy=false,origins=[],originsNext=0,originsTotal=0; - let nodes=new Map(),origin='',appliedCohort=null,next=0,total=0,related=new Map(),selected='',zoom=1; - function clearGraph(){nodes.clear();related.clear();origin='';appliedCohort=null;next=0;total=0;selected='';$('graph').replaceChildren();$('detail').replaceChildren();$('summary').textContent='';} - function controls(){ - const enabled=!!context?.enabled; - $('origins').disabled=!enabled||busy;$('origins-more').disabled=!enabled||busy; - $('origins-more').hidden=originsNext>=originsTotal; - $('origin').disabled=!enabled||busy||!origins.length;$('cohort').disabled=!enabled||busy; - $('load').disabled=!enabled||busy||!$('origin').value; - $('more').hidden=next>=total;$('more').disabled=!enabled||busy||nodes.size>=100; - for(const name of ['zoom-out','zoom-in','zoom-reset'])$(name).disabled=!enabled||busy||!nodes.size; - for(const button of root.querySelectorAll('[data-lineage-node],#project-progression-detail button'))button.disabled=!enabled||busy; - root.setAttribute('aria-busy',String(busy)); - } - function reset(){ - ++generation;pending?.abort();pending=null;busy=false;clearGraph();origins=[];originsNext=0;originsTotal=0; - const option=element('option','Choose a history source');option.value='';$('origin').replaceChildren(option); - $('cohort').value='';$('status').textContent='';controls(); - } - async function perform(work){ - if(!context?.enabled||busy)return; - const ticket=++generation,authority=context.key;pending=new AbortController();const signal=pending.signal;busy=true;controls(); - const active=()=>ticket===generation&&context?.key===authority&&!signal.aborted; - try{await work(active,signal);}catch(error){if(active()){const ownedFocus=root.contains(document.activeElement);reset();$('status').textContent=error.message;if(ownedFocus)$('origins').focus();}} - finally{if(active()){busy=false;pending=null;controls();}} - } - function page(value,offset,limit,items){ - if(!value||value.offset!==offset||value.limit!==limit||!natural(value.total)||!Array.isArray(items)||items.length!==Math.min(limit,Math.max(0,value.total-offset)))throw Error('History page differs from its selected continuation.'); - } - async function loadOrigins(append=false){ - return perform(async(active,signal)=>{ - const offset=append?originsNext:0,value=await read('progression_origins',{offset,limit:40},signal);if(!active())return; - page(value,offset,40,value.items); - const seen=new Set(append?origins.map(item=>item.origin_catalog_id):[]); - for(const item of value.items){if(!id(item.origin_catalog_id)||seen.has(item.origin_catalog_id)||!natural(item.study_count)||!natural(item.trial_count))throw Error('Invalid history source.');seen.add(item.origin_catalog_id);} - if(!append){clearGraph();origins=[];const option=element('option','Choose a history source');option.value='';$('origin').replaceChildren(option);} - origins.push(...value.items);originsNext=offset+value.items.length;originsTotal=value.total; - for(const item of value.items){const option=element('option',(item.origin_catalog_id===context.project_id?'This project':'Imported catalog '+short(item.origin_catalog_id))+' · '+item.study_count+' Studies · '+item.trial_count+' Trials');option.value=item.origin_catalog_id;$('origin').append(option);} - $('status').textContent=origins.length?'Choose a history source to load its Trials.':'No recorded Study history in this project.'; - if(!append)$('origin').focus(); - }); - } - function validNode(node,source){ - const trial=node?.trial,lineage=node?.lineage; - if(!id(trial?.id)||!id(trial?.study_id)||trial.study_id!==node.study?.id||typeof node.study.name!=='string'|| - trial.material?.catalog_id!==source||!natural(node.attempt_count)||!Array.isArray(node.runs)||node.runs.length>5||node.runs.length>node.attempt_count||node.runs_truncated!==(node.attempt_count>node.runs.length)|| - node.runs.some(run=>!id(run.id)||typeof run.state!=='string'||Object.hasOwn(run,'validation')))throw Error('Invalid saved Trial overview.'); - if(lineage!==null&&(lineage?.trial?.catalog_id!==source||lineage.trial.trial_id!==trial.id||lineage.trial.material_sha256!==trial.material.sha256))throw Error('Trial ancestry belongs to different material.'); - } - async function loadGraph(append=false){ - const requestedOrigin=append?origin:$('origin').value,cohort=append?appliedCohort:($('cohort').value||null),offset=append?next:0; - if(!id(requestedOrigin)||append&&nodes.size>=100)return; - return perform(async(active,signal)=>{ - const args={origin_catalog_id:requestedOrigin,offset,limit:20,...(cohort===null?{}:{cohort})}; - const value=await read('progression',args,signal);if(!active())return; - page(value,offset,20,value.nodes); - if(value.origin_catalog_id!==requestedOrigin||value.evidence!=='saved_metadata_only'||value.historical!==true||value.execution_available!==false||value.cohort!==cohort||!Array.isArray(value.related)||value.related.length>40)throw Error('History response differs from the selected source.'); - const seen=new Set(append?nodes.keys():[]); - for(const node of value.nodes){validNode(node,requestedOrigin);const identity=key(requestedOrigin,node.trial.id);if(seen.has(identity))throw Error('Duplicate Trial in history page.');seen.add(identity);} - for(const ref of value.related)if(!id(ref.catalog_id)||!id(ref.trial_id)||typeof ref.material_sha256!=='string'||!/^[a-f0-9]{64}$/.test(ref.material_sha256))throw Error('Invalid related Trial identity.'); - if(seen.size>100)throw Error('The graph window holds 100 Trials; choose a recorded cohort for another window.'); - if(!append){clearGraph();origin=requestedOrigin;appliedCohort=cohort;} - for(const node of value.nodes)nodes.set(key(origin,node.trial.id),structuredClone(node)); - for(const ref of value.related)related.set(key(ref.catalog_id,ref.trial_id),structuredClone(ref)); - next=offset+value.nodes.length;total=value.total;render(); - $('status').textContent=nodes.size?'Loaded '+nodes.size+' recorded Trials.':'No Trials match this source and recorded cohort.'; - }); - } - function detail(){ - const node=nodes.get(selected);$('detail').replaceChildren();if(!node)return; - const add=(tag,text)=>{const e=element(tag,text);$('detail').append(e);return e;}; - add('h3','Trial '+short(node.trial.id));add('p',node.study.name); - if(node.lineage){const intent=node.lineage.intent;add('p',intent.hypothesis);add('p',intent.change_summary);} - else add('p','Historical ancestry and intent are unknown. No relationships are inferred.'); - for(const kind of ['parent','baseline']){ - const ref=node.lineage?.intent[kind],label=kind==='parent'?'Parent':'Comparison baseline'; - if(ref){const button=add('button',label+' Trial '+short(ref.trial_id));button.type='button';button.onclick=()=>inspectTrial(ref.catalog_id,ref.trial_id);} - else add('p',label+': none declared.'); - } - for(const [label,inspect,identity] of [['Inspect Study',inspectStudy,node.study.id],['Inspect Trial',inspectTrial,node.trial.id]]){const button=add('button',label);button.type='button';button.onclick=()=>inspect(origin,identity);} - add('h4','Saved Run outcomes'); - for(const run of node.runs){const button=add('button','Inspect Run '+short(run.id)+' · saved '+run.state);button.type='button';button.onclick=()=>inspectRun(origin,run.id);} - if(!node.attempt_count)add('p','No recorded admitted attempt.'); - if(node.runs_truncated)add('p','Showing five of '+node.attempt_count+' recorded attempts.'); - const facts=add('details'),summary=element('summary','Exact original references and recorded intent');facts.append(summary,element('pre',JSON.stringify({origin_catalog_id:origin,trial:node.trial,lineage:node.lineage},null,2))); - } - function render(){ - const focused=$('graph').contains(document.activeElement)?document.activeElement.id:null; - const graph=window.WorkspaceExperimentGraph.render([...nodes.values()].map(node=>({id:key(origin,node.trial.id),title:node.study.name,recordedAt:node.lineage?.recorded_at||'', - parent:node.lineage?.intent.parent?key(node.lineage.intent.parent.catalog_id,node.lineage.intent.parent.trial_id):null, - baseline:node.lineage?.intent.baseline?key(node.lineage.intent.baseline.catalog_id,node.lineage.intent.baseline.trial_id):null, - lines:[short(node.trial.id)+' · '+(node.lineage?.intent.ancestry||'ancestry unknown'),node.lineage?.intent.change_summary||'Intent not recorded',(node.runs[0]?.state||'prepared')+' · '+node.attempt_count+' recorded attempts']})),{selected,zoom}); - $('graph').innerHTML=graph.html; - for(const button of $('graph').querySelectorAll('[data-lineage-node]')){button.disabled=busy;button.onclick=()=>{selected=button.dataset.lineageNode;render();$('status').textContent='Selected Trial '+short(nodes.get(selected).trial.id)+'.';};} - const outside=[...related.keys()].filter(identity=>!nodes.has(identity)).length; - $('summary').textContent=nodes.size+' of '+total+' Trials loaded · '+(appliedCohort===null?'all recorded cohorts':'applied cohort: '+appliedCohort)+' · '+outside+' related identities outside this graph window.'; - detail();if(focused)$('graph').querySelector('#'+CSS.escape(focused))?.focus({preventScroll:true}); - } - $('origins').onclick=()=>loadOrigins();$('origins-more').onclick=()=>loadOrigins(true); - $('form').onsubmit=event=>{event.preventDefault();loadGraph();};$('more').onclick=()=>loadGraph(true); - $('origin').onchange=()=>{++generation;pending?.abort();pending=null;busy=false;clearGraph();$('status').textContent='Load the selected history source.';controls();}; - for(const [name,delta] of [['zoom-in',0.2],['zoom-out',-0.2],['zoom-reset',null]])$(name).onclick=()=>{zoom=delta===null?1:Math.max(0.6,Math.min(1.6,zoom+delta));render();}; - return {setContext(value){if(value.key!==context?.key){const ownedFocus=root.contains(document.activeElement);context=value;reset();if(ownedFocus)onContextFocusLost();}else context=value;root.hidden=!value.enabled;controls();},clear(){context=null;reset();root.hidden=true;}}; - }; -})(); diff --git a/static/project-transfer.css b/static/project-transfer.css deleted file mode 100644 index c7acbc75..00000000 --- a/static/project-transfer.css +++ /dev/null @@ -1,2 +0,0 @@ -:root{color-scheme:light dark;--bg:#f5f6f8;--panel:#fff;--ink:#172333;--muted:#4c5b6c;--line:#b9c3cf;--accent:#1648a2;--notice:#fff3d5;--error:#8a1720} -*{box-sizing:border-box}body{margin:0;background:var(--bg);color:var(--ink);font:16px/1.55 system-ui,sans-serif}main{max-width:1080px;margin:0 auto;padding:2rem 1.2rem 5rem}header{max-width:800px;margin-bottom:1.7rem}.eyebrow{font-size:.85rem;text-transform:uppercase;letter-spacing:.08em;color:var(--muted)}h1{line-height:1.15;font-size:clamp(2rem,4vw,2.8rem)}h2{font-size:1.35rem;margin-top:0}h3{font-size:1.05rem}p{overflow-wrap:anywhere}section{background:var(--panel);border:1px solid var(--line);border-radius:.6rem;padding:1.3rem;margin:1.2rem 0}fieldset{border:0;padding:0;margin:0}legend{font-weight:650;margin-bottom:.7rem}label{display:flex;flex-direction:column;gap:.35rem;margin:.7rem 0;font-weight:550}input,select,textarea,button{font:inherit}input,select,textarea{max-width:100%;width:100%;padding:.55rem;border:1px solid var(--line);border-radius:.25rem;background:var(--panel);color:var(--ink)}textarea{resize:vertical}button{padding:.55rem .8rem;margin:.3rem .35rem .3rem 0;cursor:pointer;border:1px solid var(--accent);border-radius:.3rem;color:var(--accent);background:var(--panel)}button:disabled{opacity:.5;cursor:default}a{color:var(--accent)}.grid{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:.2rem 1rem}.actions{align-self:end}.help{font-size:.9rem;color:var(--muted)}.check{display:flex;flex-direction:row;align-items:flex-start;gap:.65rem;font-weight:400}.check input{width:auto;flex:0 0 auto;margin-top:.35rem}.facts{padding-left:1.4rem;overflow-wrap:anywhere}.facts li{margin:.65rem 0}.facts li p{margin:.15rem 0}.facts button{font-size:.85rem;padding:.15rem .4rem}.notice{padding:.8rem;border-left:4px solid #9c6800;background:var(--notice);overflow-wrap:anywhere}#transfer-error{padding:1rem;border:2px solid var(--error);color:var(--error);background:var(--panel);overflow-wrap:anywhere}#transfer-receipt,#report-summary,#transfer-context{overflow-wrap:anywhere}details{margin:1rem 0;border-top:1px solid var(--line);padding-top:.7rem}summary{cursor:pointer;font-weight:600}:focus-visible{outline:3px solid var(--accent);outline-offset:3px}.skip-link{position:absolute;left:1rem;top:-5rem;padding:.5rem;background:var(--panel);z-index:10}.skip-link:focus{top:.5rem}[hidden]{display:none!important}@media(max-width:650px){main{padding:1rem .7rem 3rem}.grid{grid-template-columns:1fr}section{padding:1rem}button{min-height:44px}h1{font-size:2rem}}@media(prefers-color-scheme:dark){:root{--bg:#10171f;--panel:#19232e;--ink:#ecf0f5;--muted:#b7c5d5;--line:#647487;--accent:#99bbff;--notice:#362d18;--error:#ffabb2}} diff --git a/static/project-transfer.html b/static/project-transfer.html deleted file mode 100644 index 504a2c44..00000000 --- a/static/project-transfer.html +++ /dev/null @@ -1,91 +0,0 @@ - - - - - Extract a legacy project · Tuldok - - - - - -
                        -

                        Tuldok / legacy catalog

                        Extract an independent project

                        -

                        Choose one registered project and the global records that belong with it. Review required dependencies before explicitly stopping the source and publishing a new project directory.

                        -

                        Preview reads the source. Extraction preserves its verified post-stop baseline. Scripts stay inert; these controls do not run computations or restore old permissions.

                        -
                        -

                        Reading extraction status…

                        - -
                        -

                        Current controller

                        Sign in to inspect this controller.

                        - - -
                        -
                        -

                        1. Choose the project and source facts

                        -
                        Explicit source selection -
                        -
                        -

                        Global data, Studies and Runs are not assigned to a project by their names or location. Enter the exact IDs you choose; review additional dependencies and unassigned facts in the report.

                        -
                        -
                        - -
                        Add producer observations or working files -
                        -
                        -
                        -
                        -

                        Selected working files become new UTF-8 adoptions attributed to this extraction. No earlier adoption is invented and no script is executed.

                        -
                        -
                        Explicit ownership decisions -
                        -
                        -

                        A required dependency cannot be excluded while claiming a complete extraction.

                        -
                        -
                        Load a prepared selection document - -

                        This imports only the named project snapshot, finite source families and ownership decisions. It does not accept commands, credentials or execution options. Review its summary before preview.

                        -
                        -

                        Selection summary

                          -

                          No selection has been previewed.

                          - -
                          -
                          -
                          -

                          2. Review dependency closure

                          Preview a selection to see its report.

                          -
                          -
                          -

                            - -
                            -
                            -

                            3. Stop the source and capture its backup

                            -

                            Stopping fences new source requests and drains the existing owners. A failed or unknown stop keeps the source fenced and cannot authorize extraction. Keep the private backup separate from the destination.

                            -
                            Explicit stop destinations -
                            -
                            - - -
                            -
                            - -
                            -

                            5. Publish the reviewed project

                            -
                            Independent destination -

                            No stopped destination is confirmed.

                            - -

                            Keep this exact key and destination when reconciling an uncertain outcome. Refreshing status never retries publication.

                            - - -
                            - -

                            Retained outcome

                            No extraction has been acknowledged.

                            - -

                            -
                            -
                            - diff --git a/static/project-transfer.js b/static/project-transfer.js deleted file mode 100644 index 58d00e5c..00000000 --- a/static/project-transfer.js +++ /dev/null @@ -1,203 +0,0 @@ -'use strict'; -// Five installed controller operations; discovery never executes remote schemas. -(()=>{ - const families={records:'Data records',responses:'Responses',preferences:'Comparative judgments',selections:'Saved selections',searches:'Saved searches',graphs:'Pipeline graphs',recipe_drafts:'Recipe definitions',model_definitions:'Model definitions',studies:'Studies',runs:'Historical Runs',releases:'Frozen releases',exposures:'Exposure facts',model_materials:'Model materials',recipe_materials:'Recipe materials',runtime_materials:'Runtime materials'}; - const canonicalFamilies=['workbench_record','workbench_response','workbench_preference','saved_selection','saved_search','pipeline_graph','recipe_definition','model_definition','study_history','trial_history','run_history','candidate_history','dataset_release','dataset_exposure','model_material','recipe_material','runtime_material','project_snapshot','project_artifact','project_file','generation_history','grounded_history','caption_proposal_history','text_proposal_history']; - const shaRoots=new Set(['releases','model_materials','recipe_materials','runtime_materials']),producerKinds=['generation','grounded','caption','text_proposal']; - const sections=['included','required','unassigned','excluded','blockers','warnings','artifacts','working_files']; - const actions=['status','preview','report_page','stop','extract']; - const exact=(v,keys)=>v!==null&&typeof v==='object'&&!Array.isArray(v)&&Object.keys(v).length===keys.length&&keys.every(k=>Object.hasOwn(v,k)); - const text=(v,max,empty=false)=>typeof v==='string'&&Array.from(v).length<=max&&(empty||/\S/u.test(v)); - const id=v=>typeof v==='string'&&/^[a-f0-9]{32}$/.test(v),sha=v=>typeof v==='string'&&/^[a-f0-9]{64}$/.test(v); - const integer=(v,max=1000000)=>Number.isSafeInteger(v)&&v>=0&&v<=max; - const clone=v=>JSON.parse(JSON.stringify(v)); - function protocol(message){const failure=Error(message);failure.code='invalid_response';return failure;} - const leaf=v=>text(v,200)&&!/[\/\\\x00-\x1f]/.test(v)&&!['.','..'].includes(v); - const working=v=>exact(v,['kind','path'])&&['script','note'].includes(v.kind)&&text(v.path,512)&&v.path.startsWith(v.kind==='script'?'scripts/':'notes/')&&!/[\\\x00-\x1f]/.test(v.path)&&v.path.split('/').length<=16&&v.path.split('/').every(p=>p&&!['.','..'].includes(p)); - function normalizeSelection(value){ - if(!exact(value,['project_snapshot','roots','decisions'])||!exact(value.project_snapshot,['id','manifest_sha256'])||!id(value.project_snapshot.id)||!sha(value.project_snapshot.manifest_sha256))throw Error('Choose the exact registered project ID and manifest SHA256.'); - if(!value.roots||typeof value.roots!=='object'||Array.isArray(value.roots)||Object.keys(value.roots).some(k=>!Object.hasOwn(families,k)&&!['producer_jobs','working_files'].includes(k)))throw Error('The selection contains an unknown source family.'); - const roots={}; - for(const family of Object.keys(families)){ - const list=value.roots[family]??[]; - if(!Array.isArray(list)||list.length>10000||new Set(list).size!==list.length||!list.every(shaRoots.has(family)?sha:id))throw Error('Use unique exact '+(shaRoots.has(family)?'SHA256 digests':'IDs')+' for '+families[family]+'.'); - roots[family]=[...list].sort(); - } - const jobs=value.roots.producer_jobs??[],files=value.roots.working_files??[]; - if(!Array.isArray(jobs)||jobs.length>10000||!jobs.every(j=>exact(j,['kind','id'])&&producerKinds.includes(j.kind)&&id(j.id))||new Set(jobs.map(j=>j.kind+':'+j.id)).size!==jobs.length)throw Error('Choose known producer kinds and unique job IDs.'); - if(!Array.isArray(files)||files.length>1000||!files.every(working)||new Set(files.map(f=>f.kind+':'+f.path)).size!==files.length)throw Error('Working files must be unique scripts/... or notes/... paths within the selected project.'); - roots.producer_jobs=clone(jobs).sort((a,b)=>(a.kind+':'+a.id).localeCompare(b.kind+':'+b.id)); - roots.working_files=clone(files).sort((a,b)=>(a.kind+':'+a.path).localeCompare(b.kind+':'+b.path)); - if(!Array.isArray(value.decisions)||value.decisions.length>10000||!value.decisions.every(d=>exact(d,['family','id','include','reason'])&&canonicalFamilies.includes(d.family)&&text(d.id,128)&&typeof d.include==='boolean'&&text(d.reason,1000))||new Set(value.decisions.map(d=>d.family+':'+d.id)).size!==value.decisions.length)throw Error('Each ownership decision needs a known family, exact report ID and reason.'); - const result={project_snapshot:clone(value.project_snapshot),roots,decisions:clone(value.decisions).sort((a,b)=>(a.family+':'+a.id).localeCompare(b.family+':'+b.id))}; - if(new TextEncoder().encode(JSON.stringify(result)).length>1048576)throw Error('The selection exceeds one MiB.'); - return result; - } - const sourceOK=v=>exact(v,['catalog_id','schema_version','catalog_signature','snapshot_sha256','backup_receipt_sha256','external_inventory_sha256'])&&id(v.catalog_id)&&v.schema_version===10&&sha(v.catalog_signature)&&sha(v.snapshot_sha256)&&(v.backup_receipt_sha256===null||sha(v.backup_receipt_sha256))&&sha(v.external_inventory_sha256); - const failureOK=v=>v===null||(v&&typeof v==='object'&&Object.keys(v).every(k=>['action','code','detail','staging_directory'].includes(k))&&['stop','extract'].includes(v.action)&&text(v.code,120)&&text(v.detail,1000,true)&&(v.staging_directory===undefined||leaf(v.staging_directory))); - function receiptOK(v){ - if(v===null)return true; - if(exact(v,['format','committed','project_id','checkpoint','request_key','input_sha256','report_sha256','source','artifacts','verification','replayed']))return v.format==='project_transfer_receipt_v1'&&v.committed===true&&id(v.project_id)&&sha(v.checkpoint)&&text(v.request_key,128)&&sha(v.input_sha256)&&sha(v.report_sha256)&&sourceOK(v.source)&&v.source.backup_receipt_sha256!==null&&exact(v.artifacts,['copied_count','missing_regenerable_count'])&&integer(v.artifacts.copied_count)&&integer(v.artifacts.missing_regenerable_count)&&exact(v.verification,['checkpoint','active_data_records'])&&v.verification.checkpoint===v.checkpoint&&integer(v.verification.active_data_records)&&typeof v.replayed==='boolean'; - return v&&typeof v==='object'&&!Array.isArray(v)&&Object.keys(v).every(k=>['committed','selected','project_id','checkpoint','request_key','directory'].includes(k))&&v.committed===true&&typeof v.selected==='boolean'&&id(v.project_id)&&sha(v.checkpoint)&&text(v.request_key,128)&&(v.directory===undefined||leaf(v.directory)); - } - function stateOK(v){ - if(!exact(v,['format','binding','phase','source_catalog_id','control_catalog_id','roots','available_actions','report','backup','destination','failure','last_receipt'])||v.format!=='project_transfer_state_v1'||!id(v.binding)||!['source_live','source_stopped','source_fenced'].includes(v.phase)||!id(v.source_catalog_id)||!id(v.control_catalog_id)||v.source_catalog_id===v.control_catalog_id||!Array.isArray(v.roots)||!v.roots.length||v.roots.length>100||!v.roots.every(r=>typeof r==='string'&&/^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/.test(r))||new Set(v.roots).size!==v.roots.length||!Array.isArray(v.available_actions)||!v.available_actions.includes('status')||!v.available_actions.every(a=>actions.includes(a))||new Set(v.available_actions).size!==v.available_actions.length||!failureOK(v.failure)||!receiptOK(v.last_receipt))return false; - if(v.report!==null&&(!exact(v.report,['report_sha256','selection_sha256','source','can_extract','counts'])||!sha(v.report.report_sha256)||!sha(v.report.selection_sha256)||!sourceOK(v.report.source)||v.report.source.catalog_id!==v.source_catalog_id||typeof v.report.can_extract!=='boolean'||!exact(v.report.counts,sections)||!Object.values(v.report.counts).every(n=>integer(n))))return false; - if(v.backup!==null&&(!exact(v.backup,['root','directory','receipt_sha256'])||!v.roots.includes(v.backup.root)||!leaf(v.backup.directory)||!sha(v.backup.receipt_sha256)))return false; - if(v.destination!==null&&(!exact(v.destination,['root','directory'])||!v.roots.includes(v.destination.root)||!leaf(v.destination.directory)))return false; - return v.phase!=='source_fenced'||v.available_actions.every(a=>a==='status'); - } - function itemOK(section,v){ - if(['included','unassigned'].includes(section))return exact(v,['family','id','revision'])&&text(v.family,64)&&text(v.id,128)&&(v.revision===null||integer(v.revision)&&v.revision>0); - if(['required','excluded'].includes(section))return exact(v,['family','id'])&&text(v.family,64)&&text(v.id,128); - if(['blockers','warnings'].includes(section))return exact(v,['family','id','code','detail'])&&text(v.family,64)&&text(v.id,128)&&text(v.code,120)&&text(v.detail,1000,true); - if(section==='artifacts')return exact(v,['sha256','bytes','preservation','state'])&&sha(v.sha256)&&integer(v.bytes,Number.MAX_SAFE_INTEGER)&&['unique','regenerable'].includes(v.preservation)&&['verified','missing','corrupt','unverified'].includes(v.state); - return section==='working_files'&&exact(v,['kind','path','sha256','bytes'])&&working({kind:v.kind,path:v.path})&&sha(v.sha256)&&integer(v.bytes,1048576); - } - function pageOK(v){return exact(v,['format','binding','report_sha256','section','items','offset','limit','total'])&&v.format==='project_transfer_report_page_v1'&&id(v.binding)&&sha(v.report_sha256)&§ions.includes(v.section)&&integer(v.offset)&&v.limit===40&&integer(v.total)&&Array.isArray(v.items)&&v.items.length<=40&&v.items.length===Math.min(40,Math.max(0,v.total-v.offset))&&v.items.every(item=>itemOK(v.section,item));} - if(typeof module==='object'&&module.exports)module.exports={normalizeSelection,stateOK,pageOK,receiptOK}; - if(typeof document==='undefined')return; - const $=name=>document.getElementById(name),base='/api/workspace/project-transfer'; - const pins=/* PROJECT_TRANSFER_CONTRACTS_START */ -{ - "project_transfer.extract": "00e0ae9a09d36279684f3614e76445ba1dca50557e55047f699a48b43f823aa8", - "project_transfer.preview": "7072d7f08763dd05e36c9be6b5aa730411948bb34c32361ec80215dd8b31bf24", - "project_transfer.report_page": "09dd19eb4299b323710181ea20a7b4dcffce0c2173eeb51a315d551e72811515", - "project_transfer.status": "190e72fe33a75105b3da034469931b4e30e646ef38af6b55ff8a3c2444725870", - "project_transfer.stop": "050519dab950115508123eef3bf9a9fe4aad40b920a6612b1b850688afec90b8" -} -/* PROJECT_TRANSFER_CONTRACTS_END */; - const routes={status:{method:'GET',path:''},preview:{method:'POST',path:'/preview'},report_page:{method:'GET',path:'/report'},stop:{method:'POST',path:'/stop'},extract:{method:'POST',path:'/extract'}}; - let state=null,contracts=new Set(),draft={roots:{},decisions:[]},busy=false,epoch=0,revision=0,reviewed=false,onlyCessation=false; - let handoff=false,freshControlAttempt=false,freshControl=false,refreshAfter=false,pending=null,lastReceipt=null,page=null,controlCatalog=null,dirty=false; - function error(message){$('transfer-error').hidden=false;$('transfer-error').textContent=message;$('transfer-error').focus();} - function message(value){$('transfer-status').textContent=value;} - function clearError(){$('transfer-error').hidden=true;$('transfer-error').textContent='';} - function currentOwner(){const value=window.TuldokAuth?.identity?.();return value?.kind==='owner'&&value.scopes?.includes('admin');} - function action(name){return currentOwner()&&contracts.has('project_transfer.'+name)&&state?.available_actions.includes(name);} - function signedControl(){return freshControl&&window.TuldokAuth?.identity?.()?.catalog_id===controlCatalog;} - function controls(){ - const live=state?.phase==='source_live',stopped=state?.phase==='source_stopped',report=state?.report; - $('selection-fields').disabled=busy||!!pending||!action('preview')||(stopped&&!signedControl()); - $('transfer-refresh').disabled=busy; - $('report-load').disabled=busy||!report||!action('report_page')||(stopped&&!signedControl()); - $('report-previous').disabled=$('report-load').disabled||!page||page.offset===0; - $('report-next').disabled=$('report-load').disabled||!page||page.offset+page.items.length>=page.total; - $('report-reviewed').disabled=busy||!reviewed||!report; - $('stop-fields').disabled=busy||!live||!action('stop')||!reviewed; - $('transfer-stop').disabled=$('stop-fields').disabled||!onlyCessation||!$('report-reviewed').checked||!$('stop-confirm').checked; - $('extract-fields').disabled=busy||!!pending||!stopped||!signedControl()||!action('extract')||!reviewed||!report?.can_extract; - $('transfer-extract').disabled=$('extract-fields').disabled||!$('report-reviewed').checked||!$('extract-confirm').checked; - $('transfer-reconcile').hidden=!pending; - $('transfer-reconcile').disabled=busy||!pending||!stopped||!signedControl()||!action('extract')||state.report?.report_sha256!==pending.report_sha256; - $('control-signin-panel').hidden=!handoff&&!(stopped&&!signedControl()); - $('control-signin').disabled=busy; - $('transfer-fence').hidden=state?.phase!=='source_fenced'; - $('transfer-fence').textContent='The source remains fenced. No stopped-source proof is available; extraction is unavailable. Retain any reported receipt or staging directory for operator review.'; - } - function invalidate(){revision++;dirty=true;reviewed=false;onlyCessation=false;page=null;$('report-reviewed').checked=false;$('stop-confirm').checked=false;$('extract-confirm').checked=false;$('report-items').replaceChildren();$('selection-dirty').textContent='Selection changed. Explicitly preview it again before any source action.';controls();} - function selection(){return normalizeSelection({project_snapshot:{id:$('snapshot-id').value.trim(),manifest_sha256:$('snapshot-sha').value.trim()},roots:clone(draft.roots),decisions:clone(draft.decisions)});} - function summarize(){ - const list=$('selection-summary');list.replaceChildren(); - for(const [key,values] of Object.entries(draft.roots))if(values.length){const li=document.createElement('li');li.textContent=`${families[key]??(key==='producer_jobs'?'Producer observations':'Working files')}: ${values.length}`;const remove=document.createElement('button');remove.type='button';remove.textContent='Remove this family';remove.onclick=()=>{delete draft.roots[key];invalidate();summarize();};li.append(remove);list.append(li);} - for(const decision of draft.decisions){const li=document.createElement('li');li.textContent=`${decision.include?'Include':'Exclude'} ${decision.family} ${decision.id}: ${decision.reason}`;const remove=document.createElement('button');remove.type='button';remove.textContent='Remove decision';remove.onclick=()=>{draft.decisions=draft.decisions.filter(d=>d!==decision);invalidate();summarize();};li.append(remove);list.append(li);} - if(!list.children.length){const li=document.createElement('li');li.textContent='No global source facts selected. Only the exact registered snapshot will be included unless you add roots.';list.append(li);} - } - function fillRoots(){for(const name of ['backup-root','destination-root']){const node=$(name),old=node.value;node.replaceChildren();for(const alias of state.roots){const option=document.createElement('option');option.value=alias;option.textContent=alias;node.append(option);}if(state.roots.includes(old))node.value=old;}} - function keepReceipt(value){if(!receiptOK(value)||value===null)return;lastReceipt=clone(value);$('transfer-receipt').textContent=`Publication recorded: project ${value.project_id}; ${value.verification?'current verified checkpoint':'recorded checkpoint'} ${value.checkpoint}; request ${value.request_key}.${value.replayed?' Exact request reconciled.':''}`;$('project-files-link').hidden=false;} - function adopt(value,{ownPreview=false}={}){ - if(!stateOK(value))throw protocol('Unsupported extraction controller response. Refresh status before continuing.'); - const changed=state?.binding!==value.binding;state=value;controlCatalog=value.control_catalog_id; - fillRoots();if(value.last_receipt)keepReceipt(value.last_receipt); - if(!ownPreview)$('selection-dirty').textContent='Controller status is current. Explicitly preview your local selection before any source effect.'; - if(changed||!ownPreview){reviewed=false;onlyCessation=false;$('report-reviewed').checked=false;page=null;$('report-items').replaceChildren();} - if(value.phase==='source_live'){handoff=false;freshControl=false;freshControlAttempt=false;} - else{handoff=!signedControl();} - $('transfer-context').textContent=`${value.phase.replaceAll('_',' ')} · source ${value.source_catalog_id} · separate control host ${value.control_catalog_id}`; - $('control-signin-status').textContent=`Control catalog: ${value.control_catalog_id}. ${signedControl()?'Fresh control sign-in verified.':'Submit a new control-host login code using the standard session dialog.'}`; - $('report-summary').textContent=value.report?`Report ${value.report.report_sha256}. Included ${value.report.counts.included}; required ${value.report.counts.required}; unassigned ${value.report.counts.unassigned}; blockers ${value.report.counts.blockers}; warnings ${value.report.counts.warnings}; artifacts ${value.report.counts.artifacts}. ${value.report.can_extract?'Complete stopped-source closure is available.':'Extraction is unavailable until every blocker is resolved.'}`:'No current report. Explicitly preview this selection.'; - if(value.destination){$('destination-root').value=value.destination.root;$('destination-directory').value=value.destination.directory;} - if(value.backup){$('backup-root').value=value.backup.root;$('backup-directory').value=value.backup.directory;} - $('extract-destination').textContent=value.destination?`Confirmed destination: ${value.destination.root} / ${value.destination.directory}.`:'Confirm the destination before stopping the source.'; - if(value.failure){$('transfer-pending').hidden=false;$('transfer-pending').textContent=`${value.failure.action}: ${value.failure.code}. ${value.failure.detail}${value.failure.staging_directory?' Retained stage: '+value.failure.staging_directory+'.':''}`;} - controls(); - } - function row(section,item){const li=document.createElement('li'); - if(section==='artifacts')li.textContent=`${item.sha256} · ${item.bytes} bytes · ${item.preservation} · ${item.state}`; - else if(section==='working_files')li.textContent=`${item.kind}: ${item.path} · ${item.bytes} bytes · ${item.sha256}`; - else{li.textContent=`${item.family} · ${item.id}${item.revision!==undefined&&item.revision!==null?' · revision '+item.revision:''}${item.code?' · '+item.code:''}`;if(item.detail){const detail=document.createElement('p');detail.textContent=item.detail;li.append(detail);}} - return li; - } - async function discover(ticket){ - const response=await window.TuldokAuth.fetch('/api/agent/capabilities',{cache:'no-store'}),value=await response.json(); - if(ticket!==epoch)return false;if(!response.ok)throw Error(value?.error??'Sign in, then refresh extraction status.'); - if(!exact(value,['format','envelope_version','catalog_id','operations','limits'])||value.format!=='agent_capabilities_v1'||value.envelope_version!==1||!id(value.catalog_id)||!Array.isArray(value.operations)||value.operations.length>256||!exact(value.limits,['request_bytes','response_bytes','max_operations'])||value.limits.request_bytes!==1048576||value.limits.response_bytes!==16777216||value.limits.max_operations!==256)throw protocol('Unsupported capability discovery response.'); - if(window.TuldokAuth.identity?.()?.catalog_id!==value.catalog_id)throw Error('Capabilities belong to a different current session.'); - const chosen=new Set(),seen=new Set(); - for(const operation of value.operations){if(!exact(operation,['id','contracts','availability'])||typeof operation.id!=='string'||seen.has(operation.id)||!Array.isArray(operation.contracts)||operation.contracts.length>4||!['available','unavailable','unsupported'].includes(operation.availability))throw Error('Unsupported capability entry.');seen.add(operation.id); - const versions=new Set();for(const contract of operation.contracts){if(!exact(contract,['version','sha256','input_schema','output_schema','scopes','authority','effects','retry','bounds'])||!Number.isSafeInteger(contract.version)||contract.version<1||versions.has(contract.version)||!sha(contract.sha256)||!contract.input_schema||typeof contract.input_schema!=='object'||!contract.output_schema||typeof contract.output_schema!=='object'||!Array.isArray(contract.scopes)||!contract.scopes.every(s=>text(s,40))||!['owner','agent'].includes(contract.authority)||!['read','mutation'].includes(contract.effects)||!['read','cas','receipt','never'].includes(contract.retry)||!exact(contract.bounds,['request_bytes','response_bytes','inline_decoded_bytes','json_depth'])||!Object.values(contract.bounds).every(v=>Number.isSafeInteger(v)&&v>0))throw protocol('Unsupported installed contract discovery frame.');versions.add(contract.version);if(contract.version===1&&operation.availability==='available'&&pins[operation.id]===contract.sha256)chosen.add(operation.id);} - } - contracts=chosen;if(!contracts.has('project_transfer.status'))throw Error('No compatible extraction status contract is available.');return true; - } - async function call(name,args,ticket,{mutation=false}={}){ - const operation='project_transfer.'+name,route=routes[name];if(!contracts.has(operation))throw Error('No compatible contract is available for '+name+'. Refresh status.'); - let response,value; - try{const query=route.method==='GET'&&Object.keys(args).length?'?'+new URLSearchParams(args):'';response=await window.TuldokAuth.fetch(base+route.path+query,{method:route.method,cache:'no-store',headers:{'Tuldok-Operation-Contract':operation+'/1/'+pins[operation],...(route.method==='POST'?{'Content-Type':'application/json'}:{})},...(route.method==='POST'?{body:JSON.stringify(args)}:{})});value=await response.json();} - catch(_){const failure=Error(mutation?'Acknowledgement unavailable. Keep this exact request and refresh status; the source may be fenced or publication may already exist.':'Response unavailable. Refresh status explicitly.');failure.code='transport';throw failure;} - if(new TextEncoder().encode(JSON.stringify(value)).length>1048576)throw Error('Extraction response exceeds its interface bound.'); - if(mutation&&value?.receipt&&receiptOK(value.receipt))keepReceipt(value.receipt); - if(ticket!==epoch){message('A session change superseded the response. Any known publication receipt has been retained. Refresh status before continuing.');return null;} - if(!response.ok){const keys=['error',...(Object.hasOwn(value??{},'code')?['code']:[]),...(Object.hasOwn(value??{},'receipt')?['receipt']:[])];const valid=exact(value,keys)&&text(value.error,1000)&&(!value.code||text(value.code,120))&&(!value.receipt||receiptOK(value.receipt));const failure=Error(valid?`${value.code??'error'}: ${value.error}`:'Unsupported error response. Retain the current request and refresh status.');failure.code=valid?(value.code??'http_error'):'transport';throw failure;} - return value; - } - async function run(work){if(busy)return;busy=true;clearError();const ticket=++epoch;controls();try{await work(ticket);}catch(failure){if(ticket===epoch){if(['invalid_response','transport','stale'].includes(failure.code)){reviewed=false;onlyCessation=false;$('report-reviewed').checked=false;if(failure.code==='invalid_response')contracts.clear();}error(failure.message);}}finally{busy=false;controls();if(refreshAfter){refreshAfter=false;void refresh();}}} - async function refresh(){return run(async ticket=>{if(!await discover(ticket))return;const value=await call('status',{},ticket);if(value){adopt(value);message('Controller status refreshed. No source or publication action was retried.');}});} - async function loadPage(ticket,offset=0,section=$('report-section').value){ - const binding=state?.binding,report=state?.report?.report_sha256;if(!report)throw Error('Preview the selection before loading its report.'); - const value=await call('report_page',{binding,report_sha256:report,section,offset,limit:40},ticket); - if(!value)return;if(!pageOK(value)||value.binding!==binding||value.report_sha256!==report||value.section!==section||value.offset!==offset||value.total!==state.report.counts[section])throw protocol('Report page is stale or unsupported. Preview and review the current report again.'); - page=value;$('report-items').replaceChildren(...value.items.map(item=>row(section,item)));$('report-page-status').textContent=`${section.replaceAll('_',' ')}: ${value.items.length?value.offset+1:0}–${value.offset+value.items.length} of ${value.total}.`; - if(section==='blockers')onlyCessation=value.total===1&&value.items.length===1&&value.items[0].code==='cessation_proof_unavailable'&&value.items[0].family==='source'&&value.items[0].id===state.source_catalog_id; - controls(); - } - function selectionAction(work){try{work();invalidate();summarize();}catch(failure){error(failure.message);}} - for(const [value,label] of Object.entries(families)){const option=document.createElement('option');option.value=value;option.textContent=label;$('selection-family').append(option);} - for(const value of canonicalFamilies){const option=document.createElement('option');option.value=value;option.textContent=value.replaceAll('_',' ');$('decision-family').append(option);} - $('selection-add').onclick=()=>selectionAction(()=>{const key=$('selection-family').value,values=$('selection-ids').value.split(/[\s,]+/u).filter(Boolean);if(!values.length||!values.every(shaRoots.has(key)?sha:id))throw Error('Enter exact '+(shaRoots.has(key)?'SHA256 digests':'32-character IDs')+' for this family.');draft.roots[key]=[...new Set([...(draft.roots[key]??[]),...values])].sort();if(draft.roots[key].length>10000)throw Error('Select at most 10,000 roots per family.');$('selection-ids').value='';}); - $('producer-add').onclick=()=>selectionAction(()=>{const value={kind:$('producer-kind').value,id:$('producer-id').value.trim()};if(!producerKinds.includes(value.kind)||!id(value.id))throw Error('Choose a known producer kind and exact job ID.');const list=draft.roots.producer_jobs??=[];if(!list.some(v=>v.kind===value.kind&&v.id===value.id))list.push(value);$('producer-id').value='';}); - $('working-add').onclick=()=>selectionAction(()=>{const value={kind:$('working-kind').value,path:$('working-path').value.trim()};if(!working(value))throw Error('Use an exact scripts/... or notes/... path without traversal.');const list=draft.roots.working_files??=[];if(!list.some(v=>v.kind===value.kind&&v.path===value.path))list.push(value);$('working-path').value='';}); - $('decision-add').onclick=()=>selectionAction(()=>{const value={family:$('decision-family').value,id:$('decision-id').value.trim(),include:$('decision-include').value==='include',reason:$('decision-reason').value};if(!canonicalFamilies.includes(value.family)||!text(value.id,128)||!text(value.reason,1000))throw Error('Enter a known report family, exact ID and reason.');draft.decisions=draft.decisions.filter(v=>!(v.family===value.family&&v.id===value.id));draft.decisions.push(value);$('decision-id').value='';$('decision-reason').value='';}); - $('selection-clear').onclick=()=>selectionAction(()=>{draft={roots:{},decisions:[]};}); - $('selection-file').onchange=async()=>{const ticket=epoch;try{const file=$('selection-file').files?.[0];if(!file)return;if(file.size>1048576)throw Error('Selection files are limited to one MiB.');const value=normalizeSelection(JSON.parse(await file.text()));if(ticket!==epoch){message('A superseded selection file was ignored. The current selection is unchanged.');return;}$('snapshot-id').value=value.project_snapshot.id;$('snapshot-sha').value=value.project_snapshot.manifest_sha256;draft={roots:value.roots,decisions:value.decisions};invalidate();summarize();message('Loaded a closed selection document. Review its friendly summary, then explicitly preview.');}catch(failure){error('Selection file refused: '+failure.message);}finally{$('selection-file').value='';}}; - for(const name of ['snapshot-id','snapshot-sha'])$(name).addEventListener('input',invalidate); - for(const name of ['report-reviewed','stop-confirm','extract-confirm'])$(name).addEventListener('change',controls); - $('transfer-refresh').onclick=refresh; - $('transfer-preview-form').onsubmit=event=>{event.preventDefault();return run(async ticket=>{const body=selection(),selectedRevision=revision;if(!await discover(ticket))return;const value=await call('preview',{binding:state.binding,selection:body},ticket);if(value&&selectedRevision===revision){adopt(value,{ownPreview:true});reviewed=true;dirty=false;onlyCessation=false;$('selection-dirty').textContent='This exact selection was previewed. Review the report before proceeding.';$('report-section').value='blockers';await loadPage(ticket,0,'blockers');message(state.phase==='source_live'?'Read-only preview complete. Review the closure before any explicit stop.':'Stopped-source preview complete. Review this exact report before extraction.');$('report-title').focus();controls();}});}; - $('report-load').onclick=()=>run(ticket=>loadPage(ticket));$('report-previous').onclick=()=>run(ticket=>loadPage(ticket,Math.max(0,(page?.offset??0)-40)));$('report-next').onclick=()=>run(ticket=>loadPage(ticket,(page?.offset??0)+(page?.items.length??0))); - $('report-section').addEventListener('change',()=>{page=null;controls();}); - $('transfer-stop-form').onsubmit=event=>{event.preventDefault();return run(async ticket=>{ - if(!reviewed||!onlyCessation||!$('report-reviewed').checked||!$('stop-confirm').checked)throw Error('Review this report and explicitly confirm source stop first.'); - const body={binding:state.binding,report_sha256:state.report.report_sha256,backup_root:$('backup-root').value,backup_directory:$('backup-directory').value.trim(),destination_root:$('destination-root').value,directory:$('destination-directory').value.trim()}; - if(!leaf(body.backup_directory)||!leaf(body.directory)||body.backup_root===body.destination_root&&body.backup_directory===body.directory)throw Error('Choose different new backup and destination directory names without separators.'); - handoff=true;freshControl=false;freshControlAttempt=false;reviewed=false;$('report-reviewed').checked=false;message('Explicit source stop is pending. No other effect is available.'); - try{const value=await call('stop',body,ticket,{mutation:true});if(value){adopt(value);message('Source stop returned. Sign in separately to the control host, then explicitly preview again.');$('control-title').focus();}} - finally{handoff=true;$('control-signin-panel').hidden=false;$('control-signin-status').textContent=`Separate control catalog: ${controlCatalog??'refresh controller status'}. Submit a new login code, then refresh status.`;window.dispatchEvent(new MessageEvent('message',{origin:location.origin,data:{type:'tuldok-session-changed'}}));} - });}; - $('control-signin').onclick=()=>{const button=$('session-open');if(button)button.click();else error('The standard session dialog is unavailable.');}; - const loginForm=$('session-form');if(loginForm)loginForm.addEventListener('submit',()=>{if(handoff||state?.phase!=='source_live')freshControlAttempt=true;},true); - const logout=$('session-logout');if(logout)logout.addEventListener('click',()=>{epoch++;contracts.clear();reviewed=false;onlyCessation=false;freshControl=false;freshControlAttempt=false;$('report-reviewed').checked=false;controls();message('Session sign-out requested. Local selection and retained receipts remain; sign in before continuing.');},true); - async function extract(ticket,body){ - pending=clone(body);$('transfer-pending').hidden=false;$('transfer-pending').textContent=`Retained request ${body.request_key} for ${body.destination_root} / ${body.directory}. No automatic retry will occur.`;controls(); - const value=await call('extract',body,ticket,{mutation:true});if(!value)return; - if(!exact(value,['format','binding','receipt','selection'])||value.format!=='project_transfer_extraction_result_v1'||value.binding!==state.binding||!receiptOK(value.receipt)||!exact(value.selection,['selected','state','error'])||typeof value.selection.selected!=='boolean')throw protocol('Unsupported extraction result. Retain its known receipt and refresh status.'); - keepReceipt(value.receipt);const selected=value.selection.selected,project=value.selection.state?.project; - if(selected&&(!project||project.project_id!==value.receipt.project_id||project.checkpoint!==value.receipt.checkpoint))throw protocol('Publication is recorded, but the selected project identity or checkpoint differs. Inspect the file workspace explicitly.'); - pending=null;reviewed=false;$('report-reviewed').checked=false;$('extract-confirm').checked=false;$('transfer-pending').hidden=true;$('selection-outcome').textContent=selected?'At acknowledgement, the verified destination was selected. The file workspace link opens the current inert metadata view.':'Publication is recorded. Selection was unavailable; inspect the file workspace and Open this directory explicitly.'; - message(value.receipt.replayed?'Exact extraction request reconciled against the current destination.':'Project published. No computation was started.');$('outcome-title').focus(); - } - $('transfer-extract-form').onsubmit=event=>{event.preventDefault();return run(async ticket=>{if(!signedControl()||!reviewed||!state?.report?.can_extract||!$('report-reviewed').checked||!$('extract-confirm').checked)throw Error('Sign in to the control host and review the stopped-source report before extraction.');const body={binding:state.binding,report_sha256:state.report.report_sha256,destination_root:state.destination?.root,directory:state.destination?.directory,name:$('destination-name').value,request_key:$('extraction-key').value.trim()};if(!text(body.name,200)||!text(body.request_key,128)||!/^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/.test(body.request_key))throw Error('Enter a project name and exact request key.');await extract(ticket,body);});}; - $('transfer-reconcile').onclick=()=>run(async ticket=>{if(!pending||!signedControl()||state?.report?.report_sha256!==pending.report_sha256)throw Error('Refresh current authorization and this exact report before an explicit reconciliation.');await extract(ticket,{...pending,binding:state.binding});}); - window.addEventListener('tuldok-session',()=>{epoch++;contracts.clear();reviewed=false;onlyCessation=false;$('report-reviewed').checked=false;$('report-items').replaceChildren();if(freshControlAttempt&&window.TuldokAuth.identity?.()?.catalog_id===controlCatalog){freshControl=true;handoff=false;message('Fresh control-host sign-in verified. Explicitly preview the stopped source again.');}controls();if(busy)refreshAfter=true;else void refresh();}); - window.addEventListener('beforeunload',event=>{if(dirty||pending){event.preventDefault();event.returnValue='';}}); - $('extraction-key').value=crypto.randomUUID().replaceAll('-','');summarize();controls();void refresh(); -})(); diff --git a/static/retained-measurement-maxima.vl.json b/static/retained-measurement-maxima.vl.json deleted file mode 100644 index 42035e08..00000000 --- a/static/retained-measurement-maxima.vl.json +++ /dev/null @@ -1 +0,0 @@ -{"$schema":"https://vega.github.io/schema/vega-lite/v5.20.1.json","description":"Maximum retained scalar for each selected subject over all matching cases. Exact values, missing counts and keyboard inspection follow the chart.","width":"container","height":{"step":30},"data":{"name":"maxima"},"mark":{"type":"point","filled":true,"size":100,"color":"#245d8a"},"encoding":{"x":{"field":"value","type":"quantitative","title":"Maximum value (selected metric units)","scale":{"zero":false},"axis":{"format":".3~e"}},"y":{"field":"subject_id","type":"nominal","title":"Subject","sort":null}},"params":[{"name":"measurement_select","select":{"type":"point","fields":["observation_id"],"on":"click","clear":false,"toggle":false}}]} diff --git a/tests/browser_model_portfolio.cjs b/tests/browser_model_portfolio.cjs deleted file mode 100644 index 851e650f..00000000 --- a/tests/browser_model_portfolio.cjs +++ /dev/null @@ -1,129 +0,0 @@ -'use strict'; -// Real Chromium interaction/layout and controlled read-lifecycle evidence. -// This isolated static fixture does not claim native project persistence. -const fs=require('node:fs'),path=require('node:path'),http=require('node:http'),crypto=require('node:crypto'); -const {spawn}=require('node:child_process'); -const {waitForDebugger}=require('./browser_startup.cjs'),{cdpSession}=require('./browser_cdp_session.cjs'); -const output=path.resolve(process.argv[2]||''),engine=process.env.TULDOK_BROWSER_EXECUTABLE; -if(!process.argv[2]||!engine||fs.existsSync(output))throw Error('Explicit fresh output directory and browser executable required'); -fs.mkdirSync(output,{recursive:true,mode:0o700}); -const fixture=structuredClone(require('./model_portfolio_fixture.cjs')); -const hash=value=>crypto.createHash('sha256').update(value).digest('hex'); -const first=fixture.document.models[0]; -const oldMethod=first.summary.method;first.summary.method+=' '+('A physical pressure field with explicit case and work scope. '.repeat(60)); -first.label='First model '; -fixture.cards[0].version.text=fixture.cards[0].version.text.replace(oldMethod,first.summary.method); -fixture.cards[0].version.sha256=first.card.sha256=hash(fixture.cards[0].version.text); -fixture.cards[0].version.bytes=Buffer.byteLength(fixture.cards[0].version.text); -for(let index=0;index<20;index++){ - const model=structuredClone(fixture.document.models[1]);model.id='extra-'+index;model.label='Extra model '+index;model.aliases=[]; - model.card.path='notes/extra-'+index+'.md';model.card.file_id=hash(fixture.project+'\0note\0'+model.card.path); - fixture.document.models.push(model);fixture.cards.push({...structuredClone(fixture.cards[1]),id:model.card.file_id,path:model.card.path}); -} -fixture.guide.version.text=JSON.stringify(fixture.document); -fixture.guide.version.sha256=fixture.inspection.expected_sha256=fixture.inspection.observed_sha256=hash(fixture.guide.version.text); -fixture.guide.version.bytes=fixture.inspection.expected_bytes=fixture.inspection.observed_bytes=Buffer.byteLength(fixture.guide.version.text); -const inline=JSON.stringify(fixture).replaceAll('<','\\u003c'); -const html=`Authored organization fixture
                            `; -const staticRoot=path.join(__dirname,'../static'),allowed=new Map([ - ['/project-files.css',['project-files.css','text/css']],['/experiment-lineage.css',['experiment-lineage.css','text/css']], - ['/experiment-graph.js',['experiment-graph.js','text/javascript']],['/project-model-portfolio.js',['project-model-portfolio.js','text/javascript']]]); -const server=http.createServer((request,response)=>{ - if(request.url==='/'){response.writeHead(200,{'Content-Type':'text/html; charset=utf-8'});response.end(html);return;} - const asset=allowed.get(request.url);if(!asset){response.writeHead(404);response.end();return;} - response.writeHead(200,{'Content-Type':asset[1]});response.end(fs.readFileSync(path.join(staticRoot,asset[0]))); -}); -let child,session; -const report={status:'starting',engine,verification_only:true,native_persistence_claim:false,graphics:'Headless Chromium with GPU disabled; no model or rendering speed claim.',checks:[],errors:[],browser_stopped:false}; -const sourceFiles=['app.py','static/project-files.css','static/project-files.html','static/project-files.js','static/project-model-portfolio.js', - 'docs/contracts/project-model-portfolio.md','tests/model_portfolio_fixture.cjs','tests/test_project_model_portfolio.cjs', - 'tests/browser_model_portfolio.cjs','tests/test_project_model_portfolio_http.py','tests/test_workspace_project_files.cjs','tests/test_workspace_project_files_m4.cjs']; -report.source_sha256=Object.fromEntries(sourceFiles.map(name=>[name,hash(fs.readFileSync(path.join(__dirname,'..',name)))])); -const pause=ms=>new Promise(resolve=>setTimeout(resolve,ms)); -async function main(){ - await new Promise(resolve=>server.listen(0,'127.0.0.1',resolve)); - const origin='http://127.0.0.1:'+server.address().port; - try{ - const flags=['--headless','--disable-gpu','--no-first-run','--no-default-browser-check','--remote-debugging-port=0','--window-size=1440,1000','--user-data-dir='+path.join(output,'profile'),'about:blank']; - report.flags=flags;report.origin=origin; - const log=fs.openSync(path.join(output,'browser.log'),'w');child=spawn(engine,flags,{stdio:['ignore',log,log]});fs.closeSync(log); - const port=await waitForDebugger(child,path.join(output,'profile/DevToolsActivePort')); - const targets=await(await fetch('http://127.0.0.1:'+port+'/json/list')).json(),target=targets.find(target=>target.type==='page'); - const socket=new WebSocket(target.webSocketDebuggerUrl);await new Promise((resolve,reject)=>{socket.addEventListener('open',resolve,{once:true});socket.addEventListener('error',reject,{once:true});}); - session=cdpSession(socket,{onEvent:event=>{if(event.method==='Runtime.exceptionThrown')report.errors.push(event.params.exceptionDetails.text);}}); - const send=session.send; - await send('Page.enable');await send('Runtime.enable'); - async function evaluate(expression){const result=await send('Runtime.evaluate',{expression,returnByValue:true,awaitPromise:true});if(result.exceptionDetails)throw Error(result.exceptionDetails.exception?.description||result.exceptionDetails.text);return result.result.value;} - async function until(expression){const end=Date.now()+15000;while(Date.now(){const element=document.querySelector(${JSON.stringify(selector)});if(!element||element.disabled)throw Error('Unavailable fixture control');element.scrollIntoView({block:'center'});element.focus();})()`); - await send('Input.dispatchKeyEvent',{type:'keyDown',key:'Enter',code:'Enter',windowsVirtualKeyCode:13,text:'\r'});await send('Input.dispatchKeyEvent',{type:'keyUp',key:'Enter',code:'Enter',windowsVirtualKeyCode:13});} - async function fill(selector,value){await evaluate(`(()=>{const element=document.querySelector(${JSON.stringify(selector)});element.value=${JSON.stringify(value)};element.dispatchEvent(new Event('input',{bubbles:true}));element.dispatchEvent(new Event('change',{bubbles:true}));})()`);} - async function screenshot(name){const shot=await send('Page.captureScreenshot',{format:'png',captureBeyondViewport:false});fs.writeFileSync(path.join(output,name),Buffer.from(shot.data,'base64'));} - async function load(){await keyClick('#project-portfolio-notes');await until("document.querySelector('#project-portfolio-note').options.length===1");await keyClick('#project-portfolio-load');await until("document.querySelector('#project-portfolio-status').textContent==='Loaded retained authored model organization.'");} - async function selectFirst(){await keyClick('[data-lineage-node="model/fit-first"]');await until("document.querySelector('#project-portfolio-status').textContent==='Exact retained model summary and captured evidence.'");} - await send('Page.navigate',{url:origin+'/'});await until("!!window.fixtureUI"); - await load();await check('readCalls.length===2','Guide loading reads no model card or payload'); - await check("document.querySelector('#project-portfolio-count').textContent.includes('22 models in this guide; 1 source reviewed')",'Exact complete and reviewed guide counts'); - const point=await evaluate("(()=>{const element=document.querySelector('[data-lineage-node=\"group/pressure\"]');element.scrollIntoView({block:'center'});const box=element.getBoundingClientRect();return {x:box.x+box.width/2,y:box.y+box.height/2};})()"); - await send('Input.dispatchMouseEvent',{type:'mousePressed',button:'left',clickCount:1,...point});await send('Input.dispatchMouseEvent',{type:'mouseReleased',button:'left',clickCount:1,...point}); - await check("document.querySelector('#project-portfolio-group').value==='pressure'&&document.activeElement.dataset.lineageNode==='group/pressure'",'Pointer group activation applies the group and retains visible keyboard focus'); - await check("!document.querySelector('#root img')&&!window.injected",'Authored graph labels remain inert text'); - await keyClick('#project-portfolio-next');await check("document.querySelector('#project-portfolio-count').textContent.includes('Showing 21–22.')",'Bounded model paging uses the full population'); - await keyClick('#project-portfolio-prev');await selectFirst(); - await check("document.activeElement.id==='project-portfolio-model-heading'",'Keyboard selection moves focus to selected summary'); - await check("document.querySelector('#project-portfolio-detail').innerText.includes(fixtureData.document.models[0].summary.method)",'Complete long method paragraph is readable retained text'); - await check("document.querySelector('#project-portfolio-detail').scrollWidth<=document.querySelector('#project-portfolio-detail').clientWidth",'Desktop detail wraps without horizontal overflow'); - await evaluate("document.querySelector('#project-portfolio-model-heading').scrollIntoView({block:'start'})");await screenshot('desktop-summary.png'); - await send('Emulation.setDeviceMetricsOverride',{width:390,height:844,deviceScaleFactor:1,mobile:true}); - await check("document.querySelector('#project-portfolio-detail').scrollWidth<=document.querySelector('#project-portfolio-detail').clientWidth",'Mobile detail wraps without horizontal overflow'); - await evaluate("document.querySelector('#project-portfolio-model-heading').scrollIntoView({block:'start'})");await screenshot('mobile-summary.png'); - await send('Emulation.clearDeviceMetricsOverride'); - await fill('#project-portfolio-search','C107');await keyClick('#project-portfolio-filter-form button'); - await check("document.querySelector('#project-portfolio-count').textContent.includes('1 match the applied filters')&&document.querySelector('#project-portfolio-next').disabled",'Alias filtering has exact counts and paging'); - await selectFirst();await keyClick('#project-portfolio-detail button');await until("document.querySelector('#project-portfolio-model-heading')?.textContent==='Second model'"); - await check("document.querySelector('#project-portfolio-detail').innerText.includes('A source-reviewed interpretation has not been recorded')",'Pending review does not invent a method summary'); - await check("document.querySelector('[data-lineage-node=\"model/fit-second\"]').getAttribute('aria-pressed')==='true'",'Off-filter relationship navigation brings selected model into the graph window'); - await selectFirst();await evaluate('window.failNext=true');await keyClick('#project-portfolio-detail button'); - await until("document.querySelector('#project-portfolio-status').textContent==='unavailable: Retained card unavailable.'"); - await check("document.querySelector('#project-portfolio-detail').children.length===0",'Unavailable card clears the previous model detail'); - await evaluate('window.corruptNext=true');await keyClick('[data-lineage-node="model/fit-first"]'); - await until("document.querySelector('#project-portfolio-status').textContent==='invalid: Model card differs from its exact retained organization reference.'"); - await check("document.querySelector('#project-portfolio-detail').children.length===0",'Foreign card revision is refused without stale detail'); - await evaluate('window.holdNext=true');await keyClick('[data-lineage-node="model/fit-first"]');await until('!!window.releaseHeld'); - await evaluate("fixtureUI.setContext({key:'two',project_id:fixtureData.project,enabled:true});window.releaseHeld()"); - await check("window.heldSignal.aborted&&document.querySelector('#project-portfolio-content').hidden",'Context replacement aborts and clears pending view'); - await load();await check("document.querySelector('#project-portfolio-detail').children.length===0",'Reload after supersession starts without old detail'); - await selectFirst();await evaluate("fixtureUI.setContext({key:'two',project_id:fixtureData.project,enabled:false})"); - await check("document.querySelector('#root').hidden&&document.querySelector('#project-portfolio-detail').children.length===0&&document.activeElement.id==='outside'",'Permission loss clears private view and restores host focus'); - await evaluate("fixtureUI.setContext({key:'three',project_id:fixtureData.project,enabled:true})");await load(); - await fill('#project-portfolio-search','No match');await keyClick('#project-portfolio-filter-form button'); - await check("document.querySelector('#project-portfolio-count').textContent.includes('0 match the applied filters. Showing 0–0.')",'Empty filter result retains exact zero denominator'); - await check('readCalls.every(call=>[\'files_inspect\',\'file_get\'].includes(call.action))','All interactions use read-only project-file actions'); - if(report.errors.length)throw Error('Browser runtime exception');report.status='passed_authored_portfolio_real_browser_component'; - }catch(error){report.status='failed_authored_portfolio_real_browser_component';report.error=String(error); - if(session){try{const state=await session.send('Runtime.evaluate',{expression:'document.body.innerText',returnByValue:true});report.failure_page=state.result?.value; - const shot=await session.send('Page.captureScreenshot',{format:'png',captureBeyondViewport:false});fs.writeFileSync(path.join(output,'failed-page.png'),Buffer.from(shot.data,'base64'));}catch(captureError){report.failure_capture_error=String(captureError);}} - throw error;} - finally{session?.close();if(child&&child.exitCode===null&&child.signalCode===null){child.kill('SIGTERM');for(let i=0;i<100&&child.exitCode===null&&child.signalCode===null;i++)await pause(50);if(child.exitCode===null&&child.signalCode===null)child.kill('SIGKILL');} - report.browser_stopped=!child||child.exitCode!==null||child.signalCode!==null;await new Promise(resolve=>server.close(resolve)); - report.end_source_sha256=Object.fromEntries(sourceFiles.map(name=>[name,hash(fs.readFileSync(path.join(__dirname,'..',name)))])); - report.source_stable_through_tests=JSON.stringify(report.source_sha256)===JSON.stringify(report.end_source_sha256); - if(!report.source_stable_through_tests){report.status='failed_authored_portfolio_real_browser_component';report.errors.push('Source changed during browser qualification');process.exitCode=1;} - report.producer_sha256=hash(fs.readFileSync(__filename));fs.writeFileSync(path.join(output,'report.json'),JSON.stringify(report,null,2)+'\n');} - console.log(report.status,report.checks.length,'checks'); -} -main().catch(error=>{console.error(String(error));process.exitCode=1;}); diff --git a/tests/browser_project_file_deletion.cjs b/tests/browser_project_file_deletion.cjs deleted file mode 100644 index ab811e53..00000000 --- a/tests/browser_project_file_deletion.cjs +++ /dev/null @@ -1,127 +0,0 @@ -'use strict'; -// Actual explicit note deletion, restore, independent fork and cold keyboard review. -const assert=require('node:assert/strict'),fs=require('node:fs'),os=require('node:os'),path=require('node:path'),crypto=require('node:crypto'); -const {spawn,execFileSync}=require('node:child_process'),{once}=require('node:events'); -const {authenticatedFixture}=require('./auth_helpers.cjs'),{waitForDebugger}=require('./browser_startup.cjs'),{cdpSession}=require('./browser_cdp_session.cjs'),{qaDirectory,screenshotOptions}=require('./qa_artifacts.cjs'); -const root=path.resolve(__dirname,'..'),hash=raw=>crypto.createHash('sha256').update(raw).digest('hex'); -assert.equal(process.env.TULDOK_NOTE_DELETION_GO,'1','Explicit note-deletion qualification GO required'); -assert.ok(process.env.TULDOK_DATABASE_URL&&process.env.TULDOK_PROJECT_FILES_COLD_DATABASE_URL,'Disposable source and cold PostgreSQL configurations required'); -assert.ok(process.env.TULDOK_M4_FREEZE_MANIFEST,'Lead must freeze and enable M4 before actual browser acceptance'); -const freeze=JSON.parse(fs.readFileSync(process.env.TULDOK_M4_FREEZE_MANIFEST,'utf8')); -const material={manifest_sha256:hash(fs.readFileSync(process.env.TULDOK_M4_FREEZE_MANIFEST)),files:freeze.files}; -function verifySource(){for(const [file,expected] of Object.entries(material.files))assert.equal(hash(fs.readFileSync(path.join(root,file))),expected,'Frozen source changed: '+file);} -verifySource(); -const testSha=hash(fs.readFileSync(__filename)),temporary=fs.mkdtempSync(path.join(os.tmpdir(),'tuldok-note-deletion-browser-')),report=qaDirectory(root,'project-note-deletion'); -// HTML textarea value normalizes CR/CRLF; portable version bytes stay exact. -const displayed=raw=>raw.toString().replace(/\r\n?/g,'\n'); -const sourceDsn=process.env.TULDOK_DATABASE_URL,coldDsn=process.env.TULDOK_PROJECT_FILES_COLD_DATABASE_URL; -assert.notEqual(sourceDsn,coldDsn); -const external=path.join(temporary,'external');fs.mkdirSync(external); -const children=[],catalogs=[],checks=[],errors=[],httpErrors=[],bounds=[]; -const gitEnv={...process.env,GIT_CONFIG_NOSYSTEM:'1',GIT_CONFIG_GLOBAL:'/dev/null',GIT_TERMINAL_PROMPT:'0'}; -const routes=JSON.parse(execFileSync('python3',['-c',"import json,agent_api;names=agent_api.ProjectFilesOwnerClient.OPERATIONS;print(json.dumps({n.split('.')[1]:{**{k:agent_api.operation(n)[k] for k in ('path','method','query','side_effects')},'header':agent_api.selected_header(n)} for n in names}))"],{cwd:root,encoding:'utf8'})); -let server,origin,auth,socket,session,send,evaluate,serverErrors='',isolation; -const pause=ms=>new Promise(resolve=>setTimeout(resolve,ms)); -async function until(fn,label){for(let i=0;i<200;i++){const result=await fn();if(result)return result;await pause(100);}throw Error('Timed out: '+label);} -function launch(command,args,options={}){const child=spawn(command,args,options);children.push(child);return child;} -async function stop(child){if(!child||child.exitCode!==null||child.signalCode!==null)return;const exited=once(child,'exit');child.kill('SIGTERM');await exited;} -async function start(control,directory,dsn){ - process.env.TULDOK_DATABASE_URL=dsn;serverErrors='';let output=''; - server=launch('python3',['-u','app.py','--port','0','--data',control,'--project-files-root','fixture='+directory],{cwd:root,env:{...process.env,TULDOK_DATABASE_URL:dsn},stdio:['ignore','pipe','pipe']}); - server.stdout.on('data',chunk=>output+=chunk);server.stderr.on('data',chunk=>serverErrors+=chunk); - const port=await until(()=>{if(server.exitCode!==null)throw Error('Server exited: '+serverErrors);return output.match(/127\.0\.0\.1:(\d+)/)?.[1];},'actual server startup'); - origin='http://127.0.0.1:'+port;catalogs.push({control,dsn});auth=authenticatedFixture();await auth.register(origin,control,root); -} -async function state(){const response=await auth.fetch(origin+routes.status.path,{headers:{'Tuldok-Operation-Contract':routes.status.header}});const value=await response.json();assert.equal(response.status,200,JSON.stringify(value));return value;} -async function call(action,fields={}){ - const current=await state(),definition=routes[action],arguments_={binding:current.binding,[definition.side_effects?'expected_checkpoint':'checkpoint']:current.project.checkpoint,...(definition.side_effects?{request_key:crypto.randomUUID().replaceAll('-','')} :{}),...fields}; - let target=definition.path;for(const [key,value] of Object.entries(arguments_))target=target.replace('{'+key+'}',encodeURIComponent(value)); - const query=new URLSearchParams(Object.entries(arguments_).filter(([key])=>definition.query.includes(key)));if(query.size)target+='?'+query; - const body=Object.fromEntries(Object.entries(arguments_).filter(([key])=>!definition.query.includes(key)&&!definition.path.includes('{'+key+'}'))); - const response=await auth.fetch(origin+target,{method:definition.method,headers:{'Content-Type':'application/json','Tuldok-Operation-Contract':definition.header},...(definition.method==='POST'?{body:JSON.stringify(body)}:{})}); - const value=await response.json();assert.equal(response.status,200,JSON.stringify(value));return value.value; -} -async function key(key,code=key,modifiers=0){for(const type of ['keyDown','keyUp'])await send('Input.dispatchKeyEvent',{type,key,code,modifiers,windowsVirtualKeyCode:{Enter:13,Tab:9,a:65}[key]||0,...(type==='keyDown'&&key==='Enter'?{text:'\r',unmodifiedText:'\r'}:{})});} -async function focus(selector){await until(()=>evaluate(`(()=>{const e=document.querySelector(${JSON.stringify(selector)});if(!e||e.disabled||!e.getClientRects().length)return false;e.scrollIntoView({block:'center'});e.focus();return document.activeElement===e;})()`),'focus '+selector);} -async function fill(selector,value){await focus(selector);await key('a','KeyA',2);await send('Input.insertText',{text:value});} -async function activate(selector){await focus(selector);await key('Enter');} -async function choose(selector,value){await focus(selector);await evaluate(`(()=>{const e=document.querySelector(${JSON.stringify(selector)});if(!Array.from(e.options).some(o=>o.value===${JSON.stringify(value)}))throw Error('Missing option');e.value=${JSON.stringify(value)};e.dispatchEvent(new Event('change',{bubbles:true}));e.dispatchEvent(new Event('input',{bubbles:true}));})()`);} -async function settled(){await until(async()=>{const failure=await evaluate('document.getElementById("project-files-error").textContent');if(failure)throw Error('UI error: '+failure);return evaluate('!document.getElementById("project-files-save").disabled');},'acknowledged UI state');} -async function navigate(){await auth.browser(send,origin);await send('Page.navigate',{url:origin+'/project-files'});await until(()=>evaluate('!!document.querySelector("#project-files-root option")&&!document.getElementById("project-files-new").disabled'),'negotiated UI startup');} -async function working(kind,file,raw,revision=0){ - await choose('#project-working-kind',kind);await fill('#project-working-path',file);await fill('#project-working-revision',String(revision));await fill('#project-working-sha',hash(raw)); - await activate('#project-working-adopt-form button[type="submit"]');await settled(); - assert.equal(await evaluate('document.getElementById("project-working-text").value'),displayed(raw)); - const observed=(await call('files_inspect')).items.find(item=>item.path===file);assert.ok(observed);const captured=await call('file_get',{file_id:observed.id,revision:observed.revision});assert.deepEqual(Buffer.from(captured.version.text),raw,'Captured public revision retains exact bytes despite native textarea newline rendering'); -} -async function inspectFile(file){ - await activate('#project-working-load');await settled(); - await evaluate(`(()=>{const b=Array.from(document.querySelectorAll('#project-working-list button')).find(e=>e.textContent.startsWith(${JSON.stringify(file+' ·')}));if(!b)throw Error('Missing working file');b.dataset.qaSelected='yes';})()`); - await activate('#project-working-list button[data-qa-selected="yes"]');await settled(); -} -async function capture(width){ - await send('Emulation.setDeviceMetricsOverride',{width,height:950,deviceScaleFactor:1,mobile:false});await evaluate('document.getElementById("project-working-heading").scrollIntoView({block:"start"})'); - await evaluate('new Promise(resolve=>requestAnimationFrame(()=>requestAnimationFrame(resolve)))'); - const value=await evaluate('({viewport:innerWidth,width:document.documentElement.scrollWidth,client:document.documentElement.clientWidth,offenders:Array.from(document.querySelectorAll("body *")).filter(e=>e.getClientRects().length&&e.getBoundingClientRect().right>innerWidth+1).map(e=>({tag:e.tagName,id:e.id,width:e.getBoundingClientRect().width,right:e.getBoundingClientRect().right,text:e.textContent.slice(0,100)})).slice(-20)})'); - bounds.push(value);fs.writeFileSync(path.join(report,'bounds-'+width+'.json'),JSON.stringify(value,null,2)+'\n');fs.writeFileSync(path.join(report,'note-cold-'+width+'.jpg'),Buffer.from((await send('Page.captureScreenshot',screenshotOptions)).data,'base64')); - assert.ok(value.width<=value.viewport+1,'Responsive overflow: '+JSON.stringify(value)); -} -function snapshot(directory){const files={};function walk(at){for(const item of fs.readdirSync(at,{withFileTypes:true})){if(['.git','.tuldok-local'].includes(item.name))continue;const next=path.join(at,item.name);if(item.isDirectory())walk(next);else if(item.isFile())files[path.relative(directory,next)]=hash(fs.readFileSync(next));else throw Error('Unexpected special fixture file');}}walk(directory);return files;} -function check(value){checks.push(value);console.log('PASS '+value);} -async function inspectIntent(){ - await activate('#project-intents-load');await settled();await until(()=>evaluate('document.querySelectorAll("#project-intents-list button").length===1'),'one unresolved recipe'); - await activate('#project-intents-list button');await settled(); - return JSON.parse(await evaluate('document.getElementById("project-intent-detail").textContent')); -} -(async()=>{ - isolation=JSON.parse(execFileSync('python3',['-c',"import json,os,psycopg;from psycopg.conninfo import conninfo_to_dict;s=conninfo_to_dict(os.environ['TULDOK_DATABASE_URL']);c=psycopg.connect(os.environ['TULDOK_PROJECT_FILES_COLD_DATABASE_URL']);row=c.execute('SELECT current_database(),current_user,has_database_privilege(current_user,%s,%s)',(s['dbname'],'CONNECT')).fetchone();assert row[0]!=s['dbname'] and not row[2];print(json.dumps(dict(database=row[0],role=row[1],source_connect=row[2])));c.close()"],{cwd:root,encoding:'utf8'})); - await start(path.join(temporary,'control'),external,sourceDsn); - const browser=launch(process.env.BROWSER||'/usr/bin/chromium',['--headless','--no-sandbox','--disable-gpu','--no-first-run','--remote-debugging-port=0','--window-size=1440,950','--user-data-dir='+path.join(temporary,'browser'),'about:blank'],{stdio:'ignore',env:{...process.env,XDG_CONFIG_HOME:temporary,XDG_CACHE_HOME:temporary}}); - const port=await waitForDebugger(browser,path.join(temporary,'browser','DevToolsActivePort')),tabs=await(await fetch('http://127.0.0.1:'+port+'/json')).json(),target=tabs.find(tab=>tab.type==='page'&&tab.url==='about:blank');assert.ok(target); - socket=new WebSocket(target.webSocketDebuggerUrl);await once(socket,'open');session=cdpSession(socket,{onEvent:event=>{if(event.method==='Runtime.exceptionThrown')errors.push(event.params.exceptionDetails);if(event.method==='Network.responseReceived'&&event.params.response.status>=400)httpErrors.push({url:event.params.response.url,status:event.params.response.status});}});send=session.send; - evaluate=async expression=>{const result=await send('Runtime.evaluate',{expression,awaitPromise:true,returnByValue:true});if(result.exceptionDetails)throw Error(JSON.stringify(result.exceptionDetails));return result.result.value;}; - await send('Page.enable');await send('Runtime.enable');await send('Network.enable');await navigate(); - await fill('#project-files-directory','alpha');await fill('#project-files-name','Note deletion keyboard Ω');await activate('#project-files-new');await settled(); - const originalState=await state(),originalProject=originalState.project.project_id,source=path.join(external,'alpha'),note=path.join(source,'notes/scientist.md'); - fs.mkdirSync(path.join(source,'notes')); - const first=Buffer.from('Exact scientist rationale Ω 山\r\n\n'),restored=Buffer.from('Explicit restored decision 🌸\n'); - fs.writeFileSync(note,first);fs.writeFileSync(path.join(source,'notes/empty.md'),''); - await working('note','notes/scientist.md',first);await working('note','notes/empty.md',Buffer.alloc(0)); - await inspectFile('notes/empty.md');assert.match(await evaluate('document.getElementById("project-working-summary").textContent'),/empty file/);assert.doesNotMatch(await evaluate('document.getElementById("project-working-summary").textContent'),/deletion/); - fs.unlinkSync(note);await inspectFile('notes/scientist.md'); - assert.equal(await evaluate('document.getElementById("project-working-text").value'),displayed(first));assert.equal(await evaluate('document.getElementById("project-working-delete-fields").disabled'),false); - const before=(await state()).project.checkpoint;await activate('#project-working-delete');await pause(100);assert.equal((await state()).project.checkpoint,before,'Unchecked deletion must have no effect'); - await focus('#project-working-delete-confirm');await key(' ','Space');assert.equal(await evaluate('document.getElementById("project-working-delete-confirm").checked'),true); - await activate('#project-working-delete');await settled();assert.ok(!fs.existsSync(note));assert.match(await evaluate('document.getElementById("project-working-summary").textContent'),/note deletion retained/);assert.equal(await evaluate('document.getElementById("project-working-text").value'),''); - await activate('#project-working-history');await settled();assert.equal(await evaluate('document.querySelectorAll("#project-working-history-list button").length'),2);assert.match(await evaluate('document.querySelectorAll("#project-working-history-list button")[1].textContent'),/note deletion/); - await activate('#project-working-history-list button');await settled();assert.equal(await evaluate('document.getElementById("project-working-text").value'),displayed(first));assert.equal(await evaluate('typeof globalThis.noteDeletionSentinel'),'undefined'); - check('Actual keyboard adoption distinguishes empty note and explicit missing-note tombstone; no unchecked effect; original scientific text remains selectable and inert'); - fs.writeFileSync(note,restored);await inspectFile('notes/scientist.md');assert.equal(await evaluate('document.getElementById("project-working-revision").value'),'2');assert.equal(await evaluate('document.getElementById("project-working-sha").value'),hash(restored)); - assert.equal(await evaluate('document.getElementById("project-working-delete-fields").disabled'),true); - await activate('#project-working-adopt-form button[type="submit"]');await settled();assert.equal(await evaluate('document.getElementById("project-working-text").value'),displayed(restored)); - fs.unlinkSync(note);await inspectFile('notes/scientist.md');await focus('#project-working-delete-confirm');await key(' ','Space');await activate('#project-working-delete');await settled(); - assert.match(await evaluate('document.getElementById("project-working-summary").textContent'),/revision 4.*deletion/); - await capture(390);await capture(1440); - const sourceBefore=snapshot(source);await fill('#project-save-as-directory','independent');await fill('#project-save-as-name','Independent deleted note Ω');await activate('#project-files-save-as');await settled(); - const forkState=await state();assert.notEqual(forkState.project.project_id,originalProject);assert.deepEqual(snapshot(source),sourceBefore); - const fork=path.join(external,'independent');assert.ok(!fs.existsSync(path.join(fork,'notes/scientist.md')));await inspectFile('notes/scientist.md');assert.match(await evaluate('document.getElementById("project-working-summary").textContent'),/revision 4.*deletion/); - check('Actual named restore appends positive revision3; second explicit deletion appends revision4; independent Save As retains absence without rewriting source'); - await activate('#project-files-close');await until(async()=>(await state()).state==='no_project_open','close before cold copy');await stop(server); - const coldRoot=path.join(temporary,'cold-external');fs.mkdirSync(coldRoot);const clone=path.join(coldRoot,'clone'),canonical=snapshot(fork); - const git=(...args)=>execFileSync('git',args,{env:gitEnv,stdio:['ignore','pipe','pipe']});git('init','-q','--template=',fork);git('-C',fork,'add','.');git('-C',fork,'-c','user.name=Disposable note QA','-c','user.email=qa@example.invalid','-c','commit.gpgsign=false','-c','core.hooksPath=/dev/null','commit','-qm','Retained explicit note deletion');git('-c','core.hooksPath=/dev/null','clone','-q','--no-hardlinks','--template=',fork,clone);if(fs.existsSync(path.join(fork,'artifacts')))fs.cpSync(path.join(fork,'artifacts'),path.join(clone,'artifacts'),{recursive:true});assert.deepEqual(snapshot(clone),canonical);fs.rmSync(external,{recursive:true}); - await start(path.join(temporary,'cold-control'),coldRoot,coldDsn);await navigate();await fill('#project-files-directory','clone');await activate('#project-files-open');await settled();assert.deepEqual((await state()).project,forkState.project); - await inspectFile('notes/scientist.md');assert.match(await evaluate('document.getElementById("project-working-summary").textContent'),/revision 4.*deletion/);assert.ok(!fs.existsSync(path.join(clone,'notes/scientist.md'))); - await activate('#project-working-history');await settled();assert.equal(await evaluate('document.querySelectorAll("#project-working-history-list button").length'),4); - await activate('#project-working-history-list button');await settled();assert.equal(await evaluate('document.getElementById("project-working-text").value'),displayed(first)); - await activate('#project-working-history-list li:nth-child(3) button');await settled();assert.equal(await evaluate('document.getElementById("project-working-text").value'),displayed(restored)); - await inspectFile('notes/empty.md');assert.match(await evaluate('document.getElementById("project-working-summary").textContent'),/empty file/); - await capture(390);await capture(1440);assert.deepEqual(snapshot(clone),canonical);assert.equal(await evaluate('typeof globalThis.noteDeletionSentinel'),'undefined');assert.deepEqual(errors,[]);assert.deepEqual(httpErrors,[]);verifySource();assert.equal(hash(fs.readFileSync(__filename)),testSha); - check('Cold Git clone on separate database role denied source CONNECT retains exact fork/tombstone/four revisions after source removal; 390/1440 keyboard UI stays responsive and inert'); - fs.writeFileSync(path.join(report,'receipt.json'),JSON.stringify({status:'pass',checks,material,test_sha256:testSha,isolation,bounds,project:forkState.project,source_project:originalProject,browser_runtime_errors:errors,http_errors:httpErrors,canonical_sha256:canonical,fixture:'Actual named keyboard note adoption/deletion/restore; local Git clone; cold distinct DB denied source CONNECT; no runtime/preflight/Run'},null,2)+'\n');console.log('Report '+path.join(report,'receipt.json')); -})().catch(async error=>{ - fs.writeFileSync(path.join(report,'failure-receipt.json'),JSON.stringify({status:'failed',error:error.message,checks,material,test_sha256:testSha,isolation,bounds,browser_runtime_errors:errors,http_errors:httpErrors},null,2)+'\n');console.error(error);console.error('Server:',serverErrors);if(evaluate)try{console.error('UI:',await evaluate('document.body.innerText'));}catch(_){}process.exitCode=1; -}).finally(async()=>{ - session?.close();socket?.close();for(const child of children.reverse())await stop(child); - for(const {control,dsn} of catalogs)try{execFileSync('python3',['-c',"import json,pathlib,os,psycopg;from psycopg import sql;root=pathlib.Path(os.environ['QA_CONTROL']);c=psycopg.connect(os.environ['TULDOK_DATABASE_URL'],autocommit=True);[(c.execute(sql.SQL('DROP SCHEMA IF EXISTS {} CASCADE').format(sql.Identifier('projection_'+v['projection_id'] if v['version']==2 else 'catalog_'+v['dataset_id'])))) for p in root.rglob('.tuldok.json') for v in [json.loads(p.read_text())]];c.close()"],{cwd:root,env:{...process.env,TULDOK_DATABASE_URL:dsn,QA_CONTROL:control},stdio:['ignore','pipe','pipe']});}catch(error){console.error('Owned cleanup failed:',error.message);process.exitCode=1;} - process.env.TULDOK_DATABASE_URL=sourceDsn;fs.rmSync(temporary,{recursive:true,force:true}); -}); diff --git a/tests/browser_project_files.cjs b/tests/browser_project_files.cjs deleted file mode 100644 index 19e854a1..00000000 --- a/tests/browser_project_files.cjs +++ /dev/null @@ -1,187 +0,0 @@ -'use strict'; -// Real browser authoring, keyboard actions and a cold process on another database. -// Inputs and runtime roots are disposable; project scripts are inert sentinels. -const assert=require('node:assert/strict'); -const fs=require('node:fs'),os=require('node:os'),path=require('node:path'),crypto=require('node:crypto'); -const {spawn,execFileSync}=require('node:child_process'); -const {once}=require('node:events'); -const {authenticatedFixture}=require('./auth_helpers.cjs'); -const {waitForDebugger}=require('./browser_startup.cjs'); -const {cdpSession}=require('./browser_cdp_session.cjs'); -const {qaDirectory,screenshotOptions}=require('./qa_artifacts.cjs'); -const root=path.resolve(__dirname,'..'); -assert.ok(process.env.TULDOK_DATABASE_URL,'Use a disposable PostgreSQL TULDOK_DATABASE_URL'); -assert.ok(process.env.TULDOK_PROJECT_FILES_COLD_DATABASE_URL,'Cold proof requires a separate disposable database URL'); -const sourceDsn=process.env.TULDOK_DATABASE_URL,coldDsn=process.env.TULDOK_PROJECT_FILES_COLD_DATABASE_URL; -const gitOptions={env:{...process.env,GIT_CONFIG_NOSYSTEM:'1',GIT_CONFIG_GLOBAL:'/dev/null',GIT_TERMINAL_PROMPT:'0'}}; -assert.notEqual(sourceDsn,coldDsn,'Source and cold connection configuration must differ'); -const temporary=fs.mkdtempSync(path.join(os.tmpdir(),'tuldok-project-files-browser-')); -const report=qaDirectory(root,'project-files'); -const external=path.join(temporary,'external');fs.mkdirSync(external); -const sourceControl=path.join(temporary,'control'),coldControl=path.join(temporary,'cold-control'); -const TEXT='Café 山 🧪 — browser-authored source\nThe scientist’s unique rationale stays exact.\n'; -const name='Browser source 山',label='positive 山',corpusNote='Earlier corpus note café 山 — preserve this scientific rationale.'; -const checks=[],errors=[],httpErrors=[],children=[],catalogs=[]; -const observationHeaders=JSON.parse(execFileSync('python3',['-c',"import json,agent_api;print(json.dumps({name:agent_api.selected_header('project_files.'+name) for name in ('status','query','get')}))"],{cwd:root,encoding:'utf8'})); -const material={head:execFileSync('git',['rev-parse','HEAD'],{cwd:root,encoding:'utf8',...gitOptions}).trim(),files:Object.fromEntries(['app.py','metadata.py','access.py','workbench.py','agent_api.py','project_store.py','project_text.py','project_workspace.py','static/project-files.html','static/project-files.js','static/project-files.css','tests/browser_project_files.cjs'].map(file=>[file,fs.existsSync(path.join(root,file))?crypto.createHash('sha256').update(fs.readFileSync(path.join(root,file))).digest('hex'):null]))}; -let socket,session,server,serverErrors='',origin,fixtureAuth,send,evaluate; -const pause=ms=>new Promise(resolve=>setTimeout(resolve,ms)); -async function until(fn,message='Timed out'){ - for(let i=0;i<200;i++){const value=await fn();if(value)return value;await pause(100);} - throw Error(message); -} -function launch(command,args,options={}){const child=spawn(command,args,options);children.push(child);return child;} -function snapshot(directory){ - const values={}; - function walk(current){for(const entry of fs.readdirSync(current,{withFileTypes:true})){ - if(['.git','.tuldok-local'].includes(entry.name))continue; - const next=path.join(current,entry.name); - if(entry.isDirectory())walk(next); - else if(entry.isFile())values[path.relative(directory,next)]=crypto.createHash('sha256').update(fs.readFileSync(next)).digest('hex'); - else throw Error('Unexpected project special file '+entry.name); - }}walk(directory);return values; -} -async function stop(child){ - if(!child||child.exitCode!==null||child.signalCode!==null)return; - const exited=once(child,'exit');child.kill('SIGTERM');await exited; -} -async function start(control,configuredRoot,dsn){ - process.env.TULDOK_DATABASE_URL=dsn; - serverErrors=''; - server=launch('python3',['-u','app.py','--port','0','--data',control,'--project-files-root','fixture='+configuredRoot],{cwd:root,stdio:['ignore','pipe','pipe'],env:{...process.env,TULDOK_DATABASE_URL:dsn}}); - let output='';server.stdout.on('data',chunk=>output+=chunk);server.stderr.on('data',chunk=>serverErrors+=chunk); - const port=await until(()=>{if(server.exitCode!==null)throw Error('Server exited: '+serverErrors);return output.match(/127\.0\.0\.1:(\d+)/)?.[1];},'Project-files server readiness: '+serverErrors); - origin='http://127.0.0.1:'+port; - catalogs.push({control,dsn}); - fixtureAuth=authenticatedFixture(); - await fixtureAuth.register(origin,control,root); - return origin; -} -async function jsonApi(relative){ - const route=relative.split('?')[0],operation=route.endsWith('/records')?'query':route.includes('/records/')?'get':'status'; - const response=await fixtureAuth.fetch(origin+relative,{headers:{'Tuldok-Operation-Contract':observationHeaders[operation]}}); - const value=await response.json();assert.equal(response.status,200,JSON.stringify(value));return value; -} -async function state(){return jsonApi('/api/workspace/project-files');} -async function detail(recordId){ - const current=await state(); - return jsonApi('/api/workspace/project-files/records/'+recordId+'?'+new URLSearchParams({binding:current.binding,checkpoint:current.project.checkpoint,history_limit:'4'})); -} -async function key(key,code=key,modifiers=0){ - for(const type of ['keyDown','keyUp'])await send('Input.dispatchKeyEvent',{type,key,code,modifiers,windowsVirtualKeyCode:{Enter:13,Tab:9,Escape:27,a:65}[key]||0,...(type==='keyDown'&&key==='Enter'?{text:'\r',unmodifiedText:'\r'}:{})}); -} -async function focus(selector){ - await until(()=>evaluate(`(()=>{const e=document.querySelector(${JSON.stringify(selector)});if(!e||e.disabled||!e.getClientRects().length)return false;e.scrollIntoView({block:'center'});e.focus();return document.activeElement===e;})()`),'Focusable control '+selector); -} -async function fill(selector,value){await focus(selector);await key('a','KeyA',2);await send('Input.insertText',{text:value});} -async function activate(selector){await focus(selector);await key('Enter');} -async function choose(selector,value){ - await focus(selector); - await evaluate(`(()=>{const e=document.querySelector(${JSON.stringify(selector)});if(!Array.from(e.options).some(o=>o.value===${JSON.stringify(value)}))throw Error('Missing rendered option');e.value=${JSON.stringify(value)};e.dispatchEvent(new Event('change',{bubbles:true}));})()`); -} -async function ready(){await until(()=>evaluate('!!document.querySelector("#project-files-root option")&&!document.getElementById("project-files-new").disabled'),'Project files UI ready');} -async function navigate(){await fixtureAuth.browser(send,origin);await send('Page.navigate',{url:origin+'/project-files'});await ready();} -async function capture(filename,width,selector='#record-heading'){ - await send('Emulation.setDeviceMetricsOverride',{width,height:950,deviceScaleFactor:1,mobile:false}); - await evaluate(`document.querySelector(${JSON.stringify(selector)}).scrollIntoView({block:'start'})`); - await pause(80); - assert.ok(await evaluate('document.documentElement.scrollWidth<=innerWidth+1'),'No horizontal overflow at '+width); - fs.writeFileSync(path.join(report,filename),Buffer.from((await send('Page.captureScreenshot',screenshotOptions)).data,'base64')); -} -function check(message){checks.push(message);console.log('PASS '+message);} -(async()=>{ - // Cold runtime role must genuinely lack CONNECT to the source database. - const isolation=JSON.parse(execFileSync('python3',['-c', - "import json,os,psycopg;from psycopg.conninfo import conninfo_to_dict;source=conninfo_to_dict(os.environ['TULDOK_DATABASE_URL']);cold=conninfo_to_dict(os.environ['TULDOK_PROJECT_FILES_COLD_DATABASE_URL']);assert source['dbname']!=cold['dbname'];c=psycopg.connect(os.environ['TULDOK_PROJECT_FILES_COLD_DATABASE_URL']);row=c.execute('SELECT current_database(), current_user, has_database_privilege(current_user,%s,%s)',(source['dbname'],'CONNECT')).fetchone();assert not row[2], 'Cold role must not connect to source database';print(json.dumps({'database':row[0],'role':row[1],'source_connect':row[2]}));c.close()" - ],{cwd:root,encoding:'utf8'})); - await start(sourceControl,external,sourceDsn); - const browser=launch(process.env.BROWSER||'/usr/bin/chromium',['--headless','--no-sandbox','--disable-gpu','--no-first-run','--no-default-browser-check','--remote-debugging-port=0','--window-size=1440,950','--user-data-dir='+path.join(temporary,'browser'),'about:blank'],{stdio:'ignore',env:{...process.env,XDG_CONFIG_HOME:temporary,XDG_CACHE_HOME:temporary}}); - const port=await waitForDebugger(browser,path.join(temporary,'browser','DevToolsActivePort')); - const tabs=await(await fetch('http://127.0.0.1:'+port+'/json')).json(); - const target=tabs.find(tab=>tab.type==='page'&&tab.url==='about:blank');assert.ok(target); - socket=new WebSocket(target.webSocketDebuggerUrl);await once(socket,'open'); - session=cdpSession(socket,{onEvent:event=>{ - if(event.method==='Runtime.exceptionThrown')errors.push(event.params.exceptionDetails); - if(event.method==='Network.responseReceived'&&event.params.response.status>=400)httpErrors.push({url:event.params.response.url,status:event.params.response.status}); - }});send=session.send; - evaluate=async expression=>{const value=await send('Runtime.evaluate',{expression,awaitPromise:true,returnByValue:true});if(value.exceptionDetails)throw Error(JSON.stringify(value.exceptionDetails));return value.result.value;}; - await send('Page.enable');await send('Runtime.enable');await send('Network.enable'); - await navigate(); - const initial=await state();assert.equal(initial.state,'no_project_open'); - await choose('#project-files-root','fixture');await fill('#project-files-directory','alpha');await fill('#project-files-name','Browser café 🧪'); - await activate('#project-files-new'); - await until(async()=>((await state()).state==='open'),'New via keyboard opens project'); - await until(()=>evaluate('!document.getElementById("import-text").disabled')); - await fill('#text-name',name);await fill('#text-content',TEXT);await fill('#text-groups','source-fixture');await fill('#text-rights','Owned synthetic browser input'); - await activate('#import-text'); - await until(()=>evaluate('document.querySelectorAll("#records-list [data-record-id]").length===1'),'Import appears in actual UI'); - const recordId=await evaluate('document.querySelector("#records-list [data-record-id]").dataset.recordId'); - await activate('#records-list [data-record-id]'); - await until(()=>evaluate('document.getElementById("record-text").value==='+JSON.stringify(TEXT)),'Imported source shown exact'); - await choose('#annotation-task','text_corpus');await fill('#annotation-value',corpusNote);await choose('#record-review','human_reviewed'); - await activate('#annotation-save'); - await until(()=>evaluate('document.getElementById("record-summary").textContent.includes("Revision 2")&&!document.getElementById("annotation-save").disabled'),'Corpus note acknowledged in actual editor'); - await choose('#annotation-task','text_classification'); - await fill('#annotation-value',label);await fill('#annotation-groups','source-fixture,review-fixture');await choose('#record-review','human_reviewed'); - await activate('#annotation-save'); - await until(()=>evaluate('document.getElementById("record-summary").textContent.includes("Revision 3")&&!document.getElementById("annotation-save").disabled'),'Annotation acknowledged in actual editor'); - const expected=await detail(recordId); - assert.equal(expected.record.text,TEXT);assert.equal(expected.record.name,name);assert.equal(expected.record.review,'human_reviewed');assert.equal(expected.history.length,3);assert.ok(expected.history.some(item=>item.annotation?.note===corpusNote)); - await activate('#record-history-more'); - await until(()=>evaluate('document.getElementById("record-history").textContent.includes('+JSON.stringify(corpusNote)+')'),'Prior corpus note is inspectable through older-history UI'); - check('Keyboard New, Unicode import, historical corpus note and human-reviewed classification commit through real UI controls'); - await activate('#project-files-save'); - await until(()=>evaluate('!document.getElementById("project-files-save").disabled')); - const beforeClose=await state(); - await capture('authored-1440.jpg',1440);await capture('authored-390.jpg',390); - await activate('#project-files-close');await until(async()=>((await state()).state==='no_project_open')); - await until(()=>evaluate('document.querySelectorAll("#records-list [data-record-id]").length===0'),'Close clears record panel'); - await stop(server); - const source=path.join(external,'alpha');fs.mkdirSync(path.join(source,'scripts'),{recursive:true}); - fs.writeFileSync(path.join(source,'scripts','must-not-run.py'),"from pathlib import Path\nPath(__file__).with_name('EXECUTED').write_text('must never run')\n"); - const before=snapshot(source); - const coldExternal=path.join(temporary,'cold-external');fs.mkdirSync(coldExternal); - const clone=path.join(coldExternal,'clone'); - // Use an actual Git commit/clone; canonical source files are plain text. - execFileSync('git',['init','-q','--template=',source],gitOptions); - execFileSync('git',['-C',source,'add','.'],gitOptions); - execFileSync('git',['-C',source,'-c','user.name=Disposable Project QA','-c','user.email=project-qa@example.invalid','-c','commit.gpgsign=false','-c','core.hooksPath=/dev/null','commit','-qm','Synthetic external project fixture'],gitOptions); - execFileSync('git',['-c','core.hooksPath=/dev/null','clone','-q','--no-hardlinks','--template=',source,clone],gitOptions); - assert.deepEqual(snapshot(clone),before,'Git clone retained exact canonical authored bytes'); - await start(coldControl,coldExternal,coldDsn); - await navigate(); - assert.equal((await state()).state,'no_project_open'); - await choose('#project-files-root','fixture');await fill('#project-files-directory','clone');await activate('#project-files-open'); - await until(async()=>((await state()).state==='open'),'Cold process Open through keyboard'); - await until(()=>evaluate('document.querySelectorAll("#records-list [data-record-id]").length===1')); - await activate('#records-list [data-record-id]'); - await until(()=>evaluate('document.getElementById("record-text").value==='+JSON.stringify(TEXT))); - await until(()=>evaluate('document.getElementById("annotation-value").value==='+JSON.stringify(label))); - const cold=await state(),actual=await detail(recordId); - assert.deepEqual(cold.project,beforeClose.project); - assert.deepEqual(actual.record,expected.record);assert.deepEqual(actual.history,expected.history); - assert.equal(await evaluate('document.getElementById("record-review").value'),'human_reviewed'); - await activate('#project-files-save');await until(()=>evaluate('!document.getElementById("project-files-save").disabled')); - assert.deepEqual(snapshot(clone),before,'Cold no-op Save has no semantic or byte changes'); - assert.ok(!fs.existsSync(path.join(clone,'scripts','EXECUTED'))); - check('Fresh application process and distinct PostgreSQL role/database reconstruct exact IDs, text, review and history from Git clone; source DB access denied'); - await activate('#record-history-more'); - await until(()=>evaluate('document.getElementById("record-history").textContent.includes('+JSON.stringify(corpusNote)+')'),'Cold Open retained corpus note is inspectable through older-history UI'); - await capture('cold-open-1440.jpg',1440);await capture('cold-open-390.jpg',390);await capture('cold-history-390.jpg',390,'#record-history'); - await activate('#project-files-close');await until(async()=>((await state()).state==='no_project_open')); - assert.deepEqual(errors,[],'No browser runtime errors');assert.deepEqual(httpErrors,[],'No failed browser requests'); - for(const [file,digest] of Object.entries(material.files))assert.equal(crypto.createHash('sha256').update(fs.readFileSync(path.join(root,file))).digest('hex'),digest,'Material source changed during campaign: '+file); - fs.writeFileSync(path.join(report,'receipt.json'),JSON.stringify({status:'pass',checks,isolation,material,project:beforeClose.project,record_id:recordId,history_count:expected.history.length,canonical_sha256:before,screenshots:['authored-1440.jpg','authored-390.jpg','cold-open-1440.jpg','cold-open-390.jpg','cold-history-390.jpg'],browser_runtime_errors:errors,http_errors:httpErrors,fixture:'Synthetic project only; no lab/scientific execution claim'},null,2)+'\n'); - console.log('Report '+path.join(report,'receipt.json')); -})().catch(async error=>{console.error(error);console.error('Server diagnostics:',serverErrors);console.error('Browser runtime errors:',JSON.stringify(errors));console.error('HTTP errors:',JSON.stringify(httpErrors));if(evaluate)try{console.error('UI diagnostics:',await evaluate('document.body.innerText'));}catch(diagnostic){console.error('UI diagnostics unavailable:',diagnostic.message);}process.exitCode=1;}).finally(async()=>{ - session?.close();socket?.close(); - for(const child of children.reverse())await stop(child); - // Drop only UUID catalog schemas whose manifests live under this owned root. - for(const {control,dsn} of catalogs){ - try{execFileSync('python3',['-c', - "import json,pathlib,os,psycopg;from psycopg import sql;root=pathlib.Path(os.environ['QA_CONTROL']);c=psycopg.connect(os.environ['TULDOK_DATABASE_URL'],autocommit=True);[(c.execute(sql.SQL('DROP SCHEMA IF EXISTS {} CASCADE').format(sql.Identifier(('projection_'+v['projection_id']) if v['version']==2 else ('catalog_'+v['dataset_id']))))) for p in root.rglob('.tuldok.json') for v in [json.loads(p.read_text())]];c.close()" - ],{cwd:root,env:{...process.env,TULDOK_DATABASE_URL:dsn,QA_CONTROL:control},stdio:['ignore','pipe','pipe']});}catch(error){console.error('Owned schema cleanup failed:',error.message);process.exitCode=1;} - } - process.env.TULDOK_DATABASE_URL=sourceDsn; - fs.rmSync(temporary,{recursive:true,force:true}); -}); diff --git a/tests/browser_project_files_m2.cjs b/tests/browser_project_files_m2.cjs deleted file mode 100644 index 39b9b3d7..00000000 --- a/tests/browser_project_files_m2.cjs +++ /dev/null @@ -1,273 +0,0 @@ -'use strict'; -// Real browser authoring, keyboard actions and a cold process on another database. -// Inputs and runtime roots are disposable; project scripts are inert sentinels. -const assert=require('node:assert/strict'); -const fs=require('node:fs'),os=require('node:os'),path=require('node:path'),crypto=require('node:crypto'); -const {spawn,execFileSync}=require('node:child_process'); -const {once}=require('node:events'); -const {authenticatedFixture}=require('./auth_helpers.cjs'); -const {waitForDebugger}=require('./browser_startup.cjs'); -const {cdpSession}=require('./browser_cdp_session.cjs'); -const {qaDirectory,screenshotOptions}=require('./qa_artifacts.cjs'); -const root=path.resolve(__dirname,'..'); -assert.ok(process.env.TULDOK_DATABASE_URL,'Use a disposable PostgreSQL TULDOK_DATABASE_URL'); -assert.ok(process.env.TULDOK_PROJECT_FILES_COLD_DATABASE_URL,'Cold proof requires a separate disposable database URL'); -const sourceDsn=process.env.TULDOK_DATABASE_URL,coldDsn=process.env.TULDOK_PROJECT_FILES_COLD_DATABASE_URL; -const gitOptions={env:{...process.env,GIT_CONFIG_NOSYSTEM:'1',GIT_CONFIG_GLOBAL:'/dev/null',GIT_TERMINAL_PROMPT:'0'}}; -assert.notEqual(sourceDsn,coldDsn,'Source and cold connection configuration must differ'); -const temporary=fs.mkdtempSync(path.join(os.tmpdir(),'tuldok-project-files-browser-')); -const report=qaDirectory(root,'project-files-m2'); -const external=path.join(temporary,'external');fs.mkdirSync(external); -const sourceControl=path.join(temporary,'control'),coldControl=path.join(temporary,'cold-control'); -const TEXT='Café 山 🧪 — browser-authored source\nThe scientist’s unique rationale stays exact.\n'; -const name='Browser source 山',label='positive 山',corpusNote='Earlier corpus note café 山 — preserve this scientific rationale.'; -const checks=[],errors=[],httpErrors=[],children=[],catalogs=[],responsiveFailures=[]; -const observationHeaders=JSON.parse(execFileSync('python3',['-c',"import json,agent_api;print(json.dumps({name:agent_api.selected_header('project_files.'+name) for name in ('status','query','get')}))"],{cwd:root,encoding:'utf8'})); -const material={head:execFileSync('git',['rev-parse','HEAD'],{cwd:root,encoding:'utf8',...gitOptions}).trim(),files:Object.fromEntries(['app.py','metadata.py','access.py','workbench.py','agent_api.py','project_store.py','project_text.py','project_workspace.py','static/project-files.html','static/project-files.js','static/project-files.css','tests/browser_project_files_m2.cjs'].map(file=>[file,fs.existsSync(path.join(root,file))?crypto.createHash('sha256').update(fs.readFileSync(path.join(root,file))).digest('hex'):null]))}; -const freeze=JSON.parse(fs.readFileSync(process.env.TULDOK_M2_FREEZE_MANIFEST||'/workspace/scratch/tuldok-save-load-qa/m2-product-freeze.json','utf8')); -material.files=freeze.files; -for(const [file,sha] of Object.entries(material.files))assert.equal(crypto.createHash('sha256').update(fs.readFileSync(path.join(root,file))).digest('hex'),sha,'Freeze mismatch '+file); -const testMaterial=Object.fromEntries(['tests/browser_project_files_m2.cjs','tests/test_project_files_m2_http.py'].map(file=>[file,crypto.createHash('sha256').update(fs.readFileSync(path.join(root,file))).digest('hex')])); -let socket,session,server,serverErrors='',origin,fixtureAuth,send,evaluate; -const pause=ms=>new Promise(resolve=>setTimeout(resolve,ms)); -async function until(fn,message='Timed out'){ - for(let i=0;i<200;i++){const value=await fn();if(value)return value;await pause(100);} - throw Error(message); -} -function launch(command,args,options={}){const child=spawn(command,args,options);children.push(child);return child;} -function snapshot(directory){ - const values={}; - function walk(current){for(const entry of fs.readdirSync(current,{withFileTypes:true})){ - if(['.git','.tuldok-local'].includes(entry.name))continue; - const next=path.join(current,entry.name); - if(entry.isDirectory())walk(next); - else if(entry.isFile())values[path.relative(directory,next)]=crypto.createHash('sha256').update(fs.readFileSync(next)).digest('hex'); - else throw Error('Unexpected project special file '+entry.name); - }}walk(directory);return values; -} -async function stop(child){ - if(!child||child.exitCode!==null||child.signalCode!==null)return; - const exited=once(child,'exit');child.kill('SIGTERM');await exited; -} -async function start(control,configuredRoot,dsn){ - process.env.TULDOK_DATABASE_URL=dsn; - serverErrors=''; - server=launch('python3',['-u','app.py','--port','0','--data',control,'--project-files-root','fixture='+configuredRoot],{cwd:root,stdio:['ignore','pipe','pipe'],env:{...process.env,TULDOK_DATABASE_URL:dsn}}); - let output='';server.stdout.on('data',chunk=>output+=chunk);server.stderr.on('data',chunk=>serverErrors+=chunk); - const port=await until(()=>{if(server.exitCode!==null)throw Error('Server exited: '+serverErrors);return output.match(/127\.0\.0\.1:(\d+)/)?.[1];},'Project-files server readiness: '+serverErrors); - origin='http://127.0.0.1:'+port; - catalogs.push({control,dsn}); - fixtureAuth=authenticatedFixture(); - await fixtureAuth.register(origin,control,root); - return origin; -} -async function jsonApi(relative){ - const route=relative.split('?')[0],operation=route.endsWith('/records')?'query':route.includes('/records/')?'get':'status'; - const response=await fixtureAuth.fetch(origin+relative,{headers:{'Tuldok-Operation-Contract':observationHeaders[operation]}}); - const value=await response.json();assert.equal(response.status,200,JSON.stringify(value));return value; -} -async function state(){return jsonApi('/api/workspace/project-files');} -async function detail(recordId){ - const current=await state(); - return jsonApi('/api/workspace/project-files/records/'+recordId+'?'+new URLSearchParams({binding:current.binding,checkpoint:current.project.checkpoint,history_limit:'4'})); -} -async function key(key,code=key,modifiers=0){ - for(const type of ['keyDown','keyUp'])await send('Input.dispatchKeyEvent',{type,key,code,modifiers,windowsVirtualKeyCode:{Enter:13,Tab:9,Escape:27,a:65}[key]||0,...(type==='keyDown'&&key==='Enter'?{text:'\r',unmodifiedText:'\r'}:{})}); -} -async function focus(selector){ - await until(()=>evaluate(`(()=>{const e=document.querySelector(${JSON.stringify(selector)});if(!e||e.disabled||!e.getClientRects().length)return false;e.scrollIntoView({block:'center'});e.focus();return document.activeElement===e;})()`),'Focusable control '+selector); -} -async function fill(selector,value){await focus(selector);await key('a','KeyA',2);await send('Input.insertText',{text:value});} -async function activate(selector){await focus(selector);await key('Enter');} -async function choose(selector,value){ - await focus(selector); - await evaluate(`(()=>{const e=document.querySelector(${JSON.stringify(selector)});if(!Array.from(e.options).some(o=>o.value===${JSON.stringify(value)}))throw Error('Missing rendered option');e.value=${JSON.stringify(value)};e.dispatchEvent(new Event('change',{bubbles:true}));})()`); -} -async function ready(){await until(()=>evaluate('!!document.querySelector("#project-files-root option")&&!document.getElementById("project-files-new").disabled'),'Project files UI ready');} -async function navigate(){await fixtureAuth.browser(send,origin);await send('Page.navigate',{url:origin+'/project-files'});await ready();} -async function capture(filename,width,selector='#record-heading'){ - await send('Emulation.setDeviceMetricsOverride',{width,height:950,deviceScaleFactor:1,mobile:false}); - await evaluate(`document.querySelector(${JSON.stringify(selector)}).scrollIntoView({block:'start'})`); - await evaluate('new Promise(resolve=>requestAnimationFrame(()=>requestAnimationFrame(resolve)))'); - const bounds=await evaluate(`(()=>({viewport:innerWidth,width:document.documentElement.scrollWidth,clientWidth:document.documentElement.clientWidth,selectedValues:['project-scientific-reference','project-explore-kind','project-data-kind','project-files-root'].map(id=>({id,value:document.getElementById(id).value,text:document.getElementById(id).selectedOptions?.[0]?.textContent})),fieldsets:Array.from(document.querySelectorAll('fieldset')).filter(e=>e.getClientRects().length).map(e=>({id:e.id,width:Math.round(e.getBoundingClientRect().width),right:Math.round(e.getBoundingClientRect().right),minWidth:getComputedStyle(e).minWidth})),offenders:Array.from(document.querySelectorAll('body *')).filter(e=>e.getClientRects().length&&e.getBoundingClientRect().right>innerWidth+1).map(e=>({tag:e.tagName,id:e.id,className:e.className,width:Math.round(e.getBoundingClientRect().width),right:Math.round(e.getBoundingClientRect().right),scrollWidth:e.scrollWidth,clientWidth:e.clientWidth,minWidth:getComputedStyle(e).minWidth,text:e.textContent.slice(0,100)})).slice(-25)}))()`); - fs.writeFileSync(path.join(report,'bounds-'+width+'.json'),JSON.stringify(bounds,null,2)+'\n'); - fs.writeFileSync(path.join(report,filename),Buffer.from((await send('Page.captureScreenshot',screenshotOptions)).data,'base64')); - if(bounds.width>bounds.viewport+1){responsiveFailures.push({width,filename,bounds});console.error('RESPONSIVE_FAILURE '+JSON.stringify({width,viewport:bounds.viewport,scrollWidth:bounds.width,clientWidth:bounds.clientWidth,report:path.join(report,'bounds-'+width+'.json')}));} -} -function check(message){checks.push(message);console.log('PASS '+message);} - -const routes=JSON.parse(execFileSync('python3',['-c',"import json,agent_api;names=tuple(n.split('.')[1] for n in agent_api.PROJECT_FILES_M2);print(json.dumps({n:{**{k:agent_api.operation('project_files.'+n)[k] for k in ('path','method','query','side_effects')},'header':agent_api.selected_header('project_files.'+n)} for n in names}))"],{cwd:root,encoding:'utf8'})); -async function observe(action,fields={}){ - const current=await state(),route=routes[action],args={binding:current.binding,...(route.side_effects?{expected_checkpoint:current.project.checkpoint,request_key:crypto.randomUUID().replaceAll('-','')}:{checkpoint:current.project.checkpoint}),...fields}; - let target=route.path;for(const [key,value] of Object.entries(args))target=target.replace('{'+key+'}',encodeURIComponent(value)); - const query=new URLSearchParams(Object.entries(args).filter(([key])=>route.query.includes(key))); - if(query.size)target+='?'+query; - const body=Object.fromEntries(Object.entries(args).filter(([key])=>!route.query.includes(key)&&!route.path.includes('{'+key+'}'))); - const response=await fixtureAuth.fetch(origin+target,{method:route.method,headers:{'Content-Type':'application/json','Tuldok-Operation-Contract':route.header},...(route.method==='POST'?{body:JSON.stringify(body)}:{})}); - const envelope=await response.json();assert.equal(response.status,200,JSON.stringify(envelope));return envelope.value; -} -async function settled(){await until(()=>evaluate('!document.getElementById("project-files-save").disabled&&!document.getElementById("project-files-dirty").textContent.includes("unsent")'),'UI acknowledges saved operation');} -async function explore(kind,contains){ - await choose('#project-explore-kind',kind);await activate('#project-explore-load');await settled(); - await until(()=>evaluate(`Array.from(document.querySelectorAll('#project-explore-list button')).some(e=>e.textContent.includes(${JSON.stringify(contains)}))`),'Rendered saved record '+contains); - await evaluate(`(()=>{for(const e of document.querySelectorAll('#project-explore-list button'))if(e.textContent.includes(${JSON.stringify(contains)})){e.dataset.qaSelected='yes';break;}})()`); - await activate('#project-explore-list button[data-qa-selected="yes"]');await settled(); -} -async function fileInput(selector,file){ - const document=await send('DOM.getDocument',{depth:1});const {nodeId}=await send('DOM.querySelector',{nodeId:document.root.nodeId,selector}); - assert.ok(nodeId,'Actual native file input exists');await send('DOM.setFileInputFiles',{nodeId,files:[file]}); -} -(async()=>{ - // Cold runtime role must genuinely lack CONNECT to the source database. - const isolation=JSON.parse(execFileSync('python3',['-c', - "import json,os,psycopg;from psycopg.conninfo import conninfo_to_dict;source=conninfo_to_dict(os.environ['TULDOK_DATABASE_URL']);cold=conninfo_to_dict(os.environ['TULDOK_PROJECT_FILES_COLD_DATABASE_URL']);assert source['dbname']!=cold['dbname'];c=psycopg.connect(os.environ['TULDOK_PROJECT_FILES_COLD_DATABASE_URL']);row=c.execute('SELECT current_database(), current_user, has_database_privilege(current_user,%s,%s)',(source['dbname'],'CONNECT')).fetchone();assert not row[2], 'Cold role must not connect to source database';print(json.dumps({'database':row[0],'role':row[1],'source_connect':row[2]}));c.close()" - ],{cwd:root,encoding:'utf8'})); - await start(sourceControl,external,sourceDsn); - const browser=launch(process.env.BROWSER||'/usr/bin/chromium',['--headless','--no-sandbox','--disable-gpu','--no-first-run','--no-default-browser-check','--remote-debugging-port=0','--window-size=1440,950','--user-data-dir='+path.join(temporary,'browser'),'about:blank'],{stdio:'ignore',env:{...process.env,XDG_CONFIG_HOME:temporary,XDG_CACHE_HOME:temporary}}); - const port=await waitForDebugger(browser,path.join(temporary,'browser','DevToolsActivePort')); - const tabs=await(await fetch('http://127.0.0.1:'+port+'/json')).json(); - const target=tabs.find(tab=>tab.type==='page'&&tab.url==='about:blank');assert.ok(target); - socket=new WebSocket(target.webSocketDebuggerUrl);await once(socket,'open'); - session=cdpSession(socket,{onEvent:event=>{ - if(event.method==='Runtime.exceptionThrown')errors.push(event.params.exceptionDetails); - if(event.method==='Network.responseReceived'&&event.params.response.status>=400)httpErrors.push({url:event.params.response.url,status:event.params.response.status}); - }});send=session.send; - evaluate=async expression=>{const value=await send('Runtime.evaluate',{expression,awaitPromise:true,returnByValue:true});if(value.exceptionDetails)throw Error(JSON.stringify(value.exceptionDetails));return value.result.value;}; - await send('Page.enable');await send('Runtime.enable');await send('Network.enable'); - - execFileSync('python3',['-c',"import pathlib,sys;sys.path.insert(0,'tests');from test_project_files_m2_http import authored_source;from PIL import Image;root=pathlib.Path(sys.argv[1]);authored_source(root);Image.new('RGB',(20,12),'#3355aa').save(root/'image.png','PNG')",external],{cwd:root}); - await navigate(); - await choose('#project-files-root','fixture');await fill('#project-files-directory','alpha');await fill('#project-files-name','Browser M2 authored project 山'); - await activate('#project-files-new');await until(async()=>((await state()).state==='open'));await settled(); - - - if(process.env.TULDOK_M2_RESPONSIVE_ONLY==='1'){ - const imported=await observe('data_import_image',{image:fs.readFileSync(path.join(external,'image.png')).toString('base64'),name:'Cold responsive image café 山',groups:['responsive-image'],rights:'Owned authored pixels'}); - const corrected=await observe('data_rights',{record_id:imported.id,revision:imported.revision,source_revision:imported.source_revision,note:'Exact cold responsive rights café 山'}); - const expected=await observe('data_get',{record_id:imported.id}),expectedHistory=await observe('data_history',{record_id:imported.id,limit:4}); - await activate('#project-files-refresh');await settled();await activate('#project-files-close');await until(async()=>((await state()).state==='no_project_open'));await stop(server); - const source=path.join(external,'alpha'),before=snapshot(source),coldExternal=path.join(temporary,'cold-external');fs.mkdirSync(coldExternal);const clone=path.join(coldExternal,'clone'); - execFileSync('git',['init','-q','--template=',source],gitOptions);execFileSync('git',['-C',source,'add','.'],gitOptions); - execFileSync('git',['-C',source,'-c','user.name=Disposable Responsive QA','-c','user.email=qa@example.invalid','-c','commit.gpgsign=false','-c','core.hooksPath=/dev/null','commit','-qm','Cold history responsive fixture'],gitOptions); - execFileSync('git',['-c','core.hooksPath=/dev/null','clone','-q','--no-hardlinks','--template=',source,clone],gitOptions);fs.cpSync(path.join(source,'artifacts'),path.join(clone,'artifacts'),{recursive:true}); - await start(coldControl,coldExternal,coldDsn);await navigate();await choose('#project-files-root','fixture');await fill('#project-files-directory','clone');await activate('#project-files-open');await until(async()=>((await state()).state==='open'));await settled(); - assert.deepEqual(await observe('data_get',{record_id:imported.id}),expected);assert.deepEqual(await observe('data_history',{record_id:imported.id,limit:4}),expectedHistory); - await choose('#project-data-kind','image');await explore('data_query','Cold responsive image café 山');await activate('#project-detail-history'); - await until(()=>evaluate('document.getElementById("project-detail-history-list").textContent.includes("Exact cold responsive rights café 山")')); - await capture('focused-cold-history-390.jpg',390,'#project-detail-history-list');await capture('focused-cold-history-1440.jpg',1440,'#project-detail-history-list'); - assert.deepEqual(snapshot(clone),before);assert.deepEqual(errors,[]);assert.deepEqual(httpErrors,[]); - for(const [file,digest] of Object.entries(material.files))assert.equal(crypto.createHash('sha256').update(fs.readFileSync(path.join(root,file))).digest('hex'),digest,'Frozen product source changed '+file); - for(const [file,digest] of Object.entries(testMaterial))assert.equal(crypto.createHash('sha256').update(fs.readFileSync(path.join(root,file))).digest('hex'),digest,'Acceptance source changed '+file); - fs.writeFileSync(path.join(report,'receipt.json'),JSON.stringify({status:responsiveFailures.length?'failed':'pass',gate:'focused_cold_history_responsive',prior_functional_and_cold_receipt:'/workspace/scratch/tuldok-save-load-qa/artifacts/project-files-m2/run-DDH5l1/receipt.json',responsive_failures:responsiveFailures,isolation,material,test_material:testMaterial,image_id:imported.id,history_count:expectedHistory.items.length,browser_runtime_errors:errors,http_errors:httpErrors,canonical_sha256:before,fixture:'Real HTTP-authored image/rights history; real Git metadata clone and explicit untracked payload transfer; actual cold UI history'},null,2)+'\n'); - console.log('Focused responsive report '+path.join(report,'receipt.json'));if(responsiveFailures.length)throw Error('Focused cold history responsive overflow remains');return; - } - let imageId,fieldId,studyId,projectId,expectedImage,expectedField,expectedStudy,rights,scienceNote; - if(process.env.TULDOK_M2_RESUME_HTTP==='1'){ - const seedImage=await observe('data_import_image',{image:fs.readFileSync(path.join(external,'image.png')).toString('base64'),name:'Browser image café 山',groups:['browser-image'],rights:'Owned authored synthetic pixels'});imageId=seedImage.id; - rights='Browser corrected exact rights café 山';await observe('data_rights',{record_id:imageId,revision:seedImage.revision,source_revision:seedImage.source_revision,note:rights});expectedImage=await observe('data_get',{record_id:imageId}); - await observe('selection_create',{document:{name:'Browser fixed image revision 山',items:[{id:imageId,revision:expectedImage.revision,source_revision:expectedImage.source_revision}]}}); - await observe('search_create',{document:{name:'Browser entered search café 山',criteria:{q:'café',kind:'image',review:'',sort:'',task:'',label:'',group:'',rights:''}}}); - const unpinned=JSON.parse(fs.readFileSync(path.join(external,'source-project.json'),'utf8'));delete unpinned.data[0].sha256;fs.writeFileSync(path.join(external,'source-project.json'),JSON.stringify(unpinned)); - const registered=await observe('source_register',{root:'fixture',manifest_path:'source-project.json'}),snapshot=Object.fromEntries(['origin_catalog_id','project_id','manifest_sha256'].map(key=>[key,registered[key]])); - const scientificRaw=fs.readFileSync(path.join(external,'observed-fields.zip')); - const field=await observe('data_import_scientific',{snapshot,reference_id:'fields',expected_sha256:crypto.createHash('sha256').update(scientificRaw).digest('hex'),document:{name:'Browser exact field sequence 山',groups:['browser-science'],rights:'Owned authored scientific arrays'}});fieldId=field.id; - scienceNote='Retained browser observation note café 山';await observe('data_annotate',{record_id:fieldId,revision:field.revision,source_revision:field.source_revision,task:field.task,annotation:{note:scienceNote},groups:field.groups,review:'draft'});expectedField=await observe('data_get',{record_id:fieldId}); - const mismatch={...unpinned,id:crypto.randomUUID().replaceAll('-',''),data:[{...unpinned.data[0],sha256:'0'.repeat(64)}]};fs.writeFileSync(path.join(external,'mismatch-project.json'),JSON.stringify(mismatch)); - const study=await observe('study_create',{name:'Browser Study hypothesis 山',limits:{attempt_slots:1,admitted_wall_seconds:60,retained_bytes:1048576,peak_staging_bytes:1048576},policy:{format:'selection_policy_v1',metric_definition_sha256:'b'.repeat(64),checkpoint_rule:'selected',replicate_reduce:'individual',required_capabilities:[],numerical_acceptance:'diagnostic',tie_break:'trial_id'}}); - const revised=await observe('study_save',{study_id:study.id,revision:study.revision,name:'Browser revised Study hypothesis 山',limits:study.limits,policy:study.policy});studyId=revised.id;projectId=(await state()).project.project_id; - expectedStudy=await observe('study',{study_id:studyId,origin_catalog_id:projectId,limit:1}); - await activate('#project-files-refresh');await settled(); - await fill('#project-register-path','mismatch-project.json');await activate('#project-register-form button[type="submit"]');await settled(); - await explore('studies','Browser revised Study hypothesis 山'); - check('Equivalent authored fixture seeded through actual HTTP; prior4UIauthoringgroups retained, CSS and cold remainder are this targeted campaign'); - }else{ - await fill('#project-source-name','Browser image café 山');await fill('#project-source-groups','browser-image');await fill('#project-source-rights','Owned authored synthetic pixels'); - await fileInput('#project-source-file',path.join(external,'image.png'));await activate('#project-source-form button[type="submit"]');await settled(); - const rows=await observe('data_query',{kind:'image',limit:40});assert.equal(rows.items.length,1);imageId=rows.items[0].id; - await choose('#project-data-kind','image');await explore('data_query','Browser image café 山'); - rights='Browser corrected exact rights café 山';await fill('#project-rights-note',rights);await activate('#project-rights-form button[type="submit"]');await settled(); - await explore('data_query','Browser image café 山'); - await fill('#project-selection-name','Browser fixed image revision 山');await activate('#project-selection-form button[type="submit"]');await settled(); - await fill('#project-data-search','café');await fill('#project-search-name','Browser entered search café 山');await activate('#project-search-form button[type="submit"]');await settled(); - await explore('data_query','Browser image café 山');await activate('#project-detail-history'); - await until(()=>evaluate('document.getElementById("project-detail-history-list").textContent.includes('+JSON.stringify(rights)+')'),'Exact corrected rights shown in actual history controls'); - await activate('#project-detail-availability');await settled(); - expectedImage=await observe('data_get',{record_id:imageId});assert.equal(expectedImage.task,'image_detection');assert.equal(expectedImage.provenance.rights_note_correction.note,rights); - check('Actual native image upload, keyboard rights correction, fixed selection, saved search and visible revision history'); - // Explicit owner registration is a separate form from imported historical paths. - const unpinned=JSON.parse(fs.readFileSync(path.join(external,'source-project.json'),'utf8'));delete unpinned.data[0].sha256;fs.writeFileSync(path.join(external,'source-project.json'),JSON.stringify(unpinned)); - await fill('#project-register-path','source-project.json');await activate('#project-register-form button[type="submit"]');await settled(); - await until(()=>evaluate('document.querySelectorAll("#project-scientific-reference option").length===1'),'Real source reference appears'); - await fill('#project-scientific-name','Browser exact field sequence 山');await fill('#project-scientific-groups','browser-science');await fill('#project-scientific-rights','Owned authored scientific arrays'); - await activate('#project-scientific-form button[type="submit"]');await settled(); - const mismatch={...unpinned,id:crypto.randomUUID().replaceAll('-',''),data:[{...unpinned.data[0],sha256:'0'.repeat(64)}]};fs.writeFileSync(path.join(external,'mismatch-project.json'),JSON.stringify(mismatch)); - await fill('#project-register-path','mismatch-project.json');await activate('#project-register-form button[type="submit"]');await settled(); - assert.equal(await evaluate('Array.from(document.querySelectorAll("#project-scientific-reference option")).filter(option=>!option.disabled).length'),0,'Declared hash mismatch must not be selectable for import'); - await fill('#project-data-search','');await choose('#project-data-kind','field_sequence');await explore('data_query','Browser exact field sequence 山'); - scienceNote='Retained browser observation note café 山';await fill('#project-data-note',scienceNote);await activate('#project-data-note-form button[type="submit"]');await settled(); - const fields=await observe('data_query',{kind:'field_sequence',limit:40});assert.equal(fields.items.length,1);fieldId=fields.items[0].id; - expectedField=await observe('data_get',{record_id:fieldId});assert.equal(expectedField.annotation.note,scienceNote); - await explore('data_query','Browser exact field sequence 山');await activate('#project-detail-availability');await settled(); - check('Actual unpinned source registration uses current observed hash; declared mismatch is unavailable; exact scientific import, note and availability controls'); - // A missing source remains metadata and is resolved only through an explicit - // current-root file selection. No automatic search or source grant occurs. - const artifactSha=expectedField.source_sha256,artifactPath=path.join(external,'alpha','artifacts','sha256',artifactSha); - assert.ok(fs.existsSync(artifactPath),'Imported exact scientific artifact exists'); - const originalArtifact=fs.readFileSync(artifactPath);fs.unlinkSync(artifactPath); - await explore('artifacts',artifactSha);await activate('#project-artifact-status'); - await until(()=>evaluate('!document.getElementById("project-artifact-resolve-form").hidden'),'Missing artifact resolution offered explicitly'); - await choose('#project-artifact-root','fixture');await fill('#project-artifact-path','observed-fields.zip');await activate('#project-artifact-resolve-form button[type="submit"]');await settled(); - await activate('#project-artifact-status');await settled(); - assert.equal((await observe('artifact_status',{sha256:artifactSha})).state,'verified'); - assert.deepEqual(fs.readFileSync(artifactPath),originalArtifact); - check('Missing artifact survives as metadata and explicit current-root resolution restores verified exact bytes'); - await fill('#project-study-create-name','Browser Study hypothesis 山');await fill('#project-study-metric','b'.repeat(64)); - await activate('#project-study-create-form button[type="submit"]');await settled(); - await explore('studies','Browser Study hypothesis 山'); - await fill('#project-metadata-name','Browser revised Study hypothesis 山');await activate('#project-metadata-form button[type="submit"]');await settled(); - await explore('studies','Browser revised Study hypothesis 山'); - const studies=await observe('studies',{limit:40});assert.equal(studies.items.length,1);studyId=studies.items[0].study.id; - projectId=(await state()).project.project_id; - expectedStudy=await observe('study',{study_id:studyId,origin_catalog_id:projectId,limit:1});assert.equal(expectedStudy.study.revision,2); - check('Study creation and metadata revision use actual named controls without execution'); - } - await activate('#project-files-save');await settled();const beforeClose=await state(); - await capture('m2-authored-1440.jpg',1440,'#project-detail-title');await capture('m2-authored-390.jpg',390,'#project-detail-title'); - if(process.env.TULDOK_M2_LAYOUT_ONLY==='1'){console.log('Layout-only probe complete '+report);return;} - await activate('#project-files-close');await until(async()=>((await state()).state==='no_project_open'));await stop(server); - const source=path.join(external,'alpha');fs.mkdirSync(path.join(source,'scripts'),{recursive:true}); - fs.writeFileSync(path.join(source,'scripts','sentinel.py'),"from pathlib import Path\nPath(__file__).with_name('EXECUTED').write_text('bad')\n"); - const before=snapshot(source),coldExternal=path.join(temporary,'cold-external');fs.mkdirSync(coldExternal);const clone=path.join(coldExternal,'clone'); - execFileSync('git',['init','-q','--template=',source],gitOptions);execFileSync('git',['-C',source,'add','.'],gitOptions); - execFileSync('git',['-C',source,'-c','user.name=Disposable M2 QA','-c','user.email=qa@example.invalid','-c','commit.gpgsign=false','-c','core.hooksPath=/dev/null','commit','-qm','Authored M2 browser fixture'],gitOptions); - execFileSync('git',['-c','core.hooksPath=/dev/null','clone','-q','--no-hardlinks','--template=',source,clone],gitOptions);fs.cpSync(path.join(source,'artifacts'),path.join(clone,'artifacts'),{recursive:true});assert.deepEqual(snapshot(clone),before); - await start(coldControl,coldExternal,coldDsn);await navigate();await choose('#project-files-root','fixture');await fill('#project-files-directory','clone');await activate('#project-files-open'); - await until(async()=>((await state()).state==='open'));await settled();assert.deepEqual((await state()).project,beforeClose.project); - assert.deepEqual(await observe('data_get',{record_id:imageId}),expectedImage);assert.deepEqual(await observe('data_get',{record_id:fieldId}),expectedField); - assert.deepEqual(await observe('study',{study_id:studyId,origin_catalog_id:projectId,limit:1}),expectedStudy); - await fill('#project-data-search','');await choose('#project-data-kind','image');await explore('data_query','Browser image café 山'); - assert.equal(await evaluate('document.getElementById("project-rights-note").value'),rights); - await activate('#project-detail-history');await until(()=>evaluate('document.getElementById("project-detail-history-list").textContent.includes('+JSON.stringify(rights)+')')); - await capture('m2-cold-image-390.jpg',390,'#project-detail-history-list'); - await choose('#project-data-kind','field_sequence');await explore('data_query','Browser exact field sequence 山'); - assert.equal(await evaluate('document.getElementById("project-data-note").value'),scienceNote);await activate('#project-detail-availability');await settled(); - await capture('m2-cold-science-1440.jpg',1440,'#project-detail-title'); - await activate('#project-files-save');await settled();assert.deepEqual(snapshot(clone),before);assert.ok(!fs.existsSync(path.join(clone,'scripts','EXECUTED'))); - check('Fresh process, fresh control, distinct PostgreSQL role denied source CONNECT and real Git metadata clone plus explicit untracked artifact transfer reconstruct exact data/history/Study; no-op Save changes no bytes; sentinel stays inert'); - assert.deepEqual(errors,[]);assert.deepEqual(httpErrors,[]); - for(const [file,digest] of Object.entries(material.files))assert.equal(crypto.createHash('sha256').update(fs.readFileSync(path.join(root,file))).digest('hex'),digest,'Frozen product source changed '+file); - for(const [file,digest] of Object.entries(testMaterial))assert.equal(crypto.createHash('sha256').update(fs.readFileSync(path.join(root,file))).digest('hex'),digest,'Acceptance test changed during campaign '+file); - fs.writeFileSync(path.join(report,'receipt.json'),JSON.stringify({status:responsiveFailures.length?'failed':'pass',functional_gate_passed:true,cold_gate_passed:true,responsive_failures:responsiveFailures,checks,isolation,material,test_material:testMaterial,authoring:process.env.TULDOK_M2_RESUME_HTTP==='1'?'real HTTP equivalent fixture; prior UI evidence retained':'actual UI native authoring',project:beforeClose.project,image_id:imageId,field_id:fieldId,study_id:studyId,canonical_sha256:before,browser_runtime_errors:errors,http_errors:httpErrors,fixture:'Authored disposable synthetic fixtures; no training or scientific validity claim'},null,2)+'\n'); - console.log('Report '+path.join(report,'receipt.json'));if(responsiveFailures.length)throw Error('Responsive overflow remains after independently completed cold gate'); -})().catch(async error=>{fs.writeFileSync(path.join(report,'failure-receipt.json'),JSON.stringify({status:'failed',error:error.message,checks,material,test_material:testMaterial,responsive_failures:responsiveFailures,browser_runtime_errors:errors,http_errors:httpErrors},null,2)+'\n');console.error('Failure receipt '+path.join(report,'failure-receipt.json'));console.error(error);console.error('Server diagnostics:',serverErrors);console.error('Browser runtime errors:',JSON.stringify(errors));console.error('HTTP errors:',JSON.stringify(httpErrors));if(evaluate)try{console.error('UI diagnostics:',await evaluate('document.body.innerText'));}catch(diagnostic){console.error('UI diagnostics unavailable:',diagnostic.message);}process.exitCode=1;}).finally(async()=>{ - session?.close();socket?.close(); - for(const child of children.reverse())await stop(child); - // Drop only UUID catalog schemas whose manifests live under this owned root. - for(const {control,dsn} of catalogs){ - try{execFileSync('python3',['-c', - "import json,pathlib,os,psycopg;from psycopg import sql;root=pathlib.Path(os.environ['QA_CONTROL']);c=psycopg.connect(os.environ['TULDOK_DATABASE_URL'],autocommit=True);[(c.execute(sql.SQL('DROP SCHEMA IF EXISTS {} CASCADE').format(sql.Identifier(('projection_'+v['projection_id']) if v['version']==2 else ('catalog_'+v['dataset_id']))))) for p in root.rglob('.tuldok.json') for v in [json.loads(p.read_text())]];c.close()" - ],{cwd:root,env:{...process.env,TULDOK_DATABASE_URL:dsn,QA_CONTROL:control},stdio:['ignore','pipe','pipe']});}catch(error){console.error('Owned schema cleanup failed:',error.message);process.exitCode=1;} - } - process.env.TULDOK_DATABASE_URL=sourceDsn; - fs.rmSync(temporary,{recursive:true,force:true}); -}); diff --git a/tests/browser_project_files_m3.cjs b/tests/browser_project_files_m3.cjs deleted file mode 100644 index 5fc1a735..00000000 --- a/tests/browser_project_files_m3.cjs +++ /dev/null @@ -1,128 +0,0 @@ -'use strict'; -// Real named runtime controls; offline byte capture, explicit recovery, inert cold Open. -const assert=require('node:assert/strict'),fs=require('node:fs'),os=require('node:os'),path=require('node:path'),crypto=require('node:crypto'); -const {spawn,execFileSync}=require('node:child_process'),{once}=require('node:events'); -const {authenticatedFixture}=require('./auth_helpers.cjs'),{waitForDebugger}=require('./browser_startup.cjs'),{cdpSession}=require('./browser_cdp_session.cjs'),{qaDirectory,screenshotOptions}=require('./qa_artifacts.cjs'); -const root=path.resolve(__dirname,'..'),hash=raw=>crypto.createHash('sha256').update(raw).digest('hex'); -assert.ok(process.env.TULDOK_DATABASE_URL&&process.env.TULDOK_PROJECT_FILES_COLD_DATABASE_URL,'Disposable source and cold PostgreSQL configurations required'); -assert.ok(process.env.TULDOK_M3_FREEZE_MANIFEST,'Lead must freeze and qualify isolated M3 before actual browser acceptance'); -const freeze=JSON.parse(fs.readFileSync(process.env.TULDOK_M3_FREEZE_MANIFEST,'utf8')); -const material={manifest_sha256:hash(fs.readFileSync(process.env.TULDOK_M3_FREEZE_MANIFEST)),files:freeze.files}; -function verifySource(){for(const [file,expected] of Object.entries(material.files))assert.equal(hash(fs.readFileSync(path.join(root,file))),expected,'Frozen source changed: '+file);} -verifySource(); -const testSha=hash(fs.readFileSync(__filename)),temporary=fs.mkdtempSync(path.join(os.tmpdir(),'tuldok-m3-browser-')),report=qaDirectory(root,'project-files-m3'); -const sourceDsn=process.env.TULDOK_DATABASE_URL,coldDsn=process.env.TULDOK_PROJECT_FILES_COLD_DATABASE_URL; -assert.notEqual(sourceDsn,coldDsn); -const external=path.join(temporary,'external');fs.mkdirSync(external); -const children=[],catalogs=[],checks=[],errors=[],httpErrors=[],bounds=[],requests=[]; -const sentinel=path.join(temporary,'EXECUTED'),audit=path.join(temporary,'process-audit.jsonl'),auditDir=path.join(temporary,'audit');fs.mkdirSync(auditDir); -fs.writeFileSync(path.join(auditDir,'sitecustomize.py'),`import sys,os,json -with open(os.environ['QA_AUDIT_INSTALLED'],'w') as f:f.write('installed') -def guard(event,args): - if event in ('subprocess.Popen','os.system','os.exec','os.posix_spawn'): - with open(os.environ['QA_PROCESS_AUDIT'],'a') as f:f.write(json.dumps({'event':event})+'\\n') - raise AssertionError('No process execution is allowed during this capture fixture') -sys.addaudithook(guard) -`); -const configFile=path.join(temporary,'runtime.json'); -const gitEnv={...process.env,GIT_CONFIG_NOSYSTEM:'1',GIT_CONFIG_GLOBAL:'/dev/null',GIT_TERMINAL_PROMPT:'0'}; -const routes=JSON.parse(execFileSync('python3',['-c',"import json,agent_api;names=agent_api.ProjectFilesOwnerClient.OPERATIONS;print(json.dumps({n.split('.')[1]:{**{k:agent_api.operation(n)[k] for k in ('path','method','query','side_effects')},'header':agent_api.selected_header(n)} for n in names}))"],{cwd:root,encoding:'utf8'})); -let server,origin,auth,socket,session,send,evaluate,serverErrors='',isolation; -const pause=ms=>new Promise(resolve=>setTimeout(resolve,ms)); -async function until(fn,label){for(let i=0;i<200;i++){const result=await fn();if(result)return result;await pause(100);}throw Error('Timed out: '+label);} -function launch(command,args,options={}){const child=spawn(command,args,options);children.push(child);return child;} -async function stop(child){if(!child||child.exitCode!==null||child.signalCode!==null)return;const exited=once(child,'exit');child.kill('SIGTERM');await exited;} -async function start(control,directory,dsn,configured=false){ - process.env.TULDOK_DATABASE_URL=dsn;serverErrors='';let output=''; - server=launch('python3',['-u','app.py','--port','0','--data',control,'--project-files-root','fixture='+directory,...(configured?['--project-runtime-source','inert-fixture='+configFile]:[])],{cwd:root,env:{...process.env,TULDOK_DATABASE_URL:dsn,QA_PROCESS_AUDIT:audit,QA_AUDIT_INSTALLED:path.join(temporary,'audit-installed-'+catalogs.length),PYTHONPATH:auditDir+path.delimiter+(process.env.PYTHONPATH||'')},stdio:['ignore','pipe','pipe']}); - server.stdout.on('data',chunk=>output+=chunk);server.stderr.on('data',chunk=>serverErrors+=chunk); - const port=await until(()=>{if(server.exitCode!==null)throw Error('Server exited: '+serverErrors);return output.match(/127\.0\.0\.1:(\d+)/)?.[1];},'actual server startup'); - assert.ok(fs.existsSync(path.join(temporary,'audit-installed-'+catalogs.length)),'App audit assertion installed');origin='http://127.0.0.1:'+port;catalogs.push({control,dsn});auth=authenticatedFixture();await auth.register(origin,control,root); -} -async function state(){const response=await auth.fetch(origin+routes.status.path,{headers:{'Tuldok-Operation-Contract':routes.status.header}});const value=await response.json();assert.equal(response.status,200,JSON.stringify(value));return value;} -async function key(key,code=key,modifiers=0){for(const type of ['keyDown','keyUp'])await send('Input.dispatchKeyEvent',{type,key,code,modifiers,windowsVirtualKeyCode:{Enter:13,Tab:9,a:65,' ':32}[key]||0,...(type==='keyDown'&&key==='Enter'?{text:'\r',unmodifiedText:'\r'}:{})});} -async function focus(selector){await until(()=>evaluate(`(()=>{const e=document.querySelector(${JSON.stringify(selector)});if(!e||e.disabled||!e.getClientRects().length)return false;e.scrollIntoView({block:'center'});e.focus();return document.activeElement===e;})()`),'focus '+selector);} -async function fill(selector,value){await focus(selector);await key('a','KeyA',2);await send('Input.insertText',{text:value});} -async function activate(selector){await focus(selector);await key('Enter');} -async function choose(selector,value){await focus(selector);await evaluate(`(()=>{const e=document.querySelector(${JSON.stringify(selector)});if(!Array.from(e.options).some(o=>o.value===${JSON.stringify(value)}))throw Error('Missing option');e.value=${JSON.stringify(value)};e.dispatchEvent(new Event('change',{bubbles:true}));e.dispatchEvent(new Event('input',{bubbles:true}));})()`);} -async function settled(){await until(async()=>{const failure=await evaluate('document.getElementById("project-files-error").textContent');if(failure)throw Error('UI error: '+failure);return evaluate('!document.getElementById("project-files-save").disabled');},'acknowledged UI state');} -async function navigate(){await auth.browser(send,origin);await send('Page.navigate',{url:origin+'/project-files'});await until(()=>evaluate('!!document.querySelector("#project-files-root option")&&!document.getElementById("project-files-new").disabled'),'negotiated UI startup');} -async function capture(width){ - await send('Emulation.setDeviceMetricsOverride',{width,height:950,deviceScaleFactor:1,mobile:false});await evaluate('document.getElementById("project-runtime-title").scrollIntoView({block:"start"})'); - await evaluate('new Promise(resolve=>requestAnimationFrame(()=>requestAnimationFrame(resolve)))'); - const value=await evaluate('({viewport:innerWidth,width:document.documentElement.scrollWidth,client:document.documentElement.clientWidth,offenders:Array.from(document.querySelectorAll("body *")).filter(e=>e.getClientRects().length&&e.getBoundingClientRect().right>innerWidth+1).map(e=>({tag:e.tagName,id:e.id,width:e.getBoundingClientRect().width,right:e.getBoundingClientRect().right,text:e.textContent.slice(0,100)})).slice(-20)})'); - bounds.push(value);fs.writeFileSync(path.join(report,'bounds-'+width+'.json'),JSON.stringify(value,null,2)+'\n');fs.writeFileSync(path.join(report,'m3-runtime-'+width+'.jpg'),Buffer.from((await send('Page.captureScreenshot',screenshotOptions)).data,'base64')); - assert.ok(value.width<=value.viewport+1,'Responsive overflow: '+JSON.stringify(value)); -} -function snapshot(directory){const files={};function walk(at){for(const item of fs.readdirSync(at,{withFileTypes:true})){if(['.git','.tuldok-local'].includes(item.name))continue;const next=path.join(at,item.name);if(item.isDirectory())walk(next);else if(item.isFile())files[path.relative(directory,next)]=hash(fs.readFileSync(next));else throw Error('Unexpected special fixture file');}}walk(directory);return files;} -function check(value){checks.push(value);console.log('PASS '+value);} -(async()=>{ - isolation=JSON.parse(execFileSync('python3',['-c',"import json,os,psycopg;from psycopg.conninfo import conninfo_to_dict;s=conninfo_to_dict(os.environ['TULDOK_DATABASE_URL']);c=psycopg.connect(os.environ['TULDOK_PROJECT_FILES_COLD_DATABASE_URL']);row=c.execute('SELECT current_database(),current_user,has_database_privilege(current_user,%s,%s)',(s['dbname'],'CONNECT')).fetchone();assert row[0]!=s['dbname'] and not row[2];print(json.dumps(dict(database=row[0],role=row[1],source_connect=row[2])));c.close()"],{cwd:root,encoding:'utf8'})); - execFileSync('python3',['-c',`import json,pathlib,shutil,sys -p=pathlib.Path(sys.argv[1]);python=p/'explicit-python';site=p/'explicit-packages' -(python/'bin').mkdir(parents=True);(python/'lib/python3.12/lib-dynload').mkdir(parents=True) -shutil.copyfile('/usr/bin/true',python/'bin/python3.12') -for i in range(45):(python/'lib/python3.12/lib-dynload'/('fixture-%03d.txt'%i)).write_text('Owned inert runtime bytes Ω '+str(i)) -packages=[] -for name in ('torch','numpy'): - (site/name).mkdir(parents=True);(site/name/'__init__.py').write_text('from pathlib import Path'+chr(10)+'Path('+repr(sys.argv[2])+').write_text("executed")'+chr(10)+'raise AssertionError("Never import fixture")'+chr(10)) - info=site/(name+'-0.0.dist-info');info.mkdir();(info/'METADATA').write_text('Name: '+name+chr(10)+'Version: 0.0'+chr(10));(info/'LICENSE').write_text('Owned fixture');packages.extend([name,info.name]) -(p/'runtime.json').write_text(json.dumps(dict(schema_version=1,python_root=str(python),python_version='3.12',site_packages=str(site),packages=packages)))`,temporary,sentinel],{cwd:root}); - await start(path.join(temporary,'control'),external,sourceDsn,true); - const browser=launch(process.env.BROWSER||'/usr/bin/chromium',['--headless','--no-sandbox','--disable-gpu','--no-first-run','--remote-debugging-port=0','--window-size=1440,950','--user-data-dir='+path.join(temporary,'browser'),'about:blank'],{stdio:'ignore',env:{...process.env,XDG_CONFIG_HOME:temporary,XDG_CACHE_HOME:temporary}}); - const port=await waitForDebugger(browser,path.join(temporary,'browser','DevToolsActivePort')),tabs=await(await fetch('http://127.0.0.1:'+port+'/json')).json(),target=tabs.find(tab=>tab.type==='page'&&tab.url==='about:blank');assert.ok(target); - socket=new WebSocket(target.webSocketDebuggerUrl);await once(socket,'open');session=cdpSession(socket,{onEvent:event=>{if(event.method==='Runtime.exceptionThrown')errors.push(event.params.exceptionDetails);if(event.method==='Network.requestWillBeSent')requests.push({url:event.params.request.url,method:event.params.request.method,body:event.params.request.postData});if(event.method==='Network.responseReceived'&&event.params.response.status>=400)httpErrors.push({url:event.params.response.url,status:event.params.response.status});}});send=session.send; - evaluate=async expression=>{const result=await send('Runtime.evaluate',{expression,awaitPromise:true,returnByValue:true});if(result.exceptionDetails)throw Error(JSON.stringify(result.exceptionDetails));return result.result.value;}; - await send('Page.enable');await send('Runtime.enable');await send('Network.enable');await navigate(); - await fill('#project-files-directory','alpha');await fill('#project-files-name','M3 offline runtime browser Ω');await activate('#project-files-new');await settled(); - const initial=await state(),project=initial.project.project_id; - const automatic=()=>requests.filter(r=>r.url.includes('/runtime/')); - assert.equal(automatic().length,0,'New does not automatically inspect or capture runtime'); - await activate('#project-runtime-sources');await settled();assert.equal(await evaluate('document.querySelectorAll("#project-runtime-source option").length'),1); - await activate('#project-runtime-inspect');await settled();assert.equal(await evaluate('document.querySelectorAll("#project-runtime-files li").length'),40); - await activate('#project-runtime-files-more');await settled();assert.ok(await evaluate('document.querySelectorAll("#project-runtime-files li").length>40')); - const summary=await evaluate('document.getElementById("project-runtime-summary").textContent'),inventory=summary.match(/[a-f0-9]{64}/)[0]; - assert.match(await evaluate('document.getElementById("project-runtime-layout").textContent'),/torch/);assert.equal(automatic().filter(r=>r.method==='POST').length,0); - check('Keyboard loads configured alias and bounded paged inventory without capture or executing package imports'); - await fill('#project-runtime-reserve','9007199254740991');await focus('#project-runtime-confirm');await key(' ','Space'); - await activate('#project-runtime-capture'); - await until(()=>evaluate('document.getElementById("project-files-error").textContent'),'expected real insufficient-reserve error'); - const failedCapture=automatic().find(r=>r.method==='POST'&&r.url.endsWith('/runtime/capture'));assert.ok(failedCapture);const failedBody=JSON.parse(failedCapture.body); - assert.match(await evaluate('document.getElementById("project-files-error").textContent'),/disk|reserve/i); - await activate('#project-files-refresh'); - await until(()=>evaluate('!document.getElementById("project-runtime-abandon-fields").disabled'),'current original capture recovery control'); - const pending=await state();assert.ok(['open','recovery_required'].includes(pending.state)); - await fill('#project-runtime-abandon-key',failedBody.request_key);await fill('#project-runtime-abandon-reason','Explicitly abandon impossible reserve; preserve original inventory and intent Ω');await activate('#project-runtime-abandon'); - await until(()=>evaluate('document.getElementById("project-files-status").textContent.includes("partial bytes and scientific intent remain")'),'canonical abandonment ACK'); - await activate('#project-files-refresh');await settled(); - await fill('#project-runtime-status-key',failedBody.request_key);await activate('#project-runtime-status-form button');await settled(); - const abandoned=JSON.parse(await evaluate('document.getElementById("project-runtime-status").textContent'));assert.equal(abandoned.state,'abandoned');assert.equal(abandoned.intent.manifest_sha256,inventory);assert.equal(abandoned.abandonment.capture_key,failedBody.request_key);assert.equal(abandoned.result,null); - check('Real reserve failure retains durable intent; named current-owner abandonment records exact key/reason and historical abandoned outcome'); - await activate('#project-runtime-sources');await settled();await activate('#project-runtime-inspect');await settled();await fill('#project-runtime-reserve','0');await focus('#project-runtime-confirm');await key(' ','Space');await activate('#project-runtime-capture');await settled(); - const captured=JSON.parse(await evaluate('document.getElementById("project-runtime-status").textContent'));assert.equal(captured.format,'project_runtime_capture_v1');assert.equal(captured.project_id,project);assert.equal(captured.manifest_sha256,inventory);assert.notEqual(captured.request_key,failedBody.request_key); - await activate('#project-runtime-status-form button');await settled();const historical=JSON.parse(await evaluate('document.getElementById("project-runtime-status").textContent'));assert.equal(historical.state,'captured');assert.deepEqual(historical.result,captured); - assert.ok(!fs.existsSync(sentinel));assert.ok(!fs.existsSync(audit),'Application never attempted subprocess/exec/install'); - check('Fresh explicit confirmed capture copies offline bytes and retains intent/result; no child process or package import executes'); - // Edits reach the project folder on Save; Close keeps them only in the working copy. - await activate('#project-files-save');await settled(); - await activate('#project-files-close');await until(async()=>(await state()).state==='no_project_open','close captured project');await stop(server); - const source=path.join(external,'alpha'),coldRoot=path.join(temporary,'cold-external');fs.mkdirSync(coldRoot);const clone=path.join(coldRoot,'clone'),canonical=snapshot(source); - const git=(...args)=>execFileSync('git',args,{env:gitEnv,stdio:['ignore','pipe','pipe']});git('init','-q','--template=',source);git('-C',source,'add','.');git('-C',source,'-c','user.name=Disposable M3 QA','-c','user.email=qa@example.invalid','-c','commit.gpgsign=false','-c','core.hooksPath=/dev/null','commit','-qm','Inert canonical runtime facts');git('-c','core.hooksPath=/dev/null','clone','-q','--no-hardlinks','--template=',source,clone);if(fs.existsSync(path.join(source,'artifacts')))fs.cpSync(path.join(source,'artifacts'),path.join(clone,'artifacts'),{recursive:true});assert.deepEqual(snapshot(clone),canonical); - // Remove the original configured source before cold Open. Canonical metadata cannot restore it. - fs.rmSync(path.join(temporary,'explicit-python'),{recursive:true});fs.rmSync(path.join(temporary,'explicit-packages'),{recursive:true});fs.unlinkSync(configFile); - const beforeCold=automatic().length;await start(path.join(temporary,'cold-control'),coldRoot,coldDsn);await navigate();await fill('#project-files-directory','clone');await activate('#project-files-open');await settled();assert.equal((await state()).project.project_id,project);assert.equal(automatic().length,beforeCold,'Cold Open does not auto inspect/capture/status'); - await activate('#project-runtime-sources');await settled();assert.equal(await evaluate('document.querySelectorAll("#project-runtime-source option").length'),0); - await fill('#project-runtime-status-key',captured.request_key);await activate('#project-runtime-status-form button');await settled();assert.deepEqual(JSON.parse(await evaluate('document.getElementById("project-runtime-status").textContent')),historical); - await fill('#project-runtime-status-key',failedBody.request_key);await activate('#project-runtime-status-form button');await settled();assert.deepEqual(JSON.parse(await evaluate('document.getElementById("project-runtime-status").textContent')),abandoned); - const cached=execFileSync('python3',['-c',"from pathlib import Path;import sys;print(len(list(Path(sys.argv[1]).rglob('runtime-snapshots'))))",path.join(temporary,'cold-control')],{encoding:'utf8'}).trim();assert.equal(cached,'0'); - await capture(390);await capture(1440);assert.deepEqual(snapshot(clone),canonical);assert.ok(!fs.existsSync(sentinel));assert.ok(!fs.existsSync(audit));assert.deepEqual(errors,[]); - assert.equal(httpErrors.length,1,JSON.stringify(httpErrors));assert.ok(httpErrors[0].url.endsWith('/runtime/capture'));verifySource();assert.equal(hash(fs.readFileSync(__filename)),testSha); - check('Cold keyboard UI on distinct role denied source CONNECT reconstructs exact captured/abandoned facts with no source alias/cache or automatic regeneration; 390/1440 responsive'); - fs.writeFileSync(path.join(report,'receipt.json'),JSON.stringify({status:'pass',source_stable:true,checks,material,test_sha256:testSha,isolation,bounds,project_id:project,captured,abandoned,browser_runtime_errors:errors,expected_http_errors:httpErrors,runtime_requests:automatic(),fixture:'M3 enabled only in derived immutable source. Actual app CLI/PG/Chromium; offline true ELF plus inert never-import packages; app-only audit hook rejects child execution; real impossible-reserve failure and explicit current-marker abandonment; Git canonical clone with explicit artifact transfer; source removed before cold Open. No scientific execution or runtime preflight.'},null,2)+'\n');console.log('Report '+path.join(report,'receipt.json')); -})().catch(async error=>{ - fs.writeFileSync(path.join(report,'failure-receipt.json'),JSON.stringify({status:'failed',error:error.message,checks,material,test_sha256:testSha,isolation,bounds,browser_runtime_errors:errors,http_errors:httpErrors,runtime_requests:requests.filter(r=>r.url.includes("/runtime/"))},null,2)+'\n');console.error(error);console.error('Server:',serverErrors);if(evaluate)try{console.error('UI:',await evaluate('document.body.innerText'));}catch(_){}process.exitCode=1; -}).finally(async()=>{ - session?.close();socket?.close();for(const child of children.reverse())await stop(child); - for(const {control,dsn} of catalogs)try{execFileSync('python3',['-c',"import json,pathlib,os,psycopg;from psycopg import sql;root=pathlib.Path(os.environ['QA_CONTROL']);c=psycopg.connect(os.environ['TULDOK_DATABASE_URL'],autocommit=True);[(c.execute(sql.SQL('DROP SCHEMA IF EXISTS {} CASCADE').format(sql.Identifier('projection_'+v['projection_id'] if v['version']==2 else 'catalog_'+v['dataset_id'])))) for p in root.rglob('.tuldok.json') for v in [json.loads(p.read_text())]];c.close()"],{cwd:root,env:{...process.env,TULDOK_DATABASE_URL:dsn,QA_CONTROL:control},stdio:['ignore','pipe','pipe']});}catch(error){console.error('Owned cleanup failed:',error.message);process.exitCode=1;} - process.env.TULDOK_DATABASE_URL=sourceDsn;fs.rmSync(temporary,{recursive:true,force:true}); -}); diff --git a/tests/browser_project_files_m4.cjs b/tests/browser_project_files_m4.cjs deleted file mode 100644 index 3cc06c20..00000000 --- a/tests/browser_project_files_m4.cjs +++ /dev/null @@ -1,115 +0,0 @@ -'use strict'; -// Real keyboard-driven named M4 controls, followed by a cold metadata clone. -const assert=require('node:assert/strict'),fs=require('node:fs'),os=require('node:os'),path=require('node:path'),crypto=require('node:crypto'); -const {spawn,execFileSync}=require('node:child_process'),{once}=require('node:events'); -const {authenticatedFixture}=require('./auth_helpers.cjs'),{waitForDebugger}=require('./browser_startup.cjs'),{cdpSession}=require('./browser_cdp_session.cjs'),{qaDirectory,screenshotOptions}=require('./qa_artifacts.cjs'); -const root=path.resolve(__dirname,'..'),hash=raw=>crypto.createHash('sha256').update(raw).digest('hex'); -assert.ok(process.env.TULDOK_DATABASE_URL&&process.env.TULDOK_PROJECT_FILES_COLD_DATABASE_URL,'Disposable source and cold PostgreSQL configurations required'); -assert.ok(process.env.TULDOK_M4_FREEZE_MANIFEST,'Lead must freeze and enable M4 before actual browser acceptance'); -const freeze=JSON.parse(fs.readFileSync(process.env.TULDOK_M4_FREEZE_MANIFEST,'utf8')); -const material={manifest_sha256:hash(fs.readFileSync(process.env.TULDOK_M4_FREEZE_MANIFEST)),files:freeze.files}; -function verifySource(){for(const [file,expected] of Object.entries(material.files))assert.equal(hash(fs.readFileSync(path.join(root,file))),expected,'Frozen source changed: '+file);} -verifySource(); -const testSha=hash(fs.readFileSync(__filename)),temporary=fs.mkdtempSync(path.join(os.tmpdir(),'tuldok-m4-browser-')),report=qaDirectory(root,'project-files-m4'); -const sourceDsn=process.env.TULDOK_DATABASE_URL,coldDsn=process.env.TULDOK_PROJECT_FILES_COLD_DATABASE_URL; -assert.notEqual(sourceDsn,coldDsn); -const external=path.join(temporary,'external');fs.mkdirSync(external); -const children=[],catalogs=[],checks=[],errors=[],httpErrors=[],bounds=[]; -const gitEnv={...process.env,GIT_CONFIG_NOSYSTEM:'1',GIT_CONFIG_GLOBAL:'/dev/null',GIT_TERMINAL_PROMPT:'0'}; -const routes=JSON.parse(execFileSync('python3',['-c',"import json,agent_api;names=agent_api.ProjectFilesOwnerClient.OPERATIONS;print(json.dumps({n.split('.')[1]:{**{k:agent_api.operation(n)[k] for k in ('path','method','query','side_effects')},'header':agent_api.selected_header(n)} for n in names}))"],{cwd:root,encoding:'utf8'})); -let server,origin,auth,socket,session,send,evaluate,serverErrors='',isolation; -const pause=ms=>new Promise(resolve=>setTimeout(resolve,ms)); -async function until(fn,label){for(let i=0;i<200;i++){const result=await fn();if(result)return result;await pause(100);}throw Error('Timed out: '+label);} -function launch(command,args,options={}){const child=spawn(command,args,options);children.push(child);return child;} -async function stop(child){if(!child||child.exitCode!==null||child.signalCode!==null)return;const exited=once(child,'exit');child.kill('SIGTERM');await exited;} -async function start(control,directory,dsn){ - process.env.TULDOK_DATABASE_URL=dsn;serverErrors='';let output=''; - server=launch('python3',['-u','app.py','--port','0','--data',control,'--project-files-root','fixture='+directory],{cwd:root,env:{...process.env,TULDOK_DATABASE_URL:dsn},stdio:['ignore','pipe','pipe']}); - server.stdout.on('data',chunk=>output+=chunk);server.stderr.on('data',chunk=>serverErrors+=chunk); - const port=await until(()=>{if(server.exitCode!==null)throw Error('Server exited: '+serverErrors);return output.match(/127\.0\.0\.1:(\d+)/)?.[1];},'actual server startup'); - origin='http://127.0.0.1:'+port;catalogs.push({control,dsn});auth=authenticatedFixture();await auth.register(origin,control,root); -} -async function state(){const response=await auth.fetch(origin+routes.status.path,{headers:{'Tuldok-Operation-Contract':routes.status.header}});const value=await response.json();assert.equal(response.status,200,JSON.stringify(value));return value;} -async function call(action,fields={}){ - const current=await state(),definition=routes[action],arguments_={binding:current.binding,[definition.side_effects?'expected_checkpoint':'checkpoint']:current.project.checkpoint,...(definition.side_effects?{request_key:crypto.randomUUID().replaceAll('-','')} :{}),...fields}; - let target=definition.path;for(const [key,value] of Object.entries(arguments_))target=target.replace('{'+key+'}',encodeURIComponent(value)); - const query=new URLSearchParams(Object.entries(arguments_).filter(([key])=>definition.query.includes(key)));if(query.size)target+='?'+query; - const body=Object.fromEntries(Object.entries(arguments_).filter(([key])=>!definition.query.includes(key)&&!definition.path.includes('{'+key+'}'))); - const response=await auth.fetch(origin+target,{method:definition.method,headers:{'Content-Type':'application/json','Tuldok-Operation-Contract':definition.header},...(definition.method==='POST'?{body:JSON.stringify(body)}:{})}); - const value=await response.json();assert.equal(response.status,200,JSON.stringify(value));return value.value; -} -async function key(key,code=key,modifiers=0){for(const type of ['keyDown','keyUp'])await send('Input.dispatchKeyEvent',{type,key,code,modifiers,windowsVirtualKeyCode:{Enter:13,Tab:9,a:65}[key]||0,...(type==='keyDown'&&key==='Enter'?{text:'\r',unmodifiedText:'\r'}:{})});} -async function focus(selector){await until(()=>evaluate(`(()=>{const e=document.querySelector(${JSON.stringify(selector)});if(!e||e.disabled||!e.getClientRects().length)return false;e.scrollIntoView({block:'center'});e.focus();return document.activeElement===e;})()`),'focus '+selector);} -async function fill(selector,value){await focus(selector);await key('a','KeyA',2);await send('Input.insertText',{text:value});} -async function activate(selector){await focus(selector);await key('Enter');} -async function choose(selector,value){await focus(selector);await evaluate(`(()=>{const e=document.querySelector(${JSON.stringify(selector)});if(!Array.from(e.options).some(o=>o.value===${JSON.stringify(value)}))throw Error('Missing option');e.value=${JSON.stringify(value)};e.dispatchEvent(new Event('change',{bubbles:true}));e.dispatchEvent(new Event('input',{bubbles:true}));})()`);} -async function settled(){await until(async()=>{const failure=await evaluate('document.getElementById("project-files-error").textContent');if(failure)throw Error('UI error: '+failure);return evaluate('!document.getElementById("project-files-save").disabled');},'acknowledged UI state');} -async function navigate(){await auth.browser(send,origin);await send('Page.navigate',{url:origin+'/project-files'});await until(()=>evaluate('!!document.querySelector("#project-files-root option")&&!document.getElementById("project-files-new").disabled'),'negotiated UI startup');} -async function working(kind,file,raw,revision=0){ - await choose('#project-working-kind',kind);await fill('#project-working-path',file);await fill('#project-working-revision',String(revision));await fill('#project-working-sha',hash(raw)); - await activate('#project-working-adopt-form button[type="submit"]');await settled(); - assert.equal(await evaluate('document.getElementById("project-working-text").value'),raw.toString()); -} -async function inspectFile(file){ - await activate('#project-working-load');await settled(); - await evaluate(`(()=>{const b=Array.from(document.querySelectorAll('#project-working-list button')).find(e=>e.textContent.startsWith(${JSON.stringify(file+' ·')}));if(!b)throw Error('Missing working file');b.dataset.qaSelected='yes';})()`); - await activate('#project-working-list button[data-qa-selected="yes"]');await settled(); -} -async function capture(width){ - await send('Emulation.setDeviceMetricsOverride',{width,height:950,deviceScaleFactor:1,mobile:false});await evaluate('document.getElementById("project-intent-title").scrollIntoView({block:"start"})'); - await evaluate('new Promise(resolve=>requestAnimationFrame(()=>requestAnimationFrame(resolve)))'); - const value=await evaluate('({viewport:innerWidth,width:document.documentElement.scrollWidth,client:document.documentElement.clientWidth,offenders:Array.from(document.querySelectorAll("body *")).filter(e=>e.getClientRects().length&&e.getBoundingClientRect().right>innerWidth+1).map(e=>({tag:e.tagName,id:e.id,width:e.getBoundingClientRect().width,right:e.getBoundingClientRect().right,text:e.textContent.slice(0,100)})).slice(-20)})'); - bounds.push(value);fs.writeFileSync(path.join(report,'bounds-'+width+'.json'),JSON.stringify(value,null,2)+'\n');fs.writeFileSync(path.join(report,'m4-cold-'+width+'.jpg'),Buffer.from((await send('Page.captureScreenshot',screenshotOptions)).data,'base64')); - assert.ok(value.width<=value.viewport+1,'Responsive overflow: '+JSON.stringify(value)); -} -function snapshot(directory){const files={};function walk(at){for(const item of fs.readdirSync(at,{withFileTypes:true})){if(['.git','.tuldok-local'].includes(item.name))continue;const next=path.join(at,item.name);if(item.isDirectory())walk(next);else if(item.isFile())files[path.relative(directory,next)]=hash(fs.readFileSync(next));else throw Error('Unexpected special fixture file');}}walk(directory);return files;} -function check(value){checks.push(value);console.log('PASS '+value);} -async function inspectIntent(){ - await activate('#project-intents-load');await settled();await until(()=>evaluate('document.querySelectorAll("#project-intents-list button").length===1'),'one unresolved recipe'); - await activate('#project-intents-list button');await settled(); - return JSON.parse(await evaluate('document.getElementById("project-intent-detail").textContent')); -} -(async()=>{ - isolation=JSON.parse(execFileSync('python3',['-c',"import json,os,psycopg;from psycopg.conninfo import conninfo_to_dict;s=conninfo_to_dict(os.environ['TULDOK_DATABASE_URL']);c=psycopg.connect(os.environ['TULDOK_PROJECT_FILES_COLD_DATABASE_URL']);row=c.execute('SELECT current_database(),current_user,has_database_privilege(current_user,%s,%s)',(s['dbname'],'CONNECT')).fetchone();assert row[0]!=s['dbname'] and not row[2];print(json.dumps(dict(database=row[0],role=row[1],source_connect=row[2])));c.close()"],{cwd:root,encoding:'utf8'})); - await start(path.join(temporary,'control'),external,sourceDsn); - const browser=launch(process.env.BROWSER||'/usr/bin/chromium',['--headless','--no-sandbox','--disable-gpu','--no-first-run','--remote-debugging-port=0','--window-size=1440,950','--user-data-dir='+path.join(temporary,'browser'),'about:blank'],{stdio:'ignore',env:{...process.env,XDG_CONFIG_HOME:temporary,XDG_CACHE_HOME:temporary}}); - const port=await waitForDebugger(browser,path.join(temporary,'browser','DevToolsActivePort')),tabs=await(await fetch('http://127.0.0.1:'+port+'/json')).json(),target=tabs.find(tab=>tab.type==='page'&&tab.url==='about:blank');assert.ok(target); - socket=new WebSocket(target.webSocketDebuggerUrl);await once(socket,'open');session=cdpSession(socket,{onEvent:event=>{if(event.method==='Runtime.exceptionThrown')errors.push(event.params.exceptionDetails);if(event.method==='Network.responseReceived'&&event.params.response.status>=400)httpErrors.push({url:event.params.response.url,status:event.params.response.status});}});send=session.send; - evaluate=async expression=>{const result=await send('Runtime.evaluate',{expression,awaitPromise:true,returnByValue:true});if(result.exceptionDetails)throw Error(JSON.stringify(result.exceptionDetails));return result.result.value;}; - await send('Page.enable');await send('Runtime.enable');await send('Network.enable');await navigate(); - await fill('#project-files-directory','alpha');await fill('#project-files-name','M4 original browser Ω');await activate('#project-files-new');await settled(); - const originalState=await state(),originalProject=originalState.project.project_id,source=path.join(external,'alpha'),sentinel=path.join(temporary,'EXECUTED'); - fs.mkdirSync(path.join(source,'scripts'));fs.mkdirSync(path.join(source,'notes')); - const first=Buffer.from('from pathlib import Path\nPath('+JSON.stringify(sentinel)+').write_text("executed")\n# authored Ω 山\n'),second=Buffer.concat([first,Buffer.from('# exact second decision 🌸\n')]); - fs.writeFileSync(path.join(source,'scripts/inert.py'),first);fs.writeFileSync(path.join(source,'notes/empty.md'),''); - await working('script','scripts/inert.py',first);await working('note','notes/empty.md',Buffer.alloc(0)); - fs.writeFileSync(path.join(source,'scripts/inert.py'),second);await inspectFile('scripts/inert.py'); - assert.equal(await evaluate('document.getElementById("project-working-text").value'),first.toString());assert.equal(await evaluate('document.getElementById("project-working-sha").value'),hash(second)); - await activate('#project-working-adopt-form button[type="submit"]');await settled();assert.equal(await evaluate('document.getElementById("project-working-text").value'),second.toString()); - await activate('#project-working-history');await settled();assert.equal(await evaluate('document.querySelectorAll("#project-working-history-list button").length'),2); - await activate('#project-working-history-list button');await settled();assert.equal(await evaluate('document.getElementById("project-working-text").value'),first.toString());assert.ok(!fs.existsSync(sentinel)); - check('Actual keyboard controls adopt script and empty note, review current changed digest and select exact older captured revision without execution'); - const draft=JSON.parse(execFileSync('python3',['-c',"import json,sys;sys.path.insert(0,'tests');from test_project_material_fork import recipe;v=recipe(sys.argv[1]);print(json.dumps({k:x for k,x in v.items() if k not in ('format','id','revision')}))",originalProject],{cwd:root,encoding:'utf8'})); - const retainedRecipe=await call('recipe_create',draft);await activate('#project-files-refresh');await settled(); - const sourceBefore=snapshot(source),sourceCheckpoint=(await state()).project.checkpoint; - await fill('#project-save-as-directory','independent');await fill('#project-save-as-name','M4 independent browser Ω');await activate('#project-files-save-as');await settled(); - const forkState=await state();assert.notEqual(forkState.project.project_id,originalProject);assert.notEqual(forkState.binding,originalState.binding);assert.deepEqual(snapshot(source),sourceBefore); - await activate('#project-fork-load');await settled();assert.match(await evaluate('document.getElementById("project-fork-summary").textContent'),new RegExp(sourceCheckpoint)); - const intent=await inspectIntent();assert.deepEqual(intent.current.definition,retainedRecipe);assert.equal(intent.fork_origin.project_id,originalProject);assert.equal(intent.current.definition.runtime.catalog_id,originalProject);assert.ok(intent.current.required_reselection.includes('runtime')); - await activate('#project-intent-capabilities');await settled();assert.match(await evaluate('document.getElementById("project-intents-list").textContent'),/Reselect/);assert.ok(!fs.existsSync(sentinel)); - check('Actual named Save As selects new identity; fork mapping and selected readonly original binding intent retain source parameters and require reselection'); - const fork=path.join(external,'independent');await activate('#project-files-close');await until(async()=>(await state()).state==='no_project_open','close before cold copy');await stop(server); - const coldRoot=path.join(temporary,'cold-external');fs.mkdirSync(coldRoot);const clone=path.join(coldRoot,'clone'),canonical=snapshot(fork); - const git=(...args)=>execFileSync('git',args,{env:gitEnv,stdio:['ignore','pipe','pipe']});git('init','-q','--template=',fork);git('-C',fork,'add','.');git('-C',fork,'-c','user.name=Disposable M4 QA','-c','user.email=qa@example.invalid','-c','commit.gpgsign=false','-c','core.hooksPath=/dev/null','commit','-qm','Exact independent M4 project');git('-c','core.hooksPath=/dev/null','clone','-q','--no-hardlinks','--template=',fork,clone);if(fs.existsSync(path.join(fork,'artifacts')))fs.cpSync(path.join(fork,'artifacts'),path.join(clone,'artifacts'),{recursive:true});assert.deepEqual(snapshot(clone),canonical); - await start(path.join(temporary,'cold-control'),coldRoot,coldDsn);await navigate();await fill('#project-files-directory','clone');await activate('#project-files-open');await settled();assert.deepEqual((await state()).project,forkState.project); - await inspectFile('scripts/inert.py');assert.equal(await evaluate('document.getElementById("project-working-text").value'),second.toString());await activate('#project-working-history');await settled();await activate('#project-working-history-list button');await settled();assert.equal(await evaluate('document.getElementById("project-working-text").value'),first.toString()); - assert.deepEqual(await inspectIntent(),intent);await capture(390);await capture(1440);assert.deepEqual(snapshot(clone),canonical);assert.ok(!fs.existsSync(sentinel));assert.deepEqual(errors,[]);assert.deepEqual(httpErrors,[]);verifySource();assert.equal(hash(fs.readFileSync(__filename)),testSha); - check('Cold UI on distinct role denied source CONNECT reconstructs exact fork, working-file history and unresolved intent; 390/1440 responsive and sentinel inert'); - fs.writeFileSync(path.join(report,'receipt.json'),JSON.stringify({status:'pass',checks,material,test_sha256:testSha,isolation,bounds,project:forkState.project,source_project:originalProject,browser_runtime_errors:errors,http_errors:httpErrors,canonical_sha256:canonical,fixture:'Real named keyboard UI; explicitly authored inert recipe references; local Git metadata clone plus explicit untracked payload transfer; no runtime/preflight'},null,2)+'\n');console.log('Report '+path.join(report,'receipt.json')); -})().catch(async error=>{ - fs.writeFileSync(path.join(report,'failure-receipt.json'),JSON.stringify({status:'failed',error:error.message,checks,material,test_sha256:testSha,isolation,bounds,browser_runtime_errors:errors,http_errors:httpErrors},null,2)+'\n');console.error(error);console.error('Server:',serverErrors);if(evaluate)try{console.error('UI:',await evaluate('document.body.innerText'));}catch(_){}process.exitCode=1; -}).finally(async()=>{ - session?.close();socket?.close();for(const child of children.reverse())await stop(child); - for(const {control,dsn} of catalogs)try{execFileSync('python3',['-c',"import json,pathlib,os,psycopg;from psycopg import sql;root=pathlib.Path(os.environ['QA_CONTROL']);c=psycopg.connect(os.environ['TULDOK_DATABASE_URL'],autocommit=True);[(c.execute(sql.SQL('DROP SCHEMA IF EXISTS {} CASCADE').format(sql.Identifier('projection_'+v['projection_id'] if v['version']==2 else 'catalog_'+v['dataset_id'])))) for p in root.rglob('.tuldok.json') for v in [json.loads(p.read_text())]];c.close()"],{cwd:root,env:{...process.env,TULDOK_DATABASE_URL:dsn,QA_CONTROL:control},stdio:['ignore','pipe','pipe']});}catch(error){console.error('Owned cleanup failed:',error.message);process.exitCode=1;} - process.env.TULDOK_DATABASE_URL=sourceDsn;fs.rmSync(temporary,{recursive:true,force:true}); -}); diff --git a/tests/browser_project_files_native.cjs b/tests/browser_project_files_native.cjs deleted file mode 100644 index b9a978af..00000000 --- a/tests/browser_project_files_native.cjs +++ /dev/null @@ -1,105 +0,0 @@ -'use strict'; -// Actual current native probe and zero-GO acknowledgement recovery; no model fit. -const assert=require('node:assert/strict'),fs=require('node:fs'),os=require('node:os'),path=require('node:path'),crypto=require('node:crypto'); -const {spawn,execFileSync}=require('node:child_process'),{once}=require('node:events'),readline=require('node:readline'); -const {authenticatedFixture}=require('./auth_helpers.cjs'),{waitForDebugger}=require('./browser_startup.cjs'),{cdpSession}=require('./browser_cdp_session.cjs'),{qaDirectory,screenshotOptions}=require('./qa_artifacts.cjs'); -const root=path.resolve(__dirname,'..'),hash=raw=>crypto.createHash('sha256').update(raw).digest('hex'); -assert.equal(process.env.TULDOK_NATIVE_PROJECT_GO,'1','Explicit native qualification GO required'); -assert.ok(process.env.TULDOK_DATABASE_URL&&process.env.TULDOK_PROJECT_FILES_COLD_DATABASE_URL,'Disposable source and cold PostgreSQL configurations required'); -assert.ok(process.env.TULDOK_NATIVE_PUBLIC_FREEZE_MANIFEST,'Lead must freeze and qualify isolated M3 before actual browser acceptance'); -const freeze=JSON.parse(fs.readFileSync(process.env.TULDOK_NATIVE_PUBLIC_FREEZE_MANIFEST,'utf8')); -const material={manifest_sha256:hash(fs.readFileSync(process.env.TULDOK_NATIVE_PUBLIC_FREEZE_MANIFEST)),files:freeze.files}; -function verifySource(){for(const [file,expected] of Object.entries(material.files))assert.equal(hash(fs.readFileSync(path.join(root,file))),expected,'Frozen source changed: '+file);} -verifySource(); -const testSha=hash(fs.readFileSync(__filename)),temporary=fs.mkdtempSync(path.join(os.tmpdir(),'tuldok-native-browser-')),report=qaDirectory(root,'project-native'); -const sourceDsn=process.env.TULDOK_DATABASE_URL,coldDsn=process.env.TULDOK_PROJECT_FILES_COLD_DATABASE_URL; -assert.notEqual(sourceDsn,coldDsn); -const children=[],catalogs=[],checks=[],errors=[],httpErrors=[],bounds=[],requests=[]; -const gitEnv={...process.env,GIT_CONFIG_NOSYSTEM:'1',GIT_CONFIG_GLOBAL:'/dev/null',GIT_TERMINAL_PROMPT:'0'}; -const routes=JSON.parse(execFileSync('python3',['-c',"import json,agent_api;names=agent_api.ProjectFilesOwnerClient.OPERATIONS;print(json.dumps({n.split('.')[1]:{**{k:agent_api.operation(n)[k] for k in ('path','method','query','side_effects')},'header':agent_api.selected_header(n)} for n in names}))"],{cwd:root,encoding:'utf8'})); -let server,origin,auth,socket,session,send,evaluate,serverErrors='',isolation,fixture,sourceFacts,coldFacts;const fixtures=[]; -const pause=ms=>new Promise(resolve=>setTimeout(resolve,ms)); -async function until(fn,label){for(let i=0;i<600;i++){const result=await fn();if(result)return result;await pause(100);}throw Error('Timed out: '+label);} -function launch(command,args,options={}){const child=spawn(command,args,options);children.push(child);return child;} -async function stop(child){if(!child||child.exitCode!==null||child.signalCode!==null)return;const exited=once(child,'exit');child.kill('SIGTERM');await exited;} -async function start(directory,dsn,cold=false){ - process.env.TULDOK_DATABASE_URL=dsn;serverErrors='';let ready; - server=launch('python3',['-u','tests/test_project_native_clients_http.py','--serve','--root',directory,...(cold?['--cold']:[])],{cwd:root,env:{...process.env,TULDOK_DATABASE_URL:dsn},stdio:['pipe','pipe','pipe']}); - const pending=new Map(),lines=readline.createInterface({input:server.stdout}); - lines.on('line',line=>{let value;try{value=JSON.parse(line);}catch(_){serverErrors+='\nUnexpected stdout: '+line;return;}if(value.origin){ready=value;return;}const wait=pending.get(value.id);if(wait){pending.delete(value.id);value.error?wait.reject(Error(value.error)):wait.resolve(value.result);}}); - server.stderr.on('data',chunk=>serverErrors+=chunk); - await until(()=>{if(server.exitCode!==null)throw Error('Fixture app exited: '+serverErrors);return ready;},'actual fixture app startup'); - const process_=server; - const host={process:process_,ready,async command(action){const id=crypto.randomUUID();return new Promise((resolve,reject)=>{const timeout=setTimeout(()=>{pending.delete(id);reject(Error('Fixture command timed out: '+action));},30000);pending.set(id,{resolve:value=>{clearTimeout(timeout);resolve(value);},reject:error=>{clearTimeout(timeout);reject(error);}});process_.stdin.write(JSON.stringify({id,action})+'\n');});},async stop(){if(process_.exitCode!==null)return;const exited=once(process_,'exit');await host.command('stop');const [code]=await exited;assert.equal(code,0,'Fixture cleanup exit: '+serverErrors);}}; - fixtures.push(host);fixture=host;origin=ready.origin;auth=authenticatedFixture();await auth.register(origin,ready.control,root);return host; -} -async function state(){const response=await auth.fetch(origin+routes.status.path,{headers:{'Tuldok-Operation-Contract':routes.status.header}});const value=await response.json();assert.equal(response.status,200,JSON.stringify(value));return value;} -async function key(key,code=key,modifiers=0){for(const type of ['keyDown','keyUp'])await send('Input.dispatchKeyEvent',{type,key,code,modifiers,windowsVirtualKeyCode:{Enter:13,Tab:9,a:65,' ':32}[key]||0,...(type==='keyDown'&&key==='Enter'?{text:'\r',unmodifiedText:'\r'}:{})});} -async function focus(selector){await until(()=>evaluate(`(()=>{const e=document.querySelector(${JSON.stringify(selector)});if(!e||e.disabled||!e.getClientRects().length)return false;e.scrollIntoView({block:'center'});e.focus();return document.activeElement===e;})()`),'focus '+selector);} -async function fill(selector,value){await focus(selector);await key('a','KeyA',2);await send('Input.insertText',{text:value});} -async function activate(selector){await focus(selector);await key('Enter');} -async function choose(selector,value){await focus(selector);await evaluate(`(()=>{const e=document.querySelector(${JSON.stringify(selector)});if(!Array.from(e.options).some(o=>o.value===${JSON.stringify(value)}))throw Error('Missing option');e.value=${JSON.stringify(value)};e.dispatchEvent(new Event('change',{bubbles:true}));e.dispatchEvent(new Event('input',{bubbles:true}));})()`);} -async function settled(){await until(async()=>{const failure=await evaluate('document.getElementById("project-files-error").textContent');if(failure)throw Error('UI error: '+failure);return evaluate('!document.getElementById("project-files-save").disabled');},'acknowledged UI state');} -async function navigate(){await auth.browser(send,origin);await send('Page.navigate',{url:origin+'/project-files'});await until(()=>evaluate('!!document.querySelector("#project-files-root option")&&!document.getElementById("project-files-new").disabled'),'negotiated UI startup');} -async function capture(width,label){ - await send('Emulation.setDeviceMetricsOverride',{width,height:950,deviceScaleFactor:1,mobile:false});await evaluate('document.getElementById("project-native-title").scrollIntoView({block:"start"})'); - await evaluate('new Promise(resolve=>requestAnimationFrame(()=>requestAnimationFrame(resolve)))'); - const value=await evaluate('({viewport:innerWidth,width:document.documentElement.scrollWidth,client:document.documentElement.clientWidth,offenders:Array.from(document.querySelectorAll("body *")).filter(e=>e.getClientRects().length&&e.getBoundingClientRect().right>innerWidth+1).map(e=>({tag:e.tagName,id:e.id,width:e.getBoundingClientRect().width,right:e.getBoundingClientRect().right,text:e.textContent.slice(0,100)})).slice(-20)})'); - bounds.push(value);fs.writeFileSync(path.join(report,label+'-bounds-'+width+'.json'),JSON.stringify(value,null,2)+'\n');fs.writeFileSync(path.join(report,label+'-'+width+'.jpg'),Buffer.from((await send('Page.captureScreenshot',screenshotOptions)).data,'base64')); - assert.ok(value.width<=value.viewport+1,'Responsive overflow: '+JSON.stringify(value)); -} -function snapshot(directory){const files={};function walk(at){for(const item of fs.readdirSync(at,{withFileTypes:true})){if(['.git','.tuldok-local'].includes(item.name))continue;const next=path.join(at,item.name);if(item.isDirectory())walk(next);else if(item.isFile())files[path.relative(directory,next)]=hash(fs.readFileSync(next));else throw Error('Unexpected special fixture file');}}walk(directory);return files;} -function check(value){checks.push(value);console.log('PASS '+value);} -(async()=>{ - assert.ok(process.env.TULDOK_TRAINING_PYTHON,'Current explicitly qualified native interpreter required'); - isolation=JSON.parse(execFileSync('python3',['-c',"import json,os,psycopg;from psycopg.conninfo import conninfo_to_dict;s=conninfo_to_dict(os.environ['TULDOK_DATABASE_URL']);c=psycopg.connect(os.environ['TULDOK_PROJECT_FILES_COLD_DATABASE_URL']);row=c.execute('SELECT current_database(),current_user,has_database_privilege(current_user,%s,%s)',(s['dbname'],'CONNECT')).fetchone();assert row[0]!=s['dbname'] and not row[2];print(json.dumps(dict(database=row[0],role=row[1],source_connect=row[2])));c.close()"],{cwd:root,encoding:'utf8'})); - const sourceHost=await start(path.join(temporary,'source-host'),sourceDsn); - const browser=launch(process.env.BROWSER||'/usr/bin/chromium',['--headless','--no-sandbox','--disable-gpu','--no-first-run','--remote-debugging-port=0','--window-size=1440,950','--user-data-dir='+path.join(temporary,'browser'),'about:blank'],{stdio:'ignore',env:{...process.env,XDG_CONFIG_HOME:temporary,XDG_CACHE_HOME:temporary}}); - const port=await waitForDebugger(browser,path.join(temporary,'browser','DevToolsActivePort')),tabs=await(await fetch('http://127.0.0.1:'+port+'/json')).json(),target=tabs.find(tab=>tab.type==='page'&&tab.url==='about:blank');assert.ok(target); - socket=new WebSocket(target.webSocketDebuggerUrl);await once(socket,'open');session=cdpSession(socket,{onEvent:event=>{if(event.method==='Runtime.exceptionThrown')errors.push(event.params.exceptionDetails);if(event.method==='Network.requestWillBeSent')requests.push({url:event.params.request.url,method:event.params.request.method,body:event.params.request.postData});if(event.method==='Network.responseReceived'&&event.params.response.status>=400)httpErrors.push({url:event.params.response.url,status:event.params.response.status});}});send=session.send; - evaluate=async expression=>{const result=await send('Runtime.evaluate',{expression,awaitPromise:true,returnByValue:true});if(result.exceptionDetails)throw Error(JSON.stringify(result.exceptionDetails));return result.result.value;}; - await send('Page.enable');await send('Runtime.enable');await send('Network.enable');await navigate(); - await fill('#project-files-directory','alpha');await fill('#project-files-name','Native keyboard CPU fixture Ω');await activate('#project-files-new');await settled(); - const project=(await state()).project.project_id,graph=await fixture.command('seed');assert.equal(graph.records,6);await activate('#project-files-refresh');await settled(); - const nativeRequests=()=>requests.filter(value=>value.url.includes('/execution/native/')); - assert.equal(nativeRequests().length,0);assert.equal((await fixture.command('facts')).go_events.length,0); - await activate('#project-native-graphs');await settled();assert.equal(await evaluate('document.querySelectorAll("#project-native-graph option").length'),1);assert.equal(nativeRequests().length,0); - await focus('#project-native-probe-confirm');await key(' ','Space');await activate('#project-native-preflight'); - await until(()=>evaluate('document.getElementById("project-files-status").textContent.includes("Native validation succeeded")'),'actual current CPU probe acknowledgement');await settled(); - let facts=await fixture.command('facts');assert.equal(facts.go_events.length,1);assert.equal(facts.workspace_runs,0);assert.ok(facts.go_events.every(event=>!event.in_transaction)); - assert.equal(await evaluate('document.getElementById("project-native-submit-fields").disabled'),false); - const before=nativeRequests().length;await activate('#project-native-submit');await evaluate('new Promise(resolve=>requestAnimationFrame(resolve))');assert.equal(nativeRequests().length,before,'Unchecked separate Start consent prevents dispatch'); - await capture(390,'validated');await capture(1440,'validated'); - check('Actual keyboard native preflight runs one current CPU probe; saved metadata loading and unchecked separate Start never dispatch a training Run'); - await fill('#project-native-run-id','9'.repeat(32));await focus('#project-native-retry-confirm');await key(' ','Space');await activate('#project-native-retry'); - await until(()=>evaluate('document.getElementById("project-files-error").textContent'),'typed current-only retry refusal');assert.match(await evaluate('document.getElementById("project-files-error").textContent'),/current local Run|current native Run/i); - facts=await fixture.command('facts');assert.equal(facts.go_events.length,1);assert.equal(facts.workspace_runs,0); - await activate('#project-files-discard');await activate('#project-files-refresh');await settled();await activate('#project-native-graphs');await settled(); - await fixture.command('install_fault');await focus('#project-native-probe-confirm');await key(' ','Space');await activate('#project-native-preflight'); - await until(()=>evaluate('document.getElementById("project-files-error").textContent'),'actual canonical/SQL acknowledgement fault');facts=await fixture.command('facts');assert.deepEqual(facts.fired,[true]);assert.equal(facts.go_events.length,1,'Failed GO intent SQL acknowledgement must send no second GO'); - await fixture.command('clear_fault');await activate('#project-files-refresh');await until(()=>evaluate('!document.getElementById("project-execution-health").disabled'),'recovery health current phase control');await activate('#project-execution-health'); - await until(()=>evaluate('document.querySelectorAll("#project-native-phases button").length===1'),'one original unresolved current phase ID'); - await evaluate(`(()=>{const button=Array.from(document.querySelectorAll('#project-native-phases button')).find(value=>/ · (ready|go_intent|unknown)$/.test(value.textContent));if(!button)throw Error('Missing original unresolved phase');button.dataset.qaSelected='yes';})()`); - await activate('#project-native-phases button[data-qa-selected="yes"]');const selectedPhase=await evaluate('document.getElementById("project-native-phase-id").value');assert.match(selectedPhase,/^[a-f0-9]{32}$/); - await activate('#project-native-reconcile');await until(()=>evaluate('document.getElementById("project-files-status").textContent.includes("does not start or resume")'),'original current phase receipt reconciliation'); - facts=await fixture.command('facts');assert.equal(facts.go_events.length,1);assert.equal(facts.pending,false);assert.equal(facts.available,true);assert.equal(facts.workspace_runs,0); - await activate('#project-files-discard');await activate('#project-files-refresh');await settled();sourceFacts=await fixture.command('facts'); - check('Named retry refuses absent current Run; real deferrable SQL fault after canonical GO intent sends zero GO, then keyboard health phase selection and explicit reconciliation restore availability without execution'); - // Edits reach the project folder on Save; Close keeps them only in the working copy. - await activate('#project-files-save');await settled(); - const source=path.join(sourceHost.ready.external,'alpha'),canonical=snapshot(source),saved=(await state()).project; - await activate('#project-files-close');await until(async()=>(await state()).state==='no_project_open','close before cold clone');await sourceHost.stop(); - const coldHostRoot=path.join(temporary,'cold-host'),external=path.join(coldHostRoot,'external');fs.mkdirSync(external,{recursive:true});const clone=path.join(external,'clone'); - const git=(...args)=>execFileSync('git',args,{env:gitEnv,stdio:['ignore','pipe','pipe']});git('init','-q','--template=',source);git('-C',source,'add','.');git('-C',source,'-c','user.name=Disposable native QA','-c','user.email=qa@example.invalid','-c','commit.gpgsign=false','-c','core.hooksPath=/dev/null','commit','-qm','Inert native probe science and exact failed phase');git('-c','core.hooksPath=/dev/null','clone','-q','--no-hardlinks','--template=',source,clone);if(fs.existsSync(path.join(source,'artifacts')))fs.cpSync(path.join(source,'artifacts'),path.join(clone,'artifacts'),{recursive:true});assert.deepEqual(snapshot(clone),canonical); - fs.rmSync(path.join(temporary,'source-host'),{recursive:true,force:true}); - const beforeCold=nativeRequests().length;await start(coldHostRoot,coldDsn,true);await navigate();await fill('#project-files-directory','clone');await activate('#project-files-open');await settled();assert.deepEqual((await state()).project,saved);assert.equal(nativeRequests().length,beforeCold); - await activate('#project-execution-health');await until(()=>evaluate('document.getElementById("project-execution-summary").textContent.includes("0 original current native phases")'),'cold phases remain historical');assert.equal(await evaluate('document.querySelectorAll("#project-native-phases button").length'),0); - await activate('#project-native-graphs');await settled();assert.equal(await evaluate('document.querySelectorAll("#project-native-graph option").length'),1);coldFacts=await fixture.command('facts');assert.equal(coldFacts.portable_phase_count,sourceFacts.portable_phase_count);assert.ok(coldFacts.portable_phase_count>=2);assert.deepEqual(coldFacts.go_events,[]);assert.deepEqual(coldFacts.forbidden,[]);assert.equal(coldFacts.workspace_runs,0);assert.deepEqual(snapshot(clone),canonical); - await capture(390,'cold');await capture(1440,'cold');assert.deepEqual(errors,[]);assert.equal(httpErrors.length,2,JSON.stringify(httpErrors));assert.ok(httpErrors.some(value=>value.status===409&&value.url.endsWith('/retry')));assert.ok(httpErrors.some(value=>value.status===503&&value.url.endsWith('/preflight')));verifySource();assert.equal(hash(fs.readFileSync(__filename)),testSha); - check('Cold keyboard Open on distinct role denied source CONNECT preserves canonical native facts but no local phases/Run owner; removed original host is not followed and 390/1440 layouts fit'); - fs.writeFileSync(path.join(report,'receipt.json'),JSON.stringify({status:'pass',source_stable:true,checks,material,test_sha256:testSha,isolation,bounds,project_id:project,source_facts:sourceFacts,cold_facts:coldFacts,browser_runtime_errors:errors,expected_http_errors:httpErrors,native_requests:nativeRequests(),fixture:'Actual app handler/PG/Chromium and explicit qualified CPU interpreter; real source/release, one native probe, real deferred SQL ACK fault and no second GO; no model fit or training Run. Test-only stdin fixture commands seed authored data and wrap the actual before_commit hook; native owners unmocked. Cold host forbids process preparation/Runs construction as assertions.'},null,2)+'\n');console.log('Report '+path.join(report,'receipt.json')); -})().catch(async error=>{ - fs.writeFileSync(path.join(report,'failure-receipt.json'),JSON.stringify({status:'failed',error:error.message,checks,material,test_sha256:testSha,isolation,bounds,source_facts:sourceFacts,cold_facts:coldFacts,browser_runtime_errors:errors,http_errors:httpErrors,native_requests:requests.filter(value=>value.url.includes('/execution/native/'))},null,2)+'\n');console.error(error);console.error('Server:',serverErrors);if(evaluate)try{console.error('UI:',await evaluate('document.body.innerText'));}catch(_){}process.exitCode=1; -}).finally(async()=>{ - session?.close();socket?.close();for(const host of fixtures.reverse())try{await host.stop();}catch(error){console.error('Fixture cleanup failed:',error.message);process.exitCode=1;}for(const child of children.reverse())await stop(child);process.env.TULDOK_DATABASE_URL=sourceDsn;fs.rmSync(temporary,{recursive:true,force:true}); -}); diff --git a/tests/browser_pumas_typed_server.py b/tests/browser_pumas_typed_server.py index 6d3d46f4..fc0b6f7e 100644 --- a/tests/browser_pumas_typed_server.py +++ b/tests/browser_pumas_typed_server.py @@ -23,8 +23,8 @@ def configure(value):state['content']=value['content'];state['mode']='success' origin='source-derived HTTP fixture; not native Pumas' original=app.make_handler -def make_handler(dataset, observer=None, *, transfer_controller=None): - class Handler(original(dataset, observer, transfer_controller=transfer_controller)): +def make_handler(dataset, observer=None): + class Handler(original(dataset, observer)): def _post(self): if self.path=='/api/test/pumas-control': body=json.loads(self.rfile.read(int(self.headers['Content-Length'])));configure(body);return self.reply({'configured':True}) diff --git a/tests/browser_text_classification_proposals_server.py b/tests/browser_text_classification_proposals_server.py index 85957ff0..a98c15a7 100644 --- a/tests/browser_text_classification_proposals_server.py +++ b/tests/browser_text_classification_proposals_server.py @@ -41,8 +41,8 @@ def instrumented_start(self, body): original_handler = app.make_handler -def instrumented_handler(dataset, observer=None, *, transfer_controller=None): - class Handler(original_handler(dataset, observer, transfer_controller=transfer_controller)): +def instrumented_handler(dataset, observer=None): + class Handler(original_handler(dataset, observer)): def _get(self): if self.path == '/api/test/classification-dispatch': with admission_lock: diff --git a/tests/model_portfolio_fixture.cjs b/tests/model_portfolio_fixture.cjs deleted file mode 100644 index cb63135a..00000000 --- a/tests/model_portfolio_fixture.cjs +++ /dev/null @@ -1,16 +0,0 @@ -'use strict'; -// Literal presentation-document fixtures, independent of the decoder. -const crypto=require('node:crypto'); -const hash=value=>crypto.createHash('sha256').update(value).digest('hex'); -const project='a'.repeat(32),path='notes/00-methods.portfolio.json'; -const summary={method:'A small pressure correction model.',purpose:'Measure one pressure correction.',experiment:'Two retained training scenes.',outcome:'Retained diagnostic result; not a rollout qualification.',lesson:'Compare work and accuracy on the same cases.',reproduction:'Use the retained source recipe; clean retraining remains pending.'}; -const cardText=Object.values(summary).join('\n\n')+'\nOriginal receipt bytes remain here.\n'; -const ref=(path,text)=>({file_id:hash(project+'\0note\0'+path),path,revision:2,sha256:hash(text)}); -const first={id:'fit-first',label:'First model',group_id:'pressure',aliases:['C107'],review:'source_reviewed',card:ref('notes/first.md',cardText),summary}; -const second={id:'fit-second',label:'Second model',group_id:'pressure',aliases:['C106'],review:'review_pending',card:ref('notes/second.md','Original pending card.\n'),summary:null}; -const document={format:'project_model_portfolio_v1',project_id:project,title:'Retained fit guide',description:'Authored retrospective organization; original Trial history is unchanged.',authorship:'retrospective',groups:[{id:'pressure',label:'Pressure methods',parent:null,description:'Pressure requests, not complete simulation steps.'}],models:[first,second],relationships:[{from:first.id,to:second.id,kind:'comparison',explanation:'Authored comparison with the earlier control.',evidence_model:first.id,excerpt:summary.lesson}]}; -const result=(model,text)=>({id:model.card.file_id,project_id:project,kind:'note',path:model.card.path,version:{revision:2,sha256:hash(text),bytes:Buffer.byteLength(text),text,actor_id:'b'.repeat(32),adopted_at:'2026-10-25T00:00:00+00:00'}}); -const cards=[result(first,cardText),result(second,'Original pending card.\n')]; -const raw=JSON.stringify(document),guideRef=ref(path,raw),guide={...result({card:guideRef},raw),version:{...result({card:guideRef},raw).version,revision:1}}; -const inspection={id:guideRef.file_id,kind:'note',path,revision:1,expected_sha256:guideRef.sha256,expected_bytes:Buffer.byteLength(raw),observed_sha256:guideRef.sha256,observed_bytes:Buffer.byteLength(raw),state:'unchanged',reason:null}; -module.exports={project,document,summary,cards,guide,inspection}; diff --git a/tests/test_agent_api.py b/tests/test_agent_api.py index 004121b4..2c9c1f70 100644 --- a/tests/test_agent_api.py +++ b/tests/test_agent_api.py @@ -284,14 +284,6 @@ def test_absolute_header_deadline_includes_trickle(self): with self.assertRaises(api.AgentAPIError): client.call('data.query',{}) self.assertLess(time.monotonic()-start,1) - def test_owner_transport_keeps_the_selected_absolute_wait_and_never_retries(self): - with server('trickle') as (endpoint,calls): - client=api.ProjectFilesOwnerClient(endpoint,TOKEN,CATALOG,timeout=.15) - start=time.monotonic() - with self.assertRaises(api.AgentAPIError):client._request('GET','/api/workbench/records') - self.assertLess(time.monotonic()-start,1) - self.assertEqual(len(calls),1) - class OutputTests(unittest.TestCase): @unittest.skipUnless(HAS_JSONSCHEMA, 'Optional agent jsonschema dependency is not installed.') diff --git a/tests/test_measurement_comparison.py b/tests/test_measurement_comparison.py deleted file mode 100644 index 16418875..00000000 --- a/tests/test_measurement_comparison.py +++ /dev/null @@ -1,119 +0,0 @@ -"""Scientific composition of real retained scalar tables, no native transport.""" -import copy -import struct -import unittest -from unittest.mock import patch - -import retained_measurements as owner -from retained_measurements import MeasurementComparison, MeasurementTable, encode -from test_retained_measurements import fixture, source -from workbench import WorkbenchError - - -def partition(subject): - document = fixture() - document['title'] = 'Original partition ' + subject - document['subjects'] = [item for item in document['subjects'] if item['id'] == subject] - document['observations'] = [row for row in document['observations'] if row['subject_id'] == subject] - return document - - -def selected(document, origin='a'*32): - table = MeasurementTable(encode(document)) - return dict(origin_catalog_id=origin, packet_sha256=table.sha256), table - - -class ComparisonTests(unittest.TestCase): - def setUp(self): - self.inputs = [selected(partition('a')), selected(partition('b'))] - self.comparison = MeasurementComparison(self.inputs) - - def test_complete_maxima_and_missing_denominators_keep_original_packet(self): - result = self.comparison.read('error') - self.assertEqual(len(result['subjects']), 2) - self.assertEqual(result['case_count'], 2) - self.assertEqual(result['observation_count'], 8) - self.assertEqual([s['maximum']['value'] for s in result['query']['summary']], [2e-15, .02]) - for row in result['query']['rows']: - locator, original = next(item for item in self.inputs if item[0] == row['source']) - evidence = original.inspect(row['id']) - self.assertEqual(struct.pack('!d', row['value']), struct.pack('!d', evidence['scalar_evidence']['value'])) - missing = self.comparison.read('latency')['query'] - self.assertEqual(missing['total'], 4) - self.assertEqual([s['states'] for s in missing['summary']], [ - dict(measured=0, failed=0, unsupported=0, unavailable=2), - dict(measured=0, failed=1, unsupported=0, unavailable=1)]) - self.assertTrue(all(s['maximum'] is None for s in missing['summary'])) - - def test_global_pages_span_packets_without_changing_maxima(self): - full = self.comparison.read('error')['query'] - rows = [] - for offset in range(5): - page = self.comparison.read('error', offset=offset, limit=1)['query'] - self.assertEqual(page['summary'], full['summary']) - self.assertEqual(page['total'], 4) - rows.extend(page['rows']) - self.assertEqual(rows, full['rows']) - self.assertEqual([r['subject_id'] for r in rows], ['a','a','b','b']) - ordered = self.comparison.read('error', subject_ids=['b','a'])['query'] - self.assertEqual([s['subject_id'] for s in ordered['summary']], ['b','a']) - - def test_density_domain_device_and_unknown_filters_are_separate(self): - density = self.comparison.read('error', filters={'cpm':16})['query'] - domain = self.comparison.read('error', filters={'grid_x':16})['query'] - self.assertEqual([s['maximum']['value'] for s in density['summary']], [1e-17,.01]) - self.assertEqual([s['maximum']['value'] for s in domain['summary']], [2e-15,.02]) - cpu = self.comparison.read('error', filters={'device':'CPU'})['query'] - self.assertEqual([s['count'] for s in cpu['summary']], [0,2]) - unknown = self.comparison.read('error', filters={'device':None})['query'] - self.assertEqual(unknown['total'], 0) - self.assertTrue(all(s['maximum'] is None for s in unknown['summary'])) - - def test_changed_original_case_evidence_or_dimension_meaning_refuses_comparison(self): - changed = partition('b') - context = fixture()['sources'][0] - import base64, json - original = json.loads(base64.b64decode(context['data_base64'])) - original['different_original_case'] = True - changed['sources'][0] = source('context', original) - for document in (changed, partition('b')): - if document is not changed: - document['dimensions'][0]['units'] = 'different units' - with self.assertRaises(WorkbenchError) as error: - MeasurementComparison([self.inputs[0], selected(document)]) - self.assertEqual(error.exception.code, 'incompatible') - - def test_overlapping_subjects_and_repeated_sources_are_explicit_errors(self): - with self.assertRaises(WorkbenchError): MeasurementComparison([self.inputs[0], self.inputs[0]]) - other = partition('a'); other['title'] = 'Different packet, same subject' - with self.assertRaises(WorkbenchError) as error: - MeasurementComparison([self.inputs[0], selected(other)]) - self.assertEqual(error.exception.code, 'conflict') - - def test_bounds_and_invalid_selections_never_return_partial_results(self): - for constant, maximum in [('MAX_COMPARISON_BYTES', 1), ('MAX_COMPARISON_SUBJECTS', 1), ('MAX_COMPARISON_ROWS', 7)]: - with patch.object(owner, constant, maximum), self.assertRaises(WorkbenchError): - MeasurementComparison(self.inputs) - with self.assertRaises(WorkbenchError): MeasurementComparison(self.inputs * 9) - for arguments in ({'subject_ids':[['bad']]}, {'subject_ids':[]}, {'subject_ids':['a','a']}, - {'subject_ids':['missing']}, {'offset':True}, {'limit':101}): - with self.subTest(arguments=arguments), self.assertRaises(WorkbenchError): - self.comparison.read('error', **arguments) - with self.assertRaises(WorkbenchError): self.comparison.read(filters={}) - - def test_packet_and_combined_observation_budgets_are_separate(self): - # Both real source tables have four observations. A packet limit of - # four still permits their complete eight-observation comparison. - with patch.object(owner,'MAX_ROWS',4),patch.object(owner,'MAX_COMPARISON_ROWS',8,create=True): - self.assertEqual(MeasurementComparison(self.inputs).read()['observation_count'],8) - with self.assertRaises(WorkbenchError):MeasurementTable(encode(fixture())) - with patch.object(owner,'MAX_COMPARISON_ROWS',7,create=True),self.assertRaises(WorkbenchError): - MeasurementComparison(self.inputs) - - def test_returned_metadata_and_query_values_have_no_mutable_owner_alias(self): - expected = self.comparison.read('error') - result = self.comparison.read('error') - result['query']['metric']['label'] = 'Changed' - result['query']['summary'][0]['states']['measured'] = 99 - result['subjects'][0]['source']['origin_catalog_id'] = 'b'*32 - self.assertEqual(self.comparison.read('error'), expected) diff --git a/tests/test_project_artifacts.py b/tests/test_project_artifacts.py deleted file mode 100644 index 87caa214..00000000 --- a/tests/test_project_artifacts.py +++ /dev/null @@ -1,514 +0,0 @@ -"""Exact artifact custody on real files, processes and disposable PostgreSQL.""" -import copy -from contextlib import contextmanager -import errno -import hashlib -import json -import os -from pathlib import Path -import shutil -import stat -import subprocess -import sys -import tempfile -import unittest -from unittest.mock import patch - -sys.path.insert(0, str(Path(__file__).resolve().parents[1])) -import project_artifacts as artifact_module -from project_artifacts import ProjectArtifacts, ProjectArtifactError, validate_declaration -from project_store import ProjectStore, ProjectStoreError - - -def declaration(raw): - return dict(format='project_artifact_v1', sha256=hashlib.sha256(raw).hexdigest(), bytes=len(raw)) - - -def envelope(value): - return dict(family='project_artifact', id=value['sha256'], document=value) - - -def request(value): - return hashlib.sha256(json.dumps(value, sort_keys=True).encode()).hexdigest() - - -class _ArtifactFixture: - def setUp(self): - self.tmp = tempfile.TemporaryDirectory(prefix='tuldok-artifacts-') - self.addCleanup(self.tmp.cleanup) - self.path = Path(self.tmp.name) - self.project = self.path / 'project' - self.store = ProjectStore.create(self.project, 'Artifact custody', 'new', 'a' * 64) - self.addCleanup(lambda: self.store.close()) - self.artifacts = ProjectArtifacts(self.store) - self.addCleanup(lambda: self.artifacts.close()) - - def payload(self, value): - return self.project / 'artifacts/sha256' / value['sha256'] - - def assert_code(self, code, function, *args, **kwargs): - with self.assertRaises(ProjectStoreError) as caught: - function(*args, **kwargs) - self.assertEqual(caught.exception.code, code) - return caught.exception - - def commit(self, values, key='payloads'): - records = [envelope(value) for value in values] - return self.store.commit(records, self.store.snapshot()['checkpoint'], key, request(records)) - -class ProjectArtifactTests(_ArtifactFixture, unittest.TestCase): - def test_copy_group_keeps_exact_independent_snapshots_with_two_source_closure_checks(self): - raws = [b'first exact output', b'second exact output'] - values = [declaration(raw) for raw in raws] - for raw, value in zip(raws, values): - self.artifacts.publish_bytes(raw, value) - self.commit(values) - target = self.path / 'copy' - with ProjectStore.create(target, 'Copy', 'copy', 'b' * 64) as store, ProjectArtifacts(store) as destination: - publish = destination.publish_fd - def mutate_source_after_snapshot(fd, value, **options): - # A mutable original source must not be the fd consumed by the - # destination. Its already-verified snapshot stays independent. - original = self.payload(value) - original.unlink() - original.write_bytes(b'changed after verified capture') - return publish(fd, value, **options) - with patch.object(destination, 'publish_fd', side_effect=mutate_source_after_snapshot): - with patch.object(self.store, '_current', wraps=self.store._current) as checks: - self.artifacts.copy_many_to(destination, values) - self.assertEqual(checks.call_count, 2) - for raw, value in zip(raws, values): - copied = target / 'artifacts/sha256' / value['sha256'] - self.assertEqual(copied.read_bytes(), raw) - self.assertEqual(copied.stat().st_nlink, 1) - self.assertNotEqual(copied.stat().st_ino, self.payload(value).stat().st_ino) - - def test_copy_group_uses_verified_records_and_verification_rejects_later_corruption(self): - value = declaration(b'present') - self.artifacts.publish_bytes(b'present', value) - self.commit([value]) - manifest = json.loads((self.project / '.tuldok/project.json').read_bytes()) - record = self.project / '.tuldok' / manifest['inventory'][0]['path'] - with ProjectStore.create(self.path / 'copy', 'Copy', 'copy', 'b' * 64) as store, ProjectArtifacts(store) as destination: - publish = destination.publish_fd - def corrupt_after_copy(*args, **options): - result = publish(*args, **options) - record.write_bytes(b'{"corrupt":true}\n') - return result - with patch.object(destination, 'publish_fd', side_effect=corrupt_after_copy): - # The copy uses the verified declaration, never the corrupt bytes. - self.artifacts.copy_many_to(destination, [value]) - self.assert_code('stale', self.store.verify_records) - - def test_copy_group_prevalidates_inventory_and_preserves_missing_payload_failure(self): - value, missing = declaration(b'present'), declaration(b'missing') - self.artifacts.publish_bytes(b'present', value) - self.commit([value, missing]) - with ProjectStore.create(self.path / 'copy', 'Copy', 'copy', 'b' * 64) as store, ProjectArtifacts(store) as destination: - with patch.object(destination, 'publish_fd', wraps=destination.publish_fd) as publish: - self.assert_code('invalid', self.artifacts.copy_many_to, destination, [value, dict(missing, bytes=True)]) - publish.assert_not_called() - self.assert_code('unavailable', self.artifacts.copy_many_to, destination, [value, missing]) - self.assertEqual(destination.status(value)['state'], 'verified') - self.assertEqual(destination.status(missing)['state'], 'missing') - - def test_status_group_retains_exact_hash_observations_with_two_closure_checks(self): - values = [declaration(b'present'), declaration(b'missing'), declaration(b'correct')] - self.artifacts.publish_bytes(b'present', values[0]) - self.artifacts.publish_bytes(b'correct', values[2]) - self.commit(values) - self.payload(values[2]).unlink() - self.payload(values[2]).write_bytes(b'changed') - expected = [self.artifacts.status(value) for value in values] - with patch.object(self.store, '_current', wraps=self.store._current) as checks: - actual = self.artifacts.status_many(values) - self.assertEqual(actual, expected) - self.assertEqual([item['state'] for item in actual], ['verified', 'missing', 'corrupt']) - self.assertEqual(checks.call_count, 2) - self.assertEqual(actual[0]['observed_sha256'], values[0]['sha256']) - self.assertEqual(actual[2]['observed_sha256'], hashlib.sha256(b'changed').hexdigest()) - - def test_status_group_uses_verified_records_and_verification_rejects_later_corruption(self): - value = declaration(b'present') - self.artifacts.publish_bytes(b'present', value) - self.commit([value]) - manifest = json.loads((self.project / '.tuldok/project.json').read_bytes()) - record = self.project / '.tuldok' / manifest['inventory'][0]['path'] - original = self.artifacts._source - @contextmanager - def corrupt_after_observation(*args): - with original(*args) as source: - yield source - record.write_bytes(b'{"corrupt":true}\n') - with patch.object(self.artifacts, '_source', side_effect=corrupt_after_observation): - self.artifacts.status_many([value]) - self.assert_code('stale', self.store.verify_records) - - def test_status_group_rejects_checkpoint_change_and_unsafe_aliases(self): - value = declaration(b'present') - self.artifacts.publish_bytes(b'present', value) - self.commit([value]) - original = self.artifacts._source - @contextmanager - def change_checkpoint(*args): - with original(*args) as source: - yield source - self.commit([], key='new-checkpoint') - with patch.object(self.artifacts, '_source', side_effect=change_checkpoint): - self.assert_code('stale', self.artifacts.status_many, [value]) - os.link(self.payload(value), self.path / 'outside-alias') - self.assert_code('invalid', self.artifacts.status_many, [value]) - - def test_presence_batch_matches_individual_observations_with_two_closure_checks(self): - values=[declaration(b'present'),declaration(b'missing'),declaration(b'other')] - self.artifacts.publish_bytes(b'present',values[0]) - self.commit(values) - expected=[self.artifacts.inspect(value) for value in values] - with patch.object(self.store,'_current',wraps=self.store._current) as checks: - actual=self.artifacts.inspect_many(values) - self.assertEqual(actual,expected) - self.assertEqual(checks.call_count,2) - self.assertTrue(all(v['observed_sha256'] is None for v in actual)) - - def test_presence_batch_uses_verified_records_and_verification_rejects_later_corruption(self): - value=declaration(b'present') - self.artifacts.publish_bytes(b'present',value) - self.commit([value]) - manifest=json.loads((self.project/'.tuldok/project.json').read_text()) - record=self.project/'.tuldok'/manifest['inventory'][0]['path'] - original=self.artifacts._source - @contextmanager - def corrupt_after_observation(*args): - with original(*args) as source: - yield source - record.write_bytes(b'{"corrupt":"outside canonical membership"}\n') - with patch.object(self.artifacts,'_source',side_effect=corrupt_after_observation): - self.artifacts.inspect_many([value]) - self.assert_code('stale',self.store.verify_records) - - def test_presence_batch_detects_checkpoint_change_and_rejects_unsafe_aliases(self): - value=declaration(b'present') - self.artifacts.publish_bytes(b'present',value) - self.commit([value]) - original=self.artifacts._source - @contextmanager - def change_checkpoint(*args): - with original(*args) as source: - yield source - self.commit([],key='new-checkpoint') - with patch.object(self.artifacts,'_source',side_effect=change_checkpoint): - self.assert_code('stale',self.artifacts.inspect_many,[value]) - alias=self.path/'outside-alias' - os.link(self.payload(value),alias) - self.assert_code('invalid',self.artifacts.inspect_many,[value]) - - def test_exact_payload_declaration_roundtrip_copy_and_missing_metadata_remain_distinct(self): - raw = b'Unique source\x00annotation\xff\r\n' - value = declaration(raw) - self.assertEqual(self.artifacts.inspect(value)['state'], 'missing') - self.assertEqual(self.artifacts.status(value)['state'], 'missing') - self.assertEqual(self.artifacts.publish_bytes(raw, value), value) - self.assertEqual(self.artifacts.inspect(value)['state'], 'unverified') - self.assertEqual(self.artifacts.status(value), dict(state='verified', expected_sha256=value['sha256'], - expected_bytes=len(raw), observed_sha256=value['sha256'], observed_bytes=len(raw))) - self.assertEqual(self.artifacts.read_blob({k: value[k] for k in ('sha256', 'bytes')}), raw) - checkpoint = self.commit([value]) - self.assertEqual(checkpoint['records'], [envelope(value)]) - self.artifacts.close() - self.store.close() - copied = self.path / 'copied' - shutil.copytree(self.project, copied) - self.project.rename(self.path / 'moved') - with ProjectStore.open(copied) as reopened, ProjectArtifacts(reopened) as owner: - self.assertEqual(reopened.snapshot(), checkpoint) - self.assertEqual(owner.status(value)['state'], 'verified') - (copied / 'artifacts/sha256' / value['sha256']).unlink() - self.assertEqual(owner.status(value)['state'], 'missing') - self.assertEqual(reopened.snapshot(), checkpoint) - self.assert_code('unavailable', owner.read_blob, {k: value[k] for k in ('sha256', 'bytes')}) - - def test_intrinsic_declaration_rejects_policy_paths_future_formats_and_bad_bounds(self): - value = declaration(b'bytes') - for invalid in [dict(value, role='model'), dict(value, path='/origin/secret'), dict(value, bytes=True), - dict(value, bytes=-1), dict(value, bytes=2 ** 63), dict(value, sha256='../escape'), - dict(value, format='project_artifact_vgarbage')]: - with self.subTest(invalid=invalid): - self.assert_code('invalid', validate_declaration, invalid) - self.assert_code('unsupported', validate_declaration, dict(value, format='project_artifact_v2')) - self.assert_code('invalid', self.artifacts.publish_bytes, b'other', value) - self.assert_code('too_large', self.artifacts.publish_bytes, b'bytes', value, maximum_bytes=4) - # Intrinsic identity admits large scientific payload sizes without a - # runtime-specific global cap. Only the consuming owner selects a bound. - large = dict(value, bytes=8 * 1024 ** 3) - self.assertEqual(validate_declaration(large), large) - empty = declaration(b'') - self.artifacts.publish_bytes(b'', empty) - self.assertEqual(self.artifacts.read_blob({k: empty[k] for k in ('sha256', 'bytes')}), b'') - - def test_publish_fd_streams_without_changing_source_offset_and_respects_caller_bound(self): - raw = (b'exact source bytes\x00' * 90_000) - value = declaration(raw) - source = self.path / 'source.bin' - source.write_bytes(raw) - fd = os.open(source, os.O_RDONLY) - self.addCleanup(lambda: os.close(fd)) - os.lseek(fd, 7, os.SEEK_SET) - self.assert_code('too_large', self.artifacts.publish_fd, fd, value, maximum_bytes=len(raw) - 1) - self.artifacts.publish_fd(fd, value, maximum_bytes=len(raw)) - self.assertEqual(os.lseek(fd, 0, os.SEEK_CUR), 7) - self.assertEqual(self.payload(value).read_bytes(), raw) - - def test_captured_read_proof_survives_source_edits_and_returned_fd_is_read_only(self): - raw = b'Original source measurement' - value = declaration(raw) - self.artifacts.publish_bytes(raw, value) - with self.artifacts.open_verified(value) as source: - self.assertEqual(os.fstat(source).st_nlink, 0) - path = self.payload(value) - path.chmod(0o600) - path.write_bytes(b'Changed source measurement!') - self.assertEqual(os.read(source, len(raw) + 1), raw) - with self.assertRaises(OSError): - os.write(source, b'No mutation capability') - self.assertEqual(self.artifacts.status(value)['state'], 'corrupt') - self.assertFalse(list((self.project / '.tuldok-local/artifact-snapshots').iterdir())) - - def test_source_changed_during_capture_is_rejected_before_final_publication(self): - raw = b'a' * (artifact_module.CHUNK_BYTES + 20) - value = declaration(raw) - source = self.path / 'source.bin' - source.write_bytes(raw) - fd = os.open(source, os.O_RDONLY) - self.addCleanup(lambda: os.close(fd)) - pread = artifact_module.os.pread - changed = False - def change_after_read(descriptor, size, offset): - nonlocal changed - result = pread(descriptor, size, offset) - if descriptor == fd and not changed: - changed = True - source.write_bytes(b'b' * len(raw)) - return result - with patch.object(artifact_module.os, 'pread', side_effect=change_after_read): - self.assert_code('stale', self.artifacts.publish_fd, fd, value) - self.assertFalse(self.payload(value).exists()) - self.assertEqual(self.store.snapshot()['records'], []) - - def test_explicit_runtime_resolution_is_not_canonical_and_never_falls_back(self): - raw = b'Externally held unique original' - value = declaration(raw) - external = self.path / 'external' - external.mkdir() - (external / 'nested').mkdir() - source = external / 'nested/input.bin' - source.write_bytes(raw) - fd = os.open(external, artifact_module.DIR_FLAGS) - bindings = {value['sha256']: dict(root_fd=fd, root_path=external, relative='nested/input.bin')} - resolved = ProjectArtifacts(self.store, resolutions=bindings) - os.close(fd) - self.addCleanup(resolved.close) - before = self.store.snapshot() - self.assertEqual(resolved.status(value)['state'], 'verified') - self.assertEqual(resolved.read_blob({k: value[k] for k in ('sha256', 'bytes')}), raw) - self.artifacts.publish_bytes(raw, value) - source.write_bytes(b'Wrong externally selected bytes') - self.assertEqual(resolved.status(value)['state'], 'corrupt') - self.assert_code('invalid', resolved.read_blob, {k: value[k] for k in ('sha256', 'bytes')}) - self.assertEqual(self.store.snapshot(), before) - displaced = external.with_name('displaced') - external.rename(displaced) - victim = self.path / 'victim' - victim.mkdir() - external.symlink_to(victim, target_is_directory=True) - self.assert_code('invalid', resolved.status, value) - self.assertEqual(list(victim.iterdir()), []) - - def test_symlink_special_hardlink_alias_and_unsafe_payload_parent_reject(self): - raw = b'Unique bytes' - value = declaration(raw) - self.artifacts.publish_bytes(raw, value) - path = self.payload(value) - target = self.path / 'target' - target.write_bytes(raw) - for special in ('symlink', 'fifo', 'hardlink'): - with self.subTest(special=special): - path.unlink() - if special == 'symlink': - path.symlink_to(target) - elif special == 'fifo': - os.mkfifo(path) - else: - os.link(target, path) - self.assert_code('invalid', self.artifacts.status, value) - path.unlink() - (self.project / 'artifacts/sha256').rmdir() - (self.project / 'artifacts/sha256').symlink_to(self.path, target_is_directory=True) - self.assert_code('invalid', self.artifacts.publish_bytes, raw, value) - self.assertEqual(target.read_bytes(), raw) - self.assertFalse((self.path / value['sha256']).exists()) - - def test_existing_corrupt_payload_is_never_overwritten(self): - raw = b'Exact original' - value = declaration(raw) - self.artifacts.publish_bytes(raw, value) - self.payload(value).chmod(0o600) - self.payload(value).write_bytes(b'Broken content') - self.assert_code('invalid', self.artifacts.publish_bytes, raw, value) - self.assertEqual(self.payload(value).read_bytes(), b'Broken content') - - def test_payload_fsync_failure_reports_unknown_retains_bytes_and_retry_barriers(self): - raw = b'Publication survives missing reply' - value = declaration(raw) - original = artifact_module.os.fsync - def fail_published_directory(fd): - info = os.fstat(fd) - if stat.S_ISDIR(info.st_mode) and self.payload(value).exists(): - raise OSError(errno.EIO, 'payload parent sync fault') - return original(fd) - with patch.object(artifact_module.os, 'fsync', side_effect=fail_published_directory): - self.assert_code('unknown', self.artifacts.publish_bytes, raw, value) - self.assertEqual(self.store.snapshot()['records'], []) - self.assertEqual(self.payload(value).read_bytes(), raw) - self.artifacts.publish_bytes(raw, value) - self.assertEqual(self.artifacts.status(value)['state'], 'verified') - - def test_no_auto_execution_and_store_capabilities_detect_replaced_root(self): - script = b'raise RuntimeError("Artifact source must never run")\n' - value = declaration(script) - with patch.object(subprocess, 'Popen', side_effect=AssertionError('No artifact execution')): - self.artifacts.publish_bytes(script, value) - self.artifacts.read_blob({k: value[k] for k in ('sha256', 'bytes')}) - with self.store.root_directory() as root: - self.assertTrue(stat.S_ISDIR(os.fstat(root).st_mode)) - moved = self.project.with_name('moved') - self.project.rename(moved) - self.project.mkdir() - self.assert_code('stale', self.artifacts.status, value) - - def test_fixed_family_format_pairs_roundtrip_and_preserve_original_origin_values(self): - records = [dict(family=family, id='a' * 32 + '.' + 'b' * 32, - document=dict(format=format_name, origin_catalog_id='c' * 32, - original_hashed_text=' { exact old text }\r\n')) - for family, format_name in (('workbench_record', 'workbench_record_v1'), - ('model_material', 'retained_model_material_v1'), ('run_history', 'project_run_history_v1'), - ('project_operation', 'project_operation_v1'), ('generation_history', 'project_generation_history_v1'))] - committed = self.store.commit(records, self.store.snapshot()['checkpoint'], 'families', request(records)) - self.store.close() - self.store = ProjectStore.open(self.project) - self.assertEqual(self.store.snapshot(), committed) - bad = dict(family='run_history', id='a', document={'format': 'workbench_record_v1'}) - self.assert_code('unsupported', self.store.commit, [bad], committed['checkpoint'], 'wrong', 'b' * 64) - - def test_real_process_interruptions_keep_published_bytes_without_partial_checkpoint(self): - code = r''' -import hashlib,json,os,sys -import project_artifacts as m -from project_store import ProjectStore -root,window=sys.argv[1:] -store=ProjectStore.open(root) -owner=m.ProjectArtifacts(store) -raw=b'Exact unique bytes across process interruption' -decl={'format':'project_artifact_v1','sha256':hashlib.sha256(raw).hexdigest(),'bytes':len(raw)} -write,rename=m._write,m._rename_noreplace -def kill_write(*args): - write(*args) - if window=='stage':os._exit(76) -def kill_rename(*args): - rename(*args) - if window=='rename':os._exit(76) -m._write=kill_write -m._rename_noreplace=kill_rename -owner.publish_bytes(raw,decl) -if window=='durable':os._exit(76) -records=[{'family':'project_artifact','id':decl['sha256'],'document':decl}] -digest=hashlib.sha256(json.dumps(records,sort_keys=True).encode()).hexdigest() -store.commit(records,store.snapshot()['checkpoint'],'artifact-edit',digest) -if window=='checkpoint':os._exit(76) -raise AssertionError('Fault not reached') -''' - raw = b'Exact unique bytes across process interruption' - value = declaration(raw) - self.artifacts.close() - self.store.close() - for window in ('stage', 'rename', 'durable', 'checkpoint'): - with self.subTest(window=window): - destination = self.path / ('kill-' + window) - shutil.copytree(self.project, destination) - child = subprocess.run([sys.executable, '-c', code, str(destination), window], - cwd=Path(artifact_module.__file__).parent, capture_output=True, text=True, timeout=10) - self.assertEqual(child.returncode, 76, child.stderr) - with ProjectStore.open(destination) as reopened, ProjectArtifacts(reopened) as owner: - snapshot = reopened.snapshot() - self.assertEqual(snapshot['records'], [envelope(value)] if window == 'checkpoint' else []) - self.assertEqual(owner.status(value)['state'], 'missing' if window == 'stage' else 'verified') - replay = reopened.reconcile('artifact-edit', request([envelope(value)])) - self.assertEqual(replay is not None, window == 'checkpoint') - - -@unittest.skipUnless(os.environ.get('TULDOK_DATABASE_URL'), 'Requires disposable local PostgreSQL') -class ArtifactSQLCustodyTests(_ArtifactFixture, unittest.TestCase): - def setUp(self): - super().setUp() - import psycopg - from psycopg import sql - from metadata import Metadata - self.db = Metadata(self.path / 'projection') - def drop_owned_schema(): - self.db.close() - with psycopg.connect(self.db.dsn, autocommit=True) as connection: - connection.execute(sql.SQL('DROP SCHEMA {} CASCADE').format(sql.Identifier(self.db.schema))) - self.addCleanup(drop_owned_schema) - self.db.execute('CREATE TABLE artifact_custody_fixture (id integer PRIMARY KEY)') - - def _publish_through_legacy_rollback_owner(self, raw): - from immutable_assets import publish_file - legacy = self.path / 'legacy-assets' - legacy.mkdir() - folder = legacy / 'owned-attempt' - value = declaration(raw) - with publish_file(self.db, folder, 'source.bin', raw) as source: - descriptor = os.open(source, os.O_RDONLY) - try: - self.artifacts.publish_fd(descriptor, value) - finally: - os.close(descriptor) - snapshot = self.commit([value]) - return folder, value, snapshot - - def test_real_sql_rollback_callbacks_do_not_delete_canonical_payload(self): - raw = b'Unique BYTEA-derived source and annotation observation' - value = declaration(raw) - with self.assertRaisesRegex(RuntimeError, 'abort SQL'): - with self.db.transaction(): - self.db.execute('INSERT INTO artifact_custody_fixture VALUES (1)') - self._publish_through_legacy_rollback_owner(raw) - raise RuntimeError('abort SQL') - self.assertFalse((self.path / 'legacy-assets/owned-attempt').exists()) - self.assertEqual(self.db.execute('SELECT count(*) FROM artifact_custody_fixture').fetchone()[0], 0) - self.assertEqual(self.payload(value).read_bytes(), raw) - self.assertEqual(self.store.snapshot()['records'], [envelope(value)]) - self.assertIsNotNone(self.store.reconcile('payloads', request([envelope(value)]))) - - def test_actual_deferred_sql_commit_failure_retains_checkpoint_and_bytes(self): - self.db.execute("""CREATE FUNCTION artifact_custody_reject_commit() RETURNS trigger LANGUAGE plpgsql AS $$ - BEGIN RAISE EXCEPTION 'fixture commit rejection' USING ERRCODE='23514'; END $$""") - self.db.execute('''CREATE CONSTRAINT TRIGGER artifact_custody_commit_failure AFTER INSERT ON artifact_custody_fixture - DEFERRABLE INITIALLY DEFERRED FOR EACH ROW EXECUTE FUNCTION artifact_custody_reject_commit()''') - raw = b'Historical model state survives canonical-before-SQL commit' - value = declaration(raw) - with self.assertRaises(Exception): - with self.db.transaction(): - self.db.execute('INSERT INTO artifact_custody_fixture VALUES (1)') - self._publish_through_legacy_rollback_owner(raw) - self.assertFalse((self.path / 'legacy-assets/owned-attempt').exists()) - self.assertEqual(self.db.execute('SELECT count(*) FROM artifact_custody_fixture').fetchone()[0], 0) - self.store.close() - self.store = ProjectStore.open(self.project) - with ProjectArtifacts(self.store) as owner: - self.assertEqual(owner.status(value)['state'], 'verified') - self.assertEqual(self.store.snapshot()['records'], [envelope(value)]) - self.assertIsNotNone(self.store.reconcile('payloads', request([envelope(value)]))) - - -if __name__ == '__main__': - unittest.main() diff --git a/tests/test_project_candidate_clients.py b/tests/test_project_candidate_clients.py deleted file mode 100644 index 8729b39d..00000000 --- a/tests/test_project_candidate_clients.py +++ /dev/null @@ -1,58 +0,0 @@ -"""Current Candidate preparation/recovery transport proof, without a writer.""" -from types import SimpleNamespace -import unittest -from unittest.mock import Mock -import agent_api as api -import project_cli -import project_dispatch -from tuldok_client import ProjectFilesClient -from test_project_files_m4_clients import ready,bound,READ,WRITE,PROJECT,ACTOR,CP,NEXT,KEY,STAMP - -STUDY='a'*32;CANDIDATE='e'*32 -ACTIONS=('execution_study_prepare_package','execution_study_prepare_verifier','execution_study_abandon_preparation','execution_study_reconcile_preparation') -def prepared(): - return dict(state='prepared',candidate_id=CANDIDATE,trial=dict(format='trial_v1',id='b'*32,study_id=STUDY, - material=dict(kind='recipe_material',catalog_id=PROJECT,id=CP,sha256=CP),replicate=0), - graph=dict(id='f'*32,revision=1,nodes=[],edges=[]),model=dict(kind='model',catalog_id=PROJECT,id=ACTOR,revision=1,sha256=CP),runtime_snapshot_sha256=CP) -def abandonment(): - return dict(format='project_candidate_preparation_abandon_v1',origin_catalog_id=PROJECT,study_id=STUDY, - preparation_key=KEY,preparation_operation='study_execution.prepare_package',input_sha256=CP, - candidate=dict(kind='candidate',catalog_id=PROJECT,id=CANDIDATE,sha256=NEXT),actor_id=ACTOR, - reason='Explicit retained scientific reason',observed_checkpoint=CP,occurred_at=STAMP,state='abandoned') -def client(value): - raw=ready(dict(status=200,result=bound(value)),owner=True) - raw._selected.update({'project_files.'+action:1 for action in ACTIONS});return raw -class CandidateClients(unittest.TestCase): - def test_fixed_inputs_consumers_and_no_implicit_grant_or_admission(self): - for action in ACTIONS: - name='project_files.'+action;self.assertIn(name,api.PROJECT_FILES_M3) - self.assertTrue(callable(getattr(ProjectFilesClient(Mock()),action))) - project_cli.parser().parse_args(['--config','/not-read','file-'+action.replace('_','-'),'--arguments','/not-read']) - self.assertEqual(api.contract(name)['authority'],'owner') - common=dict(WRITE,study_id=STUDY,revision=1,candidate_id=CANDIDATE,root='fixture',directory='a'*120,runtime_snapshot_sha256=CP) - api.validate_arguments('project_files.execution_study_prepare_package',common) - for change in ({'directory':'a'*121},{'root':'a'*65},{'approval_id':ACTOR},{'launch':True}): - with self.assertRaises(api.AgentAPIError):api.validate_arguments('project_files.execution_study_prepare_package',{**common,**change}) - args=dict(binding=READ['binding'],expected_checkpoint=CP,study_id=STUDY,preparation_key='k') - api.validate_arguments('project_files.execution_study_reconcile_preparation',args) - with self.assertRaises(api.AgentAPIError):api.validate_arguments('project_files.execution_study_reconcile_preparation',dict(args,request_key=KEY)) - self.assertEqual(api.contract('project_files.execution_study_reconcile_preparation')['retry'],'never') - def test_exact_scientific_identity_and_recovery_reason_correlation(self): - args=dict(WRITE,study_id=STUDY,revision=1,candidate_id=CANDIDATE,root='fixture',directory='package',runtime_snapshot_sha256=CP) - raw=client(prepared());sdk=ProjectFilesClient(raw);sdk.execution_study_prepare_package(**args) - for field,bad in (('candidate_id',ACTOR),('runtime_snapshot_sha256',NEXT)): - raw._request.return_value=dict(status=200,result=bound(dict(prepared(),**{field:bad}))) - with self.assertRaises(api.AgentAPIError):sdk.execution_study_prepare_package(**args) - raw._request.return_value=dict(status=200,result=bound(abandonment())) - sdk.execution_study_abandon_preparation(**dict(WRITE,request_key='new-abandon-key'),study_id=STUDY,preparation_key=KEY,reason=abandonment()['reason']) - raw._request.return_value=dict(status=200,result=bound(dict(abandonment(),reason='different'))) - with self.assertRaises(api.AgentAPIError):sdk.execution_study_abandon_preparation(**dict(WRITE,request_key='new-abandon-key'),study_id=STUDY,preparation_key=KEY,reason=abandonment()['reason']) - def test_dispatch_exact_local_owner_and_reconciliation_has_no_second_key(self): - owner=Mock();projection=SimpleNamespace(session=SimpleNamespace(access=SimpleNamespace(require=Mock())),execution=SimpleNamespace(study_execution=owner)) - args=dict(WRITE,study_id=STUDY,revision=1,candidate_id=CANDIDATE,root='fixture',directory='package',runtime_snapshot_sha256=CP) - project_dispatch.dispatch(projection,'project_files.execution_study_prepare_package',args) - owner.prepare_package.assert_called_once_with(STUDY,{k:v for k,v in args.items() if k not in ('binding','expected_checkpoint','request_key','study_id')},CP,KEY) - args=dict(binding=READ['binding'],expected_checkpoint=CP,study_id=STUDY,preparation_key='k') - project_dispatch.dispatch(projection,'project_files.execution_study_reconcile_preparation',args) - owner.reconcile_preparation.assert_called_once_with(STUDY,{'preparation_key':'k'},CP) -if __name__=='__main__':unittest.main() diff --git a/tests/test_project_composition.py b/tests/test_project_composition.py deleted file mode 100644 index c20a90df..00000000 --- a/tests/test_project_composition.py +++ /dev/null @@ -1,136 +0,0 @@ -"""Exact retained-source assembly; native history remains the proof oracle.""" -import copy -import hashlib -import unittest -from unittest.mock import patch - -from project_composition import ProjectCompositionError, merge_retained_sources -from project_history import capture_run, declarations, decode_records -from project_store import _encode -from test_project_history import ORIGIN, legacy_run - - -def snapshot(identity, records): - return dict(project_id=identity*32, name='Source '+identity, checkpoint=identity*64, records=records) - - -def approved_history(): - run=legacy_run();run['approval_id']='9'*32 - run['release_id']=run['release_sha256']=hashlib.sha256(b'reference input').hexdigest() - run['release_bytes']=len(b'reference input') - grant=dict(id=run['approval_id'],catalog_id=ORIGIN,approver_actor_id='a'*32,approver_credential_id='b'*32, - consumer_actor_id='5'*32,material_sha256='f'*64,created_at=1,expires_at=100,revoked_at=None) - consumption=dict(grant_id=grant['id'],run_id=run['id'],admission_id=run['admission_id'], - consumer_credential_id='6'*32,request_sha256=run['request_sha256'],consumed_at=2) - effects={'pipeline.inspect_release':[run['release_id']],'dataset_releases.locate':[run['release_id']], - 'pipeline.probe':['image_classification'],'pipeline.probe_native':['image_classification'], - 'pipeline.definition_identity':['image_classification'],'pipeline.exposures':[None],'runs.update':[run['id']]} - admission=dict(id=run['admission_id'],catalog_id=ORIGIN,actor_id='5'*32,credential_id='6'*32, - kind='runs',job_id=run['id'],request_digest=run['request_sha256'],effects=effects,created_at=1) - record=capture_run(run,admission_proof=dict(grant=grant,consumption=consumption,admission=admission),payloads=[]) - records=[record,*declarations(record)] - decode_records(records) - return records - - -class RetainedCompositionTests(unittest.TestCase): - def test_exact_duplicate_is_shared_and_each_source_membership_is_retained(self): - records=approved_history();left=snapshot('1',records);right=snapshot('2',copy.deepcopy(records)) - result=merge_retained_sources([left,right]) - self.assertEqual(result['records'],sorted(records,key=lambda item:(item['family'],item['id']))) - self.assertEqual(len(result['sources']),2) - for source in result['sources']: - for record in records: - expected=hashlib.sha256(_encode(record)).hexdigest() - self.assertEqual(source['records'][record['family']][record['id']],expected) - self.assertEqual(source['run_observations'],{}) - - def test_alternate_grant_is_exact_native_observation_without_duplicate_run(self): - original=approved_history();alternate=copy.deepcopy(original) - alternate[0]['document']['admission_proof']['grant']['revoked_at']=3 - alternate[0]['document']['admission_proof']['consumption']['consumed_at']=3 - decode_records(alternate) - with patch('os.open',side_effect=AssertionError('Pure construction has no filesystem access')): - result=merge_retained_sources([snapshot('1',original),snapshot('2',alternate),snapshot('3',copy.deepcopy(alternate))]) - facts=decode_records(result['records']) - self.assertEqual(len(facts.runs),1) - self.assertEqual(len(facts.observations),1) - base=next(r for r in result['records'] if r['family']=='run_history') - observation=next(r for r in result['records'] if r['family']=='run_observation') - self.assertEqual(_encode(base),_encode(original[0])) - self.assertEqual(_encode(observation['document']['observation']),_encode(alternate[0]['document'])) - expected=hashlib.sha256(_encode(alternate[0]['document'])).hexdigest() - self.assertEqual(observation['id'],expected) - for source in result['sources'][1:]: - self.assertEqual(source['run_observations'],{original[0]['id']:expected}) - self.assertFalse(result['sources'][0]['run_observations']) - - def test_broader_run_conflicts_are_rejected_at_the_named_conflict_boundary(self): - original=approved_history() - for field in ('metrics','population','admission'): - alternate=copy.deepcopy(original) - if field=='metrics':alternate[0]['document']['run']['metrics']={'accuracy':0.5} - elif field=='population':alternate[0]['document']['payloads'][0]['population']='test' - else:alternate[0]['document']['admission_proof']['admission']['created_at']=2 - decode_records(alternate) - with self.subTest(field=field),self.assertRaises(ProjectCompositionError) as caught: - merge_retained_sources([snapshot('1',original),snapshot('2',alternate)]) - self.assertEqual(caught.exception.code,'conflict') - self.assertIn('run_history/'+original[0]['id'],str(caught.exception)) - - def test_equal_python_numbers_do_not_hide_different_canonical_bytes(self): - original=approved_history();original[0]['document']['run']['parameters']={'scale':1} - alternate=copy.deepcopy(original);alternate[0]['document']['run']['parameters']['scale']=1.0 - self.assertEqual(original,alternate) - decode_records(original);decode_records(alternate) - with self.assertRaises(ProjectCompositionError) as caught: - merge_retained_sources([snapshot('1',original),snapshot('2',alternate)]) - self.assertEqual(caught.exception.code,'conflict') - - def test_other_family_conflict_and_repeated_source_project_are_rejected(self): - original=approved_history();alternate=copy.deepcopy(original) - alternate[1]['document']['bytes']+=1 - with self.assertRaises(ProjectCompositionError) as caught: - merge_retained_sources([snapshot('1',original),snapshot('2',alternate)]) - self.assertEqual(caught.exception.code,'conflict') - self.assertIn('project_artifact/',str(caught.exception)) - with self.assertRaises(ProjectCompositionError) as repeated: - merge_retained_sources([snapshot('1',original),snapshot('1',original)]) - self.assertEqual(repeated.exception.code,'conflict') - self.assertIn('source project identity repeats',str(repeated.exception)) - - def test_source_unique_policy_overrides_another_sources_runtime_dependency(self): - from project_composition import build_candidate - from test_project_fork_composition import runtime_records - import uuid - sha=hashlib.sha256(b'Z').hexdigest() - runtime,_,_=runtime_records('9'*32,shared_sha=sha,shared_bytes=1) - declaration=next(r for r in runtime if r['family']=='project_artifact' and r['id']==sha) - candidate=build_candidate([snapshot('1',runtime),snapshot('2',[copy.deepcopy(declaration)])], - '3'*32,created_at='2026-10-24T12:00:00+00:00',id_factory=lambda *_:uuid.uuid4().hex, - directory='combined',name='Conservative source custody',request_key='shared-policy') - policies={edge['declaration']['sha256']:edge['preservation'] for edge in candidate['artifacts']} - self.assertEqual(policies[sha],'unique') - - def test_source_snapshots_can_be_loaded_lazily(self): - records=approved_history() - def sources(): - yield snapshot('1',records) - yield snapshot('2',copy.deepcopy(records)) - self.assertEqual(len(merge_retained_sources(sources())['sources']),2) - with self.assertRaises(ProjectCompositionError) as caught: - merge_retained_sources(iter([snapshot('1',records)])) - self.assertEqual(caught.exception.code,'invalid') - self.assertIn('at least two',str(caught.exception)) - - def test_output_owns_its_documents_and_does_not_mutate_sources(self): - original=approved_history();before=copy.deepcopy(original) - result=merge_retained_sources([snapshot('1',original),snapshot('2',copy.deepcopy(original))]) - result['records'][0]['document']['bytes']=123 - self.assertEqual(original,before) - original[0]['document']['run']['metrics']={'accuracy':0.25} - retained=next(r for r in result['records'] if r['family']=='run_history') - self.assertIsNone(retained['document']['run']['metrics']) - - -if __name__=='__main__':unittest.main() diff --git a/tests/test_project_composition_publication.py b/tests/test_project_composition_publication.py deleted file mode 100644 index 0bb6d881..00000000 --- a/tests/test_project_composition_publication.py +++ /dev/null @@ -1,172 +0,0 @@ -"""Real native stage/custody/reconciliation across multiple independent sources.""" -import copy -import errno -import hashlib -import os -from pathlib import Path -import tempfile -import unittest -from unittest.mock import patch -import uuid - -from project_artifacts import ProjectArtifacts -from project_composition import decode_records, publish_composition -from project_fork import decode_fork, publish_fork -from project_fork_composition import build_candidate as fork_candidate -from project_history import decode_records as history_records -from project_store import DIR_FLAGS, ProjectStore, ProjectStoreError -from test_project_composition import approved_history - -NOW='2026-10-24T12:00:00+00:00' - - -def validate(records,identity,artifacts): - decode_fork(records,project_id=identity) - decode_records(records,project_id=identity) - history_records(records,artifacts=artifacts) - - -class CompositionPublicationTests(unittest.TestCase): - def setUp(self): - self.tmp=tempfile.TemporaryDirectory(prefix='native-composition-');self.addCleanup(self.tmp.cleanup) - self.root=Path(self.tmp.name);self.fd=os.open(self.root,DIR_FLAGS);self.addCleanup(os.close,self.fd) - self.stores=[];self.artifacts=[];self.snapshots=[];self.unique=[] - for number in range(2): - store=ProjectStore.create(self.root/('source'+str(number)),'Source '+str(number),'create','a'*64) - self.addCleanup(store.close);artifacts=ProjectArtifacts(store);self.addCleanup(artifacts.close) - records=approved_history() - if number:records[0]['document']['admission_proof']['grant']['revoked_at']=3 - unique=('unique source '+str(number)).encode();sha=hashlib.sha256(unique).hexdigest() - declaration=dict(format='project_artifact_v1',sha256=sha,bytes=len(unique)) - records.append(dict(family='project_artifact',id=sha,document=declaration)) - for raw in (b'reference input',unique): - artifacts.publish_bytes(raw,dict(format='project_artifact_v1',sha256=hashlib.sha256(raw).hexdigest(),bytes=len(raw))) - snap=store.commit(records,store.snapshot()['checkpoint'],'seed','b'*64) - self.stores.append(store);self.artifacts.append(artifacts);self.snapshots.append(snap);self.unique.append(sha) - - def publish(self,directory='combined',**options): - arguments=dict(root_path=self.root,name='Combined',expected_checkpoint=self.snapshots[0]['checkpoint'], - request_key='compose-exact',quiescent=True,created_at=NOW,id_factory=lambda *_:uuid.uuid4().hex,validate_candidate=validate) - arguments.update(options) - return publish_composition(self.stores[0],self.artifacts[0], - [dict(store=self.stores[1],artifacts=self.artifacts[1],checkpoint=self.snapshots[1]['checkpoint'])], - self.fd,directory,**arguments) - - def assert_code(self,code,call): - with self.assertRaises(ProjectStoreError) as caught:call() - self.assertEqual(caught.exception.code,code) - return caught.exception - - def test_complete_publication_preserves_both_sources_and_independent_payloads(self): - before=copy.deepcopy(self.snapshots) - result=self.publish();snapshot=result['snapshot'];identity=snapshot['project_id'] - self.assertFalse(result['reconciled']) - self.assertEqual(len(history_records(snapshot['records']).runs),1) - self.assertEqual(len(history_records(snapshot['records']).observations),1) - self.assertEqual(len(decode_records(snapshot['records'],project_id=identity)[identity]['sources']),2) - with ProjectStore.open(self.root/'combined') as destination,ProjectArtifacts(destination) as owner: - for sha in result['fork']['artifacts']['copied']: - source=next(s.path/'artifacts/sha256'/sha for s in self.stores if (s.path/'artifacts/sha256'/sha).exists()) - target=destination.path/'artifacts/sha256'/sha - self.assertEqual(target.read_bytes(),source.read_bytes()) - self.assertNotEqual((source.stat().st_dev,source.stat().st_ino),(target.stat().st_dev,target.stat().st_ino)) - self.assertEqual(target.stat().st_nlink,1) - self.assertEqual([s.snapshot() for s in self.stores],before) - - def test_already_forked_sources_keep_their_independent_histories(self): - for number in range(2): - result=publish_fork(self.stores[number],self.artifacts[number],self.fd,'forked-source-'+str(number), - root_path=self.root,name='Already forked source',expected_checkpoint=self.snapshots[number]['checkpoint'], - request_key='prepare-fork-'+str(number),quiescent=True, - build_candidate=lambda snap,dest:fork_candidate(snap,dest,created_at=NOW,id_factory=lambda *_:uuid.uuid4().hex), - validate_candidate=lambda records,identity:validate(records,identity,None)) - store=ProjectStore.open(self.root/('forked-source-'+str(number))) - artifacts=ProjectArtifacts(store);self.addCleanup(store.close);self.addCleanup(artifacts.close) - self.stores[number]=store;self.artifacts[number]=artifacts;self.snapshots[number]=result['snapshot'] - source_overlays=[next(r for r in s['records'] if r['family']=='project_fork') for s in self.snapshots] - result=self.publish();records=result['snapshot']['records'];identity=result['snapshot']['project_id'] - self.assertTrue(all(old in records for old in source_overlays)) - self.assertTrue(all(dict(family='project_fork',id=old['id']) in result['fork']['archived'] for old in source_overlays)) - self.assertEqual(decode_fork(records,project_id=identity)['destination_project_id'],identity) - self.assertIn(identity,decode_records(records,project_id=identity)) - - def test_missing_unique_secondary_bytes_leave_only_retained_staging(self): - (self.stores[1].path/'artifacts/sha256'/self.unique[1]).unlink() - self.assert_code('unavailable',self.publish) - self.assertFalse((self.root/'combined').exists()) - self.assertTrue(list(self.root.glob('.tuldok-fork-*'))) - - def test_missing_duplicate_is_satisfied_by_verified_primary_bytes(self): - sha=hashlib.sha256(b'reference input').hexdigest() - (self.stores[1].path/'artifacts/sha256'/sha).unlink() - result=self.publish() - self.assertIn(sha,result['fork']['artifacts']['copied']) - self.assertEqual((self.root/'combined/artifacts/sha256'/sha).read_bytes(),b'reference input') - - def test_corrupt_shared_secondary_copy_does_not_fall_back_to_good_primary(self): - sha=hashlib.sha256(b'reference input').hexdigest() - target=self.stores[1].path/'artifacts/sha256'/sha - target.chmod(0o600);target.write_bytes(b'wrong') - self.assert_code('invalid',self.publish) - self.assertFalse((self.root/'combined').exists()) - - def test_secondary_checkpoint_change_during_copy_prevents_publication(self): - copy_many=self.artifacts[0].copy_many_to - def changed(destination,declarations): - copy_many(destination,declarations) - source=self.stores[1];snapshot=source.snapshot() - source.commit(snapshot['records'],snapshot['checkpoint'],'new-source-receipt','c'*64) - with patch.object(self.artifacts[0],'copy_many_to',side_effect=changed): - self.assert_code('stale',self.publish) - self.assertFalse((self.root/'combined').exists()) - - def test_lost_publication_ack_reconciles_exact_sources_without_reconstruction(self): - fsync=os.fsync;injected=False - def fail_after_publish(fd): - nonlocal injected - if (self.root/'combined').exists() and not injected: - injected=True;raise OSError(errno.EIO,'bounded lost-ack fixture') - fsync(fd) - with patch('project_fork.os.fsync',side_effect=fail_after_publish): - failure=self.assert_code('unknown',self.publish) - self.assertTrue(failure.receipt['committed']) - with patch('project_composition.build_candidate',side_effect=AssertionError('No replayed construction')): - replay=self.publish() - self.assertTrue(replay['reconciled']) - self.assertEqual(replay['snapshot']['checkpoint'],failure.receipt['checkpoint']) - self.assert_code('conflict',lambda:self.publish(name='Changed input')) - - def test_destination_cannot_overlap_secondary_source(self): - self.assert_code('invalid',lambda:self.publish('source1/nested')) - self.assertFalse((self.stores[1].path/'nested').exists()) - - def test_persisted_membership_tampering_is_rejected(self): - result=self.publish();records=copy.deepcopy(result['snapshot']['records']) - doc=next(r['document'] for r in records if r['family']=='project_composition') - source=doc['sources'][1];family=next(iter(source['records']));identity=next(iter(source['records'][family])) - source['records'][family][identity]='0'*64 - error=self.assert_code('invalid',lambda:decode_records(records,project_id=result['snapshot']['project_id'])) - self.assertIn('exact retained envelope',str(error)) - - def test_malformed_persisted_run_memberships_have_typed_invalid_outcomes(self): - result=self.publish() - for kind in ('non-object','null-observation'): - records=copy.deepcopy(result['snapshot']['records']) - doc=next(r['document'] for r in records if r['family']=='project_composition') - source=doc['sources'][1] - if kind=='non-object':source['records']['run_history']=1 - else:source['run_observations'][next(iter(source['records']['run_history']))]=None - with self.subTest(kind=kind):self.assert_code('invalid',lambda:decode_records(records)) - - def test_future_ordinary_fork_preserves_and_archives_composition_provenance(self): - first=self.publish() - with ProjectStore.open(self.root/'combined') as source,ProjectArtifacts(source) as artifacts: - result=publish_fork(source,artifacts,self.fd,'descendant',root_path=self.root,name='Descendant', - expected_checkpoint=first['snapshot']['checkpoint'],request_key='fork-composition',quiescent=True, - build_candidate=lambda snap,dest:fork_candidate(snap,dest,created_at=NOW,id_factory=lambda *_:uuid.uuid4().hex), - validate_candidate=lambda records,identity:validate(records,identity,artifacts)) - self.assertIn(dict(family='project_composition',id=first['snapshot']['project_id']),result['fork']['archived']) - self.assertIn(first['snapshot']['project_id'],decode_records(result['snapshot']['records'],project_id=result['snapshot']['project_id'])) - - -if __name__=='__main__':unittest.main() diff --git a/tests/test_project_composition_workspace.py b/tests/test_project_composition_workspace.py deleted file mode 100644 index af5134e3..00000000 --- a/tests/test_project_composition_workspace.py +++ /dev/null @@ -1,87 +0,0 @@ -"""Owner-authorized native composition, editable notes and selection recovery.""" -import copy -import hashlib -import os -import unittest -from unittest.mock import patch - -import agent_api -from access import AccessError -from project_artifacts import ProjectArtifacts -from project_composition import decode_records -from project_files import file_id -from project_store import ProjectStore -from workbench import WorkbenchError -from test_project_composition import approved_history -from test_project_workspace import ProjectWorkspaceTests - - -@unittest.skipUnless(os.environ.get('TULDOK_DATABASE_URL'),'Requires disposable PostgreSQL') -class CompositionWorkspaceTests(unittest.TestCase): - def setUp(self): - self.fixture=ProjectWorkspaceTests('test_lifecycle_replay_is_idempotent_only_while_resulting_state_is_current') - self.fixture.setUp();self.addCleanup(self.fixture.doCleanups) - f=self.fixture;created,_=f.create();self.primary_id=created['project']['project_id'] - for revision,text in enumerate(('Original decision Ω\r\n','Updated decision Ω\r\n')): - raw=text.encode();target=f.external/'alpha/notes/decision.md';target.parent.mkdir(exist_ok=True) - target.write_bytes(raw) - f.call('file_adopt',f.mutation(kind='note',path='notes/decision.md',expected_revision=revision, - expected_sha256=hashlib.sha256(raw).hexdigest())) - self.primary=f.workspace._store.snapshot() - with ProjectStore.create(f.external/'retained','Retained source','create','a'*64) as store,ProjectArtifacts(store) as artifacts: - records=approved_history();raw=b'reference input' - artifacts.publish_bytes(raw,dict(format='project_artifact_v1',sha256=hashlib.sha256(raw).hexdigest(),bytes=len(raw))) - self.secondary=store.commit(records,store.snapshot()['checkpoint'],'seed','b'*64) - self.arguments=f.mutation(root='fixture',directory='combined',name='Combined scientific history',sources=[dict( - root='fixture',directory='retained',project_id=self.secondary['project_id'],checkpoint=self.secondary['checkpoint'])]) - - def compose(self):return self.fixture.call('compose',self.arguments) - - def test_native_owner_composition_preserves_note_history_and_selects_editable_primary_fork(self): - f=self.fixture - with patch('subprocess.Popen',side_effect=AssertionError('Imported projects never execute')): - result=self.compose() - state=result['state'];self.assertEqual(state['state'],'open') - self.assertNotEqual(state['project']['project_id'],self.primary_id) - self.assertEqual(result['sources'],[{key:s[key] for key in ('project_id','checkpoint')} for s in (self.primary,self.secondary)]) - snapshot=f.workspace._store.snapshot();identity=snapshot['project_id'] - decode_records(snapshot['records'],project_id=identity) - old_note=next(r for r in self.primary['records'] if r['family']=='project_file') - self.assertIn(old_note,snapshot['records']);self.assertEqual(len(old_note['document']['history']),2) - adopted=file_id(identity,'note','notes/decision.md') - value=f.call('file_get',dict(binding=state['binding'],checkpoint=state['project']['checkpoint'],file_id=adopted))['value'] - self.assertEqual(value['version']['text'],'Updated decision Ω\r\n') - raw=b'Next independent decision\n';target=f.external/'combined/notes/decision.md';target.write_bytes(raw) - updated=f.call('file_adopt',f.mutation(kind='note',path='notes/decision.md',expected_revision=value['version']['revision'], - expected_sha256=hashlib.sha256(raw).hexdigest())) - self.assertEqual(updated['value']['revision'],value['version']['revision']+1) - agent_api.validate_output('project_files.compose',dict(status=200,result=result),version=1) - - def test_failed_selection_preserves_primary_and_exact_retry_reconciles_destination(self): - f=self.fixture;project=f.workspace._projection_for - def fail_new(store): - if store.path.name=='combined':raise WorkbenchError('Bounded selection fixture failure.','unavailable',503) - return project(store) - with patch.object(f.workspace,'_projection_for',side_effect=fail_new),self.assertRaises(WorkbenchError) as caught:self.compose() - self.assertEqual(caught.exception.code,'project_selection_unavailable') - self.assertTrue(caught.exception.receipt['committed']);self.assertFalse(caught.exception.receipt['selected']) - self.assertEqual(f.state()['project']['project_id'],self.primary_id) - replay=self.compose();self.assertTrue(replay['fork']['reconciled']) - self.assertEqual(replay['state']['project']['project_id'],caught.exception.receipt['project_id']) - - def test_wrong_secondary_checkpoint_is_rejected_before_destination_publication(self): - self.arguments['sources'][0]['checkpoint']='0'*64 - with self.assertRaises(WorkbenchError) as caught:self.compose() - self.assertEqual(caught.exception.code,'stale_project') - self.assertFalse((self.fixture.external/'combined').exists()) - self.assertEqual(self.fixture.state()['project']['project_id'],self.primary_id) - - def test_anonymous_caller_is_denied_before_opening_retained_sources(self): - with patch.object(ProjectStore,'open_at',side_effect=AssertionError('No unauthorized filesystem selection')): - with self.assertRaises(AccessError) as caught: - self.fixture.workspace.dispatch('project_files.compose',self.arguments) - self.assertEqual(caught.exception.status,401) - self.assertFalse((self.fixture.external/'combined').exists()) - - -if __name__=='__main__':unittest.main() diff --git a/tests/test_project_control_paths.py b/tests/test_project_control_paths.py deleted file mode 100644 index 2e1832a7..00000000 --- a/tests/test_project_control_paths.py +++ /dev/null @@ -1,121 +0,0 @@ -"""Anchored physical separation of portable projects and private control state.""" -import os -from pathlib import Path -import tempfile -import unittest -from unittest.mock import patch - -from backup_metadata import tree_manifest -from project_store import DIR_FLAGS, ProjectStoreError, assert_separate_project_control -from project_transfer_controller import ProjectTransferController -from project_workspace import ProjectWorkspace -from workbench import WorkbenchError -import test_project_transfer_controller as transfer_fixture - - -class AnchoredControlPaths(unittest.TestCase): - def setUp(self): - self.temporary = tempfile.TemporaryDirectory(prefix='tuldok-control-separation-') - self.addCleanup(self.temporary.cleanup) - self.parent = Path(self.temporary.name) - self.root = self.parent / 'configured-root'; self.root.mkdir() - self.control = self.parent / 'private-control'; self.control.mkdir() - self.fd = os.open(self.root, DIR_FLAGS) - self.addCleanup(os.close, self.fd) - - def check(self, relative, *, control=None, descriptor=None): - assert_separate_project_control(self.fd if descriptor is None else descriptor, relative, - root_path=self.root, control_path=self.control if control is None else control) - - def test_existing_equality_and_both_ancestries_reject_without_leaking_or_closing_caller_fd(self): - project = self.root / 'portable'; control = project / 'control' - control.mkdir(parents=True); (control / 'child').mkdir() - original = os.fstat(self.fd) - descriptors = len(list(Path('/proc/self/fd').iterdir())) - for _ in range(4): - for relative in ('portable', 'portable/control', 'portable/control/child'): - with self.subTest(relative=relative), self.assertRaises(ProjectStoreError) as error: - self.check(relative, control=control) - self.assertEqual((error.exception.code, error.exception.status), ('conflict', 409)) - self.assertEqual(os.fstat(self.fd).st_ino, original.st_ino) - self.assertEqual(len(list(Path('/proc/self/fd').iterdir())), descriptors) - - def test_absent_leaf_is_never_allocated_and_broad_root_disjoint_siblings_are_allowed(self): - control = self.root / 'control'; control.mkdir() - (self.root / 'control-sibling').mkdir() - duplicate = os.dup(self.fd); self.addCleanup(os.close, duplicate) - self.check('new-project', control=control, descriptor=duplicate) - self.check('control-sibling', control=control, descriptor=duplicate) - self.assertFalse((self.root / 'new-project').exists()) - with self.assertRaises(ProjectStoreError) as error: - self.check('control/forbidden', control=control, descriptor=duplicate) - self.assertEqual(error.exception.code, 'conflict') - self.assertFalse((control / 'forbidden').exists()) - self.assertEqual(os.fstat(duplicate).st_ino, os.fstat(self.fd).st_ino) - - def test_symlink_leaf_intermediate_and_control_alias_are_refused_without_following(self): - (self.root / 'linked').symlink_to(self.control, target_is_directory=True) - for relative in ('linked', 'linked/child'): - with self.subTest(relative=relative), self.assertRaises(ProjectStoreError): - self.check(relative) - alias = self.parent / 'control-alias'; alias.symlink_to(self.control, target_is_directory=True) - with self.assertRaises(ProjectStoreError): self.check('new-project', control=alias) - self.assertFalse((self.control / 'child').exists()) - self.assertFalse((self.root / 'new-project').exists()) - self.assertTrue(os.fstat(self.fd).st_ino) - - def test_replaced_configured_root_is_stale_before_any_target_allocation(self): - original = os.fstat(self.fd).st_ino - self.root.rename(self.parent / 'original-root'); self.root.mkdir() - with self.assertRaises(ProjectStoreError) as error: self.check('new-project') - self.assertEqual(error.exception.code, 'stale') - self.assertEqual(os.fstat(self.fd).st_ino, original) - self.assertFalse((self.root / 'new-project').exists()) - self.assertFalse((self.parent / 'original-root' / 'new-project').exists()) - - -@unittest.skipUnless(os.environ.get('TULDOK_DATABASE_URL'), 'Requires disposable PostgreSQL') -class TransferControlPaths(unittest.TestCase): - def test_destination_inside_control_is_refused_before_source_stop_and_before_extraction(self): - f = transfer_fixture.TransferControllerTests('test_actual_http_source_control_handoff_report_and_extraction') - f.setUp(); self.addCleanup(f.doCleanups) - # Normal startup can configure a broad root or a root at control itself; - # destination validation must reject overlap before irreversible Stop. - f.controller.close(); f.workspace.close() - control = f.root / 'separate-control' - f.workspace = ProjectWorkspace(control, {'output': f.publication, 'inside': control}) - f.schemas.add(f.workspace.db.schema) - f.controller = ProjectTransferController(f.dataset, f.workspace) - f.control_token = f.workspace.access.exchange(f.workspace.access._local_owner_token())['token'] - live = f.preview() - original = tree_manifest(f.dataset.path) - with patch('runs.Runs', side_effect=AssertionError('No Run owner construction')): - with patch.object(f.dataset, 'stop_for_project_extraction', side_effect=AssertionError('Destination must be checked before Stop')) as stop: - with self.assertRaises((ProjectStoreError, WorkbenchError)) as denied: - f.controller.stop(live['binding'], live['report']['report_sha256'], 'output', 'backup', 'inside', 'forbidden') - self.assertEqual(denied.exception.code, 'conflict') - stop.assert_not_called() - self.assertEqual(f.controller.phase, 'source_live') - self.assertFalse(f.dataset._extraction_stopping) - self.assertFalse((f.publication / 'backup').exists()) - self.assertFalse((control / 'forbidden').exists()) - self.assertEqual(tree_manifest(f.dataset.path), original) - f.stop() # Disjoint sibling backup/project is a valid explicit Stop. - with f.workspace.access.bind(f.control_token): - ready = f.preview() - stopped = tree_manifest(f.dataset.path) - with patch.object(f.controller._transfer, 'extract', side_effect=AssertionError('No publication before destination check')) as extract: - with self.assertRaises((ProjectStoreError, WorkbenchError)) as denied: - f.controller.extract(ready['binding'], ready['report']['report_sha256'], 'inside', 'forbidden', - 'Must not publish', 'invalid-control-destination') - self.assertEqual(denied.exception.code, 'conflict') - extract.assert_not_called() - self.assertEqual(f.controller.phase, 'source_stopped') - self.assertFalse((control / 'forbidden').exists()) - self.assertFalse((control / '.project-projections').exists()) - self.assertFalse((f.publication / 'extracted').exists()) - self.assertEqual(tree_manifest(f.dataset.path), stopped) - - -if __name__ == '__main__': - unittest.main() diff --git a/tests/test_project_custody.py b/tests/test_project_custody.py deleted file mode 100644 index 2802f40e..00000000 --- a/tests/test_project_custody.py +++ /dev/null @@ -1,364 +0,0 @@ -"""Private original-host physical custody facts, never portable authority.""" -import copy -import hashlib -import json -import os -from pathlib import Path -import shutil -import stat -import subprocess -import sys -import tempfile -import time -import unittest -from unittest.mock import patch -import uuid - -from project_custody import ProjectCustody, validate -from project_store import ProjectStore -from workbench import WorkbenchError - - -class ProjectCustodyTests(unittest.TestCase): - def setUp(self): - self.tmp=tempfile.TemporaryDirectory(prefix='tuldok-local-custody-');self.root=Path(self.tmp.name) - self.addCleanup(self.tmp.cleanup) - self.control=self.root/'control';self.control.mkdir(mode=0o700) - self.store=ProjectStore.create(self.root/'project','Neutral custody','new-custody','a'*64) - self.addCleanup(self.store.close) - self.host=uuid.uuid4().hex;self.projection=uuid.uuid4().hex - self.manager=ProjectCustody(self.control,self.host) - self.journal=self.manager.for_projection(self.store,self.projection) - self.run=dict(id=uuid.uuid4().hex,admission_id=uuid.uuid4().hex,request_sha256='b'*64, - spec={'authored':'bounded specification'},custody_phase='prepared',custody_identity=None) - self.helper=dict(pid=123456,start_ticks='987654',boot_id='aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee') - - def fresh(self):return ProjectCustody(self.control,self.host).for_projection(self.store,self.projection) - - def test_inert_index_then_exact_private_physical_binding_survives_reread(self): - self.assertFalse((self.control/'.project-custody').exists()) - self.assertEqual(self.manager.pending(self.store),[]) - self.journal.observe_run(self.run) - file=self.control/'.project-custody'/self.journal.name - self.assertEqual(stat.S_IMODE(file.stat().st_mode),0o600) - pending=self.manager.pending(self.store) - self.assertEqual(pending,[self.journal.binding]) - self.assertEqual(self.fresh().snapshot(),self.journal.snapshot()) - self.assertNotIn('token',file.read_text()) - self.assertEqual(self.fresh().snapshot()['runs'][0]['phase'],'admitted') - - def test_exact_attempted_selection_is_correlated_and_other_checkout_refused(self): - self.journal.observe_run(self.run);before=self.store.snapshot() - record=dict(family='project_artifact',id='c'*64,document=dict(format='project_artifact_v1',sha256='c'*64,bytes=3)) - self.journal.expect_publication(before,[record],'local-publication','d'*64) - selected=self.store.commit([record],before['checkpoint'],'local-publication','d'*64) - self.fresh().validate_selection(selected) - other=dict(family='project_artifact',id='e'*64,document=dict(format='project_artifact_v1',sha256='e'*64,bytes=4)) - foreign=self.store.commit([record,other],selected['checkpoint'],'unrelated-checkout','f'*64) - with self.assertRaises(WorkbenchError):self.fresh().validate_selection(foreign) - - def test_portable_copy_and_other_host_cannot_inherit_original_custody(self): - self.journal.observe_run(self.run) - self.assertEqual(ProjectCustody(self.control,uuid.uuid4().hex).pending(self.store),[]) - clone=self.root/'copy';shutil.copytree(self.root/'project',clone) - with ProjectStore.open(clone) as copied: - self.assertEqual(copied.snapshot()['project_id'],self.store.snapshot()['project_id']) - self.assertEqual(self.manager.pending(copied),[]) - with self.assertRaises(WorkbenchError):self.manager.for_projection(copied,self.projection) - - def test_replacing_canonical_identity_at_same_root_retains_original_custody(self): - self.journal.observe_run(self.run);binding=self.journal.binding - physical=(self.root/'project').stat().st_ino - self.store.close() - with ProjectStore.create(self.root/'replacement','Different valid project','replace-project','c'*64) as other: - replacement=other.snapshot()['project_id'] - shutil.rmtree(self.root/'project'/'.tuldok') - shutil.copytree(self.root/'replacement'/'.tuldok',self.root/'project'/'.tuldok') - with ProjectStore.open(self.root/'project') as selected: - self.assertEqual(selected.snapshot()['project_id'],replacement) - self.assertEqual((self.root/'project').stat().st_ino,physical) - self.assertNotEqual(replacement,binding['project_id']) - self.assertEqual(self.manager.pending(selected),[binding]) - with self.assertRaises(WorkbenchError):self.journal.validate_selection(selected.snapshot()) - - def test_explicit_refresh_preserves_exact_original_pending_marker(self): - self.journal.observe_run(self.run);stale=self.fresh() - self.journal.launch_intent(self.run['id']) - self.assertEqual(stale.snapshot()['runs'][0]['phase'],'admitted') - observed=stale.refresh() - self.assertEqual(observed,self.journal.snapshot()) - self.assertEqual(observed['runs'][0]['phase'],'launch_intent') - self.assertTrue(stale.has_pending) - - def test_launch_identity_and_unknown_provider_remain_explicit_fences(self): - self.journal.observe_run(self.run);self.journal.launch_intent(self.run['id']) - self.journal.launched(self.run['id'],self.helper) - saved=self.fresh().snapshot()['runs'][0] - self.assertEqual(saved['custody_identity']['helper'],self.helper) - changed=copy.deepcopy(self.run);changed.update(custody_phase='barrier_ready',custody_identity=saved['custody_identity']) - self.journal.observe_run(changed) - changed['custody_phase']='go_intent';self.journal.observe_run(changed) - self.assertEqual(self.fresh().snapshot()['runs'][0]['phase'],'go_intent') - producer=uuid.uuid4().hex;admission=uuid.uuid4().hex - self.journal.register_producer('generation_history',producer,admission,'e'*64) - self.journal.producer_effect_intent('generation_history',producer) - self.journal.producer_outcome('generation_history',producer,'unknown',True) - value=self.fresh().snapshot()['producers'][0] - self.assertTrue(value['worker_drained']);self.assertEqual(value['provider_outcome'],'unknown') - self.assertTrue(self.fresh().has_pending) - - def test_only_two_file_writer_kinds_have_exact_retry_and_confirmation(self): - self.journal.runtime_started('runtime-capture','a'*64,'b'*64) - self.journal.package_started('package-prepare','c'*64,'d'*64) - self.assertTrue(self.fresh().has_pending) - with self.assertRaises(WorkbenchError):self.journal.runtime_started('runtime-capture','e'*64,'b'*64) - self.journal.runtime_confirmed('runtime-capture') - self.assertTrue(self.fresh().has_pending) - self.journal.package_confirmed('package-prepare') - self.assertEqual(self.manager.pending(self.store),[]) - - def test_unsafe_or_unclassified_local_files_fail_closed(self): - self.journal.observe_run(self.run);file=self.control/'.project-custody'/self.journal.name - file.chmod(0o644) - with self.assertRaises(WorkbenchError):self.manager.pending(self.store) - file.chmod(0o600);raw=file.read_bytes();value=json.loads(raw);value['token']='unclassified' - file.write_text(json.dumps(value)) - with self.assertRaises(WorkbenchError):self.manager.pending(self.store) - file.write_bytes(raw);file.unlink();file.symlink_to(self.root/'untrusted') - with self.assertRaises(WorkbenchError):self.manager.pending(self.store) - value=self.journal.snapshot();value['runs'][0]['arbitrary_resume']=True - with self.assertRaises(WorkbenchError):validate(value) - - def test_stale_local_reader_cannot_erase_another_current_admission(self): - stale=self.fresh();self.journal.observe_run(self.run) - other=copy.deepcopy(self.run);other['id']=uuid.uuid4().hex - with self.assertRaises(WorkbenchError) as failure:stale.observe_run(other) - self.assertEqual(failure.exception.code,'outcome_unknown') - self.assertEqual([item['run_id'] for item in self.fresh().snapshot()['runs']],[self.run['id']]) - - def test_directory_fsync_ack_loss_retains_pending_original_custody(self): - self.journal.observe_run(self.run);original=os.fsync - def fsync(descriptor): - if stat.S_ISDIR(os.fstat(descriptor).st_mode):raise OSError('Injected directory fsync acknowledgement loss') - return original(descriptor) - with patch('os.fsync',side_effect=fsync),self.assertRaises(WorkbenchError) as failure: - self.journal.launch_intent(self.run['id']) - self.assertEqual(failure.exception.code,'outcome_unknown') - self.assertEqual(self.fresh().snapshot()['runs'][0]['phase'],'launch_intent') - self.assertTrue(self.manager.pending(self.store)) - with self.assertRaises(WorkbenchError):self.journal.launched(self.run['id'],self.helper) - - -@unittest.skipUnless(os.environ.get('TULDOK_DATABASE_URL'),'Requires disposable PostgreSQL') -class OriginalHostIdentityFenceTests(unittest.TestCase): - def test_cold_workspace_detects_different_uuid_at_original_physical_root(self): - import psycopg - from psycopg import sql - from auth_helpers import ExplicitOwnerFixture - from metadata import connection_info - import project_workspace - with tempfile.TemporaryDirectory(prefix='project-custody-identity-') as temporary: - root=Path(temporary);external=root/'external';external.mkdir() - workspace=project_workspace.ProjectWorkspace(root/'control',{'fixture':external}) - schemas=[workspace.db.schema] - try: - owner=ExplicitOwnerFixture.bootstrap(workspace) - with ProjectStore.create(external/'project','Original identity','original-project','a'*64) as original: - binding=workspace.custody.for_projection(original,uuid.uuid4().hex) - binding.observe_run(dict(id=uuid.uuid4().hex,admission_id=uuid.uuid4().hex, - request_sha256='b'*64,spec={'authored':'unresolved physical custody index fixture'}, - custody_phase='prepared',custody_identity=None)) - original_id=original.snapshot()['project_id'];physical=(external/'project').stat().st_ino - with ProjectStore.create(external/'replacement','Replacement identity','replacement-project','c'*64) as replacement: - replacement_id=replacement.snapshot()['project_id'] - shutil.rmtree(external/'project'/'.tuldok') - shutil.copytree(external/'replacement'/'.tuldok',external/'project'/'.tuldok') - with owner.bound(workspace),patch('runs.Runs',side_effect=AssertionError('Cold Open constructed Runs')), \ - patch('subprocess.Popen',side_effect=AssertionError('Cold Open launched a process')): - state=workspace.status() - opened=workspace.dispatch('project_files.open',dict(binding=state['binding'],expected_checkpoint=None, - request_key='open-replaced-project',root='fixture',directory='project')) - self.assertEqual(opened['state'],'recovery_required') - self.assertEqual((external/'project').stat().st_ino,physical) - self.assertEqual(opened['project']['project_id'],replacement_id) - projection=workspace._projection;schemas.append(projection.db.schema) - self.assertFalse(projection.session.available);self.assertIsNone(projection.execution._runs) - self.assertEqual(projection.pending_original,[binding.binding]) - self.assertEqual(projection.pending_original[0]['project_id'],original_id) - with self.assertRaises(WorkbenchError) as denied: - workspace.dispatch('project_files.data_import_text',dict(binding=opened['binding'], - expected_checkpoint=opened['project']['checkpoint'],request_key='deny-replaced-project-edit', - text='No new authority',name='Blocked edit',groups=['owned'],parents=[],rights='Authored fixture')) - self.assertEqual(denied.exception.code,'projection_unavailable') - finally: - workspace.close() - with psycopg.connect(connection_info(),autocommit=True) as connection: - for schema in schemas: - connection.execute(sql.SQL('DROP SCHEMA IF EXISTS {} CASCADE').format(sql.Identifier(schema))) - - -CRASH_CHILD = r''' -import json,os,sys -from pathlib import Path -from project_workspace import ProjectWorkspace -import recipe_process -config=json.loads(Path(sys.argv[1]).read_text()) -workspace=ProjectWorkspace(config['control'],{'fixture':config['source']}) -with workspace.access.bind(Path(config['token_file']).read_text().strip()): - state=workspace.status() - workspace.dispatch('project_files.open',dict(binding=state['binding'],expected_checkpoint=None, - request_key='child-cold-open',root='fixture',directory='alpha')) - projection=workspace._projection;execution=projection.execution - projection.source_adapter.register(dict(root='fixture',manifest_path='project.json'), - projection.session.snapshot['checkpoint'],'child-current-source') - preflight=execution.preflight_external(config['graph_id'],config['graph_revision']) - body=dict(graph_id=config['graph_id'],graph_revision=config['graph_revision'],expected_digest=preflight['material_sha256']) - def crash(identity,phase): - print(json.dumps(dict(run_id=identity,projection_id=projection.db.projection_id,phase=phase,body=body)),flush=True) - os._exit(74) - if config['phase']=='started': - original=recipe_process.Handle.poll - def poll(handle): - events=original(handle) - if any(item['type']=='started' for item in events):crash(handle.spec['attempt_id'],'started') - return events - recipe_process.Handle.poll=poll - else: - original=projection.db._project_outcome - def outcome(result): - original(result) - if result=='committed': - for row in projection.db.execute('SELECT document FROM workspace_runs'): - run=json.loads(row['document']) - phase='admitted' if run['state']=='queued' else run['custody_phase'] - if phase==config['phase']:crash(run['id'],phase) - projection.db._project_outcome=outcome - execution.submit_external(body,projection.session.snapshot['checkpoint'],'original-crash-submit') - import time - time.sleep(40) - raise SystemExit('The requested real crash cut point was not reached') -''' - - -@unittest.skipUnless(os.environ.get('TULDOK_DATABASE_URL'),'Requires disposable PostgreSQL') -class OriginalHostCrashTests(unittest.TestCase): - def setUp(self): - import test_project_files_m2_http as m2 - m2.ProjectFilesM2HTTP.setUp(self) - - def receipt(self): - import test_project_files_m2_http as m2 - m2.ProjectFilesM2HTTP.receipt(self) - - def cleanup_owned(self): - import test_project_files_http as m1 - m1.ProjectFilesHTTP.cleanup_owned(self) - - def select_host(self,*args,**kwargs): - import test_project_files_http as m1 - return m1.ProjectFilesHTTP.select_host(self,*args,**kwargs) - - def request(self,*args,**kwargs): - import test_project_files_m2_http as m2 - return m2.ProjectFilesM2HTTP.request(self,*args,**kwargs) - - def state(self): - import test_project_files_http as m1 - return m1.ProjectFilesHTTP.state(self) - - def envelope(self,*args,**kwargs): - import test_project_files_http as m1 - return m1.ProjectFilesHTTP.envelope(self,*args,**kwargs) - - def action(self,*args,**kwargs): - import test_project_files_http as m1 - return m1.ProjectFilesHTTP.action(self,*args,**kwargs) - - def create(self):return self.action('new',root='fixture',directory='alpha',name='Original host neutral custody') - - def arguments(self,*args,**kwargs): - import test_project_files_m2_http as m2 - return m2.ProjectFilesM2HTTP.arguments(self,*args,**kwargs) - - def transport(self,*args,**kwargs): - import test_project_files_m2_http as m2 - return m2.ProjectFilesM2HTTP.transport(self,*args,**kwargs) - - def call(self,*args,**kwargs): - import test_project_files_m2_http as m2 - return m2.ProjectFilesM2HTTP.call(self,*args,**kwargs) - - def crash_and_reconcile(self,phase): - from test_project_files_material_http import neutral_source - import recipe_process - import project_workspace - manifest,manifest_raw,definition_raw,source,exact_input=neutral_source(self.external) - self.create() - self.call('source_register',root='fixture',manifest_path='project.json') - graph=self.call('graph_create_external',name='Original-host crash fixture',project_id=manifest['id'], - recipe_id='neutral',expected_sha256=hashlib.sha256(definition_raw).hexdigest(), - inputs={'sample':{'reference_id':'sample','expected_sha256':hashlib.sha256(exact_input).hexdigest()}}, - parameters={'mode':'sleep'}) - self.action('save');self.action('close') - token_file=self.path/'child-owner.token';token_file.write_text(self.owner.token);token_file.chmod(0o600) - config=self.path/'child-config.json' - config.write_text(json.dumps(dict(control=str(self.workspace.path),source=str(self.external), - token_file=str(token_file),graph_id=graph['id'],graph_revision=graph['revision'],phase=phase))) - config.chmod(0o600) - child=subprocess.run([sys.executable,'-c',CRASH_CHILD,str(config)],capture_output=True,text=True,timeout=50) - self.assertEqual(child.returncode,74,child.stderr+child.stdout) - observed=json.loads(child.stdout.strip().splitlines()[-1]);self.assertEqual(observed['phase'],phase) - # A restarted original host reads the private binding. Open constructs - # only inert owners and leaves all current execution unavailable. - with patch('runs.Runs',side_effect=AssertionError('Open constructed a Run owner')), \ - patch('subprocess.Popen',side_effect=AssertionError('Open launched a process')): - opened=self.action('open',root='fixture',directory='alpha') - self.assertEqual(opened['state'],'recovery_required') - self.assertIsNone(self.workspace._projection.execution._runs) - pending=self.workspace.custody.pending(self.workspace._store) - self.assertEqual(len(pending),1);self.assertEqual(pending[0]['projection_id'],observed['projection_id']) - state=self.state() - with patch.object(project_workspace,'M3_ENABLED',True), \ - patch('subprocess.Popen',side_effect=AssertionError('Reconciliation spawned a process')), \ - patch('recipe_process.Handle.go',side_effect=AssertionError('Reconciliation replayed GO')), \ - patch('runs.Runs._start',side_effect=AssertionError('Reconciliation started a queue')): - arguments=dict(binding=state['binding'],expected_checkpoint=state['project']['checkpoint']) - if phase=='admitted': - # Explicit owner-only adapter uses AgentClient's actual HTTP, - # negotiated pin and request/response identity correlation. - from agent_api import AgentClient,ProjectFilesOwnerClient - client=ProjectFilesOwnerClient(self.origin,self.owner.token,self.workspace.db.dataset_id,timeout=60) - self.assertIsInstance(client,AgentClient) - self.assertEqual(client.selected_contracts()['project_files.execution_reconcile_current'],1) - result=client.call('project_files.execution_reconcile_current',arguments) - status,response=result['status'],result['result'] - else: - status,response=self.transport('execution_reconcile_current',arguments) - self.assertEqual(status,200,response) - self.assertEqual(response['binding'],state['binding']) - value=response['value'];self.assertTrue(value['available']) - self.assertEqual(value['run_ids'],[observed['run_id']]) - current=self.workspace._projection - self.assertEqual(current.db.projection_id,observed['projection_id']) - self.assertEqual(self.workspace.custody.pending(self.workspace._store),[]) - document=next(item['document'] for item in current.session.snapshot['records'] - if item['family']=='run_history' and item['document']['run']['id']==observed['run_id']) - self.assertIn(document['run']['state'],('cancelled','interrupted')) - if phase!='admitted': - edge=next(item for item in document['payloads'] if item['name']=='custody-receipt.json') - receipt=recipe_process.validate_receipt(current.artifacts.read_blob(edge['blob']),document['run']['custody_identity']) - self.assertTrue(receipt['drained']) - self.assertEqual(receipt['go_received'],phase=='started') - before=current.db.execute('SELECT count(*) FROM workspace_runs').fetchone()[0] - with self.owner.bound(self.workspace): - replay=current.execution.submit_external(observed['body'],current.session.snapshot['checkpoint'],'original-crash-submit') - self.assertEqual(replay['run_id'],observed['run_id']) - self.assertEqual(current.db.execute('SELECT count(*) FROM workspace_runs').fetchone()[0],before) - self.action('save');self.action('close') - - def test_original_host_crash_after_admission_ack_before_queue_wake(self):self.crash_and_reconcile('admitted') - def test_original_host_crash_after_go_intent_before_go(self):self.crash_and_reconcile('go_intent') - def test_original_host_crash_after_actual_recipe_started(self):self.crash_and_reconcile('started') - - -if __name__=='__main__':unittest.main() diff --git a/tests/test_project_data.py b/tests/test_project_data.py deleted file mode 100644 index bc8df37f..00000000 --- a/tests/test_project_data.py +++ /dev/null @@ -1,458 +0,0 @@ -"""Workbench project closure through real PostgreSQL, files and shared sessions.""" -import base64 -import copy -import hashlib -import io -import json -from pathlib import Path -import tempfile -import unittest -import uuid -from unittest.mock import patch - -from PIL import Image -import psycopg -from psycopg import sql - -from access import Access, AccessError -from metadata import Metadata -from project_artifacts import ProjectArtifacts -from project_data import ProjectData, decode_data_records, validate_operation_result -from project_session import ProjectSession, operation_records -from project_store import ProjectStore -from workbench import WorkbenchError - - -def validate(records): - decode_data_records(records) - for receipt in operation_records(records).values(): - if not validate_operation_result(receipt['operation'], receipt['result'], records): - raise ValueError('Unexpected fixture operation') - - -class ProjectDataTests(unittest.TestCase): - def setUp(self): - self.tmp = tempfile.TemporaryDirectory(); self.addCleanup(self.tmp.cleanup) - self.root = Path(self.tmp.name) - self.host = self.metadata('host') - self.access = Access(self.host, self.host.path) - self.token = self.access.exchange(self.access._local_owner_token())['token'] - self.enterContext(self.access.bind(self.token)) - self.store = ProjectStore.create(self.root/'project','Data fixture','new','a'*64) - self.addCleanup(self.store.close) - self.db = self.metadata('projection') - self.artifacts = ProjectArtifacts(self.store); self.addCleanup(self.artifacts.close) - self.session = ProjectSession(self.store,self.db,self.access,self.artifacts,validate_records=validate) - self.data = ProjectData(self.session) - self.data.restore() - self.ordinal=0 - - def metadata(self, name): - db=Metadata(self.root/name) - def drop(): - with psycopg.connect(db.dsn,autocommit=True) as connection: - connection.execute(sql.SQL('DROP SCHEMA {} CASCADE').format(sql.Identifier(db.schema))) - self.addCleanup(drop);self.addCleanup(db.close) - return db - - def mutate(self, method, *args, key=None): - self.ordinal+=1 - return method(*args,self.session.snapshot['checkpoint'],key or 'op-'+str(self.ordinal)) - - def text(self, source='Hello 😀 cafe\u0301\r\n'): - return self.mutate(self.data.import_text,dict(text=source,name='Authored text',groups=['fixture'],rights='Owned fixture')) - - def annotate(self,row,task='text_classification',annotation=None): - return self.mutate(self.data.annotate,row['id'],dict(revision=row['revision'],source_revision=row['source_revision'],task=task, - annotation=annotation or {'label':'greeting'},groups=row['groups'],review='human_reviewed')) - - def image(self,color='red',groups=None): - target=io.BytesIO();Image.new('RGB',(8,6),color).save(target,'PNG') - raw=target.getvalue() - row=self.mutate(self.data.import_image,dict(image=base64.b64encode(raw).decode(),name='Small image',groups=groups or ['image-session'],rights='Owned image')) - return row,raw - - def cold(self): - snapshot=self.store.snapshot() - fresh=self.metadata('cold-'+uuid.uuid4().hex) - session=ProjectSession(self.store,fresh,self.access,self.artifacts,validate_records=validate) - adapter=ProjectData(session) - adapter.restore() - self.assertEqual(self.store.snapshot(),snapshot) - return adapter,session,fresh - - def test_text_annotation_rights_history_retry_and_cold_projection(self): - row=self.text();reviewed=self.annotate(row) - corrected=self.mutate(self.data.correct_rights_note,row['id'],dict(revision=2,source_revision=1,note='Corrected author rights'),key='rights') - self.assertEqual(corrected['record']['revision'],3) - original=self.store.snapshot() - replay=self.data.correct_rights_note(row['id'],dict(revision=2,source_revision=1,note='Corrected author rights'),'0'*64,'rights') - self.assertEqual(replay,corrected) - self.assertEqual(self.store.snapshot(),original) - other,session,db=self.cold() - self.assertEqual(other.get(row['id']),corrected['record']) - self.assertEqual(other.history(row['id']),self.data.history(row['id'])) - self.assertEqual(db.execute('SELECT original_text FROM workbench_records').fetchone()[0],'Hello 😀 cafe\u0301\r\n') - self.assertNotIn('rights_note_correction',json.loads(db.execute('SELECT provenance_json FROM workbench_records').fetchone()[0])) - - def test_responses_preferences_and_deleted_judgment_keep_exact_captures(self): - parent=self.text() - answers=[] - for completion in (' First exact\r\nanswer ','Second 😀 answer'): - result=self.mutate(self.data.save_response,dict(id=uuid.uuid4().hex,prompt_id=parent['id'],revision=0,parent_revision=1, - source_revision=1,completion=completion,review='draft')) - answers.append(result['response']) - request=dict(id=uuid.uuid4().hex,prompt_id=parent['id'],parent_revision=1,source_revision=1,left_id=answers[0]['id'],left_revision=1, - right_id=answers[1]['id'],right_revision=1,revision=0,outcome='left',rationale='Specific authored reason',review='human_reviewed') - judgment=self.mutate(self.data.save_preference,request)['judgment'] - bindings={k:judgment[k] for k in ('id','prompt_id','parent_revision','source_revision','left_id','left_revision','right_id','right_revision','revision')} - self.mutate(self.data.delete_preference,bindings) - other,_,_=self.cold() - history=other.preference_history(judgment['id'])['history'] - self.assertEqual(len(history),2) - self.assertEqual(history[0]['left']['completion'],' First exact\r\nanswer ') - self.assertTrue(history[-1]['judgment']['deleted']) - self.assertEqual(history[0]['parent'],parent) - - def test_saved_fixed_dynamic_intent_and_tombstones_survive(self): - row=self.text() - selection=self.mutate(self.data.create_selection,dict(name='Chosen revisions',items=[{k:row[k] for k in ('id','revision','source_revision')}])) - search=self.mutate(self.data.create_search,dict(name='Entered criteria',criteria=dict(q='Hello',kind='text',review='',sort='newest',task='',label='',group='',rights=''))) - self.mutate(self.data.rename_search,search['id'],dict(revision=1,name='Renamed criteria')) - self.mutate(self.data.delete_selection,selection['id'],dict(revision=1)) - self.mutate(self.data.delete_search,search['id'],dict(revision=2)) - docs={r['family']:r['document'] for r in self.store.snapshot()['records'] if r['family'].startswith('saved_')} - self.assertTrue(docs['saved_selection']['deleted']);self.assertTrue(docs['saved_search']['deleted']) - self.assertEqual(docs['saved_search']['history'][0]['criteria']['q'],'Hello') - other,_,db=self.cold() - self.assertEqual(other.list_searches(),{'searches':[]}) - self.assertEqual(other.list_selections(),{'selections':[]}) - - def test_image_exact_original_oriented_source_revisions_and_annotation(self): - row,raw=self.image() - row=self.annotate(row,'image_classification',{'label':'red'}) - body=dict(revision=1,book_id='',session_id='image-session',split='train',annotation=dict(book_present=False,crop_suitable=False,corners=[],corner_reference='image')) - saved=self.mutate(self.data.save_image_source,row['id'],body) - self.assertEqual(saved['revision'],2) - other,_,db=self.cold() - actual=other.get(row['id']) - self.assertEqual(actual['source_revision'],2) - self.assertEqual(actual['annotation'],{'label':'red'}) - self.assertEqual((db.path/'images'/row['id']/'source').read_bytes(),raw) - self.assertFalse((db.path/'images'/row['id']/'thumb.jpg').exists()) - - def test_native_mesh_spatial_audio_and_scientific_sources_roundtrip(self): - import meshes,pointclouds,volume_assets - from test_meshes import fixture as mesh_fixture - from test_spatial_storage import source - from test_audio_data import body as audio_body,segment - from test_scientific_fields import fixture as science_fixture,receipt - rows=[] - for kind,prepared in [('mesh',meshes.prepare(*mesh_fixture())),('pointcloud',pointclouds.prepare(*source('pointcloud').values())), - ('volume',volume_assets.prepare(*source('volume').values()))]: - row=self.mutate(self.data.import_bundle,kind,prepared,dict(groups=['native'],rights='Native fixture')) - rows.append(self.annotate(row,{'mesh':'mesh_geometry','pointcloud':'pointcloud_geometry','volume':'volume_grid'}[kind],{'note':'Inspected whole source'})) - audio=self.mutate(self.data.import_audio,audio_body(groups=['audio-fixture'])) - rows.append(self.annotate(audio,'audio_timed',{'segments':[segment()]})) - raw=science_fixture();science=self.mutate(self.data.import_scientific,raw,dict(groups=['science-fixture'],rights='Authored numerical source'),receipt(raw)) - rows.append(self.annotate(science,'field_sequence_fields',{'note':'Inspected exact floating fields'})) - expected={r['id']:self.data.workbench.asset(r['id'])[0] for r in rows} - other,_,db=self.cold() - for row in rows: - with self.subTest(kind=row['kind']): - self.assertEqual(other.get(row['id']),row) - self.assertEqual(other.workbench.asset(row['id'])[0],expected[row['id']]) - self.assertEqual(db.execute('SELECT count(*) FROM workbench_mesh_assets').fetchone()[0],0) - - def test_missing_payload_keeps_metadata_history_and_blocks_consumption(self): - from test_audio_data import body as audio_body - row=self.mutate(self.data.import_audio,audio_body(groups=['audio-fixture'])) - doc=next(r['document'] for r in self.store.snapshot()['records'] if r['family']=='workbench_record') - declaration=next(r['document'] for r in self.store.snapshot()['records'] if r['family']=='project_artifact') - payload=self.store.path/'artifacts'/'sha256'/declaration['sha256'] - payload.unlink() - other,_,_=self.cold() - actual=other.get(row['id']) - self.assertEqual(actual['audio'],doc['current']['audio']) - self.assertFalse(actual['source_available']) - self.assertEqual(other.history(row['id']),[row]) - with self.assertRaises(ValueError) as error:other.workbench.asset(row['id']) - self.assertEqual(error.exception.code,'unavailable') - - def test_agent_draft_scopes_owner_review_and_receipt_authorization(self): - agent=self.access.issue(dict(label='Data fixture',scopes=['inspect','edit'])) - with self.access.bind(agent['token']): - row=self.text() - before=self.store.snapshot() - with self.assertRaises(AccessError):self.annotate(row) - self.assertEqual(self.store.snapshot(),before) - token=self.access.issue(dict(label='Inspect only',scopes=['inspect']))['token'] - with self.access.bind(token),self.assertRaises(AccessError): - self.data.import_text(dict(text='Hello 😀 cafe\u0301\r\n',name='Authored text',groups=['fixture'],rights='Owned fixture'),'0'*64,'op-1') - self.assertNotIn(agent['token'],json.dumps(self.store.snapshot())) - - def test_current_job_data_access_requires_exact_local_admission_and_canonical_window(self): - runtime=Access(self.db,self.db.path) - self.session.runtime_access=runtime - owner=self.access.identity() - self.assertEqual(self.data._authority.identity()['actor_id'],owner['actor_id']) - # Trusted execution creates a local admission; it is never reconstructed - # from any project record. These rows belong only to this private fixture. - admission,job=uuid.uuid4().hex,uuid.uuid4().hex - actor=self.access.require('edit','fixture.job-data') - self.db.execute('INSERT INTO access_admissions VALUES (%s,%s,%s,%s,%s,%s,%s,%s,%s)', - (admission,self.db.dataset_id,actor.actor_id,actor.credential_id,'synthetic',job,'a'*64, - json.dumps({'dataset.add_generated':[job],'workbench.import_asset':[None]}),0)) - before=self.store.snapshot() - with runtime._job('synthetic',job,admission,'a'*64): - self.assertEqual(self.data._authority.identity()['mode'],'job') - self.assertEqual(self.data._authority.require_job('synthetic',job,admission,'a'*64).job_id,job) - with self.assertRaises(WorkbenchError): - self.data.workbench.import_asset(dict(kind='text',text='Unpublished direct job source',groups=['fixture'],rights='Owned')) - self.data._authority.facts=[] - try: - self.assertEqual(self.data._authority.require('edit','dataset.add_generated',job).job_id,job) - with self.assertRaises(AccessError):self.data._authority.require('edit','dataset.add_generated','wrong-job') - with self.assertRaises(AccessError):self.data._authority.require_job('synthetic','wrong-job',admission,'a'*64) - with self.assertRaises(AccessError):self.data._authority.require('approve-review','dataset.add_generated',job,owner_only=True) - self.db.execute('DELETE FROM access_admissions WHERE id=%s',(admission,)) - with self.assertRaises(AccessError):self.data._authority.identity() - with self.assertRaises(AccessError):self.data._authority.require('edit','dataset.add_generated',job) - finally:self.data._authority.facts=None - self.assertEqual(self.store.snapshot(),before) - self.assertEqual(self.db.execute('SELECT count(*) FROM workbench_records').fetchone()[0],0) - - def test_foreign_job_context_and_missing_runtime_bridge_never_assume_host_owner(self): - local=Access(self.db,self.db.path) - actor=self.access.require('edit','fixture.job-data') - admission,job=uuid.uuid4().hex,uuid.uuid4().hex - def insert(db): - db.execute('INSERT INTO access_admissions VALUES (%s,%s,%s,%s,%s,%s,%s,%s,%s)', - (admission,db.dataset_id,actor.actor_id,actor.credential_id,'synthetic',job,'a'*64, - json.dumps({'workbench.import_asset':[None]}),0)) - insert(self.db) - with local._job('synthetic',job,admission,'a'*64): - with self.assertRaises(AccessError):self.data._authority.identity() - self.data._authority.facts=[] - try: - with self.assertRaises(AccessError):self.data.workbench.import_asset(dict(kind='text',text='Missing runtime bridge',groups=['fixture'],rights='Owned')) - finally:self.data._authority.facts=None - foreign_db=self.metadata('foreign-job');foreign=Access(foreign_db,foreign_db.path);insert(foreign_db) - self.session.runtime_access=local - with foreign._job('synthetic',job,admission,'a'*64): - self.data._authority.facts=[] - try: - with self.assertRaises(AccessError):self.data._authority.identity() - with self.assertRaises(AccessError):self.data.workbench.import_asset(dict(kind='text',text='Foreign continuation',groups=['fixture'],rights='Owned')) - finally:self.data._authority.facts=None - insert(self.host) - with self.access._job('synthetic',job,admission,'a'*64): - self.data._authority.facts=[] - try: - with self.assertRaises(AccessError):self.data.workbench.import_asset(dict(kind='text',text='Host catalog job is foreign here',groups=['fixture'],rights='Owned')) - finally:self.data._authority.facts=None - self.assertEqual(self.db.execute('SELECT count(*) FROM workbench_records').fetchone()[0],0) - self.assertEqual(self.data._authority.identity()['actor_id'],actor.actor_id) - - def test_runtime_capture_window_requires_outer_transaction_and_closes_at_outcome(self): - self.session.runtime_access=Access(self.db,self.db.path) - with self.assertRaises(WorkbenchError),self.data.runtime_mutation('data.runtime_grounded_text','window'): - self.fail('An outer SQL transaction is required') - before=self.session.snapshot['records'] - with self.db.transaction(force_rollback=True): - with self.data.runtime_mutation('data.runtime_grounded_text','window'): - row=self.data.workbench.import_asset(dict(kind='text',text='Transaction-scoped authored capture',groups=['fixture'],rights='Owned')) - # The window remains available to the actual before-COMMIT hook. - records=self.data.capture_runtime_changes(before,operation='data.runtime_grounded_text',key='window') - self.assertEqual(records[0]['id'],row['id']) - self.assertEqual(records[0]['document']['events'][0]['operation'],'data.runtime_grounded_text') - self.assertEqual(self.data.capture_runtime_changes(before,operation='data.runtime_grounded_text',key='window'),records) - with self.assertRaises(WorkbenchError):self.data.workbench.import_asset(dict(kind='text',text='No write after capture',groups=['fixture'],rights='Owned')) - self.assertIsNone(self.data._authority.facts) - self.assertEqual(self.db.execute('SELECT count(*) FROM workbench_records').fetchone()[0],0) - self.assertEqual(self.session.snapshot['records'],before) - with self.db.transaction(): - with self.assertRaises(WorkbenchError),self.data.runtime_mutation('unsupported-window','bad'): - self.fail('Only finite owner windows are admitted') - - def test_bad_closed_shapes_and_broken_capture_refuse_before_restore_sql(self): - row=self.text() - snapshot=self.store.snapshot();bad=copy.deepcopy(snapshot) - document=next(r['document'] for r in bad['records'] if r['family']=='workbench_record') - document['source']['original_text']='Altered source' - with self.assertRaises(WorkbenchError):decode_data_records(bad['records']) - self.assertEqual(self.data.get(row['id']),row) - from project_data import _origin - source=dict(kind='text',original_text='Hello 😀 cafe\u0301\r\n') - acquisition=dict(format='tuldok_assets_jsonl_v1',request_id=uuid.uuid4().hex,row_sha256='a'*64, - declared=dict(manifest_name='assets.jsonl',row_number=1)) - origin=dict(row['provenance'],acquisition=acquisition) - _origin(origin,row,source,self.session.snapshot['records']) - origin['acquisition']['declared']['token_sha256']='b'*64 - with self.assertRaises(WorkbenchError):_origin(origin,row,source,self.session.snapshot['records']) - malformed=copy.deepcopy(snapshot) - document=next(r['document'] for r in malformed['records'] if r['family']=='workbench_record') - document['audit'][0]['details']['nested']={'token_sha256':'b'*64} - with self.assertRaises(WorkbenchError):decode_data_records(malformed['records']) - - def test_release_freeze_preserves_exact_zip_manifest_and_cold_bytes(self): - row=self.annotate(self.text()) - body=dict(items=[{k:row[k] for k in ('id','revision','source_revision')}],ratios=dict(train=100,validation=0,test=0),seed=42) - release=self.mutate(self.data.freeze_release,body,key='freeze') - raw=(self.data.releases.path/(release['id']+'.zip')).read_bytes() - self.assertEqual(hashlib.sha256(raw).hexdigest(),release['id']) - other,_,_=self.cold() - self.assertEqual((other.releases.path/(release['id']+'.zip')).read_bytes(),raw) - replay=self.data.freeze_release(body,'0'*64,'freeze') - self.assertEqual(replay,release) - - def test_actual_sql_commit_failure_retains_unique_payload_and_reconstructs(self): - self.db.execute("CREATE FUNCTION fixture_refuse_commit() RETURNS trigger LANGUAGE plpgsql AS $$ BEGIN RAISE EXCEPTION 'deferred fixture' USING ERRCODE='23514'; END $$") - self.db.execute('CREATE CONSTRAINT TRIGGER fixture_commit_failure AFTER INSERT ON workbench_records DEFERRABLE INITIALLY DEFERRED FOR EACH ROW EXECUTE FUNCTION fixture_refuse_commit()') - with self.assertRaises(WorkbenchError) as error:self.image() - self.assertEqual(error.exception.code,'projection_unavailable') - records=self.store.snapshot()['records'] - artifacts=[r['document'] for r in records if r['family']=='project_artifact'] - self.assertTrue(artifacts) - for declaration in artifacts:self.assertEqual(self.artifacts.status(declaration)['state'],'verified') - other,_,_=self.cold() - self.assertEqual(other.query()['total'],1) - - def test_image_peer_split_capture_saved_binding_and_deletion_preserve_artifacts(self): - from project_producers import ProjectProducers - first,_=self.image('red',['shared-session']);second,_=self.image('blue',['shared-session']) - first=self.annotate(first,'image_detection',{'boxes':[dict(label='fixture',x=1,y=1,width=3,height=2)]}) - source_body=dict(revision=1,book_id='',session_id='shared-session',split='train', - annotation=dict(book_present=False,crop_suitable=False,corners=[],corner_reference='image')) - self.mutate(self.data.save_image_source,first['id'],source_body) - peer=self.data.get(second['id']) - self.assertEqual((peer['source_revision'],peer['source_split']),(2,'train')) - selection=self.mutate(self.data.create_selection,dict(name='Intermediate source revision',items=[{k:peer[k] for k in ('id','revision','source_revision')}])) - self.mutate(self.data.save_image_source,second['id'],dict(source_body,revision=2)) - producers=ProjectProducers(self.session);producers.restore(self.session.snapshot) - self.data=ProjectData(self.session,generation_entries=producers.generation_jobs) - deleted=self.mutate(self.data.delete_image_source,first['id'],dict(revision=2)) - self.assertFalse(deleted['record']['source_available']) - self.assertFalse((self.db.path/'images'/first['id']).exists()) - document=next(r['document'] for r in self.store.snapshot()['records'] if r['family']=='workbench_record' and r['id']==first['id']) - self.assertTrue(document['source']['deleted']) - self.assertEqual(len(document['source']['revisions']),2) - for edge in (document['source']['original'],document['source']['oriented']): - declaration=next(r['document'] for r in self.store.snapshot()['records'] if r['family']=='project_artifact' and r['id']==edge['artifact']['sha256']) - self.assertEqual(self.artifacts.status(declaration)['state'],'verified') - other,_,_=self.cold() - self.assertFalse(other.get(first['id'])['source_available']) - self.assertEqual(other.load_selection(selection['id'])['members'][0]['status'],'stale') - - def test_legacy_m1_import_and_annotation_lost_replies_reconcile_after_cutover(self): - from project_text import ProjectText - legacy=ProjectText(self.store,self.db,self.access);legacy.restore() - body=dict(kind='text',text='M1 exactsource',name='Legacy original',groups=['legacy'],rights='Owned') - initial=legacy.checkpoint - old=legacy.import_text(body,initial,'legacy-import') - annotation=dict(revision=1,source_revision=1,task='text_classification',annotation={'label':'oldlabel'},groups=['legacy'],review='human_reviewed') - prior=legacy.checkpoint - reviewed=legacy.annotate(old['id'],annotation,prior,'legacy-annotate') - self.session.adopt(self.store.snapshot());self.data=ProjectData(self.session) - self.text('A new M2 source') - checkpoint=self.session.snapshot['checkpoint'] - replay=self.data.import_text(body,initial,'legacy-import') - self.assertEqual(replay['id'],old['id']);self.assertEqual(replay['revision'],1) - self.assertEqual(self.data.annotate(old['id'],annotation,prior,'legacy-annotate')['revision'],2) - with self.assertRaises(WorkbenchError) as error: - self.data.import_text(dict(body,text='different'),initial,'legacy-import') - self.assertEqual(error.exception.code,'conflict') - self.assertEqual(self.session.snapshot['checkpoint'],checkpoint) - with self.assertRaises(WorkbenchError) as error: - self.mutate(self.data.correct_rights_note,old['id'],dict(revision=2,source_revision=1,note='No implicit conversion')) - self.assertEqual(error.exception.code,'unsupported') - self.assertEqual(self.data.query()['total'],2) - new_annotation=dict(annotation,revision=2,annotation={'label':'M2 retained café'}) - current=self.mutate(self.data.annotate,old['id'],new_annotation,key='new-legacy-annotation') - self.assertEqual(current['revision'],3) - self.assertEqual(next(r['family'] for r in self.session.snapshot['records'] if r['id']==old['id']),'workbench_text') - replay=self.data.annotate(old['id'],new_annotation,'0'*64,'new-legacy-annotation') - self.assertEqual(replay,current) - other,_,_=self.cold() - self.assertEqual(other.get(old['id']),current) - document=next(r['document'] for r in self.session.snapshot['records'] if r['id']==old['id']) - self.assertEqual(other.history(old['id']),list(reversed(document['history']))) - - def test_sequence_uses_its_existing_owner_and_exact_bundle(self): - from test_sequences import fixture - from sequence_assets import SequenceAssets - files={name:base64.b64encode(raw).decode() for name,raw in zip(('run.json','frames.jsonl'),fixture())} - prepared=SequenceAssets.prepare_project_files(files) - with self.assertRaises(WorkbenchError):SequenceAssets.prepare_project_files(dict(files,unexpected='')) - with self.assertRaises(WorkbenchError):SequenceAssets.prepare_project_files(dict(files,**{'run.json':'not base64'})) - row=self.mutate(self.data.import_bundle,'sequence',prepared,dict(groups=['sequence-fixture'],rights='Source-derived authored fixture')) - other,_,_=self.cold() - self.assertEqual(other.get(row['id']),row) - self.assertEqual(other.workbench.asset(row['id'])[0],prepared['bundle']) - - def test_forged_well_shaped_receipt_result_is_not_a_retained_revision(self): - row=self.text();forged=copy.deepcopy(row);forged['name']='Valid text but never authored' - with self.assertRaisesRegex(WorkbenchError,'retained'): - validate_operation_result('data.import_text',forged,self.store.snapshot()['records']) - - def test_corrupt_payload_and_metadata_refuse_reconstruction_before_sql(self): - from test_audio_data import body as audio_body - row=self.mutate(self.data.import_audio,audio_body(groups=['audio-fixture'])) - snapshot=self.store.snapshot();modified=copy.deepcopy(snapshot['records']) - document=next(r['document'] for r in modified if r['family']=='workbench_record') - document['source']['metadata']['sample_rate_hz']=0 - with self.assertRaises(WorkbenchError):decode_data_records(modified) - declaration=next(r['document'] for r in snapshot['records'] if r['family']=='project_artifact') - payload=self.store.path/'artifacts'/'sha256'/declaration['sha256'] - payload.chmod(0o600) - payload.write_bytes(b'changed') - fresh=self.metadata('invalid-cold');session=ProjectSession(self.store,fresh,self.access,self.artifacts,validate_records=validate) - adapter=ProjectData(session) - with self.assertRaises(WorkbenchError):adapter.restore() - self.assertEqual(fresh.execute('SELECT count(*) FROM workbench_records').fetchone()[0],0) - - def test_release_variants_and_freeze_only_agent_keep_exact_owner_outputs(self): - # Exercise the persisted variant decoder, not just legacy release code. - labeled=[] - for index in range(6): - row=self.mutate(self.data.import_text,dict(text=f'Independent class source {index}',groups=[f'class-fixture-{index}'],rights='Authored source')) - labeled.append(self.annotate(row,annotation={'label':'greeting' if index%2 else 'other'})) - def freeze(body): - preview=self.data.preview_release(body) - self.assertTrue(preview['eligible'],preview.get('blockers')) - return self.mutate(self.data.freeze_release,dict(body,preview_token=preview['preview_token'])) - ratio=dict(train=100,validation=0,test=0) - request=dict(format='text_classification_v1',items=[{k:r[k] for k in ('id','revision','source_revision')} for r in labeled],ratios=dict(train=34,validation=33,test=33),seed=42) - for seed in range(100): - request['seed']=seed - if self.data.preview_release(request)['eligible']:break - agent=self.access.issue(dict(label='Freeze only',scopes=['inspect','freeze'])) - with self.access.bind(agent['token']): - frozen=freeze(request) - self.assertEqual(frozen['records'],6) - parent=self.text('Prompt for exact archived answers') - answers=[] - for text in ('Chosen answer','Other answer'): - answers.append(self.mutate(self.data.save_response,dict(id=uuid.uuid4().hex,prompt_id=parent['id'],revision=0,parent_revision=1, - source_revision=1,completion=text,review='human_reviewed'))['response']) - response_ref=dict(id=answers[0]['id'],revision=1,prompt_id=parent['id'],parent_revision=1,source_revision=1) - instruction=freeze(dict(format='text_instruction_v1',items=[response_ref],ratios=ratio,seed=42)) - judgment=self.mutate(self.data.save_preference,dict(id=uuid.uuid4().hex,prompt_id=parent['id'],parent_revision=1,source_revision=1, - left_id=answers[0]['id'],left_revision=1,right_id=answers[1]['id'],right_revision=1,revision=0,outcome='left',rationale='Explicit selected answer',review='human_reviewed'))['judgment'] - ref={k:judgment[k] for k in ('id','prompt_id','parent_revision','source_revision','left_id','left_revision','right_id','right_revision','revision')} - preference=freeze(dict(format='text_preference_v1',items=[ref],ratios=ratio,seed=42)) - captions=[] - for index,color in enumerate(('red','blue','green')): - image,_=self.image(color,[f'caption-session-{index}']) - captions.append(self.annotate(image,'image_caption',{'caption':f'A small {color} fixture'})) - caption_request=dict(format='image_caption_v1',items=[{k:r[k] for k in ('id','revision','source_revision')} for r in captions],ratios=dict(train=34,validation=33,test=33),seed=42) - for seed in range(100): - caption_request['seed']=seed - if self.data.preview_release(caption_request)['eligible']:break - caption_release=freeze(caption_request) - other,_,_=self.cold() - for release in (frozen,instruction,preference,caption_release): - self.assertEqual((other.releases.path/(release['id']+'.zip')).read_bytes(),(self.data.releases.path/(release['id']+'.zip')).read_bytes()) - - -if __name__=='__main__':unittest.main() diff --git a/tests/test_project_data_fork.py b/tests/test_project_data_fork.py deleted file mode 100644 index a63da59f..00000000 --- a/tests/test_project_data_fork.py +++ /dev/null @@ -1,123 +0,0 @@ -"""Pure independent data construction, checked with real owner/PG fixtures.""" -import copy -import uuid -import unittest - -from project_data import decode_data_records -from project_data_fork import fork_records, validate_records -from project_fork import ARCHIVE_FAMILIES, _digest, _input, active_records -from workbench import WorkbenchError -import test_project_data as data_fixture - - -class DataForkTests(unittest.TestCase): - def setUp(self): - self.fixture=data_fixture.ProjectDataTests('test_text_annotation_rights_history_retry_and_cold_projection') - self.fixture.setUp();self.addCleanup(self.fixture.doCleanups) - - def fork(self, records=None, source=None): - f=self.fixture; snap=f.session.snapshot - records=copy.deepcopy(records if records is not None else snap['records']) - source=source or snap['project_id'];destination=uuid.uuid4().hex - made=fork_records(records,source,snap['checkpoint'],destination, - id_factory=lambda *key:uuid.uuid4().hex,created_at='2026-10-22T12:00:00+00:00') - origin=dict(project_id=source,checkpoint=snap['checkpoint']) - doc=dict(format='project_fork_v1',source=origin,destination_project_id=destination, - request_key='fork-fixture',directory='fork-fixture',name='Derived fixture', - request_sha256=_digest(_input(origin,'fork-fixture','Derived fixture','fork-fixture')), - mapping=made['mapping'],archived=sorted([dict(family=r['family'],id=r['id']) for r in records if r['family'] in ARCHIVE_FAMILIES],key=lambda x:(x['family'],x['id'])), - artifacts=dict(copied=sorted(r['id'] for r in records if r['family']=='project_artifact'),missing_regenerable=[])) - combined=records+made['records']+[dict(family='project_fork',id=destination,document=doc)] - decode_data_records(combined);validate_records(combined) - return made,combined,destination - - def test_all_modality_sources_keep_exact_bytes_metadata_and_fresh_drafts(self): - f=self.fixture - text=f.annotate(f.text());image,_=f.image();f.annotate(image,'image_detection',{'boxes':[dict(label='fixture',x=1,y=1,width=2,height=2)]}) - import meshes,pointclouds,volume_assets - from test_meshes import fixture as mesh_source - from test_spatial_storage import source - from sequence_assets import SequenceAssets - from test_sequences import fixture as sequence_source - import base64 - for kind,prepared in [('mesh',meshes.prepare(*mesh_source())),('pointcloud',pointclouds.prepare(*source('pointcloud').values())),('volume',volume_assets.prepare(*source('volume').values())), - ('sequence',SequenceAssets.prepare_project_files({name:base64.b64encode(raw).decode() for name,raw in zip(('run.json','frames.jsonl'),sequence_source())}))]: - f.mutate(f.data.import_bundle,kind,prepared,dict(groups=['fork-native'],rights='Owned native fixture')) - from test_audio_data import body - f.mutate(f.data.import_audio,body(groups=['fork-audio'])) - from test_scientific_fields import fixture as scientific_source,receipt - raw=scientific_source();f.mutate(f.data.import_scientific,raw,dict(groups=['fork-fields'],rights='Owned fields'),receipt(raw)) - original=f.session.snapshot['records'];unchanged=copy.deepcopy(original) - made,combined,destination=self.fork() - self.assertEqual(original,unchanged) - self.assertEqual({r['document']['current']['kind'] for r in made['records']},{'text','image','sequence','mesh','pointcloud','volume','audio','field_sequence'}) - self.assertTrue(all(r['document']['current']['review']=='draft' for r in made['records'])) - self.assertTrue(all(r['document']['current']['revision']==1 and r['document']['current']['source_revision']==1 for r in made['records'])) - self.assertTrue(all(not r['document']['audit'] and not r['document']['events'] for r in made['records'])) - self.assertEqual(len(active_records(combined,project_id=destination)),len(made['records'])+sum(r['family'] not in ARCHIVE_FAMILIES for r in original)+1) - with self.assertRaises(WorkbenchError):decode_data_records(made['records']+[r for r in original if r['family']=='project_artifact']) - - def test_response_versions_preferences_and_saved_intent_have_exact_new_bindings(self): - f=self.fixture;parent=f.text();responses=[] - for value in ('Original chosen answer','Other original answer'): - responses.append(f.mutate(f.data.save_response,dict(id=uuid.uuid4().hex,prompt_id=parent['id'],revision=0,parent_revision=1,source_revision=1,completion=value,review='human_reviewed'))['response']) - judgment=f.mutate(f.data.save_preference,dict(id=uuid.uuid4().hex,prompt_id=parent['id'],parent_revision=1,source_revision=1,left_id=responses[0]['id'],left_revision=1,right_id=responses[1]['id'],right_revision=1,revision=0,outcome='left',rationale='Original comparison',review='human_reviewed'))['judgment'] - f.mutate(f.data.save_response,dict(id=responses[0]['id'],prompt_id=parent['id'],revision=1,parent_revision=1,source_revision=1,completion='Later different answer',review='human_reviewed')) - f.mutate(f.data.create_selection,dict(name='Original fixed membership',items=[dict(id=parent['id'],revision=1,source_revision=1)])) - search=f.mutate(f.data.create_search,dict(name='Retired criteria',criteria=dict(q='',kind='text',review='',sort='newest',task='',label='',group='',rights=''))) - f.mutate(f.data.delete_search,search['id'],dict(revision=1)) - made,combined,_=self.fork() - answers=[r['document']['current'] for r in made['records'] if r['family']=='workbench_response'] - self.assertEqual({r['completion'] for r in answers},{'Original chosen answer','Other original answer','Later different answer'}) - self.assertEqual(sum(m['source_id']==responses[0]['id'] for m in made['mapping']),2) - pref=next(r['document'] for r in made['records'] if r['family']=='workbench_preference') - self.assertEqual(pref['history'][0]['left']['completion'],'Original chosen answer') - self.assertEqual(pref['current']['review'],'draft') - self.assertFalse(any(r['family']=='saved_search' for r in made['records'])) - forged=copy.deepcopy(combined) - document=next(r['document'] for r in forged if r['family']=='workbench_preference' and r['id']==pref['current']['id']) - document['history'][0]['left']['completion']='Forged different comparison' - with self.assertRaises(WorkbenchError):decode_data_records(forged) - - def test_deleted_sources_remain_archived_and_live_child_keeps_exact_ancestry(self): - f=self.fixture - from project_producers import ProjectProducers - image,_=f.image();parent=f.text('Independent authored parent') - child=f.mutate(f.data.import_text,dict(text='Derived from deleted image',name='Derived text',groups=['ancestry'],parents=[image['id'],parent['id']],rights='Owned derived text')) - producers=ProjectProducers(f.session);producers.restore(f.session.snapshot) - from project_data import ProjectData - f.data=ProjectData(f.session,generation_entries=producers.generation_jobs) - f.mutate(f.data.delete_image_source,image['id'],dict(revision=1)) - made,combined,_=self.fork() - self.assertFalse(any(m['source_id']==image['id'] for m in made['mapping'])) - fresh=next(r['document']['current'] for r in made['records'] if r['document']['current']['text']==child['text']) - self.assertIn(image['id'],fresh['parents']) - self.assertNotIn(parent['id'],fresh['parents']) - self.assertTrue(any(r['id']==image['id'] for r in combined)) - - def test_legacy_text_explicit_conversion_and_forged_origin_refuse(self): - f=self.fixture - from project_text import ProjectText - legacy=ProjectText(f.store,f.db,f.access);legacy.restore() - row=legacy.import_text(dict(text='M1 fork source',name='Original legacy',groups=['legacy'],rights='Owned'),legacy.checkpoint,'legacy-fork-source') - f.session.adopt(f.store.snapshot()) - original=f.session.snapshot['records'];made,combined,_=self.fork() - self.assertEqual(made['records'][0]['family'],'workbench_record') - self.assertEqual(made['mapping'][0]['family'],'workbench_text') - self.assertEqual(combined[0],original[0]) - forged=copy.deepcopy(combined) - record=next(r for r in forged if r['id']==made['records'][0]['id']) - for value in [record['document']['origin'],record['document']['current']['provenance'],record['document']['history'][0]['provenance']]:value['origin']['checkpoint']='f'*64 - with self.assertRaises(WorkbenchError):decode_data_records(forged) - - def test_nested_fork_has_fresh_ids_and_exact_prior_archives(self): - f=self.fixture;f.text() - first,records,identity=self.fork() - old=copy.deepcopy(records) - second,combined,_=self.fork(records,identity) - self.assertTrue(set(r['id'] for r in first['records']).isdisjoint(r['id'] for r in second['records'])) - self.assertEqual(combined[:len(old)],old) - self.assertEqual(second['records'][0]['document']['origin']['origin']['project_id'],identity) - - -if __name__=='__main__':unittest.main() diff --git a/tests/test_project_dispatch.py b/tests/test_project_dispatch.py deleted file mode 100644 index 1aee28e5..00000000 --- a/tests/test_project_dispatch.py +++ /dev/null @@ -1,334 +0,0 @@ -"""Fixed consumer composition evidence, separate from canonical owner I/O tests.""" -import copy -from types import SimpleNamespace -import unittest -from unittest.mock import Mock - -import agent_api -from pipeline import decode_graph -from project_dispatch import SUPPORTED_OPERATIONS, dispatch -from project_material import ProjectMaterial -from workbench import WorkbenchError - -PROJECT, RECORD, ORIGIN = 'a' * 32, 'b' * 32, 'c' * 32 -CHECKPOINT, SHA = 'd' * 64, 'e' * 64 -BOUND = dict(binding='f' * 32, expected_checkpoint=CHECKPOINT, request_key='dispatch-fixture-1') -READ = dict(binding='f' * 32, checkpoint=CHECKPOINT) - - -class Authority: - def __init__(self, deny_owner=False): - self.calls = [] - self.deny_owner = deny_owner - - def require(self, *args, **kwargs): - self.calls.append((args, kwargs)) - if kwargs.get('owner_only') and self.deny_owner: - raise WorkbenchError('Current owner authority is required.', 'forbidden', 403) - return SimpleNamespace(actor_id=PROJECT) - - -def projection(): - access = Authority() - session = SimpleNamespace(access=access, check=Mock(), check_current=Mock(), snapshot={'project_id': PROJECT, 'records': []}, - summary={'project_id': PROJECT, 'name': 'Dispatch fixture', 'checkpoint': CHECKPOINT}) - return SimpleNamespace(session=session, data=Mock(), materials=Mock(), history=Mock(), - context=SimpleNamespace(models=Mock(), pipelines=Mock()), artifacts=Mock(), - producers=Mock(), source_adapter=Mock(), runtime_manifest=Mock(), disclose=Mock(), resolve_artifact=Mock(), execution=SimpleNamespace(study_execution=Mock(), producer_execution=Mock(), health=Mock(), preflight_external=Mock(), approve_external=Mock(), submit_external=Mock(), cancel_run=Mock(), reconcile_current=Mock())) - - -class Dispatch(unittest.TestCase): - def test_supported_operations_match_the_finite_public_contract(self): - self.assertEqual(SUPPORTED_OPERATIONS, agent_api.PROJECT_FILES_M2 | agent_api.PROJECT_FILES_M3 | (agent_api.PROJECT_FILES_M4 - {'project_files.save_as', 'project_files.compose'})) - with self.assertRaises(WorkbenchError) as failure: - dispatch(object(), 'project_files.runs_execute', {}) - self.assertEqual(failure.exception.code, 'unsupported') - - def test_current_execution_dispatch_is_finite_and_returns_native_values(self): - selected = projection() - selected.execution.preflight_external.return_value = {'material_sha256': SHA} - arguments = dict(READ, graph_id=RECORD, revision=3) - agent_api.validate_arguments('project_files.execution_preflight_external', arguments) - self.assertEqual(dispatch(selected, 'project_files.execution_preflight_external', arguments), {'material_sha256': SHA}) - selected.execution.preflight_external.assert_called_once_with(RECORD, 3) - arguments = dict(BOUND, family='text_proposal_history', producer_id=RECORD, - document={'revision': 2, 'decision': 'apply_draft', 'labels': ['stable']}) - agent_api.validate_arguments('project_files.execution_producer_decide', arguments) - dispatch(selected, 'project_files.execution_producer_decide', arguments) - selected.execution.producer_execution.decide.assert_called_once_with('text_proposal_history', RECORD, - arguments['document'], CHECKPOINT, BOUND['request_key']) - arguments = dict(binding=READ['binding'], expected_checkpoint=CHECKPOINT) - agent_api.validate_arguments('project_files.execution_reconcile_current', arguments) - dispatch(selected, 'project_files.execution_reconcile_current', arguments) - selected.execution.reconcile_current.assert_called_once_with() - self.assertEqual(agent_api.contract('project_files.execution_reconcile_current')['retry'], 'never') - with self.assertRaises(agent_api.AgentAPIError): - agent_api.validate_arguments('project_files.execution_reconcile_current', dict(arguments, request_key='invented')) - - def test_missing_current_adapters_refuse_before_any_effect(self): - selected = projection() - selected.execution.study_execution = None - with self.assertRaises(WorkbenchError) as failure: - dispatch(selected, 'project_files.execution_study_stop', dict(BOUND, study_id=RECORD, revision=2)) - self.assertEqual((failure.exception.code, failure.exception.status), ('unavailable', 409)) - selected.execution.producer_execution = None - with self.assertRaises(WorkbenchError) as failure: - dispatch(selected, 'project_files.execution_producer_cancel', dict(BOUND, family='grounded_history', producer_id=RECORD)) - self.assertEqual(failure.exception.code, 'unavailable') - selected.execution = None - with self.assertRaises(WorkbenchError) as failure: - dispatch(selected, 'project_files.execution_health', READ) - self.assertEqual(failure.exception.code, 'unavailable') - - def test_native_producer_grammars_refuse_wrong_family_documents(self): - base = dict(BOUND, family='caption_proposal_history', document=dict(request_id=RECORD, - source_id=PROJECT, revision=2, source_revision=1, server_url='http://127.0.0.1:12345', - model='current-model', instruction='Describe the captured image', seed=1)) - agent_api.validate_arguments('project_files.execution_producer_start', base) - typed = copy.deepcopy(base); typed['document'].update(protocol='pumas_typed_v1', profile=None, seed=None) - agent_api.validate_arguments('project_files.execution_producer_start', typed) - for change in ({'family': 'generation_history'}, {'family': 'arbitrary_callable'}, - {'document': dict(base['document'], credential='not-accepted')}): - with self.assertRaises(agent_api.AgentAPIError): - agent_api.validate_arguments('project_files.execution_producer_start', dict(base, **change)) - with self.assertRaises(agent_api.AgentAPIError): - agent_api.validate_arguments('project_files.execution_submit_external', dict(BOUND, - graph_id=RECORD, graph_revision=1, expected_digest=SHA, request_key='short')) - - def test_metadata_calls_preserve_native_body_and_canonical_arguments(self): - selected = projection() - selected.data.correct_rights_note.return_value = {'changed': True} - arguments = dict(BOUND, record_id=RECORD, revision=3, source_revision=1, note='Unique authored rights note') - agent_api.validate_arguments('project_files.data_rights', arguments) - self.assertEqual(dispatch(selected, 'project_files.data_rights', arguments), {'changed': True}) - selected.data.correct_rights_note.assert_called_once_with(RECORD, - {'revision': 3, 'source_revision': 1, 'note': 'Unique authored rights note'}, CHECKPOINT, BOUND['request_key']) - selected.history.prepare_trial_from_material.return_value = {'id': RECORD} - ref = dict(kind='recipe_material', catalog_id=ORIGIN, id=SHA, sha256=SHA) - arguments = dict(BOUND, study_id=RECORD, revision=2, material=ref, replicate=0) - dispatch(selected, 'project_files.trial_prepare', arguments) - selected.history.prepare_trial_from_material.assert_called_once_with(RECORD, - {'revision': 2, 'material': ref, 'replicate': 0}, CHECKPOINT, BOUND['request_key']) - - def test_external_graph_creation_uses_canonical_material_boundary(self): - selected = projection() - body = {'name': 'New external scientific recipe', 'project_id': RECORD, - 'recipe_id': 'owned_recipe', 'expected_sha256': SHA, 'inputs': {}, 'parameters': {}} - arguments = dict(BOUND, **body) - agent_api.validate_arguments('project_files.graph_create_external', arguments) - selected.materials.mutate_definition.side_effect = lambda family, operation, target, value, cp, key, invoke: invoke() - selected.context.pipelines.create_external.return_value = {'id': RECORD, 'revision': 1} - result = dispatch(selected, 'project_files.graph_create_external', arguments) - self.assertEqual(result, {'id': RECORD, 'revision': 1}) - selected.context.pipelines.create_external.assert_called_once_with(body) - captured = selected.materials.mutate_definition.call_args.args - self.assertEqual(captured[:6], ('pipeline_graph', 'graphs.create_external', None, - body, CHECKPOINT, BOUND['request_key'])) - - def test_project_graph_inputs_reuse_current_domain_grammar_without_legacy_changes(self): - from contextlib import nullcontext - import threading - from pipeline import Pipelines - for project, domain in (('graph_create', 'graphs.create'), - ('graph_create_external', 'graphs.create_external'), - ('graph_save', 'graphs.save')): - expected = copy.deepcopy(agent_api.operation(domain)['inputSchema']) - expected['properties'].update(copy.deepcopy(agent_api._PROJECT_FILES_MUTATION)) - expected['required'] = list(dict.fromkeys(expected['required'] + list(agent_api._PROJECT_FILES_MUTATION))) - self.assertEqual(agent_api.operation('project_files.' + project)['inputSchema'], expected) - # The real metadata owner authors each model graph without a worker or - # runtime. Only its SQL transaction sink is substituted in this grammar test. - owner = object.__new__(Pipelines) - owner.lock = threading.RLock() - owner.access = Mock() - owner.db = SimpleNamespace(transaction=lambda: nullcontext(), execute=Mock()) - for recipe in ('image_classification_model_v2', 'text_classification_model_v2', 'audio_classification_model_v2'): - body = {'name': 'Current typed model graph', 'release_id': SHA, 'recipe': recipe} - graph = owner.create(body) - agent_api.validate_arguments('project_files.graph_create', dict(BOUND, **body)) - agent_api.validate_arguments('project_files.graph_save', dict(BOUND, - graph_id=graph['id'], revision=graph['revision'], document=graph)) - with self.assertRaises(agent_api.AgentAPIError): - agent_api.validate_arguments('graphs.create', body, version=1) - self.assertEqual(agent_api.REGISTRY_DIGEST, agent_api._LEGACY_DIGEST) - - def test_history_pages_are_bounded_and_keep_exact_owner_snapshots(self): - selected = projection() - snapshots = [{'id': RECORD, 'revision': revision, 'text': '\U0001f9ea' * 200000} - for revision in range(6, 0, -1)] - selected.data.history.return_value = snapshots - arguments = dict(READ, record_id=RECORD, offset=1, limit=4) - value = dispatch(selected, 'project_files.data_history', arguments) - self.assertEqual(value, {'items': snapshots[1:5], 'total': 6, 'offset': 1, 'limit': 4}) - agent_api.validate_output('project_files.data_history', {'status': 200, 'result': { - 'binding': READ['binding'], 'project_id': PROJECT, 'checkpoint': CHECKPOINT, 'value': value}}) - self.assertLess(len(agent_api.encoded(value, ensure_ascii=False)), agent_api.RESPONSE_LIMIT) - with self.assertRaises(WorkbenchError): - dispatch(selected, 'project_files.data_history', dict(arguments, limit=5)) - - def test_study_summary_pages_membership_without_losing_full_charge_totals(self): - selected = projection() - trial_ids = [format(index, '032x') for index in range(10000)] - original = {'study': {'format': 'study_v1', 'id': RECORD, 'name': 'Scientific intent', - 'revision': 3, 'trial_ids': trial_ids}, - 'reservations': [], 'charged': {'attempt_slots': 10000}, - 'revision_history_complete': True, - 'page': {'offset': 40, 'limit': 20, 'total': 0, 'study_revision': 3, 'next_offset': None}} - selected.history.study.return_value = original - result = dispatch(selected, 'project_files.study', dict(READ, study_id=RECORD, - origin_catalog_id=ORIGIN, offset=40, limit=20, revision=3)) - self.assertNotIn('trial_ids', result['study']) - self.assertEqual(result['study']['source_format'], 'study_v1') - self.assertEqual(result['study']['trial_count'], 10000) - self.assertEqual(result['trials'], {'items': [{'id': identity} for identity in trial_ids[40:60]], - 'total': 10000, 'offset': 40, 'limit': 20}) - self.assertEqual(result['charged'], {'attempt_slots': 10000}) - self.assertEqual(original['study']['trial_ids'], trial_ids) - - def test_material_replay_still_checks_current_reconciliation_authority(self): - selected = projection() - selected.session.access = Authority(deny_owner=True) - selected.session.mutate = Mock(return_value={'ref': {'sha256': SHA}}) - selected.materials = ProjectMaterial(selected.session) - arguments = dict(BOUND, model_id=RECORD, revision=1, reconcile_capture=True) - with self.assertRaises(WorkbenchError) as failure: - dispatch(selected, 'project_files.model_publish', arguments) - self.assertEqual(failure.exception.code, 'forbidden') - selected.session.mutate.assert_not_called() - selected.context.models.publish.assert_not_called() - # Ordinary publication retains its actual edit-agent policy and may - # reconcile an original durable result without invoking the publisher. - result = dispatch(selected, 'project_files.model_publish', dict(arguments, reconcile_capture=False)) - self.assertEqual(result, {'ref': {'sha256': SHA}}) - selected.session.mutate.assert_called_once() - selected.context.models.publish.assert_not_called() - - def test_current_owner_root_choice_and_local_disclosure_use_their_owners(self): - selected = projection() - selected.session.access = Authority(deny_owner=True) - with self.assertRaises(WorkbenchError): - dispatch(selected, 'project_files.source_register', dict(BOUND, root='fixture', manifest_path='owned/manifest.json')) - selected.source_adapter.register.assert_not_called() - selected = projection() - dispatch(selected, 'project_files.expose_holdout', dict(BOUND, run_id=RECORD, origin_catalog_id=ORIGIN, reason='Review held-out diagnostics')) - selected.disclose.assert_called_once_with(RECORD, {'origin_catalog_id': ORIGIN, 'reason': 'Review held-out diagnostics'}, CHECKPOINT, BOUND['request_key']) - selected.history.record_disclosure.assert_not_called() - - def test_explicit_preparation_keeps_runtime_and_sequence_semantics_with_owners(self): - selected = projection() - files = {'owned-input': 'original opaque bytes'} - prepared = {'bundle': b'validated native source'} - selected.data.workbench.sequences.prepare_project_files.return_value = prepared - arguments = dict(BOUND, files=files, groups=['fixture'], rights='Authored') - dispatch(selected, 'project_files.data_import_sequence', arguments) - selected.data.workbench.sequences.prepare_project_files.assert_called_once_with(files) - selected.data.import_bundle.assert_called_once_with('sequence', prepared, - {'files': files, 'groups': ['fixture'], 'rights': 'Authored'}, CHECKPOINT, BOUND['request_key']) - ref = {'kind': 'model', 'catalog_id': PROJECT, 'id': RECORD, 'revision': 1, 'sha256': SHA} - selected.context.pipelines.get.return_value = decode_graph({ - 'schema_version': 1, 'mode': 'real', 'recipe': 'external_recipe', 'recipe_version': 1, - 'id': RECORD, 'revision': 1, 'name': 'External preparation fixture', 'layout': {}, - 'nodes': [ - {'id': 'input', 'type': 'input', 'definition_version': 1, 'parameters': { - 'project_id': ORIGIN, 'recipe_id': 'neutral', 'expected_sha256': SHA, 'inputs': {}}}, - {'id': 'execute', 'type': 'execute', 'definition_version': 1, 'parameters': {}}, - {'id': 'output', 'type': 'output', 'definition_version': 1, 'parameters': {}}], - 'edges': [{'from': 'input', 'output': 'data', 'to': 'execute', 'input': 'data'}, - {'from': 'execute', 'output': 'artifacts', 'to': 'output', 'input': 'artifacts'}]}) - dispatch(selected, 'project_files.recipe_prepare', dict(BOUND, graph_id=RECORD, revision=1, model=ref)) - selected.context.pipelines.get.assert_called_once_with(RECORD) - selected.materials.prepare_recipe.assert_called_once_with(selected.context.pipelines, RECORD, 1, ref, - CHECKPOINT, BOUND['request_key'], builtin=False, reconcile_capture=False, runtime_manifest=selected.runtime_manifest) - - def test_producer_inspection_preserves_origin_and_entry_pagination(self): - selected = projection() - args = dict(READ, family='generation_history', origin_catalog_id=ORIGIN, producer_id=RECORD, - entries_offset=40, entries_limit=20) - agent_api.validate_arguments('project_files.producer', args) - dispatch(selected, 'project_files.producer', args) - selected.producers.get.assert_called_once_with('generation_history', RECORD, - origin_catalog_id=ORIGIN, entries_offset=40, entries_limit=20) - selected.producers.capture.assert_not_called() - - def test_run_summary_keeps_counts_and_exact_document_without_unbounded_collections(self): - selected = projection() - large = [{'state': 'observed', 'message': 'unique observation'}] * 100000 - selected.history.run.return_value = { - 'origin_catalog_id': ORIGIN, 'historical': True, 'execution_available': False, - 'evidence': 'unverified', 'run': {'schema_version': 1, 'id': RECORD, 'state': 'completed', - 'events': large, 'material': {'captured': 'large exact original document'}}, - 'payloads': [], 'disclosures': [], 'document': {'sha256': SHA, 'bytes': 20000000}, - 'page': {'offset': 40, 'limit': 20, 'total': 0, 'next_offset': None, - 'disclosures_total': 0, 'disclosures_next_offset': None}} - result = dispatch(selected, 'project_files.run', dict(READ, origin_catalog_id=ORIGIN, - run_id=RECORD, offset=40, limit=20)) - self.assertEqual(result['run']['state'], 'completed') - self.assertEqual(result['run']['collection_counts']['events'], 100000) - self.assertNotIn('events', result['run']) - self.assertNotIn('material', result['run']) - self.assertEqual(result['document'], {'sha256': SHA, 'bytes': 20000000}) - self.assertLess(len(agent_api.encoded(result)), 4096) - selected.history.run.assert_called_once_with(RECORD, origin_catalog_id=ORIGIN, offset=40, limit=20) - - def test_document_segments_delegate_exact_hash_and_current_origin(self): - selected = projection() - arguments = dict(READ, run_id=RECORD, origin_catalog_id=ORIGIN, expected_sha256=SHA, - offset=262144, limit=262144) - agent_api.validate_arguments('project_files.run_document_segment', arguments) - dispatch(selected, 'project_files.run_document_segment', arguments) - selected.history.run_document_segment.assert_called_once_with(RECORD, origin_catalog_id=ORIGIN, - expected_sha256=SHA, offset=262144, limit=262144) - # Source listing is a current binding-aware owner read, not manifest - # inference in a client or a generic walk of archived source records. - reference = dict(origin_catalog_id=ORIGIN, project_id=RECORD, manifest_sha256=SHA) - dispatch(selected, 'project_files.source_references', dict(READ, **reference, offset=40, limit=20)) - selected.source_adapter.references.assert_called_once_with(reference, offset=40, limit=20) - - def test_artifact_resolution_requires_current_owner_before_the_custody_seam(self): - selected = projection() - selected.session.access = Authority(deny_owner=True) - arguments = dict(BOUND, sha256=SHA, root='fixture', path='observations/unique.bin') - agent_api.validate_arguments('project_files.artifact_resolve', arguments) - with self.assertRaises(WorkbenchError): - dispatch(selected, 'project_files.artifact_resolve', arguments) - selected.resolve_artifact.assert_not_called() - selected.session.access = Authority() - dispatch(selected, 'project_files.artifact_resolve', arguments) - selected.resolve_artifact.assert_called_once_with( - {'sha256': SHA, 'root': 'fixture', 'path': 'observations/unique.bin'}, CHECKPOINT, BOUND['request_key']) - self.assertEqual(agent_api.contract('project_files.artifact_resolve')['authority'], 'owner') - - def test_artifact_inventory_never_opens_or_invents_payload_bytes(self): - selected = projection() - declaration = dict(format='project_artifact_v1', sha256=SHA, bytes=17) - selected.session.snapshot['records'] = [{'family': 'project_artifact', 'id': SHA, 'document': declaration}] - selected.artifacts.inspect.return_value = {'state': 'missing', 'expected_bytes': 17} - value = dispatch(selected, 'project_files.artifacts', READ) - self.assertEqual(value['items'][0]['availability']['state'], 'missing') - self.assertEqual(value['items'][0]['bytes'], 17) - selected.artifacts.read_blob.assert_not_called() - selected.artifacts.publish_bytes.assert_not_called() - with self.assertRaises(WorkbenchError) as failure: - dispatch(selected, 'project_files.artifact_status', dict(READ, sha256='0' * 64)) - self.assertEqual(failure.exception.status, 404) - - -class BooleanQueries(unittest.TestCase): - def test_sdk_and_http_select_canonical_boolean_queries(self): - name = 'project_files.candidate' - selection = (name, 1, agent_api.contract(name)['sha256']) - for value in (False, True): - arguments = dict(READ, candidate_id=RECORD, origin_catalog_id=ORIGIN, verify=value) - method, target, body = agent_api.project_request(name, arguments) - self.assertIn('verify=' + str(value).lower(), target) - self.assertEqual(agent_api.validate_selected(selection, method, target, body), arguments) - with self.assertRaises(agent_api.AgentAPIError): - agent_api.validate_arguments(name, dict(arguments, verify=str(value).lower())) - for invalid in ('True', 'False', '1', 'yes', ''): - target = '/api/workspace/project-files/candidates/' + RECORD + '?binding=' + READ['binding'] + '&checkpoint=' + CHECKPOINT + '&origin_catalog_id=' + ORIGIN + '&verify=' + invalid - with self.assertRaises(agent_api.AgentAPIError): - agent_api.validate_selected(selection, 'GET', target, None) - - -if __name__ == '__main__': - unittest.main() diff --git a/tests/test_project_execution.py b/tests/test_project_execution.py deleted file mode 100644 index bab34f04..00000000 --- a/tests/test_project_execution.py +++ /dev/null @@ -1,569 +0,0 @@ -"""Current host authority and real neutral project Run custody. - -Only disposable PostgreSQL catalogs and the existing authored generic fixture -belong here. Actual host execution cases require a lead-coordinated source freeze. -""" -import copy -from contextlib import contextmanager -import hashlib -import json -import os -from pathlib import Path -from types import SimpleNamespace -import tempfile -import threading -import time -import unittest -from unittest.mock import patch -import uuid - -from access import Access, AccessError, ActorContext, _CURRENT, current_context -from metadata import Metadata, connection_info -from project_execution import ProjectExecution, validate_operation_result -from workbench import WorkbenchError - - -@unittest.skipUnless(os.environ.get('TULDOK_DATABASE_URL'), 'Requires disposable PostgreSQL') -class ProjectAccessBridgeTests(unittest.TestCase): - def setUp(self): - self.temporary = tempfile.TemporaryDirectory(prefix='tuldok-project-execution-') - self.root = Path(self.temporary.name) - self.addCleanup(self.temporary.cleanup) - self.databases = [] - self.addCleanup(self.cleanup) - self.host = self.metadata('host') - self.host_access = Access(self.host, self.host.path) - session = self.host_access.exchange(self.host_access._local_owner_token(initial=True)) - self.token, self.owner = session['token'], session['identity'] - self.local = self.metadata('projection', projection=True) - self.bridge = Access(self.local, self.local.path, authority=self.host_access) - - def metadata(self, name, projection=False): - kwargs = dict(dataset_id=uuid.uuid4().hex, projection_id=uuid.uuid4().hex) if projection else {} - db = Metadata(self.root/name, **kwargs) - self.databases.append(db) - return db - - def cleanup(self): - import psycopg - from psycopg import sql - for db in reversed(self.databases):db.close() - with psycopg.connect(connection_info(), autocommit=True) as connection: - for db in self.databases: - connection.execute(sql.SQL('DROP SCHEMA IF EXISTS {} CASCADE').format(sql.Identifier(db.schema))) - - def assert_no_credentials(self): - for table in ('access_actors','access_credentials'): - self.assertEqual(self.local.execute('SELECT count(*) FROM '+table).fetchone()[0], 0) - - def test_current_host_identity_is_retagged_without_minting_or_copying(self): - self.assertIsNone(current_context()) - with self.host_access.bind(self.token): - original = current_context() - context = self.bridge.require('execute', 'runs.submit', owner_only=True) - self.assertEqual(context.catalog_id, self.local.dataset_id) - self.assertEqual(context.actor_id, original.actor_id) - self.assertEqual(current_context(), original) - self.assertEqual(self.bridge.identity()['catalog_id'], self.local.dataset_id) - calls = (lambda: self.bridge._local_owner_token(), - lambda: self.bridge.exchange(self.token), - lambda: self.bridge.issue({'label':'No copied identity','scopes':['inspect']}), - lambda: self.bridge.revoke(original.credential_id), - lambda: self.bridge.logout(), lambda: self.bridge._resolve(self.token), - lambda: self.bridge._mint(original.actor_id,'bearer',['inspect'],600)) - for call in calls: - with self.assertRaises(AccessError):call() - with self.assertRaises(AccessError): - with self.bridge.bind(self.token):pass - self.assert_no_credentials() - - def test_wrong_host_forged_logical_credential_and_host_system_refuse(self): - other_db = self.metadata('other-host') - other = Access(other_db, other_db.path) - token = other.exchange(other._local_owner_token())['token'] - with other.bind(token), self.assertRaises(AccessError): - self.bridge.require('inspect','runs.list') - marker = _CURRENT.set(ActorContext(self.local.dataset_id,self.owner['actor_id'],self.owner['credential_id'])) - try: - with self.assertRaises(AccessError):self.bridge.require('inspect','runs.list') - finally:_CURRENT.reset(marker) - with self.host_access._reconcile(), self.assertRaises(AccessError): - self.bridge.require('inspect','runs.list') - with self.bridge._reconcile(): - self.bridge.require('cancel','runs.reconcile') - with self.assertRaises(AccessError):self.bridge.require('execute','runs.submit') - self.assert_no_credentials() - - def test_live_scopes_revocation_and_expiry_are_checked_on_every_use(self): - with self.host_access.bind(self.token): - agent = self.host_access.issue({'label':'Current agent','scopes':['inspect','edit','execute']}) - with self.host_access.bind(agent['token']): - self.bridge.require('edit','record.edit') - self.bridge.require_external_submission() - with self.assertRaises(AccessError):self.bridge.require('execute','runs.submit') - with self.assertRaises(AccessError):self.bridge.grant_execution('a'*64,agent['identity']['actor_id']) - with self.host_access.bind(self.token):self.host_access.revoke(agent['identity']['credential_id']) - with self.assertRaises(AccessError):self.bridge.identity() - with self.host_access.bind(self.token): - expired = self.host_access.issue({'label':'Expires during request','scopes':['inspect']}) - with self.host_access.bind(expired['token']): - self.host.execute('UPDATE access_credentials SET expires_at=0 WHERE id=%s',(expired['identity']['credential_id'],)) - with self.assertRaises(AccessError):self.bridge._context() - self.assert_no_credentials() - - def test_current_grant_and_exact_local_job_survive_revocation_without_new_authority(self): - request = hashlib.sha256(b'authored exact admission').hexdigest();run_id=uuid.uuid4().hex - with self.host_access.bind(self.token): - agent = self.host_access.issue({'label':'Bounded external submitter','scopes':['inspect','execute']}) - grant = self.bridge.grant_execution('b'*64,agent['identity']['actor_id']) - self.assertEqual(grant['catalog_id'], self.local.dataset_id) - with self.host_access.bind(agent['token']), self.local.transaction(): - admission = self.bridge._consume_external_run(grant['id'],'b'*64,run_id,request) - with self.host_access.bind(self.token):self.host_access.revoke(agent['identity']['credential_id']) - with self.bridge._job('runs',run_id,admission,request): - self.bridge.require('edit','runs.update',run_id) - self.bridge.require_job('runs',run_id,admission,request) - for action,target in (('runs.update',uuid.uuid4().hex),('runs.cancel',run_id)): - with self.assertRaises(AccessError):self.bridge.require('edit',action,target) - with self.assertRaises(AccessError):self.bridge.require('execute','runs.submit') - with self.assertRaises(AccessError): - with self.bridge._job('runs',run_id,uuid.uuid4().hex,request):pass - fresh = self.metadata('cold-projection',projection=True) - cold = Access(fresh,fresh.path,authority=self.host_access) - with self.assertRaises(AccessError): - with cold._job('runs',run_id,admission,request):pass - self.assert_no_credentials() - - def test_unbound_threads_get_no_owner_or_job_default(self): - errors=[] - def worker(): - try:self.bridge.require('inspect','runs.list') - except AccessError as error:errors.append(error.code) - with self.host_access.bind(self.token): - thread=threading.Thread(target=worker);thread.start();thread.join(5) - self.assertEqual(errors,['unauthenticated']) - - def test_logical_identity_collision_keeps_bridge_inert_and_execution_unavailable(self): - db=Metadata(self.root/'same-logical-project',dataset_id=self.host.dataset_id,projection_id=uuid.uuid4().hex) - self.databases.append(db) - bridge=Access(db,db.path,authority=self.host_access) - with self.host_access.bind(self.token): - # Ordinary project metadata still uses the current host Access. - self.host_access.require('edit','project_files.data_edit') - with self.assertRaises(AccessError) as failure:bridge.require_external_submission() - self.assertEqual(failure.exception.code,'unavailable') - with self.assertRaises(AccessError):bridge.grant_execution('a'*64,self.owner['actor_id']) - for table in ('access_actors','access_credentials','access_admissions','access_execution_grants'): - self.assertEqual(db.execute('SELECT count(*) FROM '+table).fetchone()[0],0) - - -class ExecutionObservationTests(unittest.TestCase): - def test_run_receipt_binds_exact_retained_identity_and_rejects_live_fields(self): - value=dict(format='project_run_admission_v1',origin_catalog_id='a'*32,run_id='b'*32,request_sha256='c'*64) - record=dict(family='run_history',id='a'*32+'.'+'b'*32,document={'run':dict(dataset_id='a'*32,id='b'*32,request_sha256='c'*64)}) - self.assertTrue(validate_operation_result('runs.submit_external',value,[record])) - for changed in (dict(value,request_sha256='d'*64),dict(value,approval_id='e'*32),dict(value,token='secret')): - with self.assertRaises(WorkbenchError):validate_operation_result('runs.submit_external',changed,[record]) - self.assertFalse(validate_operation_result('other.operation',{})) - - def test_failed_custody_ack_fences_even_when_sql_rolls_back(self): - execution=ProjectExecution.__new__(ProjectExecution) - execution.session=SimpleNamespace(available=True) - owner=SimpleNamespace(_fence_coordinator=lambda:None) - execution._runs=owner - with patch.object(owner,'_fence_coordinator') as fence: - with self.assertRaises(WorkbenchError): - with execution._journal_guard(): - raise WorkbenchError('Filesystem acknowledgement was lost.','outcome_unknown',409) - self.assertFalse(execution.session.available);fence.assert_called_once() - - -class RunHostSourceTests(unittest.TestCase): - def setUp(self): - from runs import Runs - from project_artifacts import ProjectArtifacts - from project_store import ProjectStore - self.tmp=tempfile.TemporaryDirectory(prefix='project-run-host-source-');self.addCleanup(self.tmp.cleanup) - self.root=Path(self.tmp.name);self.host=self.root/'host';self.host.mkdir() - self.source=self.host/'helper.py';self.raw=b'# exact authored host helper\n';self.source.write_bytes(self.raw) - self.sha=hashlib.sha256(self.raw).hexdigest() - self.store=ProjectStore.create(self.root/'project','Host bytes','new-host-source','a'*64) - self.addCleanup(self.store.close) - self.artifacts=ProjectArtifacts(self.store);self.addCleanup(self.artifacts.close) - self.records=[] - self.owner=Runs.__new__(Runs) - self.owner.dataset=SimpleNamespace(access=None,db=None,lock=threading.RLock()) - self.owner.project_execution=SimpleNamespace(session=SimpleNamespace(snapshot={'records':self.records})) - self.run=dict(id='a'*32,dataset_id='b'*32,state='queued',custody_phase='prepared',custody_identity=None, - material=dict(recipe={'authored':'qualified neutral helper'},host_files={'helper.py':self.sha})) - self.file_patch=patch('recipe_contract.__file__',str(self.host/'recipe_contract.py'));self.file_patch.start() - self.addCleanup(self.file_patch.stop) - self.identity_patch=patch('recipe_contract.recipe_host_identity',return_value={'helper.py':self.sha}) - self.identity=self.identity_patch.start();self.addCleanup(self.identity_patch.stop) - - def capture(self):return self.owner._capture_project_host_sources(self.run,self.artifacts) - - def retain(self,edges): - self.records.append(dict(family='run_history',id=self.run['dataset_id']+'.'+self.run['id'], - document=dict(origin_catalog_id=self.run['dataset_id'],run=copy.deepcopy(self.run),payloads=edges))) - - def test_exact_source_is_durable_and_later_updates_use_retained_bytes(self): - edges=self.capture();self.assertEqual(edges[0]['name'],'host/helper.py') - self.assertEqual(self.artifacts.read_blob(edges[0]['blob']),self.raw) - self.retain(edges);self.run.update(state='interrupted',custody_phase='drained') - self.source.write_bytes(b'# newer unqualified helper\n') - self.identity.side_effect=AssertionError('Later observation consulted the current host') - self.assertEqual(self.capture(),edges) - self.assertEqual(self.artifacts.read_blob(edges[0]['blob']),self.raw) - - def test_hash_race_cannot_publish_source_under_admitted_identity(self): - from project_artifacts import ProjectArtifactError - publish=self.artifacts.publish_fd - def changed(fd,declaration,**kwargs): - self.source.write_bytes(b'# source changed after identity measurement\n') - return publish(fd,declaration,**kwargs) - with patch.object(self.artifacts,'publish_fd',side_effect=changed),self.assertRaises(ProjectArtifactError): - self.capture() - self.assertEqual(self.store.snapshot()['records'],[]) - - def test_historical_missing_or_contradictory_host_cannot_be_retrofitted(self): - self.retain([]) - with self.assertRaises(WorkbenchError) as error:self.capture() - self.assertEqual(error.exception.code,'unavailable');self.identity.assert_not_called() - self.records.clear();edges=self.capture();self.retain(edges) - self.records[0]['document']['payloads'][0]['blob']['sha256']='f'*64 - with self.assertRaises(WorkbenchError):self.capture() - - -@unittest.skipUnless(os.environ.get('TULDOK_DATABASE_URL'),'Requires disposable PostgreSQL') -class FileWriterReconciliationTests(unittest.TestCase): - def setUp(self): - from auth_helpers import ExplicitOwnerFixture - from project_custody import ProjectCustody - from project_projection import ProjectProjection - from project_store import ProjectStore - self.tmp=tempfile.TemporaryDirectory(prefix='project-file-reconciliation-');self.root=Path(self.tmp.name) - self.databases=[];self.projections=[];self.addCleanup(self.cleanup) - host_db=self.metadata('host');self.host=SimpleNamespace(db=host_db,access=Access(host_db,host_db.path)) - self.owner=ExplicitOwnerFixture.bootstrap(self.host) - self.store=ProjectStore.create(self.root/'project','Current file custody','file-fixture','a'*64) - control=self.root/'control';control.mkdir() - self.manager=ProjectCustody(control,host_db.dataset_id) - db=self.metadata('projection',self.store.snapshot()['project_id'],uuid.uuid4().hex) - self.journal=self.manager.for_projection(self.store,db.projection_id) - self.projection=ProjectProjection(self.store,db,self.host.access,{},custody=self.journal) - self.projections.append(self.projection);self.execution=self.projection.execution;self.session=self.projection.session - self.enterContext(self.owner.bound(self.host)) - self.key='original-file-writer';self.input_sha='b'*64;self.content_sha='c'*64 - self.enterContext(patch('runs.Runs',side_effect=AssertionError('File recovery constructed Runs'))) - self.enterContext(patch('subprocess.Popen',side_effect=AssertionError('File recovery launched a process'))) - - def metadata(self,name,logical=None,physical=None): - kwargs={} if logical is None else dict(dataset_id=logical,projection_id=physical) - db=Metadata(self.root/name,**kwargs);self.databases.append(db);return db - - def cleanup(self): - import psycopg - from psycopg import sql - for projection in reversed(self.projections): - if projection.sources is not None:projection.sources.close() - projection.artifacts.close() - for db in reversed(self.databases):db.close() - if hasattr(self,'store'):self.store.close() - with psycopg.connect(connection_info(),autocommit=True) as connection: - for schema in {db.schema for db in self.databases}: - connection.execute(sql.SQL('DROP SCHEMA IF EXISTS {} CASCADE').format(sql.Identifier(schema))) - self.tmp.cleanup() - - def start(self,kind): - context=(self.execution.runtime_effect if kind=='runtime' else self.execution.package_effect) - with context(self.key,self.input_sha,self.content_sha) as effect:effect.publication_started() - - def decision(self,name): - from test_project_history import policy - return self.projection.history.create_study(dict(name=name,limits=dict(attempt_slots=1, - admitted_wall_seconds=100,retained_bytes=10000,peak_staging_bytes=10000),policy=policy()), - self.session.snapshot['checkpoint'],uuid.uuid4().hex) - - def test_package_guard_preserves_partial_bytes_until_acknowledged_owner_decision(self): - self.start('package');partial=self.root/'partial-package';partial.write_bytes(b'Preserve exact partial bytes') - with self.execution.package_reconciliation(self.key,self.input_sha,self.content_sha,self.session.snapshot['checkpoint']): - self.assertTrue(self.journal.has_pending) - self.assertTrue(self.journal.has_pending) - with self.execution.package_reconciliation(self.key,self.input_sha,self.content_sha,self.session.snapshot['checkpoint']) as effect: - self.decision('Acknowledged controlled owner decision') - effect.confirmed() - self.assertFalse(self.journal.has_pending);self.assertEqual(partial.read_bytes(),b'Preserve exact partial bytes') - self.assertIsNone(self.execution._package_active);self.assertIsNone(self.execution._runs) - - def test_runtime_prepare_recovers_exact_unknown_canonical_and_reconstructs_before_retry(self): - from project_store import ProjectStoreError - self.start('runtime');before=self.session.snapshot;original=self.store.commit - def lost(*args,**kwargs): - original(*args,**kwargs) - raise ProjectStoreError('Actual canonical selection lost its acknowledgement.','unknown',409) - with patch.object(self.store,'commit',side_effect=lost),self.assertRaises(ProjectStoreError): - self.decision('Canonical science selected before SQL rollback') - self.assertFalse(self.session.available) - observed=self.execution.runtime_pending(self.key) - self.assertEqual(observed,dict(request_key=self.key,input_sha256=self.input_sha,manifest_sha256=self.content_sha)) - recovered=self.execution.prepare_runtime_reconciliation(self.key,self.input_sha,self.content_sha,before['checkpoint']) - self.assertTrue(self.session.available);self.assertNotEqual(recovered['checkpoint'],before['checkpoint']) - self.assertIsNone(self.execution._runtime_active);self.assertTrue(self.journal.has_pending) - self.assertEqual(self.projection.db.execute('SELECT count(*) FROM model_studies').fetchone()[0],1) - with self.execution.runtime_effect(self.key,self.input_sha,self.content_sha) as effect: - effect.publication_started();self.decision('Explicit normal runtime retry acknowledged');effect.confirmed() - self.assertFalse(self.journal.has_pending) - - def test_original_retained_projection_can_restore_but_foreign_physical_owner_cannot(self): - from project_projection import ProjectProjection - self.start('runtime');old=self.projection;identity=old.db.projection_id - old.artifacts.close();old.db.close() - db=Metadata(old.db.path,create=False,dataset_id=self.store.snapshot()['project_id'],projection_id=identity) - self.databases.append(db) - journal=self.manager.for_projection(self.store,identity) - retained=ProjectProjection(self.store,db,self.host.access,{},custody=journal,restore=False) - self.projections.append(retained);self.projection=retained;self.execution=retained.execution;self.session=retained.session - self.assertFalse(self.session.available) - restored=self.execution.prepare_runtime_reconciliation(self.key,self.input_sha,self.content_sha,self.session.snapshot['checkpoint']) - self.assertEqual(restored,self.session.snapshot);self.assertTrue(self.session.available);self.assertTrue(journal.has_pending) - foreign_db=self.metadata('foreign',db.dataset_id,uuid.uuid4().hex) - foreign=ProjectProjection(self.store,foreign_db,self.host.access,{}, - custody=self.manager.for_projection(self.store,foreign_db.projection_id)) - self.projections.append(foreign) - with self.assertRaises(WorkbenchError) as denied: - foreign.execution.prepare_runtime_reconciliation(self.key,self.input_sha,self.content_sha,foreign.session.snapshot['checkpoint']) - self.assertEqual(denied.exception.code,'unavailable');self.assertTrue(journal.has_pending) - - def test_wrong_tuple_active_writer_and_unrelated_checkout_never_clear_or_adopt(self): - self.start('package');checkpoint=self.session.snapshot['checkpoint'] - with patch.object(self.store,'recover_checkpoint',side_effect=AssertionError('Rejected tuple touched selection')): - for content in ('d'*64,): - with self.assertRaises(WorkbenchError): - with self.execution.package_reconciliation(self.key,self.input_sha,content,checkpoint):pass - self.execution._package_active=self.key - try: - with self.assertRaises(WorkbenchError): - with self.execution.package_reconciliation(self.key,self.input_sha,self.content_sha,checkpoint):pass - finally:self.execution._package_active=None - self.store.commit([],checkpoint,'unrelated-checkout','e'*64) - with self.assertRaises(WorkbenchError) as rejected: - with self.execution.package_reconciliation(self.key,self.input_sha,self.content_sha,checkpoint):pass - self.assertEqual(rejected.exception.code,'stale_project');self.assertFalse(self.session.available) - self.assertEqual(self.session.snapshot['checkpoint'],checkpoint);self.assertTrue(self.journal.has_pending) - - -@unittest.skipUnless(os.environ.get('TULDOK_DATABASE_URL'), 'Requires disposable PostgreSQL') -class ProjectRunCustodyTests(unittest.TestCase): - """Real generic external recipe, trusted custodian, no provider or model fit.""" - def setUp(self): - from project_store import ProjectStore - from project_projection import ProjectProjection - from test_project_files_material_http import neutral_source - self.temporary=tempfile.TemporaryDirectory(prefix='tuldok-current-project-run-') - self.root=Path(self.temporary.name);self.addCleanup(self.temporary.cleanup) - self.databases=[];self.projections=[];self.stores=[];self.addCleanup(self.cleanup) - self.source_root=self.root/'source';self.source_root.mkdir() - self.manifest,self.manifest_raw,self.definition_raw,self.source,self.input=neutral_source(self.source_root) - self.host=self.metadata('host');self.access=Access(self.host,self.host.path) - self.token=self.access.exchange(self.access._local_owner_token())['token'] - self.enterContext(self.access.bind(self.token)) - self.store=ProjectStore.create(self.root/'project','Neutral current custody','new-custody','a'*64) - self.stores.append(self.store) - self.db=self.metadata('projection',self.store.snapshot()['project_id']) - self.projection=ProjectProjection(self.store,self.db,self.access,{'fixture':self.source_root}) - self.projections.append(self.projection);self.execution=self.projection.execution - self.session=self.projection.session - registration=self.projection.source_adapter.register(dict(root='fixture',manifest_path='project.json'),self.checkpoint(),'source-register') - self.assertEqual(registration['origin_catalog_id'],self.db.dataset_id) - body=dict(name='Neutral custody',project_id=self.manifest['id'],recipe_id='neutral', - expected_sha256=hashlib.sha256(self.definition_raw).hexdigest(),inputs={ - 'sample':dict(reference_id='sample',expected_sha256=hashlib.sha256(self.input).hexdigest())}) - self.graph=self.projection.materials.mutate_definition('pipeline_graph','graphs.create_external',None,body, - self.checkpoint(),'graph-create',lambda:self.projection.pipelines.create_external(body)) - self.preflight=self.execution.preflight_external(self.graph['id'],self.graph['revision']) - - def metadata(self,name,catalog_id=None): - args=dict(dataset_id=catalog_id,projection_id=uuid.uuid4().hex) if catalog_id is not None else {} - db=Metadata(self.root/(name+'-'+uuid.uuid4().hex),**args);self.databases.append(db) - return db - - def cleanup(self): - import psycopg - from psycopg import sql - for projection in reversed(self.projections): - execution=getattr(projection,'execution',None) - if execution is not None and execution._runs is not None: - with execution.runtime_access._reconcile():execution._runs.close() - # This explicit fixture teardown follows actual worker drain even - # when a fault intentionally keeps the public lifecycle fenced. - if projection.sources is not None:projection.sources.close() - projection.artifacts.close() - for db in reversed(self.databases):db.close() - for store in reversed(self.stores):store.close() - with psycopg.connect(connection_info(),autocommit=True) as connection: - for db in self.databases: - connection.execute(sql.SQL('DROP SCHEMA IF EXISTS {} CASCADE').format(sql.Identifier(db.schema))) - - def checkpoint(self):return self.session.snapshot['checkpoint'] - def body(self):return dict(graph_id=self.graph['id'],graph_revision=self.graph['revision'],expected_digest=self.preflight['material_sha256']) - def record(self,identity): - return next(item['document'] for item in self.store.snapshot()['records'] - if item['family']=='run_history' and item['document']['run']['id']==identity) - def await_drained(self,identity,timeout=30): - deadline=time.monotonic()+timeout - while time.monotonic()>'state'='completed'"): - document=self.record(row['id']) - self.assertEqual(document['run']['state'],'completed') - for edge in document['payloads']: - self.assertEqual(self.projection.artifacts.status(dict(format='project_artifact_v1',**edge['blob']))['state'],'verified') - observed.append('canonical-terminal-before-sql-outcome') - original_outcome(kind) - with patch.object(recipe_process.Handle,'go',go),patch.object(self.db,'_project_outcome',outcome): - admitted=self.execution.submit_external(self.body(),self.checkpoint(),'real-neutral-submit') - completed=self.await_drained(admitted['run_id']) - self.assertEqual(completed['state'],'completed',completed.get('error')) - self.assertEqual(observed,['canonical-go-intent','canonical-terminal-before-sql-outcome']) - self.assertEqual(self.execution.submit_external(self.body(),'0'*64,'real-neutral-submit'),admitted) - retained=self.record(admitted['run_id']) - self.assertEqual(retained['run']['state'],'completed') - self.assertEqual(retained['run']['request_sha256'],admitted['request_sha256']) - edges={item['name']:item for item in retained['payloads']} - self.assertEqual(self.projection.artifacts.read_blob(edges['input/sample']['blob']),self.input) - self.assertEqual(self.projection.artifacts.read_blob(edges['source/recipe.py']['blob']),self.source) - output=self.projection.artifacts.read_blob(edges['result.txt']['blob']) - self.assertIn(self.input,output) - receipt=recipe_process.validate_receipt(self.projection.artifacts.read_blob(edges['custody-receipt.json']['blob']),completed['custody_identity']) - self.assertTrue(receipt['drained']);self.assertEqual(receipt['outcome'],'completed') - self.execution.reconcile_current() - self.execution.assert_quiescent() - # Fresh projection consumes only portable facts, never source SQL - # admissions/grants, saved PID handles, queues or operation replay. - cold_db=self.metadata('cold-projection',self.db.dataset_id) - with patch('runs.Runs',side_effect=AssertionError('Cold Open constructed Runs')), \ - patch('subprocess.Popen',side_effect=AssertionError('Cold Open launched a process')): - cold=ProjectProjection(self.store,cold_db,self.access,{}) - self.projections.append(cold) - for table in ('workspace_runs','access_admissions','access_execution_grants','access_execution_consumptions'): - self.assertEqual(cold_db.execute('SELECT count(*) FROM '+table).fetchone()[0],0) - self.assertIsNone(cold.execution._runs) - self.assertEqual(cold.execution.health()['active_count'],0) - with self.assertRaises(WorkbenchError):cold.execution.submit_external(self.body(),cold.session.snapshot['checkpoint'],'real-neutral-submit') - self.assertIsNone(cold.execution._runs) - - def test_current_approval_receipt_cannot_reissue_after_cold_projection(self): - from project_projection import ProjectProjection - actor=self.access.identity()['actor_id'];body=dict(self.body(),consumer_actor_id=actor) - current=self.execution.approve_external(body,self.checkpoint(),'local-only-approval') - self.assertTrue(current['current_local']) - self.assertEqual(current,self.execution.approve_external(body,'0'*64,'local-only-approval')) - canonical=next(item['document']['result'] for item in self.store.snapshot()['records'] - if item['family']=='project_operation' and item['document']['request_key']=='local-only-approval') - self.assertEqual(canonical['format'],'project_execution_approval_v1') - self.assertNotIn('grant',canonical);self.assertNotIn('approver_credential_id',canonical) - cold_db=self.metadata('cold-approval',self.db.dataset_id) - cold=ProjectProjection(self.store,cold_db,self.access,{}) - self.projections.append(cold) - with patch('runs.Runs',side_effect=AssertionError('Historical approval constructed Runs')): - with self.assertRaises(WorkbenchError):cold.execution.approve_external(body,cold.session.snapshot['checkpoint'],'local-only-approval') - self.assertEqual(cold_db.execute('SELECT count(*) FROM access_execution_grants').fetchone()[0],0) - - def test_lost_go_commit_ack_never_sends_go_and_requires_exact_current_reconcile(self): - import recipe_process - import psycopg - original_transaction=psycopg.Connection.transaction;injected=[];original_go=recipe_process.Handle.go - go_calls=[] - @contextmanager - def transaction(connection,*args,**kwargs): - with original_transaction(connection,*args,**kwargs):yield - if connection is self.db.connection and not injected: - rows=connection.execute("SELECT document FROM workspace_runs WHERE document::jsonb->>'custody_phase'='go_intent'").fetchall() - if rows: - injected.append('lost-after-actual-go-intent-commit') - raise OSError('Injected lost SQL acknowledgement after canonical intent') - def go(handle,expected): - go_calls.append(True) - return original_go(handle,expected) - with patch.object(psycopg.Connection,'transaction',transaction),patch.object(recipe_process.Handle,'go',go): - admitted=self.execution.submit_external(self.body(),self.checkpoint(),'go-ack-fault') - deadline=time.monotonic()+30 - while time.monotonic()1}) - - def test_reads_pin_binding_checkpoint_and_path_record_without_body(self): - arguments = {'record_id': RECORD, 'binding': BINDING, 'checkpoint': CHECKPOINT} - method, path, body = api.project_request('project_files.get', arguments) - self.assertEqual((method, body), ('GET', None)) - self.assertEqual(path, f'/api/workspace/project-files/records/{RECORD}?binding={BINDING}&checkpoint={CHECKPOINT}') - for missing in ('binding', 'checkpoint', 'record_id'): - with self.subTest(missing=missing), self.assertRaises(api.AgentAPIError): - api.validate_arguments('project_files.get', {key: value for key, value in arguments.items() if key != missing}) - - def test_closed_text_inputs_refuse_execution_fields_and_wrong_annotation_family(self): - good = dict(bound(), asset={'text': 'hello', 'groups': ['source']}) - for bad in (dict(good, execution=True), dict(good, asset={**good['asset'], 'script': 'run'}), - dict(good, asset={'text': 'hello', 'groups': ['source', 'source']}), - dict(good, asset={'text': 'hello', 'groups': ['source'], 'rights': ''}), - dict(good, expected_checkpoint=None), dict(good, binding=PROJECT + 'bad')): - with self.subTest(bad=bad), self.assertRaises(api.AgentAPIError): - api.validate_arguments('project_files.import_text', bad) - annotation = {'revision': 1, 'source_revision': 1, 'task': 'text_corpus', - 'annotation': {'note': 'Reviewed'}, 'groups': ['source'], 'review': 'human_reviewed'} - api.validate_arguments('project_files.annotate', dict(bound(), record_id=RECORD, annotation=annotation)) - for change in ({'annotation': {'label': 'wrong task'}}, {'task': 'image_caption'}, - {'review': 'programmatically_verified'}, {'verified_provenance': {}}): - with self.subTest(change=change), self.assertRaises(api.AgentAPIError): - api.validate_arguments('project_files.annotate', dict(bound(), record_id=RECORD, annotation={**annotation, **change})) - for checkpoint in (None, CHECKPOINT): - api.validate_arguments('project_files.open', {**bound(), 'expected_checkpoint': checkpoint, - 'root': 'fixture', 'directory': 'project'}) - - def test_bounded_pages_cover_maximum_unicode_source_without_full_history_response(self): - large = record(); large['text'] = '🌸' * 200000 - api.validate_arguments('project_files.import_text', dict(bound(), asset={'text': large['text'], 'groups': ['source']})) - large['task'] = 'text_entities' - large['annotation'] = {'spans': [{'label': '🌸' * 80, 'start': index, 'end': index + 1} for index in range(500)]} - large['groups'] = ['🌸' * 117 + str(index) for index in range(30)] - large['parents'] = list(large['groups']); large['provenance']['rights'] = '🌸' * 1000 - large['name'] = '🌸' * 200; large['revision'] = 5 - page = dict(result(), record=large, history=[dict(large, revision=revision) for revision in (5, 4, 3, 2)], next_history_before_revision=2) - api.validate_output('project_files.get', {'status': 200, 'result': page}) - self.assertLess(len(api.encoded(page)), api.RESPONSE_LIMIT) - self.assertGreater(len(api.encoded(dict(page, history=[large] * 6))), api.RESPONSE_LIMIT) - api.validate_arguments('project_files.get', {'binding': BINDING, 'checkpoint': CHECKPOINT, 'record_id': RECORD, 'before_revision': 5, 'history_limit': 4}) - for field, wrong in [('history_limit', 5), ('before_revision', 0)]: - with self.subTest(field=field), self.assertRaises(api.AgentAPIError): - api.validate_arguments('project_files.get', {'binding': BINDING, 'checkpoint': CHECKPOINT, 'record_id': RECORD, field: wrong}) - summary = {key: value for key, value in record().items() if key in api.PROJECT_FILES_SUMMARY['properties']} - query = {'binding': BINDING, 'project_id': PROJECT, 'checkpoint': CHECKPOINT, 'items': [summary], 'next_after_id': RECORD} - api.validate_output('project_files.query', {'status': 200, 'result': query}) - query['items'][0]['text'] = 'must use get' - with self.assertRaises(api.AgentAPIError): - api.validate_output('project_files.query', {'status': 200, 'result': query}) - - def test_recovery_state_and_committed_error_receipt_are_closed(self): - recovery = dict(state(), state='recovery_required', available_actions=['open'], recovery={ - 'action': 'open', 'root': 'fixture', 'directory': 'project', - 'reason': 'unknown_publication', 'request_key': KEY}) - api.validate_output('project_files.status', {'status': 200, 'result': recovery}) - bad = copy.deepcopy(recovery); bad['available_actions'] = ['open', 'save'] - with self.assertRaises(api.AgentAPIError): - api.validate_output('project_files.status', {'status': 200, 'result': bad}) - receipt = {'committed': True, 'selected': True, 'project_id': PROJECT, 'checkpoint': CHECKPOINT, 'request_key': KEY} - api.validate_output('project_files.annotate', {'status': 503, 'result': {'code': 'projection_unavailable', 'error': 'Reopen to reconstruct.', 'receipt': receipt}}) - with self.assertRaises(api.AgentAPIError): - api.validate_output('project_files.annotate', {'status': 503, 'result': {'error': 'Unknown', 'receipt': dict(receipt, secret='reject')}}) - - def test_closed_record_output_rejects_unknown_and_inconsistent_history(self): - api.validate_output('project_files.get', {'status': 200, 'result': result()}) - variants = [] - for path, value in ((('record', 'secret'), 'leak'), (('record', 'kind'), 'image'), - (('record', 'annotation'), {'note': 'wrong task'}), - (('record', 'provenance'), {'method': 'generated'})): - bad = result(); bad[path[0]][path[1]] = value; variants.append(bad) - bad = result(); bad['history'][0]['id'] = PROJECT; variants.append(bad) - bad = result(); bad['history'].append(record()); variants.append(bad) - for bad in variants: - with self.subTest(bad=bad), self.assertRaises(api.AgentAPIError): - api.validate_output('project_files.get', {'status': 200, 'result': bad}) - - -class Consumers(unittest.TestCase): - def test_explicit_owner_wait_budget_preserves_generic_bounds_and_private_configuration(self): - endpoint,token='http://127.0.0.1:12345','fixture-agent-token-for-client-tests' - self.assertEqual(api.ProjectFilesOwnerClient(endpoint,token,CATALOG).timeout,120) - self.assertEqual(api.ProjectFilesOwnerClient(endpoint,token,CATALOG,timeout=7200).timeout,7200) - for client_type,invalid in ((api.AgentClient,301),(api.ProjectFilesOwnerClient,7201), - (api.ProjectFilesOwnerClient,float('inf')),(api.ProjectFilesOwnerClient,True)): - with self.subTest(client=client_type.__name__,timeout=invalid),self.assertRaises(api.AgentAPIError): - client_type(endpoint,token,CATALOG,timeout=invalid) - with tempfile.TemporaryDirectory() as directory: - root=Path(directory);credential=root/'token';configuration=root/'config.json' - credential.write_text(token);credential.chmod(0o600) - configuration.write_text(json.dumps(dict(endpoint=endpoint,catalog_id=CATALOG, - token_file=str(credential),timeout=7200)));configuration.chmod(0o600) - self.assertEqual(api.ProjectFilesOwnerClient.from_config(configuration).timeout,7200) - with self.assertRaises(api.AgentAPIError):api.AgentClient.from_config(configuration) - - def test_owner_file_client_keeps_unrelated_operations_outside_authority(self): - raw = client({'status': 200, 'result': state()}, owner=True) - self.assertEqual(ProjectFilesClient(raw).save(**bound()), state()) - self.assertEqual(set(raw.selected_contracts()), api.ProjectFilesOwnerClient.OPERATIONS) - self.assertEqual(raw._request.call_count, 4) - raw._request.reset_mock() - with self.assertRaises(api.AgentAPIError) as failure: - raw.call('data.get', {'record_id': RECORD}) - self.assertEqual(failure.exception.code, 'operation_unsupported') - raw._request.assert_not_called() - for action in ('new', 'open', 'save', 'close'): - self.assertEqual(api.contract('project_files.' + action)['authority'], 'owner') - - def test_cli_explicit_owner_mode_supports_only_file_commands(self): - output, errors = io.StringIO(), io.StringIO() - raw = client({'status': 200, 'result': state()}, owner=True) - args = ['--config', '/not-read.json', '--owner-project-files', 'file-save', - '--binding', BINDING, '--expected-checkpoint', CHECKPOINT, '--request-key', KEY] - with patch.object(project_cli.ProjectFilesOwnerClient, 'from_config', return_value=raw), patch('sys.stdout', output), patch('sys.stderr', errors): - self.assertEqual(project_cli.main(args), 0, errors.getvalue()) - self.assertEqual(json.loads(output.getvalue()), state()) - self.assertEqual(raw._request.call_args.kwargs['selection'], ('project_files.save', 1)) - with patch.object(project_cli.ProjectFilesOwnerClient, 'from_config') as configure, patch('sys.stdout', io.StringIO()), patch('sys.stderr', io.StringIO()) as errors: - self.assertEqual(project_cli.main(['--config', '/not-read.json', '--owner-project-files', 'coordinator-status']), 1) - self.assertEqual(json.loads(errors.getvalue())['code'], 'configuration') - configure.assert_not_called() - - def test_sdk_negotiates_and_forwards_exact_body_once(self): - raw = client({'status': 201, 'result': result()}) - files = ProjectFilesClient(raw) - asset = {'text': 'Hello world', 'groups': ['source']} - self.assertEqual(files.import_text(asset, **bound()), result()) - calls = raw._request.call_args_list - self.assertEqual(len(calls), 4) - self.assertEqual(calls[-1].args, ('POST', '/api/workspace/project-files/import-text', dict(bound(), asset=asset))) - self.assertEqual(calls[-1].kwargs['selection'], ('project_files.import_text', 1)) - self.assertEqual(asset, {'text': 'Hello world', 'groups': ['source']}) - - def test_wrong_binding_checkpoint_and_record_are_not_accepted_as_current(self): - args = {'record_id': RECORD, 'binding': BINDING, 'checkpoint': CHECKPOINT} - for key, wrong in (('binding', PROJECT), ('checkpoint', OTHER), ('record_id', PROJECT)): - reply = result() - if key == 'record_id': - reply['record']['id'] = wrong; reply['history'][0]['id'] = wrong - else: - reply[key] = wrong - raw = client({'status': 200, 'result': reply}) - with self.subTest(key=key), self.assertRaises(api.AgentAPIError) as failure: - raw.call('project_files.get', args) - self.assertEqual(failure.exception.code, 'transport') - self.assertEqual(raw._request.call_count, 4) - - def test_cursor_parameters_and_committed_receipts_survive_sdk_cli_and_http(self): - receipt = {'committed': True, 'selected': True, 'project_id': PROJECT, 'checkpoint': CHECKPOINT, 'request_key': KEY} - raw = client({'status': 503, 'result': {'code': 'projection_unavailable', 'error': 'Saved; rebuild projection.', 'receipt': receipt}}) - with self.assertRaises(api.AgentAPIError) as failure: - ProjectFilesClient(raw).save(**bound()) - self.assertEqual(failure.exception.receipt, receipt) - status, value = self.cli(raw, ['file-save', '--binding', BINDING, '--expected-checkpoint', CHECKPOINT, '--request-key', KEY]) - self.assertEqual((status, value['receipt']), (1, receipt)) - raw = client({'status': 200, 'result': result()}) - ProjectFilesClient(raw).get(RECORD, binding=BINDING, checkpoint=CHECKPOINT, before_revision=2, history_limit=4) - self.assertIn('before_revision=2&history_limit=4', raw._request.call_args.args[1]) - # The real transport must validate and preserve only a file-operation - # receipt, and reject unknown fields or credential-bearing paths. - envelope = {'error': 'Saved; rebuild projection.', 'code': 'projection_unavailable', 'receipt': receipt} - class Handler(BaseHTTPRequestHandler): - def do_POST(self): - self.rfile.read(int(self.headers.get('Content-Length', 0))) - body = api.encoded(envelope) - self.send_response(503); self.send_header('Content-Type', 'application/json'); self.send_header('Content-Length', str(len(body))); self.end_headers(); self.wfile.write(body) - def log_message(self, *_): pass - server = ThreadingHTTPServer(('127.0.0.1', 0), Handler) - thread = threading.Thread(target=server.serve_forever, daemon=True); thread.start() - self.addCleanup(server.server_close); self.addCleanup(thread.join, 5); self.addCleanup(server.shutdown) - transport = api.AgentClient(f'http://127.0.0.1:{server.server_port}', 'fixture-agent-token-for-client-tests', CATALOG) - selected = ('project_files.save', 1) - self.assertEqual(transport._request('POST', '/api/workspace/project-files/save', bound(), selection=selected)['result']['receipt'], receipt) - unicode_body = dict(bound(), asset={'text': '🌸' * 200000, 'groups': ['source']}) - self.assertEqual(transport._request('POST', '/api/workspace/project-files/import-text', unicode_body, selection=('project_files.import_text', 1))['result']['receipt'], receipt) - for bad in (dict(receipt, unexpected='reject'), dict(receipt, selected=False, root=transport._token, directory='project')): - envelope['receipt'] = bad - with self.assertRaises(api.AgentAPIError) as failure: - transport._request('POST', '/api/workspace/project-files/save', bound(), selection=selected) - self.assertEqual(failure.exception.code, 'transport') - - def test_typed_stale_busy_unknown_and_projection_failures_have_no_retry(self): - for code, status in [('stale_checkpoint', 409), ('busy', 409), ('outcome_unknown', 503), ('projection_unavailable', 503)]: - raw = client({'status': status, 'result': {'code': code, 'error': 'Inspect status before retrying.'}}) - with self.subTest(code=code), self.assertRaises(api.AgentAPIError) as failure: - ProjectFilesClient(raw).save(**bound()) - self.assertEqual((failure.exception.code, failure.exception.status), (code, status)) - self.assertEqual(raw._request.call_count, 4) - - def cli(self, raw, arguments): - output, errors = io.StringIO(), io.StringIO() - with patch.object(project_cli.AgentClient, 'from_config', return_value=raw), patch('sys.stdout', output), patch('sys.stderr', errors): - status = project_cli.main(['--config', '/not-read.json', *arguments]) - return status, json.loads(output.getvalue() if status == 0 else errors.getvalue()) - - def test_cli_named_lifecycle_and_json_text_commands_use_registry(self): - for action in ('new', 'open', 'save', 'close'): - args = ['file-' + action, '--binding', BINDING, '--expected-checkpoint', 'null' if action in ('new', 'open') else CHECKPOINT, '--request-key', KEY] - if action in ('new', 'open'): args += ['--root', 'fixture', '--directory', 'project'] - if action == 'new': args += ['--name', 'My text project'] - raw = client({'status': 200, 'result': state(opened=action != 'close')}) - status, value = self.cli(raw, args) - self.assertEqual(status, 0, value) - self.assertEqual(raw._request.call_args.kwargs['selection'], ('project_files.' + action, 1)) - with tempfile.TemporaryDirectory() as directory: - path = Path(directory) / 'arguments.json' - path.write_text(json.dumps({'binding': BINDING, 'checkpoint': CHECKPOINT, 'record_id': RECORD})) - raw = client({'status': 200, 'result': result()}) - status, value = self.cli(raw, ['file-get', '--arguments', str(path)]) - self.assertEqual(status, 0, value) - self.assertEqual(raw._request.call_args.kwargs['selection'], ('project_files.get', 2)) - raw = client({'status': 200, 'result': state(False)}) - self.assertEqual(self.cli(raw, ['file-status']), (0, state(False))) - - def test_cli_invalid_binding_rejects_before_network(self): - raw = client({'status': 200, 'result': state()}) - status, value = self.cli(raw, ['file-save', '--binding', 'invalid', '--expected-checkpoint', CHECKPOINT, '--request-key', KEY]) - self.assertEqual((status, value['code']), (1, 'invalid')) - raw._request.assert_not_called() - - -SDK_AVAILABLE = all(importlib.util.find_spec(name) for name in ('mcp', 'anyio', 'jsonschema')) - - -@unittest.skipUnless(SDK_AVAILABLE, 'Optional MCP SDK is required for actual stdio forwarding evidence') -class MCPForwarding(unittest.TestCase): - def test_main_bootstraps_before_serving_and_bootstrap_failure_prevents_serving(self): - import anyio - import mcp_stdio - order = [] - client = Mock() - client.bootstrap.side_effect = lambda: order.append('bootstrap') - - def serve_ready(function, selected, *args): - self.assertIs(function, mcp_stdio.serve) - self.assertIs(selected, client) - self.assertEqual(order, ['bootstrap']) - order.append('serve') - - with patch.object(api.AgentClient, 'from_config', return_value=client), patch.object( - anyio, 'run', side_effect=serve_ready) as run: - self.assertEqual(mcp_stdio.main(['--config', 'fixture-only']), 0) - self.assertEqual(order, ['bootstrap', 'serve']) - run.assert_called_once() - client.bootstrap.side_effect = api.AgentAPIError('Fixture authentication refusal.', 'unauthenticated', 401) - with patch.object(api.AgentClient, 'from_config', return_value=client), patch.object( - anyio, 'run') as run, patch('sys.stderr', new_callable=io.StringIO): - self.assertEqual(mcp_stdio.main(['--config', 'fixture-only']), 1) - run.assert_not_called() - - def test_registry_tool_status_and_typed_stale_error_cross_real_stdio(self): - # Deliberately simulated HTTP owner: this claim is SDK/stdio forwarding. - script = f''' -import anyio, agent_api -from mcp_stdio import serve -class Client: - def selected_contracts(self): return {{'project_files.status':1,'project_files.save':1}} - def tool_definitions(self): return agent_api.tool_definitions(self.selected_contracts()) - def call(self,name,arguments): - if name=='project_files_status': return {{'status':200,'result':{state(False)!r}}} - return {{'status':409,'result':{{'code':'stale_checkpoint','error':'Checkpoint changed.'}}}} -anyio.run(serve,Client()) -''' - process = subprocess.Popen([sys.executable, '-c', script], cwd=ROOT, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE) - def cleanup(): - if process.poll() is None: process.terminate() - try: process.communicate(timeout=5) - except subprocess.TimeoutExpired: process.kill(); process.communicate(timeout=5) - self.addCleanup(cleanup) - def send(method, request_id=None, params=None): - value = {'jsonrpc': '2.0', 'method': method} - if request_id is not None: value['id'] = request_id - if params is not None: value['params'] = params - process.stdin.write(json.dumps(value).encode() + b'\n'); process.stdin.flush() - def read(): - raw, deadline = bytearray(), time.monotonic() + 12 - while not raw.endswith(b'\n'): - ready, _, _ = select.select([process.stdout], [], [], max(0, deadline-time.monotonic())) - self.assertTrue(ready, 'MCP reply deadline') - block = os.read(process.stdout.fileno(), 1) - self.assertTrue(block, 'MCP closed before reply') - raw.extend(block) - return json.loads(raw) - send('initialize', 1, {'protocolVersion': '2025-06-18', 'capabilities': {}, 'clientInfo': {'name': 'project-files-test', 'version': '1'}}) - self.assertEqual(read()['id'], 1) - send('notifications/initialized') - send('tools/list', 2) - self.assertEqual({tool['name'] for tool in read()['result']['tools']}, {'project_files_status', 'project_files_save'}) - send('tools/call', 3, {'name': 'project_files_status', 'arguments': {}}) - value = read()['result']; self.assertFalse(value['isError']); self.assertEqual(value['structuredContent']['result'], state(False)) - send('tools/call', 4, {'name': 'project_files_save', 'arguments': bound()}) - value = read()['result']; self.assertTrue(value['isError']); self.assertEqual(value['structuredContent']['result']['code'], 'stale_checkpoint') - - -if __name__ == '__main__': - unittest.main() diff --git a/tests/test_project_files_fork_contracts.py b/tests/test_project_files_fork_contracts.py deleted file mode 100644 index b731de2c..00000000 --- a/tests/test_project_files_fork_contracts.py +++ /dev/null @@ -1,62 +0,0 @@ -"""Additive fork text results retain import-only v1 contract identities.""" -import copy -import json -from pathlib import Path -import re -import unittest -from unittest.mock import Mock - -import agent_api as api -from tuldok_client import ProjectFilesClient -from test_project_files_clients import client,record,result,bound,BINDING,PROJECT,RECORD,CHECKPOINT,OTHER - - -def fork_result(): - value=result();value['record']['provenance']={'method':'project_fork','rights':'Exact retained fixture rights', - 'origin':{'project_id':'a'*32,'checkpoint':OTHER,'family':'workbench_record','id':'f'*32,'revision':3,'source_revision':1}} - value['history']=[copy.deepcopy(value['record'])] - return value - - -class ForkTextContracts(unittest.TestCase): - def test_old_pins_stay_exact_and_only_v2_accepts_closed_fork_origins(self): - expected={'project_files.get':'6b0f4e16a00aa119b86cbb5493be0bac945ff08a5e63773a8f2c2f9296658d5b', - 'project_files.annotate':'70feae2ad14c49c4ae95b5bb69b4a50fbf93191cde840544cf89b6cbe8dc5c58'} - for name,sha in expected.items(): - self.assertEqual(api.contract(name,1)['sha256'],sha) - envelope={'status':200,'result':fork_result()} - api.validate_output(name,envelope,2) - with self.assertRaises(api.AgentAPIError):api.validate_output(name,envelope,1) - for patch in ({'family':'dataset_release'},{'source_revision':0},{'credential':'reject'}): - invalid=copy.deepcopy(envelope);invalid['result']['record']['provenance']['origin'].update(patch) - with self.assertRaises(api.AgentAPIError):api.validate_output(name,invalid,2) - source=(Path(__file__).resolve().parents[1]/'static/project-files.js').read_text() - versions=json.loads(re.search(r'PROJECT_FILES_VERSIONS_START \*/\s*(.*?)\s*/\* PROJECT_FILES_VERSIONS_END',source,re.S)[1]) - health = 'project_files.execution_health' - self.assertEqual(api.contract(health,1)['sha256'], - 'c3b1d0017f5a49cf69c3a4c5c33e1d3db9846404d12627563d97ef40de7404a5') - comparison = 'project_files.measurement_compare' - self.assertEqual(versions,{name:{str(v):api.contract(name,v)['sha256'] for v in (1,2)} - for name in (*expected, health, comparison)}) - - def test_sdk_selects_v2_and_falls_back_to_exact_v1_without_falsifying_provenance(self): - value=fork_result();raw=client({'status':200,'result':value});sdk=ProjectFilesClient(raw) - self.assertEqual(sdk.get(RECORD,binding=BINDING,checkpoint=CHECKPOINT),value) - self.assertEqual(raw._request.call_args.kwargs['selection'],('project_files.get',2)) - annotation={'revision':1,'source_revision':1,'task':'text_classification','annotation':{'label':'new'},'groups':['source'],'review':'draft'} - sdk.annotate(RECORD,annotation,**bound()) - self.assertEqual(raw._request.call_args.kwargs['selection'],('project_files.annotate',2)) - old=client({'status':200,'result':result()});original=old._request.side_effect - def v1(method,path,body=None,**kwargs): - envelope=original(method,path,body,**kwargs) - if path=='/api/agent/capabilities': - for operation in envelope['result']['operations']: - operation['contracts']=[c for c in operation['contracts'] if c['version']==1] - return envelope - old._request.side_effect=v1;ProjectFilesClient(old).get(RECORD,binding=BINDING,checkpoint=CHECKPOINT) - self.assertEqual(old._request.call_args.kwargs['selection'],('project_files.get',1)) - old._request=Mock(return_value={'status':200,'result':value}) - with self.assertRaises(api.AgentAPIError):ProjectFilesClient(old).get(RECORD,binding=BINDING,checkpoint=CHECKPOINT) - - -if __name__=='__main__':unittest.main() diff --git a/tests/test_project_files_http.py b/tests/test_project_files_http.py deleted file mode 100644 index edef4f68..00000000 --- a/tests/test_project_files_http.py +++ /dev/null @@ -1,463 +0,0 @@ -"""Real authenticated project-file transport with disposable PostgreSQL catalogs. - -Set TULDOK_DATABASE_URL to a disposable local database. An optional distinct -TULDOK_PROJECT_FILES_COLD_DATABASE_URL also proves reconstruction without the -source role/database; no lab fixture or execution service is used. -""" -from datetime import timedelta -import hashlib -import importlib.util -from http.server import ThreadingHTTPServer -import json -import os -from pathlib import Path -import shutil -import subprocess -import sys -import tempfile -import threading -import time -import unittest -from urllib.error import HTTPError -from urllib.parse import urlencode, urlsplit -from urllib.request import Request, urlopen -import uuid - -import psycopg -from psycopg import sql - -sys.path.insert(0, str(Path(__file__).resolve().parents[1])) -from app import make_handler -import agent_api -from auth_helpers import ExplicitOwnerFixture -from metadata import connection_info -from project_workspace import ProjectWorkspace - -API = '/api/workspace/project-files' -TEXT = 'Café 山 🧪 — authored source\nA scientist’s unique rationale.\n' - - -def canonical_bytes(directory): - """Track only portable authored files, ignoring local operational state.""" - result = {} - for file in directory.rglob('*'): - relative = file.relative_to(directory) - if any(part in ('.git', '.tuldok-local') for part in relative.parts): - continue - if file.is_file() and not file.is_symlink(): - result[relative.as_posix()] = file.read_bytes() - return result - - -@unittest.skipUnless(os.environ.get('TULDOK_DATABASE_URL'), 'Requires disposable local PostgreSQL') -class ProjectFilesHTTP(unittest.TestCase): - def setUp(self): - self.temporary = tempfile.TemporaryDirectory(prefix='tuldok-project-files-http-') - self.path = Path(self.temporary.name) - self.external = self.path / 'external' - self.external.mkdir() - self.hosts = [] - self.schemas = [] - self.controls = [] - self.addCleanup(self.temporary.cleanup) - self.addCleanup(self.cleanup_owned) - self.select_host(self.path / 'control', {'fixture': self.external}) - - def cleanup_owned(self): - for workspace, server, thread in reversed(self.hosts): - server.shutdown() - server.server_close() - thread.join(5) - workspace.close() - for dsn, schema in self.schemas: - with psycopg.connect(connection_info(dsn), autocommit=True) as connection: - connection.execute(sql.SQL('DROP SCHEMA IF EXISTS {} CASCADE').format(sql.Identifier(schema))) - # Projection manifests are physical identities, distinct from logical project IDs. - from project_working_store import registered_schemas - for dsn, control in self.controls: - for schema in registered_schemas(control): - with psycopg.connect(connection_info(dsn), autocommit=True) as connection: - connection.execute(sql.SQL('DROP SCHEMA IF EXISTS {} CASCADE').format(sql.Identifier(schema))) - for manifest in control.rglob('.tuldok.json'): - value = json.loads(manifest.read_bytes()) - schema = ('projection_' + value['projection_id'] if value['version'] == 2 - else 'catalog_' + value['dataset_id']) - with psycopg.connect(connection_info(dsn), autocommit=True) as connection: - connection.execute(sql.SQL('DROP SCHEMA IF EXISTS {} CASCADE').format(sql.Identifier(schema))) - - def select_host(self, control, roots, dsn=None): - dsn = dsn or os.environ['TULDOK_DATABASE_URL'] - workspace = ProjectWorkspace(control, roots, dsn=dsn) - self.schemas.append((dsn, workspace.db.schema)) - self.controls.append((dsn, Path(control))) - owner = ExplicitOwnerFixture.bootstrap(workspace) - server = ThreadingHTTPServer(('127.0.0.1', 0), make_handler(workspace)) - thread = threading.Thread(target=server.serve_forever, daemon=True) - thread.start() - self.hosts.append((workspace, server, thread)) - self.workspace, self.owner = workspace, owner - self.origin = f'http://127.0.0.1:{server.server_port}' - - def request(self, path, body=None, *, authenticated=True, method=None, token=None): - headers = {'Content-Type': 'application/json', 'Origin': self.origin} - route = urlsplit(path).path - if route == API: - operation = 'status' - elif route == API + '/records': - operation = 'query' - elif route.startswith(API + '/records/'): - operation = 'annotate' if body is not None else 'get' - elif route.startswith(API + '/'): - operation = route.removeprefix(API + '/').replace('-', '_') - else: - operation = None - if operation is not None: - headers['Tuldok-Operation-Contract'] = agent_api.selected_header('project_files.' + operation) - if authenticated: - headers['Authorization'] = 'Bearer ' + (token or self.owner.token) - request = Request(self.origin + path, - data=None if body is None else json.dumps(body, ensure_ascii=False).encode(), - headers=headers, method=method) - try: - response = urlopen(request, timeout=getattr(self, 'request_timeout_seconds', 15)) - except HTTPError as error: - response = error - with response: - raw = response.read() - value = json.loads(raw) if response.headers.get_content_type() == 'application/json' else raw - return response.status, value - - def state(self): - status, value = self.request(API) - self.assertEqual(status, 200, value) - self.assertEqual(value['format'], 'project_files_state_v1') - return value - - def envelope(self, state=None, **extra): - state = state or self.state() - return {'binding': state['binding'], - 'expected_checkpoint': state['project']['checkpoint'] if state['project'] else None, - 'request_key': uuid.uuid4().hex, **extra} - - def action(self, action_name, state=None, **extra): - status, value = self.request(API + '/' + action_name, self.envelope(state, **extra)) - self.assertIn(status, (200, 201), value) - return value - - def records(self, state=None): - state = state or self.state() - query = urlencode({'binding': state['binding'], 'checkpoint': state['project']['checkpoint']}) - status, value = self.request(API + '/records?' + query) - self.assertEqual(status, 200, value) - return value['items'] - - def detail(self, identifier, state=None): - state = state or self.state() - arguments = {'binding': state['binding'], 'checkpoint': state['project']['checkpoint'], 'history_limit': 4} - status, value = self.request(API + '/records/' + identifier + '?' + urlencode(arguments)) - self.assertEqual(status, 200, value) - history = list(value['history']) - cursor = value['next_history_before_revision'] - while cursor is not None: - arguments['before_revision'] = cursor - status, page = self.request(API + '/records/' + identifier + '?' + urlencode(arguments)) - self.assertEqual(status, 200, page) - self.assertEqual(page['record'], value['record']) - history.extend(page['history']) - cursor = page['next_history_before_revision'] - return {**value, 'history': history, 'next_history_before_revision': None} - - def create(self): - before = self.state() - self.action('new', root='fixture', directory='alpha', name='External café 🧪') - opened = self.state() - self.assertEqual(opened['state'], 'open') - self.assertNotEqual(opened['binding'], before['binding']) - return opened - - def import_text(self): - self.action('import-text', asset={'name': 'Unicode source 山', 'text': TEXT, - 'groups': ['source-fixture'], 'parents': [], - 'rights': 'Owned synthetic verification input'}) - records = self.records() - self.assertEqual(len(records), 1) - record = self.detail(records[0]['id'])['record'] - self.assertEqual(record['text'], TEXT) - return record - - def test_authenticated_owner_only_selection_and_inert_control(self): - self.assertEqual(self.request(API, authenticated=False)[0], 401) - state = self.state() - self.assertEqual(state['state'], 'no_project_open') - self.assertIsNone(state['project']) - self.assertIn('fixture', state['roots']) - for name in ('runs', 'jobs', 'generation_jobs', 'caption_proposals'): - self.assertFalse(hasattr(self.workspace, name), name + ' must not be constructed') - with self.owner.bound(self.workspace): - editor = self.workspace.access.issue({'label': 'Fixture editor', 'scopes': ['inspect', 'edit']}) - status, _ = self.request(API + '/new', self.envelope(state, root='fixture', directory='editor', name='Denied'), token=editor['token']) - self.assertEqual(status, 403) - self.assertFalse((self.external / 'editor').exists()) - self.assertEqual(self.state()['binding'], state['binding']) - - def test_cold_copy_reconstructs_exact_identity_values_and_history_without_credentials(self): - self.create() - initial = self.import_text() - first = self.detail(initial['id']) - body = {'revision': initial['revision'], 'source_revision': initial['source_revision'], - 'task': 'text_classification', 'annotation': {'label': 'positive 山'}, - 'groups': ['source-fixture', 'review-fixture'], 'review': 'human_reviewed'} - status, value = self.request(API + '/records/' + initial['id'], self.envelope(annotation=body)) - self.assertEqual(status, 200, value) - expected = self.detail(initial['id']) - self.assertEqual(expected['record']['annotation'], {'label': 'positive 山'}) - self.assertGreater(len(expected['history']), len(first['history'])) - self.assertEqual(expected['record']['revision'], initial['revision'] + 1) - self.action('save') - source_state = self.state() - source = self.external / 'alpha' - scripts = source / 'scripts' - scripts.mkdir(exist_ok=True) - trap = scripts / 'must-not-run.py' - trap.write_text("from pathlib import Path\nPath(__file__).with_name('EXECUTED').write_text('unsafe')\n") - before = canonical_bytes(source) - self.assertTrue(before) - raw = b'\n'.join(before.values()) - for secret in (self.owner.token.encode(), hashlib.sha256(self.owner.token.encode()).hexdigest().encode(), - b'access_credentials', b'Authorization', b'TULDOK_DATABASE_URL'): - self.assertNotIn(secret, raw) - self.action('close') - self.assertEqual(self.state()['state'], 'no_project_open') - relocated = self.path / 'cold-external' - relocated.mkdir() - shutil.copytree(source, relocated / 'clone', ignore=shutil.ignore_patterns('.tuldok-local')) - self.assertEqual(canonical_bytes(relocated / 'clone'), before) - cold_dsn = os.environ.get('TULDOK_PROJECT_FILES_COLD_DATABASE_URL', os.environ['TULDOK_DATABASE_URL']) - if 'TULDOK_PROJECT_FILES_COLD_DATABASE_URL' in os.environ: - source_database = psycopg.conninfo.conninfo_to_dict(connection_info(os.environ['TULDOK_DATABASE_URL']))['dbname'] - with psycopg.connect(connection_info(cold_dsn)) as connection: - database, source_access = connection.execute( - 'SELECT current_database(), has_database_privilege(current_user,%s,\'CONNECT\')', - (source_database,)).fetchone() - self.assertNotEqual(database, source_database) - self.assertFalse(source_access, 'Cold role must not connect to the source database') - self.select_host(self.path / 'fresh-control', {'fixture': relocated}, cold_dsn) - self.action('open', root='fixture', directory='clone') - cold = self.state() - self.assertEqual(cold['project'], source_state['project']) - actual = self.detail(initial['id']) - self.assertEqual(actual['record'], expected['record']) - self.assertEqual(actual['history'], expected['history']) - self.action('save') - self.assertEqual(canonical_bytes(relocated / 'clone'), before, 'No-op Save has no canonical byte changes') - self.assertFalse((relocated / 'clone' / 'scripts' / 'EXECUTED').exists()) - - def test_old_binding_and_stale_checkpoint_reject_without_canonical_effect(self): - self.create() - old = self.state() - record = self.import_text() - current = self.state() - self.assertNotEqual(old['project']['checkpoint'], current['project']['checkpoint']) - stale_query = urlencode({'binding': old['binding'], 'checkpoint': old['project']['checkpoint']}) - self.assertEqual(self.request(API + '/records?' + stale_query)[0], 409) - before = canonical_bytes(self.external / 'alpha') - status, _ = self.request(API + '/save', self.envelope(old)) - self.assertEqual(status, 409) - self.assertEqual(canonical_bytes(self.external / 'alpha'), before) - self.action('close') - self.action('open', root='fixture', directory='alpha') - self.assertNotEqual(self.state()['binding'], current['binding']) - status, _ = self.request(API + '/import-text', self.envelope(current, asset={ - 'name': 'Delayed wrong binding', 'text': 'Must not commit', 'groups': ['fixture'], 'parents': [], 'rights': 'fixture'})) - self.assertEqual(status, 409) - self.assertEqual(canonical_bytes(self.external / 'alpha'), before) - self.assertEqual([item['id'] for item in self.records()], [record['id']]) - - def test_legacy_mutations_are_unavailable_before_and_after_open(self): - for opened in (False, True): - if opened: - self.create() - before = canonical_bytes(self.external) - for path in ('/api/samples', '/api/workbench/import', '/api/workspace/runs', - '/api/releases', '/api/workspace/datasets'): - with self.subTest(opened=opened, path=path): - status, value = self.request(path, {'kind': 'image', 'image': 'fixture', 'name': 'Must not write'}) - self.assertIn(status, (403, 404, 405, 409), value) - self.assertEqual(canonical_bytes(self.external), before) - self.assertEqual(list((self.path / 'control').rglob('*.png')), []) - - def test_real_deferred_sql_failure_rolls_back_the_edit_and_a_retry_succeeds(self): - self.create() - selected = self.state() - projection_schema = self.workspace._projection.schema - # A real deferred PostgreSQL trigger fails the outer SQL COMMIT. Records - # and projection rows share that transaction, so both roll back. - with psycopg.connect(connection_info(), autocommit=True) as connection: - function = sql.Identifier(projection_schema, 'qa_reject_projection_commit') - table = sql.Identifier(projection_schema, 'workbench_records') - connection.execute(sql.SQL('''CREATE FUNCTION {}() RETURNS trigger LANGUAGE plpgsql - AS $$ BEGIN RAISE EXCEPTION 'Disposable QA deferred commit failure' USING ERRCODE='23514'; END; $$''').format(function)) - connection.execute(sql.SQL('''CREATE CONSTRAINT TRIGGER qa_reject_projection_commit - AFTER INSERT ON {} DEFERRABLE INITIALLY DEFERRED - FOR EACH ROW EXECUTE FUNCTION {}()''').format(table, function)) - asset = {'name': 'Rejected with its SQL commit 山', 'text': TEXT, - 'groups': ['recovery'], 'parents': [], 'rights': 'Owned synthetic recovery fixture'} - original = self.envelope(selected, asset=asset) - before = canonical_bytes(self.external / 'alpha') - status, error = self.request(API + '/import-text', original) - self.assertEqual(status, 409, error) - self.assertEqual(error['code'], 'rejected') - self.assertEqual(self.state(), selected, 'Nothing changed; the project stays open and current') - self.assertEqual(self.records(selected), []) - self.assertEqual(canonical_bytes(self.external / 'alpha'), before) - with psycopg.connect(connection_info(), autocommit=True) as connection: - connection.execute(sql.SQL('DROP TRIGGER qa_reject_projection_commit ON {}').format( - sql.Identifier(projection_schema, 'workbench_records'))) - status, imported = self.request(API + '/import-text', original) - self.assertEqual(status, 200, imported) - records = self.records() - self.assertEqual(len(records), 1) - self.assertEqual(self.detail(records[0]['id'])['record']['text'], TEXT) - self.assertEqual(canonical_bytes(self.external / 'alpha'), before, 'Edits are not written until Save') - - @unittest.skipUnless(importlib.util.find_spec('mcp') and importlib.util.find_spec('anyio'), - 'Requires the pinned optional MCP environment for real adapter acceptance') - def test_real_owner_sdk_cli_and_agent_sdk_mcp_share_authenticated_project(self): - import anyio - from mcp import ClientSession, StdioServerParameters - from mcp.client.stdio import stdio_client - from tuldok_client import ProjectFilesClient - - repository = Path(__file__).resolve().parents[1] - owner_client = agent_api.ProjectFilesOwnerClient(self.origin, self.owner.token, self.owner.catalog_id, timeout=15) - bootstrapped = owner_client.bootstrap() - self.assertEqual(bootstrapped['identity']['kind'], 'owner') - self.assertIn('project_files.new', bootstrapped['operations']) - owner_files = ProjectFilesClient(owner_client) - initial = owner_files.status() - opened = owner_files.new(root='fixture', directory='adapter', name='SDK CLI MCP café 山', - **self.envelope(initial)) - with self.owner.bound(self.workspace): - credential = self.workspace.access.issue({'label': 'Real adapter fixture agent', 'scopes': ['inspect', 'edit']}) - agent = agent_api.AgentClient(self.origin, credential['token'], self.owner.catalog_id, timeout=15) - self.assertEqual(agent.bootstrap()['identity']['kind'], 'agent') - with self.assertRaises(agent_api.AgentAPIError) as wrong_identity: - agent_api.AgentClient(self.origin, self.owner.token, self.owner.catalog_id, timeout=15).bootstrap() - self.assertEqual(wrong_identity.exception.code, 'unauthenticated') - files = ProjectFilesClient(agent) - imported = files.import_text({'name': 'Actual adapters 山', 'text': TEXT, 'groups': ['adapters'], - 'parents': [], 'rights': 'Owned synthetic adapter fixture'}, - **self.envelope(opened)) - record = imported['record'] - annotation = {'revision': record['revision'], 'source_revision': record['source_revision'], - 'task': 'text_corpus', 'annotation': {'note': 'Agent-authored historical note 山'}, - 'groups': ['adapters'], 'review': 'draft'} - annotated = files.annotate(record['id'], annotation, **self.envelope(self.state())) - self.assertEqual(annotated['record']['annotation'], annotation['annotation']) - stable = self.state() - before = canonical_bytes(self.external / 'adapter') - denied = agent.call('project_files.close', self.envelope(stable)) - self.assertEqual(denied['status'], 403) - denied_review = dict(annotation, revision=annotated['record']['revision'], review='human_reviewed') - denied = agent.call('project_files.annotate', dict(self.envelope(stable), - record_id=record['id'], annotation=denied_review)) - self.assertEqual(denied['status'], 403) - self.assertEqual(canonical_bytes(self.external / 'adapter'), before) - query_arguments = {'binding': stable['binding'], 'checkpoint': stable['project']['checkpoint'], 'limit': 1} - queried = agent.call('project_files.query', query_arguments) - self.assertEqual(queried['status'], 200) - self.assertEqual([item['id'] for item in queried['result']['items']], [record['id']]) - self.assertNotIn('text', queried['result']['items'][0], 'The list returns bounded summaries') - print('Actual adapter SDK authoring and authorization assertions passed', flush=True) - - def configuration(name, token): - token_file, config_file = self.path / (name + '.token'), self.path / (name + '.config.json') - token_file.write_text(token + '\n'); token_file.chmod(0o600) - config_file.write_text(json.dumps({'endpoint': self.origin, 'catalog_id': self.owner.catalog_id, - 'token_file': str(token_file), 'timeout': 15})) - config_file.chmod(0o600) - return config_file - - owner_config = configuration('adapter-owner', self.owner.token) - agent_config = configuration('adapter-agent', credential['token']) - environment = {key: value for key, value in os.environ.items() - if not key.startswith(('TULDOK_', 'PG'))} - environment['PYTHONDONTWRITEBYTECODE'] = '1' - - def owner_cli(action, current, **extra): - arguments = self.envelope(current) - command = [sys.executable, str(repository / 'project_cli.py'), '--config', str(owner_config), - '--owner-project-files', 'file-' + action, - '--binding', arguments['binding'], '--expected-checkpoint', - arguments['expected_checkpoint'] or 'null', '--request-key', arguments['request_key']] - for key, value in extra.items(): - command.extend(['--' + key, value]) - result = subprocess.run(command, cwd=repository, env=environment, - capture_output=True, text=True, timeout=30) - self.assertEqual(result.returncode, 0, result.stderr) - self.assertNotIn(self.owner.token, result.stdout + result.stderr) - return json.loads(result.stdout) - - self.assertEqual(owner_cli('save', stable)['project'], stable['project']) - closed = owner_cli('close', self.state()) - self.assertEqual(closed['state'], 'no_project_open') - reopened = owner_cli('open', closed, root='fixture', directory='adapter') - self.assertEqual(reopened['project'], stable['project']) - expected = self.detail(record['id']) - print('Actual owner CLI Save/Close/Open assertions passed', flush=True) - - async def exercise(): - started = time.monotonic() - parameters = StdioServerParameters(command=sys.executable, - args=[str(repository / 'mcp_stdio.py'), '--config', str(agent_config)], - cwd=str(repository), env=environment) - with (self.path / 'actual-mcp.stderr').open('w+') as errors: - async with stdio_client(parameters, errlog=errors) as (reader, writer): - async with ClientSession(reader, writer, read_timeout_seconds=timedelta(seconds=20)) as session: - await session.initialize() - print(json.dumps({'actual_mcp_initialize_seconds': time.monotonic() - started, - 'initialize_deadline_seconds': 20}), flush=True) - tools = {tool.name for tool in (await session.list_tools()).tools} - self.assertTrue({'project_files_status', 'project_files_query', 'project_files_get', - 'project_files_annotate'} <= tools) - - async def tool(name, arguments, expected_status=200): - response = await session.call_tool(name.replace('.', '_'), arguments) - self.assertEqual(response.isError, expected_status >= 400) - envelope = response.structuredContent - self.assertEqual(envelope['status'], expected_status, envelope) - self.assertEqual(json.loads(response.content[0].text), envelope) - return envelope['result'] - - current = await tool('project_files.status', {}) - selected = {'binding': current['binding'], 'checkpoint': current['project']['checkpoint']} - found = await tool('project_files.query', dict(selected, limit=1)) - self.assertEqual([item['id'] for item in found['items']], [record['id']]) - actual = await tool('project_files.get', dict(selected, record_id=record['id'], history_limit=4)) - self.assertEqual(actual['record'], expected['record']) - self.assertEqual(actual['history'], expected['history']) - mcp_annotation = dict(annotation, revision=actual['record']['revision'], - annotation={'note': 'Actual MCP retained note café 🧪'}) - saved = await tool('project_files.annotate', dict(self.envelope(current), - record_id=record['id'], annotation=mcp_annotation)) - self.assertEqual(saved['record']['annotation'], mcp_annotation['annotation']) - after_edit = await tool('project_files.get', dict(binding=saved['binding'], - checkpoint=saved['checkpoint'], record_id=record['id'], history_limit=4)) - self.assertEqual(len(after_edit['history']), 3) - self.assertTrue(any(item['annotation'] == annotation['annotation'] - for item in after_edit['history'])) - before_revocation = canonical_bytes(self.external / 'adapter') - with self.owner.bound(self.workspace): - self.workspace.access.revoke(credential['identity']['credential_id']) - refusal = await tool('project_files.status', {}, 401) - self.assertEqual(refusal['code'], 'unauthenticated') - self.assertEqual(agent.call('project_files.status', {})['status'], 401) - self.assertEqual(canonical_bytes(self.external / 'adapter'), before_revocation) - errors.seek(0) - self.assertNotIn(credential['token'], errors.read()) - - anyio.run(exercise) - - -if __name__ == '__main__': - unittest.main() diff --git a/tests/test_project_files_m2_http.py b/tests/test_project_files_m2_http.py deleted file mode 100644 index 9d66176f..00000000 --- a/tests/test_project_files_m2_http.py +++ /dev/null @@ -1,453 +0,0 @@ -"""Real M2 public acceptance using disposable PostgreSQL and authored fixtures. - -No training, runtime preflight, provider or user catalog belongs to this suite. -Run only after the lead enables M2 and freezes the complete working source. -""" -import base64 -from datetime import timedelta -import hashlib -import http.client -import importlib.util -import io -import json -import os -from pathlib import Path -import shutil -import subprocess -import sys -import time -import unittest -from urllib.error import HTTPError -from urllib.request import Request, urlopen -import uuid - -from PIL import Image -import psycopg - -import agent_api -import project_workspace -import test_project_files_http as m1 - -ROOT = Path(__file__).resolve().parents[1] -NOTE = 'M2 retained rationale café 山 — exact authored scientific note.' -RIGHTS = 'Owned synthetic source; corrected by M2 acceptance café 山.' -SOURCE_FILES = ('app.py','agent_api.py','access.py','project_workspace.py','project_dispatch.py', - 'project_projection.py','project_data.py','project_sources.py','project_material.py', - 'project_history.py','project_producers.py','project_session.py','project_store.py', - 'static/project-files.js','static/project-files.html','tuldok_client.py','project_cli.py','mcp_stdio.py', - 'static/scientific-inspector.js','static/scientific-inspector.css','static/scientific-fields.js', - 'static/workbench.html','static/workbench.css') -SOURCE_FILES+=('project_measurements.py','retained_measurements.py','project_fork_composition.py') -SOURCE_FILES+=('static/retained-chart.js','static/project-measurements.js','static/project-measurements.css', - 'static/retained-measurement-maxima.vl.json') - - -def subject_hashes(): - return {name:hashlib.sha256((ROOT/name).read_bytes()).hexdigest() for name in SOURCE_FILES} - - -def authored_source(root): - from qualify_scientific_fields import neutral_bundle - raw=neutral_bundle();(root/'observed-fields.zip').write_bytes(raw) - manifest={'schema_version':1,'id':uuid.uuid4().hex,'name':'Authored observed fields café 山', - 'data':[{'id':'fields','label':'Exact authored scientific array','path':'observed-fields.zip','sha256':hashlib.sha256(raw).hexdigest()}], - 'recipes':[],'evidence':[],'requirements':[]} - (root/'source-project.json').write_text(json.dumps(manifest,indent=3,ensure_ascii=False)+'\n') - return manifest,raw - - -@unittest.skipUnless(os.environ.get('TULDOK_DATABASE_URL'), 'Requires disposable real local PostgreSQL') -class ProjectFilesM2HTTP(unittest.TestCase): - cleanup_owned=m1.ProjectFilesHTTP.cleanup_owned - select_host=m1.ProjectFilesHTTP.select_host - request=m1.ProjectFilesHTTP.request - state=m1.ProjectFilesHTTP.state - envelope=m1.ProjectFilesHTTP.envelope - action=m1.ProjectFilesHTTP.action - create=m1.ProjectFilesHTTP.create - - def setUp(self): - self.assertTrue(project_workspace.M2_ENABLED,'Lead must enable and freeze M2 before acceptance execution') - self.subject=subject_hashes();self.started=time.monotonic();self.operations=[] - m1.ProjectFilesHTTP.setUp(self) - self.addCleanup(self.receipt) - - def receipt(self): - directory=Path(os.environ.get('TULDOK_QA_OUTPUT_ROOT','/workspace/scratch/tuldok-save-load-qa/artifacts'))/'m2-http' - directory.mkdir(parents=True,exist_ok=True) - current=subject_hashes() - (directory/(self._testMethodName+'-'+uuid.uuid4().hex+'.json')).write_text(json.dumps({ - 'test':self.id(),'seconds':round(time.monotonic()-self.started,3),'operations':self.operations, - 'source_sha256':self.subject,'end_sha256':current,'source_stable':current==self.subject, - 'fixture':'Disposable authored synthetic inputs; no runtime execution or scientific validity claim.'},indent=2)+'\n') - self.assertEqual(current,self.subject,'Product source changed during actual acceptance') - - def arguments(self, action, **fields): - op=agent_api.operation('project_files.'+action) - state=self.state() - bound=(self.envelope(state) if op['side_effects'] else - {'binding':state['binding'],'checkpoint':state['project']['checkpoint']}) - return dict(bound,**fields) - - def transport(self, action, arguments, *, token=None): - name='project_files.'+action - method,target,body=agent_api.project_request(name,arguments) - headers={'Authorization':'Bearer '+(token or self.owner.token),'Content-Type':'application/json', - 'Origin':self.origin,'Tuldok-Operation-Contract':agent_api.selected_header(name)} - request=Request(self.origin+target,data=None if body is None else json.dumps(body,ensure_ascii=False).encode(), - headers=headers,method=method) - try:response=urlopen(request,timeout=30) - except HTTPError as error:response=error - with response:status,value=response.status,json.load(response) - self.operations.append({'operation':name,'status':status}) - return status,value - - def call(self, action, *, token=None, **fields): - status,envelope=self.transport(action,self.arguments(action,**fields),token=token) - self.assertEqual(status,200,envelope) - self.assertEqual(envelope['binding'],self.state()['binding']) - return envelope['value'] - - def data(self, record_id):return self.call('data_get',record_id=record_id) - - def image(self): - out=io.BytesIO();Image.new('RGB',(20,12),'#3355aa').save(out,'PNG') - raw=out.getvalue() - row=self.call('data_import_image',image=base64.b64encode(raw).decode(),name='Authored blue image café 山', - groups=['m2-image'],rights='Owned synthetic pixels') - return row,raw - - def retain_authored_history(self): - # Import is M5. Author this explicitly synthetic archived observation - # through the real closed codec; public readers/disclosure stay real. - from test_project_history import legacy_run - from project_history import capture_run,declarations - projection=self.workspace._projection - run=legacy_run(projection.project_id) - run['source_records']=[{'id':'frozen-example','kind':'text','split':'test', - 'text':'PRIVATE-HOLDOUT-M2-SENTINEL','target':'PRIVATE-TARGET-M2-SENTINEL'}] - run['evidence_context']={'fixture':'PRIVATE-CONTEXT-M2-SENTINEL'} - record=capture_run(run,payloads=[]) - before=projection.session.snapshot - records=before['records']+[record,*declarations(record)] - projection.validate_records(records) - snapshot=projection.store.commit(records,before['checkpoint'],uuid.uuid4().hex,'e'*64) - projection.session.adopt(snapshot) - return run,record - - def config(self,name,token): - secret=self.path/(name+'.token');secret.write_text(token+'\n');secret.chmod(0o600) - config=self.path/(name+'.json');config.write_text(json.dumps({'endpoint':self.origin, - 'catalog_id':self.owner.catalog_id,'token_file':str(secret),'timeout':30}));config.chmod(0o600) - return config - - def test_progression_public_reads_pin_origin_scope_and_checkpoint(self): - from test_project_history import policy - self.create();old_checkpoint=self.state()['project']['checkpoint'] - self.call('study_create',name='Saved progression fixture', - limits={'attempt_slots':3,'admitted_wall_seconds':100,'retained_bytes':1000000,'peak_staging_bytes':1000000}, - policy=policy()) - origin=self.state()['project']['project_id'] - with self.owner.bound(self.workspace): - inspector=self.workspace.access.issue({'label':'Progression inspector','scopes':['inspect']}) - before=m1.canonical_bytes(self.external/'alpha') - origins=self.call('progression_origins',token=inspector['token']) - self.assertEqual(origins['items'],[{'origin_catalog_id':origin,'study_count':1,'trial_count':0}]) - result=self.call('progression',token=inspector['token'],origin_catalog_id=origin,limit=1) - self.assertEqual(result['nodes'],[]);self.assertEqual(result['related'],[]) - self.assertEqual(result['evidence'],'saved_metadata_only') - self.assertFalse(result['execution_available']) - with self.owner.bound(self.workspace): - self.workspace.access.revoke(inspector['identity']['credential_id']) - for action,args in [('progression_origins',{}),('progression',{'origin_catalog_id':origin})]: - arguments=self.arguments(action,**args) - self.assertEqual(self.transport(action,arguments,token=inspector['token'])[0],401) - self.assertEqual(self.transport(action,dict(arguments,checkpoint=old_checkpoint))[0],409) - status,error=self.transport('progression',self.arguments('progression',origin_catalog_id='f'*32)) - self.assertEqual(status,409);self.assertEqual(error['code'],'not_found') - self.assertEqual(m1.canonical_bytes(self.external/'alpha'),before) - - def test_public_mixed_authoring_git_clone_and_cold_reconstruction(self): - self.create();image,raw=self.image() - image=self.call('data_annotate',record_id=image['id'],revision=image['revision'],source_revision=image['source_revision'], - task='image_caption',annotation={'caption':NOTE},groups=['m2-image','m2-review'],review='human_reviewed') - corrected=self.call('data_rights',record_id=image['id'],revision=image['revision'],source_revision=image['source_revision'],note=RIGHTS) - image=corrected['record'];self.assertEqual(image['provenance']['rights_note_correction']['note'],RIGHTS) - history=self.call('data_history',record_id=image['id'],limit=4) - self.assertTrue(any(row['annotation']=={'caption':NOTE} for row in history['items'])) - selection=self.call('selection_create',document={'name':'Frozen image revision 山', - 'items':[{key:image[key] for key in ('id','revision','source_revision')}]}) - search=self.call('search_create',document={'name':'Entered exact source search 山', - 'criteria':{'q':'café','kind':'image','review':'','sort':'newest','task':'','label':'','group':'','rights':''}}) - search=self.call('search_rename',search_id=search['id'],revision=1,name='Renamed saved search 山') - definitions=self.call('definitions') - template=next(item['model_template'] for item in definitions['recipes'] if item.get('model_template')) - model=self.call('model_create',**dict(template,name='Retained safe model draft 山')) - model=self.call('model_save',model_id=model['id'],revision=model['revision'],document=dict(model,name='Revised model intent 山')) - material=self.call('model_publish',model_id=model['id'],revision=model['revision']) - self.assertEqual(self.call('model_material',ref=material['ref'],verify=True),material) - manifest,science=authored_source(self.external) - registered=self.call('source_register',root='fixture',manifest_path='source-project.json') - snapshotref={key:registered[key] for key in ('origin_catalog_id','project_id','manifest_sha256')} - references=self.call('source_references',**snapshotref,limit=1) - self.assertEqual(references['items'][0]['sha256'],hashlib.sha256(science).hexdigest()) - field=self.call('data_import_scientific',snapshot=snapshotref,reference_id='fields',expected_sha256=hashlib.sha256(science).hexdigest(), - document={'name':'Observed field sequence café 山','groups':['m2-science'],'rights':'Owned authored arrays'}) - self.assertEqual(field['kind'],'field_sequence') - field=self.call('data_annotate',record_id=field['id'],revision=field['revision'],source_revision=field['source_revision'], - task=field['task'],annotation={'note':NOTE},groups=field['groups'],review='human_reviewed') - policy={'format':'selection_policy_v1','metric_definition_sha256':'b'*64,'checkpoint_rule':'explicit', - 'replicate_reduce':'individual','required_capabilities':[],'numerical_acceptance':'diagnostic','tie_break':'trial_id'} - study=self.call('study_create',name='Scientific intent only 山',limits={'attempt_slots':3,'admitted_wall_seconds':100, - 'retained_bytes':1000000,'peak_staging_bytes':1000000},policy=policy) - study=self.call('study_save',study_id=study['id'],revision=study['revision'],name='Revised scientific intent 山',limits=study['limits'],policy=study['policy']) - origin=self.state()['project']['project_id'] - study_view=self.call('study',study_id=study['id'],origin_catalog_id=origin,limit=1) - self.assertEqual(study_view['study']['revision'],2) - self.assertTrue(all(value==0 for value in study_view['charged'].values())) - run,archived=self.retain_authored_history() - visible=self.call('run',run_id=run['id'],origin_catalog_id=origin,limit=1) - self.assertNotIn('PRIVATE-',json.dumps(visible)) - descriptor=visible['document'] - document_arguments=self.arguments('run_document_segment',run_id=run['id'],origin_catalog_id=origin, - expected_sha256=descriptor['sha256'],offset=0,limit=262144) - self.assertEqual(self.transport('run_document_segment',document_arguments)[0],403) - with self.owner.bound(self.workspace): - inspector=self.workspace.access.issue({'label':'M2 inspect only','scopes':['inspect']}) - before_denial=m1.canonical_bytes(self.external/'alpha') - self.assertEqual(self.transport('expose_holdout',self.arguments('expose_holdout',run_id=run['id'],origin_catalog_id=origin, - reason='No scope should deny this request'),token=inspector['token'])[0],403) - self.assertEqual(m1.canonical_bytes(self.external/'alpha'),before_denial) - self.call('expose_holdout',run_id=run['id'],origin_catalog_id=origin,reason='Inspect this authored synthetic holdout on this installation.') - segment=self.call('run_document_segment',run_id=run['id'],origin_catalog_id=origin, - expected_sha256=descriptor['sha256'],offset=0,limit=262144) - exact_document=base64.b64decode(segment['base64']) - self.assertIn(b'PRIVATE-HOLDOUT-M2-SENTINEL',exact_document) - self.assertEqual(hashlib.sha256(exact_document).hexdigest(),descriptor['sha256']) - # Missing retained material is a real filesystem negative; restore exact - # fixture bytes before Git/cold proof so no missing data is concealed. - blob=material['material']['source_closure'][0]['blob'] - payload=self.external/'alpha'/'artifacts'/'sha256'/blob['sha256'];saved=payload.read_bytes();payload.unlink() - (self.external/'retained-model-source.bin').write_bytes(saved) - try: - self.assertEqual(self.call('artifact_status',sha256=blob['sha256'])['state'],'missing') - status,error=self.transport('model_material',self.arguments('model_material',ref=material['ref'],verify=True)) - self.assertEqual(status,404,error) - self.assertEqual(self.call('model_material',ref=material['ref']),material) - self.call('artifact_resolve',sha256=blob['sha256'],root='fixture',path='retained-model-source.bin') - self.assertEqual(self.call('artifact_status',sha256=blob['sha256'])['state'],'verified') - self.assertEqual(payload.read_bytes(),saved) - finally: - if not payload.exists():payload.write_bytes(saved);payload.chmod(0o400) - expected={'image':self.data(image['id']),'image_history':self.call('data_history',record_id=image['id'],limit=4), - 'field':self.data(field['id']),'selection':self.call('selection_get',selection_id=selection['id']), - 'searches':self.call('searches'),'model':self.call('model_get',model_id=model['id']), - 'material':self.call('model_material',ref=material['ref'],verify=True),'study':study_view} - self.action('save');source_state=self.state();self.action('close') - source=self.external/'alpha';(source/'scripts').mkdir() - (source/'scripts'/'sentinel.py').write_text("from pathlib import Path\nPath(__file__).with_name('EXECUTED').write_text('bad')\n") - before=m1.canonical_bytes(source) - forbidden=(self.owner.token.encode(),hashlib.sha256(self.owner.token.encode()).hexdigest().encode(),os.environ['TULDOK_DATABASE_URL'].encode()) - for secret in forbidden:self.assertFalse(any(secret in raw for raw in before.values()),'Actual current credential or database binding leaked') - git_env=dict(os.environ,GIT_CONFIG_GLOBAL='/dev/null',GIT_CONFIG_NOSYSTEM='1',GIT_TERMINAL_PROMPT='0') - def git(*args):subprocess.run(['git',*args],check=True,stdout=subprocess.PIPE,stderr=subprocess.PIPE,env=git_env,timeout=30) - git('init','-q','--template=',str(source));git('-C',str(source),'add','.') - git('-C',str(source),'-c','user.name=Disposable QA','-c','user.email=qa@example.invalid','-c','commit.gpgsign=false', - '-c','core.hooksPath=/dev/null','commit','-qm','Authored M2 acceptance fixture') - coldroot=self.path/'cold-external';coldroot.mkdir();clone=coldroot/'clone' - git('-c','core.hooksPath=/dev/null','clone','-q','--no-hardlinks','--template=',str(source),str(clone)) - # Binary payloads are deliberately untracked. Transfer that owned - # sidecar explicitly; Git alone proves the authored text inventory. - shutil.copytree(source/'artifacts',clone/'artifacts') - self.assertEqual(m1.canonical_bytes(clone),before) - cold_dsn=os.environ['TULDOK_PROJECT_FILES_COLD_DATABASE_URL'] - source_db=psycopg.conninfo.conninfo_to_dict(os.environ['TULDOK_DATABASE_URL'])['dbname'] - with psycopg.connect(cold_dsn) as connection: - database,allowed=connection.execute('SELECT current_database(),has_database_privilege(current_user,%s,\'CONNECT\')',(source_db,)).fetchone() - self.assertNotEqual(database,source_db);self.assertFalse(allowed) - self.select_host(self.path/'cold-control',{'fixture':coldroot},cold_dsn) - self.action('open',root='fixture',directory='clone');self.assertEqual(self.state()['project'],source_state['project']) - self.assertEqual(self.data(image['id']),expected['image']);self.assertEqual(self.data(field['id']),expected['field']) - self.assertEqual(self.call('data_history',record_id=image['id'],limit=4),expected['image_history']) - self.assertEqual(self.call('selection_get',selection_id=selection['id']),expected['selection']) - self.assertEqual(self.call('searches'),expected['searches']);self.assertEqual(self.call('model_get',model_id=model['id']),expected['model']) - self.assertEqual(self.call('model_material',ref=material['ref'],verify=True),expected['material']) - self.assertEqual(self.call('study',study_id=study['id'],origin_catalog_id=origin,limit=1),expected['study']) - cold_run=self.call('run',run_id=run['id'],origin_catalog_id=origin,limit=1) - self.assertNotIn('PRIVATE-',json.dumps(cold_run)) - self.assertEqual(cold_run['document'],descriptor) - self.assertEqual(self.transport('run_document_segment',self.arguments('run_document_segment',run_id=run['id'],origin_catalog_id=origin, - expected_sha256=descriptor['sha256'],offset=0,limit=262144))[0],403,'Historical disclosure is no current authority') - status,error=self.transport('source_references',self.arguments('source_references',**snapshotref)) - self.assertEqual(status,409,error) # A historical path is no current source grant. - self.assertFalse((clone/'scripts'/'EXECUTED').exists()) - self.action('save');self.assertEqual(m1.canonical_bytes(clone),before) - - def test_unpinned_scientific_reference_uses_current_observed_hash(self): - self.create();manifest,raw=authored_source(self.external) - manifest['data'][0].pop('sha256') - (self.external/'source-project.json').write_text(json.dumps(manifest,ensure_ascii=False)) - registered=self.call('source_register',root='fixture',manifest_path='source-project.json') - reference={key:registered[key] for key in ('origin_catalog_id','project_id','manifest_sha256')} - item=self.call('source_references',**reference)['items'][0] - self.assertNotIn('sha256',item);self.assertEqual(item['integrity'],'unverified') - self.assertEqual(item['observed_sha256'],hashlib.sha256(raw).hexdigest()) - row=self.call('data_import_scientific',snapshot=reference,reference_id=item['id'],expected_sha256=item['observed_sha256'], - document={'name':'Unpinned but explicitly measured source','groups':['m2-unpinned'],'rights':'Owned authored data'}) - self.assertEqual(row['source_sha256'],item['observed_sha256']) - - def test_native_scientific_slice_refuses_stale_selection_and_changed_artifact(self): - self.create();_manifest,raw=authored_source(self.external) - registered=self.call('source_register',root='fixture',manifest_path='source-project.json') - snapshot={key:registered[key] for key in ('origin_catalog_id','project_id','manifest_sha256')} - row=self.call('data_import_scientific',snapshot=snapshot,reference_id='fields', - expected_sha256=hashlib.sha256(raw).hexdigest(), - document={'name':'Native slice source','groups':['m2-slice'],'rights':'Owned fixture'}) - arguments=self.arguments('data_scientific',record_id=row['id'],content_hash=row['content_hash'], - frame=1,field='scalar',axis='z',index=2) - before=m1.canonical_bytes(self.external/'alpha') - status,value=self.transport('data_scientific',arguments) - self.assertEqual(status,200,value) - self.assertEqual(value['value']['values'][1][2],1212+2**-45) - for change in ({'checkpoint':'0'*64},{'binding':'0'*32},{'content_hash':'0'*64}): - status,error=self.transport('data_scientific',dict(arguments,**change)) - self.assertEqual(status,409,error) - with self.owner.bound(self.workspace): - credential=self.workspace.access.issue({'label':'Revoked slice inspection','scopes':['inspect']}) - self.workspace.access.revoke(credential['identity']['credential_id']) - self.assertEqual(self.transport('data_scientific',arguments,token=credential['token'])[0],401) - self.assertEqual(m1.canonical_bytes(self.external/'alpha'),before) - path=self.external/'alpha/artifacts/sha256'/row['content_hash'] - self.assertEqual(path.read_bytes(),raw) - path.chmod(0o600) # Deliberate external corruption of this disposable fixture. - path.write_bytes(b'x'*len(raw)) - self.assertNotEqual(self.transport('data_scientific',arguments)[0],200) - path.unlink() - self.assertNotEqual(self.transport('data_scientific',arguments)[0],200) - - @unittest.skipUnless(importlib.util.find_spec('mcp'),'Requires pinned real MCP optional dependencies') - def test_real_sdk_cli_mcp_roles_lost_reply_and_stale_binding(self): - import anyio - from mcp import ClientSession,StdioServerParameters - from mcp.client.stdio import stdio_client - from tuldok_client import ProjectFilesClient - owner=agent_api.ProjectFilesOwnerClient(self.origin,self.owner.token,self.owner.catalog_id,timeout=30) - owner.bootstrap();owner_files=ProjectFilesClient(owner) - opened=owner_files.new(root='fixture',directory='adapters',name='M2 actual adapters 山',**self.envelope()) - with self.owner.bound(self.workspace): - credential=self.workspace.access.issue({'label':'M2 transport editor','scopes':['inspect','edit']}) - client=agent_api.AgentClient(self.origin,credential['token'],self.owner.catalog_id,timeout=30);client.bootstrap() - files=ProjectFilesClient(client) - imported=files.data_import_text(**self.arguments('data_import_text',text='M2 SDK authored café 山',name='Adapter source',groups=['m2-adapter'],rights='Owned fixture')) - record=imported['value'] - denied=self.arguments('data_annotate',record_id=record['id'],revision=record['revision'],source_revision=record['source_revision'], - task='text_corpus',annotation={'note':NOTE},groups=record['groups'],review='human_reviewed') - before=m1.canonical_bytes(self.external/'adapters') - self.assertEqual(client.call('project_files.data_annotate',denied)['status'],403) - self.assertEqual(client.call('project_files.study_create',self.arguments('study_create',name='Denied owner study', - limits={'attempt_slots':1,'admitted_wall_seconds':1,'retained_bytes':1,'peak_staging_bytes':1}, - policy={'format':'selection_policy_v1','metric_definition_sha256':'b'*64,'checkpoint_rule':'explicit','replicate_reduce':'individual', - 'required_capabilities':[],'numerical_acceptance':'diagnostic','tie_break':'trial_id'}))['status'],403) - self.assertEqual(m1.canonical_bytes(self.external/'adapters'),before) - config=self.config('actual-agent',credential['token']);args=self.path/'cli-arguments.json' - arguments=dict(denied,review='draft');args.write_text(json.dumps(arguments,ensure_ascii=False)) - environment={key:value for key,value in os.environ.items() if not key.startswith(('TULDOK_','PG'))} - result=subprocess.run([sys.executable,str(ROOT/'project_cli.py'),'--config',str(config),'file-data-annotate','--arguments',str(args)], - cwd=ROOT,env=environment,capture_output=True,text=True,timeout=45) - self.assertEqual(result.returncode,0,result.stderr);self.assertNotIn(credential['token'],result.stdout+result.stderr) - self.assertEqual(json.loads(result.stdout)['value']['annotation'],{'note':NOTE}) - async def exercise(): - parameters=StdioServerParameters(command=sys.executable,args=[str(ROOT/'mcp_stdio.py'),'--config',str(config)],cwd=str(ROOT),env=environment) - with (self.path/'m2-mcp.stderr').open('w+') as errors: - async with stdio_client(parameters,errlog=errors) as (reader,writer): - async with ClientSession(reader,writer,read_timeout_seconds=timedelta(seconds=20)) as session: - await session.initialize() - names={tool.name for tool in (await session.list_tools()).tools} - self.assertTrue({'project_files_data_get','project_files_data_rights','project_files_studies'}<=names) - request=self.arguments('data_get',record_id=record['id']) - observed=await session.call_tool('project_files_data_get',request) - self.assertFalse(observed.isError);self.assertEqual(observed.structuredContent['status'],200) - current=observed.structuredContent['result']['value'] - rights=self.arguments('data_rights',record_id=record['id'],revision=current['revision'],source_revision=current['source_revision'],note=RIGHTS) - saved=await session.call_tool('project_files_data_rights',rights) - self.assertFalse(saved.isError);self.assertEqual(saved.structuredContent['result']['value']['record']['provenance']['rights_note_correction']['note'],RIGHTS) - anyio.run(exercise) - # Discard the actual successful response body, then reconcile with the - # exact same request key; no mutation retry is hidden by an adapter. - arguments=self.arguments('data_import_text',text='Lost response exact source 山',name='Lost reply',groups=['m2-lost'],rights='Owned fixture') - method,target,body=agent_api.project_request('project_files.data_import_text',arguments) - connection=http.client.HTTPConnection('127.0.0.1',self.hosts[-1][1].server_port,timeout=30) - connection.request(method,target,json.dumps(body).encode(),{'Authorization':'Bearer '+self.owner.token, - 'Content-Type':'application/json','Tuldok-Operation-Contract':agent_api.selected_header('project_files.data_import_text')}) - response=connection.getresponse();self.assertEqual(response.status,200);connection.close() - committed=m1.canonical_bytes(self.external/'adapters') - status,replayed=self.transport('data_import_text',arguments);self.assertEqual(status,200,replayed) - self.assertEqual(m1.canonical_bytes(self.external/'adapters'),committed) - old=self.state();self.action('close');self.action('open',root='fixture',directory='adapters') - status,error=self.transport('data_get',{'binding':old['binding'],'checkpoint':old['project']['checkpoint'],'record_id':record['id']}) - self.assertEqual(status,409,error);self.assertEqual(m1.canonical_bytes(self.external/'adapters'),committed) - - - def test_retained_measurement_import_query_permissions_and_independent_cold_copy(self): - from retained_measurements import MeasurementTable,encode - from test_retained_measurements import fixture - self.create() - raw=encode(fixture());digest=hashlib.sha256(raw).hexdigest() - (self.external/'measurements.json').write_bytes(raw) - manifest=dict(schema_version=1,id=uuid.uuid4().hex,name='Exact native scalar source', - data=[dict(id='measurements',label='Retained scalars',path='measurements.json',sha256=digest)], - recipes=[],evidence=[],requirements=[]) - (self.external/'measurement-source.json').write_text(json.dumps(manifest)) - registered=self.call('source_register',root='fixture',manifest_path='measurement-source.json') - snapshot={k:registered[k] for k in ('origin_catalog_id','project_id','manifest_sha256')} - import_args=self.arguments('measurement_import',snapshot=snapshot,reference_id='measurements',expected_sha256=digest) - status,admitted=self.transport('measurement_import',import_args) - self.assertEqual(status,200,admitted) - origin=admitted['project_id'];selection=dict(origin_catalog_id=origin,packet_sha256=digest) - # Edits stay in the database working copy until an explicit Save. - self.action('save') - canonical=m1.canonical_bytes(self.external/'alpha') - self.assertEqual(self.transport('measurement_import',import_args)[1],admitted) - self.assertEqual(m1.canonical_bytes(self.external/'alpha'),canonical) - metadata=self.call('measurement_metadata',**selection) - self.assertEqual(metadata['value'],MeasurementTable(raw).metadata()) - self.assertEqual(self.call('measurement_sources')['items'][0]['id'],digest) - self.assertEqual(self.call('measurement_subjects',**selection,offset=1,limit=1)['value']['items'][0]['id'],'b') - query_args=self.arguments('measurement_query',**selection,metric_id='error',filters={'cpm':16}) - expected=self.call('measurement_query',**selection,metric_id='error',filters={'cpm':16}) - self.assertEqual(expected['value'],MeasurementTable(raw).query('error',filters={'cpm':16})) - row=self.call('measurement_inspect',**selection,observation_id='a-case1-error') - self.assertEqual(row['value']['scalar_evidence']['value'],1e-17) - timing=self.call('measurement_query',**selection,metric_id='latency')['value'] - self.assertTrue(all(s['maximum'] is None for s in timing['summary'])) - status,error=self.transport('measurement_query',dict(query_args,checkpoint='0'*64)) - self.assertEqual(status,409,error) - status,error=self.transport('measurement_query',dict(query_args,filters={'expression':'never execute'})) - self.assertEqual(status,400,error) - with self.owner.bound(self.workspace): - inspector=self.workspace.access.issue(dict(label='Scalar HTTP inspector',scopes=['inspect'])) - status,value=self.transport('measurement_query',query_args,token=inspector['token']) - self.assertEqual(status,200,value) - denied=self.arguments('measurement_import',snapshot=snapshot,reference_id='measurements',expected_sha256=digest) - self.assertEqual(self.transport('measurement_import',denied,token=inspector['token'])[0],403) - with self.owner.bound(self.workspace): - self.workspace.access.revoke(inspector['identity']['credential_id']) - self.assertEqual(self.transport('measurement_query',query_args,token=inspector['token'])[0],401) - self.assertEqual(m1.canonical_bytes(self.external/'alpha'),canonical) - self.action('save');self.action('close') - coldroot=self.path/'scalar-cold';coldroot.mkdir() - shutil.copytree(self.external/'alpha',coldroot/'copied') - self.assertEqual(m1.canonical_bytes(coldroot/'copied'),canonical) - for name in canonical: - self.assertNotEqual((self.external/'alpha'/name).stat().st_ino,(coldroot/'copied'/name).stat().st_ino) - self.select_host(self.path/'scalar-cold-control',{'fixture':coldroot}) - self.action('open',root='fixture',directory='copied') - self.assertEqual(self.workspace._projection.db.execute('SELECT count(*) FROM workspace_projects').fetchone()[0],0) - self.assertEqual(self.call('measurement_query',**selection,metric_id='error',filters={'cpm':16}),expected) - self.assertEqual(self.call('measurement_inspect',**selection,observation_id='a-case1-error'),row) - self.assertEqual(self.transport('measurement_query',query_args)[0],409) - self.action('save');self.action('close') - self.assertEqual(m1.canonical_bytes(coldroot/'copied'),canonical) - - -if __name__=='__main__':unittest.main() diff --git a/tests/test_project_files_m4_clients.py b/tests/test_project_files_m4_clients.py deleted file mode 100644 index 90af3962..00000000 --- a/tests/test_project_files_m4_clients.py +++ /dev/null @@ -1,255 +0,0 @@ -"""M4 fixed projections and client fault boundaries. - -Controlled replies establish transport refusal and exact byte custody, not disk -publication or execution. The loopback case exercises the real HTTP JSON reader. -""" -import copy -import hashlib -from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer -import json -from pathlib import Path -import re -import threading -from types import SimpleNamespace -import unittest -from unittest.mock import Mock - -import agent_api as api -import project_cli -import project_dispatch -from tuldok_client import ProjectFilesClient - -CATALOG, BINDING, PROJECT, ACTOR, FORK = (ch*32 for ch in 'abcdf') -CP, NEXT = 'e'*64, 'f'*64 -KEY = 'm4-reviewed-request-0001' -STAMP = '2026-10-22T12:00:00+00:00' -ROOT = Path(__file__).resolve().parents[1] -READ = dict(binding=BINDING, checkpoint=CP) -WRITE = dict(binding=BINDING, expected_checkpoint=CP, request_key=KEY) -ACTIONS = ['new','open','save','close','query','get','import_text','annotate'] - - -def identity(kind='script', path='scripts/inert.py', project=PROJECT): - return hashlib.sha256((project+'\0'+kind+'\0'+path).encode()).hexdigest() - - -def version(text, revision=1): - raw = text.encode('utf-8') - return dict(revision=revision, sha256=hashlib.sha256(raw).hexdigest(), bytes=len(raw), - text=text, adopted_at=STAMP, actor_id=ACTOR) - - -def selected(text='print("inert")\n', revision=1): - return dict(id=identity(), project_id=PROJECT, kind='script', path='scripts/inert.py', - version=version(text, revision)) - - -def bound(value, checkpoint=CP): - return dict(binding=BINDING, project_id=PROJECT, checkpoint=checkpoint, value=value) - - -def ready(reply, *, owner=False): - client = (api.ProjectFilesOwnerClient if owner else api.AgentClient)( - 'http://127.0.0.1:12345', 'fixture-only-m4-transport-token', CATALOG) - client._ready = True - client._selected = {name: 1 for name in api.PROJECT_FILES_M4} - client._request = Mock(return_value=copy.deepcopy(reply)) - return client - - -class M4Clients(unittest.TestCase): - def test_batch_reply_must_match_every_reviewed_file_and_changed_count(self): - text='Exact note\n';raw=text.encode();path='notes/first.md' - item=dict(id=identity('note',path),project_id=PROJECT,kind='note',path=path, - revision=1,sha256=hashlib.sha256(raw).hexdigest(),bytes=len(raw),adopted_at=STAMP,changed=True) - arguments=dict(WRITE,items=[dict(kind='note',path=path,expected_revision=0,expected_sha256=item['sha256'])]) - reply=dict(status=200,result=bound(dict(items=[item],changed_count=1),NEXT)) - self.assertEqual(ProjectFilesClient(ready(reply)).files_adopt(**arguments),reply['result']) - for field,value in [('project_id','f'*32),('sha256','a'*64),('path','notes/other.md'),('revision',2)]: - bad=copy.deepcopy(reply);bad['result']['value']['items'][0][field]=value - with self.subTest(field=field),self.assertRaises(api.AgentAPIError): - ProjectFilesClient(ready(bad)).files_adopt(**arguments) - bad=copy.deepcopy(reply);bad['result']['value']['changed_count']=0 - with self.assertRaises(api.AgentAPIError):ProjectFilesClient(ready(bad)).files_adopt(**arguments) - - def test_capability_profiles_fit_unchanged_budget_and_negotiate_only_intersections(self): - native = api.capabilities(CATALOG) - project = api.capabilities(CATALOG, profile='project') - self.assertLessEqual(len(api.encoded(native)), 1048576) - self.assertLessEqual(len(api.encoded(project)), 1048576) - self.assertTrue(all(not op['id'].startswith('project_files.') for op in native['operations'])) - self.assertTrue(all(op['id'].startswith('project_files.') or op['id'] in api.PROJECT_TRANSFER_OPERATIONS or op['id'] in ('context.get','identity.get') for op in project['operations'])) - self.assertTrue(api.PROJECT_FILES_M4 <= set(api.negotiate(project, CATALOG))) - self.assertFalse(api.PROJECT_FILES_M4 & set(api.negotiate(native, CATALOG))) - with self.assertRaises(api.AgentAPIError): api.capabilities(CATALOG, profile='arbitrary') - self.assertEqual(api.REGISTRY_DIGEST, api._LEGACY_DIGEST) - - def test_complete_m4_operations_have_fixed_consumers_and_closed_inputs(self): - self.assertEqual(api.PROJECT_FILES_M4,{'project_files.'+name for name in ( - 'compose','save_as','files_inspect','file_get','file_history','file_adopt','files_adopt', - 'file_adopt_deletion','material_intents','material_intent','material_intent_capabilities','fork_info')}) - self.assertEqual(project_dispatch.SUPPORTED_OPERATIONS & api.PROJECT_FILES_M4, - api.PROJECT_FILES_M4 - {'project_files.save_as','project_files.compose'}) - client = ProjectFilesClient(Mock()) - parser = project_cli.parser() - for operation in api.PROJECT_FILES_M4: - action = operation.split('.')[1] - self.assertTrue(callable(getattr(client, action))) - if action == 'save_as': - args = ['--binding',BINDING,'--expected-checkpoint',CP,'--request-key',KEY, - '--root','fixture','--directory','independent','--name','Independent'] - else: args = ['--arguments','/not-read'] - self.assertEqual(parser.parse_args(['--config','/not-read','file-'+action.replace('_','-'),*args]).command, - 'file-'+action.replace('_','-')) - with self.assertRaises(api.AgentAPIError): - api.validate_arguments('project_files.file_adopt', dict(WRITE, kind='script',path='scripts/inert.py', - expected_revision=0,expected_sha256=CP,execute=True)) - self.assertEqual(api.contract('project_files.save_as')['authority'],'owner') - self.assertEqual(api.contract('project_files.file_adopt')['authority'],'agent') - source=(ROOT/'static/project-files.js').read_text() - pins=json.loads(re.search(r'PROJECT_FILES_CONTRACTS_START \*/\s*(.*?)\s*/\* PROJECT_FILES_CONTRACTS_END',source,re.S)[1]) - for name in api.PROJECT_FILES_M4: self.assertEqual(pins[name],api.contract(name)['sha256']) - - def test_selected_file_checks_exact_utf8_revision_identity_and_empty_text(self): - arguments=dict(READ,file_id=identity(),revision=2) - for text in ('', '\0 exact\r\nΩ 🌸', '🌸'*262144): - value=bound(selected(text,2));raw=ready(dict(status=200,result=value)) - self.assertEqual(ProjectFilesClient(raw).file_get(**arguments),value) - value=bound(selected('exact',2));raw=ready(dict(status=200,result=value)) - for change in ({'text':'different'},{'bytes':4},{'sha256':CP},{'revision':3}): - corrupt=copy.deepcopy(value);corrupt['value']['version'].update(change) - raw._request.return_value=dict(status=200,result=corrupt) - with self.assertRaises(api.AgentAPIError): ProjectFilesClient(raw).file_get(**arguments) - for change in ({'id':CP},{'project_id':ACTOR},{'path':'scripts/another.py'}): - corrupt=copy.deepcopy(value);corrupt['value'].update(change) - raw._request.return_value=dict(status=200,result=corrupt) - with self.assertRaises(api.AgentAPIError): ProjectFilesClient(raw).file_get(**arguments) - - def test_nul_exception_is_only_exact_successful_file_text_leaf_over_real_http(self): - body=bound(selected('before\0after')) - class Handler(BaseHTTPRequestHandler): - def do_GET(self): - raw=api.encoded(body);self.send_response(200);self.send_header('Content-Type','application/json') - self.send_header('Content-Length',str(len(raw)));self.end_headers();self.wfile.write(raw) - def log_message(self,*_): pass - server=ThreadingHTTPServer(('127.0.0.1',0),Handler) - thread=threading.Thread(target=server.serve_forever,daemon=True);thread.start() - self.addCleanup(server.server_close);self.addCleanup(thread.join,5);self.addCleanup(server.shutdown) - client=api.AgentClient(f'http://127.0.0.1:{server.server_port}','fixture-only-m4-token',CATALOG) - client._ready=True;client._selected={'project_files.file_get':1} - self.assertEqual(ProjectFilesClient(client).file_get(**READ,file_id=identity()),body) - with self.assertRaises(api.AgentAPIError): api.decode(api.encoded(body)) - for field in ('path','kind'): - invalid=copy.deepcopy(body);invalid['value'][field]+='\0' - with self.assertRaises(api.AgentAPIError): - api.validate_output('project_files.file_get',dict(status=200,result=invalid)) - with self.assertRaises(api.AgentAPIError): - api.validate_output('project_files.file_get',dict(status=503,result={'error':'bad\0','code':'unavailable'})) - with self.assertRaises(api.AgentAPIError): - api.validate_arguments('project_files.file_adopt',dict(WRITE,kind='script',path='scripts/a\0',expected_revision=0,expected_sha256=CP)) - invalid=copy.deepcopy(body) - invalid['value']['version']['text']='bad\ud800' - with self.assertRaises(api.AgentAPIError): - api.validate_output('project_files.file_get',dict(status=200,result=invalid)) - - def test_adoption_history_and_nested_mapping_refuse_wrong_selection(self): - meta=version('exact');meta.pop('text') - adopted=dict(id=identity(),project_id=PROJECT,kind='script',path='scripts/inert.py', - **{k:v for k,v in meta.items() if k!='actor_id'},changed=True) - arguments=dict(WRITE,kind='script',path='scripts/inert.py',expected_revision=0,expected_sha256=meta['sha256']) - raw=ready(dict(status=200,result=bound(adopted,NEXT))) - self.assertEqual(ProjectFilesClient(raw).file_adopt(**arguments)['value'],adopted) - for change in ({'sha256':CP},{'revision':2},{'changed':False}): - raw._request.return_value=dict(status=200,result=bound(dict(adopted,**change),NEXT)) - with self.assertRaises(api.AgentAPIError):ProjectFilesClient(raw).file_adopt(**arguments) - history=dict(id=identity(),items=[meta],offset=0,limit=40,total=1) - raw._request.return_value=dict(status=200,result=bound(history)) - self.assertEqual(ProjectFilesClient(raw).file_history(**READ,file_id=identity())['value'],history) - raw._request.return_value=dict(status=200,result=bound(dict(history,items=[dict(meta,text='forbidden')])) ) - with self.assertRaises(api.AgentAPIError):ProjectFilesClient(raw).file_history(**READ,file_id=identity()) - mapping=dict(source=None,project_id=PROJECT,mapping=dict(items=[],offset=0,limit=40,total=0), - archived_count=0,copied_count=0,missing_regenerable_count=0) - raw._request.return_value=dict(status=200,result=bound(mapping)) - ProjectFilesClient(raw).fork_info(**READ) - for change in ({'offset':1},{'limit':1},{'total':1}): - corrupt=copy.deepcopy(mapping);corrupt['mapping'].update(change) - raw._request.return_value=dict(status=200,result=bound(corrupt)) - with self.assertRaises(api.AgentAPIError):ProjectFilesClient(raw).fork_info(**READ) - - def test_save_as_correlates_new_state_and_never_retries_failed_ack(self): - arguments=dict(WRITE,root='fixture',directory='independent',name='Independent Ω') - state=dict(format='project_files_state_v1',binding=ACTOR,state='open',roots=['fixture'], - project=dict(project_id=FORK,name=arguments['name'],checkpoint=NEXT),available_actions=ACTIONS) - fork=dict(source_project_id=PROJECT,source_checkpoint=CP,project_id=FORK,checkpoint=NEXT, - root='fixture',directory='independent',request_key=KEY,reconciled=False, - mapping_count=2,copied_count=3,missing_regenerable_count=1) - result=dict(state=state,fork=fork);raw=ready(dict(status=200,result=result),owner=True) - self.assertEqual(ProjectFilesClient(raw).save_as(**arguments),result) - for field,bad in (('directory','elsewhere'),('source_checkpoint',NEXT),('project_id',PROJECT),('request_key','different-request')): - corrupt=copy.deepcopy(result);corrupt['fork'][field]=bad - raw._request.return_value=dict(status=200,result=corrupt) - with self.assertRaises(api.AgentAPIError):ProjectFilesClient(raw).save_as(**arguments) - corrupt=copy.deepcopy(result);corrupt['state']['binding']=BINDING - raw._request.return_value=dict(status=200,result=corrupt) - with self.assertRaises(api.AgentAPIError):ProjectFilesClient(raw).save_as(**arguments) - raw._request.return_value=dict(status=503,result={'error':'Inspect current selection.','code':'outcome_unknown'}) - before=raw._request.call_count - with self.assertRaises(api.AgentAPIError):ProjectFilesClient(raw).save_as(**arguments) - self.assertEqual(raw._request.call_count-before,1) - - def test_file_observations_and_original_intents_refuse_cross_project_metadata(self): - meta=version('exact');observation=dict(id=identity(),kind='script',path='scripts/inert.py',revision=1, - expected_sha256=meta['sha256'],expected_bytes=meta['bytes'],observed_sha256=meta['sha256'], - observed_bytes=meta['bytes'],state='unchanged',reason=None) - page=dict(items=[observation],offset=0,limit=40,total=1) - raw=ready(dict(status=200,result=bound(page))) - ProjectFilesClient(raw).files_inspect(**READ) - for change in ({'id':CP},{'observed_sha256':CP},{'observed_bytes':0}): - raw._request.return_value=dict(status=200,result=bound(dict(page,items=[dict(observation,**change)]))) - with self.assertRaises(api.AgentAPIError):ProjectFilesClient(raw).files_inspect(**READ) - origin=dict(project_id=FORK,checkpoint=NEXT,family='model_definition',id=ACTOR,revision=2,created_at=STAMP) - current=dict(format='project_material_fork_intent_v1',catalog_id=PROJECT,id=ACTOR,revision=1, - name='Retained original',definition_family='model_definition', - definition={'source_selector':{'catalog_id':FORK},'specification':{'width':17}}, - required_reselection=['source_selector']) - detail=dict(family='model_definition',id=PROJECT+'.'+ACTOR,current=current,fork_origin=origin) - raw._request.return_value=dict(status=200,result=bound(detail)) - self.assertEqual(ProjectFilesClient(raw).material_intent(**READ,family='model_definition',definition_id=ACTOR)['value'],detail) - for field in ('catalog_id','id','definition_family'): - corrupt=copy.deepcopy(detail);corrupt['current'][field]='pipeline_graph' if field=='definition_family' else FORK - raw._request.return_value=dict(status=200,result=bound(corrupt)) - with self.assertRaises(api.AgentAPIError): - ProjectFilesClient(raw).material_intent(**READ,family='model_definition',definition_id=ACTOR) - summary=dict(family='model_definition',id=PROJECT+'.'+ACTOR,catalog_id=PROJECT,definition_id=ACTOR, - name=current['name'],revision=1,required_reselection=current['required_reselection'],fork_origin=origin) - raw._request.return_value=dict(status=200,result=bound(dict(items=[summary],offset=0,limit=40,total=1))) - ProjectFilesClient(raw).material_intents(**READ) - raw._request.return_value=dict(status=200,result=bound(dict(items=[dict(summary,catalog_id=FORK)],offset=0,limit=40,total=1))) - with self.assertRaises(api.AgentAPIError):ProjectFilesClient(raw).material_intents(**READ) - - def test_dispatch_projects_metadata_pages_without_captured_text_or_definition_bulk(self): - import threading - access=SimpleNamespace(lock=threading.RLock(),require=Mock()) - session=SimpleNamespace(access=access,lock=threading.RLock(),db=SimpleNamespace(lock=threading.RLock()), - check=Mock(side_effect=AssertionError('Unused full dispatcher snapshot')),check_current=Mock()) - files=SimpleNamespace(history=Mock(return_value=[version('large text '+str(i),i+1) for i in range(42)])) - projection=SimpleNamespace(session=session,files=files) - page=project_dispatch.dispatch(projection,'project_files.file_history',dict(READ,file_id=identity(),offset=40,limit=2)) - self.assertEqual((page['total'],[item['revision'] for item in page['items']]),(42,[41,42])) - self.assertTrue(all('text' not in item for item in page['items'])) - session.check_current.assert_called_once_with() - api.validate_output('project_files.file_history',dict(status=200,result=bound(page))) - - def test_dispatch_fork_info_retains_the_complete_snapshot_contract(self): - import threading - access=SimpleNamespace(lock=threading.RLock(),require=Mock()) - session=SimpleNamespace(access=access,lock=threading.RLock(),db=SimpleNamespace(lock=threading.RLock()), - check=Mock(return_value={'project_id':PROJECT,'records':[]}), - check_current=Mock(side_effect=AssertionError('Fork must read its records'))) - value=project_dispatch.dispatch(SimpleNamespace(session=session),'project_files.fork_info',dict(READ,offset=0,limit=40)) - session.check.assert_called_once_with() - self.assertEqual(value,dict(source=None,project_id=PROJECT, - mapping=dict(items=[],offset=0,limit=40,total=0),archived_count=0,copied_count=0,missing_regenerable_count=0)) - - -if __name__=='__main__':unittest.main() diff --git a/tests/test_project_files_m4_clients_http.py b/tests/test_project_files_m4_clients_http.py deleted file mode 100644 index 89e8e26c..00000000 --- a/tests/test_project_files_m4_clients_http.py +++ /dev/null @@ -1,202 +0,0 @@ -"""Actual M4 SDK, CLI and MCP over an authenticated disposable HTTP server. - -Requires lead-enabled M4 and an explicit frozen product manifest. No provider, -preflight, runtime capture, script execution or ambient user catalog is used. -""" -from datetime import timedelta -import hashlib -import importlib.util -import json -import os -from pathlib import Path -import subprocess -import sys -import time -import unittest -import uuid - -import agent_api as api -import project_workspace -from tuldok_client import ProjectFilesClient -import test_project_files_http as m1 - -ROOT=Path(__file__).resolve().parents[1] - - -def frozen_subject(): - name=os.environ.get('TULDOK_M4_FREEZE_MANIFEST') - if not name:raise AssertionError('Lead must provide TULDOK_M4_FREEZE_MANIFEST before actual acceptance') - value=json.loads(Path(name).read_text());files=value['files'] - current={file:hashlib.sha256((ROOT/file).read_bytes()).hexdigest() for file in files} - if current!=files:raise AssertionError('Frozen product changed before actual acceptance') - return dict(manifest_sha256=hashlib.sha256(Path(name).read_bytes()).hexdigest(),files=current) - - -@unittest.skipUnless(os.environ.get('TULDOK_DATABASE_URL'),'Requires disposable PostgreSQL') -class ProjectFilesM4ClientsHTTP(unittest.TestCase): - cleanup_owned=m1.ProjectFilesHTTP.cleanup_owned - select_host=m1.ProjectFilesHTTP.select_host - request=m1.ProjectFilesHTTP.request - state=m1.ProjectFilesHTTP.state - envelope=m1.ProjectFilesHTTP.envelope - - def setUp(self): - self.assertTrue(project_workspace.M4_ENABLED,'Lead must enable M4 for actual public acceptance') - self.subject=frozen_subject();self.performed=[];self.started=time.monotonic() - m1.ProjectFilesHTTP.setUp(self) - self.addCleanup(self.receipt) - - def receipt(self): - current={file:hashlib.sha256((ROOT/file).read_bytes()).hexdigest() for file in self.subject['files']} - report=Path(os.environ.get('TULDOK_QA_OUTPUT_ROOT','/workspace/scratch/tuldok-save-load-qa/artifacts'))/'m4-clients' - report.mkdir(parents=True,exist_ok=True) - (report/(self._testMethodName+'-'+uuid.uuid4().hex+'.json')).write_text(json.dumps(dict( - test=self.id(),seconds=round(time.monotonic()-self.started,3),performed=self.performed, - source=self.subject,end_sha256=current,source_stable=current==self.subject['files'], - test_sha256=hashlib.sha256(Path(__file__).read_bytes()).hexdigest(), - fixture='Disposable local PG; real HTTP/SDK/CLI/MCP transports; inert exact UTF8 files'),indent=2)+'\n') - self.assertEqual(current,self.subject['files'],'Product changed during actual acceptance') - - def config(self,name,token): - token_file=self.path/(name+'.token');config_file=self.path/(name+'.config.json') - token_file.write_text(token+'\n');token_file.chmod(0o600) - config_file.write_text(json.dumps(dict(endpoint=self.origin,catalog_id=self.owner.catalog_id, - token_file=str(token_file),timeout=15)));config_file.chmod(0o600) - return config_file - - @unittest.skipUnless(importlib.util.find_spec('mcp') and importlib.util.find_spec('anyio'), 'Requires optional locked MCP dependencies') - def test_exact_file_revisions_save_as_and_current_role_through_sdk_cli_mcp(self): - import anyio - from mcp import ClientSession,StdioServerParameters - from mcp.client.stdio import stdio_client - owner=ProjectFilesClient(api.ProjectFilesOwnerClient(self.origin,self.owner.token,self.owner.catalog_id,timeout=15)) - initial=owner.status();opened=owner.new(root='fixture',directory='transport',name='Exact file project Ω',**self.envelope(initial)) - root=self.external/'transport';(root/'scripts').mkdir();(root/'notes').mkdir() - sentinel=self.path/'must-not-execute' - script=('from pathlib import Path\nPath('+repr(str(sentinel))+').write_text("executed")\n# inert NUL follows\n\0Ω 🌸\r\n').encode() - (root/'scripts/inert.py').write_bytes(script);(root/'notes/empty.md').write_bytes(b'') - with self.owner.bound(self.workspace): - credential=self.workspace.access.issue({'label':'M4 current editor','scopes':['inspect','edit']}) - agent=api.AgentClient(self.origin,credential['token'],self.owner.catalog_id,timeout=15) - self.assertEqual(agent.bootstrap()['identity']['kind'],'agent');files=ProjectFilesClient(agent) - script_result=files.file_adopt(**self.envelope(),kind='script',path='scripts/inert.py',expected_revision=0, - expected_sha256=hashlib.sha256(script).hexdigest())['value'] - empty_result=files.file_adopt(**self.envelope(),kind='note',path='notes/empty.md',expected_revision=0, - expected_sha256=hashlib.sha256(b'').hexdigest())['value'] - def read(): - state=self.state();return dict(binding=state['binding'],checkpoint=state['project']['checkpoint']) - self.assertEqual(files.file_get(**read(),file_id=script_result['id'])['value']['version']['text'].encode(),script) - self.assertEqual(files.file_get(**read(),file_id=empty_result['id'])['value']['version']['text'],'') - self.performed.append('Actual current-agent SDK adopts and reads exact NUL/Unicode and empty UTF8 files') - agent_config=self.config('agent',credential['token']);owner_config=self.config('owner',self.owner.token) - environment={key:value for key,value in os.environ.items() if not key.startswith(('TULDOK_','PG'))} - environment['PYTHONDONTWRITEBYTECODE']='1' - def cli(config,command,*,owner_mode=False,arguments=None,flags=()): - command=[sys.executable,str(ROOT/'project_cli.py'),'--config',str(config), - *(['--owner-project-files'] if owner_mode else []),command,*flags] - if arguments is not None: - path=self.path/('args-'+uuid.uuid4().hex+'.json');path.write_text(json.dumps(arguments));command+=['--arguments',str(path)] - result=subprocess.run(command,cwd=ROOT,env=environment,capture_output=True,text=True,timeout=30) - self.assertEqual(result.returncode,0,result.stderr) - self.assertNotIn(self.owner.token,result.stdout+result.stderr);self.assertNotIn(credential['token'],result.stdout+result.stderr) - return json.loads(result.stdout) - original=cli(agent_config,'file-file-get',arguments=dict(read(),file_id=script_result['id'],revision=1)) - self.assertEqual(original['value']['version']['text'].encode(),script) - changed=script+b'# second authored observation\n';(root/'scripts/inert.py').write_bytes(changed) - async def exercise(): - params=StdioServerParameters(command=sys.executable,args=[str(ROOT/'mcp_stdio.py'),'--config',str(agent_config)],cwd=str(ROOT),env=environment) - with (self.path/'mcp.stderr').open('w+') as errors: - async with stdio_client(params,errlog=errors) as (reader,writer): - started=time.monotonic() - async with ClientSession(reader,writer,read_timeout_seconds=timedelta(seconds=20)) as session: - await session.initialize();self.performed.append(dict(actual_mcp_initialize_seconds=round(time.monotonic()-started,3),deadline_seconds=20)) - tools={tool.name for tool in (await session.list_tools()).tools} - self.assertTrue({'project_files_file_get','project_files_file_adopt','project_files_file_history'}<=tools) - async def tool(action,args): - result=await session.call_tool('project_files_'+action,args) - self.assertFalse(result.isError,result) - envelope=result.structuredContent;self.assertEqual(envelope['status'],200,envelope) - self.assertEqual(json.loads(result.content[0].text),envelope) - return envelope['result'] - exact=await tool('file_get',dict(read(),file_id=script_result['id'],revision=1)) - self.assertEqual(exact['value']['version']['text'].encode(),script) - adopted=await tool('file_adopt',dict(self.envelope(),kind='script',path='scripts/inert.py',expected_revision=1, - expected_sha256=hashlib.sha256(changed).hexdigest())) - self.assertEqual(adopted['value']['revision'],2) - page=await tool('file_history',dict(read(),file_id=script_result['id'],offset=0,limit=1)) - self.assertEqual((page['value']['total'],page['value']['items'][0]['revision']),(2,1)) - self.assertNotIn('text',page['value']['items'][0]) - page=await tool('file_history',dict(read(),file_id=script_result['id'],offset=1,limit=1)) - self.assertEqual(page['value']['items'][0]['revision'],2) - errors.seek(0);self.assertNotIn(credential['token'],errors.read()) - anyio.run(exercise) - self.performed.append('Actual MCP reads original NUL bytes, adopts revision2, pages metadata-only history') - from test_project_material_fork import recipe - original_recipe=recipe(self.state()['project']['project_id']) - recipe_body={key:value for key,value in original_recipe.items() if key not in ('format','id','revision')} - retained_recipe=files.recipe_create(**self.envelope(),**recipe_body)['value'] - self.performed.append('Actual SDK authors an inert recipe draft with explicit historical reference fields; no material preparation') - source=self.state();args=self.envelope(source) - denial=agent.call('project_files.save_as',dict(args,root='fixture',directory='denied',name='Denied')) - self.assertEqual(denial['status'],403);self.assertFalse((self.external/'denied').exists()) - fork=cli(owner_config,'file-save-as',owner_mode=True,flags=[ - '--binding',args['binding'],'--expected-checkpoint',args['expected_checkpoint'],'--request-key',args['request_key'], - '--root','fixture','--directory','independent','--name','Independent exact transport Ω']) - self.assertNotEqual(fork['fork']['project_id'],source['project']['project_id']) - self.assertEqual(fork['state'],self.state()) - self.assertEqual((self.external/'independent/scripts/inert.py').read_bytes(),changed) - self.assertEqual((self.external/'independent/notes/empty.md').read_bytes(),b'') - old=agent.call('project_files.file_get',dict(binding=source['binding'],checkpoint=source['project']['checkpoint'],file_id=script_result['id'])) - self.assertEqual(old['status'],409) - observed=files.files_inspect(**read())['value']['items'];self.assertEqual(len(observed),2) - self.assertTrue(all(item['state']=='unchanged' for item in observed)) - current=next(item for item in observed if item['kind']=='script') - self.assertNotEqual(current['id'],script_result['id']) - self.assertEqual(files.file_get(**read(),file_id=current['id'],revision=1)['value']['version']['text'].encode(),script) - self.assertEqual(files.file_get(**read(),file_id=current['id'],revision=2)['value']['version']['text'].encode(),changed) - intents=files.material_intents(**read())['value']['items'] - self.assertEqual(len(intents),1) - intent=files.material_intent(**read(),family=intents[0]['family'],definition_id=intents[0]['definition_id'])['value'] - self.assertEqual(intent['current']['definition'],retained_recipe) - self.assertEqual(intent['current']['definition']['runtime']['catalog_id'],source['project']['project_id']) - self.assertNotEqual(intent['current']['catalog_id'],source['project']['project_id']) - capabilities=files.material_intent_capabilities(**read())['value']['items'] - self.assertTrue(any(item['id']==intent['id'] and 'runtime' in item['requires_reselection'] for item in capabilities)) - self.assertFalse(sentinel.exists()) - self.performed.append('Actual owner CLI Save As selects independent identities; old binding rejected; both exact histories retained; script never executed') - - def test_fork_text_v1_refuses_before_mutation_and_v2_retains_exact_origin(self): - files=ProjectFilesClient(api.ProjectFilesOwnerClient(self.origin,self.owner.token,self.owner.catalog_id,timeout=15)) - source=files.new(root='fixture',directory='text-source',name='Source for versioned text',**self.envelope(files.status())) - original=files.import_text({'name':'Original authored Ω','text':'Exact scientific decision 山', - 'groups':['fixture'],'parents':[],'rights':'Owned text fixture'},**self.envelope(source))['record'] - fork=files.save_as(root='fixture',directory='text-fork',name='Versioned fork Ω',**self.envelope()) - current=files.status();query=files.query(binding=current['binding'],checkpoint=current['project']['checkpoint']) - row=query['items'][0];self.assertNotEqual(row['id'],original['id']) - read=dict(binding=current['binding'],checkpoint=current['project']['checkpoint'],record_id=row['id']) - detail=files.get(row['id'],binding=current['binding'],checkpoint=current['project']['checkpoint']) - provenance=detail['record']['provenance'];self.assertEqual(provenance['method'],'project_fork') - self.assertEqual(provenance['origin']['project_id'],source['project']['project_id']) - self.assertEqual(provenance['origin']['id'],original['id']) - before=m1.canonical_bytes(self.external/'text-fork') - transport=files.client - route=api.operation('project_files.get',1)['path'].replace('{record_id}',row['id']) - from urllib.parse import urlencode - old=transport._request('GET',route+'?'+urlencode({k:v for k,v in read.items() if k!='record_id'}),selection=('project_files.get',1)) - self.assertEqual(old['status'],409,old);self.assertEqual(old['result']['code'],'unsupported') - annotation=dict(revision=detail['record']['revision'],source_revision=detail['record']['source_revision'], - task='text_corpus',annotation={'note':'New independent rationale Ω'},groups=detail['record']['groups'],review='draft') - body=dict(self.envelope(current),annotation=annotation) - old=transport._request('POST',route,body,selection=('project_files.annotate',1)) - self.assertEqual(old['status'],409,old);self.assertEqual(old['result']['code'],'unsupported') - self.assertEqual(m1.canonical_bytes(self.external/'text-fork'),before) - saved=files.annotate(row['id'],annotation,**self.envelope(current)) - self.assertEqual(saved['record']['provenance'],provenance) - self.assertEqual(saved['record']['annotation'],annotation['annotation']) - latest=files.get(row['id'],binding=saved['binding'],checkpoint=saved['checkpoint'],history_limit=4) - self.assertEqual([r['revision'] for r in latest['history']],[2,1]) - self.assertTrue(all(r['provenance']==provenance for r in latest['history'])) - self.performed.append('Actual v1 get/annotate reject fork provenance before any canonical write; negotiated v2 reads and annotates exact origin/history') - - -if __name__=='__main__':unittest.main() diff --git a/tests/test_project_files_m4_http.py b/tests/test_project_files_m4_http.py deleted file mode 100644 index bd7d48ca..00000000 --- a/tests/test_project_files_m4_http.py +++ /dev/null @@ -1,161 +0,0 @@ -"""Actual idle independent forks, Git checkout and relocation using disposable PG.""" -import copy -import hashlib -import os -import shutil -import subprocess -import unittest -from unittest.mock import patch -import uuid - -import project_workspace -from project_store import ProjectStoreError -from workbench import WorkbenchError -import test_project_files_http as m1 -import test_project_files_m2_http as m2 - - -@unittest.skipUnless(os.environ.get('TULDOK_DATABASE_URL'), 'Requires disposable PostgreSQL') -class ProjectFilesM4HTTP(unittest.TestCase): - cleanup_owned=m1.ProjectFilesHTTP.cleanup_owned - select_host=m1.ProjectFilesHTTP.select_host - request=m1.ProjectFilesHTTP.request - state=m1.ProjectFilesHTTP.state - envelope=m1.ProjectFilesHTTP.envelope - action=m1.ProjectFilesHTTP.action - create=m1.ProjectFilesHTTP.create - arguments=m2.ProjectFilesM2HTTP.arguments - transport=m2.ProjectFilesM2HTTP.transport - call=m2.ProjectFilesM2HTTP.call - - def setUp(self): - self.operations=[] - m1.ProjectFilesHTTP.setUp(self) - gate=patch.object(project_workspace,'M4_ENABLED',True) - gate.start();self.addCleanup(gate.stop) - - def fork(self,**fields): - arguments=self.arguments('save_as',root='fixture',directory='fork',name='Independent fork',**fields) - status,value=self.transport('save_as',arguments) - self.assertEqual(status,200,value) - return arguments,value - - def test_batch_adoption_uses_real_http_and_survives_independent_fork(self): - self.create();root=self.external/'alpha';(root/'notes').mkdir();items=[] - for name,raw in [('first.md',b'Exact first note\r\n'),('second.md','Exact Ω note\n'.encode())]: - (root/'notes'/name).write_bytes(raw) - items.append(dict(kind='note',path='notes/'+name,expected_revision=0,expected_sha256=hashlib.sha256(raw).hexdigest())) - result=self.call('files_adopt',items=items) - self.assertEqual(result['changed_count'],2);self.assertEqual(len(self.call('files_inspect')['items']),2) - with patch.object(self.workspace._store,'snapshot',side_effect=AssertionError('Unrelated full graph copy')): - self.assertEqual(len(self.call('files_inspect')['items']),2) - selected=self.call('file_get',file_id=result['items'][0]['id']) - self.assertEqual(selected['version']['text'].encode(),b'Exact first note\r\n') - history=self.call('file_history',file_id=result['items'][0]['id']) - self.assertEqual([v['revision'] for v in history['items']],[1]) - source=copy.deepcopy(self.workspace._projection.session.snapshot) - self.fork() - current=self.workspace._projection.session.snapshot;indexed={(r['family'],r['id']):r for r in current['records']} - for record in source['records']:self.assertEqual(indexed[(record['family'],record['id'])],record) - for item in items:self.assertEqual((self.external/'fork'/item['path']).read_bytes(),(root/item['path']).read_bytes()) - - def test_nonempty_independent_fork_exact_science_new_editable_ids_and_same_request_key(self): - self.create() - row=self.call('data_import_text',text='Unique observation café 山',name='Original', - groups=['fixture'],rights='Owned fixture',request_key='same-key') - root=self.external/'alpha' - (root/'scripts').mkdir();raw=b'#!/bin/sh\nexit 99\n' - (root/'scripts'/'inert.sh').write_bytes(raw) - file=self.call('file_adopt',kind='script',path='scripts/inert.sh',expected_revision=0, - expected_sha256=hashlib.sha256(raw).hexdigest()) - original=copy.deepcopy(self.workspace._projection.session.snapshot) - before=m1.canonical_bytes(root) - arguments,value=self.fork() - self.assertNotEqual(value['fork']['source_project_id'],value['fork']['project_id']) - self.assertEqual(value['state'],self.state()) - self.assertEqual(m1.canonical_bytes(root),before) - current=self.workspace._projection.session.snapshot - indexed={(r['family'],r['id']):r for r in current['records']} - for r in original['records']:self.assertEqual(indexed[(r['family'],r['id'])],r) - forged=copy.deepcopy(current) - inherited=next(r['document'] for r in forged['records'] if r['family']=='project_file' - and r['document']['project_id']==current['project_id']) - forged_version=inherited['history'][0];forged_text='Forged inherited script\n' - forged_version.update(text=forged_text,bytes=len(forged_text.encode()),sha256=hashlib.sha256(forged_text.encode()).hexdigest()) - inherited['current']=copy.deepcopy(inherited['history'][-1]) - from project_files import decode_records - with self.assertRaisesRegex(WorkbenchError,'Working-file fork requires its exact archived history'): - decode_records(forged['records']) - with self.assertRaisesRegex(WorkbenchError,'Working-file fork requires its exact archived history'): - self.workspace._projection.session.adopt(forged) - self.assertEqual(self.workspace._projection.session.snapshot,current) - active=self.call('data_query')['items'] - self.assertEqual(len(active),1);self.assertNotEqual(active[0]['id'],row['id']) - self.assertEqual(self.call('data_get',record_id=active[0]['id'])['text'],row['text']) - status,archived=self.transport('data_availability',self.arguments('data_availability',record_id=row['id'])) - self.assertEqual(status,404,archived) - self.assertEqual((self.external/'fork/scripts/inert.sh').read_bytes(),raw) - files=self.call('files_inspect')['items'] - self.assertEqual(len(files),1);self.assertNotEqual(files[0]['id'],file['id']) - status,replay=self.transport('save_as',arguments) - self.assertEqual((status,replay),(200,value)) - # Source receipts remain exact historical facts; their request keys do - # not suppress a new independent project's current edit. - changed=self.call('data_import_text',text='Independent new data',name='New',groups=['fixture'], - rights='Owned fork fixture',request_key='same-key') - self.assertNotEqual(changed['id'],row['id']) - self.assertEqual(m1.canonical_bytes(root),before) - self.action('close');self.action('open',root='fixture',directory='fork') - self.assertEqual(len(self.call('data_query')['items']),2) - self.assertIsNone(self.workspace._projection.execution._runs) - - def test_published_unselected_fork_exact_retry_and_changed_file_guard(self): - self.create() - self.call('data_import_text',text='Retained unique data',name='Original',groups=['fixture'],rights='Owned') - source=self.state();before=m1.canonical_bytes(self.external/'alpha') - arguments=self.arguments('save_as',root='fixture',directory='fork',name='Retained destination') - with patch.object(self.workspace,'_projection_for',side_effect=RuntimeError('injected projection failure')): - status,failure=self.transport('save_as',arguments) - self.assertEqual(status,503,failure) - self.assertTrue(failure['receipt']['committed']);self.assertFalse(failure['receipt']['selected']) - self.assertEqual(self.state(),source) - self.assertEqual(m1.canonical_bytes(self.external/'alpha'),before) - status,value=self.transport('save_as',arguments) - self.assertEqual(status,200,value);self.assertTrue(value['fork']['reconciled']) - root=self.external/'fork';(root/'notes').mkdir();(root/'notes/reason.md').write_text('Original') - self.call('file_adopt',kind='note',path='notes/reason.md',expected_revision=0, - expected_sha256=hashlib.sha256(b'Original').hexdigest()) - (root/'notes/reason.md').write_text('Unadopted scientific decision') - status,failure=self.transport('save_as',self.arguments('save_as',root='fixture',directory='blocked',name='Blocked')) - self.assertEqual(status,409,failure);self.assertEqual(failure['code'],'working_files_changed') - self.assertFalse((self.external/'blocked').exists()) - - def test_git_checkout_stale_projection_and_moved_folder_inert_reconstruction(self): - self.create();root=self.external/'alpha' - first=self.call('data_import_text',text='Git observation one',name='One',groups=['fixture'],rights='Owned') - self.action('save') - def git(*args):return subprocess.check_output(['git','-C',str(root),*args],stderr=subprocess.STDOUT) - git('init','-q');git('config','user.name','Disposable Fixture');git('config','user.email','fixture@example.invalid') - git('add','.');git('commit','-qm','First authored checkpoint');old=git('rev-parse','HEAD').decode().strip() - self.call('data_import_text',text='Git observation two',name='Two',groups=['fixture'],rights='Owned') - self.action('save') - git('add','.');git('commit','-qm','Second authored checkpoint') - git('checkout','-q',old) - # The database working copy stays the session's authority; Save refuses - # to overwrite the externally checked-out folder. - self.assertEqual(self.state()['state'],'open') - status,failure=self.transport('save',self.arguments('save')) - self.assertEqual(status,409,failure);self.assertEqual(failure['code'],'conflict') - self.assertEqual(git('rev-parse','HEAD').decode().strip(),old) - self.assertEqual(git('status','--porcelain').decode(),'') - # Reopening a clean working copy imports the checked-out revision. - self.action('close') - self.action('open',root='fixture',directory='alpha') - self.assertEqual([r['id'] for r in self.call('data_query')['items']],[first['id']]) - self.action('close');shutil.move(root,self.external/'moved') - with patch('runs.Runs',side_effect=AssertionError('Open constructed Runs')),patch('subprocess.Popen',side_effect=AssertionError('Open executed')): - self.action('open',root='fixture',directory='moved') - self.assertEqual(self.call('data_get',record_id=first['id'])['text'],'Git observation one') - - -if __name__=='__main__':unittest.main() diff --git a/tests/test_project_files_material_http.py b/tests/test_project_files_material_http.py deleted file mode 100644 index 84bbc78c..00000000 --- a/tests/test_project_files_material_http.py +++ /dev/null @@ -1,197 +0,0 @@ -"""Fresh neutral material composition through real project HTTP and PostgreSQL. - -The source and exact-byte input are the existing ExternalCase fixture. This test -qualifies nonexecuting capture/metadata, never its execution or scientific value. -Run only after the lead freezes the public contracts and recipe host sources. -""" -import hashlib -import json -import os -from pathlib import Path -import shutil -import time -import unittest -from unittest.mock import patch -import uuid - -import psycopg - -from metadata import CATALOG_LOCAL_TIMEOUT -from pipeline import digest -import test_project_files_http as m1 -import test_project_files_m2_http as m2 - -ROOT=Path(__file__).resolve().parents[1] -PRODUCT_FILES=tuple(sorted(set(m2.SOURCE_FILES)|{ - 'pipeline.py','model_definitions.py','projects.py','recipe_contract.py','recipe_process.py', - 'metadata.py','workbench.py','extension_bindings.py','extension_evidence.py','model_evidence.py', - 'one_fit_evidence.py'})) - - -def subject_hashes(): - return {name:hashlib.sha256((ROOT/name).read_bytes()).hexdigest() for name in PRODUCT_FILES} - - -def neutral_source(root): - """Reuse the legacy authored process fixture without its Dataset setUp.""" - source=(Path(__file__).parent/'fixtures/external_recipe.py').read_bytes() - exact_input=b'Neutral execution input: Unicode \xce\xbb and exact bytes\x00\xff\n' - sha=lambda raw:hashlib.sha256(raw).hexdigest() - definition={ - 'schema_version':1,'format':'external_recipe_v1','id':'neutral', - 'name':'Neutral process qualification','version':1,'runtime':'system_python', - 'sources':[{'path':'recipe.py','sha256':sha(source)}],'entrypoint':'recipe.py', - 'arguments':[{'parameter':'mode'},{'input':'sample'},{'output_dir':True},{'parameter':'note'}], - 'parameters':{'mode':{'type':'string','default':'complete','enum':['complete','sleep','nonzero'],'max_length':16}, - 'note':{'type':'string','default':'Unicode λ 😀','max_length':32}}, - 'inputs':{'sample':{'max_bytes':4096}}, - 'outputs':[{'path':'result.txt','role':'result','max_bytes':4096,'required':True}], - 'environment':{},'resources':{'wall_seconds':10,'max_output_bytes':16384}} - definition_raw=json.dumps(definition).encode() - manifest={'schema_version':1,'id':uuid.uuid4().hex,'name':'Neutral fixture; no scientific claim', - 'data':[{'id':'sample','label':'Exact input','path':'input.bin','sha256':sha(exact_input)}], - 'recipes':[{'id':'neutral','label':'Neutral executable definition','path':'recipe.json','sha256':sha(definition_raw)}], - 'evidence':[],'requirements':[]} - manifest_raw=json.dumps(manifest).encode() - for name,raw in {'recipe.py':source,'input.bin':exact_input,'recipe.json':definition_raw,'project.json':manifest_raw}.items(): - (root/name).write_bytes(raw) - return manifest,manifest_raw,definition_raw,source,exact_input - - -@unittest.skipUnless(os.environ.get('TULDOK_DATABASE_URL'),'Requires disposable real local PostgreSQL') -class ProjectFilesMaterialHTTP(unittest.TestCase): - # One catalog-local wait plus the existing transport/reply allowance. - request_timeout_seconds=CATALOG_LOCAL_TIMEOUT+15 - # Use the actual M2 transport/setup helpers without inheriting unrelated - # acceptance methods or constructing the legacy execution Dataset fixture. - cleanup_owned=m2.ProjectFilesM2HTTP.cleanup_owned - select_host=m2.ProjectFilesM2HTTP.select_host - request=m2.ProjectFilesM2HTTP.request - state=m2.ProjectFilesM2HTTP.state - envelope=m2.ProjectFilesM2HTTP.envelope - action=m2.ProjectFilesM2HTTP.action - create=m2.ProjectFilesM2HTTP.create - arguments=m2.ProjectFilesM2HTTP.arguments - transport=m2.ProjectFilesM2HTTP.transport - call=m2.ProjectFilesM2HTTP.call - - def setUp(self): - self.material_subject=subject_hashes() - m2.ProjectFilesM2HTTP.setUp(self) - - def receipt(self): - current=subject_hashes() - directory=Path(os.environ.get('TULDOK_QA_OUTPUT_ROOT','/workspace/scratch/tuldok-save-load-qa/artifacts'))/'m2-material-http' - directory.mkdir(parents=True,exist_ok=True) - (directory/(self._testMethodName+'-'+uuid.uuid4().hex+'.json')).write_text(json.dumps({ - 'test':self.id(),'seconds':round(time.monotonic()-self.started,3),'operations':self.operations, - 'source_sha256':self.material_subject,'end_sha256':current,'source_stable':current==self.material_subject, - 'fixture':'Existing authored ExternalCase source/input; no execution, runtime provisioning or scientific qualification.'},indent=2)+'\n') - self.assertEqual(current,self.material_subject,'Material/public host source changed during actual HTTP proof') - - def assert_no_live_authority(self,*,studies=0,trials=0): - projection=self.workspace._projection - for table in ('workspace_projects','workspace_runs','access_actors','access_credentials','access_admissions', - 'access_execution_grants','access_execution_consumptions', - 'model_attempt_reservations','model_operation_receipts'): - self.assertEqual(projection.db.execute('SELECT count(*) FROM '+table).fetchone()[0],0,table) - # Canonical authoring intent is reconstructed without importing current - # epochs, Run rows, grants, reservations, or native request receipts. - self.assertEqual(projection.db.execute('SELECT count(*) FROM model_studies').fetchone()[0],studies) - self.assertEqual(projection.db.execute('SELECT count(*) FROM model_trials').fetchone()[0],trials) - self.assertEqual(projection.study_execution._epochs,{}) - self.assertIsNone(projection.execution._runs) - for row in projection.db.execute('SELECT document FROM model_studies'): - self.assertFalse(projection.study_execution.epoch_current(json.loads(row['document']))) - - def closure(self,ref): - with self.owner.bound(self.workspace): - return self.workspace._projection.materials.composition_closure(ref) - - def test_fresh_neutral_material_preparation_and_cold_refs_are_nonexecuting(self): - manifest,manifest_raw,definition_raw,source,exact_input=neutral_source(self.external) - cold_dsn=os.environ.get('TULDOK_PROJECT_FILES_COLD_DATABASE_URL') - self.assertTrue(cold_dsn,'Cold proof requires its separately authorized disposable role/database') - with patch('app.Dataset.__init__',side_effect=AssertionError('New/Open cannot construct a legacy Dataset')) as legacy_dataset, \ - patch('runs.Runs',side_effect=AssertionError('New/Open cannot construct a live Runs owner')) as live_runs, \ - patch('subprocess.Popen',side_effect=AssertionError('Neutral preparation must not execute or probe')) as processes: - self.create();logical=self.state()['project']['project_id'] - self.assertNotEqual(logical,self.workspace.db.dataset_id) - self.assertNotEqual(logical,manifest['id']) - self.assert_no_live_authority() - registered=self.call('source_register',root='fixture',manifest_path='project.json') - self.assertEqual(registered['origin_catalog_id'],logical) - self.assertEqual(registered['project_id'],manifest['id']) - self.assertEqual(registered['manifest_sha256'],hashlib.sha256(manifest_raw).hexdigest()) - draft=self.call('model_create',name='Neutral captured model metadata',kind='captured_source', - task={'kind':'task','catalog_id':logical,'id':'neutral.bytes','revision':1, - 'sha256':digest({'format':'authored_neutral_task_v1'})}, - specification={'format':'authored_neutral_model_v1'}, - source_selector={'project_id':manifest['id'],'recipe_id':'neutral','expected_sha256':hashlib.sha256(definition_raw).hexdigest()}, - preprocessing_policy={'kind':'identity'},output_policy={'kind':'exact_bytes'}) - model=self.call('model_publish',model_id=draft['id'],revision=draft['revision']) - self.assertEqual(model['ref']['catalog_id'],logical) - self.assertEqual(model['material']['source_selector'],draft['source_selector']) - graph=self.call('graph_create_external',name='Neutral exact-byte execution',project_id=manifest['id'], - recipe_id='neutral',expected_sha256=hashlib.sha256(definition_raw).hexdigest(), - inputs={'sample':{'reference_id':'sample','expected_sha256':hashlib.sha256(exact_input).hexdigest()}}) - self.assertEqual(graph['recipe'],'external_recipe') - self.assertEqual(self.call('graph_get',graph_id=graph['id']),graph) - material=self.call('recipe_prepare',graph_id=graph['id'],revision=graph['revision'],model=model['ref']) - self.assertEqual(material['ref']['catalog_id'],logical) - self.assertEqual(material['material']['model'],model['ref']) - self.assertEqual(material['material']['data'],[]) - self.assertEqual(self.call('recipe_material',ref=material['ref'],verify=True),material) - closure=self.closure(material['ref']) - self.assertEqual(closure['kind'],'external') - self.assertEqual(closure['captured_inputs'],{'input/sample':exact_input}) - self.assertEqual(closure['execution_material']['catalog_id'],logical) - self.assertEqual(closure['execution_material']['project']['project_id'],manifest['id']) - self.assertEqual(closure['execution_material']['inputs']['sample']['measured_sha256'],hashlib.sha256(exact_input).hexdigest()) - self.assertEqual(closure['execution_material']['captures']['source/recipe.py']['sha256'],hashlib.sha256(source).hexdigest()) - runtime=self.call('runtime_material',ref=material['material']['runtime'],verify=True) - self.assertEqual(runtime['environment'],closure['execution_material']['runtime']) - policy={'format':'selection_policy_v1','metric_definition_sha256':'b'*64,'checkpoint_rule':'explicit', - 'replicate_reduce':'individual','required_capabilities':[],'numerical_acceptance':'diagnostic','tie_break':'trial_id'} - study=self.call('study_create',name='Neutral retained composition intent',limits={ - 'attempt_slots':3,'admitted_wall_seconds':1000,'retained_bytes':10**9,'peak_staging_bytes':10**9},policy=policy) - trial=self.call('trial_prepare',study_id=study['id'],revision=study['revision'],material=material['ref'],replicate=0) - self.assertEqual(trial['material'],material['ref']) - self.assertEqual(self.call('trial',trial_id=trial['id'],origin_catalog_id=logical),trial) - view=self.call('study',study_id=study['id'],origin_catalog_id=logical,limit=1) - self.assertEqual(view['study']['trial_count'],1) - self.assertTrue(all(value==0 for value in view['charged'].values())) - for table in ('workspace_runs','access_admissions','access_execution_grants','access_execution_consumptions','model_attempt_reservations'): - self.assertEqual(self.workspace._projection.db.execute('SELECT count(*) FROM '+table).fetchone()[0],0,table) - self.action('save');expected_state=self.state();self.action('close') - original=self.external/'alpha';portable=m1.canonical_bytes(original) - cold_root=self.path/'cold-material-root';cold_root.mkdir();clone=cold_root/'clone' - shutil.copytree(original,clone,ignore=shutil.ignore_patterns('.git','.tuldok-local')) - self.assertEqual(m1.canonical_bytes(clone),portable) - source_database=psycopg.conninfo.conninfo_to_dict(os.environ['TULDOK_DATABASE_URL'])['dbname'] - with psycopg.connect(cold_dsn) as connection: - database,allowed=connection.execute('SELECT current_database(),has_database_privilege(current_user,%s,\'CONNECT\')',(source_database,)).fetchone() - self.assertNotEqual(database,source_database);self.assertFalse(allowed) - self.select_host(self.path/'cold-material-control',{'fixture':cold_root},cold_dsn) - self.action('open',root='fixture',directory='clone') - self.assertEqual(self.state()['project'],expected_state['project']) - self.assert_no_live_authority(studies=1,trials=1) - self.assertEqual(self.workspace._projection.db.execute('SELECT id FROM model_studies').fetchone()[0],study['id']) - self.assertEqual(self.workspace._projection.db.execute('SELECT id FROM model_trials').fetchone()[0],trial['id']) - self.assertEqual(self.call('model_get',model_id=draft['id']),draft) - self.assertEqual(self.call('model_material',ref=model['ref'],verify=True),model) - self.assertEqual(self.call('graph_get',graph_id=graph['id']),graph) - self.assertEqual(self.call('recipe_material',ref=material['ref'],verify=True),material) - self.assertEqual(self.call('runtime_material',ref=material['material']['runtime'],verify=True),runtime) - self.assertEqual(self.call('trial',trial_id=trial['id'],origin_catalog_id=logical),trial) - self.assertEqual(self.call('study',study_id=study['id'],origin_catalog_id=logical,limit=1),view) - self.assertEqual(self.closure(material['ref']),closure) - snapshotref={key:registered[key] for key in ('origin_catalog_id','project_id','manifest_sha256')} - status,error=self.transport('source_references',self.arguments('source_references',**snapshotref)) - self.assertEqual(status,409,error) - self.assert_no_live_authority(studies=1,trials=1);self.action('save') - self.assertEqual(m1.canonical_bytes(clone),portable) - processes.assert_not_called();live_runs.assert_not_called();legacy_dataset.assert_not_called() - - -if __name__=='__main__':unittest.main() diff --git a/tests/test_project_files_owner_mcp.py b/tests/test_project_files_owner_mcp.py deleted file mode 100644 index 95094583..00000000 --- a/tests/test_project_files_owner_mcp.py +++ /dev/null @@ -1,264 +0,0 @@ -"""Explicit project-owner MCP mode over real stdio, HTTP and disposable PG. - -The qualification subject is a separate immutable copy of the accepted M4 -client source plus exactly this test and the explicit MCP profile change. -No runtime, recipe, provider or scientific execution occurs in this fixture. -""" -from datetime import timedelta -import hashlib -import importlib.util -import io -import json -import os -from pathlib import Path -import subprocess -import sys -import time -import unittest -from unittest.mock import Mock, patch -import uuid - -import agent_api -import mcp_stdio -import test_project_files_http as http_fixture - -ROOT=Path(__file__).resolve().parents[1] -SDK_AVAILABLE=all(importlib.util.find_spec(name) for name in ('mcp','anyio','jsonschema')) - - -def subject(): - name=os.environ.get('TULDOK_OWNER_MCP_MANIFEST') - if not name:raise AssertionError('Provide the immutable owner-MCP qualification manifest') - path=Path(name);value=json.loads(path.read_text()) - if value['qualification_copy']!=str(ROOT):raise AssertionError('Tests must run in the selected immutable copy') - current={name:hashlib.sha256((ROOT/name).read_bytes()).hexdigest() for name in value['files']} - if current!=value['files']:raise AssertionError('Immutable owner-MCP source changed before the test') - return dict(manifest_sha256=hashlib.sha256(path.read_bytes()).hexdigest(), - parent_manifest_sha256=value['parent_manifest_sha256'],files=current) - - -@unittest.skipUnless(SDK_AVAILABLE,'Requires the approved optional MCP dependencies') -class OwnerModeSelection(unittest.TestCase): - def test_owner_opt_in_selects_only_existing_finite_owner_client_before_serving(self): - import anyio - owner=Mock();order=[];owner.bootstrap.side_effect=lambda:order.append('bootstrap') - def ready(function,client,*args): - self.assertIs(function,mcp_stdio.serve);self.assertIs(client,owner) - self.assertEqual(order,['bootstrap']);order.append('serve') - with (patch.object(agent_api.ProjectFilesOwnerClient,'from_config',return_value=owner) as selected, - patch.object(agent_api.AgentClient,'from_config',side_effect=AssertionError('No implicit agent fallback')), - patch.object(anyio,'run',side_effect=ready)): - self.assertEqual(mcp_stdio.main(['--config','fixture-only','--project-files-owner']),0) - selected.assert_called_once_with('fixture-only');self.assertEqual(order,['bootstrap','serve']) - - def test_default_agent_and_owner_bootstrap_refusal_never_fall_back(self): - import anyio - agent=Mock() - with (patch.object(agent_api.AgentClient,'from_config',return_value=agent) as selected, - patch.object(agent_api.ProjectFilesOwnerClient,'from_config',side_effect=AssertionError('Owner mode requires flag')), - patch.object(anyio,'run') as run): - self.assertEqual(mcp_stdio.main(['--config','fixture-only']),0) - self.assertIs(run.call_args.args[1],agent);selected.assert_called_once() - owner=Mock();owner.bootstrap.side_effect=agent_api.AgentAPIError('Refused fixture identity.','unauthenticated',401) - with (patch.object(agent_api.ProjectFilesOwnerClient,'from_config',return_value=owner), - patch.object(agent_api.AgentClient,'from_config',side_effect=AssertionError('No fallback after owner refusal')), - patch.object(anyio,'run') as run,patch('sys.stderr',new_callable=io.StringIO)): - self.assertEqual(mcp_stdio.main(['--config','fixture-only','--project-files-owner']),1) - run.assert_not_called() - - -@unittest.skipUnless(SDK_AVAILABLE,'Requires the approved optional MCP dependencies') -class TransferModeSelection(unittest.TestCase): - def test_transfer_opt_in_selects_five_only_owner_client_before_serving(self): - import anyio - owner=Mock();order=[];owner.bootstrap.side_effect=lambda:order.append('bootstrap') - self.assertEqual(agent_api.ProjectTransferOwnerClient.OPERATIONS, - frozenset('project_transfer.'+name for name in ('status','preview','report_page','stop','extract'))) - def ready(function,client,*args): - self.assertIs(function,mcp_stdio.serve);self.assertIs(client,owner) - self.assertEqual(order,['bootstrap']);order.append('serve') - with (patch.object(agent_api.ProjectTransferOwnerClient,'from_config',return_value=owner) as selected, - patch.object(agent_api.ProjectFilesOwnerClient,'from_config',side_effect=AssertionError('No file-owner fallback')), - patch.object(agent_api.AgentClient,'from_config',side_effect=AssertionError('No agent fallback')), - patch.object(anyio,'run',side_effect=ready)): - self.assertEqual(mcp_stdio.main(['--config','fixture-only','--project-transfer-owner']),0) - selected.assert_called_once_with('fixture-only');self.assertEqual(order,['bootstrap','serve']) - - def test_owner_profile_flags_are_mutually_exclusive_before_configuration_read(self): - with (patch.object(agent_api.ProjectTransferOwnerClient,'from_config') as transfer, - patch.object(agent_api.ProjectFilesOwnerClient,'from_config') as files, - patch.object(agent_api.AgentClient,'from_config') as agent, - patch('sys.stderr',new_callable=io.StringIO)): - with self.assertRaises(SystemExit) as refusal: - mcp_stdio.main(['--config','fixture-only','--project-files-owner','--project-transfer-owner']) - self.assertEqual(refusal.exception.code,2) - transfer.assert_not_called();files.assert_not_called();agent.assert_not_called() - - def test_transfer_bootstrap_refusal_cannot_serve_or_select_another_authority(self): - import anyio - owner=Mock();owner.bootstrap.side_effect=agent_api.AgentAPIError('Fixture host credential refused.','unauthenticated',401) - with (patch.object(agent_api.ProjectTransferOwnerClient,'from_config',return_value=owner), - patch.object(agent_api.ProjectFilesOwnerClient,'from_config',side_effect=AssertionError('No file-owner fallback')), - patch.object(agent_api.AgentClient,'from_config',side_effect=AssertionError('No agent fallback')), - patch.object(anyio,'run') as run,patch('sys.stderr',new_callable=io.StringIO)): - self.assertEqual(mcp_stdio.main(['--config','fixture-only','--project-transfer-owner']),1) - owner.bootstrap.assert_called_once_with();run.assert_not_called() - - -@unittest.skipUnless(SDK_AVAILABLE and os.environ.get('TULDOK_DATABASE_URL'), - 'Requires approved MCP dependencies and disposable PostgreSQL') -class OwnerMCPHTTP(unittest.TestCase): - def setUp(self): - self.subject=subject();self.performed=[];self.started=time.monotonic() - self.fixture=http_fixture.ProjectFilesHTTP('test_authenticated_owner_only_selection_and_inert_control') - self.fixture.setUp();self.addCleanup(self.fixture.doCleanups) - self.addCleanup(self.receipt) - self.environment={key:value for key,value in os.environ.items() if not key.startswith(('TULDOK_','PG'))} - self.environment['PYTHONDONTWRITEBYTECODE']='1' - - def receipt(self): - current={name:hashlib.sha256((ROOT/name).read_bytes()).hexdigest() for name in self.subject['files']} - target=Path(os.environ.get('TULDOK_QA_OUTPUT_ROOT','/workspace/scratch/tuldok-save-load-qa/artifacts'))/'owner-mcp' - target.mkdir(parents=True,exist_ok=True) - value=dict(test=self.id(),seconds=round(time.monotonic()-self.started,3),performed=self.performed, - qualification_manifest_sha256=self.subject['manifest_sha256'],parent_manifest_sha256=self.subject['parent_manifest_sha256'], - source_stable=current==self.subject['files'],mcp_stdio_sha256=current['mcp_stdio.py'], - test_sha256=hashlib.sha256(Path(__file__).read_bytes()).hexdigest(), - fixture='Actual MCP SDK stdio and authenticated HTTP; disposable PostgreSQL; authored text only') - (target/(self._testMethodName+'-'+uuid.uuid4().hex+'.json')).write_text(json.dumps(value,indent=2)+'\n') - self.assertEqual(current,self.subject['files'],'Immutable owner-MCP source changed during the test') - - def config(self,label,token,*,catalog_id=None): - f=self.fixture;private=f.path/(label+'.token');config=f.path/(label+'.json') - private.write_text(token+'\n');private.chmod(0o600) - config.write_text(json.dumps(dict(endpoint=f.origin,catalog_id=catalog_id or f.owner.catalog_id,token_file=str(private),timeout=15))) - config.chmod(0o600);return config - - def parameters(self,config,*,owner=True): - from mcp import StdioServerParameters - return StdioServerParameters(command=sys.executable,args=[str(ROOT/'mcp_stdio.py'),'--config',str(config), - *(['--project-files-owner'] if owner else [])],cwd=str(ROOT),env=self.environment) - - async def tools(self,session,*,owner): - listed=(await session.list_tools()).tools;names={item.name for item in listed} - self.assertTrue(names) - if owner: - allowed={agent_api.operation(name)['mcp_name'] for name in agent_api.ProjectFilesOwnerClient.OPERATIONS} - self.assertTrue(names<=allowed) - self.assertFalse({'context_get','identity_get','runs_recover_publication','runs_recover_coordinator'}&names) - self.assertTrue({'project_files_new','project_files_open','project_files_save','project_files_save_as','project_files_close'}<=names) - else:self.assertIn('context_get',names) - return names - - async def tool(self,session,action,arguments,*,status=200): - result=await session.call_tool('project_files_'+action,arguments) - envelope=result.structuredContent - self.assertEqual(envelope['status'],status,envelope) - self.assertEqual(result.isError,status>=400) - self.assertEqual(json.loads(result.content[0].text),envelope) - return envelope['result'] - - def test_owner_new_import_save_save_as_close_open_and_nonproject_profile_refusal(self): - import anyio - from mcp import ClientSession - from mcp.client.stdio import stdio_client - from mcp.shared.exceptions import McpError - f=self.fixture;config=self.config('owner',f.owner.token) - async def exercise(): - with (f.path/'owner-mcp.stderr').open('w+') as errors: - async with stdio_client(self.parameters(config),errlog=errors) as (reader,writer): - async with ClientSession(reader,writer,read_timeout_seconds=timedelta(seconds=20)) as session: - await session.initialize();names=await self.tools(session,owner=True) - self.performed.append(dict(owner_tool_count=len(names),all_tools_finite_project_files=True)) - with self.assertRaises(McpError) as refusal: - await session.call_tool('runs_recover_publication',{}) - self.assertEqual(refusal.exception.error.code,-32602) - initial=await self.tool(session,'status',{}) - opened=await self.tool(session,'new',f.envelope(initial,root='fixture',directory='owner-source',name='Actual owner MCP 山')) - imported=await self.tool(session,'import_text',f.envelope(opened,asset=dict( - text=http_fixture.TEXT,name='Actual owner MCP authored observation',groups=['owner-mcp'],parents=[],rights='Owned synthetic fixture'))) - state=await self.tool(session,'status',{});source_id=state['project']['project_id'] - saved=await self.tool(session,'save',f.envelope(state)) - self.assertEqual(saved['project'],state['project']) - # Edits reach the folder on Save; Save As must leave the saved source exact. - source_before=http_fixture.canonical_bytes(f.external/'owner-source') - fork=await self.tool(session,'save_as',f.envelope(saved,root='fixture',directory='owner-fork',name='Independent MCP Ω')) - current=fork['state'];self.assertNotEqual(current['project']['project_id'],source_id) - self.assertEqual(http_fixture.canonical_bytes(f.external/'owner-source'),source_before) - closed=await self.tool(session,'close',f.envelope(current));self.assertEqual(closed['state'],'no_project_open') - reopened=await self.tool(session,'open',f.envelope(closed,root='fixture',directory='owner-fork')) - self.assertEqual(reopened['project'],current['project']) - page=await self.tool(session,'query',dict(binding=reopened['binding'],checkpoint=reopened['project']['checkpoint'])) - self.assertEqual(len(page['items']),1);record_id=page['items'][0]['id'] - self.assertNotEqual(record_id,imported['record']['id']) - actual=await self.tool(session,'get',dict(record_id=record_id,binding=reopened['binding'],checkpoint=reopened['project']['checkpoint'])) - self.assertEqual(actual['record']['text'],http_fixture.TEXT) - self.assertIsNone(f.workspace._projection.execution._runs) - self.performed.extend(['Actual owner MCP New/import_text/Save/SaveAs/Close/Open completed', - 'Independent project and record IDs; original source bytes exact; Unicode text cold restored', - 'Nonproject publication owner tool refused at MCP profile boundary; no execution owner constructed']) - errors.seek(0);self.assertNotIn(f.owner.token,errors.read()) - anyio.run(exercise) - - def test_bootstrap_denies_wrong_identity_revoked_and_other_catalog_without_fallback(self): - f=self.fixture - with f.owner.bound(f.workspace): - agent=f.workspace.access.issue(dict(label='MCP denial fixture agent',scopes=['inspect','edit'])) - cases=[('owner-without-optin',self.config('owner-default',f.owner.token),False,f.owner.token), - ('agent-in-owner-mode',self.config('agent-owner-mode',agent['token']),True,agent['token'])] - saved=(f.workspace,f.owner,f.origin) - f.select_host(f.path/'other-control',{'fixture':f.external}) - other=f.owner - f.workspace,f.owner,f.origin=saved - cases.append(('other-catalog-owner',self.config('other-owner',other.token),True,other.token)) - def refused(label,config,owner,token): - command=[sys.executable,str(ROOT/'mcp_stdio.py'),'--config',str(config),*(['--project-files-owner'] if owner else [])] - result=subprocess.run(command,input='',cwd=ROOT,env=self.environment,capture_output=True,text=True,timeout=20) - self.assertEqual(result.returncode,1,(label,result.stdout,result.stderr));self.assertEqual(result.stdout,'') - self.assertNotIn(token,result.stderr);self.assertNotIn(f.origin,result.stderr) - self.performed.append(label+' refused before MCP service initialization') - for case in cases:refused(*case) - with f.owner.bound(f.workspace):f.workspace.access.revoke(f.owner.identity['credential_id']) - refused('revoked-owner',self.config('revoked-owner',f.owner.token),True,f.owner.token) - self.assertEqual(list(f.external.iterdir()),[]) - - def test_revocation_after_owner_bootstrap_denies_mutation_and_retains_no_project(self): - import anyio - from mcp import ClientSession - from mcp.client.stdio import stdio_client - f=self.fixture;config=self.config('revoke-after-start',f.owner.token) - async def exercise(): - with (f.path/'revoked-mcp.stderr').open('w+') as errors: - async with stdio_client(self.parameters(config),errlog=errors) as (reader,writer): - async with ClientSession(reader,writer,read_timeout_seconds=timedelta(seconds=20)) as session: - await session.initialize();await self.tools(session,owner=True) - state=await self.tool(session,'status',{}) - with f.owner.bound(f.workspace):f.workspace.access.revoke(f.owner.identity['credential_id']) - denial=await self.tool(session,'new',f.envelope(state,root='fixture',directory='revoked-write',name='Denied'),status=401) - self.assertEqual(denial['code'],'unauthenticated') - self.assertFalse((f.external/'revoked-write').exists());self.assertIsNone(f.workspace._store) - self.performed.append('Current HTTP credential revocation after MCP bootstrap prevents New without a filesystem effect') - errors.seek(0);self.assertNotIn(f.owner.token,errors.read()) - anyio.run(exercise) - - def test_default_agent_mcp_still_reads_edits_and_cannot_use_owner_lifecycle(self): - import anyio - from mcp import ClientSession - from mcp.client.stdio import stdio_client - f=self.fixture;f.action('new',root='fixture',directory='agent-source',name='Default agent fixture') - with f.owner.bound(f.workspace):agent=f.workspace.access.issue(dict(label='Default MCP editor',scopes=['inspect','edit'])) - config=self.config('default-agent',agent['token']) - async def exercise(): - with (f.path/'agent-mcp.stderr').open('w+') as errors: - async with stdio_client(self.parameters(config,owner=False),errlog=errors) as (reader,writer): - async with ClientSession(reader,writer,read_timeout_seconds=timedelta(seconds=20)) as session: - await session.initialize();await self.tools(session,owner=False) - current=await self.tool(session,'status',{}) - result=await self.tool(session,'import_text',f.envelope(current,asset=dict(text='Default agent exact text',name='Agent note',groups=['agent'],parents=[],rights='Owned fixture'))) - self.assertEqual(result['record']['text'],'Default agent exact text') - current=await self.tool(session,'status',{});before=http_fixture.canonical_bytes(f.external/'agent-source') - await self.tool(session,'save_as',f.envelope(current,root='fixture',directory='agent-denied',name='Denied'),status=403) - self.assertFalse((f.external/'agent-denied').exists());self.assertEqual(http_fixture.canonical_bytes(f.external/'agent-source'),before) - self.performed.append('Unchanged default agent MCP can inspect/edit; owner SaveAs returns403 with no canonical effect') - errors.seek(0);self.assertNotIn(agent['token'],errors.read()) - anyio.run(exercise) diff --git a/tests/test_project_fork.py b/tests/test_project_fork.py deleted file mode 100644 index 0683eef9..00000000 --- a/tests/test_project_fork.py +++ /dev/null @@ -1,398 +0,0 @@ -"""Independent fork publication: exact origins, verified bytes, no-clobber roots.""" -import copy -import errno -import hashlib -import json -import os -from pathlib import Path -import shutil -import subprocess -import sys -import tempfile -from types import SimpleNamespace -import unittest -from unittest.mock import patch -import uuid - -sys.path.insert(0, str(Path(__file__).resolve().parents[1])) -import project_fork as fork_module -from project_artifacts import ProjectArtifacts -from project_fork import ProjectForkError, active_records, decode_fork, publish_fork -from project_material import ProjectMaterial, decode_records as decode_material_records -from project_store import ProjectStore, ProjectStoreError, DIR_FLAGS -from test_project_material import model, SOURCE - - -def body(value): - return hashlib.sha256(json.dumps(value, sort_keys=True).encode()).hexdigest() - - -def validate(records, project_id): - decode_fork(records, project_id=project_id) - decode_material_records(records) - - -class ForkFilesystemTests(unittest.TestCase): - def setUp(self): - self.tmp = tempfile.TemporaryDirectory(prefix='tuldok-fork-') - self.addCleanup(self.tmp.cleanup) - self.path = Path(self.tmp.name) - self.root = self.path / 'projects' - self.root.mkdir() - self.root_fd = os.open(self.root, DIR_FLAGS) - self.addCleanup(lambda: os.close(self.root_fd)) - self.source_path = self.root / 'source' - self.source = ProjectStore.create(self.source_path, 'Source scientific intent', 'create-source', 'a' * 64) - self.addCleanup(lambda: self.source.close()) - self.artifacts = ProjectArtifacts(self.source) - self.addCleanup(self.artifacts.close) - self.origin = self.source.snapshot()['project_id'] - self.material_value, payloads = model(self.origin) - local = self.path / 'local-material' - capture = local / self.material_value['ref']['sha256'] - capture.mkdir(parents=True) - for name, raw in payloads.items(): - (capture / name).write_bytes(raw) - session = SimpleNamespace(snapshot=self.source.snapshot(), artifacts=self.artifacts, check_current=lambda: None) - self.material = ProjectMaterial(session) - self.record = self.material.capture_model_material(self.material_value, local) - records = [*self.material.declarations(self.record), self.record] - self.original = self.source.commit(records, self.source.snapshot()['checkpoint'], 'retain', body(records)) - - def candidate(self, source, destination): - return dict(records=copy.deepcopy(source['records']), mapping=[], archived=[], - artifacts=[dict(declaration=copy.deepcopy(item['document']), preservation='unique') - for item in source['records'] if item['family'] == 'project_artifact']) - - def fork(self, relative='fork', **options): - arguments = dict(root_path=self.root, name='Independent copy', expected_checkpoint=self.original['checkpoint'], - request_key='fork:one', quiescent=True, build_candidate=self.candidate, validate_candidate=validate) - arguments.update(options) - return publish_fork(self.source, self.artifacts, self.root_fd, relative, **arguments) - - def assert_code(self, code, function, *args, **kwargs): - with self.assertRaises(ProjectStoreError) as caught: - function(*args, **kwargs) - self.assertEqual(caught.exception.code, code) - return caught.exception - - def canonical_bytes(self): - return {p.relative_to(self.source_path).as_posix(): p.read_bytes() - for p in self.source_path.rglob('*') if p.is_file() and '.tuldok-local' not in p.parts} - - def test_complete_fork_retains_exact_original_material_hashes_and_copies_without_aliases(self): - before = self.canonical_bytes() - with patch.object(subprocess, 'Popen', side_effect=AssertionError('No project execution')): - result = self.fork() - snapshot, overlay = result['snapshot'], result['fork'] - self.assertNotEqual(snapshot['project_id'], self.origin) - self.assertFalse(result['reconciled']) - self.assertEqual(overlay['source'], dict(project_id=self.origin, checkpoint=self.original['checkpoint'])) - self.assertEqual(next(item for item in snapshot['records'] if item['family'] == 'model_material'), self.record) - with ProjectStore.open(self.root / 'fork') as destination, ProjectArtifacts(destination) as artifacts: - reader = ProjectMaterial(SimpleNamespace(snapshot=destination.snapshot(), artifacts=artifacts, check_current=lambda: None)) - self.assertEqual(reader.model(self.material_value['ref'], verify=True), self.material_value) - source_ref = self.material_value['material']['source_closure'][0]['blob'] - self.assertEqual(reader.blob(self.material_value['ref'], source_ref), SOURCE) - for sha in overlay['artifacts']['copied']: - old = self.source_path / 'artifacts/sha256' / sha - new = self.root / 'fork/artifacts/sha256' / sha - self.assertEqual(new.read_bytes(), old.read_bytes()) - self.assertNotEqual((new.stat().st_dev, new.stat().st_ino), (old.stat().st_dev, old.stat().st_ino)) - self.assertEqual(new.stat().st_nlink, 1) - manifest = json.loads((self.root / 'fork/.tuldok/project.json').read_bytes()) - self.assertTrue(all(item['namespace'] == snapshot['project_id'] for item in manifest['inventory'])) - self.assertEqual(self.canonical_bytes(), before) - - def test_exact_retry_reconciles_and_changed_body_or_unrelated_destination_never_overwrites(self): - first = self.fork() - before = (self.root / 'fork/.tuldok/project.json').read_bytes() - with patch.object(self, 'candidate', side_effect=AssertionError('Never repeat construction')): - replay = self.fork() - self.assertTrue(replay['reconciled']) - self.assertEqual(replay['snapshot'], first['snapshot']) - self.assert_code('conflict', self.fork, name='Different request') - self.assertEqual((self.root / 'fork/.tuldok/project.json').read_bytes(), before) - other = self.root / 'unrelated' - with ProjectStore.create(other, 'Existing owner', 'other', 'b' * 64): - pass - unrelated = (other / '.tuldok/project.json').read_bytes() - self.assert_code('conflict', self.fork, 'unrelated') - self.assertEqual((other / '.tuldok/project.json').read_bytes(), unrelated) - - def test_missing_runtime_inventory_does_not_repeat_full_source_closure_per_entry(self): - # Each snapshot validates the complete canonical file closure. Missing - # runtime declarations must not multiply that work by inventory length. - snapshot = self.source.snapshot - with patch.object(self.source, 'snapshot', wraps=snapshot) as scans: - self.fork('small-inventory') - baseline = scans.call_count - records = copy.deepcopy(self.original['records']) - runtime = set() - for index in range(32): - raw = ('unmaterialized runtime dependency %d' % index).encode() - sha = hashlib.sha256(raw).hexdigest() - runtime.add(sha) - records.append(dict(family='project_artifact', id=sha, - document=dict(format='project_artifact_v1', sha256=sha, bytes=len(raw)))) - self.original = self.source.commit(records, self.original['checkpoint'], - 'larger-runtime-inventory', body(records)) - def candidate(source, destination): - value = self.candidate(source, destination) - for edge in value['artifacts']: - if edge['declaration']['sha256'] in runtime: - edge['preservation'] = 'regenerable' - return value - with patch.object(self.source, 'snapshot', wraps=snapshot) as scans: - result = self.fork('large-inventory', build_candidate=candidate) - self.assertEqual(set(result['fork']['artifacts']['missing_regenerable']), runtime) - self.assertLessEqual(scans.call_count, baseline + 4, - 'Full source closure scans must stay bounded when missing runtime inventory grows') - - def test_present_payload_copy_does_not_repeat_full_source_closure_per_file(self): - snapshot = self.source.snapshot - with patch.object(self.source, 'snapshot', wraps=snapshot) as scans: - self.fork('small-payload-set') - baseline = scans.call_count - records = copy.deepcopy(self.original['records']) - payloads = {} - for index in range(8): - raw = ('retained unique output %d' % index).encode() - sha = hashlib.sha256(raw).hexdigest() - value = dict(format='project_artifact_v1', sha256=sha, bytes=len(raw)) - self.artifacts.publish_bytes(raw, value) - records.append(dict(family='project_artifact', id=sha, document=value)) - payloads[sha] = raw - self.original = self.source.commit(records, self.original['checkpoint'], - 'larger-payload-set', body(records)) - with patch.object(self.source, 'snapshot', wraps=snapshot) as scans: - result = self.fork('large-payload-set') - for sha, raw in payloads.items(): - self.assertIn(sha, result['fork']['artifacts']['copied']) - self.assertEqual((self.root / 'large-payload-set/artifacts/sha256' / sha).read_bytes(), raw) - self.assertLessEqual(scans.call_count, baseline + 4, - 'Full source closure scans must stay bounded when present payload count grows') - - def test_quiescence_checkpoint_overlap_and_symlink_guards_precede_publication(self): - before = self.canonical_bytes() - self.assert_code('busy', self.fork, quiescent=False) - self.assert_code('stale', self.fork, expected_checkpoint='f' * 64) - self.assert_code('invalid', self.fork, 'source/nested-fork') - self.assert_code('invalid', self.fork, 'source') - alias = self.root / 'alias' - alias.symlink_to(self.source_path, target_is_directory=True) - self.assert_code('conflict', self.fork, 'alias') - self.assert_code('invalid', self.fork, '../escape') - self.assertEqual(self.canonical_bytes(), before) - self.assertFalse((self.source_path / 'nested-fork').exists()) - - def test_missing_unique_corrupt_and_source_hardlinks_block_without_final_destination(self): - declaration = next(item['document'] for item in self.original['records'] if item['family'] == 'project_artifact') - payload = self.source_path / 'artifacts/sha256' / declaration['sha256'] - raw = payload.read_bytes() - payload.unlink() - self.assert_code('unavailable', self.fork) - self.assertFalse((self.root / 'fork').exists()) - payload.write_bytes(b'corrupt') - self.assert_code('invalid', self.fork) - payload.unlink() - payload.write_bytes(raw) - os.link(payload, self.path / 'unsafe-alias') - self.assert_code('invalid', self.fork) - self.assertFalse((self.root / 'fork').exists()) - self.assertEqual(self.source.snapshot(), self.original) - - def test_missing_regenerable_is_explicit_and_present_regenerable_is_still_copied(self): - # Model evidence above remains unique. Two separate owner-declared cache - # payloads exercise the explicit regenerable policy without downgrading it. - caches = [b'Regenerable optional cache one', b'Regenerable optional cache two'] - declarations = [dict(format='project_artifact_v1', sha256=hashlib.sha256(raw).hexdigest(), bytes=len(raw)) for raw in caches] - records = copy.deepcopy(self.original['records']) - for raw, declaration in zip(caches, declarations): - self.artifacts.publish_bytes(raw, declaration) - records.append(dict(family='project_artifact', id=declaration['sha256'], document=declaration)) - self.original = self.source.commit(records, self.original['checkpoint'], 'cache-declarations', body(records)) - missing = declarations[0]['sha256'] - (self.source_path / 'artifacts/sha256' / missing).unlink() - regenerable = {item['sha256'] for item in declarations} - def candidate(source, destination): - value = self.candidate(source, destination) - for edge in value['artifacts']: - if edge['declaration']['sha256'] in regenerable: - edge['preservation'] = 'regenerable' - return value - result = self.fork(build_candidate=candidate) - self.assertEqual(result['fork']['artifacts']['missing_regenerable'], [missing]) - self.assertIn(declarations[1]['sha256'], result['fork']['artifacts']['copied']) - self.assertEqual(len(result['fork']['artifacts']['copied']), len(records)-2) - with ProjectStore.open(self.root / 'fork') as destination, ProjectArtifacts(destination) as owner: - self.assertEqual(owner.status(declarations[0])['state'], 'missing') - - def test_invalid_candidate_or_omitted_inventory_retains_stage_and_source(self): - before = self.canonical_bytes() - def changed(source, destination): - value = self.candidate(source, destination) - next(item for item in value['records'] if item['family']=='project_artifact')['document']['bytes'] += 1 - return value - error = self.assert_code('invalid', self.fork, build_candidate=changed) - self.assertTrue(error.staging_directory.startswith('.tuldok-fork-')) - self.assertFalse((self.root / 'fork').exists()) - def missing_plan(source, destination): - value = self.candidate(source, destination) - value['artifacts'] = [] - return value - self.assert_code('invalid', self.fork, build_candidate=missing_plan) - self.assertEqual(self.canonical_bytes(), before) - - def test_final_rename_race_never_overwrites_existing_destination(self): - rename = fork_module._rename_noreplace - target = self.root / 'fork' - def race(parent, source, destination): - if destination == 'fork': - self.assertFalse(target.exists()) - target.mkdir() - (target / 'owned.txt').write_bytes(b'Existing owner') - rename(parent, source, destination) - with patch.object(fork_module, '_rename_noreplace', side_effect=race): - self.assert_code('conflict', self.fork) - self.assertEqual(list(target.iterdir()), [target / 'owned.txt']) - self.assertEqual((target / 'owned.txt').read_bytes(), b'Existing owner') - - def test_post_rename_fsync_failure_is_unknown_and_exact_retry_requires_fresh_barrier(self): - sync = fork_module.os.fsync - root = self.root.stat() - def fail_final_parent(fd): - info = os.fstat(fd) - if (info.st_dev, info.st_ino) == (root.st_dev, root.st_ino) and (self.root / 'fork').exists(): - raise OSError(errno.EIO, 'fork parent durability unknown') - return sync(fd) - with patch.object(fork_module.os, 'fsync', side_effect=fail_final_parent): - error = self.assert_code('unknown', self.fork) - self.assertTrue(error.receipt['committed']) - self.assertFalse(error.receipt['selected']) - self.assert_code('unavailable', self.fork) - reconciled = self.fork() - self.assertTrue(reconciled['reconciled']) - self.assertEqual(reconciled['snapshot']['project_id'], error.receipt['project_id']) - self.assertEqual(self.source.snapshot(), self.original) - - def test_real_process_kill_before_and_after_destination_publication_is_coherent(self): - self.artifacts.close() - self.source.close() - code = r''' -import copy,os,sys -import project_fork as m -from project_artifacts import ProjectArtifacts -from project_store import ProjectStore,DIR_FLAGS -from project_material import decode_records -root,window=sys.argv[1:] -source=ProjectStore.open(os.path.join(root,'source')) -artifacts=ProjectArtifacts(source) -rootfd=os.open(root,DIR_FLAGS) -rename=m._rename_noreplace -commit=ProjectStore.commit -def kill_rename(*args): - if window=='before_rename':os._exit(77) - rename(*args) - if window=='after_rename':os._exit(77) -def kill_commit(*args,**kwargs): - value=commit(*args,**kwargs) - if window=='after_checkpoint':os._exit(77) - return value -m._rename_noreplace=kill_rename -ProjectStore.commit=kill_commit -def build(snapshot,dest): - return {'records':copy.deepcopy(snapshot['records']),'mapping':[],'archived':[], - 'artifacts':[{'declaration':item['document'],'preservation':'unique'} - for item in snapshot['records'] if item['family']=='project_artifact']} -def validate(records,project): - m.decode_fork(records,project_id=project);decode_records(records) -m.publish_fork(source,artifacts,rootfd,'fork',root_path=root,name='Independent copy', - expected_checkpoint=source.snapshot()['checkpoint'],request_key='fork:one',quiescent=True, - build_candidate=build,validate_candidate=validate) -raise AssertionError('Fault window was not reached') -''' - for window in ('after_checkpoint', 'before_rename', 'after_rename'): - with self.subTest(window=window): - root = self.path / ('kill-' + window) - root.mkdir() - shutil.copytree(self.source_path, root / 'source') - child = subprocess.run([sys.executable, '-c', code, str(root), window], - cwd=Path(fork_module.__file__).parent, capture_output=True, text=True, timeout=15) - self.assertEqual(child.returncode, 77, child.stderr) - self.assertEqual((root / 'fork').exists(), window == 'after_rename') - with ProjectStore.open(root / 'source') as source, ProjectArtifacts(source) as artifacts: - self.assertEqual(source.snapshot(), self.original) - if window == 'after_rename': - rootfd = os.open(root, DIR_FLAGS) - try: - result = publish_fork(source, artifacts, rootfd, 'fork', root_path=root, - name='Independent copy', expected_checkpoint=self.original['checkpoint'], - request_key='fork:one', quiescent=True, - build_candidate=lambda *_: self.fail('Never repeat an already published fork'), - validate_candidate=validate) - self.assertTrue(result['reconciled']) - finally: - os.close(rootfd) - else: - stages = list(root.glob('.tuldok-fork-*')) - self.assertEqual(len(stages), 1) - with ProjectStore.open(stages[0]) as retained: - overlay = decode_fork(retained.snapshot()['records']) - self.assertEqual(overlay['source']['checkpoint'], self.original['checkpoint']) - self.assertEqual(next(item for item in retained.snapshot()['records'] - if item['family']=='model_material'), self.record) - - def test_current_overlay_filters_receipts_and_original_editables_without_rewriting_history(self): - source_id = 'a' * 32 - new_id = 'b' * 32 - # Structural mapping tests stay at this codec boundary; semantic data - # origin construction is owned and tested by ProjectData's fork codec. - originals = [dict(family='workbench_text', id=source_id, document={'format': 'workbench_text_v1'}), - dict(family='project_operation', id='c' * 64, document={'format': 'project_operation_v1'})] - destination = dict(family='workbench_record', id=new_id, document={'format': 'workbench_record_v1'}) - identity = 'd' * 32 - source = dict(project_id='e' * 32, checkpoint='f' * 64) - overlay = dict(format='project_fork_v1', source=source, destination_project_id=identity, - request_key='fork:fixture', request_sha256=fork_module._digest(fork_module._input(source, 'copy', 'Copy', 'fork:fixture')), - directory='copy', name='Copy', mapping=[dict(family='workbench_text', source_id=source_id, - source_revision=1, destination_id=new_id)], archived=[dict(family=i['family'], id=i['id']) for i in sorted(originals, key=lambda i:(i['family'],i['id']))], - artifacts=dict(copied=[], missing_regenerable=[])) - current = dict(family='project_fork', id=identity, document=overlay) - records = [*originals, destination, current] - self.assertEqual(decode_fork(records, project_id=identity), overlay) - self.assertEqual(active_records(records, project_id=identity), [destination, current]) - self.assertEqual(records[0], originals[0]) - bad = copy.deepcopy(records) - bad[-1]['document']['mapping'][0]['source_revision'] = True - self.assert_code('invalid', decode_fork, bad) - bad = copy.deepcopy(records) - bad[-1]['document']['mapping'][0]['destination_id'] = source_id - self.assert_code('invalid', decode_fork, bad) - - -class ActiveRecordSelectionTests(unittest.TestCase): - def test_family_selection_keeps_independent_values_and_default_membership(self): - records=[dict(family=family,id='a'*32,document=dict(format='fixture_v1',values=[1])) - for family in ('project_operation','workbench_text')] - self.assertEqual(active_records(records),records) - selected=active_records(records,families=frozenset({'project_operation'})) - self.assertEqual(selected,[records[0]]) - selected[0]['document']['values'].append(2) - self.assertEqual(records[0]['document']['values'],[1]) - self.assertEqual(active_records(records,families=frozenset()),[]) - - def test_family_selection_still_validates_excluded_fork_structure(self): - record=dict(family='workbench_text',id='a'*32,document={'format':'workbench_text_v1'}) - with self.assertRaisesRegex(ProjectForkError,'Duplicate'): - active_records([record,copy.deepcopy(record)],families=frozenset({'project_operation'})) - - def test_family_selection_rejects_implicit_or_invalid_selectors(self): - for invalid in ('project_operation',[],frozenset({1}),frozenset({'bad/family'})): - with self.subTest(selector=invalid),self.assertRaises(ProjectStoreError) as caught: - active_records([],families=invalid) - self.assertEqual(caught.exception.code,'invalid') - - -if __name__ == '__main__': - unittest.main() diff --git a/tests/test_project_fork_composition.py b/tests/test_project_fork_composition.py deleted file mode 100644 index 28e48361..00000000 --- a/tests/test_project_fork_composition.py +++ /dev/null @@ -1,365 +0,0 @@ -"""Fixed pure fork assembly and conservative payload identity dispositions.""" -import copy -import hashlib -import os -from pathlib import Path -from types import SimpleNamespace -import unittest -from unittest.mock import patch -import uuid - -from project_artifacts import validate_declaration -from project_data import decode_data_records, validate_operation_result as data_result -from project_files import ProjectFiles, decode_records as file_records, validate_operation_result as file_result -from project_fork import (ARCHIVE_FAMILIES, ProjectForkError, _digest, _input, active_records, - decode_fork, publish_fork) -from project_fork_composition import artifact_plan, build_candidate -from project_history import (capture_run, declarations as run_declarations, decode_records as history_records, - validate_operation_result as history_result) -from project_material import (ProjectMaterial, FAMILIES, _edges, _inventory, decode_records as material_records, - validate_operation_result as material_result) -from project_producers import decode_records as producer_records, _referenced_artifacts -from project_session import operation_documents, operation_records -from project_store import ProjectStore, ProjectStoreError, DIR_FLAGS -from workbench import WorkbenchError -import test_project_producers as producer_fixture -import test_project_material as material_fixture -import test_project_material_fork as material_fork_fixture -import test_project_history as history_fixture - -NOW='2026-10-22T12:00:00+00:00' - - -def declaration(sha,size): - return dict(family='project_artifact',id=sha,document=dict(format='project_artifact_v1',sha256=sha,bytes=size)) - - -def runtime_records(catalog, *, shared_sha=None, shared_bytes=1): - from recipe_process import encoded - from runtime_snapshots import descriptor - from pipeline import digest - paths={'python/bin/python3.12':'elf','systemlibs/loader':'elf','python/lib/startup.py':'data', - 'python/lib/dynload/module.so':'elf','packages/numpy/__init__.py':'data'} - files=[dict(path=path,bytes=shared_bytes if path=='packages/numpy/__init__.py' else 1, - sha256=shared_sha if path=='packages/numpy/__init__.py' and shared_sha else hashlib.sha256(path.encode()).hexdigest(), - mode=0o500 if kind=='elf' else 0o400,kind=kind) for path,kind in sorted(paths.items())] - manifest=dict(schema_version=1,profile='captured_cpu_python_v1',python_version='3.12',packages={'numpy':'0','torch':'0'}, - launch=dict(python='python/bin/python3.12',loader='systemlibs/loader',home='python',stdlib='python/lib', - dynload='python/lib/dynload',packages='packages',library_dirs=['systemlibs']), - files=files,total_bytes=sum(row['bytes'] for row in files)) - raw=encoded(manifest);sha=hashlib.sha256(raw).hexdigest() - saved=descriptor(manifest,Path('/inert/original/runtime-snapshots')/sha,catalog) - ref=dict(kind='runtime',catalog_id=catalog,id=digest(saved),sha256=digest(saved)) - inventory=[dict(name='manifest.json',sha256=sha,bytes=len(raw)), - *[dict(name=row['path'],sha256=row['sha256'],bytes=row['bytes']) for row in files]] - record=dict(family='runtime_material',id=catalog+'.'+ref['sha256'],document=dict( - format=FAMILIES['runtime_material'],origin_catalog_id=catalog,value=dict(ref=ref,descriptor=saved,environment=None,manifest=manifest), - artifacts=_edges(inventory,'runtime_material'),audit=[])) - records=[record]+[declaration(item['sha256'],item['bytes']) for item in inventory] - material_records(records) - return records,manifest,raw - - -def add_overlay(candidate,source,destination,key='composed-fork'): - origin=dict(project_id=source['project_id'],checkpoint=source['checkpoint']) - doc=dict(format='project_fork_v1',source=origin,destination_project_id=destination,request_key=key, - directory='fork',name='Composed fork',request_sha256=_digest(_input(origin,'fork','Composed fork',key)), - mapping=copy.deepcopy(candidate['mapping']),archived=copy.deepcopy(candidate['archived']), - artifacts=dict(copied=sorted(item['declaration']['sha256'] for item in candidate['artifacts'] if item['preservation']=='unique'), - missing_regenerable=sorted(item['declaration']['sha256'] for item in candidate['artifacts'] if item['preservation']=='regenerable'))) - return sorted(copy.deepcopy(candidate['records'])+[dict(family='project_fork',id=destination,document=doc)],key=lambda r:(r['family'],r['id'])) - - -class ArtifactDispositionTests(unittest.TestCase): - def setUp(self):self.catalog=uuid.uuid4().hex - - def policies(self,records):return {item['declaration']['sha256']:item['preservation'] for item in artifact_plan(records)} - - def test_runtime_files_only_are_regenerable_and_unknown_orphans_default_unique(self): - records,manifest,raw=runtime_records(self.catalog) - orphan=declaration('a'*64,123);records.append(orphan) - with patch('os.open',side_effect=AssertionError('No filesystem effects')),patch('subprocess.Popen',side_effect=AssertionError('No execution')): - policies=self.policies(records) - self.assertEqual(set(policies),{r['id'] for r in records if r['family']=='project_artifact'}) - self.assertTrue(all(policies[row['sha256']]=='regenerable' for row in manifest['files'])) - self.assertEqual(policies[hashlib.sha256(raw).hexdigest()],'unique') - self.assertEqual(policies[orphan['id']],'unique') - - def test_same_bytes_used_as_model_policy_promote_runtime_alias_to_unique(self): - value,_=material_fixture.model(self.catalog);blob=value['material']['specification'] - records,_,_=runtime_records(self.catalog,shared_sha=blob['sha256'],shared_bytes=blob['bytes']) - model=dict(family='model_material',id=self.catalog+'.'+value['ref']['sha256'],document=dict( - format=FAMILIES['model_material'],origin_catalog_id=self.catalog,value=value, - artifacts=_edges(_inventory('model_material',value),'model_material'),audit=[])) - combined={(r['family'],r['id']):r for r in records} - combined[(model['family'],model['id'])]=model - for item in _inventory('model_material',value):combined[('project_artifact',item['sha256'])]=declaration(item['sha256'],item['bytes']) - self.assertEqual(self.policies(list(combined.values()))[blob['sha256']],'unique') - - def test_data_images_bundles_and_releases_are_unique_even_with_weaker_edge_label(self): - records,manifest,_=runtime_records(self.catalog);sha=manifest['files'][0]['sha256'] - def edge(kind,role):return dict(artifact=dict(namespace=self.catalog,sha256=sha),media_type='application/octet-stream', - kind=kind,role=role,preservation='regenerable',required_for=['inspect','release']) - sources=[dict(kind='image',original=edge('image','original'),oriented=edge('image','oriented')), - dict(kind='sequence',asset=edge('sequence','original')), - dict(kind='audio',asset=edge('audio','original'))] - for source in sources: - item=dict(family='workbench_record',id=uuid.uuid4().hex,document=dict(source=source)) - self.assertEqual(self.policies(records+[item])[sha],'unique') - item=dict(family='dataset_release',id=sha,document=dict(asset=edge('release','frozen_archive'))) - self.assertEqual(self.policies(records+[item])[sha],'unique') - - def test_producer_entry_history_and_prompt_batches_cannot_weaken_runtime_alias(self): - records,manifest,_=runtime_records(self.catalog);sha=manifest['files'][0]['sha256'] - edge=dict(artifact=dict(namespace=self.catalog,sha256=sha)) - for location in ('job','entry','history','prompt'): - doc=dict(payloads={},entries=[],prompt_batches=[]) - if location=='job':doc['payloads']={'raw_response':edge} - if location=='entry':doc['entries']=[dict(payloads={'result_request':edge})] - if location=='history':doc['entries']=[dict(payloads={},history_payloads=[{'attempt_request':edge}])] - if location=='prompt':doc['prompt_batches']=[dict(payloads={'canonical_request':edge})] - with self.subTest(location=location): - item=dict(family='generation_history',id=self.catalog+'.'+uuid.uuid4().hex,document=doc) - self.assertEqual(self.policies(records+[item])[sha],'unique') - - def test_run_payload_publication_and_host_source_are_unique(self): - records,manifest,_=runtime_records(self.catalog);blob={k:manifest['files'][0][k] for k in ('sha256','bytes')} - for location in ('payload','publication','host'): - doc=dict(payloads=[],publication=None,run={}) - if location=='payload':doc['payloads']=[dict(name='weights.bin',blob=blob,preservation='regenerable')] - if location=='publication':doc['publication']=dict(source=blob,result=None) - if location=='host':doc['run']=dict(execution_kind='external_recipe',material=dict(host_files={'recipe_process.py':blob['sha256']})) - item=dict(family='run_history',id=self.catalog+'.'+uuid.uuid4().hex,document=doc) - with self.subTest(location=location):self.assertEqual(self.policies(records+[item])[blob['sha256']],'unique') - - def test_missing_unique_host_hash_is_explicit_without_invented_size(self): - missing='e'*64 - record=dict(family='run_history',id=self.catalog+'.'+uuid.uuid4().hex,document=dict(payloads=[],publication=None, - run=dict(execution_kind='external_recipe',material=dict(host_files={'recipe_process.py':missing})))) - with self.assertRaises(ProjectForkError) as caught:artifact_plan([record]) - self.assertEqual(caught.exception.code,'missing_unique') - self.assertEqual(caught.exception.missing_unique,[dict(family='run_history',id=record['id'],role='host_source',name='recipe_process.py',sha256=missing,bytes=None)]) - - def test_imported_historical_runtime_keeps_its_verified_regenerable_disposition(self): - blob=dict(sha256='a'*64,bytes=12) - edge=dict(name='runtime-files/0',blob=blob,population='unknown',role='historical_runtime', - preservation='regenerable',required_for=['scientific_inspection','execution_proof']) - doc=dict(payloads=[edge],publication=None,run=dict(execution_kind='external_recipe',material=dict( - runtime=dict(files={'/historical/runtime/dependency.py':copy.deepcopy(blob)}),host_files={}))) - record=dict(family='run_history',id=self.catalog+'.'+uuid.uuid4().hex,document=doc) - policy=self.policies([declaration(blob['sha256'],blob['bytes']),record]) - self.assertEqual(policy[blob['sha256']],'regenerable') - - def test_historical_runtime_requires_its_exact_recorded_inventory_and_role(self): - blob=dict(sha256='a'*64,bytes=12) - for mutation in ('missing-inventory','different-hash','different-bytes','different-role','explicit-unique'): - edge=dict(name='runtime-files/0',blob=copy.deepcopy(blob),population='unknown',role='historical_runtime', - preservation='regenerable',required_for=['scientific_inspection','execution_proof']) - runtime=copy.deepcopy(blob) - if mutation=='different-hash':runtime['sha256']='b'*64 - if mutation=='different-bytes':runtime['bytes']+=1 - if mutation=='different-role':edge['role']='checkpoint' - if mutation=='explicit-unique':edge['preservation']='unique' - doc=dict(payloads=[edge],publication=None,run=dict(execution_kind='external_recipe',material=dict( - runtime=dict(files={} if mutation=='missing-inventory' else {'/historical/file':runtime}),host_files={}))) - record=dict(family='run_history',id=self.catalog+'.'+uuid.uuid4().hex,document=doc) - with self.subTest(mutation=mutation): - self.assertEqual(self.policies([declaration(blob['sha256'],blob['bytes']),record])[blob['sha256']],'unique') - - def test_historical_runtime_alias_cannot_weaken_outputs_captures_proofs_or_host_sources(self): - blob=dict(sha256='a'*64,bytes=12) - for use in ('output','capture','publication','host','other-payload-first','other-payload-last'): - edge=dict(name='runtime-files/0',blob=copy.deepcopy(blob),population='unknown',role='historical_runtime', - preservation='regenerable',required_for=['scientific_inspection','execution_proof']) - doc=dict(payloads=[edge],publication=None,run=dict(execution_kind='external_recipe',artifacts=[],material=dict( - runtime=dict(files={'/historical/file':copy.deepcopy(blob)}),host_files={},captures={}))) - if use=='output':doc['run']['artifacts']=[dict(name=edge['name'],**blob)] - if use=='capture':doc['run']['material']['captures']={'capture.txt':copy.deepcopy(blob)} - if use=='publication':doc['publication']=dict(source=copy.deepcopy(blob),result=None) - if use=='host':doc['run']['material']['host_files']={'owned.py':blob['sha256']} - if use.startswith('other-payload'): - other=dict(copy.deepcopy(edge),name='weights.bin',role='checkpoint') - doc['payloads'].insert(0 if use.endswith('first') else 1,other) - record=dict(family='run_history',id=self.catalog+'.'+uuid.uuid4().hex,document=doc) - with self.subTest(use=use): - self.assertEqual(self.policies([declaration(blob['sha256'],blob['bytes']),record])[blob['sha256']],'unique') - - def test_retained_run_observation_preserves_the_same_historical_runtime_policy(self): - blob=dict(sha256='a'*64,bytes=12) - edge=dict(name='runtime-files/0',blob=blob,population='unknown',role='historical_runtime', - preservation='regenerable',required_for=['scientific_inspection','execution_proof']) - doc=dict(payloads=[edge],publication=None,run=dict(execution_kind='external_recipe',material=dict( - runtime=dict(files={'/historical/file':copy.deepcopy(blob)}),host_files={}))) - record=dict(family='run_observation',id='b'*64,document=dict(observation=doc)) - self.assertEqual(self.policies([declaration(blob['sha256'],blob['bytes']),record])[blob['sha256']],'regenerable') - - def test_native_measured_bytes_win_over_regenerable_runtime_alias_and_missing_declaration_blocks(self): - sha=hashlib.sha256(b'').hexdigest() - records,_,_=runtime_records(self.catalog,shared_sha=sha,shared_bytes=0) - self.assertEqual(self.policies(records)[sha],'regenerable') - for name,role in (('stdout.log','measured_stream'),('receipt.json','custody_proof'), - ('source/text_training.py','execution_source'),('output/weights.bin','measured_output')): - phase=dict(family='native_execution_history',id=self.catalog+'.'+uuid.uuid4().hex, - document=dict(payloads=[dict(name=name,role=role,blob=dict(sha256=sha,bytes=0), - preservation='unique',required_for=['execution_proof'])])) - with self.subTest(name=name): - self.assertEqual(self.policies(records+[phase])[sha],'unique') - with self.assertRaises(ProjectForkError) as caught: - artifact_plan([record for record in records if record['id']!=sha]+[phase]) - self.assertEqual(caught.exception.code,'missing_unique') - self.assertEqual(caught.exception.missing_unique,[dict(family=phase['family'],id=phase['id'], - role=role,name=name,sha256=sha,bytes=0)]) - - def test_intrinsic_conflicts_and_missing_known_owner_refs_refuse(self): - records,manifest,_=runtime_records(self.catalog) - with self.assertRaises((WorkbenchError,ProjectStoreError)):artifact_plan(records+[copy.deepcopy(records[-1])]) - bad=copy.deepcopy(records);bad[-1]['document']['bytes']+=1 - with self.assertRaises((WorkbenchError,ProjectStoreError)):artifact_plan(bad) - record=dict(family='workbench_record',id=uuid.uuid4().hex,document=dict(source=dict(kind='audio',asset=dict( - role='original',artifact=dict(sha256='f'*64))))) - with self.assertRaises(ProjectForkError) as caught:artifact_plan(records+[record]) - self.assertEqual(caught.exception.code,'missing_unique') - - -@unittest.skipUnless(os.environ.get('TULDOK_DATABASE_URL'),'Requires disposable PostgreSQL') -class ForkCompositionTests(unittest.TestCase): - def setUp(self): - self.fixture=producer_fixture.ProjectProducerTests('test_grounded_source_class_quotes_and_exact_response_are_one_closed_history') - self.fixture.setUp();self.addCleanup(self.fixture.doCleanups) - f=self.fixture - self.catalog=f.session.snapshot['project_id'];f.session._validate=self.validate - self.material=ProjectMaterial(f.session);self.files=ProjectFiles(f.session) - - def validate(self,records): - decode_data_records(records);material_records(records);file_records(records);producer_records(records) - history_records(records,materials=ProjectMaterial(SimpleNamespace(snapshot=dict(records=records),check_current=lambda:None))) - for receipt in operation_documents(records): - operation,result=receipt['operation'],receipt['result'] - if not (data_result(operation,result,records) or file_result(operation,result,records) - or material_result(operation,result,records) or history_result(operation,result,records)): - raise WorkbenchError('Unowned fixture receipt.') - - def commit(self,upserts): - f=self.fixture;merged={(r['family'],r['id']):r for r in f.session.snapshot['records']} - merged.update({(r['family'],r['id']):r for r in upserts}) - records=[merged[key] for key in sorted(merged)];self.validate(records) - snapshot=f.store.commit(records,f.checkpoint(),uuid.uuid4().hex,'c'*64);f.session.adopt(snapshot) - return snapshot - - def seed_material_and_files(self): - f=self.fixture;pure=material_fork_fixture.MaterialForkCodecs();pure.setUp();known=pure.known() - known['task']['catalog_id']=self.catalog - record=self.material.capture_definition('model_definition',known,f.session.snapshot['records'],action='models.create') - bound=self.material.capture_definition('recipe_definition',material_fork_fixture.recipe(self.catalog),f.session.snapshot['records'],action='recipes.create') - graph=self.material.capture_definition('pipeline_graph',material_fork_fixture.graph(),f.session.snapshot['records'],action='pipeline.create') - self.commit([record,bound,graph]) - target=f.store.path/'notes/decision.md';target.parent.mkdir();raw='Exact scientific note cafe\u0301 😀\r\n'.encode();target.write_bytes(raw) - self.files.adopt(dict(kind='note',path='notes/decision.md',expected_revision=0,expected_sha256=hashlib.sha256(raw).hexdigest()),f.checkpoint(),'adopt-note') - return record,raw - - def make(self,snapshot=None): - snapshot=snapshot or self.fixture.session.snapshot;destination=uuid.uuid4().hex - candidate=build_candidate(snapshot,destination,created_at=NOW,id_factory=lambda *key:uuid.uuid4().hex) - combined=add_overlay(candidate,snapshot,destination) - self.validate(combined);decode_fork(combined,project_id=destination) - return candidate,combined,destination - - def test_heterogeneous_real_owner_fixture_preserves_all_originals_and_fresh_fixed_drafts(self): - f=self.fixture;model,note=self.seed_material_and_files() - proposal=f.proposal();f.seed('text_classification_proposals',proposal) - self.commit(f.producers.capture_source()) - run=history_fixture.legacy_run(self.catalog);raw=b'Owned frozen input archive fixture' - sha=hashlib.sha256(raw).hexdigest();run.update(release_id=sha,release_sha256=sha,release_bytes=len(raw)) - f.artifacts.publish_bytes(raw,dict(format='project_artifact_v1',sha256=sha,bytes=len(raw))) - historical=capture_run(run,payloads=[]) - self.commit([historical,*run_declarations(historical),history_fixture.study(origin=self.catalog)]) - before=copy.deepcopy(f.session.snapshot) - with patch('os.open',side_effect=AssertionError('Pure composition opens no files')),patch('subprocess.Popen',side_effect=AssertionError('Pure composition launches nothing')): - candidate,combined,destination=self.make(before) - self.assertEqual(f.session.snapshot,before) - indexed={(r['family'],r['id']):r for r in candidate['records']} - self.assertTrue(all(indexed[(r['family'],r['id'])]==r for r in before['records'])) - archive={(r['family'],r['id']) for r in candidate['archived']} - self.assertEqual(archive,{(r['family'],r['id']) for r in before['records'] if r['family'] in ARCHIVE_FAMILIES}) - active=active_records(combined,project_id=destination) - self.assertFalse(operation_records(combined,project_id=destination)) - self.assertEqual({r['family'] for r in active},{'workbench_record','model_definition','pipeline_graph','recipe_definition','project_file', - 'project_artifact','text_proposal_history','run_history','study_history','project_fork'}) - newmodel=next(r for r in active if r['family']=='model_definition') - self.assertNotEqual(newmodel['id'],model['id']);self.assertEqual(newmodel['document']['current']['task']['catalog_id'],destination) - file=next(r for r in active if r['family']=='project_file') - self.assertEqual(file['document']['current']['text'].encode(),note) - self.assertTrue(all(item['preservation']=='unique' for item in candidate['artifacts'])) - self.assertEqual(candidate['records'],sorted(candidate['records'],key=lambda r:(r['family'],r['id']))) - self.assertEqual(candidate['mapping'],sorted(candidate['mapping'],key=lambda m:(m['family'],m['source_id'],m['source_revision'] or 0,m['destination_id']))) - - def test_nested_composition_archives_prior_overlay_and_operations_without_derived_history_growth(self): - self.seed_material_and_files();first,combined,intermediate=self.make() - snapshot=dict(project_id=intermediate,name='First fork',checkpoint='d'*64,records=combined) - second,nested,destination=self.make(snapshot) - old={(r['family'],r['id']):r for r in combined};new={(r['family'],r['id']):r for r in nested} - self.assertTrue(all(new[key]==record for key,record in old.items())) - self.assertIn(dict(family='project_fork',id=intermediate),second['archived']) - self.assertTrue(set((r['family'],r['id']) for r in first['archived'])<=set((r['family'],r['id']) for r in second['archived'])) - first_active=[r for r in active_records(combined,project_id=intermediate) if r['family'] in ('workbench_record','model_definition','recipe_definition','pipeline_graph','project_file')] - latest=[r for r in active_records(nested,project_id=destination) if r['family'] in ('workbench_record','model_definition','recipe_definition','pipeline_graph','project_file')] - self.assertEqual(len(first_active),len(latest)) - self.assertEqual(len(second['mapping']),len(first['mapping'])) - - def test_publication_copies_unique_bytes_while_missing_runtime_files_stay_explicit(self): - f=self.fixture;self.seed_material_and_files();runtime,manifest,raw=runtime_records(self.catalog) - f.artifacts.publish_bytes(raw,dict(format='project_artifact_v1',sha256=hashlib.sha256(raw).hexdigest(),bytes=len(raw))) - self.commit(runtime);source=f.session.snapshot - root=os.open(f.path,DIR_FLAGS);self.addCleanup(os.close,root) - result=publish_fork(f.store,f.artifacts,root,'independent-complete',root_path=f.path,name='Independent complete', - expected_checkpoint=source['checkpoint'],request_key='composition-publish',quiescent=True, - build_candidate=lambda snap,dest:build_candidate(snap,dest,created_at=NOW,id_factory=lambda *key:uuid.uuid4().hex), - validate_candidate=lambda records,identity:self.validate(records)) - self.assertEqual(set(result['fork']['artifacts']['missing_regenerable']),{row['sha256'] for row in manifest['files']}) - self.assertEqual(f.store.snapshot(),source) - from project_artifacts import ProjectArtifacts - with ProjectStore.open(f.path/'independent-complete') as destination,ProjectArtifacts(destination) as artifacts: - for sha in result['fork']['artifacts']['copied']: - declaration=next(r['document'] for r in destination.snapshot()['records'] if r['family']=='project_artifact' and r['id']==sha) - self.assertEqual(artifacts.status(declaration)['state'],'verified') - self.assertEqual(operation_records(destination.snapshot()['records'],project_id=destination.snapshot()['project_id']),{}) - - def test_allocator_collision_invalid_snapshot_and_destination_are_rejected(self): - self.seed_material_and_files();snapshot=self.fixture.session.snapshot - for dest,factory in [(snapshot['project_id'],lambda *key:uuid.uuid4().hex),(uuid.uuid4().hex,lambda *key:self.fixture.text['id']), - (uuid.uuid4().hex,lambda *key:'e'*32)]: - with self.subTest(destination=dest),self.assertRaises((WorkbenchError,ProjectStoreError)): - build_candidate(snapshot,dest,created_at=NOW,id_factory=factory) - bad=copy.deepcopy(snapshot);bad['records'].append(copy.deepcopy(bad['records'][0])) - with self.assertRaises((WorkbenchError,ProjectStoreError)):build_candidate(bad,uuid.uuid4().hex,created_at=NOW,id_factory=lambda *key:uuid.uuid4().hex) - - def test_revision_specific_response_mapping_and_deterministic_allocator_preserve_judgment_history(self): - f=self.fixture;parent=f.text - def change(method,*args):return method(*args,f.checkpoint(),uuid.uuid4().hex) - answers=[] - for completion in ('Exact historical answer','Other exact answer'): - answers.append(change(f.data.save_response,dict(id=uuid.uuid4().hex,prompt_id=parent['id'],revision=0, - parent_revision=1,source_revision=1,completion=completion,review='human_reviewed'))['response']) - judgment=change(f.data.save_preference,dict(id=uuid.uuid4().hex,prompt_id=parent['id'],parent_revision=1,source_revision=1, - left_id=answers[0]['id'],right_id=answers[1]['id'],left_revision=1,right_revision=1,revision=0, - outcome='left',rationale='Exact original comparison',review='human_reviewed'))['judgment'] - change(f.data.save_response,dict(id=answers[0]['id'],prompt_id=parent['id'],revision=1,parent_revision=1, - source_revision=1,completion='Later changed answer',review='human_reviewed')) - change(f.data.create_selection,dict(name='Authored membership',items=[dict(id=parent['id'],revision=1,source_revision=1)])) - source=f.session.snapshot;before=copy.deepcopy(source);destination=uuid.uuid4().hex - def allocator(family,identity,revision):return uuid.uuid5(uuid.UUID(hex=destination),family+'|'+identity+'|'+str(revision)).hex - first=build_candidate(source,destination,created_at=NOW,id_factory=allocator) - second=build_candidate(source,destination,created_at=NOW,id_factory=allocator) - self.assertEqual(first,second);self.assertEqual(source,before) - combined=add_overlay(first,source,destination);self.validate(combined) - versions=[mapping for mapping in first['mapping'] if mapping['family']=='workbench_response' and mapping['source_id']==answers[0]['id']] - self.assertEqual([m['source_revision'] for m in versions],[1,2]) - self.assertEqual(len({m['destination_id'] for m in versions}),2) - active=active_records(combined,project_id=destination) - newjudgment=next(r['document']['current'] for r in active if r['family']=='workbench_preference') - self.assertEqual(newjudgment['rationale'],judgment['rationale']);self.assertEqual(newjudgment['review'],'draft') - selected=next(r['document']['current'] for r in active if r['family']=='workbench_response' and r['id']==newjudgment['left_id']) - self.assertEqual(selected['completion'],'Exact historical answer') - membership=next(r['document']['current']['items'] for r in active if r['family']=='saved_selection') - self.assertNotEqual(membership[0]['id'],parent['id']) - self.assertEqual(membership[0]['id'],newjudgment['prompt_id']) diff --git a/tests/test_project_history.py b/tests/test_project_history.py deleted file mode 100644 index ba632ad8..00000000 --- a/tests/test_project_history.py +++ /dev/null @@ -1,825 +0,0 @@ -"""Inert history identity/closure and real PostgreSQL checkpoint boundaries.""" -import copy -import hashlib -import json -import os -from pathlib import Path -import sys -import tempfile -from types import SimpleNamespace -import unittest -from unittest.mock import patch -import uuid - -sys.path.insert(0,str(Path(__file__).resolve().parents[1])) -from access import Access -from experiments import new_study_document, validate_retained_reservation -from metadata import Metadata, connection_info -from pipeline import adapter_identity_for_graph, digest, execution_digest -from project_artifacts import ProjectArtifacts -from project_history import (FAMILY_FORMATS, HistoryFacts, ProjectHistory, capture_run, decode_records, declarations, envelope, - validate_operation_result, validate_data_exposures) -from project_session import ProjectSession -from project_store import ProjectStore -from workbench import WorkbenchError -from auth_helpers import ExplicitOwnerFixture - -ORIGIN='1'*32 -OTHER='2'*32 -MATERIAL='a'*64 - - -def policy(): - return {'format':'selection_policy_v1','metric_definition_sha256':'b'*64,'checkpoint_rule':'explicit', - 'replicate_reduce':'individual','required_capabilities':[],'numerical_acceptance':'diagnostic','tie_break':'trial_id'} - - -def study(identity='3'*32,origin=ORIGIN,trials=()): - value=new_study_document({'name':'Exact intent λ','limits':dict(attempt_slots=3,admitted_wall_seconds=100, - retained_bytes=10000,peak_staging_bytes=10000),'policy':policy()},catalog_id=origin,study_id=identity,policy_id='4'*32) - value['trial_ids']=list(trials) - return envelope('study_history',origin,identity,dict(format=FAMILY_FORMATS['study_history'],origin_catalog_id=origin, - study=value,memberships=[{'revision':1,'trial_ids':list(trials)}],policies=[{'ref':value['policy'],'policy':policy()}], - reservations=[],operations=[],revisions=[copy.deepcopy(value)],audit=[],revision_history_complete=True)) - - -def trial(identity,study_id,origin=ORIGIN,parent=None,baseline=None): - ref={'kind':'recipe_material','catalog_id':origin,'id':MATERIAL,'sha256':MATERIAL} - value={'format':'trial_v1','id':identity,'study_id':study_id,'material':ref,'replicate':0} - lineage=None - if parent is not None or baseline is not None: - intent={'ancestry':'derived' if parent else 'root','parent':parent,'baseline':baseline,'cohort':'cross-study', - 'hypothesis':'Exact saved scientific intent','change_summary':'One factor', - 'target':{'metric_id':'accuracy','metric_definition_sha256':None,'direction':'maximize','threshold':None, - 'acceptance':'Diagnostics only'}} - lineage={'format':'trial_lineage_v1','trial':{'catalog_id':origin,'trial_id':identity,'material_sha256':MATERIAL}, - 'intent':intent,'actor_id':'5'*32,'recorded_at':'2026-10-22T12:00:00+00:00','timing':'before_admission'} - return envelope('trial_history',origin,identity,dict(format=FAMILY_FORMATS['trial_history'],origin_catalog_id=origin, - trial=value,lineage=lineage)) - - -class Materials: - """Only material lookup is substituted; history/lineage validators are real.""" - def read_view(self, records): - return self - def recipe(self,ref,*,verify=False): - if ref!={'kind':'recipe_material','catalog_id':ORIGIN,'id':MATERIAL,'sha256':MATERIAL}: - raise WorkbenchError('Unknown exact fixture material.','unavailable',409) - return {'ref':copy.deepcopy(ref),'material':{'resource_envelope':dict(attempt_slots=1, - admitted_wall_seconds=10,retained_bytes=100,peak_staging_bytes=100)}} - - -def legacy_run(origin=ORIGIN): - graph={'schema_version':1,'mode':'real','id':'6'*32,'revision':1,'name':'Saved graph', - 'recipe_version':1,'nodes':[{'id':'publish','type':'publish','definition_version':1,'parameters':{}}],'edges':[]} - return {'schema_version':1,'mode':'real','id':'7'*32,'dataset_id':origin,'request_key':'old-request-0001', - 'request_sha256':'c'*64,'state':'completed','created_at':'2026-10-22T12:00:00+00:00', - 'started_at':None,'finished_at':'2026-10-22T12:01:00+00:00','graph':graph,'graph_revision':1, - 'graph_sha256':execution_digest(graph),'graph_document_sha256':digest(graph),'parameters':{}, - 'adapter':adapter_identity_for_graph(graph),'artifacts':[],'metrics':None,'attempt':1,'parent_run_id':None, - 'events':[],'error':None,'quality_claim':False,'progress':{'stage':'completed','completed':None,'total':None}, - 'node_attempts':[],'release_id':'d'*64,'release_sha256':'d'*64,'release_bytes':1,'source_records':[], - 'prior_test_exposure':{},'runtime':{},'exposure_events':[],'admission_id':'8'*32, - 'worker':{'pid':12345},'supervisor':{'pid':23456},'worker_command':['never','execute'], - 'python':'/historical/python','process_phase':'finished','release_path':'/historical/release.zip'} - - -class HistoryCodecTests(unittest.TestCase): - def test_progression_reuses_one_decoded_checkpoint_and_keeps_returned_values_independent(self): - identity='9'*32 - records=[study(trials=[identity]),trial(identity,'3'*32)] - checks=[] - session=SimpleNamespace(snapshot=dict(records=records,project_id=OTHER,checkpoint='c'*64), - summary=dict(project_id=OTHER,checkpoint='c'*64),artifacts=None, - access=SimpleNamespace(require=lambda *args,**kwargs:None), - check_current=lambda:checks.append('actual current-state guard')) - history=ProjectHistory(session,materials=Materials()) - with patch('project_history.decode_records',wraps=decode_records) as decoder: - first=history.progression(ORIGIN,offset=0,limit=20) - first['nodes'][0]['study']['name']='Caller mutation' - first['nodes'][0]['trial']['replicate']=99 - second=history.progression(ORIGIN,offset=0,limit=20) - self.assertEqual(decoder.call_count,1) - self.assertEqual(checks,['actual current-state guard']*2) - self.assertEqual(second['nodes'][0]['study']['name'],'Exact intent λ') - self.assertEqual(second['nodes'][0]['trial']['replicate'],0) - - def test_history_cache_refreshes_on_checkpoint_change_and_does_not_cache_decode_failure(self): - identity='9'*32 - records=[study(trials=[identity]),trial(identity,'3'*32)] - session=SimpleNamespace(snapshot=dict(records=records,project_id=OTHER), - summary=dict(project_id=OTHER,checkpoint='c'*64),artifacts=None, - access=SimpleNamespace(require=lambda *args,**kwargs:None),check_current=lambda:None) - history=ProjectHistory(session,materials=Materials()) - self.assertEqual(history.progression(ORIGIN)['nodes'][0]['study']['name'],'Exact intent λ') - updated=copy.deepcopy(records) - for value in (updated[0]['document']['study'],updated[0]['document']['revisions'][0]): - value['name']='New checkpoint name' - session.snapshot=dict(records=updated,project_id=OTHER) - session.summary=dict(project_id=OTHER,checkpoint='d'*64) - with patch('project_history.decode_records',side_effect=WorkbenchError('Decode unavailable','unavailable',503)): - with self.assertRaisesRegex(WorkbenchError,'Decode unavailable') as failed: - history.progression(ORIGIN) - self.assertEqual(failed.exception.code,'unavailable') - with patch('project_history.decode_records',wraps=decode_records) as decoder: - self.assertEqual(history.progression(ORIGIN)['nodes'][0]['study']['name'],'New checkpoint name') - self.assertEqual(history.progression(ORIGIN)['nodes'][0]['study']['name'],'New checkpoint name') - self.assertEqual(decoder.call_count,1) - - def test_fork_preserves_archived_disclosure_observation_without_current_permission(self): - from project_fork import _digest,_input - from project_session import operation_records - fact=dict(format='project_disclosure_v1',origin_catalog_id=ORIGIN,run_id='7'*32,payload_set_sha256='a'*64,population='all', - reason='Original explicit disclosure observation',actor_id='8'*32,occurred_at='2026-10-22T00:00:00+00:00') - key='original-disclosure' - receipt=dict(format='project_operation_v2',project_id=ORIGIN,operation='history.disclose', - target=fact['run_id'],request_key=key,input_sha256='b'*64,result=fact) - original=dict(family='project_operation',id=ORIGIN+'.'+hashlib.sha256(key.encode()).hexdigest(),document=receipt) - source=dict(project_id=ORIGIN,checkpoint='c'*64) - fork=dict(format='project_fork_v1',source=source,destination_project_id=OTHER, - request_key='fork-disclosure',request_sha256=_digest(_input(source,'copy','Copy','fork-disclosure')), - directory='copy',name='Copy',mapping=[],archived=[dict(family=original['family'],id=original['id'])], - artifacts=dict(copied=[],missing_regenerable=[])) - records=[original,dict(family='project_fork',id=OTHER,document=fork)] - calls=[] - session=SimpleNamespace(snapshot=dict(records=records,project_id=OTHER),artifacts=None, - access=SimpleNamespace(require=lambda *args,**kwargs:calls.append(args))) - history=ProjectHistory(session,materials=Materials()) - self.assertEqual(operation_records(records),{}) - self.assertEqual(history.disclosure_facts(fact['run_id'],origin_catalog_id=ORIGIN),[fact]) - self.assertEqual(history.disclosure_facts(fact['run_id'],origin_catalog_id=OTHER),[]) - self.assertEqual(calls[0],('inspect','runs.get',fact['run_id'])) - with self.assertRaisesRegex(WorkbenchError,'Current explicit disclosure'): - history._disclose(legacy_run(),'test') - - def test_cross_study_parent_baseline_and_origin_namespace_remain_exact(self): - parent_id='9'*32;child_id='a'*32 - parent_ref={'catalog_id':ORIGIN,'trial_id':parent_id,'material_sha256':MATERIAL} - records=[study('3'*32,trials=[parent_id]),study('b'*32,trials=[child_id]), - trial(parent_id,'3'*32),trial(child_id,'b'*32,parent=parent_ref,baseline=parent_ref)] - before=copy.deepcopy(records) - with patch('app.Dataset',side_effect=AssertionError('Inert decode constructed Dataset')), \ - patch('runs.Runs',side_effect=AssertionError('Inert decode constructed Runs')), \ - patch('subprocess.Popen',side_effect=AssertionError('Inert decode launched process')): - facts=decode_records(records,materials=Materials()) - self.assertEqual(facts.trials[(ORIGIN,child_id)]['lineage']['intent']['parent'],parent_ref) - self.assertEqual(records,before) - changed=copy.deepcopy(records);changed[-1]['document']['lineage']['intent']['baseline']['catalog_id']=OTHER - with self.assertRaises(WorkbenchError):decode_records(changed,materials=Materials()) - - def test_validated_fact_assembly_equals_complete_decode(self): - from project_history import assemble_validated_facts - parent_id='9'*32;child_id='a'*32 - parent_ref={'catalog_id':ORIGIN,'trial_id':parent_id,'material_sha256':MATERIAL} - saved=capture_run(legacy_run(),payloads=[]) - fixtures=( - [study('3'*32,trials=[parent_id]),study('b'*32,trials=[child_id]), - trial(parent_id,'3'*32),trial(child_id,'b'*32,parent=parent_ref,baseline=parent_ref)], - [saved,*declarations(saved)], - ) - for records in fixtures: - with self.subTest(families=sorted({r['family'] for r in records})): - decoded=decode_records(copy.deepcopy(records),materials=Materials()) - for owned in (False,True): - before=copy.deepcopy(records) - with patch('project_history._validate_run_document',side_effect=AssertionError('Validator rerun')): - assembled=assemble_validated_facts(copy.deepcopy(records) if owned else records,owned=owned) - self.assertEqual(records,before) - for field in ('studies','trials','runs','candidates','policies','reservations','observations'): - self.assertEqual(getattr(assembled,field),getattr(decoded,field),field) - self.assertEqual(list(getattr(assembled,field)),list(getattr(decoded,field)),field) - # Study authoring restore collects only Study and Trial documents. - authoring=assemble_validated_facts([r for r in copy.deepcopy(records) - if r['family'] in ('study_history','trial_history')],owned=True) - for field in ('studies','trials','policies','reservations'): - self.assertEqual(getattr(authoring,field),getattr(decoded,field),field) - - def test_history_read_uses_one_material_view_of_the_selected_records(self): - identity='9'*32 - records=[study(trials=[identity]),trial(identity,'3'*32)] - observed=[] - class Provider: - def read_view(self, selected): - observed.append(selected) - return Materials() - def recipe(self, *args, **kwargs): - raise AssertionError('History reread the live material catalog') - session=SimpleNamespace(snapshot=dict(records=records,project_id=OTHER), - summary=dict(project_id=OTHER,checkpoint='c'*64), - artifacts=None,access=SimpleNamespace(),check_current=lambda:None) - facts=ProjectHistory(session,materials=Provider())._facts() - self.assertEqual(len(observed),1) - self.assertIs(observed[0],records) - self.assertEqual(facts.trials[(ORIGIN,identity)]['trial'],records[1]['document']['trial']) - - def test_closure_omissions_cycles_and_history_completeness_are_rejected(self): - parent_id='9'*32;child_id='a'*32 - ref=lambda identity:{'catalog_id':ORIGIN,'trial_id':identity,'material_sha256':MATERIAL} - records=[study(trials=[parent_id,child_id]),trial(parent_id,'3'*32,parent=ref(child_id)), - trial(child_id,'3'*32,parent=ref(parent_id))] - with self.assertRaisesRegex(WorkbenchError,'cycle'):decode_records(records,materials=Materials()) - with self.assertRaises(WorkbenchError):decode_records(records[:-1],materials=Materials()) - value=study();value['document']['study']['revision']=2;value['document']['revisions']=[copy.deepcopy(value['document']['study'])] - with self.assertRaisesRegex(WorkbenchError,'revision gap'):decode_records([value]) - value['document']['revision_history_complete']=False - value['document']['audit']=[{'actor_id':None,'action':'studies.reconcile','target':value['document']['study']['id'], - 'details':{'state':'unknown'},'result':'interrupted','occurred_at':'2026-10-22T12:00:00+00:00'}] - self.assertFalse(decode_records([value]).studies[(ORIGIN,'3'*32)]['revision_history_complete']) - - def test_inert_run_excludes_controls_and_preserves_exact_historical_hashes(self): - run=legacy_run();saved=capture_run(run,payloads=[]) - self.assertEqual(saved['document']['run']['graph_sha256'],run['graph_sha256']) - self.assertNotIn('worker',saved['document']['run']);self.assertNotIn('worker_command',saved['document']['run']) - with patch('runs.process_status',side_effect=AssertionError('No PID observation')): - result=decode_records([saved,*declarations(saved)]) - self.assertEqual(result.runs[(ORIGIN,run['id'])]['run']['dataset_id'],ORIGIN) - changed=copy.deepcopy(saved);changed['document']['run']['worker']={'pid':1} - with self.assertRaises(WorkbenchError):decode_records([changed,*declarations(changed)]) - with self.assertRaises(WorkbenchError):capture_run(dict(run,new_unowned_field={}),payloads=[]) - - def test_missing_payload_is_declared_and_malformed_or_control_records_refuse(self): - raw=b'Unique observation\x00\xff';sha=hashlib.sha256(raw).hexdigest() - run=legacy_run();run['artifacts']=[{'name':'test-metrics.json','sha256':sha,'bytes':len(raw),'media_type':'application/json','split':'test'}] - edge={'name':'test-metrics.json','blob':{'sha256':sha,'bytes':len(raw)},'population':'test','role':'model_evidence', - 'preservation':'unique','required_for':['scientific_inspection']} - record=capture_run(run,payloads=[edge]) - declaration={'family':'project_artifact','id':sha,'document':{'format':'project_artifact_v1','sha256':sha,'bytes':len(raw)}} - self.assertEqual(len(decode_records([record,*declarations(record)]).runs),1) - with self.assertRaisesRegex(WorkbenchError,'declaration'):decode_records([record]) - for change in ({'credential':{'token':'secret'}},{'worker':None}): - changed=copy.deepcopy(record);changed['document'].update(change) - with self.assertRaises(WorkbenchError):decode_records([changed,*declarations(record)]) - - def test_operation_results_bind_historical_revision_and_reject_plausible_tamper(self): - value=study();original=copy.deepcopy(value['document']['study']) - changed=copy.deepcopy(original);changed.update(revision=2,name='Later authored name') - value['document']['study']=changed;value['document']['revisions'].append(changed) - self.assertTrue(validate_operation_result('studies.create',original,[value])) - self.assertTrue(validate_operation_result('studies.save',changed,[value])) - forged=copy.deepcopy(original);forged['name']='Plausible forged success' - self.assertTrue(validate_operation_result('studies.create',forged)) - with self.assertRaisesRegex(WorkbenchError,'retained revision'): - validate_operation_result('studies.create',forged,[value]) - parent=trial('9'*32,'3'*32);result=copy.deepcopy(parent['document']['trial']) - self.assertTrue(validate_operation_result('studies.prepare_trial',result,[parent])) - result['replicate']=1 - with self.assertRaisesRegex(WorkbenchError,'retained Trial'): - validate_operation_result('studies.prepare_trial',result,[parent]) - - def test_exposure_binds_exact_run_release_test_source_and_saved_observation(self): - run=legacy_run();run['source_records']=[{'id':'source-1','kind':'text','split':'test','content_hash':'a'*64}] - run['exposure_events']=[{'id':'e'*32,'reason':'Exact comparison','created_at':'2026-10-22T12:00:00+00:00'}] - facts=HistoryFacts();facts.runs[(ORIGIN,run['id'])]={'run':run} - exposure={'family':'dataset_exposure','id':'f'*32,'document':{'format':'dataset_exposure_v1','id':'f'*32, - 'record_id':'source-1','source_hash':'a'*64,'reason':'Exact comparison','run_id':run['id'], - 'release_id':run['release_id'],'created_at':'2026-10-22T12:00:00+00:00'}} - self.assertTrue(validate_data_exposures([exposure],facts)) - for key,value in (('run_id','8'*32),('release_id','b'*64),('source_hash','c'*64),('reason','Different reason')): - forged=copy.deepcopy(exposure);forged['document'][key]=value - with self.subTest(key=key),self.assertRaises(WorkbenchError):validate_data_exposures([forged],facts) - facts.runs[(OTHER,run['id'])]={'run':copy.deepcopy(run)} - with self.assertRaisesRegex(WorkbenchError,'unique'):validate_data_exposures([exposure],facts) - - def test_unclassified_audit_and_admission_receipt_cannot_hide_credentials(self): - value=study() - value['document']['audit']=[{'actor_id':'5'*32,'action':'access.issue','target':'6'*32, - 'details':{'token':'secret','token_sha256':'a'*64},'result':'success','occurred_at':'2026-10-22T12:00:00+00:00'}] - with self.assertRaisesRegex(WorkbenchError,'Unclassified'):decode_records([value]) - value=study();value['document']['operations']=[{'actor_id':'5'*32,'operation_id':'studies.admit', - 'request_key':'admission-0001','request_sha256':'a'*64,'result':{'token':'secret'}}] - with self.assertRaises(WorkbenchError):decode_records([value]) - value=study();value['document']['audit']=[{'actor_id':None,'action':'studies.reconcile','target':'3'*32, - 'details':{'state':'unknown','token':'secret'},'result':'interrupted','occurred_at':'2026-10-22T12:00:00+00:00'}] - with self.assertRaisesRegex(WorkbenchError,'Unclassified'):decode_records([value]) - - def test_admission_receipt_with_valid_reservation_and_nested_token_is_explicitly_unsupported(self): - from project_history import _approval - trial_value=trial('9'*32,'3'*32)['document']['trial'] - charge=Materials().recipe(trial_value['material'])['material']['resource_envelope'] - reservation={'id':'e'*32,'study_id':'3'*32,'admission_epoch':1,'request_key':'admission-0001','actor_id':'5'*32, - 'trial_id':trial_value['id'],'parent_run_id':None,'run_id':'7'*32,'request_sha256':'c'*64, - 'material_sha256':MATERIAL,'envelope':charge,'state':'settled','settled':copy.deepcopy(charge)} - run={'id':'7'*32,'actor_id':'5'*32,'request_sha256':'c'*64,'parent_run_id':None,'approval_material_sha256':MATERIAL} - validate_retained_reservation(reservation,trial=trial_value,composition=Materials().recipe(trial_value['material']),run=run) - fake={'reservation':reservation,'run':{'id':run['id'],'dataset_id':ORIGIN,'artifacts':[{'token':'secret'}]}} - with self.assertRaisesRegex(WorkbenchError,'unsupported') as error: - validate_operation_result('studies.admit',fake) - self.assertEqual(error.exception.code,'unsupported') - native=legacy_run();expected={'pipeline.inspect_release':[native['release_id']], - 'dataset_releases.locate':[native['release_id']],'pipeline.probe':['image_classification'], - 'pipeline.probe_native':['image_classification'],'pipeline.definition_identity':['image_classification'], - 'pipeline.exposures':[None],'runs.update':[native['id']]} - admission={'id':native['admission_id'],'catalog_id':ORIGIN,'actor_id':'5'*32,'credential_id':'6'*32, - 'kind':'runs','job_id':native['id'],'request_digest':native['request_sha256'],'effects':expected,'created_at':1} - proof={'grant':None,'consumption':None,'admission':admission} - self.assertIsNone(_approval(proof,native)) - bad=copy.deepcopy(proof);bad['admission']['effects']['unknown.authority']=['secret'] - with self.assertRaisesRegex(WorkbenchError,'Unclassified historical admission effects'):_approval(bad,native) - external=dict(native,execution_kind='external_recipe') - proof['admission']['effects']={'runs.update':[native['id']]} - self.assertIsNone(_approval(proof,external)) - proof['admission']['effects']['runs.update']=['9'*32] - with self.assertRaises(WorkbenchError):_approval(proof,external) - - def test_retained_receipt_and_inventory_codec_never_uses_live_runs_class(self): - import base64 - from test_builtin_artifact_sources import BuiltinArtifactSourceTests - from runs import artifact_capture_source,decode_diagnostic_json - raw,expected=BuiltinArtifactSourceTests().source() - run={'id':expected['run_id'],'dataset_id':expected['catalog_id'],'state':'completed', - 'request_sha256':expected['request_sha256'],'graph':{'recipe':'image_classification_model_v2'}, - 'graph_sha256':expected['graph_sha256'],'release_sha256':expected['release_sha256'], - 'evidence_context':{'material_sha256':expected['material_sha256'],'adapter_sha256':expected['adapter_sha256']}} - item={'name':expected['artifact_name'],'sha256':expected['measured_sha256'],'bytes':len(raw),'split':None} - proof=base64.b64decode(expected['artifact_manifest_base64']) - with patch('runs.Runs',side_effect=AssertionError('No live Runs dependency')): - self.assertEqual(artifact_capture_source(run,item,raw,proof),expected) - self.assertEqual(decode_diagnostic_json(b'{"exact":1}'),{'exact':1}) - for malformed in (b'{"exact":1,"exact":2}',b'{"exact":NaN}'): - with self.assertRaises(ValueError):decode_diagnostic_json(malformed) - with self.assertRaises(WorkbenchError):artifact_capture_source(run,item,raw+b'x',proof) - - def test_settled_charge_cannot_be_lowered_or_disconnected_from_run(self): - trial_value=trial('9'*32,'3'*32)['document']['trial'];material=Materials().recipe(trial_value['material']) - charge=material['material']['resource_envelope'] - value={'id':'e'*32,'study_id':'3'*32,'admission_epoch':1,'request_key':'reservation-0001','actor_id':'5'*32, - 'trial_id':trial_value['id'],'parent_run_id':None,'run_id':'7'*32,'request_sha256':'c'*64, - 'material_sha256':MATERIAL,'envelope':charge,'state':'settled','settled':copy.deepcopy(charge)} - run={'id':'7'*32,'actor_id':'5'*32,'request_sha256':'c'*64,'parent_run_id':None,'approval_material_sha256':MATERIAL} - self.assertEqual(validate_retained_reservation(value,trial=trial_value,composition=material,run=run),value) - changed=copy.deepcopy(value);changed['settled']['retained_bytes']=1 - with self.assertRaises(WorkbenchError):validate_retained_reservation(changed,trial=trial_value,composition=material,run=run) - - -@unittest.skipUnless(os.environ.get('TULDOK_DATABASE_URL'),'Requires disposable PostgreSQL') -class ProjectHistoryPostgresTests(unittest.TestCase): - def setUp(self): - self.tmp=tempfile.TemporaryDirectory(prefix='tuldok-history-');self.addCleanup(self.tmp.cleanup) - self.path=Path(self.tmp.name);self.databases=[];self.stores=[];self.artifact_owners=[] - self.addCleanup(self.cleanup) - self.store=ProjectStore.create(self.path/'project','Scientific history','new','f'*64);self.stores.append(self.store) - self.start() - - def cleanup(self): - import psycopg - from psycopg import sql - for artifacts in self.artifact_owners:artifacts.close() - for store in self.stores:store.close() - schemas=[] - for db in self.databases: - manifest=json.loads((db.path/'.tuldok.json').read_bytes()) - schemas.append('projection_'+manifest['projection_id'] if manifest['version']==2 else 'catalog_'+db.dataset_id) - db.close() - with psycopg.connect(connection_info(),autocommit=True) as connection: - for schema in schemas:connection.execute(sql.SQL('DROP SCHEMA IF EXISTS {} CASCADE').format(sql.Identifier(schema))) - - def start(self): - db=Metadata(self.path/('host-'+uuid.uuid4().hex),dsn=os.environ['TULDOK_DATABASE_URL']);self.databases.append(db) - host=SimpleNamespace(db=db,access=Access(db,db.path));owner=ExplicitOwnerFixture.bootstrap(host) - artifacts=ProjectArtifacts(self.store);self.artifact_owners.append(artifacts) - session=ProjectSession(self.store,db,host.access,artifacts,validate_records=lambda records:decode_records(records,materials=Materials())) - self.host,self.owner,self.session=host,owner,session - self.history=ProjectHistory(session,materials=Materials()) - - def test_cached_history_serves_verified_values_and_verification_rejects_corruption(self): - from project_store import ProjectStoreError - identity='9'*32 - records=[study(trials=[identity]),trial(identity,'3'*32)] - before=self.store.snapshot() - snapshot=self.store.commit(records,before['checkpoint'],'cache-corruption-fixture',digest(records)) - self.session.adopt(snapshot) - with self.owner.bound(self.host): - expected=self.history.progression(ORIGIN) - header=json.loads((self.store.path/'.tuldok/project.json').read_bytes()) - entry=next(item for item in header['inventory'] if item['family']=='study_history') - path=self.store.path/'.tuldok'/entry['path'] - original=path.read_bytes();info=path.stat() - corrupt=original.replace(b'Exact intent',b'Wrong intent',1) - self.assertNotEqual(corrupt,original);self.assertEqual(len(corrupt),len(original)) - try: - path.write_bytes(corrupt) - os.utime(path,ns=(info.st_atime_ns,info.st_mtime_ns)) - # Cached history keeps serving the verified value, never the - # corrupt bytes; explicit verification refuses them. - self.assertEqual(self.history.progression(ORIGIN),expected) - with self.assertRaisesRegex(ProjectStoreError,'Canonical record bytes changed or are corrupt') as failed: - self.store.verify_records() - self.assertEqual((failed.exception.code,failed.exception.status),('stale',409)) - finally: - path.write_bytes(original) - os.utime(path,ns=(info.st_atime_ns,info.st_mtime_ns)) - self.assertEqual(self.history.progression(ORIGIN),expected) - - def test_progression_uses_original_namespaces_exact_edges_and_bounded_pages(self): - parent='a'*32;child='b'*32 - ref={'catalog_id':ORIGIN,'trial_id':parent,'material_sha256':MATERIAL} - records=[study('3'*32,trials=[parent]),study('4'*32,trials=[child]), - trial(parent,'3'*32),trial(child,'4'*32,parent=ref,baseline=ref)] - before=self.store.snapshot() - captured=self.store.commit(records,before['checkpoint'],'fixture-progress',digest(records)) - self.session.adopt(captured);before=self.session.snapshot - with self.owner.bound(self.host),patch('runs.Runs',side_effect=AssertionError('No live Run owner')): - origins=self.history.progression_origins(limit=1) - self.assertEqual(origins,{'items':[{'origin_catalog_id':ORIGIN,'study_count':2,'trial_count':2}], - 'total':1,'offset':0,'limit':1}) - self.assertEqual(self.history.progression_origins(offset=1)['items'],[]) - first=self.history.progression(ORIGIN,limit=1) - self.assertEqual(first['nodes'][0]['trial'],records[2]['document']['trial']) - self.assertIsNone(first['nodes'][0]['lineage']) - self.assertEqual(first['related'],[]) - second=self.history.progression(ORIGIN,offset=1,limit=1) - self.assertEqual(second['nodes'][0]['lineage'],records[3]['document']['lineage']) - self.assertEqual(second['related'],[ref]) - self.assertEqual(second['nodes'][0]['attempt_count'],0) - self.assertFalse(second['nodes'][0]['runs_truncated']) - self.assertFalse(second['execution_available']);self.assertTrue(second['historical']) - self.assertEqual(second['evidence'],'saved_metadata_only') - both=self.history.progression(ORIGIN) - self.assertEqual(both['related'],[]) - filtered=self.history.progression(ORIGIN,cohort='cross-study') - self.assertEqual([v['trial']['id'] for v in filtered['nodes']],[child]) - self.assertEqual(self.history.progression(ORIGIN,cohort='not recorded')['nodes'],[]) - for kwargs in ({'limit':21},{'offset':True},{'cohort':''}): - with self.assertRaises(WorkbenchError):self.history.progression(ORIGIN,**kwargs) - with self.assertRaisesRegex(WorkbenchError,'origin'): - self.history.progression(self.session.snapshot['project_id']) - self.assertEqual(self.session.snapshot,before) - from access import AccessError - original_facts=self.history._facts - for operation in (self.history.progression_origins,lambda:self.history.progression(ORIGIN)): - with self.owner.bound(self.host): - inspector=self.host.access.issue({'label':'Revoked during progression read','scopes':['inspect']}) - def revoke_after_read(): - facts=original_facts() - with self.owner.bound(self.host): - self.host.access.revoke(inspector['identity']['credential_id']) - return facts - with self.host.access.bind(inspector['token']),patch.object(self.history,'_facts',side_effect=revoke_after_read): - with self.assertRaises(AccessError):operation() - for table in ('model_trials','model_studies','workspace_runs','access_admissions'): - self.assertEqual(self.host.db.execute('SELECT count(*) FROM '+table).fetchone()[0],0) - - def test_metadata_edits_cold_reopen_keep_history_without_active_authority(self): - with self.owner.bound(self.host): - before=self.session.snapshot['checkpoint'] - body={'name':'Unique hypothesis λ','limits':dict(attempt_slots=3,admitted_wall_seconds=100,retained_bytes=10000, - peak_staging_bytes=10000),'policy':policy()} - created=self.history.create_study(body,before,'create-0001') - updated=self.history.save_study(created['id'],dict(revision=1,name='Revised intent',limits=created['limits'],policy=created['policy']), - self.session.snapshot['checkpoint'],'save-0001') - self.assertEqual(updated['revision'],2) - self.assertEqual(self.history.create_study(body,before,'create-0001'),created) - snapshot=self.session.snapshot - self.artifact_owners[-1].close();self.store.close() - self.store=ProjectStore.open(self.path/'project');self.stores.append(self.store) - with patch('app.Dataset',side_effect=AssertionError('No Dataset on cold history')), \ - patch('runs.Runs',side_effect=AssertionError('No recovery owner')): - self.start() - with self.owner.bound(self.host): - self.assertEqual(self.session.snapshot,snapshot) - state=self.history.study(created['id']) - self.assertEqual(state['study'],updated) - self.assertTrue(state['revision_history_complete']) - self.assertEqual(self.store.save(snapshot['checkpoint']),snapshot) - for table in ('workspace_runs','access_execution_grants','access_execution_consumptions','access_admissions','model_operation_receipts'): - self.assertEqual(self.host.db.execute('SELECT count(*) FROM '+table).fetchone()[0],0) - - def test_trial_and_cross_study_lineage_checkpoint_preserve_previous_revision(self): - class OwnedMaterial: - def __init__(self,origin):self.origin=origin - def read_view(self,records):return self - def recipe(self,ref,*,verify=False): - self.ref=ref - if ref!={'kind':'recipe_material','catalog_id':self.origin,'id':MATERIAL,'sha256':MATERIAL}: - raise WorkbenchError('Material differs.') - return {'ref':copy.deepcopy(ref),'material':{'resource_envelope':dict(attempt_slots=1, - admitted_wall_seconds=10,retained_bytes=100,peak_staging_bytes=100)}} - origin=self.session.snapshot['project_id'];material=OwnedMaterial(origin) - self.session._validate=lambda records:decode_records(records,materials=material) - self.history=ProjectHistory(self.session,materials=material) - body={'name':'Parent Study','limits':dict(attempt_slots=3,admitted_wall_seconds=100,retained_bytes=10000, - peak_staging_bytes=10000),'policy':policy()} - with self.owner.bound(self.host): - parent_study=self.history.create_study(body,self.session.snapshot['checkpoint'],'parent-study') - child_study=self.history.create_study(dict(body,name='Separate comparison Study'),self.session.snapshot['checkpoint'],'child-study') - ref={'kind':'recipe_material','catalog_id':origin,'id':MATERIAL,'sha256':MATERIAL} - parent=self.history.prepare_trial_from_material(parent_study['id'],{'revision':1,'material':ref,'replicate':0}, - self.session.snapshot['checkpoint'],'parent-trial') - child=self.history.prepare_trial_from_material(child_study['id'],{'revision':1,'material':ref,'replicate':0}, - self.session.snapshot['checkpoint'],'child-trial') - parent_ref={'catalog_id':origin,'trial_id':parent['id'],'material_sha256':MATERIAL} - child_ref={'catalog_id':origin,'trial_id':child['id'],'material_sha256':MATERIAL} - intended=trial('a'*32,'b'*32,parent=parent_ref,baseline=parent_ref)['document']['lineage']['intent'] - value=self.history.record_lineage({'trial':child_ref,'intent':intended},self.session.snapshot['checkpoint'],'lineage-child') - self.assertEqual(value['intent']['parent'],parent_ref) - self.assertEqual(value['intent']['baseline'],parent_ref) - before=self.session.snapshot - cyclic=dict(intended,parent=child_ref,baseline=None) - with self.assertRaisesRegex(WorkbenchError,'cycle'): - self.history.record_lineage({'trial':parent_ref,'intent':cyclic},before['checkpoint'],'lineage-cycle') - self.assertEqual(self.session.snapshot,before) - self.assertEqual(self.history.study(child_study['id'])['study']['revision'],2) - self.assertEqual(self.history.trial(child['id']),child) - for table in ('model_trials','model_studies','workspace_runs','access_admissions'): - self.assertEqual(self.host.db.execute('SELECT count(*) FROM '+table).fetchone()[0],0) - - def test_missing_unique_payload_and_fresh_protected_disclosure_are_separate(self): - raw=b'Unique protected observation\x00\xff';sha=hashlib.sha256(raw).hexdigest() - declaration={'format':'project_artifact_v1','sha256':sha,'bytes':len(raw)} - run=legacy_run();run['artifacts']=[{'name':'test-metrics.json','sha256':sha,'bytes':len(raw),'media_type':'application/json','split':'test'}] - edge={'name':'test-metrics.json','blob':{'sha256':sha,'bytes':len(raw)},'population':'test','role':'model_evidence', - 'preservation':'unique','required_for':['inspection']} - record=capture_run(run,payloads=[edge]);records=[record,*declarations(record)] - self.store.commit(records,self.store.snapshot()['checkpoint'],'fixture-history','e'*64) - self.session.adopt(self.store.snapshot()) - with self.owner.bound(self.host): - self.assertEqual(self.history.run(run['id'],origin_catalog_id=ORIGIN)['payloads'][0]['availability']['state'],'missing') - with self.assertRaisesRegex(WorkbenchError,'disclosure'):self.history.artifact(run['id'],'test-metrics.json',origin_catalog_id=ORIGIN) - self.session.artifacts.publish_bytes(raw,declaration) - # A malicious portable label cannot turn a protected artifact into - # present authority. Current test filename/owner split still wins. - forged=copy.deepcopy(records);forged[0]['document']['payloads'][0]['population']='validation' - self.store.commit(forged,self.store.snapshot()['checkpoint'],'forged-label','d'*64) - self.session.adopt(self.store.snapshot()) - with self.assertRaisesRegex(WorkbenchError,'disclosure'):self.history.artifact(run['id'],'test-metrics.json',origin_catalog_id=ORIGIN) - calls=[];self.history.authorize_disclosure=lambda origin_run,population:calls.append((origin_run['dataset_id'],population)) - self.assertEqual(self.history.artifact(run['id'],'test-metrics.json',origin_catalog_id=ORIGIN),raw) - self.assertEqual(calls,[(ORIGIN,'test'),(ORIGIN,'test')]) - self.assertEqual(self.host.db.execute('SELECT count(*) FROM workspace_runs').fetchone()[0],0) - - def test_public_history_hides_frozen_holdout_and_document_segments_need_current_permission(self): - import base64 - from project_store import _encode - run=legacy_run();run['source_records']=[{'id':'frozen-example','kind':'text','split':'test', - 'text':'PRIVATE-HOLDOUT-SENTINEL','target':'PRIVATE-TARGET-SENTINEL'}] - run['evidence_context']={'fixture':'PRIVATE-CONTEXT-SENTINEL'} - record=capture_run(run,payloads=[]);records=[record,*declarations(record)] - self.store.commit(records,self.store.snapshot()['checkpoint'],'private-run-fixture','e'*64) - self.session.adopt(self.store.snapshot()) - with self.owner.bound(self.host): - result=self.history.run(run['id'],origin_catalog_id=ORIGIN,offset=0,limit=1) - self.assertNotIn('PRIVATE-',json.dumps(result)) - self.assertNotIn('source_records',result['run']);self.assertNotIn('evidence_context',result['run']) - descriptor=self.history.run_document_descriptor(run['id'],origin_catalog_id=ORIGIN) - self.assertEqual(descriptor,{'sha256':hashlib.sha256(_encode(record['document'])).hexdigest(), - 'bytes':len(_encode(record['document']))}) - with self.assertRaisesRegex(WorkbenchError,'disclosure'): - self.history.run_document_segment(run['id'],descriptor['sha256'],origin_catalog_id=ORIGIN) - self.history.authorize_disclosure=lambda *_:None - parts=[];offset=0 - while True: - segment=self.history.run_document_segment(run['id'],descriptor['sha256'],offset,limit=97,origin_catalog_id=ORIGIN) - parts.append(base64.b64decode(segment['base64'])) - if segment['next_offset'] is None:break - offset=segment['next_offset'] - self.assertEqual(b''.join(parts),_encode(record['document'])) - with self.assertRaisesRegex(WorkbenchError,'changed'): - self.history.run_document_segment(run['id'],'0'*64,origin_catalog_id=ORIGIN) - # Permission is process-local; a new owner over the same facts has none. - cold=ProjectHistory(self.session,materials=Materials()) - with self.owner.bound(self.host),self.assertRaisesRegex(WorkbenchError,'disclosure'): - cold.run_document_segment(run['id'],descriptor['sha256'],origin_catalog_id=ORIGIN) - - def test_disclosure_fact_is_actor_bound_and_never_restores_current_permission(self): - from access import AccessError - raw=b'Unique holdout observation';sha=hashlib.sha256(raw).hexdigest() - run=legacy_run();run['artifacts']=[{'name':'test-metrics.json','sha256':sha,'bytes':len(raw),'media_type':'application/json','split':'test'}] - edge={'name':'test-metrics.json','blob':{'sha256':sha,'bytes':len(raw)},'population':'test','role':'model_evidence', - 'preservation':'unique','required_for':['inspection']} - archived=capture_run(run,payloads=[edge]);records=[archived,*declarations(archived)] - self.store.commit(records,self.store.snapshot()['checkpoint'],'disclosure-fixture','d'*64) - self.session.adopt(self.store.snapshot()) - with self.owner.bound(self.host): - first=self.host.access.issue({'label':'Current disclosure authority','scopes':['inspect','expose-holdout']}) - second=self.host.access.issue({'label':'Different current actor','scopes':['inspect','expose-holdout']}) - inspect_only=self.host.access.issue({'label':'Inspect only','scopes':['inspect']}) - body={'origin_catalog_id':ORIGIN,'reason':'Compare this exact retained holdout population'} - before=self.session.snapshot['checkpoint'] - with self.host.access.bind(inspect_only['token']),self.assertRaises(AccessError): - self.history.record_disclosure(run['id'],body,before,'disclosure-0001') - with self.host.access.bind(first['token']): - fact=self.history.record_disclosure(run['id'],body,before,'disclosure-0001') - self.assertEqual(fact['actor_id'],first['identity']['actor_id']) - self.assertEqual(fact['payload_set_sha256'],self.history.payload_set_sha256(run['id'],origin_catalog_id=ORIGIN)) - self.assertEqual(self.history.record_disclosure(run['id'],body,before,'disclosure-0001'),fact) - self.assertEqual(self.history.run(run['id'],origin_catalog_id=ORIGIN)['disclosures'],[fact]) - self.assertNotIn('exposure_events',self.history.run(run['id'],origin_catalog_id=ORIGIN)['run']) - with self.host.access.bind(second['token']),self.assertRaises(WorkbenchError): - self.history.record_disclosure(run['id'],body,before,'disclosure-0001') - self.session.artifacts.publish_bytes(raw,{'format':'project_artifact_v1','sha256':sha,'bytes':len(raw)}) - with self.host.access.bind(first['token']),self.assertRaisesRegex(WorkbenchError,'disclosure'): - self.history.artifact(run['id'],'test-metrics.json',origin_catalog_id=ORIGIN) - snapshot=self.session.snapshot - self.artifact_owners[-1].close();self.store.close() - self.store=ProjectStore.open(self.path/'project');self.stores.append(self.store);self.start() - with self.owner.bound(self.host): - self.assertEqual(self.session.snapshot,snapshot) - self.assertEqual(self.history.disclosure_facts(run['id'],origin_catalog_id=ORIGIN),[fact]) - with self.assertRaisesRegex(WorkbenchError,'disclosure'): - self.history.artifact(run['id'],'test-metrics.json',origin_catalog_id=ORIGIN) - - def test_disclosure_snapshot_survives_payload_growth_and_replacement_without_new_permission(self): - from project_fork_composition import artifact_plan - run=legacy_run();run.update(state='running',finished_at=None) - run['progress']['stage']='running' - def artifact(raw,name='test-metrics.json'): - item=dict(name=name,sha256=hashlib.sha256(raw).hexdigest(),bytes=len(raw),media_type='application/json',split='test') - edge=dict(name=name,blob={k:item[k] for k in ('sha256','bytes')},population='test',role='model_evidence', - preservation='unique',required_for=['inspection']) - self.session.artifacts.publish_bytes(raw,dict(format='project_artifact_v1',**edge['blob'])) - return item,edge - old_item,old_edge=artifact(b'{"partial":1}') - run['artifacts']=[old_item] - original=capture_run(run,payloads=[old_edge]) - self.store.commit([original,*declarations(original)],self.store.snapshot()['checkpoint'],'growing-run','d'*64) - self.session.adopt(self.store.snapshot()) - body=dict(origin_catalog_id=ORIGIN,reason='Inspect the exact current observation') - with self.owner.bound(self.host),patch('runs.Runs',side_effect=AssertionError('No Run recovery in disclosure')): - first=self.history.record_disclosure(run['id'],body,self.session.snapshot['checkpoint'],'disclose-running') - self.assertEqual(first['format'],'project_disclosure_v2') - saved=copy.deepcopy(self.session.snapshot['records']) - observation=next(r for r in saved if r['family']=='run_observation') - self.assertEqual(observation['document']['observation'],original['document']) - legacy={k:v for k,v in first.items() if k!='observation_sha256'} - legacy['format']='project_disclosure_v1' - self.assertTrue(validate_operation_result('history.disclose',legacy,saved)) - replacement,replacement_edge=artifact(b'{"complete":2}') - added,added_edge=artifact(b'{"late":3}','late-output.json') - run.update(state='completed',finished_at='2026-10-22T12:01:00+00:00',artifacts=[replacement,added]) - run['progress']['stage']='completed' - grown=capture_run(run,payloads=[replacement_edge,added_edge]) - merged={(r['family'],r['id']):r for r in [*saved,grown,*declarations(grown)]} - candidate=list(merged.values()) - decode_records(candidate,materials=Materials()) - self.assertTrue(validate_operation_result('history.disclose',first,candidate)) - with self.assertRaisesRegex(WorkbenchError,'payload set'): - validate_operation_result('history.disclose',legacy,candidate) - self.store.commit(candidate,self.session.snapshot['checkpoint'],'complete-growing-run','e'*64) - self.session.adopt(self.store.snapshot()) - self.assertEqual(self.history.disclosure_facts(run['id'],origin_catalog_id=ORIGIN),[first]) - second=self.history.record_disclosure(run['id'],body,self.session.snapshot['checkpoint'],'disclose-completed') - self.assertNotEqual(second['observation_sha256'],first['observation_sha256']) - self.assertNotEqual(second['payload_set_sha256'],first['payload_set_sha256']) - # A snapshot is science evidence, never a restored local capability. - cold=ProjectHistory(self.session,materials=Materials()) - with self.assertRaisesRegex(WorkbenchError,'disclosure'): - cold.artifact(run['id'],'test-metrics.json',origin_catalog_id=ORIGIN) - current=self.session.snapshot['records'] - forged=copy.deepcopy(first);forged['payload_set_sha256']='0'*64 - with self.assertRaisesRegex(WorkbenchError,'payload set'): - validate_operation_result('history.disclose',forged,current) - foreign=copy.deepcopy(observation) - foreign['document']['observation']['run']['request_sha256']='9'*64 - from project_store import _encode as canonical - sha=hashlib.sha256(canonical(foreign['document']['observation'])).hexdigest() - foreign['id']=foreign['document']['sha256']=sha - forged=dict(first,observation_sha256=sha) - with self.assertRaisesRegex(WorkbenchError,'immutable identity'): - validate_operation_result('history.disclose',forged,[*current,foreign]) - foreign_payload=copy.deepcopy(observation) - next(edge for edge in foreign_payload['document']['observation']['payloads'] - if edge['name']=='test-metrics.json')['blob']=copy.deepcopy(added_edge['blob']) - sha=hashlib.sha256(canonical(foreign_payload['document']['observation'])).hexdigest() - foreign_payload['id']=foreign_payload['document']['sha256']=sha - # These bytes have a real global declaration, but belong to a - # different output than the observed Run inventory names here. - with self.assertRaisesRegex(WorkbenchError,'Run artifact closure'): - decode_records([*current,foreign_payload],materials=Materials()) - missing=[r for r in current if not (r['family']=='project_artifact' and r['id']==old_item['sha256'])] - with self.assertRaisesRegex(WorkbenchError,'artifact declaration'): - decode_records(missing,materials=Materials()) - # The exact old snapshot bytes stay unique even if its retained - # edge is labelled regenerable; weak labels cannot discard science. - weaker=copy.deepcopy(current) - for record in weaker: - if record['family']=='run_observation': - for edge in record['document']['observation']['payloads']:edge['preservation']='regenerable' - plan=artifact_plan(weaker) - self.assertEqual(next(v['preservation'] for v in plan if v['declaration']['sha256']==old_item['sha256']),'unique') - self.assertEqual(self.host.db.execute('SELECT count(*) FROM workspace_runs').fetchone()[0],0) - - def test_sql_analysis_uses_supplied_origin_json_and_no_active_run_row(self): - from test_retained_analysis import fixture, EVALUATION, RUN - from retained_analysis import query_history - body,evidence=fixture() - run={'id':RUN,'dataset_id':ORIGIN,'state':'completed','artifacts':[{'name':'model-evidence.json','sha256':EVALUATION}], - 'metrics':{'history':[{'epoch':1,'validation':{'accuracy':0.0,'examples':2}}, - {'epoch':2,'validation':{'accuracy':0.5,'examples':2}}]}} - with self.owner.bound(self.host): - result=query_history(self.host.db,run,evidence,body,authorize=self.host.access.require) - self.assertEqual(result['provenance']['catalog_id'],ORIGIN) - self.assertEqual([point['value'] for point in result['curve']],[0.0,0.5]) - self.assertEqual(self.host.db.execute('SELECT count(*) FROM workspace_runs').fetchone()[0],0) - - -from test_model_definitions import CapturedModelCase - - -class ProjectHistoryActualOwnerTests(CapturedModelCase): - """Actual captured composition/admission proof imported into a fresh inert DB.""" - def test_cold_actual_composed_proof_keeps_origin_without_live_authority(self): - from experiments import Experiments - from project_material import ProjectMaterial - import psycopg - from psycopg import sql - self.dataset.models=self.models - studies=Experiments(self.dataset) - with self.owner.bound(self.dataset): - model=self.models.publish(self.models.create(self.model_body)['id'],{'revision':1}) - value=studies.create({'name':'Retained exact source proof','limits':dict(attempt_slots=3, - admitted_wall_seconds=1000,retained_bytes=10**8,peak_staging_bytes=10**8),'policy':policy()}) - prepared=studies.prepare_trial(value['id'],{'request_key':'actual-history-prepare','revision':1, - 'graph_id':self.graph['id'],'graph_revision':self.graph['revision'],'model':model['ref'],'replicate':0}) - value=studies._study(value['id']) - studies.continue_study(value['id'],{'request_key':'actual-history-open','revision':value['revision'],'admission_epoch':0}) - grant=studies.approve(value['id'],{'trial_id':prepared['id'],'expected_material_sha256':prepared['material']['sha256'], - 'consumer_actor_id':self.agent['identity']['actor_id']}) - value=studies._study(value['id']) - with self.dataset.access.bind(self.agent['token']),patch.object(self.dataset.runs,'_start'): - admitted=studies.admit(value['id'],{'request_key':'actual-history-admit','revision':value['revision'], - 'admission_epoch':value['admission_epoch'],'trial_id':prepared['id'],'approval_id':grant['id']}) - with self.owner.bound(self.dataset): - self.dataset.runs.cancel(admitted['run']['id']) - run=copy.deepcopy(self.dataset.runs._load(admitted['run']['id'])) - value=studies._study(value['id']);reservation=studies._reservations(value['id'])[0] - composition=self.dataset.pipelines.recipe_material(prepared['material'],verify=True) - consumption=dict(self.dataset.db.execute('SELECT * FROM access_execution_consumptions WHERE run_id=%s',(run['id'],)).fetchone()) - admission=dict(self.dataset.db.execute('SELECT * FROM access_admissions WHERE id=%s',(run['admission_id'],)).fetchone()) - admission['effects']=json.loads(admission.pop('effects_json')) - memberships=[{'revision':row['revision'],'trial_ids':json.loads(row['document'])['trial_ids']} - for row in self.dataset.db.execute('SELECT revision,document FROM model_study_memberships WHERE study_id=%s ORDER BY revision',(value['id'],))] - root=self.path/'portable-history';store=ProjectStore.create(root,'Actual cold history','new','f'*64) - self.addCleanup(store.close) - artifacts=ProjectArtifacts(store);self.addCleanup(artifacts.close) - view=SimpleNamespace(snapshot={'project_id':store.snapshot()['project_id'],'records':[]},artifacts=artifacts,check_current=lambda:None) - material=ProjectMaterial(view) - model_record=material.capture_model_material(model,self.models.path) - recipe_record=material.capture_recipe_material(composition,self.dataset.pipelines.material_path) - runtime_ref=composition['material']['runtime'] - runtime_record=material.capture_runtime({'ref':runtime_ref,'descriptor':None,'environment':run['material']['runtime'],'manifest':None}) - records=[model_record,recipe_record,runtime_record,*material.declarations(model_record),*material.declarations(recipe_record)] - snapshot=json.loads((self.dataset.pipelines.material_path/composition['ref']['sha256']/'recipe.json').read_bytes()) - capture_map={item['path']:item['blob'] for item in snapshot['capture_paths']} - edges=[] - for name,item in run['material']['captures'].items(): - blob=capture_map[name] - raw=(self.dataset.pipelines.material_path/composition['ref']['sha256']/blob['name']).read_bytes() - declaration={'format':'project_artifact_v1','sha256':item['sha256'],'bytes':item['bytes']} - artifacts.publish_bytes(raw,declaration) - edges.append({'name':name,'blob':dict(item),'population':'unknown','role':'execution_capture', - 'preservation':'unique','required_for':['execution_proof']}) - archived=capture_run(run,admission_proof={'grant':grant,'consumption':consumption,'admission':admission},payloads=edges) - origin=self.dataset.db.dataset_id - study_doc={'format':FAMILY_FORMATS['study_history'],'origin_catalog_id':origin,'study':value,'memberships':memberships, - 'policies':[{'ref':value['policy'],'policy':policy()}],'reservations':[reservation],'operations':[], - 'revisions':[copy.deepcopy(value)],'audit':[],'revision_history_complete':False} - trial_doc={'format':FAMILY_FORMATS['trial_history'],'origin_catalog_id':origin,'trial':prepared,'lineage':None} - records.extend([envelope('study_history',origin,value['id'],study_doc), - envelope('trial_history',origin,prepared['id'],trial_doc),archived,*declarations(archived)]) - records=list({(item['family'],item['id']):item for item in records}.values()) - view.snapshot={'project_id':store.snapshot()['project_id'],'records':records} - with patch('app.Dataset',side_effect=AssertionError('No Dataset on imported history')), \ - patch('runs.Runs',side_effect=AssertionError('No imported recovery owner')), \ - patch('subprocess.Popen',side_effect=AssertionError('No imported process')): - decode_records(records,materials=material) - store.commit(records,store.snapshot()['checkpoint'],'actual-history','e'*64) - db=Metadata(self.path/'fresh-inert-db',dsn=os.environ['TULDOK_DATABASE_URL']) - self.addCleanup(db.close) - manifest=json.loads((db.path/'.tuldok.json').read_bytes()) - def remove_projection(): - db.close() - with psycopg.connect(connection_info(),autocommit=True) as connection: - connection.execute(sql.SQL('DROP SCHEMA IF EXISTS {} CASCADE').format(sql.Identifier('catalog_'+manifest['dataset_id']))) - self.addCleanup(remove_projection) - host=SimpleNamespace(db=db,access=Access(db,db.path));owner=ExplicitOwnerFixture.bootstrap(host) - session=ProjectSession(store,db,host.access,artifacts,validate_records=lambda values:decode_records(values,materials=material)) - history=ProjectHistory(session,materials=material,authorize_disclosure=lambda *_:None) - with owner.bound(host): - result=history.run(run['id'],origin_catalog_id=origin) - self.assertNotIn('spec',result['run']) - descriptor=history.run_document_descriptor(run['id'],origin_catalog_id=origin) - import base64 - parts=[];offset=0 - while True: - segment=history.run_document_segment(run['id'],descriptor['sha256'],offset,origin_catalog_id=origin) - self.assertEqual(segment['offset'],offset) - chunk=base64.b64decode(segment['base64'],validate=True);parts.append(chunk) - self.assertLessEqual(len(chunk),262144) - if segment['next_offset'] is None:break - self.assertEqual(segment['next_offset'],offset+len(chunk));offset=segment['next_offset'] - full=b''.join(parts) - self.assertEqual(len(full),descriptor['bytes']) - self.assertEqual(hashlib.sha256(full).hexdigest(),descriptor['sha256']) - self.assertEqual(json.loads(full)['run']['spec'],run['spec']) - self.assertFalse(result['execution_available']) - self.assertEqual(history.study(value['id'],origin_catalog_id=origin)['charged'],reservation['envelope']) - self.assertEqual(history.artifact(run['id'],'input/sample',origin_catalog_id=origin),self.input) - self.assertEqual(material.composition_closure(prepared['material'])['execution_material'],run['material']) - malformed=copy.deepcopy(records) - next(item for item in malformed if item['family']=='run_history')['document']['admission_proof']['consumption']['request_sha256']='0'*64 - with self.assertRaises(WorkbenchError):decode_records(malformed,materials=material) - for table in ('workspace_runs','access_admissions','access_execution_grants','access_execution_consumptions','model_operation_receipts'): - self.assertEqual(db.execute('SELECT count(*) FROM '+table).fetchone()[0],0) - - -if __name__=='__main__':unittest.main() diff --git a/tests/test_project_material.py b/tests/test_project_material.py deleted file mode 100644 index 9d69056c..00000000 --- a/tests/test_project_material.py +++ /dev/null @@ -1,523 +0,0 @@ -"""Owner codecs and canonical material custody without runtime or source execution. - -Neutral controlled source qualifies the custody fixture; it is not evidence for -current-host preflight, training, provider execution or runtime provisioning. -""" -import copy -import hashlib -import json -import math -import os -from pathlib import Path -import shutil -from types import SimpleNamespace -import tempfile -import unittest -from unittest.mock import patch -import uuid - -import agent_api -from model_definitions import ModelDefinitions, blob, decode_model_draft, decode_model_material, verify_model_closure -from pipeline import digest, decode_recipe_material, execution_digest, verify_recipe_closure -from project_artifacts import ProjectArtifacts, ProjectArtifactError, validate_declaration -from project_material import ProjectMaterial, MaterialSnapshot, decode_records, validate_operation_result -from project_store import ProjectStore -from project_session import ProjectSession, operation_records -from workbench import WorkbenchError - -SOURCE = b'raise AssertionError("retained source must never be imported")\n' - - -def definition(catalog, identity='b'*32): - return dict(format='model_draft_v1', id=identity, revision=1, name='Neutral model 山', - task=dict(kind='task',catalog_id=catalog,id='neutral.山',revision=1,sha256='a'*64), - kind='template',specification={'label':'café 山'},source_selector=None, - preprocessing_policy={'kind':'identity'},output_policy={'kind':'bytes'}) - - -def model(catalog): - draft=definition(catalog) - payloads={key+'.json':agent_api.encoded(draft[key]) for key in ('specification','preprocessing_policy','output_policy')} - payloads['source-0000.bin']=SOURCE - material=dict(format='model_material_v1',catalog_id=catalog,model_definition_id=draft['id'], - model_definition_revision=1,task=draft['task'],kind='template',entrypoint='model.py',source_selector=None, - source_closure=[dict(import_path='model.py',blob=blob(SOURCE,'source-0000.bin','application/octet-stream'))], - **{key:blob(payloads[key+'.json'],key+'.json') for key in ('specification','preprocessing_policy','output_policy')}) - ref=dict(kind='model',catalog_id=catalog,id=draft['id'],revision=1,sha256=digest(material)) - return dict(ref=ref,material=material),payloads - - -class MaterialCodecs(unittest.TestCase): - def setUp(self): - self.temporary=tempfile.TemporaryDirectory(prefix='tuldok-material-codec-') - self.addCleanup(self.temporary.cleanup);self.root=Path(self.temporary.name) - self.store=ProjectStore.create(self.root/'project','Material fixture','new-material','a'*64) - self.addCleanup(lambda:self.store.close()) - self.artifacts=ProjectArtifacts(self.store);self.addCleanup(lambda:self.artifacts.close()) - self.catalog=self.store.snapshot()['project_id'] - self.session=SimpleNamespace(snapshot=self.store.snapshot(),summary=self.store.summary(), - artifacts=self.artifacts,check_current=lambda:None) - self.material=ProjectMaterial(self.session) - - def capture(self): - value,payloads=model(self.catalog);root=self.root/'local-owner';target=root/value['ref']['sha256'];target.mkdir(parents=True) - for name,raw in payloads.items():(target/name).write_bytes(raw) - record=self.material.capture_model_material(value,root) - records=[*self.material.declarations(record),record] - return value,payloads,record,records,root - - def test_exact_unicode_hashes_source_bytes_and_closed_material_are_preserved(self): - value,payloads,record,records,root=self.capture() - self.assertNotEqual(digest(value['material']),hashlib.sha256(agent_api.encoded(value['material'])).hexdigest()) - self.assertIn(b'\\u5c71',payloads['specification.json']) - self.assertEqual(decode_model_material(value,catalog_id=self.catalog),value) - self.session.snapshot=dict(self.session.snapshot,records=records) - with patch('subprocess.Popen',side_effect=AssertionError('no process')): - self.assertEqual(self.material.model(value['ref'],verify=True),value) - self.assertEqual(self.material.blob(value['ref'],value['material']['source_closure'][0]['blob']),SOURCE) - bad=copy.deepcopy(value);bad['material']['source_closure'][0]['blob']['bytes']+=1 - with self.assertRaises(WorkbenchError):decode_model_material(bad,catalog_id=self.catalog) - bad=copy.deepcopy(record);bad['document']['artifacts'][0]['preservation']='regenerable' - with self.assertRaises(WorkbenchError):decode_records([bad]) - for malformed in (dict(record,extra=True),dict(record,document=None),dict(record,document={})): - with self.assertRaises(WorkbenchError):decode_records([malformed]) - - def test_cold_relocation_uses_canonical_artifacts_after_local_capture_deleted(self): - value,payloads,record,records,root=self.capture() - snapshot=self.store.commit(records,self.store.snapshot()['checkpoint'],'retain-material','b'*64) - self.artifacts.close();self.store.close();shutil.rmtree(root) - moved=self.root/'moved';(self.root/'project').rename(moved) - with ProjectStore.open(moved) as store,ProjectArtifacts(store) as artifacts: - material=ProjectMaterial(SimpleNamespace(snapshot=store.snapshot(),artifacts=artifacts,check_current=lambda:None)) - self.assertEqual(store.snapshot(),snapshot) - self.assertEqual(material.model(value['ref'],verify=True),value) - source=value['material']['source_closure'][0]['blob'] - self.assertEqual(material.blob(value['ref'],source),SOURCE) - (moved/'artifacts/sha256'/source['sha256']).unlink() - self.assertEqual(material.model(value['ref']),value) - with self.assertRaises(ProjectArtifactError):material.model(value['ref'],verify=True) - - def test_definition_history_is_contiguous_without_fabricating_prior_revisions(self): - first=definition(self.catalog);record=self.material.capture_definition('model_definition',first,[],action='models.create') - second=copy.deepcopy(first);second.update(revision=2,name='Changed') - updated=self.material.capture_definition('model_definition',second,[record],action='models.save') - self.assertEqual(len(updated['document']['revisions']),2) - bad=copy.deepcopy(updated);bad['document']['revisions'][0]['revision']=8 - with self.assertRaises(WorkbenchError):decode_records([bad]) - self.assertTrue(validate_operation_result('models.create',first)) - self.assertFalse(validate_operation_result('workbench.save',{})) - with self.assertRaises(WorkbenchError):validate_operation_result('models.create',dict(first,unknown=True)) - with self.assertRaises(WorkbenchError):decode_model_draft(first,catalog_id='f'*32) - graph=dict(schema_version=1,mode='real',id='d'*32,revision=1,name='Clone',recipe_version=1, - nodes=[dict(id='publish',type='publish',definition_version=1,parameters={})],edges=[]) - audit=dict(action='pipeline.clone_retained',target=graph['id'],details=dict(id='e'*32,revision=9, - material=dict(kind='recipe_material',catalog_id=self.catalog,id='c'*64,sha256='c'*64)), - result='success',actor_id='f'*32,occurred_at='2026-10-22T12:00:00+00:00') - clone=self.material.capture_definition('pipeline_graph',graph,[],action='graphs.clone',audit_facts=[audit]) - self.assertEqual(clone['document']['audit'][0],audit) - - def test_runtime_environment_is_historical_and_does_not_probe_origin_paths(self): - environment={'python':'/unavailable/original/python','packages':{'neutral':'1.0'},'definition_files':{'adapter.py':'a'*64}} - sha=digest(environment);ref=dict(kind='runtime',catalog_id=self.catalog,id=sha,sha256=sha) - record=self.material.capture_runtime(dict(ref=ref,descriptor=None,environment=environment,manifest=None)) - self.session.snapshot=dict(self.session.snapshot,records=[record]) - with patch('subprocess.Popen',side_effect=AssertionError('no process')),patch('os.stat',side_effect=AssertionError('no host paths')): - self.assertEqual(self.material.runtime(ref,verify=True)['environment'],environment) - - def test_fixed_material_snapshot_owns_input_and_returns_independent_values(self): - environment={'python':'/unavailable/original/python','packages':{'neutral':'1.0'},'definition_files':{'adapter.py':'a'*64}} - sha=digest(environment);ref=dict(kind='runtime',catalog_id=self.catalog,id=sha,sha256=sha) - original=dict(ref=ref,descriptor=None,environment=environment,manifest=None) - record=self.material.capture_runtime(original) - records=[record];view=MaterialSnapshot(records) - records[0]['document']['value']['environment']['packages']['neutral']='changed input' - value=view.runtime(ref);self.assertEqual(value,original) - value['environment']['packages']['neutral']='changed return' - self.assertEqual(view.runtime(ref),original) - with self.assertRaises(WorkbenchError):MaterialSnapshot(records) - - def test_fixed_material_snapshot_checks_complete_reference_identity(self): - environment={'python':'/unavailable/original/python','packages':{},'definition_files':{}} - sha=digest(environment);ref=dict(kind='runtime',catalog_id=self.catalog,id=sha,sha256=sha) - record=self.material.capture_runtime(dict(ref=ref,descriptor=None,environment=environment,manifest=None)) - view=MaterialSnapshot([record]) - for change in ({'catalog_id':'f'*32},{'sha256':'f'*64},{'id':'f'*64},{'kind':'recipe_material'}): - with self.assertRaises(WorkbenchError):view.runtime(dict(ref,**change)) - - def test_invalid_live_material_reference_precedes_snapshot_access(self): - with patch.object(self.session,'check_current',side_effect=AssertionError('Invalid reference accessed snapshot')): - with self.assertRaises(WorkbenchError):self.material.runtime({'catalog_id':'invalid'}) - - def test_material_read_view_uses_supplied_records_without_resnapshotting(self): - environment={'python':'/unavailable/original/python','packages':{},'definition_files':{}} - sha=digest(environment);ref=dict(kind='runtime',catalog_id=self.catalog,id=sha,sha256=sha) - original=dict(ref=ref,descriptor=None,environment=environment,manifest=None) - records=[self.material.capture_runtime(original)] - self.assertEqual(self.session.snapshot['records'],[]) - view=self.material.read_view(records) - self.assertEqual(view.runtime(ref),original) - self.assertEqual(self.session.snapshot['records'],[]) - - def test_material_read_view_rechecks_session_availability(self): - with patch.object(self.session,'check_current',side_effect=WorkbenchError('Stale checkpoint.','stale',409)): - with self.assertRaisesRegex(WorkbenchError,'Stale checkpoint'): - self.material.read_view([]) - - def test_operation_result_requires_exact_retained_revision_or_material(self): - first=definition(self.catalog);record=self.material.capture_definition('model_definition',first,[],action='models.create') - changed=copy.deepcopy(first);changed.update(revision=2,name='Changed') - history=self.material.capture_definition('model_definition',changed,[record],action='models.save') - self.assertTrue(validate_operation_result('models.create',first,[history])) - self.assertTrue(validate_operation_result('models.save',changed,[history])) - forged=dict(changed,name='Well-formed invented receipt') - with self.assertRaises(WorkbenchError):validate_operation_result('models.save',forged,[history]) - with self.assertRaises(WorkbenchError):validate_operation_result('models.create',changed,[history]) - value,payloads,immutable,records,root=self.capture() - self.assertTrue(validate_operation_result('models.publish',value,records)) - with self.assertRaises(WorkbenchError):validate_operation_result('models.publish',value,[history]) - self.assertFalse(validate_operation_result('source.register',{},records)) - - def test_action_specific_audit_details_refuse_authority_before_projection(self): - value=definition(self.catalog) - retained=self.material.capture_definition('model_definition',value,[],action='models.create') - variants=[dict(token_sha256='a'*64),dict(credential={'token':'never-import'}), - dict(document_sha256={'token':'never-import'}),dict(revision=True),dict(document_sha256='f'*64)] - with patch('model_definitions.ModelDefinitions',side_effect=AssertionError('No owner construction')): - for fields in variants: - bad=copy.deepcopy(retained);bad['document']['audit'][0]['details'].update(fields) - with self.subTest(fields=fields),self.assertRaises(WorkbenchError):decode_records([bad]) - bad=copy.deepcopy(retained);bad['document']['audit'][0]['action']='access.issue' - with self.assertRaises(WorkbenchError):decode_records([bad]) - - def test_captured_runtime_manifest_binding_and_explicit_reader_never_read_old_root(self): - from recipe_process import encoded,validate_cpu_snapshot_manifest - from runtime_snapshots import descriptor - paths={'python/bin/python3.12':'elf','systemlibs/loader':'elf','python/lib/startup.py':'data', - 'python/lib/dynload/module.so':'elf','packages/numpy/__init__.py':'data'} - manifest=dict(schema_version=1,profile='captured_cpu_python_v1',python_version='3.12',packages={'numpy':'0','torch':'0'}, - launch=dict(python='python/bin/python3.12',loader='systemlibs/loader',home='python',stdlib='python/lib', - dynload='python/lib/dynload',packages='packages',library_dirs=['systemlibs']), - files=[dict(path=path,bytes=1,sha256='a'*64,mode=0o500 if kind=='elf' else 0o400,kind=kind) for path,kind in sorted(paths.items())], - total_bytes=len(paths)) - raw=encoded(manifest);sha=hashlib.sha256(raw).hexdigest() - saved=descriptor(manifest,Path('/original-missing/runtime-snapshots')/sha,self.catalog) - runtime_sha=digest(saved);ref=dict(kind='runtime',catalog_id=self.catalog,id=runtime_sha,sha256=runtime_sha) - value=dict(ref=ref,descriptor=saved,environment=None,manifest=manifest) - with patch('recipe_process._cpu_open_root',side_effect=AssertionError('No old runtime root')), \ - patch('subprocess.Popen',side_effect=AssertionError('No process')): - record=self.material.capture_runtime(value,raw) - self.session.snapshot=dict(self.session.snapshot,records=[*self.material.declarations(record),record]) - self.assertEqual(self.material.runtime(ref,verify=True),value) - changed=copy.deepcopy(saved);changed['file_count']+=1 - with self.assertRaises(ValueError):validate_cpu_snapshot_manifest(changed,manifest) - snapshot=encoded(dict(format='external_recipe_snapshot_v1',preflight={'material':{'runtime':{},'cpu_snapshot':saved}})) - recipe_blob=blob(snapshot,'recipe.json') - self.artifacts.publish_bytes(snapshot,dict(format='project_artifact_v1',sha256=recipe_blob['sha256'],bytes=len(snapshot))) - recipe_record=dict(document={'value':{'material':{'runtime':ref,'recipe_document':recipe_blob}}}) - seen=[] - def supplied(descriptor):seen.append(descriptor);return raw - dependencies=self.material.capture_recipe_dependencies(recipe_record,[],runtime_manifest=supplied) - self.assertEqual(seen,[saved]);self.assertEqual(dependencies[-1],record) - with self.assertRaises(WorkbenchError):self.material.capture_recipe_dependencies(recipe_record,[]) - (self.root/'project/artifacts/sha256'/sha).unlink() - with self.assertRaises(ProjectArtifactError):self.material.capture_recipe_dependencies(recipe_record,dependencies) - restored=self.material.capture_recipe_dependencies(recipe_record,dependencies,runtime_manifest=supplied) - self.assertEqual(restored[-1],record) - self.assertEqual(self.material.runtime(ref,verify=True),value) - - def test_legacy_activity_path_is_retained_without_becoming_a_current_manifest(self): - from projects import manifest as current_manifest, decode_retained_snapshot - manifest = dict(schema_version=1, id='c'*32, name='Archived activity', - data=[], recipes=[], evidence=[], requirements=[], activity_path='old/activity.json') - raw = (json.dumps(manifest, indent=3)+'\n\n').encode() - saved = dict(id=manifest['id'], name=manifest['name'], root='gone', root_identity=[1,2], - manifest_path='original.json', manifest_sha256=hashlib.sha256(raw).hexdigest(), manifest=manifest) - with self.assertRaises(WorkbenchError): current_manifest(manifest) - with patch('subprocess.Popen', side_effect=AssertionError('Retained activity is inert')): - self.assertEqual(decode_retained_snapshot(saved),saved) - record=self.material.capture_snapshot(saved,raw,catalog_id=self.catalog) - self.session.snapshot=dict(self.session.snapshot,records=[*self.material.declarations(record),record]) - self.assertEqual(self.material.snapshot_ref(manifest['id'],saved['manifest_sha256'],verify=True),saved) - documents=decode_records(self.session.snapshot['records']) - self.assertEqual(documents[('project_snapshot',self.catalog+'.'+saved['manifest_sha256'])]['value'],saved) - for bad_path in ('../escape.json','/absolute.json','a\\b.json',False): - bad=copy.deepcopy(saved);bad['manifest']['activity_path']=bad_path - with self.assertRaises(WorkbenchError): decode_retained_snapshot(bad) - bad=copy.deepcopy(saved);bad['manifest']['unknown_activity_field']='anything' - with self.assertRaises(WorkbenchError): decode_retained_snapshot(bad) - - def test_original_snapshot_manifest_whitespace_is_not_reserialized_for_identity(self): - manifest=dict(schema_version=1,id='c'*32,name='Snapshot',data=[],recipes=[],evidence=[],requirements=[]) - import json - raw=(json.dumps(manifest,indent=3,ensure_ascii=False)+'\n\n').encode() - saved=dict(id=manifest['id'],name=manifest['name'],root='old-root',root_identity=[7,9],manifest_path='project.json', - manifest_sha256=hashlib.sha256(raw).hexdigest(),manifest=manifest) - record=self.material.capture_snapshot(saved,raw,catalog_id=self.catalog) - self.session.snapshot=dict(self.session.snapshot,records=[*self.material.declarations(record),record]) - self.assertEqual(self.material.snapshot_ref(manifest['id'],saved['manifest_sha256'],verify=True),saved) - rebound=dict(saved,root='explicit-current-root',root_identity=[11,13],manifest_path='moved.json') - self.assertEqual(self.material.capture_snapshot(rebound,raw,catalog_id=self.catalog),record) - with self.assertRaises(WorkbenchError):self.material.capture_snapshot(saved,agent_api.encoded(manifest),catalog_id=self.catalog) - - def test_builtin_recipe_closure_uses_frozen_validation_without_current_host_qualification(self): - import one_fit_evidence - import text_training - from workbench import encode - value,payloads=model(self.catalog) - parameters={key:rule['default'] for key,rule in text_training.PARAMETER_BOUNDS.items()} - owner=one_fit_evidence.contract(text_training);definition=owner.model_definition(parameters) - body=value['material'];body['task']=owner.task_ref(self.catalog) - for key in ('specification','preprocessing_policy','output_policy'): - raw=agent_api.encoded(definition[key]);payloads[key+'.json']=raw;body[key]=blob(raw,key+'.json') - value['ref']['sha256']=digest(body) - graph=dict(schema_version=1,mode='real',id='e'*32,revision=1,name='Frozen recipe λ',recipe_version=1, - recipe=text_training.MODEL_RECIPE,nodes=[dict(id='train',type='train',definition_version=1,parameters=parameters)],edges=[]) - runtime=dict(python='/original/now-missing',definition_files={'model.py':hashlib.sha256(SOURCE).hexdigest()}) - release=dict(id='f'*64,sha256='f'*64,split_counts={'validation':1}) - validation=dict(valid=True,execution_sha256=execution_digest(graph),runtime=runtime,release=release) - item=blob(SOURCE,'capture-0000.bin','application/octet-stream') - snapshot=dict(format='builtin_recipe_snapshot_v1',graph=graph,validation=validation,model_definition=definition, - capture_paths=[dict(path='model.py',blob=item)]) - profile=owner.profile(self.catalog,value['ref']['sha256'],parameters,1) - recipe_payloads={'capture-0000.bin':SOURCE,'recipe.json':encode(snapshot).encode(),'profile.json':encode(profile).encode()} - composition=dict(format='recipe_material_v1',catalog_id=self.catalog,recipe_id=graph['id'],recipe_revision=1, - recipe_document=blob(recipe_payloads['recipe.json'],'recipe.json'),executable_sha256=validation['execution_sha256'], - model=value['ref'],data=[dict(kind='release',catalog_id=self.catalog,id=release['id'],sha256=release['sha256'])], - trainer=dict(kind='trainer',catalog_id=self.catalog,id=text_training.MODEL_ADAPTER['name']+'_v2',revision=2,sha256=digest(text_training.MODEL_ADAPTER)), - evaluation_profile=profile['definition'],resolved_profile=blob(recipe_payloads['profile.json'],'profile.json'), - runtime=dict(kind='runtime',catalog_id=self.catalog,id=digest(runtime),sha256=digest(runtime)),captures=[item], - resource_envelope=dict(attempt_slots=1,admitted_wall_seconds=1,retained_bytes=1,peak_staging_bytes=1)) - sha=digest(composition);retained=dict(ref=dict(kind='recipe_material',catalog_id=self.catalog,id=sha,sha256=sha),material=composition) - def read(ref,item,maximum):return (payloads if ref['kind']=='model' else recipe_payloads)[item['name']] - with patch('pipeline.Pipelines.validate_graph',side_effect=AssertionError('No current host qualification')), \ - patch('subprocess.Popen',side_effect=AssertionError('No process')): - closure=verify_recipe_closure(retained,value,read_blob=read) - self.assertEqual(closure['execution_material'],validation) - for name,raw in recipe_payloads.items(): - item=next(item for item in [composition['recipe_document'],composition['resolved_profile'],*composition['captures']] if item['name']==name) - self.artifacts.publish_bytes(raw,dict(format='project_artifact_v1',sha256=item['sha256'],bytes=item['bytes'])) - dependencies=self.material.capture_recipe_dependencies(dict(document={'value':retained}),[]) - self.assertEqual(dependencies[-1]['document']['value']['environment'],runtime) - self.assertEqual(self.material.capture_recipe_dependencies(dict(document={'value':retained}),dependencies),[]) - recipe_root=self.root/'retained-recipe';target=recipe_root/retained['ref']['sha256'];target.mkdir(parents=True) - for name,raw in recipe_payloads.items():(target/name).write_bytes(raw) - record=self.material.capture_recipe_material(retained,recipe_root) - view=MaterialSnapshot([record,*dependencies]) - self.assertEqual(view.recipe(retained['ref']),retained) - expected=[edge['blob'] for item in [record,*dependencies] for edge in item['document']['artifacts']] - self.assertEqual(list(view.artifact_blobs()),expected) - changed=list(view.artifact_blobs());changed[0]['bytes']+=1 - self.assertEqual(list(view.artifact_blobs()),expected) - for field,replacement in (('data',{}),('executable_sha256','wrong'),('captures',[dict(item,media_type='text/plain')])): - bad=copy.deepcopy(retained);bad['material'][field]=replacement - changed=digest(bad['material']);bad['ref'].update(id=changed,sha256=changed) - with self.assertRaises(WorkbenchError):decode_recipe_material(bad,catalog_id=self.catalog) - changed=dict(recipe_payloads,**{'profile.json':b'{}'}) - with self.assertRaises(WorkbenchError):verify_recipe_closure(retained,value,read_blob=lambda ref,item,maximum:(payloads if ref['kind']=='model' else changed)[item['name']]) - - -class EvidenceCallbacks(unittest.TestCase): - def test_retained_one_fit_readers_match_directory_without_source_paths_or_inference(self): - """Controlled observations test custody/semantics, not a trained model.""" - import audio_training - import text_training - import one_fit_evidence as evidence - for adapter in (text_training,audio_training): - with self.subTest(adapter=adapter.ADAPTER['name']),tempfile.TemporaryDirectory() as temporary: - root=Path(temporary);catalog='1'*32;owner=evidence.contract(adapter) - parameters={name:rule['default'] for name,rule in adapter.PARAMETER_BOUNDS.items()} - context=dict(material_sha256='c'*64,adapter_sha256='e'*64,model_sha256='d'*64, - profile=owner.profile(catalog,'d'*64,parameters,1)) - records=[] - for index,split in enumerate(('train','validation')): - record={key:'a'*64 for key in adapter.REFERENCE_KEYS} - record.update(id=str(index+2)*32,revision=1,source_revision=1,split=split,class_index=0, - text='Frozen validation text λ',content_hash='b'*64,sample_rate_hz=8000,channels=1, - channel=0,start_frame=0,end_frame=16) - records.append(record) - clocks=evidence.fit_clocks(.125) - validation=dict(examples=1,loss=-math.log(.75),accuracy=1.0,macro_f1=.5,confusion_matrix=[[1,0],[0,0]]) - metrics=dict(class_vocabulary=['left','right'],validation=validation,clocks=clocks) - run=dict(id='f'*32,dataset_id=catalog,graph_sha256='b'*64,release_id='a'*64,release_sha256='a'*64, - parameters=parameters,adapter=dict(adapter.ADAPTER,version=2),evidence_context=context, - source_records=records,metrics=metrics,graph={'recipe':adapter.MODEL_RECIPE}) - job=evidence.job_for_run(run) - saved=dict(adapter=run['adapter'],parameters=parameters,transform=adapter.TRANSFORM, - class_vocabulary=metrics['class_vocabulary'],source_identity={key:job[key] - for key in ('dataset_id','run_id','graph_sha256','release_id','release_sha256')}) - saved.update(dict(vocabulary={'frozen':0},idf=[1.0]) if adapter is text_training else dict(mean=[0.0]*8,scale=[1.0]*8)) - inputs=[records[1]['text']] if adapter is text_training else [[0.0]*8] - for name,body in (('model.json',saved),('metrics.json',metrics)): - (root/name).write_text(json.dumps(body,ensure_ascii=False)) - evidence.capture(root,job=job,adapter=adapter.ADAPTER, - manifest=dict(records=records,class_vocabulary=metrics['class_vocabulary']), - reference_keys=adapter.REFERENCE_KEYS,saved=saved,inputs=inputs,validation=validation, - rows=[dict(truth_index=0,predicted_index=0,probabilities=[.75,.25])],clocks=clocks) - payloads={path.name:path.read_bytes() for path in root.iterdir()} - run['artifacts']=[dict(name=name,sha256=hashlib.sha256(raw).hexdigest(),bytes=len(raw),media_type='application/json') - for name,raw in payloads.items()] - with patch('text_training.predict_model',side_effect=AssertionError('No inference')), \ - patch('audio_training.predict_features',side_effect=AssertionError('No inference')), \ - patch('subprocess.Popen',side_effect=AssertionError('No process')): - expected=evidence.verify(root,run,metrics) - self.assertEqual(evidence.verify_blobs(run,metrics,read_blob=lambda name,maximum:payloads[name]),expected) - material=ProjectMaterial(SimpleNamespace(check_current=lambda:None)) - result=material.evidence(run,read_blob=lambda name,maximum:payloads[name]) - self.assertEqual(result['state'],'verified') - checkpoint=result['checkpoint_index']['entries'][0]['checkpoint']['sha256'] - selected=material.evidence(run,{'checkpoint_sha256':checkpoint},read_blob=lambda name,maximum:payloads[name]) - self.assertEqual(selected['checkpoint'],expected[1][0]) - self.assertEqual(selected['predictions'],expected[2][0]) - corrupted=dict(payloads,**{'probe-inputs.json':b'{}'}) - with self.assertRaises(WorkbenchError):material.evidence(run,read_blob=lambda name,maximum:corrupted[name]) - - -@unittest.skipUnless(os.environ.get('TULDOK_DATABASE_URL'),'Requires disposable PostgreSQL') -class CanonicalPublication(unittest.TestCase): - def setUp(self): - from metadata import Metadata - from access import Access - from auth_helpers import ExplicitOwnerFixture - self.temporary=tempfile.TemporaryDirectory(prefix='tuldok-material-session-');self.path=Path(self.temporary.name) - self.schemas=[];self.resources=[];self.addCleanup(self.temporary.cleanup);self.addCleanup(self.cleanup) - self.store=ProjectStore.create(self.path/'project','Canonical models','new','a'*64);self.resources.append(self.store) - self.artifacts=ProjectArtifacts(self.store);self.resources.append(self.artifacts) - self.host=Metadata(self.path/'host');self.resources.append(self.host);self.schemas.append(self.host.schema) - self.access=Access(self.host,self.host.path);self.owner=ExplicitOwnerFixture.bootstrap(SimpleNamespace(db=self.host,access=self.access)) - self.db=Metadata(self.path/'projection',dataset_id=self.store.snapshot()['project_id'],projection_id=uuid.uuid4().hex) - self.resources.append(self.db);self.schemas.append(self.db.schema) - self.session=ProjectSession(self.store,self.db,self.access,self.artifacts,validate_records=self.validate) - self.material=ProjectMaterial(self.session) - qualification=SimpleNamespace(model_template=lambda draft:('model.py',{'model.py':SOURCE})) - self.dataset=SimpleNamespace(db=self.db,access=self.material.owner_access,lock=self.db.lock,path=self.db.path,pipelines=qualification) - self.models=ModelDefinitions(self.dataset) - - def cleanup(self): - import psycopg - from psycopg import sql - from metadata import connection_info - for resource in reversed(self.resources):resource.close() - with psycopg.connect(connection_info(),autocommit=True) as db: - for schema in self.schemas:db.execute(sql.SQL('DROP SCHEMA IF EXISTS {} CASCADE').format(sql.Identifier(schema))) - - def validate(self,records): - decode_records(records) - for record in records: - if record['family']=='project_artifact':validate_declaration(record['document']) - for receipt in operation_records(records).values(): - if not validate_operation_result(receipt['operation'],receipt['result']):raise AssertionError('unowned fixture receipt') - - def create(self): - draft=definition(self.db.dataset_id) - body={key:value for key,value in draft.items() if key not in ('format','id','revision')} - return self.material.mutate_definition('model_definition','models.create',None,body,self.session.snapshot['checkpoint'],uuid.uuid4().hex,lambda:self.models.create(body)) - - def test_model_publication_is_canonical_before_ack_and_has_one_session_receipt(self): - with self.access.bind(self.owner.token): - draft=self.create();value=self.material.publish_model(self.models,draft['id'],{'revision':1},self.session.snapshot['checkpoint'],'publish-neutral') - self.assertEqual(self.material.model(value['ref'],verify=True),value) - records=self.store.snapshot()['records'] - self.assertEqual({record['family'] for record in records},{'project_artifact','project_operation','model_definition','model_material'}) - self.assertNotIn('operations',next(item['document'] for item in records if item['family']=='model_definition')) - replay=self.material.publish_model(self.models,draft['id'],{'revision':1},'0'*64,'publish-neutral') - self.assertEqual(replay,value) - original=next(item for item in records if item['family']=='model_material') - again=self.material.publish_model(self.models,draft['id'],{'revision':1},self.session.snapshot['checkpoint'],'publish-again') - self.assertEqual(again,value) - self.assertEqual(next(item for item in self.store.snapshot()['records'] if item['family']=='model_material'),original) - - def test_agent_publish_preserves_legacy_edit_scope_and_owner_reconcile_guard_precedes_replay(self): - from access import AccessError - with self.access.bind(self.owner.token): - agent=self.access.issue({'label':'Material editor','scopes':['inspect','edit']}) - with self.access.bind(agent['token']): - draft=self.create();value=self.material.publish_model(self.models,draft['id'],{'revision':1},self.session.snapshot['checkpoint'],'agent-publication') - self.assertEqual(self.material.model(value['ref'],verify=True),value) - with self.access.bind(self.owner.token): - self.material.publish_model(self.models,draft['id'],{'revision':1,'reconcile_capture':True},self.session.snapshot['checkpoint'],'owner-reconcile-receipt') - stable=self.store.snapshot() - with self.access.bind(agent['token']): - with self.assertRaises(AccessError):self.material.publish_model(self.models,draft['id'],{'revision':1,'reconcile_capture':True},'0'*64,'owner-reconcile-receipt') - self.assertEqual(self.store.snapshot(),stable) - - def test_real_deferred_sql_failure_cannot_delete_canonical_source_material(self): - with self.access.bind(self.owner.token): - draft=self.create() - self.db.execute("CREATE FUNCTION fixture_refuse_material() RETURNS trigger LANGUAGE plpgsql AS $$ BEGIN RAISE EXCEPTION 'controlled material commit rejection' USING ERRCODE='23514'; END; $$") - self.db.execute('CREATE CONSTRAINT TRIGGER fixture_material_failure AFTER INSERT ON model_materials DEFERRABLE INITIALLY DEFERRED FOR EACH ROW EXECUTE FUNCTION fixture_refuse_material()') - with self.assertRaises(WorkbenchError) as error: - self.material.publish_model(self.models,draft['id'],{'revision':1},self.session.snapshot['checkpoint'],'canonical-before-sql') - self.assertEqual(error.exception.code,'projection_unavailable') - snapshot=self.store.snapshot();retained=next(item for item in snapshot['records'] if item['family']=='model_material')['document']['value'] - self.assertFalse((self.models.path/retained['ref']['sha256']).exists(),'Legacy rollback removes only disposable projection cache') - cold=ProjectMaterial(SimpleNamespace(snapshot=snapshot,artifacts=self.artifacts,check_current=lambda:None)) - self.assertEqual(cold.model(retained['ref'],verify=True),retained) - self.assertEqual(cold.blob(retained['ref'],retained['material']['source_closure'][0]['blob']),SOURCE) - - def test_restore_is_inert_and_explicit_preparation_rebuilds_only_projection_cache(self): - from metadata import Metadata - from model_definitions import retained_json - with self.access.bind(self.owner.token): - draft=self.create();value=self.material.publish_model(self.models,draft['id'],{'revision':1},self.session.snapshot['checkpoint'],'cold-model') - cold_db=Metadata(self.path/'cold-projection',dataset_id=self.db.dataset_id,projection_id=uuid.uuid4().hex) - self.resources.append(cold_db);self.schemas.append(cold_db.schema) - cold=ProjectMaterial(SimpleNamespace(snapshot=self.store.snapshot(),artifacts=self.artifacts,db=cold_db,check_current=lambda:None)) - with patch('model_definitions.ModelDefinitions',side_effect=AssertionError('No mutable owner on Open')), \ - patch('pipeline.Pipelines',side_effect=AssertionError('No mutable owner on Open')), \ - patch('subprocess.Popen',side_effect=AssertionError('No process')): - cold.restore() - self.assertEqual(retained_json(cold_db.execute('SELECT document FROM model_definition_drafts WHERE id=%s',(draft['id'],)).fetchone()[0]),draft) - self.assertEqual(retained_json(cold_db.execute('SELECT document FROM model_materials WHERE sha256=%s',(value['ref']['sha256'],)).fetchone()[0]),value) - cache=cold.materialize_projection(value['ref'],cold_db.path/'model-materials') - self.assertEqual((cache/'source-0000.bin').read_bytes(),SOURCE) - shutil.rmtree(cache) - with self.assertRaises(WorkbenchError):cold.materialize_projection(value['ref'],self.path/'not-a-projection') - self.assertEqual(cold.model(value['ref'],verify=True),value) - - def test_builtin_prepare_execution_gate_precedes_owner_probe_cache_and_artifact_changes(self): - from pipeline import Pipelines - with self.access.bind(self.owner.token): - draft=self.create();value=self.material.publish_model(self.models,draft['id'],{'revision':1},self.session.snapshot['checkpoint'],'gate-model') - self.dataset.models=self.models - pipelines=Pipelines(self.dataset) - shutil.rmtree(self.models.path/value['ref']['sha256']) - snapshot=self.store.snapshot() - payloads={path.name:path.read_bytes() for path in (self.store.path/'artifacts/sha256').iterdir()} - with patch('subprocess.Popen',side_effect=AssertionError('Built-in probe must be fenced')) as processes, \ - patch.object(pipelines,'prepare_builtin_material',side_effect=AssertionError('Owner preparation must not begin')) as prepare: - with self.assertRaises(WorkbenchError) as error: - self.material.prepare_recipe(pipelines,'a'*32,1,value['ref'],snapshot['checkpoint'],'builtin-gate',builtin=True) - self.assertEqual(error.exception.code,'unavailable') - self.assertIn('runtime probe',str(error.exception)) - processes.assert_not_called();prepare.assert_not_called() - self.assertEqual(self.store.snapshot(),snapshot) - self.assertEqual({path.name:path.read_bytes() for path in (self.store.path/'artifacts/sha256').iterdir()},payloads) - self.assertFalse(list(self.models.path.iterdir()));self.assertFalse(list(pipelines.material_path.iterdir())) - - -from test_model_definitions import CapturedModelCase - - -@unittest.skipUnless(os.environ.get('TULDOK_DATABASE_URL'),'Requires disposable PostgreSQL') -class OpaqueCompositionReaderTests(CapturedModelCase): - def test_profile_reader_remains_callable_after_exact_opaque_source_validation(self): - from model_definitions import read_owned_blob - self.dataset.models=self.models - with self.owner.bound(self.dataset): - published=self.publish(self.create()) - prepared=self.dataset.pipelines.prepare_external_material(self.graph['id'],self.graph['revision'],published['ref']) - with self.dataset.db.transaction(): - composition=self.dataset.pipelines._retain_material(prepared) - reads=[] - def read(ref,item,maximum): - reads.append((ref['kind'],item['name'])) - root=self.models.path if ref['kind']=='model' else self.dataset.pipelines.material_path - return read_owned_blob(root,ref['sha256'],item,maximum) - with patch('subprocess.Popen',side_effect=AssertionError('Retained closure cannot execute source')): - closure=verify_recipe_closure(composition,published,read_blob=read) - self.assertEqual(closure['kind'],'external') - self.assertIsNone(closure['static_context']) - self.assertEqual(closure['execution_material'],self.preflight['material']) - self.assertEqual(closure['captured_inputs'],{'input/sample':self.input}) - self.assertEqual(reads[-1],('recipe_material','profile.json')) - self.assertTrue(any(kind=='recipe_material' and name.startswith('capture-') for kind,name in reads[:-1])) diff --git a/tests/test_project_material_fork.py b/tests/test_project_material_fork.py deleted file mode 100644 index fb27a597..00000000 --- a/tests/test_project_material_fork.py +++ /dev/null @@ -1,303 +0,0 @@ -"""Independent editable material identities, exact archived facts and inert intents.""" -import copy -import os -from pathlib import Path -from types import SimpleNamespace -import tempfile -import unittest -from unittest.mock import patch -import uuid - -from project_fork import ARCHIVE_FAMILIES, _digest, _input, active_records, publish_fork -from project_material import ProjectMaterial, FAMILIES, decode_records, _edges, _inventory -from project_material_fork import fork_records, is_intent -from project_store import DIR_FLAGS -from workbench import WorkbenchError -from test_project_material import definition, model -import test_project_material as material_fixture - -NOW = '2026-10-22T12:00:00+00:00' - - -def graph(identity=None, *, release=False, external=False): - value = dict(schema_version=1,mode='real',id=identity or uuid.uuid4().hex,revision=1, - name='Independent graph 山',recipe_version=1, - nodes=[dict(id='publish',type='publish',definition_version=1,parameters={})],edges=[]) - if release:value['nodes'].insert(0,dict(id='release',type='release',definition_version=1,parameters={'release_id':'e'*64})) - if external:value['recipe']='external_recipe' - return value - - -def recipe(catalog): - def ref(kind, identity): - result=dict(kind=kind,catalog_id=catalog,id=identity,sha256='a'*64) - if kind not in ('release','runtime'):result['revision']=1 - return result - return dict(format='recipe_draft_v2',id=uuid.uuid4().hex,revision=1,name='Bound recipe', - task=ref('task','classification'),model=ref('model','b'*32),trainer=ref('trainer','owned'), - evaluation_profile=ref('profile','owned'),runtime=ref('runtime','a'*64), - data=[ref('release','a'*64)],parameters={},layout={}) - - -def overlay(records, made, source, checkpoint, destination): - origin=dict(project_id=source,checkpoint=checkpoint) - return dict(family='project_fork',id=destination,document=dict(format='project_fork_v1',source=origin, - destination_project_id=destination,request_key='material:fork',directory='fork',name='Independent material', - request_sha256=_digest(_input(origin,'fork','Independent material','material:fork')), - mapping=copy.deepcopy(made['mapping']), - archived=sorted([dict(family=r['family'],id=r['id']) for r in records if r['family'] in ARCHIVE_FAMILIES],key=lambda r:(r['family'],r['id'])), - artifacts=dict(copied=[],missing_regenerable=[]))) - - -class MaterialForkCodecs(unittest.TestCase): - def setUp(self): - self.source=uuid.uuid4().hex;self.checkpoint='a'*64 - self.session=SimpleNamespace(snapshot=dict(project_id=self.source,checkpoint=self.checkpoint,records=[]), - summary=dict(project_id=self.source,checkpoint=self.checkpoint),check_current=lambda:None) - self.material=ProjectMaterial(self.session) - - def capture(self,family,current): - records=self.session.snapshot['records'] - action={'model_definition':'models.create','pipeline_graph':'pipeline.create','recipe_definition':'recipes.create'}[family] - record=self.material.capture_definition(family,current,records,action=action) - records.append(record) - return record - - def known(self): - import one_fit_evidence,text_training - owner=one_fit_evidence.contract(text_training) - parameters={k:v['default'] for k,v in text_training.PARAMETER_BOUNDS.items()} - parts=owner.model_definition(parameters) - value=definition(self.source,uuid.uuid4().hex) - value.update(task=owner.task_ref(self.source),**{k:parts[k] for k in ('specification','preprocessing_policy','output_policy')}) - return value - - def fork(self,records=None,source=None,checkpoint=None): - records=copy.deepcopy(self.session.snapshot['records'] if records is None else records) - source=source or self.source;checkpoint=checkpoint or self.checkpoint;destination=uuid.uuid4().hex - made=fork_records(records,source,checkpoint,destination,id_factory=lambda *key:uuid.uuid4().hex,created_at=NOW) - combined=records+made['records']+[overlay(records,made,source,checkpoint,destination)] - decode_records(combined) - return made,combined,destination - - def test_known_templates_and_binding_free_graph_are_fresh_without_rewriting_archive(self): - original=self.capture('model_definition',self.known()) - old=self.capture('pipeline_graph',graph()) - value,_=model(self.source) - material=dict(family='model_material',id=self.source+'.'+value['ref']['sha256'],document=dict( - format=FAMILIES['model_material'],origin_catalog_id=self.source,value=value,artifacts=_edges(_inventory('model_material',value),'model_material'),audit=[])) - self.session.snapshot['records'].append(material) - before=copy.deepcopy(self.session.snapshot['records']) - with patch('subprocess.Popen',side_effect=AssertionError('No execution or probe')),patch('builtins.open',side_effect=AssertionError('No origin file reads')): - made,combined,destination=self.fork() - self.assertEqual(self.session.snapshot['records'],before) - self.assertEqual(combined[:len(before)],before) - self.assertEqual(next(r for r in combined if r['family']=='model_material'),material) - newmodel=next(r for r in made['records'] if r['family']=='model_definition')['document'] - self.assertNotEqual(newmodel['current']['id'],original['document']['current']['id']) - self.assertEqual(newmodel['current']['task']['catalog_id'],destination) - self.assertEqual(newmodel['current']['task']['sha256'],original['document']['current']['task']['sha256']) - self.assertEqual(newmodel['current']['specification'],original['document']['current']['specification']) - self.assertEqual(newmodel['audit'],[]) - newgraph=next(r for r in made['records'] if r['family']=='pipeline_graph')['document'] - self.assertEqual(newgraph['current']['nodes'],old['document']['current']['nodes']) - self.assertEqual(newgraph['fork_origin']['created_at'],NOW) - self.assertTrue(all(r['document']['current']['revision']==1 for r in made['records'])) - - def test_bound_drafts_preserve_full_configuration_as_visible_nonexecutable_intents(self): - drafts=[('model_definition',definition(self.source,uuid.uuid4().hex)),('pipeline_graph',graph(release=True)), - ('pipeline_graph',graph(external=True)),('recipe_definition',recipe(self.source))] - captured=[self.capture(f,v) for f,v in drafts] - made,combined,destination=self.fork() - session=SimpleNamespace(snapshot=dict(project_id=destination,records=combined), - summary=dict(project_id=destination),check_current=lambda:None) - reader=ProjectMaterial(session) - intents=reader.intents() - self.assertEqual(len(intents),4) - self.assertEqual(reader.intent_capabilities()['editable'],[]) - self.assertEqual(len(reader.intent_capabilities()['requires_reselection']),4) - indexed={(r['family'],r['id']):r for r in captured} - for envelope in made['records']: - doc=envelope['document'];self.assertTrue(is_intent(doc['current'])) - self.assertEqual(doc['current']['definition'],indexed[(envelope['family'],doc['fork_origin']['id'])]['document']['current']) - intent=next(i for i in intents if i['family']=='model_definition') - with self.assertRaises(WorkbenchError) as caught:reader._require_resolved(intent['family'],intent['current']['id']) - self.assertEqual(caught.exception.code,'requires_reselection') - - def test_fork_proof_rejects_missing_overlay_mapping_changed_source_and_fabricated_initial(self): - self.capture('model_definition',self.known());made,combined,_=self.fork() - with self.assertRaises(WorkbenchError):decode_records(made['records']) - changes=[] - bad=copy.deepcopy(combined);bad[-1]['document']['mapping']=[];changes.append(bad) - bad=copy.deepcopy(combined);bad[0]['document']['current']['name']='Changed archive';changes.append(bad) - bad=copy.deepcopy(combined);bad[1]['document']['current']['name']='Invented';bad[1]['document']['revisions'][0]['name']='Invented';changes.append(bad) - bad=copy.deepcopy(combined);bad[1]['document']['fork_origin']['checkpoint']='b'*64;changes.append(bad) - bad=copy.deepcopy(combined);bad[1]['document']['fork_origin']['created_at']='2026-10-22T12:00:00';changes.append(bad) - for index,bad in enumerate(changes): - with self.subTest(case=index),self.assertRaises(WorkbenchError):decode_records(bad) - - def test_nested_fork_retains_exact_prior_origins_and_only_copies_active_definitions(self): - self.capture('model_definition',self.known());self.capture('recipe_definition',recipe(self.source)) - first,combined,intermediate=self.fork();unchanged=copy.deepcopy(combined) - second,nested,destination=self.fork(combined,intermediate,'b'*64) - self.assertEqual(nested[:len(combined)],unchanged) - self.assertEqual(len(second['records']),len(first['records'])) - self.assertTrue(all(r['document']['fork_origin']['project_id']==intermediate for r in second['records'])) - self.assertEqual(len([r for r in active_records(nested,project_id=destination) if r['family'] in ('model_definition','recipe_definition')]),2) - nested_intent=next(r for r in second['records'] if r['family']=='recipe_definition')['document']['current'] - self.assertFalse(is_intent(nested_intent['definition'])) - - def test_owner_history_is_archived_exact_and_mapping_identifies_current_source_revision(self): - first=self.capture('model_definition',self.known()) - second=copy.deepcopy(first['document']['current']);second.update(revision=2,name='Source revision two') - updated=self.material.capture_definition('model_definition',second,[first],action='models.save') - self.session.snapshot['records']=[updated] - made,combined,_=self.fork() - self.assertEqual(combined[0],updated) - self.assertEqual(made['mapping'][0]['source_revision'],2) - doc=made['records'][0]['document'] - self.assertEqual(doc['fork_origin']['revision'],2) - self.assertEqual(doc['current']['name'],'Source revision two') - self.assertEqual(len(doc['revisions']),1) - self.assertEqual(doc['audit'],[]) - - def test_captured_source_selector_stays_in_inert_intent_and_cannot_publish(self): - value=self.known();value.update(kind='captured_source',source_selector=dict( - project_id=uuid.uuid4().hex,recipe_id='training.py',expected_sha256='c'*64)) - self.capture('model_definition',value) - made,combined,destination=self.fork() - doc=made['records'][0]['document'] - self.assertEqual(doc['current']['required_reselection'],['source_selector']) - self.assertEqual(doc['current']['definition']['source_selector'],value['source_selector']) - reader=ProjectMaterial(SimpleNamespace(snapshot=dict(project_id=destination,records=combined), - summary=dict(project_id=destination),check_current=lambda:None)) - with self.assertRaises(WorkbenchError) as caught: - reader.publish_model(SimpleNamespace(publish=lambda *args: self.fail('Intent reached owner publication')), - doc['current']['id'],{'revision':1},'a'*64,'forbidden-intent') - self.assertEqual(caught.exception.code,'requires_reselection') - - def test_model_aware_graph_uses_owner_architecture_parameter_decoder(self): - import image_training - value=graph();value['recipe']=image_training.MODEL_RECIPE - parameters={k:v['default'] for k,v in image_training.PARAMETER_BOUNDS.items()} - parameters.update(widths=[16,32,64],input_size=96,head='linear') - value['nodes']=[dict(id='train',type='train',definition_version=1,parameters=parameters)] - self.capture('pipeline_graph',value) - made,_,_=self.fork() - self.assertFalse(is_intent(made['records'][0]['document']['current'])) - self.assertEqual(made['records'][0]['document']['current']['nodes'],value['nodes']) - - def test_known_task_does_not_adopt_unknown_binding_in_template_specification(self): - value=self.known();value['specification']['foreign_binding']=dict(catalog_id=self.source,material='b'*64) - self.capture('model_definition',value) - made,_,_=self.fork() - current=made['records'][0]['document']['current'] - self.assertTrue(is_intent(current)) - self.assertIn('specification',current['required_reselection']) - self.assertEqual(current['definition']['specification'],value['specification']) - - def test_two_overlays_cannot_bind_the_same_new_material_target(self): - self.capture('model_definition',self.known());other=self.capture('model_definition',self.known()) - _,combined,intermediate=self.fork() - _,nested,destination=self.fork(combined,intermediate,'b'*64) - earlier=next(r['document'] for r in nested if r['family']=='project_fork' and r['id']==intermediate) - latest=next(r['document'] for r in nested if r['family']=='project_fork' and r['id']==destination) - earlier['mapping'].append(dict(family='model_definition',source_id=other['id'],source_revision=999, - destination_id=latest['mapping'][0]['destination_id'])) - earlier['mapping'].sort(key=lambda m:(m['family'],m['source_id'],m['source_revision'],m['destination_id'])) - from project_fork import decode_fork - decode_fork(nested) # Structural overlay validity alone does not prove owner origins. - with self.assertRaises(WorkbenchError) as caught:decode_records(nested) - self.assertIn('target repeats',str(caught.exception)) - - def test_allocator_and_timestamp_are_explicit_and_bounded(self): - old=self.capture('model_definition',self.known()) - args=(self.session.snapshot['records'],self.source,self.checkpoint,uuid.uuid4().hex) - for factory,now in [(lambda *k:old['document']['current']['id'],NOW),(lambda *k:'x'*129,NOW),(lambda *k:uuid.uuid4().hex,'yesterday')]: - with self.assertRaises(WorkbenchError):fork_records(*args,id_factory=factory,created_at=now) - - def test_existing_nonfork_codec_still_requires_initial_owner_audit(self): - record=self.capture('model_definition',self.known());record['document']['audit']=[] - with self.assertRaises(WorkbenchError):decode_records([record]) - - -@unittest.skipUnless(os.environ.get('TULDOK_DATABASE_URL'),'Requires disposable PostgreSQL') -class MaterialForkPostgres(unittest.TestCase): - def setUp(self): - self.fixture=material_fixture.CanonicalPublication('test_model_publication_is_canonical_before_ack_and_has_one_session_receipt') - self.fixture.setUp();self.addCleanup(self.fixture.doCleanups) - - def test_cold_fork_restores_only_resolved_drafts_and_real_successor_save_has_exact_audit(self): - from metadata import Metadata - from project_artifacts import ProjectArtifacts - from project_session import ProjectSession - from model_definitions import ModelDefinitions - f=self.fixture - pure=MaterialForkCodecs();pure.setUp();known=pure.known();known['task']['catalog_id']=f.db.dataset_id - body={k:v for k,v in known.items() if k not in ('format','id','revision')} - with f.access.bind(f.owner.token): - source=f.material.mutate_definition('model_definition','models.create',None,body,f.session.snapshot['checkpoint'],'source-known',lambda:f.models.create(body)) - f.create() # Unknown task remains an explicit unresolved fork intent. - original=copy.deepcopy(f.session.snapshot);root_fd=os.open(f.path,DIR_FLAGS) - self.addCleanup(lambda:os.close(root_fd)) - def build(snap,dest): - made=fork_records(snap['records'],snap['project_id'],snap['checkpoint'],dest,id_factory=lambda *k:uuid.uuid4().hex,created_at=NOW) - return dict(records=snap['records']+made['records'],mapping=made['mapping'], - archived=sorted([dict(family=r['family'],id=r['id']) for r in snap['records'] if r['family'] in ARCHIVE_FAMILIES],key=lambda r:(r['family'],r['id'])),artifacts=[]) - result=publish_fork(f.store,f.artifacts,root_fd,'independent',root_path=f.path,name='Independent material', - expected_checkpoint=original['checkpoint'],request_key='fork-real',quiescent=True,build_candidate=build, - validate_candidate=lambda records,identity:decode_records(records)) - from project_store import ProjectStore - store=ProjectStore.open(f.path/'independent');f.resources.append(store) - artifacts=ProjectArtifacts(store);f.resources.append(artifacts) - db=Metadata(f.path/'fork-projection',dataset_id=result['snapshot']['project_id'],projection_id=uuid.uuid4().hex) - f.resources.append(db);f.schemas.append(db.schema) - session=ProjectSession(store,db,f.access,artifacts,validate_records=f.validate) - reader=ProjectMaterial(session);reader.restore() - self.assertEqual(db.execute('SELECT count(*) FROM model_definition_drafts').fetchone()[0],1) - editable=next(r for r in active_records(session.snapshot['records'],project_id=db.dataset_id) - if r['family']=='model_definition' and not is_intent(r['document']['current'])) - draft=editable['document']['current'] - with f.access.bind(f.owner.token):self.assertEqual(len(reader.intents()),1) - dataset=SimpleNamespace(db=db,lock=db.lock,access=reader.owner_access,path=db.path,pipelines=f.dataset.pipelines) - models=ModelDefinitions(dataset) - with f.access.bind(f.owner.token): - changed=dict(draft,name='Edited independent fork');savebody=dict(revision=1,document=changed) - saved=reader.mutate_definition('model_definition','models.save',draft['id'],savebody,session.snapshot['checkpoint'], - 'fork-save',lambda:models.save(draft['id'],savebody)) - self.assertEqual(saved['revision'],2) - doc=next(r['document'] for r in session.snapshot['records'] if r['family']=='model_definition' and r['id']==editable['id']) - self.assertEqual([a['action'] for a in doc['audit']],['models.save']) - self.assertEqual(doc['revisions'][0],draft) - self.assertEqual(f.store.snapshot(),original) - self.assertEqual(next(r for r in session.snapshot['records'] if r['id']==f.db.dataset_id+'.'+source['id']), - next(r for r in original['records'] if r['id']==f.db.dataset_id+'.'+source['id'])) - self.assertEqual(session.snapshot['project_id'],db.dataset_id) - - def test_reconcile_projection_preserves_custody_foreign_keys_and_refuses_immutable_conflicts(self): - f=self.fixture - with f.access.bind(f.owner.token): - draft=f.create() - published=f.material.publish_model(f.models,draft['id'],{'revision':1},f.session.snapshot['checkpoint'],'model-for-custody') - f.db.execute('CREATE TABLE fixture_retained_custody (id TEXT PRIMARY KEY, material_sha256 TEXT REFERENCES model_materials(sha256))') - f.db.execute('INSERT INTO fixture_retained_custody VALUES(%s,%s)',('drained-native-job',published['ref']['sha256'])) - stale=dict(draft,name='SQL change never canonically acknowledged') - from workbench import encode - f.db.execute('UPDATE model_definition_drafts SET document=%s WHERE id=%s',(encode(stale),draft['id'])) - unrelated=dict(draft,id=uuid.uuid4().hex,name='Local custody-owned draft') - f.db.execute('INSERT INTO model_definition_drafts VALUES(%s,%s,%s)',(unrelated['id'],1,encode(unrelated))) - with f.access.lock,f.session.lock,f.db.lock: - f.material.reconcile_projection() - self.assertEqual(f.db.execute('SELECT id FROM fixture_retained_custody').fetchall(),[('drained-native-job',)]) - self.assertEqual(f.db.execute('SELECT count(*) FROM model_definition_drafts').fetchone()[0],2) - from model_definitions import retained_json - self.assertEqual(retained_json(f.db.execute('SELECT document FROM model_definition_drafts WHERE id=%s',(draft['id'],)).fetchone()[0]),draft) - self.assertEqual(retained_json(f.db.execute('SELECT document FROM model_materials WHERE sha256=%s',(published['ref']['sha256'],)).fetchone()[0]),published) - f.db.execute('UPDATE model_definition_drafts SET document=%s WHERE id=%s',(encode(stale),draft['id'])) - f.db.execute('UPDATE model_materials SET document=%s WHERE sha256=%s',(encode({}),published['ref']['sha256'])) - with f.access.lock,f.session.lock,f.db.lock: - with self.assertRaises(WorkbenchError) as caught:f.material.reconcile_projection() - self.assertEqual(caught.exception.code,'projection_unavailable') - self.assertEqual(retained_json(f.db.execute('SELECT document FROM model_definition_drafts WHERE id=%s',(draft['id'],)).fetchone()[0]),stale) - self.assertEqual(f.db.execute('SELECT count(*) FROM fixture_retained_custody').fetchone()[0],1) - self.assertEqual(f.store.snapshot(),f.session.snapshot) diff --git a/tests/test_project_measurement_comparison_http.py b/tests/test_project_measurement_comparison_http.py deleted file mode 100644 index df5f9667..00000000 --- a/tests/test_project_measurement_comparison_http.py +++ /dev/null @@ -1,73 +0,0 @@ -"""Real native HTTP source import, atomic comparison and scalar inspection.""" -import hashlib -import json -import os -import unittest -from unittest.mock import patch - -import agent_api -from workbench import WorkbenchError - -import test_project_files_http as m1 -import test_project_files_m2_http as m2 -from retained_measurements import encode -from test_measurement_comparison import partition - - -@unittest.skipUnless(os.environ.get('TULDOK_DATABASE_URL'), 'Requires disposable PostgreSQL') -class ComparisonHTTP(unittest.TestCase): - cleanup_owned=m1.ProjectFilesHTTP.cleanup_owned - select_host=m1.ProjectFilesHTTP.select_host - request=m1.ProjectFilesHTTP.request - state=m1.ProjectFilesHTTP.state - envelope=m1.ProjectFilesHTTP.envelope - action=m1.ProjectFilesHTTP.action - create=m1.ProjectFilesHTTP.create - arguments=m2.ProjectFilesM2HTTP.arguments - transport=m2.ProjectFilesM2HTTP.transport - call=m2.ProjectFilesM2HTTP.call - def setUp(self): - self.operations=[] - m1.ProjectFilesHTTP.setUp(self) - - def test_two_original_sources_compare_and_inspect_through_real_HTTP(self): - self.create() - sources=[] - for subject, identity in [('a','b'*32),('b','c'*32)]: - raw=encode(partition(subject));digest=hashlib.sha256(raw).hexdigest() - filename=subject+'-measurements.json';manifest_name=subject+'-source.json' - (self.external/filename).write_bytes(raw) - manifest=dict(schema_version=1,id=identity,name='Original '+subject, - data=[dict(id='scalars',label='Retained scalars',path=filename,sha256=digest)], - recipes=[],evidence=[],requirements=[]) - (self.external/manifest_name).write_text(json.dumps(manifest)) - registered=self.call('source_register',root='fixture',manifest_path=manifest_name) - snapshot={key:registered[key] for key in ('origin_catalog_id','project_id','manifest_sha256')} - admitted=self.call('measurement_import',snapshot=snapshot,reference_id='scalars',expected_sha256=digest) - sources.append(dict(origin_catalog_id=admitted['origin_catalog_id'],packet_sha256=digest)) - before=self.workspace._projection.session.snapshot - metadata=self.call('measurement_compare',sources=sources)['value'] - self.assertEqual([s['id'] for s in metadata['subjects']],['a','b']) - self.assertIsNone(metadata['query']) - query=self.call('measurement_compare',sources=sources,metric_id='error',offset=1,limit=2)['value']['query'] - self.assertEqual(query['total'],4) - self.assertEqual([s['maximum']['value'] for s in query['summary']],[2e-15,.02]) - self.assertEqual([r['subject_id'] for r in query['rows']],['a','b']) - maximum=query['summary'][1] - inspected=self.call('measurement_inspect',**maximum['source'],observation_id=maximum['maximum']['id'])['value'] - self.assertEqual(inspected['scalar_evidence']['value'],.02) - self.assertEqual(inspected['case']['dimensions']['cpm'],8) - missing=self.call('measurement_compare',sources=sources,metric_id='latency')['value']['query'] - self.assertTrue(all(s['maximum'] is None for s in missing['summary'])) - self.assertEqual(self.workspace._projection.session.snapshot,before) - # Exercise version-specific admission at the real workspace/SQL owner - # with small declared fixture budgets; no partial comparison escapes. - arguments=self.arguments('measurement_compare',sources=sources) - with self.owner.bound(self.workspace),patch.object(agent_api,'measurement_comparison_row_limit', - side_effect=lambda version:7 if version==1 else 8): - with self.assertRaises(WorkbenchError) as error: - self.workspace.dispatch('project_files.measurement_compare',arguments,selected_version=1) - self.assertEqual(error.exception.code,'too_large') - value=self.workspace.dispatch('project_files.measurement_compare',arguments,selected_version=2) - self.assertEqual(value['value']['value']['observation_count'],8) - self.assertEqual(self.workspace._projection.session.snapshot,before) diff --git a/tests/test_project_measurement_reads.py b/tests/test_project_measurement_reads.py deleted file mode 100644 index 1ef28124..00000000 --- a/tests/test_project_measurement_reads.py +++ /dev/null @@ -1,108 +0,0 @@ -"""Read the adopted measurement family without cloning unrelated retained facts. - -Real canonical files and real session freshness guards; no SQL reconstruction -or packet import is claimed by this focused fixture. -""" -import copy -import json -import os -from pathlib import Path -import tempfile -import threading -import unittest -from unittest.mock import patch - -import project_measurements -import project_session -from project_projection import validate_project_records -from project_store import ProjectStore, ProjectStoreError -from test_project_receipt_validation import candidate, PROJECT - - -class MeasurementReadTests(unittest.TestCase): - def setUp(self): - temporary = tempfile.TemporaryDirectory(prefix='tuldok-measurement-read-') - self.addCleanup(temporary.cleanup) - self.root = Path(temporary.name)/'project' - self.store = ProjectStore.create(self.root, 'Measurement read fixture', 'new', 'a'*64) - self.addCleanup(self.store.close) - self.records = candidate() - self.records.append(dict(family='project_artifact', id='f'*64, - document=dict(format='project_artifact_v1', sha256='f'*64, bytes=7))) - validate_project_records(self.records, project_id=PROJECT, artifacts=None) - snapshot = self.store.commit(self.records, self.store.summary()['checkpoint'], 'seed', 'b'*64) - self.session = object.__new__(project_session.ProjectSession) - self.session.store, self.session.available = self.store, True - self.session._snapshot, self.session.lock = copy.deepcopy(snapshot), threading.RLock() - self.owner = object.__new__(project_measurements.ProjectMeasurements) - self.owner.session = self.session - self.expected = {r['id']: copy.deepcopy(r['document']) for r in self.records - if r['family'] == project_measurements.FAMILY} - - def test_documents_are_literal_independent_and_do_not_copy_unrelated_graph(self): - original = project_session.copy_validated_json - unrelated = [] - def observe(value): - if isinstance(value, dict) and 'records' in value: - unrelated.extend(r['id'] for r in value['records'] if r['id'] == 'f'*64) - return original(value) - with patch.object(project_session, 'copy_validated_json', observe): - result = self.owner._documents() - self.assertEqual(result, self.expected) - self.assertEqual(unrelated, [], 'Measurement read copied an unrelated retained envelope') - next(iter(result.values()))['source']['path'] = 'caller-edited.json' - self.assertEqual(self.owner._documents(), self.expected) - self.assertEqual(self.session._snapshot, self.store.snapshot()) - - def test_lookup_reuses_verified_records_without_redecoding_adopted_material(self): - with patch.object(self.store, '_record_file', wraps=self.store._record_file) as reads, \ - patch.object(project_measurements, 'material_records', - side_effect=AssertionError('Read-only lookup redecoded adopted material')): - self.assertEqual(self.owner._documents(), self.expected) - self.assertEqual(reads.call_count, 0, 'Verified immutable records are not re-read per lookup') - - def test_unavailable_projection_fails_before_any_store_read(self): - self.session.available = False - with patch.object(self.store, 'summary', side_effect=AssertionError('Unavailable store read')): - with self.assertRaises(project_session.ProjectSessionError) as caught: - self.owner._documents() - self.assertEqual(caught.exception.code, 'projection_unavailable') - - def test_other_family_publication_requires_reopen(self): - changed = copy.deepcopy(self.records) - changed[-1]['document']['bytes'] = 8 - self.store.commit(changed, self.store.summary()['checkpoint'], 'other', 'c'*64) - with self.assertRaises(project_session.ProjectSessionError) as caught: - self.owner._documents() - self.assertEqual(caught.exception.code, 'stale_project') - - def test_same_length_unselected_corruption_is_never_served_and_verification_rejects_it(self): - inventory = json.loads((self.root/'.tuldok/project.json').read_bytes())['inventory'] - entry = next(r for r in inventory if r['id'] == 'f'*64) - path = self.root/'.tuldok'/entry['path'] - before, info = path.read_bytes(), path.stat() - changed = before.replace(b'"bytes": 7', b'"bytes": 8') - self.assertNotEqual(changed, before) - self.assertEqual(len(changed), len(before)) - path.chmod(0o600) - path.write_bytes(changed) - os.utime(path, ns=(info.st_atime_ns, info.st_mtime_ns)) - # Reads keep serving verified values; explicit verification refuses. - self.assertEqual(self.owner._documents(), self.expected) - with self.assertRaises(ProjectStoreError) as caught: - self.store.verify_records() - self.assertEqual(caught.exception.code, 'stale') - - def test_family_can_be_empty_and_returned_snapshot_contract_stays_complete(self): - records = [r for r in self.records if r['family'] not in (project_measurements.FAMILY,'project_operation')] - validate_project_records(records, project_id=PROJECT, artifacts=None) - self.session._snapshot = self.store.commit(records, self.store.summary()['checkpoint'], 'empty', 'd'*64) - self.assertEqual(self.owner._documents(), {}) - snapshot = self.session.snapshot - self.assertEqual(snapshot, self.store.snapshot()) - snapshot['records'].clear() - self.assertEqual(self.session.snapshot, self.store.snapshot()) - - -if __name__ == '__main__': - unittest.main() diff --git a/tests/test_project_measurements.py b/tests/test_project_measurements.py deleted file mode 100644 index 22af6480..00000000 --- a/tests/test_project_measurements.py +++ /dev/null @@ -1,226 +0,0 @@ -"""Native scalar custody, publication, current access and independent Open. - -Only fixture JSON is imported. No neural or simulation runtime is involved. -""" -import copy -from functools import partial -import hashlib -import json -import os -from pathlib import Path -import shutil -import tempfile -import unittest -from unittest.mock import patch -import uuid - -from access import Access, AccessError -from metadata import Metadata, connection_info -from project_fork import active_records, publish_fork -from project_fork_composition import build_candidate -from project_measurements import FAMILY, validate_operation_result -from project_projection import ProjectProjection -from project_store import ProjectStore, DIR_FLAGS -from retained_measurements import MeasurementTable, encode -from test_retained_measurements import fixture -from workbench import WorkbenchError, timestamp - - -@unittest.skipUnless(os.environ.get('TULDOK_DATABASE_URL'), 'Requires disposable PostgreSQL') -class ProjectMeasurementTests(unittest.TestCase): - def setUp(self): - self.tmp = tempfile.TemporaryDirectory(prefix='tuldok-measurements-') - self.root = Path(self.tmp.name) - self.addCleanup(self.tmp.cleanup) - self.resources, self.schemas = [], [] - self.addCleanup(self.cleanup) - self.host = self.metadata('host') - self.access = Access(self.host, self.host.path) - self.owner_token = self.access.exchange(self.access._local_owner_token())['token'] - self.enterContext(self.access.bind(self.owner_token)) - self.source_root = self.root / 'source' - self.source_root.mkdir() - self.raw = encode(fixture()) - self.digest = hashlib.sha256(self.raw).hexdigest() - (self.source_root / 'measurements.json').write_bytes(self.raw) - self.manifest = dict(schema_version=1, id='a'*32, name='Scalar source fixture', - data=[dict(id='measurements', label='Exact scalar fixture', path='measurements.json', sha256=self.digest)], - recipes=[], evidence=[], requirements=[]) - (self.source_root / 'source.json').write_text(json.dumps(self.manifest)) - self.store = ProjectStore.create(self.root / 'project', 'Native scalar fixture', 'new-scalars', 'a'*64) - self.resources.append(self.store) - self.projection = self.project(self.store, 'projection', {'fixture': self.source_root}) - self.session = self.projection.session - self.measurements = self.projection.measurements - self.registration = self.projection.source_adapter.register( - dict(root='fixture', manifest_path='source.json'), self.checkpoint, 'register-source') - self.body = dict(snapshot={k:self.registration[k] for k in ('origin_catalog_id', 'project_id', 'manifest_sha256')}, - reference_id='measurements', expected_sha256=self.digest) - self.origin = self.session.snapshot['project_id'] - - @property - def checkpoint(self): - return self.session.snapshot['checkpoint'] - - def metadata(self, name, *, project_id=None): - kwargs = dict(dataset_id=project_id, projection_id=uuid.uuid4().hex) if project_id else {} - db = Metadata(self.root / name, **kwargs) - self.resources.append(db) - self.schemas.append(db.schema) - return db - - def project(self, store, name, roots): - db = self.metadata(name, project_id=store.snapshot()['project_id']) - projection = ProjectProjection(store, db, self.access, roots) - self.resources.append(projection) - return projection - - def cleanup(self): - import psycopg - from psycopg import sql - for resource in reversed(self.resources): - resource.close() - with psycopg.connect(connection_info(), autocommit=True) as db: - for schema in self.schemas: - db.execute(sql.SQL('DROP SCHEMA IF EXISTS {} CASCADE').format(sql.Identifier(schema))) - - def admit(self, *, body=None, key='import-measurements', checkpoint=None): - return self.projection.source_adapter.import_measurements( - body or self.body, self.checkpoint if checkpoint is None else checkpoint, key) - - def test_native_import_retains_one_exact_packet_and_no_fabricated_history(self): - with patch('subprocess.Popen', side_effect=AssertionError('No producer process')): - result = self.admit() - query = self.measurements.query(self.origin, self.digest, 'error')['value'] - records = self.store.snapshot()['records'] - self.assertEqual(len([r for r in records if r['family'] == FAMILY]), 1) - self.assertEqual({r['family'] for r in records}, - {'project_snapshot', 'project_artifact', 'project_operation', FAMILY}) - self.assertEqual(self.projection.artifacts.read_blob(result['blob']), self.raw) - self.assertTrue(validate_operation_result('measurements.import', result, records)) - self.assertEqual(result['actor_id'], self.access._context().actor_id) - self.assertEqual(query, MeasurementTable(self.raw).query('error')) - self.assertEqual([s['maximum']['value'] for s in query['summary']], [2e-15, 0.02]) - missing = self.measurements.query(self.origin, self.digest, 'latency')['value'] - self.assertTrue(all(s['maximum'] is None for s in missing['summary'])) - self.assertEqual(missing['summary'][1]['states']['failed'], 1) - self.assertEqual(self.measurements.sources()['items'][0]['availability']['state'], 'unverified') - row = self.measurements.inspect(self.origin, self.digest, 'a-case1-error')['value'] - self.assertEqual(row['scalar_evidence']['value'], 1e-17) - self.assertEqual(self.measurements.subjects(self.origin, self.digest, offset=1, limit=1)['value']['items'][0]['id'], 'b') - - def test_replay_is_exact_and_stale_or_changed_requests_do_not_publish(self): - original_cp = self.checkpoint - result = self.admit() - canonical = self.store.snapshot() - self.assertEqual(self.admit(checkpoint=original_cp), result) - self.assertEqual(self.store.snapshot(), canonical) - with self.assertRaises(WorkbenchError) as error: - self.admit(key='stale-import', checkpoint=original_cp) - self.assertEqual(error.exception.code, 'stale_project') - different = copy.deepcopy(self.body) - different['expected_sha256'] = 'f'*64 - with self.assertRaises(WorkbenchError): - self.admit(body=different) - self.assertEqual(self.store.snapshot(), canonical) - - def test_permission_precedes_source_or_artifact_reads(self): - self.admit() - inspector = self.access.issue(dict(label='Scalar inspector', scopes=['inspect'])) - with self.access.bind(inspector['token']): - self.assertEqual(self.measurements.metadata(self.origin, self.digest)['value']['case_count'], 2) - with patch.object(self.projection.sources, 'read_snapshot_manifest', side_effect=AssertionError('Denied before source I/O')): - with self.assertRaises(AccessError): - self.admit(key='not-an-editor') - with self.access.bind(inspector['token']): - with self.access.bind(self.owner_token): - self.access.revoke(inspector['identity']['credential_id']) - with patch.object(self.projection.artifacts, 'read_blob', side_effect=AssertionError('Denied before artifact I/O')): - with self.assertRaises(AccessError): - self.measurements.query(self.origin, self.digest, 'error') - - def test_current_revocation_during_selection_prevents_return(self): - self.admit() - inspector = self.access.issue(dict(label='Revoked during selection', scopes=['inspect'])) - original = MeasurementTable.query - def revoke(table, *args, **kwargs): - value = original(table, *args, **kwargs) - with self.access.bind(self.owner_token): - self.access.revoke(inspector['identity']['credential_id']) - return value - with self.access.bind(inspector['token']), patch.object(MeasurementTable, 'query', revoke): - with self.assertRaises(AccessError): - self.measurements.query(self.origin, self.digest, 'error') - - def test_cold_independent_copy_reads_without_restoring_source_bindings(self): - result = self.admit() - expected = self.measurements.query(self.origin, self.digest, 'error', filters={'cpm':16}) - copied = self.root / 'relocated-project' - shutil.copytree(self.root / 'project', copied) - for path in (self.root / 'project').rglob('*'): - if path.is_file(): - self.assertNotEqual(path.stat().st_ino, (copied / path.relative_to(self.root / 'project')).stat().st_ino) - store = ProjectStore.open(copied) - self.resources.append(store) - cold = self.project(store, 'cold-projection', {}) - shutil.rmtree(self.source_root) - self.assertEqual(cold.db.execute('SELECT count(*) FROM workspace_projects').fetchone()[0], 0) - self.assertEqual(cold.measurements.query(self.origin, self.digest, 'error', filters={'cpm':16}), expected) - self.assertEqual(cold.artifacts.read_blob(result['blob']), self.raw) - self.assertEqual(cold.measurements.metadata(self.origin, self.digest)['value']['observation_count'], 8) - - def test_fork_preserves_origin_scoped_packet_without_fabricating_new_capture(self): - result = self.admit() - before = self.store.snapshot() - root_fd = os.open(self.root, DIR_FLAGS) - try: - publish_fork(self.store, self.projection.artifacts, root_fd, 'fork', root_path=self.root, - name='Independent scalar fork', expected_checkpoint=before['checkpoint'], request_key='fork-scalars', - quiescent=True, build_candidate=partial(build_candidate, created_at=timestamp(), - id_factory=lambda _family, _source_id, _revision: uuid.uuid4().hex), - validate_candidate=lambda records, identity:self.projection.validate_records(records, project_id=identity)) - finally: - os.close(root_fd) - store = ProjectStore.open(self.root / 'fork') - self.resources.append(store) - cold = self.project(store, 'fork-projection', {}) - self.assertNotEqual(store.snapshot()['project_id'], self.origin) - records = active_records(store.snapshot()['records'], project_id=store.snapshot()['project_id']) - self.assertEqual(next(r['document'] for r in records if r['family'] == FAMILY), result) - self.assertEqual(cold.measurements.inspect(self.origin, self.digest, 'a-case1-error')['value']['observation']['value'], 1e-17) - - def test_candidate_cross_reference_receipt_and_title_forgery_are_refused(self): - result = self.admit() - canonical = self.store.snapshot() - for mutation in ('declaration', 'snapshot', 'source-path', 'title', 'receipt'): - records = copy.deepcopy(canonical['records']) - doc = next(r['document'] for r in records if r['family'] == FAMILY) - if mutation == 'declaration': - records = [r for r in records if not (r['family'] == 'project_artifact' and r['id'] == self.digest)] - if mutation == 'snapshot': - records = [r for r in records if r['family'] != 'project_snapshot'] - if mutation == 'source-path': - doc['source']['path'] = 'other.json' - if mutation == 'title': - doc['title'] = 'Different retained title' - if mutation == 'receipt': - receipt = next(r['document'] for r in records if r['family'] == 'project_operation' and r['document']['operation'] == 'measurements.import') - receipt['result']['title'] = 'Forged result' - with self.subTest(mutation=mutation), self.assertRaises(WorkbenchError): - self.projection.validate_records(records) - self.assertEqual(self.store.snapshot(), canonical) - result['title'] = 'Detached caller mutation' - self.assertNotEqual(self.measurements.sources()['items'][0]['title'], result['title']) - - def test_changed_source_packet_fails_before_canonical_import(self): - before = self.store.snapshot() - changed = fixture() - changed['observations'][0]['value'] = 0.5 - (self.source_root / 'measurements.json').write_bytes(encode(changed)) - with self.assertRaises(WorkbenchError): - self.admit() - self.assertEqual(self.store.snapshot(), before) - - -if __name__ == '__main__': - unittest.main() diff --git a/tests/test_project_measurements_clients.py b/tests/test_project_measurements_clients.py deleted file mode 100644 index 079f6ab2..00000000 --- a/tests/test_project_measurements_clients.py +++ /dev/null @@ -1,115 +0,0 @@ -"""Closed scalar selections and exact thin-client response correlation.""" -import copy -import unittest -from unittest.mock import patch - -import agent_api as api -from retained_measurements import MeasurementTable, MeasurementComparison, encode -from test_project_files_clients import BINDING, PROJECT, CHECKPOINT, OTHER, bound, client -from test_retained_measurements import fixture -from tuldok_client import ProjectFilesClient - - -class MeasurementContracts(unittest.TestCase): - def setUp(self): - self.table=MeasurementTable(encode(fixture())) - self.source=dict(format='project_measurement_source_v1',origin_catalog_id=PROJECT, - id=self.table.sha256,title=self.table.metadata()['title'],blob=dict(sha256=self.table.sha256,bytes=len(encode(fixture()))), - source=dict(origin_catalog_id=PROJECT,project_id='a'*32,manifest_sha256=OTHER, - reference_id='measurements',path='measurements.json',measured_sha256=self.table.sha256), - actor_id='d'*32,imported_at='2026-10-23T00:00:00+00:00') - self.args=dict(binding=BINDING,checkpoint=CHECKPOINT,origin_catalog_id=PROJECT,packet_sha256=self.table.sha256) - - def sdk(self,value): - return ProjectFilesClient(client({'status':200,'result':dict(binding=BINDING,project_id=PROJECT, - checkpoint=CHECKPOINT,value=value)})) - - def test_comparison_capacity_is_versioned_without_changing_packet_headers(self): - from retained_measurements import MAX_COMPARISON_ROWS,MAX_ROWS - self.assertEqual(api.measurement_comparison_row_limit(1),100000) - self.assertEqual(api.measurement_comparison_row_limit(2),250000) - self.assertEqual(api.measurement_comparison_row_limit(2),MAX_COMPARISON_ROWS) - self.assertEqual(MAX_ROWS,100000) - self.assertEqual(api._MEASUREMENT_HEADER['properties']['observation_count']['maximum'],100000) - self.assertNotEqual(api.contract('project_files.measurement_compare',1)['sha256'], - api.contract('project_files.measurement_compare',2)['sha256']) - - def test_group_comparison_header_and_query_correlate_every_original_source(self): - locator=dict(origin_catalog_id=PROJECT,packet_sha256=self.table.sha256) - comparison=MeasurementComparison([(locator,self.table)]) - args=dict(binding=BINDING,checkpoint=CHECKPOINT,sources=[locator]) - page=dict(sources=[self.source],value=comparison.read()) - self.assertEqual(self.sdk(page).measurement_compare(**args)['value'],page) - query=dict(sources=[self.source],value=comparison.read('error',offset=1,limit=1)) - request=dict(args,metric_id='error',offset=1,limit=1) - self.assertEqual(self.sdk(query).measurement_compare(**request)['value'],query) - for mutate in (lambda p:p['sources'][0].update(id=OTHER), - lambda p:p['value']['query'].update(offset=0), - lambda p:p['value']['query']['summary'][0]['states'].update(measured=99), - lambda p:p['value']['query']['rows'][0]['source'].update(packet_sha256=OTHER), - lambda p:p['value']['subjects'][0]['source'].update(origin_catalog_id='f'*32)): - bad=copy.deepcopy(query);mutate(bad) - with self.assertRaises(api.AgentAPIError):self.sdk(bad).measurement_compare(**request) - - def test_capability_bound_applies_to_the_actual_advertised_profile(self): - sizes={profile:len(api.capabilities(PROJECT,profile=profile)['operations']) for profile in ('catalog','project')} - maximum=max(sizes.values()) - with patch.object(api,'MAX_OPERATIONS',maximum): - for profile in sizes: - manifest=api.capabilities(PROJECT,profile=profile) - self.assertLess(len(api.encoded(manifest)),api.CAPABILITIES_LIMIT) - self.assertEqual(len(manifest['operations']),sizes[profile]) - with patch.object(api,'MAX_OPERATIONS',maximum-1),self.assertRaises(api.AgentAPIError) as caught: - api.capabilities(PROJECT,profile=max(sizes,key=sizes.get)) - self.assertEqual(caught.exception.code,'registry_invalid') - - def test_typed_read_routes_pin_packet_selection_and_never_accept_execution(self): - arguments=dict(self.args,metric_id='error',filters={'cpm':16},subject_ids=['a'],limit=2) - method,path,body=api.project_request('project_files.measurement_query',arguments) - self.assertEqual(method,'POST') - self.assertEqual(body['filters'],{'cpm':16}) - self.assertIn(self.table.sha256,path) - self.assertFalse(api.operation('project_files.measurement_query')['side_effects']) - for change in ({'script':'never.py'},{'execute':True},{'packet_sha256':'not-a-hash'},{'limit':101}): - with self.subTest(change=change),self.assertRaises(api.AgentAPIError): - api.validate_arguments('project_files.measurement_query',dict(arguments,**change)) - for missing in ('origin_catalog_id','packet_sha256','binding','checkpoint','metric_id'): - with self.subTest(missing=missing),self.assertRaises(api.AgentAPIError): - api.validate_arguments('project_files.measurement_query',{k:v for k,v in arguments.items() if k!=missing}) - - def test_exact_query_and_inspection_reply_is_accepted_and_changed_selection_refused(self): - query=self.table.query('error',subject_ids=['a'],filters={'cpm':16},limit=2) - value=dict(source=self.source,value=query) - args=dict(self.args,metric_id='error',subject_ids=['a'],filters={'cpm':16},limit=2) - self.assertEqual(self.sdk(value).measurement_query(**args)['value'],value) - for key,replacement in (('packet_sha256',OTHER),('filters',{}),('offset',1),('subject_ids',['b'])): - changed=copy.deepcopy(value);changed['value'][key]=replacement - with self.subTest(key=key),self.assertRaises(api.AgentAPIError): - self.sdk(changed).measurement_query(**args) - changed=copy.deepcopy(value);changed['source']['origin_catalog_id']='f'*32 - with self.assertRaises(api.AgentAPIError):self.sdk(changed).measurement_query(**args) - row=dict(source=self.source,value=self.table.inspect('a-case1-error')) - self.assertEqual(self.sdk(row).measurement_inspect(**self.args,observation_id='a-case1-error')['value'],row) - with self.assertRaises(api.AgentAPIError): - self.sdk(row).measurement_inspect(**self.args,observation_id='a-case2-error') - - def test_header_subject_and_source_pages_and_import_keep_exact_identity(self): - header=dict(source=self.source,value=self.table.metadata()) - self.assertEqual(self.sdk(header).measurement_metadata(**self.args)['value'],header) - header['value']['title']='Different retained title' - with self.assertRaises(api.AgentAPIError):self.sdk(header).measurement_metadata(**self.args) - subjects=dict(source=self.source,value=self.table.subjects(offset=1,limit=1)) - self.assertEqual(self.sdk(subjects).measurement_subjects(**self.args,offset=1,limit=1)['value'],subjects) - with self.assertRaises(api.AgentAPIError):self.sdk(subjects).measurement_subjects(**self.args,offset=0,limit=1) - availability=dict(state='unverified',expected_sha256=self.table.sha256,expected_bytes=self.source['blob']['bytes'], - observed_sha256=None,observed_bytes=self.source['blob']['bytes']) - page=dict(items=[dict(self.source,availability=availability)],offset=0,limit=40,total=1) - self.assertEqual(self.sdk(page).measurement_sources(binding=BINDING,checkpoint=CHECKPOINT)['value'],page) - request=dict(bound(),snapshot={k:self.source['source'][k] for k in ('origin_catalog_id','project_id','manifest_sha256')}, - reference_id='measurements',expected_sha256=self.table.sha256) - self.assertEqual(self.sdk(self.source).measurement_import(**request)['value'],self.source) - with self.assertRaises(api.AgentAPIError): - self.sdk(dict(self.source,id=OTHER)).measurement_import(**request) - - -if __name__=='__main__':unittest.main() diff --git a/tests/test_project_model_portfolio.cjs b/tests/test_project_model_portfolio.cjs deleted file mode 100644 index 704e4035..00000000 --- a/tests/test_project_model_portfolio.cjs +++ /dev/null @@ -1,47 +0,0 @@ -'use strict'; -const assert=require('node:assert/strict'),fs=require('node:fs'),vm=require('node:vm'),path=require('node:path'); -const fixture=require('./model_portfolio_fixture.cjs'),window={}; -vm.runInNewContext(fs.readFileSync(path.join(__dirname,'../static/project-model-portfolio.js'),'utf8'),{window,TextEncoder}); -const {decode,checkCard}=window.ProjectModelPortfolioDocument; -const valid=()=>structuredClone(fixture.document),parse=value=>decode(JSON.stringify(value)); -assert.deepEqual(JSON.parse(JSON.stringify(parse(valid()))),fixture.document); -let checks=1; -function bad(change,message,code='invalid'){ - const value=valid();change(value); - assert.throws(()=>parse(value),error=>error.code===code&&error.message===message);checks++; -} -bad(d=>{d.format='other';},'Unsupported model-organization document format.','unsupported'); -bad(d=>{d.extra=true;},'Invalid model-organization document.'); -bad(d=>{d.models=[];},'Invalid model-organization document.'); -bad(d=>{d.groups.push(structuredClone(d.groups[0]));},'Invalid or duplicate organization group.'); -bad(d=>{d.groups[0].parent='missing';},'Organization group parent is unavailable.'); -bad(d=>{d.groups[0].parent='pressure';},'Organization grouping contains a cycle.'); -bad(d=>{d.models.push(structuredClone(d.models[0]));},'Invalid or duplicate organized model.'); -bad(d=>{d.models[0].group_id='missing';},'Invalid or duplicate organized model.'); -bad(d=>{d.models[0].aliases.push('C107');},'Invalid or duplicate organized model.'); -bad(d=>{d.models[0].review='qualified';},'Invalid or duplicate organized model.'); -bad(d=>{delete d.models[0].summary.method;},'Reviewed model requires all six authored summary fields.'); -bad(d=>{d.models[1].summary={};},'Pending review cannot expose a reviewed summary.'); -bad(d=>{d.models[0].card.path='notes/../private';},'Invalid captured model-note reference.'); -bad(d=>{d.models[0].card.revision=0;},'Invalid captured model-note reference.'); -bad(d=>{d.relationships[0].to='unknown';},'Invalid authored model relationship.'); -bad(d=>{d.relationships[0].to=d.relationships[0].from;},'Invalid authored model relationship.'); -bad(d=>{d.relationships[0].kind='trial_parent';},'Invalid authored model relationship.'); -bad(d=>{d.relationships.push(structuredClone(d.relationships[0]));},'Duplicate authored model relationship.'); -bad(d=>{const a=d.relationships[0];a.kind='parameter_derivation';d.relationships.push({...a,from:a.to,to:a.from});},'Authored parameter derivation contains a cycle.'); -assert.throws(()=>decode('not JSON'),error=>error.code==='invalid'&&error.message==='Organization note is not valid JSON.');checks++; -assert.throws(()=>decode(' '.repeat(1048577)),error=>error.code==='invalid'&&error.message==='Organization note exceeds its retained text limit.');checks++; -assert.equal(checkCard(valid(),fixture.document.models[0],fixture.cards[0]),fixture.cards[0].version.text);checks++; -for(const change of [r=>{r.project_id='c'.repeat(32);},r=>{r.id='d'.repeat(64);},r=>{r.path='notes/other.md';},r=>{r.version.revision=3;},r=>{r.version.sha256='e'.repeat(64);},r=>{r.version.deleted=true;}]){ - const result=structuredClone(fixture.cards[0]);change(result); - assert.throws(()=>checkCard(valid(),fixture.document.models[0],result),error=>error.code==='invalid'&&error.message==='Model card differs from its exact retained organization reference.');checks++; -} -{ - const value=valid();value.models[0].summary.method='Not present in the captured card.'; - assert.throws(()=>checkCard(value,value.models[0],fixture.cards[0]),error=>error.message==='Authored summary differs from the captured model card.');checks++; -} -{ - const value=valid();value.relationships[0].excerpt='Not present in the captured card.'; - assert.throws(()=>checkCard(value,value.models[0],fixture.cards[0]),error=>error.message==='Authored relationship excerpt differs from its captured model card.');checks++; -} -console.log('PASS authored portfolio document:',checks,'literal contract/reference decisions; no native capture or browser claim.'); diff --git a/tests/test_project_model_portfolio_http.py b/tests/test_project_model_portfolio_http.py deleted file mode 100644 index 8fbda68f..00000000 --- a/tests/test_project_model_portfolio_http.py +++ /dev/null @@ -1,84 +0,0 @@ -"""Real authenticated note transport/cold reload; no model or recipe execution.""" -import hashlib -import json -import os -from pathlib import Path -import unittest -from unittest.mock import patch - -import project_workspace -import test_project_files_http as m1 -import test_project_files_m2_http as m2 - -ROOT = Path(__file__).resolve().parents[1] - - -@unittest.skipUnless(os.environ.get('TULDOK_DATABASE_URL'), 'Requires disposable PostgreSQL') -class ModelPortfolioHTTP(unittest.TestCase): - cleanup_owned = m1.ProjectFilesHTTP.cleanup_owned - select_host = m1.ProjectFilesHTTP.select_host - request = m1.ProjectFilesHTTP.request - state = m1.ProjectFilesHTTP.state - envelope = m1.ProjectFilesHTTP.envelope - action = m1.ProjectFilesHTTP.action - create = m1.ProjectFilesHTTP.create - arguments = m2.ProjectFilesM2HTTP.arguments - transport = m2.ProjectFilesM2HTTP.transport - call = m2.ProjectFilesM2HTTP.call - - def setUp(self): - self.operations = [] - m1.ProjectFilesHTTP.setUp(self) - gate = patch.object(project_workspace, 'M4_ENABLED', True) - gate.start() - self.addCleanup(gate.stop) - - def test_native_static_module_exact_note_revision_and_cold_reload(self): - status, html = self.request('/project-files') - self.assertEqual(status, 200) - self.assertIn(b'/project-model-portfolio.js', html) - self.assertIn(b'id="project-model-portfolio"', html) - status, script = self.request('/project-model-portfolio.js') - self.assertEqual(status, 200) - self.assertEqual(script, (ROOT/'static/project-model-portfolio.js').read_bytes()) - opened = self.create() - root = self.external/'alpha' - (root/'notes').mkdir() - paragraphs = {key: 'Literal retained '+key+' paragraph.' for key in - ('method','purpose','experiment','outcome','lesson','reproduction')} - card_text = '\n\n'.join(paragraphs.values())+'\nOriginal evidence remains.\n' - (root/'notes/model.md').write_text(card_text) - card = self.call('file_adopt',kind='note',path='notes/model.md',expected_revision=0, - expected_sha256=hashlib.sha256(card_text.encode()).hexdigest()) - guide = dict(format='project_model_portfolio_v1',project_id=opened['project']['project_id'], - title='Authored retained fixture',description='Synthetic presentation fixture; no scientific quality claim.', - authorship='retrospective',groups=[dict(id='pressure',label='Pressure methods',parent=None,description='An authored group.')], - models=[dict(id='fixture-fit',label='One retained fit',group_id='pressure',aliases=['Fixture'],review='source_reviewed', - card=dict(file_id=card['id'],path='notes/model.md',revision=1,sha256=card['sha256']),summary=paragraphs)],relationships=[]) - raw=(json.dumps(guide,ensure_ascii=False)+'\n').encode() - (root/'notes/00-fixture.portfolio.json').write_bytes(raw) - saved=self.call('file_adopt',kind='note',path='notes/00-fixture.portfolio.json',expected_revision=0, - expected_sha256=hashlib.sha256(raw).hexdigest()) - observed=self.call('file_get',file_id=saved['id'],revision=1) - self.assertEqual(observed['version']['text'].encode(),raw) - self.assertEqual(json.loads(observed['version']['text']),guide) - changed='A later authored card revision.\n' - (root/'notes/model.md').write_text(changed) - self.call('file_adopt',kind='note',path='notes/model.md',expected_revision=1, - expected_sha256=hashlib.sha256(changed.encode()).hexdigest()) - self.assertEqual(self.call('file_get',file_id=card['id'],revision=1)['version']['text'],card_text) - self.assertEqual(self.call('file_get',file_id=card['id'])['version']['text'],changed) - self.action('save') - expected=(root/'.tuldok/project.json').read_bytes() - self.action('close') - cold=os.environ.get('TULDOK_PROJECT_FILES_COLD_DATABASE_URL') - self.assertTrue(cold,'Independent cold role required for retained-note acceptance') - self.select_host(self.path/'cold-control',{'fixture':self.external},cold) - self.action('open',root='fixture',directory='alpha') - self.assertEqual((root/'.tuldok/project.json').read_bytes(),expected) - self.assertEqual(self.call('file_get',file_id=saved['id'],revision=1)['version']['text'].encode(),raw) - retained=self.call('file_get',file_id=card['id'],revision=1) - self.assertEqual(retained['version']['text'],card_text) - self.assertEqual(retained['project_id'],guide['project_id']) - self.assertEqual(self.call('file_get',file_id=card['id'])['version']['text'],changed) - self.action('close') diff --git a/tests/test_project_native_clients.py b/tests/test_project_native_clients.py deleted file mode 100644 index 0a336d04..00000000 --- a/tests/test_project_native_clients.py +++ /dev/null @@ -1,131 +0,0 @@ -"""Finite native transport boundaries; no claim of native process execution.""" -import copy -from types import SimpleNamespace -import unittest -from unittest.mock import Mock -import agent_api as api -import project_cli -import project_dispatch -from tuldok_client import ProjectFilesClient -from workbench import WorkbenchError -from test_project_files_m4_clients import ready,bound,READ,WRITE,PROJECT,ACTOR,CP,NEXT,KEY - -GRAPH='1'*32;RUN='2'*32;PHASE='3'*32 -ACTIONS=('native_preflight','native_submit','native_retry','native_reconcile') -def validation(): - return dict(status='valid',valid=True,errors=[],validation_token=CP,graph_revision=2, - execution_sha256=NEXT,release={'id':CP},runtime={'available':True}) -def phase(): - return dict(format='project_native_phase_v1',origin_catalog_id=PROJECT,phase_id=PHASE, - phase='probe',run_id=None,state='failed',spec_sha256=CP,receipt_sha256=NEXT) -def admission(): - return dict(format='project_run_admission_v1',origin_catalog_id=PROJECT,run_id=RUN,request_sha256=NEXT) -def client(value,owner=True): - raw=ready(dict(status=200,result=bound(value)),owner=owner) - raw._selected.update({'project_files.'+name:1 for name in ACTIONS});return raw - -class NativeClients(unittest.TestCase): - def test_four_closed_operations_current_owner_and_named_consumers(self): - for action in ACTIONS: - name='project_files.'+action - self.assertIn(name,api.PROJECT_FILES_M3);self.assertIn(name,project_dispatch.SUPPORTED_OPERATIONS) - self.assertEqual(api.contract(name)['authority'],'owner') - self.assertEqual(api.contract(name)['scopes'],['inspect','cancel' if action=='native_reconcile' else 'execute']) - self.assertTrue(callable(getattr(ProjectFilesClient(Mock()),action))) - project_cli.parser().parse_args(['--config','/not-read','file-'+action.replace('_','-'),'--arguments','/not-read']) - args=dict(WRITE,graph_id=GRAPH,revision=2) - api.validate_arguments('project_files.native_preflight',args) - for change in ({'runtime_snapshot_sha256':CP},{'cache':{}},{'serialized_validation':validation()},{'command':['python']}): - with self.assertRaises(api.AgentAPIError):api.validate_arguments('project_files.native_preflight',{**args,**change}) - args=dict(binding=READ['binding'],expected_checkpoint=CP,phase_id=PHASE) - api.validate_arguments('project_files.native_reconcile',args) - with self.assertRaises(api.AgentAPIError):api.validate_arguments('project_files.native_reconcile',dict(args,request_key=KEY)) - self.assertEqual(api.contract('project_files.native_reconcile')['retry'],'never') - raw=client(validation(),owner=False);raw._selected.pop('project_files.native_preflight') - with self.assertRaises(api.AgentAPIError):raw.call('project_files.native_preflight',dict(WRITE,graph_id=GRAPH,revision=2)) - raw._request.assert_not_called() - - def test_validation_admission_and_original_phase_identity_are_correlated(self): - raw=client(validation());sdk=ProjectFilesClient(raw);args=dict(WRITE,graph_id=GRAPH,revision=2) - sdk.native_preflight(**args) - for change in ({'graph_revision':3},{'validation_token':None},{'valid':False},{'cache':{}},{'phase_ref':dict(phase(),origin_catalog_id=ACTOR)}): - raw._request.return_value=dict(status=200,result=bound(dict(validation(),**change))) - with self.assertRaises(api.AgentAPIError):sdk.native_preflight(**args) - raw._request.return_value=dict(status=200,result=bound(admission())) - sdk.native_submit(**WRITE,graph_id=GRAPH,graph_revision=2,validation_token=CP) - raw._request.return_value=dict(status=200,result=bound(dict(admission(),origin_catalog_id=ACTOR))) - with self.assertRaises(api.AgentAPIError):sdk.native_retry(**WRITE,run_id=RUN) - raw._request.return_value=dict(status=200,result=bound(admission())) - with self.assertRaises(api.AgentAPIError):sdk.native_retry(**WRITE,run_id=RUN) - raw._request.return_value=dict(status=200,result=bound(phase())) - sdk.native_reconcile(binding=READ['binding'],expected_checkpoint=CP,phase_id=PHASE) - for change in ({'phase_id':GRAPH},{'origin_catalog_id':ACTOR},{'state':'running'},{'grant':{}}): - raw._request.return_value=dict(status=200,result=bound(dict(phase(),**change))) - with self.assertRaises(api.AgentAPIError):sdk.native_reconcile(binding=READ['binding'],expected_checkpoint=CP,phase_id=PHASE) - - def test_preflight_truth_fields_refuse_contradictions_and_nonstring_hashes(self): - args=dict(WRITE,graph_id=GRAPH,revision=2);raw=client(validation());sdk=ProjectFilesClient(raw) - failure=dict(status='unavailable',valid=False,errors=[dict(path='',message='Current CPU is unavailable',code='unavailable')],validation_token=None,release=None,runtime={'available':False}) - invalid=[ - dict(status='invalid',valid=True,errors=[7],release=None,runtime=None), - dict(status='invalid'),dict(errors=[dict(path='runtime',message='Unavailable',code='unavailable')]), - dict(release=None),dict(runtime=None),dict(runtime={'available':False}),dict(runtime={'available':1}), - dict(valid=False,status='invalid',errors=[],validation_token=None), - dict(failure,errors=[7]),dict(failure,status='other'),dict(failure,errors=[dict(path='',message='bad',code='unavailable',extra=True)]), - dict(failure,errors=[dict(path=7,message='bad',code='unavailable')]), - dict(failure,errors=[dict(path='',message='x'*2001,code='unavailable')]), - dict(failure,errors=failure['errors']*101), - dict(execution_sha256=int('7'*64)),dict(validation_token=int('7'*64)), - dict(execution_sha256=True),dict(validation_token=True), - ] - for change in invalid: - with self.subTest(change=change): - raw._request.return_value=dict(status=200,result=bound(dict(validation(),**change))) - with self.assertRaises(api.AgentAPIError) as caught:sdk.native_preflight(**args) - self.assertEqual(caught.exception.code,'transport') - for value in (validation(),dict(validation(),**failure)): - raw._request.return_value=dict(status=200,result=bound(value));self.assertEqual(sdk.native_preflight(**args)['value'],value) - - def test_dispatch_uses_only_four_fixed_current_execution_seams(self): - owner=Mock();projection=SimpleNamespace(session=SimpleNamespace(access=SimpleNamespace(require=Mock())),execution=owner) - project_dispatch.dispatch(projection,'project_files.native_preflight',dict(WRITE,graph_id=GRAPH,revision=2)) - owner.native_preflight.assert_called_once_with(GRAPH,2,CP,KEY) - project_dispatch.dispatch(projection,'project_files.native_submit',dict(WRITE,graph_id=GRAPH,graph_revision=2,validation_token=NEXT)) - owner.native_submit.assert_called_once_with(dict(graph_id=GRAPH,graph_revision=2,validation_token=NEXT),CP,KEY) - project_dispatch.dispatch(projection,'project_files.native_retry',dict(WRITE,run_id=RUN));owner.native_retry.assert_called_once_with(RUN,CP,KEY) - project_dispatch.dispatch(projection,'project_files.native_reconcile',dict(binding=READ['binding'],expected_checkpoint=CP,phase_id=PHASE));owner.native_reconcile.assert_called_once_with(PHASE,CP) - - def test_health_v2_adds_independent_bounded_current_phase_page_preserving_v1(self): - self.assertEqual(api.contract('project_files.execution_health',1)['sha256'],'c3b1d0017f5a49cf69c3a4c5c33e1d3db9846404d12627563d97ef40de7404a5') - legacy=dict(format='project_execution_health_v1',active_run_ids=[],active_count=0,offset=1,limit=1,local_owner_active=False,available=False,drain_required=True) - value=dict(legacy,native_phases=dict(items=[phase()],total=2,offset=1,limit=1)) - raw=client(value);raw._selected['project_files.execution_health']=2;sdk=ProjectFilesClient(raw) - sdk.execution_health(**READ,offset=1,limit=1) - for change in ({'offset':0},{'total':1},{'items':[dict(phase(),origin_catalog_id=ACTOR)]}): - raw._request.return_value=dict(status=200,result=bound(dict(value,native_phases={**value['native_phases'],**change}))) - with self.assertRaises(api.AgentAPIError):sdk.execution_health(**READ,offset=1,limit=1) - raw._selected['project_files.execution_health']=1 - raw._request.return_value=dict(status=200,result=bound(legacy));sdk.execution_health(**READ,offset=1,limit=1) - raw._request.return_value=dict(status=200,result=bound(value)) - with self.assertRaises(api.AgentAPIError):sdk.execution_health(**READ,offset=1,limit=1) - - def test_recipe_kind_is_inferred_and_contradictory_selector_refuses_before_effects(self): - import pipeline - pipelines=Mock();materials=Mock() - projection=SimpleNamespace(session=SimpleNamespace(access=SimpleNamespace(require=Mock())),materials=materials, - context=SimpleNamespace(models=Mock(),pipelines=pipelines),runtime_manifest=Mock()) - args=dict(WRITE,graph_id=GRAPH,revision=2,model={'kind':'model','catalog_id':PROJECT,'id':ACTOR,'revision':1,'sha256':CP}) - for recipe,builtin in (('external_recipe',False),(pipeline.MODEL_RECIPES[0] if isinstance(pipeline.MODEL_RECIPES,tuple) else next(iter(pipeline.MODEL_RECIPES)),True)): - pipelines.get.return_value={'id':GRAPH,'recipe':recipe};materials.reset_mock() - project_dispatch.dispatch(projection,'project_files.recipe_prepare',args) - self.assertIs(materials.prepare_recipe.call_args.kwargs['builtin'],builtin) - materials.reset_mock() - with self.assertRaises(WorkbenchError) as failure:project_dispatch.dispatch(projection,'project_files.recipe_prepare',dict(args,builtin=not builtin)) - self.assertEqual(failure.exception.code,'conflict') - materials.prepare_recipe.assert_not_called() - pipelines.get.return_value={'id':GRAPH,'recipe':'release_validation'};materials.reset_mock() - with self.assertRaises(WorkbenchError) as failure:project_dispatch.dispatch(projection,'project_files.recipe_prepare',args) - self.assertEqual(failure.exception.code,'unsupported') - materials.prepare_recipe.assert_not_called() - -if __name__=='__main__':unittest.main() diff --git a/tests/test_project_native_clients_http.py b/tests/test_project_native_clients_http.py deleted file mode 100644 index eb5d2191..00000000 --- a/tests/test_project_native_clients_http.py +++ /dev/null @@ -1,297 +0,0 @@ -"""Actual native public transports, gated by an explicit immutable qualification. - -One real owner CPU probe is reused by SDK/CLI/MCP. A real deferrable SQL ACK -fault starts no worker GO; original local phase reconciliation never repeats GO. -There is no model fit, training Run, provider, or imported execution authority. -""" -from datetime import timedelta -import hashlib -from http.server import ThreadingHTTPServer -import importlib.util -import json -import os -from pathlib import Path -import shutil -import subprocess -import sys -import tempfile -import threading -import time -import unittest -from unittest.mock import patch -import uuid - -# Script-mode browser fixtures must find the repository without PYTHONPATH. -ROOT=Path(__file__).resolve().parents[1] -sys.path.insert(0,str(ROOT)) - -import psycopg -from psycopg import sql - -import agent_api as api -from app import make_handler -from auth_helpers import ExplicitOwnerFixture -from metadata import connection_info -from project_workspace import ProjectWorkspace -import project_workspace -from tuldok_client import ProjectFilesClient - -MANIFEST_ENV='TULDOK_NATIVE_PUBLIC_FREEZE_MANIFEST' - - -def frozen_subject(): - name=os.environ.get(MANIFEST_ENV) - if not name:raise AssertionError('Lead must provide '+MANIFEST_ENV+' before actual native qualification') - path=Path(name);value=json.loads(path.read_text()) - current={name:hashlib.sha256((ROOT/name).read_bytes()).hexdigest() for name in value['files']} - if current!=value['files']:raise AssertionError('Immutable native public subject changed') - return dict(manifest_sha256=hashlib.sha256(path.read_bytes()).hexdigest(),files=current) - - -class NativePublicFixture: - """Test-owned real host and optional ACK fault; production owners stay real.""" - def __init__(self,path,*,dsn=None,cold=False): - if os.environ.get('TULDOK_NATIVE_PROJECT_GO')!='1':raise AssertionError('Explicit native qualification GO required') - if not project_workspace.M3_ENABLED:raise AssertionError('M3 must be explicitly enabled in the qualified subject') - self.path=Path(path);self.path.mkdir(parents=True,exist_ok=True) - self.external=self.path/'external';self.external.mkdir(exist_ok=True) - self.control=self.path/'control';self.dsn=dsn or os.environ['TULDOK_DATABASE_URL'] - self.workspace=ProjectWorkspace(self.control,{'fixture':self.external},dsn=self.dsn) - self.owner=ExplicitOwnerFixture.bootstrap(self.workspace) - self.go_events=[];self.fired=[];self.forbidden=[];self.fault_db=None;self.original_before=None;self.patches=[] - import recipe_process - original_go=recipe_process.Handle.go - def observed(handle,helper): - projection=self.workspace._projection - self.go_events.append(dict(phase_id=handle.spec['attempt_id'],in_transaction=projection.db.in_transaction)) - if projection.db.in_transaction:raise AssertionError('Native GO occurred before outer SQL acknowledgement') - return original_go(handle,helper) - self.patches.append(patch.object(recipe_process.Handle,'go',new=observed));self.patches[-1].start() - if cold: - def forbidden(*args,**kwargs): - self.forbidden.append('native-prepare-or-Runs');raise AssertionError('Cold Open attempted native process or Runs construction') - for target in ('project_native_process.prepare','runs.Runs'): - self.patches.append(patch(target,side_effect=forbidden));self.patches[-1].start() - self.server=ThreadingHTTPServer(('127.0.0.1',0),make_handler(self.workspace)) - self.thread=threading.Thread(target=self.server.serve_forever,daemon=True);self.thread.start() - self.origin='http://127.0.0.1:'+str(self.server.server_port) - - @property - def projection(self):return self.workspace._projection - - def seed(self): - from test_project_native_study import prepare_text_source - with self.owner.bound(self.workspace): - projection=self.projection - if projection is None:raise AssertionError('Create the test project through real HTTP before seeding') - rows,release=prepare_text_source(projection,key_prefix='public-native-'+uuid.uuid4().hex) - body=dict(name='Native public text CPU fixture Ω',recipe='text_classification',release_id=release['id']) - graph=projection.materials.mutate_definition('pipeline_graph','graphs.create',None,body, - projection.session.snapshot['checkpoint'],'public-native-graph-'+uuid.uuid4().hex, - lambda:projection.pipelines.create(body)) - return dict(graph_id=graph['id'],revision=graph['revision'],release_id=release['id'],records=len(rows)) - - def install_fault(self): - if self.original_before is not None:raise AssertionError('Only one explicit fixture fault at a time') - projection=self.projection;db=projection.db;self.fault_db=db - with db.lock: - db.execute('CREATE TEMP TABLE public_native_ack_parent(id INT PRIMARY KEY)') - db.execute('CREATE TEMP TABLE public_native_ack_child(id INT REFERENCES public_native_ack_parent(id) DEFERRABLE INITIALLY DEFERRED)') - self.original_before=db._project_before_commit - original=self.original_before - def before(): - target=any(doc['events'][-1]['state']=='go_intent' for doc in projection.execution.native._dirty.values()) - original() - if target and not self.fired: - self.fired.append(True);db.execute('INSERT INTO public_native_ack_child VALUES(1)') - db._project_before_commit=before - return dict(installed=True,kind='real_deferrable_sql_after_canonical_go_intent') - - def clear_fault(self): - if self.original_before is not None: - self.fault_db._project_before_commit=self.original_before;self.original_before=None - - def facts(self): - p=self.projection - if p is None:return dict(go_events=list(self.go_events),fired=list(self.fired),forbidden=list(self.forbidden),selected=False) - with p.db.lock: - records=p.session.snapshot['records'] - return dict(go_events=list(self.go_events),fired=list(self.fired),forbidden=list(self.forbidden),selected=True, - available=p.session.available,workspace_runs=p.db.execute('SELECT count(*) FROM workspace_runs').fetchone()[0], - portable_phase_count=sum(r['family']=='native_execution_history' for r in records), - pending=p.custody.has_pending if p.custody is not None else False) - - def close(self): - self.clear_fault();self.server.shutdown();self.server.server_close();self.thread.join(5) - close_failure=None - try: - try:self.workspace.close() - except BaseException as error: - close_failure=error - # A failed assertion may leave an original ACK fence. Dispose - # only this fixture's actual bounded children and handles; - # never claim that public Close or reconciliation succeeded. - drainage=[] - for projection in (self.workspace._projection,self.workspace._retained_recovery): - if projection is None:continue - execution=projection.execution - if execution._runs is not None:raise AssertionError('This fixture must never admit a training Run') from error - if execution.native._active:raise AssertionError('Native request still active during fixture disposal') from error - for handle in tuple(execution.native._handles.values()): - receipt=handle.close_control() - if not receipt or not receipt.get('drained'):raise AssertionError('Fixture child drainage unconfirmed') from error - drainage.append(dict(drained=True,go_received=receipt.get('go_received'))) - if projection.sources is not None:projection.sources.close() - projection.artifacts.close();projection.db.close() - if self.workspace._store is not None:self.workspace._store.close() - for _path,descriptor in self.workspace._roots.values():os.close(descriptor) - self.workspace._roots.clear();self.workspace.db.close();self.workspace._closed=True - report=Path(os.environ.get('TULDOK_QA_OUTPUT_ROOT','/workspace/scratch/tuldok-save-load-qa/artifacts'))/'native-public-cleanup' - report.mkdir(parents=True,exist_ok=True) - (report/(uuid.uuid4().hex+'.json')).write_text(json.dumps(dict(public_close_succeeded=False, - close_error=type(error).__name__,fixture_children=drainage),indent=2)+'\n') - finally: - for context in reversed(self.patches):context.stop() - # Cleanup only manifests created below this fixture's own control. - with psycopg.connect(connection_info(self.dsn),autocommit=True) as connection: - for manifest in self.control.rglob('.tuldok.json'): - value=json.loads(manifest.read_bytes()) - schema='projection_'+value['projection_id'] if value['version']==2 else 'catalog_'+value['dataset_id'] - connection.execute(sql.SQL('DROP SCHEMA IF EXISTS {} CASCADE').format(sql.Identifier(schema))) - if close_failure is not None:raise close_failure - - -@unittest.skipUnless(os.environ.get('TULDOK_NATIVE_PROJECT_GO')=='1' and os.environ.get('TULDOK_DATABASE_URL'), - 'Requires explicit native qualification GO and disposable PostgreSQL') -class NativePublicClientsHTTP(unittest.TestCase): - def setUp(self): - self.subject=frozen_subject();self.started=time.monotonic();self.performed=[];self.completed=False - self.assertTrue(os.environ.get('TULDOK_TRAINING_PYTHON'),'Explicit current qualified CPU interpreter required') - self.temp=tempfile.TemporaryDirectory(prefix='tuldok-native-public-');self.addCleanup(self.temp.cleanup) - self.path=Path(self.temp.name);self.fixture=NativePublicFixture(self.path) - self.addCleanup(self.fixture.close);self.addCleanup(self.receipt) - self.owner=ProjectFilesClient(api.ProjectFilesOwnerClient(self.fixture.origin,self.fixture.owner.token,self.fixture.owner.catalog_id,timeout=60)) - self.environment={**os.environ,'PYTHONDONTWRITEBYTECODE':'1'} - - def receipt(self): - end={name:hashlib.sha256((ROOT/name).read_bytes()).hexdigest() for name in self.subject['files']} - directory=Path(os.environ.get('TULDOK_QA_OUTPUT_ROOT','/workspace/scratch/tuldok-save-load-qa/artifacts'))/'native-public-clients';directory.mkdir(parents=True,exist_ok=True) - (directory/(self._testMethodName+'-'+uuid.uuid4().hex+'.json')).write_text(json.dumps(dict(status='pass' if self.completed else 'failed', - test=self.id(),seconds=round(time.monotonic()-self.started,3),performed=self.performed,subject=self.subject,source_stable=end==self.subject['files'], - end_sha256=end,facts=self.fixture.facts(),fixture='Real owner HTTP/SDK/CLI/MCP; one CPU probe, real deferred SQL ACK fault with zero GO, no model training.'),indent=2)+'\n') - self.assertEqual(end,self.subject['files']) - - def bound(self,*,mutation=False,key=None): - state=self.owner.status() - return dict(binding=state['binding'],**({'expected_checkpoint':state['project']['checkpoint'],'request_key':key or uuid.uuid4().hex} - if mutation else {'checkpoint':state['project']['checkpoint']})) - - def config(self,name,token): - token_file=self.path/(name+'.token');token_file.write_text(token+'\n');token_file.chmod(0o600) - path=self.path/(name+'.json');path.write_text(json.dumps(dict(endpoint=self.fixture.origin,catalog_id=self.fixture.owner.catalog_id,token_file=str(token_file),timeout=60)));path.chmod(0o600) - return path - - def cli(self,config,action,args,*,owner=True,success=True): - file=self.path/('arguments-'+uuid.uuid4().hex+'.json');file.write_text(json.dumps(args)) - result=subprocess.run([sys.executable,str(ROOT/'project_cli.py'),'--config',str(config),*(['--owner-project-files'] if owner else []), - 'file-'+action.replace('_','-'),'--arguments',str(file)],cwd=ROOT,env=self.environment,capture_output=True,text=True,timeout=60) - self.assertEqual(result.returncode==0,success,result.stderr) - self.assertNotIn(self.fixture.owner.token,result.stdout+result.stderr) - return json.loads(result.stdout) if success else result - - @unittest.skipUnless(importlib.util.find_spec('mcp') and importlib.util.find_spec('anyio'),'Requires optional locked MCP dependencies') - def test_real_native_preflight_replay_zero_go_failure_and_original_phase_recovery(self): - import anyio - from mcp import ClientSession,StdioServerParameters - from mcp.client.stdio import stdio_client - state=self.owner.status();opened=self.owner.new(binding=state['binding'],expected_checkpoint=None,request_key=uuid.uuid4().hex, - root='fixture',directory='alpha',name='Native public actual transport Ω') - graph=self.fixture.seed();initial=self.bound(mutation=True) - args=dict(initial,graph_id=graph['graph_id'],revision=graph['revision']) - result=self.owner.native_preflight(**args);self.assertTrue(result['value']['valid'],result) - self.assertEqual(len(self.fixture.go_events),1);self.assertEqual(self.fixture.facts()['workspace_runs'],0) - replay=self.cli(self.config('owner',self.fixture.owner.token),'native_preflight',args) - self.assertEqual(replay,result);self.assertEqual(len(self.fixture.go_events),1) - self.performed.append('Real owner SDK CPU preflight; named owner CLI exact request replay without another GO') - with self.fixture.owner.bound(self.fixture.workspace): - agent=self.fixture.workspace.access.issue(dict(label='Native transport ordinary editor',scopes=['inspect','edit'])) - ordinary=ProjectFilesClient(api.AgentClient(self.fixture.origin,agent['token'],self.fixture.owner.catalog_id,timeout=60)) - denied=dict(self.bound(mutation=True),graph_id=graph['graph_id'],graph_revision=graph['revision'],validation_token=result['value']['validation_token']) - before=self.fixture.projection.session.snapshot - with self.assertRaises(api.AgentAPIError) as error:ordinary.native_submit(**denied) - self.assertEqual(error.exception.status,403);self.assertEqual(error.exception.code,'forbidden');self.assertEqual(self.fixture.projection.session.snapshot,before) - self.assertEqual(len(self.fixture.go_events),1);self.assertEqual(self.fixture.facts()['workspace_runs'],0) - negative=self.cli(self.config('agent',agent['token']),'native_submit',denied,owner=False,success=False) - self.assertEqual((json.loads(negative.stderr)['status'],json.loads(negative.stderr)['code']),(403,'forbidden')) - self.performed.append('Actual SDK and named CLI ordinary editor submission denied before probe/admission effects') - owner_config=self.config('mcp-owner',self.fixture.owner.token) - async def exercise(): - params=StdioServerParameters(command=sys.executable,args=[str(ROOT/'mcp_stdio.py'),'--project-files-owner','--config',str(owner_config)],cwd=str(ROOT),env=self.environment) - with (self.path/'mcp.stderr').open('w+') as diagnostics: - async with stdio_client(params,errlog=diagnostics) as (reader,writer): - async with ClientSession(reader,writer,read_timeout_seconds=timedelta(seconds=60)) as session: - await session.initialize();tools={tool.name:tool for tool in (await session.list_tools()).tools} - for action in ('native_preflight','native_submit','native_retry','native_reconcile','execution_health'): - self.assertIn('project_files_'+action,tools) - self.assertEqual(tools['project_files_execution_health'].outputSchema,api.operation('project_files.execution_health',2)['outputSchema']) - async def call(action,arguments,status=200): - response=await session.call_tool('project_files_'+action,arguments);envelope=response.structuredContent - self.assertEqual(envelope['status'],status,envelope);self.assertEqual(response.isError,status>=400) - api.validate_output('project_files.'+action,envelope,2 if action=='execution_health' else 1) - return envelope['result'] - self.assertEqual(await call('native_preflight',args),result);self.assertEqual(len(self.fixture.go_events),1) - stale=dict(args,request_key=uuid.uuid4().hex,graph_revision=graph['revision'],validation_token=result['value']['validation_token']);stale.pop('revision') - rejected=await call('native_submit',stale,status=409);self.assertEqual(rejected['code'],'stale_project') - await call('native_retry',dict(self.bound(mutation=True),run_id='9'*32),status=409) - self.assertEqual(len(self.fixture.go_events),1);self.assertEqual(self.fixture.facts()['workspace_runs'],0) - self.fixture.install_fault() - failed_args=dict(self.bound(mutation=True),graph_id=graph['graph_id'],revision=graph['revision']) - response=await session.call_tool('project_files_native_preflight',failed_args) - self.assertTrue(response.isError,response);self.assertEqual(response.structuredContent['status'],503,response.structuredContent) - api.validate_output('project_files.native_preflight',response.structuredContent) - self.assertEqual(self.fixture.fired,[True]);self.assertEqual(len(self.fixture.go_events),1) - self.fixture.clear_fault();current=self.bound() - health=await call('execution_health',current) - phases=health['value']['native_phases']['items'];failed=[p for p in phases if p['state'] in ('ready','go_intent','unknown')] - self.assertEqual(len(failed),1,phases);phase_id=failed[0]['phase_id'] - self.assertEqual(health['checkpoint'],current['checkpoint']) - cli_health=self.cli(owner_config,'execution_health',current) - self.assertEqual(cli_health,health) - unknown=self.cli(owner_config,'native_reconcile',dict(binding=current['binding'],expected_checkpoint=current['checkpoint'],phase_id='0'*32),success=False) - self.assertEqual(json.loads(unknown.stderr)['status'],409);self.assertEqual(len(self.fixture.go_events),1) - recovered=await call('native_reconcile',dict(binding=current['binding'],expected_checkpoint=current['checkpoint'],phase_id=phase_id)) - self.assertEqual(recovered['value']['state'],'failed');self.assertEqual(len(self.fixture.go_events),1) - self.assertFalse(self.fixture.facts()['pending']);self.assertTrue(self.fixture.projection.session.available) - self.performed.append('Actual owner MCP exact preflight replay, real deferred FK failure with zero additional GO, named CLI health v2 current phase and foreign-phase refusal; original owner MCP reconciliation') - anyio.run(exercise) - self.assertEqual(self.fixture.facts()['workspace_runs'],0) - from test_project_files_http import canonical_bytes - for raw in canonical_bytes(self.fixture.external/'alpha').values(): - self.assertNotIn(self.fixture.owner.token.encode(),raw);self.assertNotIn(agent['token'].encode(),raw) - self.completed=True - - -def serve_fixture(): - import argparse - parser=argparse.ArgumentParser();parser.add_argument('--serve',action='store_true');parser.add_argument('--root',type=Path,required=True);parser.add_argument('--cold',action='store_true');args=parser.parse_args() - frozen_subject();fixture=NativePublicFixture(args.root,cold=args.cold) - print(json.dumps(dict(origin=fixture.origin,control=str(fixture.control),external=str(fixture.external))),flush=True) - try: - for line in sys.stdin: - command=json.loads(line);action=command['action'] - try: - if action=='seed':value=fixture.seed() - elif action=='install_fault':value=fixture.install_fault() - elif action=='clear_fault':fixture.clear_fault();value={'cleared':True} - elif action=='facts':value=fixture.facts() - elif action=='stop':print(json.dumps(dict(id=command['id'],result={'stopped':True})),flush=True);break - else:raise AssertionError('Unknown fixture command') - print(json.dumps(dict(id=command['id'],result=value)),flush=True) - except BaseException as error: - print(json.dumps(dict(id=command['id'],error=type(error).__name__+': '+str(error))),flush=True) - finally:fixture.close() - - -if __name__=='__main__': - if '--serve' in sys.argv:serve_fixture() - else:unittest.main() diff --git a/tests/test_project_native_execution.py b/tests/test_project_native_execution.py deleted file mode 100644 index 18979e24..00000000 --- a/tests/test_project_native_execution.py +++ /dev/null @@ -1,721 +0,0 @@ -"""Finite native phase evidence and original-host custody; no imported launch.""" -import copy -import hashlib -import json -import os -from pathlib import Path -import tempfile -from types import SimpleNamespace -import unittest -from unittest.mock import patch -import uuid -from urllib.error import HTTPError -from urllib.request import Request, urlopen - -import psycopg -import recipe_process -from pipeline import adapter_identity_for_graph, digest -from project_artifacts import ProjectArtifacts -from project_custody import ProjectCustody, NATIVE_PHASE_LIMIT, validate as validate_custody -from project_native_execution import ProjectNativeExecution, decode_records, phase_reference, classify_probe, OBSERVATIONS, FORMAT, FAMILY -from project_native_process import prepare -from project_session import ProjectSessionError -from project_store import ProjectStore -from workbench import WorkbenchError -import test_project_native_preparation as preparation_fixture -import test_project_study_execution as study_fixture -import test_project_files_http as http_fixture - - -class NativePhaseCodecs(unittest.TestCase): - def setUp(self): - self.temporary=tempfile.TemporaryDirectory(prefix='tuldok-native-phase-') - self.addCleanup(self.temporary.cleanup);self.path=Path(self.temporary.name) - self.store=ProjectStore.create(self.path/'project','Native phase fixture','new-native-phase','a'*64) - self.addCleanup(self.store.close) - self.artifacts=ProjectArtifacts(self.store);self.addCleanup(self.artifacts.close) - self.project=self.store.snapshot()['project_id'];self.phase=uuid.uuid4().hex - executable=str(Path('/usr/bin/python3').resolve()) - raw=Path(executable).read_bytes();self.source=b'print("inert codec fixture")\n' - self.prepared=prepare(self.path/'phase',phase='probe',attempt_id=self.phase,request_sha256='b'*64, - runtime=dict(executable=executable,executable_sha256=hashlib.sha256(raw).hexdigest(), - trusted_install_owner_uid=os.stat('/usr').st_uid, - files={executable:dict(sha256=hashlib.sha256(raw).hexdigest(),bytes=len(raw))}), - worker='text_training.py',sources={'text_training.py':self.source}) - definition={'text_training.py':hashlib.sha256(self.source).hexdigest()} - self.document=dict(format=FORMAT,origin_catalog_id=self.project,phase_id=self.phase, - phase='probe',run_id=None,recipe='text_classification',request_key='native-phase-fixture', - request_sha256='b'*64,actor_id='c'*32, - definition_identity=dict(definition_files=definition,adapter_definition_sha256=digest(definition)), - spec=self.prepared.spec,events=[self.event('prepared')],payloads=[], - observations=dict.fromkeys(OBSERVATIONS),probe_result=None) - self.payload('spec.json',recipe_process.encoded(self.prepared.spec),'execution_spec') - self.payload('source/text_training.py',self.source,'execution_source') - - @staticmethod - def event(state,helper=None,receipt_sha256=None): - return dict(state=state,at='2026-10-22T12:00:00+00:00',actor_id='c'*32,helper=helper,receipt_sha256=receipt_sha256) - - def payload(self,name,raw,role): - blob=dict(sha256=hashlib.sha256(raw).hexdigest(),bytes=len(raw)) - self.artifacts.publish_bytes(raw,dict(format='project_artifact_v1',**blob)) - self.document['payloads'].append(dict(name=name,blob=blob,role=role, - preservation='unique',required_for=['execution_proof'])) - for key,(filename,maximum) in OBSERVATIONS.items(): - if name==filename: - if key=='probe_stdout':self.document['probe_result']=classify_probe(self.document['recipe'],raw) - try:self.document['observations'][key]=raw.decode('utf8') if len(raw)<=maximum else None - except UnicodeError:self.document['observations'][key]=None - return blob - - def records(self): - return [dict(family=FAMILY,id=self.project+'.'+self.phase,document=copy.deepcopy(self.document)), - *[dict(family='project_artifact',id=edge['blob']['sha256'], - document=dict(format='project_artifact_v1',**edge['blob'])) for edge in self.document['payloads']]] - - def completed(self,stdout=None): - helper=recipe_process.identity(os.getpid()) - stdout=stdout if stdout is not None else recipe_process.encoded(dict(schema_version=1,available=True, - adapter=adapter_identity_for_graph(dict(recipe='text_classification')), - runtime=dict(python='3.12.fixture',device='cpu',threads=1, - scikit_learn='1.7.2',numpy='fixture',scipy='fixture',Pillow='fixture'),problems=[]))+b'\n' - stderr=b'' - receipt=dict(schema_version=1,attempt_id=self.phase,request_sha256='b'*64, - spec_sha256=hashlib.sha256(recipe_process.encoded(self.document['spec'])).hexdigest(), - helper=helper,go_received=True,spawn_closed=True,drained=True,echild=True, - outcome='completed',reason='completed',leader_returncode=0, - streams={name:dict(bytes=len(raw),sha256=hashlib.sha256(raw).hexdigest()) - for name,raw in (('stdout',stdout),('stderr',stderr))}) - self.payload('stdout.log',stdout,'measured_stream');self.payload('stderr.log',stderr,'measured_stream') - blob=self.payload('receipt.json',recipe_process.encoded(receipt),'custody_proof') - self.document['events']=[self.event('prepared'),self.event('ready',helper), - self.event('go_intent',helper),self.event('completed',helper,blob['sha256'])] - return helper,receipt - - def test_small_canonical_proofs_reject_semantic_tampering_and_classify_malformed_process_output(self): - self.completed();records=self.records() - forged=copy.deepcopy(records) - forged[0]['document']['observations']['drain_receipt']+=' ' - with self.assertRaisesRegex(WorkbenchError,'Canonical native observation differs'): - decode_records(forged) - for raw,outcome in ((b'package warning\n{}','invalid_observation'),(b'\xff','invalid_utf8'),(b'x'*32769,'too_large')): - self.document['payloads']=[edge for edge in self.document['payloads'] - if edge['name'] not in ('stdout.log','stderr.log','receipt.json')] - self.completed(raw) - self.assertEqual(self.document['probe_result']['outcome'],outcome) - self.assertEqual(decode_records(self.records())[self.project+'.'+self.phase],self.document) - - def test_prepared_and_measured_terminal_are_exact_inert_evidence(self): - self.assertEqual(decode_records(self.records(),artifacts=self.artifacts)[self.project+'.'+self.phase],self.document) - helper,receipt=self.completed();records=self.records() - with (patch('subprocess.Popen',side_effect=AssertionError('Historical phase launched')), - patch('project_native_execution.prepare',side_effect=AssertionError('Historical phase prepared'))): - decoded=decode_records(records,artifacts=self.artifacts) - self.assertEqual(decoded[self.project+'.'+self.phase],self.document) - self.assertEqual(phase_reference(self.document)['receipt_sha256'], - hashlib.sha256(recipe_process.encoded(receipt)).hexdigest()) - - def test_environment_source_and_terminal_receipt_tampering_are_rejected(self): - self.completed();records=self.records() - changes=(lambda value:value['spec']['env'].update(ACCESS_TOKEN='never-retain'), - lambda value:value['events'][-1].update(helper=recipe_process.identity(os.getpid())|{'pid':1}), - lambda value:value['payloads'].pop(1), - lambda value:value.update(unclassified=True), - lambda value:value['events'][-1].update(receipt_sha256='d'*64)) - for change in changes: - malformed=copy.deepcopy(records);change(malformed[0]['document']) - with self.assertRaises(WorkbenchError):decode_records(malformed,artifacts=self.artifacts) - - def test_historical_uid_and_original_paths_are_not_current_launch_authority(self): - self.document['spec']['trusted_install_owner_uid']=os.getuid() - self.document['payloads']=[edge for edge in self.document['payloads'] if edge['name']!='spec.json'] - self.payload('spec.json',recipe_process.encoded(self.document['spec']),'execution_spec') - with patch('subprocess.Popen',side_effect=AssertionError('No historical execution')): - self.assertEqual(len(decode_records(self.records(),artifacts=self.artifacts)),1) - with self.assertRaises(recipe_process.ProcessError):recipe_process.validate_spec(self.document['spec']) - - def test_declared_missing_phase_bytes_stay_inert_and_present_corruption_is_rejected(self): - self.completed();records=self.records() - source=next(edge['blob'] for edge in self.document['payloads'] if edge['name']=='source/text_training.py') - path=self.path/'project/artifacts/sha256'/source['sha256'] - path.chmod(0o600);path.write_bytes(b'x'*source['bytes']) - with self.assertRaisesRegex(WorkbenchError,'Present native evidence differs'): - decode_records(records,artifacts=self.artifacts) - for entry in (self.path/'project/artifacts/sha256').iterdir():entry.unlink() - with (patch('subprocess.Popen',side_effect=AssertionError('Missing historical bytes executed')), - patch('project_native_execution.prepare',side_effect=AssertionError('Missing bytes regenerated'))): - decoded=decode_records(records,artifacts=self.artifacts) - self.assertEqual(decoded[self.project+'.'+self.phase],self.document) - self.assertEqual(self.artifacts.status(dict(format='project_artifact_v1',**source))['state'],'missing') - - def test_native_journal_upgrade_binds_physical_phase_and_requires_terminal_drain_ack(self): - control=self.path/'host';control.mkdir() - owner=ProjectCustody(control,'e'*32);journal=owner.for_projection(self.store,'f'*32) - self.assertEqual(journal.snapshot()['format'],'project_local_custody_v1') - journal.native_prepared(self.document) - self.assertEqual(journal.snapshot()['format'],'project_local_custody_v2') - self.assertEqual(len(owner.pending(self.store)),1) - with self.assertRaises(WorkbenchError):journal.native_confirmed(self.phase) - journal.native_launch_intent(self.phase) - helper,receipt=self.completed();journal.native_launched(self.phase,helper) - ready=copy.deepcopy(self.document);ready['events']=ready['events'][:2];journal.native_observed(ready) - go=copy.deepcopy(self.document);go['events']=go['events'][:3];journal.native_observed(go) - fresh=owner.for_projection(self.store,'f'*32) - self.assertEqual(fresh.snapshot()['native_phases'][0]['state'],'go_intent') - bad=copy.deepcopy(self.document);bad['request_sha256']='0'*64 - with self.assertRaises(WorkbenchError):fresh.native_observed(bad) - fresh.native_observed(self.document);fresh.native_confirmed(self.phase) - self.assertFalse(owner.for_projection(self.store,'f'*32).has_pending) - self.assertEqual(owner.pending(self.store),[]) - - def test_native_admission_private_version_preserves_original_binding_without_imported_authority(self): - control=self.path/'host';control.mkdir() - owner=ProjectCustody(control,'e'*32);journal=owner.for_projection(self.store,'f'*32) - run=dict(id='1'*32,admission_id='2'*32,request_sha256='3'*64, - graph_sha256='4'*64,release_sha256='5'*64,runtime={'observed':'fixture'}) - journal.observe_native_admission(run) - current=owner.for_projection(self.store,'f'*32) - self.assertEqual(current.snapshot()['format'],'project_local_custody_v3') - self.assertEqual(current.snapshot()['native_admissions'][0]['phase_started'],False) - self.assertTrue(current.has_pending);self.assertEqual(len(owner.pending(self.store)),1) - changed=dict(run,admission_id='6'*32) - with self.assertRaises(WorkbenchError):current.observe_native_admission(changed) - malformed=current.snapshot();malformed['native_admissions'][0]['grant']='not-authority' - with self.assertRaises(WorkbenchError):validate_custody(malformed) - current.settle_native_admission(run['id']) - self.assertFalse(current.has_pending) - - def test_native_phase_capacity_covers_all_current_worker_phases_and_one_foreground(self): - from run_capacity import MAX_ATTEMPTS - control=self.path/'host';control.mkdir() - journal=ProjectCustody(control,'e'*32).for_projection(self.store,'f'*32) - value=journal.snapshot();value.update(format='project_local_custody_v3',native_admissions=[]) - entry=dict(phase_id='1'*32,phase='probe',run_id=None,request_sha256='2'*64, - spec_sha256='3'*64,state='prepared',helper=None,receipt_sha256=None) - value['native_phases']=[dict(entry,phase_id=f'{index+1:032x}') for index in range(3*MAX_ATTEMPTS+1)] - self.assertEqual(len(validate_custody(value)['native_phases']),NATIVE_PHASE_LIMIT) - value['native_phases'].append(dict(entry,phase_id='f'*32)) - with self.assertRaisesRegex(WorkbenchError,'Too many unresolved native phases'):validate_custody(value) - - def test_native_exposure_observation_is_portable_science_and_rejects_unclassified_fields(self): - from runs import project_run_projection - from test_project_history import legacy_run - run=legacy_run() - observation=dict(exposed=True,events=[dict(id='1'*32,record_id='2'*32,source_hash='3'*64, - reason='Actual prior exposure',run_id=run['id'],release_id=run['release_id'],created_at=run['created_at'])]) - run['execution_test_exposure']=observation - projected=project_run_projection(run) - self.assertEqual(projected['execution_test_exposure'],observation) - self.assertNotIn('worker',projected) - run['execution_test_exposure']['grant']='not-science' - with self.assertRaises(WorkbenchError):project_run_projection(run) - - def test_model_aware_job_evidence_must_match_run_even_when_all_template_hashes_are_consistent(self): - import audio_training - import image_training - import model_evidence - import one_fit_evidence - import text_training - for adapter in (text_training,audio_training,image_training): - parameters={key:rule['default'] for key,rule in adapter.PARAMETER_BOUNDS.items()} - if adapter is image_training:parameters.update(widths=[4,8,16],input_size=32,head='linear') - owner=model_evidence if adapter is image_training else one_fit_evidence.contract(adapter) - context=dict(material_sha256='1'*64,model_sha256='2'*64,adapter_sha256='3'*64, - profile=owner.profile(self.project,'2'*64,parameters,2)) - worker=Path(adapter.__file__).name;source=b'# Exact authored retained worker; never executed.\n' - definition={worker:hashlib.sha256(source).hexdigest()} - run=dict(id='4'*32,dataset_id=self.project,graph=dict(recipe=adapter.MODEL_RECIPE),graph_sha256='5'*64, - release_id='6'*64,release_sha256='6'*64,parameters=parameters,adapter=adapter.MODEL_ADAPTER, - runtime=dict(definition_files=definition),evidence_context=context) - def records_for(change=None): - phase=uuid.uuid4().hex;stage=self.path/('model-context-'+phase);output=stage/'output' - job=dict(schema_version=2,dataset_id=self.project,run_id=run['id'],graph_sha256=run['graph_sha256'], - release_id=run['release_id'],release_sha256=run['release_sha256'],release_path=str(self.path/'retained-release.zip'), - output_dir=str(output),parameters=parameters,parent_pid=1) - if adapter is image_training:job['evidence_context']=copy.deepcopy(context) - else:job.update(one_fit_evidence.job_for_run(run,output),release_path=str(self.path/'retained-release.zip')) - if change is not None:change(job) - # These forgeries pass the live adapter's well-formed job - # decoder. Every captured-file/template/spec SHA is freshly - # rebuilt, isolating the missing scientific relation to Run. - self.assertEqual(adapter._checked_job(job),job) - spec=self.prepared.spec - executable=spec['argv'][0] - runtime=dict(executable=executable,executable_sha256=spec['executable_sha256'], - trusted_install_owner_uid=spec['trusted_install_owner_uid'], - files={row['path']:{key:row[key] for key in ('sha256','bytes')} for row in spec['runtime_files']}) - prepared=prepare(stage,phase='train',attempt_id=phase,request_sha256='7'*64,runtime=runtime, - worker=worker,sources={worker:source},job=job,model_aware=True) - self.document=dict(format=FORMAT,origin_catalog_id=self.project,phase_id=phase,phase='train', - run_id=run['id'],recipe=adapter.MODEL_RECIPE,request_key='model-context-'+phase,request_sha256='7'*64, - actor_id='c'*32,definition_identity=dict(definition_files=definition,adapter_definition_sha256=digest(definition)), - spec=prepared.spec,events=[self.event('prepared')],payloads=[],observations=dict.fromkeys(OBSERVATIONS),probe_result=None) - self.payload('spec.json',recipe_process.encoded(prepared.spec),'execution_spec') - for item in prepared.spec['captured_files']: - name=str(Path(item['path']).relative_to(stage)) - self.payload(name,Path(item['path']).read_bytes(),'execution_spec' if name=='native-job-template.json' else 'execution_source') - records=self.records();records[0]['id']=self.project+'.'+phase - return records+[dict(family='run_history',id=self.project+'.'+run['id'],document={'run':copy.deepcopy(run)})] - with self.subTest(adapter=adapter.MODEL_RECIPE),patch('subprocess.Popen',side_effect=AssertionError('Retained job decoder launched')): - self.assertEqual(len(decode_records(records_for())),1) - if adapter is image_training: - changes=[lambda job:job['evidence_context'].update(model_sha256='8'*64), - lambda job:job['evidence_context']['profile']['probe_selection'].update(count=1)] - else: - changes=[lambda job,key=key:job['evidence'].update({key:'8'*64}) for key in - ('model_sha256','material_sha256','adapter_sha256','profile_sha256','selection_policy_sha256','output_policy_sha256')] - def downgraded(job): - job['schema_version']=1;job.pop('adapter');job.pop('evidence') - changes.append(downgraded) - for change in changes: - with self.assertRaisesRegex(WorkbenchError,'exact scientific Run inputs'):decode_records(records_for(change)) - - -class NativeOutputAnchors(unittest.TestCase): - def test_stage_output_and_leaf_symlinks_and_directory_replacement_never_receive_provenance(self): - with tempfile.TemporaryDirectory(prefix='native-output-anchor-') as temporary: - root=Path(temporary);phase='1'*32;run_id='2'*32 - output=root/'project-native-phases'/phase/'output';output.mkdir(parents=True) - foreign=root/'foreign';foreign.mkdir();(foreign/'model.json').write_bytes(b'foreign') - recorded=[] - native=ProjectNativeExecution(SimpleNamespace(projection=None,session=SimpleNamespace(snapshot={'records':[]}), - db=SimpleNamespace(path=root,dataset_id='3'*32),runtime_access=None)) - native._retain=lambda document,name,raw,role:recorded.append((name,raw,role)) - document=dict(phase_id=phase,phase='train',run_id=run_id,spec=dict(output_dir=str(output),max_output_bytes=1024)) - run=dict(graph=dict(recipe='text_classification')) - output.rmdir();output.symlink_to(foreign,target_is_directory=True) - with self.assertRaisesRegex(WorkbenchError,'stage is unavailable'):native._retain_outputs(document,run=run) - output.unlink();output.mkdir();(output/'model.json').symlink_to(foreign/'model.json') - with self.assertRaisesRegex(WorkbenchError,'stage is unavailable'):native._retain_outputs(document,run=run) - (output/'model.json').unlink();(output/'model.json').write_bytes(b'original') - original_read=os.read;replaced=[] - def read(descriptor,maximum): - raw=original_read(descriptor,maximum) - if not replaced: - replaced.append(True);output.rename(output.parent/'original-output') - output.symlink_to(foreign,target_is_directory=True) - return raw - with patch('project_native_execution.os.read',side_effect=read),self.assertRaises(WorkbenchError): - native._retain_outputs(document,run=run) - self.assertEqual(recorded,[]) - output.unlink();(output.parent/'original-output').rename(output) - native._retain_outputs(document,run=run) - self.assertEqual(recorded,[('output/model.json',b'original','measured_output')]) - - -@unittest.skipUnless(os.environ.get('TULDOK_DATABASE_URL'),'Requires disposable PostgreSQL') -class NativeProbeBoundaryTests(unittest.TestCase): - """Actual child/native probe; authored release summary only, no model fit.""" - setUp=study_fixture.ProjectStudyControlTests.setUp - cleanup=study_fixture.ProjectStudyControlTests.cleanup - metadata=study_fixture.ProjectStudyControlTests.metadata - open_projection=study_fixture.ProjectStudyControlTests.open_projection - graph=preparation_fixture.NativePreparationTests.graph - release=preparation_fixture.NativePreparationTests.release - - def install_journal(self): - projection=self.projection - owner=ProjectCustody(self.host.db.path,self.host.db.dataset_id) - projection.custody=projection.execution.custody=owner.for_projection(self.store,projection.db.projection_id) - projection.session.publication_intent=projection.execution._publication_intent - return owner - - def deferred_failure(self,state): - projection=self.projection;db=projection.db;execution=projection.execution - db.execute('CREATE TEMP TABLE native_ack_parent(id INT PRIMARY KEY)') - db.execute('CREATE TEMP TABLE native_ack_child(id INT REFERENCES native_ack_parent(id) DEFERRABLE INITIALLY DEFERRED)') - original=execution.before_commit;fired=[] - def before(): - target=any(doc['events'][-1]['state']==state for doc in execution.native._dirty.values()) - original() - if target and not fired: - fired.append(True);db.execute('INSERT INTO native_ack_child VALUES(1)') - # Fault injection wraps the installed owner; production correctly - # refuses a second owner through set_project_hooks. - self.enterContext(patch.object(db,'_project_before_commit',new=before)) - return fired - - def test_never_entered_launch_can_settle_but_restarted_ambiguous_spawn_window_remains_unknown(self): - self.install_journal();projection=self.projection;native=projection.execution.native - with self.owner.bound(self.host),patch.dict(os.environ,{'TULDOK_TRAINING_PYTHON':'/usr/bin/python3'}): - graph=self.graph();original=native._dispatch_authorized;stopped=[] - def dispatch(identity): - original(identity) - entry=next((row for row in projection.custody.snapshot().get('native_phases',[]) if row['phase_id']==identity),None) - if entry is not None and entry['state']=='launch_intent': - stopped.append(identity);raise WorkbenchError('Controlled authority loss before entering launch.','unavailable',409) - with patch.object(projection.pipelines,'inspect_release',side_effect=self.release), \ - patch.object(native,'_dispatch_authorized',side_effect=dispatch), \ - patch('subprocess.Popen',side_effect=AssertionError('Never-entered launch constructed a child')): - with self.assertRaisesRegex(WorkbenchError,'Controlled authority loss'): - projection.execution.native_preflight(graph['id'],1,projection.session.snapshot['checkpoint'],'native-never-entered') - phase=stopped[0] - # An independently restarted owner has no private proof that the - # launch call was not entered after the durable intent. - original_native=ProjectNativeExecution(projection.execution) - with patch.object(projection,'reconcile_inert',side_effect=AssertionError('Unknown spawn reconstructed')): - with self.assertRaisesRegex(WorkbenchError,'helper drainage identity'): - original_native.reconcile(phase,projection.session.snapshot['checkpoint']) - # Its original process retains the exact before-call proof. - with patch('subprocess.Popen',side_effect=AssertionError('Never-launched recovery launched')): - result=native.reconcile(phase,projection.session.snapshot['checkpoint']) - self.assertEqual(result['state'],'failed');self.assertIsNone(result['receipt_sha256']) - self.assertFalse(projection.custody.has_pending);projection.execution.assert_quiescent() - - def test_generic_reconciliation_refuses_native_phase_before_recovery_or_reconstruction(self): - self.install_journal();projection=self.projection - with self.owner.bound(self.host): - with patch.object(projection.custody,'snapshot',return_value={'native_phases':[dict(phase_id='1'*32)]}), \ - patch.object(self.store,'recover_checkpoint',side_effect=AssertionError('Generic native recovery touched checkout')), \ - patch.object(projection,'reconcile_inert',side_effect=AssertionError('Generic native recovery reconstructed')): - for action in (projection.execution.reconcile_current, - lambda:projection.execution.reconcile_original(expected_checkpoint=projection.session.snapshot['checkpoint'])): - with self.assertRaisesRegex(WorkbenchError,'native_reconcile') as error:action() - self.assertEqual(error.exception.code,'unavailable') - - def test_never_launched_failed_phase_sql_ack_loss_reconciles_exact_terminal_fact_without_popen(self): - """A second failure must not strand a proven non-process intent.""" - self.install_journal();projection=self.projection;native=projection.execution.native - with self.owner.bound(self.host),patch.dict(os.environ,{'TULDOK_TRAINING_PYTHON':'/usr/bin/python3'}), \ - patch('subprocess.Popen',side_effect=AssertionError('Never-launched double-fault spawned a child')): - graph=self.graph();original=native._dispatch_authorized;stopped=[] - def refuse_before_launch(identity): - original(identity) - entry=next((row for row in projection.custody.snapshot().get('native_phases',[]) if row['phase_id']==identity),None) - if entry is not None and entry['state']=='launch_intent': - stopped.append(identity) - raise WorkbenchError('Controlled refusal before launch entry.','unavailable',409) - with patch.object(projection.pipelines,'inspect_release',side_effect=self.release), \ - patch.object(native,'_dispatch_authorized',side_effect=refuse_before_launch): - with self.assertRaisesRegex(WorkbenchError,'Controlled refusal'): - projection.execution.native_preflight(graph['id'],graph['revision'], - projection.session.snapshot['checkpoint'],'native-never-launched-double-fault') - self.assertEqual(len(stopped),1);phase=stopped[0] - self.assertIn(phase,native._never_launched) - fired=self.deferred_failure('failed') - with self.assertRaises(psycopg.errors.ForeignKeyViolation): - native.reconcile(phase,projection.session.snapshot['checkpoint']) - self.assertEqual(fired,[True]);self.assertFalse(projection.session.available) - terminal=self.store.snapshot() - document=next(row['document'] for row in terminal['records'] if row['family']==FAMILY) - self.assertEqual(document['events'][-1]['state'],'failed') - self.assertIsNone(document['events'][-1]['helper']) - self.assertIsNone(document['events'][-1]['receipt_sha256']) - self.assertTrue(all(value is None for value in document['observations'].values())) - pending=projection.custody.snapshot()['native_phases'] - self.assertEqual(len(pending),1);self.assertEqual(pending[0]['state'],'launch_intent') - self.assertIn(phase,native._never_launched) - projection.db._project_before_commit=projection.execution.before_commit - result=native.reconcile(phase,projection.session.snapshot['checkpoint']) - self.assertEqual(result['state'],'failed');self.assertIsNone(result['receipt_sha256']) - self.assertTrue(projection.session.available);self.assertFalse(projection.custody.has_pending) - self.assertNotIn(phase,native._never_launched) - self.assertEqual(self.store.snapshot(),terminal,'Recovery duplicated or changed the acknowledged terminal science') - self.assertEqual(projection.db.execute('SELECT count(*) FROM workspace_runs').fetchone()[0],0) - self.assertEqual(projection.db.execute('SELECT count(*) FROM access_admissions').fetchone()[0],0) - projection.execution.assert_quiescent() - - def test_second_foreground_probe_refuses_before_preparation_without_blocking_current_owner(self): - native=self.projection.execution.native - native._foreground_phase='f'*32 - try: - with patch('project_native_execution.prepare',side_effect=AssertionError('Second foreground prepared')): - with self.assertRaisesRegex(WorkbenchError,'Another explicit native preparation'): - native._run_phase('probe','text_classification','second-probe',None,{},None) - self.assertEqual(native._foreground_phase,'f'*32) - finally:native._foreground_phase=None - - def _admission_ack_failure(self): - from runs import Runs - from test_project_native_study import prepare_text_source - projection=self.projection;self.install_journal() - _,release=prepare_text_source(projection,key_prefix='native-no-dispatch') - body=dict(name='Never-dispatched current admission',recipe='text_validate_export',release_id=release['id']) - graph=projection.materials.mutate_definition('pipeline_graph','graphs.create',None,body, - projection.session.snapshot['checkpoint'],'no-dispatch-graph',lambda:projection.pipelines.create(body)) - validation=projection.execution.native_preflight(graph['id'],1,projection.session.snapshot['checkpoint'],'no-dispatch-validation') - self.assertTrue(validation['valid'],validation) - projection.db.execute('CREATE TEMP TABLE native_admit_parent(id INT PRIMARY KEY)') - projection.db.execute('CREATE TEMP TABLE native_admit_child(id INT REFERENCES native_admit_parent(id) DEFERRABLE INITIALLY DEFERRED)') - original=Runs._admit - def admit(owner,*args,**kwargs): - result=original(owner,*args,**kwargs) - owner.db.execute('INSERT INTO native_admit_child VALUES(1)') - return result - with patch.object(Runs,'_admit',new=admit),patch('subprocess.Popen',side_effect=AssertionError('Unacknowledged native admission dispatched')): - with self.assertRaises(ProjectSessionError) as failure: - projection.execution.native_submit(dict(graph_id=graph['id'],graph_revision=1, - validation_token=validation['validation_token']),projection.session.snapshot['checkpoint'],'no-dispatch-admit') - self.assertIsInstance(failure.exception.__cause__,psycopg.errors.ForeignKeyViolation) - self.assertEqual(failure.exception.code,'projection_unavailable') - journal=projection.custody.snapshot() - self.assertEqual(journal['format'],'project_local_custody_v3') - self.assertEqual(len(journal['native_admissions']),1);self.assertEqual(journal['native_phases'],[]) - self.assertFalse(journal['native_admissions'][0]['phase_started']) - self.assertEqual(projection.db.execute('SELECT count(*) FROM workspace_runs').fetchone()[0],0) - self.assertEqual(projection.db.execute('SELECT count(*) FROM access_admissions').fetchone()[0],0) - self.assertFalse(projection.session.available) - with self.assertRaises(WorkbenchError):projection.execution.assert_quiescent() - return journal - - def test_native_admission_sql_ack_failure_clears_only_current_non_effect_intent_without_authority(self): - with self.owner.bound(self.host): - self._admission_ack_failure();projection=self.projection - before=self.store.snapshot() - with patch('subprocess.Popen',side_effect=AssertionError('Current admission reconciliation dispatched')): - result=projection.execution.reconcile_current() - self.assertTrue(result['available']);self.assertFalse(projection.custody.has_pending) - self.assertEqual(self.store.snapshot(),before) - retained=next(row['document']['run'] for row in before['records'] if row['family']=='run_history') - self.assertEqual(retained['state'],'queued') - self.assertEqual(projection.db.execute('SELECT count(*) FROM access_admissions').fetchone()[0],0) - projection.execution.assert_quiescent();projection.close() - - def test_native_admission_sql_ack_failure_original_physical_reopen_stays_inert_until_exact_clear(self): - from metadata import Metadata - from project_projection import ProjectProjection - with self.owner.bound(self.host): - self._admission_ack_failure();previous=self.projection - path=previous.db.path;identity=previous.db.projection_id - previous.sources.close();previous.artifacts.close();previous.db.close() - self.projections.remove(previous) - db=Metadata(path,create=False,dataset_id=self.store.snapshot()['project_id'],projection_id=identity) - self.databases.append(db) - journal=ProjectCustody(self.host.db.path,self.host.db.dataset_id).for_projection(self.store,identity) - with patch('runs.Runs',side_effect=AssertionError('Original physical reopen constructed Runs')): - projection=ProjectProjection(self.store,db,self.host.access,{},custody=journal,restore=False) - self.projections.append(projection);self.assertFalse(projection.session.available) - self.assertIsNone(projection.execution._runs) - before=self.store.snapshot() - with patch('subprocess.Popen',side_effect=AssertionError('Original admission clear dispatched')): - result=projection.execution.reconcile_original(expected_checkpoint=projection.session.snapshot['checkpoint']) - self.assertTrue(result['available']);self.assertFalse(journal.has_pending) - self.assertEqual(self.store.snapshot(),before);self.assertIsNone(projection.execution._runs) - self.assertEqual(db.execute('SELECT count(*) FROM access_admissions').fetchone()[0],0) - projection.close() - - def test_actual_go_intent_sql_failure_sends_no_go_then_exact_receipt_reconciles_without_launch(self): - self.install_journal();projection=self.projection;go=[] - with self.owner.bound(self.host),patch.dict(os.environ,{'TULDOK_TRAINING_PYTHON':'/usr/bin/python3'}): - graph=self.graph();fired=self.deferred_failure('go_intent') - with patch.object(projection.pipelines,'inspect_release',side_effect=self.release), \ - patch.object(recipe_process.Handle,'go',side_effect=AssertionError('GO before SQL acknowledgement')): - with self.assertRaises(psycopg.errors.ForeignKeyViolation): - projection.execution.native_preflight(graph['id'],1,projection.session.snapshot['checkpoint'],'go-ack-failure') - self.assertEqual(fired,[True]);self.assertFalse(projection.session.available) - phase=projection.execution.health()['native_phases']['items'][0] - self.assertEqual(phase['state'],'ready') - projection.db._project_before_commit=projection.execution.before_commit - with patch('subprocess.Popen',side_effect=AssertionError('Reconciliation launched')), \ - patch.object(recipe_process.Handle,'go',side_effect=AssertionError('Reconciliation replayed GO')): - result=projection.execution.native_reconcile(phase['phase_id'],projection.session.snapshot['checkpoint']) - self.assertEqual(result['state'],'failed');self.assertTrue(projection.session.available) - self.assertFalse(projection.custody.has_pending);projection.execution.assert_quiescent() - document=next(r['document'] for r in self.store.snapshot()['records'] if r['family']==FAMILY) - receipt=recipe_process.decode(document['observations']['drain_receipt']) - self.assertFalse(receipt['go_received']);self.assertTrue(receipt['drained']) - - def test_non_utf8_probe_with_terminal_sql_failure_reconciles_process_without_valid_preflight_or_reexecution(self): - self.install_journal();projection=self.projection - with self.owner.bound(self.host),patch.dict(os.environ,{'TULDOK_TRAINING_PYTHON':'/usr/bin/python3'}): - graph=self.graph() - source=self.root/'protocol-fixture';source.mkdir() - for name in projection.pipelines.definition_identity(graph['recipe'])['definition_files']: - (source/name).write_bytes((projection.pipelines.source_path/name).read_bytes()) - (source/'text_training.py').write_bytes(b'import sys\nsys.stdout.buffer.write(b"\\xff")\nsys.stdout.flush()\n') - with patch.object(projection.pipelines,'source_path',source): - fired=self.deferred_failure('completed') - with patch.object(projection.pipelines,'inspect_release',side_effect=self.release): - with self.assertRaises(psycopg.errors.ForeignKeyViolation): - projection.execution.native_preflight(graph['id'],1,projection.session.snapshot['checkpoint'],'malformed-ack-failure') - self.assertEqual(fired,[True]);self.assertFalse(projection.session.available) - projection.db._project_before_commit=projection.execution.before_commit - phase=projection.execution.health()['native_phases']['items'][0] - with patch('subprocess.Popen',side_effect=AssertionError('Malformed recovery launched')), \ - patch.object(recipe_process.Handle,'go',side_effect=AssertionError('Malformed recovery replayed GO')): - result=projection.execution.native_reconcile(phase['phase_id'],projection.session.snapshot['checkpoint']) - self.assertEqual(result['state'],'completed') - self.assertFalse(projection.custody.has_pending);self.assertTrue(projection.session.available) - document=next(r['document'] for r in self.store.snapshot()['records'] if r['family']==FAMILY) - self.assertIsNone(document['observations']['probe_stdout']) - self.assertEqual(document['probe_result']['outcome'],'invalid_utf8') - self.assertEqual(recipe_process.decode(document['observations']['drain_receipt'])['leader_returncode'],0) - self.assertFalse(any(r['family']=='project_operation' and r['document']['operation']=='native_preparation.validate' - for r in self.store.snapshot()['records'])) - - def test_real_probe_go_requires_canonical_and_sql_ack_and_retains_exact_raw_observation(self): - control=self.install_journal();projection=self.projection;go=[] - original=recipe_process.Handle.go - def observed(handle,helper): - self.assertFalse(projection.db.in_transaction) - current=self.store.snapshot() - document=next(r['document'] for r in current['records'] if r['family']==FAMILY - and r['document']['phase_id']==handle.spec['attempt_id']) - self.assertEqual(document['events'][-1]['state'],'go_intent') - fresh=control.for_projection(self.store,projection.db.projection_id) - self.assertEqual(fresh.snapshot()['native_phases'][0]['state'],'go_intent') - go.append(handle.spec['attempt_id']);return original(handle,helper) - with self.owner.bound(self.host),patch.dict(os.environ,{'TULDOK_TRAINING_PYTHON':'/usr/bin/python3'}): - graph=self.graph() - with patch.object(projection.pipelines,'inspect_release',side_effect=self.release), \ - patch.object(recipe_process.Handle,'go',new=observed), \ - patch('runs.Runs',side_effect=AssertionError('Probe constructed Runs')): - value=projection.execution.native_preflight(graph['id'],1,projection.session.snapshot['checkpoint'],'actual-probe') - self.assertIs(type(value['valid']),bool);self.assertEqual(len(go),1) - records=self.store.snapshot()['records'];phases=decode_records(records,artifacts=projection.artifacts) - self.assertEqual(len(phases),1) - document=next(iter(phases.values())) - self.assertIn(document['events'][-1]['state'],('completed','failed')) - stdout=next(edge['blob'] for edge in document['payloads'] if edge['name']=='stdout.log') - raw=projection.artifacts.read_blob(stdout,maximum_bytes=32768) - self.assertEqual(recipe_process.decode(raw)['runtime'],value['runtime']['runtime']) - self.assertFalse(projection.custody.has_pending);self.assertFalse(projection.execution.native.has_local_custody) - self.assertEqual(projection.db.execute('SELECT count(*) FROM workspace_runs').fetchone()[0],0) - - -@unittest.skipUnless(os.environ.get('TULDOK_DATABASE_URL'),'Requires disposable PostgreSQL') -class NativePhaseRecoveryHTTP(unittest.TestCase): - setUp=http_fixture.ProjectFilesHTTP.setUp - cleanup_owned=http_fixture.ProjectFilesHTTP.cleanup_owned - select_host=http_fixture.ProjectFilesHTTP.select_host - request=http_fixture.ProjectFilesHTTP.request - state=http_fixture.ProjectFilesHTTP.state - envelope=http_fixture.ProjectFilesHTTP.envelope - action=http_fixture.ProjectFilesHTTP.action - create=http_fixture.ProjectFilesHTTP.create - graph=preparation_fixture.NativePreparationTests.graph - release=preparation_fixture.NativePreparationTests.release - deferred_failure=NativeProbeBoundaryTests.deferred_failure - - def native_http(self,action,arguments,version=1): - import agent_api - name='project_files.'+action - method,path,body=agent_api.project_request(name,arguments,version=version) - request=Request(self.origin+path,method=method, - data=None if body is None else json.dumps(body,ensure_ascii=False).encode(), - headers={'Authorization':'Bearer '+self.owner.token,'Origin':self.origin,'Content-Type':'application/json', - 'Tuldok-Operation-Contract':agent_api.selected_header(name,version)}) - try:response=urlopen(request,timeout=45) - except HTTPError as error:response=error - with response:return response.status,json.load(response) - - def stop_without_effects(self,workspace): - # This fixture has only the canceled, drained probe and no Run owner. - # Preserve its physical SQL/journal for the explicit restarted owner. - for candidate,server,thread in self.hosts: - if candidate is workspace: - server.shutdown();server.server_close();thread.join(3);break - for projection in (workspace._projection,workspace._retained_recovery): - if projection is not None: - self.assertIsNone(projection.execution._runs) - projection.sources.close();projection.artifacts.close();projection.db.close() - workspace._store.close() - for _path,descriptor in workspace._roots.values():os.close(descriptor) - workspace._roots.clear();workspace.db.close();workspace._closed=True - - def test_uncertain_spawn_without_handle_fences_public_preflight_and_never_infers_cessation(self): - import project_workspace - from project_native_process import PreparedNative - self.enterContext(patch.object(project_workspace,'M3_ENABLED',True)) - self.enterContext(patch.dict(os.environ,{'TULDOK_TRAINING_PYTHON':'/usr/bin/python3'})) - self.create();self.projection=self.workspace._projection - with self.owner.bound(self.workspace):graph=self.graph() - acknowledged=self.state();projection=self.projection;entered=[] - def uncertain_launch(prepared,custody_directory,*,_before_spawn=None): - self.assertIsNotNone(_before_spawn) - _before_spawn();entered.append(prepared.spec['attempt_id']) - # The foundation's own real seam tests establish this callback is - # the Popen entry boundary. Simulate only its uncertain exception; - # do not fabricate a child, Handle, drainage, or successful result. - raise OSError('Controlled uncertainty after entering spawn boundary') - arguments=dict(binding=acknowledged['binding'],expected_checkpoint=acknowledged['project']['checkpoint'], - graph_id=graph['id'],revision=graph['revision'],request_key='native-uncertain-spawn') - try: - with patch.object(projection.pipelines,'inspect_release',side_effect=self.release), \ - patch.object(PreparedNative,'launch',new=uncertain_launch), \ - patch('subprocess.Popen',side_effect=AssertionError('Unknown-spawn control created a real child')): - status,error=self.native_http('native_preflight',arguments) - self.assertEqual((status,error['code']),(409,'outcome_unknown')) - self.assertEqual(len(entered),1);self.assertFalse(projection.session.available) - self.assertNotIn(entered[0],projection.execution.native._never_launched) - entry=projection.custody.snapshot()['native_phases'][0] - self.assertEqual(entry['state'],'launch_intent');self.assertIsNone(entry['helper']) - self.assertIsNone(entry['receipt_sha256']) - recovery=self.state();self.assertEqual(recovery['state'],'recovery_required') - public=dict(binding=recovery['binding'],checkpoint=recovery['project']['checkpoint']) - status,health=self.native_http('execution_health',public,2) - self.assertEqual(status,200,health);self.assertFalse(health['value']['available']) - self.assertEqual(health['value']['native_phases']['items'][0]['phase_id'],entered[0]) - before=self.workspace._store.snapshot() - status,error=self.native_http('native_preflight',dict(arguments, - expected_checkpoint=public['checkpoint'],request_key='native-fresh-after-uncertainty')) - self.assertEqual((status,error['code']),(503,'projection_unavailable')) - status,error=self.native_http('native_reconcile',dict(binding=public['binding'], - expected_checkpoint=public['checkpoint'],phase_id=entered[0])) - self.assertEqual((status,error['code']),(409,'unknown')) - self.assertEqual(entered,[entry['phase_id']]) - self.assertFalse(projection.session.available);self.assertTrue(projection.custody.has_pending) - self.assertEqual(self.workspace._store.snapshot(),before) - finally: - # This test explicitly forbids real process creation. Preserve the - # unresolved private record while disposing only fixture handles. - self.stop_without_effects(self.workspace) - - def test_selected_health_versions_discover_original_phase_and_named_recovery_never_replays_go(self): - import agent_api - import project_workspace - self.enterContext(patch.object(project_workspace,'M3_ENABLED',True)) - self.enterContext(patch.dict(os.environ,{'TULDOK_TRAINING_PYTHON':'/usr/bin/python3'})) - self.create();self.projection=self.workspace._projection - with self.owner.bound(self.workspace):graph=self.graph() - acknowledged=self.state();projection=self.projection - fired=self.deferred_failure('go_intent') - arguments=dict(binding=acknowledged['binding'],expected_checkpoint=acknowledged['project']['checkpoint'], - graph_id=graph['id'],revision=graph['revision'],request_key='http-original-native-phase') - with patch.object(projection.pipelines,'inspect_release',side_effect=self.release), \ - patch.object(recipe_process.Handle,'go',side_effect=AssertionError('Unacknowledged HTTP phase sent GO')): - status,error=self.native_http('native_preflight',arguments) - self.assertEqual((status,error['code']),(503,'storage'));self.assertEqual(fired,[True]) - recovery=self.state();self.assertEqual(recovery['state'],'recovery_required') - self.assertEqual(recovery['binding'],acknowledged['binding']) - self.assertEqual(recovery['project']['checkpoint'],acknowledged['project']['checkpoint']) - pinned=dict(binding=recovery['binding'],checkpoint=recovery['project']['checkpoint'],offset=0,limit=1) - for version in (1,2): - status,reply=self.native_http('execution_health',pinned,version) - self.assertEqual(status,200,reply) - agent_api.validate_output('project_files.execution_health',dict(status=200,result=reply),version=version) - self.assertEqual(reply['checkpoint'],pinned['checkpoint']);self.assertFalse(reply['value']['available']) - self.assertEqual('native_phases' in reply['value'],version==2) - if version==2: - phase=reply['value']['native_phases']['items'][0] - self.assertEqual(reply['value']['native_phases']['total'],1) - self.assertIsNone(phase['run_id']);self.assertEqual(phase['state'],'ready') - for changed in (dict(pinned,binding='e'*32),dict(pinned,checkpoint='f'*64)): - self.assertEqual(self.native_http('execution_health',changed,2)[0],409) - with patch.object(projection,'reconcile_inert',side_effect=AssertionError('Generic native reconstruction')): - status,error=self.native_http('execution_reconcile_current', - dict(binding=recovery['binding'],expected_checkpoint=pinned['checkpoint'])) - self.assertEqual((status,error['code']),(409,'unavailable')) - physical=projection.db.projection_id;control=self.workspace.path - self.stop_without_effects(self.workspace) - with patch('runs.Runs',side_effect=AssertionError('Original HTTP Open constructed Runs')), \ - patch('subprocess.Popen',side_effect=AssertionError('Original HTTP recovery launched')), \ - patch.object(recipe_process.Handle,'go',side_effect=AssertionError('Original HTTP recovery replayed GO')): - self.select_host(control,{'fixture':self.external}) - self.action('open',root='fixture',directory='alpha') - state=self.state();self.assertEqual(state['state'],'recovery_required') - current=dict(binding=state['binding'],checkpoint=state['project']['checkpoint'],offset=0,limit=1) - status,reply=self.native_http('execution_health',current,2) - self.assertEqual(status,200,reply);self.assertEqual(reply['value']['native_phases']['items'],[phase]) - self.assertEqual(self.workspace._retained_recovery.db.projection_id,physical) - status,result=self.native_http('native_reconcile',dict(binding=state['binding'], - expected_checkpoint=current['checkpoint'],phase_id=phase['phase_id'])) - self.assertEqual(status,200,result);self.assertEqual(result['binding'],state['binding']) - self.assertEqual(result['value']['state'],'failed') - self.assertEqual(self.workspace._projection.db.projection_id,physical) - self.assertIsNone(self.workspace._projection.execution._runs) - self.assertFalse(self.workspace._projection.custody.has_pending) - self.action('close') - - -if __name__=='__main__':unittest.main() diff --git a/tests/test_project_native_extraction.py b/tests/test_project_native_extraction.py deleted file mode 100644 index 291e2247..00000000 --- a/tests/test_project_native_extraction.py +++ /dev/null @@ -1,164 +0,0 @@ -"""Original legacy native source custody, without probing or training. - -The source is an explicitly authored disposable PostgreSQL fixture. Its retained -runtime and staging files are controlled historical observations, not evidence -that a scientific worker ran or a model trained successfully. -""" -import hashlib -import io -import json -import os -from types import SimpleNamespace -import unittest -from unittest.mock import patch -import zipfile - -from pipeline import Pipelines, adapter_identity_for_graph, digest, execution_digest -from project_artifacts import ProjectArtifacts -from project_history import ProjectHistory, decode_records -from project_material import ProjectMaterial -from project_store import ProjectStore -import test_project_extraction as fixture -from test_project_history import legacy_run - - -@unittest.skipUnless(os.environ.get('TULDOK_DATABASE_URL'), 'Requires disposable PostgreSQL') -class NativeExtractionTests(unittest.TestCase): - setUp = fixture.LegacyCapture.setUp - view = fixture.LegacyCapture.view - files = fixture.LegacyCapture.files - capture = fixture.LegacyCapture.capture - text = fixture.LegacyCapture.text - - def author(self, *, integrity=False): - row = self.text('Exact historical native input; no execution claim' + ('; integrity' if integrity else '')) - manifest = dict(schema_version=1, seed=7, split_report={}, - coordinate_contract='Controlled retained-source fixture', - limitations=['No training or numerical validation claim'], vocabulary=[], - records=[dict(row, asset='source.txt', asset_sha256=row['content_hash'], split='train')]) - archive = io.BytesIO() - with zipfile.ZipFile(archive, 'w', zipfile.ZIP_STORED) as stream: - stream.writestr('manifest.json', json.dumps(manifest).encode()) - stream.writestr('source.txt', row['text'].encode()) - release = archive.getvalue(); sha = hashlib.sha256(release).hexdigest() - folder = self.db.path / 'releases'; folder.mkdir(exist_ok=True) - (folder / (sha + '.zip')).write_bytes(release) - graph = Pipelines(self.dataset).create(dict(name='Retained native source fixture', - recipe='text_validate_export' if integrity else 'text_classification', release_id=sha)) - run = legacy_run(self.db.dataset_id) - run.update(graph=graph, graph_revision=graph['revision'], graph_sha256=execution_digest(graph), - graph_document_sha256=digest(graph), adapter=adapter_identity_for_graph(graph), - release_id=sha, release_sha256=sha, release_bytes=len(release), source_records=[dict(row, split='train')], - execution_test_exposure=dict(exposed=False, events=[])) - originals = {'text_training.py': b'# Historical authored worker, never executed\r\nvalue = "original"\n', - 'retained_helper.py': b'# Original unique helper\nraw = b"\\x00\\xff"\n'} - stage = self.db.path / 'workspace-runs' / ('.staging-' + run['id']) - if not integrity: - stage.mkdir(parents=True) - for name, raw in originals.items(): (stage / name).write_bytes(raw) - files = {name: hashlib.sha256(raw).hexdigest() for name, raw in originals.items()} - run['runtime'] = dict(schema_version=1, available=True, adapter=run['adapter'], - runtime=dict(python='3.12.authored', device='cpu', threads=1, scikit_learn='1.7.2', - numpy='authored', scipy='authored', Pillow='authored'), problems=[], - definition_files=files, adapter_definition_sha256=digest(files)) - self.save(run) - return run, originals, stage - - def save(self, run): - with self.db.lock, self.db.transaction(): - self.db.execute('INSERT INTO workspace_runs VALUES(%s,%s,%s,%s) ON CONFLICT(id) DO UPDATE SET document=excluded.document', - (run['id'], run['request_key'], run['request_sha256'], json.dumps(run))) - - def capture_without_host(self, run, source): - resolve = source.resolve_payload - source_hashes = set(run['runtime'].get('definition_files', {}).values()) - def resolve_other(sha, size): - if sha in source_hashes: raise AssertionError('Original source resolver fallback') - return resolve(sha, size) - with patch.object(Pipelines, 'definition_identity', side_effect=AssertionError('Current source substitution')), \ - patch('subprocess.Popen', side_effect=AssertionError('Extraction launched a process')), \ - patch('subprocess.run', side_effect=AssertionError('Extraction probed a runtime')), \ - patch.object(source, 'resolve_payload', side_effect=resolve_other): - return self.capture(source, {'runs': [run['id']]}) - - def test_original_sources_are_unique_canonical_payloads_and_cold_read_byte_exactly(self): - run, originals, stage = self.author(); before = self.files(); source = self.view() - captured = self.capture_without_host(run, source) - self.assertEqual(captured['blockers'], [], captured['blockers']) - materials = ProjectMaterial(SimpleNamespace(snapshot=dict(project_id=self.db.dataset_id, - records=captured['records']), check_current=lambda: None)) - facts = decode_records(captured['records'], materials=materials) - saved = facts.runs[(self.db.dataset_id, run['id'])] - self.assertEqual(saved['run']['runtime'], run['runtime']) - self.assertEqual(saved['run']['execution_test_exposure'], run['execution_test_exposure']) - for name, raw in originals.items(): - edge = next(item for item in saved['payloads'] if item['name'] == 'source/' + name) - self.assertEqual(edge['blob'], dict(sha256=hashlib.sha256(raw).hexdigest(), bytes=len(raw))) - self.assertEqual((edge['role'], edge['preservation']), ('execution_source', 'unique')) - self.assertIn(dict(source=dict(family='run_history', id=self.db.dataset_id + '.' + run['id']), - target=dict(family='project_artifact', id=edge['blob']['sha256']), - reason='unique:source/' + name), captured['dependencies']) - self.assertEqual(source.artifacts.read_blob(edge['blob']), raw) - self.assertEqual(self.files(), before) - # Publish captured bytes to a disposable canonical store, close it, then - # read through a fresh inert history owner after original files vanish. - destination = self.root / 'cold-extracted' - store = ProjectStore.create(destination, 'Cold captured originals', 'native-extraction-new', '1' * 64) - artifacts = ProjectArtifacts(store) - try: - for record in captured['records']: - if record['family'] == 'project_artifact': - artifacts.publish_bytes(source.artifacts.read_blob(record['document']), record['document']) - store.commit(captured['records'], store.snapshot()['checkpoint'], 'native-extraction-capture', '2' * 64) - finally: - artifacts.close(); store.close() - for name in originals: (stage / name).unlink() - cold = ProjectStore.open(destination); self.addCleanup(cold.close) - cold_artifacts = ProjectArtifacts(cold); self.addCleanup(cold_artifacts.close) - snapshot = cold.snapshot() - session = SimpleNamespace(snapshot=snapshot, - summary={key:snapshot[key] for key in ('project_id','checkpoint')}, - access=self.access, artifacts=cold_artifacts, check_current=lambda: None) - history = ProjectHistory(session, authorize_disclosure=lambda *args: None) - for name, raw in originals.items(): - self.assertEqual(history.artifact(run['id'], 'source/' + name, origin_catalog_id=self.db.dataset_id), raw) - - def test_missing_original_is_blocked_without_resolver_or_host_fallback(self): - run, originals, stage = self.author(); (stage / 'text_training.py').unlink() - before = self.files(); captured = self.capture_without_host(run, self.view()) - self.assertEqual([row['code'] for row in captured['blockers']], ['missing_source']) - self.assert_failure_facts(captured, run, originals) - self.assertEqual(self.files(), before) - - def test_tampered_original_is_blocked_without_invented_byte_count_or_host_fallback(self): - run, originals, stage = self.author(); (stage / 'text_training.py').write_bytes(b'# Changed original source\n') - before = self.files(); captured = self.capture_without_host(run, self.view()) - self.assertEqual([row['code'] for row in captured['blockers']], ['corrupt_source']) - self.assert_failure_facts(captured, run, originals) - self.assertEqual(self.files(), before) - - def assert_failure_facts(self, captured, run, originals): - saved = next(row['document'] for row in captured['records'] if row['family'] == 'run_history') - self.assertEqual(saved['run']['runtime'], run['runtime']) - self.assertFalse(any(edge['name'] == 'source/text_training.py' for edge in saved['payloads'])) - # The retained hash has no known original size after loss/corruption. - # Never manufacture an intrinsic declaration from changed/current bytes. - lost = hashlib.sha256(originals['text_training.py']).hexdigest() - self.assertFalse(any(row['family'] == 'project_artifact' and row['id'] == lost for row in captured['records'])) - self.assertTrue(any(edge['name'] == 'source/retained_helper.py' and edge['preservation'] == 'unique' - for edge in saved['payloads'])) - - def test_missing_training_inventory_blocks_but_in_process_integrity_needs_no_staging(self): - run, _, _ = self.author(); run['runtime'] = {}; self.save(run) - captured = self.capture_without_host(run, self.view()) - self.assertEqual([row['code'] for row in captured['blockers']], ['source_identity_unavailable']) - # Author a distinct real in-process recipe observation; no training - # staging or executable source inventory exists for this owner path. - with self.db.lock, self.db.transaction(): self.db.execute('DELETE FROM workspace_runs') - integrity, _, stage = self.author(integrity=True) - captured = self.capture_without_host(integrity, self.view()) - self.assertEqual(captured['blockers'], [], captured['blockers']) - - -if __name__ == '__main__': - unittest.main() diff --git a/tests/test_project_native_preparation.py b/tests/test_project_native_preparation.py deleted file mode 100644 index 558f3326..00000000 --- a/tests/test_project_native_preparation.py +++ /dev/null @@ -1,293 +0,0 @@ -"""Current qualification policy and canonical ordering, without a native child. - -The controlled probe response and frozen-release summary are authored fixtures. -These tests qualify owner composition, not installed runtime or model quality. -The native process/core owners separately qualify the actual custody protocol. -""" -import copy -import os -from pathlib import Path -import sys -import unittest -from unittest.mock import patch -import uuid - -from access import AccessError -from pipeline import adapter_identity_for_graph -from project_native_preparation import ProjectNativePreparation,validate_operation_result -from project_session import operation_records -import test_project_study_execution as study_fixture -from workbench import WorkbenchError - - -@unittest.skipUnless(os.environ.get('TULDOK_DATABASE_URL'),'Requires disposable PostgreSQL') -class NativePreparationTests(unittest.TestCase): - setUp=study_fixture.ProjectStudyControlTests.setUp - cleanup=study_fixture.ProjectStudyControlTests.cleanup - metadata=study_fixture.ProjectStudyControlTests.metadata - open_projection=study_fixture.ProjectStudyControlTests.open_projection - - def test_validated_native_graph_save_as_keeps_original_observation_and_cold_inert_intent(self): - """Real Save As; the probe observation alone is explicitly controlled.""" - from auth_helpers import ExplicitOwnerFixture - from project_material_fork import is_intent - from project_session import operation_documents - from project_workspace import ProjectWorkspace - from test_project_native_study import prepare_text_source - root=self.root/'fork-projects';root.mkdir() - workspace=ProjectWorkspace(self.root/'fork-control',{'fixture':root}) - self.databases.append(workspace.db);self.addCleanup(workspace.close) - owner=ExplicitOwnerFixture.bootstrap(workspace) - def action(operation,**body): - state=workspace.status() - return workspace.dispatch('project_files.'+operation,dict(binding=state['binding'], - expected_checkpoint=state['project']['checkpoint'] if state['project'] else None, - request_key=uuid.uuid4().hex,**body)) - previous=self.projection - with owner.bound(workspace),patch('subprocess.Popen',side_effect=AssertionError('Save As regression must not fit or launch')): - action('new',root='fixture',directory='original',name='Original native qualification') - projection=workspace._projection;self.databases.append(projection.db);self.projection=projection - try: - _,release=prepare_text_source(projection,key_prefix='fork-validation-text') - body=dict(name='Actual model-aware native graph',recipe='text_classification_model_v2',release_id=release['id']) - graph=projection.materials.mutate_definition('pipeline_graph','graphs.create',None,body, - projection.session.snapshot['checkpoint'],'fork-native-graph',lambda:projection.pipelines.create(body)) - calls=[] - with patch.object(projection.execution.native,'probe',side_effect=self.controlled_probe(calls)): - validation=projection.native_preparation.validate_graph(projection.pipelines,graph['id'],graph['revision'], - projection.session.snapshot['checkpoint'],'fork-native-validation') - self.assertTrue(validation['valid'],validation);self.assertEqual(len(calls),1) - source=copy.deepcopy(projection.session.snapshot) - action('save_as',root='fixture',directory='independent',name='Independent native graph intent') - fork=workspace._projection;self.databases.append(fork.db) - self.assertNotEqual(fork.project_id,source['project_id']) - indexed={(record['family'],record['id']):record for record in fork.session.snapshot['records']} - for record in source['records']:self.assertEqual(indexed[(record['family'],record['id'])],record) - intents=[record for record in fork.session.snapshot['records'] - if record['family']=='pipeline_graph' and is_intent(record['document']['current'])] - self.assertEqual(len(intents),1) - self.assertNotEqual(intents[0]['document']['current']['id'],graph['id']) - self.assertTrue(validate_operation_result('native_preparation.validate',validation,fork.session.snapshot['records'])) - without_original=[record for record in fork.session.snapshot['records'] - if record['family']!='pipeline_graph' or is_intent(record['document']['current'])] - with self.assertRaisesRegex(WorkbenchError,'exact retained graph'): - validate_operation_result('native_preparation.validate',validation,without_original) - saved=copy.deepcopy(fork.session.snapshot) - action('close');action('open',root='fixture',directory='independent') - cold=workspace._projection;self.databases.append(cold.db) - self.assertEqual(cold.session.snapshot,saved) - observations=[receipt['result'] for receipt in operation_documents(saved['records']) - if receipt['operation']=='native_preparation.validate'] - self.assertEqual(observations,[validation]);self.assertIsNone(cold.execution._runs) - self.assertEqual(cold.db.execute('SELECT count(*) FROM workspace_runs').fetchone()[0],0) - finally:self.projection=previous - - def graph(self): - pipelines=self.projection.pipelines - body=dict(name='Authored qualification graph',recipe='text_classification',release_id='a'*64) - return self.projection.materials.mutate_definition('pipeline_graph','graphs.create',None,body, - self.projection.session.snapshot['checkpoint'],'native-graph',lambda:pipelines.create(body)) - - def release(self,release_id,*,private=False,recipe=None): - value=dict(id=release_id,sha256=release_id,format='text_classification_v1',recipe=recipe, - allowed_recipes=[recipe],records=6,class_vocabulary=[dict(label='a',index=0),dict(label='b',index=1)],split_counts=dict(train=2,validation=2,test=2), - prior_test_exposure=dict(exposed=False,events=[]),status='available') - if private:value.update(path='/authored/unopened-release.zip',manifest=dict(records=[])) - return value - - def controlled_probe(self,calls): - def probe(recipe,*,expected_checkpoint,request_key,preparation): - self.assertFalse(self.projection.db.in_transaction) - receipts=operation_records(self.projection.session.snapshot['records']) - self.assertTrue(any(v['operation']=='native_preparation.intent' for v in receipts.values())) - self.assertEqual(expected_checkpoint,self.projection.session.snapshot['checkpoint']) - preparation.authorize_probe(recipe) - inputs=preparation.native_inputs(recipe) - self.assertEqual(inputs['worker'],'text_training.py') - self.assertEqual(set(inputs['sources']),set(inputs['definition_identity']['definition_files'])) - calls.append(request_key) - return dict(runtime=dict(schema_version=1,available=True,adapter=adapter_identity_for_graph(dict(recipe=recipe)), - runtime=dict(python='3.12',device='cpu',threads=1,scikit_learn='1.7.2',numpy='authored',scipy='authored',Pillow='authored'), - problems=[],**inputs['definition_identity']),phase=dict(format='project_native_phase_v1', - origin_catalog_id=self.projection.session.project_id,phase_id='b'*32,phase='probe',run_id=None, - state='completed',spec_sha256='c'*64,receipt_sha256='d'*64)) - return probe - - def test_metadata_and_unscoped_probe_never_launch_and_transaction_cannot_start_preparation(self): - with self.owner.bound(self.host),patch('subprocess.Popen',side_effect=AssertionError('No process from metadata')), \ - patch('subprocess.run',side_effect=AssertionError('No legacy direct probe')): - graph=self.graph();adapter=self.projection.native_preparation - before=self.projection.session.snapshot - self.assertEqual(self.projection.pipelines.get(graph['id']),graph) - with self.assertRaisesRegex(WorkbenchError,'explicit current preparation'): - self.projection.pipelines.probe('text_classification') - with self.projection.db.transaction(),self.assertRaisesRegex(WorkbenchError,'precede the metadata transaction'): - adapter.validate_graph(self.projection.pipelines,graph['id'],1,before['checkpoint'],'native-inside-tx') - self.assertEqual(self.projection.session.snapshot,before) - self.assertEqual(self.projection.db.execute('SELECT count(*) FROM workspace_runs').fetchone()[0],0) - - def test_intent_precedes_probe_replay_does_not_launch_and_cache_is_lexical_and_one_use(self): - with self.owner.bound(self.host),patch.dict(os.environ,{'TULDOK_TRAINING_PYTHON':sys.executable}): - graph=self.graph();adapter=self.projection.native_preparation;calls=[] - with patch.object(self.projection.pipelines,'inspect_release',side_effect=self.release), \ - patch.object(self.projection.execution.native,'probe',side_effect=self.controlled_probe(calls)), \ - patch('subprocess.Popen',side_effect=AssertionError('Only controlled probe observation')), \ - patch('subprocess.run',side_effect=AssertionError('No legacy native subprocess')): - value=adapter.validate_graph(self.projection.pipelines,graph['id'],1, - self.projection.session.snapshot['checkpoint'],'native-validation') - self.assertTrue(value['valid']);self.assertEqual(len(calls),1) - stable=self.projection.session.snapshot - for forged in (dict(value,validation_token='e'*64),dict(value,runtime=dict(value['runtime'],token='secret')), - dict(value,release=dict(value['release'],credential={'token':'secret'}))): - with self.assertRaises(WorkbenchError): - validate_operation_result('native_preparation.validate',forged,stable['records']) - self.assertEqual(adapter.validate_graph(self.projection.pipelines,graph['id'],1,'0'*64,'native-validation'),value) - self.assertEqual(self.projection.session.snapshot,stable);self.assertEqual(len(calls),1) - with adapter.current_graph(self.projection.pipelines,graph['id'],1,stable['checkpoint'],'native-admission') as current: - self.assertEqual(current.validation['validation_token'],value['validation_token']) - self.assertEqual(len(calls),2) - with self.projection.db.transaction(): - # Repeated native validation inside admission reads the - # exact current process-local probe, and cannot fork. - self.assertEqual(self.projection.pipelines.validate_graph(graph),current.validation) - current.consume_admission() - with self.assertRaisesRegex(WorkbenchError,'already been consumed'):current.consume_admission() - self.assertEqual(len(calls),2) - source=self.root/'changed-source';source.mkdir() - for name,raw in current.sources.items():(source/name).write_bytes(raw) - entry=source/'text_training.py';entry.write_bytes(entry.read_bytes()+b'\n# authored source drift\n') - with patch.object(self.projection.pipelines,'source_path',source),self.assertRaisesRegex(WorkbenchError,'source changed'): - current.authorize_probe(graph['recipe']) - with self.assertRaisesRegex(WorkbenchError,'explicit current preparation'): - self.projection.pipelines.probe('text_classification') - imported=ProjectNativePreparation(self.projection) - with self.assertRaisesRegex(WorkbenchError,'explicit current preparation'): - imported.current(self.projection.pipelines) - fact=next(v['result'] for v in operation_records(self.projection.session.snapshot['records']).values() - if v['operation']=='native_preparation.intent') - self.assertTrue(validate_operation_result('native_preparation.intent',fact,self.projection.session.snapshot['records'])) - forged=copy.deepcopy(fact);forged['runtime']['token']='secret' - with self.assertRaises(WorkbenchError):validate_operation_result('native_preparation.intent',forged) - forged=copy.deepcopy(fact);forged['graph']['document_sha256']='f'*64 - with self.assertRaises(WorkbenchError): - validate_operation_result('native_preparation.intent',forged,self.projection.session.snapshot['records']) - - def test_pure_integrity_guard_has_no_interpreter_phase_and_is_still_current_one_use(self): - with self.owner.bound(self.host): - pipelines=self.projection.pipelines - body=dict(name='Authored pure validation',recipe='text_validate_export',release_id='a'*64) - graph=self.projection.materials.mutate_definition('pipeline_graph','graphs.create',None,body, - self.projection.session.snapshot['checkpoint'],'pure-graph',lambda:pipelines.create(body)) - # The authored result isolates the guard policy. The real whole - # release reader/in-process report has its own owner acceptance. - value=dict(valid=True,errors=[],release=dict(id='a'*64),validation_token='b'*64) - before=self.projection.session.snapshot - with patch.object(pipelines,'validate_graph',return_value=value), \ - patch.object(pipelines,'inspect_release',side_effect=self.release), \ - patch('project_native_process.current_runtime',side_effect=AssertionError('Pure integrity measured an interpreter')), \ - patch('subprocess.Popen',side_effect=AssertionError('Pure integrity forked')): - with self.projection.native_preparation.current_graph(pipelines,graph['id'],1,before['checkpoint'],'pure-guard') as current: - self.assertEqual(current.validation,value);self.assertFalse(hasattr(current,'native_inputs')) - current.consume_admission() - with self.assertRaisesRegex(WorkbenchError,'already been consumed'):current.consume_admission() - with self.assertRaisesRegex(WorkbenchError,'already been consumed'):current.consume_admission() - self.assertEqual(self.projection.session.snapshot,before) - - def test_agent_cannot_replay_owner_native_validation_or_construct_preparation(self): - with self.owner.bound(self.host): - graph=self.graph() - agent=self.host.access.issue(dict(label='Native metadata editor',scopes=['inspect','edit'])) - before=self.projection.session.snapshot - with self.host.access.bind(agent['token']),patch('subprocess.Popen',side_effect=AssertionError('Denied caller launched')): - with self.assertRaises(AccessError): - self.projection.native_preparation.validate_graph(self.projection.pipelines,graph['id'],1, - before['checkpoint'],'denied-native') - self.assertEqual(self.projection.session.snapshot,before) - - def test_actual_whole_mesh_release_validation_acknowledges_and_cold_reads_without_children(self): - import meshes - from test_meshes import fixture - with self.owner.bound(self.host), \ - patch('subprocess.Popen',side_effect=AssertionError('Whole-asset integrity must not fork')), \ - patch('subprocess.run',side_effect=AssertionError('Whole-asset integrity must not probe')), \ - patch('project_native_process.current_runtime',side_effect=AssertionError('No native interpreter for integrity')): - data=self.projection.data - prepared=meshes.prepare(*fixture('asymmetric-prism')) - row=data.import_bundle('mesh',prepared,dict(groups=['authored-geometry'],rights='Authored repository mesh'), - self.projection.session.snapshot['checkpoint'],'integrity-mesh-source') - row=data.annotate(row['id'],dict(revision=row['revision'],source_revision=row['source_revision'],task='mesh_geometry', - annotation=dict(note='Inspected authored whole geometry'),groups=row['groups'],review='human_reviewed'), - self.projection.session.snapshot['checkpoint'],'integrity-mesh-review') - request=dict(items=[{key:row[key] for key in ('id','revision','source_revision')}], - ratios=dict(train=100,validation=0,test=0),seed=4) - release=data.freeze_release(request,self.projection.session.snapshot['checkpoint'],'integrity-mesh-freeze') - body=dict(name='Actual whole mesh integrity',recipe='mesh_validate_export',release_id=release['id']) - graph=self.projection.materials.mutate_definition('pipeline_graph','graphs.create',None,body, - self.projection.session.snapshot['checkpoint'],'integrity-mesh-graph',lambda:self.projection.pipelines.create(body)) - value=self.projection.native_preparation.validate_graph(self.projection.pipelines,graph['id'],1, - self.projection.session.snapshot['checkpoint'],'integrity-mesh-validation') - self.assertTrue(value['valid'],value['errors']) - observed=value['release'] - self.assertEqual(observed['result_kind'],'release_validation') - self.assertNotIn('class_vocabulary',observed) - self.assertEqual(observed['validation_summary']['mesh_count'],1) - self.assertEqual(observed['validation_summary']['vertex_count'],6) - self.assertEqual(observed['validation_summary']['triangle_count'],8) - for change in ('foreign_bytes','nested_authority','header_vocabulary'): - forged=copy.deepcopy(value) - if change=='foreign_bytes':forged['release']['validation_summary']['release_sha256']='f'*64 - elif change=='nested_authority':forged['release']['validation_summary']['meshes'][0]['provenance']['credential']={'token':'secret'} - else:forged['release']['class_vocabulary']=[] - with self.subTest(change=change),self.assertRaises(WorkbenchError): - validate_operation_result('native_preparation.validate',forged,self.projection.session.snapshot['records']) - import release_validation - manifest=next(record['document']['manifest'] for record in self.projection.session.snapshot['records'] - if record['family']=='dataset_release' and record['id']==release['id']) - historical=copy.deepcopy(observed['validation_summary']) - historical['limitations']=['Original retained explanation remains exact.'] - self.assertEqual(release_validation.decode_summary(historical,'mesh_validate_export',manifest=manifest, - release_id=release['id']),historical) - self.assertEqual(operation_records(self.projection.session.snapshot['records'])['integrity-mesh-validation']['result'],value) - before=self.projection.session.snapshot - self.assertFalse(any(r['family']=='native_execution_history' for r in before['records'])) - self.projection.close();self.open_projection() - self.assertEqual(self.projection.session.snapshot,before) - self.assertEqual(operation_records(before['records'])['integrity-mesh-validation']['result'],value) - self.assertEqual(self.projection.native_preparation.validate_graph(self.projection.pipelines,graph['id'],1, - '0'*64,'integrity-mesh-validation'),value) - self.assertIsNone(self.projection.execution._runs) - self.assertEqual(self.projection.db.execute('SELECT count(*) FROM workspace_runs').fetchone()[0],0) - - def test_actual_classification_export_integrity_dto_keeps_vocabulary_and_summary(self): - with self.owner.bound(self.host),patch('subprocess.Popen',side_effect=AssertionError('Export integrity must not fork')): - data=self.projection.data;rows=[] - for index in range(6): - row=data.import_text(dict(text='Authored independent classification source '+str(index), - groups=['export-source-'+str(index)],rights='Authored test text'), - self.projection.session.snapshot['checkpoint'],'export-source-'+str(index)) - row=data.annotate(row['id'],dict(revision=row['revision'],source_revision=row['source_revision'], - task='text_classification',annotation=dict(label='a' if index%2 else 'b'),groups=row['groups'],review='human_reviewed'), - self.projection.session.snapshot['checkpoint'],'export-review-'+str(index)) - rows.append(row) - request=dict(format='text_classification_v1',items=[{key:row[key] for key in ('id','revision','source_revision')} - for row in rows],ratios=dict(train=34,validation=33,test=33),seed=42) - for seed in range(100): - request['seed']=seed - preview=data.preview_release(request) - if preview['eligible']:break - self.assertTrue(preview['eligible'],preview['blockers']) - request['preview_token']=preview['preview_token'] - release=data.freeze_release(request,self.projection.session.snapshot['checkpoint'],'export-freeze') - body=dict(name='Actual frozen text export integrity',recipe='text_validate_export',release_id=release['id']) - graph=self.projection.materials.mutate_definition('pipeline_graph','graphs.create',None,body, - self.projection.session.snapshot['checkpoint'],'export-graph',lambda:self.projection.pipelines.create(body)) - value=self.projection.native_preparation.validate_graph(self.projection.pipelines,graph['id'],1, - self.projection.session.snapshot['checkpoint'],'export-validation') - self.assertTrue(value['valid'],value['errors']) - self.assertEqual(value['release']['result_kind'],'release_validation') - vocabulary=[dict(label='a',index=0),dict(label='b',index=1)] - self.assertEqual(value['release']['class_vocabulary'],vocabulary) - self.assertEqual(value['release']['validation_summary']['record_count'],6) - self.assertEqual(value['release']['validation_summary']['class_vocabulary'],vocabulary) - self.assertTrue(validate_operation_result('native_preparation.validate',value,self.projection.session.snapshot['records'])) - self.assertFalse(any(r['family']=='native_execution_history' for r in self.projection.session.snapshot['records'])) diff --git a/tests/test_project_native_process.py b/tests/test_project_native_process.py deleted file mode 100644 index 5df959c4..00000000 --- a/tests/test_project_native_process.py +++ /dev/null @@ -1,512 +0,0 @@ -"""Actual finite native custody with synthetic stdlib workers, never ML work.""" -import ctypes -import hashlib -import json -import os -from pathlib import Path -import select -import shutil -import signal -import sys -import tempfile -import textwrap -import time -import unittest -from unittest.mock import patch -import uuid -import venv - -import project_native_process as native -import recipe_process as custody - - -WORKER = textwrap.dedent('''\ - import argparse,ctypes,hashlib,json,os,signal,sys,time - from pathlib import Path - parser=argparse.ArgumentParser() - parser.add_argument('--probe',action='store_true') - parser.add_argument('--model-aware',action='store_true') - parser.add_argument('--job') - parser.add_argument('--verify-evidence') - args=parser.parse_args() - if args.probe: - print(json.dumps({'available':True,'model_aware':args.model_aware, - 'secret_present': 'NATIVE_FIXTURE_SECRET' in os.environ}),flush=True) - else: - path=Path(args.verify_evidence or args.job) - job=json.loads(path.read_bytes()) - assert job['parent_pid']==os.getppid() and job['parent_pid']>1 - assert ctypes.CDLL(None).prctl(1,signal.SIGKILL,0,0,0)==0 - assert job['parent_pid']==os.getppid() - root=Path(job['output_dir']) - if job.get('mode')=='escape': - child=os.fork() - if child==0: - os.setsid();child=os.fork() - if child:os._exit(0) - os.setsid();signal.signal(signal.SIGTERM,signal.SIG_IGN) - (root/'escaped.pid').write_text(str(os.getpid())) - time.sleep(30);os._exit(0) - os.waitpid(child,0);time.sleep(30) - else: - phase='verify' if args.verify_evidence else 'train' - (root/(phase+'.json')).write_text(json.dumps({'parent_pid':os.getppid(), - 'job_sha256':hashlib.sha256(path.read_bytes()).hexdigest(),'text':job['text']})) - print(json.dumps({'phase':phase}),flush=True) - ''').encode() - - -class NativeProcessTests(unittest.TestCase): - def setUp(self): - self.temporary=tempfile.TemporaryDirectory(prefix='tuldok-native-process-') - self.addCleanup(self.temporary.cleanup) - self.root=Path(self.temporary.name);self.handles=[] - self.addCleanup(self.drain) - executable=str(Path('/usr/bin/python3').resolve()) - raw=Path(executable).read_bytes() - self.runtime=dict(executable=executable,executable_sha256=hashlib.sha256(raw).hexdigest(), - trusted_install_owner_uid=os.stat('/usr').st_uid, - files={executable:dict(sha256=hashlib.sha256(raw).hexdigest(),bytes=len(raw))}) - - def drain(self): - for handle in reversed(self.handles): - handle.close_control() - - def prepare(self,phase='train',*,mode='complete',output=None,sources=None): - stage=self.root/(phase+'-'+uuid.uuid4().hex) - job=None if phase=='probe' else dict(parent_pid=1,output_dir=str(output or stage/'output'), - mode=mode,text='exact Unicode 山') - return native.prepare(stage,phase=phase,attempt_id=uuid.uuid4().hex,request_sha256='a'*64, - runtime=self.runtime,worker='text_training.py',sources=sources or {'text_training.py':WORKER}, - job=job,model_aware=True,wall_seconds=8,max_output_bytes=16384) - - def until(self,handle,predicate,*,event_type=None,timeout=10): - deadline=time.monotonic()+timeout;events=[] - while time.monotonic()1 - Path(job['output_dir'],'venv.json').write_text(json.dumps(result)) - print(json.dumps(result),flush=True) - ''').encode() - for phase in ('probe','train'): - stage=self.root/('venv-'+phase) - prepared=native.prepare(stage,phase=phase,attempt_id=uuid.uuid4().hex,request_sha256='b'*64, - runtime=runtime,worker='text_training.py',sources={'text_training.py':source}, - job=None if phase=='probe' else dict(parent_pid=1,output_dir=str(stage/'output')), - wall_seconds=8,max_output_bytes=16384) - self.assertEqual(prepared.spec['argv'][0],executable) - handle=self.launch(prepared);prepared.check_current_runtime();handle.go(handle.ready) - proof=self.finish(prepared,handle);result=json.loads(proof['stdout']) - self.assertEqual(proof['receipt']['outcome'],'completed',proof) - self.assertEqual(result['prefix'],str(root));self.assertEqual(result['executable'],executable) - self.assertEqual(result['value'],'explicit configured venv package') - self.assertTrue(Path(result['module']).is_relative_to(root)) - if phase=='train': - self.assertEqual(json.loads((stage/'output/venv.json').read_bytes()),result) - - def test_verified_executable_fd_rejects_wrong_bytes_without_closing_or_repositioning_callers_fd(self): - prepared=self.prepare();wrong=self.root/'wrong-executable';wrong.write_bytes(b'not the qualified interpreter') - descriptor=os.open(wrong,os.O_RDONLY) - try: - os.lseek(descriptor,7,os.SEEK_SET) - with self.assertRaises(custody.ProcessError) as error: - custody.launch(prepared.spec,prepared.stage/'custody',executable_fd=descriptor) - self.assertEqual(error.exception.code,'stale') - self.assertEqual(os.lseek(descriptor,0,os.SEEK_CUR),7) - self.assertTrue(os.fstat(descriptor)) - self.assertFalse((prepared.stage/'custody').exists()) - finally:os.close(descriptor) - - def test_current_venv_config_drift_before_go_prevents_dispatch_and_still_drains(self): - root,executable=self.configured_venv();runtime=native.current_runtime(executable) - stage=self.root/'venv-drift' - prepared=native.prepare(stage,phase='probe',attempt_id=uuid.uuid4().hex,request_sha256='c'*64, - runtime=runtime,worker='text_training.py',sources={'text_training.py':WORKER},wall_seconds=8) - handle=self.launch(prepared) - with (root/'pyvenv.cfg').open('a') as output:output.write('\n# changed after READY\n') - with self.assertRaises(custody.ProcessError) as error: - try: - prepared.check_current_runtime() - handle.go(handle.ready) - finally:handle.close_control() - self.assertEqual(error.exception.code,'stale') - proof=prepared.evidence(handle) - self.assertFalse(proof['receipt']['go_received']);self.assertTrue(proof['receipt']['drained']) - - def test_current_interpreter_alias_drift_before_launch_cannot_select_another_interpreter(self): - root,executable=self.configured_venv();runtime=native.current_runtime(executable) - stage=self.root/'venv-alias-drift' - prepared=native.prepare(stage,phase='probe',attempt_id=uuid.uuid4().hex,request_sha256='d'*64, - runtime=runtime,worker='text_training.py',sources={'text_training.py':WORKER},wall_seconds=8) - replacement=self.root/'replacement-python' - shutil.copy2(runtime['executable_source'],replacement) - self.assertNotEqual(replacement.resolve(),Path(executable).resolve()) - Path(executable).unlink();Path(executable).symlink_to(replacement) - with self.assertRaises(custody.ProcessError) as error:self.launch(prepared) - self.assertEqual(error.exception.code,'stale');self.assertFalse((stage/'custody').exists()) - - def test_spawn_callback_is_not_reached_for_current_config_alias_or_capture_refusal(self): - root,executable=self.configured_venv();runtime=native.current_runtime(executable) - stage=self.root/'spawn-validation' - prepared=native.prepare(stage,phase='probe',attempt_id=uuid.uuid4().hex,request_sha256='f'*64, - runtime=runtime,worker='text_training.py',sources={'text_training.py':WORKER},wall_seconds=8) - configuration=root/'pyvenv.cfg';original=configuration.read_bytes() - marker={'never_launched'};calls=[] - def before_spawn(): - calls.append('spawn');marker.discard('never_launched') - with patch.object(custody.subprocess,'Popen',side_effect=AssertionError('Validation must precede Popen')) as spawn: - configuration.write_bytes(original+b'\n# changed before launch\n') - with self.assertRaises(custody.ProcessError): - prepared.launch(stage/'custody',_before_spawn=before_spawn) - configuration.write_bytes(original) - Path(executable).unlink();Path(executable).symlink_to('/unavailable-native-interpreter') - with self.assertRaises((OSError,custody.ProcessError)): - prepared.launch(stage/'custody',_before_spawn=before_spawn) - captured=self.prepare('probe');source=captured.stage/'source/text_training.py' - source.chmod(0o600);source.write_bytes(WORKER+b'\n# changed capture\n');source.chmod(0o400) - with self.assertRaises(custody.ProcessError): - captured.launch(captured.stage/'custody',_before_spawn=before_spawn) - spawn.assert_not_called() - self.assertEqual(calls,[]);self.assertEqual(marker,{'never_launched'}) - - def test_real_spawn_callback_runs_once_immediately_before_popen_without_sending_go(self): - prepared=self.prepare('probe');events=[];marker={'never_launched'} - actual_popen=custody.subprocess.Popen - def before_spawn(): - events.append('callback');marker.discard('never_launched') - def spawn(*args,**kwargs): - self.assertEqual(events,['callback']);self.assertEqual(marker,set()) - events.append('popen') - return actual_popen(*args,**kwargs) - with patch.object(custody.subprocess,'Popen',side_effect=spawn): - handle=prepared.launch(prepared.stage/'custody',_before_spawn=before_spawn) - self.handles.append(handle);self.until(handle,lambda:handle.ready is not None) - self.assertEqual(events,['callback','popen']);self.assertFalse(handle.sent_go) - receipt=handle.close_control() - self.assertTrue(receipt['drained']);self.assertFalse(receipt['go_received']) - - def test_popen_entry_failure_cannot_reinstate_never_launched_proof(self): - prepared=self.prepare('probe');marker={'never_launched'};events=[] - def before_spawn(): - events.append('callback');marker.discard('never_launched') - def fail_spawn(*args,**kwargs): - self.assertEqual(events,['callback']);self.assertEqual(marker,set()) - events.append('popen');raise OSError('Synthetic failure after entering Popen') - with patch.object(custody.subprocess,'Popen',side_effect=fail_spawn): - with self.assertRaisesRegex(OSError,'after entering Popen'): - prepared.launch(prepared.stage/'custody',_before_spawn=before_spawn) - self.assertEqual(events,['callback','popen']);self.assertEqual(marker,set()) - - def test_post_spawn_handle_failure_cannot_reinstate_never_launched_proof(self): - prepared=self.prepare('probe');marker={'never_launched'};processes=[] - actual_popen=custody.subprocess.Popen - def before_spawn():marker.discard('never_launched') - def spawn(*args,**kwargs): - process=actual_popen(*args,**kwargs);processes.append(process);return process - with (patch.object(custody.subprocess,'Popen',side_effect=spawn), - patch.object(custody,'Handle',side_effect=OSError('Synthetic post-spawn Handle failure'))): - with self.assertRaisesRegex(OSError,'post-spawn Handle failure'): - prepared.launch(prepared.stage/'custody',_before_spawn=before_spawn) - self.assertEqual(marker,set());self.assertEqual(len(processes),1) - # Owner control closes on failure. Even if the helper exits, no Handle / - # READY identity exists to assert an acknowledged drain for this owner. - processes[0].wait(timeout=custody.CLEANUP_SECONDS+2) - - def test_retained_spec_grammar_does_not_mistake_original_uid_for_current_permission(self): - prepared=self.prepare();spec=prepared.spec;raw=custody.encoded(spec) - with patch.object(custody.os,'getuid',return_value=spec['trusted_install_owner_uid']): - with self.assertRaises(custody.ProcessError):custody.validate_spec(spec) - retained=custody.decode_retained_spec(spec) - checked=native.validate_prepared_spec(spec,phase='train',worker='text_training.py') - self.assertEqual(custody.encoded(retained),raw);self.assertEqual(custody.encoded(checked),raw) - for change in (dict(argv=[spec['argv'][0],'-c','print("unclassified")']),dict(env={'PYTHONPATH':'/outside'}), - dict(wall_seconds=601),dict(schema_version=True)): - with self.subTest(change=tuple(change)),self.assertRaises(custody.ProcessError): - native.validate_prepared_spec(dict(spec,**change),phase='train',worker='text_training.py') - - def test_pure_current_runtime_decoder_rejects_unclassified_observed_files(self): - runtime=native.current_runtime(str(Path('/usr/bin/python3'))) - self.assertEqual(native.validate_current_runtime(runtime),runtime) - outside=dict(runtime,files={**runtime['files'],'/arbitrary/file':{'sha256':'e'*64,'bytes':1}}) - with self.assertRaises(custody.ProcessError):native.validate_current_runtime(outside) - - def test_original_phase_reader_reuses_exact_live_evidence_without_runtime_or_process_authority(self): - prepared=self.prepare();handle=self.launch(prepared);handle.go(handle.ready) - live=self.finish(prepared,handle);handle.close_control() - with (patch.object(custody,'launch',side_effect=AssertionError('No launch from original evidence')), - patch.object(custody,'identity',side_effect=AssertionError('No current process lookup')), - patch.object(native,'current_runtime',side_effect=AssertionError('No runtime lookup'))): - original=native.read_phase_evidence(prepared.stage,prepared.spec,phase='train',helper=handle.ready) - self.assertEqual(original,live) - self.assertEqual(set(original),{'receipt','stdout','stderr','template','effective_job','parent_observation'}) - self.assertEqual(original['template'],prepared.template) - - def test_original_phase_reader_refuses_wrong_physical_stage_spec_helper_and_template(self): - prepared=self.prepare();handle=self.launch(prepared);handle.go(handle.ready) - self.finish(prepared,handle) - wrong_helper={**handle.ready,'pid':handle.ready['pid']+1000000} - for stage,spec,helper in ((self.root/'other-physical-stage',prepared.spec,handle.ready), - (prepared.stage,dict(prepared.spec,wall_seconds=7),handle.ready), - (prepared.stage,prepared.spec,wrong_helper)): - with self.subTest(stage=str(stage),helper=helper['pid']),self.assertRaises(custody.ProcessError): - native.read_phase_evidence(stage,spec,phase='train',helper=helper) - template=prepared.stage/'native-job-template.json' - template.chmod(0o600);template.write_bytes(prepared.template+b' ');template.chmod(0o400) - with self.assertRaises(custody.ProcessError): - native.read_phase_evidence(prepared.stage,prepared.spec,phase='train',helper=handle.ready) - - def test_original_phase_reader_preserves_real_failed_receipt_before_effective_job_exists(self): - stopped=self.root/'native_process_bootstrap.py' - stopped.write_bytes(b'raise SystemExit(17)\n') - with patch.object(native,'BOOTSTRAP',stopped):prepared=self.prepare() - handle=self.launch(prepared);handle.go(handle.ready) - self.until(handle,lambda:handle.terminal);handle.process.wait(timeout=2) - original=native.read_phase_evidence(prepared.stage,prepared.spec,phase='train',helper=handle.ready) - self.assertTrue(original['receipt']['go_received']);self.assertTrue(original['receipt']['drained']) - self.assertEqual(original['receipt']['outcome'],'failed') - self.assertEqual(original['receipt']['leader_returncode'],17) - self.assertEqual(original['template'],prepared.template) - self.assertIsNone(original['effective_job']);self.assertIsNone(original['parent_observation']) - - def test_original_phase_reader_rejects_aliased_or_changed_evidence_bytes(self): - prepared=self.prepare();handle=self.launch(prepared);handle.go(handle.ready) - self.finish(prepared,handle) - observation=prepared.stage/'native-parent-observation.json' - alias=self.root/'evidence-hardlink';os.link(observation,alias) - with self.assertRaises(custody.ProcessError): - native.read_phase_evidence(prepared.stage,prepared.spec,phase='train',helper=handle.ready) - alias.unlink() - log=handle.directory/'stdout.log';log.write_bytes(log.read_bytes()+b'unacknowledged change') - with self.assertRaises(custody.ProcessError): - native.read_phase_evidence(prepared.stage,prepared.spec,phase='train',helper=handle.ready) - - def test_original_phase_reader_cannot_normalize_changed_raw_receipt_bytes(self): - prepared=self.prepare();handle=self.launch(prepared);handle.go(handle.ready) - self.finish(prepared,handle) - receipt=handle.directory/'receipt.json';receipt.write_bytes(receipt.read_bytes()+b'\n') - with self.assertRaises(custody.ProcessError) as error: - native.read_phase_evidence(prepared.stage,prepared.spec,phase='train',helper=handle.ready) - self.assertEqual(error.exception.code,'unknown') - - def pure_job_proof(self): - prepared=self.prepare();helper=custody.identity(os.getpid()) - template=prepared.template;frame=custody.decode(template) - effective=custody.encoded(dict(frame['job'],parent_pid=helper['pid'])) - observation=custody.encoded(dict(format='native_parent_observation_v1', - attempt_id=prepared.spec['attempt_id'],request_sha256=prepared.spec['request_sha256'], - template_sha256=hashlib.sha256(template).hexdigest(), - effective_job_sha256=hashlib.sha256(effective).hexdigest(),helper=helper)) - receipt=dict(schema_version=1,attempt_id=prepared.spec['attempt_id'], - request_sha256=prepared.spec['request_sha256'], - spec_sha256=hashlib.sha256(custody.encoded(prepared.spec)).hexdigest(),helper=helper, - go_received=True,spawn_closed=True,drained=True,echild=True,outcome='completed',reason='exited', - leader_returncode=0,streams={name:dict(bytes=0,sha256=hashlib.sha256(b'').hexdigest()) for name in ('stdout','stderr')}) - return prepared,dict(phase='train',helper=helper,template=template,effective_job=effective, - parent_observation=observation,receipt=receipt) - - def test_inline_job_proof_is_pure_and_rejects_tampered_binding_or_effective_job(self): - prepared,proof=self.pure_job_proof() - with (patch.object(native.os,'open',side_effect=AssertionError('Inline proof never opens a path')), - patch.object(custody,'identity',side_effect=AssertionError('Inline proof never resolves a PID')), - patch.object(custody,'launch',side_effect=AssertionError('Inline proof never launches')), - patch.object(native,'current_runtime',side_effect=AssertionError('Inline proof never resolves runtime'))): - accepted=native.validate_job_evidence(prepared.spec,**proof) - self.assertEqual(accepted,{key:proof[key] for key in ('receipt','template','effective_job','parent_observation')}) - wrong_job=custody.decode(proof['effective_job']);wrong_job['parent_pid']+=1 - wrong_observation=custody.decode(proof['parent_observation']);wrong_observation['helper']['start_ticks']='0' - frame=custody.decode(proof['template']);frame['job']['text']='silently rewritten source' - for change in (dict(effective_job=custody.encoded(wrong_job)), - dict(parent_observation=custody.encoded(wrong_observation)), - dict(template=custody.encoded(frame)), - dict(receipt=dict(proof['receipt'],spec_sha256='0'*64)), - dict(effective_job=None,parent_observation=None), - dict(parent_observation=None), - dict(effective_job=b'x'*(native.TEMPLATE_LIMIT+1))): - with self.subTest(change=tuple(change)),self.assertRaises(custody.ProcessError): - native.validate_job_evidence(prepared.spec,**{**proof,**change}) - - def test_inline_failed_phase_preserves_absent_effective_job_without_fabrication(self): - prepared,proof=self.pure_job_proof() - proof.update(effective_job=None,parent_observation=None, - receipt=dict(proof['receipt'],outcome='failed',leader_returncode=17,reason='nonzero_exit')) - with patch.object(native.os,'open',side_effect=AssertionError('No historical path reads')): - accepted=native.validate_job_evidence(prepared.spec,**proof) - self.assertIsNone(accepted['effective_job']);self.assertIsNone(accepted['parent_observation']) - self.assertEqual(accepted['template'],prepared.template) - - -if __name__=='__main__':unittest.main() diff --git a/tests/test_project_native_run.py b/tests/test_project_native_run.py deleted file mode 100644 index b88b07af..00000000 --- a/tests/test_project_native_run.py +++ /dev/null @@ -1,292 +0,0 @@ -"""One actual native CPU Run reused for independent Save As and cold Git reads. - -Requires an explicitly qualified immutable source and CPU environment. No model -quality, package closure, or portability of installed dependencies is asserted. -""" -import copy -import hashlib -import json -import os -from pathlib import Path -import subprocess -import tempfile -import time -import unittest -from unittest.mock import patch -import uuid - -import psycopg -from psycopg import sql - -from auth_helpers import ExplicitOwnerFixture -from metadata import connection_info -from project_session import operation_records -from project_artifacts import ProjectArtifactError -from project_store import ProjectStoreError, GITIGNORE, _encode as canonical -from project_workspace import ProjectWorkspace -from workbench import WorkbenchError -import recipe_process -import text_training -from test_project_native_study import (prepare_text_source, retain_project_evidence, - qa_retained_path, native_drain_wait_seconds, NATIVE_PYTHON) - - -@unittest.skipUnless(os.environ.get('TULDOK_NATIVE_PROJECT_GO')=='1' - and os.environ.get('TULDOK_DATABASE_URL') - and os.environ.get('TULDOK_PROJECT_FILES_COLD_DATABASE_URL') and NATIVE_PYTHON is not None and NATIVE_PYTHON.is_file(), - 'Requires explicit native gate, qualified CPU runtime, and separate PostgreSQL cold role') -class NativeRunSaveAsTests(unittest.TestCase): - def setUp(self): - self.temporary=tempfile.TemporaryDirectory(prefix='tuldok-native-run-save-as-') - self.addCleanup(self.temporary.cleanup) - self.root=Path(self.temporary.name);self.external=self.root/'external';self.external.mkdir() - self.hosts=[];self.controls=[] - self.addCleanup(self.cleanup) - self.enterContext(patch.dict(os.environ,{'TULDOK_TRAINING_PYTHON':str(NATIVE_PYTHON)})) - self.select_host('source-control',os.environ['TULDOK_DATABASE_URL']) - self.call('new',root='fixture',directory='source',name='Actual model-aware native Run') - - def select_host(self,name,dsn): - control=self.root/name - workspace=ProjectWorkspace(control,{'fixture':self.external},dsn=dsn) - owner=ExplicitOwnerFixture.bootstrap(workspace) - self.hosts.append((workspace,owner));self.controls.append((control,dsn)) - self.workspace=workspace;self.owner=owner - - def call(self,action,**body): - workspace=self.workspace - with self.owner.bound(workspace): - state=workspace.status() - arguments=dict(binding=state['binding'],expected_checkpoint=(state['project']['checkpoint'] - if state['project'] else None),request_key=uuid.uuid4().hex,**body) - return workspace.dispatch('project_files.'+action,arguments) - - def cleanup(self): - for workspace,owner in reversed(self.hosts): - if workspace._closed:continue - with owner.bound(workspace): - projection=workspace._projection - if projection is not None:retain_project_evidence(projection,'direct-before-cleanup') - if projection is not None and projection.execution._runs is not None: - with projection.execution.runtime_access._reconcile():projection.execution._runs.close() - if projection.session.available and not projection.custody.has_pending: - projection.execution.reconcile_current() - workspace.close() - # Only schemas created below these disposable fixture control roots. - for control,dsn in self.controls: - with psycopg.connect(connection_info(dsn),autocommit=True) as connection: - for manifest in control.rglob('.tuldok.json'): - identity=json.loads(manifest.read_bytes()) - schema=('projection_'+identity['projection_id'] if identity['version']==2 - else 'catalog_'+identity['dataset_id']) - connection.execute(sql.SQL('DROP SCHEMA IF EXISTS {} CASCADE').format(sql.Identifier(schema))) - - def prepare_graph(self): - projection=self.workspace._projection - _,release=prepare_text_source(projection,key_prefix='native-direct-text') - body=dict(name='Actual direct text model evidence',recipe=text_training.MODEL_RECIPE,release_id=release['id']) - graph=projection.materials.mutate_definition('pipeline_graph','graphs.create',None,body, - projection.session.snapshot['checkpoint'],'native-direct-graph',lambda:projection.pipelines.create(body)) - return graph - - def await_drained(self,projection,run_id,timeout=None): - deadline=time.monotonic()+native_drain_wait_seconds(timeout);run=None - while time.monotonic()>'status'='stopping' THEN RAISE EXCEPTION 'authored deferred cancellation failure' USING ERRCODE='23514'; END IF; RETURN NEW; END $$") - db.execute('CREATE CONSTRAINT TRIGGER reject_cancel_commit AFTER UPDATE ON generation_jobs DEFERRABLE INITIALLY DEFERRED FOR EACH ROW EXECUTE FUNCTION reject_cancel_commit()') - try: - with patch.object(owner,'_signal_cancel',wraps=owner._signal_cancel) as signal,patch.object(owner.dataset.image_requests,'cancel',wraps=owner.dataset.image_requests.cancel) as provider_cancel: - with self.assertRaises(ProjectSessionError) as caught:self.adapter.cancel(self.family,ack['producer_id'],self.cp(),key) - self.assertEqual(caught.exception.code,'projection_unavailable') - self.assertEqual(signal.call_count,0);self.assertEqual(provider_cancel.call_count,0) - self.assertFalse(owner.stop.is_set());self.assertTrue(owner.worker.is_alive()) - self.assertFalse(self.session.available);self.assertTrue(self.adapter._fenced) - self.assertTrue(self.journal.has_pending) - self.assertEqual(owner._jobs()[0]['status'],'generating') - self.assertTrue(any(r['family']=='project_operation' and r['document']['request_key']==key for r in self.store.snapshot()['records'])) - finally:self._cleanup_fenced_fixture_worker(owner) - - def test_cancel_lost_sql_ack_fences_without_signalling_even_when_sql_committed(self): - ack,owner=self._active_image();db=self.session.db;original=psycopg.Connection.transaction;injected=[] - @contextmanager - def transaction(connection,*args,**kwargs): - with original(connection,*args,**kwargs):yield - if connection is db.connection and not injected: - rows=connection.execute("SELECT id FROM generation_jobs WHERE data::jsonb->>'status'='stopping'").fetchall() - if rows: - injected.append('actual-cancel-commit-ack-lost') - raise OSError('Authored lost cancellation commit acknowledgement') - try: - with patch.object(psycopg.Connection,'transaction',transaction),patch.object(owner,'_signal_cancel',wraps=owner._signal_cancel) as signal,patch.object(owner.dataset.image_requests,'cancel',wraps=owner.dataset.image_requests.cancel) as provider_cancel: - with self.assertRaises(ProjectSessionError) as caught:self.adapter.cancel(self.family,ack['producer_id'],self.cp(),uuid.uuid4().hex) - self.assertEqual(caught.exception.code,'projection_unavailable') - self.assertEqual(len(injected),1);self.assertEqual(signal.call_count,0);self.assertEqual(provider_cancel.call_count,0) - self.assertFalse(owner.stop.is_set());self.assertTrue(owner.worker.is_alive()) - self.assertFalse(self.session.available);self.assertTrue(self.adapter._fenced) - self.assertTrue(self.journal.has_pending) - self.assertEqual(owner._jobs()[0]['status'],'stopping') - finally:self._cleanup_fenced_fixture_worker(owner) - - def enable_journal(self): - from project_custody import ProjectCustody - self.custody_index=ProjectCustody(self.host.db.path,self.host.db.dataset_id) - self.journal=self.custody_index.for_projection(self.store,self.session.db.projection_id) - self.projection.custody=self.journal - self.projection.execution.custody=self.journal - self.session.publication_intent=self.journal.expect_publication - return self.journal - - def check_journal_before_http(self): - if self.journal is None:return - try: - values=self.journal.snapshot()['producers'] - if len(values)!=1 or values[0]['family']!=self.family or values[0]['phase']!='effect_intent' or values[0]['provider_outcome']!='unknown' or values[0]['worker_drained']: - raise AssertionError('Actual HTTP preceded durable original-host producer effect intent') - from project_custody import ProjectCustody - reread=ProjectCustody(self.host.db.path,self.host.db.dataset_id) - if not reread.pending(self.store):raise AssertionError('Original host journal was not durably readable before HTTP') - except BaseException as error:self.errors.append(str(error)) - - def test_original_host_journal_precedes_http_and_settles_only_actual_known_drain(self): - journal=self.enable_journal() - ack=self.adapter.start('text_proposal_history',self.body(),self.cp(),uuid.uuid4().hex) - job=self.wait();self.assertEqual(job['status'],'completed',job['error']) - self.assertTrue(journal.has_pending) - self.assertEqual(self.errors,[]) - self.adapter.assert_quiescent() - self.assertFalse(journal.has_pending) - from project_custody import ProjectCustody - self.assertEqual(ProjectCustody(self.host.db.path,self.host.db.dataset_id).pending(self.store),[]) - files=list((self.host.db.path/'.project-custody').glob('*.json')) - self.assertEqual(len(files),1);self.assertEqual(files[0].stat().st_mode & 0o777,0o600) - self.assertFalse((self.root/'project'/'.project-custody').exists()) - self.assertEqual(self.session.db.execute('SELECT count(*) FROM access_credentials').fetchone()[0],0) - - def test_unknown_provider_remains_in_original_host_journal_after_local_drain(self): - journal=self.enable_journal();self.hold=True - ack=self.adapter.start('text_proposal_history',self.body(),self.cp(),uuid.uuid4().hex) - self.assertTrue(self.observed.wait(8)) - self.adapter.cancel('text_proposal_history',ack['producer_id'],self.cp(),uuid.uuid4().hex) - self.assertFalse(self.adapter._owners['text_proposal_history'].worker.is_alive()) - health=self.adapter.status();self.assertTrue(health['fenced']) - retained=journal.snapshot()['producers'][0] - self.assertEqual(retained['provider_outcome'],'unknown');self.assertTrue(retained['worker_drained']) - from project_custody import ProjectCustody - reopened=ProjectCustody(self.host.db.path,self.host.db.dataset_id) - self.assertEqual(len(reopened.pending(self.store)),1) - self.assertEqual(self.errors,[]) - - def test_uncertain_original_host_effect_intent_ack_never_launches_worker(self): - journal=self.enable_journal();original=journal.producer_effect_intent - def lost(family,identity): - original(family,identity) - raise WorkbenchError('Authored lost original-host effect-intent acknowledgement','outcome_unknown',409) - with patch.object(journal,'producer_effect_intent',lost): - with self.assertRaises(WorkbenchError) as caught:self.adapter.start('text_proposal_history',self.body(),self.cp(),uuid.uuid4().hex) - self.assertEqual(caught.exception.code,'outcome_unknown') - self.assertEqual(self.requests,[]);self.assertFalse(self.session.available) - self.assertIsNone(self.adapter._owners['text_proposal_history'].worker) - from project_custody import ProjectCustody - reopened=ProjectCustody(self.host.db.path,self.host.db.dataset_id) - self.assertEqual(len(reopened.pending(self.store)),1) - self.assertEqual(journal.snapshot()['producers'][0]['phase'],'effect_intent') diff --git a/tests/test_project_producers.py b/tests/test_project_producers.py deleted file mode 100644 index 7e4f27a6..00000000 --- a/tests/test_project_producers.py +++ /dev/null @@ -1,414 +0,0 @@ -"""Real PostgreSQL inert producer codecs; all scientific observations synthetic. - -No model, provider service, Dataset or producer worker runs in these fixtures. -The source observations are authored explicitly and checked against owner wire -validators. Distinct projections prove that imported admissions cannot resume. -""" -import base64 -import copy -import hashlib -import io -import json -import os -from pathlib import Path -import tempfile -from types import SimpleNamespace -import unittest -from unittest.mock import patch -import uuid - -from PIL import Image -import psycopg -from psycopg import sql - -from access import Access, AccessError -from auth_helpers import ExplicitOwnerFixture -import caption_proposals as caption -import grounded_candidates as grounded -from metadata import Metadata, connection_info -from project_artifacts import ProjectArtifacts -from project_data import ProjectData, decode_data_records -from project_producers import ProjectProducers, decode_records, validate_target_proposal, validate_record_origin -from project_session import ProjectSession -from project_store import ProjectStore -import pumas_operations as pumas -import pumas_vision -import synthetic -import text_classification_proposals as classification -from workbench import WorkbenchError, encode, timestamp - -ROOT = Path(__file__).resolve().parents[1] - - -def sha(raw): - return hashlib.sha256(raw).hexdigest() - - -def response(annotation): - return encode({'model': 'fixture-model', 'choices': [{'finish_reason': 'stop', - 'message': {'role': 'assistant', 'content': encode(annotation)}}]}).encode() - - -def validate(records): - decode_data_records(records) - decode_records(records) - - -@unittest.skipUnless(os.environ.get('TULDOK_DATABASE_URL'), 'Requires disposable real local PostgreSQL') -class ProjectProducerTests(unittest.TestCase): - def setUp(self): - self.temporary = tempfile.TemporaryDirectory(prefix='tuldok-producer-codec-') - self.path = Path(self.temporary.name) - self.addCleanup(self.temporary.cleanup) - self.schemas, self.metadata = [], [] - self.addCleanup(self.cleanup_database) - self.store = ProjectStore.create(self.path/'project', 'Synthetic producer facts', uuid.uuid4().hex, '1'*64) - self.addCleanup(self.store.close) - self.artifacts = ProjectArtifacts(self.store) - self.addCleanup(self.artifacts.close) - self.session, self.host, self.owner = self.new_session('source') - self.producers = ProjectProducers(self.session) - self.data = ProjectData(self.session, generation_entries=self.producers.generation_jobs) - self.binding = self.owner.bound(self.host) - self.binding.__enter__() - self.addCleanup(self.binding.__exit__, None, None, None) - self.text = self.data.import_text({'name':'Captured café 山', 'text':'Café 山 means an exact source.', - 'groups':['fixture'], 'rights':'Owned synthetic test input'}, self.checkpoint(), uuid.uuid4().hex) - image = io.BytesIO(); Image.new('RGB',(16,8),'blue').save(image,'PNG') - self.image = self.data.import_image({'name':'Authored blue source','image':base64.b64encode(image.getvalue()).decode(), - 'groups':['fixture-image'],'rights':'Owned synthetic pixels'}, self.checkpoint(), uuid.uuid4().hex) - - def checkpoint(self): - return self.session.snapshot['checkpoint'] - - def new_session(self, name, dsn=None): - dsn = dsn or os.environ['TULDOK_DATABASE_URL'] - host_db = Metadata(self.path/(name+'-authority'), dsn=dsn) - projection = Metadata(self.path/(name+'-projection'), dsn=dsn, - dataset_id=self.store.snapshot()['project_id'], projection_id=uuid.uuid4().hex) - for db in (host_db, projection): - self.schemas.append((dsn, db.schema)); self.metadata.append(db) - host = SimpleNamespace(db=host_db, access=Access(host_db, host_db.path)) - owner = ExplicitOwnerFixture.bootstrap(host) - session = ProjectSession(self.store, projection, host.access, self.artifacts, validate_records=validate) - return session, host, owner - - def cleanup_database(self): - for db in reversed(self.metadata): - db.close() - for dsn, schema in self.schemas: - with psycopg.connect(connection_info(dsn), autocommit=True) as connection: - connection.execute(sql.SQL('DROP SCHEMA IF EXISTS {} CASCADE').format(sql.Identifier(schema))) - - def seed(self, table, job): - self.session.db.execute('INSERT INTO '+table+'(id,data) VALUES(%s,%s)',(job['id'],encode(job))) - - def proposal(self, kind='text', *, typed=False): - source = copy.deepcopy(self.text if kind=='text' else self.image) - module = classification if kind=='text' else caption - config = {'provider':'pumas_chat_compatible','server_url':'http://127.0.0.1:9', - 'model':'fixture-model','instruction':'Exact guidance café 山','seed':7} - if kind=='text': - config.update(requested_model='fixture-model',requested_server_url='http://127.0.0.1:9', labels=['first','second']) - annotation = {'label':'first'} if kind=='text' else {'caption':'A blue rectangle café 山.'} - raw = response(annotation) - now = timestamp() - job = {'schema_version':1,'id':uuid.uuid4().hex,'revision':3,'status':'completed','error':'', - 'created_at':now,'updated_at':now,'intent_sha256':'2'*64,'source':source,'config':config, - 'system_prompt':module.SYSTEM_PROMPT,'prompt_version':module.PROMPT_VERSION, - 'prompt_sha256':sha(module.SYSTEM_PROMPT.encode()),'annotation':annotation,'application':None, - 'raw_response_base64':base64.b64encode(raw).decode(),'response_sha256':sha(raw), - 'reported_model':'fixture-model','verification':'Synthetic shape observation; no semantic verification.', - 'admission_id':uuid.uuid4().hex,'request_digest':'3'*64} - if kind=='text': - job.update(labels_sha256=sha(encode(config['labels']).encode()),source_text_sha256=sha(source['text'].encode())) - else: - out=io.BytesIO(); Image.new('RGB',(16,8),'blue').save(out,'JPEG',quality=95); image=out.getvalue() - job.update(input_image_base64=base64.b64encode(image).decode(),input_image={'mime':'image/jpeg','size':[16,8], - 'bytes':len(image),'sha256':sha(image),'preparation':'oriented canonical RGB; thumbnail max 1600; JPEG quality 95'}) - if typed: - self.assertEqual(kind,'image') - fixture=ROOT/'tests/fixtures/pumas-image-to-text-v1/controlled-capabilities.json' - job['capability_observation']=pumas.validate_manifest(fixture.read_bytes()) - config.update(provider='pumas_image_to_text',model='controlled-vision',seed=None,protocol=pumas.PROTOCOL,profile='vision-cpu') - advertisement=(ROOT/'tests/fixtures/pumas-http-pr51/advertisement.json').read_bytes() - import pumas_gateway_descriptor - job['build_observation']=dict(pumas_gateway_descriptor.decode(advertisement),server_url='http://127.0.0.1:9') - job['producer_contract_source']=pumas_vision.SOURCE_COMMIT - job['provider_outcome']='result_received'; job['reported_model']=None - raw=encode({'contract_version':1,'request_id':job['id'],'result':{'kind':'text','text':encode(annotation),'finish_reason':'stop'}}).encode() - job.update(raw_response_base64=base64.b64encode(raw).decode(),response_sha256=sha(raw)) - job['canonical_request']=module.payload(job) - job['canonical_request_sha256']=sha(encode(module.payload(job)).encode()) - return job - - def generation(self): - job={'id':uuid.uuid4().hex,'config':{'server_url':'http://127.0.0.1:9','model':'fixture-model','prompt':'A blue source', - 'width':16,'height':8,'count':1,'strategy':'repeat','seed':4},'meta':{'book_id':'','session_id':'fixture','split':'unassigned'}, - 'status':'completed','error':'','completed':1,'admission_id':uuid.uuid4().hex,'request_digest':'4'*64} - entry=synthetic.Jobs._new_entry(job,0,job['config']['prompt']) - entry.update(status='completed',sample_id=self.image['id'],metadata={'seed':4,'duration_seconds':1.25}) - self.seed('generation_jobs',job) - self.session.db.execute('INSERT INTO generation_entries(id,job_id,ordinal,data) VALUES(%s,%s,%s,%s)', - (entry['id'],entry['job_id'],entry['ordinal'],encode(entry))) - return job,entry - - def commit_producers(self): - upserts=self.producers.capture_source() - merged={(r['family'],r['id']):r for r in self.session.snapshot['records']} - merged.update({(r['family'],r['id']):r for r in upserts}) - snapshot=self.store.commit([merged[k] for k in sorted(merged)],self.checkpoint(),uuid.uuid4().hex,'5'*64) - self.session.adopt(snapshot) - return snapshot - - def grounded_proposal(self): - source=self.data.annotate(self.text['id'],dict(revision=self.text['revision'],source_revision=1, - task='text_classification',annotation={'label':'first'},groups=['fixture'],review='human_reviewed'), - self.checkpoint(),uuid.uuid4().hex) - job=self.proposal() - for field in ('intent_sha256','annotation','application','labels_sha256','source_text_sha256'): - job.pop(field) - job.update(source=source,system_prompt=grounded.SYSTEM_PROMPT,prompt_version=grounded.PROMPT_VERSION, - prompt_sha256=sha(grounded.SYSTEM_PROMPT.encode()),config={'server_url':'http://127.0.0.1:9', - 'model':'fixture-model','instruction':'Preserve the reviewed meaning','seed':7,'count':1}) - value={'text':'An exact source means café 山.','label':'first', - 'evidence':[{'start':0,'end':len(source['text']),'quote':source['text']}]} - raw=response({'candidates':[value]}) - job.update(candidates=[dict(value,id=uuid.uuid4().hex,status='pending_review',record_id=None,review_note='')], - raw_response=raw.decode(),raw_response_base64=base64.b64encode(raw).decode(),response_sha256=sha(raw), - canonical_request_sha256=sha(encode(grounded.request_payload(job)).encode())) - return job - - def test_grounded_source_class_quotes_and_exact_response_are_one_closed_history(self): - job=self.grounded_proposal();self.seed('grounded_jobs',job) - snapshot=self.commit_producers() - doc=next(item['document'] for item in snapshot['records'] if item['family']=='grounded_history') - self.assertEqual(doc['job']['source'],job['source']) - self.assertEqual(doc['job']['candidates'],job['candidates']) - self.assertTrue(doc['job']['raw_response_text_available']) - for mutate in (lambda d:d['job']['candidates'][0].update(label='second'), - lambda d:d['job']['candidates'][0]['evidence'][0].update(quote='invented'), - lambda d:d['job']['candidates'][0].update(text='Invented replacement.'), - lambda d:d.update(ordinal=0)): - changed=copy.deepcopy(snapshot['records']) - changed_doc=next(item['document'] for item in changed if item['family']=='grounded_history') - mutate(changed_doc) - with self.assertRaises(WorkbenchError):decode_records(changed,artifacts=self.artifacts) - - def test_applied_target_evidence_cannot_change_frozen_labels_source_or_review(self): - job=self.proposal() - source=job['source'] - job.update(status='applied',application={'record_id':source['id'],'revision':source['revision']+1,'source_revision':1}) - self.seed('text_classification_proposals',job) - snapshot=self.commit_producers() - record=dict(source,revision=source['revision']+1,task='text_classification',annotation=job['annotation'],review='draft') - evidence={'job_id':job['id'],'applied_revision':record['revision'],'captured_revision':source['revision'], - 'source_revision':1,'source_sha256':source['source_sha256'],'source_text_sha256':job['source_text_sha256'], - 'config':job['config'],'labels_sha256':job['labels_sha256'],'prompt_version':job['prompt_version'], - 'prompt_sha256':job['prompt_sha256'],'canonical_request_sha256':job['canonical_request_sha256'], - 'response_sha256':job['response_sha256'],'reported_model':job['reported_model'], - 'verification':'Exact label shape only; applied as draft, never approved.'} - self.assertTrue(validate_target_proposal(evidence,record,snapshot['records'])) - for key,value in (('labels_sha256','0'*64),('captured_revision',8),('source_sha256','0'*64), - ('response_sha256','0'*64),('config',None)): - with self.subTest(key=key),self.assertRaises(WorkbenchError): - validate_target_proposal(dict(evidence,**{key:value}),record,snapshot['records']) - with self.assertRaises(WorkbenchError): - validate_target_proposal(evidence,dict(record,review='human_reviewed'),snapshot['records']) - with self.assertRaises(WorkbenchError): - validate_target_proposal(evidence,record,[item for item in snapshot['records'] if item['family']!='text_proposal_history']) - - def test_typed_generation_attempt_preserves_exact_request_and_refuses_rewritten_intent(self): - job,entry=self.generation() - job['config'].update(model='controlled-image',protocol=pumas.PROTOCOL,profile='controlled-image-cpu') - entry.update(model='controlled-image',request_id=uuid.uuid4().hex) - evidence={'capability_observation':pumas.validate_manifest( - (ROOT/'tests/fixtures/pumas-typed-v1/controlled-image-capabilities.json').read_bytes()), - 'producer_contract_source':pumas.SOURCE_COMMIT} - request={'contract_version':1,'request_id':entry['request_id'],'model':'controlled-image', - 'profile':'controlled-image-cpu','capability':'image_generation','input':{'kind':'text','text':entry['prompt']}, - 'output':'png_base64','options':{'kind':'image_generation','width':16,'height':8,'seed':4},'stream':False} - pumas.request_evidence(evidence,request) - entry['attempt_evidence']=evidence - self.session.db.execute('UPDATE generation_jobs SET data=%s WHERE id=%s',(encode(job),job['id'])) - self.session.db.execute('UPDATE generation_entries SET data=%s WHERE id=%s',(encode(entry),entry['id'])) - snapshot=self.commit_producers() - doc=next(item['document'] for item in snapshot['records'] if item['family']=='generation_history') - wrapper=doc['entries'][0] - self.assertEqual(wrapper['payloads']['attempt_request']['artifact']['sha256'],sha(encode(request).encode())) - self.assertNotIn('canonical_request',wrapper['entry']['attempt_evidence']) - self.assertEqual(doc['ordinal'],1);self.assertEqual(wrapper['storage_order'],1) - changed=copy.deepcopy(snapshot['records']) - changed_doc=next(item['document'] for item in changed if item['family']=='generation_history') - changed_doc['entries'][0]['entry']['prompt']='A silently changed producer prompt' - changed_doc['entries'][0]['history'][0]['prompt']='A silently changed producer prompt' - with self.assertRaises(WorkbenchError):decode_records(changed,artifacts=self.artifacts) - - def test_outer_source_identity_and_credential_bearing_historical_urls_are_rejected(self): - job=self.proposal();self.seed('text_classification_proposals',job) - job['id']=uuid.uuid4().hex - self.session.db.execute('UPDATE text_classification_proposals SET data=%s',(encode(job),)) - with self.assertRaises(WorkbenchError):self.producers.capture_source() - self.session.db.execute('DELETE FROM text_classification_proposals') - job=self.proposal();job['config']['server_url']='http://user:password@127.0.0.1:9' - self.seed('text_classification_proposals',job) - with self.assertRaises(ValueError):self.producers.capture_source() - - def test_generated_origin_requires_exact_entry_metadata_and_source_identity(self): - job,entry=self.generation();snapshot=self.commit_producers() - generation={key:entry[key] for key in ('job_id','ordinal','prompt','model','width','height','requested_seed','metadata')} - origin={'method':'model_generated','rights':'Owned synthetic pixels','source_sha256':self.image['source_sha256'], - 'generation':generation} - self.assertTrue(validate_record_origin(origin,self.image,snapshot['records'])) - changed=copy.deepcopy(origin);changed['generation']['metadata']['duration_seconds']=500 - with self.assertRaises(WorkbenchError):validate_record_origin(changed,self.image,snapshot['records']) - with self.assertRaises(WorkbenchError): - validate_record_origin(origin,dict(self.image,id=uuid.uuid4().hex),snapshot['records']) - self.assertFalse(validate_record_origin({'method':'import'},self.image,snapshot['records'])) - - def test_grounded_origin_retains_reviewed_source_and_candidate_disposition(self): - job=self.grounded_proposal();candidate=job['candidates'][0] - target=self.data.import_text({'name':'Retained rewrite','text':candidate['text'],'groups':['fixture'], - 'rights':'Owned synthetic candidate'},self.checkpoint(),uuid.uuid4().hex) - candidate.update(status='admitted',record_id=target['id'],review_note='Inspected proposal as a draft.') - self.seed('grounded_jobs',job);snapshot=self.commit_producers() - source=job['source'] - origin={'method':'model_grounded_rewrite','rights':'Owned synthetic candidate','normalization':'NFC; LF newlines', - 'provider':'pumas_chat_compatible','server_url':job['config']['server_url'],'requested_model':job['config']['model'], - 'requested_seed':job['config']['seed'],'instruction':job['config']['instruction'],'system_prompt':job['system_prompt'], - 'prompt_version':job['prompt_version'],'prompt_sha256':job['prompt_sha256'],'reported_model':job['reported_model'], - 'canonical_request_sha256':job['canonical_request_sha256'],'requested_count':1,'max_tokens':6000, - 'job_id':job['id'],'candidate_id':candidate['id'],'response_sha256':job['response_sha256'], - 'source':{key:source[key] for key in ('id','revision','source_revision','content_hash','text','annotation')}, - 'evidence':candidate['evidence'],'verification':job['verification'],'admission_note':candidate['review_note']} - target=dict(target,annotation={'label':'first'}) - self.assertTrue(validate_record_origin(origin,target,snapshot['records'])) - for change in ({'source':dict(origin['source'],revision=900)}, {'admission_note':'An unrecorded disposition'}, - {'evidence':[{'start':0,'end':1,'quote':'X'}]}, {'provider':'unrecognized'}): - with self.assertRaises(WorkbenchError):validate_record_origin(dict(origin,**change),target,snapshot['records']) - with self.assertRaises(WorkbenchError): - validate_record_origin(origin,dict(target,review='human_reviewed'),snapshot['records']) - - def test_utf16_response_bytes_stay_exact_and_opaque_secret_bound_responses_fail(self): - job=self.grounded_proposal() - raw=job['raw_response'].encode('utf-16') - job.update(raw_response=None,raw_response_base64=base64.b64encode(raw).decode(),response_sha256=sha(raw)) - self.seed('grounded_jobs',job);snapshot=self.commit_producers() - doc=next(item['document'] for item in snapshot['records'] if item['family']=='grounded_history') - self.assertFalse(doc['job']['raw_response_text_available']) - declaration=next(item['document'] for item in snapshot['records'] if item['family']=='project_artifact' and item['id']==sha(raw)) - self.assertEqual(self.artifacts.read_blob({key:declaration[key] for key in ('sha256','bytes')}),raw) - self.session.db.execute('DELETE FROM grounded_jobs') - bad=self.proposal();badraw=b'{"choices": [incomplete unknown bytes' - bad.update(status='failed',annotation=None,raw_response_base64=base64.b64encode(badraw).decode(),response_sha256=sha(badraw)) - self.seed('text_classification_proposals',bad) - with self.assertRaises(WorkbenchError) as rejected:self.producers.capture_source() - self.assertEqual(rejected.exception.code,'unsupported') - self.assertEqual(self.checkpoint(),snapshot['checkpoint']) - badraw=encode({'api_key':'synthetic-do-not-export','error':'provider error'}).encode('utf-16') - bad.update(raw_response_base64=base64.b64encode(badraw).decode(),response_sha256=sha(badraw)) - self.session.db.execute('UPDATE text_classification_proposals SET data=%s WHERE id=%s',(encode(bad),bad['id'])) - with self.assertRaises(WorkbenchError):self.producers.capture_source() - - def test_public_readers_are_current_host_authorized_bounded_and_explicit_about_missing_times(self): - proposal=self.proposal();self.seed('text_classification_proposals',proposal) - job,entry=self.generation();snapshot=self.commit_producers() - origin=self.session.db.dataset_id - summary=self.producers.list('generation_history',origin_catalog_id=origin,limit=1) - self.assertEqual((summary['total'],summary['offset'],summary['limit']),(1,0,1)) - self.assertEqual(summary['items'][0]['entry_count'],1) - self.assertIsNone(summary['items'][0]['revision']);self.assertIsNone(summary['items'][0]['created_at']) - self.assertEqual(self.producers.list('generation_history',offset=1)['items'],[]) - details=self.producers.get('generation_history',job['id'],origin_catalog_id=origin,entries_limit=1) - self.assertEqual(details['entries']['items'][0]['entry'],entry) - self.assertIsNone(details['entries']['next_offset']) - detail=self.producers.get('text_proposal_history',proposal['id'],origin_catalog_id=origin) - self.assertNotIn('source',detail['job']) - self.assertEqual(detail['source_reference']['id'],self.text['id']) - self.assertEqual(detail['payloads']['raw_response']['availability']['state'],'unverified') - with self.assertRaises(WorkbenchError): - self.producers.get('generation_history',job['id'],origin_catalog_id=uuid.uuid4().hex) - with self.assertRaises(WorkbenchError):self.producers.list('generation_history',limit=101) - _,other_host,other_owner=self.new_session('reader-other-host') - with other_owner.bound(other_host): - with self.assertRaises(AccessError):self.producers.list('generation_history') - with self.assertRaises(AccessError):self.producers.get('generation_history',job['id'],origin_catalog_id=origin) - self.assertEqual(self.checkpoint(),snapshot['checkpoint']) - - def test_real_postgres_cold_inert_history_keeps_exact_bytes_without_live_queues(self): - original=self.proposal(); self.seed('text_classification_proposals',original) - typed=self.proposal('image',typed=True); self.seed('caption_proposals',typed) - generation,entry=self.generation() - snapshot=self.commit_producers() - decoded=decode_records(snapshot['records'],artifacts=self.artifacts) - raw=encode(decoded) - self.assertNotIn(original['admission_id'],raw); self.assertNotIn(original['request_digest'],raw) - self.assertNotIn('raw_response_base64',raw); self.assertNotIn('input_image_base64',raw) - self.assertNotIn('server_url',encode(next(r for r in decoded if r['family']=='text_proposal_history')['document']['job']['config'])) - caption_doc=next(r['document'] for r in decoded if r['family']=='caption_proposal_history') - self.assertEqual(caption_doc['job']['build_observation']['observed_sha256'],typed['build_observation']['observed_sha256']) - self.assertEqual(caption_doc['observation_integrity']['build_observation'],'unverified_missing_original_wire') - dsn=os.environ.get('TULDOK_PROJECT_FILES_COLD_DATABASE_URL',os.environ['TULDOK_DATABASE_URL']) - target,host,owner=self.new_session('cold',dsn) - with patch('synthetic.Jobs',side_effect=AssertionError('No producer constructor')), \ - patch('grounded_candidates.Proposals',side_effect=AssertionError('No grounded constructor')), \ - patch('caption_proposals.CaptionProposals',side_effect=AssertionError('No caption constructor')), \ - patch('text_classification_proposals.TextClassificationProposals',side_effect=AssertionError('No classifier constructor')), \ - patch('http.client.HTTPConnection.connect',side_effect=AssertionError('Historical endpoint must not be followed')), \ - patch('threading.Thread.start',side_effect=AssertionError('Open must not start workers')): - restored=ProjectProducers(target).restore(snapshot) - with owner.bound(host): - seen=restored.generation_jobs.snapshot() - self.assertEqual(seen['entries'],[next(r['document']['entries'][0]['entry'] for r in decoded if r['family']=='generation_history')]) - for table in ('generation_jobs','grounded_jobs','caption_proposals','text_classification_proposals'): - self.assertEqual(target.db.execute('SELECT count(*) FROM '+table).fetchone()[0],0) - composed={(item['family'],item['id']):item for item in snapshot['records']} - composed.update({(item['family'],item['id']):item for item in restored.capture()}) - self.assertEqual(decode_records(list(composed.values())),decoded) - declaration=next(r['document'] for r in snapshot['records'] if r['family']=='project_artifact' and r['id']==original['response_sha256']) - self.assertEqual(self.artifacts.read_blob({k:declaration[k] for k in ('sha256','bytes')}),base64.b64decode(original['raw_response_base64'])) - self.assertFalse(hasattr(restored.generation_jobs,'resume')) - - def test_actual_source_delete_canonically_keeps_original_producer_association(self): - job,entry=self.generation(); snapshot=self.commit_producers() - target,host,owner=self.new_session('delete') - restored=ProjectProducers(target).restore(snapshot) - data=ProjectData(target,generation_entries=restored.generation_jobs) - data.restore(snapshot) - with owner.bound(host): - data.delete_image_source(self.image['id'],{'revision':1},target.snapshot['checkpoint'],uuid.uuid4().hex) - doc=next(r['document'] for r in target.snapshot['records'] if r['family']=='generation_history') - self.assertEqual(doc['entries'][0]['entry']['status'],'deleted') - self.assertIsNone(doc['entries'][0]['entry']['sample_id']) - self.assertEqual(doc['entries'][0]['history'][0]['sample_id'],self.image['id']) - self.assertEqual(doc['entries'][0]['history'][1]['status'],'deleted') - self.assertEqual(doc['job']['completed'],1) - decode_records(target.snapshot['records'],artifacts=self.artifacts) - - def test_unknown_or_secret_source_fields_fail_before_payload_publication(self): - job=self.proposal();job['future_scientific_measurement']={'value':17};self.seed('text_classification_proposals',job) - before={p.relative_to(self.path/'project').as_posix():p.read_bytes() for p in (self.path/'project').rglob('*') if p.is_file()} - with self.assertRaises(WorkbenchError):self.producers.capture_source() - after={p.relative_to(self.path/'project').as_posix():p.read_bytes() for p in (self.path/'project').rglob('*') if p.is_file()} - self.assertEqual(before,after) - job.pop('future_scientific_measurement');job['config']['api_key']='synthetic-do-not-export' - self.session.db.execute('UPDATE text_classification_proposals SET data=%s WHERE id=%s',(encode(job),job['id'])) - with self.assertRaises(WorkbenchError):self.producers.capture_source() - self.assertNotIn('synthetic-do-not-export',encode(self.store.snapshot())) - - def test_missing_evidence_allows_inert_metadata_but_corruption_refuses_restore(self): - job=self.proposal();self.seed('text_classification_proposals',job);snapshot=self.commit_producers() - payload=self.path/'project/artifacts/sha256'/job['response_sha256'] - # Artifact storage owns the exact layout; use its declared payload root. - candidates=[p for p in (self.path/'project/artifacts').rglob(job['response_sha256']) if p.is_file()] - self.assertEqual(len(candidates),1);payload=candidates[0] - original=payload.read_bytes();payload.unlink() - self.assertTrue(decode_records(snapshot['records'],artifacts=self.artifacts)) - payload.write_bytes(b'changed response bytes') - target,host,owner=self.new_session('corrupt') - with self.assertRaises(WorkbenchError):ProjectProducers(target).restore(snapshot) - self.assertEqual(target.db.execute('SELECT count(*) FROM generation_entries').fetchone()[0],0) - payload.write_bytes(original) - - -if __name__=='__main__':unittest.main() diff --git a/tests/test_project_projection.py b/tests/test_project_projection.py deleted file mode 100644 index 377b2767..00000000 --- a/tests/test_project_projection.py +++ /dev/null @@ -1,185 +0,0 @@ -"""Complete inert projection boundaries over disposable real PostgreSQL.""" -import copy -import hashlib -import json -import os -from pathlib import Path -import tempfile -import unittest -from unittest.mock import PropertyMock, patch -import uuid - -import psycopg -from psycopg import sql - -from auth_helpers import ExplicitOwnerFixture -from metadata import connection_info -from project_session import OPERATION_FORMAT, operation_documents -from project_workspace import ProjectWorkspace, http_arguments -from workbench import WorkbenchError - - -@unittest.skipUnless(os.environ.get('TULDOK_DATABASE_URL'), 'Requires disposable PostgreSQL') -class ProjectProjectionTests(unittest.TestCase): - def setUp(self): - self.tmp = tempfile.TemporaryDirectory(prefix='tuldok-project-projection-') - self.root = Path(self.tmp.name) - self.external = self.root / 'external'; self.external.mkdir() - self.hosts = [] - self.addCleanup(self.tmp.cleanup) - self.addCleanup(self.cleanup) - self.start() - self.call('new', dict(binding=self.state()['binding'], expected_checkpoint=None, - request_key='create-mixed', root='fixture', directory='project', name='Inert mixed project')) - - def start(self, *, cold=False): - control = self.root / ('control-' + uuid.uuid4().hex) - dsn = os.environ.get('TULDOK_PROJECT_FILES_COLD_DATABASE_URL') if cold else os.environ['TULDOK_DATABASE_URL'] - if cold and not dsn: - self.fail('Distinct-role cold database is a required fixture for this selection.') - host = ProjectWorkspace(control, {'fixture': self.external}, dsn=dsn) - owner = ExplicitOwnerFixture.bootstrap(host) - self.hosts.append((host, owner, control, dsn)) - self.host, self.owner = host, owner - - def cleanup(self): - owned = [] - for host, _, control, dsn in self.hosts: - host.close() - for manifest in control.rglob('.tuldok.json'): - value = json.loads(manifest.read_bytes()) - owned.append((dsn, 'projection_' + value['projection_id'] if value['version'] == 2 - else 'catalog_' + value['dataset_id'])) - for dsn, schema in owned: - with psycopg.connect(dsn, autocommit=True) as connection: - connection.execute(sql.SQL('DROP SCHEMA IF EXISTS {} CASCADE').format(sql.Identifier(schema))) - - def call(self, action, body=None): - with self.owner.bound(self.host): - return self.host.dispatch('project_files.' + action, body or {}) - - def state(self): - return self.call('status') - - def mutation(self, **fields): - state = self.state() - return dict(binding=state['binding'], expected_checkpoint=state['project']['checkpoint'], - request_key=uuid.uuid4().hex, **fields) - - def test_mixed_cold_projection_preserves_notes_and_definitions_without_worker_constructors(self): - text = self.call('import_text', self.mutation(asset=dict(text='Unique observation 山', groups=['owned'])))['record'] - with self.owner.bound(self.host): - p = self.host._projection - body = dict(name='Neutral metadata', task=dict(kind='task', catalog_id=p.project_id, - id='neutral', revision=1, sha256='a' * 64), kind='template', - specification={'scientific_decision': 'retained'}, source_selector=None, - preprocessing_policy={'kind': 'identity'}, output_policy={'kind': 'bytes'}) - model = p.materials.mutate_definition('model_definition', 'models.create', None, body, - p.session.snapshot['checkpoint'], 'model-create', lambda: p.models.create(body)) - # Another workspace sees edits only after they are saved to the folder. - self.call('save', self.mutation()) - snapshot = self.host._store.snapshot() - canonical = (self.external / 'project' / '.tuldok' / 'project.json').read_bytes() - sentinel = self.external / 'project' / 'must-not-run' - (self.external / 'project' / 'project_script.py').write_text( - 'from pathlib import Path\nPath(' + repr(str(sentinel)) + ').write_text("EXECUTED")\n') - self.call('close', self.mutation()) - self.start(cold=True) - # These assertions observe actual reconstruction; they do not replace - # the database or filesystem with mocked implementations. - with patch('runs.Runs.__init__', side_effect=AssertionError('live Runs on Open')), \ - patch('app.Dataset.__init__', side_effect=AssertionError('Dataset on Open')), \ - patch('subprocess.Popen', side_effect=AssertionError('process on Open')): - state = self.state() - self.call('open', dict(binding=state['binding'], expected_checkpoint=None, - root='fixture', directory='project', request_key='cold-open')) - self.assertFalse(sentinel.exists()) - self.assertEqual(self.host._store.snapshot(), snapshot) - self.assertEqual((self.external/'project'/'.tuldok'/'project.json').read_bytes(), canonical) - with self.owner.bound(self.host): - p = self.host._projection - self.assertEqual(p.data.get(text['id'])['text'], text['text']) - self.assertEqual(p.models.get(model['id']), model) - self.assertEqual(p.db.execute('SELECT COUNT(*) FROM workspace_projects').fetchone()[0], 0) - self.assertEqual(p.db.execute('SELECT COUNT(*) FROM workspace_runs').fetchone()[0], 0) - self.assertEqual(p.db.execute('SELECT COUNT(*) FROM access_credentials').fetchone()[0], 0) - - def test_unknown_receipt_is_rejected_before_invoke_and_sql_or_checkpoint_changes(self): - p = self.host._projection - before = p.store.snapshot() - key = 'forged-unknown' - project_id = before['project_id'] - record = dict(family='project_operation', id=project_id + '.' + hashlib.sha256(key.encode()).hexdigest(), document=dict( - format=OPERATION_FORMAT, project_id=project_id, operation='unowned.operation', target=None, request_key=key, - input_sha256='b'*64, result={'token': 'must-not-import'})) - self.assertEqual(operation_documents([record]), [record['document']]) - with self.owner.bound(self.host), \ - patch.object(p.session, 'mutate', side_effect=AssertionError('Unknown receipt invoked a mutation')) as mutate, \ - self.assertRaises(WorkbenchError) as caught: - p.validate_records([*before['records'], record]) - mutate.assert_not_called() - self.assertEqual(caught.exception.code, 'unsupported') - self.assertEqual(p.store.snapshot(), before) - self.assertEqual(p.db.execute('SELECT COUNT(*) FROM workbench_records').fetchone()[0], 0) - - def test_text_tag_uses_real_session_summary_and_record_list_remains_owned(self): - text = self.call('import_text', self.mutation(asset=dict(text='Owned note 山', groups=['owned'])))['record'] - p = self.host._projection - with self.owner.bound(self.host): - expected = dict(project_id=p.session.summary['project_id'], - checkpoint=p.session.summary['checkpoint']) - with patch.object(type(p.session), 'snapshot', new_callable=PropertyMock, - side_effect=AssertionError('Scalar tag copied a full Session')): - self.assertEqual(p.text._tag(dict(value='Exact scalar tag')), - dict(expected, value='Exact scalar tag')) - exact_current = [r['document']['current'] for r in p.session.snapshot['records'] - if r['family'] in ('workbench_text', 'workbench_record') - and r['document']['current']['kind'] == 'text'] - result = p.text.records() - self.assertEqual(result, dict(expected, items=exact_current)) - self.assertEqual([r['id'] for r in result['items']], [text['id']]) - result['items'][0]['text'] = 'Caller mutation' - self.assertEqual(p.text.get(text['id'])['text'], 'Owned note 山') - - def test_explicit_rooted_artifact_supply_is_durable_and_never_fetches_or_executes(self): - p = self.host._projection - raw = b'Unique measured bytes; never regenerate these.\n' - digest = hashlib.sha256(raw).hexdigest() - declaration = dict(format='project_artifact_v1', sha256=digest, bytes=len(raw)) - before = p.session.snapshot - snapshot = p.store.commit([dict(family='project_artifact', id=digest, document=declaration)], - before['checkpoint'], 'declare-fixture', 'c'*64) - p.session.adopt(snapshot) - source = self.external / 'payload.bin'; source.write_bytes(raw) - body = dict(sha256=digest, root='fixture', path='payload.bin') - with self.owner.bound(self.host), patch('subprocess.Popen', side_effect=AssertionError('execution')): - result = p.resolve_artifact(body, snapshot['checkpoint'], 'supply-payload') - self.assertEqual(p.artifacts.status(declaration)['state'], 'verified') - acknowledged = p.session.snapshot - source.unlink() - self.assertEqual(p.resolve_artifact(body, snapshot['checkpoint'], 'supply-payload'), result) - self.assertEqual(p.session.snapshot, acknowledged) - self.assertEqual(p.artifacts.read_blob(dict(sha256=digest, bytes=len(raw))), raw) - source.symlink_to('/dev/null') - with self.assertRaises((WorkbenchError, OSError)): - p.resolve_artifact(body, acknowledged['checkpoint'], 'supply-symlink') - self.assertEqual(p.session.snapshot, acknowledged) - self.call('close', self.mutation()) - state = self.state() - self.call('open', dict(binding=state['binding'], expected_checkpoint=None, root='fixture', - directory='project', request_key='reopen-supplied')) - self.assertEqual(self.host._projection.artifacts.status(declaration)['state'], 'verified') - - def test_finite_http_routes_keep_literal_import_and_reject_duplicate_locations(self): - import agent_api - arguments = self.mutation(text='Owned route body', groups=['owned']) - method, target, body = agent_api.project_request('project_files.data_import_text', arguments) - name, actual = http_arguments(method, target, body) - self.assertEqual(name, 'project_files.data_import_text') - self.assertEqual(actual, arguments) - state = self.state() - arguments = dict(binding=state['binding'], checkpoint=state['project']['checkpoint'], record_id='c'*32) - method, target, body = agent_api.project_request('project_files.data_get', arguments) - self.assertEqual(http_arguments(method, target, body), ('project_files.data_get', arguments)) - with self.assertRaises(agent_api.AgentAPIError): - http_arguments('GET', target + '&record_id=' + 'c'*32) diff --git a/tests/test_project_publication_recovery.py b/tests/test_project_publication_recovery.py deleted file mode 100644 index 36067a6b..00000000 --- a/tests/test_project_publication_recovery.py +++ /dev/null @@ -1,116 +0,0 @@ -"""Real committed-stage recovery preserves bytes and never reconstructs sources.""" -import errno -import os -import shutil -import unittest -from unittest.mock import patch - -from project_composition import composition_input -from project_fork import recover_committed_publication -from project_store import ProjectStore, ProjectStoreError -from project_files import file_id, materialize_captured -from test_project_composition_publication import CompositionPublicationTests - - -class PublicationRecoveryTests(unittest.TestCase): - setUp=CompositionPublicationTests.setUp - publish=CompositionPublicationTests.publish - assert_code=CompositionPublicationTests.assert_code - - def stage(self): - with patch('project_fork._rename_noreplace',side_effect=OSError(errno.EIO,'interrupted before rename')): - self.assert_code('unavailable',self.publish) - self.staging=next(self.root.glob('.tuldok-fork-*')) - with ProjectStore.open(self.staging) as store: - self.committed=store.snapshot() - self.request=composition_input(self.snapshots,'combined','Combined','compose-exact') - - def recover(self,**changes): - args=dict(root_path=self.root,expected_project_id=self.committed['project_id'], - expected_checkpoint=self.committed['checkpoint'],expected_request=self.request,quiescent=True) - args.update(changes) - return recover_committed_publication(self.fd,self.staging.name,'combined',**args) - - def test_committed_stage_recovers_without_sources_payload_copies_or_new_identity(self): - self.stage() - before={p.name:(p.read_bytes(),p.stat().st_ino) for p in (self.staging/'artifacts/sha256').iterdir()} - for store,artifacts in zip(self.stores,self.artifacts): - artifacts.close();store.close();shutil.rmtree(store.path) - with patch('project_artifacts.ProjectArtifacts.copy_many_to',side_effect=AssertionError('No recopy')), \ - patch('project_composition.build_candidate',side_effect=AssertionError('No rebuild')): - result=self.recover() - self.assertFalse(self.staging.exists()) - self.assertEqual(result['payloads_copied'],0) - self.assertFalse(result['selected']) - with ProjectStore.open(self.root/'combined') as store: - self.assertEqual(store.snapshot(),self.committed) - after={p.name:(p.read_bytes(),p.stat().st_ino) for p in (self.root/'combined/artifacts/sha256').iterdir()} - self.assertEqual(before,after) - self.assertTrue(self.recover()['reconciled']) - - def test_wrong_request_checkpoint_or_identity_never_publishes(self): - self.stage() - self.assert_code('stale',lambda:self.recover(expected_checkpoint='0'*64)) - self.assert_code('stale',lambda:self.recover(expected_project_id='0'*32)) - self.assert_code('conflict',lambda:self.recover(expected_request={**self.request,'name':'Changed'})) - self.assert_code('busy',lambda:self.recover(quiescent=False)) - self.assertTrue(self.staging.exists());self.assertFalse((self.root/'combined').exists()) - - def test_missing_copied_payload_preserves_stage_and_refuses_publication(self): - self.stage();next((self.staging/'artifacts/sha256').iterdir()).unlink() - with self.assertRaises(ProjectStoreError):self.recover() - self.assertTrue(self.staging.exists());self.assertFalse((self.root/'combined').exists()) - - def test_destination_appearance_never_overwrites_either_tree(self): - self.stage();(self.root/'combined').mkdir();(self.root/'combined/unique').write_bytes(b'keep') - self.assert_code('conflict',self.recover) - self.assertTrue(self.staging.exists());self.assertEqual((self.root/'combined/unique').read_bytes(),b'keep') - - def test_lost_rename_ack_reconciles_exact_published_checkpoint(self): - self.stage();fsync=os.fsync - def fail_after_publish(fd): - if (self.root/'combined').exists():raise OSError(errno.EIO,'lost publication acknowledgement') - fsync(fd) - with patch('project_fork.os.fsync',side_effect=fail_after_publish): - self.assert_code('unknown',self.recover) - self.assertFalse(self.staging.exists());self.assertTrue(self.recover()['reconciled']) - - def test_live_writer_and_non_stage_path_are_refused(self): - self.stage() - with ProjectStore.open(self.staging): - self.assert_code('busy',self.recover) - self.assert_code('invalid',lambda:recover_committed_publication(self.fd,'source0','combined', - root_path=self.root,expected_project_id=self.committed['project_id'],expected_checkpoint=self.committed['checkpoint'], - expected_request=self.request,quiescent=True)) - - def test_initial_empty_stage_cannot_be_mistaken_for_committed_publication(self): - self.stage();empty_name='.tuldok-fork-'+'9'*32 - with ProjectStore.create(self.root/empty_name,'Uncommitted','initial','a'*64) as store: - initial=store.snapshot() - self.assert_code('invalid',lambda:recover_committed_publication(self.fd,empty_name,'combined', - root_path=self.root,expected_project_id=initial['project_id'],expected_checkpoint=initial['checkpoint'], - expected_request=self.request,quiescent=True)) - self.assertTrue((self.root/empty_name).exists());self.assertFalse((self.root/'combined').exists()) - - def test_missing_captured_working_file_refuses_without_changing_committed_history(self): - # Seed a real current note before composing; its cloned editable record - # and materialized bytes then pass through the normal publication path. - from datetime import datetime, timezone - import hashlib - store=self.stores[0];snap=store.snapshot();raw=b'original note\n' - version=dict(revision=1,text=raw.decode(),sha256=hashlib.sha256(raw).hexdigest(),bytes=len(raw), - actor_id='1'*32,adopted_at=datetime.now(timezone.utc).isoformat()) - doc=dict(format='project_file_v1',project_id=snap['project_id'],kind='note',path='notes/test.md', - current=version,history=[version],origin=None) - record=dict(family='project_file',id=file_id(snap['project_id'],'note','notes/test.md'),document=doc) - self.snapshots[0]=store.commit([*snap['records'],record],snap['checkpoint'],'note','c'*64) - with store.root_directory() as root: - materialize_captured(self.snapshots[0]['records'],snap['project_id'],root) - self.stage();(self.staging/'notes/test.md').unlink() - self.assert_code('working_files_changed',self.recover) - self.assertFalse((self.root/'combined').exists()) - with ProjectStore.open(self.staging) as retained: - self.assertEqual(retained.snapshot(),self.committed) - - -if __name__=='__main__':unittest.main() diff --git a/tests/test_project_receipt_validation.py b/tests/test_project_receipt_validation.py deleted file mode 100644 index bf69926f..00000000 --- a/tests/test_project_receipt_validation.py +++ /dev/null @@ -1,204 +0,0 @@ -"""One mixed candidate: retain every receipt check without repeated decoding.""" -import copy -import hashlib -import json -from pathlib import Path -import tempfile -import unittest -from unittest.mock import patch - -import project_files as files -import project_material as material -import project_measurements as measurements -import project_projection as projection -import project_sources as sources -from project_artifacts import ProjectArtifacts, ProjectArtifactError -from project_store import ProjectStore -from test_retained_measurements import fixture -from workbench import WorkbenchError - -PROJECT = 'a' * 32 -ACTOR = 'c' * 32 -INSTANT = '2026-10-25T00:00:00+00:00' - - -def sha(raw): - return hashlib.sha256(raw).hexdigest() - - -def operation(name, key, result): - return dict(family='project_operation', id=PROJECT + '.' + sha(key.encode()), document=dict( - format='project_operation_v2', project_id=PROJECT, operation=name, - target=None, request_key=key, input_sha256='d' * 64, result=copy.deepcopy(result))) - - -def candidate(): - packets = [] - for index in range(2): - value = fixture() - value['title'] = f'Packet {index}' - raw = json.dumps(value).encode() - packets.append(dict(raw=raw, sha256=sha(raw), path=f'packet-{index}.json', - reference_id=f'packet-{index}', title=value['title'])) - manifest = dict(schema_version=1, id='b' * 32, name='Receipt source', - data=[dict(id=p['reference_id'], label=p['title'], path=p['path'], sha256=p['sha256']) - for p in packets], recipes=[], evidence=[], requirements=[]) - raw = json.dumps(manifest).encode() - digest = sha(raw) - snapshot = dict(id=manifest['id'], name=manifest['name'], root='original', - root_identity=[1, 2], manifest_path='source.json', manifest_sha256=digest, manifest=manifest) - retained = dict(family='project_snapshot', id=PROJECT + '.' + digest, document=dict( - format=material.FAMILIES['project_snapshot'], origin_catalog_id=PROJECT, value=snapshot, - artifacts=[dict(name='source.json', blob=dict(sha256=digest, bytes=len(raw)), - role='project_manifest', preservation='unique', required_for=['snapshot_verification'])], audit=[])) - records = [retained] - for hashed, size in [(digest, len(raw)), *[(p['sha256'], len(p['raw'])) for p in packets]]: - records.append(dict(family='project_artifact', id=hashed, - document=dict(format='project_artifact_v1', sha256=hashed, bytes=size))) - source_result = dict(origin_catalog_id=PROJECT, project_id=manifest['id'], manifest_sha256=digest, - name=manifest['name'], schema_version=1, actor_id=ACTOR, registered_at=INSTANT) - for index in range(2): - records.append(operation('source.register', f'source-{index}', source_result)) - for index, packet in enumerate(packets): - doc = dict(format=measurements.FORMAT, origin_catalog_id=PROJECT, id=packet['sha256'], - title=packet['title'], blob=dict(sha256=packet['sha256'], bytes=len(packet['raw'])), - source=dict(origin_catalog_id=PROJECT, project_id=manifest['id'], manifest_sha256=digest, - reference_id=packet['reference_id'], path=packet['path'], measured_sha256=packet['sha256']), - actor_id=ACTOR, imported_at=INSTANT) - records.append(dict(family=measurements.FAMILY, id=PROJECT + '.' + packet['sha256'], document=doc)) - records.append(operation('measurements.import', f'packet-{index}', doc)) - for batch in range(2): - items = [] - for index in range(2): - path = f'notes/note-{batch}-{index}.md' - raw = f'Owned note {batch}-{index} 山'.encode() - version = dict(revision=1, sha256=sha(raw), bytes=len(raw), text=raw.decode(), - adopted_at=INSTANT, actor_id=ACTOR) - identity = files.file_id(PROJECT, 'note', path) - doc = dict(format=files.FORMAT, project_id=PROJECT, kind='note', path=path, - current=copy.deepcopy(version), history=[version], origin=None) - records.append(dict(family=files.FAMILY, id=identity, document=doc)) - items.append(dict(id=identity, project_id=PROJECT, kind='note', path=path, changed=True, - **{key: version[key] for key in ('revision', 'sha256', 'bytes', 'adopted_at')})) - records.append(operation('files.adopt_many', f'notes-{batch}', dict(items=items, changed_count=2))) - return records - - -class ReceiptValidationTests(unittest.TestCase): - def test_whole_candidate_decodes_each_receipt_owner_once(self): - records = candidate() - before = copy.deepcopy(records) - with patch.object(files, 'decode_records', wraps=files.decode_records) as file_decode, \ - patch.object(projection, 'decode_file_records', file_decode), \ - patch.object(measurements, 'decode_records', wraps=measurements.decode_records) as measurement_decode, \ - patch.object(projection, 'decode_measurement_records', measurement_decode), \ - patch.object(material, 'decode_records', wraps=material.decode_records) as material_decode, \ - patch.object(measurements, 'material_records', material_decode), \ - patch.object(sources, 'material_records', material_decode): - projection.validate_project_records(records, project_id=PROJECT, artifacts=None) - self.assertEqual(records, before) - for name, actual, expected in [('files', file_decode.call_count, 1), - ('measurements', measurement_decode.call_count, 1), - ('material-owning readers', material_decode.call_count, 3)]: - with self.subTest(owner=name): - self.assertEqual(actual, expected, 'Receipt validation redecoded the same candidate') - - def test_standalone_file_batch_decodes_inventory_once(self): - records = candidate() - result = next(r['document']['result'] for r in records - if r['family'] == 'project_operation' - and r['document']['operation'] == 'files.adopt_many') - with patch.object(files, 'decode_records', wraps=files.decode_records) as decode: - self.assertTrue(files.validate_operation_result('files.adopt_many', result, records)) - self.assertEqual(decode.call_count, 1, 'Each batch item decoded the full file inventory') - - def test_forged_late_file_or_measurement_receipt_is_rejected(self): - for owner in ('files.adopt_many', 'measurements.import', 'source.register'): - records = candidate() - result = [r['document']['result'] for r in records if r['family'] == 'project_operation' - and r['document']['operation'] == owner][-1] - if owner == 'files.adopt_many': - result['items'][-1]['sha256'] = 'e' * 64 - else: - result['name' if owner == 'source.register' else 'title'] = 'Forged retained value' - with self.subTest(owner=owner), self.assertRaises(WorkbenchError): - projection.validate_project_records(records, project_id=PROJECT, artifacts=None) - - def test_unknown_operation_still_has_no_accepting_owner(self): - records = candidate() - records.append(operation('unknown.capture', 'unknown', {})) - with self.assertRaises(WorkbenchError) as error: - projection.validate_project_records(records, project_id=PROJECT, artifacts=None) - self.assertEqual(error.exception.code, 'unsupported') - - def test_owned_validators_and_standalone_calls_do_not_share_candidates(self): - for name, module in [('files.adopt_many', files), ('measurements.import', measurements), - ('source.register', sources)]: - records = candidate() - original_result = copy.deepcopy(next(r['document']['result'] for r in records - if r['family'] == 'project_operation' and r['document']['operation'] == name)) - checker = module.receipt_validator(records) - self.assertTrue(checker(name, original_result)) - self.assertTrue(module.validate_operation_result(name, original_result, records)) - if module is files: - doc = next(r['document'] for r in records if r['family'] == files.FAMILY) - value = doc['history'][0] - value.update(text='Edited candidate', sha256=sha(b'Edited candidate'), bytes=16) - doc['current'] = copy.deepcopy(value) - elif module is measurements: - next(r['document'] for r in records if r['family'] == measurements.FAMILY)['title'] = 'Edited candidate' - else: - value = next(r['document']['value'] for r in records if r['family'] == 'project_snapshot') - value['name'] = value['manifest']['name'] = 'Edited candidate' - with self.subTest(owner=name): - self.assertTrue(checker(name, original_result), 'Owned candidate changed with caller mutation') - with self.assertRaises(WorkbenchError): - module.receipt_validator(records)(name, original_result) - with self.assertRaises(WorkbenchError): - module.validate_operation_result(name, original_result, records) - - def test_standalone_unrecognized_and_malformed_results_do_not_decode(self): - for name, module in [('files.adopt_many', files), ('measurements.import', measurements), - ('source.register', sources)]: - records = candidate() - attribute = 'material_records' if module is sources else 'decode_records' - with self.subTest(owner=name), patch.object(module, attribute, - side_effect=AssertionError('Result shape must precede candidate decoding')) as decode: - self.assertFalse(module.validate_operation_result('unknown.capture', {}, records)) - with self.assertRaises(WorkbenchError): - module.validate_operation_result(name, {}, records) - decode.assert_not_called() - - def test_unused_malformed_file_and_missing_packet_reference_still_reject(self): - records = candidate() - next(r['document']['history'][0] for r in records if r['family'] == files.FAMILY)['text'] = 'Unhashed' - records = [r for r in records if r['family'] != 'project_operation' - or r['document']['operation'] != 'files.adopt_many'] - with self.assertRaises(WorkbenchError): - projection.validate_project_records(records, project_id=PROJECT, artifacts=None) - records = candidate() - next(r['document'] for r in records if r['family'] == measurements.FAMILY)['source']['reference_id'] = 'absent' - with self.assertRaises(WorkbenchError): - projection.validate_project_records(records, project_id=PROJECT, artifacts=None) - - def test_each_new_measurement_validator_checks_actual_packet_bytes(self): - records = candidate() - with tempfile.TemporaryDirectory() as temporary: - root = Path(temporary) / 'project' - with ProjectStore.create(root, 'Packet custody fixture', 'create', 'a' * 64) as store: - with ProjectArtifacts(store) as artifacts: - docs = [r['document'] for r in records if r['family'] == measurements.FAMILY] - for index, doc in enumerate(docs): - packet = fixture() - packet['title'] = f'Packet {index}' - raw = json.dumps(packet).encode() - self.assertEqual(sha(raw), doc['id']) - artifacts.publish_bytes(raw, measurements.declaration(doc['blob'])) - checker = measurements.receipt_validator(records, artifacts=artifacts) - self.assertTrue(checker('measurements.import', docs[0])) - payload = root / 'artifacts/sha256' / docs[0]['id'] - raw = payload.read_bytes() - payload.chmod(0o600) - payload.write_bytes(bytes([raw[0] ^ 1]) + raw[1:]) - with self.assertRaises((WorkbenchError, ProjectArtifactError)): - measurements.receipt_validator(records, artifacts=artifacts) diff --git a/tests/test_project_record_dedupe.py b/tests/test_project_record_dedupe.py deleted file mode 100644 index 3c8d1760..00000000 --- a/tests/test_project_record_dedupe.py +++ /dev/null @@ -1,150 +0,0 @@ -"""Shared runtime closures: compact storage, exact logical Run documents.""" -import copy -import json -from pathlib import Path -import tempfile -import unittest - -import project_record_dedupe as dedupe -import project_store as store_module -from project_store import ProjectStore - - -def runtime(): - files = {f'/opt/py/lib/module{i}.py': dict(bytes=10 + i, sha256=f'{i:064x}') for i in range(40)} - return dict(assumption='fixture', closure_sha256='c' * 64, executable='/opt/py/bin/python', - executable_sha256='e' * 64, files=files, flags=[], profile='fixture', trusted_install_owner_uid=0) - - -def run(identity, *, unique=3): - edges = [dict(blob=dict(bytes=len(path), sha256=item['sha256']), name=f'runtime-files/{n}', population='unknown', - preservation='regenerable', required_for=['scientific_inspection'], role='historical_runtime') - for n, (path, item) in enumerate(sorted(runtime()['files'].items()))] - before = [dict(blob=dict(bytes=n, sha256=f'{n+100:064x}'), name=f'input/{identity}/{n}', population='unknown', - preservation='unique', required_for=['execution_proof'], role='execution_source') for n in range(unique)] - after = [dict(blob=dict(bytes=7, sha256='a' * 64), name='output/model', population='unknown', - preservation='unique', required_for=['inspect'], role='output')] - spec = dict(argv=['python', 'train.py', identity], runtime_files=[dict(path=p, **v) for p, v in sorted(runtime()['files'].items())]) - document = dict(format='project_run_history_v1', origin_catalog_id='a' * 32, admission_proof=None, publication=None, - run=dict(id=identity, spec=spec, material=dict(recipe=dict(id='r'), runtime=runtime()), events=[1.5, -0.0, 'é']), - payloads=before + edges + after) - return dict(family='run_history', id='a' * 32 + '.' + identity, document=document) - - -class CompactionTests(unittest.TestCase): - def test_exact_roundtrip_and_refusals(self): - record = run('one') - compacted, closure = dedupe.compact(record['document']) - self.assertEqual(compacted['format'], dedupe.RUN_V2) - self.assertNotIn('runtime_files', compacted['run']['spec']) - self.assertEqual(store_module._encode(dedupe.expand(compacted, closure)), store_module._encode(record['document'])) - split = copy.deepcopy(record['document']) - split['payloads'].insert(10, split['payloads'].pop(0)) - self.assertIsNone(dedupe.compact(split), 'A non-contiguous runtime block stays uncompacted') - tampered = copy.deepcopy(closure); tampered['runtime']['profile'] = 'other' - with self.assertRaises(store_module.ProjectStoreError): - dedupe.expand(compacted, tampered) - - -class StoreTests(unittest.TestCase): - def setUp(self): - temporary = tempfile.TemporaryDirectory(prefix='tuldok-dedupe-') - self.addCleanup(temporary.cleanup) - self.root = Path(temporary.name) / 'project' - self.store = ProjectStore.create(self.root, 'Dedupe fixture', 'new', 'a' * 64) - self.addCleanup(lambda: self.store.close()) - - def files(self, family): - manifest = json.loads((self.root / '.tuldok/project.json').read_bytes()) - return [json.loads((self.root / '.tuldok' / e['path']).read_bytes()) for e in manifest['inventory'] if e['family'] == family] - - def test_runs_share_one_stored_closure_and_read_back_exactly(self): - records = [run('one'), run('two', unique=5)] - committed = self.store.commit(copy.deepcopy(records), self.store.summary()['checkpoint'], 'runs', 'b' * 64) - self.assertEqual([r['document'] for r in committed['records']], [r['document'] for r in records]) - self.assertEqual([d['format'] for d in self.files('run_history')], [dedupe.RUN_V2, dedupe.RUN_V2]) - self.assertEqual(len(self.files(dedupe.CLOSURE_FAMILY)), 1) - self.assertNotIn(dedupe.CLOSURE_FAMILY, {r['family'] for r in self.store.snapshot()['records']}) - self.store.close() - self.store = ProjectStore.open(self.root) - self.assertEqual(self.store.snapshot(), committed) - # Editing one Run keeps the other's verified revision and the closure. - changed = copy.deepcopy(records); changed[0]['document']['run']['events'].append('edited') - again = self.store.commit(changed, committed['checkpoint'], 'edit', 'c' * 64) - self.assertEqual(again['records'][0]['document'], changed[0]['document']) - self.store.close() - self.store = ProjectStore.open(self.root) - self.assertEqual(self.store.snapshot(), again) - self.assertEqual(len(self.files(dedupe.CLOSURE_FAMILY)), 1) - - def test_closures_are_store_owned(self): - with self.assertRaises(store_module.ProjectStoreError): - self.store.commit([dict(family=dedupe.CLOSURE_FAMILY, id='x', document=dict(format=dedupe.CLOSURE_FORMAT))], - self.store.summary()['checkpoint'], 'forged', 'd' * 64) - - -if __name__ == '__main__': - unittest.main() - - -import os -import uuid - - -@unittest.skipUnless(os.environ.get('TULDOK_DATABASE_URL'), 'Requires disposable PostgreSQL') -class WorkingStoreTests(unittest.TestCase): - def setUp(self): - temporary = tempfile.TemporaryDirectory(prefix='tuldok-dedupe-working-') - self.addCleanup(temporary.cleanup) - self.root = Path(temporary.name) / 'project' - with ProjectStore.create(self.root, 'Legacy runs', 'new', 'a' * 64) as store: - records = [run('one'), run('two', unique=4)] - self.legacy = store.commit(copy.deepcopy(records), store.summary()['checkpoint'], 'runs', 'b' * 64) - self.working_id = uuid.uuid4().hex - self.addCleanup(self.drop) - - def drop(self): - import psycopg - from psycopg import sql - from metadata import connection_info - with psycopg.connect(connection_info(None), autocommit=True) as connection: - connection.execute(sql.SQL('DROP SCHEMA IF EXISTS {} CASCADE').format(sql.Identifier('working_' + self.working_id))) - - def working(self): - from project_working_store import WorkingProjectStore - parent, leaf = os.path.split(str(self.root)) - descriptor = os.open(parent, store_module.DIR_FLAGS) - try: - folder = ProjectStore.open_folder_at(descriptor, leaf, root_path=parent) - finally: - os.close(descriptor) - return WorkingProjectStore.open(folder, self.working_id) - - def test_migration_keeps_logical_records_and_saves_compact_files(self): - from project_composition import _record_sha - store = self.working() - try: - before = store.snapshot()['records'] - previous, after = store.compact_run_closures('compact-runs', 'c' * 64) - self.assertNotEqual(previous, after['checkpoint']) - self.assertEqual(store.snapshot()['records'], before, 'Logical records are unchanged') - self.assertEqual(store.records('run_history'), [r for r in before if r['family'] == 'run_history']) - self.assertEqual(store.record('run_history', before[0]['id']), before[0]) - view = store.records_view('run_history') - self.assertNotIn(dedupe.CLOSURE_FAMILY, {r['family'] for r in view}) - digests = store.envelope_digests() - for record in before: - self.assertEqual(digests[(record['family'], record['id'])], _record_sha(record)) - # An edit through the session path keeps the shared closure. - changed = copy.deepcopy(before); changed[1]['document']['run']['events'].append('edited') - edited = store.commit(changed, after['checkpoint'], 'edit', 'd' * 64, changed={(changed[1]['family'], changed[1]['id']), }) - store.save(edited['checkpoint']) - saved = store.snapshot() - finally: - store.close() - manifest = json.loads((self.root / '.tuldok/project.json').read_bytes()) - families = [e['family'] for e in manifest['inventory']] - self.assertEqual(families.count(dedupe.CLOSURE_FAMILY), 1) - self.assertEqual({e['format'] for e in manifest['inventory'] if e['family'] == 'run_history'}, {dedupe.RUN_V2}) - with ProjectStore.open(self.root) as reread: - self.assertEqual(reread.snapshot(), saved, 'The file store reads the same logical records') diff --git a/tests/test_project_runtime.py b/tests/test_project_runtime.py deleted file mode 100644 index 75938e71..00000000 --- a/tests/test_project_runtime.py +++ /dev/null @@ -1,264 +0,0 @@ -"""Actual offline ELF inventory/copy and canonical two-phase runtime custody. - -The selected python binary is /usr/bin/true: representative bytes, never a -runnable Python/model environment. No package install, probe or child is run. -""" -import copy -import errno -import os -from pathlib import Path -import shutil -from types import SimpleNamespace -import unittest -from unittest.mock import patch - -from project_custody import ProjectCustody -from project_execution import ProjectExecution -from project_material import decode_records, validate_operation_result as material_result -from project_runtime import ProjectRuntime, validate_operation_result, _intent_key -from project_session import operation_documents, operation_records -from workbench import WorkbenchError -import test_project_material as material_fixture - - -@unittest.skipUnless(os.environ.get('TULDOK_DATABASE_URL'),'Requires disposable PostgreSQL') -class RuntimeCaptureTests(unittest.TestCase): - def setUp(self): - f=self.fixture=material_fixture.CanonicalPublication('test_model_publication_is_canonical_before_ack_and_has_one_session_receipt') - f.setUp();self.addCleanup(f.doCleanups) - self.control=ProjectCustody(f.host.path,f.host.dataset_id) - self.journal=self.control.for_projection(f.store,f.db.projection_id) - projection=SimpleNamespace(session=f.session,db=f.db,access=f.access,materials=f.material,custody=self.journal) - self.execution=projection.execution=ProjectExecution(projection) - f.session._validate=self.validate - self.runtime=ProjectRuntime(projection,resolve_configuration=self.resolve) - python=f.path/'explicit-python';site=f.path/'explicit-packages' - (python/'bin').mkdir(parents=True);(python/'lib/python3.12/lib-dynload').mkdir(parents=True) - shutil.copyfile('/usr/bin/true',python/'bin/python3.12') - (python/'lib/python3.12/lib-dynload/fixture.txt').write_text('fixture only') - entries=[] - for name in ('torch','numpy'): - (site/name).mkdir(parents=True) - (site/name/'__init__.py').write_text('raise AssertionError("Selected package must never be imported")\n') - info=site/(name+'-0.0.dist-info');info.mkdir() - (info/'METADATA').write_text('Name: '+name+'\nVersion: 0.0\n') - (info/'LICENSE').write_text('Owned fixture') - entries.extend([name,info.name]) - self.config=dict(schema_version=1,python_root=str(python),python_version='3.12',site_packages=str(site),packages=entries) - self.request=dict(profile='owned-fixture');self.key='capture:fixture' - self.cp=f.session.snapshot['checkpoint'] - - def resolve(self,request): - if request!=self.request:raise WorkbenchError('Choose a configured runtime source.','unavailable',409) - return copy.deepcopy(self.config) - - def validate(self,records): - decode_records(records) - for receipt in operation_documents(records): - if not (validate_operation_result(receipt['operation'],receipt['result'],records) - or material_result(receipt['operation'],receipt['result'],records)): - raise WorkbenchError('Unowned fixture receipt.') - - def observed(self): - with self.fixture.access.bind(self.fixture.owner.token):return self.runtime.inspect(self.request) - - def capture(self,observed=None,**kwargs): - observed=observed or self.observed() - with self.fixture.access.bind(self.fixture.owner.token): - return self.runtime.capture(self.request,observed['inventory_sha256'],self.cp,self.key,reserve_bytes=0,**kwargs) - - def test_actual_capture_retains_intent_manifest_and_all_declarations_without_running_binaries(self): - f=self.fixture - with patch('subprocess.Popen',side_effect=AssertionError('No execution, probe or install')): - observed=self.observed();result=self.capture(observed) - records=f.session.snapshot['records'];receipts=operation_records(records) - self.assertEqual(set(receipts),{_intent_key(self.key),self.key}) - self.assertEqual(receipts[_intent_key(self.key)]['operation'],'runtime.capture_intent') - self.assertEqual(result['format'],'project_runtime_capture_v1') - self.assertTrue(validate_operation_result('runtime.capture',result,records)) - self.assertEqual(result['actor_id'],f.owner.identity['actor_id']) - material=next(r['document'] for r in records if r['family']=='runtime_material') - declarations={r['id']:r['document'] for r in records if r['family']=='project_artifact'} - self.assertEqual(len(material['artifacts']),observed['file_count']+1) - self.assertEqual({e['preservation'] for e in material['artifacts'] if e['role']=='runtime_file'},{'regenerable'}) - for edge in material['artifacts']: - self.assertEqual(declarations[edge['blob']['sha256']],dict(format='project_artifact_v1',**edge['blob'])) - raw=(Path(material['value']['descriptor']['root'])/'manifest.json').read_bytes() - self.assertEqual(f.artifacts.read_blob(dict(sha256=result['manifest_sha256'],bytes=len(raw))),raw) - unique=[edge for edge in material['artifacts'] if edge['preservation']=='unique'] - self.assertEqual([edge['name'] for edge in unique],['manifest.json']) - file_edge=next(edge for edge in material['artifacts'] if edge['role']=='runtime_file') - self.assertEqual(f.artifacts.inspect(dict(format='project_artifact_v1',**file_edge['blob']))['state'],'missing') - self.assertFalse(self.execution.has_local_custody) - self.assertFalse(self.journal.has_pending) - self.assertEqual(self.control.pending(f.store),[]) - self.assertEqual(f.store.snapshot(),f.session.snapshot) - - def test_completed_replay_verifies_existing_target_without_source_reads_or_duplicate_owner_create(self): - observed=self.observed();result=self.capture(observed) - shutil.rmtree(self.config['python_root']);shutil.rmtree(self.config['site_packages']) - before=self.fixture.store.snapshot() - with (patch.object(self.runtime,'resolve_configuration',side_effect=AssertionError('No source replay')), - patch.object(self.runtime.owner,'create',side_effect=AssertionError('No duplicate publication'))): - replay=self.capture(observed) - self.assertEqual(replay,result);self.assertEqual(self.fixture.store.snapshot(),before) - self.assertFalse(self.journal.has_pending) - with self.fixture.access.bind(self.fixture.owner.token): - status=self.runtime.status(self.key) - self.assertEqual(status['state'],'captured');self.assertEqual(status['result'],result) - - def test_copy_failure_keeps_durable_intent_and_pending_guard_until_explicit_same_key_retry(self): - observed=self.observed();original=self.runtime.owner.create - def stopped(*args,**kwargs): - receipts=operation_records(self.fixture.store.snapshot()['records']) - self.assertIn(_intent_key(self.key),receipts) - self.assertEqual(self.journal.snapshot()['runtime_effects'][0]['request_key'],self.key) - self.assertFalse(self.fixture.db.in_transaction) - raise WorkbenchError('Injected copy failure.','stale',409) - with patch.object(self.runtime.owner,'create',side_effect=stopped): - with self.assertRaises(WorkbenchError) as caught:self.capture(observed) - self.assertTrue(caught.exception.receipt['committed']) - self.assertEqual(caught.exception.receipt['checkpoint'],self.fixture.store.snapshot()['checkpoint']) - self.assertTrue(self.journal.has_pending) - with self.assertRaises(WorkbenchError):self.execution.assert_quiescent() - with self.fixture.access.bind(self.fixture.owner.token):self.assertEqual(self.runtime.status(self.key)['state'],'intent_recorded') - completed=self.capture(observed) - self.assertEqual(completed['manifest_sha256'],observed['inventory_sha256']) - self.assertFalse(self.journal.has_pending);self.execution.assert_quiescent() - - def test_parent_fsync_unknown_does_not_ack_until_existing_target_verified_and_barrier_passes(self): - import runtime_snapshots - observed=self.observed();sync=runtime_snapshots.sync_directory - def fault(directory): - if Path(directory)==self.runtime.owner.path:raise OSError(errno.EIO,'Injected parent fsync failure') - return sync(directory) - with patch('runtime_snapshots.sync_directory',side_effect=fault): - with self.assertRaises(WorkbenchError) as caught:self.capture(observed) - self.assertEqual(caught.exception.code,'outcome_unknown') - self.assertTrue((self.runtime.owner.path/observed['inventory_sha256']).exists()) - self.assertNotIn(self.key,operation_records(self.fixture.store.snapshot()['records'])) - with patch.object(self.runtime.owner,'create',side_effect=AssertionError('Never copy again')): - with self.assertRaises(WorkbenchError):self.capture(observed) - self.assertTrue(self.journal.has_pending) - shutil.rmtree(self.config['python_root']);shutil.rmtree(self.config['site_packages']) - with patch.object(self.runtime.owner,'create',side_effect=AssertionError('Verify published target')): - result=self.capture(observed) - self.assertEqual(result['manifest_sha256'],observed['inventory_sha256']) - self.assertFalse(self.journal.has_pending) - - def test_intent_sql_commit_failure_never_invokes_filesystem_owner(self): - observed=self.observed();db=self.fixture.db - db.execute('CREATE TABLE deferred_runtime_parent(id INTEGER PRIMARY KEY)') - db.execute('CREATE TABLE deferred_runtime_child(id INTEGER REFERENCES deferred_runtime_parent(id) DEFERRABLE INITIALLY DEFERRED)') - mutate=self.fixture.session.mutate - def fault(operation,target,body,checkpoint,key,invoke,capture,**kwargs): - def invoke_bad(): - value=invoke();db.execute('INSERT INTO deferred_runtime_child VALUES(73)');return value - return mutate(operation,target,body,checkpoint,key,invoke_bad,capture,**kwargs) - with patch.object(self.fixture.session,'mutate',side_effect=fault),patch.object(self.runtime.owner,'create',side_effect=AssertionError('No copy before intent ACK')): - with self.assertRaises(Exception):self.capture(observed) - self.assertFalse((self.runtime.owner.path/observed['inventory_sha256']).exists()) - self.assertFalse(self.journal.has_pending) - self.assertIn(_intent_key(self.key),operation_records(self.fixture.store.snapshot()['records'])) - - def test_changed_key_body_tampered_cache_and_active_work_are_refused_without_effects(self): - observed=self.observed();result=self.capture(observed) - before=self.fixture.store.snapshot() - with self.fixture.access.bind(self.fixture.owner.token): - with patch.object(self.runtime.owner,'create',side_effect=AssertionError('No changed-key effects')): - with self.assertRaises(WorkbenchError) as caught: - self.runtime.capture(dict(profile='other'),observed['inventory_sha256'],self.cp,self.key,reserve_bytes=0) - self.assertEqual(caught.exception.code,'conflict') - self.assertEqual(self.fixture.store.snapshot(),before) - target=self.runtime.owner.path/observed['inventory_sha256']/'packages/torch/__init__.py' - target.chmod(0o600);target.write_bytes(b'changed cache');target.chmod(0o400) - with patch.object(self.runtime.owner,'create',side_effect=AssertionError('Never overwrite corrupt target')): - with self.assertRaises(WorkbenchError):self.capture(observed) - self.assertEqual(self.fixture.store.snapshot(),before) - self.execution._active_attempts.add('a'*32) - with self.assertRaises(WorkbenchError):self.observed() - self.execution._active_attempts.clear() - - def test_current_owner_authority_precedes_inspection_and_receipt_replay(self): - from access import AccessError - observed=self.observed();self.capture(observed) - with patch.object(self.runtime.owner,'get',side_effect=AssertionError('No anonymous cache reads')): - with self.assertRaises(AccessError):self.runtime.capture(self.request,observed['inventory_sha256'],self.cp,self.key,reserve_bytes=0) - with self.assertRaises(AccessError):self.runtime.inspect(self.request) - - def test_final_sql_failure_retains_canonical_manifest_and_reconciles_without_recapture(self): - observed=self.observed();f=self.fixture;db=f.db - db.execute('CREATE TABLE final_runtime_parent(id INTEGER PRIMARY KEY)') - db.execute('CREATE TABLE final_runtime_child(id INTEGER REFERENCES final_runtime_parent(id) DEFERRABLE INITIALLY DEFERRED)') - mutate=f.session.mutate - def fault(operation,target,body,checkpoint,key,invoke,capture,**kwargs): - if operation!='runtime.capture':return mutate(operation,target,body,checkpoint,key,invoke,capture,**kwargs) - def invoke_bad(): - result=invoke();db.execute('INSERT INTO final_runtime_child VALUES(84)');return result - return mutate(operation,target,body,checkpoint,key,invoke_bad,capture,**kwargs) - with patch.object(f.session,'mutate',side_effect=fault): - with self.assertRaises(Exception) as caught:self.capture(observed) - self.assertTrue(caught.exception.receipt['committed']) - self.assertFalse(f.session.available);self.assertTrue(self.journal.has_pending) - snapshot=f.store.snapshot();self.journal.validate_selection(snapshot) - result=operation_records(snapshot['records'])[self.key]['result'] - doc=next(r['document'] for r in snapshot['records'] if r['family']=='runtime_material') - manifest_edge=next(edge for edge in doc['artifacts'] if edge['role']=='runtime_manifest') - self.assertEqual(f.artifacts.status(dict(format='project_artifact_v1',**manifest_edge['blob']))['state'],'verified') - # Explicit current-outcome reconstruction, not an automatic mutation retry. - with f.access.lock,f.session.lock,db.lock:f.session.reconcile_selection(snapshot) - with patch.object(self.runtime.owner,'create',side_effect=AssertionError('Never recapture committed bytes')): - replay=self.capture(observed) - self.assertEqual(replay,result);self.assertFalse(self.journal.has_pending) - self.assertTrue(f.session.available) - - def test_receipt_requires_manifest_declarations_and_exact_durable_intent(self): - result=self.capture(self.observed());records=self.fixture.session.snapshot['records'] - variants=[] - variants.append([r for r in records if r['family']!='project_operation' or r['document']['operation']!='runtime.capture_intent']) - variants.append([r for r in records if r['family']!='project_artifact' or r['id']!=result['manifest_sha256']]) - changed=copy.deepcopy(result);changed['total_bytes']+=1 - with self.assertRaises(WorkbenchError):validate_operation_result('runtime.capture',changed,records) - for candidate in variants: - with self.assertRaises(WorkbenchError):validate_operation_result('runtime.capture',result,candidate) - - def test_sigkill_after_native_publication_retains_exact_private_intent_without_final_ack(self): - import json,subprocess,sys - from project_store import ProjectStore - report=self.fixture.path/'child-capture-report.json' - script=r''' -import json,os,signal,sys -from pathlib import Path -root=Path(sys.argv[2]) -sys.path[:0]=[str(root),str(root/'tests')] -from test_project_runtime import RuntimeCaptureTests -case=RuntimeCaptureTests('test_actual_capture_retains_intent_manifest_and_all_declarations_without_running_binaries') -case.setUp();f=case.fixture;observed=case.observed();create=case.runtime.owner.create -def stop(*args,**kwargs): - value=create(*args,**kwargs) - facts=dict(path=str(f.path),project=str(f.store.path),host_path=str(f.host.path),host_id=f.host.dataset_id, - projection_id=f.db.projection_id,schemas=[f.host.schema,f.db.schema],manifest_sha256=value['manifest_sha256'], - runtime_root=value['root'],checkpoint=f.store.snapshot()['checkpoint'],request_key=case.key) - with open(sys.argv[1],'w') as handle: - json.dump(facts,handle);handle.flush();os.fsync(handle.fileno()) - os.kill(os.getpid(),signal.SIGKILL) -case.runtime.owner.create=stop -case.capture(observed) -''' - root=Path(__file__).resolve().parents[1] - completed=subprocess.run([sys.executable,'-c',script,str(report),str(root)],cwd=root,timeout=20,capture_output=True,text=True) - self.assertEqual(completed.returncode,-9,completed.stderr) - facts=json.loads(report.read_text());self.fixture.schemas.extend(facts['schemas']) - self.addCleanup(shutil.rmtree,facts['path'],True) - with ProjectStore.open(facts['project']) as store: - snapshot=store.snapshot();self.assertEqual(snapshot['checkpoint'],facts['checkpoint']) - receipts=operation_records(snapshot['records']) - self.assertIn(_intent_key(facts['request_key']),receipts);self.assertNotIn(facts['request_key'],receipts) - private=ProjectCustody(facts['host_path'],facts['host_id']) - self.assertEqual([r['projection_id'] for r in private.pending(store)],[facts['projection_id']]) - journal=private.for_projection(store,facts['projection_id']);journal.validate_selection(snapshot) - self.assertEqual(journal.snapshot()['runtime_effects'][0]['manifest_sha256'],facts['manifest_sha256']) - self.assertFalse(any(r['family']=='runtime_material' for r in snapshot['records'])) - raw=(Path(facts['runtime_root'])/'manifest.json').read_bytes() - import hashlib - self.assertEqual(hashlib.sha256(raw).hexdigest(),facts['manifest_sha256']) diff --git a/tests/test_project_runtime_clients.py b/tests/test_project_runtime_clients.py deleted file mode 100644 index e81b06d0..00000000 --- a/tests/test_project_runtime_clients.py +++ /dev/null @@ -1,119 +0,0 @@ -"""Finite runtime transport checks; inventory/copy custody is owned elsewhere.""" -import copy -import unittest -from types import SimpleNamespace -from unittest.mock import Mock - -import agent_api as api -import project_cli -import project_dispatch -from tuldok_client import ProjectFilesClient -from test_project_files_m4_clients import ready,bound,READ,WRITE,PROJECT,ACTOR,CP,NEXT,KEY,STAMP - -ACTIONS=('runtime_sources','runtime_inspect','runtime_capture','runtime_status','runtime_abandon') - - -def inspection(): - return dict(format='project_runtime_inspection_v1',source='configured-cpu',inventory_sha256=CP, - profile='captured_cpu_python_v1',python_version='3.12',file_count=1,total_bytes=1,manifest_bytes=400,free_bytes=1000, - packages=[{'name':'numpy','version':'0.0'},{'name':'torch','version':'0.0'}], - launch=dict(python='python/bin/python3.12',loader='system/lib/ld.so',home='python',stdlib='python/lib/python3.12', - dynload='python/lib/python3.12/lib-dynload',packages='packages',library_dirs=['system/lib']), - files=dict(items=[dict(path='python/bin/python3.12',bytes=1,sha256=CP,mode=0o500,kind='elf')],offset=0,limit=40,total=1)) - - -def summary(complete=False): - value=dict(format='project_runtime_capture_v1' if complete else 'project_runtime_capture_intent_v1', - project_id=PROJECT,manifest_sha256=CP,file_count=1,total_bytes=1,actor_id=ACTOR,observed_at=STAMP,request_key=KEY) - if complete:value['runtime_ref']=dict(kind='runtime',catalog_id=PROJECT,id=NEXT,sha256=NEXT) - return value - - -def client(value): - result=ready(dict(status=200,result=bound(value)),owner=True) - result._selected={**result._selected,**{'project_files.'+action:1 for action in ACTIONS}} - return result - - -class RuntimeClients(unittest.TestCase): - def test_native_bounds_fixed_consumers_and_alias_only_current_configuration(self): - import runtime_snapshots as native - import recipe_process - self.assertEqual((native.MAX_FILES,native.MAX_FILE_BYTES,native.MAX_BYTES,native.MAX_MANIFEST), - (40000,512*1024*1024,2*1024*1024*1024,16*1024*1024)) - op=api.operation('project_files.runtime_inspect')['outputSchema']['oneOf'][0]['properties']['result']['properties']['value']['properties'] - self.assertEqual(op['file_count']['maximum'],native.MAX_FILES) - self.assertEqual(op['total_bytes']['maximum'],native.MAX_BYTES) - self.assertEqual(op['manifest_bytes']['maximum'],native.MAX_MANIFEST) - self.assertEqual(op['files']['properties']['items']['items']['properties']['bytes']['maximum'],native.MAX_FILE_BYTES) - self.assertEqual(op['files']['properties']['items']['items']['properties']['path']['maxLength'],1024) - self.assertTrue(recipe_process._cpu_relative('x'*1024));self.assertFalse(recipe_process._cpu_relative('x'*1025)) - for action in ACTIONS: - self.assertIn('project_files.'+action,api.PROJECT_FILES_M3) - self.assertTrue(callable(getattr(ProjectFilesClient(Mock()),action))) - project_cli.parser().parse_args(['--config','/not-read','file-'+action.replace('_','-'),'--arguments','/not-read']) - for change in ({'source':'/absolute/path'},{'source':'x'*65},{'configuration':{'python_root':'/tmp'}}): - with self.assertRaises(api.AgentAPIError): - api.validate_arguments('project_files.runtime_capture',{**WRITE,'source':'configured-cpu','expected_inventory_sha256':CP,**change}) - self.assertEqual(api.contract('project_files.runtime_capture')['authority'],'owner') - self.assertEqual(api.contract('project_files.runtime_status')['authority'],'agent') - - def test_inventory_nested_page_and_capture_exact_receipt_are_correlated(self): - value=inspection();raw=client(value);sdk=ProjectFilesClient(raw) - sdk.runtime_inspect(**READ,source='configured-cpu') - for change in ({'source':'another'},{'file_count':2}): - raw._request.return_value=dict(status=200,result=bound(dict(value,**change))) - with self.assertRaises(api.AgentAPIError):sdk.runtime_inspect(**READ,source='configured-cpu') - corrupt=copy.deepcopy(value);corrupt['files']['offset']=1 - raw._request.return_value=dict(status=200,result=bound(corrupt)) - with self.assertRaises(api.AgentAPIError):sdk.runtime_inspect(**READ,source='configured-cpu') - raw._request.return_value=dict(status=200,result=bound(summary(True),NEXT)) - sdk.runtime_capture(**WRITE,source='configured-cpu',expected_inventory_sha256=CP,reserve_bytes=0) - for change in ({'request_key':'another-key'},{'manifest_sha256':NEXT},{'project_id':ACTOR}): - raw._request.return_value=dict(status=200,result=bound(dict(summary(True),**change),NEXT)) - with self.assertRaises(api.AgentAPIError):sdk.runtime_capture(**WRITE,source='configured-cpu',expected_inventory_sha256=CP) - - def test_retained_status_never_conflates_capture_with_current_readiness(self): - value=dict(state='captured',intent=summary(),result=summary(True));raw=client(value);sdk=ProjectFilesClient(raw) - self.assertEqual(sdk.runtime_status(**READ,capture_key=KEY)['value'],value) - for change in ({'state':'absent'},{'intent':None},{'result':dict(summary(True),request_key='other-key')}, - {'result':dict(summary(True),file_count=2)},{'local_ready':True}): - raw._request.return_value=dict(status=200,result=bound(dict(value,**change))) - with self.assertRaises(api.AgentAPIError):sdk.runtime_status(**READ,capture_key=KEY) - - def test_abandonment_is_exact_current_intent_and_status_keeps_positive_shape(self): - abandoned=dict(format='project_runtime_capture_abandon_v1',project_id=PROJECT,capture_key=KEY, - input_sha256=NEXT,manifest_sha256=CP,actor_id=ACTOR,reason='Source disappeared; preserve partial science', - observed_checkpoint=CP,observed_at=STAMP) - raw=client(abandoned);sdk=ProjectFilesClient(raw) - sdk.runtime_abandon(**dict(WRITE,request_key='new-abandon-key'),capture_key=KEY,reason=abandoned['reason']) - for change in ({'capture_key':'other-key'},{'reason':'different'},{'project_id':ACTOR}): - raw._request.return_value=dict(status=200,result=bound(dict(abandoned,**change))) - with self.assertRaises(api.AgentAPIError):sdk.runtime_abandon(**dict(WRITE,request_key='new-abandon-key'),capture_key=KEY,reason=abandoned['reason']) - value=dict(state='abandoned',intent=summary(),result=None,abandonment=abandoned) - raw._request.return_value=dict(status=200,result=bound(value));sdk.runtime_status(**READ,capture_key=KEY) - for change in ({'intent':None},{'result':summary(True)},{'abandonment':dict(abandoned,manifest_sha256=NEXT)}): - raw._request.return_value=dict(status=200,result=bound(dict(value,**change))) - with self.assertRaises(api.AgentAPIError):sdk.runtime_status(**READ,capture_key=KEY) - for positive in (dict(state='absent',intent=None,result=None),dict(state='intent_recorded',intent=summary(),result=None),dict(state='captured',intent=summary(),result=summary(True))): - raw._request.return_value=dict(status=200,result=bound(positive));sdk.runtime_status(**READ,capture_key=KEY) - owner=Mock();projection=SimpleNamespace(session=SimpleNamespace(access=SimpleNamespace(require=Mock())),runtime=owner) - project_dispatch.dispatch(projection,'project_files.runtime_abandon',dict(WRITE,request_key='new-abandon-key',capture_key=KEY,reason=abandoned['reason'])) - owner.abandon.assert_called_once_with(KEY,abandoned['reason'],CP,'new-abandon-key') - - def test_dispatch_preserves_alias_only_owner_request_and_bounded_native_projection(self): - runtime=Mock();current=inspection();runtime.inspect.return_value={ - **{field:current[field] for field in ('inventory_sha256','file_count','total_bytes','manifest_bytes','free_bytes')}, - 'manifest':{'profile':current['profile'],'python_version':current['python_version'],'packages':{'numpy':'0.0','torch':'0.0'}, - 'launch':current['launch'],'files':current['files']['items']}} - projection=SimpleNamespace(session=SimpleNamespace(access=SimpleNamespace(require=Mock())),runtime=runtime, - runtime_sources=Mock(return_value={'sources':['configured-cpu']})) - result=project_dispatch.dispatch(projection,'project_files.runtime_inspect',dict(READ,source='configured-cpu')) - self.assertEqual(result,current);runtime.inspect.assert_called_once_with({'source':'configured-cpu'}) - project_dispatch.dispatch(projection,'project_files.runtime_capture',dict(WRITE,source='configured-cpu',expected_inventory_sha256=CP)) - runtime.capture.assert_called_once_with({'source':'configured-cpu'},CP,CP,KEY) - project_dispatch.dispatch(projection,'project_files.runtime_status',dict(READ,capture_key=KEY)) - runtime.status.assert_called_once_with(KEY) - - -if __name__=='__main__':unittest.main() diff --git a/tests/test_project_runtime_http.py b/tests/test_project_runtime_http.py deleted file mode 100644 index eba12786..00000000 --- a/tests/test_project_runtime_http.py +++ /dev/null @@ -1,83 +0,0 @@ -"""Configured current-host runtime capture through real HTTP/PG, without execution.""" -import hashlib -from http.server import ThreadingHTTPServer -import os -import shutil -import threading -import unittest -from unittest.mock import patch - -from app import make_handler -from auth_helpers import ExplicitOwnerFixture -from project_workspace import ProjectWorkspace -import project_workspace -import test_project_files_http as m1 -import test_project_files_m2_http as m2 - - -@unittest.skipUnless(os.environ.get('TULDOK_DATABASE_URL'),'Requires disposable PostgreSQL') -class ProjectRuntimeHTTP(unittest.TestCase): - cleanup_owned=m1.ProjectFilesHTTP.cleanup_owned - select_host=m1.ProjectFilesHTTP.select_host - request=m1.ProjectFilesHTTP.request - state=m1.ProjectFilesHTTP.state - envelope=m1.ProjectFilesHTTP.envelope - action=m1.ProjectFilesHTTP.action - create=m1.ProjectFilesHTTP.create - arguments=m2.ProjectFilesM2HTTP.arguments - transport=m2.ProjectFilesM2HTTP.transport - call=m2.ProjectFilesM2HTTP.call - - def setUp(self): - self.operations=[];m1.ProjectFilesHTTP.setUp(self) - self.enterContext(patch.object(project_workspace,'M3_ENABLED',True)) - python=self.path/'explicit-python';site=self.path/'explicit-packages' - (python/'bin').mkdir(parents=True);(python/'lib/python3.12/lib-dynload').mkdir(parents=True) - shutil.copyfile('/usr/bin/true',python/'bin/python3.12') - (python/'lib/python3.12/lib-dynload/fixture.txt').write_text('Owned inert bytes') - packages=[] - for name in ('torch','numpy'): - (site/name).mkdir(parents=True);(site/name/'__init__.py').write_text('raise AssertionError("Never import this fixture")\n') - info=site/(name+'-0.0.dist-info');info.mkdir();(info/'METADATA').write_text('Name: '+name+'\nVersion: 0.0\n') - (info/'LICENSE').write_text('Owned fixture');packages.extend([name,info.name]) - config=dict(schema_version=1,python_root=str(python),python_version='3.12',site_packages=str(site),packages=packages) - dsn=os.environ['TULDOK_DATABASE_URL'];control=self.path/'configured-control' - workspace=ProjectWorkspace(control,{'fixture':self.external},dsn=dsn,runtime_sources={'inert-fixture':config}) - self.schemas.append((dsn,workspace.db.schema));self.controls.append((dsn,control)) - owner=ExplicitOwnerFixture.bootstrap(workspace) - server=ThreadingHTTPServer(('127.0.0.1',0),make_handler(workspace));thread=threading.Thread(target=server.serve_forever,daemon=True);thread.start() - self.hosts.append((workspace,server,thread));self.workspace,self.owner=workspace,owner - self.origin='http://127.0.0.1:'+str(server.server_port) - - def test_configured_alias_actual_capture_and_cold_historical_status_never_execute(self): - self.create() - with patch('subprocess.Popen',side_effect=AssertionError('Runtime capture executed a child')): - sources=self.call('runtime_sources');self.assertEqual(sources['items'],[{'source':'inert-fixture'}]) - inventory=self.call('runtime_inspect',source='inert-fixture',limit=1) - self.assertEqual(len(inventory['files']['items']),1) - arguments=self.arguments('runtime_capture',source='inert-fixture', - expected_inventory_sha256=inventory['inventory_sha256'],reserve_bytes=0,request_key='actual-runtime-capture') - status,response=self.transport('runtime_capture',arguments);self.assertEqual(status,200,response) - captured=response['value'];self.assertEqual(captured['format'],'project_runtime_capture_v1') - projection=self.workspace._projection - receipts=[r['document'] for r in projection.session.snapshot['records'] if r['family']=='project_operation'] - self.assertTrue(any(r['operation']=='runtime.capture_intent' for r in receipts)) - self.assertTrue(any(r['operation']=='runtime.capture' for r in receipts)) - status,replay=self.transport('runtime_capture',arguments);self.assertEqual(status,200,replay) - self.assertEqual(replay['value'],captured) - # Another workspace sees the capture only after it is saved. - self.action('save') - self.action('close') - self.select_host(self.path/'cold-control',{'fixture':self.external}) - self.action('open',root='fixture',directory='alpha') - historical=self.call('runtime_status',capture_key='actual-runtime-capture') - self.assertEqual(historical['state'],'captured');self.assertEqual(historical['result'],captured) - self.assertEqual(self.call('runtime_sources')['items'],[]) - self.assertIsNone(self.workspace._projection.execution._runs) - self.assertFalse((self.workspace._projection.db.path/'runtime-snapshots'/inventory['inventory_sha256']).exists()) - before=self.workspace._projection.session.snapshot - status,error=self.transport('runtime_inspect',self.arguments('runtime_inspect',source='inert-fixture')) - self.assertEqual(status,409,error);self.assertEqual(self.workspace._projection.session.snapshot,before) - - -if __name__=='__main__':unittest.main() diff --git a/tests/test_project_runtime_recovery_http.py b/tests/test_project_runtime_recovery_http.py deleted file mode 100644 index 6817d148..00000000 --- a/tests/test_project_runtime_recovery_http.py +++ /dev/null @@ -1,242 +0,0 @@ -"""Real HTTP/PG recovery for stopped, nonexecuting runtime copy owners. - -Reuse the authored /usr/bin/true ELF and inert package fixture. No runtime is -installed, imported, probed or executed. Abrupt fixture disposal closes only -known workerless handles; it does not claim successful public Close. -""" -import copy -import hashlib -from http.server import ThreadingHTTPServer -import json -import os -from pathlib import Path -import shutil -import threading -import unittest -from unittest.mock import patch - -import psycopg -from psycopg import sql - -from app import make_handler -from auth_helpers import ExplicitOwnerFixture -from metadata import connection_info -from project_runtime import _intent_key, validate_operation_result -from project_session import operation_documents, operation_records -from project_workspace import ProjectWorkspace -from workbench import WorkbenchError -import test_project_runtime_http as runtime_fixture - - -class RuntimeAbandonmentCodecTests(unittest.TestCase): - def test_completed_capture_for_same_project_and_key_cannot_be_abandoned(self): - project='1'*32;actor='2'*32;key='capture-codec-fixture';manifest='3'*64 - instant='2026-10-22T10:00:00+00:00';input_sha='4'*64 - intent=dict(format='project_runtime_capture_intent_v1',project_id=project, - manifest_sha256=manifest,file_count=1,total_bytes=1,actor_id=actor, - observed_at=instant,request_key=key) - abandoned=dict(format='project_runtime_capture_abandon_v1',project_id=project, - capture_key=key,input_sha256=input_sha,manifest_sha256=manifest, - actor_id=actor,reason='Explicitly stopped copy',observed_checkpoint='5'*64, - observed_at=instant) - def receipt(operation,request_key,result): - return dict(family='project_operation', - id=project+'.'+hashlib.sha256(request_key.encode()).hexdigest(), - document=dict(format='project_operation_v2',project_id=project, - operation=operation,target=manifest,request_key=request_key, - input_sha256=input_sha,result=result)) - records=[receipt('runtime.capture_intent',_intent_key(key),intent)] - operation_documents(records) - self.assertTrue(validate_operation_result('runtime.abandon',abandoned,records)) - complete=dict(intent,format='project_runtime_capture_v1', - runtime_ref=dict(kind='runtime',catalog_id=project,id=manifest,sha256=manifest)) - self.assertTrue(validate_operation_result('runtime.capture',complete)) - records.append(receipt('runtime.capture',key,complete)) - operation_documents(records) - with self.assertRaisesRegex(WorkbenchError,'Completed runtime capture cannot be abandoned'): - validate_operation_result('runtime.abandon',abandoned,records) - # Independent historical project keys cannot contradict this intent. - other=copy.deepcopy(records[-1]);other['document']['project_id']='6'*32 - other['document']['result']['project_id']='6'*32 - other['document']['result']['runtime_ref']['catalog_id']='6'*32 - other['id']='6'*32+'.'+hashlib.sha256(key.encode()).hexdigest() - records[-1]=other - operation_documents(records) - self.assertTrue(validate_operation_result('runtime.abandon',abandoned,records)) - - -@unittest.skipUnless(os.environ.get('TULDOK_DATABASE_URL'),'Requires disposable PostgreSQL') -class ProjectRuntimeRecoveryHTTP(unittest.TestCase): - select_host=runtime_fixture.ProjectRuntimeHTTP.select_host - request=runtime_fixture.ProjectRuntimeHTTP.request - state=runtime_fixture.ProjectRuntimeHTTP.state - envelope=runtime_fixture.ProjectRuntimeHTTP.envelope - action=runtime_fixture.ProjectRuntimeHTTP.action - create=runtime_fixture.ProjectRuntimeHTTP.create - arguments=runtime_fixture.ProjectRuntimeHTTP.arguments - transport=runtime_fixture.ProjectRuntimeHTTP.transport - call=runtime_fixture.ProjectRuntimeHTTP.call - - def setUp(self): - runtime_fixture.ProjectRuntimeHTTP.setUp(self) - self.enterContext(patch('runs.Runs',side_effect=AssertionError('Recovery constructed Runs'))) - self.enterContext(patch('subprocess.Popen',side_effect=AssertionError('Runtime recovery executed a child'))) - self.config=copy.deepcopy(self.workspace._runtime_sources['inert-fixture']) - self.create() - self.inventory=self.call('runtime_inspect',source='inert-fixture',limit=1) - - def cleanup_owned(self): - schemas=set(self.schemas) - for workspace,server,thread in reversed(self.hosts): - server.shutdown();server.server_close();thread.join(3) - if workspace._closed:continue - self.dispose_handles(workspace) - for dsn,control in self.controls: - for manifest in control.rglob('.tuldok.json'): - value=json.loads(manifest.read_bytes()) - schemas.add((dsn,'projection_'+value['projection_id'] if value['version']==2 else 'catalog_'+value['dataset_id'])) - for dsn,schema in schemas: - with psycopg.connect(connection_info(dsn),autocommit=True) as connection: - connection.execute(sql.SQL('DROP SCHEMA IF EXISTS {} CASCADE').format(sql.Identifier(schema))) - - @staticmethod - def dispose_handles(workspace): - # Every tested operation is synchronous and Popen is forbidden. Leave - # journals/canonical files intact while disposing test-owned handles. - for projection in (workspace._projection,workspace._retained_recovery): - if projection is None:continue - if projection.execution._runs is not None:raise AssertionError('Unexpected live Run owner') - if projection.sources is not None:projection.sources.close() - projection.artifacts.close();projection.db.close() - if workspace._store is not None:workspace._store.close() - for _path,descriptor in workspace._roots.values():os.close(descriptor) - workspace._roots.clear();workspace.db.close();workspace._closed=True - - def stop_inert_application(self,workspace): - for candidate,server,thread in self.hosts: - if candidate is workspace: - server.shutdown();server.server_close();thread.join(3) - break - self.dispose_handles(workspace) - - def start_application(self,control,*,sources=None): - dsn=os.environ['TULDOK_DATABASE_URL'] - workspace=ProjectWorkspace(control,{'fixture':self.external},dsn=dsn,runtime_sources=sources) - self.schemas.append((dsn,workspace.db.schema));self.controls.append((dsn,Path(control))) - owner=ExplicitOwnerFixture.bootstrap(workspace) - server=ThreadingHTTPServer(('127.0.0.1',0),make_handler(workspace)) - thread=threading.Thread(target=server.serve_forever,daemon=True);thread.start() - self.hosts.append((workspace,server,thread));self.workspace,self.owner=workspace,owner - self.origin='http://127.0.0.1:'+str(server.server_port) - - def capture_arguments(self,key,*,reserve=0): - return self.arguments('runtime_capture',source='inert-fixture', - expected_inventory_sha256=self.inventory['inventory_sha256'],reserve_bytes=reserve,request_key=key) - - def partial(self,key): - status,error=self.transport('runtime_capture',self.capture_arguments(key,reserve=2**53-1)) - self.assertEqual(status,409,error);self.assertEqual(error['code'],'unavailable') - projection=self.workspace._projection - records=projection.session.snapshot['records'];intent=operation_records(records)[_intent_key(key)] - marker=projection.custody.snapshot()['runtime_effects'][0] - self.assertEqual(marker['input_sha256'],intent['input_sha256']) - self.assertNotIn(key,operation_records(records));self.assertTrue(projection.custody.has_pending) - return projection - - def test_actual_partial_copy_abandon_needs_no_remaining_source_and_retains_binding(self): - key='partial-source-lost';projection=self.partial(key);before=self.state();binding=before['binding'] - status,error=self.transport('close',self.envelope(request_key='close-pending-runtime')) - self.assertEqual(status,409,error);self.assertTrue(projection.custody.has_pending) - recovery=self.state();self.assertEqual(recovery['state'],'recovery_required') - shutil.rmtree(self.config['python_root']);shutil.rmtree(self.config['site_packages']) - with patch.object(projection.runtime,'resolve_configuration',side_effect=AssertionError('Abandon read missing source')): - abandoned=self.call('runtime_abandon',capture_key=key,reason='Explicit owner retains partial copy as abandoned') - self.assertEqual(abandoned['capture_key'],key) - self.assertTrue(validate_operation_result('runtime.abandon',abandoned,projection.session.snapshot['records'])) - self.assertEqual(self.state()['binding'],binding);self.assertEqual(self.state()['state'],'open') - self.assertFalse(projection.custody.has_pending) - self.assertEqual(self.call('runtime_status',capture_key=key)['state'],'abandoned') - self.action('save');self.action('close') - - def test_final_sql_failure_rolls_back_and_an_exact_retry_completes_without_recopying(self): - projection=self.workspace._projection;db=projection.db;key='lost-final-sql' - db.execute('CREATE TABLE runtime_ack_parent(id INTEGER PRIMARY KEY)') - db.execute('CREATE TABLE runtime_ack_child(id INTEGER REFERENCES runtime_ack_parent(id) DEFERRABLE INITIALLY DEFERRED)') - mutate=projection.session.mutate - def fault(operation,target,body,checkpoint,request_key,invoke,capture,**kwargs): - if operation!='runtime.capture':return mutate(operation,target,body,checkpoint,request_key,invoke,capture,**kwargs) - def bad(): - result=invoke();db.execute('INSERT INTO runtime_ack_child VALUES(84)');return result - return mutate(operation,target,body,checkpoint,request_key,bad,capture,**kwargs) - with patch.object(projection.session,'mutate',side_effect=fault): - status,error=self.transport('runtime_capture',self.capture_arguments(key)) - # The final records and projection rows rolled back together; only the - # previously committed intent remains (its receipt is reported). - self.assertEqual(status,409,error);self.assertEqual(error['code'],'rejected') - self.assertTrue(error['receipt']['committed']) - self.assertTrue(projection.session.available) - self.assertEqual(self.state()['state'],'open') - self.assertNotIn(key,projection.session.operations()) - arguments=self.capture_arguments(key) - status,error=self.transport('runtime_capture',dict(arguments,binding='f'*32)) - self.assertEqual(status,409,error);self.assertEqual(error['code'],'stale_project') - with patch.object(projection.runtime.owner,'create',side_effect=AssertionError('Do not recopy the copied runtime')): - status,recovered=self.transport('runtime_capture',arguments) - self.assertEqual(status,200,recovered) - self.assertEqual(self.state()['state'],'open');self.assertTrue(projection.session.available) - self.assertEqual(self.call('runtime_status',capture_key=key)['state'],'captured') - receipts=[r for r in projection.session.operations().values() if r['operation']=='runtime.capture'] - self.assertEqual(len(receipts),1) - self.action('close') - - def test_original_physical_cache_recovery_and_foreign_intent_cannot_regenerate(self): - key='published-before-final';original=self.workspace;projection=original._projection;create=projection.runtime.owner.create - def after_copy(*args,**kwargs): - value=create(*args,**kwargs) - raise WorkbenchError('Injected loss after actual native publication.','outcome_unknown',503) - with patch.object(projection.runtime.owner,'create',side_effect=after_copy): - status,error=self.transport('runtime_capture',self.capture_arguments(key)) - self.assertEqual(status,503,error);physical=projection.db.projection_id - self.assertTrue((projection.runtime.owner.path/self.inventory['inventory_sha256']).is_dir()) - # The committed intent was saved to the folder before it was copied - # (the workspace itself refuses Save while recovery is required). - original._store.save(original._store.summary()['checkpoint']) - shutil.copytree(self.external/'alpha',self.external/'clone',ignore=shutil.ignore_patterns('.tuldok-local')) - self.start_application(self.path/'foreign-control',sources={'inert-fixture':self.config}) - self.action('open',root='fixture',directory='clone') - foreign=self.workspace._projection;before=foreign.session.snapshot - with patch.object(foreign.runtime.owner,'create',side_effect=AssertionError('Imported intent regenerated a runtime')): - status,error=self.transport('runtime_capture',self.capture_arguments(key)) - self.assertEqual(status,409,error);self.assertEqual(error['code'],'unavailable') - self.assertEqual(foreign.session.snapshot,before);self.assertFalse(foreign.custody.has_pending) - self.action('close') - self.stop_inert_application(original) - shutil.rmtree(self.config['python_root']);shutil.rmtree(self.config['site_packages']) - self.start_application(original.path,sources={}) - opened=self.action('open',root='fixture',directory='alpha') - self.assertEqual(opened['state'],'recovery_required');binding=opened['binding'] - self.assertNotEqual(self.workspace._projection.db.projection_id,physical) - with patch('runtime_snapshots.RuntimeSnapshots.create',side_effect=AssertionError('Reopened recovery recopied runtime')): - status,recovered=self.transport('runtime_capture',self.capture_arguments(key)) - self.assertEqual(status,200,recovered);self.assertEqual(recovered['binding'],binding) - self.assertEqual(self.workspace._projection.db.projection_id,physical) - self.assertEqual(self.workspace.custody.pending(self.workspace._store),[]) - self.assertEqual(self.state()['state'],'open');self.assertEqual(self.call('runtime_sources')['items'],[]) - self.action('close') - - def test_original_stopped_copy_can_be_abandoned_after_fresh_open_without_aliases(self): - key='original-partial';projection=self.partial(key);original=self.workspace;physical=projection.db.projection_id - self.stop_inert_application(original) - shutil.rmtree(self.config['python_root']);shutil.rmtree(self.config['site_packages']) - self.start_application(original.path,sources={}) - opened=self.action('open',root='fixture',directory='alpha') - self.assertEqual(opened['state'],'recovery_required');binding=opened['binding'] - abandoned=self.call('runtime_abandon',capture_key=key,reason='Original owner acknowledges stopped partial copy') - self.assertEqual(abandoned['capture_key'],key);self.assertEqual(self.state()['binding'],binding) - self.assertEqual(self.workspace._projection.db.projection_id,physical) - self.assertEqual(self.workspace.custody.pending(self.workspace._store),[]) - self.assertEqual(self.call('runtime_status',capture_key=key)['state'],'abandoned') - self.action('save');self.action('close') - - -if __name__=='__main__':unittest.main() diff --git a/tests/test_project_session.py b/tests/test_project_session.py deleted file mode 100644 index 75ff7795..00000000 --- a/tests/test_project_session.py +++ /dev/null @@ -1,380 +0,0 @@ -"""Shared publication ordering over real PostgreSQL and canonical artifacts. - -Callbacks here deliberately project artifact metadata into a temporary SQL -table. Scientific policy is exercised by the separate domain codec fixtures. -""" -import copy -import hashlib -import json -import os -from pathlib import Path -from types import SimpleNamespace -import tempfile -import unittest -from unittest.mock import patch -import uuid - -import project_fork as fork_module -import psycopg -from psycopg import sql - -from access import Access, AccessError -from auth_helpers import ExplicitOwnerFixture -from metadata import Metadata, connection_info -from project_artifacts import ProjectArtifacts -from project_session import ProjectSession, ProjectSessionError, operation_documents, operation_records -from project_locks import ProjectLock -from project_store import ProjectStore, ProjectStoreError - - -class OperationCodecTests(unittest.TestCase): - def test_operation_lookup_does_not_copy_unrelated_active_envelopes(self): - key='selected-receipt' - document=dict(format='project_operation_v1',operation='fixture.capture',target=None, - request_key=key,input_sha256='a'*64,result={}) - receipt=dict(family='project_operation',id=hashlib.sha256(key.encode()).hexdigest(),document=document) - unrelated=dict(family='project_artifact',id='b'*64, - document=dict(format='project_artifact_v1',sha256='b'*64,bytes=4)) - copied=[];deepcopy=copy.deepcopy - def observe(value): - if value is unrelated:copied.append((value['family'],value['id'])) - return deepcopy(value) - with patch.object(fork_module,'copy',SimpleNamespace(deepcopy=observe)): - actual=operation_records([unrelated,receipt]) - self.assertEqual(actual,{key:document}) - self.assertEqual(copied,[],'Receipt selection must not clone unrelated active records') - actual[key]['result']['changed']=True - self.assertEqual(document['result'],{}) - - def test_namespaced_receipts_preserve_legacy_identity_and_independent_keys(self): - key = 'independent-edit' - document = dict(format='project_operation_v1', operation='fixture.capture', target=None, - request_key=key, input_sha256='a'*64, result={}) - legacy = dict(family='project_operation', id=hashlib.sha256(key.encode()).hexdigest(), document=document) - current = copy.deepcopy(legacy) - current['document'].update(format='project_operation_v2', project_id='b'*32) - current['id'] = 'b'*32 + '.' + legacy['id'] - self.assertEqual(len(operation_documents([legacy,current])), 2) - self.assertEqual(operation_records([current],project_id='b'*32)[key], current['document']) - with self.assertRaises(ProjectSessionError): - operation_records([current],project_id='c'*32) - with self.assertRaises(ProjectSessionError): - operation_records([legacy,current],project_id='b'*32) - future = copy.deepcopy(current); future['document']['format']='project_operation_v3' - with self.assertRaises(ProjectSessionError): - operation_documents([future]) - - def test_fork_cannot_reactivate_unnamespaced_source_receipt_by_editing_archive(self): - from project_fork import _digest, _input - key='legacy-edit' - legacy=dict(family='project_operation',id=hashlib.sha256(key.encode()).hexdigest(),document=dict( - format='project_operation_v1',operation='fixture.capture',target=None,request_key=key, - input_sha256='a'*64,result={})) - source=dict(project_id='b'*32,checkpoint='c'*64) - fork=dict(format='project_fork_v1',source=source,destination_project_id='d'*32, - request_key='fork-request',request_sha256=_digest(_input(source,'fork','Fork','fork-request')), - directory='fork',name='Fork',mapping=[],archived=[dict(family=legacy['family'],id=legacy['id'])], - artifacts=dict(copied=[],missing_regenerable=[])) - records=[legacy,dict(family='project_fork',id='d'*32,document=fork)] - self.assertEqual(operation_records(records,project_id='d'*32),{}) - self.assertEqual(operation_documents(records),[legacy['document']]) - fork['archived']=[] - with self.assertRaisesRegex(ProjectSessionError,'archived'): - operation_records(records,project_id='d'*32) - self.assertEqual(operation_records([legacy])[key],legacy['document']) - - -@unittest.skipUnless(os.environ.get('TULDOK_DATABASE_URL'), 'Requires disposable local PostgreSQL') -class ProjectSessionTests(unittest.TestCase): - def setUp(self): - self.temporary = tempfile.TemporaryDirectory(prefix='tuldok-project-session-') - self.path = Path(self.temporary.name) - self.resources, self.schemas = [], [] - self.addCleanup(self.temporary.cleanup) - self.addCleanup(self.cleanup_owned) - self.store = ProjectStore.create(self.path / 'project', 'Session fixture', 'new-session', 'a' * 64) - self.resources.append(self.store) - self.artifacts = ProjectArtifacts(self.store) - self.resources.append(self.artifacts) - host = self.metadata('host') - self.access = Access(host, host.path) - self.owner = ExplicitOwnerFixture.bootstrap(SimpleNamespace(db=host, access=self.access)) - self.projection = self.metadata('projection', projection=True) - self.create_projection(self.projection) - self.session = self.bind(self.projection) - - def metadata(self, name, *, projection=False): - arguments = dict(dataset_id=self.store.snapshot()['project_id'], projection_id=uuid.uuid4().hex) if projection else {} - value = Metadata(self.path / (name + '-' + uuid.uuid4().hex), **arguments) - self.schemas.append(value.schema) - self.resources.append(value) - return value - - def cleanup_owned(self): - for resource in reversed(self.resources): - resource.close() - with psycopg.connect(connection_info(), autocommit=True) as connection: - for schema in self.schemas: - connection.execute(sql.SQL('DROP SCHEMA IF EXISTS {} CASCADE').format(sql.Identifier(schema))) - - def create_projection(self, db): - db.execute('CREATE TEMP TABLE session_projection (sha256 TEXT PRIMARY KEY, bytes BIGINT NOT NULL)') - - def validate(self, records): - for item in records: - if item['family'] == 'project_artifact': - value = item['document'] - if (set(value) != {'format', 'sha256', 'bytes'} or value['format'] != 'project_artifact_v1' - or value['sha256'] != item['id'] or type(value['bytes']) is not int or value['bytes'] < 0): - raise ProjectSessionError('Invalid fixture artifact declaration.') - elif item['family'] != 'project_operation': - raise ProjectSessionError('Unsupported fixture family.') - - def bind(self, db): - with self.access.bind(self.owner.token): - return ProjectSession(self.store, db, self.access, self.artifacts, validate_records=self.validate) - - def mutation(self, raw=None, *, key=None, expected=None, capture=None, invoke=None): - raw = 'Irreplaceable observation 山'.encode() if raw is None else raw - declaration = dict(format='project_artifact_v1', sha256=hashlib.sha256(raw).hexdigest(), bytes=len(raw)) - key = key or uuid.uuid4().hex - calls = [] - - def project(): - calls.append('invoke') - self.session.db.execute('INSERT INTO session_projection VALUES (%s,%s)', - (declaration['sha256'], declaration['bytes'])) - return dict(sha256=declaration['sha256'], bytes=declaration['bytes']) - - def retain(result, before): - self.assertEqual(before, self.session.snapshot['records']) - self.artifacts.publish_bytes(raw, declaration) - return dict(records=[dict(family='project_artifact', id=declaration['sha256'], document=declaration)], result=result) - - arguments = ('fixture.capture', None, dict(sha256=declaration['sha256']), - expected or self.session.snapshot['checkpoint'], key, invoke or project, capture or retain) - return arguments, declaration, calls - - def call(self, arguments): - with self.access.bind(self.owner.token): - return self.session.mutate(*arguments) - - def test_complete_merge_and_original_result_replay_before_stale_cas(self): - first, declaration, calls = self.mutation() - first_result = self.call(first) - self.assertEqual(calls, ['invoke']) - second, other, _ = self.mutation(b'Other independently authored observation') - self.call(second) - stable = self.store.snapshot() - self.assertEqual(self.call(first), first_result) - self.assertEqual(calls, ['invoke']) - self.assertEqual(self.store.snapshot(), stable) - ids = {(item['family'], item['id']) for item in stable['records']} - self.assertIn(('project_artifact', declaration['sha256']), ids) - self.assertIn(('project_artifact', other['sha256']), ids) - self.assertEqual(self.artifacts.read_blob({key: declaration[key] for key in ('sha256', 'bytes')}), 'Irreplaceable observation 山'.encode()) - - def test_scalar_summary_is_independent_and_tracks_the_bound_publication(self): - before = self.session.summary - arguments, _declaration, _calls = self.mutation() - self.call(arguments) - snapshot = self.session.snapshot - expected = {key: snapshot[key] for key in ('project_id', 'name', 'checkpoint')} - self.assertNotEqual(before['checkpoint'], expected['checkpoint']) - original_copy = copy.deepcopy - def observe(value): - self.assertIsNot(value, self.session._snapshot, 'Summary must not clone the record graph') - return original_copy(value) - with patch('project_session.copy', SimpleNamespace(deepcopy=observe)): - first = self.session.summary - first['name'] = 'Caller mutation' - self.assertEqual(self.session.summary, expected) - self.assertEqual(self.session.snapshot['name'], expected['name']) - - def test_key_conflict_stale_and_current_auth_refuse_before_invoke(self): - first, _declaration, _calls = self.mutation() - self.call(first) - stable = self.store.snapshot() - changed = list(first); changed[2] = dict(sha256='b' * 64) - with self.assertRaises(ProjectSessionError) as error: - self.call(changed) - self.assertEqual(error.exception.code, 'conflict') - stale, _declaration, calls = self.mutation(b'Stale', expected='b' * 64) - with self.assertRaises(ProjectSessionError) as error: - self.call(stale) - self.assertEqual(error.exception.code, 'stale_project') - with self.assertRaises(AccessError): - self.session.mutate(*stale) - self.assertFalse(calls) - self.assertEqual(self.store.snapshot(), stable) - - def test_composed_validation_failure_rolls_back_sql_before_canonical_publication(self): - stable = self.store.snapshot() - - def invalid(result, before): - return dict(records=[dict(family='project_artifact', id='a' * 64, - document=dict(format='project_artifact_v1', sha256='a' * 64, bytes=-1))], result=result) - - arguments, _declaration, _calls = self.mutation(capture=invalid) - with self.assertRaises(ProjectSessionError): - self.call(arguments) - self.assertEqual(self.store.snapshot(), stable) - self.assertEqual(self.projection.execute('SELECT count(*) FROM session_projection').fetchone()[0], 0) - - def test_real_deferred_commit_failure_retains_unique_payload_and_receipt(self): - self.projection.execute("""CREATE FUNCTION pg_temp.reject_session_commit() RETURNS trigger - LANGUAGE plpgsql AS $$ BEGIN RAISE EXCEPTION 'Owned fixture deferred commit refusal'; END $$""") - self.projection.execute('''CREATE CONSTRAINT TRIGGER session_commit_refusal - AFTER INSERT ON session_projection DEFERRABLE INITIALLY DEFERRED - FOR EACH ROW EXECUTE FUNCTION pg_temp.reject_session_commit()''') - arguments, declaration, calls = self.mutation() - with self.assertRaises(ProjectSessionError) as error: - self.call(arguments) - receipt = error.exception.receipt - self.assertEqual(receipt, dict(committed=True, selected=True, project_id=self.store.snapshot()['project_id'], - checkpoint=self.store.snapshot()['checkpoint'], request_key=arguments[4])) - self.assertFalse(self.session.available) - self.assertEqual(self.projection.execute('SELECT count(*) FROM session_projection').fetchone()[0], 0) - self.assertEqual(self.artifacts.read_blob({key: declaration[key] for key in ('sha256', 'bytes')}), 'Irreplaceable observation 山'.encode()) - restored = self.metadata('fresh-projection', projection=True) - self.create_projection(restored) - for item in self.store.snapshot()['records']: - if item['family'] == 'project_artifact': - restored.execute('INSERT INTO session_projection VALUES (%s,%s)', - (item['id'], item['document']['bytes'])) - self.session = self.bind(restored) - result = self.call(arguments) - self.assertEqual(result, dict(sha256=declaration['sha256'], bytes=declaration['bytes'])) - self.assertEqual(calls, ['invoke']) - self.assertEqual(restored.execute('SELECT count(*) FROM session_projection').fetchone()[0], 1) - - def test_nested_transaction_cannot_acknowledge_uncommitted_outer_sql(self): - arguments, _declaration, calls = self.mutation() - stable = self.store.snapshot() - with self.projection.transaction(), self.assertRaises(ProjectSessionError): - self.call(arguments) - self.assertFalse(calls) - self.assertEqual(self.store.snapshot(), stable) - - def test_outer_hook_precedes_commit_and_wake_can_own_a_new_transaction(self): - events = [] - db = self.projection - def before(): - self.assertTrue(db.in_transaction) - second = bool(events) - self.assertEqual(db.execute('SELECT count(*) FROM session_projection').fetchone()[0], 2 if second else 1) - events.append('before-second' if second else 'before') - def outcome(value): - self.assertFalse(db.in_transaction) - events.append(value) - def wake(): - self.assertFalse(db.in_transaction) - with db.transaction(): - db.execute('INSERT INTO session_projection VALUES (%s,%s)', ('b'*64, 2)) - events.append('wake') - db.set_project_hooks(before, outcome) - with db.transaction(): - db.execute('INSERT INTO session_projection VALUES (%s,%s)', ('a'*64, 1)) - with db.transaction(): - db.on_commit(wake) - self.assertEqual(events, []) - self.assertEqual(events, ['before', 'committed', 'before-second', 'committed', 'wake']) - self.assertEqual(db.execute('SELECT count(*) FROM session_projection').fetchone()[0], 2) - - def test_before_commit_rejection_and_savepoint_rollback_never_wake(self): - events = [] - db = self.projection - def reject(): - events.append('before') - raise RuntimeError('Owned canonical capture failed') - db.set_project_hooks(reject, lambda value: events.append(value)) - with self.assertRaisesRegex(RuntimeError, 'canonical capture failed'): - with db.transaction(): - db.execute('INSERT INTO session_projection VALUES (%s,%s)', ('a'*64, 1)) - with self.assertRaisesRegex(RuntimeError, 'savepoint'): - with db.transaction(): - db.on_commit(lambda: events.append('bad-wake')) - raise RuntimeError('savepoint') - db.on_commit(lambda: events.append('wake')) - self.assertEqual(events, ['before', 'rolled_back']) - self.assertEqual(db.execute('SELECT count(*) FROM session_projection').fetchone()[0], 0) - - def test_background_canonical_before_sql_failure_retains_observation_and_fences(self): - raw = b'Unique background measurement' - declaration = dict(format='project_artifact_v1', sha256=hashlib.sha256(raw).hexdigest(), bytes=len(raw)) - self.artifacts.publish_bytes(raw, declaration) - records = [dict(family='project_artifact', id=declaration['sha256'], document=declaration)] - db = self.projection - db.execute('CREATE TEMP TABLE reject_background (id INTEGER, parent INTEGER REFERENCES reject_background(id) DEFERRABLE INITIALLY DEFERRED, UNIQUE(id))') - def before(): - self.session._publish_observation(records, 'background-one', 'c'*64, authorize=lambda: None) - db.set_project_hooks(before, self.session._observation_outcome) - with self.access.bind(self.owner.token), self.assertRaises(psycopg.IntegrityError): - with db.transaction(): - db.execute('INSERT INTO reject_background VALUES (1,2)') - self.assertFalse(self.session.available) - self.assertEqual(self.store.snapshot()['records'], records) - self.assertEqual(self.artifacts.read_blob({k:declaration[k] for k in ('sha256','bytes')}), raw) - self.assertEqual(db.execute('SELECT count(*) FROM reject_background').fetchone()[0], 0) - - def test_foreground_extra_capture_is_durable_without_second_hook_publication(self): - extra = dict(format='project_artifact_v1', sha256=hashlib.sha256(b'extra').hexdigest(), bytes=5) - self.artifacts.publish_bytes(b'extra', extra) - self.session.extra_capture = lambda before: [dict(family='project_artifact', id=extra['sha256'], document=extra)] - flags = [] - self.projection.set_project_hooks(lambda: flags.append(self.session.foreground_publication), - self.session._observation_outcome) - arguments, declaration, _ = self.mutation() - self.call(arguments) - self.assertEqual(flags, [True]) - self.assertFalse(self.session.foreground_publication) - self.assertEqual({i['id'] for i in self.store.snapshot()['records'] if i['family']=='project_artifact'}, - {extra['sha256'], declaration['sha256']}) - - def test_ordered_projection_lock_owns_host_and_session_for_background_entry(self): - db = self.projection - original = db.lock - db.lock = ProjectLock(self.access.lock, self.session.lock, original) - with db.lock: - self.assertGreater(self.access.lock.depth, 0) - self.assertTrue(self.session.lock._is_owned()) - with db.transaction(): - db.execute('INSERT INTO session_projection VALUES (%s,%s)', ('a'*64, 1)) - self.assertEqual(original.depth, 0) - self.assertEqual(self.access.lock.depth, 0) - - def test_background_pointer_fsync_uncertainty_fences_even_when_sql_rolls_back(self): - declaration = dict(format='project_artifact_v1', sha256=hashlib.sha256(b'unknown').hexdigest(), bytes=7) - self.artifacts.publish_bytes(b'unknown', declaration) - records = [dict(family='project_artifact', id=declaration['sha256'], document=declaration)] - previous = self.store.snapshot()['checkpoint'] - original_fsync = os.fsync - def fail_after_replace(fd): - if fd == self.store._meta_fd and json.loads((self.path/'project/.tuldok/project.json').read_bytes())['checkpoint'] != previous: - raise OSError('Owned fixture checkpoint directory fsync failure') - return original_fsync(fd) - self.projection.set_project_hooks( - lambda: self.session._publish_observation(records, 'background-unknown', 'd'*64, authorize=lambda: None), - self.session._observation_outcome) - with self.access.bind(self.owner.token), patch('project_store.os.fsync', fail_after_replace): - with self.assertRaises(ProjectStoreError) as error: - with self.projection.transaction(): - self.projection.execute('INSERT INTO session_projection VALUES (%s,%s)', ('e'*64, 1)) - self.assertEqual(error.exception.code, 'unknown') - self.assertFalse(self.session.available) - self.assertEqual(self.projection.execute('SELECT count(*) FROM session_projection').fetchone()[0], 0) - recovered = self.store.recover_checkpoint() - self.session.reconcile_selection(recovered) - self.assertTrue(self.session.available) - other = dict(format='project_artifact_v1', sha256=hashlib.sha256(b'other').hexdigest(), bytes=5) - unrelated = records + [dict(family='project_artifact', id=other['sha256'], document=other)] - changed = self.store.commit(unrelated, recovered['checkpoint'], 'unrelated-checkout', 'f'*64) - self.session.available = False - with self.assertRaises(ProjectSessionError) as conflict: - self.session.reconcile_selection(changed) - self.assertEqual(conflict.exception.code, 'stale_project') - self.assertFalse(self.session.available) - self.store.close() - reopened = ProjectStore.open(self.path/'project') - self.resources.append(reopened) - self.assertEqual(reopened.snapshot()['records'], unrelated) diff --git a/tests/test_project_session_freshness.py b/tests/test_project_session_freshness.py deleted file mode 100644 index f2ebe64c..00000000 --- a/tests/test_project_session_freshness.py +++ /dev/null @@ -1,139 +0,0 @@ -"""Freshness enforcement over real canonical files, without a SQL projection. - -Only the session's read guard is exercised here. Publication and projection -binding still require the separate real-PostgreSQL session/workspace tests. -""" -import copy -import hashlib -import json -import os -from pathlib import Path -import tempfile -from types import SimpleNamespace -import unittest -from unittest.mock import patch - -from project_session import ProjectSession, ProjectSessionError -from project_store import ProjectStore, ProjectStoreError - - -class ProjectSessionFreshnessTests(unittest.TestCase): - def setUp(self): - temporary = tempfile.TemporaryDirectory(prefix='tuldok-freshness-') - self.addCleanup(temporary.cleanup) - self.root = Path(temporary.name) / 'project' - self.store = ProjectStore.create(self.root, 'Freshness fixture', 'new', 'a' * 64) - self.addCleanup(self.store.close) - self.records = [dict(family='workbench_text', id=name, - document=dict(format='workbench_text_v1', text='Alpha ' + name)) for name in ('one', 'two')] - snapshot = self.store.commit(self.records, self.store.summary()['checkpoint'], 'seed', 'b' * 64) - # Isolate the existing read guard; no fake SQL/projection acceptance. - self.session = object.__new__(ProjectSession) - self.session.store = self.store - self.session._snapshot = copy.deepcopy(snapshot) - self.session.available = True - - def test_freshness_compares_checkpoint_without_rereading_or_copying_records(self): - before = self.store.snapshot() - with patch.object(self.store, '_snapshot', side_effect=AssertionError('Unused full snapshot')), \ - patch.object(self.store, '_record_file', wraps=self.store._record_file) as reads: - self.assertIsNone(self.session.check_current()) - self.assertIsNone(self.session.check_current()) - self.assertEqual(reads.call_count, 0) - self.assertEqual(self.store.snapshot(), before) - - def test_changed_canonical_checkpoint_refuses_both_read_contracts(self): - changed = copy.deepcopy(self.records) - changed[0]['document']['text'] = 'Independently published content' - self.store.commit(changed, self.store.summary()['checkpoint'], 'other', 'c' * 64) - for check in (self.session.check_current, self.session.check, - lambda: self.session.check_records('workbench_text')): - with self.assertRaises(ProjectSessionError) as caught: - check() - self.assertEqual(caught.exception.code, 'stale_project') - - def test_unavailable_projection_refuses_before_reading_the_store(self): - self.session.available = False - with patch.object(self.store, 'summary', side_effect=AssertionError('Unavailable store read')), \ - patch.object(self.store, 'snapshot', side_effect=AssertionError('Unavailable snapshot read')): - for check in (self.session.check_current, self.session.check, - lambda: self.session.check_records('workbench_text')): - with self.assertRaises(ProjectSessionError) as caught: - check() - self.assertEqual(caught.exception.code, 'projection_unavailable') - - def test_same_length_corruption_is_never_served_and_explicit_verification_refuses_it(self): - self.session.check_current() - manifest = json.loads((self.root / '.tuldok/project.json').read_bytes()) - path = self.root / '.tuldok' / manifest['inventory'][0]['path'] - info, original = path.stat(), path.read_bytes() - changed = original.replace(b'Alpha', b'Omega') - self.assertEqual(len(original), len(changed)) - self.assertNotEqual(hashlib.sha256(original).digest(), hashlib.sha256(changed).digest()) - path.chmod(0o600) - path.write_bytes(changed) - os.utime(path, ns=(info.st_atime_ns, info.st_mtime_ns)) - # Reads serve the verified in-memory value, never the corrupt bytes. - self.assertIsNone(self.session.check_current()) - self.assertEqual(self.session.check()['records'][0]['document']['text'], 'Alpha one') - self.assertEqual(self.session.check_records('workbench_text')['records'], self.records) - with self.assertRaises(ProjectStoreError) as caught: - self.store.verify_records() - self.assertEqual(caught.exception.code, 'stale') - - def test_record_consumers_keep_independent_complete_snapshots(self): - current = self.session.check() - current['records'][0]['document']['text'] = 'Caller mutation' - current['name'] = 'Caller renamed copy' - self.assertEqual(self.session.check(), self.store.snapshot()) - self.assertEqual(self.session._snapshot, self.store.snapshot()) - self.assertNotEqual(current, self.session.check()) - - def add_unrelated_record(self): - unrelated = dict(family='project_artifact', id='d' * 64, - document=dict(format='project_artifact_v1', sha256='d' * 64, bytes=4)) - self.session._snapshot = self.store.commit([*self.records, unrelated], - self.store.summary()['checkpoint'], 'unrelated', 'e' * 64) - - def test_selected_records_are_exact_independent_and_do_not_copy_other_families(self): - self.add_unrelated_record() - expected = {key: value for key, value in self.store.snapshot().items() if key != 'records'} - expected['records'] = self.records - copied = [] - deepcopy = copy.deepcopy - def observe(value): - self.assertEqual([row['family'] for row in value], ['workbench_text', 'workbench_text']) - copied.append(value) - return deepcopy(value) - with patch.object(self.store, '_snapshot', side_effect=AssertionError('Unselected graph copy')), \ - patch.object(self.store, '_record_file', wraps=self.store._record_file) as reads, \ - patch('project_session.copy', SimpleNamespace(deepcopy=observe)): - selected = self.session.check_records('workbench_text') - self.assertEqual(selected, expected) - self.assertEqual(reads.call_count, 0, 'Verified immutable records are not re-read per request') - self.assertEqual(len(copied), 1) - selected['records'][0]['document']['text'] = 'Caller mutation' - self.assertEqual(self.session.check_records('workbench_text'), expected) - self.assertEqual(self.session.check_records('project_file')['records'], []) - - def test_explicit_verification_rejects_corruption_in_an_unselected_family(self): - self.add_unrelated_record() - self.session.check_records('workbench_text') - manifest = json.loads((self.root / '.tuldok/project.json').read_bytes()) - entry = next(row for row in manifest['inventory'] if row['family'] == 'project_artifact') - path = self.root / '.tuldok' / entry['path'] - info, original = path.stat(), path.read_bytes() - changed = original.replace(b'"bytes": 4', b'"bytes": 5') - self.assertNotEqual(changed, original) - self.assertEqual(len(changed), len(original)) - path.chmod(0o600) - path.write_bytes(changed) - os.utime(path, ns=(info.st_atime_ns, info.st_mtime_ns)) - self.assertEqual(self.session.check_records('workbench_text')['records'], self.records) - with self.assertRaises(ProjectStoreError) as caught: - self.store.verify_records() - self.assertEqual(caught.exception.code, 'stale') - - -if __name__ == '__main__': - unittest.main() diff --git a/tests/test_project_sources.py b/tests/test_project_sources.py deleted file mode 100644 index 5156e3f0..00000000 --- a/tests/test_project_sources.py +++ /dev/null @@ -1,244 +0,0 @@ -"""Explicit rooted source registration/import using disposable PostgreSQL. - -Fixtures are authored native scientific bytes. No source script, worker, -training runtime, dependency installer, network fetch or laboratory is used. -""" -import copy -import hashlib -import json -import os -from pathlib import Path -import shutil -from types import SimpleNamespace -import tempfile -import unittest -from unittest.mock import patch -import uuid - -from access import Access, AccessError -from metadata import Metadata -from project_artifacts import ProjectArtifacts, validate_declaration -from project_data import ProjectData, decode_data_records, validate_operation_result as data_result -from project_material import ProjectMaterial, decode_records as material_records -from project_material import validate_operation_result as material_result -from project_session import ProjectSession, operation_records -from project_sources import SourceAdapter, validate_operation_result -from project_store import ProjectStore -from projects import Projects -from qualify_scientific_fields import neutral_bundle -from workbench import WorkbenchError - - -@unittest.skipUnless(os.environ.get('TULDOK_DATABASE_URL'),'Requires disposable PostgreSQL') -class SourceAdapterTests(unittest.TestCase): - def setUp(self): - self.tmp=tempfile.TemporaryDirectory(prefix='tuldok-project-source-');self.root=Path(self.tmp.name) - self.addCleanup(self.tmp.cleanup);self.resources=[];self.schemas=[];self.addCleanup(self.cleanup) - self.source_root=self.root/'source';self.source_root.mkdir() - self.raw=neutral_bundle();self.digest=hashlib.sha256(self.raw).hexdigest() - (self.source_root/'field.zip').write_bytes(self.raw) - (self.source_root/'never-run.py').write_text('raise AssertionError("Source registration executed a script")\n') - self.manifest=dict(schema_version=1,id='a'*32,name='Authored source λ', - data=[dict(id='fields',label='Authored native fields',path='field.zip',sha256=self.digest)], - recipes=[],evidence=[],requirements=[]) - self.manifest_raw=(json.dumps(self.manifest,ensure_ascii=False,indent=3)+'\n\n').encode() - (self.source_root/'source.json').write_bytes(self.manifest_raw) - self.host=self.metadata('host') - self.access=Access(self.host,self.host.path) - self.token=self.access.exchange(self.access._local_owner_token())['token'] - self.enterContext(self.access.bind(self.token)) - self.store=ProjectStore.create(self.root/'project','Source fixture','new-source','a'*64) - self.resources.append(self.store) - self.artifacts=ProjectArtifacts(self.store);self.resources.append(self.artifacts) - self.projection,self.adapter=self.project('projection',{'fixture':self.source_root}) - self.session=self.projection.session;self.db=self.session.db - - def metadata(self,name,*,projection=False): - kwargs=dict(dataset_id=self.store.snapshot()['project_id'],projection_id=uuid.uuid4().hex) if projection else {} - db=Metadata(self.root/name,**kwargs);self.resources.append(db);self.schemas.append(db.schema) - return db - - def project(self,name,roots): - db=self.metadata(name,projection=True) - session=ProjectSession(self.store,db,self.access,self.artifacts,validate_records=self.validate) - data=ProjectData(session);data.restore();materials=ProjectMaterial(session);materials.restore() - context=SimpleNamespace(db=db,lock=db.lock,path=db.path,access=materials.owner_access) - sources=Projects(context,roots);self.resources.append(sources) - projection=SimpleNamespace(session=session,db=db,access=self.access,data=data,materials=materials,sources=sources) - return projection,SourceAdapter(projection) - - def cleanup(self): - import psycopg - from psycopg import sql - from metadata import connection_info - for resource in reversed(self.resources):resource.close() - with psycopg.connect(connection_info(),autocommit=True) as db: - for schema in self.schemas:db.execute(sql.SQL('DROP SCHEMA IF EXISTS {} CASCADE').format(sql.Identifier(schema))) - - def validate(self,records): - decode_data_records(records);material_records(records) - for envelope in records: - if envelope['family']=='project_artifact':validate_declaration(envelope['document']) - for receipt in operation_records(records).values(): - operation,result=receipt['operation'],receipt['result'] - if not (validate_operation_result(operation,result,records) or data_result(operation,result,records) or material_result(operation,result,records)): - raise AssertionError('Unexpected fixture operation') - - def register(self,adapter=None,key='register-source',body=None,checkpoint=None): - adapter=adapter or self.adapter - return adapter.register(body or dict(root='fixture',manifest_path='source.json'), - checkpoint or adapter.session.snapshot['checkpoint'],key) - - def import_body(self,registration): - return dict(snapshot={key:registration[key] for key in ('origin_catalog_id','project_id','manifest_sha256')}, - reference_id='fields',expected_sha256=self.digest, - document=dict(name='Authored scientific source',groups=['source-fixture'],rights='Authored fixture; no scientific qualification claim.')) - - def test_registration_retains_original_bytes_attribution_and_one_canonical_operation(self): - with patch('subprocess.Popen',side_effect=AssertionError('No script process')): - result=self.register() - self.assertEqual(result['actor_id'],self.access._context().actor_id) - self.assertTrue(validate_operation_result('source.register',result,self.store.snapshot()['records'])) - snapshot=self.store.snapshot();records=snapshot['records'] - self.assertEqual({r['family'] for r in records},{'project_snapshot','project_artifact','project_operation'}) - retained=next(r for r in records if r['family']=='project_snapshot') - self.assertEqual(retained['document']['value']['manifest_sha256'],hashlib.sha256(self.manifest_raw).hexdigest()) - self.assertEqual(self.artifacts.read_blob(retained['document']['artifacts'][0]['blob']),self.manifest_raw) - self.assertEqual(self.db.execute('SELECT count(*) FROM workspace_projects').fetchone()[0],1) - again=self.register(key='register-again') - self.assertEqual(again['manifest_sha256'],result['manifest_sha256']) - self.assertEqual(next(r for r in self.store.snapshot()['records'] if r['family']=='project_snapshot'),retained) - for forged in (dict(result,name='Well-formed forged snapshot'),dict(result,root='fixture'),dict(result,registered_at='2026-10-22T12:00:00')): - with self.assertRaises(WorkbenchError):validate_operation_result('source.register',forged,records) - self.assertFalse(validate_operation_result('data.import_scientific',{},records)) - - def test_cold_open_has_no_bindings_and_explicit_replay_can_rebind_relocated_root(self): - first=self.register();canonical=self.store.snapshot() - original=next(r for r in canonical['records'] if r['family']=='project_snapshot') - moved=self.root/'relocated';shutil.copytree(self.source_root,moved) - projection,adapter=self.project('cold',{'fixture':moved}) - self.assertEqual(projection.db.execute('SELECT count(*) FROM workspace_projects').fetchone()[0],0) - with self.assertRaises(WorkbenchError):projection.sources.read_snapshot_manifest(first['project_id'],first['manifest_sha256']) - self.assertEqual(self.register(adapter,checkpoint='0'*64),first) - self.assertEqual(self.store.snapshot(),canonical) - current=json.loads(projection.db.execute('SELECT document FROM workspace_projects').fetchone()[0]) - self.assertNotEqual(current['root_identity'],original['document']['value']['root_identity']) - self.assertEqual(next(r for r in self.store.snapshot()['records'] if r['family']=='project_snapshot'),original) - self.assertEqual(projection.sources.read_snapshot_manifest(first['project_id'],first['manifest_sha256'])[1],self.manifest_raw) - - def test_receipt_cannot_bind_absent_current_root_and_agent_is_denied_before_read(self): - first=self.register();canonical=self.store.snapshot() - projection,adapter=self.project('without-roots',{}) - with self.assertRaises(WorkbenchError):self.register(adapter,checkpoint='0'*64) - self.assertEqual(projection.db.execute('SELECT count(*) FROM workspace_projects').fetchone()[0],0) - agent=self.access.issue(dict(label='Source editor',scopes=['inspect','edit'])) - with self.access.bind(agent['token']),patch.object(self.projection.sources,'_read_snapshot_file',side_effect=AssertionError('Owner check must precede I/O')): - with self.assertRaises(AccessError):self.register(checkpoint='0'*64) - self.assertEqual(self.store.snapshot(),canonical) - - def test_changed_manifest_stale_cas_and_key_conflict_never_renew_binding(self): - first=self.register();canonical=self.store.snapshot() - current=self.db.execute('SELECT document FROM workspace_projects').fetchone()[0] - (self.source_root/'other.json').write_bytes(self.manifest_raw) - with self.assertRaises(WorkbenchError) as error:self.register(body=dict(root='fixture',manifest_path='other.json')) - self.assertEqual(error.exception.code,'conflict') - with self.assertRaises(WorkbenchError) as error:self.register(key='stale-source',checkpoint='0'*64) - self.assertEqual(error.exception.code,'stale_project') - changed=dict(self.manifest,name='Changed source');(self.source_root/'source.json').write_text(json.dumps(changed)) - with self.assertRaises(WorkbenchError) as error:self.register(checkpoint='0'*64) - self.assertEqual(error.exception.code,'stale') - self.assertEqual(self.db.execute('SELECT document FROM workspace_projects').fetchone()[0],current) - self.assertEqual(self.store.snapshot(),canonical) - - def test_symlink_and_special_source_reads_refuse_before_any_canonical_import(self): - outside=self.root/'outside.json';outside.write_bytes(self.manifest_raw) - (self.source_root/'linked.json').symlink_to(outside) - with self.assertRaises(WorkbenchError):self.register(body=dict(root='fixture',manifest_path='linked.json')) - first=self.register();canonical=self.store.snapshot();body=self.import_body(first) - (self.source_root/'field.zip').unlink();(self.source_root/'field.zip').symlink_to(outside) - with self.assertRaises(WorkbenchError):self.adapter.import_scientific(body,self.session.snapshot['checkpoint'],'symlink-import') - (self.source_root/'field.zip').unlink();os.mkfifo(self.source_root/'field.zip') - with self.assertRaises(WorkbenchError):self.adapter.import_scientific(body,self.session.snapshot['checkpoint'],'fifo-import') - self.assertEqual(self.store.snapshot(),canonical) - - def test_real_scientific_import_uses_one_data_session_and_cold_source_access_stays_unbound(self): - registration=self.register();body=self.import_body(registration) - with patch.object(self.session,'mutate',wraps=self.session.mutate) as observed: - row=self.adapter.import_scientific(body,self.session.snapshot['checkpoint'],'import-science') - self.assertEqual(observed.call_count,1) - self.assertEqual(observed.call_args.args[0],'data.import_scientific') - self.assertEqual(self.projection.data.workbench.asset(row['id'])[0],self.raw) - canonical=self.store.snapshot() - projection,adapter=self.project('cold-import',{'fixture':self.source_root}) - self.assertEqual(projection.data.get(row['id']),row) - self.assertEqual(projection.data.workbench.asset(row['id'])[0],self.raw) - with self.assertRaises(WorkbenchError):adapter.import_scientific(body,'0'*64,'import-science') - self.assertEqual(self.register(adapter,checkpoint='0'*64),registration) - self.assertEqual(adapter.import_scientific(body,'0'*64,'import-science'),row) - forged=copy.deepcopy(body);forged['snapshot']['origin_catalog_id']='f'*32 - with self.assertRaises(WorkbenchError):adapter.import_scientific(forged,projection.session.snapshot['checkpoint'],'foreign-unbound') - self.assertEqual(self.store.snapshot(),canonical) - - def test_scientific_slice_read_pins_content_and_survives_cold_open_without_source_root(self): - body=self.import_body(self.register()) - row=self.adapter.import_scientific(body,self.session.snapshot['checkpoint'],'slice-source') - before=self.store.snapshot() - expected=self.projection.data.scientific(row['id'],row['content_hash'],frame=1,field='scalar',axis='z',index=2) - self.assertEqual(expected['values'][1][2],1212+2**-45) - projection,_adapter=self.project('cold-slice-without-roots',{}) - self.assertEqual(projection.data.scientific(row['id'],row['content_hash'],frame=1,field='scalar',axis='z',index=2),expected) - for changes in ({'frame':2},{'index':4},{'field':'absent'}): - selection=dict(frame=0,field='scalar',axis='z',index=0) - selection.update(changes) - with self.subTest(changes=changes),self.assertRaises(WorkbenchError): - projection.data.scientific(row['id'],row['content_hash'],**selection) - with self.assertRaises(WorkbenchError) as caught: - projection.data.scientific(row['id'],'0'*64) - self.assertEqual(caught.exception.code,'conflict') - token=self.access.issue(dict(label='Revoked inspection',scopes=['inspect'])) - with self.access.bind(token['token']): - with self.access.bind(self.token): - self.access.revoke(token['identity']['credential_id']) - with self.assertRaises(AccessError): - projection.data.scientific(row['id'],row['content_hash']) - self.assertEqual(self.store.snapshot(),before) - - def test_deferred_sql_failure_retains_snapshot_receipt_and_explicit_cold_replay_rebinds(self): - self.db.execute("CREATE FUNCTION fixture_refuse_source() RETURNS trigger LANGUAGE plpgsql AS $$ BEGIN RAISE EXCEPTION 'controlled source SQL failure' USING ERRCODE='23514'; END; $$") - self.db.execute('CREATE CONSTRAINT TRIGGER fixture_source_failure AFTER INSERT ON workspace_projects DEFERRABLE INITIALLY DEFERRED FOR EACH ROW EXECUTE FUNCTION fixture_refuse_source()') - with self.assertRaises(WorkbenchError) as error:self.register() - self.assertEqual(error.exception.code,'projection_unavailable') - self.assertTrue(error.exception.receipt['committed']) - canonical=self.store.snapshot();original=operation_records(canonical['records'])['register-source']['result'] - self.assertEqual(self.db.execute('SELECT count(*) FROM workspace_projects').fetchone()[0],0) - projection,adapter=self.project('cold-after-sql-failure',{'fixture':self.source_root}) - self.assertEqual(self.register(adapter,checkpoint='0'*64),original) - self.assertEqual(self.store.snapshot(),canonical) - self.assertEqual(projection.sources.read_snapshot_manifest(original['project_id'],original['manifest_sha256'])[1],self.manifest_raw) - - def test_reference_page_measures_only_selected_current_data_without_changing_registration(self): - self.manifest['data'].extend([dict(id='missing',label='Missing source',path='missing.zip',sha256='0'*64), - dict(id='later',label='Unselected source',path='never-read.bin',sha256='1'*64)]) - self.manifest['recipes']=[dict(id='script',label='Never inspect or run',path='never-run.py')] - self.manifest_raw=json.dumps(self.manifest,ensure_ascii=False).encode() - (self.source_root/'source.json').write_bytes(self.manifest_raw) - registration=self.register();snapshot={key:registration[key] for key in ('origin_catalog_id','project_id','manifest_sha256')} - canonical=self.store.snapshot() - with patch.object(self.projection.sources,'_inspect',wraps=self.projection.sources._inspect) as inspected, \ - patch.object(self.projection.sources,'_get',side_effect=AssertionError('No whole-project inspection')), \ - patch('extension_contract.catalog',side_effect=AssertionError('No extension callbacks')), \ - patch('project_activity.activity',side_effect=AssertionError('No activity callbacks')): - page=self.adapter.references(snapshot,offset=0,limit=1) - self.assertEqual((page['total'],page['offset'],page['limit']),(3,0,1)) - self.assertEqual(len(page['items']),1) - self.assertEqual(page['items'][0]['observed_sha256'],self.digest) - self.assertEqual(page['items'][0]['integrity'],'verified') - self.assertEqual(page['items'][0]['label'],'Authored native fields') - missing=self.adapter.references(snapshot,offset=1,limit=1) - self.assertEqual(missing['items'][0]['status'],'missing') - self.assertEqual([call.args[1]['id'] for call in inspected.call_args_list],['fields','missing']) - projection,adapter=self.project('cold-references',{'fixture':self.source_root}) - with patch.object(projection.sources,'_read',side_effect=AssertionError('No I/O before explicit binding')): - with self.assertRaises(WorkbenchError) as error:adapter.references(snapshot,limit=1) - self.assertEqual(error.exception.code,'unavailable') - self.assertEqual(self.store.snapshot(),canonical) diff --git a/tests/test_project_store.py b/tests/test_project_store.py deleted file mode 100644 index ac2fa578..00000000 --- a/tests/test_project_store.py +++ /dev/null @@ -1,758 +0,0 @@ -"""Canonical checkpoint guarantees on real POSIX files and separate processes.""" -import copy -import errno -import hashlib -import json -import math -import os -from pathlib import Path -import shutil -import subprocess -import struct -import sys -import tempfile -import unittest -from unittest.mock import patch - -sys.path.insert(0, str(Path(__file__).resolve().parents[1])) -import project_store as store_module -from project_store import ProjectStore, ProjectStoreError - - -def sha(raw): - return hashlib.sha256(raw).hexdigest() - - -def body(value): - return sha(json.dumps(value, sort_keys=True).encode()) - - -def record(identity='a', text='Original authored text\n漢字'): - return dict(family='workbench_text', id=identity, - document=dict(format='workbench_text_v1', text=text, - history=[dict(note='Unique annotation', reviewed=False)])) - - -def canonical(value): - return (json.dumps(value, ensure_ascii=False, sort_keys=True, indent=2, - allow_nan=False) + '\n').encode() - - -class ProjectStoreTests(unittest.TestCase): - def setUp(self): - self.tmp = tempfile.TemporaryDirectory() - self.addCleanup(self.tmp.cleanup) - self.root = Path(self.tmp.name) / 'project' - self.store = ProjectStore.create(self.root, 'Authored project', 'new', body('new')) - self.addCleanup(lambda: self.store.close()) - - def commit(self, records=None, key='edit'): - records = [record()] if records is None else records - return self.store.commit(records, self.store.snapshot()['checkpoint'], key, body(records)) - - def reopen(self, root=None): - self.store.close() - self.store = ProjectStore.open(root or self.root) - return self.store.snapshot() - - def assert_code(self, code, fn, *args, **kwargs): - with self.assertRaises(ProjectStoreError) as caught: - fn(*args, **kwargs) - self.assertEqual(caught.exception.code, code) - return caught.exception - - def bytes_tree(self): - return {str(p.relative_to(self.root)): p.read_bytes() - for p in self.root.rglob('*') if p.is_file()} - - def manifest(self): - return json.loads((self.root / '.tuldok/project.json').read_text()) - - def write_manifest(self, value): - value.pop('checkpoint', None) - value['checkpoint'] = sha(canonical(value)) - (self.root / '.tuldok/project.json').write_bytes(canonical(value)) - - def test_snapshot_preserves_scalar_types_float_bits_and_owned_nested_values(self): - floats = [-0.0, 0.0, 5e-324, -5e-324, 1.7976931348623157e308, - math.nextafter(1.0, 0.0), math.nextafter(1.0, math.inf)] - value = record() - value['document']['scalars'] = [None, False, True, -2**63, 2**63-1, - 'Unicode 漢字 \U0001f30a\x00', *floats] - expected = self.commit([value]) - first, second = self.store.snapshot(), self.store.snapshot() - self.assertEqual(first, expected) - self.assertEqual(second, expected) - actual = first['records'][0]['document']['scalars'] - self.assertEqual([type(v) for v in actual], - [type(v) for v in value['document']['scalars']]) - self.assertEqual([struct.pack('>d', v) for v in actual[6:]], - [struct.pack('>d', v) for v in floats]) - first['records'][0]['document']['history'][0]['reviewed'] = True - first['records'][0]['document']['scalars'].clear() - self.assertEqual(self.store.snapshot(), second) - - def test_create_commit_save_cold_reopen_and_independent_snapshots(self): - initial = self.store.snapshot() - self.assertEqual(initial['records'], []) - self.assertEqual(len(initial['project_id']), 32) - values = [record('b'), record('a', 'Notes preserve \r\n authored values')] - committed = self.commit(values) - self.assertEqual([r['id'] for r in committed['records']], ['a', 'b']) - before = self.bytes_tree() - self.assertEqual(self.store.save(committed['checkpoint']), committed) - self.assertEqual(before, self.bytes_tree()) - self.assertEqual(self.reopen(), committed) - values[0]['document']['text'] = 'Unchecked caller mutation' - committed['records'][0]['document']['text'] = 'Unchecked returned mutation' - self.assertEqual(self.store.snapshot()['records'][0]['document']['text'], 'Notes preserve \r\n authored values') - - def test_streamed_records_digest_equals_complete_canonical_encoding(self): - rows = [record('a'), record('b', 'Line\none "quoted" \\ ☃ 
'), - dict(family='workbench_text', id='c', document=dict(format='workbench_text_v1', text='', - history=[], nested={'z': [1, 1.0, -0.0, None, True, {}], 'ü': {'k\n': []}}))] - expected = store_module._sha(store_module._encode(rows)) - streamed = store_module._records_digest( - (row['family'], row['id'], store_module._encode(row['document'])) for row in rows) - self.assertEqual(streamed, expected) - self.assertEqual(store_module._records_digest([]), store_module._sha(store_module._encode([]))) - - def test_commit_reuses_unchanged_revisions_without_reencoding_them(self): - values = [record(str(index), 'Retained authored note %d' % index) for index in range(6)] - self.commit(values, key='initial-six') - changed = copy.deepcopy(values) - changed[2]['document']['text'] = 'Only this revision changes' - encode = store_module._encode - with patch.object(store_module, '_encode', wraps=encode) as encodes: - committed = self.commit(changed, key='change-one') - documents = [call.args[0] for call in encodes.call_args_list - if type(call.args[0]) is dict and call.args[0].get('format') == 'workbench_text_v1'] - self.assertEqual(documents, [changed[2]['document']]) - self.assertEqual(self.reopen(), committed) - - def test_python_equal_but_differently_typed_values_are_new_revisions(self): - for before, after in ((1, 1.0), (0.0, -0.0), (True, 1), (1.0, 1)): - with self.subTest(before=before, after=after): - original = dict(family='workbench_text', id='typed', document=dict(format='workbench_text_v1', value=before)) - self.commit([original], key=f'typed-{before!r}-{after!r}-a'.replace('.', '_').replace('-', '_')) - updated = copy.deepcopy(original) - updated['document']['value'] = after - self.commit([updated], key=f'typed-{before!r}-{after!r}-b'.replace('.', '_').replace('-', '_')) - value = self.reopen()['records'][0]['document']['value'] - self.assertIs(type(value), type(after)) - self.assertEqual(repr(value), repr(after)) - - def test_appending_one_record_does_not_rewrite_saved_immutable_revisions(self): - values = [record(str(index), 'Retained authored note %d' % index) for index in range(8)] - self.commit(values, key='initial-inventory') - writer = store_module._write_file - with patch.object(store_module, '_write_file', wraps=writer) as writes: - committed = self.commit([*values, record('new')], key='append-one') - record_writes = [call for call in writes.call_args_list if call.args[1].startswith('.record-')] - self.assertEqual(len(record_writes), 1, - 'Appending one record must not write disposable copies of every saved immutable revision') - self.assertEqual(self.reopen(), committed) - - def test_summary_reads_every_current_record_without_cloning_the_record_graph(self): - committed = self.commit([record('a'), record('b')], key='summary-fixture') - expected = {key: committed[key] for key in ('project_id', 'name', 'checkpoint')} - with patch.object(self.store, '_snapshot', side_effect=AssertionError('Unused record graph copy')), \ - patch.object(self.store, '_record_file', wraps=self.store._record_file) as reads: - first = self.store.summary() - first['name'] = 'Caller mutation' - second = self.store.summary() - self.assertEqual(second, expected) - self.assertEqual(reads.call_count, 0, - 'Freshness compares checkpoint bytes; verified immutable revisions are not re-read') - self.assertEqual(self.store.snapshot(), committed) - - def test_repeated_snapshot_and_root_reads_recheck_bytes_without_redecoding_identical_records(self): - rows=[record('a'),record('b','Exact second note\n')] - self.commit(rows,key='repeat-read-fixture') - expected=self.store.snapshot() - canonical_documents={canonical(row['document']) for row in rows} - with patch.object(store_module,'_decode',wraps=store_module._decode) as decode, \ - patch.object(self.store,'_record_file',wraps=self.store._record_file) as read, \ - patch.object(self.store,'_snapshot',wraps=self.store._snapshot) as snapshot: - self.assertEqual(self.store.snapshot(),expected) - with self.store.root_directory(verify_after=True) as descriptor: - self.assertTrue(os.fstat(descriptor).st_ino) - self.assertEqual(self.store.snapshot(),expected) - self.assertEqual(read.call_count,0,'Byte-identical checkpoints reuse the verified immutable records') - self.assertEqual(snapshot.call_count,2,'Root borrowing must not clone an unused public snapshot') - decoded=[call for call in decode.call_args_list if call.args[0] in canonical_documents] - self.assertEqual(len(decoded),0,'Byte-identical canonical records need no repeat decoding within one Store') - - def test_verified_decode_cache_still_rejects_same_length_corruption_with_restored_mtime(self): - self.commit([record('note','Alpha\n')],key='cache-corruption-fixture') - self.store.snapshot() - entry=self.manifest()['inventory'][0] - path=self.root/'.tuldok'/entry['path'];info=path.stat();raw=path.read_bytes() - changed=raw.replace(b'Alpha',b'Omega') - self.assertEqual(len(changed),len(raw));self.assertNotEqual(changed,raw) - path.chmod(0o600);path.write_bytes(changed) - os.utime(path,ns=(info.st_atime_ns,info.st_mtime_ns)) - # Ordinary reads keep serving the already verified value, never the - # corrupt bytes; explicit verification, Save and reopen refuse them. - self.assertEqual(self.store.snapshot()['records'][0]['document']['text'],'Alpha\n') - self.assert_code('stale',self.store.verify_records) - self.assert_code('stale',self.store.save,self.store.summary()['checkpoint']) - self.store.close() - self.assert_code('invalid',ProjectStore.open,self.root) - - def test_reusing_an_unreferenced_revision_still_checks_bytes_and_syncs_it(self): - first, second = record('first'), record('second') - self.commit([first], key='retain-first') - self.commit([second], key='retain-second') - writer, sync = store_module._write_file, store_module._sync_file - with patch.object(store_module, '_write_file', wraps=writer) as writes: - with patch.object(store_module, '_sync_file', wraps=sync) as syncs: - committed = self.commit([first, second], key='reuse-first') - self.assertFalse(any(call.args[1].startswith('.record-') for call in writes.call_args_list)) - # Only the newly referenced unreferenced revision is checked and synced; - # the unchanged current revision is reused without rewrite or re-sync. - self.assertEqual(syncs.call_count, 1) - self.assertEqual(self.reopen(), committed) - - def test_reusing_a_corrupt_unreferenced_revision_never_publishes_it(self): - first = record('first') - self.commit([first], key='retain-first') - entry = self.manifest()['inventory'][0] - self.commit([], key='exclude-first') - before = self.store.snapshot() - path = self.root / '.tuldok' / entry['path'] - path.unlink() - path.write_bytes(b'{"corrupt":"unreferenced revision"}\n') - self.assert_code('invalid', self.commit, [first], key='reuse-corrupt') - self.assertEqual(self.reopen(), before) - - def test_existing_revision_sync_failure_keeps_the_previous_checkpoint(self): - self.commit([record()], key='initial') - before = self.store.snapshot() - with patch.object(store_module, '_sync_file', side_effect=OSError(errno.EIO, 'existing revision sync failed')): - self.assert_code('unavailable', self.commit, [record(text='Changed revision')], key='new-revision-sync-error') - self.assertEqual(self.reopen(), before) - - def test_fresh_copy_and_moved_folder_keep_identity_and_values(self): - committed = self.commit() - self.store.close() - copied = Path(self.tmp.name) / 'clone' - shutil.copytree(self.root, copied) - moved = Path(self.tmp.name) / 'moved' - self.root.rename(moved) - with ProjectStore.open(copied) as other: - self.assertEqual(other.snapshot(), committed) - self.assertEqual(other.save(committed['checkpoint']), committed) - self.assertEqual(self.reopen(moved), committed) - - def test_new_never_overwrites_existing_directory_or_file(self): - before = self.bytes_tree() - self.assert_code('invalid', ProjectStore.open, 42) - self.assert_code('invalid', ProjectStore.create, 42, 'Other', 'new', body('new')) - self.assert_code('conflict', ProjectStore.create, self.root, 'Other', 'new', body('new')) - self.assertEqual(self.bytes_tree(), before) - destination = Path(self.tmp.name) / 'existing' - destination.write_bytes(b'Untouched') - self.assert_code('conflict', ProjectStore.create, destination, 'Other', 'new', body('new')) - self.assertEqual(destination.read_bytes(), b'Untouched') - - def test_replay_reconciles_before_stale_check_and_binds_body_and_values(self): - old = self.store.snapshot()['checkpoint'] - records = [record()] - committed = self.commit(records) - before = self.bytes_tree() - self.assertEqual(self.store.commit(records, old, 'edit', body(records)), committed) - self.assertEqual(self.store.reconcile('edit', body(records)), committed) - self.assertIsNone(self.store.reconcile('not-submitted', body(None))) - self.assert_code('conflict', self.store.reconcile, 'edit', body('changed')) - self.assert_code('conflict', self.store.commit, [record(text='changed')], old, 'edit', body(records)) - self.assertEqual(self.bytes_tree(), before) - self.reopen() - self.assertEqual(self.store.reconcile('edit', body(records)), committed) - self.assertEqual(self.store.reconcile('new', body('new')), committed) - - def test_colon_request_keys_roundtrip_reconcile_and_reject_changed_body(self): - before = self.store.snapshot()['checkpoint'] - records = [record()] - committed = self.store.commit(records, before, 'edit:fixture', body(records)) - canonical = self.bytes_tree() - self.assertEqual(self.store.commit(records, before, 'edit:fixture', body(records)), committed) - self.assertEqual(self.reopen(), committed) - self.assertEqual(self.store.reconcile('edit:fixture', body(records)), committed) - self.assert_code('conflict', self.store.reconcile, 'edit:fixture', body('different input')) - self.assert_code('conflict', self.store.commit, records, before, 'edit:fixture', body('different input')) - self.assertEqual(self.bytes_tree(), canonical) - - def test_stale_checkpoint_cannot_commit_or_save(self): - old = self.store.snapshot()['checkpoint'] - self.commit() - before = self.bytes_tree() - self.assert_code('stale', self.store.commit, [record(text='lost update')], old, 'late', body('late')) - self.assert_code('stale', self.store.save, old) - self.assertEqual(before, self.bytes_tree()) - - def test_second_process_writer_is_nonblocking_and_can_open_after_close(self): - code = """ -import sys -from project_store import ProjectStore, ProjectStoreError -try: - with ProjectStore.open(sys.argv[1]) as store: - print(store.snapshot()['project_id']) -except ProjectStoreError as exc: - print(exc.code) - sys.exit(7) -""" - child = subprocess.run([sys.executable, '-c', code, str(self.root)], - cwd=Path(store_module.__file__).parent, capture_output=True, text=True, timeout=10) - self.assertEqual((child.returncode, child.stdout.strip()), (7, 'busy'), child.stderr) - self.store.close() - child = subprocess.run([sys.executable, '-c', code, str(self.root)], - cwd=Path(store_module.__file__).parent, capture_output=True, text=True, timeout=10) - self.assertEqual(child.returncode, 0, child.stderr) - self.assertEqual(len(child.stdout.strip()), 32) - - def test_same_process_duplicate_and_symlink_root_do_not_evade_writer_lock(self): - self.assert_code('busy', ProjectStore.open, self.root) - alias = Path(self.tmp.name) / 'alias' - alias.symlink_to(self.root, target_is_directory=True) - self.assert_code('invalid', ProjectStore.open, alias) - self.assert_code('invalid', ProjectStore.create, alias / 'new', 'Other', 'new', body('new')) - self.assert_code('invalid', ProjectStore.open, self.root / '..' / 'project') - - def test_replaced_physical_root_or_metadata_directory_is_rejected(self): - displaced = self.root.with_name('displaced') - self.root.rename(displaced) - self.root.mkdir() - self.assert_code('stale', self.store.snapshot) - self.assert_code('stale', self.store.summary) - self.root.rmdir() - displaced.rename(self.root) - meta = self.root / '.tuldok' - meta.rename(self.root / '.old-tuldok') - meta.mkdir() - self.assert_code('stale', self.store.snapshot) - self.assert_code('stale', self.store.summary) - - def test_changed_checkpoint_is_rejected_before_mutation(self): - initial = self.store.snapshot() - manifest = self.manifest() - manifest['name'] = 'Changed outside open writer' - self.write_manifest(manifest) - self.assert_code('stale', self.store.snapshot) - self.assert_code('stale', self.store.commit, [record()], initial['checkpoint'], 'edit', body('edit')) - self.assertEqual(self.reopen()['name'], 'Changed outside open writer') - - def test_missing_or_changed_canonical_record_never_becomes_empty_project(self): - self.commit() - entry = self.manifest()['inventory'][0] - path = self.root / '.tuldok' / entry['path'] - raw = path.read_bytes() - path.write_bytes(raw.replace(b'Unique', b'Broken')) - self.assertEqual(self.store.snapshot()['records'][0]['document']['history'][0]['note'], 'Unique annotation') - self.assert_code('stale', self.store.verify_records) - self.store.close() - self.assert_code('invalid', ProjectStore.open, self.root) - path.unlink() - self.assert_code('unavailable', ProjectStore.open, self.root) - - def test_symlinks_specials_and_hardlink_aliases_are_rejected(self): - self.commit() - path = self.root / '.tuldok' / self.manifest()['inventory'][0]['path'] - raw = path.read_bytes() - other = Path(self.tmp.name) / 'other.json' - other.write_bytes(raw) - self.store.close() - path.unlink() - path.symlink_to(other) - self.assert_code('invalid', ProjectStore.open, self.root) - path.unlink() - os.mkfifo(path) - self.assert_code('invalid', ProjectStore.open, self.root) - path.unlink() - os.link(other, path) - self.assert_code('invalid', ProjectStore.open, self.root) - path.unlink() - path.write_bytes(raw) - metadata = self.root / '.tuldok/project.json' - os.link(metadata, Path(self.tmp.name) / 'checkpoint-alias') - self.assert_code('invalid', ProjectStore.open, self.root) - - def test_inventory_cannot_replace_root_path_or_namespace(self): - self.commit() - self.store.close() - original = self.manifest() - for field, value in [('path', '../escape.json'), ('path', '/tmp/escape.json'), - ('namespace', 'a' * 32), ('extra', 'unrecognized')]: - with self.subTest(field=field, value=value): - manifest = copy.deepcopy(original) - manifest['inventory'][0][field] = value - self.write_manifest(manifest) - self.assert_code('invalid', ProjectStore.open, self.root) - - def test_malformed_duplicate_nonfinite_oversized_and_future_input(self): - self.store.close() - path = self.root / '.tuldok/project.json' - original = path.read_bytes() - for raw in [b'{"format":"x","format":"y"}', b'\xff', b'{', - b'{"x": NaN}', b'{"x":' + b'1' * 5000 + b'}', b'[]\n', original.replace(b' ', b' ')]: - with self.subTest(raw=raw[:30]): - path.write_bytes(raw) - self.assert_code('invalid', ProjectStore.open, self.root) - manifest = json.loads(original) - manifest['format'] = 'tuldok_project_v2' - path.write_bytes(canonical(manifest)) - self.assert_code('unsupported', ProjectStore.open, self.root) - path.write_bytes(original) - with patch.object(store_module, 'MAX_MANIFEST_BYTES', 20): - self.assert_code('invalid', ProjectStore.open, self.root) - - def test_closed_document_envelopes_and_supported_family_format(self): - checkpoint = self.store.snapshot()['checkpoint'] - invalid = [dict(record(), extra='x'), dict(record(), family='../escape'), - dict(record(), id='/absolute'), dict(record(), document=[]), - dict(record(), document={'format': 'workbench_text_v1', 'x': float('inf')}), - dict(record(), document={'format': 'workbench_text_v1', 'x': '\ud800'}), - dict(record(), document={'format': 'workbench_text_v1', 'x': 2 ** 63})] - for value in invalid: - with self.subTest(value=repr(value)): - self.assert_code('invalid', self.store.commit, [value], checkpoint, 'bad', body('bad')) - - def test_portfolio_above_256_MiB_commits_and_cold_reopens(self): - # Each document fits the 40 MiB owner bound. Aggregate project metadata - # must also support scientific catalogs larger than the old 256 MiB. - text = 'p' * (30 * 1024 * 1024) - values = [record(str(index), text) for index in range(9)] - committed = self.store.commit(values, self.store.snapshot()['checkpoint'], - 'large-portfolio', body('large-portfolio')) - self.assertGreater(sum(row['bytes'] for row in self.manifest()['inventory']), - 256 * 1024 * 1024) - self.assertEqual(self.reopen(), committed) - self.assertEqual(self.store.snapshot()['records'], values) - - def test_aggregate_byte_bound_rejects_commit_and_cold_open(self): - values = [record('a'), record('b')] - total = sum(len(canonical(value['document'])) for value in values) - before = self.bytes_tree() - checkpoint = self.store.snapshot()['checkpoint'] - with patch.object(store_module, 'MAX_TOTAL_BYTES', total - 1): - self.assert_code('invalid', self.store.commit, values, checkpoint, - 'over-budget', body('over-budget')) - self.assertEqual(self.bytes_tree(), before) - committed = self.commit(values) - self.store.close() - with patch.object(store_module, 'MAX_TOTAL_BYTES', total - 1): - self.assert_code('invalid', ProjectStore.open, self.root) - self.assertEqual(self.reopen(), committed) - for value in [dict(record(), family='access_credentials'), - dict(record(), document={'format': 'workbench_text_v2'}), - dict(record(), document={'format': 'unknown_v1'})]: - self.assert_code('unsupported', self.store.commit, [value], checkpoint, 'bad', body('bad')) - self.assert_code('invalid', self.store.commit, [record(), record()], checkpoint, 'bad', body('bad')) - - def test_every_unicode_scalar_is_valid_and_every_surrogate_is_refused(self): - # Unicode scalar values exclude exactly D800..DFFF. Check the complete - # finite domain rather than a copied sample of the implementation. - for value in range(0x110000): - text = chr(value) - if 0xD800 <= value <= 0xDFFF: - for content in (text, 'ASCII prefix' + text, 'λ' + text + 'suffix'): - error = self.assert_code('invalid', store_module._json_value, content) - self.assertEqual(str(error), 'Project JSON contains an invalid Unicode surrogate.') - else: - store_module._json_value(text) - - def test_unicode_validation_preserves_exact_canonical_bytes(self): - for value in ('ASCII' * 20000, '\x00\n\r\t\\"', 'é e\u0301 漢字 😀', - '\ud7ff\ue000\ufffe\uffff\U0010ffff'): - document = {'key': [value, {'λ': value}]} - self.assertEqual(store_module._encode(document), canonical(document)) - - def test_large_checkpoint_index_publishes_and_cold_opens(self): - # The migrated lab's small record declarations produced a 17.99 MB - # index, even though individual records and their total were in bounds. - # Valid receipts exercise the same index publication/read boundary - # without tens of thousands of fsyncs in a focused regression fixture. - manifest = self.manifest() - manifest['receipts'].extend( - dict(request_key='operation.' + str(index).zfill(100), - request_sha256=body(index), records_sha256=sha(canonical([]))) - for index in range(52_000)) - manifest.pop('checkpoint') - manifest['checkpoint'] = sha(canonical(manifest)) - self.assertGreater(len(canonical(manifest)), 16 * 1024 * 1024) - self.store._publish(manifest) - reopened = self.reopen() - self.assertEqual(reopened['checkpoint'], manifest['checkpoint']) - self.assertEqual(reopened['records'], []) - self.assertEqual(self.manifest()['receipts'], manifest['receipts']) - - def test_oversized_checkpoint_refuses_before_staging_record_files(self): - before = self.bytes_tree() - # The existing checkpoint fits, but a new record's index would not. - maximum = len((self.root / '.tuldok/project.json').read_bytes()) + 10 - with patch.object(store_module, 'MAX_MANIFEST_BYTES', maximum): - error = self.assert_code('invalid', self.commit) - self.assertEqual(str(error), 'Project checkpoint exceeds its byte limit.') - self.assertEqual(self.bytes_tree(), before) - - def test_future_record_format_rejected_on_open(self): - self.commit() - self.store.close() - manifest = self.manifest() - manifest['inventory'][0]['format'] = 'workbench_text_v2' - self.write_manifest(manifest) - self.assert_code('unsupported', ProjectStore.open, self.root) - - def test_unreferenced_records_and_script_sentinels_are_inert(self): - script = self.root / 'execute.py' - script.write_text('raise RuntimeError("Never execute on Open or Save")\n') - orphan = self.root / '.tuldok/records/orphan.json' - orphan.write_bytes(b'Malformed orphan does not confer authority') - with patch.object(subprocess, 'Popen', side_effect=AssertionError('No execution')): - before = self.bytes_tree() - snapshot = self.reopen() - self.store.save(snapshot['checkpoint']) - self.assertEqual(before, self.bytes_tree()) - - def test_prior_immutable_revisions_are_retained_after_replace_and_delete(self): - self.commit() - first = self.root / '.tuldok' / self.manifest()['inventory'][0]['path'] - raw = first.read_bytes() - self.commit([record(text='Changed note')], 'change') - self.commit([], 'delete') - self.assertEqual(first.read_bytes(), raw) - self.assertEqual(self.reopen()['records'], []) - - def test_write_failure_keeps_old_checkpoint_and_reopen(self): - old = self.store.snapshot() - with patch.object(store_module.os, 'write', side_effect=OSError(errno.ENOSPC, 'disk full')): - self.assert_code('unavailable', self.commit) - self.assertEqual(self.reopen(), old) - self.assertIsNone(self.store.reconcile('edit', body([record()]))) - self.assertEqual(self.commit()['records'], [record()], 'An incomplete staging object must not poison retries') - - def test_checkpoint_file_sync_failure_leaves_old_checkpoint(self): - old = self.store.snapshot() - original = store_module._write_file - def fail_checkpoint(directory, name, raw): - if name.startswith('.checkpoint-'): - raise OSError(errno.EIO, 'checkpoint sync failure') - return original(directory, name, raw) - with patch.object(store_module, '_write_file', side_effect=fail_checkpoint): - self.assert_code('unavailable', self.commit) - self.assertEqual(self.reopen(), old) - self.assertTrue(list((self.root / '.tuldok/records').rglob('*.json'))) - self.assertEqual(self.commit()['records'], [record()]) - - def test_failure_after_checkpoint_replacement_is_unknown_then_reconciled(self): - original = store_module.os.fsync - replace = store_module.os.replace - published = False - def after_replace(*args, **kwargs): - nonlocal published - replace(*args, **kwargs) - published = True - def fail_meta(fd): - if published and fd == self.store._meta_fd: - raise OSError(errno.EIO, 'directory sync failure') - return original(fd) - with patch.object(store_module.os, 'fsync', side_effect=fail_meta), patch.object( - store_module.os, 'replace', side_effect=after_replace): - self.assert_code('unknown', self.commit) - self.assert_code('unknown', self.store.snapshot) - reopened = self.reopen() - self.assertEqual(reopened['records'], [record()]) - self.assertEqual(self.store.reconcile('edit', body([record()])), reopened) - - def test_new_final_destination_is_absent_until_complete_atomic_publication(self): - target = Path(self.tmp.name) / 'atomic-new' - publish = store_module._publish_directory - # A staged directory remains physically locked, so inspect bytes directly. - def inspect_bytes(parent_fd, staging, destination): - self.assertFalse(target.exists()) - manifest = json.loads((Path(self.tmp.name) / staging / '.tuldok/project.json').read_text()) - self.assertEqual(manifest['format'], 'tuldok_project_v1') - self.assertEqual(manifest['receipts'][0]['request_key'], 'atomic') - publish(parent_fd, staging, destination) - with patch.object(store_module, '_publish_directory', side_effect=inspect_bytes): - with ProjectStore.create(target, 'Atomic New', 'atomic', body('atomic')) as created: - self.assertEqual(created.path, target) - self.assertEqual(created.snapshot()['records'], []) - self.assertTrue(target.is_dir()) - - def test_new_gitignore_is_durable_before_publication_and_survives_cold_copy(self): - expected = b'/artifacts/\n/.tuldok-local/\n/.venv/\n/__pycache__/\n/PGDATA/\n/output/\n' - target = Path(self.tmp.name) / 'ignored-new' - publish = store_module._publish_directory - fsync = store_module.os.fsync - synced = set() - def observe_sync(fd): - fsync(fd) - info = os.fstat(fd) - synced.add((info.st_dev, info.st_ino)) - def inspect_before_publish(parent_fd, staging, destination): - staged = Path(self.tmp.name) / staging - self.assertFalse(target.exists()) - self.assertEqual((staged / '.gitignore').read_bytes(), expected) - for path in (staged / '.gitignore', staged): - info = path.stat() - self.assertIn((info.st_dev, info.st_ino), synced) - publish(parent_fd, staging, destination) - self.assertEqual((target / '.gitignore').read_bytes(), expected) - with patch.object(store_module.os, 'fsync', side_effect=observe_sync), patch.object( - store_module, '_publish_directory', side_effect=inspect_before_publish): - with ProjectStore.create(target, 'Ignore defaults', 'ignore', body('ignore')) as created: - checkpoint = created.snapshot() - copied = Path(self.tmp.name) / 'ignored-copy' - shutil.copytree(target, copied) - with ProjectStore.open(copied) as reopened: - self.assertEqual(reopened.snapshot(), checkpoint) - reopened.save(checkpoint['checkpoint']) - self.assertEqual((copied / '.gitignore').read_bytes(), expected) - self.assertFalse((target / '.git').exists()) - self.assertFalse((copied / '.git').exists()) - - def test_new_publish_race_does_not_overwrite_an_existing_destination(self): - target = Path(self.tmp.name) / 'raced-new' - publish = store_module._publish_directory - def race(parent_fd, staging, destination): - target.mkdir() - (target / 'owned.txt').write_bytes(b'Existing owner') - publish(parent_fd, staging, destination) - with patch.object(store_module, '_publish_directory', side_effect=race): - self.assert_code('conflict', ProjectStore.create, target, 'New', 'race', body('race')) - self.assertEqual(list(target.iterdir()), [target / 'owned.txt']) - self.assertEqual((target / 'owned.txt').read_bytes(), b'Existing owner') - - def test_interrupted_new_retains_staging_and_never_exposes_partial_final_root(self): - target = Path(self.tmp.name) / 'interrupted-new' - code = r''' -import os,sys -import project_store as m -def interrupt(*args): os._exit(74) -m._publish_directory=interrupt -m.ProjectStore.create(sys.argv[1],'Interrupted','new','a'*64) -''' - child = subprocess.run([sys.executable, '-c', code, str(target)], - cwd=Path(store_module.__file__).parent, capture_output=True, text=True, timeout=10) - self.assertEqual(child.returncode, 74, child.stderr) - self.assertFalse(target.exists()) - staging = list(Path(self.tmp.name).glob('.tuldok-new-*')) - self.assertEqual(len(staging), 1) - with ProjectStore.open(staging[0]) as retained: - self.assertIsNotNone(retained.reconcile('new', 'a' * 64)) - with ProjectStore.create(target, 'Retry explicit new', 'retry', body('retry')) as fresh: - self.assertEqual(fresh.snapshot()['records'], []) - - def test_new_parent_sync_failure_reports_unknown_and_reopens_complete_destination(self): - target = Path(self.tmp.name) / 'new-unknown' - publish = store_module._publish_directory - fsync = store_module.os.fsync - published = False - def after_publish(*args): - nonlocal published - publish(*args) - published = True - def fail_parent(fd): - if published: - raise OSError(errno.EIO, 'new parent sync failure') - return fsync(fd) - with patch.object(store_module, '_publish_directory', side_effect=after_publish), patch.object( - store_module.os, 'fsync', side_effect=fail_parent): - self.assert_code('unknown', ProjectStore.create, target, 'Unknown New', 'unknown-new', body('unknown')) - with ProjectStore.open(target) as reopened: - self.assertIsNotNone(reopened.reconcile('unknown-new', body('unknown'))) - self.assertEqual(reopened.snapshot()['records'], []) - - def test_anchored_open_create_nested_and_replaced_configured_root(self): - configured = Path(self.tmp.name) / 'configured' - configured.mkdir() - (configured / 'nested').mkdir() - trusted = os.open(configured, store_module.DIR_FLAGS) - self.addCleanup(lambda: os.close(trusted)) - with ProjectStore.create_at(trusted, 'nested/project', 'Anchored', 'anchored', body('anchored'), - root_path=configured) as project: - expected = project.snapshot() - with ProjectStore.open_at(trusted, 'nested/project', root_path=configured) as project: - self.assertEqual(project.snapshot(), expected) - displaced = configured.with_name('moved-configured') - configured.rename(displaced) - victim = Path(self.tmp.name) / 'victim' - victim.mkdir() - configured.symlink_to(victim, target_is_directory=True) - self.assert_code('invalid', project.snapshot) - self.assert_code('invalid', ProjectStore.open_at, trusted, 'nested/project', root_path=configured) - self.assert_code('invalid', ProjectStore.create_at, trusted, 'unexpected', 'New', 'no', body('no'), - root_path=configured) - self.assertEqual(list(victim.iterdir()), []) - configured.unlink() - configured.mkdir() - self.assert_code('stale', ProjectStore.create_at, trusted, 'unexpected', 'New', 'no', body('no'), - root_path=configured) - self.assertFalse((configured / 'unexpected').exists()) - self.assertFalse((displaced / 'unexpected').exists()) - - def test_anchored_descendant_symlink_and_traversal_never_write_target(self): - configured = Path(self.tmp.name) / 'configured' - configured.mkdir() - victim = Path(self.tmp.name) / 'victim' - victim.mkdir() - (configured / 'alias').symlink_to(victim, target_is_directory=True) - trusted = os.open(configured, store_module.DIR_FLAGS) - self.addCleanup(lambda: os.close(trusted)) - for relative in ('alias/project', '../victim/project', '/absolute', 'a//b', 'a/./b'): - self.assert_code('invalid', ProjectStore.create_at, trusted, relative, 'New', 'new', body('new'), - root_path=configured) - self.assertEqual(list(victim.iterdir()), []) - - def test_real_process_kills_across_publication_windows_reopen_coherently(self): - self.store.close() - original = self.bytes_tree() - code = r''' -import hashlib,json,os,sys -import project_store as m -from project_store import ProjectStore -root, window = sys.argv[1:] -store = ProjectStore.open(root) -records=[{'family':'workbench_text','id':'a','document':{'format':'workbench_text_v1','text':'acknowledged-or-old'}}] -key='crash-edit' -digest=hashlib.sha256(json.dumps(records,sort_keys=True).encode()).hexdigest() -write=m._write_file -replace=m.os.replace -publish=store._publish -def crash_write(directory,name,raw): - write(directory,name,raw) - if (window=='record' and not name.startswith('.checkpoint-')) or (window=='checkpoint' and name.startswith('.checkpoint-')): - os._exit(73) -def crash_replace(*args,**kwargs): - replace(*args,**kwargs) - if window=='replace': os._exit(73) -def crash_publish(*args,**kwargs): - publish(*args,**kwargs) - if window=='durable': os._exit(73) -m._write_file=crash_write -m.os.replace=crash_replace -store._publish=crash_publish -store.commit(records,store.snapshot()['checkpoint'],key,digest) -raise AssertionError('Fault window was not reached') -''' - for window in ('record', 'checkpoint', 'replace', 'durable'): - with self.subTest(window=window): - destination = Path(self.tmp.name) / ('kill-' + window) - shutil.copytree(self.root, destination) - child = subprocess.run([sys.executable, '-c', code, str(destination), window], - cwd=Path(store_module.__file__).parent, capture_output=True, text=True, timeout=10) - self.assertEqual(child.returncode, 73, child.stderr) - with ProjectStore.open(destination) as reopened: - snapshot = reopened.snapshot() - committed = window in ('replace', 'durable') - self.assertEqual(bool(snapshot['records']), committed) - records = [dict(family='workbench_text', id='a', document=dict( - format='workbench_text_v1', text='acknowledged-or-old'))] - self.assertEqual(reopened.reconcile('crash-edit', body(records)) is not None, committed) - reopened.save(snapshot['checkpoint']) - self.assertEqual(self.bytes_tree(), original) - - -if __name__ == '__main__': - unittest.main() diff --git a/tests/test_project_study_execution.py b/tests/test_project_study_execution.py deleted file mode 100644 index 7227e00d..00000000 --- a/tests/test_project_study_execution.py +++ /dev/null @@ -1,716 +0,0 @@ -"""Current Study epochs and retained accounting without imported runtime rows. - -Control tests use real disposable PostgreSQL and the actual canonical owners. -Host execution cases, when added, run only under a coordinated source freeze. -""" -import copy -import hashlib -import json -import os -from pathlib import Path -from types import SimpleNamespace -import tempfile -import threading -import unittest -from unittest.mock import patch -import uuid - -from access import Access -from auth_helpers import ExplicitOwnerFixture -from experiments import Experiments, validate_retained_reservation -from metadata import Metadata, connection_info, CATALOG_LOCAL_TIMEOUT -from project_history import capture_run, declarations -from project_projection import ProjectProjection -from project_session import operation_records -from project_store import ProjectStore -from project_study_execution import ProjectStudyExecution, validate_operation_result -from test_project_history import legacy_run, policy, study, trial, Materials, ORIGIN -from workbench import WorkbenchError, encode - - -class CandidatePreparationContractTests(unittest.TestCase): - def test_intent_binds_exact_candidate_and_study_revision_without_local_authority(self): - from project_history import HistoryFacts - from pipeline import digest - candidate=dict(id='6'*32,study_id='3'*32,diagnostic='Exact authored selection') - fact=dict(format='project_candidate_preparation_intent_v1',origin_catalog_id=ORIGIN,study_id='3'*32, - study_revision=4,candidate=dict(kind='candidate',catalog_id=ORIGIN,id=candidate['id'],sha256=digest(candidate)), - actor_id='5'*32,request_sha256='a'*64,root='explicit',directory='prepared',runtime_snapshot_sha256='b'*64) - facts=HistoryFacts();facts.candidates[(ORIGIN,candidate['id'])]=dict(candidate=candidate) - facts.studies[(ORIGIN,'3'*32)]=dict(revisions=[dict(revision=4)]) - operation='study_execution.prepare_package_intent' - with patch('project_study_execution._facts',return_value=facts): - self.assertTrue(validate_operation_result(operation,fact,[])) - for change in (dict(fact,study_revision=5),dict(fact,candidate=dict(fact['candidate'],sha256='c'*64)), - dict(fact,current_local=True),dict(fact,grant={'token':'secret'})): - with self.subTest(change=change),self.assertRaises(WorkbenchError): - validate_operation_result(operation,change,[]) - - def test_archived_input_facade_requires_new_disclosure_and_never_constructs_runs(self): - from project_history import ProjectHistory,HistoryFacts - from project_study_execution import _PreparationRuns - run=legacy_run();run['exposure_events']=[{'historical':'This fact grants nothing'}] - facts=HistoryFacts();facts.runs[(ORIGIN,run['id'])]=dict(origin_catalog_id=ORIGIN,run=run,payloads=[]) - session=SimpleNamespace(access=SimpleNamespace(require=lambda *a,**k:None),artifacts=None, - snapshot=dict(records=[],project_id=ORIGIN)) - history=ProjectHistory(session,materials=Materials());history._facts=lambda:facts - adapter=SimpleNamespace(history=history,origin=ORIGIN,session=session) - facade=_PreparationRuns(adapter) - with patch('runs.Runs',side_effect=AssertionError('Archived package input allocated Runs')): - with self.assertRaisesRegex(WorkbenchError,'Current explicit disclosure'):facade._load(run['id']) - seen=[];history.authorize_disclosure=lambda selected,population:seen.append((selected['id'],population)) - self.assertEqual(facade._load(run['id']),run) - self.assertEqual(seen,[(run['id'],'unknown')]) - self.assertFalse(hasattr(facade,'_admit'));self.assertFalse(hasattr(facade,'_start')) - - def test_native_directory_write_follows_ack_hook_and_project_failure_preserves_it(self): - import candidate_packages as packages - from test_candidate_packages import fixture - manifest,blobs=fixture();package=packages.create_package(manifest,blobs) - descriptor=packages.decode(blobs['runtime.json'])['snapshot'] - candidate=dict(ref=manifest['candidate'],candidate=packages.decode(blobs['candidate-decision.json'])) - with tempfile.TemporaryDirectory(prefix='tuldok-package-publication-') as directory: - root=Path(directory);root_fd=os.open(root,os.O_RDONLY|os.O_DIRECTORY) - self.addCleanup(os.close,root_fd);events=[] - def opened(body): - self.assertTrue((root/'prepared'/'project.json').is_file()) - events.append('source-read');raise RuntimeError('Controlled failure after directory publication') - access=SimpleNamespace(require=lambda *a,**k:SimpleNamespace(actor_id='5'*32)) - dataset=SimpleNamespace(db=SimpleNamespace(in_transaction=False,dataset_id=descriptor['catalog_id']), - path=root,projects=SimpleNamespace(roots={'explicit':(root_fd,[os.fstat(root_fd).st_dev,os.fstat(root_fd).st_ino])},open=opened), - runs=SimpleNamespace(artifact=lambda *args:(package,'application/zip'))) - studies=SimpleNamespace(db=dataset.db,access=access,dataset=dataset,lock=threading.RLock(), - _receipt=lambda *args:None,_study=lambda _:dict(revision=1),_expected=lambda *args:None, - candidate=lambda _:candidate) - def before_write(): - self.assertFalse((root/'prepared').exists());events.append('acknowledged-start') - publication=SimpleNamespace(runtime_snapshot=descriptor,before_write=before_write) - body=dict(request_key='controlled-prepare',revision=1,candidate_id=manifest['candidate']['id'], - root='explicit',directory='prepared',runtime_snapshot_sha256=descriptor['manifest_sha256'], - package_run_id='7'*32,package_sha256=packages.sha(package)) - with self.assertRaisesRegex(RuntimeError,'after directory publication'): - packages._prepare_operation(studies,candidate['candidate']['study_id'],body,'verify',publication=publication) - self.assertEqual(events,['acknowledged-start','source-read']) - self.assertTrue((root/'prepared'/'project.json').is_file()) - - -class StudyExecutionCodecTests(unittest.TestCase): - def test_canonical_reconstruction_uses_one_selected_material_view(self): - records=[];view=object();calls=[] - class Materials: - def read_view(self,selected): - calls.append(selected);return view - adapter=ProjectStudyExecution.__new__(ProjectStudyExecution) - adapter.session=SimpleNamespace(snapshot={'records':records});adapter.materials=Materials() - def decoded(selected,*,materials): - self.assertIs(selected,records);self.assertIs(materials,view);return 'selected facts' - with patch('project_study_execution.history_records',side_effect=decoded): - self.assertEqual(adapter._canonical(),'selected facts') - self.assertEqual(adapter._canonical(records),'selected facts') - self.assertEqual(len(calls),2) - self.assertTrue(all(selected is records for selected in calls)) - - def test_fixed_record_validation_has_no_live_material_session(self): - import project_study_execution as owner - from project_material import MaterialSnapshot - records=[] - def decoded(selected,*,materials): - self.assertIs(selected,records);self.assertIsInstance(materials,MaterialSnapshot);return 'fixed facts' - with patch('project_study_execution.ProjectMaterial',side_effect=AssertionError('No live material lookups')), \ - patch('project_study_execution.history_records',side_effect=decoded): - self.assertEqual(owner._facts(records),'fixed facts') - - def test_admission_has_only_exact_reservation_and_references(self): - value=trial('9'*32,'3'*32)['document']['trial'];composition=Materials().recipe(value['material']) - charge=composition['material']['resource_envelope'] - reservation=dict(id='e'*32,study_id='3'*32,admission_epoch=1,request_key='admission-0001',actor_id='5'*32, - trial_id=value['id'],parent_run_id=None,run_id='7'*32,request_sha256='c'*64, - material_sha256=value['material']['sha256'],envelope=charge,state='reserved',settled=None) - run=dict(id='7'*32,actor_id='5'*32,request_sha256='c'*64,parent_run_id=None, - approval_material_sha256=value['material']['sha256']) - validate_retained_reservation(reservation,trial=value,composition=composition,run=run) - result=dict(format='project_study_admission_v1',origin_catalog_id=ORIGIN, - study_id=reservation['study_id'],trial_id=value['id'],run_id=reservation['run_id'],reservation=reservation) - self.assertTrue(validate_operation_result('study_execution.admit',result)) - for change in ({'run':{'token':'secret'}},{'run_id':'8'*32}): - with self.subTest(change=change),self.assertRaises(WorkbenchError): - validate_operation_result('study_execution.admit',dict(result,**change)) - changed=copy.deepcopy(result);changed['reservation']['envelope']['secret']='secret' - with self.assertRaises(WorkbenchError):validate_operation_result('study_execution.admit',changed) - - def test_approval_canonical_fact_is_inert_and_never_contains_a_local_grant_wrapper(self): - fact=dict(format='project_study_approval_v1',origin_catalog_id=ORIGIN,study_id='3'*32, - trial_id='9'*32,approval_id='a'*32,material_sha256='b'*64, - consumer_actor_id='c'*32,approver_actor_id='d'*32,created_at=1,expires_at=601) - self.assertTrue(validate_operation_result('study_execution.approve',fact)) - for change in ({'current_local':True},{'grant':{'token':'secret'}},{'expires_at':4000}): - with self.subTest(change=change),self.assertRaises(WorkbenchError): - validate_operation_result('study_execution.approve',dict(fact,**change)) - - def test_project_reservation_uses_retained_material_and_shared_proof_validation(self): - value=trial('9'*32,'3'*32)['document']['trial'];composition=Materials().recipe(value['material']) - reservation=dict(id='e'*32,study_id='3'*32,admission_epoch=1,request_key='admission-0001',actor_id='5'*32, - trial_id=value['id'],parent_run_id=None,run_id='7'*32,request_sha256='c'*64, - material_sha256=value['material']['sha256'],envelope=composition['material']['resource_envelope'], - state='reserved',settled=None) - run=dict(id='7'*32,actor_id='5'*32,request_sha256='c'*64,parent_run_id=None, - approval_material_sha256=value['material']['sha256']) - row={key:reservation[key] for key in ('id','study_id','actor_id','request_key','request_sha256','trial_id','run_id')} - row['document']=json.dumps(reservation) - owner=Experiments.__new__(Experiments);owner.trial=lambda _:value;owner._run_fact=lambda _:run - owner.dataset=SimpleNamespace(project_study_execution=SimpleNamespace(materials=Materials()), - pipelines=SimpleNamespace(recipe_material=lambda _:(_ for _ in ()).throw( - AssertionError('Project settlement crossed into host-authorized material owner')))) - self.assertEqual(owner._reservation(row),reservation) - changed=copy.deepcopy(reservation);changed['envelope']['retained_bytes']+=1 - row['document']=json.dumps(changed) - with self.assertRaises(WorkbenchError):owner._reservation(row) - - def test_approval_binds_exact_owner_audit_and_abandon_cannot_activate_pending_epoch(self): - from project_history import HistoryFacts, _audit - value=trial('9'*32,'3'*32)['document']['trial'] - fact=dict(format='project_study_approval_v1',origin_catalog_id=ORIGIN,study_id='3'*32, - trial_id=value['id'],approval_id='a'*32,material_sha256=value['material']['sha256'], - consumer_actor_id='c'*32,approver_actor_id='d'*32,created_at=1,expires_at=601) - details={key:fact[key] for key in ('trial_id','material_sha256','approval_id','consumer_actor_id','created_at','expires_at')} - audit=dict(actor_id=fact['approver_actor_id'],action='studies.approve',target=fact['study_id'], - details=details,result='success',occurred_at='1970-01-01T00:00:01+00:00') - _audit([audit]) - facts=HistoryFacts();facts.studies[(ORIGIN,fact['study_id'])]=dict(audit=[audit]) - facts.trials[(ORIGIN,value['id'])]=dict(trial=value) - # Supply only the already-decoded closure lookup; the actual binding - # policy and the common execution approval validator remain real. - with patch('project_study_execution._facts',return_value=facts): - self.assertTrue(validate_operation_result('study_execution.approve',fact,[])) - for field,changed in (('consumer_actor_id','e'*32),('approver_actor_id','e'*32), - ('expires_at',602),('material_sha256','f'*64)): - with self.subTest(field=field),self.assertRaises(WorkbenchError): - validate_operation_result('study_execution.approve',dict(fact,**{field:changed}),[]) - adapter=ProjectStudyExecution.__new__(ProjectStudyExecution) - adapter._dirty={'3'*32};adapter._revisions={'3'*32:{2:{'revision':2}}} - adapter._pending_epochs={'3'*32:99};adapter._epochs={'4'*32:2} - adapter._package_records=[] - adapter.abandon_pending() - self.assertEqual(adapter._epochs,{'4'*32:2}) - self.assertFalse(adapter._dirty);self.assertFalse(adapter._revisions);self.assertFalse(adapter._pending_epochs) - - def test_old_reservations_contribute_full_charges_but_are_not_local_children(self): - historical=dict(id='e'*32,run_id='7'*32,state='unknown',settled=None, - envelope=dict(attempt_slots=2,admitted_wall_seconds=70,retained_bytes=800,peak_staging_bytes=900)) - class ReadOnlyRows: - def execute(self,query,args=()): - if query.startswith('SELECT * FROM model_attempt_reservations'):return [] - raise AssertionError(query) - adapter=SimpleNamespace(historical_reservations=lambda _: [copy.deepcopy(historical)],local_run_ids=lambda:set()) - owner=Experiments.__new__(Experiments) - owner.db=ReadOnlyRows();owner.dataset=SimpleNamespace(project_study_execution=adapter, - runs=SimpleNamespace(_load=lambda _:(_ for _ in ()).throw(AssertionError('Historical Run reached live resolver')))) - values=owner._reservations('3'*32) - self.assertEqual(owner._totals(values),historical['envelope']) - self.assertEqual(owner._children_ceased(values),(True,False)) - self.assertEqual(values,[historical]) - - -@unittest.skipUnless(os.environ.get('TULDOK_DATABASE_URL'),'Requires disposable PostgreSQL') -class ProjectStudyControlTests(unittest.TestCase): - def setUp(self): - self.temporary=tempfile.TemporaryDirectory(prefix='tuldok-study-execution-') - self.addCleanup(self.temporary.cleanup);self.root=Path(self.temporary.name) - self.databases=[];self.projections=[];self.addCleanup(self.cleanup) - host_db=self.metadata('host');self.host=SimpleNamespace(db=host_db,access=Access(host_db,host_db.path)) - self.owner=ExplicitOwnerFixture.bootstrap(self.host) - self.store=ProjectStore.create(self.root/'project','Current Study intent','study-fixture','f'*64) - self.addCleanup(self.store.close) - self.open_projection() - - def metadata(self,name,*,project_id=None): - kwargs={} if project_id is None else dict(dataset_id=project_id,projection_id=uuid.uuid4().hex) - db=Metadata(self.root/name,**kwargs);self.databases.append(db);return db - - def open_projection(self): - db=self.metadata('projection-'+uuid.uuid4().hex,project_id=self.store.snapshot()['project_id']) - with self.owner.bound(self.host),patch('runs.Runs',side_effect=AssertionError('Inert Study Open constructed Runs')): - projection=ProjectProjection(self.store,db,self.host.access,{}) - adapter=getattr(projection,'study_execution',None) - if adapter is None: - adapter=ProjectStudyExecution(projection,projection.execution);adapter.restore_authoring() - self.projections.append(projection);self.projection=projection;self.adapter=adapter - - def cleanup(self): - import psycopg - from psycopg import sql - for projection in reversed(self.projections): - try:projection.close() - except BaseException: - # No test here admits a worker; cleanup only this fixture's DB - # and artifact handles even after an asserted rollback failure. - projection.artifacts.close();projection.db.close() - for db in reversed(self.databases):db.close() - with psycopg.connect(connection_info(),autocommit=True) as connection: - for db in self.databases: - connection.execute(sql.SQL('DROP SCHEMA IF EXISTS {} CASCADE').format(sql.Identifier(db.schema))) - - def create_study(self): - body=dict(name='Persistent scientific intent',limits=dict(attempt_slots=3,admitted_wall_seconds=100, - retained_bytes=10000,peak_staging_bytes=10000),policy=policy()) - return self.projection.history.create_study(body,self.projection.session.snapshot['checkpoint'],'study-create-0001') - - def assert_no_runtime_authority(self): - for table in ('workspace_runs','model_attempt_reservations','access_admissions','access_execution_grants', - 'access_execution_consumptions','access_actors','access_credentials'): - self.assertEqual(self.projection.db.execute('SELECT count(*) FROM '+table).fetchone()[0],0,table) - self.assertIsNone(self.projection.execution._runs) - - def test_canonical_metadata_projects_before_background_read_and_continue_never_constructs_runs(self): - with self.owner.bound(self.host),patch('runs.Runs',side_effect=AssertionError('Continue constructed Runs')): - value=self.create_study() - self.assertEqual(self.adapter.studies._study(value['id']),value) - opened=self.adapter.continue_study(value['id'],dict(revision=1,admission_epoch=0), - self.projection.session.snapshot['checkpoint'],'study-continue-0001') - self.assertTrue(self.adapter.epoch_current(opened));self.assertEqual(opened['admission_epoch'],1) - saved=self.projection.history.save_study(value['id'],dict(revision=opened['revision'],name='New exact intent', - limits=opened['limits'],policy=opened['policy']),self.projection.session.snapshot['checkpoint'],'study-save-0001') - self.assertEqual(self.adapter.studies._study(value['id']),saved) - self.assertTrue(self.adapter.epoch_current(saved)) - self.assert_no_runtime_authority() - - def test_cold_open_keeps_epoch_fact_inert_and_requires_fresh_explicit_continue(self): - with self.owner.bound(self.host): - value=self.create_study() - opened=self.adapter.continue_study(value['id'],dict(revision=1,admission_epoch=0), - self.projection.session.snapshot['checkpoint'],'study-continue-0001') - checkpoint=self.projection.session.snapshot['checkpoint'] - self.projection.close();self.open_projection() - with self.owner.bound(self.host),patch.object(self.projection.execution,'_local_owner',side_effect=AssertionError('Historical epoch activated owner')): - self.assertEqual(self.adapter.studies._study(value['id']),opened) - self.assertFalse(self.adapter.epoch_current(opened));self.assert_no_runtime_authority() - before=self.projection.session.snapshot - with self.assertRaisesRegex(WorkbenchError,'historical Continue'): - self.adapter.continue_study(value['id'],dict(revision=1,admission_epoch=0),checkpoint,'study-continue-0001') - with self.assertRaisesRegex(WorkbenchError,'Explicitly continue'): - self.adapter.admit(value['id'],dict(revision=opened['revision'],admission_epoch=opened['admission_epoch'],trial_id='9'*32), - checkpoint,'new-attempt-0001') - self.assertEqual(self.projection.session.snapshot,before) - continued=self.adapter.continue_study(value['id'],dict(revision=opened['revision'],admission_epoch=opened['admission_epoch']), - checkpoint,'study-continue-0002') - self.assertEqual(continued['admission_epoch'],opened['admission_epoch']+1) - self.assertEqual(continued['limits'],opened['limits']);self.assertTrue(self.adapter.epoch_current(continued)) - self.assert_no_runtime_authority() - - def test_multiple_source_revisions_in_one_transaction_survive_and_rollback_does_not_activate_epoch(self): - with self.owner.bound(self.host): - value=self.create_study();before=self.projection.session.snapshot - with self.assertRaisesRegex(RuntimeError,'authored rollback'): - with self.projection.db.transaction(): - changed=copy.deepcopy(value);changed['name']='Must roll back' - self.adapter.studies._write(changed,'studies.save') - self.adapter._pending_epochs[value['id']]=99 - raise RuntimeError('authored rollback') - self.assertEqual(self.projection.session.snapshot,before) - self.assertFalse(self.adapter._dirty);self.assertFalse(self.adapter._epochs) - with self.projection.db.transaction(): - current=copy.deepcopy(value);current['name']='Observed revision two' - current=self.adapter.studies._write(current,'studies.save') - current['name']='Observed revision three' - current=self.adapter.studies._write(current,'studies.save') - doc=self.projection.history._facts().studies[(self.adapter.origin,value['id'])] - self.assertEqual([item['revision'] for item in doc['revisions']],[1,2,3]) - self.assertEqual([item['name'] for item in doc['revisions']], - ['Persistent scientific intent','Observed revision two','Observed revision three']) - self.assertEqual(doc['study'],current);self.assert_no_runtime_authority() - - -if __name__=='__main__':unittest.main() - - -# Reuse only the authored neutral fixture helpers, never its test methods. -import test_project_execution as _run_fixtures - - -@unittest.skipUnless(os.environ.get('TULDOK_DATABASE_URL'),'Requires disposable PostgreSQL and coordinated host-source freeze') -class ProjectStudyCustodyTests(unittest.TestCase): - setUp=_run_fixtures.ProjectRunCustodyTests.setUp - metadata=_run_fixtures.ProjectRunCustodyTests.metadata - cleanup=_run_fixtures.ProjectRunCustodyTests.cleanup - checkpoint=_run_fixtures.ProjectRunCustodyTests.checkpoint - record=_run_fixtures.ProjectRunCustodyTests.record - await_drained=_run_fixtures.ProjectRunCustodyTests.await_drained - - def prepare_study(self): - from pipeline import digest - materials=self.projection.materials - body=dict(name='Captured neutral Study model',kind='captured_source', - task=dict(kind='task',catalog_id=self.db.dataset_id,id='neutral.bytes',revision=1, - sha256=digest({'format':'authored_neutral_task_v1'})), - specification={'format':'authored_neutral_model_v1'}, - source_selector=dict(project_id=self.manifest['id'],recipe_id='neutral', - expected_sha256=hashlib.sha256(self.definition_raw).hexdigest()), - preprocessing_policy={'kind':'identity'},output_policy={'kind':'exact_bytes'}) - draft=materials.mutate_definition('model_definition','models.create',None,body,self.checkpoint(), - 'study-model-create',lambda:self.projection.models.create(body)) - model=materials.publish_model(self.projection.models,draft['id'],{'revision':1},self.checkpoint(),'study-model-publish') - material=materials.prepare_recipe(self.projection.pipelines,self.graph['id'],self.graph['revision'],model['ref'], - self.checkpoint(),'study-recipe-prepare') - # The capture owner returns the immutable composition, never a plan. - composition=self.projection.materials.recipe(material['ref']) - envelope=composition['material']['resource_envelope'] - limits={key:value*3 for key,value in envelope.items()} - study_value=self.projection.history.create_study(dict(name='Current neutral Study',limits=limits,policy=policy()), - self.checkpoint(),'study-create') - trial_value=self.projection.history.prepare_trial_from_material(study_value['id'],dict(revision=1, - material=composition['ref'],replicate=0),self.checkpoint(),'study-trial-prepare') - ref=dict(catalog_id=self.db.dataset_id,trial_id=trial_value['id'],material_sha256=composition['ref']['sha256']) - intent=dict(ancestry='root',parent=None,baseline=None,cohort='authored neutral control', - hypothesis='Exact original Study intent survives a cold runtime',change_summary='No change', - target=dict(metric_id='diagnostic',metric_definition_sha256=None,direction='maximize',threshold=None, - acceptance='No scientific qualification claim')) - lineage=self.projection.history.record_lineage(dict(trial=ref,intent=intent),self.checkpoint(),'study-lineage') - return study_value['id'],trial_value,composition,envelope,lineage - - def test_cold_study_spent_budget_lineage_and_approval_remain_inert_while_fresh_attempt_is_current(self): - from project_projection import ProjectProjection - study_id,trial_value,composition,envelope,lineage=self.prepare_study() - # Keep this case within its declared custody budget plus the two - # bounded catalog waits for terminal publication and observation. - drain_timeout=envelope['admitted_wall_seconds']+2*CATALOG_LOCAL_TIMEOUT - adapter=self.projection.study_execution - value=adapter.studies._study(study_id) - opened=adapter.continue_study(study_id,dict(revision=value['revision'],admission_epoch=value['admission_epoch']), - self.checkpoint(),'study-current-continue') - self.assertIsNone(self.execution._runs) - approval_body=dict(trial_id=trial_value['id'],expected_material_sha256=composition['ref']['sha256'], - consumer_actor_id=self.access.identity()['actor_id']) - approval=adapter.approve(study_id,approval_body,self.checkpoint(),'study-current-approve') - fact=operation_records(self.session.snapshot['records'])['study-current-approve']['result'] - self.assertEqual(fact['format'],'project_study_approval_v1') - self.assertNotIn('current_local',fact);self.assertNotIn('grant',fact) - self.assertEqual(approval['grant']['id'],fact['approval_id']) - self.assertIsNone(self.execution._runs) - request=dict(revision=opened['revision'],admission_epoch=opened['admission_epoch'],trial_id=trial_value['id'], - approval_id=approval['grant']['id']) - admitted=adapter.admit(study_id,request,self.checkpoint(),'study-current-attempt') - first=self.await_drained(admitted['run_id'],timeout=drain_timeout) - self.assertEqual(first['state'],'completed') - saved=self.projection.history.study(study_id) - self.assertEqual(saved['charged'],envelope) - self.assertEqual(saved['reservations'][0]['state'],'settled') - self.assertEqual(saved['reservations'][0]['settled'],envelope) - self.assertEqual(adapter.studies.lineage._record(trial_value['id']),lineage) - old_grant=approval['grant']['id'];old_run=admitted['run_id'];logical=self.db.dataset_id - self.execution.reconcile_current() - self.projection.close() - # Its worker has drained and closed; leave no duplicate cleanup owner. - self.execution._runs=None - self.db=self.metadata('cold-study-projection',logical) - with patch('runs.Runs',side_effect=AssertionError('Cold Study Open constructed Runs')): - self.projection=ProjectProjection(self.store,self.db,self.access,{'fixture':self.source_root}) - self.projections.append(self.projection);self.execution=self.projection.execution;self.session=self.projection.session - adapter=self.projection.study_execution - self.assertEqual(adapter.studies._totals(adapter.studies._reservations(study_id)),envelope) - self.assertEqual(adapter.studies.lineage._record(trial_value['id']),lineage) - for table in ('workspace_runs','model_attempt_reservations','access_admissions','access_execution_grants', - 'access_execution_consumptions','model_operation_receipts'): - self.assertEqual(self.db.execute('SELECT count(*) FROM '+table).fetchone()[0],0,table) - with patch.object(self.execution,'_local_owner',side_effect=AssertionError('Historical request allocated a new owner')): - with self.assertRaisesRegex(WorkbenchError,'historical'): - adapter.approve(study_id,approval_body,self.checkpoint(),'study-current-approve') - with self.assertRaisesRegex(WorkbenchError,'historical admission'): - adapter.admit(study_id,request,self.checkpoint(),'study-current-attempt') - value=adapter.studies._study(study_id) - with self.assertRaisesRegex(WorkbenchError,'Explicitly continue'): - adapter.admit(study_id,dict(revision=value['revision'],admission_epoch=value['admission_epoch'], - trial_id=trial_value['id'],approval_id=old_grant),self.checkpoint(),'study-before-new-epoch') - lower=dict(value['limits']);lower['retained_bytes']=envelope['retained_bytes']-1 - before=self.session.snapshot - with self.assertRaises(WorkbenchError): - self.projection.history.save_study(study_id,dict(revision=value['revision'],name=value['name'], - limits=lower,policy=value['policy']),self.checkpoint(),'study-lower-spent-budget') - self.assertEqual(self.session.snapshot,before) - continued=adapter.continue_study(study_id,dict(revision=value['revision'],admission_epoch=value['admission_epoch']), - self.checkpoint(),'study-fresh-continue') - self.assertGreater(continued['admission_epoch'],opened['admission_epoch']) - self.projection.source_adapter.register(dict(root='fixture',manifest_path='project.json'), - self.checkpoint(),'study-fresh-source-binding') - recipe_cache=self.projection.pipelines.material_path/composition['ref']['sha256'] - model_cache=self.projection.models.path/composition['material']['model']['sha256'] - self.assertFalse(recipe_cache.exists());self.assertFalse(model_cache.exists()) - original_open=self.projection.artifacts.open_verified - def missing_payload(declaration,**kwargs): - if declaration['sha256']==composition['material']['recipe_document']['sha256']: - raise WorkbenchError('Controlled missing canonical recipe bytes.','unavailable',409) - return original_open(declaration,**kwargs) - before=self.session.snapshot - with patch.object(self.projection.artifacts,'open_verified',side_effect=missing_payload): - with self.assertRaisesRegex(WorkbenchError,'missing canonical'): - adapter.approve(study_id,approval_body,self.checkpoint(),'study-missing-payload') - self.assertEqual(self.session.snapshot,before) - self.assertEqual(self.db.execute('SELECT count(*) FROM access_execution_grants').fetchone()[0],0) - current=adapter.approve(study_id,approval_body,self.checkpoint(),'study-fresh-approve') - self.assertTrue(recipe_cache.is_dir());self.assertTrue(model_cache.is_dir()) - self.assertNotEqual(current['grant']['id'],old_grant) - self.assertIsNone(self.db.execute('SELECT id FROM access_execution_grants WHERE id=%s',(old_grant,)).fetchone()) - second=adapter.admit(study_id,dict(revision=continued['revision'],admission_epoch=continued['admission_epoch'], - trial_id=trial_value['id'],approval_id=current['grant']['id']),self.checkpoint(),'study-fresh-attempt') - result=self.await_drained(second['run_id'],timeout=drain_timeout);self.assertEqual(result['state'],'completed') - self.assertNotEqual(second['run_id'],old_run) - self.assertEqual(self.db.execute('SELECT count(*) FROM workspace_runs').fetchone()[0],1) - self.assertEqual(self.db.execute('SELECT count(*) FROM model_attempt_reservations').fetchone()[0],1) - self.assertIsNone(self.db.execute('SELECT id FROM workspace_runs WHERE id=%s',(old_run,)).fetchone()) - self.assertEqual(self.projection.history.study(study_id)['charged'],{key:2*value for key,value in envelope.items()}) - self.assertEqual(adapter.studies.lineage._record(trial_value['id']),lineage) - - -@unittest.skipUnless(os.environ.get('TULDOK_DATABASE_URL'),'Requires disposable PostgreSQL') -class CandidateNativePublicationTests(unittest.TestCase): - """Actual writers/codecs with authored observations; no fitted-model claim. - - Only verified candidate selection is substituted. The explicitly authored - historical Run/receipt is test data, never an observed process completion. - No runtime executable, project source, or model state may be launched. - """ - setUp=ProjectStudyControlTests.setUp - metadata=ProjectStudyControlTests.metadata - cleanup=ProjectStudyControlTests.cleanup - prepare_study=ProjectStudyCustodyTests.prepare_study - - def open_projection(self): - from project_custody import ProjectCustody - db=self.metadata('writer-projection-'+uuid.uuid4().hex,project_id=self.store.snapshot()['project_id']) - journal=ProjectCustody(self.host.db.path,self.host.db.dataset_id).for_projection(self.store,db.projection_id) - with self.owner.bound(self.host),patch('runs.Runs',side_effect=AssertionError('Inert writer Open constructed Runs')): - projection=ProjectProjection(self.store,db,self.host.access,{},custody=journal) - self.projections.append(projection);self.projection=projection;self.adapter=projection.study_execution - - def checkpoint(self):return self.projection.session.snapshot['checkpoint'] - - def test_actual_verifier_owner_publication_is_canonical_and_cold_inert(self): - self._native_publication() - - def test_native_completion_before_wrapper_ack_reconciles_without_repeating_writer(self): - self._native_publication(wrapper_loss=True) - - def _native_publication(self,*,wrapper_loss=False): - import shutil - import candidate_packages as packages - import recipe_contract,recipe_process - from pipeline import digest,execution_digest - from project_history import envelope,FAMILY_FORMATS - from project_runtime import ProjectRuntime - from test_candidate_packages import fixture - from test_project_files_material_http import neutral_source - self.db=self.projection.db;self.source_root=self.root/'source';self.source_root.mkdir() - self.manifest,self.manifest_raw,self.definition_raw,self.source,self.input=neutral_source(self.source_root) - definition=json.loads(self.definition_raw) - definition['outputs']=[dict(path=name,role='result',max_bytes=2*1024**2,required=True) - for name in ('package.zip','checkpoint-epoch-0001.json','metrics.json')] - definition['resources']['max_output_bytes']=6*1024**2 - self.definition_raw=json.dumps(definition).encode();self.manifest['recipes'][0]['sha256']=packages.sha(self.definition_raw) - (self.source_root/'recipe.json').write_bytes(self.definition_raw) - (self.source_root/'project.json').write_bytes(json.dumps(self.manifest).encode()) - fd=os.open(self.source_root,os.O_RDONLY|os.O_DIRECTORY);info=os.fstat(fd) - self.projection.sources.roots['fixture']=(fd,[info.st_dev,info.st_ino]) - with self.owner.bound(self.host),patch('subprocess.Popen',side_effect=AssertionError('No process in writer qualification')),patch('runs.Runs',side_effect=AssertionError('No Run owner in writer qualification')): - self.projection.source_adapter.register(dict(root='fixture',manifest_path='project.json'),self.checkpoint(),'candidate-source') - body=dict(name='Authored source graph',project_id=self.manifest['id'],recipe_id='neutral',expected_sha256=packages.sha(self.definition_raw), - inputs={'sample':dict(reference_id='sample',expected_sha256=packages.sha(self.input))}) - self.graph=self.projection.materials.mutate_definition('pipeline_graph','graphs.create_external',None,body, - self.checkpoint(),'candidate-source-graph',lambda:self.projection.pipelines.create_external(body)) - study_id,trial_value,composition,envelope_value,_lineage=self.prepare_study() - python=self.root/'python';site=self.root/'packages' - (python/'bin').mkdir(parents=True);(python/'lib/python3.12/lib-dynload').mkdir(parents=True) - shutil.copyfile('/usr/bin/true',python/'bin/python3.12');(python/'lib/python3.12/lib-dynload/inert.txt').write_text('Not a Python environment') - entries=[] - for name in ('torch','numpy'): - (site/name).mkdir(parents=True);(site/name/'__init__.py').write_text('raise AssertionError("Never import")\n') - meta=site/(name+'-0.0.dist-info');meta.mkdir();(meta/'METADATA').write_text('Name: '+name+'\nVersion: 0.0\n');(meta/'LICENSE').write_text('Fixture') - entries.extend([name,meta.name]) - config=dict(schema_version=1,python_root=str(python),python_version='3.12',site_packages=str(site),packages=entries) - runtime=ProjectRuntime(self.projection,resolve_configuration=lambda request:copy.deepcopy(config)) - observed=runtime.inspect({'source':'authored'}) - captured=runtime.capture({'source':'authored'},observed['inventory_sha256'],self.checkpoint(),'candidate-runtime',reserve_bytes=0) - descriptor=self.projection.materials.runtime(captured['runtime_ref'])['descriptor'] - old_manifest,old_blobs=fixture();published=packages.decode(old_blobs['published-model-material.json']);published['catalog_id']=self.db.dataset_id - artifacts={name:old_blobs[name] for name in ('checkpoint-epoch-0001.json','weights-epoch-0001.pt','model-definition.json','fitted-transform.json','metrics.json','probe.json','probes-epoch-0001.json')} - checkpoint=packages.decode(artifacts['checkpoint-epoch-0001.json']);checkpoint['model_sha256']=packages.sha(packages.encoded(published));artifacts['checkpoint-epoch-0001.json']=packages.encoded(checkpoint) - probes=packages.decode(artifacts['probes-epoch-0001.json']);probes['checkpoint_sha256']=packages.sha(artifacts['checkpoint-epoch-0001.json']);artifacts['probes-epoch-0001.json']=packages.encoded(probes) - study_doc=next(copy.deepcopy(r) for r in self.projection.session.snapshot['records'] if r['family']=='study_history' and r['document']['study']['id']==study_id) - decision=dict(format='candidate_v1',id='f'*32,study_id=study_id,trial_id=trial_value['id'],run_id='a'*32, - checkpoint_sha256=packages.sha(artifacts['checkpoint-epoch-0001.json']),evaluation_sha256=packages.sha(artifacts['metrics.json']), - policy=study_doc['document']['study']['policy'],decision='diagnostic',limitations=['Authored structural writer fixture; not scientific qualification.']) - candidate=dict(ref=dict(kind='candidate',catalog_id=self.db.dataset_id,id=decision['id'],sha256=digest(decision)),candidate=decision, - run_id=decision['run_id'],checkpoint=packages.blob('checkpoint-epoch-0001.json',artifacts['checkpoint-epoch-0001.json'])) - manifest,blobs=packages.classifier_closure(candidate,artifacts,{'c'*32:b'authored fixture; not a PNG'}, - {'image_training.py':b'# inert authored source fixture\n'},packages.runtime_contract(descriptor), - {'material':published,**{name:old_blobs['published-'+name+'.json'] for name in ('specification','preprocessing_policy','output_policy')}}) - package=packages.create_package(manifest,blobs);packages.inspect_package(package,packages.sha(package)) - recipe_snapshot=json.loads(self.projection.materials.blob(composition['ref'],composition['material']['recipe_document'])) - execution=recipe_snapshot['preflight']['material'];run_id='a'*32;request_sha='c'*64 - spec=dict(recipe_contract.spec_for_material(execution,Path('/authored/workspace-runs')/('.external-'+run_id)),attempt_id=run_id,request_sha256=request_sha) - identity=dict(attempt_id=run_id,request_sha256=request_sha,spec_sha256=packages.sha(recipe_process.encoded(spec)),helper=dict(pid=123,start_ticks='1',boot_id='00000000-0000-0000-0000-000000000000')) - receipt=dict(schema_version=1,**identity,go_received=True,spawn_closed=True,drained=True,echild=True,outcome='completed',reason='Authored fixture only',leader_returncode=0, - streams={name:dict(bytes=0,sha256=packages.sha(b'')) for name in ('stdout','stderr')}) - receipt_raw=recipe_process.encoded(receipt) - payload_bytes={'package.zip':package,'checkpoint-epoch-0001.json':artifacts['checkpoint-epoch-0001.json'],'metrics.json':artifacts['metrics.json']} - inventory=[dict(name=name,role='result',bytes=len(raw),sha256=packages.sha(raw),media_type='application/octet-stream') for name,raw in payload_bytes.items()] - actor=self.owner.identity['actor_id'];admission_id='8'*32;approval_id='9'*32 - run=dict(schema_version=1,mode='real',execution_kind='external_recipe',result_kind='external_recipe',id=run_id,dataset_id=self.db.dataset_id, - request_key='authored-history',request_sha256=request_sha,actor_id=actor,admission_id=admission_id,approval_id=approval_id, - state='completed',created_at='2026-10-22T00:00:00+00:00',started_at=None,finished_at='2026-10-22T00:00:01+00:00',graph=self.graph, - graph_revision=self.graph['revision'],graph_sha256=execution_digest(self.graph),graph_document_sha256=digest(self.graph),material=execution, - material_sha256=digest(execution),spec=spec,outputs=execution['recipe']['outputs'],parameters=execution['parameters'],attempt=1,parent_run_id=None, - events=[],artifacts=inventory,metrics=None,error=None,custody_phase='drained',custody_identity=identity,custody_receipt_sha256=packages.sha(receipt_raw), - quality_claim=False,progress=dict(stage='completed',completed=None,total=None),node_attempts=[],approval_material_sha256=composition['ref']['sha256']) - proof=dict(grant=dict(id=approval_id,catalog_id=self.db.dataset_id,approver_actor_id=actor,approver_credential_id='4'*32,consumer_actor_id=actor, - material_sha256=composition['ref']['sha256'],created_at=1,expires_at=601,revoked_at=None), - consumption=dict(grant_id=approval_id,run_id=run_id,admission_id=admission_id,consumer_credential_id='5'*32,request_sha256=request_sha,consumed_at=2), - admission=dict(id=admission_id,catalog_id=self.db.dataset_id,actor_id=actor,credential_id='5'*32,kind='runs',job_id=run_id,request_digest=request_sha, - effects={'runs.update':[run_id]},created_at=2)) - payload_bytes['custody-receipt.json']=receipt_raw - payload_bytes['artifact-manifest.json']=encode(dict(schema_version=1,run_id=run_id,material_sha256=run['material_sha256'],request_sha256=request_sha,custody_receipt_sha256=run['custody_receipt_sha256'],artifacts=inventory)).encode() - for path in recipe_snapshot['capture_paths']:payload_bytes[path['path']]=self.projection.materials.blob(composition['ref'],path['blob']) - edges=[] - for name,raw in payload_bytes.items(): - item=dict(sha256=packages.sha(raw),bytes=len(raw));self.projection.artifacts.publish_bytes(raw,dict(format='project_artifact_v1',**item)) - edges.append(dict(name=name,blob=item,population='unknown',role='authored_fixture',preservation='unique',required_for=['inspection'])) - archived=capture_run(run,admission_proof=proof,payloads=edges) - reservation=dict(id='e'*32,study_id=study_id,admission_epoch=0,request_key='authored-history',actor_id=actor,trial_id=trial_value['id'],parent_run_id=None, - run_id=run_id,request_sha256=request_sha,material_sha256=composition['ref']['sha256'],envelope=envelope_value,state='settled',settled=envelope_value) - study_doc['document']['reservations']=[reservation] - selected=envelope('candidate_history',self.db.dataset_id,decision['id'],dict(format=FAMILY_FORMATS['candidate_history'],origin_catalog_id=self.db.dataset_id,candidate=decision)) - before=self.projection.session.snapshot;records=[r for r in before['records'] if (r['family'],r['id'])!=(study_doc['family'],study_doc['id'])] - merged={(r['family'],r['id']):r for r in [*records,study_doc,archived,*declarations(archived),selected]} - self.projection.validate_records(list(merged.values()));self.store.commit(list(merged.values()),before['checkpoint'],'authored-history-fixture','a'*64) - self.projection.session.adopt(self.store.snapshot());self.adapter.restore_authoring() - # This is the sole scientific-selection substitution. Every package, - # source, custody/input, current disclosure and canonical codec stays real. - with patch.object(self.adapter,'candidate',return_value=candidate): - request=dict(revision=study_doc['document']['study']['revision'],candidate_id=decision['id'],root='fixture',directory='verifier', - runtime_snapshot_sha256=descriptor['manifest_sha256'],package_run_id=run_id,package_sha256=packages.sha(package)) - with self.assertRaisesRegex(WorkbenchError,'disclose'): - self.adapter.prepare_verifier(study_id,request,self.checkpoint(),'verify-without-disclosure') - self.assertFalse((self.source_root/'verifier').exists()) - self.projection.disclose(run_id,dict(origin_catalog_id=self.db.dataset_id,reason='Authored writer qualification'),self.checkpoint(),'disclose-writer-fixture') - # The denied attempt retained an honest intent; use a new key. - writes=[];original_writer=packages._write_project - def write_after_intent(root,files): - receipts=operation_records(self.projection.session.snapshot['records']) - self.assertTrue(any(value['operation']=='study_execution.prepare_verifier_intent' - and value['result']['directory']=='verifier' for value in receipts.values())) - self.assertIn('verify-authored-fixture',self.projection.execution._package_pending) - self.assertFalse((self.source_root/'verifier').exists()) - writes.append(self.checkpoint());return original_writer(root,files) - with patch.object(packages,'_write_project',side_effect=write_after_intent): - if wrapper_loss: - original_mutate=self.adapter._mutate - def lose_wrapper(operation,*args,**kwargs): - if operation=='study_execution.prepare_verifier': - raise OSError('Controlled failure before public wrapper acknowledgement') - return original_mutate(operation,*args,**kwargs) - with patch.object(self.adapter,'_mutate',side_effect=lose_wrapper),self.assertRaisesRegex(OSError,'public wrapper'): - self.adapter.prepare_verifier(study_id,request,self.checkpoint(),'verify-authored-fixture') - else:result=self.adapter.prepare_verifier(study_id,request,self.checkpoint(),'verify-authored-fixture') - self.assertEqual(len(writes),1) - if wrapper_loss: - self.assertTrue(self.projection.custody.has_pending) - self.assertNotIn('verify-authored-fixture',operation_records(self.projection.session.snapshot['records'])) - native=next(value for record in self.projection.session.snapshot['records'] if record['family']=='study_history' - and record['document']['study']['id']==study_id for value in record['document']['operations'] - if value['operation_id']=='studies.prepare_verifier' and value['request_key']=='verify-authored-fixture') - self.assertEqual(native['result']['state'],'prepared') - before=copy.deepcopy(self.projection.session.snapshot) - with self.assertRaisesRegex(WorkbenchError,'complete'): - self.adapter.abandon_preparation(study_id,dict(preparation_key='verify-authored-fixture',reason='Must retain complete science'), - self.checkpoint(),'forbidden-complete-abandon') - self.assertEqual(self.projection.session.snapshot,before) - with patch.object(packages,'_write_project',side_effect=AssertionError('Recovery repeated native filesystem writes')): - result=self.adapter.reconcile_preparation(study_id,dict(preparation_key='verify-authored-fixture'),self.checkpoint()) - self.assertEqual(result,native['result']) - receipt=operation_records(self.projection.session.snapshot['records'])['verify-authored-fixture'] - self.assertEqual(receipt['operation'],'study_execution.prepare_verifier') - self.assertEqual(receipt['result'],native['result']) - self.assertFalse(self.projection.custody.has_pending) - self.assertEqual(self.adapter.prepare_verifier(study_id,request,self.checkpoint(),'verify-authored-fixture'),result) - for table in ('workspace_runs','access_execution_grants','access_admissions','model_attempt_reservations'): - self.assertEqual(self.db.execute('SELECT count(*) FROM '+table).fetchone()[0],0,table) - return - self.assertEqual(result['state'],'prepared');self.assertTrue((self.source_root/'verifier/project.json').is_file()) - receipts=operation_records(self.projection.session.snapshot['records']) - self.assertEqual(receipts['verify-authored-fixture']['operation'],'study_execution.prepare_verifier') - self.assertTrue(validate_operation_result('study_execution.prepare_verifier',result,self.projection.session.snapshot['records'])) - saved=self.projection.session.snapshot - self.assertEqual(self.adapter.prepare_verifier(study_id,request,self.checkpoint(),'verify-authored-fixture'),result) - self.assertEqual(self.projection.session.snapshot,saved) - consumer=self.projection.materials.recipe(result['trial']['material']) - # The actual native reader must consume an archived producer - # through current disclosure, with no live producer SQL row. - self.assertEqual(self.projection.pipelines.recipe_material(result['trial']['material'],verify=True),consumer) - self.projection._disclosures.clear() - with self.assertRaisesRegex(WorkbenchError,'disclose'): - self.projection.pipelines.recipe_material(result['trial']['material'],verify=True) - self.projection.disclose(run_id,dict(origin_catalog_id=self.db.dataset_id,reason='New consumer read permission'), - self.checkpoint(),'disclose-consumer-input') - snapshot=json.loads(self.projection.materials.blob(consumer['ref'],consumer['material']['recipe_document'])) - tampered=copy.deepcopy(snapshot['preflight']['material']) - import base64 - source=tampered['inputs']['package']['source'] - forged=recipe_process.decode(base64.b64decode(source['custody_receipt_base64'])) - forged['reason']='Different self-consistent authored receipt' - forged_raw=recipe_process.encoded(forged) - source['custody_receipt_base64']=base64.b64encode(forged_raw).decode('ascii') - source['custody_receipt_sha256']=packages.sha(forged_raw) - recipe_contract.validate_material(tampered) - with self.assertRaisesRegex(WorkbenchError,'producer proof differs'): - packages.authorize_material_inputs(self.projection.history,tampered) - # The named current execution composition selects the same - # history proof seam; it cannot call a general live resolver. - execution=self.projection.execution - local_reader=SimpleNamespace(project_execution=execution, - _load=lambda _:(_ for _ in ()).throw(AssertionError('Imported producer reached live SQL resolver'))) - execution._runs=local_reader - try:packages.authorize_material_inputs(local_reader,snapshot['preflight']['material']) - finally:execution._runs=None - # A synchronous failure after actual source/graph/model draft - # publication preserves its directory and every canonical phase. - partial=dict(request,revision=self.adapter.studies._study(study_id)['revision'],directory='partial') - with patch.object(self.projection.models,'publish',side_effect=RuntimeError('Controlled partial owner failure')): - with self.assertRaisesRegex(RuntimeError,'partial owner failure'): - self.adapter.prepare_verifier(study_id,partial,self.checkpoint(),'verify-partial') - phases=self.projection.session.snapshot['records'] - self.assertTrue((self.source_root/'partial/project.json').is_file()) - self.assertTrue(self.projection.custody.has_pending) - aborted=self.adapter.abandon_preparation(study_id,dict(preparation_key='verify-partial',reason='Preserve and stop the authored partial writer'), - self.checkpoint(),'abandon-partial') - self.assertEqual(aborted['state'],'abandoned') - self.assertFalse(self.projection.custody.has_pending) - current={(r['family'],r['id']):r for r in self.projection.session.snapshot['records']} - self.assertTrue(all(current[(r['family'],r['id'])]==r for r in phases)) - self.assertTrue((self.source_root/'partial/project.json').is_file()) - # Lose only final journal acknowledgement, after all native and - # canonical commits. Recovery must confirm the existing result. - uncertain=dict(partial,directory='ack-lost') - with patch.object(self.projection.custody,'package_confirmed',side_effect=OSError('Controlled final custody ACK loss')): - with self.assertRaisesRegex(OSError,'custody ACK loss'): - self.adapter.prepare_verifier(study_id,uncertain,self.checkpoint(),'verify-ack-lost') - self.assertFalse(self.projection.session.available) - completed=operation_records(self.projection.session.snapshot['records'])['verify-ack-lost']['result'] - with patch.object(packages,'_write_project',side_effect=AssertionError('Recovery repeated a native writer')): - recovered=self.adapter.reconcile_preparation(study_id,dict(preparation_key='verify-ack-lost'),self.checkpoint()) - self.assertEqual(recovered,completed);self.assertTrue(self.projection.session.available) - self.assertFalse(self.projection.custody.has_pending) - for table in ('workspace_runs','access_execution_grants','access_admissions','model_attempt_reservations'): - self.assertEqual(self.db.execute('SELECT count(*) FROM '+table).fetchone()[0],0,table) - self.assertFalse(self.projection.execution.has_local_custody) - saved=self.projection.session.snapshot - self.projection.close();self.open_projection() - self.assertEqual(self.projection.session.snapshot,saved) - self.assertFalse(self.projection.execution.has_local_custody) - self.assertIn(result['trial']['id'],self.projection.history.study(study_id)['study']['trial_ids']) - self.assertEqual(self.adapter.prepare_verifier(study_id,request,self.checkpoint(),'verify-authored-fixture'),result) - with self.assertRaisesRegex(WorkbenchError,'exact original file writer') as refused: - self.adapter.reconcile_preparation(study_id,dict(preparation_key='verify-ack-lost'),self.checkpoint()) - self.assertEqual(refused.exception.code,'unavailable') - self.assertFalse(self.projection._disclosures) - with self.assertRaisesRegex(WorkbenchError,'disclose'): - self.projection.history.artifact(run_id,'package.zip') - for table in ('workspace_runs','access_execution_grants','access_admissions','model_attempt_reservations','model_operation_receipts'): - self.assertEqual(self.projection.db.execute('SELECT count(*) FROM '+table).fetchone()[0],0,table) diff --git a/tests/test_project_text.py b/tests/test_project_text.py deleted file mode 100644 index 69322b7a..00000000 --- a/tests/test_project_text.py +++ /dev/null @@ -1,419 +0,0 @@ -"""Text-domain acceptance through real PostgreSQL and canonical POSIX files.""" -import copy -import hashlib -import json -from pathlib import Path -import subprocess -import sys -import tempfile -import threading -import unittest -from unittest.mock import patch - -import psycopg -from psycopg import sql - -from access import Access, AccessError -from metadata import Metadata -from project_store import ProjectStore, ProjectStoreError, _encode -from project_text import ProjectText, ProjectTextError, decode_records - - -class ProjectTextTests(unittest.TestCase): - def setUp(self): - self.tmp = tempfile.TemporaryDirectory() - self.addCleanup(self.tmp.cleanup) - self.root = Path(self.tmp.name) - self.host = self.metadata('host') - self.access = Access(self.host, self.host.path) - self.token = self.access.exchange(self.access._local_owner_token())['token'] - self.enterContext(self.access.bind(self.token)) - self.db = self.metadata('projection') - self.store = ProjectStore.create(self.root / 'project', 'Authored text', 'new-project', 'a' * 64) - self.addCleanup(self.store.close) - self.text = ProjectText(self.store, self.db, self.access) - self.text.restore() - - def metadata(self, name): - database = Metadata(self.root / name) - def drop_fixture(): - with psycopg.connect(database.dsn, autocommit=True) as connection: - connection.execute(sql.SQL('DROP SCHEMA {} CASCADE').format(sql.Identifier(database.schema))) - self.addCleanup(drop_fixture) - self.addCleanup(database.close) - return database - - def body(self, source='Hello 😀 cafe\u0301\r\nSecond\rline', **extra): - return dict(text=source, name='Original note', groups=['owned-fixture'], rights='Authored fixture; no grant implied', **extra) - - def import_text(self, source='Hello 😀 cafe\u0301\r\nSecond\rline', key='import-one', **extra): - return self.text.import_text(self.body(source, **extra), self.text.checkpoint, key) - - def annotation(self, row, **extra): - return dict(revision=row['revision'], source_revision=1, task='text_entities', - annotation={'spans': [dict(label='emoji', start=6, end=7)]}, - groups=['owned-fixture', 'reviewed-fixture'], review='human_reviewed', **extra) - - def save_annotation(self, row, key='annotate-one'): - return self.text.annotate(row['id'], self.annotation(row), self.text.checkpoint, key) - - def test_cold_fresh_database_restores_raw_normalized_history_and_inert_facts(self): - source = 'Hello 😀 cafe\u0301\r\nSecond\rline' - row = self.import_text(source) - saved = self.save_annotation(row) - history = self.text.history(row['id']) - snapshot = self.store.snapshot() - doc = snapshot['records'][0]['document'] - self.assertEqual(doc['original_text'], source) - self.assertEqual(saved['text'], 'Hello 😀 café\nSecond\nline') - self.assertEqual(saved['source_sha256'], hashlib.sha256(source.encode()).hexdigest()) - self.assertEqual(saved['content_hash'], hashlib.sha256(saved['text'].encode()).hexdigest()) - self.assertEqual([item['revision'] for item in doc['history']], [1, 2]) - self.assertEqual(doc['audit'][1]['action'], 'workbench.approve_review') - serialized = json.dumps(snapshot) - self.assertNotIn(self.token, serialized) - self.assertNotIn('credential_id', serialized) - self.assertNotIn('access_credentials', serialized) - self.store.save(self.text.checkpoint) - self.store.close() - self.db.close() - # A new installation grants its own current permission; old audit facts - # neither create credentials nor require the old installation to exist. - new_host = self.metadata('other-host') - new_access = Access(new_host, new_host.path) - token = new_access.exchange(new_access._local_owner_token())['token'] - fresh = self.metadata('fresh-projection') - reopened = ProjectStore.open(self.root / 'project') - self.addCleanup(reopened.close) - cold = ProjectText(reopened, fresh, new_access) - cold.restore() - with new_access.bind(token): - actual = cold.get(row['id']) - self.assertEqual({k: v for k, v in saved.items() if k != 'request_key'}, actual) - self.assertEqual(history, cold.history(row['id'])) - self.assertEqual(cold.query({'q': 'emoji'})['total'], 1) - self.assertEqual(reopened.save(cold.checkpoint), snapshot) - self.assertEqual(fresh.execute('SELECT count(*) FROM access_credentials').fetchone()[0], 0) - self.assertEqual(fresh.execute('SELECT original_text FROM workbench_records').fetchone()[0], source) - - def test_retry_returns_original_target_revision_before_stale_precondition(self): - before = self.text.checkpoint - body = self.body() - row = self.text.import_text(body, before, 'import-one') - self.save_annotation(row) - checkpoint = self.text.checkpoint - replay = self.text.import_text(body, before, 'import-one') - self.assertEqual((replay['id'], replay['revision']), (row['id'], 1)) - self.assertEqual(replay['checkpoint'], checkpoint) - self.assertEqual(self.text.query()['total'], 1) - self.assertEqual(len(self.text.history(row['id'])), 2) - with self.assertRaises(ProjectStoreError) as failure: - self.text.import_text(self.body('different'), before, 'import-one') - self.assertEqual(failure.exception.code, 'conflict') - self.assertEqual(self.text.checkpoint, checkpoint) - - def test_parent_lineage_and_annotation_replay_survive_restore(self): - parent = self.import_text() - child = self.import_text('A distinct child', key='import-child', parents=[parent['id']]) - body = dict(revision=1, source_revision=1, task='text_corpus', annotation={'note': 'Deliberate corpus review'}, - groups=child['groups'], review='human_reviewed') - before = self.text.checkpoint - reviewed = self.text.annotate(child['id'], body, before, 'review-child') - self.text.restore() - replay = self.text.annotate(child['id'], body, before, 'review-child') - self.assertEqual(reviewed, replay) - self.assertEqual(self.text.get(child['id'])['parents'], [parent['id']]) - - def test_unavailable_operations_and_invalid_annotation_have_no_effects(self): - row = self.import_text() - before = self.store.snapshot() - cases = [lambda: self.text.import_text(dict(kind='image', image='not decoded'), self.text.checkpoint, 'image'), - lambda: self.text.annotate(row['id'], dict(self.annotation(row), review='programmatically_verified'), self.text.checkpoint, 'verify'), - lambda: self.text.annotate(row['id'], dict(self.annotation(row), task='image_detection'), self.text.checkpoint, 'image-task'), - lambda: self.text.annotate(row['id'], dict(self.annotation(row), annotation={'spans': [dict(label='bad', start=True, end=7)]}), self.text.checkpoint, 'invalid-span')] - for action in cases: - with self.subTest(action=action), self.assertRaises(ProjectTextError if action != cases[-1] else ValueError): - action() - self.assertEqual(self.store.snapshot(), before) - self.assertEqual(self.text.get(row['id'])['revision'], 1) - self.assertFalse(hasattr(self.text, 'import_asset')) - self.assertFalse(hasattr(self.text, 'preferences')) - - def test_expected_checkpoint_and_record_revision_reject_without_publish(self): - checkpoint = self.text.checkpoint - row = self.import_text() - before = self.store.snapshot() - with self.assertRaises(ProjectTextError): - self.text.import_text(self.body('another'), checkpoint, 'stale-project') - self.save_annotation(row) - current = self.store.snapshot() - with self.assertRaises(ValueError): - self.text.annotate(row['id'], self.annotation(row), self.text.checkpoint, 'stale-record') - self.assertEqual(self.store.snapshot(), current) - self.assertNotEqual(current, before) - - def test_file_publication_failure_rolls_back_actual_sql(self): - before = self.store.snapshot() - with patch.object(self.store, '_publish', side_effect=ProjectStoreError('fixture unavailable', 'unavailable', 503)): - with self.assertRaises(ProjectStoreError): - self.import_text() - self.assertEqual(self.store.snapshot(), before) - self.assertEqual(self.db.execute('SELECT count(*) FROM workbench_records').fetchone()[0], 0) - self.assertEqual(self.db.execute('SELECT count(*) FROM workbench_history').fetchone()[0], 0) - self.assertEqual(self.text.query()['total'], 0) - - def test_real_postgres_commit_failure_retains_canonical_success_and_rebuilds(self): - # Deferred trigger fails at the actual outer PostgreSQL COMMIT, after - # canonical file publication, rather than replacing the DB adapter. - self.db.execute("""CREATE FUNCTION fixture_refuse_commit() RETURNS trigger LANGUAGE plpgsql AS $$ - BEGIN RAISE EXCEPTION 'fixture deferred rejection' USING ERRCODE='23514'; END $$""") - self.db.execute('''CREATE CONSTRAINT TRIGGER fixture_commit_failure AFTER INSERT ON workbench_records - DEFERRABLE INITIALLY DEFERRED FOR EACH ROW EXECUTE FUNCTION fixture_refuse_commit()''') - with self.assertRaises(ProjectTextError) as failure: - self.import_text() - self.assertEqual(failure.exception.code, 'projection_unavailable') - self.assertTrue(failure.exception.committed) - snapshot = self.store.snapshot() - self.assertEqual(failure.exception.receipt, dict(committed=True, selected=True, - project_id=snapshot['project_id'], checkpoint=snapshot['checkpoint'], request_key='import-one')) - self.assertEqual(len(snapshot['records']), 1) - self.assertFalse(self.text.available) - self.assertEqual(self.db.execute('SELECT count(*) FROM workbench_records').fetchone()[0], 0) - with self.assertRaises(ProjectTextError): - self.text.query() - self.db.execute('DROP TRIGGER fixture_commit_failure ON workbench_records') - self.text.restore() - replay = self.text.import_text(self.body(), '0' * 64, 'import-one') - self.assertEqual(replay['id'], snapshot['records'][0]['id']) - self.assertEqual(self.text.query()['total'], 1) - - def test_external_checkpoint_and_immutable_byte_edits_fence_reads_and_writes(self): - row = self.import_text() - manifest_path = self.root / 'project' / '.tuldok' / 'project.json' - original = manifest_path.read_bytes() - manifest = json.loads(original) - manifest['name'] = 'External checkout' - del manifest['checkpoint'] - manifest['checkpoint'] = hashlib.sha256(_encode(manifest)).hexdigest() - manifest_path.write_bytes(_encode(manifest)) - for action in (lambda: self.text.query(), lambda: self.text.get(row['id']), - lambda: self.text.history(row['id']), lambda: self.import_text('another', key='drift')): - with self.assertRaises(ProjectStoreError) as failure: - action() - self.assertEqual(failure.exception.code, 'stale') - self.assertEqual(self.db.execute('SELECT count(*) FROM workbench_records').fetchone()[0], 1) - manifest_path.write_bytes(original) - manifest = json.loads(original) - record_path = self.root / 'project' / '.tuldok' / manifest['inventory'][0]['path'] - record_path.write_text('{}') - with self.assertRaises(ProjectStoreError): - self.text.query() - with self.assertRaises(ProjectStoreError): - self.import_text('another', key='corrupt') - - def test_cold_decoder_rejects_corrupt_semantics_before_any_projection_write(self): - row = self.import_text() - original = self.store.snapshot()['records'] - mutations = { - 'extra credential': lambda d: d.update(access_credentials=[]), - 'missing source bytes': lambda d: d.pop('original_text'), - 'changed raw source': lambda d: d.update(original_text='forged'), - 'normalized hash': lambda d: d['history'][0].update(content_hash='f' * 64), - 'noninteger revision': lambda d: d['current'].update(revision=True), - 'future task': lambda d: d['history'][0].update(task='text_future'), - 'missing history': lambda d: d.update(history=[]), - 'missing audit': lambda d: d.update(audit=[]), - 'credential in fact': lambda d: d['audit'][0].update(credential_id='1' * 32), - 'forged review': lambda d: d['history'][0].update(review='programmatically_verified'), - 'broken parent': lambda d: d['history'][0].update(parents=['1' * 32]), - 'foreign target': lambda d: d['operations'][0].update(target='1' * 32), - } - for label, mutate in mutations.items(): - with self.subTest(label=label): - records = copy.deepcopy(original) - mutate(records[0]['document']) - if label == 'broken parent': - records[0]['document']['current']['parents'] = ['1' * 32] - before = self.db.execute('SELECT snapshot FROM workbench_history').fetchone()[0] - key = label.replace(' ', '-') - self.store.commit(records, self.store.snapshot()['checkpoint'], 'bad-' + key, hashlib.sha256(label.encode()).hexdigest()) - with self.assertRaises(ValueError): - self.text.restore() - self.assertEqual(self.db.execute('SELECT snapshot FROM workbench_history').fetchone()[0], before) - self.store.commit(original, self.store.snapshot()['checkpoint'], 'repair-' + key, hashlib.sha256(('repair' + label).encode()).hexdigest()) - self.assertEqual(self.db.execute('SELECT count(*) FROM workbench_records').fetchone()[0], 1) - - def test_decoder_rejects_unknown_formats_families_and_validly_hashed_broken_lineage(self): - row = self.import_text() - original = self.store.snapshot()['records'] - for field, value in [('family', 'future_family'), ('format', 'workbench_text_v2')]: - records = copy.deepcopy(original) - if field == 'family': - records[0][field] = value - else: - records[0]['document'][field] = value - with self.assertRaises(ProjectTextError) as failure: - decode_records(records) - self.assertEqual(failure.exception.code, 'unsupported') - from workbench import encode - for parent, message in [('1' * 32, 'missing'), (row['id'], 'cycle')]: - records = copy.deepcopy(original) - doc = records[0]['document'] - doc['current']['parents'] = [parent] - doc['history'][0]['parents'] = [parent] - doc['audit'][0]['details']['content_sha256'] = hashlib.sha256(encode(doc['history'][0]).encode()).hexdigest() - with self.assertRaisesRegex(ProjectTextError, message): - decode_records(records) - - def test_anonymous_current_access_is_not_granted_by_imported_history(self): - row = self.import_text() - unrelated_host = self.metadata('unrelated-host') - access = Access(unrelated_host, unrelated_host.path) - reader = ProjectText(self.store, self.db, access) - reader.restore() - # Current context is bound to the original host, not this installation. - with self.assertRaises(AccessError): - reader.get(row['id']) - self.assertEqual(unrelated_host.execute('SELECT count(*) FROM access_credentials').fetchone()[0], 0) - - def test_scoped_agent_draft_edits_and_reads_keep_owner_review_authority(self): - credential = self.access.issue(dict(label='Project fixture agent', scopes=['inspect', 'edit'])) - with self.access.bind(credential['token']): - row = self.import_text() - body = dict(self.annotation(row), review='draft') - updated = self.text.annotate(row['id'], body, self.text.checkpoint, 'agent-draft') - self.assertEqual(updated['revision'], 2) - self.assertEqual(self.text.get(row['id'])['annotation'], body['annotation']) - self.assertEqual(self.text.query()['total'], 1) - self.assertEqual(len(self.text.records()['items']), 1) - self.assertEqual(len(self.text.history(row['id'])), 2) - before = self.store.snapshot() - with self.assertRaises(AccessError): - self.text.annotate(row['id'], self.annotation(updated), self.text.checkpoint, 'agent-approval') - self.assertEqual(self.store.snapshot(), before) - portable = json.dumps(self.store.snapshot()) - self.assertNotIn(credential['token'], portable) - self.assertNotIn('credential_id', portable) - inspection = self.access.issue(dict(label='Read-only fixture agent', scopes=['inspect'])) - with self.access.bind(inspection['token']): - self.assertEqual(self.text.get(row['id'])['revision'], 2) - with self.assertRaises(AccessError): - self.import_text('Read only cannot import', key='read-only-write') - self.assertEqual(self.store.snapshot(), before) - - def test_no_dataset_or_recovery_owner_is_constructed(self): - with patch('app.Dataset', side_effect=AssertionError('Dataset must remain absent')): - fresh = ProjectText(self.store, self.db, self.access) - fresh.restore() - row = fresh.import_text(self.body(), fresh.checkpoint, 'inert-import') - self.assertEqual(fresh.get(row['id'])['revision'], 1) - self.assertEqual(self.db.execute('SELECT count(*) FROM workspace_runs').fetchone()[0], 0) - - def test_nested_caller_transaction_cannot_acknowledge_before_outer_commit(self): - before = self.store.snapshot() - with self.db.transaction(): - with self.assertRaises(ProjectTextError): - self.import_text() - self.assertEqual(self.store.snapshot(), before) - - def test_current_owner_revocation_waits_for_canonical_publication(self): - credential_id = self.access.require('edit', 'workbench.import_asset').credential_id - administrator = self.access.exchange(self.access._local_owner_token())['token'] - at_publication, proceed, revocation_attempt = threading.Event(), threading.Event(), threading.Event() - outcomes, failures = [], [] - original_commit = self.store.commit - def commit(*args, **kwargs): - at_publication.set() - if not proceed.wait(5): - raise AssertionError('Publication fixture timed out') - result = original_commit(*args, **kwargs) - outcomes.append('canonical') - return result - def mutate(): - try: - with self.access.bind(self.token): - self.import_text() - except BaseException as error: - failures.append(error) - def revoke(): - try: - revocation_attempt.set() - with self.access.bind(administrator): - self.access.revoke(credential_id) - outcomes.append('revoked') - except BaseException as error: - failures.append(error) - writer, revoker = threading.Thread(target=mutate), threading.Thread(target=revoke) - with patch.object(self.store, 'commit', side_effect=commit): - writer.start() - try: - self.assertTrue(at_publication.wait(5)) - revoker.start() - self.assertTrue(revocation_attempt.wait(5)) - acquired = self.access.lock.mutex.acquire(blocking=False) - if acquired: - self.access.lock.mutex.release() - self.assertFalse(acquired, 'Host authority must stay locked through canonical publication') - finally: - proceed.set() - writer.join(5) - if revoker.ident is not None: - revoker.join(5) - self.assertFalse(writer.is_alive()) - self.assertFalse(revoker.is_alive()) - self.assertEqual(failures, []) - self.assertEqual(outcomes, ['canonical', 'revoked']) - with self.assertRaises(AccessError): - self.text.query() - with self.access.bind(administrator): - self.assertEqual(len(self.text.records()['items']), 1) - - def test_full_current_records_include_text_without_query_pagination(self): - first = self.import_text() - second = self.import_text('Another complete text', key='second') - full = self.text.records() - self.assertEqual(full['checkpoint'], self.text.checkpoint) - self.assertEqual({row['id'] for row in full['items']}, {first['id'], second['id']}) - self.assertEqual({row['text'] for row in full['items']}, {first['text'], second['text']}) - self.assertNotIn('text', self.text.query({'limit': 1})['items'][0]) - - def test_lost_canonical_publication_reply_requires_reopen_and_reconciles(self): - publish = self.store._publish - def publish_then_lose_reply(*args, **kwargs): - publish(*args, **kwargs) - raise ProjectStoreError('Fixture lost publication reply.', 'unknown', 503) - with patch.object(self.store, '_publish', side_effect=publish_then_lose_reply): - with self.assertRaises(ProjectStoreError) as failure: - self.import_text() - self.assertEqual(failure.exception.code, 'unknown') - self.assertFalse(self.text.available) - self.assertEqual(self.db.execute('SELECT count(*) FROM workbench_records').fetchone()[0], 0) - self.store.close() - reopened = ProjectStore.open(self.root / 'project') - self.addCleanup(reopened.close) - restored = ProjectText(reopened, self.db, self.access) - restored.restore() - replay = restored.import_text(self.body(), '0' * 64, 'import-one') - self.assertEqual(replay['id'], reopened.snapshot()['records'][0]['id']) - self.assertEqual(len(restored.records()['items']), 1) - - def test_closed_process_opens_files_without_old_projection(self): - row = self.import_text() - self.save_annotation(row) - expected = self.store.snapshot() - self.store.close() - script = ''' -import json,sys -from project_store import ProjectStore -from project_text import decode_records -with ProjectStore.open(sys.argv[1]) as store: - snapshot=store.snapshot() - decode_records(snapshot['records']) - print(json.dumps(snapshot,ensure_ascii=False,sort_keys=True)) -''' - result = subprocess.run([sys.executable, '-c', script, str(self.root / 'project')], capture_output=True, text=True, check=True) - self.assertEqual(json.loads(result.stdout), expected) - - -if __name__ == '__main__': - unittest.main() diff --git a/tests/test_project_text_tag.py b/tests/test_project_text_tag.py deleted file mode 100644 index 6a944aa6..00000000 --- a/tests/test_project_text_tag.py +++ /dev/null @@ -1,52 +0,0 @@ -"""The scalar text response tag must not copy unrelated project metadata.""" -from types import SimpleNamespace -import unittest -from unittest.mock import patch - -import project_fork - -from project_projection import _TextView - - -class TextTagTests(unittest.TestCase): - def test_text_records_does_not_clone_unrelated_active_documents(self): - unrelated = dict(family='project_artifact', id='c' * 64, - document=dict(format='project_artifact_v1', sha256='c' * 64, bytes=4)) - note = dict(family='workbench_text', id='d' * 32, - document=dict(current=dict(kind='text', text='Unique note 山'))) - summary = dict(project_id='a' * 32, checkpoint='b' * 64) - session = SimpleNamespace(summary=summary, - snapshot=dict(summary, records=[unrelated, note]), - check_current=lambda: None) - copied = [] - original = project_fork.copy.deepcopy - - def observe(value): - if value is unrelated: - copied.append(value['id']) - return original(value) - - with patch.object(project_fork, 'copy', SimpleNamespace(deepcopy=observe)): - result = _TextView(SimpleNamespace(session=session)).records() - self.assertEqual(result, dict(summary, items=[dict(kind='text', text='Unique note 山')])) - self.assertEqual(copied, [], 'Text list cloned an unrelated active document') - result['items'][0]['text'] = 'Caller mutation' - self.assertEqual(note['document']['current']['text'], 'Unique note 山') - - def test_text_tag_reads_scalar_summary_without_a_record_snapshot(self): - class Session: - summary = dict(project_id='a' * 32, name='Owned project', checkpoint='b' * 64) - - @property - def snapshot(self): - raise AssertionError('Text response tag copied the full record graph') - - session = Session() - view = _TextView(SimpleNamespace(session=session)) - original = dict(items=[dict(text='Authored note 漢字')]) - result = view._tag(original) - self.assertEqual(result, dict(original, project_id='a' * 32, checkpoint='b' * 64)) - self.assertNotIn('name', result) - self.assertEqual(original, dict(items=[dict(text='Authored note 漢字')])) - result['project_id'] = 'caller edit' - self.assertEqual(session.summary['project_id'], 'a' * 32) diff --git a/tests/test_project_transfer.py b/tests/test_project_transfer.py deleted file mode 100644 index 5b798960..00000000 --- a/tests/test_project_transfer.py +++ /dev/null @@ -1,533 +0,0 @@ -"""M5 explicit cessation, readonly capture and atomic extraction on disposable PG.""" -import copy -import hashlib -import http.client -from http.server import ThreadingHTTPServer -import json -import os -from pathlib import Path -import tempfile -import threading -import time -from types import SimpleNamespace -import unittest -from unittest.mock import patch -import uuid - -import psycopg -from psycopg import sql -from app import Dataset, make_handler -from backup_metadata import tree_manifest -from project_store import ProjectStore, ProjectStoreError -from project_transfer import (ProjectTransfer, StoppedSourceLease, preview_source, - stop_source, decode_records, _assert_unchanged) -from workbench import WorkbenchError - - -@unittest.skipUnless(os.environ.get('TULDOK_DATABASE_URL'),'Requires disposable PostgreSQL') -class ProjectTransferTests(unittest.TestCase): - def setUp(self): - self.temporary=tempfile.TemporaryDirectory(prefix='tuldok-transfer-fixture-') - self.addCleanup(self.temporary.cleanup) - self.root=Path(self.temporary.name) - self.project_root=self.root/'registered';self.project_root.mkdir() - self.dataset=Dataset(self.root/'legacy',project_roots={'fixture':self.project_root}) - self.addCleanup(self.cleanup) - exchange=self.dataset.access.exchange(self.dataset.access._local_owner_token()) - self.token,self.actor=exchange['token'],exchange['identity']['actor_id'] - self.enterContext(self.dataset.access.bind(self.token)) - self.manifest=dict(schema_version=1,id=uuid.uuid4().hex,name='Exact chosen source λ',data=[],recipes=[],evidence=[],requirements=[]) - self.raw_manifest=(json.dumps(self.manifest,ensure_ascii=False,indent=3)+'\n\n').encode() - (self.project_root/'source.json').write_bytes(self.raw_manifest) - self.dataset.projects.register_snapshot(dict(root='fixture',manifest_path='source.json')) - self.selection=dict(project_snapshot=dict(id=self.manifest['id'],manifest_sha256=hashlib.sha256(self.raw_manifest).hexdigest()),roots={},decisions=[]) - self.parent_fd=os.open(self.root,os.O_RDONLY|os.O_DIRECTORY);self.addCleanup(os.close,self.parent_fd) - self.leases=[] - def cleanup(self): - for source in self.leases:source.close() - self.dataset.close() - with psycopg.connect(self.dataset.db.dsn,autocommit=True) as connection: - connection.execute(sql.SQL('DROP SCHEMA {} CASCADE').format(sql.Identifier(self.dataset.db.schema))) - def text(self,value='Exact original e\u0301\r\nλ'): - return self.dataset.workbench.import_asset(dict(kind='text',name='Authored unique source',text=value,groups=['shared-fixture'],parents=[],rights='Fixture permission')) - def stop(self): - source=self.dataset.stop_for_project_extraction(self.parent_fd,'verified-backup');self.leases.append(source);return source - def test_preview_readonly_no_constructor_no_stop_and_explicit_unassigned(self): - selected=self.text();other=self.text('Unassigned unique source') - self.selection['roots']['records']=[selected['id']] - before=tree_manifest(self.dataset.path) - with preview_source(self.dataset) as source: - with patch('metadata.Metadata.__init__',side_effect=AssertionError('preview initialized Metadata')), \ - patch('synthetic.Jobs.__init__',side_effect=AssertionError('preview constructed Jobs')), \ - patch('runs.Runs.__init__',side_effect=AssertionError('preview constructed Runs')): - report=ProjectTransfer(source).preview(self.selection) - self.assertFalse(report['can_extract']) - self.assertEqual([b['code'] for b in report['blockers']],['cessation_proof_unavailable']) - self.assertIn(dict(family='workbench_record',id=other['id'],revision=1),report['unassigned']) - self.assertEqual(source.db.execute("SELECT current_setting('transaction_read_only')").fetchone()[0],'on') - with self.assertRaises(psycopg.errors.ReadOnlySqlTransaction):source.db.execute('DELETE FROM workbench_records') - self.assertEqual(before,tree_manifest(self.dataset.path)) - self.assertFalse(self.dataset._extraction_stopping) - def test_actual_stop_backup_is_private_verified_and_source_unchanged(self): - self.text();source=self.stop() - self.assertIs(type(source),StoppedSourceLease) - self.assertTrue(self.dataset._closed) - self.assertEqual(tree_manifest(self.dataset.path),source.backup_receipt['files']) - self.assertEqual(tree_manifest(self.root/'verified-backup'/'catalog'),source.backup_receipt['files']) - self.assertTrue((self.root/'verified-backup'/'metadata.json').exists()) - _assert_unchanged(source) - with self.assertRaises(WorkbenchError): - with self.dataset._project_request():pass - with self.assertRaises(WorkbenchError):self.dataset.stop_for_project_extraction(self.parent_fd,'retry-backup') - - def test_native_stop_backup_deduplicates_copies_without_linking_originals(self): - original=[self.dataset.path/name for name in ('duplicate-a.bin','duplicate-b.bin')] - for path in original:path.write_bytes(b'Exact original payload' * 1000) - before=[(p.stat().st_ino,p.stat().st_ctime_ns,p.stat().st_nlink) for p in original] - source=self.stop() - copied=[self.root/'verified-backup/catalog'/p.name for p in original] - self.assertEqual(copied[0].stat().st_ino,copied[1].stat().st_ino) - self.assertTrue(all(p.stat().st_ino!=c.stat().st_ino for p,c in zip(original,copied))) - self.assertEqual(before,[(p.stat().st_ino,p.stat().st_ctime_ns,p.stat().st_nlink) for p in original]) - self.assertEqual(tree_manifest(self.root/'verified-backup/catalog'),source.backup_receipt['files']) - _assert_unchanged(source) - - def test_live_preview_reports_domain_refusal_before_source_stop(self): - from project_projection import ProjectProjection - record=self.text();self.selection['roots']['records']=[record['id']] - before=tree_manifest(self.dataset.path) - # Controlled downstream domain refusal: callers must see it while the - # source is still live, without stopping just to discover the failure. - with preview_source(self.dataset) as source,patch.object(ProjectProjection,'validate_records', - side_effect=WorkbenchError('Selected retained composition is incompatible.','invalid',409)): - report=ProjectTransfer(source).preview(self.selection) - self.assertFalse(report['can_extract']) - self.assertIn(dict(family='closure',id=self.dataset.db.dataset_id,code='invalid', - detail='Selected retained composition is incompatible.'),report['blockers']) - self.assertTrue(any(row['code']=='cessation_proof_unavailable' for row in report['blockers'])) - self.assertFalse(self.dataset._extraction_stopping) - self.assertFalse(self.dataset._closed) - self.assertEqual(tree_manifest(self.dataset.path),before) - def test_json_bool_and_fake_controller_guards_never_stop(self): - for guard in (True,{},SimpleNamespace(require=lambda _:None)): - with self.assertRaises(WorkbenchError) as caught: - stop_source(self.dataset,backup_parent_fd=self.parent_fd,backup_directory='forged',controller_guard=guard) - self.assertEqual(caught.exception.code,'forbidden') - with self.assertRaises(WorkbenchError):StoppedSourceLease(None,None,None,None) - with preview_source(self.dataset) as forged: - forged.backup_receipt={} - forged.__class__=StoppedSourceLease - with self.assertRaises(WorkbenchError):forged.require() - with self.assertRaises(WorkbenchError):ProjectTransfer(forged).extract(self.selection,'0'*64,self.parent_fd,'forged','No forged authority','forged-key') - self.assertFalse(self.dataset._closed) - self.assertFalse((self.root/'forged').exists()) - def test_unknown_custody_and_peer_ownership_cannot_mint_lease(self): - self.dataset.runs._blocked=True - with self.assertRaises(WorkbenchError) as caught:self.stop() - self.assertEqual(caught.exception.code,'unknown') - self.assertFalse((self.root/'verified-backup').exists()) - self.assertFalse(self.dataset._closed) - self.dataset.runs._blocked=False - def test_peer_lock_handoff_after_close_refuses_lease(self): - from metadata import _key - peer=psycopg.connect(self.dataset.db.dsn,autocommit=True);self.addCleanup(peer.close) - original=self.dataset.close - def close_and_claim(): - original() - self.assertTrue(peer.execute('SELECT pg_try_advisory_lock(%s)',(_key(self.dataset.db.schema+':worker:generation_jobs'),)).fetchone()[0]) - with patch.object(self.dataset,'close',side_effect=close_and_claim),self.assertRaises(WorkbenchError) as caught:self.stop() - self.assertEqual(caught.exception.code,'busy') - self.assertFalse((self.root/'verified-backup').exists()) - def test_stopped_source_sql_and_external_byte_changes_are_detected(self): - record=self.text();source=self.stop() - source.read_root('fixture','source.json') - with psycopg.connect(source.db.dsn,autocommit=True) as connection: - connection.execute(sql.SQL('UPDATE {}.workbench_records SET name=%s WHERE id=%s').format(sql.Identifier(source.db.schema)),('bypass attempt',record['id'])) - with self.assertRaises(WorkbenchError) as caught:_assert_unchanged(source) - self.assertEqual(caught.exception.code,'stale_source') - def test_registered_source_change_blocks_before_publication(self): - self.text();source=self.stop();source.read_root('fixture','source.json') - (self.project_root/'source.json').write_bytes(self.raw_manifest+b' ') - with self.assertRaises(WorkbenchError) as caught:_assert_unchanged(source) - self.assertEqual(caught.exception.code,'stale_source') - self.assertFalse((self.root/'extracted').exists()) - def test_handler_inflight_is_drained_then_new_requests_are_fenced(self): - entered=threading.Event();release=threading.Event();errors=[] - handler=make_handler(self.dataset) - original=handler._handle_GET - # The actual HTTP gate in _observe_request surrounds this handler body. - def blocked_get(request): - entered.set();release.wait(5);return original(request) - handler._handle_GET=blocked_get - server=ThreadingHTTPServer(('127.0.0.1',0),handler) - thread=threading.Thread(target=server.serve_forever,daemon=True);thread.start() - self.addCleanup(server.server_close);self.addCleanup(server.shutdown) - def request(): - try: - connection=http.client.HTTPConnection(*server.server_address,timeout=10) - connection.request('GET','/');response=connection.getresponse();response.read();connection.close() - except BaseException as error:errors.append(error) - client=threading.Thread(target=request);client.start();self.assertTrue(entered.wait(5)) - def stop(): - try: - with self.dataset.access.bind(self.token):self.leases.append(self.dataset.stop_for_project_extraction(self.parent_fd,'verified-backup')) - except BaseException as error:errors.append(error) - stopper=threading.Thread(target=stop);stopper.start();time.sleep(.1) - # If do_GET replacement was outside the gate this proves nothing; inspect - # the real gate state before releasing the in-flight HTTP operation. - self.assertTrue(self.dataset._extraction_stopping) - self.assertTrue(stopper.is_alive()) - release.set();client.join(10);stopper.join(20) - self.assertFalse(stopper.is_alive());self.assertEqual(errors,[]) - connection=http.client.HTTPConnection(*server.server_address,timeout=10) - connection.request('GET','/');response=connection.getresponse();response.read();connection.close() - self.assertEqual(response.status,409) - def test_selected_text_working_file_material_extract_replay_and_cold_rebuild(self): - row=self.text();unrelated=self.text('Keep unrelated global data unassigned') - script=b'raise AssertionError("extraction must never run me")\n' - (self.project_root/'scripts').mkdir();(self.project_root/'scripts'/'neutral.py').write_bytes(script) - self.selection['roots'].update(records=[row['id']],working_files=[dict(kind='script',path='scripts/neutral.py')]) - source=self.stop();baseline=tree_manifest(self.dataset.path);transfer=ProjectTransfer(source) - report=transfer.preview(self.selection) - self.assertTrue(report['can_extract'],report['blockers']) - self.assertTrue(any(item['id']==unrelated['id'] for item in report['unassigned'])) - receipt=transfer.extract(self.selection,report['report_sha256'],self.parent_fd,'extracted','New portable project','extract-once') - self.assertTrue(receipt['committed']);self.assertFalse(receipt['selected']) - self.assertEqual(receipt['verification']['active_data_records'],1) - with ProjectStore.open(self.root/'extracted') as store: - snapshot=store.snapshot();decode_records(snapshot['records']) - self.assertNotEqual(snapshot['project_id'],source.db.dataset_id) - active=[r for r in snapshot['records'] if r['family']=='workbench_record' and r['document']['current']['id']!=row['id']] - self.assertEqual(len(active),1) - self.assertEqual(active[0]['document']['source']['original_text'],'Exact original e\u0301\r\nλ') - self.assertEqual((store.path/'scripts'/'neutral.py').read_bytes(),script) - self.assertFalse(any(r['family'].startswith('access_') for r in snapshot['records'])) - # Actual ordinary Open under a different installation, with fresh - # physical SQL and current host authority, remains inert. - from access import Access - from metadata import Metadata - from project_projection import ProjectProjection - host=Metadata(self.root/'new-installation') - projected=Metadata(self.root/'cold-projection',dataset_id=snapshot['project_id'],projection_id=uuid.uuid4().hex) - projection=None - try: - authority=Access(host,host.path);token=authority.exchange(authority._local_owner_token())['token'] - with authority.bind(token),patch('runs.Runs.__init__',side_effect=AssertionError('Open started Runs')),patch('synthetic.Jobs.__init__',side_effect=AssertionError('Open started Jobs')): - projection=ProjectProjection(store,projected,authority,{}) - self.assertEqual(projection.data.get(active[0]['id']),active[0]['document']['current']) - for table in ('access_actors','access_credentials','access_admissions','access_execution_grants','workspace_runs'): - self.assertEqual(projected.execute('SELECT count(*) FROM '+table).fetchone()[0],0) - self.assertEqual(store.snapshot(),snapshot) - finally: - if projection is not None:projection.close() - else:projected.close() - host.close() - with psycopg.connect(source.db.dsn,autocommit=True) as cleanup: - for database in (projected,host):cleanup.execute(sql.SQL('DROP SCHEMA {} CASCADE').format(sql.Identifier(database.schema))) - replay=transfer.extract(self.selection,report['report_sha256'],self.parent_fd,'extracted','New portable project','extract-once') - self.assertEqual({k:v for k,v in replay.items() if k!='replayed'},{k:v for k,v in receipt.items() if k!='replayed'}) - self.assertTrue(replay['replayed']) - self.assertEqual(baseline,tree_manifest(self.dataset.path));_assert_unchanged(source) - with self.assertRaises(ProjectStoreError):transfer.extract(self.selection,report['report_sha256'],self.parent_fd,'extracted','Changed name','extract-once') - - def test_response_preference_model_study_shared_closure_is_exact(self): - from test_project_history import policy - parent=self.text();unrelated=self.text('Unassigned other project source') - answers=[] - for completion in ('Unique first answer\r\n','Unique second answer λ'): - answers.append(self.dataset.workbench.save_response(dict(id=uuid.uuid4().hex,prompt_id=parent['id'],revision=0, - parent_revision=1,source_revision=1,completion=completion,review='draft'))['response']) - judgment=self.dataset.workbench.preferences.save(dict(id=uuid.uuid4().hex,prompt_id=parent['id'],parent_revision=1,source_revision=1, - left_id=answers[0]['id'],left_revision=1,right_id=answers[1]['id'],right_revision=1,revision=0, - outcome='left',rationale='Exact authored distinction',review='human_reviewed'))['judgment'] - model=self.dataset.models.create(dict(name='Original model metadata',task=dict(kind='task',catalog_id=self.dataset.db.dataset_id, - id='neutral',revision=1,sha256='b'*64),kind='template',specification={'unique':'λ'},source_selector=None,preprocessing_policy={},output_policy={})) - changed=copy.deepcopy(model);changed['name']='Renamed observed metadata' - model=self.dataset.models.save(model['id'],dict(revision=1,document=changed)) - study=self.dataset.studies.create(dict(name='Chosen actual scientific intent',limits=dict(attempt_slots=2,admitted_wall_seconds=100, - retained_bytes=10000,peak_staging_bytes=10000),policy=policy())) - self.selection['roots'].update(preferences=[judgment['id']],model_definitions=[model['id']],studies=[study['id']]) - source=self.stop();transfer=ProjectTransfer(source);report=transfer.preview(self.selection) - self.assertTrue(report['can_extract'],report['blockers']) - required={(v['family'],v['id']) for v in report['required']} - self.assertIn(('workbench_record',parent['id']),required) - self.assertIn(('workbench_response',answers[0]['id']),required) - self.assertTrue(any(v['id']==unrelated['id'] for v in report['unassigned'])) - self.assertTrue(any(v['code']=='observed_history_incomplete' for v in report['warnings'])) - baseline=tree_manifest(self.dataset.path) - receipt=transfer.extract(self.selection,report['report_sha256'],self.parent_fd,'closure','Closure destination','closure-key') - with ProjectStore.open(self.root/'closure') as store: - records=store.snapshot()['records'];fork=next(r['document'] for r in records if r['family']=='project_fork') - self.assertEqual(next(r['document']['current'] for r in records if r['family']=='workbench_preference' and r['id']==judgment['id']),judgment) - fresh=next(r['document']['current'] for r in records if r['family']=='workbench_preference' and r['id']!=judgment['id']) - self.assertEqual((fresh['review'],fresh['revision']),('draft',1)) - self.assertIn(dict(family='workbench_response',id=answers[0]['id']),fork['archived']) - kept=next(r['document']['current'] for r in records if r['family']=='model_definition' and r['id'].startswith(source.db.dataset_id+'.')) - self.assertEqual(kept,model) - saved_study=next(r['document']['study'] for r in records if r['family']=='study_history') - self.assertEqual(saved_study,study) - self.assertFalse(any(r['family'].startswith('access_') for r in records)) - bad=copy.deepcopy(records);next(r['document'] for r in bad if r['family']=='project_extraction')['input_sha256']='0'*64 - with self.assertRaises(WorkbenchError):decode_records(bad) - self.assertEqual(receipt['verification']['active_data_records'],1) - self.assertEqual(baseline,tree_manifest(self.dataset.path)) - - def test_required_exclusion_and_absent_history_block_publication(self): - parent=self.text();answer=self.dataset.workbench.save_response(dict(id=uuid.uuid4().hex,prompt_id=parent['id'],revision=0, - parent_revision=1,source_revision=1,completion='Unique answer',review='draft'))['response'] - search=self.dataset.searches.create(dict(name='Original criteria',criteria={k:'' for k in ('q','kind','review','sort','task','label','group','rights')})) - self.dataset.searches.mutate(search['id'],'rename',dict(revision=1,name='Saved later name')) - self.selection['roots'].update(responses=[answer['id']],searches=[search['id']]) - self.selection['decisions']=[dict(family='workbench_record',id=parent['id'],include=False,reason='Deliberate ownership exclusion')] - source=self.stop();transfer=ProjectTransfer(source);report=transfer.preview(self.selection) - self.assertFalse(report['can_extract']) - self.assertIn('required_dependency_excluded',{v['code'] for v in report['blockers']}) - self.assertIn('intent_history_unavailable',{v['code'] for v in report['blockers']}) - with self.assertRaises(WorkbenchError) as caught:transfer.extract(self.selection,report['report_sha256'],self.parent_fd,'blocked','Blocked','block-key') - self.assertEqual(caught.exception.code,'extraction_blocked') - self.assertFalse((self.root/'blocked').exists()) - self.assertEqual(list(self.root.glob('.tuldok-extraction-*')),[]) - - def test_failed_final_rename_preserves_stage_and_lost_rename_ack_reconciles(self): - from project_transfer import _rename_noreplace as rename - self.selection['roots']['records']=[self.text()['id']] - source=self.stop();transfer=ProjectTransfer(source);report=transfer.preview(self.selection) - def fail_before(parent,old,new): - if new=='failed':raise OSError('Injected final publication failure') - return rename(parent,old,new) - with patch('project_transfer._rename_noreplace',side_effect=fail_before),self.assertRaises(OSError) as caught: - transfer.extract(self.selection,report['report_sha256'],self.parent_fd,'failed','Retained stage','before-key') - stage=self.root/caught.exception.staging_directory - self.assertTrue(stage.is_dir());self.assertFalse((self.root/'failed').exists()) - with ProjectStore.open(stage) as store:self.assertTrue(store.reconcile('before-key',next(r['document']['input_sha256'] for r in store.snapshot()['records'] if r['family']=='project_extraction'))) - def lose_ack(parent,old,new): - rename(parent,old,new) - if new=='published':raise OSError('Injected lost rename acknowledgement') - with patch('project_transfer._rename_noreplace',side_effect=lose_ack),self.assertRaises(WorkbenchError) as lost: - transfer.extract(self.selection,report['report_sha256'],self.parent_fd,'published','Known committed identity','after-key') - self.assertEqual(lost.exception.code,'unknown');self.assertTrue(lost.exception.receipt['committed']) - self.assertFalse(lost.exception.receipt['selected']);self.assertTrue((self.root/'published').exists()) - receipt=transfer.extract(self.selection,report['report_sha256'],self.parent_fd,'published','Known committed identity','after-key') - self.assertEqual(receipt['project_id'],lost.exception.receipt['project_id']);self.assertTrue(receipt['replayed']) - _assert_unchanged(source) - - def test_current_inspect_agent_can_preview_but_cannot_stop_or_reuse_revoked_view(self): - from access import AccessError - agent=self.dataset.access.issue(dict(label='Finite extraction inspector',scopes=['inspect'])) - with self.dataset.access.bind(agent['token']): - source=preview_source(self.dataset);self.addCleanup(source.close) - self.assertFalse(ProjectTransfer(source).preview(self.selection)['can_extract']) - with self.assertRaises(AccessError):self.dataset.stop_for_project_extraction(self.parent_fd,'agent-backup') - with self.dataset.access.bind(self.token):self.dataset.access.revoke(agent['identity']['credential_id']) - with self.assertRaises(AccessError):source.read_catalog('.tuldok.json') - self.assertFalse(self.dataset._extraction_stopping) - self.assertFalse((self.root/'agent-backup').exists()) - - def test_standalone_owned_image_operation_is_cancelled_and_drained(self): - from image_generation import Operation - operation=Operation();identity=uuid.uuid4().hex - with self.dataset.image_requests.lock:self.dataset.image_requests.active[identity]=operation - def worker(): - operation.cancelled.wait(5) - with self.dataset.image_requests.lock:self.dataset.image_requests.active.pop(identity,None) - operation.done.set() - thread=threading.Thread(target=worker);thread.start();self.addCleanup(thread.join,5) - source=self.stop() - self.assertTrue(operation.cancelled.is_set());self.assertTrue(operation.done.is_set()) - self.assertFalse(self.dataset.image_requests.active);source.require() - - def test_parent_revision_two_response_fork_keeps_original_binding_and_fresh_prompt(self): - parent=self.text() - parent=self.dataset.workbench.save(parent['id'],dict(revision=1,source_revision=1,task='text_classification', - annotation={'label':'authored'},groups=parent['groups'],review='draft')) - answer=self.dataset.workbench.save_response(dict(id=uuid.uuid4().hex,prompt_id=parent['id'],revision=0,parent_revision=2, - source_revision=1,completion='Exact postannotation answer',review='draft'))['response'] - self.selection['roots']['responses']=[answer['id']] - source=self.stop();transfer=ProjectTransfer(source);report=transfer.preview(self.selection) - self.assertTrue(report['can_extract'],report['blockers']) - transfer.extract(self.selection,report['report_sha256'],self.parent_fd,'revision-two','Fresh prompt','revision-two-key') - with ProjectStore.open(self.root/'revision-two') as store: - records=store.snapshot()['records'] - original=next(r for r in records if r['family']=='workbench_response' and r['id']==answer['id']) - fresh=next(r for r in records if r['family']=='workbench_response' and r['id']!=answer['id']) - self.assertEqual(original['document']['history'][0]['parent']['revision'],2) - self.assertEqual(fresh['document']['history'][0]['parent']['revision'],1) - self.assertEqual(original['document']['current'],answer) - - def test_native_original_bytea_extracts_without_reexport_or_regeneration(self): - import meshes - from test_meshes import fixture - prepared=meshes.prepare(*fixture()) - row=self.dataset.workbench.meshes.admit(prepared,dict(groups=['native-fixture'],rights='Unique native authored source')) - original=bytes(self.dataset.db.execute('SELECT bundle FROM workbench_mesh_assets WHERE id=%s',(row['id'],)).fetchone()[0]) - self.selection['roots']['records']=[row['id']] - source=self.stop();transfer=ProjectTransfer(source);report=transfer.preview(self.selection) - self.assertTrue(report['can_extract'],report['blockers']) - # Existing pure owner validation may reparse the bundle; custody must - # publish the exact original bytes rather than a newly encoded archive. - receipt=transfer.extract(self.selection,report['report_sha256'],self.parent_fd,'native','Native custody','native-key') - from project_artifacts import ProjectArtifacts - with ProjectStore.open(self.root/'native') as store,ProjectArtifacts(store) as artifacts: - records=store.snapshot()['records'];source_record=next(r for r in records if r['family']=='workbench_record' and r['id']==row['id']) - edge=source_record['document']['source']['asset']['artifact'] - self.assertEqual(artifacts.read_blob(dict(sha256=edge['sha256'],bytes=len(original))),original) - self.assertEqual(source_record['document']['current'],row) - self.assertEqual(receipt['verification']['active_data_records'],1) - self.assertEqual(bytes(source.db.execute('SELECT bundle FROM workbench_mesh_assets WHERE id=%s',(row['id'],)).fetchone()[0]),original) - - def test_missing_unique_run_input_remains_explicitly_blocked(self): - from test_project_history import legacy_run - run=legacy_run(self.dataset.db.dataset_id) - with self.dataset.db.lock,self.dataset.db.transaction(): - self.dataset.db.execute('INSERT INTO workspace_runs VALUES(%s,%s,%s,%s)',(run['id'],run['request_key'],run['request_sha256'],json.dumps(run))) - self.selection['roots']['runs']=[run['id']] - source=self.stop();transfer=ProjectTransfer(source);report=transfer.preview(self.selection) - self.assertFalse(report['can_extract']) - self.assertIn('missing_unique_payload',{v['code'] for v in report['blockers']}) - self.assertTrue(any(v['sha256']==run['release_sha256'] and v['preservation']=='unique' and v['state']=='missing' for v in report['artifacts'])) - with self.assertRaises(WorkbenchError):transfer.extract(self.selection,report['report_sha256'],self.parent_fd,'missing','Missing unique source','missing-key') - self.assertFalse((self.root/'missing').exists()) - - def test_selected_working_symlink_and_hardlink_refuse_without_following(self): - target=self.root/'outside.py';target.write_bytes(b'outside secret fixture never captured') - (self.project_root/'scripts').mkdir();(self.project_root/'scripts'/'unsafe.py').symlink_to(target) - self.selection['roots']['working_files']=[dict(kind='script',path='scripts/unsafe.py')] - source=self.stop();transfer=ProjectTransfer(source);report=transfer.preview(self.selection) - self.assertFalse(report['can_extract']);self.assertEqual(report['working_files'],[]) - self.assertFalse(any(v['sha256']==hashlib.sha256(target.read_bytes()).hexdigest() for v in report['artifacts'])) - (self.project_root/'scripts'/'unsafe.py').unlink();os.link(target,self.project_root/'scripts'/'unsafe.py') - report=transfer.preview(self.selection) - self.assertFalse(report['can_extract']);self.assertEqual(report['working_files'],[]) - - def test_full_two_study_scientific_custody_extracts_and_cold_rebuilds(self): - """Reuse strict historical source authorship, without an execution claim. - - The readonly fixture's capture boundary delegates to an actual opened - Dataset's stop guard. Neither the proxy nor a fabricated JSON proof is - ever supplied to ProjectTransfer as its source capability. - """ - import test_project_extraction as legacy_fixtures - from project_extraction import capture_legacy - holder={};expected={} - class SourceResult: - def __getattr__(_,name):return getattr(holder['source'],name) - def files(): - return dict(catalog=tree_manifest(self.dataset.path),registered=tree_manifest(self.project_root)) - def capture(_,roots): - self.selection['roots']=roots - before_stop=files() - source=self.stop();holder['source']=source - holder['baseline']=files() - holder['stop_changes']=[group+'/'+path for group in before_stop for path in set(before_stop[group])|set(holder['baseline'][group]) if before_stop[group].get(path)!=holder['baseline'][group].get(path)] - transfer=ProjectTransfer(source);report=transfer.preview(self.selection) - self.assertTrue(report['can_extract'],report['blockers']) - required={(v['family'],v['id']) for v in report['required']} - self.assertEqual(len([v for v in report['included'] if v['family']=='study_history']),2) - self.assertEqual(len([v for v in report['included'] if v['family']=='trial_history']),2) - self.assertEqual(len([v for v in report['included'] if v['family']=='candidate_history']),1) - expected['captured']=capture_legacy(source,self.selection) - receipt=transfer.extract(self.selection,report['report_sha256'],self.parent_fd,'science','Independent scientific custody','science-key') - self.assertEqual(receipt['verification']['active_data_records'],1) - from project_artifacts import ProjectArtifacts - from project_history import decode_records as history - from project_material import ProjectMaterial - with ProjectStore.open(self.root/'science') as store,ProjectArtifacts(store) as artifacts: - snapshot=store.snapshot();records=snapshot['records'] - view=SimpleNamespace(snapshot=snapshot,artifacts=artifacts,check_current=lambda:None) - facts=history(records,materials=ProjectMaterial(view),artifacts=artifacts) - self.assertEqual(len(facts.studies),2);self.assertEqual(len(facts.trials),2) - self.assertEqual(len(facts.candidates),1);self.assertEqual(len(facts.reservations),1);self.assertEqual(len(facts.runs),1) - for original in expected['captured']['records']: - self.assertIn(original,records) - if original['family']=='project_artifact' and source.artifacts.status(original['document'])['state']=='verified': - blob=dict(sha256=original['id'],bytes=original['document']['bytes']) - self.assertEqual(artifacts.read_blob(blob),source.artifacts.read_blob(blob)) - self.assertFalse(any(row['family'].startswith('access_') for row in records)) - _assert_unchanged(source) - self.assertEqual(files(),holder['baseline']) - return expected['captured'] - def fixture_assert_equal(actual,expected,*args): - # The reused capture-only fixture compares all files around capture. - # This adapter explicitly stops first; its source preservation - # baseline therefore belongs after stop/backup, as the API promises. - if type(actual) is dict and set(actual)=={'catalog','registered'} and 'baseline' in holder: - return self.assertEqual(actual,holder['baseline'],*args) - return self.assertEqual(actual,expected,*args) - fixture=SimpleNamespace(dataset=self.dataset,db=self.dataset.db,access=self.dataset.access, - actor=self.actor,workbench=self.dataset.workbench,text=self.text,files=files, - view=lambda:SourceResult(),capture=capture,assertEqual=fixture_assert_equal,assertTrue=self.assertTrue) - legacy_fixtures.LegacyCapture.test_two_study_lineage_reservation_candidate_and_run_science_are_captured(fixture) - self.assertEqual(holder['stop_changes'],['catalog/workspace-runs/.coordinator-v1.json']) - - def test_noncooperating_owned_close_stays_bounded_fenced_and_has_no_lease(self): - entered=threading.Event();release=threading.Event();original=self.dataset.generation_jobs.close - def blocked_close(): - entered.set();release.wait(5);original() - actual=self.dataset.close_for_project_extraction - def bounded(**kwargs):return actual(deadline=time.monotonic()+.1) - try: - with patch.object(self.dataset.generation_jobs,'close',side_effect=blocked_close),patch.object(self.dataset,'close_for_project_extraction',side_effect=bounded): - started=time.monotonic() - with self.assertRaises(WorkbenchError) as caught:self.stop() - self.assertEqual(caught.exception.code,'source_busy') - self.assertLess(time.monotonic()-started,2) - self.assertTrue(entered.is_set());self.assertTrue(self.dataset._extraction_closer.is_alive()) - self.assertTrue(self.dataset._extraction_stopping);self.assertEqual(self.leases,[]) - self.assertFalse((self.root/'verified-backup').exists()) - with self.assertRaises(WorkbenchError): - with self.dataset._project_request():pass - with self.assertRaises(WorkbenchError):self.dataset.stop_for_project_extraction(self.parent_fd,'retry') - release.set();self.dataset._extraction_closer.join(5) - self.assertFalse(self.dataset._extraction_closer.is_alive());self.assertTrue(self.dataset._closed) - finally: - release.set() - if self.dataset._extraction_closer is not None:self.dataset._extraction_closer.join(5) - - def test_retry_after_destination_image_edit_verifies_current_destination(self): - import base64 - import io - from PIL import Image - from access import Access - from metadata import Metadata - from project_projection import ProjectProjection - self.selection['roots']['records']=[self.text()['id']] - source=self.stop();transfer=ProjectTransfer(source);report=transfer.preview(self.selection) - birth=transfer.extract(self.selection,report['report_sha256'],self.parent_fd,'edited','Editable destination','edited-key') - host=Metadata(self.root/'edit-host');projection=None;db=None - try: - authority=Access(host,host.path);token=authority.exchange(authority._local_owner_token())['token'] - with ProjectStore.open(self.root/'edited') as store,authority.bind(token): - db=Metadata(self.root/'edit-projection',dataset_id=store.snapshot()['project_id'],projection_id=uuid.uuid4().hex) - projection=ProjectProjection(store,db,authority,{}) - image=io.BytesIO();Image.new('RGB',(4,3),'purple').save(image,'PNG');raw=image.getvalue() - current=projection.data.import_image(dict(image=base64.b64encode(raw).decode(),name='New destination-only image', - groups=['new-destination'],rights='New authored rights'),projection.session.snapshot['checkpoint'],'new-image') - checkpoint=projection.session.snapshot['checkpoint'] - self.assertNotEqual(checkpoint,birth['checkpoint']) - self.assertNotIn(hashlib.sha256(raw).hexdigest(),source.artifacts.declarations) - # The trusted controller pins its selected Store; replay must - # borrow that exact writer rather than opening a second one. - with authority.lock,projection.session.lock,db.lock: - selected=transfer.extract(self.selection,report['report_sha256'],self.parent_fd,'edited','Editable destination','edited-key',opened_store=store) - self.assertTrue(selected['replayed']);self.assertEqual(selected['checkpoint'],checkpoint) - self.assertEqual(selected['verification']['active_data_records'],2) - self.assertEqual(store.snapshot()['checkpoint'],checkpoint) - with authority.lock,projection.session.lock,db.lock,self.assertRaises(WorkbenchError): - transfer.extract(self.selection,report['report_sha256'],self.parent_fd,'different','Wrong destination','different-key',opened_store=store) - projection.close();projection=None - replay=transfer.extract(self.selection,report['report_sha256'],self.parent_fd,'edited','Editable destination','edited-key') - self.assertTrue(replay['replayed']);self.assertEqual(replay['project_id'],birth['project_id']) - self.assertEqual(replay['checkpoint'],checkpoint);self.assertEqual(replay['verification']['checkpoint'],checkpoint) - self.assertEqual(replay['verification']['active_data_records'],2) - self.assertEqual(replay['source'],birth['source']);self.assertEqual(replay['input_sha256'],birth['input_sha256']) - self.assertEqual(replay['artifacts'],birth['artifacts']);self.assertFalse(replay['selected']) - finally: - if projection is not None:projection.close() - elif db is not None:db.close() - host.close() - with psycopg.connect(source.db.dsn,autocommit=True) as cleanup: - for database in (db,host): - if database is not None:cleanup.execute(sql.SQL('DROP SCHEMA {} CASCADE').format(sql.Identifier(database.schema))) - - -if __name__=='__main__':unittest.main() diff --git a/tests/test_project_transfer_clients.py b/tests/test_project_transfer_clients.py deleted file mode 100644 index bb15545f..00000000 --- a/tests/test_project_transfer_clients.py +++ /dev/null @@ -1,156 +0,0 @@ -"""Five fixed owner extraction contracts and explicit authority handoff. - -Controlled replies qualify client refusal/correlation. Actual source ownership, -stop and extraction are exercised by controller and public HTTP tests elsewhere. -""" -import copy -from http.server import BaseHTTPRequestHandler,ThreadingHTTPServer -import io -import json -from pathlib import Path -import tempfile -import threading -import unittest -from unittest.mock import Mock,patch - -import agent_api as api -import project_cli -from tuldok_client import ProjectTransferClient - -SOURCE,CONTROL,BINDING,NEXT_BINDING,PROJECT=(c*32 for c in 'abcdf') -SHA,OTHER='e'*64,'f'*64 -TOKEN='fixture-only-transfer-owner-token' - - -def source():return dict(catalog_id=SOURCE,schema_version=10,catalog_signature=SHA,snapshot_sha256=SHA, - backup_receipt_sha256=None,external_inventory_sha256=SHA) - - -def state(stopped=False): - return dict(format='project_transfer_state_v1',binding=NEXT_BINDING if stopped else BINDING, - phase='source_stopped' if stopped else 'source_live',source_catalog_id=SOURCE,control_catalog_id=CONTROL, - roots=['output'],available_actions=['status','preview','report_page'],report=None, - backup=dict(root='output',directory='backup',receipt_sha256=SHA) if stopped else None, - destination=dict(root='output',directory='extracted') if stopped else None,failure=None,last_receipt=None) - - -def receipt(): - return dict(format='project_transfer_receipt_v1',committed=True,project_id=PROJECT,checkpoint=OTHER,request_key='k', - input_sha256=SHA,report_sha256=SHA,source=dict(source(),backup_receipt_sha256=SHA), - artifacts=dict(copied_count=1,missing_regenerable_count=0),verification=dict(checkpoint=OTHER,active_data_records=1),replayed=False) - - -def result(): - return dict(format='project_transfer_extraction_result_v1',binding=NEXT_BINDING,receipt=receipt(), - selection=dict(selected=False,state=None,error=dict(code='project_selection_unavailable',detail='Published; explicit Open required.'))) - - -def ready(value,catalog=CONTROL): - client=api.ProjectTransferOwnerClient('http://127.0.0.1:12345',TOKEN,catalog) - client._ready=True;client._selected={name:1 for name in api.PROJECT_TRANSFER_OPERATIONS} - client._request=Mock(return_value={'status':200,'result':value}) - return client - - -class TransferClients(unittest.TestCase): - def test_five_closed_operations_and_default_unavailable_profiles(self): - self.assertEqual(api.PROJECT_TRANSFER_OPERATIONS,api.ProjectTransferOwnerClient.OPERATIONS) - for profile in ('catalog','project'): - manifest=api.capabilities(SOURCE,profile=profile) - found=[op for op in manifest['operations'] if op['id'] in api.PROJECT_TRANSFER_OPERATIONS] - self.assertEqual(len(found),5);self.assertTrue(all(op['availability']=='unavailable' for op in found)) - self.assertLessEqual(len(api.encoded(manifest)),api.CAPABILITIES_LIMIT) - for name in api.PROJECT_TRANSFER_OPERATIONS: - self.assertTrue(callable(getattr(ProjectTransferClient(Mock()),name.split('.')[1]))) - self.assertEqual(api.contract(name)['authority'],'owner') - self.assertEqual(api.contract(name)['bounds']['response_bytes'],1048576) - selection=dict(project_snapshot=dict(id=SOURCE,manifest_sha256=SHA),roots={'records':[PROJECT]},decisions=[]) - api.validate_arguments('project_transfer.preview',dict(binding=BINDING,selection=selection)) - for bad in (dict(selection,credential='forbidden'),dict(selection,stopped_source_lease={}), - dict(selection,roots={'arbitrary_files':['/etc/passwd']})): - with self.assertRaises(api.AgentAPIError):api.validate_arguments('project_transfer.preview',dict(binding=BINDING,selection=bad)) - for directory in ('../escape','a/b','a\\b','.','..','bad\nname'): - with self.assertRaises(api.AgentAPIError):api.validate_arguments('project_transfer.extract',dict(binding=NEXT_BINDING,report_sha256=SHA, - destination_root='output',directory=directory,name='Extracted',request_key='k')) - - def test_owner_bootstrap_limits_tools_and_stop_requires_independent_new_client(self): - client=api.ProjectTransferOwnerClient('http://127.0.0.1:12345',TOKEN,SOURCE) - def request(method,path,body=None,**kwargs): - if path=='/api/access/session':value=dict(kind='owner',catalog_id=SOURCE) - elif path=='/api/workspace/context':value=dict(dataset_id=SOURCE) - elif path=='/api/agent/capabilities': - value=api.capabilities(SOURCE) - for op in value['operations']: - if op['id'] in api.PROJECT_TRANSFER_OPERATIONS:op['availability']='available' - else:value=state(True) - return dict(status=200,result=value) - client._request=Mock(side_effect=request) - self.assertEqual(set(client.bootstrap()['operations']),api.PROJECT_TRANSFER_OPERATIONS) - self.assertEqual({t['name'] for t in client.tool_definitions()},{name.replace('.','_') for name in api.PROJECT_TRANSFER_OPERATIONS}) - count=client._request.call_count - with self.assertRaises(api.AgentAPIError):client.call('project_files.open',{}) - self.assertEqual(client._request.call_count,count) - stopped=ProjectTransferClient(client).stop(binding=BINDING,report_sha256=SHA,backup_root='output',backup_directory='backup',destination_root='output',directory='extracted') - self.assertEqual(stopped['phase'],'source_stopped');count=client._request.call_count - with self.assertRaises(api.AgentAPIError) as failure:ProjectTransferClient(client).status() - self.assertEqual(failure.exception.code,'authentication_handoff');self.assertEqual(client._request.call_count,count) - control=ready(state(True));self.assertEqual(ProjectTransferClient(control).status(),stopped) - wrong=ready(state(True),catalog=SOURCE) - with self.assertRaises(api.AgentAPIError):ProjectTransferClient(wrong).status() - - def test_paged_report_and_published_unselected_receipt_correlate_without_retry(self): - page=dict(format='project_transfer_report_page_v1',binding=NEXT_BINDING,report_sha256=SHA,section='included', - items=[dict(family='workbench_record',id=PROJECT,revision=1)],offset=0,limit=40,total=1) - client=ready(page);sdk=ProjectTransferClient(client) - sdk.report_page(binding=NEXT_BINDING,report_sha256=SHA,section='included') - for change in ({'binding':BINDING},{'report_sha256':OTHER},{'section':'unassigned'},{'offset':1},{'total':41}): - client._request.return_value=dict(status=200,result=dict(page,**change)) - with self.assertRaises(api.AgentAPIError):sdk.report_page(binding=NEXT_BINDING,report_sha256=SHA,section='included') - args=dict(binding=NEXT_BINDING,report_sha256=SHA,destination_root='output',directory='extracted',name='Extracted',request_key='k') - client._request.return_value=dict(status=200,result=result());self.assertFalse(sdk.extract(**args)['selection']['selected']) - bad=result();bad['receipt']['request_key']='other';client._request.return_value=dict(status=200,result=bad) - with self.assertRaises(api.AgentAPIError):sdk.extract(**args) - bad=result();bad['selection']['selected']=True;client._request.return_value=dict(status=200,result=bad) - with self.assertRaises(api.AgentAPIError):sdk.extract(**args) - client._request.return_value=dict(status=503,result={'code':'unknown','error':'Inspect explicit current status.'});before=client._request.call_count - with self.assertRaises(api.AgentAPIError):sdk.extract(**args) - self.assertEqual(client._request.call_count,before+1) - - def test_real_http_preserves_only_exact_partial_receipt_and_enforces_one_mib(self): - partial=dict(committed=True,selected=False,project_id=PROJECT,checkpoint=OTHER,request_key='k',directory='extracted') - value=dict(code='unknown',error='Published; inspect exact destination.',receipt=partial);oversized=False - class Handler(BaseHTTPRequestHandler): - def do_POST(self): - self.rfile.read(int(self.headers.get('Content-Length','0')));raw=api.encoded(value) - self.send_response(503);self.send_header('Content-Type','application/json');self.send_header('Content-Length',str(1048577 if oversized else len(raw)));self.end_headers() - if not oversized:self.wfile.write(raw) - def log_message(self,*_):pass - server=ThreadingHTTPServer(('127.0.0.1',0),Handler);thread=threading.Thread(target=server.serve_forever,daemon=True);thread.start() - self.addCleanup(server.server_close);self.addCleanup(thread.join,5);self.addCleanup(server.shutdown) - client=api.ProjectTransferOwnerClient(f'http://127.0.0.1:{server.server_port}',TOKEN,CONTROL) - client._ready=True;client._selected={'project_transfer.extract':1} - args=dict(binding=NEXT_BINDING,report_sha256=SHA,destination_root='output',directory='extracted',name='Extracted',request_key='k') - with self.assertRaises(api.AgentAPIError) as failure:ProjectTransferClient(client).extract(**args) - self.assertEqual(failure.exception.receipt,partial) - value['receipt']=dict(partial,credential=TOKEN) - with self.assertRaises(api.AgentAPIError) as failure:ProjectTransferClient(client).extract(**args) - self.assertEqual(failure.exception.code,'transport') - oversized=True - with self.assertRaises(api.AgentAPIError) as failure:ProjectTransferClient(client).extract(**args) - self.assertEqual(failure.exception.code,'response_too_large') - - def test_named_cli_selects_separate_owner_and_preserves_selection_document(self): - with tempfile.TemporaryDirectory(prefix='transfer-cli-fixture-') as directory: - selection=dict(project_snapshot=dict(id=SOURCE,manifest_sha256=SHA),roots={'records':[PROJECT]},decisions=[]) - file=Path(directory)/'selection.json';file.write_text(json.dumps(selection)) - client=Mock();client.call.return_value=dict(status=200,result=state()) - output=io.StringIO() - with (patch.object(project_cli.ProjectTransferOwnerClient,'from_config',return_value=client) as constructor, - patch('sys.stdout',output)): - code=project_cli.main(['--config','/not-read','project-transfer','preview','--binding',BINDING,'--selection',str(file)]) - self.assertEqual(code,0);constructor.assert_called_once() - self.assertEqual(client.call.call_args.args[:2],('project_transfer.preview',dict(binding=BINDING,selection=selection))) - self.assertEqual(json.loads(output.getvalue()),state()) - - -if __name__=='__main__':unittest.main() diff --git a/tests/test_project_transfer_clients_http.py b/tests/test_project_transfer_clients_http.py deleted file mode 100644 index 6bd9ff2b..00000000 --- a/tests/test_project_transfer_clients_http.py +++ /dev/null @@ -1,235 +0,0 @@ -"""One frozen M5 SDK/CLI/MCP workflow over the actual legacy HTTP controller. - -Only a disposable fixture is authored. Stop uses the original live Dataset; -the two client configurations contain independent current owner credentials. -No runtime, provider, model preparation or scientific execution is qualified. -""" -from datetime import timedelta -import hashlib -import importlib.util -import json -import os -from pathlib import Path -import subprocess -import sys -import time -import unittest -import uuid - -import agent_api as api -from backup_metadata import tree_manifest -from project_transfer import _assert_unchanged -from tuldok_client import ProjectTransferClient -import test_project_transfer_controller as controller_fixture - -ROOT = Path(__file__).resolve().parents[1] -SDK_AVAILABLE = all(importlib.util.find_spec(name) for name in ('mcp', 'anyio', 'jsonschema')) - - -def frozen_subject(): - name = os.environ.get('TULDOK_M5_CLIENTS_MANIFEST') - if not name: - raise AssertionError('Provide the immutable M5 clients qualification manifest') - path = Path(name) - value = json.loads(path.read_text()) - if value['qualification_copy'] != str(ROOT): - raise AssertionError('Run this acceptance test in the selected immutable copy') - current = {name: hashlib.sha256((ROOT / name).read_bytes()).hexdigest() for name in value['files']} - if current != value['files']: - raise AssertionError('Immutable M5 client source changed before acceptance') - return dict(manifest_sha256=hashlib.sha256(path.read_bytes()).hexdigest(), - parent_manifest_sha256=value['parent_manifest_sha256'], files=current) - - -@unittest.skipUnless(os.environ.get('TULDOK_DATABASE_URL') and SDK_AVAILABLE, - 'Requires disposable PostgreSQL and the approved optional MCP dependencies') -class ProjectTransferClientsHTTP(unittest.TestCase): - def setUp(self): - self.subject = frozen_subject() - self.started, self.performed = time.monotonic(), [] - self.pins = {name: api.contract(name)['sha256'] for name in sorted(api.PROJECT_TRANSFER_OPERATIONS)} - self.assertEqual(len(self.pins), 5) - # Reuse only fixture authoring/cleanup, never inherit its TestCase or run - # its controller test methods as a second acceptance campaign. - self.fixture = controller_fixture.TransferControllerTests('test_actual_http_source_control_handoff_report_and_extraction') - self.fixture.setUp() - self.addCleanup(self.fixture.doCleanups) - self.addCleanup(self.receipt) - f = self.fixture - f.workspace.transfer_controller = f.controller # Same attachment as normal application startup. - self.server = f.server() - self.origin = 'http://127.0.0.1:' + str(self.server.server_port) - self.environment = {key: value for key, value in os.environ.items() if not key.startswith(('TULDOK_', 'PG'))} - self.environment['PYTHONDONTWRITEBYTECODE'] = '1' - self.source_config = self.config('source', f.source_token, f.dataset.db.dataset_id) - self.control_config = self.config('control', f.control_token, f.workspace.db.dataset_id) - - def receipt(self): - current = {name: hashlib.sha256((ROOT / name).read_bytes()).hexdigest() for name in self.subject['files']} - output = Path(os.environ.get('TULDOK_QA_OUTPUT_ROOT', '/workspace/scratch/tuldok-save-load-qa/artifacts')) / 'm5-clients' - output.mkdir(parents=True, exist_ok=True) - value = dict(test=self.id(), seconds=round(time.monotonic() - self.started, 3), performed=self.performed, - qualification_manifest_sha256=self.subject['manifest_sha256'], - parent_manifest_sha256=self.subject['parent_manifest_sha256'], source_stable=current == self.subject['files'], - contract_sha256=self.pins, test_sha256=hashlib.sha256(Path(__file__).read_bytes()).hexdigest(), - fixture='Actual owner SDK, CLI subprocesses and MCP SDK stdio over real HTTP; disposable legacy/control PG catalogs; authored text and inert script only') - (output / (self._testMethodName + '-' + uuid.uuid4().hex + '.json')).write_text(json.dumps(value, indent=2) + '\n') - self.assertEqual(current, self.subject['files'], 'Immutable M5 source changed during acceptance') - - def config(self, label, token, catalog_id): - private = self.fixture.root / (label + '.token') - config = self.fixture.root / (label + '.config.json') - private.write_text(token + '\n'); private.chmod(0o600) - config.write_text(json.dumps(dict(endpoint=self.origin, catalog_id=catalog_id, token_file=str(private), timeout=30))) - config.chmod(0o600) - return config - - def cli(self, config, action, *flags): - result = subprocess.run([sys.executable, str(ROOT / 'project_cli.py'), '--config', str(config), - 'project-transfer', action, *flags], cwd=ROOT, env=self.environment, capture_output=True, text=True, timeout=45) - for token in (self.fixture.source_token, self.fixture.control_token): - self.assertNotIn(token, result.stdout + result.stderr) - self.assertEqual(result.returncode, 0, result.stderr) - return json.loads(result.stdout) - - def parameters(self, config): - from mcp import StdioServerParameters - return StdioServerParameters(command=sys.executable, args=[str(ROOT / 'mcp_stdio.py'), '--config', str(config), - '--project-transfer-owner'], cwd=str(ROOT), env=self.environment) - - async def tools(self, session): - definitions = {tool.name: tool for tool in (await session.list_tools()).tools} - expected = {api.operation(name)['mcp_name'] for name in api.PROJECT_TRANSFER_OPERATIONS} - self.assertEqual(set(definitions), expected) - preview = definitions[api.operation('project_transfer.preview')['mcp_name']] - self.assertEqual(preview.inputSchema, api.operation('project_transfer.preview')['inputSchema']) - self.assertEqual(preview.outputSchema, api.operation('project_transfer.preview')['outputSchema']) - return definitions - - async def tool(self, session, action, arguments, status=200): - name = 'project_transfer.' + action - value = await session.call_tool(api.operation(name)['mcp_name'], arguments) - envelope = value.structuredContent - self.assertEqual(envelope['status'], status, envelope) - self.assertEqual(value.isError, status >= 400) - self.assertEqual(json.loads(value.content[0].text), envelope) - api.validate_output(name, envelope) - return envelope['result'] - - def test_owner_handoff_and_single_extraction_through_sdk_cli_and_real_mcp(self): - import anyio - from mcp import ClientSession - from mcp.client.stdio import stdio_client - - f = self.fixture - sentinel = f.root / 'must-not-execute' - script = ('from pathlib import Path\nPath(' + repr(str(sentinel)) + ').write_text("executed")\n# exact inert Ω\r\n').encode() - (f.registered / 'scripts').mkdir() - (f.registered / 'scripts' / 'inert.py').write_bytes(script) - f.selection['roots']['working_files'] = [dict(kind='script', path='scripts/inert.py')] - source_transport = api.ProjectTransferOwnerClient.from_config(self.source_config) - source = ProjectTransferClient(source_transport) - bootstrap = source_transport.bootstrap() - self.assertEqual(bootstrap['identity']['catalog_id'], f.dataset.db.dataset_id) - self.assertEqual(set(bootstrap['operations']), api.PROJECT_TRANSFER_OPERATIONS) - self.assertEqual(source_transport.selected_contracts(), {name: 1 for name in self.pins}) - initial = source.status() - live = source.preview(f.selection, binding=initial['binding']) - self.assertEqual(live['phase'], 'source_live') - self.assertFalse(live['report']['can_extract']) - first = source.report_page(binding=live['binding'], report_sha256=live['report']['report_sha256'], section='included', limit=1) - second = self.cli(self.source_config, 'report-page', '--binding', live['binding'], '--report-sha256', live['report']['report_sha256'], - '--section', 'included', '--offset', '1', '--limit', '1') - self.assertEqual((first['offset'], second['offset'], len(second['items'])), (0, 1, 1)) - self.assertNotEqual(first['items'][0], second['items'][0]) - self.assertEqual(first['report_sha256'], second['report_sha256']) - config_before = self.source_config.read_bytes() - self.performed.append('Source owner SDK negotiates exactly five pins, previews read-only; named CLI pages the next report item') - - async def exercise(): - source_errors = f.root / 'source-mcp.stderr' - with source_errors.open('w+') as diagnostics: - async with stdio_client(self.parameters(self.source_config), errlog=diagnostics) as (read, write): - async with ClientSession(read, write, read_timeout_seconds=timedelta(seconds=30)) as source_session: - await source_session.initialize() - await self.tools(source_session) - before = await self.tool(source_session, 'status', {}) - self.assertEqual(before['binding'], live['binding']) - working = await self.tool(source_session, 'report_page', dict(binding=live['binding'], report_sha256=live['report']['report_sha256'], section='working_files', offset=0, limit=40)) - self.assertEqual(working['items'], [dict(kind='script', path='scripts/inert.py', sha256=hashlib.sha256(script).hexdigest(), bytes=len(script))]) - self.performed.append('Source MCP exposes only five pinned tools and reads exact inert script availability') - - stopped = source.stop(binding=live['binding'], report_sha256=live['report']['report_sha256'], - backup_root='output', backup_directory='backup', destination_root='output', directory='extracted') - self.assertEqual(stopped['phase'], 'source_stopped') - self.assertNotEqual(stopped['binding'], live['binding']) - baseline = tree_manifest(f.dataset.path) - with self.assertRaises(api.AgentAPIError) as fenced: source.status() - self.assertEqual(fenced.exception.code, 'authentication_handoff') - denied = await self.tool(source_session, 'status', {}, status=401) - self.assertIn(denied['code'], ('unauthenticated', 'forbidden')) - self.assertEqual(self.source_config.read_bytes(), config_before) - self.assertEqual(source_transport.catalog_id, f.dataset.db.dataset_id) - - # New credentials AND catalog configuration are supplied - # explicitly; no old client learns a replacement token. - control_transport = api.ProjectTransferOwnerClient.from_config(self.control_config) - control = ProjectTransferClient(control_transport) - current = control_transport.bootstrap() - self.assertEqual(current['identity']['catalog_id'], f.workspace.db.dataset_id) - self.assertEqual(set(current['operations']), api.PROJECT_TRANSFER_OPERATIONS) - fresh = control.status() - selection_file = f.root / 'explicit-selection.json' - selection_file.write_text(json.dumps(f.selection)) - selection_file.chmod(0o600) - ready = self.cli(self.control_config, 'preview', '--binding', fresh['binding'], '--selection', str(selection_file)) - self.assertTrue(ready['report']['can_extract']) - self.assertNotEqual(ready['report']['report_sha256'], live['report']['report_sha256']) - self.assertEqual(ready['binding'], fresh['binding']) - self.performed.append('One explicit SDK Stop; old SDK fences locally and old MCP receives401; new independently configured owner SDK/CLI identify the control catalog') - - arguments = dict(binding=ready['binding'], report_sha256=ready['report']['report_sha256'], - destination_root='output', directory='extracted', name='Client extraction Ω', request_key='m5-client-extraction-key') - with (f.root / 'control-mcp.stderr').open('w+') as errors: - async with stdio_client(self.parameters(self.control_config), errlog=errors) as (reader, writer): - async with ClientSession(reader, writer, read_timeout_seconds=timedelta(seconds=30)) as session: - await session.initialize() - await self.tools(session) - result = await self.tool(session, 'extract', arguments) - errors.seek(0) - self.assertNotIn(f.source_token, errors.read()) - errors.seek(0) - self.assertNotIn(f.control_token, errors.read()) - self.assertTrue(result['receipt']['committed']) - self.assertFalse(result['receipt']['replayed']) - self.assertTrue(result['selection']['selected']) - self.assertEqual(result['receipt']['verification']['active_data_records'], 1) - self.assertEqual(result['receipt']['source']['catalog_id'], f.dataset.db.dataset_id) - self.assertNotIn(result['receipt']['project_id'], (f.dataset.db.dataset_id, f.workspace.db.dataset_id)) - replay = control.extract(**arguments) - self.assertTrue(replay['receipt']['replayed']) - self.assertTrue(replay['selection']['selected']) - self.assertEqual(replay['receipt']['project_id'], result['receipt']['project_id']) - self.assertEqual(replay['receipt']['checkpoint'], result['receipt']['checkpoint']) - self.assertEqual(replay['selection']['state']['project']['checkpoint'], replay['receipt']['checkpoint']) - self.assertEqual(tree_manifest(f.dataset.path), baseline) - _assert_unchanged(f.controller._source) - self.performed.append('Fresh-control MCP publishes once and selects inertly; SDK exact-key retry reconciles the selected writer with the same verified project/head') - diagnostics.seek(0) - self.assertNotIn(f.source_token, diagnostics.read()) - diagnostics.seek(0) - self.assertNotIn(f.control_token, diagnostics.read()) - return result - - result = anyio.run(exercise) - self.assertEqual((f.publication / 'extracted' / 'scripts' / 'inert.py').read_bytes(), script) - self.assertFalse(sentinel.exists()) - self.assertEqual(f.workspace._store.snapshot()['project_id'], result['receipt']['project_id']) - canonical = json.dumps(f.workspace._store.snapshot(), ensure_ascii=False) - self.assertNotIn(f.source_token, canonical) - self.assertNotIn(f.control_token, canonical) - self.performed.append('Original source remains unchanged; destination retains exact script bytes; no script executes or credentials enter canonical facts') - - -if __name__ == '__main__': - unittest.main() diff --git a/tests/test_project_transfer_controller.py b/tests/test_project_transfer_controller.py deleted file mode 100644 index a9802cff..00000000 --- a/tests/test_project_transfer_controller.py +++ /dev/null @@ -1,345 +0,0 @@ -"""Finite two-authority extraction controller on disposable PostgreSQL.""" -import hashlib -import http.client -from http.server import ThreadingHTTPServer -import json -import os -from pathlib import Path -import tempfile -import threading -import time -import unittest -from unittest.mock import patch -import uuid - -import psycopg -from psycopg import sql -from app import Dataset, make_handler -import agent_api -from access import AccessError -from backup_metadata import tree_manifest -from project_store import ProjectStore, ProjectStoreError -from project_transfer_controller import ProjectTransferController, _receipt_summary -from project_workspace import ProjectWorkspace -from workbench import WorkbenchError - - -@unittest.skipUnless(os.environ.get('TULDOK_DATABASE_URL'), 'Requires disposable PostgreSQL') -class TransferControllerTests(unittest.TestCase): - def setUp(self): - self.temporary = tempfile.TemporaryDirectory(prefix='tuldok-transfer-controller-') - self.addCleanup(self.temporary.cleanup) - self.root = Path(self.temporary.name) - self.registered = self.root / 'registered' - self.publication = self.root / 'publication' - self.registered.mkdir(); self.publication.mkdir() - self.dataset = Dataset(self.root / 'legacy', project_roots={'fixture': self.registered}) - self.workspace = ProjectWorkspace(self.root / 'control', {'output': self.publication}) - self.controller = ProjectTransferController(self.dataset, self.workspace) - self.schemas = {self.dataset.db.schema, self.workspace.db.schema} - self.addCleanup(self.cleanup) - source = self.dataset.access.exchange(self.dataset.access._local_owner_token()) - control = self.workspace.access.exchange(self.workspace.access._local_owner_token()) - self.source_token, self.control_token = source['token'], control['token'] - self.control_credential = control['identity']['credential_id'] - self.enterContext(self.dataset.access.bind(self.source_token)) - manifest = dict(schema_version=1, id=uuid.uuid4().hex, name='Explicit source λ', data=[], recipes=[], evidence=[], requirements=[]) - raw = (json.dumps(manifest, ensure_ascii=False, indent=3) + '\n\n').encode() - (self.registered / 'source.json').write_bytes(raw) - self.dataset.projects.register_snapshot(dict(root='fixture', manifest_path='source.json')) - record = self.dataset.workbench.import_asset(dict(kind='text', name='Exact selected source', text='Original e\u0301\r\nλ', groups=['fixture-source'], parents=[], rights='Fixture permission')) - self.selection = dict(project_snapshot=dict(id=manifest['id'], manifest_sha256=hashlib.sha256(raw).hexdigest()), roots=dict(records=[record['id']]), decisions=[]) - - def cleanup(self): - if self.workspace._projection is not None: - self.schemas.add(self.workspace._projection.db.schema) - self.controller.close(); self.workspace.close(); self.dataset.close() - with psycopg.connect(self.dataset.db.dsn, autocommit=True) as connection: - for schema in self.schemas: - connection.execute(sql.SQL('DROP SCHEMA IF EXISTS {} CASCADE').format(sql.Identifier(schema))) - - def preview(self): - state = self.controller.status() - return self.controller.preview(state['binding'], self.selection) - - def stop(self): - state = self.preview() - return self.controller.stop(state['binding'], state['report']['report_sha256'], 'output', 'backup', 'output', 'extracted') - - def ready(self): - self.stop() - with self.workspace.access.bind(self.control_token): - return self.preview() - - def extract(self, state, key='controller-extract-key'): - return self.controller.extract(state['binding'], state['report']['report_sha256'], 'output', 'extracted', 'Extracted scientific project', key) - - def test_live_preview_is_readonly_paged_and_never_constructs_owners(self): - for number in range(41): - self.dataset.workbench.import_asset(dict(kind='text', name=str(number), text='Unassigned ' + str(number), groups=['fixture-source'], parents=[], rights='Fixture permission')) - before = tree_manifest(self.dataset.path) - with patch('metadata.Metadata.__init__', side_effect=AssertionError('Metadata construction')), patch('runs.Runs.__init__', side_effect=AssertionError('Runs construction')): - state = self.preview() - self.assertFalse(state['report']['can_extract']) - self.assertEqual(state['report']['counts']['unassigned'], 41) - page = self.controller.report_page(state['binding'], state['report']['report_sha256'], 'unassigned') - self.assertEqual((len(page['items']), page['total'], page['offset'], page['limit']), (40, 41, 0, 40)) - self.assertEqual(len(self.controller.report_page(state['binding'], state['report']['report_sha256'], 'unassigned', 40)['items']), 1) - for section, offset, limit in (([], 0, 40), ('unassigned', True, 40), ('unassigned', 0, 41)): - with self.assertRaises(WorkbenchError): self.controller.report_page(state['binding'], state['report']['report_sha256'], section, offset, limit) - with self.assertRaises(WorkbenchError) as caught: self.controller.report_page(state['binding'], '0' * 64, 'unassigned') - self.assertEqual(caught.exception.code, 'stale') - self.assertEqual(before, tree_manifest(self.dataset.path)) - self.assertFalse(self.dataset._extraction_stopping) - - def test_stop_validates_physical_targets_and_current_owner_before_effects(self): - state = self.preview() - (self.publication / 'already-there').mkdir() - with patch.object(self.dataset, 'stop_for_project_extraction', wraps=self.dataset.stop_for_project_extraction) as stop: - for backup, destination in (('same', 'same'), ('already-there', 'new')): - with self.assertRaises(WorkbenchError): self.controller.stop(state['binding'], state['report']['report_sha256'], 'output', backup, 'output', destination) - with self.workspace.access.bind(self.control_token): - with self.assertRaises(AccessError): self.controller.stop(state['binding'], state['report']['report_sha256'], 'output', 'backup', 'output', 'extracted') - stop.assert_not_called() - self.assertFalse(self.dataset._closed) - with self.assertRaises(WorkbenchError): ProjectTransferController(self.dataset, self.workspace, {'inside': self.dataset.path}) - linked = self.root / 'linked'; linked.symlink_to(self.publication, target_is_directory=True) - with self.assertRaises((WorkbenchError, ProjectStoreError, OSError)): ProjectTransferController(self.dataset, self.workspace, {'linked': linked}) - - def test_scoped_agent_cannot_review_or_stop_the_catalog(self): - state = self.preview() - agent = self.dataset.access.issue(dict(label='Fixture scoped reader', scopes=['inspect', 'edit'])) - with self.dataset.access.bind(agent['token']), patch.object(self.dataset, 'stop_for_project_extraction', wraps=self.dataset.stop_for_project_extraction) as stop: - with self.assertRaises(AccessError): self.controller.status() - with self.assertRaises(AccessError): self.controller.preview(state['binding'], self.selection) - with self.assertRaises(AccessError): self.controller.stop(state['binding'], state['report']['report_sha256'], 'output', 'backup', 'output', 'extracted') - stop.assert_not_called() - self.assertFalse(self.dataset._extraction_stopping) - - def test_stop_rotates_binding_and_requires_independent_control_auth_then_cold_open(self): - old = self.controller.status()['binding'] - stopped = self.stop() - self.assertEqual((stopped['phase'], self.controller.phase), ('source_stopped', 'source_stopped')) - self.assertIs(self.controller.access, self.workspace.access) - self.assertIs(self.controller.control_workspace, self.workspace) - self.assertNotEqual(stopped['binding'], old) - self.assertIsNone(stopped['report']) - with self.assertRaises(AccessError): self.controller.status() - baseline = tree_manifest(self.dataset.path) - with self.workspace.access.bind(self.control_token): - with self.assertRaises(WorkbenchError) as caught: self.controller.preview(old, self.selection) - self.assertEqual(caught.exception.code, 'stale') - ready = self.preview() - self.assertTrue(ready['report']['can_extract']) - result = self.extract(ready) - self.assertTrue(result['receipt']['committed']) - self.assertTrue(result['selection']['selected'], result) - self.assertIsNone(result['selection']['error']) - self.assertEqual(result['selection']['state']['project']['checkpoint'], result['receipt']['checkpoint']) - replay = self.extract(ready) - self.assertTrue(replay['receipt']['replayed']) - self.assertEqual(result['receipt']['project_id'], replay['receipt']['project_id']) - with self.assertRaises(ProjectStoreError): - self.controller.extract(ready['binding'], ready['report']['report_sha256'], 'output', 'extracted', 'Changed input', 'controller-extract-key') - self.assertEqual(baseline, tree_manifest(self.dataset.path)) - self.schemas.add(self.workspace._projection.db.schema) - self.workspace.close() - with ProjectStore.open(self.publication / 'extracted') as store: - snapshot = store.snapshot() - self.assertEqual(snapshot['project_id'], result['receipt']['project_id']) - self.assertNotIn('access_credential', {r['family'] for r in snapshot['records']}) - - def test_published_lost_ack_is_visible_and_exact_retry_reconciles(self): - state = self.ready() - from project_transfer import _rename_noreplace - def renamed_then_lost(*arguments): - _rename_noreplace(*arguments) - raise OSError('Controlled lost acknowledgement') - with self.workspace.access.bind(self.control_token): - with patch('project_transfer._rename_noreplace', side_effect=renamed_then_lost), self.assertRaises(WorkbenchError) as caught: - self.extract(state) - self.assertEqual(caught.exception.code, 'unknown') - status = self.controller.status() - self.assertTrue(status['last_receipt']['committed']) - self.assertFalse(status['last_receipt']['selected']) - self.assertEqual(status['failure']['action'], 'extract') - result = self.extract(state) - self.assertTrue(result['receipt']['replayed']) - self.assertTrue(result['selection']['selected']) - self.assertEqual(result['receipt']['project_id'], status['last_receipt']['project_id']) - - def test_known_prepublication_failure_retains_private_staging(self): - state = self.ready() - with self.workspace.access.bind(self.control_token): - with patch('project_transfer._rename_noreplace', side_effect=OSError('Controlled before-rename failure')), self.assertRaises(OSError) as caught: - self.extract(state) - staging = caught.exception.staging_directory - self.assertTrue((self.publication / staging).is_dir()) - self.assertFalse((self.publication / 'extracted').exists()) - failed = self.controller.status() - self.assertIsNone(failed['last_receipt']) - self.assertEqual(failed['failure']['staging_directory'], staging) - result = self.extract(state) - self.assertFalse(result['receipt']['replayed']) - self.assertTrue(result['selection']['selected']) - - def test_open_failure_preserves_committed_receipt_and_retry_selects(self): - state = self.ready() - dispatch = self.workspace.dispatch - def unavailable_open(name, arguments): - if name == 'project_files.open': raise WorkbenchError('Controlled selection failure', 'unavailable', 503) - return dispatch(name, arguments) - with self.workspace.access.bind(self.control_token): - with patch.object(self.workspace, 'dispatch', side_effect=unavailable_open): result = self.extract(state) - self.assertTrue(result['receipt']['committed']) - self.assertFalse(result['selection']['selected']) - self.assertEqual(result['selection']['error']['code'], 'unavailable') - retry = self.extract(state) - self.assertTrue(retry['receipt']['replayed']) - self.assertTrue(retry['selection']['selected']) - - def test_revoked_control_authority_cannot_replay_a_published_extraction(self): - state = self.ready() - with self.workspace.access.bind(self.control_token): - result = self.extract(state) - before = tree_manifest(self.publication / 'extracted') - self.workspace.access.revoke(self.control_credential) - with patch.object(self.controller._transfer, 'extract', wraps=self.controller._transfer.extract) as extract: - with self.assertRaises(AccessError): self.extract(state) - extract.assert_not_called() - self.assertTrue(result['selection']['selected']) - self.assertEqual(before, tree_manifest(self.publication / 'extracted')) - - def test_failed_stop_stays_fenced_without_minting_a_lease(self): - state = self.preview() - def fenced_pending(*arguments): - self.dataset._extraction_stopping = True - raise WorkbenchError('Controlled pending drain', 'busy', 409) - with patch.object(self.dataset, 'stop_for_project_extraction', side_effect=fenced_pending): - with self.assertRaises(WorkbenchError): self.controller.stop(state['binding'], state['report']['report_sha256'], 'output', 'backup', 'output', 'extracted') - self.assertEqual(self.controller.phase, 'source_fenced') - self.assertIsNone(self.controller._source) - with self.assertRaises(AccessError): self.controller.status() - with self.workspace.access.bind(self.control_token): - failed = self.controller.status() - self.assertEqual(failed['available_actions'], ['status']) - self.assertEqual(failed['failure']['code'], 'busy') - with self.assertRaises(WorkbenchError): self.controller.preview(failed['binding'], self.selection) - for name, body in (([], {}), ('project_transfer.status', {'lease': True}), ('project_transfer.extract', {'binding': failed['binding']})): - with self.assertRaises(WorkbenchError): self.controller.dispatch(name, body) - - def test_native_no_effect_stop_denial_keeps_source_authentication(self): - state = self.preview() - with patch.object(self.dataset, 'stop_for_project_extraction', side_effect=AccessError('Revoked before native fence')): - with self.assertRaises(AccessError): self.controller.stop(state['binding'], state['report']['report_sha256'], 'output', 'backup', 'output', 'extracted') - self.assertEqual(self.controller.phase, 'source_live') - self.assertIs(self.controller.access, self.dataset.access) - refreshed = self.controller.status() - self.assertIsNone(refreshed['report']) - self.assertNotEqual(refreshed['binding'], state['binding']) - self.assertFalse(self.dataset._extraction_stopping) - - def server(self, blocked=None): - handler = make_handler(self.dataset, transfer_controller=self.controller) - if blocked is not None: - original = handler._handle_GET - def held(request): - if request.path == '/api/access/session' and request.headers.get('Fixture-Hold') == 'yes': - blocked[0].set() - if not blocked[1].wait(10): raise AssertionError('Fixture handler release timed out') - return original(request) - handler._handle_GET = held - server = ThreadingHTTPServer(('127.0.0.1', 0), handler) - thread = threading.Thread(target=server.serve_forever, daemon=True) - thread.start() - self.addCleanup(server.server_close); self.addCleanup(server.shutdown) - return server - - def http(self, server, method, path, token=None, body=None, operation=None, headers=None): - fields = dict(headers or {}) - if token is not None: fields['Authorization'] = 'Bearer ' + token - if operation is not None: fields[agent_api.CONTRACT_HEADER] = agent_api.selected_header(operation) - raw = None if body is None else json.dumps(body).encode() - if raw is not None: fields['Content-Type'] = 'application/json' - connection = http.client.HTTPConnection(*server.server_address, timeout=15) - try: - connection.request(method, path, raw, fields) - response = connection.getresponse() - value = json.loads(response.read()) - result = dict(status=response.status, result=value) - if operation is not None: agent_api.validate_output(operation, result) - return result - finally: - connection.close() - - def transfer_http(self, server, action, token, arguments): - name = 'project_transfer.' + action - method, path, body = agent_api.project_request(name, arguments) - return self.http(server, method, path, token, body, name) - - def test_actual_http_source_control_handoff_report_and_extraction(self): - server = self.server() - initial = self.transfer_http(server, 'status', self.source_token, {}) - self.assertEqual(initial['status'], 200) - live = self.transfer_http(server, 'preview', self.source_token, dict(binding=initial['result']['binding'], selection=self.selection))['result'] - page = self.transfer_http(server, 'report_page', self.source_token, dict(binding=live['binding'], report_sha256=live['report']['report_sha256'], section='included', offset=0, limit=2)) - self.assertEqual(page['status'], 200) - self.assertEqual(page['result']['limit'], 2) - stopped = self.transfer_http(server, 'stop', self.source_token, dict(binding=live['binding'], report_sha256=live['report']['report_sha256'], backup_root='output', backup_directory='backup', destination_root='output', directory='extracted')) - self.assertEqual(stopped['status'], 200) - self.assertEqual(stopped['result']['phase'], 'source_stopped') - self.assertEqual(self.http(server, 'GET', '/api/access/session', self.source_token)['status'], 401) - who = self.http(server, 'GET', '/api/access/session', self.control_token) - self.assertEqual(who['result']['catalog_id'], self.workspace.db.dataset_id) - fresh = self.transfer_http(server, 'status', self.control_token, {})['result'] - ready = self.transfer_http(server, 'preview', self.control_token, dict(binding=fresh['binding'], selection=self.selection))['result'] - result = self.transfer_http(server, 'extract', self.control_token, dict(binding=ready['binding'], report_sha256=ready['report']['report_sha256'], destination_root='output', directory='extracted', name='Actual wire extraction', request_key='http-extraction-key')) - self.assertEqual(result['status'], 200, result) - self.assertTrue(result['result']['selection']['selected']) - self.assertEqual(result['result']['receipt']['project_id'], self.workspace._store.snapshot()['project_id']) - - def test_actual_http_late_source_handler_prevents_early_authentication_handoff(self): - entered, release = threading.Event(), threading.Event() - server = self.server((entered, release)) - self.addCleanup(release.set) - outcomes = [] - def held_request(): - try: outcomes.append(self.http(server, 'GET', '/api/access/session', self.source_token, headers={'Fixture-Hold': 'yes'})) - except BaseException as error: outcomes.append(error) - client = threading.Thread(target=held_request) - client.start() - self.assertTrue(entered.wait(5)) - live = self.preview() - monotonic = time.monotonic - # Advance only the native Stop deadline, without sleeping a minute or - # inventing a cessation lease. The real in-flight request remains held. - with patch('app.time.monotonic', side_effect=lambda: monotonic() + (61 if self.dataset._extraction_stopping else 0)): - stopped = self.transfer_http(server, 'stop', self.source_token, dict(binding=live['binding'], report_sha256=live['report']['report_sha256'], backup_root='output', backup_directory='backup', destination_root='output', directory='extracted')) - self.assertEqual((stopped['status'], stopped['result']['code']), (409, 'source_busy')) - self.assertEqual(self.controller.phase, 'source_fenced') - self.assertFalse(self.dataset._closed) - self.assertTrue(any(self.dataset._extraction_requests.values())) - early = self.http(server, 'GET', '/api/access/session', self.control_token) - self.assertEqual((early['status'], early['result']['code']), (409, 'source_stopping')) - release.set(); client.join(5) - self.assertFalse(client.is_alive()) - self.assertEqual(len(outcomes), 1) - self.assertIsInstance(outcomes[0], dict) - self.assertEqual(outcomes[0]['result']['catalog_id'], self.dataset.db.dataset_id) - current = self.http(server, 'GET', '/api/access/session', self.control_token) - self.assertEqual(current['status'], 200) - self.assertEqual(current['result']['catalog_id'], self.workspace.db.dataset_id) - self.assertEqual(self.http(server, 'GET', '/api/access/session', self.source_token)['status'], 401) - state = self.transfer_http(server, 'status', self.control_token, {}) - self.assertEqual(state['result']['available_actions'], ['status']) - self.assertIsNone(self.controller._source) - - -class TransferReceiptBounds(unittest.TestCase): - def test_many_copied_artifacts_do_not_create_an_oversized_post_commit_ack(self): - native = dict(format='project_extraction_receipt_v1', committed=True, project_id='a' * 32, checkpoint='b' * 64, - request_key='bounded-receipt', input_sha256='c' * 64, report_sha256='d' * 64, source={}, - artifacts=dict(copied=['e' * 64] * 20000, missing_regenerable=['f' * 64] * 20000), verification={}, replayed=False) - receipt = _receipt_summary(native) - self.assertEqual(receipt['artifacts'], dict(copied_count=20000, missing_regenerable_count=20000)) - self.assertLess(len(json.dumps(receipt)), 1024) diff --git a/tests/test_project_validation_cache.py b/tests/test_project_validation_cache.py deleted file mode 100644 index 034d50dd..00000000 --- a/tests/test_project_validation_cache.py +++ /dev/null @@ -1,105 +0,0 @@ -"""Private workspace caches that make reopening an unchanged project fast.""" -from pathlib import Path -import tempfile -import unittest -from unittest.mock import patch - -import project_store as store_module -from project_store import ProjectStore -from project_validation_cache import CanonicalDigestCache, ProjectValidationCache - -PROJECT = 'a' * 32 -CHECKPOINT = 'b' * 64 - - -def note(identity, text): - return dict(family='workbench_text', id=identity, - document=dict(format='workbench_text_v1', text=text, history=[])) - - -class ValidationCacheTests(unittest.TestCase): - def setUp(self): - temporary = tempfile.TemporaryDirectory(prefix='tuldok-validation-cache-') - self.addCleanup(temporary.cleanup) - self.control = Path(temporary.name) - - def test_marker_binds_project_checkpoint_and_validator_fingerprint(self): - cache = ProjectValidationCache(self.control, fingerprint='1' * 64) - self.assertFalse(cache.known(PROJECT, CHECKPOINT)) - cache.remember(PROJECT, CHECKPOINT) - self.assertTrue(cache.known(PROJECT, CHECKPOINT)) - self.assertTrue(ProjectValidationCache(self.control, fingerprint='1' * 64).known(PROJECT, CHECKPOINT)) - self.assertFalse(cache.known(PROJECT, 'c' * 64)) - self.assertFalse(cache.known('d' * 32, CHECKPOINT)) - self.assertFalse(ProjectValidationCache(self.control, fingerprint='2' * 64).known(PROJECT, CHECKPOINT), - 'Changed validator source must revalidate') - - def test_tampered_or_invalid_markers_are_not_trusted(self): - cache = ProjectValidationCache(self.control, fingerprint='1' * 64) - cache.remember(PROJECT, CHECKPOINT) - marker = next((self.control / '.project-validation').glob('*.json')) - marker.write_text('{"format":"project_validation_marker_v1","checkpoint":"other"}') - self.assertFalse(cache.known(PROJECT, CHECKPOINT)) - with self.assertRaises(ValueError): - cache.known('not-a-project', CHECKPOINT) - - def test_default_fingerprint_covers_validating_sources(self): - self.assertRegex(ProjectValidationCache(self.control).fingerprint, '^[a-f0-9]{64}$') - - -class CanonicalDigestCacheTests(unittest.TestCase): - def setUp(self): - temporary = tempfile.TemporaryDirectory(prefix='tuldok-canonical-cache-') - self.addCleanup(temporary.cleanup) - self.root = Path(temporary.name) - self.control = self.root / 'control' - self.control.mkdir() - store = ProjectStore.create(self.root / 'project', 'Canonical fixture', 'new', 'a' * 64) - self.records = [note('one', 'Alpha ☃'), note('two', 'Beta\nwith "quotes"')] - self.committed = store.commit(self.records, store.summary()['checkpoint'], 'seed', 'b' * 64) - store.close() - - def open(self, cache): - store = ProjectStore.open(self.root / 'project', canonical_digests=cache) - self.addCleanup(store.close) - return store - - def test_reopen_skips_only_repeated_canonical_proofs_and_keeps_exact_values(self): - cache = CanonicalDigestCache(self.control) - with patch.object(store_module, '_decode', wraps=store_module._decode) as decode: - store = self.open(cache) - first = store.snapshot() - store.close() - self.assertEqual(first, self.committed) - self.assertEqual(decode.call_count, 1 + len(self.records), 'Checkpoint plus each record proven once') - reopened = CanonicalDigestCache(self.control) - with patch.object(store_module, '_decode', wraps=store_module._decode) as decode: - second = ProjectStore.open(self.root / 'project', canonical_digests=reopened) - try: - self.assertEqual(second.snapshot(), self.committed) - finally: - second.close() - self.assertEqual(decode.call_count, 1, 'Only the checkpoint itself is decoded canonically') - - def test_corruption_still_fails_with_a_warm_canonical_cache(self): - cache = CanonicalDigestCache(self.control) - self.open(cache).close() - manifest = store_module._decode((self.root / 'project/.tuldok/project.json').read_bytes()) - path = self.root / 'project/.tuldok' / manifest['inventory'][0]['path'] - path.write_bytes(path.read_bytes().replace(b'Alpha', b'Omega')) - with self.assertRaises(store_module.ProjectStoreError): - ProjectStore.open(self.root / 'project', canonical_digests=CanonicalDigestCache(self.control)) - - def test_commit_registers_new_revisions_and_unreadable_cache_is_ignored(self): - cache = CanonicalDigestCache(self.control) - store = self.open(cache) - store.commit([*self.records, note('three', 'Gamma')], store.summary()['checkpoint'], 'more', 'c' * 64) - manifest = store_module._decode((self.root / 'project/.tuldok/project.json').read_bytes()) - added = next(entry for entry in manifest['inventory'] if entry['id'] == 'three') - self.assertIn(added['sha256'], CanonicalDigestCache(self.control)) - cache.path.write_bytes(b'truncated') - self.assertNotIn(added['sha256'], CanonicalDigestCache(self.control)) - - -if __name__ == '__main__': - unittest.main() diff --git a/tests/test_project_validation_delta.py b/tests/test_project_validation_delta.py deleted file mode 100644 index 73dfea16..00000000 --- a/tests/test_project_validation_delta.py +++ /dev/null @@ -1,67 +0,0 @@ -"""Edit-scoped validation re-checks exactly what an edit can affect.""" -import os -import unittest -from unittest.mock import patch - -from project_projection import validate_project_records -from project_validation_delta import COMPONENTS, ValidationDelta, edit_delta -from workbench import WorkbenchError - -PROJECT = 'a' * 32 -BROKEN_TEXT = dict(family='workbench_text', id='broken', document=dict(format='workbench_text_v1', text=17)) - - -class DeltaRules(unittest.TestCase): - def test_new_artifact_declarations_touch_no_component(self): - delta = ValidationDelta(frozenset({('project_artifact', 'b' * 64)}), added=frozenset({('project_artifact', 'b' * 64)})) - self.assertEqual(delta.families, frozenset()) - self.assertFalse(any(delta.touches(component) for component in COMPONENTS)) - changed = ValidationDelta(frozenset({('project_artifact', 'b' * 64)})) - self.assertTrue(changed.touches('history'), 'A changed existing declaration is re-checked') - - def test_receipt_rules(self): - delta = ValidationDelta(frozenset({('workbench_record', 'r'), ('project_operation', 'new')}), - frozenset({'data.import_text'})) - self.assertTrue(delta.receipt_needed('data.annotate', ('project_operation', 'old')), 'Data receipts bind to changed data records') - self.assertFalse(delta.receipt_needed('files.adopt', ('project_operation', 'old'))) - self.assertTrue(delta.receipt_needed('files.adopt', ('project_operation', 'new')), 'The new receipt is always checked') - self.assertTrue(delta.receipt_needed('unclassified.operation', ('project_operation', 'old')), 'Unknown receipts are always checked') - runtime = ValidationDelta(frozenset({('project_operation', 'new')}), frozenset({'runtime.capture'})) - self.assertTrue(runtime.receipt_needed('runtime.abandon', ('project_operation', 'old')), 'Shared key spaces are re-checked') - self.assertFalse(runtime.receipt_needed('studies.save', ('project_operation', 'old'))) - self.assertTrue(ValidationDelta(frozenset(), frozenset({'studies.save'})).history_receipt_added()) - - -class ScopedValidation(unittest.TestCase): - def validate(self, records, delta): - with edit_delta(delta): - validate_project_records(records, project_id=PROJECT, artifacts=None) - - def test_touched_component_still_rejects_an_invalid_change(self): - with self.assertRaises(WorkbenchError): - self.validate([BROKEN_TEXT], ValidationDelta(frozenset({('workbench_text', 'broken')}))) - with self.assertRaises(WorkbenchError): - validate_project_records([BROKEN_TEXT], project_id=PROJECT, artifacts=None) - - def test_untouched_component_is_not_revalidated(self): - # The base checkpoint is assumed validated; an unrelated edit skips data. - with patch.dict(os.environ, {'TULDOK_VALIDATION_CROSSCHECK': '0'}): - self.validate([BROKEN_TEXT], ValidationDelta(frozenset({('project_file', 'other')}))) - - def test_crosscheck_reports_a_skipped_failure(self): - # Only possible when the 'validated base' assumption is violated, as here. - with patch.dict(os.environ, {'TULDOK_VALIDATION_CROSSCHECK': '1'}): - with self.assertRaisesRegex(AssertionError, 'disagrees'): - self.validate([BROKEN_TEXT], ValidationDelta(frozenset({('project_file', 'other')}))) - - def test_identity_and_claim_checks_always_run(self): - duplicate = [BROKEN_TEXT, dict(BROKEN_TEXT)] - with self.assertRaises(WorkbenchError): - self.validate(duplicate, ValidationDelta(frozenset({('project_file', 'other')}))) - unknown = [dict(family='unclaimed_family', id='x', document={})] - with self.assertRaises(WorkbenchError): - self.validate(unknown, ValidationDelta(frozenset({('project_file', 'other')}))) - - -if __name__ == '__main__': - unittest.main() diff --git a/tests/test_project_working_store.py b/tests/test_project_working_store.py deleted file mode 100644 index d943af12..00000000 --- a/tests/test_project_working_store.py +++ /dev/null @@ -1,231 +0,0 @@ -"""Database working copy of an external project: import, commit, save.""" -import copy -import os -from pathlib import Path -import shutil -import tempfile -import unittest -import uuid -from unittest.mock import patch - -import project_store as store_module -from project_store import ProjectStore, ProjectStoreError -from project_working_store import WorkingProjectStore - - -def note(identity, text): - return dict(family='workbench_text', id=identity, - document=dict(format='workbench_text_v1', text=text, history=[])) - - -@unittest.skipUnless(os.environ.get('TULDOK_DATABASE_URL'), 'Requires disposable PostgreSQL') -class WorkingProjectStoreTests(unittest.TestCase): - def setUp(self): - temporary = tempfile.TemporaryDirectory(prefix='tuldok-working-store-') - self.addCleanup(temporary.cleanup) - self.root = Path(temporary.name) - self.folder_path = self.root / 'project' - store = ProjectStore.create(self.folder_path, 'Working fixture', 'new', 'a' * 64) - self.records = [note('one', 'Alpha ☃'), note('two', 'Beta "quoted"\nline'), note('three', 'Gamma')] - self.initial = store.commit(self.records, store.summary()['checkpoint'], 'seed', 'b' * 64) - store.close() - self.working_id = uuid.uuid4().hex - self.addCleanup(self.drop_schema) - self.opened = [] - self.addCleanup(lambda: [store.close() for store in self.opened]) - - def drop_schema(self): - import psycopg - from psycopg import sql - from metadata import connection_info - with psycopg.connect(connection_info(None), autocommit=True) as connection: - connection.execute(sql.SQL('DROP SCHEMA IF EXISTS {} CASCADE').format( - sql.Identifier('working_' + self.working_id))) - - def folder(self): - parent, leaf = os.path.split(str(self.folder_path)) - descriptor = os.open(parent, store_module.DIR_FLAGS) - try: - return ProjectStore.open_folder_at(descriptor, leaf, root_path=parent) - finally: - os.close(descriptor) - - def open(self): - store = WorkingProjectStore.open(self.folder(), self.working_id) - self.opened.append(store) - return store - - def reopen(self, store): - store.close() - return self.open() - - def file_snapshot(self): - with ProjectStore.open(self.folder_path) as store: - return store.snapshot() - - def test_import_matches_the_file_store_exactly(self): - store = self.open() - self.assertEqual(store.snapshot(), self.initial) - self.assertEqual(store.summary(), {k: self.initial[k] for k in ('project_id', 'name', 'checkpoint')}) - self.assertFalse(store.dirty()) - self.assertEqual(store.records('workbench_text'), self.initial['records']) - self.assertEqual(store.record('workbench_text', 'two'), self.initial['records'][2]) - self.assertIsNone(store.record('workbench_text', 'absent')) - - def test_unchanged_folder_reattaches_without_reading_records(self): - store = self.open() - store.close() - with patch.object(ProjectStore, 'folder_record', side_effect=AssertionError('Record file read')): - again = self.open() - self.assertEqual(again.snapshot(), self.initial) - - def test_commit_stays_in_database_and_matches_file_store_identity(self): - store = self.open() - before_files = sorted(p.relative_to(self.folder_path) for p in self.folder_path.rglob('*')) - before_checkpoint = (self.folder_path / '.tuldok/project.json').read_bytes() - changed = copy.deepcopy(self.records) - changed[1]['document']['text'] = 'Edited in Tuldok' - changed.append(note('four', 'Delta')) - committed = store.commit(changed, self.initial['checkpoint'], 'edit', 'c' * 64) - self.assertTrue(store.dirty()) - self.assertEqual(sorted(p.relative_to(self.folder_path) for p in self.folder_path.rglob('*')), before_files) - self.assertEqual((self.folder_path / '.tuldok/project.json').read_bytes(), before_checkpoint) - # The same commit on a file store yields the identical checkpoint. - mirror = self.root / 'mirror' - shutil.copytree(self.folder_path, mirror) - with ProjectStore.open(mirror) as file_store: - expected = file_store.commit(copy.deepcopy(changed), self.initial['checkpoint'], 'edit', 'c' * 64) - self.assertEqual(committed['checkpoint'], expected['checkpoint']) - self.assertEqual(store.snapshot(), expected) - reopened = self.reopen(store) - self.assertEqual(reopened.snapshot(), expected, 'Unsaved work persists across sessions') - self.assertTrue(reopened.dirty()) - - def test_changed_hint_and_exact_comparison_agree(self): - store = self.open() - changed = copy.deepcopy(self.records) - changed[0]['document']['text'] = 'Hinted change' - hinted = store.commit(changed, self.initial['checkpoint'], 'hinted', 'd' * 64, - changed={('workbench_text', 'one')}) - store.close() - other = WorkingProjectStore.open(self.folder(), uuid.uuid4().hex) - self.addCleanup(lambda: self._drop(other)) - exact = other.commit(copy.deepcopy(changed), self.initial['checkpoint'], 'hinted', 'd' * 64) - self.assertEqual(hinted['checkpoint'], exact['checkpoint']) - - def _drop(self, store): - schema = store.schema - store.close() - import psycopg - from psycopg import sql - from metadata import connection_info - with psycopg.connect(connection_info(None), autocommit=True) as connection: - connection.execute(sql.SQL('DROP SCHEMA IF EXISTS {} CASCADE').format(sql.Identifier(schema))) - - def test_save_exports_byte_identical_files(self): - store = self.open() - changed = copy.deepcopy(self.records) - changed[2]['document']['text'] = 'Saved change' - committed = store.commit(changed, self.initial['checkpoint'], 'edit', 'e' * 64) - store.save(committed['checkpoint']) - self.assertFalse(store.dirty()) - saved = store.snapshot() - store.close() - self.assertEqual(self.file_snapshot(), saved) - with patch.object(ProjectStore, 'folder_record', side_effect=AssertionError('Re-import after own save')): - self.assertEqual(self.open().snapshot(), saved) - - def test_clean_working_copy_imports_only_changed_external_records(self): - store = self.open() - store.close() - with ProjectStore.open(self.folder_path) as file_store: - changed = copy.deepcopy(self.records) - changed[0]['document']['text'] = 'Changed outside Tuldok' - external = file_store.commit(changed, self.initial['checkpoint'], 'outside', 'f' * 64) - reads = [] - original = ProjectStore.folder_record - def observe(folder, entry): - reads.append(entry['id']) - return original(folder, entry) - with patch.object(ProjectStore, 'folder_record', observe): - store = self.open() - self.assertEqual(reads, ['one']) - self.assertEqual(store.snapshot(), external) - - def test_external_change_with_unsaved_work_is_an_explicit_conflict(self): - store = self.open() - changed = copy.deepcopy(self.records) - changed[0]['document']['text'] = 'Unsaved' - committed = store.commit(changed, self.initial['checkpoint'], 'unsaved', '1' * 64) - store.close() - with ProjectStore.open(self.folder_path) as file_store: - other = copy.deepcopy(self.records) - other[1]['document']['text'] = 'Outside' - file_store.commit(other, self.initial['checkpoint'], 'outside', '2' * 64) - with self.assertRaises(ProjectStoreError) as caught: - self.open() - self.assertEqual(caught.exception.code, 'conflict') - - def test_save_refuses_to_overwrite_an_external_change(self): - store = self.open() - changed = copy.deepcopy(self.records) - changed[0]['document']['text'] = 'Unsaved' - committed = store.commit(changed, self.initial['checkpoint'], 'unsaved', '3' * 64) - external = (self.folder_path / '.tuldok/project.json') - before = external.read_bytes() - # Simulate a checkout replacing project.json while Tuldok holds the folder. - raw = before.replace(b'"Working fixture"', b'"Renamed outside"') - external.chmod(0o600) - external.write_bytes(raw) - with self.assertRaises(ProjectStoreError) as caught: - store.save(committed['checkpoint']) - self.assertEqual(caught.exception.code, 'conflict') - self.assertEqual(external.read_bytes(), raw) - - def test_second_session_on_the_same_working_copy_is_busy(self): - self.open() - with self.assertRaises(ProjectStoreError) as caught: - WorkingProjectStore(self.folder(), self.working_id) - self.assertEqual(caught.exception.code, 'busy') - - def test_receipt_replay_and_stale_checkpoint(self): - store = self.open() - changed = copy.deepcopy(self.records) - changed[0]['document']['text'] = 'Once' - first = store.commit(changed, self.initial['checkpoint'], 'once', '4' * 64) - self.assertEqual(store.commit(copy.deepcopy(changed), first['checkpoint'], 'once', '4' * 64)['checkpoint'], - first['checkpoint']) - self.assertIsNotNone(store.reconcile('once', '4' * 64)) - with self.assertRaises(ProjectStoreError) as caught: - store.commit(changed, self.initial['checkpoint'], 'later', '5' * 64) - self.assertEqual(caught.exception.code, 'stale') - - def test_envelope_digests_equal_canonical_envelope_hashes(self): - from project_composition import _record_sha, known_envelope_digests - store = self.open() - changed = copy.deepcopy(self.records) - changed[0]['document']['text'] = 'Committed after import' - store.commit(changed, self.initial['checkpoint'], 'edit', '6' * 64) - digests = store.envelope_digests() - snapshot = store.snapshot() - self.assertEqual(set(digests), {(r['family'], r['id']) for r in snapshot['records']}) - for record in snapshot['records']: - self.assertEqual(digests[(record['family'], record['id'])], _record_sha(record)) - # A supplied digest applies only to that exact object. - record = snapshot['records'][0] - with known_envelope_digests({id(record): (record, 'f' * 64)}): - self.assertEqual(_record_sha(record), 'f' * 64) - self.assertNotEqual(_record_sha(copy.deepcopy(record)), 'f' * 64) - store._execute(store._q('UPDATE {records} SET envelope_sha256=NULL')) - self.assertEqual(store.envelope_digests(), digests, 'Missing digests are recomputed from stored bytes') - - def test_verify_records_detects_working_copy_corruption(self): - store = self.open() - store.verify_records() - store._execute(store._q("UPDATE {records} SET raw = convert_to(replace(convert_from(raw, 'UTF8'), 'Gamma', 'Omega'), 'UTF8') WHERE id='three'")) - with self.assertRaises(ProjectStoreError): - store.verify_records() - - -if __name__ == '__main__': - unittest.main() diff --git a/tests/test_project_workspace.py b/tests/test_project_workspace.py deleted file mode 100644 index aa0b5c4d..00000000 --- a/tests/test_project_workspace.py +++ /dev/null @@ -1,350 +0,0 @@ -"""Workspace recovery/replay boundaries over disposable real PostgreSQL projections.""" -import copy -import errno -import json -import os -from pathlib import Path -import sys -import tempfile -import unittest -from unittest.mock import patch -import uuid - -import psycopg -from psycopg import sql - -sys.path.insert(0, str(Path(__file__).resolve().parents[1])) -from auth_helpers import ExplicitOwnerFixture -from metadata import connection_info -import project_store -from project_store import ProjectStore, ProjectStoreError -from project_workspace import ProjectWorkspace, _digest -from workbench import WorkbenchError - - -@unittest.skipUnless(os.environ.get('TULDOK_DATABASE_URL'), 'Requires disposable local PostgreSQL') -class ProjectWorkspaceTests(unittest.TestCase): - def setUp(self): - self.tmp = tempfile.TemporaryDirectory(prefix='tuldok-project-workspace-') - self.path = Path(self.tmp.name) - self.external = self.path / 'external' - self.external.mkdir() - self.hosts = [] - self.addCleanup(self.tmp.cleanup) - self.addCleanup(self.cleanup_owned) - self.start() - - def start(self, control=None): - control = control or self.path / ('control-' + uuid.uuid4().hex) - workspace = ProjectWorkspace(control, {'fixture': self.external}, dsn=os.environ['TULDOK_DATABASE_URL']) - owner = ExplicitOwnerFixture.bootstrap(workspace) - self.hosts.append((workspace, owner, control)) - self.workspace, self.owner = workspace, owner - - def cleanup_owned(self): - schemas = set() - for workspace, _owner, control in reversed(self.hosts): - workspace.close() - for manifest in Path(control).rglob('.tuldok.json'): - value = json.loads(manifest.read_bytes()) - schemas.add('projection_' + value['projection_id'] if value['version'] == 2 - else 'catalog_' + value['dataset_id']) - from project_working_store import registered_schemas - schemas.update(registered_schemas(control)) - with psycopg.connect(connection_info(), autocommit=True) as connection: - for schema in schemas: - connection.execute(sql.SQL('DROP SCHEMA IF EXISTS {} CASCADE').format(sql.Identifier(schema))) - - def call(self, action, arguments=None): - with self.owner.bound(self.workspace): - return self.workspace.dispatch('project_files.' + action, arguments or {}) - - def state(self): - return self.call('status') - - def mutation(self, state=None, **extra): - state = state or self.state() - result = dict(binding=state['binding'], - expected_checkpoint=state['project']['checkpoint'] if state['project'] else None, - request_key=uuid.uuid4().hex) - result.update(extra) - return result - - def create(self, directory='alpha'): - arguments = self.mutation(root='fixture', directory=directory, name='Workspace authored project') - return self.call('new', arguments), arguments - - def test_status_returns_current_metadata_without_copying_the_record_graph(self): - self.create() - self.import_record('A retained record unrelated to the project summary') - expected = self.state() - with patch.object(self.workspace._store, 'snapshot', - wraps=self.workspace._store.snapshot) as snapshots: - observed = self.state() - self.assertEqual(observed, expected) - self.assertEqual(snapshots.call_count, 0, - 'Status must not copy every retained record to return three metadata fields') - - def test_control_project_ancestry_is_rejected_before_destination_or_projection_creation(self): - with ProjectStore.create(self.external/'science','Existing portable project','existing-project','b'*64):pass - self.start(self.external/'science/control') - control=self.workspace.path - for action,directory in (('open','science'),('new','science/control/child')): - arguments=self.mutation(root='fixture',directory=directory) - if action=='new':arguments['name']='Must not create' - with self.subTest(action=action),self.assertRaisesRegex(ProjectStoreError,'private workspace control') as caught: - self.call(action,arguments) - self.assertEqual(caught.exception.code,'conflict') - self.assertIsNone(self.workspace._projection) - self.assertFalse((control/'.project-projections').exists()) - self.assertFalse((control/'child').exists()) - self.start(self.external/'sibling-control') - created,_=self.create('safe-project') - before=self.workspace._store.snapshot() - bad=self.mutation(root='fixture',directory='sibling-control/child',name='Must not fork') - with self.assertRaisesRegex(ProjectStoreError,'private workspace control') as caught: - self.call('save_as',bad) - self.assertEqual(caught.exception.code,'conflict') - self.assertFalse((self.workspace.path/'child').exists()) - self.assertEqual(self.workspace._store.snapshot(),before) - fork=self.call('save_as',self.mutation(root='fixture',directory='safe-copy',name='Sibling copy')) - self.assertEqual(fork['state']['state'],'open') - self.assertNotEqual(fork['state']['project']['project_id'],created['project']['project_id']) - - def import_record(self, text='Authored source'): - arguments = self.mutation(asset=dict(text=text, name='Source', groups=['owned'], rights='Fixture authorship')) - return self.call('import_text', arguments), arguments - - def annotate(self, row, note='Reviewed note'): - arguments = self.mutation(record_id=row['id'], annotation=dict( - revision=row['revision'], source_revision=1, task='text_corpus', - annotation={'note': note}, groups=['owned'], review='human_reviewed')) - return self.call('annotate', arguments), arguments - - def assert_code(self, code, action, arguments): - with self.assertRaises((WorkbenchError, ProjectStoreError)) as caught: - self.call(action, arguments) - self.assertEqual(caught.exception.code, code) - return caught.exception - - def unknown_import(self): - """Commit an edit whose PostgreSQL COMMIT acknowledgement is lost. - - Records and projection rows commit together in the database working - copy, so the only uncertain outcome is a lost commit acknowledgement. - """ - from contextlib import contextmanager - from metadata import CommitOutcomeUnknown - before = self.state() - arguments = self.mutation(before, asset=dict(text='Uncertain publication', groups=['owned'])) - db = self.workspace._projection.db - real = db.transaction - @contextmanager - def lost_acknowledgement(*args, **kwargs): - outermost = not db._rollback - with real(*args, **kwargs) as value: - yield value - if outermost: - raise CommitOutcomeUnknown('fixture lost COMMIT acknowledgement') - with patch.object(db, 'transaction', lost_acknowledgement): - self.assert_code('unknown', 'import_text', arguments) - return before, arguments - - def test_unknown_fsync_status_and_explicit_current_open_reconcile_canonical_edit(self): - self.create() - before, edit = self.unknown_import() - recovery = self.state() - self.assertEqual(recovery['state'], 'recovery_required') - self.assertEqual(recovery['binding'], before['binding']) - self.assertEqual(recovery['project'], before['project']) - self.assertEqual(recovery['available_actions'], ['open']) - self.assertEqual(recovery['recovery'], dict(action='open', root='fixture', directory='alpha', - reason='unknown_publication', request_key=edit['request_key'])) - self.assert_code('projection_unavailable', 'close', self.mutation(recovery)) - self.assert_code('stale_project', 'open', self.mutation(recovery, root='fixture', directory='alpha', - expected_checkpoint='a' * 64)) - opened = self.call('open', self.mutation(recovery, root='fixture', directory='alpha')) - self.assertEqual(opened['state'], 'open') - self.assertNotEqual(opened['binding'], before['binding']) - self.assertNotEqual(opened['project']['checkpoint'], before['project']['checkpoint']) - replay = dict(edit, binding=opened['binding']) - result = self.call('import_text', replay) - self.assertEqual(result['record']['text'], 'Uncertain publication') - self.assertEqual(result['record']['revision'], 1) - with self.owner.bound(self.workspace): - self.assertEqual(len(self.workspace._text.records()['items']), 1) - - def test_unknown_recovery_does_not_succeed_until_the_working_copy_is_available(self): - self.create() - _before, edit = self.unknown_import() - recovery = self.state() - old_projection = self.workspace._projection - reopen = self.mutation(recovery, root='fixture', directory='alpha') - from project_working_store import WorkingProjectStore - with patch.object(WorkingProjectStore, 'open', - side_effect=project_store.ProjectStoreError('Local PostgreSQL is unavailable.', 'unavailable', 503)): - self.assert_code('unavailable', 'open', reopen) - self.assertEqual(self.state(), recovery) - self.assertIs(self.workspace._projection, old_projection) - opened = self.call('open', reopen) - self.assertEqual(opened['state'], 'open') - self.assertEqual(self.call('import_text', dict(edit, binding=opened['binding']))['record']['revision'], 1) - - def test_new_reconciliation_does_not_select_before_failed_parent_barrier_succeeds(self): - before = self.state() - arguments = self.mutation(before, root='fixture', directory='created', name='Await durable New') - parent = self.external.stat() - fsync = project_store.os.fsync - def fail_published_parent(fd): - info = os.fstat(fd) - if ((info.st_dev, info.st_ino) == (parent.st_dev, parent.st_ino) - and (self.external / 'created').exists()): - raise OSError(errno.EIO, 'persistent New parent directory fsync failure') - return fsync(fd) - with patch.object(project_store.os, 'fsync', side_effect=fail_published_parent): - self.assert_code('unavailable', 'new', arguments) - self.assertEqual(self.state(), before) - with ProjectStore.open(self.external / 'created') as created: - expected = created.snapshot() - selected = self.call('new', arguments) - self.assertEqual(selected['project']['project_id'], expected['project_id']) - self.assertEqual(selected['project']['checkpoint'], expected['checkpoint']) - - def test_rejected_sql_commit_rolls_back_records_and_projection_together(self): - self.create() - before = self.state() - projection = self.workspace._projection - projection.execute("""CREATE FUNCTION fixture_workspace_refuse_commit() RETURNS trigger LANGUAGE plpgsql AS $$ - BEGIN RAISE EXCEPTION 'fixture deferred rejection' USING ERRCODE='23514'; END $$""") - projection.execute("""CREATE CONSTRAINT TRIGGER fixture_workspace_commit_failure AFTER INSERT ON workbench_records - DEFERRABLE INITIALLY DEFERRED FOR EACH ROW EXECUTE FUNCTION fixture_workspace_refuse_commit()""") - arguments = self.mutation(before, asset=dict(text='Rejected with its SQL commit', groups=['owned'])) - with self.assertRaises(Exception): - self.call('import_text', arguments) - # Nothing was committed: same checkpoint, no records, still open. - self.assertEqual(self.state(), before) - self.assertEqual(self.workspace._store.summary()['checkpoint'], before['project']['checkpoint']) - self.assertEqual(projection.execute('SELECT count(*) FROM workbench_records').fetchone()[0], 0) - projection.execute('DROP TRIGGER fixture_workspace_commit_failure ON workbench_records') - result = self.call('import_text', arguments) - self.assertEqual(result['record']['text'], 'Rejected with its SQL commit') - self.assertEqual(projection.execute('SELECT count(*) FROM workbench_records').fetchone()[0], 1) - - def test_failed_reconstruction_keeps_recovery_generation_and_old_projection(self): - self.create() - before, edit = self.unknown_import() - projection = self.workspace._projection - recovery = self.state() - arguments = self.mutation(recovery, root='fixture', directory='alpha') - with patch.object(self.workspace, '_projection_for', side_effect=WorkbenchError('SQL unavailable', 'projection_unavailable', 503)): - self.assert_code('projection_unavailable', 'open', arguments) - self.assertIs(self.workspace._projection, projection) - self.assertEqual(self.state(), recovery) - opened = self.call('open', arguments) - self.assertEqual(opened['state'], 'open') - self.assertNotEqual(opened['binding'], before['binding']) - self.assertEqual(self.call('import_text', dict(edit, binding=opened['binding']))['record']['revision'], 1) - - def test_new_projection_failure_reports_created_unselected_and_exact_retry(self): - before = self.state() - arguments = self.mutation(before, root='fixture', directory='created', name='Created unselected') - with patch.object(self.workspace, '_projection_for', side_effect=RuntimeError('Projection initialization failed')): - failure = self.assert_code('project_selection_unavailable', 'new', arguments) - self.assertEqual(self.state(), before) - self.assertEqual(failure.receipt, dict(committed=True, selected=False, project_id=failure.project_id, - checkpoint=failure.checkpoint, request_key=arguments['request_key'], root='fixture', directory='created')) - with ProjectStore.open(self.external / 'created') as retained: - self.assertEqual(retained.snapshot()['project_id'], failure.project_id) - selected = self.call('new', arguments) - self.assertEqual(selected['project']['project_id'], failure.project_id) - self.assertEqual(selected['project']['checkpoint'], failure.checkpoint) - - def test_new_detach_failure_keeps_original_and_reconciles_after_restart(self): - original, _ = self.create('original') - arguments = self.mutation(root='fixture', directory='created', name='New survives failed Close') - with patch.object(self.workspace, '_detach', side_effect=WorkbenchError('Close barrier failed', 'unavailable', 503)): - failure = self.assert_code('project_selection_unavailable', 'new', arguments) - self.assertEqual(self.state(), original) - self.workspace.close() - self.start() - restarted = self.mutation(root='fixture', directory='created', name=arguments['name'], request_key=arguments['request_key']) - selected = self.call('new', restarted) - self.assertEqual(selected['project']['project_id'], failure.project_id) - - def test_new_receipt_rejects_changed_semantics_and_unrelated_existing_folder(self): - arguments = self.mutation(root='fixture', directory='created', name='Original name') - with patch.object(self.workspace, '_projection_for', side_effect=RuntimeError('Projection failed')): - self.assert_code('project_selection_unavailable', 'new', arguments) - before = (self.external / 'created/.tuldok/project.json').read_bytes() - self.assert_code('conflict', 'new', dict(arguments, name='Changed name')) - self.assertEqual((self.external / 'created/.tuldok/project.json').read_bytes(), before) - with ProjectStore.create(self.external / 'unrelated', 'Other owner', 'unrelated', 'b' * 64): - pass - other = self.mutation(root='fixture', directory='unrelated', name='Original name') - self.assert_code('conflict', 'new', other) - self.assertEqual(self.state()['state'], 'no_project_open') - - def test_lifecycle_replay_is_idempotent_only_while_resulting_state_is_current(self): - created, create_args = self.create() - self.assertEqual(self.call('new', create_args), created) - self.assert_code('conflict', 'new', dict(create_args, name='Changed payload')) - imported, _ = self.import_record() - self.assert_code('stale_project', 'new', create_args) - save_args = self.mutation() - saved = self.call('save', save_args) - self.assertEqual(self.call('save', save_args), saved) - updated, _ = self.annotate(imported['record']) - self.assert_code('stale_project', 'save', save_args) - close_args = self.mutation() - closed = self.call('close', close_args) - self.assertEqual(self.call('close', close_args), closed) - open_args = self.mutation(root='fixture', directory='alpha') - opened = self.call('open', open_args) - self.assertEqual(self.call('open', open_args), opened) - self.assertEqual(opened['state'], 'open') - self.assert_code('stale_project', 'close', close_args) - self.assertEqual(self.state(), opened) - self.call('close', self.mutation()) - self.assert_code('stale_project', 'open', open_args) - self.assertEqual(updated['record']['revision'], 2) - - def test_replay_history_never_exceeds_original_returned_revision(self): - self.create() - imported, import_args = self.import_record() - annotated, annotate_args = self.annotate(imported['record']) - self.annotate(annotated['record'], 'Third revision') - original = self.call('import_text', import_args) - self.assertEqual(original['record']['revision'], 1) - self.assertEqual([item['revision'] for item in original['history']], [1]) - self.assertIsNone(original['next_history_before_revision']) - original_review = self.call('annotate', annotate_args) - self.assertEqual(original_review['record']['revision'], 2) - self.assertEqual([item['revision'] for item in original_review['history']], [2]) - self.assertEqual(original_review['next_history_before_revision'], 2) - - def test_query_and_history_pages_are_bounded_and_complete(self): - self.create() - first, _ = self.import_record('First source') - second, _ = self.import_record('Second source') - current = self.state() - query = dict(binding=current['binding'], checkpoint=current['project']['checkpoint'], limit=1) - page = self.call('query', query) - self.assertEqual(len(page['items']), 1) - self.assertNotIn('text', page['items'][0]) - self.assertNotIn('annotation', page['items'][0]) - other = self.call('query', dict(query, after_id=page['next_after_id'])) - self.assertIsNone(other['next_after_id']) - self.assertEqual({page['items'][0]['id'], other['items'][0]['id']}, {first['record']['id'], second['record']['id']}) - changed, _ = self.annotate(first['record']) - self.annotate(changed['record'], 'Revision three') - current = self.state() - get = dict(binding=current['binding'], checkpoint=current['project']['checkpoint'], record_id=first['record']['id'], history_limit=2) - detail = self.call('get', get) - self.assertEqual([item['revision'] for item in detail['history']], [3, 2]) - older = self.call('get', dict(get, before_revision=detail['next_history_before_revision'])) - self.assertEqual([item['revision'] for item in older['history']], [1]) - self.assertIsNone(older['next_history_before_revision']) - - -if __name__ == '__main__': - unittest.main() diff --git a/tests/test_project_workspace_custody.py b/tests/test_project_workspace_custody.py deleted file mode 100644 index b22a9b1f..00000000 --- a/tests/test_project_workspace_custody.py +++ /dev/null @@ -1,197 +0,0 @@ -"""Flag-gated real Workspace custody boundaries, PostgreSQL and loopback HTTP. - -These tests do not qualify public M3 availability. A real local provider remains -active while an actual canonical commit loses its acknowledgement. Fault patches -inject only the acknowledgement failure; owners and dispatch remain production. -""" -import fcntl -from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer -import json -import os -from pathlib import Path -import tempfile -import threading -import unittest -from unittest.mock import patch -from urllib.error import HTTPError -from urllib.request import Request, urlopen -import uuid - -import psycopg -from psycopg import sql - -import agent_api -from app import make_handler -from auth_helpers import ExplicitOwnerFixture -from metadata import connection_info -from project_store import ProjectStoreError -import project_workspace -from workbench import WorkbenchError, encode - - -@unittest.skipUnless(os.environ.get('TULDOK_DATABASE_URL'), 'Requires disposable real PostgreSQL') -class ProjectWorkspaceCustodyTests(unittest.TestCase): - def setUp(self): - self.temp=tempfile.TemporaryDirectory(prefix='tuldok-workspace-custody-') - self.root=Path(self.temp.name);self.external=self.root/'external';self.external.mkdir() - self.provider_entered=threading.Event();self.provider_release=threading.Event() - self.provider_disconnected=threading.Event();self.provider_requests=[];self.worker_errors=[] - self.workspace=None;self.servers=[] - self.previous_hook=threading.excepthook - threading.excepthook=lambda event:self.worker_errors.append(event.exc_value) - self.addCleanup(self.cleanup) - self.flag=patch.object(project_workspace,'M3_ENABLED',True);self.flag.start() - self.workspace=project_workspace.ProjectWorkspace(self.root/'control',{'fixture':self.external}) - self.owner=ExplicitOwnerFixture.bootstrap(self.workspace) - fixture=self - class Provider(BaseHTTPRequestHandler): - def log_message(self,*args):pass - def send(self,value): - raw=encode(value).encode();self.send_response(200) - self.send_header('Content-Type','application/json');self.send_header('Content-Length',str(len(raw)));self.end_headers() - try:self.wfile.write(raw) - except (BrokenPipeError,ConnectionResetError):fixture.provider_disconnected.set() - def do_GET(self): - fixture.provider_requests.append(('GET',self.path)) - self.send({'data':[{'id':'fixture-model','owned_by':'fixture'}]}) - def do_POST(self): - fixture.provider_requests.append(('POST',self.path)) - self.rfile.read(int(self.headers.get('Content-Length','0'))) - fixture.provider_entered.set();fixture.provider_release.wait(20) - self.send({'model':'fixture-model','choices':[{'finish_reason':'stop','message':{'content':encode({'label':'positive'})}}]}) - self.provider=self.server(Provider) - self.provider_url='http://127.0.0.1:'+str(self.provider.server_port) - self.application=self.server(make_handler(self.workspace)) - self.origin='http://127.0.0.1:'+str(self.application.server_port) - state=self.state() - status,state=self.call('new',dict(binding=state['binding'],expected_checkpoint=None,request_key=uuid.uuid4().hex, - root='fixture',directory='owned-project',name='Owned custody boundaries')) - self.assertEqual(status,200,state) - status,imported=self.call('data_import_text',self.envelope(text='Exact owned text café 山.',name='Owned source',groups=['owned'],parents=[],rights='Authored fixture')) - self.assertEqual(status,200,imported) - self.source=imported['value'] - - def server(self,handler): - server=ThreadingHTTPServer(('127.0.0.1',0),handler) - thread=threading.Thread(target=server.serve_forever,daemon=True);thread.start() - self.servers.append((server,thread));return server - - def call(self,action,body=None,*,token=None): - name='project_files.'+action;operation=agent_api.operation(name) - headers={'Origin':self.origin,'Content-Type':'application/json', - 'Authorization':'Bearer '+(token or self.owner.token), - 'Tuldok-Operation-Contract':agent_api.selected_header(name)} - request=Request(self.origin+operation['path'],data=None if body is None else encode(body).encode(),headers=headers,method=operation['method']) - try:response=urlopen(request,timeout=15) - except HTTPError as error:response=error - with response:return response.status,json.loads(response.read()) - - def state(self): - status,value=self.call('status');self.assertEqual(status,200,value);return value - - def envelope(self,**values): - state=self.state() - return dict(binding=state['binding'],expected_checkpoint=state['project']['checkpoint'],request_key=uuid.uuid4().hex,**values) - - def start_provider(self): - status,result=self.call('execution_producer_start',self.envelope(family='text_proposal_history',document=dict( - request_id=uuid.uuid4().hex,source_id=self.source['id'],revision=self.source['revision'],source_revision=self.source['source_revision'], - server_url=self.provider_url,model='fixture-model',instruction='Select only an exact offered label.',seed=7,labels=['positive','negative']))) - self.assertEqual(status,200,result) - self.assertTrue(self.provider_entered.wait(10),'Actual provider POST was not entered') - projection=self.workspace._projection;adapter=projection.execution.producer_execution - owner=adapter._owners['text_proposal_history'] - self.assertIsNone(projection.execution._runs) - self.assertTrue(owner.worker.is_alive());self.assertFalse(owner.stop.is_set()) - self.assertTrue(projection.custody.has_pending) - return projection,owner,result - - def assert_same_locked_selection(self,store,projection,root_fd,physical): - self.assertIs(self.workspace._store,store);self.assertIs(self.workspace._projection,projection) - self.assertEqual(store._root_fd,root_fd) - observed=os.fstat(root_fd);self.assertEqual((observed.st_dev,observed.st_ino),physical) - competing=os.open(self.external/'owned-project',os.O_RDONLY|os.O_DIRECTORY) - try: - with self.assertRaises(BlockingIOError):fcntl.flock(competing,fcntl.LOCK_EX|fcntl.LOCK_NB) - finally:os.close(competing) - self.assertFalse(projection.db.connection.closed) - - def stop_fixture_worker(self,owner): - # Explicit disposable-fixture disposal, not a successful application - # cancellation/recovery claim. Unknown provider cessation stays unknown. - owner.stop.set();self.provider_release.set();owner.worker.join(10) - self.assertFalse(owner.worker.is_alive()) - - def test_recovery_open_keeps_producer_only_store_projection_and_real_root_flock(self): - projection,owner,_=self.start_provider();state=self.state() - store=self.workspace._store;root_fd=store._root_fd;st=os.fstat(root_fd);physical=(st.st_dev,st.st_ino) - original=store.commit;injected=[] - def lost_ack(*args,**kwargs): - result=original(*args,**kwargs) - injected.append(result['checkpoint']) - raise ProjectStoreError('Authored canonical acknowledgement loss after actual commit','unknown',409) - with patch.object(store,'commit',lost_ack): - status,error=self.call('data_import_text',dict(binding=state['binding'],expected_checkpoint=state['project']['checkpoint'], - request_key=uuid.uuid4().hex,text='Canonical result selected before lost acknowledgement.',name='Lost reply source',groups=['owned'],parents=[],rights='Authored fault fixture')) - self.assertEqual(status,409,error);self.assertEqual(error['code'],'unknown');self.assertEqual(len(injected),1) - self.assertFalse(projection.session.available) - recovery=self.state();self.assertEqual(recovery['state'],'recovery_required') - self.assertTrue(owner.worker.is_alive());self.assertFalse(owner.stop.is_set()) - self.assert_same_locked_selection(store,projection,root_fd,physical) - arguments=dict(binding=recovery['binding'],expected_checkpoint=recovery['project']['checkpoint'],request_key=uuid.uuid4().hex,root='fixture',directory='owned-project') - status,error=self.call('open',arguments) - self.assertEqual(status,503,error);self.assertEqual(error['code'],'projection_unavailable') - self.assertTrue(owner.worker.is_alive());self.assertFalse(owner.stop.is_set()) - self.assert_same_locked_selection(store,projection,root_fd,physical) - # The old local provider thread can drain without any Run owner, yet no - # generic provider cessation receipt exists. Recovery remains fenced. - self.stop_fixture_worker(owner) - status,error=self.call('open',dict(arguments,request_key=uuid.uuid4().hex)) - self.assertEqual(status,503,error);self.assertEqual(error['code'],'projection_unavailable') - self.assertTrue(projection.custody.has_pending) - self.assert_same_locked_selection(store,projection,root_fd,physical) - self.assertIsNone(projection.execution._runs) - - def test_normal_stale_reconcile_checkpoint_refuses_before_any_provider_drain(self): - projection,owner,_=self.start_provider();stale=self.state() - store=self.workspace._store;root_fd=store._root_fd;st=os.fstat(root_fd);physical=(st.st_dev,st.st_ino) - status,changed=self.call('data_import_text',dict(binding=stale['binding'],expected_checkpoint=stale['project']['checkpoint'], - request_key=uuid.uuid4().hex,text='A later canonical edit.',name='Later source',groups=['owned'],parents=[],rights='Authored fixture')) - self.assertEqual(status,200,changed);self.assertNotEqual(changed['checkpoint'],stale['project']['checkpoint']) - before=store.snapshot();thread=owner.worker - status,error=self.call('execution_reconcile_current',dict(binding=stale['binding'],expected_checkpoint=stale['project']['checkpoint'])) - self.assertEqual(status,409,error);self.assertEqual(error['code'],'stale_project') - self.assertIs(owner.worker,thread);self.assertTrue(thread.is_alive());self.assertFalse(owner.stop.is_set()) - self.assertFalse(self.provider_release.is_set());self.assertFalse(self.provider_disconnected.is_set()) - self.assertEqual(store.snapshot(),before) - self.assertEqual(self.state()['state'],'open') - self.assert_same_locked_selection(store,projection,root_fd,physical) - self.assertEqual(self.provider_requests,[('GET','/v1/models'),('POST','/v1/chat/completions')]) - - def cleanup(self): - try: - if self.workspace is not None: - projection=self.workspace._projection - if projection is not None: - adapter=projection.execution.producer_execution - for owner in adapter._owners.values(): - if owner.worker is not None and owner.worker.is_alive():self.stop_fixture_worker(owner) - self.provider_release.set() - for server,thread in reversed(self.servers):server.shutdown();server.server_close();thread.join(3) - # Production correctly refuses Close for unresolved generic provider - # effects. Dispose only the test-owned handles after actual joins. - if self.workspace is not None: - ws=self.workspace - schemas=[ws.db.schema] - if ws._projection is not None: - schemas.append(ws._projection.db.schema) - ws._projection.artifacts.close();ws._projection.db.close() - if ws._store is not None:ws._store.close() - for _path,descriptor in ws._roots.values():os.close(descriptor) - ws._roots.clear();ws.db.close();ws._closed=True - with psycopg.connect(connection_info(),autocommit=True) as connection: - for schema in schemas:connection.execute(sql.SQL('DROP SCHEMA IF EXISTS {} CASCADE').format(sql.Identifier(schema))) - self.assertTrue(all(isinstance(error,(WorkbenchError,ValueError)) for error in self.worker_errors),self.worker_errors) - finally: - threading.excepthook=self.previous_hook - self.flag.stop();self.temp.cleanup() diff --git a/tests/test_retained_measurements.py b/tests/test_retained_measurements.py deleted file mode 100644 index a56a19d6..00000000 --- a/tests/test_retained_measurements.py +++ /dev/null @@ -1,154 +0,0 @@ -"""Source-bound scalar, complete-denominator and closed-query decisions.""" -import base64 -import copy -import hashlib -import json -from pathlib import Path -import struct -import sys -import unittest - -sys.path.insert(0,str(Path(__file__).resolve().parents[1])) -from retained_measurements import MeasurementTable, decode, digest, encode -from workbench import WorkbenchError - - -def source(identity,value,kind='json'): - raw=encode(value) if kind=='json' else value - return {'id':identity,'label':identity,'kind':kind,'bytes':len(raw), - 'sha256':hashlib.sha256(raw).hexdigest(),'data_base64':base64.b64encode(raw).decode('ascii')} - - -def ref(pointer,hashed=None): - result={'source_id':'context','pointer':pointer} - if hashed is not None:result['sha256']=digest(hashed) - return result - - -def fixture(): - scope={'id':'consumed','label':'Retained consumed diagnostics','population':'consumed', - 'task':'Fixture measurements, not scientific acceptance'} - metrics=[{'id':'error','label':'Declared error ratio','units':'1','description':'Exact retained scalar'}, - {'id':'latency','label':'Complete-call latency','units':'ms','description':'No qualified timing available'}] - context={'scope':scope,'metrics':metrics,'values':[1e-17,2e-15,0.01,0.02],'latency_claim':False} - doc={'format':'retained_measurements_v1','schema_version':1,'title':'Finite comparison fixture', - 'scope':{k:scope[k] for k in ('id','label','population')}, - 'dimensions':[{'id':'cpm','label':'Cells per metre','type':'number','units':'cells/m','scope':'case'}, - {'id':'grid_x','label':'Domain X cells','type':'integer','units':'cells','scope':'case'}, - {'id':'device','label':'Device','type':'string','units':None,'scope':'subject'}, - {'id':'passes','label':'Actual work','type':'integer','units':'passes','scope':'observation'}], - 'subjects':[{'id':i,'label':i,'dimensions':{'device':'GPU' if i=='a' else 'CPU'},'reference':ref('')} for i in ('a','b')], - 'cases':[{'id':'case1','dimensions':{'cpm':16,'grid_x':8},'reference':ref('')}, - {'id':'case2','dimensions':{'cpm':8,'grid_x':16},'reference':ref('')}], - 'metrics':[{**{k:m[k] for k in ('id','label','units')},'definition':ref('/metrics/'+str(i),m)} for i,m in enumerate(metrics)], - 'observations':[],'sources':[source('context',context),source('failure',b'Original failed timing attempt','opaque')]} - doc['scope']['definition']=ref('/scope',scope) - index=0 - for subject in ('a','b'): - for case in ('case1','case2'): - doc['observations'].append({'id':subject+'-'+case+'-error','subject_id':subject,'case_id':case,'metric_id':'error', - 'state':'measured','value':context['values'][index],'reason':None,'dimensions':{'passes':1 if subject=='a' else 2},'reference':ref('/values/'+str(index))}) - failed=subject=='b' and case=='case2' - doc['observations'].append({'id':subject+'-'+case+'-latency','subject_id':subject,'case_id':case,'metric_id':'latency', - 'state':'failed' if failed else 'unavailable','value':None, - 'reason':'Retained failure' if failed else 'No qualified timing', - 'dimensions':{'passes':1 if subject=='a' else 2}, - 'reference':{'source_id':'failure','pointer':None} if failed else ref('/latency_claim')}) - index+=1 - return doc - - -class RetainedMeasurementTests(unittest.TestCase): - def test_exact_tiny_values_density_and_grid_filters_and_detached_results(self): - doc=fixture();table=MeasurementTable(encode(doc));query=table.query('error') - self.assertEqual(query['total'],4);self.assertEqual(query['sampling'],'none') - self.assertEqual([r['maximum']['value'] for r in query['summary']],[2e-15,0.02]) - row=table.inspect('a-case1-error') - self.assertEqual(struct.pack('!d',row['observation']['value']),struct.pack('!d',1e-17)) - self.assertEqual(row['scalar_evidence']['value'],1e-17) - self.assertEqual(row['case_evidence']['state'],'included') - self.assertEqual(table.query('error',filters={'cpm':16})['rows'][0]['dimensions']['grid_x'],8) - self.assertEqual(table.query('error',filters={'grid_x':16})['rows'][0]['dimensions']['cpm'],8) - self.assertEqual(table.query('error',filters={'device':'CPU'})['total'],2) - self.assertEqual(table.query('error',filters={'passes':1})['summary'][1]['count'],0) - query['rows'][0]['value']=999;row['subject']['label']='wrong' - self.assertEqual(table.inspect('a-case1-error')['observation']['value'],1e-17) - self.assertEqual(table.subjects()['items'][0]['label'],'a') - self.assertEqual(table.subjects(offset=1,limit=1)['items'][0]['id'],'b') - self.assertEqual(table.subjects(offset=2)['items'],[]) - self.assertEqual(table.metadata()['subject_count'],2) - - def test_missing_and_failed_timings_are_explicit_not_zero_or_dropped(self): - table=MeasurementTable(encode(fixture()));query=table.query('latency',offset=1,limit=2) - self.assertEqual(query['total'],4);self.assertEqual(len(query['rows']),2) - self.assertTrue(all(v['maximum'] is None and v['count']==2 for v in query['summary'])) - self.assertEqual(query['summary'][1]['states'],{'measured':0,'failed':1,'unsupported':0,'unavailable':1}) - self.assertEqual(table.inspect('b-case2-latency')['source']['kind'],'opaque') - self.assertEqual(table.inspect('b-case2-latency')['scalar_evidence']['state'],'opaque') - - def test_missing_duplicate_and_unresolved_matrix_members_are_refused(self): - for mutation in ('missing','duplicate','unknown','malformed'): - doc=fixture() - if mutation=='missing':doc['observations'].pop() - if mutation=='duplicate':doc['observations'][-1]=copy.deepcopy(doc['observations'][0]);doc['observations'][-1]['id']='new-id' - if mutation=='unknown':doc['observations'][0]['case_id']='outside' - if mutation=='malformed':doc['observations'][0]['case_id']=[] - with self.subTest(mutation=mutation),self.assertRaises(WorkbenchError):MeasurementTable(encode(doc)) - - def test_measured_value_source_hash_and_definition_changes_are_refused(self): - for mutation in ('value','hash','definition','units','pointer','source-type','boolean','huge-integer'): - doc=fixture() - if mutation=='value':doc['observations'][0]['value']=0.5 - if mutation=='hash':doc['sources'][0]['sha256']='f'*64 - if mutation=='definition':doc['metrics'][0]['definition']['sha256']='f'*64 - if mutation=='units':doc['metrics'][0]['units']='s' - if mutation=='pointer':doc['observations'][0]['reference']['pointer']='/values/099' - if mutation=='source-type':doc['observations'][0]['reference']['source_id']=[] - if mutation=='boolean':doc['observations'][0]['value']=True - if mutation=='huge-integer':doc['observations'][0]['value']=10**400 - with self.subTest(mutation=mutation),self.assertRaises(WorkbenchError):MeasurementTable(encode(doc)) - - def test_null_status_reason_and_dimension_contracts_are_not_inferred(self): - for mutation in ('null-measured','non-null-missing','empty-reason','boolean-dimension','extra-dimension'): - doc=fixture() - if mutation=='null-measured':doc['observations'][0]['value']=None - if mutation=='non-null-missing':doc['observations'][1]['value']=0 - if mutation=='empty-reason':doc['observations'][1]['reason']='' - if mutation=='boolean-dimension':doc['cases'][0]['dimensions']['grid_x']=True - if mutation=='extra-dimension':doc['cases'][0]['dimensions']['unexpected']=1 - with self.subTest(mutation=mutation),self.assertRaises(WorkbenchError):MeasurementTable(encode(doc)) - - def test_nonfinite_underflow_duplicate_keys_and_unicode_are_refused(self): - for raw in (b'{"a":1,"a":2}',b'{"a":NaN}',b'{"a":1e999}',b'{"a":1e-999}',b'{"a":"\\ud800"}'): - with self.subTest(raw=raw),self.assertRaises(WorkbenchError):decode(raw) - self.assertEqual(struct.pack('!d',decode(b'{"a":5e-324}')['a']),struct.pack('!d',5e-324)) - - def test_query_rejects_unknown_selectors_and_never_executes_expressions(self): - table=MeasurementTable(encode(fixture())) - for args in ({'metric_id':[]},{'metric_id':'outside'},{'metric_id':'error','filters':{'grid_x':True}}, - {'metric_id':'error','filters':{'expression':'a > 0'}},{'metric_id':'error','subject_ids':['a','a']}, - {'metric_id':'error','offset':True},{'metric_id':'error','limit':101}): - with self.subTest(args=args),self.assertRaises(WorkbenchError):table.query(**args) - with self.assertRaises(WorkbenchError):table.inspect([]) - - def test_source_scalar_sign_and_pointer_escape_are_exact(self): - doc=fixture();original=json.loads(base64.b64decode(doc['sources'][0]['data_base64'])) - original['a/b~c']=-0.0;doc['sources'][0]=source('context',original) - doc['observations'][0]['value']=-0.0;doc['observations'][0]['reference']=ref('/a~1b~0c') - table=MeasurementTable(encode(doc)) - self.assertEqual(struct.pack('!d',table.inspect('a-case1-error')['observation']['value']),struct.pack('!d',-0.0)) - doc['observations'][0]['value']=0.0 - with self.assertRaisesRegex(WorkbenchError,'scalar'):MeasurementTable(encode(doc)) - - def test_source_and_complete_matrix_limits_refuse_before_expansion(self): - doc=fixture();doc['sources'][0]['bytes']=8*1024*1024+1 - with self.assertRaises(WorkbenchError) as error:MeasurementTable(encode(doc)) - self.assertEqual(error.exception.status,413) - doc=fixture();base=doc['subjects'][0] - doc['subjects']=[dict(copy.deepcopy(base),id='s'+str(i)) for i in range(128)] - base=doc['cases'][0];doc['cases']=[dict(copy.deepcopy(base),id='c'+str(i)) for i in range(1000)] - with self.assertRaises(WorkbenchError) as error:MeasurementTable(encode(doc)) - self.assertEqual(error.exception.status,413) - - -if __name__=='__main__':unittest.main() diff --git a/tests/test_torch_runtime.py b/tests/test_torch_runtime.py index 73beb56c..c0469772 100644 --- a/tests/test_torch_runtime.py +++ b/tests/test_torch_runtime.py @@ -90,8 +90,6 @@ def checkpoint(): self.assertEqual(len(calls),2) def test_retained_prelink_manifest_keeps_exact_hash_without_current_launch_authority(self): - from pipeline import digest - from project_material import decode_runtime_material manifest=runtime.inventory(self.config);manifest.pop('file_links') raw=runtime.encoded(manifest) descriptor=dict(schema_version=1,profile=runtime.PROFILE,catalog_id='a'*32, @@ -101,9 +99,6 @@ def test_retained_prelink_manifest_keeps_exact_hash_without_current_launch_autho runtime.verify_descriptor(descriptor,manifest) path=Path(self.temp.name)/'old-manifest.json';path.write_bytes(raw) with self.assertRaisesRegex(ValueError,'closed manifest'):runtime.load(path) - value=dict(ref=dict(kind='runtime',catalog_id='a'*32,id=digest(descriptor),sha256=digest(descriptor)), - descriptor=descriptor,environment=None,manifest=manifest) - self.assertEqual(decode_runtime_material(value,catalog_id='a'*32),value) self.assertEqual(runtime.verify_retained_descriptor(descriptor,manifest),manifest) self.assertNotIn('file_links',manifest) changed=dict(manifest,unknown_field=[]) diff --git a/tests/test_tuldok_project_http.py b/tests/test_tuldok_project_http.py index 9d93f4fe..a004570d 100644 --- a/tests/test_tuldok_project_http.py +++ b/tests/test_tuldok_project_http.py @@ -32,10 +32,13 @@ import test_tuldok_project_builds as builds_base # noqa: E402 REPOSITORY = Path(__file__).resolve().parents[1] +# The catalog's manifest lost five entries when the old project mode was deleted (spec-m8.md, section 10): the +# project_transfer operations, which it listed as unavailable. This is the digest of the manifest published before +# (115 operations, b31b7a2b...) with those five entries taken out; every other entry is byte for byte what it was. PUBLISHED = { - 'catalog': (115, 'b31b7a2b794020622e64d593cd29455226a4170451f15201e28cad5d9edd18f1'), - 'project': (152, '58e4270277a38b58869ca4c6ae4bccffe74387b2ee70d3c178b30821f8d27320'), + 'catalog': (110, 'ad5cc7ac91646b39b7a20b9dfca5ec79ed96ded4b5e36732fcf1145f1cc24460'), } +OLD_MODE = ('project_files.', 'project_transfer.') DISCOVERY = '9c02284ed750bce31c53100d4657deaf40b519c9d17d5e3165b6b6342930b660' PROJECT_NAMES = {'project.' + operation.name for operation in operations.OPERATIONS} AGENT_SCOPES = ['inspect', 'edit', 'execute', 'cancel'] @@ -64,7 +67,7 @@ def digest(value): class Contracts(unittest.TestCase): - """What is published: unchanged for catalogs and old projects, the table for project folders.""" + """What is published: unchanged for catalogs, the table for project folders, nothing of the old project mode.""" def test_the_published_digests_are_unchanged(self): for profile, (count, expected) in PUBLISHED.items(): @@ -72,9 +75,20 @@ def test_the_published_digests_are_unchanged(self): value = agent_api.capabilities('b' * 32, profile=profile) self.assertEqual(len(value['operations']), count) self.assertEqual(digest(value), expected) - self.assertFalse([item['id'] for item in value['operations'] if item['id'].startswith('project.')]) + self.assertFalse([item['id'] for item in value['operations'] + if item['id'].startswith(('project.',) + OLD_MODE)]) self.assertEqual(digest(agent_api.discovery()), DISCOVERY) + def test_the_old_project_mode_is_not_published(self): + with self.assertRaises(agent_api.AgentAPIError) as refused: + agent_api.capabilities('b' * 32, profile='project') + self.assertEqual(refused.exception.code, 'registry_invalid') + folder = agent_api.capabilities('b' * 32, profile='project_folder') + self.assertFalse([item['id'] for item in folder['operations'] if item['id'].startswith(OLD_MODE)]) + for name in ('project_files.status', 'project_transfer.status'): + with self.subTest(name), self.assertRaises(agent_api.AgentAPIError): + agent_api.operation(name) + def test_the_project_folder_profile_is_the_table(self): value = agent_api.capabilities('b' * 32, profile='project_folder') self.assertEqual(agent_api.negotiate(value, 'b' * 32).keys(), PROJECT_NAMES | {'context.get', 'identity.get'}) diff --git a/tests/test_workspace_project_candidate.cjs b/tests/test_workspace_project_candidate.cjs deleted file mode 100644 index c1d0d8c3..00000000 --- a/tests/test_workspace_project_candidate.cjs +++ /dev/null @@ -1,25 +0,0 @@ -'use strict'; -const assert=require('node:assert/strict'); -const {mount,state,response,bound,tick,P,ACTOR,C,NEXT}=require('./test_workspace_project_files_m4.cjs'); -const STUDY='a'.repeat(32),CANDIDATE='e'.repeat(32); -const prepared=()=>({state:'prepared',candidate_id:CANDIDATE,trial:{format:'trial_v1',id:'1'.repeat(32),study_id:STUDY,material:{kind:'recipe_material',catalog_id:P,id:C,sha256:C},replicate:0},graph:{id:'2'.repeat(32),revision:1,nodes:[],edges:[]},model:{kind:'model',catalog_id:P,id:ACTOR,revision:1,sha256:C},runtime_snapshot_sha256:C}); -const recovery=()=>({...state(),state:'recovery_required',available_actions:['open'],recovery:{action:'open',root:'fixture',directory:'alpha',reason:'projection_unavailable',request_key:'pending-preparation-key'}}); -(async()=>{ - { - const h=mount();await tick();for(const [id,value] of Object.entries({'project-candidate-study':STUDY,'project-candidate-id':CANDIDATE,'project-candidate-revision':'1','project-candidate-directory':'package','project-candidate-runtime':C}))h.input(id,value);h.nodes.get('project-candidate-kind').value='package'; - h.answers.push(({options})=>{const body=JSON.parse(options.body);assert.equal(body.study_id,undefined);assert.equal(body.expected_checkpoint,C);assert.equal(body.runtime_snapshot_sha256,C);assert.equal(body.candidate_id,CANDIDATE);assert.ok(!Object.hasOwn(body,'approval_id'));assert.equal(h.nodes.get('project-candidate-recovery-key').value,body.request_key);return response(bound(prepared(),NEXT));});await h.submit('project-candidate-prepare-form');assert.equal(h.nodes.get('project-files-error').textContent,'');assert.match(h.nodes.get('project-files-status').textContent,/No Run was launched/); - } - { - const h=mount();await tick();h.answers.push(response(recovery()));await h.click('project-files-refresh'); - assert.equal(h.nodes.get('project-candidate-prepare-fields').disabled,true);assert.equal(h.nodes.get('project-candidate-reconcile').disabled,false);assert.equal(h.nodes.get('project-candidate-abandon').disabled,false); - h.input('project-candidate-recovery-study',STUDY);h.input('project-candidate-recovery-key','pending-preparation-key'); - h.answers.push(({options})=>{const body=JSON.parse(options.body);assert.deepEqual(Object.keys(body).sort(),['binding','expected_checkpoint','preparation_key'].sort());assert.equal(body.preparation_key,'pending-preparation-key');return response(bound(prepared(),NEXT));});await h.click('project-candidate-reconcile');assert.equal(h.nodes.get('project-files-error').textContent,'');assert.match(h.nodes.get('project-files-status').textContent,/no writer was replayed/); - } - { - const h=mount();await tick();h.answers.push(response(recovery()));await h.click('project-files-refresh');h.input('project-candidate-recovery-study',STUDY);h.input('project-candidate-recovery-key','pending-preparation-key'); - const before=h.requests.length;await h.click('project-candidate-abandon');assert.equal(h.requests.length,before);assert.match(h.nodes.get('project-files-error').textContent,/explicit reason/); - h.input('project-candidate-abandon-reason','Scientist explicitly abandons stopped partial writer Ω'); - h.answers.push(({options})=>{const body=JSON.parse(options.body);assert.notEqual(body.request_key,body.preparation_key);return response(bound({format:'project_candidate_preparation_abandon_v1',origin_catalog_id:P,study_id:STUDY,preparation_key:body.preparation_key,preparation_operation:'study_execution.prepare_package',input_sha256:C,candidate:{kind:'candidate',catalog_id:P,id:CANDIDATE,sha256:NEXT},actor_id:ACTOR,reason:body.reason,observed_checkpoint:C,occurred_at:'2026-10-22T12:00:00+00:00',state:'abandoned'},NEXT));});await h.click('project-candidate-abandon');assert.equal(h.nodes.get('project-files-error').textContent,'');assert.match(h.nodes.get('project-files-status').textContent,/original staging and scientific facts remain/); - } - console.log('Candidate controller: 3 selected groups PASS'); -})().catch(error=>{console.error(error);process.exitCode=1;}); diff --git a/tests/test_workspace_project_file_deletion.cjs b/tests/test_workspace_project_file_deletion.cjs deleted file mode 100644 index 846f944b..00000000 --- a/tests/test_workspace_project_file_deletion.cjs +++ /dev/null @@ -1,43 +0,0 @@ -'use strict'; -// Controlled response checks; actual filesystem/HTTP proof is a separate gate. -const assert=require('node:assert/strict'),crypto=require('node:crypto'); -const {mount,bound,response,tick,P,ACTOR,C,NEXT}=require('./test_workspace_project_files_m4.cjs'); -const path='notes/scientist.md',text='Ω authored note\0before\r\n',sha=crypto.createHash('sha256').update(text).digest('hex'); -const id=crypto.createHash('sha256').update(P+'\0note\0'+path).digest('hex'),stamp='2026-10-22T12:00:00+00:00'; -const positive={revision:1,sha256:sha,bytes:Buffer.byteLength(text),text,adopted_at:stamp,actor_id:ACTOR}; -const deleted={revision:2,deleted:true,sha256:null,bytes:0,text:null,adopted_at:stamp,actor_id:ACTOR}; -const selection=version=>({id,project_id:P,kind:'note',path,version}); -const missing={id,kind:'note',path,revision:1,expected_sha256:sha,expected_bytes:positive.bytes,observed_sha256:null,observed_bytes:null,state:'missing',reason:'missing'}; -const tombstone={...missing,revision:2,expected_sha256:null,expected_bytes:0,state:'deleted',reason:null}; -const page=item=>({items:[item],offset:0,limit:40,total:1}); -async function chooseMissing(h){h.answers.push(response(bound(page(missing))));await h.click('project-working-load');h.answers.push(response(bound(selection(positive))));await h.row('project-working-list');} -(async()=>{ - { - const h=mount();await tick();await chooseMissing(h); - assert.equal(h.nodes.get('project-working-delete-fields').disabled,false); - assert.equal(h.nodes.get('project-working-text').value,text); - assert.match(h.nodes.get('project-working-delete-summary').textContent,new RegExp(sha)); - assert.ok(!h.requests.some(r=>r.url.endsWith('/adopt-deletion')),'Inspection must never adopt deletion'); - const before=h.requests.length;await h.submit('project-working-delete-form');assert.equal(h.requests.length,before);assert.match(h.nodes.get('project-files-error').textContent,/explicitly confirm/); - h.nodes.get('project-working-delete-confirm').checked=true; - h.nodes.get('project-working-delete-confirm').listeners.get('change')(); - h.answers.push(({url,options})=>{assert.equal(url,'/api/workspace/project-files/files/adopt-deletion');const body=JSON.parse(options.body);assert.equal(body.binding,'b'.repeat(32));assert.equal(body.expected_checkpoint,C);assert.equal(body.path,path);assert.equal(body.expected_revision,1);assert.equal(body.expected_sha256,sha);assert.deepEqual(Object.keys(body).sort(),['binding','expected_checkpoint','expected_revision','expected_sha256','path','request_key']);return response(bound({id,project_id:P,kind:'note',path,revision:2,sha256:null,bytes:0,deleted:true,adopted_at:stamp,changed:true},NEXT));},response(bound(page(tombstone),NEXT)),response(bound(selection(deleted),NEXT))); - await h.submit('project-working-delete-form');assert.equal(h.nodes.get('project-files-error').textContent,'');assert.equal(h.nodes.get('project-working-text').value,'');assert.match(h.nodes.get('project-working-summary').textContent,/note deletion retained/);assert.equal(h.nodes.get('project-working-delete-fields').disabled,true); - const metadata=v=>Object.fromEntries(Object.entries(v).filter(([k])=>k!=='text')); - h.answers.push(response(bound({id,items:[metadata(positive),metadata(deleted)],offset:0,limit:40,total:2},NEXT))); - await h.click('project-working-history');const labels=h.nodes.get('project-working-history-list').querySelectorAll('button').map(b=>b.textContent);assert.match(labels[1],/note deletion/);assert.doesNotMatch(labels[1],/null/); - h.answers.push(response(bound(selection(positive),NEXT)));await h.row('project-working-history-list');assert.equal(h.nodes.get('project-working-text').value,text);assert.equal(h.nodes.get('project-working-delete-fields').disabled,true); - } - { - const h=mount();await tick();await chooseMissing(h); - h.answers.push(response(bound(page({...missing,state:'unchanged',observed_sha256:sha,observed_bytes:positive.bytes,reason:null}))));await h.click('project-working-load'); - assert.equal(h.nodes.get('project-working-delete-fields').disabled,true,'Fresh inspection invalidates prior missing-note choice'); - h.nodes.get('project-working-delete-confirm').checked=true;const before=h.requests.length;await h.submit('project-working-delete-form');assert.equal(h.requests.length,before); - } - { - const h=mount();await tick();await chooseMissing(h);h.nodes.get('project-working-delete-confirm').checked=true; - h.answers.push(response(bound({id,project_id:P,kind:'note',path,revision:2,sha256:sha,bytes:0,deleted:true,adopted_at:stamp,changed:true},NEXT))); - await h.submit('project-working-delete-form');assert.match(h.nodes.get('project-files-error').textContent,/differs/);assert.equal(h.nodes.get('project-working-text').value,text,'Malformed deletion ACK cannot replace captured text'); - } - console.log('PASS 3 note-deletion controller groups: explicit missing-note confirmation, exact CAS, tombstone/history, refresh invalidation and malformed ACK refusal'); -})().catch(error=>{console.error(error);process.exitCode=1;}); diff --git a/tests/test_workspace_project_files.cjs b/tests/test_workspace_project_files.cjs deleted file mode 100644 index 86582638..00000000 --- a/tests/test_workspace_project_files.cjs +++ /dev/null @@ -1,267 +0,0 @@ -// Deterministic projection/lifecycle evidence; real keyboard/layout evidence is -// owned by browser_project_files.cjs, not this deliberately small DOM substitute. -'use strict'; -const assert=require('node:assert/strict'),fs=require('node:fs'),path=require('node:path'),vm=require('node:vm'),crypto=require('node:crypto'); -const html=fs.readFileSync(path.join(__dirname,'../static/project-files.html'),'utf8'); -const source=fs.readFileSync(path.join(__dirname,'../static/project-files.js'),'utf8'); -const pins=JSON.parse(source.match(/PROJECT_FILES_CONTRACTS_START \*\/\s*([\s\S]*?)\s*\/\* PROJECT_FILES_CONTRACTS_END/)[1]); -const capabilities={format:'agent_capabilities_v1',envelope_version:1,catalog_id:'a'.repeat(32),operations:Object.entries(pins).map(([id,sha256])=>({id,availability:'available',contracts:[{version:1,sha256,input_schema:{},output_schema:{},scopes:['inspect'],authority:'agent',effects:'read',retry:'read',bounds:{request_bytes:1048576,response_bytes:16777216,inline_decoded_bytes:524288,json_depth:64}}]})),limits:{request_bytes:1048576,response_bytes:16777216,max_operations:256}}; -const B='b'.repeat(32),P='c'.repeat(32),R='d'.repeat(32),C='e'.repeat(64),N='f'.repeat(64); -const actions=['new','open','save','close','query','get','import_text','annotate']; -const state=(binding=B,checkpoint=C,opened=true)=>({format:'project_files_state_v1',binding,state:opened?'open':'no_project_open',roots:['fixture'],project:opened?{project_id:P,name:'Text project',checkpoint}:null,available_actions:opened?actions:['new','open']}); -const record=(name='Greeting',revision=1)=>({id:R,kind:'text',name,text:'Hello world',groups:['source'],parents:[],provenance:{method:'import',rights:'unknown',normalization:'NFC; LF newlines'},task:'text_classification',annotation:{label:'greeting'},review:'draft',revision,source_revision:1,created_at:'2026-10-22T12:00:00+00:00',updated_at:'2026-10-22T12:00:00+00:00'}); -const summary=value=>Object.fromEntries(Object.entries(value).filter(([key])=>['id','kind','name','task','review','revision','source_revision','created_at','updated_at'].includes(key))); -const records=(binding=B,checkpoint=C,items=[record()],next_after_id=null)=>({binding,project_id:P,checkpoint,items:items.map(summary),next_after_id}); -const result=(binding=B,checkpoint=C,value=record())=>({binding,project_id:P,checkpoint,record:value,history:[value],next_history_before_revision:null}); -const reply=(value,status=200)=>new Response(JSON.stringify(value),{status,headers:{'Content-Type':'application/json'}}); -const defer=()=>{let resolve;const promise=new Promise(done=>{resolve=done;});return {promise,resolve};}; -const tick=async()=>{await new Promise(done=>setImmediate(done));await new Promise(done=>setImmediate(done));}; -function mount(initial=[reply(state()),reply(records())],capabilityValue=capabilities){ - const nodes=new Map(),events=new Map(),requests=[],answers=[...initial],discoveries=[];let focused=null; - class Node{ - constructor(tag='div'){this.tagName=tag;this.value='';this.children=[];this.dataset={};this.attrs={};this.listeners=new Map();this.disabled=false;this.hidden=false;this.textContent='';} - append(...values){this.children.push(...values);if(this.tagName==='select'&&!this.value&&values.length)this.value=values[0].value;} - replaceChildren(...values){this.children=[...values];if(this.tagName==='select')this.value=values[0]?.value??'';} - setAttribute(name,value){this.attrs[name]=value;} - addEventListener(name,handler){this.listeners.set(name,handler);} - focus(){focused=this;} - querySelectorAll(tag){return this.children.flatMap(child=>[...(child.tagName===tag?[child]:[]),...child.querySelectorAll(tag)]);} - } - for(const match of html.matchAll(/<([a-z][a-z0-9]*)\b([^>]*\bid="([^"]+)"[^>]*)>/g)){ - const node=new Node(match[1]);node.value=match[2].match(/\bvalue="([^"]*)"/)?.[1]??'';node.disabled=/\bdisabled\b/.test(match[2]);nodes.set(match[3],node); - } - nodes.get('annotation-task').value='text_classification';nodes.get('record-review').value='draft';nodes.get('project-explore-kind').value='data_query';nodes.get('project-source-kind').value='image';nodes.get('project-data-review').value='draft'; - const context={document:{getElementById:id=>{assert.ok(nodes.has(id),'Unknown node '+id);return nodes.get(id);},createElement:tag=>new Node(tag)},URLSearchParams,TextEncoder,crypto,console,window:null}; - context.window=context;context.TuldokAuth={canReview:()=>true,fetch:(url,options)=>{if(url==='/api/agent/capabilities'){discoveries.push({url,options});return Promise.resolve(reply(capabilityValue));}const header=options.headers?.['Tuldok-Operation-Contract'];assert.ok(header,'Every project call selects an exact contract');const [operation,version,digest]=header.split('/');assert.equal(version,'1');assert.equal(digest,pins[operation]);requests.push({url,options});assert.ok(answers.length,'Unexpected fetch '+url);return Promise.resolve(answers.shift());}}; - context.addEventListener=(name,handler)=>events.set(name,handler); - // View modules have separate real-browser evidence; this fixture owns native record/control lifetimes. - context.ScientificFieldInspector=()=>({clear(){},show(){}}); - context.ProjectExperimentProgression=()=>({setContext(){},clear(){}}); - context.ProjectMeasurements=()=>({setContext(){},clear(){}}); - context.ProjectModelPortfolio=()=>({setContext(){},clear(){}}); - vm.createContext(context);vm.runInContext(source,context); - return {nodes,requests,answers,events,discoveries,focused:()=>focused, - input(id,value){const node=nodes.get(id);node.value=value;node.listeners.get('input')?.({target:node});}, - async click(id){await nodes.get(id).onclick();await tick();}, - async submit(id){nodes.get(id).onsubmit({preventDefault(){}});await tick();}}; -} -(async()=>{ - // The actual browser controller transports the current binding and checkpoint - // on every read/edit, then adopts only the acknowledged checkpoint. - { - const h=mount();await tick();assert.equal(h.nodes.get('project-files-error').textContent,'');assert.equal(h.discoveries.length,1);assert.equal(h.nodes.get('text-import-fields').disabled,false); - h.input('text-name','Authored note');h.input('text-content',''); - h.answers.push(reply(result(B,N,record('Authored note'))),reply(records(B,N,[record('Authored note')]))); - await h.submit('text-import-form'); - assert.ok(h.requests[2],h.nodes.get('project-files-error').textContent+' '+JSON.stringify(h.requests));const sent=JSON.parse(h.requests[2].options.body); - assert.equal(sent.binding,B);assert.equal(sent.expected_checkpoint,C);assert.equal(sent.asset.text,'');assert.match(sent.request_key,/^[a-f0-9]{32}$/); - assert.equal(h.nodes.get('text-content').value,'');assert.equal(h.nodes.get('project-files-dirty').textContent,'No unsubmitted edits.'); - assert.ok(h.requests[3].url.includes('checkpoint='+N));assert.equal(h.nodes.get('record-heading').textContent,'Authored note'); - assert.equal(h.focused(),h.nodes.get('record-heading')); - h.input('annotation-value','revised');h.answers.push(reply(result(B,C,{...record('Authored note',2),annotation:{label:'revised'}})),reply(records(B,C))); - await h.submit('annotation-form'); - const annotation=JSON.parse(h.requests[4].options.body);assert.equal(annotation.expected_checkpoint,N);assert.equal(annotation.annotation.revision,1);assert.equal(annotation.annotation.source_revision,1);assert.equal(annotation.annotation.annotation.label,'revised'); - h.answers.push(reply(state()),reply(records()));await h.click('project-files-save'); - assert.equal(JSON.parse(h.requests[6].options.body).expected_checkpoint,C);assert.equal(h.nodes.get('record-heading').textContent,'Authored note');assert.equal(h.focused(),h.nodes.get('project-files-save'));assert.equal(h.nodes.get('project-files-save').disabled,false); - h.answers.push(reply(state(P,C,false)));await h.click('project-files-close'); - assert.equal(h.nodes.get('text-import-fields').disabled,true); - h.nodes.get('project-files-directory').value='copied-project';h.answers.push(reply(state(B,C,true)),reply(records()));await h.click('project-files-open'); - const opening=JSON.parse(h.requests[9].options.body);assert.equal(opening.binding,P);assert.equal(opening.expected_checkpoint,null);assert.equal(opening.directory,'copied-project'); - } - // Unsubmitted drafts cannot disappear through lifecycle actions and warn on - // navigation; explicit discard is the only local destructive transition. - { - const h=mount();await tick();h.input('text-content','Keep this draft'); - const count=h.requests.length;await h.click('project-files-close');assert.equal(h.requests.length,count);assert.equal(h.nodes.get('text-content').value,'Keep this draft'); - assert.equal(h.focused(),h.nodes.get('project-files-error'));assert.match(h.nodes.get('project-files-error').textContent,/unsent or unacknowledged/); - let prevented=false;const event={preventDefault(){prevented=true;}};h.events.get('beforeunload')(event);assert.ok(prevented);assert.equal(event.returnValue,''); - await h.click('project-files-discard');assert.equal(h.nodes.get('text-content').value,'');assert.equal(h.nodes.get('project-files-discard').disabled,true); - } - // A session replacement supersedes a delayed response. It cannot display the - // old record even when the old request later succeeds with a valid payload. - { - const h=mount();await tick();const delayed=defer();h.answers.push(delayed.promise); - const button=h.nodes.get('records-list').querySelectorAll('button')[0],old=button.onclick();await tick(); - h.answers.push(reply(state(P,N)),reply(records(P,N,[record('New session record')])));h.events.get('tuldok-session')();await tick(); - delayed.resolve(reply(result(B,C,record('Obsolete record'))));await old;await tick(); - assert.equal(h.nodes.get('record-text').value,'');assert.notEqual(h.nodes.get('record-heading').textContent,'Obsolete record'); - assert.match(h.nodes.get('records-list').querySelectorAll('button')[0].textContent,/New session record/); - } - // Unknown acknowledgement retains edits, fences writes, and exposes recovery. - { - const h=mount();await tick();h.input('text-name','Draft');h.input('text-content','Unique draft'); - h.answers.push(Promise.reject(Error('connection lost')));await h.submit('text-import-form'); - assert.equal(h.nodes.get('text-content').value,'Unique draft');assert.match(h.nodes.get('project-files-error').textContent,/may already be saved/);assert.equal(h.nodes.get('import-text').disabled,true); - h.answers.push(reply(state()),reply(records()));await h.click('project-files-refresh');assert.equal(h.nodes.get('text-content').value,'Unique draft');assert.equal(h.nodes.get('import-text').disabled,false); - } - // History and record continuation are explicit, checkpoint-bound reads. - // Loading an older history page never rewrites an unsubmitted annotation. - { - const h=mount([reply(state()),reply(records(B,C,[record()],R))]);await tick(); - const other={...record('Second record'),id:'e'.repeat(32)};h.answers.push(reply(records(B,C,[other])));await h.click('records-more'); - assert.equal(h.nodes.get('records-list').querySelectorAll('button').length,2);assert.ok(h.requests.at(-1).url.includes('after_id='+R));assert.equal(h.nodes.get('records-more').hidden,true); - const latest=record('Greeting',2);h.answers.push(reply({...result(B,C,latest),next_history_before_revision:2}),reply(records()));await h.nodes.get('records-list').querySelectorAll('button')[0].onclick();await tick(); - h.input('annotation-value','Unsaved annotation');h.answers.push(reply({...result(B,C,latest),history:[record()]}));await h.click('record-history-more'); - assert.ok(h.requests.at(-1).url.includes('before_revision=2'));assert.equal(h.nodes.get('record-history').children.length,2);assert.equal(h.nodes.get('record-history-more').hidden,true);assert.equal(h.nodes.get('annotation-value').value,'Unsaved annotation'); - } - // A committed outcome receipt survives the error projection. Recovery Open - // targets only the declared directory and preserves the in-tab source draft. - { - const h=mount();await tick();h.input('text-name','Retained draft');h.input('text-content','May be committed'); - const receipt={committed:true,selected:true,project_id:P,checkpoint:N,request_key:'file-request-0001'}; - h.answers.push(reply({code:'projection_unavailable',error:'Saved; local view unavailable.',receipt},503));await h.submit('text-import-form'); - assert.match(h.nodes.get('project-files-receipt').textContent,/Saved to project/);assert.equal(h.nodes.get('text-content').value,'May be committed'); - const recovery={...state(),state:'recovery_required',available_actions:['open'],recovery:{action:'open',root:'fixture',directory:'original-project',reason:'projection_unavailable',request_key:'file-request-0001'}}; - h.answers.push(reply(recovery));await h.click('project-files-refresh');assert.equal(h.nodes.get('project-files-open').disabled,false);assert.equal(h.nodes.get('project-files-directory').disabled,true);assert.equal(h.nodes.get('project-files-directory').value,'original-project'); - h.answers.push(reply(state(P,N)),reply(records(P,N)));await h.click('project-files-open');assert.equal(h.nodes.get('text-content').value,'May be committed');assert.equal(JSON.parse(h.requests.at(-2).options.body).directory,'original-project');assert.equal(h.nodes.get('project-files-discard').disabled,false); - h.answers.push(reply(result(P,N)),reply(records(P,N)));await h.nodes.get('records-list').querySelectorAll('button')[0].onclick();await tick();assert.equal(h.nodes.get('record-text').value,'Hello world');assert.equal(h.nodes.get('text-content').value,'May be committed'); - } - // Incompatible capability pins stop dispatch rather than trusting remote - // schemas or silently downgrading the operation selection. - { - const incompatible=JSON.parse(JSON.stringify(capabilities));incompatible.operations.find(item=>item.id==='project_files.status').contracts[0].sha256='0'.repeat(64); - const h=mount([],incompatible);await tick();assert.equal(h.requests.length,0);assert.match(h.nodes.get('project-files-error').textContent,/No compatible project status contract/);assert.equal(h.nodes.get('project-files-open').disabled,true); - } - // Invalid future/unknown fields are errors, never an empty successful project. - { - const h=mount([reply({...state(),future:true})]);await tick();assert.match(h.nodes.get('project-files-error').textContent,/Unsupported project response/);assert.equal(h.nodes.get('project-files-new').disabled,true); - } - // A stale checkpoint error retains annotation text and focuses its recovery - // message. Refresh can update identity without silently reattaching the draft. - { - const h=mount();await tick();h.answers.push(reply(result()),reply(records()));await h.nodes.get('records-list').querySelectorAll('button')[0].onclick();await tick(); - h.input('annotation-value','Never lose this label');h.answers.push(reply({code:'stale_checkpoint',error:'Reload current checkpoint.'},409));await h.submit('annotation-form'); - assert.equal(h.nodes.get('annotation-value').value,'Never lose this label');assert.equal(h.nodes.get('annotation-save').disabled,true);assert.match(h.nodes.get('project-files-error').textContent,/stale_checkpoint/); - h.answers.push(reply(state(B,N)),reply(records(B,N)));await h.click('project-files-refresh');assert.equal(h.nodes.get('annotation-value').value,'Never lose this label');assert.equal(h.nodes.get('annotation-fields').disabled,true); - } - // M2 explores actual data through fixed contracts, preserves independent - // drafts and reads a bounded history page at the exact selected checkpoint. - { - const h=mount();await tick(); - const boundValue=(value,checkpoint=C)=>({binding:B,project_id:P,checkpoint,value}); - const data={...record(),source_available:true,source_lineage_known:true}; - h.answers.push(reply(boundValue({items:[data],offset:0,limit:40,total:1,analysis:{},criteria:{}}))); - await h.click('project-explore-load'); - assert.match(h.requests.at(-1).url,/\/data\?binding=/); - h.answers.push(reply(boundValue(data)));await h.nodes.get('project-explore-list').querySelectorAll('button')[0].onclick();await tick(); - assert.equal(h.nodes.get('project-data-note-form').hidden,false);assert.equal(h.nodes.get('project-metadata-form').hidden,true); - assert.equal(h.nodes.get('project-detail-title').textContent,'Greeting'); - h.answers.push(reply(boundValue({items:[data],offset:0,limit:1,total:2}))); - await h.click('project-detail-history');assert.match(h.requests.at(-1).url,/limit=1/);assert.equal(h.nodes.get('project-detail-history-more').hidden,false); - h.answers.push(reply(boundValue({items:[data],offset:1,limit:1,total:2}))); - await h.click('project-detail-history-more');assert.match(h.requests.at(-1).url,/offset=1/);assert.equal(h.nodes.get('project-detail-history-more').hidden,true); - h.input('project-search-name','Keep this independent draft');h.input('project-rights-note','Authored permission note'); - h.answers.push(reply(boundValue({record:{...data,revision:2},changed:true},N)),reply(records(B,N))); - await h.submit('project-rights-form');const request=h.requests.at(-2),body=JSON.parse(request.options.body); - assert.equal(request.options.headers['Tuldok-Operation-Contract'].split('/')[0],'project_files.data_rights'); - assert.equal(body.expected_checkpoint,C);assert.equal(body.revision,1);assert.equal(body.note,'Authored permission note');assert.match(body.request_key,/^[a-f0-9]{32}$/); - assert.match(h.nodes.get('project-files-dirty').textContent,/unsent or unacknowledged/);assert.equal(h.nodes.get('project-search-name').value,'Keep this independent draft'); - assert.equal(h.nodes.get('project-rights-fields').disabled,true,'Old selected metadata is fenced after publication'); - await h.click('project-files-discard');assert.equal(h.nodes.get('project-search-name').value,''); - } - // Missing/corrupt artifact observations are readable facts. A superseded M2 - // request cannot attach its payload or authoring metadata to a new binding. - { - const h=mount();await tick();h.nodes.get('project-explore-kind').value='artifacts'; - const facts={sha256:C,bytes:99,availability:{status:'corrupt',integrity:'mismatch',reason:'Exact unique bytes differ'}}; - h.answers.push(reply({binding:B,project_id:P,checkpoint:C,value:{items:[facts],offset:0,limit:40,total:1}})); - await h.click('project-explore-load');await h.nodes.get('project-explore-list').querySelectorAll('button')[0].onclick();await tick(); - const strings=node=>[node.textContent,...node.children.flatMap(strings)]; - assert.ok(strings(h.nodes.get('project-detail-facts')).includes('corrupt')); - assert.ok(strings(h.nodes.get('project-detail-facts')).includes('Exact unique bytes differ')); - h.nodes.get('project-explore-kind').value='data_query';const delayed=defer();h.answers.push(delayed.promise);const loading=h.click('project-explore-load');await tick(); - h.answers.push(reply(state(P,N)),reply(records(P,N)));h.events.get('tuldok-session')();await tick(); - delayed.resolve(reply({binding:B,project_id:P,checkpoint:C,value:{items:[record('Obsolete history')],offset:0,limit:40,total:1}}));await loading;await tick(); - assert.equal(h.nodes.get('project-explore-list').children.length,0); - assert.notEqual(h.nodes.get('project-detail-title').textContent,'Obsolete history'); - } - // Model creation copies the current owner's complete inert template. Source - // registration selects declared scientific references without user hash edits. - { - const h=mount();await tick();const boundValue=(value,checkpoint=C)=>({binding:B,project_id:P,checkpoint,value}); - const template={name:'Owner template',task:{kind:'task',catalog_id:P,id:'classification',revision:1,sha256:C},kind:'template',specification:{template:'owned'},source_selector:null,preprocessing_policy:{owned:true},output_policy:{owned:true}}; - h.answers.push(reply(boundValue({recipes:[{model_template:template}]})));await h.click('project-definitions-load'); - h.input('project-model-create-name','My scientific model');h.answers.push(reply(boundValue({id:R,name:'My scientific model',revision:1},N)),reply(records(B,N))); - await h.submit('project-model-create-form');const created=JSON.parse(h.requests.at(-2).options.body); - assert.equal(created.name,'My scientific model');assert.deepEqual(created.specification,template.specification);assert.equal(created.source_selector,null);assert.equal(created.expected_checkpoint,C);assert.equal(created.task.catalog_id,P); - h.input('project-register-path','fixture/tuldok.json');h.answers.push(reply(boundValue({project_id:R,origin_catalog_id:P,manifest_sha256:C},C)),reply(boundValue({items:[{id:'measurements',label:'Captured scientific fields',sha256:N,observed_sha256:N,status:'available',integrity:'verified'}],offset:0,limit:40,total:1},C))); - await h.submit('project-register-form');assert.equal(h.nodes.get('project-scientific-fields').disabled,false); - h.input('project-scientific-name','Observed fields');h.answers.push(reply(boundValue({id:R,kind:'field_sequence'},N)),reply(records(B,N))); - await h.submit('project-scientific-form');const imported=JSON.parse(h.requests.at(-2).options.body); - assert.equal(imported.reference_id,'measurements');assert.equal(imported.expected_sha256,N);assert.equal(imported.snapshot.project_id,R);assert.equal(imported.snapshot.manifest_sha256,C);assert.equal(imported.expected_checkpoint,C);assert.equal(imported.document.name,'Observed fields'); - assert.ok(h.requests.every(request=>!/(execute|submit-external|capture-runtime)/.test(request.url))); - } - // Resolving an explicitly selected missing artifact imports a trusted-root - // file by identity; its durable observation is followed by a fresh status read. - { - const h=mount();await tick();h.nodes.get('project-explore-kind').value='artifacts'; - const boundValue=(value,checkpoint=C)=>({binding:B,project_id:P,checkpoint,value}); - h.answers.push(reply(boundValue({items:[{format:'project_artifact_v1',sha256:C,bytes:9,availability:{state:'missing'}}],offset:0,limit:40,total:1}))); - await h.click('project-explore-load');await h.nodes.get('project-explore-list').querySelectorAll('button')[0].onclick();await tick(); - assert.equal(h.nodes.get('project-artifact-resolve-form').hidden,false);assert.equal(h.nodes.get('project-artifact-root').value,'fixture'); - h.input('project-artifact-path','unique/observation.bin');h.answers.push(reply(boundValue({format:'project_artifact_resolution_v1',sha256:C,bytes:9,actor_id:P,observed_at:'2026-10-22T12:00:00+00:00'},N)),reply(boundValue({state:'verified',expected_sha256:C,expected_bytes:9,observed_sha256:C,observed_bytes:9},N))); - await h.submit('project-artifact-resolve-form'); - const resolve=h.requests.at(-2),body=JSON.parse(resolve.options.body),status=h.requests.at(-1); - assert.equal(resolve.options.headers['Tuldok-Operation-Contract'].split('/')[0],'project_files.artifact_resolve'); - assert.equal(body.root,'fixture');assert.equal(body.path,'unique/observation.bin');assert.equal(body.sha256,C);assert.equal(body.expected_checkpoint,C);assert.match(body.request_key,/^[a-f0-9]{32}$/); - assert.equal(status.options.headers['Tuldok-Operation-Contract'].split('/')[0],'project_files.artifact_status');assert.equal(JSON.parse(status.options.body).checkpoint,N); - assert.equal(h.nodes.get('project-artifact-resolve-form').hidden,true);assert.equal(h.nodes.get('project-artifact-path').value,'');assert.equal(h.nodes.get('project-files-dirty').textContent,'No unsubmitted edits.'); - } - // Native saved selections contain items without pagination fields. Their - // successful create and get results must stay distinct from page contracts. - { - const h=mount();await tick();const boundValue=(value,checkpoint=C)=>({binding:B,project_id:P,checkpoint,value}); - const data={...record(),source_available:true},selection={id:P,name:'Exact revision',revision:1,mode:'fixed',schema_version:1,items:[{id:R,revision:1,source_revision:1}]}; - h.answers.push(reply(boundValue({items:[data],total:1,offset:0,limit:40,analysis:{},criteria:{}})));await h.click('project-explore-load'); - h.answers.push(reply(boundValue(data)));await h.nodes.get('project-explore-list').querySelectorAll('button')[0].onclick();await tick(); - h.input('project-selection-name','Exact revision');h.answers.push(reply(boundValue(selection,N)),reply(records(B,N))); - await h.submit('project-selection-form');assert.equal(h.nodes.get('project-files-error').textContent,'');assert.equal(h.nodes.get('project-files-dirty').textContent,'No unsubmitted edits.'); - assert.equal(JSON.parse(h.requests.at(-2).options.body).expected_checkpoint,C);assert.ok(h.requests.at(-1).url.includes('checkpoint='+N)); - h.nodes.get('project-explore-kind').value='selections';h.answers.push(reply(boundValue({items:[selection],total:1,offset:0,limit:40},N)));await h.click('project-explore-load'); - h.answers.push(reply(boundValue(selection,N)));await h.nodes.get('project-explore-list').querySelectorAll('button')[0].onclick();await tick(); - assert.equal(h.nodes.get('project-files-error').textContent,'');assert.equal(h.nodes.get('project-detail-title').textContent,'Exact revision'); - // Strict continuation checks still apply to actual pages. - h.answers.push(reply(boundValue({items:[selection],total:2,offset:0,limit:40},N)));await h.click('project-explore-load');assert.match(h.nodes.get('project-files-error').textContent,/Saved page differs/); - } - // Unpinned references use the owner's actual observation and retain their - // unverified meaning. A declared digest mismatch is never selectable/imported. - { - const h=mount();await tick();const boundValue=(value,checkpoint=C)=>({binding:B,project_id:P,checkpoint,value}); - const refs=[{id:'unpinned',label:'Observed data',status:'available',integrity:'unverified',observed_sha256:N}, - {id:'mismatch',label:'Changed declared data',status:'available',integrity:'mismatch',sha256:C,observed_sha256:N}, - {id:'missing',label:'Missing declared data',status:'missing',integrity:'unverified',sha256:C}]; - h.input('project-register-path','fixture/tuldok.json');h.answers.push(reply(boundValue({project_id:R,origin_catalog_id:P,manifest_sha256:C},N)),reply(boundValue({items:refs,total:3,offset:0,limit:40},N))); - await h.submit('project-register-form');const choices=h.nodes.get('project-scientific-reference').children; - assert.equal(choices[0].disabled,false);assert.match(choices[0].textContent,/unverified; not pinned/);assert.equal(choices[1].disabled,true);assert.match(choices[1].textContent,/mismatch/);assert.equal(choices[2].disabled,true); - h.nodes.get('project-scientific-reference').value='mismatch';const before=h.requests.length;await h.submit('project-scientific-form');assert.equal(h.requests.length,before);assert.match(h.nodes.get('project-files-error').textContent,/Declared digests must match/); - h.nodes.get('project-scientific-reference').value='unpinned';h.input('project-scientific-name','Observed fields');h.answers.push(reply(boundValue({id:R,kind:'field_sequence'},C)),reply(records(B,C))); - await h.submit('project-scientific-form');assert.equal(h.nodes.get('project-files-error').textContent,'');const imported=JSON.parse(h.requests.at(-2).options.body); - assert.equal(imported.reference_id,'unpinned');assert.equal(imported.expected_sha256,N);assert.equal(imported.expected_checkpoint,N); - } - // Current material review, local grant and durable admission are separate - // named actions. Reconciliation has no fabricated receipt key. - { - const h=mount();await tick();const boundValue=(value,checkpoint=C)=>({binding:B,project_id:P,checkpoint,value}); - assert.equal(h.requests.length,2,'Opening status never starts execution'); - h.answers.push(reply(boundValue({format:'project_execution_health_v1',active_run_ids:[],active_count:0,offset:0,limit:40,local_owner_active:false,available:true,drain_required:false})));await h.click('project-execution-health');assert.match(h.nodes.get('project-execution-summary').textContent,/0 current/); - h.answers.push(reply(boundValue({items:[{id:R,name:'Explicit recipe',revision:3,recipe:'external_recipe'}],total:1,offset:0,limit:40})));await h.click('project-execution-graphs'); - h.answers.push(reply(boundValue({graph_revision:3,material_sha256:N,material:{runtime:'current observed runtime'}})));await h.submit('project-execution-preflight-form');assert.equal(h.nodes.get('project-execution-submit-fields').disabled,true); - h.input('project-execution-consumer',P);await h.submit('project-execution-approval-form');assert.match(h.nodes.get('project-files-error').textContent,/Explicitly approve/); - const grant={id:R,catalog_id:P,approver_actor_id:P,approver_credential_id:null,consumer_actor_id:P,material_sha256:N,created_at:1,expires_at:3601,revoked_at:null}; - h.nodes.get('project-execution-confirm').checked=true;h.answers.push(reply(boundValue({format:'project_current_execution_approval_v1',current_local:true,grant},N)));await h.submit('project-execution-approval-form');assert.equal(h.nodes.get('project-files-error').textContent,'');assert.equal(h.nodes.get('project-execution-submit-fields').disabled,false);assert.equal(h.nodes.get('project-files-dirty').textContent,'No unsubmitted edits.'); - const approval=JSON.parse(h.requests.at(-1).options.body);assert.equal(approval.expected_checkpoint,C);assert.equal(approval.expected_digest,N);assert.equal(approval.consumer_actor_id,P); - h.answers.push(reply(boundValue({format:'project_run_admission_v1',origin_catalog_id:P,run_id:R,request_sha256:N},C)));await h.submit('project-execution-submit-form');assert.match(h.nodes.get('project-files-status').textContent,/durable intent/);assert.equal(h.nodes.get('project-execution-submit-fields').disabled,true);assert.equal(JSON.parse(h.requests.at(-1).options.body).approval_id,R); - h.answers.push(reply(boundValue({format:'project_run_admission_v1',origin_catalog_id:P,run_id:R,request_sha256:N},N)));await h.submit('project-execution-cancel-form');assert.match(h.nodes.get('project-files-status').textContent,/intent saved/); - h.answers.push(reply(boundValue({format:'project_execution_reconciliation_v1',origin_catalog_id:P,run_ids:[R],available:true},C)));await h.click('project-execution-reconcile');const reconciled=JSON.parse(h.requests.at(-1).options.body);assert.deepEqual(Object.keys(reconciled).sort(),['binding','expected_checkpoint']);assert.equal(reconciled.expected_checkpoint,N);assert.match(h.nodes.get('project-files-status').textContent,/reconciled and drained/); - } - // A typed model request uses the saved source revisions and an explicit - // endpoint. A missing acknowledgement preserves its authored request. - { - const h=mount();await tick();const boundValue=(value,checkpoint=C)=>({binding:B,project_id:P,checkpoint,value}); - const source={...record(),source_available:true};h.answers.push(reply(boundValue({items:[source],total:1,offset:0,limit:40,analysis:{},criteria:{}})));await h.click('project-explore-load');h.answers.push(reply(boundValue(source)));await h.nodes.get('project-explore-list').querySelectorAll('button')[0].onclick();await tick(); - h.nodes.get('project-producer-task').value='text_proposal_history';h.answers.push(reply(boundValue(source)));await h.click('project-producer-source-load'); - h.input('project-producer-url','http://127.0.0.1:12345');h.input('project-producer-model','exact-current-model');h.input('project-producer-instruction','Classify the exact frozen source');h.input('project-producer-labels','accepted\nrejected');h.nodes.get('project-producer-transport').value='typed';h.nodes.get('project-producer-confirm').checked=true; - h.answers.push(new Response('{broken',{status:200}));await h.submit('project-producer-start-form');const sent=JSON.parse(h.requests.at(-1).options.body);assert.equal(sent.family,'text_proposal_history');assert.equal(sent.document.source_id,R);assert.equal(sent.document.revision,1);assert.equal(sent.document.seed,null);assert.equal(sent.document.protocol,'pumas_typed_v1');assert.deepEqual(sent.document.labels,['accepted','rejected']);assert.match(h.nodes.get('project-files-error').textContent,/Acknowledgement unavailable/);assert.equal(h.nodes.get('project-producer-instruction').value,'Classify the exact frozen source');assert.equal(h.nodes.get('project-files-close').disabled,true); - } - console.log('PASS project-files controller: checkpoint requests, submit/history projection, dirty preservation, superseded replies, typed errors, unknown acknowledgements'); -})().catch(error=>{console.error(error);process.exitCode=1;}); diff --git a/tests/test_workspace_project_files_m4.cjs b/tests/test_workspace_project_files_m4.cjs deleted file mode 100644 index 80e343ca..00000000 --- a/tests/test_workspace_project_files_m4.cjs +++ /dev/null @@ -1,102 +0,0 @@ -// M4 controller fault boundaries. This small DOM substitute proves requests and -// inert projection; keyboard/layout and actual storage require real browser QA. -'use strict'; -const assert=require('node:assert/strict'),fs=require('node:fs'),path=require('node:path'),vm=require('node:vm'),crypto=require('node:crypto'); -const html=fs.readFileSync(path.join(__dirname,'../static/project-files.html'),'utf8'),source=fs.readFileSync(path.join(__dirname,'../static/project-files.js'),'utf8'); -const pins=JSON.parse(source.match(/PROJECT_FILES_CONTRACTS_START \*\/\s*([\s\S]*?)\s*\/\* PROJECT_FILES_CONTRACTS_END/)[1]); -const versionPins=JSON.parse(source.match(/PROJECT_FILES_VERSIONS_START \*\/\s*([\s\S]*?)\s*\/\* PROJECT_FILES_VERSIONS_END/)[1]); -const B='b'.repeat(32),P='c'.repeat(32),ACTOR='d'.repeat(32),FORK='a'.repeat(32),C='e'.repeat(64),NEXT='f'.repeat(64); -const actions=['new','open','save','close','query','get','import_text','annotate']; -const capabilities={format:'agent_capabilities_v1',envelope_version:1,catalog_id:'a'.repeat(32),operations:Object.entries(pins).map(([id,sha256])=>({id,availability:'available',contracts:[{version:1,sha256,input_schema:{},output_schema:{},scopes:['inspect'],authority:'agent',effects:'read',retry:'read',bounds:{request_bytes:1048576,response_bytes:16777216,inline_decoded_bytes:524288,json_depth:64}}]})),limits:{request_bytes:1048576,response_bytes:16777216,max_operations:256}}; -const state=(binding=B,checkpoint=C,project=P,name='Text project')=>({format:'project_files_state_v1',binding,state:'open',roots:['fixture'],project:{project_id:project,name,checkpoint},available_actions:actions}); -const records=(binding=B,checkpoint=C,project=P)=>({binding,project_id:project,checkpoint,items:[],next_after_id:null}); -const bound=(value,checkpoint=C)=>({binding:B,project_id:P,checkpoint,value}); -const response=(value,status=200)=>new Response(JSON.stringify(value),{status,headers:{'Content-Type':'application/json'}}); -const tick=async()=>{for(let n=0;n<4;n++)await new Promise(done=>setImmediate(done));}; -const hash=raw=>crypto.createHash('sha256').update(raw).digest('hex'),fileID=hash(P+'\0script\0scripts/inert.py'); -const version=(text='print("only text")\0Ω\r\n',revision=1)=>({revision,sha256:hash(Buffer.from(text)),bytes:Buffer.byteLength(text),adopted_at:'2026-10-22T12:00:00+00:00',actor_id:ACTOR,text}); -const selected=(text,revision)=>({id:fileID,project_id:P,kind:'script',path:'scripts/inert.py',version:version(text,revision)}); -function mount(capabilityValue=capabilities){ - const nodes=new Map(),requests=[],answers=[response(state()),response(records())];let focused=null; - class Element{ - constructor(tag){Object.assign(this,{tagName:tag,value:'',children:[],dataset:{},attrs:{},listeners:new Map(),disabled:false,hidden:false,textContent:''});} - append(...children){this.children.push(...children);if(this.tagName==='select'&&!this.value)this.value=children[0]?.value??'';} - replaceChildren(...children){this.children=children;if(this.tagName==='select')this.value=children[0]?.value??'';} - setAttribute(key,value){this.attrs[key]=value;} - addEventListener(name,handler){this.listeners.set(name,handler);} - focus(){focused=this;} - querySelectorAll(tag){return this.children.flatMap(child=>[...(child.tagName===tag?[child]:[]),...child.querySelectorAll(tag)]);} - } - for(const match of html.matchAll(/<([a-z][a-z0-9]*)\b([^>]*\bid="([^"]+)"[^>]*)>/g)){ - const node=new Element(match[1]);node.value=match[2].match(/\bvalue="([^"]*)"/)?.[1]??'';nodes.set(match[3],node); - } - for(const [id,value] of Object.entries({'annotation-task':'text_classification','record-review':'draft','project-explore-kind':'data_query','project-source-kind':'image','project-data-review':'draft','project-working-kind':'script'}))nodes.get(id).value=value; - const context={document:{getElementById:id=>{assert.ok(nodes.has(id),id);return nodes.get(id);},createElement:tag=>new Element(tag)},URLSearchParams,TextEncoder,TextDecoder,crypto,console,window:null};context.window=context; - context.addEventListener=()=>{}; - context.TuldokAuth={canReview:()=>true,fetch:async(url,options)=>{ - if(url==='/api/agent/capabilities')return response(capabilityValue); - const [operation,version,digest]=options.headers['Tuldok-Operation-Contract'].split('/');assert.equal(digest,versionPins[operation]?.[version]??pins[operation]); - const request={url,options};requests.push(request);assert.ok(answers.length,'Unexpected fetch '+url); - const next=answers.shift();return typeof next==='function'?next(request):next; - }}; - // View modules have separate real-browser evidence; this fixture owns native record/control lifetimes. - context.ScientificFieldInspector=()=>({clear(){},show(){}}); - context.ProjectExperimentProgression=()=>({setContext(){},clear(){}}); - context.ProjectMeasurements=()=>({setContext(){},clear(){}}); - context.ProjectModelPortfolio=()=>({setContext(){},clear(){}}); - vm.createContext(context);vm.runInContext(source,context); - return {nodes,requests,answers,focused:()=>focused, - input(id,value){const node=nodes.get(id);node.value=value;node.listeners.get('input')?.({target:node});}, - async click(id){await nodes.get(id).onclick();await tick();}, - async submit(id){nodes.get(id).onsubmit({preventDefault(){}});await tick();for(let n=0;n<100&&nodes.get('project-save-as-fields').disabled&&!nodes.get('project-files-error').textContent;n++)await new Promise(done=>setTimeout(done,2));}, - async row(id,index=0){await nodes.get(id).querySelectorAll('button')[index].onclick();await tick();}}; -} -const inspection=()=>{const v=version();return {id:fileID,kind:'script',path:'scripts/inert.py',revision:1,expected_sha256:v.sha256,expected_bytes:v.bytes,observed_sha256:v.sha256,observed_bytes:v.bytes,state:'unchanged',reason:null};}; -module.exports={mount,state,records,bound,response,tick,B,P,ACTOR,C,NEXT,capabilities,versionPins}; -if(require.main===module)(async()=>{ - // Save As changes only after a correlated independent selection receipt. - { - const h=mount();await tick();h.input('project-save-as-directory','independent');h.input('project-save-as-name','Fork Ω'); - h.answers.push(({options})=>{const body=JSON.parse(options.body);assert.equal(body.binding,B);assert.equal(body.expected_checkpoint,C);assert.equal(body.root,'fixture');return response({state:state(ACTOR,NEXT,FORK,'Fork Ω'),fork:{source_project_id:P,source_checkpoint:C,project_id:FORK,checkpoint:NEXT,root:body.root,directory:body.directory,request_key:body.request_key,reconciled:false,mapping_count:2,copied_count:1,missing_regenerable_count:1}});},response(records(ACTOR,NEXT,FORK))); - await h.submit('project-save-as-form');assert.equal(h.nodes.get('project-files-error').textContent,'');assert.match(h.nodes.get('project-save-as-summary').textContent,/2 editable mappings/);assert.equal(h.focused(),h.nodes.get('project-fork-load')); - assert.ok(h.requests.at(-1).url.includes('binding='+ACTOR));assert.ok(h.requests.at(-1).url.includes('checkpoint='+NEXT)); - } - // Lost acknowledgement retains the exact source/destination/key for explicit - // retry, even after status refresh observes a different selection. - { - const h=mount();await tick();h.input('project-save-as-directory','pending');h.input('project-save-as-name','Pending'); - h.answers.push(()=>Promise.reject(Error('lost reply')));await h.submit('project-save-as-form');const original=JSON.parse(h.requests.at(-1).options.body); - assert.match(h.nodes.get('project-files-error').textContent,/may already be saved/);assert.equal(h.nodes.get('project-save-as-directory').value,'pending'); - h.answers.push(response(state(ACTOR,NEXT,FORK,'Pending')),response(records(ACTOR,NEXT,FORK)));await h.click('project-files-refresh'); - h.input('project-save-as-directory','different');const before=h.requests.length;await h.submit('project-save-as-form');assert.equal(h.requests.length,before);assert.match(h.nodes.get('project-files-error').textContent,/pending Save As destination/); - h.input('project-save-as-directory','pending');h.answers.push(({options})=>{assert.deepEqual(JSON.parse(options.body),original);return response({error:'Inspect original source before recovery.',code:'stale_binding'},409);});await h.submit('project-save-as-form');assert.equal(h.requests.length,before+1); - } - // Captured scripts render only after exact byte/revision checks. A corrupt - // reply cannot replace the prior visible revision, and no script is evaluated. - { - const h=mount();await tick();h.answers.push(response(bound({items:[inspection()],offset:0,limit:40,total:1})));await h.click('project-working-load'); - h.answers.push(response(bound(selected())));await h.row('project-working-list');assert.equal(h.nodes.get('project-working-text').value,version().text);assert.equal(h.nodes.get('project-working-path').value,'scripts/inert.py'); - const meta=version();delete meta.text;h.answers.push(response(bound({id:fileID,items:[meta],offset:0,limit:40,total:1})));await h.click('project-working-history'); - assert.equal(h.nodes.get('project-working-history-list').children.length,1);assert.equal(h.nodes.get('project-working-history-more').hidden,true); - const corrupt=selected('changed',1);corrupt.version.sha256=C;h.answers.push(response(bound(corrupt)));await h.row('project-working-history-list'); - assert.equal(h.nodes.get('project-working-text').value,version().text);assert.match(h.nodes.get('project-files-error').textContent,/exact bytes/); - } - // Explicit adoption transports the reviewed SHA and optimistic revision. The - // current file is read by the server owner; the browser sends no source text. - { - const h=mount();await tick();const v=version('new exact text',1); - for(const [id,value] of Object.entries({'project-working-path':'scripts/inert.py','project-working-revision':'0','project-working-sha':v.sha256}))h.input(id,value); - h.answers.push(({options})=>{const body=JSON.parse(options.body);assert.equal(body.expected_checkpoint,C);assert.equal(body.expected_revision,0);assert.equal(body.expected_sha256,v.sha256);assert.equal(body.path,'scripts/inert.py');assert.ok(!Object.hasOwn(body,'text'));return response(bound({id:fileID,project_id:P,kind:'script',path:body.path,revision:1,sha256:v.sha256,bytes:v.bytes,adopted_at:v.adopted_at,changed:true},NEXT));},response(bound({items:[],offset:0,limit:40,total:0},NEXT)),response(bound(selected('new exact text',1),NEXT))); - await h.submit('project-working-adopt-form');assert.equal(h.nodes.get('project-files-error').textContent,'');assert.equal(h.nodes.get('project-working-text').value,'new exact text');assert.equal(h.nodes.get('project-working-revision').value,'1');assert.match(h.nodes.get('project-files-status').textContent,/remains inert/); - } - // Fork metadata pages and unresolved binding details remain read-only. The - // original definition is fetched only after a user selects that exact row. - { - const h=mount();await tick();const origin={project_id:FORK,checkpoint:NEXT,family:'model_definition',id:ACTOR,revision:2,created_at:'2026-10-22T12:00:00+00:00'},current={format:'project_material_fork_intent_v1',catalog_id:P,id:ACTOR,revision:1,name:'Retained ') + self.write('box.zip', zip_bytes({'in.wav': wav16([1, 2, 3])}, zipfile.ZIP_DEFLATED)) + for address, media, disposition in (('pic.png', 'image/png', 'inline'), + ('x.svg', 'application/octet-stream', 'attachment'), + ('x.html', 'application/octet-stream', 'attachment'), + ('box.zip!in.wav', 'audio/wav', 'inline')): + with self.subTest(address): + answer = inside.file_response(self.product, address) + headers = dict(answer.headers) + self.assertEqual(headers['Content-Type'], media) + self.assertTrue(headers['Content-Disposition'].startswith(disposition)) + self.assertEqual(b''.join(bytes(chunk) for chunk in answer.chunks), inside_archive.locate( + self.root, address).blob().view.tobytes()) + answer = inside.file_response(self.product, 'pic.png', 'bytes=2-5') + self.assertEqual((answer.status, dict(answer.headers)['Content-Range'], b''.join(answer.chunks)), + (206, f'bytes 2-5/{len(png(2, 2))}', png(2, 2)[2:6])) + self.assertEqual(inside.file_response(self.product, 'pic.png', 'bytes=1-2,4-5').status, 200) + + +# ------------------------------------------------------------ through the service + +class ProductCase(builds_base.BuildCase): + """BuildCase with an adopted product for datasets/numbers, whose output directory the tests fill.""" + + def setUp(self): + super().setUp() + patcher = mock.patch.dict(os.environ, {local.SETTINGS_VARIABLE: str(self.temporary / 'settings.json')}) + patcher.start() + self.addCleanup(patcher.stop) + inside_archive.forget_members() + inside.forget_indexes() + source = self.temporary / 'numbers.json' + source.write_text('{"numbers": [1, 2]}', encoding='utf-8') + manifest = {'format': 'tuldok_adoption_v1', + 'products': [{'reference': 'datasets/numbers', 'files': {'numbers.json': str(source)}}]} + with self.opened() as project: + done = adoption.adopt(project, adoption.make_plan(project, manifest, copy=True)) + self.run_id = done['entries'][0]['run_id'] + self.output = Path(done['entries'][0]['directory']) + + def write(self, address, data): + path = self.output / address + path.parent.mkdir(parents=True, exist_ok=True) + path.write_bytes(data if isinstance(data, bytes) else data.encode()) + + +@unittest.skipUnless(builds_base.DATABASE, 'TULDOK_DATABASE_URL is not set; database tests need a disposable cluster.') +class Operations(ProductCase): + + def setUp(self): + super().setUp() + self.service = Service(self.folder) + self.addCleanup(self.service.close) + + def call(self, name, **arguments): + result = self.service.call(name, arguments, OWNER) + json.dumps(result, allow_nan=False) + return result + + def test_the_five_operations_on_an_adopted_product(self): + self.write('field.npy', npy((4, 6), '') + self.write('x.html', '') + token = self.agent['token'] + for address, body, media, disposition in (('p.png', picture, 'image/png', 'inline'), + ('s.wav', sound, 'audio/wav', 'inline'), + ('x.svg', None, 'application/octet-stream', 'attachment'), + ('x.html', None, 'application/octet-stream', 'attachment')): + with self.subTest(address): + status, headers, data = self.get(address, token) + self.assertEqual((status, headers['Content-Type']), (200, media)) + self.assertTrue(headers['Content-Disposition'].startswith(disposition)) + self.assertEqual((headers['X-Content-Type-Options'], headers['Cache-Control']), ('nosniff', 'no-store')) + if body is not None: + self.assertEqual(data, body) + status, headers, data = self.get('s.wav', token, {'Range': 'bytes=4-9'}) + self.assertEqual((status, data, headers['Content-Range']), (206, sound[4:10], f'bytes 4-9/{len(sound)}')) + status, _, data = self.get('p.png') + self.assertEqual(status, 401, data) + status, _, data = self.get('p.png', 'not-a-token') + self.assertIn(status, (401, 403)) + status, _, data = self.get('../p.png', token) + self.assertEqual((status, json.loads(data)['code']), (400, 'invalid')) + status, _, data = self.get('missing.png', token) + self.assertEqual((status, json.loads(data)['code']), (404, 'not-found')) + request = Request(f'{self.root}/api/project/file?run={self.run_id}', headers={'Authorization': 'Bearer ' + token}) + with self.assertRaises(HTTPError) as caught: + urlopen(request, timeout=30) + self.assertEqual(caught.exception.code, 400) + request = Request(f'{self.root}/api/samples', headers={'Authorization': 'Bearer ' + token}) + with self.assertRaises(HTTPError) as caught: + urlopen(request, timeout=30) + self.assertEqual(caught.exception.code, 409) # every other /api/ GET is still refused + + +if __name__ == '__main__': + unittest.main() diff --git a/tests/test_tuldok_project_service.py b/tests/test_tuldok_project_service.py index 5b68ee56..0fc24cdc 100644 --- a/tests/test_tuldok_project_service.py +++ b/tests/test_tuldok_project_service.py @@ -48,7 +48,7 @@ class Table(unittest.TestCase): def test_every_operation_is_declared_once(self): names = [operation.name for operation in operations.OPERATIONS] - self.assertEqual(len(names), 41) # the rows of spec-m7.md section 2 and of section 2 of spec-w1.md and spec-w3.md + self.assertEqual(len(names), 46) # the rows of spec-m7.md section 2, of section 2 of spec-w1.md and spec-w3.md, and of section 3 of spec-d1.md self.assertEqual(len(set(names)), len(names)) for name in REQUEST_OPERATIONS: self.assertIsNotNone(operations.by_name(name)) @@ -205,6 +205,9 @@ def test_every_read(self): 'run': {'run': run_id}, 'progress': {'run': run_id[:8]}, 'products': {}, 'activity': {}, 'map': {}, 'note': {'path': 'missing.md'}, 'recipe_results': {'recipe': 'recipes/fit-a'}, 'draft_branch': {'recipe': 'recipes/fit-a', 'title': 'Fit c'}, + 'records': {'run': run_id}, 'record': {'run': run_id, 'id': 'weights.json'}, 'inside': {'run': run_id}, + 'array_slice': {'run': run_id, 'path': 'weights.npy'}, + 'array_summary': {'run': run_id, 'path': 'weights.npy'}, } reads = [operation for operation in operations.OPERATIONS if not operation.mutation] arguments['build_requests'] = {'state': 'queued', 'limit': 5} @@ -214,6 +217,9 @@ def test_every_read(self): if operation.name == 'build_request': # tested with a request in test_tuldok_project_build_requests self.assertEqual(self.refused(operation.name, {'request': 'abcdef12'}).code, 'not-found') continue + if operation.name in ('array_slice', 'array_summary'): # no arrays here; test_tuldok_project_inside + self.assertEqual(self.refused(operation.name, arguments[operation.name]).code, 'not-found') + continue if operation.name == 'note': # this fixture has no notes; read in test_tuldok_project_workspace self.assertEqual(self.refused(operation.name, arguments['note']).code, 'not-found') continue diff --git a/tuldok_project/check.py b/tuldok_project/check.py index f626501e..94c2084f 100644 --- a/tuldok_project/check.py +++ b/tuldok_project/check.py @@ -107,6 +107,18 @@ def check_definition(definition, notes, add): _check_run(run, path, benchmark=definition.kind == 'benchmark', add=add) if definition.kind == 'benchmark': _check_benchmark(document, path, add) + if definition.kind == 'dataset' and isinstance(document.get('view'), dict): + _check_view(document['view'], path, add) + + +def _check_view(view, path, add): + """The addresses of a dataset's view: a record list's at most two '!', a pattern's at most one.""" + from . import inside_archive # here: inside_archive imports store, which imports this module + for key, archives in (('records', 2), ('files', 1)): + if isinstance(view.get(key), str): + wrong = inside_archive.address_problem(view[key], archives=archives) + if wrong: + add('error', path, documents.pointer('view', key), wrong) def _check_run(run, path, *, benchmark, add): diff --git a/tuldok_project/host.py b/tuldok_project/host.py index 8b9acdda..b982ab9e 100644 --- a/tuldok_project/host.py +++ b/tuldok_project/host.py @@ -5,7 +5,8 @@ (the credentials the app signs in with, as Dataset does) and one Service for the folder. dispatch checks the caller's who rule with access.require inside the credential app.py has bound, passes the caller's identity to the service as -its actor, and turns a ProjectError into a status and a refusal body. This is +its actor, and turns a ProjectError into a status and a refusal body; +product_file does the same for the bytes of a product's file. This is the one module of the package that imports the app's kept layers (metadata, access, agent_api); access errors are left to app.py, which answers them. """ @@ -82,6 +83,15 @@ def dispatch(self, name, arguments): except local.SettingsError as error: # the settings file broke while the app runs return refusal(store.ProjectError(str(error), 'settings')) + def product_file(self, run, address, range_header=None): + """GET /api/project/file for the bound credential, which must be allowed to inspect (as an inspect + operation is): (200, inside.FileResponse) or (status, refusal body).""" + self._require('inspect', 'project.file') + try: + return 200, self.service.product_file(run, address, range_header) + except store.ProjectError as error: + return refusal(error) + def _require(self, who, action): if who == 'owner': self.access.require('approve-execution', action, owner_only=True) diff --git a/tuldok_project/inside.py b/tuldok_project/inside.py new file mode 100644 index 00000000..0baf8e47 --- /dev/null +++ b/tuldok_project/inside.py @@ -0,0 +1,630 @@ +"""Looking inside a product: its records, one record's content, its files and archives, and the bytes of one file. + +Owns sections 2 to 6 of docs/plans/definition-first-projects/spec-d1.md above +the readers. A Product is the output directory of a finished run with the +view of its dataset, if any. Its records come from records.jsonl at its root, +else from the view (a record list, or a pattern of files reaching into at most +one archive), else from every regular file under it (at most WALK_FILES); the +index of a product is kept (INDEXES of them, least recently used dropped) and +made again when its list's size or time changes. records, record, inside, +array_slice and array_summary answer the operations of those names; +file_response answers GET /api/project/file. Addresses are resolved by +inside_archive, which confines them to the product; nothing here writes. +A product's files are whatever a build or a person put there: what a damaged +or mislabelled one makes a reader raise is answered as a refusal (unsupported) +by each of those six, and logged, so that it is never a failure of the app. +""" +import codecs +import collections +import functools +import json +import logging +import os +import re +import struct +import threading +import zlib +from urllib.parse import urlencode + +from . import inside_archive, inside_arrays, inside_shapes +from .inside_archive import is_archive_name, locate +from .store import ProjectError + +LINE_BYTES = 64 * 1024 # one line of a record list +WALK_FILES = 200_000 # files listed when there is no list and no view +INDEXES = 8 # record indexes kept +TEXT_CHARACTERS = 262_144 # characters of a text record returned +COUNT_TEXT_BYTES = 16 * 1024 * 1024 # a text longer than this is not counted to its end +PREVIEW_CHARACTERS = 400 +PROBLEM_LINES = 20 +RECORD_LIST = 'records.jsonl' +KINDS = ('text', 'image', 'audio', 'pointcloud', 'mesh', 'array', 'file') +EXTENSIONS = { + 'text': ('.txt', '.md', '.json', '.jsonl', '.csv', '.tsv', '.yaml', '.yml', '.log'), + 'image': ('.png', '.jpg', '.jpeg', '.webp', '.gif', '.bmp'), + 'audio': ('.wav', '.flac', '.mp3', '.ogg', '.opus', '.m4a'), + 'pointcloud': ('.xyz',), + 'mesh': ('.obj', '.stl'), + 'array': ('.npy', '.npz'), +} +MEDIA_TYPES = {'.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp', + '.gif': 'image/gif', '.bmp': 'image/bmp', '.wav': 'audio/wav', '.flac': 'audio/flac', + '.mp3': 'audio/mpeg', '.ogg': 'audio/ogg', '.opus': 'audio/ogg', '.m4a': 'audio/mp4'} +_ID = re.compile(r'[A-Za-z0-9._-]{1,200}') +_SURROGATES = re.compile('[\udc80-\udcff]') +_lock = threading.Lock() +_indexes = collections.OrderedDict() # (root, source) -> (stamp, _Index) +_LOG = logging.getLogger(__name__) +# What a reader raises on bytes that are not what it expects. ValueError covers bad numbers, bad UTF-8 and bad JSON. +_DAMAGED = (struct.error, zlib.error, EOFError, IndexError, KeyError, ValueError, OverflowError, StopIteration, + ArithmeticError, OSError) + + +def _reading(function): + """function, with what a damaged or mislabelled file makes it raise turned into a refusal (unsupported).""" + @functools.wraps(function) + def guarded(product, *arguments, **options): + try: + return function(product, *arguments, **options) + except ProjectError: + raise + except _DAMAGED as error: + _LOG.warning('A file of run %s could not be read by %s.', product.run_id, function.__name__, exc_info=True) + raise ProjectError('That file could not be read: it is damaged, or it is not what its name says ' + f'({type(error).__name__}).', 'unsupported') from error + return guarded + + +class Product: + """The output directory (real path) of run run_id, and the view of its dataset (a dict) or None.""" + + def __init__(self, run_id, directory, view=None): + self.run_id = run_id + self.root = os.path.realpath(directory) + self.view = view if isinstance(view, dict) else None + if not os.path.isdir(self.root): + raise ProjectError(f'Run {run_id} has no output directory.', 'not-found') + + +def _extension(name): + return os.path.splitext(name.lower())[1] + + +def kind_by_name(name, head=None): + """The kind of a file by its extension; a .ply is a mesh when head (a callable giving its first bytes) shows faces.""" + extension = _extension(name) + if extension == '.ply': + faces = inside_shapes.ply_has_faces(head()) if head is not None else None + return 'mesh' if faces else 'pointcloud' + return next((kind for kind, endings in EXTENSIONS.items() if extension in endings), 'file') + + +# --------------------------------------------------------------------- the index + +class _Index: + def __init__(self, source): + self.source = source + self.records = [] + self.by_id = {} + self.problems = [] + self.bad_lines = 0 + + def add(self, record): + self.by_id[record['id']] = len(self.records) + self.records.append(record) + + def line_problem(self, line, message): + self.bad_lines += 1 + if self.bad_lines <= PROBLEM_LINES: + self.problems.append({'line': line, 'message': message}) + + def finish(self): + if self.bad_lines > PROBLEM_LINES: + self.problems.append({'line': None, 'message': f'{self.bad_lines} lines in all are not records; the ' + f'first {PROBLEM_LINES} are listed.'}) + self.kinds = dict(collections.Counter(record['kind'] for record in self.records)) + self.splits = dict(collections.Counter(record['split'] for record in self.records if record['split'])) + return self + + +def _record(identifier, kind, path, *, size=None, **extra): + return {'id': identifier, 'kind': kind, 'path': path, 'bytes': size, 'text': None, 'array': None, 'split': None, + 'rights': None, 'origin': None, 'meta': None, **extra} + + +_LIST_KEYS = ('id', 'kind', 'path', 'text', 'array', 'split', 'rights', 'origin', 'meta') + + +def _list_entry(value): + """A record from one decoded line of a record list, or the reason it is not one.""" + if not isinstance(value, dict): + return 'it is not a JSON object' + identifier, kind = value.get('id'), value.get('kind') + if not isinstance(identifier, str) or not _ID.fullmatch(identifier): + return 'id must be 1 to 200 characters of A-Z a-z 0-9 . _ -' + if kind not in KINDS: + return f'kind must be one of {", ".join(KINDS)}' + path, text = value.get('path'), value.get('text') + if text is not None and (not isinstance(text, str) or len(text.encode('utf-8')) > LINE_BYTES): + return 'text must be a string of at most 64 KiB' + if path is None: + if kind != 'text' or text is None: + return 'path is required unless kind is text and text is given' + else: + wrong = inside_archive.address_problem(path) + if wrong: + return wrong + for key in ('array', 'split', 'rights'): + if value.get(key) is not None and not isinstance(value[key], str): + return f'{key} must be a string' + for key in ('origin', 'meta'): + if value.get(key) is not None and not isinstance(value[key], dict): + return f'{key} must be an object' + meta = dict(value.get('meta') or {}) + for key, item in value.items(): + if key not in _LIST_KEYS: + meta.setdefault(key, item) + return _record(identifier, kind, path, text=text, array=value.get('array'), split=value.get('split'), + rights=value.get('rights'), origin=value.get('origin'), meta=meta or None) + + +def _lines(place): + """(line number, bytes or None when longer than LINE_BYTES) of a record list.""" + if place.member is None: + with open(place.path, 'rb') as handle: + number = 0 + while True: + raw = handle.readline(LINE_BYTES + 1) + if not raw: + return + number += 1 + if len(raw) > LINE_BYTES and not raw.endswith(b'\n'): + while raw and not raw.endswith(b'\n'): + raw = handle.readline(LINE_BYTES) + yield number, None + else: + yield number, raw + else: + data = bytes(place.blob().view) + for number, raw in enumerate(data.split(b'\n'), start=1): + yield number, (None if len(raw) > LINE_BYTES else raw) + + +def _from_list(place, source): + index = _Index(source) + for number, raw in _lines(place): + if raw is None: + index.line_problem(number, f'The line is longer than {LINE_BYTES} bytes.') + continue + if not raw.strip(): + continue + try: + entry = _list_entry(json.loads(raw)) + except (ValueError, RecursionError): + entry = 'it is not JSON' + if isinstance(entry, str): + index.line_problem(number, f'Not a record: {entry}.') + elif entry['id'] in index.by_id: + index.line_problem(number, f'Not a record: the id {entry["id"]} is used by an earlier line.') + else: + index.add(entry) + return index.finish() + + +def _walk(root, index): + """(address, real path, bytes) of the regular files under root, sorted by address, at most WALK_FILES.""" + found = [] + for directory, folders, files in os.walk(root): + folders.sort() + for name in sorted(files): + full = os.path.join(directory, name) + if os.path.islink(full): + real = os.path.realpath(full) + if not real.startswith(root + os.sep) or not os.path.isfile(real): + continue + elif not os.path.isfile(full): + continue + if len(found) >= WALK_FILES: + index.problems.append({'line': None, 'message': f'Only the first {WALK_FILES} files are listed.'}) + found.sort() + return found + found.append((os.path.relpath(full, root).replace(os.sep, '/'), full, os.path.getsize(full))) + found.sort() + return found + + +def _ply_head(product, address): + return lambda: locate(product.root, address).head(64 * 1024) + + +def _from_files(product): + index = _Index('files') + for address, full, size in _walk(product.root, index): + index.add(_record(address, kind_by_name(address, _ply_head(product, address)), address, size=size)) + return index.finish() + + +def pattern_regex(text): + """A pattern of section 2 as a compiled expression: * and ? within one segment, ** across segments.""" + out, at = [], 0 + while at < len(text): + if text.startswith('**/', at): + out.append('(?:.*/)?') + at += 3 + elif text.startswith('**', at): + out.append('.*') + at += 2 + elif text[at] == '*': + out.append('[^/]*') + at += 1 + elif text[at] == '?': + out.append('[^/]') + at += 1 + else: + out.append(re.escape(text[at])) + at += 1 + return re.compile(''.join(out), re.S) + + +def _from_pattern(product, view): + index = _Index('view') + outer, _, inner = view['files'].partition('!') + kind, show = view.get('kind'), view.get('show') + outer_match = pattern_regex(outer) + matched = [item for item in _walk(product.root, index) if outer_match.fullmatch(item[0])] + found = [] + for address, full, size in matched: + if not inner: + found.append((address, size)) + continue + try: + held = inside_archive.archive(inside_archive.file_blob(full)) + except ProjectError as error: + index.problems.append({'line': None, 'message': f'{address}: {error}'}) + continue + inner_match = pattern_regex(inner) + found.extend((f'{address}!{name}', member.size) for name, member in held.members.items() + if not name.endswith('/') and inner_match.fullmatch(name)) + for address, size in sorted(found): + chosen = kind or kind_by_name(address, _ply_head(product, address)) + index.add(_record(address, chosen, address, size=size, view_show=show)) + return index.finish() + + +def _source(product): + """(source name, the Place of a record list or None, view) for a product.""" + view = product.view + try: + return 'records.jsonl', locate(product.root, RECORD_LIST), None + except ProjectError: + pass + if view and isinstance(view.get('records'), str): + return 'view', locate(product.root, view['records']), view + if view and isinstance(view.get('files'), str): + return 'view', None, view + return 'files', None, None + + +def _stamp(product, place): + """What changes when a product's records would: its list's file, else the product directory.""" + path = product.root + if place is not None: + path = place.path if place.path is not None else locate(product.root, + place.address.split('!')[0]).path + info = os.stat(path) + return info.st_size, info.st_mtime_ns, info.st_ino + + +def index_of(product): + """The record index of a product, made once and kept while its list is unchanged.""" + source, place, view = _source(product) + key = (product.root, json.dumps(view, sort_keys=True)) + stamp = _stamp(product, place) + with _lock: + kept = _indexes.get(key) + if kept is not None and kept[0] == stamp: + _indexes.move_to_end(key) + return kept[1] + if place is not None: + index = _from_list(place, source) + elif view is not None: + index = _from_pattern(product, view) + else: + index = _from_files(product) + with _lock: + _indexes[key] = (stamp, index) + while len(_indexes) > INDEXES: + _indexes.popitem(last=False) + return index + + +def forget_indexes(): + with _lock: + _indexes.clear() + + +# ------------------------------------------------------------------- records + +def _size_of(product, record): + if record['bytes'] is None and record['path'] is not None: + try: + record['bytes'] = locate(product.root, record['path']).size + except ProjectError: + pass + return record['bytes'] + + +def _decode_text(raw, final): + """raw as text, with each byte that is not UTF-8 as a lone surrogate (see _replaced).""" + return codecs.getincrementaldecoder('utf-8')('surrogateescape').decode(bytes(raw), final=final) + + +def _replaced(text): + """(text with each lone surrogate as U+FFFD, how many there were).""" + return _SURROGATES.sub('\ufffd', text), len(_SURROGATES.findall(text)) + + +def _preview(product, record): + if record['text'] is not None: + return record['text'][:PREVIEW_CHARACTERS] + try: + raw = locate(product.root, record['path']).head(PREVIEW_CHARACTERS * 4) + except ProjectError: + return None + return _replaced(_decode_text(raw, False)[:PREVIEW_CHARACTERS])[0] + + +def _shown(product, record, *, preview): + shown = {key: record[key] for key in ('id', 'kind', 'path', 'split', 'rights', 'origin', 'meta')} + shown['bytes'] = _size_of(product, record) + if record['array'] is not None: + shown['array'] = record['array'] + if preview and record['kind'] == 'text': + shown['preview'] = _preview(product, record) + return shown + + +@_reading +def records(product, *, offset=0, limit=50, kind=None, split=None): + index = index_of(product) + chosen = [record for record in index.records + if (kind is None or record['kind'] == kind) and (split is None or record['split'] == split)] + return {'records': [_shown(product, record, preview=True) for record in chosen[offset:offset + limit]], + 'total': len(chosen), 'source': index.source, 'kinds': index.kinds, 'splits': index.splits, + 'problems': index.problems} + + +def file_url(run_id, address): + return '/api/project/file?' + urlencode({'run': run_id, 'path': address}) + + +def _text_content(record, place): + if place is None: + text = record['text'] + return {'text': text, 'characters': len(text), 'truncated': False, 'replaced': 0} + size = place.size or 0 + most = TEXT_CHARACTERS * 4 + 4 + whole = size <= max(most, COUNT_TEXT_BYTES) + raw = place.head(size if whole else most) + text = _decode_text(raw, whole) + characters = len(text) if whole else None + truncated = len(text) > TEXT_CHARACTERS or not whole + text, replaced = _replaced(text[:TEXT_CHARACTERS]) + return {'text': text, 'characters': characters, 'truncated': truncated, 'replaced': replaced} + + +def array_listing(place): + """The arrays of an .npy or .npz Place: [{array, shape, dtype, bytes}]; a plain .npy's one array is named null.""" + if place.name.lower().endswith('.npz'): + held, blob = inside_archive.open_archive_place(place) + found = [] + for name in sorted(held.members): + member = held.members[name] + if name.endswith('/') or not name.endswith('.npy'): + continue + inner = inside_archive.Place(place.address, 'file', parent=blob, archive_=held, member=member) + header = inside_arrays.read_header(inner) + found.append({'array': name[:-4], 'shape': header.shape, 'dtype': header.dtype, 'bytes': member.size}) + return found + header = inside_arrays.read_header(place) + return [{'array': None, 'shape': header.shape, 'dtype': header.dtype, 'bytes': place.size}] + + +def _array_content(record, place): + arrays = array_listing(place) + names = [item['array'] for item in arrays] + show = record['array'] if record['array'] in names else record.get('view_show') + if show not in names: + show = next((item['array'] for item in arrays if len(item['shape']) >= 2), names[0] if names else None) + return {'arrays': arrays, 'show': show} + + +def _content(record, place): + kind = record['kind'] + try: + if kind == 'text': + return _text_content(record, place) + if kind == 'image': + return inside_shapes.image_content(place) + if kind == 'audio': + return inside_shapes.audio_content(place) + if kind == 'pointcloud': + return inside_shapes.pointcloud_content(place) + if kind == 'mesh': + return inside_shapes.mesh_content(place) + if kind == 'array': + return _array_content(record, place) + except (ValueError, IndexError, StopIteration, OverflowError, KeyError) as error: + raise ProjectError(f'{record["path"]} could not be read as {kind}: {type(error).__name__}.', + 'invalid') from None + return {} + + +@_reading +def record(product, identifier): + index = index_of(product) + position = index.by_id.get(identifier) + if position is None: + raise ProjectError(f'There is no record {identifier} in this product.', 'not-found') + found = index.records[position] + shown = _shown(product, found, preview=False) + place = locate(product.root, found['path']) if found['path'] is not None else None + extension = _extension(found['path'] or '') + if found['kind'] in ('image', 'audio') and extension in MEDIA_TYPES: + shown['media_type'] = MEDIA_TYPES[extension] + shown['url'] = file_url(product.run_id, found['path']) + else: + shown['media_type'] = 'text/plain' if found['kind'] == 'text' else 'application/octet-stream' + return {'record': shown, 'content': _content(found, place)} + + +# -------------------------------------------------------------------- inside + +def _entry(address, name, kind_of_entry, size, kind): + return {'name': name, 'path': address, 'type': kind_of_entry, 'bytes': size, 'kind': kind} + + +def _file_entry(address, name, size, place_for_head, depth): + if name.lower().endswith('.npz') or (is_archive_name(name) and depth < inside_archive.ARCHIVES_IN_ADDRESS): + kind_of_entry = 'archive' + else: + kind_of_entry = 'file' + return _entry(address, name, kind_of_entry, size, kind_by_name(name, place_for_head)) + + +def _entries(product, place): + address = place.address + if place.kind == 'directory': + found = [] + for item in sorted(os.scandir(place.path), key=lambda item: item.name): + child = f'{address}/{item.name}' if address else item.name + try: + child_place = locate(product.root, child, folders=True) + except ProjectError: + continue # a link that leaves the product, or something that is not a file or directory + if child_place.kind == 'directory': + found.append(_entry(child, item.name, 'directory', None, None)) + else: + found.append(_file_entry(child, item.name, child_place.size, + lambda child_place=child_place: child_place.head(64 * 1024), 0)) + return found + lower = place.name.lower() + if place.kind == 'file' and lower.endswith(('.npz', '.npy')): + return [{**_entry(address, item['array'] or place.name, 'array', item['bytes'], 'array'), + 'array': item['array'], 'shape': item['shape'], 'dtype': item['dtype']} + for item in array_listing(place)] + if place.kind == 'file': + if not is_archive_name(lower) or place.depth >= inside_archive.ARCHIVES_IN_ADDRESS: + raise ProjectError(f'{address} is a file; read it with record, or list a directory or an archive.', + 'invalid') + held, blob = inside_archive.open_archive_place(place) + prefix, base = '', address + '!' + else: + held, blob = place.archive, place.parent + prefix, base = place.prefix, address + '/' + found = [] + for name, member in held.tree().get(prefix, {}).items(): + child = base + name + if member is None: + found.append(_entry(child, name, 'directory', None, None)) + continue + inner = inside_archive.Place(child, 'file', parent=blob, archive_=held, member=member) + found.append(_file_entry(child, name, member.size, lambda inner=inner: inner.head(64 * 1024), + child.count('!'))) + return found + + +@_reading +def inside(product, *, path='', offset=0, limit=200): + place = locate(product.root, path, folders=True) + entries = _entries(product, place) + entries.sort(key=lambda entry: (entry['type'] != 'directory', entry['name'])) + return {'entries': entries[offset:offset + limit], 'total': len(entries)} + + +# -------------------------------------------------------------------- arrays + +def _array_at(product, path, name): + """(Blob, Header, a name for messages) of the array at path (an .npy, or an .npz with name).""" + place = locate(product.root, path) + lower = place.name.lower() + if lower.endswith('.npz'): + if not name: + raise ProjectError(f'{path} holds several arrays; name one with array.', 'invalid') + held, blob = inside_archive.open_archive_place(place) + member = held.members.get(name + '.npy') + if member is None: + raise ProjectError(f'There is no array {name} in {path}.', 'not-found') + place = inside_archive.Place(path, 'file', parent=blob, archive_=held, member=member) + label = f'{path} {name}' + elif lower.endswith('.npy'): + label = path + else: + raise ProjectError(f'{path} is not an .npy or .npz array.', 'invalid') + header = inside_arrays.read_header(place) + header.require(label) + return place.blob(), header, label + + +@_reading +def array_slice(product, *, path, array=None, axes=None, index=None, most=256): + blob, header, label = _array_at(product, path, array) + return inside_arrays.array_slice(blob, header, label, axes=axes, index=index, most=most) + + +@_reading +def array_summary(product, *, path, array=None, bins=64): + blob, header, label = _array_at(product, path, array) + return inside_arrays.array_summary(blob, header, label, bins=bins) + + +# ---------------------------------------------------------------------- bytes + +class FileResponse: + """What GET /api/project/file sends: status, headers and chunks of the body.""" + + def __init__(self, status, headers, length, chunks): + self.status, self.headers, self.length, self.chunks = status, headers, length, chunks + + +_RANGE = re.compile(r'bytes=(\d+)-(\d*)') + + +@_reading +def file_response(product, address, range_header=None, chunk=1 << 16): + """The bytes of a file or archive member of a product, with its media type, disposition and range.""" + place = locate(product.root, address) + extension = _extension(place.name) + media_type = MEDIA_TYPES.get(extension) + safe_name = re.sub(r'[^A-Za-z0-9._-]', '_', place.name)[:200] or 'file' + disposition = (f'inline; filename="{safe_name}"' if media_type else f'attachment; filename="{safe_name}"') + headers = [('Content-Type', media_type or 'application/octet-stream'), ('Content-Disposition', disposition), + ('Cache-Control', 'no-store'), ('X-Content-Type-Options', 'nosniff')] + if place.member is None: + size = os.path.getsize(place.path) + first, last, status = 0, size - 1, 200 + matched = _RANGE.fullmatch((range_header or '').strip()) + if matched: + start = int(matched[1]) + end = int(matched[2]) if matched[2] else size - 1 + if start <= end and start < size: + first, last, status = start, min(end, size - 1), 206 + headers.append(('Accept-Ranges', 'bytes')) + if status == 206: + headers.append(('Content-Range', f'bytes {first}-{last}/{size}')) + def from_disk(): + with open(place.path, 'rb') as handle: + handle.seek(first) + left = last - first + 1 + while left > 0: + raw = handle.read(min(chunk, left)) + if not raw: + return + left -= len(raw) + yield raw + return FileResponse(status, headers, max(0, last - first + 1), from_disk()) + if place.member.size > inside_archive.MEMBER_BYTES: + raise ProjectError(f'{address} is {place.member.size} bytes; at most {inside_archive.MEMBER_BYTES} are sent.', + 'too-large') + view = place.blob().view + return FileResponse(200, headers, len(view), (view[at:at + chunk] for at in range(0, len(view), chunk))) diff --git a/tuldok_project/inside_archive.py b/tuldok_project/inside_archive.py new file mode 100644 index 00000000..39e0f8d4 --- /dev/null +++ b/tuldok_project/inside_archive.py @@ -0,0 +1,425 @@ +"""Where the bytes of a product are: addresses, files on disk through mmap, zip archives and their members. + +Owns sections 1 (addresses), 3 ("reading no more than is needed") and 6 +(confinement) of docs/plans/definition-first-projects/spec-d1.md for the +layer below the formats. locate() turns an address under a product directory +into a Place: a directory on disk, a directory inside an archive, or a file +(on disk or a member). A Place's bytes are a Blob, a memoryview with a key: +a file on disk is mapped read only and never copied; a member stored +uncompressed is a slice of its archive's bytes (so a member of an archive on +disk is read through the same mapping, at its offsets); a compressed member +is decompressed whole, refused too-large beyond MEMBER_BYTES (by the size the +archive declares, and again while decompressing), and kept in one cache of +at most CACHE_BYTES shared by every product, least recently used first out. +A zip's central directory is read from its end and kept per archive +(DIRECTORIES of them); nothing else of an archive is read to list it. +Nothing is ever written or extracted. +""" +import bz2 +import collections +import mmap +import os +import stat +import struct +import threading +import zlib + +from . import documents +from .store import ProjectError + +MEMBER_BYTES = 256 * 1024 * 1024 # a member decompressed into memory +CACHE_BYTES = 512 * 1024 * 1024 # decompressed members kept, all products together +DIRECTORIES = 32 # central directories kept +ARCHIVES_IN_ADDRESS = 2 # '!' in an address +ARCHIVE_EXTENSIONS = ('.zip', '.npz') +_CHUNK = 1 << 20 +_EOCD = b'PK\x05\x06' +_CENTRAL = b'PK\x01\x02' +_LOCAL = b'PK\x03\x04' +_CENTRAL_HEADER = struct.Struct('<4sHHHHHHIIIHHHHHII') + +_lock = threading.Lock() +_members = collections.OrderedDict() # key -> bytes, decompressed members +_members_bytes = 0 +_directories = collections.OrderedDict() # blob key -> Archive + + +def refuse(message, code='not-found'): + raise ProjectError(message, code) + + +# ------------------------------------------------------------------ addresses + +def address_parts(text, *, archives=ARCHIVES_IN_ADDRESS, root=False): + """The parts of an address split at '!'; refused invalid when it is not one (absolute, '..', too many '!').""" + if root and text == '': + return [''] + if not isinstance(text, str) or not text: + refuse('An address must be a non-empty relative path.', 'invalid') + parts = text.split('!') + if len(parts) > archives + 1: + refuse(f'The address {text!r} has more than {archives} "!".', 'invalid') + for part in parts: + wrong = documents.relative_path_problem(part) + if wrong: + refuse(f'The address {text!r} {wrong}.', 'invalid') + return parts + + +def address_problem(text, *, archives=ARCHIVES_IN_ADDRESS): + """A sentence saying why text is not an address, or None.""" + try: + address_parts(text, archives=archives) + except ProjectError as error: + return str(error) + return None + + +def is_archive_name(name): + return name.lower().endswith(ARCHIVE_EXTENSIONS) + + +def disk_path(root, relative): + """The real path of relative under the real directory root; not-found when it is missing or leaves root.""" + full = os.path.realpath(os.path.join(root, relative)) if relative else root + if full != root and not full.startswith(root + os.sep): + refuse(f'There is no file {relative} in this product.') + if not os.path.lexists(full): + refuse(f'There is no file {relative} in this product.') + return full + + +# ---------------------------------------------------------------------- blobs + +class Blob: + """Bytes of one file or member: view (a memoryview), key (its identity for caches), and, when the bytes lie in + a file on disk as they are, path and offset (where they begin in it).""" + __slots__ = ('view', 'key', 'path', 'offset') + + def __init__(self, view, key, path=None, offset=0): + self.view, self.key, self.path, self.offset = view, key, path, offset + + def __len__(self): + return len(self.view) + + +def file_blob(path): + """A regular file mapped read only (an empty file is empty bytes).""" + with open(path, 'rb') as handle: + info = os.fstat(handle.fileno()) + if not stat.S_ISREG(info.st_mode): + refuse(f'{os.path.basename(path)} is not a regular file.') + key = ('file', info.st_dev, info.st_ino, info.st_size, info.st_mtime_ns) + if info.st_size == 0: + return Blob(memoryview(b''), key, path, 0) + mapped = mmap.mmap(handle.fileno(), 0, access=mmap.ACCESS_READ) + return Blob(memoryview(mapped), key, path, 0) + + +# -------------------------------------------------------------------- archives + +Member = collections.namedtuple('Member', 'name method flags compressed size header') + + +class Archive: + """A zip's members by name, from its central directory; the tree of names is made when first listed.""" + + def __init__(self, members): + self.members = members + self._tree = None + + def is_folder(self, prefix): + return prefix in self.tree() + + def tree(self): + """{folder ('' for the top): {child name: Member, or None for a folder}}, implicit folders included.""" + if self._tree is None: + tree = {'': {}} + for name, member in self.members.items(): + parts = name.rstrip('/').split('/') + for depth in range(len(parts)): + folder = '/'.join(parts[:depth]) + children = tree.setdefault(folder, {}) + last = depth == len(parts) - 1 + if last and not name.endswith('/'): + children[parts[depth]] = member + else: + children.setdefault(parts[depth], None) + tree.setdefault('/'.join(parts[:depth + 1]), {}) + self._tree = tree + return self._tree + + +def _zip_problem(text): + refuse(f'This is not a zip archive Tuldok can read: {text}.', 'unsupported') + + +def _parse_directory(view): + size = len(view) + start = max(0, size - (22 + 65535)) + tail = bytes(view[start:]) + at = tail.rfind(_EOCD) + while at >= 0 and len(tail) - at < 22: + at = tail.rfind(_EOCD, 0, at) + if at < 0: + _zip_problem('no end of central directory') + _, _, _, _, count, directory_size, directory_offset, _ = struct.unpack_from('= 0 and bytes(view[locator:locator + 4]) == b'PK\x06\x07': + record = struct.unpack_from(' len(raw): + _zip_problem('a damaged central directory') + (_, _, _, flags, method, _, _, _, compressed, size_, name_length, extra_length, comment_length, _, _, _, + header) = _CENTRAL_HEADER.unpack_from(raw, position) + name_bytes = raw[position + 46:position + 46 + name_length] + extra = raw[position + 46 + name_length:position + 46 + name_length + extra_length] + position += 46 + name_length + extra_length + comment_length + if 0xFFFFFFFF in (compressed, size_, header): + at_extra = 0 + while at_extra + 4 <= len(extra): + tag, length = struct.unpack_from(' DIRECTORIES: + _directories.popitem(last=False) + return found + + +def _data_offset(view, member): + at = member.header + if bytes(view[at:at + 4]) != _LOCAL: + _zip_problem(f'a damaged local header for {member.name}') + name_length, extra_length = struct.unpack_from(' len(view): + _zip_problem(f'{member.name} runs past the end of the archive') + return start + + +def _decompressor(member): + if member.method == 8: + return zlib.decompressobj(-15) + if member.method == 12: + return bz2.BZ2Decompressor() + refuse(f'{member.name} is compressed with method {member.method}, which Tuldok does not read.', 'unsupported') + + +def _inflate_raw(view, member, most): + """At most most bytes of a compressed member, decompressing no more than needed.""" + source = view[_data_offset(view, member):][:member.compressed] + engine = _decompressor(member) + out = bytearray() + position = 0 + zlib_engine = member.method == 8 + while len(out) < most and not engine.eof: + room = most - len(out) + if zlib_engine and engine.unconsumed_tail: + piece = engine.decompress(engine.unconsumed_tail, room) + elif not zlib_engine and not engine.needs_input: + piece = engine.decompress(b'', room) + elif position < len(source): + piece = engine.decompress(source[position:position + _CHUNK], room) + position += _CHUNK + else: + break + out += piece + return out + + +def _inflate(view, member, most): + """At most most bytes of a compressed member; compressed data that is damaged is refused unsupported.""" + try: + return _inflate_raw(view, member, most) + except (zlib.error, OSError, EOFError, ValueError) as error: + _zip_problem(f'{member.name} does not decompress ({type(error).__name__})') + + +def _remember(key, data): + global _members_bytes + with _lock: + if key in _members or len(data) > CACHE_BYTES: + return + _members[key] = data + _members_bytes += len(data) + while _members_bytes > CACHE_BYTES: + _, dropped = _members.popitem(last=False) + _members_bytes -= len(dropped) + + +def _remembered(key): + with _lock: + found = _members.get(key) + if found is not None: + _members.move_to_end(key) + return found + + +def forget_members(): + """Drop every kept member and central directory (tests use it).""" + global _members_bytes + with _lock: + _members.clear() + _directories.clear() + _members_bytes = 0 + + +def _check_member(member): + if member.flags & 1: + refuse(f'{member.name} is encrypted.', 'unsupported') + + +def member_blob(blob, member): + """The bytes of a member: a slice of the archive when stored, else decompressed whole (bounded, kept).""" + _check_member(member) + key = (blob.key, member.name) + if member.method == 0: + start = _data_offset(blob.view, member) + view = blob.view[start:start + member.compressed] + return Blob(view, key, blob.path, blob.offset + start if blob.path else 0) + if member.size > MEMBER_BYTES: + refuse(f'{member.name} is {member.size} bytes decompressed; at most {MEMBER_BYTES} are read.', 'too-large') + data = _remembered(key) + if data is None: + data = _inflate(blob.view, member, MEMBER_BYTES + 1) + if len(data) > MEMBER_BYTES: + refuse(f'{member.name} is more than {MEMBER_BYTES} bytes decompressed; at most {MEMBER_BYTES} are read.', + 'too-large') + data = bytes(data) + _remember(key, data) + return Blob(memoryview(data), key) + + +def member_head(blob, member, most): + """The first most bytes of a member, decompressing only those when it is compressed and not kept.""" + _check_member(member) + if member.method == 0: + start = _data_offset(blob.view, member) + return bytes(blob.view[start:start + min(most, member.compressed)]) + data = _remembered((blob.key, member.name)) + if data is not None: + return data[:most] + return bytes(_inflate(blob.view, member, most)) + + +# ---------------------------------------------------------------------- places + +class Place: + """What an address names. kind is 'directory' (on disk), 'folder' (inside an archive) or 'file'. + + A file is on disk (path) or a member (parent, the archive's Blob, and member). An archive folder has + parent, archive and prefix. address is the address it was found by. + """ + + def __init__(self, address, kind, *, path=None, parent=None, archive_=None, member=None, prefix=''): + self.address, self.kind, self.path = address, kind, path + self.parent, self.archive, self.member, self.prefix = parent, archive_, member, prefix + self._blob = None + + @property + def name(self): + last = self.address.split('!')[-1] + return last.rsplit('/', 1)[-1] + + @property + def size(self): + if self.member is not None: + return self.member.size + if self.path is not None and self.kind == 'file': + return os.stat(self.path).st_size + return None + + @property + def depth(self): + """How many '!' its address has.""" + return self.address.count('!') + + def blob(self): + if self._blob is None: + self._blob = member_blob(self.parent, self.member) if self.member is not None else file_blob(self.path) + return self._blob + + def head(self, most): + """The first most bytes.""" + if self._blob is not None: + return bytes(self._blob.view[:most]) + if self.member is not None: + return member_head(self.parent, self.member, most) + with open(self.path, 'rb') as handle: + return handle.read(most) + + +def locate(root, address, *, folders=False): + """The Place address names under the real product directory root. + + Refused invalid for a malformed address and not-found for anything + missing or outside root. Directories (on disk or in an archive) are found + only when folders is true. + """ + parts = address_parts(address, root=folders) + full = disk_path(root, parts[0]) + if len(parts) == 1: + if os.path.isdir(full): + if not folders: + refuse(f'{address or "The product"} is a directory.', 'invalid') + return Place(address, 'directory', path=full) + if not os.path.isfile(full): + refuse(f'There is no file {address} in this product.') + return Place(address, 'file', path=full) + if not os.path.isfile(full): + refuse(f'There is no archive {parts[0]} in this product.') + place = Place(parts[0], 'file', path=full) + for depth, part in enumerate(parts[1:], start=1): + if place.kind != 'file': + refuse(f'There is no archive {"!".join(parts[:depth])} in this product.') + parent = place.blob() + held = archive(parent) + here = '!'.join(parts[:depth + 1]) + member = held.members.get(part) + if member is not None and not part.endswith('/'): + place = Place(here, 'file', parent=parent, archive_=held, member=member) + elif folders and depth == len(parts) - 1 and held.is_folder(part): + place = Place(here, 'folder', parent=parent, archive_=held, prefix=part) + else: + refuse(f'There is no member {part} in {"!".join(parts[:depth])}.') + return place + + +def open_archive_place(place): + """The (Archive, its Blob) of a file Place that is an archive.""" + blob = place.blob() + return archive(blob), blob diff --git a/tuldok_project/inside_arrays.py b/tuldok_project/inside_arrays.py new file mode 100644 index 00000000..aeea5fd1 --- /dev/null +++ b/tuldok_project/inside_arrays.py @@ -0,0 +1,303 @@ +"""Arrays in a product: NPY headers, the arrays of an NPZ, a two-axis slice and a summary, without numpy. + +Owns the "Arrays" paragraph and the array_slice and array_summary rows of +section 3 of docs/plans/definition-first-projects/spec-d1.md. A header is +parsed with ast.literal_eval from at most HEADER_BYTES; versions 1, 2 and 3, +C and Fortran order, either byte order; floats of 2, 4 and 8 bytes, integers +of 1 to 8 bytes and booleans are read, and anything else (objects, complex, +strings, structured types) is refused unsupported. Nothing is unpickled. The +values a slice or a summary needs are gathered from the array's bytes (a +Blob of inside_archive, mapped or decompressed) at the strides they lie at, +byte column by byte column, so only those bytes are touched and no Python +loop runs per value; they are decoded with the array module (struct for +half floats). A summary reads at most SUMMARY_VALUES values, every n-th in +storage order beyond that. +""" +import ast +from array import array +import base64 +import collections +import math +import operator +import struct +import sys +from itertools import repeat + +from .store import ProjectError + +HEADER_BYTES = 64 * 1024 # an NPY header +SUMMARY_VALUES = 4_000_000 # values read for one summary +DRAWN_MOST = 512 # rows and columns of a slice +_MAGIC = b'\x93NUMPY' +_NATIVE_LITTLE = sys.byteorder == 'little' +_SIGNED = {1: 'b', 2: 'h', 4: 'i', 8: 'q'} +_UNSIGNED = {1: 'B', 2: 'H', 4: 'I', 8: 'Q'} +_FLOATS = {4: 'f', 8: 'd'} +_NAMES = {'f': 'float', 'i': 'int', 'u': 'uint'} +assert all(array(code).itemsize == size for table in (_SIGNED, _UNSIGNED, _FLOATS) for size, code in table.items()) + + +def _refuse(message, code='unsupported'): + raise ProjectError(message, code) + + +class Header: + """One NPY header: shape, descr, fortran, offset (of the data), and, when its type is read, kind ('f', 'i', + 'u' or 'b'), itemsize and little; problem says why it is not read otherwise.""" + + def __init__(self, shape, descr, fortran, offset): + self.shape, self.descr, self.fortran, self.offset = shape, descr, fortran, offset + self.kind = self.itemsize = self.little = None + self.problem = None + if not isinstance(descr, str): + self.problem = 'a structured type' + return + order, code, size = (descr[0], descr[1:2], descr[2:]) if descr[:1] in '<>|=' else ('=', descr[:1], descr[1:]) + if code == 'O': + self.problem = 'an object array (it is never unpickled)' + return + if not size.isdigit(): + self.problem = f'the type {descr}' + return + size = int(size) + if (code == 'f' and size in (2, 4, 8)) or (code in 'iu' and size in (1, 2, 4, 8)) or (code == 'b' + and size == 1): + self.kind, self.itemsize = code, size + self.little = _NATIVE_LITTLE if order in '=|' else order == '<' + elif code == 'c': + self.problem = 'a complex array' + else: + self.problem = f'the type {descr}' + + @property + def dtype(self): + """The type's name: float32, int16, uint8, bool, ...; the descr when it is not read.""" + if self.kind is None: + return self.descr if isinstance(self.descr, str) else 'structured' + if self.kind == 'b': + return 'bool' + return f'{_NAMES[self.kind]}{self.itemsize * 8}' + + @property + def count(self): + return math.prod(self.shape) + + def require(self, name): + if self.problem is not None: + _refuse(f'{name} is {self.problem}; Tuldok reads floats, integers and booleans.') + + def strides(self): + """Bytes between neighbours along each axis.""" + steps, step = [0] * len(self.shape), self.itemsize + axes = range(len(self.shape)) if self.fortran else reversed(range(len(self.shape))) + for axis in axes: + steps[axis] = step + step *= self.shape[axis] + return steps + + +def header_length(head): + """The number of bytes before an NPY array's data, from at least its first 12 bytes; refused when not NPY.""" + if len(head) < 10 or bytes(head[:6]) != _MAGIC: + _refuse('This is not an NPY array.') + major = head[6] + if major == 1: + return 10 + struct.unpack_from('= 12: + return 12 + struct.unpack_from(' HEADER_BYTES: + _refuse(f'The NPY header is more than {HEADER_BYTES} bytes.') + if len(head) < end: + _refuse('The NPY header is cut short.') + try: + text = bytes(head[start:end]).decode('utf-8' if major == 3 else 'latin-1') + value = ast.literal_eval(text.strip()) + except (ValueError, SyntaxError, TypeError, MemoryError, RecursionError, UnicodeError): + _refuse('The NPY header is not a literal Tuldok can read.') + if (not isinstance(value, dict) or set(value) != {'descr', 'fortran_order', 'shape'} + or not isinstance(value['fortran_order'], bool) or not isinstance(value['shape'], tuple) + or not all(type(item) is int and item >= 0 for item in value['shape'])): + _refuse('The NPY header must hold descr, fortran_order and a shape of whole numbers.') + return Header(list(value['shape']), value['descr'], value['fortran_order'], end) + + +def read_header(place): + """The Header of the NPY array a Place holds, reading only its first bytes.""" + head = place.head(12) + return parse_header(place.head(header_length(head))) + + +# ------------------------------------------------------------------- reading + +def gather(view, start, step, count, itemsize): + """The bytes of count values of itemsize, the first at start and each step bytes after the one before.""" + if count <= 0: + return b'' + if step == itemsize: + return bytes(view[start:start + count * itemsize]) + out = bytearray(count * itemsize) + last = start + (count - 1) * step + for byte in range(itemsize): + out[byte::itemsize] = view[start + byte:last + byte + 1:step] + return out + + +def decode(raw, header): + """The values in raw (a whole number of header's items) as an array, or a tuple for half floats.""" + if header.kind == 'f' and header.itemsize == 2: + return struct.unpack(('<' if header.little else '>') + f'{len(raw) // 2}e', raw) + if header.kind == 'f': + values = array(_FLOATS[header.itemsize]) + elif header.kind == 'i': + values = array(_SIGNED[header.itemsize]) + else: + values = array(_UNSIGNED[header.itemsize]) + values.frombytes(raw) + if header.little != _NATIVE_LITTLE and header.itemsize > 1: + values.byteswap() + if header.kind == 'b': + values = array('B', (1 if value else 0 for value in values)) + return values + + +def _check_length(blob, header, name): + if header.offset + header.count * header.itemsize > len(blob.view): + _refuse(f'{name} is shorter than its shape says.') + + +def float32_base64(values): + """values as base64 of little-endian 32-bit floats.""" + packed = array('f', values) + if not _NATIVE_LITTLE: + packed.byteswap() + return base64.b64encode(packed.tobytes()).decode('ascii') + + +def _finite_range(values): + """(minimum, maximum, count of non-finite) of numbers; the minimum and maximum of the finite ones.""" + try: + total = sum(values) + finite = values if isinstance(total, int) or math.isfinite(total) else None + except OverflowError: + finite = None + if finite is None: + finite = [value for value in values if math.isfinite(value)] + if not finite: + return None, None, len(values) + return min(finite), max(finite), len(values) - len(finite) + + +def array_slice(blob, header, name, *, axes=None, index=None, most=256): + """Two axes of an array, at index on the others, at most most rows and columns (one stride for both).""" + header.require(name) + _check_length(blob, header, name) + shape, ndim = header.shape, len(header.shape) + if axes is None: + axes = list(range(max(0, ndim - 2), ndim)) + if ndim >= 2 and (len(axes) != 2 or axes[0] == axes[1] or not all(0 <= axis < ndim for axis in axes)): + _refuse(f'axes must be two different axes of the {ndim} of {name}.', 'invalid') + if ndim < 2 and list(axes) != list(range(ndim)): + _refuse(f'{name} has {ndim} axes; leave axes out.', 'invalid') + if index is None: + index = [size // 2 for size in shape] + if len(index) != ndim: + _refuse(f'index must give one position for each of the {ndim} axes of {name}.', 'invalid') + for axis, (position, size) in enumerate(zip(index, shape)): + if axis not in axes and not 0 <= position < size: + _refuse(f'Position {position} is outside axis {axis} of {name}, which has {size}.', 'invalid') + steps = header.strides() + base = header.offset + sum(position * steps[axis] for axis, position in enumerate(index) if axis not in axes) + if ndim >= 2: + full_rows, full_columns = shape[axes[0]], shape[axes[1]] + row_step, column_step = steps[axes[0]], steps[axes[1]] + else: + full_rows, full_columns = 1, (shape[0] if ndim else 1) + row_step, column_step = 0, (steps[0] if ndim else header.itemsize) + stride = max(1, math.ceil(full_rows / most), math.ceil(full_columns / most)) + rows, columns = math.ceil(full_rows / stride), math.ceil(full_columns / stride) + values = [] + if rows and columns: + if row_step == header.itemsize and column_step != header.itemsize and rows > 1: + # Rows lie next to each other: read each column whole, then turn them into rows. + by_column = [decode(gather(blob.view, base + column * stride * column_step, stride * row_step, rows, + header.itemsize), header) for column in range(columns)] + for row in range(rows): + values.extend(column[row] for column in by_column) + else: + for row in range(rows): + values.extend(decode(gather(blob.view, base + row * stride * row_step, stride * column_step, + columns, header.itemsize), header)) + low, high, nonfinite = _finite_range(values) + return {'shape': shape, 'dtype': header.dtype, 'axes': list(axes), 'index': list(index), 'rows': rows, + 'columns': columns, 'stride': stride, 'values_f32': float32_base64(values), 'min': low, 'max': high, + 'nonfinite': nonfinite} + + +def array_summary(blob, header, name, *, bins=64): + """Count, range, mean, deviation, zeros, non-finite and a histogram of an array, every stride-th value.""" + header.require(name) + _check_length(blob, header, name) + count = header.count + stride = max(1, math.ceil(count / SUMMARY_VALUES)) + read = math.ceil(count / stride) + size = header.itemsize + values = array('d') + chunk = max(1, (1 << 20) // stride) * stride # values of the array per piece, a multiple of the stride + for first in range(0, count, chunk): + taken = math.ceil(min(chunk, count - first) / stride) + piece = decode(gather(blob.view, header.offset + first * size, stride * size, taken, size), header) + values.extend(piece.tolist() if isinstance(piece, array) else piece) + assert len(values) == read + result = {'shape': header.shape, 'dtype': header.dtype, 'count': count, 'stride': stride} + try: + total = math.fsum(values) + except (OverflowError, ValueError): + total = math.nan + finite = values if math.isfinite(total) else array('d', filter(math.isfinite, values)) + result['nonfinite'] = len(values) - len(finite) + if not finite: + return {**result, 'min': None, 'max': None, 'mean': None, 'std': None, 'zeros': 0, + 'histogram': {'low': None, 'high': None, 'counts': [0] * bins}} + try: + mean = (total if finite is values else math.fsum(finite)) / len(finite) + except OverflowError: + mean = math.inf + deviations = array('d', map(operator.sub, finite, repeat(mean))) + std = math.sqrt(math.fsum(map(operator.mul, deviations, deviations)) / len(finite)) + low, high = min(finite), max(finite) + counts = [0] * bins + if high > low: + scale = bins / (high - low) + for position, many in collections.Counter(map(int, map(operator.mul, map(operator.sub, finite, repeat(low)), + repeat(scale)))).items(): + counts[min(position, bins - 1)] += many + else: + counts[0] = len(finite) + integral = header.kind != 'f' + return {**result, 'min': int(low) if integral else low, 'max': int(high) if integral else high, 'mean': mean, + 'std': std, 'zeros': finite.count(0), 'histogram': {'low': low, 'high': high, 'counts': counts}} + + +def columns(blob, header, name, wanted, most): + """The first wanted columns of a two-axis array (N, at least wanted), every stride-th row, at most most rows. + + Returns (rows in all, stride, [values of each column]). + """ + header.require(name) + _check_length(blob, header, name) + if len(header.shape) != 2 or header.shape[1] < wanted: + _refuse(f'{name} must have the shape (N, {wanted} or more).') + total = header.shape[0] + stride = max(1, math.ceil(total / most)) + taken = math.ceil(total / stride) + row_step, column_step = header.strides() + return total, stride, [decode(gather(blob.view, header.offset + column * column_step, stride * row_step, taken, + header.itemsize), header) for column in range(wanted)] diff --git a/tuldok_project/inside_shapes.py b/tuldok_project/inside_shapes.py new file mode 100644 index 00000000..c792cbf2 --- /dev/null +++ b/tuldok_project/inside_shapes.py @@ -0,0 +1,425 @@ +"""Images, sounds, point clouds and meshes in a product: what a viewer needs, read with the standard library. + +Owns the image, audio, pointcloud and mesh rows of "content of record" in +section 3 of docs/plans/definition-first-projects/spec-d1.md. An image gives +its width and height from its header (PNG, JPEG, GIF, WebP, BMP). A WAV of +PCM (8, 16, 24, 32 bit) or 32-bit float gives its channels, rate, length and +at most PEAKS pairs of lowest and highest sample; other sounds give nulls. A +point cloud (PLY ASCII or binary little-endian, XYZ text, or an NPY of shape +(N, 3 or more)) gives at most POINTS points, every stride-th beyond that, and +the bounds of the points given. A mesh (PLY, OBJ, STL binary or ASCII) gives +its vertices and its polygons split into triangles as a fan, refused +too-large beyond MESH_VERTICES or MESH_TRIANGLES. A point cloud or mesh file +of more than SHAPE_BYTES is refused too-large before it is parsed. +""" +from array import array +import base64 +import math +import re +import struct +import sys + +from . import inside_arrays +from .store import ProjectError + +SHAPE_BYTES = 256 * 1024 * 1024 # a point cloud or mesh file parsed +POINTS = 100_000 # points returned +MESH_VERTICES = 200_000 +MESH_TRIANGLES = 400_000 +PEAKS = 1000 # pairs of lowest and highest sample +IMAGE_HEAD = 64 * 1024 # read first for an image's size; a JPEG may need up to IMAGE_HEAD_MOST +IMAGE_HEAD_MOST = 1024 * 1024 +_PLY_HEADER = 64 * 1024 +_PLY_TYPES = {'char': 'b', 'int8': 'b', 'uchar': 'B', 'uint8': 'B', 'short': 'h', 'int16': 'h', 'ushort': 'H', + 'uint16': 'H', 'int': 'i', 'int32': 'i', 'uint': 'I', 'uint32': 'I', 'float': 'f', 'float32': 'f', + 'double': 'd', 'float64': 'd'} +_LITTLE = sys.byteorder == 'little' +assert array('I').itemsize == 4 + + +def _refuse(message, code='unsupported'): + raise ProjectError(message, code) + + +def _b64(values, code): + packed = array(code, values) + if not _LITTLE: + packed.byteswap() + return base64.b64encode(packed.tobytes()).decode('ascii') + + +def _bounds(xs, ys, zs): + if not xs: + return None + return [[min(xs), min(ys), min(zs)], [max(xs), max(ys), max(zs)]] + + +def _check_size(place): + size = place.size + if size is not None and size > SHAPE_BYTES: + _refuse(f'{place.name} is {size} bytes; at most {SHAPE_BYTES} are parsed.', 'too-large') + + +# ---------------------------------------------------------------------- images + +_JPEG_FRAMES = set(range(0xC0, 0xD0)) - {0xC4, 0xC8, 0xCC} + + +def image_size(head): + """(width, height) from the first bytes of a PNG, JPEG, GIF, WebP or BMP; (None, None) when not found.""" + head = bytes(head) + if head[:8] == b'\x89PNG\r\n\x1a\n' and head[12:16] == b'IHDR' and len(head) >= 24: + return struct.unpack_from('>II', head, 16) + if head[:6] in (b'GIF87a', b'GIF89a') and len(head) >= 10: + return struct.unpack_from('= 26: + if struct.unpack_from('= 30: + chunk = head[12:16] + if chunk == b'VP8 ' and head[23:26] == b'\x9d\x01\x2a': + width, height = struct.unpack_from('> 14) & 0x3FFF) + 1 + if chunk == b'VP8X': + return (int.from_bytes(head[24:27], 'little') + 1, int.from_bytes(head[27:30], 'little') + 1) + if head[:2] == b'\xff\xd8': + at = 2 + while at + 9 <= len(head): + if head[at] != 0xFF: + at += 1 + continue + marker = head[at + 1] + if marker == 0xFF: + at += 1 + elif marker in (0x01, 0xD8) or 0xD0 <= marker <= 0xD7: + at += 2 + elif marker in _JPEG_FRAMES: + height, width = struct.unpack_from('>HH', head, at + 5) + return width, height + else: + at += 2 + struct.unpack_from('>H', head, at + 2)[0] + return None, None + + +def image_content(place): + size = place.size or 0 + width, height = image_size(place.head(IMAGE_HEAD)) + if width is None and size > IMAGE_HEAD: + width, height = image_size(place.head(IMAGE_HEAD_MOST)) + return {'width': width, 'height': height} + + +# ----------------------------------------------------------------------- sound + +def _wave_format(view): + """(format tag, channels, rate, block align, bits, data offset, data bytes) of a RIFF WAVE, or None.""" + if len(view) < 12 or bytes(view[:4]) != b'RIFF' or bytes(view[8:12]) != b'WAVE': + return None + at, found = 12, None + while at + 8 <= len(view): + name, size = struct.unpack_from('<4sI', view, at) + body = at + 8 + if name == b'fmt ' and size >= 16: + tag, channels, rate, _, align, bits = struct.unpack_from('= 40: + tag = struct.unpack_from('= 0 else len(head) + self.format, self.elements = None, [] + for line in head[:end].decode('latin-1').splitlines()[1:]: + words = line.split() + if not words or words[0] in ('comment', 'obj_info'): + continue + if words[0] == 'format' and len(words) >= 2: + self.format = words[1] + elif words[0] == 'element' and len(words) == 3 and words[2].isdigit(): + self.elements.append((words[1], int(words[2]), [])) + elif words[0] == 'property' and self.elements: + if words[1] == 'list' and len(words) == 5 and words[2] in _PLY_TYPES and words[3] in _PLY_TYPES: + self.elements[-1][2].append((words[4], (_PLY_TYPES[words[2]], _PLY_TYPES[words[3]]))) + elif len(words) == 3 and words[1] in _PLY_TYPES: + self.elements[-1][2].append((words[2], _PLY_TYPES[words[1]])) + else: + _refuse(f'This PLY has a property Tuldok does not read: {line.strip()}.', 'invalid') + if self.format not in ('ascii', 'binary_little_endian'): + _refuse(f'PLY {self.format} is not read; ASCII and binary little-endian are.') + + def count(self, name): + return next((count for element, count, _ in self.elements if element == name), 0) + + +def ply_has_faces(head): + """Whether a PLY header declares faces; None when it is not a header Tuldok reads.""" + try: + return _Ply(head).count('face') > 0 + except ProjectError: + return None + + +def _ply_read(place, want_faces): + """(vertex columns {name: values}, vertex count, faces as lists of indexes or None) of a PLY.""" + view = place.blob().view + ply = _Ply(view[:_PLY_HEADER]) + columns, faces, vertices = {}, None, 0 + if ply.format == 'ascii': + lines = iter(bytes(view[ply.end:]).split(b'\n')) + for name, count, properties in ply.elements: + if name == 'vertex': + vertices = count + names = [prop for prop, _ in properties] + rows = [next(lines).split() for _ in range(count)] + for position, prop in enumerate(names): + columns[prop] = [float(row[position]) for row in rows] + elif name == 'face' and want_faces: + faces = [] + for _ in range(count): + words = next(lines).split() + faces.append([int(word) for word in words[1:1 + int(words[0])]]) + else: + for _ in range(count): + next(lines) + return columns, vertices, faces + at = ply.end + for name, count, properties in ply.elements: + if all(isinstance(kind, str) for _, kind in properties): + record = struct.calcsize('<' + ''.join(kind for _, kind in properties)) + if name == 'vertex': + vertices = count + offset = 0 + for prop, kind in properties: + size = struct.calcsize(kind) + raw = inside_arrays.gather(view, at + offset, record, count, size) + values = array(kind) + values.frombytes(bytes(raw)) + columns[prop] = values + offset += size + at += record * count + continue + listed = [] if (name == 'face' and want_faces) else None + for _ in range(count): + for _, kind in properties: + if isinstance(kind, str): + at += struct.calcsize(kind) + continue + many = struct.unpack_from('<' + kind[0], view, at)[0] + at += struct.calcsize(kind[0]) + items = struct.unpack_from(f'<{many}{kind[1]}', view, at) + at += many * struct.calcsize(kind[1]) + if listed is not None: + listed.append(list(items)) + if listed is not None: + faces = listed + return columns, vertices, faces + + +# ------------------------------------------------------------------ point clouds + +def _sample(total): + stride = max(1, math.ceil(total / POINTS)) + return stride, range(0, total, stride) + + +def pointcloud_content(place, kind_hint=None): + _check_size(place) + lower = place.name.lower() + colors = None + if lower.endswith('.npy'): + blob = place.blob() + header = inside_arrays.read_header(place) + total, stride, (xs, ys, zs) = inside_arrays.columns(blob, header, place.name, 3, POINTS) + xs, ys, zs = list(xs), list(ys), list(zs) + elif lower.endswith('.ply'): + columns, total, _ = _ply_read(place, False) + if not all(axis in columns for axis in 'xyz'): + _refuse('This PLY has no x, y and z.', 'invalid') + stride, chosen = _sample(total) + xs, ys, zs = ([columns[axis][i] for i in chosen] for axis in 'xyz') + if all(channel in columns for channel in ('red', 'green', 'blue')): + colors = [max(0, min(255, int(columns[channel][i]))) for i in chosen + for channel in ('red', 'green', 'blue')] + else: + rows = [] + for line in bytes(place.blob().view).decode('utf-8', 'replace').splitlines(): + words = line.replace(',', ' ').split() + if not words or words[0].startswith('#'): + continue + try: + rows.append([float(word) for word in words]) + except ValueError: + continue + rows = [row for row in rows if len(row) >= 3] + total = len(rows) + stride, chosen = _sample(total) + picked = [rows[i] for i in chosen] + xs, ys, zs = [row[0] for row in picked], [row[1] for row in picked], [row[2] for row in picked] + if picked and all(len(row) >= 6 and all(0 <= value <= 255 and value == int(value) for value in row[3:6]) + for row in picked): + colors = [int(value) for row in picked for value in row[3:6]] + points = [value for triple in zip(xs, ys, zs) for value in triple] + return {'count': total, 'stride': stride, 'bounds': _bounds(xs, ys, zs), 'points_f32': _b64(points, 'f'), + 'colors_u8': None if colors is None else base64.b64encode(bytes(colors)).decode('ascii')} + + +# ----------------------------------------------------------------------- meshes + +def _too_large(vertices, triangles): + if vertices > MESH_VERTICES or triangles > MESH_TRIANGLES: + _refuse(f'This mesh has {vertices} vertices and {triangles} triangles; at most {MESH_VERTICES} vertices ' + f'and {MESH_TRIANGLES} triangles are shown.', 'too-large') + + +def _fan(polygons, vertices): + triangles = [] + for polygon in polygons: + for corner in range(1, len(polygon) - 1): + triangles.extend((polygon[0], polygon[corner], polygon[corner + 1])) + if any(not 0 <= index < vertices for index in triangles): + _refuse('A face names a vertex the mesh does not have.', 'invalid') + return triangles + + +def _obj(text): + positions, polygons = [], [] + for line in text.splitlines(): + words = line.split() + if not words: + continue + if words[0] == 'v' and len(words) >= 4: + positions.extend(float(word) for word in words[1:4]) + elif words[0] == 'f' and len(words) >= 4: + count = len(positions) // 3 + polygon = [] + for word in words[1:]: + index = int(word.split('/')[0]) + polygon.append(count + index if index < 0 else index - 1) + polygons.append(polygon) + return positions, polygons + + +_STL_VERTEX = re.compile(rb'vertex\s+(\S+)\s+(\S+)\s+(\S+)') + + +def _stl(view): + if len(view) >= 84: + count = struct.unpack_from(', the rule its caller must satisfy (who), whether it changes anything (mutation), a closed JSON Schema of its arguments and the result keys that are always present. service.py checks @@ -15,6 +16,7 @@ REQUEST_STATES = ('awaiting-approval', 'queued', 'running', 'succeeded', 'failed', 'cancelled', 'declined', 'expired') KINDS = ('dataset', 'model', 'recipe', 'benchmark', 'step', 'environment', 'chart') CHANGES = ('training-policy', 'architecture', 'refinement', 'component') # a recipe's kind of change +RECORD_KINDS = ('text', 'image', 'audio', 'pointcloud', 'mesh', 'array', 'file') # the kinds of a product's record TARGET_LIMIT = 50 REASON_CHARACTERS = 400 @@ -41,6 +43,9 @@ class Operation: _OFFSET = {'type': 'integer', 'minimum': 0} _THEME = {'type': 'string', 'enum': ['light', 'dark']} _TARGETS = {'type': 'array', 'items': _REFERENCE, 'maxItems': TARGET_LIMIT} +_ADDRESS = {'type': 'string', 'minLength': 1, 'maxLength': 4096} # a path in a product; '!' names an archive member +_ARRAY = {'type': 'string', 'minLength': 1, 'maxLength': 1024} +_AXIS = {'type': 'integer', 'minimum': 0, 'maximum': 63} def _limit(most): @@ -67,6 +72,9 @@ def _arguments(required=(), **properties): REQUEST = ('id', 'state', 'targets', 'every', 'scratch', 'covers', 'requested_at', 'requested_by', 'decided_at', 'decided_by', 'started_at', 'finished_at', 'plan_id', 'cancel_requested', 'result', 'problem', 'expires_at') +SLICE = ('shape', 'dtype', 'axes', 'index', 'rows', 'columns', 'stride', 'values_f32', 'min', 'max', 'nonfinite') +SUMMARY_OF_ARRAY = ('shape', 'dtype', 'count', 'min', 'max', 'mean', 'std', 'zeros', 'nonfinite', 'histogram', + 'stride') SAVE = ('written', 'deleted', 'results_written', 'results_deleted') CANCEL_RUN = ('id', 'reference', 'subject', 'state', 'cancel_file', 'already_asked') STOP_RUN = ('id', 'reference', 'subject', 'was', 'state', 'killed', 'remaining', 'marked_unknown') @@ -139,6 +147,29 @@ def _arguments(required=(), **properties): change={'type': 'string', 'enum': list(CHANGES)}, description={'type': 'string', 'maxLength': 4000}), ('reference', 'text', 'parent', 'inlined', 'problems')), + Operation('records', "Read one page of the records of a finished run's product, optionally of one kind or split, " + 'with the counts by kind and split.', 'inspect', False, + _arguments(['run'], run=_RUN, offset=_OFFSET, limit=_limit(200), + kind={'type': 'string', 'enum': list(RECORD_KINDS)}, split=_TEXT), + ('records', 'total', 'source', 'kinds', 'splits', 'problems')), + Operation('record', "Read one record of a finished run's product with its content: text, image size, sound " + 'peaks, points, mesh or arrays.', 'inspect', False, + _arguments(['run', 'id'], run=_RUN, id={'type': 'string', 'minLength': 1, 'maxLength': 4096}), + ('record', 'content')), + Operation('inside', "List a directory, an archive or the arrays of an .npz in a finished run's product.", + 'inspect', False, + _arguments(['run'], run=_RUN, path={'type': 'string', 'maxLength': 4096}, offset=_OFFSET, + limit=_limit(500)), ('entries', 'total')), + Operation('array_slice', "Read a slice along two axes of an array in a finished run's product, as 32-bit floats.", + 'inspect', False, + _arguments(['run', 'path'], run=_RUN, path=_ADDRESS, array=_ARRAY, + axes={'type': 'array', 'items': _AXIS, 'minItems': 2, 'maxItems': 2}, + index={'type': 'array', 'items': {'type': 'integer', 'minimum': 0}, 'maxItems': 64}, + most=_limit(512)), SLICE), + Operation('array_summary', "Read the range, mean, deviation and histogram of an array in a finished run's " + 'product.', 'inspect', False, + _arguments(['run', 'path'], run=_RUN, path=_ADDRESS, array=_ARRAY, bins=_limit(256)), + SUMMARY_OF_ARRAY), Operation('set_definition', "Check a definition's text and keep it as an unsaved edit.", 'edit', True, _arguments(['reference', 'text'], reference=_REFERENCE, text=_TEXT), DEFINITION), Operation('remove_definition', 'Mark a definition that nothing uses as removed, until the project is saved.', diff --git a/tuldok_project/schemas/dataset.schema.json b/tuldok_project/schemas/dataset.schema.json index 61ba913e..a92bce49 100644 --- a/tuldok_project/schemas/dataset.schema.json +++ b/tuldok_project/schemas/dataset.schema.json @@ -49,6 +49,72 @@ "type": "integer", "minimum": 0 } + }, + "view": { + "type": "object", + "description": "an object with records (a record list) or files (a pattern), not both", + "additionalProperties": false, + "properties": { + "records": { + "type": "string", + "minLength": 1, + "maxLength": 1024, + "description": "the address of a record list in the product, such as lists/all.jsonl" + }, + "files": { + "type": "string", + "minLength": 1, + "maxLength": 1024, + "description": "a pattern of addresses in the product, such as training-view.zip!samples/*.npz" + }, + "kind": { + "enum": [ + "text", + "image", + "audio", + "pointcloud", + "mesh", + "array", + "file" + ] + }, + "show": { + "type": "string", + "minLength": 1, + "maxLength": 1024, + "description": "the name of the array drawn first" + } + }, + "dependentSchemas": { + "records": { + "properties": { + "files": { + "not": {}, + "description": "Use either records or files in view, not both; remove one." + }, + "kind": { + "not": {}, + "description": "kind applies to the files of a pattern; remove it, or use files." + }, + "show": { + "not": {}, + "description": "show applies to the files of a pattern; remove it, or use files." + } + } + } + }, + "anyOf": [ + { + "required": [ + "records" + ] + }, + { + "required": [ + "files" + ] + } + ] } }, "if": { diff --git a/tuldok_project/service.py b/tuldok_project/service.py index c8a0c8e3..664fad5a 100644 --- a/tuldok_project/service.py +++ b/tuldok_project/service.py @@ -7,8 +7,11 @@ returns a JSON-plain object. Calls are answered one at a time under one lock of the service. Every mutating call that passed the actor check writes one activity row, done or refused. The six operations on build requests are -passed to build_requests. Nothing here knows of HTTP or of the app's access -layer. +passed to build_requests. The five reads inside a product (spec-d1.md) find +the finished run with the project open for a moment and read its output +directory through inside.py after closing it; product_file does the same for +the file route; those reads run outside the lock, so a long one holds up no +other call. Nothing here knows of HTTP or of the app's access layer. The worker (section 4) is one thread per service, started by start() and stopped by close(). It runs queued build requests one at a time while it @@ -33,11 +36,27 @@ import jsonschema import psycopg -from . import (activity, build_requests, builds, charts, check, environments, launcher, local, operations, plan, - store, workspace) +from . import (activity, build_requests, builds, charts, check, environments, inside, launcher, local, operations, + plan, store, workspace) from .documents import Problem CHECK_PROBLEMS = 200 + +# The reads inside a product (spec-d1.md), each a function of (inside.Product, arguments). call() finds the product +# under the service's lock and reads outside it: decompressing a large member or parsing a large mesh takes seconds, +# and the other calls (the page's own readings among them) must not wait for it. inside.py guards what it keeps. +INSIDE_READS = { + 'records': lambda product, a: inside.records(product, offset=a.get('offset', 0), limit=a.get('limit', 50), + kind=a.get('kind'), split=a.get('split')), + 'record': lambda product, a: inside.record(product, a['id']), + 'inside': lambda product, a: inside.inside(product, path=a.get('path', ''), offset=a.get('offset', 0), + limit=a.get('limit', 200)), + 'array_slice': lambda product, a: inside.array_slice(product, path=a['path'], array=a.get('array'), + axes=a.get('axes'), index=a.get('index'), + most=a.get('most', 256)), + 'array_summary': lambda product, a: inside.array_summary(product, path=a['path'], array=a.get('array'), + bins=a.get('bins', 64)), +} POLL_SECONDS = 1.0 # how often the worker looks for a queued request CLOSE_SECONDS = 30.0 # how long close() waits for the worker WORKER_LOCK = 'build-requests.lock' @@ -253,6 +272,14 @@ def call(self, name, arguments, actor): raise store.ProjectError(f'There is no operation project.{name}.', 'not-found') if not _allowed(operation.who, actor): raise store.ProjectError(f'This credential may not call project.{name}.', 'forbidden') + if name in INSIDE_READS: + problems = _argument_problems(operation, arguments) + if problems: + raise store.ProjectError(f'The arguments of project.{name} do not match its schema.', 'invalid', + problems=problems) + with self._lock: + product = self._product(arguments['run']) + return _plain(INSIDE_READS[name](product, dict(arguments))) with self._lock: try: problems = _argument_problems(operation, arguments) @@ -262,18 +289,18 @@ def call(self, name, arguments, actor): result = _plain(getattr(self, f'_{name}')(dict(arguments), actor)) except store.ProjectError as exc: if operation.mutation: - self._record(actor, name, _target(arguments), exc.code, str(exc)) + self._record_activity(actor, name, _target(arguments), exc.code, str(exc)) raise except Exception as exc: if operation.mutation: - self._record(actor, name, _target(arguments), 'error', f'{type(exc).__name__}: {exc}') + self._record_activity(actor, name, _target(arguments), 'error', f'{type(exc).__name__}: {exc}') raise if operation.mutation: target = result.get('id', '') if name == 'request_build' else _target(arguments) - self._record(actor, name, target, 'done') + self._record_activity(actor, name, target, 'done') return result - def _record(self, actor, name, target, outcome, detail=''): + def _record_activity(self, actor, name, target, outcome, detail=''): # Its own connection: the row is written even when the project would not open. with psycopg.connect(store.connection_info(self.dsn), autocommit=True) as connection: activity.record(connection, self.schema, actor, name, target, outcome, detail) @@ -423,6 +450,30 @@ def _draft_branch(self, arguments, actor): return workspace.draft_branch(project, recipe, arguments['title'], name=arguments.get('name'), change=arguments.get('change'), description=arguments.get('description')) + # ------------------------------------------------------ inside a product + + def _product(self, run): + """The inside.Product of a finished run (succeeded or adopted), read with the project open for a moment.""" + with self._open() as project: + run_id = builds.find_run(project, run) + state, directory, reference = project._execute( + 'SELECT state, directory, reference FROM {schema}.runs WHERE id = %s', (run_id,)).fetchone() + view = None + if reference.startswith('datasets/'): + row = project._execute('SELECT document FROM {schema}.definitions WHERE directory = %s AND name = %s ' + 'AND NOT removed', ('datasets', reference.split('/', 1)[1])).fetchone() + view = row[0].get('view') if row and isinstance(row[0], dict) else None + if state not in ('succeeded', builds.ADOPTED) or not directory: + raise store.ProjectError(f'Run {run_id} is {state}; only a finished run has a product to look inside.', + 'not-found') + return inside.Product(run_id, os.path.join(directory, builds.OUTPUT), view) + + def product_file(self, run, address, range_header=None): + """The inside.FileResponse of GET /api/project/file; the caller has checked the right to inspect.""" + with self._lock: + product = self._product(run) + return inside.file_response(product, address, range_header) + # ------------------------------------------------------------- changes def _set_definition(self, arguments, actor): From 04e1ddb28753dcb3a1f934c011a1817d555fe93a Mon Sep 17 00:00:00 2001 From: MrScripty Date: Fri, 13 Nov 2026 15:44:47 -0700 Subject: [PATCH 062/131] feat(pumas): follow the contract Pumas Library 0.8.0 released The client was written against a pre-release of the 0.8 contract. It is compared with the release (tag v0.8.0, read only) and brought up to it; spec-d3.md lists every difference. served_models() reads what an endpoint serves from GET /v1/served-models: each model and profile with its modalities and capabilities, bounded and validated, independent of the catalog. available_capabilities() answers which of a served model's capabilities make a given output from a given input. Nothing calls them yet: generation in a project folder is phase 5. Also: image-to-text checks the total image bytes, message and part bounds an endpoint advertises, and typed image generation the prompt length; a refusal made before a handler ran is read as not admitted with its code kept; any image memory policy name is kept; the advertisement's service_generation may be 256 characters. Unknown fields, capabilities, formats, modalities and reasons are ignored, as the contract asks. Pumas is reached as an HTTP endpoint only. No running Pumas was contacted: everything is checked against fakes built from the release. Co-Authored-By: Claude Fable 5.2 --- ai_http.py | 7 +- .../contracts/pumas-image-to-text-consumer.md | 67 +- .../definition-first-projects/spec-d3.md | 27 + image_generation.py | 6 +- pumas_gateway_descriptor.py | 5 +- pumas_operations.py | 222 ++- pumas_vision.py | 12 +- tests/fake_pumas_typed.py | 13 +- .../controlled-capabilities.json | 175 ++- .../schemas/capabilities-response.schema.json | 194 ++- .../schemas/capability-descriptor.schema.json | 169 ++- .../served-models-response.schema.json | 417 ++++++ .../pumas-image-to-text-v1/served-models.json | 1199 +++++++++++++++++ .../pumas-image-to-text-v1/source.json | 93 +- .../controlled-image-capabilities.json | 2 +- .../controlled-text-capabilities.json | 2 +- tests/fixtures/pumas-typed-v1/source.json | 7 +- tests/test_pumas_served_models.py | 143 ++ tests/test_pumas_typed.py | 3 + tests/test_pumas_vision.py | 17 +- 20 files changed, 2625 insertions(+), 155 deletions(-) create mode 100644 tests/fixtures/pumas-image-to-text-v1/schemas/served-models-response.schema.json create mode 100644 tests/fixtures/pumas-image-to-text-v1/served-models.json create mode 100644 tests/test_pumas_served_models.py diff --git a/ai_http.py b/ai_http.py index d1ac25ac..933a0b2b 100644 --- a/ai_http.py +++ b/ai_http.py @@ -91,7 +91,8 @@ def collect(value, depth=0): def pumas_error_detail(data, payload=None, headers=None): """Pumas' OpenAI-compatible errors carry its (redacted) reason in `error.message`. - Returns '' for any body that is not a bounded `pumas_error`; that reason is + Returns '' for any body that is not a bounded `pumas_error` or typed + operation error; that reason is still passed through the same redaction as other provider diagnostics. """ if not data or len(data) > MAX_ERROR_BODY: @@ -101,7 +102,9 @@ def pumas_error_detail(data, payload=None, headers=None): except (ValueError, UnicodeError): return '' error = value.get('error') if isinstance(value, dict) else None - if (not isinstance(error, dict) or error.get('type') != 'pumas_error' + # Typed operation errors (contract version 1) carry `code`, `outcome` and `message` instead of `type`. + typed = isinstance(error, dict) and value.get('contract_version') == 1 and isinstance(error.get('outcome'), str) + if (not isinstance(error, dict) or (error.get('type') != 'pumas_error' and not typed) or not isinstance(error.get('message'), str) or not error['message'].strip()): return '' detail = provider_error_detail(json.dumps({'message': error['message']}).encode(), payload, headers) diff --git a/docs/contracts/pumas-image-to-text-consumer.md b/docs/contracts/pumas-image-to-text-consumer.md index c557e28e..3d54eef9 100644 --- a/docs/contracts/pumas-image-to-text-consumer.md +++ b/docs/contracts/pumas-image-to-text-consumer.md @@ -1,13 +1,15 @@ # Pumas Image→Text consumer This opt-in caption path, and the typed text and image operations that share -`pumas_operations`, consume the Pumas Library v0.8 typed HTTP contract on branch -`feat/v080-consumer-api`, source `4c79cd8e35db566b70caaa13d8d8f92265f5976e`: -[model operations, contract version 1](https://github.com/MrScripty/Pumas-Library/blob/4c79cd8e35db566b70caaa13d8d8f92265f5976e/docs/contracts/model-operations-v1.md). -It supersedes the merged PR68 pin `36c2aab2c885b8416fd4e39cf8c37c510596d6e4`, -which `source.json` keeps as `previous_producer`. The legacy compatible caption -path remains available. The PR54 typed text/image capture receipt in -`tests/fixtures/pumas-typed-v1` is historical and is not repinned. +`pumas_operations`, consume the typed HTTP contract released in Pumas Library +0.8.0, tag `v0.8.0`, commit `69e32a2208c5c2d840f4adafec03350669fcb5bc`: +[model operations, contract version 1](https://github.com/MrScripty/Pumas-Library/blob/v0.8.0/docs/contracts/model-operations-v1.md). +Pumas is reached only as an HTTP endpoint; no Pumas code is imported or started. +It supersedes the pre-release pin `4c79cd8e35db566b70caaa13d8d8f92265f5976e` +(and before it PR68), which `source.json` keeps as `previous_producer`. The +legacy compatible caption path remains available. The PR54 typed text/image +capture receipt in `tests/fixtures/pumas-typed-v1` keeps its gateway harness; +its capability files were brought to the 0.8.0 descriptor shape. ### Additive compatibility @@ -23,16 +25,26 @@ position or count: validated: fixed semantic task, string format lists, an availability `state` with an optional string reason, and finite, ordered bounds for the options Tuldok compares (`max_tokens`, `temperature`, `top_p`, `width`, `height`, - `seed`, `image_bytes`, `image_pixels`, `image_count`). A used capability or + `seed`, `input_characters`, `image_bytes`, `total_image_bytes`, `image_pixels`, + `image_count`, `message_count`, `content_parts`). A used capability or option advertised twice is refused as ambiguous. -- Other capabilities (`multimodal_embedding`, `decision`, audio, future values), - formats (`content_batch`, `decision`, `decisions`, future values), option names, +- Other capabilities (`multimodal_embedding`, `decision`, `rerank`, audio, future + values), formats (`content_batch`, `decision`, `decisions`, `relevance_scores`, + future values), modalities, option names, availability states and reasons, and response or result fields are ignored. Any availability other than `available` means unavailable, and its reason is shown. - The capability observation is bounded at 1 MiB. `GET /v1/served-models` is preferred for listing serving aliases with their profiles; gateways without it (HTTP 404) fall back to `/v1/models`, which lists each ID once with `profiles`. +- `pumas_operations.served_models(address)` reads `GET /v1/served-models` in + full, independent of the catalog: each served (model, profile) with + `profile_required`, model ID, provider, load state, context size, input and + output modalities and its descriptors with availability, bounded at 8 MiB and + 4096 entries. Values outside the 0.8.0 vocabulary are dropped; a malformed + entry refuses the listing, naming the entry. `available_capabilities(entry, + input_kind, output)` answers which available capabilities make an output from + a request input kind, as the release's resolver matches input formats. Availability is a live observation, not a model qualification receipt. @@ -58,7 +70,7 @@ aggregate, four-image, 4096-axis, 4,194,304-pixel, 128-message and 128-total-par bounds. Tokens default to 512. Pumas no longer caps Image→Text `max_tokens` at 2048; the live `max_tokens` bound follows the served context window and is checked before admission. Temperature/top-p must be finite and within 0–2/0–1. -Advertised image byte, pixel, count and dimension bounds are checked when present. The caption application's existing preparation is smaller: +Advertised image byte, aggregate byte, pixel, count, dimension, message and part bounds are checked when present. The caption application's existing preparation is smaller: one RGB JPEG, at most 2 MiB and 1600 pixels on its longest side. It decodes the captured, hash-verified canonical image and retains both canonical-source and prepared-input hashes. Preparation is explicit in request history. @@ -80,6 +92,8 @@ bytes. Explicit application creates a draft target and records its evidence in revision history; human review remains separate. Every typed error is `{contract_version, request_id, error:{code, outcome, message}}`. +A refusal made before the request reaches its handler is `{"error":{"code","message"}}` +(for example `request_limit`, HTTP 413); it is decoded as a typed `not_admitted` refusal. `error.outcome` is authoritative: `not_admitted` records no provider effect and anything else is `unknown`, whatever the HTTP status. 404 `model_not_found` and 409 `ambiguous_model`/`ambiguous_operation` are ordinary refusals. An error whose @@ -103,30 +117,29 @@ and packaged application acceptance remain integration-lead/provider-owner gates ## Evidence and coordinated review `tests/fixtures/pumas-image-to-text-v1/source.json` labels the capability/wire -fixture as **source-derived**, with inspected production-source hashes. It is not -a captured native DTO schema export or an actual model reply. The fixture follows -the pinned descriptor construction for a llama.cpp vision serving with an -8192-token context, including the `multimodal_embedding` and `decision` -descriptors. The tests exercise additive capability parsing, named/facade PNG/JPEG inputs (including progressive +fixture as **release-derived**. It is not a captured native DTO schema export or +an actual model reply. The fixtures (`controlled-capabilities.json`, +`served-models.json`) follow the 0.8.0 descriptor construction for a llama.cpp +vision serving with an 8192-token context and a Torch image serving, including +modalities and the `multimodal_embedding`, `decision` and `rerank` descriptors. The tests exercise additive capability parsing, named/facade PNG/JPEG inputs (including progressive JPEG), order, closed shapes, finite/resource bounds, typed application captions, draft/history, live selection refusal, cancellation/borrowed-owner survival, HTTP outcomes, restart and no replay. The existing typed browser suite additionally checks the actual caption form, capability inspection, application and disconnect. -The six actual production DTO schemas regenerated at the pinned source with the -`export-contract` feature are retained in -`tests/fixtures/pumas-image-to-text-v1/schemas/`, with SHA-256 identities in -`source.json`. All six changed from the PR68 export (new capabilities, formats, -`context_tokens`, decision and content-batch DTOs and the required error -`message`). The -source-derived capability fixture and authored named/facade image requests and -typed responses validate against these exports in the vision tests. The schemas +The schemas in `tests/fixtures/pumas-image-to-text-v1/schemas/` have SHA-256 +identities and origins in `source.json`. `capability-descriptor.schema.json` is +the copy the 0.8.0 release ships; `capabilities-response` and +`served-models-response` are derived from it and from `types.rs` at the tag; the +request, response and error schemas remain the pre-release export, as the +release's changes to them are additive and Pumas is not built here. The +capability fixtures and authored named/facade image requests and typed +responses validate against these schemas in the vision tests. The schemas describe wire shape; finite bounds and live readiness remain runtime checks. Neither fixture output nor schema validity proves native inference. -`source.json` records the branch, commit, tree, contract document hash and -handler/controlled-test source hashes. The pin is a branch commit, not a merged -Pumas main commit; repin when it merges. The fixture gateway advertisement reads +`source.json` records the tag, commit, tree and contract document hash. The +fixture gateway advertisement reads the same versioned source pin as its consumer acceptance evidence. The combined desktop contract and packaged application are provider integration gates. Real model/projector inference, semantic quality, managed native teardown diff --git a/docs/plans/definition-first-projects/spec-d3.md b/docs/plans/definition-first-projects/spec-d3.md index ab2e5454..0ed7e0a8 100644 --- a/docs/plans/definition-first-projects/spec-d3.md +++ b/docs/plans/definition-first-projects/spec-d3.md @@ -35,3 +35,30 @@ A disposable PostgreSQL, as the rules say (`/tmp/claude-1000/d3/pg`), with `TULD ## 4. Out of scope Any use of the endpoint from a project folder; where a project keeps the endpoint's address; audio and 3D output (the release reserves audio output and has none for 3D); decisions, rerank, embeddings and transcription as Tuldok features (the served-models answer lists them; nothing calls them yet). + +## As built + +The earlier work (`feat/pumas-v080-api`, written against the pre-release `4c79cd8e`) was merged with `git merge --no-commit --no-ff` and left open. It was then compared with Pumas Library `v0.8.0` (commit `69e32a2208c5c2d840f4adafec03350669fcb5bc`), read with `git show` only. "Earlier client" below means the merged state before this phase's changes. + +| Area | Released contract (0.8.0) | Earlier client | Done | +| --- | --- | --- | --- | +| Endpoints | `GET /v1/served-models`, `GET /v1/capabilities`, `POST /v1/model-operations`; `/v1/models` lists each ID once with `profiles`; `POST /v1/images/generations`; `GET /.well-known/pumas` | All used. `/v1/served-models` was read only for (model, profile) pairs to fill a model list | New `served_models()` and `available_capabilities()` (2.4). The listing for catalog forms is unchanged | +| Request `input` kinds and `output` | Kinds `text`, `text_batch`, `messages`, `image_messages`, `image`, `content_batch`, `decision`, `rerank`, reserved `audio`; outputs `text`, `embeddings_float32`, `png_base64`, `decisions`, `relevance_scores`, reserved `labels`, `pcm_*`. Message content is a string or parts; parts gain `audio` | Sends `messages` (string content), `image`, `messages`/`image_messages` with text and image parts; outputs `text`, `png_base64`. All still valid | No change to requests. `INPUT_KINDS` maps each kind to the descriptor formats the release's resolver matches, for `available_capabilities()` | +| Results | `text` (finish `stop`/`length`/`content_filter`), `embeddings`, `image`, `decisions`, `relevance_scores` | Decodes `text` and `image`; refuses a finish other than `stop` as incomplete (outcome `unknown`) | No change: Tuldok applies only complete text and requests no other result kind | +| Capability names | Ten, adding `rerank` (and `audio_transcription`, `audio_classification`) | Selects `chat_generation`, `image_generation`, `image_to_text` by name; ignores others | No change to selection. Release vocabulary recorded in `CAPABILITIES`; fixtures gain `rerank` | +| Descriptor fields | Required `input_modalities`, `output_modalities` per descriptor; `modalities {input, output}` per serving | Not read (tolerated) | Read and validated by `served_models()`; fixtures carry them. `/v1/capabilities` decoding still does not require them | +| Option names | Adds `total_image_bytes`, `message_count`, `content_parts`, `input_tokens`, `top_n`, audio bounds | Compared `max_tokens`, `temperature`, `top_p`, `width`, `height`, `seed`, `image_bytes`, `image_pixels`, `image_count` | Image→Text also checks `total_image_bytes`, `message_count`, `content_parts`; typed image generation checks `input_characters` against the prompt. Both only when advertised | +| Availability reasons | Closed set `unsupported_adapter`, `unknown_model_task`, `model_task_mismatch`, `runtime_unavailable` | Any string shown; fixtures used the pre-release `unqualified_audio_runtime` | Fixtures use release reasons. Unknown reasons still shown as text, never interpreted | +| Error shape | `{contract_version, request_id, error:{code, outcome, message}}`; pre-handler refusals are `{"error":{"code","message"}}` | Pre-handler body on `/v1/model-operations` was read as malformed (outcome `unknown`, code lost) | Decoded as a typed refusal, `not_admitted`, code kept. `ai_http` also shows the `message` of a typed error (e.g. from `/v1/served-models`) | +| Error codes and statuses | Twelve codes, status per code (400/404/409/413/422/503/502) | Codes kept verbatim; `outcome` authoritative, status recorded as evidence | No change | +| Byte bounds | Request/response 32 MiB, stream event 256 KiB; images 8 MiB each, 16 MiB total, 4 images, 4096 px, 4 Mpx; 128 messages/parts; message ≤ 1024 bytes | Same bounds locally; responses read under the lesser of Tuldok's and the advertised bound | No change. `served_models()` reads at most 8 MiB and 4096 entries | +| Image generation | Width/height bound 1–2³²−1 (no allowlist); `memory_policy` gains `scaled_fp8_to_bf16_sequential_cpu_offload`; errors `{"error":{"type":"pumas_error",code,message}}` with 400/409/499/502/503/507 | Typed path caps at 2048 px/side, 4 Mpx (Tuldok's own limit); legacy path dropped unknown memory policies | Cap kept (Tuldok policy, within the release bound). Any `[a-z0-9_]{1,64}` memory policy is now kept | +| `/.well-known/pumas` | `HttpServiceDescription`, `InstanceDescription`, `PumasBuildInfo` as at the tag | Same fields and types; `service_generation` limited to 128 characters | Limit raised to 256, as the release's reference consumer allows. Fixture unchanged (its shape matches the release) | +| Pins | — | `pumas_operations.SOURCE_COMMIT` = `4c79cd8e…`, `pumas_gateway_descriptor.SOURCE_COMMIT` = `80f06ab1…` (PR51) | Both `69e32a22…` (`v0.8.0`); `pumas_vision` follows `pumas_operations` | +| Fixtures | Only `capability-descriptor.schema.json` is published at the tag | Six schemas exported at `4c79cd8e` | Descriptor schema replaced by the release copy (its digest equals the one the release's consumer reference pins); `capabilities-response` and a new `served-models-response` derived from it and `types.rs`; the other four kept, marked in `source.json` | + +Notes on the spec: + +- 2.4 says the functions run "over the HTTP transport already used (`ai_http`)". The typed module's other GETs use `gateway_discovery.get_json`; `served_models()` uses `ai_http.request` as written, so it takes any HTTP(S) address (a trailing `/v1` is accepted), not only numeric loopback. `available_capabilities()` makes no request. +- "Whatever else is declared" is read as the release's output formats. An output or input kind outside them raises `ValueError`, since unknown values are dropped from descriptors. +- A malformed entry refuses the whole listing, naming the entry, as the other decoders in these modules do; unknown values within an entry are dropped. diff --git a/image_generation.py b/image_generation.py index 2ca126f5..67f1a92e 100644 --- a/image_generation.py +++ b/image_generation.py @@ -11,6 +11,7 @@ import http.client import io import json +import re import select import socket import threading @@ -93,7 +94,8 @@ def decode_image(data, width, height): for key in ('seed', 'steps', 'guidance', 'duration_seconds'): if type(metadata.get(key)) in (int, float): safe_metadata[key] = metadata[key] - if metadata.get('memory_policy') in ('sequential_cpu_offload', 'model_cpu_offload', 'gpu'): + # The policy set grows with adapters (0.8.0 adds `scaled_fp8_to_bf16_sequential_cpu_offload`). + if isinstance(metadata.get('memory_policy'), str) and re.fullmatch(r'[a-z0-9_]{1,64}', metadata['memory_policy']): safe_metadata['memory_policy'] = metadata['memory_policy'] result['metadata'] = safe_metadata return result @@ -122,6 +124,8 @@ def typed_generate(base, body, operation, payload, on_admission=None): evidence = {'capability_observation': observed, 'producer_contract_source': pumas.SOURCE_COMMIT} try: pumas.require(observed, 'image_generation', 'text', 'png_base64', options) + pumas.require(observed, 'image_generation', 'text', 'png_base64', {'input_characters': len(payload['prompt'])}, + advisory=('input_characters',)) request = {'contract_version': 1, 'request_id': body['request_id'], 'model': payload['model'], 'profile': observed['capabilities']['profile'], 'capability': 'image_generation', 'input': {'kind': 'text', 'text': payload['prompt']}, 'output': 'png_base64', diff --git a/pumas_gateway_descriptor.py b/pumas_gateway_descriptor.py index b1eb3ec0..c6469b53 100644 --- a/pumas_gateway_descriptor.py +++ b/pumas_gateway_descriptor.py @@ -11,7 +11,8 @@ import json from urllib.parse import urlsplit -SOURCE_COMMIT = '80f06ab17f9eea639fee143c86319ca9b5e1a21c' +# Pumas Library tag v0.8.0, whose `HttpServiceDescription` and `PumasBuildInfo` this decodes. +SOURCE_COMMIT = '69e32a2208c5c2d840f4adafec03350669fcb5bc' # Transport bound. Open lists have no entry-count cap of their own. MAX_DESCRIPTION_BYTES = 64 * 1024 @@ -142,7 +143,7 @@ def decode(raw): value = _object(value, '', ('advertisement_schema_version', 'service_generation', 'instance', 'endpoint', 'build_info')) _version(value['advertisement_schema_version'], 'advertisement_schema_version') - _text(value['service_generation'], 'service_generation', 128) + _text(value['service_generation'], 'service_generation', 256) try: endpoint(value['endpoint']) except ValueError as error: diff --git a/pumas_operations.py b/pumas_operations.py index 3878473a..e3260895 100644 --- a/pumas_operations.py +++ b/pumas_operations.py @@ -1,8 +1,10 @@ -"""Finite Pumas typed model operations (contract version 1, v0.8 additive rules). +"""Finite Pumas typed model operations, as released in Pumas Library 0.8.0 (contract version 1). -Discovery budgets never time generation. Responses grow additively: unknown -response fields, capabilities, formats, option names, availability reasons and -error codes are ignored; only what Tuldok uses is validated and selected by name. +Pumas is reached only as an HTTP endpoint. Discovery budgets never time +generation. Responses grow additively: unknown response fields, capabilities, +formats, modalities, option names, availability reasons and error codes are +ignored; only what Tuldok uses is validated and selected by name. Requests send +only what the selected serving declared. """ import hashlib import http.client @@ -13,14 +15,18 @@ import time from urllib.parse import urlencode, urlsplit +import ai_http +from ai_codex import CodexError import gateway_discovery from pumas_gateway_descriptor import endpoint from workbench import WorkbenchError, encode PROTOCOL = 'pumas_typed_v1' -SOURCE_COMMIT = '4c79cd8e35db566b70caaa13d8d8f92265f5976e' +# Pumas Library tag v0.8.0: the released contract this module follows. +SOURCE_COMMIT = '69e32a2208c5c2d840f4adafec03350669fcb5bc' MAX_CAPABILITIES = 1024 * 1024 MAX_SERVED_MODELS = 8 * 1024 * 1024 +MAX_SERVED_ENTRIES = 4096 MAX_TEXT_RESPONSE = 256 * 1024 MAX_IMAGE_JSON = 12 * 1024 * 1024 MAX_DIMENSION = 2048 @@ -30,8 +36,25 @@ USED_CAPABILITIES = {'chat_generation': 'chat_generation', 'image_generation': 'text_to_image', 'image_to_text': 'image_to_text'} # Option bounds Tuldok compares against. Other advertised options are ignored. -USED_OPTIONS = {'max_tokens', 'temperature', 'top_p', 'width', 'height', 'seed', - 'image_bytes', 'image_pixels', 'image_count'} +USED_OPTIONS = {'max_tokens', 'temperature', 'top_p', 'width', 'height', 'seed', 'input_characters', + 'image_bytes', 'image_pixels', 'image_count', 'total_image_bytes', 'message_count', 'content_parts'} +# The 0.8.0 release vocabulary. Values outside these sets are ignored, never an error. +CAPABILITIES = ('chat_generation', 'text_generation', 'text_embedding', 'image_generation', 'image_to_text', + 'multimodal_embedding', 'decision', 'rerank', 'audio_transcription', 'audio_classification') +INPUT_FORMATS = ('messages_text', 'messages_image', 'messages_multimodal', 'text', 'text_batch', 'png_base64', + 'jpeg_base64', 'pcm_s16le', 'pcm_f32le', 'content_batch', 'decision', 'rerank') +OUTPUT_FORMATS = ('text', 'embeddings_float32', 'png_base64', 'decisions', 'relevance_scores', 'labels') +MODALITIES = ('text', 'image', 'audio', 'video', 'json', 'vector') +OPTION_NAMES = ('max_tokens', 'temperature', 'top_p', 'dimensions', 'input_count', 'input_characters', 'width', + 'height', 'seed', 'max_output_tokens', 'image_bytes', 'image_pixels', 'image_count', + 'total_image_bytes', 'message_count', 'content_parts', 'input_tokens', 'top_n', 'audio_count', + 'total_audio_bytes', 'audio_seconds', 'sample_rate') +# Request `input.kind` to the descriptor input formats that accept it (the release's resolver). +# `messages` with image parts is the same request as `image_messages`; ask with that kind. +INPUT_KINDS = {'text': ('text',), 'text_batch': ('text_batch',), 'messages': ('messages_text',), + 'image_messages': ('messages_image',), 'image': ('png_base64', 'jpeg_base64'), + 'content_batch': ('content_batch',), 'decision': ('decision',), 'rerank': ('rerank',), + 'audio': ('pcm_s16le', 'pcm_f32le')} class OperationError(WorkbenchError): @@ -84,11 +107,19 @@ def message_text(value): return value[:MAX_MESSAGE] + ('…' if len(value) > MAX_MESSAGE else '') +def pre_handler(value): + """True for a refusal made before the request reached its handler: `{"error":{"code","message"}}`.""" + return (type(value) is dict and type(value.get('error')) is dict and 'contract_version' not in value + and 'request_id' not in value and 'outcome' not in value['error']) + + def typed_error(value): """Decode `{contract_version, request_id, error:{code, outcome, message}}` or return None. `outcome` is authoritative. Only `not_admitted` proves no provider effect; - any other value is treated as `unknown`. Unknown codes are kept verbatim. + any other value is treated as `unknown`. A pre-handler refusal has no + outcome and never reached a handler, so it is `not_admitted`. Unknown codes + are kept verbatim. """ if type(value) is not dict or type(value.get('error')) is not dict: return None @@ -96,7 +127,7 @@ def typed_error(value): code = error.get('code') if not isinstance(code, str) or not code or len(code) > 200: return None - outcome = 'not_admitted' if error.get('outcome') == 'not_admitted' else 'unknown' + outcome = 'not_admitted' if error.get('outcome') == 'not_admitted' or pre_handler(value) else 'unknown' return {'code': code, 'outcome': outcome, 'message': message_text(error.get('message'))} @@ -298,6 +329,174 @@ def missing(status, raw): max_response=1024*1024, decode=_openai_models, require_complete=True, error=http_error) +def _known(values, vocabulary, where): + """The known members of a declared list, in order; unknown strings are ignored.""" + if type(values) is not list or any(type(value) is not str for value in values): + raise ValueError(where + ' must be a list of strings.') + return [value for value in dict.fromkeys(values) if value in vocabulary] + + +def _text_field(value, where, limit): + if not isinstance(value, str) or not value.strip() or len(value) > limit: + raise ValueError(f'{where} must be a nonempty string of at most {limit} characters.') + return value + + +def _served_descriptor(item, where): + """One release capability descriptor, reduced to the vocabulary Tuldok knows.""" + response_fields(item, ('capability', 'semantic_task', 'input_formats', 'output_formats', 'input_modalities', + 'output_modalities', 'streaming', 'availability', 'option_bounds')) + if type(item['semantic_task']) is not str or type(item['streaming']) is not bool: + raise ValueError(where + ' has an invalid semantic task or streaming flag.') + availability = item['availability'] + if type(availability) is not dict or type(availability.get('state')) is not str: + raise ValueError(where + ' has an invalid availability.') + reason = availability.get('reason') + if reason is not None and type(reason) is not str: + raise ValueError(where + ' has an invalid availability reason.') + bounds = {} + if type(item['option_bounds']) is not list: + raise ValueError(where + ' option bounds must be a list.') + for bound in item['option_bounds']: + if type(bound) is not dict or bound.get('option') not in OPTION_NAMES: + continue + response_fields(bound, ('option', 'minimum', 'maximum')) + if (bound['option'] in bounds or not _bound_number(bound['minimum']) or not _bound_number(bound['maximum']) + or bound['minimum'] > bound['maximum']): + raise ValueError(where + ' has an invalid or repeated ' + bound['option'] + ' bound.') + bounds[bound['option']] = {'minimum': bound['minimum'], 'maximum': bound['maximum']} + available = availability['state'] == 'available' + return {'capability': item['capability'], 'semantic_task': item['semantic_task'], + 'input_formats': _known(item['input_formats'], INPUT_FORMATS, where + ' input formats'), + 'output_formats': _known(item['output_formats'], OUTPUT_FORMATS, where + ' output formats'), + 'input_modalities': _known(item['input_modalities'], MODALITIES, where + ' input modalities'), + 'output_modalities': _known(item['output_modalities'], MODALITIES, where + ' output modalities'), + 'streaming': item['streaming'], + # An unknown reason is kept as display text, never interpreted. + 'availability': {'state': 'available'} if available else + {'state': 'unavailable', 'reason': message_text(reason) or None}, + 'option_bounds': bounds} + + +def _served_entry(item, where): + response_fields(item, ('model', 'profile', 'model_id', 'provider', 'load_state', 'profile_required', + 'modalities', 'capabilities')) + selected = profile(item['profile']) + if selected is None: + raise ValueError(where + ' has no exact profile.') + context = item.get('context_tokens') + if context is not None and (type(context) is not int or not 0 < context <= 4294967295): + raise ValueError(where + ' context_tokens must be a positive 32-bit integer.') + if type(item['profile_required']) is not bool: + raise ValueError(where + ' profile_required must be true or false.') + modalities = item['modalities'] + response_fields(modalities, ('input', 'output')) + if type(item['capabilities']) is not list: + raise ValueError(where + ' capabilities must be a list.') + capabilities = [] + for index, row in enumerate(item['capabilities']): + if type(row) is not dict or row.get('capability') not in CAPABILITIES: + continue + if any(seen['capability'] == row['capability'] for seen in capabilities): + raise ValueError(where + ' lists ' + row['capability'] + ' more than once.') + capabilities.append(_served_descriptor(row, f'{where} capability {index}')) + return {'model': alias(item['model']), 'profile': selected, 'profile_required': item['profile_required'], + 'model_id': _text_field(item['model_id'], where + ' model_id', 1024), + 'provider': _text_field(item['provider'], where + ' provider', 128), + 'load_state': _text_field(item['load_state'], where + ' load_state', 128), + 'context_tokens': context, + 'modalities': {'input': _known(modalities['input'], MODALITIES, where + ' input modalities'), + 'output': _known(modalities['output'], MODALITIES, where + ' output modalities')}, + 'capabilities': capabilities} + + +def decode_served_models(raw): + """Validate a `GET /v1/served-models` body into the served (model, profile) pairs. + + Refuses a body that is not contract version 1, lacks a required field or + has a malformed entry, naming the entry. Capabilities, formats, modalities + and option names outside the release vocabulary, and unknown fields, are + dropped without error. + """ + if len(raw) > MAX_SERVED_MODELS: + raise ValueError(f'The served-model listing exceeds {MAX_SERVED_MODELS} bytes.') + value = strict_json(raw) + response_fields(value, ('supported_contract_versions', 'max_request_bytes', 'max_response_bytes', 'models')) + versions = value['supported_contract_versions'] + if type(versions) is not list or not any(type(version) is int and version == 1 for version in versions): + raise ValueError('Pumas typed contract version 1 is unavailable.') + for key in ('max_request_bytes', 'max_response_bytes'): + if not _positive_int(value[key]): + raise ValueError('Unsupported typed Pumas byte bounds.') + if type(value['models']) is not list or len(value['models']) > MAX_SERVED_ENTRIES: + raise ValueError(f'The served-model listing must be a list of at most {MAX_SERVED_ENTRIES} entries.') + models, pairs = [], set() + for index, item in enumerate(value['models']): + try: + entry = _served_entry(item, f'Served model {index}') + except ValueError as error: + message = str(error) + raise ValueError(message if message.startswith('Served model') else f'Served model {index}: {message}') from None + if (entry['model'], entry['profile']) in pairs: + raise ValueError(f"Served model {index} repeats {entry['model']} with profile {entry['profile']}.") + pairs.add((entry['model'], entry['profile'])) + models.append(entry) + return {'max_request_bytes': value['max_request_bytes'], 'max_response_bytes': value['max_response_bytes'], + 'models': models} + + +def served_models(address, cancel_event=None): + """What a Pumas endpoint serves: each (model, profile) with its capabilities, from `GET /v1/served-models`. + + Independent of the catalog. Reads at most `MAX_SERVED_MODELS` bytes within + 15 seconds and never retries. Raises `OperationError` with the reason. + """ + base = ai_http.validate_url('llamacpp', address) + try: + with ai_http.request(base, '/v1/served-models', timeout=15, label='Pumas endpoint', + cancel_event=cancel_event) as (response, transport, deadline): + raw = bytearray() + while not response.isclosed(): + remaining = deadline - time.monotonic() + if remaining <= 0: + raise TimeoutError() + transport.settimeout(remaining) + chunk = response.read1(65536) + if not chunk: + break + raw.extend(chunk) + if len(raw) > MAX_SERVED_MODELS: + raise ValueError(f'The served-model listing exceeds {MAX_SERVED_MODELS} bytes.') + if response.length not in (None, 0): + raise ValueError('The served-model listing ended before its declared length.') + return decode_served_models(bytes(raw)) + except (CodexError, TimeoutError, OSError, http.client.HTTPException, ValueError) as error: + raise OperationError('Pumas served models unavailable: ' + (str(error) or 'the endpoint timed out.')) from None + + +def available_capabilities(served, input_kind, output): + """The capabilities of one served model that are available to make `output` from `input_kind`. + + `served` is one entry of `served_models()`. `input_kind` is a request + `input.kind`; `output` an output format of the release. Returns capability + names in the order the endpoint declared them. + """ + if input_kind not in INPUT_KINDS: + raise ValueError('Unknown input kind; use one of ' + ', '.join(INPUT_KINDS) + '.') + if output not in OUTPUT_FORMATS: + raise ValueError('Unknown output; use one of ' + ', '.join(OUTPUT_FORMATS) + '.') + names = [] + for row in served['capabilities']: + formats = INPUT_KINDS[input_kind] + # The release sends a `text` input to chat as one user message. + if input_kind == 'text' and row['capability'] == 'chat_generation': + formats = ('messages_text',) + if (row['availability']['state'] == 'available' and output in row['output_formats'] + and any(name in row['input_formats'] for name in formats)): + names.append(row['capability']) + return names + + def descriptor(observed, name): """Select a capability descriptor by name, never by position or count.""" return next((row for row in observed['capabilities']['capabilities'] @@ -404,6 +603,11 @@ def result(raw, request_id): """Decode a finite typed response. Unknown response fields are ignored.""" try: value = strict_json(raw) + if pre_handler(value): + error = typed_error(value) + if error is None: + raise ValueError('Invalid Pumas refusal.') + raise OperationError(error_message(error), error['outcome'], error['code'], raw) if type(value) is not dict or type(value.get('contract_version')) is not int or value['contract_version'] != 1: raise ValueError('Typed response is not contract version 1.') if 'error' in value: diff --git a/pumas_vision.py b/pumas_vision.py index 59a677ab..81badc8a 100644 --- a/pumas_vision.py +++ b/pumas_vision.py @@ -1,4 +1,4 @@ -"""Finite Image→Text consumer of the Pumas v0.8 typed contract, never model qualification. +"""Finite Image→Text consumer of the Pumas 0.8.0 typed contract, never model qualification. The application sends its prepared image bytes, without URL/path authority. Pumas's production PNG/turbojpeg decoder remains the admission authority. @@ -28,7 +28,8 @@ MAX_MESSAGES = MAX_PARTS = 128 # Pumas has no fixed generation cap; the live max_tokens bound follows the served context. MAX_TOKENS = 4294967295 -IMAGE_FACTS = ('image_count', 'image_bytes', 'image_pixels', 'width', 'height') +IMAGE_FACTS = ('image_count', 'image_bytes', 'image_pixels', 'width', 'height', 'total_image_bytes', + 'message_count', 'content_parts') def _container(data, encoding): @@ -176,7 +177,12 @@ def prepare(job, payload, stop): input_format, images = validate_input(payload['input'], facade='semantic_task' in payload) options = {key: value for key, value in payload['options'].items() if key != 'kind'} # Image facts are checked against advertised bounds; local preflight already bounds them. - pumas.require(observed, 'image_to_text', input_format, 'text', dict(options, image_count=len(images)), advisory=IMAGE_FACTS) + facts = dict(options, image_count=len(images), total_image_bytes=sum(row['image_bytes'] for row in images)) + if payload['input']['kind'] != 'image': + messages = payload['input']['messages'] + facts.update(message_count=len(messages), content_parts=sum( + 1 if type(message['content']) is str else len(message['content']) for message in messages)) + pumas.require(observed, 'image_to_text', input_format, 'text', facts, advisory=IMAGE_FACTS) for image in images: pumas.require(observed, 'image_to_text', input_format, 'text', image, advisory=IMAGE_FACTS) job.update(capability_observation=observed, build_observation=build, producer_contract_source=SOURCE_COMMIT) pumas.request_evidence(job, payload) diff --git a/tests/fake_pumas_typed.py b/tests/fake_pumas_typed.py index e28f311e..10d301a3 100644 --- a/tests/fake_pumas_typed.py +++ b/tests/fake_pumas_typed.py @@ -1,4 +1,4 @@ -"""Source-derived PR54 finite HTTP fixture; it is not the native gateway.""" +"""Source-derived PR54 finite HTTP fixture, with 0.8.0 served-model listings; it is not the native gateway.""" import base64 import json import threading @@ -24,8 +24,14 @@ def reply(self, value, status=200): try: self.wfile.write(raw) except OSError: pass def do_GET(self): + if self.path == '/v1/served-models' and state.get('served_models_raw') is not None: + raw = state['served_models_raw'] + self.send_response(200); self.send_header('Content-Length', str(len(raw))); self.end_headers() + try: self.wfile.write(raw) + except OSError: pass + return if self.path == '/v1/served-models' and state.get('served_models') is not None: - return self.reply(state['served_models']) + return self.reply(state['served_models'], state.get('served_models_status', 200)) if self.path == '/v1/models': rows = [{'id': 'controlled-text'}, {'id': 'controlled-image'}] if state.get('duplicate_alias'): rows.append({'id': 'controlled-text'}) @@ -57,6 +63,9 @@ def do_POST(self): return self.reply({'contract_version': 1, 'request_id': body['request_id'], 'error': {'code': 'capability_unavailable' if mode == 'not_admitted' else 'provider_failure', 'outcome': mode, 'message': state.get('error_message', 'fixture provider reason')}}, state.get('error_status', 503)) + if mode == 'pre_handler': + # 0.8.0 refusals made before the handler carry only code and message. + return self.reply({'error': {'code': 'request_limit', 'message': 'the request body exceeds 33554432 bytes'}}, 413) if mode == 'unreadable': return self.reply({'contract_version': 1, 'request_id': None, 'error': {'code': 'invalid_request', 'outcome': 'not_admitted', 'message': 'request body is not valid JSON'}}, 400) diff --git a/tests/fixtures/pumas-image-to-text-v1/controlled-capabilities.json b/tests/fixtures/pumas-image-to-text-v1/controlled-capabilities.json index 262544db..ff524b1a 100644 --- a/tests/fixtures/pumas-image-to-text-v1/controlled-capabilities.json +++ b/tests/fixtures/pumas-image-to-text-v1/controlled-capabilities.json @@ -8,16 +8,33 @@ "max_response_bytes": 33554432, "max_stream_event_bytes": 262144, "context_tokens": 8192, + "modalities": { + "input": [ + "text", + "image" + ], + "output": [ + "text" + ] + }, "capabilities": [ { "capability": "chat_generation", "semantic_task": "chat_generation", "input_formats": [ - "messages_text" + "messages_text", + "messages_multimodal" ], "output_formats": [ "text" ], + "input_modalities": [ + "text", + "image" + ], + "output_modalities": [ + "text" + ], "streaming": true, "availability": { "state": "available" @@ -37,6 +54,46 @@ "option": "top_p", "minimum": 0.0, "maximum": 1.0 + }, + { + "option": "image_bytes", + "minimum": 1.0, + "maximum": 8388608.0 + }, + { + "option": "total_image_bytes", + "minimum": 1.0, + "maximum": 16777216.0 + }, + { + "option": "image_pixels", + "minimum": 1.0, + "maximum": 4194304.0 + }, + { + "option": "image_count", + "minimum": 0.0, + "maximum": 4.0 + }, + { + "option": "width", + "minimum": 1.0, + "maximum": 4096.0 + }, + { + "option": "height", + "minimum": 1.0, + "maximum": 4096.0 + }, + { + "option": "message_count", + "minimum": 1.0, + "maximum": 128.0 + }, + { + "option": "content_parts", + "minimum": 1.0, + "maximum": 128.0 } ] }, @@ -49,6 +106,12 @@ "output_formats": [ "text" ], + "input_modalities": [ + "text" + ], + "output_modalities": [ + "text" + ], "streaming": true, "availability": { "state": "available" @@ -81,6 +144,12 @@ "output_formats": [ "embeddings_float32" ], + "input_modalities": [ + "text" + ], + "output_modalities": [ + "vector" + ], "streaming": false, "availability": { "state": "unavailable", @@ -103,6 +172,12 @@ "output_formats": [ "png_base64" ], + "input_modalities": [ + "text" + ], + "output_modalities": [ + "image" + ], "streaming": false, "availability": { "state": "unavailable", @@ -141,10 +216,14 @@ "output_formats": [ "text" ], + "input_modalities": [], + "output_modalities": [ + "text" + ], "streaming": false, "availability": { "state": "unavailable", - "reason": "unqualified_audio_runtime" + "reason": "unsupported_adapter" }, "option_bounds": [ { @@ -164,6 +243,10 @@ "output_formats": [ "labels" ], + "input_modalities": [], + "output_modalities": [ + "json" + ], "streaming": false, "availability": { "state": "unavailable", @@ -182,6 +265,13 @@ "output_formats": [ "text" ], + "input_modalities": [ + "text", + "image" + ], + "output_modalities": [ + "text" + ], "streaming": false, "availability": { "state": "available" @@ -207,6 +297,11 @@ "minimum": 1.0, "maximum": 8388608.0 }, + { + "option": "total_image_bytes", + "minimum": 1.0, + "maximum": 16777216.0 + }, { "option": "image_pixels", "minimum": 1.0, @@ -226,6 +321,16 @@ "option": "height", "minimum": 1.0, "maximum": 4096.0 + }, + { + "option": "message_count", + "minimum": 1.0, + "maximum": 128.0 + }, + { + "option": "content_parts", + "minimum": 1.0, + "maximum": 128.0 } ] }, @@ -240,6 +345,13 @@ "output_formats": [ "embeddings_float32" ], + "input_modalities": [ + "text", + "image" + ], + "output_modalities": [ + "vector" + ], "streaming": false, "availability": { "state": "unavailable", @@ -256,6 +368,11 @@ "minimum": 1.0, "maximum": 8388608.0 }, + { + "option": "total_image_bytes", + "minimum": 1.0, + "maximum": 16777216.0 + }, { "option": "image_pixels", "minimum": 1.0, @@ -265,6 +382,16 @@ "option": "image_count", "minimum": 1.0, "maximum": 4.0 + }, + { + "option": "width", + "minimum": 1.0, + "maximum": 4096.0 + }, + { + "option": "height", + "minimum": 1.0, + "maximum": 4096.0 } ] }, @@ -277,6 +404,13 @@ "output_formats": [ "decisions" ], + "input_modalities": [ + "text", + "image" + ], + "output_modalities": [ + "json" + ], "streaming": false, "availability": { "state": "unavailable", @@ -288,6 +422,11 @@ "minimum": 1.0, "maximum": 8388608.0 }, + { + "option": "total_image_bytes", + "minimum": 1.0, + "maximum": 16777216.0 + }, { "option": "image_pixels", "minimum": 1.0, @@ -297,8 +436,40 @@ "option": "image_count", "minimum": 0.0, "maximum": 4.0 + }, + { + "option": "width", + "minimum": 1.0, + "maximum": 4096.0 + }, + { + "option": "height", + "minimum": 1.0, + "maximum": 4096.0 } ] + }, + { + "capability": "rerank", + "semantic_task": "rerank", + "input_formats": [ + "rerank" + ], + "output_formats": [ + "relevance_scores" + ], + "input_modalities": [ + "text" + ], + "output_modalities": [ + "json" + ], + "streaming": false, + "availability": { + "state": "unavailable", + "reason": "model_task_mismatch" + }, + "option_bounds": [] } ] } diff --git a/tests/fixtures/pumas-image-to-text-v1/schemas/capabilities-response.schema.json b/tests/fixtures/pumas-image-to-text-v1/schemas/capabilities-response.schema.json index c455d4f7..3e291b61 100644 --- a/tests/fixtures/pumas-image-to-text-v1/schemas/capabilities-response.schema.json +++ b/tests/fixtures/pumas-image-to-text-v1/schemas/capabilities-response.schema.json @@ -35,7 +35,6 @@ "AvailabilityReason": { "enum": [ "unsupported_adapter", - "unqualified_audio_runtime", "unknown_model_task", "model_task_mismatch", "runtime_unavailable" @@ -65,6 +64,11 @@ "const": "decision", "description": "Typed questions about a state answered with probabilities by a native\ndecision model (llama.cpp `/v1/systemone`, e.g. Kev, OpenJev).", "type": "string" + }, + { + "const": "rerank", + "description": "Relevance of each document to a query, scored by a reranker\n(llama.cpp `/v1/rerank`).", + "type": "string" } ] }, @@ -82,6 +86,13 @@ }, "type": "array" }, + "input_modalities": { + "description": "Content modalities this capability accepts for this served model.", + "items": { + "$ref": "#/$defs/Modality" + }, + "type": "array" + }, "option_bounds": { "items": { "$ref": "#/$defs/OptionBound" @@ -94,6 +105,13 @@ }, "type": "array" }, + "output_modalities": { + "description": "Modalities this capability produces.", + "items": { + "$ref": "#/$defs/Modality" + }, + "type": "array" + }, "semantic_task": { "$ref": "#/$defs/SemanticTask" }, @@ -106,6 +124,8 @@ "semantic_task", "input_formats", "output_formats", + "input_modalities", + "output_modalities", "streaming", "availability", "option_bounds" @@ -113,19 +133,75 @@ "type": "object" }, "InputFormat": { - "enum": [ - "messages_text", - "png_base64", - "jpeg_base64", - "messages_image", - "text", - "text_batch", - "pcm_s16le", - "pcm_f32le", - "content_batch", - "decision" + "oneOf": [ + { + "enum": [ + "messages_text", + "png_base64", + "jpeg_base64", + "messages_image", + "text", + "text_batch", + "pcm_s16le", + "pcm_f32le", + "content_batch", + "decision", + "rerank" + ], + "type": "string" + }, + { + "const": "messages_multimodal", + "description": "Messages whose parts include audio.", + "type": "string" + } + ] + }, + "Modality": { + "description": "A modality primitive: one kind of data, the same whether it is a model's\ninput or its output. `json` and `vector` are output-only result kinds.", + "oneOf": [ + { + "enum": [ + "text", + "image", + "audio", + "video" + ], + "type": "string" + }, + { + "const": "json", + "description": "Structured data checked against the capability's schema\n(decision answers, relevance scores).", + "type": "string" + }, + { + "const": "vector", + "description": "Embedding vectors.", + "type": "string" + } + ] + }, + "ModalitySet": { + "description": "What a served model accepts and produces, as its runtime declares it.", + "properties": { + "input": { + "items": { + "$ref": "#/$defs/Modality" + }, + "type": "array" + }, + "output": { + "items": { + "$ref": "#/$defs/Modality" + }, + "type": "array" + } + }, + "required": [ + "input", + "output" ], - "type": "string" + "type": "object" }, "OptionBound": { "properties": { @@ -149,22 +225,71 @@ "type": "object" }, "OptionName": { - "enum": [ - "max_tokens", - "temperature", - "top_p", - "dimensions", - "input_count", - "input_characters", - "width", - "height", - "seed", - "max_output_tokens", - "image_bytes", - "image_pixels", - "image_count" - ], - "type": "string" + "oneOf": [ + { + "enum": [ + "max_tokens", + "temperature", + "top_p", + "dimensions", + "input_count", + "input_characters", + "width", + "height", + "seed", + "max_output_tokens", + "image_bytes", + "image_pixels", + "image_count" + ], + "type": "string" + }, + { + "const": "total_image_bytes", + "description": "Decoded bytes of all images in one request.", + "type": "string" + }, + { + "const": "message_count", + "description": "Messages in one `image_messages` input.", + "type": "string" + }, + { + "const": "content_parts", + "description": "Content parts across one request.", + "type": "string" + }, + { + "const": "input_tokens", + "description": "Tokens per input, including special tokens, from the served model's\nown positional limit.", + "type": "string" + }, + { + "const": "top_n", + "description": "Documents returned by a `rerank` operation.", + "type": "string" + }, + { + "const": "audio_count", + "description": "Audio clips in one request.", + "type": "string" + }, + { + "const": "total_audio_bytes", + "description": "Decoded PCM bytes of all audio in one request.", + "type": "string" + }, + { + "const": "audio_seconds", + "description": "Seconds per audio clip.", + "type": "string" + }, + { + "const": "sample_rate", + "description": "Sample rate of an audio clip, in Hz.", + "type": "string" + } + ] }, "OutputFormat": { "enum": [ @@ -172,7 +297,8 @@ "embeddings_float32", "png_base64", "labels", - "decisions" + "decisions", + "relevance_scores" ], "type": "string" }, @@ -186,7 +312,8 @@ "audio_classification", "image_to_text", "multimodal_embedding", - "decision" + "decision", + "rerank" ], "type": "string" } @@ -223,6 +350,10 @@ "minimum": 0, "type": "integer" }, + "modalities": { + "$ref": "#/$defs/ModalitySet", + "description": "Modalities the served model accepts and produces, from its runtime." + }, "model": { "type": "string" }, @@ -245,6 +376,7 @@ "max_request_bytes", "max_response_bytes", "max_stream_event_bytes", + "modalities", "capabilities" ], "title": "CapabilitiesResponse", diff --git a/tests/fixtures/pumas-image-to-text-v1/schemas/capability-descriptor.schema.json b/tests/fixtures/pumas-image-to-text-v1/schemas/capability-descriptor.schema.json index 9dc9d126..7d2228eb 100644 --- a/tests/fixtures/pumas-image-to-text-v1/schemas/capability-descriptor.schema.json +++ b/tests/fixtures/pumas-image-to-text-v1/schemas/capability-descriptor.schema.json @@ -35,7 +35,6 @@ "AvailabilityReason": { "enum": [ "unsupported_adapter", - "unqualified_audio_runtime", "unknown_model_task", "model_task_mismatch", "runtime_unavailable" @@ -65,23 +64,62 @@ "const": "decision", "description": "Typed questions about a state answered with probabilities by a native\ndecision model (llama.cpp `/v1/systemone`, e.g. Kev, OpenJev).", "type": "string" + }, + { + "const": "rerank", + "description": "Relevance of each document to a query, scored by a reranker\n(llama.cpp `/v1/rerank`).", + "type": "string" } ] }, "InputFormat": { - "enum": [ - "messages_text", - "png_base64", - "jpeg_base64", - "messages_image", - "text", - "text_batch", - "pcm_s16le", - "pcm_f32le", - "content_batch", - "decision" - ], - "type": "string" + "oneOf": [ + { + "enum": [ + "messages_text", + "png_base64", + "jpeg_base64", + "messages_image", + "text", + "text_batch", + "pcm_s16le", + "pcm_f32le", + "content_batch", + "decision", + "rerank" + ], + "type": "string" + }, + { + "const": "messages_multimodal", + "description": "Messages whose parts include audio.", + "type": "string" + } + ] + }, + "Modality": { + "description": "A modality primitive: one kind of data, the same whether it is a model's\ninput or its output. `json` and `vector` are output-only result kinds.", + "oneOf": [ + { + "enum": [ + "text", + "image", + "audio", + "video" + ], + "type": "string" + }, + { + "const": "json", + "description": "Structured data checked against the capability's schema\n(decision answers, relevance scores).", + "type": "string" + }, + { + "const": "vector", + "description": "Embedding vectors.", + "type": "string" + } + ] }, "OptionBound": { "properties": { @@ -105,22 +143,71 @@ "type": "object" }, "OptionName": { - "enum": [ - "max_tokens", - "temperature", - "top_p", - "dimensions", - "input_count", - "input_characters", - "width", - "height", - "seed", - "max_output_tokens", - "image_bytes", - "image_pixels", - "image_count" - ], - "type": "string" + "oneOf": [ + { + "enum": [ + "max_tokens", + "temperature", + "top_p", + "dimensions", + "input_count", + "input_characters", + "width", + "height", + "seed", + "max_output_tokens", + "image_bytes", + "image_pixels", + "image_count" + ], + "type": "string" + }, + { + "const": "total_image_bytes", + "description": "Decoded bytes of all images in one request.", + "type": "string" + }, + { + "const": "message_count", + "description": "Messages in one `image_messages` input.", + "type": "string" + }, + { + "const": "content_parts", + "description": "Content parts across one request.", + "type": "string" + }, + { + "const": "input_tokens", + "description": "Tokens per input, including special tokens, from the served model's\nown positional limit.", + "type": "string" + }, + { + "const": "top_n", + "description": "Documents returned by a `rerank` operation.", + "type": "string" + }, + { + "const": "audio_count", + "description": "Audio clips in one request.", + "type": "string" + }, + { + "const": "total_audio_bytes", + "description": "Decoded PCM bytes of all audio in one request.", + "type": "string" + }, + { + "const": "audio_seconds", + "description": "Seconds per audio clip.", + "type": "string" + }, + { + "const": "sample_rate", + "description": "Sample rate of an audio clip, in Hz.", + "type": "string" + } + ] }, "OutputFormat": { "enum": [ @@ -128,7 +215,8 @@ "embeddings_float32", "png_base64", "labels", - "decisions" + "decisions", + "relevance_scores" ], "type": "string" }, @@ -142,7 +230,8 @@ "audio_classification", "image_to_text", "multimodal_embedding", - "decision" + "decision", + "rerank" ], "type": "string" } @@ -161,6 +250,13 @@ }, "type": "array" }, + "input_modalities": { + "description": "Content modalities this capability accepts for this served model.", + "items": { + "$ref": "#/$defs/Modality" + }, + "type": "array" + }, "option_bounds": { "items": { "$ref": "#/$defs/OptionBound" @@ -173,6 +269,13 @@ }, "type": "array" }, + "output_modalities": { + "description": "Modalities this capability produces.", + "items": { + "$ref": "#/$defs/Modality" + }, + "type": "array" + }, "semantic_task": { "$ref": "#/$defs/SemanticTask" }, @@ -185,6 +288,8 @@ "semantic_task", "input_formats", "output_formats", + "input_modalities", + "output_modalities", "streaming", "availability", "option_bounds" diff --git a/tests/fixtures/pumas-image-to-text-v1/schemas/served-models-response.schema.json b/tests/fixtures/pumas-image-to-text-v1/schemas/served-models-response.schema.json new file mode 100644 index 00000000..066a6546 --- /dev/null +++ b/tests/fixtures/pumas-image-to-text-v1/schemas/served-models-response.schema.json @@ -0,0 +1,417 @@ +{ + "$defs": { + "Availability": { + "oneOf": [ + { + "properties": { + "state": { + "const": "available", + "type": "string" + } + }, + "required": [ + "state" + ], + "type": "object" + }, + { + "properties": { + "reason": { + "$ref": "#/$defs/AvailabilityReason" + }, + "state": { + "const": "unavailable", + "type": "string" + } + }, + "required": [ + "state", + "reason" + ], + "type": "object" + } + ] + }, + "AvailabilityReason": { + "enum": [ + "unsupported_adapter", + "unknown_model_task", + "model_task_mismatch", + "runtime_unavailable" + ], + "type": "string" + }, + "Capability": { + "oneOf": [ + { + "enum": [ + "chat_generation", + "text_generation", + "text_embedding", + "image_generation", + "image_to_text", + "audio_transcription", + "audio_classification" + ], + "type": "string" + }, + { + "const": "multimodal_embedding", + "description": "One embedding per image or per mixed text/image item, in the same\nvector space as the model's text embeddings.", + "type": "string" + }, + { + "const": "decision", + "description": "Typed questions about a state answered with probabilities by a native\ndecision model (llama.cpp `/v1/systemone`, e.g. Kev, OpenJev).", + "type": "string" + }, + { + "const": "rerank", + "description": "Relevance of each document to a query, scored by a reranker\n(llama.cpp `/v1/rerank`).", + "type": "string" + } + ] + }, + "CapabilityDescriptor": { + "properties": { + "availability": { + "$ref": "#/$defs/Availability" + }, + "capability": { + "$ref": "#/$defs/Capability" + }, + "input_formats": { + "items": { + "$ref": "#/$defs/InputFormat" + }, + "type": "array" + }, + "input_modalities": { + "description": "Content modalities this capability accepts for this served model.", + "items": { + "$ref": "#/$defs/Modality" + }, + "type": "array" + }, + "option_bounds": { + "items": { + "$ref": "#/$defs/OptionBound" + }, + "type": "array" + }, + "output_formats": { + "items": { + "$ref": "#/$defs/OutputFormat" + }, + "type": "array" + }, + "output_modalities": { + "description": "Modalities this capability produces.", + "items": { + "$ref": "#/$defs/Modality" + }, + "type": "array" + }, + "semantic_task": { + "$ref": "#/$defs/SemanticTask" + }, + "streaming": { + "type": "boolean" + } + }, + "required": [ + "capability", + "semantic_task", + "input_formats", + "output_formats", + "input_modalities", + "output_modalities", + "streaming", + "availability", + "option_bounds" + ], + "type": "object" + }, + "InputFormat": { + "oneOf": [ + { + "enum": [ + "messages_text", + "png_base64", + "jpeg_base64", + "messages_image", + "text", + "text_batch", + "pcm_s16le", + "pcm_f32le", + "content_batch", + "decision", + "rerank" + ], + "type": "string" + }, + { + "const": "messages_multimodal", + "description": "Messages whose parts include audio.", + "type": "string" + } + ] + }, + "Modality": { + "description": "A modality primitive: one kind of data, the same whether it is a model's\ninput or its output. `json` and `vector` are output-only result kinds.", + "oneOf": [ + { + "enum": [ + "text", + "image", + "audio", + "video" + ], + "type": "string" + }, + { + "const": "json", + "description": "Structured data checked against the capability's schema\n(decision answers, relevance scores).", + "type": "string" + }, + { + "const": "vector", + "description": "Embedding vectors.", + "type": "string" + } + ] + }, + "ModalitySet": { + "description": "What a served model accepts and produces, as its runtime declares it.", + "properties": { + "input": { + "items": { + "$ref": "#/$defs/Modality" + }, + "type": "array" + }, + "output": { + "items": { + "$ref": "#/$defs/Modality" + }, + "type": "array" + } + }, + "required": [ + "input", + "output" + ], + "type": "object" + }, + "OptionBound": { + "properties": { + "maximum": { + "format": "double", + "type": "number" + }, + "minimum": { + "format": "double", + "type": "number" + }, + "option": { + "$ref": "#/$defs/OptionName" + } + }, + "required": [ + "option", + "minimum", + "maximum" + ], + "type": "object" + }, + "OptionName": { + "oneOf": [ + { + "enum": [ + "max_tokens", + "temperature", + "top_p", + "dimensions", + "input_count", + "input_characters", + "width", + "height", + "seed", + "max_output_tokens", + "image_bytes", + "image_pixels", + "image_count" + ], + "type": "string" + }, + { + "const": "total_image_bytes", + "description": "Decoded bytes of all images in one request.", + "type": "string" + }, + { + "const": "message_count", + "description": "Messages in one `image_messages` input.", + "type": "string" + }, + { + "const": "content_parts", + "description": "Content parts across one request.", + "type": "string" + }, + { + "const": "input_tokens", + "description": "Tokens per input, including special tokens, from the served model's\nown positional limit.", + "type": "string" + }, + { + "const": "top_n", + "description": "Documents returned by a `rerank` operation.", + "type": "string" + }, + { + "const": "audio_count", + "description": "Audio clips in one request.", + "type": "string" + }, + { + "const": "total_audio_bytes", + "description": "Decoded PCM bytes of all audio in one request.", + "type": "string" + }, + { + "const": "audio_seconds", + "description": "Seconds per audio clip.", + "type": "string" + }, + { + "const": "sample_rate", + "description": "Sample rate of an audio clip, in Hz.", + "type": "string" + } + ] + }, + "OutputFormat": { + "enum": [ + "text", + "embeddings_float32", + "png_base64", + "labels", + "decisions", + "relevance_scores" + ], + "type": "string" + }, + "SemanticTask": { + "enum": [ + "chat_generation", + "text_generation", + "text_embedding", + "text_to_image", + "speech_to_text", + "audio_classification", + "image_to_text", + "multimodal_embedding", + "decision", + "rerank" + ], + "type": "string" + }, + "ServedModelEntry": { + "properties": { + "capabilities": { + "items": { + "$ref": "#/$defs/CapabilityDescriptor" + }, + "type": "array" + }, + "context_tokens": { + "description": "Context window configured for this serving, when the runtime reports it.", + "format": "uint32", + "minimum": 0, + "type": [ + "integer", + "null" + ] + }, + "load_state": { + "type": "string" + }, + "modalities": { + "$ref": "#/$defs/ModalitySet" + }, + "model": { + "description": "The served alias callers put in `model`.", + "type": "string" + }, + "model_id": { + "description": "The library model identifier behind the alias.", + "type": "string" + }, + "profile": { + "description": "The exact profile callers put in `profile`.", + "type": "string" + }, + "profile_required": { + "type": "boolean" + }, + "provider": { + "type": "string" + } + }, + "required": [ + "model", + "profile", + "model_id", + "provider", + "load_state", + "profile_required", + "modalities", + "capabilities" + ], + "type": "object" + } + }, + "$schema": "https://json-schema.org/draft/2020-12/schema", + "description": "`GET /v1/served-models`: every served (model, profile) pair exactly once.", + "properties": { + "max_request_bytes": { + "format": "uint", + "minimum": 0, + "type": "integer" + }, + "max_response_bytes": { + "format": "uint", + "minimum": 0, + "type": "integer" + }, + "max_stream_event_bytes": { + "format": "uint", + "minimum": 0, + "type": "integer" + }, + "models": { + "items": { + "$ref": "#/$defs/ServedModelEntry" + }, + "type": "array" + }, + "supported_contract_versions": { + "items": { + "format": "uint32", + "minimum": 0, + "type": "integer" + }, + "type": "array" + } + }, + "required": [ + "supported_contract_versions", + "max_request_bytes", + "max_response_bytes", + "max_stream_event_bytes", + "models" + ], + "title": "ServedModelsResponse", + "type": "object" +} diff --git a/tests/fixtures/pumas-image-to-text-v1/served-models.json b/tests/fixtures/pumas-image-to-text-v1/served-models.json new file mode 100644 index 00000000..421441ca --- /dev/null +++ b/tests/fixtures/pumas-image-to-text-v1/served-models.json @@ -0,0 +1,1199 @@ +{ + "supported_contract_versions": [ + 1 + ], + "max_request_bytes": 33554432, + "max_response_bytes": 33554432, + "max_stream_event_bytes": 262144, + "models": [ + { + "model": "controlled-vision", + "profile": "vision-cpu", + "model_id": "vlm/controlled/controlled-vision", + "provider": "llama_cpp", + "load_state": "loaded", + "context_tokens": 8192, + "profile_required": true, + "modalities": { + "input": [ + "text", + "image" + ], + "output": [ + "text" + ] + }, + "capabilities": [ + { + "capability": "chat_generation", + "semantic_task": "chat_generation", + "input_formats": [ + "messages_text", + "messages_multimodal" + ], + "output_formats": [ + "text" + ], + "input_modalities": [ + "text", + "image" + ], + "output_modalities": [ + "text" + ], + "streaming": true, + "availability": { + "state": "available" + }, + "option_bounds": [ + { + "option": "max_tokens", + "minimum": 1.0, + "maximum": 8192.0 + }, + { + "option": "temperature", + "minimum": 0.0, + "maximum": 2.0 + }, + { + "option": "top_p", + "minimum": 0.0, + "maximum": 1.0 + }, + { + "option": "image_bytes", + "minimum": 1.0, + "maximum": 8388608.0 + }, + { + "option": "total_image_bytes", + "minimum": 1.0, + "maximum": 16777216.0 + }, + { + "option": "image_pixels", + "minimum": 1.0, + "maximum": 4194304.0 + }, + { + "option": "image_count", + "minimum": 0.0, + "maximum": 4.0 + }, + { + "option": "width", + "minimum": 1.0, + "maximum": 4096.0 + }, + { + "option": "height", + "minimum": 1.0, + "maximum": 4096.0 + }, + { + "option": "message_count", + "minimum": 1.0, + "maximum": 128.0 + }, + { + "option": "content_parts", + "minimum": 1.0, + "maximum": 128.0 + } + ] + }, + { + "capability": "text_generation", + "semantic_task": "text_generation", + "input_formats": [ + "text" + ], + "output_formats": [ + "text" + ], + "input_modalities": [ + "text" + ], + "output_modalities": [ + "text" + ], + "streaming": true, + "availability": { + "state": "available" + }, + "option_bounds": [ + { + "option": "max_tokens", + "minimum": 1.0, + "maximum": 8192.0 + }, + { + "option": "temperature", + "minimum": 0.0, + "maximum": 2.0 + }, + { + "option": "top_p", + "minimum": 0.0, + "maximum": 1.0 + } + ] + }, + { + "capability": "text_embedding", + "semantic_task": "text_embedding", + "input_formats": [ + "text", + "text_batch" + ], + "output_formats": [ + "embeddings_float32" + ], + "input_modalities": [ + "text" + ], + "output_modalities": [ + "vector" + ], + "streaming": false, + "availability": { + "state": "unavailable", + "reason": "model_task_mismatch" + }, + "option_bounds": [ + { + "option": "dimensions", + "minimum": 1.0, + "maximum": 4294967295.0 + } + ] + }, + { + "capability": "image_generation", + "semantic_task": "text_to_image", + "input_formats": [ + "text" + ], + "output_formats": [ + "png_base64" + ], + "input_modalities": [ + "text" + ], + "output_modalities": [ + "image" + ], + "streaming": false, + "availability": { + "state": "unavailable", + "reason": "unsupported_adapter" + }, + "option_bounds": [ + { + "option": "width", + "minimum": 1.0, + "maximum": 4294967295.0 + }, + { + "option": "height", + "minimum": 1.0, + "maximum": 4294967295.0 + }, + { + "option": "seed", + "minimum": 0.0, + "maximum": 4294967295.0 + }, + { + "option": "input_characters", + "minimum": 1.0, + "maximum": 4000.0 + } + ] + }, + { + "capability": "audio_transcription", + "semantic_task": "speech_to_text", + "input_formats": [ + "pcm_s16le", + "pcm_f32le" + ], + "output_formats": [ + "text" + ], + "input_modalities": [], + "output_modalities": [ + "text" + ], + "streaming": false, + "availability": { + "state": "unavailable", + "reason": "unsupported_adapter" + }, + "option_bounds": [ + { + "option": "max_output_tokens", + "minimum": 512.0, + "maximum": 512.0 + } + ] + }, + { + "capability": "audio_classification", + "semantic_task": "audio_classification", + "input_formats": [ + "pcm_s16le", + "pcm_f32le" + ], + "output_formats": [ + "labels" + ], + "input_modalities": [], + "output_modalities": [ + "json" + ], + "streaming": false, + "availability": { + "state": "unavailable", + "reason": "unsupported_adapter" + }, + "option_bounds": [] + }, + { + "capability": "image_to_text", + "semantic_task": "image_to_text", + "input_formats": [ + "png_base64", + "jpeg_base64", + "messages_image" + ], + "output_formats": [ + "text" + ], + "input_modalities": [ + "text", + "image" + ], + "output_modalities": [ + "text" + ], + "streaming": false, + "availability": { + "state": "available" + }, + "option_bounds": [ + { + "option": "max_tokens", + "minimum": 1.0, + "maximum": 8192.0 + }, + { + "option": "temperature", + "minimum": 0.0, + "maximum": 2.0 + }, + { + "option": "top_p", + "minimum": 0.0, + "maximum": 1.0 + }, + { + "option": "image_bytes", + "minimum": 1.0, + "maximum": 8388608.0 + }, + { + "option": "total_image_bytes", + "minimum": 1.0, + "maximum": 16777216.0 + }, + { + "option": "image_pixels", + "minimum": 1.0, + "maximum": 4194304.0 + }, + { + "option": "image_count", + "minimum": 1.0, + "maximum": 4.0 + }, + { + "option": "width", + "minimum": 1.0, + "maximum": 4096.0 + }, + { + "option": "height", + "minimum": 1.0, + "maximum": 4096.0 + }, + { + "option": "message_count", + "minimum": 1.0, + "maximum": 128.0 + }, + { + "option": "content_parts", + "minimum": 1.0, + "maximum": 128.0 + } + ] + }, + { + "capability": "multimodal_embedding", + "semantic_task": "multimodal_embedding", + "input_formats": [ + "png_base64", + "jpeg_base64", + "content_batch" + ], + "output_formats": [ + "embeddings_float32" + ], + "input_modalities": [ + "text", + "image" + ], + "output_modalities": [ + "vector" + ], + "streaming": false, + "availability": { + "state": "unavailable", + "reason": "model_task_mismatch" + }, + "option_bounds": [ + { + "option": "dimensions", + "minimum": 1.0, + "maximum": 4294967295.0 + }, + { + "option": "image_bytes", + "minimum": 1.0, + "maximum": 8388608.0 + }, + { + "option": "total_image_bytes", + "minimum": 1.0, + "maximum": 16777216.0 + }, + { + "option": "image_pixels", + "minimum": 1.0, + "maximum": 4194304.0 + }, + { + "option": "image_count", + "minimum": 1.0, + "maximum": 4.0 + }, + { + "option": "width", + "minimum": 1.0, + "maximum": 4096.0 + }, + { + "option": "height", + "minimum": 1.0, + "maximum": 4096.0 + } + ] + }, + { + "capability": "decision", + "semantic_task": "decision", + "input_formats": [ + "decision" + ], + "output_formats": [ + "decisions" + ], + "input_modalities": [ + "text", + "image" + ], + "output_modalities": [ + "json" + ], + "streaming": false, + "availability": { + "state": "unavailable", + "reason": "model_task_mismatch" + }, + "option_bounds": [ + { + "option": "image_bytes", + "minimum": 1.0, + "maximum": 8388608.0 + }, + { + "option": "total_image_bytes", + "minimum": 1.0, + "maximum": 16777216.0 + }, + { + "option": "image_pixels", + "minimum": 1.0, + "maximum": 4194304.0 + }, + { + "option": "image_count", + "minimum": 0.0, + "maximum": 4.0 + }, + { + "option": "width", + "minimum": 1.0, + "maximum": 4096.0 + }, + { + "option": "height", + "minimum": 1.0, + "maximum": 4096.0 + } + ] + }, + { + "capability": "rerank", + "semantic_task": "rerank", + "input_formats": [ + "rerank" + ], + "output_formats": [ + "relevance_scores" + ], + "input_modalities": [ + "text" + ], + "output_modalities": [ + "json" + ], + "streaming": false, + "availability": { + "state": "unavailable", + "reason": "model_task_mismatch" + }, + "option_bounds": [] + } + ] + }, + { + "model": "controlled-vision", + "profile": "vision-gpu", + "model_id": "vlm/controlled/controlled-vision", + "provider": "llama_cpp", + "load_state": "loading", + "context_tokens": 8192, + "profile_required": true, + "modalities": { + "input": [ + "text", + "image" + ], + "output": [ + "text" + ] + }, + "capabilities": [ + { + "capability": "chat_generation", + "semantic_task": "chat_generation", + "input_formats": [ + "messages_text", + "messages_multimodal" + ], + "output_formats": [ + "text" + ], + "input_modalities": [ + "text", + "image" + ], + "output_modalities": [ + "text" + ], + "streaming": false, + "availability": { + "state": "unavailable", + "reason": "runtime_unavailable" + }, + "option_bounds": [ + { + "option": "max_tokens", + "minimum": 1.0, + "maximum": 8192.0 + }, + { + "option": "temperature", + "minimum": 0.0, + "maximum": 2.0 + }, + { + "option": "top_p", + "minimum": 0.0, + "maximum": 1.0 + }, + { + "option": "image_bytes", + "minimum": 1.0, + "maximum": 8388608.0 + }, + { + "option": "total_image_bytes", + "minimum": 1.0, + "maximum": 16777216.0 + }, + { + "option": "image_pixels", + "minimum": 1.0, + "maximum": 4194304.0 + }, + { + "option": "image_count", + "minimum": 0.0, + "maximum": 4.0 + }, + { + "option": "width", + "minimum": 1.0, + "maximum": 4096.0 + }, + { + "option": "height", + "minimum": 1.0, + "maximum": 4096.0 + }, + { + "option": "message_count", + "minimum": 1.0, + "maximum": 128.0 + }, + { + "option": "content_parts", + "minimum": 1.0, + "maximum": 128.0 + } + ] + }, + { + "capability": "text_generation", + "semantic_task": "text_generation", + "input_formats": [ + "text" + ], + "output_formats": [ + "text" + ], + "input_modalities": [ + "text" + ], + "output_modalities": [ + "text" + ], + "streaming": false, + "availability": { + "state": "unavailable", + "reason": "runtime_unavailable" + }, + "option_bounds": [ + { + "option": "max_tokens", + "minimum": 1.0, + "maximum": 8192.0 + }, + { + "option": "temperature", + "minimum": 0.0, + "maximum": 2.0 + }, + { + "option": "top_p", + "minimum": 0.0, + "maximum": 1.0 + } + ] + }, + { + "capability": "text_embedding", + "semantic_task": "text_embedding", + "input_formats": [ + "text", + "text_batch" + ], + "output_formats": [ + "embeddings_float32" + ], + "input_modalities": [ + "text" + ], + "output_modalities": [ + "vector" + ], + "streaming": false, + "availability": { + "state": "unavailable", + "reason": "model_task_mismatch" + }, + "option_bounds": [ + { + "option": "dimensions", + "minimum": 1.0, + "maximum": 4294967295.0 + } + ] + }, + { + "capability": "image_generation", + "semantic_task": "text_to_image", + "input_formats": [ + "text" + ], + "output_formats": [ + "png_base64" + ], + "input_modalities": [ + "text" + ], + "output_modalities": [ + "image" + ], + "streaming": false, + "availability": { + "state": "unavailable", + "reason": "unsupported_adapter" + }, + "option_bounds": [ + { + "option": "width", + "minimum": 1.0, + "maximum": 4294967295.0 + }, + { + "option": "height", + "minimum": 1.0, + "maximum": 4294967295.0 + }, + { + "option": "seed", + "minimum": 0.0, + "maximum": 4294967295.0 + }, + { + "option": "input_characters", + "minimum": 1.0, + "maximum": 4000.0 + } + ] + }, + { + "capability": "audio_transcription", + "semantic_task": "speech_to_text", + "input_formats": [ + "pcm_s16le", + "pcm_f32le" + ], + "output_formats": [ + "text" + ], + "input_modalities": [], + "output_modalities": [ + "text" + ], + "streaming": false, + "availability": { + "state": "unavailable", + "reason": "unsupported_adapter" + }, + "option_bounds": [ + { + "option": "max_output_tokens", + "minimum": 512.0, + "maximum": 512.0 + } + ] + }, + { + "capability": "audio_classification", + "semantic_task": "audio_classification", + "input_formats": [ + "pcm_s16le", + "pcm_f32le" + ], + "output_formats": [ + "labels" + ], + "input_modalities": [], + "output_modalities": [ + "json" + ], + "streaming": false, + "availability": { + "state": "unavailable", + "reason": "unsupported_adapter" + }, + "option_bounds": [] + }, + { + "capability": "image_to_text", + "semantic_task": "image_to_text", + "input_formats": [ + "png_base64", + "jpeg_base64", + "messages_image" + ], + "output_formats": [ + "text" + ], + "input_modalities": [ + "text", + "image" + ], + "output_modalities": [ + "text" + ], + "streaming": false, + "availability": { + "state": "unavailable", + "reason": "runtime_unavailable" + }, + "option_bounds": [ + { + "option": "max_tokens", + "minimum": 1.0, + "maximum": 8192.0 + }, + { + "option": "temperature", + "minimum": 0.0, + "maximum": 2.0 + }, + { + "option": "top_p", + "minimum": 0.0, + "maximum": 1.0 + }, + { + "option": "image_bytes", + "minimum": 1.0, + "maximum": 8388608.0 + }, + { + "option": "total_image_bytes", + "minimum": 1.0, + "maximum": 16777216.0 + }, + { + "option": "image_pixels", + "minimum": 1.0, + "maximum": 4194304.0 + }, + { + "option": "image_count", + "minimum": 1.0, + "maximum": 4.0 + }, + { + "option": "width", + "minimum": 1.0, + "maximum": 4096.0 + }, + { + "option": "height", + "minimum": 1.0, + "maximum": 4096.0 + }, + { + "option": "message_count", + "minimum": 1.0, + "maximum": 128.0 + }, + { + "option": "content_parts", + "minimum": 1.0, + "maximum": 128.0 + } + ] + }, + { + "capability": "multimodal_embedding", + "semantic_task": "multimodal_embedding", + "input_formats": [ + "png_base64", + "jpeg_base64", + "content_batch" + ], + "output_formats": [ + "embeddings_float32" + ], + "input_modalities": [ + "text", + "image" + ], + "output_modalities": [ + "vector" + ], + "streaming": false, + "availability": { + "state": "unavailable", + "reason": "model_task_mismatch" + }, + "option_bounds": [ + { + "option": "dimensions", + "minimum": 1.0, + "maximum": 4294967295.0 + }, + { + "option": "image_bytes", + "minimum": 1.0, + "maximum": 8388608.0 + }, + { + "option": "total_image_bytes", + "minimum": 1.0, + "maximum": 16777216.0 + }, + { + "option": "image_pixels", + "minimum": 1.0, + "maximum": 4194304.0 + }, + { + "option": "image_count", + "minimum": 1.0, + "maximum": 4.0 + }, + { + "option": "width", + "minimum": 1.0, + "maximum": 4096.0 + }, + { + "option": "height", + "minimum": 1.0, + "maximum": 4096.0 + } + ] + }, + { + "capability": "decision", + "semantic_task": "decision", + "input_formats": [ + "decision" + ], + "output_formats": [ + "decisions" + ], + "input_modalities": [ + "text", + "image" + ], + "output_modalities": [ + "json" + ], + "streaming": false, + "availability": { + "state": "unavailable", + "reason": "model_task_mismatch" + }, + "option_bounds": [ + { + "option": "image_bytes", + "minimum": 1.0, + "maximum": 8388608.0 + }, + { + "option": "total_image_bytes", + "minimum": 1.0, + "maximum": 16777216.0 + }, + { + "option": "image_pixels", + "minimum": 1.0, + "maximum": 4194304.0 + }, + { + "option": "image_count", + "minimum": 0.0, + "maximum": 4.0 + }, + { + "option": "width", + "minimum": 1.0, + "maximum": 4096.0 + }, + { + "option": "height", + "minimum": 1.0, + "maximum": 4096.0 + } + ] + }, + { + "capability": "rerank", + "semantic_task": "rerank", + "input_formats": [ + "rerank" + ], + "output_formats": [ + "relevance_scores" + ], + "input_modalities": [ + "text" + ], + "output_modalities": [ + "json" + ], + "streaming": false, + "availability": { + "state": "unavailable", + "reason": "model_task_mismatch" + }, + "option_bounds": [] + } + ] + }, + { + "model": "controlled-image", + "profile": "controlled-image-cpu", + "model_id": "diffusion/controlled/controlled-image", + "provider": "torch", + "load_state": "loaded", + "profile_required": false, + "modalities": { + "input": [ + "text" + ], + "output": [ + "image" + ] + }, + "capabilities": [ + { + "capability": "chat_generation", + "semantic_task": "chat_generation", + "input_formats": [ + "messages_text", + "messages_multimodal" + ], + "output_formats": [ + "text" + ], + "input_modalities": [ + "text" + ], + "output_modalities": [ + "text" + ], + "streaming": false, + "availability": { + "state": "unavailable", + "reason": "unsupported_adapter" + }, + "option_bounds": [ + { + "option": "max_tokens", + "minimum": 1.0, + "maximum": 4294967295.0 + }, + { + "option": "temperature", + "minimum": 0.0, + "maximum": 2.0 + }, + { + "option": "top_p", + "minimum": 0.0, + "maximum": 1.0 + } + ] + }, + { + "capability": "text_generation", + "semantic_task": "text_generation", + "input_formats": [ + "text" + ], + "output_formats": [ + "text" + ], + "input_modalities": [ + "text" + ], + "output_modalities": [ + "text" + ], + "streaming": false, + "availability": { + "state": "unavailable", + "reason": "unsupported_adapter" + }, + "option_bounds": [ + { + "option": "max_tokens", + "minimum": 1.0, + "maximum": 4294967295.0 + }, + { + "option": "temperature", + "minimum": 0.0, + "maximum": 2.0 + }, + { + "option": "top_p", + "minimum": 0.0, + "maximum": 1.0 + } + ] + }, + { + "capability": "text_embedding", + "semantic_task": "text_embedding", + "input_formats": [ + "text", + "text_batch" + ], + "output_formats": [ + "embeddings_float32" + ], + "input_modalities": [ + "text" + ], + "output_modalities": [ + "vector" + ], + "streaming": false, + "availability": { + "state": "unavailable", + "reason": "unsupported_adapter" + }, + "option_bounds": [ + { + "option": "dimensions", + "minimum": 1.0, + "maximum": 8192.0 + }, + { + "option": "input_count", + "minimum": 1.0, + "maximum": 128.0 + }, + { + "option": "input_characters", + "minimum": 0.0, + "maximum": 65536.0 + } + ] + }, + { + "capability": "image_generation", + "semantic_task": "text_to_image", + "input_formats": [ + "text" + ], + "output_formats": [ + "png_base64" + ], + "input_modalities": [ + "text" + ], + "output_modalities": [ + "image" + ], + "streaming": false, + "availability": { + "state": "available" + }, + "option_bounds": [ + { + "option": "width", + "minimum": 1.0, + "maximum": 4294967295.0 + }, + { + "option": "height", + "minimum": 1.0, + "maximum": 4294967295.0 + }, + { + "option": "seed", + "minimum": 0.0, + "maximum": 4294967295.0 + }, + { + "option": "input_characters", + "minimum": 1.0, + "maximum": 4000.0 + } + ] + }, + { + "capability": "audio_transcription", + "semantic_task": "speech_to_text", + "input_formats": [ + "pcm_s16le", + "pcm_f32le" + ], + "output_formats": [ + "text" + ], + "input_modalities": [], + "output_modalities": [ + "text" + ], + "streaming": false, + "availability": { + "state": "unavailable", + "reason": "unsupported_adapter" + }, + "option_bounds": [] + }, + { + "capability": "audio_classification", + "semantic_task": "audio_classification", + "input_formats": [ + "pcm_s16le", + "pcm_f32le" + ], + "output_formats": [ + "labels" + ], + "input_modalities": [], + "output_modalities": [ + "json" + ], + "streaming": false, + "availability": { + "state": "unavailable", + "reason": "unsupported_adapter" + }, + "option_bounds": [] + }, + { + "capability": "rerank", + "semantic_task": "rerank", + "input_formats": [ + "rerank" + ], + "output_formats": [ + "relevance_scores" + ], + "input_modalities": [ + "text" + ], + "output_modalities": [ + "json" + ], + "streaming": false, + "availability": { + "state": "unavailable", + "reason": "model_task_mismatch" + }, + "option_bounds": [] + } + ] + } + ] +} diff --git a/tests/fixtures/pumas-image-to-text-v1/source.json b/tests/fixtures/pumas-image-to-text-v1/source.json index 40d6dc5d..4b746fba 100644 --- a/tests/fixtures/pumas-image-to-text-v1/source.json +++ b/tests/fixtures/pumas-image-to-text-v1/source.json @@ -1,45 +1,68 @@ { "producer_repository": "MrScripty/Pumas-Library", - "producer_branch": "feat/v080-consumer-api", - "producer_commit": "4c79cd8e35db566b70caaa13d8d8f92265f5976e", - "producer_tree": "c646a01d5cc88814bdd2dd7e4565d9d1deda2203", + "producer_tag": "v0.8.0", + "producer_commit": "69e32a2208c5c2d840f4adafec03350669fcb5bc", + "producer_tree": "1658aabb33dca9672f38a20595dd589664538f61", "contract_path": "docs/contracts/model-operations-v1.md", - "contract_url": "https://github.com/MrScripty/Pumas-Library/blob/4c79cd8e35db566b70caaa13d8d8f92265f5976e/docs/contracts/model-operations-v1.md", - "contract_sha256": "ab0f8a2c9b01f89a28d9a03ed3a9d9246eb6d1665ee2690a4fd2bcb8ff0f9d44", - "fixture_kind": "Source-derived controlled consumer fixture; not actual native DTO export or model inference", - "inspected_source_sha256": { - "types.rs": "dc4e11a3de059f268c7bbf0f2008b4d1710f5ca6e8c20d06608e67773579bbd0", - "model_operations.rs": "2ffd1b7e215fc0da59fbb70acfbd6a5beb2aa4370fb15546afc7a16f6b49ef16", - "projection.rs": "7357166a8ef9e73b29602323b6ef3d7cca3364b9a18ac0a4715f467e9080f9d8", - "vision_tests.rs": "ce340d0dfe576196330e85b6a92151e6d7329dd9878a0c39e52f0f8126a0dc5a" - }, - "inspected_source_native_blob_sha": { - "types.rs": "4b5414db04e62af6d1e39a3c39455ed6bc23e546", - "model_operations.rs": "64ed36cf3606f3028a3a2ec641d02790e71e56fc", - "projection.rs": "c1595de051af74c752e2553e6d2f3c5159c1f47e", - "vision_tests.rs": "4de87a94aba30ec82f19e49c4a8e47ef6de49654" - }, - "schema_export_status": "Six actual production Rust DTO schemas were regenerated at schema_export_commit with the export-contract feature. The controlled capability fixture follows that commit's descriptor construction for a llama.cpp vision serving with an 8192-token context. Packaged/native qualification remains separate.", - "actual_dto_schema_sha256": { - "capabilities-response.schema.json": "e1949bef5e7480f2808f2f1ec66e77adf438e44c6d000a04430bbf15d117a04e", - "capability-descriptor.schema.json": "c586a54fd8c0524dfcbae00dd298d5ee06bb70675c78e871b8a82a77c7ba5316", - "error-response.schema.json": "6b681ab7c7f224e2a35dddaeeb113e9ee2069b058904ced3390c17d1fe36c218", - "modality-request.schema.json": "feb94daa68db1003eb633161ef72431611c1cd5eb6c3096f20c2b69d4a6b9162", + "contract_sha256": "39978648ff03b127b0e075ec9b758654ddc8ce19f865dde0839159de2dea2cc3", + "fixture_kind": "Release-derived controlled consumer fixture; not native DTO export output, a running Pumas or model inference", + "schema_sha256": { "operation-request.schema.json": "a09fac92af50255d960d1d27ce570c7f89dd377bd7733cead30c4f7fea70a5c5", - "operation-response.schema.json": "17f366d747de6a0047d40a5e549af5abe7045a3a8f64d987c398b7786488d476" + "modality-request.schema.json": "feb94daa68db1003eb633161ef72431611c1cd5eb6c3096f20c2b69d4a6b9162", + "capabilities-response.schema.json": "bbe630b92ec0d2e58eebe4ba6783d2c8db78f193b45b869aedaba7f1e8abe478", + "capability-descriptor.schema.json": "070f85949bff2451a0ca3f3a489548afff82f7d1e3a25ddc6036370aab6f3365", + "operation-response.schema.json": "17f366d747de6a0047d40a5e549af5abe7045a3a8f64d987c398b7786488d476", + "error-response.schema.json": "6b681ab7c7f224e2a35dddaeeb113e9ee2069b058904ced3390c17d1fe36c218", + "served-models-response.schema.json": "9e0cbb5b7e7378b40b375cf260775bdf77648a3270446fe00ccf33a2b80b26e8" + }, + "schema_origin": { + "capability-descriptor.schema.json": "verbatim copy of scripts/consumers/contracts/capability-descriptor.schema.json at v0.8.0", + "capabilities-response.schema.json": "the 4c79cd8 export with its descriptor $defs replaced by the v0.8.0 descriptor schema and `modalities` (ModalitySet) added from types.rs at v0.8.0", + "served-models-response.schema.json": "authored from ServedModelsResponse/ServedModelEntry in types.rs at v0.8.0, sharing the descriptor $defs above", + "operation-request.schema.json": "the 4c79cd8 export (see previous_producer); the 0.8.0 changes to these types are additive (audio parts, rerank, relevance_scores) and were not exported, since Pumas is not built here", + "modality-request.schema.json": "the 4c79cd8 export (see previous_producer); the 0.8.0 changes to these types are additive (audio parts, rerank, relevance_scores) and were not exported, since Pumas is not built here", + "operation-response.schema.json": "the 4c79cd8 export (see previous_producer); the 0.8.0 changes to these types are additive (audio parts, rerank, relevance_scores) and were not exported, since Pumas is not built here", + "error-response.schema.json": "the 4c79cd8 export (see previous_producer); the 0.8.0 changes to these types are additive (audio parts, rerank, relevance_scores) and were not exported, since Pumas is not built here" }, - "schema_export_command": "PUMAS_IMAGE_CONTRACT_EXPORT_DIR=... cargo test --locked -p pumas-rpc --features export-contract image_to_text_actual_dto_schema_export (from rust/)", - "schema_export_commit": "4c79cd8e35db566b70caaa13d8d8f92265f5976e", + "capability_fixtures": "controlled-capabilities.json and served-models.json follow the v0.8.0 descriptor construction (model_operations.rs: protocol_modalities, chat_bounds, parts::image_bounds) for a llama.cpp vision serving with an 8192-token context, and a Torch image serving", "previous_producer": { - "producer_pr": 68, - "producer_commit": "36c2aab2c885b8416fd4e39cf8c37c510596d6e4", + "producer_branch": "feat/v080-consumer-api", + "producer_commit": "4c79cd8e35db566b70caaa13d8d8f92265f5976e", + "producer_tree": "c646a01d5cc88814bdd2dd7e4565d9d1deda2203", + "contract_sha256": "ab0f8a2c9b01f89a28d9a03ed3a9d9246eb6d1665ee2690a4fd2bcb8ff0f9d44", + "inspected_source_sha256": { + "types.rs": "dc4e11a3de059f268c7bbf0f2008b4d1710f5ca6e8c20d06608e67773579bbd0", + "model_operations.rs": "2ffd1b7e215fc0da59fbb70acfbd6a5beb2aa4370fb15546afc7a16f6b49ef16", + "projection.rs": "7357166a8ef9e73b29602323b6ef3d7cca3364b9a18ac0a4715f467e9080f9d8", + "vision_tests.rs": "ce340d0dfe576196330e85b6a92151e6d7329dd9878a0c39e52f0f8126a0dc5a" + }, + "inspected_source_native_blob_sha": { + "types.rs": "4b5414db04e62af6d1e39a3c39455ed6bc23e546", + "model_operations.rs": "64ed36cf3606f3028a3a2ec641d02790e71e56fc", + "projection.rs": "c1595de051af74c752e2553e6d2f3c5159c1f47e", + "vision_tests.rs": "4de87a94aba30ec82f19e49c4a8e47ef6de49654" + }, "actual_dto_schema_sha256": { - "capabilities-response.schema.json": "b55b150f6958239e71d71f1b28fd36450907ddccf78544d52b64543ad4f2493d", - "capability-descriptor.schema.json": "eb25783123d38de5ff6aedf4cfa69de8f4f5f5c60799768b1b90da258b85f922", - "error-response.schema.json": "b024363b19d55a004d9577ad04d7e2ec9209d3d1193b7c53c46a7d6ed401e3be", - "modality-request.schema.json": "24b5f0a73a1252d31a3b22687a84f07b16a9d3ea700809a42e615e7f4e668704", - "operation-request.schema.json": "08f46f0e79c6cb288c413b008abbdfbedb1898d02fb98d396ef73faf8634c642", - "operation-response.schema.json": "20bf98dfd7292b1e3a99bf34ec524858351ba6f9d226f17257362e9ddf0500f8" + "capabilities-response.schema.json": "e1949bef5e7480f2808f2f1ec66e77adf438e44c6d000a04430bbf15d117a04e", + "capability-descriptor.schema.json": "c586a54fd8c0524dfcbae00dd298d5ee06bb70675c78e871b8a82a77c7ba5316", + "error-response.schema.json": "6b681ab7c7f224e2a35dddaeeb113e9ee2069b058904ced3390c17d1fe36c218", + "modality-request.schema.json": "feb94daa68db1003eb633161ef72431611c1cd5eb6c3096f20c2b69d4a6b9162", + "operation-request.schema.json": "a09fac92af50255d960d1d27ce570c7f89dd377bd7733cead30c4f7fea70a5c5", + "operation-response.schema.json": "17f366d747de6a0047d40a5e549af5abe7045a3a8f64d987c398b7786488d476" + }, + "schema_export_command": "PUMAS_IMAGE_CONTRACT_EXPORT_DIR=... cargo test --locked -p pumas-rpc --features export-contract image_to_text_actual_dto_schema_export (from rust/)", + "schema_export_commit": "4c79cd8e35db566b70caaa13d8d8f92265f5976e", + "previous_producer": { + "producer_pr": 68, + "producer_commit": "36c2aab2c885b8416fd4e39cf8c37c510596d6e4", + "actual_dto_schema_sha256": { + "capabilities-response.schema.json": "b55b150f6958239e71d71f1b28fd36450907ddccf78544d52b64543ad4f2493d", + "capability-descriptor.schema.json": "eb25783123d38de5ff6aedf4cfa69de8f4f5f5c60799768b1b90da258b85f922", + "error-response.schema.json": "b024363b19d55a004d9577ad04d7e2ec9209d3d1193b7c53c46a7d6ed401e3be", + "modality-request.schema.json": "24b5f0a73a1252d31a3b22687a84f07b16a9d3ea700809a42e615e7f4e668704", + "operation-request.schema.json": "08f46f0e79c6cb288c413b008abbdfbedb1898d02fb98d396ef73faf8634c642", + "operation-response.schema.json": "20bf98dfd7292b1e3a99bf34ec524858351ba6f9d226f17257362e9ddf0500f8" + } } } } diff --git a/tests/fixtures/pumas-typed-v1/controlled-image-capabilities.json b/tests/fixtures/pumas-typed-v1/controlled-image-capabilities.json index 55290a88..f1ce50a0 100644 --- a/tests/fixtures/pumas-typed-v1/controlled-image-capabilities.json +++ b/tests/fixtures/pumas-typed-v1/controlled-image-capabilities.json @@ -1 +1 @@ -{"supported_contract_versions":[1],"model":"controlled-image","profile":"controlled-image-cpu","max_request_bytes":33554432,"max_response_bytes":33554432,"max_stream_event_bytes":262144,"capabilities":[{"capability":"chat_generation","semantic_task":"chat_generation","input_formats":["messages_text"],"output_formats":["text"],"streaming":false,"availability":{"state":"unavailable","reason":"unsupported_adapter"},"option_bounds":[{"option":"max_tokens","minimum":1.0,"maximum":4294967295.0},{"option":"temperature","minimum":0.0,"maximum":2.0},{"option":"top_p","minimum":0.0,"maximum":1.0}]},{"capability":"text_generation","semantic_task":"text_generation","input_formats":["text"],"output_formats":["text"],"streaming":false,"availability":{"state":"unavailable","reason":"unsupported_adapter"},"option_bounds":[{"option":"max_tokens","minimum":1.0,"maximum":4294967295.0},{"option":"temperature","minimum":0.0,"maximum":2.0},{"option":"top_p","minimum":0.0,"maximum":1.0}]},{"capability":"text_embedding","semantic_task":"text_embedding","input_formats":["text","text_batch"],"output_formats":["embeddings_float32"],"streaming":false,"availability":{"state":"unavailable","reason":"unsupported_adapter"},"option_bounds":[{"option":"dimensions","minimum":1.0,"maximum":8192.0},{"option":"input_count","minimum":1.0,"maximum":128.0},{"option":"input_characters","minimum":0.0,"maximum":65536.0}]},{"capability":"image_generation","semantic_task":"text_to_image","input_formats":["text"],"output_formats":["png_base64"],"streaming":false,"availability":{"state":"available"},"option_bounds":[{"option":"width","minimum":1.0,"maximum":4294967295.0},{"option":"height","minimum":1.0,"maximum":4294967295.0},{"option":"seed","minimum":0.0,"maximum":4294967295.0},{"option":"input_characters","minimum":1.0,"maximum":4000.0}]},{"capability":"audio_transcription","semantic_task":"speech_to_text","input_formats":["pcm_s16le","pcm_f32le"],"output_formats":["text"],"streaming":false,"availability":{"state":"unavailable","reason":"unqualified_audio_runtime"},"option_bounds":[]},{"capability":"audio_classification","semantic_task":"audio_classification","input_formats":["pcm_s16le","pcm_f32le"],"output_formats":["labels"],"streaming":false,"availability":{"state":"unavailable","reason":"unqualified_audio_runtime"},"option_bounds":[]}]} \ No newline at end of file +{"supported_contract_versions":[1],"model":"controlled-image","profile":"controlled-image-cpu","max_request_bytes":33554432,"max_response_bytes":33554432,"max_stream_event_bytes":262144,"modalities":{"input":["text"],"output":["image"]},"capabilities":[{"capability":"chat_generation","semantic_task":"chat_generation","input_formats":["messages_text","messages_multimodal"],"output_formats":["text"],"input_modalities":["text"],"output_modalities":["text"],"streaming":false,"availability":{"state":"unavailable","reason":"unsupported_adapter"},"option_bounds":[{"option":"max_tokens","minimum":1.0,"maximum":4294967295.0},{"option":"temperature","minimum":0.0,"maximum":2.0},{"option":"top_p","minimum":0.0,"maximum":1.0}]},{"capability":"text_generation","semantic_task":"text_generation","input_formats":["text"],"output_formats":["text"],"input_modalities":["text"],"output_modalities":["text"],"streaming":false,"availability":{"state":"unavailable","reason":"unsupported_adapter"},"option_bounds":[{"option":"max_tokens","minimum":1.0,"maximum":4294967295.0},{"option":"temperature","minimum":0.0,"maximum":2.0},{"option":"top_p","minimum":0.0,"maximum":1.0}]},{"capability":"text_embedding","semantic_task":"text_embedding","input_formats":["text","text_batch"],"output_formats":["embeddings_float32"],"input_modalities":["text"],"output_modalities":["vector"],"streaming":false,"availability":{"state":"unavailable","reason":"unsupported_adapter"},"option_bounds":[{"option":"dimensions","minimum":1.0,"maximum":8192.0},{"option":"input_count","minimum":1.0,"maximum":128.0},{"option":"input_characters","minimum":0.0,"maximum":65536.0}]},{"capability":"image_generation","semantic_task":"text_to_image","input_formats":["text"],"output_formats":["png_base64"],"input_modalities":["text"],"output_modalities":["image"],"streaming":false,"availability":{"state":"available"},"option_bounds":[{"option":"width","minimum":1.0,"maximum":4294967295.0},{"option":"height","minimum":1.0,"maximum":4294967295.0},{"option":"seed","minimum":0.0,"maximum":4294967295.0},{"option":"input_characters","minimum":1.0,"maximum":4000.0}]},{"capability":"audio_transcription","semantic_task":"speech_to_text","input_formats":["pcm_s16le","pcm_f32le"],"output_formats":["text"],"input_modalities":[],"output_modalities":["text"],"streaming":false,"availability":{"state":"unavailable","reason":"unsupported_adapter"},"option_bounds":[]},{"capability":"audio_classification","semantic_task":"audio_classification","input_formats":["pcm_s16le","pcm_f32le"],"output_formats":["labels"],"input_modalities":[],"output_modalities":["json"],"streaming":false,"availability":{"state":"unavailable","reason":"unsupported_adapter"},"option_bounds":[]},{"capability":"rerank","semantic_task":"rerank","input_formats":["rerank"],"output_formats":["relevance_scores"],"input_modalities":["text"],"output_modalities":["json"],"streaming":false,"availability":{"state":"unavailable","reason":"model_task_mismatch"},"option_bounds":[]}]} \ No newline at end of file diff --git a/tests/fixtures/pumas-typed-v1/controlled-text-capabilities.json b/tests/fixtures/pumas-typed-v1/controlled-text-capabilities.json index b0ecdc2a..c2d370e1 100644 --- a/tests/fixtures/pumas-typed-v1/controlled-text-capabilities.json +++ b/tests/fixtures/pumas-typed-v1/controlled-text-capabilities.json @@ -1 +1 @@ -{"supported_contract_versions":[1],"model":"controlled-text","profile":"controlled-text-cpu","max_request_bytes":33554432,"max_response_bytes":33554432,"max_stream_event_bytes":262144,"capabilities":[{"capability":"chat_generation","semantic_task":"chat_generation","input_formats":["messages_text"],"output_formats":["text"],"streaming":true,"availability":{"state":"available"},"option_bounds":[{"option":"max_tokens","minimum":1.0,"maximum":4294967295.0},{"option":"temperature","minimum":0.0,"maximum":2.0},{"option":"top_p","minimum":0.0,"maximum":1.0}]},{"capability":"text_generation","semantic_task":"text_generation","input_formats":["text"],"output_formats":["text"],"streaming":true,"availability":{"state":"available"},"option_bounds":[{"option":"max_tokens","minimum":1.0,"maximum":4294967295.0},{"option":"temperature","minimum":0.0,"maximum":2.0},{"option":"top_p","minimum":0.0,"maximum":1.0}]},{"capability":"text_embedding","semantic_task":"text_embedding","input_formats":["text","text_batch"],"output_formats":["embeddings_float32"],"streaming":false,"availability":{"state":"unavailable","reason":"model_task_mismatch"},"option_bounds":[{"option":"dimensions","minimum":1.0,"maximum":8192.0},{"option":"input_count","minimum":1.0,"maximum":128.0},{"option":"input_characters","minimum":0.0,"maximum":65536.0}]},{"capability":"image_generation","semantic_task":"text_to_image","input_formats":["text"],"output_formats":["png_base64"],"streaming":false,"availability":{"state":"unavailable","reason":"unsupported_adapter"},"option_bounds":[{"option":"width","minimum":1.0,"maximum":4294967295.0},{"option":"height","minimum":1.0,"maximum":4294967295.0},{"option":"seed","minimum":0.0,"maximum":4294967295.0},{"option":"input_characters","minimum":1.0,"maximum":4000.0}]},{"capability":"audio_transcription","semantic_task":"speech_to_text","input_formats":["pcm_s16le","pcm_f32le"],"output_formats":["text"],"streaming":false,"availability":{"state":"unavailable","reason":"unqualified_audio_runtime"},"option_bounds":[]},{"capability":"audio_classification","semantic_task":"audio_classification","input_formats":["pcm_s16le","pcm_f32le"],"output_formats":["labels"],"streaming":false,"availability":{"state":"unavailable","reason":"unqualified_audio_runtime"},"option_bounds":[]}]} \ No newline at end of file +{"supported_contract_versions":[1],"model":"controlled-text","profile":"controlled-text-cpu","max_request_bytes":33554432,"max_response_bytes":33554432,"max_stream_event_bytes":262144,"modalities":{"input":["text"],"output":["text"]},"capabilities":[{"capability":"chat_generation","semantic_task":"chat_generation","input_formats":["messages_text","messages_multimodal"],"output_formats":["text"],"input_modalities":["text"],"output_modalities":["text"],"streaming":true,"availability":{"state":"available"},"option_bounds":[{"option":"max_tokens","minimum":1.0,"maximum":4294967295.0},{"option":"temperature","minimum":0.0,"maximum":2.0},{"option":"top_p","minimum":0.0,"maximum":1.0}]},{"capability":"text_generation","semantic_task":"text_generation","input_formats":["text"],"output_formats":["text"],"input_modalities":["text"],"output_modalities":["text"],"streaming":true,"availability":{"state":"available"},"option_bounds":[{"option":"max_tokens","minimum":1.0,"maximum":4294967295.0},{"option":"temperature","minimum":0.0,"maximum":2.0},{"option":"top_p","minimum":0.0,"maximum":1.0}]},{"capability":"text_embedding","semantic_task":"text_embedding","input_formats":["text","text_batch"],"output_formats":["embeddings_float32"],"input_modalities":["text"],"output_modalities":["vector"],"streaming":false,"availability":{"state":"unavailable","reason":"model_task_mismatch"},"option_bounds":[{"option":"dimensions","minimum":1.0,"maximum":8192.0},{"option":"input_count","minimum":1.0,"maximum":128.0},{"option":"input_characters","minimum":0.0,"maximum":65536.0}]},{"capability":"image_generation","semantic_task":"text_to_image","input_formats":["text"],"output_formats":["png_base64"],"input_modalities":["text"],"output_modalities":["image"],"streaming":false,"availability":{"state":"unavailable","reason":"unsupported_adapter"},"option_bounds":[{"option":"width","minimum":1.0,"maximum":4294967295.0},{"option":"height","minimum":1.0,"maximum":4294967295.0},{"option":"seed","minimum":0.0,"maximum":4294967295.0},{"option":"input_characters","minimum":1.0,"maximum":4000.0}]},{"capability":"audio_transcription","semantic_task":"speech_to_text","input_formats":["pcm_s16le","pcm_f32le"],"output_formats":["text"],"input_modalities":[],"output_modalities":["text"],"streaming":false,"availability":{"state":"unavailable","reason":"unsupported_adapter"},"option_bounds":[]},{"capability":"audio_classification","semantic_task":"audio_classification","input_formats":["pcm_s16le","pcm_f32le"],"output_formats":["labels"],"input_modalities":[],"output_modalities":["json"],"streaming":false,"availability":{"state":"unavailable","reason":"unsupported_adapter"},"option_bounds":[]},{"capability":"rerank","semantic_task":"rerank","input_formats":["rerank"],"output_formats":["relevance_scores"],"input_modalities":["text"],"output_modalities":["json"],"streaming":false,"availability":{"state":"unavailable","reason":"model_task_mismatch"},"option_bounds":[]}]} \ No newline at end of file diff --git a/tests/fixtures/pumas-typed-v1/source.json b/tests/fixtures/pumas-typed-v1/source.json index e8c525fe..76275c8a 100644 --- a/tests/fixtures/pumas-typed-v1/source.json +++ b/tests/fixtures/pumas-typed-v1/source.json @@ -6,7 +6,8 @@ "streaming_commit": "f3b3c770ca531f013c8e1f8b1f958b9dc0babbfb", "fixture_origin": "Actual non-test pinned gateway with authored controlled text backend and owned managed image worker. No model inference.", "capabilities_sha256": { - "controlled-image-capabilities.json": "dc884c0a2ef44cdcb36a5cfb6b4658630ee625f9eeed4864aba9aa296844982b", - "controlled-text-capabilities.json": "f67f101ea23679cdc0062169b11fe8ab0769a87491bbb7f85fdbc1452c0af8c9" - } + "controlled-image-capabilities.json": "7ed4f80b7100b9fc6782d48606680302778a4422de04f776fcd541da2bcc9237", + "controlled-text-capabilities.json": "12bf001573db2e557f83f8423c760d9c3e948e4c6198f9a21970202567577bf6" + }, + "capabilities_update": "Pumas Library v0.8.0 (69e32a2208c5c2d840f4adafec03350669fcb5bc): descriptors gain input_modalities and output_modalities, the serving gains modalities, chat accepts messages_multimodal, rerank is listed, and the pre-release reason unqualified_audio_runtime becomes unsupported_adapter. The gateway harness is unchanged." } diff --git a/tests/test_pumas_served_models.py b/tests/test_pumas_served_models.py new file mode 100644 index 00000000..37506e2f --- /dev/null +++ b/tests/test_pumas_served_models.py @@ -0,0 +1,143 @@ +"""What a Pumas 0.8.0 endpoint serves: `GET /v1/served-models` against a fake, never a running Pumas.""" +import copy +import json +import sys +import unittest +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) +sys.path.insert(0, str(Path(__file__).resolve().parent)) + +import pumas_operations as pumas +from fake_pumas_typed import start + +LISTING = json.loads((Path(__file__).parent / 'fixtures/pumas-image-to-text-v1/served-models.json').read_bytes()) + + +class ServedModelsTests(unittest.TestCase): + def setUp(self): + self.server, self.url, self.state = start() + self.addCleanup(self.server.server_close); self.addCleanup(self.server.shutdown) + self.listing = copy.deepcopy(LISTING) + self.state['served_models'] = self.listing + + def entry(self, model, profile): + return next(row for row in self.listing['models'] if row['model'] == model and row['profile'] == profile) + + def test_two_models_one_served_by_two_profiles(self): + served = pumas.served_models(self.url) + self.assertEqual(served['max_request_bytes'], 33554432) + pairs = [(row['model'], row['profile'], row['profile_required']) for row in served['models']] + self.assertEqual(pairs, [('controlled-vision', 'vision-cpu', True), ('controlled-vision', 'vision-gpu', True), + ('controlled-image', 'controlled-image-cpu', False)]) + cpu, gpu, image = served['models'] + self.assertEqual((cpu['provider'], cpu['load_state'], cpu['context_tokens']), ('llama_cpp', 'loaded', 8192)) + self.assertEqual(gpu['load_state'], 'loading'); self.assertIsNone(image['context_tokens']) + self.assertEqual(cpu['modalities'], {'input': ['text', 'image'], 'output': ['text']}) + self.assertEqual(image['modalities'], {'input': ['text'], 'output': ['image']}) + vision = next(row for row in cpu['capabilities'] if row['capability'] == 'image_to_text') + self.assertEqual(vision['availability'], {'state': 'available'}) + self.assertEqual(vision['input_modalities'], ['text', 'image']); self.assertEqual(vision['output_modalities'], ['text']) + self.assertEqual(vision['option_bounds']['max_tokens'], {'minimum': 1, 'maximum': 8192}) + self.assertEqual(vision['option_bounds']['total_image_bytes']['maximum'], 16777216) + # A trailing `/v1` on the address is accepted, as elsewhere for gateways. + self.assertEqual(pumas.served_models(self.url + '/v1'), served) + + def test_available_capabilities_by_input_kind_and_output(self): + cpu, gpu, image = pumas.served_models(self.url)['models'] + self.assertEqual(pumas.available_capabilities(cpu, 'image', 'text'), ['image_to_text']) + self.assertEqual(pumas.available_capabilities(cpu, 'image_messages', 'text'), ['image_to_text']) + self.assertEqual(pumas.available_capabilities(cpu, 'messages', 'text'), ['chat_generation']) + # The release sends a `text` input to chat as one user message. + self.assertEqual(pumas.available_capabilities(cpu, 'text', 'text'), ['chat_generation', 'text_generation']) + self.assertEqual(pumas.available_capabilities(cpu, 'text', 'png_base64'), []) + self.assertEqual(pumas.available_capabilities(gpu, 'image', 'text'), []) + self.assertEqual(pumas.available_capabilities(image, 'text', 'png_base64'), ['image_generation']) + self.assertEqual(pumas.available_capabilities(image, 'rerank', 'relevance_scores'), []) + for kind, output in (('video', 'text'), ('text', 'future_output')): + with self.subTest(kind=kind, output=output), self.assertRaises(ValueError): + pumas.available_capabilities(cpu, kind, output) + + def test_unavailable_capability_keeps_its_reason(self): + gpu = pumas.served_models(self.url)['models'][1] + vision = next(row for row in gpu['capabilities'] if row['capability'] == 'image_to_text') + self.assertEqual(vision['availability'], {'state': 'unavailable', 'reason': 'runtime_unavailable'}) + image = next(row for row in gpu['capabilities'] if row['capability'] == 'image_generation') + self.assertEqual(image['availability']['reason'], 'unsupported_adapter') + + def test_unknown_capability_modality_format_option_and_reason_are_ignored(self): + cpu = self.entry('controlled-vision', 'vision-cpu') + cpu['modalities']['input'].insert(1, 'smell'); cpu['modalities']['output'].append('hologram') + cpu['future_field'] = {'nested': True}; self.listing['future'] = 1 + cpu['capabilities'].insert(0, {'capability': 'future_capability', 'semantic_task': 'future', 'input_formats': [7], + 'availability': 'odd'}) + cpu['capabilities'].append('not even an object') + vision = next(row for row in cpu['capabilities'] if type(row) is dict and row['capability'] == 'image_to_text') + vision['input_modalities'].insert(0, 'smell'); vision['input_formats'].append('future_format') + vision['output_formats'].append('future_output'); vision['extra'] = True + vision['option_bounds'].insert(0, {'option': 'future_option', 'minimum': 'unbounded'}) + decision = next(row for row in cpu['capabilities'] if type(row) is dict and row['capability'] == 'decision') + decision['availability'] = {'state': 'deferred', 'reason': 'future_reason', 'until': 'later'} + served = pumas.served_models(self.url)['models'][0] + self.assertEqual(served['modalities'], {'input': ['text', 'image'], 'output': ['text']}) + self.assertNotIn('future_capability', [row['capability'] for row in served['capabilities']]) + row = next(row for row in served['capabilities'] if row['capability'] == 'image_to_text') + self.assertEqual(row['input_modalities'], ['text', 'image']) + self.assertNotIn('future_format', row['input_formats']); self.assertNotIn('future_option', row['option_bounds']) + self.assertEqual(next(row for row in served['capabilities'] if row['capability'] == 'decision')['availability'], + {'state': 'unavailable', 'reason': 'future_reason'}) + self.assertEqual(pumas.available_capabilities(served, 'image', 'text'), ['image_to_text']) + + def test_response_over_the_bound_is_refused(self): + self.state['served_models_raw'] = b'{"models":[' + b' ' * pumas.MAX_SERVED_MODELS + b']}' + with self.assertRaises(pumas.OperationError) as caught: + pumas.served_models(self.url) + self.assertIn('exceeds', str(caught.exception)) + with self.assertRaises(ValueError): + pumas.decode_served_models(b' ' * (pumas.MAX_SERVED_MODELS + 1)) + + def test_malformed_entries_are_refused_with_the_entry_named(self): + def vision(value): + return next(row for row in value['models'][1]['capabilities'] if row['capability'] == 'image_to_text') + cases = (lambda v: v['models'][1].pop('profile'), + lambda v: v['models'][1].update(profile_required='yes'), + lambda v: v['models'][1].update(context_tokens=0), + lambda v: v['models'][1].update(model=' padded'), + lambda v: v['models'][1].update(modalities=['text']), + lambda v: v['models'][1]['capabilities'].append(copy.deepcopy(vision(v))), + lambda v: vision(v).pop('input_modalities'), + lambda v: vision(v).update(availability={'state': 'unavailable', 'reason': 3}), + lambda v: vision(v)['option_bounds'].append({'option': 'max_tokens', 'minimum': 1, 'maximum': 2}), + lambda v: vision(v)['option_bounds'][0].update(minimum=10, maximum=1), + lambda v: v['models'].append(copy.deepcopy(v['models'][1])), + lambda v: v['models'].__setitem__(1, 'not an object')) + for index, mutate in enumerate(cases): + value = copy.deepcopy(LISTING); mutate(value) + self.state['served_models'] = value + with self.subTest(case=index), self.assertRaises(pumas.OperationError) as caught: + pumas.served_models(self.url) + self.assertIn('Served model', str(caught.exception)) + for mutate in (lambda v: v.update(supported_contract_versions=[2]), lambda v: v.pop('models'), + lambda v: v.update(max_request_bytes=0)): + value = copy.deepcopy(LISTING); mutate(value) + with self.subTest(value=sorted(value)), self.assertRaises(ValueError): + pumas.decode_served_models(json.dumps(value).encode()) + for raw in (b'{"models":[],"models":[]}', b'{"x":NaN}', b'['): + with self.assertRaises(ValueError): + pumas.decode_served_models(raw) + + def test_typed_refusal_and_missing_route_name_their_reason(self): + self.state.update(served_models={'contract_version': 1, 'request_id': None, 'error': { + 'code': 'capability_unavailable', 'outcome': 'not_admitted', 'message': 'the gateway is shutting down'}}, + served_models_status=503) + with self.assertRaises(pumas.OperationError) as caught: + pumas.served_models(self.url) + self.assertIn('the gateway is shutting down', str(caught.exception)) + self.state.update(served_models=None) + with self.assertRaises(pumas.OperationError) as caught: + pumas.served_models(self.url) + self.assertIn('HTTP 404', str(caught.exception)) + + +if __name__ == '__main__': + unittest.main() diff --git a/tests/test_pumas_typed.py b/tests/test_pumas_typed.py index 059ddd55..1e838d38 100644 --- a/tests/test_pumas_typed.py +++ b/tests/test_pumas_typed.py @@ -242,6 +242,9 @@ def test_typed_error_outcome_is_authoritative_and_message_is_retained(self): self.assertIn('provider said '+str(status),job['error']) self.state['mode']='unreadable'; job=self.generate() self.assertEqual(job['provider_outcome'],'not_admitted'); self.assertIn('not valid JSON',job['error']) + self.state['mode']='pre_handler'; job=self.generate() + self.assertEqual(job['provider_outcome'],'not_admitted'); self.assertEqual(job['provider_error_code'],'request_limit') + self.assertEqual(job['provider_http_status'],413); self.assertIn('exceeds 33554432 bytes',job['error']) self.state.update(mode='not_admitted',error_status=503,error_message='image runtime is busy') with self.assertRaises(pumas.OperationError) as caught: self.data.image_requests.generate(self.image()) self.assertIn('image runtime is busy',str(caught.exception)); self.assertEqual(caught.exception.outcome,'not_admitted') diff --git a/tests/test_pumas_vision.py b/tests/test_pumas_vision.py index 91641985..55202b71 100644 --- a/tests/test_pumas_vision.py +++ b/tests/test_pumas_vision.py @@ -28,23 +28,29 @@ def image(encoding='png', size=(16,8), progressive=False): class VisionBoundaryTests(unittest.TestCase): def job(self): return {'id':'caption-17','config':{'model':'controlled-vision','profile':'vision-cpu'}} - def test_actual_dto_schema_identities_and_closed_capability_enum(self): + def test_release_schema_identities_and_closed_capability_enum(self): source = json.loads((FIXTURES/'source.json').read_text()) self.assertEqual(source['producer_commit'], vision.SOURCE_COMMIT) - schemas = source['actual_dto_schema_sha256'] + self.assertEqual(source['producer_tag'], 'v0.8.0') + schemas = source['schema_sha256'] self.assertEqual(set(schemas), {name+'.schema.json' for name in ( - 'operation-request', 'modality-request', 'capabilities-response', + 'operation-request', 'modality-request', 'capabilities-response', 'served-models-response', 'capability-descriptor', 'operation-response', 'error-response')}) + self.assertEqual(set(schemas), set(source['schema_origin'])) for name, digest in schemas.items(): raw = (FIXTURES/'schemas'/name).read_bytes() self.assertEqual(hashlib.sha256(raw).hexdigest(), digest, name) self.assertEqual(json.loads(raw)['$schema'], 'https://json-schema.org/draft/2020-12/schema') + # The release's own consumer reference pins this digest for the descriptor schema it ships. + self.assertEqual(schemas['capability-descriptor.schema.json'], + '070f85949bff2451a0ca3f3a489548afff82f7d1e3a25ddc6036370aab6f3365') descriptor = json.loads((FIXTURES/'schemas/capability-descriptor.schema.json').read_text()) # Documented capability variants export as `oneOf`; new ones are appended additively. variants = descriptor['$defs']['Capability']['oneOf'] names = [name for row in variants for name in row.get('enum', [row.get('const')])] self.assertTrue(set(pumas.USED_CAPABILITIES) <= set(names)) - self.assertTrue({'multimodal_embedding', 'decision'} <= set(names)) + self.assertTrue({'multimodal_embedding', 'decision', 'rerank'} <= set(names)) + self.assertTrue(set(pumas.CAPABILITIES) <= set(names)) error = json.loads((FIXTURES/'schemas/error-response.schema.json').read_text()) self.assertIn('message', error['$defs']['OperationError']['required']) self.assertEqual(error['properties']['request_id']['type'], ['string', 'null']) @@ -57,6 +63,9 @@ def test_source_derived_descriptors_validate_against_actual_schemas(self): 'capabilities-response', 'operation-request', 'modality-request', 'operation-response', 'error-response')} def valid(name, value): jsonschema.Draft202012Validator(schemas[name]).validate(value) valid('capabilities-response', json.loads((FIXTURES/'controlled-capabilities.json').read_bytes())) + schemas['served-models-response'] = json.loads((FIXTURES/'schemas/served-models-response.schema.json').read_text()) + valid('served-models-response', json.loads((FIXTURES/'served-models.json').read_bytes())) + valid('error-response', {'contract_version':1,'request_id':'caption-17','error':{'code':'request_limit','outcome':'not_admitted','message':'the request has more than 4 images; the limit is 4'}}) valid('operation-request', vision.request(self.job(), image(), facade=False)) valid('operation-request', vision.request(self.job(), {'kind':'image_messages','messages':[{'role':'user','content':[image()]}]}, facade=False)) valid('modality-request', {key: value for key, value in vision.request(self.job(), image('jpeg')).items()}) From f26361dcf4bdd4a31528245b652b37bd3ba3af04 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Fri, 13 Nov 2026 15:49:06 -0700 Subject: [PATCH 063/131] docs(plan): the spec of the weights view Phase 2 of the data tools plan: a model's weights layer by layer. Three read operations (the weights files of a run and their layers, a comparison of two files tensor by tensor, an array as tiles), .safetensors read like .npz, and a Weights block in a model's drawer. A PyTorch pickle is listed with the reason it is not opened. Co-Authored-By: Claude Fable 5.2 --- .../definition-first-projects/spec-d2.md | 82 +++++++++++++++++++ 1 file changed, 82 insertions(+) create mode 100644 docs/plans/definition-first-projects/spec-d2.md diff --git a/docs/plans/definition-first-projects/spec-d2.md b/docs/plans/definition-first-projects/spec-d2.md new file mode 100644 index 00000000..5aa97774 --- /dev/null +++ b/docs/plans/definition-first-projects/spec-d2.md @@ -0,0 +1,82 @@ +# Implementation spec: a model's weights, layer by layer + +This is phase 2 of [the data tools plan](data-tools-plan.md). It builds on [spec-d1.md](spec-d1.md) (reading inside a product) and its rules apply: standard library only, nothing unpickled, nothing written, bounded reads, a damaged file refused and not a failure. The page follows [spec-w4.md](spec-w4.md). + +**Owner, 2026-11-13:** "It would be great if tuldok also had a layer visulization tool so we can visualize a models weights." + +**After this phase** a model's drawer shows the weights its run produced: every layer with its shape and size, how its values are distributed, its kernels or matrix as images, and how much each layer changed from the weights it started from or from the model it derives from. Nothing runs the model: there are no activations and no drawn architecture, since nothing records one. + +## 1. What a run's weights are + +- The outputs of the run whose role is `weights`, as the product records them. +- When it records none: the files at the top of the product whose extension is `.npz`, `.safetensors`, `.pt`, `.pth`, `.ckpt`, `.bin` or `.onnx` and whose name contains `weight` or `model`, not beginning `initial-`. +- **Readable:** `.npz` and `.safetensors`. Anything else is listed with the reason it is not opened: a PyTorch file is a pickle, and Tuldok never opens a pickle (decision 4 of the plan: the training code writes `.npz` or `.safetensors` beside it). +- **The weights a run started from:** the file beside a weights file with the same name prefixed `initial-` (the earlier lab runs keep `initial-weights.npz`). + +## 2. `.safetensors` + +Read like an `.npz`: its tensors are its arrays, by name, in `inside`, `record`, `array_slice` and `array_summary`. The extension joins kind `array`. + +The file is 8 bytes (the header's length, little-endian), the header (JSON: each tensor's `dtype`, `shape` and `data_offsets`, and `__metadata__`), then the data. Bounds: a header of at most 16 MiB; offsets inside the file, not overlapping the header. Types read: `F16 F32 F64 I8 I16 I32 I64 U8 U16 U32 U64 BOOL`, little-endian, row-major. A tensor of another type (`BF16` and the rest) is listed with its type and refused `unsupported` when read. Data on disk is read through `mmap` as an `.npy` is. + +## 3. Operations + +Three reads, `inspect`, in the table like the others. Every one takes `run` (a finished run, as in spec-d1). + +| Operation | Arguments | Result | +| --- | --- | --- | +| `weights` | none besides `run` | `files`: each weights file with `path`, `output` (the output's name, or null when found by name), `bytes`, `readable`, `reason` (a sentence, when not readable), `starts_from` (the address of its `initial-` file, or null), and when readable `parameters` (a count) and `layers` | +| `weights_compare` | `path`, `other_run`, `other_path` | `tensors`: for each array in both with the same shape, `array`, `parameters`, `norm`, `other_norm`, `difference_norm`, `relative_change` (the difference's norm over the other's; null when that is zero), `cosine` (null when either norm is zero), `largest_change`. `total`: the same over all of them together. `only_here`, `only_there` (names), `reshaped` (name and both shapes) | +| `array_tiles` | `path`, `array`, `across` (the axis counted over), `axes` (the two drawn in each tile, default the last two), `index` (positions on the remaining axes, default the middle), `first` (default 0), `most` (tiles at most, default 16, at most 64) | `shape`, `dtype`, `across`, `axes`, `index`, `first`, `tiles`, `rows`, `columns`, `values_f32` (base64: tile by tile, each row by row), `min`, `max`, `nonfinite` | + +**Layers.** A tensor's layer is its name without its last dotted part: `encoders.0.layers.0.weight` and `encoders.0.layers.0.bias` are the tensors `weight` and `bias` of the layer `encoders.0.layers.0`. A name with no dot is its own layer. Layers keep the order of the file. Each layer has `name`, `parameters` and `tensors` (each: `array`, `name`, `shape`, `dtype`, `parameters`). + +**Norms** are Euclidean, over 64-bit floats, with `math.sumprod` and `math.fsum`. Non-finite values make the quantities that include them null, and `nonfinite` counts them. + +**Bounds.** A tile is at most 64 by 64 (subsampled by a stride beyond, as a slice is); `weights_compare` reads at most 32,000,000 values in all and is refused `too-large` beyond, saying how many there are; `weights` lists at most 10,000 tensors per file. + +`other_run` may be the same run (its `initial-` file) or any other finished run of the project. + +## 4. The page + +In a model's drawer, a block **Weights**, after "Runs and product", when the model has a current product with a weights file. + +- **Head:** the file (a select when there are several), its size and parameter count. A file that is not readable shows its reason and nothing else. +- **Compare with:** nothing (the default), "the weights it started from" when the run kept them, "the model it derives from" for each model the map draws a line from that has readable weights. Choosing one asks `weights_compare` once. +- **The layers,** as a table: name, shape of its first tensor, parameters, a small drawing of how its values are distributed (asked for when the row comes on screen, 32 bins), and when comparing a bar of how much it changed with the figure. Sorting by name (file order), size or change. +- **A tensor opened** (a click on its layer, then on the tensor when there are several): range, mean, spread, zeros; the distribution, larger; and its values as images. Two dimensions: one image. Three or more: tiles across the first axis with the last two drawn, the other axes on sliders, and controls to change which axis is counted across and to page through the tiles. Colours diverge around zero. When comparing: this, the other, or their difference. +- A layer that exists on one side only, or changed shape, is marked so. + +The drawings reuse the viewers of spec-d1's `inside.js` where they fit. No library, canvas 2D, light and dark, and nothing is redrawn by a timer or a return to the window. + +## 5. Slices + +| | Slice | Files | +| --- | --- | --- | +| D2a | `.safetensors`, the three operations, the contract text | `tuldok_project/inside_arrays.py`, `inside.py`, a new `tuldok_project/inside_weights.py`, `operations.py`, `service.py`, `docs/contracts/project-folder.md`, `tests/test_tuldok_project_weights.py`, and the tests that count the project-folder operations | +| D2b | The Weights block | `static/project-workspace/weights.js`, `screens.js`, `adapter.js`, `base.css`, `app.py` (the asset list), `tests/browser_project_workspace_weights.cjs` | + +D2a is built on a branch of its own beside spec-d1's page; D2b after both. + +## 6. Tests + +**D2a, `tests/test_tuldok_project_weights.py`,** fixtures written by the test with the standard library: + +- A `.safetensors` of several types read through `inside`, `array_slice` and `array_summary`, equal to the same values in an `.npz`; a `BF16` tensor listed and refused; a header longer than the file, offsets outside the file and overlapping the header, each refused `unsupported`. +- `weights` on a run with a declared weights output, on one found by name, on one with an `initial-` file, on one with `model.pt` (not readable, with its reason, and the file is never opened); layers grouped and ordered; parameter counts. +- `weights_compare` against arithmetic the test does itself: identical files (zero change, cosine 1), a known difference, a tensor missing on each side, a changed shape, a zero tensor (nulls), a non-finite value, the bound (lowered for the test). +- `array_tiles` on a five-dimensional kernel: each tile equals the matching `array_slice`; paging with `first`; subsampling. +- The three are in the `project_folder` profile and absent from `catalog`, whose digest is unchanged. + +**D2b, `tests/browser_project_workspace_weights.cjs`,** on a fixture with a parent model and a model derived from it, each with a small `weights.npz` (and the derived one with `initial-weights.npz`), and a third whose only weights file is `model.pt`: + +1. The derived model's drawer shows Weights with the right parameter count and layers in file order; the third model's shows the reason. +2. A layer's distribution is drawn when its row comes on screen and not before. +3. Opening a tensor shows its statistics (equal to the fixture's) and its tiles; the slider and the paging change them. +4. Comparing with the starting weights and with the parent shows the fixture's change per layer; "difference" draws a different image from "this". +5. Nothing is added or removed on a return to the window or a timer reading. +6. Light and dark. + +## 7. Out of scope + +Activations; a drawing of the architecture; reading `.pt`, `.ckpt`, ONNX or GGUF; comparing more than two files; any change to how a recipe declares its outputs. From 0ec230d1a261c7f744affb0ec84af89f65652ef8 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Fri, 13 Nov 2026 15:49:48 -0700 Subject: [PATCH 064/131] docs(plan): ledger entry for the data tools plan, phase 1's server side and the Pumas client Co-Authored-By: Claude Fable 5.2 --- .../execution-ledger.md | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/docs/plans/definition-first-projects/execution-ledger.md b/docs/plans/definition-first-projects/execution-ledger.md index f7b0be09..179a7fed 100644 --- a/docs/plans/definition-first-projects/execution-ledger.md +++ b/docs/plans/definition-first-projects/execution-ledger.md @@ -593,3 +593,28 @@ The tab bar was rebuilt with each of those, the strip on every reading, and the 3. A view of a model's weights layer by layer. **Also carried:** the unreachable lines in catalog mode's run code that read attributes only the deleted modules set. + +## 2026-11-13 — the data tools plan; reading inside a product (server); the Pumas 0.8.0 client + +**Owner, 2026-11-13,** on the [data tools plan](data-tools-plan.md): "we will use the pumas endpoint. We wont be embedding pumas. What do you mean by lables? Right now we just need the basic modality support for data generation and annotation. text, image, audio, 3D (point clouds, mesh). We dont have a specific need for the surrogate lab. This is more a setup so other projects can setup what they need to generate. The rest sounds good. You can go ahead". The plan records what that changed: Pumas as an endpoint only, five kinds of record, "annotation" for "label", the lab's field comparison last. + +**Commits** on `feat/definition-first-projects`, none pushed: the plan and specs (`c7693b0d`, `1c08b2b0`, `685be616`, `f26361dc`); reading inside a product `710a5f01`; the Pumas client `d3270202` (the earlier branch merged), `04e1ddb2`, merged here as `be7af731`. + +**Phase 1, server side** ([spec-d1.md](spec-d1.md), slice D1a). Five read operations and one route open the output of any finished run: its records, one record, its files and archives, a slice and a summary of an array, and the bytes of an image or a sound. Kinds: text, image, audio, point cloud, mesh, array, file. Standard library only; nothing is unpickled, extracted or written. + +**Changed in review:** + +- The reads were answered under the service's one lock, so a large member being decompressed held up every other call. They now find the run under the lock and read outside it. +- The readers were fed 22,000 corrupted files. Compressed data that does not decompress and a binary PLY that ends early raised errors of their own; every entry point now refuses a damaged file as `unsupported` and logs it. A malformed `.npy` was coded `invalid`, which is kept for arguments; it is `unsupported` too. + +**Measured** on the lab's largest product (9.77 GB), through the readers alone: listing 0.004 s, one sample's arrays 0.004 s, a slice 0.009 s, a summary of 645,120 values 0.12 s. + +**Phase 3, the Pumas 0.8.0 client** ([spec-d3.md](spec-d3.md)), built beside phase 1 on a branch of its own. The client written on 2 November against a pre-release was merged, compared with the contract released at the tag `v0.8.0` (read only from the Pumas Library repository; the spec's "As built" has the table) and brought up to it. `served_models()` reads what an endpoint serves, with each model's modalities and capabilities. Nothing uses it yet. No running Pumas was contacted. + +**What Pumas 0.8.0 can make:** text and PNG images. Its contract reserves audio output and has nothing for 3D. Audio and 3D datasets therefore come from import or a project's own generator command until a served model declares them. + +**Tests:** project suite 610; `tests/test_tuldok_project_inside.py` 24; agent interface 43 (4 skipped); the Pumas client and its fakes 80, and the four catalog tools that call it (61); the two Pumas browser checks and the two controller checks. The catalog profile's manifest is unchanged by phase 1. + +**Not verified:** a real Pumas endpoint; the schemas the release does not publish (four are the pre-release export, one is derived); what spec-d1's "As built" lists. The standards service the implementers' rules name answered "awaiting application publication" on 2026-11-13, so no standards text was read for these slices. + +**Next:** the page of phase 1 (the record grid and a viewer per kind), and phase 2 (weights by layer, [spec-d2.md](spec-d2.md)), both being built. From f2ddc53adf9327819354b86e9356a39fb73bab57 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Fri, 13 Nov 2026 15:58:08 -0700 Subject: [PATCH 065/131] docs(plan): the spec of annotation in a project folder Phase 4 of the data tools plan. A task is a new kind of definition (review, class, tags, text, boxes, spans, segments) on a dataset; its annotations are a file of lines beside it in Git, one per record, tied to the record's content by a hash; they are edited in the database and written by Save, as definitions are. Two steps Tuldok itself provides, import and freeze, are built like any build. An Annotate tab, as the mockup laid it out. Four slices. Co-Authored-By: Claude Fable 5.2 --- .../definition-first-projects/spec-d4.md | 179 ++++++++++++++++++ 1 file changed, 179 insertions(+) create mode 100644 docs/plans/definition-first-projects/spec-d4.md diff --git a/docs/plans/definition-first-projects/spec-d4.md b/docs/plans/definition-first-projects/spec-d4.md new file mode 100644 index 00000000..278b42cb --- /dev/null +++ b/docs/plans/definition-first-projects/spec-d4.md @@ -0,0 +1,179 @@ +# Implementation spec: annotation in a project folder + +This is phase 4 of [the data tools plan](data-tools-plan.md). It builds on [spec-d1.md](spec-d1.md) (records and their viewers). Section 1 of [spec-m1-m2.md](spec-m1-m2.md) (rules for implementers) applies, with the import rule as amended by [spec-m7.md](spec-m7.md); the page follows [spec-w4.md](spec-w4.md). + +**Owner, 2026-11-13:** "Right now we just need the basic modality support for data generation and annotation. text, image, audio, 3D (point clouds, mesh). We dont have a specific need for the surrogate lab. This is more a setup so other projects can setup what they need to generate." And on Git: "there has to be enough info to understand what the project/models/itterations/etc is withought carrying unessisary data, binaries, easily calculate info." + +**After this phase** a project can bring files on this machine into a dataset, a person (or an agent allowed to edit) can annotate its records from the page, the annotations are text in the Git folder, and a dataset with splits can be frozen from them and trained on. Nothing here calls Pumas: suggestions and generation are phase 5. + +**Words.** A **record** is one item of a dataset (spec-d1). An **annotation** is what was recorded about one record under one task. A **task** is a definition saying what is recorded and on which dataset. A **term** is one entry of a task's vocabulary. The word "label" is not used for any of these: a definition's `labels` are its own key and value tags, as before. + +## 1. The task: a new kind of definition + +`annotations/.json`, kind `annotation`: + +| Field | | +| --- | --- | +| `format`, `kind`, `title` | as every definition | +| `description`, `card`, `labels` | as every definition; `card` is where the guide for annotators is written | +| `dataset` | required; a reference to a dataset. An edge of the graph, as a chart's benchmark is | +| `task` | required; one of the seven below | +| `vocabulary` | the terms: 1 to 500 different strings of 1 to 200 characters. Required for `class`, `tags`, `boxes`, `spans`, `segments`; not allowed for `review` and `text` | + +| Task | An annotation's `value` | On records of kind | +| --- | --- | --- | +| `review` | null | any but `file` | +| `class` | one term | any but `file` | +| `tags` | a list of different terms, possibly empty | any but `file` | +| `text` | a string of at most 64 KiB: a caption, a transcript, a summary | any but `file` | +| `boxes` | a list of `{"term", "x", "y", "w", "h"}` in pixels of the image, inside it, `w` and `h` above zero | image | +| `spans` | a list of `{"term", "start", "end"}` in characters (code points) of the text, `start` below `end`, inside it | text | +| `segments` | a list of `{"term", "start", "end"}` in seconds, `start` below `end`, with an optional `"text"` | audio | + +A task is never built: it has no `run` and no product. Planning a task plans its dataset, as planning a chart plans its benchmark. + +## 2. The annotations: a file of lines + +`annotations/.jsonl`, beside the task's `.json` and only there (a `.jsonl` with no task of its name is a problem `check` reports). One JSON object per line, keys in this order: + +| Key | | +| --- | --- | +| `record` | the record's id: 1 to 600 characters, no control characters. One line per record | +| `sha256` | the hash of the record's content when it was annotated, or null (section 3) | +| `state` | `draft`, `accepted`, `needs-work` or `rejected` | +| `value` | as the task says; may be null in any state but `accepted` (a `review` task's is always null) | +| `note` | optional; at most 4,000 characters | +| `by` | `owner`, or `agent:` and the credential's label cut to 80 characters. Never an id, a token or a scope | +| `at` | UTC, `YYYY-MM-DDTHH:MM:SSZ` | +| `from` | optional; an object of at most 2 KiB saying what suggested the value (phase 5 fills it). Kept as it is | + +Lines are sorted by `record`, bytewise in UTF-8; each is written with `ensure_ascii` false, separators `,` and `:`, and ends with a newline. The file is at most 64 MiB. A record with no line is not annotated. A file with no line left is deleted on save. + +`check` reads every line: a line that is not such an object, a duplicate record, lines out of order, a value its task does not allow, a term not in the vocabulary. Each is a problem with its line number (the first 20 per file, then a count). A term removed from the vocabulary while annotations use it is a warning naming how many do. + +Example lines, one per task: + +``` +{"record":"a1","sha256":"9f…","state":"rejected","value":null,"note":"blurry","by":"owner","at":"2026-11-13T10:02:11Z"} +{"record":"a2","sha256":"…","state":"accepted","value":"cat","by":"owner","at":"…"} +{"record":"a3","sha256":"…","state":"accepted","value":["indoor","night"],"by":"owner","at":"…"} +{"record":"a4","sha256":"…","state":"draft","value":"a dog on a sofa","by":"agent:helper","at":"…"} +{"record":"a5","sha256":"…","state":"accepted","value":[{"term":"cat","x":10,"y":4,"w":80,"h":60}],"by":"owner","at":"…"} +{"record":"a6","sha256":"…","state":"accepted","value":[{"term":"PER","start":0,"end":5}],"by":"owner","at":"…"} +{"record":"a7","sha256":"…","state":"accepted","value":[{"term":"speech","start":1.25,"end":3.5,"text":"hello"}],"by":"owner","at":"…"} +``` + +## 3. Tying an annotation to what it describes + +An annotation belongs to a record's content, so that it survives the dataset being built again and is noticed when the content differs. + +- **The hash** is SHA-256 of the record's file, of an archive member's bytes once decompressed, or of the UTF-8 of an inline `text`. A record list may carry it (`sha256` joins the keys of `records.jsonl` that spec-d1 knows); `import` and `freeze` write it. Otherwise Tuldok computes it when the record is first annotated and keeps it per run and record. A record over 1 GiB is not hashed: its annotations carry null and are tied by id alone. +- **Stale.** An annotation is stale when the dataset's current product has no record of its id, or has one whose hash differs. Stale is computed, never stored. Stale annotations are kept, counted, shown, and never dropped by Tuldok; a person removes or redoes them. +- Only the records that have annotations are ever hashed to find the stale ones, never a whole product. + +## 4. The working copy + +Annotations are edited in the database and written by Save, as definitions are. + +- **Kept until Save.** `set_annotation` changes rows and marks them unsaved. `status` gains `annotations_unsaved` (per task, how many records) and `annotations_changed` (files changed on disk since the last import); it counts flagged rows and never renders a file. `save` writes each task's file that has unsaved rows, whole, by a temporary file and a rename, and gains `annotations_written` and `annotations_deleted`; it refuses `changed-on-disk` as it does for definitions. +- **A file changed on disk** (a pull, a hand edit) is imported on the next operation. Where it changes a record that also has an unsaved edit here, the project does not open: the refusal is `conflict` and names the file, and `resolve_conflict` keeps the edits here or takes the file, as for definitions. Size and time are compared before a file is hashed. +- **Revert.** `revert_annotations` puts back the saved line of the named records, or of every record of the task. +- **A task with annotations cannot be removed** by `remove_definition`; the refusal says how many there are. +- Every mutation writes one activity row (the task and how many records), as other mutations do. + +## 5. Operations + +| Operation | Who | Arguments | Result | +| --- | --- | --- | --- | +| `annotation_tasks` | inspect | none | `tasks`: each with `task`, `title`, `dataset`, `type`, `vocabulary`, `run` (the dataset's current product, or null), `records`, `counts` (`unannotated`, `draft`, `accepted`, `needs-work`, `rejected`, `stale`, `invalid`), `unsaved` | +| `annotated_records` | inspect | `task`; `state` (one of the counts' names, or absent for all); `kind`; `offset`; `limit` (at most 200) | `records` (as spec-d1's `records`, each with `annotation`: null or `state`, `value`, `note`, `by`, `at`, `stale`, `unsaved`), `total`, `counts` | +| `annotation` | inspect | `task`, `record` | `task`, `record`, `annotation` (the line as it now is, or null), `saved` (the line in the file, or null), `unsaved`, `stale`, `sha256` | +| `set_annotation` | edit, changes | `task`; `items`: at most 200 of `{record, state, value, note}` or `{record, remove: true}`; `from` (optional, applied to every item) | `task`, `set`, `removed`, `unsaved` | +| `revert_annotations` | edit, changes | `task`; `records` (optional) | `task`, `reverted` | + +`set_annotation` checks every item against the task, the vocabulary and the record's kind before changing anything; one bad item refuses the call, naming it. It sets `by` from the caller and `at` from the clock. An agent allowed to edit annotates through the same operation, and its lines say `agent:` and its label. + +The reads that look into a product are answered outside the service's lock, as spec-d1's are. + +## 6. Steps Tuldok provides + +A dataset's `run` names either a `command`, as now, or a `step`: one of `import` and `freeze` (phase 5 adds `generate`). A `step` excludes `command` and `environment`; its outputs are fixed and are not declared. It is planned, requested, approved, run, cancelled and recorded like any build, from a commit as builds are, and shows as `tuldok ` in a plan. + +Tuldok runs `python -m tuldok_project.steps ` with its own interpreter, its own code first on the path and the snapshot's code not on it (`PYTHONSAFEPATH`), the run's settings and output directory as arguments. A step reads files and writes its output; it never opens the database. It prints progress in the existing form. + +**`import`.** Settings: + +| | | +| --- | --- | +| `source` | a directory: relative to the code root (it is then read from the commit, and the dataset can be built anywhere), or absolute (this machine only; `check` warns) | +| `pattern` | which files, in spec-d1's pattern form; default `**/*` | +| `kind` | the kind of every file; default by extension | +| `rights` | required: a sentence on what may be done with the files | +| `lines` | for text: true makes each non-empty line of each file a record of its own. A line of a `.jsonl` file that is an object with a string `text` gives that string; any other line gives itself | + +Output: the files under `files/`, hard-linked (copied across file systems), and `records.jsonl` with `id`, `kind`, `path` or `text`, `sha256`, `bytes`, `rights` and `origin` (the file's path under the source, and its line). Ids are made from the path: `/` becomes `__`, any other character outside `A-Z a-z 0-9 . _ -` becomes `_`, and a number is added to one that repeats. Symbolic links leaving the source are skipped and counted. + +**`freeze`.** A dataset whose `run` has `step: "freeze"`, `inputs: {"records": }`, `annotations` (one or more tasks on that dataset: new edges of the graph) and settings: + +| | | +| --- | --- | +| `seed` | an integer | +| `shares` | the splits and their relative sizes, for example `{"train": 8, "validation": 1, "test": 1}` | +| `include` | which states of the first task's annotations take a record in; default `["accepted"]` | + +It reads the tasks' line files from the commit it is built from (annotations not saved and committed are not frozen, as code is not), takes the records of the input's product that the first task includes and that are not stale, orders them by the SHA-256 of the seed and the record's hash, and cuts that order by the shares. Output: the included records' files linked under `files/` and `records.jsonl` with each record's `split` and `annotations` (per task: `state` and `value`), which join the keys spec-d1 knows. Stale and excluded records are counted in the run's progress and log. + +A frozen dataset is out of date when the line file of any of its tasks differs from the one its run read, as it is when its definition or its input changed. + +## 7. The page + +**The strip** counts annotations with definitions: "3 definitions, 41 annotations unsaved". Save writes both. + +**A tab, Annotate,** between Data and Train, laid out as the mockup's (`docs/plans/project-workspace-redesign/mockups/shared/screens.js`, lines 263 to 325): + +- **Bar:** the task (a select of the project's tasks, with "New task"), a filter by state (All, To do, Accepted, Needs work, Rejected, Stale; "To do" is unannotated and draft together), progress ("412 of 1,000 decided"), and the keys. +- **Left:** the records as a paged grid of 48, each with a dot for its state; a record that is stale or unsaved is marked. +- **Middle:** the record in its viewer (spec-d1's), with previous and next. +- **Right:** the form for the task, a note, and the decision. + +| Task | The form | +| --- | --- | +| `review` | the decision alone | +| `class` | the terms as radio buttons, the first nine on the keys 1 to 9 | +| `tags` | the terms as checkboxes, the same keys | +| `text` | a text area | +| `boxes` | drag on the image to draw a box, choose its term; boxes are selected, moved, resized by their corners and deleted; they are listed beside the image | +| `spans` | select text to mark a span, choose its term; spans are shown in the text and listed | +| `segments` | drag on the waveform to mark a stretch, choose its term, optionally type what is said; a stretch can be played | + +- **The decision:** Accept, Needs work, Reject. "Keep and next" (Enter) keeps the form's value with the chosen decision and moves on; without a decision it is kept as a draft. "Skip" moves on and keeps nothing. Left and right arrows move without keeping. Keys are ignored while typing in a field. +- **New task:** a form with title, dataset, task and vocabulary, which keeps a new definition as an unsaved edit, as the editor does. +- **Stale:** the form shows the annotation with what changed (the record is gone, or its content differs), and "Still right" sets its hash to the record's. +- A task whose dataset has no product says so and offers to plan the dataset. + +**The Data tab** gains two forms that write a dataset definition as an unsaved edit: **Import** (name, source, pattern, kind, rights, lines) and **Freeze** (name, the dataset, its tasks, seed, shares, which states). Building them is the existing plan and request. + +Canvas 2D, no library, light and dark, every control reachable by keyboard; nothing is redrawn by a timer or a return to the window when nothing changed, and what is typed in the form is never lost to a reading. + +## 8. Slices + +| | Slice | Mainly | +| --- | --- | --- | +| D4a | The kind and its schema; the line file read, checked and written; `check`, the folder reader, the graph and the plan know both | `documents.py`, `schemas/`, `folder.py`, `check.py`, `graph.py`, `plan.py`, a new `annotations.py`, `operations.KINDS`, the page's kind lists | +| D4b | The working copy (tables, import, status, save, conflict, revert, the hash cache) and the five operations | `store.py`, a new `annotation_rows.py`, `service.py`, `operations.py`, `inside.py` (the `sha256` key) | +| D4c | `run.step`; `import` and `freeze`; out of date by the line files | `schemas/` (`$defs/run`), `check.py`, `plan.py`, `builds.py`, a new `steps.py`, `inside.py` (the `annotations` key) | +| D4d | The Annotate tab, the strip, the two forms of the Data tab | `static/project-workspace/annotate.js`, `tabs.js`, `actions.js`, `app.js`, `adapter.js`, `base.css`, `app.py` (the asset list) | + +D4a first; D4b and D4c after it; D4d last. `docs/contracts/project-folder.md` is brought up to date by each slice for what it adds. + +## 9. Tests + +- **D4a,** `tests/test_tuldok_project_annotations.py`: a task of each kind checks; each rule of sections 1 and 2 broken once gives its problem with its line; a file written from rows equals the file it was read from, byte for byte; order and escaping; a `.jsonl` without its task; a fresh open of a folder with tasks lists them and their edge; planning a task plans its dataset. +- **D4b,** `tests/test_tuldok_project_annotation_rows.py`: set, status counts, save writes the file and clears the count; a second open reads the same; revert; a file changed on disk with and without an unsaved edit on the same record (import, and conflict resolved both ways); stale by a missing record and by different content; the hash is computed once per run and record and not for a record over the bound (lowered for the test); every refusal of `set_annotation`; an agent's line says `agent:` and its label and nothing else of it; removing a task with annotations is refused; 100,000 annotations set in batches, counted, saved and reopened within a time the test states. +- **D4c,** `tests/test_tuldok_project_steps.py`: `import` of a tree holding each kind, by pattern, with `lines`, from a relative and an absolute source, ids made unique, links out skipped; the product is read by spec-d1's operations with the hashes given; `freeze` splits by the shares, the same for the same seed and different for another, includes by state, leaves out stale ones, carries the annotations; it goes out of date when a line file changes and not when another task's does; a step runs with no environment and cannot import the snapshot's code. +- **D4d,** `tests/browser_project_workspace_annotate.cjs`, on a fixture with a record of each kind imported: a task of each kind is made from the page and one record annotated with it, by pointer for boxes, spans and segments and by keys for class and tags; the strip's count; Save, then the file on disk has the lines; a reload shows them; a filter by state; a stale record marked and put right; nothing rebuilt on a return to the window while the form holds typed text, and the text still there. +- **The example.** `examples/tiny-project` gains a few small files of each kind and an `import` of them from a relative source, a `class` task with annotations, and a `freeze`. The plan's test for this phase is run on it: import, annotate from the page, save, a fresh clone shows the same annotations, the frozen dataset builds with its splits. + +## 10. Out of scope + +Suggestions from a model and generation (phase 5); the history of one annotation (Git has it); several people's annotations of one record side by side and agreement between them; export to COCO and other formats; annotating arrays beyond the tasks that fit any kind; polygons, masks, keypoints and 3D boxes; importing from a URL. From dfbeb10e0d5c84b5294cd4abb8f305c6225d5278 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Fri, 13 Nov 2026 16:04:30 -0700 Subject: [PATCH 066/131] feat(project): read a model's weights layer by layer Three read operations on the output of a finished run. weights lists a run's weights files with their layers (a tensor's layer is its name without its last part), parameter counts and the weights it started from; a file that is not .npz or .safetensors is listed with the reason it is not opened, and a PyTorch pickle is never opened. weights_compare compares two files tensor by tensor: norms, the norm of the difference, relative change, cosine, largest change. array_tiles reads an array as tiles across one axis, for kernels. .safetensors is read like .npz: its tensors are arrays, through mmap, with the header bounded and every offset checked. Found in review: array_summary answered Infinity for 64-bit values too large to sum or square, which is not JSON. An overflowing mean or deviation is now null. Nothing is written; the catalog profile's manifest is unchanged. Co-Authored-By: Claude Fable 5.2 --- docs/contracts/project-folder.md | 96 ++- .../definition-first-projects/spec-d2.md | 17 + tests/test_tuldok_project_inside.py | 15 + tests/test_tuldok_project_service.py | 12 +- tests/test_tuldok_project_weights.py | 550 ++++++++++++++++++ tuldok_project/inside.py | 63 +- tuldok_project/inside_arrays.py | 117 +++- tuldok_project/inside_weights.py | 386 ++++++++++++ tuldok_project/operations.py | 23 +- tuldok_project/service.py | 67 ++- 10 files changed, 1275 insertions(+), 71 deletions(-) create mode 100644 tests/test_tuldok_project_weights.py create mode 100644 tuldok_project/inside_weights.py diff --git a/docs/contracts/project-folder.md b/docs/contracts/project-folder.md index 8ea8c8fe..87db96bc 100644 --- a/docs/contracts/project-folder.md +++ b/docs/contracts/project-folder.md @@ -1884,6 +1884,9 @@ and result keys of each operation are in its contract. | `inside` | inspect | List a directory, an archive or the arrays of an .npz in a finished run's product. | | `array_slice` | inspect | Read a slice along two axes of an array in a finished run's product, as 32-bit floats. | | `array_summary` | inspect | Read the range, mean, deviation and histogram of an array in a finished run's product. | +| `weights` | inspect | List the weights files of a finished run's product, each with its size, the file it started from and, when Tuldok reads it, its layers and parameter count. | +| `weights_compare` | inspect | Compare, array by array, a weights file of a finished run's product with one of the same or another finished run: norms, relative change, cosine and largest change. | +| `array_tiles` | inspect | Read tiles of two axes of an array in a finished run's product, one per position along a third axis, as 32-bit floats. | | `set_definition` | edit | Check a definition's text and keep it as an unsaved edit. | | `remove_definition` | edit | Mark a definition that nothing uses as removed, until the project is saved. | | `revert_definition` | edit | Put back the file in the folder in place of a definition's unsaved edit or removal, or drop a definition the folder has no file for. | @@ -1982,8 +1985,8 @@ project stay command-line actions. A **product** is the `output` directory of a run in state `succeeded` or `adopted`, named by its run id (or an unambiguous prefix of it). The -operations `records`, `record`, `inside`, `array_slice` and `array_summary` -read it; each takes `run`, and a run that does not exist, has not finished or +operations `records`, `record`, `inside`, `array_slice`, `array_summary`, +`array_tiles`, `weights` and `weights_compare` read it; each takes `run`, and a run that does not exist, has not finished or has no output directory is refused `not-found`. Like every operation they open the project for a moment, to find the run and the view of its dataset; they read the product after closing it and write nothing: no file, no row. @@ -2043,7 +2046,7 @@ it: a missing file, and a symbolic link that leaves the product, are refused | audio | `.wav .flac .mp3 .ogg .opus .m4a` | | pointcloud | `.xyz`, and `.ply` with no faces | | mesh | `.obj .stl`, and `.ply` with faces | -| array | `.npy .npz` | +| array | `.npy .npz .safetensors` | | file | everything else | The index of a product's records is kept for the 8 products read last and @@ -2082,12 +2085,13 @@ counts. A file that cannot be read as its kind is refused `invalid`. `offset` and `limit` (at most 500, 200 by default), and answers `entries` and `total`. A directory lists its children, an archive the members at its top (an address `a.zip!samples` lists the members under `samples/`), and an -`.npy` or `.npz` its arrays. Each entry has `name`, `path` (its address), +`.npy`, `.npz` or `.safetensors` its arrays. Each entry has `name`, `path` (its address), `type` (`directory`, `file`, `archive` or `array`), `bytes` (decompressed, for a member) and `kind`; an array also has `array`, `shape` and `dtype`, and its `path` is the address of its file. Directories come first, then by name. A zip nested deeper than an address can name is a `file`. A plain file is -refused `invalid`. +refused `invalid`. A `.safetensors` file is listed with `type` `archive`, as +an `.npz` is, though no address reaches into it with `!`. **Arrays.** NPY versions 1, 2 and 3 are read, in C or Fortran order, little- or big-endian, of floats of 2, 4 and 8 bytes, signed and unsigned integers of @@ -2097,6 +2101,18 @@ structured types) is listed with its type as written and refused `unsupported` when read; an object array is never unpickled. The header is parsed as a literal of at most 64 KiB. +A `.safetensors` file is read like an `.npz`: its tensors are its arrays, named +by `array` as they are in its header, listed in the order of its header. The +file is 8 bytes (the header's length, little-endian), a JSON header of at most +16 MiB (each tensor's `dtype`, `shape` and `data_offsets`, and +`__metadata__`, which is not shown), then the data, read where it lies. The +types `F16 F32 F64 I8 I16 I32 I64 U8 U16 U32 U64 BOOL` are read, little-endian +and in C order, and named as an NPY array's are; a tensor of another type +(`BF16` and the rest) is listed with its type as written and refused +`unsupported` when read. A header longer than the file, data offsets outside +the file or reaching into the header, and data whose length does not match +its shape and type are refused `unsupported`. + **`array_slice`** takes `path`, `array` (for an `.npz`), `axes` (the two axes drawn, by default the last two), `index` (one position per axis, by default the middle of each; ignored for the two drawn) and `most` (rows and columns @@ -2114,6 +2130,20 @@ the lowest to the highest finite value) and `stride`. At most 4,000,000 values are read: beyond that every n-th value in storage order, and `stride` is n. All but `count` and `stride` are of the values read. +**`array_tiles`** takes `path`, `array`, `across` (the axis counted over; by +default the first axis not drawn), `axes` (the two drawn in each tile; by +default the last two other than `across`), `index` (one position per axis, by +default the middle of each; used for the axes neither drawn nor counted +over), `first` (0 by default) and `most` (tiles at most, 16 by default, at most +64). The array has three axes or more; otherwise, or when `first` is outside +`across`, the call is refused `invalid`. It answers `shape`, `dtype`, +`across`, `axes`, `index` (with the position of `first` on `across`), `first`, +`tiles` (how many follow `first`, at most `most`), `rows`, `columns`, +`stride` (as for `array_slice`, one for every tile, each tile at most 64 by +64), `values_f32` (base64 of little-endian 32-bit floats, tile by tile, each +row by row; tile `t` is the slice at position `first + t` on `across`), `min`, +`max` (of the finite values of all the tiles) and `nonfinite`. + **Reading no more than is needed.** A file on disk is mapped read only, and a member stored uncompressed in a zip is read at its offsets in its archive's bytes, so a slice reads only the bytes it draws and listing an archive reads @@ -2144,6 +2174,62 @@ script. Every answer carries `X-Content-Type-Options: nosniff` and whole file. This route is not an operation and is not in the capability manifest: an agent reads records, arrays and text through the operations. +### A model's weights + +`weights`, `weights_compare` and `array_tiles` (above) read a product as the +operations above do: the same addresses and confinement, nothing written, and +a damaged file refused `unsupported`. Nothing runs the model. + +**A run's weights** are the outputs its product records with role +`weights`; a declared output that is a directory gives the files directly in +it with one of the extensions below. When the product records none, they are +the files at the top of the product whose extension is `.npz`, +`.safetensors`, `.pt`, `.pth`, `.ckpt`, `.bin` or `.onnx` and whose name +contains `weight` or `model` (in any case), not beginning `initial-`. Only +`.npz` and `.safetensors` files are read. A PyTorch file (`.pt`, `.pth`, +`.ckpt`, `.bin`) is a pickle: it is listed by name and size with the reason, +and never opened, not even to look at its first bytes. The weights a file +started from are the file beside it with the same name prefixed `initial-`. + +**Layers.** A tensor's layer is its name without its last dotted part: +`encoders.0.layers.0.weight` and `encoders.0.layers.0.bias` are the tensors +`weight` and `bias` of the layer `encoders.0.layers.0`; a name with no dot is +its own layer. Layers are in the order of the file (an `.npz`'s members in the +order of its central directory, a safetensors file's tensors in the order of +its header), each where its first tensor is. + +**`weights`** takes only `run` and answers `files`, each with `path` (its +address), `output` (the output's name, or null when found by name), `bytes` +(null when a declared output is missing), `readable`, `reason` (null when +readable; otherwise a sentence: a pickle, ONNX, another format, a file that is +missing, or one that could not be read and why), `starts_from` (the address of +its `initial-` file, or null) and, when readable, `parameters` (the count of +the tensors listed), `tensors` (how many the file holds) and `layers` (each +`name`, `parameters` and `tensors`, each tensor `array`, `name`, `shape`, +`dtype` and `parameters`). At most 10,000 tensors of a file are listed. A +damaged weights file is listed as not readable with its reason; the call is +not refused for it. + +**`weights_compare`** takes `path`, `other_run` (the same run, for its +`initial-` file, or any other finished run of the project) and `other_path`, +both weights files that are read (otherwise refused `unsupported` with the +reason). For each array in both with the same shape, in the order of `path`, +`tensors` gives `array`, `parameters`, `norm`, `other_norm`, +`difference_norm` (of this minus the other), `relative_change` (the +difference's norm over the other's; null when that is zero), `cosine` (null +when either norm is zero), `largest_change` (the largest absolute difference) +and `nonfinite` (non-finite values in either). `total` gives the same over all +of them together, without `array`. `only_here` and `only_there` name the +arrays of one file only, `reshaped` gives `array`, `shape` and `other_shape` +of those whose shapes differ, and `unread` gives `array`, `dtype` and +`other_dtype` of those with the same shape that one side's type keeps from +being read; neither is compared. Norms are Euclidean, over 64-bit floats; a +quantity that includes a non-finite value is null. Arrays are compared +element by element in C order, whichever order each is stored in. At most +32,000,000 values are read in all (both files together) and at most 10,000 +tensors per file; beyond either the call is refused `too-large`, saying how +many there are. + ## The project directory on this machine Everything a project keeps on one machine alone (installed environments, code diff --git a/docs/plans/definition-first-projects/spec-d2.md b/docs/plans/definition-first-projects/spec-d2.md index 5aa97774..6932748d 100644 --- a/docs/plans/definition-first-projects/spec-d2.md +++ b/docs/plans/definition-first-projects/spec-d2.md @@ -80,3 +80,20 @@ D2a is built on a branch of its own beside spec-d1's page; D2b after both. ## 7. Out of scope Activations; a drawing of the architecture; reading `.pt`, `.ckpt`, ONNX or GGUF; comparing more than two files; any change to how a recipe declares its outputs. + +## As built + +### D2a, the readers and the operations + +What differs from the text above, and what was found. + +- **`weights_compare` also answers `unread`:** tensors of the same shape that one side holds in a type Tuldok does not read (`BF16`, say), with both types. They are left out of the comparison. Each tensor row and `total` also carry `nonfinite`. +- **`array_tiles` also answers `stride`,** as a slice does. `across` defaults to the first axis not drawn; an array of fewer than three axes is refused `invalid`. +- **`weights`** also answers `tensors` (how many the file holds; `parameters` counts those listed, at most 10,000). A declared weights output that is a directory gives the weights files at its top. A declared output that is missing is listed as not readable with `bytes` null. A damaged file is listed as not readable with its reason; the call is not refused. +- **`weights_compare`:** all four arguments are required; a file of more than 10,000 tensors is refused `too-large`; the bound of 32,000,000 values counts both files together. +- **Layer order:** an `.npz` follows its directory of members, a `.safetensors` its header. +- **In `inside.py`** the guard of the entry points, the list of what a damaged file raises and the function that finds an array are no longer private (`reading`, `DAMAGED`, `array_at`), since the weights module uses them. A product now carries the outputs its run recorded, so that no reader opens the database. +- **A summary never answers infinity** (found in review, feeding the readers 20,000 corrupted `.safetensors` files). 64-bit values near the largest a float holds overflowed the mean and the deviation of `array_summary`, which spec-d1 built: the answer held `Infinity`, which is not JSON, and a page could not have read it. A mean or deviation that overflows is null, and the histogram's positions are computed on halved values when the range itself overflows. `weights_compare` already answered null in that case. +- **Measured** on an earlier lab model (26 tensors in 14 layers, 163,068 parameters, 660 KB), through the readers alone: `weights` 0.002 s; `weights_compare` against its `initial-weights.npz` 0.024 s (total relative change 0.85, cosine 0.70; four layers started at zero, so their relative change is null); `array_tiles` of its largest tensor 0.0003 s. +- **Tests:** `tests/test_tuldok_project_weights.py`, 16; `tests/test_tuldok_project_inside.py`, 25; project suite 626 before the review's change, and the two files above after it; agent interface 43 (4 skipped). The catalog profile's digest is unchanged. +- **Not verified:** a `.safetensors` written by the library itself (the tests write their own); comparing a Fortran-ordered array with a C-ordered one is right but reorders value by value, which would be slow on a large tensor; a big-endian machine. diff --git a/tests/test_tuldok_project_inside.py b/tests/test_tuldok_project_inside.py index 40b45d07..afc89097 100644 --- a/tests/test_tuldok_project_inside.py +++ b/tests/test_tuldok_project_inside.py @@ -235,6 +235,21 @@ def test_subsampling_and_non_finite_values(self): self.assertEqual((summary['count'], summary['nonfinite'], summary['min'], summary['max']), (6, 3, -2.0, 3.0)) self.assertEqual(sum(summary['histogram']['counts']), 3) + def test_a_summary_of_values_too_large_to_sum_is_plain_json(self): + huge = 1.7e308 + self.write('same.npy', npy((2,), ' (struct code, NPY descr) +TYPES = {'F16': ('e', ' (stamp, _Index) _LOG = logging.getLogger(__name__) # What a reader raises on bytes that are not what it expects. ValueError covers bad numbers, bad UTF-8 and bad JSON. -_DAMAGED = (struct.error, zlib.error, EOFError, IndexError, KeyError, ValueError, OverflowError, StopIteration, +DAMAGED = (struct.error, zlib.error, EOFError, IndexError, KeyError, ValueError, OverflowError, StopIteration, ArithmeticError, OSError) -def _reading(function): +def reading(function): """function, with what a damaged or mislabelled file makes it raise turned into a refusal (unsupported).""" @functools.wraps(function) def guarded(product, *arguments, **options): @@ -68,7 +72,7 @@ def guarded(product, *arguments, **options): return function(product, *arguments, **options) except ProjectError: raise - except _DAMAGED as error: + except DAMAGED as error: _LOG.warning('A file of run %s could not be read by %s.', product.run_id, function.__name__, exc_info=True) raise ProjectError('That file could not be read: it is damaged, or it is not what its name says ' f'({type(error).__name__}).', 'unsupported') from error @@ -76,12 +80,14 @@ def guarded(product, *arguments, **options): class Product: - """The output directory (real path) of run run_id, and the view of its dataset (a dict) or None.""" + """The output directory (real path) of run run_id, the view of its dataset (a dict) or None, and the outputs + the product records ({name: {path, role, bytes}}, empty when it records none).""" - def __init__(self, run_id, directory, view=None): + def __init__(self, run_id, directory, view=None, outputs=None): self.run_id = run_id self.root = os.path.realpath(directory) self.view = view if isinstance(view, dict) else None + self.outputs = outputs if isinstance(outputs, dict) else {} if not os.path.isdir(self.root): raise ProjectError(f'Run {run_id} has no output directory.', 'not-found') @@ -384,7 +390,7 @@ def _shown(product, record, *, preview): return shown -@_reading +@reading def records(product, *, offset=0, limit=50, kind=None, split=None): index = index_of(product) chosen = [record for record in index.records @@ -414,7 +420,12 @@ def _text_content(record, place): def array_listing(place): - """The arrays of an .npy or .npz Place: [{array, shape, dtype, bytes}]; a plain .npy's one array is named null.""" + """The arrays of an .npy, .npz or .safetensors Place: [{array, shape, dtype, bytes}]; a plain .npy's one array is + named null; a safetensors file's tensors are in the order of its header.""" + if place.name.lower().endswith('.safetensors'): + return [{'array': name, 'shape': header.shape, 'dtype': header.dtype, + 'bytes': header.count * header.itemsize if header.itemsize else None} + for name, header in inside_arrays.safetensors_headers(place)] if place.name.lower().endswith('.npz'): held, blob = inside_archive.open_archive_place(place) found = [] @@ -460,7 +471,7 @@ def _content(record, place): return {} -@_reading +@reading def record(product, identifier): index = index_of(product) position = index.by_id.get(identifier) @@ -485,7 +496,8 @@ def _entry(address, name, kind_of_entry, size, kind): def _file_entry(address, name, size, place_for_head, depth): - if name.lower().endswith('.npz') or (is_archive_name(name) and depth < inside_archive.ARCHIVES_IN_ADDRESS): + if name.lower().endswith(('.npz', '.safetensors')) or (is_archive_name(name) + and depth < inside_archive.ARCHIVES_IN_ADDRESS): kind_of_entry = 'archive' else: kind_of_entry = 'file' @@ -509,7 +521,7 @@ def _entries(product, place): lambda child_place=child_place: child_place.head(64 * 1024), 0)) return found lower = place.name.lower() - if place.kind == 'file' and lower.endswith(('.npz', '.npy')): + if place.kind == 'file' and lower.endswith(ARRAY_FILES): return [{**_entry(address, item['array'] or place.name, 'array', item['bytes'], 'array'), 'array': item['array'], 'shape': item['shape'], 'dtype': item['dtype']} for item in array_listing(place)] @@ -534,7 +546,7 @@ def _entries(product, place): return found -@_reading +@reading def inside(product, *, path='', offset=0, limit=200): place = locate(product.root, path, folders=True) entries = _entries(product, place) @@ -544,10 +556,19 @@ def inside(product, *, path='', offset=0, limit=200): # -------------------------------------------------------------------- arrays -def _array_at(product, path, name): - """(Blob, Header, a name for messages) of the array at path (an .npy, or an .npz with name).""" +def array_at(product, path, name): + """(Blob, Header, a name for messages) of the array at path (an .npy, or an .npz or .safetensors with name).""" place = locate(product.root, path) lower = place.name.lower() + if lower.endswith('.safetensors'): + if not name: + raise ProjectError(f'{path} holds several tensors; name one with array.', 'invalid') + header = dict(inside_arrays.safetensors_headers(place)).get(name) + if header is None: + raise ProjectError(f'There is no array {name} in {path}.', 'not-found') + label = f'{path} {name}' + header.require(label) + return place.blob(), header, label if lower.endswith('.npz'): if not name: raise ProjectError(f'{path} holds several arrays; name one with array.', 'invalid') @@ -560,21 +581,21 @@ def _array_at(product, path, name): elif lower.endswith('.npy'): label = path else: - raise ProjectError(f'{path} is not an .npy or .npz array.', 'invalid') + raise ProjectError(f'{path} is not an .npy, .npz or .safetensors array.', 'invalid') header = inside_arrays.read_header(place) header.require(label) return place.blob(), header, label -@_reading +@reading def array_slice(product, *, path, array=None, axes=None, index=None, most=256): - blob, header, label = _array_at(product, path, array) + blob, header, label = array_at(product, path, array) return inside_arrays.array_slice(blob, header, label, axes=axes, index=index, most=most) -@_reading +@reading def array_summary(product, *, path, array=None, bins=64): - blob, header, label = _array_at(product, path, array) + blob, header, label = array_at(product, path, array) return inside_arrays.array_summary(blob, header, label, bins=bins) @@ -590,7 +611,7 @@ def __init__(self, status, headers, length, chunks): _RANGE = re.compile(r'bytes=(\d+)-(\d*)') -@_reading +@reading def file_response(product, address, range_header=None, chunk=1 << 16): """The bytes of a file or archive member of a product, with its media type, disposition and range.""" place = locate(product.root, address) diff --git a/tuldok_project/inside_arrays.py b/tuldok_project/inside_arrays.py index aeea5fd1..110f9ac0 100644 --- a/tuldok_project/inside_arrays.py +++ b/tuldok_project/inside_arrays.py @@ -1,4 +1,4 @@ -"""Arrays in a product: NPY headers, the arrays of an NPZ, a two-axis slice and a summary, without numpy. +"""Arrays in a product: NPY and safetensors headers, a two-axis slice and a summary, without numpy. Owns the "Arrays" paragraph and the array_slice and array_summary rows of section 3 of docs/plans/definition-first-projects/spec-d1.md. A header is @@ -12,11 +12,21 @@ loop runs per value; they are decoded with the array module (struct for half floats). A summary reads at most SUMMARY_VALUES values, every n-th in storage order beyond that. + +A .safetensors file (section 2 of spec-d2.md) is 8 bytes giving the length +of a JSON header (at most SAFETENSORS_HEADER_BYTES), the header, then the +data; safetensors_headers turns each tensor of its header into a Header of +the NPY reader (little-endian, C order, its offset where its data begins in +the file), so a tensor is sliced and summarised as an NPY array is. A tensor +of a type outside SAFETENSORS_TYPES is listed with its type and refused when +read. A header longer than the file, and data offsets outside the file or +reaching into the header, are refused unsupported. """ import ast from array import array import base64 import collections +import json import math import operator import struct @@ -26,6 +36,9 @@ from .store import ProjectError HEADER_BYTES = 64 * 1024 # an NPY header +SAFETENSORS_HEADER_BYTES = 16 * 1024 * 1024 # a safetensors header +SAFETENSORS_TYPES = {'F16': '= 0 + + +def safetensors_headers(place): + """[(name, Header)] of the tensors of the .safetensors file a Place holds, in the order of its header. + + Each Header's offset is where its data begins in the file. Only the + header is read. A tensor of a type Tuldok does not read has kind None + and says so in problem. + """ + size = place.size or 0 + head = place.head(8) + if len(head) < 8: + _refuse('This is not a safetensors file: it is shorter than 8 bytes.') + length = struct.unpack(' SAFETENSORS_HEADER_BYTES: + _refuse(f'The safetensors header is {length} bytes; at most {SAFETENSORS_HEADER_BYTES} are read.') + if 8 + length > size: + _refuse(f'The safetensors header says it is {length} bytes, longer than the file.') + try: + value = json.loads(bytes(place.head(8 + length)[8:]).decode('utf-8')) + except (ValueError, RecursionError): + _refuse('The safetensors header is not JSON.') + if not isinstance(value, dict): + _refuse('The safetensors header is not a JSON object.') + start = 8 + length + found = [] + for name, entry in value.items(): + if name == '__metadata__': + continue + if (not isinstance(entry, dict) or not isinstance(entry.get('dtype'), str) + or not isinstance(entry.get('shape'), list) or not all(map(_whole, entry['shape'])) + or not isinstance(entry.get('data_offsets'), list) or len(entry['data_offsets']) != 2 + or not all(type(item) is int for item in entry['data_offsets'])): + _refuse(f'The safetensors entry {name!r} must hold a dtype, a shape of whole numbers and two ' + 'data_offsets.') + begin, end = entry['data_offsets'] + if begin < 0 or end < begin: + _refuse(f'The data of the tensor {name!r} reaches into the safetensors header.') + if start + end > size: + _refuse(f'The data of the tensor {name!r} lies outside the file.') + dtype = entry['dtype'] + header = Header(list(entry['shape']), SAFETENSORS_TYPES.get(dtype, dtype), False, start + begin) + if dtype not in SAFETENSORS_TYPES: + header.descr, header.kind, header.itemsize = dtype, None, None + header.problem = f'of the type {dtype}' + elif end - begin != header.count * header.itemsize: + _refuse(f'The data of the tensor {name!r} is {end - begin} bytes; its shape and type need ' + f'{header.count * header.itemsize}.') + found.append((name, header)) + return found + + # ------------------------------------------------------------------- reading def gather(view, start, step, count, itemsize): @@ -168,7 +235,7 @@ def decode(raw, header): return values -def _check_length(blob, header, name): +def check_length(blob, header, name): if header.offset + header.count * header.itemsize > len(blob.view): _refuse(f'{name} is shorter than its shape says.') @@ -181,7 +248,7 @@ def float32_base64(values): return base64.b64encode(packed.tobytes()).decode('ascii') -def _finite_range(values): +def finite_range(values): """(minimum, maximum, count of non-finite) of numbers; the minimum and maximum of the finite ones.""" try: total = sum(values) @@ -198,7 +265,19 @@ def _finite_range(values): def array_slice(blob, header, name, *, axes=None, index=None, most=256): """Two axes of an array, at index on the others, at most most rows and columns (one stride for both).""" header.require(name) - _check_length(blob, header, name) + check_length(blob, header, name) + axes, index, rows, columns, stride, values = slice_values(blob, header, name, axes=axes, index=index, most=most) + low, high, nonfinite = finite_range(values) + return {'shape': header.shape, 'dtype': header.dtype, 'axes': axes, 'index': index, 'rows': rows, + 'columns': columns, 'stride': stride, 'values_f32': float32_base64(values), 'min': low, 'max': high, + 'nonfinite': nonfinite} + + +def slice_values(blob, header, name, *, axes=None, index=None, most=256): + """(axes, index, rows, columns, stride, values row by row) of the slice array_slice answers. + + The caller has checked the header (require) and the blob's length. + """ shape, ndim = header.shape, len(header.shape) if axes is None: axes = list(range(max(0, ndim - 2), ndim)) @@ -235,16 +314,13 @@ def array_slice(blob, header, name, *, axes=None, index=None, most=256): for row in range(rows): values.extend(decode(gather(blob.view, base + row * stride * row_step, stride * column_step, columns, header.itemsize), header)) - low, high, nonfinite = _finite_range(values) - return {'shape': shape, 'dtype': header.dtype, 'axes': list(axes), 'index': list(index), 'rows': rows, - 'columns': columns, 'stride': stride, 'values_f32': float32_base64(values), 'min': low, 'max': high, - 'nonfinite': nonfinite} + return list(axes), list(index), rows, columns, stride, values def array_summary(blob, header, name, *, bins=64): """Count, range, mean, deviation, zeros, non-finite and a histogram of an array, every stride-th value.""" header.require(name) - _check_length(blob, header, name) + check_length(blob, header, name) count = header.count stride = max(1, math.ceil(count / SUMMARY_VALUES)) read = math.ceil(count / stride) @@ -266,18 +342,25 @@ def array_summary(blob, header, name, *, bins=64): if not finite: return {**result, 'min': None, 'max': None, 'mean': None, 'std': None, 'zeros': 0, 'histogram': {'low': None, 'high': None, 'counts': [0] * bins}} + # 64-bit values near the largest a float holds overflow a sum or a square: such a mean or deviation is null, + # never infinity (an answer is plain JSON). + mean = std = None try: mean = (total if finite is values else math.fsum(finite)) / len(finite) - except OverflowError: - mean = math.inf - deviations = array('d', map(operator.sub, finite, repeat(mean))) - std = math.sqrt(math.fsum(map(operator.mul, deviations, deviations)) / len(finite)) + deviations = array('d', map(operator.sub, finite, repeat(mean))) + std = math.sqrt(math.fsum(map(operator.mul, deviations, deviations)) / len(finite)) + except (OverflowError, ValueError): + pass + mean = mean if mean is not None and math.isfinite(mean) else None + std = std if mean is not None and std is not None and math.isfinite(std) else None low, high = min(finite), max(finite) counts = [0] * bins if high > low: - scale = bins / (high - low) - for position, many in collections.Counter(map(int, map(operator.mul, map(operator.sub, finite, repeat(low)), - repeat(scale)))).items(): + # Halved when the range itself overflows, so that a position is always a finite number. + part = 1.0 if math.isfinite(high - low) else 0.5 + base, scale = low * part, bins / (high * part - low * part) + for position, many in collections.Counter( + int((value * part - base) * scale) for value in finite).items(): counts[min(position, bins - 1)] += many else: counts[0] = len(finite) @@ -292,7 +375,7 @@ def columns(blob, header, name, wanted, most): Returns (rows in all, stride, [values of each column]). """ header.require(name) - _check_length(blob, header, name) + check_length(blob, header, name) if len(header.shape) != 2 or header.shape[1] < wanted: _refuse(f'{name} must have the shape (N, {wanted} or more).') total = header.shape[0] diff --git a/tuldok_project/inside_weights.py b/tuldok_project/inside_weights.py new file mode 100644 index 00000000..e04603c4 --- /dev/null +++ b/tuldok_project/inside_weights.py @@ -0,0 +1,386 @@ +"""A model's weights: which files of a run are its weights, their layers, how two of them differ, and an array's tiles. + +Owns sections 1 and 3 of docs/plans/definition-first-projects/spec-d2.md +above the readers. A run's weights files are the outputs its product records +with role "weights" (a declared output that is a directory gives the files at +its top with a weights extension), else the files at the top of the product +whose extension is a weights extension and whose name holds "weight" or +"model", not beginning "initial-". Only .npz and .safetensors are opened; a +PyTorch file is a pickle and is listed by name and size with the reason, never +opened, not even to look at its first bytes. weights, weights_compare and +array_tiles answer the operations of those names. Norms are Euclidean over +64-bit floats (math.sumprod per piece, math.fsum over the pieces); a quantity +that includes a non-finite value is None. Bounds: TENSORS tensors listed or +compared per file, COMPARE_VALUES values read by one comparison, tiles of at +most TILE_SIDE by TILE_SIDE and at most TILES_MOST of them. Nothing here opens +the project or writes anything; the files are found and confined by +inside_archive. +""" +import collections +import logging +import math +import operator +import os +from array import array + +from . import inside, inside_archive, inside_arrays +from .inside_archive import locate +from .store import ProjectError + +EXTENSIONS = ('.npz', '.safetensors', '.pt', '.pth', '.ckpt', '.bin', '.onnx') +READABLE = ('.npz', '.safetensors') +PICKLES = ('.pt', '.pth', '.ckpt', '.bin') +ROLE = 'weights' +INITIAL = 'initial-' +TENSORS = 10_000 # tensors listed (weights) or compared (weights_compare) per file +COMPARE_VALUES = 32_000_000 # values read by one weights_compare, both files together +TILE_SIDE = 64 # rows and columns of one tile +TILES_MOST = 64 # tiles in one answer +_PIECE = 1 << 20 # values compared at a time +_LOG = logging.getLogger(__name__) + +Tensor = collections.namedtuple('Tensor', 'name header place') + + +def _extension(name): + return os.path.splitext(name.lower())[1] + + +def unreadable_reason(name): + """Why a weights file called name is not opened, or None when it is read.""" + extension = _extension(name) + if extension in READABLE: + return None + if extension in PICKLES: + return (f'A PyTorch file ({extension}) is a pickle, and Tuldok never opens a pickle; have the training code ' + 'write an .npz or .safetensors file beside it.') + if extension == '.onnx': + return 'Tuldok does not read ONNX files; have the training code write an .npz or .safetensors file beside it.' + return 'Tuldok reads weights from .npz and .safetensors files only.' + + +# ---------------------------------------------------------------- tensors + +def tensors(place, most=None): + """([Tensor] in the order of the file, how many it holds) of an .npz or .safetensors Place; at most most listed.""" + lower = place.name.lower() + if lower.endswith('.safetensors'): + found = [Tensor(name, header, place) for name, header in inside_arrays.safetensors_headers(place)] + return (found if most is None else found[:most]), len(found) + if not lower.endswith('.npz'): + raise ProjectError(f'{place.address}: {unreadable_reason(place.name)}', 'unsupported') + held, blob = inside_archive.open_archive_place(place) + names = [name for name in held.members if name.endswith('.npy') and not name.endswith('/')] + found = [] + for name in names if most is None else names[:most]: + inner = inside_archive.Place(place.address, 'file', parent=blob, archive_=held, member=held.members[name]) + found.append(Tensor(name[:-4], inside_arrays.read_header(inner), inner)) + return found, len(names) + + +def layers(listed): + """The layers of tensors in file order: a tensor's layer is its name without its last dotted part.""" + grouped = collections.OrderedDict() + for tensor in listed: + layer, dot, last = tensor.name.rpartition('.') + if not dot: + layer = last = tensor.name + grouped.setdefault(layer, []).append({'array': tensor.name, 'name': last, 'shape': tensor.header.shape, + 'dtype': tensor.header.dtype, 'parameters': tensor.header.count}) + return [{'name': name, 'parameters': sum(item['parameters'] for item in items), 'tensors': items} + for name, items in grouped.items()] + + +# ---------------------------------------------------------------- weights + +def _top_files(product, place, *, by_name): + """Addresses of the regular files directly in a directory Place with a weights extension, sorted by name.""" + found = [] + for item in sorted(os.scandir(place.path), key=lambda item: item.name): + name = item.name + lower = name.lower() + if lower.startswith(INITIAL) or _extension(name) not in EXTENSIONS: + continue + if by_name and 'weight' not in lower and 'model' not in lower: + continue + address = f'{place.address}/{name}' if place.address else name + try: + if locate(product.root, address).kind == 'file': + found.append(address) + except ProjectError: + continue # a link that leaves the product, or not a regular file + return found + + +def weight_files(product): + """[(address, output name or None)] of a run's weights files (section 1 of spec-d2.md).""" + declared = [(name, item) for name, item in product.outputs.items() + if isinstance(item, dict) and item.get('role') == ROLE and isinstance(item.get('path'), str)] + found = [] + if declared: + for name, item in declared: + address = item['path'].strip('/') + try: + place = locate(product.root, address, folders=True) + except ProjectError: + found.append((address, name)) # listed as missing + continue + if place.kind == 'directory': + found.extend((child, name) for child in _top_files(product, place, by_name=False)) + else: + found.append((address, name)) + else: + top = locate(product.root, '', folders=True) + found = [(address, None) for address in _top_files(product, top, by_name=True)] + seen = set() + return [item for item in found if not (item[0] in seen or seen.add(item[0]))] + + +def _starts_from(product, address): + """The address of the initial- file beside a weights file, or None.""" + folder, _, name = address.rpartition('/') + if name.lower().startswith(INITIAL): + return None + candidate = f'{folder}/{INITIAL}{name}' if folder else INITIAL + name + try: + return candidate if locate(product.root, candidate).kind == 'file' else None + except ProjectError: + return None + + +def _weights_file(product, address, output): + entry = {'path': address, 'output': output, 'bytes': None, 'readable': False, 'reason': None, + 'starts_from': None} + try: + place = locate(product.root, address) + except ProjectError: + entry['reason'] = 'The file is not in the product.' + return entry + entry['bytes'] = place.size # os.stat: the file is not opened + entry['starts_from'] = _starts_from(product, address) + entry['reason'] = unreadable_reason(place.name) + if entry['reason'] is not None: + return entry + try: + listed, total = tensors(place, TENSORS) + except ProjectError as error: + entry['reason'] = f'It could not be read: {error}' + return entry + except inside.DAMAGED as error: + _LOG.warning('A weights file of run %s could not be read.', product.run_id, exc_info=True) + entry['reason'] = ('It could not be read: it is damaged, or it is not what its name says ' + f'({type(error).__name__}).') + return entry + entry.update(readable=True, parameters=sum(tensor.header.count for tensor in listed), tensors=total, + layers=layers(listed)) + return entry + + +@inside.reading +def weights(product): + """{files}: each weights file of the run with its layers when it is read.""" + return {'files': [_weights_file(product, address, output) for address, output in weight_files(product)]} + + +# ---------------------------------------------------------------- compare + +def _weights_place(product, path): + place = locate(product.root, path) + reason = unreadable_reason(place.name) + if reason is not None: + raise ProjectError(f'{path}: {reason}', 'unsupported') + return place + + +def _all_tensors(place, path): + listed, total = tensors(place) + if total > TENSORS: + raise ProjectError(f'{path} holds {total} tensors; at most {TENSORS} are compared.', 'too-large') + return listed + + +def _reader(tensor, label, logical): + """A function (first, count) -> array('d') of the tensor's values from first, in storage order, or in C order + when logical (a Fortran-ordered array is then read whole once).""" + header = tensor.header + blob = tensor.place.blob() + inside_arrays.check_length(blob, header, label) + size = header.itemsize + + def piece(first, count): + raw = inside_arrays.gather(blob.view, header.offset + first * size, size, count, size) + return array('d', inside_arrays.decode(raw, header)) + if not logical or not header.fortran or len(header.shape) < 2: + return piece + whole = piece(0, header.count) + shape = header.shape + reordered = array('d', bytes(8 * header.count)) + # C position of the value at Fortran position f: walk the Fortran order with its C strides. + c_steps, step = [0] * len(shape), 1 + for axis in reversed(range(len(shape))): + c_steps[axis] = step + step *= shape[axis] + position, counters = 0, [0] * len(shape) + for value in whole: + reordered[position] = value + for axis in range(len(shape)): + counters[axis] += 1 + position += c_steps[axis] + if counters[axis] < shape[axis]: + break + position -= c_steps[axis] * shape[axis] + counters[axis] = 0 + return lambda first, count: reordered[first:first + count] + + +def _total(parts): + """math.fsum of non-negative or signed partial sums, or None when one is not finite or the sum overflows.""" + if not all(map(math.isfinite, parts)): + return None + try: + total = math.fsum(parts) + except (OverflowError, ValueError): + return None + return total if math.isfinite(total) else None + + +def _nonfinite(values, squares): + return 0 if math.isfinite(squares) else sum(1 for value in values if not math.isfinite(value)) + + +class _Sums: + """Sums of squares of this, the other and their difference, their dot product, the largest change.""" + + def __init__(self): + self.here, self.there, self.difference, self.dot = [], [], [], [] + self.parameters = self.nonfinite = 0 + self.largest = 0.0 + self.largest_known = True + + def add(self, here, there): + difference = array('d', map(operator.sub, here, there)) + squares = math.sumprod(here, here), math.sumprod(there, there), math.sumprod(difference, difference) + self.here.append(squares[0]) + self.there.append(squares[1]) + self.difference.append(squares[2]) + self.dot.append(math.sumprod(here, there)) + self.parameters += len(here) + bad = _nonfinite(here, squares[0]) + _nonfinite(there, squares[1]) + self.nonfinite += bad + if bad or not math.isfinite(squares[2]): + self.largest_known = False + elif difference: + self.largest = max(self.largest, max(difference), -min(difference)) + + def merge(self, other): + for name in ('here', 'there', 'difference', 'dot'): + getattr(self, name).extend(getattr(other, name)) + self.parameters += other.parameters + self.nonfinite += other.nonfinite + self.largest = max(self.largest, other.largest) + self.largest_known = self.largest_known and other.largest_known + + def result(self): + here, there, difference, dot = (_total(self.here), _total(self.there), _total(self.difference), + _total(self.dot)) + norm, other_norm, difference_norm = (None if value is None else math.sqrt(value) + for value in (here, there, difference)) + relative = difference_norm / other_norm if difference_norm is not None and other_norm else None + cosine = None + if dot is not None and here and there: + scale = math.sqrt(here * there) + if not math.isfinite(scale) or scale == 0: + scale = norm * other_norm + cosine = max(-1.0, min(1.0, dot / scale)) if scale else None + largest = self.largest if self.largest_known and self.parameters else None + return {'parameters': self.parameters, 'norm': norm, 'other_norm': other_norm, + 'difference_norm': difference_norm, 'relative_change': relative, 'cosine': cosine, + 'largest_change': largest, 'nonfinite': self.nonfinite} + + +@inside.reading +def weights_compare(product, *, path, other, other_path): + """How the arrays of the weights file at path differ from those of other_path in the product other.""" + here = _all_tensors(_weights_place(product, path), path) + there = {tensor.name: tensor for tensor in _all_tensors(_weights_place(other, other_path), other_path)} + names_here = {tensor.name for tensor in here} + compared, reshaped, unread = [], [], [] + for tensor in here: + match = there.get(tensor.name) + if match is None: + continue + if tensor.header.shape != match.header.shape: + reshaped.append({'array': tensor.name, 'shape': tensor.header.shape, 'other_shape': match.header.shape}) + elif tensor.header.kind is None or match.header.kind is None: + unread.append({'array': tensor.name, 'dtype': tensor.header.dtype, 'other_dtype': match.header.dtype}) + else: + compared.append((tensor, match)) + values = 2 * sum(tensor.header.count for tensor, _ in compared) + if values > COMPARE_VALUES: + raise ProjectError(f'Comparing {path} with {other_path} reads {values} values; at most {COMPARE_VALUES} ' + 'are read.', 'too-large') + rows, everything = [], _Sums() + for tensor, match in compared: + logical = tensor.header.fortran != match.header.fortran + read_here = _reader(tensor, f'{path} {tensor.name}', logical) + read_there = _reader(match, f'{other_path} {match.name}', logical) + sums = _Sums() + count = tensor.header.count + for first in range(0, count, _PIECE): + taken = min(_PIECE, count - first) + sums.add(read_here(first, taken), read_there(first, taken)) + rows.append({'array': tensor.name, **sums.result()}) + everything.merge(sums) + return {'tensors': rows, 'total': everything.result(), + 'only_here': [tensor.name for tensor in here if tensor.name not in there], + 'only_there': [name for name in there if name not in names_here], + 'reshaped': reshaped, 'unread': unread} + + +# ------------------------------------------------------------------ tiles + +def _refuse(message): + raise ProjectError(message, 'invalid') + + +@inside.reading +def array_tiles(product, *, path, array=None, across=None, axes=None, index=None, first=0, most=16): + """Tiles of two axes of an array, one per position along the axis across, from first, at most most of them.""" + blob, header, label = inside.array_at(product, path, array) + inside_arrays.check_length(blob, header, label) + shape, ndim = header.shape, len(header.shape) + if ndim < 3: + _refuse(f'{label} has {ndim} axes; tiles need three or more (read it with array_slice).') + if axes is None: + axes = [axis for axis in range(ndim) if axis != across][-2:] + if len(axes) != 2 or axes[0] == axes[1] or not all(0 <= axis < ndim for axis in axes): + _refuse(f'axes must be two different axes of the {ndim} of {label}.') + if across is None: + across = next(axis for axis in range(ndim) if axis not in axes) + if not 0 <= across < ndim or across in axes: + _refuse(f'across must be an axis of {label} that is not drawn.') + if index is None: + index = [size // 2 for size in shape] + if len(index) != ndim: + _refuse(f'index must give one position for each of the {ndim} axes of {label}.') + index = list(index) + size = shape[across] + if size and not 0 <= first < size: + _refuse(f'first ({first}) is outside axis {across} of {label}, which has {size}.') + count = max(0, min(most, TILES_MOST, size - first)) + index[across] = first if size else 0 + rows = columns = stride = 0 + values = [] + for tile in range(count): + index[across] = first + tile + _, _, rows, columns, stride, drawn = inside_arrays.slice_values(blob, header, label, axes=list(axes), + index=index, most=TILE_SIDE) + values.extend(drawn) + index[across] = first if size else 0 + if not count: + stride = max(1, math.ceil(shape[axes[0]] / TILE_SIDE), math.ceil(shape[axes[1]] / TILE_SIDE)) + rows, columns = math.ceil(shape[axes[0]] / stride), math.ceil(shape[axes[1]] / stride) + low, high, nonfinite = inside_arrays.finite_range(values) + return {'shape': shape, 'dtype': header.dtype, 'across': across, 'axes': list(axes), 'index': index, + 'first': first, 'tiles': count, 'rows': rows, 'columns': columns, 'stride': stride, + 'values_f32': inside_arrays.float32_base64(values), 'min': low, 'max': high, 'nonfinite': nonfinite} diff --git a/tuldok_project/operations.py b/tuldok_project/operations.py index cdd6bab5..ebf8a993 100644 --- a/tuldok_project/operations.py +++ b/tuldok_project/operations.py @@ -2,8 +2,10 @@ Owns the table of section 2 of docs/plans/definition-first-projects/spec-m7.md, with the three rows of section 2 of spec-w1.md (map, note, recipe_results) and the two of -section 2 of spec-w3.md (draft_branch, revert_definition) and the five of -section 3 of spec-d1.md (records, record, inside, array_slice, array_summary). +section 2 of spec-w3.md (draft_branch, revert_definition), the five of +section 3 of spec-d1.md (records, record, inside, array_slice, array_summary) +and the three of section 3 of spec-d2.md (weights, weights_compare, +array_tiles). Each Operation names one operation project., the rule its caller must satisfy (who), whether it changes anything (mutation), a closed JSON Schema of its arguments and the result keys that are always present. service.py checks @@ -75,6 +77,9 @@ def _arguments(required=(), **properties): SLICE = ('shape', 'dtype', 'axes', 'index', 'rows', 'columns', 'stride', 'values_f32', 'min', 'max', 'nonfinite') SUMMARY_OF_ARRAY = ('shape', 'dtype', 'count', 'min', 'max', 'mean', 'std', 'zeros', 'nonfinite', 'histogram', 'stride') +TILES = ('shape', 'dtype', 'across', 'axes', 'index', 'first', 'tiles', 'rows', 'columns', 'stride', 'values_f32', + 'min', 'max', 'nonfinite') +COMPARE = ('tensors', 'total', 'only_here', 'only_there', 'reshaped', 'unread') SAVE = ('written', 'deleted', 'results_written', 'results_deleted') CANCEL_RUN = ('id', 'reference', 'subject', 'state', 'cancel_file', 'already_asked') STOP_RUN = ('id', 'reference', 'subject', 'was', 'state', 'killed', 'remaining', 'marked_unknown') @@ -170,6 +175,20 @@ def _arguments(required=(), **properties): 'product.', 'inspect', False, _arguments(['run', 'path'], run=_RUN, path=_ADDRESS, array=_ARRAY, bins=_limit(256)), SUMMARY_OF_ARRAY), + Operation('weights', "List the weights files of a finished run's product, each with its size, the file it started " + 'from and, when Tuldok reads it, its layers and parameter count.', 'inspect', False, + _arguments(['run'], run=_RUN), ('files',)), + Operation('weights_compare', "Compare, array by array, a weights file of a finished run's product with one of " + 'the same or another finished run: norms, relative change, cosine and largest change.', 'inspect', + False, + _arguments(['run', 'path', 'other_run', 'other_path'], run=_RUN, path=_ADDRESS, other_run=_RUN, + other_path=_ADDRESS), COMPARE), + Operation('array_tiles', "Read tiles of two axes of an array in a finished run's product, one per position along " + 'a third axis, as 32-bit floats.', 'inspect', False, + _arguments(['run', 'path'], run=_RUN, path=_ADDRESS, array=_ARRAY, across=_AXIS, + axes={'type': 'array', 'items': _AXIS, 'minItems': 2, 'maxItems': 2}, + index={'type': 'array', 'items': {'type': 'integer', 'minimum': 0}, 'maxItems': 64}, + first=_OFFSET, most=_limit(64)), TILES), Operation('set_definition', "Check a definition's text and keep it as an unsaved edit.", 'edit', True, _arguments(['reference', 'text'], reference=_REFERENCE, text=_TEXT), DEFINITION), Operation('remove_definition', 'Mark a definition that nothing uses as removed, until the project is saved.', diff --git a/tuldok_project/service.py b/tuldok_project/service.py index 664fad5a..3bd64533 100644 --- a/tuldok_project/service.py +++ b/tuldok_project/service.py @@ -7,11 +7,12 @@ returns a JSON-plain object. Calls are answered one at a time under one lock of the service. Every mutating call that passed the actor check writes one activity row, done or refused. The six operations on build requests are -passed to build_requests. The five reads inside a product (spec-d1.md) find -the finished run with the project open for a moment and read its output -directory through inside.py after closing it; product_file does the same for -the file route; those reads run outside the lock, so a long one holds up no -other call. Nothing here knows of HTTP or of the app's access layer. +passed to build_requests. The five reads inside a product (spec-d1.md) and +the three reads of a model's weights (spec-d2.md) find the finished run (and +for weights_compare the other run) with the project open for a moment and +read its output directory through inside.py and inside_weights.py after +closing it; product_file does the same for the file route; those reads run +outside the lock, so a long one holds up no other call. Nothing here knows of HTTP or of the app's access layer. The worker (section 4) is one thread per service, started by start() and stopped by close(). It runs queued build requests one at a time while it @@ -36,26 +37,37 @@ import jsonschema import psycopg -from . import (activity, build_requests, builds, charts, check, environments, inside, launcher, local, operations, - plan, store, workspace) +from . import (activity, build_requests, builds, charts, check, environments, inside, inside_weights, launcher, local, + operations, plan, store, workspace) from .documents import Problem CHECK_PROBLEMS = 200 -# The reads inside a product (spec-d1.md), each a function of (inside.Product, arguments). call() finds the product -# under the service's lock and reads outside it: decompressing a large member or parsing a large mesh takes seconds, -# and the other calls (the page's own readings among them) must not wait for it. inside.py guards what it keeps. +# The reads inside a product (spec-d1.md, spec-d2.md), each a function of ({argument: inside.Product}, arguments): +# the products of the arguments in PRODUCT_ARGUMENTS that the call gives. call() finds them under the service's lock +# and reads outside it: decompressing a large member, parsing a large mesh or comparing two large weights files takes +# seconds, and the other calls (the page's own readings among them) must not wait for it. inside.py guards what it +# keeps. +PRODUCT_ARGUMENTS = ('run', 'other_run') INSIDE_READS = { - 'records': lambda product, a: inside.records(product, offset=a.get('offset', 0), limit=a.get('limit', 50), - kind=a.get('kind'), split=a.get('split')), - 'record': lambda product, a: inside.record(product, a['id']), - 'inside': lambda product, a: inside.inside(product, path=a.get('path', ''), offset=a.get('offset', 0), - limit=a.get('limit', 200)), - 'array_slice': lambda product, a: inside.array_slice(product, path=a['path'], array=a.get('array'), - axes=a.get('axes'), index=a.get('index'), - most=a.get('most', 256)), - 'array_summary': lambda product, a: inside.array_summary(product, path=a['path'], array=a.get('array'), - bins=a.get('bins', 64)), + 'records': lambda found, a: inside.records(found['run'], offset=a.get('offset', 0), limit=a.get('limit', 50), + kind=a.get('kind'), split=a.get('split')), + 'record': lambda found, a: inside.record(found['run'], a['id']), + 'inside': lambda found, a: inside.inside(found['run'], path=a.get('path', ''), offset=a.get('offset', 0), + limit=a.get('limit', 200)), + 'array_slice': lambda found, a: inside.array_slice(found['run'], path=a['path'], array=a.get('array'), + axes=a.get('axes'), index=a.get('index'), + most=a.get('most', 256)), + 'array_summary': lambda found, a: inside.array_summary(found['run'], path=a['path'], array=a.get('array'), + bins=a.get('bins', 64)), + 'weights': lambda found, a: inside_weights.weights(found['run']), + 'weights_compare': lambda found, a: inside_weights.weights_compare(found['run'], path=a['path'], + other=found['other_run'], + other_path=a['other_path']), + 'array_tiles': lambda found, a: inside_weights.array_tiles(found['run'], path=a['path'], array=a.get('array'), + across=a.get('across'), axes=a.get('axes'), + index=a.get('index'), first=a.get('first', 0), + most=a.get('most', 16)), } POLL_SECONDS = 1.0 # how often the worker looks for a queued request CLOSE_SECONDS = 30.0 # how long close() waits for the worker @@ -278,8 +290,8 @@ def call(self, name, arguments, actor): raise store.ProjectError(f'The arguments of project.{name} do not match its schema.', 'invalid', problems=problems) with self._lock: - product = self._product(arguments['run']) - return _plain(INSIDE_READS[name](product, dict(arguments))) + found = {key: self._product(arguments[key]) for key in PRODUCT_ARGUMENTS if key in arguments} + return _plain(INSIDE_READS[name](found, dict(arguments))) with self._lock: try: problems = _argument_problems(operation, arguments) @@ -453,11 +465,17 @@ def _draft_branch(self, arguments, actor): # ------------------------------------------------------ inside a product def _product(self, run): - """The inside.Product of a finished run (succeeded or adopted), read with the project open for a moment.""" + """The inside.Product of a finished run (succeeded or adopted), read with the project open for a moment. + + It carries the outputs its products row records (with their roles), so that inside_weights knows which + files are the run's weights without opening the project. + """ with self._open() as project: run_id = builds.find_run(project, run) state, directory, reference = project._execute( 'SELECT state, directory, reference FROM {schema}.runs WHERE id = %s', (run_id,)).fetchone() + recorded = project._execute('SELECT outputs FROM {schema}.products WHERE run_id = %s', + (run_id,)).fetchone() view = None if reference.startswith('datasets/'): row = project._execute('SELECT document FROM {schema}.definitions WHERE directory = %s AND name = %s ' @@ -466,7 +484,8 @@ def _product(self, run): if state not in ('succeeded', builds.ADOPTED) or not directory: raise store.ProjectError(f'Run {run_id} is {state}; only a finished run has a product to look inside.', 'not-found') - return inside.Product(run_id, os.path.join(directory, builds.OUTPUT), view) + return inside.Product(run_id, os.path.join(directory, builds.OUTPUT), view, + recorded[0] if recorded else None) def product_file(self, run, address, range_header=None): """The inside.FileResponse of GET /api/project/file; the caller has checked the right to inspect.""" From eefa274ebaba0fbad21f0ae5fa2558f1aea5baf4 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Fri, 13 Nov 2026 16:20:36 -0700 Subject: [PATCH 067/131] feat(project): annotation tasks and their file of lines A project folder gains an eighth kind of definition, the annotation task, in annotations/.json: the dataset whose records it is on, what is recorded (review, class, tags, text, boxes on images, spans in text, segments in audio) and the vocabulary of terms. The annotations themselves are annotations/.jsonl beside it: one line per record with the record's id, the hash of its content, a state, the value, who and when. Lines are sorted and written in one exact form, so a file read and written back is the same bytes and a diff shows what changed. check reads every line and reports problems with their line numbers; the graph draws the task's edge to its dataset; planning a task plans its dataset. A task is never built. The working copy in the database, the operations, the steps that import and freeze, and the Annotate tab are later slices. Co-Authored-By: Claude Fable 5.2 --- docs/contracts/project-folder.md | 137 +++++- .../definition-first-projects/spec-d4.md | 19 + static/project-workspace/editor.js | 4 +- .../project/annotations/wave-quality.json | 10 + .../project/annotations/wave-quality.jsonl | 2 + tests/test_tuldok_project_annotations.py | 371 +++++++++++++++ tests/test_tuldok_project_charts.py | 6 +- tests/test_tuldok_project_cli.py | 19 +- tests/test_tuldok_project_store.py | 14 +- tuldok_project/annotations.py | 429 ++++++++++++++++++ tuldok_project/charts.py | 3 +- tuldok_project/check.py | 27 +- tuldok_project/documents.py | 5 +- tuldok_project/folder.py | 22 +- tuldok_project/graph.py | 8 +- tuldok_project/operations.py | 2 +- tuldok_project/plan.py | 9 +- tuldok_project/schemas/annotation.schema.json | 149 ++++++ tuldok_project/schemas/benchmark.schema.json | 3 +- tuldok_project/schemas/chart.schema.json | 3 +- tuldok_project/schemas/dataset.schema.json | 3 +- .../schemas/environment.schema.json | 3 +- tuldok_project/schemas/model.schema.json | 3 +- tuldok_project/schemas/recipe.schema.json | 3 +- tuldok_project/schemas/step.schema.json | 3 +- tuldok_project/store.py | 10 +- 26 files changed, 1212 insertions(+), 55 deletions(-) create mode 100644 tests/fixtures/tuldok_project/minimal/project/annotations/wave-quality.json create mode 100644 tests/fixtures/tuldok_project/minimal/project/annotations/wave-quality.jsonl create mode 100644 tests/test_tuldok_project_annotations.py create mode 100644 tuldok_project/annotations.py create mode 100644 tuldok_project/schemas/annotation.schema.json diff --git a/docs/contracts/project-folder.md b/docs/contracts/project-folder.md index 8ea8c8fe..cc97044f 100644 --- a/docs/contracts/project-folder.md +++ b/docs/contracts/project-folder.md @@ -2,16 +2,17 @@ Owner: the package `tuldok_project/` (`folder.py` reads the folder, `documents.py` and `schemas/*.json` check single files, `check.py` applies every rule, -`results.py` owns summary files, `store.py` and `result_rows.py` the database -copy and its results, `charts.py` charts and the report page, `plan.py` +`results.py` owns summary files, `annotations.py` the files of annotations, +`store.py` and `result_rows.py` the database copy and its results, `charts.py` charts and the report page, `plan.py` plans, `environments.py` environments, and `builds.py`, `launcher.py` and `snapshot.py` building). The format names are `tuldok_project_v1` for the folder and `tuldok_definition_v1` for each definition. A project folder describes a piece of research as a set of small JSON files that people and agents write and keep in Git. Each file is a **definition**: it says -what a dataset, model, training recipe, benchmark, build step, environment or -chart is and, where something has to be produced, which command produces it. +what a dataset, model, training recipe, benchmark, build step, environment, +chart or annotation task is and, where something has to be produced, which +command produces it. What a command writes is a **product**. Products stay on the machine that made them; the folder holds only what someone wrote, plus benchmark summaries. @@ -21,7 +22,8 @@ document says exactly what the checker accepts. ## What belongs in the folder Put in the folder: the definitions, the result summary of each benchmark -(`results/`), and cards and notes written by people (`notes/`). +(`results/`), the annotations of each annotation task (`annotations/`), and +cards and notes written by people (`notes/`). Keep out of the folder: generated datasets, weights, logs, run directories, installed environments, caches, checksums of other files, and history. Git is @@ -45,6 +47,8 @@ benchmarks/.json steps/.json environments/.json charts/.json +annotations/.json +annotations/.jsonl the annotations of task results/.csv notes/... ``` @@ -52,14 +56,17 @@ notes/... - `tuldok.json` is required. Every other entry is optional. - Any other top-level entry is an error. Move such files into `notes/` or out of the folder. -- The seven **definition directories** (`datasets/` to `charts/`) hold only +- The eight **definition directories** (`datasets/` to `annotations/`) hold only `.json` files, one definition each, and no subdirectories. + `annotations/` also holds `.jsonl`, the annotations of the task in + `.json`, which must exist. - `results/` holds only `.csv` files. - `notes/` holds plain files and directories to any depth. Their contents are not read. - Every file is a regular file and every directory a real directory. A symbolic link anywhere in the folder, including under `notes/`, is an error. -- Size limits: `tuldok.json` 64 KiB, a definition 1 MiB, a results file 16 MiB. +- Size limits: `tuldok.json` 64 KiB, a definition 1 MiB, a results file 16 MiB, + a file of annotations 64 MiB. A **name** is 1 to 120 characters of lowercase letters, digits, `.`, `_` and `-`, starting with a letter or digit (`^[a-z0-9][a-z0-9._-]{0,119}$`). The file @@ -121,6 +128,7 @@ directories: | `subjects[].recipe` (benchmark) | `recipes/` | | `cases.dataset` (benchmark) | `datasets/` | | `benchmark` (chart) | `benchmarks/` | +| `dataset` (annotation) | `datasets/` | An **input** is what a command reads from another definition's product. It is written either as a reference, meaning the whole product, or as @@ -132,7 +140,7 @@ other definition declares in its `run.outputs`. | Field | Required | Rule | | --- | --- | --- | | `format` | yes | exactly `tuldok_definition_v1` | -| `kind` | yes | `dataset`, `model`, `recipe`, `benchmark`, `step`, `environment` or `chart`; must match the directory | +| `kind` | yes | `dataset`, `model`, `recipe`, `benchmark`, `step`, `environment`, `chart` or `annotation`; must match the directory | | `title` | yes | 1 to 200 characters | | `description` | no | at most 4,000 characters | | `card` | no | path of an existing file under `notes/`, written from the project folder, for example `notes/fits/early-fit.md` | @@ -213,7 +221,7 @@ directory) and may not lead outside it through a symbolic link. Any other placeholder is an error, and so is a brace without its partner. Write `{{` and `}}` for literal braces. -## The seven kinds +## The eight kinds The examples below come from one project. References in them point at the other examples, except `environments/cuda-torch`, a second environment not shown. @@ -454,6 +462,102 @@ Example, `charts/final-velocity-ranking.json`: } ``` +### `annotation` + +An annotation task says what is recorded about the records of one dataset +(see [Looking inside a product](#looking-inside-a-product) for records). Its +annotations are the lines of `annotations/.jsonl` beside it. A task is +never built: it has no `run`, no product, and the state `none`. Planning a task +plans its dataset in its place. + +| Field | Required | Rule | +| --- | --- | --- | +| `dataset` | yes | reference to `datasets/` | +| `task` | yes | `review`, `class`, `tags`, `text`, `boxes`, `spans` or `segments` | +| `vocabulary` | for `class`, `tags`, `boxes`, `spans` and `segments`; not allowed for `review` and `text` | 1 to 500 different **terms**, each 1 to 200 characters without control characters | + +`earlier_work` is not allowed here. `card` is where the guide for the people +and agents who annotate is written. + +What an annotation's `value` is, by task, and which records it may describe: + +| Task | `value` | Records of kind | +| --- | --- | --- | +| `review` | always null; the state is the decision | any but `file` | +| `class` | one term | any but `file` | +| `tags` | a list of different terms, possibly empty | any but `file` | +| `text` | a string of at most 64 KiB in UTF-8: a caption, a transcript, a summary | any but `file` | +| `boxes` | a list of `{"term", "x", "y", "w", "h"}`, numbers in pixels of the image; `x` and `y` at least 0, `w` and `h` above 0, the box inside the image | `image` | +| `spans` | a list of `{"term", "start", "end"}`, whole numbers of characters (code points) of the text; 0 ≤ `start` < `end` ≤ the text's length | `text` | +| `segments` | a list of `{"term", "start", "end"}` with an optional `"text"` (a string of at most 64 KiB), numbers of seconds; 0 ≤ `start` < `end` ≤ the sound's length | `audio` | + +A list holds at most 1,000 items, and an item no other key. The value may be +null in any state but `accepted`. The record's kind, an image's size, a text's +length and a sound's length are known only from the dataset's product, so the +folder check cannot apply those rules; Tuldok applies them when an annotation +is made. + +Example, `annotations/scene-quality.json`: + +```json +{ + "format": "tuldok_definition_v1", + "kind": "annotation", + "title": "Scene quality", + "card": "notes/annotating/scene-quality.md", + "dataset": "datasets/sinusoidal-v1", + "task": "class", + "vocabulary": ["clean", "noisy", "broken"] +} +``` + +#### The annotations file + +`annotations/.jsonl` holds the annotations of task ``, one JSON +object per line, one line per record. A record with no line is not annotated. +The keys, in this order: + +| Key | Required | Rule | +| --- | --- | --- | +| `record` | yes | the record's id: 1 to 600 characters, no control characters; each record once | +| `sha256` | yes | the SHA-256 of the record's content when it was annotated (64 lowercase hexadecimal characters), or null | +| `state` | yes | `draft`, `accepted`, `needs-work` or `rejected` | +| `value` | yes | as the task says, or null | +| `note` | no | a string of at most 4,000 characters | +| `by` | yes | `owner`, or `agent:` followed by 1 to 80 characters (the agent credential's name, cut) | +| `at` | yes | a real UTC time, `YYYY-MM-DDTHH:MM:SSZ` | +| `from` | no | an object of at most 2 KiB, written compact, saying what suggested the value; kept as it is | + +The file is written in one exact form, so that Git shows one changed line per +changed annotation: + +- lines sorted by `record`, comparing the bytes of its UTF-8; +- each line written compact (`,` and `:` with no spaces), with characters + other than ASCII written as themselves rather than as `\u` escapes, the keys + in the order above and the keys of a `boxes`, `spans` or `segments` item in + the order of the table of tasks; +- each line ending with `\n`, the last one included. + +A file with no line left is deleted when it is saved. The JSON rules above +apply to each line: no repeated key, no `NaN` or `Infinity`, and no escaped +half of a surrogate pair. + +The check reads every line. A line that is not such an object, a value the task +does not allow, a record that an earlier line has, and a line whose record +does not sort after the one above it are errors; a term outside the +vocabulary is a warning, so that a term can be removed from a vocabulary +while annotations still use it. Each problem names its line (`line `): the +first 20 of a file, then one problem counting the rest. A file of annotations +is not checked while its task has errors. + +Example, `annotations/scene-quality.jsonl`: + +``` +{"record":"scene-0001","sha256":"9f2c0e5d1b8a7f6e5d4c3b2a19087f6e5d4c3b2a19087f6e5d4c3b2a19087f6e","state":"accepted","value":"clean","by":"owner","at":"2026-11-13T10:02:11Z"} +{"record":"scene-0002","sha256":null,"state":"rejected","value":null,"note":"blurry","by":"owner","at":"2026-11-13T10:02:40Z"} +{"record":"scene-0003","sha256":null,"state":"draft","value":"noisy","by":"agent:helper","at":"2026-11-13T10:05:02Z"} +``` + ## Results files `results/.csv` is the summary of benchmark `benchmarks/.json`, which @@ -517,6 +621,7 @@ pilot-dense-k1,velocity_error_final,cells_per_metre=8,4,0,0.195,0.175,0.129,0.27 | a benchmark subject's `recipe` | `subject:` | | a benchmark's `cases.dataset` | `cases` | | a chart's `benchmark` | `benchmark` | + | an annotation task's `dataset` | `dataset` | Two more fields of a recipe are edges with a role, shown in a definition's uses and used-by, but are not uses in this sense: they may run both ways, @@ -529,7 +634,8 @@ pilot-dense-k1,velocity_error_final,cells_per_metre=8,4,0,0.195,0.175,0.129,0.27 4. A chart's `metric`, `metric_x`, `subjects` and `group` exist in its benchmark. 5. Code paths exist under the code root (see the `run` block). -6. Every results file has its benchmark and follows the rules above. +6. Every results file has its benchmark and follows the rules above. Every + file of annotations has its task and follows the rules of its task. 7. A recipe's `group` is a group of `tuldok.json`; a group's `parent` is another group and no group is its own ancestor; a recipe is never derived from or compared with itself; following `derived_from` never comes back to where it @@ -554,7 +660,7 @@ at least one error, and 2 for a usage error such as an unknown option. Every problem is reported; the check does not stop at the first. A problem has a severity (`error` or `warning`), the file's path relative to the project folder, a JSON pointer to the field (empty for a problem with the whole file; `line ` -in a results file), and one sentence. Text output prints one line per problem, +in a results file or a file of annotations), and one sentence. Text output prints one line per problem, with the parts separated by two spaces and `-` for an empty pointer, sorted by path and pointer, then a count: @@ -567,11 +673,16 @@ warning results/dense-development-240.csv - The results file does not end wit With `--json` the object is `{"folder", "ok", "errors", "warnings", "problems"}`, each problem being `{"severity", "path", "pointer", "message"}`. -There are three warnings; every other problem is an error: +These are warnings; every other problem is an error: - a code path that does not exist, in a definition with `earlier_work`; - a results file without a final line end; -- a results file that is not checked because its benchmark has errors. +- a results file that is not checked because its benchmark has errors; +- in a file of annotations: a term that is not in the task's vocabulary (one + warning per term, saying how many annotations use it and on which lines), a + blank line, a line not written in the exact form below, a missing final line + end, and a file with no lines; +- a file of annotations that is not checked because its task has errors. One mistake is reported once. A reference into the wrong directory is reported by the field's own rule and not again as a missing definition, and a chart is not diff --git a/docs/plans/definition-first-projects/spec-d4.md b/docs/plans/definition-first-projects/spec-d4.md index 278b42cb..94264dba 100644 --- a/docs/plans/definition-first-projects/spec-d4.md +++ b/docs/plans/definition-first-projects/spec-d4.md @@ -177,3 +177,22 @@ D4a first; D4b and D4c after it; D4d last. `docs/contracts/project-folder.md` is ## 10. Out of scope Suggestions from a model and generation (phase 5); the history of one annotation (Git has it); several people's annotations of one record side by side and agreement between them; export to COCO and other formats; annotating arrays beyond the tasks that fit any kind; polygons, masks, keypoints and 3D boxes; importing from a URL. + +## As built + +### D4a, the task and the file of lines + +What differs from the text above, and what was chosen where it was silent. + +- **A term that is not in the vocabulary is a warning in `check` and an error in an edit.** Section 2 lists it among a line's problems and also calls a removed term a warning; in a folder the two cannot be told apart. `check` warns once per term, with how many annotations use it and up to 20 line numbers. `annotations.validate`, which edits go through, refuses it. +- **Form and content are separate.** A line whose content is right but which is not written exactly as Tuldok writes it (key order, spacing, escapes, the form of a number), a blank line, a missing final newline and an empty file are warnings. A wrong value, a duplicate record and lines out of order are errors. A file with no problem at all is written back byte for byte. +- **The cap of 20 problems per file** counts errors and warnings together; one more problem counts the rest, and is an error if any of the rest is. +- **Bounds the text did not give:** at most 1,000 boxes, spans or segments in one annotation; a segment's `text` at most 64 KiB; `note` and `from` may be absent but not null; `agent:` is followed by 1 to 80 characters; a term holds no control character. The 64 KiB of a `text` value are UTF-8 bytes; the 2 KiB of `from` are of its compact form. +- **Inside an item** the keys are written in the order `term`, `x`, `y`, `w`, `h`, `start`, `end`, `text`. +- **A line file whose task has errors** is not checked and says so, as a results file whose benchmark has errors does. +- **The edge** from a task to its dataset has the role `dataset`. Planning a task plans its dataset and says so in the plan's notes; a task is never a step. +- **The store,** for now, neither lists nor refuses a task's line file: its lines reach the database in D4b. A line file without its task sends the open to `check`, which refuses it. Removing a task today would leave its line file behind; D4b refuses that removal. +- **The fixture project of the tests** gained a task and its lines, since a test requires a definition of every kind; three tests that count definitions moved from 12 to 13. +- **Checked in review** with annotations generated at random: 400 of each task, with ids holding `/`, `!`, non-Latin letters and upper case, values holding quotes, backslashes, line separators and emoji, written and read back equal, byte for byte and in order; 3,000 corrupted files read without an error escaping; 100,000 lines written in 0.2 s and read and checked in 1.4 s (16 MiB). +- **Tests:** `tests/test_tuldok_project_annotations.py`, 22; project suite 632; agent interface 43 (4 skipped). The catalog profile's digest is unchanged. +- **Not verified:** the editor's list of kinds in a browser. diff --git a/static/project-workspace/editor.js b/static/project-workspace/editor.js index 0763145a..a1ed5bd0 100644 --- a/static/project-workspace/editor.js +++ b/static/project-workspace/editor.js @@ -16,8 +16,8 @@ window.LabEditor = (() => { const { sect, modelState } = S.parts; const isObject = v => !!v && typeof v === 'object' && !Array.isArray(v); const button = (cls, text, key, onClick) => { const b = h('button', cls, text); b.type = 'button'; if (key) b.dataset.key = key; if (onClick) b.addEventListener('click', onClick); return b; }; - const KIND_ORDER = ['recipe', 'dataset', 'model', 'step', 'benchmark', 'chart', 'environment']; - const KIND_TITLE = { recipe: 'Recipes', dataset: 'Datasets', model: 'Models', step: 'Steps', benchmark: 'Benchmarks', chart: 'Charts', environment: 'Environments' }; + const KIND_ORDER = ['recipe', 'dataset', 'annotation', 'model', 'step', 'benchmark', 'chart', 'environment']; + const KIND_TITLE = { recipe: 'Recipes', dataset: 'Datasets', model: 'Models', step: 'Steps', benchmark: 'Benchmarks', chart: 'Charts', environment: 'Environments', annotation: 'Annotation tasks' }; // ---- Page memory ------------------------------------------------------------ const buffers = new Map(); // reference -> { text, base }: typed and not kept yet diff --git a/tests/fixtures/tuldok_project/minimal/project/annotations/wave-quality.json b/tests/fixtures/tuldok_project/minimal/project/annotations/wave-quality.json new file mode 100644 index 00000000..f1445f83 --- /dev/null +++ b/tests/fixtures/tuldok_project/minimal/project/annotations/wave-quality.json @@ -0,0 +1,10 @@ +{ + "format": "tuldok_definition_v1", + "kind": "annotation", + "title": "Wave scene quality", + "description": "Whether each scene looks like a clean wave.", + "card": "notes/decisions.md", + "dataset": "datasets/waves", + "task": "class", + "vocabulary": ["clean", "noisy"] +} diff --git a/tests/fixtures/tuldok_project/minimal/project/annotations/wave-quality.jsonl b/tests/fixtures/tuldok_project/minimal/project/annotations/wave-quality.jsonl new file mode 100644 index 00000000..ab11d565 --- /dev/null +++ b/tests/fixtures/tuldok_project/minimal/project/annotations/wave-quality.jsonl @@ -0,0 +1,2 @@ +{"record":"scene-001","sha256":null,"state":"accepted","value":"clean","by":"owner","at":"2026-11-13T10:02:11Z"} +{"record":"scene-002","sha256":null,"state":"draft","value":"noisy","note":"ripples at the edge","by":"agent:helper","at":"2026-11-13T10:03:00Z"} diff --git a/tests/test_tuldok_project_annotations.py b/tests/test_tuldok_project_annotations.py new file mode 100644 index 00000000..af7f07d4 --- /dev/null +++ b/tests/test_tuldok_project_annotations.py @@ -0,0 +1,371 @@ +"""Annotation tasks and their line files: sections 1 and 2 of spec-d4.md (slice D4a). + +A task of each kind checks; each rule of the task and of a line, broken once, +gives its problem at its line; a file written from the rows it was read into +is the same bytes; lines are ordered and escaped as section 2 says; a line +file without its task is an error; a fresh open of a folder with a task lists +it and its edge; planning a task plans its dataset. Each test works on a copy +of tests/fixtures/tuldok_project/minimal, whose annotations/wave-quality is a +class task on datasets/waves. +""" +import json +import os +from pathlib import Path +import shutil +import sys +import tempfile +import unittest +import uuid + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) + +from tuldok_project import annotations, plan, store # noqa: E402 +from tuldok_project.check import check_folder # noqa: E402 + +REPOSITORY = Path(__file__).resolve().parents[1] +FIXTURE = REPOSITORY / 'tests' / 'fixtures' / 'tuldok_project' / 'minimal' +DATABASE = os.environ.get('TULDOK_DATABASE_URL') +TASK = 'annotations/wave-quality' +AT = '2026-11-13T10:02:11Z' +SHA = '9f' * 32 + +# One sound value per task, and the vocabulary each task's definition carries. +VALUES = { + 'review': None, + 'class': 'cat', + 'tags': ['indoor', 'night'], + 'text': 'a dog on a sofa', + 'boxes': [{'term': 'cat', 'x': 10, 'y': 4, 'w': 80, 'h': 60}], + 'spans': [{'term': 'cat', 'start': 0, 'end': 5}], + 'segments': [{'term': 'speech', 'start': 1.25, 'end': 3.5, 'text': 'hello'}], +} +VOCABULARY = ['cat', 'indoor', 'night', 'speech'] + + +def line(record='a1', **fields): + row = {'record': record, 'sha256': SHA, 'state': 'accepted', 'value': 'cat', 'by': 'owner', 'at': AT} + row.update(fields) + return annotations.encode(row) + + +class FolderCase(unittest.TestCase): + def setUp(self): + directory = tempfile.TemporaryDirectory() + self.addCleanup(directory.cleanup) + self.base = Path(directory.name) / 'minimal' + shutil.copytree(FIXTURE, self.base) + self.folder = self.base / 'project' + + def task(self, name='wave-quality', **fields): + document = {'format': 'tuldok_definition_v1', 'kind': 'annotation', 'title': 'T', + 'dataset': 'datasets/waves', 'task': 'class', 'vocabulary': VOCABULARY} + document.update(fields) + document = {key: value for key, value in document.items() if value is not None} + (self.folder / f'annotations/{name}.json').write_text(json.dumps(document, indent=2) + '\n', encoding='utf-8') + + def lines(self, *texts, name='wave-quality', raw=None): + data = raw if raw is not None else ''.join(text + '\n' for text in texts).encode('utf-8') + (self.folder / f'annotations/{name}.jsonl').write_bytes(data) + + def problems(self): + return [(p.severity, p.path, p.pointer) for p in check_folder(self.folder).problems] + + def assertOnly(self, expected): + report = check_folder(self.folder) + listing = '\n'.join(f' {p.severity} {p.path} {p.pointer!r} {p.message}' for p in report.problems) + self.assertEqual([(p.severity, p.path, p.pointer) for p in report.problems], [expected], listing) + message = report.problems[0].message + self.assertTrue(message.endswith('.'), message) + self.assertNotIn('label', message.lower()) + return message + + +class Tasks(FolderCase): + def test_the_fixture_task_checks(self): + self.assertEqual(self.problems(), []) + + def test_a_task_of_each_kind_checks(self): + for task, value in VALUES.items(): + with self.subTest(task=task): + vocabulary = VOCABULARY if task in annotations.VOCABULARY_TASKS else None + self.task(task=task, vocabulary=vocabulary) + self.lines(line(value=value), line('a2', state='draft', value=None, by='agent:helper', + note='first pass', **{'from': {'model': 'm'}})) + self.assertEqual(self.problems(), []) + + def test_each_rule_of_a_task(self): + cases = [ + ('no dataset', {'dataset': None}, '/dataset'), + ('dataset in another directory', {'dataset': 'recipes/stepper-k1'}, '/dataset'), + ('dataset missing', {'dataset': 'datasets/nowhere'}, '/dataset'), + ('unknown task', {'task': 'polygons'}, '/task'), + ('class needs a vocabulary', {'vocabulary': None}, '/vocabulary'), + ('review takes none', {'task': 'review'}, '/vocabulary'), + ('text takes none', {'task': 'text'}, '/vocabulary'), + ('empty vocabulary', {'vocabulary': []}, '/vocabulary'), + ('repeated term', {'vocabulary': ['cat', 'cat']}, '/vocabulary'), + ('term too long', {'vocabulary': ['x' * 201]}, '/vocabulary/0'), + ('empty term', {'vocabulary': ['']}, '/vocabulary/0'), + ('control character in a term', {'vocabulary': ['a\nb']}, '/vocabulary/0'), + ('too many terms', {'vocabulary': [f't{i}' for i in range(501)]}, '/vocabulary'), + ('no run', {'run': {'command': ['true']}}, '/run'), + ('no earlier_work', {'earlier_work': {'rebuild': 'yes'}}, '/earlier_work'), + ] + self.lines() # no line file problems in the way: an empty file is a warning, removed below + os.remove(self.folder / 'annotations/wave-quality.jsonl') + for name, fields, pointer in cases: + with self.subTest(name): + self.task(**{'task': 'class', 'vocabulary': VOCABULARY, 'dataset': 'datasets/waves', **fields}) + self.assertOnly(('error', 'annotations/wave-quality.json', pointer)) + + def test_a_line_file_without_its_task(self): + self.lines(line(), name='orphan') + message = self.assertOnly(('error', 'annotations/orphan.jsonl', '')) + self.assertIn('annotations/orphan.json', message) + + def test_other_files_are_refused_in_annotations(self): + (self.folder / 'annotations/notes.txt').write_text('x') + self.assertOnly(('error', 'annotations/notes.txt', '')) + + def test_line_files_belong_to_annotations_only(self): + (self.folder / 'datasets/waves.jsonl').write_text(line() + '\n') + self.assertOnly(('error', 'datasets/waves.jsonl', '')) + + def test_a_task_with_errors_leaves_its_lines_unchecked(self): + self.task(task='polygons') + self.lines('not json') + self.assertEqual(self.problems(), [('error', 'annotations/wave-quality.json', '/task'), + ('warning', 'annotations/wave-quality.jsonl', '')]) + + +class Lines(FolderCase): + """Each rule of section 2 broken once, as line 2 after a sound line 1.""" + + def broken(self, text, severity='error', pointer='line 2', task='class', vocabulary=VOCABULARY): + self.task(task=task, vocabulary=vocabulary) + self.lines(line('a0', value=VALUES[task]), text) + return self.assertOnly((severity, 'annotations/wave-quality.jsonl', pointer)) + + def test_each_rule_of_a_line(self): + long_record = 'r' * 601 + cases = [ + ('not JSON', '{"record":', {}), + ('not an object', '["a1"]', {}), + ('a key twice', '{"record":"a1","record":"a2"}', {}), + ('NaN', line()[:-1] + ',"from":{"x":NaN}}', {}), + ('unknown key', line()[:-1] + ',"extra":1}', {}), + ('missing key', line().replace(',"sha256":"' + SHA + '"', ''), {}), + ('record too long', line(long_record), {}), + ('record with a control character', line('a\x01'), {}), + ('record empty', line(''), {}), + ('sha256 malformed', line(sha256='ABC'), {}), + ('state unknown', line(state='done'), {}), + ('accepted without a value', line(value=None), {}), + ('review with a value', line(value='cat'), {'task': 'review', 'vocabulary': None}), + ('class value not a string', line(value=['cat']), {}), + ('tags repeated', line(value=['indoor', 'indoor']), {'task': 'tags'}), + ('tags not a list', line(value='indoor'), {'task': 'tags'}), + ('text too long', line(value='x' * (64 * 1024 + 1)), {'task': 'text', 'vocabulary': None}), + ('box with no width', line(value=[{'term': 'cat', 'x': 0, 'y': 0, 'w': 0, 'h': 5}]), {'task': 'boxes'}), + ('box left of the image', line(value=[{'term': 'cat', 'x': -1, 'y': 0, 'w': 2, 'h': 5}]), {'task': 'boxes'}), + ('box missing h', line(value=[{'term': 'cat', 'x': 0, 'y': 0, 'w': 2}]), {'task': 'boxes'}), + ('span backwards', line(value=[{'term': 'cat', 'start': 5, 'end': 5}]), {'task': 'spans'}), + ('span in fractions', line(value=[{'term': 'cat', 'start': 0.5, 'end': 5}]), {'task': 'spans'}), + ('span with text', line(value=[{'term': 'cat', 'start': 0, 'end': 5, 'text': 'x'}]), {'task': 'spans'}), + ('segment backwards', line(value=[{'term': 'speech', 'start': 2, 'end': 1}]), {'task': 'segments'}), + ('segment text not a string', line(value=[{'term': 'speech', 'start': 0, 'end': 1, 'text': 3}]), + {'task': 'segments'}), + ('note too long', line(note='n' * 4001), {}), + ('note null', line()[:-1] + ',"note":null}', {}), + ('by an id', line(by='credential-1234'), {}), + ('by an agent with no label', line(by='agent:'), {}), + ('by an agent label too long', line(by='agent:' + 'x' * 81), {}), + ('at not a real time', line(at='2026-02-30T10:00:00Z'), {}), + ('at not UTC', line(at='2026-11-13T10:02:11+01:00'), {}), + ('from not an object', line(**{'from': 'model'}), {}), + ('from too large', line(**{'from': {'x': 'y' * 2048}}), {}), + ('a lone surrogate', line(note='x').replace('"x"', '"\\ud800"'), {}), + ('duplicate record', line('a0'), {}), + ('out of order', line('A'), {}), + ] + for name, text, task in cases: + with self.subTest(name): + self.broken(text, **task) + + def test_warnings(self): + cases = [ + ('a term not in the vocabulary', line(value='dog'), 'line 2'), + ('a blank line', '', 'line 2'), + ('another form', line().replace(',', ', ', 1), 'line 2'), + ('keys in another order', '{"sha256":"' + SHA + '","record":"a1","state":"accepted","value":"cat",' + '"by":"owner","at":"' + AT + '"}', 'line 2'), + ('ASCII escapes', line(note='é').replace('é', '\\u00e9'), 'line 2'), + ] + for name, text, pointer in cases: + with self.subTest(name): + self.broken(text, 'warning', pointer) + + def test_a_term_removed_from_the_vocabulary_counts_its_uses(self): + self.task(vocabulary=['cat', 'noisy']) + self.lines(line('a1', value='dog'), line('a2'), line('a3', value='dog')) + message = self.assertOnly(('warning', 'annotations/wave-quality.jsonl', 'line 1')) + self.assertIn("'dog'", message) + self.assertIn('2 annotations use it (lines 1, 3)', message) + + def test_the_file_as_a_whole(self): + self.task() + self.lines(raw=line().encode('utf-8')) + self.assertOnly(('warning', 'annotations/wave-quality.jsonl', 'line 1')) # no final line end + self.lines(raw=b'') + self.assertOnly(('warning', 'annotations/wave-quality.jsonl', '')) # no line at all + self.lines(raw=b'\xff\n') + self.assertOnly(('error', 'annotations/wave-quality.jsonl', '')) # not UTF-8 + + def test_the_first_twenty_then_a_count(self): + self.task() + self.lines(*[line(f'a{i:02}', state='done') for i in range(25)]) + report = check_folder(self.folder) + pointers = [p.pointer for p in report.problems] + self.assertEqual(len(pointers), 21) + self.assertEqual(sorted(pointers[1:], key=lambda p: int(p.split()[1])), + [f'line {n}' for n in range(1, 21)]) + self.assertEqual(report.problems[0].pointer, '') + self.assertIn('5 more problems', report.problems[0].message) + + +class Writing(unittest.TestCase): + def test_a_well_formed_file_is_written_back_byte_for_byte(self): + raw = ''.join(text + '\n' for text in [ + '{"record":"a1","sha256":"' + SHA + '","state":"rejected","value":null,"note":"blurry","by":"owner","at":"' + AT + '"}', + '{"record":"a2","sha256":null,"state":"accepted","value":"cat","by":"owner","at":"' + AT + '"}', + '{"record":"a3","sha256":null,"state":"accepted","value":["indoor","night"],"by":"owner","at":"' + AT + '"}', + '{"record":"a4","sha256":null,"state":"draft","value":"un chien \\"Rex\\"\\n sur le canapé ✓","by":"agent:helper","at":"' + AT + '","from":{"model":"m","score":0.5}}', + '{"record":"a5","sha256":null,"state":"accepted","value":[{"term":"cat","x":10,"y":4.5,"w":80,"h":60}],"by":"owner","at":"' + AT + '"}', + '{"record":"a6","sha256":null,"state":"accepted","value":[{"term":"cat","start":0,"end":5}],"by":"owner","at":"' + AT + '"}', + '{"record":"a7","sha256":null,"state":"accepted","value":[{"term":"speech","start":1.25,"end":3.5,"text":"hello"}],"by":"owner","at":"' + AT + '"}', + ]).encode('utf-8') + for task in annotations.TASKS: + parsed = annotations.read(raw, task, VOCABULARY) + self.assertEqual(len(parsed.rows), 7) + self.assertEqual(annotations.write(row for _, row in parsed.rows), raw) + + def test_order_and_escaping(self): + rows = [{'record': record, 'sha256': None, 'state': 'draft', 'value': None, 'by': 'owner', 'at': AT, + 'note': 'tab\there "quoted" \\ é 
 😀'} + for record in ('é', 'b', '😀', 'Z', 'a', '￿', 'a b')] + rows[0]['from'] = None # absent + data = annotations.write(rows) + lines = data.decode('utf-8').split('\n') + self.assertEqual(lines[-1], '') + records = [json.loads(text)['record'] for text in lines[:-1]] + self.assertEqual(records, ['Z', 'a', 'a b', 'b', 'é', '￿', '😀']) + self.assertEqual([record.encode('utf-8') for record in records], + sorted(record.encode('utf-8') for record in records)) + first = lines[0] + self.assertTrue(first.startswith('{"record":"Z","sha256":null,"state":"draft","value":null,"note":')) + self.assertTrue(first.endswith(',"by":"owner","at":"' + AT + '"}')) + self.assertIn('"tab\\there \\"quoted\\" \\\\ é 
 😀"', first) + self.assertNotIn('"from"', data.decode('utf-8')) + self.assertNotIn(', ', first.split('"note"')[0]) + self.assertEqual(annotations.write([]), b'') + parsed = annotations.read(data, 'review', []) + self.assertEqual(parsed.problems, []) + + def test_an_item_is_written_in_its_key_order(self): + row = {'at': AT, 'by': 'owner', 'value': [{'h': 2, 'w': 3, 'term': 'cat', 'y': 1, 'x': 0}], + 'state': 'accepted', 'sha256': None, 'record': 'r'} + self.assertEqual(annotations.encode(row), + '{"record":"r","sha256":null,"state":"accepted",' + '"value":[{"term":"cat","x":0,"y":1,"w":3,"h":2}],"by":"owner","at":"' + AT + '"}') + + +class Records(unittest.TestCase): + """What only the record can tell: its kind, an image's size, a text's length, a sound's length.""" + + def errors(self, task, value, **record): + row = {'record': 'r', 'sha256': None, 'state': 'accepted', 'value': value, 'by': 'owner', 'at': AT} + return annotations.validate(task, VOCABULARY, row, **record) + + def test_kinds(self): + self.assertEqual(annotations.record_kinds('boxes'), ('image',)) + self.assertEqual(annotations.record_kinds('spans'), ('text',)) + self.assertEqual(annotations.record_kinds('segments'), ('audio',)) + for task in ('review', 'class', 'tags', 'text'): + self.assertNotIn('file', annotations.record_kinds(task)) + self.assertIn('mesh', annotations.record_kinds(task)) + self.assertEqual(self.errors('class', 'cat', kind='image'), []) + self.assertEqual(len(self.errors('class', 'cat', kind='file')), 1) + self.assertEqual(len(self.errors('boxes', VALUES['boxes'], kind='text')), 1) + + def test_bounds(self): + self.assertEqual(self.errors('boxes', VALUES['boxes'], kind='image', size=(90, 64)), []) + self.assertEqual(len(self.errors('boxes', VALUES['boxes'], kind='image', size=(89, 64))), 1) + self.assertEqual(self.errors('spans', VALUES['spans'], kind='text', length=5), []) + self.assertEqual(len(self.errors('spans', VALUES['spans'], kind='text', length=4)), 1) + self.assertEqual(self.errors('segments', VALUES['segments'], kind='audio', duration=3.5), []) + self.assertEqual(len(self.errors('segments', VALUES['segments'], kind='audio', duration=3.4)), 1) + + def test_a_term_outside_the_vocabulary_is_an_error_for_an_edit(self): + self.assertEqual(len(self.errors('class', 'dog')), 1) + self.assertEqual(annotations.value_problems('tags', VOCABULARY, 'accepted', ['dog', 'cat', 'ant']), + ([], ['ant', 'dog'])) + + +class Planning(FolderCase): + def test_planning_a_task_plans_its_dataset(self): + report = check_folder(self.folder) + definitions = {reference: d.document for reference, d in report.definitions.items()} + result = plan.make_plan(definitions, [TASK]) + self.assertEqual(result['targets'], ['datasets/waves']) + self.assertIn(f'{TASK} annotates the records of datasets/waves, which is planned in its place.', + result['notes']) + self.assertNotIn('annotation', {step['kind'] for step in result['steps']}) + self.assertEqual(result['steps'][-1]['reference'], 'datasets/waves') + everything = plan.make_plan(definitions, [], every=True) + self.assertNotIn(TASK, [step['reference'] for step in everything['steps']]) + + +@unittest.skipUnless(DATABASE, 'TULDOK_DATABASE_URL is not set; database tests need a disposable cluster.') +class Opening(FolderCase): + def setUp(self): + super().setUp() + self.project_id = uuid.uuid4().hex + project_file = self.folder / 'tuldok.json' + document = json.loads(project_file.read_text(encoding='utf-8')) + document['id'] = self.project_id + project_file.write_text(json.dumps(document, indent=2) + '\n', encoding='utf-8') + self.addCleanup(store.drop_project, self.project_id) + + def open(self): + project = store.open_project(self.folder) + self.addCleanup(project.close) + return project + + def test_a_fresh_open_lists_the_task_and_its_edge(self): + project = self.open() + rows = project.definitions(kind='annotation') + self.assertEqual([(row['reference'], row['state']) for row in rows], [(TASK, 'none')]) + self.assertIn({'from': TASK, 'to': 'datasets/waves', 'role': 'dataset'}, project.graph()['edges']) + self.assertIn({'reference': TASK, 'role': 'dataset'}, project.definition('datasets/waves')['used_by']) + status = project.status() + self.assertEqual((status['irregular'], status['added'], status['changed']), ([], [], [])) + project.close() + self.assertEqual(self.open().definitions(kind='annotation')[0]['reference'], TASK) # the quick second open + + def test_a_line_file_without_its_task_stops_the_open(self): + self.lines(line(), name='orphan') + with self.assertRaises(store.ProjectError) as caught: + self.open() + self.assertEqual(caught.exception.code, 'invalid') + self.assertIn('annotations/orphan.jsonl', [p.path for p in caught.exception.problems]) + + def test_a_bad_line_stops_the_open(self): + self.lines(line('a1'), line('a0')) + with self.assertRaises(store.ProjectError) as caught: + self.open() + self.assertIn(('annotations/wave-quality.jsonl', 'line 2'), + [(p.path, p.pointer) for p in caught.exception.problems]) + + +if __name__ == '__main__': + unittest.main() diff --git a/tests/test_tuldok_project_charts.py b/tests/test_tuldok_project_charts.py index c35d25c2..32a75b07 100644 --- a/tests/test_tuldok_project_charts.py +++ b/tests/test_tuldok_project_charts.py @@ -310,15 +310,15 @@ def test_one_self_contained_page_with_every_chart(self): self.assertEqual(headings, ['Every metric side by side', 'Rollout error in training order', 'Rollout error by subject', 'Error against time']) details = root.findall('.//details') - self.assertEqual(len(details), 7) + self.assertEqual(len(details), 8) # one per kind self.assertTrue(all(element.get('open') is None for element in details)) sections = [element.text for element in root.iter('h2')] self.assertEqual(sections, ['Charts ', 'Results ', 'Definitions ']) - self.assertIn('12 definitions', page) + self.assertIn('13 definitions', page) self.assertIn('color-scheme: dark', dark) self.assertIn('#171c22', dark) # Where the project stands comes first, then the charts, then the results and the definitions. - self.assertLess(light.index('12 definitions'), light.index('

                            Charts')) + self.assertLess(light.index('13 definitions'), light.index('

                            Charts')) self.assertLess(light.index('

                            Charts'), light.index('

                            Results')) self.assertLess(light.index('

                            Results'), light.index('

                            Definitions')) diff --git a/tests/test_tuldok_project_cli.py b/tests/test_tuldok_project_cli.py index b09d134a..eb6ff970 100644 --- a/tests/test_tuldok_project_cli.py +++ b/tests/test_tuldok_project_cli.py @@ -118,20 +118,21 @@ def test_open_prints_counts_and_time_then_attaches(self): self.assertRegex(lines[0], rf'^Opened Minimal surrogate project \({self.project_id}\) from .* in \d+\.\d\d s\.$') self.assertIn('kind count', lines) self.assertIn('recipe 3', lines) - self.assertIn('total 12', lines) + self.assertIn('total 13', lines) self.assertIn('state count', lines) self.assertIn('cannot-rebuild 1', lines) self.assertTrue(self.schema_exists()) again = self.run_json('open', self.folder) self.assertEqual(again['project_id'], self.project_id) self.assertEqual(again['kinds']['recipe'], 3) - self.assertEqual(again['states'], {'cannot-rebuild': 1, 'none': 5, 'not-built': 5, 'not-set-up': 1}) + self.assertEqual(again['states'], {'cannot-rebuild': 1, 'none': 6, 'not-built': 5, 'not-set-up': 1}) self.assertIsInstance(again['seconds'], float) def test_list(self): lines = self.run_ok('list', self.folder).splitlines() - self.assertEqual(len(lines), 12) - self.assertEqual(lines[0].split(None, 2), ['benchmarks/rollout', 'not-built', 'Rollout error']) + self.assertEqual(len(lines), 13) + self.assertEqual(lines[0].split(None, 2), ['annotations/wave-quality', 'none', 'Wave scene quality']) + self.assertEqual(lines[1].split(None, 2), ['benchmarks/rollout', 'not-built', 'Rollout error']) self.assertEqual(len({line.index('not-built') for line in lines if ' not-built ' in line}), 1) # aligned rows = self.run_json('list', self.folder, '--kind', 'recipe') self.assertEqual([row['reference'] for row in rows], @@ -144,8 +145,8 @@ def test_show(self): lines = head.splitlines() self.assertEqual(lines[:4], ['reference datasets/waves', 'title Wave scenes', 'kind dataset', 'state not-built']) - self.assertIn('uses steps/solver input:solver', lines) - self.assertIn('used by recipes/stepper-k1 input:training', lines) + self.assertIn('uses steps/solver input:solver', lines) + self.assertIn('used by recipes/stepper-k1 input:training', lines) self.assertEqual(text, (self.folder / 'datasets' / 'waves.json').read_text(encoding='utf-8')) shown = self.run_json('show', self.folder, 'models/stepper') self.assertEqual(shown['uses'], []) @@ -159,10 +160,10 @@ def test_show_of_a_missing_definition_exits_1(self): def test_graph_and_order(self): nodes, edges = self.run_ok('graph', self.folder).split('\n\n') - self.assertEqual(len(nodes.splitlines()), 12) + self.assertEqual(len(nodes.splitlines()), 13) self.assertIn('recipes/stepper-k2 input:start recipes/stepper-k1', edges.splitlines()) drawn = self.run_json('graph', self.folder) - self.assertEqual(len(drawn['nodes']), 12) + self.assertEqual(len(drawn['nodes']), 13) self.assertEqual(len(drawn['edges']), len(edges.splitlines())) order = [line.split() for line in self.run_ok('graph', self.folder, '--order').splitlines()] references = [reference for reference, _ in order] @@ -247,7 +248,7 @@ def test_a_moved_folder_needs_rebind(self): done = run('list', moved / 'project') self.assertEqual(done.returncode, 1) self.assertIn('rebind', done.stderr) - self.assertEqual(len(self.run_json('list', moved / 'project', '--rebind')), 12) + self.assertEqual(len(self.run_json('list', moved / 'project', '--rebind')), 13) def test_open_elsewhere_is_busy_and_every_command_releases_the_lock(self): for arguments in (('open',), ('list',), ('show', 'models/stepper'), ('graph',), ('status',), ('save',)): diff --git a/tests/test_tuldok_project_store.py b/tests/test_tuldok_project_store.py index b659c9c7..35010bfe 100644 --- a/tests/test_tuldok_project_store.py +++ b/tests/test_tuldok_project_store.py @@ -29,6 +29,7 @@ DATABASE = os.environ.get('TULDOK_DATABASE_URL') FIXTURE_STATES = { + 'annotations/wave-quality': 'none', # a task is never built (spec-d4.md) 'benchmarks/rollout': 'not-built', # its early-fit subject carries nothing 'charts/rollout-comparison': 'none', 'charts/rollout-progression': 'none', @@ -180,9 +181,9 @@ def test_first_open_imports_every_definition(self): self.assertEqual(summary['project_id'], self.project_id) self.assertEqual(summary['folder'], os.path.realpath(self.folder)) self.assertEqual(summary['code_root'], '../code') - self.assertEqual(summary['kinds'], {'benchmark': 1, 'chart': 4, 'dataset': 1, 'environment': 1, - 'model': 1, 'recipe': 3, 'step': 1}) - self.assertEqual(summary['states'], {'cannot-rebuild': 1, 'none': 5, 'not-built': 5, 'not-set-up': 1}) + self.assertEqual(summary['kinds'], {'annotation': 1, 'benchmark': 1, 'chart': 4, 'dataset': 1, + 'environment': 1, 'model': 1, 'recipe': 3, 'step': 1}) + self.assertEqual(summary['states'], {'cannot-rebuild': 1, 'none': 6, 'not-built': 5, 'not-set-up': 1}) rows = project.definitions() self.assertEqual({row['reference']: row['state'] for row in rows}, FIXTURE_STATES) self.assertEqual([row['reference'] for row in project.definitions(kind='chart')], @@ -198,7 +199,7 @@ def test_first_open_imports_every_definition(self): self.assertIn({'reference': 'benchmarks/rollout', 'role': 'cases'}, shown['used_by']) drawn = project.graph() - self.assertEqual(len(drawn['nodes']), 12) + self.assertEqual(len(drawn['nodes']), 13) self.assertIn({'from': 'recipes/stepper-k2', 'to': 'recipes/stepper-k1', 'role': 'input:start'}, drawn['edges']) self.assertEqual(len(drawn['edges']), len(check.check_folder(self.folder).edges)) order = project.order() @@ -213,7 +214,7 @@ def test_second_open_of_unchanged_folder_does_not_run_the_checker(self): project = self.open() checker.assert_not_called() self.assertEqual(self.dump(), before) - self.assertEqual(len(project.definitions()), 12) + self.assertEqual(len(project.definitions()), 13) def test_changed_added_and_removed_files_are_imported(self): self.close(self.open()) @@ -386,7 +387,8 @@ def test_remove_refused_while_used(self): with self.assertRaises(ProjectError) as caught: self.project.remove_definition('datasets/waves') self.assertEqual(caught.exception.code, 'in-use') - self.assertEqual(caught.exception.references, ['benchmarks/rollout', 'recipes/stepper-k1', 'recipes/stepper-k2']) + self.assertEqual(caught.exception.references, ['annotations/wave-quality', 'benchmarks/rollout', + 'recipes/stepper-k1', 'recipes/stepper-k2']) self.assertEqual(self.dump(), before) def test_removing_a_user_frees_what_it_used(self): diff --git a/tuldok_project/annotations.py b/tuldok_project/annotations.py new file mode 100644 index 00000000..120fedef --- /dev/null +++ b/tuldok_project/annotations.py @@ -0,0 +1,429 @@ +"""Annotations of a dataset's records: what each task allows, and the line file that keeps them. + +Owns sections 1 and 2 of docs/plans/definition-first-projects/spec-d4.md apart +from the task's own schema (schemas/annotation.schema.json): which value each +task allows and on which kinds of record, the rules of one line of +annotations/.jsonl, reading such a file into rows with its problems by +line number, and writing rows back as the file in its one exact form. It is +pure and uses the standard library alone: it opens no file and no database. +A row is a dict with the keys of KEYS (note and from only when present). +""" +from dataclasses import dataclass, field +from datetime import datetime +import json +import math +import re +import unicodedata + +TASKS = ('review', 'class', 'tags', 'text', 'boxes', 'spans', 'segments') +VOCABULARY_TASKS = ('class', 'tags', 'boxes', 'spans', 'segments') +STATES = ('draft', 'accepted', 'needs-work', 'rejected') +RECORD_KINDS = ('text', 'image', 'audio', 'pointcloud', 'mesh', 'array', 'file') # spec-d1's kinds of record +KEYS = ('record', 'sha256', 'state', 'value', 'note', 'by', 'at', 'from') +REQUIRED = ('record', 'sha256', 'state', 'value', 'by', 'at') + +FILE_LIMIT = 64 * 1024 * 1024 # bytes of one line file +RECORD_LIMIT = 600 # characters of a record id +TEXT_LIMIT = 64 * 1024 # UTF-8 bytes of a text task's value, and of a segment's text +NOTE_LIMIT = 4000 # characters +BY_LIMIT = 80 # characters of an agent's label after 'agent:' +FROM_LIMIT = 2048 # UTF-8 bytes of 'from', written compact +ITEM_LIMIT = 1000 # boxes, spans or segments in one annotation +PROBLEM_LIMIT = 20 # line problems reported per file before a count + +# The one kind of record a task needs; the other tasks take any kind but 'file'. +_ONLY_KIND = {'boxes': 'image', 'spans': 'text', 'segments': 'audio'} +# Key order of the objects inside a boxes, spans or segments value. +_ITEM_ORDER = ('term', 'x', 'y', 'w', 'h', 'start', 'end', 'text') +_ITEM_RANK = {key: index for index, key in enumerate(_ITEM_ORDER)} +_ITEM_KEYS = {'boxes': ('term', 'x', 'y', 'w', 'h'), 'spans': ('term', 'start', 'end'), + 'segments': ('term', 'start', 'end')} +_SHA256 = re.compile(r'^[0-9a-f]{64}$') +_AT = re.compile(r'^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$') + + +# ------------------------------------------------------------ the tasks (1) + +def record_kinds(task): + """The kinds of record an annotation under task may describe, in RECORD_KINDS order.""" + if task in _ONLY_KIND: + return (_ONLY_KIND[task],) + return tuple(kind for kind in RECORD_KINDS if kind != 'file') + + +def allows_kind(task, kind): + """True when an annotation under task may describe a record of this kind.""" + return kind in record_kinds(task) + + +def _has_control(text): + return any(unicodedata.category(char) == 'Cc' for char in text) + + +def _number(value): + return isinstance(value, (int, float)) and not isinstance(value, bool) and math.isfinite(value) + + +def _whole(value): + return isinstance(value, int) and not isinstance(value, bool) + + +def _utf8_size(text): + try: + return len(text.encode('utf-8')) + except UnicodeEncodeError: + return None + + +def _items(task, value, vocabulary, unknown, size, length, duration): + """Errors of a boxes, spans or segments value; terms outside the vocabulary are added to unknown.""" + if not isinstance(value, list): + return [f'A {task} value must be a list of objects.'] + if len(value) > ITEM_LIMIT: + return [f'A {task} value holds {len(value)} items; at most {ITEM_LIMIT} are allowed.'] + errors = [] + keys = _ITEM_KEYS[task] + for index, item in enumerate(value): + where = f'Item {index + 1} of the value' + if not isinstance(item, dict): + errors.append(f'{where} must be an object with {", ".join(keys)}.') + continue + allowed = keys + (('text',) if task == 'segments' else ()) + extra = sorted(set(item) - set(allowed)) + missing = [key for key in keys if key not in item] + if extra or missing: + parts = ([f'has the unknown key{"s" if len(extra) > 1 else ""} {", ".join(extra)}'] if extra else []) \ + + ([f'lacks {", ".join(missing)}'] if missing else []) + errors.append(f'{where} {" and ".join(parts)}; it takes {", ".join(allowed)}.') + continue + term = item['term'] + if not isinstance(term, str): + errors.append(f'{where} has a term that is not a string.') + elif term not in vocabulary: + unknown.add(term) + if task == 'boxes': + if not all(_number(item[key]) for key in ('x', 'y', 'w', 'h')): + errors.append(f'{where} must give x, y, w and h as numbers of pixels.') + elif item['x'] < 0 or item['y'] < 0: + errors.append(f'{where} starts outside the image; x and y must be at least 0.') + elif item['w'] <= 0 or item['h'] <= 0: + errors.append(f'{where} must have w and h above zero.') + elif size is not None and (item['x'] + item['w'] > size[0] or item['y'] + item['h'] > size[1]): + errors.append(f'{where} reaches outside the image of {size[0]} by {size[1]} pixels.') + continue + start, end = item['start'], item['end'] + if task == 'spans' and not (_whole(start) and _whole(end)): + errors.append(f'{where} must give start and end as whole numbers of characters.') + elif task == 'segments' and not (_number(start) and _number(end)): + errors.append(f'{where} must give start and end as numbers of seconds.') + elif start < 0 or start >= end: + errors.append(f'{where} must have 0 ≤ start < end; it has start {start} and end {end}.') + elif task == 'spans' and length is not None and end > length: + errors.append(f'{where} ends at {end}, past the text of {length} characters.') + elif task == 'segments' and duration is not None and end > duration: + errors.append(f'{where} ends at {end} seconds, past the sound of {duration} seconds.') + if task == 'segments' and 'text' in item: + text = item['text'] + if not isinstance(text, str): + errors.append(f'{where} has a text that is not a string.') + elif (_utf8_size(text) or 0) > TEXT_LIMIT: + errors.append(f'{where} has a text over {TEXT_LIMIT} bytes.') + return errors + + +def value_problems(task, vocabulary, state, value, *, kind=None, size=None, length=None, duration=None): + """(errors, unknown terms) of one annotation's value under task. + + vocabulary is the task's list of terms (empty for review and text). state + is the annotation's state: only an accepted annotation needs a value. kind + (the record's kind), size ((width, height) of an image), length (code + points of a text) and duration (seconds of a sound) are checked when + given. errors are sentences; unknown is the sorted list of terms the value + uses that the vocabulary does not hold, which the caller reports as it + sees fit (check warns, an edit refuses). + """ + if task not in TASKS: + return [f'{task!r} is not a task; use one of {", ".join(TASKS)}.'], [] + errors, unknown = [], set() + if kind is not None and not allows_kind(task, kind): + errors.append(f'A {task} task does not annotate records of kind {kind!r}; ' + f'it takes {", ".join(record_kinds(task))}.') + terms = set(vocabulary or ()) + if task == 'review': + if value is not None: + errors.append('A review task records no value; write null.') + return errors, [] + if value is None: + if state == 'accepted': + errors.append('An accepted annotation must have a value; give one or choose another state.') + return errors, [] + if task == 'class': + if not isinstance(value, str): + errors.append('A class value must be one term, as a string.') + elif value not in terms: + unknown.add(value) + elif task == 'tags': + if not isinstance(value, list) or not all(isinstance(term, str) for term in value): + errors.append('A tags value must be a list of terms, as strings.') + else: + if len(set(value)) != len(value): + errors.append('A tags value names a term more than once; list each term once.') + unknown.update(term for term in value if term not in terms) + elif task == 'text': + if not isinstance(value, str): + errors.append('A text value must be a string.') + elif (_utf8_size(value) or 0) > TEXT_LIMIT: + errors.append(f'A text value is {_utf8_size(value)} bytes; at most {TEXT_LIMIT} are allowed.') + else: + errors.extend(_items(task, value, vocabulary or (), unknown, size, length, duration)) + return errors, sorted(unknown) + + +# ------------------------------------------------------------- a line (2) + +def row_problems(row): + """The errors of a row's keys and of every field but value, as sentences (value_problems judges value).""" + if not isinstance(row, dict): + return ['The line must be one JSON object.'] + errors = [] + extra = [key for key in row if key not in KEYS] + if extra: + errors.append(f'Remove the unknown key{"s" if len(extra) > 1 else ""} {", ".join(extra)}; ' + f'a line takes {", ".join(KEYS)}.') + missing = [key for key in REQUIRED if key not in row] + if missing: + errors.append(f'Add the required key{"s" if len(missing) > 1 else ""} {", ".join(missing)}.') + record = row.get('record') + if 'record' in row and not (isinstance(record, str) and 1 <= len(record) <= RECORD_LIMIT + and not _has_control(record)): + errors.append(f'The key record must be a record id of 1 to {RECORD_LIMIT} characters without control characters.') + sha = row.get('sha256') + if sha is not None and not (isinstance(sha, str) and _SHA256.fullmatch(sha)): + errors.append('The key sha256 must be 64 lowercase hexadecimal characters, or null.') + if 'state' in row and row['state'] not in STATES: + errors.append(f'The key state must be one of {", ".join(STATES)}.') + if 'note' in row and not (isinstance(row['note'], str) and len(row['note']) <= NOTE_LIMIT): + errors.append(f'The key note must be a string of at most {NOTE_LIMIT} characters; leave the key out for none.') + by = row.get('by') + if 'by' in row and not (by == 'owner' or (isinstance(by, str) and by.startswith('agent:') + and 1 <= len(by) - len('agent:') <= BY_LIMIT + and not _has_control(by))): + errors.append(f"The key by must be 'owner', or 'agent:' followed by 1 to {BY_LIMIT} characters.") + at = row.get('at') + if 'at' in row and not (isinstance(at, str) and _AT.fullmatch(at) and _real_time(at)): + errors.append('The key at must be a real UTC time written YYYY-MM-DDTHH:MM:SSZ.') + if 'from' in row: + written = _compact(row['from']) if isinstance(row['from'], dict) else None + size = _utf8_size(written) if written is not None else None + if size is None or size > FROM_LIMIT: + errors.append(f'The key from must be an object of at most {FROM_LIMIT} bytes written compact; ' + 'leave the key out for none.') + if not errors and _utf8_size(_compact(row)) is None: + errors.append('The line holds an escaped half of a surrogate pair (\\ud800 to \\udfff alone); ' + 'write the character itself.') + return errors + + +def _real_time(text): + try: + datetime.strptime(text, '%Y-%m-%dT%H:%M:%SZ') + except ValueError: + return False + return True + + +def validate(task, vocabulary, row, *, kind=None, size=None, length=None, duration=None): + """Every error of one row under task, terms outside the vocabulary included, as sentences.""" + errors = row_problems(row) + if isinstance(row, dict) and 'value' in row: + found, unknown = value_problems(task, vocabulary, row.get('state'), row['value'], + kind=kind, size=size, length=length, duration=duration) + errors += found + errors += [f'The term {term!r} is not in the vocabulary of the task.' for term in unknown] + return errors + + +# --------------------------------------------------------- writing a file + +def _compact(value): + return json.dumps(value, ensure_ascii=False, separators=(',', ':'), allow_nan=False) + + +def _ordered_value(value): + """value with the keys of the objects in a boxes, spans or segments list in their written order.""" + if not isinstance(value, list): + return value + ordered = [] + for item in value: + if isinstance(item, dict): + item = {key: item[key] for key in sorted(item, key=lambda key: _ITEM_RANK.get(key, len(_ITEM_RANK)))} + ordered.append(item) + return ordered + + +def encode(row): + """One row as its line, without the line end: keys in KEYS order, compact, not ASCII-escaped. + + note and from are left out when absent or None. + """ + ordered = {} + for key in KEYS: + if key in row and not (key in ('note', 'from') and row[key] is None): + ordered[key] = _ordered_value(row[key]) if key == 'value' else row[key] + return _compact(ordered) + + +def sort_key(record): + """The order of lines: the record id's UTF-8 bytes.""" + return record.encode('utf-8') + + +def write(rows): + """The bytes of a line file holding rows: sorted by record, each line ending with a line end. + + Rows must be valid (validate) and their records different; an empty rows + gives b'' (a file with no line left is deleted on save, not written). + """ + ordered = sorted(rows, key=lambda row: sort_key(row['record'])) + return ''.join(encode(row) + '\n' for row in ordered).encode('utf-8') + + +# --------------------------------------------------------- reading a file + +@dataclass(frozen=True) +class LineProblem: + """One problem of a line file: severity 'error' or 'warning'; line is its number, or None for the file.""" + severity: str + line: int | None + message: str + + @property + def pointer(self): + """The pointer check reports: 'line ', or '' for the whole file.""" + return '' if self.line is None else f'line {self.line}' + + +@dataclass +class Parsed: + """What read() found. + + rows holds (line number, row) for every line that names a record soundly + and is the first for its record, in file order, including lines whose + value has an error (invalid holds their numbers). unknown maps each term + outside the vocabulary to the numbers of the lines that use it. + problems holds every problem, in line order; reported() caps them. + """ + rows: list = field(default_factory=list) + invalid: set = field(default_factory=set) + unknown: dict = field(default_factory=dict) + problems: list = field(default_factory=list) + + def reported(self, limit=PROBLEM_LIMIT): + """The first limit problems, then one that counts the rest (an error when any of them is).""" + if len(self.problems) <= limit: + return list(self.problems) + rest = self.problems[limit:] + severity = 'error' if any(problem.severity == 'error' for problem in rest) else 'warning' + return self.problems[:limit] + [LineProblem( + severity, None, f'{len(rest)} more problem{"s" if len(rest) > 1 else ""} in this file ' + f'{"are" if len(rest) > 1 else "is"} not listed; fix the ones above and check again.')] + + +def _unique_object(pairs): + seen = {} + for key, value in pairs: + if key in seen: + raise ValueError(f'the key {key!r} appears twice in one object') + seen[key] = value + return seen + + +def _refuse_constant(name): + raise ValueError(f'{name} is not allowed') + + +def _finite_float(text): + value = float(text) + if not math.isfinite(value): + raise ValueError(f'the number {text} is too large to represent') + return value + + +def _decode_line(text): + """The JSON value of one line, or raise ValueError with a fragment saying why not.""" + try: + return json.loads(text, object_pairs_hook=_unique_object, + parse_constant=_refuse_constant, parse_float=_finite_float) + except json.JSONDecodeError as exc: + raise ValueError(f'it is not valid JSON ({exc.msg} at column {exc.colno})') from None + + +def read(raw, task, vocabulary): + """Read the bytes of a line file whose task is `task` with this vocabulary; return Parsed. + + Errors: a file that is not UTF-8; a line that is not a JSON object of the + keys of section 2, or whose value its task does not allow; a record that + an earlier line already has; a line whose record does not come after the + one above it. Warnings: a term outside the vocabulary (one per term, + counting its lines); an empty file; a blank line; a missing final line + end; a line not written in the exact form write() gives. + """ + parsed = Parsed() + add = parsed.problems.append + try: + text = raw.decode('utf-8') + except UnicodeDecodeError as exc: + add(LineProblem('error', None, f'The file is not UTF-8 text (bad byte at offset {exc.start}).')) + return parsed + if not text: + add(LineProblem('warning', None, 'The file has no lines; remove it.')) + return parsed + pieces = text.split('\n') + if pieces[-1] == '': + pieces.pop() + else: + add(LineProblem('warning', len(pieces), 'The last line does not end with a line end.')) + seen, previous = {}, None + for number, piece in enumerate(pieces, 1): + if piece.strip() == '': + add(LineProblem('warning', number, 'The line is blank; remove it.')) + continue + try: + row = _decode_line(piece) + except ValueError as exc: + add(LineProblem('error', number, f'The line is not an annotation: {exc}.')) + continue + errors = row_problems(row) + record = row.get('record') if isinstance(row, dict) else None + if errors and not (isinstance(record, str) and 1 <= len(record) <= RECORD_LIMIT and not _has_control(record) + and _utf8_size(record) is not None): + add(LineProblem('error', number, ' '.join(errors))) + continue + if record in seen: + add(LineProblem('error', number, f'The record {record!r} already has line {seen[record]}; ' + 'keep one line per record.')) + continue + seen[record] = number + if previous is not None and sort_key(record) < sort_key(previous): + errors.append(f'The record {record!r} comes before {previous!r} of the line above; ' + 'sort the lines by record.') + previous = record + if 'value' in row: + found, unknown = value_problems(task, vocabulary, row.get('state'), row['value']) + errors += found + for term in unknown: + parsed.unknown.setdefault(term, []).append(number) + parsed.rows.append((number, row)) + if errors: + parsed.invalid.add(number) + add(LineProblem('error', number, ' '.join(errors))) + elif encode(row) != piece: + add(LineProblem('warning', number, 'The line is not written in the form Tuldok writes ' + '(key order, spacing or escaping); saving rewrites it.')) + for term, lines in parsed.unknown.items(): + shown = ', '.join(map(str, lines[:PROBLEM_LIMIT])) + (', …' if len(lines) > PROBLEM_LIMIT else '') + count = f'{len(lines)} annotation{"s" if len(lines) > 1 else ""} use{"" if len(lines) > 1 else "s"}' + add(LineProblem('warning', lines[0], f'The term {term!r} is not in the vocabulary of the task; ' + f'{count} it (line{"s" if len(lines) > 1 else ""} {shown}).')) + parsed.problems.sort(key=lambda problem: (problem.line or 0, problem.severity)) + return parsed diff --git a/tuldok_project/charts.py b/tuldok_project/charts.py index aa9d1de6..9faae1aa 100644 --- a/tuldok_project/charts.py +++ b/tuldok_project/charts.py @@ -825,7 +825,8 @@ def _comparison_grid(svg, data, y): # =============================================================== report _PLURALS = {'dataset': 'Datasets', 'model': 'Models', 'recipe': 'Recipes', 'benchmark': 'Benchmarks', - 'step': 'Steps', 'environment': 'Environments', 'chart': 'Charts'} + 'step': 'Steps', 'environment': 'Environments', 'chart': 'Charts', + 'annotation': 'Annotation tasks'} _STATE_WORDS = {'cannot-rebuild': 'cannot rebuild', 'needs-work': 'needs work', 'not-built': 'not built', 'not-set-up': 'not set up', 'none': 'no state'} diff --git a/tuldok_project/check.py b/tuldok_project/check.py index 94c2084f..80f80bf4 100644 --- a/tuldok_project/check.py +++ b/tuldok_project/check.py @@ -6,15 +6,16 @@ schemas) nor summary-file content (results.py): kind against directory, cards, placeholders in context, benchmark uniqueness rules, references and named outputs, charts against their benchmark, cycles, paths into the code root -(in definitions and in the code_paths of tuldok.json), and the map's fields +(in definitions and in the code_paths of tuldok.json), the map's fields (spec-w1.md section 1): groups, a recipe's group, derived_from and -compared_with, and map.chart. +compared_with, and map.chart, and each annotations/.jsonl against its +task (spec-d4.md section 2; the rules of a line are annotations.py's). Problems are collected, never raised, so one bad file never hides another. """ from dataclasses import dataclass, field import os -from . import documents, folder as folder_reader, graph, results +from . import annotations, documents, folder as folder_reader, graph, results from .documents import Problem _SEVERITY_ORDER = {'error': 0, 'warning': 1} @@ -74,6 +75,7 @@ def add(severity, path, pointer, message): check_cycles(definitions, add) check_map(project, definitions, add) _check_results(read.results, definitions, unsound, add) + _check_annotations(read.annotations, definitions, unsound, add) problems.sort(key=lambda p: (p.path, p.pointer, _SEVERITY_ORDER.get(p.severity, 2), p.message)) decoded = {reference: d.document for reference, d in definitions.items() if d.document is not None} @@ -424,3 +426,22 @@ def _check_results(files, definitions, unsound, add): continue for severity, pointer, message in results.check_results(file.text, benchmark.document): add(severity, file.path, pointer, message) + + +def _check_annotations(files, definitions, unsound, add): + """Each line file against its task: a file with no task is an error; a task with errors leaves it unchecked.""" + for file in files: + name = file.path[len(f'{folder_reader.ANNOTATIONS}/'):-len(folder_reader.LINES_SUFFIX)] + task = definitions.get(documents.reference(folder_reader.ANNOTATIONS, name)) + if task is None: + add('error', file.path, '', f'There is no {folder_reader.ANNOTATIONS}/{name}.json, the task of these ' + 'annotations; add the task or remove the file.') + continue + if file.text is None or task.document is None: + continue # unreadable: already reported + if task.path in unsound: + add('warning', file.path, '', f'Not checked, because {task.path} has errors; fix those first.') + continue + parsed = annotations.read(file.raw, task.document['task'], task.document.get('vocabulary', [])) + for problem in parsed.reported(): + add(problem.severity, file.path, problem.pointer, problem.message) diff --git a/tuldok_project/documents.py b/tuldok_project/documents.py index f4174780..79a88715 100644 --- a/tuldok_project/documents.py +++ b/tuldok_project/documents.py @@ -28,11 +28,13 @@ 'step': 'steps', 'environment': 'environments', 'chart': 'charts', + 'annotation': 'annotations', } KINDS = {directory: kind for kind, directory in DIRECTORIES.items()} # Which directories each reference-taking field accepts (2.6, 2.7). The keys -# are the edge roles of 2.9 without their ":" suffix, and the two roles +# are the edge roles of 2.9 without their ":" suffix, the role of an +# annotation task's dataset (spec-d4.md section 1), and the two roles # of a recipe's place on the map (spec-w1.md section 1): derived_from and # compared_with. ACCEPTS = { @@ -42,6 +44,7 @@ 'subject': ('recipes',), 'cases': ('datasets',), 'benchmark': ('benchmarks',), + 'dataset': ('datasets',), 'derived': ('recipes',), 'compared': ('recipes',), } diff --git a/tuldok_project/folder.py b/tuldok_project/folder.py index 78c5fe01..17a83846 100644 --- a/tuldok_project/folder.py +++ b/tuldok_project/folder.py @@ -5,7 +5,9 @@ accepts only regular files and directories, enforces the size caps, and returns every file it could read together with the problems it found. It decodes tuldok.json and the definitions (documents.decode) but judges nothing else -about their content; that is check.py's work. +about their content; that is check.py's work. annotations/ may also hold the +line files of its tasks, .jsonl (spec-d4.md section 2), which it reads +as text; whether each has its task is check.py's rule too. """ from dataclasses import dataclass, field import errno @@ -19,11 +21,14 @@ DEFINITION_LIMIT = 1024 * 1024 PROJECT_LIMIT = 64 * 1024 RESULTS_LIMIT = 16 * 1024 * 1024 +LINES_LIMIT = 64 * 1024 * 1024 # annotations.FILE_LIMIT PROJECT_FILE = 'tuldok.json' OPTIONAL_FILES = ('README.md', '.gitignore') RESULTS = 'results' NOTES = 'notes' +ANNOTATIONS = 'annotations' +LINES_SUFFIX = '.jsonl' # Flags for opening a directory without following a symbolic link. DIRECTORY_FLAGS = os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW | os.O_CLOEXEC @@ -60,6 +65,7 @@ class Folder: root: str project: File | None = None definitions: list = field(default_factory=list) + annotations: list = field(default_factory=list) # File per annotations/.jsonl, document None results: list = field(default_factory=list) notes: frozenset = frozenset() problems: list = field(default_factory=list) @@ -158,15 +164,23 @@ def _read_definitions(folder, root_fd, directory): try: for name, entry_kind in entries(fd): path = f'{directory}/{name}' - if entry_kind != 'file' or not name.endswith('.json'): + lines = directory == ANNOTATIONS and name.endswith(LINES_SUFFIX) + if entry_kind != 'file' or not (name.endswith('.json') or lines): + allowed = ('.json files, one task each, and their .jsonl annotations' + if directory == ANNOTATIONS else '.json files, one definition each') message = (_wrong_type(entry_kind, 'file') if entry_kind == 'link' - else f'{directory}/ may hold only .json files, one definition each; move or remove this.') + else f'{directory}/ may hold only {allowed}; move or remove this.') folder.problems.append(Problem('error', path, '', message)) continue - stem = name[:-len('.json')] + stem = name[:-len(LINES_SUFFIX if lines else '.json')] if not documents.is_name(stem): folder.problems.append(Problem('error', path, '', f'{stem!r} is not a valid name; use lowercase letters, digits, ".", "_" or "-", starting with a letter or digit.')) continue + if lines: + loaded = _load(folder, fd, name, path, LINES_LIMIT, decode=False) + if loaded is not None: + folder.annotations.append(loaded) + continue loaded = _load(folder, fd, name, path, DEFINITION_LIMIT, decode=True) if loaded is not None: folder.definitions.append(Definition(**vars(loaded), kind=kind, name=stem)) diff --git a/tuldok_project/graph.py b/tuldok_project/graph.py index a9e39c35..a058c7f6 100644 --- a/tuldok_project/graph.py +++ b/tuldok_project/graph.py @@ -4,6 +4,7 @@ Every function is pure and takes `definitions`, a mapping of reference (such as 'datasets/x') to decoded document. Documents need not be valid: fields of the wrong type are skipped, so the graph can be read even from a folder with problems. +An annotation task uses its dataset in the role dataset (spec-d4.md section 1). Edges whose target is not in `definitions` are kept by edges() and uses() but ignored by order() and cycles(). The two roles of a recipe's place on the map (spec-w1.md section 1), derived and compared, are edges like the others for @@ -79,6 +80,8 @@ def uses(document): found.append(Use('cases', '/cases/dataset', cases['dataset'])) if kind == 'chart' and isinstance(document.get('benchmark'), str): found.append(Use('benchmark', '/benchmark', document['benchmark'])) + if kind == 'annotation' and isinstance(document.get('dataset'), str): + found.append(Use('dataset', '/dataset', document['dataset'])) return found @@ -219,7 +222,8 @@ def users_of(definitions, reference): _CARRIED = (None, 'needs-work', 'cannot-rebuild') _OWN_STATE = {'needs-work': 1, 'no': 2} # earlier_work.rebuild -> index into _CARRIED _BASE_STATE = {'dataset': 'not-built', 'recipe': 'not-built', 'benchmark': 'not-built', - 'step': 'not-built', 'environment': 'not-set-up', 'model': 'none', 'chart': 'none'} + 'step': 'not-built', 'environment': 'not-set-up', 'model': 'none', 'chart': 'none', + 'annotation': 'none'} _BUILT = ('dataset', 'recipe', 'step', 'benchmark') _ENVIRONMENT_STATES = ('ready', 'failing', 'not-set-up') _BUILD_STATES = ('running', 'built', 'out-of-date', 'failed') @@ -250,7 +254,7 @@ def states(definitions, local=None): built carries nothing to what uses it, and nothing through it: its product is on this machine to be used, whether it was built here or adopted (spec-m8.md section 3). Other edges (environment, model, subjects, cases, - chart) carry nothing. Otherwise the state follows the + chart, an annotation task's dataset) carry nothing. Otherwise the state follows the kind. The table is read in order, so a model marked rebuild "no" is cannot-rebuild, not none. Cycles are tolerated: the result is the fixed point. """ diff --git a/tuldok_project/operations.py b/tuldok_project/operations.py index cdd6bab5..860b6c08 100644 --- a/tuldok_project/operations.py +++ b/tuldok_project/operations.py @@ -14,7 +14,7 @@ WHO = ('inspect', 'edit', 'cancel', 'request', 'owner') REQUEST_STATES = ('awaiting-approval', 'queued', 'running', 'succeeded', 'failed', 'cancelled', 'declined', 'expired') -KINDS = ('dataset', 'model', 'recipe', 'benchmark', 'step', 'environment', 'chart') +KINDS = ('dataset', 'model', 'recipe', 'benchmark', 'step', 'environment', 'chart', 'annotation') CHANGES = ('training-policy', 'architecture', 'refinement', 'component') # a recipe's kind of change RECORD_KINDS = ('text', 'image', 'audio', 'pointcloud', 'mesh', 'array', 'file') # the kinds of a product's record TARGET_LIMIT = 50 diff --git a/tuldok_project/plan.py b/tuldok_project/plan.py index ac8c138a..7d60ea36 100644 --- a/tuldok_project/plan.py +++ b/tuldok_project/plan.py @@ -186,7 +186,8 @@ def make_plan(definitions, targets, *, every=False, local=None, built=None, esti current estimate ({disk_bytes, wall_seconds, items, measured_at}). every adds every dataset, recipe, step and benchmark to the targets. A - chart target is replaced by its benchmark; a model target adds nothing + chart target is replaced by its benchmark, an annotation task by its + dataset (spec-d4.md section 1); a model target adds nothing and a note saying so. Raises ValueError naming any target that is not a definition. """ @@ -204,6 +205,10 @@ def make_plan(definitions, targets, *, every=False, local=None, built=None, esti benchmark = definitions[reference].get('benchmark') notes.append(f'{reference} is drawn from {benchmark}, which is planned in its place.') reference = benchmark + elif kind == 'annotation': + dataset = definitions[reference].get('dataset') + notes.append(f'{reference} annotates the records of {dataset}, which is planned in its place.') + reference = dataset elif kind == 'model': notes.append(f'{reference} is a model; a model is not built, only the recipes that train it.') if reference not in resolved: @@ -212,7 +217,7 @@ def make_plan(definitions, targets, *, every=False, local=None, built=None, esti adopted = {reference for reference, entry in (built or {}).items() if entry.get('adopted')} members = _closure(definitions, edges_from, states, [reference for reference in resolved if _kind(reference) != 'model'], adopted) - members = {reference for reference in members if _kind(reference) not in ('model', 'chart')} + members = {reference for reference in members if _kind(reference) not in ('model', 'chart', 'annotation')} ordered = graph.order({reference: definitions[reference] for reference in members}) actions = {reference: _action(_kind(reference), states[reference]) for reference in ordered} diff --git a/tuldok_project/schemas/annotation.schema.json b/tuldok_project/schemas/annotation.schema.json new file mode 100644 index 00000000..8bab9667 --- /dev/null +++ b/tuldok_project/schemas/annotation.schema.json @@ -0,0 +1,149 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://tuldok.invalid/schemas/annotation.schema.json", + "title": "Tuldok annotation task definition", + "description": "One annotation task in annotations/.json (tuldok_definition_v1). Its annotations are the lines of annotations/.jsonl, checked in tuldok_project/annotations.py.", + "type": "object", + "additionalProperties": false, + "required": [ + "format", + "kind", + "title", + "dataset", + "task" + ], + "properties": { + "format": { + "const": "tuldok_definition_v1" + }, + "kind": { + "enum": [ + "dataset", + "model", + "recipe", + "benchmark", + "step", + "environment", + "chart", + "annotation" + ] + }, + "title": { + "$ref": "#/$defs/title" + }, + "description": { + "$ref": "#/$defs/description" + }, + "card": { + "$ref": "#/$defs/card" + }, + "labels": { + "$ref": "#/$defs/labels" + }, + "dataset": { + "type": "string", + "pattern": "^datasets/[a-z0-9][a-z0-9._-]{0,119}$", + "description": "a reference to a dataset, such as datasets/" + }, + "task": { + "enum": [ + "review", + "class", + "tags", + "text", + "boxes", + "spans", + "segments" + ] + }, + "vocabulary": { + "type": "array", + "minItems": 1, + "maxItems": 500, + "uniqueItems": true, + "items": { + "$ref": "#/$defs/term" + }, + "description": "1 to 500 different terms" + } + }, + "allOf": [ + { + "if": { + "required": [ + "task" + ], + "properties": { + "task": { + "enum": [ + "review", + "text" + ] + } + } + }, + "then": { + "properties": { + "vocabulary": { + "not": {}, + "description": "A review or text task has no vocabulary; remove it." + } + } + } + }, + { + "if": { + "required": [ + "task" + ], + "properties": { + "task": { + "enum": [ + "class", + "tags", + "boxes", + "spans", + "segments" + ] + } + } + }, + "then": { + "required": [ + "vocabulary" + ] + } + } + ], + "$defs": { + "term": { + "type": "string", + "minLength": 1, + "maxLength": 200, + "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]*$", + "description": "a term of 1 to 200 characters without control characters" + }, + "title": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "description": { + "type": "string", + "maxLength": 4000 + }, + "card": { + "type": "string", + "pattern": "^notes/", + "description": "a path under notes/, such as notes/.md" + }, + "labels": { + "type": "object", + "maxProperties": 32, + "additionalProperties": { + "type": "string", + "maxLength": 400 + } + } + } +} diff --git a/tuldok_project/schemas/benchmark.schema.json b/tuldok_project/schemas/benchmark.schema.json index 98bb4ded..e1f55f3b 100644 --- a/tuldok_project/schemas/benchmark.schema.json +++ b/tuldok_project/schemas/benchmark.schema.json @@ -24,7 +24,8 @@ "benchmark", "step", "environment", - "chart" + "chart", + "annotation" ] }, "title": { diff --git a/tuldok_project/schemas/chart.schema.json b/tuldok_project/schemas/chart.schema.json index 4cc338dc..163acbdd 100644 --- a/tuldok_project/schemas/chart.schema.json +++ b/tuldok_project/schemas/chart.schema.json @@ -25,7 +25,8 @@ "benchmark", "step", "environment", - "chart" + "chart", + "annotation" ] }, "title": { diff --git a/tuldok_project/schemas/dataset.schema.json b/tuldok_project/schemas/dataset.schema.json index a92bce49..8a94af79 100644 --- a/tuldok_project/schemas/dataset.schema.json +++ b/tuldok_project/schemas/dataset.schema.json @@ -22,7 +22,8 @@ "benchmark", "step", "environment", - "chart" + "chart", + "annotation" ] }, "title": { diff --git a/tuldok_project/schemas/environment.schema.json b/tuldok_project/schemas/environment.schema.json index 3a33f985..d2e9baa0 100644 --- a/tuldok_project/schemas/environment.schema.json +++ b/tuldok_project/schemas/environment.schema.json @@ -25,7 +25,8 @@ "benchmark", "step", "environment", - "chart" + "chart", + "annotation" ] }, "title": { diff --git a/tuldok_project/schemas/model.schema.json b/tuldok_project/schemas/model.schema.json index b3db3056..3d311093 100644 --- a/tuldok_project/schemas/model.schema.json +++ b/tuldok_project/schemas/model.schema.json @@ -22,7 +22,8 @@ "benchmark", "step", "environment", - "chart" + "chart", + "annotation" ] }, "title": { diff --git a/tuldok_project/schemas/recipe.schema.json b/tuldok_project/schemas/recipe.schema.json index 7a886aa5..35ee25dc 100644 --- a/tuldok_project/schemas/recipe.schema.json +++ b/tuldok_project/schemas/recipe.schema.json @@ -22,7 +22,8 @@ "benchmark", "step", "environment", - "chart" + "chart", + "annotation" ] }, "title": { diff --git a/tuldok_project/schemas/step.schema.json b/tuldok_project/schemas/step.schema.json index b8baa0d0..2af7157f 100644 --- a/tuldok_project/schemas/step.schema.json +++ b/tuldok_project/schemas/step.schema.json @@ -22,7 +22,8 @@ "benchmark", "step", "environment", - "chart" + "chart", + "annotation" ] }, "title": { diff --git a/tuldok_project/store.py b/tuldok_project/store.py index 9ab66775..d0a6e256 100644 --- a/tuldok_project/store.py +++ b/tuldok_project/store.py @@ -176,6 +176,8 @@ def _list_definitions(root): Anything the layout rules would refuse (a link, a non-.json entry, a bad name, an oversize file) is put in irregular, which sends open() to the checker. + A task's annotations/.jsonl beside its .json is neither listed + nor irregular; one without its task is irregular. """ files, irregular = {}, [] root_fd = _open_root(root) @@ -189,8 +191,14 @@ def _list_definitions(root): continue fd = os.open(directory, folder_reader.DIRECTORY_FLAGS, dir_fd=root_fd) try: - for name, entry_kind in folder_reader.entries(fd): + listed = folder_reader.entries(fd) + tasks = {name for name, entry_kind in listed if entry_kind == 'file'} + for name, entry_kind in listed: path = f'{directory}/{name}' + if (directory == folder_reader.ANNOTATIONS and name.endswith(folder_reader.LINES_SUFFIX) + and entry_kind == 'file' + and name[:-len(folder_reader.LINES_SUFFIX)] + '.json' in tasks): + continue # a task's annotations (spec-d4.md section 2): not a definition file stem = name[:-len('.json')] if name.endswith('.json') else None if entry_kind != 'file' or stem is None or not documents.is_name(stem): irregular.append(path) From e2ae4bb29dded43063b1340e26d31bc1328cc20b Mon Sep 17 00:00:00 2001 From: MrScripty Date: Fri, 13 Nov 2026 16:48:08 -0700 Subject: [PATCH 068/131] feat(project): import and freeze, steps Tuldok provides A dataset's run may name a step instead of a command. A step needs no environment and declares no outputs; it is planned, requested, approved, run and cancelled like any build, and runs as Tuldok's own interpreter with Tuldok's code and none of the project's on its path. import brings the files of a directory into a product: hard links, a records.jsonl giving each record's id, kind, hash, size, rights and where it came from, optionally one record per line of text. It never follows a link out of its source and writes only into its output. freeze takes a dataset and one or more annotation tasks on it and makes a dataset with splits: the records the first task accepted, ordered by a hash of the seed and their content, cut by the shares, each carrying its annotations. It reads the tasks' line files from Git at the commit it is built from, and is out of date when one of them changes. Co-Authored-By: Claude Fable 5.2 --- docs/contracts/project-folder.md | 150 ++++- .../definition-first-projects/spec-d4.md | 19 + tests/test_tuldok_project_steps.py | 584 +++++++++++++++++ tuldok_project/__main__.py | 2 + tuldok_project/build_requests.py | 6 +- tuldok_project/builds.py | 257 +++++++- tuldok_project/check.py | 136 +++- tuldok_project/documents.py | 1 + tuldok_project/graph.py | 8 +- tuldok_project/inside.py | 23 +- tuldok_project/plan.py | 34 +- tuldok_project/schemas/benchmark.schema.json | 113 +++- tuldok_project/schemas/dataset.schema.json | 105 ++- tuldok_project/schemas/recipe.schema.json | 113 +++- tuldok_project/schemas/step.schema.json | 113 +++- tuldok_project/snapshot.py | 33 + tuldok_project/steps.py | 608 ++++++++++++++++++ 17 files changed, 2181 insertions(+), 124 deletions(-) create mode 100644 tests/test_tuldok_project_steps.py create mode 100644 tuldok_project/steps.py diff --git a/docs/contracts/project-folder.md b/docs/contracts/project-folder.md index 34cf9946..bb19bcac 100644 --- a/docs/contracts/project-folder.md +++ b/docs/contracts/project-folder.md @@ -129,6 +129,7 @@ directories: | `cases.dataset` (benchmark) | `datasets/` | | `benchmark` (chart) | `benchmarks/` | | `dataset` (annotation) | `datasets/` | +| `run.annotations` (a dataset's freeze) | `annotations/` | An **input** is what a command reads from another definition's product. It is written either as a reference, meaning the whole product, or as @@ -189,7 +190,8 @@ object. It is required unless `earlier_work.rebuild` is `no`. | Field | Required | Rule | | --- | --- | --- | -| `command` | yes | 1 to 64 strings, the program and its arguments; run in the code root. When the first string is exactly `python` it means the environment's interpreter | +| `command` | unless `step` is given | 1 to 64 strings, the program and its arguments; run in the code root. When the first string is exactly `python` it means the environment's interpreter | +| `step` | no | datasets only: `import` or `freeze`, a step Tuldok provides in place of a command; see [Steps Tuldok provides](#steps-tuldok-provides) | | `environment` | when the first string of `command` is `python` | reference to `environments/` | | `inputs` | no | at most 32 entries; keys `^[a-z][a-z0-9_]{0,31}$`; values are inputs from `datasets/`, `recipes/` or `steps/` | | `settings` | no | object, free content, written to a file whose path replaces `{settings}`; not together with `settings_file` | @@ -199,6 +201,7 @@ object. It is required unless `earlier_work.rebuild` is `no`. | `resources` | no | any of `gpu` (boolean), `cpu_threads` (integer ≥ 1), `memory_gb`, `wall_hours`, `disk_gb` (numbers > 0) | | `sources` | no | at most 64 code paths (files or directories); a change in them means the code changed | | `estimate` | no | `{"command": [...]}`, 1 to 64 strings; the command prints one JSON object with any of `disk_bytes`, `wall_seconds`, `items` | +| `annotations` | with `step: "freeze"` only | 1 to 32 different references to `annotations/`: the tasks a freeze reads | A **code path** is a path relative to the code root, at most 1,024 characters. `settings_file`, `sources`, a model's `config_file` and `sources`, and an @@ -234,6 +237,9 @@ examples, except `environments/cuda-torch`, a second environment not shown. | `splits` | no | object, split name to a number of items (integer ≥ 0) | | `view` | no | how its product is shown as records; see [Looking inside a product](#looking-inside-a-product) | +A dataset's run may name a `step` instead of a `command`: see +[Steps Tuldok provides](#steps-tuldok-provides). + Example, `datasets/sinusoidal-v1.json`: ```json @@ -255,6 +261,123 @@ Example, `datasets/sinusoidal-v1.json`: } ``` +#### Steps Tuldok provides + +A dataset's `run` names either a `command` or a `step`, one of `import` and +`freeze`. A run with `step` has no `command`, `environment`, `outputs`, +`settings_file`, `env` or `estimate`: the step's outputs are fixed, its +settings are inline in `settings`, and it runs with Tuldok's own interpreter +(see [The command and its environment](#the-command-and-its-environment)). +It may have `resources` and `sources`. A plan shows it as `tuldok import` or +`tuldok freeze`. It is planned, requested, approved, run, cancelled and +recorded like any build, from a commit as builds are. `check` reports a +setting the step does not take, a required one missing and a value of the +wrong form. + +**`import`** brings files on this machine into the dataset. Its run takes no +`inputs`. Settings: + +| Setting | Required | Rule | +| --- | --- | --- | +| `source` | yes | a directory. Relative to the code root, it is a code path read from the code the run sees (the commit, or the working tree for a scratch run), and a change under it makes the product out of date; absolute, it is read on this machine only, and `check` warns | +| `pattern` | no | which files, as a pattern of [Looking inside a product](#looking-inside-a-product) without `!`, matched against paths under the source; default `**/*` | +| `kind` | no | one of the seven kinds, for every file; default by extension | +| `rights` | yes | 1 to 1,000 characters: what may be done with the files | +| `lines` | no | `true` makes each line of each text file a record of its own (a line that is empty or blank is skipped). A line of a `.jsonl` file that is an object with a string `text` gives that string; any other line gives itself | + +Its product holds the files under `files/`, each at its path under the +source, hard-linked (copied when a link cannot be made, such as across file +systems), and `records.jsonl` with one line per file, or per line with +`lines`: + +``` +{"id":"images__cat.png","kind":"image","path":"files/images/cat.png","sha256":"9f…","bytes":5120,"rights":"Photographed by us; free to use.","origin":{"path":"images/cat.png"}} +{"id":"notes__a.txt__4","kind":"text","text":"second line","sha256":"…","bytes":11,"rights":"…","origin":{"path":"notes/a.txt","line":4}} +``` + +An id is made from the path (and `/` and the line number): `/` becomes +`__`, any other character outside `A-Z a-z 0-9 . _ -` becomes `_`, it is cut +to 200 characters, and an id already taken gets `-2`, `-3`, … before its +extension. Files are taken in the order of their paths, bytewise in UTF-8. A +path holding `!` (which an address reads as an archive) is placed with `_` +in its place. `sha256` is the SHA-256 of the file, or of the UTF-8 of a +line's text; null for a file over 1 GiB. A symbolic link whose target is in +the source is taken where it stands; one that leaves the source is skipped +and counted, and so are names that are not UTF-8, entries that are not +regular files, lines that are not UTF-8 and lines too long for one line of +`records.jsonl` (64 KiB). The step never follows a link out of its source, +writes only its output and deletes nothing. + +**`freeze`** makes a dataset with splits from another dataset's records and +their annotations. Its run takes one input, `"inputs": {"records": +"datasets/"}`, and `annotations`, one or more tasks on that dataset; +`check` reports a task on another dataset. Settings: + +| Setting | Required | Rule | +| --- | --- | --- | +| `seed` | yes | an integer of at most 63 bits | +| `shares` | yes | 1 to 16 splits and their relative sizes, integers from 0 to 1,000,000, at least one above 0, for example `{"train": 8, "validation": 1, "test": 1}` | +| `include` | no | the states of the first task's annotations that take a record in; default `["accepted"]` | + +It reads each task's line file from the commit the build uses, at the +project folder's place in the code's Git repository (a scratch build reads +the working tree): annotations that are not saved and committed are not +frozen, as code is not. A build from a commit refuses a project folder that +is not in the code's repository. The input's records are its product's +`records.jsonl`, or its files (an input shown through a `view` is refused). +A record is taken when the first task has an annotation of it in a state of +`include` that is not stale: its record exists and, when the annotation +carries a `sha256`, the record's hash is the same. The records taken are +ordered by the SHA-256 of `:` (`:id:` for a +record with no hash), then cut by the shares, the splits taken in the order +of their names (`test`, `train`, `validation`), each split's end being +`count × shares so far ÷ all shares`, rounded down. The output holds their +files linked under `files/` (an archive member brings its whole archive) +and `records.jsonl` with each record's keys, `split` and `annotations`: per +task by name, its `state` and `value`, for each task whose annotation of the +record is not stale. + +``` +{"id":"images__cat.png","kind":"image","path":"files/images/cat.png","sha256":"9f…","bytes":5120,"rights":"…","origin":{"path":"images/cat.png"},"split":"train","annotations":{"scene-quality":{"state":"accepted","value":"clean"}}} +``` + +Stale annotations, records left out by their state, records with no +annotation, invalid lines, stale annotations of the other tasks and records +whose file is missing are counted in the run's progress and printed in its +log. A record whose id is not one of `records.jsonl` (a file of an input +with no `records.jsonl`) gets one made as `import` makes them. + +A frozen dataset's run records the SHA-256 of each task's line file as it +read it; see [Build states](#build-states). + +Example, `datasets/scene-photos.json` and `datasets/scene-photos-v1.json`: + +```json +{ + "format": "tuldok_definition_v1", + "kind": "dataset", + "title": "Scene photos", + "run": { + "step": "import", + "settings": {"source": "data/scenes", "pattern": "**/*.png", "rights": "Photographed by us; free to use."} + } +} +``` + +```json +{ + "format": "tuldok_definition_v1", + "kind": "dataset", + "title": "Scene photos v1, frozen", + "run": { + "step": "freeze", + "inputs": {"records": "datasets/scene-photos"}, + "annotations": ["annotations/scene-quality"], + "settings": {"seed": 7, "shares": {"train": 8, "validation": 1, "test": 1}} + } +} +``` + ### `model` A model is an architecture. It produces nothing by itself; recipes train it. @@ -1425,6 +1548,7 @@ is 32 hexadecimal characters: | --- | --- | | `output/` | what `{output}` names, made empty before the command starts; a succeeded run's `output/` is its product | | `settings.json` | the inline `settings` as the run saw them, when the definition has them | +| `tasks.json`, `annotations/` | a freeze's tasks and the line files it read | | `stdout.log`, `stderr.log` | the command's standard output and error | | `cancel` | present when cancellation was asked for | | `outcome.json` | how the command ended, written when every process of the run is gone | @@ -1460,6 +1584,17 @@ The working directory is the code root in the snapshot (or the code root itself for a scratch run). Standard input is `/dev/null`; standard output and error are appended to the two logs. +A [step Tuldok provides](#steps-tuldok-provides) needs no environment +definition. Its command is Tuldok's own interpreter running `-m +tuldok_project.steps /settings.json /output`, followed by `--code ` for `import`, and by +`--records --tasks /tasks.json` for +`freeze`, which also finds the line files it was given in `/annotations/`. Its environment is the one above without `env`, +with `PYTHONSAFEPATH=1` and `PYTHONPATH` set to Tuldok's own directory last, +so that Tuldok's code is imported and the code root's never is. A step opens +no database; it prints progress lines like any command. + ### Placeholders at run time | Placeholder | Filled with | @@ -1544,7 +1679,15 @@ A current product is **out of date** when: - the run was not a scratch run, and one of the definition's `sources` (or a file under one) changed since the run's commit: in a later commit or as an uncommitted change to a tracked file. When Git no longer has that commit, - the code is taken to have changed. + the code is taken to have changed. An `import` from a relative `source` is + out of date the same way when a file under its source changed; +- for a `freeze`, the line file of one of its tasks differs from the one its + run read: in the commit `HEAD` names (the commit a build would use; an + uncommitted change does not count), or in the working tree for a scratch + product. The cause names the task and the file (`the annotations of + annotations/scene-quality (annotations/scene-quality.jsonl) changed since + run …`, or `are gone`). A change to the file of a task it does not read + changes nothing. A benchmark has a product per subject. It is `built` when every subject that would run has a current product that is not out of date, and `out-of-date` @@ -2126,6 +2269,9 @@ it: a missing file, and a symbolic link that leaves the product, are refused | `array` | for kind `array` in an `.npz`: the array to show first | | `split`, `rights` | optional strings | | `origin`, `meta` | optional objects, kept and shown as they are | + | `sha256` | optional; the SHA-256 of the record's content, 64 lowercase hexadecimal digits, or null | + | `bytes` | optional; the record's size, an integer ≥ 0 (otherwise the file's size is shown) | + | `annotations` | optional object; a frozen record's annotations, per task its `state` and `value` | Other keys are kept and shown in `meta` (a key of `meta` itself wins). A line that is not such a record, or is longer than 64 KiB, is skipped and diff --git a/docs/plans/definition-first-projects/spec-d4.md b/docs/plans/definition-first-projects/spec-d4.md index 94264dba..a78fdcc4 100644 --- a/docs/plans/definition-first-projects/spec-d4.md +++ b/docs/plans/definition-first-projects/spec-d4.md @@ -196,3 +196,22 @@ What differs from the text above, and what was chosen where it was silent. - **Checked in review** with annotations generated at random: 400 of each task, with ids holding `/`, `!`, non-Latin letters and upper case, values holding quotes, backslashes, line separators and emoji, written and read back equal, byte for byte and in order; 3,000 corrupted files read without an error escaping; 100,000 lines written in 0.2 s and read and checked in 1.4 s (16 MiB). - **Tests:** `tests/test_tuldok_project_annotations.py`, 22; project suite 632; agent interface 43 (4 skipped). The catalog profile's digest is unchanged. - **Not verified:** the editor's list of kinds in a browser. + +### D4c, the steps Tuldok provides + +What differs from section 6, and what was chosen where it was silent. + +- **`run` is one shape in every schema** (a test requires it), so `step` and `annotations` are written into the `run` of all four kinds that have one, and only a dataset may use `step`. A run with a `step` has no `command`, `environment`, `outputs`, `settings_file`, `env` or `estimate`; `annotations` go only with `freeze`. +- **A freeze reads its tasks' line files from Git at the commit it is built from,** at the project folder's place in the repository, not from the code snapshot: a project folder need not lie under the code root (the tests' fixture has its code beside it). A build from a commit refuses a project folder that is outside the code's repository; a scratch build reads the working tree. +- **The order of the splits** is the order of their names, not the order written: the settings pass through the database, which does not keep the order of keys. Each split ends at the count times the shares so far over their total, rounded down. +- **The order of the records** is by the SHA-256 of `:`, or of `:id:` for a record that has no hash. An annotation with no hash is tied to its record by id. +- **Ids from paths** are cut to 200 characters (spec-d1's bound), made unique by `-2`, `-3` before the extension; a record made from a line is `__`. A path holding `!` is placed with `_` in its stead, since an address reads `!` as an archive. Letters outside the allowed set become `_`; the record's `origin` keeps the path as it was. +- **What is left out and counted:** a record whose line in `records.jsonl` would pass 64 KiB; blank lines, under `lines`; an annotation line that is not valid; a stale annotation of a task other than the first (the record stays, without that task's annotation). An error of a line file as a whole fails the step. +- **What a freeze does not take:** an input read through a `view` is refused. A record that is a member of an archive gets no hash, and its whole archive is linked. +- **`bytes` joins the keys of a record line** that the reader knows, with `sha256` and `annotations`, so that an imported record's size is its own and not part of `meta`. +- **Out of date.** A freeze's run keeps, in a new column of `runs`, the Git blob and SHA-256 of each line file it read; the product is out of date when a task's file at the commit to build from differs, with a cause naming the file. A build request covers a freeze's tasks. An import from a source under the code root is out of date when something under that source changes; one from an absolute source never is. +- **The step's process** is Tuldok's interpreter with `-m tuldok_project.steps`, and `PYTHONSAFEPATH` and `PYTHONPATH` are set after the run's own variables, so nothing in a definition can point it at other code. +- **Hard links.** `import` and `freeze` link files rather than copy them (a copy only across file systems). A linked file is the same file as its source: editing the source in place changes the product, which the record's hash then shows. The launcher counts linked files at their full size against a run's disk limit. +- **Checked in review** on a source holding links out of it (to a file and to a directory), a link looping back into it, a named pipe, a name that collides with another once made an id, names with spaces, shell characters and non-Latin letters, a name of 240 characters and an empty file: eight records, ids unique and valid, the two links out and the pipe skipped and counted, nothing read from outside the source, nothing written outside the output, the source's files unchanged, and the product read back by spec-d1's reader with every hash. +- **Tests:** `tests/test_tuldok_project_steps.py`, 18; project suite 667; agent interface 43 (4 skipped). +- **Not verified:** a copy across file systems; a source of very many or very large files; the plan and the run of a step as the page shows them. diff --git a/tests/test_tuldok_project_steps.py b/tests/test_tuldok_project_steps.py new file mode 100644 index 00000000..8566def4 --- /dev/null +++ b/tests/test_tuldok_project_steps.py @@ -0,0 +1,584 @@ +"""The steps Tuldok provides (docs/plans/definition-first-projects/spec-d4.md, section 6, slice D4c). + +import and freeze are first tested as functions on directories the test +writes. Then a project is built for real through builds.execute: a Git +repository holding the project folder and its code side by side (code_root +../code, so the line files are read from the commit and not from the +snapshot), an import from a relative source, two tasks with annotations, a +third task on the same dataset, and a freeze. Those tests run only when +TULDOK_DATABASE_URL names a disposable cluster. No GPU, no environment: a step +runs with Tuldok's own interpreter, and the code root holds a decoy +tuldok_project/steps.py that fails if it is ever imported. +""" +import hashlib +import json +import os +from pathlib import Path +import shutil +import subprocess +import sys +import tempfile +import unittest +from unittest import mock +import uuid + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) + +from tuldok_project import (annotations, build_requests, builds, check, inside, local, plan, steps, # noqa: E402 + store) + +DATABASE = os.environ.get('TULDOK_DATABASE_URL') +GIT = ['git', '-c', 'user.name=Tuldok Test', '-c', 'user.email=test@example.invalid', '-c', 'commit.gpgsign=false'] +RIGHTS = 'Made by the test; anything may be done with them.' +AT = '2026-11-13T10:00:00Z' +PLY_FACES = b'ply\nformat ascii 1.0\nelement vertex 3\nproperty float x\nproperty float y\nproperty float z\n' \ + b'element face 1\nproperty list uchar int vertex_indices\nend_header\n0 0 0\n1 0 0\n0 1 0\n3 0 1 2\n' +PLY_POINTS = b'ply\nformat ascii 1.0\nelement vertex 1\nproperty float x\nproperty float y\nproperty float z\n' \ + b'end_header\n0 0 0\n' + + +def _sha(data): + return hashlib.sha256(data).hexdigest() + + +def _tree(root): + """A source tree holding a file of each kind, nested files, names that make the same id, and links.""" + files = { + 'notes/a.txt': b'first line\n\n \nsecond line\r\n', + 'notes/b.jsonl': b'{"text": "from json"}\n{"other": 1}\n[1, 2]\n', + 'images/cat.png': b'\x89PNG\r\n\x1a\nnot really', + 'sounds/hello.wav': b'RIFF....WAVE', + 'shapes/cloud.xyz': b'0 0 0\n1 1 1\n', + 'shapes/mesh.obj': b'v 0 0 0\nv 1 0 0\nv 0 1 0\nf 1 2 3\n', + 'shapes/faces.ply': PLY_FACES, + 'shapes/points.ply': PLY_POINTS, + 'arrays/x.npy': b'\x93NUMPY fake', + 'other/blob.bin': b'\x00\x01\x02', + 'same id/a b.txt': b'one\n', + 'same id/a_b.txt': b'two\n', + 'odd/bang!name.txt': b'bang\n', + } + for name, data in files.items(): + path = root / name + path.parent.mkdir(parents=True, exist_ok=True) + path.write_bytes(data) + return files + + +def _records(output): + with open(Path(output) / 'records.jsonl', encoding='utf-8') as handle: + return [json.loads(line) for line in handle] + + +def _row(record, state, value, sha256=None, by='owner'): + return {'record': record, 'sha256': sha256, 'state': state, 'value': value, 'by': by, 'at': AT} + + +class Shared(unittest.TestCase): + """What steps.py repeats from inside.py, standard library alone, stays the same.""" + + def test_kinds_patterns_and_ids(self): + self.assertEqual(steps.EXTENSIONS, inside.EXTENSIONS) + self.assertEqual(steps.KINDS, inside.KINDS) + for pattern in ('**/*', '*.png', 'a/**/b?.txt', '**', 'x/*/y'): + self.assertEqual(steps.pattern_regex(pattern).pattern, inside.pattern_regex(pattern).pattern) + self.assertEqual(steps.id_from('a b/c!d/é.png'), 'a_b__c_d___.png') + self.assertEqual(len(steps.id_from('x' * 300)), 200) + used = set() + self.assertEqual([steps.unique(name, used, 200) for name in ('a.png', 'a.png', 'a.png', 'a-2.png')], + ['a.png', 'a-2.png', 'a-3.png', 'a-2-2.png']) + long = 'y' * 196 + '.png' + self.assertEqual(len(steps.unique(long, {long}, 200)), 200) + + +class Import(unittest.TestCase): + + def setUp(self): + directory = tempfile.TemporaryDirectory() + self.addCleanup(directory.cleanup) + self.temporary = Path(directory.name) + self.code = self.temporary / 'code' + self.source = self.code / 'data' + self.files = _tree(self.source) + outside = self.temporary / 'outside' + outside.mkdir() + (outside / 'secret.txt').write_text('never imported', encoding='utf-8') + os.symlink(outside / 'secret.txt', self.source / 'notes' / 'leaving.txt') + os.symlink(outside, self.source / 'leaving-folder') + os.symlink(self.source / 'images' / 'cat.png', self.source / 'other' / 'cat-again.png') + self.said = [] + + def output(self, name='out'): + path = self.temporary / name + path.mkdir() + return path + + def run_import(self, settings, *, name='out', code=True): + output = self.output(name) + counts = steps.import_files({'rights': RIGHTS, **settings}, str(output), + code_root=str(self.code) if code else None, out=self.said.append) + return output, counts, _records(output) + + def test_every_kind_from_a_relative_source(self): + output, counts, records = self.run_import({'source': 'data'}) + by_origin = {record['origin']['path']: record for record in records} + kinds = {path: record['kind'] for path, record in by_origin.items()} + self.assertEqual(kinds['images/cat.png'], 'image') + self.assertEqual(kinds['sounds/hello.wav'], 'audio') + self.assertEqual(kinds['shapes/cloud.xyz'], 'pointcloud') + self.assertEqual(kinds['shapes/points.ply'], 'pointcloud') + self.assertEqual(kinds['shapes/mesh.obj'], 'mesh') + self.assertEqual(kinds['shapes/faces.ply'], 'mesh') + self.assertEqual(kinds['arrays/x.npy'], 'array') + self.assertEqual(kinds['other/blob.bin'], 'file') + self.assertEqual(kinds['notes/a.txt'], 'text') + # A link inside the source is imported where it stands; links leaving it are skipped and counted. + self.assertIn('other/cat-again.png', by_origin) + self.assertNotIn('notes/leaving.txt', by_origin) + self.assertEqual(counts['links_out'], 2) + self.assertTrue(any('2 symbolic links leaving the source were skipped.' in line for line in self.said)) + self.assertEqual(len(records), len(self.files) + 1) + for path, data in self.files.items(): + record = by_origin[path] + self.assertEqual((record['sha256'], record['bytes'], record['rights']), (_sha(data), len(data), RIGHTS)) + placed = output / record['path'] + self.assertEqual(placed.read_bytes(), data) + self.assertEqual(os.stat(placed).st_ino, os.stat(self.source / path).st_ino) # hard-linked + self.assertEqual(list(record), ['id', 'kind', 'path', 'sha256', 'bytes', 'rights', 'origin']) + # Ids from paths, made unique; a name holding '!' is placed where an address cannot read it as an archive. + self.assertEqual(by_origin['images/cat.png']['id'], 'images__cat.png') + self.assertEqual(by_origin['same id/a b.txt']['id'], 'same_id__a_b.txt') + self.assertEqual(by_origin['same id/a_b.txt']['id'], 'same_id__a_b-2.txt') + self.assertEqual(by_origin['odd/bang!name.txt']['path'], 'files/odd/bang_name.txt') + self.assertEqual(by_origin['images/cat.png']['path'], 'files/images/cat.png') + self.assertEqual(len({record['id'] for record in records}), len(records)) + # Nothing outside the output was written, nothing in the source changed. + self.assertEqual(sorted(os.listdir(output)), ['files', 'records.jsonl']) + self.assertEqual((self.source / 'notes' / 'a.txt').read_bytes(), self.files['notes/a.txt']) + + def test_by_pattern_with_a_kind_from_an_absolute_source(self): + _, counts, records = self.run_import({'source': str(self.source), 'pattern': 'shapes/*.ply', 'kind': 'mesh'}, + code=False) + self.assertEqual([(record['origin']['path'], record['kind']) for record in records], + [('shapes/faces.ply', 'mesh'), ('shapes/points.ply', 'mesh')]) + self.assertEqual(counts['links_out'], 1) # the folder link is not a file the pattern can take + + def test_lines(self): + _, counts, records = self.run_import({'source': 'data', 'pattern': 'notes/*', 'lines': True}) + texts = [(record['id'], record['text'], record['origin']) for record in records] + self.assertEqual(texts, [ + ('notes__a.txt__1', 'first line', {'path': 'notes/a.txt', 'line': 1}), + ('notes__a.txt__4', 'second line', {'path': 'notes/a.txt', 'line': 4}), + ('notes__b.jsonl__1', 'from json', {'path': 'notes/b.jsonl', 'line': 1}), + ('notes__b.jsonl__2', '{"other": 1}', {'path': 'notes/b.jsonl', 'line': 2}), + ('notes__b.jsonl__3', '[1, 2]', {'path': 'notes/b.jsonl', 'line': 3})]) + for record in records: + self.assertEqual(record['kind'], 'text') + self.assertNotIn('path', record) + self.assertEqual(record['sha256'], _sha(record['text'].encode('utf-8'))) + self.assertEqual(record['bytes'], len(record['text'].encode('utf-8'))) + self.assertEqual(counts['lines'], 5) + + def test_the_product_is_read_by_the_readers_with_its_hashes(self): + output, _, records = self.run_import({'source': 'data', 'pattern': '**/*.txt', 'lines': True}) + product = inside.Product('run-import', str(output)) + listed = inside.records(product, limit=200) + self.assertEqual(listed['source'], 'records.jsonl') + self.assertEqual(listed['problems'], []) + self.assertEqual(listed['total'], len(records)) + shown = {record['id']: record for record in listed['records']} + for record in records: + self.assertEqual(shown[record['id']]['sha256'], record['sha256']) + self.assertEqual(shown[record['id']]['bytes'], record['bytes']) + self.assertIsNone(shown[record['id']]['meta']) + one = inside.record(product, records[0]['id']) + self.assertEqual(one['content']['text'], records[0]['text']) + self.assertEqual(one['record']['sha256'], records[0]['sha256']) + + def test_a_source_that_leaves_the_code_root(self): + os.symlink(self.temporary / 'outside', self.code / 'away') + with self.assertRaisesRegex(steps.StepError, 'outside the code root'): + steps.import_files({'source': 'away', 'rights': RIGHTS}, str(self.output()), code_root=str(self.code), + out=self.said.append) + + +class Freeze(unittest.TestCase): + """freeze on an imported product of ten text records, with two tasks.""" + + def setUp(self): + directory = tempfile.TemporaryDirectory() + self.addCleanup(directory.cleanup) + self.temporary = Path(directory.name) + source = self.temporary / 'source' + source.mkdir() + for number in range(10): + (source / f'r{number}.txt').write_text(f'record {number}\n', encoding='utf-8') + self.product = self.temporary / 'product' + self.product.mkdir() + steps.import_files({'source': str(source), 'rights': RIGHTS}, str(self.product), out=lambda text: None) + self.records = {record['id']: record for record in _records(self.product)} + self.count = 0 + + def lines(self, name, rows): + path = self.temporary / f'{name}.jsonl' + data = annotations.write(rows) + path.write_bytes(data) + return str(path), _sha(data) + + def task(self, name, rows, task='class', vocabulary=('good', 'bad')): + path, digest = self.lines(name, rows) + return {'reference': f'annotations/{name}', 'task': task, 'vocabulary': list(vocabulary), 'lines': path, + 'sha256': digest} + + def freeze(self, settings, tasks): + self.count += 1 + output = self.temporary / f'frozen-{self.count}' + output.mkdir() + said = [] + counts = steps.freeze_records(settings, str(output), records=str(self.product), tasks=tasks, + out=said.append) + return output, counts, _records(output), said + + def accepted_all(self): + return [_row(identifier, 'accepted', 'good', record['sha256']) + for identifier, record in self.records.items()] + + def test_splits_by_the_shares_the_same_for_a_seed(self): + tasks = [self.task('quality', self.accepted_all())] + settings = {'seed': 7, 'shares': {'train': 8, 'validation': 1, 'test': 1}} + output, counts, frozen, _ = self.freeze(settings, tasks) + self.assertEqual([record['split'] for record in frozen], ['test'] + ['train'] * 8 + ['validation']) + self.assertEqual(counts['included'], 10) + again = self.freeze(settings, tasks)[2] + self.assertEqual(frozen, again) + other = self.freeze({**settings, 'seed': 8}, tasks)[2] + self.assertNotEqual([record['id'] for record in frozen], [record['id'] for record in other]) + self.assertEqual(sorted(record['id'] for record in frozen), sorted(record['id'] for record in other)) + # The order is the SHA-256 of the seed and the record's hash. + expected = sorted(self.records.values(), key=lambda record: steps.order_key(7, record['sha256'], record['id'])) + self.assertEqual([record['id'] for record in frozen], [record['id'] for record in expected]) + for record in frozen: + source = self.records[record['id']] + self.assertEqual(record['sha256'], source['sha256']) + self.assertEqual(record['annotations'], {'quality': {'state': 'accepted', 'value': 'good'}}) + self.assertEqual(os.stat(output / record['path']).st_ino, os.stat(self.product / source['path']).st_ino) + self.assertEqual(list(record)[-2:], ['split', 'annotations']) + + def test_includes_by_state_and_leaves_out_stale_ones(self): + ids = sorted(self.records) + rows = [_row(ids[0], 'accepted', 'good', self.records[ids[0]]['sha256']), + _row(ids[1], 'accepted', 'bad', None), # tied by id alone + _row(ids[2], 'needs-work', 'bad', self.records[ids[2]]['sha256']), + _row(ids[3], 'rejected', None, self.records[ids[3]]['sha256']), + _row(ids[4], 'accepted', 'good', '0' * 64), # its content differs + _row('gone', 'accepted', 'good', '1' * 64), # its record is gone + _row(ids[5], 'draft', None, self.records[ids[5]]['sha256'])] + captions = [_row(ids[0], 'draft', 'a caption', self.records[ids[0]]['sha256']), + _row(ids[1], 'accepted', 'stale caption', '2' * 64), + _row(ids[9], 'accepted', 'not taken', None)] + tasks = [self.task('quality', rows), self.task('captions', captions, task='text', vocabulary=())] + _, counts, frozen, said = self.freeze({'seed': 1, 'shares': {'all': 1}}, tasks) + self.assertEqual(sorted(record['id'] for record in frozen), [ids[0], ids[1]]) + carried = {record['id']: record['annotations'] for record in frozen} + self.assertEqual(carried[ids[0]], {'quality': {'state': 'accepted', 'value': 'good'}, + 'captions': {'state': 'draft', 'value': 'a caption'}}) + self.assertEqual(carried[ids[1]], {'quality': {'state': 'accepted', 'value': 'bad'}}) + self.assertEqual((counts['stale'], counts['excluded'], counts['unannotated'], counts['stale_other']), + (2, 3, 4, 1)) + self.assertIn('2 annotations of quality are stale (the record is gone or its content differs) and were ' + 'left out.', said) + self.assertTrue(any(line.startswith('{"format":"tuldok_progress_v1","stage":"freeze"') for line in said)) + wider = self.freeze({'seed': 1, 'shares': {'all': 1}, 'include': ['accepted', 'needs-work', 'draft']}, + tasks)[2] + self.assertEqual(sorted(record['id'] for record in wider), [ids[0], ids[1], ids[2], ids[5]]) + + def test_a_changed_line_file_is_refused(self): + task = self.task('quality', self.accepted_all()) + task['sha256'] = '3' * 64 + with self.assertRaisesRegex(steps.StepError, 'not the file the build read'): + self.freeze({'seed': 1, 'shares': {'all': 1}}, [task]) + + +class Checked(unittest.TestCase): + """check: the step's settings, inputs and tasks (section 6), on a folder written by the test.""" + + def setUp(self): + directory = tempfile.TemporaryDirectory() + self.addCleanup(directory.cleanup) + self.root = Path(directory.name) + self.folder = self.root / 'project' + _write_project(self.root, uuid.uuid4().hex) + + def problems(self): + report = check.check_folder(self.folder) + return {(problem.severity, problem.path, problem.pointer, problem.message) for problem in report.problems} + + def write(self, reference, document): + path = self.folder / f'{reference}.json' + path.parent.mkdir(exist_ok=True) + path.write_text(json.dumps(document, indent=2) + '\n', encoding='utf-8') + + def test_the_fixture_checks(self): + self.assertEqual({problem for problem in self.problems() if problem[0] == 'error'}, set()) + + def test_an_absolute_source_is_a_warning(self): + self.write('datasets/raw', _import_definition({'source': str(self.root / 'code' / 'data')})) + self.assertIn(('warning', 'datasets/raw.json', '/run/settings/source', + f'The source {self.root / "code" / "data"} is absolute, so this dataset can be built on this ' + 'machine only; give a path relative to the code root.'), self.problems()) + + def test_settings_and_fields_a_step_does_not_take(self): + document = _import_definition({'source': 'missing', 'kind': 'video', 'lines': 'yes', 'extra': 1, + 'pattern': '../x'}) + del document['run']['settings']['rights'] + document['run'].update(command=['python', 'x.py'], environment='environments/none', + outputs={'data': {'path': 'x', 'role': 'data'}}) + self.write('datasets/raw', document) + found = {(pointer, severity) for severity, path, pointer, _ in self.problems() if path == 'datasets/raw.json'} + for pointer in ('/run/settings/rights', '/run/settings/kind', '/run/settings/lines', '/run/settings/extra', + '/run/settings/pattern', '/run/settings/source', '/run/command', '/run/environment', + '/run/outputs'): + self.assertIn((pointer, 'error'), found) + + def test_a_freeze_by_a_task_of_another_dataset(self): + self.write('datasets/elsewhere', _import_definition({'source': 'data'})) + self.write('annotations/other-place', {'format': 'tuldok_definition_v1', 'kind': 'annotation', + 'title': 'Elsewhere', 'dataset': 'datasets/elsewhere', + 'task': 'review'}) + frozen = _freeze_definition(['annotations/quality', 'annotations/other-place']) + frozen['run']['settings'] = {'seed': 1.5, 'shares': {'train': 0}, 'include': ['accepted', 'accepted']} + self.write('datasets/frozen', frozen) + problems = self.problems() + self.assertIn(('error', 'datasets/frozen.json', '/run/annotations/1', + 'annotations/other-place annotates datasets/elsewhere, not datasets/raw, the input of this ' + 'freeze; name a task of its input.'), problems) + found = {pointer for severity, path, pointer, _ in problems if path == 'datasets/frozen.json'} + self.assertTrue({'/run/settings/seed', '/run/settings/shares', '/run/settings/include'} <= found) + + def test_a_plan_shows_the_step_and_notes_a_task_elsewhere(self): + definitions = {path.parent.name + '/' + path.stem: json.loads(path.read_text(encoding='utf-8')) + for path in self.folder.glob('*/*.json')} + definitions['annotations/quality']['dataset'] = 'datasets/frozen' + made = plan.make_plan(definitions, ['datasets/frozen']) + shown = {step['reference']: (step['command'], step['environment'], step['step'], step['annotations']) + for step in made['steps']} + self.assertEqual(shown, {'datasets/raw': (['tuldok', 'import'], None, 'import', []), + 'datasets/frozen': (['tuldok', 'freeze'], None, 'freeze', + ['annotations/quality', 'annotations/captions'])}) + self.assertIn('datasets/frozen freezes by annotations/quality, which annotates datasets/frozen, not its ' + 'input datasets/raw; it fails when built.', made['notes']) + + +# ------------------------------------------------------------- a project + +def _import_definition(settings): + return {'format': 'tuldok_definition_v1', 'kind': 'dataset', 'title': 'Imported', + 'run': {'step': 'import', 'settings': {'rights': RIGHTS, **settings}}} + + +def _freeze_definition(tasks): + return {'format': 'tuldok_definition_v1', 'kind': 'dataset', 'title': 'Frozen', + 'run': {'step': 'freeze', 'inputs': {'records': 'datasets/raw'}, 'annotations': tasks, + 'settings': {'seed': 11, 'shares': {'train': 3, 'test': 1}}}} + + +def _write_project(root, project_id): + """root/project (the folder, code_root ../code) and root/code (a source tree, and a decoy of Tuldok's steps).""" + folder, code = root / 'project', root / 'code' + for directory in ('datasets', 'annotations'): + (folder / directory).mkdir(parents=True) + (folder / 'tuldok.json').write_text(json.dumps({'format': 'tuldok_project_v1', 'id': project_id, + 'name': 'Steps test project', 'code_root': '../code'}, + indent=2) + '\n', encoding='utf-8') + definitions = { + 'datasets/raw': _import_definition({'source': 'data', 'pattern': '**/*.txt'}), + 'datasets/frozen': _freeze_definition(['annotations/quality', 'annotations/captions']), + 'annotations/quality': {'format': 'tuldok_definition_v1', 'kind': 'annotation', 'title': 'Quality', + 'dataset': 'datasets/raw', 'task': 'class', 'vocabulary': ['good', 'bad']}, + 'annotations/captions': {'format': 'tuldok_definition_v1', 'kind': 'annotation', 'title': 'Captions', + 'dataset': 'datasets/raw', 'task': 'text'}, + 'annotations/unrelated': {'format': 'tuldok_definition_v1', 'kind': 'annotation', 'title': 'Unrelated', + 'dataset': 'datasets/raw', 'task': 'review'}, + } + for reference, document in definitions.items(): + (folder / f'{reference}.json').write_text(json.dumps(document, indent=2) + '\n', encoding='utf-8') + for number in range(8): + path = code / 'data' / f'item-{number}.txt' + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(f'item {number}\n', encoding='utf-8') + decoy = code / 'tuldok_project' + decoy.mkdir() + (decoy / '__init__.py').write_text('', encoding='utf-8') + (decoy / 'steps.py').write_text('import sys\nprint("the snapshot\'s code was imported", file=sys.stderr)\n' + 'sys.exit(3)\n', encoding='utf-8') + + +def _writable(root): + for current, directories, _files in os.walk(root): + for name in directories: + path = os.path.join(current, name) + if not os.path.islink(path): + os.chmod(path, 0o755) + + +@unittest.skipUnless(DATABASE, 'TULDOK_DATABASE_URL is not set; database tests need a disposable cluster.') +class Built(unittest.TestCase): + """import and freeze built for real by builds.execute, and the frozen dataset's out-of-date state.""" + + def setUp(self): + directory = tempfile.TemporaryDirectory() + self.addCleanup(directory.cleanup) + self.root = Path(directory.name) / 'repository' + self.root.mkdir() + self.home = Path(directory.name) / 'home' + self.addCleanup(_writable, self.home) + patcher = mock.patch.dict(os.environ, {local.HOME_VARIABLE: str(self.home)}) + patcher.start() + self.addCleanup(patcher.stop) + self.project_id = uuid.uuid4().hex + _write_project(self.root, self.project_id) + self.folder = self.root / 'project' + self.git('init', '-q') + self.commit('The project.') + self.addCleanup(store.drop_project, self.project_id) + + def git(self, *arguments): + subprocess.run([*GIT, '-C', str(self.root), *arguments], check=True, capture_output=True, timeout=60) + + def commit(self, message): + self.git('add', '-A') + self.git('commit', '-q', '-m', message) + + def opened(self): + return store.open_project(self.folder) + + def build(self, *targets, scratch=False): + with self.opened() as project: + made = plan.build_plan(project, list(targets)) + done = builds.execute(self.folder, made, confirm=lambda given: True, scratch=scratch) + self.assertTrue(done['ok'], done) + return done + + def status(self): + with self.opened() as project: + return builds.status(project) + + def product(self, reference): + with self.opened() as project: + found = builds.products(project, reference) + return found[0] + + def write_lines(self, name, rows): + (self.folder / 'annotations' / f'{name}.jsonl').write_bytes(annotations.write(rows)) + + def test_import_then_freeze_and_out_of_date_by_the_line_files(self): + done = self.build('datasets/raw') + run = done['steps'][0] + with self.opened() as project: + row = builds.run_details(project, run['run_id']) + # Tuldok's interpreter and code; no environment; the snapshot's decoy never imported. + self.assertEqual(row['argv'][:5], [sys.executable, '-m', 'tuldok_project.steps', 'import', + os.path.join(row['directory'], 'settings.json')]) + self.assertIsNone(row['environment']) + self.assertEqual((row['env']['PYTHONSAFEPATH'], row['env']['PYTHONPATH']), ('1', builds.TULDOK_ROOT)) + stderr = (Path(row['directory']) / 'stderr.log').read_text(encoding='utf-8') + self.assertNotIn('snapshot', stderr) + raw = self.product('datasets/raw') + records = {record['id']: record for record in _records(raw['directory'])} + self.assertEqual(sorted(records), [f'item-{number}.txt' for number in range(8)]) + event = (Path(row['directory']) / 'stdout.log').read_text(encoding='utf-8') + self.assertIn('"stage":"import","completed":8,"total":8', event) + + ids = sorted(records) + self.write_lines('quality', [_row(identifier, 'accepted', 'good', records[identifier]['sha256']) + for identifier in ids[:6]] + [_row(ids[6], 'rejected', None)]) + self.write_lines('captions', [_row(ids[0], 'accepted', 'the first item', records[ids[0]]['sha256'])]) + self.write_lines('unrelated', [_row(ids[0], 'accepted', None)]) + self.commit('Annotations.') + done = self.build('datasets/frozen') + self.assertEqual([step['reference'] for step in done['steps']], ['datasets/frozen']) + frozen_product = self.product('datasets/frozen') + frozen = _records(frozen_product['directory']) + self.assertEqual([record['split'] for record in frozen], ['test'] + ['train'] * 5) # 6 cut 1:3 + self.assertEqual({record['id'] for record in frozen}, set(ids[:6])) + first = next(record for record in frozen if record['id'] == ids[0]) + self.assertEqual(first['annotations'], {'quality': {'state': 'accepted', 'value': 'good'}, + 'captions': {'state': 'accepted', 'value': 'the first item'}}) + with self.opened() as project: + row = builds.run_details(project, frozen_product['run_id']) + covered = build_requests.covers(project, plan.build_plan(project, ['datasets/frozen']), + ['datasets/frozen'], every=False, scratch=False) + quality = (self.folder / 'annotations' / 'quality.jsonl').read_bytes() + self.assertEqual(row['annotations']['annotations/quality']['sha256'], _sha(quality)) + self.assertEqual(row['annotations']['annotations/quality']['file'], 'annotations/quality.jsonl') + self.assertEqual(set(row['annotations']), {'annotations/quality', 'annotations/captions'}) + self.assertIn('annotations/quality', covered['definitions']) + self.assertIn('annotations/captions', covered['definitions']) + self.assertIsNone(row['environment']) + self.assertEqual(self.status()['datasets/frozen']['state'], 'built') + # The frozen product is read by spec-d1's readers, with its splits and annotations. + listed = inside.records(inside.Product(frozen_product['run_id'], frozen_product['directory']), limit=200) + self.assertEqual((listed['splits'], listed['problems']), ({'train': 5, 'test': 1}, [])) + self.assertEqual(next(record for record in listed['records'] if record['id'] == ids[0])['annotations'], + first['annotations']) + + # Another task's file changes: still built. + self.write_lines('unrelated', [_row(ids[1], 'accepted', None)]) + self.commit('Another task.') + self.assertEqual(self.status()['datasets/frozen']['state'], 'built') + # One of its tasks' files changes but is not committed: the commit a build would use is unchanged. + self.write_lines('quality', [_row(ids[0], 'rejected', None)]) + self.assertEqual(self.status()['datasets/frozen']['state'], 'built') + self.commit('Fewer accepted.') + entry = self.status()['datasets/frozen'] + self.assertEqual(entry['state'], 'out-of-date') + self.assertEqual(entry['causes'], [f'the annotations of annotations/quality (annotations/quality.jsonl) changed ' + f'since run {frozen_product["run_id"][:12]}']) + self.assertEqual(self.status()['datasets/raw']['state'], 'built') + done = self.build('datasets/frozen') + self.assertEqual(_records(self.product('datasets/frozen')['directory']), []) + self.assertEqual(self.status()['datasets/frozen']['state'], 'built') + # A file removed is a cause too. + os.remove(self.folder / 'annotations' / 'captions.jsonl') + self.commit('No captions.') + self.assertIn('are gone since run', self.status()['datasets/frozen']['causes'][0]) + + def test_the_source_changing_puts_an_import_out_of_date(self): + self.build('datasets/raw') + (self.root / 'code' / 'data' / 'item-0.txt').write_text('changed\n', encoding='utf-8') + self.commit('A source file changed.') + causes = self.status()['datasets/raw']['causes'] + self.assertEqual(len(causes), 1) + self.assertTrue(causes[0].startswith('its source data changed since commit '), causes) + self.assertTrue(causes[0].endswith(': data/item-0.txt'), causes) + + def test_a_scratch_freeze_reads_the_working_tree(self): + self.build('datasets/raw') + records = {record['id']: record for record in _records(self.product('datasets/raw')['directory'])} + self.write_lines('quality', [_row(identifier, 'accepted', 'good', record['sha256']) + for identifier, record in records.items()]) + self.build('datasets/frozen', scratch=True) + self.assertEqual(len(_records(self.product('datasets/frozen')['directory'])), 8) + self.assertEqual(self.status()['datasets/frozen']['state'], 'built') + self.write_lines('quality', [_row('item-0.txt', 'accepted', 'bad', records['item-0.txt']['sha256'])]) + self.assertIn('annotations/quality', self.status()['datasets/frozen']['causes'][0]) + + def test_a_step_is_cancelled_like_any_run(self): + # The cancel file is written before the custodian first looks, while the step is still starting. + for number in range(200): + (self.root / 'code' / 'data' / f'bulk-{number:05}.txt').write_text(str(number), encoding='utf-8') + self.commit('Many files.') + with self.opened() as project: + made = plan.build_plan(project, ['datasets/raw']) + + def on_event(kind, item): + if kind == 'start': + Path(item['directory'], 'cancel').touch() + + done = builds.execute(self.folder, made, confirm=lambda given: True, on_event=on_event) + self.assertFalse(done['ok']) + self.assertEqual(done['steps'][0]['state'], 'cancelled') + + +if __name__ == '__main__': + unittest.main() diff --git a/tuldok_project/__main__.py b/tuldok_project/__main__.py index 7ec8c0fd..7dd591d7 100644 --- a/tuldok_project/__main__.py +++ b/tuldok_project/__main__.py @@ -900,6 +900,8 @@ def _show_run(row, event): label = 'subject recipe' if name == '{recipe}' else f'input {name}' output = f' ({used["output"]})' if used.get('output') else '' rows.append((label, f'{used["reference"]}{output}, run {used["run_id"]}')) + for task, read in sorted((row.get('annotations') or {}).items()): + rows.append((f'task {task}', f'{read["file"]}, sha256 {(read["sha256"] or "none (no file)")[:16]}')) product = row['product'] if product is not None: rows.append(('product', product['directory'] + (' (adopted)' if product['adopted'] else '') diff --git a/tuldok_project/build_requests.py b/tuldok_project/build_requests.py index 2cbfd8a7..53ad8d75 100644 --- a/tuldok_project/build_requests.py +++ b/tuldok_project/build_requests.py @@ -91,7 +91,8 @@ def covers(project, made, targets, *, every, scratch): steps are the plan's build steps in order, each with the benchmark subjects execute would run (those to run that are not built yet); definitions has the SHA-256 of the text of every reference in the plan's - steps, whatever its action. + steps, whatever its action, and of the tasks a freeze among them reads + (whose line files the commit covers, as it covers code). """ status = builds.status(project) steps = [] @@ -103,7 +104,8 @@ def covers(project, made, targets, *, every, scratch): held = (status.get(step['reference']) or {}).get('subjects') or {} subjects = [name for name in step['subjects']['run'] if (held.get(name) or {}).get('state') != 'built'] steps.append({'reference': step['reference'], 'subjects': subjects}) - references = sorted({step['reference'] for step in made['steps']}) + references = sorted({step['reference'] for step in made['steps']} + | {task for step in made['steps'] for task in step.get('annotations') or ()}) texts = dict(project._execute(f'SELECT {store._REFERENCE_SQL}, text FROM {{schema}}.definitions ' f'WHERE NOT removed AND {store._REFERENCE_SQL} = ANY(%s)', (references,)).fetchall()) return {'targets': list(targets), 'every': bool(every), 'scratch': bool(scratch), diff --git a/tuldok_project/builds.py b/tuldok_project/builds.py index 0f1d2001..91c68b13 100644 --- a/tuldok_project/builds.py +++ b/tuldok_project/builds.py @@ -17,7 +17,11 @@ except an estimate's throwaway directory. A run in state adopted ran nothing: adoption.py recorded files made elsewhere as its product, and status counts that product built without comparing anything (spec-m8.md -section 3); a later build replaces it like any other. +section 3); a later build replaces it like any other. A dataset whose run +names a step Tuldok provides (spec-d4.md section 6) runs steps.py with +Tuldok's own interpreter and code, no environment; a freeze's run records the +line files of its tasks as it read them from the commit, and the product is +out of date when one of them differs at HEAD (_LineFiles). What a person needs while and after a build runs (sections 7 and 8): a run is named by its id or an unambiguous prefix of it (find_run); run_details reads @@ -42,13 +46,15 @@ import re import shutil import stat +import sys import time import uuid from psycopg import sql from psycopg.types.json import Jsonb -from . import documents, environments, graph, launcher, local, result_rows, snapshot, store +from . import annotations, documents, environments, graph, launcher, local, result_rows, snapshot, store +from . import folder as folder_reader BUILT_KINDS = ('dataset', 'recipe', 'step', 'benchmark') ACTIVE = ('queued', 'running') @@ -73,6 +79,11 @@ ESTIMATE_OUTPUT_LIMIT = 64 * 1024 # bytes of standard output an estimate may print ESTIMATE_FIELDS = ('disk_bytes', 'wall_seconds', 'items') _RUN_TEXT = re.compile(r'[A-Za-z0-9][A-Za-z0-9_.-]{0,127}') +# A step Tuldok provides (spec-d4.md section 6) runs this module with Tuldok's own interpreter, from Tuldok's root. +STEPS_MODULE = 'tuldok_project.steps' +TULDOK_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) +STEP_TASKS_FILE = 'tasks.json' # /tasks.json: what a freeze is told of its tasks +STEP_LINES = 'annotations' # /annotations/.jsonl: the line files a freeze read TABLES = ( '''CREATE TABLE IF NOT EXISTS {schema}.plans ( @@ -93,6 +104,8 @@ exit_status integer, seconds double precision, bytes bigint, strays integer, problem text)''', 'CREATE INDEX IF NOT EXISTS runs_reference ON {schema}.runs (reference, subject, queued_at)', + # A freeze's run records each task's line file as it read it: {task: {file, sha256, blob}} (spec-d4.md section 6). + 'ALTER TABLE {schema}.runs ADD COLUMN IF NOT EXISTS annotations jsonb', '''CREATE TABLE IF NOT EXISTS {schema}.products ( run_id text PRIMARY KEY, reference text NOT NULL, subject text NOT NULL DEFAULT '', @@ -107,7 +120,7 @@ _RUN_COLUMNS = ('id', 'reference', 'subject', 'plan_id', 'state', 'scratch', 'commit', 'inputs', 'environment', 'argv', 'directory', 'owner_pid', 'owner_boot', 'queued_at', 'started_at', 'finished_at', 'exit_status', 'seconds', 'bytes', 'strays', 'problem') -_DETAIL_COLUMNS = _RUN_COLUMNS + ('definition', 'settings', 'env') +_DETAIL_COLUMNS = _RUN_COLUMNS + ('definition', 'settings', 'env', 'annotations') def _q(schema, template): @@ -276,11 +289,108 @@ def _own_causes(document, text, product, current, changes, code_root): sources = [source for source in _run_block(document).get('sources', []) if isinstance(source, str)] hits = sorted(path for path in changed if any(_under(path, source) for source in sources)) if hits: - shown = ', '.join(hits[:3]) + (f' and {len(hits) - 3} more' if len(hits) > 3 else '') - causes.append(f'its code changed since commit {product["commit"][:12]}: {shown}') + causes.append(f'its code changed since commit {product["commit"][:12]}: {_named(hits)}') + source = import_source(document) + hits = sorted(path for path in changed if source is not None and _under(path, source)) + if hits: + causes.append(f'its source {source} changed since commit {product["commit"][:12]}: {_named(hits)}') return causes +def _named(paths): + return ', '.join(paths[:3]) + (f' and {len(paths) - 3} more' if len(paths) > 3 else '') + + +def import_source(document): + """The source of an import step when it is relative to the code root (read from the commit), else None.""" + run = _run_block(document) + settings = run.get('settings') if isinstance(run.get('settings'), dict) else {} + source = settings.get('source') + if run.get('step') == 'import' and isinstance(source, str) and source and not source.startswith('/'): + return source + return None + + +def step_tasks(document): + """The tasks a freeze step names in run.annotations (references, in order); empty for any other run.""" + run = _run_block(document) + tasks = run.get('annotations') if run.get('step') == 'freeze' else None + return [task for task in (tasks if isinstance(tasks, list) else ()) if isinstance(task, str)] + + +_LINE_HASHES = {} # (path, size, mtime_ns, inode) -> SHA-256 of a working-tree line file, for scratch products +_LINE_HASHES_KEPT = 256 + + +class _LineFiles: + """The tasks' line files as a build would read them now, for the out-of-date state of a frozen dataset. + + A product built from a commit is compared with the code root's HEAD (the + commit a build would use), a scratch product with the working tree. + Nothing is read for a file whose Git blob is the one the run recorded. + """ + _UNKNOWN = object() + + def __init__(self, folder, code_root): + self.folder, self.code_root = folder, code_root + self._head = None + self._looked = False + + def head(self): + if not self._looked: + self._looked = True + try: + if snapshot._repository(self.folder)[0] == snapshot._repository(self.code_root)[0]: + self._head = snapshot._head(self.code_root) + except snapshot.SnapshotError: + self._head = None + return self._head + + def now(self, item, scratch): + """The SHA-256 of the file now, None when there is none, or _UNKNOWN when it cannot be told.""" + if scratch: + path = os.path.join(self.folder, item['file']) + try: + info = os.stat(path) + except FileNotFoundError: + return None + except OSError: + return self._UNKNOWN + key = (path, info.st_size, info.st_mtime_ns, info.st_ino) + if key not in _LINE_HASHES: + try: + with open(path, 'rb') as handle: + _LINE_HASHES[key] = hashlib.sha256(handle.read()).hexdigest() + except OSError: + return self._UNKNOWN + while len(_LINE_HASHES) > _LINE_HASHES_KEPT: + _LINE_HASHES.pop(next(iter(_LINE_HASHES))) + return _LINE_HASHES[key] + head = self.head() + if head is None: + return self._UNKNOWN + try: + found = snapshot.file_at(self.folder, head, item['file'], None) + if found is None: + return None + if found[0] == item.get('blob'): + return item['sha256'] + return hashlib.sha256(snapshot.file_at(self.folder, head, item['file'], annotations.FILE_LIMIT)[1] + ).hexdigest() + except (snapshot.SnapshotError, TypeError): + return self._UNKNOWN + + def causes(self, product): + found = [] + for reference, item in sorted((product.get('annotations') or {}).items()): + now = self.now(item, product['scratch']) + if now is self._UNKNOWN or now == item.get('sha256'): + continue + was = 'are gone' if now is None else 'changed' + found.append(f'the annotations of {reference} ({item["file"]}) {was} since run {_short(product["run_id"])}') + return found + + def status(project): """{reference: {state, causes, scratch, adopted, subjects}} for every dataset, recipe, step and benchmark with runs or products. @@ -301,13 +411,14 @@ def status(project): texts = {reference: text for reference, text, _ in rows} definitions = {reference: document for reference, _, document in rows} current = {} - for (run_id, reference, subject, outputs, scratch, commit, definition, settings, inputs, state) in connection.execute(_q( + for (run_id, reference, subject, outputs, scratch, commit, definition, settings, inputs, state, + read) in connection.execute(_q( schema, '''SELECT p.run_id, p.reference, p.subject, p.outputs, r.scratch, r.commit, r.definition, - r.settings, r.inputs, r.state + r.settings, r.inputs, r.state, r.annotations FROM {schema}.products p JOIN {schema}.runs r ON r.id = p.run_id WHERE p.current''')): current[reference, subject] = {'run_id': run_id, 'outputs': outputs, 'scratch': scratch, 'commit': commit, 'definition': definition, 'settings': settings, 'inputs': inputs, - 'adopted': state == ADOPTED} + 'adopted': state == ADOPTED, 'annotations': read} latest = {reference: (run_id, state, problem) for reference, run_id, state, problem in connection.execute(_q( schema, '''SELECT DISTINCT ON (reference) reference, id, state, problem FROM {schema}.runs ORDER BY reference, queued_at DESC, id''')).fetchall()} @@ -317,6 +428,7 @@ def status(project): changes = _changes(code_root, {product['commit'] for product in current.values() if not product['scratch'] and product['commit']}) if current else {} held = graph.states(definitions, {reference: 'built' for reference, subject in current if not subject}) + line_files = _LineFiles(project._state()['folder'], code_root) if current else None found = {} out_of_date = set() @@ -329,6 +441,8 @@ def judge(reference, document, subject=None): return {'state': 'built', 'causes': [], 'run_id': product['run_id'], 'scratch': False, 'adopted': True} product = {**product, 'subject_document': subject} causes = _own_causes(document, texts[reference], product, current, changes, code_root) + if product['annotations']: + causes += line_files.causes(product) for key, used in _uses(document, subject).items(): if used in out_of_date and not any(cause.startswith(_input_words(key, used)) for cause in causes): causes.append(f'{_input_words(key, used)} is out of date') @@ -582,6 +696,9 @@ def _resolve(self, project, reference, subject, *, estimate=False): output = os.path.join(run_directory, OUTPUT) estimate_block = run.get('estimate') if isinstance(run.get('estimate'), dict) else {} command = list(estimate_block.get('command') or []) if estimate else list(run.get('command') or []) + step = None if estimate or not isinstance(run.get('step'), str) else run['step'] + if step is not None: + command = ['tuldok', step] # replaced by the step's own argv below values, missing, recorded = {'output': output}, {}, {} environment_record = None @@ -593,7 +710,7 @@ def _resolve(self, project, reference, subject, *, estimate=False): prepared = {'id': run_id, 'reference': reference, 'subject': subject['name'] if subject else '', 'definition': text, 'settings': None, 'environment': environment_record, 'directory': run_directory, 'argv': list(command), 'env': {}, - 'problem': None, 'skipped': False} + 'problem': None, 'skipped': False, 'annotations': None, 'files': {}} try: if not command: raise StepProblem(f'{reference} has no run.estimate.command.' if estimate else @@ -640,21 +757,11 @@ def _resolve(self, project, reference, subject, *, estimate=False): if prepared['settings'] is None: raise StepProblem(f'Its settings file {run["settings_file"]} cannot be read in the code ' f'at commit {self.code.commit[:12] or "(none)"}.') - argv = [_fill(part, values, missing, f'The command word {part!r}') for part in command] - if command[0] == 'python': - if environment_record is None: - raise StepProblem('The command starts with python but the run names no environment.') - argv[0] = environment_record['interpreter'] - elif '/' in argv[0]: - program = os.path.join(self.code.code_root, argv[0]) - if not (os.path.isfile(program) and os.access(program, os.X_OK)): - raise StepProblem(f'The program {argv[0]} is not an executable file in the code.') - argv[0] = program + if step is not None: + argv = self._step_argv(project, reference, run, step, values, prepared) else: - program = shutil.which(argv[0], path=os.environ.get('PATH', os.defpath)) - if program is None: - raise StepProblem(f'The program {argv[0]} was not found on PATH.') - argv[0] = program + argv = [_fill(part, values, missing, f'The command word {part!r}') for part in command] + argv[0] = self._program(command, argv, environment_record) prepared['argv'] = argv resources = run.get('resources') if isinstance(run.get('resources'), dict) else {} gpu = resources.get('gpu') is True @@ -667,6 +774,9 @@ def _resolve(self, project, reference, subject, *, estimate=False): for key, value in (run.get('env') or {}).items(): env[key] = _fill(value, values, missing, f'The value of env {key}') env.update(self.extra_env) + if step is not None: + # Tuldok's own code first; the snapshot's code (the working directory) never importable. + env.update(PYTHONSAFEPATH='1', PYTHONPATH=TULDOK_ROOT) prepared['env'] = env wall_hours = resources.get('wall_hours') or DEFAULT_WALL_HOURS disk_gb = resources.get('disk_gb') or DEFAULT_DISK_GB @@ -683,6 +793,95 @@ def _resolve(self, project, reference, subject, *, estimate=False): prepared['inline_settings'] = 'settings' in run return prepared + def _program(self, command, argv, environment_record): + """The program a command runs: the environment's interpreter for python, a file in the code, or one on PATH.""" + if command[0] == 'python': + if environment_record is None: + raise StepProblem('The command starts with python but the run names no environment.') + return environment_record['interpreter'] + if '/' in argv[0]: + program = os.path.join(self.code.code_root, argv[0]) + if not (os.path.isfile(program) and os.access(program, os.X_OK)): + raise StepProblem(f'The program {argv[0]} is not an executable file in the code.') + return program + program = shutil.which(argv[0], path=os.environ.get('PATH', os.defpath)) + if program is None: + raise StepProblem(f'The program {argv[0]} was not found on PATH.') + return program + + def _step_argv(self, project, reference, run, step, values, prepared): + """The argv of a step Tuldok provides; for a freeze, the line files read and what the step is told of them.""" + if 'settings' not in values: + raise StepProblem(f'{reference} runs the step {step}, which needs run.settings.') + argv = [sys.executable, '-m', STEPS_MODULE, step, values['settings'], values['output']] + if step == 'import': + return argv + ['--code', self.code.code_root] + if step != 'freeze': + raise StepProblem(f'Tuldok provides no step {step!r}; use import or freeze.') + inputs = _declared_inputs({'run': run}) + used = inputs.get('records', (None, None))[0] + if 'inputs.records' not in values or used is None: + raise StepProblem('A freeze reads the records of its input records; declare run.inputs.records.') + tasks = step_tasks({'run': run}) + if not tasks: + raise StepProblem('A freeze needs one or more tasks in run.annotations.') + documents_ = {row[0]: row[1] for row in project._execute( + f'SELECT {store._REFERENCE_SQL}, document FROM {{schema}}.definitions ' + f'WHERE NOT removed AND {store._REFERENCE_SQL} = ANY(%s)', ([*tasks, used],)).fetchall()} + described, read = [], {} + for task in tasks: + document = documents_.get(task) + if document is None: + raise StepProblem(f'Its task {task} does not exist.') + if document.get('dataset') != used: + raise StepProblem(f'Its task {task} annotates {document.get("dataset")}, not its input {used}.') + name = documents.parse_reference(task)[1] + file = f'{folder_reader.ANNOTATIONS}/{name}{folder_reader.LINES_SUFFIX}' + blob, data = self._line_file(project, file) + digest = None if data is None else hashlib.sha256(data).hexdigest() + read[task] = {'file': file, 'sha256': digest, 'blob': blob} + copy = None + if data is not None: + copy = os.path.join(prepared['directory'], STEP_LINES, f'{name}{folder_reader.LINES_SUFFIX}') + prepared['files'][copy] = data + described.append({'reference': task, 'task': document.get('task'), + 'vocabulary': document.get('vocabulary') or [], 'lines': copy, 'sha256': digest}) + view = (documents_.get(used) or {}).get('view') + tasks_file = os.path.join(prepared['directory'], STEP_TASKS_FILE) + prepared['files'][tasks_file] = (json.dumps({'tasks': described, 'view': view}, ensure_ascii=False, + indent=2) + '\n').encode('utf-8') + prepared['annotations'] = read + return argv + ['--records', values['inputs.records'], '--tasks', tasks_file] + + def _line_file(self, project, file): + """(Git blob id or None, bytes or None) of a line file, relative to the project folder, as this build reads it. + + From the build's commit (annotations not committed are not frozen, as + code is not); a scratch build reads the working tree. + """ + folder = project._state()['folder'] + if self.code.scratch: + path = os.path.join(folder, file) + if not os.path.isfile(path): + return None, None + with open(path, 'rb') as handle: + data = handle.read(annotations.FILE_LIMIT + 1) + if len(data) > annotations.FILE_LIMIT: + raise StepProblem(f'{file} is over {annotations.FILE_LIMIT} bytes.') + return None, data + try: + same = snapshot._repository(folder)[0] == snapshot._repository(_code_root(project))[0] + except snapshot.SnapshotError: + same = False + if not same: + raise StepProblem(f'The project folder is not in the Git repository of the code, so {file} cannot be ' + f'read from commit {self.code.commit[:12]}; commit it there, or build with scratch.') + try: + found = snapshot.file_at(folder, self.code.commit, file, annotations.FILE_LIMIT) + except snapshot.SnapshotError as exc: + raise StepProblem(str(exc)) from None + return found if found is not None else (None, None) + def _check_expected(self, project, reference, text, run, subject): """Refuse (stale) a step when a definition it reads to run is not the text whose SHA-256 expect holds. @@ -690,6 +889,7 @@ def _check_expected(self, project, reference, text, run, subject): environment and, for a benchmark subject, the subject's recipe. """ others = [used for used in (run.get('environment'), (subject or {}).get('recipe')) if isinstance(used, str)] + others += step_tasks({'run': run}) texts = dict(project._execute(f'SELECT {store._REFERENCE_SQL}, text FROM {{schema}}.definitions ' f'WHERE NOT removed AND {store._REFERENCE_SQL} = ANY(%s)', (others,)).fetchall()) texts[reference] = text @@ -703,15 +903,16 @@ def _check_expected(self, project, reference, text, run, subject): def _insert(self, project, prepared, state): project._execute('''INSERT INTO {schema}.runs (id, reference, subject, plan_id, state, scratch, commit, definition, settings, inputs, environment, argv, env, directory, owner_pid, - owner_boot, queued_at, started_at, finished_at, problem) + owner_boot, queued_at, started_at, finished_at, problem, annotations) VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, now(), CASE WHEN %s = 'running' THEN now() END, - CASE WHEN %s = 'running' THEN NULL ELSE now() END, %s)''', + CASE WHEN %s = 'running' THEN NULL ELSE now() END, %s, %s)''', (prepared['id'], prepared['reference'], prepared['subject'], self.plan_id, state, self.code.scratch, self.code.commit, prepared['definition'], prepared['settings'], Jsonb(prepared['inputs']), Jsonb(prepared['environment']) if prepared['environment'] else None, Jsonb(prepared['argv']), Jsonb(prepared['env']), prepared['directory'], os.getpid(), - self.boot, state, state, prepared['problem'])) + self.boot, state, state, prepared['problem'], + Jsonb(prepared['annotations']) if prepared['annotations'] is not None else None)) # ------------------------------------------------------------------- run @@ -729,6 +930,10 @@ def run_one(self, reference, subject=None): if prepared['inline_settings']: with open(os.path.join(prepared['directory'], SETTINGS_FILE), 'w', encoding='utf-8') as handle: handle.write(prepared['settings']) + for path, data in prepared['files'].items(): + os.makedirs(os.path.dirname(path), exist_ok=True) + with open(path, 'xb') as handle: + handle.write(data) self._insert(project, prepared, 'running') self.on_event('start', item) try: diff --git a/tuldok_project/check.py b/tuldok_project/check.py index 80f80bf4..ce0b76a8 100644 --- a/tuldok_project/check.py +++ b/tuldok_project/check.py @@ -8,8 +8,10 @@ outputs, charts against their benchmark, cycles, paths into the code root (in definitions and in the code_paths of tuldok.json), the map's fields (spec-w1.md section 1): groups, a recipe's group, derived_from and -compared_with, and map.chart, and each annotations/.jsonl against its -task (spec-d4.md section 2; the rules of a line are annotations.py's). +compared_with, and map.chart, each annotations/.jsonl against its +task (spec-d4.md section 2; the rules of a line are annotations.py's), and +the settings, inputs and tasks of a dataset whose run names a step Tuldok +provides (section 6). Problems are collected, never raised, so one bad file never hides another. """ from dataclasses import dataclass, field @@ -71,6 +73,7 @@ def add(severity, path, pointer, message): check_code_paths(definition, code_root, add) check_references(definitions, add) + check_steps(definitions, add) check_charts(definitions, unsound, add) check_cycles(definitions, add) check_map(project, definitions, add) @@ -111,6 +114,8 @@ def check_definition(definition, notes, add): _check_benchmark(document, path, add) if definition.kind == 'dataset' and isinstance(document.get('view'), dict): _check_view(document['view'], path, add) + if definition.kind == 'dataset' and isinstance(run, dict) and run.get('step') in STEP_SETTINGS: + _check_step(run, path, add) def _check_view(view, path, add): @@ -123,6 +128,129 @@ def _check_view(view, path, add): add('error', path, documents.pointer('view', key), wrong) +# The settings of each step Tuldok provides (spec-d4.md section 6): {member: required}. +STEP_SETTINGS = {'import': {'source': True, 'pattern': False, 'kind': False, 'rights': True, 'lines': False}, + 'freeze': {'seed': True, 'shares': True, 'include': False}} +SEED_LIMIT = 2 ** 63 +SHARES_LIMIT = 16 +SHARE_LIMIT = 1_000_000 +RIGHTS_LIMIT = 1000 + + +def _check_step(run, path, add): + """The settings, inputs and tasks of a run that names a step Tuldok provides.""" + step = run['step'] + settings = run.get('settings') + if 'settings' not in run: + add('error', path, '/run/settings', f'Add the required field \'settings\'; the step {step} needs ' + + ' and '.join(key for key, needed in STEP_SETTINGS[step].items() if needed) + + '.') + if isinstance(settings, dict): + for key in settings: + if key not in STEP_SETTINGS[step]: + add('error', path, documents.pointer('run', 'settings', key), + f'Remove the unknown setting {key!r}; the step {step} takes ' + + ', '.join(STEP_SETTINGS[step]) + '.') + for key, needed in STEP_SETTINGS[step].items(): + if needed and key not in settings: + add('error', path, documents.pointer('run', 'settings', key), + f'Add the required setting {key!r} of the step {step}.') + settings = settings if isinstance(settings, dict) else {} + where = lambda key: documents.pointer('run', 'settings', key) # noqa: E731 + if step == 'import': + _check_import(settings, path, where, add) + if 'inputs' in run: + add('error', path, '/run/inputs', 'The step import reads files, not other products; remove inputs.') + if 'annotations' in run: + add('error', path, '/run/annotations', 'Only the step freeze reads annotations; remove annotations.') + else: + _check_freeze(run, settings, path, where, add) + + +def _check_import(settings, path, where, add): + source = settings.get('source') + if 'source' in settings: + if not isinstance(source, str) or not source or len(source) > 1024 or '\x00' in source: + add('error', path, where('source'), 'The source must be a directory: a path of 1 to 1,024 characters.') + elif source.startswith('/'): + add('warning', path, where('source'), f'The source {source} is absolute, so this dataset can be built ' + 'on this machine only; give a path relative to the code root.') + if 'pattern' in settings: + pattern = settings['pattern'] + wrong = documents.relative_path_problem(pattern) if isinstance(pattern, str) else 'must be a string' + if not wrong and len(pattern) > 1024: + wrong = 'is longer than 1,024 characters' + if not wrong and '!' in pattern: + wrong = "reaches into an archive with '!', which import does not do" + if wrong: + add('error', path, where('pattern'), f'The pattern {pattern!r} {wrong}.') + if 'kind' in settings and settings['kind'] not in annotations.RECORD_KINDS: + add('error', path, where('kind'), f'The kind {settings["kind"]!r} is not one of ' + ', '.join(annotations.RECORD_KINDS) + + '.') + rights = settings.get('rights') + if 'rights' in settings and (not isinstance(rights, str) or not rights.strip() or len(rights) > RIGHTS_LIMIT): + add('error', path, where('rights'), f'rights must be a sentence of 1 to {RIGHTS_LIMIT:,} characters on ' + 'what may be done with the files.') + if 'lines' in settings and not isinstance(settings['lines'], bool): + add('error', path, where('lines'), 'lines must be true or false.') + + +def _check_freeze(run, settings, path, where, add): + inputs = run.get('inputs') + if not isinstance(inputs, dict) or set(inputs) != {'records'} or not isinstance(inputs['records'], str) \ + or not inputs['records'].startswith('datasets/'): + add('error', path, '/run/inputs', 'The step freeze takes one input, records, naming a dataset: ' + '"inputs": {"records": "datasets/"}.') + if 'annotations' not in run: + add('error', path, '/run/annotations', "Add the required field 'annotations': the tasks the step freeze " + 'reads, the first deciding which records are taken.') + seed = settings.get('seed') + if 'seed' in settings and (type(seed) is not int or not -SEED_LIMIT <= seed < SEED_LIMIT): + add('error', path, where('seed'), 'The seed must be an integer of at most 63 bits.') + shares = settings.get('shares') + if 'shares' in settings: + if not isinstance(shares, dict) or not 1 <= len(shares) <= SHARES_LIMIT: + add('error', path, where('shares'), f'shares must be an object of 1 to {SHARES_LIMIT} splits and their ' + 'relative sizes, such as {"train": 8, "validation": 1, "test": 1}.') + else: + for name, size in shares.items(): + if not documents.NAME.match(name) or len(name) > 32: + add('error', path, documents.pointer('run', 'settings', 'shares', name), + f'The split name {name!r} must be 1 to 32 characters of a-z 0-9 . _ -, starting with a ' + 'letter or digit.') + if type(size) is not int or not 0 <= size <= SHARE_LIMIT: + add('error', path, documents.pointer('run', 'settings', 'shares', name), + f'The share of {name!r} must be an integer from 0 to {SHARE_LIMIT:,}.') + if all(type(size) is int for size in shares.values()) and not any(shares.values()): + add('error', path, where('shares'), 'At least one share must be above 0.') + include = settings.get('include') + if 'include' in settings: + if not isinstance(include, list) or not include or len(set(map(str, include))) != len(include) \ + or any(state not in annotations.STATES for state in include): + add('error', path, where('include'), 'include must be a list of different states: ' + + ', '.join(annotations.STATES) + '.') + + +def check_steps(definitions, add): + """Report each task of a freeze that annotates another dataset than the freeze's input (a missing one is + check_references' problem).""" + for definition in definitions.values(): + run = definition.document.get('run') if isinstance(definition.document, dict) else None + if definition.kind != 'dataset' or not isinstance(run, dict) or run.get('step') != 'freeze': + continue + inputs = run.get('inputs') if isinstance(run.get('inputs'), dict) else {} + used = inputs.get('records') if isinstance(inputs.get('records'), str) else None + tasks = run.get('annotations') if isinstance(run.get('annotations'), list) else [] + for index, task in enumerate(tasks): + target = definitions.get(task) if isinstance(task, str) else None + if target is None or target.kind != 'annotation' or not isinstance(target.document, dict): + continue + if used is not None and target.document.get('dataset') != used: + add('error', definition.path, documents.pointer('run', 'annotations', index), + f'{task} annotates {target.document.get("dataset")}, not {used}, the input of this freeze; ' + 'name a task of its input.') + + def _check_run(run, path, *, benchmark, add): inputs = set(run['inputs']) if isinstance(run.get('inputs'), dict) else set() context = {'inputs': inputs, 'has_settings': 'settings' in run or 'settings_file' in run, 'benchmark': benchmark} @@ -211,6 +339,10 @@ def sources(holder, *prefix): if 'settings_file' in run: yield '/run/settings_file', run['settings_file'] yield from sources(run, 'run') + settings = run.get('settings') + source = settings.get('source') if run.get('step') == 'import' and isinstance(settings, dict) else None + if isinstance(source, str) and source and not source.startswith('/'): + yield '/run/settings/source', source # relative to the code root, read from the commit if 'config_file' in document: yield '/config_file', document['config_file'] yield from sources(document) diff --git a/tuldok_project/documents.py b/tuldok_project/documents.py index 79a88715..93152a24 100644 --- a/tuldok_project/documents.py +++ b/tuldok_project/documents.py @@ -45,6 +45,7 @@ 'cases': ('datasets',), 'benchmark': ('benchmarks',), 'dataset': ('datasets',), + 'annotations': ('annotations',), 'derived': ('recipes',), 'compared': ('recipes',), } diff --git a/tuldok_project/graph.py b/tuldok_project/graph.py index a058c7f6..6c76e594 100644 --- a/tuldok_project/graph.py +++ b/tuldok_project/graph.py @@ -4,7 +4,9 @@ Every function is pure and takes `definitions`, a mapping of reference (such as 'datasets/x') to decoded document. Documents need not be valid: fields of the wrong type are skipped, so the graph can be read even from a folder with problems. -An annotation task uses its dataset in the role dataset (spec-d4.md section 1). +An annotation task uses its dataset in the role dataset (spec-d4.md section 1), +and a freeze step its tasks in the role annotations (section 6): an edge for +order() and cycles(), which carries no state and which a plan does not follow. Edges whose target is not in `definitions` are kept by edges() and uses() but ignored by order() and cycles(). The two roles of a recipe's place on the map (spec-w1.md section 1), derived and compared, are edges like the others for @@ -60,6 +62,10 @@ def uses(document): found.append(Use(f'input:{name}', documents.pointer('run', 'inputs', name, 'from'), value['from'], output)) if isinstance(run.get('environment'), str): found.append(Use('environment', '/run/environment', run['environment'])) + tasks = run.get('annotations') + for index, task in enumerate(tasks if isinstance(tasks, list) else ()): + if isinstance(task, str): + found.append(Use('annotations', documents.pointer('run', 'annotations', index), task)) kind = document.get('kind') if kind == 'recipe' and isinstance(document.get('model'), str): found.append(Use('model', '/model', document['model'])) diff --git a/tuldok_project/inside.py b/tuldok_project/inside.py index e6c689b8..1b7ecb6b 100644 --- a/tuldok_project/inside.py +++ b/tuldok_project/inside.py @@ -135,10 +135,14 @@ def finish(self): def _record(identifier, kind, path, *, size=None, **extra): return {'id': identifier, 'kind': kind, 'path': path, 'bytes': size, 'text': None, 'array': None, 'split': None, - 'rights': None, 'origin': None, 'meta': None, **extra} + 'rights': None, 'origin': None, 'meta': None, 'sha256': None, 'annotations': None, **extra} _LIST_KEYS = ('id', 'kind', 'path', 'text', 'array', 'split', 'rights', 'origin', 'meta') +# Keys import and freeze write (spec-d4.md sections 3 and 6): the content's hash, its size, and a frozen record's +# annotations ({task: {state, value}}). +_STEP_KEYS = ('sha256', 'bytes', 'annotations') +_SHA256 = re.compile(r'[0-9a-f]{64}') def _list_entry(value): @@ -163,15 +167,21 @@ def _list_entry(value): for key in ('array', 'split', 'rights'): if value.get(key) is not None and not isinstance(value[key], str): return f'{key} must be a string' - for key in ('origin', 'meta'): + for key in ('origin', 'meta', 'annotations'): if value.get(key) is not None and not isinstance(value[key], dict): return f'{key} must be an object' + if value.get('sha256') is not None and not (isinstance(value['sha256'], str) and _SHA256.fullmatch(value['sha256'])): + return 'sha256 must be 64 lowercase hexadecimal digits' + size = value.get('bytes') + if size is not None and (type(size) is not int or size < 0): + return 'bytes must be an integer of at least 0' meta = dict(value.get('meta') or {}) for key, item in value.items(): - if key not in _LIST_KEYS: + if key not in _LIST_KEYS and key not in _STEP_KEYS: meta.setdefault(key, item) - return _record(identifier, kind, path, text=text, array=value.get('array'), split=value.get('split'), - rights=value.get('rights'), origin=value.get('origin'), meta=meta or None) + return _record(identifier, kind, path, size=size, text=text, array=value.get('array'), split=value.get('split'), + rights=value.get('rights'), origin=value.get('origin'), meta=meta or None, + sha256=value.get('sha256'), annotations=value.get('annotations')) def _lines(place): @@ -381,7 +391,8 @@ def _preview(product, record): def _shown(product, record, *, preview): - shown = {key: record[key] for key in ('id', 'kind', 'path', 'split', 'rights', 'origin', 'meta')} + shown = {key: record[key] for key in ('id', 'kind', 'path', 'split', 'rights', 'origin', 'meta', 'sha256', + 'annotations')} shown['bytes'] = _size_of(product, record) if record['array'] is not None: shown['array'] = record['array'] diff --git a/tuldok_project/plan.py b/tuldok_project/plan.py index 7d60ea36..c95bf659 100644 --- a/tuldok_project/plan.py +++ b/tuldok_project/plan.py @@ -2,7 +2,8 @@ Owns docs/plans/definition-first-projects/spec-m4.md. make_plan is a pure function of the decoded definitions (reference -> document): it follows the -input, environment and subject edges from the targets, but never out of a +input, environment and subject edges from the targets (a freeze's tasks only +to note one that is missing or on another dataset), but never out of a blocked step or into a blocked subject recipe, puts what it reaches in graph.order, gives each step an action from graph.states (with the environments' states recorded on this machine, spec-m5.md section 5: a ready @@ -126,6 +127,30 @@ def _inputs(document): return found +def _tasks(run): + """The tasks a freeze step reads (run.annotations), in order; empty for any other run.""" + tasks = run.get('annotations') if run.get('step') == 'freeze' else None + return [task for task in (tasks if isinstance(tasks, list) else ()) if isinstance(task, str)] + + +def _task_notes(definitions, reference, document): + """Notes on a freeze's tasks that do not exist or are on another dataset than its input (spec-d4.md section 6). + + The plan follows a step's annotations edges only this far: a task is + never a step. Such a freeze fails before it runs. + """ + used = _inputs(document).get('records', {}).get('reference') + notes = [] + for task in _tasks(_run(document)): + target = definitions.get(task) + if target is None: + notes.append(f'{reference} freezes by {task}, which does not exist; it fails when built.') + elif target.get('dataset') != used: + notes.append(f'{reference} freezes by {task}, which annotates {target.get("dataset")}, not its input ' + f'{used}; it fails when built.') + return notes + + def _resources(document): declared = _run(document).get('resources') declared = declared if isinstance(declared, dict) else {} @@ -226,9 +251,12 @@ def make_plan(definitions, targets, *, every=False, local=None, built=None, esti document, kind = definitions[reference], _kind(reference) run = _run(document) action = actions[reference] + provided = run.get('step') if isinstance(run.get('step'), str) else None step = {'number': number, 'reference': reference, 'kind': kind, 'title': document.get('title'), 'state': states[reference], 'action': action, - 'command': run.get('command'), 'environment': run.get('environment'), + 'command': ['tuldok', provided] if provided else run.get('command'), + 'environment': None if provided else run.get('environment'), + 'step': provided, 'annotations': _tasks(run), 'inputs': _inputs(document), 'resources': _resources(document), 'estimate': (estimates or {}).get(reference), 'blocked_by': [], 'blocked_by_more': 0, @@ -240,6 +268,8 @@ def make_plan(definitions, targets, *, every=False, local=None, built=None, esti if action == 'build' and not step['subjects']['run']: # Nothing would run: blocked, though by no cause of its own. step['action'] = action = actions[reference] = 'blocked' + if provided == 'freeze': + notes.extend(_task_notes(definitions, reference, document)) if action == 'blocked': found = causes(definitions, edges_from, reference) step['blocked_by'] = found[:CAUSE_LIMIT] diff --git a/tuldok_project/schemas/benchmark.schema.json b/tuldok_project/schemas/benchmark.schema.json index e1f55f3b..16e5aea7 100644 --- a/tuldok_project/schemas/benchmark.schema.json +++ b/tuldok_project/schemas/benchmark.schema.json @@ -44,7 +44,13 @@ "$ref": "#/$defs/earlier_work" }, "run": { - "$ref": "#/$defs/run" + "$ref": "#/$defs/run", + "properties": { + "step": { + "not": {}, + "description": "Only a dataset's run may name a step Tuldok provides; give a command." + } + } }, "metrics": { "type": "array", @@ -306,13 +312,17 @@ "run": { "type": "object", "additionalProperties": false, - "required": [ - "command" - ], "properties": { "command": { "$ref": "#/$defs/command" }, + "step": { + "enum": [ + "import", + "freeze" + ], + "description": "a step Tuldok provides: import or freeze" + }, "environment": { "type": "string", "pattern": "^environments/[a-z0-9][a-z0-9._-]{0,119}$", @@ -414,6 +424,17 @@ "$ref": "#/$defs/command" } } + }, + "annotations": { + "type": "array", + "minItems": 1, + "maxItems": 32, + "uniqueItems": true, + "items": { + "type": "string", + "pattern": "^annotations/[a-z0-9][a-z0-9._-]{0,119}$", + "description": "a reference to an annotation task, such as annotations/" + } } }, "dependentSchemas": { @@ -426,27 +447,77 @@ } } }, - "if": { - "required": [ - "command" - ], - "properties": { - "command": { - "type": "array", - "minItems": 1, - "prefixItems": [ - { - "const": "python" + "allOf": [ + { + "if": { + "required": [ + "command" + ], + "properties": { + "command": { + "type": "array", + "minItems": 1, + "prefixItems": [ + { + "const": "python" + } + ] } + } + }, + "then": { + "required": [ + "environment" ] } + }, + { + "if": { + "required": [ + "step" + ] + }, + "then": { + "properties": { + "command": { + "not": {}, + "description": "A run with step has no command; remove one of the two." + }, + "environment": { + "not": {}, + "description": "A step Tuldok provides runs with Tuldok's own interpreter; remove environment." + }, + "outputs": { + "not": {}, + "description": "A step's outputs are fixed by the step; remove outputs." + }, + "settings_file": { + "not": {}, + "description": "A step takes its settings inline; use settings, not settings_file." + }, + "env": { + "not": {}, + "description": "A step Tuldok provides takes no environment variables; remove env." + }, + "estimate": { + "not": {}, + "description": "A step Tuldok provides has no estimate command; remove estimate." + } + } + }, + "else": { + "required": [ + "command" + ], + "properties": { + "annotations": { + "not": {}, + "description": "annotations belong to a run with step freeze; add step or remove annotations." + } + } + } } - }, - "then": { - "required": [ - "environment" - ] - } + ] } } } diff --git a/tuldok_project/schemas/dataset.schema.json b/tuldok_project/schemas/dataset.schema.json index 8a94af79..95ea2ddf 100644 --- a/tuldok_project/schemas/dataset.schema.json +++ b/tuldok_project/schemas/dataset.schema.json @@ -261,13 +261,17 @@ "run": { "type": "object", "additionalProperties": false, - "required": [ - "command" - ], "properties": { "command": { "$ref": "#/$defs/command" }, + "step": { + "enum": [ + "import", + "freeze" + ], + "description": "a step Tuldok provides: import or freeze" + }, "environment": { "type": "string", "pattern": "^environments/[a-z0-9][a-z0-9._-]{0,119}$", @@ -369,6 +373,17 @@ "$ref": "#/$defs/command" } } + }, + "annotations": { + "type": "array", + "minItems": 1, + "maxItems": 32, + "uniqueItems": true, + "items": { + "type": "string", + "pattern": "^annotations/[a-z0-9][a-z0-9._-]{0,119}$", + "description": "a reference to an annotation task, such as annotations/" + } } }, "dependentSchemas": { @@ -381,27 +396,77 @@ } } }, - "if": { - "required": [ - "command" - ], - "properties": { - "command": { - "type": "array", - "minItems": 1, - "prefixItems": [ - { - "const": "python" + "allOf": [ + { + "if": { + "required": [ + "command" + ], + "properties": { + "command": { + "type": "array", + "minItems": 1, + "prefixItems": [ + { + "const": "python" + } + ] } + } + }, + "then": { + "required": [ + "environment" + ] + } + }, + { + "if": { + "required": [ + "step" ] + }, + "then": { + "properties": { + "command": { + "not": {}, + "description": "A run with step has no command; remove one of the two." + }, + "environment": { + "not": {}, + "description": "A step Tuldok provides runs with Tuldok's own interpreter; remove environment." + }, + "outputs": { + "not": {}, + "description": "A step's outputs are fixed by the step; remove outputs." + }, + "settings_file": { + "not": {}, + "description": "A step takes its settings inline; use settings, not settings_file." + }, + "env": { + "not": {}, + "description": "A step Tuldok provides takes no environment variables; remove env." + }, + "estimate": { + "not": {}, + "description": "A step Tuldok provides has no estimate command; remove estimate." + } + } + }, + "else": { + "required": [ + "command" + ], + "properties": { + "annotations": { + "not": {}, + "description": "annotations belong to a run with step freeze; add step or remove annotations." + } + } } } - }, - "then": { - "required": [ - "environment" - ] - } + ] } } } diff --git a/tuldok_project/schemas/recipe.schema.json b/tuldok_project/schemas/recipe.schema.json index 35ee25dc..fd079c6f 100644 --- a/tuldok_project/schemas/recipe.schema.json +++ b/tuldok_project/schemas/recipe.schema.json @@ -42,7 +42,13 @@ "$ref": "#/$defs/earlier_work" }, "run": { - "$ref": "#/$defs/run" + "$ref": "#/$defs/run", + "properties": { + "step": { + "not": {}, + "description": "Only a dataset's run may name a step Tuldok provides; give a command." + } + } }, "model": { "type": "string", @@ -237,13 +243,17 @@ "run": { "type": "object", "additionalProperties": false, - "required": [ - "command" - ], "properties": { "command": { "$ref": "#/$defs/command" }, + "step": { + "enum": [ + "import", + "freeze" + ], + "description": "a step Tuldok provides: import or freeze" + }, "environment": { "type": "string", "pattern": "^environments/[a-z0-9][a-z0-9._-]{0,119}$", @@ -345,6 +355,17 @@ "$ref": "#/$defs/command" } } + }, + "annotations": { + "type": "array", + "minItems": 1, + "maxItems": 32, + "uniqueItems": true, + "items": { + "type": "string", + "pattern": "^annotations/[a-z0-9][a-z0-9._-]{0,119}$", + "description": "a reference to an annotation task, such as annotations/" + } } }, "dependentSchemas": { @@ -357,27 +378,77 @@ } } }, - "if": { - "required": [ - "command" - ], - "properties": { - "command": { - "type": "array", - "minItems": 1, - "prefixItems": [ - { - "const": "python" + "allOf": [ + { + "if": { + "required": [ + "command" + ], + "properties": { + "command": { + "type": "array", + "minItems": 1, + "prefixItems": [ + { + "const": "python" + } + ] } + } + }, + "then": { + "required": [ + "environment" ] } + }, + { + "if": { + "required": [ + "step" + ] + }, + "then": { + "properties": { + "command": { + "not": {}, + "description": "A run with step has no command; remove one of the two." + }, + "environment": { + "not": {}, + "description": "A step Tuldok provides runs with Tuldok's own interpreter; remove environment." + }, + "outputs": { + "not": {}, + "description": "A step's outputs are fixed by the step; remove outputs." + }, + "settings_file": { + "not": {}, + "description": "A step takes its settings inline; use settings, not settings_file." + }, + "env": { + "not": {}, + "description": "A step Tuldok provides takes no environment variables; remove env." + }, + "estimate": { + "not": {}, + "description": "A step Tuldok provides has no estimate command; remove estimate." + } + } + }, + "else": { + "required": [ + "command" + ], + "properties": { + "annotations": { + "not": {}, + "description": "annotations belong to a run with step freeze; add step or remove annotations." + } + } + } } - }, - "then": { - "required": [ - "environment" - ] - } + ] }, "recipe_reference": { "type": "string", diff --git a/tuldok_project/schemas/step.schema.json b/tuldok_project/schemas/step.schema.json index 2af7157f..b35025ce 100644 --- a/tuldok_project/schemas/step.schema.json +++ b/tuldok_project/schemas/step.schema.json @@ -42,7 +42,13 @@ "$ref": "#/$defs/earlier_work" }, "run": { - "$ref": "#/$defs/run" + "$ref": "#/$defs/run", + "properties": { + "step": { + "not": {}, + "description": "Only a dataset's run may name a step Tuldok provides; give a command." + } + } } }, "if": { @@ -188,13 +194,17 @@ "run": { "type": "object", "additionalProperties": false, - "required": [ - "command" - ], "properties": { "command": { "$ref": "#/$defs/command" }, + "step": { + "enum": [ + "import", + "freeze" + ], + "description": "a step Tuldok provides: import or freeze" + }, "environment": { "type": "string", "pattern": "^environments/[a-z0-9][a-z0-9._-]{0,119}$", @@ -296,6 +306,17 @@ "$ref": "#/$defs/command" } } + }, + "annotations": { + "type": "array", + "minItems": 1, + "maxItems": 32, + "uniqueItems": true, + "items": { + "type": "string", + "pattern": "^annotations/[a-z0-9][a-z0-9._-]{0,119}$", + "description": "a reference to an annotation task, such as annotations/" + } } }, "dependentSchemas": { @@ -308,27 +329,77 @@ } } }, - "if": { - "required": [ - "command" - ], - "properties": { - "command": { - "type": "array", - "minItems": 1, - "prefixItems": [ - { - "const": "python" + "allOf": [ + { + "if": { + "required": [ + "command" + ], + "properties": { + "command": { + "type": "array", + "minItems": 1, + "prefixItems": [ + { + "const": "python" + } + ] } + } + }, + "then": { + "required": [ + "environment" ] } + }, + { + "if": { + "required": [ + "step" + ] + }, + "then": { + "properties": { + "command": { + "not": {}, + "description": "A run with step has no command; remove one of the two." + }, + "environment": { + "not": {}, + "description": "A step Tuldok provides runs with Tuldok's own interpreter; remove environment." + }, + "outputs": { + "not": {}, + "description": "A step's outputs are fixed by the step; remove outputs." + }, + "settings_file": { + "not": {}, + "description": "A step takes its settings inline; use settings, not settings_file." + }, + "env": { + "not": {}, + "description": "A step Tuldok provides takes no environment variables; remove env." + }, + "estimate": { + "not": {}, + "description": "A step Tuldok provides has no estimate command; remove estimate." + } + } + }, + "else": { + "required": [ + "command" + ], + "properties": { + "annotations": { + "not": {}, + "description": "annotations belong to a run with step freeze; add step or remove annotations." + } + } + } } - }, - "then": { - "required": [ - "environment" - ] - } + ] } } } diff --git a/tuldok_project/snapshot.py b/tuldok_project/snapshot.py index 4efc98e7..05a4e24a 100644 --- a/tuldok_project/snapshot.py +++ b/tuldok_project/snapshot.py @@ -329,3 +329,36 @@ def changed_since(code_root, commit): if inside: changed.add(inside) return changed + + +# ------------------------------------------------------------- file_at + +def file_at(directory, commit, path, limit): + """(blob id, bytes) of path, relative to directory, in commit of directory's repository; None when it has no such file. + + The blob id alone is returned with None for the bytes when limit is None + (to compare without reading). Raises SnapshotError: not-in-git, + git-failed, and too-large when the file is over limit bytes. + """ + directory = os.path.abspath(os.fspath(directory)) + if not isinstance(commit, str) or not _COMMIT.match(commit): + raise SnapshotError(f'{commit!r} is not a full commit id.', 'invalid') + _repository(directory) + listed = _git(directory, f'find {path} in commit {commit[:12]}', 'ls-tree', '-z', '-l', commit, '--', path) + for entry in listed.split(b'\0'): + if not entry: + continue + head, _, name = entry.partition(b'\t') + words = head.split() + if name.decode('utf-8', 'surrogateescape') != path: # ls-tree names it relative to directory + continue + if len(words) != 4 or words[1] != b'blob': + return None + blob, size = words[2].decode('ascii'), int(words[3]) + if limit is None: + return blob, None + if size > limit: + raise SnapshotError(f'{path} is {size} bytes in commit {commit[:12]}; at most {limit} are read.', + 'too-large') + return blob, _git(directory, f'read {path} in commit {commit[:12]}', 'cat-file', 'blob', blob) + return None diff --git a/tuldok_project/steps.py b/tuldok_project/steps.py new file mode 100644 index 00000000..b14682ca --- /dev/null +++ b/tuldok_project/steps.py @@ -0,0 +1,608 @@ +"""The steps Tuldok provides: import files into a dataset, and freeze a dataset with splits from its annotations. + +Owns section 6 of docs/plans/definition-first-projects/spec-d4.md. A dataset +whose run names a step (run.step) is built by Tuldok's own interpreter running + + python -m tuldok_project.steps import --code + python -m tuldok_project.steps freeze --records --tasks + +with Tuldok's code first on the module path and the snapshot's code off it +(builds.py sets PYTHONSAFEPATH and PYTHONPATH). A step reads files and writes +its output directory; it opens no database, follows no symbolic link out of +its source, writes nowhere else and deletes nothing. It prints +tuldok_progress_v1 lines and, at its end, what it counted, one plain line +each. The standard library alone is used: the record rules it shares with +inside.py (the kinds by extension, the pattern form, an id's characters) are +repeated here and a test keeps the two equal. + +import_files and freeze_records are the steps as functions on directories; +main() is the command line. +""" +import argparse +import hashlib +import json +import os +import re +import shutil +import stat +import sys +import time + +from . import annotations + +KINDS = ('text', 'image', 'audio', 'pointcloud', 'mesh', 'array', 'file') +EXTENSIONS = { + 'text': ('.txt', '.md', '.json', '.jsonl', '.csv', '.tsv', '.yaml', '.yml', '.log'), + 'image': ('.png', '.jpg', '.jpeg', '.webp', '.gif', '.bmp'), + 'audio': ('.wav', '.flac', '.mp3', '.ogg', '.opus', '.m4a'), + 'pointcloud': ('.xyz',), + 'mesh': ('.obj', '.stl'), + 'array': ('.npy', '.npz', '.safetensors'), +} +STEPS = ('import', 'freeze') +RECORD_LIST = 'records.jsonl' +FILES = 'files' +DEFAULT_PATTERN = '**/*' +DEFAULT_INCLUDE = ('accepted',) +ID_LIMIT = 200 # characters of a record id (spec-d1) +LINE_BYTES = 64 * 1024 # one line of records.jsonl, and one text record (spec-d1) +HASH_LIMIT = 1024 ** 3 # a record over 1 GiB is not hashed (spec-d4 section 3) +PROGRESS_SECONDS = 0.5 +PROGRESS_TOTAL = 1_000_000 # the most a progress line may count (launcher._event) +_ID = re.compile(r'[A-Za-z0-9._-]{1,200}') +_NOT_ID = re.compile(r'[^A-Za-z0-9._-]') +_SHA256 = re.compile(r'[0-9a-f]{64}') +_CHUNK = 1 << 20 + + +class StepError(Exception): + """A step that cannot go on; its message is printed and the step exits with status 1.""" + + +# ------------------------------------------------------------------ shared + +def kind_by_name(name, head=None): + """The kind of a file by its extension; a .ply is a mesh when head() (its first bytes) declares faces.""" + extension = os.path.splitext(name.lower())[1] + if extension == '.ply': + return 'mesh' if head is not None and _ply_has_faces(head()) else 'pointcloud' + return next((kind for kind, endings in EXTENSIONS.items() if extension in endings), 'file') + + +def _ply_has_faces(head): + text = head.split(b'end_header', 1)[0].decode('ascii', 'replace') + for line in text.splitlines(): + words = line.split() + if len(words) == 3 and words[0] == 'element' and words[1] == 'face' and words[2].isdigit(): + return int(words[2]) > 0 + return False + + +def pattern_regex(text): + """spec-d1's pattern form: * and ? within one segment, ** across segments.""" + out, at = [], 0 + while at < len(text): + if text.startswith('**/', at): + out.append('(?:.*/)?') + at += 3 + elif text.startswith('**', at): + out.append('.*') + at += 2 + elif text[at] == '*': + out.append('[^/]*') + at += 1 + elif text[at] == '?': + out.append('[^/]') + at += 1 + else: + out.append(re.escape(text[at])) + at += 1 + return re.compile(''.join(out), re.S) + + +def id_from(text): + """An id made from a path: '/' becomes '__', any other character outside A-Z a-z 0-9 . _ - becomes '_'.""" + made = _NOT_ID.sub('_', text.replace('/', '__')) + return made[:ID_LIMIT] or '_' + + +def unique(name, used, limit=None): + """name, or name with -2, -3, ... before its extension, whichever is not in used; added to used.""" + if name not in used: + used.add(name) + return name + slash = name.rfind('/') + 1 + stem, extension = os.path.splitext(name[slash:]) + stem = name[:slash] + stem + number = 2 + while True: + tail = f'-{number}{extension}' + candidate = (stem[:limit - len(tail)] if limit else stem) + tail + if candidate not in used: + used.add(candidate) + return candidate + number += 1 + + +def sha256_file(path, limit=HASH_LIMIT): + """(SHA-256 of the file, its size); the hash is None when the file is over limit.""" + with open(path, 'rb') as handle: + size = os.fstat(handle.fileno()).st_size + if size > limit: + return None, size + digest = hashlib.sha256() + while True: + chunk = handle.read(_CHUNK) + if not chunk: + return digest.hexdigest(), size + digest.update(chunk) + + +def _sha256_text(text): + return hashlib.sha256(text.encode('utf-8')).hexdigest() + + +def _line(record): + return json.dumps(record, ensure_ascii=False, separators=(',', ':')) + '\n' + + +def _inside(path, root): + return path == root or path.startswith(root + os.sep) + + +def _place(source, target): + """Hard-link source to target, copying it when a link cannot be made (another file system); 'link' or 'copy'.""" + os.makedirs(os.path.dirname(target), exist_ok=True) + try: + os.link(source, target, follow_symlinks=False) + return 'link' + except OSError: + shutil.copyfile(source, target, follow_symlinks=False) + return 'copy' + + +class Progress: + """Prints tuldok_progress_v1 lines: at the start, at most every PROGRESS_SECONDS, and at the end.""" + + def __init__(self, stage, total, out): + self.stage, self.total, self.out = stage, total, out + self.last = 0.0 + + def __call__(self, completed, metrics, *, final=False): + now = time.monotonic() + if not final and completed and now - self.last < PROGRESS_SECONDS: + return + self.last = now + total = max(self.total, completed) + if total > PROGRESS_TOTAL: + completed, total = completed * PROGRESS_TOTAL // total, PROGRESS_TOTAL + self.out(json.dumps({'format': 'tuldok_progress_v1', 'stage': self.stage, 'completed': completed, + 'total': total, 'metrics': metrics}, separators=(',', ':'))) + + +def _say(out, counts, words): + for key, text in words: + if counts.get(key): + out(f'{counts[key]} {text}') + + +# ------------------------------------------------------------------- import + +def _source_root(source, code_root): + if os.path.isabs(source): + root = source + else: + if code_root is None: + raise StepError(f'The source {source!r} is relative to the code root, but no code root was given.') + code_real = os.path.realpath(code_root) + root = os.path.join(code_real, source) + if not _inside(os.path.realpath(root), code_real): + raise StepError(f'The source {source} leads outside the code root through a symbolic link.') + real = os.path.realpath(root) + if not os.path.isdir(real): + raise StepError(f'The source {source} is not a directory here.') + return real + + +def _walk(root, matches, counts): + """[(path under the source, real path)] of the regular files the pattern takes, sorted bytewise in UTF-8.""" + found = [] + for directory, folders, names in os.walk(root): + for name in list(folders): + full = os.path.join(directory, name) + if os.path.islink(full): + folders.remove(name) # never descended into; one inside the source is walked where it leads + if not _inside(os.path.realpath(full), root): + counts['links_out'] += 1 + folders.sort() + for name in names: + full = os.path.join(directory, name) + relative = os.path.relpath(full, root).replace(os.sep, '/') + if not matches(relative): + continue + real = full + if os.path.islink(full): + real = os.path.realpath(full) + if not _inside(real, root): + counts['links_out'] += 1 + continue + try: + mode = os.stat(real).st_mode + except OSError: + counts['unreadable'] += 1 + continue + if not stat.S_ISREG(mode): + counts['not_files'] += 1 + continue + try: + relative.encode('utf-8') + except UnicodeEncodeError: + counts['names_not_utf8'] += 1 + continue + found.append((relative, real)) + found.sort(key=lambda item: item[0].encode('utf-8')) + return found + + +def _addresses(paths): + """{path under the source: its address in the output}: files/, or for a path holding '!' (which an + address reads as an archive) the path with '_' for '!', made unique against every other address.""" + used = {f'{FILES}/{path}' for path in paths if '!' not in path} + found = {path: f'{FILES}/{path}' for path in paths if '!' not in path} + for path in paths: + if '!' in path: + found[path] = unique(f'{FILES}/{path.replace("!", "_")}', used) + return found + + +def _line_texts(path, json_lines, counts): + """(line number, text) of each non-empty line of a text file; a .jsonl line {"text": ...} gives that string.""" + with open(path, 'rb') as handle: + for number, raw in enumerate(handle, 1): + try: + text = raw.decode('utf-8').rstrip('\n').rstrip('\r') + except UnicodeDecodeError: + counts['lines_not_utf8'] += 1 + continue + if not text.strip(): + continue + if json_lines: + try: + value = json.loads(text) + except (ValueError, RecursionError): + value = None + if isinstance(value, dict) and isinstance(value.get('text'), str): + text = value['text'] + if not text.strip(): + continue + yield number, text + + +def import_files(settings, output, *, code_root=None, out=print): + """The import step: settings as section 6 gives them, into the existing directory output. Returns the counts.""" + source = settings['source'] + rights = settings['rights'] + chosen_kind = settings.get('kind') + split_lines = settings.get('lines', False) is True + root = _source_root(source, code_root) + matches = pattern_regex(settings.get('pattern', DEFAULT_PATTERN)).fullmatch + counts = dict.fromkeys(('records', 'files', 'lines', 'bytes', 'links_out', 'not_files', 'unreadable', + 'names_not_utf8', 'lines_not_utf8', 'too_long', 'copied'), 0) + found = _walk(root, matches, counts) + addresses = _addresses([path for path, _ in found]) + progress = Progress('import', len(found), out) + progress(0, {}) + used_ids = set() + with open(os.path.join(output, RECORD_LIST), 'x', encoding='utf-8') as listing: + for done, (path, real) in enumerate(found, 1): + def head(real=real): + with open(real, 'rb') as handle: + return handle.read(64 * 1024) + kind = chosen_kind or kind_by_name(path, head) + if split_lines and kind == 'text': + for number, text in _line_texts(real, path.lower().endswith('.jsonl'), counts): + data = text.encode('utf-8') + record = {'id': None, 'kind': 'text', 'text': text, 'sha256': hashlib.sha256(data).hexdigest(), + 'bytes': len(data), 'rights': rights, 'origin': {'path': path, 'line': number}} + if len(data) > LINE_BYTES or len(_line(record).encode('utf-8')) + ID_LIMIT > LINE_BYTES: + counts['too_long'] += 1 + continue + record['id'] = unique(id_from(f'{path}/{number}'), used_ids, ID_LIMIT) + listing.write(_line(record)) + counts['records'] += 1 + counts['lines'] += 1 + counts['bytes'] += len(data) + else: + address = addresses[path] + if _place(real, os.path.join(output, *address.split('/'))) == 'copy': + counts['copied'] += 1 + digest, size = sha256_file(os.path.join(output, *address.split('/'))) + record = {'id': unique(id_from(path), used_ids, ID_LIMIT), 'kind': kind, 'path': address, + 'sha256': digest, 'bytes': size, 'rights': rights, 'origin': {'path': path}} + listing.write(_line(record)) + counts['records'] += 1 + counts['files'] += 1 + counts['bytes'] += size + progress(done, {'records': counts['records'], 'links_out': counts['links_out']}) + progress(len(found), {'records': counts['records'], 'links_out': counts['links_out']}, final=True) + out(f'{counts["records"]} records imported from {source}: {counts["files"]} files, {counts["lines"]} lines.') + _say(out, counts, (('links_out', 'symbolic links leaving the source were skipped.'), + ('not_files', 'entries that are not regular files were skipped.'), + ('unreadable', 'entries that could not be read were skipped.'), + ('names_not_utf8', 'files whose names are not UTF-8 were skipped.'), + ('lines_not_utf8', 'lines that are not UTF-8 were skipped.'), + ('too_long', f'lines too long for a record ({LINE_BYTES} bytes) were skipped.'), + ('copied', 'files were copied, since they could not be linked.'))) + return counts + + +# ------------------------------------------------------------------- freeze + +def _list_record(value): + """A record from one decoded line of an input's records.jsonl (spec-d1's rules), or None.""" + if not isinstance(value, dict) or not isinstance(value.get('id'), str) or value.get('kind') not in KINDS: + return None + path, text = value.get('path'), value.get('text') + if path is not None and (not isinstance(path, str) or not path): + return None + if path is None and (value['kind'] != 'text' or not isinstance(text, str)): + return None + return value + + +def _input_records(root, view, counts): + """(records in order, {id: record}) of the input product: its records.jsonl, else every regular file.""" + listed = os.path.join(root, RECORD_LIST) + records = [] + if os.path.isfile(listed) and not os.path.islink(listed): + with open(listed, 'rb') as handle: + for raw in handle: + if not raw.strip(): + continue + try: + value = _list_record(json.loads(raw)) + except (ValueError, RecursionError): + value = None + if value is None: + counts['bad_lines'] += 1 + else: + records.append(dict(value)) + elif view is not None: + raise StepError('The input dataset is shown through a view, and freeze reads only a product\'s ' + f'{RECORD_LIST} or its files; give the input a {RECORD_LIST}.') + else: + for directory, folders, names in os.walk(root): + folders.sort() + for name in names: + full = os.path.join(directory, name) + if os.path.islink(full) or not os.path.isfile(full): + continue + address = os.path.relpath(full, root).replace(os.sep, '/') + records.append({'id': address, 'kind': kind_by_name(address), 'path': address}) + records.sort(key=lambda record: record['id'].encode('utf-8', 'surrogateescape')) + by_id = {} + for record in records: + if record['id'] in by_id: + counts['bad_lines'] += 1 + else: + by_id[record['id']] = record + return by_id + + +def _record_hash(root, record): + """The record's SHA-256: as its list gives it, else of its file or text; None over HASH_LIMIT or in an archive.""" + if 'hash' in record: + return record['hash'] + given = record.get('sha256') + if isinstance(given, str) and _SHA256.fullmatch(given): + found = given + elif record.get('path') is None: + found = _sha256_text(record['text']) + elif '!' in record['path']: + found = None + else: + full = _confined(root, record['path']) + found = sha256_file(full)[0] if full is not None else None + record['hash'] = found + return found + + +def _confined(root, address): + """The real path of a regular file at address under root, or None when it is missing or leaves root.""" + full = os.path.realpath(os.path.join(root, *address.split('/'))) + return full if _inside(full, root) and full != root and os.path.isfile(full) else None + + +def _read_task(task): + """(rows by record of the task's sound lines, how many lines were invalid).""" + path, expected = task.get('lines'), task.get('sha256') + if path is None: + return {}, 0 + with open(path, 'rb') as handle: + raw = handle.read(annotations.FILE_LIMIT + 1) + if len(raw) > annotations.FILE_LIMIT: + raise StepError(f'The annotations of {task["reference"]} are over {annotations.FILE_LIMIT} bytes.') + if expected is not None and hashlib.sha256(raw).hexdigest() != expected: + raise StepError(f'The annotations of {task["reference"]} are not the file the build read; build again.') + parsed = annotations.read(raw, task['task'], task.get('vocabulary') or []) + whole = [problem.message for problem in parsed.problems if problem.line is None and problem.severity == 'error'] + if whole: + raise StepError(f'The annotations of {task["reference"]} cannot be read: {whole[0]}') + return {row['record']: row for number, row in parsed.rows if number not in parsed.invalid}, len(parsed.invalid) + + +def _stale(row, record, root): + """True when the annotation does not describe this record's content (or the record is gone).""" + if record is None: + return True + return row['sha256'] is not None and row['sha256'] != _record_hash(root, record) + + +def _cut(count, shares): + """[(split, start, end)] cutting count items by shares, the splits taken in the order of their names. + + By name, not as written: a definition's settings reach the step through + the database, which keeps no order of an object's keys. + """ + total = sum(shares.values()) + found, start, running = [], 0, 0 + for name, weight in sorted(shares.items()): + running += weight + end = count * running // total + found.append((name, start, end)) + start = end + return found + + +def order_key(seed, record_hash, identifier): + """The key freeze orders records by: the SHA-256 of ':' ('id:' when it has none).""" + tied = record_hash if record_hash is not None else f'id:{identifier}' + return hashlib.sha256(f'{seed}:{tied}'.encode('utf-8')).hexdigest() + + +_FROZEN_KEYS = ('id', 'kind', 'path', 'text', 'array', 'sha256', 'bytes', 'rights', 'origin', 'meta') + + +def freeze_records(settings, output, *, records, tasks, view=None, out=print): + """The freeze step: settings as section 6 gives them, from the input product at records, into output. + + tasks is a list of {reference, task, vocabulary, lines (a path or None), + sha256 (of that file, checked, or None)}, the first being the one whose + states include a record. Returns the counts. + """ + seed, shares = settings['seed'], dict(settings['shares']) + include = set(settings.get('include', DEFAULT_INCLUDE)) + if not tasks: + raise StepError('freeze needs at least one task.') + root = os.path.realpath(records) + counts = dict.fromkeys(('records', 'included', 'stale', 'excluded', 'unannotated', 'invalid', 'stale_other', + 'missing_files', 'too_long', 'bad_lines', 'copied'), 0) + by_id = _input_records(root, view, counts) + counts['records'] = len(by_id) + rows = [] + for task in tasks: + found, invalid = _read_task(task) + rows.append(found) + counts['invalid'] += invalid + first, first_name = rows[0], tasks[0]['reference'].split('/', 1)[1] + progress = Progress('freeze', len(first), out) + progress(0, {}) + chosen = [] + for done, (identifier, row) in enumerate(sorted(first.items(), key=lambda item: item[0].encode('utf-8')), 1): + record = by_id.get(identifier) + if _stale(row, record, root): + counts['stale'] += 1 + elif row['state'] not in include: + counts['excluded'] += 1 + else: + chosen.append(record) + progress(done, {'included': len(chosen), 'stale': counts['stale'], 'excluded': counts['excluded']}) + counts['unannotated'] = sum(1 for identifier in by_id if identifier not in first) + chosen.sort(key=lambda record: (order_key(seed, _record_hash(root, record), record['id']), record['id'])) + used_ids, placed = set(), {} + with open(os.path.join(output, RECORD_LIST), 'x', encoding='utf-8') as listing: + for split, start, end in _cut(len(chosen), shares): + for record in chosen[start:end]: + line = _frozen(record, split, tasks, rows, root, output, placed, used_ids, counts) + if line is not None: + listing.write(line) + counts['included'] += 1 + progress(len(first), {'included': counts['included'], 'stale': counts['stale'], + 'excluded': counts['excluded']}, final=True) + out(f'{counts["included"]} of {counts["records"]} records frozen by {first_name}: ' + + ', '.join(f'{split} {end - start}' for split, start, end in _cut(len(chosen), shares)) + '.') + _say(out, counts, (('stale', f'annotations of {first_name} are stale (the record is gone or its content ' + 'differs) and were left out.'), + ('excluded', f'records were left out by their state under {first_name}.'), + ('unannotated', f'records have no annotation under {first_name} and were left out.'), + ('invalid', 'annotations are not valid for their task and were not read.'), + ('stale_other', 'stale annotations of the other tasks were not carried.'), + ('missing_files', 'records whose file is missing from the input were left out.'), + ('too_long', f'records too long for one line ({LINE_BYTES} bytes) were left out.'), + ('bad_lines', f'lines of the input\'s {RECORD_LIST} are not records and were skipped.'), + ('copied', 'files were copied, since they could not be linked.'))) + return counts + + +def _frozen(record, split, tasks, rows, root, output, placed, used_ids, counts): + """The records.jsonl line of one frozen record, its file linked under files/; None when it is left out.""" + line = {key: record[key] for key in _FROZEN_KEYS if record.get(key) is not None} + extra = {key: value for key, value in record.items() if key not in _FROZEN_KEYS + and key not in ('split', 'annotations', 'hash')} + if extra: + line['meta'] = {**extra, **(line.get('meta') or {})} + line['sha256'] = _record_hash(root, record) + if record.get('path') is not None: + outer = record['path'].split('!', 1)[0] + source = _confined(root, outer) + if source is None: + counts['missing_files'] += 1 + return None + target = outer if outer.startswith(f'{FILES}/') else f'{FILES}/{outer}' + if target not in placed: + if _place(source, os.path.join(output, *target.split('/'))) == 'copy': + counts['copied'] += 1 + placed[target] = os.path.getsize(source) + line['path'] = target + record['path'][len(outer):] + if '!' not in record['path'] and not isinstance(line.get('bytes'), int): + line['bytes'] = placed[target] + identifier = record['id'] if _ID.fullmatch(record['id']) else id_from(record['id']) + line['id'] = unique(identifier, used_ids, ID_LIMIT) + line['split'] = split + carried = {} + for task, found in zip(tasks, rows): + row = found.get(record['id']) + if row is None: + continue + if _stale(row, record, root): + counts['stale_other'] += 1 + continue + carried[task['reference'].split('/', 1)[1]] = {'state': row['state'], 'value': row['value']} + line['annotations'] = carried + ordered = {key: line[key] for key in (*_FROZEN_KEYS, 'split', 'annotations') if key in line} + text = _line(ordered) + if len(text.encode('utf-8')) > LINE_BYTES: + counts['too_long'] += 1 + return None + return text + + +# --------------------------------------------------------------- command line + +def _arguments(argv): + parser = argparse.ArgumentParser(prog='python -m tuldok_project.steps', + description='Run a step Tuldok provides (spec-d4.md section 6).') + parser.add_argument('step', choices=STEPS) + parser.add_argument('settings', help='the run\'s settings file') + parser.add_argument('output', help='the run\'s output directory, which exists') + parser.add_argument('--code', help='the code root the run sees (for a relative source)') + parser.add_argument('--records', help='freeze: the input product\'s directory') + parser.add_argument('--tasks', help='freeze: a JSON file of the tasks and their line files') + return parser.parse_args(argv) + + +def main(argv=None): + arguments = _arguments(argv) + out = lambda text: print(text, flush=True) # noqa: E731 + try: + with open(arguments.settings, encoding='utf-8') as handle: + settings = json.load(handle) + if not os.path.isdir(arguments.output): + raise StepError(f'The output directory {arguments.output} does not exist.') + if arguments.step == 'import': + import_files(settings, arguments.output, code_root=arguments.code, out=out) + else: + if arguments.records is None or arguments.tasks is None: + raise StepError('freeze needs --records and --tasks.') + with open(arguments.tasks, encoding='utf-8') as handle: + described = json.load(handle) + freeze_records(settings, arguments.output, records=arguments.records, tasks=described['tasks'], + view=described.get('view'), out=out) + except (StepError, OSError, ValueError, KeyError, TypeError) as exc: + print(f'{arguments.step}: {exc}', file=sys.stderr, flush=True) + return 1 + return 0 + + +if __name__ == '__main__': + sys.exit(main()) From aafa52171c31bc53a695feb52510ec941d942df2 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Fri, 13 Nov 2026 16:52:01 -0700 Subject: [PATCH 069/131] docs(plan): the spec of generation and suggestions through the Pumas endpoint Phase 5 of the data tools plan. The endpoint's address is a setting of the machine. A step generate makes a text or image dataset by asking a model the endpoint serves, as an ordinary build; a person annotating can ask such a model for a suggestion. Tuldok offers only what the endpoint says it serves: Pumas 0.8.0 makes text and images, so audio and 3D datasets come from import or a project's own command. Co-Authored-By: Claude Fable 5.2 --- .../definition-first-projects/spec-d5.md | 97 +++++++++++++++++++ 1 file changed, 97 insertions(+) create mode 100644 docs/plans/definition-first-projects/spec-d5.md diff --git a/docs/plans/definition-first-projects/spec-d5.md b/docs/plans/definition-first-projects/spec-d5.md new file mode 100644 index 00000000..30a44a3c --- /dev/null +++ b/docs/plans/definition-first-projects/spec-d5.md @@ -0,0 +1,97 @@ +# Implementation spec: generating datasets and suggesting annotations through the Pumas endpoint + +This is phase 5 of [the data tools plan](data-tools-plan.md). It builds on [spec-d3.md](spec-d3.md) (the client for the Pumas 0.8.0 endpoint) and [spec-d4.md](spec-d4.md) (annotation, and the steps Tuldok provides). Section 1 of [spec-m1-m2.md](spec-m1-m2.md) applies; the page follows [spec-w4.md](spec-w4.md). + +**Owner, 2026-11-13:** "we will use the pumas endpoint. We wont be embedding pumas." And: "Right now we just need the basic modality support for data generation and annotation. text, image, audio, 3D (point clouds, mesh). ... This is more a setup so other projects can setup what they need to generate." + +**After this phase** a project can make a dataset by asking a model that a Pumas endpoint serves, as an ordinary build, and a person annotating can ask such a model for a suggestion and accept or change it. Tuldok offers what the endpoint says it serves and nothing else. + +## 1. What an endpoint can do, and what Tuldok offers + +Pumas Library 0.8.0 produces **text** (`chat_generation`, `text_generation`) and **PNG images** (`image_generation`); it reads images (`image_to_text`), decides between choices on text, images and audio (`decision`), and transcribes speech (`audio_transcription`). Its contract reserves audio output and has nothing for 3D. + +Tuldok hard-codes none of that. Every offer on the page and every check before a call comes from `GET /v1/served-models` at that moment: a model is offered for a use when one of its capabilities is available and takes the input and makes the output the use needs. So: + +| Wanted | Through the endpoint today | Otherwise | +| --- | --- | --- | +| A text dataset | yes | a project's own command, or `import` | +| An image dataset | yes | the same | +| An audio dataset | no: no served model declares audio output | a project's own generator command, as an ordinary build writing `records.jsonl`; or `import` | +| A point cloud or mesh dataset | no: the contract has no such output | the same | +| A suggestion for a text, an image, a sound | where a served model's capability fits (section 4) | none | +| A suggestion for a point cloud or a mesh | no: no model takes them | none | + +When Pumas gains an output, the generation form and the step need only know how to store it as a record; the offer appears by itself. This phase stores `text` and `png_base64`. + +## 2. The endpoint is a setting of the machine + +- The address is in Tuldok's settings file beside the project directory: `pumas_endpoint`, an `http` or `https` address, or absent. It is never in the Git folder and never in a definition. +- **Operations:** `endpoint` (inspect): the address, whether it answered, and what it serves (each model and profile with its modalities and the capabilities available), or the reason it did not answer. `set_endpoint` (owner, changes): sets or clears the address; it is checked by asking it once. `find_endpoints` (owner): the Pumas endpoints advertising themselves on this machine, found as catalog mode finds them, for the owner to pick from. +- A call to the endpoint is bounded in time and bytes as the client already bounds it, and is made outside the service's lock. +- **One module of `tuldok_project/` imports the client** (`pumas_operations`, `image_generation`, `gateway_discovery`, `ai_http`): a new `tuldok_project/pumas.py`, as `host.py` is the one that imports the app's access layer. Nothing of Pumas is imported, bundled or started. + +## 3. The step `generate` + +A dataset whose `run` has `step: "generate"`, like `import` and `freeze` (spec-d4 section 6), with settings: + +| | | +| --- | --- | +| `make` | `text` or `image` | +| `model`, `profile` | the served model's alias, and its profile when the endpoint requires one | +| `prompt` | the request, with `{n}` (the item's number from 1) and, with an input, `{text}` | +| `count` | how many to make, 1 to 100,000; not with an input | +| `per` | with an input: how many for each of its records, default 1 | +| `seed` | an integer; item `n` is asked with `seed + n - 1` where the capability takes a seed | +| `options` | the capability's own options (`max_tokens`, `temperature`, `top_p`, `width`, `height` and what else it declares), checked against the bounds the endpoint advertises | +| `rights` | required: a sentence on what may be done with the output | + +- **An input.** `inputs: {"prompts": }` makes one request for each text record of that dataset's product (times `per`), in the product's order: a dataset of prompts written by hand, imported, or itself generated can drive a dataset of images. +- **Output:** `records.jsonl` and, for images, the files under `files/`. Each record has its `id` (`g000001` and on), `kind`, `text` or `path`, `sha256`, `bytes`, `rights` and `origin`: `{"generated": {"model", "profile", "capability", "prompt", "seed", "options", "input"}}`, where `seed` is null when the capability took none and `input` is the prompting record's id. +- **Before anything is asked,** the step reads what the endpoint serves and fails, saying why, when the model is not served, the capability is not available, or an option is outside its bounds. +- **A request that fails.** One refused before the provider took it (`not_admitted`) is asked again, twice at most, after a pause. Anything else, or a third refusal, fails the step with the item's number and the endpoint's reason; what was made stays in the failed run's directory and is no product. +- **Where the endpoint comes from.** The build passes the machine's `pumas_endpoint` to the step. With none set, a plan marks the step as not buildable and says so, as it does for an environment that is not ready. The run's record keeps the address and the endpoint's reported version; neither goes to Git. +- **Progress** is the count made; a cancel stops the step between or during a request, as any run. +- **Who may start it** is who may start any build: an agent's request waits for the owner. Generation works the machine that runs Pumas; the approval is the owner's say over that. +- A generated dataset is **rebuilt** only when its definition or its input changes. Building it again may not give the same content (a model need not be deterministic); annotations are tied to content, so those that no longer fit are marked stale (spec-d4 section 3). + +## 4. Suggestions + +`suggest_annotation` (who: edit; it changes nothing): `task`, `record`, `model`, `profile`, and an optional `instruction`. It answers `suggestion`: a `value` in the task's form and `from`: `{"model", "profile", "capability"}`. Nothing is stored. The page puts the value in the form; when the person keeps it, `set_annotation` carries `from`, and the line in Git names the model. + +| Task | Record | Asked as | +| --- | --- | --- | +| `text` (a caption) | image | `image_to_text` | +| `text` (a transcript) | audio | `audio_transcription`, where the released contract gives a request for it; else none | +| `text` (a summary) | text | chat | +| `class`, `tags` | text, image, audio | `decision` over the vocabulary, where a served model offers it for that input; else, for text and images, chat or `image_to_text` asked to answer with terms only, and the answer kept only when it is made of terms | +| `review`, `boxes`, `spans`, `segments` | any | none in this phase | + +`suggestion_models` (inspect): for a task, the served models that can suggest for each kind of record it has, so the page offers only those. A suggestion that is not a valid value of the task is answered as a refusal with the model's words, never as a value. + +## 5. The page + +- **Train tab, beside the environments:** the endpoint. Its address, whether it answers, the models it serves with what each takes and makes. The owner sets, clears or finds it. +- **Data tab, a form "Generate":** name, what to make, the model (those that can make it), the prompt, a count or a dataset of prompts, seed, the options the chosen capability declares with their bounds, rights. It keeps a dataset definition as an unsaved edit; building it is the existing plan and request. With no endpoint, or none that can make anything, the form says so. +- **Annotate tab:** "Suggest" beside the form when a served model fits the task and the record, with the model as a select. While the model answers the button says so and can be cancelled; the suggestion fills the form marked as a suggestion until the person changes or keeps it. "Suggest for this page" asks for the records on screen that have no annotation, one after another, as drafts. + +## 6. Slices + +| | Slice | Mainly | +| --- | --- | --- | +| D5a | The setting, `pumas.py`, the three endpoint operations, the step `generate` | `tuldok_project/local.py`, `pumas.py`, `steps.py`, `builds.py`, `plan.py`, `check.py`, `schemas/`, `operations.py`, `service.py` | +| D5b | `suggest_annotation`, `suggestion_models` | `tuldok_project/pumas.py`, `annotation_records.py`, `operations.py`, `service.py` | +| D5c | The endpoint on the Train tab, the Generate form, Suggest in Annotate | `static/project-workspace/` | + +## 7. Tests + +Everything is checked against a fake endpoint built from the released contract (`tests/fake_pumas_typed.py` and what spec-d3 added). No running Pumas is contacted. + +- **D5a:** the setting set, cleared and refused when it does not answer; `endpoint` with two models and an unavailable capability; a text dataset and an image dataset generated for real through the build machinery against the fake, with their records, hashes and `origin`; from a dataset of prompts, with `per`; seeds passed and recorded, and null where none is taken; an option out of bounds, a model not served and a capability unavailable each fail before any request; a `not_admitted` refusal retried and then failed; another failure failing at once with the item's number; no endpoint set: the plan says so; nothing of the address in the Git folder. +- **D5b:** each row of section 4's table against the fake; an answer that is not made of terms refused; no model fitting: none offered. +- **D5c,** a browser check with the fake: the endpoint set from the page and its models listed; the Generate form writing a definition that checks; a suggestion asked, shown, changed and kept, and the saved line naming the model. + +**A real endpoint** is tried once, on the owner's word: one small text dataset and one small image dataset through the Pumas the owner runs, and one suggestion. It uses that machine's GPU for a moment. + +## 8. Out of scope + +Audio and 3D output (nothing serves them); video; embeddings, rerank and similarity search over a dataset; continuing a generation that failed part way; a queue of suggestions that outlives the page; choosing among several endpoints. From 68aad8fba6fdfbd67107c989da0f3430e543e0a5 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Fri, 13 Nov 2026 16:56:20 -0700 Subject: [PATCH 070/131] feat(project): annotations are edited in the database and written by Save The annotations of a task are rows of the project's working copy, as definitions are. set_annotation keeps up to 200 at a time as unsaved edits, checked against the task, its vocabulary and the record's kind; revert_annotations puts the saved lines back; Save writes each changed task's whole file and status counts what is unsaved without rendering a file. A line file changed on disk is imported on the next operation, and where it changes a record that also has an unsaved edit the project does not open until the conflict is resolved, as for definitions. An annotation is tied to its record's content by a hash, from the record list or computed once per run and record, and is stale when the dataset's product no longer holds that content. annotation_tasks counts each task's records by state; annotated_records pages through them with their annotations; annotation reads one. An agent's lines say agent: and its label, and nothing else of it. Found in review: a line file rewritten to the same size within the same tick of the clock looked unchanged by size and time, so the edit was not imported and Save would have written over it. A file's size and time are trusted only once its time is two seconds old. 100,000 annotations: counted in 0.2 s, saved in 2 s, reopened in 0.02 s. Co-Authored-By: Claude Fable 5.2 --- docs/contracts/project-folder.md | 135 +++- .../definition-first-projects/spec-d4.md | 21 + tests/test_tuldok_project_annotation_rows.py | 587 ++++++++++++++++++ tests/test_tuldok_project_cli.py | 3 +- tests/test_tuldok_project_service.py | 10 +- tests/test_tuldok_project_store.py | 5 +- tuldok_project/__main__.py | 5 + tuldok_project/annotation_records.py | 240 +++++++ tuldok_project/annotation_rows.py | 372 +++++++++++ tuldok_project/inside.py | 13 +- tuldok_project/operations.py | 47 +- tuldok_project/service.py | 269 +++++++- tuldok_project/store.py | 339 +++++++++- 13 files changed, 1999 insertions(+), 47 deletions(-) create mode 100644 tests/test_tuldok_project_annotation_rows.py create mode 100644 tuldok_project/annotation_records.py create mode 100644 tuldok_project/annotation_rows.py diff --git a/docs/contracts/project-folder.md b/docs/contracts/project-folder.md index 34cf9946..5e012467 100644 --- a/docs/contracts/project-folder.md +++ b/docs/contracts/project-folder.md @@ -705,13 +705,13 @@ to the folder. Each project has its own schema, `project_`, named after the | `list [--kind K]` | Prints each definition's reference, state and title, one per line. `--kind` keeps one kind. | | `show REFERENCE` | Prints a definition's reference, title, kind and state, what it uses and what uses it (each with its role), then the definition's text. | | `graph [--order]` | Prints every definition with its kind and state, then every use as `from role to`. `--order` instead prints the build order: each definition after everything it uses, with its state. | -| `status` | Lists definitions edited or removed in the database and not yet saved, and definition files added, changed or missing on disk since the last import. | +| `status` | Lists definitions edited or removed in the database and not yet saved, and definition files added, changed or missing on disk since the last import; and per annotation task, how many records have unsaved annotations, and the annotation files changed on disk. | | `set REFERENCE FILE` | Replaces or adds the definition at `REFERENCE` with the text of `FILE`, in the database only. The text is checked on its own and against the rest of the project; an edit with any error is refused and changes nothing. | | `remove REFERENCE` | Removes the definition in the database only. It is refused while another definition uses it, or while it is the chart `tuldok.json` names in `map.chart`. | | `revert REFERENCE` | Undoes the unsaved edit or the removal of a definition, in the database only: the file in the folder takes its place again. A definition the folder has no file for is dropped instead (refused while another definition uses it). A file that no longer checks is refused, and a definition with neither an unsaved edit nor a removal has nothing to revert (exit status 1). | | `branch RECIPE --title TITLE [--name NAME] [--change KIND] [--description TEXT] [--keep]` | Prints a new recipe branched from `RECIPE` (a bare name or `recipes/`), as the operation `draft_branch` writes it: its reference, its problems in the form `check` prints them, and its text. Nothing is stored, unless `--keep` is given and the text has no error: then it is kept as an unsaved edit, as `set` keeps one. With `--keep` and an error, exit status 1. Here `--keep` keeps the branch; `branch` takes no `--keep` or `--discard` for a conflict. | | `map` | Prints the project's map: per group in order, its title, how many models (recipes) it has and how many of each kind of change, then the models in no group and the totals, then how many lines (`derived_from`, and recipes used as inputs by recipes) and comparisons there are, and the track. Reads the database only, never a results file, values file or note. | -| `save` | Writes every unsaved definition to its file and deletes the files of removed ones. It writes nothing when one of those files changed on disk since it was imported, and names them. | +| `save` | Writes every unsaved definition to its file and deletes the files of removed ones, and writes the annotation file of each task with unsaved annotations. It writes nothing when one of those files changed on disk since it was imported, and names them. | | `forget` | Drops the project's copy from the database, including unsaved edits. The folder is not touched. | `note FOLDER PATH` prints one file under the folder's `notes/` directory, @@ -797,6 +797,68 @@ that subject's rows. Charts and the report read only these rows. A copy of the folder with its `results/` files draws every chart; no run directory or values file is needed. +## Annotations in the database + +Annotations are edited in the database copy and written to the folder by +`save`, as definitions are. The copy holds one row per task and record: the +line's fields as they now are, the line as it is in `annotations/.jsonl` +(or nothing, for an annotation made here and not yet saved), and whether the +row is unsaved. An annotation removed here and not yet saved keeps its row, +with no fields, until `save`. + +**Opening** notices an annotation file that is new, changed or gone. Its size +and time are compared with those recorded at the last import or save, and +only a file whose size or time differs is read and its SHA-256 compared; a +file with the same content and a new time is not imported again. A changed +file is read line by line: each record whose line changed takes the file's +line. Where the record also has an unsaved annotation here, the project does +not open: the refusal is `conflict` and names `annotations/.jsonl`, and +opening again with `--keep` (or `resolve_conflict` `keep`) keeps the +annotations here, the file's lines becoming the saved ones, while `--discard` +takes the file's lines. An annotation file that is gone forgets the saved +lines; an annotation with an unsaved change here stays, unsaved. A task +removed from the folder while it has unsaved annotations here is a +conflict too; it can only be discarded. A line holding the character U+0000 +cannot be kept in the database and refuses the open `invalid`. + +**`save`** writes, whole, the file of each task that has an unsaved row, from +all its annotations in the exact form of [The annotations file](#the-annotations-file) +(by a temporary file and a rename), and deletes it when the task has no +annotation left; it also deletes the file of a removed task. It writes nothing +when such a file changed on disk since it was imported, and names it +(`changed-on-disk`). After a save no annotation is unsaved, and each row's +saved line is the line written. + +**`status`** gains `annotations_unsaved`, a list of `{task, records}` (the +task's reference and how many of its records have an unsaved change), and +`annotations_changed`, the paths of the annotation files added, changed or +removed on disk since the last import or save, by size and time. Neither reads +nor writes an annotation file. + +A task with annotations cannot be removed (`in-use`, saying how many); remove +or revert its annotations first. + +**The hash of a record's content** ties an annotation to what it describes: +SHA-256 of the record's file, of an archive member's bytes once decompressed, +or of the UTF-8 of an inline `text`. A record list may give it as `sha256`. +Otherwise Tuldok computes it when the record is first annotated, or first +looked at for an annotation, and keeps it for that run and record; a run's +product never changes, so it is computed once. A record over 1 GiB is not +hashed: its annotations carry null and are tied by id alone. + +**Stale.** An annotation is stale when its dataset's current product has no +record of its id, or has one whose hash differs from the annotation's (an +annotation or a record without a hash is never stale by content). It is +worked out when asked, never stored, and only the records that have +annotations are hashed to find it. When the dataset has no product, nothing +is stale (`stale` is null). Stale annotations are kept, counted and shown; +Tuldok never drops one. + +**Invalid.** An annotation is invalid when its value is not one the task as it +now is allows (its `task` or `vocabulary` changed since it was made). Each row +remembers the task it was last checked against, so counting reads no value +until the task changes. + ## Values files A benchmark run writes one values file per benchmark and subject: the measured @@ -2013,6 +2075,11 @@ and result keys of each operation are in its contract. | `cancel_build` | cancel | Cancel a build request, stopping its build when it is running. | | `cancel_run` | cancel | Ask a queued or running run to stop. | | `stop_run` | cancel | Kill what a run whose build is gone left running, and mark it unknown. | +| `annotation_tasks` | inspect | List the annotation tasks, each with its dataset, current product and counts of its records by the state of their annotations. | +| `annotated_records` | inspect | Read one page of the records of a task's dataset with their annotations, optionally in one state or of one kind, with the counts. | +| `annotation` | inspect | Read one record's annotation under a task as it now is and as it is in the file, whether it is unsaved or stale, and the hash of the record's content. | +| `set_annotation` | edit | Check annotations of a task's records, or their removal, and keep them as unsaved edits; one item that does not check refuses them all. | +| `revert_annotations` | edit | Put back the saved annotations of a task's named records, or of all its records, in place of their unsaved edits. | `map` answers `groups` (in their order, each with `id`, `title`, `parent`, `description` and `models`, the number of recipes naming it), `models` (one per @@ -2126,6 +2193,7 @@ it: a missing file, and a symbolic link that leaves the product, are refused | `array` | for kind `array` in an `.npz`: the array to show first | | `split`, `rights` | optional strings | | `origin`, `meta` | optional objects, kept and shown as they are | + | `sha256` | optional; the SHA-256 of the record's content, 64 lowercase hexadecimal characters (see [Annotations in the database](#annotations-in-the-database)) | Other keys are kept and shown in `meta` (a key of `meta` itself wins). A line that is not such a record, or is longer than 64 KiB, is skipped and @@ -2166,7 +2234,8 @@ size or time. **`records`** takes `offset`, `limit` (at most 200, 50 by default), `kind` and `split`, and answers `records` (each `id`, `kind`, `path`, `bytes`, `split`, -`rights`, `origin`, `meta`, `array` when the list gives one, and for a text +`rights`, `origin`, `meta`, `sha256` (null unless the list gives it), `array` +when the list gives one, and for a text record its first 400 characters as `preview`), `total` (after the filters), `source` (`records.jsonl`, `view` or `files`), `kinds` and `splits` (counts over all the records; records without a split are not counted in `splits`) @@ -2341,6 +2410,66 @@ element by element in C order, whichever order each is stored in. At most tensors per file; beyond either the call is refused `too-large`, saying how many there are. +### Annotating + +The five operations on annotations (see [Annotations in the database](#annotations-in-the-database)) +name a task by `task`, its name or its reference `annotations/`, and +answer it as the reference. A task that the project does not have (or has +removed) is refused `not-found`. The records are those of the current product +of the task's dataset, read as `records` reads them; the reads find the product +with the project open for a moment and read it after, as the reads above do. + +**`annotation_tasks`** takes nothing and answers `tasks`, by name, each with +`task`, `title`, `dataset`, `type` (the task's `task`), `vocabulary` (empty for +`review` and `text`), `run` (the dataset's current product, or null), +`records` (how many records it has, or null), `counts` and `unsaved` (how many +records have an unsaved change). `counts` has `unannotated` (records of the +product without an annotation), `draft`, `accepted`, `needs-work`, `rejected` +(annotations by state, stale ones included), `stale` and `invalid`. + +**`annotated_records`** takes `task`, `state` (one of the names of `counts`; +absent for all), `kind`, `offset` and `limit` (at most 200, 50 by default), +and answers `task`, `run`, `records` (the page), `total` (after the filters) +and `counts`. The records are those of the product in its order, each as +`records` gives it with `in_product` true, followed (unless `kind` is given) +by the annotated records the product does not have, by id, with `in_product` +false and null `kind`, `path`, `bytes`, `split`, `rights`, `origin`, `meta` +and `sha256`. Each has `annotation`: null, or `state`, `value`, `note` (null +when there is none), `by`, `at`, `stale` and `unsaved`. + +**`annotation`** takes `task` and `record` and answers `task`, `record`, +`annotation` (the line as it now is, as an object with the keys of the +annotations file, or null), `saved` (the line in the file, likewise, or +null), `unsaved`, `stale` (null when there is no annotation or no product) +and `sha256` (the hash of the record's content now, or null). + +**`set_annotation`** takes `task`, `items` (1 to 200, each +`{record, state, value?, note?}` or `{record, remove: true}`) and `from` +(optional, an object written as every item's `from`), and answers `task`, +`set`, `removed` (how many annotations went) and `unsaved` (how many of the +task's records now have an unsaved change). Every item is checked before +anything changes: the record must be in the product (refused `not-found` +when the dataset has none), named once, and its line must be one the +annotations file allows, its value checked against the task, the vocabulary +and the record's kind, and, where the product makes it cheap to know, an +image's size, a text's length (a file of at most 16 MiB) and a WAVE sound's +length. One item that does not check refuses the call `invalid`, with one +problem per such item whose pointer is `/items/`. The line takes `sha256` +from the record now, `by` from the caller (`owner`, or `agent:` and the +credential's name cut to 80 characters; never its id, token or scopes) and +`at` from the clock. Setting an annotation again takes the record's hash +again, which is how a stale annotation that is still right is put right. +Removing a record that has no annotation does nothing. + +**`revert_annotations`** takes `task` and `records` (optional, at most 10,000) +and answers `task` and `reverted`: how many of those records (all the task's, +without `records`) had an unsaved change and now have their saved line +again, or no annotation when the file has none. + +Each call of `set_annotation` and `revert_annotations` writes one activity +row whose target is the task's reference and whose detail says how many +records it set, removed or reverted. + ## The project directory on this machine Everything a project keeps on one machine alone (installed environments, code diff --git a/docs/plans/definition-first-projects/spec-d4.md b/docs/plans/definition-first-projects/spec-d4.md index 94264dba..c4c884b2 100644 --- a/docs/plans/definition-first-projects/spec-d4.md +++ b/docs/plans/definition-first-projects/spec-d4.md @@ -196,3 +196,24 @@ What differs from the text above, and what was chosen where it was silent. - **Checked in review** with annotations generated at random: 400 of each task, with ids holding `/`, `!`, non-Latin letters and upper case, values holding quotes, backslashes, line separators and emoji, written and read back equal, byte for byte and in order; 3,000 corrupted files read without an error escaping; 100,000 lines written in 0.2 s and read and checked in 1.4 s (16 MiB). - **Tests:** `tests/test_tuldok_project_annotations.py`, 22; project suite 632; agent interface 43 (4 skipped). The catalog profile's digest is unchanged. - **Not verified:** the editor's list of kinds in a browser. + +### D4b, the working copy and the operations + +What differs from sections 3 to 5, and what was chosen where they were silent. + +- **A file's size and time are trusted only once its time is old** (found in review). A line file written a moment ago can be written again within the same tick of the clock, to the same size, and by size and time it would look untouched: the edit would not be imported, and the next Save would write over it. A file whose time is less than two seconds old when it is recorded is recorded as unsettled, and is read and compared by content on every operation until it is seen settled, as Git does for the same case. A test writes such an edit and fails without the rule. +- **A removed annotation** is a row with no state until Save, which keeps its saved line so that the file can be rewritten or deleted. +- **`from` is kept as text** (`json`, not `jsonb`), since the database's own form reorders keys and `from` is kept as it is. `value` is `jsonb`: a number of 1e16 or more written as a float in a file becomes a whole number the next time that task is saved. +- **Invalid is kept, not computed on every count.** Each row holds a digest of the task's type and vocabulary it was last judged against, and the verdict; a count judges again only the rows of a task that changed. Invalid judges the value alone, not the record's kind. +- **A task whose dataset has no product:** `stale` and `unannotated` are 0, a record's `stale` is null, setting an annotation is refused `not-found`, and removing one still works. +- **A task deleted on disk while it has unsaved annotations** is a `conflict` that only `discard` resolves. A line file that is gone never conflicts: unsaved rows stay, with no saved line. +- **U+0000** in a line or an item is refused `invalid`: PostgreSQL cannot store it. +- **Removing a task** that has annotations is refused `in-use` with their number. With none left, Save deletes the task and its line file together. +- **`set_annotation` works in two stages:** it finds and hashes the records outside the service's lock, then checks and stores under it; when the task or the product's run changed in between, it is refused `busy`. +- **Activity rows** carry "N set, M removed" or "N reverted". +- **A record's hash** is also computed, and kept, when `annotation` reads a record that has no annotation. +- **An agent with an empty label** is written `agent:agent`. +- **Names.** Every operation answers the task as `annotations/` and takes a bare name or that reference; `status` and `save` name files as `annotations/.jsonl`. `annotated_records` also answers `task`, `run` and, for each record, `sha256` and `in_product`; annotations whose record is not in the product come last, with `in_product` false and no kind. "Still right" on a stale annotation is setting it again. +- **Measured with 100,000 annotations** (the test's bound in brackets): setting them in 500 calls of 200, 28 to 36 s, about 66 ms a call (120); counting them, 0.2 s (2); `status`, 0.03 s; Save, 2 s (10); opening again, 0.02 s (2); importing the file into an empty database, 5 s (30). +- **Tests:** `tests/test_tuldok_project_annotation_rows.py`, 22; the project suite and the agent interface are in the ledger. The catalog profile's digest is unchanged. +- **Not verified:** hashes kept for runs that are later forgotten are never pruned; a sound's length is read from WAV files only, so a segment in another format is not checked against the sound's end; the command line has no annotation commands. diff --git a/tests/test_tuldok_project_annotation_rows.py b/tests/test_tuldok_project_annotation_rows.py new file mode 100644 index 00000000..b896acbc --- /dev/null +++ b/tests/test_tuldok_project_annotation_rows.py @@ -0,0 +1,587 @@ +"""The working copy of annotations and the five operations: sections 3 to 5 of spec-d4.md (slice D4b). + +Each test starts from test_tuldok_project_inside.ProductCase (a Git-committed +copy of the buildable fixture with an adopted product for datasets/numbers), +writes a record list and its files into that product, adds four tasks on +datasets/numbers (a class, a boxes, a spans and a segments task) and serves +the folder with a Service. Annotations are set, counted, saved, reverted, +changed on disk and found stale through the service's operations, as the page +and an agent would. Run only when TULDOK_DATABASE_URL names a disposable +cluster. No GPU is used. +""" +import hashlib +import json +import os +from pathlib import Path +import sys +import time +import unittest +from unittest import mock + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) +sys.path.insert(0, str(Path(__file__).resolve().parent)) + +from tuldok_project import adoption, annotation_records, annotations, inside, service, store # noqa: E402 +from tuldok_project.service import Service # noqa: E402 +import test_tuldok_project_builds as builds_base # noqa: E402 +import test_tuldok_project_inside as inside_base # noqa: E402 + +OWNER = inside_base.OWNER +AT = '2026-11-13T10:02:11Z' +TASK = 'annotations/scenes' +LINES = 'annotations/scenes.jsonl' +# The time bounds of the test with 100,000 annotations, in seconds. Measured when it was written: set (500 calls of +# 200) 33 s, count 0.24 s, save 2.2 s, open again 0.02 s, a fresh import of the saved file 4.7 s; each bound is +# several times that, so that a slower machine passes and a change of order (a file rendered on every call, a +# query per row) does not. +BOUNDS = {'set': 120.0, 'count': 2.0, 'save': 10.0, 'reopen': 2.0, 'import': 30.0} + + +def sha(data): + return hashlib.sha256(data if isinstance(data, bytes) else data.encode('utf-8')).hexdigest() + + +def agent(*scopes, label='Helper'): + return {'actor_id': 'agent-7f3c', 'kind': 'agent', 'label': label, 'scopes': list(scopes)} + + +@unittest.skipUnless(builds_base.DATABASE, 'TULDOK_DATABASE_URL is not set; database tests need a disposable cluster.') +class AnnotationCase(inside_base.ProductCase): + """ProductCase with records of several kinds, four tasks on datasets/numbers and a Service.""" + + RECORDS = None + + def setUp(self): + super().setUp() + self.write('img.png', inside_base.png(20, 10)) + self.write('snd.wav', inside_base.wav16([0] * 8000, rate=8000)) # one second + self.write('f1.txt', 'abcdef') + self.records = self.RECORDS or [ + {'id': 't1', 'kind': 'text', 'text': 'hello world', 'sha256': sha('hello world')}, + {'id': 't2', 'kind': 'text', 'text': 'second'}, + {'id': 'f1', 'kind': 'text', 'path': 'f1.txt'}, + {'id': 'img', 'kind': 'image', 'path': 'img.png'}, + {'id': 'snd', 'kind': 'audio', 'path': 'snd.wav'}, + ] + self.write_list(self.records) + self.task('scenes', 'class', ['cat', 'dog']) + self.task('shapes', 'boxes', ['cat']) + self.task('mentions', 'spans', ['PER']) + self.task('speech', 'segments', ['speech']) + patcher = mock.patch.object(service, '_now', return_value=AT) + patcher.start() + self.addCleanup(patcher.stop) + self.service = Service(self.folder) + self.addCleanup(self.service.close) + + def write_list(self, records): + self.write('records.jsonl', ''.join(json.dumps(record) + '\n' for record in records)) + + def task(self, name, kind, vocabulary=None): + document = {'format': 'tuldok_definition_v1', 'kind': 'annotation', 'title': name.title(), + 'dataset': 'datasets/numbers', 'task': kind} + if vocabulary: + document['vocabulary'] = vocabulary + (self.folder / 'annotations').mkdir(exist_ok=True) + (self.folder / f'annotations/{name}.json').write_text(json.dumps(document, indent=2) + '\n', encoding='utf-8') + + def call(self, name, actor=OWNER, **arguments): + result = self.service.call(name, arguments, actor) + json.dumps(result, allow_nan=False) + return result + + def refused(self, name, actor=OWNER, **arguments): + with self.assertRaises(store.ProjectError) as caught: + self.service.call(name, arguments, actor) + return caught.exception + + def set(self, *items, task='scenes', actor=OWNER, **extra): + return self.call('set_annotation', actor=actor, task=task, items=list(items), **extra) + + def lines_file(self, name='scenes'): + return self.folder / f'annotations/{name}.jsonl' + + def disk_lines(self, name='scenes'): + return [json.loads(line) for line in self.lines_file(name).read_text(encoding='utf-8').splitlines()] + + def counts(self, task=TASK): + return next(item for item in self.call('annotation_tasks')['tasks'] if item['task'] == task) + + def rewrite(self, rows, name='scenes'): + """Write the line file by hand (as a pull would), with a time other than the one recorded.""" + path = self.lines_file(name) + before = path.stat().st_mtime_ns if path.exists() else 0 + path.write_bytes(annotations.write(rows)) + os.utime(path, ns=(before + 10_000_000_000, before + 10_000_000_000)) + + +class WorkingCopy(AnnotationCase): + + def test_set_count_save_and_open_again(self): + done = self.set({'record': 't1', 'state': 'accepted', 'value': 'cat'}, + {'record': 't2', 'state': 'draft', 'value': None, 'note': 'not sure'}) + self.assertEqual(done, {'task': TASK, 'set': 2, 'removed': 0, 'unsaved': 2}) + status = self.call('status') + self.assertEqual((status['annotations_unsaved'], status['annotations_changed']), + ([{'task': TASK, 'records': 2}], [])) + listed = self.counts() + self.assertEqual((listed['records'], listed['unsaved'], listed['type'], listed['dataset'], listed['run']), + (5, 2, 'class', 'datasets/numbers', self.run_id)) + self.assertEqual(listed['counts'], {'unannotated': 3, 'draft': 1, 'accepted': 1, 'needs-work': 0, + 'rejected': 0, 'stale': 0, 'invalid': 0}) + self.assertFalse(self.lines_file().exists()) + + saved = self.call('save') + self.assertEqual((saved['annotations_written'], saved['annotations_deleted']), ([LINES], [])) + self.assertEqual(self.lines_file().read_bytes(), ( + '{"record":"t1","sha256":"%s","state":"accepted","value":"cat","by":"owner","at":"%s"}\n' + '{"record":"t2","sha256":"%s","state":"draft","value":null,"note":"not sure","by":"owner","at":"%s"}\n' + % (sha('hello world'), AT, sha('second'), AT)).encode()) + self.assertEqual(self.call('status')['annotations_unsaved'], []) + self.assertEqual(self.counts()['unsaved'], 0) + self.assertEqual(self.call('save')['annotations_written'], []) # nothing left to write + + one = self.call('annotation', task='scenes', record='t2') + self.assertEqual((one['unsaved'], one['stale'], one['sha256']), (False, False, sha('second'))) + self.assertEqual(one['annotation'], one['saved']) + # A second open, and a fresh import of the folder into an empty database, read the same. + again = Service(self.folder) + self.addCleanup(again.close) + self.assertEqual(again.call('annotation', {'task': TASK, 'record': 't2'}, OWNER), one) + self.service.close() + again.close() + store.drop_project(self.project_id) + fresh = Service(self.folder) + self.addCleanup(fresh.close) + self.assertEqual(fresh.call('annotation', {'task': TASK, 'record': 't2'}, OWNER)['annotation'], + one['annotation']) + self.assertEqual(fresh.call('status', {}, OWNER)['annotations_unsaved'], []) + + def test_remove_and_delete_the_file(self): + self.set({'record': 't1', 'state': 'rejected'}) + self.call('save') + done = self.set({'record': 't1', 'remove': True}, {'record': 't2', 'remove': True}) + self.assertEqual((done['set'], done['removed'], done['unsaved']), (0, 1, 1)) + self.assertIsNone(self.call('annotation', task='scenes', record='t1')['annotation']) + self.assertEqual(self.call('save')['annotations_deleted'], [LINES]) + self.assertFalse(self.lines_file().exists()) + self.assertEqual(self.call('status')['annotations_unsaved'], []) + + def test_revert(self): + self.set({'record': 't1', 'state': 'accepted', 'value': 'cat'}) + self.call('save') + self.set({'record': 't1', 'state': 'accepted', 'value': 'dog'}, {'record': 't2', 'state': 'draft'}, + {'record': 'f1', 'state': 'draft'}) + self.assertEqual(self.call('revert_annotations', task=TASK, records=['t1']), {'task': TASK, 'reverted': 1}) + back = self.call('annotation', task='scenes', record='t1') + self.assertEqual((back['annotation']['value'], back['unsaved']), ('cat', False)) + self.assertEqual(self.call('revert_annotations', task='scenes'), {'task': TASK, 'reverted': 2}) + self.assertIsNone(self.call('annotation', task='scenes', record='t2')['annotation']) + self.assertEqual(self.call('status')['annotations_unsaved'], []) + self.assertEqual(self.call('revert_annotations', task='scenes')['reverted'], 0) + # A removal is reverted too. + self.set({'record': 't1', 'remove': True}) + self.call('revert_annotations', task='scenes') + self.assertEqual(self.call('annotation', task='scenes', record='t1')['annotation']['value'], 'cat') + + def test_a_file_changed_on_disk_is_imported(self): + self.set({'record': 't1', 'state': 'accepted', 'value': 'cat'}, {'record': 't2', 'state': 'draft'}) + self.call('save') + rows = self.disk_lines() + rows[1]['state'] = 'needs-work' + rows.append({'record': 'zz', 'sha256': None, 'state': 'rejected', 'value': None, 'by': 'owner', 'at': AT}) + self.rewrite(rows) + self.assertEqual(self.call('annotation', task='scenes', record='t2')['annotation']['state'], 'needs-work') + counts = self.counts()['counts'] + self.assertEqual((counts['needs-work'], counts['rejected'], counts['stale']), (1, 1, 1)) # zz is not a record + status = self.call('status') + self.assertEqual((status['annotations_unsaved'], status['annotations_changed']), ([], [])) + # The same bytes with a new time are not imported again: only the time recorded changes. + os.utime(self.lines_file(), ns=(1, 1)) + self.assertEqual(self.call('annotation', task='scenes', record='zz')['annotation']['state'], 'rejected') + # A line file that is gone forgets the saved lines; an unsaved edit stays, as unsaved. + self.set({'record': 't1', 'state': 'accepted', 'value': 'dog'}) + self.lines_file().unlink() + status = self.call('status') + self.assertEqual(status['annotations_unsaved'], [{'task': TASK, 'records': 1}]) + one = self.call('annotation', task='scenes', record='t1') + self.assertEqual((one['annotation']['value'], one['saved'], one['unsaved']), ('dog', None, True)) + self.assertIsNone(self.call('annotation', task='scenes', record='t2')['annotation']) + self.assertEqual(self.call('save')['annotations_written'], [LINES]) + self.assertEqual([row['record'] for row in self.disk_lines()], ['t1']) + + def test_an_edit_of_the_same_size_at_the_same_time_is_still_noticed(self): + # Written twice within one tick of the clock, to the same size: size and time say nothing changed. + self.set({'record': 't1', 'state': 'accepted', 'value': 'cat'}) + self.call('save') + path = self.lines_file() + before = os.stat(path) + edited = path.read_bytes().replace(b'"value":"cat"', b'"value":"dog"') + self.assertEqual(len(edited), before.st_size) + path.write_bytes(edited) + os.utime(path, ns=(before.st_atime_ns, before.st_mtime_ns)) + self.assertEqual(os.stat(path).st_mtime_ns, before.st_mtime_ns) + self.assertEqual(self.call('annotation', task='scenes', record='t1')['annotation']['value'], 'dog') + # And save does not write over such an edit: with an unsaved change of that record it is a conflict. + self.set({'record': 't1', 'state': 'accepted', 'value': 'cat'}) + again = path.read_bytes().replace(b'"value":"dog"', b'"value":"cat"').replace(b'"state":"accepted"', + b'"state":"rejected"') + now = os.stat(path) + path.write_bytes(again) + os.utime(path, ns=(now.st_atime_ns, now.st_mtime_ns)) + self.assertEqual(self.refused('save').code, 'conflict') + self.assertEqual(path.read_bytes(), again) # nothing was written over the edit + + def test_a_change_on_disk_to_an_edited_record_is_a_conflict(self): + for choice, value in (('keep', 'dog'), ('discard', 'cat')): + with self.subTest(choice): + self.set({'record': 't1', 'state': 'accepted', 'value': 'cat'}, + {'record': 't2', 'state': 'draft'}) + self.call('save') + self.set({'record': 't1', 'state': 'accepted', 'value': 'dog'}) + rows = self.disk_lines() + rows[1]['note'] = 'changed on disk, t1 is not' + self.rewrite(rows) + # A change to another record than the one edited here is no conflict: it is imported. + self.assertEqual(self.call('annotation', task='scenes', record='t2')['annotation']['note'], + 'changed on disk, t1 is not') + rows = self.disk_lines() + rows[0]['note'] = 'changed on disk' + self.rewrite(rows) + refused = self.refused('summary') + self.assertEqual((refused.code, refused.references), ('conflict', [LINES])) + self.assertIn(LINES, str(refused)) + self.assertEqual(self.refused('save').code, 'conflict') + self.call('resolve_conflict', choice=choice) + one = self.call('annotation', task='scenes', record='t1') + self.assertEqual(one['annotation']['value'], value) + self.assertEqual(one['saved']['note'], 'changed on disk') + self.assertEqual(one['unsaved'], choice == 'keep') + self.call('save') + self.assertEqual(self.disk_lines()[0]['value'], value) + self.assertEqual(self.call('status')['annotations_unsaved'], []) + self.call('set_annotation', task='scenes', items=[{'record': 't1', 'remove': True}, + {'record': 't2', 'remove': True}]) + self.call('save') + + def test_save_refuses_a_file_changed_since_it_was_imported(self): + self.set({'record': 't1', 'state': 'draft'}) + self.call('save') + self.set({'record': 't2', 'state': 'draft'}) + with store.open_project(self.folder) as project: + rows = self.disk_lines() + rows[0]['note'] = 'between the open and the save' + self.rewrite(rows) + with self.assertRaises(store.ProjectError) as caught: + project.save() + self.assertEqual((caught.exception.code, caught.exception.references), ('changed-on-disk', [LINES])) + + def test_activity_names_the_task_and_how_many(self): + self.set({'record': 't1', 'state': 'draft'}, {'record': 't2', 'state': 'draft'}) + self.call('revert_annotations', task='annotations/scenes') + rows = self.call('activity')['items'] + self.assertEqual([(row['operation'], row['target'], row['outcome'], row['detail']) for row in rows], + [('revert_annotations', TASK, 'done', '2 reverted'), + ('set_annotation', TASK, 'done', '2 set, 0 removed')]) + + def test_an_agents_line_says_agent_and_its_label_and_nothing_else_of_it(self): + label = 'Night shift helper ' + 'x' * 100 + self.set({'record': 't1', 'state': 'draft', 'value': 'cat'}, actor=agent('inspect', 'edit', label=label)) + self.assertEqual(self.refused('set_annotation', actor=agent('inspect'), task='scenes', + items=[{'record': 't1', 'state': 'draft'}]).code, 'forbidden') + self.call('save') + text = self.lines_file().read_text(encoding='utf-8') + [row] = self.disk_lines() + self.assertEqual(row['by'], 'agent:' + label[:80]) + self.assertEqual(len(row['by']), len('agent:') + 80) + for secret in ('agent-7f3c', 'inspect', 'edit', 'scopes', 'actor'): + self.assertNotIn(secret, text) + + def test_removing_a_task_with_annotations_is_refused(self): + self.set({'record': 't1', 'state': 'draft'}, {'record': 't2', 'state': 'draft'}, {'record': 'f1', 'state': 'draft'}) + refused = self.refused('remove_definition', reference=TASK) + self.assertEqual(refused.code, 'in-use') + self.assertIn('3 annotations', str(refused)) + self.call('revert_annotations', task='scenes') + self.call('remove_definition', reference=TASK) # none left: it may go + self.assertEqual(self.call('save')['deleted'], [TASK]) + + def test_a_removed_task_takes_its_file_with_it(self): + self.set({'record': 't1', 'state': 'draft'}) + self.call('save') + self.set({'record': 't1', 'remove': True}) + self.call('remove_definition', reference=TASK) + saved = self.call('save') + self.assertEqual((saved['deleted'], saved['annotations_deleted']), ([TASK], [LINES])) + self.assertFalse(self.lines_file().exists()) + self.assertTrue(self.call('check')['ok']) + + +class Refusals(AnnotationCase): + """Every refusal of set_annotation; each changes nothing and is recorded.""" + + def assertRefused(self, code, task='scenes', items=(), **extra): + before = self.call('status')['annotations_unsaved'] + refused = self.refused('set_annotation', task=task, items=list(items), **extra) + self.assertEqual(refused.code, code, str(refused)) + self.assertEqual(self.call('status')['annotations_unsaved'], before) + self.assertNotIn('label', str(refused).lower()) + return refused + + def test_every_refusal(self): + self.set({'record': 't1', 'state': 'draft'}) + good = {'record': 't2', 'state': 'accepted', 'value': 'cat'} + cases = [ + ('not-found', 'nothing', [good], {}), # no such task + ('invalid', 'scenes', [], {}), # no item + ('invalid', 'scenes', [good] * 201, {}), # over 200 items + ('invalid', 'scenes', [{**good, 'state': 'done'}], {}), # not a state + ('invalid', 'scenes', [{**good, 'colour': 'red'}], {}), # an unknown key + ('invalid', 'scenes', [{**good, 'note': 'n' * 4001}], {}), # a note too long + ('invalid', 'scenes', [{'record': 't2', 'remove': False}], {}), # remove must be true + ('invalid', 'scenes', [{**good, 'record': 'r' * 601}], {}), # a record id too long + ('invalid', 'scenes', [good, {'record': 'missing', 'state': 'draft'}], {}), # not in the product + ('invalid', 'scenes', [good, {**good, 'value': 'dog'}], {}), # a record twice + ('invalid', 'scenes', [{**good, 'value': 'cow'}], {}), # a term not in the vocabulary + ('invalid', 'scenes', [{**good, 'value': None}], {}), # accepted without a value + ('invalid', 'scenes', [{**good, 'value': ['cat']}], {}), # not one term + ('invalid', 'scenes', [{**good, 'note': 'a\x00b'}], {}), # U+0000 + ('invalid', 'scenes', [good], {'from': {'model': 'x' * 3000}}), # from over 2 KiB + ('invalid', 'shapes', [{'record': 't2', 'state': 'accepted', # boxes on a text + 'value': [{'term': 'cat', 'x': 0, 'y': 0, 'w': 1, 'h': 1}]}], {}), + ('invalid', 'shapes', [{'record': 'img', 'state': 'accepted', # outside the image + 'value': [{'term': 'cat', 'x': 15, 'y': 0, 'w': 10, 'h': 5}]}], {}), + ('invalid', 'mentions', [{'record': 't1', 'state': 'accepted', # past the text + 'value': [{'term': 'PER', 'start': 6, 'end': 12}]}], {}), + ('invalid', 'mentions', [{'record': 'f1', 'state': 'accepted', # past a file's text + 'value': [{'term': 'PER', 'start': 0, 'end': 7}]}], {}), + ('invalid', 'speech', [{'record': 'snd', 'state': 'accepted', # past the sound + 'value': [{'term': 'speech', 'start': 0.5, 'end': 1.5}]}], {}), + ('invalid', 'speech', [{'record': 'img', 'state': 'draft', 'value': None}], {}), # not a sound + ] + for code, task, items, extra in cases: + with self.subTest(task=task, items=str(items)[:120]): + refused = self.assertRefused(code, task, items, **extra) + if code == 'invalid' and items and len(items) <= 2 and 'remove' not in items[-1] \ + and len(items[-1]['record']) <= 600 and items[-1].get('state') in annotations.STATES \ + and set(items[-1]) <= {'record', 'state', 'value', 'note'} \ + and len(items[-1].get('note') or '') <= 4000: + self.assertEqual([problem.pointer for problem in refused.problems], [f'/items/{len(items) - 1}']) + # The same items, right, are kept; the bounds were the record's. + self.set({'record': 'img', 'state': 'accepted', 'value': [{'term': 'cat', 'x': 10, 'y': 0, 'w': 10, 'h': 10}]}, + task='shapes') + self.set({'record': 't1', 'state': 'accepted', 'value': [{'term': 'PER', 'start': 6, 'end': 11}]}, + task='mentions') + self.set({'record': 'f1', 'state': 'accepted', 'value': [{'term': 'PER', 'start': 0, 'end': 6}]}, + task='mentions') + self.set({'record': 'snd', 'state': 'accepted', 'value': [{'term': 'speech', 'start': 0.5, 'end': 1.0, + 'text': 'hi'}]}, task='speech') + # Without a product, there is nothing to annotate; a removal is still allowed. + with store.open_project(self.folder) as project: + project._execute('UPDATE {schema}.products SET current = false') + self.assertRefused('not-found', 'scenes', [good]) + self.assertEqual(self.set({'record': 't1', 'remove': True})['removed'], 1) + refusals = [row for row in self.call('activity', limit=500)['items'] if row['outcome'] != 'done'] + self.assertEqual(len(refusals), len(cases) + 1) + self.assertTrue(all(row['target'] in (TASK, 'annotations/nothing', 'annotations/shapes', + 'annotations/mentions', 'annotations/speech') for row in refusals)) + + def test_a_value_the_task_no_longer_allows_is_counted_invalid(self): + self.set({'record': 't1', 'state': 'accepted', 'value': 'cat'}, {'record': 't2', 'state': 'accepted', + 'value': 'dog'}) + self.assertEqual(self.counts()['counts']['invalid'], 0) + text = (self.folder / 'annotations/scenes.json').read_text(encoding='utf-8').replace('"dog"', '"bird"') + self.call('set_definition', reference=TASK, text=text) + self.assertEqual(self.counts()['counts']['invalid'], 1) + self.assertEqual([record['id'] for record in self.call('annotated_records', task='scenes', + state='invalid')['records']], ['t2']) + + +class Stale(AnnotationCase): + + def test_stale_by_a_missing_record_and_by_different_content(self): + self.set({'record': 't1', 'state': 'accepted', 'value': 'cat'}, {'record': 't2', 'state': 'draft'}, + {'record': 'f1', 'state': 'draft'}) + self.assertEqual(self.counts()['counts']['stale'], 0) + # The record list now gives another hash for t1, and has no t2. + records = [dict(record) for record in self.records if record['id'] != 't2'] + records[0]['sha256'] = sha('hello there') + self.write_list(records) + listed = self.counts() + self.assertEqual((listed['counts']['stale'], listed['records'], listed['counts']['unannotated']), (2, 4, 2)) + page = self.call('annotated_records', task='scenes', state='stale') + self.assertEqual([(record['id'], record['in_product'], record['annotation']['stale']) + for record in page['records']], [('t1', True, True), ('t2', False, True)]) + self.assertEqual(self.call('annotation', task='scenes', record='t1')['stale'], True) + # "Still right": setting it again takes the record's hash. + self.set({'record': 't1', 'state': 'accepted', 'value': 'cat'}) + self.assertEqual(self.call('annotation', task='scenes', record='t1')['annotation']['sha256'], + sha('hello there')) + self.assertEqual(self.counts()['counts']['stale'], 1) + + def test_stale_when_a_new_product_holds_other_content(self): + self.set({'record': 'f1', 'state': 'draft'}) + source = self.temporary / 'again.json' + source.write_text('{}', encoding='utf-8') + manifest = {'format': 'tuldok_adoption_v1', + 'products': [{'reference': 'datasets/numbers', 'files': {'numbers.json': str(source)}}]} + with self.opened() as project: + done = adoption.adopt(project, adoption.make_plan(project, manifest, copy=True, replace=True)) + output = Path(done['entries'][0]['directory']) + (output / 'records.jsonl').write_text(json.dumps({'id': 'f1', 'kind': 'text', 'path': 'f1.txt'}) + '\n') + (output / 'f1.txt').write_text('abcdeF') + self.assertEqual(self.counts()['counts']['stale'], 1) + (output / 'f1.txt').write_text('abcdef') # a run's files never change; this one is read once, then kept + self.assertEqual(self.counts()['counts']['stale'], 1) + + +class Hashes(AnnotationCase): + + def test_computed_once_per_run_and_record_and_not_over_the_bound(self): + calls = [] + original = annotation_records._file_sha256 + + def counted(path, limit): + calls.append(os.path.basename(path)) + return original(path, limit) + + with mock.patch.object(annotation_records, '_file_sha256', counted): + self.set({'record': 'f1', 'state': 'draft'}, {'record': 'img', 'state': 'draft'}) + self.assertEqual(sorted(calls), ['f1.txt', 'img.png']) + self.counts() + self.call('annotated_records', task='scenes') + self.call('annotation', task='scenes', record='f1') + self.set({'record': 'f1', 'state': 'rejected'}) + self.assertEqual(sorted(calls), ['f1.txt', 'img.png']) + # The hash of a record that is not annotated is computed when it is asked for, once. + self.assertEqual(self.call('annotation', task='scenes', record='snd')['sha256'], + sha((self.output / 'snd.wav').read_bytes())) + self.call('annotation', task='scenes', record='snd') + self.assertEqual(calls.count('snd.wav'), 1) + self.assertEqual(self.call('annotation', task='scenes', record='f1')['annotation']['sha256'], sha('abcdef')) + # A record over the bound is not hashed: its annotation carries null and is tied by its id alone. + with mock.patch.object(annotation_records, 'HASH_LIMIT', 8): + self.write('big.txt', 'more than eight bytes') + self.write_list(self.records + [{'id': 'big', 'kind': 'text', 'path': 'big.txt'}]) + self.set({'record': 'big', 'state': 'draft'}) + one = self.call('annotation', task='scenes', record='big') + self.assertEqual((one['annotation']['sha256'], one['sha256'], one['stale']), (None, None, False)) + + def test_an_archive_member_is_hashed_decompressed(self): + import zipfile + member = b'inside the archive ' * 100 + self.write('pack.zip', inside_base.zip_bytes({'a.txt': member}, zipfile.ZIP_DEFLATED)) + self.write_list(self.records + [{'id': 'packed', 'kind': 'text', 'path': 'pack.zip!a.txt'}]) + self.set({'record': 'packed', 'state': 'draft'}) + self.assertEqual(self.call('annotation', task='scenes', record='packed')['annotation']['sha256'], sha(member)) + + def test_the_record_list_may_carry_the_hash(self): + bad = dict(self.records[1], sha256='ABC') + self.write_list([self.records[0], bad]) + listed = self.call('records', run=self.run_id) + self.assertEqual([record['sha256'] for record in listed['records']], [sha('hello world')]) + self.assertEqual(listed['problems'][0]['line'], 2) + self.assertIn('sha256', listed['problems'][0]['message']) + + +class Reads(AnnotationCase): + + def test_annotated_records_pages_and_filters(self): + self.set({'record': 't1', 'state': 'accepted', 'value': 'cat'}, {'record': 'img', 'state': 'rejected'}) + page = self.call('annotated_records', task='scenes', limit=2) + self.assertEqual((page['total'], page['run'], [record['id'] for record in page['records']]), + (5, self.run_id, ['t1', 't2'])) + first = page['records'][0] + self.assertEqual(first['annotation'], {'state': 'accepted', 'value': 'cat', 'note': None, 'by': 'owner', + 'at': AT, 'stale': False, 'unsaved': True}) + self.assertEqual((first['preview'], first['in_product'], first['sha256']), ('hello world', True, + sha('hello world'))) + self.assertIsNone(page['records'][1]['annotation']) + self.assertEqual(page['counts']['unannotated'], 3) + for state, expected in (('unannotated', ['t2', 'f1', 'snd']), ('accepted', ['t1']), ('rejected', ['img']), + ('draft', []), ('stale', []), ('invalid', [])): + with self.subTest(state): + found = self.call('annotated_records', task='scenes', state=state) + self.assertEqual(([record['id'] for record in found['records']], found['total']), + (expected, len(expected))) + self.assertEqual([record['id'] for record in self.call('annotated_records', task='annotations/scenes', + kind='image')['records']], ['img']) + self.assertEqual([record['id'] for record in self.call('annotated_records', task='scenes', offset=4)['records']], + ['snd']) + self.assertEqual(self.refused('annotated_records', task='scenes', limit=201).code, 'invalid') + self.assertEqual(self.refused('annotation', task='nothing', record='t1').code, 'not-found') + + def test_tasks_are_listed_with_what_the_page_needs(self): + tasks = self.call('annotation_tasks')['tasks'] + self.assertEqual([task['task'] for task in tasks], ['annotations/mentions', 'annotations/scenes', + 'annotations/shapes', 'annotations/speech']) + self.assertEqual(set(tasks[1]), {'task', 'title', 'dataset', 'type', 'vocabulary', 'run', 'records', 'counts', + 'unsaved'}) + self.assertEqual(tasks[1]['vocabulary'], ['cat', 'dog']) + + def test_reads_change_nothing_on_disk_and_are_not_recorded(self): + self.set({'record': 't1', 'state': 'draft'}) + before = sorted((path, path.stat().st_mtime_ns) for path in self.folder.rglob('*') if path.is_file()) + rows = len(self.call('activity')['items']) + self.call('annotation_tasks') + self.call('annotated_records', task='scenes') + self.call('annotation', task='scenes', record='t1') + self.call('status') + after = sorted((path, path.stat().st_mtime_ns) for path in self.folder.rglob('*') if path.is_file()) + self.assertEqual((before, len(self.call('activity')['items'])), (after, rows)) + + +class Many(AnnotationCase): + """100,000 annotations: set in batches of 200 through the service, counted, saved and opened again.""" + + COUNT = 100_000 + RECORDS = [{'id': f'r{index:06d}', 'kind': 'text', 'text': f'record {index}', 'sha256': sha(f'record {index}')} + for index in range(COUNT)] + + def test_one_hundred_thousand(self): + times = {} + started = time.perf_counter() + for first in range(0, self.COUNT, 200): + self.set(*({'record': f'r{index:06d}', 'state': ('accepted', 'draft', 'rejected', 'needs-work')[index % 4], + 'value': 'cat' if index % 4 == 0 else None} for index in range(first, first + 200))) + times['set'] = time.perf_counter() - started + + started = time.perf_counter() + listed = self.counts() + times['count'] = time.perf_counter() - started + self.assertEqual(listed['counts'], {'unannotated': 0, 'draft': 25_000, 'accepted': 25_000, + 'needs-work': 25_000, 'rejected': 25_000, 'stale': 0, 'invalid': 0}) + self.assertEqual(listed['unsaved'], self.COUNT) + started = time.perf_counter() + self.assertEqual(self.call('status')['annotations_unsaved'], [{'task': TASK, 'records': self.COUNT}]) + times['status'] = time.perf_counter() - started + + started = time.perf_counter() + self.assertEqual(self.call('save')['annotations_written'], [LINES]) + times['save'] = time.perf_counter() - started + self.assertEqual(len(self.lines_file().read_bytes().splitlines()), self.COUNT) + + started = time.perf_counter() + again = Service(self.folder) + self.addCleanup(again.close) + self.assertEqual(again.call('annotation', {'task': TASK, 'record': 'r099999'}, OWNER)['annotation']['state'], + 'needs-work') + times['reopen'] = time.perf_counter() - started + + self.service.close() + again.close() + store.drop_project(self.project_id) + inside.forget_indexes() + started = time.perf_counter() + fresh = Service(self.folder) + self.addCleanup(fresh.close) + self.assertEqual(fresh.call('annotation_tasks', {}, OWNER)['tasks'][1]['counts']['accepted'], 25_000) + times['import'] = time.perf_counter() - started + print(f'\n100,000 annotations: ' + ', '.join(f'{name} {seconds:.2f} s' for name, seconds in times.items()), + file=sys.stderr) + for name, bound in BOUNDS.items(): + self.assertLess(times[name], bound, name) + + +if __name__ == '__main__': + unittest.main() diff --git a/tests/test_tuldok_project_cli.py b/tests/test_tuldok_project_cli.py index eb6ff970..b0b25be2 100644 --- a/tests/test_tuldok_project_cli.py +++ b/tests/test_tuldok_project_cli.py @@ -181,7 +181,8 @@ def test_set_status_save(self): self.assertEqual(self.run_ok('save', self.folder), 'wrote datasets/waves\n') self.assertEqual((self.folder / 'datasets' / 'waves.json').read_text(encoding='utf-8'), text) self.assertEqual(self.run_json('save', self.folder), {'written': [], 'deleted': [], 'results_written': [], - 'results_deleted': []}) + 'results_deleted': [], 'annotations_written': [], + 'annotations_deleted': []}) self.assertEqual(self.run_ok('status', self.folder), 'Nothing is unsaved and no file changed on disk since the last import.\n') diff --git a/tests/test_tuldok_project_service.py b/tests/test_tuldok_project_service.py index 4fdd41ed..d6b5d726 100644 --- a/tests/test_tuldok_project_service.py +++ b/tests/test_tuldok_project_service.py @@ -48,7 +48,7 @@ class Table(unittest.TestCase): def test_every_operation_is_declared_once(self): names = [operation.name for operation in operations.OPERATIONS] - self.assertEqual(len(names), 49) # the rows of spec-m7.md section 2, of section 2 of spec-w1.md and spec-w3.md, and of section 3 of spec-d1.md and spec-d2.md + self.assertEqual(len(names), 54) # the rows of spec-m7.md section 2, of section 2 of spec-w1.md and spec-w3.md, of section 3 of spec-d1.md and spec-d2.md, and of section 5 of spec-d4.md self.assertEqual(len(set(names)), len(names)) for name in REQUEST_OPERATIONS: self.assertIsNotNone(operations.by_name(name)) @@ -79,7 +79,7 @@ def test_mutations_and_owner_rows(self): self.assertEqual(mutations, {'set_definition', 'remove_definition', 'revert_definition', 'save', 'resolve_conflict', 'import_values', 'check_environment', 'connect_environment', 'disconnect_environment', 'request_build', 'approve_build', 'decline_build', - 'cancel_build', 'cancel_run', 'stop_run'}) + 'cancel_build', 'cancel_run', 'stop_run', 'set_annotation', 'revert_annotations'}) owner = {operation.name for operation in operations.OPERATIONS if operation.who == 'owner'} self.assertEqual(owner, {'connect_environment', 'disconnect_environment', 'approve_build', 'decline_build'}) @@ -212,6 +212,8 @@ def test_every_read(self): 'weights_compare': {'run': run_id, 'path': 'weights.json', 'other_run': run_id, 'other_path': 'weights.json'}, 'array_tiles': {'run': run_id, 'path': 'weights.npy'}, + 'annotation_tasks': {}, 'annotated_records': {'task': 'none-here'}, + 'annotation': {'task': 'none-here', 'record': 'r1'}, } reads = [operation for operation in operations.OPERATIONS if not operation.mutation] arguments['build_requests'] = {'state': 'queued', 'limit': 5} @@ -228,6 +230,10 @@ def test_every_read(self): if operation.name == 'weights_compare': # fit-a's weights are JSON; test_tuldok_project_weights self.assertEqual(self.refused(operation.name, arguments[operation.name]).code, 'unsupported') continue + if operation.name in ('annotated_records', 'annotation'): # this fixture has no task; read in + # test_tuldok_project_annotation_rows + self.assertEqual(self.refused(operation.name, arguments[operation.name]).code, 'not-found') + continue if operation.name == 'note': # this fixture has no notes; read in test_tuldok_project_workspace self.assertEqual(self.refused(operation.name, arguments['note']).code, 'not-found') continue diff --git a/tests/test_tuldok_project_store.py b/tests/test_tuldok_project_store.py index 35010bfe..c3a7804a 100644 --- a/tests/test_tuldok_project_store.py +++ b/tests/test_tuldok_project_store.py @@ -45,7 +45,7 @@ } CLEAN_STATUS = {'unsaved': [], 'removed': [], 'added': [], 'changed': [], 'missing': [], 'irregular': [], - 'results_unsaved': [], 'results_changed': []} + 'results_unsaved': [], 'results_changed': [], 'annotations_unsaved': [], 'annotations_changed': []} @@ -439,7 +439,8 @@ def test_save_writes_and_deletes_files(self): self.project.remove_definition('charts/speed-accuracy') result = self.project.save() self.assertEqual(result, {'written': ['datasets/waves', 'models/extra'], 'deleted': ['charts/speed-accuracy'], - 'results_written': [], 'results_deleted': []}) + 'results_written': [], 'results_deleted': [], + 'annotations_written': [], 'annotations_deleted': []}) self.assertEqual(self.read('datasets/waves'), waves) self.assertEqual(self.read('models/extra'), extra) self.assertFalse((self.folder / 'charts' / 'speed-accuracy.json').exists()) diff --git a/tuldok_project/__main__.py b/tuldok_project/__main__.py index 7ec8c0fd..50022a85 100644 --- a/tuldok_project/__main__.py +++ b/tuldok_project/__main__.py @@ -332,6 +332,7 @@ def _graph(project, arguments): ('unsaved', 'unsaved'), ('removed', 'removed'), ('added', 'added on disk'), ('changed', 'changed on disk'), ('missing', 'missing on disk'), ('irregular', 'not a definition file'), ('results_unsaved', 'results unsaved'), ('results_changed', 'results changed on disk'), + ('annotations_changed', 'annotations changed on disk'), ) @@ -341,6 +342,8 @@ def _status(project, arguments): _json(status) return 0 rows = [(word, reference) for key, word in _STATUS_WORDS for reference in status[key]] + rows += [('annotations unsaved', f'{item["task"]} ({_plural(item["records"], "record")})') + for item in status['annotations_unsaved']] if rows: _columns(rows) else: @@ -408,6 +411,8 @@ def _save(project, arguments): rows += [('deleted', reference) for reference in saved['deleted']] rows += [('wrote', f'results/{name}.csv') for name in saved['results_written']] rows += [('deleted', f'results/{name}.csv') for name in saved['results_deleted']] + rows += [('wrote', path) for path in saved['annotations_written']] + rows += [('deleted', path) for path in saved['annotations_deleted']] if rows: _columns(rows) else: diff --git a/tuldok_project/annotation_records.py b/tuldok_project/annotation_records.py new file mode 100644 index 00000000..c7f7f2b1 --- /dev/null +++ b/tuldok_project/annotation_records.py @@ -0,0 +1,240 @@ +"""What an annotation needs to know of its dataset's product: a record's kind, size and content hash, and staleness. + +Owns the product side of sections 3 and 5 of +docs/plans/definition-first-projects/spec-d4.md. It reads a product through +inside.py (its record index, inside_archive's places) and opens no database: +the service finds the product and the kept hashes under its lock, calls these +functions outside it, and keeps what they computed. The hash of a record's +content is SHA-256 of its file, of an archive member's bytes once +decompressed, or of the UTF-8 of an inline text; a record over HASH_LIMIT +bytes is not hashed (None). check_items turns the items of set_annotation +into rows, checked with annotations.validate against the task, the +vocabulary, the record's kind and what is cheap to know of it: an image's +size (from its first bytes), a text's length (when its file is at most +inside.COUNT_TEXT_BYTES) and a WAVE sound's length (from its header). +""" +import codecs +import hashlib +import os +import struct + +from . import annotation_rows, annotations, inside, inside_archive, inside_shapes +from .store import ProjectError + +HASH_LIMIT = 1 << 30 # bytes of a record hashed; a larger one is tied by its id alone +ITEM_LIMIT = 200 # items of one set_annotation +WAVE_HEAD = 64 * 1024 # read for a sound's length +_CHUNK = 1 << 20 + + +# ------------------------------------------------------------- the product + +@inside.reading +def index(product): + """The record index of a product (inside.index_of); a damaged record list is refused unsupported.""" + return inside.index_of(product) + + +@inside.reading +def shown(product, record): + """A record of the index as the operation records shows it (spec-d1.md).""" + return inside._shown(product, record, preview=True) + + +# ---------------------------------------------------------------- the hash + +def _member_sha256(place, limit): + """SHA-256 of an archive member decompressed, streamed; None when it is over limit.""" + member, parent = place.member, place.parent + if member.size > limit: + return None + inside_archive._check_member(member) # an encrypted member is refused + view = parent.view + start = inside_archive._data_offset(view, member) + source = view[start:start + member.compressed] + digest = hashlib.sha256() + if member.method == 0: + for at in range(0, len(source), _CHUNK): + digest.update(source[at:at + _CHUNK]) + return digest.hexdigest() + engine = inside_archive._decompressor(member) + total, position = 0, 0 + zlib_engine = member.method == 8 + while not engine.eof: + if zlib_engine and engine.unconsumed_tail: + piece = engine.decompress(engine.unconsumed_tail, _CHUNK) + elif not zlib_engine and not engine.needs_input: + piece = engine.decompress(b'', _CHUNK) + elif position < len(source): + piece = engine.decompress(source[position:position + _CHUNK], _CHUNK) + position += _CHUNK + else: + break + total += len(piece) + if total > limit: + return None + digest.update(piece) + return digest.hexdigest() + + +def _file_sha256(path, limit): + with open(path, 'rb') as handle: + if os.fstat(handle.fileno()).st_size > limit: + return None + digest = hashlib.sha256() + total = 0 + while True: + chunk = handle.read(_CHUNK) + if not chunk: + return digest.hexdigest() + total += len(chunk) + if total > limit: + return None + digest.update(chunk) + + +def record_sha256(product, record): + """The hash of a record's content (a record of inside's index), or None: over HASH_LIMIT, or unreadable.""" + if record['path'] is None: + text = record['text'] or '' + return hashlib.sha256(text.encode('utf-8', 'surrogatepass')).hexdigest() + try: + place = inside_archive.locate(product.root, record['path']) + if place.member is not None: + return _member_sha256(place, HASH_LIMIT) + return _file_sha256(place.path, HASH_LIMIT) + except (ProjectError, *inside.DAMAGED): + return None + + +def current_hashes(product, index, records, kept): + """({record: hash or None} of the records in the product, {record: hash or None} newly computed). + + A record's hash is the one its list gives, else the one kept for this + run (kept), else it is computed now. Records not in the product are left + out. + """ + found, computed = {}, {} + for record_id in records: + position = index.by_id.get(record_id) + if position is None: + continue + record = index.records[position] + if record.get('sha256'): + found[record_id] = record['sha256'] + elif record_id in kept: + found[record_id] = kept[record_id] + else: + found[record_id] = computed[record_id] = record_sha256(product, record) + return found, computed + + +def is_stale(record_id, sha256, index, hashes): + """Whether an annotation is stale: its record is not in the product, or its content's hash differs. + + An annotation without a hash, or a record without one (over the bound), + is tied by its id alone. + """ + if record_id not in index.by_id: + return True + current = hashes.get(record_id) + return sha256 is not None and current is not None and sha256 != current + + +# ---------------------------------------------------------- what is cheap to know + +def _wave_seconds(head, size): + """The length in seconds of a RIFF WAVE from its first bytes and its file size, or None.""" + if len(head) < 12 or head[:4] != b'RIFF' or head[8:12] != b'WAVE': + return None + at, found = 12, None + while at + 8 <= len(head): + name, length = struct.unpack_from('<4sI', head, at) + body = at + 8 + if name == b'fmt ' and length >= 16 and body + 16 <= len(head): + _tag, channels, rate, _, align, _bits = struct.unpack_from(' (stamp, _Index) @@ -135,10 +136,11 @@ def finish(self): def _record(identifier, kind, path, *, size=None, **extra): return {'id': identifier, 'kind': kind, 'path': path, 'bytes': size, 'text': None, 'array': None, 'split': None, - 'rights': None, 'origin': None, 'meta': None, **extra} + 'rights': None, 'origin': None, 'meta': None, 'sha256': None, **extra} -_LIST_KEYS = ('id', 'kind', 'path', 'text', 'array', 'split', 'rights', 'origin', 'meta') +# sha256 is the hash of the record's content (spec-d4.md section 3), given by the list or None. +_LIST_KEYS = ('id', 'kind', 'path', 'text', 'array', 'split', 'rights', 'origin', 'meta', 'sha256') def _list_entry(value): @@ -166,12 +168,15 @@ def _list_entry(value): for key in ('origin', 'meta'): if value.get(key) is not None and not isinstance(value[key], dict): return f'{key} must be an object' + sha256 = value.get('sha256') + if sha256 is not None and not (isinstance(sha256, str) and _SHA256.fullmatch(sha256)): + return 'sha256 must be 64 lowercase hexadecimal characters' meta = dict(value.get('meta') or {}) for key, item in value.items(): if key not in _LIST_KEYS: meta.setdefault(key, item) return _record(identifier, kind, path, text=text, array=value.get('array'), split=value.get('split'), - rights=value.get('rights'), origin=value.get('origin'), meta=meta or None) + rights=value.get('rights'), origin=value.get('origin'), meta=meta or None, sha256=sha256) def _lines(place): @@ -381,7 +386,7 @@ def _preview(product, record): def _shown(product, record, *, preview): - shown = {key: record[key] for key in ('id', 'kind', 'path', 'split', 'rights', 'origin', 'meta')} + shown = {key: record[key] for key in ('id', 'kind', 'path', 'split', 'rights', 'origin', 'meta', 'sha256')} shown['bytes'] = _size_of(product, record) if record['array'] is not None: shown['array'] = record['array'] diff --git a/tuldok_project/operations.py b/tuldok_project/operations.py index bf4a5377..b2b27fb7 100644 --- a/tuldok_project/operations.py +++ b/tuldok_project/operations.py @@ -3,9 +3,10 @@ Owns the table of section 2 of docs/plans/definition-first-projects/spec-m7.md, with the three rows of section 2 of spec-w1.md (map, note, recipe_results) and the two of section 2 of spec-w3.md (draft_branch, revert_definition), the five of -section 3 of spec-d1.md (records, record, inside, array_slice, array_summary) -and the three of section 3 of spec-d2.md (weights, weights_compare, -array_tiles). +section 3 of spec-d1.md (records, record, inside, array_slice, array_summary), +the three of section 3 of spec-d2.md (weights, weights_compare, +array_tiles) and the five of section 5 of spec-d4.md (annotation_tasks, +annotated_records, annotation, set_annotation, revert_annotations). Each Operation names one operation project., the rule its caller must satisfy (who), whether it changes anything (mutation), a closed JSON Schema of its arguments and the result keys that are always present. service.py checks @@ -21,6 +22,11 @@ RECORD_KINDS = ('text', 'image', 'audio', 'pointcloud', 'mesh', 'array', 'file') # the kinds of a product's record TARGET_LIMIT = 50 REASON_CHARACTERS = 400 +ANNOTATION_STATES = ('draft', 'accepted', 'needs-work', 'rejected') # annotations.STATES +# The counts of annotation_tasks, and the filters of annotated_records. +ANNOTATION_COUNTS = ('unannotated', 'draft', 'accepted', 'needs-work', 'rejected', 'stale', 'invalid') +ANNOTATION_ITEMS = 200 # items of one set_annotation +REVERT_RECORDS = 10_000 # records named by one revert_annotations @dataclass(frozen=True) @@ -48,6 +54,13 @@ class Operation: _ADDRESS = {'type': 'string', 'minLength': 1, 'maxLength': 4096} # a path in a product; '!' names an archive member _ARRAY = {'type': 'string', 'minLength': 1, 'maxLength': 1024} _AXIS = {'type': 'integer', 'minimum': 0, 'maximum': 63} +_RECORD_ID = {'type': 'string', 'minLength': 1, 'maxLength': 600} # an annotation's record (spec-d4.md section 2) +_SET_ITEM = {'type': 'object', 'properties': {'record': _RECORD_ID, + 'state': {'type': 'string', 'enum': list(ANNOTATION_STATES)}, + 'value': {}, 'note': {'type': 'string', 'maxLength': 4000}}, + 'required': ['record', 'state'], 'additionalProperties': False} +_REMOVE_ITEM = {'type': 'object', 'properties': {'record': _RECORD_ID, 'remove': {'const': True}}, + 'required': ['record', 'remove'], 'additionalProperties': False} def _limit(most): @@ -61,7 +74,8 @@ def _arguments(required=(), **properties): # --------------------------------------------------------------- result keys SUMMARY = ('project_id', 'name', 'folder', 'code_root', 'kinds', 'states', 'worker') -STATUS = ('unsaved', 'removed', 'added', 'changed', 'missing', 'irregular', 'results_unsaved', 'results_changed') +STATUS = ('unsaved', 'removed', 'added', 'changed', 'missing', 'irregular', 'results_unsaved', 'results_changed', + 'annotations_unsaved', 'annotations_changed') DEFINITION = ('reference', 'kind', 'title', 'text', 'document', 'state', 'unsaved', 'removed', 'uses', 'used_by') PLAN = ('targets', 'every', 'buildable', 'blocked_targets', 'counts', 'gpu_steps', 'disk_gb', 'disk_unknown', 'wall_hours', 'wall_unknown', 'estimated_disk_gb', 'estimated_disk_steps', 'estimated_wall_hours', @@ -80,7 +94,7 @@ def _arguments(required=(), **properties): TILES = ('shape', 'dtype', 'across', 'axes', 'index', 'first', 'tiles', 'rows', 'columns', 'stride', 'values_f32', 'min', 'max', 'nonfinite') COMPARE = ('tensors', 'total', 'only_here', 'only_there', 'reshaped', 'unread') -SAVE = ('written', 'deleted', 'results_written', 'results_deleted') +SAVE = ('written', 'deleted', 'results_written', 'results_deleted', 'annotations_written', 'annotations_deleted') CANCEL_RUN = ('id', 'reference', 'subject', 'state', 'cancel_file', 'already_asked') STOP_RUN = ('id', 'reference', 'subject', 'was', 'state', 'killed', 'remaining', 'marked_unknown') @@ -189,6 +203,29 @@ def _arguments(required=(), **properties): axes={'type': 'array', 'items': _AXIS, 'minItems': 2, 'maxItems': 2}, index={'type': 'array', 'items': {'type': 'integer', 'minimum': 0}, 'maxItems': 64}, first=_OFFSET, most=_limit(64)), TILES), + Operation('annotation_tasks', 'List the annotation tasks, each with its dataset, current product and counts of ' + 'its records by the state of their annotations.', 'inspect', False, _arguments(), ('tasks',)), + Operation('annotated_records', "Read one page of the records of a task's dataset with their annotations, " + 'optionally in one state or of one kind, with the counts.', 'inspect', False, + _arguments(['task'], task=_NAME, state={'type': 'string', 'enum': list(ANNOTATION_COUNTS)}, + kind={'type': 'string', 'enum': list(RECORD_KINDS)}, offset=_OFFSET, limit=_limit(200)), + ('task', 'run', 'records', 'total', 'counts')), + Operation('annotation', "Read one record's annotation under a task as it now is and as it is in the file, " + "whether it is unsaved or stale, and the hash of the record's content.", 'inspect', False, + _arguments(['task', 'record'], task=_NAME, record=_RECORD_ID), + ('task', 'record', 'annotation', 'saved', 'unsaved', 'stale', 'sha256')), + Operation('set_annotation', "Check annotations of a task's records, or their removal, and keep them as unsaved " + 'edits; one item that does not check refuses them all.', 'edit', True, + _arguments(['task', 'items'], task=_NAME, + items={'type': 'array', 'minItems': 1, 'maxItems': ANNOTATION_ITEMS, + 'items': {'oneOf': [_SET_ITEM, _REMOVE_ITEM]}}, + **{'from': {'type': 'object'}}), + ('task', 'set', 'removed', 'unsaved')), + Operation('revert_annotations', "Put back the saved annotations of a task's named records, or of all its " + 'records, in place of their unsaved edits.', 'edit', True, + _arguments(['task'], task=_NAME, + records={'type': 'array', 'items': _RECORD_ID, 'minItems': 1, 'maxItems': REVERT_RECORDS}), + ('task', 'reverted')), Operation('set_definition', "Check a definition's text and keep it as an unsaved edit.", 'edit', True, _arguments(['reference', 'text'], reference=_REFERENCE, text=_TEXT), DEFINITION), Operation('remove_definition', 'Mark a definition that nothing uses as removed, until the project is saved.', diff --git a/tuldok_project/service.py b/tuldok_project/service.py index 3bd64533..6e99344c 100644 --- a/tuldok_project/service.py +++ b/tuldok_project/service.py @@ -12,7 +12,13 @@ for weights_compare the other run) with the project open for a moment and read its output directory through inside.py and inside_weights.py after closing it; product_file does the same for the file route; those reads run -outside the lock, so a long one holds up no other call. Nothing here knows of HTTP or of the app's access layer. +outside the lock, so a long one holds up no other call. The five operations +on annotations (spec-d4.md section 5) work the same way: what the database +holds of a task (its rows, the hashes kept for its product) is read under the +lock, the product is read and hashed outside it (annotation_records), and +what was computed is kept under the lock again; set_annotation finds and +reads the records it names before it takes the lock to check and store them. +Nothing here knows of HTTP or of the app's access layer. The worker (section 4) is one thread per service, started by start() and stopped by close(). It runs queued build requests one at a time while it @@ -29,6 +35,7 @@ import dataclasses import datetime import fcntl +import json import logging import math import os @@ -37,8 +44,8 @@ import jsonschema import psycopg -from . import (activity, build_requests, builds, charts, check, environments, inside, inside_weights, launcher, local, - operations, plan, store, workspace) +from . import (activity, annotation_records, annotation_rows, annotations, build_requests, builds, charts, check, + documents, environments, inside, inside_weights, launcher, local, operations, plan, store, workspace) from .documents import Problem CHECK_PROBLEMS = 200 @@ -69,11 +76,13 @@ index=a.get('index'), first=a.get('first', 0), most=a.get('most', 16)), } +# The reads of annotations (spec-d4.md section 5): each takes the service's lock itself, only for its database work. +ANNOTATION_READS = ('annotation_tasks', 'annotated_records', 'annotation') POLL_SECONDS = 1.0 # how often the worker looks for a queued request CLOSE_SECONDS = 30.0 # how long close() waits for the worker WORKER_LOCK = 'build-requests.lock' _LOG = logging.getLogger(__name__) -_TARGET_ARGUMENTS = ('reference', 'run', 'request') +_TARGET_ARGUMENTS = ('reference', 'run', 'request', 'task') def _plain(value): @@ -124,10 +133,26 @@ def _target(arguments): if isinstance(arguments, dict): for key in _TARGET_ARGUMENTS: if isinstance(arguments.get(key), str): + if key == 'task': # a task is named by its reference, given as a bare name or not + return annotation_rows.reference(_bare(arguments[key], annotation_rows.DIRECTORY)) return arguments[key] return '' +def _detail(name, result): + """The detail of a done activity row: how many records a change of annotations touched.""" + if name == 'set_annotation': + return f'{result["set"]} set, {result["removed"]} removed' + if name == 'revert_annotations': + return f'{result["reverted"]} reverted' + return '' + + +def _now(): + """The time an annotation is made: UTC, to the second (spec-d4.md section 2).""" + return datetime.datetime.now(datetime.timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ') + + def _write_cancel_file(directory): """Ask the launcher running in directory to cancel its run (builds.cancel does the same with a run's row).""" try: @@ -292,13 +317,33 @@ def call(self, name, arguments, actor): with self._lock: found = {key: self._product(arguments[key]) for key in PRODUCT_ARGUMENTS if key in arguments} return _plain(INSIDE_READS[name](found, dict(arguments))) - with self._lock: + if name in ANNOTATION_READS: + problems = _argument_problems(operation, arguments) + if problems: + raise store.ProjectError(f'The arguments of project.{name} do not match its schema.', 'invalid', + problems=problems) + return _plain(getattr(self, f'_{name}')(dict(arguments), actor)) + prepared = () + if name == 'set_annotation': # the records are found and read before the lock is taken to store them try: problems = _argument_problems(operation, arguments) if problems: raise store.ProjectError(f'The arguments of project.{name} do not match its schema.', 'invalid', problems=problems) - result = _plain(getattr(self, f'_{name}')(dict(arguments), actor)) + prepared = (self._prepare_annotations(dict(arguments)),) + except store.ProjectError as exc: + self._record_activity(actor, name, _target(arguments), exc.code, str(exc)) + raise + except Exception as exc: + self._record_activity(actor, name, _target(arguments), 'error', f'{type(exc).__name__}: {exc}') + raise + with self._lock: + try: + problems = [] if prepared else _argument_problems(operation, arguments) # prepared: checked above + if problems: + raise store.ProjectError(f'The arguments of project.{name} do not match its schema.', 'invalid', + problems=problems) + result = _plain(getattr(self, f'_{name}')(dict(arguments), actor, *prepared)) except store.ProjectError as exc: if operation.mutation: self._record_activity(actor, name, _target(arguments), exc.code, str(exc)) @@ -309,7 +354,7 @@ def call(self, name, arguments, actor): raise if operation.mutation: target = result.get('id', '') if name == 'request_build' else _target(arguments) - self._record_activity(actor, name, target, 'done') + self._record_activity(actor, name, target, 'done', _detail(name, result)) return result def _record_activity(self, actor, name, target, outcome, detail=''): @@ -493,6 +538,216 @@ def product_file(self, run, address, range_header=None): product = self._product(run) return inside.file_response(product, address, range_header) + # ---------------------------------------------------------- annotations + + def _located(self, project, document): + """(run id, output directory, the dataset's view) of the current product of a task's dataset, or None.""" + dataset = document.get('dataset') if isinstance(document, dict) else None + if not isinstance(dataset, str): + return None + row = project._execute('''SELECT p.run_id, r.state, r.directory FROM {schema}.products p + JOIN {schema}.runs r ON r.id = p.run_id + WHERE p.reference = %s AND p.subject = '' AND p.current''', (dataset,)).fetchone() + if row is None or row[1] not in ('succeeded', builds.ADOPTED) or not row[2]: + return None + parsed = documents.parse_reference(dataset) + held = project._execute('SELECT document FROM {schema}.definitions WHERE directory = %s AND name = %s ' + 'AND NOT removed', parsed).fetchone() if parsed else None + view = held[0].get('view') if held and isinstance(held[0], dict) else None + return row[0], os.path.join(row[2], builds.OUTPUT), view + + @staticmethod + def _product_of(located): + """(inside.Product, its record index) of what _located found, or (None, None) when there is none.""" + if located is None: + return None, None + try: + product = inside.Product(*located) + except store.ProjectError: + return None, None # its output directory is gone + return product, annotation_records.index(product) + + def _gather(self, project, name, document): + """What the database holds of one task for its counts and its records: read under the lock.""" + connection, schema = project._connection, project.schema + annotation_rows.recheck(connection, schema, name, document) + located = self._located(project, document) + return {'name': name, 'document': document, 'located': located, + 'held': annotation_rows.held_rows(connection, schema, name), + 'unsaved': annotation_rows.unsaved_counts(connection, schema).get(name, 0), + 'kept': annotation_rows.cached_hashes(connection, schema, located[0]) if located else {}} + + @staticmethod + def _judge(gathered): + """Read the task's product outside the lock: its index, the hashes of the annotated records, what is stale.""" + product, index = Service._product_of(gathered['located']) + held = gathered['held'] + hashes, computed, stale = {}, {}, set() + if index is not None: + hashes, computed = annotation_records.current_hashes(product, index, held, gathered['kept']) + stale = {record for record, (sha, *_rest) in held.items() + if annotation_records.is_stale(record, sha, index, hashes)} + counts = dict.fromkeys(operations.ANNOTATION_COUNTS, 0) + for _sha, state, valid, _unsaved in held.values(): + counts[state] += 1 + counts['invalid'] += not valid + counts['stale'] = len(stale) + if index is not None: + counts['unannotated'] = len(index.records) - sum(1 for record in held if record in index.by_id) + return {**gathered, 'product': product, 'index': index, 'hashes': hashes, 'computed': computed, + 'stale': stale, 'counts': counts} + + def _keep_hashes(self, judged): + """Keep the hashes computed outside the lock, per run and record.""" + if judged['computed']: + with self._lock, self._open() as project: + annotation_rows.keep_hashes(project._connection, project.schema, judged['located'][0], + judged['computed']) + + def _annotation_tasks(self, arguments, actor): + with self._lock, self._open() as project: + gathered = [self._gather(project, name, document) for name, document in project.annotation_tasks().items()] + tasks = [] + for item in gathered: + judged = self._judge(item) + self._keep_hashes(judged) + document, index = judged['document'], judged['index'] + tasks.append({'task': annotation_rows.reference(judged['name']), 'title': document.get('title'), + 'dataset': document.get('dataset'), 'type': document.get('task'), + 'vocabulary': document.get('vocabulary') or [], + 'run': judged['located'][0] if index is not None else None, + 'records': len(index.records) if index is not None else None, + 'counts': judged['counts'], 'unsaved': judged['unsaved']}) + return {'tasks': tasks} + + def _annotated_records(self, arguments, actor): + with self._lock, self._open() as project: + name, document = project.annotation_task(arguments['task']) + gathered = self._gather(project, name, document) + judged = self._judge(gathered) + held, index, stale = judged['held'], judged['index'], judged['stale'] + wanted, kind = arguments.get('state'), arguments.get('kind') + listed = [record for record in (index.records if index is not None else []) + if kind is None or record['kind'] == kind] + gone = [] if kind is not None else sorted( + (record for record in held if index is None or record not in index.by_id), key=annotations.sort_key) + + def chosen(record_id): + if wanted is None: + return True + if wanted == 'unannotated': + return record_id not in held + if record_id not in held: + return False + if wanted == 'stale': + return record_id in stale + if wanted == 'invalid': + return not held[record_id][2] + return held[record_id][1] == wanted + + ids = [(record['id'], record) for record in listed if chosen(record['id'])] + ids += [(record_id, None) for record_id in gone if wanted != 'unannotated' and chosen(record_id)] + offset, limit = arguments.get('offset', 0), arguments.get('limit', 50) + page = ids[offset:offset + limit] + with self._lock, self._open() as project: + if judged['computed']: + annotation_rows.keep_hashes(project._connection, project.schema, judged['located'][0], + judged['computed']) + found = annotation_rows.rows(project._connection, project.schema, name, [record_id for record_id, _ in page]) + records = [] + for record_id, record in page: + shown = (annotation_records.shown(judged['product'], record) if record is not None + else {'id': record_id, 'kind': None, 'path': None, 'split': None, 'rights': None, + 'origin': None, 'meta': None, 'sha256': None, 'bytes': None}) + shown['in_product'] = record is not None + current, _saved, unsaved = found.get(record_id, (None, None, False)) + shown['annotation'] = None if current is None else { + 'state': current['state'], 'value': current['value'], 'note': current.get('note'), + 'by': current['by'], 'at': current['at'], + 'stale': record_id in stale if index is not None else None, 'unsaved': unsaved} + records.append(shown) + return {'task': annotation_rows.reference(name), 'run': judged['located'][0] if index is not None else None, + 'records': records, 'total': len(ids), 'counts': judged['counts']} + + def _annotation(self, arguments, actor): + record_id = arguments['record'] + with self._lock, self._open() as project: + name, document = project.annotation_task(arguments['task']) + located = self._located(project, document) + kept = (annotation_rows.cached_hashes(project._connection, project.schema, located[0], [record_id]) + if located else {}) + current, saved, unsaved = annotation_rows.rows(project._connection, project.schema, name, + [record_id]).get(record_id, (None, None, False)) + product, index = self._product_of(located) + sha256, stale = None, None + if index is not None: + hashes, computed = annotation_records.current_hashes(product, index, [record_id], kept) + sha256 = hashes.get(record_id) + if current is not None: + stale = annotation_records.is_stale(record_id, current['sha256'], index, hashes) + self._keep_hashes({'computed': computed, 'located': located}) + return {'task': annotation_rows.reference(name), 'record': record_id, 'annotation': current, + 'saved': None if saved is None else json.loads(saved), 'unsaved': unsaved, 'stale': stale, + 'sha256': sha256} + + def _prepare_annotations(self, arguments): + """Find the task and its product under the lock, then read the records the items set outside it. + + Returns what _set_annotation needs: the task as it was, the run, and + for each record set, its facts and hash (None when the product does not + have it), and the hashes computed here. + """ + setting = [item['record'] for item in arguments['items'] if not item.get('remove')] + with self._lock, self._open() as project: + name, document = project.annotation_task(arguments['task']) + located = self._located(project, document) + kept = (annotation_rows.cached_hashes(project._connection, project.schema, located[0], setting) + if located and setting else {}) + known, computed = {}, {} + if setting: + product, index = self._product_of(located) + if index is None: + raise store.ProjectError(f'{document.get("dataset")} has no product to annotate; build it first.', + 'not-found', references=[document.get('dataset')]) + hashes, computed = annotation_records.current_hashes(product, index, setting, kept) + for record_id in setting: + position = index.by_id.get(record_id) + if position is not None: + known[record_id] = (annotation_records.facts(product, index.records[position], + document.get('task')), hashes.get(record_id)) + return {'name': name, 'document': document, 'run': located[0] if located else None, 'known': known, + 'computed': computed} + + def _set_annotation(self, arguments, actor, prepared): + with self._open() as project: + name, document = project.annotation_task(arguments['task']) + located = self._located(project, document) + if (annotation_rows.fingerprint(document) != annotation_rows.fingerprint(prepared['document']) + or document.get('dataset') != prepared['document'].get('dataset') + or (located[0] if located else None) != prepared['run']): + raise store.ProjectError(f'{annotation_rows.reference(name)} or the product of its dataset changed ' + 'while the annotations were being checked; try again.', 'busy', + references=[annotation_rows.reference(name)]) + if prepared['computed']: + annotation_rows.keep_hashes(project._connection, project.schema, prepared['run'], + prepared['computed']) + rows, removals, problems = annotation_records.check_items( + document, arguments['items'], prepared['known'], by=annotation_records.by_of(actor), at=_now(), + origin=arguments.get('from')) + if problems: + raise store.ProjectError(f'{len(problems)} of the items cannot be kept; nothing was changed.', + 'invalid', problems=[Problem('error', annotation_rows.path(name), pointer, + message) for pointer, message in problems], + references=[annotation_rows.reference(name)]) + done, removed, unsaved = project.set_annotations(name, rows, removals, document) + return {'task': annotation_rows.reference(name), 'set': done, 'removed': removed, 'unsaved': unsaved} + + def _revert_annotations(self, arguments, actor): + with self._open() as project: + name, document = project.annotation_task(arguments['task']) + reverted = project.revert_annotations(name, arguments.get('records'), document) + return {'task': annotation_rows.reference(name), 'reverted': reverted} + # ------------------------------------------------------------- changes def _set_definition(self, arguments, actor): diff --git a/tuldok_project/store.py b/tuldok_project/store.py index d0a6e256..8fed5499 100644 --- a/tuldok_project/store.py +++ b/tuldok_project/store.py @@ -25,6 +25,12 @@ The record of changes asked through the service (spec-m7.md section 5) lives in one more table owned by activity, and the build requests (section 4) in one owned by build_requests. +Annotations (spec-d4.md sections 3 and 4) live in three more tables owned by +annotation_rows and follow the definitions' pattern row by row: a task's line +file is imported when it changed on disk (its size and time are compared +before it is hashed), an unsaved row whose saved line the file changes is a +conflict, status counts the unsaved rows without writing a file, and save +writes each task's file that has unsaved rows, whole. The state row also keeps tuldok.json as last imported (spec-w1.md: the map's groups and track are read from it); a change to it alone imports the folder again, and the chart its map.chart names cannot be removed. @@ -44,8 +50,8 @@ from metadata import connection_info -from . import (activity, build_requests, builds, check, documents, environments, folder as folder_reader, graph, - result_rows, results) +from . import (activity, annotation_rows, annotations, build_requests, builds, check, documents, environments, + folder as folder_reader, graph, result_rows, results) from .documents import Problem PROJECT_ID = re.compile(r'^[a-f0-9]{32}$') @@ -70,6 +76,7 @@ PRIMARY KEY (from_ref, to_ref, role))''', 'CREATE INDEX IF NOT EXISTS edges_to ON {schema}.edges (to_ref)', *result_rows.TABLES, + *annotation_rows.TABLES, ) # Later additive changes go here as ALTER TABLE ... ADD COLUMN IF NOT EXISTS. # state.project: tuldok.json as last imported, for the map's groups and track (spec-w1.md). @@ -166,9 +173,11 @@ def _read_project_file(root): @dataclass(frozen=True) class DiskListing: - """The definition files on disk: reference -> SHA-256, and paths that are not plain definition files.""" + """The definition files on disk: reference -> SHA-256, paths that are not plain definition files, and the + tasks' line files: task name -> (size, mtime in nanoseconds), which are not read here.""" files: dict irregular: tuple + lines: dict def _list_definitions(root): @@ -176,10 +185,11 @@ def _list_definitions(root): Anything the layout rules would refuse (a link, a non-.json entry, a bad name, an oversize file) is put in irregular, which sends open() to the checker. - A task's annotations/.jsonl beside its .json is neither listed - nor irregular; one without its task is irregular. + A task's annotations/.jsonl beside its .json is not a + definition file: its size and time go in lines; one without its task is + irregular. """ - files, irregular = {}, [] + files, irregular, lines = {}, [], {} root_fd = _open_root(root) try: top = dict(folder_reader.entries(root_fd)) @@ -198,7 +208,13 @@ def _list_definitions(root): if (directory == folder_reader.ANNOTATIONS and name.endswith(folder_reader.LINES_SUFFIX) and entry_kind == 'file' and name[:-len(folder_reader.LINES_SUFFIX)] + '.json' in tasks): - continue # a task's annotations (spec-d4.md section 2): not a definition file + # a task's annotations (spec-d4.md section 2): not a definition file, and not read here + try: + info = os.stat(name, dir_fd=fd, follow_symlinks=False) + except FileNotFoundError: + continue + lines[name[:-len(folder_reader.LINES_SUFFIX)]] = (info.st_size, info.st_mtime_ns) + continue stem = name[:-len('.json')] if name.endswith('.json') else None if entry_kind != 'file' or stem is None or not documents.is_name(stem): irregular.append(path) @@ -213,7 +229,7 @@ def _list_definitions(root): os.close(fd) finally: os.close(root_fd) - return DiskListing(files, tuple(irregular)) + return DiskListing(files, tuple(irregular), lines) def _list_results(root): @@ -398,12 +414,13 @@ def _attach(self, root, project, *, rebind, on_conflict): if state is not None and state['folder'] != root and not rebind: raise ProjectError(f'This project is bound to {state["folder"]}, not {root}; ' 'open it with rebind to move it here.', 'bound-elsewhere') - rows, recorded_results = {}, {} + rows, recorded_results, recorded_lines = {}, {}, {} if exists: for reference, file_sha256, unsaved, removed in self._execute( f'SELECT {_REFERENCE_SQL}, file_sha256, unsaved, removed FROM {{schema}}.definitions'): rows[reference] = (file_sha256, unsaved or removed) recorded_results = dict(self._execute('SELECT benchmark, file_sha256 FROM {schema}.results_files')) + recorded_lines = annotation_rows.recorded_files(self._connection, self.schema) listing = _list_definitions(root) results_on_disk, results_irregular = _list_results(root) on_disk = {reference: sha for reference, (sha, _) in rows.items() if sha is not None} @@ -413,12 +430,17 @@ def _attach(self, root, project, *, rebind, on_conflict): and {name: _sha(raw) for name, raw in results_on_disk.items()} == recorded_results and state['name'] == project['name'] and state['code_root'] == code_root and state['project'] == project): - if state['folder'] != root: - self._execute('UPDATE {schema}.state SET folder = %s', (root,)) - return - self._import(root, rows, on_conflict, results_on_disk, recorded_results) - - def _import(self, root, rows, on_conflict, results_on_disk, recorded_results): + touched = _touched_lines(root, listing.lines, recorded_lines) + if touched is not None: + with self._connection.transaction(): + for name, (sha, size, mtime) in touched.items(): + annotation_rows.record_file(self._connection, self.schema, name, sha, size, mtime) + if state['folder'] != root: + self._execute('UPDATE {schema}.state SET folder = %s', (root,)) + return + self._import(root, rows, on_conflict, results_on_disk, recorded_results, recorded_lines, listing.lines) + + def _import(self, root, rows, on_conflict, results_on_disk, recorded_results, recorded_lines, disk_lines): report = check.check_folder(root) if not report.ok: raise ProjectError(f'The project folder {root} has errors; fix them and open it again.', 'invalid', @@ -438,10 +460,29 @@ def _import(self, root, rows, on_conflict, results_on_disk, recorded_results): reseat.append((reference, disk_sha)) continue (take if disk_sha is not None else delete).append(reference) - if conflicts and on_conflict is None: - raise ProjectError('These definitions changed on disk and also have unsaved edits here: ' - + ', '.join(conflicts) + '. Open again keeping or discarding the edits.', - 'conflict', references=conflicts) + exists = self._schema_exists() + lines_plan, touched = self._lines_to_import(root, disk, recorded_lines, disk_lines, exists) + unsaved_rows = annotation_rows.unsaved_counts(self._connection, self.schema) if exists else {} + line_conflicts = [] + for name, item in lines_plan.items(): + if item['lines'] is not None and item['comparison'].contested: + line_conflicts.append(annotation_rows.path(name)) + tasks_gone = sorted(documents.parse_reference(reference)[1] for reference in delete + if reference.startswith(annotation_rows.DIRECTORY + '/')) + for name in tasks_gone: + if unsaved_rows.get(name) and annotation_rows.path(name) not in line_conflicts: + line_conflicts.append(annotation_rows.path(name)) + line_conflicts.sort() + if (conflicts or line_conflicts) and on_conflict is None: + named = conflicts + line_conflicts + raise ProjectError('These definitions or annotations changed on disk and also have unsaved edits here: ' + + ', '.join(named) + '. Open again keeping or discarding the edits.', + 'conflict', references=named) + kept_gone = [annotation_rows.path(name) for name in tasks_gone if unsaved_rows.get(name)] + if kept_gone and on_conflict == 'keep': + raise ProjectError('These annotations have unsaved edits here, but their task was removed from the ' + 'folder: ' + ', '.join(kept_gone) + '. Open again discarding the edits, or put the ' + 'task back in the folder.', 'invalid', references=kept_gone) # The project as it will be: the folder, with the unsaved edits the database keeps. merged = dict(disk) @@ -486,6 +527,26 @@ def _import(self, root, rows, on_conflict, results_on_disk, recorded_results): result_rows.remove_benchmark(self._connection, self.schema, name) if directory == environments.DIRECTORY: environments.forget(self._connection, self.schema, name) + if directory == annotation_rows.DIRECTORY: + annotation_rows.forget_task(self._connection, self.schema, name) + for name, (sha, size, mtime) in touched.items(): + annotation_rows.record_file(self._connection, self.schema, name, sha, size, mtime) + for name, item in lines_plan.items(): + if name in tasks_gone: + continue + comparison, lines = item['comparison'], item['lines'] + taken, reseated = list(comparison.take), [] + if lines is None or on_conflict == 'keep': + reseated = comparison.contested + else: + taken += [record for record, _ in comparison.contested] + task = merged.get(annotation_rows.reference(name)) + annotation_rows.apply_import(self._connection, self.schema, name, lines, + task.document if task is not None else None, taken, reseated) + if lines is None: + annotation_rows.forget_file(self._connection, self.schema, name) + else: + annotation_rows.record_file(self._connection, self.schema, name, *item['stamp']) for reference in take: directory, name = documents.parse_reference(reference) if directory == 'benchmarks' and reference in merged: @@ -504,6 +565,67 @@ def _import(self, root, rows, on_conflict, results_on_disk, recorded_results): project = EXCLUDED.project''', (self.project_id, project['name'], root, project.get('code_root', '.'), Jsonb(project))) + def _lines_to_import(self, root, disk, recorded, disk_lines, exists): + """({task name: {lines, comparison, stamp}} of line files new, changed or gone, {name: (sha, size, mtime)} + of those whose size or time alone changed). + + A file whose size and time are those recorded is not read. One that is + read is checked again against its task in the folder (it may have + changed since the checker read it); an error refuses the open invalid. + lines is {record: (the line as it is in the file, its row)}, or None + for a file that is gone; stamp is (sha256, size, mtime_ns). + """ + plan, touched, problems = {}, {}, [] + for name in sorted(set(disk_lines) | set(recorded)): + known = recorded.get(name) + if name not in disk_lines: + plan[name] = {'lines': None, 'stamp': None, + 'comparison': annotation_rows.compare(self._connection, self.schema, name, None)} + continue + if known is not None and tuple(known[1:]) == disk_lines[name]: + continue + where = annotation_rows.path(name) + try: + found = _read_lines(root, name) + except folder_reader.Unsafe as exc: + raise ProjectError(f'{where} cannot be read; fix it and open the project again.', 'invalid', + problems=[Problem('error', where, '', str(exc))]) from None + if found is None: + if known is not None: + plan[name] = {'lines': None, 'stamp': None, + 'comparison': annotation_rows.compare(self._connection, self.schema, name, None)} + continue + raw, size, mtime = found + sha = _sha(raw) + if known is not None and sha == known[0]: + touched[name] = (sha, size, mtime) + continue + task = disk.get(annotation_rows.reference(name)) + if task is None or not isinstance(task.document, dict): + problems.append(Problem('error', where, '', f'There is no {annotation_rows.reference(name)}.json, ' + 'the task of these annotations.')) + continue + parsed = annotations.read(raw, task.document.get('task'), task.document.get('vocabulary', [])) + errors = [Problem(item.severity, where, item.pointer, item.message) + for item in parsed.reported() if item.severity == 'error'] + if errors: + problems.extend(errors) + continue + pieces = raw.decode('utf-8').split('\n') + lines = {} + for number, row in parsed.rows: + if annotation_rows.has_nul(row): + problems.append(Problem('error', where, f'line {number}', 'The line holds the character U+0000, ' + 'which Tuldok cannot keep; remove it.')) + lines[row['record']] = (pieces[number - 1], row) + comparison = (annotation_rows.compare(self._connection, self.schema, name, lines) if exists + else annotation_rows.Comparison(take=list(lines))) + plan[name] = {'lines': lines, 'stamp': (sha, size, mtime), 'comparison': comparison} + if problems: + raise ProjectError('A file of annotations changed while the folder was being opened, or holds what ' + 'Tuldok cannot keep; fix it and open the project again.', 'invalid', problems=problems) + return plan, touched + def _results_to_import(self, disk, merged, results_on_disk, recorded_results): """({benchmark: text} of new or changed results files, [benchmarks whose file is gone]). @@ -590,6 +712,10 @@ def status(self): are not the results file as last imported or saved (save would write or remove it); results_changed names the results files added, changed or removed on disk since then. + annotations_unsaved is [{task, records}]: per task (its reference), how + many records have an unsaved change; annotations_changed names the line + files added, changed or removed on disk since then, by size and time + alone. Neither renders nor reads a line file. """ state = self._state() rows = self._execute(f'SELECT {_REFERENCE_SQL}, file_sha256, unsaved, removed FROM {{schema}}.definitions').fetchall() @@ -610,7 +736,12 @@ def status(self): 'irregular': list(listing.irregular) + list(results_irregular), 'results_unsaved': [name for name, (text, recorded_sha) in texts.items() if result_rows.differs(text, recorded_sha)], - 'results_changed': results_changed} + 'results_changed': results_changed, + 'annotations_unsaved': [{'task': annotation_rows.reference(name), 'records': count} + for name, count in annotation_rows.unsaved_counts(self._connection, + self.schema).items()], + 'annotations_changed': _lines_changed(listing.lines, annotation_rows.recorded_files( + self._connection, self.schema))} # ------------------------------------------------------------ editing @@ -695,6 +826,11 @@ def remove_definition(self, reference): if row is None: raise ProjectError(f'There is no definition {reference}.', 'not-found', references=[reference]) self._refuse_in_use(reference) + if directory == annotation_rows.DIRECTORY: + held = annotation_rows.held_count(self._connection, self.schema, name) + if held: + raise ProjectError(f'{reference} has {held} annotation{"s" if held != 1 else ""}; remove ' + f'{"them" if held != 1 else "it"} first.', 'in-use', references=[reference]) if row[0] is None: # Never written to disk: there is no file for save() to delete. self._drop(reference) @@ -716,9 +852,11 @@ def _refuse_in_use(self, reference): def _drop(self, reference): """Delete a definition's row outright (there is no file for save() to delete) and forget its records.""" - self._execute('DELETE FROM {schema}.definitions WHERE directory = %s AND name = %s', - documents.parse_reference(reference)) + directory, name = documents.parse_reference(reference) + self._execute('DELETE FROM {schema}.definitions WHERE directory = %s AND name = %s', (directory, name)) self._forget(reference) + if directory == annotation_rows.DIRECTORY: + annotation_rows.forget_task(self._connection, self.schema, name) def _forget(self, reference): """Drop what a definition that is gone leaves: its edges, runs and products, results, environment record.""" @@ -817,6 +955,11 @@ def save(self): Otherwise nothing is written and ProjectError (code changed-on-disk) names them. Returns the references written and deleted, and the benchmarks whose results files were written and deleted. + Each task with an unsaved annotation (or removed, with a line file) + has annotations/.jsonl written whole from all its rows through + annotations.write, or deleted when no annotation is left + (spec-d4.md section 4), under the same rule; annotations_written and + annotations_deleted name those files. """ root = self._state()['folder'] rows = self._execute(f'SELECT {_REFERENCE_SQL}, text, file_sha256, removed FROM {{schema}}.definitions ' @@ -838,6 +981,7 @@ def save(self): changed.append(_results_path(name)) else: results_plan.append((name, text, True)) + lines_plan = self._lines_to_save(root, changed) if changed: raise ProjectError('These files changed on disk since they were imported: ' + ', '.join(changed) + '. Open the project again to take or keep the changes.', 'changed-on-disk', @@ -860,7 +1004,24 @@ def save(self): if must_change: _write_path(root, folder_reader.RESULTS, f'{name}.csv', text.encode('utf-8')) results_written.append(name) + annotations_written, annotations_deleted = [], [] + for name, data, must_change, _ in lines_plan: + if must_change and data is None: + _delete_path(root, folder_reader.ANNOTATIONS, name + folder_reader.LINES_SUFFIX) + annotations_deleted.append(annotation_rows.path(name)) + elif must_change: + _write_path(root, folder_reader.ANNOTATIONS, name + folder_reader.LINES_SUFFIX, data) + annotations_written.append(annotation_rows.path(name)) with self._connection.transaction(): + for name, data, _, lines in lines_plan: + annotation_rows.mark_saved(self._connection, self.schema, name, lines) + if data is None: + annotation_rows.forget_file(self._connection, self.schema, name) + else: # the file now holds data: its digest is known, its size and time are read + info = os.stat(os.path.join(root, folder_reader.ANNOTATIONS, name + folder_reader.LINES_SUFFIX), + follow_symlinks=False) + annotation_rows.record_file(self._connection, self.schema, name, _sha(data), info.st_size, + info.st_mtime_ns) for name, text, _ in results_plan: if text is None: result_rows.forget_file(self._connection, self.schema, name) @@ -876,7 +1037,68 @@ def save(self): cursor.executemany(self._sql('DELETE FROM {schema}.definitions WHERE directory = %s AND name = %s'), [documents.parse_reference(reference) for reference in deleted]) return {'written': written, 'deleted': deleted, - 'results_written': results_written, 'results_deleted': results_deleted} + 'results_written': results_written, 'results_deleted': results_deleted, + 'annotations_written': annotations_written, 'annotations_deleted': annotations_deleted} + + def _lines_to_save(self, root, changed): + """[(task name, bytes to write or None to delete, whether the file must change, [(record, line)])]. + + The tasks are those with an unsaved row, and removed tasks whose line + file is recorded. A file whose content is neither the one recorded nor + the one to be written is added to changed by its path. + """ + recorded = annotation_rows.recorded_files(self._connection, self.schema) + names = set(annotation_rows.unsaved_counts(self._connection, self.schema)) + names |= {name for (name,) in self._execute('SELECT name FROM {schema}.definitions WHERE directory = %s ' + 'AND removed', (annotation_rows.DIRECTORY,)) + if name in recorded} + plan = [] + for name in sorted(names): + data, lines = annotation_rows.file_text(self._connection, self.schema, name) + if not lines: + data = None + known = recorded.get(name) + current = _lines_sha(root, name, known) + target = None if data is None else _sha(data) + if current == target: + plan.append((name, data, False, lines)) + elif current != (known[0] if known else None): + changed.append(annotation_rows.path(name)) + else: + plan.append((name, data, True, lines)) + return plan + + # -------------------------------------------------------- annotations + + def annotation_tasks(self): + """{task name: document} of every task not removed, by name.""" + return dict(self._execute('SELECT name, document FROM {schema}.definitions WHERE directory = %s ' + 'AND NOT removed ORDER BY name', (annotation_rows.DIRECTORY,)).fetchall()) + + def annotation_task(self, task): + """(name, document) of a task given by name or reference; refused not-found when the project has none.""" + name = task[len(annotation_rows.DIRECTORY) + 1:] if task.startswith(annotation_rows.DIRECTORY + '/') else task + row = self._execute('SELECT document FROM {schema}.definitions WHERE directory = %s AND name = %s ' + 'AND NOT removed', (annotation_rows.DIRECTORY, name)).fetchone() \ + if documents.is_name(name) else None + if row is None: + raise ProjectError(f'There is no task {annotation_rows.reference(name)}.', 'not-found', + references=[annotation_rows.reference(name)]) + return name, row[0] + + def set_annotations(self, name, given, removals, document): + """Store checked rows and removals of task name as unsaved, in one transaction (annotation_rows.set_rows). + + Returns (set, removed, how many records of the task are now unsaved). + """ + with self._connection.transaction(): + done = annotation_rows.set_rows(self._connection, self.schema, name, given, removals, document) + return (*done, annotation_rows.unsaved_counts(self._connection, self.schema).get(name, 0)) + + def revert_annotations(self, name, records, document): + """Put back the saved lines of the task's unsaved records (all when records is None); returns how many.""" + with self._connection.transaction(): + return annotation_rows.revert(self._connection, self.schema, name, records, document) # ------------------------------------------------------------ results @@ -950,6 +1172,77 @@ def __exit__(self, *exc): # --------------------------------------------------------------- files +def _touched_lines(root, disk_lines, recorded): + """None when a task's line file is new, gone or changed in content; else {name: (sha, size, mtime)} of the + files whose size or time alone differ from those recorded (they are read and hashed; the others are not).""" + if set(disk_lines) != set(recorded): + return None + touched = {} + for name, stamp in disk_lines.items(): + if tuple(recorded[name][1:]) == stamp: + continue + try: + found = _read_lines(root, name) + except folder_reader.Unsafe: + return None + if found is None or _sha(found[0]) != recorded[name][0]: + return None + touched[name] = (recorded[name][0], found[1], found[2]) + return touched + + +def _read_lines(root, name): + """(bytes, size, mtime_ns) of annotations/.jsonl; None when there is none, folder.Unsafe when it is not + a plain file. The size and time are taken before the bytes are read, so a change while reading shows next time.""" + filename = name + folder_reader.LINES_SUFFIX + try: + fd = os.open(os.path.join(root, folder_reader.ANNOTATIONS), folder_reader.DIRECTORY_FLAGS) + except FileNotFoundError: + return None + except OSError as exc: + raise folder_reader.Unsafe(f'The directory {folder_reader.ANNOTATIONS} cannot be opened: {exc.strerror}.') \ + from None + try: + try: + info = os.stat(filename, dir_fd=fd, follow_symlinks=False) + except FileNotFoundError: + return None + return folder_reader.read(fd, filename, folder_reader.LINES_LIMIT), info.st_size, info.st_mtime_ns + finally: + os.close(fd) + + +def _lines_sha(root, name, known): + """SHA-256 of a task's line file, None when there is none, 'unreadable' when it is not a plain file; the + recorded digest when its size and time are those recorded in known ((sha, size, mtime) or None).""" + try: + info = os.stat(os.path.join(root, folder_reader.ANNOTATIONS, name + folder_reader.LINES_SUFFIX), + follow_symlinks=False) + except FileNotFoundError: + return None + except OSError: + return 'unreadable' + if known is not None and (info.st_size, info.st_mtime_ns) == tuple(known[1:]): + return known[0] + try: + found = _read_lines(root, name) + except folder_reader.Unsafe: + return 'unreadable' + return None if found is None else _sha(found[0]) + + +def _lines_changed(disk_lines, recorded): + """The paths of the line files added, removed, or whose size or time differ from those recorded.""" + def differs(name): + disk, known = disk_lines.get(name), recorded.get(name) + if disk is None or known is None: + return disk is not known + # A file recorded while its time was still fresh was compared by content when the project was opened for + # this call (annotation_rows.UNSETTLED): only its size can say more here. + return disk[0] != known[1] or (known[2] != annotation_rows.UNSETTLED and disk[1] != known[2]) + return sorted(annotation_rows.path(name) for name in set(disk_lines) | set(recorded) if differs(name)) + + def _file_sha(root, reference): """SHA-256 of the definition file on disk, None when it does not exist, 'unreadable' when it is not a plain file.""" directory, name = documents.parse_reference(reference) From 7d376b618b2bd9787229abd72eb374e3b97c7540 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Fri, 13 Nov 2026 17:00:14 -0700 Subject: [PATCH 071/131] feat(workspace): look inside a dataset A dataset with a product gains "Look inside" on its card and in its drawer. It opens to the product's records as a paged grid of 48 tiles, filtered by kind and split, with a viewer beside it for the selected record: the text; the image at its size; the sound with its waveform and the browser's player; a point cloud or a mesh drawn with a depth buffer, turned by dragging and zoomed by the wheel; an array as a slice with its axes on selects and sliders, the value under the pointer, the stacked-slice drawing of the mockup and its histogram. A Files switch browses the product a level at a time, archives and arrays included. Canvas 2D, no library; light and dark. The view is redrawn only when a reading finds something changed, in place, keeping page, selection and scroll. Open defect, recorded in spec-d1.md: about one run of the check in twelve, the main area's scroll goes back to its top once in the first second after a dataset is opened. The cause is not found yet. Not opened yet from the Files view: a text, point cloud or mesh that is not one of the product's records, since no operation reads those by address. Co-Authored-By: Claude Fable 5.2 --- app.py | 1 + .../definition-first-projects/spec-d1.md | 23 + static/project-workspace.html | 1 + static/project-workspace/adapter.js | 18 +- static/project-workspace/base.css | 62 ++ static/project-workspace/inside.js | 701 ++++++++++++++++++ static/project-workspace/tabs.js | 18 +- tests/browser_project_workspace_inside.cjs | 454 ++++++++++++ tests/project_inside_browser_fixture.py | 179 +++++ 9 files changed, 1454 insertions(+), 3 deletions(-) create mode 100644 static/project-workspace/inside.js create mode 100644 tests/browser_project_workspace_inside.cjs create mode 100644 tests/project_inside_browser_fixture.py diff --git a/app.py b/app.py index 838b063c..59f876e0 100644 --- a/app.py +++ b/app.py @@ -805,6 +805,7 @@ def _get(self): '/project-workspace/actions.js': ('project-workspace/actions.js', 'text/javascript'), '/project-workspace/editor.js': ('project-workspace/editor.js', 'text/javascript'), '/project-workspace/tabs.js': ('project-workspace/tabs.js', 'text/javascript'), + '/project-workspace/inside.js': ('project-workspace/inside.js', 'text/javascript'), '/project-workspace/app.js': ('project-workspace/app.js', 'text/javascript'), '/static/vendor/ubuntu-sans/UbuntuSans[wdth,wght].ttf': ('vendor/ubuntu-sans/UbuntuSans[wdth,wght].ttf', 'font/ttf'), '/static/vendor/ubuntu-sans/UbuntuSans-Italic[wdth,wght].ttf': ('vendor/ubuntu-sans/UbuntuSans-Italic[wdth,wght].ttf', 'font/ttf'), diff --git a/docs/plans/definition-first-projects/spec-d1.md b/docs/plans/definition-first-projects/spec-d1.md index e36f0a59..5cdbb1da 100644 --- a/docs/plans/definition-first-projects/spec-d1.md +++ b/docs/plans/definition-first-projects/spec-d1.md @@ -175,3 +175,26 @@ What differs from the text above, and what was found. - **Measured on the lab's largest product** (9.77 GB, 792 members), through the readers alone, no database: listing the archive 0.004 s; the arrays of one sample 0.004 s; a middle slice of its `features` 0.009 s; a summary of its 645,120 values 0.12 s. The disk's cache may have held the file. - **Tests:** `tests/test_tuldok_project_inside.py`, 24; project suite 610; agent interface 43 (4 skipped, as before). The catalog profile's digest is unchanged. - **Not verified:** a big-endian machine; a PLY whose lists are in an element other than its faces; a JPEG whose size is declared beyond its first megabyte; a product on a disk that is truly cold. A file of a finished run is read through `mmap`: if something truncated it while it was being read, the process would be killed. Tuldok never changes a finished run's output. + +### D1b, the page + +What differs from section 7, and why. + +- **The opened state is `#data/inside:`, not `#data/`.** `#data/` already opens the dataset's drawer beside the cards, and the existing checks rely on it (`browser_project_workspace_actions.cjs` edits a dataset from that drawer; `browser_project_workspace_still.cjs` counts it). `inside:` is a prefix of the selection like `edit:` and `plan:`. The opened view has no drawer. +- **"Look inside" sits under the card**, in a `.ds-item` that wraps the card's button (a button cannot hold a button), and in the drawer above Edit; it is drawn only when the dataset has a product with a run. A dataset with several products offers them in a select in the opened view's head, not on the card. +- **What redraws what.** A person's selection (a click, or the left and right arrows) sets the tiles' `aria-pressed` in place and replaces only the viewer; it is not in the address. A page, a filter, the Files switch and a level of the tree draw the whole view again, built off the page and put in place (spec-w4 R8). The arrows cross to the next or previous page at the ends of one. While the next record is read the viewer keeps the one on screen for 250 ms, then says "Reading…" (it is not on screen yet). A reading that changed something draws the opened view again in place (spec-w4 R3): `tabs.js` passes the drawer's `_again` mark to `LabInside.open`. +- **Files is browsed a level at a time**, with a line of links back up (Product / bundles / training-view.zip / samples), not as an expanding tree; a directory, an archive and an `.npy` or `.npz` open in place, an array or a file opens in the viewer. +- **What opens from the tree.** Arrays are read by their place (`array_slice` and `array_summary` take a path); images and sounds by the file route. A text, a point cloud or a mesh is opened through `record` when its address is a record's id (in a product read from its files it is), because no operation reads those kinds by address. A text, point cloud or mesh inside an archive, or one not among the records of a `records.jsonl` or a view, says so instead of opening: the server has no read for it. Section 7's "any file … opens in the same viewers" is therefore true of arrays, images and sounds only; the server was not changed. +- **Tiles.** An image tile reads its record to use the `url` the operation gives (two requests a tile: the record, the bytes); an array tile reads its record (an `.npz` needs `show`, which `records` gives only from a list) and one `array_slice` of `most` 48. Tiles are filled by an `IntersectionObserver` on the main area, 48 at most a page. A tile's id is cut at its start when long, so the file's name shows; the whole id is its title and label. +- **The slice viewer is written in `inside.js`; catalog mode's `scientific-inspector.js` is not used.** That module is built around the catalog's field-sequence manifests (frames, fields named by the manifest, x, y and z axes, nested arrays of values) and writes its controls with `innerHTML`; an adapter would have had to make those manifests up from an `.npy` header. Here the slice is a heat map in a canvas, two axes chosen by selects when there are three or more, a slider for every other axis, the range, the value and full index under the pointer, and the summary's histogram on request. +- **The stacked-slice drawing** (the mockup's `drawVolume`) reads up to ten positions of the first axis not drawn, at `most` 24 each, coloured on one range across them, the slider's slice outlined. A one-dimensional array is drawn as a line, not as a single row of cells. +- **Point clouds and meshes** are drawn into an `ImageData` with a depth buffer (a mesh's triangles rasterised, flat shaded from a fixed light), z up; colours by height use the diverging ramp's two ends. Dragging turns, the wheel zooms, the arrow keys and + and − do the same on the focused canvas, "Reset view" puts it back. A frame is drawn on `requestAnimationFrame` only after one of these; canvases are drawn again when their box changes size or the theme changes, and at no other time. +- **Colours.** Five tokens were added to `base.css` in both themes, `--ramp-lo`, `--ramp-hi` (sequential), `--ramp-neg`, `--ramp-mid`, `--ramp-pos` (diverging about zero, used when a range has both signs). +- **The answers.** `adapter.js` has the five reads and the file route's address as `P.product`; their answers are kept like any other and forgotten when a reading finds a change. The slice drawn as a slider moves is asked for each time and not kept. +- **Files beyond section 8's list:** `static/project-workspace.html` gains the ` + diff --git a/static/project-workspace/adapter.js b/static/project-workspace/adapter.js index 36b73d07..b85ba37c 100644 --- a/static/project-workspace/adapter.js +++ b/static/project-workspace/adapter.js @@ -103,6 +103,22 @@ window.TuldokProject = (() => { // What the page watches: asked again on every reading ('map' on some, app.js), kept across a change. const WATCHED = ['summary', 'status', 'build_requests', 'environments', 'runs', 'map']; + // ---- Looking inside a product (spec-d1.md, inside.js) ----------------------------- + // The five reads of a finished run's product. Their answers are kept like any other until a reading + // finds something changed (they are not watched, so forgetBut() drops them); the slice the viewer draws + // as a slider moves is asked for each time and not kept, so the kept answers do not grow with every move. + const defined = o => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined && v !== null)); + const product = { + records: (run, { offset, limit, kind, split } = {}) => read('records', defined({ run, offset, limit, kind, split })), + record: (run, id) => read('record', { run, id }), + inside: (run, { path, offset, limit } = {}) => read('inside', defined({ run, path: path || null, offset, limit })), + /** A slice; kept unless fresh (the viewer's slider). */ + slice: (run, { path, array, axes, index, most }, fresh = false) => (fresh ? call : read)('array_slice', defined({ run, path, array, axes, index, most })), + summary: (run, { path, array, bins }) => read('array_summary', defined({ run, path, array, bins })), + /** The address of an image's or a sound's bytes (GET /api/project/file), as the record operation gives it. */ + fileUrl: (run, path) => '/api/project/file?run=' + encodeURIComponent(run) + '&path=' + encodeURIComponent(path) + }; + // ---- The map ------------------------------------------------------------ /** * What the Map tab and the drawer read, from the answer of `map`: @@ -250,5 +266,5 @@ window.TuldokProject = (() => { return out; } - return { KINDS, UNSET, WATCHED, kindLabel, stateWord, call, read, again, forget, forgetBut, forgetAll, map, setDrafts, trackName, better, units, standing, needs, titleOf, day }; + return { KINDS, UNSET, WATCHED, kindLabel, stateWord, call, read, again, forget, forgetBut, forgetAll, map, setDrafts, trackName, better, units, standing, needs, titleOf, day, product }; })(); diff --git a/static/project-workspace/base.css b/static/project-workspace/base.css index 3b038e6a..2eef2472 100644 --- a/static/project-workspace/base.css +++ b/static/project-workspace/base.css @@ -33,6 +33,9 @@ --k-component: #8a94a3; --mark: #2e6fcf; --grid: #e6eaef; + /* The colour ramps of the viewers of a product (inside.js): sequential low to high, diverging about zero. */ + --ramp-lo: #e4ebf5; --ramp-hi: #1c5cab; + --ramp-neg: #2e6fcf; --ramp-mid: #efeeeb; --ramp-pos: #d2652f; --font: "Ubuntu Sans", "Noto Sans", system-ui, sans-serif; --mono: "Ubuntu Sans Mono", "Ubuntu Mono", ui-monospace, monospace; --radius: 4px; @@ -48,6 +51,7 @@ --good-wash: #15302a; --warn-wash: #342a16; --serious-wash: #3a2320; --k-training-policy: #22a07f; --k-architecture: #4f8ae0; --k-refinement: #d96f3c; --k-component: #7c8694; --mark: #4f8ae0; --grid: #222a33; + --ramp-lo: #2a3542; --ramp-hi: #8db4f5; --ramp-neg: #4f8ae0; --ramp-mid: #3a3a37; --ramp-pos: #e07a4a; } } :root[data-theme="dark"] { @@ -60,6 +64,7 @@ --good-wash: #15302a; --warn-wash: #342a16; --serious-wash: #3a2320; --k-training-policy: #22a07f; --k-architecture: #4f8ae0; --k-refinement: #d96f3c; --k-component: #7c8694; --mark: #4f8ae0; --grid: #222a33; + --ramp-lo: #2a3542; --ramp-hi: #8db4f5; --ramp-neg: #4f8ae0; --ramp-mid: #3a3a37; --ramp-pos: #e07a4a; } * { box-sizing: border-box; } @@ -594,3 +599,60 @@ textarea.code { width: 100%; min-width: 0; font: 12px/1.5 var(--mono); white-spa .row.def > .title { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; } div.row.def { cursor: default; } @media (max-width: 900px) { .row.def { grid-template-columns: minmax(0, 1fr) minmax(0, 1fr) 110px; } .row.def .umark { display: none; } } + +/* ---- Looking inside a product (inside.js, spec-d1.md section 7); from the mockup's Data tab. ---- */ +.ds-item { display: grid; align-content: start; gap: 6px; min-width: 0; } +.ds-foot { display: flex; gap: 8px; } +.ds-back { margin-bottom: 10px; } +.ds-head { display: flex; flex-wrap: wrap; align-items: center; gap: 8px 16px; margin-bottom: 12px; } +.ds-head h2 { font-size: 17px; overflow-wrap: anywhere; } +.ds-head .meta { display: flex; flex-wrap: wrap; gap: 4px 12px; align-items: center; font-size: 12.5px; color: var(--ink-2); } +.ds-head select { max-width: 360px; } +.inside-problems { margin: -4px 0 12px; } +.ds-body { display: grid; grid-template-columns: minmax(0, 1fr) minmax(360px, 44%); gap: 20px; align-items: start; } +@media (max-width: 1100px) { .ds-body { grid-template-columns: minmax(0, 1fr); } } +.rec-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(96px, 1fr)); gap: 8px; } +.rec { display: grid; grid-template-rows: auto auto; padding: 0; border: 1px solid var(--line); border-radius: var(--radius); background: var(--surface); overflow: hidden; text-align: left; color: inherit; min-width: 0; } +.rec:hover { border-color: var(--line-strong); } +.rec[aria-pressed="true"] { border-color: var(--accent); box-shadow: inset 0 0 0 1px var(--accent); } +.rec .th { display: grid; place-items: center; aspect-ratio: 1; background: var(--surface-2); color: var(--ink-3); overflow: hidden; border-bottom: 1px solid var(--line); } +.rec .th > * { grid-area: 1 / 1; } +.rec .th svg.glyph { width: 30px; height: 30px; } +.rec .th img { width: 100%; height: 100%; object-fit: contain; } +.rec .th canvas { display: block; width: 100%; height: 100%; } +.rec .th .pre { align-self: start; justify-self: stretch; margin: 6px 7px; font: 10.5px/1.35 var(--mono); color: var(--ink-2); white-space: pre-wrap; overflow-wrap: anywhere; overflow: hidden; text-align: left; display: -webkit-box; -webkit-box-orient: vertical; -webkit-line-clamp: 6; } +.rec .id { display: block; font: 11px var(--mono); color: var(--ink-2); padding: 3px 6px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; direction: rtl; text-align: left; } +.rec.refused .th { color: var(--serious); } +.inside-list .sect { margin-bottom: 8px; } +.crumbs { display: flex; flex-wrap: wrap; gap: 2px 6px; align-items: baseline; font-size: 13px; margin: 0 0 8px; overflow-wrap: anywhere; } +.crumbs .sep { color: var(--ink-3); } +.crumbs .here { font-weight: 500; } +.crumbs .linkish { font: inherit; color: var(--accent); background: none; border: 0; padding: 0; cursor: pointer; } +.crumbs .linkish:hover { text-decoration: underline; } +.row.tree-entry { grid-template-columns: 18px minmax(0, 1fr) auto; } +.row.tree-entry svg.glyph { width: 18px; height: 18px; color: var(--ink-3); } +.viewer { position: sticky; top: 0; border: 1px solid var(--line); border-radius: var(--radius); background: var(--surface); padding: 12px; display: grid; gap: 10px; min-width: 0; max-height: calc(100vh - 140px); overflow: auto; } +@media (max-width: 1100px) { .viewer { position: static; max-height: none; } } +.iv { display: grid; gap: 10px; min-width: 0; } +.iv-head { display: grid; gap: 2px; min-width: 0; } +.iv-head h3 { font-size: 13px; font-weight: 600; overflow-wrap: anywhere; } +.iv-text { margin: 0; padding: 10px; background: var(--surface-2); border-radius: var(--radius); font: 12.5px/1.5 var(--mono); color: var(--ink); white-space: pre-wrap; overflow-wrap: anywhere; max-height: 52vh; overflow: auto; } +.iv-imgbox { overflow: auto; max-height: 60vh; background: var(--surface-2); border-radius: var(--radius); } +.iv-img { display: block; width: 100%; padding: 0; border: 0; background: none; cursor: zoom-in; } +.iv-img img { display: block; width: 100%; max-height: 56vh; object-fit: contain; image-rendering: pixelated; } +.iv-img.actual { width: auto; cursor: zoom-out; } +.iv-img.actual img { width: auto; max-height: none; max-width: none; } +.iv canvas { display: block; width: 100%; background: var(--surface-2); border-radius: var(--radius); } +.iv canvas.iv-3d { cursor: grab; touch-action: none; } +.iv canvas.iv-3d.dragging { cursor: grabbing; } +.iv canvas.iv-heat { cursor: crosshair; } +.iv audio { width: 100%; } +.iv-ctl { display: flex; flex-wrap: wrap; gap: 8px 14px; align-items: center; font-size: 12.5px; color: var(--ink-2); } +.iv-field { display: inline-flex; gap: 6px; align-items: center; min-width: 0; } +.iv-field select { max-width: 240px; } +.iv-slider input[type="range"] { width: 140px; } +.iv-array { display: grid; gap: 10px; min-width: 0; } +.iv-probe { font-variant-numeric: tabular-nums; color: var(--ink); min-height: 1.5em; overflow-wrap: anywhere; } +.iv-ends { display: flex; justify-content: space-between; margin-top: 2px; } +.iv-facts { font-size: 12.5px; } +.iv-hist { display: grid; gap: 6px; } diff --git a/static/project-workspace/inside.js b/static/project-workspace/inside.js new file mode 100644 index 00000000..42babd73 --- /dev/null +++ b/static/project-workspace/inside.js @@ -0,0 +1,701 @@ +'use strict'; +// Looking inside a product (docs/plans/definition-first-projects/spec-d1.md section 7): the Data tab's +// second state, one dataset opened (#data/inside:), and its viewers. The records are paged 48 at +// a time as tiles beside the selected record's viewer (below it under 1,100 px); a "Files" switch browses +// the product as a tree (directories, archives and the arrays of an .npy or .npz) from which a file or an +// array opens in the same viewers. Everything is read through window.TuldokProject's five operations +// (records, record, inside, array_slice, array_summary) and the file route for an image's or a sound's +// bytes; nothing is written. Drawing is Canvas 2D with the tokens of base.css, drawn again when the theme +// changes or a canvas's box changes size, and on requestAnimationFrame only while something changes. +// +// Updating in place (spec-w4): the view is built off the page and put in place in one step. A reading that +// changed nothing never reaches here (app.js draws nothing); one that changed something forgets these +// answers, and open() is called with again set: the view is read and drawn again in place, keeping the +// page, the filters, the selection, the viewer's settings and the scroll. A person's selection changes the +// tiles' pressed state and the viewer only; a page, a filter or the Files switch draws the view again. +window.LabInside = (() => { + const P = window.TuldokProject, S = window.LabScreens, C = window.LabCharts, h = C.h; + const { sect, putInPlace, bytes, time, failure } = S.parts; + const PER_PAGE = 48; // tiles on a page (spec-d1 section 7) + const TILE_MOST = 48; // rows and columns of an array tile's slice + const VIEW_MOST = 256; // rows and columns of the viewer's slice + const STACK_MOST = 24, STACK_SLICES = 10; // the stacked-slice drawing: slices read, and their size + const MESH_AS_POINTS = 60000; // above this many triangles a mesh is drawn as its vertices + const TREE_LIMIT = 200; // entries of the Files tree read at a time + const KINDS = ['text', 'image', 'audio', 'pointcloud', 'mesh', 'array', 'file']; + const WORD = { text: 'Text', image: 'Image', audio: 'Sound', pointcloud: 'Point cloud', mesh: 'Mesh', array: 'Array', file: 'File' }; + const count = (n, one, many) => n.toLocaleString('en-GB') + ' ' + (n === 1 ? one : many || one + 's'); + const button = (cls, text, onClick) => { const b = h('button', cls, text); b.type = 'button'; if (onClick) b.addEventListener('click', onClick); return b; }; + const fmt = v => v == null ? '—' : C.fmtSci(v); + + // ---- Decoding ------------------------------------------------------------------------------------------- + function raw(b64) { const s = atob(b64 || ''), u = new Uint8Array(s.length); for (let i = 0; i < s.length; i++) u[i] = s.charCodeAt(i); return u; } + /** Little-endian 32-bit floats from base64, whatever the machine's byte order. */ + function floats(b64) { const u = raw(b64), d = new DataView(u.buffer), out = new Float32Array(u.length >> 2); for (let i = 0; i < out.length; i++) out[i] = d.getFloat32(i * 4, true); return out; } + function uints(b64) { const u = raw(b64), d = new DataView(u.buffer), out = new Uint32Array(u.length >> 2); for (let i = 0; i < out.length; i++) out[i] = d.getUint32(i * 4, true); return out; } + + // ---- Colours, from the tokens of base.css ----------------------------------------------------------------- + function token(name) { + const v = getComputedStyle(document.documentElement).getPropertyValue(name).trim(); + const m = /^#([0-9a-f]{6})$/i.exec(v); if (m) { const n = parseInt(m[1], 16); return [n >> 16, (n >> 8) & 255, n & 255]; } + return [128, 128, 128]; + } + const mix = (a, b, t) => [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t, a[2] + (b[2] - a[2]) * t]; + /** value -> [r, g, b]: diverging about zero when the range has both signs, else sequential from low to high. */ + function ramp(min, max) { + const lo = token('--ramp-lo'), hi = token('--ramp-hi'), neg = token('--ramp-neg'), mid = token('--ramp-mid'), pos = token('--ramp-pos'); + if (min < 0 && max > 0) { const m = Math.max(-min, max); return v => v < 0 ? mix(mid, neg, Math.min(1, -v / m)) : mix(mid, pos, Math.min(1, v / m)); } + const span = max - min || 1; return v => mix(lo, hi, Math.min(1, Math.max(0, (v - min) / span))); + } + + // ---- Canvases: sized to their box, drawn again on a new size or theme ------------------------------------- + const painters = new Map(); // canvas -> draw() + const sizes = new ResizeObserver(entries => { for (const e of entries) { const draw = painters.get(e.target); if (draw && e.target.isConnected) { e.target._shown = true; draw(); } } }); + /** Registers draw(canvas) for a canvas: it is called when the canvas's box gets a size, changes size, or the theme changes. */ + function paints(canvas, draw) { prune(); painters.set(canvas, draw); sizes.observe(canvas); } + /** Forgets the canvases that were on the page and are no more (a viewer replaced, the view left), and what they drew from. */ + function prune() { for (const canvas of painters.keys()) if (canvas._shown && !canvas.isConnected) { painters.delete(canvas); sizes.unobserve(canvas); } } + function retheme() { prune(); for (const [canvas, draw] of painters) if (canvas.isConnected) draw(); } + new MutationObserver(retheme).observe(document.documentElement, { attributes: true, attributeFilter: ['data-theme'] }); + matchMedia('(prefers-color-scheme: dark)').addEventListener('change', retheme); + /** Sets a canvas's pixel size for its CSS width and a height (CSS pixels); returns [width, height] in device pixels or null when it has no width yet. */ + function fit(canvas, cssHeight) { + const w = canvas.clientWidth; if (!w) return null; + const dpr = window.devicePixelRatio || 1, W = Math.max(1, Math.round(w * dpr)), H = Math.max(1, Math.round(cssHeight * dpr)); + if (canvas.style.height !== cssHeight + 'px') canvas.style.height = cssHeight + 'px'; + if (canvas.width !== W) canvas.width = W; if (canvas.height !== H) canvas.height = H; + return [W, H]; + } + /** A heat map of rows x columns values into ctx's rectangle (x, y, w, h), unsmoothed; non-finite values left clear. */ + function heat(ctx, values, rows, cols, colour, x, y, w, hgt) { + const off = document.createElement('canvas'); off.width = cols; off.height = rows; + const o = off.getContext('2d'), img = o.createImageData(cols, rows); + for (let i = 0; i < rows * cols; i++) { const v = values[i]; if (!Number.isFinite(v)) continue; const c = colour(v); img.data[i * 4] = c[0]; img.data[i * 4 + 1] = c[1]; img.data[i * 4 + 2] = c[2]; img.data[i * 4 + 3] = 255; } + o.putImageData(img, 0, 0); ctx.imageSmoothingEnabled = false; ctx.drawImage(off, x, y, w, hgt); + } + /** The rectangle a rows x columns grid takes in W x H, keeping square cells. */ + function contain(rows, cols, W, H) { const s = Math.min(W / cols, H / rows), w = cols * s, hh = rows * s; return [(W - w) / 2, (H - hh) / 2, w, hh]; } + + // ---- Glyphs --------------------------------------------------------------------------------------------- + const GLYPHS = { + text: 'M5 6h14M5 10h14M5 14h10M5 18h12', + image: 'M4 5h16v14H4zM4 16l5-5 4 4 3-3 4 4M15 9.5a1 1 0 1 0 0 .1', + audio: 'M3 12h2M7 8v8M11 4v16M15 7v10M19 10v4', + pointcloud: 'M6 7h.01M10 5h.01M15 6h.01M18 10h.01M8 11h.01M13 10h.01M5 15h.01M11 15h.01M16 14h.01M9 19h.01M14 18h.01M19 17h.01', + mesh: 'M12 3 3 19h18zM12 3l-3 9 12 7M9 12 3 19', + array: 'M4 4h16v16H4zM4 9.3h16M4 14.6h16M9.3 4v16M14.6 4v16', + file: 'M6 3h8l4 4v14H6zM14 3v4h4', + directory: 'M3 6h6l2 2h10v11H3z', + archive: 'M5 4h14v16H5zM11 4v2h2v2h-2v2h2v2h-2v2', + refused: 'M12 3 2 21h20zM12 10v5M12 18h.01' + }; + function glyph(name) { + const ns = 'http://www.w3.org/2000/svg', s = document.createElementNS(ns, 'svg'), p = document.createElementNS(ns, 'path'); + s.setAttribute('viewBox', '0 0 24 24'); s.setAttribute('aria-hidden', 'true'); s.setAttribute('class', 'glyph ' + name); + p.setAttribute('d', GLYPHS[name] || GLYPHS.file); p.setAttribute('fill', 'none'); p.setAttribute('stroke', 'currentColor'); p.setAttribute('stroke-width', name === 'pointcloud' ? '2.6' : '1.6'); p.setAttribute('stroke-linecap', 'round'); p.setAttribute('stroke-linejoin', 'round'); + s.appendChild(p); return s; + } + + // ---- What is kept per dataset, across drawings --------------------------------------------------------------- + const views = new Map(); // reference -> the person's place in it + const viewOf = ref => { if (!views.has(ref)) views.set(ref, { run: null, page: 0, kind: null, split: null, sel: null, mode: 'records', path: '', treeOffset: 0, treeTarget: null, viewers: new Map() }); return views.get(ref); }; + const settingsOf = (v, key, make) => { if (!v.viewers.has(key)) v.viewers.set(key, make()); return v.viewers.get(key); }; + let current = null; // { ref, main, act, root, io, vturn } + const R = P.product; // the five reads and the file route (adapter.js) + + /** + * Shows the dataset ref opened in main. What is on screen for it stays unless again (a reading changed + * something): then it is read and drawn again in place. "Reading…" only when it is not on screen yet. + */ + function open(main, ref, act, again) { + const shown = !!(current && current.ref === ref && current.root && main.contains(current.root)); + if (shown && !again) { current.act = act; return; } + if (!current || current.ref !== ref) { leave(); current = { ref, main, act, root: null, io: null, vturn: 0, focusSel: false }; } + current.act = act; + draw(current, !shown); + } + /** The dataset view is no longer shown: its tile observer stops. */ + function leave() { if (current && current.io) current.io.disconnect(); current = null; } + /** Whether the page still shows this dataset opened (another tab may have been drawn meanwhile). */ + const here = c => current === c && decodeURIComponent(location.hash.slice(1)) === 'data/inside:' + c.ref; + + /** Reads what the view shows: the dataset, its products, a page of records or a level of the tree, and the viewer's subject. */ + async function load(c, v) { + const [defs, prods] = await Promise.all([P.read('definitions', { kind: 'dataset' }), P.read('products', { reference: c.ref })]); + const def = defs.definitions.find(d => d.reference === c.ref) || { reference: c.ref, title: c.ref }; + const products = prods.products.filter(p => p.run_id); + if (!products.length) return { def, products }; + const product = products.find(p => p.run_id === v.run) || products[0]; v.run = product.run_id; + const args = { offset: v.page * PER_PAGE, limit: PER_PAGE, kind: v.kind, split: v.split }; + let page = await R.records(v.run, args); + if (!page.records.length && v.page > 0 && page.total) { v.page = Math.floor((page.total - 1) / PER_PAGE); args.offset = v.page * PER_PAGE; page = await R.records(v.run, args); } + let tree = null; + if (v.mode === 'files') tree = await R.inside(v.run, { path: v.path, offset: v.treeOffset, limit: TREE_LIMIT }).catch(error => ({ error })); + if (v.mode === 'records' && !page.records.some(r => r.id === v.sel)) v.sel = page.records.length ? page.records[v.selAt === -1 ? page.records.length - 1 : 0].id : null; + v.selAt = 0; + const target = v.mode === 'files' ? v.treeTarget : v.sel ? { record: v.sel } : null; + const viewer = target ? await viewerFor(c, v, target) : null; + return { def, products, product, page, tree, viewer }; + } + + /** Draws the whole view (first: not on screen yet), built off the page and put in place in one step. */ + async function draw(c, first) { + const main = c.main, mine = main._paint = (main._paint || 0) + 1, v = viewOf(c.ref); + if (first) { main.textContent = ''; main.appendChild(h('p', 'note', 'Reading…')); main.scrollTop = 0; main.scrollLeft = 0; } + main._painted = 'data/inside:' + c.ref; // so that the cards, drawn again later, start from "Reading…" (tabs.js's paint) + main.setAttribute('aria-busy', 'true'); + let got; try { got = await load(c, v); } catch (error) { got = { error }; } + if (main._paint === mine) main.removeAttribute('aria-busy'); + if (main._paint !== mine || !here(c)) return; + const root = h('div', 'inside'); + try { build(c, v, got, root); } catch (error) { root.textContent = ''; failure(root, error); console.error(error); } + if (c.io) c.io.disconnect(); + putInPlace(main, root); + c.root = root; + if (c.focusSel) { c.focusSel = false; const t = root.querySelector('.rec[aria-pressed="true"]'); if (t) t.focus(); } + watchTiles(c, root); + } + + function build(c, v, got, root) { + const back = button('btn sm ghost ds-back', '← All datasets', () => c.act.go('data')); back.dataset.key = 'inside-back'; root.appendChild(back); + if (got.error) { root.appendChild(window.LabActions.refusal(got.error)); return; } + const { def, products, product, page, tree } = got; + const head = h('div', 'ds-head'); head.appendChild(h('h2', null, def.title)); + const meta = h('div', 'meta'); + if (product) { + meta.appendChild(h('span', 'mono', 'run ' + product.run_id.slice(0, 8))); + meta.appendChild(h('span', null, (product.adopted ? 'adopted ' : 'built ') + time(product.finished_at))); + meta.appendChild(h('span', null, bytes(product.bytes))); + if (page) meta.appendChild(h('span', null, count(Object.values(page.kinds).reduce((a, b) => a + b, 0), 'record') + ' · ' + ({ 'records.jsonl': 'from records.jsonl', view: 'from the dataset\'s view', files: 'one per file' }[page.source] || page.source))); + } + head.appendChild(meta); + if (products.length > 1) { + const s = h('select'); s.setAttribute('aria-label', 'Product'); s.dataset.key = 'inside-product'; + for (const p of products) { const o = h('option', null, (p.subject ? p.subject + ' · ' : '') + 'run ' + p.run_id.slice(0, 8) + ' · ' + time(p.finished_at)); o.value = p.run_id; o.selected = p.run_id === v.run; s.appendChild(o); } + s.addEventListener('change', () => { Object.assign(v, { run: s.value, page: 0, sel: null, path: '', treeOffset: 0, treeTarget: null }); draw(c, false); }); + head.appendChild(s); + } + root.appendChild(head); + if (!product) { root.appendChild(h('p', 'empty', 'This dataset has no product on this machine: there is nothing to look inside.')); return; } + if (page.problems && page.problems.length) { + const p = h('p', 'small warnline inside-problems', page.problems.slice(0, 3).map(x => (x.line != null ? 'Line ' + x.line + ': ' : '') + x.message).join(' ') + (page.problems.length > 3 ? ' (' + page.problems.length + ' problems in all)' : '')); + root.appendChild(p); + } + // The Files switch, the kinds and the splits as filters. + const bar = h('div', 'filters'); + const seg = h('div', 'seg'); seg.setAttribute('role', 'group'); seg.setAttribute('aria-label', 'Show'); + for (const [mode, label] of [['records', 'Records'], ['files', 'Files']]) { const b = button(null, label, () => { if (v.mode !== mode) { v.mode = mode; draw(c, false); } }); b.setAttribute('aria-pressed', String(v.mode === mode)); b.dataset.key = 'inside-mode-' + mode; seg.appendChild(b); } + bar.appendChild(seg); + if (v.mode === 'records') { + const all = Object.values(page.kinds).reduce((a, b) => a + b, 0); + bar.appendChild(chips('Kind', [[null, 'All', all]].concat(KINDS.filter(k => page.kinds[k]).map(k => [k, WORD[k], page.kinds[k]])), v.kind, k => { v.kind = k; v.page = 0; v.sel = null; draw(c, false); }, 'kind')); + const splits = Object.entries(page.splits || {}); + if (splits.length) bar.appendChild(chips('Split', [[null, 'All', null]].concat(splits.map(([s, n]) => [s, s, n])), v.split, s => { v.split = s; v.page = 0; v.sel = null; draw(c, false); }, 'split')); + } + root.appendChild(bar); + const body = h('div', 'ds-body'); + const left = h('div', 'inside-list'); + if (v.mode === 'records') records(c, v, page, left); else files(c, v, tree, left); + body.appendChild(left); + const panel = h('section', 'viewer'); panel.setAttribute('aria-label', 'Viewer'); + panel.appendChild(got.viewer || h('p', 'empty', v.mode === 'files' ? 'Choose a file or an array in the tree.' : 'Choose a record.')); + body.appendChild(panel); root.appendChild(body); + } + function chips(label, items, value, pick, key) { + const g = h('div', 'grp'); g.setAttribute('role', 'group'); g.setAttribute('aria-label', label); + for (const [id, text, n] of items) { const b = button('btn sm', text + (n != null ? ' · ' + n.toLocaleString('en-GB') : ''), () => { if (value !== id) pick(id); }); b.setAttribute('aria-pressed', String(value === id)); b.dataset.key = 'inside-' + key + '-' + (id || 'all'); g.appendChild(b); } + return g; + } + + // ---- The records: a page of tiles ------------------------------------------------------------------------ + function records(c, v, page, left) { + const first = v.page * PER_PAGE + 1, last = v.page * PER_PAGE + page.records.length; + left.appendChild(sect('Records', page.total ? first.toLocaleString('en-GB') + '–' + last.toLocaleString('en-GB') + ' of ' + page.total.toLocaleString('en-GB') : '0')); + if (!page.total) { left.appendChild(h('p', 'empty', v.kind || v.split ? 'No record matches the filters.' : 'This product holds no records.')); return; } + const grid = h('div', 'rec-grid'); grid.setAttribute('role', 'group'); grid.setAttribute('aria-label', 'Records ' + first + ' to ' + last + ' of ' + page.total + '; the left and right arrows move the selection'); + for (const r of page.records) grid.appendChild(tile(c, v, r)); + left.appendChild(grid); + const pages = Math.ceil(page.total / PER_PAGE); + if (pages > 1) { + const pg = h('div', 'pager'); + const pb = button('btn sm', 'Previous', () => turnPage(c, v, v.page - 1, 0)); pb.disabled = v.page === 0; pb.dataset.key = 'inside-prev'; + const nb = button('btn sm', 'Next', () => turnPage(c, v, v.page + 1, 0)); nb.disabled = v.page + 1 >= pages; nb.dataset.key = 'inside-next'; + pg.appendChild(pb); pg.appendChild(nb); pg.appendChild(h('span', null, 'page ' + (v.page + 1) + ' of ' + pages)); left.appendChild(pg); + } + left._records = page.records; left._pages = pages; + } + function turnPage(c, v, n, at) { v.page = n; v.sel = null; v.selAt = at; draw(c, false); } + /** One record as a tile: its id always; text's first characters; an image or a small array slice once the tile is seen; else the kind's glyph. */ + function tile(c, v, r) { + const b = h('button', 'rec ' + r.kind); b.type = 'button'; b.dataset.id = r.id; b.dataset.key = 'rec-' + r.id; b.dataset.kind = r.kind; + b.setAttribute('aria-pressed', String(r.id === v.sel)); b.setAttribute('aria-label', WORD[r.kind] + ' ' + r.id); b.title = r.id; + const th = h('span', 'th'); + if (r.kind === 'text' && r.preview != null) th.appendChild(h('span', 'pre', r.preview.slice(0, 160))); + else th.appendChild(glyph(r.kind)); + if (r.kind === 'image' || r.kind === 'array') b.dataset.lazy = '1'; + const label = h('span', 'id'); label.appendChild(h('bdi', null, r.id)); b.appendChild(th); b.appendChild(label); // cut at its start when long: the name shows + b.addEventListener('click', () => select(c, v, r.id)); + return b; + } + /** Fills a tile's picture when it comes into view: the image by its url, an array by a small slice of the array shown first. */ + function watchTiles(c, root) { + const lazy = root.querySelectorAll('.rec[data-lazy]'); if (!lazy.length) return; + c.io = new IntersectionObserver(entries => { for (const e of entries) if (e.isIntersecting) { c.io.unobserve(e.target); fillTile(c, e.target); } }, { root: c.main, rootMargin: '120px 0px' }); + for (const t of lazy) c.io.observe(t); + } + async function fillTile(c, t) { + const v = viewOf(c.ref), run = v.run, id = t.dataset.id, th = t.querySelector('.th'), kind = t.dataset.kind; + const live = () => t.isConnected && current === c && viewOf(c.ref).run === run; + try { + const rec = await R.record(run, id); if (!live()) return; + if (kind === 'image') { + const img = h('img'); img.alt = ''; img.decoding = 'async'; img.src = rec.record.url; + await new Promise(resolve => { img.onload = img.onerror = resolve; }); if (!live()) return; + if (!img.naturalWidth) throw Error('The image could not be decoded.'); + th.replaceChildren(img); + } else { + const arrays = rec.content.arrays || [], name = rec.content.show, a = arrays.find(x => x.array === name) || arrays[0]; + if (!a) throw Error('No array.'); + const s = await R.slice(run, { path: rec.record.path, array: a.array, most: TILE_MOST }); if (!live()) return; + const cv = h('canvas'); cv.setAttribute('aria-hidden', 'true'); + const values = floats(s.values_f32); + paints(cv, () => { const size = fit(cv, cv.clientWidth); if (!size) return; const ctx = cv.getContext('2d'); ctx.clearRect(0, 0, size[0], size[1]); if (s.rows === 1 && s.columns > 1) line(ctx, values, s.min, s.max, 0, 0, size[0], size[1], 2); else { const [x, y, w, hh] = contain(s.rows, s.columns, size[0], size[1]); heat(ctx, values, s.rows, s.columns, ramp(s.min, s.max), x, y, w, hh); } }); + th.replaceChildren(cv); + } + } catch (error) { + if (!live()) return; + th.replaceChildren(glyph('refused')); t.title = id + ': ' + (error.message || error); t.classList.add('refused'); + } + } + /** Selects a record: the tiles' pressed state is set in place and the viewer replaced once its new content is read. */ + async function select(c, v, id) { + if (!c.root) return; + v.sel = id; + for (const t of c.root.querySelectorAll('.rec')) { const on = String(t.dataset.id === id); if (t.getAttribute('aria-pressed') !== on) t.setAttribute('aria-pressed', on); } + await showIn(c, v, { record: id }); + } + async function showIn(c, v, target) { + const panel = c.root && c.root.querySelector('.viewer'); if (!panel) return; + const mine = ++c.vturn; + panel.setAttribute('aria-busy', 'true'); + const slow = setTimeout(() => { if (c.vturn === mine) panel.replaceChildren(h('p', 'note', 'Reading…')); }, 250); + const el = await viewerFor(c, v, target); + clearTimeout(slow); + if (c.vturn !== mine || !panel.isConnected) return; + panel.removeAttribute('aria-busy'); + putInPlace(panel, el); + } + /** Left and right arrows move the selection in the grid, across pages, when the focus is not in a field or a viewer that turns. */ + function onKey(e) { + if (e.defaultPrevented || e.altKey || e.ctrlKey || e.metaKey || (e.key !== 'ArrowLeft' && e.key !== 'ArrowRight')) return; + const c = current; if (!c || !c.root || !c.root.isConnected) return; + const v = viewOf(c.ref); if (v.mode !== 'records') return; + const t = e.target; if (t && t.closest && (t.closest('input, select, textarea, [contenteditable], audio, .turns') )) return; + const list = c.root.querySelector('.inside-list'), recs = list && list._records; if (!recs || !recs.length) return; + e.preventDefault(); + const i = recs.findIndex(r => r.id === v.sel), d = e.key === 'ArrowRight' ? 1 : -1, n = i + d; + const onTile = !!(t && t.classList && t.classList.contains('rec')); + if (n >= 0 && n < recs.length) { select(c, v, recs[n].id); if (onTile) { const next = c.root.querySelector('.rec[data-id="' + CSS.escape(recs[n].id) + '"]'); if (next) next.focus(); } return; } + c.focusSel = onTile; + if (n >= recs.length && v.page + 1 < list._pages) turnPage(c, v, v.page + 1, 0); + else if (n < 0 && v.page > 0) turnPage(c, v, v.page - 1, -1); + else c.focusSel = false; + } + window.addEventListener('keydown', onKey); + + // ---- Files: the product as a tree ------------------------------------------------------------------------ + function files(c, v, tree, left) { + // The way down, each step a link back up. + const crumbs = h('nav', 'crumbs'); crumbs.setAttribute('aria-label', 'Where in the product'); + const parts = v.path ? v.path.split(/(?<=!)|\//).filter(Boolean) : []; + const steps = [['', 'Product']]; let at = ''; + for (const p of parts) { at = at ? (at.endsWith('!') ? at + p : at + '/' + p) : p; steps.push([at.replace(/!$/, ''), p.replace(/!$/, '')]); } + steps.forEach(([path, name], i) => { + if (i) crumbs.appendChild(h('span', 'sep', '/')); + if (i === steps.length - 1) { const s = h('span', 'here', name); s.setAttribute('aria-current', 'location'); crumbs.appendChild(s); } + else { const b = button('linkish', name, () => go(c, v, path)); b.dataset.key = 'crumb-' + path; crumbs.appendChild(b); } + }); + left.appendChild(sect('Files', tree && !tree.error ? count(tree.total, 'entry', 'entries') : '')); + left.appendChild(crumbs); + if (!tree) return; + if (tree.error) { left.appendChild(window.LabActions.refusal(tree.error)); return; } + if (!tree.entries.length) { left.appendChild(h('p', 'empty', 'Nothing here.')); return; } + const ul = h('ul', 'rows tree-rows'); + for (const e of tree.entries) { + const li = h('li'), into = e.type === 'directory' || e.type === 'archive'; + const key = e.type === 'array' ? e.path + '#' + e.array : e.path; + const b = button('row tree-entry'); b.dataset.key = 'entry-' + key; b.dataset.path = e.path; b.dataset.type = e.type; if (e.array) b.dataset.array = e.array; + const t = v.treeTarget; if (!into) b.setAttribute('aria-pressed', String(!!t && t.path === e.path && (t.array || null) === (e.array || null))); + b.appendChild(glyph(e.type === 'directory' ? 'directory' : e.type === 'archive' ? 'archive' : e.kind || 'file')); + const name = h('span'); name.appendChild(h('span', 'title', e.type === 'array' ? e.array || '(the array)' : e.name)); + const what = e.type === 'array' ? e.dtype + ' · ' + e.shape.join(' × ') : e.type === 'directory' ? 'directory' : e.type === 'archive' ? 'archive' + (e.kind ? ' of ' + e.kind + 's' : '') : (WORD[e.kind] || 'File').toLowerCase(); + name.appendChild(h('span', 'sub', what)); b.appendChild(name); + b.appendChild(h('span', 'sub num', e.bytes == null ? '' : bytes(e.bytes))); + b.addEventListener('click', () => { + if (into || (e.type === 'file' && e.kind === 'array')) { go(c, v, e.path); return; } + const siblings = e.type === 'array' ? tree.entries.filter(x => x.type === 'array') : null; + v.treeTarget = { path: e.path, array: e.array || null, kind: e.type === 'array' ? 'array' : e.kind || 'file', name: e.name, arrays: siblings }; + for (const x of left.querySelectorAll('.tree-entry[aria-pressed]')) { const on = String(x === b); if (x.getAttribute('aria-pressed') !== on) x.setAttribute('aria-pressed', on); } + showIn(c, v, v.treeTarget); + }); + li.appendChild(b); ul.appendChild(li); + } + left.appendChild(ul); + if (tree.total > tree.entries.length) { + const pg = h('div', 'pager'); + const pb = button('btn sm', 'Previous', () => { v.treeOffset = Math.max(0, v.treeOffset - TREE_LIMIT); draw(c, false); }); pb.disabled = v.treeOffset === 0; pb.dataset.key = 'tree-prev'; + const nb = button('btn sm', 'Next', () => { v.treeOffset += TREE_LIMIT; draw(c, false); }); nb.disabled = v.treeOffset + tree.entries.length >= tree.total; nb.dataset.key = 'tree-next'; + pg.appendChild(pb); pg.appendChild(nb); pg.appendChild(h('span', null, (v.treeOffset + 1) + '–' + (v.treeOffset + tree.entries.length) + ' of ' + tree.total)); left.appendChild(pg); + } + } + function go(c, v, path) { v.path = path; v.treeOffset = 0; draw(c, false); } + + // ---- The viewers --------------------------------------------------------------------------------------------- + /** + * The viewer of a target, read in full before it is returned: {record: id}, or a place in the tree + * {path, array, kind, arrays}. A refusal is shown as the server's sentence. + */ + async function viewerFor(c, v, target) { + const run = v.run, el = h('div', 'iv'); + try { + if (target.record != null) await recordView(c, v, el, await R.record(run, target.record)); + else await placeView(c, v, el, target); + } catch (error) { + el.replaceChildren(heading(target.record != null ? target.record : target.path + (target.array ? ' · ' + target.array : ''), null)); + el.appendChild(window.LabActions.refusal(error)); + } + return el; + } + function heading(id, line) { const hd = h('header', 'iv-head'); hd.appendChild(h('h3', 'mono', id)); if (line) hd.appendChild(h('p', 'small muted', line)); return hd; } + async function recordView(c, v, el, got) { + const r = got.record, k = got.content || {}; + el.appendChild(heading(r.id, [WORD[r.kind], bytes(r.bytes), r.path && r.path !== r.id ? r.path : null].filter(Boolean).join(' · '))); + const key = 'rec:' + r.id; + if (r.kind === 'text') textView(el, k); + else if (r.kind === 'image') imageView(el, r.url, k.width, k.height, r.id, settingsOf(v, key, () => ({ actual: false }))); + else if (r.kind === 'audio') audioView(el, r.url, k, r.id); + else if (r.kind === 'pointcloud') cloudView(el, k, settingsOf(v, key, turned)); + else if (r.kind === 'mesh') meshView(el, k, settingsOf(v, key, turned)); + else if (r.kind === 'array') await arrayView(el, v.run, r.path, k.arrays || [], k.show, settingsOf(v, key, () => ({}))); + else el.appendChild(h('p', 'note', 'A file of no kind Tuldok shows: it is listed, never opened.')); + const facts = h('dl', 'setup iv-facts'); + const put = (name, value) => { if (value == null || value === '') return; facts.appendChild(h('dt', null, name)); facts.appendChild(h('dd', typeof value === 'string' ? null : 'mono pre', typeof value === 'string' ? value : JSON.stringify(value, null, 1))); }; + put('Split', r.split); put('Rights', r.rights); put('Origin', r.origin); put('Meta', r.meta); + if (facts.children.length) el.appendChild(facts); + } + /** A place in the tree that is not a record: an array by its path, an image or a sound by the file route; other kinds only as a record. */ + async function placeView(c, v, el, t) { + if (t.kind === 'array') { el.appendChild(heading(t.path, 'Array')); await arrayView(el, v.run, t.path, t.arrays || [], t.array, settingsOf(v, 'path:' + t.path + '#' + t.array, () => ({}))); return; } + if (!t.path.includes('!')) { + try { await recordView(c, v, el, await R.record(v.run, t.path)); return; } catch (error) { if (error.code !== 'not-found') throw error; el.replaceChildren(); } + } + el.appendChild(heading(t.path, WORD[t.kind] || 'File')); + if (t.kind === 'image') imageView(el, R.fileUrl(v.run, t.path), null, null, t.path, settingsOf(v, 'path:' + t.path, () => ({ actual: false }))); + else if (t.kind === 'audio') audioView(el, R.fileUrl(v.run, t.path), null, t.path); + else el.appendChild(h('p', 'note', 'Not one of the product\'s records: Tuldok reads arrays, images and sounds by their place, and other kinds only as records.')); + } + function textView(el, k) { + const line = [count(k.characters != null ? k.characters : k.text.length, 'character'), k.truncated ? 'truncated: the first ' + k.text.length.toLocaleString('en-GB') + ' are shown' : null, k.replaced ? count(k.replaced, 'byte') + ' not UTF-8, shown as �' : null].filter(Boolean).join(' · '); + el.appendChild(h('p', 'small muted', line)); + const pre = h('pre', 'iv-text'); pre.textContent = k.text; pre.tabIndex = 0; pre.setAttribute('aria-label', 'The text'); el.appendChild(pre); + } + function imageView(el, url, width, height, id, st) { + const b = h('button', 'iv-img'); b.type = 'button'; b.dataset.key = 'iv-img'; b.setAttribute('aria-pressed', String(!!st.actual)); + const img = h('img'); img.src = url; img.alt = 'Image ' + id + (width && height ? ', ' + width + ' by ' + height + ' pixels' : ''); + b.appendChild(img); + const size = h('p', 'small muted'); + const say = () => { const w = width || img.naturalWidth, hh = height || img.naturalHeight; size.textContent = (w && hh ? w + ' × ' + hh + ' pixels' : img.complete ? 'size not found' : 'size known once it loads') + ' · ' + (st.actual ? 'actual size; press for fitted' : 'fitted; press for actual size'); b.classList.toggle('actual', !!st.actual); b.setAttribute('aria-pressed', String(!!st.actual)); b.setAttribute('aria-label', 'Image ' + id + ', ' + (st.actual ? 'at actual size' : 'fitted to the panel') + '; press to toggle'); }; + img.addEventListener('load', () => { if (!width) say(); }, { once: true }); + img.addEventListener('error', () => { size.textContent = 'The image could not be shown.'; }, { once: true }); + b.addEventListener('click', () => { st.actual = !st.actual; say(); }); + say(); el.appendChild(size); const box = h('div', 'iv-imgbox'); box.appendChild(b); el.appendChild(box); + } + function audioView(el, url, k, id) { + const has = k && k.seconds != null; + el.appendChild(h('p', 'small muted', has ? [k.seconds.toFixed(k.seconds < 10 ? 2 : 1) + ' s', k.rate.toLocaleString('en-GB') + ' Hz', count(k.channels, 'channel'), count(k.frames, 'frame')].join(' · ') : 'Length, rate and channels are read from a WAV only; the player reads the rest.')); + if (has && k.peaks && k.peaks.length) { + const cv = h('canvas', 'iv-wave'); cv.setAttribute('role', 'img'); cv.setAttribute('aria-label', 'Waveform of ' + id + ', ' + k.seconds.toFixed(2) + ' seconds'); + paints(cv, () => { + const size = fit(cv, 96); if (!size) return; const [W, H] = size, ctx = cv.getContext('2d'); ctx.clearRect(0, 0, W, H); + const ink = token('--mark'), axis = token('--line-strong'), n = k.peaks.length; + ctx.fillStyle = 'rgb(' + axis.join(',') + ')'; ctx.fillRect(0, Math.floor(H / 2), W, 1); + ctx.fillStyle = 'rgb(' + ink.join(',') + ')'; + for (let x = 0; x < W; x++) { + const a = Math.floor(x / W * n), b = Math.max(a + 1, Math.floor((x + 1) / W * n)); let lo = 1, hi = -1; + for (let i = a; i < b && i < n; i++) { lo = Math.min(lo, k.peaks[i][0]); hi = Math.max(hi, k.peaks[i][1]); } + if (hi < lo) continue; const y0 = (1 - hi) / 2 * (H - 2) + 1, y1 = (1 - lo) / 2 * (H - 2) + 1; ctx.fillRect(x, y0, 1, Math.max(1, y1 - y0)); + } + }); + el.appendChild(cv); + } + const a = h('audio'); a.controls = true; a.preload = 'metadata'; a.src = url; a.dataset.key = 'iv-audio'; a.setAttribute('aria-label', 'Play ' + id); el.appendChild(a); + } + + // ---- Point clouds and meshes: turned by dragging, zoomed by the wheel ---------------------------------------------- + const turned = () => ({ yaw: -0.6, pitch: 0.45, zoom: 1 }); + function cloudView(el, k, st) { + const pts = floats(k.points_f32), colours = k.colors_u8 ? raw(k.colors_u8) : null; + el.appendChild(h('p', 'small muted', count(k.count, 'point') + (k.stride > 1 ? ' · every ' + ordinal(k.stride) + ' shown (' + count(pts.length / 3, 'point') + ')' : '') + ' · ' + (colours ? 'their own colours' : 'coloured by height'))); + space(el, { points: pts, colours, bounds: k.bounds }, st, 'Point cloud, ' + count(pts.length / 3, 'point') + (k.stride > 1 ? ' of ' + k.count.toLocaleString('en-GB') : '')); + } + function meshView(el, k, st) { + const pos = floats(k.positions_f32), asPoints = k.triangles > MESH_AS_POINTS; + el.appendChild(h('p', 'small muted', count(k.vertices, 'vertex', 'vertices') + ' · ' + count(k.triangles, 'triangle') + (asPoints ? ' · above ' + MESH_AS_POINTS.toLocaleString('en-GB') + ' triangles the vertices are drawn as points' : ' · flat shaded'))); + if (asPoints) space(el, { points: pos, colours: null, bounds: k.bounds }, st, 'Mesh of ' + count(k.triangles, 'triangle') + ', drawn as its ' + count(k.vertices, 'vertex', 'vertices') + ' as points'); + else space(el, { points: pos, triangles: uints(k.triangles_u32), bounds: k.bounds }, st, 'Mesh, ' + count(k.vertices, 'vertex', 'vertices') + ' and ' + count(k.triangles, 'triangle') + ', flat shaded'); + } + const ordinal = n => n + (n % 100 >= 11 && n % 100 <= 13 ? 'th' : ['th', 'st', 'nd', 'rd'][n % 10] || 'th'); + /** A canvas showing points or triangles in 3-D; z is up. Drawn on requestAnimationFrame only after a change. */ + function space(el, m, st, label) { + const cv = h('canvas', 'iv-3d turns'); cv.tabIndex = 0; cv.setAttribute('role', 'img'); cv.dataset.key = 'iv-3d'; + cv.setAttribute('aria-label', label + '. Drag or use the arrow keys to turn it, the wheel or + and − to zoom.'); + const [lo, hi] = m.bounds || [[-1, -1, -1], [1, 1, 1]], centre = [0, 1, 2].map(i => (lo[i] + hi[i]) / 2); + const radius = Math.max(1e-9, Math.hypot(hi[0] - lo[0], hi[1] - lo[1], hi[2] - lo[2]) / 2); + let frame = 0; + const draw = () => { + frame = 0; + const size = fit(cv, Math.min(420, Math.round(cv.clientWidth * 0.75))); if (!size) return; + const [W, H] = size, ctx = cv.getContext('2d'), img = ctx.createImageData(W, H), px = img.data, depth = new Float32Array(W * H).fill(Infinity); + const cy = Math.cos(st.yaw), sy = Math.sin(st.yaw), cp = Math.cos(st.pitch), sp = Math.sin(st.pitch), s = st.zoom * 0.46 * Math.min(W, H) / radius; + const n = m.points.length / 3, X = new Float32Array(n), Y = new Float32Array(n), Z = new Float32Array(n); + for (let i = 0; i < n; i++) { + const x = m.points[i * 3] - centre[0], y = m.points[i * 3 + 1] - centre[1], z = m.points[i * 3 + 2] - centre[2]; + const x1 = x * cy - y * sy, y1 = x * sy + y * cy, d = y1 * cp + z * sp, up = -y1 * sp + z * cp; + X[i] = W / 2 + x1 * s; Y[i] = H / 2 - up * s; Z[i] = d; + } + if (m.triangles) { + const base = token('--mark'), L = [-0.35, 0.55, -0.76], t = m.triangles; + for (let f = 0; f + 2 < t.length; f += 3) { + const a = t[f], b = t[f + 1], c = t[f + 2]; + // The normal in screen space (x right, y up, z away), for flat shading lit from the front. + const ux = X[b] - X[a], uy = Y[a] - Y[b], uz = (Z[b] - Z[a]) * s, vx = X[c] - X[a], vy = Y[a] - Y[c], vz = (Z[c] - Z[a]) * s; + const nx = uy * vz - uz * vy, ny = uz * vx - ux * vz, nz = ux * vy - uy * vx, len = Math.hypot(nx, ny, nz) || 1; + const shade = 0.32 + 0.68 * Math.abs((nx * L[0] + ny * L[1] + nz * L[2]) / len); + triangle(px, depth, W, H, X[a], Y[a], Z[a], X[b], Y[b], Z[b], X[c], Y[c], Z[c], base[0] * shade, base[1] * shade, base[2] * shade); + } + } else { + const r = Math.max(1, Math.round((window.devicePixelRatio || 1) * 1.6)); + const neg = token('--ramp-neg'), pos = token('--ramp-pos'), span = (hi[2] - lo[2]) || 1; + for (let i = 0; i < n; i++) { + const x0 = Math.round(X[i]), y0 = Math.round(Y[i]); if (x0 < 0 || y0 < 0 || x0 >= W || y0 >= H) continue; + let R, G, B; if (m.colours) { R = m.colours[i * 3]; G = m.colours[i * 3 + 1]; B = m.colours[i * 3 + 2]; } else { const c = mix(neg, pos, (m.points[i * 3 + 2] - lo[2]) / span); R = c[0]; G = c[1]; B = c[2]; } + for (let dy = 0; dy < r; dy++) for (let dx = 0; dx < r; dx++) { + const xx = x0 + dx, yy = y0 + dy; if (xx >= W || yy >= H) continue; const o = yy * W + xx; + if (Z[i] < depth[o]) { depth[o] = Z[i]; px[o * 4] = R; px[o * 4 + 1] = G; px[o * 4 + 2] = B; px[o * 4 + 3] = 255; } + } + } + } + ctx.putImageData(img, 0, 0); + }; + const later = () => { if (!frame) frame = requestAnimationFrame(draw); }; + paints(cv, draw); + let drag = null; + cv.addEventListener('pointerdown', e => { if (e.button !== 0) return; drag = { x: e.clientX, y: e.clientY, id: e.pointerId }; cv.setPointerCapture(e.pointerId); cv.classList.add('dragging'); }); + cv.addEventListener('pointermove', e => { if (!drag || e.pointerId !== drag.id) return; st.yaw += (e.clientX - drag.x) * 0.01; st.pitch = Math.max(-1.55, Math.min(1.55, st.pitch + (e.clientY - drag.y) * 0.01)); drag.x = e.clientX; drag.y = e.clientY; later(); }); + const end = e => { if (drag && e.pointerId === drag.id) { drag = null; cv.classList.remove('dragging'); } }; + cv.addEventListener('pointerup', end); cv.addEventListener('pointercancel', end); + cv.addEventListener('wheel', e => { e.preventDefault(); st.zoom = Math.max(0.2, Math.min(25, st.zoom * Math.exp(-e.deltaY * 0.0015))); later(); }, { passive: false }); + cv.addEventListener('keydown', e => { + const k = e.key; let used = true; + if (k === 'ArrowLeft') st.yaw -= 0.15; else if (k === 'ArrowRight') st.yaw += 0.15; + else if (k === 'ArrowUp') st.pitch = Math.max(-1.55, st.pitch - 0.15); else if (k === 'ArrowDown') st.pitch = Math.min(1.55, st.pitch + 0.15); + else if (k === '+' || k === '=') st.zoom = Math.min(25, st.zoom * 1.2); else if (k === '-' || k === '−') st.zoom = Math.max(0.2, st.zoom / 1.2); + else used = false; + if (used) { e.preventDefault(); later(); } + }); + el.appendChild(cv); + const bar = h('div', 'iv-ctl'); + const reset = button('btn sm', 'Reset view', () => { Object.assign(st, turned()); later(); }); reset.dataset.key = 'iv-reset'; bar.appendChild(reset); + bar.appendChild(h('span', 'small faint', 'Drag to turn, wheel to zoom')); + el.appendChild(bar); + } + /** Fills one triangle into the pixel and depth buffers (nearest wins). */ + function triangle(px, depth, W, H, ax, ay, az, bx, by, bz, cx, cy, cz, R, G, B) { + const area = (bx - ax) * (cy - ay) - (by - ay) * (cx - ax); if (Math.abs(area) < 1e-9) return; + const x0 = Math.max(0, Math.floor(Math.min(ax, bx, cx))), x1 = Math.min(W - 1, Math.ceil(Math.max(ax, bx, cx))); + const y0 = Math.max(0, Math.floor(Math.min(ay, by, cy))), y1 = Math.min(H - 1, Math.ceil(Math.max(ay, by, cy))); + for (let y = y0; y <= y1; y++) { + const py = y + 0.5; + for (let x = x0; x <= x1; x++) { + const qx = x + 0.5; + const w0 = ((cx - bx) * (py - by) - (cy - by) * (qx - bx)) / area, w1 = ((ax - cx) * (py - cy) - (ay - cy) * (qx - cx)) / area, w2 = 1 - w0 - w1; + if (w0 < 0 || w1 < 0 || w2 < 0) continue; + const z = w0 * az + w1 * bz + w2 * cz, o = y * W + x; + if (z < depth[o]) { depth[o] = z; px[o * 4] = R; px[o * 4 + 1] = G; px[o * 4 + 2] = B; px[o * 4 + 3] = 255; } + } + } + } + + // ---- Arrays: a slice along two axes, sliders for the others, the stacked slices and the histogram --------------------- + /** A line of a one-row slice across (x, y, w, hh). */ + function line(ctx, values, min, max, x, y, w, hh, width) { + const n = values.length, span = (max - min) || 1, ink = token('--mark'); + ctx.strokeStyle = 'rgb(' + ink.join(',') + ')'; ctx.lineWidth = width; ctx.beginPath(); + let on = false; + for (let i = 0; i < n; i++) { const v = values[i]; if (!Number.isFinite(v)) { on = false; continue; } const px = x + (n === 1 ? w / 2 : i / (n - 1) * w), py = y + hh - 4 - (v - min) / span * (hh - 8); if (on) ctx.lineTo(px, py); else ctx.moveTo(px, py); on = true; } + ctx.stroke(); + } + async function arrayView(el, run, path, arrays, show, st) { + if (!arrays.length) { el.appendChild(h('p', 'note', 'This file holds no array.')); return; } + const pick = arrays.find(a => a.array === st.array) || arrays.find(a => a.array === show) || arrays.find(a => a.shape.length >= 2) || arrays[0]; + st.array = pick.array; + const box = h('div', 'iv-array'); + /** Draws this array viewer again (another array or other axes), replacing it in one step with the focus kept. */ + const again = async () => { + const host = h('div'); await arrayView(host, run, path, arrays, show, st); + const fresh = host.firstChild; if (!fresh || !box.isConnected) return; + const key = box.contains(document.activeElement) && document.activeElement.dataset ? document.activeElement.dataset.key : null; + box.replaceWith(fresh); + if (key) { const e = [...fresh.querySelectorAll('[data-key]')].find(x => x.dataset.key === key); if (e) e.focus({ preventScroll: true }); } + }; + // The arrays, with shape and type; the one chosen is drawn. + if (arrays.length > 1) { + const s = h('select'); s.setAttribute('aria-label', 'Array'); s.dataset.key = 'iv-array'; + for (const a of arrays) { const o = h('option', null, (a.array == null ? '(the array)' : a.array) + ' · ' + a.dtype + ' · ' + (a.shape.length ? a.shape.join(' × ') : 'one value')); o.value = a.array; o.selected = a === pick; s.appendChild(o); } + s.addEventListener('change', () => { st.array = s.value; st.axes = null; st.index = null; again(); }); + const l = h('label', 'iv-field'); l.appendChild(document.createTextNode('Array')); l.appendChild(s); box.appendChild(l); + } else box.appendChild(h('p', 'small muted', (pick.array ? pick.array + ' · ' : '') + pick.dtype + ' · ' + (pick.shape.length ? pick.shape.join(' × ') : 'one value'))); + const shape = pick.shape, nd = shape.length; + if (!st.axes || st.axes.some(a => a >= nd)) st.axes = nd >= 2 ? [nd - 2, nd - 1] : nd === 1 ? [0] : []; + if (!st.index || st.index.length !== nd) st.index = shape.map(n => Math.floor(n / 2)); + const base = { path, array: pick.array, most: VIEW_MOST }; + const args = () => { const a = Object.assign({}, base); if (nd >= 2) { a.axes = st.axes.slice(); a.index = st.index.slice(); } return a; }; + // Two axes drawn (for three or more dimensions they can be chosen), a slider per other axis. + const ctl = h('div', 'iv-ctl'); + if (nd > 2) for (const [i, label] of [[0, 'Rows'], [1, 'Columns']]) { + const s = h('select'); s.setAttribute('aria-label', label + ' axis'); s.dataset.key = 'iv-axis-' + i; + for (let a = 0; a < nd; a++) { const o = h('option', null, 'axis ' + a + ' (' + shape[a] + ')'); o.value = String(a); o.selected = st.axes[i] === a; o.disabled = st.axes[1 - i] === a; s.appendChild(o); } + s.addEventListener('change', () => { st.axes[i] = Number(s.value); again(); }); + const l = h('label', 'iv-field'); l.appendChild(document.createTextNode(label)); l.appendChild(s); ctl.appendChild(l); + } + const others = nd >= 2 ? shape.map((_, a) => a).filter(a => !st.axes.includes(a)) : []; + const sliders = []; + for (const a of others) { + const l = h('label', 'iv-field iv-slider'); const name = h('span', null, 'Axis ' + a); l.appendChild(name); + const r = h('input'); r.type = 'range'; r.min = '0'; r.max = String(shape[a] - 1); r.value = String(st.index[a]); r.dataset.key = 'iv-axis-slider-' + a; r.dataset.axis = String(a); + const at = h('span', 'num small', st.index[a] + ' of ' + shape[a]); + r.setAttribute('aria-label', 'Position on axis ' + a + ', 0 to ' + (shape[a] - 1)); + l.appendChild(r); l.appendChild(at); ctl.appendChild(l); sliders.push({ a, r, at }); + } + if (ctl.children.length) box.appendChild(ctl); + // The slice, read now. + let s; + try { s = await R.slice(run, args(), true); } catch (error) { box.appendChild(window.LabActions.refusal(error)); el.appendChild(box); return; } + const sliceBox = h('div', 'iv-slice'), cv = h('canvas', 'iv-heat'); cv.setAttribute('role', 'img'); sliceBox.appendChild(cv); + const range = h('p', 'small muted iv-range'), probe = h('p', 'small iv-probe'); probe.textContent = 'Point at the slice to read a value.'; + let values = floats(s.values_f32), rect = null; + const say = () => { + cv.dataset.index = JSON.stringify(s.index); cv.dataset.axes = JSON.stringify(s.axes || []); + const what = s.rows === 1 && nd <= 1 ? (nd === 0 ? 'The value' : 'The ' + s.columns + ' values') : 'Slice of ' + s.rows + ' by ' + s.columns + ' values along axes ' + (s.axes || []).join(' and ') + (others.length ? ' at ' + others.map(a => 'axis ' + a + ' = ' + s.index[a]).join(', ') : ''); + cv.setAttribute('aria-label', what + ' of ' + (pick.array || path) + ', from ' + fmt(s.min) + ' to ' + fmt(s.max)); + range.textContent = 'From ' + fmt(s.min) + ' to ' + fmt(s.max) + (s.stride > 1 ? ' · every ' + ordinal(s.stride) + ' row and column' : '') + (s.nonfinite ? ' · ' + count(s.nonfinite, 'value') + ' not finite, left clear' : ''); + }; + const paintSlice = () => { + const wide = s.rows === 1, w = cv.clientWidth; if (!w) return; + const cssH = wide ? 120 : Math.max(80, Math.min(360, Math.round(w * s.rows / s.columns))); + const size = fit(cv, cssH); if (!size) return; const [W, H] = size, ctx = cv.getContext('2d'); ctx.clearRect(0, 0, W, H); + if (wide) { rect = [0, 0, W, H]; line(ctx, values, s.min == null ? 0 : s.min, s.max == null ? 1 : s.max, 0, 0, W, H, Math.max(1.5, W / 400)); } + else { rect = contain(s.rows, s.columns, W, H); heat(ctx, values, s.rows, s.columns, ramp(s.min == null ? 0 : s.min, s.max == null ? 1 : s.max), ...rect); } + const where = rect.map(n => Math.round(n * 100) / 100).join(',') + ';' + s.rows + 'x' + s.columns; // where the cells are, for a reader of the page + if (cv.dataset.cells !== where) cv.dataset.cells = where; + }; + paints(cv, paintSlice); + cv.addEventListener('pointermove', e => { + if (!rect) return; const dpr = cv.width / cv.clientWidth, x = e.offsetX * dpr - rect[0], y = e.offsetY * (cv.height / cv.clientHeight) - rect[1]; + if (x < 0 || y < 0 || x >= rect[2] || y >= rect[3]) { probe.textContent = 'Point at the slice to read a value.'; delete probe.dataset.index; return; } + const col = Math.min(s.columns - 1, Math.floor(x / rect[2] * s.columns)), row = s.rows === 1 ? 0 : Math.min(s.rows - 1, Math.floor(y / rect[3] * s.rows)); + const index = (s.index || []).slice(); if (nd >= 2) { index[s.axes[0]] = row * s.stride; index[s.axes[1]] = col * s.stride; } else if (nd === 1) index[0] = col * s.stride; + const v = values[row * s.columns + col]; + probe.textContent = '[' + index.join(', ') + '] = ' + (Number.isFinite(v) ? String(v) : String(v) + ' (not finite)'); + probe.dataset.index = JSON.stringify(index); probe.dataset.value = String(v); + }); + cv.addEventListener('pointerleave', () => { probe.textContent = 'Point at the slice to read a value.'; delete probe.dataset.index; }); + box.appendChild(sliceBox); box.appendChild(range); box.appendChild(probe); say(); + // Three or more dimensions: the stacked slices along the first other axis, the slider's slice outlined (the mockup's drawVolume). + let stack = null; + if (nd >= 3) { + const axis = others[0], n = shape[axis], at = Array.from(new Set(Array.from({ length: Math.min(n, STACK_SLICES) }, (_, i) => Math.round(n <= STACK_SLICES ? i : i * (n - 1) / (STACK_SLICES - 1))))); + const vol = h('canvas', 'iv-vol'); vol.setAttribute('role', 'img'); + stack = { axis, at, vol, slices: null, key: null }; + const loadStack = async () => { + const key = JSON.stringify([st.axes, st.index.filter((_, i) => i !== axis)]); if (stack.key === key) return; stack.key = key; + const got = await Promise.all(at.map(p => { const a = args(); a.most = STACK_MOST; a.index[axis] = p; return R.slice(run, a); })); + if (stack.key !== key) return; + stack.slices = got.map(g => ({ values: floats(g.values_f32), rows: g.rows, cols: g.columns, min: g.min, max: g.max })); + }; + const paintStack = () => { + if (!stack.slices) return; const w = vol.clientWidth; if (!w) return; + const size = fit(vol, Math.round(Math.min(360, w * 0.62))); if (!size) return; + volume(vol, stack.slices, at.indexOf(nearest(at, st.index[axis]))); + vol.setAttribute('aria-label', 'Stacked slices of ' + (pick.array || path) + ' along axis ' + axis + ': ' + at.length + ' of its ' + n + ' positions, the one at ' + nearest(at, st.index[axis]) + ' outlined'); + }; + try { await loadStack(); } catch (error) { stack = null; box.appendChild(window.LabActions.refusal(error)); } + if (stack) { paints(vol, paintStack); stack.paint = paintStack; stack.load = loadStack; const vb = h('div', 'iv-volbox'); vb.appendChild(vol); box.insertBefore(vb, sliceBox); } + } + // A slider moves the slice: read again (the latest wins), redraw in place. + let wanted = 0, timer = 0; + for (const { a, r, at } of sliders) r.addEventListener('input', () => { + st.index[a] = Number(r.value); at.textContent = st.index[a] + ' of ' + shape[a]; + if (stack && a === stack.axis) stack.paint && stack.paint(); + clearTimeout(timer); const mine = ++wanted; + timer = setTimeout(async () => { + try { + const next = await R.slice(run, args(), true); if (mine !== wanted) return; + s = next; values = floats(s.values_f32); paintSlice(); say(); + probe.textContent = 'Point at the slice to read a value.'; delete probe.dataset.index; + if (stack && a !== stack.axis) { await stack.load(); stack.paint(); } + } catch (error) { if (mine === wanted) { probe.textContent = error.message; } } + }, 90); + }); + // The summary's histogram, on request. + const hb = button('btn sm', st.hist ? 'Hide the histogram' : 'Show the histogram'); hb.dataset.key = 'iv-hist'; hb.setAttribute('aria-expanded', String(!!st.hist)); + const hist = h('div', 'iv-hist'); hist.hidden = !st.hist; + const fillHist = async () => { + if (hist.firstChild) return; + try { + const sum = await R.summary(run, { path, array: pick.array, bins: 64 }); + const hc = h('canvas', 'iv-histc'); hc.setAttribute('role', 'img'); hc.setAttribute('aria-label', 'Histogram of ' + (pick.array || path) + ' in ' + sum.histogram.counts.length + ' bins from ' + fmt(sum.histogram.low) + ' to ' + fmt(sum.histogram.high)); + paints(hc, () => { + const size = fit(hc, 110); if (!size) return; const [W, H] = size, ctx = hc.getContext('2d'); ctx.clearRect(0, 0, W, H); + const counts = sum.histogram.counts, most = Math.max(1, ...counts), bw = W / counts.length, ink = token('--mark'), axis = token('--line-strong'); + ctx.fillStyle = 'rgb(' + ink.join(',') + ')'; + counts.forEach((n, i) => { if (!n) return; const bh = Math.max(1, n / most * (H - 6)); ctx.fillRect(i * bw + 0.5, H - bh, Math.max(1, bw - 1), bh); }); + ctx.fillStyle = 'rgb(' + axis.join(',') + ')'; ctx.fillRect(0, H - 1, W, 1); + }); + hist.appendChild(hc); + const ends = h('div', 'iv-ends small faint'); ends.appendChild(h('span', null, fmt(sum.histogram.low))); ends.appendChild(h('span', null, fmt(sum.histogram.high))); hist.appendChild(ends); + const dl = h('dl', 'setup iv-facts'); + for (const [k, val] of [['Values', sum.count.toLocaleString('en-GB') + (sum.stride > 1 ? ', every ' + ordinal(sum.stride) + ' read' : '')], ['Mean', fmt(sum.mean)], ['Deviation', fmt(sum.std)], ['Zeros', sum.zeros.toLocaleString('en-GB')], ['Not finite', sum.nonfinite.toLocaleString('en-GB')]]) { dl.appendChild(h('dt', null, k)); dl.appendChild(h('dd', 'num', val)); } + hist.appendChild(dl); + } catch (error) { hist.appendChild(window.LabActions.refusal(error)); } + }; + hb.addEventListener('click', async () => { st.hist = !st.hist; hb.textContent = st.hist ? 'Hide the histogram' : 'Show the histogram'; hb.setAttribute('aria-expanded', String(st.hist)); if (st.hist) await fillHist(); hist.hidden = !st.hist; }); + if (st.hist) await fillHist(); + const hrow = h('div', 'iv-ctl'); hrow.appendChild(hb); box.appendChild(hrow); box.appendChild(hist); + el.appendChild(box); + } + const nearest = (list, x) => list.reduce((a, b) => Math.abs(b - x) < Math.abs(a - x) ? b : a, list[0]); + /** The stacked-slice drawing of the mockup (drawVolume): each slice a sheared sheet of cells, the chosen one outlined. */ + function volume(canvas, slices, hot) { + const W = canvas.width, H = canvas.height, ctx = canvas.getContext('2d'); ctx.clearRect(0, 0, W, H); + let min = Infinity, max = -Infinity; for (const sl of slices) { if (sl.min != null) min = Math.min(min, sl.min); if (sl.max != null) max = Math.max(max, sl.max); } + if (!Number.isFinite(min)) { min = 0; max = 1; } + const colour = ramp(min, max), first = slices[0], sx = Math.min(16, first.cols), sy = Math.max(2, Math.min(16, Math.round(16 * first.rows / Math.max(1, first.cols)), first.rows)), nsl = slices.length; + const cw = Math.min(W * 0.62 / (sx + sy / 2), 30 * W / 480), ch = cw * 0.5, dz = Math.min(H * 0.07, (H - 30 - sy * ch) / Math.max(1, nsl - 1)); + const ox = W / 2 - (sx * cw) / 2 + (sy * cw) / 4, oy = H - 16 - (nsl - 1) * dz - sy * ch; + const accent = token('--accent'); + for (let k = 0; k < nsl; k++) { + const sl = slices[k], isHot = k === hot; ctx.globalAlpha = isHot ? 1 : 0.55; + for (let j = 0; j < sy; j++) for (let i = 0; i < sx; i++) { + const v = sl.values[Math.min(sl.rows - 1, Math.floor(j * sl.rows / sy)) * sl.cols + Math.min(sl.cols - 1, Math.floor(i * sl.cols / sx))]; + if (!Number.isFinite(v)) continue; const c = colour(v); ctx.fillStyle = 'rgb(' + c.map(Math.round).join(',') + ')'; + const px = ox + i * cw - j * (cw / 2), py = oy + (nsl - 1 - k) * dz + j * ch; + ctx.beginPath(); ctx.moveTo(px, py); ctx.lineTo(px + cw, py); ctx.lineTo(px + cw / 2, py + ch); ctx.lineTo(px - cw / 2, py + ch); ctx.closePath(); ctx.fill(); + } + if (isHot) { ctx.globalAlpha = 1; ctx.strokeStyle = 'rgb(' + accent.join(',') + ')'; ctx.lineWidth = Math.max(2, W / 300); const py = oy + (nsl - 1 - k) * dz; ctx.beginPath(); ctx.moveTo(ox, py); ctx.lineTo(ox + sx * cw, py); ctx.lineTo(ox + sx * cw - sy * cw / 2, py + sy * ch); ctx.lineTo(ox - sy * cw / 2, py + sy * ch); ctx.closePath(); ctx.stroke(); } + } + ctx.globalAlpha = 1; + } + + return { open, leave, PER_PAGE }; +})(); diff --git a/static/project-workspace/tabs.js b/static/project-workspace/tabs.js index 3b6614bf..1b26515f 100644 --- a/static/project-workspace/tabs.js +++ b/static/project-workspace/tabs.js @@ -602,8 +602,17 @@ } // ---- Data ----------------------------------------------------------------------- + // The tab has two states (spec-d1 section 7): the cards, and one dataset opened, '#data/inside:' + // (inside.js); a selection '' is that dataset's drawer beside the cards, as before. + const INSIDE = 'inside:'; + const lookInside = (ref, act) => { const b = button('btn sm', 'Look inside', ev => { ev.stopPropagation(); act.go('data', INSIDE + ref); }); b.dataset.key = 'inside-' + ref; return b; }; + /** Data: the dataset cards, a dataset's drawer, or one dataset opened (inside.js). */ function data_(main, aside, state, act, data) { - const E = window.LabEditor, raw = state.sel.data || null, sel = raw && E ? E.subject(raw) : raw; + const E = window.LabEditor, raw = state.sel.data || null; + if (raw && raw.startsWith(INSIDE)) { closeDrawer(aside); window.LabInside.open(main, raw.slice(INSIDE.length), act, !!aside._again); return false; } + if (window.LabInside) window.LabInside.leave(); + if (main._painted && String(main._painted).startsWith('data/' + INSIDE)) { main.scrollTop = 0; main.scrollLeft = 0; } // back to the cards: from their top + const sel = raw && E ? E.subject(raw) : raw; paint(main, () => Promise.all([P.read('definitions', { kind: 'dataset' }), P.read('products'), P.read('graph')]), (frag, [defs, products, graph]) => { const sets = defs.definitions.filter(d => !d.removed), byRef = new Map(); for (const p of products.products) { if (!byRef.has(p.reference)) byRef.set(p.reference, []); byRef.get(p.reference).push(p); } @@ -628,7 +637,11 @@ t.appendChild(h('div', 'uses', used.length ? 'used by ' + used.length + ': ' + used.map(nameOfRef).join(', ') : 'used by nothing')); t.appendChild(h('div', 'path', ps.length ? ps[0].directory : d.reference)); card.appendChild(t); card.title = d.title; - card.addEventListener('click', () => act.select(d.reference === sel ? null : d.reference)); grid.appendChild(card); + card.addEventListener('click', () => act.select(d.reference === sel ? null : d.reference)); + // "Look inside" beside the card (a button cannot hold a button), when the dataset has a product here. + const item = h('div', 'ds-item'); item.appendChild(card); + if (ps.some(p => p.run_id)) { const foot = h('div', 'ds-foot'); foot.appendChild(lookInside(d.reference, act)); item.appendChild(foot); } + grid.appendChild(item); } frag.appendChild(grid); }); @@ -638,6 +651,7 @@ const hd = h('header'); hd.appendChild(h('span', 'kicker', d.reference)); const t2 = h('h2', null, d.title); t2.tabIndex = -1; hd.appendChild(t2); const meta = h('div', 'ins-meta'); meta.appendChild(p.products.some(x => x.adopted) ? S.stateEl('good', 'adopted') : modelState(d.state)); meta.appendChild(Tree.mark({ id: d.reference, unsaved: d.unsaved })); hd.appendChild(meta); ins.appendChild(hd); // Edit (spec-w3 section 3.2): the editor, in the text view. + if (p.products.some(x => x.run_id)) { const look = h('div', 'actions'); look.appendChild(lookInside(d.reference, act)); ins.appendChild(look); } ins.appendChild(A.group('dataedit:' + d.reference, [{ id: 'edit', label: 'Edit', cls: 'btn sm', who: 'edit', onClick: () => act.select('edit:' + d.reference) }])); if (E) E.decorate(hd); const doc = d.document || {}; diff --git a/tests/browser_project_workspace_inside.cjs b/tests/browser_project_workspace_inside.cjs new file mode 100644 index 00000000..a46e02f5 --- /dev/null +++ b/tests/browser_project_workspace_inside.cjs @@ -0,0 +1,454 @@ +'use strict'; +// Looking inside a product (docs/plans/definition-first-projects/spec-d1.md sections 7 and 9, slice D1b) in a +// headless browser, the owner signed in, no GPU. Tuldok runs with --project-folder on a copy of the minimal fixture +// with the buildable fixture's definitions beside it, in a Git repository of its own, and one more dataset, +// datasets/specimens, whose command (tests/project_inside_browser_fixture.py, standard library only) writes a +// product of 57 records: at least one of every kind (text, image, audio, point cloud, mesh, array, file), a zip +// archive holding .npz arrays, and an array Tuldok refuses to read. The command line builds it before Tuldok starts. +// 1. Data shows "Look inside" on that dataset and not on one without a product; the dataset opens to 48 tiles, +// the counts by kind are the fixture's, the pager reaches the rest, a kind filter narrows the grid. +// 2. Each kind's viewer shows its record: the text equals the file's; the image is decoded at its true size; the +// sound plays, with the right length and a drawn waveform; a point cloud and a mesh draw a canvas that is not +// blank and changes when dragged (and a mesh above 60,000 triangles says it is drawn as points); the array's +// value under the pointer equals the fixture's at that place, and its slider moves the slice; the histogram +// draws; the array Tuldok refuses shows the server's sentence and the grid stays usable; left and right +// arrows move the selection. +// 3. "Files" lists the tree, opens the archive and an array inside it, whose value under the pointer is the +// fixture's. +// 4. With the dataset open and a record selected, the window regaining focus and one reading on the timer add, +// remove and change no node and keep every scroll (the counting of browser_project_workspace_still.cjs). When +// something changes elsewhere (an agent asks for a build), the view is drawn again in place: same page, same +// selection, same scroll, no "Reading…". +// 5. Light and dark: no viewer is blank in either, at 1440 by 900; screenshots of the view and every viewer in +// both themes at 1440 by 900 and 1000 by 800 (with --shots , written there too). +// Step 6 of the spec (the existing workspace checks pass unchanged) is the running of those checks. +// With --lab-root nothing is asserted (spec-d1 section 9: a fresh database has no products for the lab). +// It fails on any script error, and on any failed request but the refusals the check asks for. +// node tests/browser_project_workspace_inside.cjs [--shots ] [--lab-root ] +const assert = require('node:assert/strict'), fs = require('node:fs'), os = require('node:os'), path = require('node:path'); +const { spawn, execFileSync } = require('node:child_process'), { once } = require('node:events'); +const { authenticatedFixture } = require('./auth_helpers.cjs'), { waitForDebugger } = require('./browser_startup.cjs'), { cdpSession } = require('./browser_cdp_session.cjs'), { qaDirectory } = require('./qa_artifacts.cjs'); + +const root = path.resolve(__dirname, '..'); +const argv = process.argv.slice(2), option = name => { const i = argv.indexOf(name); return i >= 0 ? argv[i + 1] : null; }; +if (argv.includes('--lab-root')) { console.log('Nothing is asserted with --lab-root (spec-d1 section 9): a fresh database has no products for the lab.'); process.exit(0); } +assert.ok(process.env.TULDOK_DATABASE_URL, 'TULDOK_DATABASE_URL must name a disposable PostgreSQL cluster'); +const venv = path.join(root, '.venv', 'bin'); +if (fs.existsSync(path.join(venv, 'python'))) process.env.PATH = venv + path.delimiter + process.env.PATH; // auth_helpers runs python3 +const python = fs.existsSync(path.join(venv, 'python')) ? path.join(venv, 'python') : 'python3'; +const IDLE_MS = 15000; // the page's reading while nothing builds (app.js) +const WATCHED = ['summary', 'status', 'build_requests', 'environments', 'runs']; +const REF = 'datasets/specimens', OPENED = 'data/' + encodeURIComponent('inside:' + REF); +const KINDS = { text: 45, image: 1, audio: 1, pointcloud: 2, mesh: 3, array: 3, file: 2 }; // what the fixture's command writes +const TOTAL = Object.values(KINDS).reduce((a, b) => a + b, 0); + +const temporary = fs.mkdtempSync(path.join(os.tmpdir(), 'tuldok-inside-browser-')); +const report = qaDirectory(root, 'project-workspace-inside'); +const shots = option('--shots') ? path.resolve(option('--shots')) : null; if (shots) fs.mkdirSync(shots, { recursive: true }); +const children = [], checks = [], errors = [], failures = [], refusedOk = []; +let server, serverErrors = '', origin, auth, socket, session, send, evaluate, owned = null; +const pause = ms => new Promise(resolve => setTimeout(resolve, ms)); +async function until(fn, label, tries = 300) { for (let i = 0; i < tries; i++) { const value = await fn(); if (value) return value; await pause(100); } throw Error('Timed out: ' + label); } +function check(text) { checks.push(text); console.log('PASS ' + text); } +function launch(command, args, options) { const child = spawn(command, args, options); children.push(child); return child; } +async function stop(child) { if (!child || child.exitCode !== null || child.signalCode !== null) return; const exited = once(child, 'exit'); child.kill('SIGTERM'); await Promise.race([exited, pause(10000)]); if (child.exitCode === null && child.signalCode === null) { child.kill('SIGKILL'); await exited; } } +function findBrowser() { + const candidates = [process.env.BROWSER, '/usr/bin/chromium', '/usr/bin/chromium-browser', '/usr/bin/google-chrome']; + const cache = path.join(os.homedir(), '.cache', 'ms-playwright'); + if (fs.existsSync(cache)) for (const name of fs.readdirSync(cache).filter(n => n.startsWith('chromium_headless_shell-')).sort().reverse()) candidates.push(path.join(cache, name, 'chrome-headless-shell-linux64', 'chrome-headless-shell')); + const found = candidates.find(candidate => candidate && fs.existsSync(candidate)); + assert.ok(found, 'No headless browser: set BROWSER'); + return found; +} +/** Drops the project's schema and the catalog's from the disposable database, so each run imports afresh. */ +function dropOwned(folder, catalog) { + const id = JSON.parse(fs.readFileSync(path.join(folder, 'tuldok.json'), 'utf8')).id; + execFileSync(python, ['-c', `import json, os, pathlib, sys, psycopg +from psycopg import sql +from tuldok_project import store +store.drop_project(sys.argv[1], os.environ['TULDOK_DATABASE_URL']) +root = pathlib.Path(sys.argv[2]) +if root.exists(): + with psycopg.connect(os.environ['TULDOK_DATABASE_URL'], autocommit=True) as c: + for p in root.rglob('.tuldok.json'): + v = json.loads(p.read_text()) + name = 'projection_' + v['projection_id'] if v.get('version') == 2 else 'catalog_' + v['dataset_id'] + c.execute(sql.SQL('DROP SCHEMA IF EXISTS {} CASCADE').format(sql.Identifier(name))) +`, id, catalog], { cwd: root, stdio: ['ignore', 'pipe', 'pipe'] }); +} +async function contract(name) { + const capabilities = await (await auth.fetch(origin + '/api/agent/capabilities')).json(); + const operation = capabilities.operations.find(item => item.id === 'project.' + name), c = operation.contracts[operation.contracts.length - 1]; + return 'project.' + name + '/' + c.version + '/' + c.sha256; +} +/** An operation as the owner (bearer: as that agent credential instead); refused: the refusal is answered instead of failing. */ +async function api(name, body = {}, refused = false, bearer = null) { + const headers = { 'Content-Type': 'application/json', 'Tuldok-Operation-Contract': await contract(name) }; + const response = bearer ? await globalThis.fetch(origin + '/api/project/' + name, { method: 'POST', headers: { ...headers, Authorization: 'Bearer ' + bearer }, body: JSON.stringify(body) }) + : await auth.fetch(origin + '/api/project/' + name, { method: 'POST', headers, body: JSON.stringify(body) }); + const value = await response.json(); if (!refused) assert.equal(response.status, 200, name + ': ' + JSON.stringify(value)); return value; +} +async function credential(label, scopes) { + const response = await auth.fetch(origin + '/api/access/credentials', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ label, scopes, ttl_seconds: 3600 }) }); + const value = await response.json(); assert.equal(response.status, 201, JSON.stringify(value)); return value.token; +} + +// ---- The page's readings, from the browser's network (as browser_project_workspace_still.cjs) ---------------- +const calls = new Map(), finished = []; +function network(event) { + const p = event.params; + if (event.method === 'Network.requestWillBeSent' && /\/api\/project\/[a-z_]+$/.test(p.request.url)) calls.set(p.requestId, { name: p.request.url.split('/').pop(), sent: Date.now() }); + if ((event.method === 'Network.loadingFinished' || event.method === 'Network.loadingFailed') && calls.has(p.requestId)) { finished.push(Object.assign(calls.get(p.requestId), { done: Date.now() })); calls.delete(p.requestId); } +} +async function reading(since, names, label, tries = 300) { + await until(() => names.every(name => finished.some(f => f.name === name && f.sent >= since)), 'a reading: ' + label, tries); + await until(() => !calls.size && Date.now() - Math.max(0, ...finished.map(f => f.done)) > 700, 'the reading done: ' + label, 300); + await settled(label); +} +/** Waits until nothing reads: no "Reading…", the main area and the viewer not busy. */ +async function settled(label) { + await until(() => evaluate(`(() => { const reading = e => [...e.querySelectorAll('.note')].some(n => n.textContent === 'Reading…'); const v = document.querySelector('#main .viewer'); return !reading(document.getElementById('main')) && !reading(document.getElementById('aside')) && !document.getElementById('main').hasAttribute('aria-busy') && !(v && v.hasAttribute('aria-busy')); })()`), 'settled: ' + label); + await pause(150); +} +async function hash(value) { await evaluate(`location.hash = ${JSON.stringify('#' + value)}`); await settled('#' + value); await pause(200); await settled('#' + value); } +const byKey = key => `[data-key=${JSON.stringify(key)}]`; +let moved = 0; // presses whose target was not under its point when measured (the layout moved between); counted, then measured again +async function centre(selector) { + for (;;) { + const at = await until(() => evaluate(`(() => { const e = [...document.querySelectorAll(${JSON.stringify(selector)})].find(e => e.offsetParent !== null); if (!e) return null; e.scrollIntoView({ block: 'nearest', inline: 'nearest' }); const r = e.getBoundingClientRect(), x = r.left + r.width / 2, y = r.top + r.height / 2, hit = document.elementFromPoint(x, y); return { x, y, ok: !!hit && (hit === e || e.contains(hit)) }; })()`), 'shown: ' + selector, 100); + if (at.ok) return at; + if (++moved > 20) throw Error('The target of ' + selector + ' is never under its point'); + await pause(100); + } +} +async function mouse(type, x, y, buttons = 0) { await send('Input.dispatchMouseEvent', { type, x, y, button: type === 'mouseMoved' ? (buttons ? 'left' : 'none') : 'left', buttons, clickCount: type === 'mouseMoved' ? 0 : 1 }); } +async function press(selector) { const { x, y } = await centre(selector); await mouse('mouseMoved', x, y); await mouse('mousePressed', x, y, 1); await mouse('mouseReleased', x, y); } +async function key(name, code) { for (const type of ['rawKeyDown', 'keyUp']) await send('Input.dispatchKeyEvent', { type, key: name, code: name, windowsVirtualKeyCode: code, nativeVirtualKeyCode: code }); } +async function shot(name) { + await evaluate('new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve)))'); + const png = Buffer.from((await send('Page.captureScreenshot', { format: 'png', captureBeyondViewport: false })).data, 'base64'); + fs.writeFileSync(path.join(report, name + '.png'), png); if (shots) fs.writeFileSync(path.join(shots, name + '.png'), png); +} +/** What a canvas shows: how many pixels are drawn, how many colours, and a sum that changes when the drawing does. */ +const pixels = selector => evaluate(`(() => { const c = document.querySelector(${JSON.stringify(selector)}); if (!c || !c.width) return null; const d = c.getContext('2d').getImageData(0, 0, c.width, c.height).data; let drawn = 0, sum = 0; const colours = new Set(); for (let i = 0; i < d.length; i += 4) if (d[i + 3]) { drawn++; sum = (sum + (i / 4 + 1) * (d[i] * 3 + d[i + 1] * 5 + d[i + 2] * 7)) % 2147483647; if (colours.size < 64) colours.add(d[i] + ',' + d[i + 1] + ',' + d[i + 2]); } return { drawn, colours: colours.size, sum, label: c.getAttribute('aria-label') || '' }; })()`); +/** Selects a record by its tile and waits for its viewer. */ +async function open(id) { + await press(`#main .rec${byKey('rec-' + id)}`); + await until(() => evaluate(`(() => { const v = document.querySelector('#main .viewer'); const t = v && v.querySelector('.iv-head h3'); return !!t && t.textContent === ${JSON.stringify(id)} && !v.hasAttribute('aria-busy'); })()`), 'the viewer of ' + id); + await settled(id); +} +/** The value under the pointer at a cell (row, column) of the slice drawn: moves the mouse there and reads the probe. */ +async function probe(row, col) { + const at = await evaluate(`(() => { const c = document.querySelector('#main .viewer canvas.iv-heat'); c.scrollIntoView({ block: 'nearest' }); const [rect, grid] = c.dataset.cells.split(';'), [x, y, w, h] = rect.split(',').map(Number), [rows, cols] = grid.split('x').map(Number); const r = c.getBoundingClientRect(), kx = r.width / c.width, ky = r.height / c.height; return { x: r.left + (x + (${col} + 0.5) * w / cols) * kx, y: r.top + (y + (${row} + 0.5) * h / rows) * ky }; })()`); + await mouse('mouseMoved', at.x, at.y); + return until(() => evaluate(`(() => { const p = document.querySelector('#main .viewer .iv-probe'); return p && p.dataset.index ? { index: JSON.parse(p.dataset.index), value: Number(p.dataset.value), text: p.textContent } : null; })()`), 'a value under the pointer'); +} +async function drag(selector) { + const { x, y } = await centre(selector); + await mouse('mouseMoved', x, y); await mouse('mousePressed', x, y, 1); + for (let i = 1; i <= 6; i++) await mouse('mouseMoved', x + i * 14, y + i * 5, 1); + await mouse('mouseReleased', x + 84, y + 30); + await evaluate('new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve)))'); +} + +// The watcher of browser_project_workspace_still.cjs: added, removed and changed nodes, "Reading…", the scrolls. +const WATCHER = `window.__still = (() => { + const ids = ['tabs', 'strip', 'main', 'aside', 'needs-panel'], el = id => document.getElementById(id); + let counts = null, flash = 0, timer = null; + const name = n => !n ? '?' : n.nodeType === 1 ? n.tagName.toLowerCase() + (typeof n.className === 'string' && n.className ? '.' + n.className.trim().split(/\\s+/).join('.') : '') : '#text ' + JSON.stringify(String(n.data || '').slice(0, 30)); + for (const id of ids) new MutationObserver(list => { + if (!counts) return; + const c = counts[id]; + for (const r of list) { + if (r.type === 'childList') { c.added += r.addedNodes.length; c.removed += r.removedNodes.length; for (const n of [...r.addedNodes, ...r.removedNodes]) if (c.what.length < 6) c.what.push(name(n) + ' in ' + name(r.target)); } + else if (r.type === 'characterData') { const msg = el('strip').querySelector('.msg'); if (msg && r.target === msg.lastChild) c.readAt++; else { c.text++; if (c.what.length < 6) c.what.push('text of ' + name(r.target.parentNode)); } } + else { c.attrs++; if (c.what.length < 6) c.what.push('@' + r.attributeName + ' on ' + name(r.target)); } + } + }).observe(el(id), { childList: true, subtree: true, characterData: true, attributes: true }); + const where = (e, top) => { const p = []; while (e && e !== top) { p.unshift(e.tagName.toLowerCase() + ':' + [...e.parentElement.children].indexOf(e)); e = e.parentElement; } return p.join('>'); }; + function scrolls() { + const main = el('main'), out = { main: [main.scrollLeft, main.scrollTop].map(Math.round) }; + for (const e of main.querySelectorAll('*')) if (e.scrollLeft || e.scrollTop) out['main ' + where(e, main)] = [Math.round(e.scrollLeft), Math.round(e.scrollTop)]; + return out; + } + return { + start() { counts = {}; for (const id of ids) { counts[id] = { added: 0, removed: 0, attrs: 0, text: 0, readAt: 0, what: [] }; for (const e of el(id).querySelectorAll('*')) e.__seen = 1; } flash = 0; clearInterval(timer); timer = setInterval(() => { if ((el('main').textContent + el('aside').textContent).includes('Reading…')) flash++; }, 50); }, + stop() { clearInterval(timer); const fresh = {}; for (const id of ids) fresh[id] = [...el(id).querySelectorAll('*')].filter(e => !e.__seen).length; const r = { counts, flash, fresh, scrolls: scrolls() }; counts = null; return r; }, + scrolls + }; +})(); true`; +const touched = (r, ids) => ids.filter(id => { const c = r.counts[id]; return c.added || c.removed || c.attrs || c.text || r.fresh[id]; }).map(id => id + ' ' + JSON.stringify(r.counts[id]) + ' new ' + r.fresh[id]); + +(async () => { + // ---- The fixture: minimal + buildable + datasets/specimens, in Git; the specimens built ------------------------------ + fs.cpSync(path.join(root, 'tests', 'fixtures', 'tuldok_project', 'minimal'), path.join(temporary, 'fixture'), { recursive: true }); + const folder = path.join(temporary, 'fixture', 'project'), code = path.join(temporary, 'fixture', 'code'), buildable = path.join(root, 'tests', 'fixtures', 'tuldok_project', 'buildable'); + for (const kind of ['environments', 'datasets', 'recipes', 'benchmarks', 'charts']) for (const name of fs.readdirSync(path.join(buildable, 'project', kind))) fs.copyFileSync(path.join(buildable, 'project', kind, name), path.join(folder, kind, name)); + for (const name of fs.readdirSync(path.join(buildable, 'code'))) fs.cpSync(path.join(buildable, 'code', name), path.join(code, name), { recursive: true }); + fs.copyFileSync(path.join(root, 'tests', 'project_inside_browser_fixture.py'), path.join(code, 'make_specimens.py')); + fs.writeFileSync(path.join(folder, 'datasets', 'specimens.json'), JSON.stringify({ format: 'tuldok_definition_v1', kind: 'dataset', title: 'Specimens of every kind', + description: 'One record of every kind and more, for looking inside.', run: { command: ['python', 'make_specimens.py', '--out', '{output}'], environment: 'environments/test-python', sources: ['make_specimens.py'] } }, null, 2) + '\n'); + const git = ['-c', 'user.name=Tuldok Test', '-c', 'user.email=test@example.invalid', '-c', 'commit.gpgsign=false', '-c', 'init.defaultBranch=main', '-C', path.join(temporary, 'fixture')]; + execFileSync('git', [...git, 'init', '-q']); execFileSync('git', [...git, 'add', '-A']); execFileSync('git', [...git, 'commit', '-q', '-m', 'The fixture.']); + const home = path.join(temporary, 'home'), catalog = path.join(temporary, 'catalog'); fs.mkdirSync(home); + const env = { ...process.env, TULDOK_PROJECT_HOME: home, TULDOK_SETTINGS: path.join(temporary, 'settings.json') }; + owned = [folder, catalog]; dropOwned(folder, catalog); + const cli = (...args) => execFileSync(python, ['-m', 'tuldok_project', ...args], { cwd: root, env, stdio: ['ignore', 'pipe', 'pipe'] }).toString(); + cli('connect', folder, 'test-python', python); + cli('build', folder, REF, '--yes'); + let output = ''; + server = launch(python, ['-u', 'app.py', '--port', '0', '--data', catalog, '--project-folder', folder], { cwd: root, env, stdio: ['ignore', 'pipe', 'pipe'] }); + server.stdout.on('data', chunk => { output += chunk; }); server.stderr.on('data', chunk => { serverErrors += chunk; }); + const port = await until(() => { if (server.exitCode !== null) throw Error('Tuldok exited: ' + serverErrors); return output.match(/127\.0\.0\.1:(\d+)/)?.[1]; }, 'Tuldok start-up', 3000); + origin = 'http://127.0.0.1:' + port; + auth = authenticatedFixture(); await auth.register(origin, catalog, root); + const product = (await api('products', { reference: REF })).products[0], run = product.run_id, out = product.directory; + const datasets = (await api('definitions', { kind: 'dataset' })).definitions.filter(d => !d.removed).map(d => d.reference); + const withProduct = new Set((await api('products')).products.map(p => p.reference)); + const without = datasets.filter(d => !withProduct.has(d)); + assert.ok(without.length > 0, 'The fixture has a dataset without a product'); + + const browser = launch(findBrowser(), ['--headless', '--no-sandbox', '--disable-gpu', '--no-first-run', '--hide-scrollbars', '--autoplay-policy=no-user-gesture-required', '--remote-debugging-port=0', '--window-size=1440,900', '--user-data-dir=' + path.join(temporary, 'browser'), 'about:blank'], { stdio: 'ignore', env: { ...process.env, XDG_CONFIG_HOME: temporary, XDG_CACHE_HOME: temporary } }); + const debugPort = await waitForDebugger(browser, path.join(temporary, 'browser', 'DevToolsActivePort')); + const target = (await (await fetch('http://127.0.0.1:' + debugPort + '/json')).json()).find(item => item.type === 'page'); + socket = new WebSocket(target.webSocketDebuggerUrl); await once(socket, 'open'); + session = cdpSession(socket, { timeoutMs: 60000, onEvent: event => { + network(event); + if (event.method === 'Runtime.exceptionThrown') errors.push(event.params.exceptionDetails.exception?.description || event.params.exceptionDetails.text); + if (event.method === 'Runtime.consoleAPICalled' && event.params.type === 'error') errors.push(event.params.args.map(a => a.value ?? a.description).join(' ')); + if (event.method === 'Log.entryAdded' && event.params.entry.level === 'error' && !/\/api\/project\/array_slice/.test(event.params.entry.url || '')) errors.push(event.params.entry.text + ' ' + (event.params.entry.url || '')); + if (event.method === 'Network.loadingFailed' && !event.params.canceled) failures.push({ id: event.params.requestId, error: event.params.errorText }); + if (event.method === 'Network.responseReceived' && event.params.response.status >= 400) { + // The array Tuldok refuses (arrays/complex.npy) is asked for by its tile and its viewer: those refusals are expected. + if (event.params.response.status === 409 && /\/api\/project\/array_slice$/.test(event.params.response.url)) refusedOk.push(event.params.response.url); + else failures.push({ url: event.params.response.url, status: event.params.response.status }); + } + } }); + send = session.send; + evaluate = async expression => { const result = await send('Runtime.evaluate', { expression, awaitPromise: true, returnByValue: true }); if (result.exceptionDetails) throw Error(JSON.stringify(result.exceptionDetails)); return result.result.value; }; + await send('Page.enable'); await send('Runtime.enable'); await send('Network.enable'); await send('Log.enable'); + const size = async (width, height) => send('Emulation.setDeviceMetricsOverride', { width, height, deviceScaleFactor: 1, mobile: false }); + const theme = async name => { await send('Emulation.setEmulatedMedia', { features: [{ name: 'prefers-color-scheme', value: name }, { name: 'prefers-reduced-motion', value: 'reduce' }] }); }; + await size(1440, 900); await theme('light'); + await auth.browser(send, origin); // the owner's session + const load = async (name, place) => { + await theme(name); + await send('Page.navigate', { url: 'about:blank' }); await pause(100); // a page of its own, not a change of hash + await send('Page.navigate', { url: origin + '/?theme=' + name + '#' + place }); + await until(() => evaluate(`document.readyState === 'complete' && !!document.getElementById('needs-btn') && !document.getElementById('needs-btn').disabled`), 'the project read', 1200); + await settled('opened ' + place); + }; + await load('light', 'data'); + // For a failure's report: when the main area's scroll went back to 0, and what it showed then. + await evaluate(`(() => { const m = document.getElementById('main'); window.__resets = []; let last = 0; m.addEventListener('scroll', () => { if (last > 50 && m.scrollTop === 0) window.__resets.push('from ' + last + ', height ' + m.scrollHeight + '/' + m.clientHeight + ' at ' + Math.round(performance.now()) + ' ms, ' + ((document.querySelector('#main .inside-list .sect .sum') || {}).textContent || '')); last = m.scrollTop; }); return true; })()`); + + // ---- 1. The cards, the dataset opened, the pager and a filter ---------------------------------------------------- + const looks = await evaluate(`[...document.querySelectorAll('#main .ds-item')].map(i => ({ ref: i.querySelector('.ds-card').dataset.ref, look: !!i.querySelector('[data-key^="inside-"]') }))`); + assert.ok(looks.find(x => x.ref === REF).look, '"Look inside" on the dataset with a product'); + for (const ref of without) assert.equal(looks.find(x => x.ref === ref).look, false, 'No "Look inside" on ' + ref + ', which has no product'); + await shot('light-1440-data-cards'); + await press(byKey('inside-' + REF)); + await until(() => evaluate(`location.hash === ${JSON.stringify('#' + OPENED)}`), 'the dataset opened'); await settled('the dataset opened'); + const grid = await evaluate(`({ tiles: document.querySelectorAll('#main .rec').length, sum: document.querySelector('#main .inside-list .sect .sum').textContent, chips: Object.fromEntries([...document.querySelectorAll('#main [data-key^="inside-kind-"]')].map(b => [b.dataset.key.slice('inside-kind-'.length), Number(b.textContent.split('·')[1].replace(/\\D/g, ''))])), title: document.querySelector('#main .ds-head h2').textContent, meta: document.querySelector('#main .ds-head .meta').textContent })`); + assert.equal(grid.tiles, 48, '48 tiles on the first page'); + assert.equal(grid.sum, '1–48 of ' + TOTAL); + assert.deepEqual(grid.chips, Object.assign({ all: TOTAL }, KINDS), 'The counts by kind are the fixture\'s'); + assert.equal(grid.title, 'Specimens of every kind'); assert.match(grid.meta, new RegExp('run ' + run.slice(0, 8))); + // Every tile carries its record's id; tiles never jump: each is a square picture and a line. + const ids = await evaluate(`[...document.querySelectorAll('#main .rec')].map(t => t.dataset.id)`); + const listed = (await api('records', { run, limit: 48 })).records.map(r => r.id); + assert.deepEqual(ids, listed, 'The tiles are the first page of records, in order'); + await press(byKey('inside-next')); + await until(() => evaluate(`document.querySelector('#main .inside-list .sect .sum').textContent.startsWith('49')`), 'page 2 drawn'); await settled('page 2'); + const second = await evaluate(`({ tiles: document.querySelectorAll('#main .rec').length, sum: document.querySelector('#main .inside-list .sect .sum').textContent, ids: [...document.querySelectorAll('#main .rec')].map(t => t.dataset.id) })`); + assert.equal(second.tiles, TOTAL - 48); assert.equal(second.sum, '49–' + TOTAL + ' of ' + TOTAL); + assert.deepEqual(second.ids, (await api('records', { run, offset: 48, limit: 48 })).records.map(r => r.id), 'The pager reaches the rest'); + await press(byKey('inside-prev')); await settled('page 1'); + await press(byKey('inside-kind-mesh')); await settled('meshes'); + const meshes = await evaluate(`[...document.querySelectorAll('#main .rec')].map(t => t.dataset.kind + ' ' + t.dataset.id)`); + assert.deepEqual(meshes, ['mesh meshes/cube.obj', 'mesh meshes/sphere.stl', 'mesh meshes/terrain.ply'], 'The kind filter narrows the grid'); + await press(byKey('inside-kind-all')); await settled('all'); + assert.equal(await evaluate(`document.querySelectorAll('#main .rec').length`), 48); + check('1. "Look inside" on ' + REF + ' and on none of ' + without.join(', ') + '; opened at #' + OPENED + ' to 48 tiles of ' + TOTAL + ' with the counts ' + JSON.stringify(grid.chips) + '; Next showed ' + second.tiles + ' more (' + second.sum + '); Mesh narrowed the grid to ' + meshes.length); + + // ---- 2. Each kind's viewer ------------------------------------------------------------------------------------------- + const note = 'texts/note-03.txt', expected = fs.readFileSync(path.join(out, note), 'utf8'); + await open(note); + const text = await evaluate(`({ text: document.querySelector('#main .viewer .iv-text').textContent, line: document.querySelector('#main .viewer .iv > p.small.muted').textContent })`); + assert.equal(text.text, expected, 'The text shown is the file\'s'); + // Left and right arrows move the selection (the focus on a tile). + await evaluate(`document.querySelector('#main .rec[aria-pressed="true"]').focus(); true`); + await key('ArrowRight', 39); + await until(() => evaluate(`document.querySelector('#main .rec[aria-pressed="true"]').dataset.id === 'texts/note-04.txt' && document.activeElement.dataset.id === 'texts/note-04.txt' && document.querySelector('#main .viewer .iv-head h3').textContent === 'texts/note-04.txt'`), 'the right arrow selects the next record'); + await key('ArrowLeft', 37); + await until(() => evaluate(`document.querySelector('#main .viewer .iv-head h3').textContent === ${JSON.stringify(note)}`), 'the left arrow selects it back'); + await settled('arrows'); + + await open('images/gradient.png'); + const image = await until(() => evaluate(`(() => { const i = document.querySelector('#main .viewer .iv-img img'); return i && i.complete && i.naturalWidth ? { w: i.naturalWidth, h: i.naturalHeight, alt: i.alt, src: i.getAttribute('src'), size: i.closest('.iv').querySelector(':scope > p.small').textContent } : null; })()`), 'the image decoded'); + const imageRecord = (await api('record', { run, id: 'images/gradient.png' })).record; + assert.deepEqual([image.w, image.h], [37, 23], 'The image is decoded at its true size'); + assert.equal(image.src, imageRecord.url, 'The image\'s src is the url the record operation gives'); + await press('#main .viewer .iv-img'); assert.ok(await evaluate(`document.querySelector('#main .viewer .iv-img').classList.contains('actual')`), 'A press shows the actual size'); + await press('#main .viewer .iv-img'); + + await open('sounds/tone.wav'); + const sound = await until(() => evaluate(`(() => { const a = document.querySelector('#main .viewer audio'); return a && a.readyState >= 1 && Number.isFinite(a.duration) ? { duration: a.duration, src: a.getAttribute('src'), error: a.error && a.error.code } : null; })()`), 'the sound\'s metadata'); + assert.ok(Math.abs(sound.duration - 1.5) < 0.01, 'The sound lasts 1.5 s: ' + sound.duration); + assert.equal(sound.src, (await api('record', { run, id: 'sounds/tone.wav' })).record.url); + const played = await evaluate(`(async () => { const a = document.querySelector('#main .viewer audio'); a.muted = true; await a.play(); await new Promise(r => setTimeout(r, 400)); const t = a.currentTime; a.pause(); a.currentTime = 0; return t; })()`); + assert.ok(played > 0, 'The sound plays: ' + played); + const wave = await pixels('#main .viewer canvas.iv-wave'); + assert.ok(wave && wave.drawn > 200 && wave.colours >= 2, 'The waveform is drawn: ' + JSON.stringify(wave)); + + const turned = {}; + for (const id of ['clouds/helix.ply', 'meshes/sphere.stl', 'meshes/cube.obj']) { + await open(id); + const before = await pixels('#main .viewer canvas.iv-3d'); + assert.ok(before && before.drawn > 500 && before.colours >= 2, id + ' is drawn: ' + JSON.stringify(before)); + await drag('#main .viewer canvas.iv-3d'); + const after = await pixels('#main .viewer canvas.iv-3d'); + assert.notEqual(after.sum, before.sum, id + ' changes when dragged'); + await press(byKey('iv-reset')); await evaluate('new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve)))'); + assert.equal((await pixels('#main .viewer canvas.iv-3d')).sum, before.sum, id + ': Reset view draws it as at first'); + turned[id] = before.label.split('.')[0] + ' (' + before.drawn + ' pixels, ' + after.drawn + ' after a drag)'; + } + await open('meshes/terrain.ply'); + const terrain = await evaluate(`({ line: document.querySelector('#main .viewer .iv > p.small.muted').textContent, label: document.querySelector('#main .viewer canvas.iv-3d').getAttribute('aria-label') })`); + assert.match(terrain.line, /61,250 triangles · above 60,000 triangles the vertices are drawn as points/); assert.match(terrain.label, /drawn as its 30,976 vertices as points/); + assert.ok((await pixels('#main .viewer canvas.iv-3d')).drawn > 500, 'The large mesh is drawn as points'); + + await open('arrays/field.npy'); + const f = ([i, j, k]) => i * 10000 + j * 100 + k; + const p1 = await probe(7, 11); + assert.deepEqual(p1.index, [3, 7, 11], 'The middle slice along axes 1 and 2'); assert.equal(p1.value, f(p1.index), 'The value under the pointer is the fixture\'s'); + const vol = await pixels('#main .viewer canvas.iv-vol'); + assert.ok(vol && vol.drawn > 500 && vol.colours > 4, 'The stacked slices are drawn: ' + JSON.stringify(vol)); + await evaluate(`document.querySelector('#main .viewer [data-key="iv-axis-slider-0"]').focus(); true`); + await key('ArrowRight', 39); + await until(() => evaluate(`document.querySelector('#main .viewer canvas.iv-heat').dataset.index === '[4,6,8]'`), 'the slider moves the slice'); + const p2 = await probe(2, 5); + assert.deepEqual(p2.index, [4, 2, 5]); assert.equal(p2.value, f(p2.index), 'After the slider the value is the fixture\'s at the new place'); + const vol1 = await pixels('#main .viewer canvas.iv-vol'); + assert.notEqual(vol1.sum, vol.sum, 'The stacked slices outline the new slice'); + await press(byKey('iv-hist')); + await until(() => evaluate(`!!document.querySelector('#main .viewer canvas.iv-histc')`), 'the histogram'); + const hist = await pixels('#main .viewer canvas.iv-histc'); assert.ok(hist.drawn > 100, 'The histogram is drawn'); + const mean = await evaluate(`[...document.querySelectorAll('#main .viewer .iv-hist dt')].find(d => d.textContent === 'Mean').nextElementSibling.textContent`); + await open('arrays/pair.npz'); + const pair = await probe(3, 4); + assert.deepEqual(pair.index, [3, 4]); assert.equal(pair.value, Math.fround(3 - 4 / 10), 'The npz\'s array shown first is velocity, with the fixture\'s values'); + + await open('arrays/complex.npy'); + const refusal = await evaluate(`document.querySelector('#main .viewer .refusal p').textContent`); + const answered = await api('array_slice', { run, path: 'arrays/complex.npy', most: 256 }, true); + assert.equal(answered.code, 'unsupported'); assert.equal(refusal, answered.error, 'The refusal is the server\'s sentence'); + assert.ok(await evaluate(`document.querySelector('#main .rec[data-id="arrays/complex.npy"]').classList.contains('refused')`), 'Its tile shows it is refused'); + await open('misc/blob.bin'); + assert.match(await evaluate(`document.querySelector('#main .viewer .iv .note').textContent`), /listed, never opened/); + await open('arrays/field.npy'); // the grid stays usable after a refusal + check('2. Viewers: the text of ' + note + ' equals the file (' + text.line + '); the arrows moved the selection; the image decoded at ' + image.w + ' × ' + image.h + ' from the record\'s url; the sound lasts ' + sound.duration + ' s and played to ' + played.toFixed(2) + ' s, its waveform drawn; ' + Object.values(turned).join('; ') + ', each changed when dragged and came back with Reset view; meshes/terrain.ply: "' + terrain.line + '"; arrays/field.npy read ' + JSON.stringify(p1.index) + ' = ' + p1.value + ', then after the slider ' + JSON.stringify(p2.index) + ' = ' + p2.value + ', its stacked slices and histogram (mean ' + mean + ') drawn; pair.npz showed velocity ' + JSON.stringify(pair.index) + ' = ' + pair.value + '; arrays/complex.npy showed "' + refusal + '"'); + + // ---- 3. Files: the tree, the archive, an array inside it ----------------------------------------------------------- + await press(byKey('inside-mode-files')); await settled('files'); + const top = await evaluate(`[...document.querySelectorAll('#main .tree-entry')].map(b => b.dataset.path + ':' + b.dataset.type)`); + assert.deepEqual(top, (await api('inside', { run })).entries.map(e => e.path + ':' + e.type), 'Files lists the product\'s top'); + await press(byKey('entry-bundles')); await settled('bundles'); + await press(byKey('entry-bundles/training-view.zip')); await settled('the archive'); + const inArchive = await evaluate(`[...document.querySelectorAll('#main .tree-entry')].map(b => b.dataset.path + ':' + b.dataset.type)`); + assert.deepEqual(inArchive, ['bundles/training-view.zip!samples:directory', 'bundles/training-view.zip!readme.txt:file'], 'The archive opens to its members'); + await press(byKey('entry-bundles/training-view.zip!samples')); await settled('samples'); + await press(byKey('entry-bundles/training-view.zip!samples/s1.npz')); await settled('s1.npz'); + const crumbs = await evaluate(`document.querySelector('#main .crumbs').textContent`); + await press(byKey('entry-bundles/training-view.zip!samples/s1.npz#target')); + await until(() => evaluate(`!!document.querySelector('#main .viewer canvas.iv-heat') && !document.querySelector('#main .viewer').hasAttribute('aria-busy')`), 'the array inside the archive'); await settled('target'); + const inner = await probe(5, 7); + assert.deepEqual(inner.index, [5, 7]); assert.equal(inner.value, 1000 + 5 * 10 + 7, 'The value inside the archive is the fixture\'s'); + await press(byKey('crumb-bundles/training-view.zip')); await settled('back up'); + await press(byKey('entry-bundles/training-view.zip!readme.txt')); await settled('readme'); + const readme = await evaluate(`document.querySelector('#main .viewer .iv .note').textContent`); + check('3. Files listed ' + top.length + ' entries at the top; the archive opened to ' + inArchive.length + ' members; "' + crumbs.replace(/\s+/g, ' ') + '" listed target, whose value at ' + JSON.stringify(inner.index) + ' is ' + inner.value + '; a text inside the archive says: "' + readme + '"'); + + // ---- 4. Nothing changed: the window regains focus, the timer reads ------------------------------------------------- + await press(byKey('inside-mode-records')); await settled('records'); + await open('clouds/helix.ply'); + await until(() => evaluate(`[...document.querySelectorAll('#main .rec[data-lazy]')].every(t => { const r = t.getBoundingClientRect(); return r.top > innerHeight || r.bottom < 0 || !t.querySelector('svg.glyph:not(.refused)'); })`), 'the tiles in view filled'); + await pause(300); + await evaluate(WATCHER); + const rows = []; + for (const cause of ['focus', 'timer']) { + const before = await evaluate(`window.__still.scrolls()`), since = Date.now(); + await evaluate(`window.__still.start(); true`); + if (cause === 'focus') { await evaluate(`window.dispatchEvent(new Event('focus')); true`); await reading(since, WATCHED.concat(['map']), 'focus'); } + else await reading(since, WATCHED, 'the timer', Math.round((IDLE_MS + 15000) / 100)); + const r = await evaluate(`window.__still.stop()`); + assert.deepEqual(touched(r, ['tabs', 'strip', 'main', 'aside', 'needs-panel']), [], cause + ': nothing is touched'); + assert.equal(r.flash, 0, cause + ': "Reading…" is never shown'); assert.deepEqual(r.scrolls, before, cause + ': every scroll stays'); + rows.push(cause + ': 0 nodes added or removed, 0 changed' + (r.counts.strip.readAt ? ' ("Read at" ticked)' : '')); + } + check('4. With ' + REF + ' open and clouds/helix.ply selected: ' + rows.join('; ')); + // Something changed elsewhere (an agent asks for a build, which awaits approval): the view is drawn again in place, its page and selection kept. + await press(byKey('inside-next')); await settled('page 2'); + const picked = second.ids[3]; await open(picked); + const before4 = await evaluate(`({ sum: document.querySelector('#main .inside-list .sect .sum').textContent, scroll: document.getElementById('main').scrollTop })`); + const since4 = Date.now(); await evaluate(`window.__still.start(); true`); + const asked = await api('request_build', { targets: ['recipes/fit-b'] }, false, await credential('A second session', ['inspect', 'execute'])); + assert.equal(asked.state, 'awaiting-approval'); + await evaluate(`window.dispatchEvent(new Event('focus')); true`); await reading(since4, WATCHED.concat(['map', 'records', 'record']), 'a request elsewhere'); + const r4 = await evaluate(`window.__still.stop()`); + const after4 = await evaluate(`({ sum: document.querySelector('#main .inside-list .sect .sum').textContent, scroll: document.getElementById('main').scrollTop, pressed: document.querySelector('#main .rec[aria-pressed="true"]').dataset.id, viewer: document.querySelector('#main .viewer .iv-head h3').textContent })`); + assert.ok(r4.fresh.main > 0, 'The view was drawn again: ' + JSON.stringify(r4.counts.main)); + assert.equal(r4.flash, 0, '"Reading…" is never shown when the view is drawn again'); + assert.deepEqual([after4.sum, after4.scroll, after4.pressed, after4.viewer], [before4.sum, before4.scroll, picked, picked], 'The page, the scroll and the selection are kept'); + check('4. An agent asked for a build elsewhere: the opened view was read and drawn again in place (' + r4.fresh.main + ' new nodes), still at ' + after4.sum + ' with ' + picked + ' selected, no "Reading…"'); + + // ---- 5. Light and dark, two sizes: nothing blank; the screenshots --------------------------------------------------------- + const VIEWERS = [['text', 'texts/note-03.txt'], ['image', 'images/gradient.png'], ['audio', 'sounds/tone.wav'], ['pointcloud', 'clouds/helix.ply'], ['mesh', 'meshes/sphere.stl'], ['mesh-points', 'meshes/terrain.ply'], ['array', 'arrays/field.npy'], ['refused', 'arrays/complex.npy'], ['file', 'misc/blob.bin']]; + const seen = []; + for (const [w, hgt] of [[1440, 900], [1000, 800]]) for (const name of ['light', 'dark']) { + await size(w, hgt); await load(name, OPENED); + const tag = name + '-' + w; + await shot(tag + '-dataset'); + for (const [kind, id] of VIEWERS) { + await open(id); + if (kind === 'array') { await press(byKey('iv-hist')); await until(() => evaluate(`!!document.querySelector('#main .viewer canvas.iv-histc')`), 'the histogram'); await probe(7, 11); } + const blank = await evaluate(`(() => { const v = document.querySelector('#main .viewer .iv'); const cs = [...v.querySelectorAll('canvas')].map(c => { if (!c.width) return 0; const d = c.getContext('2d').getImageData(0, 0, c.width, c.height).data; let n = 0; for (let i = 3; i < d.length; i += 4) if (d[i]) n++; return n; }); const img = v.querySelector('img'); return { canvases: cs, text: v.innerText.trim().length, image: img ? img.naturalWidth : null }; })()`); + assert.ok(blank.text > 0, tag + ' ' + kind + ': the viewer says something'); + assert.ok(blank.canvases.every(n => n > 50), tag + ' ' + kind + ': no blank canvas ' + JSON.stringify(blank.canvases)); + if (kind === 'image') assert.equal(blank.image, 37); + // Nothing overflows sideways: the page, the main area, the viewer. + const over = await evaluate(`(() => { const m = document.getElementById('main'), v = document.querySelector('#main .viewer'); return { page: document.documentElement.scrollWidth - innerWidth, main: m.scrollWidth - m.clientWidth, viewer: v.scrollWidth - v.clientWidth }; })()`); + assert.ok(over.page <= 0 && over.main <= 1 && over.viewer <= 1, tag + ' ' + kind + ': sideways overflow ' + JSON.stringify(over)); + // The viewer from its top; an array's also from its end (the value under the pointer and the histogram). + await evaluate(`(() => { const v = document.querySelector('#main .viewer'); v.scrollTop = 0; v.scrollIntoView({ block: 'start' }); return true; })()`); + await shot(tag + '-' + kind); + if (kind === 'array') { await evaluate(`(() => { const v = document.querySelector('#main .viewer'); v.scrollTop = v.scrollHeight; v.scrollIntoView({ block: 'end' }); return true; })()`); await shot(tag + '-array-end'); } + seen.push(tag + ' ' + kind + (blank.canvases.length ? ' ' + blank.canvases.length + ' canvas' + (blank.canvases.length > 1 ? 'es' : '') : '')); + } + await press(byKey('inside-mode-files')); await settled('files'); + await press(byKey('entry-arrays')); await settled('arrays'); await press(byKey('entry-arrays/pair.npz')); await settled('pair'); await press(byKey('entry-arrays/pair.npz#velocity')); await settled('velocity'); + await shot(tag + '-files'); + } + await size(1440, 900); + check('5. No viewer blank and nothing overflowing sideways in light and dark at 1440 × 900 and 1000 × 800 (' + seen.length + ' viewers: ' + seen.slice(0, VIEWERS.length).join(', ') + ', …)' + (shots ? '; screenshots in ' + shots : '')); + + // ---- Nothing failed --------------------------------------------------------------------------------------------------------- + assert.deepEqual(errors, [], 'Script errors'); + assert.deepEqual(failures, [], 'Failed requests'); + assert.ok(refusedOk.length > 0, 'The refused array was asked for'); + check('No script error, no failed request but the ' + refusedOk.length + ' refusals of arrays/complex.npy asked for' + (moved ? '; ' + moved + ' presses measured again because their target was not under its point' : '')); + fs.writeFileSync(path.join(report, 'receipt.json'), JSON.stringify({ status: 'pass', folder, checks }, null, 2) + '\n'); + console.log('Receipt in ' + report); +})().catch(async error => { + process.exitCode = 1; + console.error(error); if (serverErrors) console.error('Server:', serverErrors.slice(-4000)); + console.error('Script errors:', JSON.stringify(errors)); console.error('Failed requests:', JSON.stringify(failures)); + try { if (evaluate) { console.error('Main scrolled back to 0:', JSON.stringify(await evaluate('window.__resets || null'))); await shot('failure'); console.error('Page:', (await evaluate('document.body.innerText')).slice(0, 2000)); } } catch (_) { /* the page is gone */ } + fs.writeFileSync(path.join(report, 'failure.json'), JSON.stringify({ status: 'failed', error: String(error && error.stack || error), checks, errors, failures }, null, 2) + '\n'); +}).finally(async () => { + try { session?.close(); } catch (_) { /* closed */ } + for (const child of children.reverse()) await stop(child); + if (owned) try { dropOwned(...owned); } catch (error) { console.error('Dropping the disposable schemas failed:', error.message); process.exitCode = 1; } + try { execFileSync('chmod', ['-R', 'u+w', temporary]); } catch (_) { /* nothing was made read-only */ } // finished runs leave their directories read-only + fs.rmSync(temporary, { recursive: true, force: true }); +}); diff --git a/tests/project_inside_browser_fixture.py b/tests/project_inside_browser_fixture.py new file mode 100644 index 00000000..f52200b8 --- /dev/null +++ b/tests/project_inside_browser_fixture.py @@ -0,0 +1,179 @@ +"""The product the browser check of looking inside reads (tests/browser_project_workspace_inside.cjs). + +Run by a dataset's build as its command (``python make_specimens.py --out {output}``), it writes, with the +standard library only, at least one record of every kind and more than 48 records in all: texts, a PNG, a WAV, +point clouds in PLY and XYZ, meshes in OBJ, STL and PLY (one above 60,000 triangles), arrays in NPY and NPZ, a +zip archive holding an NPZ, and files of no kind. The values are made from formulas the check knows: + +- arrays/field.npy, float32 of shape (6, 12, 16): element (i, j, k) is i * 10000 + j * 100 + k; +- arrays/pair.npz: ``velocity``, float32 (20, 30), element (j, k) is j - k / 10; ``mask``, uint8 (30,); +- bundles/training-view.zip: samples/s0.npz and samples/s1.npz (stored), each with ``target`` float32 (8, 10), + element (j, k) is s * 1000 + j * 10 + k, and readme.txt; +- arrays/complex.npy: complex64, which Tuldok lists and refuses to read (unsupported); +- images/gradient.png: 37 by 23 pixels; sounds/tone.wav: 16-bit mono, 8,000 Hz, 1.5 s (12,000 frames). + +57 records in all: text 45, image 1, audio 1, pointcloud 2, mesh 3, array 3, file 2. +""" +import argparse +import io +import math +import os +import struct +import wave +import zipfile +import zlib + + +def npy(shape, code, value): + """The bytes of a little-endian, C-ordered NPY of version 1 whose element at an index is value(index).""" + descr = {'f': 'I', len(data)) + kind + data + struct.pack('>I', zlib.crc32(kind + data)) + rows = b''.join(b'\x00' + b''.join(bytes([40 + 200 * x // width, 60 + 160 * y // height, 180]) for x in range(width)) + for y in range(height)) + return (b'\x89PNG\r\n\x1a\n' + chunk(b'IHDR', struct.pack('>IIBBBBB', width, height, 8, 2, 0, 0, 0)) + + chunk(b'IDAT', zlib.compress(rows)) + chunk(b'IEND', b'')) + + +def wav(seconds=1.5, rate=8000): + frames = int(seconds * rate) + samples = [int(12000 * math.sin(2 * math.pi * 330 * n / rate) * (0.3 + 0.7 * n / frames)) for n in range(frames)] + buffer = io.BytesIO() + with wave.open(buffer, 'wb') as sound: + sound.setnchannels(1) + sound.setsampwidth(2) + sound.setframerate(rate) + sound.writeframes(struct.pack(f'<{frames}h', *samples)) + return buffer.getvalue() + + +def helix(count): + out = [] + for n in range(count): + t = n / count * 6 * math.pi + r = 1 + 0.15 * math.sin(7 * t) + out.append((r * math.cos(t), r * math.sin(t), t / (2 * math.pi) - 1.5, + int(60 + 190 * n / count), 120, int(240 - 190 * n / count))) + return out + + +def ply_points(points): + lines = ['ply', 'format ascii 1.0', f'element vertex {len(points)}', 'property float x', 'property float y', + 'property float z', 'property uchar red', 'property uchar green', 'property uchar blue', 'end_header'] + lines += [f'{x:.5f} {y:.5f} {z:.5f} {r} {g} {b}' for x, y, z, r, g, b in points] + return ('\n'.join(lines) + '\n').encode() + + +def xyz_points(count): + lines = [] + for n in range(count): + u, v = n % 40 / 39, n // 40 / (count // 40) + lines.append(f'{u * 2 - 1:.4f} {v * 2 - 1:.4f} {0.4 * math.sin(4 * u) * math.cos(3 * v):.4f}') + return ('\n'.join(lines) + '\n').encode() + + +CUBE = [(0, 0, 0), (1, 0, 0), (1, 1, 0), (0, 1, 0), (0, 0, 1), (1, 0, 1), (1, 1, 1), (0, 1, 1)] +QUADS = [(0, 3, 2, 1), (4, 5, 6, 7), (0, 1, 5, 4), (2, 3, 7, 6), (1, 2, 6, 5), (0, 4, 7, 3)] + + +def obj_cube(): + lines = [f'v {x} {y} {z}' for x, y, z in CUBE] + lines += ['f ' + ' '.join(str(index + 1) for index in quad) for quad in QUADS] + return ('\n'.join(lines) + '\n').encode() + + +def stl_sphere(rings=14, segments=24): + def at(i, j): + theta, phi = math.pi * i / rings, 2 * math.pi * j / segments + return (math.sin(theta) * math.cos(phi), math.sin(theta) * math.sin(phi), math.cos(theta)) + triangles = [] + for i in range(rings): + for j in range(segments): + a, b, c, d = at(i, j), at(i + 1, j), at(i + 1, j + 1), at(i, j + 1) + if i > 0: + triangles.append((a, b, d)) + if i < rings - 1: + triangles.append((b, c, d)) + data = b'\x00' * 80 + struct.pack(' Date: Fri, 13 Nov 2026 17:07:34 -0700 Subject: [PATCH 072/131] docs(plan): ledger entry for the dataset view, the weights readers and annotation's server side Co-Authored-By: Claude Fable 5.2 --- .../execution-ledger.md | 26 +++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/docs/plans/definition-first-projects/execution-ledger.md b/docs/plans/definition-first-projects/execution-ledger.md index 179a7fed..bc73d68b 100644 --- a/docs/plans/definition-first-projects/execution-ledger.md +++ b/docs/plans/definition-first-projects/execution-ledger.md @@ -618,3 +618,29 @@ The tab bar was rebuilt with each of those, the strip on every reading, and the **Not verified:** a real Pumas endpoint; the schemas the release does not publish (four are the pre-release export, one is derived); what spec-d1's "As built" lists. The standards service the implementers' rules name answered "awaiting application publication" on 2026-11-13, so no standards text was read for these slices. **Next:** the page of phase 1 (the record grid and a viewer per kind), and phase 2 (weights by layer, [spec-d2.md](spec-d2.md)), both being built. + +## 2026-11-13 — data tools: looking inside a dataset (page), weights (server), annotation (server) + +**Commits** on `feat/definition-first-projects`, none pushed: the page of phase 1 `7d376b61`; the weights readers `dfbeb10e`; annotation tasks and their file of lines `eefa274e`; the working copy and its operations `68aad8fb`; the steps `import` and `freeze` `e2ae4bb2`; merged here as `7262e8b4`. Specs: [spec-d2.md](spec-d2.md), [spec-d4.md](spec-d4.md), [spec-d5.md](spec-d5.md) (phase 5, written, not built). + +**How.** Slices were built by agents in working trees of their own, several at once where they touched different files, and merged after review. Each "As built" section of the specs has what differs from the text and what was not verified. + +**Phase 1, the page** ([spec-d1.md](spec-d1.md), slice D1b). A dataset with a product opens to its records as a paged grid with a viewer per kind: text, image, sound with its waveform, point cloud and mesh turned by dragging, array as a slice with the stacked-slice drawing and histogram; and a Files view of the product. Checked by `tests/browser_project_workspace_inside.cjs`, with screenshots read in light and dark at two widths. + +**Open defect in it.** In the reviewer's twelve further runs of that check, one failed: the main area's scroll went back to its top once, in the first second after the dataset opened, with its content unchanged. The owner's one complaint about this page so far was a full reset where an update in place was wanted, so this is not accepted as a flake: it is being reproduced in a loop with every way of moving the scroll traced. Also open: the Files view cannot yet open a text, point cloud or mesh that is not one of the product's records. + +**Phase 2, server side** (slice D2a): a run's weights by layer, a comparison of two files tensor by tensor, an array as tiles, `.safetensors` read like `.npz`. A PyTorch pickle is listed with its reason and never opened. + +**Phase 4, server side** (slices D4a to D4c): the annotation task as an eighth kind of definition; its annotations as a file of lines in Git, tied to each record's content by a hash; the working copy in the database, written by Save, with conflicts handled as for definitions; five operations; and `import` and `freeze` as steps Tuldok itself runs as ordinary builds. + +**Changed in review:** + +- `array_summary` (phase 1) answered `Infinity` for 64-bit values too large to sum, which is not JSON; found by feeding the weights readers 20,000 corrupted files. An overflowing mean or deviation is null. +- A line file rewritten to the same size within one tick of the clock looked unchanged by size and time: the edit was not imported and Save would have written over it. A file's size and time are trusted only once its time is two seconds old; a test that writes such an edit fails without the rule. +- The annotation file module was checked with 2,800 random annotations of every task written and read back byte for byte, and 3,000 corrupted files; `import` on a directory holding links out of it, a loop, a named pipe and names that collide. + +**Tests on the merged branch:** project suite 689; agent interface 43 (4 skipped). The catalog profile's manifest is unchanged throughout. + +**Not verified:** what each spec's "As built" lists; a real `.safetensors` written by the library; a copy across file systems in `import`; the standards service was unavailable (see the entry above). + +**Next:** the cause of the scroll going back; the Weights block of a model's drawer; the Annotate tab with the Import and Freeze forms; then phase 5. From 8b7ff5256a8066f5bf935890beccc6abdcb75718 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Fri, 13 Nov 2026 17:35:16 -0700 Subject: [PATCH 073/131] feat(workspace): a model's weights in its drawer A model whose run produced weights gains a Weights block in its drawer: the file with its size and parameter count, the layers as a table with each one's shape, parameters and a small drawing of how its values are distributed (asked for only when the row comes on screen), and, on choosing what to compare with, how much each layer changed from the weights it started from or from the model it derives from. A layer that started at zero says so. A tensor opens to its statistics, its distribution, and its values as images: one image for two dimensions, tiles across an axis for a kernel, with sliders for the other axes and paging; when comparing, this file, the other, or their difference. A file that is not .npz or .safetensors shows why it is not opened. Canvas 2D, no library, light and dark. Nothing is redrawn by a timer or a return to the window; a reading that changed something redraws the drawer in place with the comparison, the opened tensor and the scroll kept. Co-Authored-By: Claude Fable 5.2 --- app.py | 1 + .../definition-first-projects/spec-d2.md | 20 + static/project-workspace.html | 1 + static/project-workspace/adapter.js | 5 + static/project-workspace/base.css | 57 +++ static/project-workspace/inside.js | 3 +- static/project-workspace/screens.js | 5 + static/project-workspace/weights.js | 410 ++++++++++++++++ tests/browser_project_workspace_weights.cjs | 461 ++++++++++++++++++ tests/project_weights_browser_fixture.py | 179 +++++++ 10 files changed, 1141 insertions(+), 1 deletion(-) create mode 100644 static/project-workspace/weights.js create mode 100644 tests/browser_project_workspace_weights.cjs create mode 100644 tests/project_weights_browser_fixture.py diff --git a/app.py b/app.py index 59f876e0..67afe506 100644 --- a/app.py +++ b/app.py @@ -806,6 +806,7 @@ def _get(self): '/project-workspace/editor.js': ('project-workspace/editor.js', 'text/javascript'), '/project-workspace/tabs.js': ('project-workspace/tabs.js', 'text/javascript'), '/project-workspace/inside.js': ('project-workspace/inside.js', 'text/javascript'), + '/project-workspace/weights.js': ('project-workspace/weights.js', 'text/javascript'), '/project-workspace/app.js': ('project-workspace/app.js', 'text/javascript'), '/static/vendor/ubuntu-sans/UbuntuSans[wdth,wght].ttf': ('vendor/ubuntu-sans/UbuntuSans[wdth,wght].ttf', 'font/ttf'), '/static/vendor/ubuntu-sans/UbuntuSans-Italic[wdth,wght].ttf': ('vendor/ubuntu-sans/UbuntuSans-Italic[wdth,wght].ttf', 'font/ttf'), diff --git a/docs/plans/definition-first-projects/spec-d2.md b/docs/plans/definition-first-projects/spec-d2.md index 6932748d..f7a1f7e0 100644 --- a/docs/plans/definition-first-projects/spec-d2.md +++ b/docs/plans/definition-first-projects/spec-d2.md @@ -97,3 +97,23 @@ What differs from the text above, and what was found. - **Measured** on an earlier lab model (26 tensors in 14 layers, 163,068 parameters, 660 KB), through the readers alone: `weights` 0.002 s; `weights_compare` against its `initial-weights.npz` 0.024 s (total relative change 0.85, cosine 0.70; four layers started at zero, so their relative change is null); `array_tiles` of its largest tensor 0.0003 s. - **Tests:** `tests/test_tuldok_project_weights.py`, 16; `tests/test_tuldok_project_inside.py`, 25; project suite 626 before the review's change, and the two files above after it; agent interface 43 (4 skipped). The catalog profile's digest is unchanged. - **Not verified:** a `.safetensors` written by the library itself (the tests write their own); comparing a Fortran-ordered array with a C-ordered one is right but reorders value by value, which would be slow on a large tensor; a big-endian machine. + +### D2b, the page + +What differs from section 4, and why. + +- **Where the block sits and when it shows.** `screens.js` puts an empty, hidden block between "Runs and product" and "Uses"; `weights.js` (`LabWeights.block`) reads the model's current products and their `weights`, and shows the block only when one of them lists a weights file. A model without one (no product, or no weights file in it) has no Weights block at all. Read again for the model on screen (spec-w4 R3), the block is one of the drawer's reads: it resolves only once complete (the comparison, the opened tensor and its images read), so the drawer is put in place in one step. +- **Several products.** A model with several current products (subjects) lists the weights files of all of them in the one select, each labelled with its subject. +- **"The model it derives from"** is the model's `derived_from` (the one derivation line the map draws to it); its current products' readable weights files are each a choice, labelled with the model's short name and title (and the file's path when it has several). +- **A layer's change** is not in the answer of `weights_compare`, which is per tensor. The page computes it over the layer's tensors that were compared: the square root of the summed squared `difference_norm` over that of the summed squared `other_norm`. For a layer of one tensor it is that tensor's `relative_change`. "From zero" when the other's norm is zero; "not finite" when a tensor's norms are null; "not compared" when none of its tensors was (only here, reshaped, not read), with the marks of those tensors under its name. The bar is scaled to the largest change among the layers. Sorting by change puts the layers that started at zero first (an unbounded relative change), then the largest, then those not compared. +- **The table in a narrow drawer:** a fixed layout of four columns (layer, parameters, the small distribution, the change); the shape of a layer's first tensor (and how many tensors it has) is a second line under its name rather than a column, and the marks of a comparison a third. +- **A tensor opened** is drawn in a row of its own under its layer's row, across the drawer's width, rather than below the table, so that it stays next to the layer it belongs to whatever the sort. Its first tensor is opened with it; a layer of several tensors offers them as a switch. The statistics and the larger distribution (64 bins) are of this file's tensor in every mode, and say so when comparing; the images follow the mode. +- **One axis** (a bias) is drawn as one strip of cells by `array_slice`; section 4 names only two and three or more. A scalar shows its statistics only. +- **Tiles.** `array_tiles` with 16 tiles a page; "Tiles across" chooses any axis (the two drawn are then the last two others, as the operation's default) and the sliders are for the axes neither drawn nor counted across. Every tile is its own canvas with its position under it and its own text alternative, in a grid that wraps (at least 72 px a tile). All the tiles of a page share one range, symmetric about zero; the difference is computed in the page from the two answers (the same arguments give the same tiles, rows, columns and stride on both sides) and drawn on its own symmetric range. A legend under the images shows the ramp from −m to +m and says the range. +- **What is kept.** `weights` and `weights_compare` are read through the adapter's kept answers (forgotten when a reading finds a change, so asked again then: one `weights_compare` per choice and per drawing after a change). A product does not change once its run finished, so the distributions (`array_summary`) and the tiles and slices are also kept in `weights.js` for the page's life (the tiles and slices at most 64, the least recently used dropped): a block drawn again draws a distribution already read at once and never asks for it again, and a slider moved back draws without asking. The slice and tile reads themselves are not kept by the adapter (asked fresh), as spec-d1 does for its slider. +- **What redraws what.** The person's choices (file, comparison, sort, a layer, a tensor, a mode) build the block again off the page and put it in place with its focus (by `data-key`) and the drawer's scroll kept; an axis or a page builds the images again the same way; a slider moves only the tiles (read again after 90 ms, the latest wins), so a drag is never interrupted. While something reads the block or the images carry `aria-busy`; "Reading…" is never shown, because the block is on screen. +- **`inside.js` exports its drawing parts** as `LabInside.drawing` (`floats`, `token`, `ramp`, `paints`, `fit`, `heat`, `contain`, `ordinal`); its own behaviour is unchanged. The diverging ramp is always asked for on a range symmetric about zero, so a tensor of one sign is still coloured from zero. +- **Files beyond section 5's list:** `static/project-workspace.html` gains the ` + diff --git a/static/project-workspace/adapter.js b/static/project-workspace/adapter.js index b85ba37c..2322de75 100644 --- a/static/project-workspace/adapter.js +++ b/static/project-workspace/adapter.js @@ -115,6 +115,11 @@ window.TuldokProject = (() => { /** A slice; kept unless fresh (the viewer's slider). */ slice: (run, { path, array, axes, index, most }, fresh = false) => (fresh ? call : read)('array_slice', defined({ run, path, array, axes, index, most })), summary: (run, { path, array, bins }) => read('array_summary', defined({ run, path, array, bins })), + // A model's weights (spec-d2.md, weights.js): its weights files, a comparison of two, and tiles of a tensor + // of three or more axes (asked for each time the person moves through them unless kept). + weights: run => read('weights', { run }), + compare: (run, path, otherRun, otherPath) => read('weights_compare', { run, path, other_run: otherRun, other_path: otherPath }), + tiles: (run, { path, array, across, axes, index, first, most }, fresh = false) => (fresh ? call : read)('array_tiles', defined({ run, path, array, across, axes, index, first, most })), /** The address of an image's or a sound's bytes (GET /api/project/file), as the record operation gives it. */ fileUrl: (run, path) => '/api/project/file?run=' + encodeURIComponent(run) + '&path=' + encodeURIComponent(path) }; diff --git a/static/project-workspace/base.css b/static/project-workspace/base.css index 2eef2472..5784a60a 100644 --- a/static/project-workspace/base.css +++ b/static/project-workspace/base.css @@ -656,3 +656,60 @@ div.row.def { cursor: default; } .iv-ends { display: flex; justify-content: space-between; margin-top: 2px; } .iv-facts { font-size: 12.5px; } .iv-hist { display: grid; gap: 6px; } + +/* ---- A model's weights (weights.js, spec-d2 section 4): the block in the model's drawer. ---- */ +.wts { display: grid; gap: 10px; min-width: 0; } +.wts > h3 { margin-bottom: 0; } +.wts-head { display: grid; gap: 2px; min-width: 0; } +.wts-head p { margin: 0; } +.wts-path { overflow-wrap: anywhere; } +.wts-pick { display: grid; gap: 4px; font-size: 12.5px; color: var(--ink-2); } +.wts-pick select { max-width: 100%; min-width: 0; } +.wts-bar { display: flex; flex-wrap: wrap; gap: 8px; align-items: center; } +.wts .seg { justify-self: start; max-width: 100%; flex-wrap: wrap; } +.wts .seg button { font-size: 12.5px; padding: 3px 10px; } +.wts-total, .wts-there { margin: 0; } +.wts-tablebox { min-width: 0; } +table.wts-table { table-layout: fixed; width: 100%; font-size: 12.5px; } +table.wts-table th, table.wts-table td { padding: 6px 4px; vertical-align: middle; } +table.wts-table th:first-child, table.wts-table td:first-child { padding-left: 0; } +table.wts-table th:last-child, table.wts-table td:last-child { padding-right: 0; } +table.wts-table th { font-size: 12px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; } +table.wts-table col.wc-n { width: 76px; } +table.wts-table col.wc-dist { width: 60px; } +table.wts-table col.wc-chg { width: 82px; } +.wts-name { min-width: 0; } +.wts-name .linkish { display: block; max-width: 100%; color: var(--ink); text-decoration: underline; text-decoration-color: var(--line-strong); text-underline-offset: 2px; } +.wts-name .linkish:hover { text-decoration-color: var(--accent); } +.wts-name .linkish[aria-expanded="true"] { color: var(--accent); text-decoration-color: var(--accent); } +.wts-lname { overflow-wrap: anywhere; } +.wts-shape { display: block; font-size: 12px; color: var(--ink-2); font-variant-numeric: tabular-nums; overflow-wrap: anywhere; } +.wts-mark { display: inline-block; margin: 3px 4px 0 0; padding: 0 6px; border-radius: 9px; font-size: 11.5px; line-height: 18px; border: 1px solid var(--warn); color: var(--warn); background: var(--warn-wash); } +.wts-mark.only { border-color: var(--line-strong); color: var(--ink-2); background: var(--surface-2); } +.wts-dist canvas.wts-spark { display: block; width: 100%; height: 22px; background: var(--surface-2); border-radius: 3px; } +.wts-dist canvas.wts-spark.refused { outline: 1px solid var(--serious); } +.wts-chg { font-variant-numeric: tabular-nums; } +.wts-cbar { display: block; height: 6px; background: var(--surface-2); border-radius: 3px; overflow: hidden; } +.wts-cbar i { display: block; height: 100%; background: var(--mark); border-radius: 3px; } +.wts-fig { display: block; margin-top: 2px; font-size: 12px; color: var(--ink); } +.wts-zero { font-size: 12px; color: var(--ink-2); font-style: italic; } +tr.wts-open > td { padding: 8px 0 14px; border-top: 0; } +tr.wts-row:has(+ tr.wts-open) > td { background: var(--accent-wash); } +.wts-tensor { display: grid; gap: 8px; min-width: 0; padding: 10px; border: 1px solid var(--line); border-radius: var(--radius); background: var(--surface); } +.wts-tensor p { margin: 0; } +.wts-what { overflow-wrap: anywhere; } +.wts-stats { font-size: 12.5px; } +.wts canvas.wts-hist { display: block; width: 100%; background: var(--surface-2); border-radius: var(--radius); } +.wts-images { display: grid; gap: 8px; min-width: 0; } +.wts-ctl .iv-field select { max-width: 100%; } +.wts-ctl .iv-slider input[type="range"] { width: 110px; } +.wts-pics.tiles { display: grid; grid-template-columns: repeat(auto-fill, minmax(72px, 1fr)); gap: 8px; } +.wts-pics.one canvas { display: block; width: 100%; background: var(--surface-2); border-radius: var(--radius); } +.wts-tile { margin: 0; display: grid; gap: 2px; min-width: 0; } +.wts-tile canvas { display: block; width: 100%; background: var(--surface-2); border-radius: 3px; } +.wts-tile figcaption { font-size: 11.5px; color: var(--ink-3); text-align: center; } +.wts canvas.wts-ramp { display: block; width: 100%; height: 10px; border-radius: 3px; } +.wts-legend { display: grid; gap: 2px; } +.wts-legend .wts-range { margin-top: 4px; } +.wts-pager { margin: 0; flex-wrap: wrap; } +.wts-reason { margin: 0; } diff --git a/static/project-workspace/inside.js b/static/project-workspace/inside.js index 42babd73..08c5aca4 100644 --- a/static/project-workspace/inside.js +++ b/static/project-workspace/inside.js @@ -697,5 +697,6 @@ window.LabInside = (() => { ctx.globalAlpha = 1; } - return { open, leave, PER_PAGE }; + // The drawing parts other viewers reuse (weights.js): decoding, the tokens' colours, the canvases drawn again on a new size or theme. + return { open, leave, PER_PAGE, drawing: { floats, token, ramp, paints, fit, heat, contain, ordinal } }; })(); diff --git a/static/project-workspace/screens.js b/static/project-workspace/screens.js index b6f5f5a2..05b1967d 100644 --- a/static/project-workspace/screens.js +++ b/static/project-workspace/screens.js @@ -198,6 +198,11 @@ window.LabScreens = (() => { // What is read when the model is opened. const results = block('Results'), runs = block('Runs and product'), uses2 = block('Uses'), card = block('Card'); for (const b of [results, runs, uses2, card]) { b.appendChild(h('p', 'note', 'Reading…')); ins.appendChild(b); } + // Weights (weights.js, spec-d2 section 4), after Runs and product: shown only when the model has a current product with a weights file. + if (window.LabWeights) { + const wts = h('div', 'wts-box'); wts.hidden = true; ins.insertBefore(wts, uses2); + reads.push(window.LabWeights.block(wts, m, g, aside.parentElement, live).catch(error => { if (!live()) return; wts.hidden = false; wts.replaceChildren(h('h3', null, 'Weights'), A.refusal(error)); })); + } if (more) more(ins); if (!same) aside.appendChild(ins); // first shown: at once, its blocks filled as they come const fill = (b, build) => p => { if (!live()) return; b.lastChild.remove(); try { build(b, p); } catch (error) { failure(b, error); } }; diff --git a/static/project-workspace/weights.js b/static/project-workspace/weights.js new file mode 100644 index 00000000..698d6a12 --- /dev/null +++ b/static/project-workspace/weights.js @@ -0,0 +1,410 @@ +'use strict'; +// A model's weights (docs/plans/definition-first-projects/spec-d2.md section 4): the block "Weights" of a model's +// drawer, after "Runs and product", when the model has a current product with a weights file. Its head names the +// file (a select when there are several), its size and parameters; a file Tuldok does not read shows its reason +// and nothing else. "Compare with" offers the weights the run started from and the models the map draws a +// derivation line from; choosing one asks weights_compare once. The layers are a table (name, shape of the first +// tensor, parameters, a small distribution asked for when its row comes on screen, and when comparing a bar of +// how much it changed); a layer opened shows a tensor's statistics, its larger distribution and its values as +// images, one image for two axes (array_slice), tiles for three or more (array_tiles), coloured diverging about +// zero; when comparing, this, the other, or their difference (computed here, tile by tile). +// +// Updating in place (spec-w4): the block is built off the page and put in place whole. Read again for the model +// on screen (screens.js), it is built from the person's place in it (file, comparison, sort, layer and tensor +// opened, axes, page, mode) and resolves only once complete, so the drawer puts it in place in one step. The +// person's own choices draw the block again the same way (putInPlace, the focus kept by data-key); a slider moves +// only the tiles. A product does not change once its run finished: the distributions and tiles read are kept here +// for the page's life (bounded), so a block drawn again draws them at once and asks for none again. +window.LabWeights = (() => { + const P = window.TuldokProject, S = window.LabScreens, C = window.LabCharts, h = C.h, R = P.product; + const { bytes, putInPlace } = S.parts; + const D = window.LabInside.drawing; + const SMALL_BINS = 32, BIG_BINS = 64; // a row's distribution, the opened tensor's + const TILES = 16; // tiles on a page + const SLICE_MOST = 256; // rows and columns of a two-axis image + const KEEP = 64; // tiles and slices kept + const MARGIN = '40px 0px'; // how near the drawer's view a row's distribution is asked for + const fmt = v => v == null ? '—' : C.fmtSci(v); + const num = n => n == null ? '—' : n.toLocaleString('en-GB'); + const shapeText = s => s.length ? s.join(' × ') : 'one value'; + const plural = (n, one, many) => num(n) + ' ' + (n === 1 ? one : many || one + 's'); + const button = (cls, text, onClick) => { const b = h('button', cls, text); b.type = 'button'; if (onClick) b.addEventListener('click', onClick); return b; }; + const refusal = error => window.LabActions.refusal(error); + + // ---- What is kept ------------------------------------------------------------------------------------------------ + const places = new Map(); // model id -> the person's place in its block + const placeOf = id => { if (!places.has(id)) places.set(id, { file: null, compare: '', sort: 'file', layer: null, tensor: null, mode: 'this', views: new Map() }); return places.get(id); }; + const summaries = new Map(); // run \n path \n array \n bins -> an answer of array_summary + const sumKey = (run, path, array, bins) => [run, path, array, bins].join('\n'); + const answers = new Map(); // the tiles and slices read, the latest last + async function kept(key, ask) { + if (answers.has(key)) { const v = answers.get(key); answers.delete(key); answers.set(key, v); return v; } + const v = await ask(); answers.set(key, v); while (answers.size > KEEP) answers.delete(answers.keys().next().value); return v; + } + async function summary(run, path, array, bins) { + const key = sumKey(run, path, array, bins); + if (!summaries.has(key)) summaries.set(key, await R.summary(run, { path, array, bins })); + return summaries.get(key); + } + + // ---- Reading --------------------------------------------------------------------------------------------------------- + /** The weights files of a model's current products, each with its run and a key. */ + async function filesOf(reference) { + const products = (await P.read('products', { reference })).products.filter(p => p.run_id); + const lists = await Promise.all(products.map(p => R.weights(p.run_id).then(w => w.files.map(f => Object.assign({ run: p.run_id, subject: p.subject || '', key: p.run_id + '\n' + f.path }, f))))); + return lists.flat(); + } + /** What a file can be compared with: the weights it started from, and the readable weights of each model it derives from. */ + async function choicesFor(m, g, f) { + const out = []; + if (f.starts_from) out.push({ key: 'start', label: 'The weights it started from', detail: f.starts_from, run: f.run, path: f.starts_from }); + const parents = [m.parent].filter(p => p && g.byId.has(p)); + for (const ref of parents) { + const files = await filesOf(ref).catch(() => []), readable = files.filter(x => x.readable), o = g.byId.get(ref); + for (const x of readable) out.push({ key: 'model\n' + ref + '\n' + x.key, label: 'The model it derives from', detail: (o.short ? o.short + ' · ' : '') + o.title + (readable.length > 1 ? ' · ' + x.path : ''), run: x.run, path: x.path, model: ref }); + } + return out; + } + + /** + * Fills box (a block of the drawer of model m, on the page or not yet) with the Weights block, or hides it + * when the model has no weights file. Resolves once the block is complete. scroller: the drawer's own scroll + * (the root of the rows' observer); live(): whether the drawer still shows this model. + */ + async function block(box, m, g, scroller, live) { + const st = placeOf(m.id), ctx = { box, m, g, st, scroller, live, io: null, turn: 0 }; + const root = await build(ctx); + if (!live()) return; + if (st.ctx && st.ctx !== ctx && st.ctx.io) st.ctx.io.disconnect(); // the block it replaces asks for nothing more + st.ctx = ctx; + if (!root) { box.hidden = true; box.replaceChildren(); return; } + box.hidden = false; box.replaceChildren(root); watch(ctx, root); + } + /** Draws the block again for the person's own choice: built off the page, then put in place with the focus and the scroll kept. */ + async function again(ctx) { + const mine = ++ctx.turn; + ctx.box.setAttribute('aria-busy', 'true'); + let root; try { root = await build(ctx); } catch (error) { root = h('div'); root.appendChild(h('h3', null, 'Weights')); root.appendChild(refusal(error)); } + if (mine !== ctx.turn || !ctx.box.isConnected) return; + ctx.box.removeAttribute('aria-busy'); + if (ctx.io) ctx.io.disconnect(); + putInPlace(ctx.box, root || h('div'), ctx.scroller); + watch(ctx, root); + } + + /** The block's content, read in full; null when the model has no weights file. */ + async function build(ctx) { + const { m, g, st } = ctx; + const files = await filesOf(m.id); + if (!files.length) return null; + const f = files.find(x => x.key === st.file) || files.find(x => x.readable) || files[0]; st.file = f.key; + const root = h('div', 'wts'); + root.appendChild(h('h3', null, 'Weights')); + // The head: the file, its size and parameters. + const head = h('div', 'wts-head'); + if (files.length > 1) { + const s = h('select'); s.setAttribute('aria-label', 'Weights file'); s.dataset.key = 'wts-file'; + for (const x of files) { const o = h('option', null, x.path + (x.subject ? ' · ' + x.subject : '') + (x.readable ? '' : ' (not read)')); o.value = x.key; o.selected = x === f; s.appendChild(o); } + s.addEventListener('change', () => { Object.assign(st, { file: s.value, compare: '', layer: null, tensor: null, mode: 'this' }); again(ctx); }); + const l = h('label', 'iv-field wts-pick'); l.appendChild(document.createTextNode('File')); l.appendChild(s); head.appendChild(l); + } else head.appendChild(h('p', 'mono wts-path', f.path)); + head.appendChild(h('p', 'small muted wts-size', [bytes(f.bytes), f.readable ? plural(f.parameters, 'parameter') : null, f.readable ? plural(f.layers.length, 'layer') + ', ' + plural(f.tensors, 'tensor') : null].filter(Boolean).join(' · '))); + root.appendChild(head); + if (!f.readable) { root.appendChild(h('p', 'empty wts-reason', f.reason)); return root; } + if (f.layers.length && f.tensors > f.layers.reduce((n, l) => n + l.tensors.length, 0)) root.appendChild(h('p', 'note', 'The first ' + num(f.layers.reduce((n, l) => n + l.tensors.length, 0)) + ' tensors are listed.')); + // Compare with. + const choices = await choicesFor(m, g, f); + if (!choices.some(c => c.key === st.compare)) st.compare = ''; + const choice = choices.find(c => c.key === st.compare) || null; + let cmp = null, cmpError = null; + if (choice) try { cmp = await R.compare(f.run, f.path, choice.run, choice.path); } catch (error) { cmpError = error; } + if (choices.length) { + const s = h('select'); s.setAttribute('aria-label', 'Compare with'); s.dataset.key = 'wts-compare'; + const none = h('option', null, 'Nothing'); none.value = ''; s.appendChild(none); + for (const c of choices) { const o = h('option', null, c.label + ': ' + c.detail); o.value = c.key; o.selected = c === choice; s.appendChild(o); } + s.addEventListener('change', () => { st.compare = s.value; if (!s.value && st.sort === 'change') st.sort = 'file'; if (!s.value) st.mode = 'this'; again(ctx); }); + const l = h('label', 'iv-field wts-pick'); l.appendChild(document.createTextNode('Compare with')); l.appendChild(s); root.appendChild(l); + } + if (cmpError) root.appendChild(refusal(cmpError)); + const cmpd = cmp ? compared(cmp) : null; + if (cmp) { + const t = cmp.total; + root.appendChild(h('p', 'small muted wts-total', 'All compared: ' + plural(t.parameters, 'parameter') + ', relative change ' + (t.relative_change == null ? (t.other_norm === 0 ? 'from zero' : '—') : fmt(t.relative_change)) + ', cosine ' + fmt(t.cosine) + ', largest change ' + fmt(t.largest_change) + '.')); + if (cmp.only_there.length) root.appendChild(h('p', 'small muted wts-there', 'Only in the other: ' + cmp.only_there.join(', ') + '.')); + } + // Sorting. + if (st.sort === 'change' && !cmp) st.sort = 'file'; + const seg = h('div', 'seg wts-sort'); seg.setAttribute('role', 'group'); seg.setAttribute('aria-label', 'Sort the layers by'); + for (const [key, label] of [['file', 'File order'], ['size', 'Size']].concat(cmp ? [['change', 'Change']] : [])) { + const b = button(null, label, () => { if (st.sort !== key) { st.sort = key; again(ctx); } }); b.setAttribute('aria-pressed', String(st.sort === key)); b.dataset.key = 'wts-sort-' + key; seg.appendChild(b); + } + const bar = h('div', 'wts-bar'); bar.appendChild(h('span', 'small muted', 'Sort by')); bar.appendChild(seg); root.appendChild(bar); + // The layers. + const rows = f.layers.map((layer, i) => ({ layer, i, change: cmpd ? layerChange(layer, cmpd) : null })); + const rel = r => r.change && r.change.rel != null ? r.change.rel : r.change && r.change.zero ? Infinity : -1; + if (st.sort === 'size') rows.sort((a, b) => b.layer.parameters - a.layer.parameters || a.i - b.i); + if (st.sort === 'change') rows.sort((a, b) => rel(b) - rel(a) || a.i - b.i); + const most = Math.max(0, ...rows.map(r => r.change && r.change.rel != null ? r.change.rel : 0)); + const table = h('table', 'tv wts-table' + (cmp ? ' comparing' : '')); + const cols = h('colgroup'); for (const c of ['name', 'n', 'dist'].concat(cmp ? ['chg'] : [])) cols.appendChild(h('col', 'wc-' + c)); table.appendChild(cols); + const th = h('thead'), hr = h('tr'); + for (const [label, cls] of [['Layer', ''], ['Parameters', 'n'], ['Values', '']].concat(cmp ? [['Change', '']] : [])) hr.appendChild(h('th', cls, label)); + th.appendChild(hr); table.appendChild(th); + const tb = h('tbody'); + for (const r of rows) { + const { layer } = r, open = st.layer === layer.name, first = layer.tensors[0]; + const tr = h('tr', 'wts-row'); tr.dataset.layer = layer.name; + const name = h('td', 'wts-name'); + const nb = button('linkish', null, () => { if (st.layer === layer.name) { st.layer = null; st.tensor = null; } else { st.layer = layer.name; st.tensor = layer.tensors[0].array; } again(ctx); }); + nb.dataset.key = 'wts-layer-' + layer.name; nb.setAttribute('aria-expanded', String(open)); + nb.appendChild(h('span', 'mono wts-lname', layer.name)); + nb.setAttribute('aria-label', 'Layer ' + layer.name + ', ' + plural(layer.parameters, 'parameter') + (open ? '; press to close' : '; press to open')); + name.appendChild(nb); + name.appendChild(h('span', 'wts-shape', shapeText(first.shape) + (layer.tensors.length > 1 ? ' · ' + plural(layer.tensors.length, 'tensor') : ''))); + if (r.change && r.change.marks.length) for (const mk of r.change.marks) { const s = h('span', 'wts-mark ' + mk.kind, mk.text); s.title = mk.title; name.appendChild(s); } + tr.appendChild(name); + tr.appendChild(h('td', 'n', num(layer.parameters))); + const dist = h('td', 'wts-dist'), cv = h('canvas', 'wts-spark'); cv.setAttribute('role', 'img'); cv.setAttribute('aria-label', 'Distribution of ' + first.array + ': not read yet'); + cv.dataset.run = f.run; cv.dataset.path = f.path; cv.dataset.array = first.array; + dist.appendChild(cv); tr.appendChild(dist); + if (cmp) tr.appendChild(changeCell(r.change, most)); + tb.appendChild(tr); + if (open) { + const or = h('tr', 'wts-open'), td = h('td'); td.colSpan = cmp ? 4 : 3; + td.appendChild(await tensorPanel(ctx, f, layer, cmpd, choice)); + or.appendChild(td); tb.appendChild(or); + } + } + table.appendChild(tb); + const wrap = h('div', 'wts-tablebox'); wrap.appendChild(table); root.appendChild(wrap); + return root; + } + + /** The comparison by array: rows of tensors compared, and the marks of those that are not. */ + function compared(cmp) { + const rows = new Map(cmp.tensors.map(t => [t.array, t])), marks = new Map(); + for (const a of cmp.only_here) marks.set(a, { kind: 'only', text: 'only here', title: a + ' is not in the other file' }); + for (const r of cmp.reshaped) marks.set(r.array, { kind: 'reshaped', text: 'reshaped', title: r.array + ' is ' + shapeText(r.shape) + ' here and ' + shapeText(r.other_shape) + ' in the other' }); + for (const u of cmp.unread || []) marks.set(u.array, { kind: 'unread', text: 'not read', title: u.array + ' is ' + u.dtype + ' here and ' + u.other_dtype + ' in the other; one of them is a type Tuldok does not read' }); + return { rows, marks }; + } + /** A layer's change over its tensors compared: the norm of their differences over the norm of the other's; null when that is zero (started at zero) or not finite. */ + function layerChange(layer, cmpd) { + const got = layer.tensors.map(t => cmpd.rows.get(t.array)).filter(Boolean); + const marks = layer.tensors.map(t => cmpd.marks.has(t.array) ? Object.assign({ array: t.array, name: t.name }, cmpd.marks.get(t.array)) : null).filter(Boolean) + .map(mk => Object.assign({}, mk, { text: (layer.tensors.length > 1 ? mk.name + ' ' : '') + mk.text })); + if (!got.length) return { rel: null, none: true, marks }; + if (got.some(r => r.difference_norm == null || r.other_norm == null)) return { rel: null, nonfinite: true, marks }; + const d = Math.sqrt(got.reduce((a, r) => a + r.difference_norm * r.difference_norm, 0)), o = Math.sqrt(got.reduce((a, r) => a + r.other_norm * r.other_norm, 0)); + return { rel: o ? d / o : null, zero: !o, marks, partial: got.length < layer.tensors.length }; + } + function changeCell(c, most) { + const td = h('td', 'wts-chg'); + if (c.none) { td.appendChild(h('span', 'small faint', 'not compared')); td.dataset.change = 'none'; return td; } + if (c.zero) { const s = h('span', 'wts-zero', 'from zero'); s.title = 'It started at zero, so its change has no relative size'; td.appendChild(s); td.dataset.change = 'zero'; return td; } + if (c.rel == null) { td.appendChild(h('span', 'small faint', 'not finite')); td.dataset.change = 'nonfinite'; return td; } + const bar = h('span', 'wts-cbar'); bar.setAttribute('aria-hidden', 'true'); const i = h('i'); i.style.width = (most > 0 ? Math.max(1, 100 * c.rel / most) : 0).toFixed(1) + '%'; bar.appendChild(i); + td.appendChild(bar); td.appendChild(h('span', 'wts-fig', fmt(c.rel))); td.dataset.change = String(c.rel); + td.title = 'Relative change ' + fmt(c.rel) + (c.partial ? ', over the tensors compared' : ''); + return td; + } + + // ---- A row's distribution, when it comes on screen --------------------------------------------------------------------- + function watch(ctx, root) { + if (ctx.io) ctx.io.disconnect(); ctx.io = null; + if (!root) return; + const lazy = []; + for (const cv of root.querySelectorAll('canvas.wts-spark')) { + const got = summaries.get(sumKey(cv.dataset.run, cv.dataset.path, cv.dataset.array, SMALL_BINS)); + if (got) spark(cv, got); else lazy.push(cv); + } + if (!lazy.length) return; + const io = ctx.io = new IntersectionObserver(entries => { + for (const e of entries) if (e.isIntersecting && e.target.isConnected) { + io.unobserve(e.target); + const cv = e.target; + summary(cv.dataset.run, cv.dataset.path, cv.dataset.array, SMALL_BINS).then(s => spark(cv, s), error => { cv.setAttribute('aria-label', 'Distribution of ' + cv.dataset.array + ': ' + (error.message || error)); cv.title = error.message || String(error); cv.classList.add('refused'); }); + } + }, { root: ctx.scroller, rootMargin: MARGIN }); + for (const cv of lazy) io.observe(cv); + } + function spark(cv, s) { + cv.dataset.drawn = '1'; + cv.setAttribute('aria-label', 'Distribution of ' + cv.dataset.array + ' in ' + s.histogram.counts.length + ' bins from ' + fmt(s.histogram.low) + ' to ' + fmt(s.histogram.high) + ', mean ' + fmt(s.mean)); + D.paints(cv, () => histogram(cv, s, 22, false)); + } + /** Bars of a histogram in a canvas of a CSS height; a mark at zero when zero is inside the range. */ + function histogram(cv, s, cssH, axis) { + const size = D.fit(cv, cssH); if (!size) return; const [W, H] = size, ctx = cv.getContext('2d'); ctx.clearRect(0, 0, W, H); + const counts = s.histogram.counts, most = Math.max(1, ...counts), bw = W / Math.max(1, counts.length), ink = D.token('--mark'), line = D.token('--line-strong'), dpr = window.devicePixelRatio || 1; + const { low, high } = s.histogram; + if (low != null && high != null && low < 0 && high > 0) { ctx.fillStyle = 'rgb(' + D.token('--ink-3').join(',') + ')'; ctx.fillRect(Math.round((0 - low) / (high - low) * W), 0, Math.max(1, Math.round(dpr)), H); } + ctx.fillStyle = 'rgb(' + ink.join(',') + ')'; + counts.forEach((n, i) => { if (!n) return; const bh = Math.max(Math.round(dpr), n / most * (H - 2 * dpr)); ctx.fillRect(i * bw + (bw > 3 ? 0.5 : 0), H - bh, Math.max(1, bw - (bw > 3 ? 1 : 0)), bh); }); + if (axis) { ctx.fillStyle = 'rgb(' + line.join(',') + ')'; ctx.fillRect(0, H - Math.max(1, Math.round(dpr)), W, Math.max(1, Math.round(dpr))); } + } + + // ---- A tensor opened --------------------------------------------------------------------------------------------------- + const viewOf = (st, f, t) => { const key = f.key + '\n' + t.array; if (!st.views.has(key)) st.views.set(key, { across: null, index: t.shape.map(n => Math.floor(n / 2)), first: 0 }); return st.views.get(key); }; + async function tensorPanel(ctx, f, layer, cmpd, choice) { + const { st } = ctx; + const t = layer.tensors.find(x => x.array === st.tensor) || layer.tensors[0]; st.tensor = t.array; + const panel = h('div', 'wts-tensor'); panel.setAttribute('aria-label', 'Tensor ' + t.array); + if (layer.tensors.length > 1) { + const seg = h('div', 'seg wts-tensors'); seg.setAttribute('role', 'group'); seg.setAttribute('aria-label', 'Tensor of ' + layer.name); + for (const x of layer.tensors) { const b = button(null, x.name, () => { if (st.tensor !== x.array) { st.tensor = x.array; again(ctx); } }); b.setAttribute('aria-pressed', String(x === t)); b.dataset.key = 'wts-tensor-' + x.array; b.title = x.array + ' · ' + shapeText(x.shape); seg.appendChild(b); } + panel.appendChild(seg); + } + panel.appendChild(h('p', 'small muted wts-what', [t.array, t.dtype, shapeText(t.shape), plural(t.parameters, 'value')].join(' · '))); + // When comparing: how it changed, or why it is not compared; this, the other or their difference. + const row = cmpd ? cmpd.rows.get(t.array) : null, mark = cmpd ? cmpd.marks.get(t.array) : null; + if (!row) st.mode = 'this'; + if (cmpd) { + if (row) panel.appendChild(h('p', 'small wts-row-cmp', 'Against ' + choice.detail + ': relative change ' + (row.relative_change == null ? (row.other_norm === 0 ? 'from zero' : '—') : fmt(row.relative_change)) + ', cosine ' + fmt(row.cosine) + ', largest change ' + fmt(row.largest_change) + '.')); + else panel.appendChild(h('p', 'small warnline', mark ? mark.title + ': it is not compared.' : 'Not compared.')); + if (row) { + const seg = h('div', 'seg wts-mode'); seg.setAttribute('role', 'group'); seg.setAttribute('aria-label', 'Show'); + for (const [key, label] of [['this', 'This'], ['other', 'The other'], ['difference', 'Difference']]) { const b = button(null, label, () => { if (st.mode !== key) { st.mode = key; again(ctx); } }); b.setAttribute('aria-pressed', String(st.mode === key)); b.dataset.key = 'wts-mode-' + key; seg.appendChild(b); } + panel.appendChild(seg); + } + } + // Its statistics and the larger distribution (of this file's tensor). + try { + const s = await summary(f.run, f.path, t.array, BIG_BINS); + if (row) panel.appendChild(h('p', 'small faint', 'Statistics of this file\'s tensor')); + const dl = h('dl', 'setup iv-facts wts-stats'); + const put = (k, text, stat, value) => { dl.appendChild(h('dt', null, k)); const dd = h('dd', 'num', text); dd.dataset.stat = stat; if (value != null) dd.dataset.value = String(value); dl.appendChild(dd); }; + put('Range', fmt(s.min) + ' to ' + fmt(s.max), 'range', JSON.stringify([s.min, s.max])); + put('Mean', fmt(s.mean), 'mean', s.mean); put('Spread', fmt(s.std), 'std', s.std); + put('Zeros', num(s.zeros), 'zeros', s.zeros); + put('Values', num(s.count) + (s.stride > 1 ? ', every ' + D.ordinal(s.stride) + ' read' : ''), 'count', s.count); + if (s.nonfinite) put('Not finite', num(s.nonfinite), 'nonfinite', s.nonfinite); + panel.appendChild(dl); + if (s.histogram && s.histogram.counts.length) { + const hc = h('canvas', 'wts-hist'); hc.setAttribute('role', 'img'); + hc.setAttribute('aria-label', 'Distribution of ' + t.array + ' in ' + s.histogram.counts.length + ' bins from ' + fmt(s.histogram.low) + ' to ' + fmt(s.histogram.high)); + D.paints(hc, () => histogram(hc, s, 72, true)); panel.appendChild(hc); + const ends = h('div', 'iv-ends small faint'); ends.appendChild(h('span', null, fmt(s.histogram.low))); ends.appendChild(h('span', null, fmt(s.histogram.high))); panel.appendChild(ends); + } + } catch (error) { panel.appendChild(refusal(error)); } + // Its values as images. + const images = h('div', 'wts-images'); + await fillImages(ctx, images, images, f, t, row ? choice : null); + panel.appendChild(images); + return panel; + } + + /** The drawn axes for a tensor of three or more axes counted across one: the last two of the others. */ + const drawnFor = (nd, across) => { const others = []; for (let a = 0; a < nd; a++) if (a !== across) others.push(a); return others.slice(-2); }; + /** Reads what the images show for the mode: this, the other, or their difference (each tile by tile). */ + async function readImages(f, t, v, mode, other) { + const nd = t.shape.length; + const ask = (run, path) => { + if (nd >= 3) { const args = { path, array: t.array, across: v.across, index: v.index.slice(), first: v.first, most: TILES }; return kept(JSON.stringify(['tiles', run, args]), () => R.tiles(run, args, true)); } + const args = { path, array: t.array, most: SLICE_MOST }; return kept(JSON.stringify(['slice', run, args]), () => R.slice(run, args, true)); + }; + const here = await ask(f.run, f.path); + if (mode === 'this') return { a: here, values: D.floats(here.values_f32) }; + const there = await ask(other.run, other.path), tv = D.floats(there.values_f32); + if (mode === 'other') return { a: there, values: tv }; + const hv = D.floats(here.values_f32), d = new Float32Array(hv.length); + for (let i = 0; i < d.length; i++) d[i] = hv[i] - tv[i]; + let min = Infinity, max = -Infinity, nonfinite = 0; for (const x of d) { if (!Number.isFinite(x)) { nonfinite++; continue; } if (x < min) min = x; if (x > max) max = x; } + return { a: Object.assign({}, here, { min: Number.isFinite(min) ? min : null, max: Number.isFinite(max) ? max : null, nonfinite }), values: d }; + } + const MODE_WORD = { this: 'this file', other: 'the other file', difference: 'this minus the other' }; + /** + * Fills target with the controls and the images of tensor t (built in full before it returns); host is the + * element they are shown in (target itself, or the box they will be put in place in). + */ + async function fillImages(ctx, target, host, f, t, other) { + const { st } = ctx, nd = t.shape.length, v = viewOf(st, f, t), mode = other ? st.mode : 'this'; + if (nd === 0) return; + if (nd >= 3) { if (v.across == null || v.across >= nd) v.across = 0; if (v.first >= t.shape[v.across]) v.first = 0; } + const ctl = h('div', 'iv-ctl wts-ctl'); + let sliders = []; + if (nd >= 3) { + const s = h('select'); s.setAttribute('aria-label', 'Axis counted across the tiles'); s.dataset.key = 'wts-across'; + for (let a = 0; a < nd; a++) { const o = h('option', null, 'axis ' + a + ' (' + t.shape[a] + ')'); o.value = String(a); o.selected = a === v.across; s.appendChild(o); } + s.addEventListener('change', () => { v.across = Number(s.value); v.first = 0; redrawImages(ctx, host, f, t, other); }); + const l = h('label', 'iv-field'); l.appendChild(document.createTextNode('Tiles across')); l.appendChild(s); ctl.appendChild(l); + const drawn = drawnFor(nd, v.across); + for (let a = 0; a < nd; a++) if (a !== v.across && !drawn.includes(a)) { + const l2 = h('label', 'iv-field iv-slider'); l2.appendChild(h('span', null, 'Axis ' + a)); + const r = h('input'); r.type = 'range'; r.min = '0'; r.max = String(t.shape[a] - 1); r.value = String(v.index[a]); r.dataset.key = 'wts-axis-slider-' + a; r.dataset.axis = String(a); + r.setAttribute('aria-label', 'Position on axis ' + a + ', 0 to ' + (t.shape[a] - 1)); + const at = h('span', 'num small', v.index[a] + ' of ' + t.shape[a]); + l2.appendChild(r); l2.appendChild(at); ctl.appendChild(l2); sliders.push({ a, r, at }); + } + } + let got; + try { got = await readImages(f, t, v, mode, other); } catch (error) { target.replaceChildren(ctl, refusal(error)); return; } + const pics = h('div', 'wts-pics'), legend = h('div', 'wts-legend'); + const paint = g => { drawPics(pics, legend, g, t, v, mode); }; + paint(got); + if (nd >= 3) { + const n = t.shape[v.across], last = v.first + got.a.tiles; + const pg = h('div', 'pager wts-pager'); + const pb = button('btn sm', 'Previous', () => { v.first = Math.max(0, v.first - TILES); redrawImages(ctx, host, f, t, other); }); pb.disabled = v.first === 0; pb.dataset.key = 'wts-prev'; + const nb = button('btn sm', 'Next', () => { v.first += TILES; redrawImages(ctx, host, f, t, other); }); nb.disabled = last >= n; nb.dataset.key = 'wts-next'; + pg.appendChild(pb); pg.appendChild(nb); pg.appendChild(h('span', 'small muted', 'Tiles ' + (v.first + 1) + '–' + last + ' of ' + n + ' along axis ' + v.across)); + target.replaceChildren(ctl, pics, legend, pg); + // A slider moves the tiles: read again (the latest wins), drawn again in place; the controls stay. + let wanted = 0, timer = 0; + for (const { a, r, at } of sliders) r.addEventListener('input', () => { + v.index[a] = Number(r.value); at.textContent = v.index[a] + ' of ' + t.shape[a]; + clearTimeout(timer); const mine = ++wanted; host.setAttribute('aria-busy', 'true'); + timer = setTimeout(async () => { + try { const next = await readImages(f, t, v, mode, other); if (mine !== wanted || !pics.isConnected) return; paint(next); } + catch (error) { if (mine === wanted) legend.replaceChildren(refusal(error)); } + if (mine === wanted) host.removeAttribute('aria-busy'); + }, 90); + }); + } else target.replaceChildren(pics, legend); + host.dataset.mode = mode; + } + /** Draws the images again for a control (an axis, a page): built off the page, put in place with the focus kept. */ + async function redrawImages(ctx, box, f, t, other) { + const mine = box._turn = (box._turn || 0) + 1, fresh = h('div'); box.setAttribute('aria-busy', 'true'); + await fillImages(ctx, fresh, box, f, t, other); + if (mine !== box._turn || !box.isConnected) return; + box.removeAttribute('aria-busy'); + const frag = document.createDocumentFragment(); frag.append(...fresh.childNodes); + putInPlace(box, frag, ctx.scroller); + } + + /** The tiles (three or more axes) or the one image (one or two axes), on a range symmetric about zero, and the legend. */ + function drawPics(pics, legend, g, t, v, mode) { + const a = g.a, nd = t.shape.length, m = Math.max(Math.abs(a.min || 0), Math.abs(a.max || 0)) || 1, colour = D.ramp(-m, m); + const tiles = nd >= 3 ? a.tiles : 1, rows = a.rows, cols = a.columns, per = rows * cols; + const where = nd >= 3 ? ' along axes ' + a.axes.join(' and ') + (a.index.some((_, i) => i !== a.across && !a.axes.includes(i)) ? ' at ' + a.index.map((p, i) => i !== a.across && !a.axes.includes(i) ? 'axis ' + i + ' = ' + p : null).filter(Boolean).join(', ') : '') : ''; + const els = []; + for (let k = 0; k < tiles; k++) { + const fig = h('figure', 'wts-tile'), cv = h('canvas'); cv.setAttribute('role', 'img'); + const values = g.values.subarray(k * per, (k + 1) * per); + if (nd >= 3) cv.setAttribute('aria-label', 'Tile at axis ' + a.across + ' = ' + (a.first + k) + ' of ' + t.array + ' (' + MODE_WORD[mode] + '): ' + rows + ' by ' + cols + ' values' + where); + else cv.setAttribute('aria-label', (nd === 1 ? 'The ' + cols + ' values' : rows + ' by ' + cols + ' values') + ' of ' + t.array + ' (' + MODE_WORD[mode] + '), from ' + fmt(a.min) + ' to ' + fmt(a.max) + (a.stride > 1 ? ', every ' + D.ordinal(a.stride) + ' row and column' : '')); + D.paints(cv, () => { + const w = cv.clientWidth; if (!w) return; + const cssH = nd === 1 ? 28 : Math.max(nd >= 3 ? 24 : 32, Math.min(nd >= 3 ? w * 1.5 : 320, Math.round(w * rows / cols))); + const size = D.fit(cv, cssH); if (!size) return; const ctx = cv.getContext('2d'); ctx.clearRect(0, 0, size[0], size[1]); + const [x, y, ww, hh] = nd === 1 ? [0, 0, size[0], size[1]] : D.contain(rows, cols, size[0], size[1]); + D.heat(ctx, values, rows, cols, colour, x, y, ww, hh); + }); + fig.appendChild(cv); + if (nd >= 3) fig.appendChild(h('figcaption', 'num', String(a.first + k))); + els.push(fig); + } + pics.className = 'wts-pics' + (nd >= 3 ? ' tiles' : ' one'); + pics.dataset.mode = mode; pics.dataset.first = String(a.first || 0); pics.dataset.index = JSON.stringify(a.index || []); pics.dataset.across = String(nd >= 3 ? a.across : ''); + pics.replaceChildren(...els); + // The legend: the ramp from -m to +m. + const ramp = h('canvas', 'wts-ramp'); ramp.setAttribute('aria-hidden', 'true'); + D.paints(ramp, () => { const size = D.fit(ramp, 10); if (!size) return; const n = 64, vals = new Float32Array(n); for (let i = 0; i < n; i++) vals[i] = -m + 2 * m * (i + 0.5) / n; D.heat(ramp.getContext('2d'), vals, 1, n, colour, 0, 0, size[0], size[1]); }); + const ends = h('div', 'iv-ends small faint'); ends.appendChild(h('span', null, '−' + fmt(m))); ends.appendChild(h('span', null, '0')); ends.appendChild(h('span', null, '+' + fmt(m))); + const say = h('p', 'small muted wts-range', (mode === 'difference' ? 'This minus the other' : mode === 'other' ? 'The other file' : 'This file') + ': from ' + fmt(a.min) + ' to ' + fmt(a.max) + ', coloured on ±' + fmt(m) + ' about zero' + (a.stride > 1 ? ' · every ' + D.ordinal(a.stride) + ' row and column' : '') + (a.nonfinite ? ' · ' + plural(a.nonfinite, 'value') + ' not finite, left clear' : '') + '.'); + legend.replaceChildren(ramp, ends, say); + } + + return { block }; +})(); diff --git a/tests/browser_project_workspace_weights.cjs b/tests/browser_project_workspace_weights.cjs new file mode 100644 index 00000000..5b115b79 --- /dev/null +++ b/tests/browser_project_workspace_weights.cjs @@ -0,0 +1,461 @@ +'use strict'; +// A model's weights in its drawer (docs/plans/definition-first-projects/spec-d2.md sections 4 and 6, slice D2b) in a +// headless browser, the owner signed in, no GPU. Tuldok runs with --project-folder on a copy of the minimal fixture, +// in a Git repository of its own, with three more recipes of earlier work whose products are adopted (the command +// line's adopt) from files tests/project_weights_browser_fixture.py writes with the standard library: +// recipes/wt-parent (weights.npz), recipes/wt-child, derived from it (weights.npz and initial-weights.npz), and +// recipes/wt-pickle (model.pt only). The fixture prints what it knows: layers, parameters, statistics, the change +// of each layer against the initial weights and against the parent. +// 1. The derived model's drawer shows Weights with the fixture's parameter count and its layers in file order, +// each with the fixture's parameters and the shape of its first tensor; the third model's shows the reason +// and nothing else. +// 2. A layer's distribution is asked for (array_summary, 32 bins) when its row comes on screen and not before, +// and once: the page's requests are counted while the drawer scrolls. +// 3. Opening a tensor shows its statistics (equal to the fixture's), its larger distribution and its values: a +// two-axis tensor as one image, the five-axis kernel as tiles whose range is the fixture's; a slider and the +// paging change the tiles (and their range is the fixture's at the new place). +// 4. Comparing with the starting weights and with the parent asks weights_compare once each and shows the +// fixture's change per layer ("from zero" for the layer that started at zero, the marks of a reshaped tensor, +// one only here and one only in the other); "difference" draws a different image from "this", on the +// fixture's range of the difference. +// 5. With the drawer open, comparing and a tensor opened, the window regaining focus and one reading on the timer +// add, remove and change no node and keep every scroll. +// 6. Light and dark at 1440 by 900 and 1000 by 800: no canvas of the block blank, nothing overflowing the drawer +// sideways; screenshots of the layers, an opened two-axis tensor, the kernel as tiles, the comparison and the +// unreadable file (with --shots , written there too). +// It fails on any script error and any failed request. +// node tests/browser_project_workspace_weights.cjs [--shots ] +const assert = require('node:assert/strict'), fs = require('node:fs'), os = require('node:os'), path = require('node:path'); +const { spawn, execFileSync } = require('node:child_process'), { once } = require('node:events'); +const { authenticatedFixture } = require('./auth_helpers.cjs'), { waitForDebugger } = require('./browser_startup.cjs'), { cdpSession } = require('./browser_cdp_session.cjs'), { qaDirectory } = require('./qa_artifacts.cjs'); + +const root = path.resolve(__dirname, '..'); +const argv = process.argv.slice(2), option = name => { const i = argv.indexOf(name); return i >= 0 ? argv[i + 1] : null; }; +assert.ok(process.env.TULDOK_DATABASE_URL, 'TULDOK_DATABASE_URL must name a disposable PostgreSQL cluster'); +const venv = path.join(root, '.venv', 'bin'); +if (fs.existsSync(path.join(venv, 'python'))) process.env.PATH = venv + path.delimiter + process.env.PATH; // auth_helpers runs python3 +const python = fs.existsSync(path.join(venv, 'python')) ? path.join(venv, 'python') : 'python3'; +const IDLE_MS = 15000; // the page's reading while nothing builds (app.js) +const WATCHED = ['summary', 'status', 'build_requests', 'environments', 'runs']; +const CHILD = 'recipes/wt-child', PARENT = 'recipes/wt-parent', PICKLE = 'recipes/wt-pickle'; +const RECIPES = { + 'wt-parent': { title: 'Weights parent', labels: { short: 'WP', trained_at: '2026-10-01' }, change: 'architecture' }, + 'wt-child': { title: 'Weights child', labels: { short: 'WC', trained_at: '2026-10-05' }, change: 'refinement', derived_from: PARENT }, + 'wt-pickle': { title: 'Weights in a pickle', labels: { short: 'WK', trained_at: '2026-10-07' }, change: 'component' } +}; +const MARGIN = 40; // weights.js asks for a row's distribution this near the drawer's view + +const temporary = fs.mkdtempSync(path.join(os.tmpdir(), 'tuldok-weights-browser-')); +const report = qaDirectory(root, 'project-workspace-weights'); +const shots = option('--shots') ? path.resolve(option('--shots')) : null; if (shots) fs.mkdirSync(shots, { recursive: true }); +const children = [], checks = [], errors = [], failures = []; +let server, serverErrors = '', origin, auth, socket, session, send, evaluate, owned = null; +const pause = ms => new Promise(resolve => setTimeout(resolve, ms)); +async function until(fn, label, tries = 300) { for (let i = 0; i < tries; i++) { const value = await fn(); if (value) return value; await pause(100); } throw Error('Timed out: ' + label); } +function check(text) { checks.push(text); console.log('PASS ' + text); } +function launch(command, args, options) { const child = spawn(command, args, options); children.push(child); return child; } +async function stop(child) { if (!child || child.exitCode !== null || child.signalCode !== null) return; const exited = once(child, 'exit'); child.kill('SIGTERM'); await Promise.race([exited, pause(10000)]); if (child.exitCode === null && child.signalCode === null) { child.kill('SIGKILL'); await exited; } } +function findBrowser() { + const candidates = [process.env.BROWSER, '/usr/bin/chromium', '/usr/bin/chromium-browser', '/usr/bin/google-chrome']; + const cache = path.join(os.homedir(), '.cache', 'ms-playwright'); + if (fs.existsSync(cache)) for (const name of fs.readdirSync(cache).filter(n => n.startsWith('chromium_headless_shell-')).sort().reverse()) candidates.push(path.join(cache, name, 'chrome-headless-shell-linux64', 'chrome-headless-shell')); + const found = candidates.find(candidate => candidate && fs.existsSync(candidate)); + assert.ok(found, 'No headless browser: set BROWSER'); + return found; +} +/** Drops the project's schema and the catalog's from the disposable database, so each run imports afresh. */ +function dropOwned(folder, catalog) { + const id = JSON.parse(fs.readFileSync(path.join(folder, 'tuldok.json'), 'utf8')).id; + execFileSync(python, ['-c', `import json, os, pathlib, sys, psycopg +from psycopg import sql +from tuldok_project import store +store.drop_project(sys.argv[1], os.environ['TULDOK_DATABASE_URL']) +root = pathlib.Path(sys.argv[2]) +if root.exists(): + with psycopg.connect(os.environ['TULDOK_DATABASE_URL'], autocommit=True) as c: + for p in root.rglob('.tuldok.json'): + v = json.loads(p.read_text()) + name = 'projection_' + v['projection_id'] if v.get('version') == 2 else 'catalog_' + v['dataset_id'] + c.execute(sql.SQL('DROP SCHEMA IF EXISTS {} CASCADE').format(sql.Identifier(name))) +`, id, catalog], { cwd: root, stdio: ['ignore', 'pipe', 'pipe'] }); +} +async function contract(name) { + const capabilities = await (await auth.fetch(origin + '/api/agent/capabilities')).json(); + const operation = capabilities.operations.find(item => item.id === 'project.' + name), c = operation.contracts[operation.contracts.length - 1]; + return 'project.' + name + '/' + c.version + '/' + c.sha256; +} +/** An operation as the owner. */ +async function api(name, body = {}) { + const headers = { 'Content-Type': 'application/json', 'Tuldok-Operation-Contract': await contract(name) }; + const response = await auth.fetch(origin + '/api/project/' + name, { method: 'POST', headers, body: JSON.stringify(body) }); + const value = await response.json(); assert.equal(response.status, 200, name + ': ' + JSON.stringify(value)); return value; +} + +// ---- The page's requests, from the browser's network, with their bodies ------------------------------------------------ +const calls = new Map(), finished = []; +function network(event) { + const p = event.params; + if (event.method === 'Network.requestWillBeSent' && /\/api\/project\/[a-z_]+$/.test(p.request.url)) { let body = null; try { body = p.request.postData ? JSON.parse(p.request.postData) : null; } catch (_) { body = null; } calls.set(p.requestId, { name: p.request.url.split('/').pop(), body, sent: Date.now() }); } + if ((event.method === 'Network.loadingFinished' || event.method === 'Network.loadingFailed') && calls.has(p.requestId)) { finished.push(Object.assign(calls.get(p.requestId), { done: Date.now() })); calls.delete(p.requestId); } +} +const asked = (name, since = 0, test = () => true) => finished.concat([...calls.values()]).filter(f => f.name === name && f.sent >= since && test(f.body || {})); +async function reading(since, names, label, tries = 300) { + await until(() => names.every(name => finished.some(f => f.name === name && f.sent >= since)), 'a reading: ' + label, tries); + await until(() => !calls.size && Date.now() - Math.max(0, ...finished.map(f => f.done)) > 700, 'the reading done: ' + label, 300); + await settled(label); +} +/** Waits until nothing reads: no "Reading…", nothing busy in the drawer, no request of the project in flight. */ +async function settled(label) { + await until(() => evaluate(`(() => { const reading = e => [...e.querySelectorAll('.note')].some(n => n.textContent === 'Reading…'); return !reading(document.getElementById('main')) && !reading(document.getElementById('aside')) && !document.querySelector('#aside [aria-busy]'); })()`) .then(ok => ok && !calls.size), 'settled: ' + label); + await pause(200); +} +async function hash(value) { await evaluate(`location.hash = ${JSON.stringify('#' + value)}`); await settled('#' + value); await pause(200); await settled('#' + value); } +const byKey = key => `[data-key=${JSON.stringify(key)}]`; +async function centre(selector) { + for (let moved = 0; ; moved++) { + const at = await until(() => evaluate(`(() => { const e = [...document.querySelectorAll(${JSON.stringify(selector)})].find(e => e.offsetParent !== null); if (!e) return null; e.scrollIntoView({ block: 'nearest', inline: 'nearest' }); const r = e.getBoundingClientRect(), x = r.left + r.width / 2, y = r.top + r.height / 2, hit = document.elementFromPoint(x, y); return { x, y, ok: !!hit && (hit === e || e.contains(hit)) }; })()`), 'shown: ' + selector, 100); + if (at.ok) return at; + if (moved > 20) throw Error('The target of ' + selector + ' is never under its point'); + await pause(100); + } +} +async function mouse(type, x, y, buttons = 0) { await send('Input.dispatchMouseEvent', { type, x, y, button: type === 'mouseMoved' ? (buttons ? 'left' : 'none') : 'left', buttons, clickCount: type === 'mouseMoved' ? 0 : 1 }); } +async function press(selector) { const { x, y } = await centre(selector); await mouse('mouseMoved', x, y); await mouse('mousePressed', x, y, 1); await mouse('mouseReleased', x, y); } +async function key(name, code) { for (const type of ['rawKeyDown', 'keyUp']) await send('Input.dispatchKeyEvent', { type, key: name, code: name, windowsVirtualKeyCode: code, nativeVirtualKeyCode: code }); } +/** Chooses an option of a select by the keyboard's way of changing it (the change event the page listens to). */ +async function choose(selector, value) { await evaluate(`(() => { const s = document.querySelector(${JSON.stringify(selector)}); s.focus(); s.value = ${JSON.stringify(value)}; s.dispatchEvent(new Event('change', { bubbles: true })); return true; })()`); } +async function frames() { await evaluate('new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve)))'); } +async function shot(name) { + await frames(); + const png = Buffer.from((await send('Page.captureScreenshot', { format: 'png', captureBeyondViewport: false })).data, 'base64'); + fs.writeFileSync(path.join(report, name + '.png'), png); if (shots) fs.writeFileSync(path.join(shots, name + '.png'), png); +} +/** What a canvas shows: how many pixels are drawn, how many colours, and a sum that changes when the drawing does. */ +const PIXELS = `c => { if (!c || !c.width) return null; const d = c.getContext('2d').getImageData(0, 0, c.width, c.height).data; let drawn = 0, sum = 0; const colours = new Set(); for (let i = 0; i < d.length; i += 4) if (d[i + 3]) { drawn++; sum = (sum + (i / 4 + 1) * (d[i] * 3 + d[i + 1] * 5 + d[i + 2] * 7)) % 2147483647; if (colours.size < 64) colours.add(d[i] + ',' + d[i + 1] + ',' + d[i + 2]); } return { drawn, colours: colours.size, sum, label: c.getAttribute('aria-label') || '' }; }`; +const pixels = selector => evaluate(`(${PIXELS})(document.querySelector(${JSON.stringify(selector)}))`); +const tilesNow = () => evaluate(`(() => { const p = document.querySelector('#aside .wts-pics'); return { mode: p.dataset.mode, first: Number(p.dataset.first), index: JSON.parse(p.dataset.index), across: p.dataset.across, tiles: p.querySelectorAll('canvas').length, captions: [...p.querySelectorAll('figcaption')].map(c => c.textContent), sums: [...p.querySelectorAll('canvas')].map(c => (${PIXELS})(c)), range: document.querySelector('#aside .wts-range').textContent }; })()`); +const close = (a, b, label, tol = 1e-6) => assert.ok(Math.abs(a - b) <= tol * Math.max(1, Math.abs(b)), label + ': ' + a + ' is not ' + b); + +// The watcher of browser_project_workspace_still.cjs: added, removed and changed nodes, "Reading…", the scrolls. +const WATCHER = `window.__still = (() => { + const ids = ['tabs', 'strip', 'main', 'aside', 'needs-panel'], el = id => document.getElementById(id); + let counts = null, flash = 0, timer = null; + const name = n => !n ? '?' : n.nodeType === 1 ? n.tagName.toLowerCase() + (typeof n.className === 'string' && n.className ? '.' + n.className.trim().split(/\\s+/).join('.') : '') : '#text ' + JSON.stringify(String(n.data || '').slice(0, 30)); + for (const id of ids) new MutationObserver(list => { + if (!counts) return; + const c = counts[id]; + for (const r of list) { + if (r.type === 'childList') { c.added += r.addedNodes.length; c.removed += r.removedNodes.length; for (const n of [...r.addedNodes, ...r.removedNodes]) if (c.what.length < 6) c.what.push(name(n) + ' in ' + name(r.target)); } + else if (r.type === 'characterData') { const msg = el('strip').querySelector('.msg'); if (msg && r.target === msg.lastChild) c.readAt++; else { c.text++; if (c.what.length < 6) c.what.push('text of ' + name(r.target.parentNode)); } } + else { c.attrs++; if (c.what.length < 6) c.what.push('@' + r.attributeName + ' on ' + name(r.target)); } + } + }).observe(el(id), { childList: true, subtree: true, characterData: true, attributes: true }); + const where = (e, top) => { const p = []; while (e && e !== top) { p.unshift(e.tagName.toLowerCase() + ':' + [...e.parentElement.children].indexOf(e)); e = e.parentElement; } return p.join('>'); }; + function scrolls() { + const out = {}; + for (const top of [el('main'), el('drawer')]) { out[top.id] = [top.scrollLeft, top.scrollTop].map(Math.round); for (const e of top.querySelectorAll('*')) if (e.scrollLeft || e.scrollTop) out[top.id + ' ' + where(e, top)] = [Math.round(e.scrollLeft), Math.round(e.scrollTop)]; } + return out; + } + return { + start() { counts = {}; for (const id of ids) { counts[id] = { added: 0, removed: 0, attrs: 0, text: 0, readAt: 0, what: [] }; for (const e of el(id).querySelectorAll('*')) e.__seen = 1; } flash = 0; clearInterval(timer); timer = setInterval(() => { if ((el('main').textContent + el('aside').textContent).includes('Reading…')) flash++; }, 50); }, + stop() { clearInterval(timer); const fresh = {}; for (const id of ids) fresh[id] = [...el(id).querySelectorAll('*')].filter(e => !e.__seen).length; const r = { counts, flash, fresh, scrolls: scrolls() }; counts = null; return r; }, + scrolls + }; +})(); true`; +const touched = (r, ids) => ids.filter(id => { const c = r.counts[id]; return c.added || c.removed || c.attrs || c.text || r.fresh[id]; }).map(id => id + ' ' + JSON.stringify(r.counts[id]) + ' new ' + r.fresh[id]); + +/** The lowest and highest of tiles of the fixture's five-axis kernel (C order), across axis 0 from first, drawn on axes 3 and 4, at index on axes 1 and 2. */ +function tileRange(values, shape, first, count, index, minus = null) { + let lo = Infinity, hi = -Infinity; + const at = i => [i[0] * shape[1] * shape[2] * shape[3] * shape[4] + i[1] * shape[2] * shape[3] * shape[4] + i[2] * shape[3] * shape[4] + i[3] * shape[4] + i[4]]; + for (let t = first; t < first + count; t++) for (let r = 0; r < shape[3]; r++) for (let c = 0; c < shape[4]; c++) { + const k = at([t, index[1], index[2], r, c])[0], v = minus ? Math.fround(Math.fround(values[k]) - Math.fround(minus[k])) : values[k]; + lo = Math.min(lo, v); hi = Math.max(hi, v); + } + return [lo, hi]; +} + +(async () => { + // ---- The fixture: minimal + three recipes of earlier work, in Git; their products adopted ------------------------------------ + fs.cpSync(path.join(root, 'tests', 'fixtures', 'tuldok_project', 'minimal'), path.join(temporary, 'fixture'), { recursive: true }); + const folder = path.join(temporary, 'fixture', 'project'); + for (const [name, r] of Object.entries(RECIPES)) fs.writeFileSync(path.join(folder, 'recipes', name + '.json'), JSON.stringify(Object.assign({ format: 'tuldok_definition_v1', kind: 'recipe', title: r.title, description: 'Weights for the browser check of a model\'s weights.', labels: r.labels, + earlier_work: { rebuild: 'no', reason: 'Written by the browser check of the weights; only its weights remain.' }, model: 'models/stepper', group: 'steppers', change: r.change }, r.derived_from ? { derived_from: r.derived_from } : {}), null, 2) + '\n'); + const git = ['-c', 'user.name=Tuldok Test', '-c', 'user.email=test@example.invalid', '-c', 'commit.gpgsign=false', '-c', 'init.defaultBranch=main', '-C', path.join(temporary, 'fixture')]; + execFileSync('git', [...git, 'init', '-q']); execFileSync('git', [...git, 'add', '-A']); execFileSync('git', [...git, 'commit', '-q', '-m', 'The fixture.']); + const files = path.join(temporary, 'weights'); + const X = JSON.parse(execFileSync(python, [path.join(root, 'tests', 'project_weights_browser_fixture.py'), '--out', files]).toString()); + const home = path.join(temporary, 'home'), catalog = path.join(temporary, 'catalog'); fs.mkdirSync(home); + const env = { ...process.env, TULDOK_PROJECT_HOME: home, TULDOK_SETTINGS: path.join(temporary, 'settings.json') }; + owned = [folder, catalog]; dropOwned(folder, catalog); + const cli = (...args) => execFileSync(python, ['-m', 'tuldok_project', ...args], { cwd: root, env, stdio: ['ignore', 'pipe', 'pipe'] }).toString(); + const manifest = path.join(temporary, 'adopt.json'); + fs.writeFileSync(manifest, JSON.stringify({ format: 'tuldok_adoption_v1', products: [ + { reference: PARENT, files: { 'weights.npz': path.join(files, 'parent', 'weights.npz') } }, + { reference: CHILD, files: { 'weights.npz': path.join(files, 'child', 'weights.npz'), 'initial-weights.npz': path.join(files, 'child', 'initial-weights.npz') } }, + { reference: PICKLE, files: { 'model.pt': path.join(files, 'pickle', 'model.pt') } } + ] })); + cli('adopt', folder, manifest, '--copy'); + let output = ''; + server = launch(python, ['-u', 'app.py', '--port', '0', '--data', catalog, '--project-folder', folder], { cwd: root, env, stdio: ['ignore', 'pipe', 'pipe'] }); + server.stdout.on('data', chunk => { output += chunk; }); server.stderr.on('data', chunk => { serverErrors += chunk; }); + const port = await until(() => { if (server.exitCode !== null) throw Error('Tuldok exited: ' + serverErrors); return output.match(/127\.0\.0\.1:(\d+)/)?.[1]; }, 'Tuldok start-up', 3000); + origin = 'http://127.0.0.1:' + port; + auth = authenticatedFixture(); await auth.register(origin, catalog, root); + const products = (await api('products')).products, runOf = ref => products.find(p => p.reference === ref).run_id; + const pickled = (await api('weights', { run: runOf(PICKLE) })).files[0]; + assert.equal(pickled.readable, false); + + const browser = launch(findBrowser(), ['--headless', '--no-sandbox', '--disable-gpu', '--no-first-run', '--hide-scrollbars', '--remote-debugging-port=0', '--window-size=1440,900', '--user-data-dir=' + path.join(temporary, 'browser'), 'about:blank'], { stdio: 'ignore', env: { ...process.env, XDG_CONFIG_HOME: temporary, XDG_CACHE_HOME: temporary } }); + const debugPort = await waitForDebugger(browser, path.join(temporary, 'browser', 'DevToolsActivePort')); + const target = (await (await fetch('http://127.0.0.1:' + debugPort + '/json')).json()).find(item => item.type === 'page'); + socket = new WebSocket(target.webSocketDebuggerUrl); await once(socket, 'open'); + session = cdpSession(socket, { timeoutMs: 60000, onEvent: event => { + network(event); + if (event.method === 'Runtime.exceptionThrown') errors.push(event.params.exceptionDetails.exception?.description || event.params.exceptionDetails.text); + if (event.method === 'Runtime.consoleAPICalled' && event.params.type === 'error') errors.push(event.params.args.map(a => a.value ?? a.description).join(' ')); + if (event.method === 'Log.entryAdded' && event.params.entry.level === 'error') errors.push(event.params.entry.text + ' ' + (event.params.entry.url || '')); + if (event.method === 'Network.loadingFailed' && !event.params.canceled) failures.push({ id: event.params.requestId, error: event.params.errorText }); + if (event.method === 'Network.responseReceived' && event.params.response.status >= 400) failures.push({ url: event.params.response.url, status: event.params.response.status }); + } }); + send = session.send; + evaluate = async expression => { const result = await send('Runtime.evaluate', { expression, awaitPromise: true, returnByValue: true }); if (result.exceptionDetails) throw Error(JSON.stringify(result.exceptionDetails)); return result.result.value; }; + await send('Page.enable'); await send('Runtime.enable'); await send('Network.enable'); await send('Log.enable'); + const size = async (width, height) => send('Emulation.setDeviceMetricsOverride', { width, height, deviceScaleFactor: 1, mobile: false }); + const theme = async name => { await send('Emulation.setEmulatedMedia', { features: [{ name: 'prefers-color-scheme', value: name }, { name: 'prefers-reduced-motion', value: 'reduce' }] }); }; + await auth.browser(send, origin); // the owner's session + const model = ref => 'map/' + encodeURIComponent(ref); + const load = async (name, place) => { + await theme(name); + await send('Page.navigate', { url: 'about:blank' }); await pause(100); // a page of its own, not a change of hash + await send('Page.navigate', { url: origin + '/?theme=' + name + '#' + place }); + await until(() => evaluate(`document.readyState === 'complete' && !!document.getElementById('needs-btn') && !document.getElementById('needs-btn').disabled`), 'the project read', 1200); + await settled('opened ' + place); + }; + const block = () => evaluate(`(() => { const w = document.querySelector('#aside .wts'); if (!w) return null; return { size: w.querySelector('.wts-size').textContent, path: (w.querySelector('.wts-path') || {}).textContent || null, reason: (w.querySelector('.wts-reason') || {}).textContent || null, table: !!w.querySelector('table'), compare: !!w.querySelector('[data-key="wts-compare"]'), + rows: [...w.querySelectorAll('tr.wts-row')].map(r => ({ layer: r.dataset.layer, parameters: Number(r.children[1].textContent.replace(/\\D/g, '')), shape: r.querySelector('.wts-shape').textContent, marks: [...r.querySelectorAll('.wts-mark')].map(m => m.textContent), change: r.querySelector('.wts-chg') ? r.querySelector('.wts-chg').dataset.change : null, figure: r.querySelector('.wts-fig') ? r.querySelector('.wts-fig').textContent : null })) }; })()`); + const stats = () => evaluate(`Object.fromEntries([...document.querySelectorAll('#aside .wts-stats dd')].map(d => [d.dataset.stat, d.dataset.value]))`); + const sparks = () => evaluate(`(() => { const d = document.getElementById('drawer'), top = d.getBoundingClientRect(); return [...document.querySelectorAll('#aside canvas.wts-spark')].map(c => { const r = c.getBoundingClientRect(); return { array: c.dataset.array, near: r.bottom > top.top - ${MARGIN} && r.top < top.bottom + ${MARGIN}, drawn: c.dataset.drawn === '1' }; }); })()`); + const summaries32 = (since = 0) => asked('array_summary', since, b => b.bins === 32).map(f => f.body.array); + + // ---- 1 and 2. The derived model's drawer: the file, the layers in file order; distributions asked for as rows come on screen -------- + await size(1440, 640); await load('light', 'map'); + const since2 = Date.now(); + await hash(model(CHILD)); + await until(() => evaluate(`!!document.querySelector('#aside .wts table')`), 'the Weights block'); + await settled('the child\'s drawer'); + const b1 = await block(); + assert.equal(b1.path, 'weights.npz'); + assert.match(b1.size, new RegExp(X.parameters.toLocaleString('en-GB') + ' parameters · ' + X.layers.length + ' layers, 8 tensors'), 'The parameter count is the fixture\'s'); + assert.deepEqual(b1.rows.map(r => r.layer), X.layers.map(l => l.name), 'The layers in file order'); + assert.deepEqual(b1.rows.map(r => r.parameters), X.layers.map(l => l.parameters), 'Each layer\'s parameters'); + assert.deepEqual(b1.rows.map(r => r.shape.split(' · ')[0]), X.layers.map(l => l.tensors[0].shape.join(' × ')), 'The shape of each layer\'s first tensor'); + // 2. Opened below the fold, no row has asked for its distribution; scrolled so that the first rows come on screen, only those ask. + await pause(400); + let seen = await sparks(); + assert.ok(seen.every(s => !s.near), 'At 1440 × 640 the table opens below the drawer\'s view: ' + JSON.stringify(seen)); + assert.deepEqual(summaries32(since2), [], 'No row off screen asked for its distribution'); + await evaluate(`(() => { const d = document.getElementById('drawer'), r = document.querySelectorAll('#aside tr.wts-row')[1].getBoundingClientRect(); d.scrollTop += r.bottom - d.getBoundingClientRect().bottom + 4; return true; })()`); + await until(async () => (await sparks()).filter(s => s.near).every(s => s.drawn), 'the rows on screen drawn'); await pause(400); + seen = await sparks(); + const off = seen.filter(s => !s.near).map(s => s.array); + assert.ok(off.length > 0 && off.length < seen.length, 'Some rows are on screen and some below: ' + JSON.stringify(seen)); + assert.deepEqual(summaries32(since2).sort(), seen.filter(s => s.near).map(s => s.array).sort(), 'Only the rows on screen asked for their distribution'); + const before2 = summaries32(since2).length; + await evaluate(`(() => { const d = document.getElementById('drawer'); d.scrollTop = d.scrollHeight; return true; })()`); + await until(async () => (await sparks()).every(s => s.drawn), 'every row drawn once on screen'); + await evaluate(`(() => { const d = document.getElementById('drawer'); d.scrollTop = 0; return true; })()`); await pause(300); + await evaluate(`(() => { const d = document.getElementById('drawer'); d.scrollTop = d.scrollHeight; return true; })()`); await pause(300); + const all2 = summaries32(since2); + assert.deepEqual(all2.slice().sort(), X.layers.map(l => l.tensors[0].name).sort(), 'Each row asked once, for its first tensor'); + const spark = await pixels('#aside canvas.wts-spark'); + assert.ok(spark.drawn > 20, 'A distribution is drawn: ' + JSON.stringify(spark)); + // The third model: the reason and nothing else; the parent: no comparison offered. + await hash(model(PICKLE)); + await until(() => evaluate(`!!document.querySelector('#aside .wts')`), 'the pickle\'s Weights'); + const b3 = await block(); + assert.equal(b3.reason, pickled.reason, 'The reason is the server\'s'); assert.equal(b3.path, 'model.pt'); assert.equal(b3.table, false); assert.equal(b3.compare, false); + assert.equal(await evaluate(`[...document.querySelector('#aside .wts').children].map(e => e.className || e.tagName).join(' ')`), 'H3 wts-head empty wts-reason', 'Nothing else is shown'); + await hash(model(PARENT)); await until(() => evaluate(`!!document.querySelector('#aside .wts table')`), 'the parent\'s Weights'); + const bp = await block(); assert.equal(bp.compare, false, 'The parent has nothing to compare with'); + assert.match(bp.size, new RegExp(X.parent_parameters.toLocaleString('en-GB') + ' parameters')); + await hash('map/' + encodeURIComponent('recipes/early-fit')); + assert.equal(await evaluate(`!!document.querySelector('#aside .wts-box') && document.querySelector('#aside .wts-box').hidden`), true, 'A model without a product has no Weights block'); + check('1. ' + CHILD + ': "' + b1.size + '", layers ' + b1.rows.map(r => r.layer + ' (' + r.parameters + ', ' + r.shape + ')').join(', ') + '; ' + PICKLE + ' shows only "' + b3.reason + '"; the parent offers no comparison; early-fit has no block'); + check('2. At 1440 × 640 the drawer first asked for ' + before2 + ' distributions, those of its rows on screen, not for ' + off.join(', ') + '; scrolled down and back, each of the ' + all2.length + ' rows had asked once'); + + // ---- 3. A tensor opened: a two-axis tensor, then the five-axis kernel as tiles; the slider and the pages ------------------------ + await size(1440, 900); await hash(model(CHILD)); + await press(byKey('wts-layer-head')); await settled('head opened'); + const hs = await stats(), xh = X.stats['head.weight']; + assert.deepEqual(JSON.parse(hs.range), [xh.min, xh.max], 'head.weight\'s range'); close(Number(hs.mean), xh.mean, 'head.weight\'s mean'); close(Number(hs.std), xh.std, 'head.weight\'s spread'); + assert.equal(Number(hs.zeros), xh.zeros); assert.equal(Number(hs.count), xh.count); + const tensors = await evaluate(`[...document.querySelectorAll('#aside .wts-tensors button')].map(b => b.textContent + ':' + b.getAttribute('aria-pressed'))`); + assert.deepEqual(tensors, ['weight:true', 'bias:false'], 'A layer of two tensors offers both, the first opened'); + const head = await pixels('#aside .wts-pics.one canvas'); + assert.ok(head.drawn > 200 && head.colours > 4, 'The two-axis tensor is drawn as one image: ' + JSON.stringify(head)); + assert.match(head.label, /^3 by 16 values of head\.weight \(this file\), from -1\.5 to 2$/); + const hist = await pixels('#aside canvas.wts-hist'); assert.ok(hist.drawn > 100, 'The larger distribution is drawn'); + await press(byKey('wts-tensor-head.bias')); await settled('head.bias'); + assert.match((await pixels('#aside .wts-pics.one canvas')).label, /^The 3 values of head\.bias/); + await press(byKey('wts-layer-conv')); await settled('conv opened'); + const cs = await stats(), xc = X.stats['conv.weight']; + assert.deepEqual(JSON.parse(cs.range), [xc.min, xc.max], 'conv.weight\'s range'); close(Number(cs.mean), xc.mean, 'conv.weight\'s mean'); close(Number(cs.std), xc.std, 'conv.weight\'s spread'); + assert.equal(Number(cs.zeros), xc.zeros); assert.equal(Number(cs.count), 7200); + const shape = [20, 3, 4, 5, 6], t0 = await tilesNow(); + assert.equal(t0.tiles, 16); assert.deepEqual(t0.captions, Array.from({ length: 16 }, (_, i) => String(i))); assert.deepEqual(t0.index, [0, 1, 2, 2, 3]); + assert.ok(t0.sums.every(s => s.drawn > 50), 'Every tile is drawn'); assert.ok(new Set(t0.sums.map(s => s.sum)).size > 12, 'The tiles differ'); + const r0 = tileRange(X.conv_weight, shape, 0, 16, [0, 1, 2]); + const fmtR = async (word, r) => word + ': from ' + await evaluate(`window.LabCharts.fmtSci(${r[0]})`) + ' to ' + await evaluate(`window.LabCharts.fmtSci(${r[1]})`); + assert.ok(t0.range.startsWith(await fmtR('This file', r0)), 'The tiles\' range is the fixture\'s: ' + t0.range); + // The slider on axis 1 (by the keyboard), then the pages. + await evaluate(`document.querySelector('#aside [data-key="wts-axis-slider-1"]').focus(); true`); + await key('ArrowRight', 39); + await until(async () => JSON.stringify((await tilesNow()).index) === '[0,2,2,2,3]', 'the slider moves the tiles'); await settled('slider'); + const t1 = await tilesNow(), r1 = tileRange(X.conv_weight, shape, 0, 16, [0, 2, 2]); + assert.notEqual(t1.sums[0].sum, t0.sums[0].sum, 'The slider changes the tiles'); assert.ok(t1.range.startsWith(await fmtR('This file', r1)), 'At axis 1 = 2 the range is the fixture\'s: ' + t1.range); + assert.equal(await evaluate(`document.activeElement.dataset.key`), 'wts-axis-slider-1', 'The slider keeps the focus'); + await press(byKey('wts-next')); await settled('next tiles'); + const t2 = await tilesNow(), r2 = tileRange(X.conv_weight, shape, 16, 4, [0, 2, 2]); + assert.equal(t2.first, 16); assert.equal(t2.tiles, 4); assert.deepEqual(t2.captions, ['16', '17', '18', '19']); + assert.ok(t2.range.startsWith(await fmtR('This file', r2)), 'The second page\'s range is the fixture\'s: ' + t2.range); + assert.equal(await evaluate(`document.querySelector('#aside .wts-pager').textContent.includes('Tiles 17–20 of 20 along axis 0')`), true); + await press(byKey('wts-prev')); await settled('first tiles'); + await choose('#aside [data-key="wts-across"]', '2'); await settled('across axis 2'); + const t3 = await tilesNow(); + assert.equal(t3.across, '2'); assert.equal(t3.tiles, 4, 'Across axis 2 there are 4 tiles'); assert.deepEqual(await evaluate(`[...document.querySelectorAll('#aside .wts-ctl input[type=range]')].map(r => r.dataset.axis)`), ['0', '1'], 'Sliders for axes 0 and 1'); + await choose('#aside [data-key="wts-across"]', '0'); await settled('across axis 0'); + check('3. head.weight: range ' + hs.range + ', mean ' + hs.mean + ', spread ' + hs.std + ', zeros ' + hs.zeros + ' as the fixture\'s, drawn as one 3 × 16 image; conv.weight: range ' + cs.range + ', mean ' + cs.mean + ', zeros ' + cs.zeros + ', 16 tiles ("' + t0.range.split(',')[0] + '"); axis 1 to 2 by the keyboard: "' + t1.range.split(',')[0] + '"; Next: tiles 16–19, "' + t2.range.split(',')[0] + '"; across axis 2: 4 tiles'); + + // ---- 4. Comparing: with the starting weights, with the parent; this, the other, the difference ------------------------------ + const since4 = Date.now(); + await choose('#aside [data-key="wts-compare"]', 'start'); await settled('compare with the start'); + assert.equal(asked('weights_compare', since4).length, 1, 'One weights_compare for the choice'); + const b4 = await block(); + for (const r of b4.rows) { + const want = X.against_initial.relative[r.layer]; + if (want === null) { assert.equal(r.change, 'zero', r.layer + ' started at zero'); continue; } + close(Number(r.change), want, r.layer + '\'s change against its initial weights', 1e-9); + } + assert.ok(b4.rows.find(r => r.layer === 'scale').figure === null && (await evaluate(`document.querySelector('#aside tr[data-layer="scale"] .wts-zero').textContent`)) === 'from zero'); + const widths = await evaluate(`Object.fromEntries([...document.querySelectorAll('#aside tr.wts-row')].filter(r => r.querySelector('.wts-cbar i')).map(r => [r.dataset.layer, parseFloat(r.querySelector('.wts-cbar i').style.width)]))`); + assert.equal(Math.max(...Object.values(widths)), 100, 'The largest change fills its bar'); + close(widths['encoder.0'], 100 * X.against_initial.relative['encoder.0'] / X.against_initial.relative.conv, 'encoder.0\'s bar is scaled to the largest', 1e-3); + // Sorted by change, the largest first. + await press(byKey('wts-sort-change')); await settled('sorted by change'); + const sorted = (await block()).rows.map(r => r.layer); + assert.deepEqual(sorted, ['scale'].concat(Object.entries(X.against_initial.relative).filter(([, v]) => v !== null).sort((a, b) => b[1] - a[1]).map(([k]) => k)), 'Sorted by change'); + await press(byKey('wts-sort-file')); await settled('file order'); + // The kernel still open: this, then the difference. + const this4 = await tilesNow(); + assert.equal(this4.mode, 'this'); + await press(byKey('wts-mode-difference')); await settled('difference'); + const diff4 = await tilesNow(), rd = tileRange(X.conv_weight, shape, diff4.first, diff4.tiles, diff4.index, X.conv_weight_initial); + assert.equal(diff4.mode, 'difference'); + assert.ok(diff4.sums.every(s => s.drawn > 50), 'The difference is drawn'); + assert.notEqual(diff4.sums[0].sum, this4.sums[0].sum, '"Difference" draws a different image from "this"'); + assert.ok(diff4.range.startsWith(await fmtR('This minus the other', rd)), 'The difference\'s range is the fixture\'s: ' + diff4.range); + await press(byKey('wts-mode-other')); await settled('the other'); + const other4 = await tilesNow(), ro = tileRange(X.conv_weight_initial, shape, other4.first, other4.tiles, other4.index); + assert.ok(other4.range.startsWith(await fmtR('The other file', ro)), 'The other\'s range is the initial weights\': ' + other4.range); + await shot('light-1440-compare-difference-check'); + await press(byKey('wts-mode-difference')); await settled('difference again'); + const since4b = Date.now(); + const parentKey = await evaluate(`[...document.querySelectorAll('#aside [data-key="wts-compare"] option')].find(o => o.value.startsWith('model')).value`); + await choose('#aside [data-key="wts-compare"]', parentKey); await settled('compare with the parent'); + assert.equal(asked('weights_compare', since4b).length, 1, 'One weights_compare for the parent'); + const b5 = await block(); + for (const r of b5.rows) { + const want = X.against_parent.relative[r.layer]; + if (want === undefined) { assert.equal(r.change, 'none', r.layer + ' is not compared'); continue; } + close(Number(r.change), want, r.layer + '\'s change against the parent', 1e-9); + } + assert.deepEqual(b5.rows.find(r => r.layer === 'head').marks, ['weight reshaped']); assert.deepEqual(b5.rows.find(r => r.layer === 'extra').marks, ['only here']); + assert.match(await evaluate(`document.querySelector('#aside .wts-there').textContent`), /Only in the other: old\.weight\./); + check('4. Against initial-weights.npz (one weights_compare): ' + b4.rows.map(r => r.layer + ' ' + (r.figure || r.change)).join(', ') + ', as the fixture computes; sorted by change: ' + sorted.join(', ') + '; the difference drawn apart from this, "' + diff4.range.split(',')[0] + '"; against the parent (one more): ' + b5.rows.map(r => r.layer + ' ' + (r.figure || r.change) + (r.marks.length ? ' [' + r.marks.join(', ') + ']' : '')).join(', ') + ', old.weight only in the other'); + + // ---- 5. Nothing changed: the window regains focus, the timer reads --------------------------------------------------------- + await choose('#aside [data-key="wts-compare"]', 'start'); await settled('compare with the start again'); + await press(byKey('wts-mode-difference')); await settled('difference'); + await evaluate(`(() => { const d = document.getElementById('drawer'); d.scrollTop = Math.min(d.scrollHeight, 500); return true; })()`); await pause(400); await settled('scrolled'); + await evaluate(WATCHER); + const rows5 = []; + for (const cause of ['focus', 'timer']) { + const before = await evaluate(`window.__still.scrolls()`), since = Date.now(); + await evaluate(`window.__still.start(); true`); + if (cause === 'focus') { await evaluate(`window.dispatchEvent(new Event('focus')); true`); await reading(since, WATCHED.concat(['map']), 'focus'); } + else await reading(since, WATCHED, 'the timer', Math.round((IDLE_MS + 15000) / 100)); + const r = await evaluate(`window.__still.stop()`); + assert.deepEqual(touched(r, ['tabs', 'strip', 'main', 'aside', 'needs-panel']), [], cause + ': nothing is touched'); + assert.equal(r.flash, 0, cause + ': "Reading…" is never shown'); assert.deepEqual(r.scrolls, before, cause + ': every scroll stays'); + assert.equal(asked('weights_compare', since).length + asked('array_summary', since).length + asked('array_tiles', since).length + asked('weights', since).length, 0, cause + ': nothing of the weights is asked again'); + rows5.push(cause + ': 0 nodes added or removed, 0 changed, nothing of the weights asked'); + } + // Something changed elsewhere (a definition added to the project folder, which status reports): the drawer is drawn again in place, the block keeping its comparison, the tensor opened and its mode. + const before5 = await evaluate(`({ scroll: document.getElementById('drawer').scrollTop, compare: document.querySelector('#aside [data-key="wts-compare"]').value, mode: document.querySelector('#aside .wts-pics').dataset.mode, open: document.querySelector('#aside [aria-expanded="true"]').dataset.key })`); + const tilesBefore = await tilesNow(), since5 = Date.now(); + await evaluate(`window.__still.start(); true`); + fs.writeFileSync(path.join(folder, 'datasets', 'added-elsewhere.json'), JSON.stringify(Object.assign(JSON.parse(fs.readFileSync(path.join(folder, 'datasets', 'waves.json'), 'utf8')), { title: 'Added elsewhere' }), null, 2) + '\n'); + await evaluate(`window.dispatchEvent(new Event('focus')); true`); await reading(since5, WATCHED.concat(['map']), 'a file added'); + await until(() => evaluate(`!!document.querySelector('#aside .wts-pics canvas')`), 'the block drawn again'); await settled('drawn again'); + const r5 = await evaluate(`window.__still.stop()`); + const after5 = await evaluate(`({ scroll: document.getElementById('drawer').scrollTop, compare: document.querySelector('#aside [data-key="wts-compare"]').value, mode: document.querySelector('#aside .wts-pics').dataset.mode, open: document.querySelector('#aside [aria-expanded="true"]').dataset.key })`); + const tilesAfter = await tilesNow(); + assert.ok(r5.fresh.aside > 0, 'The drawer was drawn again: ' + JSON.stringify(r5.counts.aside)); + assert.equal(r5.flash, 0, '"Reading…" is never shown when the drawer is drawn again'); + assert.deepEqual(after5, before5, 'The scroll, the comparison, the layer opened and the mode are kept'); + assert.deepEqual(tilesAfter.sums.map(s => s.sum), tilesBefore.sums.map(s => s.sum), 'The tiles are drawn as before'); + assert.equal(asked('array_summary', since5).length, 0, 'No distribution is asked for again'); + rows5.push('a file added elsewhere: the drawer drawn again in place (' + r5.fresh.aside + ' new nodes, ' + asked('weights_compare', since5).length + ' weights_compare asked again), its scroll, comparison, opened layer and mode kept, no "Reading…"'); + check('5. With ' + CHILD + '\'s drawer open, compared with its starting weights and the kernel\'s difference shown: ' + rows5.join('; ')); + + // ---- 6. Light and dark, two sizes: nothing blank, nothing overflowing the drawer; the screenshots ----------------------------------- + const seen6 = []; + const scrollTo = async selector => { await evaluate(`(() => { const e = document.querySelector(${JSON.stringify(selector)}); e.scrollIntoView({ block: 'start' }); return true; })()`); await pause(250); await settled('scrolled to ' + selector); }; + const sound = async tag => { + const r = await evaluate(`(() => { const w = document.querySelector('#aside .wts'), d = document.getElementById('drawer'); const blank = [...w.querySelectorAll('canvas')].filter(c => c.getBoundingClientRect().height > 0).map(c => { if (!c.width) return 0; const x = c.getContext('2d').getImageData(0, 0, c.width, c.height).data; let n = 0; for (let i = 3; i < x.length; i += 4) if (x[i]) n++; return n; }); const wide = [...w.querySelectorAll('*')].filter(e => e.getBoundingClientRect().right > d.getBoundingClientRect().right - 1 && e.getBoundingClientRect().width > 0).map(e => e.tagName + '.' + e.className); return { blank, over: d.scrollWidth - d.clientWidth, page: document.documentElement.scrollWidth - innerWidth, wide: wide.slice(0, 4) }; })()`); + assert.ok(r.blank.every(n => n > 20), tag + ': no blank canvas ' + JSON.stringify(r.blank)); + assert.ok(r.over <= 1 && r.page <= 0, tag + ': nothing overflows the drawer sideways ' + JSON.stringify(r)); + seen6.push(tag + ' (' + r.blank.length + ' canvases)'); + }; + for (const [w, hgt] of [[1440, 900], [1000, 800]]) for (const name of ['light', 'dark']) { + const tag = name + '-' + w; + await size(w, hgt); await load(name, model(CHILD)); + await until(() => evaluate(`!!document.querySelector('#aside .wts table')`), 'the Weights block'); + await scrollTo('#aside .wts'); await until(async () => (await sparks()).filter(s => s.near).every(s => s.drawn), 'the rows drawn'); + await sound(tag + ' layers'); await shot(tag + '-1-layers'); + await press(byKey('wts-layer-head')); await settled('head'); + await scrollTo('#aside .wts-tensor'); await sound(tag + ' two-axis'); await shot(tag + '-2-tensor-2d'); + await press(byKey('wts-layer-conv')); await settled('conv'); + await scrollTo('#aside .wts-tensor'); await sound(tag + ' kernel'); await shot(tag + '-3-kernel-tiles'); + await evaluate(`(() => { const e = document.querySelector('#aside .wts-pics'); e.scrollIntoView({ block: 'start' }); return true; })()`); await pause(200); await shot(tag + '-3b-kernel-tiles-end'); + await choose('#aside [data-key="wts-compare"]', 'start'); await settled('compare'); + await scrollTo('#aside .wts'); await sound(tag + ' compare'); await shot(tag + '-4-compare-start'); + await evaluate(`(() => { document.querySelector('#aside tr[data-layer="scale"]').scrollIntoView({ block: 'end' }); return true; })()`); await pause(200); await shot(tag + '-4b-compare-from-zero'); + await press(byKey('wts-mode-difference')); await settled('difference'); + await scrollTo('#aside .wts-tensor'); await sound(tag + ' difference'); await shot(tag + '-5-compare-difference'); + await hash(model(PICKLE)); await until(() => evaluate(`!!document.querySelector('#aside .wts-reason')`), 'the reason'); + await scrollTo('#aside .wts'); await sound(tag + ' unreadable'); await shot(tag + '-6-unreadable'); + } + await size(1440, 900); + check('6. No canvas blank and nothing overflowing the drawer sideways in light and dark at 1440 × 900 and 1000 × 800: ' + seen6.length + ' views' + (shots ? '; screenshots in ' + shots : '')); + + // ---- Nothing failed --------------------------------------------------------------------------------------------------------- + assert.deepEqual(errors, [], 'Script errors'); + assert.deepEqual(failures, [], 'Failed requests'); + check('No script error, no failed request'); + fs.writeFileSync(path.join(report, 'receipt.json'), JSON.stringify({ status: 'pass', folder, checks }, null, 2) + '\n'); + console.log('Receipt in ' + report); +})().catch(async error => { + process.exitCode = 1; + console.error(error); if (serverErrors) console.error('Server:', serverErrors.slice(-4000)); + console.error('Script errors:', JSON.stringify(errors)); console.error('Failed requests:', JSON.stringify(failures)); + try { if (evaluate) { await shot('failure'); console.error('Drawer:', (await evaluate('document.getElementById("aside").innerText')).slice(0, 2500)); } } catch (_) { /* the page is gone */ } + fs.writeFileSync(path.join(report, 'failure.json'), JSON.stringify({ status: 'failed', error: String(error && error.stack || error), checks, errors, failures }, null, 2) + '\n'); +}).finally(async () => { + try { session?.close(); } catch (_) { /* closed */ } + for (const child of children.reverse()) await stop(child); + if (owned) try { dropOwned(...owned); } catch (error) { console.error('Dropping the disposable schemas failed:', error.message); process.exitCode = 1; } + try { execFileSync('chmod', ['-R', 'u+w', temporary]); } catch (_) { /* nothing was made read-only */ } // finished runs leave their directories read-only + fs.rmSync(temporary, { recursive: true, force: true }); +}); diff --git a/tests/project_weights_browser_fixture.py b/tests/project_weights_browser_fixture.py new file mode 100644 index 00000000..3f2653a0 --- /dev/null +++ b/tests/project_weights_browser_fixture.py @@ -0,0 +1,179 @@ +"""The weights the browser check of a model's weights reads (tests/browser_project_workspace_weights.cjs). + +Written with the standard library only, and adopted by the check as the products of three recipes: + +- parent/weights.npz: the weights of the parent model; +- child/weights.npz and child/initial-weights.npz: the weights of the model derived from it, and those it + started from; +- pickle/model.pt: a file Tuldok lists and never opens. + +The child's tensors, in file order (five layers, 7,416 parameters): + + encoder.0.weight (16, 6) encoder.0.bias (16,) layer encoder.0 + conv.weight (20, 3, 4, 5, 6) conv.bias (20,) layer conv, a five-dimensional kernel + head.weight (3, 16) head.bias (3,) layer head; head.weight[j, k] is j - k / 10 + scale (8,) its own layer; all zeros in initial-weights.npz + extra.weight (5, 5) only in the child + +The parent has the same, except head.weight is (2, 16) (reshaped), extra.weight is missing and it has +old.weight (4, 4) (only in the parent). Every value is a 32-bit float made from a formula. + +It prints, as JSON, what the check compares the page with: the layers and their parameters, the statistics of +some tensors (over the 32-bit values, in 64-bit arithmetic, the deviation of the population), and the relative +change of each layer against the initial weights and against the parent (the norm of the difference over the +norm of the other, both over the tensors of the layer compared; null when the other's norm is zero). +""" +import argparse +import io +import json +import math +import os +import struct +import zipfile + + +def f32(x): + return struct.unpack(' Date: Fri, 13 Nov 2026 17:58:21 -0700 Subject: [PATCH 074/131] feat(workspace): the Annotate tab, and Import and Freeze on the Data tab A tab between Data and Train. A task is chosen or made ("New task": title, dataset, what is recorded, the vocabulary). Its dataset's records are a paged grid with a dot for each one's state; the selected record is shown in the dataset view's own viewers; beside it is the form for the task: the decision alone, one term by radio buttons and the keys 1 to 9, several by checkboxes, a text, boxes drawn on the image, spans marked in the text, segments marked on the waveform and played. Accept, Needs work or Reject; a note; "Keep and next" on Enter; the arrows move. Boxes and segments can be made and changed by keyboard; a span's ends are number fields. Keeping an annotation makes it an unsaved edit: the strip counts annotations with definitions and the same Save writes both. A stale annotation says what changed and can be confirmed or removed. What is typed or drawn in the form is never replaced by a reading; another session's annotation appears in the grid without the form being touched. The Data tab gains two forms that keep a dataset definition as an unsaved edit: Import (files of a directory) and Freeze (a dataset and its tasks into splits). They are built by the existing plan and request. examples/tiny-project gains a few small files of each kind with the script that makes them, an import of them, a class task with saved annotations and a freeze. Co-Authored-By: Claude Fable 5.2 --- app.py | 1 + docs/contracts/project-folder.md | 10 +- .../definition-first-projects/spec-d4.md | 17 + examples/tiny-project/README.md | 23 +- examples/tiny-project/code/make_samples.py | 79 ++ .../tiny-project/code/samples/clouds/ring.ply | 127 +++ .../code/samples/images/shapes.png | Bin 0 -> 151 bytes .../code/samples/meshes/pyramid.obj | 11 + .../code/samples/sounds/two-tones.wav | Bin 0 -> 9644 bytes .../code/samples/texts/greeting.txt | 1 + .../code/samples/texts/weather.txt | 1 + .../project/annotations/sample-quality.json | 9 + .../project/annotations/sample-quality.jsonl | 6 + .../project/datasets/samples-v1.json | 12 + .../project/datasets/samples.json | 10 + static/project-workspace.html | 1 + static/project-workspace/actions.js | 12 +- static/project-workspace/adapter.js | 19 +- static/project-workspace/annotate.js | 817 ++++++++++++++++++ static/project-workspace/app.js | 6 +- static/project-workspace/base.css | 78 ++ static/project-workspace/inside.js | 32 +- static/project-workspace/tabs.js | 13 +- tests/browser_project_workspace_annotate.cjs | 534 ++++++++++++ 24 files changed, 1787 insertions(+), 32 deletions(-) create mode 100644 examples/tiny-project/code/make_samples.py create mode 100644 examples/tiny-project/code/samples/clouds/ring.ply create mode 100644 examples/tiny-project/code/samples/images/shapes.png create mode 100644 examples/tiny-project/code/samples/meshes/pyramid.obj create mode 100644 examples/tiny-project/code/samples/sounds/two-tones.wav create mode 100644 examples/tiny-project/code/samples/texts/greeting.txt create mode 100644 examples/tiny-project/code/samples/texts/weather.txt create mode 100644 examples/tiny-project/project/annotations/sample-quality.json create mode 100644 examples/tiny-project/project/annotations/sample-quality.jsonl create mode 100644 examples/tiny-project/project/datasets/samples-v1.json create mode 100644 examples/tiny-project/project/datasets/samples.json create mode 100644 static/project-workspace/annotate.js create mode 100644 tests/browser_project_workspace_annotate.cjs diff --git a/app.py b/app.py index 59f876e0..3c484e04 100644 --- a/app.py +++ b/app.py @@ -806,6 +806,7 @@ def _get(self): '/project-workspace/editor.js': ('project-workspace/editor.js', 'text/javascript'), '/project-workspace/tabs.js': ('project-workspace/tabs.js', 'text/javascript'), '/project-workspace/inside.js': ('project-workspace/inside.js', 'text/javascript'), + '/project-workspace/annotate.js': ('project-workspace/annotate.js', 'text/javascript'), '/project-workspace/app.js': ('project-workspace/app.js', 'text/javascript'), '/static/vendor/ubuntu-sans/UbuntuSans[wdth,wght].ttf': ('vendor/ubuntu-sans/UbuntuSans[wdth,wght].ttf', 'font/ttf'), '/static/vendor/ubuntu-sans/UbuntuSans-Italic[wdth,wght].ttf': ('vendor/ubuntu-sans/UbuntuSans-Italic[wdth,wght].ttf', 'font/ttf'), diff --git a/docs/contracts/project-folder.md b/docs/contracts/project-folder.md index 342af558..780c4ae8 100644 --- a/docs/contracts/project-folder.md +++ b/docs/contracts/project-folder.md @@ -2085,8 +2085,11 @@ status 2. The app opens the project only for each operation, as the commands do, so files changed on disk are imported before an operation answers and the command line keeps working beside the app. -The page at `/` is the Map workspace: the tabs Map, Data, Train, Benchmarks, -Analysis and Overview over the project, read through the operations below. +The page at `/` is the Map workspace: the tabs Map, Data, Annotate, Train, +Benchmarks, Analysis and Overview over the project, read through the operations +below. Annotate shows a task's records, one in its viewer, and the task's form, +which keeps an annotation with `set_annotation`; Save writes the unsaved +annotations with the unsaved definitions. Each of its controls calls one operation and is drawn only for a session that may call it, so a credential that may only inspect sees a page that changes nothing. The report is linked from the Overview tab. The page reads again @@ -2098,7 +2101,8 @@ request ended or `status` changed) and compares each answer with the one it holds. When none differs nothing on the page is drawn again but the time it was read and the progress of a running build; when one does, what is on screen is drawn again in place, keeping the scroll and the focus, and a drawer holding the editor or the branch form -is left alone except after a control's answer. A reading that fails leaves +is left alone except after a control's answer, as are the forms of New task, +Import and Freeze and an annotation typed or drawn and not kept. A reading that fails leaves the page as it is; the status strip says the project was not read, and why. ### Signing in and issuing an agent credential diff --git a/docs/plans/definition-first-projects/spec-d4.md b/docs/plans/definition-first-projects/spec-d4.md index 9e0e8cee..b1511c50 100644 --- a/docs/plans/definition-first-projects/spec-d4.md +++ b/docs/plans/definition-first-projects/spec-d4.md @@ -236,3 +236,20 @@ What differs from section 6, and what was chosen where it was silent. - **Checked in review** on a source holding links out of it (to a file and to a directory), a link looping back into it, a named pipe, a name that collides with another once made an id, names with spaces, shell characters and non-Latin letters, a name of 240 characters and an empty file: eight records, ids unique and valid, the two links out and the pipe skipped and counted, nothing read from outside the source, nothing written outside the output, the source's files unchanged, and the product read back by spec-d1's reader with every hash. - **Tests:** `tests/test_tuldok_project_steps.py`, 18; project suite 667; agent interface 43 (4 skipped). - **Not verified:** a copy across file systems; a source of very many or very large files; the plan and the run of a step as the page shows them. + +### D4d, the page + +What differs from section 7, and what was chosen where it was silent. + +- **The form is the third column of the main area, not the drawer** the mockup puts it in. The viewer and the form share one draft (a box drawn on the image is listed in the form), and with both in the main area a reading that changed something puts the bar and the grid in place and leaves the viewer and the form alone; the drawer stays free for New task. Below 1,180 px of the tab's own width (a container query, so an open drawer counts) the form goes under the viewer, and below 700 px everything is one column. +- **The tab is drawn in four parts** (bar, grid, viewer, form), each built off the page and put in place only when what it shows differs (spec-w4 R2 to R4); selecting a record sets the tiles' pressed state in place. **What is typed or drawn is a draft in page memory** per task and record, kept until it is kept, reverted or put right: a reading never replaces a form holding one, moving to another record keeps it, a reload loses it (as the editor's typed text). A form holding a draft is kept even when its record's annotation was changed elsewhere meanwhile; Keep then sets it over the other (set_annotation has no "only if unchanged"). The New task, Import and Freeze forms are drawer forms like the branch form: never touched by a reading on the timer or on focus, their text kept in their group's slot. +- **"New task" is a button beside the task select**, not one of its options: arrowing through a closed select fires its change at once, which would open the form while moving through the tasks. +- **"To do" lists the records not annotated, then the drafts**, each in the product's order, paged exactly from the two totals: `annotated_records` takes one state, and merging the two in product order would mean reading every record. +- **A stale annotation whose record is gone** cannot be put right (`set_annotation` refuses a record the product does not have): the form offers "Remove the annotation" (with a confirmation) in place of "Still right". What changed is said in words; for content that differs the two hashes are shown, cut to 12 characters. +- **Keys.** 1 to 9 for `class` and `tags` only. Enter also keeps when the focus is on a decision button or a term's radio or checkbox (it keeps rather than toggling); the arrows on a radio keep their own meaning; keys on a drawing surface or a 3-D viewer are that surface's. +- **Drawing by keyboard.** On the image (boxes) and the waveform (segments), focused: N adds one, [ and ] choose, the arrows move the chosen one (Alt: by 10 px or 0.5 s; otherwise 1 px or 0.05 s), Shift and the arrows resize a box or move a segment's end, Delete removes, P plays a segment, Escape lets go. A **span** is marked by selecting text with the pointer (or "Mark the selected text"); by keyboard its start and end are edited as numbers in the list, since text in a `pre` cannot be selected by keyboard without caret browsing. Offsets are counted in code points from the DOM's UTF-16 offsets, the term tags drawn in the text left out. +- **Limits of the viewers.** Segments need a sound's length, which Tuldok reads from WAV only: on another sound the form says so and shows the plain viewer. Spans can be marked in the part of a text the record answer holds (it says when it is truncated). A boxes, spans or segments task on a record of another kind keeps only a decision and a note. +- **Beyond section 8's files.** `inside.js` exports `viewers` (a record's viewer for a run, the waveform, `paints`, `fit`, `token`, `glyph`, `WORD`); its waveform drawing became the function `wave`, used by its own viewer unchanged. `adapter.js`'s Needs you gains an item for unsaved annotations (with Save, and a button per task opening Annotate on it) and counts changed annotation files with the files changed on disk. The Data tab's dataset drawer gains **Plan build** (for a session that may request), so that a dataset kept by Import or Freeze is planned from where it was made; the plan and the request are the existing ones. The paragraph of `docs/contracts/project-folder.md` that describes the page names the tab. +- **The example.** `examples/tiny-project` gains `code/make_samples.py` and the files it writes under `code/samples` (two texts, a PNG, a WAV, a PLY point cloud, an OBJ mesh; 12.5 KB), `datasets/samples` (import from `samples`), `annotations/sample-quality` (class) with six saved annotations carrying the files' hashes, and `datasets/samples-v1` (freeze, seed 7, train 3 to test 1). `check` reports no problem; built on a committed copy, the freeze takes the five accepted records, four train and one test. The WAV is 8-bit at 8,000 Hz: Chrome refuses a WAV at 2,000 Hz (`MEDIA_ERR_SRC_NOT_SUPPORTED`), found by the check. No test counted the example's definitions; its README's table and step count were brought up to date. +- **The check,** `tests/browser_project_workspace_annotate.cjs`, does what section 9 asks on a project of its own (a record of each kind but `file`, imported), and also: a refusal shown beside the form with nothing lost, the arrows, Revert, a task on a dataset with no product planning it, and the definition texts of New task, Import and Freeze compared byte for byte. +- **Not covered by the check:** a session that may only inspect (controls hidden or disabled, by the same `who` rule as elsewhere); paging beyond 48 records on this tab; an annotation file changed on disk while the page holds drafts; a sound other than WAV; screen readers (the drawing surfaces announce the chosen box or segment through a live region, not heard here). diff --git a/examples/tiny-project/README.md b/examples/tiny-project/README.md index 01bccdec..c55be4b9 100644 --- a/examples/tiny-project/README.md +++ b/examples/tiny-project/README.md @@ -1,7 +1,8 @@ # Tiny project The smallest real Tuldok project: a dataset, a network trained on a GPU, a -benchmark and two charts. Building it end to end takes about a minute, and it +benchmark and two charts, and beside them a few small files of each kind +brought in, annotated and frozen with splits. Building it end to end takes about a minute, and it uses every part of a build: environments, a command per definition, a product passed from one definition to the next, progress lines while training, a benchmark's results imported into the database, and charts drawn from them. @@ -25,6 +26,9 @@ phase are random, and predict the next 16 samples of the clean wave. | `benchmarks/held-out` | `bench.py` scores a subject on the 400 test waves: error (RMSE) and time per wave | | `charts/held-out-ranking` | the subjects ranked by error | | `charts/held-out-tradeoff` | error against time per wave | +| `datasets/samples` | the step `import`: the files under `code/samples` (two texts, a PNG, a WAV, a PLY point cloud and an OBJ mesh, written by `make_samples.py`), one record each | +| `annotations/sample-quality` | a `class` task on `datasets/samples`: whether each sample is clean; its annotations are `annotations/sample-quality.jsonl` | +| `datasets/samples-v1` | the step `freeze`: the samples whose quality is accepted, split three to one from seed 7 | The benchmark has two subjects: `small-net-a`, the trained network, and `predict-zero`, which always predicts zero and shows the error any model has to @@ -72,8 +76,10 @@ P=examples/tiny-project/project .venv/bin/python -m tuldok_project build $P --all ``` -The plan has three build steps after the two environments: `datasets/waves`, -`recipes/small-net-a`, then `benchmarks/held-out` once for each subject. +The plan has five build steps after the two environments: `datasets/waves`, +`recipes/small-net-a`, then `benchmarks/held-out` once for each subject, and +`datasets/samples` and `datasets/samples-v1`, which Tuldok's own steps build +in a moment with no environment. | Step | Time | | --- | --- | @@ -81,6 +87,17 @@ The plan has three build steps after the two environments: `datasets/waves`, | `recipes/small-net-a` | 6,000 updates; well under a minute on a GPU, much of it starting CUDA. The recipe allows 6 minutes | | `benchmarks/held-out` | a few seconds per subject, mostly starting torch | +### The samples, annotated + +`datasets/samples` brings the files under `code/samples` in as records; open +it on the Data tab of the page (`python app.py --data CATALOG --project-folder +$P`) to look inside. On the Annotate tab, `annotations/sample-quality` shows +each record with its annotation; change one, press Keep and next, and Save +writes `annotations/sample-quality.jsonl`. `datasets/samples-v1` takes the +records whose annotation is accepted, as committed, and splits them; build it +again after committing a change to the annotations. To write the samples +again, run `python make_samples.py` from `code/`: the bytes are the same. + ### Watch the training While the recipe runs, in a second terminal: diff --git a/examples/tiny-project/code/make_samples.py b/examples/tiny-project/code/make_samples.py new file mode 100644 index 00000000..9bd26169 --- /dev/null +++ b/examples/tiny-project/code/make_samples.py @@ -0,0 +1,79 @@ +"""Writes samples/, the few small files datasets/samples imports: two texts, a PNG, a WAV, a PLY point cloud and +an OBJ mesh, about thirteen kilobytes in all. Standard library only; the same bytes on every run. + + python make_samples.py (from code/; writes samples/ beside this file) +""" +import io +import math +import os +import struct +import wave +import zlib + +HERE = os.path.dirname(os.path.abspath(__file__)) + + +def png(width, height, boxes): + """An RGB PNG of a pale background with filled rectangles (x, y, w, h, colour).""" + def chunk(kind, data): + return struct.pack('>I', len(data)) + kind + data + struct.pack('>I', zlib.crc32(kind + data)) + + def colour(x, y): + for bx, by, bw, bh, rgb in boxes: + if bx <= x < bx + bw and by <= y < by + bh: + return rgb + return (232, 236, 240) + rows = b''.join(b'\x00' + b''.join(bytes(colour(x, y)) for x in range(width)) for y in range(height)) + return (b'\x89PNG\r\n\x1a\n' + chunk(b'IHDR', struct.pack('>IIBBBBB', width, height, 8, 2, 0, 0, 0)) + + chunk(b'IDAT', zlib.compress(rows, 9)) + chunk(b'IEND', b'')) + + +def wav(rate=8000, seconds=1.2): + """8-bit mono at 8,000 Hz: two tones (0.20 to 0.55 s at 250 Hz, 0.80 to 1.10 s at 400 Hz) with silence around them.""" + frames = int(rate * seconds) + samples = bytearray() + for n in range(frames): + t = n / rate + tone = 250 if 0.20 <= t < 0.55 else 400 if 0.80 <= t < 1.10 else 0 + samples.append(128 + (round(90 * math.sin(2 * math.pi * tone * t)) if tone else 0)) + buffer = io.BytesIO() + with wave.open(buffer, 'wb') as sound: + sound.setnchannels(1) + sound.setsampwidth(1) + sound.setframerate(rate) + sound.writeframes(bytes(samples)) + return buffer.getvalue() + + +def ring(count=120): + lines = ['ply', 'format ascii 1.0', f'element vertex {count}', 'property float x', 'property float y', + 'property float z', 'end_header'] + for n in range(count): + t = 2 * math.pi * n / count + lines.append(f'{math.cos(t):.3f} {math.sin(t):.3f} {0.2 * math.sin(3 * t):.3f}') + return '\n'.join(lines) + '\n' + + +PYRAMID = '\n'.join(['v 0 0 0', 'v 1 0 0', 'v 1 1 0', 'v 0 1 0', 'v 0.5 0.5 0.8', + 'f 1 3 2', 'f 1 4 3', 'f 1 2 5', 'f 2 3 5', 'f 3 4 5', 'f 4 1 5']) + '\n' + +FILES = { + 'texts/greeting.txt': 'Ada Lovelace wrote to Charles Babbage from London 🌍 in 1843.\n', + 'texts/weather.txt': 'Rain over Manila this morning; clear skies in Cebu by the afternoon.\n', + 'images/shapes.png': png(64, 48, [(6, 8, 22, 18, (44, 95, 184)), (36, 20, 20, 22, (210, 101, 47))]), + 'sounds/two-tones.wav': wav(), + 'clouds/ring.ply': ring(), + 'meshes/pyramid.obj': PYRAMID, +} + + +def main(): + for name, data in FILES.items(): + path = os.path.join(HERE, 'samples', *name.split('/')) + os.makedirs(os.path.dirname(path), exist_ok=True) + with open(path, 'wb') as handle: + handle.write(data if isinstance(data, bytes) else data.encode('utf-8')) + + +if __name__ == '__main__': + main() diff --git a/examples/tiny-project/code/samples/clouds/ring.ply b/examples/tiny-project/code/samples/clouds/ring.ply new file mode 100644 index 00000000..7098931e --- /dev/null +++ b/examples/tiny-project/code/samples/clouds/ring.ply @@ -0,0 +1,127 @@ +ply +format ascii 1.0 +element vertex 120 +property float x +property float y +property float z +end_header +1.000 0.000 0.000 +0.999 0.052 0.031 +0.995 0.105 0.062 +0.988 0.156 0.091 +0.978 0.208 0.118 +0.966 0.259 0.141 +0.951 0.309 0.162 +0.934 0.358 0.178 +0.914 0.407 0.190 +0.891 0.454 0.198 +0.866 0.500 0.200 +0.839 0.545 0.198 +0.809 0.588 0.190 +0.777 0.629 0.178 +0.743 0.669 0.162 +0.707 0.707 0.141 +0.669 0.743 0.118 +0.629 0.777 0.091 +0.588 0.809 0.062 +0.545 0.839 0.031 +0.500 0.866 0.000 +0.454 0.891 -0.031 +0.407 0.914 -0.062 +0.358 0.934 -0.091 +0.309 0.951 -0.118 +0.259 0.966 -0.141 +0.208 0.978 -0.162 +0.156 0.988 -0.178 +0.105 0.995 -0.190 +0.052 0.999 -0.198 +0.000 1.000 -0.200 +-0.052 0.999 -0.198 +-0.105 0.995 -0.190 +-0.156 0.988 -0.178 +-0.208 0.978 -0.162 +-0.259 0.966 -0.141 +-0.309 0.951 -0.118 +-0.358 0.934 -0.091 +-0.407 0.914 -0.062 +-0.454 0.891 -0.031 +-0.500 0.866 -0.000 +-0.545 0.839 0.031 +-0.588 0.809 0.062 +-0.629 0.777 0.091 +-0.669 0.743 0.118 +-0.707 0.707 0.141 +-0.743 0.669 0.162 +-0.777 0.629 0.178 +-0.809 0.588 0.190 +-0.839 0.545 0.198 +-0.866 0.500 0.200 +-0.891 0.454 0.198 +-0.914 0.407 0.190 +-0.934 0.358 0.178 +-0.951 0.309 0.162 +-0.966 0.259 0.141 +-0.978 0.208 0.118 +-0.988 0.156 0.091 +-0.995 0.105 0.062 +-0.999 0.052 0.031 +-1.000 0.000 0.000 +-0.999 -0.052 -0.031 +-0.995 -0.105 -0.062 +-0.988 -0.156 -0.091 +-0.978 -0.208 -0.118 +-0.966 -0.259 -0.141 +-0.951 -0.309 -0.162 +-0.934 -0.358 -0.178 +-0.914 -0.407 -0.190 +-0.891 -0.454 -0.198 +-0.866 -0.500 -0.200 +-0.839 -0.545 -0.198 +-0.809 -0.588 -0.190 +-0.777 -0.629 -0.178 +-0.743 -0.669 -0.162 +-0.707 -0.707 -0.141 +-0.669 -0.743 -0.118 +-0.629 -0.777 -0.091 +-0.588 -0.809 -0.062 +-0.545 -0.839 -0.031 +-0.500 -0.866 -0.000 +-0.454 -0.891 0.031 +-0.407 -0.914 0.062 +-0.358 -0.934 0.091 +-0.309 -0.951 0.118 +-0.259 -0.966 0.141 +-0.208 -0.978 0.162 +-0.156 -0.988 0.178 +-0.105 -0.995 0.190 +-0.052 -0.999 0.198 +-0.000 -1.000 0.200 +0.052 -0.999 0.198 +0.105 -0.995 0.190 +0.156 -0.988 0.178 +0.208 -0.978 0.162 +0.259 -0.966 0.141 +0.309 -0.951 0.118 +0.358 -0.934 0.091 +0.407 -0.914 0.062 +0.454 -0.891 0.031 +0.500 -0.866 0.000 +0.545 -0.839 -0.031 +0.588 -0.809 -0.062 +0.629 -0.777 -0.091 +0.669 -0.743 -0.118 +0.707 -0.707 -0.141 +0.743 -0.669 -0.162 +0.777 -0.629 -0.178 +0.809 -0.588 -0.190 +0.839 -0.545 -0.198 +0.866 -0.500 -0.200 +0.891 -0.454 -0.198 +0.914 -0.407 -0.190 +0.934 -0.358 -0.178 +0.951 -0.309 -0.162 +0.966 -0.259 -0.141 +0.978 -0.208 -0.118 +0.988 -0.156 -0.091 +0.995 -0.105 -0.062 +0.999 -0.052 -0.031 diff --git a/examples/tiny-project/code/samples/images/shapes.png b/examples/tiny-project/code/samples/images/shapes.png new file mode 100644 index 0000000000000000000000000000000000000000..eba5f68e51dfd5d0c4d7c200c0a28a2ae13e9fc0 GIT binary patch literal 151 zcmeAS@N?(olHy`uVBq!ia0vp^4nSF!Z*Lm%HW&yvToiT* z^7N^2aSts?Skc1uBJ733JJtIKX4h|7{(l!xIRnEFiGn%bPlK5t;@PXvY0L}^Czx-D j!^IdJ;u_r9fEJlDWL{|L+~)A|1xU`*)z4*}Q$iB}G)^m& literal 0 HcmV?d00001 diff --git a/examples/tiny-project/code/samples/meshes/pyramid.obj b/examples/tiny-project/code/samples/meshes/pyramid.obj new file mode 100644 index 00000000..cdc4552f --- /dev/null +++ b/examples/tiny-project/code/samples/meshes/pyramid.obj @@ -0,0 +1,11 @@ +v 0 0 0 +v 1 0 0 +v 1 1 0 +v 0 1 0 +v 0.5 0.5 0.8 +f 1 3 2 +f 1 4 3 +f 1 2 5 +f 2 3 5 +f 3 4 5 +f 4 1 5 diff --git a/examples/tiny-project/code/samples/sounds/two-tones.wav b/examples/tiny-project/code/samples/sounds/two-tones.wav new file mode 100644 index 0000000000000000000000000000000000000000..fa19afba8513a6616dcfc2e16d12140d13449fbb GIT binary patch literal 9644 zcmeI!F$#k)6vpxA*0DEemx>6E;%WzlA~f`}(24^Sf2?TdnaTG*6O{GW3 zWZ@slq6x^4%pL>~KmY** x5ZISM-3{|P4_&QQ61cV-BueuR1I__=fqFnqq%Y7L$p_{cXME0$;Dc%tHVG literal 0 HcmV?d00001 diff --git a/examples/tiny-project/code/samples/texts/greeting.txt b/examples/tiny-project/code/samples/texts/greeting.txt new file mode 100644 index 00000000..f269535a --- /dev/null +++ b/examples/tiny-project/code/samples/texts/greeting.txt @@ -0,0 +1 @@ +Ada Lovelace wrote to Charles Babbage from London 🌍 in 1843. diff --git a/examples/tiny-project/code/samples/texts/weather.txt b/examples/tiny-project/code/samples/texts/weather.txt new file mode 100644 index 00000000..302ea685 --- /dev/null +++ b/examples/tiny-project/code/samples/texts/weather.txt @@ -0,0 +1 @@ +Rain over Manila this morning; clear skies in Cebu by the afternoon. diff --git a/examples/tiny-project/project/annotations/sample-quality.json b/examples/tiny-project/project/annotations/sample-quality.json new file mode 100644 index 00000000..3385e268 --- /dev/null +++ b/examples/tiny-project/project/annotations/sample-quality.json @@ -0,0 +1,9 @@ +{ + "format": "tuldok_definition_v1", + "kind": "annotation", + "title": "Sample quality", + "description": "Whether each sample is clean enough to keep.", + "dataset": "datasets/samples", + "task": "class", + "vocabulary": ["clean", "noisy", "broken"] +} diff --git a/examples/tiny-project/project/annotations/sample-quality.jsonl b/examples/tiny-project/project/annotations/sample-quality.jsonl new file mode 100644 index 00000000..83139ec8 --- /dev/null +++ b/examples/tiny-project/project/annotations/sample-quality.jsonl @@ -0,0 +1,6 @@ +{"record":"clouds__ring.ply","sha256":"3de402a535f473fd002e7f74f88aba003dc18e7cc1d3b23195fc10b0c752dae8","state":"accepted","value":"clean","by":"owner","at":"2026-11-13T09:30:00Z"} +{"record":"images__shapes.png","sha256":"1ab3564df0659b467dc93b26be066accd4b19f5dbc0c0216831d856facec9372","state":"accepted","value":"clean","by":"owner","at":"2026-11-13T09:30:00Z"} +{"record":"meshes__pyramid.obj","sha256":"ebf7519500bc461c4856157e63bc2ab6661b56894c36f04f8da217bc2d05b593","state":"accepted","value":"clean","by":"owner","at":"2026-11-13T09:30:00Z"} +{"record":"sounds__two-tones.wav","sha256":"fd10d893427a1a9dd4a0005abc271e1c94ab22adfb7d222042b71929246880ff","state":"accepted","value":"clean","by":"owner","at":"2026-11-13T09:30:00Z"} +{"record":"texts__greeting.txt","sha256":"a9af2325f767d1c8d2e130f52d0c119e5d98831bb11d0a148e33c39b0874b15d","state":"accepted","value":"clean","by":"owner","at":"2026-11-13T09:30:00Z"} +{"record":"texts__weather.txt","sha256":"43242d49e671a79209b537a360a4a11ef3112e9e4b7a394b02ed701c3ba677a5","state":"rejected","value":null,"note":"too short to be of use","by":"owner","at":"2026-11-13T09:30:00Z"} diff --git a/examples/tiny-project/project/datasets/samples-v1.json b/examples/tiny-project/project/datasets/samples-v1.json new file mode 100644 index 00000000..a3557688 --- /dev/null +++ b/examples/tiny-project/project/datasets/samples-v1.json @@ -0,0 +1,12 @@ +{ + "format": "tuldok_definition_v1", + "kind": "dataset", + "title": "Samples v1, frozen", + "description": "The samples whose quality annotation is accepted, split three to one.", + "run": { + "step": "freeze", + "inputs": {"records": "datasets/samples"}, + "annotations": ["annotations/sample-quality"], + "settings": {"seed": 7, "shares": {"train": 3, "test": 1}} + } +} diff --git a/examples/tiny-project/project/datasets/samples.json b/examples/tiny-project/project/datasets/samples.json new file mode 100644 index 00000000..44777ab3 --- /dev/null +++ b/examples/tiny-project/project/datasets/samples.json @@ -0,0 +1,10 @@ +{ + "format": "tuldok_definition_v1", + "kind": "dataset", + "title": "Samples of each kind", + "description": "Two texts, an image, a sound, a point cloud and a mesh, imported from code/samples (written by code/make_samples.py).", + "run": { + "step": "import", + "settings": {"source": "samples", "pattern": "**/*", "rights": "Made by make_samples.py for this example; free to use."} + } +} diff --git a/static/project-workspace.html b/static/project-workspace.html index 4b882589..33b3bb6d 100644 --- a/static/project-workspace.html +++ b/static/project-workspace.html @@ -17,6 +17,7 @@ + diff --git a/static/project-workspace/actions.js b/static/project-workspace/actions.js index 29dbd259..72b46349 100644 --- a/static/project-workspace/actions.js +++ b/static/project-workspace/actions.js @@ -168,12 +168,12 @@ window.LabActions = (() => { id: 'save', label: 'Save', cls: 'btn sm', who: 'edit', op: 'save', busy: 'Saving…', extra: error => { if (error.code !== 'changed-on-disk') return null; const b = btn('btn sm', 'Read the project again', 'reread'); b.addEventListener('click', () => hooks.reread()); const d = h('div', 'actions'); d.appendChild(b); return d; } }); - /** The strip's part: how many definitions are unsaved or marked removed, and Save. */ + /** The strip's part: how many definitions are unsaved or marked removed and how many annotations are unsaved ("3 definitions, 41 annotations unsaved"), and Save, which writes both. */ function stripSave(status, note) { - const n = status.unsaved.length + status.removed.length; - if (!n) { if (note) note.textContent = ''; return null; } + const n = status.unsaved.length + status.removed.length, a = P.annotationsUnsaved(status); + if (!n && !a) { if (note) note.textContent = ''; return null; } const box = h('span', 'unsaved'); - box.appendChild(h('span', 'count', plural(n, 'definition', 'definitions') + ' unsaved')); + box.appendChild(h('span', 'count', [n ? plural(n, 'definition', 'definitions') : null, a ? plural(a, 'annotation', 'annotations') : null].filter(Boolean).join(', ') + ' unsaved')); box.appendChild(group('save', [saveItem()], { inline: true, refusalIn: note })); return box; } @@ -188,8 +188,8 @@ window.LabActions = (() => { } else if (n.save) { items.push(saveItem()); for (const ref of n.references.slice(0, 6)) { - const where = ref.startsWith('recipes/') ? 'map' : ref.startsWith('datasets/') ? 'data' : null; - if (where) items.push({ id: 'open-' + ref, label: ref, cls: 'btn sm ghost', onClick: () => go(where, ref) }); + const where = ref.startsWith('recipes/') ? 'map' : ref.startsWith('datasets/') ? 'data' : ref.startsWith('annotations/') ? 'annotate' : null; + if (where) items.push({ id: 'open-' + ref, label: ref, cls: 'btn sm ghost', onClick: () => { if (where !== 'annotate') return go(where, ref); if (window.LabAnnotate) window.LabAnnotate.choose(ref); go(where); } }); } } else if (n.environment) { const e = n.environment; diff --git a/static/project-workspace/adapter.js b/static/project-workspace/adapter.js index b85ba37c..4e2f9692 100644 --- a/static/project-workspace/adapter.js +++ b/static/project-workspace/adapter.js @@ -119,6 +119,19 @@ window.TuldokProject = (() => { fileUrl: (run, path) => '/api/project/file?run=' + encodeURIComponent(run) + '&path=' + encodeURIComponent(path) }; + // ---- Annotating (spec-d4.md, annotate.js) -------------------------------------------------- + // The three reads of annotations, kept like any other answer until a reading finds something changed (they are + // not watched, so forgetBut() drops them). The two changes (set_annotation, revert_annotations) are called by + // controls (actions.js) by their names. + const annotations = { + tasks: () => read('annotation_tasks'), + /** A page of a task's records with their annotations; state one of the counts' names, or none for all. */ + records: (task, { state, kind, offset, limit } = {}) => read('annotated_records', defined({ task, state, kind, offset, limit })), + one: (task, record) => read('annotation', { task, record }) + }; + /** How many records have an unsaved annotation, in all, from a status answer. */ + const annotationsUnsaved = status => ((status && status.annotations_unsaved) || []).reduce((n, t) => n + t.records, 0); + // ---- The map ------------------------------------------------------------ /** * What the Map tab and the drawer read, from the answer of `map`: @@ -251,8 +264,10 @@ window.TuldokProject = (() => { out.push({ kind: 'approval', key: 'request:' + r.id, request: r, text: 'A build of ' + (r.every ? 'everything buildable' : listed(r.targets || [])) + ', asked by ' + who + ' on ' + day(r.requested_at) + ', awaits your approval.' }); } if (status.unsaved.length) out.push({ kind: 'changed', key: 'unsaved', save: true, references: status.unsaved.map(String), text: plural(status.unsaved.length, 'definition has', 'definitions have') + ' unsaved edits: ' + listed(status.unsaved.map(String)) + '.' }); + const typed = annotationsUnsaved(status); + if (typed) out.push({ kind: 'changed', key: 'annotations-unsaved', save: true, references: status.annotations_unsaved.map(t => t.task), text: plural(typed, 'annotation is', 'annotations are') + ' unsaved: ' + listed(status.annotations_unsaved.map(t => t.task + ' (' + t.records + ')')) + '.' }); if (status.removed.length) out.push({ kind: 'changed', key: 'removed', save: true, references: status.removed.map(String), text: plural(status.removed.length, 'definition is', 'definitions are') + ' marked removed and not yet saved: ' + listed(status.removed.map(String)) + '.' }); - const disk = [].concat(status.added, status.changed, status.missing).map(String); + const disk = [].concat(status.added, status.changed, status.missing, status.annotations_changed || []).map(String); if (disk.length) out.push({ kind: 'changed', text: plural(disk.length, 'file changed', 'files changed') + ' on disk since the project was last read: ' + listed(disk) + '.' }); if (status.irregular.length) out.push({ kind: 'missing', text: plural(status.irregular.length, 'file is', 'files are') + ' not regular files and are not read: ' + listed(status.irregular.map(String)) + '.' }); const results = [].concat(status.results_unsaved, status.results_changed).map(String); @@ -266,5 +281,5 @@ window.TuldokProject = (() => { return out; } - return { KINDS, UNSET, WATCHED, kindLabel, stateWord, call, read, again, forget, forgetBut, forgetAll, map, setDrafts, trackName, better, units, standing, needs, titleOf, day, product }; + return { KINDS, UNSET, WATCHED, kindLabel, stateWord, call, read, again, forget, forgetBut, forgetAll, map, setDrafts, trackName, better, units, standing, needs, titleOf, day, product, annotations, annotationsUnsaved }; })(); diff --git a/static/project-workspace/annotate.js b/static/project-workspace/annotate.js new file mode 100644 index 00000000..d7cb0ed4 --- /dev/null +++ b/static/project-workspace/annotate.js @@ -0,0 +1,817 @@ +'use strict'; +// The Annotate tab (docs/plans/definition-first-projects/spec-d4.md section 7): a task's records as a paged grid of +// 48 with a dot for the state of each, the record in its viewer (inside.js's), and the task's form beside it with +// the decision, a note, Keep and next, Skip, Revert and, for a stale annotation, Still right. Boxes are drawn on the +// image, spans marked in the text and segments on the waveform, in Canvas 2D and the DOM with the tokens of +// base.css, by pointer and by keyboard. The New task form (in the drawer) keeps a new annotations/ +// definition as an unsaved edit, as the editor keeps a new definition; the Data tab's Import and Freeze forms +// (datasetForm) keep a new dataset the same way. Annotations are kept with set_annotation and written by Save. +// +// Updating in place (spec-w4): the tab is drawn in four parts (the bar, the grid, the viewer, the form), each built +// off the page and put in place only when what it shows differs, so a reading that changed something elsewhere +// redraws the grid and leaves the form alone. What is typed or drawn in the form is a draft kept in page memory per +// task and record until it is kept, reverted or put right: a reading never replaces a form that holds one, and +// moving to another record keeps it. The forms in the drawer are never touched by a reading on the timer or on +// focus, and keep what is typed in their group's slot (actions.js). Keys (1 to 9, Enter, the left and right +// arrows) are ignored while typing in a field. +window.LabAnnotate = (() => { + const P = window.TuldokProject, S = window.LabScreens, A = window.LabActions, C = window.LabCharts, h = C.h, V = window.LabInside.viewers; + const { sect, putInPlace, putDrawer, turn, time, bytes } = S.parts; + const PER_PAGE = 48; + const TYPES = ['review', 'class', 'tags', 'text', 'boxes', 'spans', 'segments']; + const TYPE_WORD = { review: 'Review', class: 'Class: one term', tags: 'Tags: any of the terms', text: 'Text: a caption or a transcript', boxes: 'Boxes on an image', spans: 'Spans of a text', segments: 'Segments of a sound' }; + const NEEDS_TERMS = ['class', 'tags', 'boxes', 'spans', 'segments']; + const ONLY = { boxes: 'image', spans: 'text', segments: 'audio' }; // the one kind of record these tasks describe + const FILTERS = [['all', 'All'], ['todo', 'To do'], ['accepted', 'Accepted'], ['needs-work', 'Needs work'], ['rejected', 'Rejected'], ['stale', 'Stale']]; + const DECISIONS = [['accepted', 'Accept', 'ok'], ['needs-work', 'Needs work', 'warn'], ['rejected', 'Reject', 'bad']]; + const STATE = { none: ['neutral', 'not annotated'], draft: ['neutral', 'draft'], accepted: ['good', 'accepted'], 'needs-work': ['warn', 'needs work'], rejected: ['serious', 'rejected'] }; + const FORMAT = 'tuldok_definition_v1'; + const count = (n, one, many) => n.toLocaleString('en-GB') + ' ' + (n === 1 ? one : many || one + 's'); + const button = (cls, text, key, onClick) => { const b = h('button', cls, text); b.type = 'button'; if (key) b.dataset.key = key; if (onClick) b.addEventListener('click', onClick); return b; }; + const kbd = text => h('span', 'kbd', text); + const clamp = (v, lo, hi) => Math.min(hi, Math.max(lo, v)); + const rgb = (c, a) => a == null ? 'rgb(' + c.join(',') + ')' : 'rgba(' + c.join(',') + ',' + a + ')'; + const nameOf = ref => ref.slice(ref.indexOf('/') + 1); + const copy = v => v == null ? v : JSON.parse(JSON.stringify(v)); + const textOf = doc => JSON.stringify(doc, null, 2) + '\n'; + + // ---- What is kept in this page ------------------------------------------------------------------------------------ + const ui = { task: null, filter: 'all', page: 0, sel: new Map(), selAt: 0, terms: new Map() }; // sel and terms: per task + const drafts = new Map(); // task + '\n' + record -> { state, value, note, dirty } + const store = new Map(); // the viewers' settings (inside.js), per record + let here = null; // the tab on screen: { main, act, root, keys, parts, t, page, rec, pick, repaint, relist } + + const draftKey = (t, rec) => t.task + '\n' + rec.id; + function emptyValue(type) { return type === 'class' || type === 'review' ? null : type === 'text' ? '' : []; } + /** A draft from the annotation as it is (not typed yet), or the one typed. */ + function draftOf(t, rec, fresh) { + const k = draftKey(t, rec), had = drafts.get(k); + if (had && (had.dirty || !fresh)) return had; + const a = rec.annotation, d = { state: a && a.state !== 'draft' ? a.state : null, value: a && a.value != null ? copy(a.value) : emptyValue(t.type), note: (a && a.note) || '', dirty: false }; + if (t.type === 'text' && typeof d.value !== 'string') d.value = ''; + if (['tags', 'boxes', 'spans', 'segments'].includes(t.type) && !Array.isArray(d.value)) d.value = []; + drafts.set(k, d); return d; + } + /** The value a draft keeps, as the task's value: null for review, an empty text or no term. */ + function valueOf(t, d) { + if (t.type === 'review') return null; + if (t.type === 'class') return d.value || null; + if (t.type === 'text') return d.value ? d.value : null; + if (t.type === 'tags') return t.vocabulary.filter(v => d.value.includes(v)); + if (t.type === 'segments') return d.value.map(s => { const o = { term: s.term, start: s.start, end: s.end }; if (s.text) o.text = s.text; return o; }); + return copy(d.value); + } + function itemOf(t, rec, d) { const it = { record: rec.id, state: d.state || 'draft', value: valueOf(t, d) }; if (d.note && d.note.trim()) it.note = d.note; return it; } + + // ---- Reading --------------------------------------------------------------------------------------------------- + /** A page of the task's records for the filter: "To do" is the records not annotated, then the drafts. */ + async function pageOf(t) { + const offset = ui.page * PER_PAGE; + if (ui.filter !== 'todo') { const r = await P.annotations.records(t.task, { state: ui.filter === 'all' ? null : ui.filter, offset, limit: PER_PAGE }); return { records: r.records, total: r.total }; } + const u = await P.annotations.records(t.task, { state: 'unannotated', offset, limit: PER_PAGE }); + const need = PER_PAGE - u.records.length, d = await P.annotations.records(t.task, { state: 'draft', offset: Math.max(0, offset - u.total), limit: Math.max(1, need) }); + return { records: need > 0 ? u.records.concat(d.records.slice(0, need)) : u.records, total: u.total + d.total }; + } + async function load() { + const tasks = (await P.annotations.tasks()).tasks; + if (!tasks.length) return { tasks }; + const t = tasks.find(x => x.task === ui.task) || tasks[0]; ui.task = t.task; + if (!t.run) return { tasks, t }; + let page = await pageOf(t); + if (!page.records.length && ui.page > 0 && page.total) { ui.page = Math.floor((page.total - 1) / PER_PAGE); page = await pageOf(t); } + let id = ui.sel.get(t.task); + if (!page.records.some(r => r.id === id)) id = page.records.length ? page.records[ui.selAt === -1 ? page.records.length - 1 : 0].id : null; + ui.selAt = 0; if (id) ui.sel.set(t.task, id); else ui.sel.delete(t.task); + return { tasks, t, page, rec: page.records.find(r => r.id === id) || null }; + } + + // ---- The tab ----------------------------------------------------------------------------------------------------- + /** The screen (app.js): the tab in main; the drawer holds the New task form when it is selected. */ + function annotate(main, aside, state, act) { + draw(main, act); + if (state.sel.annotate === 'new-task') { taskForm(aside, act); return true; } + aside.textContent = ''; aside._for = null; + return false; + } + /** A person's own move (a record, a page, a filter, a task): drawn again at once from what is kept. */ + const redraw = () => { if (here && here.root && here.root.isConnected) draw(here.main, here.act); }; + + /** + * Draws the tab: "Reading…" only when it is not on screen; otherwise each part whose content differs is built off + * the page and put in place, the others are left alone. A form holding a draft of the record it shows is kept. + */ + async function draw(main, act) { + const view = main._view, mine = main._paint = (main._paint || 0) + 1; + const shown = !!(here && here.root && main.contains(here.root) && main._painted === view); + if (!shown) { main.textContent = ''; main.appendChild(h('p', 'note', 'Reading…')); here = { main, act, root: null, keys: {}, parts: {}, pick: -1 }; } + here.act = act; + main.setAttribute('aria-busy', 'true'); + let got; try { got = await load(); } catch (error) { got = { error }; } + if (main._paint !== mine || main._view !== view) return; + const kind = got.error ? 'error' : !got.tasks.length ? 'none' : !got.t.run ? 'unbuilt' : 'records'; + const t = got.t || null, rec = got.rec || null, may = A.may('edit'); + const keys = { shape: kind, bar: kind === 'error' ? 'error' : JSON.stringify([got.tasks.map(x => [x.task, x.title, x.type]), t && [t.task, t.run, t.records, t.counts, t.dataset], ui.filter, may]) }; + if (kind === 'records') { + keys.list = JSON.stringify([t.task, t.run, ui.filter, ui.page, got.page.total, got.page.records.map(r => [r.id, r.kind, r.path, r.preview || null, r.in_product, r.annotation && [r.annotation.state, r.annotation.stale, r.annotation.unsaved]])]); + keys.view = rec ? JSON.stringify([t.task, t.type, t.run, rec.id, rec.kind, rec.in_product]) : 'none'; // its place in the list is set in place (place()) + keys.form = rec ? JSON.stringify([t.task, t.type, t.vocabulary, rec.id, rec.kind, rec.in_product, rec.annotation, may]) : 'none'; + const same = here.rec && rec && here.t && here.t.task === t.task && here.rec.id === rec.id; + if (same && here.keys.form && keys.form !== here.keys.form && (drafts.get(draftKey(t, rec)) || {}).dirty) keys.form = here.keys.form; // what is typed stays + } else keys.msg = JSON.stringify([kind, t && [t.task, t.dataset], may, got.error ? got.error.message : null]); + // What changed is read before anything is put in place, so that it is put in one step. + const build = {}; + try { + if (keys.view && keys.view !== here.keys.view) { if (!here.rec || !rec || here.rec.id !== rec.id) here.pick = -1; build.view = rec ? await buildView(t, rec, got.page) : h('p', 'empty', 'Choose a record.'); } + if (keys.form && keys.form !== here.keys.form && rec && rec.annotation && rec.annotation.stale) build.detail = await P.annotations.one(t.task, rec.id).catch(() => null); + } catch (error) { build.view = h('div', 'iv'); build.view.appendChild(A.refusal(error)); } + if (main._paint !== mine || main._view !== view) return; + main.removeAttribute('aria-busy'); + here.t = t; here.page = got.page || null; here.rec = rec; here.tasks = got.tasks; + const fresh = !here.root || keys.shape !== here.keys.shape; + if (fresh) { + const root = h('div', 'annotate'); root.dataset.shape = kind; + here.parts = { bar: h('div', 'ann-barbox') }; root.appendChild(here.parts.bar); + if (kind === 'records') { const body = h('div', 'ann-body'); for (const p of ['list', 'view', 'form']) { here.parts[p] = h('div', 'ann-' + p); body.appendChild(here.parts[p]); } here.parts.view.classList.add('viewer'); here.parts.view.setAttribute('aria-label', 'The record'); root.appendChild(body); } + else { here.parts.msg = h('div', 'ann-msg'); root.appendChild(here.parts.msg); } + here.keys = { shape: kind }; + here.root = root; + } + const put = (name, make) => { + if (here.keys[name] === keys[name]) return; + here.keys[name] = keys[name]; + const content = make(); if (fresh) here.parts[name].replaceChildren(content); else putInPlace(here.parts[name], content, main); + }; + put('bar', () => kind === 'error' ? h('div') : buildBar(got.tasks, t)); + if (kind === 'records') { + put('list', () => buildList(t, got.page)); + put('view', () => { const hooks = build.view._hooks || {}; here.repaint = hooks.repaint || null; here.textOf = hooks.textOf || null; here.play = hooks.play || null; return build.view; }); + put('form', () => rec ? buildForm(t, rec, build.detail) : h('p', 'empty', t.records ? 'No record matches the filter.' : 'The product of ' + t.dataset + ' holds no records.')); + // The selection is set in place: the grid is not drawn again for it. + for (const b of here.parts.list.querySelectorAll('.rec')) { const on = String(!!rec && b.dataset.id === rec.id); if (b.getAttribute('aria-pressed') !== on) b.setAttribute('aria-pressed', on); } + if (rec) place(here.parts.view, got.page, rec); + if (here.repaint) here.repaint(); + } else put('msg', () => buildMessage(kind, t, got.error)); + if (fresh) putInPlace(main, here.root); + main._painted = view; + if (here.focusSel) { here.focusSel = false; const b = here.root.querySelector('.rec[aria-pressed="true"]'); if (b) b.focus(); } + } + + function buildMessage(kind, t, error) { + const box = h('div', 'ann-empty'); + if (kind === 'error') { box.appendChild(A.refusal(error)); return box; } + if (kind === 'none') { + box.appendChild(h('p', 'empty', 'This project has no annotation task. A task says what is recorded about the records of one dataset: a decision, a class, tags, a text, boxes, spans or segments.')); + if (!A.may('edit')) box.appendChild(h('p', 'note', 'Making a task needs the right to edit.')); + return box; + } + box.appendChild(h('p', 'empty', t.dataset + ' has no product on this machine, so ' + t.task + ' has no records to annotate yet. Build the dataset first.')); + box.appendChild(A.group('annotate:plan', [{ id: 'plan', label: 'Plan a build of ' + t.dataset, cls: 'btn', who: 'request', onClick: () => here.act.go('train', 'plan:' + t.dataset) }])); + return box; + } + + // ---- The bar ----------------------------------------------------------------------------------------------------- + function buildBar(tasks, t) { + const bar = h('div', 'ann-bar'); + if (tasks.length) { + const l = h('label', 'ann-task'); l.appendChild(document.createTextNode('Task')); + const s = h('select'); s.dataset.key = 'ann:task'; + for (const x of tasks) { const o = h('option', null, x.title + ' · ' + x.type); o.value = x.task; o.selected = !!t && x.task === t.task; s.appendChild(o); } + s.addEventListener('change', () => { ui.task = s.value; ui.page = 0; here.pick = -1; redraw(); }); + l.appendChild(s); bar.appendChild(l); + } + bar.appendChild(A.group('annotate:new', [{ id: 'new', label: 'New task', cls: 'btn sm', who: 'edit', onClick: () => here.act.select('new-task') }], { inline: true })); + if (t && t.run) { + const c = t.counts, n = { all: null, todo: c.unannotated + c.draft, accepted: c.accepted, 'needs-work': c['needs-work'], rejected: c.rejected, stale: c.stale }; + const seg = h('div', 'seg ann-filter'); seg.setAttribute('role', 'group'); seg.setAttribute('aria-label', 'Show the records'); + for (const [id, label] of FILTERS) { const b = button(null, label + (n[id] != null ? ' · ' + n[id].toLocaleString('en-GB') : ''), 'ann:filter-' + id, () => { if (ui.filter !== id) { ui.filter = id; ui.page = 0; redraw(); } }); b.setAttribute('aria-pressed', String(ui.filter === id)); seg.appendChild(b); } + bar.appendChild(seg); + const decided = Math.min(t.records, c.accepted + c['needs-work'] + c.rejected); + const pr = h('span', 'ann-progress'); const bg = h('i'), fill = h('b'); fill.style.width = (t.records ? Math.round(100 * decided / t.records) : 0) + '%'; bg.appendChild(fill); pr.appendChild(bg); + pr.appendChild(document.createTextNode(decided.toLocaleString('en-GB') + ' of ' + count(t.records, 'record') + ' decided')); + bg.setAttribute('role', 'progressbar'); bg.setAttribute('aria-valuemin', '0'); bg.setAttribute('aria-valuemax', String(t.records)); bg.setAttribute('aria-valuenow', String(decided)); bg.setAttribute('aria-label', 'Decided'); + bar.appendChild(pr); + const keys = h('span', 'ann-keys small faint'); + const say = (...parts) => { for (const p of parts) keys.appendChild(typeof p === 'string' ? document.createTextNode(p) : p); }; + say(kbd('←'), ' ', kbd('→'), ' move'); + if (['class', 'tags'].includes(t.type) && t.vocabulary.length) say(' · ', kbd('1'), '–', kbd(String(Math.min(9, t.vocabulary.length))), ' term'); + say(' · ', kbd('Enter'), ' keep and next'); + bar.appendChild(keys); + } + return bar; + } + + // ---- The grid ---------------------------------------------------------------------------------------------------- + const marked = a => !a ? 'none' : a.state; + function buildList(t, page) { + const box = h('div'); + const first = ui.page * PER_PAGE + 1, last = ui.page * PER_PAGE + page.records.length; + box.appendChild(sect('Records', page.total ? first.toLocaleString('en-GB') + '–' + last.toLocaleString('en-GB') + ' of ' + page.total.toLocaleString('en-GB') : '0')); + if (!page.total) { box.appendChild(h('p', 'empty', ui.filter === 'all' ? 'The product holds no records.' : 'No record is ' + FILTERS.find(f => f[0] === ui.filter)[1].toLowerCase() + '.')); return box; } + const grid = h('div', 'rec-grid ann-grid'); grid.setAttribute('role', 'group'); grid.setAttribute('aria-label', 'Records ' + first + ' to ' + last + ' of ' + page.total + '; the left and right arrows move the selection'); + for (const r of page.records) grid.appendChild(tile(t, r)); + box.appendChild(grid); + const pages = Math.ceil(page.total / PER_PAGE); + if (pages > 1) { + const pg = h('div', 'pager'); + const pb = button('btn sm', 'Previous', 'ann:page-prev', () => turnPage(ui.page - 1, 0)); pb.disabled = ui.page === 0; + const nb = button('btn sm', 'Next', 'ann:page-next', () => turnPage(ui.page + 1, 0)); nb.disabled = ui.page + 1 >= pages; + pg.appendChild(pb); pg.appendChild(nb); pg.appendChild(h('span', null, 'page ' + (ui.page + 1) + ' of ' + pages)); box.appendChild(pg); + } + return box; + } + function turnPage(n, at) { ui.page = n; ui.sel.delete(ui.task); ui.selAt = at; redraw(); } + function tile(t, r) { + const a = r.annotation, st = marked(a), [, word] = STATE[st]; + const b = h('button', 'rec ann-rec ' + (r.kind || 'gone')); b.type = 'button'; b.dataset.id = r.id; b.dataset.key = 'ann-rec-' + r.id; b.dataset.state = st; + if (a && a.stale) b.dataset.stale = '1'; if (a && a.unsaved) b.dataset.unsaved = '1'; + b.setAttribute('aria-pressed', 'false'); b.title = r.id; + b.setAttribute('aria-label', (r.kind ? (V.WORD[r.kind] || r.kind) : 'Gone') + ' ' + r.id + ', ' + word + (a && a.stale ? ', stale' : '') + (a && a.unsaved ? ', unsaved' : '')); + const th = h('span', 'th'); + if (!r.in_product) th.appendChild(V.glyph('refused')); + else if (r.kind === 'text' && r.preview != null) th.appendChild(h('span', 'pre', r.preview.slice(0, 160))); + else th.appendChild(V.glyph(r.kind)); + if (r.in_product && r.kind === 'image' && r.path) { const img = h('img'); img.alt = ''; img.loading = 'lazy'; img.decoding = 'async'; img.src = P.product.fileUrl(t.run, r.path); img.addEventListener('load', () => { const g = th.querySelector('svg'); if (g) g.remove(); }, { once: true }); img.addEventListener('error', () => img.remove(), { once: true }); th.appendChild(img); } + const dot = h('i', 'badge ' + st); dot.setAttribute('aria-hidden', 'true'); th.appendChild(dot); + const id = h('span', 'id'); id.appendChild(h('bdi', null, r.id)); + const line = h('span', 'st'); line.appendChild(document.createTextNode(word)); + if (a && a.stale) line.appendChild(h('b', 'stale', 'stale')); if (a && a.unsaved) line.appendChild(h('b', 'unsaved', 'unsaved')); + b.appendChild(th); b.appendChild(id); b.appendChild(line); + b.addEventListener('click', () => select(r.id)); + return b; + } + function select(id) { if (!here || !here.t) return; ui.sel.set(here.t.task, id); redraw(); } + /** Moves the selection by d without keeping anything, across pages; on keep, done() moves on the same way. */ + function move(d, focusTile) { + if (!here || !here.page || !here.rec) return; + const list = here.page.records, i = list.findIndex(r => r.id === here.rec.id), n = i + d, pages = Math.ceil(here.page.total / PER_PAGE); + here.focusSel = !!focusTile; + if (n >= 0 && n < list.length) { ui.sel.set(here.t.task, list[n].id); return true; } + if (n >= list.length && ui.page + 1 < pages) { ui.page++; ui.sel.delete(ui.task); ui.selAt = 0; return true; } + if (n < 0 && ui.page > 0) { ui.page--; ui.sel.delete(ui.task); ui.selAt = -1; return true; } + here.focusSel = false; return false; + } + + // ---- The viewer --------------------------------------------------------------------------------------------------- + function heading(id, line) { const hd = h('header', 'iv-head'); hd.appendChild(h('h3', 'mono', id)); if (line) hd.appendChild(h('p', 'small muted', line)); return hd; } + /** Sets the record's place in the list into the viewer's Previous, Next and "3 of 48", in place: the viewer is not drawn again for it. */ + function place(view, page, rec) { + const nav = view.querySelector('.ann-nav'); if (!nav) return; + const at = page.records.indexOf(rec), pages = Math.ceil(page.total / PER_PAGE), [prev, where, next] = nav.children; + const text = (ui.page * PER_PAGE + at + 1).toLocaleString('en-GB') + ' of ' + page.total.toLocaleString('en-GB'); + if (where.textContent !== text) where.textContent = text; + const p = at <= 0 && ui.page === 0, n = at >= page.records.length - 1 && ui.page + 1 >= pages; + if (prev.disabled !== p) prev.disabled = p; if (next.disabled !== n) next.disabled = n; + } + async function buildView(t, rec, page) { + const el = h('div', 'iv ann-iv'); + const nav = h('div', 'ann-nav'); + nav.appendChild(button('btn sm', '← Previous', 'ann:prev', () => { if (move(-1)) redraw(); })); nav.appendChild(h('span', 'small muted')); nav.appendChild(button('btn sm', 'Next →', 'ann:next', () => { if (move(1)) redraw(); })); + el.appendChild(nav); place(el, page, rec); + el._hooks = {}; + if (!rec.in_product) { el.appendChild(heading(rec.id, 'Not in the current product')); el.appendChild(h('p', 'empty', 'This record is not in the current product of ' + t.dataset + ': it is gone, so its annotation is stale.')); return el; } + const got = await P.product.record(t.run, rec.id); + if (t.type === 'boxes' && rec.kind === 'image') boxView(el, got, t, rec); + else if (t.type === 'spans' && rec.kind === 'text') spanView(el, got, t, rec); + else if (t.type === 'segments' && rec.kind === 'audio') segmentView(el, got, t, rec); + else await V.record(el, got, t.run, store); + return el; + } + const cur = () => here && here.t && here.rec ? draftOf(here.t, here.rec) : null; + /** The boxes, spans or segments of a record's draft (the one typed, or the annotation's). */ + const itemsOf = (t, rec) => { const d = draftOf(t, rec); if (!Array.isArray(d.value)) d.value = []; return d.value; }; + const newTerm = t => { const v = ui.terms.get(t.task); return t.vocabulary.includes(v) ? v : t.vocabulary[0]; }; + const fontOf = px => px + 'px ' + getComputedStyle(document.body).fontFamily; + /** Something drawn or typed changed: the draft is marked, and the drawing and the list follow. */ + function touch(list = true) { + const d = cur(); if (!d) return; d.dirty = true; + const m = here.root && here.root.querySelector('.ann-form .umark'); if (m && m.textContent !== 'not kept yet') { m.textContent = 'not kept yet'; m.classList.add('typed'); } + if (list && here.relist) here.relist(); + if (here.repaint) here.repaint(); + } + function pickItem(i) { here.pick = i; if (here.relist) here.relist(); if (here.repaint) here.repaint(); } + /** The keys of a surface (boxes, segments): N adds one, [ and ] choose, Delete removes, Escape lets go; the rest is the surface's. */ + function surfaceKeys(e, items, add, step) { + const list = items(); let used = true; + if (e.key === 'n' || e.key === 'N') { list.push(add()); here.pick = list.length - 1; touch(); } + else if (e.key === ']' || e.key === '[') { if (list.length) pickItem(((here.pick < 0 ? (e.key === ']' ? -1 : 0) : here.pick) + (e.key === ']' ? 1 : -1) + list.length) % list.length); } + else if ((e.key === 'Delete' || e.key === 'Backspace') && list[here.pick]) { list.splice(here.pick, 1); here.pick = -1; touch(); } + else if (e.key === 'Escape' && here.pick >= 0) { e.stopPropagation(); pickItem(-1); } + else if (e.key.startsWith('Arrow') && list[here.pick]) { step(list[here.pick], e.key, e.shiftKey, e.altKey); touch(); } + else used = false; + if (used) e.preventDefault(); + } + + // Boxes, drawn on the image. Coordinates are pixels of the image, whatever its size on screen. + function boxView(el, got, t, rec) { + const r = got.record, k = got.content || {}, may = A.may('edit'), items = () => itemsOf(t, rec); + el.appendChild(heading(r.id, ['Image', k.width && k.height ? k.width + ' × ' + k.height + ' pixels' : null, bytes(r.bytes)].filter(Boolean).join(' · '))); + const stage = h('div', 'ann-stage'), wrap = h('div', 'ann-imgwrap'), img = h('img'), cv = h('canvas', 'ann-surface'); + img.src = r.url; img.alt = ''; img.draggable = false; + cv.tabIndex = 0; cv.dataset.key = 'ann:surface'; cv.setAttribute('role', 'application'); + cv.setAttribute('aria-label', 'Image ' + r.id + ' with its boxes. ' + (may ? 'Drag to draw a box, drag a box to move it, a corner to resize it. N adds a box, [ and ] choose one, the arrows move it, Shift and the arrows resize it, Delete removes it.' : '')); + const said = h('p', 'sr-only'); said.setAttribute('aria-live', 'polite'); + wrap.appendChild(img); wrap.appendChild(cv); stage.appendChild(wrap); el.appendChild(stage); el.appendChild(said); + if (may) el.appendChild(h('p', 'small faint ann-help', 'Drag on the image to draw a box; drag a box to move it, a corner to resize it. With the image focused: N adds a box, [ and ] choose one, the arrows move it (Alt: by 10), Shift and the arrows resize it, Delete removes it.')); + let nw = k.width || 0, nh = k.height || 0, frame = 0, drag = null; + const layout = () => { + if (!wrap.isConnected) return; + if (!nw || !nh) { if (!img.naturalWidth) return; nw = img.naturalWidth; nh = img.naturalHeight; } + const avail = stage.clientWidth; if (!avail) return; + const s = Math.min(avail / nw, Math.max(180, innerHeight * 0.55) / nh), w = Math.max(1, Math.floor(nw * s)), hh = Math.max(1, Math.floor(nh * s)); + if (wrap.style.width !== w + 'px' || wrap.style.height !== hh + 'px') { wrap.style.width = w + 'px'; wrap.style.height = hh + 'px'; } + wrap.classList.toggle('pixels', s >= 2); + wrap.dataset.image = nw + 'x' + nh; + paint(); + }; + const paint = () => { + frame = 0; + const W0 = cv.clientWidth, H0 = cv.clientHeight; if (!W0 || !H0 || !nw) return; + const dpr = window.devicePixelRatio || 1, W = Math.round(W0 * dpr), H = Math.round(H0 * dpr); + if (cv.width !== W) cv.width = W; if (cv.height !== H) cv.height = H; + const ctx = cv.getContext('2d'); ctx.clearRect(0, 0, W, H); + const sx = W / nw, sy = H / nh, list = items(), mark = V.token('--mark'), acc = V.token('--accent'), halo = V.token('--surface'), ink = V.token('--accent-ink'); + ctx.font = fontOf(Math.round(11.5 * dpr)); ctx.textBaseline = 'top'; + list.forEach((b, i) => { + const on = i === here.pick, x = b.x * sx, y = b.y * sy, w = b.w * sx, hh = b.h * sy, c = on ? acc : mark; + ctx.fillStyle = rgb(c, on ? 0.16 : 0.08); ctx.fillRect(x, y, w, hh); + ctx.lineWidth = (on ? 4 : 3) * dpr; ctx.strokeStyle = rgb(halo, 0.9); ctx.strokeRect(x, y, w, hh); + ctx.lineWidth = (on ? 2 : 1.5) * dpr; ctx.strokeStyle = rgb(c); ctx.strokeRect(x, y, w, hh); + const label = (i + 1) + ' ' + b.term, tw = ctx.measureText(label).width + 8 * dpr, th = 16 * dpr, ty = y >= th ? y - th : y; + ctx.fillStyle = rgb(c); ctx.fillRect(x, ty, Math.min(tw, Math.max(tw, w)), th); ctx.fillStyle = rgb(ink); ctx.fillText(label, x + 4 * dpr, ty + 2 * dpr); + if (on) for (const [cx, cy] of [[x, y], [x + w, y], [x, y + hh], [x + w, y + hh]]) { const s = 7 * dpr; ctx.fillStyle = rgb(halo); ctx.fillRect(cx - s / 2, cy - s / 2, s, s); ctx.strokeStyle = rgb(acc); ctx.lineWidth = 1.5 * dpr; ctx.strokeRect(cx - s / 2, cy - s / 2, s, s); } + }); + const b = list[here.pick]; const text = b ? 'Box ' + (here.pick + 1) + ', ' + b.term + ', at ' + b.x + ', ' + b.y + ', ' + b.w + ' by ' + b.h + ' pixels' : count(list.length, 'box', 'boxes'); + if (said.textContent !== text) said.textContent = text; + }; + const later = () => { if (!frame) frame = requestAnimationFrame(paint); }; + el._hooks.repaint = later; + img.addEventListener('load', layout); + const ro = new ResizeObserver(() => { if (!stage.isConnected) { if (stage._seen) ro.disconnect(); return; } stage._seen = true; layout(); }); + ro.observe(stage); + V.paints(cv, later); // the theme + const at = e => { const q = cv.getBoundingClientRect(); return { x: clamp((e.clientX - q.left) / q.width * nw, 0, nw), y: clamp((e.clientY - q.top) / q.height * nh, 0, nh) }; }; + const corners = b => [['nw', b.x, b.y], ['ne', b.x + b.w, b.y], ['sw', b.x, b.y + b.h], ['se', b.x + b.w, b.y + b.h]]; + const fitBox = b => { b.x = clamp(Math.round(b.x), 0, nw - 1); b.y = clamp(Math.round(b.y), 0, nh - 1); b.w = clamp(Math.round(b.w), 1, nw - b.x); b.h = clamp(Math.round(b.h), 1, nh - b.y); return b; }; + cv.addEventListener('pointerdown', e => { + if (e.button !== 0 || !may || !nw) return; + e.preventDefault(); cv.focus({ preventScroll: true }); + const p = at(e), list = items(), tol = 8 * nw / cv.clientWidth; + let hit = null; + const order = list.map((_, i) => i).reverse(); if (here.pick >= 0 && list[here.pick]) order.unshift(here.pick); + for (const i of order) { for (const [corner, cx, cy] of corners(list[i])) if (Math.abs(p.x - cx) <= tol && Math.abs(p.y - cy) <= tol) { hit = { mode: 'resize', i, corner }; break; } if (hit) break; } + if (!hit) for (const i of order) { const b = list[i]; if (p.x >= b.x && p.x <= b.x + b.w && p.y >= b.y && p.y <= b.y + b.h) { hit = { mode: 'move', i }; break; } } + if (!hit) { list.push({ term: newTerm(t), x: p.x, y: p.y, w: 0, h: 0 }); hit = { mode: 'new', i: list.length - 1 }; } + drag = Object.assign(hit, { from: p, orig: Object.assign({}, list[hit.i]), id: e.pointerId, moved: false }); + here.pick = hit.i; cv.setPointerCapture(e.pointerId); later(); + }); + cv.addEventListener('pointermove', e => { + if (!drag || e.pointerId !== drag.id) return; + const p = at(e), b = items()[drag.i], o = drag.orig; if (!b) return; + drag.moved = true; + if (drag.mode === 'new') Object.assign(b, { x: Math.min(drag.from.x, p.x), y: Math.min(drag.from.y, p.y), w: Math.abs(p.x - drag.from.x), h: Math.abs(p.y - drag.from.y) }); + else if (drag.mode === 'move') Object.assign(b, { x: clamp(o.x + p.x - drag.from.x, 0, nw - o.w), y: clamp(o.y + p.y - drag.from.y, 0, nh - o.h) }); + else { const fx = drag.corner.includes('w') ? o.x + o.w : o.x, fy = drag.corner.includes('n') ? o.y + o.h : o.y; Object.assign(b, { x: Math.min(fx, p.x), y: Math.min(fy, p.y), w: Math.abs(p.x - fx), h: Math.abs(p.y - fy) }); } + later(); + }); + const end = e => { + if (!drag || e.pointerId !== drag.id) return; + const list = items(), b = list[drag.i], d = drag; drag = null; + if (!b) return; + if (d.mode === 'new' && (b.w < 1 || b.h < 1)) { list.splice(d.i, 1); here.pick = -1; if (here.relist) here.relist(); later(); return; } // a press without a drag: nothing drawn, nothing chosen + if (!d.moved) { if (here.relist) here.relist(); later(); return; } + fitBox(b); touch(); + }; + cv.addEventListener('pointerup', end); cv.addEventListener('pointercancel', end); + cv.addEventListener('keydown', e => { + if (!may || !nw) return; + surfaceKeys(e, items, () => fitBox({ term: newTerm(t), x: nw / 4, y: nh / 4, w: Math.max(1, nw / 2), h: Math.max(1, nh / 2) }), (b, key, shift, alt) => { + const s = alt ? 10 : 1, dx = key === 'ArrowLeft' ? -s : key === 'ArrowRight' ? s : 0, dy = key === 'ArrowUp' ? -s : key === 'ArrowDown' ? s : 0; + if (shift) { b.w = clamp(b.w + dx, 1, nw - b.x); b.h = clamp(b.h + dy, 1, nh - b.y); } + else { b.x = clamp(b.x + dx, 0, nw - b.w); b.y = clamp(b.y + dy, 0, nh - b.h); } + }); + }); + } + + // Spans, marked in the text. Offsets are characters (code points) of the record's text. + function spanView(el, got, t, rec) { + const r = got.record, k = got.content || {}, text = k.text || '', may = A.may('edit'), items = () => itemsOf(t, rec); + const total = k.characters != null ? k.characters : Array.from(text).length; + el.appendChild(heading(r.id, ['Text', count(total, 'character'), k.truncated ? 'truncated: spans can be marked in the first ' + Array.from(text).length.toLocaleString('en-GB') : null].filter(Boolean).join(' · '))); + const pre = h('pre', 'iv-text ann-text'); pre.tabIndex = 0; pre.dataset.key = 'ann:text-surface'; + pre.setAttribute('aria-label', 'The text, with its spans marked' + (may ? '; select a stretch of it to mark a span' : '')); + el.appendChild(pre); + const cps = Array.from(text), u16 = [0]; for (const c of cps) u16.push(u16[u16.length - 1] + c.length); // code point -> UTF-16 offset + const toCp = u => { let lo = 0, hi = cps.length; while (lo < hi) { const m = (lo + hi + 1) >> 1; if (u16[m] <= u) lo = m; else hi = m - 1; } return lo; }; + const paint = () => { + const list = items(), cuts = new Set([0, cps.length]); + for (const s of list) { cuts.add(clamp(s.start, 0, cps.length)); cuts.add(clamp(s.end, 0, cps.length)); } + const at = [...cuts].sort((a, b) => a - b), frag = document.createDocumentFragment(); + for (let j = 0; j + 1 < at.length; j++) { + const a = at[j], b = at[j + 1], piece = cps.slice(a, b).join(''), over = list.map((s, i) => [s, i]).filter(([s]) => s.start <= a && s.end >= b); + if (!over.length) frag.appendChild(document.createTextNode(piece)); + else { const m = h('mark', 'ann-span' + (over.some(([, i]) => i === here.pick) ? ' sel' : '') + (over.length > 1 ? ' many' : ''), piece); m.dataset.i = String(over[over.length - 1][1]); m.title = over.map(([s, i]) => (i + 1) + ' ' + s.term).join(', '); frag.appendChild(m); } + for (const [s, i] of list.map((s, i) => [s, i])) if (s.end === b) { const tag = h('span', 'ann-tag' + (i === here.pick ? ' sel' : ''), (i + 1) + ' ' + s.term); tag.setAttribute('aria-hidden', 'true'); tag.contentEditable = 'false'; frag.appendChild(tag); } + } + pre.replaceChildren(frag); + }; + el._hooks.repaint = paint; + /** The UTF-16 offset in the text of a place in pre, the tags left out. */ + const offsetOf = (node, offset) => { const range = document.createRange(); range.setStart(pre, 0); range.setEnd(node, offset); const f = range.cloneContents(); for (const x of f.querySelectorAll('.ann-tag')) x.remove(); return f.textContent.length; }; + const mark = () => { + if (!may) return false; + const s = getSelection(); if (!s.rangeCount || s.isCollapsed) return false; + const range = s.getRangeAt(0); if (!pre.contains(range.startContainer) || !pre.contains(range.endContainer)) return false; + let a = toCp(offsetOf(range.startContainer, range.startOffset)), b = toCp(offsetOf(range.endContainer, range.endOffset)); if (a > b) [a, b] = [b, a]; + if (a === b) return false; + const list = items(); list.push({ term: newTerm(t), start: a, end: b }); here.pick = list.length - 1; + s.removeAllRanges(); touch(); return true; + }; + pre.addEventListener('mouseup', () => { mark(); }); + pre.addEventListener('click', e => { const m = e.target.closest && e.target.closest('mark.ann-span'); if (m && getSelection().isCollapsed) pickItem(Number(m.dataset.i)); }); + if (may) { const row = h('div', 'iv-ctl'); row.appendChild(button('btn sm', 'Mark the selected text', 'ann:mark', () => { if (!mark()) say.textContent = 'Select a stretch of the text first.'; })); const say = h('span', 'small faint', 'Select a stretch of the text to mark it as a span of the term chosen in the form.'); say.setAttribute('aria-live', 'polite'); row.appendChild(say); el.appendChild(row); } + paint(); + el._hooks.textOf = (a, b) => cps.slice(a, b).join(''); + } + + // Segments, drawn on the waveform. Times are seconds of the sound. + function segmentView(el, got, t, rec) { + const r = got.record, k = got.content || {}, may = A.may('edit'), items = () => itemsOf(t, rec); + if (k.seconds == null || !k.peaks || !k.peaks.length) { + el.appendChild(heading(r.id, 'Sound')); + el.appendChild(h('p', 'note', 'Tuldok reads a sound\'s length from a WAV only, so segments cannot be drawn on this one; its viewer is below.')); + V.record(el, got, t.run, store); return; + } + const secs = k.seconds; + el.appendChild(heading(r.id, [secs.toFixed(secs < 10 ? 2 : 1) + ' s', k.rate.toLocaleString('en-GB') + ' Hz', count(k.channels, 'channel'), bytes(r.bytes)].join(' · '))); + const cv = h('canvas', 'ann-surface ann-wave'); cv.tabIndex = 0; cv.dataset.key = 'ann:surface'; cv.setAttribute('role', 'application'); + cv.setAttribute('aria-label', 'Waveform of ' + r.id + ', ' + secs.toFixed(2) + ' seconds, with its segments. ' + (may ? 'Drag to mark a segment, drag a segment to move it, an end to move that end. N adds a segment, [ and ] choose one, the arrows move it, Shift and the arrows move its end, P plays it, Delete removes it.' : '')); + const said = h('p', 'sr-only'); said.setAttribute('aria-live', 'polite'); + const audio = h('audio'); audio.controls = true; audio.preload = 'metadata'; audio.src = r.url; audio.dataset.key = 'ann:audio'; audio.setAttribute('aria-label', 'Play ' + r.id); + el.appendChild(cv); el.appendChild(audio); el.appendChild(said); + if (may) el.appendChild(h('p', 'small faint ann-help', 'Drag on the waveform to mark a segment; drag a segment to move it, an end to move that end. With the waveform focused: N adds a segment, [ and ] choose one, the arrows move it by 0.05 s (Alt: by 0.5 s), Shift and the arrows move its end, P plays it, Delete removes it.')); + let frame = 0, drag = null, stopAt = null; + const paint = () => { + frame = 0; + const size = V.fit(cv, 120); if (!size) return; const [W, H] = size, dpr = window.devicePixelRatio || 1, ctx = cv.getContext('2d'); + ctx.clearRect(0, 0, W, H); V.wave(ctx, W, H, k.peaks); + const list = items(), mark = V.token('--k-refinement'), acc = V.token('--accent'), ink = V.token('--accent-ink'); + ctx.font = fontOf(Math.round(11.5 * dpr)); ctx.textBaseline = 'top'; + list.forEach((s, i) => { + const on = i === here.pick, x0 = s.start / secs * W, x1 = s.end / secs * W, c = on ? acc : mark; + ctx.fillStyle = rgb(c, on ? 0.26 : 0.16); ctx.fillRect(x0, 0, Math.max(1, x1 - x0), H); + ctx.fillStyle = rgb(c); ctx.fillRect(x0, 0, Math.max(1, dpr * (on ? 2 : 1)), H); ctx.fillRect(x1 - Math.max(1, dpr * (on ? 2 : 1)), 0, Math.max(1, dpr * (on ? 2 : 1)), H); + const label = (i + 1) + ' ' + s.term, tw = ctx.measureText(label).width + 8 * dpr; + ctx.fillRect(x0, 0, tw, 16 * dpr); ctx.fillStyle = rgb(ink); ctx.fillText(label, x0 + 4 * dpr, 2 * dpr); + }); + if (!audio.paused) { ctx.fillStyle = rgb(V.token('--ink')); ctx.fillRect(audio.currentTime / secs * W, 0, Math.max(1, dpr), H); } + const s = list[here.pick], text = s ? 'Segment ' + (here.pick + 1) + ', ' + s.term + ', ' + s.start.toFixed(2) + ' to ' + s.end.toFixed(2) + ' seconds' : count(list.length, 'segment'); + if (said.textContent !== text) said.textContent = text; + }; + const later = () => { if (!frame) frame = requestAnimationFrame(paint); }; + el._hooks.repaint = later; + V.paints(cv, paint); + const tick = () => { if (stopAt != null && audio.currentTime >= stopAt) { audio.pause(); stopAt = null; } later(); if (!audio.paused) requestAnimationFrame(tick); }; + audio.addEventListener('play', () => requestAnimationFrame(tick)); audio.addEventListener('pause', later); + el._hooks.play = i => { const s = items()[i]; if (!s) return; stopAt = s.end; audio.currentTime = s.start; const p = audio.play(); if (p && p.catch) p.catch(() => {}); }; + const round = v => Math.round(v * 1000) / 1000; + const at = e => { const q = cv.getBoundingClientRect(); return clamp((e.clientX - q.left) / q.width * secs, 0, secs); }; + cv.addEventListener('pointerdown', e => { + if (e.button !== 0 || !may) return; + e.preventDefault(); cv.focus({ preventScroll: true }); + const p = at(e), list = items(), tol = 6 * secs / cv.clientWidth; + let hit = null; + const order = list.map((_, i) => i).reverse(); if (here.pick >= 0 && list[here.pick]) order.unshift(here.pick); + for (const i of order) { const s = list[i]; if (Math.abs(p - s.start) <= tol) { hit = { mode: 'start', i }; break; } if (Math.abs(p - s.end) <= tol) { hit = { mode: 'end', i }; break; } } + if (!hit) for (const i of order) { const s = list[i]; if (p > s.start && p < s.end) { hit = { mode: 'move', i }; break; } } + if (!hit) { list.push({ term: newTerm(t), start: p, end: p }); hit = { mode: 'new', i: list.length - 1 }; } + drag = Object.assign(hit, { from: p, orig: Object.assign({}, list[hit.i]), id: e.pointerId, moved: false }); + here.pick = hit.i; cv.setPointerCapture(e.pointerId); later(); + }); + cv.addEventListener('pointermove', e => { + if (!drag || e.pointerId !== drag.id) return; + const p = at(e), s = items()[drag.i], o = drag.orig; if (!s) return; + drag.moved = true; + if (drag.mode === 'new') { s.start = Math.min(drag.from, p); s.end = Math.max(drag.from, p); } + else if (drag.mode === 'move') { const len = o.end - o.start, a = clamp(o.start + p - drag.from, 0, secs - len); s.start = a; s.end = a + len; } + else { const fixed = drag.mode === 'start' ? o.end : o.start; s.start = Math.min(fixed, p); s.end = Math.max(fixed, p); } + later(); + }); + const end = e => { + if (!drag || e.pointerId !== drag.id) return; + const list = items(), s = list[drag.i], d = drag; drag = null; + if (!s) return; + s.start = round(s.start); s.end = round(s.end); + if (s.end - s.start < 0.01) { if (d.mode === 'new') { list.splice(d.i, 1); here.pick = -1; if (here.relist) here.relist(); later(); return; } s.end = round(Math.min(secs, s.start + 0.01)); } + if (!d.moved) { if (here.relist) here.relist(); later(); return; } + touch(); + }; + cv.addEventListener('pointerup', end); cv.addEventListener('pointercancel', end); + cv.addEventListener('keydown', e => { + if (!may) return; + if ((e.key === 'p' || e.key === 'P') && items()[here.pick]) { e.preventDefault(); el._hooks.play(here.pick); return; } + surfaceKeys(e, items, () => { const a = round(clamp(audio.currentTime || 0, 0, Math.max(0, secs - 0.25))); return { term: newTerm(t), start: a, end: round(Math.min(secs, a + 0.25)) }; }, (s, key, shift, alt) => { + const step = alt ? 0.5 : 0.05, d = key === 'ArrowLeft' || key === 'ArrowDown' ? -step : step; + if (shift) s.end = round(clamp(s.end + d, s.start + 0.01, secs)); + else { const len = s.end - s.start; s.start = round(clamp(s.start + d, 0, secs - len)); s.end = round(s.start + len); } + }); + }); + } + + // ---- The form ---------------------------------------------------------------------------------------------------- + function buildForm(t, rec, detail) { + here.relist = null; + const d = draftOf(t, rec, true), a = rec.annotation, may = A.may('edit'), fits = !ONLY[t.type] || rec.kind === ONLY[t.type]; + const form = h('div', 'inspector ann-formbox'); + const hd = h('header'); hd.appendChild(h('span', 'kicker', t.title + ' · ' + t.type)); + const t2 = h('h2', 'mono', rec.id); t2.tabIndex = -1; hd.appendChild(t2); + const meta = h('div', 'ins-meta'), [tone, word] = STATE[marked(a)]; meta.appendChild(S.stateEl(tone, word)); + if (a && a.stale) meta.appendChild(h('span', 'ann-flag stale', 'stale')); + if (a && a.unsaved) meta.appendChild(h('span', 'ann-flag unsaved', 'unsaved')); + const um = h('span', 'umark' + (d.dirty ? ' typed' : ''), d.dirty ? 'not kept yet' : ''); meta.appendChild(um); + hd.appendChild(meta); + if (a) hd.appendChild(h('p', 'small faint', (a.state === 'draft' ? 'Drafted' : 'Annotated') + ' by ' + a.by + ' · ' + time(a.at))); + form.appendChild(hd); + if (a && a.stale) { + const box = h('div', 'ann-stale'); box.setAttribute('role', 'status'); + box.appendChild(h('p', null, rec.in_product ? 'Stale: the record\'s content differs from what was annotated.' : 'Stale: the record is gone from the current product of ' + t.dataset + '.')); + if (rec.in_product && detail && detail.annotation) box.appendChild(h('p', 'small mono', 'annotated ' + String(detail.annotation.sha256 || 'without a hash').slice(0, 12) + ' · now ' + String(detail.sha256 || 'not hashed').slice(0, 12))); + box.appendChild(h('p', 'small', rec.in_product ? 'The annotation as it was made is below. Still right keeps it for the content as it is now; or change it and keep it.' : 'Remove the annotation, or keep it until the record comes back.')); + form.appendChild(box); + } + const f = h('div', 'form ann-fields'); + if (!rec.in_product) f.appendChild(h('p', 'note', 'Nothing can be set on a record that is not in the product.')); + else if (rec.kind === 'file') f.appendChild(h('p', 'note', 'A file of no kind cannot be annotated.')); + else if (!fits) f.appendChild(h('p', 'note', 'This task annotates ' + ONLY[t.type] + ' records; this record is ' + (V.WORD[rec.kind] || rec.kind).toLowerCase() + ', so only a decision and a note can be kept for it.')); + if (rec.in_product && rec.kind !== 'file' && fits) valueControls(f, t, rec, d, may); + // The decision. + const dl = h('div', 'ann-field'); dl.appendChild(h('h3', null, 'Decision')); + const seg = h('div', 'seg ann-decide'); seg.setAttribute('role', 'group'); seg.setAttribute('aria-label', 'Decision'); + for (const [v, label, cls] of DECISIONS) { + const b = button(cls, label, 'ann:decide-' + v, () => { d.state = d.state === v ? null : v; for (const x of seg.children) x.setAttribute('aria-pressed', String(x.dataset.key === 'ann:decide-' + d.state)); touch(false); }); + b.setAttribute('aria-pressed', String(d.state === v)); b.disabled = !may || !rec.in_product; seg.appendChild(b); + } + dl.appendChild(seg); dl.appendChild(h('p', 'small faint', 'Without a decision, Keep and next keeps a draft.')); f.appendChild(dl); + const nl = h('label'); nl.appendChild(document.createTextNode('Note')); + const note = h('textarea'); note.rows = 2; note.maxLength = 4000; note.value = d.note; note.dataset.key = 'ann:note'; note.disabled = !may || !rec.in_product; note.placeholder = 'optional'; + note.addEventListener('input', () => { d.note = note.value; touch(false); }); nl.appendChild(note); f.appendChild(nl); + form.appendChild(f); + // Keep and next, Skip, Revert, Still right, Remove; a refusal is shown under them in the server's words. + const slot = A.slot('annotate:form'); if (slot.for !== draftKey(t, rec)) { slot.refusal = null; slot.confirming = null; slot.for = draftKey(t, rec); } + const k = draftKey(t, rec), after = () => { drafts.delete(k); }; + form.appendChild(A.group('annotate:form', [ + { id: 'keep', label: 'Keep and next', cls: 'btn primary', who: 'edit', op: 'set_annotation', busy: 'Keeping…', hidden: !rec.in_product, title: 'Enter', + args: () => ({ task: t.task, items: [itemOf(t, rec, d)] }), done: () => { after(); move(1); } }, + { id: 'skip', label: 'Skip', cls: 'btn ghost', onClick: () => { if (move(1)) redraw(); } }, + { id: 'still', label: 'Still right', cls: 'btn', who: 'edit', op: 'set_annotation', busy: 'Keeping…', hidden: !(a && a.stale && rec.in_product), + args: () => ({ task: t.task, items: [Object.assign({ record: rec.id, state: a.state, value: a.value }, a.note ? { note: a.note } : {})] }), done: after }, + { id: 'remove', label: 'Remove the annotation', cls: 'btn', who: 'edit', op: 'set_annotation', busy: 'Removing…', hidden: !(a && !rec.in_product), + confirm: 'Remove the annotation of ' + rec.id + '; Save removes its line from the file.', args: () => ({ task: t.task, items: [{ record: rec.id, remove: true }] }), done: after }, + { id: 'revert', label: 'Revert', cls: 'btn ghost', who: 'edit', op: 'revert_annotations', busy: 'Reverting…', hidden: !(a && a.unsaved), + confirm: 'Put back the saved annotation of ' + rec.id + ' in place of its unsaved one' + '; a record with no saved annotation has none again.', args: () => ({ task: t.task, records: [rec.id] }), done: after } + ])); + if (!may) form.appendChild(h('p', 'note', 'This session may look but not annotate: that needs the right to edit.')); + else form.appendChild(h('p', 'note', 'Keep and next keeps the annotation in Tuldok as an unsaved edit; Save writes every task\'s annotations to its file.')); + return form; + } + + /** The controls of the value, by task. */ + function valueControls(f, t, rec, d, may) { + if (t.type === 'review') return; + if (t.type === 'text') { + const l = h('label'); l.appendChild(document.createTextNode('Text')); + const area = h('textarea'); area.rows = 5; area.value = d.value || ''; area.dataset.key = 'ann:text'; area.disabled = !may; area.placeholder = 'a caption, a transcript or a summary'; + area.addEventListener('input', () => { d.value = area.value; touch(false); }); l.appendChild(area); f.appendChild(l); return; + } + if (t.type === 'class' || t.type === 'tags') { + const one = t.type === 'class', box = h('div', 'ann-field'); box.appendChild(h('h3', null, one ? 'Term' : 'Terms')); + const rd = h('div', 'radio ann-terms'); rd.setAttribute('role', one ? 'radiogroup' : 'group'); rd.setAttribute('aria-label', one ? 'Term' : 'Terms'); + t.vocabulary.forEach((term, i) => { + const l = h('label'), inp = h('input'); inp.type = one ? 'radio' : 'checkbox'; inp.name = 'ann-term'; inp.value = term; inp.dataset.key = 'ann:term-' + i; inp.disabled = !may; + inp.checked = one ? d.value === term : d.value.includes(term); + inp.addEventListener('change', () => { if (one) { if (inp.checked) d.value = term; } else d.value = inp.checked ? d.value.concat([term]) : d.value.filter(x => x !== term); touch(false); }); + l.appendChild(inp); l.appendChild(h('span', null, term)); if (i < 9) l.appendChild(kbd(String(i + 1))); rd.appendChild(l); + }); + box.appendChild(rd); f.appendChild(box); return; + } + // Boxes, spans and segments: the term of new ones, and the list of those drawn. + const box = h('div', 'ann-field'); + const what = { boxes: ['Boxes', 'box', 'boxes'], spans: ['Spans', 'span', 'spans'], segments: ['Segments', 'segment', 'segments'] }[t.type]; + const tl = h('label', 'ann-newterm'); tl.appendChild(document.createTextNode('Term of new ' + what[2])); + const ts = h('select'); ts.dataset.key = 'ann:new-term'; ts.disabled = !may; + for (const term of t.vocabulary) { const o = h('option', null, term); o.value = term; o.selected = term === newTerm(t); ts.appendChild(o); } + ts.addEventListener('change', () => { ui.terms.set(t.task, ts.value); }); + tl.appendChild(ts); box.appendChild(tl); + box.appendChild(h('h3', null, what[0])); + const listBox = h('div', 'ann-itembox'); box.appendChild(listBox); + const relist = () => putInPlace(listBox, itemList(t, d, what, may)); + here.relist = relist; listBox.appendChild(itemList(t, d, what, may)); + f.appendChild(box); + } + function itemList(t, d, what, may) { + const list = d.value; + if (!list.length) return h('p', 'note', 'No ' + what[2] + ' yet. ' + { boxes: 'Drag on the image to draw one.', spans: 'Select a stretch of the text to mark one.', segments: 'Drag on the waveform to mark one.' }[t.type]); + const ul = h('ul', 'ann-items'); + list.forEach((it, i) => { + const row = h('li', i === here.pick ? 'sel' : null); row.dataset.i = String(i); + const pick = button('linkish', (i + 1) + '', 'ann:item-' + i, () => { pickItem(here.pick === i ? -1 : i); }); pick.setAttribute('aria-label', 'Choose ' + what[1] + ' ' + (i + 1)); pick.setAttribute('aria-pressed', String(i === here.pick)); row.appendChild(pick); + const li = h('span', 'ann-fields'); row.appendChild(li); // the term, the place and Remove, after the number + const ts = h('select'); ts.dataset.key = 'ann:item-' + i + '-term'; ts.setAttribute('aria-label', 'Term of ' + what[1] + ' ' + (i + 1)); ts.disabled = !may; + for (const term of t.vocabulary.includes(it.term) ? t.vocabulary : [it.term].concat(t.vocabulary)) { const o = h('option', null, term); o.value = term; o.selected = term === it.term; ts.appendChild(o); } + ts.addEventListener('change', () => { it.term = ts.value; touch(); }); li.appendChild(ts); + const num = (name, label, step, lo, hi) => { + const n = h('input'); n.type = 'number'; n.step = String(step); n.value = String(it[name]); n.dataset.key = 'ann:item-' + i + '-' + name; n.setAttribute('aria-label', label + ' of ' + what[1] + ' ' + (i + 1)); n.disabled = !may; n.className = 'ann-num'; + n.addEventListener('change', () => { const v = Number(n.value); if (!Number.isFinite(v)) { n.value = String(it[name]); return; } it[name] = clamp(step === 1 ? Math.round(v) : Math.round(v * 1000) / 1000, lo(), hi()); if (it.start !== undefined && it.end <= it.start) it.end = Math.min(hi(), it.start + (step === 1 ? 1 : 0.01)); touch(); }); + return n; + }; + if (t.type === 'boxes') li.appendChild(h('span', 'mono small ann-coords', 'x ' + it.x + ', y ' + it.y + ' · ' + it.w + ' × ' + it.h)); + if (t.type === 'spans') { + const n = here.textOf ? Array.from(here.textOf(0, 1e9)).length : 1e9; + li.appendChild(num('start', 'Start', 1, () => 0, () => Math.max(0, it.end - 1))); li.appendChild(num('end', 'End', 1, () => it.start + 1, () => n)); + li.appendChild(h('q', 'ann-covered', here.textOf ? here.textOf(it.start, it.end) : '')); + } + if (t.type === 'segments') { + li.appendChild(num('start', 'Start (s)', 0.01, () => 0, () => Math.max(0, it.end - 0.01))); li.appendChild(num('end', 'End (s)', 0.01, () => it.start + 0.01, () => 1e9)); + const tx = h('input'); tx.type = 'text'; tx.value = it.text || ''; tx.placeholder = 'what is said (optional)'; tx.dataset.key = 'ann:item-' + i + '-text'; tx.setAttribute('aria-label', 'What is said in segment ' + (i + 1)); tx.disabled = !may; tx.className = 'ann-saying'; + tx.addEventListener('input', () => { it.text = tx.value; touch(false); }); li.appendChild(tx); + li.appendChild(button('btn sm', 'Play', 'ann:item-' + i + '-play', () => { if (here.play) here.play(i); })); + } + const rm = button('btn sm ghost', 'Remove', 'ann:item-' + i + '-remove', () => { list.splice(i, 1); here.pick = -1; touch(); }); rm.disabled = !may; rm.setAttribute('aria-label', 'Remove ' + what[1] + ' ' + (i + 1)); li.appendChild(rm); + ul.appendChild(row); + }); + return ul; + } + + // ---- Keys -------------------------------------------------------------------------------------------------------- + function onKey(e) { + if (e.defaultPrevented || e.altKey || e.ctrlKey || e.metaKey || !here || !here.root || !here.root.isConnected || !here.rec) return; + const t = e.target, choice = !!(t && t.matches && t.matches('input[type="radio"], input[type="checkbox"]')); // a term or a tag: its keys are the form's but the arrows + if (t && t.closest && t.closest('#aside, #needs-panel, dialog, .session-bar, audio, .turns, .ann-surface')) return; + if (!choice && t && t.closest && t.closest('input, select, textarea, [contenteditable="true"]')) return; + if (e.key === 'ArrowLeft' || e.key === 'ArrowRight') { if (choice) return; e.preventDefault(); if (move(e.key === 'ArrowRight' ? 1 : -1, !!(t.classList && t.classList.contains('rec')))) redraw(); return; } + if (e.key === 'Enter') { if (t.closest && t.closest('button, a, summary, [role="button"]') && !t.closest('.ann-decide')) return; const b = here.parts.form && here.parts.form.querySelector('[data-key="annotate:form:keep"]'); if (b && !b.disabled) { e.preventDefault(); b.click(); } return; } + if (/^[1-9]$/.test(e.key) && ['class', 'tags'].includes(here.t.type)) { + const box = here.parts.form && here.parts.form.querySelector('[data-key="ann:term-' + (Number(e.key) - 1) + '"]'); + if (!box || box.disabled) return; + e.preventDefault(); if (here.t.type === 'class') box.checked = true; else box.checked = !box.checked; + box.dispatchEvent(new Event('change')); + } + } + window.addEventListener('keydown', onKey); + + // ---- Forms in the drawer: a new task, an import, a freeze ------------------------------------------------------- + /** A form in the drawer for sel: drawn once, and again only after a control's answer, from what its slot keeps. */ + function formDrawer(aside, sel, load, build) { + if (aside._for === sel && aside._again !== 'control') return; + const same = aside._for === sel && !!aside.firstChild, mine = turn(aside); + aside._for = sel; aside._editing = null; + if (!same) { aside.textContent = ''; aside.appendChild(h('p', 'note', 'Reading…')); } + load().then(value => { if (aside._turn !== mine || aside._for !== sel) return; const ins = h('div', 'inspector ann-new'); build(ins, value); putDrawer(aside, ins); }, + error => { if (aside._turn !== mine || aside._for !== sel) return; putDrawer(aside, A.refusal(error)); }); + } + const slug = text => text.toLowerCase().normalize('NFKD').replace(/[̀-ͯ]/g, '').replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 64).replace(/-+$/, ''); + /** A labelled field whose value lives in the slot s under name. */ + function input(s, key, name, label, { type = 'text', hint, max, placeholder, area, value, onInput } = {}) { + const l = h('label'); l.appendChild(document.createTextNode(label)); + const i = area ? h('textarea') : h('input'); if (!area) i.type = type; else i.rows = area; + if (max) i.maxLength = max; if (placeholder) i.placeholder = placeholder; i.autocomplete = 'off'; i.spellcheck = false; + i.dataset.key = key + ':field:' + name; i.value = s.text[name] != null ? s.text[name] : value || ''; + if (s.text[name] == null && value) s.text[name] = value; + i.addEventListener('input', () => { s.text[name] = i.value; if (onInput) onInput(i.value); }); + l.appendChild(i); if (hint) l.appendChild(h('span', 'hint', hint)); return l; + } + function choice(s, key, name, label, options, fallback, onChange) { + const l = h('label'); l.appendChild(document.createTextNode(label)); + const sel = h('select'); sel.dataset.key = key + ':field:' + name; + if (s.text[name] == null || !options.some(o => o[0] === s.text[name])) s.text[name] = fallback; + for (const [v, text] of options) { const o = h('option', null, text); o.value = v; o.selected = v === s.text[name]; sel.appendChild(o); } + sel.addEventListener('change', () => { s.text[name] = sel.value; if (onChange) onChange(sel.value); }); + l.appendChild(sel); return l; + } + const lines = text => (text || '').split('\n').map(x => x.trim()).filter(Boolean); + const header = (ins, kicker, title, lead) => { const hd = h('header'); hd.appendChild(h('span', 'kicker', kicker)); const t2 = h('h2', null, title); t2.tabIndex = -1; hd.appendChild(t2); ins.appendChild(hd); if (lead) ins.appendChild(h('p', 'note', lead)); }; + + /** New task: title, name, dataset, task and vocabulary; kept as a new annotations/ definition. */ + function taskForm(aside, act) { + formDrawer(aside, 'annotate:new-task', () => P.read('definitions', { kind: 'dataset' }), (ins, defs) => { + const key = 'newtask', s = A.slot(key), sets = defs.definitions.filter(d => !d.removed); + header(ins, 'new annotation task', 'A new task', 'A task says what is recorded about the records of one dataset. It is kept as a new definition, an unsaved edit, until Save writes it to annotations/.json.'); + const f = h('div', 'form'); + let nameBox = null; + f.appendChild(input(s, key, 'title', 'Title (required)', { max: 200, placeholder: 'What is recorded', onInput: () => { if (!s.text.nameTyped && nameBox) { nameBox.value = slug(s.text.title || ''); s.text.name = nameBox.value; } } })); + const nl = input(s, key, 'name', 'Name', { max: 120, hint: 'a to z, 0 to 9, . _ -; the file is annotations/.json', placeholder: 'made from the title', onInput: v => { s.text.nameTyped = !!v; } }); + nameBox = nl.querySelector('input'); if (!s.text.nameTyped) { nameBox.value = slug(s.text.title || ''); s.text.name = nameBox.value; } + f.appendChild(nl); + if (!sets.length) f.appendChild(h('p', 'failure', 'The project has no dataset: a task annotates the records of one.')); + f.appendChild(choice(s, key, 'dataset', 'Dataset', sets.map(d => [d.reference, d.title + ' · ' + d.reference]), sets.length ? sets[0].reference : '')); + const vocab = input(s, key, 'vocabulary', 'Vocabulary: one term per line', { area: 5, hint: '1 to 500 different terms of 1 to 200 characters', placeholder: 'clean\nnoisy\nbroken' }); + const showVocab = type => { vocab.hidden = !NEEDS_TERMS.includes(type); }; + f.appendChild(choice(s, key, 'task', 'Task', TYPES.map(x => [x, x + ' · ' + TYPE_WORD[x]]), 'class', showVocab)); + showVocab(s.text.task); f.appendChild(vocab); + ins.appendChild(f); + const reference = () => 'annotations/' + (s.text.name || '').trim(); + ins.appendChild(A.group(key, [ + { id: 'keep', label: 'Keep', cls: 'btn primary', who: 'edit', op: 'set_definition', busy: 'Keeping…', + args: st => { + const doc = { format: FORMAT, kind: 'annotation', title: (st.text.title || '').trim(), dataset: st.text.dataset, task: st.text.task }; + if (NEEDS_TERMS.includes(st.text.task)) doc.vocabulary = lines(st.text.vocabulary); + return { reference: reference(), text: textOf(doc) }; + }, + done: r => { ui.task = r.reference; ui.page = 0; ui.filter = 'all'; act.select(null); } }, + { id: 'back', label: 'Cancel', cls: 'btn ghost', onClick: () => act.select(null) } + ])); + ins.appendChild(h('p', 'note', 'Keep checks the definition and keeps it in Tuldok as an unsaved edit; Save writes it to the project folder.')); + }); + } + + /** The Data tab's two forms (spec-d4 section 7): Import and Freeze, each kept as a new datasets/ definition. */ + function datasetForm(aside, which, act) { + const freeze = which === 'freeze', key = 'new' + which, sel = 'data:new:' + which; + if (!['import', 'freeze'].includes(which)) { aside.textContent = ''; aside._for = sel; aside.appendChild(h('p', 'empty', 'There is no form ' + which + ' here.')); return; } + formDrawer(aside, sel, () => Promise.all([P.read('definitions', { kind: 'dataset' }), freeze ? P.annotations.tasks() : null]), (ins, [defs, tasks]) => { + const s = A.slot(key), sets = defs.definitions.filter(d => !d.removed); + header(ins, freeze ? 'new dataset · freeze' : 'new dataset · import', freeze ? 'Freeze a dataset' : 'Import files', + freeze ? 'A dataset with splits made from another dataset\'s records and their annotations: the records the first task includes, ordered by the seed and cut by the shares. It reads the tasks\' annotations as saved and committed.' + : 'A dataset of files on this machine: each file under the source (or each line, with lines) becomes a record. A source relative to the code root is read from the commit a build uses.'); + const f = h('div', 'form'); + let nameBox = null; + f.appendChild(input(s, key, 'title', 'Title (required)', { max: 200, onInput: () => { if (!s.text.nameTyped && nameBox) { nameBox.value = slug(s.text.title || ''); s.text.name = nameBox.value; } } })); + const nl = input(s, key, 'name', 'Name', { max: 120, hint: 'the file is datasets/.json', placeholder: 'made from the title', onInput: v => { s.text.nameTyped = !!v; } }); + nameBox = nl.querySelector('input'); if (!s.text.nameTyped) { nameBox.value = slug(s.text.title || ''); s.text.name = nameBox.value; } + f.appendChild(nl); + if (!freeze) { + f.appendChild(input(s, key, 'source', 'Source (required)', { hint: 'a directory: relative to the code root, or absolute (this machine only)', placeholder: 'data/photos' })); + f.appendChild(input(s, key, 'pattern', 'Pattern', { hint: 'which files; empty: every file (**/*)', placeholder: '**/*.png' })); + f.appendChild(choice(s, key, 'kind', 'Kind', [['', 'By each file\'s extension']].concat(['text', 'image', 'audio', 'pointcloud', 'mesh', 'array', 'file'].map(k => [k, 'Every file is ' + (V.WORD[k] || k).toLowerCase()])), '')); + f.appendChild(input(s, key, 'rights', 'Rights (required)', { area: 2, max: 1000, hint: 'what may be done with the files', placeholder: 'Photographed by us; free to use.' })); + const lab = h('label', 'check'), box = h('input'); box.type = 'checkbox'; box.checked = !!s.text.lines; box.dataset.key = key + ':field:lines'; + box.addEventListener('change', () => { s.text.lines = box.checked; }); lab.appendChild(box); lab.appendChild(document.createTextNode(' Each line of a text file is a record of its own')); f.appendChild(lab); + } else { + const ofTasks = h('div', 'ann-field'); + const drawTasks = ds => { + const mine = tasks.tasks.filter(x => x.dataset === ds); + if (!Array.isArray(s.text.tasks) || s.text.tasksOf !== ds) { s.text.tasks = mine.length ? [mine[0].task] : []; s.text.tasksOf = ds; } // the dataset's first task, until the person chooses + const box = h('div'); box.appendChild(h('h3', null, 'Its tasks')); + if (!mine.length) box.appendChild(h('p', 'failure', ds ? ds + ' has no annotation task: a freeze takes its records by one.' : 'Choose the dataset first.')); + for (const m of mine) { + const lab = h('label', 'check'), c = h('input'); c.type = 'checkbox'; c.checked = s.text.tasks.includes(m.task); c.dataset.key = key + ':field:task-' + m.task; + c.addEventListener('change', () => { s.text.tasks = c.checked ? s.text.tasks.concat([m.task]) : s.text.tasks.filter(x => x !== m.task); drawTasks(ds); }); + lab.appendChild(c); lab.appendChild(document.createTextNode(' ' + m.title + ' · ' + m.task + (s.text.tasks[0] === m.task ? ' (first: its states take a record in)' : ''))); box.appendChild(lab); + } + putInPlace(ofTasks, box); + }; + f.appendChild(choice(s, key, 'dataset', 'The dataset whose records are frozen', sets.map(d => [d.reference, d.title + ' · ' + d.reference]), sets.length ? sets[0].reference : '', drawTasks)); + f.appendChild(ofTasks); drawTasks(s.text.dataset); + const two = h('div', 'two'); + two.appendChild(input(s, key, 'seed', 'Seed (required)', { type: 'number', value: '7', hint: 'an integer' })); + two.appendChild(input(s, key, 'shares', 'Shares (required)', { value: 'train 8, validation 1, test 1', hint: 'each split and its relative size' })); + f.appendChild(two); + const st = h('div', 'ann-field'); st.appendChild(h('h3', null, 'Which states of the first task take a record in')); + if (!Array.isArray(s.text.include)) s.text.include = ['accepted']; + for (const [v, label] of [['accepted', 'Accepted'], ['needs-work', 'Needs work'], ['rejected', 'Rejected'], ['draft', 'Draft']]) { + const lab = h('label', 'check'), c = h('input'); c.type = 'checkbox'; c.checked = s.text.include.includes(v); c.dataset.key = key + ':field:include-' + v; + c.addEventListener('change', () => { s.text.include = c.checked ? s.text.include.concat([v]) : s.text.include.filter(x => x !== v); }); + lab.appendChild(c); lab.appendChild(document.createTextNode(' ' + label)); st.appendChild(lab); + } + f.appendChild(st); + } + ins.appendChild(f); + const reference = () => 'datasets/' + (s.text.name || '').trim(); + ins.appendChild(A.group(key, [ + { id: 'keep', label: 'Keep', cls: 'btn primary', who: 'edit', op: 'set_definition', busy: 'Keeping…', args: st => ({ reference: reference(), text: textOf(freeze ? freezeDoc(st.text) : importDoc(st.text)) }), + done: r => { act.select(r.reference); } }, + { id: 'back', label: 'Cancel', cls: 'btn ghost', onClick: () => act.select(null) } + ])); + ins.appendChild(h('p', 'note', 'Keep checks the definition and keeps it in Tuldok as an unsaved edit; Save writes it. Building it is planned and requested as any build is.')); + }); + } + /** The definition an import writes (docs/contracts/project-folder.md, Steps Tuldok provides). */ + function importDoc(x) { + const settings = { source: (x.source || '').trim() }; + if ((x.pattern || '').trim()) settings.pattern = x.pattern.trim(); + if (x.kind) settings.kind = x.kind; + settings.rights = (x.rights || '').trim(); + if (x.lines) settings.lines = true; + return { format: FORMAT, kind: 'dataset', title: (x.title || '').trim(), run: { step: 'import', settings } }; + } + /** The definition a freeze writes; shares are read from "train 8, validation 1, test 1". */ + function freezeDoc(x) { + const shares = {}; + for (const part of String(x.shares || '').split(',').map(p => p.trim()).filter(Boolean)) { + const m = /^(\S+)\s*[ :=]\s*(\d+)$/.exec(part); + if (!m) throw Object.assign(Error('Shares are written as names and whole numbers, for example "train 8, validation 1, test 1"; "' + part + '" is not.'), { code: 'invalid' }); + shares[m[1]] = Number(m[2]); + } + const seed = Number(String(x.seed || '').trim()); + if (!Number.isInteger(seed) || String(x.seed || '').trim() === '') throw Object.assign(Error('The seed is a whole number.'), { code: 'invalid' }); + const settings = { seed, shares }; + const include = (x.include || []).slice().sort((a, b) => ['accepted', 'needs-work', 'rejected', 'draft'].indexOf(a) - ['accepted', 'needs-work', 'rejected', 'draft'].indexOf(b)); + if (!(include.length === 1 && include[0] === 'accepted')) settings.include = include; + return { format: FORMAT, kind: 'dataset', title: (x.title || '').trim(), run: { step: 'freeze', inputs: { records: x.dataset }, annotations: (x.tasks || []).slice(), settings } }; + } + + /** Needs you: the Annotate tab opens on this task. */ + function choose(task) { ui.task = task; ui.page = 0; ui.filter = 'all'; } + + S.annotate = annotate; + return { choose, datasetForm }; +})(); diff --git a/static/project-workspace/app.js b/static/project-workspace/app.js index 2105eaf5..6be3d43b 100644 --- a/static/project-workspace/app.js +++ b/static/project-workspace/app.js @@ -19,7 +19,7 @@ // shows the conflict panel. (() => { const P = window.TuldokProject, S = window.LabScreens, A = window.LabActions; - const TABS = [['map', 'Map'], ['data', 'Data'], ['train', 'Train'], ['benchmarks', 'Benchmarks'], ['analysis', 'Analysis'], ['overview', 'Overview']]; + const TABS = [['map', 'Map'], ['data', 'Data'], ['annotate', 'Annotate'], ['train', 'Train'], ['benchmarks', 'Benchmarks'], ['analysis', 'Analysis'], ['overview', 'Overview']]; const POLL_MS = 2000, IDLE_MS = 15000; // how often the page asks again while something builds, and while nothing does const ACTIVE_RUN = ['queued', 'running'], ACTIVE_REQUEST = ['queued', 'running']; const $ = id => document.getElementById(id); @@ -115,8 +115,8 @@ setText(m.firstChild, text + (p ? ' ' + p.stage + ': ' + p.completed + ' of ' + p.total + '.' : '')); setText(m.lastChild, ' Read at ' + data.readAt + '.'); want.push(m); - const n = data.status ? data.status.unsaved.length + data.status.removed.length : 0; - if (n) want.push(part('save', n + ' ' + A.may('edit'), () => A.stripSave(data.status, $('strip-note')))); + const n = data.status ? data.status.unsaved.length + data.status.removed.length : 0, a = P.annotationsUnsaved(data.status); + if (n || a) want.push(part('save', n + ' ' + a + ' ' + A.may('edit'), () => A.stripSave(data.status, $('strip-note')))); else if ($('strip-note').firstChild) $('strip-note').textContent = ''; want.push(needsButton()); } diff --git a/static/project-workspace/base.css b/static/project-workspace/base.css index 2eef2472..6b81e10c 100644 --- a/static/project-workspace/base.css +++ b/static/project-workspace/base.css @@ -656,3 +656,81 @@ div.row.def { cursor: default; } .iv-ends { display: flex; justify-content: space-between; margin-top: 2px; } .iv-facts { font-size: 12.5px; } .iv-hist { display: grid; gap: 6px; } + +/* ---- Annotating (annotate.js, spec-d4.md section 7); from the mockup's Annotate tab. ---- */ +.annotate { container-type: inline-size; min-width: 0; } +.ann-bar { display: flex; flex-wrap: wrap; gap: 8px 14px; align-items: center; margin-bottom: 14px; } +.ann-bar .ann-task { display: inline-flex; gap: 6px; align-items: center; font-size: 12.5px; color: var(--ink-2); min-width: 0; } +.ann-bar .ann-task select { max-width: 340px; min-width: 0; } +.ann-filter button { white-space: nowrap; } +.ann-progress { display: inline-flex; align-items: center; gap: 8px; font-size: 12.5px; color: var(--ink-2); white-space: nowrap; font-variant-numeric: tabular-nums; } +.ann-progress i { position: relative; display: inline-block; width: 90px; height: 4px; border-radius: 2px; background: var(--grid); overflow: hidden; } +.ann-progress b { position: absolute; left: 0; top: 0; bottom: 0; background: var(--good); } +.ann-keys { white-space: nowrap; } +.kbd { display: inline-block; font: 11px/1.4 var(--font); min-width: 16px; text-align: center; border: 1px solid var(--line-strong); border-bottom-width: 2px; border-radius: 3px; padding: 0 4px; color: var(--ink-2); background: var(--surface); } +.ann-body { display: grid; grid-template-columns: minmax(220px, 0.85fr) minmax(0, 1.5fr) minmax(290px, 340px); gap: 18px; align-items: start; } +@container (max-width: 1180px) { .ann-body { grid-template-columns: minmax(200px, 0.8fr) minmax(0, 1.5fr); } .ann-list { grid-row: span 2; } .ann-form { grid-column: 2; } } +@container (max-width: 700px) { .ann-body { grid-template-columns: minmax(0, 1fr); } .ann-list { grid-row: auto; } .ann-form { grid-column: auto; } } +.ann-list, .ann-view, .ann-form { min-width: 0; } +.ann-list .sect { margin-bottom: 8px; } +.ann-grid { grid-template-columns: repeat(auto-fill, minmax(88px, 1fr)); } +.ann-rec .th { position: relative; } +.ann-rec .th .pre { margin-right: 20px; } +.ann-rec.gone .th { color: var(--serious); } +.ann-rec .st { display: flex; gap: 6px; align-items: baseline; padding: 0 6px 4px; font-size: 11px; color: var(--ink-3); white-space: nowrap; overflow: hidden; } +.ann-rec .st b { font-weight: 500; } +.ann-rec .st b.stale { color: var(--serious); } +.ann-rec .st b.unsaved { color: var(--warn); } +.ann-rec[data-stale="1"] { border-color: var(--serious); } +.badge { position: absolute; right: 5px; top: 5px; width: 9px; height: 9px; border-radius: 50%; box-shadow: 0 0 0 2px var(--surface); } +.badge.none { background: var(--surface); box-shadow: inset 0 0 0 1.5px var(--ink-3), 0 0 0 2px var(--surface); } +.badge.draft { background: var(--accent); } +.badge.accepted { background: var(--good); } +.badge.needs-work { background: var(--warn); } +.badge.rejected { background: var(--serious); } +.ann-view.viewer { position: static; max-height: none; overflow: visible; } +.ann-nav { display: flex; align-items: center; justify-content: space-between; gap: 8px; } +.ann-stage { width: 100%; min-width: 0; display: flex; justify-content: center; background: var(--surface-2); border-radius: var(--radius); } +.ann-imgwrap { position: relative; max-width: 100%; } +.ann-imgwrap img { display: block; width: 100%; height: 100%; user-select: none; -webkit-user-drag: none; } +.ann-imgwrap.pixels img { image-rendering: pixelated; } +.ann-imgwrap canvas.ann-surface { position: absolute; inset: 0; width: 100%; height: 100%; background: transparent; border-radius: 0; cursor: crosshair; touch-action: none; } +.iv canvas.ann-wave { cursor: crosshair; touch-action: none; } +.ann-surface:focus-visible { outline: 2px solid var(--focus); outline-offset: 2px; } +.ann-help { max-width: none; } +.ann-text mark.ann-span { background: color-mix(in srgb, var(--k-refinement) 26%, transparent); color: inherit; border-bottom: 2px solid var(--k-refinement); cursor: pointer; } +.ann-text mark.ann-span.many { background: color-mix(in srgb, var(--k-refinement) 42%, transparent); } +.ann-text mark.ann-span.sel { background: color-mix(in srgb, var(--accent) 30%, transparent); border-bottom-color: var(--accent); } +.ann-text .ann-tag { display: inline-block; margin: 0 2px; padding: 0 4px; border-radius: 3px; font: 10.5px/1.5 var(--font); background: var(--k-refinement); color: var(--accent-ink); vertical-align: 1px; user-select: none; -webkit-user-select: none; } +.ann-text .ann-tag.sel { background: var(--accent); } +.ann-formbox { gap: 14px; } +.ann-formbox h2.mono { font-family: var(--mono); font-size: 14px; } +.ann-flag { font-size: 11.5px; font-weight: 500; } +.ann-flag.stale { color: var(--serious); } +.ann-flag.unsaved { color: var(--warn); } +.ann-field { display: grid; gap: 6px; min-width: 0; } +.ann-field h3 { margin: 0; } +.form .radio.ann-terms label { padding: 3px 6px 3px 10px; } +.form .radio.ann-terms .kbd { margin-left: 2px; } +.ann-decide { justify-self: start; } +.seg button.ok[aria-pressed="true"] { background: var(--good-wash); color: var(--ink); box-shadow: inset 0 -2px 0 var(--good); } +.seg button.warn[aria-pressed="true"] { background: var(--warn-wash); color: var(--ink); box-shadow: inset 0 -2px 0 var(--warn); } +.seg button.bad[aria-pressed="true"] { background: var(--serious-wash); color: var(--ink); box-shadow: inset 0 -2px 0 var(--serious); } +.seg button[disabled] { cursor: not-allowed; opacity: .55; } +.ann-newterm { max-width: 260px; } +.ann-items { list-style: none; margin: 0; padding: 0; display: grid; gap: 4px; } +.ann-items li { display: grid; grid-template-columns: auto minmax(0, 1fr); gap: 6px; align-items: start; padding: 5px 6px; border: 1px solid var(--line); border-radius: var(--radius); background: var(--surface); min-width: 0; } +.ann-items li.sel { border-color: var(--accent); box-shadow: inset 3px 0 0 var(--accent); } +.ann-items .linkish { font: 600 12.5px var(--mono); color: var(--accent); background: none; border: 0; padding: 0 4px; cursor: pointer; min-width: 22px; } +.ann-items select { max-width: 116px; min-height: 26px; padding: 1px 4px; font-size: 13px; } +.form .ann-items input.ann-num { width: 66px; min-height: 26px; padding: 1px 4px; } +.form .ann-items input.ann-saying { flex: 1 1 140px; min-width: 0; width: auto; min-height: 26px; padding: 1px 6px; } +.ann-items .ann-coords { color: var(--ink-2); flex: 1 1 auto; } +.ann-items .ann-covered { flex: 1 1 100%; font-size: 12.5px; color: var(--ink-2); overflow-wrap: anywhere; } +.ann-items .ann-fields { display: flex; flex-wrap: wrap; gap: 6px; align-items: center; min-width: 0; } +.ann-items .linkish { min-height: 26px; } +.ann-items .ann-fields > .btn.ghost { margin-left: auto; } +.ann-stale { display: grid; gap: 4px; padding: 8px 10px; border: 1px solid var(--serious); border-left-width: 3px; border-radius: var(--radius); background: var(--serious-wash); } +.ann-stale p:first-child { color: var(--serious); font-weight: 500; } +.ann-empty { display: grid; gap: 12px; justify-items: start; } +.ann-new .form h3 { margin: 4px 0 0; } diff --git a/static/project-workspace/inside.js b/static/project-workspace/inside.js index 42babd73..5348a749 100644 --- a/static/project-workspace/inside.js +++ b/static/project-workspace/inside.js @@ -415,22 +415,24 @@ window.LabInside = (() => { el.appendChild(h('p', 'small muted', has ? [k.seconds.toFixed(k.seconds < 10 ? 2 : 1) + ' s', k.rate.toLocaleString('en-GB') + ' Hz', count(k.channels, 'channel'), count(k.frames, 'frame')].join(' · ') : 'Length, rate and channels are read from a WAV only; the player reads the rest.')); if (has && k.peaks && k.peaks.length) { const cv = h('canvas', 'iv-wave'); cv.setAttribute('role', 'img'); cv.setAttribute('aria-label', 'Waveform of ' + id + ', ' + k.seconds.toFixed(2) + ' seconds'); - paints(cv, () => { - const size = fit(cv, 96); if (!size) return; const [W, H] = size, ctx = cv.getContext('2d'); ctx.clearRect(0, 0, W, H); - const ink = token('--mark'), axis = token('--line-strong'), n = k.peaks.length; - ctx.fillStyle = 'rgb(' + axis.join(',') + ')'; ctx.fillRect(0, Math.floor(H / 2), W, 1); - ctx.fillStyle = 'rgb(' + ink.join(',') + ')'; - for (let x = 0; x < W; x++) { - const a = Math.floor(x / W * n), b = Math.max(a + 1, Math.floor((x + 1) / W * n)); let lo = 1, hi = -1; - for (let i = a; i < b && i < n; i++) { lo = Math.min(lo, k.peaks[i][0]); hi = Math.max(hi, k.peaks[i][1]); } - if (hi < lo) continue; const y0 = (1 - hi) / 2 * (H - 2) + 1, y1 = (1 - lo) / 2 * (H - 2) + 1; ctx.fillRect(x, y0, 1, Math.max(1, y1 - y0)); - } - }); + paints(cv, () => { const size = fit(cv, 96); if (!size) return; const ctx = cv.getContext('2d'); ctx.clearRect(0, 0, size[0], size[1]); wave(ctx, size[0], size[1], k.peaks); }); el.appendChild(cv); } const a = h('audio'); a.controls = true; a.preload = 'metadata'; a.src = url; a.dataset.key = 'iv-audio'; a.setAttribute('aria-label', 'Play ' + id); el.appendChild(a); } + /** A sound's waveform from its peaks ([low, high] per bucket, -1 to 1) across a W by H canvas: the axis, then a bar per column. */ + function wave(ctx, W, H, peaks) { + const ink = token('--mark'), axis = token('--line-strong'), n = peaks.length; + ctx.fillStyle = 'rgb(' + axis.join(',') + ')'; ctx.fillRect(0, Math.floor(H / 2), W, 1); + ctx.fillStyle = 'rgb(' + ink.join(',') + ')'; + for (let x = 0; x < W; x++) { + const a = Math.floor(x / W * n), b = Math.max(a + 1, Math.floor((x + 1) / W * n)); let lo = 1, hi = -1; + for (let i = a; i < b && i < n; i++) { lo = Math.min(lo, peaks[i][0]); hi = Math.max(hi, peaks[i][1]); } + if (hi < lo) continue; const y0 = (1 - hi) / 2 * (H - 2) + 1, y1 = (1 - lo) / 2 * (H - 2) + 1; ctx.fillRect(x, y0, 1, Math.max(1, y1 - y0)); + } + } + // ---- Point clouds and meshes: turned by dragging, zoomed by the wheel ---------------------------------------------- const turned = () => ({ yaw: -0.6, pitch: 0.45, zoom: 1 }); function cloudView(el, k, st) { @@ -697,5 +699,11 @@ window.LabInside = (() => { ctx.globalAlpha = 1; } - return { open, leave, PER_PAGE }; + /** + * What the Annotate tab (annotate.js) draws with: a record's viewer as this module draws it, from the answer of + * `record` (run: the product's run; store: a Map that keeps each viewer's settings, as a dataset opened here does), + * and the parts its own drawing surfaces share with these viewers. + */ + const viewers = { record: (el, got, run, store) => recordView(null, { run, viewers: store }, el, got), wave, paints, fit, token, glyph, WORD }; + return { open, leave, PER_PAGE, viewers }; })(); diff --git a/static/project-workspace/tabs.js b/static/project-workspace/tabs.js index 1b26515f..ccd90145 100644 --- a/static/project-workspace/tabs.js +++ b/static/project-workspace/tabs.js @@ -619,7 +619,12 @@ const users = new Map(); for (const e of graph.edges) { if (!users.has(e.to)) users.set(e.to, new Set()); users.get(e.to).add(e.from); } const built = sets.filter(d => byRef.has(d.reference)).length, adopted = sets.filter(d => (byRef.get(d.reference) || []).some(p => p.adopted)).length; const total = sets.reduce((n, d) => n + (byRef.get(d.reference) || []).reduce((a, p) => a + (p.bytes || 0), 0), 0); - frag.appendChild(sect('Datasets', sets.length + ' · ' + built + ' with files on this machine' + (adopted ? ', ' + adopted + ' adopted' : '') + (total ? ' · ' + bytes(total) : ''))); + const head = sect('Datasets', sets.length + ' · ' + built + ' with files on this machine' + (adopted ? ', ' + adopted + ' adopted' : '') + (total ? ' · ' + bytes(total) : '')); + // Two forms that keep a new dataset as an unsaved edit (spec-d4 section 7, annotate.js): files brought in, and a dataset frozen with splits. + if (window.LabAnnotate) { head.appendChild(h('span', 'spacer')); head.appendChild(A.group('data:new', [ + { id: 'import', label: 'Import files', cls: 'btn sm', who: 'edit', onClick: () => act.select(sel === 'new:import' ? null : 'new:import') }, + { id: 'freeze', label: 'Freeze a dataset', cls: 'btn sm', who: 'edit', onClick: () => act.select(sel === 'new:freeze' ? null : 'new:freeze') }], { inline: true })); } + frag.appendChild(head); if (!sets.length) { frag.appendChild(h('p', 'empty', 'The project defines no dataset.')); return; } const grid = h('div', 'ds-grid'); for (const d of sets) { @@ -646,15 +651,17 @@ frag.appendChild(grid); }); if (!sel) return closeDrawer(aside); + if (raw.startsWith('new:') && window.LabAnnotate) { window.LabAnnotate.datasetForm(aside, raw.slice(4), act); return true; } if (E && E.owns(raw, data)) { E.drawer(aside, raw, act, data, 'data'); return true; } drawer(aside, sel, () => Promise.all([P.read('definition', { reference: sel }), P.read('products', { reference: sel })]), (ins, [d, p]) => { const hd = h('header'); hd.appendChild(h('span', 'kicker', d.reference)); const t2 = h('h2', null, d.title); t2.tabIndex = -1; hd.appendChild(t2); const meta = h('div', 'ins-meta'); meta.appendChild(p.products.some(x => x.adopted) ? S.stateEl('good', 'adopted') : modelState(d.state)); meta.appendChild(Tree.mark({ id: d.reference, unsaved: d.unsaved })); hd.appendChild(meta); ins.appendChild(hd); // Edit (spec-w3 section 3.2): the editor, in the text view. if (p.products.some(x => x.run_id)) { const look = h('div', 'actions'); look.appendChild(lookInside(d.reference, act)); ins.appendChild(look); } - ins.appendChild(A.group('dataedit:' + d.reference, [{ id: 'edit', label: 'Edit', cls: 'btn sm', who: 'edit', onClick: () => act.select('edit:' + d.reference) }])); - if (E) E.decorate(hd); const doc = d.document || {}; + ins.appendChild(A.group('dataedit:' + d.reference, [{ id: 'edit', label: 'Edit', cls: 'btn sm', who: 'edit', onClick: () => act.select('edit:' + d.reference) }, + { id: 'plan', label: 'Plan build', cls: 'btn sm', who: 'request', hidden: !(doc.run && typeof doc.run === 'object'), onClick: () => act.go('train', 'plan:' + d.reference) }])); + if (E) E.decorate(hd); ins.appendChild(block('Description', doc.description ? h('p', null, doc.description) : h('p', 'note', 'The definition has no description.'))); const su = setup(); const skip = new Set(['format', 'kind', 'title', 'description']); for (const [k, v] of Object.entries(doc)) { diff --git a/tests/browser_project_workspace_annotate.cjs b/tests/browser_project_workspace_annotate.cjs new file mode 100644 index 00000000..363cccf0 --- /dev/null +++ b/tests/browser_project_workspace_annotate.cjs @@ -0,0 +1,534 @@ +'use strict'; +// Annotating from the page (docs/plans/definition-first-projects/spec-d4.md sections 7 and 9, slice D4d) in a headless +// browser, the owner signed in, no GPU. The fixture is a project of its own in a Git repository: code/samples holds a +// file of each kind (written by examples/tiny-project/code/make_samples.py, and an array written here), the dataset +// datasets/specimens imports them with the import step (built by the command line before Tuldok starts), and the task +// annotations/quality has three stale annotations in its line file (two whose content differs, one whose record is +// gone). datasets/later imports from the same source and is never built. +// 1. The Annotate tab opens on quality; the filter Stale lists the three, each tile marked stale; the record whose +// content differs says so and Still right puts it right; the one that is gone is removed. +// 2. A task of each of the seven kinds is made with New task and one record annotated with it: review and text by +// the form's buttons and field, class and tags by the keys 1 to 9 and Enter, boxes by dragging on the image +// and the arrow keys, spans by selecting text with the pointer (after an astral character), segments by dragging +// on the waveform and Shift and an arrow; a stretch is played. +// 3. The strip counts "7 definitions, 9 annotations unsaved"; Save writes them: each task's file has exactly the line +// expected (a box's pixels, a span's offsets and the text they cover, a segment's seconds) and the strip's count +// is gone. A reload shows each annotation again; the filter by state lists what it should. +// 4. With text typed into the form and not kept, the window regaining focus and a reading on the timer add, remove +// and change no node of the main area, and the text, the focus and the caret are there. A second session (an +// agent credential with the right to edit) sets an annotation: the grid shows it and the form is not touched. +// 5. A task on a dataset with no product says so and plans the dataset. +// 6. The Data tab's Import and Freeze forms each keep a definition, written by Save exactly as expected, which +// `check` accepts; the freeze is planned from its drawer. +// 7. Screenshots of each task's form (an annotation drawn), the stale state, New task and the two Data forms, in light +// and dark at 1440 by 900 and 1000 by 800 (with --shots , written there too); nothing overflows sideways. +// It fails on any script error, and on any failed request. +// node tests/browser_project_workspace_annotate.cjs [--shots ] +const assert = require('node:assert/strict'), fs = require('node:fs'), os = require('node:os'), path = require('node:path'); +const { spawn, execFileSync } = require('node:child_process'), { once } = require('node:events'); +const { authenticatedFixture } = require('./auth_helpers.cjs'), { waitForDebugger } = require('./browser_startup.cjs'), { cdpSession } = require('./browser_cdp_session.cjs'), { qaDirectory } = require('./qa_artifacts.cjs'); + +const root = path.resolve(__dirname, '..'); +const argv = process.argv.slice(2), option = name => { const i = argv.indexOf(name); return i >= 0 ? argv[i + 1] : null; }; +assert.ok(process.env.TULDOK_DATABASE_URL, 'TULDOK_DATABASE_URL must name a disposable PostgreSQL cluster'); +const venv = path.join(root, '.venv', 'bin'); +if (fs.existsSync(path.join(venv, 'python'))) process.env.PATH = venv + path.delimiter + process.env.PATH; // auth_helpers runs python3 +const python = fs.existsSync(path.join(venv, 'python')) ? path.join(venv, 'python') : 'python3'; +const IDLE_MS = 15000; // the page's reading while nothing builds (app.js) +const WATCHED = ['summary', 'status', 'build_requests', 'environments', 'runs']; +const REF = 'datasets/specimens'; +const IDS = ['arrays__grid.npy', 'clouds__ring.ply', 'images__shapes.png', 'meshes__pyramid.obj', 'sounds__two-tones.wav', 'texts__greeting.txt', 'texts__weather.txt']; + +const temporary = fs.mkdtempSync(path.join(os.tmpdir(), 'tuldok-annotate-browser-')); +const report = qaDirectory(root, 'project-workspace-annotate'); +const shots = option('--shots') ? path.resolve(option('--shots')) : null; if (shots) fs.mkdirSync(shots, { recursive: true }); +const children = [], checks = [], errors = [], failures = [], refused = []; +let server, serverErrors = '', origin, auth, socket, session, send, evaluate, owned = null; +const pause = ms => new Promise(resolve => setTimeout(resolve, ms)); +async function until(fn, label, tries = 300) { for (let i = 0; i < tries; i++) { const value = await fn(); if (value) return value; await pause(100); } throw Error('Timed out: ' + label); } +function check(text) { checks.push(text); console.log('PASS ' + text); } +function launch(command, args, options) { const child = spawn(command, args, options); children.push(child); return child; } +async function stop(child) { if (!child || child.exitCode !== null || child.signalCode !== null) return; const exited = once(child, 'exit'); child.kill('SIGTERM'); await Promise.race([exited, pause(10000)]); if (child.exitCode === null && child.signalCode === null) { child.kill('SIGKILL'); await exited; } } +function findBrowser() { + const candidates = [process.env.BROWSER, '/usr/bin/chromium', '/usr/bin/chromium-browser', '/usr/bin/google-chrome']; + const cache = path.join(os.homedir(), '.cache', 'ms-playwright'); + if (fs.existsSync(cache)) for (const name of fs.readdirSync(cache).filter(n => n.startsWith('chromium_headless_shell-')).sort().reverse()) candidates.push(path.join(cache, name, 'chrome-headless-shell-linux64', 'chrome-headless-shell')); + const found = candidates.find(candidate => candidate && fs.existsSync(candidate)); + assert.ok(found, 'No headless browser: set BROWSER'); + return found; +} +/** Drops the project's schema and the catalog's from the disposable database, so each run imports afresh. */ +function dropOwned(folder, catalog) { + const id = JSON.parse(fs.readFileSync(path.join(folder, 'tuldok.json'), 'utf8')).id; + execFileSync(python, ['-c', `import json, os, pathlib, sys, psycopg +from psycopg import sql +from tuldok_project import store +store.drop_project(sys.argv[1], os.environ['TULDOK_DATABASE_URL']) +root = pathlib.Path(sys.argv[2]) +if root.exists(): + with psycopg.connect(os.environ['TULDOK_DATABASE_URL'], autocommit=True) as c: + for p in root.rglob('.tuldok.json'): + v = json.loads(p.read_text()) + name = 'projection_' + v['projection_id'] if v.get('version') == 2 else 'catalog_' + v['dataset_id'] + c.execute(sql.SQL('DROP SCHEMA IF EXISTS {} CASCADE').format(sql.Identifier(name))) +`, id, catalog], { cwd: root, stdio: ['ignore', 'pipe', 'pipe'] }); +} +async function contract(name) { + const capabilities = await (await auth.fetch(origin + '/api/agent/capabilities')).json(); + const operation = capabilities.operations.find(item => item.id === 'project.' + name), c = operation.contracts[operation.contracts.length - 1]; + return 'project.' + name + '/' + c.version + '/' + c.sha256; +} +/** An operation as the owner (bearer: as that agent credential instead). */ +async function api(name, body = {}, bearer = null) { + const headers = { 'Content-Type': 'application/json', 'Tuldok-Operation-Contract': await contract(name) }; + const response = bearer ? await globalThis.fetch(origin + '/api/project/' + name, { method: 'POST', headers: { ...headers, Authorization: 'Bearer ' + bearer }, body: JSON.stringify(body) }) + : await auth.fetch(origin + '/api/project/' + name, { method: 'POST', headers, body: JSON.stringify(body) }); + const value = await response.json(); assert.equal(response.status, 200, name + ': ' + JSON.stringify(value)); return value; +} +async function credential(label, scopes) { + const response = await auth.fetch(origin + '/api/access/credentials', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ label, scopes, ttl_seconds: 3600 }) }); + const value = await response.json(); assert.equal(response.status, 201, JSON.stringify(value)); return value.token; +} + +// ---- The page's readings, from the browser's network (as browser_project_workspace_still.cjs) ---------------- +const calls = new Map(), finished = []; +function network(event) { + const p = event.params; + if (event.method === 'Network.requestWillBeSent' && /\/api\/project\/[a-z_]+$/.test(p.request.url)) calls.set(p.requestId, { name: p.request.url.split('/').pop(), sent: Date.now() }); + if ((event.method === 'Network.loadingFinished' || event.method === 'Network.loadingFailed') && calls.has(p.requestId)) { finished.push(Object.assign(calls.get(p.requestId), { done: Date.now() })); calls.delete(p.requestId); } +} +async function reading(since, names, label, tries = 300) { + await until(() => names.every(name => finished.some(f => f.name === name && f.sent >= since)), 'a reading: ' + label, tries); + await until(() => !calls.size && Date.now() - Math.max(0, ...finished.map(f => f.done)) > 700, 'the reading done: ' + label, 300); + await settled(label); +} +/** Waits until nothing reads: no call of the project in flight, no "Reading…", nothing busy. */ +async function settled(label) { + await until(async () => !calls.size && await evaluate(`(() => { const reading = e => [...e.querySelectorAll('.note')].some(n => n.textContent === 'Reading…'); return !reading(document.getElementById('main')) && !reading(document.getElementById('aside')) && !document.getElementById('main').hasAttribute('aria-busy') && !document.querySelector('.act-group [aria-busy]'); })()`), 'settled: ' + label); + await pause(200); + await until(async () => !calls.size, 'settled again: ' + label); +} +async function hash(value) { await evaluate(`location.hash = ${JSON.stringify('#' + value)}`); await settled('#' + value); await pause(200); await settled('#' + value); } +const byKey = key => `[data-key=${JSON.stringify(key)}]`; +async function centre(selector) { + return until(() => evaluate(`(() => { const e = [...document.querySelectorAll(${JSON.stringify(selector)})].find(e => e.offsetParent !== null); if (!e) return null; e.scrollIntoView({ block: 'nearest', inline: 'nearest' }); const r = e.getBoundingClientRect(), x = r.left + r.width / 2, y = r.top + r.height / 2, hit = document.elementFromPoint(x, y); return hit && (hit === e || e.contains(hit)) ? { x, y } : null; })()`), 'shown: ' + selector, 100); +} +async function mouse(type, x, y, buttons = 0, modifiers = 0) { await send('Input.dispatchMouseEvent', { type, x, y, modifiers, button: type === 'mouseMoved' ? (buttons ? 'left' : 'none') : 'left', buttons, clickCount: type === 'mouseMoved' ? 0 : 1 }); } +async function press(selector) { const { x, y } = await centre(selector); await mouse('mouseMoved', x, y); await mouse('mousePressed', x, y, 1); await mouse('mouseReleased', x, y); } +async function dragFrom(a, b, steps = 8) { await mouse('mouseMoved', a.x, a.y); await mouse('mousePressed', a.x, a.y, 1); for (let i = 1; i <= steps; i++) await mouse('mouseMoved', a.x + (b.x - a.x) * i / steps, a.y + (b.y - a.y) * i / steps, 1); await mouse('mouseReleased', b.x, b.y); } +const KEYS = { Enter: 13, ArrowLeft: 37, ArrowUp: 38, ArrowRight: 39, ArrowDown: 40, Delete: 46 }; +async function key(name, modifiers = 0) { + const code = KEYS[name] || name.toUpperCase().charCodeAt(0), text = name.length === 1 ? name : name === 'Enter' ? '\r' : undefined; + await send('Input.dispatchKeyEvent', { type: text ? 'keyDown' : 'rawKeyDown', key: name, code: /^\d$/.test(name) ? 'Digit' + name : name.length === 1 ? 'Key' + name.toUpperCase() : name, windowsVirtualKeyCode: code, modifiers, text }); + await send('Input.dispatchKeyEvent', { type: 'keyUp', key: name, windowsVirtualKeyCode: code, modifiers }); +} +async function type(selector, text) { await press(selector); await evaluate(`(() => { const e = document.activeElement; if (e.select) e.select(); return true; })()`); await send('Input.insertText', { text }); } +/** Sets a select's value as a person would choose it, with its change event. */ +async function choose(selector, value) { await press(selector); await evaluate(`(() => { const s = document.querySelector(${JSON.stringify(selector)}); s.value = ${JSON.stringify(value)}; s.dispatchEvent(new Event('change', { bubbles: true })); return true; })()`); await key('Escape'); } +async function shot(name) { + await evaluate('new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve)))'); + const png = Buffer.from((await send('Page.captureScreenshot', { format: 'png', captureBeyondViewport: false })).data, 'base64'); + fs.writeFileSync(path.join(report, name + '.png'), png); if (shots) fs.writeFileSync(path.join(shots, name + '.png'), png); +} +const stripText = () => evaluate(`document.getElementById('strip').innerText.replace(/\\s+/g, ' ')`); +const form = () => evaluate(`(() => { const f = document.querySelector('#main .ann-form'); return f ? f.innerText : ''; })()`); +const tiles = () => evaluate(`[...document.querySelectorAll('#main .ann-rec')].map(b => ({ id: b.dataset.id, state: b.dataset.state, stale: b.dataset.stale === '1', unsaved: b.dataset.unsaved === '1', pressed: b.getAttribute('aria-pressed') === 'true' }))`); +const lines = name => { const file = path.join(folder, 'annotations', name + '.jsonl'); return fs.existsSync(file) ? fs.readFileSync(file, 'utf8').split('\n').filter(Boolean).map(l => JSON.parse(l)) : []; }; + +// The watcher of browser_project_workspace_still.cjs, and the form of the Annotate tab on its own. +const WATCHER = `window.__still = (() => { + const ids = ['tabs', 'strip', 'main', 'aside', 'needs-panel'], el = id => document.getElementById(id); + let counts = null, flash = 0, timer = null, observers = []; + const name = n => !n ? '?' : n.nodeType === 1 ? n.tagName.toLowerCase() + (typeof n.className === 'string' && n.className ? '.' + n.className.trim().split(/\\s+/).join('.') : '') : '#text ' + JSON.stringify(String(n.data || '').slice(0, 30)); + const watch = (key, node) => { const o = new MutationObserver(list => { + if (!counts) return; + const c = counts[key]; + for (const r of list) { + if (r.type === 'childList') { c.added += r.addedNodes.length; c.removed += r.removedNodes.length; for (const n of [...r.addedNodes, ...r.removedNodes]) if (c.what.length < 6) c.what.push(name(n) + ' in ' + name(r.target)); } + else if (r.type === 'characterData') { const msg = el('strip').querySelector('.msg'); if (msg && r.target === msg.lastChild) c.readAt++; else { c.text++; if (c.what.length < 6) c.what.push('text of ' + name(r.target.parentNode)); } } + else { c.attrs++; if (c.what.length < 6) c.what.push('@' + r.attributeName + ' on ' + name(r.target)); } + } + }); o.observe(node, { childList: true, subtree: true, characterData: true, attributes: true }); observers.push(o); }; + return { + start() { + for (const o of observers) o.disconnect(); observers = []; + counts = {}; for (const id of ids.concat(['form'])) counts[id] = { added: 0, removed: 0, attrs: 0, text: 0, readAt: 0, what: [] }; + for (const id of ids) { watch(id, el(id)); for (const e of el(id).querySelectorAll('*')) e.__seen = 1; } + const f = document.querySelector('#main .ann-form'); if (f) watch('form', f); + flash = 0; clearInterval(timer); timer = setInterval(() => { if ((el('main').textContent + el('aside').textContent).includes('Reading…')) flash++; }, 50); + }, + stop() { clearInterval(timer); const fresh = {}; for (const id of ids) fresh[id] = [...el(id).querySelectorAll('*')].filter(e => !e.__seen).length; const r = { counts, flash, fresh }; counts = null; for (const o of observers) o.disconnect(); observers = []; return r; } + }; +})(); true`; + +let folder; +(async () => { + // ---- The fixture: a project in Git, code/samples of each kind, datasets/specimens built -------------------------- + const repo = path.join(temporary, 'fixture'), code = path.join(repo, 'code'); folder = path.join(repo, 'project'); + for (const d of ['datasets', 'annotations']) fs.mkdirSync(path.join(folder, d), { recursive: true }); + fs.mkdirSync(code, { recursive: true }); + fs.writeFileSync(path.join(folder, 'tuldok.json'), JSON.stringify({ format: 'tuldok_project_v1', id: require('node:crypto').randomUUID().replace(/-/g, ''), name: 'Annotation check', code_root: '../code' }, null, 2) + '\n'); + fs.copyFileSync(path.join(root, 'examples', 'tiny-project', 'code', 'make_samples.py'), path.join(code, 'make_samples.py')); + execFileSync(python, ['make_samples.py'], { cwd: code, env: { ...process.env, PYTHONDONTWRITEBYTECODE: '1' } }); + // An array of 3 by 4 float32, element (i, j) = i * 10 + j. + { const header = "{'descr': ' JSON.stringify(Object.assign({ format: 'tuldok_definition_v1' }, o), null, 2) + '\n'; + fs.writeFileSync(path.join(folder, 'datasets', 'specimens.json'), doc({ kind: 'dataset', title: 'Specimens of each kind', run: { step: 'import', settings: { source: 'samples', rights: 'Written for this check; free to use.' } } })); + fs.writeFileSync(path.join(folder, 'datasets', 'later.json'), doc({ kind: 'dataset', title: 'Texts, not built', run: { step: 'import', settings: { source: 'samples', pattern: '**/*.txt', rights: 'Written for this check; free to use.' } } })); + fs.writeFileSync(path.join(folder, 'annotations', 'quality.json'), doc({ kind: 'annotation', title: 'Quality', dataset: REF, task: 'class', vocabulary: ['clean', 'noisy'] })); + const old = 'f'.repeat(64), at = '2026-11-13T09:00:00Z'; + fs.writeFileSync(path.join(folder, 'annotations', 'quality.jsonl'), [ + { record: 'texts__gone.txt', sha256: old, state: 'accepted', value: 'clean', by: 'owner', at }, + { record: 'texts__greeting.txt', sha256: old, state: 'accepted', value: 'clean', by: 'owner', at }, + { record: 'texts__weather.txt', sha256: old, state: 'needs-work', value: 'noisy', note: 'is it rain?', by: 'agent:helper', at } + ].map(l => JSON.stringify(l) + '\n').join('')); + const git = ['-c', 'user.name=Tuldok Test', '-c', 'user.email=test@example.invalid', '-c', 'commit.gpgsign=false', '-c', 'init.defaultBranch=main', '-C', repo]; + execFileSync('git', [...git, 'init', '-q']); execFileSync('git', [...git, 'add', '-A']); execFileSync('git', [...git, 'commit', '-q', '-m', 'The fixture.']); + const home = path.join(temporary, 'home'), catalog = path.join(temporary, 'catalog'); fs.mkdirSync(home); + const env = { ...process.env, TULDOK_PROJECT_HOME: home, TULDOK_SETTINGS: path.join(temporary, 'settings.json') }; + owned = [folder, catalog]; dropOwned(folder, catalog); + const cli = (...args) => execFileSync(python, ['-m', 'tuldok_project', ...args], { cwd: root, env, stdio: ['ignore', 'pipe', 'pipe'] }).toString(); + assert.match(cli('check', folder), /^0 errors/m); + cli('build', folder, REF, '--yes'); + let output = ''; + server = launch(python, ['-u', 'app.py', '--port', '0', '--data', catalog, '--project-folder', folder], { cwd: root, env, stdio: ['ignore', 'pipe', 'pipe'] }); + server.stdout.on('data', chunk => { output += chunk; }); server.stderr.on('data', chunk => { serverErrors += chunk; }); + const port = await until(() => { if (server.exitCode !== null) throw Error('Tuldok exited: ' + serverErrors); return output.match(/127\.0\.0\.1:(\d+)/)?.[1]; }, 'Tuldok start-up', 3000); + origin = 'http://127.0.0.1:' + port; + auth = authenticatedFixture(); await auth.register(origin, catalog, root); + const run = (await api('products', { reference: REF })).products[0].run_id; + const listed = (await api('records', { run, limit: 50 })).records; + assert.deepEqual(listed.map(r => r.id).sort(), IDS, 'The import made a record of each file'); + const kinds = Object.fromEntries(listed.map(r => [r.id, r.kind])); + assert.deepEqual([kinds['arrays__grid.npy'], kinds['clouds__ring.ply'], kinds['images__shapes.png'], kinds['meshes__pyramid.obj'], kinds['sounds__two-tones.wav'], kinds['texts__greeting.txt']], ['array', 'pointcloud', 'image', 'mesh', 'audio', 'text']); + const greeting = fs.readFileSync(path.join(code, 'samples', 'texts', 'greeting.txt'), 'utf8'); + + const browser = launch(findBrowser(), ['--headless', '--no-sandbox', '--disable-gpu', '--no-first-run', '--hide-scrollbars', '--autoplay-policy=no-user-gesture-required', '--remote-debugging-port=0', '--window-size=1440,900', '--user-data-dir=' + path.join(temporary, 'browser'), 'about:blank'], { stdio: 'ignore', env: { ...process.env, XDG_CONFIG_HOME: temporary, XDG_CACHE_HOME: temporary } }); + const debugPort = await waitForDebugger(browser, path.join(temporary, 'browser', 'DevToolsActivePort')); + const target = (await (await fetch('http://127.0.0.1:' + debugPort + '/json')).json()).find(item => item.type === 'page'); + socket = new WebSocket(target.webSocketDebuggerUrl); await once(socket, 'open'); + session = cdpSession(socket, { timeoutMs: 60000, onEvent: event => { + network(event); + if (event.method === 'Runtime.exceptionThrown') errors.push(event.params.exceptionDetails.exception?.description || event.params.exceptionDetails.text); + if (event.method === 'Runtime.consoleAPICalled' && event.params.type === 'error') errors.push(event.params.args.map(a => a.value ?? a.description).join(' ')); + if (event.method === 'Log.entryAdded' && event.params.entry.level === 'error' && !/\/api\/project\/set_annotation$/.test(event.params.entry.url || '')) errors.push(event.params.entry.text + ' ' + (event.params.entry.url || '')); + if (event.method === 'Network.loadingFailed' && !event.params.canceled) failures.push({ id: event.params.requestId, error: event.params.errorText }); + if (event.method === 'Network.responseReceived' && event.params.response.status >= 400) failures.push({ url: event.params.response.url, status: event.params.response.status }); // the one refusal asked for is taken out below + } }); + send = session.send; + evaluate = async expression => { const result = await send('Runtime.evaluate', { expression, awaitPromise: true, returnByValue: true }); if (result.exceptionDetails) throw Error(JSON.stringify(result.exceptionDetails)); return result.result.value; }; + await send('Page.enable'); await send('Runtime.enable'); await send('Network.enable'); await send('Log.enable'); + const size = async (width, height) => send('Emulation.setDeviceMetricsOverride', { width, height, deviceScaleFactor: 1, mobile: false }); + const theme = async name => { await send('Emulation.setEmulatedMedia', { features: [{ name: 'prefers-color-scheme', value: name }, { name: 'prefers-reduced-motion', value: 'reduce' }] }); }; + await size(1440, 900); await theme('light'); + await auth.browser(send, origin); // the owner's session + const load = async (name, place) => { + await theme(name); + await send('Page.navigate', { url: 'about:blank' }); await pause(100); + await send('Page.navigate', { url: origin + '/?theme=' + name + '#' + place }); + await until(() => evaluate(`document.readyState === 'complete' && !!document.getElementById('needs-btn') && !document.getElementById('needs-btn').disabled`), 'the project read', 1200); + await settled('opened ' + place); + }; + const pickTask = async ref => { if ((await evaluate(`document.querySelector('[data-key="ann:task"]').value`)) !== ref) { await choose(byKey('ann:task'), ref); await settled('task ' + ref); } }; + const open = async id => { await press(byKey('ann-rec-' + id)); await until(() => evaluate(`(() => { const h = document.querySelector('#main .ann-form h2'); return !!h && h.textContent === ${JSON.stringify(id)}; })()`), 'the form of ' + id); await settled(id); }; + const filter = async id => { await press(byKey('ann:filter-' + id)); await until(() => evaluate(`document.querySelector('[data-key="ann:filter-${id}"]').getAttribute('aria-pressed') === 'true'`), 'filter ' + id); await settled('filter ' + id); }; + const kept = async label => { await until(async () => !(await evaluate(`!!document.querySelector('.act-group [aria-busy]')`)), 'kept: ' + label); await settled(label); }; + await load('light', 'annotate'); + + // ---- 1. Stale annotations, marked and put right ----------------------------------------------------------------- + assert.equal(await evaluate(`[...document.querySelectorAll('#tabs a')].map(a => a.textContent).join(' ')`), 'Map Data Annotate Train Benchmarks Analysis Overview'); + assert.equal(await evaluate(`document.querySelector('[data-key="ann:task"]').value`), 'annotations/quality'); + await filter('stale'); + let t = await tiles(); + assert.deepEqual(t.map(x => [x.id, x.stale]), [['texts__greeting.txt', true], ['texts__weather.txt', true], ['texts__gone.txt', true]], 'The filter Stale lists the three, each marked: ' + JSON.stringify(t)); + await open('texts__greeting.txt'); + assert.match(await form(), /Stale: the record's content differs from what was annotated/); + await shot('light-1440-stale'); + await press(byKey('annotate:form:still')); await kept('still right'); + await filter('all'); + t = await tiles(); const greet = t.find(x => x.id === 'texts__greeting.txt'); + assert.deepEqual([greet.stale, greet.unsaved, greet.state], [false, true, 'accepted'], 'Still right: no longer stale, unsaved'); + assert.equal((await api('annotation', { task: 'quality', record: 'texts__greeting.txt' })).stale, false); + await open('texts__gone.txt'); + assert.match(await form(), /Stale: the record is gone from the current product of datasets\/specimens/); + await press(byKey('annotate:form:remove')); await press(byKey('annotate:form:remove:confirm')); await kept('removed'); + assert.equal((await api('annotation', { task: 'quality', record: 'texts__gone.txt' })).annotation, null, 'The annotation of the record that is gone was removed'); + check('1. The filter Stale listed the three stale annotations, each marked; Still right put texts__greeting.txt right (now unsaved, not stale) and the one whose record is gone was removed'); + + // ---- 2. A task of each kind made from the page, one record annotated with each --------------------------------- + const TASKS = [ + { name: 'looked-at', title: 'Looked at', type: 'review', record: 'meshes__pyramid.obj' }, + { name: 'shape-kind', title: 'Shape kind', type: 'class', vocab: ['round', 'angular', 'flat'], record: 'clouds__ring.ply' }, + { name: 'scene-tags', title: 'Scene tags', type: 'tags', vocab: ['blue', 'orange', 'small', 'large'], record: 'images__shapes.png' }, + { name: 'captions', title: 'Captions', type: 'text', record: 'arrays__grid.npy' }, + { name: 'shapes', title: 'Shapes', type: 'boxes', vocab: ['blue', 'orange'], record: 'images__shapes.png' }, + { name: 'names', title: 'Names', type: 'spans', vocab: ['PER', 'PLACE', 'DATE'], record: 'texts__greeting.txt' }, + { name: 'tones', title: 'Tones', type: 'segments', vocab: ['tone', 'silence'], record: 'sounds__two-tones.wav' } + ]; + const drawn = {}; + for (const task of TASKS) { + await press(byKey('annotate:new:new')); + await until(() => evaluate(`!!document.querySelector('#aside [data-key="newtask:field:title"]')`), 'the New task form'); + await type(byKey('newtask:field:title'), task.title); + assert.equal(await evaluate(`document.querySelector('[data-key="newtask:field:name"]').value`), task.name, 'The name is made from the title'); + await choose(byKey('newtask:field:dataset'), REF); + await choose(byKey('newtask:field:task'), task.type); + assert.equal(await evaluate(`document.querySelector('[data-key="newtask:field:vocabulary"]').closest('label').hidden`), !task.vocab, 'The vocabulary is asked only of the tasks that have one'); + if (task.vocab) { await type(byKey('newtask:field:vocabulary'), task.vocab.join('\n')); } + if (task.type === 'segments') await shot('light-1440-new-task'); + await press(byKey('newtask:keep')); await kept('kept ' + task.name); + await until(() => evaluate(`!document.getElementById('drawer').classList.contains('open') && document.querySelector('[data-key="ann:task"]').value === 'annotations/${task.name}'`), 'the new task chosen: ' + task.name); + await settled(task.name); + const def = await api('definition', { reference: 'annotations/' + task.name }); + assert.equal(def.unsaved, true); + assert.equal(def.text, JSON.stringify(Object.assign({ format: 'tuldok_definition_v1', kind: 'annotation', title: task.title, dataset: REF, task: task.type }, task.vocab ? { vocabulary: task.vocab } : {}), null, 2) + '\n', 'The definition text of ' + task.name); + await open(task.record); + if (task.type === 'review') { + // The arrows move without keeping anything. + await press('#main .ann-form h2'); await key('ArrowRight'); + await until(async () => ((await tiles()).find(x => x.pressed) || {}).id === 'sounds__two-tones.wav', 'the right arrow moved on'); await settled('moved'); + await key('ArrowLeft'); await until(async () => ((await tiles()).find(x => x.pressed) || {}).id === task.record, 'the left arrow moved back'); await settled('moved back'); + await press(byKey('ann:decide-accepted')); await key('Enter'); + } + if (task.type === 'class') { + // Accepted without a term is refused: the server's sentence beside the form, the decision still chosen. + await press(byKey('ann:decide-accepted')); await key('Enter'); await kept('refused'); + const refusal = await evaluate(`(() => { const r = document.querySelector('#main .ann-form .refusal'); return r ? r.innerText : null; })()`); + assert.match(refusal || '', /cannot be kept; nothing was changed/, 'The refusal is shown beside the form: ' + refusal); + assert.equal(await evaluate(`document.querySelector('[data-key="ann:decide-accepted"]').getAttribute('aria-pressed')`), 'true', 'Nothing chosen is lost'); + refused.push(refusal.split('\n')[0]); + await press(byKey('ann:decide-accepted')); + await press('#main .ann-form h2'); await key('2'); await key('1'); assert.equal(await evaluate(`document.querySelector('[data-key="ann:term-0"]').checked`), true, 'Key 1 chose the first term'); await key('Enter'); } + if (task.type === 'tags') { await press('#main .ann-form h2'); for (const k of ['1', '2', '3', '3']) await key(k); await press(byKey('ann:decide-needs-work')); await key('Enter'); } + if (task.type === 'text') { await type(byKey('ann:text'), 'A grid of values that rise by ten a row.'); await press(byKey('ann:decide-accepted')); await press(byKey('annotate:form:keep')); } + if (task.type === 'boxes') { + // Pixels (6, 8) to (28, 26) of the 64 by 48 image, wherever it is drawn; then two to the right and one taller by keys. + const g = await evaluate(`(() => { const c = document.querySelector('#main .ann-view canvas.ann-surface'); c.scrollIntoView({ block: 'center' }); const r = c.getBoundingClientRect(); return { left: r.left, top: r.top, width: r.width, height: r.height, image: c.parentElement.dataset.image }; })()`); + assert.equal(g.image, '64x48'); + const px = (x, y) => ({ x: g.left + x * g.width / 64, y: g.top + y * g.height / 48 }); + await dragFrom(px(6, 8), px(28, 26)); + await key('ArrowRight'); await key('ArrowRight'); await key('ArrowDown', 8); + drawn.box = await evaluate(`document.querySelector('#main .ann-items li .ann-coords').textContent`); + assert.equal(drawn.box, 'x 8, y 8 · 22 × 19', 'The box drawn and moved, in pixels of the image'); + await shot('light-1440-boxes-drawn'); + await press(byKey('ann:decide-accepted')); await key('Enter'); + } + if (task.type === 'spans') { + await choose(byKey('ann:new-term'), 'DATE'); + const u = greeting.indexOf('1843'); + const r = await evaluate(`(() => { const pre = document.querySelector('#main .ann-text'); pre.scrollIntoView({ block: 'center' }); const node = [...pre.childNodes].find(n => n.nodeType === 3); const range = document.createRange(); range.setStart(node, ${u}); range.setEnd(node, ${u + 4}); const q = range.getClientRects()[0]; return { left: q.left, right: q.right, y: q.top + q.height / 2 }; })()`); + await dragFrom({ x: r.left + 1, y: r.y }, { x: r.right - 1, y: r.y }); + drawn.span = await evaluate(`[...document.querySelectorAll('#main .ann-items li')].map(li => ({ start: Number(li.querySelector('[data-key$="-start"]').value), end: Number(li.querySelector('[data-key$="-end"]').value), term: li.querySelector('select').value, covered: li.querySelector('.ann-covered').textContent }))`); + assert.equal(drawn.span.length, 1); assert.equal(drawn.span[0].covered, '1843'); assert.equal(drawn.span[0].term, 'DATE'); + assert.equal(await evaluate(`document.querySelector('#main .ann-text mark.ann-span').textContent`), '1843', 'The span is shown in the text'); + await shot('light-1440-spans-marked'); + await press(byKey('ann:decide-accepted')); await key('Enter'); + } + if (task.type === 'segments') { + const g = await evaluate(`(() => { const c = document.querySelector('#main .ann-view canvas.ann-surface'); c.scrollIntoView({ block: 'center' }); const r = c.getBoundingClientRect(); return { left: r.left, width: r.width, y: r.top + r.height / 2 }; })()`); + const sx = s => g.left + s / 1.2 * g.width; + await dragFrom({ x: sx(0.2), y: g.y }, { x: sx(0.55), y: g.y }); + await key('ArrowRight', 8); + await type(byKey('ann:item-0-text'), 'the first tone'); + await evaluate(`(() => { document.querySelector('#main .ann-view audio').muted = true; return true; })()`); // the headless browser has no sound to play to + await press(byKey('ann:item-0-play')); + const played = await until(() => evaluate(`(() => { const a = document.querySelector('#main .ann-view audio'); return a.currentTime > 0.21 ? a.currentTime : null; })()`), 'the stretch plays', 60); + await until(() => evaluate(`document.querySelector('#main .ann-view audio').paused`), 'the stretch stops at its end', 60); + const stoppedAt = await evaluate(`document.querySelector('#main .ann-view audio').currentTime`); + drawn.segment = await evaluate(`(() => { const li = document.querySelector('#main .ann-items li'); return { start: Number(li.querySelector('[data-key$="-start"]').value), end: Number(li.querySelector('[data-key$="-end"]').value), term: li.querySelector('select').value }; })()`); + assert.ok(Math.abs(drawn.segment.start - 0.2) <= 0.01 && Math.abs(drawn.segment.end - 0.6) <= 0.01, 'The segment dragged and lengthened by a key: ' + JSON.stringify(drawn.segment)); + assert.ok(stoppedAt >= drawn.segment.end - 0.05 && stoppedAt <= drawn.segment.end + 0.3, 'The stretch stopped at its end: ' + stoppedAt); + drawn.played = played; + await shot('light-1440-segments-marked'); + await press(byKey('ann:decide-accepted')); await press(byKey('annotate:form:keep')); + } + await kept('annotated ' + task.name); + const got = await api('annotation', { task: task.name, record: task.record }); + assert.ok(got.annotation && got.unsaved, 'Kept and unsaved: ' + task.name + ' ' + JSON.stringify(got)); + task.line = got.annotation; + } + check('2. Seven tasks made with New task (review, class, tags, text, boxes, spans, segments), each kept as the definition expected, and one record annotated with each: class and tags by the keys, boxes by dragging on the image and the arrows (' + drawn.box + '), spans by selecting "1843" after the 🌍, segments by dragging on the waveform and Shift with an arrow (' + drawn.segment.start + ' to ' + drawn.segment.end + ' s, played from ' + drawn.played.toFixed(2) + ' s)'); + + // ---- 3. The strip, Save, the files, a reload, the filter ------------------------------------------------------ + const status = await api('status'); + assert.equal(status.unsaved.length, 7); assert.equal(status.annotations_unsaved.reduce((n, x) => n + x.records, 0), 9); + assert.match(await stripText(), /7 definitions, 9 annotations unsaved/, 'The strip counts both'); + await press(byKey('save:save')); await kept('saved'); + await until(async () => !/unsaved/.test(await stripText()), 'the strip without unsaved'); + const after = await api('status'); assert.deepEqual([after.unsaved, after.annotations_unsaved], [[], []]); + const expected = { + 'looked-at': { state: 'accepted', value: null }, 'shape-kind': { state: 'draft', value: 'round' }, 'scene-tags': { state: 'needs-work', value: ['blue', 'orange'] }, + captions: { state: 'accepted', value: 'A grid of values that rise by ten a row.' }, shapes: { state: 'accepted', value: [{ term: 'blue', x: 8, y: 8, w: 22, h: 19 }] } + }; + const cps = Array.from(greeting), start = cps.indexOf('1'); + assert.ok(cps.length < greeting.length, 'The greeting holds an astral character before the span'); + expected.names = { state: 'accepted', value: [{ term: 'DATE', start, end: start + 4 }] }; + expected.tones = { state: 'accepted', value: [{ term: 'tone', start: drawn.segment.start, end: drawn.segment.end, text: 'the first tone' }] }; + for (const task of TASKS) { + const file = lines(task.name); + assert.equal(file.length, 1, task.name + ' has one line'); + const line = file[0]; + assert.deepEqual(Object.keys(line), ['record', 'sha256', 'state', 'value', 'by', 'at'], 'The keys of a line, in order'); + assert.deepEqual({ record: line.record, state: line.state, value: line.value, by: line.by }, Object.assign({ record: task.record, by: 'owner' }, expected[task.name]), 'The line of ' + task.name); + assert.equal(line.sha256, listed.find(r => r.id === task.record).sha256, 'The line carries the record\'s hash'); + } + assert.equal(cps.slice(lines('names')[0].value[0].start, lines('names')[0].value[0].end).join(''), '1843', 'The span\'s offsets, in code points, cover 1843'); + assert.deepEqual(lines('quality').map(l => [l.record, l.state, l.sha256 === old]), [['texts__greeting.txt', 'accepted', false], ['texts__weather.txt', 'needs-work', true]], 'quality: put right, left stale, the gone one removed'); + check('3. The strip read "7 definitions, 9 annotations unsaved"; Save wrote each task\'s file with exactly the line expected (the box at 8, 8, 22 by 19 pixels; the span ' + start + ' to ' + (start + 4) + ' covering "1843"; the segment ' + drawn.segment.start + ' to ' + drawn.segment.end + ' s), and the count is gone'); + await load('light', 'annotate'); + for (const task of TASKS) { + await pickTask('annotations/' + task.name); + const tile = (await tiles()).find(x => x.id === task.record); + assert.equal(tile.state, expected[task.name].state, 'After a reload the tile of ' + task.name + ' shows its state'); + await open(task.record); + const text = await form(); + if (task.type === 'boxes') assert.match(text, /x 8, y 8 · 22 × 19/); + if (task.type === 'spans') assert.match(text, /1843/); + if (task.type === 'class') assert.equal(await evaluate(`document.querySelector('[data-key="ann:term-0"]').checked`), true); + if (task.type === 'tags') assert.deepEqual(await evaluate(`[0, 1, 2, 3].map(i => document.querySelector('[data-key="ann:term-' + i + '"]').checked)`), [true, true, false, false]); + if (task.type === 'text') assert.equal(await evaluate(`document.querySelector('[data-key="ann:text"]').value`), expected.captions.value); + if (task.type === 'segments') assert.equal(await evaluate(`document.querySelector('[data-key="ann:item-0-text"]').value`), 'the first tone'); + } + await pickTask('annotations/captions'); + await filter('accepted'); assert.deepEqual((await tiles()).map(x => x.id), ['arrays__grid.npy'], 'Accepted lists the one accepted'); + await filter('todo'); assert.equal((await tiles()).length, 6, 'To do lists the six others'); + await filter('rejected'); assert.equal((await tiles()).length, 0); + await filter('all'); assert.equal((await tiles()).length, 7); + check('3. After a reload each task shows its annotation (tile state and form); the filter lists 1 accepted, 6 to do, 0 rejected, 7 in all'); + + // ---- 4. Typed and not kept: nothing is touched; a second session's annotation reaches the grid ------------------- + await open('texts__weather.txt'); + await press(byKey('ann:text')); + await send('Input.insertText', { text: 'Rain over Manila' }); + await evaluate(`(() => { const e = document.activeElement; e.setSelectionRange(4, 4); return true; })()`); + const typed = () => evaluate(`({ key: document.activeElement.dataset.key, value: document.activeElement.value, caret: document.activeElement.selectionStart })`); + const before = await typed(); + assert.deepEqual(before, { key: 'ann:text', value: 'Rain over Manila', caret: 4 }); + await evaluate(WATCHER); await evaluate(`window.__still.start()`); + let since = Date.now(); await evaluate(`window.dispatchEvent(new Event('focus')); true`); await reading(since, WATCHED.concat(['map']), 'focus'); + since = Date.now(); await reading(since, WATCHED, 'the timer', Math.round((IDLE_MS + 8000) / 100)); + const r4 = await evaluate(`window.__still.stop()`); + for (const id of ['tabs', 'main', 'aside']) assert.deepEqual([r4.counts[id].added, r4.counts[id].removed, r4.counts[id].attrs, r4.counts[id].text, r4.fresh[id]], [0, 0, 0, 0, 0], id + ' untouched: ' + JSON.stringify(r4.counts[id])); + assert.equal(r4.flash, 0); + assert.deepEqual(await typed(), before, 'The typed text, the focus and the caret stay'); + check('4. With "' + before.value + '" typed and not kept (caret at 4), the window regaining focus and a reading on the timer added, removed and changed no node; the text, focus and caret are there'); + const agent = await credential('An annotating agent', ['inspect', 'edit']); + await api('set_annotation', { task: 'captions', items: [{ record: 'clouds__ring.ply', state: 'accepted', value: 'A ring of points.' }] }, agent); + assert.equal(lines('captions').length, 1); + await evaluate(`window.__still.start()`); + since = Date.now(); await evaluate(`window.dispatchEvent(new Event('focus')); true`); await reading(since, WATCHED.concat(['map']), 'focus after the agent'); + await until(async () => ((await tiles()).find(x => x.id === 'clouds__ring.ply') || {}).state === 'accepted', 'the agent\'s annotation in the grid'); + const r5 = await evaluate(`window.__still.stop()`); + assert.ok(r5.counts.main.added > 0, 'The grid was drawn again'); + assert.deepEqual([r5.counts.form.added, r5.counts.form.removed, r5.counts.form.attrs, r5.counts.form.text], [0, 0, 0, 0], 'The form was not touched: ' + JSON.stringify(r5.counts.form)); + assert.deepEqual(await typed(), before, 'The typed text, the focus and the caret stay'); + const ring = (await tiles()).find(x => x.id === 'clouds__ring.ply'); assert.equal(ring.unsaved, true); + assert.equal((await api('annotation', { task: 'captions', record: 'clouds__ring.ply' })).annotation.by, 'agent:An annotating agent'); + check('4. A second session (an agent allowed to edit) annotated clouds__ring.ply: the grid shows it accepted and unsaved after one reading, the form was not touched and the typed text is there'); + // Revert from the page: the agent's annotation goes; the typed text of the record left stays in this page. + await open('clouds__ring.ply'); + await press(byKey('annotate:form:revert')); await press(byKey('annotate:form:revert:confirm')); await kept('reverted'); + assert.equal((await api('annotation', { task: 'captions', record: 'clouds__ring.ply' })).annotation, null, 'Reverted: no annotation'); + assert.equal(((await tiles()).find(x => x.id === 'clouds__ring.ply') || {}).state, 'none'); + await open('texts__weather.txt'); + assert.equal(await evaluate(`document.querySelector('[data-key="ann:text"]').value`), 'Rain over Manila', 'The typed text of the record left is there when it is chosen again'); + check('4. Revert on the page put back clouds__ring.ply (no annotation again); the text typed on texts__weather.txt was there on coming back to it'); + + // ---- 5. A task on a dataset with no product ------------------------------------------------------------------------ + await load('light', 'annotate'); + await press(byKey('annotate:new:new')); + await until(() => evaluate(`!!document.querySelector('#aside [data-key="newtask:field:title"]')`), 'the New task form'); + await type(byKey('newtask:field:title'), 'Later review'); await choose(byKey('newtask:field:dataset'), 'datasets/later'); await choose(byKey('newtask:field:task'), 'review'); + await press(byKey('newtask:keep')); await kept('later review'); + await until(() => evaluate(`/datasets\\/later has no product on this machine/.test(document.getElementById('main').innerText)`), 'no product'); + await press(byKey('annotate:plan:plan')); + await until(() => evaluate(`location.hash === '#train/' + encodeURIComponent('plan:datasets/later')`), 'the plan of datasets/later'); + await settled('plan of later'); + assert.match(await evaluate(`document.getElementById('aside').innerText`), /datasets\/later/); + check('5. A task on datasets/later, which has no product, says so and its "Plan a build" opens the plan of datasets/later'); + + // ---- 6. Import and Freeze on the Data tab --------------------------------------------------------------------------- + await hash('data'); + await press(byKey('data:new:import')); + await until(() => evaluate(`!!document.querySelector('#aside [data-key="newimport:field:title"]')`), 'the Import form'); + await type(byKey('newimport:field:title'), 'Notes only'); + await type(byKey('newimport:field:source'), 'samples'); await type(byKey('newimport:field:pattern'), '**/*.txt'); + await type(byKey('newimport:field:rights'), 'Written for this check.'); await press(byKey('newimport:field:lines')); + await shot('light-1440-import'); + await press(byKey('newimport:keep')); await kept('import kept'); + await until(() => evaluate(`location.hash === '#data/' + encodeURIComponent('datasets/notes-only')`), 'the new dataset\'s drawer'); + await press(byKey('data:new:freeze')); + await until(() => evaluate(`!!document.querySelector('#aside [data-key="newfreeze:field:title"]')`), 'the Freeze form'); + await type(byKey('newfreeze:field:title'), 'Specimens v1'); + await choose(byKey('newfreeze:field:dataset'), REF); await settled('freeze dataset'); + const boxes = await evaluate(`[...document.querySelectorAll('#aside [data-key^="newfreeze:field:task-"]')].map(c => [c.dataset.key.slice(21), c.checked])`); + assert.deepEqual(boxes.map(b => b[0]), ['annotations/captions', 'annotations/looked-at', 'annotations/names', 'annotations/quality', 'annotations/scene-tags', 'annotations/shape-kind', 'annotations/shapes', 'annotations/tones'], 'The tasks on specimens'); + await press(byKey('newfreeze:field:task-annotations/captions')); // off: the first task is then looked-at + await press(byKey('newfreeze:field:task-annotations/looked-at')); await press(byKey('newfreeze:field:task-annotations/shapes')); + await type(byKey('newfreeze:field:seed'), '3'); await type(byKey('newfreeze:field:shares'), 'train 2, test 1'); + await press(byKey('newfreeze:field:include-needs-work')); + await shot('light-1440-freeze'); + await press(byKey('newfreeze:keep')); await kept('freeze kept'); + await until(() => evaluate(`location.hash === '#data/' + encodeURIComponent('datasets/specimens-v1')`), 'the frozen dataset\'s drawer'); + await settled('frozen drawer'); + await press(byKey('dataedit:datasets/specimens-v1:plan')); + await until(() => evaluate(`location.hash === '#train/' + encodeURIComponent('plan:datasets/specimens-v1')`), 'the plan of the freeze'); await settled('plan of the freeze'); + const plan = await evaluate(`document.getElementById('aside').innerText`); + assert.match(plan, /A build of datasets\/specimens-v1/); assert.match(plan, /1 step to build/); + const planned = await api('plan', { targets: ['datasets/specimens-v1'] }); + assert.deepEqual(planned.steps.filter(s => s.action === 'build').map(s => [s.reference, s.step]), [['datasets/specimens-v1', 'freeze']], 'The freeze is planned'); + await hash('data'); await press(byKey('save:save')); await kept('saved the datasets'); + const want = { + 'notes-only': { format: 'tuldok_definition_v1', kind: 'dataset', title: 'Notes only', run: { step: 'import', settings: { source: 'samples', pattern: '**/*.txt', rights: 'Written for this check.', lines: true } } }, + 'specimens-v1': { format: 'tuldok_definition_v1', kind: 'dataset', title: 'Specimens v1', run: { step: 'freeze', inputs: { records: REF }, annotations: ['annotations/looked-at', 'annotations/shapes'], settings: { seed: 3, shares: { train: 2, test: 1 }, include: ['accepted', 'needs-work'] } } } + }; + for (const [name, d] of Object.entries(want)) assert.equal(fs.readFileSync(path.join(folder, 'datasets', name + '.json'), 'utf8'), JSON.stringify(d, null, 2) + '\n', 'The definition written for ' + name); + const checked = cli('check', folder); + assert.match(checked, /^0 errors/m, checked); + check('6. Import and Freeze kept datasets/notes-only and datasets/specimens-v1, written by Save exactly as expected; `check` reports ' + checked.trim().split('\n').pop().replace(/ in .*/, '') + '; the freeze was planned from its drawer (1 step to build: tuldok freeze)'); + + // ---- 7. Screenshots in both themes at two sizes; nothing overflows sideways -------------------------------------- + const seen = []; + const over = async label => { const o = await evaluate(`(() => { const m = document.getElementById('main'), a = document.getElementById('drawer'); return { page: document.documentElement.scrollWidth - innerWidth, main: m.scrollWidth - m.clientWidth, drawer: a.scrollWidth - a.clientWidth }; })()`); assert.ok(o.page <= 0 && o.main <= 1 && o.drawer <= 1, label + ': sideways overflow ' + JSON.stringify(o)); }; + for (const [w, hgt] of [[1440, 900], [1000, 800]]) for (const name of ['light', 'dark']) { + await size(w, hgt); await load(name, 'annotate'); + const tag = name + '-' + w; + for (const task of TASKS.concat([{ name: 'quality', record: 'texts__weather.txt', type: 'stale' }])) { + await pickTask('annotations/' + task.name); await open(task.record); + await evaluate(`(() => { document.getElementById('main').scrollTop = 0; return true; })()`); + if (task.type === 'boxes') { await press('#main canvas.ann-surface'); await key(']'); } // a box chosen, its handles drawn + await over(tag + ' ' + task.type); await shot(tag + '-' + task.type); seen.push(tag + ' ' + task.type); + if (['spans', 'segments', 'boxes'].includes(task.type) && w === 1000) { await evaluate(`(() => { document.querySelector('#main .ann-form').scrollIntoView({ block: 'start' }); return true; })()`); await shot(tag + '-' + task.type + '-form'); } + } + await press(byKey('annotate:new:new')); await until(() => evaluate(`!!document.querySelector('#aside [data-key="newtask:field:title"]')`), 'the New task form'); + await type(byKey('newtask:field:title'), 'Mood of each sound'); await type(byKey('newtask:field:vocabulary'), 'calm\nlively'); + await over(tag + ' new task'); await shot(tag + '-new-task'); + await hash('data'); await press(byKey('data:new:import')); await until(() => evaluate(`!!document.querySelector('#aside [data-key="newimport:field:title"]')`), 'the Import form'); await settled('import'); + await over(tag + ' import'); await shot(tag + '-import'); + await press(byKey('data:new:freeze')); await until(() => evaluate(`!!document.querySelector('#aside [data-key="newfreeze:field:title"]')`), 'the Freeze form'); await settled('freeze'); + await over(tag + ' freeze'); await shot(tag + '-freeze'); + } + await size(1440, 900); + check('7. Nothing overflows sideways in light and dark at 1440 × 900 and 1000 × 800 (' + seen.length + ' views of the forms, and New task, Import and Freeze)' + (shots ? '; screenshots in ' + shots : '')); + + // ---- Nothing failed --------------------------------------------------------------------------------------------------- + assert.deepEqual(errors, [], 'Script errors'); + const asked = failures.filter(f => f.url && /\/api\/project\/set_annotation$/.test(f.url)); + assert.equal(asked.length, 1, 'The one refusal asked for: ' + JSON.stringify(failures)); + assert.deepEqual(failures.filter(f => !asked.includes(f)), [], 'Failed requests'); + check('No script error, no failed request but the refusal of set_annotation asked for ("' + refused[0] + '")'); + fs.writeFileSync(path.join(report, 'receipt.json'), JSON.stringify({ status: 'pass', folder, checks }, null, 2) + '\n'); + console.log('Receipt in ' + report); +})().catch(async error => { + process.exitCode = 1; + console.error(error); if (serverErrors) console.error('Server:', serverErrors.slice(-4000)); + console.error('Script errors:', JSON.stringify(errors)); console.error('Failed requests:', JSON.stringify(failures)); + try { if (evaluate) { await shot('failure'); console.error('Page:', (await evaluate('document.body.innerText')).slice(0, 3000)); } } catch (_) { /* the page is gone */ } + fs.writeFileSync(path.join(report, 'failure.json'), JSON.stringify({ status: 'failed', error: String(error && error.stack || error), checks, errors, failures }, null, 2) + '\n'); +}).finally(async () => { + try { session?.close(); } catch (_) { /* closed */ } + for (const child of children.reverse()) await stop(child); + if (owned) try { dropOwned(...owned); } catch (error) { console.error('Dropping the disposable schemas failed:', error.message); process.exitCode = 1; } + try { execFileSync('chmod', ['-R', 'u+w', temporary]); } catch (_) { /* nothing was made read-only */ } + fs.rmSync(temporary, { recursive: true, force: true }); +}); From f6231508e1f6a36cf814091d9c89e985fc472efe Mon Sep 17 00:00:00 2001 From: MrScripty Date: Fri, 13 Nov 2026 18:06:09 -0700 Subject: [PATCH 075/131] feat(project): generate datasets and suggest annotations through a Pumas endpoint The address of the Pumas endpoint is a setting of the machine, never in the Git folder or a definition. endpoint says what it serves now; set_endpoint (owner) sets or clears it after asking it once; find_endpoints (owner) lists those advertising themselves here. The address must be a numeric loopback HTTP address, as Pumas 0.8.0 serves. A dataset's run may name the step generate: a model and what to make (text or image), a prompt with the item's number, a count or a dataset of prompts, a seed, the capability's options within the bounds the endpoint advertises. It runs as an ordinary build, checks what the endpoint serves before asking anything, retries a request refused before admission twice, and writes each record with its hash, rights and what generated it. With no endpoint set a plan says the step is blocked. The run's record keeps the address and the endpoint's version. suggest_annotation asks a served model for a value of a task for one record and stores nothing; suggestion_models lists the models that fit a task's records. Captions through image_to_text, transcripts through audio_transcription, summaries through chat, classes and tags through decision or a constrained answer. An answer that is not a value of the task is a refusal with the model's words. Tuldok hard-codes no capability: every offer comes from what the endpoint serves at that moment. Everything is checked against a fake endpoint; no running Pumas was contacted. Co-Authored-By: Claude Fable 5.2 --- docs/contracts/project-folder.md | 161 +++- .../definition-first-projects/spec-d5.md | 43 + pumas_operations.py | 9 +- tests/fake_pumas_typed.py | 20 +- tests/test_tuldok_project_pumas.py | 875 ++++++++++++++++++ tests/test_tuldok_project_service.py | 18 +- tuldok_project/annotation_records.py | 24 + tuldok_project/builds.py | 63 +- tuldok_project/check.py | 94 +- tuldok_project/local.py | 74 +- tuldok_project/operations.py | 28 +- tuldok_project/plan.py | 37 +- tuldok_project/pumas.py | 516 +++++++++++ tuldok_project/schemas/benchmark.schema.json | 5 +- tuldok_project/schemas/dataset.schema.json | 5 +- tuldok_project/schemas/recipe.schema.json | 5 +- tuldok_project/schemas/step.schema.json | 5 +- tuldok_project/service.py | 144 ++- tuldok_project/steps.py | 208 ++++- 19 files changed, 2258 insertions(+), 76 deletions(-) create mode 100644 tests/test_tuldok_project_pumas.py create mode 100644 tuldok_project/pumas.py diff --git a/docs/contracts/project-folder.md b/docs/contracts/project-folder.md index 342af558..d32e3a9e 100644 --- a/docs/contracts/project-folder.md +++ b/docs/contracts/project-folder.md @@ -191,7 +191,7 @@ object. It is required unless `earlier_work.rebuild` is `no`. | Field | Required | Rule | | --- | --- | --- | | `command` | unless `step` is given | 1 to 64 strings, the program and its arguments; run in the code root. When the first string is exactly `python` it means the environment's interpreter | -| `step` | no | datasets only: `import` or `freeze`, a step Tuldok provides in place of a command; see [Steps Tuldok provides](#steps-tuldok-provides) | +| `step` | no | datasets only: `import`, `freeze` or `generate`, a step Tuldok provides in place of a command; see [Steps Tuldok provides](#steps-tuldok-provides) | | `environment` | when the first string of `command` is `python` | reference to `environments/` | | `inputs` | no | at most 32 entries; keys `^[a-z][a-z0-9_]{0,31}$`; values are inputs from `datasets/`, `recipes/` or `steps/` | | `settings` | no | object, free content, written to a file whose path replaces `{settings}`; not together with `settings_file` | @@ -263,13 +263,13 @@ Example, `datasets/sinusoidal-v1.json`: #### Steps Tuldok provides -A dataset's `run` names either a `command` or a `step`, one of `import` and -`freeze`. A run with `step` has no `command`, `environment`, `outputs`, +A dataset's `run` names either a `command` or a `step`, one of `import`, +`freeze` and `generate`. A run with `step` has no `command`, `environment`, `outputs`, `settings_file`, `env` or `estimate`: the step's outputs are fixed, its settings are inline in `settings`, and it runs with Tuldok's own interpreter (see [The command and its environment](#the-command-and-its-environment)). -It may have `resources` and `sources`. A plan shows it as `tuldok import` or -`tuldok freeze`. It is planned, requested, approved, run, cancelled and +It may have `resources` and `sources`. A plan shows it as `tuldok import`, +`tuldok freeze` or `tuldok generate`. It is planned, requested, approved, run, cancelled and recorded like any build, from a commit as builds are. `check` reports a setting the step does not take, a required one missing and a value of the wrong form. @@ -378,6 +378,72 @@ Example, `datasets/scene-photos.json` and `datasets/scene-photos-v1.json`: } ``` +**`generate`** makes a dataset by asking a model that the machine's Pumas +endpoint serves (see [The Pumas endpoint](#the-pumas-endpoint)): one request +per item, over HTTP, the endpoint's address given by the build and never +written in the folder. Its run takes no input, or one, `"inputs": {"prompts": +"datasets/"}`, and no `annotations`. Settings: + +| Setting | Required | Rule | +| --- | --- | --- | +| `make` | yes | `text` or `image` | +| `model` | yes | the served model's alias: 1 to 256 bytes, no control characters, no spaces around it | +| `profile` | no | the profile it is served with, 1 to 128 of `A-Z a-z 0-9 . _ -`; needed when the endpoint serves the model with more than one | +| `prompt` | yes | 1 to 16,000 characters: the request, with `{n}` (the item's number from 1) and, with an input, `{text}` (the prompting record's text); `{{` and `}}` are literal braces | +| `count` | without an input | how many to make, 1 to 100,000; not with an input | +| `per` | no | with an input only: how many for each of its text records, 1 to 1,000, default 1 | +| `seed` | no | 0 to 4,294,967,295; item `n` is asked with `seed + n − 1` when the capability takes a seed (it advertises a `seed` bound and its options kind has one: `image_generation`) | +| `options` | no | at most 32 options of the capability, numbers: `max_tokens`, `temperature`, `top_p` for text, `width` and `height` (both required) for images; each must be advertised with a bound by the endpoint and within it, and `seed` is not one | +| `rights` | yes | 1 to 1,000 characters: what may be done with what is made | + +Before anything is asked the step reads what the endpoint serves +(`GET /v1/served-models`) and fails, saying why, when the model or profile is +not served, no capability of it is available to make the output (`text`, or +`png_base64` for an image) from a text, an option is not one the capability +takes or is outside its advertised bounds, or a prompt (`input_characters`) or +a seed is. The capability is the first of the model's available ones that +makes the output, in the endpoint's order. A request refused before the +provider took it (outcome `not_admitted`) is asked again after 1 s and after 2 +s more; a third refusal, or any other failure, fails the step with the item's +number and the endpoint's reason. What was made stays in the failed run's +directory and is no product. With an input, one request is made for each text +record of its product (inline, or a UTF-8 file of at most 64 KiB) times `per`, +in the product's order; records of other kinds are skipped and counted. An +input shown through a `view` is refused. + +Its product holds `records.jsonl` and, for images and texts too long for one +line, the files under `files/`: + +``` +{"id":"g000001","kind":"text","text":"Waves fold over.","sha256":"…","bytes":16,"rights":"…","origin":{"generated":{"model":"writer","profile":"writer-cpu","capability":"chat_generation","prompt":"Write line 1 of a short poem.","seed":null,"options":{"max_tokens":64},"input":null}}} +{"id":"g000001","kind":"image","path":"files/g000001.png","sha256":"…","bytes":5120,"rights":"…","origin":{"generated":{"model":"painter","profile":"painter-gpu","capability":"image_generation","prompt":"A picture of a red ball, number 1.","seed":100,"options":{"width":64,"height":32},"input":"subjects.txt__1"}}} +``` + +`seed` is the seed the item was made with (for an image, the one the endpoint +reports), null when the capability took none; `input` is the prompting +record's id, or null. A generated dataset is built again only when its +definition or its input changes; a model need not give the same content +again, and annotations that no longer fit are then stale. Its run keeps the +endpoint's address and reported version (`endpoint` of `run`; see +[The run directory](#the-run-directory)); +on a machine with no endpoint set, a plan shows it `blocked`. + +Example, `datasets/poem-lines.json`: + +```json +{ + "format": "tuldok_definition_v1", + "kind": "dataset", + "title": "Poem lines", + "run": { + "step": "generate", + "settings": {"make": "text", "model": "writer", "prompt": "Write line {n} of a short poem.", "count": 3, + "seed": 5, "options": {"max_tokens": 64, "temperature": 0.7}, + "rights": "Made by a model; anything may be done with it."} + } +} +``` + ### `model` A model is an architecture. It produces nothing by itself; recipes train it. @@ -1218,7 +1284,7 @@ reference), numbered from 1. Each step has one action: | `ready` | an environment in state `ready`; it is not counted as something to set up | | `build` | a dataset, recipe, step or benchmark in state `not-built`, `out-of-date`, `failed` or `running` (the text says why under the step; `build` refuses a step that is running) | | `built` | a dataset, recipe, step or benchmark in state `built`; it is not counted as work | -| `blocked` | a definition in state `cannot-rebuild` or `needs-work`, and a benchmark with no subject to run | +| `blocked` | a definition in state `cannot-rebuild` or `needs-work`, a benchmark with no subject to run, and a `generate` dataset to be built on a machine with no Pumas endpoint set | A blocked step is explained by its causes: the definitions whose own `earlier_work.rebuild` is `no` or `needs-work`, among the step itself and @@ -1233,6 +1299,11 @@ skipped, with the reason; a subject with no recipe is run. The benchmark is its subjects is; when no subject would run, it is `blocked` with no cause of its own. +A `generate` held by the missing endpoint is its own cause, with `rebuild` +`endpoint` and the reason; it is listed among `blocked_targets` whether it is +a target or not, and the plan cannot be built. The settings file is read for +this only when such a step is to be built. + The plan can be built when no target is blocked. Blocked steps are listed but not counted in the totals. @@ -1611,6 +1682,7 @@ is 32 hexadecimal characters: | `output/` | what `{output}` names, made empty before the command starts; a succeeded run's `output/` is its product | | `settings.json` | the inline `settings` as the run saw them, when the definition has them | | `tasks.json`, `annotations/` | a freeze's tasks and the line files it read | +| `endpoint.json` | a generate's endpoint, `{address, version}`, as it found it; kept in the run's record as `endpoint` | | `stdout.log`, `stderr.log` | the command's standard output and error | | `cancel` | present when cancellation was asked for | | `outcome.json` | how the command ended, written when every process of the run is gone | @@ -2223,6 +2295,11 @@ and result keys of each operation are in its contract. | `annotation` | inspect | Read one record's annotation under a task as it now is and as it is in the file, whether it is unsaved or stale, and the hash of the record's content. | | `set_annotation` | edit | Check annotations of a task's records, or their removal, and keep them as unsaved edits; one item that does not check refuses them all. | | `revert_annotations` | edit | Put back the saved annotations of a task's named records, or of all its records, in place of their unsaved edits. | +| `endpoint` | inspect | Read the Pumas endpoint this machine uses: its address, whether it answered, and each model and profile it serves with its modalities, its capabilities and what Tuldok can make with it. | +| `set_endpoint` | owner | Set the Pumas endpoint this machine uses once it has answered what it serves, or clear it with null. | +| `find_endpoints` | owner | List the Pumas endpoints advertising themselves on this machine, for the owner to pick from. | +| `suggestion_models` | inspect | List, for each kind of record in the product of a task's dataset, the models the Pumas endpoint serves that can suggest a value of the task. | +| `suggest_annotation` | edit | Ask a model the Pumas endpoint serves for a value of a task for one record; nothing is stored, and an answer that is not a value of the task is refused. | `map` answers `groups` (in their order, each with `id`, `title`, `parent`, `description` and `models`, the number of recipes naming it), `models` (one per @@ -2615,6 +2692,72 @@ Each call of `set_annotation` and `revert_annotations` writes one activity row whose target is the task's reference and whose detail says how many records it set, removed or reverted. +**`suggestion_models`** takes `task` and answers `task`, `type`, `address` +(the machine's endpoint, or null), `kinds` and `problem` (why nothing could +be asked: no endpoint, or the endpoint's reason; else null). `kinds` maps +each kind of record the product has that the task annotates to the served +models that can suggest for it now: `{model, profile, capability}`. It is +empty for a kind no model fits, and for every kind of a `review`, `boxes`, +`spans` or `segments` task and of a point cloud, mesh, array or file. + +| Task | Record | Asked as | +| --- | --- | --- | +| `text` | image | `image_to_text`, `image_messages` with the instruction and the image | +| `text` | audio | `audio_transcription`, the `audio` input (a 16-bit PCM WAVE of at most 30 s, sent as `pcm_s16le`), no options | +| `text` | text | `chat_generation`, `messages`: the instruction as system, the text as user | +| `class`, `tags` | text, image, audio | `decision` where an available one takes the record's modality: one `choice` over the vocabulary for `class`, one `noul` per term for `tags` (kept above 0.5); else, for text and images, `chat_generation` or `image_to_text` asked to answer with terms only, kept only when the answer is made of terms | + +**`suggest_annotation`** takes `task`, `record`, `model`, `profile` (needed +when the endpoint serves the model with more than one) and `instruction` +(optional, at most 4,000 characters; a caption and a summary have a default) +and answers `task`, `record` and `suggestion`: `value`, in the task's form, +and `from`, `{model, profile, capability}`. Nothing is stored and no activity +row is written; a person who keeps the value passes `from` to +`set_annotation`, so that its line in the annotations file names the model. +It is refused `not-found` for a record the product does not have, +`unavailable` when no endpoint is set, the endpoint does not answer or +refuses, or the model cannot suggest for this record now, `invalid` for a +record that cannot be sent (an image not PNG or JPEG or over the client's +bounds, a sound not such a WAVE), and `unsuitable` for an answer that is not a +value of the task, the model's words quoted. The record is read and the +endpoint asked outside the service's lock; an answer not given within 300 s +is given up. + +## The Pumas endpoint + +Generation and suggestions go through a Pumas endpoint, reached by HTTP +only: nothing of Pumas is part of Tuldok. The address is a setting of the +machine, `pumas_endpoint` in the settings file (see +[The project directory on this machine](#the-project-directory-on-this-machine)), +never in the folder or in a definition. Every offer and every check comes from +what the endpoint says it serves at that moment (`GET /v1/served-models` of +the Pumas 0.8.0 contract); an output Tuldok cannot keep as a record (anything +but `text` and `png_base64`) is not offered. Every call is bounded in time +and bytes as Tuldok's client bounds it and is made outside the service's lock. + +**`endpoint`** takes nothing and answers `address` (or null), `answered`, +`version` (what its `/.well-known/pumas` reports, or null), `models` and +`problem` (null when it answered). Each model is one served (model, profile): +`model`, `profile`, `profile_required`, `model_id`, `provider`, `load_state`, +`context_tokens`, `modalities` (`input`, `output`), `capabilities` (each with +`capability`, `available`, `reason`, `input_formats`, `output_formats`, +`input_modalities`, `output_modalities` and `option_bounds`, option to +`{minimum, maximum}`) and `makes`: what a `generate` can make with it now, +each `{make, capability, options (the options it takes, with their bounds), +seed (whether it takes one)}`. + +**`set_endpoint`** takes `address`, or null to clear the setting. An address +is asked once what it serves and kept only when it answered; it must be the +numeric-loopback HTTP address Pumas 0.8.0 serves on, such as +`http://127.0.0.1:8765`, without a path (refused `invalid` otherwise, and +`unavailable` when it does not answer). It answers as `endpoint` does, and +writes an activity row (`set` or `cleared`). + +**`find_endpoints`** takes nothing and answers `endpoints`, each `{address, +version, component}`, the Pumas endpoints that advertise themselves on this +machine's loopback listeners, and `rejected`, `{server_url, reason}` of those +that answered with an advertisement Tuldok refuses. + ## The project directory on this machine Everything a project keeps on one machine alone (installed environments, code @@ -2631,10 +2774,12 @@ environment variable `TULDOK_SETTINGS` names. It is strict JSON as in [JSON rules](#json-rules), at most 64 KiB, and has no other fields: ```json -{"format": "tuldok_settings_v1", "project_home": "/absolute/path"} +{"format": "tuldok_settings_v1", "project_home": "/absolute/path", "pumas_endpoint": "http://127.0.0.1:8765"} ``` -`project_home` is optional and must be absolute. The file is read only when +`project_home` is optional and must be absolute. `pumas_endpoint` is optional, +an `http` or `https` address of at most 2,048 characters with no spaces; it is +set by `set_endpoint` (see [The Pumas endpoint](#the-pumas-endpoint)). The file is read only when the environment variable does not decide. A settings file that cannot be read or is not valid stops the command with a message naming the file and the fault, exit status 2, and stops the app's start-up; Tuldok never falls back to diff --git a/docs/plans/definition-first-projects/spec-d5.md b/docs/plans/definition-first-projects/spec-d5.md index 30a44a3c..b8e57b47 100644 --- a/docs/plans/definition-first-projects/spec-d5.md +++ b/docs/plans/definition-first-projects/spec-d5.md @@ -95,3 +95,46 @@ Everything is checked against a fake endpoint built from the released contract ( ## 8. Out of scope Audio and 3D output (nothing serves them); video; embeddings, rerank and similarity search over a dataset; continuing a generation that failed part way; a queue of suggestions that outlives the page; choosing among several endpoints. + +## As built + +### D5a and D5b + +What differs from the text above, and what was chosen where it was silent. + +- **The address is a numeric-loopback HTTP address.** Section 2 says "an `http` or `https` address". The settings file accepts that (`local.endpoint_problem`), but `set_endpoint` keeps only what the client can send a model operation to: `pumas_operations.exchange` takes a credential-free numeric-loopback `http` base (`pumas_gateway_descriptor.endpoint`), which is also what Pumas 0.8.0 binds (`local-discovery-bootstrap.md`). Anything else is refused `invalid` before any request. Supporting `https` or a host name needs a change to the client's exchange, not to `pumas.py`. +- **`pumas.py` imports `pumas_operations`, `image_generation`, `pumas_vision` and `gateway_discovery`**; `ai_http` is reached through `served_models`. No other module of `tuldok_project/` imports any of them; `steps.py` imports `pumas.py` inside `generate_records` only. +- **One additive change to the client:** `pumas_operations.result` decodes a `decisions` result (`{kind, answers}`, answers read by the caller) and `exchange` checks the result kind through `RESULT_KINDS`, which adds `decisions`. Catalog mode never asks for that output; its tests pass unchanged. +- **The fake** (`tests/fake_pumas_typed.py`) gained three optional state keys: `modes` (one mode per POST, before `mode`), `respond(body)` (the `result` of a successful POST) and `advertise` (a version for which `/.well-known/pumas` answers with the advertisement fixture at the fake's own address). Without them it answers as before. +- **The endpoint's version** is `build_info.package_version` of its `/.well-known/pumas`, or null when it has none. The step writes `{address, version}` to `/endpoint.json` (beside `output/`, not in the product) and the build keeps it in a new column `runs.endpoint`, set to `{address, version: null}` when the run is recorded and completed from the file when it ends. The address also appears in the run's `argv`. Neither is in the folder; a test scans the folder and `git log -p` for it. +- **No endpoint set.** A plan marks a `generate` that would be built `blocked`, with one cause, itself, `rebuild: "endpoint"` and the reason, and a note; it is added to `blocked_targets` even when it is not a target (so `execute` refuses the plan before anything runs) and `buildable` is false. The settings file is read for this only when such a step is in the plan, through a function `make_plan` takes as `endpoint`: spec-m4's rule that making a plan opens no file (a test of it) still holds for every plan without a generate. A setting cleared after the plan was made fails the step before it starts (`StepProblem`). +- **The capability** is the first of the served model's available capabilities, in the endpoint's order, that makes the output from `text` (`available_capabilities(entry, 'text', output)`); the request's input is always `{"kind": "text"}` with `capability` named. With the vision fixture's models that is `chat_generation` before `text_generation`. +- **Options.** Only the names of the capability's options kind in the released grammar are sent (`text_generation`: `max_tokens`, `temperature`, `top_p`; `image_generation`: `width`, `height`, and `seed` from the setting). An option must be advertised with a bound and lie within it; `width` and `height` are required for an image, and the client's own cap (2,048 px a side, 4 Mpx) applies. A capability whose options kind Tuldok does not know is offered and asked with no options. +- **The seed** is sent only when the capability's options kind has one and the endpoint advertises a `seed` bound; `seed + count − 1` is checked against it before anything is asked. For an image `origin.seed` is the seed the endpoint reports it used (also when the setting has none); for text it is null. +- **Bounds not in the text:** at most 100,000 items in all, also with an input (records × `per`); `per` 1 to 1,000; `prompt` 1 to 16,000 characters, checked against an advertised `input_characters` per item before anything is asked; `seed` 0 to 2³²−1; `options` at most 32 numbers, `seed` not among them. +- **A text too long for one line** of `records.jsonl` (64 KiB) is written as `files/.txt` with `path`; the client reads at most 256 KiB of a text result. +- **The pauses** before asking again an item refused `not_admitted` are 1 s and 2 s. Every `not_admitted` outcome is asked again, as the text says, whatever its code. Each attempt has its own `request_id`. +- **An input of prompts** gives its text records only, inline or a UTF-8 file of at most 64 KiB in the product; others are skipped and counted. An input shown through a `view` is refused, as for `freeze`. +- **`set_endpoint`** writes an activity row (`set` or `cleared`, the address not in it). `find_endpoints` is the owner's and is not a mutation, so it writes none. `suggest_annotation` is `edit` and not a mutation: nothing is stored and no row is written. +- **Suggestions.** No options are sent (the capability's defaults apply). A suggestion is given up after 300 s (`pumas.SUGGEST_SECONDS`) by the client's own cancel. A record is read whole up to 16 MiB; an image must be PNG or JPEG and pass `pumas_vision.image_part`; a sound must be a 16-bit PCM WAVE of one or two channels, 8 to 192 kHz and at most 30 s (sent as `pcm_s16le`), since Pumas parses no container. Advertised image and audio bounds are checked when advertised. A caption's default instruction is "Describe this image in one or two sentences.", a summary's "Summarize this text in a few sentences." +- **Refusals of `suggest_annotation`:** `unavailable` (no endpoint, it did not answer or refused, the model cannot suggest for this record), `not-found` (model or profile not served, record not in the product), `invalid` (a model served with two profiles named without one; content that cannot be sent) and a new code, `unsuitable` (409), for an answer that is not a value of the task, with the model's words quoted (at most 400 characters). +- **Terms only.** `class` keeps the whole answer, trimmed of spaces, quotes and a final full stop, when it is a term exactly. `tags` takes the whole answer as one term when it is one, else splits it on lines and commas (a term holding a comma is then lost), trims list marks, and keeps it only when every piece is a term; the value is in vocabulary order. Case is not folded. +- **Decisions.** `class` asks one `choice` question `class` with the vocabulary as `criteria`; `tags` one `noul` question per term, `t0`, `t1`, …, and keeps the terms above 0.5. `state` is the record's text, or the instruction (default "Decide for the content given.") with `images` or `audio`. +- **`suggestion_models`** answers the kinds the product has that the task annotates (none without a product), each with every served (model, profile) that fits, and `problem` instead of a refusal when there is no endpoint or it does not answer. + +Section 4's table, as built: + +| Task | Record | Offered | Request | +| --- | --- | --- | --- | +| `text` (caption) | image | yes, where `image_to_text` is available for `messages_image` | `capability: image_to_text`, `input: {"kind": "image_messages", "messages": [{"role": "user", "content": [{"kind": "text", "text": }, {"kind": "image", "encoding": "png"\|"jpeg", "data_base64": …}]}]}`, `output: text` | +| `text` (transcript) | audio | yes, where `audio_transcription` is available for `pcm_s16le`/`pcm_f32le` | `capability: audio_transcription`, `input: {"kind": "audio", "encoding": "pcm_s16le", "sample_rate_hz", "channels", "sample_count", "data_base64"}`, `output: text`, no options. The contract's "Audio transcription" section gives this input; its request grammar still calls the `audio` kind reserved, and no options kind is named for it, so none is sent | +| `text` (summary) | text | yes, where `chat_generation` is available for `messages_text` | `capability: chat_generation`, `input: {"kind": "messages", "messages": [{"role": "system", "content": }, {"role": "user", "content": }]}`, `output: text` | +| `class`, `tags` | text, image, audio | yes by `decision`, where it is available and its `input_modalities` hold the record's modality | `capability: decision`, `input: {"kind": "decision", "state", "questions", "images": [{"encoding", "data_base64"}] \| "audio": [clip]}`, `output: decisions`. The shape of a decision image is not written out in the contract's text (only that audio clips have no `kind`); it is the released DTO `DecisionImage {encoding, data_base64}` (`types.rs` at `v0.8.0`) | +| `class`, `tags` | text | else by `chat_generation`, terms only | as the summary, the instruction asking for terms of the listed vocabulary | +| `class`, `tags` | image | else by `image_to_text`, terms only | as the caption, likewise | +| `class`, `tags` | audio | only by `decision`; no fallback, as the text says | | +| `review`, `boxes`, `spans`, `segments` | any | no | | +| any | point cloud, mesh, array, file | no | | + +- **Tests:** `tests/test_tuldok_project_pumas.py`, 29: the check (4), the settings file (2), the routes and offers from descriptors alone (2), `endpoint`/`find_endpoints` on the fake with the scanner patched (3), and against a database: the setting set, cleared, refused and its activity (3), a text dataset and an image dataset from a dataset of prompts with `per` and seeds generated by `builds.execute`, an option, a model and a capability each failing before any request, `not_admitted` asked again twice then failing, another failure failing at once at item 2 (5), each row of the table, answers not made of terms or not in the vocabulary refused, no model fitting, and a kept suggestion's `from` in the saved line (8), and the step alone (2). `test_tuldok_project_service.py`: 59 operations, `set_endpoint` a mutation, `set_endpoint` and `find_endpoints` the owner's, the new reads in `test_every_read`. The catalog profile's digest is unchanged; the project_folder profile has the five new operations. +- **Not verified:** a real Pumas (the owner's word is needed, section 7); a decision model's, a Torch transcription runtime's and a vision model's real answers (the fake answers what the contract describes); `https` and host-name addresses (refused); cancelling a generate during a request (the launcher's cancel stops the process, as for any run; not tested here); 100,000 items; a JPEG or stereo sound sent for a suggestion; the page (D5c). diff --git a/pumas_operations.py b/pumas_operations.py index e3260895..df4304fa 100644 --- a/pumas_operations.py +++ b/pumas_operations.py @@ -32,6 +32,8 @@ MAX_DIMENSION = 2048 MAX_PIXELS = 4194304 MAX_MESSAGE = 600 +# The result kind of each output Tuldok asks for. +RESULT_KINDS = {'text': 'text', 'png_base64': 'image', 'decisions': 'decisions'} # Capabilities Tuldok sends, with their fixed contract-version-1 semantic task. USED_CAPABILITIES = {'chat_generation': 'chat_generation', 'image_generation': 'text_to_image', 'image_to_text': 'image_to_text'} @@ -581,7 +583,7 @@ def watch(): # The typed error's `outcome` is authoritative; HTTP status is evidence only. error.provider_http_status = response.status raise - if value['kind'] != {'text': 'text', 'png_base64': 'image'}.get(payload['output']): + if value['kind'] != RESULT_KINDS.get(payload['output']): raise OperationError('Typed result has the wrong output kind; no replay.', 'unknown', raw=raw) if response.status != 200: raise OperationError('Unexpected typed HTTP status; provider outcome unknown, no replay.', 'unknown', raw=raw) @@ -632,6 +634,11 @@ def result(raw, request_id): if projected['finish_reason'] != 'stop': raise ValueError('Text did not finish with stop; partial output is not applied.') projected['text'].encode('utf-8') + elif projected.get('kind') == 'decisions': + # `answers` maps each question to its typed answer; the caller reads the answers it asked for. + response_fields(projected, ('kind', 'answers')) + if type(projected['answers']) is not dict: + raise ValueError('Invalid typed decisions result.') elif projected.get('kind') == 'image': response_fields(projected, ('kind', 'png_base64', 'seed')) if not isinstance(projected['png_base64'], str) or type(projected['seed']) is not int or not 0 <= projected['seed'] <= 4294967295: diff --git a/tests/fake_pumas_typed.py b/tests/fake_pumas_typed.py index 10d301a3..da37bb90 100644 --- a/tests/fake_pumas_typed.py +++ b/tests/fake_pumas_typed.py @@ -1,4 +1,11 @@ -"""Source-derived PR54 finite HTTP fixture, with 0.8.0 served-model listings; it is not the native gateway.""" +"""Source-derived PR54 finite HTTP fixture, with 0.8.0 served-model listings; it is not the native gateway. + +For spec-d5.md's tests the state may also hold: `modes`, a list of modes taken +one per POST before `mode`; `respond(body)`, giving the `result` of a +successful POST (a decision's `decisions`, an echo of the prompt); and +`advertise`, a package version for which `/.well-known/pumas` answers with +the advertisement fixture at this fake's own address. +""" import base64 import json import threading @@ -24,6 +31,11 @@ def reply(self, value, status=200): try: self.wfile.write(raw) except OSError: pass def do_GET(self): + if self.path == '/.well-known/pumas' and state.get('advertise'): + value = json.loads((FIXTURES.parent / 'pumas-http-pr51/advertisement.json').read_bytes()) + value['endpoint'] = 'http://127.0.0.1:' + str(self.server.server_port) + value['build_info']['package_version'] = state['advertise'] + return self.reply(value) if self.path == '/v1/served-models' and state.get('served_models_raw') is not None: raw = state['served_models_raw'] self.send_response(200); self.send_header('Content-Length', str(len(raw))); self.end_headers() @@ -54,7 +66,7 @@ def do_GET(self): def do_POST(self): body = json.loads(self.rfile.read(int(self.headers['Content-Length']))) state['requests'].append(body); state['entered'].set() - mode = state['mode'] + mode = state['modes'].pop(0) if state.get('modes') else state['mode'] if mode == 'hold': state['release'].wait(3) if mode == 'delay': time.sleep(.2) @@ -70,7 +82,9 @@ def do_POST(self): return self.reply({'contract_version': 1, 'request_id': None, 'error': {'code': 'invalid_request', 'outcome': 'not_admitted', 'message': 'request body is not valid JSON'}}, 400) result = {'kind': 'text', 'text': state['content'], 'finish_reason': 'stop'} - if body['capability'] == 'image_generation': + if state.get('respond') is not None: + result = state['respond'](body) + elif body['capability'] == 'image_generation': import io from PIL import Image out = io.BytesIO(); Image.new('RGB', (body['options']['width'], body['options']['height']), (35,95,160)).save(out, 'PNG') diff --git a/tests/test_tuldok_project_pumas.py b/tests/test_tuldok_project_pumas.py new file mode 100644 index 00000000..b834fa41 --- /dev/null +++ b/tests/test_tuldok_project_pumas.py @@ -0,0 +1,875 @@ +"""Generating datasets and suggesting annotations through a Pumas endpoint (spec-d5.md, slices D5a and D5b). + +Everything is asked of tests/fake_pumas_typed.py, a fake made from the +released 0.8.0 contract that this test starts on a loopback port of its own, +serving a /v1/served-models listing the test writes (the vision fixture's +models and four more). No running Pumas is contacted and this machine's +listeners are never scanned: find_endpoints is tested with the scanner +patched. The settings file and the projects home are throwaway paths. + +The check of a definition is tested on its own. Everything else needs a +database and runs only when TULDOK_DATABASE_URL names a disposable cluster: a +Git repository holding a project folder and its code side by side, whose +datasets are generated for real by builds.execute (the step runs as +python -m tuldok_project.steps generate, against the fake), and a Service +for the operations. No GPU, no environment. +""" +import base64 +import copy +import hashlib +import io +import json +import os +from pathlib import Path +import socket +import subprocess +import sys +import tempfile +import unittest +from unittest import mock +import uuid +import wave + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) +sys.path.insert(0, str(Path(__file__).resolve().parent)) + +from PIL import Image # noqa: E402 + +import fake_pumas_typed # noqa: E402 +import gateway_discovery # noqa: E402 +from tuldok_project import annotations, builds, check, inside, local, plan, pumas, steps, store # noqa: E402 +from tuldok_project.service import Service # noqa: E402 +from tuldok_project.store import ProjectError # noqa: E402 + +DATABASE = os.environ.get('TULDOK_DATABASE_URL') +GIT = ['git', '-c', 'user.name=Tuldok Test', '-c', 'user.email=test@example.invalid', '-c', 'commit.gpgsign=false'] +RIGHTS = 'Made by a model for this test; anything may be done with it.' +FIXTURES = Path(__file__).resolve().parent / 'fixtures' +OWNER = {'actor_id': 'owner-1', 'kind': 'owner', 'label': 'The owner', + 'scopes': ['approve-execution', 'cancel', 'edit', 'execute', 'inspect']} +EDITOR = {'actor_id': 'agent-1', 'kind': 'agent', 'label': 'helper', 'scopes': ['inspect', 'edit']} +TEXT_BOUNDS = [{'option': 'max_tokens', 'minimum': 1.0, 'maximum': 4096.0}, + {'option': 'temperature', 'minimum': 0.0, 'maximum': 2.0}, + {'option': 'top_p', 'minimum': 0.0, 'maximum': 1.0}] +IMAGE_BOUNDS = [{'option': 'width', 'minimum': 1.0, 'maximum': 4294967295.0}, + {'option': 'height', 'minimum': 1.0, 'maximum': 4294967295.0}, + {'option': 'seed', 'minimum': 0.0, 'maximum': 4294967295.0}, + {'option': 'input_characters', 'minimum': 1.0, 'maximum': 4000.0}] + + +# ----------------------------------------------------------- the listing + +def _capability(name, inputs, outputs, input_modalities, output_modalities, bounds=(), reason=None, task=None): + return {'capability': name, 'semantic_task': task or name, 'input_formats': list(inputs), + 'output_formats': list(outputs), 'input_modalities': list(input_modalities), + 'output_modalities': list(output_modalities), 'streaming': False, + 'availability': {'state': 'unavailable', 'reason': reason} if reason else {'state': 'available'}, + 'option_bounds': [dict(bound) for bound in bounds]} + + +def _model(model, profile, capabilities, inputs, outputs, provider='llama_cpp'): + return {'model': model, 'profile': profile, 'model_id': f'test/{model}', 'provider': provider, + 'load_state': 'loaded', 'profile_required': False, 'modalities': {'input': inputs, 'output': outputs}, + 'capabilities': capabilities} + + +def listing(): + """The vision fixture's served models (controlled-vision on two profiles, controlled-image) and four more.""" + value = json.loads((FIXTURES / 'pumas-image-to-text-v1' / 'served-models.json').read_bytes()) + value['models'] += [ + _model('writer', 'writer-cpu', [ + _capability('chat_generation', ['messages_text'], ['text'], ['text'], ['text'], TEXT_BOUNDS), + _capability('text_generation', ['text'], ['text'], ['text'], ['text'], TEXT_BOUNDS), + _capability('image_generation', ['text'], ['png_base64'], ['text'], ['image'], IMAGE_BOUNDS, + reason='unsupported_adapter', task='text_to_image')], ['text'], ['text']), + _model('painter', 'painter-gpu', [ + _capability('image_generation', ['text'], ['png_base64'], ['text'], ['image'], IMAGE_BOUNDS, + task='text_to_image'), + _capability('chat_generation', ['messages_text'], ['text'], ['text'], ['text'], TEXT_BOUNDS, + reason='unsupported_adapter')], ['text'], ['image'], provider='torch'), + _model('decider', 'decider-cpu', [ + _capability('decision', ['decision'], ['decisions'], ['text', 'image', 'audio'], ['json'])], + ['text', 'image', 'audio'], ['json']), + _model('listener', 'listener-cpu', [ + _capability('audio_transcription', ['pcm_s16le', 'pcm_f32le'], ['text'], ['audio'], ['text'], + [{'option': 'max_output_tokens', 'minimum': 512.0, 'maximum': 512.0}])], + ['audio'], ['text'], provider='torch'), + ] + return value + + +def png(size=(16, 8), color=(20, 120, 200)): + out = io.BytesIO() + Image.new('RGB', size, color).save(out, 'PNG') + return out.getvalue() + + +def wav(seconds=0.25, rate=16000): + out = io.BytesIO() + with wave.open(out, 'wb') as sound: + sound.setnchannels(1) + sound.setsampwidth(2) + sound.setframerate(rate) + sound.writeframes(b'\x01\x00' * int(seconds * rate)) + return out.getvalue() + + +def closed_port(): + with socket.socket() as probe: + probe.bind(('127.0.0.1', 0)) + return probe.getsockname()[1] + + +def text_result(text): + return {'kind': 'text', 'text': text, 'finish_reason': 'stop'} + + +# ------------------------------------------------------------ definitions + +def _generate(settings, inputs=None): + run = {'step': 'generate', 'settings': {'rights': RIGHTS, **settings}} + if inputs is not None: + run['inputs'] = inputs + return {'format': 'tuldok_definition_v1', 'kind': 'dataset', 'title': 'Generated', 'run': run} + + +def _import(settings): + return {'format': 'tuldok_definition_v1', 'kind': 'dataset', 'title': 'Imported', + 'run': {'step': 'import', 'settings': {'rights': RIGHTS, **settings}}} + + +def _task(dataset, task, vocabulary=None, title='A task'): + document = {'format': 'tuldok_definition_v1', 'kind': 'annotation', 'title': title, 'dataset': dataset, + 'task': task} + if vocabulary is not None: + document['vocabulary'] = vocabulary + return document + + +DEFINITIONS = { + # The exact texts a page would write: a text dataset, and an image dataset driven by a dataset of prompts. + 'datasets/lines': _generate({'make': 'text', 'model': 'writer', 'prompt': 'Write line {n} of a short poem.', + 'count': 3, 'seed': 5, 'options': {'max_tokens': 64, 'temperature': 0.7}}), + 'datasets/prompts': _import({'source': 'data/prompts', 'pattern': '*.txt', 'lines': True}), + 'datasets/pictures': _generate({'make': 'image', 'model': 'painter', 'profile': 'painter-gpu', + 'prompt': 'A picture of {text}, number {n}.', 'per': 2, 'seed': 100, + 'options': {'width': 64, 'height': 32}}, inputs={'prompts': 'datasets/prompts'}), + 'datasets/one-line': _generate({'make': 'text', 'model': 'writer', 'prompt': 'One line.', 'count': 1}), + 'datasets/three-lines': _generate({'make': 'text', 'model': 'writer', 'prompt': 'Line {n}.', 'count': 3}), + 'datasets/too-long': _generate({'make': 'text', 'model': 'writer', 'prompt': 'Line {n}.', 'count': 2, + 'options': {'max_tokens': 99999}}), + 'datasets/nobody': _generate({'make': 'text', 'model': 'nobody', 'prompt': 'Line {n}.', 'count': 2}), + 'datasets/no-paint': _generate({'make': 'image', 'model': 'writer', 'prompt': 'Line {n}.', 'count': 2, + 'options': {'width': 8, 'height': 8}}), + 'datasets/mixed': _import({'source': 'data/mixed'}), + 'annotations/captions': _task('datasets/mixed', 'text', title='Captions, transcripts and summaries'), + 'annotations/kinds': _task('datasets/mixed', 'class', ['cat', 'dog', 'car'], title='What it is'), + 'annotations/labels': _task('datasets/mixed', 'tags', ['red', 'blue', 'round'], title='What it has'), + 'annotations/quality': _task('datasets/mixed', 'review', title='Quality'), +} + + +def write_project(root, project_id): + """root/project (the folder, code_root ../code) and root/code (the prompts and a text, an image and a sound).""" + folder, code = root / 'project', root / 'code' + for directory in ('datasets', 'annotations'): + (folder / directory).mkdir(parents=True) + (folder / 'tuldok.json').write_text(json.dumps({'format': 'tuldok_project_v1', 'id': project_id, + 'name': 'Generation test project', 'code_root': '../code'}, + indent=2) + '\n', encoding='utf-8') + for reference, document in DEFINITIONS.items(): + (folder / f'{reference}.json').write_text(json.dumps(document, indent=2) + '\n', encoding='utf-8') + (code / 'data' / 'prompts').mkdir(parents=True) + (code / 'data' / 'prompts' / 'subjects.txt').write_text('a red ball\na blue car\n', encoding='utf-8') + mixed = code / 'data' / 'mixed' + mixed.mkdir() + (mixed / 'note.txt').write_text('A long text about a dog that runs after a red ball.\n', encoding='utf-8') + (mixed / 'photo.png').write_bytes(png()) + (mixed / 'voice.wav').write_bytes(wav()) + (mixed / 'shape.xyz').write_text('0 0 0\n1 1 1\n', encoding='utf-8') + + +def records_of(directory): + with open(Path(directory) / 'records.jsonl', encoding='utf-8') as handle: + return [json.loads(line) for line in handle] + + +# ------------------------------------------------------------------ check + +class Checked(unittest.TestCase): + """check on a generate's settings and input (spec-d5.md section 3), with no database.""" + + def setUp(self): + directory = tempfile.TemporaryDirectory() + self.addCleanup(directory.cleanup) + self.root = Path(directory.name) + self.folder = self.root / 'project' + write_project(self.root, uuid.uuid4().hex) + + def write(self, reference, document): + (self.folder / f'{reference}.json').write_text(json.dumps(document, indent=2) + '\n', encoding='utf-8') + + def problems(self, reference): + report = check.check_folder(self.folder) + return {(problem.pointer, problem.severity) for problem in report.problems + if problem.path == f'{reference}.json'} + + def test_the_project_checks(self): + report = check.check_folder(self.folder) + self.assertEqual([problem for problem in report.problems if problem.severity == 'error'], []) + + def test_settings_a_generate_refuses(self): + self.write('datasets/lines', _generate({'make': 'video', 'model': ' padded', 'profile': 'a b', + 'prompt': 'A {text} and {other} and {', 'count': 0, 'per': 2, + 'seed': -1, 'options': {'seed': 1, 'Bad': 1, 'max_tokens': 'many'}, + 'extra': True})) + found = self.problems('datasets/lines') + for pointer in ('make', 'model', 'profile', 'prompt', 'count', 'per', 'seed', 'options/seed', 'options/Bad', + 'options/max_tokens', 'extra'): + self.assertIn((f'/run/settings/{pointer}', 'error'), found) + + def test_placeholders_and_the_input(self): + self.write('datasets/lines', _generate({'make': 'text', 'model': 'writer', 'prompt': 'About {text}.', + 'count': 2})) + report = check.check_folder(self.folder) + self.assertIn('The prompt uses {text}; it may use {n} ({text} needs an input of prompts).', + [problem.message for problem in report.problems if problem.path == 'datasets/lines.json']) + self.write('datasets/lines', _generate({'make': 'text', 'model': 'writer', 'prompt': 'About {text}.', + 'count': 2}, inputs={'prompts': 'datasets/prompts'})) + self.assertIn(('/run/settings/count', 'error'), self.problems('datasets/lines')) + self.write('datasets/lines', _generate({'make': 'text', 'model': 'writer', 'prompt': 'One.'})) + self.assertIn(('/run/settings/count', 'error'), self.problems('datasets/lines')) + document = _generate({'make': 'text', 'model': 'writer', 'prompt': 'One.', 'count': 1}, + inputs={'other': 'datasets/prompts'}) + document['run']['annotations'] = ['annotations/kinds'] + self.write('datasets/lines', document) + self.assertTrue({('/run/inputs', 'error'), ('/run/annotations', 'error')} <= self.problems('datasets/lines')) + del document['run']['inputs'], document['run']['annotations'] + document['run']['command'] = ['make'] + self.write('datasets/lines', document) + self.assertIn(('/run/command', 'error'), self.problems('datasets/lines')) + + def test_a_plan_without_an_endpoint_says_so(self): + definitions = {reference: copy.deepcopy(document) for reference, document in DEFINITIONS.items()} + made = plan.make_plan(definitions, ['datasets/pictures'], endpoint=False) + steps_ = {step['reference']: step for step in made['steps']} + self.assertEqual(steps_['datasets/prompts']['action'], 'build') + self.assertEqual(steps_['datasets/pictures']['action'], 'blocked') + self.assertEqual(steps_['datasets/pictures']['command'], ['tuldok', 'generate']) + self.assertEqual(steps_['datasets/pictures']['blocked_by'], + [{'reference': 'datasets/pictures', 'rebuild': 'endpoint', 'reason': plan.NO_ENDPOINT}]) + self.assertFalse(made['buildable']) + self.assertEqual(made['blocked_targets'], ['datasets/pictures']) + self.assertIn('datasets/pictures is generated through a Pumas endpoint, and none is set on this machine.', + made['notes']) + asked = [] + made = plan.make_plan(definitions, ['datasets/prompts'], endpoint=lambda: asked.append(1) or False) + self.assertTrue(made['buildable']) + self.assertEqual(asked, []) # no generate to build: the setting is not even read + made = plan.make_plan(definitions, ['datasets/pictures'], endpoint=lambda: True) + self.assertTrue(made['buildable']) + self.assertEqual({step['action'] for step in made['steps']}, {'build'}) + + +class Settings(unittest.TestCase): + """pumas_endpoint in the settings file, beside project_home.""" + + def setUp(self): + directory = tempfile.TemporaryDirectory() + self.addCleanup(directory.cleanup) + self.file = Path(directory.name) / 'settings.json' + patcher = mock.patch.dict(os.environ, {local.SETTINGS_VARIABLE: str(self.file)}) + patcher.start() + self.addCleanup(patcher.stop) + + def test_set_kept_beside_the_home_and_cleared(self): + self.assertIsNone(local.pumas_endpoint()) + local.set_pumas_endpoint('http://127.0.0.1:8765') + local.set_project_home(str(self.file.parent / 'home')) + self.assertEqual(json.loads(self.file.read_text()), {'format': 'tuldok_settings_v1', + 'pumas_endpoint': 'http://127.0.0.1:8765', + 'project_home': str(self.file.parent / 'home')}) + self.assertEqual(self.file.stat().st_mode & 0o777, 0o600) + local.set_pumas_endpoint(None) + self.assertEqual(json.loads(self.file.read_text()), {'format': 'tuldok_settings_v1', + 'project_home': str(self.file.parent / 'home')}) + with self.assertRaises(ValueError): + local.set_pumas_endpoint('ftp://somewhere') + + def test_a_bad_value_in_the_file(self): + self.file.write_text(json.dumps({'format': 'tuldok_settings_v1', 'pumas_endpoint': 'not an address'})) + with self.assertRaises(local.SettingsError) as raised: + local.pumas_endpoint() + self.assertIn('its pumas_endpoint must be an http or https address', str(raised.exception)) + + +class Routes(unittest.TestCase): + """What a served model is offered for comes from its descriptors alone (no request).""" + + def setUp(self): + self.models = {(entry['model'], entry['profile']): entry + for entry in pumas.client.decode_served_models(json.dumps(listing()).encode())['models']} + + def capabilities(self, model, profile, task, kind): + return [route['capability'] for route in pumas.routes(self.models[model, profile], task, kind)] + + def test_section_four(self): + vision = ('controlled-vision', 'vision-cpu') + self.assertEqual(self.capabilities(*vision, 'text', 'image'), ['image_to_text']) + self.assertEqual(self.capabilities('controlled-vision', 'vision-gpu', 'text', 'image'), []) # unavailable + self.assertEqual(self.capabilities('listener', 'listener-cpu', 'text', 'audio'), ['audio_transcription']) + self.assertEqual(self.capabilities('writer', 'writer-cpu', 'text', 'text'), ['chat_generation']) + for kind in ('text', 'image', 'audio'): + self.assertEqual(self.capabilities('decider', 'decider-cpu', 'class', kind), ['decision']) + self.assertEqual(self.capabilities('decider', 'decider-cpu', 'tags', kind), ['decision']) + self.assertEqual(self.capabilities('writer', 'writer-cpu', 'class', 'text'), ['chat_generation']) + self.assertEqual(self.capabilities(*vision, 'tags', 'image'), ['image_to_text']) + self.assertEqual(self.capabilities('writer', 'writer-cpu', 'class', 'audio'), []) + for task in ('review', 'boxes', 'spans', 'segments'): + for model in self.models: + self.assertEqual(self.capabilities(*model, task, 'image'), []) + for kind in ('pointcloud', 'mesh', 'array', 'file'): + for model in self.models: + self.assertEqual(self.capabilities(*model, 'text', kind), []) + + def test_what_each_model_makes(self): + self.assertEqual(pumas.makes(self.models['writer', 'writer-cpu']), + [{'make': 'text', 'capability': 'chat_generation', 'seed': False, + 'options': {'max_tokens': {'minimum': 1.0, 'maximum': 4096.0}, + 'temperature': {'minimum': 0.0, 'maximum': 2.0}, + 'top_p': {'minimum': 0.0, 'maximum': 1.0}}}]) + self.assertEqual(pumas.makes(self.models['painter', 'painter-gpu']), + [{'make': 'image', 'capability': 'image_generation', 'seed': True, + 'options': {'width': {'minimum': 1.0, 'maximum': 4294967295.0}, + 'height': {'minimum': 1.0, 'maximum': 4294967295.0}}}]) + self.assertEqual(pumas.makes(self.models['decider', 'decider-cpu']), []) + self.assertEqual(pumas.makes(self.models['listener', 'listener-cpu']), []) + + +# ------------------------------------------------------------- the fake + +class Endpoint(unittest.TestCase): + """A fake endpoint, and throwaway settings and projects home.""" + + def setUp(self): + directory = tempfile.TemporaryDirectory() + self.addCleanup(directory.cleanup) + self.temporary = Path(directory.name) + self.settings = self.temporary / 'settings.json' + self.home = self.temporary / 'home' + patcher = mock.patch.dict(os.environ, {local.SETTINGS_VARIABLE: str(self.settings), + local.HOME_VARIABLE: str(self.home)}) + patcher.start() + self.addCleanup(patcher.stop) + self.server, self.base, self.fake = fake_pumas_typed.start() + self.addCleanup(self.server.server_close) + self.addCleanup(self.server.shutdown) + self.fake['served_models'] = listing() + self.fake['advertise'] = '0.8.0' + + def posts(self): + return [body for body in self.fake['requests']] + + +class Observed(Endpoint): + """endpoint, set_endpoint and find_endpoints as pumas.py answers them, with no project.""" + + def test_endpoint_with_its_models_and_an_unavailable_capability(self): + seen = pumas.observe(self.base) + self.assertEqual((seen['address'], seen['answered'], seen['version'], seen['problem']), + (self.base, True, '0.8.0', None)) + by = {(model['model'], model['profile']): model for model in seen['models']} + self.assertEqual(len(by), 7) + writer = by['writer', 'writer-cpu'] + image = next(row for row in writer['capabilities'] if row['capability'] == 'image_generation') + self.assertEqual((image['available'], image['reason']), (False, 'unsupported_adapter')) + self.assertEqual([made['make'] for made in writer['makes']], ['text']) + self.assertEqual([made['make'] for made in by['painter', 'painter-gpu']['makes']], ['image']) + self.assertEqual(by['controlled-vision', 'vision-cpu']['modalities'], {'input': ['text', 'image'], + 'output': ['text']}) + self.assertEqual(self.posts(), []) + + def test_no_endpoint_and_one_that_does_not_answer(self): + self.assertEqual(pumas.observe(None), {'address': None, 'answered': False, 'version': None, 'models': [], + 'problem': pumas.NO_ENDPOINT}) + seen = pumas.observe(f'http://127.0.0.1:{closed_port()}') + self.assertFalse(seen['answered']) + self.assertIn('Pumas served models unavailable', seen['problem']) + with self.assertRaises(pumas.PumasError) as raised: + pumas.normalize('https://pumas.example.org') + self.assertEqual(raised.exception.code, 'invalid') + + def test_find_endpoints_with_the_scanner_patched(self): + port = int(self.base.rsplit(':', 1)[1]) + with mock.patch.object(gateway_discovery, 'listening_endpoints', + return_value=[('127.0.0.1', closed_port()), ('127.0.0.1', port)]): + found = pumas.find() + self.assertEqual(found, {'endpoints': [{'address': self.base, 'version': '0.8.0', 'component': 'pumas-rpc'}], + 'rejected': []}) + + +@unittest.skipUnless(DATABASE, 'TULDOK_DATABASE_URL is not set; database tests need a disposable cluster.') +class Project(Endpoint): + """A committed project, built for real by builds.execute against the fake, and a Service for it.""" + + def setUp(self): + super().setUp() + self.root = self.temporary / 'repository' + self.root.mkdir() + self.project_id = uuid.uuid4().hex + write_project(self.root, self.project_id) + self.folder = self.root / 'project' + self.git('init', '-q') + self.git('add', '-A') + self.git('commit', '-q', '-m', 'The project.') + self.addCleanup(store.drop_project, self.project_id) + self.service = Service(self.folder) + self.addCleanup(self.service.close) + + def git(self, *arguments): + return subprocess.run([*GIT, '-C', str(self.root), *arguments], check=True, capture_output=True, + timeout=60).stdout + + def call(self, name, arguments=None, actor=OWNER): + result = self.service.call(name, arguments or {}, actor) + json.dumps(result, allow_nan=False) + return result + + def refused(self, name, arguments=None, actor=OWNER): + with self.assertRaises(ProjectError) as raised: + self.service.call(name, arguments or {}, actor) + return raised.exception + + def set_endpoint(self): + return self.call('set_endpoint', {'address': self.base}) + + def build(self, *targets, ok=True): + with store.open_project(self.folder) as project: + made = plan.build_plan(project, list(targets)) + done = builds.execute(self.folder, made, confirm=lambda given: True) + self.assertEqual(done['ok'], ok, done) + return done + + def run_row(self, run_id): + with store.open_project(self.folder) as project: + return builds.run_details(project, run_id) + + def product(self, reference): + with store.open_project(self.folder) as project: + found = builds.products(project, reference) + return found[0] if found else None + + def stderr(self, item): + return (Path(item['directory']) / 'stderr.log').read_text(encoding='utf-8') + + +class EndpointSetting(Project): + + def test_set_cleared_and_refused_when_it_does_not_answer(self): + seen = self.set_endpoint() + self.assertEqual((seen['address'], seen['answered'], len(seen['models'])), (self.base, True, 7)) + self.assertEqual(json.loads(self.settings.read_text())['pumas_endpoint'], self.base) + self.assertEqual(self.call('endpoint', actor=EDITOR)['address'], self.base) + silent = f'http://127.0.0.1:{closed_port()}' + refused = self.refused('set_endpoint', {'address': silent}) + self.assertEqual(refused.code, 'unavailable') + self.assertTrue(str(refused).startswith(f'The Pumas endpoint at {silent} did not answer, so it was not set')) + self.assertEqual(json.loads(self.settings.read_text())['pumas_endpoint'], self.base) + self.assertEqual(self.refused('set_endpoint', {'address': 'https://pumas.example.org'}).code, 'invalid') + self.assertEqual(self.refused('set_endpoint', {'address': self.base}, actor=EDITOR).code, 'forbidden') + self.assertEqual(self.refused('find_endpoints', actor=EDITOR).code, 'forbidden') + cleared = self.call('set_endpoint', {'address': None}) + self.assertEqual((cleared['address'], cleared['answered']), (None, False)) + self.assertNotIn('pumas_endpoint', json.loads(self.settings.read_text())) + with store.open_project(self.folder) as project: + rows = project._execute('SELECT operation, outcome, detail FROM {schema}.activity ORDER BY at, id' + ).fetchall() + self.assertEqual([tuple(row) for row in rows], [('set_endpoint', 'done', 'set'), + ('set_endpoint', 'unavailable', refused.args[0][:400]), + ('set_endpoint', 'invalid', mock.ANY), + ('set_endpoint', 'done', 'cleared')]) + self.assertEqual(self.posts(), []) # asking what it serves is no model operation + + def test_find_endpoints_through_the_service(self): + port = int(self.base.rsplit(':', 1)[1]) + with mock.patch.object(gateway_discovery, 'listening_endpoints', return_value=[('127.0.0.1', port)]): + found = self.call('find_endpoints') + self.assertEqual(found['endpoints'], [{'address': self.base, 'version': '0.8.0', 'component': 'pumas-rpc'}]) + + def test_no_endpoint_set_the_plan_says_so(self): + plan_ = self.call('plan', {'targets': ['datasets/lines']}) + self.assertFalse(plan_['buildable']) + self.assertEqual(plan_['steps'][0]['blocked_by'][0]['reason'], plan.NO_ENDPOINT) + with store.open_project(self.folder) as project: + made = plan.build_plan(project, ['datasets/lines']) + with self.assertRaises(ProjectError) as raised: + builds.execute(self.folder, made, confirm=lambda given: True) + self.assertEqual(raised.exception.code, 'blocked') + # The setting goes away while a plan made with it is run: the step fails before it starts. + self.set_endpoint() + with store.open_project(self.folder) as project: + made = plan.build_plan(project, ['datasets/lines']) + self.assertTrue(made['buildable']) + self.call('set_endpoint', {'address': None}) + done = builds.execute(self.folder, made, confirm=lambda given: True) + self.assertFalse(done['ok']) + self.assertIn('No Pumas endpoint is set on this machine', done['steps'][0]['problem']) + self.assertEqual(self.posts(), []) + + +class Generated(Project): + """Datasets generated for real (D5a).""" + + def setUp(self): + super().setUp() + self.set_endpoint() + self.fake['respond'] = lambda body: text_result('made: ' + body['input']['text']) + + def test_a_text_dataset_with_its_records_hashes_and_origin(self): + done = self.build('datasets/lines') + [item] = done['steps'] + product = self.product('datasets/lines') + records = records_of(product['directory']) + self.assertEqual([record['id'] for record in records], ['g000001', 'g000002', 'g000003']) + first = records[0] + self.assertEqual(list(first), ['id', 'kind', 'text', 'sha256', 'bytes', 'rights', 'origin']) + text = 'made: Write line 1 of a short poem.' + self.assertEqual((first['kind'], first['text'], first['rights']), ('text', text, RIGHTS)) + self.assertEqual((first['sha256'], first['bytes']), (hashlib.sha256(text.encode()).hexdigest(), len(text))) + # The capability took no seed (text_generation options have none): null, and none was sent. + self.assertEqual(first['origin'], {'generated': {'model': 'writer', 'profile': 'writer-cpu', + 'capability': 'chat_generation', + 'prompt': 'Write line 1 of a short poem.', 'seed': None, + 'options': {'max_tokens': 64, 'temperature': 0.7}, + 'input': None}}) + posts = self.posts() + self.assertEqual(len(posts), 3) + self.assertEqual({key: posts[2][key] for key in ('model', 'profile', 'capability', 'input', 'output', + 'options', 'stream')}, + {'model': 'writer', 'profile': 'writer-cpu', 'capability': 'chat_generation', + 'input': {'kind': 'text', 'text': 'Write line 3 of a short poem.'}, 'output': 'text', + 'options': {'kind': 'text_generation', 'max_tokens': 64, 'temperature': 0.7}, + 'stream': False}) + row = self.run_row(item['run_id']) + self.assertEqual(row['endpoint'], {'address': self.base, 'version': '0.8.0'}) + self.assertEqual(row['argv'][3], 'generate') + self.assertIsNone(row['environment']) + listed = inside.records(inside.Product(product['run_id'], product['directory']), limit=10) + self.assertEqual((listed['total'], listed['problems'], listed['kinds']), (3, [], {'text': 3})) + self.assertEqual(listed['records'][0]['sha256'], first['sha256']) + stdout = (Path(item['directory']) / 'stdout.log').read_text(encoding='utf-8') + self.assertIn('"stage":"generate","completed":3,"total":3', stdout) + # Built again only when its definition changes. + self.assertEqual(self.call('plan', {'targets': ['datasets/lines']})['steps'][0]['action'], 'built') + # Nothing of the address is in the Git folder, nor in what was committed. + port = self.base.rsplit(':', 1)[1] + for path in self.root.rglob('*'): + if path.is_file() and '.git' not in path.parts: + data = path.read_bytes() + self.assertNotIn(self.base.encode(), data, path) + self.assertNotIn(f':{port}'.encode(), data, path) + self.assertNotIn(f'127.0.0.1:{port}'.encode(), self.git('log', '-p', '--all')) + + def test_an_image_dataset_from_a_dataset_of_prompts_with_per_and_seeds(self): + self.fake['respond'] = None + done = self.build('datasets/pictures') + self.assertEqual([item['reference'] for item in done['steps']], ['datasets/prompts', 'datasets/pictures']) + prompts = records_of(self.product('datasets/prompts')['directory']) + self.assertEqual([record['text'] for record in prompts], ['a red ball', 'a blue car']) + product = self.product('datasets/pictures') + records = records_of(product['directory']) + self.assertEqual([record['id'] for record in records], ['g000001', 'g000002', 'g000003', 'g000004']) + for number, record in enumerate(records, 1): + source = prompts[(number - 1) // 2] + self.assertEqual((record['kind'], record['path']), ('image', f'files/g{number:06d}.png')) + data = (Path(product['directory']) / record['path']).read_bytes() + self.assertEqual((record['sha256'], record['bytes']), (hashlib.sha256(data).hexdigest(), len(data))) + with Image.open(io.BytesIO(data)) as image: + self.assertEqual((image.format, image.size), ('PNG', (64, 32))) + self.assertEqual(record['origin'], {'generated': { + 'model': 'painter', 'profile': 'painter-gpu', 'capability': 'image_generation', + 'prompt': f'A picture of {source["text"]}, number {number}.', 'seed': 99 + number, + 'options': {'width': 64, 'height': 32}, 'input': source['id']}}) + self.assertEqual([body['options'] for body in self.posts()], + [{'kind': 'image_generation', 'width': 64, 'height': 32, 'seed': seed} + for seed in (100, 101, 102, 103)]) + listed = inside.records(inside.Product(product['run_id'], product['directory']), limit=10) + self.assertEqual((listed['kinds'], listed['problems']), ({'image': 4}, [])) + + def test_an_option_a_model_and_a_capability_fail_before_any_request(self): + for reference, expected in ( + ('datasets/too-long', "The option max_tokens 99999 is outside the bound 1 to 4096 that the endpoint " + "advertises for chat_generation."), + ('datasets/nobody', "The endpoint serves no model 'nobody'"), + ('datasets/no-paint', 'writer (writer-cpu) cannot make image now: image_generation is unavailable ' + '(unsupported_adapter).')): + with self.subTest(reference): + done = self.build(reference, ok=False) + self.assertEqual(done['steps'][0]['state'], 'failed') + stderr = self.stderr(done['steps'][0]) + self.assertIn('Nothing was asked: ', stderr) + self.assertIn(expected, stderr) + self.assertIsNone(self.product(reference)) + self.assertEqual(self.posts(), []) + + def test_not_admitted_is_asked_again_twice_then_fails(self): + self.fake['modes'] = ['not_admitted', 'not_admitted'] + done = self.build('datasets/one-line') + self.assertEqual(len(self.posts()), 3) + self.assertEqual(len({body['request_id'] for body in self.posts()}), 3) + self.assertEqual(len(records_of(self.product('datasets/one-line')['directory'])), 1) + self.assertIn('Item 1 was not admitted (capability_unavailable); asking again in 1 s.', + (Path(done['steps'][0]['directory']) / 'stdout.log').read_text(encoding='utf-8')) + self.fake['requests'].clear() + self.fake['modes'] = ['not_admitted'] * 3 + definition = self.folder / 'datasets' / 'one-line.json' + document = json.loads(definition.read_text()) + document['title'] = 'Generated again' + definition.write_text(json.dumps(document, indent=2) + '\n') + self.git('commit', '-q', '-am', 'Again.') + done = self.build('datasets/one-line', ok=False) + self.assertEqual(len(self.posts()), 3) + stderr = self.stderr(done['steps'][0]) + self.assertIn('Item 1 failed (asked 3 times): Pumas refused the request (capability_unavailable; not ' + 'admitted, no provider effect): fixture provider reason', stderr) + + def test_another_failure_fails_at_once_with_the_item_number(self): + self.fake['modes'] = ['success', 'unknown'] + done = self.build('datasets/three-lines', ok=False) + self.assertEqual(len(self.posts()), 2) + stderr = self.stderr(done['steps'][0]) + self.assertIn('Item 2 failed: Pumas reported provider_failure; provider outcome unknown, no automatic replay: ' + 'fixture provider reason', stderr) + # What was made stays in the failed run's directory, and is no product. + self.assertEqual(len(records_of(Path(done['steps'][0]['directory']) / 'output')), 1) + self.assertIsNone(self.product('datasets/three-lines')) + self.assertEqual(self.run_row(done['steps'][0]['run_id'])['endpoint'], + {'address': self.base, 'version': '0.8.0'}) + + +class Suggested(Project): + """suggest_annotation and suggestion_models, each row of section 4's table (D5b).""" + + def setUp(self): + super().setUp() + self.set_endpoint() + self.build('datasets/mixed') + self.ids = {record['kind']: record['id'] for record in records_of(self.product('datasets/mixed')['directory'])} + self.answers = {} + self.fake['respond'] = self.respond + + def respond(self, body): + if body['capability'] == 'decision': + return {'kind': 'decisions', 'answers': self.answers, 'input_tokens': 7} + return text_result(self.answer) + + def suggest(self, task, kind, model, profile=None, **extra): + arguments = {'task': task, 'record': self.ids[kind], 'model': model, **extra} + if profile: + arguments['profile'] = profile + return self.call('suggest_annotation', arguments, actor=EDITOR) + + def last(self): + return self.posts()[-1] + + def test_suggestion_models_offer_only_what_fits(self): + found = self.call('suggestion_models', {'task': 'captions'}, actor=EDITOR) + self.assertEqual((found['type'], found['address'], found['problem']), ('text', self.base, None)) + self.assertEqual(found['kinds'], { + 'audio': [{'model': 'listener', 'profile': 'listener-cpu', 'capability': 'audio_transcription'}], + 'image': [{'model': 'controlled-vision', 'profile': 'vision-cpu', 'capability': 'image_to_text'}], + 'pointcloud': [], + 'text': [{'model': 'controlled-vision', 'profile': 'vision-cpu', 'capability': 'chat_generation'}, + {'model': 'writer', 'profile': 'writer-cpu', 'capability': 'chat_generation'}]}) + kinds = self.call('suggestion_models', {'task': 'kinds'})['kinds'] + self.assertEqual([row['model'] for row in kinds['audio']], ['decider']) + self.assertEqual({row['model']: row['capability'] for row in kinds['image']}, + {'controlled-vision': 'image_to_text', 'decider': 'decision'}) + # No model fits: none offered. + self.assertEqual(self.call('suggestion_models', {'task': 'quality'})['kinds'], + {'audio': [], 'image': [], 'pointcloud': [], 'text': []}) + self.fake['served_models'] = {**listing(), 'models': [model for model in listing()['models'] + if model['model'] == 'writer']} + kinds = self.call('suggestion_models', {'task': 'kinds'})['kinds'] + self.assertEqual((kinds['audio'], kinds['image'], kinds['pointcloud']), ([], [], [])) + refused = self.refused('suggest_annotation', {'task': 'kinds', 'record': self.ids['audio'], 'model': 'writer'}) + self.assertEqual(refused.code, 'unavailable') + self.assertIn('cannot suggest a value of a class task for a audio record now', str(refused)) + self.call('set_endpoint', {'address': None}) + self.assertEqual(self.call('suggestion_models', {'task': 'kinds'})['problem'], pumas.NO_ENDPOINT) + self.assertEqual(self.refused('suggest_annotation', {'task': 'kinds', 'record': self.ids['text'], + 'model': 'writer'}).code, 'unavailable') + self.assertEqual(self.posts(), []) + + def test_a_caption_by_image_to_text(self): + self.answer = 'A blue rectangle.' + found = self.suggest('captions', 'image', 'controlled-vision', 'vision-cpu') + self.assertEqual(found, {'task': 'annotations/captions', 'record': self.ids['image'], + 'suggestion': {'value': 'A blue rectangle.', + 'from': {'model': 'controlled-vision', 'profile': 'vision-cpu', + 'capability': 'image_to_text'}}}) + body = self.last() + self.assertEqual((body['capability'], body['output'], body['profile']), ('image_to_text', 'text', 'vision-cpu')) + [message] = body['input']['messages'] + self.assertEqual(body['input']['kind'], 'image_messages') + self.assertEqual(message['content'][0], {'kind': 'text', 'text': pumas.DEFAULT_CAPTION}) + self.assertEqual(base64.b64decode(message['content'][1]['data_base64']), png()) + self.assertNotIn('options', body) + # The model must be named with its profile when it is served by two. + self.assertEqual(self.refused('suggest_annotation', {'task': 'captions', 'record': self.ids['image'], + 'model': 'controlled-vision'}).code, 'invalid') + + def test_a_transcript_by_audio_transcription(self): + self.answer = 'hello there' + found = self.suggest('captions', 'audio', 'listener') + self.assertEqual(found['suggestion'], {'value': 'hello there', 'from': { + 'model': 'listener', 'profile': 'listener-cpu', 'capability': 'audio_transcription'}}) + body = self.last() + clip = body['input'] + self.assertEqual({key: clip[key] for key in ('kind', 'encoding', 'sample_rate_hz', 'channels', 'sample_count')}, + {'kind': 'audio', 'encoding': 'pcm_s16le', 'sample_rate_hz': 16000, 'channels': 1, + 'sample_count': 4000}) + self.assertEqual(base64.b64decode(clip['data_base64']), b'\x01\x00' * 4000) + self.assertNotIn('options', body) + + def test_a_summary_by_chat(self): + self.answer = ' A dog chases a ball. ' + found = self.suggest('captions', 'text', 'writer', instruction='Summarize in one sentence.') + self.assertEqual(found['suggestion']['value'], 'A dog chases a ball.') + body = self.last() + self.assertEqual((body['capability'], body['input']['kind']), ('chat_generation', 'messages')) + self.assertEqual(body['input']['messages'], [ + {'role': 'system', 'content': 'Summarize in one sentence.'}, + {'role': 'user', 'content': 'A long text about a dog that runs after a red ball.\n'}]) + + def test_class_and_tags_by_a_decision_on_text_images_and_sounds(self): + self.answers = {'class': {'type': 'choice', 'choice': 'dog', 'probabilities': {'dog': 0.9}, + 'confidence': 0.9}} + for kind in ('text', 'image', 'audio'): + with self.subTest(kind): + found = self.suggest('kinds', kind, 'decider') + self.assertEqual(found['suggestion'], {'value': 'dog', 'from': { + 'model': 'decider', 'profile': 'decider-cpu', 'capability': 'decision'}}) + body = self.last() + self.assertEqual((body['output'], body['input']['kind']), ('decisions', 'decision')) + self.assertEqual(body['input']['questions'], {'class': { + 'type': 'choice', 'instructions': 'Choose the term that fits.', + 'criteria': {'cat': None, 'dog': None, 'car': None}}}) + text, image, sound = self.posts() + self.assertEqual(text['input']['state'], 'A long text about a dog that runs after a red ball.\n') + self.assertEqual(set(image['input']), {'kind', 'state', 'questions', 'images'}) + self.assertEqual(image['input']['images'], [{'encoding': 'png', + 'data_base64': base64.b64encode(png()).decode()}]) + self.assertEqual(set(sound['input']['audio'][0]), {'encoding', 'sample_rate_hz', 'channels', 'sample_count', + 'data_base64'}) + self.answers = {'t0': {'type': 'noul', 'noul': 0.9}, 't1': {'type': 'noul', 'noul': 0.2}, + 't2': {'type': 'noul', 'noul': 0.7}} + self.assertEqual(self.suggest('labels', 'image', 'decider')['suggestion']['value'], ['red', 'round']) + self.assertEqual(sorted(self.last()['input']['questions']), ['t0', 't1', 't2']) + self.assertEqual(self.last()['input']['questions']['t1'], + {'type': 'noul', 'instructions': 'Does the term "blue" apply?'}) + + def test_class_and_tags_by_chat_and_image_to_text_asked_for_terms_only(self): + self.answer = 'dog' + found = self.suggest('kinds', 'text', 'writer') + self.assertEqual(found['suggestion'], {'value': 'dog', 'from': { + 'model': 'writer', 'profile': 'writer-cpu', 'capability': 'chat_generation'}}) + self.assertIn('Answer with exactly one of these terms', self.last()['input']['messages'][0]['content']) + self.assertIn('\ncat\ndog\ncar', self.last()['input']['messages'][0]['content']) + self.answer = '"Cat."' + self.assertEqual(self.refused('suggest_annotation', {'task': 'kinds', 'record': self.ids['image'], + 'model': 'controlled-vision', 'profile': 'vision-cpu'} + ).code, 'unsuitable') + self.answer = 'cat.' + found = self.suggest('kinds', 'image', 'controlled-vision', 'vision-cpu') + self.assertEqual(found['suggestion']['value'], 'cat') + self.assertEqual(self.last()['capability'], 'image_to_text') + self.answer = 'round\nred' + self.assertEqual(self.suggest('labels', 'text', 'writer')['suggestion']['value'], ['red', 'round']) + self.answer = 'red, blue' + self.assertEqual(self.suggest('labels', 'image', 'controlled-vision', 'vision-cpu')['suggestion']['value'], + ['red', 'blue']) + + def test_an_answer_not_made_of_terms_is_refused_with_the_models_words(self): + self.answer = 'a fluffy animal, probably' + refused = self.refused('suggest_annotation', {'task': 'labels', 'record': self.ids['text'], 'model': 'writer'}, + actor=EDITOR) + self.assertEqual(refused.code, 'unsuitable') + self.assertIn("is not made of the task's terms", str(refused)) + self.assertIn('“a fluffy animal, probably”', str(refused)) + self.answers = {'class': {'type': 'choice', 'choice': 'horse', 'probabilities': {}, 'confidence': 0.5}} + refused = self.refused('suggest_annotation', {'task': 'kinds', 'record': self.ids['text'], 'model': 'decider'}) + self.assertEqual(refused.code, 'unsuitable') + self.assertIn("The term 'horse' is not in the vocabulary of the task.", str(refused)) + self.answers = {'class': {'type': 'choice'}} + self.assertEqual(self.refused('suggest_annotation', {'task': 'kinds', 'record': self.ids['text'], + 'model': 'decider'}).code, 'unsuitable') + self.answer = ' ' + self.assertEqual(self.refused('suggest_annotation', {'task': 'captions', 'record': self.ids['text'], + 'model': 'writer'}).code, 'unsuitable') + # A refusal of the endpoint is the endpoint's reason. + self.fake['modes'] = ['not_admitted'] + refused = self.refused('suggest_annotation', {'task': 'captions', 'record': self.ids['text'], + 'model': 'writer'}) + self.assertEqual(refused.code, 'unavailable') + self.assertIn('capability_unavailable', str(refused)) + # Nothing is stored by asking. + with store.open_project(self.folder) as project: + self.assertEqual(project._execute('SELECT count(*) FROM {schema}.activity').fetchone()[0], 1) + + def test_a_kept_suggestion_names_the_model_in_git(self): + self.answer = 'A blue rectangle.' + found = self.suggest('captions', 'image', 'controlled-vision', 'vision-cpu')['suggestion'] + self.call('set_annotation', {'task': 'captions', 'from': found['from'], + 'items': [{'record': self.ids['image'], 'state': 'accepted', + 'value': found['value'] + ' On white.'}]}, actor=EDITOR) + self.call('save') + [line] = (self.folder / 'annotations' / 'captions.jsonl').read_text(encoding='utf-8').splitlines() + kept = json.loads(line) + self.assertEqual((kept['value'], kept['by'], kept['from']), + ('A blue rectangle. On white.', 'agent:helper', + {'model': 'controlled-vision', 'profile': 'vision-cpu', 'capability': 'image_to_text'})) + self.assertEqual(annotations.read(line.encode() + b'\n', 'text', []).problems, []) + + +class StepAlone(Endpoint): + """generate_records as a function on directories: refusals that need no project.""" + + def setUp(self): + super().setUp() + self.output = self.temporary / 'out' + self.output.mkdir() + self.said = [] + + def generate(self, **settings): + return steps.generate_records({'rights': RIGHTS, **settings}, str(self.output), endpoint=self.base, + out=self.said.append, pauses=(0, 0)) + + def test_a_seed_past_the_bound_and_a_long_prompt_fail_before_any_request(self): + with self.assertRaises(steps.StepError) as raised: + self.generate(make='image', model='painter', prompt='x', count=3, seed=4294967294, + options={'width': 8, 'height': 8}) + self.assertIn('seed 4294967296 is outside the bound', str(raised.exception)) + with self.assertRaises(steps.StepError) as raised: + self.generate(make='image', model='painter', prompt='x' * 4001, count=1, options={'width': 8, 'height': 8}) + self.assertIn("The prompt's input_characters 4001 is outside the bound 1 to 4000", str(raised.exception)) + with self.assertRaises(steps.StepError) as raised: + self.generate(make='image', model='painter', prompt='x', count=1, options={'width': 8}) + self.assertIn('image_generation needs the options width and height.', str(raised.exception)) + with self.assertRaises(steps.StepError) as raised: + self.generate(make='text', model='writer', prompt='x', count=1, options={'width': 8}) + self.assertIn("chat_generation takes the options max_tokens, temperature, top_p, not 'width'.", + str(raised.exception)) + self.assertEqual(self.posts(), []) + + def test_a_long_text_is_written_as_a_file(self): + self.fake['respond'] = lambda body: text_result('y' * 70000) + counts = self.generate(make='text', model='writer', prompt='x', count=1) + self.assertEqual(counts['in_files'], 1) + [record] = records_of(self.output) + self.assertEqual((record['kind'], record['path'], record['bytes']), ('text', 'files/g000001.txt', 70000)) + self.assertEqual((self.output / 'files' / 'g000001.txt').read_text(), 'y' * 70000) + + +if __name__ == '__main__': + unittest.main() diff --git a/tests/test_tuldok_project_service.py b/tests/test_tuldok_project_service.py index d6b5d726..65eeb02b 100644 --- a/tests/test_tuldok_project_service.py +++ b/tests/test_tuldok_project_service.py @@ -48,7 +48,7 @@ class Table(unittest.TestCase): def test_every_operation_is_declared_once(self): names = [operation.name for operation in operations.OPERATIONS] - self.assertEqual(len(names), 54) # the rows of spec-m7.md section 2, of section 2 of spec-w1.md and spec-w3.md, of section 3 of spec-d1.md and spec-d2.md, and of section 5 of spec-d4.md + self.assertEqual(len(names), 59) # the rows of spec-m7.md section 2, of section 2 of spec-w1.md and spec-w3.md, of section 3 of spec-d1.md and spec-d2.md, of section 5 of spec-d4.md, and of sections 2 and 4 of spec-d5.md self.assertEqual(len(set(names)), len(names)) for name in REQUEST_OPERATIONS: self.assertIsNotNone(operations.by_name(name)) @@ -79,9 +79,11 @@ def test_mutations_and_owner_rows(self): self.assertEqual(mutations, {'set_definition', 'remove_definition', 'revert_definition', 'save', 'resolve_conflict', 'import_values', 'check_environment', 'connect_environment', 'disconnect_environment', 'request_build', 'approve_build', 'decline_build', - 'cancel_build', 'cancel_run', 'stop_run', 'set_annotation', 'revert_annotations'}) + 'cancel_build', 'cancel_run', 'stop_run', 'set_annotation', 'revert_annotations', + 'set_endpoint'}) owner = {operation.name for operation in operations.OPERATIONS if operation.who == 'owner'} - self.assertEqual(owner, {'connect_environment', 'disconnect_environment', 'approve_build', 'decline_build'}) + self.assertEqual(owner, {'connect_environment', 'disconnect_environment', 'approve_build', 'decline_build', + 'set_endpoint', 'find_endpoints'}) def test_error_status(self): self.assertEqual([operations.error_status(code) for code in @@ -214,6 +216,8 @@ def test_every_read(self): 'array_tiles': {'run': run_id, 'path': 'weights.npy'}, 'annotation_tasks': {}, 'annotated_records': {'task': 'none-here'}, 'annotation': {'task': 'none-here', 'record': 'r1'}, + 'endpoint': {}, 'find_endpoints': {}, 'suggestion_models': {'task': 'none-here'}, + 'suggest_annotation': {'task': 'none-here', 'record': 'r1', 'model': 'm'}, } reads = [operation for operation in operations.OPERATIONS if not operation.mutation] arguments['build_requests'] = {'state': 'queued', 'limit': 5} @@ -230,6 +234,14 @@ def test_every_read(self): if operation.name == 'weights_compare': # fit-a's weights are JSON; test_tuldok_project_weights self.assertEqual(self.refused(operation.name, arguments[operation.name]).code, 'unsupported') continue + if operation.name == 'find_endpoints': # the owner's, and it scans this machine: tested with the + # scanner patched in test_tuldok_project_pumas + self.assertEqual(self.refused(operation.name, {}, actor=agent('inspect')).code, 'forbidden') + continue + if operation.name in ('suggestion_models', 'suggest_annotation'): # no task here; asked in + # test_tuldok_project_pumas + self.assertEqual(self.refused(operation.name, arguments[operation.name]).code, 'not-found') + continue if operation.name in ('annotated_records', 'annotation'): # this fixture has no task; read in # test_tuldok_project_annotation_rows self.assertEqual(self.refused(operation.name, arguments[operation.name]).code, 'not-found') diff --git a/tuldok_project/annotation_records.py b/tuldok_project/annotation_records.py index c7f7f2b1..9bac2002 100644 --- a/tuldok_project/annotation_records.py +++ b/tuldok_project/annotation_records.py @@ -12,6 +12,7 @@ vocabulary, the record's kind and what is cheap to know of it: an image's size (from its first bytes), a text's length (when its file is at most inside.COUNT_TEXT_BYTES) and a WAVE sound's length (from its header). +content reads one record whole for a suggestion (spec-d5.md section 4). """ import codecs import hashlib @@ -188,6 +189,29 @@ def facts(product, record, task): return found +# ----------------------------------------------------- what a model is sent + +def content(product, record, limit): + """A record's content for a suggestion (spec-d5.md section 4): {kind, text} or {kind, data} (its bytes). + + A record over limit bytes is refused invalid; one that cannot be read, not-found. + """ + if record['path'] is None: + return {'kind': record['kind'], 'text': record['text'] or ''} + try: + place = inside_archive.locate(product.root, record['path']) + size = place.size or 0 + if size > limit: + raise ProjectError(f'The record {record["id"]!r} is {size:,} bytes; at most {limit:,} are sent to a model.', + 'invalid') + data = place.head(size) + except inside.DAMAGED: + raise ProjectError(f'The record {record["id"]!r} cannot be read.', 'not-found') from None + if record['kind'] == 'text': + return {'kind': 'text', 'text': codecs.decode(data, 'utf-8', 'replace')} + return {'kind': record['kind'], 'data': data} + + # ------------------------------------------------------------------ the items def by_of(actor): diff --git a/tuldok_project/builds.py b/tuldok_project/builds.py index 91c68b13..7c575b8e 100644 --- a/tuldok_project/builds.py +++ b/tuldok_project/builds.py @@ -21,7 +21,11 @@ names a step Tuldok provides (spec-d4.md section 6) runs steps.py with Tuldok's own interpreter and code, no environment; a freeze's run records the line files of its tasks as it read them from the commit, and the product is -out of date when one of them differs at HEAD (_LineFiles). +out of date when one of them differs at HEAD (_LineFiles). A generate is +given the machine's Pumas endpoint (local.pumas_endpoint; none set is a +problem before it runs), and its run keeps the address and the version the +endpoint reported, in the column endpoint, never in the project folder +(spec-d5.md section 3). What a person needs while and after a build runs (sections 7 and 8): a run is named by its id or an unambiguous prefix of it (find_run); run_details reads @@ -84,6 +88,8 @@ TULDOK_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) STEP_TASKS_FILE = 'tasks.json' # /tasks.json: what a freeze is told of its tasks STEP_LINES = 'annotations' # /annotations/.jsonl: the line files a freeze read +STEP_REPORT = 'endpoint.json' # /endpoint.json: the endpoint a generate asked, and its version +REPORT_LIMIT = 4096 TABLES = ( '''CREATE TABLE IF NOT EXISTS {schema}.plans ( @@ -106,6 +112,8 @@ 'CREATE INDEX IF NOT EXISTS runs_reference ON {schema}.runs (reference, subject, queued_at)', # A freeze's run records each task's line file as it read it: {task: {file, sha256, blob}} (spec-d4.md section 6). 'ALTER TABLE {schema}.runs ADD COLUMN IF NOT EXISTS annotations jsonb', + # A generate's run keeps the Pumas endpoint it asked: {address, version} (spec-d5.md section 3). + 'ALTER TABLE {schema}.runs ADD COLUMN IF NOT EXISTS endpoint jsonb', '''CREATE TABLE IF NOT EXISTS {schema}.products ( run_id text PRIMARY KEY, reference text NOT NULL, subject text NOT NULL DEFAULT '', @@ -120,7 +128,7 @@ _RUN_COLUMNS = ('id', 'reference', 'subject', 'plan_id', 'state', 'scratch', 'commit', 'inputs', 'environment', 'argv', 'directory', 'owner_pid', 'owner_boot', 'queued_at', 'started_at', 'finished_at', 'exit_status', 'seconds', 'bytes', 'strays', 'problem') -_DETAIL_COLUMNS = _RUN_COLUMNS + ('definition', 'settings', 'env', 'annotations') +_DETAIL_COLUMNS = _RUN_COLUMNS + ('definition', 'settings', 'env', 'annotations', 'endpoint') def _q(schema, template): @@ -710,7 +718,7 @@ def _resolve(self, project, reference, subject, *, estimate=False): prepared = {'id': run_id, 'reference': reference, 'subject': subject['name'] if subject else '', 'definition': text, 'settings': None, 'environment': environment_record, 'directory': run_directory, 'argv': list(command), 'env': {}, - 'problem': None, 'skipped': False, 'annotations': None, 'files': {}} + 'problem': None, 'skipped': False, 'annotations': None, 'endpoint': None, 'files': {}} try: if not command: raise StepProblem(f'{reference} has no run.estimate.command.' if estimate else @@ -816,8 +824,10 @@ def _step_argv(self, project, reference, run, step, values, prepared): argv = [sys.executable, '-m', STEPS_MODULE, step, values['settings'], values['output']] if step == 'import': return argv + ['--code', self.code.code_root] + if step == 'generate': + return argv + self._generate_argv(project, run, values, prepared) if step != 'freeze': - raise StepProblem(f'Tuldok provides no step {step!r}; use import or freeze.') + raise StepProblem(f'Tuldok provides no step {step!r}; use import, freeze or generate.') inputs = _declared_inputs({'run': run}) used = inputs.get('records', (None, None))[0] if 'inputs.records' not in values or used is None: @@ -853,6 +863,27 @@ def _step_argv(self, project, reference, run, step, values, prepared): prepared['annotations'] = read return argv + ['--records', values['inputs.records'], '--tasks', tasks_file] + def _generate_argv(self, project, run, values, prepared): + """The arguments of a generate after its settings and output: the machine's endpoint, the report, the input.""" + try: + address = local.pumas_endpoint() + except local.SettingsError as exc: + raise StepProblem(str(exc)) from None + if address is None: + raise StepProblem('No Pumas endpoint is set on this machine, so nothing can be generated; the owner sets ' + 'one, then build again.') + prepared['endpoint'] = {'address': address, 'version': None} + argv = ['--endpoint', address, '--report', os.path.join(prepared['directory'], STEP_REPORT)] + used = _declared_inputs({'run': run}).get('prompts', (None, None))[0] + if used is not None: + row = project._execute(f'SELECT document FROM {{schema}}.definitions WHERE NOT removed AND ' + f'{store._REFERENCE_SQL} = %s', (used,)).fetchone() + if row is not None and isinstance(row[0], dict) and row[0].get('view') is not None: + raise StepProblem(f'Its input prompts ({used}) is shown through a view, and generate reads only a ' + "product's records.jsonl or its files.") + argv += ['--records', values['inputs.prompts']] + return argv + def _line_file(self, project, file): """(Git blob id or None, bytes or None) of a line file, relative to the project folder, as this build reads it. @@ -903,16 +934,17 @@ def _check_expected(self, project, reference, text, run, subject): def _insert(self, project, prepared, state): project._execute('''INSERT INTO {schema}.runs (id, reference, subject, plan_id, state, scratch, commit, definition, settings, inputs, environment, argv, env, directory, owner_pid, - owner_boot, queued_at, started_at, finished_at, problem, annotations) + owner_boot, queued_at, started_at, finished_at, problem, annotations, endpoint) VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, now(), CASE WHEN %s = 'running' THEN now() END, - CASE WHEN %s = 'running' THEN NULL ELSE now() END, %s, %s)''', + CASE WHEN %s = 'running' THEN NULL ELSE now() END, %s, %s, %s)''', (prepared['id'], prepared['reference'], prepared['subject'], self.plan_id, state, self.code.scratch, self.code.commit, prepared['definition'], prepared['settings'], Jsonb(prepared['inputs']), Jsonb(prepared['environment']) if prepared['environment'] else None, Jsonb(prepared['argv']), Jsonb(prepared['env']), prepared['directory'], os.getpid(), self.boot, state, state, prepared['problem'], - Jsonb(prepared['annotations']) if prepared['annotations'] is not None else None)) + Jsonb(prepared['annotations']) if prepared['annotations'] is not None else None, + Jsonb(prepared['endpoint']) if prepared['endpoint'] is not None else None)) # ------------------------------------------------------------------- run @@ -993,9 +1025,26 @@ def _finish(self, project, prepared, outcome, problem): seconds = %s, bytes = %s, strays = %s, problem = %s WHERE id = %s''', (state, outcome.exit_status, outcome.seconds, outcome.bytes, outcome.strays, problem, prepared['id'])) + if prepared.get('endpoint') is not None: + project._execute('UPDATE {schema}.runs SET endpoint = %s WHERE id = %s', + (Jsonb(_endpoint_report(prepared)), prepared['id'])) return state, problem +def _endpoint_report(prepared): + """{address, version} of the endpoint a generate asked: the version as its report file says, when it does.""" + found = dict(prepared['endpoint']) + try: + with open(os.path.join(prepared['directory'], STEP_REPORT), 'rb') as handle: + reported = json.loads(handle.read(REPORT_LIMIT + 1)[:REPORT_LIMIT]) + except (OSError, ValueError): + return found + version = reported.get('version') if isinstance(reported, dict) else None + if isinstance(version, str) and 0 < len(version) <= 128 and version.isprintable(): + found['version'] = version + return found + + def outputs_path(outputs): return next((item['path'] for item in outputs.values() if item['role'] == 'results'), '') diff --git a/tuldok_project/check.py b/tuldok_project/check.py index ce0b76a8..a2cef8c2 100644 --- a/tuldok_project/check.py +++ b/tuldok_project/check.py @@ -11,13 +11,15 @@ compared_with, and map.chart, each annotations/.jsonl against its task (spec-d4.md section 2; the rules of a line are annotations.py's), and the settings, inputs and tasks of a dataset whose run names a step Tuldok -provides (section 6). +provides (section 6; generate is spec-d5.md section 3). Problems are collected, never raised, so one bad file never hides another. """ from dataclasses import dataclass, field +import math import os +import re -from . import annotations, documents, folder as folder_reader, graph, results +from . import annotations, documents, folder as folder_reader, graph, results, steps from .documents import Problem _SEVERITY_ORDER = {'error': 0, 'warning': 1} @@ -130,8 +132,16 @@ def _check_view(view, path, add): # The settings of each step Tuldok provides (spec-d4.md section 6): {member: required}. STEP_SETTINGS = {'import': {'source': True, 'pattern': False, 'kind': False, 'rights': True, 'lines': False}, - 'freeze': {'seed': True, 'shares': True, 'include': False}} + 'freeze': {'seed': True, 'shares': True, 'include': False}, + 'generate': {'make': True, 'model': True, 'profile': False, 'prompt': True, 'count': False, + 'per': False, 'seed': False, 'options': False, 'rights': True}} SEED_LIMIT = 2 ** 63 +GENERATE_SEED_LIMIT = 2 ** 32 # a seed Pumas takes is unsigned 32-bit +PROMPT_LIMIT = 16_000 # characters of a generate prompt +PER_LIMIT = 1000 +OPTIONS_LIMIT = 32 +_OPTION_NAME = re.compile(r'^[a-z][a-z0-9_]{0,63}$') +_PROFILE = re.compile(r'^[A-Za-z0-9_.-]{1,128}$') SHARES_LIMIT = 16 SHARE_LIMIT = 1_000_000 RIGHTS_LIMIT = 1000 @@ -157,12 +167,14 @@ def _check_step(run, path, add): f'Add the required setting {key!r} of the step {step}.') settings = settings if isinstance(settings, dict) else {} where = lambda key: documents.pointer('run', 'settings', key) # noqa: E731 + if step in ('import', 'generate') and 'annotations' in run: + add('error', path, '/run/annotations', 'Only the step freeze reads annotations; remove annotations.') if step == 'import': _check_import(settings, path, where, add) if 'inputs' in run: add('error', path, '/run/inputs', 'The step import reads files, not other products; remove inputs.') - if 'annotations' in run: - add('error', path, '/run/annotations', 'Only the step freeze reads annotations; remove annotations.') + elif step == 'generate': + _check_generate(run, settings, path, where, add) else: _check_freeze(run, settings, path, where, add) @@ -195,6 +207,78 @@ def _check_import(settings, path, where, add): add('error', path, where('lines'), 'lines must be true or false.') +def _check_generate(run, settings, path, where, add): + """The settings and the one optional input (prompts) of the step generate (spec-d5.md section 3).""" + inputs = run.get('inputs') + with_input = 'inputs' in run + if with_input and (not isinstance(inputs, dict) or set(inputs) != {'prompts'} + or not isinstance(inputs['prompts'], str) or not inputs['prompts'].startswith('datasets/')): + add('error', path, '/run/inputs', 'The step generate takes at most one input, prompts, naming a dataset: ' + '"inputs": {"prompts": "datasets/"}.') + if 'make' in settings and settings['make'] not in steps.MAKES: + add('error', path, where('make'), 'make must be ' + ' or '.join(steps.MAKES) + '.') + model = settings.get('model') + if 'model' in settings and not (isinstance(model, str) and model and model == model.strip() + and len(model.encode('utf-8', 'surrogatepass')) <= 256 + and not any(ord(char) < 32 or ord(char) == 127 for char in model)): + add('error', path, where('model'), 'model must be the alias a Pumas endpoint serves: 1 to 256 bytes, with no ' + 'spaces around it and no control characters.') + if 'profile' in settings and not (isinstance(settings['profile'], str) and _PROFILE.match(settings['profile'])): + add('error', path, where('profile'), 'profile must be a Pumas profile: 1 to 128 of A-Z a-z 0-9 . _ -.') + prompt = settings.get('prompt') + if 'prompt' in settings: + if not isinstance(prompt, str) or not prompt.strip() or len(prompt) > PROMPT_LIMIT: + add('error', path, where('prompt'), f'prompt must be a request of 1 to {PROMPT_LIMIT:,} characters.') + else: + allowed = ('n', 'text') if with_input else ('n',) + try: + names = [text for part, text in steps.prompt_parts(prompt) if part == 'name'] + except ValueError as exc: + add('error', path, where('prompt'), f'The prompt {exc}.') + else: + for name in dict.fromkeys(name for name in names if name not in allowed): + add('error', path, where('prompt'), f'The prompt uses {{{name}}}; it may use ' + + ' and '.join(f'{{{known}}}' for known in allowed) + + ('' if with_input else ' ({text} needs an input of prompts)') + '.') + count, per = settings.get('count'), settings.get('per') + if with_input: + if 'count' in settings: + add('error', path, where('count'), 'With an input, one item is made for each of its text records ' + '(times per); remove count.') + if 'per' in settings and (type(per) is not int or not 1 <= per <= PER_LIMIT): + add('error', path, where('per'), f'per must be a whole number from 1 to {PER_LIMIT:,}.') + else: + if 'count' not in settings: + add('error', path, where('count'), 'Add the required setting \'count\' of the step generate: how many to ' + 'make, without an input of prompts.') + elif type(count) is not int or not 1 <= count <= steps.GENERATE_LIMIT: + add('error', path, where('count'), f'count must be a whole number from 1 to {steps.GENERATE_LIMIT:,}.') + if 'per' in settings: + add('error', path, where('per'), 'per goes with an input of prompts; remove it or add the input.') + seed = settings.get('seed') + if 'seed' in settings and (type(seed) is not int or not 0 <= seed < GENERATE_SEED_LIMIT): + add('error', path, where('seed'), 'The seed must be a whole number from 0 to 4,294,967,295.') + options = settings.get('options') + if 'options' in settings: + if not isinstance(options, dict) or len(options) > OPTIONS_LIMIT: + add('error', path, where('options'), f'options must be an object of at most {OPTIONS_LIMIT} options of ' + 'the capability, such as {"max_tokens": 256}.') + else: + for name, value in options.items(): + pointer = documents.pointer('run', 'settings', 'options', name) + if name == 'seed': + add('error', path, pointer, 'The seed is the setting seed, not an option; move it there.') + elif not _OPTION_NAME.match(name): + add('error', path, pointer, f'The option name {name!r} must be 1 to 64 of a-z 0-9 _, starting ' + 'with a letter.') + elif isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value): + add('error', path, pointer, f'The option {name} must be a number.') + rights = settings.get('rights') + if 'rights' in settings and (not isinstance(rights, str) or not rights.strip() or len(rights) > RIGHTS_LIMIT): + add('error', path, where('rights'), f'rights must be a sentence of 1 to {RIGHTS_LIMIT:,} characters on ' + 'what may be done with what is made.') + + def _check_freeze(run, settings, path, where, add): inputs = run.get('inputs') if not isinstance(inputs, dict) or set(inputs) != {'records'} or not isinstance(inputs['records'], str) \ diff --git a/tuldok_project/local.py b/tuldok_project/local.py index 5b64511a..4547b3f9 100644 --- a/tuldok_project/local.py +++ b/tuldok_project/local.py @@ -9,6 +9,9 @@ cannot be read or is not valid raises SettingsError: it never falls back to the default. Nothing in a local home is part of the project folder. Environments that Tuldok installs go to /environments//. +The settings file also holds pumas_endpoint, the address of the Pumas endpoint +this machine uses (spec-d5.md section 2), or nothing; it is never part of a +project folder. pumas.py checks an address before set_pumas_endpoint keeps it. Working out a path never creates anything; a directory is made only when a caller asks for it with create=True, or by set_project_home. """ @@ -26,7 +29,8 @@ DEFAULT_SETTINGS = os.path.join('~', '.local', 'share', 'tuldok', 'settings.json') SETTINGS_FORMAT = 'tuldok_settings_v1' SETTINGS_LIMIT = 64 * 1024 -SETTINGS_FIELDS = ('format', 'project_home') +SETTINGS_FIELDS = ('format', 'project_home', 'pumas_endpoint') +ENDPOINT_LIMIT = 2048 # characters of pumas_endpoint ENVIRONMENTS = 'environments' _PROJECT_DIRECTORY = re.compile(r'^[a-f0-9]{32}$') @@ -64,9 +68,61 @@ def read_settings(): home = settings.get('project_home') if 'project_home' in settings and not (isinstance(home, str) and os.path.isabs(home) and '\x00' not in home): raise SettingsError(f'The settings file {path} is not valid: its project_home must be an absolute path.') + if 'pumas_endpoint' in settings and endpoint_problem(settings['pumas_endpoint']): + raise SettingsError(f'The settings file {path} is not valid: its pumas_endpoint ' + f'{endpoint_problem(settings["pumas_endpoint"])}.') return settings +def endpoint_problem(value): + """Why value cannot be a pumas_endpoint (an http or https address), or None.""" + if not isinstance(value, str) or not 1 <= len(value) <= ENDPOINT_LIMIT: + return f'must be an address of 1 to {ENDPOINT_LIMIT} characters' + if not value.startswith(('http://', 'https://')) or any(char.isspace() or ord(char) < 32 for char in value): + return 'must be an http or https address without spaces' + return None + + +def pumas_endpoint(): + """The Pumas endpoint this machine uses (pumas_endpoint of the settings file), or None; raises SettingsError.""" + return read_settings().get('pumas_endpoint') + + +def set_pumas_endpoint(address): + """Keep address as pumas_endpoint in the settings file, or remove the key when address is None. + + The caller has checked the address (pumas.py asks it once); a value that + is not an http or https address raises ValueError. A settings file that is + not valid is not replaced (SettingsError). Returns the settings file's path. + """ + if address is not None and endpoint_problem(address): + raise ValueError(f'{address!r} {endpoint_problem(address)}.') + settings = {key: value for key, value in read_settings().items() if key != 'pumas_endpoint'} + if address is not None: + settings['pumas_endpoint'] = address + return _write_settings(settings) + + +def _write_settings(settings): + """Write settings (with its format) through a temporary file renamed into place, mode 0600; the file's path.""" + file = settings_path() + os.makedirs(os.path.dirname(file), exist_ok=True) + text = json.dumps({'format': SETTINGS_FORMAT, **settings}, indent=2, ensure_ascii=False) + '\n' + descriptor, temporary = tempfile.mkstemp(prefix='.settings.', suffix='.tmp', dir=os.path.dirname(file)) + try: + with os.fdopen(descriptor, 'w', encoding='utf-8') as handle: + os.fchmod(handle.fileno(), 0o600) + handle.write(text) + os.replace(temporary, file) + except BaseException: + try: + os.unlink(temporary) + except OSError: + pass + raise + return file + + def projects_home_source(): """(the directory that holds every project's local home, where it came from: environment, settings or default).""" configured = os.environ.get(HOME_VARIABLE) @@ -127,21 +183,7 @@ def set_project_home(path): raise ValueError(f'{path} cannot be made: {exc.strerror}.') from None if not os.path.isdir(path) or not os.access(path, os.W_OK | os.X_OK): raise ValueError(f'{path} is not a directory this user can write.') - file = settings_path() - os.makedirs(os.path.dirname(file), exist_ok=True) - text = json.dumps({**settings, 'format': SETTINGS_FORMAT, 'project_home': path}, indent=2, ensure_ascii=False) + '\n' - descriptor, temporary = tempfile.mkstemp(prefix='.settings.', suffix='.tmp', dir=os.path.dirname(file)) - try: - with os.fdopen(descriptor, 'w', encoding='utf-8') as handle: - os.fchmod(handle.fileno(), 0o600) - handle.write(text) - os.replace(temporary, file) - except BaseException: - try: - os.unlink(temporary) - except OSError: - pass - raise + file = _write_settings({**settings, 'project_home': path}) return {'project_home': path, 'settings': file, 'before': before, 'before_projects': project_directories(before) if before != path else 0, 'overridden': bool(os.environ.get(HOME_VARIABLE))} diff --git a/tuldok_project/operations.py b/tuldok_project/operations.py index b2b27fb7..68b19015 100644 --- a/tuldok_project/operations.py +++ b/tuldok_project/operations.py @@ -5,8 +5,10 @@ section 2 of spec-w3.md (draft_branch, revert_definition), the five of section 3 of spec-d1.md (records, record, inside, array_slice, array_summary), the three of section 3 of spec-d2.md (weights, weights_compare, -array_tiles) and the five of section 5 of spec-d4.md (annotation_tasks, -annotated_records, annotation, set_annotation, revert_annotations). +array_tiles), the five of section 5 of spec-d4.md (annotation_tasks, +annotated_records, annotation, set_annotation, revert_annotations) and the +five of sections 2 and 4 of spec-d5.md (endpoint, set_endpoint, +find_endpoints, suggestion_models, suggest_annotation). Each Operation names one operation project., the rule its caller must satisfy (who), whether it changes anything (mutation), a closed JSON Schema of its arguments and the result keys that are always present. service.py checks @@ -27,6 +29,8 @@ ANNOTATION_COUNTS = ('unannotated', 'draft', 'accepted', 'needs-work', 'rejected', 'stale', 'invalid') ANNOTATION_ITEMS = 200 # items of one set_annotation REVERT_RECORDS = 10_000 # records named by one revert_annotations +ENDPOINT_CHARACTERS = 2048 # an address of a Pumas endpoint (local.ENDPOINT_LIMIT) +INSTRUCTION_CHARACTERS = 4000 @dataclass(frozen=True) @@ -97,6 +101,7 @@ def _arguments(required=(), **properties): SAVE = ('written', 'deleted', 'results_written', 'results_deleted', 'annotations_written', 'annotations_deleted') CANCEL_RUN = ('id', 'reference', 'subject', 'state', 'cancel_file', 'already_asked') STOP_RUN = ('id', 'reference', 'subject', 'was', 'state', 'killed', 'remaining', 'marked_unknown') +ENDPOINT = ('address', 'answered', 'version', 'models', 'problem') OPERATIONS = ( @@ -226,6 +231,16 @@ def _arguments(required=(), **properties): _arguments(['task'], task=_NAME, records={'type': 'array', 'items': _RECORD_ID, 'minItems': 1, 'maxItems': REVERT_RECORDS}), ('task', 'reverted')), + Operation('suggestion_models', "List, for each kind of record in the product of a task's dataset, the models " + 'the Pumas endpoint serves that can suggest a value of the task.', 'inspect', False, + _arguments(['task'], task=_NAME), ('task', 'type', 'address', 'kinds', 'problem')), + Operation('suggest_annotation', 'Ask a model the Pumas endpoint serves for a value of a task for one record; ' + 'nothing is stored, and an answer that is not a value of the task is refused.', 'edit', False, + _arguments(['task', 'record', 'model'], task=_NAME, record=_RECORD_ID, + model={'type': 'string', 'minLength': 1, 'maxLength': 256}, + profile={'type': 'string', 'minLength': 1, 'maxLength': 128}, + instruction={'type': 'string', 'minLength': 1, 'maxLength': INSTRUCTION_CHARACTERS}), + ('task', 'record', 'suggestion')), Operation('set_definition', "Check a definition's text and keep it as an unsaved edit.", 'edit', True, _arguments(['reference', 'text'], reference=_REFERENCE, text=_TEXT), DEFINITION), Operation('remove_definition', 'Mark a definition that nothing uses as removed, until the project is saved.', @@ -248,6 +263,15 @@ def _arguments(required=(), **properties): interpreter={'type': 'string', 'minLength': 1, 'maxLength': 4096}), ENVIRONMENT), Operation('disconnect_environment', "Forget an environment's recorded interpreter on this machine; nothing is " 'deleted.', 'owner', True, _arguments(['reference'], reference=_REFERENCE), ('disconnected',)), + Operation('endpoint', 'Read the Pumas endpoint this machine uses: its address, whether it answered, and each ' + 'model and profile it serves with its modalities, its capabilities and what Tuldok can make with it.', + 'inspect', False, _arguments(), ENDPOINT), + Operation('set_endpoint', 'Set the Pumas endpoint this machine uses once it has answered what it serves, or ' + 'clear it with null.', 'owner', True, + _arguments(['address'], address={'type': ['string', 'null'], 'minLength': 1, + 'maxLength': ENDPOINT_CHARACTERS}), ENDPOINT), + Operation('find_endpoints', 'List the Pumas endpoints advertising themselves on this machine, for the owner to ' + 'pick from.', 'owner', False, _arguments(), ('endpoints', 'rejected')), Operation('request_build', "Ask for a build of the targets: the owner's request is queued, an agent's waits for " "the owner's approval (read build_request for its state), and a queued request not started by " 'its expires_at expires.', 'request', True, diff --git a/tuldok_project/plan.py b/tuldok_project/plan.py index c95bf659..74c6e5c7 100644 --- a/tuldok_project/plan.py +++ b/tuldok_project/plan.py @@ -21,18 +21,25 @@ built has the action built and is not work; one that is out-of-date or failed is built again, and its reasons say why. build_plan reads those states from builds.status, which looks at the code root's Git history only when some -product exists. +product exists. A generate step (spec-d5.md section 3) to be built on a +machine with no Pumas endpoint set is blocked, says so, and keeps the plan +from being buildable, as an environment that is not ready keeps it from +running; the settings file is read for that only when such a step is to be +built. """ from collections import deque import math from . import documents, graph +from . import local as machine # make_plan's argument local is the recorded states from .store import ProjectError BUILT_KINDS = ('dataset', 'recipe', 'step', 'benchmark') ACTIONS = ('build', 'set-up', 'blocked', 'ready', 'built') RESOURCES = ('gpu', 'cpu_threads', 'memory_gb', 'wall_hours', 'disk_gb') CAUSE_LIMIT = 5 +NO_ENDPOINT = ('No Pumas endpoint is set on this machine, so this dataset cannot be generated here; the owner sets ' + 'one, then it can be built.') _CAUSE_LABELS = ('no', 'needs-work') @@ -199,7 +206,7 @@ def _estimated(steps, field, scale): return math.fsum(values) / scale, len(values) -def make_plan(definitions, targets, *, every=False, local=None, built=None, estimates=None): +def make_plan(definitions, targets, *, every=False, local=None, built=None, estimates=None, endpoint=False): """The plan for targets over {reference: document}, as section 3 and 4 of spec-m4.md describe it. local is graph.states' mapping of references to the state recorded on @@ -209,6 +216,10 @@ def make_plan(definitions, targets, *, every=False, local=None, built=None, esti running) and scratch says whether its current product is a scratch one. estimates is builds.stored_estimates' mapping of reference to the current estimate ({disk_bytes, wall_seconds, items, measured_at}). + endpoint says whether this machine has a Pumas endpoint set, or is a + function answering that, asked only when a generate step would be built + (so that a plan with none reads no settings file); without one such a + step is blocked by itself (rebuild 'endpoint'). every adds every dataset, recipe, step and benchmark to the targets. A chart target is replaced by its benchmark, an annotation task by its @@ -246,6 +257,13 @@ def make_plan(definitions, targets, *, every=False, local=None, built=None, esti ordered = graph.order({reference: definitions[reference] for reference in members}) actions = {reference: _action(_kind(reference), states[reference]) for reference in ordered} + asked = {} + + def has_endpoint(): + if 'set' not in asked: + asked['set'] = bool(endpoint() if callable(endpoint) else endpoint) + return asked['set'] + steps = [] for number, reference in enumerate(ordered, 1): document, kind = definitions[reference], _kind(reference) @@ -270,6 +288,12 @@ def make_plan(definitions, targets, *, every=False, local=None, built=None, esti step['action'] = action = actions[reference] = 'blocked' if provided == 'freeze': notes.extend(_task_notes(definitions, reference, document)) + if provided == 'generate' and action == 'build' and not has_endpoint(): + step['action'] = action = actions[reference] = 'blocked' + step['blocked_by'] = [{'reference': reference, 'rebuild': 'endpoint', 'reason': NO_ENDPOINT}] + notes.append(f'{reference} is generated through a Pumas endpoint, and none is set on this machine.') + steps.append(step) + continue if action == 'blocked': found = causes(definitions, edges_from, reference) step['blocked_by'] = found[:CAUSE_LIMIT] @@ -277,13 +301,16 @@ def make_plan(definitions, targets, *, every=False, local=None, built=None, esti steps.append(step) blocked = {step['reference'] for step in steps if step['action'] == 'blocked'} + # A generate held by the missing endpoint stops the build wherever it stands, as a target or not. + held = [step['reference'] for step in steps if step['reference'] not in resolved + and any(cause['rebuild'] == 'endpoint' for cause in step['blocked_by'])] disk_gb, disk_unknown = _total(steps, 'disk_gb') wall_hours, wall_unknown = _total(steps, 'wall_hours') estimated_disk_gb, estimated_disk_steps = _estimated(steps, 'disk_bytes', 1000 ** 3) estimated_wall_hours, estimated_wall_steps = _estimated(steps, 'wall_seconds', 3600) return {'targets': resolved, 'every': every, - 'buildable': not any(reference in blocked for reference in resolved), - 'blocked_targets': [reference for reference in resolved if reference in blocked], + 'buildable': not any(reference in blocked for reference in resolved) and not held, + 'blocked_targets': [reference for reference in resolved if reference in blocked] + held, 'counts': {action: sum(step['action'] == action for step in steps) for action in ACTIONS}, 'gpu_steps': sum(step['action'] == 'build' and step['resources']['gpu'] is True for step in steps), 'disk_gb': disk_gb, 'disk_unknown': disk_unknown, @@ -312,4 +339,4 @@ def build_plan(project, targets, *, every=False): local = {**environments.recorded_states(project._connection, project.schema), **{reference: entry['state'] for reference, entry in built.items()}} return make_plan(definitions, targets, every=every, local=local, built=built, - estimates=builds.stored_estimates(project)) + estimates=builds.stored_estimates(project), endpoint=lambda: machine.pumas_endpoint() is not None) diff --git a/tuldok_project/pumas.py b/tuldok_project/pumas.py new file mode 100644 index 00000000..e01bdea4 --- /dev/null +++ b/tuldok_project/pumas.py @@ -0,0 +1,516 @@ +"""The Pumas endpoint this machine uses: what it serves, and asking it to make a record or suggest an annotation. + +Owns sections 1 and 2 and the requests of sections 3 and 4 of +docs/plans/definition-first-projects/spec-d5.md. This is the one module of +tuldok_project that imports Tuldok's client for the Pumas 0.8.0 endpoint +(spec-d3.md): pumas_operations, image_generation, pumas_vision and +gateway_discovery, which use ai_http. Pumas is reached by HTTP at an address +and only so; nothing of it is imported, bundled or started. + +Tuldok hard-codes no capability. Every offer and every check before a call +comes from what served() read from GET /v1/served-models at that moment, +through pumas_operations.available_capabilities. What a request carries is +the released grammar (model-operations-v1.md): an input kind, an output, the +options kind of the capability. A generated record is stored only for the +outputs this phase can keep, text and png_base64; another output is not +offered. Every request is bounded in time and bytes as the client bounds it +(pumas_operations.exchange: a 10 s connection, the response read under the +lesser of the client's bound and the endpoint's max_response_bytes, the +request under its max_request_bytes); a suggestion is also given up after +SUGGEST_SECONDS. Nothing here opens the database or the project: service.py +and steps.py call these functions outside the service's lock. +""" +import base64 +import http.client +import io +import json +import math +import threading +import wave + +import gateway_discovery +import image_generation +import pumas_operations as client +import pumas_vision + +# What the step generate makes, and the output it asks for. Only these can be kept as records (section 1). +OUTPUTS = {'text': 'text', 'image': 'png_base64'} +# The options kind of each capability Tuldok sends, and the request options of each kind (model-operations-v1.md). +# Only these names are ever sent as options; seed comes from the step's own setting, never from its options. +OPTION_KINDS = {'chat_generation': 'text_generation', 'text_generation': 'text_generation', + 'image_to_text': 'text_generation', 'image_generation': 'image_generation'} +KIND_OPTIONS = {'text_generation': ('max_tokens', 'temperature', 'top_p'), + 'image_generation': ('width', 'height', 'seed')} +WHOLE_OPTIONS = ('max_tokens', 'width', 'height', 'seed') +SUGGEST_SECONDS = 300.0 # a suggestion not answered by then is given up +CONTENT_LIMIT = 16 * 1024 * 1024 # bytes of a record sent for a suggestion +TEXT_LIMIT = 64 * 1024 # bytes of a text record sent for a suggestion +AUDIO_SECONDS = 30 # the release's bound on one clip +AUDIO_BYTES = 16 * 1024 * 1024 +WORDS_SHOWN = 400 # characters of a model's answer quoted in a refusal +MODALITY = {'text': 'text', 'image': 'image', 'audio': 'audio'} # a record's kind -> the modality it is sent as +DEFAULT_CAPTION = 'Describe this image in one or two sentences.' +DEFAULT_SUMMARY = 'Summarize this text in a few sentences.' +DEFAULT_DECISION = 'Decide for the content given.' +NO_ENDPOINT = 'No Pumas endpoint is set on this machine; the owner sets one.' + + +class PumasError(Exception): + """A call that cannot be made or did not succeed. code is a refusal code of the project's operations; + outcome is the endpoint's (not_admitted or unknown) when it answered the request, else None.""" + + def __init__(self, message, code='unavailable', *, outcome=None, provider_code=None): + super().__init__(message) + self.code, self.outcome, self.provider_code = code, outcome, provider_code + + +# ----------------------------------------------------------- the endpoint + +def normalize(address): + """The address as the client sends to it: numeric-loopback HTTP, as Pumas 0.8.0 serves (PumasError invalid).""" + try: + return client.endpoint(address) + except ValueError: + raise PumasError(f'{address!r} is not an address Tuldok can reach Pumas at: Pumas 0.8.0 serves on a ' + 'numeric loopback address such as http://127.0.0.1:8765, without a path.', 'invalid') from None + + +def served(address, cancel_event=None): + """What the endpoint serves now (pumas_operations.served_models); PumasError when it does not answer.""" + try: + return client.served_models(address, cancel_event) + except client.OperationError as exc: + raise PumasError(str(exc), 'unavailable') from None + + +def version(address): + """The endpoint's reported version (its /.well-known/pumas build_info.package_version), or None.""" + try: + observed = gateway_discovery.inspect_advertised(address) + except (ValueError, OSError, TypeError, KeyError, http.client.HTTPException): + return None + build = observed['advertisement'].get('build_info') + found = build.get('package_version') if isinstance(build, dict) else None + return found if isinstance(found, str) and len(found) <= 128 else None + + +def _descriptor(entry, name): + return next((row for row in entry['capabilities'] if row['capability'] == name), None) + + +def _options_kind(row): + return OPTION_KINDS.get(row['capability']) + + +def _sendable(row): + """{option: {minimum, maximum}} of the options a step may set for this capability (seed aside).""" + names = KIND_OPTIONS.get(_options_kind(row), ()) + return {name: row['option_bounds'][name] for name in names if name != 'seed' and name in row['option_bounds']} + + +def _takes_seed(row): + return 'seed' in KIND_OPTIONS.get(_options_kind(row), ()) and 'seed' in row['option_bounds'] + + +def makes(entry): + """What a served model can make now that Tuldok keeps: [{make, capability, options, seed}].""" + found = [] + for make, output in OUTPUTS.items(): + names = client.available_capabilities(entry, 'text', output) + if names: + row = _descriptor(entry, names[0]) + found.append({'make': make, 'capability': names[0], 'options': _sendable(row), 'seed': _takes_seed(row)}) + return found + + +def shown(entry): + """One served (model, profile) as the operation endpoint shows it.""" + return {'model': entry['model'], 'profile': entry['profile'], 'profile_required': entry['profile_required'], + 'model_id': entry['model_id'], 'provider': entry['provider'], 'load_state': entry['load_state'], + 'context_tokens': entry['context_tokens'], 'modalities': entry['modalities'], + 'capabilities': [{'capability': row['capability'], 'available': row['availability']['state'] == 'available', + 'reason': row['availability'].get('reason'), 'input_formats': row['input_formats'], + 'output_formats': row['output_formats'], 'input_modalities': row['input_modalities'], + 'output_modalities': row['output_modalities'], 'option_bounds': row['option_bounds']} + for row in entry['capabilities']], + 'makes': makes(entry)} + + +def observe(address): + """{address, answered, version, models, problem}: what the endpoint at address serves now, asked once.""" + if address is None: + return {'address': None, 'answered': False, 'version': None, 'models': [], 'problem': NO_ENDPOINT} + try: + listing = served(address) + except PumasError as exc: + return {'address': address, 'answered': False, 'version': None, 'models': [], 'problem': str(exc)} + return {'address': address, 'answered': True, 'version': version(address), + 'models': [shown(entry) for entry in listing['models']], 'problem': None} + + +def find(): + """{endpoints: [{address, version, component}], rejected}: the Pumas endpoints advertising themselves here.""" + try: + found = gateway_discovery.scan_advertised() + except ValueError as exc: + raise PumasError(str(exc), 'unavailable') from None + endpoints = [] + for row in found['gateways']: + build = row['advertisement'].get('build_info') or {} + endpoints.append({'address': row['server_url'], 'version': build.get('package_version'), + 'component': build.get('component')}) + return {'endpoints': endpoints, 'rejected': found['rejected']} + + +def choose(listing, model, profile=None): + """The served entry of model (and profile): PumasError not-found when not served, invalid when ambiguous.""" + rows = [entry for entry in listing['models'] if entry['model'] == model] + if not rows: + names = sorted({entry['model'] for entry in listing['models']}) + raise PumasError(f'The endpoint serves no model {model!r}; it serves ' + + (', '.join(names) if names else 'none') + '.', 'not-found') + if profile is not None: + entry = next((entry for entry in rows if entry['profile'] == profile), None) + if entry is None: + raise PumasError(f'The endpoint serves {model} with the profile ' + ', '.join(e['profile'] for e in rows) + + f', not {profile}.', 'not-found') + return entry + if len(rows) > 1: + raise PumasError(f'{model} is served with the profiles ' + ', '.join(entry['profile'] for entry in rows) + + '; name one.', 'invalid') + return rows[0] + + +def _unavailable(entry, output): + """Why no capability of entry makes output now, in words.""" + reasons = [f'{row["capability"]} is unavailable' + (f' ({row["availability"]["reason"]})' + if row['availability'].get('reason') else '') + for row in entry['capabilities'] if output in row['output_formats'] + and row['availability']['state'] != 'available'] + return '; '.join(reasons) if reasons else f'none of its capabilities makes {output}' + + +def _number(name, value): + if isinstance(value, bool) or type(value) not in (int, float) or not math.isfinite(value): + raise PumasError(f'The option {name} must be a number.', 'invalid') + if name in WHOLE_OPTIONS and type(value) is not int: + raise PumasError(f'The option {name} must be a whole number.', 'invalid') + + +def _figure(value): + """A number as it reads: a whole one in full, another as short as it stays exact enough.""" + if isinstance(value, float) and value.is_integer() and abs(value) < 2 ** 63: + value = int(value) + return str(value) if isinstance(value, int) else f'{value:.6g}' + + +def _bound(row, name, value, what): + bound = row['option_bounds'].get(name) + if bound is not None and not bound['minimum'] <= value <= bound['maximum']: + raise PumasError(f'{what} {name} {_figure(value)} is outside the bound {_figure(bound["minimum"])} to ' + f'{_figure(bound["maximum"])} that the endpoint advertises for {row["capability"]}.', + 'invalid') + + +def options_of(row, options): + """The request options (with their kind) for the step's options, checked against the advertised bounds.""" + kind = _options_kind(row) + allowed = [name for name in KIND_OPTIONS.get(kind, ()) if name != 'seed'] + for name, value in options.items(): + if name not in allowed: + raise PumasError(f'{row["capability"]} takes the options ' + (', '.join(allowed) or 'none') + + f', not {name!r}.', 'invalid') + _number(name, value) + if name not in row['option_bounds']: + raise PumasError(f'The endpoint advertises no bound for {name} of {row["capability"]}, so Tuldok does ' + 'not send it; remove the option.', 'invalid') + _bound(row, name, value, 'The option') + if kind == 'image_generation': + if 'width' not in options or 'height' not in options: + raise PumasError('image_generation needs the options width and height.', 'invalid') + try: + client.image_dimensions(options['width'], options['height']) + except ValueError as exc: + raise PumasError(str(exc), 'invalid') from None + return {'kind': kind, **options} if kind else None + + +def prepare_make(listing, settings): + """What every item of a generate step is asked with, checked before anything is asked (PumasError). + + {entry, row (the capability's descriptor), output, options (the request's, or None), takes_seed}. + """ + entry = choose(listing, settings['model'], settings.get('profile')) + output = OUTPUTS[settings['make']] + names = client.available_capabilities(entry, 'text', output) + if not names: + raise PumasError(f'{entry["model"]} ({entry["profile"]}) cannot make {settings["make"]} now: ' + + _unavailable(entry, output) + '.', 'unavailable') + row = _descriptor(entry, names[0]) + return {'entry': entry, 'row': row, 'output': output, 'options': options_of(row, settings.get('options') or {}), + 'takes_seed': _takes_seed(row)} + + +def check_item(prepared, prompt, seed): + """Refuse (PumasError invalid) an item whose prompt or seed is outside what the endpoint advertises.""" + row = prepared['row'] + _bound(row, 'input_characters', len(prompt), 'The prompt\'s') + if seed is not None: + _bound(row, 'seed', seed, 'The') + + +def _exchange(address, listing, request, stop, limit): + size = len(json.dumps(request, ensure_ascii=False, separators=(',', ':')).encode('utf-8')) + if size > listing['max_request_bytes']: + raise PumasError(f'The request is {size} bytes; the endpoint takes at most {listing["max_request_bytes"]}.', + 'invalid') + try: + return client.exchange(address, request, stop, min(limit, listing['max_response_bytes']))[1] + except client.OperationError as exc: + raise PumasError(str(exc), 'unavailable', outcome=exc.outcome, provider_code=exc.provider_code) from None + + +def _request(entry, row, request_id, input_value, output, options=None): + value = {'contract_version': 1, 'request_id': request_id, 'model': entry['model'], 'profile': entry['profile'], + 'capability': row['capability'], 'input': input_value, 'output': output, 'stream': False} + if options: + value['options'] = options + return value + + +def make_one(address, listing, prepared, prompt, seed, request_id, stop): + """Ask for one item: {'text': str} or {'png': bytes, 'seed': int}. PumasError with the endpoint's reason.""" + entry, row = prepared['entry'], prepared['row'] + check_item(prepared, prompt, seed) + options = dict(prepared['options']) if prepared['options'] else None + if prepared['takes_seed'] and seed is not None: + options['seed'] = seed + request = _request(entry, row, request_id, {'kind': 'text', 'text': prompt}, prepared['output'], options) + if prepared['output'] == 'text': + return {'text': _exchange(address, listing, request, stop, client.MAX_TEXT_RESPONSE)['text']} + value = _exchange(address, listing, request, stop, image_generation.MAX_JSON) + try: + decoded = image_generation.decode_png(value['png_base64'], options['width'], options['height']) + except ValueError as exc: + raise PumasError(str(exc), 'unavailable', outcome='unknown') from None + return {'png': base64.b64decode(decoded['image']), 'seed': value['seed']} + + +# ------------------------------------------------------------ suggestions + +def routes(entry, task, kind): + """How entry can suggest a value of task for a record of kind now, best first (section 4's table). + + Each is {capability, input (the request's input kind), output, terms (asked to answer with terms only)}. + """ + if kind not in MODALITY: + return [] + found = [] + if task == 'text': + input_kind, name = {'image': ('image_messages', 'image_to_text'), 'audio': ('audio', 'audio_transcription'), + 'text': ('messages', 'chat_generation')}[kind] + if name in client.available_capabilities(entry, input_kind, 'text'): + found.append({'capability': name, 'input': input_kind, 'output': 'text', 'terms': False}) + elif task in ('class', 'tags'): + if 'decision' in client.available_capabilities(entry, 'decision', 'decisions') \ + and MODALITY[kind] in _descriptor(entry, 'decision')['input_modalities']: + found.append({'capability': 'decision', 'input': 'decision', 'output': 'decisions', 'terms': False}) + fallback = {'text': ('messages', 'chat_generation'), 'image': ('image_messages', 'image_to_text')}.get(kind) + if fallback and fallback[1] in client.available_capabilities(entry, fallback[0], 'text'): + found.append({'capability': fallback[1], 'input': fallback[0], 'output': 'text', 'terms': True}) + return found + + +def _within(row, facts): + for name, value in facts.items(): + _bound(row, name, value, 'The record\'s') + + +def _image(data): + """(image part, its facts) of PNG or JPEG bytes, checked as the client checks them.""" + encoding = 'png' if data.startswith(b'\x89PNG\r\n\x1a\n') else 'jpeg' if data.startswith(b'\xff\xd8') else None + if encoding is None: + raise PumasError('Only a PNG or JPEG image can be sent to a model.', 'invalid') + part = {'kind': 'image', 'encoding': encoding, 'data_base64': base64.b64encode(data).decode('ascii')} + try: + facts = pumas_vision.image_part(part) + except ValueError as exc: + raise PumasError(f'The image cannot be sent to a model: {exc}', 'invalid') from None + return part, dict(facts, image_count=1, total_image_bytes=facts['image_bytes']) + + +def _clip(data): + """(audio clip without kind, its facts) of a 16-bit PCM WAVE sound of at most AUDIO_SECONDS.""" + refused = PumasError(f'Only a 16-bit PCM WAVE sound of one or two channels, 8 to 192 kHz and at most ' + f'{AUDIO_SECONDS} s can be sent to a model.', 'invalid') + try: + with wave.open(io.BytesIO(data)) as sound: + channels, width, rate = sound.getnchannels(), sound.getsampwidth(), sound.getframerate() + pcm = sound.readframes(sound.getnframes()) + except (wave.Error, EOFError, ValueError, OSError): + raise refused from None + if width != 2 or channels not in (1, 2) or not 8000 <= rate <= 192000: + raise refused + frames = len(pcm) // (2 * channels) + pcm = pcm[:frames * 2 * channels] + if not frames or frames / rate > AUDIO_SECONDS or len(pcm) > AUDIO_BYTES: + raise refused + clip = {'encoding': 'pcm_s16le', 'sample_rate_hz': rate, 'channels': channels, 'sample_count': frames, + 'data_base64': base64.b64encode(pcm).decode('ascii')} + return clip, {'audio_count': 1, 'total_audio_bytes': len(pcm), 'audio_seconds': frames / rate, + 'sample_rate': rate} + + +def _terms_instruction(task, vocabulary, instruction): + listed = '\n'.join(vocabulary) + if task == 'class': + asked = 'Answer with exactly one of these terms, written as it is, and nothing else:' + else: + asked = ('Answer with the terms of this list that apply, one per line, written as they are, and nothing ' + 'else; answer with nothing when none applies:') + return (instruction + '\n\n' if instruction else '') + asked + '\n' + listed + + +def _terms(task, vocabulary, answer): + """The value a terms-only answer gives, or None when it is not made of terms.""" + terms = set(vocabulary) + whole = answer.strip().strip('"\'`').strip() + if task == 'class': + whole = whole.rstrip('.').strip() + return whole if whole in terms else None + if whole in terms: + return [whole] + found = [] + for line in whole.replace(',', '\n').splitlines(): + term = line.strip().strip('-*•').strip().strip('"\'`').rstrip('.').strip() + if not term: + continue + if term not in terms: + return None + if term not in found: + found.append(term) + return [term for term in vocabulary if term in found] + + +def _quoted(words): + words = ' '.join(str(words).split()) + return '“' + words[:WORDS_SHOWN] + ('…' if len(words) > WORDS_SHOWN else '') + '”' + + +def suggest(address, listing, entry, route, task, vocabulary, content, instruction=None, *, request_id, stop=None, + check=None): + """Ask entry for a value of task for one record's content, by route; the value, or PumasError. + + content is {'kind', 'text'} or {'kind', 'data'}. check(value) returns the + problems of a value under the task; an answer with any, or not made of + terms where terms were asked for, is refused (code unsuitable) with the + model's words, never returned as a value. + """ + row = _descriptor(entry, route['capability']) + kind = content['kind'] + stop = stop or threading.Event() + timer = threading.Timer(SUGGEST_SECONDS, stop.set) + timer.daemon = True + if route['capability'] == 'decision': + input_value = _decision_input(row, task, vocabulary, content, instruction) + timer.start() + try: + value = _exchange(address, listing, _request(entry, row, request_id, input_value, 'decisions'), stop, + client.MAX_TEXT_RESPONSE) + finally: + timer.cancel() + suggestion, words = _decided(task, vocabulary, value['answers']) + else: + if route['terms']: + asked = _terms_instruction(task, vocabulary, instruction) + else: + asked = instruction or (DEFAULT_CAPTION if kind == 'image' else DEFAULT_SUMMARY) + input_value = _text_input(row, route, content, asked) + timer.start() + try: + value = _exchange(address, listing, _request(entry, row, request_id, input_value, 'text'), stop, + client.MAX_TEXT_RESPONSE) + finally: + timer.cancel() + words = value['text'] + suggestion = _terms(task, vocabulary, words) if route['terms'] else words.strip() + if route['terms'] and suggestion is None: + raise PumasError(f'The answer of {entry["model"]} is not made of the task\'s terms, so it is not a ' + f'suggestion. It answered {_quoted(words)}.', 'unsuitable') + if not route['terms'] and not suggestion: + raise PumasError(f'{entry["model"]} answered with nothing.', 'unsuitable') + problems = check(suggestion) if check is not None else [] + if problems: + raise PumasError(f'The answer of {entry["model"]} is not a value of the task: ' + ' '.join(problems) + + f' It answered {_quoted(words)}.', 'unsuitable') + return suggestion + + +def _text_input(row, route, content, asked): + if route['input'] == 'messages': + text = content['text'] + if len(text.encode('utf-8', 'surrogatepass')) > TEXT_LIMIT: + raise PumasError(f'The text is over {TEXT_LIMIT} bytes, more than Tuldok sends for a suggestion.', 'invalid') + return {'kind': 'messages', 'messages': [{'role': 'system', 'content': asked}, {'role': 'user', 'content': text}]} + if route['input'] == 'image_messages': + part, facts = _image(content['data']) + _within(row, dict(facts, message_count=1, content_parts=2)) + value = {'kind': 'image_messages', + 'messages': [{'role': 'user', 'content': [{'kind': 'text', 'text': asked}, part]}]} + try: + pumas_vision.validate_input(value) + except ValueError as exc: + raise PumasError(f'The image cannot be sent to a model: {exc}', 'invalid') from None + return value + clip, facts = _clip(content['data']) # audio_transcription: the audio input, no options + _within(row, facts) + return {'kind': 'audio', **clip} + + +def _decision_input(row, task, vocabulary, content, instruction): + """A decision over the vocabulary: one choice for class, a yes-or-no (noul) per term for tags.""" + if task == 'class': + questions = {'class': {'type': 'choice', 'instructions': instruction or 'Choose the term that fits.', + 'criteria': {term: None for term in vocabulary}}} + else: + questions = {f't{index}': {'type': 'noul', 'instructions': (instruction + ' ' if instruction else '') + + f'Does the term {json.dumps(term, ensure_ascii=False)} apply?'} + for index, term in enumerate(vocabulary)} + value = {'kind': 'decision', 'questions': questions} + if content['kind'] == 'text': + if len(content['text'].encode('utf-8', 'surrogatepass')) > TEXT_LIMIT: + raise PumasError(f'The text is over {TEXT_LIMIT} bytes, more than Tuldok sends for a suggestion.', 'invalid') + value['state'] = content['text'] + elif content['kind'] == 'image': + part, facts = _image(content['data']) + _within(row, facts) + value['state'] = instruction or DEFAULT_DECISION + value['images'] = [{'encoding': part['encoding'], 'data_base64': part['data_base64']}] + else: + clip, facts = _clip(content['data']) + _within(row, facts) + value['state'] = instruction or DEFAULT_DECISION + value['audio'] = [clip] + return value + + +def _decided(task, vocabulary, answers): + """(the value the decision answers give, the answers in words), or PumasError unsuitable.""" + words = json.dumps(answers, ensure_ascii=False)[:WORDS_SHOWN * 2] + if task == 'class': + answer = answers.get('class') + choice = answer.get('choice') if isinstance(answer, dict) else None + if not isinstance(choice, str): + raise PumasError(f'The decision has no choice for the question asked. It answered {_quoted(words)}.', + 'unsuitable') + return choice, choice + chosen = [] + for index, term in enumerate(vocabulary): + answer = answers.get(f't{index}') + probability = answer.get('noul') if isinstance(answer, dict) else None + if isinstance(probability, bool) or type(probability) not in (int, float) or not math.isfinite(probability): + raise PumasError(f'The decision does not answer whether {term!r} applies. It answered {_quoted(words)}.', + 'unsuitable') + if probability > 0.5: + chosen.append(term) + return chosen, words diff --git a/tuldok_project/schemas/benchmark.schema.json b/tuldok_project/schemas/benchmark.schema.json index 16e5aea7..4215457e 100644 --- a/tuldok_project/schemas/benchmark.schema.json +++ b/tuldok_project/schemas/benchmark.schema.json @@ -319,9 +319,10 @@ "step": { "enum": [ "import", - "freeze" + "freeze", + "generate" ], - "description": "a step Tuldok provides: import or freeze" + "description": "a step Tuldok provides: import, freeze or generate" }, "environment": { "type": "string", diff --git a/tuldok_project/schemas/dataset.schema.json b/tuldok_project/schemas/dataset.schema.json index 95ea2ddf..03257b51 100644 --- a/tuldok_project/schemas/dataset.schema.json +++ b/tuldok_project/schemas/dataset.schema.json @@ -268,9 +268,10 @@ "step": { "enum": [ "import", - "freeze" + "freeze", + "generate" ], - "description": "a step Tuldok provides: import or freeze" + "description": "a step Tuldok provides: import, freeze or generate" }, "environment": { "type": "string", diff --git a/tuldok_project/schemas/recipe.schema.json b/tuldok_project/schemas/recipe.schema.json index fd079c6f..07413d62 100644 --- a/tuldok_project/schemas/recipe.schema.json +++ b/tuldok_project/schemas/recipe.schema.json @@ -250,9 +250,10 @@ "step": { "enum": [ "import", - "freeze" + "freeze", + "generate" ], - "description": "a step Tuldok provides: import or freeze" + "description": "a step Tuldok provides: import, freeze or generate" }, "environment": { "type": "string", diff --git a/tuldok_project/schemas/step.schema.json b/tuldok_project/schemas/step.schema.json index b35025ce..517fe152 100644 --- a/tuldok_project/schemas/step.schema.json +++ b/tuldok_project/schemas/step.schema.json @@ -201,9 +201,10 @@ "step": { "enum": [ "import", - "freeze" + "freeze", + "generate" ], - "description": "a step Tuldok provides: import or freeze" + "description": "a step Tuldok provides: import, freeze or generate" }, "environment": { "type": "string", diff --git a/tuldok_project/service.py b/tuldok_project/service.py index 6e99344c..27e6c506 100644 --- a/tuldok_project/service.py +++ b/tuldok_project/service.py @@ -18,7 +18,13 @@ lock, the product is read and hashed outside it (annotation_records), and what was computed is kept under the lock again; set_annotation finds and reads the records it names before it takes the lock to check and store them. -Nothing here knows of HTTP or of the app's access layer. +The five operations on the Pumas endpoint (spec-d5.md sections 2 and 4) call +it outside the lock, through pumas.py: endpoint, set_endpoint and +find_endpoints need no project at all (the address is a setting of the +machine, in local.py's settings file), and suggestion_models and +suggest_annotation find the task's product under the lock and read it and +ask the endpoint after releasing it. Nothing here knows of HTTP or of the +app's access layer. The worker (section 4) is one thread per service, started by start() and stopped by close(). It runs queued build requests one at a time while it @@ -45,7 +51,8 @@ import psycopg from . import (activity, annotation_records, annotation_rows, annotations, build_requests, builds, charts, check, - documents, environments, inside, inside_weights, launcher, local, operations, plan, store, workspace) + documents, environments, inside, inside_weights, launcher, local, operations, plan, pumas, store, + workspace) from .documents import Problem CHECK_PROBLEMS = 200 @@ -78,6 +85,10 @@ } # The reads of annotations (spec-d4.md section 5): each takes the service's lock itself, only for its database work. ANNOTATION_READS = ('annotation_tasks', 'annotated_records', 'annotation') +# The calls to the Pumas endpoint (spec-d5.md): each is made outside the service's lock; those that read a project +# take the lock themselves, only for their database work. +OUTSIDE_LOCK = ANNOTATION_READS + ('endpoint', 'set_endpoint', 'find_endpoints', 'suggestion_models', + 'suggest_annotation') POLL_SECONDS = 1.0 # how often the worker looks for a queued request CLOSE_SECONDS = 30.0 # how long close() waits for the worker WORKER_LOCK = 'build-requests.lock' @@ -145,6 +156,8 @@ def _detail(name, result): return f'{result["set"]} set, {result["removed"]} removed' if name == 'revert_annotations': return f'{result["reverted"]} reverted' + if name == 'set_endpoint': + return 'set' if result['address'] else 'cleared' return '' @@ -317,12 +330,24 @@ def call(self, name, arguments, actor): with self._lock: found = {key: self._product(arguments[key]) for key in PRODUCT_ARGUMENTS if key in arguments} return _plain(INSIDE_READS[name](found, dict(arguments))) - if name in ANNOTATION_READS: - problems = _argument_problems(operation, arguments) - if problems: - raise store.ProjectError(f'The arguments of project.{name} do not match its schema.', 'invalid', - problems=problems) - return _plain(getattr(self, f'_{name}')(dict(arguments), actor)) + if name in OUTSIDE_LOCK: + try: + problems = _argument_problems(operation, arguments) + if problems: + raise store.ProjectError(f'The arguments of project.{name} do not match its schema.', 'invalid', + problems=problems) + result = _plain(getattr(self, f'_{name}')(dict(arguments), actor)) + except store.ProjectError as exc: + if operation.mutation: + self._record_activity(actor, name, _target(arguments), exc.code, str(exc)) + raise + except Exception as exc: + if operation.mutation: + self._record_activity(actor, name, _target(arguments), 'error', f'{type(exc).__name__}: {exc}') + raise + if operation.mutation: + self._record_activity(actor, name, _target(arguments), 'done', _detail(name, result)) + return result prepared = () if name == 'set_annotation': # the records are found and read before the lock is taken to store them try: @@ -748,6 +773,109 @@ def _revert_annotations(self, arguments, actor): reverted = project.revert_annotations(name, arguments.get('records'), document) return {'task': annotation_rows.reference(name), 'reverted': reverted} + # ------------------------------------------------------- the endpoint + + def _endpoint(self, arguments, actor): + return pumas.observe(local.pumas_endpoint()) + + def _set_endpoint(self, arguments, actor): + """Ask the address once what it serves and keep it when it answered; null clears the setting.""" + if arguments['address'] is None: + local.set_pumas_endpoint(None) + return pumas.observe(None) + try: + address = pumas.normalize(arguments['address']) + except pumas.PumasError as exc: + raise store.ProjectError(str(exc), exc.code) from None + seen = pumas.observe(address) + if not seen['answered']: + raise store.ProjectError(f'The Pumas endpoint at {address} did not answer, so it was not set: ' + f'{seen["problem"]}', 'unavailable') + local.set_pumas_endpoint(address) + return seen + + def _find_endpoints(self, arguments, actor): + try: + return pumas.find() + except pumas.PumasError as exc: + raise store.ProjectError(str(exc), exc.code) from None + + def _task_product(self, task): + """(name, document, inside.Product or None, its record index or None) of a task: found under the lock.""" + with self._lock, self._open() as project: + name, document = project.annotation_task(task) + located = self._located(project, document) + product, index = self._product_of(located) + return name, document, product, index + + def _suggestion_models(self, arguments, actor): + name, document, _product, index = self._task_product(arguments['task']) + task = document.get('task') + kinds = sorted({record['kind'] for record in index.records} if index is not None else ()) + kinds = [kind for kind in kinds if annotations.allows_kind(task, kind)] + result = {'task': annotation_rows.reference(name), 'type': task, 'address': local.pumas_endpoint(), + 'kinds': {kind: [] for kind in kinds}, 'problem': None} + if result['address'] is None: + result['problem'] = pumas.NO_ENDPOINT + return result + try: + listing = pumas.served(result['address']) + except pumas.PumasError as exc: + result['problem'] = str(exc) + return result + for kind in kinds: + for entry in listing['models']: + found = pumas.routes(entry, task, kind) + if found: + result['kinds'][kind].append({'model': entry['model'], 'profile': entry['profile'], + 'capability': found[0]['capability']}) + return result + + def _suggest_annotation(self, arguments, actor): + """A value of the task for one record, asked of a served model; nothing is stored (spec-d5.md section 4).""" + record_id = arguments['record'] + name, document, product, index = self._task_product(arguments['task']) + reference = annotation_rows.reference(name) + task, vocabulary = document.get('task'), document.get('vocabulary') or [] + if index is None: + raise store.ProjectError(f'{document.get("dataset")} has no product to annotate; build it first.', + 'not-found', references=[document.get('dataset')]) + position = index.by_id.get(record_id) + if position is None: + raise store.ProjectError(f'The record {record_id!r} is not in the product of {document.get("dataset")}.', + 'not-found', references=[reference]) + record = index.records[position] + if not annotations.allows_kind(task, record['kind']): + raise store.ProjectError(f'A {task} task does not annotate records of kind {record["kind"]!r}.', 'invalid', + references=[reference]) + address = local.pumas_endpoint() + if address is None: + raise store.ProjectError(pumas.NO_ENDPOINT, 'unavailable') + facts = annotation_records.facts(product, record, task) + + def check(value): + errors, unknown = annotations.value_problems(task, vocabulary, 'draft', value, kind=record['kind'], + size=facts['size'], length=facts['length'], + duration=facts['duration']) + return errors + [f'The term {term!r} is not in the vocabulary of the task.' for term in unknown] + + try: + listing = pumas.served(address) + entry = pumas.choose(listing, arguments['model'], arguments.get('profile')) + found = pumas.routes(entry, task, record['kind']) + if not found: + raise pumas.PumasError(f'{entry["model"]} ({entry["profile"]}) cannot suggest a value of a {task} task ' + f'for a {record["kind"]} record now.', 'unavailable') + content = annotation_records.content(product, record, pumas.CONTENT_LIMIT) + value = pumas.suggest(address, listing, entry, found[0], task, vocabulary, content, + arguments.get('instruction'), request_id=f'tuldok-suggest:{os.urandom(8).hex()}', + check=check) + except pumas.PumasError as exc: + raise store.ProjectError(str(exc), exc.code, references=[reference]) from None + return {'task': reference, 'record': record_id, + 'suggestion': {'value': value, 'from': {'model': entry['model'], 'profile': entry['profile'], + 'capability': found[0]['capability']}}} + # ------------------------------------------------------------- changes def _set_definition(self, arguments, actor): diff --git a/tuldok_project/steps.py b/tuldok_project/steps.py index b14682ca..ca5100a2 100644 --- a/tuldok_project/steps.py +++ b/tuldok_project/steps.py @@ -1,22 +1,30 @@ -"""The steps Tuldok provides: import files into a dataset, and freeze a dataset with splits from its annotations. +"""The steps Tuldok provides: import files into a dataset, freeze a dataset with splits from its annotations, +and generate a dataset by asking a model a Pumas endpoint serves. -Owns section 6 of docs/plans/definition-first-projects/spec-d4.md. A dataset -whose run names a step (run.step) is built by Tuldok's own interpreter running +Owns section 6 of docs/plans/definition-first-projects/spec-d4.md and section +3 of spec-d5.md. A dataset whose run names a step (run.step) is built by +Tuldok's own interpreter running python -m tuldok_project.steps import --code python -m tuldok_project.steps freeze --records --tasks + python -m tuldok_project.steps generate --endpoint
                            + --report [--records ] with Tuldok's code first on the module path and the snapshot's code off it (builds.py sets PYTHONSAFEPATH and PYTHONPATH). A step reads files and writes its output directory; it opens no database, follows no symbolic link out of its source, writes nowhere else and deletes nothing. It prints tuldok_progress_v1 lines and, at its end, what it counted, one plain line -each. The standard library alone is used: the record rules it shares with -inside.py (the kinds by extension, the pattern form, an id's characters) are -repeated here and a test keeps the two equal. - -import_files and freeze_records are the steps as functions on directories; -main() is the command line. +each. The standard library alone is used by import and freeze: the record +rules they share with inside.py (the kinds by extension, the pattern form, an +id's characters) are repeated here and a test keeps the two equal. generate +reaches the endpoint only through pumas.py, the one module that imports +Tuldok's client for it; it is given the machine's address by the build and +writes the address and the endpoint's version to its report file, which the +build keeps in the run's record. + +import_files, freeze_records and generate_records are the steps as functions +on directories; main() is the command line. """ import argparse import hashlib @@ -26,7 +34,9 @@ import shutil import stat import sys +import threading import time +import uuid from . import annotations @@ -39,7 +49,7 @@ 'mesh': ('.obj', '.stl'), 'array': ('.npy', '.npz', '.safetensors'), } -STEPS = ('import', 'freeze') +STEPS = ('import', 'freeze', 'generate') RECORD_LIST = 'records.jsonl' FILES = 'files' DEFAULT_PATTERN = '**/*' @@ -53,6 +63,9 @@ _NOT_ID = re.compile(r'[^A-Za-z0-9._-]') _SHA256 = re.compile(r'[0-9a-f]{64}') _CHUNK = 1 << 20 +MAKES = ('text', 'image') # what generate makes (spec-d5.md section 3) +GENERATE_LIMIT = 100_000 # items one generate makes +RETRY_PAUSES = (1.0, 2.0) # before asking again an item the endpoint did not admit; twice at most class StepError(Exception): @@ -567,6 +580,174 @@ def _frozen(record, split, tasks, rows, root, output, placed, used_ids, counts): return text +# ----------------------------------------------------------------- generate + +def prompt_parts(template): + """[('text', characters) or ('name', placeholder)] of a prompt; ValueError for a stray brace. + + {n} and {text} are the placeholders; {{ and }} are literal braces. + """ + parts, at = [], 0 + while at < len(template): + if template.startswith('{{', at): + parts.append(('text', '{')) + at += 2 + elif template.startswith('}}', at): + parts.append(('text', '}')) + at += 2 + elif template[at] == '{': + end = template.find('}', at + 1) + if end < 0 or '{' in template[at + 1:end]: + raise ValueError('has a { that is not closed; write {{ for a brace') + parts.append(('name', template[at + 1:end])) + at = end + 1 + elif template[at] == '}': + raise ValueError('has a } that is not opened; write }} for a brace') + else: + parts.append(('text', template[at])) + at += 1 + return parts + + +def fill_prompt(template, values): + """The prompt with each {name} replaced from values (KeyError naming one it does not hold).""" + return ''.join(text if part == 'text' else str(values[text]) for part, text in prompt_parts(template)) + + +def _prompt_texts(root, view, counts): + """[(record id, text)] of the text records of the input product, in its order.""" + by_id = _input_records(root, view, counts) + found = [] + for identifier, record in by_id.items(): + if record['kind'] != 'text': + counts['not_text'] += 1 + continue + if record.get('path') is None: + found.append((identifier, record['text'])) + continue + full = _confined(root, record['path']) if '!' not in record['path'] else None + if full is None or os.path.getsize(full) > LINE_BYTES: + counts['unread'] += 1 + continue + with open(full, 'rb') as handle: + raw = handle.read() + try: + found.append((identifier, raw.decode('utf-8'))) + except UnicodeDecodeError: + counts['unread'] += 1 + return found + + +def _ask(pumas, endpoint, listing, prepared, prompt, seed, number, token, pauses, out): + """One item made, asking again (after a pause) what the endpoint refused before the provider took it.""" + never = threading.Event() # a cancel stops the whole step + for attempt in range(len(pauses) + 1): + try: + return pumas.make_one(endpoint, listing, prepared, prompt, seed, f'tuldok-generate:{token}:{number}:' + f'{attempt + 1}', never) + except pumas.PumasError as exc: + if exc.outcome != 'not_admitted' or attempt == len(pauses): + tries = f' (asked {attempt + 1} times)' if attempt else '' + raise StepError(f'Item {number} failed{tries}: {exc}') from None + out(f'Item {number} was not admitted ({exc.provider_code or "refused"}); asking again in ' + f'{pauses[attempt]:g} s.') + time.sleep(pauses[attempt]) + + +def generate_records(settings, output, *, endpoint, records=None, view=None, report=None, out=print, + pauses=RETRY_PAUSES): + """The generate step (spec-d5.md section 3): settings as the definition gives them, into output. + + endpoint is the machine's Pumas address; records the input product of + prompts, or None; report a file to write {address, version} to. Nothing + is asked before what the endpoint serves has been read and every item + checked against it. Returns the counts. + """ + from . import pumas # the step's one way to the endpoint + make, template, rights = settings['make'], settings['prompt'], settings['rights'] + seed = settings.get('seed') + counts = dict.fromkeys(('made', 'inputs', 'not_text', 'unread', 'bad_lines', 'retried', 'in_files'), 0) + if records is not None: + texts = _prompt_texts(os.path.realpath(records), view, counts) + counts['inputs'] = len(texts) + per = settings.get('per', 1) + items = [(identifier, text) for identifier, text in texts for _ in range(per)] + else: + items = [(None, None)] * settings['count'] + if len(items) > GENERATE_LIMIT: + raise StepError(f'It would make {len(items):,} items; one generate makes at most {GENERATE_LIMIT:,}.') + try: + listing = pumas.served(endpoint) + except pumas.PumasError as exc: + raise StepError(f'The Pumas endpoint at {endpoint} did not say what it serves: {exc}') from None + if report is not None: + with open(report, 'w', encoding='utf-8') as handle: + json.dump({'address': endpoint, 'version': pumas.version(endpoint)}, handle) + try: + prepared = pumas.prepare_make(listing, settings) + asked = [] + for number, (source, text) in enumerate(items, 1): + values = {'n': number} if source is None else {'n': number, 'text': text} + try: + prompt = fill_prompt(template, values) + except (KeyError, ValueError) as exc: + raise StepError(f'The prompt cannot be filled for item {number}: {exc}') from None + item_seed = seed + number - 1 if seed is not None and prepared['takes_seed'] else None + pumas.check_item(prepared, prompt, item_seed) + asked.append((source, prompt, item_seed)) + except pumas.PumasError as exc: + raise StepError(f'Nothing was asked: {exc}') from None + entry, row = prepared['entry'], prepared['row'] + sent = {key: value for key, value in (prepared['options'] or {}).items() if key != 'kind'} + token = uuid.uuid4().hex[:16] + progress = Progress('generate', len(asked), out) + progress(0, {}) + out(f'Asking {entry["model"]} ({entry["profile"]}) by {row["capability"]} for {len(asked)} ' + f'{"texts" if make == "text" else "images"}.') + used_ids = set() + with open(os.path.join(output, RECORD_LIST), 'x', encoding='utf-8') as listing_file: + for number, (source, prompt, item_seed) in enumerate(asked, 1): + made = _ask(pumas, endpoint, listing, prepared, prompt, item_seed, number, token, pauses, out) + identifier = unique(f'g{number:06d}', used_ids, ID_LIMIT) + origin = {'generated': {'model': entry['model'], 'profile': entry['profile'], + 'capability': row['capability'], 'prompt': prompt, + 'seed': made.get('seed', item_seed) if make == 'image' else None, + 'options': sent, 'input': source}} + listing_file.write(_line(_generated_record(output, identifier, make, made, rights, origin, counts))) + listing_file.flush() + counts['made'] += 1 + progress(number, {'made': counts['made']}) + progress(len(asked), {'made': counts['made']}, final=True) + out(f'{counts["made"]} {"texts" if make == "text" else "images"} made by {entry["model"]}.') + _say(out, counts, (('not_text', 'records of the input are not text and were not used.'), + ('unread', f'text records of the input could not be read (missing, over {LINE_BYTES} bytes ' + 'or not UTF-8) and were not used.'), + ('bad_lines', f'lines of the input\'s {RECORD_LIST} are not records and were skipped.'), + ('in_files', f'texts too long for one line ({LINE_BYTES} bytes) were written as files.'))) + return counts + + +def _generated_record(output, identifier, make, made, rights, origin, counts): + """The records.jsonl line of one made item; an image, or a text too long for a line, is a file under files/.""" + if make == 'text': + data = made['text'].encode('utf-8', 'surrogatepass') + record = {'id': identifier, 'kind': 'text', 'text': made['text'], 'sha256': hashlib.sha256(data).hexdigest(), + 'bytes': len(data), 'rights': rights, 'origin': origin} + if len(_line(record).encode('utf-8', 'surrogatepass')) <= LINE_BYTES: + return record + counts['in_files'] += 1 + address = f'{FILES}/{identifier}.txt' + else: + data = made['png'] + address = f'{FILES}/{identifier}.png' + target = os.path.join(output, *address.split('/')) + os.makedirs(os.path.dirname(target), exist_ok=True) + with open(target, 'xb') as handle: + handle.write(data) + return {'id': identifier, 'kind': make, 'path': address, 'sha256': hashlib.sha256(data).hexdigest(), + 'bytes': len(data), 'rights': rights, 'origin': origin} + + # --------------------------------------------------------------- command line def _arguments(argv): @@ -578,6 +759,8 @@ def _arguments(argv): parser.add_argument('--code', help='the code root the run sees (for a relative source)') parser.add_argument('--records', help='freeze: the input product\'s directory') parser.add_argument('--tasks', help='freeze: a JSON file of the tasks and their line files') + parser.add_argument('--endpoint', help='generate: the Pumas endpoint this machine uses') + parser.add_argument('--report', help='generate: a file to write the endpoint\'s address and version to') return parser.parse_args(argv) @@ -591,6 +774,11 @@ def main(argv=None): raise StepError(f'The output directory {arguments.output} does not exist.') if arguments.step == 'import': import_files(settings, arguments.output, code_root=arguments.code, out=out) + elif arguments.step == 'generate': + if arguments.endpoint is None: + raise StepError('generate needs --endpoint, the Pumas endpoint this machine uses.') + generate_records(settings, arguments.output, endpoint=arguments.endpoint, records=arguments.records, + report=arguments.report, out=out) else: if arguments.records is None or arguments.tasks is None: raise StepError('freeze needs --records and --tasks.') From fc145a4814dcab2892848eb2c8020ef961cfa64d Mon Sep 17 00:00:00 2001 From: MrScripty Date: Fri, 13 Nov 2026 18:48:15 -0700 Subject: [PATCH 076/131] feat(workspace): the Pumas endpoint, a Generate form, and suggestions in Annotate The Train tab shows the Pumas endpoint of this machine beside the environments: its address, whether it answers, its version, and each model it serves with what it takes and makes and which capabilities are available. The owner sets it, clears it or finds it on this machine. The Data tab gains a Generate form beside Import and Freeze: what to make (only what some served model can), the model, the prompt, a count or a dataset of prompts, a seed where the capability takes one, and the capability's options with the bounds the endpoint advertises. It keeps a dataset definition as an unsaved edit; building it is the existing plan and request. With no endpoint it says why and where to set one. The Annotate tab gains Suggest when a served model fits the task and the record: the answer fills the form, marked as a suggestion naming the model, until the person changes or keeps it, and the saved line then names the model. A refusal leaves the form as it was. "Suggest for this page" keeps a draft for each record on screen that has no annotation. Checked against a fake endpoint the check starts itself; no running Pumas was contacted and this machine's listeners were not scanned. Co-Authored-By: Claude Fable 5.2 --- app.py | 1 + docs/contracts/project-folder.md | 6 +- .../definition-first-projects/spec-d5.md | 15 + static/project-workspace.html | 1 + static/project-workspace/annotate.js | 127 ++++- static/project-workspace/base.css | 33 ++ static/project-workspace/generate.js | 258 +++++++++ static/project-workspace/tabs.js | 23 +- tests/browser_fake_pumas.py | 74 +++ tests/browser_project_workspace_endpoint.cjs | 498 ++++++++++++++++++ 10 files changed, 1022 insertions(+), 14 deletions(-) create mode 100644 static/project-workspace/generate.js create mode 100644 tests/browser_fake_pumas.py create mode 100644 tests/browser_project_workspace_endpoint.cjs diff --git a/app.py b/app.py index f6689868..7c787753 100644 --- a/app.py +++ b/app.py @@ -808,6 +808,7 @@ def _get(self): '/project-workspace/inside.js': ('project-workspace/inside.js', 'text/javascript'), '/project-workspace/weights.js': ('project-workspace/weights.js', 'text/javascript'), '/project-workspace/annotate.js': ('project-workspace/annotate.js', 'text/javascript'), + '/project-workspace/generate.js': ('project-workspace/generate.js', 'text/javascript'), '/project-workspace/app.js': ('project-workspace/app.js', 'text/javascript'), '/static/vendor/ubuntu-sans/UbuntuSans[wdth,wght].ttf': ('vendor/ubuntu-sans/UbuntuSans[wdth,wght].ttf', 'font/ttf'), '/static/vendor/ubuntu-sans/UbuntuSans-Italic[wdth,wght].ttf': ('vendor/ubuntu-sans/UbuntuSans-Italic[wdth,wght].ttf', 'font/ttf'), diff --git a/docs/contracts/project-folder.md b/docs/contracts/project-folder.md index 3b44f8bc..e49dd9f4 100644 --- a/docs/contracts/project-folder.md +++ b/docs/contracts/project-folder.md @@ -2161,7 +2161,11 @@ The page at `/` is the Map workspace: the tabs Map, Data, Annotate, Train, Benchmarks, Analysis and Overview over the project, read through the operations below. Annotate shows a task's records, one in its viewer, and the task's form, which keeps an annotation with `set_annotation`; Save writes the unsaved -annotations with the unsaved definitions. +annotations with the unsaved definitions. Its Suggest asks `suggest_annotation` +of a model `suggestion_models` offers and fills the form, and a kept +suggestion passes its `from`. Train shows the machine's Pumas endpoint +(`endpoint`; for the owner `set_endpoint` and `find_endpoints`), and Data's +Generate form keeps a dataset whose run is the step `generate`. Each of its controls calls one operation and is drawn only for a session that may call it, so a credential that may only inspect sees a page that changes nothing. The report is linked from the Overview tab. The page reads again diff --git a/docs/plans/definition-first-projects/spec-d5.md b/docs/plans/definition-first-projects/spec-d5.md index b8e57b47..73701fee 100644 --- a/docs/plans/definition-first-projects/spec-d5.md +++ b/docs/plans/definition-first-projects/spec-d5.md @@ -138,3 +138,18 @@ Section 4's table, as built: - **Tests:** `tests/test_tuldok_project_pumas.py`, 29: the check (4), the settings file (2), the routes and offers from descriptors alone (2), `endpoint`/`find_endpoints` on the fake with the scanner patched (3), and against a database: the setting set, cleared, refused and its activity (3), a text dataset and an image dataset from a dataset of prompts with `per` and seeds generated by `builds.execute`, an option, a model and a capability each failing before any request, `not_admitted` asked again twice then failing, another failure failing at once at item 2 (5), each row of the table, answers not made of terms or not in the vocabulary refused, no model fitting, and a kept suggestion's `from` in the saved line (8), and the step alone (2). `test_tuldok_project_service.py`: 59 operations, `set_endpoint` a mutation, `set_endpoint` and `find_endpoints` the owner's, the new reads in `test_every_read`. The catalog profile's digest is unchanged; the project_folder profile has the five new operations. - **Not verified:** a real Pumas (the owner's word is needed, section 7); a decision model's, a Torch transcription runtime's and a vision model's real answers (the fake answers what the contract describes); `https` and host-name addresses (refused); cancelling a generate during a request (the launcher's cancel stops the process, as for any run; not tested here); 100,000 items; a JPEG or stereo sound sent for a suggestion; the page (D5c). + +### D5c, the page + +What differs from section 5, and what was chosen where it was silent. + +- **A new script, `static/project-workspace/generate.js`** (`window.LabGenerate`), holds the endpoint on Train and the Generate form; Suggest is in `annotate.js`, since it fills that tab's drafts. `app.py`'s asset list and `project-workspace.html` gain the script. `annotate.js` exports its drawer-form parts (`forms`: `formDrawer`, `input`, `choice`, `header`, `slug`, `textOf`) and `tabs.js` its `drawer` (`S.drawer`), so the Generate form and the endpoint's drawer are drawn as Import, Freeze and an environment's drawer are. +- **The endpoint on Train** is a section after Environments: a row with its state (answers, does not answer, not set), its address and version, and every served (model, profile) with what it takes and makes (from `modalities`), what a dataset can be made of with it (`makes`, with each option's bounds and whether it takes a seed), its available capabilities with their formats and its unavailable ones with their reasons. The owner's controls are in the endpoint's drawer (`#train/endpoint`), as an environment's are in its own: an address field and Set, Find on this machine (its list, each with Use this, kept until the page is left), Clear the endpoint (two presses), and Ask it again (anyone; forgets the answer and reads again). Refusals are shown under the control in the server's words. A session that is not the owner's sees the drawer without them. +- **The endpoint's answer is not watched.** It is read with the Train tab and forgotten, as every answer that is not watched, when a reading finds something changed or after a control's answer. An endpoint that stops answering while nothing else in the project changes is shown as answering until then, or until Ask it again; reading it on every timer would ask the endpoint every 15 seconds and break spec-w4 R1's list of what is watched. +- **The Generate form.** What to make lists `text` and `image` only when some served model `makes` it; the model select lists the (model, profile) entries that make it, with the capability. The profile is written when `profile_required` is true *or* the endpoint serves the model with more than one profile (the step needs it then too); a line in the form says so. The options are the chosen `makes` entry's, each a number field with the advertised `minimum` and `maximum`, in the order the contract names them (`max_tokens`, `temperature`, `top_p`, `width`, `height`, then others by name; the answer holds them in key order). The seed field appears only when the entry takes one. Before the definition is sent the page refuses, in the form's refusal style: a count, `per` or seed that is not a whole number or is outside its bounds, an option outside its bounds, and a missing `width` or `height` for an image (the contract requires both; `makes` does not say which options are required, so these two are known to the page). An empty option or seed is not written; `per` is written only when it is not 1. The settings are written in the contract's order: `make`, `model`, `profile`, `prompt`, `count` or `per`, `seed`, `options`, `rights`; the run is `step`, `inputs`, `settings`. Any dataset may be chosen as prompts (whether its product holds text records is the step's to say). With no endpoint, one that does not answer, or nothing that can be made, the form says which and why, and its one button goes to `#train/endpoint`. +- **Suggest** is drawn above the form's fields, for a session that may edit, a record in the product, and a task of type `text`, `class` or `tags` whose `suggestion_models` lists a model for the record's kind (`suggestion_models` is read only for those, with the other answers of the tab). The model is a select of the offers for that kind; the choice is remembered per task and kind of record while the page is open. While asked, the button reads "Asking …" and Cancel drops the answer when it comes; **the endpoint is not told**: no operation stops a suggestion, so the server's request runs to its end (at most 300 s). A suggestion fills the record's draft (what was decided and noted stays) and keeps its `from`; the mark reads "Suggested by · ()" while the value is the one suggested and "Changed from the suggestion of …" once the person changes it; Keep and next sends `from` with `set_annotation` in both cases, as the server's own test does. A refusal is shown in the suggestion box, with the server's sentence (for `unsuitable`, the model's words) and "No suggestion: the form is as it was."; the fields are not drawn again. +- **Suggest for this page** is in the same box (so it is reached from a record whose kind some model fits). It asks for the records of the page on screen that are in the product, have no annotation, no typed draft in the page, and a kind some model fits, each with the model chosen for its kind (or the first offered), one after another; each answer is kept at once with `set_annotation` as a `draft` carrying its `from`, and the page reads again after each, so the grid shows the drafts as they come. The line under it says "Asking for 3 of 12 records · 2 kept, 0 refused", Stop ends it after the request in flight (whose answer is then dropped), and at the end it says "Done." or "Stopped." with how many were kept and refused and the first refusal. Single Suggest is disabled while it runs. +- **Updating in place.** The suggestion box is put in place on its own when its state changes (asking, cancelled, refused, the page's progress), and the form is drawn again only when a suggestion fills it. The Generate form is a drawer form like Import and Freeze; its parts that depend on a choice (what to make, the model, a count or prompts) are drawn again in place from the group's slot, so nothing typed is lost. +- **`docs/contracts/project-folder.md`:** the paragraph on the page names Suggest, the endpoint on Train and the Generate form. +- **The check,** `tests/browser_project_workspace_endpoint.cjs`, starts the fake through a new helper, `tests/browser_fake_pumas.py` (the listing of `test_tuldok_project_pumas.py`, advertising 0.8.0, answers set by lines on its stdin), and starts Tuldok through a `python -c` launcher that replaces `gateway_discovery.listening_endpoints` with a list holding the fake's port alone before `app.py` runs, so Find on this machine is exercised end to end without scanning this machine; no server code changed for it. It does what section 7 asks, and also: an address that does not answer refused (`unavailable`), the settings file written and cleared, a refused Keep (a missing height) with nothing typed lost, the image dataset from a dataset of prompts written exactly as expected, Cancel while the fake holds its answer, the Suggest for this page counts with one refusal arranged (`unknown` from the fake), the endpoint's drawer kept across a focus and a timer reading with an address typed, and 32 screenshots in light and dark at 1440 × 900 and 1000 × 800 with nothing overflowing sideways. +- **Not covered by the check:** a session that may only inspect or edit (the owner's controls hidden, Suggest hidden without edit); keyboard-only use of the new controls (they are ordinary buttons, selects and fields with the page's focus ring, not driven by keys in the check); the image dataset built (only its definition is checked; the text one is built through the page); a suggestion for an image or a sound asked singly from the page (an image is asked by Suggest for this page); Stop during Suggest for this page; a model that needs its profile written into a definition (the line is checked, the text is not); the real scanner of this machine and a real Pumas. diff --git a/static/project-workspace.html b/static/project-workspace.html index f317eb1d..5630f103 100644 --- a/static/project-workspace.html +++ b/static/project-workspace.html @@ -19,6 +19,7 @@ + diff --git a/static/project-workspace/annotate.js b/static/project-workspace/annotate.js index d7cb0ed4..857f5494 100644 --- a/static/project-workspace/annotate.js +++ b/static/project-workspace/annotate.js @@ -25,6 +25,7 @@ window.LabAnnotate = (() => { const FILTERS = [['all', 'All'], ['todo', 'To do'], ['accepted', 'Accepted'], ['needs-work', 'Needs work'], ['rejected', 'Rejected'], ['stale', 'Stale']]; const DECISIONS = [['accepted', 'Accept', 'ok'], ['needs-work', 'Needs work', 'warn'], ['rejected', 'Reject', 'bad']]; const STATE = { none: ['neutral', 'not annotated'], draft: ['neutral', 'draft'], accepted: ['good', 'accepted'], 'needs-work': ['warn', 'needs work'], rejected: ['serious', 'rejected'] }; + const SUGGESTS = ['text', 'class', 'tags']; // the tasks a served model can suggest a value of (spec-d5 section 4) const FORMAT = 'tuldok_definition_v1'; const count = (n, one, many) => n.toLocaleString('en-GB') + ' ' + (n === 1 ? one : many || one + 's'); const button = (cls, text, key, onClick) => { const b = h('button', cls, text); b.type = 'button'; if (key) b.dataset.key = key; if (onClick) b.addEventListener('click', onClick); return b; }; @@ -82,7 +83,9 @@ window.LabAnnotate = (() => { let id = ui.sel.get(t.task); if (!page.records.some(r => r.id === id)) id = page.records.length ? page.records[ui.selAt === -1 ? page.records.length - 1 : 0].id : null; ui.selAt = 0; if (id) ui.sel.set(t.task, id); else ui.sel.delete(t.task); - return { tasks, t, page, rec: page.records.find(r => r.id === id) || null }; + // The models that can suggest (spec-d5 section 4), for a session that may annotate; none when they cannot be read. + const offers = A.may('edit') && SUGGESTS.includes(t.type) ? await P.read('suggestion_models', { task: t.task }).then(r => r.kinds || {}, () => ({})) : {}; + return { tasks, t, page, rec: page.records.find(r => r.id === id) || null, offers }; } // ---- The tab ----------------------------------------------------------------------------------------------------- @@ -114,7 +117,7 @@ window.LabAnnotate = (() => { if (kind === 'records') { keys.list = JSON.stringify([t.task, t.run, ui.filter, ui.page, got.page.total, got.page.records.map(r => [r.id, r.kind, r.path, r.preview || null, r.in_product, r.annotation && [r.annotation.state, r.annotation.stale, r.annotation.unsaved]])]); keys.view = rec ? JSON.stringify([t.task, t.type, t.run, rec.id, rec.kind, rec.in_product]) : 'none'; // its place in the list is set in place (place()) - keys.form = rec ? JSON.stringify([t.task, t.type, t.vocabulary, rec.id, rec.kind, rec.in_product, rec.annotation, may]) : 'none'; + keys.form = rec ? JSON.stringify([t.task, t.type, t.vocabulary, rec.id, rec.kind, rec.in_product, rec.annotation, may, (got.offers || {})[rec.kind] || []]) : 'none'; const same = here.rec && rec && here.t && here.t.task === t.task && here.rec.id === rec.id; if (same && here.keys.form && keys.form !== here.keys.form && (drafts.get(draftKey(t, rec)) || {}).dirty) keys.form = here.keys.form; // what is typed stays } else keys.msg = JSON.stringify([kind, t && [t.task, t.dataset], may, got.error ? got.error.message : null]); @@ -126,7 +129,7 @@ window.LabAnnotate = (() => { } catch (error) { build.view = h('div', 'iv'); build.view.appendChild(A.refusal(error)); } if (main._paint !== mine || main._view !== view) return; main.removeAttribute('aria-busy'); - here.t = t; here.page = got.page || null; here.rec = rec; here.tasks = got.tasks; + here.t = t; here.page = got.page || null; here.rec = rec; here.tasks = got.tasks; here.offers = got.offers || {}; const fresh = !here.root || keys.shape !== here.keys.shape; if (fresh) { const root = h('div', 'annotate'); root.dataset.shape = kind; @@ -153,6 +156,7 @@ window.LabAnnotate = (() => { } else put('msg', () => buildMessage(kind, t, got.error)); if (fresh) putInPlace(main, here.root); main._painted = view; + if (here.focusAfter) { const k = here.focusAfter; here.focusAfter = null; A.focusKey(k); } if (here.focusSel) { here.focusSel = false; const b = here.root.querySelector('.rec[aria-pressed="true"]'); if (b) b.focus(); } } @@ -285,6 +289,7 @@ window.LabAnnotate = (() => { function touch(list = true) { const d = cur(); if (!d) return; d.dirty = true; const m = here.root && here.root.querySelector('.ann-form .umark'); if (m && m.textContent !== 'not kept yet') { m.textContent = 'not kept yet'; m.classList.add('typed'); } + if (d.from) markSuggestion(d); if (list && here.relist) here.relist(); if (here.repaint) here.repaint(); } @@ -538,6 +543,7 @@ window.LabAnnotate = (() => { box.appendChild(h('p', 'small', rec.in_product ? 'The annotation as it was made is below. Still right keeps it for the content as it is now; or change it and keep it.' : 'Remove the annotation, or keep it until the record comes back.')); form.appendChild(box); } + if (may && rec.in_product && ((here.offers || {})[rec.kind] || []).length) { const sb = h('div', 'ann-suggestbox'); sb.appendChild(suggestBox(t, rec)); form.appendChild(sb); } const f = h('div', 'form ann-fields'); if (!rec.in_product) f.appendChild(h('p', 'note', 'Nothing can be set on a record that is not in the product.')); else if (rec.kind === 'file') f.appendChild(h('p', 'note', 'A file of no kind cannot be annotated.')); @@ -560,7 +566,7 @@ window.LabAnnotate = (() => { const k = draftKey(t, rec), after = () => { drafts.delete(k); }; form.appendChild(A.group('annotate:form', [ { id: 'keep', label: 'Keep and next', cls: 'btn primary', who: 'edit', op: 'set_annotation', busy: 'Keeping…', hidden: !rec.in_product, title: 'Enter', - args: () => ({ task: t.task, items: [itemOf(t, rec, d)] }), done: () => { after(); move(1); } }, + args: () => Object.assign({ task: t.task, items: [itemOf(t, rec, d)] }, d.from ? { from: d.from } : {}), done: () => { after(); move(1); } }, { id: 'skip', label: 'Skip', cls: 'btn ghost', onClick: () => { if (move(1)) redraw(); } }, { id: 'still', label: 'Still right', cls: 'btn', who: 'edit', op: 'set_annotation', busy: 'Keeping…', hidden: !(a && a.stale && rec.in_product), args: () => ({ task: t.task, items: [Object.assign({ record: rec.id, state: a.state, value: a.value }, a.note ? { note: a.note } : {})] }), done: after }, @@ -641,6 +647,115 @@ window.LabAnnotate = (() => { return ul; } + // ---- Suggestions (spec-d5 section 4) ---------------------------------------------------------------------------- + // Suggest asks the chosen model (suggestion_models' offers for the record's kind) for a value of the task for the + // record on screen. The answer fills the record's draft with its `from`, marked as the model's suggestion until the + // person changes or keeps it; Keep sends `from` with set_annotation, so the saved line names the model. Cancel drops + // the answer when it comes (the endpoint is not told: no operation stops a suggestion). A refusal is shown beside the + // form, which is left as it was. Suggest for this page asks, one record after another, for the records on screen that + // have no annotation and no typed draft, and keeps each answer as a draft with its `from`. The model chosen is + // remembered per task and kind of record while the page is open. A reading never asks anything. + const sug = { choice: new Map(), asking: null, refusals: new Map(), batch: null, said: new Map(), turn: 0 }; + const offerKey = o => o.model + '\u0000' + o.profile; + /** The model chosen for the task and kind: the one picked while the page is open, else the first offered. */ + function chosen(t, kind) { const list = (here && here.offers || {})[kind] || [], k = sug.choice.get(t.task + '\n' + kind); return list.find(o => offerKey(o) === k) || list[0] || null; } + const fromWords = f => f.model + ' · ' + f.profile; + function suggestionLine(d) { + const same = JSON.stringify(valueOf(here.t, d)) === d.fromValue; + return [same ? 'Suggested by ' + fromWords(d.from) + ' (' + d.from.capability + '): check it, change it or keep it.' : 'Changed from the suggestion of ' + fromWords(d.from) + '; kept, the line still names it.', same]; + } + /** Sets the suggestion's mark in place: a suggestion, or one the person changed. */ + function markSuggestion(d) { + const m = here.root && here.root.querySelector('.ann-form .ann-sugmark'); if (!m) return; + const [text, same] = suggestionLine(d); + if (m.textContent !== text) m.textContent = text; + if (m.classList.contains('changed') === same) m.classList.toggle('changed', !same); + } + function suggestBox(t, rec) { + const box = h('div', 'ann-suggest'), list = here.offers[rec.kind] || [], k = draftKey(t, rec), d = drafts.get(k); + const asking = sug.asking && sug.asking.key === k ? sug.asking : null, batch = sug.batch && sug.batch.task === t.task ? sug.batch : null; + const row = h('div', 'ann-suggest-row'); + const l = h('label', 'ann-suggest-model'); l.appendChild(document.createTextNode('Suggest with')); + const sel = h('select'); sel.dataset.key = 'ann:suggest-model'; const pick = chosen(t, rec.kind); + for (const o of list) { const op = h('option', null, fromWords(o) + ' (' + o.capability + ')'); op.value = offerKey(o); op.selected = !!pick && offerKey(o) === offerKey(pick); sel.appendChild(op); } + sel.disabled = !!asking || !!batch; + sel.addEventListener('change', () => { sug.choice.set(t.task + '\n' + rec.kind, sel.value); }); + l.appendChild(sel); row.appendChild(l); + if (asking) { + const b = button('btn sm', 'Asking ' + asking.model + '…', 'ann:suggest'); b.disabled = true; b.setAttribute('aria-busy', 'true'); row.appendChild(b); + row.appendChild(button('btn sm ghost', 'Cancel', 'ann:suggest-cancel', () => { sug.asking = null; reboxed(t, rec, 'ann:suggest'); })); + } else { const b = button('btn sm', 'Suggest', 'ann:suggest', () => ask(t, rec)); b.disabled = !!batch || !!sug.asking; row.appendChild(b); } + box.appendChild(row); + if (d && d.from) { const [text, same] = suggestionLine(d); const m = h('p', 'small ann-sugmark' + (same ? '' : ' changed'), text); m.setAttribute('role', 'status'); box.appendChild(m); } + const refusal = sug.refusals.get(k); + if (refusal) { const r = A.refusal(refusal); r.classList.add('ann-sugrefusal'); r.insertBefore(h('p', 'small', 'No suggestion: the form is as it was.'), r.children[1] || null); box.appendChild(r); } + const page = h('div', 'ann-suggest-row ann-batch'); + if (batch) { + const line = h('span', 'small ann-batch-line', batchWords(batch)); line.setAttribute('role', 'status'); page.appendChild(line); + const stop = button('btn sm ghost', batch.stop ? 'Stopping…' : 'Stop', 'ann:suggest-stop', () => { batch.stop = true; reboxed(t, rec, 'ann:suggest-stop'); }); stop.disabled = batch.stop; page.appendChild(stop); + } else { + const b = button('btn sm', 'Suggest for this page', 'ann:suggest-page', () => suggestPage(t)); b.disabled = !!sug.asking; page.appendChild(b); + const said = sug.said.get(t.task); + page.appendChild(h('span', 'small faint ann-batch-line', said || 'Asks for each record on this page with no annotation, one after another, and keeps each answer as a draft.')); + } + box.appendChild(page); + return box; + } + const shows = (t, rec) => !!(here && here.root && here.root.isConnected && here.t && here.rec && here.t.task === t.task && here.rec.id === rec.id); + /** The suggestion part of the form on screen, drawn again in place; the focus goes to focus when it was lost. */ + function reboxed(t, rec, focus) { + if (!shows(t, rec)) return; + const w = here.parts.form && here.parts.form.querySelector('.ann-suggestbox'); if (!w) return; + const r = putInPlace(w, suggestBox(t, rec)); + if (focus && (!r.inside || !r.found || document.activeElement === document.body)) A.focusKey(focus); + } + const rebox = focus => { if (here && here.t && here.rec) reboxed(here.t, here.rec, focus); }; + async function ask(t, rec) { + const o = chosen(t, rec.kind); if (!o || sug.asking || sug.batch) return; + const k = draftKey(t, rec), mine = { key: k, model: o.model, n: ++sug.turn }; + sug.asking = mine; sug.refusals.delete(k); reboxed(t, rec, 'ann:suggest-cancel'); + let got = null, error = null; + try { got = await P.call('suggest_annotation', { task: t.task, record: rec.id, model: o.model, profile: o.profile }); } catch (e) { error = e; } + if (sug.asking !== mine) return; // cancelled: the answer is dropped + sug.asking = null; + if (error) { sug.refusals.set(k, error); reboxed(t, rec, 'ann:suggest'); return; } + fill(t, rec, got.suggestion); + if (shows(t, rec)) { here.keys.form = null; here.focusAfter = 'ann:suggest'; redraw(); } + } + /** The suggestion in the record's draft, with its `from`; what was decided and noted stays. */ + function fill(t, rec, s) { + const d = draftOf(t, rec); + if (t.type === 'text') d.value = typeof s.value === 'string' ? s.value : ''; + else if (t.type === 'class') d.value = typeof s.value === 'string' ? s.value : null; + else if (t.type === 'tags') d.value = Array.isArray(s.value) ? s.value.slice() : []; + d.from = s.from; d.fromValue = JSON.stringify(valueOf(t, d)); d.dirty = true; + } + const batchWords = b => 'Asking for ' + Math.max(1, b.at) + ' of ' + count(b.total, 'record') + ' · ' + b.kept + ' kept, ' + b.refused + ' refused'; + function progress(b) { const line = here && here.root && here.root.querySelector('.ann-form .ann-batch-line'); const text = batchWords(b); if (line && line.textContent !== text) line.textContent = text; } + /** Suggest for this page: each record on screen with no annotation and no typed draft, one after another, kept as a draft. */ + async function suggestPage(t) { + if (sug.batch || sug.asking || !here.page) return; + const todo = here.page.records.filter(r => r.in_product && !r.annotation && chosen(t, r.kind) && !(drafts.get(draftKey(t, r)) || {}).dirty); + const b = sug.batch = { task: t.task, total: todo.length, at: 0, kept: 0, refused: 0, first: null, stop: false }; + sug.said.delete(t.task); rebox('ann:suggest-stop'); + for (const r of todo) { + if (b.stop) break; + b.at++; progress(b); + const o = chosen(t, r.kind); + try { + const got = await P.call('suggest_annotation', { task: t.task, record: r.id, model: o.model, profile: o.profile }); + if (b.stop) break; // stopped while it was asked: the answer is dropped + await P.call('set_annotation', { task: t.task, from: got.suggestion.from, items: [{ record: r.id, state: 'draft', value: got.suggestion.value }] }); + b.kept++; + P.forgetBut(P.WATCHED); here.act.refresh(); // the grid shows the new draft + } catch (error) { b.refused++; if (!b.first) b.first = r.id + ': ' + error.message; } + progress(b); + } + sug.batch = null; + sug.said.set(t.task, (b.stop ? 'Stopped. ' : 'Done. ') + 'Kept ' + count(b.kept, 'draft') + ', ' + b.refused + ' refused, of ' + count(b.total, 'record') + ' with no annotation' + (b.first ? '. First refused: ' + b.first : '.')); + rebox('ann:suggest-page'); + } + // ---- Keys -------------------------------------------------------------------------------------------------------- function onKey(e) { if (e.defaultPrevented || e.altKey || e.ctrlKey || e.metaKey || !here || !here.root || !here.root.isConnected || !here.rec) return; @@ -813,5 +928,7 @@ window.LabAnnotate = (() => { function choose(task) { ui.task = task; ui.page = 0; ui.filter = 'all'; } S.annotate = annotate; - return { choose, datasetForm }; + // The drawer forms' parts, for the Generate form (generate.js). + const forms = { formDrawer, input, choice, header, slug, textOf }; + return { choose, datasetForm, forms }; })(); diff --git a/static/project-workspace/base.css b/static/project-workspace/base.css index b1b31209..bfdfcddf 100644 --- a/static/project-workspace/base.css +++ b/static/project-workspace/base.css @@ -522,6 +522,7 @@ textarea { font: inherit; resize: vertical; } .rows > li.with-act > .row { flex: 1 1 auto; min-width: 0; } .rows > li.with-act > .act-group { flex: none; margin-right: 8px; } .sect .act-group { align-self: center; } +.sect .act-group .btn { white-space: nowrap; } .hair { position: relative; display: inline-block; width: 120px; height: 2px; background: var(--grid); flex: none; vertical-align: middle; } .hair i { position: absolute; left: 0; top: 0; bottom: 0; background: var(--accent); } .progress-line { display: flex; align-items: center; gap: 10px; flex-wrap: wrap; } @@ -791,3 +792,35 @@ tr.wts-row:has(+ tr.wts-open) > td { background: var(--accent-wash); } .ann-stale p:first-child { color: var(--serious); font-weight: 500; } .ann-empty { display: grid; gap: 12px; justify-items: start; } .ann-new .form h3 { margin: 4px 0 0; } + +/* ---- The Pumas endpoint (generate.js): on Train beside the environments, the Generate form, and Suggest (annotate.js). ---- */ +.ep-models > li.ep-model { display: grid; grid-template-columns: minmax(150px, 220px) minmax(0, 1fr) minmax(120px, 190px); gap: 12px; align-items: start; padding: 8px 8px; } +.ep-model > span { min-width: 0; } +.ep-model .title, .ep-model .sub { display: block; } +.ep-model .title { font-weight: 500; overflow-wrap: anywhere; } +.ep-model .title.mono { font-family: var(--mono); font-size: 13px; } +.ep-model .sub { color: var(--ink-2); font-size: 12.5px; overflow-wrap: anywhere; } +.ep-model .sub.mono { font-family: var(--mono); font-size: 12px; color: var(--ink-3); } +.ep-model .ep-makes b { font-weight: 500; color: var(--ink); } +.ep-model .ep-off { color: var(--ink-3); } +.ep-model .ep-load { text-align: right; } +@media (max-width: 1100px) { .ep-models > li.ep-model { grid-template-columns: minmax(120px, 170px) minmax(0, 1fr); } .ep-model .ep-load { grid-column: 2; text-align: left; } } +.row.ep-row .sub { white-space: normal; } +.ep-part { display: grid; gap: 6px; } +.ep-part .note { margin: 0; } +.ep-found { display: grid; gap: 6px; } +.ep-found .rows { margin-top: 4px; } +.ep-found .row.ep-hit { cursor: default; } +.gen-form .gen-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(150px, 1fr)); gap: 10px; align-items: start; } +.gen-form .gen-line { margin: -4px 0 0; } +.gen-form .ann-field h3 { margin: 4px 0 0; } +.gen-none { display: grid; gap: 10px; justify-items: start; } +.ann-suggest { display: grid; gap: 8px; padding: 9px 10px; border: 1px solid var(--line); border-radius: var(--radius); background: var(--surface-2); min-width: 0; } +.ann-suggest-row { display: flex; flex-wrap: wrap; gap: 8px; align-items: center; min-width: 0; } +.ann-suggest-model { display: inline-flex; flex-wrap: wrap; gap: 6px; align-items: center; font-size: 12.5px; color: var(--ink-2); min-width: 0; flex: 1 1 200px; } +.ann-suggest-model select { min-width: 0; max-width: 100%; flex: 1 1 140px; font: inherit; font-size: 13px; color: var(--ink); background: var(--surface); border: 1px solid var(--line-strong); border-radius: var(--radius); padding: 3px 6px; } +.ann-sugmark { margin: 0; padding: 2px 0 2px 8px; border-left: 3px solid var(--accent); color: var(--ink); overflow-wrap: anywhere; } +.ann-sugmark.changed { border-left-color: var(--ink-3); color: var(--ink-2); font-weight: 400; } +.ann-batch { border-top: 1px solid var(--line); padding-top: 8px; } +.ann-batch .ann-batch-line { flex: 1 1 180px; min-width: 0; overflow-wrap: anywhere; font-variant-numeric: tabular-nums; } +.ann-sugrefusal { font-size: 12.5px; } diff --git a/static/project-workspace/generate.js b/static/project-workspace/generate.js new file mode 100644 index 00000000..b5814394 --- /dev/null +++ b/static/project-workspace/generate.js @@ -0,0 +1,258 @@ +'use strict'; +// The Pumas endpoint on the page (docs/plans/definition-first-projects/spec-d5.md section 5): the endpoint on the Train +// tab, beside the environments (its address, whether it answers, its version and the models it serves with what each +// takes and makes; for the owner, Set, Clear and Find on this machine in its drawer), and the Data tab's Generate form, +// which keeps a new dataset whose run is the step generate as an unsaved edit, as Import and Freeze do (annotate.js). +// Everything offered comes from the answer of `endpoint` at that moment: what to make is only what some served model +// makes, a model only one that makes it, an option only one its capability declares, with the advertised bounds as the +// field's minimum and maximum. Building the dataset is the existing plan and request. Suggest on the Annotate tab is +// annotate.js's. +// +// Updating in place (spec-w4): the endpoint's answer is not watched; it is read with the Train tab and forgotten, as +// every answer not watched, when a reading finds something changed (or after a control's answer), so the section is +// drawn again in place only then. Its drawer is drawn again in place the same way, its typed address kept in its +// group's slot (actions.js). The Generate form is a drawer form like Import and Freeze: never touched by a reading on +// the timer or on focus, its text kept in its group's slot. +window.LabGenerate = (() => { + const P = window.TuldokProject, S = window.LabScreens, A = window.LabActions, h = window.LabCharts.h; + const { sect, putInPlace, block } = S.parts; + const FORMAT = 'tuldok_definition_v1'; + const MAKE_WORD = { text: 'Texts', image: 'Images (PNG)' }; + const REQUIRED = { image: ['width', 'height'] }; // the options a generate of this kind cannot do without (docs/contracts/project-folder.md) + const button = (cls, text, key, onClick) => { const b = h('button', cls, text); b.type = 'button'; if (key) b.dataset.key = key; if (onClick) b.addEventListener('click', onClick); return b; }; + const num = v => Number.isInteger(v) ? v.toLocaleString('en-GB') : String(v); + const bound = b => num(b.minimum) + ' to ' + num(b.maximum); + const listed = xs => xs.length < 2 ? xs.join('') : xs.slice(0, -1).join(', ') + ' and ' + xs[xs.length - 1]; + const entryKey = m => m.model + '\u0000' + m.profile; + // The options of a capability in the order the contract names them (the server's answer holds them in key order). + const ORDER = ['max_tokens', 'temperature', 'top_p', 'width', 'height']; + const rank = n => { const i = ORDER.indexOf(n); return i < 0 ? ORDER.length : i; }; + const optionsOf = made => Object.entries(made.options).sort(([a], [b]) => rank(a) - rank(b) || (a < b ? -1 : a > b ? 1 : 0)); + const forms = () => window.LabAnnotate.forms; + + // ---- What the endpoint answer says, in words ------------------------------------------------------------------- + /** {tone, word, line}: the endpoint's state in one mark and one sentence. */ + function standing(ep) { + if (ep.error) return { tone: 'serious', word: 'not read', line: ep.error.message }; + if (!ep.address) return { tone: 'warn', word: 'not set', line: 'No Pumas endpoint is set on this machine, so nothing can be generated or suggested here.' }; + if (!ep.answered) return { tone: 'serious', word: 'does not answer', line: ep.problem || 'It did not answer.' }; + return { tone: 'good', word: 'answers', line: (ep.version ? 'Pumas ' + ep.version : 'Version not reported') + ' · ' + ep.models.length + (ep.models.length === 1 ? ' model' : ' models') + ' served' }; + } + /** The (model, profile) entries that can make a dataset now, by what they make. */ + function makers(ep) { + const by = {}; + if (ep && !ep.error && ep.answered) for (const m of ep.models) for (const made of m.makes) (by[made.make] = by[made.make] || []).push({ m, made }); + return by; + } + /** Whether the profile has to be written: the endpoint says so, or it serves the model with more than one. */ + const needsProfile = (ep, m) => m.profile_required || ep.models.filter(x => x.model === m.model).length > 1; + + // ---- Train: the endpoint beside the environments ------------------------------------------------------------------ + /** The section of the Train tab: a row opening the endpoint's drawer, and the models it serves. */ + function section(frag, ep, sel, act) { + const st = standing(ep); + const head = sect('Pumas endpoint', 'a setting of this machine'); head.classList.add('gap'); + head.appendChild(h('span', 'spacer')); + head.appendChild(A.group('train:endpoint', [{ id: 'open', label: ep.address ? 'Change' : 'Set the endpoint', cls: 'btn sm', who: 'owner', onClick: () => act.select(sel === 'endpoint' ? null : 'endpoint') }], { inline: true })); + frag.appendChild(head); + const ul = h('ul', 'rows'), li = h('li'), r = button('row env ep-row', null, 'open-endpoint', () => act.select(sel === 'endpoint' ? null : 'endpoint')); + r.setAttribute('aria-pressed', String(sel === 'endpoint')); + r.appendChild(S.stateEl(st.tone, st.word)); + const t = h('span'); t.appendChild(h('span', 'title', ep.address || 'No endpoint set')); t.appendChild(h('span', 'sub' + (st.tone === 'serious' ? ' warnline' : ''), st.line)); r.appendChild(t); + r.appendChild(h('span', 'sub', ep.address ? 'generation and suggestions go here' : A.may('owner') ? 'set it to generate and suggest' : 'the owner sets it')); + li.appendChild(r); ul.appendChild(li); frag.appendChild(ul); + if (ep.error || !ep.answered) return; + if (!ep.models.length) { frag.appendChild(h('p', 'empty', 'The endpoint serves no model.')); return; } + const ml = h('ul', 'rows ep-models'); ml.setAttribute('aria-label', 'The models the endpoint serves'); + for (const m of ep.models) ml.appendChild(modelRow(m)); + frag.appendChild(ml); + } + /** One served (model, profile): what it takes and makes, what a dataset can be made of with it, its capabilities. */ + function modelRow(m) { + const li = h('li', 'ep-model'); li.dataset.model = m.model; li.dataset.profile = m.profile; + const who = h('span', 'ep-who'); who.appendChild(h('span', 'title mono', m.model)); who.appendChild(h('span', 'sub mono', m.profile + (m.profile_required ? ' · profile required' : ''))); li.appendChild(who); + const what = h('span', 'ep-what'); + what.appendChild(h('span', 'title', 'Takes ' + (listed(m.modalities.input) || 'nothing') + ' · makes ' + (listed(m.modalities.output) || 'nothing'))); + const makes = h('span', 'sub ep-makes'); + if (m.makes.length) { + makes.appendChild(h('b', null, 'A dataset of: ')); + makes.appendChild(document.createTextNode(m.makes.map(x => (x.make === 'image' ? 'images' : 'texts') + ' by ' + x.capability + (Object.keys(x.options).length ? ' (' + optionsOf(x).map(([k, b]) => k + ' ' + bound(b)).join(', ') + ')' : '') + (x.seed ? ', with a seed' : '')).join('; '))); + } else makes.textContent = 'No dataset can be made with it.'; + what.appendChild(makes); + const on = m.capabilities.filter(c => c.available), off = m.capabilities.filter(c => !c.available); + if (on.length) what.appendChild(h('span', 'sub ep-caps', 'Available: ' + on.map(c => c.capability + ' (' + c.input_formats.join(', ') + ' → ' + c.output_formats.join(', ') + ')').join(', '))); + if (off.length) what.appendChild(h('span', 'sub ep-off', 'Unavailable: ' + off.map(c => c.capability + (c.reason ? ' (' + c.reason + ')' : '')).join(', '))); + li.appendChild(what); + li.appendChild(h('span', 'sub ep-load', [m.provider, m.load_state, m.context_tokens ? m.context_tokens.toLocaleString('en-GB') + ' tokens' : null].filter(Boolean).join(' · '))); + return li; + } + + // ---- Train: the endpoint's drawer ----------------------------------------------------------------------------------- + let found = null; // the last answer of find_endpoints, shown until the page is left + /** The drawer: the endpoint's state; for the owner Set (an address), Clear and Find on this machine; Ask it again. */ + function drawer(aside, act) { + S.drawer(aside, 'endpoint', () => P.read('endpoint'), (ins, ep) => { + const st = standing(ep); + const hd = h('header'); hd.appendChild(h('span', 'kicker', 'Pumas endpoint · a setting of this machine')); + const t = h('h2', null, ep.address || 'No endpoint set'); t.tabIndex = -1; hd.appendChild(t); + const meta = h('div', 'ins-meta'); meta.appendChild(S.stateEl(st.tone, st.word)); hd.appendChild(meta); ins.appendChild(hd); + const dl = h('dl', 'setup'); const put = (k, v) => { dl.appendChild(h('dt', null, k)); dl.appendChild(h('dd', null, v)); }; + put('Address', ep.address || 'none'); put('Answers', ep.address ? (ep.answered ? 'yes' : 'no') : '—'); + if (ep.answered) { put('Version', ep.version || 'not reported'); put('Models', String(ep.models.length)); } + if (ep.problem && ep.address) put('Problem', ep.problem); + ins.appendChild(dl); + ins.appendChild(h('p', 'note', 'The address is kept in Tuldok\'s settings file on this machine, never in the project folder. Generation and suggestions go to it over HTTP; nothing of Pumas runs inside Tuldok.')); + ins.appendChild(A.group('endpoint:again', [{ id: 'again', label: 'Ask it again', cls: 'btn sm', onClick: () => { P.forget(['endpoint']); act.refresh(); } }])); + if (!A.may('owner')) { ins.appendChild(h('p', 'note', 'Only the owner of this Tuldok sets the endpoint.')); return; } + const set = h('div', 'ep-part'); set.appendChild(h('h3', null, ep.address ? 'Set another address' : 'Set the address')); + set.appendChild(h('p', 'note', 'A numeric loopback HTTP address, such as http://127.0.0.1:8765, without a path. Tuldok asks it once what it serves and keeps it only when it answers.')); + const f = h('div', 'form'); + f.appendChild(A.group('endpoint:set', [{ id: 'set', label: 'Set', cls: 'btn', who: 'owner', op: 'set_endpoint', busy: 'Asking it…', + input: { name: 'address', label: 'Address', placeholder: 'http://127.0.0.1:8765', max: 2048, always: true }, + args: s => ({ address: (s.text.address || '').trim() }) }])); + set.appendChild(f); ins.appendChild(set); + const find = h('div', 'ep-part'); find.appendChild(h('h3', null, 'Find on this machine')); + find.appendChild(h('p', 'note', 'Lists the Pumas endpoints that advertise themselves on this machine\'s loopback listeners, to pick from. Nothing is set until you pick one.')); + const list = h('div', 'ep-found'); + find.appendChild(A.group('endpoint:find', [{ id: 'find', label: 'Find on this machine', cls: 'btn', who: 'owner', op: 'find_endpoints', busy: 'Looking…', local: true, + done: r => { found = r; putInPlace(list, foundList()); } }])); + list.appendChild(foundList()); find.appendChild(list); ins.appendChild(find); + if (ep.address) ins.appendChild(A.group('endpoint:clear', [{ id: 'clear', label: 'Clear the endpoint', cls: 'btn ghost', who: 'owner', op: 'set_endpoint', args: () => ({ address: null }), busy: 'Clearing…', + confirm: 'Clear the endpoint of this machine: nothing can be generated or suggested here until one is set again. Nothing else changes.' }])); + }); + } + /** What Find on this machine found, each with Use this. */ + function foundList() { + const box = h('div'); + if (!found) return box; + if (!found.endpoints.length) box.appendChild(h('p', 'empty', 'No Pumas endpoint advertises itself on this machine.')); + else { + const ul = h('ul', 'rows'); + for (const e of found.endpoints) { + const li = h('li', 'with-act'); const t = h('span', 'row ep-hit'); t.style.gridTemplateColumns = 'minmax(0, 1fr)'; + const s = h('span'); s.appendChild(h('span', 'title mono', e.address)); s.appendChild(h('span', 'sub', [e.version ? 'Pumas ' + e.version : 'version not reported', e.component].filter(Boolean).join(' · '))); t.appendChild(s); li.appendChild(t); + li.appendChild(A.group('endpoint:use:' + e.address, [{ id: 'use', label: 'Use this', cls: 'btn sm', who: 'owner', op: 'set_endpoint', args: () => ({ address: e.address }), busy: 'Asking it…' }], { inline: true })); + ul.appendChild(li); + } + box.appendChild(ul); + } + for (const r of found.rejected || []) box.appendChild(h('p', 'small warnline', r.server_url + ' answered, but its advertisement was refused: ' + r.reason)); + return box; + } + + // ---- Data: the Generate form ------------------------------------------------------------------------------------------ + /** Generate: a new datasets/ whose run is the step generate, kept as an unsaved edit. */ + function form(aside, act) { + const F = forms(); + F.formDrawer(aside, 'data:new:generate', () => Promise.all([P.read('endpoint').catch(error => ({ error })), P.read('definitions', { kind: 'dataset' })]), (ins, [ep, defs]) => { + const key = 'newgenerate', s = A.slot(key), by = makers(ep), kinds = Object.keys(MAKE_WORD).filter(k => by[k]); + F.header(ins, 'new dataset · generate', 'Generate a dataset', + 'A dataset made by asking a model the Pumas endpoint serves, one request per item. It is built as any build is, on a machine with an endpoint set; a model need not make the same thing twice.'); + if (!kinds.length) { + const why = h('div', 'gen-none'); why.setAttribute('role', 'status'); + why.appendChild(h('p', 'failure', ep.error ? 'What the endpoint serves could not be read: ' + ep.error.message + : !ep.address ? 'No Pumas endpoint is set on this machine, so there is nothing to generate with.' + : !ep.answered ? 'The Pumas endpoint at ' + ep.address + ' does not answer: ' + (ep.problem || 'no reason was given.') + : 'The Pumas endpoint at ' + ep.address + ' serves ' + ep.models.length + (ep.models.length === 1 ? ' model' : ' models') + ', and none can make a text or an image now.')); + why.appendChild(h('p', 'note', 'Generate offers only what a served model can make at the moment the form is opened.')); + const acts = h('div', 'actions'); acts.appendChild(button('btn', 'The endpoint on the Train tab', 'gen:endpoint', () => act.go('train', 'endpoint'))); acts.appendChild(button('btn ghost', 'Cancel', 'gen:cancel', () => act.select(null))); + why.appendChild(acts); ins.appendChild(why); return; + } + const sets = defs.definitions.filter(d => !d.removed); + const box = h('div', 'form gen-form'); + const fields = () => { + const f = document.createDocumentFragment(); + let nameBox = null; + f.appendChild(F.input(s, key, 'title', 'Title (required)', { max: 200, onInput: () => { if (!s.text.nameTyped && nameBox) { nameBox.value = F.slug(s.text.title || ''); s.text.name = nameBox.value; } } })); + const nl = F.input(s, key, 'name', 'Name', { max: 120, hint: 'the file is datasets/.json', placeholder: 'made from the title', onInput: v => { s.text.nameTyped = !!v; } }); + nameBox = nl.querySelector('input'); if (!s.text.nameTyped) { nameBox.value = F.slug(s.text.title || ''); s.text.name = nameBox.value; } + f.appendChild(nl); + f.appendChild(F.choice(s, key, 'make', 'What to make', kinds.map(k => [k, MAKE_WORD[k]]), kinds[0], redraw)); + const offer = by[s.text.make]; + f.appendChild(F.choice(s, key, 'model', 'Model, of those that make ' + (s.text.make === 'image' ? 'images' : 'texts') + ' now', offer.map(({ m, made }) => [entryKey(m), m.model + ' · ' + m.profile + ' (' + made.capability + ')']), entryKey(offer[0].m), redraw)); + const { m, made } = offer.find(o => entryKey(o.m) === s.text.model); + if (needsProfile(ep, m)) f.appendChild(h('p', 'small faint gen-line', 'The profile ' + m.profile + ' is written with the model: ' + (m.profile_required ? 'the endpoint requires it.' : 'the endpoint serves ' + m.model + ' with more than one.'))); + const prompts = s.text.from === 'prompts'; + f.appendChild(F.input(s, key, 'prompt', 'Prompt (required)', { area: 3, max: 16000, placeholder: s.text.make === 'image' ? 'A picture of {text}, number {n}.' : 'Write line {n} of a short poem.' })); + f.appendChild(h('p', 'small faint gen-line', '{n} is replaced by the item\'s number from 1' + (prompts ? '; {text} by the text of the prompting record' : '; with a dataset of prompts, {text} by the text of the prompting record') + '. {{ and }} are written as braces.')); + const how = h('div', 'ann-field'); how.appendChild(h('h3', null, 'How many')); + const rd = h('div', 'radio'); rd.setAttribute('role', 'radiogroup'); rd.setAttribute('aria-label', 'How many'); + for (const [v, label] of [['count', 'A count'], ['prompts', 'One for each text record of a dataset of prompts']]) { + const l = h('label'), i = h('input'); i.type = 'radio'; i.name = 'gen-from'; i.value = v; i.checked = (s.text.from || 'count') === v; i.dataset.key = key + ':field:from-' + v; + i.addEventListener('change', () => { if (i.checked) { s.text.from = v; redraw(); } }); l.appendChild(i); l.appendChild(h('span', null, label)); rd.appendChild(l); + } + how.appendChild(rd); + if (!prompts) how.appendChild(numberField(s, key, 'count', 'Count (required)', { minimum: 1, maximum: 100000 }, { value: '10', step: 1 })); + else { + const two2 = h('div', 'two'); + if (!sets.length) two2.appendChild(h('p', 'failure', 'The project has no dataset to take prompts from.')); + else two2.appendChild(F.choice(s, key, 'prompts', 'The dataset of prompts', sets.map(d => [d.reference, d.title + ' · ' + d.reference]), sets[0].reference)); + two2.appendChild(numberField(s, key, 'per', 'For each record', { minimum: 1, maximum: 1000 }, { value: '1', step: 1, hint: 'how many for each of its text records' })); + how.appendChild(two2); + } + f.appendChild(how); + // The seed and the options, as the chosen capability declares them. + const opts = h('div', 'ann-field gen-opts'); opts.appendChild(h('h3', null, 'Options of ' + made.capability)); + const names = optionsOf(made).map(([n]) => n), need = REQUIRED[s.text.make] || []; + if (!names.length && !made.seed) opts.appendChild(h('p', 'note', made.capability + ' declares no option Tuldok can set; the endpoint\'s defaults apply.')); + const grid = h('div', 'gen-grid'); + if (made.seed) grid.appendChild(numberField(s, key, 'seed', 'Seed', { minimum: 0, maximum: 4294967295 }, { step: 1 })); + for (const n of names) grid.appendChild(numberField(s, key, 'opt:' + n, n + (need.includes(n) ? ' (required)' : ''), made.options[n], { step: 'any' })); + if (grid.children.length) opts.appendChild(grid); + const said = []; + if (made.seed) said.push('Item n is asked with the seed + n − 1; with no seed the endpoint chooses one.'); + if (names.length) said.push('An option left empty is not sent' + (need.length ? ', except ' + listed(need) + ', which an image needs' : '') + '. The bounds are what the endpoint advertises now' + (s.text.make === 'image' ? '; Tuldok asks for at most 2,048 pixels a side.' : '.')); + if (said.length) opts.appendChild(h('p', 'small faint gen-line', said.join(' '))); + f.appendChild(opts); + f.appendChild(F.input(s, key, 'rights', 'Rights (required)', { area: 2, max: 1000, hint: 'what may be done with what is made', placeholder: 'Made by a model; anything may be done with it.' })); + return f; + }; + const redraw = () => putInPlace(box, fields()); + box.appendChild(fields()); + ins.appendChild(box); + ins.appendChild(A.group(key, [ + { id: 'keep', label: 'Keep', cls: 'btn primary', who: 'edit', op: 'set_definition', busy: 'Keeping…', + args: st => { const o = by[st.text.make].find(x => entryKey(x.m) === st.text.model); return { reference: 'datasets/' + (st.text.name || '').trim(), text: F.textOf(generateDoc(st.text, o.m, o.made, needsProfile(ep, o.m))) }; }, + done: r => { act.select(r.reference); } }, + { id: 'back', label: 'Cancel', cls: 'btn ghost', onClick: () => act.select(null) } + ])); + ins.appendChild(h('p', 'note', 'Keep checks the definition and keeps it in Tuldok as an unsaved edit; Save writes it. Building it is planned and requested as any build is; an agent\'s request waits for the owner.')); + }); + } + /** A number field whose value lives in the slot; the bounds are its minimum and maximum. */ + function numberField(s, key, name, label, b, { value, step, hint } = {}) { + const l = forms().input(s, key, name, label, { type: 'number', value, hint: hint || bound(b) }); + const i = l.querySelector('input'); i.min = String(b.minimum); i.max = String(b.maximum); i.step = String(step || 'any'); i.inputMode = step === 1 ? 'numeric' : 'decimal'; + return l; + } + const refuse = text => { throw Object.assign(Error(text), { code: 'invalid' }); }; + /** A whole number or a number from the field's text, within its bounds; null when empty and not required. */ + function numberOf(text, label, b, whole, required) { + const raw = String(text == null ? '' : text).trim(); + if (!raw) { if (required) refuse(label + ' is required.'); return null; } + const v = Number(raw); + if (!Number.isFinite(v) || (whole && !Number.isInteger(v))) refuse(label + ' is ' + (whole ? 'a whole number' : 'a number') + '; "' + raw + '" is not.'); + if (v < b.minimum || v > b.maximum) refuse(label + ' ' + raw + ' is outside ' + bound(b) + '.'); + return v; + } + /** The definition a generate writes (docs/contracts/project-folder.md, Steps Tuldok provides). */ + function generateDoc(x, m, made, profile) { + const settings = { make: x.make, model: m.model }; + if (profile) settings.profile = m.profile; + settings.prompt = (x.prompt || '').trim(); + const prompts = x.from === 'prompts'; + if (prompts) { const per = numberOf(x.per, 'For each record', { minimum: 1, maximum: 1000 }, true, false); if (per !== null && per !== 1) settings.per = per; } + else settings.count = numberOf(x.count, 'The count', { minimum: 1, maximum: 100000 }, true, true); + if (made.seed) { const seed = numberOf(x.seed, 'The seed', { minimum: 0, maximum: 4294967295 }, true, false); if (seed !== null) settings.seed = seed; } + const options = {}, need = REQUIRED[x.make] || []; + for (const [n, b] of optionsOf(made)) { const v = numberOf(x['opt:' + n], n, b, ['max_tokens', 'width', 'height'].includes(n), need.includes(n)); if (v !== null) options[n] = v; } + if (Object.keys(options).length) settings.options = options; + settings.rights = (x.rights || '').trim(); + const run = { step: 'generate' }; + if (prompts) run.inputs = { prompts: x.prompts }; + run.settings = settings; + return { format: FORMAT, kind: 'dataset', title: (x.title || '').trim(), run }; + } + + return { section, drawer, form }; +})(); diff --git a/static/project-workspace/tabs.js b/static/project-workspace/tabs.js index ccd90145..565512f1 100644 --- a/static/project-workspace/tabs.js +++ b/static/project-workspace/tabs.js @@ -10,7 +10,8 @@ // only read. Train draws the controls of spec-w3.md section 3.1 (actions.js): // Plan build, a build request's Approve, Decline and Cancel, a run's Cancel // run and Stop, an environment's Check again, Connect and Disconnect, and it -// shows a running run live; it lists first what is planned (the page's drafts +// shows a running run live, and the machine's Pumas endpoint beside the environments (generate.js); +// it lists first what is planned (the page's drafts // and the models never built, spec-w3 section 3.2). Data's drawer has Edit; // the editor itself is editor.js's. Rule: the chrome holds no project words; titles, // metrics and text come from the project. @@ -346,11 +347,12 @@ function train(main, aside, state, act, data) { const sel = state.sel.train || null; paint(main, async () => { - const [recipes, runs, requests, envs] = await Promise.all([P.read('definitions', { kind: 'recipe' }), P.read('runs'), P.read('build_requests'), P.read('environments')]); + const [recipes, runs, requests, envs, endpoint] = await Promise.all([P.read('definitions', { kind: 'recipe' }), P.read('runs'), P.read('build_requests'), P.read('environments'), + window.LabGenerate ? P.read('endpoint').catch(error => ({ error })) : null]); const running = runs.runs.filter(r => r.state === 'running'); const progress = new Map(await Promise.all(running.map(r => P.call('progress', { run: r.id }).then(p => [r.id, p.event], () => [r.id, null])))); - return { recipes: recipes.definitions, runs: runs.runs, requests: requests.requests, envs: envs.environments, progress }; - }, (frag, { recipes, runs, requests, envs, progress }) => { + return { recipes: recipes.definitions, runs: runs.runs, requests: requests.requests, envs: envs.environments, progress, endpoint }; + }, (frag, { recipes, runs, requests, envs, progress, endpoint }) => { const g = graphFor(data.map), deviceOf = new Map(envs.map(e => [e.reference, e.device])); // Planned (spec-w3 section 3.2): the drafts of this page, then the models never built. const E = window.LabEditor, drafts = g.nodes.filter(m => m.draft); @@ -436,9 +438,12 @@ } frag.appendChild(ul); } + // The Pumas endpoint of this machine, beside the environments (spec-d5 section 5, generate.js). + if (endpoint) window.LabGenerate.section(frag, endpoint, sel, act); }); if (!sel) return closeDrawer(aside); - if (sel.startsWith('run:')) runDrawer(aside, sel, act, data); + if (sel === 'endpoint' && window.LabGenerate) window.LabGenerate.drawer(aside, act); + else if (sel.startsWith('run:')) runDrawer(aside, sel, act, data); else if (sel.startsWith('request:')) requestDrawer(aside, sel, act, data); else if (sel.startsWith('plan:')) A.planView(aside, sel, act.go, () => { const one = sel.slice(5); act.select(data.map.byId.has(one) ? one : null); }); else if (sel.startsWith('env:')) envDrawer(aside, sel, act, data); @@ -620,10 +625,11 @@ const built = sets.filter(d => byRef.has(d.reference)).length, adopted = sets.filter(d => (byRef.get(d.reference) || []).some(p => p.adopted)).length; const total = sets.reduce((n, d) => n + (byRef.get(d.reference) || []).reduce((a, p) => a + (p.bytes || 0), 0), 0); const head = sect('Datasets', sets.length + ' · ' + built + ' with files on this machine' + (adopted ? ', ' + adopted + ' adopted' : '') + (total ? ' · ' + bytes(total) : '')); - // Two forms that keep a new dataset as an unsaved edit (spec-d4 section 7, annotate.js): files brought in, and a dataset frozen with splits. + // Three forms that keep a new dataset as an unsaved edit (spec-d4 section 7, annotate.js; spec-d5 section 5, generate.js): files brought in, a dataset frozen with splits, and one generated through the Pumas endpoint. if (window.LabAnnotate) { head.appendChild(h('span', 'spacer')); head.appendChild(A.group('data:new', [ { id: 'import', label: 'Import files', cls: 'btn sm', who: 'edit', onClick: () => act.select(sel === 'new:import' ? null : 'new:import') }, - { id: 'freeze', label: 'Freeze a dataset', cls: 'btn sm', who: 'edit', onClick: () => act.select(sel === 'new:freeze' ? null : 'new:freeze') }], { inline: true })); } + { id: 'freeze', label: 'Freeze a dataset', cls: 'btn sm', who: 'edit', onClick: () => act.select(sel === 'new:freeze' ? null : 'new:freeze') }, + { id: 'generate', label: 'Generate', cls: 'btn sm', who: 'edit', hidden: !window.LabGenerate, onClick: () => act.select(sel === 'new:generate' ? null : 'new:generate') }], { inline: true })); } frag.appendChild(head); if (!sets.length) { frag.appendChild(h('p', 'empty', 'The project defines no dataset.')); return; } const grid = h('div', 'ds-grid'); @@ -651,6 +657,7 @@ frag.appendChild(grid); }); if (!sel) return closeDrawer(aside); + if (raw === 'new:generate' && window.LabGenerate && window.LabAnnotate) { window.LabGenerate.form(aside, act); return true; } if (raw.startsWith('new:') && window.LabAnnotate) { window.LabAnnotate.datasetForm(aside, raw.slice(4), act); return true; } if (E && E.owns(raw, data)) { E.drawer(aside, raw, act, data, 'data'); return true; } drawer(aside, sel, () => Promise.all([P.read('definition', { reference: sel }), P.read('products', { reference: sel })]), (ins, [d, p]) => { @@ -772,6 +779,6 @@ }); } - S.paint = paint; + S.paint = paint; S.drawer = drawer; Object.assign(S, { benchmarks, train, data: data_, analysis }); })(); diff --git a/tests/browser_fake_pumas.py b/tests/browser_fake_pumas.py new file mode 100644 index 00000000..824d77b1 --- /dev/null +++ b/tests/browser_fake_pumas.py @@ -0,0 +1,74 @@ +"""A fake Pumas endpoint for a browser check (tests/browser_project_workspace_endpoint.cjs), driven by lines on stdin. + +It starts tests/fake_pumas_typed.py on a loopback port of its own, serving the +listing tests/test_tuldok_project_pumas.py writes (the vision fixture's models, +writer, painter, decider and listener) and advertising itself as 0.8.0, and +prints its address as the first line on stdout. Each line read on stdin is a +JSON object and is answered with one JSON line: + + {"answer": "..."} the text a suggestion by chat or image_to_text answers + {"answers": {...}} the answers a decision gives + {"modes": [...]} modes taken one per POST (fake_pumas_typed's) + {"posts": true} answers {"posts": [{capability, model, profile, input kind}, ...]} + +A text dataset asked by text (generate) is answered "made: ", an +image a PNG of the asked size. Nothing else is contacted; it ends with stdin. +""" +import io +import json +import sys +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).resolve().parent)) +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) + +import fake_pumas_typed # noqa: E402 +from test_tuldok_project_pumas import listing # noqa: E402 + + +def main(): + server, base, state = fake_pumas_typed.start() + state['served_models'] = listing() + state['advertise'] = '0.8.0' + said = {'answer': 'A short text.', 'answers': {}} + + def respond(body): + if body['capability'] == 'decision': + return {'kind': 'decisions', 'answers': said['answers'], 'input_tokens': 7} + if body['capability'] == 'image_generation': + from PIL import Image + out = io.BytesIO() + Image.new('RGB', (body['options']['width'], body['options']['height']), (35, 95, 160)).save(out, 'PNG') + import base64 + return {'kind': 'image', 'png_base64': base64.b64encode(out.getvalue()).decode(), + 'seed': body['options'].get('seed', 7)} + if body['input'].get('kind') == 'text': + return {'kind': 'text', 'text': 'made: ' + body['input']['text'], 'finish_reason': 'stop'} + return {'kind': 'text', 'text': said['answer'], 'finish_reason': 'stop'} + + state['respond'] = respond + print(base, flush=True) + try: + for line in sys.stdin: + if not line.strip(): + continue + command = json.loads(line) + if 'answer' in command: + said['answer'] = command['answer'] + if 'answers' in command: + said['answers'] = command['answers'] + if 'modes' in command: + state['modes'] = list(command['modes']) + if command.get('posts'): + posts = [{'capability': body.get('capability'), 'model': body.get('model'), 'profile': body.get('profile'), + 'input': (body.get('input') or {}).get('kind')} for body in state['requests']] + print(json.dumps({'posts': posts}), flush=True) + else: + print(json.dumps({'ok': True}), flush=True) + finally: + server.shutdown() + server.server_close() + + +if __name__ == '__main__': + main() diff --git a/tests/browser_project_workspace_endpoint.cjs b/tests/browser_project_workspace_endpoint.cjs new file mode 100644 index 00000000..5d43c5b3 --- /dev/null +++ b/tests/browser_project_workspace_endpoint.cjs @@ -0,0 +1,498 @@ +'use strict'; +// The Pumas endpoint on the page (docs/plans/definition-first-projects/spec-d5.md sections 5 and 7, slice D5c) in a +// headless browser, the owner signed in, no GPU. Every request for a model goes to a fake endpoint that this check +// starts itself (tests/browser_fake_pumas.py, built on tests/fake_pumas_typed.py from the released 0.8.0 contract); +// no real Pumas is contacted. Tuldok is started with gateway_discovery.listening_endpoints replaced by a list holding +// the fake's port alone, so "Find on this machine" asks only the fake and this machine's listeners are never scanned. +// The settings file is TULDOK_SETTINGS when it is set (else one in a temporary directory), written empty first. +// The fixture is a project of its own in Git: datasets/notes imports three texts and a PNG, datasets/subjects two lines +// of prompts; annotations/summaries (text) and annotations/topics (class) are tasks on datasets/notes. +// 1. No endpoint set: the Train tab says so; the Generate form says why it cannot be used and goes to the endpoint. +// 2. The endpoint set from the page: an address that is not loopback refused with the server's sentence, one that does +// not answer refused; Find on this machine lists the fake; the fake's address accepted. Its seven models listed +// with what each takes and makes, an unavailable capability with its reason. +// 3. Generate: only text and images offered, the models that make each, the option fields carrying the advertised +// bounds, the seed shown only for a capability that takes one; a text dataset and an image dataset from a dataset +// of prompts kept, written by Save exactly as expected, accepted by `check`. +// 4. The text dataset planned, requested and built through the page against the fake; its records in the dataset view. +// 5. Suggest: cancelled while the model answers (the answer dropped); asked, shown as a suggestion naming the model, +// changed and kept; after Save the line on disk carries `from`. A refused suggestion (an answer that is not a term) +// leaves the form as it was. Suggest for this page keeps drafts and reports its counts. +// 6. With text typed in the Generate form, the endpoint's address and the annotation form, the window regaining focus +// and a reading on the timer add, remove and change no node, and the text is there. +// 7. Screenshots in light and dark at 1440 by 900 and 1000 by 800 (with --shots , written there too). +// It fails on any script error, and on any failed request but the refusals it asks for. +// node tests/browser_project_workspace_endpoint.cjs [--shots ] +const assert = require('node:assert/strict'), fs = require('node:fs'), os = require('node:os'), path = require('node:path'), readline = require('node:readline'); +const { spawn, execFileSync } = require('node:child_process'), { once } = require('node:events'); +const { authenticatedFixture } = require('./auth_helpers.cjs'), { waitForDebugger } = require('./browser_startup.cjs'), { cdpSession } = require('./browser_cdp_session.cjs'), { qaDirectory } = require('./qa_artifacts.cjs'); + +const root = path.resolve(__dirname, '..'); +const argv = process.argv.slice(2), option = name => { const i = argv.indexOf(name); return i >= 0 ? argv[i + 1] : null; }; +assert.ok(process.env.TULDOK_DATABASE_URL, 'TULDOK_DATABASE_URL must name a disposable PostgreSQL cluster'); +const venv = path.join(root, '.venv', 'bin'); +if (fs.existsSync(path.join(venv, 'python'))) process.env.PATH = venv + path.delimiter + process.env.PATH; // auth_helpers runs python3 +const python = fs.existsSync(path.join(venv, 'python')) ? path.join(venv, 'python') : 'python3'; +const IDLE_MS = 15000; // the page's reading while nothing builds (app.js) +const WATCHED = ['summary', 'status', 'build_requests', 'environments', 'runs']; +const RIGHTS = 'Made by a model for this check; anything may be done with it.'; +// Tuldok, with the scanner of find_endpoints answering the fake's port alone (argv[1]). +const LAUNCH = `import runpy, sys +import gateway_discovery +port = int(sys.argv[1]) +gateway_discovery.listening_endpoints = lambda: [('127.0.0.1', port)] +sys.argv = ['app.py'] + sys.argv[2:] +runpy.run_path('app.py', run_name='__main__')`; + +const temporary = fs.mkdtempSync(path.join(os.tmpdir(), 'tuldok-endpoint-browser-')); +const report = qaDirectory(root, 'project-workspace-endpoint'); +const shots = option('--shots') ? path.resolve(option('--shots')) : null; if (shots) fs.mkdirSync(shots, { recursive: true }); +const children = [], checks = [], errors = [], failures = []; +let server, serverErrors = '', origin, auth, socket, session, send, evaluate, owned = null, fake = null, fakeLines = null; +const pause = ms => new Promise(resolve => setTimeout(resolve, ms)); +async function until(fn, label, tries = 300) { for (let i = 0; i < tries; i++) { const value = await fn(); if (value) return value; await pause(100); } throw Error('Timed out: ' + label); } +function check(text) { checks.push(text); console.log('PASS ' + text); } +function launch(command, args, options) { const child = spawn(command, args, options); children.push(child); return child; } +async function stop(child) { if (!child || child.exitCode !== null || child.signalCode !== null) return; const exited = once(child, 'exit'); child.kill('SIGTERM'); await Promise.race([exited, pause(10000)]); if (child.exitCode === null && child.signalCode === null) { child.kill('SIGKILL'); await exited; } } +function findBrowser() { + const candidates = [process.env.BROWSER, '/usr/bin/chromium', '/usr/bin/chromium-browser', '/usr/bin/google-chrome']; + const cache = path.join(os.homedir(), '.cache', 'ms-playwright'); + if (fs.existsSync(cache)) for (const name of fs.readdirSync(cache).filter(n => n.startsWith('chromium_headless_shell-')).sort().reverse()) candidates.push(path.join(cache, name, 'chrome-headless-shell-linux64', 'chrome-headless-shell')); + const found = candidates.find(candidate => candidate && fs.existsSync(candidate)); + assert.ok(found, 'No headless browser: set BROWSER'); + return found; +} +/** Drops the project's schema and the catalog's from the disposable database, so each run imports afresh. */ +function dropOwned(folder, catalog) { + const id = JSON.parse(fs.readFileSync(path.join(folder, 'tuldok.json'), 'utf8')).id; + execFileSync(python, ['-c', `import json, os, pathlib, sys, psycopg +from psycopg import sql +from tuldok_project import store +store.drop_project(sys.argv[1], os.environ['TULDOK_DATABASE_URL']) +root = pathlib.Path(sys.argv[2]) +if root.exists(): + with psycopg.connect(os.environ['TULDOK_DATABASE_URL'], autocommit=True) as c: + for p in root.rglob('.tuldok.json'): + v = json.loads(p.read_text()) + name = 'projection_' + v['projection_id'] if v.get('version') == 2 else 'catalog_' + v['dataset_id'] + c.execute(sql.SQL('DROP SCHEMA IF EXISTS {} CASCADE').format(sql.Identifier(name))) +`, id, catalog], { cwd: root, stdio: ['ignore', 'pipe', 'pipe'] }); +} +async function contract(name) { + const capabilities = await (await auth.fetch(origin + '/api/agent/capabilities')).json(); + const operation = capabilities.operations.find(item => item.id === 'project.' + name), c = operation.contracts[operation.contracts.length - 1]; + return 'project.' + name + '/' + c.version + '/' + c.sha256; +} +/** An operation as the owner. */ +async function api(name, body = {}) { + const headers = { 'Content-Type': 'application/json', 'Tuldok-Operation-Contract': await contract(name) }; + const response = await auth.fetch(origin + '/api/project/' + name, { method: 'POST', headers, body: JSON.stringify(body) }); + const value = await response.json(); assert.equal(response.status, 200, name + ': ' + JSON.stringify(value)); return value; +} +/** A command to the fake endpoint (tests/browser_fake_pumas.py), and its answer. */ +async function tell(command) { fake.stdin.write(JSON.stringify(command) + '\n'); const [line] = await once(fakeLines, 'line'); return JSON.parse(line); } + +// ---- The page's readings, from the browser's network (as browser_project_workspace_still.cjs) ---------------- +const calls = new Map(), finished = []; +function network(event) { + const p = event.params; + if (event.method === 'Network.requestWillBeSent' && /\/api\/project\/[a-z_]+$/.test(p.request.url)) calls.set(p.requestId, { name: p.request.url.split('/').pop(), sent: Date.now() }); + if ((event.method === 'Network.loadingFinished' || event.method === 'Network.loadingFailed') && calls.has(p.requestId)) { finished.push(Object.assign(calls.get(p.requestId), { done: Date.now() })); calls.delete(p.requestId); } +} +async function reading(since, names, label, tries = 300) { + await until(() => names.every(name => finished.some(f => f.name === name && f.sent >= since)), 'a reading: ' + label, tries); + await until(() => !calls.size && Date.now() - Math.max(0, ...finished.map(f => f.done)) > 700, 'the reading done: ' + label, 300); + await settled(label); +} +/** Waits until nothing reads: no call of the project in flight, no "Reading…", nothing busy. */ +async function settled(label) { + await until(async () => !calls.size && await evaluate(`(() => { const reading = e => [...e.querySelectorAll('.note')].some(n => n.textContent === 'Reading…'); return !reading(document.getElementById('main')) && !reading(document.getElementById('aside')) && !document.getElementById('main').hasAttribute('aria-busy') && !document.querySelector('.act-group [aria-busy]') && !document.querySelector('#main [data-key="ann:suggest"][aria-busy]'); })()`), 'settled: ' + label); + await pause(200); + await until(async () => !calls.size, 'settled again: ' + label); +} +async function hash(value) { await evaluate(`location.hash = ${JSON.stringify('#' + value)}`); await settled('#' + value); await pause(200); await settled('#' + value); } +const byKey = key => `[data-key=${JSON.stringify(key)}]`; +async function centre(selector) { + return until(() => evaluate(`(() => { const e = [...document.querySelectorAll(${JSON.stringify(selector)})].find(e => e.offsetParent !== null); if (!e) return null; e.scrollIntoView({ block: 'nearest', inline: 'nearest' }); const r = e.getBoundingClientRect(), x = r.left + r.width / 2, y = r.top + r.height / 2, hit = document.elementFromPoint(x, y); return hit && (hit === e || e.contains(hit)) ? { x, y } : null; })()`), 'shown: ' + selector, 100); +} +async function mouse(type, x, y, buttons = 0) { await send('Input.dispatchMouseEvent', { type, x, y, button: type === 'mouseMoved' ? (buttons ? 'left' : 'none') : 'left', buttons, clickCount: type === 'mouseMoved' ? 0 : 1 }); } +async function press(selector) { const { x, y } = await centre(selector); await mouse('mouseMoved', x, y); await mouse('mousePressed', x, y, 1); await mouse('mouseReleased', x, y); } +const KEYS = { Enter: 13, Escape: 27, Tab: 9 }; +async function key(name) { + const code = KEYS[name] || name.toUpperCase().charCodeAt(0), text = name.length === 1 ? name : name === 'Enter' ? '\r' : undefined; + await send('Input.dispatchKeyEvent', { type: text ? 'keyDown' : 'rawKeyDown', key: name, code: name.length === 1 ? 'Key' + name.toUpperCase() : name, windowsVirtualKeyCode: code, text }); + await send('Input.dispatchKeyEvent', { type: 'keyUp', key: name, windowsVirtualKeyCode: code }); +} +async function type(selector, text) { await press(selector); await evaluate(`(() => { const e = document.activeElement; if (e.select) e.select(); return true; })()`); await send('Input.insertText', { text }); } +/** Sets a select's value as a person would choose it, focused and with its change event (no popup is opened: a form that draws itself again on a change would leave an Escape to the page). */ +async function choose(selector, value) { await centre(selector); await evaluate(`(() => { const s = document.querySelector(${JSON.stringify(selector)}); s.focus(); s.value = ${JSON.stringify(value)}; s.dispatchEvent(new Event('change', { bubbles: true })); return true; })()`); } +async function shot(name) { + await evaluate('new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve)))'); + const png = Buffer.from((await send('Page.captureScreenshot', { format: 'png', captureBeyondViewport: false })).data, 'base64'); + fs.writeFileSync(path.join(report, name + '.png'), png); if (shots) fs.writeFileSync(path.join(shots, name + '.png'), png); +} +const text = selector => evaluate(`(() => { const e = document.querySelector(${JSON.stringify(selector)}); return e ? e.innerText : null; })()`); +const value = selector => evaluate(`(() => { const e = document.querySelector(${JSON.stringify(selector)}); return e ? e.value : null; })()`); +const options = selector => evaluate(`[...document.querySelectorAll(${JSON.stringify(selector + ' option')})].map(o => o.value)`); +const tiles = () => evaluate(`[...document.querySelectorAll('#main .ann-rec')].map(b => ({ id: b.dataset.id, state: b.dataset.state, pressed: b.getAttribute('aria-pressed') === 'true' }))`); +const lines = (folder, name) => { const file = path.join(folder, 'annotations', name + '.jsonl'); return fs.existsSync(file) ? fs.readFileSync(file, 'utf8').split('\n').filter(Boolean).map(l => JSON.parse(l)) : []; }; + +// The watcher of browser_project_workspace_still.cjs. +const WATCHER = `window.__still = (() => { + const ids = ['tabs', 'strip', 'main', 'aside', 'needs-panel'], el = id => document.getElementById(id); + let counts = null, flash = 0, timer = null, observers = []; + const name = n => !n ? '?' : n.nodeType === 1 ? n.tagName.toLowerCase() + (typeof n.className === 'string' && n.className ? '.' + n.className.trim().split(/\\s+/).join('.') : '') : '#text ' + JSON.stringify(String(n.data || '').slice(0, 30)); + const watch = (key, node) => { const o = new MutationObserver(list => { + if (!counts) return; + const c = counts[key]; + for (const r of list) { + if (r.type === 'childList') { c.added += r.addedNodes.length; c.removed += r.removedNodes.length; for (const n of [...r.addedNodes, ...r.removedNodes]) if (c.what.length < 6) c.what.push(name(n) + ' in ' + name(r.target)); } + else if (r.type === 'characterData') { const msg = el('strip').querySelector('.msg'); if (msg && r.target === msg.lastChild) c.readAt++; else { c.text++; if (c.what.length < 6) c.what.push('text of ' + name(r.target.parentNode)); } } + else { c.attrs++; if (c.what.length < 6) c.what.push('@' + r.attributeName + ' on ' + name(r.target)); } + } + }); o.observe(node, { childList: true, subtree: true, characterData: true, attributes: true }); observers.push(o); }; + return { + start() { + for (const o of observers) o.disconnect(); observers = []; + counts = {}; for (const id of ids) counts[id] = { added: 0, removed: 0, attrs: 0, text: 0, readAt: 0, what: [] }; + for (const id of ids) { watch(id, el(id)); for (const e of el(id).querySelectorAll('*')) e.__seen = 1; } + flash = 0; clearInterval(timer); timer = setInterval(() => { if ((el('main').textContent + el('aside').textContent).includes('Reading…')) flash++; }, 50); + }, + stop() { clearInterval(timer); const fresh = {}; for (const id of ids) fresh[id] = [...el(id).querySelectorAll('*')].filter(e => !e.__seen).length; const r = { counts, flash, fresh }; counts = null; for (const o of observers) o.disconnect(); observers = []; return r; } + }; +})(); true`; + +let folder; +(async () => { + // ---- The fake endpoint, the fixture and Tuldok ------------------------------------------------------------------- + fake = launch(python, [path.join(root, 'tests', 'browser_fake_pumas.py')], { cwd: root, stdio: ['pipe', 'pipe', 'pipe'] }); + let fakeErrors = ''; fake.stderr.on('data', chunk => { fakeErrors += chunk; }); + fakeLines = readline.createInterface({ input: fake.stdout }); + const base = await Promise.race([once(fakeLines, 'line').then(([line]) => line.trim()), once(fake, 'exit').then(() => { throw Error('The fake endpoint exited: ' + fakeErrors); })]); + assert.match(base, /^http:\/\/127\.0\.0\.1:\d+$/); + const fakePort = Number(base.split(':').pop()); + + const repo = path.join(temporary, 'fixture'), code = path.join(repo, 'code'); folder = path.join(repo, 'project'); + for (const d of ['datasets', 'annotations']) fs.mkdirSync(path.join(folder, d), { recursive: true }); + fs.mkdirSync(path.join(code, 'notes'), { recursive: true }); fs.mkdirSync(path.join(code, 'subjects'), { recursive: true }); + fs.writeFileSync(path.join(folder, 'tuldok.json'), JSON.stringify({ format: 'tuldok_project_v1', id: require('node:crypto').randomUUID().replace(/-/g, ''), name: 'Endpoint check', code_root: '../code' }, null, 2) + '\n'); + fs.writeFileSync(path.join(code, 'notes', 'a.txt'), 'A long text about a dog that runs after a red ball in the park.\n'); + fs.writeFileSync(path.join(code, 'notes', 'b.txt'), 'Rain is expected over the hills by the evening.\n'); + fs.writeFileSync(path.join(code, 'notes', 'c.txt'), 'The train to the coast leaves at nine.\n'); + execFileSync(python, ['-c', 'import sys; from PIL import Image; Image.new("RGB", (48, 32), (200, 120, 40)).save(sys.argv[1])', path.join(code, 'notes', 'photo.png')]); + fs.writeFileSync(path.join(code, 'subjects', 'subjects.txt'), 'a red ball\na blue car\n'); + const doc = o => JSON.stringify(Object.assign({ format: 'tuldok_definition_v1' }, o), null, 2) + '\n'; + fs.writeFileSync(path.join(folder, 'datasets', 'notes.json'), doc({ kind: 'dataset', title: 'Notes and a photo', run: { step: 'import', settings: { source: 'notes', rights: 'Written for this check; free to use.' } } })); + fs.writeFileSync(path.join(folder, 'datasets', 'subjects.json'), doc({ kind: 'dataset', title: 'Subjects to draw', run: { step: 'import', settings: { source: 'subjects', rights: 'Written for this check; free to use.', lines: true } } })); + fs.writeFileSync(path.join(folder, 'annotations', 'summaries.json'), doc({ kind: 'annotation', title: 'Summaries', dataset: 'datasets/notes', task: 'text' })); + fs.writeFileSync(path.join(folder, 'annotations', 'topics.json'), doc({ kind: 'annotation', title: 'Topics', dataset: 'datasets/notes', task: 'class', vocabulary: ['animals', 'weather', 'travel'] })); + const git = ['-c', 'user.name=Tuldok Test', '-c', 'user.email=test@example.invalid', '-c', 'commit.gpgsign=false', '-c', 'init.defaultBranch=main', '-C', repo]; + const commit = message => { execFileSync('git', [...git, 'add', '-A']); execFileSync('git', [...git, 'commit', '-q', '-m', message]); }; + execFileSync('git', [...git, 'init', '-q']); commit('The fixture.'); + const home = process.env.TULDOK_PROJECT_HOME || path.join(temporary, 'home'), catalog = path.join(temporary, 'catalog'); fs.mkdirSync(home, { recursive: true }); + const settingsFile = process.env.TULDOK_SETTINGS || path.join(temporary, 'settings.json'); + fs.mkdirSync(path.dirname(settingsFile), { recursive: true }); fs.writeFileSync(settingsFile, JSON.stringify({ format: 'tuldok_settings_v1' }) + '\n', { mode: 0o600 }); + const env = { ...process.env, TULDOK_PROJECT_HOME: home, TULDOK_SETTINGS: settingsFile }; + owned = [folder, catalog]; dropOwned(folder, catalog); + const cli = (...args) => execFileSync(python, ['-m', 'tuldok_project', ...args], { cwd: root, env, stdio: ['ignore', 'pipe', 'pipe'] }).toString(); + assert.match(cli('check', folder), /^0 errors/m); + cli('build', folder, 'datasets/notes', '--yes'); cli('build', folder, 'datasets/subjects', '--yes'); + let output = ''; + server = launch(python, ['-c', LAUNCH, String(fakePort), '--port', '0', '--data', catalog, '--project-folder', folder], { cwd: root, env: { ...env, PYTHONUNBUFFERED: '1' }, stdio: ['ignore', 'pipe', 'pipe'] }); + server.stdout.on('data', chunk => { output += chunk; }); server.stderr.on('data', chunk => { serverErrors += chunk; }); + const port = await until(() => { if (server.exitCode !== null) throw Error('Tuldok exited: ' + serverErrors); return output.match(/127\.0\.0\.1:(\d+)/)?.[1]; }, 'Tuldok start-up', 3000); + origin = 'http://127.0.0.1:' + port; + auth = authenticatedFixture(); await auth.register(origin, catalog, root); + + const browser = launch(findBrowser(), ['--headless', '--no-sandbox', '--disable-gpu', '--no-first-run', '--hide-scrollbars', '--remote-debugging-port=0', '--window-size=1440,900', '--user-data-dir=' + path.join(temporary, 'browser'), 'about:blank'], { stdio: 'ignore', env: { ...process.env, XDG_CONFIG_HOME: temporary, XDG_CACHE_HOME: temporary } }); + const debugPort = await waitForDebugger(browser, path.join(temporary, 'browser', 'DevToolsActivePort')); + const target = (await (await fetch('http://127.0.0.1:' + debugPort + '/json')).json()).find(item => item.type === 'page'); + socket = new WebSocket(target.webSocketDebuggerUrl); await once(socket, 'open'); + const ASKED = /\/api\/project\/(set_endpoint|suggest_annotation)$/; // the refusals this check asks for + session = cdpSession(socket, { timeoutMs: 60000, onEvent: event => { + network(event); + if (event.method === 'Runtime.exceptionThrown') errors.push(event.params.exceptionDetails.exception?.description || event.params.exceptionDetails.text); + if (event.method === 'Runtime.consoleAPICalled' && event.params.type === 'error') errors.push(event.params.args.map(a => a.value ?? a.description).join(' ')); + if (event.method === 'Log.entryAdded' && event.params.entry.level === 'error' && !ASKED.test(event.params.entry.url || '')) errors.push(event.params.entry.text + ' ' + (event.params.entry.url || '')); + if (event.method === 'Network.loadingFailed' && !event.params.canceled) failures.push({ id: event.params.requestId, error: event.params.errorText }); + if (event.method === 'Network.responseReceived' && event.params.response.status >= 400) failures.push({ url: event.params.response.url, status: event.params.response.status }); + } }); + send = session.send; + evaluate = async expression => { const result = await send('Runtime.evaluate', { expression, awaitPromise: true, returnByValue: true }); if (result.exceptionDetails) throw Error(JSON.stringify(result.exceptionDetails)); return result.result.value; }; + await send('Page.enable'); await send('Runtime.enable'); await send('Network.enable'); await send('Log.enable'); + const size = async (width, height) => send('Emulation.setDeviceMetricsOverride', { width, height, deviceScaleFactor: 1, mobile: false }); + const theme = async name => { await send('Emulation.setEmulatedMedia', { features: [{ name: 'prefers-color-scheme', value: name }, { name: 'prefers-reduced-motion', value: 'reduce' }] }); }; + await size(1440, 900); await theme('light'); + await auth.browser(send, origin); + const load = async (name, place) => { + await theme(name); + await send('Page.navigate', { url: 'about:blank' }); await pause(100); + await send('Page.navigate', { url: origin + '/?theme=' + name + '#' + place }); + await until(() => evaluate(`document.readyState === 'complete' && !!document.getElementById('needs-btn') && !document.getElementById('needs-btn').disabled`), 'the project read', 1200); + await settled('opened ' + place); + }; + const kept = async label => { await until(async () => !(await evaluate(`!!document.querySelector('.act-group [aria-busy]')`)), 'kept: ' + label); await settled(label); }; + const drawerText = () => text('#aside'); + const settingsNow = () => JSON.parse(fs.readFileSync(settingsFile, 'utf8')); + + // ---- 1. No endpoint set ---------------------------------------------------------------------------------------------- + await load('light', 'train'); + const row = await text('#main [data-key="open-endpoint"]'); + assert.match(row, /not set/); assert.match(row, /No endpoint set/); assert.match(row, /No Pumas endpoint is set on this machine/); + assert.equal(await evaluate(`document.querySelectorAll('#main .ep-model').length`), 0); + await hash('data'); + await press(byKey('data:new:generate')); + await until(() => evaluate(`!!document.querySelector('#aside .gen-none')`), 'the Generate form without an endpoint'); + const none = await drawerText(); + assert.match(none, /No Pumas endpoint is set on this machine, so there is nothing to generate with/); + assert.equal(await evaluate(`!!document.querySelector('#aside [data-key="newgenerate:field:title"]')`), false, 'No field is offered'); + await press(byKey('gen:endpoint')); + await until(() => evaluate(`location.hash === '#train/endpoint' && !!document.querySelector('#aside [data-key="endpoint:set:field:address"]')`), 'the endpoint\'s drawer on Train'); + await settled('endpoint drawer'); + check('1. No endpoint set: the Train tab says "' + row.split('\n').slice(0, 3).join(' · ') + '"; the Generate form says "' + none.match(/No Pumas endpoint[^\n]*/)[0] + '" and its button opens the endpoint on the Train tab'); + + // ---- 2. The endpoint set from the page ---------------------------------------------------------------------------- + const refusal = async () => until(() => text('#aside [data-group="endpoint:set"] .refusal'), 'the refusal beside Set'); + await type(byKey('endpoint:set:field:address'), 'http://192.168.1.5:8765'); + await press(byKey('endpoint:set:set')); await kept('a remote address'); + const remote = await refusal(); + assert.match(remote, /'http:\/\/192\.168\.1\.5:8765' is not an address Tuldok can reach Pumas at: Pumas 0\.8\.0 serves on a numeric loopback address/); + assert.equal(await value(byKey('endpoint:set:field:address')), 'http://192.168.1.5:8765', 'What was typed stays'); + await shot('light-1440-train-refusal'); + const closed = await new Promise(resolve => { const s = require('node:net').createServer(); s.listen(0, '127.0.0.1', () => { const p = s.address().port; s.close(() => resolve(p)); }); }); + await type(byKey('endpoint:set:field:address'), 'http://127.0.0.1:' + closed); + await press(byKey('endpoint:set:set')); await kept('an address that does not answer'); + const silent = await refusal(); + assert.match(silent, new RegExp('The Pumas endpoint at http://127\\.0\\.0\\.1:' + closed + ' did not answer, so it was not set')); + assert.equal(settingsNow().pumas_endpoint, undefined, 'Nothing was set'); + await press(byKey('endpoint:find:find')); await kept('found'); + const found = await until(() => text('#aside .ep-found'), 'what Find found'); + assert.match(found, new RegExp(base.replace(/\./g, '\\.') + '\\nPumas 0\\.8\\.0 · pumas-rpc'), 'Find lists the fake: ' + found); + await type(byKey('endpoint:set:field:address'), base); + await press(byKey('endpoint:set:set')); await kept('the fake set'); + await until(async () => /answers/.test(await text('#main [data-key="open-endpoint"]') || ''), 'the endpoint answers'); + assert.equal(settingsNow().pumas_endpoint, base, 'The settings file holds the address'); + assert.equal(await evaluate(`!!document.querySelector('#aside [data-group="endpoint:set"] .refusal')`), false, 'The refusal is gone'); + const models = await evaluate(`[...document.querySelectorAll('#main .ep-model')].map(li => ({ id: li.dataset.model + ' · ' + li.dataset.profile, text: li.innerText }))`); + assert.deepEqual(models.map(m => m.id), ['controlled-vision · vision-cpu', 'controlled-vision · vision-gpu', 'controlled-image · controlled-image-cpu', 'writer · writer-cpu', 'painter · painter-gpu', 'decider · decider-cpu', 'listener · listener-cpu']); + const of = id => models.find(m => m.id === id).text; + assert.match(of('writer · writer-cpu'), /Takes text · makes text/); assert.match(of('writer · writer-cpu'), /A dataset of: texts by chat_generation \(max_tokens 1 to 4,096, temperature 0 to 2, top_p 0 to 1\)/); + assert.match(of('writer · writer-cpu'), /Unavailable: image_generation \(unsupported_adapter\)/); + assert.match(of('painter · painter-gpu'), /A dataset of: images by image_generation \(width 1 to 4,294,967,295, height 1 to 4,294,967,295\), with a seed/); + assert.match(of('controlled-vision · vision-gpu'), /No dataset can be made with it/); assert.match(of('controlled-vision · vision-gpu'), /chat_generation \(runtime_unavailable\)/); + assert.match(of('decider · decider-cpu'), /Takes text, image and audio · makes json/); + assert.match(of('listener · listener-cpu'), /Available: audio_transcription \(pcm_s16le, pcm_f32le → text\)/); + assert.match(await text('#main [data-key="open-endpoint"]'), /Pumas 0\.8\.0 · 7 models served/); + check('2. The endpoint set from the page: "' + remote.split('\n')[0].slice(0, 90) + '…" and "' + silent.split('\n')[0].slice(0, 70) + '…" refused beside Set, the typed address kept; Find on this machine listed ' + base + ' (Pumas 0.8.0); the fake\'s address accepted and written to the settings file; its 7 models listed with what each takes and makes, unavailable capabilities with their reasons'); + + // ---- 3. Generate -------------------------------------------------------------------------------------------------- + await hash('data'); + await press(byKey('data:new:generate')); + await until(() => evaluate(`!!document.querySelector('#aside [data-key="newgenerate:field:title"]')`), 'the Generate form'); + await settled('generate form'); + assert.deepEqual(await options('#aside [data-key="newgenerate:field:make"]'), ['text', 'image'], 'Only what some served model makes'); + assert.deepEqual(await options('#aside [data-key="newgenerate:field:model"]'), ['controlled-vision\u0000vision-cpu', 'writer\u0000writer-cpu'], 'The models that make texts'); + assert.match(await drawerText(), /The profile vision-cpu is written with the model: the endpoint requires it/); + await choose(byKey('newgenerate:field:model'), 'writer\u0000writer-cpu'); + const field = name => evaluate(`(() => { const i = document.querySelector('#aside [data-key="newgenerate:field:${name}"]'); return i ? { min: i.min, max: i.max } : null; })()`); + assert.deepEqual(await field('opt:max_tokens'), { min: '1', max: '4096' }); assert.deepEqual(await field('opt:temperature'), { min: '0', max: '2' }); assert.deepEqual(await field('opt:top_p'), { min: '0', max: '1' }); + assert.equal(await field('seed'), null, 'No seed for a capability that takes none'); + assert.doesNotMatch(await drawerText(), /The profile/); + await type(byKey('newgenerate:field:title'), 'Poem lines'); + await type(byKey('newgenerate:field:prompt'), 'Write line {n} of a short poem.'); + await type(byKey('newgenerate:field:count'), '3'); + await type(byKey('newgenerate:field:opt:max_tokens'), '64'); await type(byKey('newgenerate:field:opt:temperature'), '0.7'); + await type(byKey('newgenerate:field:rights'), RIGHTS); + await shot('light-1440-generate-text'); + await press(byKey('newgenerate:keep')); await kept('poem lines kept'); + await until(() => evaluate(`location.hash === '#data/' + encodeURIComponent('datasets/poem-lines')`), 'the new dataset\'s drawer'); await settled('poem drawer'); + await press(byKey('data:new:generate')); + await until(() => evaluate(`!!document.querySelector('#aside [data-key="newgenerate:field:title"]')`), 'the Generate form again'); await settled('generate again'); + await choose(byKey('newgenerate:field:make'), 'image'); await settled('image'); + assert.deepEqual(await options('#aside [data-key="newgenerate:field:model"]'), ['controlled-image\u0000controlled-image-cpu', 'painter\u0000painter-gpu'], 'The models that make images'); + await choose(byKey('newgenerate:field:model'), 'painter\u0000painter-gpu'); + assert.deepEqual(await field('seed'), { min: '0', max: '4294967295' }, 'The seed of a capability that takes one'); + assert.deepEqual(await field('opt:width'), { min: '1', max: '4294967295' }); assert.deepEqual(await field('opt:height'), { min: '1', max: '4294967295' }); + assert.equal(await field('opt:max_tokens'), null); + await type(byKey('newgenerate:field:title'), 'Pictures of subjects'); + await press(byKey('newgenerate:field:from-prompts')); await settled('from prompts'); + assert.match(await drawerText(), /\{text\} by the text of the prompting record/); + await choose(byKey('newgenerate:field:prompts'), 'datasets/subjects'); + await type(byKey('newgenerate:field:per'), '2'); + await type(byKey('newgenerate:field:prompt'), 'A picture of {text}, number {n}.'); + await type(byKey('newgenerate:field:seed'), '100'); await type(byKey('newgenerate:field:opt:width'), '64'); + await type(byKey('newgenerate:field:rights'), RIGHTS); + await press(byKey('newgenerate:keep')); await kept('height missing'); + assert.match(await text('#aside [data-group="newgenerate"] .refusal') || '', /height is required/, 'An image needs its height'); + await type(byKey('newgenerate:field:opt:height'), '32'); + assert.equal(await value(byKey('newgenerate:field:title')), 'Pictures of subjects', 'Nothing typed was lost'); + await shot('light-1440-generate-image'); + await press(byKey('newgenerate:keep')); await kept('pictures kept'); + await until(() => evaluate(`location.hash === '#data/' + encodeURIComponent('datasets/pictures-of-subjects')`), 'the image dataset\'s drawer'); await settled('pictures drawer'); + await press(byKey('save:save')); await kept('saved the datasets'); + const want = { + 'poem-lines': { format: 'tuldok_definition_v1', kind: 'dataset', title: 'Poem lines', run: { step: 'generate', settings: { make: 'text', model: 'writer', prompt: 'Write line {n} of a short poem.', count: 3, options: { max_tokens: 64, temperature: 0.7 }, rights: RIGHTS } } }, + 'pictures-of-subjects': { format: 'tuldok_definition_v1', kind: 'dataset', title: 'Pictures of subjects', run: { step: 'generate', inputs: { prompts: 'datasets/subjects' }, settings: { make: 'image', model: 'painter', prompt: 'A picture of {text}, number {n}.', per: 2, seed: 100, options: { width: 64, height: 32 }, rights: RIGHTS } } } + }; + for (const [name, d] of Object.entries(want)) assert.equal(fs.readFileSync(path.join(folder, 'datasets', name + '.json'), 'utf8'), JSON.stringify(d, null, 2) + '\n', 'The definition written for ' + name); + const checked = cli('check', folder); + assert.match(checked, /^0 errors/m, checked); + check('3. Generate offered text and image only, the models making each, the options with the advertised bounds as minimum and maximum (max_tokens 1–4096 …, width 1–4294967295), the seed only for image_generation, the profile line for controlled-vision; a missing height refused with nothing lost; datasets/poem-lines and datasets/pictures-of-subjects written by Save exactly as expected; `check` reports ' + checked.trim().split('\n').pop().replace(/ in .*/, '')); + + // ---- 4. Built through the page, its records in the dataset view ---------------------------------------------------- + commit('The generated datasets.'); + await hash('data/' + encodeURIComponent('datasets/poem-lines')); + await press(byKey('dataedit:datasets/poem-lines:plan')); + await until(() => evaluate(`location.hash === '#train/' + encodeURIComponent('plan:datasets/poem-lines') && !!document.querySelector('#aside .plan-view')`), 'the plan of poem-lines'); await settled('plan'); + const plan = await drawerText(); + assert.match(plan, /1 step to build/); assert.match(plan, /can be built/); + await press(byKey('request:plan:datasets/poem-lines:request')); await kept('requested'); + const product = await until(async () => { const p = (await api('products', { reference: 'datasets/poem-lines' })).products; return p.length ? p[0] : null; }, 'the generated product', 600); + const posts = (await tell({ posts: true })).posts.filter(p => p.input === 'text'); + assert.deepEqual(posts.map(p => [p.model, p.capability]), [['writer', 'chat_generation'], ['writer', 'chat_generation'], ['writer', 'chat_generation']], 'Three requests to the fake'); + await hash('data/' + encodeURIComponent('inside:datasets/poem-lines')); + await until(() => evaluate(`document.querySelectorAll('#main .rec').length === 3`), 'the three records in the dataset view'); + const ids = await evaluate(`[...document.querySelectorAll('#main .rec')].map(t => t.dataset.id)`); + assert.deepEqual(ids, ['g000001', 'g000002', 'g000003']); + await press('#main .rec[data-id="g000002"]'); + await until(async () => (await text('#main .viewer .iv-text')) === 'made: Write line 2 of a short poem.', 'the record\'s text in the viewer'); + check('4. datasets/poem-lines planned from its drawer ("1 step to build"), requested and built through the page against the fake (3 requests to writer by chat_generation; run ' + product.run_id.slice(0, 8) + '); the dataset view lists g000001 to g000003 and shows "made: Write line 2 of a short poem."'); + + // ---- 5. Suggestions ------------------------------------------------------------------------------------------------- + await hash('annotate'); + const pickTask = async ref => { if ((await value(byKey('ann:task'))) !== ref) { await choose(byKey('ann:task'), ref); await settled('task ' + ref); } }; + const open = async id => { await press(byKey('ann-rec-' + id)); await until(() => evaluate(`(() => { const h = document.querySelector('#main .ann-form h2'); return !!h && h.textContent === ${JSON.stringify(id)}; })()`), 'the form of ' + id); await settled(id); }; + const mark = () => text('#main .ann-form .ann-sugmark'); + await pickTask('annotations/summaries'); await open('a.txt'); + assert.deepEqual(await options('#main [data-key="ann:suggest-model"]'), ['controlled-vision\u0000vision-cpu', 'writer\u0000writer-cpu'], 'The models that suggest a summary of a text'); + await choose(byKey('ann:suggest-model'), 'writer\u0000writer-cpu'); + // Cancelled while the model answers: the answer is dropped. + await tell({ answer: 'An answer that comes too late.', modes: ['hold'] }); + await press(byKey('ann:suggest')); + await until(async () => (await text('#main [data-key="ann:suggest"]')) === 'Asking writer…', 'the button says the model is asked'); + assert.equal(await evaluate(`document.activeElement.dataset.key`), 'ann:suggest-cancel', 'The focus is on Cancel'); + await press(byKey('ann:suggest-cancel')); + await until(async () => (await text('#main [data-key="ann:suggest"]')) === 'Suggest', 'Suggest again'); + await pause(3500); // the fake holds the answer up to 3 s + assert.equal(await value(byKey('ann:text')), '', 'The cancelled answer was dropped'); assert.equal(await mark(), null); + // Asked, shown as a suggestion naming the model, changed and kept. + await tell({ answer: 'A dog chases a red ball.' }); + await press(byKey('ann:suggest')); + await until(async () => /Suggested by writer · writer-cpu \(chat_generation\)/.test(await mark() || ''), 'the suggestion shown'); + assert.equal(await value(byKey('ann:text')), 'A dog chases a red ball.'); + assert.match(await text('#main .ann-form .umark'), /not kept yet/); + await settled('suggested'); + await shot('light-1440-suggestion'); + await press(byKey('ann:text')); await evaluate(`(() => { const e = document.activeElement; e.setSelectionRange(e.value.length, e.value.length); return true; })()`); await send('Input.insertText', { text: ' In the park.' }); + assert.match(await mark(), /Changed from the suggestion of writer · writer-cpu/); + await press(byKey('ann:decide-accepted')); await press(byKey('annotate:form:keep')); await kept('kept the summary'); + // A refused suggestion leaves the form as it was. + await pickTask('annotations/topics'); await open('b.txt'); + assert.deepEqual(await options('#main [data-key="ann:suggest-model"]'), ['controlled-vision\u0000vision-cpu', 'writer\u0000writer-cpu', 'decider\u0000decider-cpu'], 'The models that suggest a class of a text (in the endpoint\'s order)'); + await choose(byKey('ann:suggest-model'), 'writer\u0000writer-cpu'); + await press(byKey('ann:term-1')); await type(byKey('ann:note'), 'clouds, maybe'); + await tell({ answer: 'a fluffy animal, probably' }); + await press(byKey('ann:suggest')); + const refused = await until(() => text('#main .ann-form .ann-sugrefusal'), 'the refusal beside the form'); + assert.match(refused, /No suggestion: the form is as it was/); assert.match(refused, /a fluffy animal, probably/); + assert.deepEqual([await evaluate(`document.querySelector('[data-key="ann:term-1"]').checked`), await value(byKey('ann:note')), await mark()], [true, 'clouds, maybe', null], 'The form is as it was'); + await settled('refused'); + await shot('light-1440-suggestion-refused'); + // Suggest for this page: a.txt, c.txt and photo.png have no annotation (b.txt holds a typed draft); the second is refused. + await tell({ answer: 'travel', modes: ['success', 'unknown'] }); + await press(byKey('ann:suggest-page')); + const said = await until(async () => { const t = await text('#main .ann-form .ann-batch .ann-batch-line'); return t && /^Done\./.test(t) ? t : null; }, 'the page suggested', 600); + assert.match(said, /^Done\. Kept 2 drafts, 1 refused, of 3 records with no annotation\. First refused: c\.txt: /, said); + await settled('page suggested'); + const after = await tiles(); + assert.deepEqual(after.map(x => [x.id, x.state]), [['a.txt', 'draft'], ['b.txt', 'none'], ['c.txt', 'none'], ['photo.png', 'draft']], 'The drafts kept: ' + JSON.stringify(after)); + assert.deepEqual([await evaluate(`document.querySelector('[data-key="ann:term-1"]').checked`), await value(byKey('ann:note'))], [true, 'clouds, maybe'], 'The typed draft of b.txt stays'); + await press(byKey('save:save')); await kept('saved the annotations'); + const summary = lines(folder, 'summaries'); + assert.deepEqual(summary.map(l => [l.record, l.state, l.value, l.from]), [['a.txt', 'accepted', 'A dog chases a red ball. In the park.', { model: 'writer', profile: 'writer-cpu', capability: 'chat_generation' }]]); + assert.deepEqual(Object.keys(summary[0]), ['record', 'sha256', 'state', 'value', 'by', 'at', 'from'], 'The keys of the line'); + const topics = lines(folder, 'topics'); + assert.deepEqual(topics.map(l => [l.record, l.state, l.value, l.from]), [['a.txt', 'draft', 'travel', { model: 'writer', profile: 'writer-cpu', capability: 'chat_generation' }], ['photo.png', 'draft', 'travel', { model: 'controlled-vision', profile: 'vision-cpu', capability: 'image_to_text' }]]); + check('5. Suggest: cancelled while writer was asked ("Asking writer…", the late answer dropped); asked again, shown "' + 'Suggested by writer · writer-cpu (chat_generation)' + '", changed by typing and kept; after Save the line of a.txt carries from {writer, writer-cpu, chat_generation}. "a fluffy animal, probably" refused beside the form with the term and the note as they were. Suggest for this page: "' + said.slice(0, 80) + '…"; the two drafts saved with their from'); + + // ---- 6. Typed text is never lost to a reading ------------------------------------------------------------------------ + const typed = () => evaluate(`({ key: document.activeElement.dataset.key, value: document.activeElement.value })`); + const still = async (label, typeInto, words) => { + await type(typeInto, words); + const before = await typed(); assert.deepEqual(before, { key: JSON.parse(typeInto.slice(10, -1)), value: words }); + await evaluate(WATCHER); await evaluate(`window.__still.start()`); + let since = Date.now(); await evaluate(`window.dispatchEvent(new Event('focus')); true`); await reading(since, WATCHED.concat(['map']), label + ': focus'); + since = Date.now(); await reading(since, WATCHED, label + ': the timer', Math.round((IDLE_MS + 8000) / 100)); + const r = await evaluate(`window.__still.stop()`); + for (const id of ['tabs', 'main', 'aside']) assert.deepEqual([r.counts[id].added, r.counts[id].removed, r.counts[id].attrs, r.counts[id].text, r.fresh[id]], [0, 0, 0, 0, 0], label + ': ' + id + ' untouched: ' + JSON.stringify(r.counts[id])); + assert.equal(r.flash, 0, label + ': no "Reading…"'); + assert.deepEqual(await typed(), before, label + ': the typed text and the focus stay'); + }; + await load('light', 'data/new%3Agenerate'); + await until(() => evaluate(`!!document.querySelector('#aside [data-key="newgenerate:field:title"]')`), 'the Generate form'); await settled('generate'); + await still('Generate', byKey('newgenerate:field:prompt'), 'Describe {n} clouds.'); + await load('light', 'train/endpoint'); await still('The endpoint', byKey('endpoint:set:field:address'), 'http://127.0.0.1:9'); + await load('light', 'annotate'); await pickTask('annotations/summaries'); await open('c.txt'); + await still('Annotate', byKey('ann:text'), 'A train leaves at nine.'); + check('6. With text typed in the Generate form, the endpoint\'s address and the annotation form, the window regaining focus and a reading on the timer added, removed and changed no node of the tab bar, the main area or the drawer, showed no "Reading…", and the text and the focus stayed'); + + // ---- 7. Screenshots ------------------------------------------------------------------------------------------------ + const seen = []; + const over = async label => { const o = await evaluate(`(() => { const m = document.getElementById('main'), a = document.getElementById('drawer'); return { page: document.documentElement.scrollWidth - innerWidth, main: m.scrollWidth - m.clientWidth, drawer: a.scrollWidth - a.clientWidth }; })()`); assert.ok(o.page <= 0 && o.main <= 1 && o.drawer <= 1, label + ': sideways overflow ' + JSON.stringify(o)); }; + const toEndpoint = () => evaluate(`(() => { document.querySelector('#main [data-key="open-endpoint"]').closest('ul').previousElementSibling.scrollIntoView({ block: 'start' }); return true; })()`); + const view = async (tag, name) => { await over(tag + ' ' + name); await shot(tag + '-' + name); seen.push(tag + ' ' + name); }; + const generateForm = async () => { await press(byKey('data:new:generate')); await until(() => evaluate(`!!document.querySelector('#aside .gen-form, #aside .gen-none')`), 'the Generate form'); await settled('generate'); }; + for (const [w, hgt] of [[1440, 900], [1000, 800]]) for (const name of ['light', 'dark']) { + const tag = name + '-' + w; + await size(w, hgt); + await api('set_endpoint', { address: null }); + await load(name, 'train'); await toEndpoint(); await view(tag, 'train-not-set'); + await hash('data'); await generateForm(); await view(tag, 'generate-none'); + await api('set_endpoint', { address: base }); + await load(name, 'train'); await toEndpoint(); await view(tag, 'train-set'); + await press(byKey('open-endpoint')); await settled('drawer'); + await type(byKey('endpoint:set:field:address'), 'http://192.168.1.5:8765'); await press(byKey('endpoint:set:set')); await kept('refused'); await refusal(); + await toEndpoint(); await view(tag, 'train-refusal'); + await hash('data'); await generateForm(); + await choose(byKey('newgenerate:field:make'), 'text'); await choose(byKey('newgenerate:field:model'), 'writer\u0000writer-cpu'); + await type(byKey('newgenerate:field:title'), 'Short poems'); await type(byKey('newgenerate:field:prompt'), 'Write line {n} of a short poem.'); + await view(tag, 'generate-text'); + await choose(byKey('newgenerate:field:make'), 'image'); await choose(byKey('newgenerate:field:model'), 'painter\u0000painter-gpu'); + await press(byKey('newgenerate:field:from-prompts')); await settled('prompts'); + await evaluate(`(() => { document.getElementById('drawer').scrollTop = 1e6; return true; })()`); + await view(tag, 'generate-image'); + await hash('annotate'); await pickTask('annotations/summaries'); await open('b.txt'); + await choose(byKey('ann:suggest-model'), 'writer\u0000writer-cpu'); await tell({ answer: 'Rain is coming to the hills tonight.' }); + await press(byKey('ann:suggest')); await until(async () => /Suggested by/.test(await mark() || ''), 'the suggestion'); await settled('suggestion'); + await view(tag, 'suggestion'); + await pickTask('annotations/topics'); await open('c.txt'); + await choose(byKey('ann:suggest-model'), 'writer\u0000writer-cpu'); await tell({ answer: 'trains and boats' }); + await press(byKey('ann:suggest')); await until(() => text('#main .ann-form .ann-sugrefusal'), 'the refusal'); await settled('refusal'); + if (w === 1000) await evaluate(`(() => { document.querySelector('#main .ann-form').scrollIntoView({ block: 'start' }); return true; })()`); + await view(tag, 'suggestion-refused'); + } + await size(1440, 900); + check('7. Nothing overflows sideways in light and dark at 1440 × 900 and 1000 × 800 (' + seen.length + ' views: the endpoint not set, set and refused, the Generate form without an endpoint, for text and for images, and a suggestion and a refusal)' + (shots ? '; screenshots in ' + shots : '')); + + // ---- Nothing failed --------------------------------------------------------------------------------------------------- + assert.deepEqual(errors, [], 'Script errors'); + const asked = failures.filter(f => f.url && ASKED.test(f.url)); + assert.ok(asked.length >= 7, 'The refusals asked for: ' + JSON.stringify(asked)); + assert.deepEqual(failures.filter(f => !asked.includes(f)), [], 'Failed requests'); + check('No script error, no failed request but the ' + asked.length + ' refusals of set_endpoint and suggest_annotation asked for'); + fs.writeFileSync(path.join(report, 'receipt.json'), JSON.stringify({ status: 'pass', folder, checks }, null, 2) + '\n'); + console.log('Receipt in ' + report); +})().catch(async error => { + process.exitCode = 1; + console.error(error); if (serverErrors) console.error('Server:', serverErrors.slice(-4000)); + console.error('Script errors:', JSON.stringify(errors)); console.error('Failed requests:', JSON.stringify(failures)); + try { if (evaluate) { await shot('failure'); console.error('Page:', (await evaluate('document.body.innerText')).slice(0, 3000)); } } catch (_) { /* the page is gone */ } + fs.writeFileSync(path.join(report, 'failure.json'), JSON.stringify({ status: 'failed', error: String(error && error.stack || error), checks, errors, failures }, null, 2) + '\n'); +}).finally(async () => { + try { session?.close(); } catch (_) { /* closed */ } + try { fake?.stdin.end(); } catch (_) { /* gone */ } + for (const child of children.reverse()) await stop(child); + if (owned) try { dropOwned(...owned); } catch (error) { console.error('Dropping the disposable schemas failed:', error.message); process.exitCode = 1; } + try { execFileSync('chmod', ['-R', 'u+w', temporary]); } catch (_) { /* nothing was made read-only */ } + fs.rmSync(temporary, { recursive: true, force: true }); +}); From 32b1d0d9e8884c93bbd3db9787423a204f57f00e Mon Sep 17 00:00:00 2001 From: MrScripty Date: Fri, 13 Nov 2026 19:15:27 -0700 Subject: [PATCH 077/131] fix(workspace): the dataset view no longer jumps back to its top; any file opens from Files About one time in eight, in the first second after a dataset was opened, the main area's scroll went back to its top with its content unchanged. No code of the page moved it: it was the browser's scroll anchoring. Tiles fill in after the view is drawn, and when the tile the browser had chosen as its anchor had its picture replaced, the scroll was put back to 0. The page keeps the main area's scroll itself, so anchoring is turned off there (overflow-anchor: none). A loop that reproduced it in 3 of 12 iterations, with every way of moving the scroll traced, ran 220 iterations clean with the rule. The Annotate tab's grid fills the same way and is covered by the same rule. The check no longer measures a press again: it asserts every press found its target, and a new step scrolls right after opening and asserts the scroll through the tiles filling, a timer reading and a return to the window. record takes a path as well as an id: any file of a product, or a member of an archive in it, is read as a record by its address, so the Files view opens texts, point clouds and meshes that are not among the product's records. Co-Authored-By: Claude Fable 5.2 --- docs/contracts/project-folder.md | 4 +-- .../definition-first-projects/spec-d1.md | 6 ++-- static/project-workspace/adapter.js | 2 ++ static/project-workspace/base.css | 5 ++- static/project-workspace/inside.js | 10 ++---- tests/browser_project_workspace_inside.cjs | 36 +++++++++++++++---- tests/test_tuldok_project_inside.py | 36 +++++++++++++++++++ tuldok_project/inside.py | 20 +++++++---- tuldok_project/operations.py | 8 +++-- tuldok_project/service.py | 2 +- 10 files changed, 97 insertions(+), 32 deletions(-) diff --git a/docs/contracts/project-folder.md b/docs/contracts/project-folder.md index 3b44f8bc..322dc696 100644 --- a/docs/contracts/project-folder.md +++ b/docs/contracts/project-folder.md @@ -2272,7 +2272,7 @@ and result keys of each operation are in its contract. | `recipe_results` | inspect | Read the summary rows of every benchmark subject made from one recipe, ungrouped or for one group. | | `draft_branch` | inspect | Write the text of a new recipe branched from one of the project's, with its name and what keeping it would find wrong; nothing is stored. | | `records` | inspect | Read one page of the records of a finished run's product, optionally of one kind or split, with the counts by kind and split. | -| `record` | inspect | Read one record of a finished run's product with its content: text, image size, sound peaks, points, mesh or arrays. | +| `record` | inspect | Read one record of a finished run's product by its id, or any file in it by its path, with its content: text, image size, sound peaks, points, mesh or arrays. | | `inside` | inspect | List a directory, an archive or the arrays of an .npz in a finished run's product. | | `array_slice` | inspect | Read a slice along two axes of an array in a finished run's product, as 32-bit floats. | | `array_summary` | inspect | Read the range, mean, deviation and histogram of an array in a finished run's product. | @@ -2468,7 +2468,7 @@ over all the records; records without a split are not counted in `splits`) and `problems` (each `{line, message}`, `line` null for a problem of the whole list). -**`record`** takes `id` and answers `record` (as above, with `media_type`: +**`record`** takes `id`, or `path` (an address) in its place, exactly one of the two, and answers `record` (as above, with `media_type`: the type of the file route for an image or a sound, with `url`, the file route's address for it; `text/plain` for text; else `application/octet-stream`) and `content`, by kind: diff --git a/docs/plans/definition-first-projects/spec-d1.md b/docs/plans/definition-first-projects/spec-d1.md index 5cdbb1da..d7603002 100644 --- a/docs/plans/definition-first-projects/spec-d1.md +++ b/docs/plans/definition-first-projects/spec-d1.md @@ -184,7 +184,7 @@ What differs from section 7, and why. - **"Look inside" sits under the card**, in a `.ds-item` that wraps the card's button (a button cannot hold a button), and in the drawer above Edit; it is drawn only when the dataset has a product with a run. A dataset with several products offers them in a select in the opened view's head, not on the card. - **What redraws what.** A person's selection (a click, or the left and right arrows) sets the tiles' `aria-pressed` in place and replaces only the viewer; it is not in the address. A page, a filter, the Files switch and a level of the tree draw the whole view again, built off the page and put in place (spec-w4 R8). The arrows cross to the next or previous page at the ends of one. While the next record is read the viewer keeps the one on screen for 250 ms, then says "Reading…" (it is not on screen yet). A reading that changed something draws the opened view again in place (spec-w4 R3): `tabs.js` passes the drawer's `_again` mark to `LabInside.open`. - **Files is browsed a level at a time**, with a line of links back up (Product / bundles / training-view.zip / samples), not as an expanding tree; a directory, an archive and an `.npy` or `.npz` open in place, an array or a file opens in the viewer. -- **What opens from the tree.** Arrays are read by their place (`array_slice` and `array_summary` take a path); images and sounds by the file route. A text, a point cloud or a mesh is opened through `record` when its address is a record's id (in a product read from its files it is), because no operation reads those kinds by address. A text, point cloud or mesh inside an archive, or one not among the records of a `records.jsonl` or a view, says so instead of opening: the server has no read for it. Section 7's "any file … opens in the same viewers" is therefore true of arrays, images and sounds only; the server was not changed. +- **What opens from the tree.** Arrays are read by their place (`array_slice` and `array_summary` take a path and an array's name). Any other file, on disk or a member of an archive, is read by `record` with `path` (added after review) and shown in the same viewer as a record: its id the address, its kind by its name, an image or a sound through the file route. - **Tiles.** An image tile reads its record to use the `url` the operation gives (two requests a tile: the record, the bytes); an array tile reads its record (an `.npz` needs `show`, which `records` gives only from a list) and one `array_slice` of `most` 48. Tiles are filled by an `IntersectionObserver` on the main area, 48 at most a page. A tile's id is cut at its start when long, so the file's name shows; the whole id is its title and label. - **The slice viewer is written in `inside.js`; catalog mode's `scientific-inspector.js` is not used.** That module is built around the catalog's field-sequence manifests (frames, fields named by the manifest, x, y and z axes, nested arrays of values) and writes its controls with `innerHTML`; an adapter would have had to make those manifests up from an `.npy` header. Here the slice is a heat map in a canvas, two axes chosen by selects when there are three or more, a slider for every other axis, the range, the value and full index under the pointer, and the summary's histogram on request. - **The stacked-slice drawing** (the mockup's `drawVolume`) reads up to ten positions of the first axis not drawn, at `most` 24 each, coloured on one range across them, the slider's slice outlined. A one-dimensional array is drawn as a line, not as a single row of cells. @@ -195,6 +195,4 @@ What differs from section 7, and why. What the check does not cover: the lab's products (with `--lab-root` it asserts nothing); a dataset with several products and its select; records from `records.jsonl` or a view, their problems shown, and the split filter (the fixture's product is read from its files and has no splits); a product with no records (the empty states are drawn, not exercised); Tab order and the focus ring, checked only by eye; turning a canvas by the keyboard; point clouds near 100,000 points and meshes near 60,000 triangles, whose drawing time was not measured; a theme changed while the view is open (the check reloads the page in each theme); the viewer's "Reading…" after 250 ms. -Found while running the check: twice in its first fifteen runs the press of Next landed on a tile instead. The main area had been scrolled to show the button, and its scroll was back at 0 when the press arrived. It did not recur in nine later runs traced for it (every `scrollTop` set to 0 and every `LabInside.open` logged), so what moved it is not known. The check now measures a target again when it is not the element under its point, and waits for the second page to be drawn rather than only for the page to settle. The cause was not found. - -**Open defect, found again in review.** In twelve more runs of the check, one failed the same way: the press of Next, made right after the dataset opened, did not reach the button. The check's own record of it: the main area went from a scroll of 283 back to 0 with its content the same height (1,142 in a frame of 809), 681 ms after the page loaded, still on the first page. So the content was not shorter and nothing was clamped: something set the scroll, or moved the focus to an element at the top, in the first second after the dataset view is drawn. It is about one run in twelve on this machine. A person would see the view jump to its top once, just after opening a dataset, if they had already scrolled. It is not yet explained; it is being reproduced in a loop with every way of moving the scroll traced. +**The view went back to its top once in its first second (found by the check, fixed after review).** About one run of the check in nine, the press of Next, made right after the dataset opened, landed on a tile: the main area had been scrolled to show the button and was back at 0 when the press arrived, with its content the same height. A loop of its own (one server; load Data, press "Look inside" after 0 to 1,000 ms, scroll Next into view after 0 to 800 ms, watch two seconds), with stacks recorded before the page's scripts ran for every `scrollTop` set, `scrollTo`, `scrollIntoView` and `focus`, every replacement of the main area's content, and a per-frame sample of its scroll and of the mutations in it, reproduced it in 3 of its first 12 iterations. No call of the page moved it: the last traced events were always the scroll to Next, then, about 200 ms later, a tile's glyph replaced (`span.th` +1 −1 and the refused array's tile marked `refused` when its slice was refused), then the scroll at 0 in the next frame. That is the browser's scroll anchoring: the anchor it had chosen lay in a tile whose picture was replaced, and the scroll was put back to the top. With `overflow-anchor: none` injected on the main area the same loop ran 40 iterations clean; with the fix in the page (`main { overflow-anchor: none }` in `base.css`: the page keeps the main area's scroll itself, spec-w4 R4) it ran 220 clean. The cause is shared CSS behaviour, not `app.js` or `tabs.js`; the Annotate tab, whose tiles also drop their glyph when their image loads, was exposed to it and is covered by the same rule. The check now scrolls the opened view down at once and asserts the scroll is unchanged after the tiles fill, a timer reading and a focus event, and it asserts that no press had to be measured again. diff --git a/static/project-workspace/adapter.js b/static/project-workspace/adapter.js index 17655c27..a3e845b3 100644 --- a/static/project-workspace/adapter.js +++ b/static/project-workspace/adapter.js @@ -111,6 +111,8 @@ window.TuldokProject = (() => { const product = { records: (run, { offset, limit, kind, split } = {}) => read('records', defined({ run, offset, limit, kind, split })), record: (run, id) => read('record', { run, id }), + /** Any file of the product, or a member of an archive in it, read as a record by its address. */ + recordAt: (run, path) => read('record', { run, path }), inside: (run, { path, offset, limit } = {}) => read('inside', defined({ run, path: path || null, offset, limit })), /** A slice; kept unless fresh (the viewer's slider). */ slice: (run, { path, array, axes, index, most }, fresh = false) => (fresh ? call : read)('array_slice', defined({ run, path, array, axes, index, most })), diff --git a/static/project-workspace/base.css b/static/project-workspace/base.css index b1b31209..b64d1ca1 100644 --- a/static/project-workspace/base.css +++ b/static/project-workspace/base.css @@ -429,7 +429,10 @@ body.shell { height: 100vh; display: grid; grid-template-rows: 48px auto auto 1f #needs-panel .needs li:first-child { border-top: 0; } #needs-panel .needs li:last-child { border-bottom: 0; } .stage { position: relative; min-height: 0; overflow: clip; display: grid; } -main { overflow: auto; padding: 18px 20px 40px; min-height: 0; min-width: 0; } +/* overflow-anchor: the page keeps the main area's scroll itself (putInPlace, spec-w4 R4). The browser's scroll + anchoring, left on, moved it back to the top when a tile's picture replaced its glyph in the first second after a + dataset opened (spec-d1 As built, D1b). */ +main { overflow: auto; overflow-anchor: none; padding: 18px 20px 40px; min-height: 0; min-width: 0; } main.map { padding: 10px 20px 12px; display: grid; grid-template-rows: auto auto minmax(0, 1fr); overflow: hidden; } main.map .tree-host { overflow: auto; min-height: 0; border: 1px solid var(--line); border-top: 0; border-radius: 0 0 var(--radius) var(--radius); background: var(--surface); } main.map > .filters { margin-bottom: 10px; } diff --git a/static/project-workspace/inside.js b/static/project-workspace/inside.js index 92b262e4..2ce407d1 100644 --- a/static/project-workspace/inside.js +++ b/static/project-workspace/inside.js @@ -383,16 +383,10 @@ window.LabInside = (() => { put('Split', r.split); put('Rights', r.rights); put('Origin', r.origin); put('Meta', r.meta); if (facts.children.length) el.appendChild(facts); } - /** A place in the tree that is not a record: an array by its path, an image or a sound by the file route; other kinds only as a record. */ + /** A place in the tree: an array by its path and name, any other file read as a record by its address (record's path). */ async function placeView(c, v, el, t) { if (t.kind === 'array') { el.appendChild(heading(t.path, 'Array')); await arrayView(el, v.run, t.path, t.arrays || [], t.array, settingsOf(v, 'path:' + t.path + '#' + t.array, () => ({}))); return; } - if (!t.path.includes('!')) { - try { await recordView(c, v, el, await R.record(v.run, t.path)); return; } catch (error) { if (error.code !== 'not-found') throw error; el.replaceChildren(); } - } - el.appendChild(heading(t.path, WORD[t.kind] || 'File')); - if (t.kind === 'image') imageView(el, R.fileUrl(v.run, t.path), null, null, t.path, settingsOf(v, 'path:' + t.path, () => ({ actual: false }))); - else if (t.kind === 'audio') audioView(el, R.fileUrl(v.run, t.path), null, t.path); - else el.appendChild(h('p', 'note', 'Not one of the product\'s records: Tuldok reads arrays, images and sounds by their place, and other kinds only as records.')); + await recordView(c, v, el, await R.recordAt(v.run, t.path)); // any file, inside an archive too, by its address } function textView(el, k) { const line = [count(k.characters != null ? k.characters : k.text.length, 'character'), k.truncated ? 'truncated: the first ' + k.text.length.toLocaleString('en-GB') + ' are shown' : null, k.replaced ? count(k.replaced, 'byte') + ' not UTF-8, shown as �' : null].filter(Boolean).join(' · '); diff --git a/tests/browser_project_workspace_inside.cjs b/tests/browser_project_workspace_inside.cjs index a46e02f5..941b4389 100644 --- a/tests/browser_project_workspace_inside.cjs +++ b/tests/browser_project_workspace_inside.cjs @@ -6,7 +6,9 @@ // product of 57 records: at least one of every kind (text, image, audio, point cloud, mesh, array, file), a zip // archive holding .npz arrays, and an array Tuldok refuses to read. The command line builds it before Tuldok starts. // 1. Data shows "Look inside" on that dataset and not on one without a product; the dataset opens to 48 tiles, -// the counts by kind are the fixture's, the pager reaches the rest, a kind filter narrows the grid. +// the counts by kind are the fixture's, the pager reaches the rest, a kind filter narrows the grid. Scrolled +// down as soon as it opens, it keeps its scroll while its tiles fill, through a timer reading and a focus event. +// Every press must find its target where it was measured. // 2. Each kind's viewer shows its record: the text equals the file's; the image is decoded at its true size; the // sound plays, with the right length and a drawn waveform; a point cloud and a mesh draw a canvas that is not // blank and changes when dragged (and a mesh above 60,000 triangles says it is drawn as points); the array's @@ -14,7 +16,7 @@ // draws; the array Tuldok refuses shows the server's sentence and the grid stays usable; left and right // arrows move the selection. // 3. "Files" lists the tree, opens the archive and an array inside it, whose value under the pointer is the -// fixture's. +// fixture's, and opens any file by its address: a text inside the archive, a mesh on disk. // 4. With the dataset open and a record selected, the window regaining focus and one reading on the timer add, // remove and change no node and keep every scroll (the counting of browser_project_workspace_still.cjs). When // something changes elsewhere (an agent asks for a build), the view is drawn again in place: same page, same @@ -112,7 +114,7 @@ async function settled(label) { } async function hash(value) { await evaluate(`location.hash = ${JSON.stringify('#' + value)}`); await settled('#' + value); await pause(200); await settled('#' + value); } const byKey = key => `[data-key=${JSON.stringify(key)}]`; -let moved = 0; // presses whose target was not under its point when measured (the layout moved between); counted, then measured again +let moved = 0; // presses whose target was not under its point when measured (the layout moved between); must stay 0 async function centre(selector) { for (;;) { const at = await until(() => evaluate(`(() => { const e = [...document.querySelectorAll(${JSON.stringify(selector)})].find(e => e.offsetParent !== null); if (!e) return null; e.scrollIntoView({ block: 'nearest', inline: 'nearest' }); const r = e.getBoundingClientRect(), x = r.left + r.width / 2, y = r.top + r.height / 2, hit = document.elementFromPoint(x, y); return { x, y, ok: !!hit && (hit === e || e.contains(hit)) }; })()`), 'shown: ' + selector, 100); @@ -255,6 +257,15 @@ const touched = (r, ids) => ids.filter(id => { const c = r.counts[id]; return c. assert.deepEqual(grid.chips, Object.assign({ all: TOTAL }, KINDS), 'The counts by kind are the fixture\'s'); assert.equal(grid.title, 'Specimens of every kind'); assert.match(grid.meta, new RegExp('run ' + run.slice(0, 8))); // Every tile carries its record's id; tiles never jump: each is a square picture and a line. + // The view keeps its scroll through its first seconds: scrolled down at once, then the tiles fill, the timer reads + // and the window regains focus (scroll anchoring once moved it back to the top here; spec-d1 As built, D1b). + const scrolled = await evaluate(`(() => { document.querySelector('#main [data-key="inside-next"]').scrollIntoView({ block: 'nearest' }); return document.getElementById('main').scrollTop; })()`); + assert.ok(scrolled > 50, 'The opened view scrolls at this size: ' + scrolled); + const since1 = Date.now(); + await reading(since1, WATCHED, 'the timer, with the view scrolled', Math.round((IDLE_MS + 15000) / 100)); + const since2 = Date.now(); await evaluate(`window.dispatchEvent(new Event('focus')); true`); await reading(since2, WATCHED.concat(['map']), 'focus, with the view scrolled'); + const kept1 = await evaluate(`({ top: document.getElementById('main').scrollTop, filled: [...document.querySelectorAll('#main .rec[data-lazy]')].filter(t => !t.querySelector('svg.glyph:not(.refused)')).length })`); + assert.equal(kept1.top, scrolled, 'The scroll is where it was after the tiles filled, a timer reading and a focus event: ' + JSON.stringify(kept1)); const ids = await evaluate(`[...document.querySelectorAll('#main .rec')].map(t => t.dataset.id)`); const listed = (await api('records', { run, limit: 48 })).records.map(r => r.id); assert.deepEqual(ids, listed, 'The tiles are the first page of records, in order'); @@ -269,6 +280,7 @@ const touched = (r, ids) => ids.filter(id => { const c = r.counts[id]; return c. assert.deepEqual(meshes, ['mesh meshes/cube.obj', 'mesh meshes/sphere.stl', 'mesh meshes/terrain.ply'], 'The kind filter narrows the grid'); await press(byKey('inside-kind-all')); await settled('all'); assert.equal(await evaluate(`document.querySelectorAll('#main .rec').length`), 48); + check('1. The opened view, scrolled to ' + scrolled + ' at once, kept that scroll while ' + kept1.filled + ' tiles filled and through a timer reading and a focus event'); check('1. "Look inside" on ' + REF + ' and on none of ' + without.join(', ') + '; opened at #' + OPENED + ' to 48 tiles of ' + TOTAL + ' with the counts ' + JSON.stringify(grid.chips) + '; Next showed ' + second.tiles + ' more (' + second.sum + '); Mesh narrowed the grid to ' + meshes.length); // ---- 2. Each kind's viewer ------------------------------------------------------------------------------------------- @@ -365,9 +377,18 @@ const touched = (r, ids) => ids.filter(id => { const c = r.counts[id]; return c. const inner = await probe(5, 7); assert.deepEqual(inner.index, [5, 7]); assert.equal(inner.value, 1000 + 5 * 10 + 7, 'The value inside the archive is the fixture\'s'); await press(byKey('crumb-bundles/training-view.zip')); await settled('back up'); - await press(byKey('entry-bundles/training-view.zip!readme.txt')); await settled('readme'); - const readme = await evaluate(`document.querySelector('#main .viewer .iv .note').textContent`); - check('3. Files listed ' + top.length + ' entries at the top; the archive opened to ' + inArchive.length + ' members; "' + crumbs.replace(/\s+/g, ' ') + '" listed target, whose value at ' + JSON.stringify(inner.index) + ' is ' + inner.value + '; a text inside the archive says: "' + readme + '"'); + // Any file opens from the tree by its address: a text inside the archive, a mesh on disk. + await press(byKey('entry-bundles/training-view.zip!readme.txt')); + await until(() => evaluate(`(() => { const t = document.querySelector('#main .viewer .iv-text'); return !!t && document.querySelector('#main .viewer .iv-head h3').textContent === 'bundles/training-view.zip!readme.txt'; })()`), 'the text inside the archive'); await settled('readme'); + const readme = await evaluate(`document.querySelector('#main .viewer .iv-text').textContent`); + assert.equal(readme, 'Two samples, stored.\n', 'The text inside the archive is the fixture\'s'); + await press(byKey('crumb-')); await settled('the top'); + await press(byKey('entry-meshes')); await settled('meshes'); + await press(byKey('entry-meshes/cube.obj')); + await until(() => evaluate(`!!document.querySelector('#main .viewer canvas.iv-3d') && document.querySelector('#main .viewer .iv-head h3').textContent === 'meshes/cube.obj'`), 'the mesh from the tree'); await settled('cube'); + const cube = await pixels('#main .viewer canvas.iv-3d'); + assert.ok(cube.drawn > 500 && /8 vertices and 12 triangles/.test(cube.label), 'The mesh opened from the tree is drawn: ' + JSON.stringify(cube)); + check('3. Files listed ' + top.length + ' entries at the top; the archive opened to ' + inArchive.length + ' members; "' + crumbs.replace(/\s+/g, ' ') + '" listed target, whose value at ' + JSON.stringify(inner.index) + ' is ' + inner.value + '; the text inside the archive read "' + readme.trim() + '"; meshes/cube.obj opened from the tree (' + cube.label.split('.')[0] + ')'); // ---- 4. Nothing changed: the window regains focus, the timer reads ------------------------------------------------- await press(byKey('inside-mode-records')); await settled('records'); @@ -436,7 +457,8 @@ const touched = (r, ids) => ids.filter(id => { const c = r.counts[id]; return c. assert.deepEqual(errors, [], 'Script errors'); assert.deepEqual(failures, [], 'Failed requests'); assert.ok(refusedOk.length > 0, 'The refused array was asked for'); - check('No script error, no failed request but the ' + refusedOk.length + ' refusals of arrays/complex.npy asked for' + (moved ? '; ' + moved + ' presses measured again because their target was not under its point' : '')); + assert.equal(moved, 0, 'Every press found its target under its point (the page did not move between measuring and pressing)'); + check('No script error, no failed request but the ' + refusedOk.length + ' refusals of arrays/complex.npy asked for; every press found its target where it was measured'); fs.writeFileSync(path.join(report, 'receipt.json'), JSON.stringify({ status: 'pass', folder, checks }, null, 2) + '\n'); console.log('Receipt in ' + report); })().catch(async error => { diff --git a/tests/test_tuldok_project_inside.py b/tests/test_tuldok_project_inside.py index afc89097..288519bb 100644 --- a/tests/test_tuldok_project_inside.py +++ b/tests/test_tuldok_project_inside.py @@ -609,6 +609,42 @@ def with_view(document): listed = self.call('records', run=self.run_id) self.assertEqual((listed['source'], [record['id'] for record in listed['records']]), ('view', ['field.npy'])) + def test_a_file_by_path_on_disk_and_inside_an_archive(self): + points = [(0, 0, 0, 255, 0, 0), (1, 2, 3, 0, 255, 0)] + members = {'deep/note.txt': 'inside the archive', 'deep/cube.obj': obj_cube(), + 'deep/points.ply': ply_points_ascii(points)} + self.write('notes/a.txt', 'on disk') + self.write('shapes/points.ply', ply_points_ascii(points)) + self.write('shapes/cube.obj', obj_cube()) + self.write('bundle.zip', zip_bytes({name: data if isinstance(data, bytes) else data.encode() + for name, data in members.items()}, zipfile.ZIP_DEFLATED)) + for prefix in ('', 'bundle.zip!deep/'): + text = self.call('record', run=self.run_id, path=(prefix or 'notes/a') + ('note.txt' if prefix else '.txt')) + self.assertEqual((text['record']['kind'], text['content']['text']), + ('text', 'inside the archive' if prefix else 'on disk')) + where = prefix or 'shapes/' + cloud = self.call('record', run=self.run_id, path=where + 'points.ply') + self.assertEqual((cloud['record']['id'], cloud['record']['kind'], cloud['content']['count']), + (where + 'points.ply', 'pointcloud', 2)) + self.assertEqual(floats(cloud['content']['points_f32']), [0, 0, 0, 1, 2, 3]) + mesh = self.call('record', run=self.run_id, path=where + 'cube.obj') + self.assertEqual((mesh['record']['kind'], mesh['content']['vertices'], mesh['content']['triangles']), + ('mesh', 8, 12)) + # A member of an archive is not a record: by id it is not found, by path it is read. + with self.assertRaises(store.ProjectError) as caught: + self.call('record', run=self.run_id, id='bundle.zip!deep/note.txt') + self.assertEqual(caught.exception.code, 'not-found') + for arguments, code in (({'path': '../outside.txt'}, 'invalid'), ({'path': '/etc/hostname'}, 'invalid'), + ({'path': 'notes/missing.txt'}, 'not-found'), ({'path': 'notes'}, 'invalid'), + ({'id': 'notes/a.txt', 'path': 'notes/a.txt'}, 'invalid'), ({}, 'invalid')): + with self.subTest(arguments=arguments), self.assertRaises(store.ProjectError) as caught: + self.call('record', run=self.run_id, **arguments) + self.assertEqual(caught.exception.code, code) + os.symlink('/etc/hostname', self.output / 'notes' / 'out.txt') + with self.assertRaises(store.ProjectError) as caught: + self.call('record', run=self.run_id, path='notes/out.txt') + self.assertEqual(caught.exception.code, 'not-found') + def test_refusals(self): with self.assertRaises(store.ProjectError) as caught: self.call('records', run='f' * 32) diff --git a/tuldok_project/inside.py b/tuldok_project/inside.py index c46b77d0..59949803 100644 --- a/tuldok_project/inside.py +++ b/tuldok_project/inside.py @@ -483,12 +483,20 @@ def _content(record, place): @reading -def record(product, identifier): - index = index_of(product) - position = index.by_id.get(identifier) - if position is None: - raise ProjectError(f'There is no record {identifier} in this product.', 'not-found') - found = index.records[position] +def record(product, identifier=None, *, path=None): + """One record with its content, by its id; or, by path, the file or archive member at that address read as a + record of a product read from its files would be (its id the address, its kind by its name).""" + if (identifier is None) == (path is None): + raise ProjectError('Name a record by id or a file by path, one of the two.', 'invalid') + if path is not None: + place = locate(product.root, path) # refuses a malformed address, a directory and what is not there + found = _record(path, kind_by_name(path, lambda: place.head(64 * 1024)), path, size=place.size) + else: + index = index_of(product) + position = index.by_id.get(identifier) + if position is None: + raise ProjectError(f'There is no record {identifier} in this product.', 'not-found') + found = index.records[position] shown = _shown(product, found, preview=False) place = locate(product.root, found['path']) if found['path'] is not None else None extension = _extension(found['path'] or '') diff --git a/tuldok_project/operations.py b/tuldok_project/operations.py index 68b19015..82071a5c 100644 --- a/tuldok_project/operations.py +++ b/tuldok_project/operations.py @@ -176,9 +176,11 @@ def _arguments(required=(), **properties): _arguments(['run'], run=_RUN, offset=_OFFSET, limit=_limit(200), kind={'type': 'string', 'enum': list(RECORD_KINDS)}, split=_TEXT), ('records', 'total', 'source', 'kinds', 'splits', 'problems')), - Operation('record', "Read one record of a finished run's product with its content: text, image size, sound " - 'peaks, points, mesh or arrays.', 'inspect', False, - _arguments(['run', 'id'], run=_RUN, id={'type': 'string', 'minLength': 1, 'maxLength': 4096}), + Operation('record', "Read one record of a finished run's product by its id, or any file in it by its path, " + 'with its content: text, image size, sound peaks, points, mesh or arrays.', 'inspect', False, + dict(_arguments(['run'], run=_RUN, id={'type': 'string', 'minLength': 1, 'maxLength': 4096}, + path={'type': 'string', 'minLength': 1, 'maxLength': 4096}), + oneOf=[{'required': ['id']}, {'required': ['path']}]), ('record', 'content')), Operation('inside', "List a directory, an archive or the arrays of an .npz in a finished run's product.", 'inspect', False, diff --git a/tuldok_project/service.py b/tuldok_project/service.py index 27e6c506..021ecb0e 100644 --- a/tuldok_project/service.py +++ b/tuldok_project/service.py @@ -66,7 +66,7 @@ INSIDE_READS = { 'records': lambda found, a: inside.records(found['run'], offset=a.get('offset', 0), limit=a.get('limit', 50), kind=a.get('kind'), split=a.get('split')), - 'record': lambda found, a: inside.record(found['run'], a['id']), + 'record': lambda found, a: inside.record(found['run'], a.get('id'), path=a.get('path')), 'inside': lambda found, a: inside.inside(found['run'], path=a.get('path', ''), offset=a.get('offset', 0), limit=a.get('limit', 200)), 'array_slice': lambda found, a: inside.array_slice(found['run'], path=a['path'], array=a.get('array'), From b427c3cd825255d4830ba01d44e905727261dbed Mon Sep 17 00:00:00 2001 From: MrScripty Date: Fri, 13 Nov 2026 19:38:17 -0700 Subject: [PATCH 078/131] docs(plan): ledger entry for the data tools, phases 1 to 5 Co-Authored-By: Claude Fable 5.2 --- .../data-tools-plan.md | 2 + .../execution-ledger.md | 40 +++++++++++++++++++ 2 files changed, 42 insertions(+) diff --git a/docs/plans/definition-first-projects/data-tools-plan.md b/docs/plans/definition-first-projects/data-tools-plan.md index bce5b313..38e65715 100644 --- a/docs/plans/definition-first-projects/data-tools-plan.md +++ b/docs/plans/definition-first-projects/data-tools-plan.md @@ -2,6 +2,8 @@ **Status: approved by the owner on 2026-11-13, with the changes under "The owner's answer" below.** +**Built, 2026-11-13:** phases 1 to 5, on `feat/definition-first-projects`, not pushed; the specs `spec-d1.md` to `spec-d5.md` say what was built and what was not verified, and the [ledger](execution-ledger.md) has the record. **Not built:** phase 6. **Not run:** anything against a real Pumas endpoint, which waits for the owner's word (decision 3). The owner has not yet looked at these pages. + ## The owner's answer > we will use the pumas endpoint. We wont be embedding pumas. What do you mean by lables? Right now we just need the basic modality support for data generation and annotation. text, image, audio, 3D (point clouds, mesh). We dont have a specific need for the surrogate lab. This is more a setup so other projects can setup what they need to generate. The rest sounds good. You can go ahead diff --git a/docs/plans/definition-first-projects/execution-ledger.md b/docs/plans/definition-first-projects/execution-ledger.md index bc73d68b..4ac28aef 100644 --- a/docs/plans/definition-first-projects/execution-ledger.md +++ b/docs/plans/definition-first-projects/execution-ledger.md @@ -644,3 +644,43 @@ The tab bar was rebuilt with each of those, the strip on every reading, and the **Not verified:** what each spec's "As built" lists; a real `.safetensors` written by the library; a copy across file systems in `import`; the standards service was unavailable (see the entry above). **Next:** the cause of the scroll going back; the Weights block of a model's drawer; the Annotate tab with the Import and Freeze forms; then phase 5. + +## 2026-11-13 — data tools: phases 1 to 5 are built + +**Commits** on `feat/definition-first-projects`, none pushed: the Weights block `8b7ff525`; the Annotate tab with Import and Freeze `c41f360c`; the endpoint, `generate` and suggestions, server side `f6231508`; their page `fc145a48`; the dataset view's scroll and `record` by path `32b1d0d9`; merged as `636da697` and `d95aeb4f`. + +**What a project folder has now** (the plan's five phases): + +1. **Looking inside data.** A dataset opens to its records as a paged grid with a viewer per kind (text, image, sound, point cloud, mesh, array) and a Files view in which any file or archive member opens. +2. **Weights by layer.** A model's drawer shows its weights file by layer, how each layer's values are distributed, a tensor as images, and the change from the weights it started from or from the model it derives from. +3. **The Pumas 0.8.0 client,** following the released contract. +4. **Annotation.** Tasks as a kind of definition; annotations as lines in Git; the Annotate tab with a form per task (decision, class, tags, text, boxes, spans, segments); Import and Freeze as steps Tuldok runs. +5. **Through the Pumas endpoint.** The endpoint as a setting of the machine, shown on the Train tab; a Generate form and the step `generate` for text and image datasets; Suggest in Annotate. + +**The open defect of the last entry is closed.** The dataset view's jump to its top was the browser's scroll anchoring: tiles fill in after the view is drawn, and when the tile the browser had chosen as its anchor had its picture replaced, the scroll was put back to 0. No code of the page moved it. A loop with every way of moving the scroll traced reproduced it in 3 of 12 iterations; with `overflow-anchor: none` on the main area, which keeps its scroll itself, 220 iterations were clean. The Annotate tab's grid fills the same way and is covered by the same rule. One correction to how this was handled: the agent sent to find it waited on a test run of the reviewer's that had been held up, and stood idle for about an hour and a half before that was noticed. + +**Acceptance on the merged tip `d95aeb4f`:** + +| Claim | Evidence | Result | +| --- | --- | --- | +| The project folder's code behaves as its tests say | `python -m unittest discover -s tests -p 'test_tuldok_project_*.py'`, on a disposable PostgreSQL | 719 pass | +| The agent interface and the Pumas client are unchanged in what catalog mode uses | `test_agent_api`, `test_agent_negotiation`, `test_agent_http`, and the seven modules of the Pumas client and its fakes | 123 pass, 4 skipped as before | +| Each page part does what its spec says, in a real browser against a served fixture | `browser_project_workspace_inside`, `_weights`, `_annotate`, `_endpoint`, `_actions`, `_still` and `browser_project_workspace` | 8, 7, 11, 8, 27, 6 and 23 steps pass | +| The lab's folder still opens | `python -m tuldok_project check` on `projects/surrogate-lab`, read only | 0 errors, the same 8 warnings | +| Generation and suggestions work against a real endpoint | one small text dataset, one small image dataset and one suggestion through the owner's Pumas | **not run**: it needs the owner's word, and uses that machine's GPU for a moment | +| The pages are what the owner wants | the owner looks at them | **pending** | + +Everything that speaks to Pumas was checked against a fake endpoint built from the released contract. No running Pumas was contacted and this machine's listeners were not scanned. + +**Known limits,** each in its spec's "As built": + +- The endpoint must be a numeric loopback address on this machine: that is what the 0.8.0 client sends to and what Pumas 0.8.0 serves on. +- Pumas 0.8.0 makes text and images. Audio and 3D datasets come from `import` or a project's own command. +- `set_annotation` does not refuse when the annotation changed since the form was drawn: of two people keeping the same record, the later one wins without a warning. +- Cancelling a suggestion drops its answer; the request to the endpoint runs to its end. +- The endpoint's state on the Train tab is not read again on the timer. +- The whole repository suite (catalog mode included, about an hour) was not run after the data tools; the project suite, the agent interface and the Pumas client were. + +**Not built:** phase 6, native, predicted and signed error side by side in the Analysis tab. + +**Next:** the owner looks at the pages; on the owner's word, the run against a real endpoint. From 36061650d03be583fc011729eaf7c9ce470d20bd Mon Sep 17 00:00:00 2001 From: MrScripty Date: Wed, 18 Nov 2026 22:24:15 -0700 Subject: [PATCH 079/131] feat(workspace): Benchmarks opens on a benchmark with results and an accuracy-against-time chart Co-Authored-By: Claude Opus 5.5 --- static/project-workspace/tabs.js | 16 +++++++++++++--- tests/browser_project_workspace.cjs | 8 ++++++++ 2 files changed, 21 insertions(+), 3 deletions(-) diff --git a/static/project-workspace/tabs.js b/static/project-workspace/tabs.js index 565512f1..299ee90e 100644 --- a/static/project-workspace/tabs.js +++ b/static/project-workspace/tabs.js @@ -103,11 +103,21 @@ return Promise.all(defs.map(async d => { const full = await P.read('definition', { reference: d.reference }); const doc = full.document || {}; return { reference: d.reference, title: d.title, benchmark: typeof doc.benchmark === 'string' ? nameOfRef(doc.benchmark) : null, form: doc.form }; })); } async function benchmarkList() { - const [overview, defs] = await Promise.all([P.read('results_overview'), P.read('definitions', { kind: 'benchmark' })]); + const [overview, defs, charts] = await Promise.all([P.read('results_overview'), P.read('definitions', { kind: 'benchmark' }), chartIndex()]); const titles = new Map(defs.definitions.map(d => [nameOfRef(d.reference), d])); - return overview.benchmarks.map(b => ({ ...b, title: titles.has(b.benchmark) ? titles.get(b.benchmark).title : b.benchmark, state: titles.has(b.benchmark) ? titles.get(b.benchmark).state : null })); + return overview.benchmarks.map(b => ({ ...b, title: titles.has(b.benchmark) ? titles.get(b.benchmark).title : b.benchmark, state: titles.has(b.benchmark) ? titles.get(b.benchmark).state : null, + forms: charts.filter(c => c.benchmark === b.benchmark).map(c => c.form) })); } - const pickBenchmark = (list, wanted) => (list.find(b => b.benchmark === wanted) || list.find(b => b.subjects_with_results > 0) || list[0] || null); + /** + * The benchmark the tab shows: the one asked for; else, among those with + * results, the first with an accuracy-against-time chart, then the first + * with any chart, then the first; else the first of all. + */ + const pickBenchmark = (list, wanted) => { + const withResults = list.filter(b => b.subjects_with_results > 0); + return list.find(b => b.benchmark === wanted) || withResults.find(b => (b.forms || []).includes('tradeoff')) + || withResults.find(b => (b.forms || []).length) || withResults[0] || list[0] || null; + }; /** * One benchmark as the tab shows it: its metrics, its subjects (each with * the model of its recipe from the map, its values per metric for every diff --git a/tests/browser_project_workspace.cjs b/tests/browser_project_workspace.cjs index 53c24d53..9adf472a 100644 --- a/tests/browser_project_workspace.cjs +++ b/tests/browser_project_workspace.cjs @@ -142,6 +142,14 @@ async function otherTabs(map) { for (const theme of ['light', 'dark']) { // Benchmarks: pick, hover and focus a point, sort, compare two, open one. await open(theme, 'benchmarks'); await settled('benchmarks'); + if (theme === 'light') { // opened without a choice: a benchmark with results and an accuracy-against-time chart, if there is one + const has = (name, form) => Object.values(chartBench).some(c => c.benchmark === name && (!form || c.form === form)); + const withResults = overview.benchmarks.filter(b => b.subjects_with_results > 0); + const expected = (withResults.find(b => has(b.benchmark, 'tradeoff')) || withResults.find(b => has(b.benchmark)) || withResults[0] || overview.benchmarks[0]).benchmark; + const shown = await evaluate(`document.querySelector('#main select[data-key="benchmark"]').value`); + assert.equal(shown, expected, 'The tab opens on a benchmark with results and an accuracy-against-time chart'); + check('Benchmarks opens on ' + shown); + } await choose('#main select[data-key="benchmark"]', bench); const drawn = await evaluate(`({ charts: document.querySelectorAll('#main .bench-chart').length, svgs: document.querySelectorAll('#main .bench-chart svg').length, rows: document.querySelectorAll('#main .bench-all tbody tr').length, coverage: document.querySelector('#main .coverage').innerText, heads: [...document.querySelectorAll('#main .bench-chart .sect')].map(e => e.innerText.replace(/\\n/g, ' ')) })`); assert.equal(drawn.charts, Object.values(chartBench).filter(c => c.benchmark === bench).length, 'One section per chart of ' + bench); From 8f7dfad776e7b1aa3ffc1f3d5b427d0bae243a2a Mon Sep 17 00:00:00 2001 From: MrScripty Date: Wed, 18 Nov 2026 22:43:57 -0700 Subject: [PATCH 080/131] docs(research): Tuldok against annotation, tracking, generation, model-viewing and physics-AI tools Co-Authored-By: Claude Opus 5.5 --- docs/research/competitive-landscape/README.md | 212 ++++++++++++++++++ 1 file changed, 212 insertions(+) create mode 100644 docs/research/competitive-landscape/README.md diff --git a/docs/research/competitive-landscape/README.md b/docs/research/competitive-landscape/README.md new file mode 100644 index 00000000..137c6e96 --- /dev/null +++ b/docs/research/competitive-landscape/README.md @@ -0,0 +1,212 @@ +# Tuldok and the tools that do the same jobs + +Researched 2026-11-18. Four areas were surveyed in parallel: annotation and dataset curation; experiment tracking, lifecycle and versioning; synthetic data generation, model visualisation and evaluation harnesses; physics-AI and simulation-surrogate platforms. Web facts were read on 2026-11-18 unless dated otherwise. Open-source repositories were cloned shallowly and read, never built or run, under `workspace/scratch/competitor-repos/` (about 2.4 GB in all: label-studio, cvat, argilla, doccano, mlflow, clearml, dvc, aim, zenml, distilabel, netron, WeightWatcher, BlenderProc, model-explorer, lm-evaluation-harness, physicsnemo, neuraloperator, PDEBench, the_well, deepxde). FiftyOne (2.1 GB) was grepped and deleted; Rerun was read through the GitHub tree. + +**[unverified]** marks a claim taken from vendor marketing, an aggregator or memory and not confirmed in a primary source. Tuldok's column describes the branch `feat/definition-first-projects` as of today (project-folder mode, the Map workspace, data tools phases 1 to 6) plus catalog mode. + +## 1. The short answer + +**Nobody else does the whole loop.** Tuldok's purpose is: make or import data, look inside it, annotate it, freeze it, define models and how they are trained, build them, benchmark them, and see the results. That spans what is usually four products: + +| Job | Usual tools | Tuldok | +| --- | --- | --- | +| Annotate and curate | Label Studio, CVAT, FiftyOne, Encord, Labelbox | Annotate tab, Look inside, Freeze | +| Track, version, reproduce | MLflow, W&B, ClearML, DVC, ZenML | Git folder of definitions, Map, Train, builds | +| Generate data, inspect models, evaluate | distilabel, Replicator, Netron, TensorBoard, lm-eval | Generate via Pumas, Weights, Benchmarks | +| Physics surrogates | PhysicsNeMo, NeuralOperator, SimAI, PhysicsX, Simcenter | Benchmarks, Analysis (kept fields), project's own solver step | + +**Three things only Tuldok has**, confirmed by searching the code of the open tools and the documentation of the closed ones: + +1. **An accuracy-against-time chart with the Pareto frontier.** No tracker (MLflow, ClearML, DVC, ZenML, Aim: a code search for "pareto" finds nothing), no harness (lm-eval, HELM, Inspect, Promptfoo, MLPerf) and no physics benchmark (PDEBench, The Well, PhysicsNeMo-CFD) draws one. MLPerf sets an accuracy pass mark and then ranks by speed; HELM and Promptfoo add speed as a column; W&B can be made to draw one with a custom Vega panel. For a project with two targets, accuracy-first models and real-time models, this is the central view, and it is Tuldok's. +2. **A family tree of models.** Others draw how files were produced: W&B artifact lineage, ClearML parent tasks, ZenML pipeline DAGs, DVC `dvc dag`, Valohai data heritage, Ansys SimAI's 2026 R1 Build panel. None shows which model derives from which with the kind of change, groups and comparisons, as the Map does. The nearest real model tree is the Hugging Face Hub's `base_model` tree, outside these tools. +3. **A project that is a Git folder of definitions only,** with the working copy in a database, weights and products kept out of Git on the machine, and no hash lockfiles. Only DVC (`dvc.yaml`, plots declared in files, experiments as Git refs) and Valohai (`valohai.yaml`) keep definitions in Git, and DVC rests on hash lockfiles. Charts declared as files: Tuldok and DVC only. + +**Also rare:** agents may ask for a build and only the owner approves it (Valohai's `require-approval` nodes and ZenML's Slack ask-steps come close; no tool has a queue of agent requests); annotations stored as text in Git (CVAT removed its Git sync; Hugging Face datasets are Git repositories but have no annotation); one viewer for text, image, audio, point clouds, meshes and arrays (FiftyOne has no audio; Label Studio Community has no 3D; Rerun views but does not annotate); weights compared with the weights a model started from or with its parent (WeightWatcher compares base and fine-tuned models; nobody else links it to an ancestry). + +**Where Tuldok trails,** in the order that matters for its stated purpose: + +1. **Physics-specific learning:** no model zoo or pretrained physics models (PhysicsNeMo, NeuralOperator, The Well checkpoints), no mesh/CAD-native geometric learning, no physics-informed losses, no confidence or out-of-range flag per prediction (SimAI, physicsAI and Rescale all sell this). +2. **Scale:** no multi-GPU, cluster or cloud training; no hyperparameter search. +3. **Live training views:** no live loss curves, no weight histograms over training, no parallel-coordinates plot (nearly every tracker has one). +4. **Annotation breadth:** no polygons, masks, keypoints, cuboids or tracking; no video; no QA by consensus or ground truth; no curation by embeddings or similarity; no rank or rate questions; no standard export formats (COCO, YOLO, KITTI): Tuldok writes JSON and JSONL. +5. **Model structure:** no drawn architecture graph (Netron, Model Explorer, TensorBoard), no activations or attribution (Captum). +6. **Generation breadth:** Pumas 0.8.0 makes text and PNG images only; nothing renders 3D scenes with ground truth (Replicator, BlenderProc, Kubric), and generated data gets no real-against-synthetic quality report (SDV, MOSTLY AI). +7. **Ecosystem:** no hosted option, no large community, no ready task catalogues. + +**The market is unstable,** which favours Tuldok's choice of plain definition files that do not depend on one vendor: + +- Neptune shut down in March 2026 and deleted user data with no export. +- lakeFS bought DVC (2025-11) and moved lakeFS itself to BSL 1.1 (2026-09-22); DVC stays Apache-2.0. +- ClearML's server is SSPL, W&B self-hosting needs a licence, and SDV is BSL. +- Argilla is in maintenance only, HELM entered maintenance mode on 2026-06-01, Unity Perception is discontinued, and NeMo Microservices shut down on 2026-10-01. +- Gretel went to NVIDIA, Monolith to CoreWeave, Altair to Siemens, Promptfoo to OpenAI (announced 2026-03-09), and W&B is CoreWeave's. +- Determined, Pachyderm and Guild AI look dormant, and Aim's main branch has had no commits since 2025-12-31. + +## 2. Area by area + +### 2.1 Annotation, curation and looking at data + +| Tool | Licence, price | Closest overlap with Tuldok | Better than Tuldok | Tuldok has, it lacks | +| --- | --- | --- | --- | --- | +| **Label Studio** 1.23 | Apache-2.0 open core; Starter Cloud and Enterprise by quote | Its ML backend: an HTTP server with `/predict`, `/setup`, `/train`, `/health`, predictions stored with a `model_version` for a person to accept (`label_studio/ml/api_connector.py`). The nearest thing to Pumas suggestions | About 20 control tags (polygon, brush, keypoint, relations, ranker, pairwise, time series, video tracking, PDF); about 10 export formats | 3D in the open edition (LiDAR is Enterprise), meshes, arrays, annotations in Git, frozen releases, training and benchmarks | +| **CVAT** 2.83 | MIT; cloud from $23/user/month yearly | 3D point clouds with cuboids, audio (new in 2026), and a pull-based CLI agent that runs your own model | The 2D/3D vision editor, tracking with interpolation, quality control and consensus, about 30 export formats | Meshes, arrays, text; Git sync was removed (`cvat/apps/dataset_repo/README.md`); no releases; no training | +| **FiftyOne** 1.22 | Apache-2.0 open core; enterprise "Voxel51" by quote | Meshes (glTF, OBJ, PLY, STL), point clouds, Gaussian splats, MCAP/ROS/Rerun import | Curation: views, embeddings, similarity, evaluation panels, large model zoo | Audio; annotations in Git; versioning (Enterprise only: read-only snapshots) | +| **Rerun** 0.43 | Apache/MIT; Hub priced per deployment | Viewing `volume_3d`, `voxel_grid_map`, `tensor`, `mesh3d`, audio | Large time-indexed 3D and volume viewing; a reference design for solver fields | Any annotation | +| **Argilla** 2.8 | Apache-2.0, maintenance only | Suggestions with the model that made them | Rank and rate questions, vector search | 3D, audio, being maintained | +| **Doccano** 1.8 | MIT | Auto-labelling through any REST endpoint, with a response mapping | Sequence labelling, intent and slot | 3D, releases, training | +| **Prodigy** | Proprietary; $390 personal, $490 per seat | Local, scriptable, model-in-the-loop accept or reject | The fastest accept/reject flow; any API from a recipe | 3D, frozen releases, open source | +| **Hugging Face Hub** | Hosted; viewer on private data needs a paid plan | Every dataset is a Git repository | Distribution at scale, SQL console | 3D viewer, annotation | +| **Encord, Labelbox, V7, Supervisely, SuperAnnotate, Scale Nucleus, Roboflow** | Closed, mostly by quote | Encord: LiDAR to 10M points a frame, DICOM; Supervisely: the widest modality range, meshes by export apps | Team workflows, QA, active learning, hosted models | Local-first, open, Git text, links to training and benchmarks | + +### 2.2 Tracking, lifecycle, versioning + +| Tool | Licence, price | Core model | Better than Tuldok | Tuldok has, it lacks | +| --- | --- | --- | --- | --- | +| **MLflow** 3.18 | Apache-2.0 | Logged runs in SQLite by default; registry; GenAI tracing | Autologging, scale, serving; a built-in MCP server and an in-app assistant (`mlflow/mcp/server.py`, `mlflow/assistant/`); parallel coordinates and scatter | Definitions in Git, model tree, Pareto chart, approval, annotation, weights | +| **W&B** | SDK MIT, server proprietary; self-hosting licensed | Logged runs; Artifacts lineage DAG | Polish, Sweeps, Reports, collaboration; official MCP server | Free local use beyond personal, definitions in Git, approval | +| **ClearML** 2.2 | SDK Apache-2.0, server SSPL | Auto-captured runs; clone, edit, re-enqueue | Remote execution on queues, comparisons, HPO | Open server licence, Git definitions, model tree | +| **DVC** | Apache-2.0 (now owned by lakeFS) | `dvc.yaml` stages in Git, plots in files, `dvc repro` | Content-addressed remote for large files, experiments as Git refs | GUI (only Studio), roles, MCP, model semantics; Tuldok avoids its hash lockfiles | +| **ZenML** 0.98 | Apache-2.0; Pro paid | Code-defined pipelines, model control plane | Orchestration across stacks; official MCP server; ask-steps for approval | Git definitions, model tree, Pareto | +| **Valohai** | Commercial | `valohai.yaml` in Git, immutable outputs | `require-approval` pipeline nodes, managed compute | Open source, local | +| **Aim, TensorBoard, Trackio** | Apache-2.0 / Apache-2.0 / MIT | Local logged metrics | Live curves, histograms, HParams, projector (TensorBoard); W&B-compatible logging (Trackio) | Definitions, lineage, roles | +| **Kubeflow, Metaflow, Polyaxon, Determined, Pachyderm** | Apache-2.0 | Cluster pipelines | Distributed training, HPO | Local simplicity; two are dormant | +| **Neptune** | Shut down March 2026 | | | A warning about SaaS-only tracking | + +### 2.3 Generation, model inspection, evaluation + +| Tool | What it is | Better than Tuldok | Tuldok has, it lacks | +| --- | --- | --- | --- | +| **distilabel** (Apache-2.0; last commit 2025-12-15) | LLM pipelines for synthetic text: Self-Instruct, Evol-Instruct, Magpie, UltraFeedback, judges; any OpenAI-compatible `base_url`; Ray | Recipes and judges, many providers, scale-out | Review built in, frozen releases, non-text data | +| **NeMo Data Designer** (ex-Gretel, Apache-2.0) | Column-by-column datasets from samplers and LLMs, with validators | Declarative schema with validators | Review, freeze, training | +| **Omniverse Replicator / Cosmos** (NVIDIA licences) | Randomised USD scenes rendered with ground truth (boxes, segmentation, depth, point clouds) | Physically based rendering and sensor simulation | Openness, review, freeze | +| **BlenderProc** (GPL-3), **Kubric** (Apache-2.0) | Blender rendering pipelines with depth, segmentation, flow; Kubric adds PyBullet physics | 3D scenes with ground truth, video | Both could run as a Tuldok project's own command | +| **SDV** (BSL), **MOSTLY AI** (Apache-2.0 SDK) | Tabular generators with quality reports | Real-against-synthetic fidelity scores | Tuldok has no tabular generation | +| **Netron** (MIT) | Graph viewer for about 180 formats; opens `.pt` pickles with a JavaScript unpickler that runs no Python (`source/python.js`) | Architecture graph; safe reading of nearly every format | Distributions, kernels as tiles, change against parent or start, links to runs and benchmarks | +| **Model Explorer** (Apache-2.0) | GPU-drawn graphs, side-by-side graphs, per-node data overlays from JSON | Overlays and graph comparison | It loads `.pt2` with `torch.export.load`, trusting the file | +| **WeightWatcher** (Apache-2.0) | Per-layer spectral quality (alpha) without test data; base vs fine-tuned | Data-free layer quality | Ancestry, GUI; it loads `.bin` with `torch.load` and relies on torch's `weights_only` default | +| **TensorBoard** | Scalars, histograms over steps, graph, projector | Training-time views | Definitions, ancestry | +| **lm-eval, HELM, OpenCompass, Inspect, Promptfoo, MLPerf** | Language-model evaluation; MLPerf for systems | Task catalogues, standard errors, per-sample transcripts, sandboxes | Any non-language metric, the Pareto chart, ancestry | + +Tuldok never opens a pickle: `.pt` files are listed with the reason (spec-d2, decision 4). Netron's approach, a pickle reader that runs no code, is the one to copy if `.pt` files must be read. + +### 2.4 Physics AI and surrogates + +The field has four layers. Tuldok sits in a fourth that only closed enterprise products occupy, and they aim at a different buyer. + +1. **Libraries you fork:** + - **PhysicsNeMo** 2.2 (Apache-2.0; Hydra configs; FNO, MeshGraphNet, Transolver, DoMINO; multi-GPU and domain-parallel; CFD metrics including force coefficients and spectra). Its `benchmarks/` folder times library code, not models. + - **NeuralOperator** 2.0 (MIT; FNO, TFNO, UNO, SFNO, GINO and more). + - **DeepXDE** (LGPL-2.1; physics-informed networks). + - None has a project, a model tree, an accuracy-against-time view or a GUI. +2. **Benchmark datasets:** + - **PDEBench** (MIT, but `pdebench/models/metrics.py` carries an NEC non-commercial header: do not copy it). + - **The Well** (BSD-3; 15 TB across 16+ datasets; the best-specified HDF5 format; a ready true / predicted / |error| video per field). + - Both report accuracy only. +3. **Solvers that make data:** PhiFlow, JAX-Fluids, Warp and Newton, Genesis World 1.x, Taichi. Each could be a Tuldok project's own solver step. +4. **Commercial surrogate platforms, the real competitors:** + + | Platform | What it offers | Notes | + | --- | --- | --- | + | Ansys SimAI (now Synopsys) | Full 3D fields from 30–100 earlier simulations, with confidence for out-of-range designs | An automatic evaluation report; a Build panel in 2026 R1; a desktop Pro tier | + | Siemens Simcenter ROM, HEEDS AI and the former Altair physicsAI / romAI | Geometric learning on native meshes, flags for out-of-range designs | FMU export for real-time system simulation | + | PhysicsX | Data Factory, large geometry models, applications | Raised $300M in June 2026 [unverified] | + | Neural Concept | CAD-native design copilot | Raised $100M in December 2025 | + | Rescale AI Physics | Cloud HPC solvers with a dataset-creation agent, Auto Tune and confidence estimates | | + | Monolith (CoreWeave) | Engineering test data | | + | Luminary Cloud | Cloud CFD with a surrogate | | + + All are closed and priced by quote. + +**Nobody targets games.** The nearest things are FMU reduced-order models for real-time system simulation (Siemens, Altair), NVIDIA's Omniverse digital-twin blueprint (a live surrogate in a rendered scene, not a game export), and Taichi's AOT runtime. A benchmark subject that is the model *as deployed* (timed on ONNX Runtime or inside an engine) would be a feature nobody in the field has. + +**How kept fields compare** (phase 6): The Well's true / predicted / |error| rows and PhysicsNeMo's `pred_`/`true_` mesh fields are offline files for ParaView or a video. SimAI and Simcenter show predicted fields in 3D viewers (side-by-side error views [unverified]). Tuldok's Analysis tab shows native, predicted and *signed* error side by side, with whole-field figures, in the same place as the benchmark that scored the model. + +## 3. Feature matrix + +✓ yes · ~ partly or in a paid tier only · ✗ no · ? unverified. One column per family where the members agree; the area sections above have the detail. + +| Capability | Tuldok | Label Studio | CVAT | FiftyOne | MLflow | W&B | ClearML | DVC | ZenML | TensorBoard | Netron | PhysicsNeMo | The Well / PDEBench | SimAI / Simcenter / PhysicsX | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Fully open source | ✓ | ~ open core | ✓ | ~ open core | ✓ | ✗ | ~ SSPL server | ✓ | ~ | ✓ | ✓ | ✓ | ✓ | ✗ | +| Local-first, no account | ✓ | ✓ | ✓ | ✓ | ✓ | ~ personal | ~ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ~ desktop tier | +| Project = definitions in Git | ✓ | ✗ | ✗ | ✗ | ~ | ✗ | ✗ | ✓ | ~ | ✗ | – | ~ configs | ~ configs | ✗ | +| Weights kept out of Git | ✓ | – | – | – | ✓ | ✓ | ✓ | ✓ | ✓ | – | – | ✓ | ✓ | ✓ | +| Text / image / audio data | ✓ | ✓ | ~ no text | ~ no audio | – | ~ | ~ | – | – | ~ | – | ✗ | ✗ | ✗ | +| Point cloud / mesh / arrays | ✓ | ~ Ent LiDAR | ~ PCD only | ✓ | – | ✗ | ✗ | – | – | ✗ | – | ✓ (in code) | ✓ arrays | ✓ meshes | +| Video | ✗ | ✓ | ✓ | ✓ | – | ~ | ~ | – | – | ✗ | – | ✗ | ✗ | ? | +| Annotation, shapes beyond boxes | ✗ | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | +| Annotations as Git text | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ~ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | +| Model suggestions, human accepts | ✓ Pumas | ✓ ML backend | ✓ Nuclio, agent | ~ in-process | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | +| Frozen release with provenance | ✓ | ~ snapshots | ✗ | ~ Ent | ~ | ✓ Artifacts | ✓ Datasets | ✓ | ✓ | ✗ | ✗ | ✗ | ✓ fixed sets | ? | +| Curation by embeddings | ✗ | ✗ | ✗ | ✓ | ✗ | ~ | ~ | ✗ | ✗ | ~ projector | ✗ | ✗ | ✗ | ✗ | +| Standard export formats | ✗ JSON/JSONL | ✓ | ✓ ~30 | ✓ | – | – | – | – | – | – | – | ✓ HDF5/Zarr | ✓ HDF5 | ? | +| Data generation step | ✓ Pumas text/PNG; own command | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✓ stages | ✓ steps | ✗ | ✗ | ✗ | ✓ PDEBench scripts | ~ | +| Training regime as definition | ✓ recipes | ✗ | ✗ | ✗ | ~ MLproject | ~ | ~ | ✓ | ✓ | ✗ | ✗ | ✓ Hydra | ✓ Hydra | ~ automatic | +| Rebuild from definitions | ✓ | ✗ | ✗ | ✗ | ~ | ~ | ~ | ✓ | ~ | ✗ | ✗ | ~ | ~ | ✗ | +| Live training curves | ~ progress | ✗ | ✗ | ✗ | ✓ | ✓ | ✓ | ~ | ~ | ✓ | ✗ | ✓ TB | ✓ | ? | +| Hyperparameter search | ✗ | ✗ | ✗ | ✗ | ~ | ✓ | ✓ | ✗ | ~ | ✗ | ✗ | ~ | ✗ | ✓ automatic | +| Multi-GPU / cluster / cloud | ✗ | – | – | – | ✗ | ~ | ✓ | ✗ | ✓ | – | – | ✓ | ~ | ✓ | +| Model family tree | ✓ Map | ✗ | ✗ | ✗ | ✗ | ~ artifact DAG | ~ parents | ~ dag | ~ DAG | ✗ | ✗ | ✗ | ✗ | ~ Build panel | +| Benchmarks as definitions | ✓ | ✗ | ✗ | ~ | ✗ | ✗ | ✗ | ~ metrics | ✗ | ✗ | ✗ | ~ | ✓ | ✗ | +| Accuracy-vs-time Pareto chart | ✓ | ✗ | ✗ | ✗ | ✗ | ~ custom Vega | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | +| Parallel coordinates | ✗ | ✗ | ✗ | ✗ | ✓ | ✓ | ✓ | ~ | ✗ | ✓ | ✗ | ✗ | ✗ | ? | +| Charts declared as files | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | +| Per-case values | ✓ | – | – | ✓ | ~ | ~ | ~ | ✗ | ✗ | ✗ | ✗ | ✓ metrics.jsonl | ~ | ? | +| Native / predicted / error fields | ✓ Analysis | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ~ files | ~ video | ✓ 3D viewer | +| Confidence per prediction | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ~ UQ | ✗ | ✓ | +| Weights: layers, distributions | ✓ | ✗ | ✗ | ✗ | ✗ | ✓ histograms | ✗ | ✗ | ✗ | ✓ | ~ stats | ✗ | ✗ | ✗ | +| Weights: change vs parent / start | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | +| Architecture graph | ✗ | ✗ | ✗ | ✗ | ✗ | ~ | ✗ | ✗ | ✗ | ✓ | ✓ | ✗ | ✗ | ✗ | +| Pretrained models / zoo | ✗ | ✗ | ~ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | – | ✓ | ✓ | ✓ | +| Agents request, owner approves | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ~ ask step | ✗ | ✗ | ✗ | ✗ | ✗ | +| MCP server | ✓ with grants | ~ | ~ | ? | ✓ | ✓ | ~ community | ✗ | ✓ | ✗ | ✗ | ~ skill | ✗ | ~ SDK | +| Roles | ✓ owner/edit/inspect | ~ Ent | ✓ | ~ Ent | ✓ | ✓ | ~ paid | ~ Studio | ~ Pro | ✗ | ✗ | ✗ | ✗ | ✓ | +| Hosted option, large community | ✗ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Real-time / game deployment | ✗ (a stated goal) | – | – | – | ~ serving | ✗ | ~ | ✗ | ~ | – | – | ~ Omniverse twin | ✗ | ~ FMU ROMs | + +## 4. What to do with this + +### Defend (what nobody else has, and what serves both targets) + +1. The tradeoff chart and frontier. Add an MLPerf-style preset: "accuracy at least X, then fastest", and allow a benchmark subject to be the model *as deployed* (ONNX Runtime, a game engine) so the real-time target is measured where it runs. +2. The Map. Keep derivations, kinds of change and comparisons first-class; nobody else has them. +3. Definition-only Git folders with no hash lockfiles, and charts as files. +4. Owner approval of agent requests. MLflow, W&B and ZenML now have MCP servers, but none has grants or an approval queue. + +### Borrow (ideas and formats, not code, unless the licence allows) + +| Idea | From | Size | +| --- | --- | --- | +| Import The Well and PDEBench HDF5; PhysicsNeMo `metrics.jsonl` as per-case values and `pred_`/`true_` fields as kept fields | The Well, PDEBench, PhysicsNeMo | Small to medium | +| Spectral (Fourier-band) error, rollout errors over time, integrated quantities (forces) as benchmark metrics | PDEBench, The Well, PhysicsNeMo-CFD | Small | +| A confidence / out-of-range flag per prediction | SimAI, physicsAI, Rescale | Medium (needs the training code's help) | +| Parallel coordinates on Benchmarks | MLflow, W&B, TensorBoard | Small | +| Live training curves on Train from a run's progress | every tracker | Small | +| Weight distributions across checkpoints in training order | TensorBoard, W&B | Small (the lab keeps checkpoints) | +| An architecture graph from a recipe's model definition | Netron, Model Explorer | Medium | +| A per-layer spectral quality column | WeightWatcher (Apache-2.0) | Small | +| A pickle reader that runs no code, if `.pt` must be read | Netron (MIT) | Medium | +| Polygons, keypoints, masks; COCO / YOLO / KITTI export | Label Studio, CVAT | Medium each | +| Rank and rate annotation questions | Argilla, Label Studio | Small | +| Similarity and embedding views for curation | FiftyOne | Medium | +| A real-against-synthetic quality report for generated datasets | SDV, MOSTLY AI | Medium | +| Generation templates (Magpie, Evol-Instruct, judges) for `generate` | distilabel | Small | +| A read-only MCP mode | W&B | Small | + +### Call rather than rebuild (complements) + +PhysicsNeMo and NeuralOperator models as a recipe's training code; PhiFlow, Warp, Genesis or JAX-Fluids as a project's solver step; BlenderProc or Kubric as a scene generator command; Label Studio or CVAT as an external annotator for shapes Tuldok does not draw, with their exports imported. + +### Licence cautions + +- **Do not copy:** PDEBench's `pdebench/models/metrics.py` (NEC non-commercial header). +- **Copyleft:** DeepXDE is LGPL-2.1 and BlenderProc is GPL-3. +- **Source-available, not open source:** SDV is BSL, lakeFS is BSL from 2026-09-22, and the ClearML server is SSPL. +- **Fine with attribution:** PhysicsNeMo, NeuralOperator, The Well, Netron, WeightWatcher, Label Studio's open edition, CVAT, FiftyOne's open edition and MLflow are permissive. + +## 5. Not verified + +- **Commercial physics platforms:** most capability claims are marketing, especially whether they show error fields and whether they track lineage. +- **Prices and plans:** Labelbox, V7, Roboflow Core, Voxel51 Enterprise and the W&B tiers. +- **Capabilities:** Labelbox and V7 LiDAR support; whether FiftyOne has an MCP server; JAX-Fluids' licence; Taichi's current activity. +- **Recent events:** PhysicsX's 2026 round, the Anaconda–Outerbounds deal, and the date Warp's licence changed. From 4ff0ad4241c20f4fc5fd3769f3cb579a401eb50e Mon Sep 17 00:00:00 2001 From: MrScripty Date: Wed, 18 Nov 2026 23:05:03 -0700 Subject: [PATCH 081/131] feat(project): native, predicted and signed error of the fields a run kept, in Analysis Phase 6 of the data tools plan (spec-d6.md): field-index.json read as Tuldok's format; operations fields and field_compare; the Kept fields section with three panels, axis and position, Remove the mean, and the run's own reported figures beside Tuldok's. Co-Authored-By: Claude Opus 5.5 --- app.py | 1 + docs/contracts/project-folder.md | 83 ++- .../definition-first-projects/spec-d6.md | 167 ++++++ static/project-workspace.html | 1 + static/project-workspace/adapter.js | 4 + static/project-workspace/app.js | 11 +- static/project-workspace/base.css | 28 ++ static/project-workspace/fields.js | 267 ++++++++++ static/project-workspace/tabs.js | 23 +- tests/browser_project_workspace_fields.cjs | 373 ++++++++++++++ tests/project_fields_browser_fixture.py | 103 ++++ tests/test_tuldok_project_fields.py | 475 ++++++++++++++++++ tests/test_tuldok_project_service.py | 6 +- tuldok_project/inside_arrays.py | 32 ++ tuldok_project/inside_fields.py | 426 ++++++++++++++++ tuldok_project/inside_weights.py | 19 +- tuldok_project/operations.py | 14 +- tuldok_project/service.py | 24 +- 18 files changed, 2016 insertions(+), 41 deletions(-) create mode 100644 docs/plans/definition-first-projects/spec-d6.md create mode 100644 static/project-workspace/fields.js create mode 100644 tests/browser_project_workspace_fields.cjs create mode 100644 tests/project_fields_browser_fixture.py create mode 100644 tests/test_tuldok_project_fields.py create mode 100644 tuldok_project/inside_fields.py diff --git a/app.py b/app.py index 7c787753..9e1f64e2 100644 --- a/app.py +++ b/app.py @@ -807,6 +807,7 @@ def _get(self): '/project-workspace/tabs.js': ('project-workspace/tabs.js', 'text/javascript'), '/project-workspace/inside.js': ('project-workspace/inside.js', 'text/javascript'), '/project-workspace/weights.js': ('project-workspace/weights.js', 'text/javascript'), + '/project-workspace/fields.js': ('project-workspace/fields.js', 'text/javascript'), '/project-workspace/annotate.js': ('project-workspace/annotate.js', 'text/javascript'), '/project-workspace/generate.js': ('project-workspace/generate.js', 'text/javascript'), '/project-workspace/app.js': ('project-workspace/app.js', 'text/javascript'), diff --git a/docs/contracts/project-folder.md b/docs/contracts/project-folder.md index bcec05f7..e922414a 100644 --- a/docs/contracts/project-folder.md +++ b/docs/contracts/project-folder.md @@ -2283,6 +2283,8 @@ and result keys of each operation are in its contract. | `weights` | inspect | List the weights files of a finished run's product, each with its size, the file it started from and, when Tuldok reads it, its layers and parameter count. | | `weights_compare` | inspect | Compare, array by array, a weights file of a finished run's product with one of the same or another finished run: norms, relative change, cosine and largest change. | | `array_tiles` | inspect | Read tiles of two axes of an array in a finished run's product, one per position along a third axis, as 32-bit floats. | +| `fields` | inspect | List the fields a finished run's product kept: each case's native and predicted files, its name, shape and whether the two can be compared, and the figures the run reported itself. | +| `field_compare` | inspect | Read a slice of one kept case's native field, predicted field and signed error as 32-bit floats, with the figures of the error over the whole field. | | `set_definition` | edit | Check a definition's text and keep it as an unsaved edit. | | `remove_definition` | edit | Mark a definition that nothing uses as removed, until the project is saved. | | `revert_definition` | edit | Put back the file in the folder in place of a definition's unsaved edit or removal, or drop a definition the folder has no file for. | @@ -2392,7 +2394,7 @@ project stay command-line actions. A **product** is the `output` directory of a run in state `succeeded` or `adopted`, named by its run id (or an unambiguous prefix of it). The operations `records`, `record`, `inside`, `array_slice`, `array_summary`, -`array_tiles`, `weights` and `weights_compare` read it; each takes `run`, and a run that does not exist, has not finished or +`array_tiles`, `weights`, `weights_compare`, `fields` and `field_compare` read it; each takes `run`, and a run that does not exist, has not finished or has no output directory is refused `not-found`. Like every operation they open the project for a moment, to find the run and the view of its dataset; they read the product after closing it and write nothing: no file, no row. @@ -2640,6 +2642,85 @@ element by element in C order, whichever order each is stored in. At most tensors per file; beyond either the call is refused `too-large`, saying how many there are. +### The fields a run kept + +`fields` and `field_compare` read a product as the operations above do: the +same confinement, nothing written, a damaged file refused `unsupported`. +Nothing runs a model or a solver; only kept files are read. + +**A product keeps fields** when the top of its directory holds +`field-index.json`: + +```json +[{"run_id": "…", "cases": [{"member_ordinal": 0, + "predicted": {"name": "pressure-prediction.npy", "bytes": 32896, "sha256": "…"}, + "reference": {"name": "pressure-reference.npy", "bytes": 32896, "sha256": "…"}, + "mask": null, "time_units": "not_applicable"}]}] +``` + +- A list of entries, each an object with a list `cases`; anything else is a + damaged index, refused `unsupported` (an index over 4 MiB is refused + `too-large`). Each case names a `predicted` and a `reference` file by + `name`: a plain file name at the top of the same product (no `/`, `\`, `!` + or `..`), an `.npy`. +- Every other key of a case is optional and kept as given for display + (`details`). `sha256` is not checked. `bytes`, when given, is compared with + the file's size, and a mismatch is shown (`bytes_mismatch`), not refused. +- `mask`: null, or `{"name": …}` of a boolean or integer `.npy` of the same + shape; true or non-zero is inside. With a mask the figures are over the + inside only, and the outside is NaN in the slices. +- Both files are `.npy` of a number type (floats or integers, not booleans), + of the same shape, of one to four axes and at most 16,777,216 values each. + A case that is not so is listed with the reason, and `field_compare` + refuses it `unsupported` (`too-large` for one over the size). +- **Which case it is.** When the product holds `probe.json` of `format` + `probe_v1`, a case's `member_ordinal` is looked up among its `members` (by + each member's `ordinal`, else its position): the case is named by the + member's `frozen_reference.member_id`, and its split is + `frozen_reference.split`, else the member's `split`, else the probe's. + Otherwise a case is named by its position, `case N` (`entry E case N` past + the first entry), and has no split. +- **What the run reported.** Every JSON file at the top of the product (at + most 4 MiB) whose `format` ends `_diagnostic_v1` gives its top-level + numeric fields whose names end `relative_l2`, as `reported`. They are shown, + never used to compute anything. + +**`fields`** takes only `run` and answers `kept` (whether there is an index), +`cases` and `reported` (each `{file, field, value}`), and `more` (true when +more than 10,000 cases are held; the first 10,000 are listed). Each case has +`entry` and `case` (its positions), `name`, `split` (or null), `predicted`, +`reference` and `mask` (file names, or null), `shape` and `dtype` (null when +the files could not be read as far as that; `dtype` is "float32 / float64" +when the two differ), `comparable`, `details`, and `reason` when it is not +comparable and `bytes_mismatch` (the names) when a size differs. + +**`field_compare`** takes `entry`, `case`, `axis` (the axis cut across; by +default the last), `index` (one position per axis, as `array_slice` takes it; +those of the axes drawn are ignored; by default the middle) and `mean_free` +(false by default). A one-axis field is drawn as one row (`axes` `[0]`), a +two-axis field whole (`axes` `[0, 1]`); `axis` is then null. A field of three +or four axes is drawn through the last two axes other than `axis`, the +positions on the others given by `index`. Beyond 256 rows or columns the slice +is subsampled by one stride, as `array_slice` is. It answers `entry`, `case`, +`shape`, `dtype`, `axes`, `axis`, `index`, `rows`, `columns`, `stride`, +`mean_free`, `reference_f32`, `predicted_f32` and `error_f32` (base64 of +little-endian 32-bit floats, row by row; cells outside the mask NaN), `range` +(the lowest and highest finite value of the reference and the prediction in +the slice together, or null), `error_limit` (the largest absolute finite +error in the slice, or null) and `figures`. The error is predicted minus +reference; with `mean_free` each field's mean (over the inside) is taken from +it first, in the error only: the two fields are shown as they are. + +`figures` are over the whole field, not the slice: the cells inside the mask +whose two values are finite. `count` (those cells), `nonfinite` (non-finite +values inside, of either field, left out), `max_abs_error`, `mean_error`, +`rmse`, `relative_l2` (the error's norm over the reference's; null when that +is zero) and `mean_free_relative_l2` (the same with each field's mean removed +first; null when the reference is constant). They are computed in 64-bit +floats with `math.fsum` and `math.sumprod`; a figure that would overflow is +null, as all of them are when no cell counts. A case's figures are kept while +its files are unchanged, so asking for another slice reads only the slice. + ### Annotating The five operations on annotations (see [Annotations in the database](#annotations-in-the-database)) diff --git a/docs/plans/definition-first-projects/spec-d6.md b/docs/plans/definition-first-projects/spec-d6.md new file mode 100644 index 00000000..c47a46c7 --- /dev/null +++ b/docs/plans/definition-first-projects/spec-d6.md @@ -0,0 +1,167 @@ +# Implementation spec: native, predicted and signed error side by side + +This is phase 6, the last, of [the data tools plan](data-tools-plan.md). It builds on [spec-d1.md](spec-d1.md) (reading inside a product) and [spec-d2.md](spec-d2.md) (weights), and their rules apply: standard library only, nothing unpickled, nothing written, bounded reads, a damaged file refused and not a failure, reads outside the service lock. The page follows [spec-w4.md](spec-w4.md) and updates in place: nothing is rebuilt by a timer or a return to the window. + +**Owner, 2026-11-18:** "complete and test phase 6." + +**After this phase** the Analysis tab shows, for the chosen subject, the fields its run kept: the native (reference) field, the model's prediction and the signed error (predicted minus native), side by side as slices through the volume, with the error's figures over the whole field. Nothing runs a model or a solver; only kept files are read. + +## 1. What a run kept + +A product **keeps fields** when the top of its directory holds `field-index.json`. The earlier lab runs write it (83 of them, one case each); it is read as Tuldok's format from here on and written into `docs/contracts/project-folder.md`: + +```json +[{"run_id": "…", "cases": [{"member_ordinal": 0, + "predicted": {"name": "pressure-prediction.npy", "bytes": 32896, "sha256": "…"}, + "reference": {"name": "pressure-reference.npy", "bytes": 32896, "sha256": "…"}, + "mask": null, "time_units": "not_applicable"}]}] +``` + +- A list of entries; each has `cases`; each case names a `predicted` and a `reference` file by `name`, a plain file name at the top of the same product (no `/`, no `..`). Every other key is optional and kept as given for display (`member_ordinal`, `time_units`, `bytes`); `sha256` is not checked (no hash maps, as the owner ruled), but `bytes` is compared with the file and a mismatch is shown, not refused. +- `mask`: null, or `{"name": …}` of a boolean or integer `.npy` of the same shape; true or non-zero is inside. Where there is a mask, figures are over the inside only and the outside is drawn blank. +- Both files are `.npy` of a numeric type, the same shape, one to four dimensions, at most 16,777,216 values each (`too-large` beyond). Otherwise the case is listed with the reason it cannot be compared and refused `unsupported` when asked for. +- **Which case it is.** When the product holds `probe.json` of format `probe_v1`, a case's `member_ordinal` is looked up in its `members` and the member's `frozen_reference.member_id` and `split` are shown (for the lab: `baseline--water-validation-0000-frame-15`, validation). Otherwise the case is named by its position. +- **The run's own figure.** When the product holds a JSON file whose `format` ends in `_diagnostic_v1` and has numeric fields ending in `relative_l2`, they are listed as "the run reported" beside Tuldok's figures, by field name. They are never used to compute anything. + +## 2. Operations + +Two reads, `inspect`, in `INSIDE_READS` like the others, in the `project_folder` profile and absent from `catalog` (whose digest is unchanged). Both take `run`. + +| Operation | Arguments | Result | +| --- | --- | --- | +| `fields` | none besides `run` | `kept` (bool), `cases`: each with `entry`, `case` (positions), `name` (member id or "case N"), `split`, `predicted`, `reference`, `mask` (names), `shape`, `dtype`, `comparable`, `reason` (when not), `bytes_mismatch` (names, when any). `reported`: the run's own figures `{file, field, value}` | +| `field_compare` | `entry`, `case`, `axis` (default the last), `index` (positions on the other axes beyond the two drawn, default the middle), `mean_free` (bool, default false) | `shape`, `axes` (the two drawn), `axis`, `index`, `rows`, `columns`, `reference_f32`, `predicted_f32`, `error_f32` (base64, row by row; masked cells NaN), `range` (min and max over reference and predicted together, so both share one scale), `error_limit` (the largest absolute error of the slice, so the error scale is symmetric about zero), and `figures` over the whole field (not the slice): `count`, `nonfinite`, `max_abs_error`, `mean_error`, `rmse`, `relative_l2` (error norm over reference norm, null when that is zero), `mean_free_relative_l2` (the same with each field's mean removed first) | + +- **The slice.** A 1-D field is one row. A 2-D field is drawn whole. A 3-D or 4-D field is drawn through the two axes other than `axis` (for 4-D, also fixing `index` on the remaining one); the position on `axis` is in `index`. Larger than 256 by 256: subsampled by a stride, as `array_slice` does. +- **`mean_free`** removes each field's mean (over the inside) before the slice's error is formed; the figures always include both `relative_l2` and `mean_free_relative_l2`. (Pressure is defined only up to a constant: the lab scores the mean-free figure.) +- Arithmetic in 64-bit floats with `math.fsum` and `math.sumprod`; non-finite values are counted and left out of figures. +- Reuse `inside_arrays` (`read_header`, `decode`, `gather`, `float32_base64`, the slicing) rather than writing a second `.npy` reader. A new module `tuldok_project/inside_fields.py`. + +## 3. The page + +In the Analysis tab, a section **Kept fields** below "Per case", for the chosen subject, when the subject's model has a current product that keeps fields (the products of a recipe are read as `weights.js` reads them). The section is absent, not empty, when nothing is kept; when the subject's model has a product that keeps none, one line says so. + +- **Head:** the case (a select when there are several): its name, split and shape. The run it comes from, linked to Train. +- **Three panels side by side,** of equal size: Native, Predicted, Signed error (predicted − native). Native and Predicted share one sequential colour scale over `range`; the error uses a diverging scale symmetric about zero over `error_limit`. A colour bar under each with its ends in numbers. At narrow widths the panels stack. +- **Controls:** the axis cut across (x, y, z, named by position), a slider for the position on it (and for a 4-D field one more), and "Remove the mean". Moving the slider asks `field_compare` again, at most one request in flight, the last position wins; the panels are redrawn in place. +- **Hover** on any panel shows the cell's position and the three values in a tip. +- **Figures:** a small table of the whole-field figures, and beside it "the run reported" when there is one. +- Canvas 2D, no library, light and dark; reuse `inside.js`'s colour scales and canvas helpers where they fit. Opened state goes in the address like the rest of the tab (`anaCase`, `anaAxis`, `anaIndex`, `anaMeanFree`), so a reload restores it. + +## 4. Slices + +| | Slice | Files | +| --- | --- | --- | +| D6a | Format, the two operations, the contract text | `tuldok_project/inside_fields.py` (new), `inside.py` if a shared helper moves, `operations.py`, `service.py`, `docs/contracts/project-folder.md`, `tests/test_tuldok_project_fields.py` (new), and the tests that count the project-folder operations | +| D6b | The Kept fields section | `static/project-workspace/tabs.js` (the Analysis screen), a new `static/project-workspace/fields.js` if it keeps `tabs.js` smaller, `base.css`, `app.py` (the asset list), `tests/browser_project_workspace_fields.cjs` (new) | + +## 5. Tests + +**D6a, `tests/test_tuldok_project_fields.py`,** fixtures written by the test with the standard library (`.npy` by hand): + +- `fields` on a product with no index (`kept` false), with one entry of two cases, with a `probe.json` (names and split), with a `*_diagnostic_v1` file (reported figures), with a case whose files differ in shape, whose file is missing, whose name has a `/` or `..`, whose type is not numeric, whose `bytes` differ from the file: each listed with its reason, the rest still listed; a damaged index refused `unsupported`. +- `field_compare` against arithmetic the test does itself: identical fields (all zeros, `relative_l2` 0), a known constant offset (`relative_l2` > 0, `mean_free_relative_l2` 0), a mask (outside NaN, figures over the inside), a non-finite value (counted, left out), a zero reference (null), each axis of a 3-D field and each slice equal to the matching `array_slice` of both files, a 1-D, a 2-D and a 4-D field, subsampling past 256, the size bound (lowered for the test). +- The two are in `project_folder` and absent from `catalog`; the catalog digest is unchanged. + +**D6b, `tests/browser_project_workspace_fields.cjs`,** on a fixture with a benchmark whose subject's model has a product keeping a 3-D case (with `probe.json` and a diagnostic file) and another subject whose model keeps none: + +1. Analysis on the first subject shows Kept fields with the case name, three panels and the figures equal to the fixture's arithmetic; the second subject shows no such section (or the one line). +2. The panels' pixels: Native and Predicted differ where the fixture differs; the error panel is the middle colour where they agree. +3. The slider and the axis select change the slice (a different image) with one request each and no rebuild of the rest of the tab (a marker element on the page survives). +4. "Remove the mean" changes the error panel on the constant-offset fixture to the middle colour. +5. Hover shows the three values of the cell. +6. Reload restores the case, axis, position and mean option. Nothing is redrawn on a return to the window or a timer reading. +7. Light and dark, 1440 and 390 wide, no sideways overflow, no script error. + +**On the lab folder (acceptance, read only):** for one earlier model of the 150-pressure-fits benchmark, the case `baseline--water-validation-0000-frame-15` is shown; Tuldok's `mean_free_relative_l2` equals the run's reported `mean_free_same_request_pressure_relative_l2` to at least 6 significant figures (or the difference is explained). + +## 6. Out of scope + +Running a model or solver to make predictions; vector fields drawn as arrows; time series of fields; 3-D volume rendering; comparing two models' predictions with each other; any change to the lab's runs or files. + +## As built + +### D6a, the reader and the operations + +What differs from the text above, and what was found. + +- **`index` is one position per axis, as `array_slice` takes it**, not only the positions beyond the two drawn: the + answer's `axes` and `index` have the form of an `array_slice` answer, so a slice can be checked against one, and + the positions of the drawn axes are ignored. For a field of four axes the two drawn are the last two of the + axes other than `axis` (the remaining one is fixed by `index`), as `array_tiles` chooses the axes it draws. + `axis` is answered null for a field of one or two axes. +- **`range` and `error_limit` are of the slice** (the finite values inside the mask), as the text says for the + error's limit; both are null when the slice has no such value. The answer also carries `entry`, `case`, + `dtype`, `stride` and `mean_free`. `fields` also answers `more` (true past 10,000 cases) and gives each case + `details`: the case's other keys as the index gives them (`member_ordinal`, `time_units`, the lab's hashes). +- **What "damaged" means for the index:** not JSON, not UTF-8, not a list, or an entry that is not an object with a + list `cases` refuses both operations `unsupported`; an index over 4 MiB is `too-large`. A case that is not an + object or names no predicted or reference file is listed with that reason, the others still listed. +- **A plain file name** also may not hold `\`, `!` (which would address an archive member) or a NUL, and must end + `.npy`. Booleans are not "a numeric type" for the predicted and reference files (they are for a mask). A file + shorter than its shape says is listed with that reason, as is a mask of another shape or type. +- **A case's name and split from `probe.json`:** the member is found by its `ordinal` (by its position when it + has none); the split is `frozen_reference.split`, else the member's `split`, else the probe's. A case is + otherwise named `case N` by its position (0 first), `entry E case N` past the first entry. +- **"The run reported"** reads only the top-level numeric fields of each `*_diagnostic_v1` JSON file at the top + of the product (at most 4 MiB a file, 500 files); a file is parsed only when its bytes hold `_diagnostic_v1`. +- **Mean-free figures** take each field's mean over the inside cells whose two values are finite, and form + `(p − mean p) − (r − mean r)`; null when the reference is constant there. A figure that overflows is null. +- **Figures are kept** (16 cases, least recently used dropped) while the files' size, time and inode are unchanged, + so a slider moved reads only the slice; spec-d2's reordering of a Fortran-ordered array moved into + `inside_arrays` (`to_c_order`, `c_order_values`), used by `inside_weights` and `inside_fields` alike. +- **The acceptance on the lab folder** (read only, through `inside_fields` directly, no database), run + `7a700731ead945aebefdb7798536c30f` of project `0dcc3af1…`: `fields` lists one case, + `baseline--water-validation-0000-frame-15`, validation, 16 × 16 × 16 float64, comparable, and the run's + `mean_free_same_request_pressure_relative_l2` 0.0028656154967496624; `field_compare` answers + `mean_free_relative_l2` 0.00286561549674967, a difference of 7.4e-18 (relative 2.6e-15), so equal to 15 + significant figures (`relative_l2` 0.0027748834045040957, `rmse` 0.0711, 4,096 cells, no non-finite value). + `fields` took 0.003 s and `field_compare` 0.002 s. This is the one run named for the check; the other 82 runs + of the benchmark were not read. +- **Tests:** `tests/test_tuldok_project_fields.py`, 16; the two operations in `test_tuldok_project_service.py`'s + read test, and its count of the table's rows (59 to 61). Project suite 735 OK on a disposable PostgreSQL; agent + interface 43 OK (4 skipped). The catalog profile's digest is unchanged. Browser checks: + `browser_project_workspace_fields.cjs` 8 PASS (run twice), and unchanged `_weights` (7 PASS), `_inside` (8 PASS) + and `browser_project_workspace.cjs` (24 PASS). +- **Not verified:** a field near the bound of 16,777,216 values (its time and memory: the figures read both whole + fields into 64-bit arrays, about 270 MB, once per case); a big-endian machine; an index written by the lab with + a mask (none of the lab's runs has one). + +### D6b, the section + +What differs from section 3, and why. + +- **The address.** The Analysis tab's settings were not in the address before this phase (only the benchmark and + the compare set were). `app.js` now keeps `anaBench`, `anaSubject`, `anaMetric` and the four of this section in + the query, so that a reload restores the subject as well as the case; `act.keepUI` sets one without drawing the + tab again (the slider's moves). Choosing another benchmark or subject forgets the case, axis and position. +- **Where the reads live.** `tabs.js` reads the section's data with the rest of the tab (`LabFields.read`, so the + tab is put in place in one step) and builds it with the tab (`LabFields.section`); `fields.js` draws the + person's moves in place. `adapter.js` gained the two reads (`P.product.fields`, `fieldCompare`); it is not in + section 4's list. The section's case select names cases of every current product of the model that keeps + fields (with its subject when there are several). +- **The slider, the axis and "Remove the mean"** each ask `field_compare` at once (one request per change; a + change while one is in flight waits and only the latest is asked), and draw the three canvases again; the axis + also draws the controls again in place (its slider changes). Another case builds the section again and puts it + in place in the same element. The panels' aria-labels and the line under them say what is drawn. +- **The scales.** `inside.js`'s `ramp` is diverging whenever a range has both signs, so the panels use two scales + of their own on the same tokens: sequential `--ramp-lo` to `--ramp-hi` over `range` for Native and Predicted, and + diverging `--ramp-neg` / `--ramp-mid` / `--ramp-pos` over ±`error_limit` (all `--ramp-mid` when the limit is 0). + The canvas helpers (`fit`, `heat`, `contain`, `paints`, `token`, `floats`) are `inside.js`'s. +- **The figures and "the run reported"** are two small tables side by side (wrapping); a bytes mismatch is one + warning line under the head. The run is a link to `#train/run:`. +- **Axes are named x, y, z for a field of three**, `axis 0` … `axis 3` for four. +- **The check's fixture** (`tests/project_fields_browser_fixture.py`) makes the reference a multiple of 1/512 whose + mean is exactly zero, so that the constant-offset case's mean-free error is exactly zero: with rounding noise of + 1e-16 the diverging scale, scaled to the slice's largest error, would colour the noise fully. The page has no + tolerance for that; a real field whose error is pure rounding would be drawn at full colour, with `error_limit` + under the bar saying how small it is. +- **Files beyond section 4's list:** `static/project-workspace.html` (the ` + diff --git a/static/project-workspace/adapter.js b/static/project-workspace/adapter.js index a3e845b3..9f43a2f3 100644 --- a/static/project-workspace/adapter.js +++ b/static/project-workspace/adapter.js @@ -122,6 +122,10 @@ window.TuldokProject = (() => { weights: run => read('weights', { run }), compare: (run, path, otherRun, otherPath) => read('weights_compare', { run, path, other_run: otherRun, other_path: otherPath }), tiles: (run, { path, array, across, axes, index, first, most }, fresh = false) => (fresh ? call : read)('array_tiles', defined({ run, path, array, across, axes, index, first, most })), + // The fields a run kept (spec-d6.md, fields.js): its cases, and one slice of a case's native field, prediction + // and signed error with the error's figures (asked for each time the person moves through it unless kept). + fields: run => read('fields', { run }), + fieldCompare: (run, { entry, case: one, axis, index, mean_free }, fresh = false) => (fresh ? call : read)('field_compare', defined({ run, entry, case: one, axis, index, mean_free })), /** The address of an image's or a sound's bytes (GET /api/project/file), as the record operation gives it. */ fileUrl: (run, path) => '/api/project/file?run=' + encodeURIComponent(run) + '&path=' + encodeURIComponent(path) }; diff --git a/static/project-workspace/app.js b/static/project-workspace/app.js index 6be3d43b..7eae0a98 100644 --- a/static/project-workspace/app.js +++ b/static/project-workspace/app.js @@ -49,7 +49,9 @@ toggleKind: (k, all) => { if (!state.kinds) state.kinds = new Set([k]); else if (state.kinds.has(k)) { state.kinds.delete(k); if (!state.kinds.size) state.kinds = null; } else { state.kinds.add(k); if (state.kinds.size === all.length) state.kinds = null; } render(); }, toggleTrack: () => { state.track = !state.track; render(); }, // The other tabs: their own settings (state.ui), and the benchmark and compare set, which the address keeps (?benchmark=, ?cmp=). - setUI: (k, v) => { state.ui[k] = v; render(); }, + setUI: (k, v) => { state.ui[k] = v; if (ADDRESSED.includes(k)) address(); render(); }, + /** Keeps a setting of the tab that a view has already drawn in place (fields.js's slider): into the address, and nothing drawn again. */ + keepUI: (k, v) => { state.ui[k] = v; if (ADDRESSED.includes(k)) address(); }, setBenchmark: name => { state.benchmark = name; state.cmp = []; address(); render(); }, toggleCompare: id => { const i = state.cmp.indexOf(id); if (i >= 0) state.cmp.splice(i, 1); else if (state.cmp.length < 3) state.cmp.push(id); address(); render(); }, clearCompare: () => { state.cmp = []; address(); render(); }, @@ -60,11 +62,14 @@ /** Draws the drawer afresh. */ reopen: () => { $('aside')._for = null; render(); } }; - /** Writes the benchmark and compare set into the address without reloading, so the view can be shared. */ + // The settings of the Analysis tab the address keeps, so that a reload opens it where it was (spec-d6 section 3). + const ADDRESSED = ['anaBench', 'anaSubject', 'anaMetric', 'anaCase', 'anaAxis', 'anaIndex', 'anaMeanFree']; + /** Writes the benchmark, the compare set and the Analysis tab's settings into the address without reloading, so the view can be shared. */ function address() { const q = new URLSearchParams(location.search); if (state.benchmark) q.set('benchmark', state.benchmark); else q.delete('benchmark'); if (state.cmp.length) q.set('cmp', state.cmp.join(',')); else q.delete('cmp'); + for (const k of ADDRESSED) { const v = state.ui[k]; if (v === null || v === undefined || v === '' || v === false) q.delete(k); else q.set(k, String(v)); } const text = q.toString().replace(/%2C/g, ',').replace(/%2F/g, '/'); // references read as they are history.replaceState(null, '', location.pathname + (text ? '?' + text : '') + location.hash); } @@ -316,7 +321,7 @@ window.addEventListener('focus', () => { if (data.summary || failed) reread('focus'); }); // Who may use a control comes from the session: draw the controls again when it changes. window.addEventListener('tuldok-session', () => { if (failed) reread('focus'); else { $('aside')._for = null; if (data.map) act.redraw(); else { strip(); render(); } } }); - { const q = new URLSearchParams(location.search); state.benchmark = q.get('benchmark') || null; state.cmp = (q.get('cmp') || '').split(',').filter(Boolean).slice(0, 3); } + { const q = new URLSearchParams(location.search); state.benchmark = q.get('benchmark') || null; state.cmp = (q.get('cmp') || '').split(',').filter(Boolean).slice(0, 3); for (const k of ADDRESSED) if (q.get(k)) state.ui[k] = q.get(k); } // The tab bar, once (spec-w4 R5): render() sets which link is current. for (const [id, label] of TABS) { const a = document.createElement('a'); a.href = '#' + id; a.textContent = label; a.dataset.tab = id; $('tabs').appendChild(a); } parse(); strip(); render(); first(); diff --git a/static/project-workspace/base.css b/static/project-workspace/base.css index 3d136f2a..fec0260d 100644 --- a/static/project-workspace/base.css +++ b/static/project-workspace/base.css @@ -394,6 +394,34 @@ table.cmpt .d.better { color: var(--good); } table.cmpt .d.worse { color: var(-- .ana-none { margin-top: 8px; } .pager { display: flex; gap: 8px; align-items: center; font-size: 12.5px; color: var(--ink-2); margin: 10px 0; } table.cases-t { margin-top: 8px; } +/* Kept fields (fields.js, spec-d6 section 3): three panels of equal size side by side, stacked when narrow. */ +section.fld { margin-top: 26px; display: grid; gap: 10px; min-width: 0; } +section.fld .sect { margin-bottom: 0; flex-wrap: wrap; } +.fld-head { display: grid; gap: 4px; min-width: 0; } +.fld-head p { margin: 0; overflow-wrap: anywhere; } +.fld-pick select { max-width: min(520px, 100%); min-width: 0; } +.fld-pick { max-width: 100%; } +.fld-run { color: var(--accent); } +.fld-ctl .fld-at { min-width: 4.5em; } +.fld-view { display: grid; gap: 6px; min-width: 0; } +.fld-panels { position: relative; display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 14px; min-width: 0; } +.fld-panels[aria-busy="true"] { cursor: progress; } +.fld-panel { margin: 0; display: grid; gap: 4px; min-width: 0; align-content: start; } +.fld-title { font-size: 12.5px; font-weight: 600; color: var(--ink); } +canvas.fld-cv { display: block; width: 100%; background: var(--surface-2); border-radius: 3px; cursor: crosshair; } +canvas.fld-bar { display: block; width: 100%; height: 10px; border-radius: 2px; } +.fld-where { margin: 0; } +.fld-tip { position: absolute; z-index: 3; pointer-events: none; display: grid; gap: 2px; padding: 6px 8px; min-width: 150px; font-size: 12px; background: var(--surface); color: var(--ink); border: 1px solid var(--line-strong); border-radius: var(--radius); box-shadow: 0 2px 8px rgba(0, 0, 0, .14); } +.fld-tip[hidden] { display: none; } +.fld-tip-row { display: flex; justify-content: space-between; gap: 12px; font-variant-numeric: tabular-nums; } +.fld-tip-row span:first-child { color: var(--ink-2); } +.fld-figs { display: flex; flex-wrap: wrap; gap: 10px 28px; align-items: flex-start; min-width: 0; } +.fld-figs table.tv { width: auto; min-width: 0; font-size: 12.5px; } +.fld-figs table.tv caption { text-align: left; caption-side: top; padding-bottom: 4px; } +.fld-figs th { font-weight: 400; color: var(--ink-2); text-align: left; padding-right: 16px; } +.fld-figs th.mono { overflow-wrap: anywhere; max-width: 32ch; } +.fld-figs td.n { font-variant-numeric: tabular-nums; } +@media (max-width: 760px) { .fld-panels { grid-template-columns: minmax(0, 1fr); } } @media (max-width: 1100px) { .row.run { grid-template-columns: 90px minmax(0, 1fr) 70px 130px; } .row.run > .chip { display: none; } } /* ---- The shell: top bar, tabs, status strip, stage, drawer (b-map.html). ---- */ diff --git a/static/project-workspace/fields.js b/static/project-workspace/fields.js new file mode 100644 index 00000000..97089991 --- /dev/null +++ b/static/project-workspace/fields.js @@ -0,0 +1,267 @@ +'use strict'; +// The fields a run kept (docs/plans/definition-first-projects/spec-d6.md section 3): the section "Kept fields" of +// the Analysis tab, below "Per case", for the chosen subject. When the subject's model has a current product whose +// run kept fields (fields), the section shows one case (a select when there are several): its name, split and +// shape and the run it comes from; three panels side by side, Native, Predicted and Signed error (predicted − +// native), slices through the field read by field_compare; Native and Predicted on one sequential scale over the +// slice's range, the error on a diverging scale symmetric about zero; a colour bar under each with its ends; the +// axis cut across, a slider for the position on it (and one more for a fourth axis) and "Remove the mean"; a tip +// with the cell's position and its three values under the pointer; the error's figures over the whole field, and +// what the run reported beside them. The section is absent when the model has no product, one line when its +// products keep no fields. +// +// Updating in place (spec-w4): tabs.js reads what the section shows with the rest of the tab (read()) and builds +// it with the tab off the page (section()), so a reading that changed something draws it again in place, where the +// person left it (the case, axis, position and mean option are the tab's settings, kept in the address). The +// person's own moves are drawn here and nothing else of the tab: a slider, the axis or "Remove the mean" asks +// field_compare again (at most one request in flight, the last position wins) and the panels are drawn again in +// their canvases; another case builds the section again and puts it in place. A timer or a return to the window +// with nothing changed never reaches here. +window.LabFields = (() => { + const P = window.TuldokProject, S = window.LabScreens, C = window.LabCharts, h = C.h, R = P.product; + const { sect, putInPlace } = S.parts; + const D = window.LabInside.drawing; + const fmt = v => v == null ? '—' : C.fmtSci(v); + const num = n => n == null ? '—' : n.toLocaleString('en-GB'); + const shapeText = s => s && s.length ? s.join(' × ') : '—'; + const button = (cls, text, onClick) => { const b = h('button', cls, text); b.type = 'button'; if (onClick) b.addEventListener('click', onClick); return b; }; + const refusal = error => window.LabActions.refusal(error); + const PANEL_MOST = 420; // the CSS height of a panel at most + const axisNames = nd => nd === 3 ? ['x', 'y', 'z'] : Array.from({ length: nd }, (_, i) => 'axis ' + i); + + // ---- Colours: the tokens of base.css ------------------------------------------------------------------------------- + const mix = (a, b, t) => [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t, a[2] + (b[2] - a[2]) * t]; + /** Sequential from --ramp-lo to --ramp-hi over [min, max], whatever the signs. */ + function sequential(min, max) { const lo = D.token('--ramp-lo'), hi = D.token('--ramp-hi'), span = max - min || 1; return v => mix(lo, hi, Math.min(1, Math.max(0, (v - min) / span))); } + /** Diverging about zero over [−m, m]: --ramp-mid at zero, --ramp-neg and --ramp-pos at the ends. */ + function diverging(m) { const neg = D.token('--ramp-neg'), mid = D.token('--ramp-mid'), pos = D.token('--ramp-pos'), s = m || 1; return v => v < 0 ? mix(mid, neg, Math.min(1, -v / s)) : mix(mid, pos, Math.min(1, v / s)); } + + // ---- Reading -------------------------------------------------------------------------------------------------------- + const keyOf = (run, entry, one) => run + ':' + entry + ':' + one; + const intOr = (v, d) => { const n = Number(v); return v !== null && v !== undefined && v !== '' && Number.isInteger(n) && n >= 0 ? n : d; }; + /** The person's place in a case from the tab's settings (strings when they came from the address), checked against its shape. */ + function viewFor(c, ui) { + const nd = c.shape ? c.shape.length : 0, mid = (c.shape || []).map(n => Math.floor(n / 2)); + let axis = intOr(ui.anaAxis, nd - 1); if (axis >= nd) axis = nd - 1; + let index = typeof ui.anaIndex === 'string' ? ui.anaIndex.split(',').map(x => intOr(x, -1)) : Array.isArray(ui.anaIndex) ? ui.anaIndex.slice() : null; + if (!index || index.length !== nd || index.some((p, i) => p < 0 || p >= c.shape[i])) index = mid; + const meanFree = ui.anaMeanFree === true || ui.anaMeanFree === '1' || ui.anaMeanFree === 'true'; + return { axis, index, meanFree }; + } + const argsOf = (c, v) => ({ entry: c.entry, case: c.case, axis: c.shape.length >= 3 ? v.axis : null, index: v.index.slice(), mean_free: v.meanFree }); + + /** + * What the section shows for a subject's recipe, read in full: null when the model has no current product (the + * section is absent), { none } when none of its products keeps fields, else the cases, the one chosen, the + * person's place in it and its first slice. + */ + async function read(recipe, ui) { + if (!recipe) return null; + const products = (await P.read('products', { reference: recipe })).products.filter(p => p.run_id); + if (!products.length) return null; + const got = await Promise.all(products.map(p => R.fields(p.run_id).then(f => ({ p, f }), error => ({ p, error })))); + const kept = got.filter(g => g.f && g.f.kept); + if (!kept.length) { const failed = got.find(g => g.error); return { none: true, error: failed ? failed.error : null }; } + const several = kept.length > 1; + const cases = kept.flatMap(g => g.f.cases.map(c => Object.assign({}, c, { run: g.p.run_id, subject: g.p.subject || '', key: keyOf(g.p.run_id, c.entry, c.case), reported: g.f.reported, label: c.name + (several && g.p.subject ? ' · ' + g.p.subject : '') }))); + if (!cases.length) return { none: true, empty: true, run: kept[0].p.run_id }; + const chosen = cases.find(c => c.key === ui.anaCase) || cases.find(c => c.comparable) || cases[0]; + const out = { cases, chosen, view: null, cmp: null, error: null }; + if (chosen.comparable) { + out.view = viewFor(chosen, !ui.anaCase || chosen.key === ui.anaCase ? ui : {}); + try { out.cmp = await R.fieldCompare(chosen.run, argsOf(chosen, out.view)); } catch (error) { out.error = error; } + } + return out; + } + + // ---- The section ---------------------------------------------------------------------------------------------------- + /** The section for what read() gave (built off the page); null when it is absent. act: the tab's actions (keepUI). */ + function section(model, act) { + if (!model) return null; + const box = h('section', 'fld'); box.dataset.key = 'fld'; + fill(box, model, act); + return box; + } + function fill(box, model, act) { + box.appendChild(sect('Kept fields', model.none ? undefined : model.chosen.label)); + if (model.none) { + box.appendChild(h('p', 'empty fld-none', model.empty ? 'The run kept a field index that lists no case.' : model.error ? 'Whether this model\'s run kept fields could not be read: ' + (model.error.message || model.error) : 'The run of this model kept no fields: its product holds no field-index.json.')); + return; + } + const c = model.chosen, ctx = { box, model, c, act, v: model.view, cmp: model.cmp, busy: false, again: false }; + box.appendChild(head(ctx)); + if (!c.comparable) { box.appendChild(h('p', 'empty fld-reason', 'This case cannot be compared: ' + c.reason)); return; } + if (c.bytes_mismatch && c.bytes_mismatch.length) box.appendChild(h('p', 'small warnline fld-bytes', 'The index gives another size for ' + c.bytes_mismatch.join(' and ') + ' than the file has.')); + if (model.error) { box.appendChild(refusal(model.error)); return; } + ctx.ctl = h('div', 'iv-ctl fld-ctl'); controls(ctx); box.appendChild(ctx.ctl); + ctx.panels = panels(ctx); box.appendChild(ctx.panels); + ctx.figs = h('div', 'fld-figs'); figures(ctx); box.appendChild(ctx.figs); + } + /** The head: the case (a select when there are several), its split and shape, and the run, linked to Train. */ + function head(ctx) { + const { model, c, act } = ctx, hd = h('div', 'fld-head'); + if (model.cases.length > 1) { + const s = h('select'); s.setAttribute('aria-label', 'Case'); s.dataset.key = 'fld-case'; + for (const x of model.cases) { const o = h('option', null, x.label + (x.split ? ' · ' + x.split : '') + (x.comparable ? '' : ' (cannot be compared)')); o.value = x.key; o.selected = x === c; s.appendChild(o); } + s.addEventListener('change', () => chooseCase(ctx, s.value)); + const l = h('label', 'iv-field fld-pick'); l.appendChild(document.createTextNode('Case')); l.appendChild(s); hd.appendChild(l); + } else hd.appendChild(h('p', 'mono fld-name', c.name)); + const facts = [c.split ? 'split ' + c.split : null, c.shape ? shapeText(c.shape) : null, c.dtype, c.predicted + ' against ' + c.reference + (c.mask ? ', inside ' + c.mask : '')].filter(Boolean); + const line = h('p', 'small muted fld-facts', facts.join(' · ') + ' · from run '); + const run = h('a', 'mono fld-run', c.run.slice(0, 8)); run.href = '#train/' + encodeURIComponent('run:' + c.run); run.dataset.key = 'fld-run'; run.title = 'The run ' + c.run + ' on the Train tab'; + run.addEventListener('click', ev => { ev.preventDefault(); act.go('train', 'run:' + c.run); }); + line.appendChild(run); hd.appendChild(line); + return hd; + } + /** Another case: its first slice read, then the section built again and put in place. */ + async function chooseCase(ctx, key) { + const { model, act, box } = ctx, c = model.cases.find(x => x.key === key); if (!c) return; + act.keepUI('anaCase', key); act.keepUI('anaAxis', null); act.keepUI('anaIndex', null); + const next = { cases: model.cases, chosen: c, view: null, cmp: null, error: null }; + box.setAttribute('aria-busy', 'true'); + if (c.comparable) { next.view = viewFor(c, { anaMeanFree: ctx.v ? ctx.v.meanFree : false }); try { next.cmp = await R.fieldCompare(c.run, argsOf(c, next.view), true); } catch (error) { next.error = error; } } + if (!box.isConnected) return; + const fresh = h('div'); fill(fresh, next, act); + const frag = document.createDocumentFragment(); frag.append(...fresh.childNodes); + box.removeAttribute('aria-busy'); + putInPlace(box, frag, document.getElementById('main')); + } + + /** The axis cut across, the sliders of the axes not drawn and "Remove the mean"; drawn again when the axis changes. */ + function controls(ctx) { + const { c, v } = ctx, nd = c.shape.length, names = axisNames(nd), items = []; + if (nd >= 3) { + const s = h('select'); s.setAttribute('aria-label', 'The axis cut across'); s.dataset.key = 'fld-axis'; + for (let a = 0; a < nd; a++) { const o = h('option', null, names[a] + ' (' + c.shape[a] + ')'); o.value = String(a); o.selected = a === v.axis; s.appendChild(o); } + s.addEventListener('change', () => { v.axis = Number(s.value); ctx.act.keepUI('anaAxis', String(v.axis)); controls(ctx); ask(ctx); }); + const l = h('label', 'iv-field'); l.appendChild(document.createTextNode('Cut across')); l.appendChild(s); items.push(l); + for (const a of fixedAxes(nd, v.axis)) { + const l2 = h('label', 'iv-field iv-slider'); l2.appendChild(h('span', null, a === v.axis ? 'Position on ' + names[a] : names[a])); + const r = h('input'); r.type = 'range'; r.min = '0'; r.max = String(c.shape[a] - 1); r.value = String(v.index[a]); r.dataset.key = 'fld-slider-' + a; r.dataset.axis = String(a); + r.setAttribute('aria-label', 'Position on ' + names[a] + ', 0 to ' + (c.shape[a] - 1)); + const at = h('span', 'num small fld-at', v.index[a] + ' of ' + c.shape[a]); + r.addEventListener('input', () => { v.index[a] = Number(r.value); at.textContent = v.index[a] + ' of ' + c.shape[a]; ctx.act.keepUI('anaIndex', v.index.join(',')); ask(ctx); }); + l2.appendChild(r); l2.appendChild(at); items.push(l2); + } + } + const mean = button('btn sm fld-mean', 'Remove the mean', () => { v.meanFree = !v.meanFree; mean.setAttribute('aria-pressed', String(v.meanFree)); ctx.act.keepUI('anaMeanFree', v.meanFree ? '1' : null); ask(ctx); }); + mean.dataset.key = 'fld-mean'; mean.setAttribute('aria-pressed', String(v.meanFree)); mean.title = 'Take each field\'s mean from it before the error is formed (a pressure is defined only up to a constant)'; + items.push(mean); + if (ctx.ctl.isConnected) { const frag = document.createDocumentFragment(); frag.append(...items); putInPlace(ctx.ctl, frag, document.getElementById('main')); } + else ctx.ctl.replaceChildren(...items); + } + /** The axes not drawn of a field of nd axes cut across axis: axis first, then the other. */ + const fixedAxes = (nd, axis) => { const others = []; for (let a = 0; a < nd; a++) if (a !== axis) others.push(a); return [axis].concat(others.slice(0, -2)); }; + + /** Asks field_compare for the person's place: at most one request in flight; one asked meanwhile waits, the latest wins. */ + function ask(ctx) { + if (ctx.busy) { ctx.again = true; return; } + ctx.busy = true; ctx.again = false; ctx.panels.setAttribute('aria-busy', 'true'); + R.fieldCompare(ctx.c.run, argsOf(ctx.c, ctx.v), true).then(cmp => { + if (ctx.again || !ctx.panels.isConnected) return; + ctx.cmp = cmp; ctx.err.replaceChildren(); redraw(ctx); figures(ctx); + }, error => { if (!ctx.again) ctx.err.replaceChildren(refusal(error)); }).finally(() => { + ctx.busy = false; + if (ctx.again && ctx.panels.isConnected) ask(ctx); else ctx.panels.removeAttribute('aria-busy'); + }); + } + + // ---- The three panels ----------------------------------------------------------------------------------------------- + const PANELS = [['reference', 'Native', 'reference_f32'], ['predicted', 'Predicted', 'predicted_f32'], ['error', 'Signed error (predicted − native)', 'error_f32']]; + function panels(ctx) { + const wrap = h('div', 'fld-panels'); ctx.parts = {}; + for (const [id, title, field] of PANELS) { + const fig = h('figure', 'fld-panel'); fig.dataset.panel = id; + fig.appendChild(h('figcaption', 'fld-title', title)); + const cv = h('canvas', 'fld-cv'); cv.setAttribute('role', 'img'); cv.dataset.panel = id; fig.appendChild(cv); + const bar = h('canvas', 'fld-bar'); bar.setAttribute('aria-hidden', 'true'); fig.appendChild(bar); + const ends = h('div', 'iv-ends small faint fld-ends'); fig.appendChild(ends); + ctx.parts[id] = { cv, bar, ends, field }; + D.paints(cv, () => drawPanel(ctx, id)); D.paints(bar, () => drawBar(ctx, id)); + cv.addEventListener('mousemove', ev => hover(ctx, id, ev)); cv.addEventListener('mouseleave', () => { ctx.tip.hidden = true; }); + wrap.appendChild(fig); + } + ctx.tip = h('div', 'fld-tip'); ctx.tip.hidden = true; ctx.tip.setAttribute('role', 'status'); wrap.appendChild(ctx.tip); + ctx.say = h('p', 'small muted fld-where'); ctx.err = h('div', 'fld-err'); + const outer = h('div', 'fld-view'); outer.appendChild(wrap); outer.appendChild(ctx.say); outer.appendChild(ctx.err); + ctx.wrap = wrap; decode(ctx); label(ctx); + return outer; + } + /** The answer's three slices as floats, and the scales they are drawn on. */ + function decode(ctx) { + const a = ctx.cmp, range = a.range || [0, 0]; + ctx.values = { reference: D.floats(a.reference_f32), predicted: D.floats(a.predicted_f32), error: D.floats(a.error_f32) }; + ctx.scale = { reference: sequential(range[0], range[1]), predicted: sequential(range[0], range[1]), error: diverging(a.error_limit || 0) }; + } + function redraw(ctx) { + decode(ctx); label(ctx); + for (const id of Object.keys(ctx.parts)) { drawPanel(ctx, id); drawBar(ctx, id); } + ctx.wrap.dataset.index = JSON.stringify(ctx.cmp.index); ctx.wrap.dataset.axis = String(ctx.cmp.axis); ctx.wrap.dataset.meanFree = String(ctx.cmp.mean_free); + } + /** What the panels show, in words: their labels, the colour bars' ends and the line under them. */ + function label(ctx) { + const a = ctx.cmp, c = ctx.c, nd = c.shape.length, names = axisNames(nd), range = a.range; + const where = nd >= 3 ? 'through ' + a.axes.map(x => names[x]).join(' and ') + ' at ' + fixedAxes(nd, a.axis).map(x => names[x] + ' = ' + a.index[x]).join(', ') : nd === 2 ? 'the whole field' : 'the whole line'; + for (const [id, title] of PANELS) { + const p = ctx.parts[id]; + p.cv.setAttribute('aria-label', title + ', ' + a.rows + ' by ' + a.columns + ' cells ' + where + (id === 'error' ? ', ±' + fmt(a.error_limit) + ' about zero' + (a.mean_free ? ', each mean removed' : '') : range ? ', from ' + fmt(range[0]) + ' to ' + fmt(range[1]) : '')); + p.ends.replaceChildren(...(id === 'error' ? ['−' + fmt(a.error_limit), '0', '+' + fmt(a.error_limit)] : range ? [fmt(range[0]), fmt(range[1])] : ['—', '—']).map(t => h('span', null, t))); + } + ctx.say.textContent = 'A slice ' + where + (a.stride > 1 ? ', every ' + D.ordinal(a.stride) + ' row and column' : '') + '. Native and predicted share one scale' + (range ? ' from ' + fmt(range[0]) + ' to ' + fmt(range[1]) : '') + '; the error is coloured on ±' + fmt(a.error_limit) + ' about zero' + (a.mean_free ? ', with each field\'s mean removed first' : '') + (c.mask ? '; outside the mask is left blank' : '') + '.'; + } + function drawPanel(ctx, id) { + const p = ctx.parts[id], cv = p.cv, a = ctx.cmp, w = cv.clientWidth; if (!w) return; + const cssH = a.rows === 1 ? 28 : Math.max(32, Math.min(PANEL_MOST, Math.round(w * a.rows / a.columns))); + const size = D.fit(cv, cssH); if (!size) return; const g = cv.getContext('2d'); g.clearRect(0, 0, size[0], size[1]); + const rect = a.rows === 1 ? [0, 0, size[0], size[1]] : D.contain(a.rows, a.columns, size[0], size[1]); + p.rect = rect.map(x => x / (window.devicePixelRatio || 1)); + D.heat(g, ctx.values[id], a.rows, a.columns, ctx.scale[id], rect[0], rect[1], rect[2], rect[3]); + cv.dataset.drawn = String((cv._drawn = (cv._drawn || 0) + 1)); + } + function drawBar(ctx, id) { + const p = ctx.parts[id], size = D.fit(p.bar, 10); if (!size) return; + const a = ctx.cmp, n = 64, vals = new Float32Array(n), m = a.error_limit || 0, range = a.range || [0, 0]; + for (let i = 0; i < n; i++) { const t = (i + 0.5) / n; vals[i] = id === 'error' ? -m + 2 * m * t : range[0] + (range[1] - range[0]) * t; } + D.heat(p.bar.getContext('2d'), vals, 1, n, id === 'error' ? diverging(m) : ctx.scale[id], 0, 0, size[0], size[1]); + } + /** The tip under the pointer: the cell's position in the field and its three values. */ + function hover(ctx, id, ev) { + const p = ctx.parts[id], a = ctx.cmp; if (!p.rect) return; + const box = p.cv.getBoundingClientRect(), x = ev.clientX - box.left - p.rect[0], y = ev.clientY - box.top - p.rect[1]; + const col = Math.floor(x / p.rect[2] * a.columns), row = Math.floor(y / p.rect[3] * a.rows); + if (col < 0 || row < 0 || col >= a.columns || row >= a.rows) { ctx.tip.hidden = true; return; } + const i = row * a.columns + col, at = a.index.slice(), nd = ctx.c.shape.length; + if (nd === 1) at[0] = col * a.stride; else { at[a.axes[0]] = row * a.stride; at[a.axes[1]] = col * a.stride; } + const names = axisNames(nd), v = ctx.values; + const outside = !Number.isFinite(v.reference[i]) && !Number.isFinite(v.predicted[i]) && ctx.c.mask; + ctx.tip.replaceChildren(h('div', 'mono fld-tip-at', (nd === 3 ? at.map((q, k) => names[k] + ' ' + q).join(', ') : '(' + at.join(', ') + ')'))); + if (outside) ctx.tip.appendChild(h('div', null, 'outside the mask')); + else for (const [key, word] of [['reference', 'Native'], ['predicted', 'Predicted'], ['error', a.mean_free ? 'Error, means removed' : 'Error']]) { const r = h('div', 'fld-tip-row'); r.dataset.value = key; r.appendChild(h('span', null, word)); r.appendChild(h('span', 'num', fmt(v[key][i]))); ctx.tip.appendChild(r); } + ctx.tip.dataset.cell = JSON.stringify(at); + ctx.tip.hidden = false; + const wrap = ctx.wrap.getBoundingClientRect(), tw = ctx.tip.offsetWidth, th = ctx.tip.offsetHeight; + let left = ev.clientX - wrap.left + 14, top = ev.clientY - wrap.top + 14; + if (left + tw > wrap.width) left = Math.max(0, ev.clientX - wrap.left - tw - 14); + if (top + th > wrap.height + 40) top = Math.max(0, ev.clientY - wrap.top - th - 14); + ctx.tip.style.left = left + 'px'; ctx.tip.style.top = top + 'px'; + } + + // ---- The figures ---------------------------------------------------------------------------------------------------- + const FIGURES = [['count', 'Cells counted'], ['nonfinite', 'Values not finite'], ['max_abs_error', 'Largest |error|'], ['mean_error', 'Mean error'], ['rmse', 'RMSE'], ['relative_l2', 'Relative L2'], ['mean_free_relative_l2', 'Mean-free relative L2']]; + function figures(ctx) { + const f = ctx.cmp.figures, c = ctx.c, items = []; + const t = h('table', 'tv fld-figures'); t.appendChild(h('caption', 'small muted', 'Over the whole field' + (c.mask ? ', inside the mask' : '') + ', whatever the slice')); + const tb = h('tbody'); + for (const [key, word] of FIGURES) { const tr = h('tr'); tr.dataset.fig = key; tr.dataset.value = f[key] == null ? '' : String(f[key]); tr.appendChild(h('th', null, word)); tr.appendChild(h('td', 'n', key === 'count' || key === 'nonfinite' ? num(f[key]) : fmt(f[key]))); tb.appendChild(tr); } + t.appendChild(tb); items.push(t); + if (c.reported && c.reported.length) { + const r = h('table', 'tv fld-reported'); r.appendChild(h('caption', 'small muted', 'The run reported')); + const rb = h('tbody'); + for (const x of c.reported) { const tr = h('tr'); tr.dataset.value = String(x.value); const th = h('th', 'mono', x.field); th.title = 'In ' + x.file; tr.appendChild(th); tr.appendChild(h('td', 'n', fmt(x.value))); rb.appendChild(tr); } + r.appendChild(rb); items.push(r); + } + ctx.figs.replaceChildren(...items); + } + + return { read, section }; +})(); diff --git a/static/project-workspace/tabs.js b/static/project-workspace/tabs.js index 299ee90e..e3f1a07d 100644 --- a/static/project-workspace/tabs.js +++ b/static/project-workspace/tabs.js @@ -7,7 +7,8 @@ // reading that found something changed) keeps the scroll, inside tables too, // and the focus; a drawer read again for its subject stays on screen until // its new content replaces it whole (spec-w4.md). Data, Benchmarks and Analysis -// only read. Train draws the controls of spec-w3.md section 3.1 (actions.js): +// only read; Analysis shows, below the per-case values, the fields the subject's +// run kept (fields.js, spec-d6.md). Train draws the controls of spec-w3.md section 3.1 (actions.js): // Plan build, a build request's Approve, Decline and Cancel, a run's Cancel // run and Stop, an environment's Check again, Connect and Disconnect, and it // shows a running run live, and the machine's Pumas endpoint beside the environments (generate.js); @@ -716,20 +717,25 @@ const subject = view.byName.get(ui.anaSubject) || view.subjects.find(s => s.perCase) || view.subjects[0] || null; const metric = view.metrics.find(m => m.id === ui.anaMetric) || view.metrics[0] || null; const page = Math.max(0, ui.anaPage || 0); - const values = subject && metric ? await P.read('values', { benchmark: view.name, subject: subject.name, metric: metric.id, offset: page * PAGE, limit: PAGE }) : null; - return { list, b, view, subject, metric, page, values }; - }, (frag, { list, view, subject, metric, page, values }, width) => { + const [values, kept] = await Promise.all([subject && metric ? P.read('values', { benchmark: view.name, subject: subject.name, metric: metric.id, offset: page * PAGE, limit: PAGE }) : null, + // The fields the subject's run kept (spec-d6, fields.js): read with the rest, so the tab is put in place in one step. + subject && window.LabFields ? window.LabFields.read(subject.recipe, ui).catch(error => ({ none: true, error })) : null]); + return { list, b, view, subject, metric, page, values, kept }; + }, (frag, { list, view, subject, metric, page, values, kept }, width) => { if (!view) { frag.appendChild(h('p', 'empty', 'This project defines no benchmark.')); return; } const bar = h('div', 'viewer-bar'); - bar.appendChild(select('Benchmark', list.map(x => [x.benchmark, x.title + (x.subjects_with_values ? ' · ' + x.subjects_with_values + ' with per-case values' : '')]), view.name, v => { state.ui.anaSubject = null; state.ui.anaPage = 0; act.setUI('anaBench', v); }, 'ana-bench')); - if (view.subjects.length) bar.appendChild(select('Subject', view.subjects.map(s => [s.name, s.full + (s.perCase ? ' · per-case values' : '')]), subject.name, v => { state.ui.anaPage = 0; act.setUI('anaSubject', v); }, 'ana-subject')); + const fieldsLeft = () => { state.ui.anaCase = null; state.ui.anaAxis = null; state.ui.anaIndex = null; }; // a case belongs to its subject + bar.appendChild(select('Benchmark', list.map(x => [x.benchmark, x.title + (x.subjects_with_values ? ' · ' + x.subjects_with_values + ' with per-case values' : '')]), view.name, v => { state.ui.anaSubject = null; state.ui.anaPage = 0; fieldsLeft(); act.setUI('anaBench', v); }, 'ana-bench')); + if (view.subjects.length) bar.appendChild(select('Subject', view.subjects.map(s => [s.name, s.full + (s.perCase ? ' · per-case values' : '')]), subject.name, v => { state.ui.anaPage = 0; fieldsLeft(); act.setUI('anaSubject', v); }, 'ana-subject')); if (view.metrics.length) bar.appendChild(select('Metric', view.metrics.map(m => [m.id, m.title + units(m)]), metric.id, v => { state.ui.anaPage = 0; act.setUI('anaMetric', v); }, 'ana-metric')); frag.appendChild(bar); - if (!subject || !metric) { frag.appendChild(h('p', 'empty', 'This benchmark has no ' + (subject ? 'metric' : 'subject') + '.')); return; } + // Kept fields (fields.js), below Per case: absent when the subject's model has no product. + const fields = () => { const f = window.LabFields && window.LabFields.section(kept, act); if (f) frag.appendChild(f); }; + if (!subject || !metric) { frag.appendChild(h('p', 'empty', 'This benchmark has no ' + (subject ? 'metric' : 'subject') + '.')); if (subject) fields(); return; } if (!values.total) { frag.appendChild(sect('Per case', metric.title + units(metric) + ' · ' + subject.full)); const p = h('p', 'empty ana-none'); p.appendChild(document.createTextNode('This machine holds no per-case values of ' + subject.full + ' for ' + metric.title + ' on ' + view.title + '; its summaries are on the ')); - const a = h('a', null, 'Benchmarks tab'); a.href = '#benchmarks'; a.addEventListener('click', ev => { ev.preventDefault(); act.setBenchmark(view.name); act.go('benchmarks'); }); p.appendChild(a); p.appendChild(document.createTextNode('.')); frag.appendChild(p); return; + const a = h('a', null, 'Benchmarks tab'); a.href = '#benchmarks'; a.addEventListener('click', ev => { ev.preventDefault(); act.setBenchmark(view.name); act.go('benchmarks'); }); p.appendChild(a); p.appendChild(document.createTextNode('.')); frag.appendChild(p); fields(); return; } const rows = values.rows.map(r => ({ ...r, id: r.case + (r.group ? ' · ' + r.group : ''), label: r.case + (r.group ? ' · ' + r.group.replace(/;/g, ', ') : '') })); const pages = Math.ceil(values.total / PAGE), first = page * PAGE + 1, last = page * PAGE + rows.length; @@ -754,6 +760,7 @@ const t = h('table', 'tv cases-t'); t.appendChild(headRow([['Case'], ['Group'], [metric.title + units(metric), 'n'], ['Why no value']])); const tb = h('tbody'); for (const r of rows) { const tr = h('tr', 'rowbtn' + (r.id === sel ? ' is-sel' : '')); tr.addEventListener('click', () => act.select(r.id === sel ? null : r.id)); tr.appendChild(h('td', 'ck', r.case)); tr.appendChild(h('td', 'small faint', r.group || '')); tr.appendChild(h('td', 'n', r.value == null ? '—' : fmt(r.value))); tr.appendChild(h('td', 'small faint', r.reason || '')); tb.appendChild(tr); } t.appendChild(tb); sec.appendChild(wrapTable(t)); frag.appendChild(sec); + fields(); }); return closeDrawer(aside); } diff --git a/tests/browser_project_workspace_fields.cjs b/tests/browser_project_workspace_fields.cjs new file mode 100644 index 00000000..adda6824 --- /dev/null +++ b/tests/browser_project_workspace_fields.cjs @@ -0,0 +1,373 @@ +'use strict'; +// The fields a run kept, side by side, in the Analysis tab (docs/plans/definition-first-projects/spec-d6.md sections +// 3 and 5, slice D6b) in a headless browser, the owner signed in, no GPU. Tuldok runs with --project-folder on a copy +// of the minimal fixture, in a Git repository of its own, with three recipes of earlier work and a benchmark of +// earlier work whose subjects they are: recipes/fd-kept, whose adopted product keeps two cases of a 6 x 5 x 4 field +// (tests/project_fields_browser_fixture.py, with probe.json and a diagnostic file), recipes/fd-none, whose product +// keeps none, and recipes/fd-absent, with no product. The fixture prints the fields and their figures. +// 1. Analysis on fd-kept shows Kept fields with the case's name and split, three panels and the figures equal to +// the fixture's arithmetic, and what the run reported; fd-none shows one line; fd-absent no section. +// 2. The panels' pixels: Native and Predicted differ where the fixture differs; the error panel is the middle +// colour (--ramp-mid) where they agree. +// 3. Hover shows the cell's position and its three values. +// 4. The slider and the axis select change the slice (a different image) with one field_compare each, the +// canvases drawn again in place and the rest of the tab untouched (marked elements survive). +// 5. "Remove the mean" turns the error panel of the constant-offset case to the middle colour, one request. +// 6. A reload restores the case, axis, position and mean option; a return to the window and a timer reading +// touch nothing and ask nothing of the fields. +// 7. Light and dark at 1440 and 390 wide: no blank canvas, no sideways overflow, the panels side by side when +// wide and stacked when narrow; no script error and no failed request. +// node tests/browser_project_workspace_fields.cjs [--shots ] +const assert = require('node:assert/strict'), fs = require('node:fs'), os = require('node:os'), path = require('node:path'); +const { spawn, execFileSync } = require('node:child_process'), { once } = require('node:events'); +const { authenticatedFixture } = require('./auth_helpers.cjs'), { waitForDebugger } = require('./browser_startup.cjs'), { cdpSession } = require('./browser_cdp_session.cjs'), { qaDirectory } = require('./qa_artifacts.cjs'); + +const root = path.resolve(__dirname, '..'); +const argv = process.argv.slice(2), option = name => { const i = argv.indexOf(name); return i >= 0 ? argv[i + 1] : null; }; +assert.ok(process.env.TULDOK_DATABASE_URL, 'TULDOK_DATABASE_URL must name a disposable PostgreSQL cluster'); +const venv = path.join(root, '.venv', 'bin'); +if (fs.existsSync(path.join(venv, 'python'))) process.env.PATH = venv + path.delimiter + process.env.PATH; // auth_helpers runs python3 +const python = fs.existsSync(path.join(venv, 'python')) ? path.join(venv, 'python') : 'python3'; +const IDLE_MS = 15000; // the page's reading while nothing builds (app.js) +const WATCHED = ['summary', 'status', 'build_requests', 'environments', 'runs']; +const KEPT = 'recipes/fd-kept', NONE = 'recipes/fd-none', ABSENT = 'recipes/fd-absent', BENCH = 'kept-fields'; +const RECIPES = { + 'fd-kept': { title: 'Fields kept', labels: { short: 'FK', trained_at: '2026-10-01' }, change: 'architecture' }, + 'fd-none': { title: 'Fields not kept', labels: { short: 'FN', trained_at: '2026-10-03' }, change: 'refinement' }, + 'fd-absent': { title: 'Fields absent', labels: { short: 'FA', trained_at: '2026-10-05' }, change: 'component' } +}; + +const temporary = fs.mkdtempSync(path.join(os.tmpdir(), 'tuldok-fields-browser-')); +const report = qaDirectory(root, 'project-workspace-fields'); +const shots = option('--shots') ? path.resolve(option('--shots')) : null; if (shots) fs.mkdirSync(shots, { recursive: true }); +const children = [], checks = [], errors = [], failures = []; +let server, serverErrors = '', origin, auth, socket, session, send, evaluate, owned = null; +const pause = ms => new Promise(resolve => setTimeout(resolve, ms)); +async function until(fn, label, tries = 300) { for (let i = 0; i < tries; i++) { const value = await fn(); if (value) return value; await pause(100); } throw Error('Timed out: ' + label); } +function check(text) { checks.push(text); console.log('PASS ' + text); } +function launch(command, args, options) { const child = spawn(command, args, options); children.push(child); return child; } +async function stop(child) { if (!child || child.exitCode !== null || child.signalCode !== null) return; const exited = once(child, 'exit'); child.kill('SIGTERM'); await Promise.race([exited, pause(10000)]); if (child.exitCode === null && child.signalCode === null) { child.kill('SIGKILL'); await exited; } } +function findBrowser() { + const candidates = [process.env.BROWSER, '/usr/bin/chromium', '/usr/bin/chromium-browser', '/usr/bin/google-chrome']; + const cache = path.join(os.homedir(), '.cache', 'ms-playwright'); + if (fs.existsSync(cache)) for (const name of fs.readdirSync(cache).filter(n => n.startsWith('chromium_headless_shell-')).sort().reverse()) candidates.push(path.join(cache, name, 'chrome-headless-shell-linux64', 'chrome-headless-shell')); + const found = candidates.find(candidate => candidate && fs.existsSync(candidate)); + assert.ok(found, 'No headless browser: set BROWSER'); + return found; +} +/** Drops the project's schema and the catalog's from the disposable database, so each run imports afresh. */ +function dropOwned(folder, catalog) { + const id = JSON.parse(fs.readFileSync(path.join(folder, 'tuldok.json'), 'utf8')).id; + execFileSync(python, ['-c', `import json, os, pathlib, sys, psycopg +from psycopg import sql +from tuldok_project import store +store.drop_project(sys.argv[1], os.environ['TULDOK_DATABASE_URL']) +root = pathlib.Path(sys.argv[2]) +if root.exists(): + with psycopg.connect(os.environ['TULDOK_DATABASE_URL'], autocommit=True) as c: + for p in root.rglob('.tuldok.json'): + v = json.loads(p.read_text()) + name = 'projection_' + v['projection_id'] if v.get('version') == 2 else 'catalog_' + v['dataset_id'] + c.execute(sql.SQL('DROP SCHEMA IF EXISTS {} CASCADE').format(sql.Identifier(name))) +`, id, catalog], { cwd: root, stdio: ['ignore', 'pipe', 'pipe'] }); +} +async function contract(name) { + const capabilities = await (await auth.fetch(origin + '/api/agent/capabilities')).json(); + const operation = capabilities.operations.find(item => item.id === 'project.' + name), c = operation.contracts[operation.contracts.length - 1]; + return 'project.' + name + '/' + c.version + '/' + c.sha256; +} +/** An operation as the owner. */ +async function api(name, body = {}) { + const headers = { 'Content-Type': 'application/json', 'Tuldok-Operation-Contract': await contract(name) }; + const response = await auth.fetch(origin + '/api/project/' + name, { method: 'POST', headers, body: JSON.stringify(body) }); + const value = await response.json(); assert.equal(response.status, 200, name + ': ' + JSON.stringify(value)); return value; +} + +// ---- The page's requests, from the browser's network, with their bodies ------------------------------------------------ +const calls = new Map(), finished = []; +function network(event) { + const p = event.params; + if (event.method === 'Network.requestWillBeSent' && /\/api\/project\/[a-z_]+$/.test(p.request.url)) { let body = null; try { body = p.request.postData ? JSON.parse(p.request.postData) : null; } catch (_) { body = null; } calls.set(p.requestId, { name: p.request.url.split('/').pop(), body, sent: Date.now() }); } + if ((event.method === 'Network.loadingFinished' || event.method === 'Network.loadingFailed') && calls.has(p.requestId)) { finished.push(Object.assign(calls.get(p.requestId), { done: Date.now() })); calls.delete(p.requestId); } +} +const asked = (name, since = 0, test = () => true) => finished.concat([...calls.values()]).filter(f => f.name === name && f.sent >= since && test(f.body || {})); +async function reading(since, names, label, tries = 300) { + await until(() => names.every(name => finished.some(f => f.name === name && f.sent >= since)), 'a reading: ' + label, tries); + await until(() => !calls.size && Date.now() - Math.max(0, ...finished.map(f => f.done)) > 700, 'the reading done: ' + label, 300); + await settled(label); +} +/** Waits until nothing reads: no "Reading…", nothing busy in the main area, no request of the project in flight. */ +async function settled(label) { + await until(() => evaluate(`(() => { const m = document.getElementById('main'); return ![...m.querySelectorAll('.note')].some(n => n.textContent === 'Reading…') && !m.hasAttribute('aria-busy') && !m.querySelector('[aria-busy]'); })()`).then(ok => ok && !calls.size), 'settled: ' + label); + await pause(200); +} +const byKey = key => `[data-key=${JSON.stringify(key)}]`; +async function mouse(type, x, y, buttons = 0) { await send('Input.dispatchMouseEvent', { type, x, y, button: type === 'mouseMoved' ? (buttons ? 'left' : 'none') : 'left', buttons, clickCount: type === 'mouseMoved' ? 0 : 1 }); } +async function press(selector) { + const at = await until(() => evaluate(`(() => { const e = document.querySelector(${JSON.stringify(selector)}); if (!e) return null; e.scrollIntoView({ block: 'center', inline: 'nearest' }); const r = e.getBoundingClientRect(); return { x: r.left + r.width / 2, y: r.top + r.height / 2 }; })()`), 'shown: ' + selector, 100); + await pause(100); await mouse('mouseMoved', at.x, at.y); await mouse('mousePressed', at.x, at.y, 1); await mouse('mouseReleased', at.x, at.y); +} +/** Chooses an option of a select the way the keyboard changes it (the change event the page listens to). */ +async function choose(selector, value) { await evaluate(`(() => { const s = document.querySelector(${JSON.stringify(selector)}); s.focus(); s.value = ${JSON.stringify(value)}; s.dispatchEvent(new Event('change', { bubbles: true })); return true; })()`); } +/** Moves a slider to a value as a drag ends there (one input event). */ +async function slide(selector, value) { await evaluate(`(() => { const r = document.querySelector(${JSON.stringify(selector)}); r.focus(); r.value = ${JSON.stringify(String(value))}; r.dispatchEvent(new Event('input', { bubbles: true })); return true; })()`); } +async function frames() { await evaluate('new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve)))'); } +async function shot(name) { + await frames(); + const png = Buffer.from((await send('Page.captureScreenshot', { format: 'png', captureBeyondViewport: false })).data, 'base64'); + fs.writeFileSync(path.join(report, name + '.png'), png); if (shots) fs.writeFileSync(path.join(shots, name + '.png'), png); +} +const close = (a, b, label, tol = 1e-12) => assert.ok(Math.abs(a - b) <= tol * Math.max(1, Math.abs(b)), label + ': ' + a + ' is not ' + b); + +// What a panel shows: a sum over its pixels that changes when the drawing does, how many are drawn, and the colour at +// the centre of each cell of a rows x columns grid drawn square in it (as inside.js's contain() places it). +const PANEL = `(id, rows, cols) => { const c = document.querySelector('section.fld canvas.fld-cv[data-panel="' + id + '"]'); if (!c || !c.width) return null; + const g = c.getContext('2d'), d = g.getImageData(0, 0, c.width, c.height).data; let drawn = 0, sum = 0; for (let i = 0; i < d.length; i += 4) if (d[i + 3]) { drawn++; sum = (sum + (i / 4 + 1) * (d[i] * 3 + d[i + 1] * 5 + d[i + 2] * 7)) % 2147483647; } + const W = c.width, H = c.height, s = rows === 1 ? null : Math.min(W / cols, H / rows), x0 = s ? (W - cols * s) / 2 : 0, y0 = s ? (H - rows * s) / 2 : 0, sx = s || W / cols, sy = s || H; + const cells = []; for (let r = 0; r < rows; r++) { const row = []; for (let k = 0; k < cols; k++) { const p = g.getImageData(Math.floor(x0 + (k + 0.5) * sx), Math.floor(y0 + (r + 0.5) * sy), 1, 1).data; row.push([p[0], p[1], p[2], p[3]]); } cells.push(row); } + const box = c.getBoundingClientRect(); return { drawn, sum, cells, label: c.getAttribute('aria-label'), times: Number(c.dataset.drawn || 0), box: { left: box.left, top: box.top, width: box.width, height: box.height }, cell: { x0, y0, sx, sy, dpr: window.devicePixelRatio || 1 } }; }`; +const panel = (id, rows, cols) => evaluate(`(${PANEL})(${JSON.stringify(id)}, ${rows}, ${cols})`); +const MID = `(() => { const v = getComputedStyle(document.documentElement).getPropertyValue('--ramp-mid').trim(), n = parseInt(v.slice(1), 16); return [n >> 16, (n >> 8) & 255, n & 255, 255]; })()`; +const figuresShown = () => evaluate(`Object.fromEntries([...document.querySelectorAll('section.fld .fld-figures tr')].map(r => [r.dataset.fig, r.dataset.value === '' ? null : Number(r.dataset.value)]))`); +const stateShown = () => evaluate(`(() => { const f = document.querySelector('section.fld'); if (!f) return null; const s = q => f.querySelector(q); return { kase: s('[data-key="fld-case"]') ? s('[data-key="fld-case"]').value : null, caseText: s('[data-key="fld-case"]') ? s('[data-key="fld-case"]').selectedOptions[0].textContent : (s('.fld-name') || {}).textContent, facts: (s('.fld-facts') || {}).textContent, axis: s('[data-key="fld-axis"]') ? s('[data-key="fld-axis"]').value : null, sliders: [...f.querySelectorAll('input[type=range]')].map(r => [r.dataset.axis, r.value]), mean: s('[data-key="fld-mean"]') ? s('[data-key="fld-mean"]').getAttribute('aria-pressed') : null, panels: f.querySelectorAll('canvas.fld-cv').length, none: (s('.fld-none') || {}).textContent || null, reported: [...f.querySelectorAll('.fld-reported tr')].map(r => [r.querySelector('th').textContent, Number(r.dataset.value)]) }; })()`); +/** The value of the fixture's field at an index of its shape, in C order. */ +const at = (values, shape, i) => values[(i[0] * shape[1] + i[1]) * shape[2] + i[2]]; + +// The watcher of browser_project_workspace_still.cjs: added, removed and changed nodes, "Reading…", the scrolls. +const WATCHER = `window.__still = (() => { + const ids = ['tabs', 'strip', 'main', 'aside', 'needs-panel'], el = id => document.getElementById(id); + let counts = null, flash = 0, timer = null; + const name = n => !n ? '?' : n.nodeType === 1 ? n.tagName.toLowerCase() + (typeof n.className === 'string' && n.className ? '.' + n.className.trim().split(/\\s+/).join('.') : '') : '#text ' + JSON.stringify(String(n.data || '').slice(0, 30)); + for (const id of ids) new MutationObserver(list => { + if (!counts) return; + const c = counts[id]; + for (const r of list) { + if (r.type === 'childList') { c.added += r.addedNodes.length; c.removed += r.removedNodes.length; for (const n of [...r.addedNodes, ...r.removedNodes]) if (c.what.length < 6) c.what.push(name(n) + ' in ' + name(r.target)); } + else if (r.type === 'characterData') { const msg = el('strip').querySelector('.msg'); if (msg && r.target === msg.lastChild) c.readAt++; else { c.text++; if (c.what.length < 6) c.what.push('text of ' + name(r.target.parentNode)); } } + else { c.attrs++; if (c.what.length < 6) c.what.push('@' + r.attributeName + ' on ' + name(r.target)); } + } + }).observe(el(id), { childList: true, subtree: true, characterData: true, attributes: true }); + return { + start() { counts = {}; for (const id of ids) { counts[id] = { added: 0, removed: 0, attrs: 0, text: 0, readAt: 0, what: [] }; for (const e of el(id).querySelectorAll('*')) e.__seen = 1; } flash = 0; clearInterval(timer); timer = setInterval(() => { if (el('main').textContent.includes('Reading…')) flash++; }, 50); }, + stop() { clearInterval(timer); const fresh = {}; for (const id of ids) fresh[id] = [...el(id).querySelectorAll('*')].filter(e => !e.__seen).length; const r = { counts, flash, fresh, scroll: el('main').scrollTop }; counts = null; return r; } + }; +})(); true`; +const touched = (r, ids) => ids.filter(id => { const c = r.counts[id]; return c.added || c.removed || c.attrs || c.text || r.fresh[id]; }).map(id => id + ' ' + JSON.stringify(r.counts[id]) + ' new ' + r.fresh[id]); + +(async () => { + // ---- The fixture: minimal + three recipes and a benchmark of earlier work, in Git; two products adopted ---------------- + fs.cpSync(path.join(root, 'tests', 'fixtures', 'tuldok_project', 'minimal'), path.join(temporary, 'fixture'), { recursive: true }); + const folder = path.join(temporary, 'fixture', 'project'); + for (const [name, r] of Object.entries(RECIPES)) fs.writeFileSync(path.join(folder, 'recipes', name + '.json'), JSON.stringify({ format: 'tuldok_definition_v1', kind: 'recipe', title: r.title, description: 'A model for the browser check of kept fields.', labels: r.labels, + earlier_work: { rebuild: 'no', reason: 'Written by the browser check of kept fields; only its product remains.' }, model: 'models/stepper', group: 'steppers', change: r.change }, null, 2) + '\n'); + fs.writeFileSync(path.join(folder, 'benchmarks', BENCH + '.json'), JSON.stringify({ format: 'tuldok_definition_v1', kind: 'benchmark', title: 'Kept pressure fields', description: 'The pressure the models predicted, beside the native field.', + earlier_work: { rebuild: 'no', reason: 'Measured before this format.' }, metrics: [{ id: 'pressure_l2', title: 'Pressure relative L2', better: 'lower' }], + subjects: [{ name: 'fd-kept', title: 'Fields kept', recipe: KEPT }, { name: 'fd-none', title: 'Fields not kept', recipe: NONE }, { name: 'fd-absent', title: 'Fields absent', recipe: ABSENT }] }, null, 2) + '\n'); + const git = ['-c', 'user.name=Tuldok Test', '-c', 'user.email=test@example.invalid', '-c', 'commit.gpgsign=false', '-c', 'init.defaultBranch=main', '-C', path.join(temporary, 'fixture')]; + execFileSync('git', [...git, 'init', '-q']); execFileSync('git', [...git, 'add', '-A']); execFileSync('git', [...git, 'commit', '-q', '-m', 'The fixture.']); + const files = path.join(temporary, 'fields'); + const X = JSON.parse(execFileSync(python, [path.join(root, 'tests', 'project_fields_browser_fixture.py'), '--out', files]).toString()); + const home = path.join(temporary, 'home'), catalog = path.join(temporary, 'catalog'); fs.mkdirSync(home); + const env = { ...process.env, TULDOK_PROJECT_HOME: home, TULDOK_SETTINGS: path.join(temporary, 'settings.json') }; + owned = [folder, catalog]; dropOwned(folder, catalog); + const cli = (...args) => execFileSync(python, ['-m', 'tuldok_project', ...args], { cwd: root, env, stdio: ['ignore', 'pipe', 'pipe'] }).toString(); + const manifest = path.join(temporary, 'adopt.json'), keptFiles = fs.readdirSync(path.join(files, 'kept')); + fs.writeFileSync(manifest, JSON.stringify({ format: 'tuldok_adoption_v1', products: [ + { reference: KEPT, files: Object.fromEntries(keptFiles.map(n => [n, path.join(files, 'kept', n)])) }, + { reference: NONE, files: { 'notes.txt': path.join(files, 'none', 'notes.txt') } } + ] })); + cli('adopt', folder, manifest, '--copy'); + let output = ''; + server = launch(python, ['-u', 'app.py', '--port', '0', '--data', catalog, '--project-folder', folder], { cwd: root, env, stdio: ['ignore', 'pipe', 'pipe'] }); + server.stdout.on('data', chunk => { output += chunk; }); server.stderr.on('data', chunk => { serverErrors += chunk; }); + const port = await until(() => { if (server.exitCode !== null) throw Error('Tuldok exited: ' + serverErrors); return output.match(/127\.0\.0\.1:(\d+)/)?.[1]; }, 'Tuldok start-up', 3000); + origin = 'http://127.0.0.1:' + port; + auth = authenticatedFixture(); await auth.register(origin, catalog, root); + const products = (await api('products')).products, keptRun = products.find(p => p.reference === KEPT).run_id; + const listed = await api('fields', { run: keptRun }); + assert.equal(listed.cases.length, 2); + + const browser = launch(findBrowser(), ['--headless', '--no-sandbox', '--disable-gpu', '--no-first-run', '--hide-scrollbars', '--remote-debugging-port=0', '--window-size=1440,900', '--user-data-dir=' + path.join(temporary, 'browser'), 'about:blank'], { stdio: 'ignore', env: { ...process.env, XDG_CONFIG_HOME: temporary, XDG_CACHE_HOME: temporary } }); + const debugPort = await waitForDebugger(browser, path.join(temporary, 'browser', 'DevToolsActivePort')); + const target = (await (await fetch('http://127.0.0.1:' + debugPort + '/json')).json()).find(item => item.type === 'page'); + socket = new WebSocket(target.webSocketDebuggerUrl); await once(socket, 'open'); + session = cdpSession(socket, { timeoutMs: 60000, onEvent: event => { + network(event); + if (event.method === 'Runtime.exceptionThrown') errors.push(event.params.exceptionDetails.exception?.description || event.params.exceptionDetails.text); + if (event.method === 'Runtime.consoleAPICalled' && event.params.type === 'error') errors.push(event.params.args.map(a => a.value ?? a.description).join(' ')); + if (event.method === 'Log.entryAdded' && event.params.entry.level === 'error') errors.push(event.params.entry.text + ' ' + (event.params.entry.url || '')); + if (event.method === 'Network.loadingFailed' && !event.params.canceled) failures.push({ id: event.params.requestId, error: event.params.errorText }); + if (event.method === 'Network.responseReceived' && event.params.response.status >= 400) failures.push({ url: event.params.response.url, status: event.params.response.status }); + } }); + send = session.send; + evaluate = async expression => { const result = await send('Runtime.evaluate', { expression, awaitPromise: true, returnByValue: true }); if (result.exceptionDetails) throw Error(JSON.stringify(result.exceptionDetails)); return result.result.value; }; + await send('Page.enable'); await send('Runtime.enable'); await send('Network.enable'); await send('Log.enable'); + const size = async (width, height) => send('Emulation.setDeviceMetricsOverride', { width, height, deviceScaleFactor: 1, mobile: width < 600 }); + const theme = async name => { await send('Emulation.setEmulatedMedia', { features: [{ name: 'prefers-color-scheme', value: name }, { name: 'prefers-reduced-motion', value: 'reduce' }] }); }; + await auth.browser(send, origin); // the owner's session + /** Loads the Analysis tab in a theme with the address's settings (a page of its own, not a change of hash). */ + const load = async (name, query) => { + await theme(name); + await send('Page.navigate', { url: 'about:blank' }); await pause(100); + await send('Page.navigate', { url: origin + '/?theme=' + name + (query ? '&' + query : '') + '#analysis' }); + await until(() => evaluate(`document.readyState === 'complete' && !!document.getElementById('needs-btn') && !document.getElementById('needs-btn').disabled`), 'the project read', 1200); + await until(() => evaluate(`!!document.querySelector('[data-key="ana-subject"]')`), 'the Analysis tab'); + await settled('opened ' + query); + }; + const drawnPanels = () => until(() => evaluate(`(() => { const c = [...document.querySelectorAll('section.fld canvas.fld-cv')]; return c.length === 3 && c.every(x => Number(x.dataset.drawn) > 0); })()`), 'the three panels drawn'); + const search = () => evaluate('location.search'); + const shape = X.shape, rows0 = shape[0], cols0 = shape[1]; + const same = (a, b) => a.every((v, i) => v === b[i]); + + // ---- 1. Kept fields on fd-kept, one line on fd-none, nothing on fd-absent ------------------------------------------------ + await size(1440, 900); await load('light', 'anaBench=' + BENCH + '&anaSubject=fd-kept'); + await until(() => evaluate(`!!document.querySelector('section.fld')`), 'Kept fields'); await drawnPanels(); await settled('Kept fields'); + const s1 = await stateShown(), c0 = X.cases[0]; + assert.equal(s1.panels, 3, 'Three panels'); + assert.ok(s1.caseText.startsWith(c0.name + ' · ' + c0.split), 'The case is named from the probe with its split: ' + s1.caseText); + assert.match(s1.facts, /6 × 5 × 4/); assert.match(s1.facts, /split validation/); assert.match(s1.facts, new RegExp('from run ' + keptRun.slice(0, 8))); + const f1 = await figuresShown(); + for (const [k, v] of Object.entries(c0.figures)) { if (v === null) assert.equal(f1[k], null, k); else close(f1[k], v, 'figure ' + k); } + assert.deepEqual(s1.reported, [['mean_free_same_request_pressure_relative_l2', X.reported]], 'What the run reported'); + assert.equal(await evaluate(`[...document.querySelectorAll('#main section')].map(s => s.className).join(' ')`).then(t => t.endsWith('fld')), true, 'Kept fields comes after the rest'); + const runHref = await evaluate(`document.querySelector('section.fld .fld-run').getAttribute('href')`); + assert.equal(runHref, '#train/' + encodeURIComponent('run:' + keptRun), 'The run is linked to Train'); + await shot('light-1440-1-kept-fields'); + await choose(byKey('ana-subject'), 'fd-none'); await settled('fd-none'); + const sNone = await until(() => stateShown(), 'the one line'); + assert.ok(sNone.none && /kept no fields/.test(sNone.none), 'fd-none says its run kept no fields: ' + JSON.stringify(sNone)); assert.equal(sNone.panels, 0); + await choose(byKey('ana-subject'), 'fd-absent'); await settled('fd-absent'); + assert.equal(await evaluate(`document.querySelector('section.fld')`), null, 'fd-absent has no section'); + check('1. fd-kept: "' + s1.caseText + '", "' + s1.facts + '", three panels, figures as the fixture computes (relative L2 ' + f1.relative_l2 + ', mean-free ' + f1.mean_free_relative_l2 + ') and the run\'s own ' + X.reported + '; fd-none: "' + sNone.none + '"; fd-absent: no section'); + + // ---- 2. The pixels: where native and predicted differ, and the middle colour where they agree --------------------------------- + await choose(byKey('ana-subject'), 'fd-kept'); await settled('fd-kept again'); await drawnPanels(); + const mid = await evaluate(MID); + const [pn, pp, pe] = [await panel('reference', rows0, cols0), await panel('predicted', rows0, cols0), await panel('error', rows0, cols0)]; + let agreeing = 0, differing = 0; + for (let r = 0; r < rows0; r++) for (let c = 0; c < cols0; c++) { + const i = [r, c, 2], differs = at(c0.predicted, shape, i) !== at(c0.reference, shape, i); + if (differs) { differing++; assert.ok(!same(pn.cells[r][c], pp.cells[r][c]), 'Native and Predicted differ at ' + i); assert.ok(!same(pe.cells[r][c], mid), 'The error is coloured at ' + i); } + else { agreeing++; assert.deepEqual(pn.cells[r][c], pp.cells[r][c], 'Native and Predicted agree at ' + i); assert.deepEqual(pe.cells[r][c], mid, 'The error is the middle colour at ' + i); } + } + assert.ok(agreeing > 0 && differing > 0); + assert.ok(pn.drawn > 1000 && pe.drawn > 1000, 'The panels are drawn'); + check('2. At z = 2: ' + differing + ' cells where the fixture differs are different in Native and Predicted and coloured in the error; ' + agreeing + ' where it agrees are the same colour and the error there is --ramp-mid ' + JSON.stringify(mid.slice(0, 3))); + + // ---- 3. Hover: the cell's position and its three values ------------------------------------------------------------------- + const hr = 4, hc = 3, hi = [hr, hc, 2]; + const px = pn.box.left + (pn.cell.x0 + (hc + 0.5) * pn.cell.sx) / pn.cell.dpr, py = pn.box.top + (pn.cell.y0 + (hr + 0.5) * pn.cell.sy) / pn.cell.dpr; + await mouse('mouseMoved', px, py); await pause(150); + const tip = await evaluate(`(() => { const t = document.querySelector('section.fld .fld-tip'); return { hidden: t.hidden, cell: t.dataset.cell, rows: [...t.querySelectorAll('.fld-tip-row')].map(r => [r.dataset.value, r.lastChild.textContent]), at: t.querySelector('.fld-tip-at').textContent }; })()`); + assert.equal(tip.hidden, false, 'The tip shows'); + assert.equal(tip.cell, JSON.stringify(hi), 'The tip is of the cell under the pointer'); assert.equal(tip.at, 'x 4, y 3, z 2'); + const fmtF = v => evaluate(`window.LabCharts.fmtSci(Math.fround(${v}))`); + const want = [['reference', await fmtF(at(c0.reference, shape, hi))], ['predicted', await fmtF(at(c0.predicted, shape, hi))], ['error', await fmtF(Math.fround(at(c0.predicted, shape, hi) - at(c0.reference, shape, hi)))]]; + assert.deepEqual(tip.rows, want, 'The three values of the cell'); + await mouse('mouseMoved', 5, 5); await pause(100); + assert.equal(await evaluate(`document.querySelector('section.fld .fld-tip').hidden`), true, 'The tip goes when the pointer leaves'); + check('3. Hover on Native at ' + tip.at + ': ' + tip.rows.map(r => r.join(' ')).join(', ') + ', the fixture\'s values'); + + // ---- 4. The slider and the axis select: one request each, a different image, drawn in place ------------------------------------ + await evaluate(`(() => { document.querySelector('[data-key="ana-bench"]').__mark = 1; document.querySelector('section.fld').__mark = 2; document.querySelector('section.fld canvas.fld-cv[data-panel="error"]').__mark = 3; document.querySelector('section.fld .fld-figures').__mark = 4; return true; })()`); + const marks = () => evaluate(`[document.querySelector('[data-key="ana-bench"]').__mark, document.querySelector('section.fld').__mark, document.querySelector('section.fld canvas.fld-cv[data-panel="error"]').__mark, document.querySelector('#main .cases-t, #main .ana-none') ? 1 : 0]`); + const since4 = Date.now(), before4 = await panel('reference', rows0, cols0); + await slide(byKey('fld-slider-2'), 0); await until(() => asked('field_compare', since4).length >= 1 && !calls.size, 'the slider\'s request'); await settled('slider'); + const after4 = await panel('reference', rows0, cols0); + assert.equal(asked('field_compare', since4).length, 1, 'One field_compare for the slider'); + assert.deepEqual(asked('field_compare', since4)[0].body.index, [3, 2, 0]); + assert.notEqual(after4.sum, before4.sum, 'The slider changes the slice'); assert.ok(after4.times > before4.times, 'The canvas is drawn again in place'); + assert.deepEqual(await marks(), [1, 2, 3, 1], 'The rest of the tab and the section are the same elements'); + const since4b = Date.now(); + await choose(byKey('fld-axis'), '0'); await until(() => asked('field_compare', since4b).length >= 1 && !calls.size, 'the axis\'s request'); await settled('axis'); + const axis4 = await panel('reference', 5, 4); + assert.equal(asked('field_compare', since4b).length, 1, 'One field_compare for the axis'); assert.equal(asked('field_compare', since4b)[0].body.axis, 0); + assert.notEqual(axis4.sum, after4.sum, 'The axis changes the slice'); assert.match(axis4.label, /5 by 4 cells through y and z at x = 3/); + assert.deepEqual(await marks(), [1, 2, 3, 1], 'Still the same elements'); + assert.equal(await evaluate(`document.activeElement.dataset.key`), 'fld-axis', 'The axis select keeps the focus'); + const f4 = await figuresShown(); for (const [k, v] of Object.entries(c0.figures)) if (v !== null) close(f4[k], v, 'figure ' + k + ' after the axis'); + check('4. The slider (z to 0) and the axis (to x): one field_compare each, the images different (' + before4.sum + ' → ' + after4.sum + ' → ' + axis4.sum + '), the canvases drawn again in place, the tab and the section the same elements, the figures unchanged'); + + // ---- 5. "Remove the mean" on the constant-offset case ----------------------------------------------------------------------- + const kase1 = keptRun + ':0:1', since5 = Date.now(); + await choose(byKey('fld-case'), kase1); await settled('case 1'); await drawnPanels(); + assert.equal(asked('field_compare', since5).length, 1, 'One field_compare for the case'); + assert.deepEqual(await marks().then(m => [m[0], m[1]]), [1, 2], 'Another case is drawn in the same section'); + const s5 = await stateShown(); assert.ok(s5.caseText.startsWith('scene-b-frame-9 · test'), s5.caseText); assert.equal(s5.axis, '2', 'Another case starts on its last axis'); + const off = await panel('error', rows0, cols0); + assert.ok(off.cells.flat().every(c => !same(c, mid)), 'The offset is coloured everywhere'); + await choose(byKey('fld-axis'), '1'); await settled('case 1 axis y'); + await slide(byKey('fld-slider-1'), 3); await settled('case 1 y = 3'); + const sinceMean = Date.now(); + await press(byKey('fld-mean')); await until(() => asked('field_compare', sinceMean).length >= 1 && !calls.size, 'the mean\'s request'); await settled('mean removed'); + assert.equal(asked('field_compare', sinceMean).length, 1, 'One field_compare for the mean'); assert.equal(asked('field_compare', sinceMean)[0].body.mean_free, true); + const free = await panel('error', 6, 4); + assert.ok(free.cells.flat().every(c => same(c, mid)), 'Without the mean the offset\'s error is the middle colour: ' + JSON.stringify(free.cells[0])); + assert.equal(await evaluate(`document.querySelector('[data-key="fld-mean"]').getAttribute('aria-pressed')`), 'true'); + const f5 = await figuresShown(); close(f5.mean_free_relative_l2, 0, 'mean-free relative L2 of the offset'); close(f5.relative_l2, X.cases[1].figures.relative_l2, 'its relative L2'); + await shot('light-1440-5-mean-removed'); + check('5. The offset case: its error coloured everywhere, then "Remove the mean" (one field_compare) draws it in the middle colour; mean-free relative L2 ' + f5.mean_free_relative_l2 + ', relative L2 ' + f5.relative_l2); + + // ---- 6. A reload restores the place; a return to the window and a timer reading touch nothing -------------------------------------- + const query = (await search()).replace(/^\?/, '').split('&').filter(p => !p.startsWith('theme=')).join('&'); + const params = new URLSearchParams(query); + assert.equal(params.get('anaCase'), kase1); assert.equal(params.get('anaAxis'), '1'); assert.equal(params.get('anaIndex'), '3,3,2'); assert.equal(params.get('anaMeanFree'), '1'); + const before6 = await stateShown(), sinceLoad = Date.now(); + await load('light', query); await drawnPanels(); await settled('reloaded'); + const after6 = await stateShown(); + assert.deepEqual(after6, before6, 'The reload restores the case, axis, position and mean option'); + assert.deepEqual(asked('field_compare', sinceLoad).map(f => f.body), [{ run: keptRun, entry: 0, case: 1, axis: 1, index: [3, 3, 2], mean_free: true }], 'The reload asks for that slice once'); + assert.ok((await panel('error', 6, 4)).cells.flat().every(c => same(c, mid)), 'and draws it as before'); + await evaluate(WATCHER); + const rows6 = []; + for (const cause of ['focus', 'timer']) { + const since = Date.now(); + await evaluate(`window.__still.start(); true`); + if (cause === 'focus') { await evaluate(`window.dispatchEvent(new Event('focus')); true`); await reading(since, WATCHED.concat(['map']), 'focus'); } + else await reading(since, WATCHED, 'the timer', Math.round((IDLE_MS + 15000) / 100)); + const r = await evaluate(`window.__still.stop()`); + assert.deepEqual(touched(r, ['tabs', 'main', 'aside', 'needs-panel']), [], cause + ': nothing is touched'); + assert.equal(r.flash, 0, cause + ': "Reading…" is never shown'); + assert.equal(asked('fields', since).length + asked('field_compare', since).length, 0, cause + ': nothing of the fields is asked again'); + rows6.push(cause + ': 0 nodes added, removed or changed, nothing of the fields asked'); + } + check('6. The address kept ' + query + '; the reload drew the same case, axis, position and mean option with one field_compare; ' + rows6.join('; ')); + + // ---- 7. Light and dark, 1440 and 390 wide ----------------------------------------------------------------------------------- + const seen7 = []; + for (const [w, hgt] of [[1440, 900], [390, 844]]) for (const name of ['light', 'dark']) { + const tag = name + '-' + w; + await size(w, hgt); await load(name, 'anaBench=' + BENCH + '&anaSubject=fd-kept'); + await drawnPanels(); await settled(tag); + await evaluate(`(() => { document.querySelector('section.fld').scrollIntoView({ block: 'start' }); return true; })()`); await pause(300); + const r = await evaluate(`(() => { const m = document.getElementById('main'), f = document.querySelector('section.fld'); const cv = [...f.querySelectorAll('canvas')].map(c => { if (!c.width) return 0; const d = c.getContext('2d').getImageData(0, 0, c.width, c.height).data; let n = 0; for (let i = 3; i < d.length; i += 4) if (d[i]) n++; return n; }); const tops = [...f.querySelectorAll('.fld-panel')].map(p => Math.round(p.getBoundingClientRect().top)); const widths = [...f.querySelectorAll('.fld-panel')].map(p => Math.round(p.getBoundingClientRect().width)); const wide = [...m.querySelectorAll('*')].filter(e => e.getBoundingClientRect().right > m.getBoundingClientRect().right + 1 && e.getBoundingClientRect().width > 0 && !e.closest('.tv-wrap')).map(e => e.tagName + '.' + e.className).slice(0, 4); return { cv, tops, widths, page: document.documentElement.scrollWidth - innerWidth, main: m.scrollWidth - m.clientWidth, wide }; })()`); + assert.ok(r.cv.every(n => n > 10), tag + ': no blank canvas ' + JSON.stringify(r.cv)); + assert.ok(r.page <= 0 && r.main <= 1 && !r.wide.length, tag + ': nothing overflows sideways ' + JSON.stringify(r)); + assert.ok(Math.max(...r.widths) - Math.min(...r.widths) <= 1, tag + ': the panels are of equal size ' + JSON.stringify(r.widths)); + if (w >= 1000) assert.equal(new Set(r.tops).size, 1, tag + ': side by side ' + JSON.stringify(r.tops)); + else assert.ok(r.tops[0] < r.tops[1] && r.tops[1] < r.tops[2], tag + ': stacked ' + JSON.stringify(r.tops)); + await shot(tag + '-7-kept-fields'); + seen7.push(tag + ' (' + (w >= 1000 ? 'side by side' : 'stacked') + ')'); + } + await size(1440, 900); + check('7. No blank canvas and nothing overflowing sideways: ' + seen7.join(', ') + (shots ? '; screenshots in ' + shots : '')); + + // ---- Nothing failed ----------------------------------------------------------------------------------------------------- + assert.deepEqual(errors, [], 'Script errors'); + assert.deepEqual(failures, [], 'Failed requests'); + check('No script error, no failed request'); + fs.writeFileSync(path.join(report, 'receipt.json'), JSON.stringify({ status: 'pass', folder, checks }, null, 2) + '\n'); + console.log('Receipt in ' + report); +})().catch(async error => { + process.exitCode = 1; + console.error(error); if (serverErrors) console.error('Server:', serverErrors.slice(-4000)); + console.error('Script errors:', JSON.stringify(errors)); console.error('Failed requests:', JSON.stringify(failures)); + try { if (evaluate) { await shot('failure'); console.error('Main:', (await evaluate('document.getElementById("main").innerText')).slice(0, 2500)); } } catch (_) { /* the page is gone */ } + fs.writeFileSync(path.join(report, 'failure.json'), JSON.stringify({ status: 'failed', error: String(error && error.stack || error), checks, errors, failures }, null, 2) + '\n'); +}).finally(async () => { + try { session?.close(); } catch (_) { /* closed */ } + for (const child of children.reverse()) await stop(child); + if (owned) try { dropOwned(...owned); } catch (error) { console.error('Dropping the disposable schemas failed:', error.message); process.exitCode = 1; } + try { execFileSync('chmod', ['-R', 'u+w', temporary]); } catch (_) { /* nothing was made read-only */ } // finished runs leave their directories read-only + fs.rmSync(temporary, { recursive: true, force: true }); +}); diff --git a/tests/project_fields_browser_fixture.py b/tests/project_fields_browser_fixture.py new file mode 100644 index 00000000..e5f00464 --- /dev/null +++ b/tests/project_fields_browser_fixture.py @@ -0,0 +1,103 @@ +"""The fields the browser check of kept fields reads (tests/browser_project_workspace_fields.cjs). + +Written with the standard library only, and adopted by the check as the products of two recipes: + +- kept/: the product of a model whose run kept fields: field-index.json with two cases, probe.json naming them, + a diagnostic file with the figure the run reported, and the four arrays (float64, shape 6 x 5 x 4): + case 0 (scene-a-frame-3, validation): pressure-reference.npy and pressure-prediction.npy, equal except where + x >= 3 and y >= 2, where the prediction is higher by 0.4 + 0.1 z; + case 1 (scene-b-frame-9, test): offset-reference.npy and offset-prediction.npy, the prediction the reference + plus 1.5 everywhere (a constant offset: its mean-free error is exactly zero, see reference()); +- none/: the product of a model whose run kept no fields (a notes file only). + +It prints, as JSON, what the check compares the page with: the shape, both cases' values in C order, and the +figures of each over the whole field (64-bit arithmetic, as the operation computes them). +""" +import argparse +import json +import math +import os +import struct + +SHAPE = (6, 5, 4) + + +def indexes(shape): + out = [()] + for size in shape: + out = [index + (i,) for index in out for i in range(size)] + return out + + +def npy(shape, values): + header = repr({'descr': '= 3 and y >= 2 else 0.0) + + +def figures(p, r): + e = [a - b for a, b in zip(p, r)] + n = len(r) + mp, mr = math.fsum(p) / n, math.fsum(r) / n + fp, fr = [a - mp for a in p], [b - mr for b in r] + fe = [a - b for a, b in zip(fp, fr)] + norm = lambda values: math.sqrt(math.fsum(v * v for v in values)) # noqa: E731 + return {'count': n, 'nonfinite': 0, 'max_abs_error': max(map(abs, e)), 'mean_error': math.fsum(e) / n, + 'rmse': norm(e) / math.sqrt(n), 'relative_l2': norm(e) / norm(r) if norm(r) else None, + 'mean_free_relative_l2': norm(fe) / norm(fr) if norm(fr) else None} + + +def main(): + parser = argparse.ArgumentParser() + parser.add_argument('--out', required=True) + out = parser.parse_args().out + cells = indexes(SHAPE) + r0 = [reference(i) for i in cells] + p0 = [predicted(i) for i in cells] + r1 = r0 + p1 = [value + 1.5 for value in r0] + kept, none = os.path.join(out, 'kept'), os.path.join(out, 'none') + os.makedirs(kept, exist_ok=True) + os.makedirs(none, exist_ok=True) + arrays = {'pressure-reference.npy': r0, 'pressure-prediction.npy': p0, 'offset-reference.npy': r1, + 'offset-prediction.npy': p1} + for name, values in arrays.items(): + with open(os.path.join(kept, name), 'wb') as handle: + handle.write(npy(SHAPE, values)) + size = os.path.getsize(os.path.join(kept, 'pressure-reference.npy')) + index = [{'run_id': 'f' * 32, 'cases': [ + {'member_ordinal': 0, 'predicted': {'name': 'pressure-prediction.npy', 'bytes': size}, + 'reference': {'name': 'pressure-reference.npy', 'bytes': size}, 'mask': None, 'time_units': 'not_applicable'}, + {'member_ordinal': 1, 'predicted': {'name': 'offset-prediction.npy', 'bytes': size}, + 'reference': {'name': 'offset-reference.npy', 'bytes': size}, 'mask': None}]}] + probe = {'format': 'probe_v1', 'split': 'validation', 'members': [ + {'ordinal': 0, 'frozen_reference': {'member_id': 'scene-a-frame-3', 'split': 'validation'}}, + {'ordinal': 1, 'frozen_reference': {'member_id': 'scene-b-frame-9', 'split': 'test'}}]} + f0, f1 = figures(p0, r0), figures(p1, r1) + diagnostic = {'format': 'fixture_pressure_diagnostic_v1', + 'mean_free_same_request_pressure_relative_l2': f0['mean_free_relative_l2'], 'population': 'probe'} + for name, value in (('field-index.json', index), ('probe.json', probe), ('pressure-diagnostic.json', diagnostic)): + with open(os.path.join(kept, name), 'w') as handle: + json.dump(value, handle) + with open(os.path.join(none, 'notes.txt'), 'w') as handle: + handle.write('This run kept no fields.\n') + print(json.dumps({'shape': list(SHAPE), 'cases': [ + {'name': 'scene-a-frame-3', 'split': 'validation', 'reference': r0, 'predicted': p0, 'figures': f0}, + {'name': 'scene-b-frame-9', 'split': 'test', 'reference': r1, 'predicted': p1, 'figures': f1}], + 'reported': diagnostic['mean_free_same_request_pressure_relative_l2']})) + + +if __name__ == '__main__': + main() diff --git a/tests/test_tuldok_project_fields.py b/tests/test_tuldok_project_fields.py new file mode 100644 index 00000000..fd827d96 --- /dev/null +++ b/tests/test_tuldok_project_fields.py @@ -0,0 +1,475 @@ +"""The fields a run kept, side by side (docs/plans/definition-first-projects/spec-d6.md, slice D6a). + +The readers are tested on files the tests write with the standard library +(NPY with struct, the index and probe with json) and need no database. The +operations need one and run only when TULDOK_DATABASE_URL names a disposable +cluster: they adopt a product for recipes/fit-a (as test_tuldok_project_weights +does) holding a field index and its arrays. No GPU is used. +""" +import hashlib +import json +import math +import os +from pathlib import Path +import sys +import tempfile +import unittest +from unittest import mock + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) +sys.path.insert(0, str(Path(__file__).resolve().parent)) + +import agent_api # noqa: E402 +from tuldok_project import adoption, inside, inside_archive, inside_fields, local, operations, store # noqa: E402 +from tuldok_project.service import Service # noqa: E402 +import test_tuldok_project_builds as builds_base # noqa: E402 +from test_tuldok_project_inside import OWNER, f32, floats, npy, raw_header # noqa: E402 + +FIELDS = ('fields', 'field_compare') +NAN = float('nan') + + +def flat(shape, value): + """value(index) over shape in C order.""" + indexes = [()] + for size in shape: + indexes = [index + (position,) for index in indexes for position in range(size)] + return [value(index) for index in indexes] + + +def case(predicted='p.npy', reference='r.npy', mask=None, **extra): + return {'predicted': {'name': predicted, **extra.pop('predicted_extra', {})}, + 'reference': {'name': reference, **extra.pop('reference_extra', {})}, + 'mask': None if mask is None else {'name': mask}, **extra} + + +def norm(values): + return math.sqrt(math.fsum(value * value for value in values)) + + +def same(a, b): + """Two lists of floats equal, NaN equal to NaN.""" + return len(a) == len(b) and all((x != x and y != y) or x == y for x, y in zip(a, b)) + + +class FieldCase(unittest.TestCase): + + def setUp(self): + directory = tempfile.TemporaryDirectory() + self.addCleanup(directory.cleanup) + self.root = os.path.realpath(directory.name) + inside_archive.forget_members() + inside.forget_indexes() + inside_fields.forget_figures() + self.product = inside.Product('run-1', self.root) + + def write(self, name, data): + path = Path(self.root, name) + path.write_bytes(data if isinstance(data, bytes) else json.dumps(data).encode()) + return path + + def index(self, *entries): + self.write('field-index.json', [{'run_id': 'r' * 32, 'cases': list(cases)} for cases in entries]) + + def pair(self, shape, reference, predicted, *, descr='= 2: + return to_c_order(values, header.shape) + return values + + def columns(blob, header, name, wanted, most): """The first wanted columns of a two-axis array (N, at least wanted), every stride-th row, at most most rows. diff --git a/tuldok_project/inside_fields.py b/tuldok_project/inside_fields.py new file mode 100644 index 00000000..31b9cda9 --- /dev/null +++ b/tuldok_project/inside_fields.py @@ -0,0 +1,426 @@ +"""The fields a run kept: its native (reference) and predicted fields, and their signed error, side by side. + +Owns sections 1 and 2 of docs/plans/definition-first-projects/spec-d6.md. A +product keeps fields when the top of its directory holds INDEX +(field-index.json): a list of entries, each with a list of cases, each case +naming a predicted and a reference .npy (and optionally a mask) by a plain +file name at the top of the product. fields lists every case with whether it +can be compared and why not; the member a case stands for is named from +probe.json (format probe_v1) when the product holds one, and the figures the +run reported itself (numeric fields ending relative_l2 of a JSON file at the +top whose format ends _diagnostic_v1) are listed beside, never used. +field_compare reads one case: a slice of the native field, the predicted +field and their difference (predicted minus native) through two axes, as +array_slice draws one, and the error's figures over the whole field (inside +the mask, finite values only), in 64-bit floats with math.fsum and +math.sumprod. The figures of a case are kept (FIGURES_KEPT of them, least +recently used dropped) while its files are unchanged, so a slider moved reads +only the slice. Bounds: FIELD_VALUES values a field, INDEX_BYTES of the index, +JSON_BYTES of probe.json and of a diagnostic file, CASES cases listed. The +arrays are read by inside_arrays; nothing here writes, opens the project or +checks a hash: bytes is compared with the file and a mismatch is shown, not +refused. +""" +import collections +import json +import math +import operator +import os +import threading +from array import array +from itertools import compress, repeat + +from . import inside, inside_arrays +from .inside_archive import locate +from .store import ProjectError + +INDEX = 'field-index.json' +PROBE = 'probe.json' +PROBE_FORMAT = 'probe_v1' +DIAGNOSTIC_SUFFIX = '_diagnostic_v1' +REPORTED_SUFFIX = 'relative_l2' +FIELD_VALUES = 16_777_216 # values of one field +INDEX_BYTES = 4 * 1024 * 1024 # the field index +JSON_BYTES = 4 * 1024 * 1024 # probe.json, and a file looked at for a diagnostic +TOP_JSON_FILES = 500 # JSON files at the top looked at for a diagnostic +CASES = 10_000 # cases listed +SLICE_MOST = 256 # rows and columns of a slice +FIGURES_KEPT = 16 # cases whose whole-field figures are kept +NUMERIC = ('f', 'i', 'u') +MASKS = ('b', 'i', 'u') +_FIGURES = ('count', 'nonfinite', 'max_abs_error', 'mean_error', 'rmse', 'relative_l2', 'mean_free_relative_l2') +_lock = threading.Lock() +_kept = collections.OrderedDict() # (root, entry, case, stamps) -> (figures, means) + + +def _refuse(message, code='unsupported'): + raise ProjectError(message, code) + + +def forget_figures(): + with _lock: + _kept.clear() + + +# ------------------------------------------------------------------ reading JSON at the top + +def _json_at(product, name, most): + """The decoded JSON of the file name at the top of the product, or None when there is none; refused when it is + larger than most or not JSON.""" + try: + place = locate(product.root, name) + except ProjectError: + return None + if (place.size or 0) > most: + _refuse(f'{name} is {place.size} bytes; at most {most} are read.', 'too-large') + try: + return json.loads(bytes(place.head(place.size or 0)).decode('utf-8')) + except (ValueError, RecursionError): + _refuse(f'{name} is not JSON.') + + +def _index(product): + """The entries of the product's field index, or None when it keeps none; a damaged index is refused.""" + value = _json_at(product, INDEX, INDEX_BYTES) + if value is None: + try: + locate(product.root, INDEX) + except ProjectError: + return None + if not isinstance(value, list): + _refuse(f'{INDEX} must be a list of entries.') + for position, entry in enumerate(value): + if not isinstance(entry, dict) or not isinstance(entry.get('cases'), list): + _refuse(f'Entry {position} of {INDEX} must be an object with a list of cases.') + return value + + +def _probe_members(product): + """{member_ordinal: (member id, split)} from probe.json of format probe_v1; empty when there is none.""" + try: + value = _json_at(product, PROBE, JSON_BYTES) + except ProjectError: + return {} + if not isinstance(value, dict) or value.get('format') != PROBE_FORMAT or not isinstance(value.get('members'), + list): + return {} + found = {} + for position, member in enumerate(value['members']): + if not isinstance(member, dict): + continue + ordinal = member.get('ordinal', position) + frozen = member.get('frozen_reference') if isinstance(member.get('frozen_reference'), dict) else {} + identifier = frozen.get('member_id') if isinstance(frozen.get('member_id'), str) else None + split = next((item for item in (frozen.get('split'), member.get('split'), value.get('split')) + if isinstance(item, str)), None) + if type(ordinal) is int and (identifier or split): + found.setdefault(ordinal, (identifier, split)) + return found + + +def _reported(product): + """[{file, field, value}]: the numeric fields ending relative_l2 of each *_diagnostic_v1 file at the top.""" + out = [] + names = sorted(item.name for item in os.scandir(product.root) + if item.name.lower().endswith('.json') and item.name != INDEX)[:TOP_JSON_FILES] + for name in names: + try: + place = locate(product.root, name) + if (place.size or 0) > JSON_BYTES: + continue + raw = bytes(place.head(place.size or 0)) + if DIAGNOSTIC_SUFFIX.encode() not in raw: + continue + value = json.loads(raw.decode('utf-8')) + except (ProjectError, ValueError, RecursionError): + continue + if not isinstance(value, dict) or not isinstance(value.get('format'), str) \ + or not value['format'].endswith(DIAGNOSTIC_SUFFIX): + continue + for field, item in value.items(): + if (field.endswith(REPORTED_SUFFIX) and isinstance(item, (int, float)) and not isinstance(item, bool) + and math.isfinite(item)): + out.append({'file': name, 'field': field, 'value': item}) + return out + + +# ------------------------------------------------------------------ one case + +def _name_of(part): + """The file name a case's predicted, reference or mask names, or None.""" + return part.get('name') if isinstance(part, dict) and isinstance(part.get('name'), str) else None + + +def _plain_problem(name): + if not name or '/' in name or '\\' in name or '..' in name or '!' in name or '\x00' in name: + return f'{name!r} is not a plain file name at the top of the product' + if not name.lower().endswith('.npy'): + return f'{name} is not an .npy file' + return None + + +class _Case: + """One case of the index, its files read as far as their headers.""" + + def __init__(self, product, entry, position, raw, members): + self.entry, self.case = entry, position + self.raw = raw if isinstance(raw, dict) else {} + self.predicted = _name_of(self.raw.get('predicted')) + self.reference = _name_of(self.raw.get('reference')) + mask = self.raw.get('mask') + self.mask = _name_of(mask) + self.shape = self.dtype = None + self.reason, self.code = None, 'unsupported' + self.bytes_mismatch = [] + self.files = {} # role -> (place, header) + ordinal = self.raw.get('member_ordinal') + member = members.get(ordinal) if type(ordinal) is int else None + self.name = member[0] if member and member[0] else f'case {position}' if entry == 0 else \ + f'entry {entry} case {position}' + self.split = member[1] if member else None + if not isinstance(raw, dict): + self.reason = 'The case is not a JSON object.' + return + if self.predicted is None or self.reference is None: + self.reason = 'The case does not name its predicted and reference files.' + return + if mask is not None and self.mask is None: + self.reason = 'The mask must be null or name a file.' + return + self.reason = self._read(product) + + def _read(self, product): + roles = [('predicted', self.predicted), ('reference', self.reference)] + if self.mask is not None: + roles.append(('mask', self.mask)) + for role, name in roles: + problem = _plain_problem(name) + if problem: + return f'The {role} file: {problem}.' + try: + place = locate(product.root, name) + except ProjectError: + return f'The {role} file {name} is not in the product.' + declared = self.raw[role].get('bytes') + if type(declared) is int and declared != place.size: + self.bytes_mismatch.append(name) + try: + header = inside_arrays.read_header(place) + except ProjectError as error: + return f'The {role} file {name}: {error}' + if header.problem is not None: + return f'The {role} file {name} is {header.problem}.' + if header.kind not in (MASKS if role == 'mask' else NUMERIC): + return f'The {role} file {name} is of the type {header.dtype}, not ' + ( + 'a boolean or integer mask.' if role == 'mask' else 'a number.') + try: + inside_arrays.check_length(place.blob(), header, name) + except ProjectError as error: + return f'The {role} file: {error}' + self.files[role] = (place, header) + predicted, reference = self.files['predicted'][1], self.files['reference'][1] + self.shape = reference.shape + self.dtype = (predicted.dtype if predicted.dtype == reference.dtype + else f'{predicted.dtype} / {reference.dtype}') + for role in ('predicted', 'mask'): + if role in self.files and self.files[role][1].shape != reference.shape: + return (f'The {role} file is of the shape {self.files[role][1].shape}; the reference is of the shape ' + f'{reference.shape}.') + if not 1 <= len(reference.shape) <= 4: + return f'The fields have {len(reference.shape)} axes; one to four are compared.' + if reference.count > FIELD_VALUES: + self.code = 'too-large' + return f'The fields have {reference.count} values each; at most {FIELD_VALUES} are compared.' + return None + + def listed(self): + details = {key: value for key, value in self.raw.items() if key not in ('predicted', 'reference', 'mask')} + item = {'entry': self.entry, 'case': self.case, 'name': self.name, 'split': self.split, + 'predicted': self.predicted, 'reference': self.reference, 'mask': self.mask, 'shape': self.shape, + 'dtype': self.dtype, 'comparable': self.reason is None, 'details': details} + if self.reason is not None: + item['reason'] = self.reason + if self.bytes_mismatch: + item['bytes_mismatch'] = self.bytes_mismatch + return item + + def stamps(self): + out = [] + for role in ('predicted', 'reference', 'mask'): + if role in self.files: + info = os.stat(self.files[role][0].path) + out.append((role, info.st_size, info.st_mtime_ns, info.st_ino)) + return tuple(out) + + +def _cases(product, entries, members): + found = [] + for entry, item in enumerate(entries): + for position, raw in enumerate(item['cases']): + if len(found) >= CASES: + return found, True + found.append(_Case(product, entry, position, raw, members)) + return found, False + + +@inside.reading +def fields(product): + """{kept, cases, reported}: every case of the product's field index, and the figures the run reported.""" + entries = _index(product) + if entries is None: + return {'kept': False, 'cases': [], 'reported': [], 'more': False} + found, more = _cases(product, entries, _probe_members(product)) + return {'kept': True, 'cases': [case.listed() for case in found], 'reported': _reported(product), 'more': more} + + +# ------------------------------------------------------------------ figures + +def _finite(values): + """Whether every value is finite (one sum when it is finite, else value by value).""" + try: + if math.isfinite(math.fsum(values)): + return True + except (OverflowError, ValueError): + pass + return all(map(math.isfinite, values)) + + +def _number(compute): + """compute(), or None when it overflows or is not a finite number.""" + try: + value = compute() + except (OverflowError, ValueError, ZeroDivisionError): + return None + return value if value is not None and math.isfinite(value) else None + + +def _figures(predicted, reference, inside_mask): + """(figures over the inside cells whose two values are finite, (mean predicted, mean reference) or None).""" + if inside_mask is not None: + predicted = array('d', compress(predicted, inside_mask)) + reference = array('d', compress(reference, inside_mask)) + nonfinite = 0 + if not (_finite(predicted) and _finite(reference)): + good_p, good_r = list(map(math.isfinite, predicted)), list(map(math.isfinite, reference)) + nonfinite = good_p.count(False) + good_r.count(False) + keep = list(map(operator.and_, good_p, good_r)) + predicted, reference = array('d', compress(predicted, keep)), array('d', compress(reference, keep)) + count = len(reference) + figures = dict.fromkeys(_FIGURES) + figures.update(count=count, nonfinite=nonfinite) + if not count: + return figures, None + error = array('d', map(operator.sub, predicted, reference)) + squares = _number(lambda: math.sumprod(error, error)) + norm_reference = _number(lambda: math.sqrt(math.sumprod(reference, reference))) + figures['max_abs_error'] = _number(lambda: max(map(abs, error))) + figures['mean_error'] = _number(lambda: math.fsum(error) / count) + figures['rmse'] = _number(lambda: math.sqrt(squares / count)) if squares is not None else None + if squares is not None and norm_reference: + figures['relative_l2'] = _number(lambda: math.sqrt(squares) / norm_reference) + mean_p = _number(lambda: math.fsum(predicted) / count) + mean_r = _number(lambda: math.fsum(reference) / count) + means = None + if mean_p is not None and mean_r is not None: + means = (mean_p, mean_r) + free_p = array('d', map(operator.sub, predicted, repeat(mean_p))) + free_r = array('d', map(operator.sub, reference, repeat(mean_r))) + free_error = array('d', map(operator.sub, free_p, free_r)) + free_norm = _number(lambda: math.sqrt(math.sumprod(free_r, free_r))) + free_squares = _number(lambda: math.sumprod(free_error, free_error)) + if free_norm and free_squares is not None: + figures['mean_free_relative_l2'] = _number(lambda: math.sqrt(free_squares) / free_norm) + return figures, means + + +def _whole_figures(product, case): + key = (product.root, case.entry, case.case, case.stamps()) + with _lock: + if key in _kept: + _kept.move_to_end(key) + return _kept[key] + values = {role: inside_arrays.c_order_values(place.blob(), header, place.address) + for role, (place, header) in case.files.items()} + inside_mask = None + if 'mask' in values: + inside_mask = [1 if value else 0 for value in values['mask']] + found = _figures(values['predicted'], values['reference'], inside_mask) + with _lock: + _kept[key] = found + while len(_kept) > FIGURES_KEPT: + _kept.popitem(last=False) + return found + + +# ------------------------------------------------------------------ the slice + +def _drawn(ndim, axis): + """(the two axes drawn or [0] for one axis, the axis cut across or None) of a field of ndim axes.""" + if ndim == 1: + return [0], None + if ndim == 2: + return [0, 1], None + if axis is None: + axis = ndim - 1 + if not 0 <= axis < ndim: + _refuse(f'axis must be one of the {ndim} axes of the fields.', 'invalid') + return [other for other in range(ndim) if other != axis][-2:], axis + + +@inside.reading +def field_compare(product, *, entry, case, axis=None, index=None, mean_free=False): + """A slice of one kept case's native, predicted and signed error fields, with the error's whole-field figures.""" + entries = _index(product) + if entries is None: + _refuse('This product keeps no fields.', 'not-found') + if not 0 <= entry < len(entries) or not 0 <= case < len(entries[entry]['cases']): + _refuse(f'There is no case {case} of entry {entry} in {INDEX}.', 'not-found') + found = _Case(product, entry, case, entries[entry]['cases'][case], {}) + if found.reason is not None: + _refuse(f'Case {case} of entry {entry} cannot be compared: {found.reason}', found.code) + figures, means = _whole_figures(product, found) + shape, ndim = found.shape, len(found.shape) + axes, axis = _drawn(ndim, axis) + if index is None: + index = [size // 2 for size in shape] + if len(index) != ndim: + _refuse(f'index must give one position for each of the {ndim} axes of the fields.', 'invalid') + index = list(index) + sliced = {} + for role, (place, header) in found.files.items(): + _, _, rows, columns, stride, values = inside_arrays.slice_values(place.blob(), header, role, axes=axes, + index=index, most=SLICE_MOST) + sliced[role] = values + reference, predicted = sliced['reference'], sliced['predicted'] + inside_cells = [bool(value) for value in sliced['mask']] if 'mask' in sliced else None + shift_p, shift_r = means if mean_free and means is not None else (0.0, 0.0) + nan = math.nan + shown_r, shown_p, error = [], [], [] + low = high = None + limit = None + for position, (r, p) in enumerate(zip(reference, predicted)): + if inside_cells is not None and not inside_cells[position]: + shown_r.append(nan) + shown_p.append(nan) + error.append(nan) + continue + r, p = float(r), float(p) + shown_r.append(r) + shown_p.append(p) + for value in (r, p): + if math.isfinite(value): + low = value if low is None or value < low else low + high = value if high is None or value > high else high + try: + difference = (p - shift_p) - (r - shift_r) + except OverflowError: + difference = nan + error.append(difference) + if math.isfinite(difference): + limit = abs(difference) if limit is None or abs(difference) > limit else limit + return {'entry': entry, 'case': case, 'shape': shape, 'dtype': found.dtype, 'axes': axes, 'axis': axis, + 'index': index, 'rows': rows, 'columns': columns, 'stride': stride, 'mean_free': bool(mean_free), + 'reference_f32': inside_arrays.float32_base64(shown_r), + 'predicted_f32': inside_arrays.float32_base64(shown_p), + 'error_f32': inside_arrays.float32_base64(error), + 'range': None if low is None else [low, high], 'error_limit': limit, 'figures': figures} diff --git a/tuldok_project/inside_weights.py b/tuldok_project/inside_weights.py index e04603c4..ce2a9ea6 100644 --- a/tuldok_project/inside_weights.py +++ b/tuldok_project/inside_weights.py @@ -212,24 +212,7 @@ def piece(first, count): return array('d', inside_arrays.decode(raw, header)) if not logical or not header.fortran or len(header.shape) < 2: return piece - whole = piece(0, header.count) - shape = header.shape - reordered = array('d', bytes(8 * header.count)) - # C position of the value at Fortran position f: walk the Fortran order with its C strides. - c_steps, step = [0] * len(shape), 1 - for axis in reversed(range(len(shape))): - c_steps[axis] = step - step *= shape[axis] - position, counters = 0, [0] * len(shape) - for value in whole: - reordered[position] = value - for axis in range(len(shape)): - counters[axis] += 1 - position += c_steps[axis] - if counters[axis] < shape[axis]: - break - position -= c_steps[axis] * shape[axis] - counters[axis] = 0 + reordered = inside_arrays.to_c_order(piece(0, header.count), header.shape) return lambda first, count: reordered[first:first + count] diff --git a/tuldok_project/operations.py b/tuldok_project/operations.py index 82071a5c..28c59b7c 100644 --- a/tuldok_project/operations.py +++ b/tuldok_project/operations.py @@ -5,7 +5,8 @@ section 2 of spec-w3.md (draft_branch, revert_definition), the five of section 3 of spec-d1.md (records, record, inside, array_slice, array_summary), the three of section 3 of spec-d2.md (weights, weights_compare, -array_tiles), the five of section 5 of spec-d4.md (annotation_tasks, +array_tiles), the two of section 2 of spec-d6.md (fields, field_compare), +the five of section 5 of spec-d4.md (annotation_tasks, annotated_records, annotation, set_annotation, revert_annotations) and the five of sections 2 and 4 of spec-d5.md (endpoint, set_endpoint, find_endpoints, suggestion_models, suggest_annotation). @@ -97,6 +98,8 @@ def _arguments(required=(), **properties): 'stride') TILES = ('shape', 'dtype', 'across', 'axes', 'index', 'first', 'tiles', 'rows', 'columns', 'stride', 'values_f32', 'min', 'max', 'nonfinite') +FIELD_COMPARE = ('entry', 'case', 'shape', 'dtype', 'axes', 'axis', 'index', 'rows', 'columns', 'stride', + 'mean_free', 'reference_f32', 'predicted_f32', 'error_f32', 'range', 'error_limit', 'figures') COMPARE = ('tensors', 'total', 'only_here', 'only_there', 'reshaped', 'unread') SAVE = ('written', 'deleted', 'results_written', 'results_deleted', 'annotations_written', 'annotations_deleted') CANCEL_RUN = ('id', 'reference', 'subject', 'state', 'cancel_file', 'already_asked') @@ -210,6 +213,15 @@ def _arguments(required=(), **properties): axes={'type': 'array', 'items': _AXIS, 'minItems': 2, 'maxItems': 2}, index={'type': 'array', 'items': {'type': 'integer', 'minimum': 0}, 'maxItems': 64}, first=_OFFSET, most=_limit(64)), TILES), + Operation('fields', "List the fields a finished run's product kept: each case's native and predicted files, its " + 'name, shape and whether the two can be compared, and the figures the run reported itself.', 'inspect', + False, _arguments(['run'], run=_RUN), ('kept', 'cases', 'reported')), + Operation('field_compare', "Read a slice of one kept case's native field, predicted field and signed error as " + '32-bit floats, with the figures of the error over the whole field.', 'inspect', False, + _arguments(['run', 'entry', 'case'], run=_RUN, entry=_OFFSET, case=_OFFSET, + axis={'type': 'integer', 'minimum': 0, 'maximum': 3}, + index={'type': 'array', 'items': {'type': 'integer', 'minimum': 0}, 'maxItems': 4}, + mean_free=_FLAG), FIELD_COMPARE), Operation('annotation_tasks', 'List the annotation tasks, each with its dataset, current product and counts of ' 'its records by the state of their annotations.', 'inspect', False, _arguments(), ('tasks',)), Operation('annotated_records', "Read one page of the records of a task's dataset with their annotations, " diff --git a/tuldok_project/service.py b/tuldok_project/service.py index 021ecb0e..3cfb1ba1 100644 --- a/tuldok_project/service.py +++ b/tuldok_project/service.py @@ -7,12 +7,13 @@ returns a JSON-plain object. Calls are answered one at a time under one lock of the service. Every mutating call that passed the actor check writes one activity row, done or refused. The six operations on build requests are -passed to build_requests. The five reads inside a product (spec-d1.md) and -the three reads of a model's weights (spec-d2.md) find the finished run (and -for weights_compare the other run) with the project open for a moment and -read its output directory through inside.py and inside_weights.py after -closing it; product_file does the same for the file route; those reads run -outside the lock, so a long one holds up no other call. The five operations +passed to build_requests. The five reads inside a product (spec-d1.md), the +three reads of a model's weights (spec-d2.md) and the two of the fields a run +kept (spec-d6.md) find the finished run (and for weights_compare the other +run) with the project open for a moment and read its output directory +through inside.py, inside_weights.py and inside_fields.py after closing it; +product_file does the same for the file route; those reads run outside the +lock, so a long one holds up no other call. The five operations on annotations (spec-d4.md section 5) work the same way: what the database holds of a task (its rows, the hashes kept for its product) is read under the lock, the product is read and hashed outside it (annotation_records), and @@ -51,13 +52,14 @@ import psycopg from . import (activity, annotation_records, annotation_rows, annotations, build_requests, builds, charts, check, - documents, environments, inside, inside_weights, launcher, local, operations, plan, pumas, store, - workspace) + documents, environments, inside, inside_fields, inside_weights, launcher, local, operations, plan, + pumas, store, workspace) from .documents import Problem CHECK_PROBLEMS = 200 -# The reads inside a product (spec-d1.md, spec-d2.md), each a function of ({argument: inside.Product}, arguments): +# The reads inside a product (spec-d1.md, spec-d2.md, spec-d6.md), each a function of +# ({argument: inside.Product}, arguments): # the products of the arguments in PRODUCT_ARGUMENTS that the call gives. call() finds them under the service's lock # and reads outside it: decompressing a large member, parsing a large mesh or comparing two large weights files takes # seconds, and the other calls (the page's own readings among them) must not wait for it. inside.py guards what it @@ -82,6 +84,10 @@ across=a.get('across'), axes=a.get('axes'), index=a.get('index'), first=a.get('first', 0), most=a.get('most', 16)), + 'fields': lambda found, a: inside_fields.fields(found['run']), + 'field_compare': lambda found, a: inside_fields.field_compare(found['run'], entry=a['entry'], case=a['case'], + axis=a.get('axis'), index=a.get('index'), + mean_free=a.get('mean_free', False)), } # The reads of annotations (spec-d4.md section 5): each takes the service's lock itself, only for its database work. ANNOTATION_READS = ('annotation_tasks', 'annotated_records', 'annotation') From 990bd4a161930df90189c3eca27c6257267a9a65 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Wed, 18 Nov 2026 23:05:21 -0700 Subject: [PATCH 082/131] docs(plan): phase 6 is built; the Benchmarks tab opens on an accuracy-against-time chart Co-Authored-By: Claude Opus 5.5 --- .../data-tools-plan.md | 2 +- .../execution-ledger.md | 20 +++++++++++++++++++ 2 files changed, 21 insertions(+), 1 deletion(-) diff --git a/docs/plans/definition-first-projects/data-tools-plan.md b/docs/plans/definition-first-projects/data-tools-plan.md index 38e65715..acd7e77b 100644 --- a/docs/plans/definition-first-projects/data-tools-plan.md +++ b/docs/plans/definition-first-projects/data-tools-plan.md @@ -2,7 +2,7 @@ **Status: approved by the owner on 2026-11-13, with the changes under "The owner's answer" below.** -**Built, 2026-11-13:** phases 1 to 5, on `feat/definition-first-projects`, not pushed; the specs `spec-d1.md` to `spec-d5.md` say what was built and what was not verified, and the [ledger](execution-ledger.md) has the record. **Not built:** phase 6. **Not run:** anything against a real Pumas endpoint, which waits for the owner's word (decision 3). The owner has not yet looked at these pages. +**Built:** phases 1 to 5 on 2026-11-13 and phase 6 on 2026-11-18, on `feat/definition-first-projects`, not pushed; the specs `spec-d1.md` to `spec-d6.md` say what was built and what was not verified, and the [ledger](execution-ledger.md) has the record. **Not run:** anything against a real Pumas endpoint, which waits for the owner's word (decision 3). ## The owner's answer diff --git a/docs/plans/definition-first-projects/execution-ledger.md b/docs/plans/definition-first-projects/execution-ledger.md index 4ac28aef..bb7b048b 100644 --- a/docs/plans/definition-first-projects/execution-ledger.md +++ b/docs/plans/definition-first-projects/execution-ledger.md @@ -684,3 +684,23 @@ Everything that speaks to Pumas was checked against a fake endpoint built from t **Not built:** phase 6, native, predicted and signed error side by side in the Analysis tab. **Next:** the owner looks at the pages; on the owner's word, the run against a real endpoint. + +## 2026-11-18: the Benchmarks tab opens on an accuracy-against-time chart; phase 6 is built + +**Owner, 2026-11-18:** "I agree to the changes. After that complete and test phase 6." + +**The Benchmarks tab** opened on the first benchmark with results, which in the lab defines no chart, so the accuracy-against-time chart was out of sight. It now opens, when no benchmark is asked for, on the first with results and a `tradeoff` chart, then the first with any chart (`36061650`; a step in `browser_project_workspace.cjs` checks it). The lab gained the same chart for its 127 earlier pressure models (`charts/pressure-models-error-against-speed.json`, lab commit `0cd5aaf72`): 127 points, 19 on the frontier. + +**Phase 6** (`4ff0ad42`, [spec-d6.md](spec-d6.md) with its "As built"): a product that holds `field-index.json` keeps fields; `fields` lists its cases and `field_compare` gives a slice of the native, predicted and signed error fields with whole-field figures; the Analysis tab shows them as three panels under "Kept fields", with the axis, the position, "Remove the mean" and the run's own reported figures. + +| Claim | Evidence | Result | +| --- | --- | --- | +| The readers and operations | `test_tuldok_project_fields` | 16 pass | +| Nothing else in the project folder's code changed in behaviour | the project suite on a disposable PostgreSQL | 735 pass | +| Catalog mode's manifest is unchanged | `test_agent_api`, `test_agent_negotiation`, `test_agent_http` | 43 pass, 4 skipped | +| The page | `browser_project_workspace_fields.cjs` (seven steps of spec section 5) and, again, `_weights`, `_inside` and `browser_project_workspace` | all pass | +| The lab's runs | `fields` and `field_compare` through the service on the owner's database, read only | 83 runs keep fields, all comparable; for run `7a700731…` Tuldok's mean-free relative L2 is 0.00286561549674967 and the run reported 0.0028656154967496624 | + +**Not verified:** masks in the page (no lab run has one); 1-D, 2-D and 4-D fields in the page; a field near the 16,777,216-value bound. In the lab, Analysis opens on the first subject of a benchmark, which may keep no fields: choose an earlier pressure model that does (83 of the 150 fits). + +**The data tools plan is built:** phases 1 to 6. **Not run:** anything against a real Pumas endpoint, which waits for the owner's word. From 8db523b41db75dff19082933ad1296e2dfdcdc58 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Wed, 18 Nov 2026 23:06:06 -0700 Subject: [PATCH 083/131] docs(research): the clones' size Co-Authored-By: Claude Opus 5.5 --- docs/research/competitive-landscape/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/research/competitive-landscape/README.md b/docs/research/competitive-landscape/README.md index 137c6e96..9b92a28d 100644 --- a/docs/research/competitive-landscape/README.md +++ b/docs/research/competitive-landscape/README.md @@ -1,6 +1,6 @@ # Tuldok and the tools that do the same jobs -Researched 2026-11-18. Four areas were surveyed in parallel: annotation and dataset curation; experiment tracking, lifecycle and versioning; synthetic data generation, model visualisation and evaluation harnesses; physics-AI and simulation-surrogate platforms. Web facts were read on 2026-11-18 unless dated otherwise. Open-source repositories were cloned shallowly and read, never built or run, under `workspace/scratch/competitor-repos/` (about 2.4 GB in all: label-studio, cvat, argilla, doccano, mlflow, clearml, dvc, aim, zenml, distilabel, netron, WeightWatcher, BlenderProc, model-explorer, lm-evaluation-harness, physicsnemo, neuraloperator, PDEBench, the_well, deepxde). FiftyOne (2.1 GB) was grepped and deleted; Rerun was read through the GitHub tree. +Researched 2026-11-18. Four areas were surveyed in parallel: annotation and dataset curation; experiment tracking, lifecycle and versioning; synthetic data generation, model visualisation and evaluation harnesses; physics-AI and simulation-surrogate platforms. Web facts were read on 2026-11-18 unless dated otherwise. Open-source repositories were cloned shallowly and read, never built or run, under `workspace/scratch/competitor-repos/` (about 3.9 GB in all: label-studio, cvat, argilla, doccano, mlflow, clearml, dvc, aim, zenml, distilabel, netron, WeightWatcher, BlenderProc, model-explorer, lm-evaluation-harness, physicsnemo, neuraloperator, PDEBench, the_well, deepxde). FiftyOne (2.1 GB) was grepped and deleted; Rerun was read through the GitHub tree. **[unverified]** marks a claim taken from vendor marketing, an aggregator or memory and not confirmed in a primary source. Tuldok's column describes the branch `feat/definition-first-projects` as of today (project-folder mode, the Map workspace, data tools phases 1 to 6) plus catalog mode. From a312e13edae60aa1be9781a2d7f55ad0464f5c68 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Wed, 18 Nov 2026 23:07:08 -0700 Subject: [PATCH 084/131] docs(research): the key claims checked by hand in the clones; the Pareto search corrected Co-Authored-By: Claude Opus 5.5 --- docs/research/competitive-landscape/README.md | 20 ++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/docs/research/competitive-landscape/README.md b/docs/research/competitive-landscape/README.md index 9b92a28d..c3154478 100644 --- a/docs/research/competitive-landscape/README.md +++ b/docs/research/competitive-landscape/README.md @@ -17,7 +17,7 @@ Researched 2026-11-18. Four areas were surveyed in parallel: annotation and data **Three things only Tuldok has**, confirmed by searching the code of the open tools and the documentation of the closed ones: -1. **An accuracy-against-time chart with the Pareto frontier.** No tracker (MLflow, ClearML, DVC, ZenML, Aim: a code search for "pareto" finds nothing), no harness (lm-eval, HELM, Inspect, Promptfoo, MLPerf) and no physics benchmark (PDEBench, The Well, PhysicsNeMo-CFD) draws one. MLPerf sets an accuracy pass mark and then ranks by speed; HELM and Promptfoo add speed as a column; W&B can be made to draw one with a custom Vega panel. For a project with two targets, accuracy-first models and real-time models, this is the central view, and it is Tuldok's. +1. **An accuracy-against-time chart with the Pareto frontier.** No tracker draws one (MLflow, ClearML, DVC, ZenML, Aim: the word "pareto" appears in MLflow only inside its GEPA prompt optimiser, and in ClearML's SDK only where `HyperParameterOptimizer` sorts multi-objective trials by successive Pareto fronts, a ranking with no chart; see section 5a), no harness (lm-eval, HELM, Inspect, Promptfoo, MLPerf) and no physics benchmark (PDEBench, The Well, PhysicsNeMo-CFD) draws one. MLPerf sets an accuracy pass mark and then ranks by speed; HELM and Promptfoo add speed as a column; W&B can be made to draw one with a custom Vega panel. For a project with two targets, accuracy-first models and real-time models, this is the central view, and it is Tuldok's. 2. **A family tree of models.** Others draw how files were produced: W&B artifact lineage, ClearML parent tasks, ZenML pipeline DAGs, DVC `dvc dag`, Valohai data heritage, Ansys SimAI's 2026 R1 Build panel. None shows which model derives from which with the kind of change, groups and comparisons, as the Map does. The nearest real model tree is the Hugging Face Hub's `base_model` tree, outside these tools. 3. **A project that is a Git folder of definitions only,** with the working copy in a database, weights and products kept out of Git on the machine, and no hash lockfiles. Only DVC (`dvc.yaml`, plots declared in files, experiments as Git refs) and Valohai (`valohai.yaml`) keep definitions in Git, and DVC rests on hash lockfiles. Charts declared as files: Tuldok and DVC only. @@ -204,6 +204,24 @@ PhysicsNeMo and NeuralOperator models as a recipe's training code; PhiFlow, Warp - **Source-available, not open source:** SDV is BSL, lakeFS is BSL from 2026-09-22, and the ClearML server is SSPL. - **Fine with attribution:** PhysicsNeMo, NeuralOperator, The Well, Netron, WeightWatcher, Label Studio's open edition, CVAT, FiftyOne's open edition and MLflow are permissive. +## 5a. Checked by hand in the clones + +The four areas were researched by separate agents. The claims this document leans on were then checked again directly in the cloned code on 2026-11-18: + +| Claim | Where | Result | +| --- | --- | --- | +| CVAT removed its Git sync | `cvat/apps/dataset_repo/README.md` | Confirmed: "…synchronizing CVAT tasks with Git repositories, which was removed." | +| No tracker draws an accuracy-vs-time Pareto chart | whole-word `pareto` in mlflow, clearml, dvc, aim, zenml | **Corrected.** Earlier wording said a search finds nothing. MLflow: only `genai/optimize/optimizers/gepa_optimizer.py`, `genai/judges/optimizers/gepa.py` and their protos and docs (prompt optimisation). ClearML: `automation/optimization.py:1207`, trials sorted by Pareto fronts. DVC, Aim, ZenML: none. No chart in any of them; a case-insensitive search also matches `compareTo…` names, which explains the agent's false positives | +| Label Studio Community has no point clouds | `web/libs/editor/src`, for `lidar`, `pointcloud`, `.pcd` | Confirmed: no file | +| PDEBench's metrics file is not MIT | `pdebench/models/metrics.py`, header | Confirmed: NEC Laboratories Europe copyright header, "All rights reserved" | +| Netron reads pickles with its own reader | `netron/source/python.js:3895` | Confirmed: `registerType('pickle.Unpickler', …)` in JavaScript | +| Argilla adds no new features | `argilla/README.md` | Confirmed: "we won't be adding new features going forward" | +| MLflow has a built-in MCP server | `mlflow/mcp/server.py` | Confirmed | +| The Well renders true / predicted / error videos | `the_well/benchmark/metrics/plottable_data.py:227` | Confirmed: `make_video` | +| PhysicsNeMo's `benchmarks/` times library code | `physicsnemo/benchmarks/` | Confirmed: an ASV-style suite (`run_benchmarks.sh`), no model accuracy | + +Claims about closed products, prices and 2026 company events were not checked again beyond the sources each area cites. They are listed below where they could not be confirmed. + ## 5. Not verified - **Commercial physics platforms:** most capability claims are marketing, especially whether they show error fields and whether they track lineage. From 58226bb5575de808ee1d2f622d188fb0d674552b Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 19 Nov 2026 05:15:07 -0700 Subject: [PATCH 085/131] docs(plan): training views, model structure, generated annotation, curation, comparison, serving and search Co-Authored-By: Claude Opus 5.5 --- docs/plans/training-and-curation/plan.md | 58 ++++++++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 docs/plans/training-and-curation/plan.md diff --git a/docs/plans/training-and-curation/plan.md b/docs/plans/training-and-curation/plan.md new file mode 100644 index 00000000..35d0fefd --- /dev/null +++ b/docs/plans/training-and-curation/plan.md @@ -0,0 +1,58 @@ +# Plan: training views, model structure, generated annotation, curation, comparison, serving and search + +**Status:** approved 2026-11-19 ("I agree"), with the four decisions as recommended. The baseline before this plan is the tag `tuldok-before-training-and-curation`. Embeddings through the Pumas endpoint default to EmbeddingGemma 2 (owner, 2026-11-19: "Set embeddinggemma 2 as the default embbedder for Pumas"). + +**Owner, 2026-11-19:** "Tuldok needs live training views and model structure viwer. … Tuldok also needs a strong set of annotation types … Tuldok centers on generated annotations rather than human made ones … automated/ai segmentors, polygons, depth mapping, image masks, ranking, time series, object tracking, point cloud objects (selecting points that belong to an object), some quality control tools like agreement betwene different models … We should also have serving trained models as a REST endpoint and autologging. … it would be great if it could compare selected models deeper like also showing output results next to eachother. … Tuldok should have curarion by embeddings. … Parallel coordinates sound very usful for Tuldok. Hyperparameter search could be usful … on tiny models localy. We are not going to add a model zoo now." + +And on how Tuldok is built: "I actualy think Tuldoks expectation of projects being made with use created python scripts to be a strength … Tuldok solves larger architectural and the more difficult aspects of a complete end to end model/data workflow." + +## The rule every phase follows + +Tuldok does not grow a generator, a training framework or an annotation model of its own. Each capability is three parts: + +1. **A file contract,** written in `docs/contracts/project-folder.md`: what a project's own script writes into its run's product (a metrics log, a graph, annotations, embeddings), as plain JSON, JSONL, `.npy` or PNG. +2. **A reader and a view in Tuldok:** standard library only, nothing unpickled, nothing of the project's code run inside Tuldok's server, bounded reads, as in the data tools. +3. **A thin optional helper,** `tuldok_log`, a small Python package a project's script may import to write those files in a few lines. It depends on the standard library, and on PyTorch only where it needs a model (graph export, autologging). It lives in the Tuldok repository and is installed into a project's environment like any other dependency; a project may also write the files itself. + +Projects keep writing their own Python (by hand or by an AI). Tuldok supplies the contracts, the orchestration (builds, approval, runs), and the views. + +## Why the structure needs the training code + +The model's structure is defined, as the owner says: it is the Python class that builds the layers and its `forward` method. But that definition is code, and the files Tuldok can read today hold none of it: + +- A weights file (`.npz`, `.safetensors`) is only named arrays: `encoder.0.weight` with its shape and values. It says nothing about which layer feeds which. +- `model.pt` saved with `torch.save(model)` is a pickle that names the class by its import path; loading it runs the project's code. Tuldok never opens a pickle. +- The lab's `model-definition.json` describes the model in the lab's own words (encoder widths 8, 16, 24, 32, bottleneck 48, SiLU, two convolutions a block). That is a good card, but not a graph Tuldok can draw for any project. + +So the graph has to be produced where the code already runs: in the project's environment, by its training script, once, with an example input. PyTorch can do this: `torch.export` (or `torch.fx`) runs the model on an example input and records each operation, its inputs and outputs, their shapes, and the module each came from. `tuldok_log.export_graph(model, example_input)` writes that record as `model-graph.json` next to the weights. Models whose `forward` branches on data values may not export whole; the helper then writes the module tree (layers, nesting, parameters) without the data flow, and says so in the file. + +## Phases + +| # | Phase | Size | Done when | +| --- | --- | --- | --- | +| 1 | **Autologging and live training views.** Contract: `training/metrics.jsonl` (one line per log: step, wall time, any named scalars), `training/histograms.jsonl` (per layer, per N steps: bins of weights and gradients), `training/samples/` (an image or a field every N steps), the checkpoint index. `tuldok_log`: `log(step, **scalars)`, `log_sample(...)`, and `autolog(model, optimizer)` for PyTorch, which records loss, learning rate, gradient norm and histograms without the script naming them. Train tab: a running run's curves drawn live and updated in place, several runs overlaid, smoothing, log scale; histograms over steps per layer; the samples as a strip. A converter for the lab's earlier `history.json` is a lab script, not Tuldok code | Medium | A tiny CPU stand-in run logs through `autolog`; its curves grow on the page while it runs without the page being rebuilt; two finished runs overlay; an earlier lab run's history is shown after the lab's converter runs | +| 2 | **The model structure viewer.** Contract `model-graph.json`: nodes (operation, module path, parameter tensors, input and output shapes, attributes), edges, the module tree. `tuldok_log.export_graph`. In a model's drawer: the graph drawn left to right, modules folded into groups that open, a node's tensors linked to the Weights block; overlays coloured on the graph (parameter count, change against the parent or the starting weights, time per operation when profiled); two models' graphs side by side with matching modules lined up | Medium | A fixture model with nested modules is exported in a test environment with PyTorch and drawn; folding, the weights link and the change overlay work; two variants of one architecture are compared | +| 3 | **Comparing chosen models deeply.** The Map's compare set (two to four models) opens a Compare view: one column per model, rows of what differs (recipe settings, data, parent, kind of change), metrics with confidence intervals, where each sits on the frontier; then the outputs: one case chosen, every model's prediction in a row with the native field and each one's signed error, the same slice and axis for all, moved together. Benchmarks gains parallel coordinates (recipe settings and metrics as axes; a range dragged on an axis keeps the runs inside it) and bootstrap confidence intervals from per-case values, with frontier points marked when their difference is not significant | Medium | On the lab folder three earlier pressure models with kept fields are compared on one case; parallel coordinates over the 150 fits filters to the best errors and shows their settings | +| 4 | **Generated annotation, more kinds, and quality control.** New annotation kinds: polygons, image masks (PNG or run-length), depth maps (`.npy` per image), keypoints, ranking, time-series segments, object tracks (an object's identity across frames or time), point-cloud objects (point indices or per-point instance ids), 3D boxes. Every annotation names what made it (model, version, settings, or a person). An **annotator step**: a project's script, or a model behind the Pumas endpoint, writes annotations for a dataset; people review instead of drawing. Quality control: agreement between annotators, human or model (IoU for masks, polygons, boxes and point sets; rank correlation for rankings; agreement scores for classes), a list of the records where they disagree most, filters by confidence; two annotators shown side by side | Large | On the tiny example, two stand-in "segmentors" annotate the same images and point clouds; their masks and point objects are drawn as overlays; agreement is computed against the test's own arithmetic; the most-disputed records are listed and one is reviewed and kept | +| 5 | **Curation by embeddings.** Contract: an embeddings product (a vector per record, by record id, `.npy` plus an index), made by a project's script or by a model behind the Pumas endpoint (0.8.0 declares `embeddings_float32`). Data tab: a map of the dataset in two dimensions (projection written by the script, or a principal-component projection Tuldok computes for small sets), coloured by any field or annotation; near-duplicates; "more like this"; outliers; thin regions; near-copies across the training and validation splits (leakage). A selection becomes a dataset definition (a subset, or Freeze from it) | Medium | On a fixture with planted duplicates and one leaked validation record, both are found; a selection on the map is frozen into a dataset whose records are exactly those chosen | +| 6 | **Serving a trained model.** A recipe may declare `serve`: the project's own entry point (a script with a `predict` function). Train tab starts and stops it as a local REST endpoint behind Tuldok's credentials, loopback only, on the owner's approval like a build; each request's time is logged, so "the model as served" can be a benchmark subject | Medium | A stand-in model is served, answers a request through Tuldok's endpoint with a credential and refuses one without; its timings appear as a benchmark subject | +| 7 | **Hyperparameter search on this machine.** A `sweep` definition: the recipe it varies, parameters with ranges, a strategy (grid, random, successive halving that stops poor runs early), one or two objectives, a budget (runs, minutes, one at a time). One approval covers the whole budget. Each trial is a recipe on the Map, grouped under the sweep; two objectives give the frontier; parallel coordinates is its main view | Medium | A sweep of a tiny CPU stand-in runs within its budget, stops poor trials early, and its trials appear on the Map, the frontier and parallel coordinates | + +**Order.** Phases 1 and 2 first: they are what the owner named first, and both can be checked now against existing lab runs and tiny stand-ins. Phase 3 next, because it reuses kept fields and serves the two targets directly. Then 4 and 5 (data quality), then 6 and 7. + +**Compute.** Nothing in these phases trains a real model or benchmarks one. Tests use stand-in scripts that finish in seconds on the CPU. Phase 2's graph export needs PyTorch in a test environment (CPU only). Any GPU use waits for the owner's word, as before. + +## Out of scope + +- A model zoo. Later, perhaps, a community hub where people share models and datasets made with Tuldok. +- Distributed or cloud training. +- A built-in data-generation language; projects write scripts. +- A manual annotation editor of Label Studio's breadth: people review generated annotations and correct them, but Tuldok does not aim to be the best drawing tool. +- Video as a record kind. Object tracks work over frames stored as images, or over time in a sequence. + +## Decisions needed + +1. **This plan and its order.** Recommended as written. +2. **Where embeddings come from.** Recommended: both a project's script and the Pumas endpoint. +3. **The `tuldok_log` helper as a package in the Tuldok repository** that projects install. Recommended: yes, kept small; projects may ignore it and write the files themselves. +4. **Serving reachable only from this machine at first.** Recommended: yes; a remote address is a later choice. From 31e6ac175a50c0fcbcd90ae137822a147c26c0c2 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 19 Nov 2026 05:21:16 -0700 Subject: [PATCH 086/131] docs(plan): spec-t2, a model's structure: model-graph.json, export_graph, three reads, the Structure block Co-Authored-By: Claude Opus 5.5 --- docs/plans/training-and-curation/spec-t2.md | 107 ++++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 docs/plans/training-and-curation/spec-t2.md diff --git a/docs/plans/training-and-curation/spec-t2.md b/docs/plans/training-and-curation/spec-t2.md new file mode 100644 index 00000000..31e32b97 --- /dev/null +++ b/docs/plans/training-and-curation/spec-t2.md @@ -0,0 +1,107 @@ +# Implementation spec: a model's structure + +This is phase 2 of [the training and curation plan](plan.md). It follows that plan's rule: a file contract, a reader and a view in Tuldok, and a thin optional helper. The readers follow [spec-d1.md](../definition-first-projects/spec-d1.md) and [spec-d2.md](../definition-first-projects/spec-d2.md): standard library only, nothing unpickled, nothing of the project's code run, nothing written, bounded reads, a damaged file refused and not a failure, reads outside the service lock. The page follows [spec-w4.md](../definition-first-projects/spec-w4.md): nothing is rebuilt by a timer or a return to the window. + +**Owner, 2026-11-19:** "Tuldok needs live training views and model structure viwer." + +**After this phase** a model's drawer shows, beside its Weights, how the model is built: its operations from input to output drawn left to right, its modules as groups that open and close, each operation's tensors linked to the Weights block, the drawing coloured by a figure per module (parameters, output size, how much the weights changed), and the graph of another model lined up with it, module by module. Tuldok draws what the project's training script recorded; it never runs the model. + +## 1. The file: `model-graph.json` + +Written by the project's script, where the model's code already runs, once, with an example input (plan, "Why the structure needs the training code"). It lies at the top of a run's product, or beside one of its weights files (spec-d2 section 1). Plain JSON, UTF-8, at most 32 MiB. + +```json +{"format": "tuldok_model_graph_v1", + "complete": true, "reason": null, "method": "torch.export", + "torch": "2.8.0+cpu", "model": "mypackage.nets.Net", + "inputs": [{"name": "x", "shape": [2, 1, 8, 8], "dtype": "float32"}], + "tensors": {"stem.weight": {"shape": [4, 1, 3, 3], "dtype": "float32", "kind": "parameter"}}, + "nodes": [ + {"id": "x", "kind": "input", "operation": "input", "module": "", "tensors": [], + "inputs": [], "outputs": [{"shape": [2, 1, 8, 8], "dtype": "float32"}], "attributes": {}}, + {"id": "conv2d", "kind": "operation", "operation": "aten.conv2d.default", "module": "stem", + "tensors": ["stem.weight", "stem.bias"], "inputs": [{"shape": [2, 1, 8, 8], "dtype": "float32"}], + "outputs": [{"shape": [2, 4, 8, 8], "dtype": "float32"}], "attributes": {"padding": [1, 1]}}], + "edges": [{"from": "x", "to": "conv2d", "input": 0}], + "modules": {"path": "", "class": "mypackage.nets.Net", "parameters": 1234, "children": [ + {"path": "stem", "class": "torch.nn.modules.conv.Conv2d", "parameters": 40, "children": []}]}, + "notes": []} +``` + +- `format` is `tuldok_model_graph_v1`. `complete` is false when only the module tree could be written; `reason` then says why (a sentence), and `nodes` and `edges` are empty. `method` is `torch.export`, `torch.fx` or `module-tree`. `torch` is the version that wrote it, `model` the class's import path (a name only: Tuldok never imports it). +- `inputs`: the example input's tensors, each `name`, `shape` and `dtype`. +- `tensors`: the model's parameters and buffers by the names of its `state_dict`, the names its weights file uses, each `shape`, `dtype` and `kind` (`parameter` or `buffer`). +- `nodes`, in an order where each node comes after the nodes it reads (the exported graph's order): `id` (unique), `kind` (`input`, `operation` or `output`), `operation` (the operator's name, `aten.conv2d.default`, or for a module traced whole by `torch.fx` the module's class), `module` (the path of the deepest module it ran in, `""` for the model itself), `tensors` (the names in `tensors` it reads), `inputs` and `outputs` (each `shape` and `dtype`, a list since an operation can take or give several; a value that is not a tensor is left out), and `attributes` (at most 16 of its other arguments, by name, each a number, a boolean, a short string, null or a list of at most 16 of those). +- `edges`: `from` a node `to` a node; `input` is the position of the value among the arguments of `to` that are nodes. +- `modules`: the tree of the model's modules from `named_modules`, each `path`, `class` (its import path), `parameters` (every parameter under it, counted once) and `children`. +- `notes`: sentences on what was left out (a truncated graph, an attribute dropped). + +**Bounds,** which the helper keeps and the reader checks: 20,000 nodes, 100,000 edges, 20,000 modules, a module tree at most 64 deep, 100,000 tensors, 64 tensor names and 16 inputs or outputs per node, 16 axes per shape, 1,024 characters per string. A model whose exported graph has more than 20,000 nodes is written as its module tree with `complete` false and the reason. + +## 2. The helper: `tuldok_log.graph.export_graph` + +`tuldok_log` is the small package of the plan (decision 3). Phase 2 adds `tuldok_log/graph.py`; it imports the standard library and, inside `export_graph`, PyTorch. + +`export_graph(model, example_inputs, path)` writes `model-graph.json` at `path` (a file, or a directory to write it in) and returns the dictionary written. + +1. `torch.export.export(model, example_inputs)` (strict off, so a script's own Python is traced as written). Each `call_function` node becomes an operation; its module is the last entry of its `nn_module_stack`; its tensors are the parameters, buffers and constants it reads, by the names of the graph signature (which are the `state_dict` names); its shapes and types come from each node's `meta["val"]` (fake tensors: nothing is computed again). +2. If export fails: `torch.fx.symbolic_trace(model)`, the shapes from running `ShapeProp` once on the example input (a forward pass on the CPU or wherever the inputs are); a `call_module` node is one operation named by its module's class, with that module's tensors. +3. If both fail (a `forward` that branches on data values, say): the module tree only, `complete` false, `reason` naming both errors (their first line, at most 400 characters). + +Never pickles, never imports anything of Tuldok's server, writes with `json.dump` to a temporary file in the same directory and renames it, so a reader never sees half a file. + +## 3. Operations + +Three reads, `inspect`, in `INSIDE_READS` like the others, in the `project_folder` profile and absent from `catalog` (whose digest is unchanged). Each takes `run`. The file is found at the top of the product, else beside the run's weights files (in their order); none is refused `not-found`. + +| Operation | Arguments | Result | +| --- | --- | --- | +| `model_graph` | `depth` (0 to 64, default 1 when the graph has more than 200 operations, else 64), `open` and `close` (module paths, at most 2,000 each) | `path`, `format`, `complete`, `reason`, `method`, `torch`, `model`, `inputs`, `notes`, `depth`, `counts` (`nodes`, `edges`, `operations`, `modules`, `tensors` of the whole file), `modules` (the tree), `tensors`, `open` (the modules open in effect), and the graph folded: `nodes` and `edges` | +| `model_graph_overlay` | `kind`: `parameters`, `outputs`, `operations` or `change`; for `change`, `against`: `start` (the weights file's `initial-` file) or `run` (with `other_run`), and optionally `path` and `other_path` (weights files; default the first readable one) | `kind`, `unit`, `modules` ({path: number or null}), `nodes` ({id: number or null}), `low`, `high` (over the finite numbers of both), and for `change` `against` (`run`, `path`, `other_run`, `other_path`) | +| `model_graph_compare` | `other_run` | `modules`: every module path of either tree, in this tree's order then the other's, each `path`, `status` (`same`, `changed`, `added`: here only, `missing`: there only), `class`, `other_class`, `parameters`, `other_parameters`, `reshaped` (tensors directly in it whose shape differs: `name`, `shape`, `other_shape`), `only_here` and `only_there` (its own tensors on one side); `counts` by status | + +**Folding.** A module's depth is its number of dotted parts (`""` is 0, `blocks` 1, `blocks.0.conv` 3). A module is open when it is in `open`, or when its depth is at most `depth` and it is not in `close`; the model itself is always open. An operation is shown when every module on its path is open; otherwise it is folded into the shallowest module on its path that is closed, shown as one node of kind `group`, id `module:`. Inputs and outputs are always shown. A shown node carries `id`, `kind`, `label`, `module`, `class` (of its module), `operation` (operations), `tensors` (an operation's own; a group's, every tensor its operations read, at most 64, with `tensor_count`), `parameters` (the sum of the sizes of its tensors that are parameters, for a group its module's count), `inputs` and `outputs` (a group's: the values that cross into and out of it, at most 16 each), `operations` (1, or how many a group holds) and `first` (the position in the file of its first node). Shown nodes are in the order of `first`. Edges join the shown nodes of their two ends: an edge inside one group is dropped, edges between the same two shown nodes are one with `count`, and each carries `shape` and `dtype` of the first value it carries. + +**Overlays.** `parameters`: a module's count from the tree; an operation's, the parameters among its tensors. `outputs`: the number of values an operation gives (the product of its outputs' shapes), a module's the sum over the operations in it. `operations`: how many operations run in a module (an operation's is 1). `change`: from `weights_compare` of spec-d2 (its bounds and refusals), the relative change of the tensors under a module (`sqrt(Σ difference_norm²) / sqrt(Σ other_norm²)` over them, the page's layer change of D2b) and of an operation's tensors; null where none is compared, where the other's norm is zero, or where a norm is not finite. "Under a module" means its own tensors and those of every module inside it. + +**Comparing.** Modules are matched by path. `changed`: the class differs, or a tensor directly in it changed shape or is on one side only. A module whose children differ but whose own tensors and class are the same is `same`; its children say what changed. + +**Refusals.** A file that is not UTF-8 JSON, not of the format, missing a key, of a wrong type, past a bound, with a duplicate node id, with an edge naming no node, or with a module tree not rooted at `""` is refused `unsupported` with a sentence saying what (a file over 32 MiB `too-large`). The parsed file is kept (8 files, least recently used dropped) while its size, time and inode are unchanged. + +## 4. The page + +In a model's drawer, a block **Structure** right after Weights, when one of the model's current products has `model-graph.json` (`model_graph` refused `not-found` for all of them: no block at all). + +- **Head:** how it was written (`method`, `torch`), its counts, the example input's shapes; when not `complete`, the reason, and the module tree alone. +- **The drawing,** SVG, no library: left to right, ranks by the longest path from the inputs (an edge back to an earlier node is ignored in ranking and drawn as a curve), each rank's nodes ordered by the barycentre of their neighbours (four sweeps, down and up). Each node a box with its label (operation or module name), its output shape, and a mark for a group (how many operations). In a scrolling box of its own, so a wide graph never widens the drawer. +- **Folding:** a graph of more than 200 operations starts at depth 1, else open. A group pressed opens (one `model_graph`); the module outline under the drawing lists every module with its class and parameters, open or closed, as a tree whose rows open and close the module. "Open all" and "Fold to depth 1". +- **A node pressed** shows its details under the drawing: operation, module and class, inputs and outputs, attributes, and its tensors, each a link that opens that tensor in the Weights block above (its layer opened and scrolled to). +- **Colour by:** nothing, parameters, output size, change from the weights it started from (when kept), change from the model it derives from. The nodes are filled on a sequential scale (logarithmic for counts), a legend gives the ends; a node with no value is left plain. +- **Compare with:** the model it derives from and the models derived from it, when they have a graph. The other's drawing is shown under this one (the drawer is 420 px wide, so the two are stacked, one above the other, folded the same way), and both are marked from `model_graph_compare`: a module added (here only), missing (there only) or changed is outlined and named in a list of the differences. +- Every node is a focusable button (Enter or Space), with a text alternative. Light and dark from the tokens of `base.css`. Read again for the model on screen, the block resolves only once complete, and is put in place in one step with the person's place in it (folding, selection, colour, comparison) kept. + +## 5. Slices + +| | Slice | Files | +| --- | --- | --- | +| T2a | The contract, the helper, the reader and the operations | `docs/contracts/project-folder.md`, `tuldok_log/graph.py` (new), `tuldok_project/inside_graph.py` (new), `operations.py`, `service.py`, `tests/test_tuldok_project_model_graph.py` (new), `tests/test_tuldok_log_graph.py` (new), the count of the table's rows in `tests/test_tuldok_project_service.py` | +| T2b | The Structure block | `static/project-workspace/structure.js` (new), `weights.js` (opening a tensor from outside), `screens.js`, `adapter.js`, `base.css`, `static/project-workspace.html`, `app.py` (the asset list), `tests/browser_project_workspace_structure.cjs` (new), its fixture | + +## 6. Tests + +**T2a, `tests/test_tuldok_project_model_graph.py`,** on graph files the tests write by hand: a graph read whole; folding at depth 0, 1 and full, with `open` and `close`, against counts the test computes (nodes, edges merged with their count, an edge inside a group dropped, a group's crossing values and parameters); each overlay's arithmetic (parameters, outputs, operations, change against a known weights difference, against the start and another run); the comparison (same, changed by class, by shape, added, missing); every refusal (not JSON, wrong format, missing key, duplicate id, dangling edge, a bound lowered for the test, deep nesting); a module-tree-only file; the file found beside the weights; the three in `project_folder`, not in `catalog`, digest unchanged; the committed fixture graphs (written by the helper) read. + +**`tests/test_tuldok_log_graph.py`,** with PyTorch on the CPU, skipped when it is absent: a nested model (a convolution stem, residual blocks of two convolutions with an add, an MLP head) exported whole: every parameter name in a node's `tensors` is in `state_dict`, every `state_dict` name is in `tensors`, the shapes are those of a forward pass, the add has two edges in, the module tree's counts are `sum(p.numel())`; a model whose `forward` branches on a value writes the module tree, `complete` false, with the reason; the file is JSON with no pickle; the node bound (lowered) falls back to the tree. + +**T2b, `tests/browser_project_workspace_structure.cjs`,** on fixture products for a parent and a derived model (graphs written by the helper once and committed as test data, weights written with the standard library, the derived one with `initial-weights.npz`), owner signed in, no GPU, no PyTorch: + +1. The derived model's drawer shows Structure after Weights, with the file's counts and the drawing; a model without a graph has no block. +2. Pressing a group opens it in place (more nodes, one `model_graph`, nothing else in the drawer rebuilt); the outline closes it again. +3. A node pressed shows its details; its tensor link opens that layer in the Weights block. +4. Colour by parameters and by change: the nodes' fills change and differ between nodes. +5. Compare with the parent: the changed and added modules are marked, as `model_graph_compare` says. +6. Light and dark, 1440 and 390 wide: no sideways overflow of the drawer or the page, no script error, no failed request; nothing redrawn on a return to the window. + +## 7. Out of scope + +Running the model, activations, profiling time per operation (a later field `seconds` on a node; nothing writes it yet), ONNX or TorchScript files, graphs of frameworks other than PyTorch, editing a model's structure, drawing more than two graphs at once. From 36365df3a38618249866736ff3d442574c649d66 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 19 Nov 2026 05:22:17 -0700 Subject: [PATCH 087/131] docs(plan): spec of phase 1, autologging and live training views Co-Authored-By: Claude Opus 5.5 --- docs/plans/training-and-curation/spec-t1.md | 176 ++++++++++++++++++++ 1 file changed, 176 insertions(+) create mode 100644 docs/plans/training-and-curation/spec-t1.md diff --git a/docs/plans/training-and-curation/spec-t1.md b/docs/plans/training-and-curation/spec-t1.md new file mode 100644 index 00000000..a857a444 --- /dev/null +++ b/docs/plans/training-and-curation/spec-t1.md @@ -0,0 +1,176 @@ +# Implementation spec: autologging and live training views + +This is phase 1 of [the training and curation plan](plan.md), and it follows "The rule every phase follows": a file contract, a reader and a view in Tuldok, and a thin optional helper, `tuldok_log`. The rules of the data tools apply to the reader ([spec-d1.md](../definition-first-projects/spec-d1.md), [spec-d2.md](../definition-first-projects/spec-d2.md), [spec-d6.md](../definition-first-projects/spec-d6.md)): standard library only, nothing unpickled, nothing of the project's code run inside Tuldok's server, nothing written, bounded reads, a damaged line or file refused or reported and never a failure, reads outside the service lock. The page follows [spec-w4.md](../definition-first-projects/spec-w4.md): it updates in place, and nothing is rebuilt by a timer or a return to the window. + +**Owner, 2026-11-19:** "Tuldok needs live training views … We should also have … autologging." And on how Tuldok is built: projects write their own Python scripts; Tuldok supplies the contracts, the orchestration and the views. + +**After this phase** a project's training script writes a few plain files into its run's output directory while it trains, by hand or through `tuldok_log` (three lines with `autolog`). On the Train tab, the drawer of a run shows its curves while it runs, growing in place every two seconds, with other runs overlaid, smoothing and a log scale; the distributions of each layer's weights and gradients over the steps as small heat strips; and the samples the script kept, as a strip. Nothing trains a real model; nothing reads the lab's runs. + +## 1. Rules + +- **The script writes, Tuldok reads.** Tuldok never runs the project's code, never imports it, never opens a pickle. `tuldok_log` is imported by the project's script in the project's environment, never by Tuldok's server. +- **A running run is readable.** The training files are read from a run's output directory whatever its state, as soon as the run has a directory: queued with none yet answers "nothing logged"; running, succeeded, adopted, failed, cancelled or timed out are read alike (a failed run's curves are often what one most wants to see). The other reads inside a product (spec-d1) still need a finished run. +- **Files are appended while they are read.** A reader takes only complete lines (ending in a newline); a partial last line is left for the next read. A file that became shorter, or another file under the same name, is read again from its start. +- **Bounded.** Every read has a bound on bytes, lines, series and points (section 4), and long series are reduced on the server before they are sent. +- **Cheap when nothing changed.** What has been read of a file is kept in memory with its offset, so reading again reads only what was appended since. + +## 2. The contract: `training/` in a run's output directory + +Everything is under `training/` at the top of the run's output (`{output}/training/`). Every file is optional; a run with no `training/` has nothing logged. JSON is UTF-8, one object per line (JSON Lines), and Python's `NaN`, `Infinity` and `-Infinity` are read as non-finite. + +### 2.1 `training/metrics.jsonl` + +One object per log: + +```json +{"step": 120, "time": 14.2, "epoch": 3, "loss": 0.0213, "lr": 0.001, "grad_norm": 0.84, "val/loss": 0.031} +``` + +- `step`: required, an integer ≥ 0. Steps normally increase; they need not (a resumed run may log a step again), and the page draws points in the order of the file. +- `time`: required, seconds since the run started (a finite number ≥ 0). +- `epoch`: optional, a number. +- **Every other key whose value is a number is a scalar series** named by the key (1 to 200 characters). `null` or a non-finite number is a gap in that series, counted as `nonfinite`. A key absent from a line is no point of that series (a validation loss logged every hundred steps is a series of its own with fewer points). +- Keys whose value is not a number (a string, an object, a boolean) are kept as the line has them and listed by name as `other_keys`; they are not series. +- A line that is not such an object (not JSON, no integer `step`, no `time`) is counted and its line number reported; the rest are read. + +### 2.2 `training/histograms.jsonl` + +One object per tensor per log: + +```json +{"step": 100, "time": 12.1, "name": "encoder.0.weight", "kind": "weights", "edges": [-0.5, -0.4, …, 0.5], "counts": [3, 11, …, 2]} +``` + +- `step` and `time` as above; `name` (1 to 1,000 characters): the tensor; `kind`: `weights` or `gradients`. +- `edges`: n + 1 finite numbers, not decreasing; `counts`: n numbers ≥ 0 (counts of values in each bin; the last bin includes its upper edge). 1 ≤ n ≤ 1,024. +- Optional `nonfinite`: values left out because they were not finite. + +### 2.3 `training/samples/` and `training/samples.jsonl` + +What the model made every N steps, so one can watch it learn: an image (PNG) or an array (`.npy`, the forms spec-d1 reads). Each file is written whole under `training/samples/` (written to a temporary name and renamed, by `tuldok_log`), named by its step and name: `samples/000000120-prediction.png`. Then one line is appended to `training/samples.jsonl`: + +```json +{"step": 120, "time": 14.2, "name": "prediction", "path": "samples/000000120-prediction.png"} +``` + +`path` is relative to `training/`, a plain address under `samples/` (no `..`, no `!`). The kind follows the extension: `.png` (also `.jpg`, `.jpeg`, `.webp`) is an image; `.npy` is an array. A line naming a file that is missing is listed with that problem. + +### 2.4 `training/checkpoints.jsonl` and how the checkpoint index relates + +The project-folder format has no checkpoint index today: a run's final weights are its declared outputs (role `weights`, or found by name, spec-d2), and the earlier CLI's `checkpoint` role names one output. A script that keeps checkpoints during the run may list them here, one line each: + +```json +{"step": 1000, "time": 120.5, "path": "checkpoints/step-1000.safetensors", "loss": 0.012} +``` + +`path` is relative to the run's output directory. The other numeric keys are figures of that checkpoint. Tuldok lists them and marks their steps on the curves; it does not open them here (the Weights block of the model's drawer reads the run's final weights as before). + +### 2.5 `training/training.json` + +Optional, written once by `tuldok_log` at the start: `{"format": "tuldok_training_v1", "started_at": "", "helper": "tuldok_log 1"}`. A reader shows `started_at`; nothing depends on it. + +### 2.6 The earlier lab runs + +The lab's earlier runs keep their history in `history.json`, in the lab's own form. Converting it into `training/metrics.jsonl` is a **lab script**, not Tuldok code, and it is deferred: this phase writes nothing into the lab repository or into any run's product. Until it exists, those runs show "nothing logged". + +## 3. `tuldok_log` + +A package at the top of the Tuldok repository, `tuldok_log/`, installed into a project's environment like any dependency (or put on its path). Standard library only; PyTorch is imported only inside `autolog`, and the helpers that take a model or a tensor use the object's own methods (`named_parameters`, `detach`, `histc`) without importing anything. + +```python +from tuldok_log import Logger, autolog + +log = Logger(output) # writes into /training/ +log.log(step, loss=0.21, lr=1e-3) # one metrics line; epoch=... optional +log.log_histograms(step, model) # weights and gradients of every parameter; or tensors={"name": values} +log.log_sample(step, "prediction", png_bytes_or_array) +log.checkpoint(step, "checkpoints/step-1000.safetensors", loss=0.012) + +track = autolog(model, optimizer, directory=output, every=10, loss=criterion) +``` + +- `Logger(directory)`: the run's output directory; creates `training/` and writes `training.json` when it is absent. Its clock starts when it is made. Every line is written with one `write` call on a file opened for appending, so a reader sees whole lines or none (a partial line at worst while the write lands). `close()` and a context manager. +- `log(step, *, epoch=None, **scalars)`: values are converted with `float()`; a value that is not finite is written as `null`. +- `log_histograms(step, model=None, *, tensors=None, kinds=('weights', 'gradients'), bins=32, most=64)`: for a model, every parameter (the first `most`) and its gradient when it has one; for `tensors`, a mapping of name to values (a nested list, an object with `tolist()`, or a tensor). Histograms are computed by the tensor's own `histc` when it has one, else in Python. +- `log_sample(step, name, value)`: `bytes` beginning with the PNG signature are written as a `.png`; an object with `__array_interface__` or `dtype`/`shape`/`tobytes` (a NumPy array), a tensor (`detach().cpu()`), or a nested list of numbers is written as an `.npy` of its numeric type (float32 for a list). Written to a temporary name, renamed, then indexed. +- `autolog(model, optimizer, *, directory=None, logger=None, every=50, histograms_every=None, loss=None, bins=32)`: registers the optimizer's step hooks (PyTorch 2.0 or later). Each optimizer step counts one step. Every `every` steps it writes one metrics line with the learning rate (`lr`, or `lr/` for several parameter groups), the gradient norm over all parameters before the step (`grad_norm`) and, when it knows it, the loss: the mean of the losses seen since the last line. It knows the loss when `loss` is the loss module (a forward hook reads its output) or when the script calls `track.note(loss=…)` (any named scalars). Every `histograms_every` steps (default: `every`) it writes the histograms of the weights and of the gradients. `track.close()` removes the hooks. The script names none of these. + +## 4. Operations + +Five reads, `inspect`, in the `project_folder` profile and absent from `catalog` (whose digest is unchanged). Each takes `run`; a run with no directory answers as having nothing logged (`training`) or `not-found` (the others). + +| Operation | Arguments | Result | +| --- | --- | --- | +| `training` | none besides `run` | `run` (`id`, `state`, `active`), `present` (whether `training/` exists), `started_at`, `series` (each: `name`, `points`, `nonfinite`, `first_step`, `last_step`, `last`, `min`, `max`), `lines` (complete metrics lines read), `last_step`, `last_time`, `other_keys`, `histograms` (each: `name`, `kind`, `rows`, `first_step`, `last_step`), `histogram_lines`, `samples` (each name with `count` and `last_step`), `sample_lines`, `checkpoints` (the last 200: `step`, `time`, `path`, figures), `problems` (the first 20: `file`, `line`, `problem`), `bad_lines`, `truncated` | +| `training_series` | `series`: up to 16 of `{name, size, since}`; `most` (default 1,000, at most 4,000) | `series`: each `name`, `points`, `nonfinite`, `size`, `first`, `buckets`; `lines` | +| `training_histograms` | `name`, `kind`, `most` (rows, default 120, at most 500), `bins` (default 48, at most 128) | `name`, `kind`, `rows` (each `step`, `time`), `stride`, `low`, `high`, `bins`, `counts` (row by row, re-binned), `nonfinite` | +| `training_samples` | `name`, `offset`, `limit` (at most 200) | `samples` (each `index`, `step`, `time`, `name`, `path`, `kind`, `bytes`, `problem`; an image's `url`), `total` (of that name, or all) | +| `training_sample` | `index` | `sample` (as above) and `content`: for an image `width`, `height`, `url`; for an array a slice as `array_slice` answers it (the last two axes, at most 128 by 128) | + +**Reduced series.** A series of `n` points is sent in buckets of `size` consecutive points, `size` the smallest power of two for which there are at most `most` buckets (1 while `n ≤ most`). A bucket is `[first_step, last_step, last_time, mean, min, max]` over its finite values (`mean`, `min`, `max` null when it has none). The bucket boundaries depend only on `size`, so the page keeps what it has: it sends the `size` it holds and `since`, the bucket it wants from (its count less one, since the last may have grown); when the server's `size` is the same it answers from `since` (`first`), otherwise from 0, and the page replaces what it held. A live run thus sends a few buckets a reading. + +**Histograms over steps.** The rows are the tensor's logs, evenly chosen when there are more than `most` (the first and the last always among them). Every row is re-binned onto `bins` equal bins over the lowest and highest edge of the chosen rows, a bin's count shared out by overlap (as if spread evenly inside it); `counts` are the shares, not rounded. + +**Images of a running run.** `GET /api/project/file` serves a file under `training/` of any run that has a directory, as it serves a finished product's files (same checks: inside the output directory, no `..`). + +## 5. Bounds + +| | Bound | Beyond it | +| --- | --- | --- | +| A line of `metrics.jsonl`, `samples.jsonl`, `checkpoints.jsonl` | 64 KiB | counted as a bad line | +| A line of `histograms.jsonl` | 256 KiB | counted as a bad line | +| Lines of `metrics.jsonl` kept | 1,000,000 | later lines not read, `truncated` | +| Series | 200 | later names not kept, reported once | +| Lines of `histograms.jsonl` indexed | 1,000,000 | `truncated` | +| Tensor and kind pairs | 2,000 | later pairs not kept, reported once | +| Bins of one histogram line | 1,024 | a bad line | +| Lines of `samples.jsonl` and of `checkpoints.jsonl` | 100,000 and 10,000 | `truncated` | +| Files kept in memory | 16, least recently used dropped | read again from the start when asked again | + +A histogram line is kept as its offset and length only; its bins are read again when a strip is drawn. + +## 6. The page + +In the run's drawer on the Train tab, a block **Training**, after "Latest progress", when the run has a directory. A run with nothing logged shows one line that says so, and how a script logs (`tuldok_log`), and nothing else. + +- **Curves.** A chart (canvas 2D, no library) of the chosen series against the step (or the time since the run started). A chooser of series (the run's series, `loss` first when there is one; up to four shown). Controls: **Smoothing** (a slider, 0 to 0.99, exponential moving average over the drawn buckets; the raw line stays faint behind), **Log scale** (values ≤ 0 left out, said under the chart), **Step / Time**. When a series is reduced, the band between each bucket's min and max is shaded. Checkpoints are ticks on the step axis. Hover shows the step, the time and the value of each line at that step. +- **Overlay.** "Compare with" lists the other runs of the project (newest first, those of the same model first); each run added is drawn in its own colour, with a legend of run, model and state; a run is removed from its chip. Up to four runs. +- **Histograms.** Under the curves, for each tensor (weights, and gradients when logged; a switch between the two), a heat strip: steps across, bins down, each column's counts as shares of its own total so a narrowing distribution shows. The first eight tensors are drawn; "Show all" draws the rest. Each strip is read when it comes on screen. +- **Samples.** A strip of the last twelve samples of the chosen name (a select when there are several), newest last, with the step under each; an array is drawn as an image with `inside.js`'s colour ramp. +- **Live, in place.** While the run is active, every reading of the page (every two seconds, spec-w4 R7) asks `training` once; when its `lines` grew, `training_series` for the shown series from where the page is (appending buckets); when `histogram_lines` grew, the strips on screen are read again; when `sample_lines` grew, the new samples. The canvases are drawn again and new samples appended; **the block is never rebuilt** by a reading, and a reading that found nothing new touches no element. A run's answers are kept by the page while it is open, so the drawer drawn again (the run ended) puts the block back without "Reading…" and without reading the series again. +- **The address** keeps the overlay and the settings: `trWith` (run ids), `trSeries`, `trSmooth`, `trLog`, `trX`. +- Light and dark from the page's tokens; at 390 wide the controls wrap and the chart fills the drawer. + +## 7. Slices + +| | Slice | Files | +| --- | --- | --- | +| T1a | The contract text, the reader, the five operations, the file route | `docs/contracts/project-folder.md`, `tuldok_project/training.py` (new), `operations.py`, `service.py`, `tests/test_tuldok_project_training.py` (new), and the tests that count the project-folder operations | +| T1b | `tuldok_log` | `tuldok_log/__init__.py` (new), `tests/test_tuldok_log.py` (new) | +| T1c | The Training block | `static/project-workspace/training.js` (new), `tabs.js` (the run's drawer), `adapter.js`, `app.js` (the address, the reading), `base.css`, `app.py` and `static/project-workspace.html` (the asset), `tests/browser_project_workspace_training.cjs` (new) | + +## 8. Tests + +**T1a, `tests/test_tuldok_project_training.py`,** files written by the test: + +- `training` on a run with no `training/`; on a metrics file with several series, a gap (`null`, `NaN`), a key that is not a number, a bad line, a line too long; on a file whose last line is partial (not counted), then completed by an append (counted); on a file replaced by a shorter one (read again). +- `training_series` against the test's arithmetic: raw points while `n ≤ most`; buckets of a power of two beyond, with mean, min and max per bucket; `since` with the same size answers only the later buckets; with a different size from 0; the bound on lines (lowered for the test). +- `training_histograms`: two rows with different edges re-binned onto one grid, the totals kept; row choice past `most`, first and last kept; a damaged line counted. +- `training_samples` and `training_sample`: a PNG (its size), an `.npy` (its slice), a missing file, a path with `..`. +- A running run (state `running`) is read; a queued run without directory answers nothing logged; the file route serves `training/` of a running run and not its other files. +- The five are in `project_folder` and absent from `catalog`; the catalog digest is unchanged. + +**T1b, `tests/test_tuldok_log.py`:** `Logger` writes lines the reader reads back (series, gaps as `null`, histograms from lists, samples PNG and `.npy` and the index); every line is whole; `autolog` with PyTorch on the CPU (a tiny model, ten steps, `every=2`): metrics lines with `loss`, `lr`, `grad_norm`; weights and gradients histograms for every parameter; the hooks removed by `close()`. Skipped when PyTorch is not importable; run with the lab's interpreter, which has it (read only, nothing installed). + +**T1c, `tests/browser_project_workspace_training.cjs`,** in a headless browser, the owner signed in, no GPU: a fixture with two finished runs of a small stand-in script that logs through `tuldok_log` (built before the server starts), and a third run of the same script for about ten seconds, asked for and run while the page watches: + +1. The running run's drawer shows Training; its curve grows across readings (more points drawn, the last step larger) while a marker set on the block survives and no node of the block is added or removed by a reading. +2. The two finished runs overlaid: three lines and a legend of three. +3. Smoothing, log scale and Step / Time change the drawing (another image), the block the same element. +4. Histograms drawn (non-blank strips, one per tensor shown) and samples drawn (images loaded, steps under them). +5. Nothing is touched by a return to the window with the finished run open. +6. Light and dark, 1440 and 390 wide: no sideways overflow, no script error, no failed request. + +## 9. Out of scope + +A lab converter of `history.json` (a lab script, deferred); TensorBoard event files or any other format; logging from inside Tuldok's server; text or audio samples; comparing histograms of two runs; alerts on a diverging run; the Analysis or Benchmarks tabs; any change to how runs are started or to the lab's runs. From f441788bba8d85dbf3e542ff4ae7b6ebb4d27df4 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 19 Nov 2026 05:27:58 -0700 Subject: [PATCH 088/131] feat(project): read what a training script logged, while it runs training/metrics.jsonl, histograms.jsonl, samples.jsonl and checkpoints.jsonl of a run's output, read incrementally whatever the run's state: whole lines only, long series in power-of-two buckets, histograms re-binned onto one grid. Five inspect reads in the project_folder profile; the file route serves training/ of a running run. Catalog digest unchanged. Co-Authored-By: Claude Opus 5.5 --- docs/contracts/project-folder.md | 69 +++ tests/test_tuldok_project_service.py | 9 +- tests/test_tuldok_project_training.py | 392 ++++++++++++++++ tuldok_project/operations.py | 34 ++ tuldok_project/service.py | 46 +- tuldok_project/training.py | 650 ++++++++++++++++++++++++++ 6 files changed, 1195 insertions(+), 5 deletions(-) create mode 100644 tests/test_tuldok_project_training.py create mode 100644 tuldok_project/training.py diff --git a/docs/contracts/project-folder.md b/docs/contracts/project-folder.md index e922414a..3da8b57a 100644 --- a/docs/contracts/project-folder.md +++ b/docs/contracts/project-folder.md @@ -2285,6 +2285,11 @@ and result keys of each operation are in its contract. | `array_tiles` | inspect | Read tiles of two axes of an array in a finished run's product, one per position along a third axis, as 32-bit floats. | | `fields` | inspect | List the fields a finished run's product kept: each case's native and predicted files, its name, shape and whether the two can be compared, and the figures the run reported itself. | | `field_compare` | inspect | Read a slice of one kept case's native field, predicted field and signed error as 32-bit floats, with the figures of the error over the whole field. | +| `training` | inspect | List what a run's training script logged, while it runs or after: its scalar series, the tensors whose histograms it kept, its samples and checkpoints, and the lines it could not read. | +| `training_series` | inspect | Read scalar series a run's training script logged, in buckets of a power of two points (mean, least and greatest), from the bucket the caller holds when its bucket size is the same. | +| `training_histograms` | inspect | Read one tensor's histograms of weights or gradients over the steps of a run's training, re-binned onto one grid. | +| `training_samples` | inspect | List one page of the samples a run's training script kept, optionally of one name. | +| `training_sample` | inspect | Read one sample a run's training script kept: an image's size and address, or an array's slice as 32-bit floats. | | `set_definition` | edit | Check a definition's text and keep it as an unsaved edit. | | `remove_definition` | edit | Mark a definition that nothing uses as removed, until the project is saved. | | `revert_definition` | edit | Put back the file in the folder in place of a definition's unsaved edit or removal, or drop a definition the folder has no file for. | @@ -2721,6 +2726,70 @@ floats with `math.fsum` and `math.sumprod`; a figure that would overflow is null, as all of them are when no cell counts. A case's figures are kept while its files are unchanged, so asking for another slice reads only the slice. +### What a training script logged + +A run's own script may log its training into `training/` of its output +directory (`{output}/training/`), by hand or through the helper `tuldok_log` +(the package of that name at the top of the Tuldok repository, standard +library only, PyTorch only for `autolog`). Every file is optional. Tuldok +reads them; it never runs, imports or unpickles anything of the project's. +Unlike the reads above, these read a run **in any state** that has a +directory, while it runs as well as after: a file being appended to is read +up to its last complete line (a partial last line is left for the next read), +and what has been read is kept with its offset, so reading again reads only +what was appended. A file that became shorter, or was replaced, is read again +from its start. JSON is UTF-8, one object per line; `NaN` and `Infinity` are +read as non-finite. + +- **`training/metrics.jsonl`**, one line per log: + `{"step": 120, "time": 14.2, "epoch": 3, "loss": 0.0213, "lr": 0.001}`. + `step` an integer of 0 or more, `time` seconds since the run started (0 or + more) are required; `epoch` is optional. Every other key whose value is a + number is a scalar series of that name (1 to 200 characters); `null` or a + non-finite number is a gap, counted as `nonfinite`. Keys whose value is not + a number are kept and listed by name (`other_keys`), not drawn. +- **`training/histograms.jsonl`**, one line per tensor per log: + `{"step": 100, "time": 12.1, "name": "encoder.0.weight", "kind": "weights", "edges": […], "counts": […]}`. + `kind` is `weights` or `gradients`; `edges` n + 1 finite numbers in order, + `counts` n numbers of 0 or more, 1 ≤ n ≤ 1,024; optional `nonfinite`. +- **`training/samples.jsonl`** and the files under `training/samples/`: one + line per sample, `{"step": 120, "time": 14.2, "name": "prediction", "path": "samples/000000120-prediction.png"}`, + `path` relative to `training/` and under `samples/`. A `.png`, `.jpg`, + `.jpeg` or `.webp` is an image; an `.npy` an array (read as `array_slice` + reads one). A sample's file is written whole before its line. +- **`training/checkpoints.jsonl`**: `{"step": 1000, "time": 120.5, "path": "checkpoints/step-1000.safetensors", "loss": 0.012}`, + `path` relative to the output directory; the other numeric keys are the + checkpoint's figures. Listed and marked on the curves, not opened. A run's + final weights are still its declared outputs (see [A model's weights](#a-models-weights)). +- **`training/training.json`**: `{"format": "tuldok_training_v1", "started_at": ""}`, shown. + +A line that is not as above is counted (`bad_lines`) and reported with its +file and number (the first 20, `problems`); the rest are read. Bounds: 64 KiB +a line (256 KiB in `histograms.jsonl`), 1,000,000 metrics lines and 1,000,000 +histogram lines (`truncated` beyond), 200 series, 2,000 tensor and kind +pairs, 100,000 samples, 10,000 checkpoints. + +| Operation | Arguments | Result | +| --- | --- | --- | +| `training` | `run` | `run` (`id`, `state`, `active`), `present`, `started_at`, `series` (`name`, `points`, `nonfinite`, `first_step`, `last_step`, `last`, `min`, `max`), `lines`, `last_step`, `last_time`, `other_keys`, `histograms` (`name`, `kind`, `rows`, `first_step`, `last_step`), `histogram_lines`, `samples` (`name`, `count`, `last_step`), `sample_lines`, `checkpoints` (the last 200), `problems`, `bad_lines`, `truncated` | +| `training_series` | `run`, `series` (1 to 16 of `{name, size, since}`), `most` (default 1,000, at most 4,000) | `series` (`name`, `points`, `nonfinite`, `size`, `first`, `buckets`), `lines` | +| `training_histograms` | `run`, `name`, `kind`, `most` (rows, default 120, at most 500), `bins` (default 48, at most 128) | `name`, `kind`, `rows` (`step`, `time`), `stride`, `low`, `high`, `bins`, `counts`, `totals`, `nonfinite` | +| `training_samples` | `run`, `name`, `offset`, `limit` (at most 200) | `samples` (`index`, `step`, `time`, `name`, `path`, `kind`, `bytes`, `problem`, and `url` for an image), `total` | +| `training_sample` | `run`, `index` | `sample` and `content`: an image's `width`, `height` and `url`; an array's slice (the last two axes, at most 128 by 128) as `array_slice` answers | + +A series of n points is sent in **buckets** of `size` consecutive points, +`size` the smallest power of two that makes at most `most` buckets (1 while +n ≤ `most`); a bucket is `[first_step, last_step, last_time, mean, min, max]` +of its finite values (null when it has none). A caller that holds buckets +sends the `size` it holds and `since`; when the size is still the same the +answer begins at bucket `since` (`first`), otherwise at 0. A tensor's +histogram rows are chosen evenly past `most` (the first and the last kept), +and each is re-binned onto `bins` equal bins between the lowest and highest +edge of the chosen rows, a bin's count shared by overlap. A run with no +directory answers `training` with `present` false and the other four +`not-found`. `GET /api/project/file` serves a file under `training/` of a run +in any state that has a directory; any other file only of a finished run. + ### Annotating The five operations on annotations (see [Annotations in the database](#annotations-in-the-database)) diff --git a/tests/test_tuldok_project_service.py b/tests/test_tuldok_project_service.py index 536697a1..f07046f7 100644 --- a/tests/test_tuldok_project_service.py +++ b/tests/test_tuldok_project_service.py @@ -48,7 +48,7 @@ class Table(unittest.TestCase): def test_every_operation_is_declared_once(self): names = [operation.name for operation in operations.OPERATIONS] - self.assertEqual(len(names), 61) # the rows of spec-m7.md section 2, of section 2 of spec-w1.md and spec-w3.md, of section 3 of spec-d1.md and spec-d2.md, of section 5 of spec-d4.md, of sections 2 and 4 of spec-d5.md, and of section 2 of spec-d6.md + self.assertEqual(len(names), 66) # the rows of spec-m7.md section 2, of section 2 of spec-w1.md and spec-w3.md, of section 3 of spec-d1.md and spec-d2.md, of section 5 of spec-d4.md, of sections 2 and 4 of spec-d5.md, of section 2 of spec-d6.md, and of section 4 of training-and-curation/spec-t1.md self.assertEqual(len(set(names)), len(names)) for name in REQUEST_OPERATIONS: self.assertIsNotNone(operations.by_name(name)) @@ -215,6 +215,9 @@ def test_every_read(self): 'other_path': 'weights.json'}, 'array_tiles': {'run': run_id, 'path': 'weights.npy'}, 'fields': {'run': run_id}, 'field_compare': {'run': run_id, 'entry': 0, 'case': 0}, + 'training': {'run': run_id}, 'training_series': {'run': run_id, 'series': [{'name': 'loss'}]}, + 'training_histograms': {'run': run_id, 'name': 'w', 'kind': 'weights'}, + 'training_samples': {'run': run_id}, 'training_sample': {'run': run_id, 'index': 0}, 'annotation_tasks': {}, 'annotated_records': {'task': 'none-here'}, 'annotation': {'task': 'none-here', 'record': 'r1'}, 'endpoint': {}, 'find_endpoints': {}, 'suggestion_models': {'task': 'none-here'}, @@ -232,6 +235,10 @@ def test_every_read(self): # test_tuldok_project_inside and test_tuldok_project_weights self.assertEqual(self.refused(operation.name, arguments[operation.name]).code, 'not-found') continue + if operation.name in ('training_histograms', 'training_sample'): # fit-a logged nothing; + # test_tuldok_project_training + self.assertEqual(self.refused(operation.name, arguments[operation.name]).code, 'not-found') + continue if operation.name == 'field_compare': # fit-a keeps no fields; test_tuldok_project_fields self.assertEqual(self.refused(operation.name, arguments[operation.name]).code, 'not-found') continue diff --git a/tests/test_tuldok_project_training.py b/tests/test_tuldok_project_training.py new file mode 100644 index 00000000..2bc56450 --- /dev/null +++ b/tests/test_tuldok_project_training.py @@ -0,0 +1,392 @@ +"""What a training script logged, read while it is written (docs/plans/training-and-curation/spec-t1.md, slice T1a). + +The readers are tested on files the tests write with the standard library and +need no database. The operations need one and run only when +TULDOK_DATABASE_URL names a disposable cluster: they build recipes/fit-a (as +test_tuldok_project_builds does), write training files into its run's output, +and read them with the run marked running and queued. No GPU is used. +""" +import hashlib +import json +import math +import os +from pathlib import Path +import sys +import tempfile +import unittest +from unittest import mock + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) +sys.path.insert(0, str(Path(__file__).resolve().parent)) + +import agent_api # noqa: E402 +from tuldok_project import builds, local, operations, store, training # noqa: E402 +from tuldok_project.service import Service # noqa: E402 +import test_tuldok_project_builds as builds_base # noqa: E402 +from test_tuldok_project_inside import OWNER, floats, npy, png # noqa: E402 + +TRAINING = ('training', 'training_series', 'training_histograms', 'training_samples', 'training_sample') + + +def line(value): + return (json.dumps(value) + '\n').encode() + + +class TrainingCase(unittest.TestCase): + + def setUp(self): + directory = tempfile.TemporaryDirectory() + self.addCleanup(directory.cleanup) + self.root = os.path.realpath(directory.name) + os.makedirs(os.path.join(self.root, 'training', 'samples')) + training.forget() + self.addCleanup(training.forget) + self.run = training.Run('run-1', 'running', self.root) + + def path(self, name): + return os.path.join(self.root, 'training', name) + + def append(self, name, data): + with open(self.path(name), 'ab') as handle: + handle.write(data) + + def overview(self): + got = training.overview(self.run) + json.dumps(got, allow_nan=False) + return got + + def series(self, *wanted, most=1000): + got = training.series(self.run, [w if isinstance(w, dict) else {'name': w} for w in wanted], most=most) + json.dumps(got, allow_nan=False) + return got + + def refused(self, code, call, *arguments, **options): + with self.assertRaises(store.ProjectError) as caught: + call(*arguments, **options) + self.assertEqual(caught.exception.code, code, str(caught.exception)) + + +class Metrics(TrainingCase): + + def test_nothing_logged(self): + got = training.overview(training.Run('run-2', 'queued', None)) + self.assertEqual((got['present'], got['series'], got['lines'], got['run']['active']), (False, [], 0, True)) + os.rmdir(os.path.join(self.root, 'training', 'samples')) + os.rmdir(os.path.join(self.root, 'training')) + self.assertFalse(self.overview()['present']) + self.refused('not-found', training.series, training.Run('run-2', 'queued', None), [{'name': 'loss'}]) + + def test_series_gaps_other_keys_and_bad_lines(self): + self.append('metrics.jsonl', b''.join([ + line({'step': 0, 'time': 0.5, 'epoch': 0, 'loss': 2.0, 'lr': 0.1, 'note': 'warm-up'}), + line({'step': 1, 'time': 1.0, 'loss': None, 'lr': 0.1}), + b'{"step": 2, "time": 1.5, "loss": NaN, "lr": 0.1, "val/loss": 3.0}\n', + b'not json\n', + line({'step': -1, 'time': 2.0, 'loss': 1.0}), + line({'step': 3, 'loss': 1.0}), + line([1, 2]), + line({'step': 4, 'time': 2.5, 'loss': 1.0, 'lr': 0.05, 'flag': True, 'big': 10 ** 400}), + b'\n', + b'{"step": 5, "time": 3.0, "loss": 0.5' + b' ' * (training.LINE_BYTES + 10) + b'}\n', + ])) + got = self.overview() + by = {s['name']: s for s in got['series']} + self.assertEqual(list(by), ['loss', 'lr', 'val/loss', 'big']) + self.assertEqual((by['loss']['points'], by['loss']['nonfinite'], by['loss']['min'], by['loss']['max'], + by['loss']['last'], by['loss']['last_step']), (4, 2, 1.0, 2.0, 1.0, 4)) + self.assertEqual((by['lr']['points'], by['lr']['last']), (4, 0.05)) + self.assertEqual((by['val/loss']['points'], by['val/loss']['first_step']), (1, 2)) + self.assertEqual((by['big']['nonfinite'], by['big']['last']), (1, None)) + self.assertEqual(got['other_keys'], ['note', 'flag']) + self.assertEqual((got['lines'], got['last_step'], got['last_time']), (4, 4, 2.5)) + self.assertEqual(got['bad_lines'], 5) + self.assertEqual([p['line'] for p in got['problems']], [4, 5, 6, 7, 10]) + self.assertTrue(all(p['file'] == 'training/metrics.jsonl' for p in got['problems'])) + [loss] = self.series('loss')['series'] + self.assertEqual(loss['buckets'], [[0, 0, 0.5, 2.0, 2.0, 2.0], [1, 1, 1.0, None, None, None], + [2, 2, 1.5, None, None, None], [4, 4, 2.5, 1.0, 1.0, 1.0]]) + self.assertEqual(self.series('missing')['series'][0]['points'], 0) + + def test_a_partial_last_line_waits_for_its_end(self): + self.append('metrics.jsonl', line({'step': 0, 'time': 0.0, 'loss': 1.0}) + b'{"step": 1, "time": 0.1, "lo') + got = self.overview() + self.assertEqual((got['lines'], got['bad_lines']), (1, 0)) + self.append('metrics.jsonl', b'ss": 0.5}\n' + line({'step': 2, 'time': 0.2, 'loss': 0.25})) + got = self.overview() + self.assertEqual((got['lines'], got['bad_lines'], got['series'][0]['last']), (3, 0, 0.25)) + self.assertEqual([b[3] for b in self.series('loss')['series'][0]['buckets']], [1.0, 0.5, 0.25]) + + def test_a_line_too_long_while_it_is_written(self): + self.append('metrics.jsonl', line({'step': 0, 'time': 0.0, 'loss': 1.0}) + b'{"x": "' + + b'a' * (training.LINE_BYTES + 1)) + self.assertEqual(self.overview()['bad_lines'], 1) + self.append('metrics.jsonl', b'a' * 100 + b'"}\n' + line({'step': 1, 'time': 0.1, 'loss': 0.5})) + got = self.overview() + self.assertEqual((got['lines'], got['bad_lines'], got['series'][0]['points']), (2, 1, 2)) + + def test_a_file_replaced_or_shortened_is_read_again(self): + self.append('metrics.jsonl', b''.join(line({'step': i, 'time': i, 'loss': i}) for i in range(5))) + self.assertEqual(self.overview()['lines'], 5) + with open(self.path('metrics.jsonl'), 'wb') as handle: # the same inode, shorter + handle.write(line({'step': 0, 'time': 0, 'loss': 9.0})) + got = self.overview() + self.assertEqual((got['lines'], got['series'][0]['last']), (1, 9.0)) + replacement = self.path('other') + with open(replacement, 'wb') as handle: # another file, longer + handle.write(b''.join(line({'step': i, 'time': i, 'acc': i}) for i in range(7))) + os.replace(replacement, self.path('metrics.jsonl')) + got = self.overview() + self.assertEqual(([s['name'] for s in got['series']], got['lines']), (['acc'], 7)) + + def test_buckets_of_a_long_series_and_since(self): + values = [math.sin(i / 7) * 10 + i for i in range(1000)] + self.append('metrics.jsonl', b''.join(line({'step': 10 * i, 'time': i / 4, 'loss': v}) + for i, v in enumerate(values))) + [raw] = self.series('loss', most=1000)['series'] + self.assertEqual((raw['size'], len(raw['buckets'])), (1, 1000)) + self.assertEqual([b[3] for b in raw['buckets']], values) + [got] = self.series('loss', most=100)['series'] + self.assertEqual((got['size'], got['first'], len(got['buckets'])), (16, 0, 63)) + for number, bucket in enumerate(got['buckets']): + part = values[number * 16:(number + 1) * 16] + self.assertEqual(bucket[:3], [10 * number * 16, 10 * (number * 16 + len(part) - 1), + (number * 16 + len(part) - 1) / 4]) + self.assertAlmostEqual(bucket[3], math.fsum(part) / len(part), places=12) + self.assertEqual(bucket[4:], [min(part), max(part)]) + # The page holds 63 buckets of 16; more points arrive; it asks from its last one. + self.append('metrics.jsonl', b''.join(line({'step': 10 * i, 'time': i / 4, 'loss': float(i)}) + for i in range(1000, 1020))) + [more] = self.series({'name': 'loss', 'size': 16, 'since': 62}, most=100)['series'] + self.assertEqual((more['size'], more['first'], len(more['buckets']), more['points']), (16, 62, 2, 1020)) + self.assertEqual(more['buckets'][-1][1], 10190) + # Past 1,600 points the size doubles: the page is sent everything again, from 0. + self.append('metrics.jsonl', b''.join(line({'step': 10 * i, 'time': i / 4, 'loss': 1.0}) + for i in range(1020, 1700))) + [again] = self.series({'name': 'loss', 'size': 16, 'since': 63}, most=100)['series'] + self.assertEqual((again['size'], again['first'], len(again['buckets'])), (32, 0, 54)) + self.assertEqual(training.bucket_size(0, 10), 1) + self.assertEqual(training.bucket_size(11, 10), 2) + + def test_the_bound_on_lines(self): + with mock.patch.object(training._Metrics, 'line_most', 3): + self.append('metrics.jsonl', b''.join(line({'step': i, 'time': i, 'loss': i}) for i in range(6))) + got = self.overview() + self.assertEqual((got['lines'], got['truncated']), (3, True)) + + def test_the_bound_on_series(self): + with mock.patch.object(training, 'SERIES', 2): + self.append('metrics.jsonl', line({'step': 0, 'time': 0, 'a': 1, 'b': 2, 'c': 3})) + got = self.overview() + self.assertEqual([s['name'] for s in got['series']], ['a', 'b']) + self.assertEqual((got['bad_lines'], len(got['problems'])), (0, 1)) + + def test_a_file_outside_the_output_is_not_read(self): + outside = tempfile.NamedTemporaryFile('wb', delete=False) + self.addCleanup(os.unlink, outside.name) + outside.write(line({'step': 0, 'time': 0, 'secret': 1})) + outside.close() + os.symlink(outside.name, self.path('metrics.jsonl')) + self.assertEqual(self.overview()['series'], []) + + +class Histograms(TrainingCase): + + def histogram(self, step, edges, counts, name='layer.weight', kind='weights', **extra): + self.append('histograms.jsonl', line({'step': step, 'time': step / 10, 'name': name, 'kind': kind, + 'edges': edges, 'counts': counts, **extra})) + + def test_rows_re_binned_onto_one_grid(self): + self.histogram(0, [0.0, 1.0, 2.0], [4, 6]) + self.histogram(10, [1.0, 3.0, 4.0], [10, 2], nonfinite=3) + self.histogram(10, [0.0, 1.0], [5], kind='gradients') + self.append('histograms.jsonl', b'{"step": 1}\n' + line({'step': 1, 'time': 0, 'name': 'x', 'kind': 'weights', + 'edges': [1, 0], 'counts': [1]})) + got = self.overview() + self.assertEqual([(h['name'], h['kind'], h['rows'], h['last_step']) for h in got['histograms']], + [('layer.weight', 'weights', 2, 10), ('layer.weight', 'gradients', 1, 10)]) + self.assertEqual((got['histogram_lines'], got['bad_lines']), (3, 2)) + h = training.histograms(self.run, name='layer.weight', kind='weights', bins=4) + json.dumps(h, allow_nan=False) + self.assertEqual((h['low'], h['high'], h['bins'], h['stride'], h['nonfinite']), (0.0, 4.0, 4, 1, 3)) + self.assertEqual(h['rows'], [{'step': 0, 'time': 0.0}, {'step': 10, 'time': 1.0}]) + self.assertEqual(h['counts'], [[4.0, 6.0, 0.0, 0.0], [0.0, 5.0, 5.0, 2.0]]) + self.assertEqual(h['totals'], [10.0, 12.0]) + h = training.histograms(self.run, name='layer.weight', kind='weights', bins=8) + self.assertEqual(h['counts'][0], [2.0, 2.0, 3.0, 3.0, 0.0, 0.0, 0.0, 0.0]) + self.refused('not-found', training.histograms, self.run, name='nothing', kind='weights') + + def test_rows_chosen_past_most_keep_the_first_and_the_last(self): + for step in range(50): + self.histogram(step, [0.0, 1.0], [step]) + h = training.histograms(self.run, name='layer.weight', kind='weights', most=7, bins=2) + steps = [row['step'] for row in h['rows']] + self.assertEqual((len(steps), steps[0], steps[-1], h['stride']), (7, 0, 49, 49 / 6)) + self.assertEqual(steps, sorted(set(steps))) + + def test_rebin_keeps_the_total(self): + counts = training.rebin([-1.0, -0.3, 0.2, 0.9, 0.9, 2.5], [3, 5, 7, 2, 11], -1.0, 2.5, 7) + self.assertAlmostEqual(math.fsum(counts), 28.0, places=12) + self.assertEqual(training.rebin([1.0, 1.0], [4], 1.0, 1.0, 5), [0.0, 0.0, 4.0, 0.0, 0.0]) + + +class Samples(TrainingCase): + + def sample(self, step, name, path, data=None): + if data is not None: + with open(os.path.join(self.root, 'training', path), 'wb') as handle: + handle.write(data) + self.append('samples.jsonl', line({'step': step, 'time': step / 10, 'name': name, 'path': path})) + + def test_images_arrays_missing_files_and_bad_paths(self): + self.sample(10, 'prediction', 'samples/000000010-prediction.png', png(5, 3)) + self.sample(10, 'field', 'samples/000000010-field.npy', npy((2, 3), ' 0 else -math.inf + + +def _finite(value): + number = _number(value) + return number if number is not None and math.isfinite(number) else None + + +def _step(value): + return value if isinstance(value, int) and not isinstance(value, bool) and value >= 0 else None + + +# ------------------------------------------------------------------ reading a file that grows + +class _Log: + """One file read incrementally: whole lines only, from where the last read stopped.""" + + line_limit = LINE_BYTES + line_most = METRICS_LINES + + def __init__(self, path, label): + self.path, self.label = path, label + self.lock = threading.Lock() + self._start() + + def _start(self): + self.identity, self.offset, self.number, self.skipping = None, 0, 0, False + self.bad, self.problems, self.truncated = 0, [], False + self.reset() + + def reset(self): + """Forgets what was read (a subclass's own state).""" + + def take(self, value, number, start, length): + """Keeps one decoded line; returns a sentence saying why it is refused, or None.""" + raise NotImplementedError + + def problem(self, number, text, bad=True): + self.bad += bad + if len(self.problems) < PROBLEMS: + self.problems.append({'file': f'{DIRECTORY}/{self.label}', 'line': number, 'problem': text}) + + def refresh(self): + """Reads what was appended since the last read (all of it after a change of file); call with lock held.""" + try: + stat = os.stat(self.path) + except OSError: + if self.identity is not None: + self._start() + return + identity = (stat.st_dev, stat.st_ino) + if identity != self.identity or stat.st_size < self.offset: + self._start() + self.identity = identity + if stat.st_size == self.offset or self.truncated: + return + with open(self.path, 'rb') as handle: + handle.seek(self.offset) + pending = b'' + while True: + chunk = handle.read(CHUNK) + if not chunk: + break + pending += chunk + start = 0 + while True: + end = pending.find(b'\n', start) + if end < 0: + break + self._line(pending[start:end], self.offset) + self.offset += end - start + 1 + start = end + 1 + if self.truncated: + return + pending = pending[start:] + if len(pending) > self.line_limit: # a line too long: skip its bytes up to its newline + if not self.skipping: + self.number += 1 + self.problem(self.number, f'The line is longer than {self.line_limit} bytes.') + self.skipping = True + self.offset += len(pending) + pending = b'' + + def _line(self, raw, start): + if self.skipping: # the end of a line too long, already counted + self.skipping = False + return + self.number += 1 + if self.number > self.line_most: + self.truncated = True + return + if not raw.strip(): + return + if len(raw) > self.line_limit: + self.problem(self.number, f'The line is longer than {self.line_limit} bytes.') + return + try: + value = json.loads(raw.decode('utf-8')) + except (UnicodeDecodeError, ValueError, RecursionError): + self.problem(self.number, 'The line is not JSON.') + return + if not isinstance(value, dict): + self.problem(self.number, 'The line is not a JSON object.') + return + wrong = self.take(value, self.number, start, len(raw)) + if wrong: + self.problem(self.number, wrong) + + +class _Metrics(_Log): + def reset(self): + self.steps, self.times, self.epochs = array('q'), array('d'), array('d') + self.series = {} # name -> (array of line positions, array of values) + self.nonfinite = collections.Counter() + self.stats = {} # name -> [min, max, last] of its finite values + self.other_keys = [] + self.dropped = set() + + def take(self, value, number, start, length): + step, time = _step(value.get('step')), _finite(value.get('time')) + if step is None: + return 'It has no step (an integer of 0 or more).' + if time is None or time < 0: + return 'It has no time (seconds since the run started, 0 or more).' + epoch = _finite(value.get('epoch')) + at = len(self.steps) + self.steps.append(step) + self.times.append(time) + self.epochs.append(math.nan if epoch is None else epoch) + for key, item in value.items(): + if key in _RESERVED: + continue + number = None if item is None else _number(item) + if item is not None and number is None: + if key not in self.other_keys and len(self.other_keys) < OTHER_KEYS: + self.other_keys.append(key) + continue + held = self.series.get(key) + if held is None: + if not key or len(key) > NAME_CHARACTERS: + continue + if len(self.series) >= SERIES: + if key not in self.dropped: + self.dropped.add(key) + self.problem(number, f'More than {SERIES} series: {key[:80]} is not kept.', bad=False) + continue + held = self.series[key] = (array('q'), array('d')) + if number is None or not math.isfinite(number): + self.nonfinite[key] += 1 + number = math.nan + else: + stats = self.stats.get(key) + if stats is None: + self.stats[key] = [number, number, number] + else: + stats[0], stats[1], stats[2] = min(stats[0], number), max(stats[1], number), number + held[0].append(at) + held[1].append(number) + return None + + +class _Histograms(_Log): + line_limit = HISTOGRAM_LINE_BYTES + line_most = HISTOGRAM_LINES + + def reset(self): + self.pairs = {} # (name, kind) -> (steps, times, offsets, lengths) + self.dropped = set() + + def take(self, value, number, start, length): + wrong = histogram_problem(value) + if wrong: + return wrong + key = (value['name'], value['kind']) + held = self.pairs.get(key) + if held is None: + if len(self.pairs) >= PAIRS: + if key not in self.dropped: + self.dropped.add(key) + self.problem(number, f'More than {PAIRS} tensors: {key[0][:80]} ({key[1]}) is not kept.', + bad=False) + return None + held = self.pairs[key] = (array('q'), array('d'), array('q'), array('q')) + held[0].append(value['step']) + held[1].append(_finite(value.get('time')) or 0.0) + held[2].append(start) + held[3].append(length) + return None + + +def histogram_problem(value): + """A sentence saying why value is not a histogram line, or None.""" + if _step(value.get('step')) is None: + return 'It has no step (an integer of 0 or more).' + name = value.get('name') + if not isinstance(name, str) or not name or len(name) > TENSOR_CHARACTERS: + return f'It has no name (1 to {TENSOR_CHARACTERS} characters).' + if value.get('kind') not in KINDS: + return 'Its kind is not weights or gradients.' + edges, counts = value.get('edges'), value.get('counts') + if not isinstance(edges, list) or not isinstance(counts, list) or not 1 <= len(counts) <= BINS \ + or len(edges) != len(counts) + 1: + return f'It needs edges (n + 1 numbers) and counts (n numbers), 1 to {BINS} bins.' + previous = -math.inf + for edge in edges: + number = _finite(edge) + if number is None or number < previous: + return 'Its edges are not finite numbers in order.' + previous = number + for count in counts: + number = _finite(count) + if number is None or number < 0: + return 'Its counts are not numbers of 0 or more.' + return None + + +class _Samples(_Log): + line_most = SAMPLE_LINES + + def reset(self): + self.entries = [] # dicts: step, time, name, path, kind + + def take(self, value, number, start, length): + step, name, path = _step(value.get('step')), value.get('name'), value.get('path') + if step is None: + return 'It has no step (an integer of 0 or more).' + if not isinstance(name, str) or not name or len(name) > NAME_CHARACTERS: + return f'It has no name (1 to {NAME_CHARACTERS} characters).' + if not isinstance(path, str) or not path.startswith('samples/') or '!' in path or '\\' in path \ + or any(part in ('', '.', '..') for part in path.split('/')): + return 'Its path is not a plain address under samples/.' + extension = os.path.splitext(path.lower())[1] + kind = 'image' if extension in IMAGE_EXTENSIONS else 'array' if extension in ARRAY_EXTENSIONS else None + if kind is None: + return 'Its file is not a PNG, JPEG or WebP image or an .npy array.' + self.entries.append({'step': step, 'time': _finite(value.get('time')), 'name': name, 'path': path, + 'kind': kind}) + return None + + +class _Checkpoints(_Log): + line_most = CHECKPOINT_LINES + + def reset(self): + self.entries = [] + + def take(self, value, number, start, length): + step, path = _step(value.get('step')), value.get('path') + if step is None: + return 'It has no step (an integer of 0 or more).' + if not isinstance(path, str) or not path or len(path) > 4096: + return 'It has no path.' + entry = {'step': step, 'time': _finite(value.get('time')), 'path': path} + entry['figures'] = {key: _finite(item) for key, item in value.items() + if key not in ('step', 'time', 'path') and _number(item) is not None} + self.entries.append(entry) + return None + + +_CLASSES = {METRICS: _Metrics, HISTOGRAMS: _Histograms, SAMPLES: _Samples, CHECKPOINTS: _Checkpoints} +_kept_lock = threading.Lock() +_kept = collections.OrderedDict() # (real path of the file, its class) -> _Log + + +def forget(): + """Forgets every file read (the tests).""" + with _kept_lock: + _kept.clear() + + +def _path(run, name): + """The real path of training/ under the run's output, or None when it has none or it lies outside.""" + if run.root is None: + return None + full = os.path.realpath(os.path.join(run.root, DIRECTORY, name)) + if not full.startswith(run.root + os.sep) or not os.path.isfile(full): + return None + return full + + +class _Read: + """The state of one file of a run, refreshed, with its lock held for the block.""" + + def __init__(self, run, name): + self.run, self.name, self.log = run, name, None + + def __enter__(self): + path = _path(self.run, self.name) + if path is None: + return None + key = (path, self.name) + with _kept_lock: + log = _kept.get(key) + if log is None: + log = _kept[key] = _CLASSES[self.name](path, self.name) + _kept.move_to_end(key) + while len(_kept) > FILES_KEPT: + _kept.popitem(last=False) + log.lock.acquire() + self.log = log + try: + log.refresh() + except OSError: + log._start() + return log + + def __exit__(self, *exc): + if self.log is not None: + self.log.lock.release() + return False + + +def _started(run): + path = _path(run, STARTED) + if path is None: + return None + try: + with open(path, 'rb') as handle: + value = json.loads(handle.read(STARTED_BYTES).decode('utf-8')) + except (OSError, UnicodeDecodeError, ValueError, RecursionError): + return None + if isinstance(value, dict) and value.get('format') == STARTED_FORMAT and isinstance(value.get('started_at'), str): + return value['started_at'][:64] + return None + + +# ----------------------------------------------------------------------------- operations + +def overview(run): + """The operation training: what the run logged, by series, tensor, sample name and checkpoint.""" + present = run.root is not None and os.path.isdir(os.path.join(run.root, DIRECTORY)) + result = {'run': {'id': run.run_id, 'state': run.state, 'active': run.active}, 'present': present, + 'started_at': _started(run) if present else None, 'series': [], 'lines': 0, 'last_step': None, + 'last_time': None, 'other_keys': [], 'histograms': [], 'histogram_lines': 0, 'samples': [], + 'sample_lines': 0, 'checkpoints': [], 'problems': [], 'bad_lines': 0, 'truncated': False} + if not present: + return result + problems = [] + with _Read(run, METRICS) as log: + if log is not None: + for name, (at, values) in log.series.items(): + low, high, last = log.stats.get(name, (None, None, None)) + result['series'].append({'name': name, 'points': len(values), 'nonfinite': log.nonfinite[name], + 'first_step': log.steps[at[0]] if at else None, + 'last_step': log.steps[at[-1]] if at else None, 'last': last, + 'min': low, 'max': high}) + result['lines'] = len(log.steps) + if log.steps: + result['last_step'], result['last_time'] = log.steps[-1], log.times[-1] + result['other_keys'] = list(log.other_keys) + _gather(result, problems, log) + with _Read(run, HISTOGRAMS) as log: + if log is not None: + for (name, kind), (steps, _times, _offsets, _lengths) in log.pairs.items(): + result['histograms'].append({'name': name, 'kind': kind, 'rows': len(steps), + 'first_step': steps[0], 'last_step': steps[-1]}) + result['histogram_lines'] = sum(len(held[0]) for held in log.pairs.values()) + _gather(result, problems, log) + with _Read(run, SAMPLES) as log: + if log is not None: + names = collections.OrderedDict() + for entry in log.entries: + held = names.setdefault(entry['name'], {'name': entry['name'], 'count': 0, 'last_step': None}) + held['count'] += 1 + held['last_step'] = entry['step'] + result['samples'] = list(names.values()) + result['sample_lines'] = len(log.entries) + _gather(result, problems, log) + with _Read(run, CHECKPOINTS) as log: + if log is not None: + result['checkpoints'] = [dict(entry, figures=dict(entry['figures'])) + for entry in log.entries[-CHECKPOINTS_SHOWN:]] + _gather(result, problems, log) + result['problems'] = problems[:PROBLEMS] + return result + + +def _gather(result, problems, log): + result['bad_lines'] += log.bad + result['truncated'] = result['truncated'] or log.truncated + problems.extend(log.problems) + + +def series(run, wanted, *, most=1000): + """The operation training_series: each wanted series ({name, size, since}) in buckets, from since when the + page holds buckets of the same size.""" + answer = {'series': [], 'lines': 0} + with _Read(run, METRICS) as log: + if log is None: + if run.root is None: + raise ProjectError(f'Run {run.run_id} has no output directory yet.', 'not-found') + for item in wanted: + answer['series'].append(_empty(item['name'])) + return answer + answer['lines'] = len(log.steps) + for item in wanted: + held = log.series.get(item['name']) + if held is None: + answer['series'].append(_empty(item['name'])) + continue + answer['series'].append(_bucketed(log, item['name'], held, item.get('size', 0), item.get('since', 0), + most)) + return answer + + +def _empty(name): + return {'name': name, 'points': 0, 'nonfinite': 0, 'size': 1, 'first': 0, 'buckets': []} + + +def bucket_size(points, most): + """The smallest power of two for which points make at most most buckets.""" + size = 1 + while (points + size - 1) // size > most: + size *= 2 + return size + + +def _bucketed(log, name, held, size_held, since, most): + at, values = held + points = len(values) + size = bucket_size(points, most) + count = (points + size - 1) // size + first = min(since, count) if size_held == size else 0 + buckets = [] + for number in range(first, count): + low, high = number * size, min(points, (number + 1) * size) + finite = [value for value in values[low:high] if not math.isnan(value)] + if finite: + mean = math.fsum(finite) / len(finite) + if not math.isfinite(mean): # the sum overflowed + mean = math.fsum(value / len(finite) for value in finite) + low_value, high_value = min(finite), max(finite) + else: + mean = low_value = high_value = None + buckets.append([log.steps[at[low]], log.steps[at[high - 1]], log.times[at[high - 1]], mean, low_value, + high_value]) + return {'name': name, 'points': points, 'nonfinite': log.nonfinite[name], 'size': size, 'first': first, + 'buckets': buckets} + + +def _chosen(count, most): + """Positions of count rows, evenly chosen when there are more than most; the first and the last kept.""" + if count <= most: + return list(range(count)), 1 + if most == 1: + return [count - 1], count + picked = sorted({round(i * (count - 1) / (most - 1)) for i in range(most)}) + return picked, (count - 1) / (most - 1) + + +def histograms(run, *, name, kind, most=120, bins=48): + """The operation training_histograms: one tensor's histograms over the steps, re-binned onto one grid.""" + with _Read(run, HISTOGRAMS) as log: + held = log.pairs.get((name, kind)) if log is not None else None + if held is None: + raise ProjectError(f'Run {run.run_id} logged no histograms of the {kind} of {name}.', 'not-found') + steps, times, offsets, lengths = held + positions, stride = _chosen(len(steps), most) + rows = [] + with open(log.path, 'rb') as handle: + for position in positions: + handle.seek(offsets[position]) + raw = handle.read(lengths[position]) + try: + value = json.loads(raw.decode('utf-8')) + except (UnicodeDecodeError, ValueError, RecursionError): + value = None + if not isinstance(value, dict) or histogram_problem(value) or value['name'] != name \ + or value['kind'] != kind: + continue # the file changed under the index: the next read finds it + rows.append((steps[position], times[position], [float(e) for e in value['edges']], + [float(c) for c in value['counts']], _finite(value.get('nonfinite')) or 0)) + if not rows: + raise ProjectError(f'The histograms of {name} could not be read again; ask again.', 'unsupported') + low = min(row[2][0] for row in rows) + high = max(row[2][-1] for row in rows) + counts = [rebin(edges, row_counts, low, high, bins) for _s, _t, edges, row_counts, _n in rows] + return {'name': name, 'kind': kind, 'rows': [{'step': s, 'time': t} for s, t, *_rest in rows], + 'stride': stride, 'low': low, 'high': high, 'bins': bins, 'counts': counts, + 'totals': [math.fsum(row[3]) for row in rows], 'nonfinite': sum(row[4] for row in rows)} + + +def rebin(edges, counts, low, high, bins): + """counts over edges shared out onto bins equal bins over [low, high] by overlap (spread evenly in a bin).""" + target = [0.0] * bins + width = (high - low) / bins + if not width > 0 or not math.isfinite(width): + target[bins // 2] = math.fsum(counts) + return target + + def at(x): + return min(bins - 1, max(0, int((x - low) / width))) + + for index, count in enumerate(counts): + if not count: + continue + a, b = edges[index], edges[index + 1] + if not b > a: + target[at(a)] += count + continue + first, last = at(a), at(b) + if first == last: + target[first] += count + continue + for place in range(first, last + 1): + left = max(a, low + place * width) + right = min(b, low + (place + 1) * width) if place < bins - 1 else b + if right > left: + target[place] += count * (right - left) / (b - a) + return target + + +def _sample_shown(run, entry, index): + address = f'{DIRECTORY}/{entry["path"]}' + shown = dict(entry, index=index, bytes=None, problem=None) + path = _path(run, entry['path']) + if path is None: + shown['problem'] = 'The file is missing.' + return shown + try: + shown['bytes'] = os.path.getsize(path) + except OSError: + shown['problem'] = 'The file is missing.' + return shown + if entry['kind'] == 'image': + shown['url'] = inside.file_url(run.run_id, address) + return shown + + +def samples(run, *, name=None, offset=0, limit=50): + """The operation training_samples: one page of the samples, of one name or all.""" + with _Read(run, SAMPLES) as log: + if log is None: + if run.root is None: + raise ProjectError(f'Run {run.run_id} has no output directory yet.', 'not-found') + return {'samples': [], 'total': 0} + chosen = [(index, entry) for index, entry in enumerate(log.entries) if name is None or entry['name'] == name] + return {'samples': [_sample_shown(run, entry, index) for index, entry in chosen[offset:offset + limit]], + 'total': len(chosen)} + + +@inside.reading +def _sample_content(product, run, shown): + address = f'{DIRECTORY}/{shown["path"]}' + if shown['kind'] == 'image': + content = inside_shapes.image_content(locate(product.root, address)) + content['url'] = shown['url'] + return content + return inside.array_slice(product, path=address, most=SAMPLE_SLICE) + + +def sample(run, *, index): + """The operation training_sample: one sample with its content (an image's size, an array's slice).""" + with _Read(run, SAMPLES) as log: + entry = log.entries[index] if log is not None and index < len(log.entries) else None + if entry is None: + raise ProjectError(f'Run {run.run_id} logged no sample {index}.', 'not-found') + shown = _sample_shown(run, entry, index) + if shown['problem']: + raise ProjectError(f'Sample {index} of run {run.run_id}: {shown["problem"]}', 'not-found') + return {'sample': shown, 'content': _sample_content(run.product(), run, shown)} From f26ceb010a9cb41788d576b4dd843b5d8f4320e3 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 19 Nov 2026 05:28:57 -0700 Subject: [PATCH 089/131] feat(tuldok_log): a small helper that writes the training files, with autolog for PyTorch Logger(directory).log / log_histograms / log_sample / checkpoint, standard library only; autolog(model, optimizer) records loss, learning rate, gradient norm and histograms through optimizer step hooks. PyTorch imported only there. Co-Authored-By: Claude Opus 5.5 --- tests/test_tuldok_log.py | 267 ++++++++++++++++++++++++++ tuldok_log/__init__.py | 393 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 660 insertions(+) create mode 100644 tests/test_tuldok_log.py create mode 100644 tuldok_log/__init__.py diff --git a/tests/test_tuldok_log.py b/tests/test_tuldok_log.py new file mode 100644 index 00000000..7fd4db66 --- /dev/null +++ b/tests/test_tuldok_log.py @@ -0,0 +1,267 @@ +"""tuldok_log writes the training files Tuldok reads (docs/plans/training-and-curation/spec-t1.md, slice T1b). + +The Logger is tested with the standard library and read back with Tuldok's own +reader (tuldok_project.training) when it can be imported. autolog needs +PyTorch and is skipped when it cannot be imported; Tuldok's environment has no +PyTorch, so run this file with an interpreter that has it (on the CPU) to +cover it, for example the lab's: + + /.venv/bin/python -m unittest tests/test_tuldok_log.py + +There the reader may not be importable (its database driver is absent); the +lines are then checked as JSON against the contract by this file itself. +""" +import json +import math +import os +from pathlib import Path +import struct +import sys +import tempfile +import threading +import unittest +import zlib + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) + +import tuldok_log # noqa: E402 + +try: + from tuldok_project import training as reader +except ImportError: # an interpreter without Tuldok's own requirements + reader = None +try: + import torch +except ImportError: + torch = None + + +def png(width, height): + def chunk(kind, data): + return struct.pack('>I', len(data)) + kind + data + struct.pack('>I', zlib.crc32(kind + data)) + rows = b''.join(b'\x00' + b'\x10\x20\x30' * width for _ in range(height)) + return (b'\x89PNG\r\n\x1a\n' + chunk(b'IHDR', struct.pack('>IIBBBBB', width, height, 8, 2, 0, 0, 0)) + + chunk(b'IDAT', zlib.compress(rows)) + chunk(b'IEND', b'')) + + +def lines(path): + raw = Path(path).read_bytes() + assert raw.endswith(b'\n'), 'every line is whole' + return [json.loads(text) for text in raw.decode('utf-8').splitlines()] + + +def npy_values(data): + """(descr, shape, values) of a little-endian .npy of version 1 written by tuldok_log.""" + assert data[:8] == b'\x93NUMPY\x01\x00' + length = struct.unpack('= 0 for c in counts)) + return None if ok else 'not a histogram line' + + +class LoggerCase(unittest.TestCase): + + def setUp(self): + directory = tempfile.TemporaryDirectory() + self.addCleanup(directory.cleanup) + self.output = directory.name + self.files = os.path.join(self.output, 'training') + if reader is not None: + reader.forget() + + def test_metrics_with_gaps_and_the_start(self): + with tuldok_log.Logger(self.output) as log: + log.log(0, loss=2.5, lr=0.1) + log.log(1, epoch=0, loss=float('nan'), lr=0.1, acc=None) + log.log(2, loss=float('inf'), extra=3) + with self.assertRaises(ValueError): + log.log(3, time=1.0) + got = lines(os.path.join(self.files, 'metrics.jsonl')) + self.assertEqual([(g['step'], g.get('loss'), g.get('epoch')) for g in got], + [(0, 2.5, None), (1, None, 0.0), (2, None, None)]) + self.assertTrue(all(isinstance(g['time'], float) and g['time'] >= 0 for g in got)) + self.assertEqual(got[1]['acc'], None) + started = json.loads(Path(self.files, 'training.json').read_text()) + self.assertEqual(started['format'], 'tuldok_training_v1') + if reader is not None: + run = reader.Run('r', 'running', self.output) + seen = reader.overview(run) + self.assertEqual(seen['started_at'], started['started_at']) + self.assertEqual({s['name']: (s['points'], s['nonfinite']) for s in seen['series']}, + {'loss': (3, 2), 'lr': (2, 0), 'acc': (1, 1), 'extra': (1, 0)}) + self.assertEqual(seen['bad_lines'], 0) + + def test_histograms_from_lists_and_objects(self): + class Values: # an object with tolist(), as an array is + def tolist(self): + return [[0.0, 1.0], [2.0, 3.0]] + with tuldok_log.Logger(self.output) as log: + log.log_histograms(5, tensors={'a': [0.0, 0.5, 1.0, 1.0, float('nan')], 'b': Values(), 'c': [7.0, 7.0], + 'd': [float('nan')]}, bins=4) + got = lines(os.path.join(self.files, 'histograms.jsonl')) + self.assertEqual([g['name'] for g in got], ['a', 'b', 'c']) + a, b, c = got + self.assertEqual((a['edges'], a['counts'], a['nonfinite']), ([0.0, 0.25, 0.5, 0.75, 1.0], [1, 0, 1, 2], 1)) + self.assertEqual((b['counts'], b['kind'], b['step']), ([1, 1, 1, 1], 'weights', 5)) + self.assertEqual((c['edges'][0], c['edges'][-1], sum(c['counts'])), (6.5, 7.5, 2)) + self.assertTrue(all(contract_histogram(g) is None for g in got)) + if reader is not None: + h = reader.histograms(reader.Run('r', 'running', self.output), name='a', kind='weights', bins=4) + self.assertEqual(h['counts'], [[1.0, 0.0, 1.0, 2.0]]) + + def test_samples_png_and_arrays(self): + with tuldok_log.Logger(self.output) as log: + first = log.log_sample(10, 'prediction', png(3, 2)) + second = log.log_sample(10, 'field map', [[1, 2, 3], [4, 5, 6]]) + with self.assertRaises(ValueError): + log.log_sample(11, 'bad', b'not a png') + with self.assertRaises(ValueError): + log.log_sample(11, 'ragged', [[1, 2], [3]]) + self.assertEqual((first, second), ('samples/000000010-prediction.png', 'samples/000000010-field_map.npy')) + self.assertEqual(Path(self.files, first).read_bytes(), png(3, 2)) + self.assertEqual(npy_values(Path(self.files, second).read_bytes()), + ('/training/. + + directory is the run's output directory (the {output} a recipe's command is + given). The clock (each line's time) starts when the Logger is made. + """ + + def __init__(self, directory): + self.directory = os.path.join(os.fspath(directory), DIRECTORY) + os.makedirs(os.path.join(self.directory, 'samples'), exist_ok=True) + self._start = time.monotonic() + self._lock = threading.Lock() + self._files = {} + started = os.path.join(self.directory, STARTED) + if not os.path.exists(started): + stamp = datetime.datetime.now(datetime.timezone.utc).isoformat(timespec='seconds') + self._replace(started, json.dumps({'format': FORMAT, 'started_at': stamp, + 'helper': 'tuldok_log ' + __version__}).encode('utf-8') + b'\n') + + # ---------------------------------------------------------------- plumbing + + def elapsed(self): + """Seconds since the Logger was made.""" + return round(time.monotonic() - self._start, 6) + + def _append(self, name, value): + data = _line(value) + with self._lock: + fd = self._files.get(name) + if fd is None: + fd = self._files[name] = os.open(os.path.join(self.directory, name), + os.O_WRONLY | os.O_APPEND | os.O_CREAT, 0o644) + written = os.write(fd, data) + while written < len(data): # a short write is rare on a regular file; finish the line + written += os.write(fd, data[written:]) + + @staticmethod + def _replace(path, data): + temporary = f'{path}.{os.getpid()}.{threading.get_ident()}.part' + with open(temporary, 'wb') as handle: + handle.write(data) + os.replace(temporary, path) + + def close(self): + with self._lock: + for fd in self._files.values(): + os.close(fd) + self._files.clear() + + def __enter__(self): + return self + + def __exit__(self, *exc): + self.close() + return False + + # ----------------------------------------------------------------- metrics + + def log(self, step, *, epoch=None, **scalars): + """One line of metrics.jsonl: step, time, epoch when given, and each named scalar (null when not finite).""" + line = {'step': int(step), 'time': self.elapsed()} + if epoch is not None: + line['epoch'] = _scalar(epoch) + for name, value in scalars.items(): + if name in _RESERVED: + raise ValueError(f'{name} is not a name for a scalar; it is a key of every line.') + line[name] = None if value is None else _scalar(value) + self._append(METRICS, line) + + def checkpoint(self, step, path, **figures): + """One line of checkpoints.jsonl: a checkpoint the script kept, by its path in the output directory.""" + line = {'step': int(step), 'time': self.elapsed(), 'path': os.fspath(path)} + for name, value in figures.items(): + line[name] = None if value is None else _scalar(value) + self._append(CHECKPOINTS, line) + + # -------------------------------------------------------------- histograms + + def log_histograms(self, step, model=None, *, tensors=None, kinds=KINDS, bins=32, most=64): + """Lines of histograms.jsonl: for a model, each parameter's weights and (when it has one) its gradient; for + tensors, a mapping of name to values, as weights. At most most tensors a call.""" + elapsed = self.elapsed() + written = 0 + if model is not None: + for name, parameter in model.named_parameters(): + if written >= most: + break + for kind in kinds: + values = parameter if kind == 'weights' else getattr(parameter, 'grad', None) + if values is None: + continue + self._histogram(step, elapsed, name, kind, values, bins) + written += 1 + for name, values in (tensors or {}).items(): + if written >= most: + break + self._histogram(step, elapsed, str(name), 'weights', values, bins) + written += 1 + + def _histogram(self, step, elapsed, name, kind, values, bins): + edges, counts, nonfinite = histogram(values, bins) + if edges is None: + return + line = {'step': int(step), 'time': elapsed, 'name': name, 'kind': kind, 'edges': edges, 'counts': counts} + if nonfinite: + line['nonfinite'] = nonfinite + self._append(HISTOGRAMS, line) + + # ----------------------------------------------------------------- samples + + def log_sample(self, step, name, value): + """A sample: PNG bytes as a .png, anything else (an array, a tensor, a nested list of numbers) as an .npy; + written whole under samples/, then indexed in samples.jsonl. Returns its path relative to training/.""" + elapsed = self.elapsed() + safe = _SAFE.sub('_', str(name)).strip('._') or 'sample' + if isinstance(value, (bytes, bytearray, memoryview)): + data = bytes(value) + if not data.startswith(PNG_SIGNATURE): + raise ValueError('A sample given as bytes must be a PNG.') + extension = '.png' + else: + data = npy_bytes(value) + extension = '.npy' + relative = f'samples/{int(step):09d}-{safe[:80]}{extension}' + self._replace(os.path.join(self.directory, relative), data) + self._append(SAMPLES, {'step': int(step), 'time': elapsed, 'name': str(name), 'path': relative}) + return relative + + +# --------------------------------------------------------------------- histograms + +def _flat(values): + """The numbers of values as a flat list of floats: a tensor (detached, on the CPU), an object with tolist(), a + nested sequence.""" + if hasattr(values, 'detach'): + values = values.detach().cpu() + if hasattr(values, 'tolist'): + values = values.tolist() + out = [] + stack = [values] + while stack: + item = stack.pop() + if isinstance(item, (list, tuple)): + stack.extend(reversed(item)) + else: + out.append(float(item)) + return out + + +def histogram(values, bins=32): + """(edges, counts, nonfinite) of values' finite numbers over bins equal bins; (None, None, n) when none is + finite. A tensor is counted by its own histc (no copy to Python) when it has one.""" + bins = max(1, int(bins)) + if hasattr(values, 'histc') and hasattr(values, 'detach'): + tensor = values.detach().float() + finite = tensor[tensor.isfinite()] if hasattr(tensor, 'isfinite') else tensor + nonfinite = int(tensor.numel() - finite.numel()) + if finite.numel() == 0: + return None, None, nonfinite + low, high = float(finite.min()), float(finite.max()) + if high == low: + low, high = low - 0.5, high + 0.5 + counts = [int(c) for c in finite.histc(bins=bins, min=low, max=high).tolist()] + return _edges(low, high, bins), counts, nonfinite + numbers = _flat(values) + finite = [n for n in numbers if math.isfinite(n)] + nonfinite = len(numbers) - len(finite) + if not finite: + return None, None, nonfinite + low, high = min(finite), max(finite) + if high == low: + low, high = low - 0.5, high + 0.5 + counts = [0] * bins + width = (high - low) / bins + for n in finite: + counts[min(bins - 1, int((n - low) / width))] += 1 + return _edges(low, high, bins), counts, nonfinite + + +def _edges(low, high, bins): + edges = [low + (high - low) * i / bins for i in range(bins + 1)] + edges[-1] = high + return edges + + +# ------------------------------------------------------------------------- .npy + +def npy_bytes(value): + """The bytes of an .npy (version 1.0, C order, little-endian) of value: an array with __array_interface__ or + dtype/shape/tobytes (NumPy), a tensor (detached, on the CPU), or a nested list of numbers (as float32).""" + if hasattr(value, 'detach'): + value = value.detach().cpu() + if hasattr(value, 'numpy'): + try: + value = value.numpy() + except (RuntimeError, TypeError): # PyTorch built without NumPy + value = value.tolist() + else: + value = value.tolist() + dtype = getattr(value, 'dtype', None) + descr = getattr(dtype, 'str', None) + if descr and hasattr(value, 'tobytes') and hasattr(value, 'shape'): + if getattr(dtype, 'kind', descr[1:2]) not in _NUMERIC_KINDS: + raise ValueError(f'A sample must be numeric; this one is of type {descr}.') + if descr[0] == '>': + value = value.byteswap() + descr = '<' + descr[1:] + shape = tuple(int(n) for n in value.shape) + return _npy_header(descr, shape) + value.tobytes(order='C') + shape, flat = _shape_of(value) + return _npy_header(' Date: Thu, 19 Nov 2026 05:29:45 -0700 Subject: [PATCH 090/131] feat(tuldok_log): export_graph writes a PyTorch model's structure as model-graph.json torch.export, else torch.fx with one forward pass for the shapes, else the module tree alone with complete false and the reason. JSON only, written through a rename. The two fixture graphs the structure checks read are written once by tests/project_structure_fixture_export.py and committed. Co-Authored-By: Claude Opus 5.5 --- tests/fixtures/model_graph/derived.json | 1 + tests/fixtures/model_graph/parent.json | 1 + tests/project_structure_fixture_export.py | 60 ++++ tests/test_tuldok_log_graph.py | 181 ++++++++++ tuldok_log/__init__.py | 1 + tuldok_log/graph.py | 398 ++++++++++++++++++++++ 6 files changed, 642 insertions(+) create mode 100644 tests/fixtures/model_graph/derived.json create mode 100644 tests/fixtures/model_graph/parent.json create mode 100644 tests/project_structure_fixture_export.py create mode 100644 tests/test_tuldok_log_graph.py create mode 100644 tuldok_log/__init__.py create mode 100644 tuldok_log/graph.py diff --git a/tests/fixtures/model_graph/derived.json b/tests/fixtures/model_graph/derived.json new file mode 100644 index 00000000..ba9925a6 --- /dev/null +++ b/tests/fixtures/model_graph/derived.json @@ -0,0 +1 @@ +{"format":"tuldok_model_graph_v1","complete":true,"reason":null,"method":"torch.export","torch":"2.8.0+cpu","model":"__main__.Net","inputs":[{"name":"x","shape":[2,1,8,8],"dtype":"float32"}],"tensors":{"stem.weight":{"shape":[4,1,3,3],"dtype":"float32","kind":"parameter"},"stem.bias":{"shape":[4],"dtype":"float32","kind":"parameter"},"blocks.0.conv1.weight":{"shape":[4,4,3,3],"dtype":"float32","kind":"parameter"},"blocks.0.conv1.bias":{"shape":[4],"dtype":"float32","kind":"parameter"},"blocks.0.conv2.weight":{"shape":[4,4,3,3],"dtype":"float32","kind":"parameter"},"blocks.0.conv2.bias":{"shape":[4],"dtype":"float32","kind":"parameter"},"blocks.1.conv1.weight":{"shape":[4,4,3,3],"dtype":"float32","kind":"parameter"},"blocks.1.conv1.bias":{"shape":[4],"dtype":"float32","kind":"parameter"},"blocks.1.conv2.weight":{"shape":[4,4,3,3],"dtype":"float32","kind":"parameter"},"blocks.1.conv2.bias":{"shape":[4],"dtype":"float32","kind":"parameter"},"head.0.weight":{"shape":[16,4],"dtype":"float32","kind":"parameter"},"head.0.bias":{"shape":[16],"dtype":"float32","kind":"parameter"},"head.2.weight":{"shape":[3,16],"dtype":"float32","kind":"parameter"},"head.2.bias":{"shape":[3],"dtype":"float32","kind":"parameter"},"gate.weight":{"shape":[3,3],"dtype":"float32","kind":"parameter"},"gate.bias":{"shape":[3],"dtype":"float32","kind":"parameter"}},"nodes":[{"id":"x","kind":"input","operation":"input","module":"","tensors":[],"inputs":[],"outputs":[{"shape":[2,1,8,8],"dtype":"float32"}],"attributes":{}},{"id":"conv2d","kind":"operation","operation":"aten.conv2d.default","module":"stem","tensors":["stem.weight","stem.bias"],"inputs":[{"shape":[2,1,8,8],"dtype":"float32"}],"outputs":[{"shape":[2,4,8,8],"dtype":"float32"}],"attributes":{"stride":[1,1],"padding":[1,1]}},{"id":"conv2d_1","kind":"operation","operation":"aten.conv2d.default","module":"blocks.0.conv1","tensors":["blocks.0.conv1.weight","blocks.0.conv1.bias"],"inputs":[{"shape":[2,4,8,8],"dtype":"float32"}],"outputs":[{"shape":[2,4,8,8],"dtype":"float32"}],"attributes":{"stride":[1,1],"padding":[1,1]}},{"id":"silu","kind":"operation","operation":"aten.silu.default","module":"blocks.0.act","tensors":[],"inputs":[{"shape":[2,4,8,8],"dtype":"float32"}],"outputs":[{"shape":[2,4,8,8],"dtype":"float32"}],"attributes":{}},{"id":"conv2d_2","kind":"operation","operation":"aten.conv2d.default","module":"blocks.0.conv2","tensors":["blocks.0.conv2.weight","blocks.0.conv2.bias"],"inputs":[{"shape":[2,4,8,8],"dtype":"float32"}],"outputs":[{"shape":[2,4,8,8],"dtype":"float32"}],"attributes":{"stride":[1,1],"padding":[1,1]}},{"id":"add","kind":"operation","operation":"aten.add.Tensor","module":"blocks.0","tensors":[],"inputs":[{"shape":[2,4,8,8],"dtype":"float32"},{"shape":[2,4,8,8],"dtype":"float32"}],"outputs":[{"shape":[2,4,8,8],"dtype":"float32"}],"attributes":{}},{"id":"conv2d_3","kind":"operation","operation":"aten.conv2d.default","module":"blocks.1.conv1","tensors":["blocks.1.conv1.weight","blocks.1.conv1.bias"],"inputs":[{"shape":[2,4,8,8],"dtype":"float32"}],"outputs":[{"shape":[2,4,8,8],"dtype":"float32"}],"attributes":{"stride":[1,1],"padding":[1,1]}},{"id":"silu_1","kind":"operation","operation":"aten.silu.default","module":"blocks.1.act","tensors":[],"inputs":[{"shape":[2,4,8,8],"dtype":"float32"}],"outputs":[{"shape":[2,4,8,8],"dtype":"float32"}],"attributes":{}},{"id":"conv2d_4","kind":"operation","operation":"aten.conv2d.default","module":"blocks.1.conv2","tensors":["blocks.1.conv2.weight","blocks.1.conv2.bias"],"inputs":[{"shape":[2,4,8,8],"dtype":"float32"}],"outputs":[{"shape":[2,4,8,8],"dtype":"float32"}],"attributes":{"stride":[1,1],"padding":[1,1]}},{"id":"add_1","kind":"operation","operation":"aten.add.Tensor","module":"blocks.1","tensors":[],"inputs":[{"shape":[2,4,8,8],"dtype":"float32"},{"shape":[2,4,8,8],"dtype":"float32"}],"outputs":[{"shape":[2,4,8,8],"dtype":"float32"}],"attributes":{}},{"id":"mean","kind":"operation","operation":"aten.mean.dim","module":"","tensors":[],"inputs":[{"shape":[2,4,8,8],"dtype":"float32"}],"outputs":[{"shape":[2,4],"dtype":"float32"}],"attributes":{"dim":[2,3]}},{"id":"linear","kind":"operation","operation":"aten.linear.default","module":"head.0","tensors":["head.0.weight","head.0.bias"],"inputs":[{"shape":[2,4],"dtype":"float32"}],"outputs":[{"shape":[2,16],"dtype":"float32"}],"attributes":{}},{"id":"silu_2","kind":"operation","operation":"aten.silu.default","module":"head.1","tensors":[],"inputs":[{"shape":[2,16],"dtype":"float32"}],"outputs":[{"shape":[2,16],"dtype":"float32"}],"attributes":{}},{"id":"linear_1","kind":"operation","operation":"aten.linear.default","module":"head.2","tensors":["head.2.weight","head.2.bias"],"inputs":[{"shape":[2,16],"dtype":"float32"}],"outputs":[{"shape":[2,3],"dtype":"float32"}],"attributes":{}},{"id":"linear_2","kind":"operation","operation":"aten.linear.default","module":"gate","tensors":["gate.weight","gate.bias"],"inputs":[{"shape":[2,3],"dtype":"float32"}],"outputs":[{"shape":[2,3],"dtype":"float32"}],"attributes":{}},{"id":"sigmoid","kind":"operation","operation":"aten.sigmoid.default","module":"","tensors":[],"inputs":[{"shape":[2,3],"dtype":"float32"}],"outputs":[{"shape":[2,3],"dtype":"float32"}],"attributes":{}},{"id":"mul","kind":"operation","operation":"aten.mul.Tensor","module":"","tensors":[],"inputs":[{"shape":[2,3],"dtype":"float32"},{"shape":[2,3],"dtype":"float32"}],"outputs":[{"shape":[2,3],"dtype":"float32"}],"attributes":{}},{"id":"output","kind":"output","operation":"output","module":"","tensors":[],"inputs":[{"shape":[2,3],"dtype":"float32"}],"outputs":[{"shape":[2,3],"dtype":"float32"}],"attributes":{}}],"edges":[{"from":"x","to":"conv2d","input":0},{"from":"conv2d","to":"conv2d_1","input":0},{"from":"conv2d_1","to":"silu","input":0},{"from":"silu","to":"conv2d_2","input":0},{"from":"conv2d","to":"add","input":0},{"from":"conv2d_2","to":"add","input":1},{"from":"add","to":"conv2d_3","input":0},{"from":"conv2d_3","to":"silu_1","input":0},{"from":"silu_1","to":"conv2d_4","input":0},{"from":"add","to":"add_1","input":0},{"from":"conv2d_4","to":"add_1","input":1},{"from":"add_1","to":"mean","input":0},{"from":"mean","to":"linear","input":0},{"from":"linear","to":"silu_2","input":0},{"from":"silu_2","to":"linear_1","input":0},{"from":"linear_1","to":"linear_2","input":0},{"from":"linear_2","to":"sigmoid","input":0},{"from":"linear_1","to":"mul","input":0},{"from":"sigmoid","to":"mul","input":1},{"from":"mul","to":"output","input":0}],"modules":{"path":"","class":"__main__.Net","parameters":775,"children":[{"path":"stem","class":"torch.nn.modules.conv.Conv2d","parameters":40,"children":[]},{"path":"blocks","class":"torch.nn.modules.container.Sequential","parameters":592,"children":[{"path":"blocks.0","class":"__main__.Block","parameters":296,"children":[{"path":"blocks.0.conv1","class":"torch.nn.modules.conv.Conv2d","parameters":148,"children":[]},{"path":"blocks.0.act","class":"torch.nn.modules.activation.SiLU","parameters":0,"children":[]},{"path":"blocks.0.conv2","class":"torch.nn.modules.conv.Conv2d","parameters":148,"children":[]}]},{"path":"blocks.1","class":"__main__.Block","parameters":296,"children":[{"path":"blocks.1.conv1","class":"torch.nn.modules.conv.Conv2d","parameters":148,"children":[]},{"path":"blocks.1.act","class":"torch.nn.modules.activation.SiLU","parameters":0,"children":[]},{"path":"blocks.1.conv2","class":"torch.nn.modules.conv.Conv2d","parameters":148,"children":[]}]}]},{"path":"head","class":"torch.nn.modules.container.Sequential","parameters":131,"children":[{"path":"head.0","class":"torch.nn.modules.linear.Linear","parameters":80,"children":[]},{"path":"head.1","class":"torch.nn.modules.activation.SiLU","parameters":0,"children":[]},{"path":"head.2","class":"torch.nn.modules.linear.Linear","parameters":51,"children":[]}]},{"path":"gate","class":"torch.nn.modules.linear.Linear","parameters":12,"children":[]}]},"notes":[]} diff --git a/tests/fixtures/model_graph/parent.json b/tests/fixtures/model_graph/parent.json new file mode 100644 index 00000000..fc7060fe --- /dev/null +++ b/tests/fixtures/model_graph/parent.json @@ -0,0 +1 @@ +{"format":"tuldok_model_graph_v1","complete":true,"reason":null,"method":"torch.export","torch":"2.8.0+cpu","model":"__main__.Net","inputs":[{"name":"x","shape":[2,1,8,8],"dtype":"float32"}],"tensors":{"stem.weight":{"shape":[4,1,3,3],"dtype":"float32","kind":"parameter"},"stem.bias":{"shape":[4],"dtype":"float32","kind":"parameter"},"blocks.0.conv1.weight":{"shape":[4,4,3,3],"dtype":"float32","kind":"parameter"},"blocks.0.conv1.bias":{"shape":[4],"dtype":"float32","kind":"parameter"},"blocks.0.conv2.weight":{"shape":[4,4,3,3],"dtype":"float32","kind":"parameter"},"blocks.0.conv2.bias":{"shape":[4],"dtype":"float32","kind":"parameter"},"blocks.1.conv1.weight":{"shape":[4,4,3,3],"dtype":"float32","kind":"parameter"},"blocks.1.conv1.bias":{"shape":[4],"dtype":"float32","kind":"parameter"},"blocks.1.conv2.weight":{"shape":[4,4,3,3],"dtype":"float32","kind":"parameter"},"blocks.1.conv2.bias":{"shape":[4],"dtype":"float32","kind":"parameter"},"head.0.weight":{"shape":[8,4],"dtype":"float32","kind":"parameter"},"head.0.bias":{"shape":[8],"dtype":"float32","kind":"parameter"},"head.2.weight":{"shape":[3,8],"dtype":"float32","kind":"parameter"},"head.2.bias":{"shape":[3],"dtype":"float32","kind":"parameter"}},"nodes":[{"id":"x","kind":"input","operation":"input","module":"","tensors":[],"inputs":[],"outputs":[{"shape":[2,1,8,8],"dtype":"float32"}],"attributes":{}},{"id":"conv2d","kind":"operation","operation":"aten.conv2d.default","module":"stem","tensors":["stem.weight","stem.bias"],"inputs":[{"shape":[2,1,8,8],"dtype":"float32"}],"outputs":[{"shape":[2,4,8,8],"dtype":"float32"}],"attributes":{"stride":[1,1],"padding":[1,1]}},{"id":"conv2d_1","kind":"operation","operation":"aten.conv2d.default","module":"blocks.0.conv1","tensors":["blocks.0.conv1.weight","blocks.0.conv1.bias"],"inputs":[{"shape":[2,4,8,8],"dtype":"float32"}],"outputs":[{"shape":[2,4,8,8],"dtype":"float32"}],"attributes":{"stride":[1,1],"padding":[1,1]}},{"id":"silu","kind":"operation","operation":"aten.silu.default","module":"blocks.0.act","tensors":[],"inputs":[{"shape":[2,4,8,8],"dtype":"float32"}],"outputs":[{"shape":[2,4,8,8],"dtype":"float32"}],"attributes":{}},{"id":"conv2d_2","kind":"operation","operation":"aten.conv2d.default","module":"blocks.0.conv2","tensors":["blocks.0.conv2.weight","blocks.0.conv2.bias"],"inputs":[{"shape":[2,4,8,8],"dtype":"float32"}],"outputs":[{"shape":[2,4,8,8],"dtype":"float32"}],"attributes":{"stride":[1,1],"padding":[1,1]}},{"id":"add","kind":"operation","operation":"aten.add.Tensor","module":"blocks.0","tensors":[],"inputs":[{"shape":[2,4,8,8],"dtype":"float32"},{"shape":[2,4,8,8],"dtype":"float32"}],"outputs":[{"shape":[2,4,8,8],"dtype":"float32"}],"attributes":{}},{"id":"conv2d_3","kind":"operation","operation":"aten.conv2d.default","module":"blocks.1.conv1","tensors":["blocks.1.conv1.weight","blocks.1.conv1.bias"],"inputs":[{"shape":[2,4,8,8],"dtype":"float32"}],"outputs":[{"shape":[2,4,8,8],"dtype":"float32"}],"attributes":{"stride":[1,1],"padding":[1,1]}},{"id":"silu_1","kind":"operation","operation":"aten.silu.default","module":"blocks.1.act","tensors":[],"inputs":[{"shape":[2,4,8,8],"dtype":"float32"}],"outputs":[{"shape":[2,4,8,8],"dtype":"float32"}],"attributes":{}},{"id":"conv2d_4","kind":"operation","operation":"aten.conv2d.default","module":"blocks.1.conv2","tensors":["blocks.1.conv2.weight","blocks.1.conv2.bias"],"inputs":[{"shape":[2,4,8,8],"dtype":"float32"}],"outputs":[{"shape":[2,4,8,8],"dtype":"float32"}],"attributes":{"stride":[1,1],"padding":[1,1]}},{"id":"add_1","kind":"operation","operation":"aten.add.Tensor","module":"blocks.1","tensors":[],"inputs":[{"shape":[2,4,8,8],"dtype":"float32"},{"shape":[2,4,8,8],"dtype":"float32"}],"outputs":[{"shape":[2,4,8,8],"dtype":"float32"}],"attributes":{}},{"id":"mean","kind":"operation","operation":"aten.mean.dim","module":"","tensors":[],"inputs":[{"shape":[2,4,8,8],"dtype":"float32"}],"outputs":[{"shape":[2,4],"dtype":"float32"}],"attributes":{"dim":[2,3]}},{"id":"linear","kind":"operation","operation":"aten.linear.default","module":"head.0","tensors":["head.0.weight","head.0.bias"],"inputs":[{"shape":[2,4],"dtype":"float32"}],"outputs":[{"shape":[2,8],"dtype":"float32"}],"attributes":{}},{"id":"silu_2","kind":"operation","operation":"aten.silu.default","module":"head.1","tensors":[],"inputs":[{"shape":[2,8],"dtype":"float32"}],"outputs":[{"shape":[2,8],"dtype":"float32"}],"attributes":{}},{"id":"linear_1","kind":"operation","operation":"aten.linear.default","module":"head.2","tensors":["head.2.weight","head.2.bias"],"inputs":[{"shape":[2,8],"dtype":"float32"}],"outputs":[{"shape":[2,3],"dtype":"float32"}],"attributes":{}},{"id":"output","kind":"output","operation":"output","module":"","tensors":[],"inputs":[{"shape":[2,3],"dtype":"float32"}],"outputs":[{"shape":[2,3],"dtype":"float32"}],"attributes":{}}],"edges":[{"from":"x","to":"conv2d","input":0},{"from":"conv2d","to":"conv2d_1","input":0},{"from":"conv2d_1","to":"silu","input":0},{"from":"silu","to":"conv2d_2","input":0},{"from":"conv2d","to":"add","input":0},{"from":"conv2d_2","to":"add","input":1},{"from":"add","to":"conv2d_3","input":0},{"from":"conv2d_3","to":"silu_1","input":0},{"from":"silu_1","to":"conv2d_4","input":0},{"from":"add","to":"add_1","input":0},{"from":"conv2d_4","to":"add_1","input":1},{"from":"add_1","to":"mean","input":0},{"from":"mean","to":"linear","input":0},{"from":"linear","to":"silu_2","input":0},{"from":"silu_2","to":"linear_1","input":0},{"from":"linear_1","to":"output","input":0}],"modules":{"path":"","class":"__main__.Net","parameters":699,"children":[{"path":"stem","class":"torch.nn.modules.conv.Conv2d","parameters":40,"children":[]},{"path":"blocks","class":"torch.nn.modules.container.Sequential","parameters":592,"children":[{"path":"blocks.0","class":"__main__.Block","parameters":296,"children":[{"path":"blocks.0.conv1","class":"torch.nn.modules.conv.Conv2d","parameters":148,"children":[]},{"path":"blocks.0.act","class":"torch.nn.modules.activation.SiLU","parameters":0,"children":[]},{"path":"blocks.0.conv2","class":"torch.nn.modules.conv.Conv2d","parameters":148,"children":[]}]},{"path":"blocks.1","class":"__main__.Block","parameters":296,"children":[{"path":"blocks.1.conv1","class":"torch.nn.modules.conv.Conv2d","parameters":148,"children":[]},{"path":"blocks.1.act","class":"torch.nn.modules.activation.SiLU","parameters":0,"children":[]},{"path":"blocks.1.conv2","class":"torch.nn.modules.conv.Conv2d","parameters":148,"children":[]}]}]},{"path":"head","class":"torch.nn.modules.container.Sequential","parameters":67,"children":[{"path":"head.0","class":"torch.nn.modules.linear.Linear","parameters":40,"children":[]},{"path":"head.1","class":"torch.nn.modules.activation.SiLU","parameters":0,"children":[]},{"path":"head.2","class":"torch.nn.modules.linear.Linear","parameters":27,"children":[]}]}]},"notes":[]} diff --git a/tests/project_structure_fixture_export.py b/tests/project_structure_fixture_export.py new file mode 100644 index 00000000..96a03080 --- /dev/null +++ b/tests/project_structure_fixture_export.py @@ -0,0 +1,60 @@ +"""Writes the model graphs the structure checks read: tests/fixtures/model_graph/parent.json and derived.json. + +Run once, with a Python that has PyTorch (the CPU is enough), and commit what it writes; the browser check +(tests/browser_project_workspace_structure.cjs) and the reader's tests read the committed files and need no +PyTorch: + + PYTHONPATH=. tests/project_structure_fixture_export.py + +Both models are Net below, exported by tuldok_log.graph.export_graph on one example input of shape +(2, 1, 8, 8): a convolution stem, two residual blocks of two convolutions with an add, and an MLP head. The +derived model widens the head's hidden layer from 8 to 16 (head.0 and head.2 change shape) and adds a module +gate after the head. +""" +import os +import sys + +import torch +from torch import nn + +sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__)))) +from tuldok_log.graph import export_graph # noqa: E402 + +OUT = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'fixtures', 'model_graph') + + +class Block(nn.Module): + def __init__(self, width): + super().__init__() + self.conv1 = nn.Conv2d(width, width, 3, padding=1) + self.act = nn.SiLU() + self.conv2 = nn.Conv2d(width, width, 3, padding=1) + + def forward(self, x): + return x + self.conv2(self.act(self.conv1(x))) + + +class Net(nn.Module): + def __init__(self, hidden=8, gate=False): + super().__init__() + self.stem = nn.Conv2d(1, 4, 3, padding=1) + self.blocks = nn.Sequential(Block(4), Block(4)) + self.head = nn.Sequential(nn.Linear(4, hidden), nn.SiLU(), nn.Linear(hidden, 3)) + self.gate = nn.Linear(3, 3) if gate else None + + def forward(self, x): + y = self.head(self.blocks(self.stem(x)).mean((2, 3))) + return y if self.gate is None else y * torch.sigmoid(self.gate(y)) + + +def main(): + os.makedirs(OUT, exist_ok=True) + torch.manual_seed(0) + example = torch.zeros(2, 1, 8, 8) + for name, model in (('parent', Net()), ('derived', Net(hidden=16, gate=True))): + written = export_graph(model.eval(), example, os.path.join(OUT, name + '.json')) + print(name, written['method'], written['complete'], len(written['nodes']), 'nodes') + + +if __name__ == '__main__': + main() diff --git a/tests/test_tuldok_log_graph.py b/tests/test_tuldok_log_graph.py new file mode 100644 index 00000000..8605c66e --- /dev/null +++ b/tests/test_tuldok_log_graph.py @@ -0,0 +1,181 @@ +"""tuldok_log.graph.export_graph on small models, with PyTorch on the CPU (docs/plans/training-and-curation/spec-t2.md). + +Skipped when PyTorch is not installed (Tuldok's own environment has none). Run +with a Python that has it, for example: + + PYTHONPATH=.:tests -m unittest test_tuldok_log_graph + +It needs nothing of Tuldok's server: only tuldok_log and the standard library. +""" +import json +import os +from pathlib import Path +import sys +import tempfile +import unittest +from unittest import mock + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) + +try: + import torch + from torch import nn +except ImportError: # Tuldok's own environment: nothing to test here + torch = None + +from tuldok_log import graph as tuldok_graph # noqa: E402 + + +if torch is not None: + class Block(nn.Module): + def __init__(self, width): + super().__init__() + self.conv1 = nn.Conv2d(width, width, 3, padding=1) + self.act = nn.SiLU() + self.conv2 = nn.Conv2d(width, width, 3, padding=1) + self.norm = nn.BatchNorm2d(width) + + def forward(self, x): + return x + self.norm(self.conv2(self.act(self.conv1(x)))) + + class Nested(nn.Module): + """A convolution stem, residual blocks of two convolutions and an add, an MLP head.""" + + def __init__(self): + super().__init__() + self.stem = nn.Conv2d(2, 6, 3, padding=1) + self.blocks = nn.Sequential(Block(6), Block(6)) + self.mlp = nn.Sequential(nn.Linear(6, 12), nn.SiLU(), nn.Linear(12, 5)) + + def forward(self, x): + return self.mlp(self.blocks(self.stem(x)).mean((2, 3))) + + class Branches(Nested): + """Its forward chooses a path by the input's values, which neither torch.export nor torch.fx can follow.""" + + def forward(self, x): + if x.sum() > 0: + return super().forward(x) + return self.mlp(x.mean((2, 3)).repeat(1, 3)) + + +@unittest.skipIf(torch is None, 'PyTorch is not installed in this environment.') +class Export(unittest.TestCase): + + def setUp(self): + directory = tempfile.TemporaryDirectory() + self.addCleanup(directory.cleanup) + self.folder = Path(directory.name) + torch.manual_seed(0) + self.example = torch.randn(3, 2, 10, 10) + + def export(self, model, path=None): + written = tuldok_graph.export_graph(model.eval(), self.example, path or self.folder) + target = Path(path) if path else self.folder / 'model-graph.json' + raw = target.read_bytes() + self.assertFalse(raw.startswith(b'\x80'), 'not a pickle') + self.assertEqual(json.loads(raw), written) + self.assertEqual([p.name for p in target.parent.iterdir() if p.name.endswith('.tmp')], []) + return written + + def test_a_nested_model_exported_whole(self): + model = Nested() + written = self.export(model) + self.assertEqual((written['format'], written['complete'], written['reason'], written['method']), + ('tuldok_model_graph_v1', True, None, 'torch.export')) + self.assertEqual(written['torch'], torch.__version__) + self.assertEqual(written['inputs'], [{'name': 'x', 'shape': [3, 2, 10, 10], 'dtype': 'float32'}]) + state = model.state_dict() + self.assertEqual(set(written['tensors']), set(state)) + for name, tensor in state.items(): + self.assertEqual(written['tensors'][name]['shape'], list(tensor.shape), name) + self.assertEqual(written['tensors']['blocks.0.norm.running_mean']['kind'], 'buffer') + self.assertEqual(written['tensors']['stem.weight']['kind'], 'parameter') + nodes = {node['id']: node for node in written['nodes']} + used = {name for node in written['nodes'] for name in node['tensors']} + self.assertTrue(used <= set(state)) + self.assertTrue({name for name, _ in model.named_parameters()} <= used) + # The shapes are those of a forward pass, recorded module by module with hooks. + seen = {} + + def hook(path): + def record(module, inputs, output): + seen.setdefault(path, list(output.shape)) # returns None, so the output is unchanged + return record + hooks = [module.register_forward_hook(hook(path)) + for path, module in model.named_modules() if path and not list(module.children())] + with torch.no_grad(): + model(self.example) + for hook in hooks: + hook.remove() + for node in written['nodes']: + if node['kind'] == 'operation' and node['module'] in seen and node['tensors']: + self.assertEqual(node['outputs'][0]['shape'], seen[node['module']], node['id']) + convolutions = [node for node in written['nodes'] if node['operation'] == 'aten.conv2d.default'] + self.assertEqual([node['module'] for node in convolutions], + ['stem', 'blocks.0.conv1', 'blocks.0.conv2', 'blocks.1.conv1', 'blocks.1.conv2']) + self.assertEqual(convolutions[0]['tensors'], ['stem.weight', 'stem.bias']) + self.assertEqual(convolutions[0]['attributes']['padding'], [1, 1]) + adds = [node for node in written['nodes'] if node['operation'] == 'aten.add.Tensor'] + self.assertEqual([node['module'] for node in adds], ['blocks.0', 'blocks.1']) + into = [edge for edge in written['edges'] if edge['to'] == adds[0]['id']] + self.assertEqual(len(into), 2) + self.assertEqual(sorted(edge['input'] for edge in into), [0, 1]) + self.assertEqual({nodes[edge['from']]['module'] for edge in into}, {'stem', 'blocks.0.norm'}) + self.assertEqual(written['nodes'][-1]['kind'], 'output') + self.assertEqual(written['nodes'][-1]['outputs'], [{'shape': [3, 5], 'dtype': 'float32'}]) + # The module tree and its counts. + tree = written['modules'] + self.assertEqual((tree['path'], tree['class'], tree['parameters']), + ('', f'{Nested.__module__}.Nested', sum(p.numel() for p in model.parameters()))) + flat = {} + stack = [tree] + while stack: + item = stack.pop() + flat[item['path']] = item + stack.extend(item['children']) + self.assertEqual(set(flat), {path for path, _ in model.named_modules()}) + for path, module in model.named_modules(): + self.assertEqual(flat[path]['parameters'], sum(p.numel() for p in module.parameters()), path) + self.assertEqual(flat['blocks.0.conv1']['class'], 'torch.nn.modules.conv.Conv2d') + # Every edge joins two nodes, each after the nodes it reads. + order = {node['id']: i for i, node in enumerate(written['nodes'])} + self.assertTrue(all(order[edge['from']] < order[edge['to']] for edge in written['edges'])) + + def test_a_forward_that_branches_on_values_writes_the_module_tree(self): + written = self.export(Branches()) + self.assertEqual((written['complete'], written['method'], written['nodes'], written['edges']), + (False, 'module-tree', [], [])) + self.assertIn('torch.export failed', written['reason']) + self.assertIn('torch.fx failed', written['reason']) + self.assertEqual(written['modules']['parameters'], sum(p.numel() for p in Branches().parameters())) + self.assertIn('blocks.1.norm.running_var', written['tensors']) + + def test_torch_fx_when_export_fails(self): + def refuse(*_, **__): + raise RuntimeError('export is not available here') + with mock.patch.object(torch.export, 'export', refuse): + written = self.export(Nested(), self.folder / 'traced.json') + self.assertEqual((written['complete'], written['method']), (True, 'torch.fx')) + self.assertTrue(any('export is not available here' in note for note in written['notes'])) + modules = [node for node in written['nodes'] if node['operation'] == 'torch.nn.modules.conv.Conv2d'] + self.assertEqual(modules[0]['module'], 'stem') + self.assertEqual(modules[0]['tensors'], ['stem.weight', 'stem.bias']) + self.assertEqual(modules[0]['outputs'], [{'shape': [3, 6, 10, 10], 'dtype': 'float32'}]) + self.assertEqual(written['nodes'][0], {**written['nodes'][0], 'kind': 'input', 'id': 'x'}) + + def test_past_the_node_bound_the_module_tree(self): + with mock.patch.object(tuldok_graph, 'NODES', 5): + written = self.export(Nested()) + self.assertEqual((written['complete'], written['method']), (False, 'module-tree')) + self.assertIn('more than 5 nodes', written['reason']) + + def test_a_directory_or_a_file(self): + written = self.export(Nested(), self.folder / 'named.json') + self.assertTrue((self.folder / 'named.json').is_file()) + self.assertFalse((self.folder / 'model-graph.json').exists()) + self.assertEqual(written['format'], 'tuldok_model_graph_v1') + + +if __name__ == '__main__': + unittest.main() diff --git a/tuldok_log/__init__.py b/tuldok_log/__init__.py new file mode 100644 index 00000000..2ad27ff5 --- /dev/null +++ b/tuldok_log/__init__.py @@ -0,0 +1 @@ +"""tuldok_log: small helpers a project's script may import to write the files Tuldok reads.""" diff --git a/tuldok_log/graph.py b/tuldok_log/graph.py new file mode 100644 index 00000000..9ff4c3f7 --- /dev/null +++ b/tuldok_log/graph.py @@ -0,0 +1,398 @@ +"""Write a PyTorch model's structure as model-graph.json, the file Tuldok draws (docs/plans/training-and-curation/spec-t2.md). + +export_graph(model, example_inputs, path) records the model's operations from +its inputs to its outputs, with the module each ran in, the parameter and +buffer tensors each reads (by the names of the model's state_dict, which are +the names its weights file uses), the shapes and types of what each takes and +gives, and the tree of the model's modules. It tries torch.export.export +first, then torch.fx.symbolic_trace with one forward pass for the shapes, and +when both fail (a forward that branches on data values, say) writes the +module tree alone with complete false and the reason. It imports PyTorch only +inside export_graph, writes JSON only (never a pickle), and replaces the file +in one rename, so a reader never sees half of it. The bounds are section 1 of +the spec; a graph past them is written as its module tree with the reason. +""" +import json +import math +import os +import re +import uuid + +FORMAT = 'tuldok_model_graph_v1' +FILE = 'model-graph.json' +NODES = 20_000 +EDGES = 100_000 +MODULES = 20_000 +DEPTH = 64 +TENSORS = 100_000 +NODE_TENSORS = 64 +VALUES = 16 # inputs or outputs of a node +AXES = 16 +TEXT = 1024 +ATTRIBUTES = 16 +LIST = 16 +REASON = 400 + + +def _text(value, most=TEXT): + value = str(value) + return value if len(value) <= most else value[:most - 1] + '…' + + +def _first_line(error): + lines = str(error).strip().splitlines() + return _text(f'{type(error).__name__}: {lines[0] if lines else ""}'.rstrip(': '), REASON) + + +def _class(module): + kind = type(module) + return _text(f'{kind.__module__}.{kind.__qualname__}') + + +def _dtype(dtype): + return _text(str(dtype).replace('torch.', ''), 64) + + +def _shape(shape): + out = [] + for size in list(shape)[:AXES]: + try: + out.append(int(size)) + except (TypeError, ValueError): + out.append(_text(size, 64)) # a symbolic size + return out + + +def _plain(value, depth=0): + """value as a JSON-plain attribute, or a marker object _SKIP when it is not one.""" + if value is None or isinstance(value, bool): + return value + if isinstance(value, int): + return value + if isinstance(value, float): + return value if math.isfinite(value) else str(value) + if isinstance(value, str): + return _text(value, 200) + if isinstance(value, (list, tuple)) and depth == 0: + items = [_plain(item, 1) for item in value[:LIST]] + return _SKIP if any(item is _SKIP for item in items) else items + if type(value).__module__.startswith('torch') and type(value).__name__ in ('dtype', 'device', 'layout', + 'memory_format'): + return _text(str(value).replace('torch.', ''), 64) + return _SKIP + + +_SKIP = object() + + +# ------------------------------------------------------------------ the module tree + +def module_tree(model): + """The tree of model's modules: {path, class, parameters, children}, at most MODULES modules, DEPTH deep.""" + count = [0] + + def node(module, path, depth): + count[0] += 1 + children = [] + if depth < DEPTH: + for name, child in module.named_children(): + if count[0] >= MODULES: + break + children.append(node(child, f'{path}.{name}' if path else name, depth + 1)) + return {'path': _text(path), 'class': _class(module), + 'parameters': sum(p.numel() for p in module.parameters()), 'children': children} + return node(model, '', 0), count[0] >= MODULES + + +def _tensors(model): + found = {} + parameters = {name for name, _ in model.named_parameters(remove_duplicate=False)} + for name, tensor in model.state_dict(keep_vars=True).items(): + if len(found) >= TENSORS: + break + found[_text(name)] = {'shape': _shape(tensor.shape), 'dtype': _dtype(tensor.dtype), + 'kind': 'parameter' if name in parameters else 'buffer'} + for name, tensor in model.named_buffers(): + if name not in found and len(found) < TENSORS: # a buffer that is not persistent + found[_text(name)] = {'shape': _shape(tensor.shape), 'dtype': _dtype(tensor.dtype), 'kind': 'buffer'} + return found + + +# ------------------------------------------------------------------ values + +def _values(value): + """[{shape, dtype}] of the tensors in value (a tensor, a fake tensor, tensor metadata or a sequence of them).""" + if value is None: + return [] + if isinstance(value, (list, tuple)) and not hasattr(value, 'shape'): + out = [] + for item in value: + out.extend(_values(item)) + return out[:VALUES] + shape, dtype = getattr(value, 'shape', None), getattr(value, 'dtype', None) + if shape is None or dtype is None: + return [] + return [{'shape': _shape(shape), 'dtype': _dtype(dtype)}] + + +_STACK_PATH = re.compile(r"\._modules\[['\"]([^'\"]+)['\"]\]|\[['\"]([^'\"]+)['\"]\]|\[(\d+)\]") + + +def _module_path(raw, known): + """A module path of nn_module_stack in the dotted form of named_modules ('' for the model).""" + text = str(raw) + for prefix in ("L['self'].", "L['self']", 'L__self__.', 'L__self__', 'self.', 'self'): + if text.startswith(prefix): + text = text[len(prefix):] + break + text = _STACK_PATH.sub(lambda m: '.' + (m.group(1) or m.group(2) or m.group(3)), text).strip('.') + while text and text not in known: + text = text.rpartition('.')[0] + return text + + +def _operation_name(target): + if isinstance(target, str): + return _text(target, 200) + name = getattr(target, '__name__', None) + if type(target).__name__ in ('OpOverload', 'OpOverloadPacket'): + return _text(str(target), 200) + module = getattr(target, '__module__', None) + return _text(f'{module}.{name}' if module and name else str(target), 200) + + +def _attributes(node, Node): + """Up to ATTRIBUTES of a call's arguments that are not graph values, by name where the schema gives one.""" + found = {} + names = [] + schema = getattr(node.target, '_schema', None) + if schema is not None: + names = [argument.name for argument in schema.arguments] + for position, value in enumerate(node.args): + if _holds_node(value, Node): + continue + plain = _plain(value) + if plain is not _SKIP: + found[names[position] if position < len(names) else f'arg{position}'] = plain + for key, value in node.kwargs.items(): + if _holds_node(value, Node): + continue + plain = _plain(value) + if plain is not _SKIP: + found[_text(key, 64)] = plain + return dict(list(found.items())[:ATTRIBUTES]) + + +def _holds_node(value, Node): + if isinstance(value, Node): + return True + if isinstance(value, (list, tuple)): + return any(_holds_node(item, Node) for item in value) + if isinstance(value, dict): + return any(_holds_node(item, Node) for item in value.values()) + return False + + +def _node_arguments(node, Node): + """The graph values a node reads, in the order of its arguments.""" + out = [] + + def walk(value): + if isinstance(value, Node): + out.append(value) + elif isinstance(value, (list, tuple)): + for item in value: + walk(item) + elif isinstance(value, dict): + for item in value.values(): + walk(item) + walk(node.args) + walk(node.kwargs) + return out + + +class _Graph: + """The nodes and edges being written, with the names of the values that are tensors of the model.""" + + def __init__(self, Node): + self.Node = Node + self.nodes, self.edges, self.ids, self.notes = [], [], {}, [] + self.tensor_of = {} # graph value name -> state_dict name + + def add(self, fx_node, kind, operation, module, tensors, outputs, attributes): + if len(tensors) > NODE_TENSORS: + self.notes.append(f'{fx_node.name} reads {len(tensors)} tensors; the first {NODE_TENSORS} are listed.') + entry = {'id': _text(fx_node.name, 200), 'kind': kind, 'operation': operation, 'module': module, + 'tensors': tensors[:NODE_TENSORS], 'inputs': [], 'outputs': outputs[:VALUES], + 'attributes': attributes} + self.ids[fx_node] = entry + self.nodes.append(entry) + return entry + + def connect(self, fx_node, entry, values): + position = 0 + for value in values: + source = self.ids.get(value) + if source is None: + continue + self.edges.append({'from': source['id'], 'to': entry['id'], 'input': position}) + if len(entry['inputs']) < VALUES: + entry['inputs'].extend(source['outputs'][:1]) + position += 1 + + +def _from_export(model, example_inputs, torch, known): + exported = torch.export.export(model, tuple(example_inputs), strict=False) + graph_module = exported.graph_module + Node = torch.fx.Node + signature = exported.graph_signature + kinds = {} + for spec in signature.input_specs: + name = getattr(spec.arg, 'name', None) + kinds[name] = (spec.kind.name, spec.target) + user_outputs = {getattr(spec.arg, 'name', None) for spec in signature.output_specs + if spec.kind.name == 'USER_OUTPUT'} + graph = _Graph(Node) + for node in graph_module.graph.nodes: + if node.op == 'placeholder': + kind, target = kinds.get(node.name, ('USER_INPUT', None)) + if kind in ('PARAMETER', 'BUFFER', 'CONSTANT_TENSOR'): + if target is not None: + graph.tensor_of[node] = _text(target) + continue + graph.add(node, 'input', 'input', '', [], _values(node.meta.get('val')), {}) + elif node.op == 'get_attr': + graph.tensor_of[node] = _text(node.target) + elif node.op == 'call_function': + stack = node.meta.get('nn_module_stack') or {} + module = _module_path(list(stack.values())[-1][0], known) if stack else '' + values = _node_arguments(node, Node) + tensors = [graph.tensor_of[value] for value in values if value in graph.tensor_of] + entry = graph.add(node, 'operation', _operation_name(node.target), module, + list(dict.fromkeys(tensors)), _values(node.meta.get('val')), + _attributes(node, Node)) + graph.connect(node, entry, [value for value in values if value not in graph.tensor_of]) + elif node.op == 'output': + values = [value for value in _node_arguments(node, Node) + if value not in graph.tensor_of and (not user_outputs or value.name in user_outputs)] + entry = graph.add(node, 'output', 'output', '', [], + [item for value in values if value in graph.ids for item in graph.ids[value]['outputs'][:1]], + {}) + graph.connect(node, entry, values) + if len(graph.nodes) > NODES: + raise _TooLarge(f'The exported graph has more than {NODES} nodes; the module tree alone is written.') + return graph + + +def _from_fx(model, example_inputs, torch, known): + from torch.fx.passes.shape_prop import ShapeProp + traced = torch.fx.symbolic_trace(model) + ShapeProp(traced).propagate(*example_inputs) + Node = torch.fx.Node + graph = _Graph(Node) + owned = {path: [f'{path}.{name}' for name, _ in module.named_parameters()] + + [f'{path}.{name}' for name, _ in module.named_buffers()] + for path, module in traced.named_modules() if path} + for node in traced.graph.nodes: + shapes = _values(node.meta.get('tensor_meta')) + if node.op == 'placeholder': + graph.add(node, 'input', 'input', '', [], shapes, {}) + elif node.op == 'get_attr': + graph.tensor_of[node] = _text(node.target) + elif node.op in ('call_module', 'call_function', 'call_method'): + values = _node_arguments(node, Node) + tensors = [graph.tensor_of[value] for value in values if value in graph.tensor_of] + if node.op == 'call_module': + module = _module_path(node.target, known) + operation = _class(traced.get_submodule(node.target)) + tensors = owned.get(node.target, []) + tensors + sub = traced.get_submodule(node.target) + attributes = {'repr': _text(sub.extra_repr(), 200)} if sub.extra_repr() else {} + else: + module = '' + operation = ('Tensor.' + node.target) if node.op == 'call_method' else _operation_name(node.target) + attributes = _attributes(node, Node) + entry = graph.add(node, 'operation', operation, module, list(dict.fromkeys(tensors)), shapes, + attributes) + graph.connect(node, entry, [value for value in values if value not in graph.tensor_of]) + elif node.op == 'output': + values = [value for value in _node_arguments(node, Node) if value not in graph.tensor_of] + entry = graph.add(node, 'output', 'output', '', [], + [item for value in values if value in graph.ids for item in graph.ids[value]['outputs'][:1]], + {}) + graph.connect(node, entry, values) + if len(graph.nodes) > NODES: + raise _TooLarge(f'The traced graph has more than {NODES} nodes; the module tree alone is written.') + return graph + + +class _TooLarge(Exception): + pass + + +# ------------------------------------------------------------------ writing + +def _destination(path): + path = os.fspath(path) + return os.path.join(path, FILE) if os.path.isdir(path) else path + + +def _write(document, path): + """document as JSON at path, through a file beside it renamed into place (made with the process's umask).""" + folder, name = os.path.split(os.path.abspath(path)) + temporary = os.path.join(folder, f'.{name}.{os.getpid()}.{uuid.uuid4().hex[:8]}.tmp') + try: + with open(temporary, 'x', encoding='utf-8') as out: + json.dump(document, out, ensure_ascii=False, allow_nan=False, separators=(',', ':')) + out.write('\n') + os.replace(temporary, path) + except BaseException: + try: + os.unlink(temporary) + except OSError: + pass + raise + + +def export_graph(model, example_inputs, path): + """Write model's structure, traced on example_inputs (a tensor or a tuple of them), as model-graph.json at + path (a file, or a directory to write model-graph.json in); return what was written.""" + import torch + if isinstance(example_inputs, torch.Tensor): + example_inputs = (example_inputs,) + example_inputs = tuple(example_inputs) + tree, cut = module_tree(model) + known = {path_ for path_, _ in model.named_modules()} + notes = [f'The model has more than {MODULES} modules; the first are listed.'] if cut else [] + inputs = [{'name': f'input{position}', **value} for position, item in enumerate(example_inputs) + for value in _values(item)[:1]][:VALUES] + graph, method, reasons = None, 'module-tree', [] + for name, build in (('torch.export', _from_export), ('torch.fx', _from_fx)): + try: + graph = build(model, example_inputs, torch, known) + method = name + break + except _TooLarge as error: + reasons.append(str(error)) + break + except Exception as error: # a model export or tracing cannot follow; the next way is tried + reasons.append(f'{name} failed ({_first_line(error)})') + if graph is not None and len(graph.edges) > EDGES: + reasons.append(f'The graph has more than {EDGES} edges; the module tree alone is written.') + graph, method = None, 'module-tree' + if graph is not None and reasons: + notes.append('Exported by torch.fx after ' + '; '.join(reasons) + '.') + if graph is not None: + inputs = [{'name': node['id'], **node['outputs'][0]} for node in graph.nodes + if node['kind'] == 'input' and node['outputs']][:VALUES] or inputs + notes.extend(graph.notes) + document = { + 'format': FORMAT, 'complete': graph is not None, + 'reason': None if graph is not None else _text('; '.join(reasons) + '.', TEXT), + 'method': method, 'torch': _text(torch.__version__, 64), 'model': _class(model), 'inputs': inputs, + 'tensors': _tensors(model), 'nodes': graph.nodes if graph is not None else [], + 'edges': graph.edges if graph is not None else [], 'modules': tree, + 'notes': [_text(note) for note in notes[:100]], + } + _write(document, _destination(path)) + return document From 54e309189262f7c8a454d3b6cb2f050aea1cd2c3 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 19 Nov 2026 05:29:45 -0700 Subject: [PATCH 091/131] feat(project): model_graph, model_graph_overlay and model_graph_compare read model-graph.json A standard-library reader that checks the file against its format and bounds, folds the graph to a depth of the module tree, colours modules and operations by parameters, outputs, operations or the change of their weights, and matches two graphs' modules by path. The contract text. Co-Authored-By: Claude Opus 5.5 --- docs/contracts/project-folder.md | 91 +++- tests/test_tuldok_project_model_graph.py | 515 ++++++++++++++++++++ tests/test_tuldok_project_service.py | 8 +- tuldok_project/inside_graph.py | 586 +++++++++++++++++++++++ tuldok_project/operations.py | 23 +- tuldok_project/service.py | 20 +- 6 files changed, 1234 insertions(+), 9 deletions(-) create mode 100644 tests/test_tuldok_project_model_graph.py create mode 100644 tuldok_project/inside_graph.py diff --git a/docs/contracts/project-folder.md b/docs/contracts/project-folder.md index e922414a..e12fd409 100644 --- a/docs/contracts/project-folder.md +++ b/docs/contracts/project-folder.md @@ -2285,6 +2285,9 @@ and result keys of each operation are in its contract. | `array_tiles` | inspect | Read tiles of two axes of an array in a finished run's product, one per position along a third axis, as 32-bit floats. | | `fields` | inspect | List the fields a finished run's product kept: each case's native and predicted files, its name, shape and whether the two can be compared, and the figures the run reported itself. | | `field_compare` | inspect | Read a slice of one kept case's native field, predicted field and signed error as 32-bit floats, with the figures of the error over the whole field. | +| `model_graph` | inspect | Read the structure a finished run's script recorded (model-graph.json): its operations and the edges between them, folded to a depth of the module tree with modules opened or closed by path, and the module tree. | +| `model_graph_overlay` | inspect | Read a number per module and per operation of a finished run's model graph: parameters, output values, operations, or the relative change of the weights under it against the weights it started from or another run's. | +| `model_graph_compare` | inspect | Match the modules of two finished runs' model graphs by path: the same, changed (class or tensor shapes), added or missing. | | `set_definition` | edit | Check a definition's text and keep it as an unsaved edit. | | `remove_definition` | edit | Mark a definition that nothing uses as removed, until the project is saved. | | `revert_definition` | edit | Put back the file in the folder in place of a definition's unsaved edit or removal, or drop a definition the folder has no file for. | @@ -2394,7 +2397,8 @@ project stay command-line actions. A **product** is the `output` directory of a run in state `succeeded` or `adopted`, named by its run id (or an unambiguous prefix of it). The operations `records`, `record`, `inside`, `array_slice`, `array_summary`, -`array_tiles`, `weights`, `weights_compare`, `fields` and `field_compare` read it; each takes `run`, and a run that does not exist, has not finished or +`array_tiles`, `weights`, `weights_compare`, `fields`, `field_compare`, +`model_graph`, `model_graph_overlay` and `model_graph_compare` read it; each takes `run`, and a run that does not exist, has not finished or has no output directory is refused `not-found`. Like every operation they open the project for a moment, to find the run and the view of its dataset; they read the product after closing it and write nothing: no file, no row. @@ -2721,6 +2725,91 @@ floats with `math.fsum` and `math.sumprod`; a figure that would overflow is null, as all of them are when no cell counts. A case's figures are kept while its files are unchanged, so asking for another slice reads only the slice. +### A model's structure + +A run's **model graph** is the file `model-graph.json` at the top of its +product, or beside one of its weights files (see above). The project's own +training script writes it, once, with an example input, where the model's +code runs: Tuldok never imports or runs a project's model. The optional +helper `tuldok_log.graph.export_graph(model, example_inputs, path)` writes it +for a PyTorch model (with `torch.export`, else `torch.fx`, else the module +tree alone); a script may also write it itself. + +```json +{"format": "tuldok_model_graph_v1", "complete": true, "reason": null, + "method": "torch.export", "torch": "2.8.0+cpu", "model": "nets.Net", + "inputs": [{"name": "x", "shape": [2, 1, 8, 8], "dtype": "float32"}], + "tensors": {"stem.weight": {"shape": [4, 1, 3, 3], "dtype": "float32", "kind": "parameter"}}, + "nodes": [{"id": "conv2d", "kind": "operation", "operation": "aten.conv2d.default", + "module": "stem", "tensors": ["stem.weight", "stem.bias"], + "inputs": [{"shape": [2, 1, 8, 8], "dtype": "float32"}], + "outputs": [{"shape": [2, 4, 8, 8], "dtype": "float32"}], + "attributes": {"padding": [1, 1]}}], + "edges": [{"from": "x", "to": "conv2d", "input": 0}], + "modules": {"path": "", "class": "nets.Net", "parameters": 1234, "children": [ + {"path": "stem", "class": "torch.nn.modules.conv.Conv2d", "parameters": 40, "children": []}]}, + "notes": []} +``` + +- Required: `format` (`tuldok_model_graph_v1`), `complete`, `tensors`, + `nodes`, `edges`, `modules`. `complete` false means only the module tree + was written; `reason` says why, and `nodes` and `edges` are not read. +- `tensors` are the model's parameters and buffers by the names of its + `state_dict` (the names of its weights file), each `shape`, `dtype` and + `kind` (`parameter`, `buffer` or `constant`). +- `nodes`, each after the nodes it reads: `id` (unique, not beginning + `module:`), `kind` (`input`, `operation` or `output`), `operation`, + `module` (the path of the deepest module it ran in, `""` for the model; a + path the tree does not list is read as its nearest listed parent), + `tensors` (names in `tensors` it reads), `inputs` and `outputs` (each + `shape` and `dtype`; a size is a whole number, or the name of a symbol), + `attributes` (optional: numbers, booleans, strings, null or short lists of + those). `edges` go `from` a node `to` a node; `input` is the position among + the values of `to`. +- `modules` is the tree of the model's modules, rooted at path `""`; each + child's path extends its parent's; `parameters` counts every parameter + under a module. +- Bounds: 32 MiB (refused `too-large` beyond), 20,000 nodes, 100,000 edges, + 20,000 modules, 64 deep, 100,000 tensors, 64 tensor names and 16 inputs or + outputs per node, 16 axes, 16 attributes, 1,024 characters per string. A + file that is not UTF-8 JSON (`NaN` and `Infinity` are not JSON), not of the + format, or past a bound is refused `unsupported`, saying what. + +**`model_graph`** takes `depth` (0 to 64; by default 1 when the graph has more +than 200 operations, else 64), `open` and `close` (module paths, at most +2,000 each). A module's depth is its count of dotted parts; it is open when +named in `open`, or when its depth is at most `depth` and it is not named in +`close`. An operation inside a closed module is shown as the shallowest +closed module on its path: a node of kind `group`, id `module:`, with +`operations` (how many it holds), `tensors` (those its operations read, at +most 64, and `tensor_count`), `parameters` (the module's), and `inputs` and +`outputs` (the values that cross into and out of it). Edges between the +same two shown nodes are one, with `count`; an edge inside a group is +dropped; each carries the `shape` and `dtype` of the first value it carries. +The answer also gives the file's `path`, `complete`, `reason`, `method`, +`torch`, `model`, `inputs`, `notes`, `counts`, the `modules` tree, the +`tensors`, the `depth` used and `open` (the modules open in effect). + +**`model_graph_overlay`** takes `kind`: `parameters` (a module's from the +tree; an operation's, the sizes of its tensors that are parameters), +`outputs` (the values an operation gives; a module's, the sum over its +operations; null for a symbolic size), `operations` (how many run in a +module), or `change`, with `against` `start` (the `initial-` file beside the +weights file) or `run` (with `other_run`), and optionally `path` and +`other_path` (weights files; by default the first readable one). The change +of a module is computed from `weights_compare`'s rows of the tensors under +it, `sqrt(sum difference_norm^2) / sqrt(sum other_norm^2)`, null when none +is compared, when the other's norm is zero or a norm is not finite. It +answers `kind`, `unit`, `modules` and `nodes` (a number or null each), +`low` and `high`, and for `change` `against`. + +**`model_graph_compare`** takes `other_run` and matches the two trees' +modules by path: each module of either, in this tree's order then the +other's, with `status` `same`, `changed` (its class differs, or a tensor +directly in it changed shape or is on one side only), `added` (here only) or +`missing` (there only), both classes and parameter counts, `reshaped`, +`only_here` and `only_there`; and `counts` by status. + ### Annotating The five operations on annotations (see [Annotations in the database](#annotations-in-the-database)) diff --git a/tests/test_tuldok_project_model_graph.py b/tests/test_tuldok_project_model_graph.py new file mode 100644 index 00000000..bcfd41d4 --- /dev/null +++ b/tests/test_tuldok_project_model_graph.py @@ -0,0 +1,515 @@ +"""A model's structure, read from model-graph.json (docs/plans/training-and-curation/spec-t2.md, slice T2a). + +The reader is tested on graph files the tests write by hand, and on the two +committed under tests/fixtures/model_graph (written once by +tuldok_log.graph.export_graph through tests/project_structure_fixture_export.py), +with no database: a Product is a directory. The weights the change overlay +compares are .npz files written with the standard library. The operations +run through the service only when TULDOK_DATABASE_URL names a disposable +cluster. No PyTorch and no GPU are used. +""" +import copy +import hashlib +import json +import math +import os +from pathlib import Path +import sys +import tempfile +import unittest +from unittest import mock + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) +sys.path.insert(0, str(Path(__file__).resolve().parent)) + +import agent_api # noqa: E402 +from tuldok_project import adoption, inside, inside_archive, inside_graph, local, operations, store # noqa: E402 +from tuldok_project.service import Service # noqa: E402 +import test_tuldok_project_builds as builds_base # noqa: E402 +from test_tuldok_project_inside import OWNER, npy, zip_bytes # noqa: E402 + +FIXTURES = Path(__file__).resolve().parent / 'fixtures' / 'model_graph' +GRAPH_OPERATIONS = ('model_graph', 'model_graph_overlay', 'model_graph_compare') + + +def value(*shape): + return {'shape': list(shape), 'dtype': 'float32'} + + +def module(path, kind, parameters, *children): + return {'path': path, 'class': kind, 'parameters': parameters, 'children': list(children)} + + +def node(identifier, kind, module_path, tensors=(), outputs=(), operation=None, attributes=None): + return {'id': identifier, 'kind': kind, 'operation': operation or (kind if kind != 'operation' else 'aten.x'), + 'module': module_path, 'tensors': list(tensors), 'inputs': [], 'outputs': list(outputs), + 'attributes': attributes or {}} + + +TENSORS = {'enc.0.weight': (4, 4), 'enc.0.bias': (4,), 'enc.1.weight': (2, 4), 'enc.1.bias': (2,), + 'head.weight': (3, 2), 'head.bias': (3,)} + + +def hand_graph(): + """A model of 39 parameters: enc (a Sequential of two Linear, enc.0 and enc.1, with a ReLU run in enc itself) + and head (a Linear with a buffer), and an add in the model itself that takes a skip from enc.0 and two values + from enc (the ReLU and head).""" + tensors = {name: {'shape': list(shape), 'dtype': 'float32', 'kind': 'parameter'} for name, shape in TENSORS.items()} + tensors['head.scale'] = {'shape': [3], 'dtype': 'float32', 'kind': 'buffer'} + return { + 'format': 'tuldok_model_graph_v1', 'complete': True, 'reason': None, 'method': 'torch.export', + 'torch': '2.8.0+cpu', 'model': 'tests.Net', 'inputs': [{'name': 'x', **value(1, 4)}], + 'tensors': tensors, + 'nodes': [ + node('x', 'input', '', outputs=[value(1, 4)], operation='input'), + node('a', 'operation', 'enc.0', ['enc.0.weight', 'enc.0.bias'], [value(1, 4)], 'aten.linear.default', + {'bias': True}), + node('r', 'operation', 'enc', [], [value(1, 4)], 'aten.relu.default'), + node('b', 'operation', 'enc.1', ['enc.1.weight', 'enc.1.bias'], [value(1, 2)], 'aten.linear.default'), + node('c', 'operation', 'head', ['head.weight', 'head.bias', 'head.scale'], [value(1, 3)], + 'aten.linear.default'), + node('d', 'operation', '', [], [value(1, 3)], 'aten.add.Tensor', {'alpha': 1, 'dims': [1, 2]}), + node('out', 'output', '', outputs=[value(1, 3)], operation='output')], + 'edges': [{'from': 'x', 'to': 'a', 'input': 0}, {'from': 'a', 'to': 'r', 'input': 0}, + {'from': 'r', 'to': 'b', 'input': 0}, {'from': 'b', 'to': 'c', 'input': 0}, + {'from': 'c', 'to': 'd', 'input': 0}, {'from': 'a', 'to': 'd', 'input': 1}, + {'from': 'r', 'to': 'd', 'input': 2}, {'from': 'd', 'to': 'out', 'input': 0}], + 'modules': module('', 'tests.Net', 39, + module('enc', 'torch.nn.Sequential', 30, module('enc.0', 'torch.nn.Linear', 20), + module('enc.1', 'torch.nn.Linear', 10)), + module('head', 'torch.nn.Linear', 9)), + 'notes': []} + + +def npz(arrays): + """An .npz of {name: (shape, [values])} in float32.""" + return zip_bytes({name + '.npy': npy(shape, ' r and r -> b are inside enc and dropped; a -> d and r -> d are one edge of two + self.assertEqual(self.edges(answer), [('x', 'module:enc', 1), ('module:enc', 'module:head', 1), + ('module:head', 'd', 1), ('module:enc', 'd', 2), ('d', 'out', 1)]) + enc = answer['nodes'][1] + self.assertEqual((enc['kind'], enc['label'], enc['class'], enc['operations'], enc['parameters'], + enc['tensors'], enc['tensor_count'], enc['first']), + ('group', 'enc', 'torch.nn.Sequential', 3, 30, + ['enc.0.weight', 'enc.0.bias', 'enc.1.weight', 'enc.1.bias'], 4, 1)) + self.assertEqual(enc['inputs'], [value(1, 4)]) + self.assertEqual(enc['outputs'], [value(1, 2), value(1, 4)], 'b -> c, then a -> d (r -> d merged with it)') + self.assertEqual(answer['open'], []) + + def test_folded_at_depth_one(self): + answer = self.graph(depth=1) + self.assertEqual([item['id'] for item in answer['nodes']], + ['x', 'module:enc.0', 'r', 'module:enc.1', 'c', 'd', 'out']) + self.assertEqual(len(answer['edges']), 8 - 0) + self.assertEqual(answer['open'], ['enc', 'head']) + + def test_opened_and_closed_by_name(self): + closed = self.graph(closed=['enc']) + self.assertEqual([item['id'] for item in closed['nodes']], ['x', 'module:enc', 'c', 'd', 'out']) + self.assertEqual(closed['open'], ['head']) + # A module opened under a closed one stays inside it. + inner = self.graph(depth=0, opened=['enc.1']) + self.assertEqual([item['id'] for item in inner['nodes']], ['x', 'module:enc', 'module:head', 'd', 'out']) + opened = self.graph(depth=0, opened=['enc', 'enc.1']) + self.assertEqual([item['id'] for item in opened['nodes']], + ['x', 'module:enc.0', 'r', 'b', 'module:head', 'd', 'out']) + self.assertEqual(opened['open'], ['enc', 'enc.1']) + + def test_large_graphs_start_at_depth_one(self): + with mock.patch.object(inside_graph, 'LARGE', 4): + self.assertEqual(self.graph()['depth'], 1) + self.assertEqual(self.graph()['depth'], 64) + + def test_a_module_the_tree_does_not_list_is_its_nearest_listed_parent(self): + document = hand_graph() + document['nodes'][2]['module'] = 'enc.ghost.deeper' + self.write(document) + self.assertEqual(self.graph()['nodes'][2]['module'], 'enc') + + +class Refusals(ReaderCase): + + def check(self, document, code='unsupported', **patches): + self.write(document) + inside_graph.forget() + with mock.patch.multiple(inside_graph, **patches) if patches else _nothing(): + return self.refused(code, inside_graph.model_graph, self.product) + + def changed(self, change): + document = hand_graph() + change(document) + return document + + def test_each_refusal(self): + self.assertIn('not JSON', self.check('{"format": ')) + self.assertIn('not JSON', self.check(b'\xff\xfe'.decode('latin-1'))) + self.assertIn('not JSON', self.check('[' * 100_000 + ']' * 100_000)) + self.assertIn('not JSON', self.check(json.dumps(hand_graph()).replace('"alpha": 1', '"alpha": NaN'))) + self.assertIn('format', self.check(self.changed(lambda d: d.update(format='other_v1')))) + self.assertIn('has no modules', self.check(self.changed(lambda d: d.pop('modules')))) + self.assertIn('complete', self.check(self.changed(lambda d: d.update(complete='yes')))) + self.assertIn('used twice', self.check(self.changed(lambda d: d['nodes'][2].update(id='a')))) + self.assertIn('names no node', self.check(self.changed(lambda d: d['edges'][0].update(to='nowhere')))) + self.assertIn('kind', self.check(self.changed(lambda d: d['nodes'][1].update(kind='layer')))) + self.assertIn('sizes', self.check(self.changed(lambda d: d['nodes'][1]['outputs'][0].update(shape=[-1])))) + self.assertIn('may not begin', self.check(self.changed(lambda d: d['nodes'][1].update(id='module:a')))) + self.assertIn('start at the model', self.check(self.changed(lambda d: d['modules'].update(path='net')))) + self.assertIn('extend its parent', self.check(self.changed( + lambda d: d['modules']['children'][0]['children'][0].update(path='other.0')))) + self.assertIn('listed twice', self.check(self.changed( + lambda d: d['modules']['children'][1].update(path='enc')))) + self.assertIn('short list', self.check(self.changed( + lambda d: d['nodes'][1]['attributes'].update(nested={'a': 1})))) + self.assertIn('at most 6', self.check(hand_graph(), NODES=6)) + self.assertIn('at most 7', self.check(hand_graph(), EDGES=7)) + self.assertIn('more than 4 modules', self.check(hand_graph(), MODULES=4)) + self.assertIn('deeper than 1', self.check(hand_graph(), DEPTH=1)) + self.assertIn('at most 1 are read', self.check(hand_graph(), NODE_TENSORS=1)) + self.assertIn('bytes', self.check(hand_graph(), code='too-large', FILE_BYTES=100)) + + def test_no_file_is_not_found(self): + self.refused('not-found', inside_graph.model_graph, self.product) + + def test_a_module_tree_alone(self): + document = hand_graph() + document.update(complete=False, reason='torch.export failed (data-dependent); torch.fx failed.', + method='module-tree') + document['edges'].append({'from': 'nowhere', 'to': 'x'}) # ignored with the nodes + self.write(document) + answer = inside_graph.model_graph(self.product, depth=0) + self.assertEqual((answer['complete'], answer['reason'], answer['nodes'], answer['edges']), + (False, document['reason'], [], [])) + self.assertEqual(answer['counts']['modules'], 5) + self.assertEqual(answer['modules']['parameters'], 39) + + +class _nothing: + def __enter__(self): + return self + + def __exit__(self, *_): + return False + + +class Finding(ReaderCase): + + def test_beside_a_declared_weights_file(self): + product = self.make_product('run-2', outputs={'model': {'path': 'out/weights.npz', 'role': 'weights'}}) + Path(product.root, 'out').mkdir() + Path(product.root, 'out', 'weights.npz').write_bytes(npz(weights(lambda name, n: n))) + self.write(hand_graph(), product, 'out/model-graph.json') + self.assertEqual(inside_graph.model_graph(product)['path'], 'out/model-graph.json') + self.write(hand_graph(), product) # the top of the product comes first + self.assertEqual(inside_graph.model_graph(product)['path'], 'model-graph.json') + + def test_kept_while_unchanged(self): + path = self.write(hand_graph()) + first = inside_graph.graph_of(self.product)[1] + self.assertIs(inside_graph.graph_of(self.product)[1], first) + document = hand_graph() + document['torch'] = '2.9.0' + path.write_text(json.dumps(document) + ' ' * 7, encoding='utf-8') + self.assertEqual(inside_graph.graph_of(self.product)[1].torch, '2.9.0') + + +class Overlays(ReaderCase): + + def setUp(self): + super().setUp() + self.write(hand_graph()) + + def overlay(self, product=None, **arguments): + answer = inside_graph.model_graph_overlay(product or self.product, **arguments) + json.dumps(answer, allow_nan=False) + return answer + + def test_counts(self): + parameters = self.overlay(kind='parameters') + self.assertEqual(parameters['modules'], {'': 39, 'enc': 30, 'enc.0': 20, 'enc.1': 10, 'head': 9}) + self.assertEqual(parameters['nodes'], {'a': 20, 'r': 0, 'b': 10, 'c': 9, 'd': 0}) + self.assertEqual((parameters['unit'], parameters['low'], parameters['high']), ('parameters', 0, 39)) + outputs = self.overlay(kind='outputs') + self.assertEqual(outputs['nodes'], {'a': 4, 'r': 4, 'b': 2, 'c': 3, 'd': 3}) + self.assertEqual(outputs['modules'], {'': 16, 'enc': 10, 'enc.0': 4, 'enc.1': 2, 'head': 3}) + counted = self.overlay(kind='operations') + self.assertEqual(counted['modules'], {'': 5, 'enc': 3, 'enc.0': 1, 'enc.1': 1, 'head': 1}) + self.assertEqual(set(counted['nodes'].values()), {1}) + + def test_a_symbolic_size_has_no_output_count(self): + document = hand_graph() + document['nodes'][3]['outputs'] = [{'shape': ['s0', 2], 'dtype': 'float32'}] + self.write(document) + outputs = self.overlay(kind='outputs') + self.assertEqual((outputs['nodes']['b'], outputs['modules']['enc.1'], outputs['modules']['enc'], + outputs['modules']['head']), (None, None, None, 3)) + + def expected_change(self, here, there, names): + difference = math.fsum((a - b) ** 2 for name in names for a, b in zip(here[name][1], there[name][1])) + other = math.fsum(b * b for name in names for b in there[name][1]) + return math.sqrt(difference) / math.sqrt(other) + + def test_change_against_the_start_and_another_run(self): + start = weights(lambda name, n: 1 + n % 3) + trained = weights(lambda name, n: (1 + n % 3) * (2 if name.startswith('enc.0') else 1) + + (0.5 if name == 'head.bias' else 0)) + Path(self.product.root, 'weights.npz').write_bytes(npz(trained)) + Path(self.product.root, 'initial-weights.npz').write_bytes(npz(start)) + answer = self.overlay(kind='change', against='start') + self.assertEqual(answer['against'], {'kind': 'start', 'run': 'run-1', 'path': 'weights.npz', + 'other_run': 'run-1', 'other_path': 'initial-weights.npz'}) + for path, names in (('enc.0', ['enc.0.weight', 'enc.0.bias']), ('enc', [n for n in TENSORS if + n.startswith('enc.')]), + ('head', ['head.weight', 'head.bias']), ('', list(TENSORS))): + self.assertAlmostEqual(answer['modules'][path], self.expected_change(trained, start, names), 12, path) + self.assertEqual(answer['modules']['enc.1'], 0.0) + self.assertAlmostEqual(answer['nodes']['a'], 1.0, 12) + self.assertAlmostEqual(answer['nodes']['c'], self.expected_change(trained, start, ['head.weight', + 'head.bias']), 12) + self.assertIsNone(answer['nodes']['r'], 'r reads no tensor') + self.assertEqual((answer['low'], answer['high']), (0.0, 1.0)) + # Another run, whose weights are the start: the same numbers. + other = self.make_product('run-0') + Path(other.root, 'weights.npz').write_bytes(npz(start)) + against = self.overlay(kind='change', against='run', other=other) + self.assertEqual(against['modules'], answer['modules']) + self.assertEqual(against['against']['other_run'], 'run-0') + + def test_change_with_zero_and_missing_tensors(self): + start = weights(lambda name, n: 0 if name.startswith('head') else 1) + trained = weights(lambda name, n: 2) + del trained['enc.1.bias'] + Path(self.product.root, 'weights.npz').write_bytes(npz(trained)) + Path(self.product.root, 'initial-weights.npz').write_bytes(npz(start)) + answer = self.overlay(kind='change', against='start') + self.assertIsNone(answer['modules']['head'], 'it started at zero') + self.assertAlmostEqual(answer['modules']['enc.1'], 1.0, 12, 'over the one tensor compared') + + def test_change_refusals(self): + self.refused('not-found', self.overlay, kind='change', against='start') # no weights file + Path(self.product.root, 'weights.npz').write_bytes(npz(weights(lambda name, n: 1))) + self.refused('not-found', self.overlay, kind='change', against='start') # no initial- file + self.refused('invalid', self.overlay, kind='change', against='run') # no other run + self.refused('invalid', self.overlay, kind='change') + self.refused('invalid', self.overlay, kind='time') + + +class Comparing(ReaderCase): + + def test_modules_matched_by_path(self): + here = hand_graph() + there = copy.deepcopy(here) + there['tensors']['enc.1.weight']['shape'] = [3, 4] + there['modules']['children'][0]['children'][0]['class'] = 'torch.nn.LazyLinear' + there['modules']['children'][1] = module('tail', 'torch.nn.Linear', 9) + del there['tensors']['head.weight'], there['tensors']['head.bias'], there['tensors']['head.scale'] + there['tensors']['tail.weight'] = {'shape': [3, 2], 'dtype': 'float32', 'kind': 'parameter'} + there['nodes'][4]['module'] = 'tail' + there['nodes'][4]['tensors'] = ['tail.weight'] + other = self.make_product('run-0') + self.write(here) + self.write(there, other) + answer = inside_graph.model_graph_compare(self.product, other=other) + rows = {row['path']: row for row in answer['modules']} + self.assertEqual([row['path'] for row in answer['modules']], ['', 'enc', 'enc.0', 'enc.1', 'head', 'tail']) + self.assertEqual({path: row['status'] for path, row in rows.items()}, + {'': 'same', 'enc': 'same', 'enc.0': 'changed', 'enc.1': 'changed', 'head': 'added', + 'tail': 'missing'}) + self.assertEqual(rows['enc.1']['reshaped'], [{'name': 'enc.1.weight', 'shape': [2, 4], 'other_shape': [3, 4]}]) + self.assertEqual((rows['enc.0']['class'], rows['enc.0']['other_class']), + ('torch.nn.Linear', 'torch.nn.LazyLinear')) + self.assertEqual((rows['tail']['class'], rows['tail']['other_parameters']), (None, 9)) + self.assertEqual(answer['counts'], {'same': 2, 'changed': 2, 'added': 1, 'missing': 1}) + + +class Fixtures(ReaderCase): + """The two graphs export_graph wrote (tests/project_structure_fixture_export.py), read as Tuldok reads them.""" + + def test_the_committed_graphs(self): + products = {} + for name in ('parent', 'derived'): + products[name] = self.make_product(name) + self.write((FIXTURES / f'{name}.json').read_text(encoding='utf-8'), products[name]) + answer = inside_graph.model_graph(products[name]) + self.assertEqual((answer['complete'], answer['method'], answer['inputs'][0]['shape']), + (True, 'torch.export', [2, 1, 8, 8])) + for item in answer['nodes']: + self.assertTrue(set(item['tensors']) <= set(answer['tensors']), item['id']) + used = {tensor for item in answer['nodes'] for tensor in item['tensors']} + self.assertEqual(used, set(answer['tensors']), 'every parameter is read by some operation') + adds = [item for item in answer['nodes'] if item['operation'] == 'aten.add.Tensor'] + self.assertEqual([item['module'] for item in adds], ['blocks.0', 'blocks.1']) + edges_in = [edge for edge in answer['edges'] if edge['to'] == adds[0]['id']] + self.assertEqual(len(edges_in), 2, 'the residual add takes the block\'s input and its last convolution') + parameters = sum(math.prod(t['shape']) for t in answer['tensors'].values()) + self.assertEqual(answer['modules']['parameters'], parameters) + folded = inside_graph.model_graph(products[name], depth=0) + self.assertIn('module:blocks', [item['id'] for item in folded['nodes']]) + compared = inside_graph.model_graph_compare(products['derived'], other=products['parent']) + status = {row['path']: row['status'] for row in compared['modules']} + self.assertEqual({path for path, state in status.items() if state != 'same'}, {'head.0', 'head.2', 'gate'}) + self.assertEqual((status['head.0'], status['gate']), ('changed', 'added')) + + +# ------------------------------------------------------------------ through the service + +class GraphProducts(builds_base.BuildCase): + """recipes/fit-a adopted twice, each product with the derived fixture's graph and a weights.npz.""" + + def setUp(self): + super().setUp() + patcher = mock.patch.dict(os.environ, {local.SETTINGS_VARIABLE: str(self.temporary / 'settings.json')}) + patcher.start() + self.addCleanup(patcher.stop) + inside_archive.forget_members() + inside.forget_indexes() + inside_graph.forget() + + def declare(document): + document['run']['outputs'] = {'model': {'path': 'weights.npz', 'role': 'weights'}, + 'graph': {'path': 'model-graph.json', 'role': 'file'}} + self.edit('recipes/fit-a', declare) + graph = json.loads((FIXTURES / 'derived.json').read_text(encoding='utf-8')) + self.runs_made = [] + for scale in (1.0, 2.0): + source = self.temporary / f'weights-{scale}.npz' + source.write_bytes(zip_bytes({name + '.npy': npy(tuple(t['shape']), ' Graph + + +def _refuse(message, code='unsupported'): + raise ProjectError(message, code) + + +def forget(): + with _lock: + _kept.clear() + + +# ---------------------------------------------------------------- checking the file + +class _Check: + """Checks the parts of a decoded file, naming where a problem is.""" + + @staticmethod + def text(value, where, *, empty=True): + if not isinstance(value, str) or len(value) > TEXT or (not empty and not value): + _refuse(f'{FILE}: {where} must be a string of {"1" if not empty else "0"} to {TEXT} characters.') + return value + + @staticmethod + def optional_text(value, where): + return None if value is None else _Check.text(value, where) + + @staticmethod + def items(value, where, most): + if not isinstance(value, list): + _refuse(f'{FILE}: {where} must be a list.') + if len(value) > most: + _refuse(f'{FILE}: {where} holds {len(value)} items; at most {most} are read.') + return value + + @staticmethod + def mapping(value, where, keys=()): + if not isinstance(value, dict): + _refuse(f'{FILE}: {where} must be an object.') + missing = [key for key in keys if key not in value] + if missing: + _refuse(f'{FILE}: {where} has no {", ".join(missing)}.') + return value + + @staticmethod + def count(value, where): + if type(value) is not int or value < 0: + _refuse(f'{FILE}: {where} must be a whole number of at least 0.') + return value + + @classmethod + def shape(cls, value, where): + cls.items(value, where, AXES) + for size in value: + if not ((type(size) is int and size >= 0) or (isinstance(size, str) and 0 < len(size) <= 64)): + _refuse(f'{FILE}: {where} must hold sizes (whole numbers of at least 0, or names of a symbol).') + return list(value) + + @classmethod + def value(cls, value, where, named=False): + cls.mapping(value, where, ('shape', 'dtype') + (('name',) if named else ())) + out = {'shape': cls.shape(value['shape'], where + '.shape'), 'dtype': cls.text(value['dtype'], where + '.dtype')} + if named: + out = {'name': cls.text(value['name'], where + '.name'), **out} + return out + + @classmethod + def values(cls, value, where, named=False): + return [cls.value(item, f'{where}[{i}]', named) for i, item in enumerate(cls.items(value, where, VALUES))] + + @classmethod + def attribute(cls, value, where, nested=False): + if value is None or isinstance(value, (bool, int, str)): + if isinstance(value, str): + cls.text(value, where) + return value + if isinstance(value, float): + return value + if isinstance(value, list) and not nested: + return [cls.attribute(item, where, True) for item in cls.items(value, where, LIST)] + _refuse(f'{FILE}: {where} must be a number, a boolean, a string, null or a short list of those.') + + +def _no_constant(name): + raise ValueError(f'{name} is not JSON') + + +class Graph: + """A checked model-graph.json: its fields, its nodes and edges, and its module tree, flat and as given.""" + + def __init__(self, document): + c = _Check + c.mapping(document, 'the file', ('format', 'complete', 'nodes', 'edges', 'modules', 'tensors')) + if document['format'] != FORMAT: + _refuse(f'{FILE}: format must be {FORMAT}.') + if not isinstance(document['complete'], bool): + _refuse(f'{FILE}: complete must be true or false.') + self.complete = document['complete'] + self.reason = c.optional_text(document.get('reason'), 'reason') + self.method = c.optional_text(document.get('method'), 'method') + self.torch = c.optional_text(document.get('torch'), 'torch') + self.model = c.optional_text(document.get('model'), 'model') + self.inputs = c.values(document.get('inputs', []), 'inputs', named=True) + self.notes = [c.text(note, f'notes[{i}]') for i, note in enumerate(c.items(document.get('notes', []), + 'notes', NOTES))] + self._tensors(document['tensors']) + self._modules(document['modules']) + self._nodes(document['nodes'] if self.complete else []) + self._edges(document['edges'] if self.complete else []) + self.operations = sum(1 for node in self.nodes if node['kind'] == 'operation') + + def _tensors(self, value): + c = _Check + c.mapping(value, 'tensors') + if len(value) > TENSORS: + _refuse(f'{FILE}: tensors holds {len(value)} tensors; at most {TENSORS} are read.') + self.tensors = {} + for name, item in value.items(): + where = f'tensors[{name[:80]!r}]' + c.text(name, where, empty=False) + c.mapping(item, where, ('shape', 'dtype')) + kind = item.get('kind', 'parameter') + if kind not in TENSOR_KINDS: + _refuse(f'{FILE}: {where}.kind must be one of {", ".join(TENSOR_KINDS)}.') + self.tensors[name] = {'shape': c.shape(item['shape'], where + '.shape'), + 'dtype': c.text(item['dtype'], where + '.dtype'), 'kind': kind} + + def _modules(self, root): + """The tree, checked without recursion: self.tree (as answered) and self.modules {path: info}, in the tree's + depth-first order.""" + c = _Check + self.modules = collections.OrderedDict() + c.mapping(root, 'modules', ('path', 'class', 'parameters', 'children')) + if root['path'] != '': + _refuse(f'{FILE}: the module tree must start at the model itself, path "".') + self.tree = {} + stack = [(root, None, 0, self.tree)] + while stack: + item, parent, depth, out = stack.pop() + where = f'modules {str(item.get("path", "?"))[:80]!r}' if isinstance(item, dict) else 'modules' + c.mapping(item, where, ('path', 'class', 'parameters', 'children')) + path = c.text(item['path'], where + '.path') + if parent is not None and (not path or (parent and not path.startswith(parent + '.'))): + _refuse(f'{FILE}: {where}: a module\'s path must extend its parent\'s ({parent!r}).') + if path in self.modules: + _refuse(f'{FILE}: the module {path[:80]!r} is listed twice.') + if len(self.modules) >= MODULES: + _refuse(f'{FILE}: the module tree holds more than {MODULES} modules.') + children = c.items(item['children'], where + '.children', MODULES) + if children and depth >= DEPTH: + _refuse(f'{FILE}: the module tree is deeper than {DEPTH}.') + kids = [{} for _ in children] + out.update({'path': path, 'class': c.text(item['class'], where + '.class'), + 'parameters': c.count(item['parameters'], where + '.parameters'), 'children': kids}) + self.modules[path] = {'class': out['class'], 'parameters': out['parameters'], 'parent': parent, + 'depth': 0 if not path else path.count('.') + 1, 'children': []} + if parent is not None: + self.modules[parent]['children'].append(path) + for child, kid in reversed(list(zip(children, kids))): + stack.append((child, path, depth + 1, kid)) + + def _nodes(self, value): + c = _Check + self.nodes, self.index = [], {} + for i, item in enumerate(c.items(value, 'nodes', NODES)): + where = f'nodes[{i}]' + c.mapping(item, where, ('id', 'kind', 'operation', 'module', 'tensors', 'inputs', 'outputs')) + identifier = c.text(item['id'], where + '.id', empty=False) + if identifier.startswith(GROUP): + _refuse(f'{FILE}: {where}.id may not begin "{GROUP}".') + if identifier in self.index: + _refuse(f'{FILE}: the node id {identifier[:80]!r} is used twice.') + if item['kind'] not in NODE_KINDS: + _refuse(f'{FILE}: {where}.kind must be one of {", ".join(NODE_KINDS)}.') + module = c.text(item['module'], where + '.module') + while module and module not in self.modules: + module = module.rpartition('.')[0] # a module the tree does not list: its nearest listed parent + tensors = [c.text(name, f'{where}.tensors', empty=False) + for name in c.items(item['tensors'], where + '.tensors', NODE_TENSORS)] + attributes = c.mapping(item.get('attributes', {}), where + '.attributes') + if len(attributes) > ATTRIBUTES: + _refuse(f'{FILE}: {where}.attributes holds more than {ATTRIBUTES} attributes.') + self.index[identifier] = len(self.nodes) + self.nodes.append({ + 'id': identifier, 'kind': item['kind'], 'operation': c.text(item['operation'], where + '.operation'), + 'module': module, 'tensors': list(dict.fromkeys(tensors)), + 'inputs': c.values(item['inputs'], where + '.inputs'), + 'outputs': c.values(item['outputs'], where + '.outputs'), + 'attributes': {c.text(key, where + '.attributes', empty=False)[:200]: + c.attribute(entry, f'{where}.attributes') for key, entry in attributes.items()}}) + + def _edges(self, value): + c = _Check + self.edges = [] + for i, item in enumerate(c.items(value, 'edges', EDGES)): + where = f'edges[{i}]' + c.mapping(item, where, ('from', 'to')) + ends = [] + for key in ('from', 'to'): + if not isinstance(item[key], str) or item[key] not in self.index: + _refuse(f'{FILE}: {where}.{key} names no node.') + ends.append(self.index[item[key]]) + self.edges.append((ends[0], ends[1], c.count(item.get('input', 0), where + '.input'))) + + +def _read(place): + if (place.size or 0) > FILE_BYTES: + _refuse(f'{place.address} is {place.size} bytes; at most {FILE_BYTES} are read.', 'too-large') + raw = bytes(place.head(place.size or 0)) + try: + document = json.loads(raw.decode('utf-8'), parse_constant=_no_constant) + except (ValueError, RecursionError): + _refuse(f'{place.address} is not JSON.') + return Graph(document) + + +def _graph_place(product): + """The Place of a run's graph file: at the top of the product, else beside one of its weights files.""" + candidates = [FILE] + for address, _ in inside_weights.weight_files(product): + folder = address.rpartition('/')[0] + candidates.append(f'{folder}/{FILE}' if folder else FILE) + for address in dict.fromkeys(candidates): + try: + place = locate(product.root, address) + except ProjectError: + continue + if place.kind == 'file': + return place + raise ProjectError(f'Run {product.run_id} has no {FILE}.', 'not-found') + + +def graph_of(product): + """(the Place, the checked Graph) of a run's graph file, kept while the file is unchanged.""" + place = _graph_place(product) + info = os.stat(place.path) + key = (place.path, info.st_size, info.st_mtime_ns, info.st_ino) + with _lock: + if key in _kept: + _kept.move_to_end(key) + return place, _kept[key] + graph = _read(place) + with _lock: + _kept[key] = graph + while len(_kept) > KEPT: + _kept.popitem(last=False) + return place, graph + + +# ---------------------------------------------------------------- folding + +def _label(operation): + """A short name of an operation: aten.conv2d.default -> conv2d; torch.nn.modules.conv.Conv2d -> Conv2d.""" + parts = operation.split('.') + if len(parts) >= 3 and parts[0] in ('aten', 'prims', 'quantized'): + return parts[1] + return parts[-1] or operation + + +def _size(shape): + total = 1 + for size in shape: + if not isinstance(size, int): + return None + total *= size + return total + + +def _node_parameters(graph, tensors): + return sum(_size(graph.tensors[name]['shape']) or 0 for name in tensors + if name in graph.tensors and graph.tensors[name]['kind'] == 'parameter') + + +class _Folding: + def __init__(self, graph, depth, opened, closed): + self.graph, self.depth, self.opened, self.closed = graph, depth, set(opened), set(closed) + self.groups = {} + + def is_open(self, path): + if not path: + return True + if path in self.opened: + return True + return self.graph.modules[path]['depth'] <= self.depth and path not in self.closed + + def group(self, module): + """The shallowest closed module on module's path, or None when every one is open.""" + if module in self.groups: + return self.groups[module] + found, path = None, '' + for part in module.split('.') if module else []: + path = f'{path}.{part}' if path else part + if path in self.graph.modules and not self.is_open(path): + found = path + break + self.groups[module] = found + return found + + def open_in_effect(self): + return [path for path in self.graph.modules if path and self.group(path) is None] + + +def fold(graph, depth=None, opened=(), closed=()): + """The shown nodes and merged edges of graph folded at depth with the modules opened and closed by name.""" + if depth is None: + depth = 1 if graph.operations > LARGE else DEPTH + folding = _Folding(graph, depth, opened, closed) + shown, order, place = {}, [], [] + for position, node in enumerate(graph.nodes): + group = folding.group(node['module']) if node['kind'] == 'operation' else None + if group is None: + key = node['id'] + shown[key] = {'id': key, 'kind': node['kind'], 'label': _label(node['operation']) if node['kind'] == + 'operation' else node['id'], 'module': node['module'], + 'class': graph.modules.get(node['module'], {}).get('class'), + 'operation': node['operation'], 'tensors': node['tensors'], + 'tensor_count': len(node['tensors']), + 'parameters': _node_parameters(graph, node['tensors']), 'inputs': node['inputs'], + 'outputs': node['outputs'], 'attributes': node['attributes'], 'operations': 1, + 'first': position} + order.append(key) + else: + key = GROUP + group + entry = shown.get(key) + if entry is None: + module = graph.modules[group] + entry = shown[key] = {'id': key, 'kind': 'group', 'label': group, 'module': group, + 'class': module['class'], 'operation': None, 'tensors': [], + 'tensor_count': 0, 'parameters': module['parameters'], 'inputs': [], + 'outputs': [], 'attributes': {}, 'operations': 0, 'first': position, + '_tensors': {}} + order.append(key) + entry['operations'] += 1 + for name in node['tensors']: + entry['_tensors'][name] = None + place.append(key) + edges = collections.OrderedDict() + for source, target, _ in graph.edges: + a, b = place[source], place[target] + if a == b: + continue + value = graph.nodes[source]['outputs'][:1] + edge = edges.get((a, b)) + if edge is None: + edge = edges[(a, b)] = {'from': a, 'to': b, 'count': 0, + 'shape': value[0]['shape'] if value else None, + 'dtype': value[0]['dtype'] if value else None} + edge['count'] += 1 + if shown[b]['kind'] == 'group' and value and len(shown[b]['inputs']) < VALUES: + shown[b]['inputs'].append(value[0]) + if shown[a]['kind'] == 'group' and value and len(shown[a]['outputs']) < VALUES and edge['count'] == 1: + shown[a]['outputs'].append(value[0]) + for entry in shown.values(): + held = entry.pop('_tensors', None) + if held is not None: + names = list(held) + entry['tensors'], entry['tensor_count'] = names[:GROUP_TENSORS], len(names) + return {'depth': depth, 'open': folding.open_in_effect(), 'nodes': [shown[key] for key in order], + 'edges': list(edges.values())} + + +def _head(place, graph): + return {'path': place.address, 'format': FORMAT, 'complete': graph.complete, 'reason': graph.reason, + 'method': graph.method, 'torch': graph.torch, 'model': graph.model, 'inputs': graph.inputs, + 'notes': graph.notes, + 'counts': {'nodes': len(graph.nodes), 'edges': len(graph.edges), 'operations': graph.operations, + 'modules': len(graph.modules), 'tensors': len(graph.tensors)}} + + +@inside.reading +def model_graph(product, *, depth=None, opened=(), closed=()): + place, graph = graph_of(product) + return {**_head(place, graph), 'modules': graph.tree, 'tensors': graph.tensors, + **fold(graph, depth, opened, closed)} + + +# ---------------------------------------------------------------- overlays + +def _prefixes(name): + """The module paths a dotted tensor name (or a module path) lies under, the model itself first.""" + out, path = [''], '' + parts = name.split('.') + for part in parts[:-1]: + path = f'{path}.{part}' if path else part + out.append(path) + return out + + +def _module_prefixes(module): + return _prefixes(module + '.x') if module else [''] + + +def _finite(values): + return [value for value in values if value is not None and math.isfinite(value)] + + +def _counts(graph, kind): + modules = {path: 0 for path in graph.modules} + nodes = {} + for node in graph.nodes: + if node['kind'] != 'operation': + continue + if kind == 'outputs': + sizes = [_size(value['shape']) for value in node['outputs']] + value = None if any(size is None for size in sizes) else sum(sizes) + else: + value = 1 + nodes[node['id']] = value + for path in _module_prefixes(node['module']): + if path in modules: + modules[path] = None if modules[path] is None or value is None else modules[path] + value + return modules, nodes + + +def _relative(sums): + difference, other, bad = sums + if bad or not other: + return None + return math.sqrt(difference) / math.sqrt(other) + + +def _changes(graph, compared): + """{module: relative change}, {node: relative change} from the rows of a weights_compare.""" + rows = {row['array']: row for row in compared['tensors']} + modules = {path: [0.0, 0.0, False, 0] for path in graph.modules} + + def add(sums, row): + if row['difference_norm'] is None or row['other_norm'] is None: + sums[2] = True + else: + sums[0] += row['difference_norm'] ** 2 + sums[1] += row['other_norm'] ** 2 + sums[3] += 1 + for name, row in rows.items(): + for path in _prefixes(name): + if path in modules: + add(modules[path], row) + nodes = {} + for node in graph.nodes: + if node['kind'] != 'operation': + continue + sums = [0.0, 0.0, False, 0] + for name in node['tensors']: + if name in rows: + add(sums, rows[name]) + nodes[node['id']] = _relative(sums[:3]) if sums[3] else None + return {path: (_relative(sums[:3]) if sums[3] else None) for path, sums in modules.items()}, nodes + + +def _readable_weights(product, path=None): + """The address of a readable weights file of a product: path when given, else the first readable one.""" + if path is not None: + return path + for address, output in inside_weights.weight_files(product): + if inside_weights._weights_file(product, address, output)['readable']: + return address + raise ProjectError(f'Run {product.run_id} has no weights file Tuldok reads.', 'not-found') + + +@inside.reading +def model_graph_overlay(product, *, kind, against=None, other=None, path=None, other_path=None): + _, graph = graph_of(product) + extra = {} + if kind == 'parameters': + modules = {name: module['parameters'] for name, module in graph.modules.items()} + nodes = {node['id']: _node_parameters(graph, node['tensors']) for node in graph.nodes + if node['kind'] == 'operation'} + unit = 'parameters' + elif kind in ('outputs', 'operations'): + modules, nodes = _counts(graph, kind) + unit = 'values' if kind == 'outputs' else 'operations' + elif kind == 'change': + here = _readable_weights(product, path) + if against == 'start': + other, other_path = product, other_path or inside_weights._starts_from(product, here) + if other_path is None: + raise ProjectError(f'{here} has no initial- file beside it to compare with.', 'not-found') + elif against == 'run': + if other is None: + raise ProjectError('Name the other run to compare with (other_run).', 'invalid') + other_path = _readable_weights(other, other_path) + else: + raise ProjectError('against must be start or run for the change overlay.', 'invalid') + compared = inside_weights.weights_compare(product, path=here, other=other, other_path=other_path) + modules, nodes = _changes(graph, compared) + unit = 'relative change' + extra = {'against': {'kind': against, 'run': product.run_id, 'path': here, 'other_run': other.run_id, + 'other_path': other_path}} + else: + raise ProjectError(f'kind must be one of {", ".join(OVERLAYS)}.', 'invalid') + finite = _finite(list(modules.values()) + list(nodes.values())) + return {'kind': kind, 'unit': unit, 'modules': modules, 'nodes': nodes, + 'low': min(finite) if finite else None, 'high': max(finite) if finite else None, **extra} + + +# ---------------------------------------------------------------- comparing + +def _own_tensors(graph): + """{module path: {tensor name: shape}} of the tensors directly in each module.""" + owned = collections.defaultdict(dict) + for name, tensor in graph.tensors.items(): + module = name.rpartition('.')[0] + owned[module][name] = tensor['shape'] + return owned + + +@inside.reading +def model_graph_compare(product, *, other): + _, here = graph_of(product) + _, there = graph_of(other) + mine, theirs = _own_tensors(here), _own_tensors(there) + rows = [] + for path in list(here.modules) + [path for path in there.modules if path not in here.modules]: + a, b = here.modules.get(path), there.modules.get(path) + row = {'path': path, 'class': a['class'] if a else None, 'other_class': b['class'] if b else None, + 'parameters': a['parameters'] if a else None, 'other_parameters': b['parameters'] if b else None, + 'reshaped': [], 'only_here': [], 'only_there': []} + if a is None: + row['status'] = 'missing' + elif b is None: + row['status'] = 'added' + else: + ours, others = mine.get(path, {}), theirs.get(path, {}) + row['reshaped'] = [{'name': name, 'shape': shape, 'other_shape': others[name]} + for name, shape in ours.items() if name in others and others[name] != shape] + row['only_here'] = [name for name in ours if name not in others] + row['only_there'] = [name for name in others if name not in ours] + row['status'] = 'changed' if (a['class'] != b['class'] or row['reshaped'] or row['only_here'] + or row['only_there']) else 'same' + rows.append(row) + counts = collections.Counter(row['status'] for row in rows) + return {'modules': rows, 'counts': {status: counts.get(status, 0) + for status in ('same', 'changed', 'added', 'missing')}} diff --git a/tuldok_project/operations.py b/tuldok_project/operations.py index 28c59b7c..971bc19a 100644 --- a/tuldok_project/operations.py +++ b/tuldok_project/operations.py @@ -5,7 +5,9 @@ section 2 of spec-w3.md (draft_branch, revert_definition), the five of section 3 of spec-d1.md (records, record, inside, array_slice, array_summary), the three of section 3 of spec-d2.md (weights, weights_compare, -array_tiles), the two of section 2 of spec-d6.md (fields, field_compare), +array_tiles), the two of section 2 of spec-d6.md (fields, field_compare), the three of +section 3 of docs/plans/training-and-curation/spec-t2.md (model_graph, +model_graph_overlay, model_graph_compare), the five of section 5 of spec-d4.md (annotation_tasks, annotated_records, annotation, set_annotation, revert_annotations) and the five of sections 2 and 4 of spec-d5.md (endpoint, set_endpoint, @@ -32,6 +34,8 @@ REVERT_RECORDS = 10_000 # records named by one revert_annotations ENDPOINT_CHARACTERS = 2048 # an address of a Pumas endpoint (local.ENDPOINT_LIMIT) INSTRUCTION_CHARACTERS = 4000 +GRAPH_MODULES = 2000 # modules named open or closed by one model_graph (spec-t2.md section 3) +GRAPH_OVERLAYS = ('parameters', 'outputs', 'operations', 'change') @dataclass(frozen=True) @@ -105,6 +109,9 @@ def _arguments(required=(), **properties): CANCEL_RUN = ('id', 'reference', 'subject', 'state', 'cancel_file', 'already_asked') STOP_RUN = ('id', 'reference', 'subject', 'was', 'state', 'killed', 'remaining', 'marked_unknown') ENDPOINT = ('address', 'answered', 'version', 'models', 'problem') +MODEL_GRAPH = ('path', 'format', 'complete', 'reason', 'method', 'torch', 'model', 'inputs', 'notes', 'counts', + 'modules', 'tensors', 'depth', 'open', 'nodes', 'edges') +_MODULE_PATHS = {'type': 'array', 'items': {'type': 'string', 'maxLength': 1024}, 'maxItems': GRAPH_MODULES} OPERATIONS = ( @@ -222,6 +229,20 @@ def _arguments(required=(), **properties): axis={'type': 'integer', 'minimum': 0, 'maximum': 3}, index={'type': 'array', 'items': {'type': 'integer', 'minimum': 0}, 'maxItems': 4}, mean_free=_FLAG), FIELD_COMPARE), + Operation('model_graph', "Read the structure a finished run's script recorded (model-graph.json): its " + 'operations and the edges between them, folded to a depth of the module tree with modules opened or ' + 'closed by path, and the module tree.', 'inspect', False, + _arguments(['run'], run=_RUN, depth={'type': 'integer', 'minimum': 0, 'maximum': 64}, + open=_MODULE_PATHS, close=_MODULE_PATHS), MODEL_GRAPH), + Operation('model_graph_overlay', "Read a number per module and per operation of a finished run's model graph: " + 'parameters, output values, operations, or the relative change of the weights under it against the ' + 'weights it started from or another run\'s.', 'inspect', False, + _arguments(['run', 'kind'], run=_RUN, kind={'type': 'string', 'enum': list(GRAPH_OVERLAYS)}, + against={'type': 'string', 'enum': ['start', 'run']}, other_run=_RUN, path=_ADDRESS, + other_path=_ADDRESS), ('kind', 'unit', 'modules', 'nodes', 'low', 'high')), + Operation('model_graph_compare', "Match the modules of two finished runs' model graphs by path: the same, " + 'changed (class or tensor shapes), added or missing.', 'inspect', False, + _arguments(['run', 'other_run'], run=_RUN, other_run=_RUN), ('modules', 'counts')), Operation('annotation_tasks', 'List the annotation tasks, each with its dataset, current product and counts of ' 'its records by the state of their annotations.', 'inspect', False, _arguments(), ('tasks',)), Operation('annotated_records', "Read one page of the records of a task's dataset with their annotations, " diff --git a/tuldok_project/service.py b/tuldok_project/service.py index 3cfb1ba1..5d55c6c3 100644 --- a/tuldok_project/service.py +++ b/tuldok_project/service.py @@ -8,10 +8,12 @@ of the service. Every mutating call that passed the actor check writes one activity row, done or refused. The six operations on build requests are passed to build_requests. The five reads inside a product (spec-d1.md), the -three reads of a model's weights (spec-d2.md) and the two of the fields a run -kept (spec-d6.md) find the finished run (and for weights_compare the other -run) with the project open for a moment and read its output directory -through inside.py, inside_weights.py and inside_fields.py after closing it; +three reads of a model's weights (spec-d2.md), the two of the fields a run +kept (spec-d6.md) and the three of a model's graph (spec-t2.md) find the +finished run (and for weights_compare and the graph's overlay and comparison +the other run) with the project open for a moment and read its output +directory through inside.py, inside_weights.py, inside_fields.py and +inside_graph.py after closing it; product_file does the same for the file route; those reads run outside the lock, so a long one holds up no other call. The five operations on annotations (spec-d4.md section 5) work the same way: what the database @@ -52,13 +54,13 @@ import psycopg from . import (activity, annotation_records, annotation_rows, annotations, build_requests, builds, charts, check, - documents, environments, inside, inside_fields, inside_weights, launcher, local, operations, plan, + documents, environments, inside, inside_fields, inside_graph, inside_weights, launcher, local, operations, plan, pumas, store, workspace) from .documents import Problem CHECK_PROBLEMS = 200 -# The reads inside a product (spec-d1.md, spec-d2.md, spec-d6.md), each a function of +# The reads inside a product (spec-d1.md, spec-d2.md, spec-d6.md, and spec-t2.md's model graph), each a function of # ({argument: inside.Product}, arguments): # the products of the arguments in PRODUCT_ARGUMENTS that the call gives. call() finds them under the service's lock # and reads outside it: decompressing a large member, parsing a large mesh or comparing two large weights files takes @@ -88,6 +90,12 @@ 'field_compare': lambda found, a: inside_fields.field_compare(found['run'], entry=a['entry'], case=a['case'], axis=a.get('axis'), index=a.get('index'), mean_free=a.get('mean_free', False)), + 'model_graph': lambda found, a: inside_graph.model_graph(found['run'], depth=a.get('depth'), + opened=a.get('open', ()), closed=a.get('close', ())), + 'model_graph_overlay': lambda found, a: inside_graph.model_graph_overlay( + found['run'], kind=a['kind'], against=a.get('against'), other=found.get('other_run'), path=a.get('path'), + other_path=a.get('other_path')), + 'model_graph_compare': lambda found, a: inside_graph.model_graph_compare(found['run'], other=found['other_run']), } # The reads of annotations (spec-d4.md section 5): each takes the service's lock itself, only for its database work. ANNOTATION_READS = ('annotation_tasks', 'annotated_records', 'annotation') From 24d33282173d00c80871e95d556f8070979989b4 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 19 Nov 2026 05:44:22 -0700 Subject: [PATCH 092/131] feat(project): a run's training drawn live in its drawer on the Train tab training.js: curves of the chosen series, one chart a series, up to four runs overlaid, smoothing, log scale, step or time; histograms over the steps as heat strips; the last samples as a strip. Updated in place on every reading while a run in view is active; never rebuilt by a reading. The settings are kept in the address. Browser check with a stand-in script logging through tuldok_log. Co-Authored-By: Claude Opus 5.5 --- app.py | 1 + static/project-workspace.html | 1 + static/project-workspace/app.js | 3 +- static/project-workspace/base.css | 42 ++ static/project-workspace/tabs.js | 15 +- static/project-workspace/training.js | 476 +++++++++++++++++++ tests/browser_project_workspace_training.cjs | 303 ++++++++++++ tests/project_training_stand_in.py | 104 ++++ 8 files changed, 940 insertions(+), 5 deletions(-) create mode 100644 static/project-workspace/training.js create mode 100644 tests/browser_project_workspace_training.cjs create mode 100644 tests/project_training_stand_in.py diff --git a/app.py b/app.py index 9e1f64e2..cba0f31a 100644 --- a/app.py +++ b/app.py @@ -808,6 +808,7 @@ def _get(self): '/project-workspace/inside.js': ('project-workspace/inside.js', 'text/javascript'), '/project-workspace/weights.js': ('project-workspace/weights.js', 'text/javascript'), '/project-workspace/fields.js': ('project-workspace/fields.js', 'text/javascript'), + '/project-workspace/training.js': ('project-workspace/training.js', 'text/javascript'), '/project-workspace/annotate.js': ('project-workspace/annotate.js', 'text/javascript'), '/project-workspace/generate.js': ('project-workspace/generate.js', 'text/javascript'), '/project-workspace/app.js': ('project-workspace/app.js', 'text/javascript'), diff --git a/static/project-workspace.html b/static/project-workspace.html index ccf47a7a..a689712a 100644 --- a/static/project-workspace.html +++ b/static/project-workspace.html @@ -19,6 +19,7 @@ + diff --git a/static/project-workspace/app.js b/static/project-workspace/app.js index 7eae0a98..db80dbe9 100644 --- a/static/project-workspace/app.js +++ b/static/project-workspace/app.js @@ -63,7 +63,8 @@ reopen: () => { $('aside')._for = null; render(); } }; // The settings of the Analysis tab the address keeps, so that a reload opens it where it was (spec-d6 section 3). - const ADDRESSED = ['anaBench', 'anaSubject', 'anaMetric', 'anaCase', 'anaAxis', 'anaIndex', 'anaMeanFree']; + // And those of the Training block of a run's drawer (spec-t1 section 6): the runs compared, the series, smoothing, log scale, across. + const ADDRESSED = ['anaBench', 'anaSubject', 'anaMetric', 'anaCase', 'anaAxis', 'anaIndex', 'anaMeanFree', 'trWith', 'trSeries', 'trSmooth', 'trLog', 'trX']; /** Writes the benchmark, the compare set and the Analysis tab's settings into the address without reloading, so the view can be shared. */ function address() { const q = new URLSearchParams(location.search); diff --git a/static/project-workspace/base.css b/static/project-workspace/base.css index fec0260d..f559d215 100644 --- a/static/project-workspace/base.css +++ b/static/project-workspace/base.css @@ -36,6 +36,8 @@ /* The colour ramps of the viewers of a product (inside.js): sequential low to high, diverging about zero. */ --ramp-lo: #e4ebf5; --ramp-hi: #1c5cab; --ramp-neg: #2e6fcf; --ramp-mid: #efeeeb; --ramp-pos: #d2652f; + /* The runs drawn together on a training chart, in the order they are added (validated: CVD and contrast, light and dark). */ + --run-1: #2e6fcf; --run-2: #d2652f; --run-3: #8a4fbf; --run-4: #178f74; --font: "Ubuntu Sans", "Noto Sans", system-ui, sans-serif; --mono: "Ubuntu Sans Mono", "Ubuntu Mono", ui-monospace, monospace; --radius: 4px; @@ -52,6 +54,7 @@ --k-training-policy: #22a07f; --k-architecture: #4f8ae0; --k-refinement: #d96f3c; --k-component: #7c8694; --mark: #4f8ae0; --grid: #222a33; --ramp-lo: #2a3542; --ramp-hi: #8db4f5; --ramp-neg: #4f8ae0; --ramp-mid: #3a3a37; --ramp-pos: #e07a4a; + --run-1: #4f8ae0; --run-2: #d96f3c; --run-3: #9a72d8; --run-4: #22a07f; } } :root[data-theme="dark"] { @@ -65,6 +68,7 @@ --k-training-policy: #22a07f; --k-architecture: #4f8ae0; --k-refinement: #d96f3c; --k-component: #7c8694; --mark: #4f8ae0; --grid: #222a33; --ramp-lo: #2a3542; --ramp-hi: #8db4f5; --ramp-neg: #4f8ae0; --ramp-mid: #3a3a37; --ramp-pos: #e07a4a; + --run-1: #4f8ae0; --run-2: #d96f3c; --run-3: #9a72d8; --run-4: #22a07f; } * { box-sizing: border-box; } @@ -855,3 +859,41 @@ tr.wts-row:has(+ tr.wts-open) > td { background: var(--accent-wash); } .ann-batch { border-top: 1px solid var(--line); padding-top: 8px; } .ann-batch .ann-batch-line { flex: 1 1 180px; min-width: 0; overflow-wrap: anywhere; font-variant-numeric: tabular-nums; } .ann-sugrefusal { font-size: 12.5px; } + +/* What a run's training script logged (training.js, spec-t1.md section 6), in the run's drawer. */ +.trn { display: grid; gap: 8px; min-width: 0; } +.trn[aria-busy="true"] { cursor: progress; } +.trn h4 { margin: 4px 0 0; font-size: 13px; } +.trn-at { margin: 0; color: var(--ink-2); font-variant-numeric: tabular-nums; } +.trn-series, .trn-controls { display: flex; flex-wrap: wrap; align-items: center; gap: 6px 10px; min-width: 0; } +.trn-series .btn { max-width: 100%; overflow: hidden; text-overflow: ellipsis; } +.trn-smooth { display: inline-flex; align-items: center; gap: 6px; } +.trn-smooth input { width: 110px; } +.trn-smooth .num { min-width: 2.6em; font-variant-numeric: tabular-nums; } +.trn-runs { display: grid; gap: 6px; min-width: 0; } +.trn-runs select { max-width: 100%; min-width: 0; } +.trn-legend { list-style: none; margin: 0; padding: 0; display: grid; gap: 2px; } +.trn-legend li { display: flex; align-items: center; gap: 8px; min-width: 0; font-size: 13px; } +.trn-legend li > span:nth-child(2) { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; min-width: 0; } +.trn-legend .trn-remove { min-height: 22px; padding: 0 6px; margin-left: auto; } +.trn-swatch { flex: none; width: 14px; height: 3px; border-radius: 2px; display: inline-block; } +.trn-fig { margin: 0; display: grid; gap: 2px; min-width: 0; } +.trn-cap { color: var(--ink-2); overflow-wrap: anywhere; } +.trn-cap b { color: var(--ink); font-weight: 600; } +.trn-plot { position: relative; min-width: 0; } +canvas.trn-chart { display: block; width: 100%; cursor: crosshair; } +.trn-note { margin: 0; } +.trn-note:empty { display: none; } +.trn-tip { position: absolute; z-index: 3; pointer-events: none; display: grid; gap: 2px; padding: 6px 8px; max-width: 100%; font-size: 12px; background: var(--surface); color: var(--ink); border: 1px solid var(--line-strong); border-radius: var(--radius); box-shadow: 0 2px 8px rgba(0, 0, 0, .14); font-variant-numeric: tabular-nums; } +.trn-tip[hidden] { display: none; } +.trn-tip-head { color: var(--ink-2); } +.trn-tip-row { display: flex; align-items: center; gap: 6px; } +.trn-hists, .trn-samples-box { display: grid; gap: 6px; min-width: 0; border-top: 1px solid var(--line); padding-top: 8px; } +.trn-strip-row { display: grid; gap: 2px; min-width: 0; } +.trn-strip-label { display: flex; flex-wrap: wrap; gap: 0 4px; min-width: 0; overflow-wrap: anywhere; } +canvas.trn-strip { display: block; width: 100%; background: var(--surface-2); border-radius: 2px; } +.trn-samples { display: flex; gap: 8px; overflow-x: auto; padding-bottom: 4px; min-width: 0; } +.trn-sample { margin: 0; flex: none; display: grid; gap: 2px; justify-items: center; } +.trn-thumb { display: block; width: 72px; height: 72px; object-fit: contain; background: var(--surface-2); border-radius: 3px; image-rendering: pixelated; } +div.trn-thumb { display: grid; place-items: center; text-align: center; padding: 4px; } +.trn-problems { color: var(--warn); margin: 0; } diff --git a/static/project-workspace/tabs.js b/static/project-workspace/tabs.js index e3f1a07d..68dfdb44 100644 --- a/static/project-workspace/tabs.js +++ b/static/project-workspace/tabs.js @@ -454,7 +454,7 @@ }); if (!sel) return closeDrawer(aside); if (sel === 'endpoint' && window.LabGenerate) window.LabGenerate.drawer(aside, act); - else if (sel.startsWith('run:')) runDrawer(aside, sel, act, data); + else if (sel.startsWith('run:')) runDrawer(aside, sel, act, data, state); else if (sel.startsWith('request:')) requestDrawer(aside, sel, act, data); else if (sel.startsWith('plan:')) A.planView(aside, sel, act.go, () => { const one = sel.slice(5); act.select(data.map.byId.has(one) ? one : null); }); else if (sel.startsWith('env:')) envDrawer(aside, sel, act, data); @@ -509,6 +509,7 @@ * again and its drawer is drawn again in place. */ S.tick = async () => { + if (window.LabTraining) await window.LabTraining.tick(); // the open run's Training block, in place (training.js) const aside = document.getElementById('aside'); if (!live || aside._for !== live.key) { live = null; return; } const mine = live; @@ -519,9 +520,12 @@ if (pr.ended) { live = null; mine.ended(); } // not awaited: the reading it starts waits for the one calling this } catch (error) { /* the next tick asks again; the strip says what fails */ } }; - function runDrawer(aside, key, act, data) { - const id = key.slice(4); - drawer(aside, key, () => Promise.all([P.read('run', { run: id }), P.call('progress', { run: id })]), (ins, [r, pr]) => { + /** A run's name in the Training block: its model's short name (or its definition) and the start of its id. */ + const runLabel = (runs, data) => id => { const r = runs.find(x => x.id === id), m = r && graphFor(data.map).byId.get(r.reference); return (m ? Tree.refName(m) : r ? nameOfRef(r.reference) : 'run') + (r && r.subject ? ' · ' + r.subject : '') + ' · ' + id.slice(0, 8); }; + function runDrawer(aside, key, act, data, state) { + const id = key.slice(4), T = window.LabTraining; + drawer(aside, key, () => Promise.all([P.read('run', { run: id }), P.call('progress', { run: id }), + T ? T.read(id, state.ui).catch(error => ({ error })) : null, T ? P.read('runs').then(a => a.runs, () => []) : []]), (ins, [r, pr, tr, runs]) => { const m = graphFor(data.map).byId.get(r.reference); const hd = h('header'); hd.appendChild(h('span', 'kicker', 'run ' + r.id)); const t2 = h('h2', null, (m ? Tree.nameOf(m) : r.reference) + (r.subject ? ' · ' + r.subject : '')); t2.tabIndex = -1; hd.appendChild(t2); const meta = h('div', 'ins-meta'); if (m) meta.appendChild(h('span', 'chip ' + m.kind, P.kindLabel(m.kind))); meta.appendChild(runState(r.state)); if (r.scratch) meta.appendChild(h('span', 'small faint', 'from the code as it is')); hd.appendChild(meta); ins.appendChild(hd); @@ -557,6 +561,9 @@ const progBlock = block('Latest progress', prog); if (!pr.event && !active) progBlock.hidden = true; // A run read live shows its progress and logs first; an ended one its record first. ins.appendChild(progBlock); + // What its training script logged, drawn live while it runs (training.js, spec-t1.md section 6). + if (tr && tr.error) ins.appendChild(block('Training', h('p', 'note', 'Its training could not be read: ' + tr.error.message))); + else if (tr) ins.appendChild(T.block(tr, act, runLabel(runs, data), runs)); if (!active) ins.appendChild(su.dl); const logs = {}; for (const [name, title] of [['stdout', 'Standard output'], ['stderr', 'Standard error']]) { diff --git a/static/project-workspace/training.js b/static/project-workspace/training.js new file mode 100644 index 00000000..24296f88 --- /dev/null +++ b/static/project-workspace/training.js @@ -0,0 +1,476 @@ +'use strict'; +// What a run's training script logged (docs/plans/training-and-curation/spec-t1.md section 6): the block "Training" +// of a run's drawer on the Train tab. Curves of the chosen series, one small chart a series (never two scales on +// one axis), each run in its own colour (the run opened and up to three overlaid from "Compare with"), smoothing, +// a log scale, step or time across, the band of each bucket's least and greatest value when a long series is +// reduced, and the checkpoints as ticks; under them, each tensor's histograms over the steps as a heat strip +// (weights or gradients), read when the strip comes on screen; and the last samples of a name as a strip. +// +// Updating in place (spec-w4): tabs.js reads the block's data with the drawer (read()) and builds it with the +// drawer off the page (block()); the answers are kept here by run for as long as the page lives, so a drawer drawn +// again (the run ended) builds the block from what is held. While a run in view is active, every reading of the +// page (tick(), every two seconds while something builds) asks `training` once a run; when lines were added it asks +// for the new buckets only (training_series from where the page is), draws the canvases again, reads again the +// strips on screen when histograms were added, and appends the new samples. The block is never built again by a +// reading, and a reading that found nothing new touches no element. The person's own choices (a series, a run to +// compare, weights or gradients, all the tensors, a sample name) build the block's content again in the same +// element; smoothing, log scale and step or time only draw the canvases again. The settings that are not of one +// run are kept in the address (trWith, trSeries, trSmooth, trLog, trX). +window.LabTraining = (() => { + const P = window.TuldokProject, C = window.LabCharts, h = C.h, D = window.LabInside.drawing; + const fmt = v => v == null || !Number.isFinite(v) ? '—' : C.fmtSci(v); + const button = (cls, text, onClick) => { const b = h('button', cls, text); b.type = 'button'; if (onClick) b.addEventListener('click', onClick); return b; }; + const COLOURS = ['--run-1', '--run-2', '--run-3', '--run-4']; // the runs in view, in the order they were added + const RUNS_MOST = 4, SERIES_MOST = 4, POINTS = 800, HIST_ROWS = 120, HIST_BINS = 32, STRIPS_FIRST = 8, SAMPLES_SHOWN = 12; + const CHART_HEIGHT = 150, STRIP_HEIGHT = 36, SAMPLE_SIZE = 72; + const ACTIVE = ['queued', 'running']; + /** Sets an element's text in place: its one text node's data when it has one, so no node is added or removed. */ + const setText = (el, text) => { if (el.childNodes.length === 1 && el.firstChild.nodeType === 3) { if (el.firstChild.data !== text) el.firstChild.data = text; } else if (el.textContent !== text) el.textContent = text; }; + const seconds = s => s == null ? '—' : s < 90 ? s.toFixed(s < 10 ? 1 : 0) + ' s' : s < 5400 ? (s / 60).toFixed(1) + ' min' : (s / 3600).toFixed(2) + ' h'; + + // ---- What is held, by run, for the page's life --------------------------------------------------------------- + const held = new Map(); // run id -> { over, series: Map(name -> {size, points, lines, buckets}), samples: Map(name -> {total, items}), arrays: Map(index -> answer), hist: Map(key -> {answer, at}) } + const runOf = id => { let r = held.get(id); if (!r) { r = { over: null, series: new Map(), samples: new Map(), arrays: new Map(), hist: new Map() }; held.set(id, r); } return r; }; + let view = null; // the block on screen: { el, id, ids, settings, act, labelOf, sampleName, kind, all, charts: Map(name -> canvas), redraw() } + + /** The settings the address keeps, from the tab's state. */ + function settingsOf(ui, id) { + const others = String(ui.trWith || '').split(',').filter(x => x && x !== id).slice(0, RUNS_MOST - 1); + const smooth = Math.min(0.99, Math.max(0, Number(ui.trSmooth) || 0)); + return { with: others, series: String(ui.trSeries || '').split(',').filter(Boolean).slice(0, SERIES_MOST), smooth, log: ui.trLog === '1', x: ui.trX === 'time' ? 'time' : 'step' }; + } + /** The series shown: the chosen ones the runs logged, else loss (or the first). */ + function shownSeries(ids, chosen) { + const names = []; + for (const id of ids) { const o = runOf(id).over; if (o) for (const s of o.series) if (!names.includes(s.name)) names.push(s.name); } + const picked = chosen.filter(n => names.includes(n)); + if (picked.length) return { names, picked }; + const first = names.includes('loss') ? 'loss' : names[0]; + return { names, picked: first ? [first] : [] }; + } + + // ---- Reading --------------------------------------------------------------------------------------------------- + async function overview(id) { const r = runOf(id); r.over = await P.call('training', { run: id }); return r.over; } + /** The buckets of the named series of a run that are new since what is held (all of them when the size changed). */ + async function seriesOf(id, names) { + const r = runOf(id), o = r.over; if (!o) return false; + const want = names.filter(n => o.series.some(s => s.name === n) && (!r.series.has(n) || r.series.get(n).lines !== o.lines)); + if (!want.length) return false; + const answer = await P.call('training_series', { run: id, most: POINTS, series: want.map(n => { const s = r.series.get(n); return s ? { name: n, size: s.size, since: Math.max(0, s.buckets.length - 1) } : { name: n }; }) }); + for (const a of answer.series) { + const s = r.series.get(a.name); + if (s && s.size === a.size && a.first <= s.buckets.length) s.buckets.splice(a.first, Infinity, ...a.buckets); + else r.series.set(a.name, { size: a.size, buckets: a.buckets }); + Object.assign(r.series.get(a.name), { size: a.size, points: a.points, lines: answer.lines }); + } + return true; + } + /** The last samples of one name; only those added since what is held. */ + async function samplesOf(id, name) { + const r = runOf(id), o = r.over; if (!o || !name) return false; + const listed = o.samples.find(s => s.name === name); if (!listed) return false; + const s = r.samples.get(name); + if (s && s.total === listed.count) return false; + const from = s ? s.total : Math.max(0, listed.count - SAMPLES_SHOWN); + const answer = await P.call('training_samples', { run: id, name, offset: Math.max(from, listed.count - SAMPLES_SHOWN), limit: SAMPLES_SHOWN }); + const items = (s ? s.items : []).concat(answer.samples).slice(-SAMPLES_SHOWN); + r.samples.set(name, { total: answer.total, items }); + return answer.samples; + } + const sampleName = (o, chosen) => o && o.samples.length ? (o.samples.some(s => s.name === chosen) ? chosen : o.samples[0].name) : null; + + /** + * What the block of run id needs, for the drawer's load: the run's and the overlaid runs' overviews (asked + * afresh), the new buckets of the series shown and the last samples. Resolves once complete. + */ + async function read(id, ui) { + const settings = settingsOf(ui || {}, id), ids = [id].concat(settings.with); + await Promise.all(ids.map(x => overview(x).catch(error => { if (x === id) throw error; runOf(x).over = null; }))); + const { picked } = shownSeries(ids, settings.series); + await Promise.all(ids.map(x => seriesOf(x, picked))); + const r = runOf(id); r.sampleName = sampleName(r.over, r.sampleName); + await samplesOf(id, r.sampleName); + return { id, settings }; + } + + // ---- The block ------------------------------------------------------------------------------------------------- + /** The block for what read() gave, built off the page; act: the tab's actions (keepUI); labelOf(run id) names a run. */ + function block(value, act, labelOf, runs) { + const el = h('div', 'trn'); el.dataset.run = value.id; + view = { el, id: value.id, settings: value.settings, act, labelOf, runs: runs || [], charts: new Map(), kind: (view && view.id === value.id && view.kind) || 'weights', all: view && view.id === value.id ? view.all : false }; + fill(view); + return el; + } + const idsOf = v => [v.id].concat(v.settings.with.filter(x => runOf(x).over)); + /** Builds the content of the block (in its element, on or off the page). */ + function fill(v) { + const el = v.el, o = runOf(v.id).over; + el.textContent = ''; + el.appendChild(h('h3', null, 'Training')); + if (!o || !o.present || (!o.lines && !o.histogram_lines && !o.sample_lines)) { + const p = h('p', 'note trn-none', o && o.run.active ? 'Nothing logged yet. A script logs its training into training/ of its output (tuldok_log, or by hand); it is drawn here as it arrives.' : 'This run logged no training. A script logs into training/ of its output, with tuldok_log or by hand.'); + el.appendChild(p); v.charts = new Map(); return; + } + const ids = idsOf(v); + // The line under the title: where the run is. + const at = h('p', 'small trn-at'); at.dataset.key = 'trn-at'; el.appendChild(at); v.at = at; setAt(v); + // Series and controls. + const { names, picked } = shownSeries(ids, v.settings.series); + v.picked = picked; + const chooser = h('div', 'trn-series'); chooser.setAttribute('role', 'group'); chooser.setAttribute('aria-label', 'Series shown'); + v.chooser = chooser; chooserButtons(v, names); + el.appendChild(chooser); + el.appendChild(controls(v)); + // The runs in view: a legend, and Compare with. + el.appendChild(legend(v, ids)); + // One chart a series. + v.charts = new Map(); + for (const n of picked) { + const fig = h('figure', 'trn-fig'); const cap = h('figcaption', 'small trn-cap'); cap.appendChild(h('b', null, n)); const sum = h('span', 'faint'); cap.appendChild(sum); fig.appendChild(cap); + const wrap = h('div', 'trn-plot'); const c = h('canvas', 'trn-chart'); c.dataset.series = n; c.setAttribute('role', 'img'); wrap.appendChild(c); + const tip = h('div', 'trn-tip'); tip.hidden = true; wrap.appendChild(tip); fig.appendChild(wrap); + const note = h('p', 'small faint trn-note'); fig.appendChild(note); + el.appendChild(fig); + const chart = { canvas: c, tip, sum, note, name: n }; + v.charts.set(n, chart); + D.paints(c, () => drawChart(v, chart)); + hover(v, chart); + } + if (!picked.length) el.appendChild(h('p', 'note', 'This run logged no scalar series.')); + // Histograms and samples. + v.histBox = h('div', 'trn-hists-slot'); v.sampleBox = h('div', 'trn-samples-slot'); + el.appendChild(v.histBox); el.appendChild(v.sampleBox); + histograms(v); + samples(v); + const problems = o.problems || []; + if (o.bad_lines || o.truncated) { + const p = h('p', 'small warnline trn-problems', (o.bad_lines ? o.bad_lines + ' line' + (o.bad_lines === 1 ? '' : 's') + ' could not be read' + (problems.length ? ' (first: ' + problems[0].file + ' line ' + problems[0].line + ', ' + problems[0].problem.replace(/\.$/, '') + ')' : '') + '. ' : '') + (o.truncated ? 'Only the first part of a long file is read.' : '')); + el.appendChild(p); + } + if (o.other_keys && o.other_keys.length) el.appendChild(h('p', 'small faint', 'Also logged, not drawn: ' + o.other_keys.slice(0, 8).join(', ') + (o.other_keys.length > 8 ? '…' : ''))); + } + /** The buttons of the series chooser, one a name; a name already there keeps its button. */ + function chooserButtons(v, names) { + const have = new Set([...v.chooser.children].map(b => b.dataset.series)); + for (const n of names) { + if (have.has(n)) continue; + const b = button('btn sm', n, () => toggleSeries(v, n)); b.setAttribute('aria-pressed', String(v.picked.includes(n))); b.dataset.key = 'trn-series-' + n; b.dataset.series = n; + if (!v.picked.includes(n) && v.picked.length >= SERIES_MOST) b.disabled = true; + v.chooser.appendChild(b); + } + } + function setAt(v) { + const o = runOf(v.id).over; if (!v.at || !o) return; + const text = (o.last_step == null ? 'No metrics yet' : 'Step ' + o.last_step.toLocaleString('en-GB') + ' · ' + seconds(o.last_time)) + ' · ' + o.lines.toLocaleString('en-GB') + ' lines' + (o.started_at ? ' · started ' + P.day(o.started_at) : '') + (o.run.active ? ' · read live' : ''); + setText(v.at, text); + } + function controls(v) { + const row = h('div', 'trn-controls'); + const sm = h('label', 'trn-smooth'); sm.appendChild(h('span', 'small', 'Smoothing')); + const range = h('input'); range.type = 'range'; range.min = '0'; range.max = '0.99'; range.step = '0.01'; range.value = String(v.settings.smooth); range.dataset.key = 'trn-smooth'; + const shown = h('span', 'small num', v.settings.smooth.toFixed(2)); sm.appendChild(range); sm.appendChild(shown); + range.addEventListener('input', () => { v.settings.smooth = Number(range.value); shown.textContent = v.settings.smooth.toFixed(2); v.act.keepUI('trSmooth', v.settings.smooth ? String(v.settings.smooth) : null); drawAll(v); }); + row.appendChild(sm); + const log = button('btn sm', 'Log scale', () => { v.settings.log = !v.settings.log; log.setAttribute('aria-pressed', String(v.settings.log)); v.act.keepUI('trLog', v.settings.log ? '1' : null); drawAll(v); }); + log.setAttribute('aria-pressed', String(v.settings.log)); log.dataset.key = 'trn-log'; row.appendChild(log); + const x = h('select'); x.dataset.key = 'trn-x'; x.setAttribute('aria-label', 'Across'); for (const [val, text] of [['step', 'By step'], ['time', 'By time']]) { const op = h('option', null, text); op.value = val; x.appendChild(op); } x.value = v.settings.x; + x.addEventListener('change', () => { v.settings.x = x.value; v.act.keepUI('trX', x.value === 'time' ? 'time' : null); drawAll(v); }); + row.appendChild(x); + return row; + } + function legend(v, ids) { + const box = h('div', 'trn-runs'); + const ul = h('ul', 'trn-legend'); + ids.forEach((id, i) => { + const o = runOf(id).over, li = h('li'); li.dataset.run = id; + const sw = h('span', 'trn-swatch'); sw.style.background = 'var(' + COLOURS[i] + ')'; li.appendChild(sw); + li.appendChild(h('span', null, v.labelOf(id))); + li.appendChild(h('span', 'small faint', o ? o.run.state : '')); + if (i > 0) { const x = button('btn sm ghost trn-remove', '×', () => setWith(v, v.settings.with.filter(w => w !== id))); x.setAttribute('aria-label', 'Stop comparing with ' + v.labelOf(id)); x.dataset.key = 'trn-remove-' + id; li.appendChild(x); } + ul.appendChild(li); + }); + box.appendChild(ul); + if (ids.length < RUNS_MOST) { + const s = h('select'); s.dataset.key = 'trn-with'; s.setAttribute('aria-label', 'Compare with another run'); + const first = h('option', null, 'Compare with…'); first.value = ''; s.appendChild(first); + const me = v.runs.find(r => r.id === v.id); + const others = v.runs.filter(r => !ids.includes(r.id) && r.state !== 'queued'); + others.sort((a, b) => (me && b.reference === me.reference) - (me && a.reference === me.reference)); + for (const r of others.slice(0, 50)) { const op = h('option', null, v.labelOf(r.id) + ' · ' + r.state); op.value = r.id; s.appendChild(op); } + s.disabled = !others.length; + s.addEventListener('change', () => { if (s.value) setWith(v, v.settings.with.concat([s.value])); }); + box.appendChild(s); + } + return box; + } + /** The person chose other runs to compare with: read them, then build the content again in place. */ + async function setWith(v, others) { + v.settings.with = others.slice(0, RUNS_MOST - 1); + v.act.keepUI('trWith', v.settings.with.join(',') || null); + await rebuild(v); + } + function toggleSeries(v, n) { + const now = v.picked.includes(n) ? v.picked.filter(x => x !== n) : v.picked.concat([n]).slice(0, SERIES_MOST); + v.settings.series = now; + v.act.keepUI('trSeries', now.join(',') || null); + rebuild(v); + } + /** Reads what the content needs and builds it again in the block's element, the focus kept by data-key. */ + async function rebuild(v) { + v.el.setAttribute('aria-busy', 'true'); + try { + const ids = [v.id].concat(v.settings.with); + await Promise.all(ids.map(x => runOf(x).over ? null : overview(x).catch(() => null))); + const { picked } = shownSeries(ids, v.settings.series); + await Promise.all(ids.map(x => seriesOf(x, picked))); + await samplesOf(v.id, runOf(v.id).sampleName); + } catch (error) { console.warn(error); } + v.el.removeAttribute('aria-busy'); + if (view !== v || !v.el.isConnected) return; + const key = document.activeElement && v.el.contains(document.activeElement) ? document.activeElement.dataset.key : null; + fill(v); + if (key) { const again = v.el.querySelector('[data-key="' + CSS.escape(key) + '"]'); if (again) again.focus({ preventScroll: true }); } + } + const drawAll = v => { for (const chart of v.charts.values()) drawChart(v, chart); }; + + // ---- A chart --------------------------------------------------------------------------------------------------- + /** The lines of a chart: for each run in view, its points [x, y, low, high] (y the bucket's mean). */ + function linesOf(v, name) { + return idsOf(v).map((id, i) => { + const s = runOf(id).series.get(name), colour = D.token(COLOURS[i]); + const pts = s ? s.buckets.filter(b => b[3] != null).map(b => [v.settings.x === 'time' ? b[2] : b[1], b[3], b[4], b[5], b[1], b[2]]) : []; + return { id, colour, pts, size: s ? s.size : 1, points: s ? s.points : 0 }; + }); + } + /** Exponential moving average with the start's bias removed, as TensorBoard draws it. */ + function smooth(values, w) { + if (!w) return values; + let last = 0, n = 0; return values.map(y => { last = last * w + (1 - w) * y; n++; return last / (1 - Math.pow(w, n)); }); + } + function scaleOf(lines, log) { + let x0 = Infinity, x1 = -Infinity, y0 = Infinity, y1 = -Infinity; + for (const l of lines) for (const p of l.pts) { + x0 = Math.min(x0, p[0]); x1 = Math.max(x1, p[0]); + for (const y of [p[1], p[2], p[3]]) if (y != null && (!log || y > 0)) { y0 = Math.min(y0, y); y1 = Math.max(y1, y); } + } + if (!Number.isFinite(x0)) return null; + if (x1 === x0) { x0 -= 0.5; x1 += 0.5; } + if (!Number.isFinite(y0)) return null; + let t = log ? [Math.log10(y0), Math.log10(y1)] : [y0, y1]; + if (t[1] === t[0]) t = [t[0] - (Math.abs(t[0]) || 1) * 0.05, t[1] + (Math.abs(t[1]) || 1) * 0.05]; + const pad = (t[1] - t[0]) * 0.06; + return { x0, x1, y0: t[0] - pad, y1: t[1] + pad, log }; + } + const ticks = (a, b, n) => { const span = b - a, step0 = Math.pow(10, Math.floor(Math.log10(span / n))), err = n / (span / step0), step = step0 * (err <= 0.15 ? 10 : err <= 0.35 ? 5 : err <= 0.75 ? 2 : 1); const out = []; for (let t = Math.ceil(a / step) * step; t <= b + step * 1e-9; t += step) out.push(+t.toPrecision(12)); return out; }; + function drawChart(v, chart) { + const c = chart.canvas, size = D.fit(c, CHART_HEIGHT); if (!size) return; + const [W, H] = size, dpr = window.devicePixelRatio || 1, g = c.getContext('2d'); + g.setTransform(1, 0, 0, 1, 0, 0); g.clearRect(0, 0, W, H); g.scale(dpr, dpr); + const w = W / dpr, hh = H / dpr, L = 48, R = 8, T = 8, B = 20; + const lines = linesOf(v, chart.name), sc = scaleOf(lines, v.settings.log); + chart.lines = lines; chart.scale = sc; chart.box = { L, R, T, B, w, hh }; + const ink = 'rgb(' + D.token('--ink-3').join(',') + ')', grid = 'rgb(' + D.token('--grid').join(',') + ')'; + g.font = '11px ' + getComputedStyle(document.body).fontFamily; g.fillStyle = ink; g.strokeStyle = grid; g.lineWidth = 1; + const total = lines.reduce((n, l) => n + l.pts.length, 0); + c.dataset.points = String(total); c.dataset.drawn = String(Number(c.dataset.drawn || 0) + 1); + c.dataset.last = lines[0] && lines[0].pts.length ? String(lines[0].pts[lines[0].pts.length - 1][4]) : ''; + c.dataset.lines = String(lines.filter(l => l.pts.length).length); + const nonpos = v.settings.log && lines.some(l => l.pts.some(p => p[1] <= 0)); + const reduced = lines.find(l => l.size > 1); + setText(chart.note, [reduced ? 'Each point is the mean of ' + reduced.size + ' logged values; the band their least and greatest.' : '', nonpos ? 'Values of 0 or less are left out on the log scale.' : '', v.settings.smooth ? 'Smoothed (' + v.settings.smooth.toFixed(2) + '); the faint line is as logged.' : ''].filter(Boolean).join(' ')); + const main = runOf(v.id).series.get(chart.name), last = main && main.buckets.length ? main.buckets[main.buckets.length - 1][3] : null; + setText(chart.sum, main ? ' · ' + main.points.toLocaleString('en-GB') + ' points · last ' + fmt(last) : ' · not logged by this run'); + c.setAttribute('aria-label', chart.name + ' against the ' + v.settings.x + ', ' + lines.filter(l => l.pts.length).length + ' run' + (lines.length === 1 ? '' : 's') + (last != null ? '; the last value of this run ' + fmt(last) : '')); + if (!sc) { g.fillText('Nothing to draw yet.', L, T + 14); return; } + const X = x => L + (x - sc.x0) / (sc.x1 - sc.x0) * (w - L - R), Y = y => T + (1 - ((sc.log ? Math.log10(y) : y) - sc.y0) / (sc.y1 - sc.y0)) * (hh - T - B); + chart.X = X; chart.Y = Y; + // Grid and axes. + const yt = sc.log ? ticks(sc.y0, sc.y1, 3).filter(t => Number.isInteger(t)).map(t => Math.pow(10, t)) : ticks(sc.y0, sc.y1, 3); + g.textAlign = 'right'; g.textBaseline = 'middle'; + for (const t of yt) { const y = Y(t); if (y < T - 1 || y > hh - B + 1) continue; g.beginPath(); g.moveTo(L, Math.round(y) + 0.5); g.lineTo(w - R, Math.round(y) + 0.5); g.stroke(); g.fillText(C.fmtSci(t), L - 4, y); } + g.textAlign = 'center'; g.textBaseline = 'top'; + for (const t of ticks(sc.x0, sc.x1, 4)) { const x = X(t); if (x < L - 1 || x > w - R + 1) continue; g.fillText(v.settings.x === 'time' ? seconds(t) : t.toLocaleString('en-GB'), x, hh - B + 4); } + // Checkpoints of the run opened, as ticks on the step axis. + const o = runOf(v.id).over; + if (o && v.settings.x === 'step') { g.strokeStyle = ink; for (const k of o.checkpoints || []) { const x = X(k.step); if (x < L || x > w - R) continue; g.beginPath(); g.moveTo(x, hh - B); g.lineTo(x, hh - B - 5); g.stroke(); } } + // Bands, then raw lines (faint when smoothed), then smoothed lines. + g.save(); g.beginPath(); g.rect(L, T, w - L - R, hh - T - B); g.clip(); + const ok = y => y != null && (!sc.log || y > 0); + for (const l of lines) { + const rgb = l.colour.join(','); + if (l.size > 1) { + const band = l.pts.filter(p => ok(p[2]) && ok(p[3])); + if (band.length > 1) { g.fillStyle = 'rgba(' + rgb + ',0.16)'; g.beginPath(); band.forEach((p, i) => (i ? g.lineTo : g.moveTo).call(g, X(p[0]), Y(p[3]))); for (let i = band.length - 1; i >= 0; i--) g.lineTo(X(band[i][0]), Y(band[i][2])); g.closePath(); g.fill(); } + } + const path = (ys, alpha, width) => { g.strokeStyle = 'rgba(' + rgb + ',' + alpha + ')'; g.lineWidth = width; g.lineJoin = 'round'; g.beginPath(); let on = false; l.pts.forEach((p, i) => { const y = ys[i]; if (!ok(y)) { on = false; return; } if (on) g.lineTo(X(p[0]), Y(y)); else { g.moveTo(X(p[0]), Y(y)); on = true; } }); g.stroke(); if (l.pts.length === 1 && ok(ys[0])) { g.fillStyle = g.strokeStyle; g.beginPath(); g.arc(X(l.pts[0][0]), Y(ys[0]), 3, 0, 7); g.fill(); } }; + const raw = l.pts.map(p => p[1]); + if (v.settings.smooth) { path(raw, 0.25, 1); path(smoothLog(raw, v.settings.smooth, sc.log), 1, 2); } + else path(raw, 1, 2); + } + g.restore(); + } + /** Smoothing in the drawn space: on a log scale the logarithms are smoothed, so a falling loss is not pulled up. */ + function smoothLog(raw, w, log) { + if (!log) return smooth(raw, w); + const out = new Array(raw.length).fill(null), idx = [], logs = []; + raw.forEach((y, i) => { if (y > 0) { idx.push(i); logs.push(Math.log10(y)); } }); + smooth(logs, w).forEach((y, k) => { out[idx[k]] = Math.pow(10, y); }); + return out; + } + function hover(v, chart) { + const c = chart.canvas, tip = chart.tip; + c.addEventListener('mousemove', e => { + const sc = chart.scale; if (!sc || !chart.X) return; + const r = c.getBoundingClientRect(), mx = e.clientX - r.left, { L, R, w } = chart.box; + if (mx < L || mx > w - R) { tip.hidden = true; return; } + const x = sc.x0 + (mx - L) / (w - L - R) * (sc.x1 - sc.x0); + tip.textContent = ''; + const head = h('div', 'trn-tip-head', (v.settings.x === 'time' ? 'at ' + seconds(x) : 'step ' + Math.round(x).toLocaleString('en-GB'))); tip.appendChild(head); + chart.lines.forEach(l => { + if (!l.pts.length) return; + let best = l.pts[0]; for (const p of l.pts) if (Math.abs(p[0] - x) < Math.abs(best[0] - x)) best = p; + const row = h('div', 'trn-tip-row'); const sw = h('span', 'trn-swatch'); sw.style.background = 'rgb(' + l.colour.join(',') + ')'; row.appendChild(sw); + row.appendChild(h('span', null, v.labelOf(l.id) + ': ' + fmt(best[1]) + ' at step ' + best[4].toLocaleString('en-GB') + ' · ' + seconds(best[5]))); + tip.appendChild(row); + }); + tip.hidden = false; + const left = Math.min(Math.max(0, mx + 12), r.width - tip.offsetWidth - 2); tip.style.left = Math.max(0, left) + 'px'; tip.style.top = '4px'; + }); + c.addEventListener('mouseleave', () => { tip.hidden = true; }); + } + + // ---- Histograms ------------------------------------------------------------------------------------------------ + function histograms(v) { + v.histBox.textContent = ''; + const o = runOf(v.id).over; if (!o || !o.histograms.length) return; + const box = h('div', 'trn-hists'); box.appendChild(h('h4', null, 'Histograms over the steps')); + const kinds = [...new Set(o.histograms.map(x => x.kind))]; + if (!kinds.includes(v.kind)) v.kind = kinds[0]; + const head = h('div', 'trn-controls'); + if (kinds.length > 1) { + const sw = h('div', 'seg'); sw.setAttribute('role', 'group'); sw.setAttribute('aria-label', 'Which values'); + for (const k of kinds) { const b = button('btn sm', k === 'weights' ? 'Weights' : 'Gradients', () => { v.kind = k; rebuild(v); }); b.setAttribute('aria-pressed', String(k === v.kind)); b.dataset.key = 'trn-kind-' + k; sw.appendChild(b); } + head.appendChild(sw); + } + head.appendChild(h('span', 'small faint', 'Steps across, values up; each column shaded by its share of the values.')); + box.appendChild(head); + const list = o.histograms.filter(x => x.kind === v.kind), shown = v.all ? list : list.slice(0, STRIPS_FIRST); + for (const item of shown) { + const row = h('div', 'trn-strip-row'); + const label = h('div', 'small trn-strip-label'); label.appendChild(h('span', 'mono', item.name)); const range = h('span', 'faint'); label.appendChild(range); row.appendChild(label); + const c = h('canvas', 'trn-strip'); c.dataset.tensor = item.name; c.dataset.kind = item.kind; c.setAttribute('role', 'img'); c.setAttribute('aria-label', 'The ' + item.kind + ' of ' + item.name + ' over the steps'); row.appendChild(c); + box.appendChild(row); + const strip = { canvas: c, range, name: item.name, kind: item.kind }; + D.paints(c, () => drawStrip(v, strip)); + watch(v, strip); + } + if (list.length > shown.length) { const more = button('btn sm ghost', 'Show all ' + list.length, () => { v.all = true; rebuild(v); }); more.dataset.key = 'trn-all'; box.appendChild(more); } + v.histBox.appendChild(box); + } + const histKey = (name, kind) => name + '\u0000' + kind; + const seen = new IntersectionObserver(entries => { for (const e of entries) if (e.isIntersecting && e.target._strip) { seen.unobserve(e.target); readStrip(e.target._strip.v, e.target._strip.s); } }); + /** A strip is read when it comes on screen, and again then when histograms were added since it was read. */ + function watch(v, strip) { strip.canvas._strip = { v, s: strip }; const r = runOf(v.id), kept = r.hist.get(histKey(strip.name, strip.kind)); if (kept && r.over && kept.at === r.over.histogram_lines) return; seen.observe(strip.canvas); } + async function readStrip(v, strip) { + const r = runOf(v.id), key = histKey(strip.name, strip.kind), at = r.over ? r.over.histogram_lines : 0; + try { r.hist.set(key, { answer: await P.call('training_histograms', { run: v.id, name: strip.name, kind: strip.kind, most: HIST_ROWS, bins: HIST_BINS }), at }); } + catch (error) { strip.range.textContent = ' · ' + error.message; return; } + if (strip.canvas.isConnected) drawStrip(v, strip); + } + function drawStrip(v, strip) { + const kept = runOf(v.id).hist.get(histKey(strip.name, strip.kind)), c = strip.canvas, size = D.fit(c, STRIP_HEIGHT); + if (!size || !kept) return; + const a = kept.answer, cols = a.rows.length, rows = a.bins, values = new Float32Array(rows * cols); + for (let j = 0; j < cols; j++) { const total = a.totals[j] || 1, col = a.counts[j]; for (let b = 0; b < rows; b++) values[(rows - 1 - b) * cols + j] = Math.sqrt(col[b] / total); } + const lo = D.token('--ramp-lo'), hi = D.token('--ramp-hi'), colour = t => [lo[0] + (hi[0] - lo[0]) * t, lo[1] + (hi[1] - lo[1]) * t, lo[2] + (hi[2] - lo[2]) * t]; + const g = c.getContext('2d'); g.setTransform(1, 0, 0, 1, 0, 0); g.clearRect(0, 0, size[0], size[1]); + D.heat(g, values, rows, cols, colour, 0, 0, size[0], size[1]); + c.dataset.drawn = String(Number(c.dataset.drawn || 0) + 1); c.dataset.rows = String(cols); + const text = ' · ' + fmt(a.low) + ' to ' + fmt(a.high) + ' · steps ' + a.rows[0].step.toLocaleString('en-GB') + '–' + a.rows[cols - 1].step.toLocaleString('en-GB'); + setText(strip.range, text); + } + + // ---- Samples --------------------------------------------------------------------------------------------------- + function samples(v) { + v.sampleBox.textContent = ''; v.samplesStrip = null; + const r = runOf(v.id), o = r.over; if (!o || !o.samples.length) return; + const box = h('div', 'trn-samples-box'); const head = h('div', 'trn-controls'); head.appendChild(h('h4', null, 'Samples')); + if (o.samples.length > 1) { + const s = h('select'); s.dataset.key = 'trn-sample'; s.setAttribute('aria-label', 'Which samples'); + for (const x of o.samples) { const op = h('option', null, x.name + ' · ' + x.count); op.value = x.name; s.appendChild(op); } + s.value = r.sampleName; s.addEventListener('change', () => { r.sampleName = s.value; rebuild(v); }); head.appendChild(s); + } else head.appendChild(h('span', 'small faint', o.samples[0].name)); + box.appendChild(head); + const strip = h('div', 'trn-samples'); strip.setAttribute('role', 'list'); strip.tabIndex = 0; strip.setAttribute('aria-label', 'The last samples, newest last'); + const held_ = r.samples.get(r.sampleName); + for (const item of held_ ? held_.items : []) strip.appendChild(sampleFigure(v, item)); + v.samplesStrip = strip; + box.appendChild(strip); v.sampleBox.appendChild(box); + requestAnimationFrame(() => { strip.scrollLeft = strip.scrollWidth; }); + } + function sampleFigure(v, item) { + const fig = h('figure', 'trn-sample'); fig.setAttribute('role', 'listitem'); fig.dataset.step = String(item.step); fig.dataset.index = String(item.index); + if (item.problem) fig.appendChild(h('div', 'trn-thumb small faint', item.problem)); + else if (item.kind === 'image') { const img = h('img', 'trn-thumb'); img.alt = item.name + ' at step ' + item.step; img.src = item.url; img.width = SAMPLE_SIZE; img.height = SAMPLE_SIZE; img.loading = 'lazy'; fig.appendChild(img); } + else { const c = h('canvas', 'trn-thumb'); c.setAttribute('role', 'img'); c.setAttribute('aria-label', item.name + ' at step ' + item.step); fig.appendChild(c); D.paints(c, () => drawArray(v, item, c)); } + fig.appendChild(h('figcaption', 'small num', 'step ' + item.step.toLocaleString('en-GB'))); + return fig; + } + async function drawArray(v, item, c) { + const r = runOf(v.id); let a = r.arrays.get(item.index); + if (!a) { try { a = (await P.call('training_sample', { run: v.id, index: item.index })).content; r.arrays.set(item.index, a); } catch (error) { c.title = error.message; return; } } + const size = D.fit(c, SAMPLE_SIZE); if (!size) return; + const values = D.floats(a.values_f32), g = c.getContext('2d'); g.setTransform(1, 0, 0, 1, 0, 0); g.clearRect(0, 0, size[0], size[1]); + const [x, y, w, hh] = D.contain(a.rows, a.columns, size[0], size[1]); + D.heat(g, values, a.rows, a.columns, D.ramp(a.min == null ? 0 : a.min, a.max == null ? 1 : a.max), x, y, w, hh); + c.dataset.drawn = String(Number(c.dataset.drawn || 0) + 1); + } + + // ---- Live ------------------------------------------------------------------------------------------------------ + let ticking = false; + /** + * One step of the live block (tabs.js calls it on every reading): for each run in view whose last answer said it + * was active, `training` once; then only what grew is read and drawn, in place. + */ + async function tick() { + const v = view; if (!v || !v.el.isConnected || ticking) return; + const ids = [v.id].concat(v.settings.with).filter(id => { const o = runOf(id).over; return o && o.run.active; }); + if (!ids.length) return; + ticking = true; + try { + for (const id of ids) { + const r = runOf(id), before = r.over; + const o = await overview(id); + if (view !== v || !v.el.isConnected) return; + const grewLines = o.lines !== before.lines, grewHist = o.histogram_lines !== before.histogram_lines, grewSamples = o.sample_lines !== before.sample_lines; + const wasEmpty = !before.lines && !before.histogram_lines && !before.sample_lines; + if (id === v.id && wasEmpty && (grewLines || grewHist || grewSamples)) { await rebuild(v); continue; } // its first lines: the block's content is drawn + let samplesDrawn = false; + if (id === v.id) { // a name not there before: its control or its part is added, the rest left as it is + const names = shownSeries(idsOf(v), v.settings.series).names; + if (names.some(n => !before.series.some(b => b.name === n))) chooserButtons(v, names); + if (o.histograms.length !== before.histograms.length) histograms(v); + if (o.samples.length !== before.samples.length) { r.sampleName = sampleName(o, r.sampleName); await samplesOf(id, r.sampleName); if (view !== v) return; samples(v); samplesDrawn = true; } + } + if (grewLines) { await seriesOf(id, v.picked || []); if (view !== v) return; drawAll(v); } + if (id === v.id) { + setAt(v); + if (grewHist) for (const c of v.el.querySelectorAll('canvas.trn-strip')) { const s = c._strip && c._strip.s; if (s && r.hist.has(histKey(s.name, s.kind))) await readStrip(v, s); } + if (grewSamples && v.samplesStrip && !samplesDrawn) { + const added = await samplesOf(id, r.sampleName); + if (added && added.length && view === v) { + for (const item of added) v.samplesStrip.appendChild(sampleFigure(v, item)); + while (v.samplesStrip.children.length > SAMPLES_SHOWN) v.samplesStrip.firstChild.remove(); + v.samplesStrip.scrollLeft = v.samplesStrip.scrollWidth; + } + } + } + } + } catch (error) { /* the next reading asks again */ } + finally { ticking = false; } + } + /** Whether a run in the block on screen is read live (app.js keeps reading every two seconds while one is). */ + const live = () => !!(view && view.el.isConnected && [view.id].concat(view.settings.with).some(id => { const o = runOf(id).over; return o && o.run.active; })); + + return { read, block, tick, live, ACTIVE }; +})(); diff --git a/tests/browser_project_workspace_training.cjs b/tests/browser_project_workspace_training.cjs new file mode 100644 index 00000000..82fb36a6 --- /dev/null +++ b/tests/browser_project_workspace_training.cjs @@ -0,0 +1,303 @@ +'use strict'; +// What a training script logged, drawn live in a run's drawer on the Train tab +// (docs/plans/training-and-curation/spec-t1.md sections 6 and 8, slice T1c), in a headless browser, the owner signed +// in, no GPU. Tuldok runs with --project-folder on a copy of the minimal fixture with the buildable fixture's +// definitions beside it, in a Git repository of its own, and three recipes that run a stand-in training script +// (tests/project_training_stand_in.py: a linear model fitted in plain Python, logged through tuldok_log, which the +// recipe puts on PYTHONPATH): trainer-a and trainer-b are built before Tuldok starts (sixty steps, finished in a +// moment), trainer-live is asked for while the page watches and runs about ten seconds. +// 1. trainer-a's drawer shows Training: the loss drawn, with trainer-b overlaid from "Compare with" (two lines, +// a legend of two); the address keeps it, and a reload draws the same. +// 2. Smoothing, log scale and By time draw the chart again (another image), the block the same element; another +// series chosen adds its chart. +// 3. Histograms drawn (strips not blank, one per tensor, weights and gradients) and samples drawn (images +// loaded, arrays drawn, steps under them). +// 4. trainer-live, opened while it runs: its curve grows across readings (more points, a later last step) while +// a marker on the block, its chart and its strips survives and no node of the block is added or removed +// outside the samples strip (where new samples are appended); when it ends, all sixty lines are drawn. +// 5. With the finished run open, a return to the window touches nothing in the drawer. +// 6. Light and dark at 1440 and 390 wide: no blank chart, nothing overflowing sideways; no script error and no +// failed request. +// node tests/browser_project_workspace_training.cjs [--shots ] +const assert = require('node:assert/strict'), fs = require('node:fs'), os = require('node:os'), path = require('node:path'); +const { spawn, execFileSync } = require('node:child_process'), { once } = require('node:events'); +const { authenticatedFixture } = require('./auth_helpers.cjs'), { waitForDebugger } = require('./browser_startup.cjs'), { cdpSession } = require('./browser_cdp_session.cjs'), { qaDirectory } = require('./qa_artifacts.cjs'); + +const root = path.resolve(__dirname, '..'); +const argv = process.argv.slice(2), option = name => { const i = argv.indexOf(name); return i >= 0 ? argv[i + 1] : null; }; +assert.ok(process.env.TULDOK_DATABASE_URL, 'TULDOK_DATABASE_URL must name a disposable PostgreSQL cluster'); +const venv = path.join(root, '.venv', 'bin'); +if (fs.existsSync(path.join(venv, 'python'))) process.env.PATH = venv + path.delimiter + process.env.PATH; // auth_helpers runs python3 +const python = fs.existsSync(path.join(venv, 'python')) ? path.join(venv, 'python') : 'python3'; +const WATCHED = ['summary', 'status', 'build_requests', 'environments', 'runs']; +const STEPS = 60, LIVE_STEPS = 50, LIVE_SLEEP = 0.25; + +const temporary = fs.mkdtempSync(path.join(os.tmpdir(), 'tuldok-training-browser-')); +const report = qaDirectory(root, 'project-workspace-training'); +const shots = option('--shots') ? path.resolve(option('--shots')) : null; if (shots) fs.mkdirSync(shots, { recursive: true }); +const children = [], checks = [], errors = [], failures = []; +let server, serverErrors = '', origin, auth, socket, session, send, evaluate, owned = null; +const pause = ms => new Promise(resolve => setTimeout(resolve, ms)); +async function until(fn, label, tries = 300) { for (let i = 0; i < tries; i++) { const value = await fn(); if (value) return value; await pause(100); } throw Error('Timed out: ' + label); } +function check(text) { checks.push(text); console.log('PASS ' + text); } +function launch(command, args, options) { const child = spawn(command, args, options); children.push(child); return child; } +async function stop(child) { if (!child || child.exitCode !== null || child.signalCode !== null) return; const exited = once(child, 'exit'); child.kill('SIGTERM'); await Promise.race([exited, pause(10000)]); if (child.exitCode === null && child.signalCode === null) { child.kill('SIGKILL'); await exited; } } +function findBrowser() { + const candidates = [process.env.BROWSER, '/usr/bin/chromium', '/usr/bin/chromium-browser', '/usr/bin/google-chrome']; + const cache = path.join(os.homedir(), '.cache', 'ms-playwright'); + if (fs.existsSync(cache)) for (const name of fs.readdirSync(cache).filter(n => n.startsWith('chromium_headless_shell-')).sort().reverse()) candidates.push(path.join(cache, name, 'chrome-headless-shell-linux64', 'chrome-headless-shell')); + const found = candidates.find(candidate => candidate && fs.existsSync(candidate)); + assert.ok(found, 'No headless browser: set BROWSER'); + return found; +} +/** Drops the project's schema and the catalog's from the disposable database, so each run imports afresh. */ +function dropOwned(folder, catalog) { + const id = JSON.parse(fs.readFileSync(path.join(folder, 'tuldok.json'), 'utf8')).id; + execFileSync(python, ['-c', `import json, os, pathlib, sys, psycopg +from psycopg import sql +from tuldok_project import store +store.drop_project(sys.argv[1], os.environ['TULDOK_DATABASE_URL']) +root = pathlib.Path(sys.argv[2]) +if root.exists(): + with psycopg.connect(os.environ['TULDOK_DATABASE_URL'], autocommit=True) as c: + for p in root.rglob('.tuldok.json'): + v = json.loads(p.read_text()) + name = 'projection_' + v['projection_id'] if v.get('version') == 2 else 'catalog_' + v['dataset_id'] + c.execute(sql.SQL('DROP SCHEMA IF EXISTS {} CASCADE').format(sql.Identifier(name))) +`, id, catalog], { cwd: root, stdio: ['ignore', 'pipe', 'pipe'] }); +} +async function contract(name) { + const capabilities = await (await auth.fetch(origin + '/api/agent/capabilities')).json(); + const operation = capabilities.operations.find(item => item.id === 'project.' + name), c = operation.contracts[operation.contracts.length - 1]; + return 'project.' + name + '/' + c.version + '/' + c.sha256; +} +/** An operation as the owner. */ +async function api(name, body = {}) { + const headers = { 'Content-Type': 'application/json', 'Tuldok-Operation-Contract': await contract(name) }; + const response = await auth.fetch(origin + '/api/project/' + name, { method: 'POST', headers, body: JSON.stringify(body) }); + const value = await response.json(); assert.equal(response.status, 200, name + ': ' + JSON.stringify(value)); return value; +} + +// ---- The page's requests, from the browser's network --------------------------------------------------------------------- +const calls = new Map(), finished = []; +function network(event) { + const p = event.params; + if (event.method === 'Network.requestWillBeSent' && /\/api\/project\/[a-z_]+$/.test(p.request.url)) { let body = null; try { body = p.request.postData ? JSON.parse(p.request.postData) : null; } catch (_) { body = null; } calls.set(p.requestId, { name: p.request.url.split('/').pop(), body, sent: Date.now() }); } + if ((event.method === 'Network.loadingFinished' || event.method === 'Network.loadingFailed') && calls.has(p.requestId)) { finished.push(Object.assign(calls.get(p.requestId), { done: Date.now() })); calls.delete(p.requestId); } +} +const asked = (name, since = 0) => finished.concat([...calls.values()]).filter(f => f.name === name && f.sent >= since); +async function settled(label) { + await until(() => evaluate(`(() => { const a = document.getElementById('aside'), m = document.getElementById('main'); return ![...a.querySelectorAll('.note'), ...m.querySelectorAll('.note')].some(n => n.textContent === 'Reading…') && !a.querySelector('[aria-busy]') && !m.hasAttribute('aria-busy'); })()`).then(ok => ok && !calls.size), 'settled: ' + label); + await pause(250); +} +async function frames() { await evaluate('new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve)))'); } +async function shot(name) { + await frames(); + const png = Buffer.from((await send('Page.captureScreenshot', { format: 'png', captureBeyondViewport: false })).data, 'base64'); + fs.writeFileSync(path.join(report, name + '.png'), png); if (shots) fs.writeFileSync(path.join(shots, name + '.png'), png); +} +const byKey = key => `[data-key=${JSON.stringify(key)}]`; +async function choose(selector, value) { await evaluate(`(() => { const s = document.querySelector(${JSON.stringify(selector)}); s.focus(); s.value = ${JSON.stringify(value)}; s.dispatchEvent(new Event('change', { bubbles: true })); return true; })()`); } +async function slide(selector, value) { await evaluate(`(() => { const r = document.querySelector(${JSON.stringify(selector)}); r.focus(); r.value = ${JSON.stringify(String(value))}; r.dispatchEvent(new Event('input', { bubbles: true })); return true; })()`); } +async function click(selector) { await evaluate(`(() => { const b = document.querySelector(${JSON.stringify(selector)}); b.click(); return true; })()`); } +// What a canvas shows: a sum over its pixels that changes when the drawing does, and how many are drawn. +const PIXELS = `c => { if (!c || !c.width) return null; const d = c.getContext('2d').getImageData(0, 0, c.width, c.height).data; let drawn = 0, sum = 0; for (let i = 0; i < d.length; i += 4) if (d[i + 3]) { drawn++; sum = (sum + (i / 4 + 1) * (d[i] * 3 + d[i + 1] * 5 + d[i + 2] * 7)) % 2147483647; } return { drawn, sum, points: Number(c.dataset.points || 0), lines: Number(c.dataset.lines || 0), last: Number(c.dataset.last || -1), times: Number(c.dataset.drawn || 0) }; }`; +const chart = series => evaluate(`(${PIXELS})(document.querySelector('#aside .trn canvas.trn-chart[data-series=${JSON.stringify(series)}]'))`); +const block = () => evaluate(`(() => { const t = document.querySelector('#aside .trn'); if (!t) return null; return { run: t.dataset.run, legend: [...t.querySelectorAll('.trn-legend li')].map(li => li.dataset.run), charts: [...t.querySelectorAll('canvas.trn-chart')].map(c => c.dataset.series), strips: [...t.querySelectorAll('canvas.trn-strip')].map(c => [c.dataset.tensor, c.dataset.kind, Number(c.dataset.drawn || 0)]), samples: [...t.querySelectorAll('.trn-sample')].map(f => Number(f.dataset.step)), at: (t.querySelector('.trn-at') || {}).textContent || '', none: (t.querySelector('.trn-none') || {}).textContent || null }; })()`); + +(async () => { + // ---- The fixture ----------------------------------------------------------------------------------------------------------- + fs.cpSync(path.join(root, 'tests', 'fixtures', 'tuldok_project', 'minimal'), path.join(temporary, 'fixture'), { recursive: true }); + const folder = path.join(temporary, 'fixture', 'project'), code = path.join(temporary, 'fixture', 'code'), buildable = path.join(root, 'tests', 'fixtures', 'tuldok_project', 'buildable'); + for (const kind of ['environments', 'datasets', 'recipes', 'benchmarks', 'charts']) for (const name of fs.readdirSync(path.join(buildable, 'project', kind))) fs.copyFileSync(path.join(buildable, 'project', kind, name), path.join(folder, kind, name)); + for (const name of fs.readdirSync(path.join(buildable, 'code'))) fs.cpSync(path.join(buildable, 'code', name), path.join(code, name), { recursive: true }); + fs.copyFileSync(path.join(root, 'tests', 'project_training_stand_in.py'), path.join(code, 'logged_train.py')); + const recipe = (name, title, short, args) => fs.writeFileSync(path.join(folder, 'recipes', name + '.json'), JSON.stringify({ format: 'tuldok_definition_v1', kind: 'recipe', title, labels: { short }, change: 'training-policy', derived_from: 'recipes/fit-a', + run: { command: ['python', 'logged_train.py', '--out', '{output}', ...args], environment: 'environments/test-python', env: { PYTHONPATH: root }, outputs: { weights: { path: 'weights.json', role: 'weights' } }, sources: ['logged_train.py'] } }, null, 2) + '\n'); + recipe('trainer-a', 'Stand-in trainer, rate 0.05', 'TRA', ['--steps', String(STEPS), '--lr', '0.05', '--seed', '1']); + recipe('trainer-b', 'Stand-in trainer, rate 0.02', 'TRB', ['--steps', String(STEPS), '--lr', '0.02', '--seed', '1']); + recipe('trainer-live', 'Stand-in trainer, slowed', 'TRL', ['--steps', String(LIVE_STEPS), '--lr', '0.05', '--seed', '2', '--sleep', String(LIVE_SLEEP)]); + const git = ['-c', 'user.name=Tuldok Test', '-c', 'user.email=test@example.invalid', '-c', 'commit.gpgsign=false', '-c', 'init.defaultBranch=main', '-C', path.join(temporary, 'fixture')]; + execFileSync('git', [...git, 'init', '-q']); execFileSync('git', [...git, 'add', '-A']); execFileSync('git', [...git, 'commit', '-q', '-m', 'The fixture.']); + const home = path.join(temporary, 'home'), catalog = path.join(temporary, 'catalog'); fs.mkdirSync(home); + const env = { ...process.env, TULDOK_PROJECT_HOME: home, TULDOK_SETTINGS: path.join(temporary, 'settings.json') }; + owned = [folder, catalog]; dropOwned(folder, catalog); + const cli = (...args) => execFileSync(python, ['-m', 'tuldok_project', ...args], { cwd: root, env, stdio: ['ignore', 'pipe', 'pipe'] }).toString(); + cli('connect', folder, 'test-python', python); + cli('build', folder, 'recipes/trainer-a', '--yes'); cli('build', folder, 'recipes/trainer-b', '--yes'); + let output = ''; + server = launch(python, ['-u', 'app.py', '--port', '0', '--data', catalog, '--project-folder', folder], { cwd: root, env, stdio: ['ignore', 'pipe', 'pipe'] }); + server.stdout.on('data', chunk => { output += chunk; }); server.stderr.on('data', chunk => { serverErrors += chunk; }); + const port = await until(() => { if (server.exitCode !== null) throw Error('Tuldok exited: ' + serverErrors); return output.match(/127\.0\.0\.1:(\d+)/)?.[1]; }, 'Tuldok start-up', 3000); + origin = 'http://127.0.0.1:' + port; + auth = authenticatedFixture(); await auth.register(origin, catalog, root); + const runs = (await api('runs')).runs, runA = runs.find(r => r.reference === 'recipes/trainer-a').id, runB = runs.find(r => r.reference === 'recipes/trainer-b').id; + for (const id of [runA, runB]) { const o = await api('training', { run: id }); assert.equal(o.lines, STEPS, 'the stand-in logged every step'); } + + const browser = launch(findBrowser(), ['--headless', '--no-sandbox', '--disable-gpu', '--no-first-run', '--hide-scrollbars', '--remote-debugging-port=0', '--window-size=1440,900', '--user-data-dir=' + path.join(temporary, 'browser'), 'about:blank'], { stdio: 'ignore', env: { ...process.env, XDG_CONFIG_HOME: temporary, XDG_CACHE_HOME: temporary } }); + const debugPort = await waitForDebugger(browser, path.join(temporary, 'browser', 'DevToolsActivePort')); + const target = (await (await fetch('http://127.0.0.1:' + debugPort + '/json')).json()).find(item => item.type === 'page'); + socket = new WebSocket(target.webSocketDebuggerUrl); await once(socket, 'open'); + session = cdpSession(socket, { timeoutMs: 60000, onEvent: event => { + network(event); + if (event.method === 'Runtime.exceptionThrown') errors.push(event.params.exceptionDetails.exception?.description || event.params.exceptionDetails.text); + if (event.method === 'Runtime.consoleAPICalled' && event.params.type === 'error') errors.push(event.params.args.map(a => a.value ?? a.description).join(' ')); + if (event.method === 'Log.entryAdded' && event.params.entry.level === 'error') errors.push(event.params.entry.text + ' ' + (event.params.entry.url || '')); + if (event.method === 'Network.loadingFailed' && !event.params.canceled) failures.push({ id: event.params.requestId, error: event.params.errorText }); + if (event.method === 'Network.responseReceived' && event.params.response.status >= 400) failures.push({ url: event.params.response.url, status: event.params.response.status }); + } }); + send = session.send; + evaluate = async expression => { const result = await send('Runtime.evaluate', { expression, awaitPromise: true, returnByValue: true }); if (result.exceptionDetails) throw Error(JSON.stringify(result.exceptionDetails)); return result.result.value; }; + await send('Page.enable'); await send('Runtime.enable'); await send('Network.enable'); await send('Log.enable'); + const size = async (width, height) => send('Emulation.setDeviceMetricsOverride', { width, height, deviceScaleFactor: 1, mobile: width < 600 }); + const theme = async name => { await send('Emulation.setEmulatedMedia', { features: [{ name: 'prefers-color-scheme', value: name }, { name: 'prefers-reduced-motion', value: 'reduce' }] }); }; + await auth.browser(send, origin); + /** Opens a run's drawer on the Train tab in a theme with the address's settings (a page of its own). */ + const load = async (name, run, query) => { + await theme(name); + await send('Page.navigate', { url: 'about:blank' }); await pause(100); + await send('Page.navigate', { url: origin + '/?theme=' + name + (query ? '&' + query : '') + '#train/' + encodeURIComponent('run:' + run) }); + await until(() => evaluate(`document.readyState === 'complete' && !!document.getElementById('needs-btn') && !document.getElementById('needs-btn').disabled`), 'the project read', 1200); + await until(() => evaluate(`!!document.querySelector('#aside .trn')`), 'the Training block'); + await settled('opened ' + run); + }; + const drawnChart = (series, lines) => until(async () => { const c = await chart(series); return c && c.times > 0 && c.drawn > 100 && (!lines || c.lines === lines) ? c : null; }, 'the chart of ' + series); + + // ---- 1. trainer-a with trainer-b overlaid -------------------------------------------------------------------------------------- + await size(1440, 900); await load('light', runA); + const one = await drawnChart('loss', 1); + let b1 = await block(); + assert.deepEqual(b1.legend, [runA], 'one run in the legend'); assert.deepEqual(b1.charts, ['loss'], 'the loss is drawn first'); + assert.equal(one.points, STEPS, 'every logged step is a point'); assert.equal(one.last, STEPS); + assert.match(b1.at, new RegExp('Step ' + STEPS + ' ')); + await choose(byKey('trn-with'), runB); await settled('compared'); + const two = await drawnChart('loss', 2); + b1 = await block(); + assert.deepEqual(b1.legend, [runA, runB], 'two runs in the legend'); assert.equal(two.points, 2 * STEPS); + const query1 = (await evaluate('location.search')).replace(/^\?/, '').split('&').filter(p => !p.startsWith('theme=')).join('&'); + assert.equal(new URLSearchParams(query1).get('trWith'), runB, 'the address keeps the run compared with'); + await load('light', runA, query1); + const two2 = await drawnChart('loss', 2); + assert.equal(two2.sum, two.sum, 'a reload draws the same'); + await shot('light-1440-1-overlaid'); + check('1. ' + runA.slice(0, 8) + ' drew its loss (' + one.points + ' points, last step ' + one.last + '); "Compare with" added ' + runB.slice(0, 8) + ': two lines, a legend of two; the address kept trWith and a reload drew the same image'); + + // ---- 2. Smoothing, log scale, by time; another series ---------------------------------------------------------------------------- + await evaluate(`(() => { document.querySelector('#aside .trn').__mark = 1; document.querySelector('#aside canvas.trn-chart').__mark = 2; return true; })()`); + const marks = () => evaluate(`(() => { const t = document.querySelector('#aside .trn'), c = document.querySelector('#aside canvas.trn-chart'); return [t && t.__mark, c && c.__mark]; })()`); + const since2 = Date.now(), images = [two2.sum]; + await slide(byKey('trn-smooth'), 0.8); await frames(); images.push((await chart('loss')).sum); + await click(byKey('trn-log')); await frames(); images.push((await chart('loss')).sum); + await choose(byKey('trn-x'), 'time'); await frames(); images.push((await chart('loss')).sum); + assert.equal(new Set(images).size, 4, 'each control draws another image: ' + images); + assert.deepEqual(await marks(), [1, 2], 'the block and the chart are the same elements'); + assert.equal(asked('training_series', since2).length + asked('training', since2).length, 0, 'drawing again asks nothing'); + const q2 = new URLSearchParams(await evaluate('location.search')); + assert.deepEqual([q2.get('trSmooth'), q2.get('trLog'), q2.get('trX')], ['0.8', '1', 'time']); + await shot('light-1440-2-smoothed-log-time'); + await click(byKey('trn-series-val/loss')); await settled('val/loss'); + const val = await drawnChart('val/loss', 2); + assert.deepEqual((await block()).charts, ['loss', 'val/loss']); assert.equal(val.points, 2 * STEPS / 10, 'val/loss has a point every ten steps'); + assert.equal((await marks())[0], 1, 'a series added builds the content in the same block'); + check('2. Smoothing 0.8, log scale and by time each drew another image (' + images.join(' → ') + ') with nothing asked and the block and chart the same elements; the address kept them; val/loss added its chart (' + val.points + ' points)'); + + // ---- 3. Histograms and samples ----------------------------------------------------------------------------------------------------- + const intoView = sel => evaluate(`(() => { const e = document.querySelector(${JSON.stringify(sel)}); if (e) e.scrollIntoView({ block: 'start' }); return !!e; })()`); + await intoView('#aside .trn-hists'); // a strip is read when it comes on screen + const strips = await until(async () => { const b = await block(); return b.strips.length === 2 && b.strips.every(s => s[2] > 0) ? b.strips : null; }, 'the strips drawn'); + assert.deepEqual(strips.map(s => s.slice(0, 2)), [['linear.weight', 'weights'], ['linear.bias', 'weights']]); + const stripPixels = await evaluate(`[...document.querySelectorAll('#aside canvas.trn-strip')].map(c => (${PIXELS})(c).drawn)`); + assert.ok(stripPixels.every(n => n > 200), 'the strips are not blank ' + stripPixels); + const stripRows = await evaluate(`[...document.querySelectorAll('#aside canvas.trn-strip')].map(c => Number(c.dataset.rows))`); + assert.deepEqual(stripRows, [STEPS / 5 + 1, STEPS / 5 + 1], 'one column a logged step (every five, and the first)'); + await click(byKey('trn-kind-gradients')); await settled('gradients'); await intoView('#aside .trn-hists'); + await until(async () => { const b = await block(); return b.strips.length === 2 && b.strips.every(s => s[1] === 'gradients' && s[2] > 0); }, 'the gradients drawn'); + const samples = (await block()).samples; + assert.deepEqual(samples, [10, 20, 30, 40, 50, 60], 'the samples strip, newest last'); + const arrays = await until(() => evaluate(`(() => { const c = [...document.querySelectorAll('#aside .trn-sample canvas')]; return c.length === 6 && c.every(x => Number(x.dataset.drawn) > 0) ? c.map(x => (${PIXELS})(x).drawn) : null; })()`), 'the array samples drawn'); + assert.ok(arrays.every(n => n > 100), 'array samples not blank'); + await choose(byKey('trn-sample'), 'prediction'); await settled('prediction samples'); + const loaded = await until(() => evaluate(`(() => { const i = [...document.querySelectorAll('#aside .trn-sample img')]; return i.length === 6 && i.every(x => x.complete && x.naturalWidth === 8) ? i.length : null; })()`), 'the PNG samples loaded'); + await evaluate(`document.querySelector('#aside .trn-hists').scrollIntoView(); true`); await shot('light-1440-3-histograms-samples'); + check('3. Histograms: ' + strips.length + ' strips of ' + stripRows[0] + ' steps each, not blank (' + stripPixels + ' pixels), weights then gradients; samples: ' + arrays.length + ' arrays drawn at steps ' + samples.join(', ') + ', and ' + loaded + ' PNG images loaded'); + + // ---- 4. A run drawn live ----------------------------------------------------------------------------------------------------------- + await load('light', runA, ''); // no settings: the loss alone, by step + const asking = await api('request_build', { targets: ['recipes/trainer-live'] }); + const liveRun = await until(async () => { const r = (await api('runs')).runs.find(x => x.reference === 'recipes/trainer-live' && x.state === 'running'); return r ? r.id : null; }, 'the live run running', 300); + // The page learns of a build asked for elsewhere on its next reading (at most fifteen seconds while idle, spec-w4 R1); + // a return to the window makes that reading now, and from then on it reads every two seconds while the run runs. + await evaluate(`window.dispatchEvent(new Event('focus')); true`); + await evaluate(`location.hash = '#train/' + encodeURIComponent('run:${liveRun}'); true`); + // From its tenth step it has logged every name it will (val/loss, the samples): from then on a reading adds nothing but points and samples. + await until(async () => { const b = await block(); return b && b.samples.length && (await evaluate(`!!document.querySelector('#aside [data-series="val/loss"]')`)); }, 'the live run\'s names', 300); + // From its tenth step it has logged every name it will (val/loss, the samples): from then on a reading adds nothing but points and samples. + await until(async () => { const b = await block(); return b && b.samples.length > 0 && await evaluate(`!!document.querySelector('#aside [data-series="val/loss"]')`); }, 'the live run\'s names', 300); + const first = await until(async () => { const c = await chart('loss'); return c && c.points >= 3 ? c : null; }, 'the live run\'s first points', 300); + await evaluate(`window.__trn = (() => { const t = document.querySelector('#aside .trn'); t.__mark = 'live'; t.querySelector('canvas.trn-chart').__mark = 'chart'; for (const c of t.querySelectorAll('canvas.trn-strip')) c.__mark = 'strip'; + const counts = { added: 0, removed: 0, what: [] }; new MutationObserver(list => { for (const r of list) { if (r.target.closest && r.target.closest('.trn-samples')) continue; if (r.type === 'childList' && (r.addedNodes.length || r.removedNodes.length)) { counts.added += r.addedNodes.length; counts.removed += r.removedNodes.length; if (counts.what.length < 6) counts.what.push(r.target.className); } } }).observe(t, { childList: true, subtree: true }); + return { counts, still: () => { const now = document.querySelector('#aside .trn'); return !!now && now.__mark === 'live' && now.querySelector('canvas.trn-chart').__mark === 'chart' && [...now.querySelectorAll('canvas.trn-strip')].every(c => c.__mark === 'strip'); } }; })(); true`); + const seenPoints = [first.points], seenLast = [first.last]; + for (let i = 0; i < 3; i++) { + const before = seenPoints[seenPoints.length - 1]; + const c = await until(async () => { const x = await chart('loss'); return x && x.points > before ? x : null; }, 'the curve grows (' + i + ')', 100); + seenPoints.push(c.points); seenLast.push(c.last); + const kept = await evaluate('window.__trn.still()'); assert.ok(kept, 'the block, its chart and its strips are the same elements after a reading'); + } + const counts4 = await evaluate('window.__trn.counts'); + assert.deepEqual([counts4.added, counts4.removed], [0, 0], 'no node of the block added or removed by the readings: ' + JSON.stringify(counts4)); + const grownSamples = (await block()).samples; + await shot('light-1440-4-live'); + const ended = await until(async () => { const r = (await api('runs')).runs.find(x => x.id === liveRun); return r.state !== 'running' ? r.state : null; }, 'the live run ends', 400); + assert.equal(ended, 'succeeded'); + const last4 = await until(async () => { const c = await chart('loss'); const b = await block(); return c && c.points === LIVE_STEPS && !/read live/.test(b.at) ? c : null; }, 'all its lines drawn once it ended', 300); + assert.equal(last4.last, LIVE_STEPS); + assert.equal(asking.state, 'queued'); + check('4. ' + liveRun.slice(0, 8) + ' opened while running: points ' + seenPoints.join(' → ') + ', last step ' + seenLast.join(' → ') + ' across readings, the block, its chart and strips the same elements, no node added or removed outside the samples strip (samples now ' + grownSamples.join(', ') + '); ended ' + ended + ' with all ' + last4.points + ' points drawn'); + + // ---- 5. A return to the window touches nothing ------------------------------------------------------------------------------------- + await settled('after the live run'); + await pause(500); + await evaluate(`window.__quiet = { n: 0, what: [] }; new MutationObserver(list => { for (const r of list) { window.__quiet.n++; if (window.__quiet.what.length < 6) window.__quiet.what.push(r.type + ' ' + (r.target.className || r.target.nodeName)); } }).observe(document.getElementById('aside'), { childList: true, subtree: true, characterData: true, attributes: true }); true`); + const since5 = Date.now(); + await evaluate(`window.dispatchEvent(new Event('focus')); true`); + await until(() => WATCHED.every(name => finished.some(f => f.name === name && f.sent >= since5)), 'the reading on focus'); + await settled('focus'); await pause(700); + const quiet = await evaluate('window.__quiet'); + assert.equal(quiet.n, 0, 'a return to the window touches nothing in the drawer: ' + JSON.stringify(quiet)); + assert.equal(asked('training', since5).length + asked('training_series', since5).length, 0, 'and asks nothing of the training'); + check('5. With the finished run open, a return to the window read the project and touched nothing in the drawer, nothing of its training asked'); + + // ---- 6. Light and dark, 1440 and 390 wide -------------------------------------------------------------------------------------------- + const seen6 = []; + for (const [w, hgt] of [[1440, 900], [390, 844]]) for (const name of ['light', 'dark']) { + const tag = name + '-' + w; + await size(w, hgt); await load(name, runA, 'trWith=' + runB + '&trSeries=loss,grad_norm'); + await drawnChart('loss', 2); await drawnChart('grad_norm', 2); + const r = await evaluate(`(() => { const a = document.getElementById('aside'), t = a.querySelector('.trn'); const cv = [...t.querySelectorAll('canvas.trn-chart')].map(c => (${PIXELS})(c).drawn); const wide = [...t.querySelectorAll('*')].filter(e => { const b = e.getBoundingClientRect(); return b.width > 0 && b.right > a.getBoundingClientRect().right + 1 && !e.closest('.trn-samples'); }).map(e => e.tagName + '.' + e.className).slice(0, 4); return { cv, page: document.documentElement.scrollWidth - innerWidth, aside: a.scrollWidth - a.clientWidth, wide }; })()`); + assert.ok(r.cv.every(n => n > 100), tag + ': no blank chart ' + JSON.stringify(r.cv)); + assert.ok(r.page <= 0 && r.aside <= 1 && !r.wide.length, tag + ': nothing overflows sideways ' + JSON.stringify(r)); + await shot(tag + '-6-training'); + seen6.push(tag); + } + await size(1440, 900); + check('6. Two charts of two runs drawn and nothing overflowing sideways: ' + seen6.join(', ') + (shots ? '; screenshots in ' + shots : '')); + + assert.deepEqual(errors, [], 'Script errors'); + assert.deepEqual(failures, [], 'Failed requests'); + check('No script error, no failed request'); + fs.writeFileSync(path.join(report, 'receipt.json'), JSON.stringify({ status: 'pass', folder, checks }, null, 2) + '\n'); + console.log('Receipt in ' + report); +})().catch(async error => { + process.exitCode = 1; + console.error(error); if (serverErrors) console.error('Server:', serverErrors.slice(-4000)); + console.error('Script errors:', JSON.stringify(errors)); console.error('Failed requests:', JSON.stringify(failures)); + try { if (evaluate) { await shot('failure'); console.error('Drawer:', (await evaluate('document.getElementById("aside").innerText')).slice(0, 2500)); } } catch (_) { /* the page is gone */ } + fs.writeFileSync(path.join(report, 'failure.json'), JSON.stringify({ status: 'failed', error: String(error && error.stack || error), checks, errors, failures }, null, 2) + '\n'); +}).finally(async () => { + try { session?.close(); } catch (_) { /* closed */ } + for (const child of children.reverse()) await stop(child); + if (owned) try { dropOwned(...owned); } catch (error) { console.error('Dropping the disposable schemas failed:', error.message); process.exitCode = 1; } + try { execFileSync('chmod', ['-R', 'u+w', temporary]); } catch (_) { /* nothing was made read-only */ } + fs.rmSync(temporary, { recursive: true, force: true }); +}); diff --git a/tests/project_training_stand_in.py b/tests/project_training_stand_in.py new file mode 100644 index 00000000..442668ed --- /dev/null +++ b/tests/project_training_stand_in.py @@ -0,0 +1,104 @@ +"""A stand-in training script for tests/browser_project_workspace_training.cjs: it trains nothing real. + +A linear model of sixteen weights and a bias is fitted by gradient descent, in +plain Python on the CPU, to numbers it draws itself, and everything is logged +through tuldok_log as a project's script would: every step the loss, the +learning rate (a cosine schedule) and the gradient norm; every ten steps a +validation loss; every five steps the histograms of the weights and their +gradients (the model offers named_parameters, each parameter a list with a +grad); every ten steps two samples, the prediction over an 8 x 8 grid as an +.npy and as a small PNG. A tuldok_progress_v1 line is printed each step, and +--sleep slows it so that a run lasts a few seconds. At the end weights.json is +written, the recipe's declared output. + + python project_training_stand_in.py --out [--steps 60] [--lr 0.05] [--sleep 0] [--seed 1] +""" +import argparse +import json +import math +import os +import random +import struct +import sys +import time +import zlib + +from tuldok_log import Logger + + +class Parameter(list): + grad = None + + +def png(rows): + """A greyscale PNG of rows of values in 0..1.""" + height, width = len(rows), len(rows[0]) + raw = b''.join(b'\x00' + bytes(max(0, min(255, int(v * 255))) for v in row) for row in rows) + + def chunk(kind, data): + return struct.pack('>I', len(data)) + kind + data + struct.pack('>I', zlib.crc32(kind + data)) + return (b'\x89PNG\r\n\x1a\n' + chunk(b'IHDR', struct.pack('>IIBBBBB', width, height, 8, 0, 0, 0, 0)) + + chunk(b'IDAT', zlib.compress(raw)) + chunk(b'IEND', b'')) + + +def main(): + parser = argparse.ArgumentParser() + parser.add_argument('--out', required=True) + parser.add_argument('--steps', type=int, default=60) + parser.add_argument('--lr', type=float, default=0.05) + parser.add_argument('--sleep', type=float, default=0.0) + parser.add_argument('--seed', type=int, default=1) + options = parser.parse_args() + rng = random.Random(options.seed) + size = 16 + truth = [rng.gauss(0, 1) for _ in range(size)] + inputs = [[rng.gauss(0, 1) for _ in range(size)] for _ in range(64)] + targets = [sum(a * b for a, b in zip(x, truth)) + 0.5 for x in inputs] + held_inputs = [[rng.gauss(0, 1) for _ in range(size)] for _ in range(16)] + held_targets = [sum(a * b for a, b in zip(x, truth)) + 0.5 for x in held_inputs] + weight = Parameter(rng.gauss(0, 0.1) for _ in range(size)) + bias = Parameter([0.0]) + + class Model: + @staticmethod + def named_parameters(): + return [('linear.weight', weight), ('linear.bias', bias)] + + def predict(x): + return sum(a * b for a, b in zip(x, weight)) + bias[0] + + log = Logger(options.out) + for step in range(1, options.steps + 1): + rate = options.lr * 0.5 * (1 + math.cos(math.pi * (step - 1) / options.steps)) + errors = [predict(x) - y for x, y in zip(inputs, targets)] + loss = sum(e * e for e in errors) / len(errors) + weight.grad = Parameter(2 * sum(e * x[i] for e, x in zip(errors, inputs)) / len(errors) for i in range(size)) + bias.grad = Parameter([2 * sum(errors) / len(errors)]) + norm = math.sqrt(sum(g * g for g in weight.grad) + bias.grad[0] ** 2) + scalars = {'loss': loss, 'lr': rate, 'grad_norm': norm} + if step % 10 == 0: + scalars['val/loss'] = sum((predict(x) - y) ** 2 for x, y in zip(held_inputs, held_targets)) / 16 + log.log(step, epoch=step // 20, **scalars) + if step % 5 == 0 or step == 1: + log.log_histograms(step, Model(), bins=24) + for i in range(size): + weight[i] -= rate * weight.grad[i] + bias[0] -= rate * bias.grad[0] + if step % 10 == 0: + grid = [[predict([math.sin(r + c * k / 3) for k in range(size)]) for c in range(8)] for r in range(8)] + log.log_sample(step, 'field', grid) + low = min(min(row) for row in grid) + high = max(max(row) for row in grid) + log.log_sample(step, 'prediction', png([[(v - low) / ((high - low) or 1) for v in row] for row in grid])) + print(json.dumps({'format': 'tuldok_progress_v1', 'stage': 'fit', 'completed': step, 'total': options.steps, + 'metrics': {'loss': loss}}), flush=True) + if options.sleep: + time.sleep(options.sleep) + log.close() + with open(os.path.join(options.out, 'weights.json'), 'w') as handle: + json.dump({'weight': list(weight), 'bias': bias[0]}, handle) + return 0 + + +if __name__ == '__main__': + sys.exit(main()) From 25101b90b47455b8bd99ac1581b1d6fe9cab3451 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 19 Nov 2026 05:50:12 -0700 Subject: [PATCH 093/131] feat(workspace): the Structure block draws a model's graph beside its Weights A left-to-right SVG drawing (longest-path ranks, barycentre order), modules folded into groups that open and close in place, an operation's tensors linked to the Weights block (LabWeights.reveal), colours from model_graph_overlay, the derived or parent model's graph drawn below with the modules model_graph_compare finds changed, added or missing. A run with no graph is answered path null rather than refused. The browser check and its fixture; spec-t2's As built. Co-Authored-By: Claude Opus 5.5 --- app.py | 1 + docs/contracts/project-folder.md | 6 +- docs/plans/training-and-curation/spec-t2.md | 28 ++ static/project-workspace.html | 1 + static/project-workspace/adapter.js | 5 + static/project-workspace/base.css | 53 +++ static/project-workspace/screens.js | 5 + static/project-workspace/structure.js | 346 ++++++++++++++++++ static/project-workspace/weights.js | 20 +- tests/browser_project_workspace_structure.cjs | 343 +++++++++++++++++ tests/project_structure_browser_fixture.py | 105 ++++++ tests/test_tuldok_project_model_graph.py | 9 +- tests/test_tuldok_project_service.py | 4 +- tuldok_project/inside_graph.py | 16 + 14 files changed, 936 insertions(+), 6 deletions(-) create mode 100644 static/project-workspace/structure.js create mode 100644 tests/browser_project_workspace_structure.cjs create mode 100644 tests/project_structure_browser_fixture.py diff --git a/app.py b/app.py index 9e1f64e2..e2ed01cf 100644 --- a/app.py +++ b/app.py @@ -807,6 +807,7 @@ def _get(self): '/project-workspace/tabs.js': ('project-workspace/tabs.js', 'text/javascript'), '/project-workspace/inside.js': ('project-workspace/inside.js', 'text/javascript'), '/project-workspace/weights.js': ('project-workspace/weights.js', 'text/javascript'), + '/project-workspace/structure.js': ('project-workspace/structure.js', 'text/javascript'), '/project-workspace/fields.js': ('project-workspace/fields.js', 'text/javascript'), '/project-workspace/annotate.js': ('project-workspace/annotate.js', 'text/javascript'), '/project-workspace/generate.js': ('project-workspace/generate.js', 'text/javascript'), diff --git a/docs/contracts/project-folder.md b/docs/contracts/project-folder.md index e12fd409..7e4ab8ec 100644 --- a/docs/contracts/project-folder.md +++ b/docs/contracts/project-folder.md @@ -2788,7 +2788,11 @@ same two shown nodes are one, with `count`; an edge inside a group is dropped; each carries the `shape` and `dtype` of the first value it carries. The answer also gives the file's `path`, `complete`, `reason`, `method`, `torch`, `model`, `inputs`, `notes`, `counts`, the `modules` tree, the -`tensors`, the `depth` used and `open` (the modules open in effect). +`tensors`, the `depth` used and `open` (the modules open in effect). A run +with no graph file is not refused: `path` is null, `modules` null and the +rest empty (as `fields` answers `kept` false), so a page can ask every +model's product. `model_graph_overlay` and `model_graph_compare` refuse such +a run `not-found`. **`model_graph_overlay`** takes `kind`: `parameters` (a module's from the tree; an operation's, the sizes of its tensors that are parameters), diff --git a/docs/plans/training-and-curation/spec-t2.md b/docs/plans/training-and-curation/spec-t2.md index 31e32b97..7707bab8 100644 --- a/docs/plans/training-and-curation/spec-t2.md +++ b/docs/plans/training-and-curation/spec-t2.md @@ -105,3 +105,31 @@ In a model's drawer, a block **Structure** right after Weights, when one of the ## 7. Out of scope Running the model, activations, profiling time per operation (a later field `seconds` on a node; nothing writes it yet), ONNX or TorchScript files, graphs of frameworks other than PyTorch, editing a model's structure, drawing more than two graphs at once. + +## As built + +What differs from the text above, and what was found. Built on `feat/t2-model-graph` beside phase 1, which owns `tuldok_log/__init__.py`; this branch holds a one-line `tuldok_log/__init__.py` (a docstring) only so that `tuldok_log.graph` imports, and the merge takes phase 1's. + +### T2a, the file, the helper, the reader and the operations + +- **A run with no graph is not refused by `model_graph`.** Section 3 says "none is refused `not-found`". As first built it was, and the page, which asks `model_graph` for each current product of every model whose drawer opens, then drew a failed request (a 404, which the browser logs as an error) for every model without a graph; the weights check, which fails on any such error, would have failed. `model_graph` now answers `path` null, `modules` null and the rest empty, as `fields` answers `kept` false (spec-d6). `model_graph_overlay` and `model_graph_compare` still refuse it `not-found`; the page asks them only of a run that has a graph. +- **The arguments are named `open` and `close`** in the operation; the reader's keywords are `opened` and `closed`. +- **The node bound past 20,000 in the helper** is checked while the graph is walked: past it, the module tree alone is written with the reason, as section 2 says; the edge bound (100,000) the same way after the walk. A node past 64 tensors keeps the first 64 with a note. +- **Tensors.** The helper lists `state_dict` (parameters and persistent buffers, with `kind`) and adds non-persistent buffers as `buffer`. Lifted constants (`CONSTANT_TENSOR` in an exported graph) are read by name like parameters but are not in `tensors` unless the `state_dict` holds them; a node's `tensors` may then name one the reader does not know, which it accepts (it counts no parameters for it). +- **Module paths** in `nn_module_stack` are taken in the dotted form of `named_modules`; a path the tree does not list is walked up to its nearest listed parent, by the helper and by the reader alike. PyTorch 2.8 already gives dotted paths; the other spellings (`L['self'].blocks[0]`) are handled but were not met. +- **`tuldok_log` writes through a file beside the target** (`.model-graph.json...tmp`, opened exclusively so the umask applies) renamed into place; `tempfile.mkstemp` was tried first and left the file readable by its owner only. +- **The reader's group `outputs`** are the values of the first edge from the group to each shown node it feeds, at most 16; `inputs` every crossing edge's value, at most 16. +- **Tests.** `tests/test_tuldok_project_model_graph.py`, 20 (one with the database). `tests/test_tuldok_log_graph.py`, 5, run with the lab's PyTorch 2.8.0+cpu on the CPU (`PYTHONPATH=.:tests -m unittest test_tuldok_log_graph`); in Tuldok's environment, which has no PyTorch, they are skipped (5 skipped). The service test's count of the table's rows went from 61 to 64. The catalog profile's digest is unchanged. + +### T2b, the Structure block + +- **The two drawings are one above the other**, not side by side: the drawer is at most 420 px wide. Modules are matched by path by `model_graph_compare`; the other drawing is folded with the same depth, `open` and `close`. A node's mark is its module's status; a group whose own module is the same but holds a module that differs is marked "something inside it differs" (`inside`). A module only in the other model is marked in the other drawing. +- **A group pressed opens** (rather than selecting it): its parents are opened with it, past the depth when needed. An operation pressed shows its details; "Fold " in the details, and every row of the outline, close a module again. Inputs and outputs show their details too. +- **"Fit to width"** (not in section 4) shrinks the drawings to the drawer's width for an overview, never larger than their own size; pressed again, their actual size in the scrolling box. Added because the fixture's chain of 18 nodes shows two or three at a time in the drawer; even fitted, a long chain is a thin strip (doubt: a top-to-bottom layout might suit the narrow drawer better; section 4 asks for left to right). +- **The colours.** The fills are `color-mix` of the tokens `--ramp-lo` and `--ramp-hi` in CSS, so a theme change recolours them with no script; a node past 55 % of the scale writes its labels in `--surface`. Counts (parameters, output size, operations) are on a logarithmic scale from zero, the change linear from its lowest. "Operations" is offered as a colour too (section 4 names parameters, output size and the two changes). +- **"Change from the weights it started from"** is offered whether or not the run kept an `initial-` file; without one, choosing it shows the server's refusal in the block. "Change from the model it derives from" compares with the first current product of the parent. +- **`weights.js` gained `reveal(model, array)`:** it opens the tensor's layer with that tensor in the Weights block (the same rebuild in place as a person's click), scrolls the layer's row to the top of the drawer's view and focuses its button. +- **Files beyond section 5's list:** `tests/project_structure_browser_fixture.py` (the weights, standard library) and `tests/project_structure_fixture_export.py` (writes the committed graphs `tests/fixtures/model_graph/parent.json` and `derived.json`; run once with the lab's PyTorch). +- **Found at 390 px:** the page's own header (tabs and session bar), strip, stage and map are wider than the window on every tab before this block draws (the page is 553 to 554 px wider than 390). The check asserts that the drawer does not pass its stage and that nothing in the drawer overflows, and records the page's overflow; it does not assert the page's, which is not this phase's. The drawer itself sits 9 px past the window because the stage does. +- **Runs** (a disposable PostgreSQL, no GPU): project suite 755 OK (735 before this phase, and the 20 of `test_tuldok_project_model_graph.py`); agent interface 43 OK (4 skipped); `test_tuldok_log_graph.py` 5 OK with the lab's PyTorch, 5 skipped without it; `browser_project_workspace_structure.cjs` 8 PASS, and unchanged `_weights` (7 PASS) and `browser_project_workspace.cjs` (24 PASS). +- **Not verified:** a graph near the bounds (20,000 nodes: the reader's time and the page's drawing of thousands of SVG nodes; folding to depth 1 by default past 200 operations is untested in the page); a graph written by `torch.fx` drawn in the page (tested in the helper only); a module-tree-only file in the page (tested in the reader only); a model with several products of which more than one holds a graph (the first is drawn); the overlay's and comparison's refusals shown in the block; a theme changed while the drawer is open (the check loads each theme); Tab order and the focus ring of the SVG nodes, by eye in the screenshots only; the lab's own models (none has a `model-graph.json` yet; nothing was exported from the lab's code). diff --git a/static/project-workspace.html b/static/project-workspace.html index ccf47a7a..bec8ec33 100644 --- a/static/project-workspace.html +++ b/static/project-workspace.html @@ -18,6 +18,7 @@ + diff --git a/static/project-workspace/adapter.js b/static/project-workspace/adapter.js index 9f43a2f3..6e3720a7 100644 --- a/static/project-workspace/adapter.js +++ b/static/project-workspace/adapter.js @@ -126,6 +126,11 @@ window.TuldokProject = (() => { // and signed error with the error's figures (asked for each time the person moves through it unless kept). fields: run => read('fields', { run }), fieldCompare: (run, { entry, case: one, axis, index, mean_free }, fresh = false) => (fresh ? call : read)('field_compare', defined({ run, entry, case: one, axis, index, mean_free })), + // A model's structure (spec-t2.md, structure.js): its graph folded by the person's choices, a number per module + // and operation, and the matching of two graphs' modules. Kept like the rest until a reading finds a change. + graph: (run, { depth, open, close } = {}) => read('model_graph', defined({ run, depth, open: open && open.length ? open : null, close: close && close.length ? close : null })), + graphOverlay: (run, { kind, against, other_run, path, other_path }) => read('model_graph_overlay', defined({ run, kind, against, other_run, path, other_path })), + graphCompare: (run, otherRun) => read('model_graph_compare', { run, other_run: otherRun }), /** The address of an image's or a sound's bytes (GET /api/project/file), as the record operation gives it. */ fileUrl: (run, path) => '/api/project/file?run=' + encodeURIComponent(run) + '&path=' + encodeURIComponent(path) }; diff --git a/static/project-workspace/base.css b/static/project-workspace/base.css index fec0260d..34979886 100644 --- a/static/project-workspace/base.css +++ b/static/project-workspace/base.css @@ -746,6 +746,59 @@ tr.wts-row:has(+ tr.wts-open) > td { background: var(--accent-wash); } .wts-pager { margin: 0; flex-wrap: wrap; } .wts-reason { margin: 0; } +/* ---- A model's structure (structure.js, docs/plans/training-and-curation/spec-t2.md section 4). ---- */ +.st { display: grid; gap: 10px; min-width: 0; } +.st > h3 { margin-bottom: 0; } +.st p { margin: 0; } +.st-size, .st-how, .st-reason { overflow-wrap: anywhere; } +.st-bar { display: flex; flex-wrap: wrap; gap: 8px 12px; align-items: end; min-width: 0; } +.st-pick { display: grid; gap: 4px; font-size: 12.5px; color: var(--ink-2); min-width: 0; max-width: 100%; } +.st-pick select { max-width: 100%; min-width: 0; } +.st-folds { display: flex; flex-wrap: wrap; gap: 6px; } +.st-draw { min-width: 0; } +.st-scroll { overflow: auto; max-height: 380px; border: 1px solid var(--line); border-radius: var(--radius); background: var(--surface-2); } +.st-scroll svg { display: block; font-family: var(--font); } +.st-scroll.fit svg { height: auto; } +.st-edge { fill: none; stroke: var(--line-strong); stroke-width: 1.3; } +.st-edge.back { stroke-dasharray: 3 3; } +.st-arrowhead { fill: var(--line-strong); } +.st-node { cursor: pointer; } +.st-node:focus { outline: none; } +.st-node .st-box { fill: var(--surface); stroke: var(--line-strong); stroke-width: 1; } +.st-node.group .st-box { stroke: var(--ink-3); } +.st-node .st-inner { fill: none; stroke: var(--line-strong); stroke-dasharray: 2 2; } +.st-node.input .st-box, .st-node.output .st-box { fill: var(--accent-wash); stroke: var(--accent); } +.st-node .st-label { font-size: 12px; font-weight: 600; fill: var(--ink); } +.st-node .st-subl { font-size: 11px; fill: var(--ink-2); font-variant-numeric: tabular-nums; } +.st-node.deep .st-label, .st-node.deep .st-subl { fill: var(--surface); } +.st-node:hover .st-box { stroke: var(--accent); } +.st-node:focus-visible .st-box, .st-node.selected .st-box { stroke: var(--accent); stroke-width: 2.5; } +.st-node.mark-added .st-box, .st-node.mark-changed .st-box, .st-node.mark-inside .st-box { stroke: var(--warn); stroke-width: 2; stroke-dasharray: 5 3; } +.st-node.mark-added .st-box { stroke-dasharray: none; } +.st-badge { fill: var(--warn); } +.st-legend { display: grid; gap: 4px; } +.st-ramp { display: block; height: 10px; border-radius: 3px; background: linear-gradient(to right, var(--ramp-lo), var(--ramp-hi)); } +.st-detail { display: grid; gap: 8px; min-width: 0; padding: 10px; border: 1px solid var(--line); border-radius: var(--radius); background: var(--surface); } +.st-dtitle { overflow-wrap: anywhere; } +.st-facts { font-size: 12.5px; } +.st-facts dd { overflow-wrap: anywhere; } +.st-tensors { list-style: none; margin: 0; padding: 0; display: grid; gap: 4px; font-size: 12.5px; } +.st-tensors li { overflow-wrap: anywhere; } +.st .linkish { font: inherit; color: var(--accent); background: none; border: 0; padding: 0; cursor: pointer; text-align: left; text-decoration: underline; text-underline-offset: 2px; overflow-wrap: anywhere; } +.st-detail .btn { justify-self: start; } +.st-sub { font-size: 13px; color: var(--ink-2); font-weight: 600; margin: 4px 0 0; overflow-wrap: anywhere; } +.st-difflist { list-style: none; margin: 4px 0 0; padding: 0; display: grid; gap: 3px; font-size: 12.5px; } +.st-difflist li { overflow-wrap: anywhere; padding-left: 8px; border-left: 3px solid var(--warn); } +.st-difflist li.st-d-missing { border-left-color: var(--line-strong); } +.st-outline { min-width: 0; } +.st-tree { list-style: none; margin: 0; padding: 0 0 0 12px; } +.st-outline > .st-tree { padding-left: 0; } +.st-row { display: flex; flex-wrap: wrap; gap: 2px 8px; align-items: baseline; min-width: 0; padding: 1px 0; } +.st-toggle { display: inline-flex; gap: 4px; align-items: baseline; font: inherit; font-size: 12.5px; color: var(--ink); background: none; border: 0; padding: 2px 0; cursor: pointer; min-width: 0; overflow-wrap: anywhere; text-align: left; } +.st-toggle:hover { color: var(--accent); } +.st-caret { color: var(--ink-3); width: 10px; flex: none; } +.st-m-missing { border-color: var(--line-strong); color: var(--ink-2); background: var(--surface-2); } + /* ---- Annotating (annotate.js, spec-d4.md section 7); from the mockup's Annotate tab. ---- */ .annotate { container-type: inline-size; min-width: 0; } .ann-bar { display: flex; flex-wrap: wrap; gap: 8px 14px; align-items: center; margin-bottom: 14px; } diff --git a/static/project-workspace/screens.js b/static/project-workspace/screens.js index 05b1967d..fa6188f1 100644 --- a/static/project-workspace/screens.js +++ b/static/project-workspace/screens.js @@ -203,6 +203,11 @@ window.LabScreens = (() => { const wts = h('div', 'wts-box'); wts.hidden = true; ins.insertBefore(wts, uses2); reads.push(window.LabWeights.block(wts, m, g, aside.parentElement, live).catch(error => { if (!live()) return; wts.hidden = false; wts.replaceChildren(h('h3', null, 'Weights'), A.refusal(error)); })); } + // Structure (structure.js, spec-t2 section 4), after Weights: shown only when a current product holds model-graph.json. + if (window.LabStructure) { + const stb = h('div', 'st-box'); stb.hidden = true; ins.insertBefore(stb, uses2); + reads.push(window.LabStructure.block(stb, m, g, aside.parentElement, live).catch(error => { if (!live()) return; stb.hidden = false; stb.replaceChildren(h('h3', null, 'Structure'), A.refusal(error)); })); + } if (more) more(ins); if (!same) aside.appendChild(ins); // first shown: at once, its blocks filled as they come const fill = (b, build) => p => { if (!live()) return; b.lastChild.remove(); try { build(b, p); } catch (error) { failure(b, error); } }; diff --git a/static/project-workspace/structure.js b/static/project-workspace/structure.js new file mode 100644 index 00000000..d04aa1af --- /dev/null +++ b/static/project-workspace/structure.js @@ -0,0 +1,346 @@ +'use strict'; +// A model's structure (docs/plans/training-and-curation/spec-t2.md section 4): the block "Structure" of a model's +// drawer, right after Weights, when one of the model's current products holds model-graph.json. The graph the +// project's script recorded is drawn left to right in SVG (ranks by the longest path from the inputs, each rank +// ordered by the barycentre of its neighbours), its modules folded into groups that open when pressed and close +// from the module outline under the drawing. An operation pressed shows its details, whose tensors open in the +// Weights block (LabWeights.reveal). "Colour by" fills the nodes from model_graph_overlay; "Compare with" draws +// the graph of the model it derives from, or of one derived from it, under this one, folded the same way, and +// marks the modules model_graph_compare finds added, missing or changed. +// +// Updating in place (spec-w4): the block is built off the page and put in place whole, like weights.js's. Read +// again for the model on screen (screens.js), it is built from the person's place in it (folding, selection, +// colour, comparison) and resolves only once complete; the person's own choices draw it again the same way, the +// focus kept by data-key and the drawing's scroll by putInPlace. +window.LabStructure = (() => { + const P = window.TuldokProject, S = window.LabScreens, C = window.LabCharts, h = C.h, R = P.product; + const { putInPlace } = S.parts; + const SVG = 'http://www.w3.org/2000/svg'; + const W = 132, H = 42, GAP = 40, VGAP = 14, PAD = 10, SWEEPS = 4, LABEL = 18; + const num = n => n == null ? '—' : n.toLocaleString('en-GB'); + const plural = (n, one, many) => num(n) + ' ' + (n === 1 ? one : many || one + 's'); + const shapeText = s => !s ? '' : s.length ? s.join('×') : 'scalar'; + const valuesText = list => (list || []).map(v => shapeText(v.shape) + ' ' + v.dtype).join(', ') || '—'; + const short = text => text.length > LABEL ? text.slice(0, LABEL - 1) + '…' : text; + const classShort = c => c ? c.split('.').pop() : ''; + const button = (cls, text, onClick) => { const b = h('button', cls, text); b.type = 'button'; if (onClick) b.addEventListener('click', onClick); return b; }; + const refusal = error => window.LabActions.refusal(error); + const svg = (tag, attrs) => { const e = document.createElementNS(SVG, tag); for (const [k, v] of Object.entries(attrs || {})) e.setAttribute(k, v); return e; }; + const COLOURS = [['', 'Nothing'], ['parameters', 'Parameters'], ['outputs', 'Output size'], ['operations', 'Operations'], ['change:start', 'Change from the weights it started from'], ['change:parent', 'Change from the model it derives from']]; + let drawings = 0; // a number per drawing, for the ids of its arrow markers + + // ---- The person's place in each model's block ------------------------------------------------------------------- + const places = new Map(); + const placeOf = id => { if (!places.has(id)) places.set(id, { depth: null, open: [], close: [], selected: null, colour: '', compare: '', fit: false }); return places.get(id); }; + const foldArgs = (st, depth) => st.depth == null && !st.open.length && !st.close.length && depth == null ? {} : { depth: st.depth == null ? depth : st.depth, open: st.open.slice().sort(), close: st.close.slice().sort() }; + + // ---- Reading ---------------------------------------------------------------------------------------------------------- + /** The first current product of a model that holds a graph: { run, subject, graph } (its graph folded the default way), or null. */ + async function graphRun(reference) { + const products = (await P.read('products', { reference })).products.filter(p => p.run_id); + for (const p of products) { + const graph = await R.graph(p.run_id, {}); + if (graph.path) return { run: p.run_id, subject: p.subject || '', graph }; // path null: no graph in this product + } + return null; + } + + /** + * Fills box (a block of the drawer of model m, on the page or not yet) with the Structure block, or hides it + * when no product of the model holds a graph. Resolves once the block is complete. + */ + async function block(box, m, g, scroller, live) { + const st = placeOf(m.id), ctx = { box, m, g, st, scroller, live, turn: 0 }; + let root; + try { root = await build(ctx); } catch (error) { root = h('div', 'st'); root.appendChild(h('h3', null, 'Structure')); root.appendChild(refusal(error)); } + if (!live()) return; + st.ctx = ctx; + if (!root) { box.hidden = true; box.replaceChildren(); return; } + box.hidden = false; box.replaceChildren(root); + } + async function again(ctx) { + const mine = ++ctx.turn; + ctx.box.setAttribute('aria-busy', 'true'); + let root; try { root = await build(ctx); } catch (error) { root = h('div', 'st'); root.appendChild(h('h3', null, 'Structure')); root.appendChild(refusal(error)); } + if (mine !== ctx.turn || !ctx.box.isConnected) return; + ctx.box.removeAttribute('aria-busy'); + putInPlace(ctx.box, root || h('div'), ctx.scroller); + } + + /** The other models it can be compared with: the model it derives from and those derived from it, with a graph. */ + async function choicesFor(m, g) { + const refs = [m.parent].filter(p => p && g.byId.has(p)).map(p => ['parent', p]).concat(g.nodes.filter(n => n.parent === m.id).map(n => ['child', n.id])); + const out = []; + for (const [rel, ref] of refs) { + const got = await graphRun(ref).catch(() => null), o = g.byId.get(ref); + if (got) out.push({ key: ref, run: got.run, label: (rel === 'parent' ? 'The model it derives from: ' : 'Derived from it: ') + (o.short ? o.short + ' · ' : '') + o.title }); + } + return out; + } + + async function build(ctx) { + const { m, g, st } = ctx; + const found = await graphRun(m.id); + if (!found) return null; + const { run } = found; + const args = foldArgs(st, null); + const graph = Object.keys(args).length ? await R.graph(run, args) : found.graph; + const root = h('div', 'st'); + root.appendChild(h('h3', null, 'Structure')); + const c = graph.counts; + root.appendChild(h('p', 'small muted st-size', [graph.path + (found.subject ? ' · ' + found.subject : ''), plural(c.operations, 'operation'), plural(c.modules, 'module'), plural(c.tensors, 'tensor')].join(' · '))); + root.appendChild(h('p', 'small faint st-how', 'Recorded by ' + (graph.method || 'the project') + (graph.torch ? ' with PyTorch ' + graph.torch : '') + (graph.inputs.length ? '; example input ' + graph.inputs.map(v => v.name + ' ' + shapeText(v.shape)).join(', ') : '') + '.')); + for (const note of graph.notes) root.appendChild(h('p', 'small warnline', note)); + if (!graph.complete) { + root.appendChild(h('p', 'empty st-reason', 'Only the module tree was recorded: ' + (graph.reason || 'no reason given') + '.')); + root.appendChild(outline(ctx, graph, null)); + return root; + } + // The controls: colour, comparison, folding. + const colourChoices = COLOURS.filter(([k]) => k !== 'change:parent' || m.parent); + if (!colourChoices.some(([k]) => k === st.colour)) st.colour = ''; + const compareChoices = await choicesFor(m, g); + if (!compareChoices.some(x => x.key === st.compare)) st.compare = ''; + const bar = h('div', 'st-bar'); + const sel = (label, key, options, value, onChange) => { + const s = h('select'); s.setAttribute('aria-label', label); s.dataset.key = key; + for (const [v, t] of options) { const o = h('option', null, t); o.value = v; o.selected = v === value; s.appendChild(o); } + s.addEventListener('change', () => onChange(s.value)); + const l = h('label', 'iv-field st-pick'); l.appendChild(document.createTextNode(label)); l.appendChild(s); return l; + }; + bar.appendChild(sel('Colour by', 'st-colour', colourChoices, st.colour, v => { st.colour = v; again(ctx); })); + if (compareChoices.length) bar.appendChild(sel('Compare with', 'st-compare', [['', 'Nothing']].concat(compareChoices.map(x => [x.key, x.label])), st.compare, v => { st.compare = v; again(ctx); })); + const folds = h('div', 'st-folds'); + const all = button('btn sm', 'Open all', () => { Object.assign(st, { depth: 64, open: [], close: [] }); again(ctx); }); all.dataset.key = 'st-open-all'; + const one = button('btn sm', 'Fold to depth 1', () => { Object.assign(st, { depth: 1, open: [], close: [] }); again(ctx); }); one.dataset.key = 'st-fold-1'; + const fit = button('btn sm', 'Fit to width', () => { st.fit = !st.fit; again(ctx); }); fit.dataset.key = 'st-fit'; fit.setAttribute('aria-pressed', String(st.fit)); + fit.title = 'Shrink the drawings to the drawer\'s width, for an overview; press again for their actual size'; + folds.appendChild(all); folds.appendChild(one); folds.appendChild(fit); bar.appendChild(folds); + root.appendChild(bar); + // The overlay and the comparison, read in full before anything is drawn. + let overlay = null, overlayError = null; + if (st.colour) { + const [kind, against] = st.colour.split(':'); + const oargs = { kind }; + if (against === 'start') oargs.against = 'start'; + if (against === 'parent') { const p = (await P.read('products', { reference: m.parent })).products.find(x => x.run_id); oargs.against = 'run'; oargs.other_run = p ? p.run_id : null; } + try { overlay = await R.graphOverlay(run, oargs); } catch (error) { overlayError = error; } + } + const choice = compareChoices.find(x => x.key === st.compare) || null; + let other = null, cmp = null, cmpError = null; + if (choice) { + try { [other, cmp] = await Promise.all([R.graph(choice.run, { depth: graph.depth, open: st.open.slice().sort(), close: st.close.slice().sort() }), R.graphCompare(run, choice.run)]); } + catch (error) { cmpError = error; } + } + if (overlayError) root.appendChild(refusal(overlayError)); + if (cmpError) root.appendChild(refusal(cmpError)); + const status = cmp ? statuses(cmp, false) : null; + root.appendChild(drawing(ctx, graph, overlay, status, 'This model', true)); + if (overlay) root.appendChild(legend(overlay)); + const chosen = graph.nodes.find(n => n.id === st.selected); + if (chosen) root.appendChild(details(ctx, graph, chosen, overlay, status)); + if (other) { + const head = h('h4', 'st-sub', (g.byId.get(choice.key).short ? g.byId.get(choice.key).short + ' · ' : '') + g.byId.get(choice.key).title); + root.appendChild(head); + root.appendChild(drawing(ctx, other, null, statuses(cmp, true), 'The other model', false)); + root.appendChild(differences(cmp)); + } + root.appendChild(outline(ctx, graph, status)); + return root; + } + + // ---- The comparison -------------------------------------------------------------------------------------------------- + /** {path: status} from a model_graph_compare answer, seen from this graph or (mirrored) from the other's. */ + function statuses(cmp, mirrored) { + const out = new Map(); + for (const r of cmp.modules) out.set(r.path, mirrored ? ({ added: 'missing', missing: 'added' }[r.status] || r.status) : r.status); + return out; + } + /** A node's mark: its module's status; a group's, or "inside" when a module within it differs. */ + function markOf(node, status) { + if (!status || node.kind === 'input' || node.kind === 'output') return null; + const own = status.get(node.module); + if (own && own !== 'same' && own !== 'missing') return own; + if (node.kind === 'group') for (const [path, s] of status) if (s !== 'same' && s !== 'missing' && path.startsWith(node.module + '.')) return 'inside'; + return null; + } + const MARK_WORD = { added: 'only in this model', missing: 'only in the other model', changed: 'changed', inside: 'something inside it differs' }; + function differences(cmp) { + const box = h('div', 'st-diff'); const rows = cmp.modules.filter(r => r.status !== 'same'); + box.appendChild(h('p', 'small muted', rows.length ? 'Modules matched by path: ' + ['changed', 'added', 'missing'].map(k => cmp.counts[k] + ' ' + { changed: 'changed', added: 'only here', missing: 'only in the other' }[k]).join(', ') + '.' : 'Every module matches by path, class and tensor shapes.')); + if (!rows.length) return box; + const ul = h('ul', 'st-difflist'); + for (const r of rows) { + const li = h('li', 'st-d-' + r.status); li.dataset.path = r.path; li.dataset.status = r.status; + li.appendChild(h('span', 'mono', r.path || '(the model)')); + const why = r.status === 'added' ? 'only in this model' : r.status === 'missing' ? 'only in the other' : [r.class !== r.other_class ? classShort(r.other_class) + ' → ' + classShort(r.class) : null].concat(r.reshaped.map(x => x.name.split('.').pop() + ' ' + shapeText(x.other_shape) + ' → ' + shapeText(x.shape)), r.only_here.map(n => n.split('.').pop() + ' added'), r.only_there.map(n => n.split('.').pop() + ' removed')).filter(Boolean).join('; '); + li.appendChild(h('span', 'small muted', ' ' + why)); ul.appendChild(li); + } + box.appendChild(ul); return box; + } + + // ---- The layout ---------------------------------------------------------------------------------------------------------- + /** Positions of the shown nodes: ranks by the longest path from the inputs, each rank ordered by barycentre. */ + function layout(nodes, edges) { + const at = new Map(nodes.map((n, i) => [n.id, i])), rank = new Array(nodes.length).fill(0); + const into = nodes.map(() => []), out = nodes.map(() => []), forward = []; + for (const e of edges) { const a = at.get(e.from), b = at.get(e.to); if (a == null || b == null) continue; if (a < b) { into[b].push(a); out[a].push(b); forward.push(e); } } + for (let i = 0; i < nodes.length; i++) for (const a of into[i]) rank[i] = Math.max(rank[i], rank[a] + 1); + const ranks = []; for (let i = 0; i < nodes.length; i++) (ranks[rank[i]] = ranks[rank[i]] || []).push(i); + const pos = new Array(nodes.length).fill(0); + const place = () => { for (const r of ranks) r.forEach((i, k) => { pos[i] = k; }); }; + place(); + const bary = (i, side) => { const n = side[i]; return n.length ? n.reduce((s, j) => s + pos[j], 0) / n.length : pos[i]; }; + for (let sweep = 0; sweep < SWEEPS; sweep++) { + const down = sweep % 2 === 0, order = down ? ranks.slice(1) : ranks.slice(0, -1).reverse(); + for (const r of order) { const b = new Map(r.map(i => [i, bary(i, down ? into : out)])); r.sort((x, y) => b.get(x) - b.get(y) || x - y); r.forEach((i, k) => { pos[i] = k; }); } + } + const most = Math.max(1, ...ranks.map(r => r.length)); + const xy = nodes.map((_, i) => { const r = ranks[rank[i]]; return { x: PAD + rank[i] * (W + GAP), y: PAD + (pos[i] + (most - r.length) / 2) * (H + VGAP) }; }); + return { xy, at, width: PAD * 2 + ranks.length * W + (ranks.length - 1) * GAP, height: PAD * 2 + most * H + (most - 1) * VGAP + 18, rank }; + } + + // ---- The drawing ------------------------------------------------------------------------------------------------------ + /** The value of a node in an overlay: a group's module's, an operation's own. */ + const valueOf = (node, overlay) => !overlay ? null : node.kind === 'group' ? overlay.modules[node.module] : node.kind === 'operation' ? overlay.nodes[node.id] : null; + const LOG = { parameters: true, outputs: true, operations: true }; + /** 0..1 of a value on the overlay's scale (logarithmic for counts). */ + function scaled(v, overlay) { + if (v == null || !Number.isFinite(v)) return null; + const f = LOG[overlay.kind] ? x => Math.log10(1 + Math.max(0, x)) : x => x; + const lo = Math.min(f(0), f(overlay.low == null ? 0 : overlay.low)), hi = f(overlay.high == null ? 0 : overlay.high); + return hi > lo ? Math.min(1, Math.max(0, (f(v) - lo) / (hi - lo))) : 0; + } + const fmtValue = (v, overlay) => v == null ? 'no value' : overlay.kind === 'change' ? C.fmtSci(v) : num(v) + ' ' + overlay.unit; + + function drawing(ctx, graph, overlay, status, title, mine) { + const { st } = ctx, id = ++drawings, lay = layout(graph.nodes, graph.edges); + const box = h('div', 'st-draw'); box.dataset.which = mine ? 'this' : 'other'; + const s = svg('svg', { width: lay.width, height: lay.height, viewBox: '0 0 ' + lay.width + ' ' + lay.height, role: 'group', 'aria-label': title + ': ' + plural(graph.nodes.length, 'node') + ', ' + plural(graph.edges.length, 'edge') + ', drawn left to right' }); + const defs = svg('defs'), marker = svg('marker', { id: 'st-arrow-' + id, viewBox: '0 0 8 8', refX: 7, refY: 4, markerWidth: 7, markerHeight: 7, orient: 'auto-start-reverse' }); + marker.appendChild(svg('path', { d: 'M0 0 L8 4 L0 8 z', class: 'st-arrowhead' })); defs.appendChild(marker); s.appendChild(defs); + const edges = svg('g', { class: 'st-edges' }); + for (const e of graph.edges) { + const a = lay.at.get(e.from), b = lay.at.get(e.to); if (a == null || b == null) continue; + const p = lay.xy[a], q = lay.xy[b]; + let d; + if (lay.rank[b] > lay.rank[a]) { const x1 = p.x + W, y1 = p.y + H / 2, x2 = q.x - 2, y2 = q.y + H / 2, mx = (x1 + x2) / 2; d = `M${x1} ${y1} C${mx} ${y1} ${mx} ${y2} ${x2} ${y2}`; } + else { const x1 = p.x + W / 2, y1 = p.y + H, x2 = q.x + W / 2, y2 = q.y + H + 2, low = Math.max(y1, y2) + 16; d = `M${x1} ${y1} C${x1} ${low} ${x2} ${low} ${x2} ${y2}`; } + const path = svg('path', { d, class: 'st-edge' + (lay.rank[b] > lay.rank[a] ? '' : ' back'), 'marker-end': 'url(#st-arrow-' + id + ')' }); + const t = svg('title'); t.textContent = e.from + ' → ' + e.to + (e.shape ? ': ' + shapeText(e.shape) + ' ' + e.dtype : '') + (e.count > 1 ? ' (' + e.count + ' values)' : ''); path.appendChild(t); + edges.appendChild(path); + } + s.appendChild(edges); + const layer = svg('g', { class: 'st-nodes' }); + graph.nodes.forEach((n, i) => { + const { x, y } = lay.xy[i], v = valueOf(n, overlay), t = overlay ? scaled(v, overlay) : null, mark = markOf(n, status); + const gEl = svg('g', { class: 'st-node ' + n.kind + (mark ? ' mark-' + mark : '') + (mine && st.selected === n.id ? ' selected' : '') + (t != null && t > 0.55 ? ' deep' : ''), transform: `translate(${x} ${y})`, tabindex: '0', role: 'button' }); + gEl.dataset.key = (mine ? 'st-node-' : 'st-other-') + n.id; gEl.dataset.id = n.id; gEl.dataset.module = n.module; if (mark) gEl.dataset.mark = mark; + if (t != null) gEl.dataset.value = String(v); + const sub = n.kind === 'group' ? classShort(n.class) + ' · ' + plural(n.operations, 'op') : n.outputs.length ? shapeText(n.outputs[0].shape) : ''; + const what = n.kind === 'group' ? 'Module ' + n.module + ' (' + classShort(n.class) + '), ' + plural(n.operations, 'operation') + ' folded; press to open it' : n.kind === 'operation' ? 'Operation ' + n.label + ' in ' + (n.module || 'the model') + ', gives ' + valuesText(n.outputs) + (mine ? '; press for its details' : '') : (n.kind === 'input' ? 'Input ' : 'Output ') + n.id + ', ' + valuesText(n.outputs); + gEl.setAttribute('aria-label', what + (overlay ? '; ' + fmtValue(v, overlay) : '') + (mark ? '; ' + MARK_WORD[mark] : '')); + const rect = svg('rect', { width: W, height: H, rx: n.kind === 'operation' ? 6 : n.kind === 'group' ? 3 : 14, class: 'st-box' }); + if (t != null) rect.style.fill = `color-mix(in srgb, var(--ramp-hi) ${Math.round(t * 100)}%, var(--ramp-lo))`; + gEl.appendChild(rect); + if (n.kind === 'group') gEl.appendChild(svg('rect', { x: 3, y: 3, width: W - 6, height: H - 6, rx: 2, class: 'st-inner' })); + const l1 = svg('text', { x: 8, y: 17, class: 'st-label' }); l1.textContent = short(n.kind === 'group' ? n.module.split('.').slice(-2).join('.') : n.label); gEl.appendChild(l1); + const l2 = svg('text', { x: 8, y: 32, class: 'st-subl' }); l2.textContent = short(sub); gEl.appendChild(l2); + if (mark) { const b = svg('circle', { cx: W - 8, cy: 8, r: 4, class: 'st-badge' }); gEl.appendChild(b); } + const tip = svg('title'); tip.textContent = what; gEl.appendChild(tip); + const act = () => { + if (n.kind === 'group') { openModule(st, n.module, graph.depth); st.selected = null; again(ctx); return; } + if (!mine) return; + st.selected = st.selected === n.id ? null : n.id; again(ctx); + }; + gEl.addEventListener('click', act); + gEl.addEventListener('keydown', ev => { if (ev.key === 'Enter' || ev.key === ' ') { ev.preventDefault(); act(); } }); + layer.appendChild(gEl); + }); + s.appendChild(layer); + if (st.fit) { s.setAttribute('width', '100%'); s.removeAttribute('height'); s.style.maxWidth = lay.width + 'px'; } // shrunk to the box, never grown + const scroll = h('div', 'st-scroll' + (st.fit ? ' fit' : '')); scroll.appendChild(s); box.appendChild(scroll); + return box; + } + function openModule(st, path, depth) { + if (st.depth == null) st.depth = depth; + st.close = st.close.filter(p => p !== path); + // Its parents must be open too for it to show. + const parts = path.split('.'); + for (let k = 1; k <= parts.length; k++) { const p = parts.slice(0, k).join('.'); st.close = st.close.filter(x => x !== p); if (k > st.depth && !st.open.includes(p)) st.open.push(p); } + } + function closeModule(st, path, depth) { + if (st.depth == null) st.depth = depth; + st.open = st.open.filter(p => p !== path && !p.startsWith(path + '.')); + if (path.split('.').length <= st.depth && !st.close.includes(path)) st.close.push(path); + } + + function legend(overlay) { + const box = h('div', 'st-legend'); + const ramp = h('span', 'st-ramp'); ramp.setAttribute('aria-hidden', 'true'); box.appendChild(ramp); + const lo = LOG[overlay.kind] ? 0 : overlay.low; + box.appendChild(h('span', 'small faint', fmtValue(lo, overlay) + ' to ' + fmtValue(overlay.high, overlay) + (LOG[overlay.kind] ? ', on a logarithmic scale' : '') + (overlay.against ? '; against ' + overlay.against.other_path + (overlay.against.other_run !== overlay.against.run ? ' of run ' + overlay.against.other_run.slice(0, 8) : '') : '') + '. Plain: no value.')); + box.dataset.kind = overlay.kind; + return box; + } + + // ---- A node's details -------------------------------------------------------------------------------------------------- + function details(ctx, graph, n, overlay, status) { + const { st, m } = ctx, box = h('div', 'st-detail'); box.dataset.id = n.id; + const head = h('p', 'st-dtitle'); head.appendChild(h('strong', 'mono', n.kind === 'operation' ? n.label : n.id)); if (n.kind === 'operation') head.appendChild(h('span', 'small muted mono', ' ' + n.operation)); box.appendChild(head); + const dl = h('dl', 'setup iv-facts st-facts'); + const put = (k, v) => { dl.appendChild(h('dt', null, k)); dl.appendChild(h('dd', null, v)); }; + put('Module', (n.module || 'the model itself') + (n.class ? ' · ' + classShort(n.class) : '')); + put('Takes', valuesText(n.inputs)); put('Gives', valuesText(n.outputs)); + const attrs = Object.entries(n.attributes || {}); + if (attrs.length) put('Attributes', attrs.map(([k, v]) => k + ' = ' + JSON.stringify(v)).join(', ')); + if (overlay) put(COLOURS.find(([k]) => k.startsWith(overlay.kind))[1], fmtValue(valueOf(n, overlay), overlay)); + const mark = markOf(n, status); if (mark) put('Compared', MARK_WORD[mark]); + box.appendChild(dl); + if (n.tensors.length) { + box.appendChild(h('p', 'small muted', 'Its tensors, in the Weights block above:')); + const ul = h('ul', 'st-tensors'); + for (const name of n.tensors) { + const t = graph.tensors[name], li = h('li'); + const b = button('linkish mono', name, () => { if (window.LabWeights && window.LabWeights.reveal) window.LabWeights.reveal(m.id, name); }); + b.dataset.key = 'st-tensor-' + name; b.dataset.tensor = name; li.appendChild(b); + if (t) li.appendChild(h('span', 'small muted', ' ' + shapeText(t.shape) + ' ' + t.dtype + (t.kind !== 'parameter' ? ' · ' + t.kind : ''))); + ul.appendChild(li); + } + box.appendChild(ul); + } + if (n.module) { const c = button('btn sm', 'Fold ' + n.module, () => { closeModule(st, n.module, graph.depth); st.selected = null; again(ctx); }); c.dataset.key = 'st-fold-here'; box.appendChild(c); } + return box; + } + + // ---- The module outline ------------------------------------------------------------------------------------------------ + /** The module tree as a list; a module's row opens or closes it; the children of a closed module are not listed. */ + function outline(ctx, graph, status) { + const { st } = ctx, open = new Set(graph.open), box = h('div', 'st-outline'); + box.appendChild(h('p', 'small muted', 'Modules')); + const walk = (node, depth) => { + const ul = h('ul', 'st-tree'); + for (const child of node.children) { + const li = h('li'); li.dataset.path = child.path; + const isOpen = open.has(child.path), mark = status ? status.get(child.path) : null; + const row = h('div', 'st-row'); + const b = button('st-toggle', null, () => { if (isOpen) closeModule(st, child.path, graph.depth); else openModule(st, child.path, graph.depth); again(ctx); }); + b.dataset.key = 'st-mod-' + child.path; b.setAttribute('aria-expanded', String(isOpen)); + b.setAttribute('aria-label', (isOpen ? 'Fold ' : 'Open ') + child.path); + b.appendChild(h('span', 'st-caret', isOpen ? '▾' : '▸')); + b.appendChild(h('span', 'mono', child.path.split('.').pop())); + row.appendChild(b); + row.appendChild(h('span', 'small muted', classShort(child.class) + ' · ' + num(child.parameters))); + if (mark && mark !== 'same') { const s = h('span', 'wts-mark st-m-' + mark, { added: 'only here', missing: 'only there', changed: 'changed' }[mark]); row.appendChild(s); } + li.appendChild(row); + if (isOpen && child.children.length && depth < 64) li.appendChild(walk(child, depth + 1)); + ul.appendChild(li); + } + return ul; + }; + box.appendChild(graph.modules.children.length ? walk(graph.modules, 1) : h('p', 'small faint', 'The model has no modules inside it.')); + return box; + } + + return { block }; +})(); diff --git a/static/project-workspace/weights.js b/static/project-workspace/weights.js index 698d6a12..591a1465 100644 --- a/static/project-workspace/weights.js +++ b/static/project-workspace/weights.js @@ -406,5 +406,23 @@ window.LabWeights = (() => { legend.replaceChildren(ramp, ends, say); } - return { block }; + /** + * Opens the tensor called array in the Weights block of model id (structure.js's link from a node of the graph): + * its layer opened with that tensor, drawn in place, then scrolled to and focused. Resolves to whether it was + * found among the layers of the file shown. + */ + async function reveal(id, array) { + const st = places.get(id), ctx = st && st.ctx; + if (!ctx || !ctx.box.isConnected) return false; + const dot = array.lastIndexOf('.'), layer = dot > 0 ? array.slice(0, dot) : array; + Object.assign(st, { layer, tensor: array }); + await again(ctx); + const button = [...ctx.box.querySelectorAll('[data-key]')].find(e => e.dataset.key === 'wts-layer-' + layer); + if (!button) return false; + button.closest('tr').scrollIntoView({ block: 'start', behavior: 'auto' }); + button.focus({ preventScroll: true }); + return true; + } + + return { block, reveal }; })(); diff --git a/tests/browser_project_workspace_structure.cjs b/tests/browser_project_workspace_structure.cjs new file mode 100644 index 00000000..94fe8f96 --- /dev/null +++ b/tests/browser_project_workspace_structure.cjs @@ -0,0 +1,343 @@ +'use strict'; +// A model's structure in its drawer (docs/plans/training-and-curation/spec-t2.md sections 4 and 6, slice T2b) in a +// headless browser, the owner signed in, no GPU and no PyTorch. Tuldok runs with --project-folder on a copy of the +// minimal fixture, in a Git repository of its own, with three recipes of earlier work whose products are adopted +// (the command line's adopt): recipes/st-parent (the committed graph tests/fixtures/model_graph/parent.json and a +// weights.npz), recipes/st-derived, derived from it (derived.json, weights.npz and initial-weights.npz), and +// recipes/st-plain (a weights.npz and no graph). The weights are written by tests/project_structure_browser_fixture.py, +// which prints the graphs' counts and the derived model's change per module against its initial weights. +// 1. The derived model's drawer shows Structure right after Weights, with the graph's counts and every node +// drawn; the plain model has no Structure block. +// 2. Folding: the outline folds blocks (one model_graph asked; a group node replaces its operations, nothing +// outside the block is rebuilt), pressing the group opens it again. +// 3. An operation pressed shows its details; its tensor link opens that layer in the Weights block. +// 4. Colour by parameters, then by the change from the starting weights: the nodes' fills change and differ +// between nodes, and each value is the server's (the change also the fixture's arithmetic). Fit to width +// shrinks the drawing to the drawer, and back. +// 5. Compare with the parent: the second drawing, the derived model's changed and added modules marked as +// model_graph_compare says, and listed. +// 6. Nothing changed: the window regaining focus adds, removes and changes no node of the drawer. +// 7. Light and dark at 1440 by 900 and 390 by 844: every node drawn, nothing in the drawer overflowing sideways +// (the page's header, strip and map are wider than 390 px on every tab; recorded, not asserted); screenshots +// (with --shots , written there too). +// It fails on any script error and any failed request. +// node tests/browser_project_workspace_structure.cjs [--shots ] +const assert = require('node:assert/strict'), fs = require('node:fs'), os = require('node:os'), path = require('node:path'); +const { spawn, execFileSync } = require('node:child_process'), { once } = require('node:events'); +const { authenticatedFixture } = require('./auth_helpers.cjs'), { waitForDebugger } = require('./browser_startup.cjs'), { cdpSession } = require('./browser_cdp_session.cjs'), { qaDirectory } = require('./qa_artifacts.cjs'); + +const root = path.resolve(__dirname, '..'); +const argv = process.argv.slice(2), option = name => { const i = argv.indexOf(name); return i >= 0 ? argv[i + 1] : null; }; +assert.ok(process.env.TULDOK_DATABASE_URL, 'TULDOK_DATABASE_URL must name a disposable PostgreSQL cluster'); +const venv = path.join(root, '.venv', 'bin'); +if (fs.existsSync(path.join(venv, 'python'))) process.env.PATH = venv + path.delimiter + process.env.PATH; // auth_helpers runs python3 +const python = fs.existsSync(path.join(venv, 'python')) ? path.join(venv, 'python') : 'python3'; +const WATCHED = ['summary', 'status', 'build_requests', 'environments', 'runs']; +const DERIVED = 'recipes/st-derived', PARENT = 'recipes/st-parent', PLAIN = 'recipes/st-plain'; +const RECIPES = { + 'st-parent': { title: 'Structure parent', labels: { short: 'SP', trained_at: '2026-10-01' }, change: 'architecture' }, + 'st-derived': { title: 'Structure derived', labels: { short: 'SD', trained_at: '2026-10-05' }, change: 'architecture', derived_from: PARENT }, + 'st-plain': { title: 'Weights without a graph', labels: { short: 'SN', trained_at: '2026-10-07' }, change: 'component' } +}; +const GRAPHS = path.join(root, 'tests', 'fixtures', 'model_graph'); + +const temporary = fs.mkdtempSync(path.join(os.tmpdir(), 'tuldok-structure-browser-')); +const report = qaDirectory(root, 'project-workspace-structure'); +const shots = option('--shots') ? path.resolve(option('--shots')) : null; if (shots) fs.mkdirSync(shots, { recursive: true }); +const children = [], checks = [], errors = [], failures = []; +let server, serverErrors = '', origin, auth, socket, session, send, evaluate, owned = null; +const pause = ms => new Promise(resolve => setTimeout(resolve, ms)); +async function until(fn, label, tries = 300) { for (let i = 0; i < tries; i++) { const value = await fn(); if (value) return value; await pause(100); } throw Error('Timed out: ' + label); } +function check(text) { checks.push(text); console.log('PASS ' + text); } +function launch(command, args, options) { const child = spawn(command, args, options); children.push(child); return child; } +async function stop(child) { if (!child || child.exitCode !== null || child.signalCode !== null) return; const exited = once(child, 'exit'); child.kill('SIGTERM'); await Promise.race([exited, pause(10000)]); if (child.exitCode === null && child.signalCode === null) { child.kill('SIGKILL'); await exited; } } +function findBrowser() { + const candidates = [process.env.BROWSER, '/usr/bin/chromium', '/usr/bin/chromium-browser', '/usr/bin/google-chrome']; + const cache = path.join(os.homedir(), '.cache', 'ms-playwright'); + if (fs.existsSync(cache)) for (const name of fs.readdirSync(cache).filter(n => n.startsWith('chromium_headless_shell-')).sort().reverse()) candidates.push(path.join(cache, name, 'chrome-headless-shell-linux64', 'chrome-headless-shell')); + const found = candidates.find(candidate => candidate && fs.existsSync(candidate)); + assert.ok(found, 'No headless browser: set BROWSER'); + return found; +} +/** Drops the project's schema and the catalog's from the disposable database, so each run imports afresh. */ +function dropOwned(folder, catalog) { + const id = JSON.parse(fs.readFileSync(path.join(folder, 'tuldok.json'), 'utf8')).id; + execFileSync(python, ['-c', `import json, os, pathlib, sys, psycopg +from psycopg import sql +from tuldok_project import store +store.drop_project(sys.argv[1], os.environ['TULDOK_DATABASE_URL']) +root = pathlib.Path(sys.argv[2]) +if root.exists(): + with psycopg.connect(os.environ['TULDOK_DATABASE_URL'], autocommit=True) as c: + for p in root.rglob('.tuldok.json'): + v = json.loads(p.read_text()) + name = 'projection_' + v['projection_id'] if v.get('version') == 2 else 'catalog_' + v['dataset_id'] + c.execute(sql.SQL('DROP SCHEMA IF EXISTS {} CASCADE').format(sql.Identifier(name))) +`, id, catalog], { cwd: root, stdio: ['ignore', 'pipe', 'pipe'] }); +} +async function contract(name) { + const capabilities = await (await auth.fetch(origin + '/api/agent/capabilities')).json(); + const operation = capabilities.operations.find(item => item.id === 'project.' + name), c = operation.contracts[operation.contracts.length - 1]; + return 'project.' + name + '/' + c.version + '/' + c.sha256; +} +/** An operation as the owner. */ +async function api(name, body = {}) { + const headers = { 'Content-Type': 'application/json', 'Tuldok-Operation-Contract': await contract(name) }; + const response = await auth.fetch(origin + '/api/project/' + name, { method: 'POST', headers, body: JSON.stringify(body) }); + const value = await response.json(); assert.equal(response.status, 200, name + ': ' + JSON.stringify(value)); return value; +} + +// ---- The page's requests, from the browser's network, with their bodies ------------------------------------------------ +const calls = new Map(), finished = []; +function network(event) { + const p = event.params; + if (event.method === 'Network.requestWillBeSent' && /\/api\/project\/[a-z_]+$/.test(p.request.url)) { let body = null; try { body = p.request.postData ? JSON.parse(p.request.postData) : null; } catch (_) { body = null; } calls.set(p.requestId, { name: p.request.url.split('/').pop(), body, sent: Date.now() }); } + if ((event.method === 'Network.loadingFinished' || event.method === 'Network.loadingFailed') && calls.has(p.requestId)) { finished.push(Object.assign(calls.get(p.requestId), { done: Date.now() })); calls.delete(p.requestId); } +} +const asked = (name, since = 0, test = () => true) => finished.concat([...calls.values()]).filter(f => f.name === name && f.sent >= since && test(f.body || {})); +async function reading(since, names, label, tries = 300) { + await until(() => names.every(name => finished.some(f => f.name === name && f.sent >= since)), 'a reading: ' + label, tries); + await until(() => !calls.size && Date.now() - Math.max(0, ...finished.map(f => f.done)) > 700, 'the reading done: ' + label, 300); + await settled(label); +} +/** Waits until nothing reads: no "Reading…", nothing busy in the drawer, no request of the project in flight. */ +async function settled(label) { + await until(() => evaluate(`(() => { const reading = e => [...e.querySelectorAll('.note')].some(n => n.textContent === 'Reading…'); return !reading(document.getElementById('main')) && !reading(document.getElementById('aside')) && !document.querySelector('#aside [aria-busy]'); })()`).then(ok => ok && !calls.size), 'settled: ' + label); + await pause(200); +} +async function hash(value) { await evaluate(`location.hash = ${JSON.stringify('#' + value)}`); await settled('#' + value); await pause(200); await settled('#' + value); } +const byKey = key => `[data-key=${JSON.stringify(key)}]`; +async function centre(selector) { + for (let moved = 0; ; moved++) { + const at = await until(() => evaluate(`(() => { const e = [...document.querySelectorAll(${JSON.stringify(selector)})].find(e => e.getClientRects().length); if (!e) return null; e.scrollIntoView({ block: 'nearest', inline: 'nearest' }); const r = e.getBoundingClientRect(), x = r.left + Math.min(r.width / 2, 20), y = r.top + r.height / 2, hit = document.elementFromPoint(x, y); return { x, y, ok: !!hit && (hit === e || e.contains(hit)) }; })()`), 'shown: ' + selector, 100); + if (at.ok) return at; + if (moved > 20) throw Error('The target of ' + selector + ' is never under its point'); + await pause(100); + } +} +async function mouse(type, x, y, buttons = 0) { await send('Input.dispatchMouseEvent', { type, x, y, button: type === 'mouseMoved' ? (buttons ? 'left' : 'none') : 'left', buttons, clickCount: type === 'mouseMoved' ? 0 : 1 }); } +async function press(selector) { const { x, y } = await centre(selector); await mouse('mouseMoved', x, y); await mouse('mousePressed', x, y, 1); await mouse('mouseReleased', x, y); } +/** Chooses an option of a select by the keyboard's way of changing it (the change event the page listens to). */ +async function choose(selector, value) { await evaluate(`(() => { const s = document.querySelector(${JSON.stringify(selector)}); s.focus(); s.value = ${JSON.stringify(value)}; s.dispatchEvent(new Event('change', { bubbles: true })); return true; })()`); } +async function frames() { await evaluate('new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve)))'); } +async function shot(name) { + await frames(); + const png = Buffer.from((await send('Page.captureScreenshot', { format: 'png', captureBeyondViewport: false })).data, 'base64'); + fs.writeFileSync(path.join(report, name + '.png'), png); if (shots) fs.writeFileSync(path.join(shots, name + '.png'), png); +} +const close = (a, b, label, tol = 1e-9) => assert.ok(Math.abs(a - b) <= tol * Math.max(1, Math.abs(b)), label + ': ' + a + ' is not ' + b); +/** The nodes of a drawing ('this' or 'other'): id, kind, mark, value, the computed fill of the box. */ +const nodes = (which = 'this') => evaluate(`[...document.querySelectorAll('#aside .st-draw[data-which="${which}"] g.st-node')].map(g => ({ id: g.dataset.id, kind: [...g.classList].find(c => ['input', 'operation', 'output', 'group'].includes(c)), module: g.dataset.module, mark: g.dataset.mark || null, value: g.dataset.value == null ? null : Number(g.dataset.value), fill: getComputedStyle(g.querySelector('rect.st-box')).fill, label: g.getAttribute('aria-label'), w: g.getBBox().width }))`); + +(async () => { + // ---- The fixture: minimal + three recipes of earlier work, in Git; their products adopted ------------------------------------ + fs.cpSync(path.join(root, 'tests', 'fixtures', 'tuldok_project', 'minimal'), path.join(temporary, 'fixture'), { recursive: true }); + const folder = path.join(temporary, 'fixture', 'project'); + for (const [name, r] of Object.entries(RECIPES)) fs.writeFileSync(path.join(folder, 'recipes', name + '.json'), JSON.stringify(Object.assign({ format: 'tuldok_definition_v1', kind: 'recipe', title: r.title, description: 'A model for the browser check of a model\'s structure.', labels: r.labels, + earlier_work: { rebuild: 'no', reason: 'Written by the browser check of the structure; only its graph and weights remain.' }, model: 'models/stepper', group: 'steppers', change: r.change }, r.derived_from ? { derived_from: r.derived_from } : {}), null, 2) + '\n'); + const git = ['-c', 'user.name=Tuldok Test', '-c', 'user.email=test@example.invalid', '-c', 'commit.gpgsign=false', '-c', 'init.defaultBranch=main', '-C', path.join(temporary, 'fixture')]; + execFileSync('git', [...git, 'init', '-q']); execFileSync('git', [...git, 'add', '-A']); execFileSync('git', [...git, 'commit', '-q', '-m', 'The fixture.']); + const files = path.join(temporary, 'weights'); + const X = JSON.parse(execFileSync(python, [path.join(root, 'tests', 'project_structure_browser_fixture.py'), '--out', files]).toString()); + const home = path.join(temporary, 'home'), catalog = path.join(temporary, 'catalog'); fs.mkdirSync(home); + const env = { ...process.env, TULDOK_PROJECT_HOME: home, TULDOK_SETTINGS: path.join(temporary, 'settings.json') }; + owned = [folder, catalog]; dropOwned(folder, catalog); + const cli = (...args) => execFileSync(python, ['-m', 'tuldok_project', ...args], { cwd: root, env, stdio: ['ignore', 'pipe', 'pipe'] }).toString(); + const manifest = path.join(temporary, 'adopt.json'); + fs.writeFileSync(manifest, JSON.stringify({ format: 'tuldok_adoption_v1', products: [ + { reference: PARENT, files: { 'weights.npz': path.join(files, 'parent', 'weights.npz'), 'model-graph.json': path.join(GRAPHS, 'parent.json') } }, + { reference: DERIVED, files: { 'weights.npz': path.join(files, 'derived', 'weights.npz'), 'initial-weights.npz': path.join(files, 'derived', 'initial-weights.npz'), 'model-graph.json': path.join(GRAPHS, 'derived.json') } }, + { reference: PLAIN, files: { 'weights.npz': path.join(files, 'plain', 'weights.npz') } } + ] })); + cli('adopt', folder, manifest, '--copy'); + let output = ''; + server = launch(python, ['-u', 'app.py', '--port', '0', '--data', catalog, '--project-folder', folder], { cwd: root, env, stdio: ['ignore', 'pipe', 'pipe'] }); + server.stdout.on('data', chunk => { output += chunk; }); server.stderr.on('data', chunk => { serverErrors += chunk; }); + const port = await until(() => { if (server.exitCode !== null) throw Error('Tuldok exited: ' + serverErrors); return output.match(/127\.0\.0\.1:(\d+)/)?.[1]; }, 'Tuldok start-up', 3000); + origin = 'http://127.0.0.1:' + port; + auth = authenticatedFixture(); await auth.register(origin, catalog, root); + const products = (await api('products')).products, runOf = ref => products.find(p => p.reference === ref).run_id; + const compared = await api('model_graph_compare', { run: runOf(DERIVED), other_run: runOf(PARENT) }); + const parameters = await api('model_graph_overlay', { run: runOf(DERIVED), kind: 'parameters' }); + const change = await api('model_graph_overlay', { run: runOf(DERIVED), kind: 'change', against: 'start' }); + for (const [p, v] of Object.entries(X.against_initial)) { if (v === null) assert.equal(change.modules[p], null, p); else close(change.modules[p], v, 'The change of ' + p + ' is the fixture\'s'); } + + const browser = launch(findBrowser(), ['--headless', '--no-sandbox', '--disable-gpu', '--no-first-run', '--hide-scrollbars', '--remote-debugging-port=0', '--window-size=1440,900', '--user-data-dir=' + path.join(temporary, 'browser'), 'about:blank'], { stdio: 'ignore', env: { ...process.env, XDG_CONFIG_HOME: temporary, XDG_CACHE_HOME: temporary } }); + const debugPort = await waitForDebugger(browser, path.join(temporary, 'browser', 'DevToolsActivePort')); + const target = (await (await fetch('http://127.0.0.1:' + debugPort + '/json')).json()).find(item => item.type === 'page'); + socket = new WebSocket(target.webSocketDebuggerUrl); await once(socket, 'open'); + session = cdpSession(socket, { timeoutMs: 60000, onEvent: event => { + network(event); + if (event.method === 'Runtime.exceptionThrown') errors.push(event.params.exceptionDetails.exception?.description || event.params.exceptionDetails.text); + if (event.method === 'Runtime.consoleAPICalled' && event.params.type === 'error') errors.push(event.params.args.map(a => a.value ?? a.description).join(' ')); + if (event.method === 'Log.entryAdded' && event.params.entry.level === 'error') errors.push(event.params.entry.text + ' ' + (event.params.entry.url || '')); + if (event.method === 'Network.loadingFailed' && !event.params.canceled) failures.push({ id: event.params.requestId, error: event.params.errorText }); + if (event.method === 'Network.responseReceived' && event.params.response.status >= 400) failures.push({ url: event.params.response.url, status: event.params.response.status }); + } }); + send = session.send; + evaluate = async expression => { const result = await send('Runtime.evaluate', { expression, awaitPromise: true, returnByValue: true }); if (result.exceptionDetails) throw Error(JSON.stringify(result.exceptionDetails)); return result.result.value; }; + await send('Page.enable'); await send('Runtime.enable'); await send('Network.enable'); await send('Log.enable'); + const size = async (width, height) => send('Emulation.setDeviceMetricsOverride', { width, height, deviceScaleFactor: 1, mobile: false }); + const theme = async name => { await send('Emulation.setEmulatedMedia', { features: [{ name: 'prefers-color-scheme', value: name }, { name: 'prefers-reduced-motion', value: 'reduce' }] }); }; + await auth.browser(send, origin); // the owner's session + const model = ref => 'map/' + encodeURIComponent(ref); + const load = async (name, place) => { + await theme(name); + await send('Page.navigate', { url: 'about:blank' }); await pause(100); + await send('Page.navigate', { url: origin + '/?theme=' + name + '#' + place }); + await until(() => evaluate(`document.readyState === 'complete' && !!document.getElementById('needs-btn') && !document.getElementById('needs-btn').disabled`), 'the project read', 1200); + await settled('opened ' + place); + }; + const shown = () => until(() => evaluate(`!!document.querySelector('#aside .st svg g.st-node')`), 'the Structure block'); + + // ---- 1. The derived model's drawer: Structure after Weights, the counts, every node; the plain model: no block ------------- + await size(1440, 900); await load('light', model(DERIVED)); await shown(); await settled('the derived drawer'); + const b1 = await evaluate(`(() => { const s = document.querySelector('#aside .st-box'); return { after: s.previousElementSibling.className, size: s.querySelector('.st-size').textContent, how: s.querySelector('.st-how').textContent }; })()`); + assert.equal(b1.after, 'wts-box', 'Structure follows Weights'); + const d = X.graphs.derived; + assert.match(b1.size, new RegExp('^model-graph\\.json · ' + d.operations + ' operations · ' + d.modules + ' modules · ' + d.tensors + ' tensors$')); + assert.match(b1.how, /^Recorded by torch\.export with PyTorch 2\.8\.0\+cpu; example input x 2×1×8×8\.$/); + const n1 = await nodes(); + assert.equal(n1.length, d.nodes, 'every node of a small graph is drawn, nothing folded'); + assert.ok(n1.every(n => n.w > 50), 'every node has a box'); + assert.equal(n1.filter(n => n.kind === 'group').length, 0); + await hash(model(PLAIN)); await until(() => evaluate(`!!document.querySelector('#aside .wts table')`), 'the plain model\'s weights'); await settled('plain'); + assert.equal(await evaluate(`document.querySelector('#aside .st-box').hidden && !document.querySelector('#aside .st')`), true, 'No graph: no Structure block'); + check('1. ' + DERIVED + ': Structure after Weights, "' + b1.size + '", ' + n1.length + ' nodes drawn; ' + PLAIN + ' has weights and no Structure block'); + + // ---- 2. Folding in place: the outline folds blocks, the group opens it again ------------------------------------------------ + await hash(model(DERIVED)); await shown(); await settled('derived again'); + await evaluate(`(() => { for (const e of document.querySelectorAll('#aside *')) e.__seen = 1; return true; })()`); + const since2 = Date.now(); + await press(byKey('st-mod-blocks')); await settled('blocks folded'); + assert.equal(asked('model_graph', since2).length, 1, 'One model_graph for the fold'); + assert.deepEqual(asked('model_graph', since2)[0].body.close, ['blocks']); + const n2 = await nodes(); + const blockOps = n1.filter(n => n.kind === 'operation' && n.module.startsWith('blocks')).length; + assert.equal(n2.length, n1.length - blockOps + 1, 'The ' + blockOps + ' operations of blocks are one group'); + assert.deepEqual(n2.filter(n => n.kind === 'group').map(n => n.id), ['module:blocks']); + const outside = await evaluate(`[...document.querySelectorAll('#aside *')].filter(e => !e.__seen && !e.closest('.st-box')).length`); + assert.equal(outside, 0, 'Nothing outside the Structure block is rebuilt'); + assert.equal(await evaluate(`document.querySelector('#aside [data-key="st-mod-blocks"]').getAttribute('aria-expanded')`), 'false'); + assert.equal(await evaluate(`document.activeElement.dataset.key`), 'st-mod-blocks', 'The outline\'s button keeps the focus'); + await shot('light-1440-1-folded'); + const since2b = Date.now(); + await press(byKey('st-node-module:blocks')); await settled('blocks opened'); + assert.equal(asked('model_graph', since2b).length, 1, 'One model_graph to open it'); + const n2b = await nodes(); + assert.equal(n2b.length, n1.length, 'Opened again: every node'); + check('2. The outline folded blocks (' + blockOps + ' operations into one group, one model_graph, nothing outside the block rebuilt); pressing the group opened it again (' + n2b.length + ' nodes)'); + + // ---- 3. An operation's details; its tensor reaches the Weights block ---------------------------------------------------- + const stem = n1.find(n => n.module === 'stem'); + await press(byKey('st-node-' + stem.id)); await settled('stem selected'); + const det = await evaluate(`(() => { const e = document.querySelector('#aside .st-detail'); return { id: e.dataset.id, text: e.textContent, tensors: [...e.querySelectorAll('[data-tensor]')].map(b => b.dataset.tensor) }; })()`); + assert.equal(det.id, stem.id); assert.deepEqual(det.tensors, ['stem.weight', 'stem.bias']); + assert.match(det.text, /aten\.conv2d\.default/); assert.match(det.text, /2×1×8×8 float32/); assert.match(det.text, /padding = \[1,1\]/); + await press(byKey('st-tensor-stem.weight')); + await until(() => evaluate(`!!document.querySelector('#aside tr.wts-row[data-layer="stem"] [aria-expanded="true"]')`), 'the stem layer opened in Weights'); + await settled('weights opened'); + const w3 = await evaluate(`({ focus: document.activeElement.dataset.key, tensor: document.querySelector('#aside .wts-tensor').getAttribute('aria-label'), top: document.querySelector('#aside tr.wts-row[data-layer="stem"]').getBoundingClientRect().top, view: (r => ({ top: r.top, bottom: r.bottom }))(document.getElementById('drawer').getBoundingClientRect()) })`); + assert.equal(w3.focus, 'wts-layer-stem', 'The layer\'s button has the focus'); + assert.equal(w3.tensor, 'Tensor stem.weight'); + assert.ok(w3.top >= w3.view.top - 1 && w3.top < w3.view.bottom, 'The layer is scrolled into the drawer\'s view: ' + JSON.stringify(w3)); + await shot('light-1440-2-tensor-in-weights'); + check('3. ' + stem.id + ' pressed: its details (aten.conv2d.default, 2×1×8×8 in, padding [1,1]) with stem.weight and stem.bias; stem.weight opened the stem layer in Weights, focused and in view'); + + // ---- 4. Colour by parameters, then by the change from the starting weights ------------------------------------------------ + await evaluate(`document.querySelector('#aside .st').scrollIntoView(); true`); + const plainFill = (await nodes()).find(n => n.id === stem.id).fill; + await choose('#aside [data-key="st-colour"]', 'parameters'); await settled('parameters'); + const n4 = await nodes(); + for (const n of n4) if (n.kind === 'operation') assert.equal(n.value, parameters.nodes[n.id], n.id + '\'s parameters are the server\'s'); + const fills4 = new Set(n4.filter(n => n.kind === 'operation' && n.value != null).map(n => n.fill)); + assert.ok(fills4.size >= 3, 'The fills differ between nodes: ' + [...fills4].join(' | ')); + assert.notEqual(n4.find(n => n.id === stem.id).fill, plainFill, 'Colouring changes the fill'); + assert.equal(await evaluate(`document.querySelector('#aside .st-legend').dataset.kind`), 'parameters'); + await choose('#aside [data-key="st-colour"]', 'change:start'); await settled('change'); + const n4b = await nodes(); + for (const n of n4b) if (n.kind === 'operation') { const want = change.nodes[n.id]; if (want == null) assert.equal(n.value, null, n.id); else close(n.value, want, n.id + '\'s change'); } + close(n4b.find(n => n.id === stem.id).value, X.against_initial.stem, 'the stem\'s change is the fixture\'s'); + assert.notDeepEqual(n4b.map(n => n.fill), n4.map(n => n.fill), 'The change colours differently from the parameters'); + await shot('light-1440-3-change'); + // Fit to width: the whole drawing in the drawer's width, every node still a box; pressed again, its actual size. + await press(byKey('st-fit')); await settled('fit'); + const fit4 = await evaluate(`(() => { const sc = document.querySelector('#aside .st-draw[data-which="this"] .st-scroll'), s = sc.querySelector('svg'); return { box: sc.clientWidth, svg: s.getBoundingClientRect().width, scroll: sc.scrollWidth - sc.clientWidth, natural: s.viewBox.baseVal.width }; })()`); + assert.ok(fit4.svg <= fit4.box + 1 && fit4.scroll <= 1 && fit4.natural > fit4.box, 'Fitted to the width: ' + JSON.stringify(fit4)); + await shot('light-1440-3b-fit'); + await press(byKey('st-fit')); await settled('actual size'); + assert.ok(await evaluate(`(() => { const sc = document.querySelector('#aside .st-draw[data-which="this"] .st-scroll'); return sc.scrollWidth - sc.clientWidth > 100; })()`), 'Actual size scrolls again'); + check('4. Coloured by parameters (' + fills4.size + ' fills, each value the server\'s), then by the change from the starting weights (stem ' + n4b.find(n => n.id === stem.id).value.toFixed(4) + ', the fixture\'s ' + X.against_initial.stem.toFixed(4) + ')'); + + // ---- 5. Compared with the parent ------------------------------------------------------------------------------------------ + const since5 = Date.now(); + await choose('#aside [data-key="st-compare"]', PARENT); await settled('compare'); + assert.equal(asked('model_graph_compare', since5).length, 1); + const n5 = await nodes(), o5 = await nodes('other'); + assert.equal(o5.length, X.graphs.parent.nodes, 'The parent\'s graph is drawn'); + const status = Object.fromEntries(compared.modules.map(r => [r.path, r.status])); + for (const n of n5) if (n.kind === 'operation') { const s = status[n.module]; assert.equal(n.mark, s && s !== 'same' ? s : null, n.id + ' in ' + n.module); } + assert.deepEqual(n5.filter(n => n.mark).map(n => n.module + ':' + n.mark).sort(), ['gate:added', 'head.0:changed', 'head.2:changed']); + const listed = await evaluate(`[...document.querySelectorAll('#aside .st-difflist li')].map(li => li.dataset.path + ':' + li.dataset.status)`); + assert.deepEqual(listed, compared.modules.filter(r => r.status !== 'same').map(r => r.path + ':' + r.status)); + assert.deepEqual(o5.filter(n => n.mark).map(n => n.module + ':' + n.mark).sort(), ['head.0:changed', 'head.2:changed']); + // Folded at depth 0 both drawings fold the same way; head is marked as holding a change. + await press(byKey('st-fold-1')); await settled('depth 1'); + await press(byKey('st-mod-head')); await settled('head folded'); + const head5 = (await nodes()).find(n => n.id === 'module:head'), headOther = (await nodes('other')).find(n => n.id === 'module:head'); + assert.equal(head5.mark, 'inside'); assert.equal(headOther.mark, 'inside'); + await evaluate(`document.querySelector('#aside .st-sub').scrollIntoView(); true`); await shot('light-1440-4-compare'); + check('5. Compared with ' + PARENT + ' (one model_graph_compare): ' + listed.join(', ') + ' marked and listed; the parent\'s ' + o5.length + ' nodes drawn below with head.0 and head.2 changed; head folded is marked as holding a change in both'); + + // ---- 6. Nothing changed: the window regains focus --------------------------------------------------------------------------- + await evaluate(`window.__changes = 0; window.__mo = new MutationObserver(list => { window.__changes += list.length; }); window.__mo.observe(document.getElementById('aside'), { childList: true, subtree: true, attributes: true, characterData: true }); true`); + const since6 = Date.now(); + await evaluate(`window.dispatchEvent(new Event('focus')); true`); await reading(since6, WATCHED.concat(['map']), 'focus'); + const changes6 = await evaluate(`(() => { window.__mo.disconnect(); return window.__changes; })()`); + assert.equal(changes6, 0, 'The drawer is not touched'); + assert.equal(asked('model_graph', since6).length + asked('model_graph_overlay', since6).length + asked('model_graph_compare', since6).length, 0, 'Nothing of the graph is asked again'); + check('6. The window regaining focus: 0 changes in the drawer, nothing of the graph asked again'); + + // ---- 7. Light and dark, 1440 and 390 wide --------------------------------------------------------------------------------- + const seen7 = [], fills7 = {}, headerOver = []; + for (const [w, hgt] of [[1440, 900], [390, 844]]) for (const name of ['light', 'dark']) { + const tag = name + '-' + w; + await size(w, hgt); await load(name, model(DERIVED)); await shown(); await settled(tag); + await choose('#aside [data-key="st-colour"]', 'change:start'); await settled(tag + ' colour'); + await choose('#aside [data-key="st-compare"]', PARENT); await settled(tag + ' compare'); + await evaluate(`document.querySelector('#aside .st').scrollIntoView(); true`); await pause(200); + const r = await evaluate(`(() => { const s = document.querySelector('#aside .st'), d = document.getElementById('drawer'); const wide = [...s.querySelectorAll('*')].filter(e => !e.closest('.st-scroll') && e.getBoundingClientRect().width > 0 && e.getBoundingClientRect().right > d.getBoundingClientRect().right + 1).map(e => e.tagName + '.' + e.getAttribute('class')).slice(0, 4); return { drawerRight: Math.round(d.getBoundingClientRect().right - d.parentElement.getBoundingClientRect().right), offenders: [...d.querySelectorAll('*')].filter(e => e.getBoundingClientRect().right > d.getBoundingClientRect().right + 1 && !e.closest('.st-scroll')).map(e => e.tagName + '.' + e.getAttribute('class') + ':' + Math.round(e.getBoundingClientRect().right)).slice(0, 8), nodes: s.querySelectorAll('g.st-node').length, over: d.scrollWidth - d.clientWidth, page: document.documentElement.scrollWidth - innerWidth, wide, scroll: s.querySelector('.st-scroll').getBoundingClientRect().right <= d.getBoundingClientRect().right + 1, label: getComputedStyle(s.querySelector('g.st-node .st-label')).fill }; })()`); + assert.equal(r.nodes, d.nodes + X.graphs.parent.nodes, tag + ': both drawings'); + // At 390 px the page's own header, strip and map are wider than the window on every tab before this block draws + // (found here; not this phase's; the drawer's stage among them): the drawer must not pass its stage, nothing in it + // the drawer, and the page's overflow is recorded. + assert.ok(r.over <= 1 && r.drawerRight <= 0 && !r.offenders.length && !r.wide.length && r.scroll, tag + ': nothing in the drawer overflows sideways ' + JSON.stringify(r)); + if (r.page > 0) headerOver.push(tag + ' ' + r.page + ' px'); + fills7[tag] = r.label; + await shot(tag + '-5-structure'); + await evaluate(`document.querySelector('#aside .st-draw[data-which="other"]').scrollIntoView(); true`); await pause(150); await shot(tag + '-6-other'); + seen7.push(tag); + } + assert.notEqual(fills7['light-1440'], fills7['dark-1440'], 'The labels follow the theme'); + await size(1440, 900); + check('7. Both drawings drawn and nothing in the drawer overflowing sideways in ' + seen7.join(', ') + (headerOver.length ? ' (the page itself, outside the drawer, is wider than the window: ' + headerOver.join(', ') + ')' : '') + (shots ? '; screenshots in ' + shots : '')); + + // ---- Nothing failed --------------------------------------------------------------------------------------------------------- + assert.deepEqual(errors, [], 'Script errors'); + assert.deepEqual(failures, [], 'Failed requests'); + check('No script error, no failed request'); + fs.writeFileSync(path.join(report, 'receipt.json'), JSON.stringify({ status: 'pass', folder, checks }, null, 2) + '\n'); + console.log('Receipt in ' + report); +})().catch(async error => { + process.exitCode = 1; + console.error(error); if (serverErrors) console.error('Server:', serverErrors.slice(-4000)); + console.error('Script errors:', JSON.stringify(errors)); console.error('Failed requests:', JSON.stringify(failures)); + try { if (evaluate) { await shot('failure'); console.error('Drawer:', (await evaluate('document.getElementById("aside").innerText')).slice(0, 2500)); } } catch (_) { /* the page is gone */ } + fs.writeFileSync(path.join(report, 'failure.json'), JSON.stringify({ status: 'failed', error: String(error && error.stack || error), checks, errors, failures }, null, 2) + '\n'); +}).finally(async () => { + try { session?.close(); } catch (_) { /* closed */ } + for (const child of children.reverse()) await stop(child); + if (owned) try { dropOwned(...owned); } catch (error) { console.error('Dropping the disposable schemas failed:', error.message); process.exitCode = 1; } + try { execFileSync('chmod', ['-R', 'u+w', temporary]); } catch (_) { /* nothing was made read-only */ } + fs.rmSync(temporary, { recursive: true, force: true }); +}); diff --git a/tests/project_structure_browser_fixture.py b/tests/project_structure_browser_fixture.py new file mode 100644 index 00000000..7c48de2e --- /dev/null +++ b/tests/project_structure_browser_fixture.py @@ -0,0 +1,105 @@ +"""The weights the browser check of a model's structure reads (tests/browser_project_workspace_structure.cjs). + +Written with the standard library only; the graphs are the committed tests/fixtures/model_graph/parent.json and +derived.json (written once by tuldok_log.graph.export_graph). For each tensor the graph names, a 32-bit value +made from a formula: + +- parent/weights.npz: the parent's tensors; +- derived/weights.npz and derived/initial-weights.npz: the derived model's, and those it started from (the + stem and the blocks moved by known amounts, the head and the gate started at the same values); +- plain/weights.npz: a model with weights and no graph. + +It prints, as JSON, what the check compares the page with: each graph's counts, and the relative change of each +module of the derived model against its initial weights (the norm of the difference over the norm of the other, +over the tensors under the module; null when the other's norm is zero or nothing is compared). +""" +import argparse +import io +import json +import math +import os +import struct +import zipfile + +HERE = os.path.dirname(os.path.abspath(__file__)) +GRAPHS = os.path.join(HERE, 'fixtures', 'model_graph') + + +def f32(x): + return struct.unpack(' Date: Thu, 19 Nov 2026 05:56:31 -0700 Subject: [PATCH 094/131] docs(plan): phase 1 as built Co-Authored-By: Claude Opus 5.5 --- docs/plans/training-and-curation/spec-t1.md | 113 ++++++++++++++++++++ 1 file changed, 113 insertions(+) diff --git a/docs/plans/training-and-curation/spec-t1.md b/docs/plans/training-and-curation/spec-t1.md index a857a444..03ce88b7 100644 --- a/docs/plans/training-and-curation/spec-t1.md +++ b/docs/plans/training-and-curation/spec-t1.md @@ -174,3 +174,116 @@ In the run's drawer on the Train tab, a block **Training**, after "Latest progre ## 9. Out of scope A lab converter of `history.json` (a lab script, deferred); TensorBoard event files or any other format; logging from inside Tuldok's server; text or audio samples; comparing histograms of two runs; alerts on a diverging run; the Analysis or Benchmarks tabs; any change to how runs are started or to the lab's runs. + +## As built + +What differs from the text above, and what was found while building it. + +### T1a, the reader and the operations + +- **`tuldok_project/training.py`** holds the reader; `service.py` gains `TRAINING_READS` beside `INSIDE_READS`. The + run is found under the service's lock (`_training_run`, any state, its `directory`) and its files read outside + it. A run of any state with an output directory is read; one without (a queued run) answers `training` with + `present` false and the other four `not-found`. +- **`training_histograms` also answers `totals`** (each row's count before re-binning), which the page uses to shade + each column by its share. It is in the contract text. +- **Damaged lines.** A line that is not JSON, not an object, has no integer `step` or finite `time` (metrics), or + fails the histogram, sample or checkpoint checks is counted in `bad_lines`; past the bound on series or tensor + pairs the dropped name is reported once in `problems` but not counted as a bad line. A line longer than the bound + is skipped up to its newline even when that arrives in a later read. A number too large for a float + (`1e400` as an integer) is a non-finite value, a gap. +- **What is kept per file:** the metrics as arrays (step, time, epoch, and per series its line positions and + values) with each series' least, greatest and last finite value kept as lines arrive, so `training` costs a + `stat` and the appended bytes, not a pass over the series; a histogram line as its offset and length; samples and + checkpoints as small dicts. 64 file states (four a run) are kept, least recently used dropped. +- **A symlink** under `training/` that leads outside the output directory is treated as absent. +- **`GET /api/project/file`** serves a `training/` address (no `!`) of a run in any state with a directory through + `service.product_file`; `app.py` is unchanged. +- **Tests:** `tests/test_tuldok_project_training.py`, 18 (15 without a database, 3 with); the read test and the + operation count (61 to 66) in `test_tuldok_project_service.py`. The catalog's digest is unchanged + (`ad5cc7ac…`, 110 operations), checked in the new file and by the agent interface tests. + +### T1b, `tuldok_log` + +- As section 3, with `Logger.elapsed()` public and `log_sample` returning the path it wrote. `autolog` logs the + first optimizer step as well as every `every`-th, so a curve starts at step 1. Gradient histograms are written in + the optimizer's pre-step hook (gradients may be zeroed after the step), weight histograms after it; both carry the + step number after the step. +- **The loss module's forward hook counts every call of the module**, so a script that also calls the same loss + module for validation mixes those values into `loss`. The docstring says to pass the module or call `note()`; + a separate validation loss module (or `note(val_loss=…)`) avoids it. Not otherwise guarded. +- `note()` scalars other than the loss are written with the next logged line and then forgotten; a note made on a + step that is not logged waits for the next one. +- **Tests:** `tests/test_tuldok_log.py`, 8: 6 with the standard library (read back through the reader), and 2 of + `autolog` that need PyTorch, skipped in Tuldok's environment. Run with the lab's interpreter + (`/.venv/bin/python -m unittest tests/test_tuldok_log.py`, PyTorch 2.8.0+cpu, `PYTHONDONTWRITEBYTECODE=1`, + read only, nothing installed): 8 OK on the CPU. The grad norm is checked against the test's own norm taken in a + pre-step hook of its own; the loss against the mean of the losses it saw. + +### T1c, the block + +- **Where.** The block is in the run's drawer, after "Latest progress", read with the drawer (`LabTraining.read` + in `runDrawer`'s load) and built with it (`LabTraining.block`). A failure to read it shows one line in the block, + not a failed drawer. `tabs.js`'s `S.tick` calls `LabTraining.tick()` first on every reading. +- **One chart a series** rather than one chart with a series chooser: series of different scales (loss and learning + rate) are never drawn on one axis. Up to four series and four runs. Runs are told apart by colour and a legend + (swatch, model's short name, start of the run id, state), and the hover tip names each run with its value, step + and time; there are no direct labels at the ends of the lines (the drawer is narrow). The four colours are new + tokens `--run-1` … `--run-4` in `base.css`, light and dark, checked with the dataviz palette validator (lightness, + chroma, colour-blind separation, contrast: all pass in both modes). +- **The overlay chooser** lists the project's other runs that are not queued (the run's own model's first), up to + fifty; runs that logged nothing draw no line but stay in the legend. +- **Smoothing on a log scale** smooths the logarithms, so a falling loss is not pulled up by its early values. A + value of 0 or less is left out on the log scale and a line under the chart says so; the same line says when a + series is reduced (each point a mean of N, the band their range) and when it is smoothed. +- **Histograms**: one strip a tensor for the kind chosen (weights or gradients), 32 bins and at most 120 steps, each + column shaded by the square root of its share of its column's total. The common range over all steps means a + distribution that narrows a lot is drawn in a few bins at the end (visible in the check's gradients); a per-column + range was not built. A strip is read when it comes on screen, and again when histograms were added since. +- **Live updates in place.** A reading asks `training` for each active run in view; new lines ask + `training_series` from the last bucket held, and the charts are redrawn in their canvases; new histogram lines + read again the strips already read; new samples are appended to the strip (the oldest removed past twelve). A + name that was not there before (a validation loss first logged at step 10, the first samples, new tensors) adds + its chooser button or draws its part again (histograms, samples); only a run that had logged nothing before draws + the block's content anew. Texts (where the run is, a chart's caption) are set as the data of their text node, so + a reading adds or removes no node. When the run ends, the page draws the drawer again (as before this phase), + and the block is built again from what is held, without "Reading…" and without reading the series again. +- **The page reads every two seconds only while it knows a build runs** (spec-w4 R1): a build asked for elsewhere + is seen on the next reading, up to fifteen seconds later, and only then is the block read live. The check makes + that reading at once by a return to the window. Opening a run's drawer does not by itself start fast reading. +- **The address** keeps `trWith`, `trSeries`, `trSmooth`, `trLog`, `trX` (`app.js`'s `ADDRESSED`). The chosen + sample name, weights or gradients and "Show all" are kept by the page for the run while it lives, not in the + address. +- **The check** (`tests/browser_project_workspace_training.cjs`, with the stand-in `tests/project_training_stand_in.py`, + plain Python, logging through `tuldok_log` put on the run's `PYTHONPATH` by the recipe's `env`): 7 PASS, run + three times while building and twice at the end. In step 4 the live run (50 steps, 0.25 s each) grew 10 → 18 → + 27 → 35 points across readings with the block, its chart and its strips the same elements and no node added or + removed outside the samples strip; the marker is set once the run has logged every name it will (from its tenth + step), since a first name is drawn by adding its control. +- **Files beyond section 7's list:** `tests/project_training_stand_in.py`; `adapter.js` was not changed (the block + calls `P.call` and keeps its own answers by run, since a running run's answers must not be kept by the adapter). + +### Runs at the end + +Disposable PostgreSQL under `/tmp/claude-1000/t1`, `TULDOK_PROJECT_HOME` and `TULDOK_SETTINGS` there: + +- `PYTHONPATH=tests .venv/bin/python -m unittest discover -s tests -p 'test_tuldok_project_*.py'`: 753 OK (735 + before, plus the 18 of `test_tuldok_project_training`). +- `PYTHONPATH=tests .venv/bin/python -m unittest test_agent_api test_agent_negotiation test_agent_http`: 43 OK, 4 + skipped. +- `tests/test_tuldok_log.py`: 8 OK with the lab's interpreter (PyTorch on the CPU); 6 OK, 2 skipped with Tuldok's. +- Browser: `browser_project_workspace_training.cjs` 7 PASS; unchanged `browser_project_workspace.cjs` 24 PASS, + `browser_project_workspace_fields.cjs` 8 PASS, `browser_project_workspace_still.cjs` 6 PASS (the run drawer + changed). + +### Not verified + +A real training run (nothing was trained; `autolog` was exercised on a tiny model for ten steps on the CPU); the +lab's earlier runs (the converter of `history.json` is deferred and nothing was written into the lab); a metrics +file near the bound of 1,000,000 lines (its memory, about 16 bytes a line and 16 a value, and the first read's +time); bucket sizes above 1 in the page (the check's series are shorter than 800 points; the reader's buckets are +unit-tested); `training_histograms` past `most` in the page; a sample `.npy` of three or more axes in the page; +several parameter groups or the overlay of a run that is itself running; the hover tip in the check (drawn, not +asserted); keyboard order and focus rings beyond the screenshots; a theme changed while the drawer is open (each +theme is loaded); the coding-standards guidance (the Standards Engine answered that its guidance is awaiting +publication, so none was read). From 28c3fb3234d394ebf8f8b454afac1fc59b88f69b Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 19 Nov 2026 05:56:37 -0700 Subject: [PATCH 095/131] docs(plan): phase 1 as built, the check's runs Co-Authored-By: Claude Opus 5.5 --- docs/plans/training-and-curation/spec-t1.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/plans/training-and-curation/spec-t1.md b/docs/plans/training-and-curation/spec-t1.md index 03ce88b7..7da8c0fb 100644 --- a/docs/plans/training-and-curation/spec-t1.md +++ b/docs/plans/training-and-curation/spec-t1.md @@ -255,8 +255,9 @@ What differs from the text above, and what was found while building it. sample name, weights or gradients and "Show all" are kept by the page for the run while it lives, not in the address. - **The check** (`tests/browser_project_workspace_training.cjs`, with the stand-in `tests/project_training_stand_in.py`, - plain Python, logging through `tuldok_log` put on the run's `PYTHONPATH` by the recipe's `env`): 7 PASS, run - three times while building and twice at the end. In step 4 the live run (50 steps, 0.25 s each) grew 10 → 18 → + plain Python, logging through `tuldok_log` put on the run's `PYTHONPATH` by the recipe's `env`): 7 PASS, on + the last two runs (once before its commit, once at the end; the earlier runs failed on the check's own timing and + on the block's first way of adding names, both fixed). In step 4 the live run (50 steps, 0.25 s each) grew 10 → 18 → 27 → 35 points across readings with the block, its chart and its strips the same elements and no node added or removed outside the samples strip; the marker is set once the run has logged every name it will (from its tenth step), since a first name is drawn by adding its control. From bb913102207f59b509ec6da950a3fac584e82855 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 19 Nov 2026 05:58:21 -0700 Subject: [PATCH 096/131] docs(plan): spec-t3, comparing chosen models: differences, intervals, parallel coordinates, the Compare tab Co-Authored-By: Claude Opus 5.5 --- docs/plans/training-and-curation/spec-t3.md | 98 +++++++++++++++++++++ 1 file changed, 98 insertions(+) create mode 100644 docs/plans/training-and-curation/spec-t3.md diff --git a/docs/plans/training-and-curation/spec-t3.md b/docs/plans/training-and-curation/spec-t3.md new file mode 100644 index 00000000..bbf01574 --- /dev/null +++ b/docs/plans/training-and-curation/spec-t3.md @@ -0,0 +1,98 @@ +# Implementation spec: comparing chosen models deeply + +This is phase 3 of [the training and curation plan](plan.md). It follows that plan's rule (Tuldok reads what a project's scripts wrote; nothing of the project's code runs in Tuldok), and it adds no file contract: everything here is read from what Tuldok already holds, the definitions, the per-case values of [the values files](../../contracts/project-folder.md#values-files) and the fields a run kept ([spec-d6.md](../definition-first-projects/spec-d6.md)). The readers follow spec-d1 and spec-d6: standard library only, nothing written, bounded work, an unusable input listed with its reason rather than failing the whole answer. The page follows [spec-w4.md](../definition-first-projects/spec-w4.md): nothing is rebuilt by a timer or a return to the window, and a person's own moves are drawn in place. + +**Owner, 2026-11-19:** "Tuldok already kinda has comparison view for models in the ancestory tree/list, but it would be great if it could compare selected models deeper like also showing output results next to eachother. Im not sure how the GUI would work for that." And: "Parallel coordinates sound very usful for Tuldok." + +**After this phase** the models a person chose (two to four) open a **Compare** tab: one column per model, rows of who each is and what differs between their recipes, their metrics on every benchmark that measures them with a 95 % interval where this machine holds per-case values, where each sits on the frontier, and then their outputs on one case they all kept, the native field, each prediction and each signed error, moved together by one slice control. The Benchmarks tab gains **parallel coordinates** over the benchmark's metrics and the recipe settings that vary between its subjects (a range dragged on an axis keeps the subjects inside it, in the table and in the other charts), and **intervals**: whiskers on the ranking charts and in the table, and a mark on the frontier where two neighbours are not told apart by their per-case values. + +## 1. What differs between recipes + +A recipe's definition is a JSON document. To compare two to four of them, and to put their settings on axes, each document is **flattened** to its leaves: + +- A leaf is `null`, a boolean, a number, a string, or an empty object or list (shown as `{}` and `[]`). An object's keys are joined with `.`; a list's items are `[0]`, `[1]`, …; a key that is not a plain name (holding `.`, `[`, `]`, `"` or a space, or empty) is written `["key"]`. So the lab's learning rate is `run.settings.captures[0].experiment.training.learning_rate`. +- The keys of who a model is and how it is described are not settings: `format`, `kind`, `title`, `description`, `card`, `labels`, `earlier_work` and `compared_with` are left out. `group`, `change` and `derived_from` are compared on their own rows (kinds `group`, `change`, `parent`); the leaves under `run.inputs` are of kind `data`; every other leaf is of kind `setting`. +- **Bounds:** at most 5,000 leaves a document and 32 levels deep (past either, the rest is left out and the document marked `truncated`); a string is compared whole but shown to 200 characters. +- A settings file a recipe names (`run.settings_file`) is not opened: only what the definition holds is compared (doubt: a recipe whose settings live in its file shows none here). + +Two leaves are **the same** when both models have the path and the values are equal as JSON values (`1` and `1.0` are equal; `true` and `1` are not). A path **differs** when any model lacks it or holds another value. The comparison lists every differing path, `group`, `change` and `parent` first, then `data`, then the settings in path order, at most 400 rows (`more` says how many past them), and counts the paths that are the same. + +## 2. Intervals from per-case values + +A summary row of a benchmark (count, mean, median, p10, p90, min, max) made from per-case values (`origin` `values`) can carry an interval; one read from a results file cannot, as the cases are not on this machine. + +- **The cases** of a subject and metric are its held values that are numbers, over every group (the cases the ungrouped summary row is made from), each keyed by its case and group. +- **The resampling** (a percentile bootstrap): the values sorted ascending; a fresh `random.Random(20261119)`; 2,000 resamples, each `rng.choices(values, k=n)` sorted; the six statistics of each resample computed as `results.summarise` computes them (the mean with `math.fsum`, the percentiles by its linear interpolation); the interval of each statistic is the 2.5th and 97.5th percentiles of its 2,000 values, by linear interpolation at `q × 1999`. A subject with fewer than 2 values has no interval. The same seed for every interval makes an answer the same on every reading and lets a test do the arithmetic itself. +- **The difference between two subjects** on a metric and a statistic: when they share at least 2 case keys, *paired*: the shared keys in sorted order, each resample `rng.choices(range(m), k=m)`, the statistic of each side over the drawn keys and their difference (first minus second); otherwise *independent*: each resample draws the first's values then the second's. The interval is taken as above. The difference is **significant** when its interval does not hold zero. +- **The frontier.** For a tradeoff chart that is not grouped, its frontier points (chart_data's, in its order by x) are taken in pairs of neighbours; a pair is compared on both of the chart's metrics with the chart's statistic. A pair is **separated** when both differences are significant; otherwise each of its points is **not separated from** the other. A pair where either side lacks values on either metric is left unknown (null). Grouped tradeoff charts are listed with no pairs (doubt: the cases of one group value would do; not built). +- **Cost.** 2,000 resamples of 128 values take about 25 ms in CPython; a benchmark of 150 subjects, five metrics and 128 cases each takes about 20 s. The intervals of a benchmark are therefore computed outside the service's lock and kept (8 benchmarks, least recently used dropped) while its held values are the same; the page draws the tab first and the intervals when they arrive (section 5.2). + +## 3. Parallel coordinates + +For one benchmark and a statistic, every subject is a line through: + +- **the metric axes,** one per metric of the benchmark: the subject's statistic from its summary row (null when it has none). `positive` says whether every value is above zero, so the page may offer a logarithmic scale. +- **the setting axes:** the subjects' recipes flattened as in section 1 (the identity rows `group` and `change` and the `data` leaves included as settings may vary there too). A path is a candidate when at least two subjects have it and their values are not all the same. It is a **number** axis when every value is a number (not a boolean), and a **category** axis when its values are texts, booleans or a mix, with 2 to 12 distinct values; categories are ordered by their JSON text and a subject's value on the axis is the position of its category. A path with more than 12 distinct non-numeric values is left out. +- **Which settings first.** The candidates are ordered by how strongly they go with the first metric that has at least three values: the absolute Spearman rank correlation (ties given their mean rank) over the subjects that have both, null under three or when either side is constant; then by how many subjects have the path, then by path. At most 48 are answered (`left_out` counts the others). + +The page shows the metrics and the first six settings by default, at most twelve axes at once, with a chooser for the rest. + +## 4. Operations + +Three reads, `inspect`, in the `project_folder` profile and absent from `catalog` (whose digest is unchanged). Nothing new is written to the contract file: these read the definitions and results it already describes. + +| Operation | Arguments | Result | +| --- | --- | --- | +| `model_compare` | `recipes` (2 to 4 distinct recipe references), `statistic` (one of the six, default `median`) | `statistic`, `resamples`, `level`, `seed`; `models`: per recipe `reference`, `title`, `group`, `change`, `derived_from`, `truncated`; `differs`: each `kind`, `path`, `values` (one per model, JSON as held, null where absent), `present` (booleans); `same` (count of paths the same), `more`; `benchmarks`: each benchmark with a subject made from one of the recipes: `benchmark`, `title`, `metrics` (`id`, `title`, `units`, `better`), `models` (one per recipe: null, or its `subject`, `title`, `per_case`, and `values` by metric: `value`, `count`, `low`, `high`), `frontiers` (per tradeoff chart: `chart`, `title`, `statistic`, `metric`, `metric_x`, `grouped`, `models`: one per recipe, null when not drawn, else `on` (on the frontier), `x`, `value`, `not_separated_from` (subject names)) | +| `benchmark_axes` | `benchmark`, `statistic` (default `median`) | `benchmark`, `statistic`, `metrics` (`id`, `title`, `units`, `better`, `positive`, `low`, `high`), `settings` (`path`, `kind` `number` or `category`, `categories`, `low`, `high`, `count`, `distinct`, `association`), `left_out`, `subjects` (`subject`, `title`, `recipe`, `metrics` by id, `settings` by path) | +| `intervals` | `benchmark` | `benchmark`, `resamples`, `level`, `seed`, `intervals`: per subject and metric with values, `subject`, `metric`, `count`, and for each statistic `[low, high]` (or null); `frontiers`: per tradeoff chart `chart`, `title`, `statistic`, `metric`, `metric_x`, `grouped`, `pairs` (`subjects` [a, b], `metric` and `metric_x` each `low`, `high`, `paired`, `count`, `significant`, or null; `separated`), `not_separated` (subject names) | + +`model_compare` refuses `not-found` for a recipe that is not defined, `invalid` for repeated ones; the values of `model_compare` are those of `intervals` for the subjects of its recipes (the frontier pairs only those that touch one of them). The three are reads of the database and the definitions: their answer is computed from what the project holds, under the service's lock for the reading and, for `intervals` and `model_compare`, outside it for the resampling. + +## 5. The page + +### 5.1 The Compare tab + +The compare set (the page's `cmp`, kept in the address as before) may now hold **four** models; choosing another benchmark no longer empties it, since it is no longer only of one benchmark. It is filled from three places: the boxes of the Benchmarks table, **Compare** in a model's drawer on the Benchmarks tab, and **Compare** in a model's drawer on the **Map** (new). Each drawer with Compare also has **Open Compare** once the set holds two. + +**Why a tab, not a view inside Benchmarks or a drawer:** the set is the page's, not one benchmark's; one column a model needs the full width (the drawer is 420 px); and a tab has an address (`#compare`), so a comparison can be reloaded and shared. The tab is after Benchmarks. + +The tab, for the models of the set that are recipes on the map (a benchmark subject made from no recipe is named and left out): + +- **Head:** the set as chips with × and Clear, the statistic (shared with Benchmarks), and, under two models, a sentence on how to choose them. +- **The table,** one column per model (its name opens its drawer, with Compare in it): *Who* (group, kind of change, derives from, state, trained); *What differs* (section 1: each differing path with each model's value; absent written as "—"; the count of the same); then per benchmark, its metrics, each cell the statistic, its interval as `low – high` and the number of cases, the best of a row marked; and for each tradeoff chart, the frontier row: "on the frontier", "on the frontier, not separated from …", "off the frontier", or "—". The table scrolls sideways in its own box when narrow. +- **Outputs.** The cases the models' runs kept (spec-d6 `fields` of every current product of each model), matched by name (the probe's member id, or "case N"); a case is offered when at least two models kept it, comparable and of the same shape (a model of another shape is said so in its column). A select chooses it (the most shared first). One control for all columns: the axis cut across, the position (and the fourth axis), "Remove the mean". Then a grid, a column per model and three rows, Native, Predicted and Signed error; Native and Predicted of every column on one sequential scale (over every column's `range`), the errors on one diverging scale (±the largest `error_limit`), a colour bar for each row with its ends; under each column the whole-field figures (relative L2, mean-free relative L2, RMSE). Hover shows the cell's position and the three values of that column. A move asks `field_compare` of every column at once (one request each, at most one round in flight, the latest wins) and draws the canvases again in place. The case, axis, position and mean option are kept in the address (`cmpCase`, `cmpAxis`, `cmpIndex`, `cmpMeanFree`). +- Read with the tab and put in place in one step (tabs.js's `paint`); the outputs' first slices are read with it. + +### 5.2 Benchmarks: parallel coordinates and intervals + +- **Settings and metrics** (parallel coordinates), after the charts, when the benchmark has two subjects or more: an SVG of one vertical axis per chosen axis, one line per subject (in the kind of change's colour, as the charts' points), each axis named with its ends (a category axis with its categories). Under it, the chooser: the metric axes and the 48 settings (each with its association), as toggles, at most twelve on. Each axis has buttons to move it left and right, and a metric axis whose values are all positive a "log" toggle. **Brushing:** a range dragged on an axis keeps the lines whose value on it lies inside (a line with no value there is out); ranges on several axes all apply; a range is cleared by a click on the axis without a drag, and all by "Clear ranges". The lines out of range are faint; the subjects table hides their rows and says how many are shown; the charts above draw their points faint. All of this is set in place (no reading, no rebuild of the tab); the order, the axes on, the log scales and the ranges are the tab's settings, kept when the tab is drawn again. +- **Intervals:** read after the tab is put in place (section 2's cost); when they arrive the tab is drawn again in place with them (its scroll, focus and brushing kept). The ranking charts get a whisker from `low` to `high` of the chart's statistic for each subject with an interval; the table's metric cells a second line `low – high` of the tab's statistic; the tradeoff chart a dashed ring round each frontier point not separated from a neighbour, a tip line naming that neighbour, and a line of the legend. A line under the charts says how the intervals are made (2,000 resamples, seed, percentile 95 %). + +## 6. Slices + +| | Slice | Files | +| --- | --- | --- | +| T3a | Flattening, the differences, the intervals, the axes; the three operations | `tuldok_project/comparing.py` (new), `operations.py`, `service.py`, `tests/test_tuldok_project_comparing.py` (new), the count of the table's rows in `tests/test_tuldok_project_service.py` and its read test | +| T3b | The Compare tab | `static/project-workspace/compare.js` (new), `compare.css` (new), `fields.js` (its helpers shared), `tabs.js` (the limit of four, Compare in drawers), `screens.js` (Compare on the Map's drawer), `app.js` (the tab, the limit, the address), `adapter.js` (a kept answer peeked), `static/project-workspace.html`, `app.py` (the asset list) | +| T3c | Parallel coordinates and intervals on Benchmarks | `static/project-workspace/parallel.js` (new), `charts.js` (whiskers, the ring), `tabs.js`, `compare.css`; `tests/browser_project_workspace_compare.cjs` (new) and its fixture `tests/project_compare_browser_fixture.py` (new) | + +## 7. Tests + +**T3a, `tests/test_tuldok_project_comparing.py`:** flattening (nested objects and lists, quoted keys, empty containers, the identity keys left out, the bounds lowered for the test, `1` equal to `1.0` and not to `true`); the differences of three documents (each kind, an absent path, the order, `more`); the bootstrap against the test's own arithmetic (its own seeded `random.Random`, choices and percentiles: every statistic's interval equal), fewer than 2 values (none), the paired and the independent difference, significance; the axes on documents the test writes (a number axis, a category axis with its positions, a constant path left out, a path of 13 texts left out, the association against a Spearman correlation the test computes, the order, `left_out` with the bound lowered); the three operations on a project with per-case values imported (`model_compare` of three recipes: differences, values with intervals equal to the module's, frontier rows; `intervals` with frontier pairs; `benchmark_axes`); refusals (an unknown recipe, a repeated one, an unknown benchmark); the three in `project_folder` and not in `catalog`, the digest unchanged. + +**T3b and T3c, `tests/browser_project_workspace_compare.cjs`,** on the minimal fixture with three recipes of earlier work whose adopted products keep fields of one shared case (and one more case kept by two of them), a benchmark whose subjects they are with per-case values imported for each and a tradeoff and a ranking chart, and recipes whose settings vary (a number, a category): + +1. The Map drawer's Compare adds models; Open Compare shows the tab with three columns, the differing settings (and not the same ones), the metrics with intervals equal to `intervals`' answer, and the frontier rows. +2. Outputs: the shared case chosen, nine panels drawn; one slider move asks `field_compare` three times and redraws every canvas in place (the rest of the tab the same elements); the Native row of every column on one scale (the same colour where the fields are equal). +3. Benchmarks: parallel coordinates with the metric and setting axes; a range dragged on the metric axis hides the table rows outside it and dims the charts' points, with no request; reordering and the log toggle redraw in place; clearing shows every row again. +4. Intervals: the ranking chart has whiskers, the table has `low – high` lines, the tradeoff chart marks the frontier points the answer says are not separated. +5. Light and dark, 1440 and 390 wide: no sideways overflow of the page's main area outside the tables' own scrolling boxes, no blank canvas, no script error, no failed request. + +**Regressions:** the project suite, the agent interface tests, `browser_project_workspace.cjs`, `_fields.cjs` and `_structure.cjs`. + +**On the lab folder (acceptance, read only):** parallel coordinates over the 150-pressure-fits benchmark's 150 subjects (definitions and the results file only) filter to the best errors and show their settings; three earlier pressure models with kept fields compared on one case (the owner, on his database). + +## 8. Out of scope + +Running anything to make a prediction; comparing more than four models; intervals for grouped rows (by horizon, say) and for results read from a file; multiple-comparison corrections; settings read from a recipe's settings file; brushing on the Map; a hyperparameter search's own view (phase 7 reuses this). From b4b15d765e4033a3ef0d7501e38709febbfa8986 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 19 Nov 2026 06:03:03 -0700 Subject: [PATCH 097/131] feat(project): model_compare, benchmark_axes and intervals: what differs, bootstrap intervals, parallel coordinates data comparing.py flattens recipe definitions to leaf paths, lists what differs between two to four of them, makes seeded percentile-bootstrap intervals (2,000 resamples) from the per-case values held here and compares frontier neighbours with paired differences, and puts a benchmark's subjects on metric and setting axes ordered by their rank correlation with the first metric. Co-Authored-By: Claude Opus 5.5 --- docs/plans/training-and-curation/spec-t3.md | 2 +- tests/test_tuldok_project_comparing.py | 396 +++++++++++++++ tests/test_tuldok_project_service.py | 4 +- tuldok_project/comparing.py | 527 ++++++++++++++++++++ tuldok_project/operations.py | 19 +- tuldok_project/service.py | 29 +- 6 files changed, 969 insertions(+), 8 deletions(-) create mode 100644 tests/test_tuldok_project_comparing.py create mode 100644 tuldok_project/comparing.py diff --git a/docs/plans/training-and-curation/spec-t3.md b/docs/plans/training-and-curation/spec-t3.md index bbf01574..31757dea 100644 --- a/docs/plans/training-and-curation/spec-t3.md +++ b/docs/plans/training-and-curation/spec-t3.md @@ -32,7 +32,7 @@ A summary row of a benchmark (count, mean, median, p10, p90, min, max) made from For one benchmark and a statistic, every subject is a line through: - **the metric axes,** one per metric of the benchmark: the subject's statistic from its summary row (null when it has none). `positive` says whether every value is above zero, so the page may offer a logarithmic scale. -- **the setting axes:** the subjects' recipes flattened as in section 1 (the identity rows `group` and `change` and the `data` leaves included as settings may vary there too). A path is a candidate when at least two subjects have it and their values are not all the same. It is a **number** axis when every value is a number (not a boolean), and a **category** axis when its values are texts, booleans or a mix, with 2 to 12 distinct values; categories are ordered by their JSON text and a subject's value on the axis is the position of its category. A path with more than 12 distinct non-numeric values is left out. +- **the setting axes:** the subjects' recipes flattened as in section 1 (the identity rows `group` and `change` and the `data` leaves included as settings may vary there too). A path is a candidate when at least two subjects have it and their values are not all the same. It is a **number** axis when every value is a number (not a boolean), and a **category** axis when its values are texts, booleans or a mix, with 2 to 12 distinct values; categories are ordered numbers first (by value), then `false` and `true`, then texts, then the rest, and a subject's value on the axis is the position of its category. A path with more than 12 distinct non-numeric values is left out. - **Which settings first.** The candidates are ordered by how strongly they go with the first metric that has at least three values: the absolute Spearman rank correlation (ties given their mean rank) over the subjects that have both, null under three or when either side is constant; then by how many subjects have the path, then by path. At most 48 are answered (`left_out` counts the others). The page shows the metrics and the first six settings by default, at most twelve axes at once, with a chooser for the rest. diff --git a/tests/test_tuldok_project_comparing.py b/tests/test_tuldok_project_comparing.py new file mode 100644 index 00000000..3bdc7b9f --- /dev/null +++ b/tests/test_tuldok_project_comparing.py @@ -0,0 +1,396 @@ +"""Comparing chosen models (docs/plans/training-and-curation/spec-t3.md sections 1 to 4). + +Flattening, the differences, the bootstrap and the axes are tested on data the +tests write, against arithmetic the tests do themselves (their own seeded +random.Random, choices and percentiles). The three operations run on a copy of +tests/fixtures/tuldok_project/minimal with its per-case values imported, when +TULDOK_DATABASE_URL names a disposable cluster. +""" +import hashlib +import json +import math +import os +from pathlib import Path +import random +import sys +import unittest +from unittest import mock + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) +sys.path.insert(0, str(Path(__file__).resolve().parent)) + +import agent_api # noqa: E402 +from tuldok_project import comparing, local, operations # noqa: E402 +from tuldok_project.service import Service # noqa: E402 +from tuldok_project.store import ProjectError # noqa: E402 +from test_tuldok_project_store import StoreCase # noqa: E402 + +DATABASE = os.environ.get('TULDOK_DATABASE_URL') +COMPARING = ('model_compare', 'benchmark_axes', 'intervals') +OWNER = {'actor_id': 'owner-1', 'kind': 'owner', 'label': 'The owner', + 'scopes': ['inspect', 'edit', 'execute', 'cancel', 'approve-execution']} + + +# ------------------------------------------------------------ the test's own arithmetic + +def percentile(ordered, q): + """numpy's 'linear' percentile, written again: position q (n − 1), interpolated.""" + position = q * (len(ordered) - 1) + low = int(position) + if low + 1 >= len(ordered): + return ordered[-1] + return ordered[low] * (1 - (position - low)) + ordered[low + 1] * (position - low) + + +def stat(values, name): + ordered = sorted(values) + return {'mean': lambda: math.fsum(ordered) / len(ordered), 'min': lambda: ordered[0], 'max': lambda: ordered[-1], + 'median': lambda: percentile(ordered, 0.5), 'p10': lambda: percentile(ordered, 0.1), + 'p90': lambda: percentile(ordered, 0.9)}[name]() + + +def bootstrap(values, name, resamples=2000): + rng, ordered = random.Random(20261119), sorted(values) + draws = sorted(stat(rng.choices(ordered, k=len(ordered)), name) for _ in range(resamples)) + return [percentile(draws, 0.025), percentile(draws, 0.975)] + + +def close(test, got, want, places=12): + test.assertEqual(len(got), len(want)) + for a, b in zip(got, want): + test.assertAlmostEqual(a, b, places=places) + + +class Flattening(unittest.TestCase): + + def test_leaves_paths_and_identity_left_out(self): + document = {'format': 'tuldok_definition_v1', 'kind': 'recipe', 'title': 'T', 'description': 'D', + 'labels': {'short': 'X'}, 'earlier_work': {}, 'compared_with': [], 'card': 'notes/x.md', + 'group': 'g', 'change': 'refinement', 'derived_from': 'recipes/a', + 'run': {'settings': {'lr': 0.001, 'layers': [8, 16], 'opt': {'name': 'adam', 'betas': []}, + 'a.b': 1, '': 2, 'with space': {'x': True}, 'empty': {}}, + 'inputs': {'training': 'datasets/w'}}} + flat, truncated = comparing.flatten(document) + self.assertFalse(truncated) + self.assertEqual(flat, { + 'group': 'g', 'change': 'refinement', 'derived_from': 'recipes/a', + 'run.settings.lr': 0.001, 'run.settings.layers[0]': 8, 'run.settings.layers[1]': 16, + 'run.settings.opt.name': 'adam', 'run.settings.opt.betas': [], 'run.settings["a.b"]': 1, + 'run.settings[""]': 2, 'run.settings["with space"].x': True, 'run.settings.empty': {}, + 'run.inputs.training': 'datasets/w'}) + self.assertEqual([comparing.kind_of(path) for path in ('group', 'change', 'derived_from', + 'run.inputs.training', 'run.settings.lr')], + ['group', 'change', 'parent', 'data', 'setting']) + + def test_bounds(self): + document = {'run': {'settings': {f'k{i}': i for i in range(10)}}} + flat, truncated = comparing.flatten(document, leaves=4) + self.assertEqual((len(flat), truncated), (4, True)) + deep = {'a': {'b': {'c': {'d': 1}}}, 'e': 2} + flat, truncated = comparing.flatten(deep, depth=3) + self.assertEqual((flat, truncated), ({'e': 2}, True)) + self.assertEqual(comparing.flatten(deep, depth=4), ({'a.b.c.d': 1, 'e': 2}, False)) + + +class Differences(unittest.TestCase): + + def test_what_differs_in_its_order_and_what_is_the_same(self): + a = {'group': 'g', 'change': 'refinement', 'run': {'inputs': {'t': 'datasets/a'}, + 'settings': {'lr': 1, 'n': 2, 'flag': True, 'x10': 1, + 'x2': 1, 'name': 'adam'}}} + b = {'group': 'g', 'change': 'architecture', 'derived_from': 'recipes/a', + 'run': {'inputs': {'t': 'datasets/b'}, 'settings': {'lr': 1.0, 'n': 3, 'flag': 1, 'x10': 2, 'x2': 2, + 'name': 'adam'}}} + c = {'group': 'g', 'change': 'refinement', 'run': {'inputs': {'t': 'datasets/a'}, + 'settings': {'lr': 1, 'n': 2, 'flag': True, 'x10': 1, + 'x2': 1, 'name': 'adam'}}} + got = comparing.differences([a, b, c]) + self.assertEqual([(row['kind'], row['path']) for row in got['differs']], + [('change', 'change'), ('parent', 'derived_from'), ('data', 'run.inputs.t'), + ('setting', 'run.settings.flag'), ('setting', 'run.settings.n'), + ('setting', 'run.settings.x2'), ('setting', 'run.settings.x10')]) + parent = got['differs'][1] + self.assertEqual((parent['values'], parent['present']), ([None, 'recipes/a', None], [False, True, False])) + self.assertEqual(got['differs'][3]['values'], [True, 1, True]) # true is not 1 + self.assertEqual(got['same'], 3) # group, lr (1 is 1.0) and name + self.assertEqual(got['more'], 0) + limited = comparing.differences([a, b, c], most=2) + self.assertEqual((len(limited['differs']), limited['more']), (2, 5)) + long = comparing.differences([{'note': 'x' * 300}, {'note': 'y'}]) + self.assertEqual(len(long['differs'][0]['values'][0]), comparing.SHOWN) + + +class Bootstrap(unittest.TestCase): + VALUES = [0.31, 0.12, 0.5, 0.44, 0.27, 0.9, 0.05, 0.61, 0.33, 0.29, 0.71] + + def test_every_statistic_against_the_tests_own_resampling(self): + got = comparing.interval_set(self.VALUES) + for name in comparing.STATISTICS: + with self.subTest(name): + close(self, got[name], bootstrap(self.VALUES, name)) + self.assertLessEqual(got[name][0], got[name][1]) + self.assertEqual(comparing.interval_set(self.VALUES), got) # the same on every reading + self.assertEqual(comparing.interval_set(list(reversed(self.VALUES))), got) # sorted first + self.assertLessEqual(got['median'][0], stat(self.VALUES, 'median')) + self.assertGreaterEqual(got['median'][1], stat(self.VALUES, 'median')) + + def test_fewer_than_two_values_have_none(self): + self.assertIsNone(comparing.interval_set([0.5])) + self.assertIsNone(comparing.interval_set([])) + self.assertEqual(comparing.interval_set([2.0, 2.0])['mean'], [2.0, 2.0]) + + def test_paired_difference(self): + first = {('c1', ''): 1.0, ('c2', ''): 2.0, ('c3', ''): 3.0, ('c4', ''): 4.0, ('c5', ''): 5.0} + second = {key: value - 0.5 + 0.01 * i for i, (key, value) in enumerate(sorted(first.items()))} + second[('only', '')] = 99.0 + got = comparing.difference(first, second, 'median') + keys = sorted(set(first) & set(second)) + a, b = [first[k] for k in keys], [second[k] for k in keys] + rng, draws = random.Random(20261119), [] + for _ in range(2000): + drawn = rng.choices(range(len(keys)), k=len(keys)) + draws.append(stat([a[i] for i in drawn], 'median') - stat([b[i] for i in drawn], 'median')) + draws.sort() + want = [percentile(draws, 0.025), percentile(draws, 0.975)] + close(self, [got['low'], got['high']], want) + self.assertEqual((got['paired'], got['count']), (True, 5)) + self.assertTrue(got['significant']) # every case of the first is about 0.5 above the second + + def test_independent_difference_and_not_significant(self): + first = {('a', ''): 1.0, ('b', ''): 2.0, ('c', ''): 3.0} + second = {('x', ''): 1.5, ('y', ''): 2.5, ('z', ''): 2.0, ('w', ''): 3.5} + got = comparing.difference(first, second, 'mean') + rng, draws = random.Random(20261119), [] + av, bv = sorted(first.values()), sorted(second.values()) + for _ in range(2000): + draws.append(stat(rng.choices(av, k=3), 'mean') - stat(rng.choices(bv, k=4), 'mean')) + draws.sort() + close(self, [got['low'], got['high']], [percentile(draws, 0.025), percentile(draws, 0.975)]) + self.assertEqual((got['paired'], got['count'], got['significant']), (False, 3, False)) + self.assertIsNone(comparing.difference({('a', ''): 1.0}, second, 'mean')) + + +class FrontierPairs(unittest.TestCase): + + def test_neighbours_compared_on_both_metrics(self): + def point(subject, x, value, frontier=True): + return {'subject': subject, 'x': x, 'value': value, 'frontier': frontier} + chart = {'chart': 'charts/t', 'title': 'T', 'statistic': 'median', 'group': None, + 'metric': {'id': 'err'}, 'metric_x': {'id': 'ms'}, + 'series': [{'group': '', 'points': [point('a', 1, 0.9), point('off', 1.5, 0.95, False), + point('b', 2, 0.5), point('c', 2.1, 0.49)]}]} + cases = [('k%d' % i, '') for i in range(8)] + held = {('a', 'ms'): {k: 1.0 + 0.01 * i for i, k in enumerate(cases)}, + ('a', 'err'): {k: 0.9 + 0.01 * i for i, k in enumerate(cases)}, + ('b', 'ms'): {k: 2.0 + 0.01 * i for i, k in enumerate(cases)}, + ('b', 'err'): {k: 0.5 + 0.01 * i for i, k in enumerate(cases)}, + # c is b again, a hair better and a hair slower on alternate cases: not told apart from b. + ('c', 'ms'): {k: 2.0 + 0.01 * i + (0.02 if i % 2 else -0.02) for i, k in enumerate(cases)}, + ('c', 'err'): {k: 0.5 + 0.01 * i + (-0.02 if i % 2 else 0.02) for i, k in enumerate(cases)}} + pairs = comparing._frontier_pairs(chart, held) + self.assertEqual([pair['subjects'] for pair in pairs], [['a', 'b'], ['b', 'c']]) + self.assertEqual(pairs[0]['metric'], comparing.difference(held['a', 'err'], held['b', 'err'], 'median')) + self.assertEqual((pairs[0]['separated'], pairs[1]['separated']), (True, False)) + self.assertEqual(comparing._frontier_pairs(chart, held, touching={'a'})[0]['subjects'], ['a', 'b']) + self.assertEqual(len(comparing._frontier_pairs(chart, held, touching={'c'})), 1) + del held['c', 'ms'] + self.assertIsNone(comparing._frontier_pairs(chart, held)[1]['separated']) + self.assertEqual(comparing._frontier_pairs({**chart, 'group': 'horizon'}, held), []) + + +class Axes(unittest.TestCase): + + def gathered(self, recipes, metric_values): + class Row: + def __init__(self, value): + self.count, self.median, self.mean = 4, value, value + + class Stored: + def __init__(self, value): + self.row, self.origin = Row(value), 'file' + + subjects = [{'name': f's{i}', 'title': f'S{i}', 'recipe': f'recipes/r{i}'} for i in range(len(recipes))] + summaries = {(f's{i}', 'err'): Stored(value) for i, value in enumerate(metric_values) if value is not None} + return {'benchmark': 'b', 'metrics': [{'id': 'err', 'title': 'Error', 'units': '1', 'better': 'lower'}], + 'subjects': subjects, 'summaries': summaries, + 'recipes': {f'recipes/r{i}': document for i, document in enumerate(recipes)}} + + def test_number_and_category_axes_and_their_order(self): + recipes, errors = [], [0.5, 0.4, 0.3, 0.2, 0.1, None] + for i in range(6): + recipes.append({'change': ['refinement', 'architecture'][i % 2], + 'run': {'settings': {'width': 8 * (i + 1), 'seed': [3, 1, 4, 1, 5, 9][i], 'constant': 7, + 'opt': ['adam', 'sgd', 'adam', 'sgd', 'adam', 'sgd'][i], + 'tag': f'run-{i}', 'flag': i > 2}}}) + recipes[5]['run']['settings']['width'] = 'wide' # a mix of texts and numbers: a category + got = comparing.benchmark_axes(self.gathered(recipes, errors)) + axes = {axis['path']: axis for axis in got['settings']} + self.assertNotIn('run.settings.constant', axes) # the same everywhere + self.assertIn('run.settings.tag', axes) # 6 texts are a category + width = axes['run.settings.width'] + self.assertEqual((width['kind'], width['categories']), ('category', [8, 16, 24, 32, 40, 'wide'])) + seed = axes['run.settings.seed'] + self.assertEqual((seed['kind'], seed['low'], seed['high'], seed['distinct'], seed['count']), + ('number', 1, 9, 5, 6)) + xs, ys = [3, 1, 4, 1, 5], [0.5, 0.4, 0.3, 0.2, 0.1] # s5 has no error + self.assertAlmostEqual(seed['association'], spearman(xs, ys)) + flag = axes['run.settings.flag'] + self.assertEqual((flag['kind'], flag['categories']), ('category', [False, True])) + self.assertAlmostEqual(flag['association'], spearman([0, 0, 0, 1, 1], ys)) + order = [abs(axis['association']) for axis in got['settings'] if axis['association'] is not None] + self.assertEqual(order, sorted(order, reverse=True)) + self.assertEqual(got['subjects'][1]['settings']['run.settings.opt'], 1) # sgd, second category + self.assertEqual(got['subjects'][5]['metrics'], {'err': None}) + self.assertEqual(got['metrics'][0]['positive'], True) + self.assertEqual((got['metrics'][0]['low'], got['metrics'][0]['high']), (0.1, 0.5)) + # Thirteen distinct texts are left out; a bound on the axes counts the others in left_out. + recipes13 = [{'run': {'settings': {'name': f'n{i}', 'x': i}}} for i in range(13)] + got13 = comparing.benchmark_axes(self.gathered(recipes13, [float(i) for i in range(13)])) + self.assertEqual([axis['path'] for axis in got13['settings']], ['run.settings.x']) + self.assertEqual(comparing.benchmark_axes(self.gathered(recipes, errors), most=2)['left_out'], + len(got['settings']) - 2) + + +def spearman(xs, ys): + def ranks(values): + out = [] + for value in values: + below = sum(1 for other in values if other < value) + equal = sum(1 for other in values if other == value) + out.append(below + (equal + 1) / 2) + return out + rx, ry = ranks(xs), ranks(ys) + mx, my = sum(rx) / len(rx), sum(ry) / len(ry) + sxy = sum((a - mx) * (b - my) for a, b in zip(rx, ry)) + return sxy / math.sqrt(sum((a - mx) ** 2 for a in rx) * sum((b - my) ** 2 for b in ry)) + + +# ------------------------------------------------------------ on a project + +@unittest.skipUnless(DATABASE, 'TULDOK_DATABASE_URL is not set; database tests need a disposable cluster.') +class OnAProject(StoreCase): + """The minimal fixture: benchmark rollout of three recipes, a tradeoff chart speed-accuracy, values imported.""" + + def setUp(self): + super().setUp() + project = self.open() + self.values = {} + for path in sorted((self.base / 'values').glob('*.json')): + text = path.read_text(encoding='utf-8') + project.import_values(text) + document = json.loads(text) + for item in document['values']: + if item['value'] is not None: + group = ';'.join(f'{k}={v}' for k, v in sorted((item.get('group') or {}).items())) + self.values.setdefault((document['subject'], item['metric']), {})[item['case'], group] = \ + item['value'] + self.close(project) + patcher = mock.patch.dict(os.environ, {local.HOME_VARIABLE: str(self.temporary / 'home'), + local.SETTINGS_VARIABLE: str(self.temporary / 'settings.json')}) + patcher.start() + self.addCleanup(patcher.stop) + self.service = Service(self.folder) + self.addCleanup(self.service.close) + + def call(self, name, **arguments): + result = self.service.call(name, arguments, OWNER) + json.dumps(result, allow_nan=False) + return result + + def test_intervals_and_the_frontier(self): + got = self.call('intervals', benchmark='benchmarks/rollout') + self.assertEqual((got['resamples'], got['level'], got['seed']), (2000, 0.95, 20261119)) + rows = {(row['subject'], row['metric']): row for row in got['intervals']} + self.assertEqual(set(rows), set(self.values)) + for key, cases in self.values.items(): + with self.subTest(key): + self.assertEqual(rows[key]['count'], len(cases)) + for name in ('median', 'mean', 'p90'): + close(self, rows[key][name], bootstrap(list(cases.values()), name)) + [front] = got['frontiers'] + self.assertEqual((front['chart'], front['statistic'], front['grouped']), ('charts/speed-accuracy', 'median', + False)) + # The pairs are the frontier's neighbours as chart_data orders them. + with self.opened_project() as project: + from tuldok_project import charts + data = charts.chart_data(project, 'charts/speed-accuracy') + on = [point['subject'] for point in data['series'][0]['points'] if point['frontier']] + self.assertEqual(len(front['pairs']), max(0, len(on) - 1)) + for pair, (a, b) in zip(front['pairs'], zip(on, on[1:])): + self.assertEqual(pair['subjects'], [a, b]) + for key, metric in (('metric', 'rmse'), ('metric_x', 'seconds')): + want = comparing.difference(self.values[a, metric], self.values[b, metric], 'median') + self.assertEqual(pair[key], want) + apart = sorted({s for pair in front['pairs'] if pair['separated'] is False for s in pair['subjects']}) + self.assertEqual(front['not_separated'], apart) + with self.assertRaises(ProjectError) as caught: + self.service.call('intervals', {'benchmark': 'nothing'}, OWNER) + self.assertEqual(caught.exception.code, 'not-found') + + def opened_project(self): + return self.service._open() + + def test_model_compare(self): + recipes = ['recipes/stepper-k2', 'recipes/stepper-k1', 'recipes/early-fit'] + got = self.call('model_compare', recipes=recipes, statistic='mean') + self.assertEqual([model['reference'] for model in got['models']], recipes) + self.assertEqual([model['change'] for model in got['models']], + ['refinement', 'training-policy', 'architecture']) + kinds = {row['path']: row['kind'] for row in got['differs']} + self.assertEqual(kinds['change'], 'change') + self.assertEqual(kinds['derived_from'], 'parent') + self.assertEqual(kinds['run.inputs.start.from'], 'data') + self.assertEqual(kinds['run.settings.learning_rate'], 'setting') + self.assertNotIn('model', kinds) # all three are models/stepper + [bench] = got['benchmarks'] + self.assertEqual(bench['benchmark'], 'rollout') + self.assertEqual([column['subject'] for column in bench['models']], ['stepper-k2', 'stepper-k1', 'early-fit']) + k2 = bench['models'][0]['values']['rmse'] + cases = list(self.values['stepper-k2', 'rmse'].values()) + self.assertAlmostEqual(k2['value'], math.fsum(cases) / len(cases)) + close(self, [k2['low'], k2['high']], bootstrap(cases, 'mean')) + self.assertTrue(bench['models'][0]['per_case']) + [front] = bench['frontiers'] + flags = [row['on'] if row else None for row in front['models']] + with self.opened_project() as project: + from tuldok_project import charts + data = charts.chart_data(project, 'charts/speed-accuracy') + points = {point['subject']: point['frontier'] for point in data['series'][0]['points']} + self.assertEqual(flags, [points.get(s) for s in ('stepper-k2', 'stepper-k1', 'early-fit')]) + refused = [] + for arguments in ({'recipes': ['recipes/stepper-k1', 'recipes/stepper-k1']}, + {'recipes': ['recipes/stepper-k1', 'recipes/none']}, {'recipes': ['recipes/stepper-k1']}, + {'recipes': recipes, 'statistic': 'mode'}): + with self.assertRaises(ProjectError) as caught: + self.service.call('model_compare', arguments, OWNER) + refused.append(caught.exception.code) + self.assertEqual(refused, ['invalid', 'not-found', 'invalid', 'invalid']) + + def test_benchmark_axes(self): + got = self.call('benchmark_axes', benchmark='rollout') + self.assertEqual([metric['id'] for metric in got['metrics']], ['rmse', 'seconds']) + self.assertEqual([row['subject'] for row in got['subjects']], ['stepper-k1', 'stepper-k2', 'early-fit']) + axes = {axis['path']: axis for axis in got['settings']} + self.assertEqual(axes['change']['categories'], ['architecture', 'refinement', 'training-policy']) + self.assertEqual([row['settings']['change'] for row in got['subjects']], [2, 1, 0]) + with self.assertRaises(ProjectError) as caught: + self.service.call('benchmark_axes', {'benchmark': 'nothing'}, OWNER) + self.assertEqual(caught.exception.code, 'not-found') + + +class Published(unittest.TestCase): + + def test_the_three_are_in_the_project_folder_profile_and_not_in_the_catalog(self): + for name in COMPARING: + operation = operations.by_name(name) + self.assertEqual((operation.who, operation.mutation), ('inspect', False)) + folder = {item['id'] for item in agent_api.capabilities('b' * 32, profile='project_folder')['operations']} + catalog = agent_api.capabilities('b' * 32) + self.assertTrue({'project.' + name for name in COMPARING} <= folder) + self.assertFalse({'project.' + name for name in COMPARING} & {item['id'] for item in catalog['operations']}) + self.assertEqual((len(catalog['operations']), hashlib.sha256(agent_api.encoded(catalog)).hexdigest()), + (110, 'ad5cc7ac91646b39b7a20b9dfca5ec79ed96ded4b5e36732fcf1145f1cc24460')) + + +if __name__ == '__main__': + unittest.main() diff --git a/tests/test_tuldok_project_service.py b/tests/test_tuldok_project_service.py index 7a84ddad..2681ecca 100644 --- a/tests/test_tuldok_project_service.py +++ b/tests/test_tuldok_project_service.py @@ -48,7 +48,7 @@ class Table(unittest.TestCase): def test_every_operation_is_declared_once(self): names = [operation.name for operation in operations.OPERATIONS] - self.assertEqual(len(names), 64) # the rows of spec-m7.md section 2, of section 2 of spec-w1.md and spec-w3.md, of section 3 of spec-d1.md and spec-d2.md, of section 5 of spec-d4.md, of sections 2 and 4 of spec-d5.md, of section 2 of spec-d6.md, and of section 3 of spec-t2.md + self.assertEqual(len(names), 67) # the rows of spec-m7.md section 2, of section 2 of spec-w1.md and spec-w3.md, of section 3 of spec-d1.md and spec-d2.md, of section 5 of spec-d4.md, of sections 2 and 4 of spec-d5.md, of section 2 of spec-d6.md, of section 3 of spec-t2.md, and of section 4 of spec-t3.md self.assertEqual(len(set(names)), len(names)) for name in REQUEST_OPERATIONS: self.assertIsNotNone(operations.by_name(name)) @@ -217,6 +217,8 @@ def test_every_read(self): 'fields': {'run': run_id}, 'field_compare': {'run': run_id, 'entry': 0, 'case': 0}, 'model_graph': {'run': run_id}, 'model_graph_overlay': {'run': run_id, 'kind': 'parameters'}, 'model_graph_compare': {'run': run_id, 'other_run': run_id}, + 'model_compare': {'recipes': ['recipes/fit-a', 'recipes/fit-b']}, 'benchmark_axes': {'benchmark': 'score'}, + 'intervals': {'benchmark': 'benchmarks/score'}, 'annotation_tasks': {}, 'annotated_records': {'task': 'none-here'}, 'annotation': {'task': 'none-here', 'record': 'r1'}, 'endpoint': {}, 'find_endpoints': {}, 'suggestion_models': {'task': 'none-here'}, diff --git a/tuldok_project/comparing.py b/tuldok_project/comparing.py new file mode 100644 index 00000000..d32e21af --- /dev/null +++ b/tuldok_project/comparing.py @@ -0,0 +1,527 @@ +"""Comparing chosen models: what differs between recipes, intervals from per-case values, parallel coordinates. + +Owns sections 1 to 4 of docs/plans/training-and-curation/spec-t3.md. Nothing +here opens a file or runs anything of a project: the inputs are the +definitions, the summary rows and the per-case values a project holds. Each +operation is two halves: gather_* reads what it needs from an open Project +(under the service's lock), and the function of the same name without the +prefix computes the answer from what was gathered (outside it), so a long +resampling holds up no other call. Standard library only. + +The bootstrap is a percentile bootstrap with one fixed seed: every interval +starts a fresh random.Random(SEED), so an answer is the same on every reading +and a test can repeat the arithmetic. +""" +import collections +import json +import math +import random +import re +import threading + +from . import charts, documents, results +from .store import ProjectError + +RESAMPLES = 2000 +LEVEL = 0.95 +SEED = 20261119 +MIN_VALUES = 2 # values a subject needs for an interval +LEAVES = 5000 # leaves of one flattened document +DEPTH = 32 # levels of one flattened document +SHOWN = 200 # characters of a text value shown +DIFFERS = 400 # differing paths answered +CATEGORIES = 12 # distinct values of a category axis at most +SETTINGS = 48 # setting axes answered at most +KEPT = 8 # benchmarks whose intervals are kept +STATISTICS = results.STATISTICS + +# Keys of a definition that say who a model is, not how it is made (left out of the comparison). +IDENTITY = ('format', 'kind', 'title', 'description', 'card', 'labels', 'earlier_work', 'compared_with') +# Keys compared on rows of their own, first. +_OWN_ROWS = {'group': 'group', 'change': 'change', 'derived_from': 'parent'} +_KIND_ORDER = {'group': 0, 'change': 1, 'parent': 2, 'data': 3, 'setting': 4} +_QUOTED = re.compile(r'[.\[\]" ]') + + +# ================================================================ flattening + +def _part(path, key): + if key and not _QUOTED.search(key): + return f'{path}.{key}' if path else key + return f'{path}[{json.dumps(key)}]' + + +def flatten(document, *, leaves=LEAVES, depth=DEPTH): + """(leaves, truncated): {path: leaf} of a definition's document, its identity keys left out (section 1). + + A leaf is None, a boolean, a number, a string, or an empty object or list. + Past `leaves` leaves or `depth` levels the rest is left out and truncated + is True. + """ + out, truncated = {}, False + + def walk(value, path, level): + nonlocal truncated + if len(out) >= leaves: + truncated = True + return + if isinstance(value, (dict, list)) and value: + if level >= depth: + truncated = True + return + items = value.items() if isinstance(value, dict) else enumerate(value) + for key, item in items: + walk(item, _part(path, str(key)) if isinstance(value, dict) else f'{path}[{key}]', level + 1) + else: + out[path] = value + + if isinstance(document, dict): + for key, value in document.items(): + if key not in IDENTITY: + walk(value, _part('', str(key)), 1) + return out, truncated + + +def kind_of(path): + """group, change, parent, data (under run.inputs) or setting.""" + if path in _OWN_ROWS: + return _OWN_ROWS[path] + if path == 'run.inputs' or path.startswith(('run.inputs.', 'run.inputs[')): + return 'data' + return 'setting' + + +def _canon(value): + """A value as it is compared: numbers by value (1 is 1.0), booleans apart from numbers.""" + if isinstance(value, bool): + return ('b', value) + if isinstance(value, (int, float)): + return ('n', float(value)) + if isinstance(value, str): + return ('s', value) + if value is None: + return ('z',) + return ('j', json.dumps(value, sort_keys=True)) + + +def _natural(path): + return [(0, int(part), '') if part.isdigit() else (1, 0, part) for part in re.split(r'(\d+)', path) if part] + + +def _shown(value): + return value[:SHOWN - 1] + '…' if isinstance(value, str) and len(value) > SHOWN else value + + +def differences(documents_, *, most=DIFFERS, leaves=LEAVES, depth=DEPTH): + """{differs, same, more, truncated} of two or more definitions' documents (section 1).""" + flats = [flatten(document, leaves=leaves, depth=depth) for document in documents_] + paths = set().union(*(flat for flat, _ in flats)) + differ, same = [], 0 + for path in paths: + present = [path in flat for flat, _ in flats] + canon = {_canon(flat[path]) for flat, _ in flats if path in flat} + if all(present) and len(canon) == 1: + same += 1 + else: + differ.append(path) + differ.sort(key=lambda path: (_KIND_ORDER[kind_of(path)], _natural(path))) + rows = [{'kind': kind_of(path), 'path': path, 'values': [_shown(flat.get(path)) for flat, _ in flats], + 'present': [path in flat for flat, _ in flats]} for path in differ[:most]] + return {'differs': rows, 'same': same, 'more': max(0, len(differ) - most), + 'truncated': [truncated for _, truncated in flats]} + + +# ================================================================ intervals + +def _quantile(ordered, q): + """Linear interpolation at q × (count − 1) of sorted numbers.""" + position = q * (len(ordered) - 1) + lower = math.floor(position) + if lower >= len(ordered) - 1: + return ordered[-1] + return ordered[lower] + (ordered[lower + 1] - ordered[lower]) * (position - lower) + + +def statistic(ordered, name): + """One statistic of sorted numbers, as results.summarise computes it.""" + if name == 'mean': + return math.fsum(ordered) / len(ordered) + if name == 'min': + return ordered[0] + if name == 'max': + return ordered[-1] + return results._percentile(ordered, {'median': 5, 'p10': 1, 'p90': 9}[name]) + + +def _ends(draws): + ordered = sorted(draws) + return [_quantile(ordered, (1 - LEVEL) / 2), _quantile(ordered, 1 - (1 - LEVEL) / 2)] + + +def interval_set(values, statistics=STATISTICS, *, resamples=RESAMPLES): + """{statistic: [low, high]} of a percentile bootstrap of values (section 2); None under MIN_VALUES values.""" + ordered = sorted(float(value) for value in values) + if len(ordered) < MIN_VALUES: + return None + rng, n = random.Random(SEED), len(ordered) + draws = {name: [] for name in statistics} + for _ in range(resamples): + sample = sorted(rng.choices(ordered, k=n)) + for name in statistics: + draws[name].append(statistic(sample, name)) + return {name: _ends(draws[name]) for name in statistics} + + +def difference(first, second, name, *, resamples=RESAMPLES): + """The interval of statistic(first) − statistic(second), first and second {case key: value} (section 2). + + {low, high, paired, count, significant}; None when either has fewer than MIN_VALUES values. + """ + if len(first) < MIN_VALUES or len(second) < MIN_VALUES: + return None + rng, draws = random.Random(SEED), [] + shared = sorted(set(first) & set(second)) + if len(shared) >= MIN_VALUES: + a, b, m = [float(first[key]) for key in shared], [float(second[key]) for key in shared], len(shared) + positions = range(m) + for _ in range(resamples): + drawn = rng.choices(positions, k=m) + draws.append(statistic(sorted(a[i] for i in drawn), name) - statistic(sorted(b[i] for i in drawn), name)) + paired, count = True, m + else: + a, b = sorted(map(float, first.values())), sorted(map(float, second.values())) + for _ in range(resamples): + draws.append(statistic(sorted(rng.choices(a, k=len(a))), name) + - statistic(sorted(rng.choices(b, k=len(b))), name)) + paired, count = False, min(len(a), len(b)) + low, high = _ends(draws) + return {'low': low, 'high': high, 'paired': paired, 'count': count, 'significant': low > 0 or high < 0} + + +# ================================================================ gathering (the project open) + +def _rows(project, template, parameters=None): + return project._execute(template, parameters).fetchall() + + +def _benchmark_document(project, name): + document = charts._document(project, 'benchmarks', name) + if document is None: + raise ProjectError(f'There is no benchmark benchmarks/{name}.', 'not-found', references=[f'benchmarks/{name}']) + return document + + +def _bare(text): + return text[len('benchmarks/'):] if isinstance(text, str) and text.startswith('benchmarks/') else text + + +def _held_values(project, benchmark, subjects=None): + """{(subject, metric): {(case, group): value}} of the numbers held for a benchmark.""" + query = ('SELECT subject, metric, case_id, grp, value FROM {schema}.result_values ' + 'WHERE benchmark = %s AND value IS NOT NULL') + parameters = [benchmark] + if subjects is not None: + query += ' AND subject = ANY(%s)' + parameters.append(sorted(subjects)) + held = collections.defaultdict(dict) + for subject, metric, case, group, value in _rows(project, query + ' ORDER BY 1, 2, 3, 4', parameters): + held[subject, metric][case, group] = value + return dict(held) + + +def _tradeoff_charts(project, benchmark): + """The data of each tradeoff chart of a benchmark, by reference order.""" + found = [] + for name, document in _rows(project, "SELECT name, document FROM {schema}.definitions " + "WHERE directory = 'charts' AND NOT removed ORDER BY name"): + if not isinstance(document, dict) or document.get('form') != 'tradeoff': + continue + if documents.parse_reference(document.get('benchmark')) != ('benchmarks', benchmark): + continue + try: + found.append(charts.chart_data(project, f'charts/{name}')) + except ProjectError: + continue # a chart whose metric the benchmark lacks: listed nowhere here + return found + + +def _recipe_documents(project, references): + names = sorted({reference.split('/', 1)[1] for reference in references + if isinstance(reference, str) and reference.startswith('recipes/')}) + if not names: + return {} + return {f'recipes/{name}': document for name, document in _rows( + project, "SELECT name, document FROM {schema}.definitions WHERE directory = 'recipes' AND NOT removed " + 'AND name = ANY(%s)', (names,))} + + +def _summaries(project, benchmark, subjects=None): + """{(subject, metric): SummaryRow-with-origin} of the rows over all cases.""" + out = {} + for stored in project.result_summaries(benchmark, group=''): + if subjects is None or stored.row.subject in subjects: + out[stored.row.subject, stored.row.metric] = stored + return out + + +def _metrics(document): + return [{'id': item['id'], 'title': item.get('title', item['id']), 'units': item.get('units'), + 'better': item.get('better', 'none')} for item in document.get('metrics', []) if isinstance(item, dict)] + + +def gather_intervals(project, benchmark): + """What intervals() needs: the held values of a benchmark and its tradeoff charts.""" + name = _bare(benchmark) + _benchmark_document(project, name) + return {'benchmark': name, 'held': _held_values(project, name), 'charts': _tradeoff_charts(project, name)} + + +def gather_compare(project, recipes): + """What model_compare() needs: the recipes' documents and, per benchmark that measures one, its rows.""" + if len(set(recipes)) != len(recipes): + raise ProjectError('Each recipe may be named once.', 'invalid') + found = _recipe_documents(project, recipes) + missing = [reference for reference in recipes if reference not in found] + if missing: + raise ProjectError(f'There is no recipe {missing[0]}.', 'not-found', references=missing) + wanted, benchmarks = set(recipes), [] + for name, document in _rows(project, "SELECT name, document FROM {schema}.definitions " + "WHERE directory = 'benchmarks' AND NOT removed ORDER BY name"): + subjects = [item for item in (document or {}).get('subjects', []) if isinstance(item, dict)] + made = {} + for item in subjects: + if item.get('recipe') in wanted and item.get('recipe') not in made: + made[item['recipe']] = item + if not made: + continue + benchmarks.append({'benchmark': name, 'title': (document or {}).get('title', name), + 'metrics': _metrics(document), + 'made': made, 'summaries': _summaries(project, name), + 'held': _held_values(project, name), 'charts': _tradeoff_charts(project, name)}) + return {'recipes': list(recipes), 'documents': [found[reference] for reference in recipes], + 'benchmarks': benchmarks} + + +def gather_axes(project, benchmark): + """What benchmark_axes() needs: the benchmark, its summary rows and its subjects' recipes.""" + name = _bare(benchmark) + document = _benchmark_document(project, name) + subjects = [item for item in document.get('subjects', []) if isinstance(item, dict) and 'name' in item] + return {'benchmark': name, 'metrics': _metrics(document), 'subjects': subjects, + 'summaries': _summaries(project, name), + 'recipes': _recipe_documents(project, [item.get('recipe') for item in subjects])} + + +# ================================================================ answers + +_kept = collections.OrderedDict() +_kept_lock = threading.Lock() + + +def _frontier_pairs(chart, held, touching=None): + """The neighbour pairs of an ungrouped tradeoff chart's frontier, compared on both metrics (section 2).""" + if chart.get('group'): + return [] + points = [point for series in chart.get('series', []) for point in series['points'] if point.get('frontier')] + pairs, name = [], chart['statistic'] + for a, b in zip(points, points[1:]): + if touching is not None and not ({a['subject'], b['subject']} & touching): + continue + both = {} + for key, metric in (('metric', chart['metric']), ('metric_x', chart['metric_x'])): + first, second = held.get((a['subject'], metric['id'])), held.get((b['subject'], metric['id'])) + both[key] = difference(first, second, name) if first and second else None + separated = None if both['metric'] is None or both['metric_x'] is None else ( + both['metric']['significant'] and both['metric_x']['significant']) + pairs.append({'subjects': [a['subject'], b['subject']], **both, 'separated': separated}) + return pairs + + +def _chart_head(chart): + return {'chart': chart['chart'], 'title': chart['title'], 'statistic': chart['statistic'], + 'metric': chart['metric'], 'metric_x': chart['metric_x'], 'grouped': bool(chart.get('group'))} + + +def intervals(gathered): + """The answer of the intervals operation (section 4) for what gather_intervals read; kept while it is the same.""" + key = gathered['benchmark'] + with _kept_lock: + if key in _kept and _kept[key][0] == gathered: + _kept.move_to_end(key) + return _kept[key][1] + held = gathered['held'] + rows = [] + for (subject, metric), values in sorted(held.items()): + ends = interval_set(values.values()) + rows.append({'subject': subject, 'metric': metric, 'count': len(values), + **{name: (ends[name] if ends else None) for name in STATISTICS}}) + frontiers = [] + for chart in gathered['charts']: + pairs = _frontier_pairs(chart, held) + apart = sorted({subject for pair in pairs if pair['separated'] is False for subject in pair['subjects']}) + frontiers.append({**_chart_head(chart), 'pairs': pairs, 'not_separated': apart}) + answer = {'benchmark': key, 'resamples': RESAMPLES, 'level': LEVEL, 'seed': SEED, 'intervals': rows, + 'frontiers': frontiers} + with _kept_lock: + _kept[key] = (gathered, answer) + while len(_kept) > KEPT: + _kept.popitem(last=False) + return answer + + +def model_compare(gathered, statistic_name='median'): + """The answer of model_compare (section 4) for what gather_compare read.""" + recipes, docs = gathered['recipes'], gathered['documents'] + models = [] + for reference, document in zip(recipes, docs): + models.append({'reference': reference, 'title': document.get('title', reference), + 'group': document.get('group'), 'change': document.get('change'), + 'derived_from': document.get('derived_from'), 'truncated': flatten(document)[1]}) + diff = differences(docs) + benchmarks = [] + for bench in gathered['benchmarks']: + columns = [] + for reference in recipes: + item = bench['made'].get(reference) + if item is None: + columns.append(None) + continue + subject, values = item['name'], {} + per_case = False + for metric in bench['metrics']: + stored = bench['summaries'].get((subject, metric['id'])) + cases = bench['held'].get((subject, metric['id'])) + ends = interval_set(cases.values(), (statistic_name,)) if cases else None + per_case = per_case or (stored is not None and stored.origin == 'values') + row = stored.row if stored is not None else None + values[metric['id']] = {'value': getattr(row, statistic_name) if row and row.count > 0 else None, + 'count': row.count if row else None, + 'low': ends[statistic_name][0] if ends else None, + 'high': ends[statistic_name][1] if ends else None} + columns.append({'subject': subject, 'title': item.get('title') or subject, 'per_case': per_case, + 'values': values}) + mine = {column['subject'] for column in columns if column} + frontiers = [] + for chart in bench['charts']: + points = {point['subject']: point for series in chart.get('series', []) for point in series['points']} + pairs = _frontier_pairs(chart, bench['held'], touching=mine) + rows = [] + for column in columns: + point = points.get(column['subject']) if column else None + if point is None: + rows.append(None) + continue + apart = sorted({other for pair in pairs if pair['separated'] is False and column['subject'] in + pair['subjects'] for other in pair['subjects'] if other != column['subject']}) + rows.append({'on': bool(point.get('frontier')), 'x': point.get('x'), 'value': point.get('value'), + 'not_separated_from': apart}) + frontiers.append({**_chart_head(chart), 'models': rows}) + benchmarks.append({'benchmark': bench['benchmark'], 'title': bench['title'], 'metrics': bench['metrics'], + 'models': columns, 'frontiers': frontiers}) + return {'statistic': statistic_name, 'resamples': RESAMPLES, 'level': LEVEL, 'seed': SEED, 'models': models, + 'differs': diff['differs'], 'same': diff['same'], 'more': diff['more'], 'benchmarks': benchmarks} + + +def _ranks(values): + """Ranks from 1, ties given their mean rank.""" + order = sorted(range(len(values)), key=values.__getitem__) + ranks = [0.0] * len(values) + start = 0 + while start < len(order): + end = start + while end + 1 < len(order) and values[order[end + 1]] == values[order[start]]: + end += 1 + for position in range(start, end + 1): + ranks[order[position]] = (start + end) / 2 + 1 + start = end + 1 + return ranks + + +def spearman(xs, ys): + """The Spearman rank correlation of two equal lists; None under three pairs or when either is constant.""" + if len(xs) < 3: + return None + rx, ry = _ranks(xs), _ranks(ys) + mx, my = math.fsum(rx) / len(rx), math.fsum(ry) / len(ry) + sxy = math.fsum((a - mx) * (b - my) for a, b in zip(rx, ry)) + sxx, syy = math.fsum((a - mx) ** 2 for a in rx), math.fsum((b - my) ** 2 for b in ry) + if sxx == 0 or syy == 0: + return None + return sxy / math.sqrt(sxx * syy) + + +def _category_order(canon): + """Categories in order: numbers by value, then false and true, then texts, then null and the rest.""" + tag = canon[0] + if tag == 'n': + return (0, canon[1], '') + if tag == 'b': + return (1, int(canon[1]), '') + if tag == 's': + return (2, 0, canon[1]) + return (3, 0, canon[-1] if len(canon) > 1 else '') + + +def _number(value): + return isinstance(value, (int, float)) and not isinstance(value, bool) and math.isfinite(value) + + +def benchmark_axes(gathered, statistic_name='median', *, most=SETTINGS): + """The answer of benchmark_axes (section 3) for what gather_axes read.""" + subjects = gathered['subjects'] + metric_values = {} + metrics = [] + for metric in gathered['metrics']: + values = {} + for item in subjects: + stored = gathered['summaries'].get((item['name'], metric['id'])) + number = getattr(stored.row, statistic_name) if stored is not None and stored.row.count > 0 else None + if number is not None: + values[item['name']] = number + metric_values[metric['id']] = values + found = list(values.values()) + metrics.append({**metric, 'positive': bool(found) and all(v > 0 for v in found), + 'low': min(found) if found else None, 'high': max(found) if found else None}) + by_path = collections.defaultdict(dict) + for item in subjects: + document = gathered['recipes'].get(item.get('recipe')) + if isinstance(document, dict): + for path, value in flatten(document)[0].items(): + by_path[path][item['name']] = value + leading = next((values for values in metric_values.values() if len(values) >= 3), None) + candidates = [] + for path, values in by_path.items(): + if len(values) < 2 or len({_canon(value) for value in values.values()}) < 2: + continue + if all(_number(value) for value in values.values()): + axis = {'path': path, 'kind': 'number', 'categories': None, + 'low': min(values.values()), 'high': max(values.values())} + positions = {name: value for name, value in values.items()} + else: + kinds = sorted({_canon(value) for value in values.values()}, key=_category_order) + if len(kinds) > CATEGORIES: + continue + first = {} + for value in values.values(): + first.setdefault(_canon(value), value) + axis = {'path': path, 'kind': 'category', 'categories': [_shown(first[kind]) for kind in kinds], + 'low': 0, 'high': len(kinds) - 1} + positions = {name: kinds.index(_canon(value)) for name, value in values.items()} + axis['count'] = len(values) + axis['distinct'] = len({_canon(value) for value in values.values()}) + if leading is not None: + both = [name for name in positions if name in leading] + axis['association'] = spearman([positions[name] for name in both], [leading[name] for name in both]) + else: + axis['association'] = None + candidates.append((axis, positions)) + candidates.sort(key=lambda pair: (pair[0]['association'] is None, -abs(pair[0]['association'] or 0), + -pair[0]['count'], _natural(pair[0]['path']))) + chosen = candidates[:most] + rows = [] + for item in subjects: + rows.append({'subject': item['name'], 'title': item.get('title') or item['name'], 'recipe': item.get('recipe'), + 'metrics': {metric['id']: metric_values[metric['id']].get(item['name']) for metric in metrics}, + 'settings': {axis['path']: positions.get(item['name']) for axis, positions in chosen}}) + return {'benchmark': gathered['benchmark'], 'statistic': statistic_name, 'metrics': metrics, + 'settings': [axis for axis, _ in chosen], 'left_out': max(0, len(candidates) - most), 'subjects': rows} diff --git a/tuldok_project/operations.py b/tuldok_project/operations.py index 971bc19a..15500047 100644 --- a/tuldok_project/operations.py +++ b/tuldok_project/operations.py @@ -7,7 +7,8 @@ the three of section 3 of spec-d2.md (weights, weights_compare, array_tiles), the two of section 2 of spec-d6.md (fields, field_compare), the three of section 3 of docs/plans/training-and-curation/spec-t2.md (model_graph, -model_graph_overlay, model_graph_compare), +model_graph_overlay, model_graph_compare), the three of section 4 of +spec-t3.md (model_compare, benchmark_axes, intervals), the five of section 5 of spec-d4.md (annotation_tasks, annotated_records, annotation, set_annotation, revert_annotations) and the five of sections 2 and 4 of spec-d5.md (endpoint, set_endpoint, @@ -36,6 +37,7 @@ INSTRUCTION_CHARACTERS = 4000 GRAPH_MODULES = 2000 # modules named open or closed by one model_graph (spec-t2.md section 3) GRAPH_OVERLAYS = ('parameters', 'outputs', 'operations', 'change') +COMPARED_MOST = 4 # recipes of one model_compare (spec-t3.md section 4) @dataclass(frozen=True) @@ -111,6 +113,7 @@ def _arguments(required=(), **properties): ENDPOINT = ('address', 'answered', 'version', 'models', 'problem') MODEL_GRAPH = ('path', 'format', 'complete', 'reason', 'method', 'torch', 'model', 'inputs', 'notes', 'counts', 'modules', 'tensors', 'depth', 'open', 'nodes', 'edges') +_STATISTIC = {'type': 'string', 'enum': ['mean', 'median', 'p10', 'p90', 'min', 'max']} _MODULE_PATHS = {'type': 'array', 'items': {'type': 'string', 'maxLength': 1024}, 'maxItems': GRAPH_MODULES} @@ -243,6 +246,20 @@ def _arguments(required=(), **properties): Operation('model_graph_compare', "Match the modules of two finished runs' model graphs by path: the same, " 'changed (class or tensor shapes), added or missing.', 'inspect', False, _arguments(['run', 'other_run'], run=_RUN, other_run=_RUN), ('modules', 'counts')), + Operation('model_compare', 'Compare two to four recipes: the settings, data and parent that differ, their ' + 'metrics on every benchmark that measures them with bootstrap intervals from per-case values, and ' + 'where each sits on the frontier of its tradeoff charts.', 'inspect', False, + _arguments(['recipes'], recipes={'type': 'array', 'items': _REFERENCE, 'minItems': 2, + 'maxItems': COMPARED_MOST}, statistic=_STATISTIC), + ('statistic', 'resamples', 'level', 'seed', 'models', 'differs', 'same', 'more', 'benchmarks')), + Operation('benchmark_axes', "Read a benchmark's subjects as lines through axes: its metrics and the numeric or " + 'categorical recipe settings that vary between them, the settings that go most with the first metric ' + 'first.', 'inspect', False, _arguments(['benchmark'], benchmark=_NAME, statistic=_STATISTIC), + ('benchmark', 'statistic', 'metrics', 'settings', 'left_out', 'subjects')), + Operation('intervals', "Read bootstrap intervals of every statistic of a benchmark's subjects from the per-case " + 'values held here, and whether neighbours on the frontier of its tradeoff charts are told apart.', + 'inspect', False, _arguments(['benchmark'], benchmark=_NAME), + ('benchmark', 'resamples', 'level', 'seed', 'intervals', 'frontiers')), Operation('annotation_tasks', 'List the annotation tasks, each with its dataset, current product and counts of ' 'its records by the state of their annotations.', 'inspect', False, _arguments(), ('tasks',)), Operation('annotated_records', "Read one page of the records of a task's dataset with their annotations, " diff --git a/tuldok_project/service.py b/tuldok_project/service.py index 5d55c6c3..90134c28 100644 --- a/tuldok_project/service.py +++ b/tuldok_project/service.py @@ -26,7 +26,9 @@ find_endpoints need no project at all (the address is a setting of the machine, in local.py's settings file), and suggestion_models and suggest_annotation find the task's product under the lock and read it and -ask the endpoint after releasing it. Nothing here knows of HTTP or of the +ask the endpoint after releasing it. Two of the three comparisons of +spec-t3.md (intervals, model_compare) read the project under the lock and +resample its per-case values after releasing it (comparing.py). Nothing here knows of HTTP or of the app's access layer. The worker (section 4) is one thread per service, started by start() and @@ -54,8 +56,8 @@ import psycopg from . import (activity, annotation_records, annotation_rows, annotations, build_requests, builds, charts, check, - documents, environments, inside, inside_fields, inside_graph, inside_weights, launcher, local, operations, plan, - pumas, store, workspace) + comparing, documents, environments, inside, inside_fields, inside_graph, inside_weights, launcher, local, + operations, plan, pumas, store, workspace) from .documents import Problem CHECK_PROBLEMS = 200 @@ -101,8 +103,10 @@ ANNOTATION_READS = ('annotation_tasks', 'annotated_records', 'annotation') # The calls to the Pumas endpoint (spec-d5.md): each is made outside the service's lock; those that read a project # take the lock themselves, only for their database work. -OUTSIDE_LOCK = ANNOTATION_READS + ('endpoint', 'set_endpoint', 'find_endpoints', 'suggestion_models', - 'suggest_annotation') +# The comparisons of spec-t3.md that resample per-case values: read under the lock, computed outside it. +COMPARING_READS = ('intervals', 'model_compare') +OUTSIDE_LOCK = ANNOTATION_READS + COMPARING_READS + ('endpoint', 'set_endpoint', 'find_endpoints', + 'suggestion_models', 'suggest_annotation') POLL_SECONDS = 1.0 # how often the worker looks for a queued request CLOSE_SECONDS = 30.0 # how long close() waits for the worker WORKER_LOCK = 'build-requests.lock' @@ -467,6 +471,21 @@ def _chart(self, arguments, actor): result['svg'] = charts.render_svg(data, theme=arguments.get('theme', 'light')) return result + def _intervals(self, arguments, actor): + with self._lock, self._open() as project: + gathered = comparing.gather_intervals(project, arguments['benchmark']) + return comparing.intervals(gathered) + + def _model_compare(self, arguments, actor): + with self._lock, self._open() as project: + gathered = comparing.gather_compare(project, arguments['recipes']) + return comparing.model_compare(gathered, arguments.get('statistic', 'median')) + + def _benchmark_axes(self, arguments, actor): + with self._open() as project: + gathered = comparing.gather_axes(project, arguments['benchmark']) + return comparing.benchmark_axes(gathered, arguments.get('statistic', 'median')) + def _report(self, arguments, actor): with self._open() as project: return {'html': charts.render_report(project, theme=arguments.get('theme', 'light'))} From 40760c0bb7675e0747878504d19b342b8873fc8b Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 19 Nov 2026 06:16:37 -0700 Subject: [PATCH 098/131] docs(plan): spec-t5, curation by embeddings Co-Authored-By: Claude Opus 5.5 --- docs/plans/training-and-curation/spec-t5.md | 127 ++++++++++++++++++++ 1 file changed, 127 insertions(+) create mode 100644 docs/plans/training-and-curation/spec-t5.md diff --git a/docs/plans/training-and-curation/spec-t5.md b/docs/plans/training-and-curation/spec-t5.md new file mode 100644 index 00000000..d10a1d7d --- /dev/null +++ b/docs/plans/training-and-curation/spec-t5.md @@ -0,0 +1,127 @@ +# Implementation spec: curation by embeddings + +This is phase 5 of [the training and curation plan](plan.md). It follows that plan's rule: a file contract, a reader and a view in Tuldok, and no embedder of Tuldok's own. The readers follow [spec-d1.md](../definition-first-projects/spec-d1.md) and [spec-d6.md](../definition-first-projects/spec-d6.md): standard library only, nothing unpickled, nothing of the project's code run, nothing written, bounded reads, a damaged file refused and not a failure, reads outside the service lock. The step follows [spec-d4.md](../definition-first-projects/spec-d4.md) section 6 and [spec-d5.md](../definition-first-projects/spec-d5.md) section 3 (`generate`): Pumas is reached only through `tuldok_project/pumas.py` and the 0.8.0 client of [spec-d3.md](../definition-first-projects/spec-d3.md). The page follows [spec-w4.md](../definition-first-projects/spec-w4.md): nothing is rebuilt by a timer or a return to the window. + +**Owner, 2026-11-19:** "Tuldok should have curarion by embeddings. Tuldok needs to have great curaiton tools for datasets in order to build high quality training data." And: "Set embeddinggemma 2 as the default embbedder for Pumas." + +**After this phase** a dataset that has embeddings opens on the Data tab as a map: its records as points in two dimensions, coloured by split, kind, an annotation the records carry or any field of theirs; beside it the near-duplicates, the outliers, the thin parts of the map, the near-copies between the training split and the others (leakage), and, for the record opened, the records most like it. A region chosen on the map becomes a new dataset of exactly those records, or opens Freeze with them. Embeddings are made by a project's own script, or by a new step `embed` that asks a model the Pumas endpoint serves, EmbeddingGemma 2 unless the definition or the machine names another. Tuldok never computes an embedding. + +## 1. The file: an embeddings product + +A product holds a set of embeddings `` (1 to 64 characters of `a-z 0-9 . _ -`, starting with a letter or digit) as two files under `embeddings/` at its top: + +- **`embeddings/.npy`:** one row per record, shape `(rows, dimensions)`, `float32` (little- or big-endian; `float16` and `float64` are read too), C order, every value finite, no row all zeros. +- **`embeddings/.json`,** the index, UTF-8 JSON of at most 16 MiB: + +```json +{"format": "tuldok_embeddings_v1", + "records": ["a1", "a2", "a3"], + "dimensions": 256, + "metric": "cosine", + "model": {"name": "embeddinggemma-2", "model_id": "unsloth/embeddinggemma-2-GGUF", "profile": "embed-gpu", + "capability": "text_embedding", "via": "pumas"}, + "prefix": "task: clustering | query: ", + "source": {"dataset": "datasets/photos", "run": "4f1c…"}, + "projection": {"file": "photos.map.npy", "method": "umap"}, + "notes": ["2 point clouds were not embedded: no model the endpoint serves takes them."]} +``` + +- `records`: the record ids in row order, 1 to 50,000 different ids of spec-d1 (1 to 200 of `A-Z a-z 0-9 . _ -`). +- `dimensions`: 1 to 4,096, the second axis of the `.npy`. `metric`: `cosine` (the only one). +- `model`: an object with `name` (1 to 256 characters) and any other short facts (strings, numbers, booleans or null), shown as given. +- `prefix`: the text put before each record's text, or null. EmbeddingGemma expects a task prefix (Pumas: "task prefixes … are part of the caller's text"). +- `source`: which records the rows are: `dataset` (a reference, or null for the product's own records) and `run` (the run whose product holds them, or null when the script cannot know it; section 3 finds it). +- `projection` (optional): a two-dimensional map the script made (UMAP, t-SNE, anything), a `.npy` of shape `(rows, 2)` beside the index, and its `method` (1 to 64 characters). Tuldok draws it instead of its own. +- `notes` (optional): at most 64 sentences of at most 1,000 characters. + +Other keys are kept and ignored. Bounds: rows × dimensions at most 40,000,000 values (160 MB of `float32`); at most 64 sets in one product. A set breaking a rule is listed with the reason and refused `unsupported` when read; a `.npy` over the bound `too-large`. + +**Who writes it.** A project's own script, in the product of a dataset (its own records' embeddings, `source.dataset` null) or of a dataset whose run takes the records' dataset as an input (`source.dataset` names it). Or the step `embed` (section 5). The contract goes into `docs/contracts/project-folder.md`. + +## 2. The default embedder + +When nothing names an embedding model, Tuldok uses **EmbeddingGemma 2**: the served (model, profile) whose alias or `model_id` contains `embeddinggemma-2`, ignoring case, preferring the `model_id` `unsloth/embeddinggemma-2-GGUF`, then the endpoint's order, among those with an embedding capability available. When none is served the call is refused `not-found`, naming what the endpoint serves with an embedding capability; another model is never chosen silently. + +The machine's settings file (beside `pumas_endpoint`, `local.py`) may hold `embedding_model` (an alias, and optionally `embedding_profile`) to use instead of EmbeddingGemma 2, and `embedding_prefix` (default `task: clustering | query: `). A step's own `model` and `prefix` come first. The order is: the definition, the machine's setting, EmbeddingGemma 2. + +- **`endpoint`** answers, besides what it did, `embedder`: `{model, profile, prefix, named_by` (`setting` or `default`)`, chosen` (the served entry it resolves to now, or null)`, problem` (why none, or null)`, embedders` (every served (model, profile) with an embedding capability available: `model`, `profile`, `model_id`, `capabilities`, `dimensions` (the advertised bound or null)`)}`. +- **`set_embedder`** (owner, changes): `model` (an alias, or null for EmbeddingGemma 2), `profile`, `prefix` (null for the default prefix). A model that the endpoint does not serve with an embedding capability is refused; the prefix is at most 1,000 characters. Answers `endpoint`'s `embedder`. + +## 3. Finding a dataset's embeddings + +**`embeddings`** (inspect), argument `dataset` (a reference). The dataset's current products, and the current products of every dataset whose `run.inputs` names it, are looked through for `embeddings/*.json`. A set belongs to the dataset when its `source.dataset` names it, or when it lies in the dataset's own product with `source.dataset` null. Its **records run** is `source.run` when given; else the run holding it when the records are its own; else the run the holding run recorded for that input. The answer: `dataset`, `run` (its first current product's run, or null), and `sets`, each `run` (holding it), `holder` (the dataset holding it), `name`, `rows`, `dimensions`, `model`, `prefix`, `source`, `records_run`, `current` (the records run is a current product of the dataset), `projection` (its method or null), `notes`, `problem` (null, or why it cannot be read). + +## 4. Reads + +Five reads, `inspect`, in `INSIDE_READS` like the others, in the `project_folder` profile and absent from `catalog` (whose digest is unchanged). Each takes `run` (holding the set), `name`, and `records_run` (whose records the rows are; default `run`), which joins the product arguments the service finds under its lock. + +| Operation | Arguments | Result | +| --- | --- | --- | +| `embedding_map` | `colour` (`split`, `kind`, `annotation:`, `field:`; optional), `cells` (8 to 64, default 24), `thin` (0 to 1, default 0.25) | `name`, `rows`, `dimensions`, `model`, `method` (`pca`, or the script's), `explained` (the share of the variance on each axis, for `pca`), `sample` (rows the components were computed from), `ids`, `x_f32`, `y_f32` (base64), `bounds`, `missing` (rows whose record is not in the records product), `colours` (what can be chosen: `split`, `kind`, `annotation:` for each task the records carry, `field:` for each key of `meta` found), `colour` (`by`, `type` `category` or `number`, `categories` with counts, `codes_u16` or `values_f32` (base64, per row), or null), `grid` (`cells`, `counts` row by row), `thin` (cells) | +| `embedding_neighbours` | `record`, `limit` (1 to 200, default 12) | `record`, `neighbours` (`id`, `cosine`, `split`, `kind`), most alike first; exact | +| `embedding_duplicates` | `threshold` (0.5 to 1, default 0.98), `limit` (1 to 1,000, default 200) | `threshold`, `pairs` (`a`, `b`, `cosine`, `a_split`, `b_split`), most alike first, `total`, `groups` (how many records are in some pair), `complete`, `examined`, `rows` | +| `embedding_outliers` | `k` (1 to 50, default 5), `limit` (1 to 1,000, default 50) | `k`, `outliers` (`id`, `distance` (one minus the cosine to its k-th nearest record), `nearest`, `split`), farthest first, `median` (of every examined row's distance), `complete`, `examined`, `rows` | +| `embedding_leakage` | `threshold` (default 0.95), `train` (the split trained on, default `train`), `limit` | `threshold`, `train`, `splits` (each split's count), `pairs` (`record`, `split`, `near` (the training record), `cosine`), most alike first, `total`, `leaked` (records of other splits with a near-copy in training), `complete`, `examined`, `rows`; a product with no splits answers `splits` {} and no pairs | + +**Arithmetic,** in 64-bit floats with `math.sumprod`, `math.fsum` and `math.dist`. Rows are made unit length; cosine is their dot product. + +- **The map (`pca`).** The mean and the leading eight principal components (fewer when there are fewer dimensions or rows) of a sample of the rows, evenly spaced, of at most `max(256, 2^19 / dimensions)` rows: by power iteration on the sample's covariance (computed whole when there are at most 1,024 dimensions, else applied without forming it), eight vectors together, orthonormalised each turn and rotated to the covariance's own axes by a small Jacobi solve (Rayleigh–Ritz), until they move less than 1e-9 or after 200 turns. Every row is projected on the first two. `explained` is each component's variance over the total. Signs are fixed so that each component's largest entry is positive. +- **Bounding the pair searches.** Each row also gets its coordinates on all the components and the length of what they leave out (the residual). For two unit rows, the distance in those coordinates, with the residual lengths as one more, is never more than their true distance, so a pair whose coordinates are farther apart than the threshold allows is ruled out without reading its rows. The rows are sorted by their first coordinate and each is compared with those within the threshold's distance along it; what is not ruled out is computed exactly. Nothing found is approximate. +- **What bounds it.** A search examines rows in a fixed shuffled order and stops after 20,000,000 comparisons of coordinates or 400,000 exact ones; a row is examined whole or not at all, so what is listed is exactly right for the rows examined, and `complete` says whether every row was. Duplicates and outliers examine every row; leakage the rows of the splits other than `train`. +- **Outliers** are the rows farthest from their k-th nearest neighbour (exact, by the same sorting: the search around a row stops when the first coordinate alone is farther than its k-th nearest so far). +- **Thin regions** are the map's cells (a `cells` by `cells` grid over its bounds) that hold some points but at most `thin` times the median count of the cells that hold any; each with its place, count and its records (at most 20), fewest first, at most 64 cells. +- **Colour.** `split` and `kind` are the records' own; `annotation:` the value a frozen record carries for that task (a term, the terms joined, or its state when it has no value); `field:` a key of a record's `meta` (a number is a number, anything else a category). At most 24 categories, the rest one `other`; a row with no value has the code 65535 or NaN. +- **Kept.** What is computed for a set (its unit rows, components, coordinates, sorted order, the searches' answers) is kept while its two files are unchanged, at most two sets and 400 MB, least recently used dropped. + +## 5. The steps `embed` and `select`, and freezing a selection + +**`embed`.** A dataset whose `run` has `step: "embed"`, `inputs: {"records": }`, and `settings`, every one optional: `model` and `profile` (the served alias; section 2's order otherwise), `prefix` (at most 1,000 characters), `dimensions` (1 to 4,096; Pumas truncates and renormalises), `name` (of the set; default the input's name), `batch` (1 to 256, default 32). Output: `embeddings/.npy` and `.json`, with `source` naming the input and its run, `model` naming what answered (`name`, `model_id`, `profile`, `capability`, `via: "pumas"`), and nothing else in the product. + +- **What is asked.** Text records (inline, or a UTF-8 file of at most 64 KiB) by `text_embedding` with `text_batch`, the prefix put before each text; PNG and JPEG images of at most 8 MiB by `multimodal_embedding` with `content_batch`, one image part an item. A batch is at most `batch` items, at most the advertised `input_count`, and for images at most the advertised `image_count` (4 without one) and 16 MiB. Options `{"kind": "embeddings", "dimensions": d}` only when `dimensions` is set; it is checked against an advertised `dimensions` bound when there is one. Records of other kinds, or that cannot be sent, are not embedded and are counted in `notes`. +- **Before anything is asked,** the step reads what the endpoint serves and fails, saying why, when the model is not served, the capability a kind of record needs is not available, or `dimensions` is past its bound. A dataset with records of a kind the model cannot embed fails before anything is asked unless it also has records it can; then those are noted. +- **The answer** must hold one finite vector per item, all of one length (`dimensions` when set). A refusal before the provider took it (`not_admitted`) is asked again twice, after 1 s and 2 s; anything else fails the step with the batch's first record. +- **Resumable.** Every batch answered is appended to `embeddings/..partial` (rows) and its ids to `..partial.json` (with the model, the input run, the prefix and the dimensions). When the dataset's last run failed, the build passes its output to the step, which takes the rows already answered from it when the input run, model, prefix and dimensions are the same, and asks only for the rest; the step says how many it took. +- **Progress** is the count of records embedded, in the existing form; the endpoint's address and version are kept in the run's record as for `generate`, never in the folder. Planning: without an endpoint the step is blocked as `generate` is. + +**`select`.** A dataset whose `run` has `step: "select"`, `inputs: {"records": }`, `settings: {"records": [ids]}` (1 to 20,000 different ids): its product holds exactly those records of the input's product, in the input's order, each line as the input has it (its split and annotations kept), its file linked under `files/`, its hash computed when the input has none. An id the input does not have fails the step, naming the first. This is what a selection on the map becomes. + +**Freeze** gains an optional setting `records` (1 to 20,000 ids): only those records of the input are taken, before the first task's states decide. "Freeze these" on the map opens the Freeze form with the dataset and the ids filled in. + +`check` checks the settings of both steps; the schemas list them; both are planned, requested, approved, run and recorded like any build. + +## 6. The page + +**The dataset opened** (`#data/inside:`, spec-d1) gains a third mode beside Records and Files, **Map**, when `embeddings` lists a set for it. With several sets, a select names each (`holder · name · model`). A set whose records run is not the dataset's current product says so. + +- **The map,** a canvas: the points, coloured by the choice (`Colour by`: none, split, kind, each annotation, each field), a legend with each category's count or the number scale's ends; the thin cells shaded; the selected record ringed, its most alike joined to it by lines. The wheel zooms about the pointer, dragging pans; "Reset view". +- **Hovering** a point shows its id and colour value in a tip; resting on it 300 ms shows the record in the viewer beside the map, with inside.js's viewers. A click opens it (pinned) and asks for its neighbours. +- **Choosing a region:** Box or Lasso (a toggle), then dragging. The chosen points are marked and counted. "New dataset from these" (title, name; Keep) keeps a `select` definition as an unsaved edit, as the other forms do, staying on the map; "Freeze these" opens the Freeze form filled in; "Clear". +- **Beside the map,** lists, each row a button that opens its record: **More like this** (the opened record's neighbours), **Duplicates** (threshold), **Outliers**, **Leakage** (when the records have splits; threshold and the training split), **Thin regions** (a cell's row selects its records). Each list is asked for when first shown and when its controls change. +- **The Embed form,** on the Data tab beside Import, Freeze and Generate: title, name, the dataset, the model (EmbeddingGemma 2 or the machine's setting, shown as what it resolves to now; or any served embedder), prefix (the default shown), dimensions (with the advertised bound), batch. It keeps an `embed` definition as an unsaved edit. With no endpoint, or none that embeds, it says so. +- **The endpoint's drawer** on Train shows the embedder (what the machine's setting or the default resolves to), and for the owner a select of the served embedders ("EmbeddingGemma 2 (default)" first) and the prefix, with Set. +- Every control is a button, select or field; the canvas has a text alternative and is reachable by Tab, with the arrow keys moving through the points nearest in the map. Light and dark from the tokens of `base.css`. Updating in place: the map's answers are not watched; a reading that changed something draws the view again in place keeping the set, colour, zoom, selection and the lists' controls; a timer or a return to the window with nothing changed touches nothing. + +## 7. Slices + +| | Slice | Files | +| --- | --- | --- | +| T5a | The contract, the reader and the six reads | `docs/contracts/project-folder.md`, `tuldok_project/embeddings.py` (new), `operations.py`, `service.py`, `tests/test_tuldok_project_curation.py` (new), the count of the table's rows in `tests/test_tuldok_project_service.py` | +| T5b | The default embedder, the settings, `embed`, `select`, freeze's `records` | `pumas_operations.py` (the `embeddings` result), `tuldok_project/pumas.py`, `local.py`, `steps.py`, `builds.py`, `plan.py`, `check.py`, `schemas/`, `operations.py`, `service.py`, `tests/fake_pumas_typed.py`, `tests/browser_fake_pumas.py`, `tests/test_tuldok_project_curation.py` | +| T5c | The page | `static/project-workspace/curation.js` (new), `inside.js`, `tabs.js` (the Embed button), `annotate.js` (Freeze filled in), `generate.js` (the embedder), `base.css`, `static/project-workspace.html`, `app.py` (the asset list), `tests/browser_project_workspace_curation.cjs` (new), its fixture | + +## 8. Tests + +**T5a and T5b, `tests/test_tuldok_project_curation.py`,** fixtures written by the test with the standard library: + +- The contract: a set read; each rule broken once refused with its sentence (format, ids repeated, rows and shape disagreeing, a non-finite value, a zero row, a projection of the wrong shape, a bound lowered for the test). +- The map's components against the test's own arithmetic on a planted structure (points spread along two known orthogonal directions with known variances, and noise): the axes and the shares of variance; a script's projection used as given. +- Neighbours, duplicates, outliers and leakage on a fixture with planted near-duplicates, one far record and one validation record that is a near-copy of a training one, against a brute force the test computes; a budget lowered for the test gives `complete` false with exactly-right pairs for the rows examined; thin cells against the test's counting. +- The default embedder: EmbeddingGemma 2 chosen when served (by alias and by model id, the preferred id first), refused with the served embedders listed when not, never another model; the machine's setting and the definition's model in that order. +- `embed` against the fake endpoint, built for real by `builds.execute`: a text and image dataset embedded in batches, the requests' inputs, prefix and options as section 5 says, a valid product read back by the reads; a point cloud noted and not embedded; a `not_admitted` asked again; a failure part way and a second build that takes the answered rows and asks only for the rest; no endpoint, the plan says so. `select` and freeze's `records` built for real, with exactly the records chosen. +- The six reads and `set_embedder` in `project_folder`, not in `catalog`, its digest unchanged. + +**T5c, `tests/browser_project_workspace_curation.cjs`,** on a fixture project (a frozen dataset with planted duplicates and one leaked validation record, embeddings written by a script), the fake endpoint, owner signed in, no GPU: the map drawn and coloured by split; a region chosen and kept as a new dataset whose definition holds exactly those records; Freeze filled in with them; the duplicates and the leaked record listed; more like this for an opened record; the Embed form showing EmbeddingGemma 2 as the default; light and dark at 1440 and 390 wide, no sideways overflow, no script error, nothing redrawn on a return to the window. + +## 9. Out of scope + +Computing embeddings in Tuldok; approximate nearest-neighbour indexes; UMAP or t-SNE in Tuldok (a script may write either as the projection); embeddings of sounds, point clouds and meshes through the endpoint (Pumas 0.8.0 embeds text and images only); colouring by an annotation that is not carried in the records (the working copy's annotations of a task); several sets on one map; clustering. From f9eac713f6893d6105bebf55befbdb9f72de2cc8 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 19 Nov 2026 06:17:12 -0700 Subject: [PATCH 099/131] feat(workspace): the Compare tab, parallel coordinates and intervals on Benchmarks A Compare tab after Benchmarks shows the page's compare set (now up to four, filled from the Map's and Benchmarks' drawers and the table) one column a model: who it is, the recipe paths that differ, metrics with bootstrap intervals and the frontier, then the outputs of a case the models kept, with one slice control and one colour scale a row. Benchmarks gains parallel coordinates with brushing linked to the table and charts, whiskers on ranking charts and the table, and a ring on frontier points not told apart. Co-Authored-By: Claude Opus 5.5 --- app.py | 3 + static/project-workspace.html | 3 + static/project-workspace/adapter.js | 6 +- static/project-workspace/app.js | 12 +- static/project-workspace/charts.js | 9 +- static/project-workspace/compare.css | 86 +++++++ static/project-workspace/compare.js | 342 +++++++++++++++++++++++++++ static/project-workspace/fields.js | 32 ++- static/project-workspace/parallel.js | 218 +++++++++++++++++ static/project-workspace/screens.js | 8 +- static/project-workspace/tabs.js | 78 ++++-- 11 files changed, 758 insertions(+), 39 deletions(-) create mode 100644 static/project-workspace/compare.css create mode 100644 static/project-workspace/compare.js create mode 100644 static/project-workspace/parallel.js diff --git a/app.py b/app.py index e2ed01cf..d6ec7ccf 100644 --- a/app.py +++ b/app.py @@ -797,6 +797,9 @@ def _get(self): }) assets.update({'/project-workspace': ('project-workspace.html', 'text/html'), '/project-workspace/base.css': ('project-workspace/base.css', 'text/css'), + '/project-workspace/compare.css': ('project-workspace/compare.css', 'text/css'), + '/project-workspace/compare.js': ('project-workspace/compare.js', 'text/javascript'), + '/project-workspace/parallel.js': ('project-workspace/parallel.js', 'text/javascript'), '/project-workspace/adapter.js': ('project-workspace/adapter.js', 'text/javascript'), '/project-workspace/charts.js': ('project-workspace/charts.js', 'text/javascript'), '/project-workspace/markdown.js': ('project-workspace/markdown.js', 'text/javascript'), diff --git a/static/project-workspace.html b/static/project-workspace.html index bec8ec33..19aaea1a 100644 --- a/static/project-workspace.html +++ b/static/project-workspace.html @@ -8,6 +8,7 @@ + @@ -22,7 +23,9 @@ + + diff --git a/static/project-workspace/adapter.js b/static/project-workspace/adapter.js index 6e3720a7..93be789a 100644 --- a/static/project-workspace/adapter.js +++ b/static/project-workspace/adapter.js @@ -69,7 +69,7 @@ window.TuldokProject = (() => { const key = keyOf(name, args); if (!kept.has(key)) { const entry = { text: null }; - entry.answer = call(name, args).then(value => { entry.text = JSON.stringify(value); return value; }, error => { if (kept.get(key) === entry) kept.delete(key); throw error; }); + entry.answer = call(name, args).then(value => { entry.text = JSON.stringify(value); entry.value = value; return value; }, error => { if (kept.get(key) === entry) kept.delete(key); throw error; }); kept.set(key, entry); } return kept.get(key).answer; @@ -96,6 +96,8 @@ window.TuldokProject = (() => { } return changed; } + /** The kept answer of a read when it has arrived, else undefined; asks nothing (the Benchmarks tab's intervals, spec-t3 section 5.2). */ + function peek(name, args = {}) { const entry = kept.get(keyOf(name, args)); return entry && entry.text !== null ? (entry.value !== undefined ? entry.value : JSON.parse(entry.text)) : undefined; } function forget(names) { for (const key of [...kept.keys()]) if (names.includes(key.split(' ')[0])) kept.delete(key); } /** Forgets every kept answer whose operation is not named. */ function forgetBut(names) { for (const key of [...kept.keys()]) if (!names.includes(key.split(' ')[0])) kept.delete(key); } @@ -297,5 +299,5 @@ window.TuldokProject = (() => { return out; } - return { KINDS, UNSET, WATCHED, kindLabel, stateWord, call, read, again, forget, forgetBut, forgetAll, map, setDrafts, trackName, better, units, standing, needs, titleOf, day, product, annotations, annotationsUnsaved }; + return { KINDS, UNSET, WATCHED, kindLabel, stateWord, call, read, peek, again, forget, forgetBut, forgetAll, map, setDrafts, trackName, better, units, standing, needs, titleOf, day, product, annotations, annotationsUnsaved }; })(); diff --git a/static/project-workspace/app.js b/static/project-workspace/app.js index 7eae0a98..10bebe1d 100644 --- a/static/project-workspace/app.js +++ b/static/project-workspace/app.js @@ -19,7 +19,7 @@ // shows the conflict panel. (() => { const P = window.TuldokProject, S = window.LabScreens, A = window.LabActions; - const TABS = [['map', 'Map'], ['data', 'Data'], ['annotate', 'Annotate'], ['train', 'Train'], ['benchmarks', 'Benchmarks'], ['analysis', 'Analysis'], ['overview', 'Overview']]; + const TABS = [['map', 'Map'], ['data', 'Data'], ['annotate', 'Annotate'], ['train', 'Train'], ['benchmarks', 'Benchmarks'], ['compare', 'Compare'], ['analysis', 'Analysis'], ['overview', 'Overview']]; const POLL_MS = 2000, IDLE_MS = 15000; // how often the page asks again while something builds, and while nothing does const ACTIVE_RUN = ['queued', 'running'], ACTIVE_REQUEST = ['queued', 'running']; const $ = id => document.getElementById(id); @@ -52,8 +52,9 @@ setUI: (k, v) => { state.ui[k] = v; if (ADDRESSED.includes(k)) address(); render(); }, /** Keeps a setting of the tab that a view has already drawn in place (fields.js's slider): into the address, and nothing drawn again. */ keepUI: (k, v) => { state.ui[k] = v; if (ADDRESSED.includes(k)) address(); }, - setBenchmark: name => { state.benchmark = name; state.cmp = []; address(); render(); }, - toggleCompare: id => { const i = state.cmp.indexOf(id); if (i >= 0) state.cmp.splice(i, 1); else if (state.cmp.length < 3) state.cmp.push(id); address(); render(); }, + // The compare set is the page's, of up to COMPARE_MOST models from any benchmark or the map (spec-t3 section 5.1): another benchmark keeps it. + setBenchmark: name => { state.benchmark = name; address(); render(); }, + toggleCompare: id => { const i = state.cmp.indexOf(id); if (i >= 0) state.cmp.splice(i, 1); else if (state.cmp.length < COMPARE_MOST) state.cmp.push(id); address(); render(); }, clearCompare: () => { state.cmp = []; address(); render(); }, /** Reads everything again (a control's answer came, or a view asks for it). */ refresh: () => changed(), @@ -63,7 +64,8 @@ reopen: () => { $('aside')._for = null; render(); } }; // The settings of the Analysis tab the address keeps, so that a reload opens it where it was (spec-d6 section 3). - const ADDRESSED = ['anaBench', 'anaSubject', 'anaMetric', 'anaCase', 'anaAxis', 'anaIndex', 'anaMeanFree']; + const ADDRESSED = ['anaBench', 'anaSubject', 'anaMetric', 'anaCase', 'anaAxis', 'anaIndex', 'anaMeanFree', 'cmpCase', 'cmpAxis', 'cmpIndex', 'cmpMeanFree']; + const COMPARE_MOST = 4; /** Writes the benchmark, the compare set and the Analysis tab's settings into the address without reloading, so the view can be shared. */ function address() { const q = new URLSearchParams(location.search); @@ -321,7 +323,7 @@ window.addEventListener('focus', () => { if (data.summary || failed) reread('focus'); }); // Who may use a control comes from the session: draw the controls again when it changes. window.addEventListener('tuldok-session', () => { if (failed) reread('focus'); else { $('aside')._for = null; if (data.map) act.redraw(); else { strip(); render(); } } }); - { const q = new URLSearchParams(location.search); state.benchmark = q.get('benchmark') || null; state.cmp = (q.get('cmp') || '').split(',').filter(Boolean).slice(0, 3); for (const k of ADDRESSED) if (q.get(k)) state.ui[k] = q.get(k); } + { const q = new URLSearchParams(location.search); state.benchmark = q.get('benchmark') || null; state.cmp = (q.get('cmp') || '').split(',').filter(Boolean).slice(0, COMPARE_MOST); for (const k of ADDRESSED) if (q.get(k)) state.ui[k] = q.get(k); } // The tab bar, once (spec-w4 R5): render() sets which link is current. for (const [id, label] of TABS) { const a = document.createElement('a'); a.href = '#' + id; a.textContent = label; a.dataset.tab = id; $('tabs').appendChild(a); } parse(); strip(); render(); first(); diff --git a/static/project-workspace/charts.js b/static/project-workspace/charts.js index ca036bec..1cbe4a5e 100644 --- a/static/project-workspace/charts.js +++ b/static/project-workspace/charts.js @@ -130,6 +130,7 @@ window.LabCharts = (() => { const g = el('g'), cx = X(p.x), cy = Y(p.y); const hit = el('circle', { cx, cy, r: 11, class: 'hit', tabindex: 0, role: 'button', 'data-id': p.id, 'aria-label': p.name + ', ' + opts.yTitle + ' ' + fmtSci(p.y) + ', ' + opts.xTitle + ' ' + fmtSci(p.x) + (p.frontier ? ', on the frontier' : '') }); g.appendChild(hit); g.appendChild(el('circle', { cx, cy, r: 6, class: 'pt ' + p.kind + ((opts.dimOff && !p.frontier) || p.dim ? ' dim' : '') })); + if (p.nsig) g.appendChild(el('circle', { cx, cy, r: 10, class: 'nsig' })); // on the frontier, not told apart from a neighbour (spec-t3) if (p.id === opts.selected) g.appendChild(el('circle', { cx, cy, r: 9, class: 'sel' })); interactive(hit, host, svg, () => [cx, cy], p.rows, opts.onSelect && (() => opts.onSelect(p.id))); svg.appendChild(g); @@ -182,11 +183,11 @@ window.LabCharts = (() => { host.appendChild(svg); } - /** Subjects best first {id, name, y, kind, rows}: one row each, a dot on the value axis with a hairline from its start. */ + /** Subjects best first {id, name, y, kind, rows, lo, hi}: one row each, a dot on the value axis with a hairline from its start, and a whisker from lo to hi when given (an interval, spec-t3). */ function ranking(host, points, opts) { host.textContent = ''; host.classList.add('chart'); host._tip = null; const n = points.length, RH = n > 60 ? 16 : 20, W = Math.max(360, opts.width), L = Math.min(260, Math.max(120, W * 0.24)), R = 64, T = 26, H = T + n * RH + 8; - const xa = axis(points.map(p => p.y)), X = v => L + xa.at(v) * (W - L - R); + const xa = axis(points.map(p => p.y).concat(points.map(p => p.lo), points.map(p => p.hi))), X = v => L + xa.at(v) * (W - L - R); const svg = frame(W, H, axisWords(opts.yTitle, xa) + ' for ' + n + ' subjects, best first'); const grid = el('g', { class: 'grid' }), ax = el('g', { class: 'axis' }); xa.ticks.forEach((v, i) => { grid.appendChild(el('line', { x1: X(v), y1: T - 4, x2: X(v), y2: H - 8 })); ax.appendChild(el('text', { x: X(v), y: T - 10, 'text-anchor': i === xa.ticks.length - 1 && xa.ticks.length > 1 ? 'end' : 'middle' }, xa.label(v))); }); @@ -196,8 +197,10 @@ window.LabCharts = (() => { const max = Math.floor((L - 14) / 6.6), t = p.name.length > max ? p.name.slice(0, max - 1) + '…' : p.name; g.appendChild(el('text', { x: L - 10, y: cy + 4, 'text-anchor': 'end', class: 'rk' + (p.id === opts.selected ? ' on' : '') }, t)); g.appendChild(el('line', { x1: L, y1: cy, x2: cx, y2: cy, class: 'stem' })); - const hit = el('rect', { x: 0, y: cy - RH / 2, width: W, height: RH, class: 'hit band', tabindex: 0, role: 'button', 'data-id': p.id, 'aria-label': p.name + ', ' + opts.yTitle + ' ' + fmtSci(p.y) }); + const ci = p.lo != null && p.hi != null; + const hit = el('rect', { x: 0, y: cy - RH / 2, width: W, height: RH, class: 'hit band', tabindex: 0, role: 'button', 'data-id': p.id, 'aria-label': p.name + ', ' + opts.yTitle + ' ' + fmtSci(p.y) + (ci ? ', 95% interval ' + fmtSci(p.lo) + ' to ' + fmtSci(p.hi) : '') }); g.insertBefore(hit, g.firstChild); + if (ci) { const a = X(p.lo), b = X(p.hi), w = el('g', { class: 'ci', 'data-lo': p.lo, 'data-hi': p.hi }); w.appendChild(el('line', { x1: a, y1: cy, x2: b, y2: cy })); w.appendChild(el('line', { x1: a, y1: cy - 4, x2: a, y2: cy + 4 })); w.appendChild(el('line', { x1: b, y1: cy - 4, x2: b, y2: cy + 4 })); g.appendChild(w); } g.appendChild(el('circle', { cx, cy, r: 4.5, class: 'pt ' + p.kind + (p.dim ? ' dim' : '') })); if (p.id === opts.selected) g.appendChild(el('circle', { cx, cy, r: 8, class: 'sel' })); g.appendChild(el('text', { x: W - 4, y: cy + 4, 'text-anchor': 'end', class: 'rv' }, fmtSci(p.y))); diff --git a/static/project-workspace/compare.css b/static/project-workspace/compare.css new file mode 100644 index 00000000..a3d7b431 --- /dev/null +++ b/static/project-workspace/compare.css @@ -0,0 +1,86 @@ +/* The Compare tab, parallel coordinates and intervals (docs/plans/training-and-curation/spec-t3.md section 5), + on the tokens of base.css, so light and dark follow it. */ + +/* The compare set's fourth colour, and a model's colour in its column. */ +.cmp-chips .c.s4 i { background: var(--k-component); } +.cmpv .swatch, .cmpv-colhead .swatch { width: 10px; height: 10px; border-radius: 50%; display: inline-block; flex: none; margin-right: 6px; vertical-align: -1px; } +.s1 > .swatch { background: var(--k-architecture); } .s2 > .swatch { background: var(--k-refinement); } +.s3 > .swatch { background: var(--k-training-policy); } .s4 > .swatch { background: var(--k-component); } + +/* ---- The Compare tab ---- */ +.cmpv-head { display: grid; gap: 8px; min-width: 0; } +.cmpv-head .cmp-chips .iv-field { margin-left: 8px; font-size: 12.5px; color: var(--ink-2); } +.cmpv-empty { margin-top: 14px; } +.cmpv-table { margin-top: 18px; } +table.tv.cmpv { min-width: 100%; } +table.tv.cmpv th.cmpv-col { text-align: left; min-width: 150px; vertical-align: bottom; } +table.tv.cmpv th.cmpv-row { text-align: left; font-weight: 400; color: var(--ink-2); max-width: 340px; min-width: 120px; vertical-align: top; } +table.tv.cmpv tr.cmpv-group th { text-align: left; padding-top: 16px; font-weight: 600; color: var(--ink); border-bottom: 1px solid var(--line); } +table.tv.cmpv tr.cmpv-group .sum { margin-left: 10px; font-weight: 400; color: var(--ink-3); font-size: 12px; } +table.tv.cmpv td { vertical-align: top; } +.cmpv-path { display: block; overflow-wrap: anywhere; font-size: 12px; color: var(--ink); } +.cmpv-kind { display: block; } +td.cmpv-v { overflow-wrap: anywhere; max-width: 260px; font-size: 12px; } +table.tv.cmpv td.n { text-align: left; } +.cmpv-value { display: block; font-variant-numeric: tabular-nums; } +td .ci { display: block; font-size: 11.5px; color: var(--ink-3); font-weight: 400; font-variant-numeric: tabular-nums; white-space: nowrap; } +.cmpv-n { display: block; } +td.cmpv-on { color: var(--good); } +td.cmpv-nsig { color: var(--warn); } +.cmpv-out { margin-top: 26px; display: grid; gap: 10px; min-width: 0; } +.cmpv-out .sect { margin-bottom: 0; flex-wrap: wrap; } +.cmpv-outhead { display: grid; gap: 4px; min-width: 0; } +.cmpv-outhead p { margin: 0; overflow-wrap: anywhere; } +.cmpv-outhead select { max-width: min(520px, 100%); min-width: 0; } +.cmpv-grid { position: relative; display: grid; gap: 10px; min-width: 0; } +.cmpv-grid[aria-busy="true"] { cursor: progress; } +.cmpv-cells { display: grid; grid-template-columns: repeat(var(--cols, 3), minmax(0, 1fr)); gap: 10px; min-width: 0; } +.cmpv-colhead { font-size: 12.5px; font-weight: 600; color: var(--ink); overflow-wrap: anywhere; min-width: 0; } +.cmpv-orow { display: grid; gap: 4px; min-width: 0; } +.cmpv-otitle { display: flex; flex-wrap: wrap; gap: 4px 14px; align-items: center; min-width: 0; } +.cmpv-barbox { flex: 1 1 180px; max-width: 360px; min-width: 0; } +.cmpv-cell { margin: 0; min-width: 0; } +.cmpv-missing { margin: 0; padding: 10px 0; } +.cmpv-figs dl { margin: 0; display: grid; gap: 2px; font-size: 12px; } +.cmpv-figs dl > div { display: flex; justify-content: space-between; gap: 8px; min-width: 0; } +.cmpv-figs dt { color: var(--ink-2); overflow-wrap: anywhere; } +.cmpv-figs dd { margin: 0; font-variant-numeric: tabular-nums; } +.cmpv-where { margin: 0; } + +/* ---- Intervals on the charts ---- */ +.chart .ci line { stroke: var(--ink-3); stroke-width: 1.25; } +.chart .nsig { fill: none; stroke: var(--warn); stroke-width: 1.5; stroke-dasharray: 3 2; } + +/* ---- Parallel coordinates ---- */ +.pc { margin-top: 26px; min-width: 0; } +.pc .sect { flex-wrap: wrap; } +.pc-count { margin-left: auto; color: var(--ink-2); } +.pc-draw { min-width: 0; } +.pc-svg { display: block; width: 100%; height: auto; touch-action: none; } +.pc .pcl { fill: none; stroke: var(--k-component); stroke-width: 1.4; opacity: .7; } +.pc .pcl.training-policy { stroke: var(--k-training-policy); } +.pc .pcl.architecture { stroke: var(--k-architecture); } +.pc .pcl.refinement { stroke: var(--k-refinement); } +.pc .pcl.other, .pc .pcl.unset { stroke: var(--ink-3); } +.pc .pcl.out { opacity: .08; } +.pc .pcl.on { stroke-width: 3; opacity: 1; } +.pc .pc-line { stroke: var(--line-strong); stroke-width: 1; } +.pc .pc-title { fill: var(--ink); font-size: 11.5px; font-weight: 600; font-family: var(--font); } +.pc .pc-sub { fill: var(--ink-3); font-size: 10.5px; font-family: var(--font); } +.pc .pc-tick { fill: var(--ink-2); font-size: 10.5px; font-family: var(--font); paint-order: stroke; stroke: var(--surface); stroke-width: 3px; stroke-linejoin: round; } +.pc .pc-brush { fill: var(--accent); fill-opacity: .22; stroke: var(--accent); stroke-width: 1; } +.pc .pc-hit { fill: transparent; cursor: ns-resize; } +.pc-axes { display: flex; flex-wrap: wrap; gap: 6px; align-items: center; margin-top: 8px; } +.pc-ax { display: inline-flex; align-items: center; gap: 2px; padding: 1px 4px; border: 1px solid var(--line); border-radius: 999px; font-size: 12px; background: var(--surface); max-width: 100%; min-width: 0; } +.pc-ax.metric { border-color: var(--line-strong); } +.pc-ax .pc-name { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; max-width: 22ch; padding: 0 2px; } +.pc-ax button { border: 0; background: none; color: var(--ink-3); cursor: pointer; padding: 0 3px; font: inherit; line-height: 1.4; } +.pc-ax button:disabled { opacity: .3; cursor: default; } +.pc-ax button[aria-pressed="true"] { color: var(--accent); font-weight: 600; } +.pc-choose { margin-top: 8px; font-size: 12.5px; } +.pc-choose summary { cursor: pointer; color: var(--ink-2); } +.pc-list { list-style: none; margin: 6px 0 0; padding: 0; display: grid; gap: 2px; max-height: 260px; overflow: auto; } +.pc-list label { display: flex; gap: 6px; align-items: baseline; min-width: 0; } +.pc-list label .mono { overflow-wrap: anywhere; min-width: 0; } +.pc-filtered { margin: 0 0 6px; } +.chart g.pc-out > :not(.hit) { opacity: .15; } diff --git a/static/project-workspace/compare.js b/static/project-workspace/compare.js new file mode 100644 index 00000000..d0f4ad4d --- /dev/null +++ b/static/project-workspace/compare.js @@ -0,0 +1,342 @@ +'use strict'; +// The Compare tab (docs/plans/training-and-curation/spec-t3.md section 5.1), added to window.LabScreens: the page's +// compare set of two to four models, one column each. A table of who each model is (group, kind of change, the +// model it derives from, state, training date), what differs between their recipes (model_compare's differs: the +// settings, data and parent, only where they differ), and per benchmark that measures one of them its metrics with +// the tab's statistic, the 95 % interval from per-case values held here and the number of cases, the best of a row +// marked, and where each sits on the frontier of each tradeoff chart. Then the outputs: the cases the models' runs +// kept (spec-d6, fields.js's parts), matched by name; one case chosen; for each model its native field, its +// prediction and its signed error, three rows of panels with one colour scale a row (native and predicted share +// one), moved together by one control (the axis cut across, the position, "Remove the mean"). +// +// Updating in place (spec-w4): the tab is read and built like the others (tabs.js's paint) and put in place in one +// step; the person's moves through the outputs ask field_compare of every column at once (one round in flight, the +// latest wins) and draw the canvases again in place, keeping the case, axis, position and mean option in the +// address (cmpCase, cmpAxis, cmpIndex, cmpMeanFree). Choosing another case draws the tab again in place. +(() => { + const S = window.LabScreens, P = window.TuldokProject, Tree = window.LabTree, C = window.LabCharts, h = C.h; + const { sect, putInPlace, modelState } = S.parts; + const D = window.LabInside.drawing, R = P.product; + const F = () => window.LabFields.parts; + const fmt = C.fmtSci; + const STATISTICS = ['median', 'mean', 'p10', 'p90', 'min', 'max']; + const MOST = 4, CELL_MOST = 260; // models in the set; the CSS height of a panel at most + const button = (cls, text, onClick) => { const b = h('button', cls, text); b.type = 'button'; if (onClick) b.addEventListener('click', onClick); return b; }; + const units = m => m.units && m.units !== '1' ? ' (' + m.units + ')' : ''; + const shapeText = s => s && s.length ? s.join(' × ') : '—'; + const shown = v => v === undefined ? '—' : v === null ? 'null' : typeof v === 'object' ? JSON.stringify(v) : String(v); + const KIND_WORDS = { group: 'group', change: 'kind of change', parent: 'derives from', data: 'data', setting: 'setting' }; + const ui4 = ui => ({ anaAxis: ui.cmpAxis, anaIndex: ui.cmpIndex, anaMeanFree: ui.cmpMeanFree }); + + // ---- Reading ---------------------------------------------------------------------------------------------------- + /** + * The outputs the tab shows: every model's kept cases, the cases kept by two models or more (comparable, matched by + * name), the one chosen, the person's place in it and every column's first slice (null where the model did not + * keep it or kept another shape). + */ + async function readOutputs(models, ui) { + const Fp = F(); + const kept = await Promise.all(models.map(m => Fp.keptCases(m).catch(error => ({ none: true, error })))); + const byName = new Map(); + kept.forEach((k, i) => { + if (!k || k.none) return; + for (const c of k.cases) { if (!c.comparable) continue; if (!byName.has(c.name)) byName.set(c.name, models.map(() => null)); const row = byName.get(c.name); if (!row[i]) row[i] = c; } + }); + const shared = [...byName].map(([name, cols]) => ({ name, cols, n: cols.filter(Boolean).length, split: cols.find(Boolean).split || null })) + .filter(x => x.n >= 2).sort((a, b) => b.n - a.n || a.name.localeCompare(b.name)); + if (!shared.length) return { kept, shared, chosen: null }; + const chosen = shared.find(x => x.name === ui.cmpCase) || shared[0]; + const lead = chosen.cols.find(Boolean); + const view = Fp.viewFor(lead, !ui.cmpCase || chosen.name === ui.cmpCase ? ui4(ui) : { anaMeanFree: ui.cmpMeanFree }); + const answers = await Promise.all(chosen.cols.map(c => c && sameShape(c, lead) ? R.fieldCompare(c.run, Fp.argsOf(c, view)).catch(error => ({ error })) : null)); + return { kept, shared, chosen, lead, view, answers }; + } + const sameShape = (a, b) => a.shape.length === b.shape.length && a.shape.every((n, i) => n === b.shape[i]); + + // ---- The screen --------------------------------------------------------------------------------------------------- + function compare(main, aside, state, act, data) { + const ui = state.ui, sel = state.sel.compare || null, g = S.parts.graphFor(data.map); + const models = state.cmp.filter(k => g.byId.has(k)), others = state.cmp.filter(k => !g.byId.has(k)); + const stat = STATISTICS.includes(ui.stat) ? ui.stat : 'median'; + S.paint(main, async () => { + if (models.length < 2) return { models }; + const [cmp, outputs] = await Promise.all([P.read('model_compare', { recipes: models, statistic: stat }), readOutputs(models, ui)]); + return { models, cmp, outputs }; + }, (frag, got) => { + frag.appendChild(head(g, state, act, stat, others)); + if (got.models.length < 2) { + frag.appendChild(h('p', 'empty cmpv-empty', 'Choose two to four models to compare: Compare in a model\'s drawer on the Map or on the Benchmarks tab, or the boxes of the Benchmarks table.')); + return; + } + const list = got.models.map(id => g.byId.get(id)); + frag.appendChild(table(got.cmp, list, g, act, sel)); + frag.appendChild(outputs(got.outputs, list, act, ui)); + }); + if (!sel || !g.byId.has(sel)) { aside.textContent = ''; aside._for = null; return false; } + S.inspectorModel(aside, sel, act, data, ins => S.compareActs(ins, sel, state, act, 'compare')); + const ins = aside.querySelector('.inspector'); if (ins) S.compareActs(ins, sel, state, act, 'compare'); + return true; + } + + /** The set as chips with ×, Clear, and the statistic. */ + function head(g, state, act, stat, others) { + const box = h('div', 'cmpv-head'); + box.appendChild(sect('Compare', state.cmp.length + ' of ' + MOST + ' models')); + const chips = h('div', 'cmp-chips'); + state.cmp.forEach((k, i) => { + const m = g.byId.get(k), name = m ? Tree.nameOf(m) : k.replace(/^subject:/, ''); + const c = h('span', 'c s' + (i + 1)); c.appendChild(h('i')); c.appendChild(document.createTextNode(name)); + const x = button(null, '×', () => act.toggleCompare(k)); x.setAttribute('aria-label', 'Remove ' + name); x.dataset.key = 'cmpv-x-' + k; c.appendChild(x); chips.appendChild(c); + }); + if (state.cmp.length) { const clear = button('btn sm ghost', 'Clear', () => act.clearCompare()); clear.dataset.key = 'cmpv-clear'; chips.appendChild(clear); } + const s = h('select'); s.setAttribute('aria-label', 'Statistic'); s.dataset.key = 'cmpv-stat'; + for (const v of STATISTICS) { const o = h('option', null, v.charAt(0).toUpperCase() + v.slice(1)); o.value = v; o.selected = v === stat; s.appendChild(o); } + s.addEventListener('change', () => act.setUI('stat', s.value)); + const l = h('label', 'iv-field'); l.appendChild(document.createTextNode('Statistic')); l.appendChild(s); chips.appendChild(l); + box.appendChild(chips); + if (others.length) box.appendChild(h('p', 'small muted', others.map(k => k.replace(/^subject:/, '')).join(', ') + (others.length === 1 ? ' is a benchmark subject' : ' are benchmark subjects') + ' made from no recipe on the map, and left out here.')); + return box; + } + + // ---- The table: who, what differs, the metrics and the frontier ------------------------------------------------------- + function table(cmp, list, g, act, sel) { + const sec = h('section', 'cmpv-table'); + const t = h('table', 'tv cmpv'), thead = h('thead'), hr = h('tr'); + hr.appendChild(h('th', 'cmpv-row', '')); + list.forEach((m, i) => { + const th = h('th', 'cmpv-col s' + (i + 1)); th.dataset.model = m.id; + const b = button('linkish', Tree.nameOf(m), () => act.select(m.id === sel ? null : m.id)); b.dataset.key = 'cmpv-open-' + m.id; b.title = 'Open ' + m.title; + th.appendChild(h('i', 'swatch')); th.appendChild(b); hr.appendChild(th); + }); + thead.appendChild(hr); t.appendChild(thead); + const tb = h('tbody'), n = list.length; + const group = (title, extra) => { const tr = h('tr', 'cmpv-group'); const th = h('th', null, title); th.colSpan = n + 1; if (extra) th.appendChild(h('span', 'sum', extra)); tr.appendChild(th); tb.appendChild(tr); }; + const row = (label, cells, cls, labelCls) => { const tr = h('tr', cls || null); const th = h('th', 'cmpv-row' + (labelCls ? ' ' + labelCls : '')); if (typeof label === 'string') th.textContent = label; else th.appendChild(label); tr.appendChild(th); for (const c of cells) tr.appendChild(c); tb.appendChild(tr); return tr; }; + const td = (text, cls) => h('td', cls || null, text); + // Who. + group('Who'); + row('Group', list.map(m => td(m.groupTitle || '—'))); + row('Kind of change', list.map(m => { const c = h('td'); c.appendChild(h('span', 'chip ' + m.kind, P.kindLabel(m.kind))); return c; })); + row('Derives from', list.map(m => { const p = m.parent && g.byId.get(m.parent); return td(p ? Tree.nameOf(p) : m.parent || '—'); })); + row('State', list.map(m => { const c = h('td'); c.appendChild(modelState(m.state)); return c; })); + row('Trained', list.map(m => td(m.trainedAt ? P.day(m.trainedAt) : '—', 'nowrap'))); + // What differs. + group('What differs', cmp.differs.length + (cmp.more ? ' of ' + (cmp.differs.length + cmp.more) : '') + ' paths differ · ' + cmp.same + ' the same'); + if (!cmp.differs.length) row('Nothing', list.map(() => td('the same', 'small faint'))); + for (const d of cmp.differs) { + const label = h('span'); label.appendChild(h('span', 'mono cmpv-path', d.path)); label.appendChild(h('span', 'cmpv-kind small faint', KIND_WORDS[d.kind] || d.kind)); + const tr = row(label, d.values.map((v, i) => td(d.present[i] ? shown(v) : '—', 'mono cmpv-v' + (d.present[i] ? '' : ' faint'))), 'cmpv-diff'); + tr.dataset.path = d.path; tr.dataset.kind = d.kind; + } + if (cmp.more) row('…', list.map(() => td(cmp.more + ' more not listed', 'small faint'))); + // The benchmarks. + if (!cmp.benchmarks.length) { group('Results'); row('None', list.map(() => td('no benchmark measures it', 'small faint'))); } + for (const b of cmp.benchmarks) { + group(b.title, cmp.statistic + ' · 95 % interval from ' + cmp.resamples.toLocaleString('en-GB') + ' resamples of the per-case values held here'); + for (const metric of b.metrics) { + const values = b.models.map(c => c && c.values[metric.id] && c.values[metric.id].value != null ? c.values[metric.id].value : null).filter(v => v != null); + const best = !values.length || metric.better === 'none' ? null : metric.better === 'higher' ? Math.max(...values) : Math.min(...values); + const tr = row(metric.title + units(metric), b.models.map(c => { + const v = c && c.values[metric.id]; + if (!c) return td('not a subject', 'small faint'); + if (!v || v.value == null) return td('—', 'n faint'); + const cell = h('td', 'n' + (values.length > 1 && v.value === best ? ' best' : '')); + cell.appendChild(h('span', 'cmpv-value', fmt(v.value))); + if (v.low != null) { const ci = h('span', 'ci', fmt(v.low) + ' – ' + fmt(v.high)); ci.title = 'The 95 % interval of the ' + cmp.statistic + ' from ' + cmp.resamples + ' resamples of its per-case values (seed ' + cmp.seed + ')'; cell.appendChild(ci); cell.dataset.low = String(v.low); cell.dataset.high = String(v.high); } + if (v.count != null) cell.appendChild(h('span', 'cmpv-n small faint', v.count.toLocaleString('en-GB') + ' cases')); + cell.dataset.value = String(v.value); + return cell; + }), 'cmpv-metric'); + tr.dataset.benchmark = b.benchmark; tr.dataset.metric = metric.id; + } + for (const f of b.frontiers) { + const tr = row('Frontier · ' + f.title, f.models.map((r, i) => { + if (!b.models[i]) return td('not a subject', 'small faint'); + if (!r) return td('not drawn', 'small faint'); + const words = r.on ? 'on the frontier' + (r.not_separated_from.length ? ', not separated from ' + r.not_separated_from.join(', ') : '') : 'off the frontier'; + const cell = td(words, r.on ? (r.not_separated_from.length ? 'cmpv-nsig' : 'cmpv-on') : 'faint'); + cell.dataset.on = String(r.on); cell.dataset.nsig = r.not_separated_from.join(','); + return cell; + }), 'cmpv-front'); + tr.dataset.chart = f.chart; + } + } + t.appendChild(tb); + const wrap = h('div', 'tv-wrap'); wrap.appendChild(t); sec.appendChild(wrap); + return sec; + } + + // ---- The outputs ---------------------------------------------------------------------------------------------------- + const ROWS = [['reference', 'Native', 'reference_f32'], ['predicted', 'Predicted', 'predicted_f32'], ['error', 'Signed error (predicted − native)', 'error_f32']]; + function outputs(o, list, act, ui) { + const sec = h('section', 'cmpv-out'); sec.dataset.key = 'cmpv-out'; + if (!o.chosen) { + sec.appendChild(sect('Outputs')); + const said = list.map((m, i) => { const k = o.kept[i]; return Tree.nameOf(m) + ': ' + (!k ? 'no product on this machine' : k.none ? 'kept no fields' : k.cases.filter(c => c.comparable).length + ' comparable cases'); }); + sec.appendChild(h('p', 'empty cmpv-none', 'No case is kept by two of these models. ' + said.join('; ') + '.')); + return sec; + } + const c = o.chosen, lead = o.lead, ctx = { o, list, act, view: o.view, answers: o.answers.slice(), busy: false, again: false }; + sec.appendChild(sect('Outputs', c.name + (c.split ? ' · ' + c.split : '') + ' · kept by ' + c.n + ' of ' + list.length)); + const hd = h('div', 'cmpv-outhead'); + if (o.shared.length > 1) { + const s = h('select'); s.setAttribute('aria-label', 'Case'); s.dataset.key = 'cmpv-case'; + for (const x of o.shared) { const op = h('option', null, x.name + (x.split ? ' · ' + x.split : '') + ' · ' + x.n + ' of ' + list.length); op.value = x.name; op.selected = x === c; s.appendChild(op); } + s.addEventListener('change', () => { act.keepUI('cmpAxis', null); act.keepUI('cmpIndex', null); act.setUI('cmpCase', s.value); }); + const l = h('label', 'iv-field'); l.appendChild(document.createTextNode('Case')); l.appendChild(s); hd.appendChild(l); + } else hd.appendChild(h('p', 'mono cmpv-casename', c.name)); + hd.appendChild(h('p', 'small muted', [shapeText(lead.shape), lead.dtype, 'the native field of each model\'s own run'].filter(Boolean).join(' · '))); + sec.appendChild(hd); + ctx.ctl = h('div', 'iv-ctl cmpv-ctl'); controls(ctx); sec.appendChild(ctx.ctl); + ctx.grid = grid(ctx); sec.appendChild(ctx.grid); + ctx.say = h('p', 'small muted cmpv-where'); sec.appendChild(ctx.say); + ctx.err = h('div', 'cmpv-err'); sec.appendChild(ctx.err); + redraw(ctx, false); + return sec; + } + /** The one control of every column: the axis, the sliders of the axes not drawn and "Remove the mean". */ + function controls(ctx) { + const Fp = F(), lead = ctx.o.lead, v = ctx.view, nd = lead.shape.length, names = Fp.axisNames(nd), items = []; + if (nd >= 3) { + const s = h('select'); s.setAttribute('aria-label', 'The axis cut across, for every model'); s.dataset.key = 'cmpv-axis'; + for (let a = 0; a < nd; a++) { const op = h('option', null, names[a] + ' (' + lead.shape[a] + ')'); op.value = String(a); op.selected = a === v.axis; s.appendChild(op); } + s.addEventListener('change', () => { v.axis = Number(s.value); ctx.act.keepUI('cmpAxis', String(v.axis)); controls(ctx); ask(ctx); }); + const l = h('label', 'iv-field'); l.appendChild(document.createTextNode('Cut across')); l.appendChild(s); items.push(l); + for (const a of Fp.fixedAxes(nd, v.axis)) { + const l2 = h('label', 'iv-field iv-slider'); l2.appendChild(h('span', null, a === v.axis ? 'Position on ' + names[a] : names[a])); + const r = h('input'); r.type = 'range'; r.min = '0'; r.max = String(lead.shape[a] - 1); r.value = String(v.index[a]); r.dataset.key = 'cmpv-slider-' + a; r.dataset.axis = String(a); + r.setAttribute('aria-label', 'Position on ' + names[a] + ' for every model, 0 to ' + (lead.shape[a] - 1)); + const at = h('span', 'num small', v.index[a] + ' of ' + lead.shape[a]); + r.addEventListener('input', () => { v.index[a] = Number(r.value); at.textContent = v.index[a] + ' of ' + lead.shape[a]; ctx.act.keepUI('cmpIndex', v.index.join(',')); ask(ctx); }); + l2.appendChild(r); l2.appendChild(at); items.push(l2); + } + } + const mean = button('btn sm', 'Remove the mean', () => { v.meanFree = !v.meanFree; mean.setAttribute('aria-pressed', String(v.meanFree)); ctx.act.keepUI('cmpMeanFree', v.meanFree ? '1' : null); ask(ctx); }); + mean.dataset.key = 'cmpv-mean'; mean.setAttribute('aria-pressed', String(v.meanFree)); mean.title = 'Take each field\'s mean from it before the error is formed, in every column'; + items.push(mean); + if (ctx.ctl.isConnected) { const frag = document.createDocumentFragment(); frag.append(...items); putInPlace(ctx.ctl, frag, document.getElementById('main')); } + else ctx.ctl.replaceChildren(...items); + } + /** Asks field_compare of every column for the place: one round in flight; a move meanwhile waits, the latest wins. */ + function ask(ctx) { + if (ctx.busy) { ctx.again = true; return; } + ctx.busy = true; ctx.again = false; ctx.grid.setAttribute('aria-busy', 'true'); + const Fp = F(), cols = ctx.o.chosen.cols, lead = ctx.o.lead; + Promise.all(cols.map(c => c && sameShape(c, lead) ? R.fieldCompare(c.run, Fp.argsOf(c, ctx.view), true).catch(error => ({ error })) : null)).then(answers => { + if (ctx.again || !ctx.grid.isConnected) return; + ctx.answers = answers; redraw(ctx, true); + }).finally(() => { + ctx.busy = false; + if (ctx.again && ctx.grid.isConnected) ask(ctx); else ctx.grid.removeAttribute('aria-busy'); + }); + } + + /** Three rows of panels, a column per model, a colour bar a row, the figures under each column. */ + function grid(ctx) { + const { list, o } = ctx, n = list.length, wrap = h('div', 'cmpv-grid'); wrap.style.setProperty('--cols', String(n)); + ctx.cells = {}; ctx.bars = {}; + const heads = h('div', 'cmpv-cells cmpv-heads'); + list.forEach((m, i) => { const d = h('div', 'cmpv-colhead s' + (i + 1)); d.appendChild(h('i', 'swatch')); d.appendChild(h('span', null, Tree.nameOf(m))); heads.appendChild(d); }); + wrap.appendChild(heads); + for (const [id, title] of ROWS) { + const rowEl = h('div', 'cmpv-orow'); rowEl.dataset.row = id; + const top = h('div', 'cmpv-otitle'); top.appendChild(h('span', 'fld-title', title)); + const bar = h('canvas', 'fld-bar cmpv-bar'); bar.setAttribute('aria-hidden', 'true'); const ends = h('div', 'iv-ends small faint cmpv-ends'); + const barBox = h('div', 'cmpv-barbox'); barBox.appendChild(bar); barBox.appendChild(ends); top.appendChild(barBox); + rowEl.appendChild(top); + ctx.bars[id] = { bar, ends }; D.paints(bar, () => drawBar(ctx, id)); + const cells = h('div', 'cmpv-cells'); + list.forEach((m, i) => { + const fig = h('figure', 'cmpv-cell'); fig.dataset.model = m.id; fig.dataset.row = id; + const c = o.chosen.cols[i]; + if (!c) fig.appendChild(h('p', 'small faint cmpv-missing', 'Not kept by this model.')); + else if (!sameShape(c, o.lead)) fig.appendChild(h('p', 'small faint cmpv-missing', 'Kept with another shape (' + shapeText(c.shape) + '), not drawn.')); + else { + const cv = h('canvas', 'fld-cv cmpv-cv'); cv.setAttribute('role', 'img'); cv.dataset.model = m.id; cv.dataset.row = id; fig.appendChild(cv); + ctx.cells[id + ' ' + i] = { cv, i, id }; + D.paints(cv, () => drawCell(ctx, id, i)); + cv.addEventListener('mousemove', ev => hover(ctx, id, i, ev)); cv.addEventListener('mouseleave', () => { ctx.tip.hidden = true; }); + } + cells.appendChild(fig); + }); + rowEl.appendChild(cells); wrap.appendChild(rowEl); + } + ctx.figs = h('div', 'cmpv-cells cmpv-figs'); wrap.appendChild(ctx.figs); + ctx.tip = h('div', 'fld-tip cmpv-tip'); ctx.tip.hidden = true; ctx.tip.setAttribute('role', 'status'); wrap.appendChild(ctx.tip); + return wrap; + } + /** The answers as floats, one scale a row over every column: native and predicted share one, the errors one diverging about zero. */ + function decode(ctx) { + const Fp = F(), got = ctx.answers.filter(a => a && !a.error); + const lows = got.map(a => a.range && a.range[0]).filter(v => v != null), highs = got.map(a => a.range && a.range[1]).filter(v => v != null); + ctx.range = lows.length ? [Math.min(...lows), Math.max(...highs)] : [0, 0]; + ctx.limit = Math.max(0, ...got.map(a => a.error_limit || 0)); + ctx.values = ctx.answers.map(a => a && !a.error ? { reference: D.floats(a.reference_f32), predicted: D.floats(a.predicted_f32), error: D.floats(a.error_f32) } : null); + const seq = Fp.sequential(ctx.range[0], ctx.range[1]); + ctx.scale = { reference: seq, predicted: seq, error: Fp.diverging(ctx.limit) }; + } + function redraw(ctx, draw) { + decode(ctx); + const Fp = F(), lead = ctx.o.lead, nd = lead.shape.length, names = Fp.axisNames(nd), first = ctx.answers.find(a => a && !a.error); + const where = !first ? '' : nd >= 3 ? 'through ' + first.axes.map(x => names[x]).join(' and ') + ' at ' + Fp.fixedAxes(nd, first.axis).map(x => names[x] + ' = ' + first.index[x]).join(', ') : nd === 2 ? 'the whole field' : 'the whole line'; + for (const { cv, i, id } of Object.values(ctx.cells)) { + const a = ctx.answers[i]; + cv.setAttribute('aria-label', ROWS.find(r => r[0] === id)[1] + ' of ' + Tree.nameOf(ctx.list[i]) + (a && !a.error ? ', ' + a.rows + ' by ' + a.columns + ' cells ' + where : ', not read')); + if (draw) drawCell(ctx, id, i); + } + ctx.bars.reference.ends.replaceChildren(...[fmt(ctx.range[0]), 'native and predicted, every column', fmt(ctx.range[1])].map(t => h('span', null, t))); + ctx.bars.predicted.ends.replaceChildren(...[fmt(ctx.range[0]), 'the same scale', fmt(ctx.range[1])].map(t => h('span', null, t))); + ctx.bars.error.ends.replaceChildren(...['−' + fmt(ctx.limit), '0', '+' + fmt(ctx.limit)].map(t => h('span', null, t))); + if (draw) for (const id of Object.keys(ctx.bars)) drawBar(ctx, id); + ctx.say.textContent = first ? 'A slice ' + where + (first.stride > 1 ? ', every ' + D.ordinal(first.stride) + ' row and column' : '') + ' of each model\'s field; one scale for native and predicted from ' + fmt(ctx.range[0]) + ' to ' + fmt(ctx.range[1]) + ', the errors on ±' + fmt(ctx.limit) + ' about zero' + (first.mean_free ? ', each field\'s mean removed first' : '') + '.' : ''; + const errors = ctx.answers.filter(a => a && a.error); + ctx.err.replaceChildren(...errors.slice(0, 1).map(a => window.LabActions.refusal(a.error))); + figures(ctx); + if (first) { ctx.grid.dataset.index = JSON.stringify(first.index); ctx.grid.dataset.axis = String(first.axis); ctx.grid.dataset.meanFree = String(first.mean_free); } + } + function drawCell(ctx, id, i) { + const cell = ctx.cells[id + ' ' + i], a = ctx.answers[i], vals = ctx.values && ctx.values[i]; if (!cell || !a || a.error || !vals) return; + const cv = cell.cv, w = cv.clientWidth; if (!w) return; + const cssH = a.rows === 1 ? 28 : Math.max(32, Math.min(CELL_MOST, Math.round(w * a.rows / a.columns))); + const size = D.fit(cv, cssH); if (!size) return; const gx = cv.getContext('2d'); gx.clearRect(0, 0, size[0], size[1]); + const rect = a.rows === 1 ? [0, 0, size[0], size[1]] : D.contain(a.rows, a.columns, size[0], size[1]); + cell.rect = rect.map(x => x / (window.devicePixelRatio || 1)); + D.heat(gx, vals[id], a.rows, a.columns, ctx.scale[id], rect[0], rect[1], rect[2], rect[3]); + cv.dataset.drawn = String((cv._drawn = (cv._drawn || 0) + 1)); + } + function drawBar(ctx, id) { + const b = ctx.bars[id], size = D.fit(b.bar, 10); if (!size) return; + const n = 64, vals = new Float32Array(n), m = ctx.limit || 0, range = ctx.range || [0, 0]; + for (let i = 0; i < n; i++) { const t = (i + 0.5) / n; vals[i] = id === 'error' ? -m + 2 * m * t : range[0] + (range[1] - range[0]) * t; } + D.heat(b.bar.getContext('2d'), vals, 1, n, ctx.scale[id], 0, 0, size[0], size[1]); + } + function hover(ctx, id, i, ev) { + const cell = ctx.cells[id + ' ' + i], a = ctx.answers[i]; if (!cell || !cell.rect || !a || a.error) return; + const box = cell.cv.getBoundingClientRect(), x = ev.clientX - box.left - cell.rect[0], y = ev.clientY - box.top - cell.rect[1]; + const col = Math.floor(x / cell.rect[2] * a.columns), row = Math.floor(y / cell.rect[3] * a.rows); + if (col < 0 || row < 0 || col >= a.columns || row >= a.rows) { ctx.tip.hidden = true; return; } + const k = row * a.columns + col, at = a.index.slice(), nd = ctx.o.lead.shape.length, names = F().axisNames(nd), v = ctx.values[i]; + if (nd === 1) at[0] = col * a.stride; else { at[a.axes[0]] = row * a.stride; at[a.axes[1]] = col * a.stride; } + ctx.tip.replaceChildren(h('b', null, Tree.nameOf(ctx.list[i])), h('div', 'mono fld-tip-at', nd === 3 ? at.map((q, j) => names[j] + ' ' + q).join(', ') : '(' + at.join(', ') + ')')); + for (const [key, word] of [['reference', 'Native'], ['predicted', 'Predicted'], ['error', a.mean_free ? 'Error, means removed' : 'Error']]) { const r = h('div', 'fld-tip-row'); r.dataset.value = key; r.appendChild(h('span', null, word)); r.appendChild(h('span', 'num', fmt(v[key][k]))); ctx.tip.appendChild(r); } + ctx.tip.dataset.cell = JSON.stringify(at); ctx.tip.dataset.model = ctx.list[i].id; + ctx.tip.hidden = false; + const wrap = ctx.grid.getBoundingClientRect(), tw = ctx.tip.offsetWidth; + let left = ev.clientX - wrap.left + 14; if (left + tw > wrap.width) left = Math.max(0, ev.clientX - wrap.left - tw - 14); + ctx.tip.style.left = left + 'px'; ctx.tip.style.top = (ev.clientY - wrap.top + 14) + 'px'; + } + const FIGURES = [['relative_l2', 'Relative L2'], ['mean_free_relative_l2', 'Mean-free relative L2'], ['rmse', 'RMSE'], ['max_abs_error', 'Largest |error|']]; + /** The whole-field figures under each column. */ + function figures(ctx) { + const items = ctx.answers.map((a, i) => { + const box = h('div', 'cmpv-fig'); box.dataset.model = ctx.list[i].id; + if (!a || a.error) { box.appendChild(h('p', 'small faint', a && a.error ? 'Not read.' : '—')); return box; } + const dl = h('dl', 'cmpv-figdl'); + for (const [key, word] of FIGURES) { const d = h('div'); d.dataset.fig = key; d.dataset.value = a.figures[key] == null ? '' : String(a.figures[key]); d.appendChild(h('dt', null, word)); d.appendChild(h('dd', 'num', fmt(a.figures[key]))); dl.appendChild(d); } + box.appendChild(dl); return box; + }); + ctx.figs.replaceChildren(...items); + } + + S.compare = compare; +})(); diff --git a/static/project-workspace/fields.js b/static/project-workspace/fields.js index 97089991..86d5f7a8 100644 --- a/static/project-workspace/fields.js +++ b/static/project-workspace/fields.js @@ -56,6 +56,25 @@ window.LabFields = (() => { * person's place in it and its first slice. */ async function read(recipe, ui) { + const found = await keptCases(recipe); + if (!found || found.none) return found; + const cases = found.cases; + const chosen = cases.find(c => c.key === ui.anaCase) || cases.find(c => c.comparable) || cases[0]; + const out = { cases, chosen, view: null, cmp: null, error: null }; + if (chosen.comparable) { + out.view = viewFor(chosen, !ui.anaCase || chosen.key === ui.anaCase ? ui : {}); + try { out.cmp = await R.fieldCompare(chosen.run, argsOf(chosen, out.view)); } catch (error) { out.error = error; } + } + return out; + } + + /** + * The cases kept by every current product of a recipe's model: null when it has no current product, { none } when + * none of them keeps fields (with the first refusal, or empty when an index lists no case), else { cases }, each + * case as fields lists it with its run, subject, key, the run's reported figures and a label. Shared with the + * Compare tab (compare.js, spec-t3 section 5.1). + */ + async function keptCases(recipe) { if (!recipe) return null; const products = (await P.read('products', { reference: recipe })).products.filter(p => p.run_id); if (!products.length) return null; @@ -65,13 +84,7 @@ window.LabFields = (() => { const several = kept.length > 1; const cases = kept.flatMap(g => g.f.cases.map(c => Object.assign({}, c, { run: g.p.run_id, subject: g.p.subject || '', key: keyOf(g.p.run_id, c.entry, c.case), reported: g.f.reported, label: c.name + (several && g.p.subject ? ' · ' + g.p.subject : '') }))); if (!cases.length) return { none: true, empty: true, run: kept[0].p.run_id }; - const chosen = cases.find(c => c.key === ui.anaCase) || cases.find(c => c.comparable) || cases[0]; - const out = { cases, chosen, view: null, cmp: null, error: null }; - if (chosen.comparable) { - out.view = viewFor(chosen, !ui.anaCase || chosen.key === ui.anaCase ? ui : {}); - try { out.cmp = await R.fieldCompare(chosen.run, argsOf(chosen, out.view)); } catch (error) { out.error = error; } - } - return out; + return { cases }; } // ---- The section ---------------------------------------------------------------------------------------------------- @@ -263,5 +276,8 @@ window.LabFields = (() => { ctx.figs.replaceChildren(...items); } - return { read, section }; + // The parts the Compare tab draws its outputs with (compare.js): the cases, the person's place in one, the request's + // arguments, the axes' names and the colour scales. + const parts = { keptCases, viewFor, argsOf, axisNames, fixedAxes, sequential, diverging, PANEL_MOST }; + return { read, section, parts }; })(); diff --git a/static/project-workspace/parallel.js b/static/project-workspace/parallel.js new file mode 100644 index 00000000..6b449af6 --- /dev/null +++ b/static/project-workspace/parallel.js @@ -0,0 +1,218 @@ +'use strict'; +// Parallel coordinates on the Benchmarks tab (docs/plans/training-and-curation/spec-t3.md section 5.2): one vertical +// axis per metric of the benchmark and per recipe setting that varies between its subjects (benchmark_axes), one +// line per subject in its kind of change's colour. The person chooses the axes (at most twelve; the metrics and the +// six settings that go most with the first metric to begin with), moves them left and right, puts a metric whose +// values are all positive on a logarithmic scale, and drags a range on any axis: the lines outside every range are +// faint, the subjects table hides their rows and the charts above draw their points faint. A click on an axis +// without a drag clears its range; "Clear ranges" clears all. +// +// Updating in place (spec-w4): the section is built with the tab (tabs.js's paint) from the tab's settings +// (pcAxes, pcLog, pcBrush, kept per benchmark in state.ui), so a reading that changed something draws it again where +// the person left it. The person's own moves touch only this section (drawn again in place) and, for a range, the +// table's rows and the charts' marks (apply()); nothing is read again. +window.LabParallel = (() => { + const C = window.LabCharts, h = C.h, el = C.el, S = window.LabScreens; + const MOST = 12, SETTINGS_FIRST = 6, H = 300, T = 46, B = 30; + const fmt = C.fmtSci; + let last = null; // the benchmark drawn last: { benchmark, data, axes } (apply() reads it) + const button = (cls, text, onClick, key, label) => { const b = h('button', cls, text); b.type = 'button'; if (key) b.dataset.key = key; if (label) b.setAttribute('aria-label', label); if (onClick) b.addEventListener('click', onClick); return b; }; + const tail = path => { const m = path.match(/([^.\[\]]+|\[[^\]]*\])$/); return m ? m[1].replace(/^\["?|"?\]$/g, '') : path; }; + + /** Every axis the answer offers, metrics first: id, kind (metric, number, category), titles and range. */ + function axesOf(data) { + const out = data.metrics.map(m => ({ id: 'm:' + m.id, kind: 'metric', title: m.title, short: m.title, low: m.low, high: m.high, positive: m.positive, better: m.better, units: m.units, key: m.id })); + for (const s of data.settings) out.push({ id: 's:' + s.path, kind: s.kind, title: s.path, short: tail(s.path), low: s.low, high: s.high, categories: s.categories, association: s.association, positive: s.kind === 'number' && s.low > 0, key: s.path, count: s.count }); + return out; + } + const defaults = all => all.filter(a => a.kind === 'metric').concat(all.filter(a => a.kind !== 'metric').slice(0, SETTINGS_FIRST)).slice(0, MOST).map(a => a.id); + /** The axes shown, in the person's order: those of the tab's settings that this benchmark has, else the defaults. */ + function shownAxes(all, ui) { + const byId = new Map(all.map(a => [a.id, a])); + const kept = Array.isArray(ui.pcAxes) ? ui.pcAxes.filter(id => byId.has(id)).slice(0, MOST) : []; + return (kept.length ? kept : defaults(all)).map(id => byId.get(id)); + } + const valueOf = (row, a) => { const v = a.kind === 'metric' ? row.metrics[a.key] : row.settings[a.key]; return v == null ? null : v; }; + const isLog = (a, ui) => a.positive && (ui.pcLog || []).includes(a.id) && a.low > 0 && a.high > a.low; + /** The axis's scale: t(v) in [0, 1] from its low to its high end, and back. */ + function scaleOf(a, ui) { + const lo = a.low, hi = a.high; + if (lo == null || hi == null) return { t: () => 0.5, v: () => null }; + if (isLog(a, ui)) { const l0 = Math.log10(lo), l1 = Math.log10(hi); return { t: v => (Math.log10(Math.max(v, lo)) - l0) / (l1 - l0), v: t => Math.pow(10, l0 + t * (l1 - l0)) }; } + if (hi === lo) return { t: () => 0.5, v: () => lo }; + return { t: v => (v - lo) / (hi - lo), v: t => lo + t * (hi - lo) }; + } + /** The ranges drawn, of axes that exist: {id: [low, high]}. */ + function rangesOf(all, ui) { const ids = new Set(all.map(a => a.id)), out = {}; for (const [id, r] of Object.entries(ui.pcBrush || {})) if (ids.has(id) && Array.isArray(r) && r.length === 2) out[id] = r; return out; } + /** The names of the subjects inside every range, or null when no range is drawn. */ + function keptOf(data, all, ui) { + const ranges = rangesOf(all, ui), ids = Object.keys(ranges); if (!ids.length) return null; + const byId = new Map(all.map(a => [a.id, a])), keep = new Set(); + for (const row of data.subjects) if (ids.every(id => { const v = valueOf(row, byId.get(id)); return v != null && v >= ranges[id][0] && v <= ranges[id][1]; })) keep.add(row.subject); + return keep; + } + + // ---- The section ------------------------------------------------------------------------------------------------ + function section(data, view, state, act, width) { + const ui = state.ui; + if (ui.pcFor !== data.benchmark) { ui.pcFor = data.benchmark; ui.pcAxes = null; ui.pcLog = null; ui.pcBrush = null; } // the settings are per benchmark + const all = axesOf(data); + last = { benchmark: data.benchmark, data, all }; + const sec = h('section', 'pc'); sec.dataset.key = 'pc'; + const ctx = { data, view, state, act, width, sec, all }; + fill(ctx); + return sec; + } + /** Builds the section's content (put in place when it is on the page). */ + function fill(ctx) { + const { data, state, sec, all } = ctx, ui = state.ui, axes = shownAxes(all, ui), keep = keptOf(data, all, ui); + const items = []; + const head = S.parts.sect('Settings and metrics', data.subjects.length + ' subjects · ' + axes.length + ' of ' + all.length + ' axes'); + const count = h('span', 'pc-count small'); count.setAttribute('aria-live', 'polite'); head.appendChild(count); ctx.count = count; + items.push(head); + items.push(h('p', 'small faint bench-desc', 'One line per subject through its metrics (the ' + data.statistic + ' over its cases) and the recipe settings that vary between subjects. Drag along an axis to keep the subjects inside a range; the table and the charts above follow. ' + (data.left_out ? data.left_out + ' more settings are not offered.' : ''))); + const host = h('div', 'pc-draw'); ctx.host = host; items.push(host); + items.push(axisControls(ctx, axes)); + items.push(chooser(ctx, axes)); + draw(ctx, axes, keep); + setCount(ctx, keep); + if (sec.isConnected) { const frag = document.createDocumentFragment(); frag.append(...items); S.parts.putInPlace(sec, frag, document.getElementById('main')); } + else sec.replaceChildren(...items); + } + function setCount(ctx, keep) { + const n = ctx.data.subjects.length, text = keep ? keep.size + ' of ' + n + ' inside the ranges' : 'no range drawn'; + if (ctx.count.textContent !== text) ctx.count.textContent = text; + ctx.count.dataset.kept = keep ? String(keep.size) : ''; + } + + /** The SVG: the axes, their names and ends, the lines, the ranges, and the axes' hit areas for dragging. */ + function draw(ctx, axes, keep) { + const { data, view, state, host } = ctx, ui = state.ui, W = Math.max(320, ctx.width), k = axes.length; + const L = 30, R = 30, X = i => k > 1 ? L + i * (W - L - R) / (k - 1) : W / 2, Y = t => T + (1 - t) * (H - T - B); + const gap = k > 1 ? (W - L - R) / (k - 1) : W, chars = Math.max(4, Math.floor(gap / 6.4) - 1); + const cut = (t, n) => t.length > n ? t.slice(0, Math.max(1, n - 1)) + '…' : t; + const svg = el('svg', { viewBox: `0 0 ${W} ${H}`, role: 'group', 'aria-label': 'Parallel coordinates: ' + data.subjects.length + ' subjects through ' + k + ' axes: ' + axes.map(a => a.short).join(', '), class: 'pc-svg' }); + const scales = axes.map(a => scaleOf(a, ui)); + // The lines. + const lines = el('g', { class: 'pc-lines' }); + const sel = state.sel.benchmarks || null; + for (const row of data.subjects) { + const s = view.byName.get(row.subject), kind = s ? s.kind : 'other'; + let d = '', open = false; + axes.forEach((a, i) => { const v = valueOf(row, a); if (v == null || !Number.isFinite(v)) { open = false; return; } d += (open ? 'L' : 'M') + X(i).toFixed(1) + ',' + Y(scales[i].t(v)).toFixed(1); open = true; }); + if (!d) continue; + const on = s && s.key === sel; + const p = el('path', { d, class: 'pcl ' + kind + (keep && !keep.has(row.subject) ? ' out' : '') + (on ? ' on' : ''), 'data-subject': row.subject }); + p.appendChild(el('title', {}, (s ? s.full : row.title) + ': ' + axes.map(a => a.short + ' ' + shownValue(a, valueOf(row, a))).join(', '))); + lines.appendChild(p); + } + svg.appendChild(lines); + // The axes. + const ranges = rangesOf(ctx.all, ui); + axes.forEach((a, i) => { + const x = X(i), g = el('g', { class: 'pc-axis', 'data-axis': a.id }), right = i < k - 1 || k === 1, anchor = right ? 'start' : 'end', dx = right ? 5 : -5; + g.appendChild(el('line', { x1: x, y1: Y(0), x2: x, y2: Y(1), class: 'pc-line' })); + const title = el('text', { x, y: 14, 'text-anchor': i === 0 && k > 1 ? 'start' : i === k - 1 && k > 1 ? 'end' : 'middle', class: 'pc-title' }, cut(a.short, chars)); + title.appendChild(el('title', {}, a.title + (a.kind === 'metric' ? '' : ' (' + a.kind + ')'))); + g.appendChild(title); + const sub = a.kind === 'metric' ? (a.better === 'lower' ? 'lower better' : a.better === 'higher' ? 'higher better' : '') + (isLog(a, ui) ? ' · log' : '') : a.association == null ? '' : 'ρ ' + a.association.toFixed(2); + g.appendChild(el('text', { x, y: 28, 'text-anchor': i === 0 && k > 1 ? 'start' : i === k - 1 && k > 1 ? 'end' : 'middle', class: 'pc-sub' }, cut(sub, chars))); + if (a.kind === 'category') { + const n = a.categories.length, every = Math.max(1, Math.ceil(n / Math.max(1, Math.floor((H - T - B) / 13)))); + a.categories.forEach((c, j) => { if (j % every && j !== n - 1) return; g.appendChild(el('text', { x: x + dx, y: Y(n > 1 ? j / (n - 1) : 0.5) + 4, 'text-anchor': anchor, class: 'pc-tick' }, cut(typeof c === 'string' ? c : JSON.stringify(c), Math.min(12, chars)))); }); + } else if (a.low != null) { + g.appendChild(el('text', { x: x + dx, y: Y(1) + 4, 'text-anchor': anchor, class: 'pc-tick' }, fmt(a.high))); + g.appendChild(el('text', { x: x + dx, y: Y(0) + 4, 'text-anchor': anchor, class: 'pc-tick' }, fmt(a.low))); + } + const r = ranges[a.id]; + if (r) { const y0 = Y(scales[i].t(r[1])), y1 = Y(scales[i].t(r[0])); g.appendChild(el('rect', { x: x - 7, y: Math.min(y0, y1), width: 14, height: Math.max(2, Math.abs(y1 - y0)), class: 'pc-brush', 'data-low': r[0], 'data-high': r[1] })); } + const hit = el('rect', { x: x - 12, y: Y(1) - 6, width: 24, height: Y(0) - Y(1) + 12, class: 'pc-hit', 'data-axis': a.id }); + hit.appendChild(el('title', {}, 'Drag to keep a range of ' + a.title + '; a click clears it')); + g.appendChild(hit); + brushing(ctx, hit, g, a, scales[i], Y, x); + svg.appendChild(g); + }); + host.replaceChildren(svg); + ctx.svg = svg; + } + const shownValue = (a, v) => v == null ? '—' : a.kind === 'category' ? (c => typeof c === 'string' ? c : JSON.stringify(c))(a.categories[v]) : fmt(v); + + /** A range dragged on an axis: kept in the tab's settings, the lines, the table and the charts set in place. */ + function brushing(ctx, hit, g, a, scale, Y, x) { + let start = null, box = null; + const at = ev => { const pt = ctx.svg.createSVGPoint(); pt.x = ev.clientX; pt.y = ev.clientY; return pt.matrixTransform(ctx.svg.getScreenCTM().inverse()).y; }; + const clamp = y => Math.min(Y(0), Math.max(Y(1), y)); + hit.addEventListener('pointerdown', ev => { + ev.preventDefault(); start = clamp(at(ev)); try { hit.setPointerCapture(ev.pointerId); } catch (e) { /* a synthetic pointer */ } + box = el('rect', { x: x - 7, y: start, width: 14, height: 0, class: 'pc-brush pc-dragging' }); g.insertBefore(box, hit); + }); + hit.addEventListener('pointermove', ev => { if (start === null) return; const y = clamp(at(ev)); box.setAttribute('y', String(Math.min(start, y))); box.setAttribute('height', String(Math.abs(y - start))); }); + const end = ev => { + if (start === null) return; + const y = clamp(at(ev)), moved = Math.abs(y - start) >= 3, ui = ctx.state.ui, ranges = Object.assign({}, ui.pcBrush || {}); + const y0 = start; start = null; + if (moved) { const t0 = (Y(0) - Math.max(y, y0)) / (Y(0) - Y(1)), t1 = (Y(0) - Math.min(y, y0)) / (Y(0) - Y(1)); ranges[a.id] = [scale.v(t0), scale.v(t1)]; } + else delete ranges[a.id]; + ctx.act.keepUI('pcBrush', Object.keys(ranges).length ? ranges : null); + fill(ctx); apply(document.getElementById('main'), ctx.view, ctx.state); + }; + hit.addEventListener('pointerup', end); + hit.addEventListener('pointercancel', () => { start = null; if (box) box.remove(); }); + } + + /** The chosen axes in order, each moved left or right, put on a log scale or taken away; and Clear ranges. */ + function axisControls(ctx, axes) { + const ui = ctx.state.ui, box = h('div', 'pc-axes'), ids = axes.map(a => a.id); + const set = (k, v) => { ctx.act.keepUI(k, v); fill(ctx); apply(document.getElementById('main'), ctx.view, ctx.state); }; + axes.forEach((a, i) => { + const chip = h('span', 'pc-ax' + (a.kind === 'metric' ? ' metric' : '')); chip.dataset.axis = a.id; + const move = (d) => { const next = ids.slice(); next.splice(i, 1); next.splice(i + d, 0, a.id); set('pcAxes', next); }; + const left = button('pc-mv', '◀', () => move(-1), 'pc-left-' + a.id, 'Move ' + a.short + ' left'); left.disabled = i === 0; chip.appendChild(left); + const name = h('span', 'pc-name', a.short); name.title = a.title; chip.appendChild(name); + const right = button('pc-mv', '▶', () => move(1), 'pc-right-' + a.id, 'Move ' + a.short + ' right'); right.disabled = i === axes.length - 1; chip.appendChild(right); + if (a.positive && a.kind !== 'category') { const on = isLog(a, ui), lg = button('pc-log', 'log', () => { const list = (ui.pcLog || []).filter(x => x !== a.id); if (!on) list.push(a.id); set('pcLog', list); }, 'pc-log-' + a.id, (on ? 'Linear scale for ' : 'Logarithmic scale for ') + a.short); lg.setAttribute('aria-pressed', String(on)); chip.appendChild(lg); } + const x = button('pc-x', '×', () => set('pcAxes', ids.filter(id => id !== a.id)), 'pc-drop-' + a.id, 'Take ' + a.short + ' away'); x.disabled = axes.length <= 2; chip.appendChild(x); + box.appendChild(chip); + }); + const clear = button('btn sm ghost', 'Clear ranges', () => set('pcBrush', null), 'pc-clear'); clear.disabled = !Object.keys(rangesOf(ctx.all, ui)).length; box.appendChild(clear); + return box; + } + /** Every axis on offer, the settings with how strongly they go with the first metric; at most twelve on. */ + function chooser(ctx, axes) { + const ui = ctx.state.ui, on = new Set(axes.map(a => a.id)), d = h('details', 'pc-choose'); d.dataset.key = 'pc-choose'; + if (ui.pcChooser) d.open = true; + d.addEventListener('toggle', () => { ctx.state.ui.pcChooser = d.open; }); + d.appendChild(h('summary', null, 'Choose axes · ' + on.size + ' of at most ' + MOST)); + const ul = h('ul', 'pc-list'); + for (const a of ctx.all) { + const li = h('li'), l = h('label'), cb = h('input'); cb.type = 'checkbox'; cb.checked = on.has(a.id); cb.disabled = !cb.checked && on.size >= MOST || cb.checked && on.size <= 2; cb.dataset.key = 'pc-pick-' + a.id; + cb.addEventListener('change', () => { const ids = axes.map(x => x.id); ctx.act.keepUI('pcAxes', cb.checked ? ids.concat([a.id]) : ids.filter(id => id !== a.id)); fill(ctx); apply(document.getElementById('main'), ctx.view, ctx.state); }); + l.appendChild(cb); l.appendChild(h('span', a.kind === 'metric' ? null : 'mono', a.title)); + l.appendChild(h('span', 'small faint', a.kind === 'metric' ? ' metric' : ' ' + a.kind + (a.association == null ? '' : ' · ρ ' + a.association.toFixed(2)) + ' · ' + a.count + ' subjects')); + li.appendChild(l); ul.appendChild(li); + } + d.appendChild(ul); + return d; + } + + /** + * Sets the ranges drawn on the axes into the rest of the tab, under root (the main area, or the tab's content + * while it is built): the subjects table hides the rows outside them and says how many it shows, and the + * charts' marks of those subjects are faint. Nothing is read; nothing else is drawn. + */ + function apply(root, view, state) { + const keep = last && last.benchmark === view.name ? keptOf(last.data, last.all, state.ui) : null; + for (const tr of root.querySelectorAll('.bench-all tr[data-subject]')) { const hide = !!keep && !keep.has(tr.dataset.subject); if (tr.hidden !== hide) tr.hidden = hide; } + for (const mark of root.querySelectorAll('.bench-chart [data-id]')) { const s = view.byKey.get(mark.dataset.id), out = !!keep && !!s && !keep.has(s.name); mark.parentNode.classList.toggle('pc-out', out); } + const table = root.querySelector('.bench-all'); + if (table) { + let note = table.querySelector('.pc-filtered'); + const shown = keep ? [...table.querySelectorAll('tr[data-subject]')].filter(tr => !tr.hidden).length : null; + if (keep && !note) { note = h('p', 'small muted pc-filtered'); const sect = table.querySelector('.sect'); if (sect) sect.after(note); else table.prepend(note); } + if (keep) { const text = shown + ' rows shown: the subjects inside the ranges drawn on the axes of Settings and metrics.'; if (note.textContent !== text) note.textContent = text; note.dataset.shown = String(shown); } + else if (note) note.remove(); + } + } + + return { section, apply }; +})(); diff --git a/static/project-workspace/screens.js b/static/project-workspace/screens.js index fa6188f1..68b7daeb 100644 --- a/static/project-workspace/screens.js +++ b/static/project-workspace/screens.js @@ -124,7 +124,13 @@ window.LabScreens = (() => { if (E) E.decorate(main); if (planSel) { window.LabActions.planView(aside, planSel, act.go, sel ? () => act.select(sel) : null); return true; } if (E && E.owns(raw, data)) { E.drawer(aside, raw, act, data, 'map'); return true; } - if (sel) { inspectorModel(aside, sel, act, data); return true; } + if (sel) { + // Compare (spec-t3 section 5.1): the model into the page's compare set, kept current on every render (tabs.js). + const more = window.LabScreens.compareActs ? ins => window.LabScreens.compareActs(ins, sel, state, act, 'map') : undefined; + inspectorModel(aside, sel, act, data, more); + const ins = aside.querySelector('.inspector'); if (ins && more) more(ins); + return true; + } aside.textContent = ''; aside._for = null; return false; } diff --git a/static/project-workspace/tabs.js b/static/project-workspace/tabs.js index e3f1a07d..317a191f 100644 --- a/static/project-workspace/tabs.js +++ b/static/project-workspace/tabs.js @@ -21,6 +21,7 @@ const { sect, cell, block, time, bytes, failure, modelState, graphFor, putInPlace, putDrawer, turn } = S.parts; const fmt = C.fmtSci; const STATISTICS = ['median', 'mean', 'p10', 'p90', 'min', 'max']; + const COMPARE_MOST = 4; // models in the compare set (app.js keeps the same bound; spec-t3 section 5.1) const plural = (n, one, many) => n.toLocaleString('en-GB') + ' ' + (n === 1 ? one : many || one + 's'); const nameOfRef = ref => ref.slice(ref.indexOf('/') + 1); const seconds = s => s == null ? '' : s < 1 ? '<1 s' : s < 90 ? Math.round(s) + ' s' : s < 5400 ? Math.round(s / 60) + ' min' : (s / 3600).toFixed(1) + ' h'; @@ -147,9 +148,19 @@ // ---- Benchmarks: the screen ------------------------------------------------- function benchmarks(main, aside, state, act, data) { const sel = state.sel.benchmarks || null, ui = state.ui; - paint(main, async () => { const list = await benchmarkList(); const b = pickBenchmark(list, state.benchmark); return { list, view: b ? await benchmarkView(b.benchmark, data.map) : null, picked: b }; }, (frag, { list, view, picked }, width) => { + const stat0 = STATISTICS.includes(ui.stat) ? ui.stat : 'median'; + paint(main, async () => { + const list = await benchmarkList(), b = pickBenchmark(list, state.benchmark); + if (!b) return { list, view: null, picked: b }; + // Parallel coordinates (parallel.js) are read with the tab; the intervals, which may take seconds to make the + // first time (spec-t3 section 2), only when they have already arrived: else after the tab is put in place. + const [view, axes] = await Promise.all([benchmarkView(b.benchmark, data.map), window.LabParallel ? P.read('benchmark_axes', { benchmark: b.benchmark, statistic: stat0 }).catch(error => ({ error })) : null]); + return { list, view, picked: b, axes, iv: P.peek('intervals', { benchmark: b.benchmark }) }; + }, (frag, { list, view, picked, axes, iv }, width) => { if (!view) { frag.appendChild(h('p', 'empty', 'This project defines no benchmark.')); return; } - const stat = STATISTICS.includes(ui.stat) ? ui.stat : 'median', cmp = state.cmp.filter(k => view.byKey.has(k)); + const stat = stat0, cmp = state.cmp.filter(k => view.byKey.has(k)); + if (iv === undefined) P.read('intervals', { benchmark: view.name }).then(() => { if (state.screen === 'benchmarks' && main._view === 'benchmarks/') act.setUI('ivFor', view.name); }, () => { /* no intervals: the tab stays as it is */ }); + const ivs = intervalIndex(iv); const bar = h('div', 'filters'); bar.appendChild(select('Benchmark', list.map(b => [b.benchmark, b.title + ' · ' + plural(b.subjects_with_results, 'subject') + ' with results']), view.name, v => act.setBenchmark(v), 'benchmark')); bar.appendChild(kindChips(state, act, view.subjects.map(s => s.kind))); @@ -170,11 +181,15 @@ const show = visibleSubject(state), select_ = key => act.select(key === sel ? null : key); // Charts, by their form. if (!view.charts.length) frag.appendChild(h('p', 'empty bench-note', 'No chart is defined for this benchmark; every value is in the table below.')); - for (const c of view.charts) frag.appendChild(chartSection(c, view, { width, sel, onSelect: select_, show, frontierOnly: !!ui.frontierOnly, tables: !!ui.chartTables })); + for (const c of view.charts) frag.appendChild(chartSection(c, view, { width, sel, onSelect: select_, show, frontierOnly: !!ui.frontierOnly, tables: !!ui.chartTables, ivs })); + if (ivs.rows) frag.appendChild(h('p', 'small faint bench-desc bench-iv', 'Intervals: 95 % percentile bootstrap, ' + iv.resamples.toLocaleString('en-GB') + ' resamples of each subject\'s per-case values held here (seed ' + iv.seed + '); a dashed ring on the frontier: not told apart from a neighbour on both metrics.')); + // Parallel coordinates over the metrics and the recipe settings that vary (parallel.js, spec-t3 section 5.2). + if (axes && window.LabParallel && view.subjects.length >= 2) frag.appendChild(axes.error ? (() => { const d = h('section', 'pc'); d.appendChild(sect('Settings and metrics')); failure(d, axes.error); return d; })() : window.LabParallel.section(axes, view, state, act, width)); // The compare set. if (cmp.length) frag.appendChild(compareSection(view, cmp, stat, act)); // Every subject. - frag.appendChild(subjectTable(view, state, act, stat, sel, cmp)); + frag.appendChild(subjectTable(view, state, act, stat, sel, cmp, ivs)); + if (window.LabParallel) window.LabParallel.apply(frag, view, state); // the ranges drawn on the axes }); if (!sel) return closeDrawer(aside); benchmarkDrawer(aside, sel, state, act, data); @@ -183,7 +198,7 @@ /** The drawer of a selected subject: the model's drawer when it is made from a recipe of the map, with Compare. */ function benchmarkDrawer(aside, sel, state, act, data) { const isModel = data.map.byId.has(sel); - if (isModel) S.inspectorModel(aside, sel, act, data, ins => compareActs(ins, sel, state, act, true)); + if (isModel) S.inspectorModel(aside, sel, act, data, ins => compareActs(ins, sel, state, act, 'benchmarks')); else if (aside._for !== sel || aside._again) { const name = sel.startsWith('subject:') ? sel.slice('subject:'.length) : sel; drawer(aside, sel, async () => { const list = await benchmarkList(); const b = pickBenchmark(list, state.benchmark); return b ? benchmarkView(b.benchmark, data.map) : null; }, (ins, view) => { @@ -193,20 +208,35 @@ ins.appendChild(h('p', 'note', s.recipe ? 'Made from ' + s.recipe + ', which is not on the map.' : 'Not made from a recipe of this project.')); const dl = h('dl', 'metrics'); for (const m of view.metrics) dl.appendChild(cell(m.title, fmt(valueOf(s, m.id, 'median')), m.units && m.units !== '1' ? m.units : '')); ins.appendChild(dl); ins.appendChild(h('p', 'note', 'Medians over ' + (s.count == null ? 'no cases' : plural(s.count, 'case')) + ' of ' + view.title + '.')); - compareActs(ins, sel, state, act, false); + compareActs(ins, sel, state, act, 'subject'); }); } - const ins = aside.querySelector('.inspector'); if (ins) compareActs(ins, sel, state, act, isModel); + const ins = aside.querySelector('.inspector'); if (ins) compareActs(ins, sel, state, act, isModel ? 'benchmarks' : 'subject'); } - /** Compare, kept current on every render (a drawer is built once per selection). */ - function compareActs(ins, sel, state, act, isModel) { + /** + * Compare, kept current on every render (a drawer is built once per selection), in a model's drawer on the + * Benchmarks tab, the Map and the Compare tab (where: 'benchmarks', 'subject', 'map', 'compare'): adds the model + * to the compare set or takes it out, opens the Compare tab once the set holds two, and On the map. + */ + function compareActs(ins, sel, state, act, where) { const old = ins.querySelector('.bench-acts'); if (old) old.remove(); const acts = h('div', 'actions bench-acts'), on = state.cmp.includes(sel); - const b = button('btn', on ? 'Remove from compare' : 'Compare', () => act.toggleCompare(sel)); b.disabled = !on && state.cmp.length >= 3; acts.appendChild(b); - if (isModel) acts.appendChild(button('btn ghost', 'On the map', () => act.go('map', sel))); + const b = button('btn', on ? 'Remove from compare' : 'Compare', () => act.toggleCompare(sel)); b.disabled = !on && state.cmp.length >= COMPARE_MOST; b.dataset.key = 'cmp-toggle-' + sel; acts.appendChild(b); + if (where !== 'compare' && state.cmp.length >= 2) { const o = button('btn ghost', 'Open Compare · ' + state.cmp.length, () => act.go('compare')); o.dataset.key = 'cmp-open'; acts.appendChild(o); } + if (where !== 'map' && where !== 'subject') acts.appendChild(button('btn ghost', 'On the map', () => act.go('map', sel))); const head = ins.querySelector('header'); head.after(acts); } + S.compareActs = compareActs; + /** + * The intervals answer (spec-t3 section 4) as the tab looks it up: of(subject, metric, statistic) gives [low, high] + * or null, frontiers by chart reference; rows is how many there are (0 while they have not arrived). + */ + function intervalIndex(iv) { + const by = new Map(), frontiers = new Map(); + if (iv) { for (const r of iv.intervals) by.set(r.subject + '\u0000' + r.metric, r); for (const f of iv.frontiers) frontiers.set(f.chart, f); } + return { rows: by.size, frontiers, of: (subject, metric, stat) => { const r = by.get(subject + '\u0000' + metric); return r && r[stat] ? r[stat] : null; } }; + } /** One chart: its heading and population in words, the drawing by form (a panel per group value), and its table when asked. */ function chartSection(c, view, o) { const sec = h('section', 'bench-chart'); sec.dataset.chart = c.reference; @@ -230,15 +260,17 @@ if (!s.points.length) { sec.appendChild(h('p', 'empty', 'No subject has a value here.')); continue; } sec.appendChild(host); if (d.form === 'tradeoff') { - const pts = s.points.map(p => ({ ...point(p), x: p.x, y: p.value, frontier: p.frontier, rows: tipRows(p, [{ v: fmt(p.x), l: d.metric_x.title + units(d.metric_x) }, { l: p.frontier ? 'on the frontier' : '' }]) })); + const front = !d.group && o.ivs.frontiers.get(c.reference), apart = p => front ? front.pairs.filter(q => q.separated === false && q.subjects.includes(p.subject)).map(q => q.subjects.find(x => x !== p.subject)) : []; + const pts = s.points.map(p => { const away = p.frontier ? apart(p) : []; return { ...point(p), x: p.x, y: p.value, frontier: p.frontier, nsig: away.length > 0, rows: tipRows(p, [{ v: fmt(p.x), l: d.metric_x.title + units(d.metric_x) }, { l: p.frontier ? 'on the frontier' + (away.length ? ', not told apart from ' + away.join(', ') : '') : '' }]) }; }); C.scatter(host, pts, { width: o.width, height: 340, xTitle: d.metric_x.title + units(d.metric_x), yTitle: d.metric.title + units(d.metric), xName: d.metric_x.title, yName: d.metric.title, xBetter: d.metric_x.better, yBetter: d.metric.better, selected: o.sel, onSelect: o.onSelect, dimOff: o.frontierOnly }); - host.appendChild(legend(pts, 'Line: the frontier, where no other subject is at least as good on both and better on one')); + host.appendChild(legend(pts, 'Line: the frontier, where no other subject is at least as good on both and better on one' + (pts.some(p => p.nsig) ? '; dashed ring: not told apart from a neighbour by the per-case values' : ''))); } else if (d.form === 'progression') { const pts = s.points.map(p => ({ ...point(p), y: p.value, best: p.best_so_far, rows: tipRows(p, [{ v: fmt(p.best_so_far), l: 'best so far' }, { l: p.trained_at ? 'trained ' + P.day(p.trained_at) : 'no training date' }]) })); C.progression(host, pts, { width: o.width, height: 240, yTitle: d.metric.title + units(d.metric), selected: o.sel, onSelect: o.onSelect }); host.appendChild(legend(pts, 'Step line: the best so far, ' + better(d.metric))); } else { - const pts = s.points.map(p => ({ ...point(p), y: p.value, rows: tipRows(p) })); + const ci = p => !d.group && o.ivs.of(p.subject, d.metric.id, d.statistic); + const pts = s.points.map(p => { const e = ci(p); return { ...point(p), y: p.value, lo: e ? e[0] : null, hi: e ? e[1] : null, rows: tipRows(p, e ? [{ v: fmt(e[0]) + ' – ' + fmt(e[1]), l: '95 % interval' }] : []) }; }); C.ranking(host, pts, { width: o.width, yTitle: d.metric.title + units(d.metric), selected: o.sel, onSelect: o.onSelect }); host.appendChild(legend(pts, 'Best first, ' + better(d.metric))); } @@ -285,13 +317,15 @@ t.appendChild(tb); const w = wrapTable(t); const foot = h('p', 'small faint bench-desc', 'Marked: the best value of each column.'); const box = h('div'); box.appendChild(w); box.appendChild(foot); return box; } - /** Up to three subjects side by side: every metric, with the change from the first. */ + /** Up to four subjects side by side: every metric, with the change from the first. */ function compareSection(view, cmp, stat, act) { - const sec = h('section', 'bench-cmp'); sec.appendChild(sect('Compare', cmp.length + ' of 3')); + const sec = h('section', 'bench-cmp'); sec.appendChild(sect('Compare', cmp.length + ' of ' + COMPARE_MOST)); const list = cmp.map(k => view.byKey.get(k)); const chips = h('div', 'cmp-chips'); list.forEach((s, i) => { const c = h('span', 'c s' + (i + 1)); c.appendChild(h('i')); c.appendChild(document.createTextNode(s.full)); const x = button(null, '×', () => act.toggleCompare(s.key)); x.setAttribute('aria-label', 'Remove ' + s.full); c.appendChild(x); chips.appendChild(c); }); - chips.appendChild(button('btn sm ghost', 'Clear', () => act.clearCompare())); sec.appendChild(chips); + chips.appendChild(button('btn sm ghost', 'Clear', () => act.clearCompare())); + if (cmp.length >= 2) { const o = button('btn sm', 'Open Compare', () => act.go('compare')); o.dataset.key = 'bench-open-compare'; chips.appendChild(o); } + sec.appendChild(chips); const t = h('table', 'tv cmpt'); t.appendChild(headRow([['']].concat(list.map(s => [s.full, 'n'])))); const tb = h('tbody'), base = list[0]; for (const m of view.metrics) { const tr = h('tr'); tr.appendChild(h('td', null, m.title + units(m) + ' · ' + stat)); @@ -309,7 +343,7 @@ return sec; } /** Every subject of the benchmark, sortable by any column; a row opens the subject, its box adds it to the compare set. */ - function subjectTable(view, state, act, stat, sel, cmp) { + function subjectTable(view, state, act, stat, sel, cmp, ivs) { const sec = h('section', 'bench-all'), show = visibleSubject(state); const rows = view.subjects.filter(s => show(s) && (!state.ui.resultsOnly || view.metrics.some(m => valueOf(s, m.id, stat) != null))); const sort = state.ui.sort || { key: view.metrics.length ? 'm:' + view.metrics[0].id : 'full', dir: 1 }; @@ -332,13 +366,17 @@ const tb = h('tbody'); for (const s of rows) { const row = h('tr', 'rowbtn' + (s.key === sel ? ' is-sel' : '')); row.dataset.subject = s.name; row.addEventListener('click', () => act.select(s.key === sel ? null : s.key)); - const tdc = h('td'), cb = h('input'); cb.type = 'checkbox'; cb.checked = cmp.includes(s.key); cb.disabled = !cb.checked && cmp.length >= 3; cb.dataset.key = 'cmp-' + s.key; cb.setAttribute('aria-label', 'Compare ' + s.full); + const tdc = h('td'), cb = h('input'); cb.type = 'checkbox'; cb.checked = cmp.includes(s.key); cb.disabled = !cb.checked && state.cmp.length >= COMPARE_MOST; cb.dataset.key = 'cmp-' + s.key; cb.setAttribute('aria-label', 'Compare ' + s.full); cb.addEventListener('click', ev => { ev.stopPropagation(); act.toggleCompare(s.key); }); tdc.appendChild(cb); row.appendChild(tdc); row.appendChild(h('td', 'ck', s.model && s.model.short ? s.model.short : '')); const nt = h('td'); const nb = button('linkish', s.model ? s.model.title : s.title, ev => { ev.stopPropagation(); act.select(s.key === sel ? null : s.key); }); nb.dataset.key = 'open-' + s.key; nt.appendChild(nb); row.appendChild(nt); const kt = h('td'); kt.appendChild(s.model ? h('span', 'chip ' + s.kind, P.kindLabel(s.kind)) : h('span', 'small faint', 'not on the map')); row.appendChild(kt); row.appendChild(h('td', 'small faint nowrap grp', s.group)); - for (const m of view.metrics) row.appendChild(h('td', 'n', valueOf(s, m.id, stat) == null ? '' : fmt(valueOf(s, m.id, stat)))); + for (const m of view.metrics) { + const v = valueOf(s, m.id, stat), td = h('td', 'n', v == null ? '' : fmt(v)), e = v == null ? null : ivs.of(s.name, m.id, stat); + if (e) { const ci = h('span', 'ci', fmt(e[0]) + ' – ' + fmt(e[1])); ci.title = 'The 95 % interval of the ' + stat + ' from the per-case values'; td.appendChild(ci); td.dataset.low = String(e[0]); td.dataset.high = String(e[1]); } + row.appendChild(td); + } row.appendChild(h('td', 'n', s.count == null ? '' : String(s.count))); row.appendChild(h('td', 'small faint', s.perCase ? 'held here' : '')); tb.appendChild(row); } From 7097c74b766a6505f2a03efc2e731583bd20e992 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 19 Nov 2026 06:17:12 -0700 Subject: [PATCH 100/131] test(workspace): browser check of the Compare tab, parallel coordinates and intervals Co-Authored-By: Claude Opus 5.5 --- tests/browser_project_workspace_compare.cjs | 306 ++++++++++++++++++++ tests/project_compare_browser_fixture.py | 139 +++++++++ 2 files changed, 445 insertions(+) create mode 100644 tests/browser_project_workspace_compare.cjs create mode 100644 tests/project_compare_browser_fixture.py diff --git a/tests/browser_project_workspace_compare.cjs b/tests/browser_project_workspace_compare.cjs new file mode 100644 index 00000000..68d38acc --- /dev/null +++ b/tests/browser_project_workspace_compare.cjs @@ -0,0 +1,306 @@ +'use strict'; +// Comparing chosen models deeply (docs/plans/training-and-curation/spec-t3.md sections 5 and 7, slices T3b and T3c) +// in a headless browser, the owner signed in, no GPU. Tuldok runs with --project-folder on a copy of the minimal +// fixture in a Git repository of its own, with what tests/project_compare_browser_fixture.py writes: five recipes of +// earlier work whose settings vary, a benchmark of the five with a tradeoff and a ranking chart, per-case values of +// each (imported through import_values), and adopted products of three of them that keep fields of one shared case. +// 1. The Map drawer's Compare adds three models; Open Compare shows the Compare tab: three columns, the paths that +// differ (and not those that are the same), the metrics with intervals equal to the intervals operation's, and +// the frontier rows (cm-b and cm-c not told apart). +// 2. Outputs: the shared case, nine panels drawn; the Native row the same colours in every column (one scale), +// the Predicted row different where the predictions differ; one slider move asks field_compare three times and +// draws every canvas again in place, the rest of the tab the same elements; hover names the column's values. +// 3. Benchmarks: parallel coordinates with the metric and setting axes; a range dragged on the error axis hides the +// table rows outside it, makes the charts' points of those subjects faint, and asks nothing; moving an axis and +// the log scale redraw it in place with the range kept; Clear ranges shows every row again. +// 4. Intervals: whiskers on the ranking chart, a low – high line in the table's cells, a dashed ring on the frontier +// points the answer says are not told apart. +// 5. Light and dark at 1440 and 390 wide, the Compare and Benchmarks tabs: no blank canvas, nothing in the main area +// wider than it outside the tables' own scrolling boxes; no script error and no failed request. +// node tests/browser_project_workspace_compare.cjs [--shots ] +const assert = require('node:assert/strict'), fs = require('node:fs'), os = require('node:os'), path = require('node:path'); +const { spawn, execFileSync } = require('node:child_process'), { once } = require('node:events'); +const { authenticatedFixture } = require('./auth_helpers.cjs'), { waitForDebugger } = require('./browser_startup.cjs'), { cdpSession } = require('./browser_cdp_session.cjs'), { qaDirectory } = require('./qa_artifacts.cjs'); + +const root = path.resolve(__dirname, '..'); +const argv = process.argv.slice(2), option = name => { const i = argv.indexOf(name); return i >= 0 ? argv[i + 1] : null; }; +assert.ok(process.env.TULDOK_DATABASE_URL, 'TULDOK_DATABASE_URL must name a disposable PostgreSQL cluster'); +const venv = path.join(root, '.venv', 'bin'); +if (fs.existsSync(path.join(venv, 'python'))) process.env.PATH = venv + path.delimiter + process.env.PATH; // auth_helpers runs python3 +const python = fs.existsSync(path.join(venv, 'python')) ? path.join(venv, 'python') : 'python3'; +const MODELS = ['recipes/cm-a', 'recipes/cm-b', 'recipes/cm-c'], BENCH = 'cmp-bench'; + +const temporary = fs.mkdtempSync(path.join(os.tmpdir(), 'tuldok-compare-browser-')); +const report = qaDirectory(root, 'project-workspace-compare'); +const shots = option('--shots') ? path.resolve(option('--shots')) : null; if (shots) fs.mkdirSync(shots, { recursive: true }); +const children = [], checks = [], errors = [], failures = []; +let server, serverErrors = '', origin, auth, socket, session, send, evaluate, owned = null; +const pause = ms => new Promise(resolve => setTimeout(resolve, ms)); +async function until(fn, label, tries = 300) { for (let i = 0; i < tries; i++) { const value = await fn(); if (value) return value; await pause(100); } throw Error('Timed out: ' + label); } +function check(text) { checks.push(text); console.log('PASS ' + text); } +function launch(command, args, options) { const child = spawn(command, args, options); children.push(child); return child; } +async function stop(child) { if (!child || child.exitCode !== null || child.signalCode !== null) return; const exited = once(child, 'exit'); child.kill('SIGTERM'); await Promise.race([exited, pause(10000)]); if (child.exitCode === null && child.signalCode === null) { child.kill('SIGKILL'); await exited; } } +function findBrowser() { + const candidates = [process.env.BROWSER, '/usr/bin/chromium', '/usr/bin/chromium-browser', '/usr/bin/google-chrome']; + const cache = path.join(os.homedir(), '.cache', 'ms-playwright'); + if (fs.existsSync(cache)) for (const name of fs.readdirSync(cache).filter(n => n.startsWith('chromium_headless_shell-')).sort().reverse()) candidates.push(path.join(cache, name, 'chrome-headless-shell-linux64', 'chrome-headless-shell')); + const found = candidates.find(candidate => candidate && fs.existsSync(candidate)); + assert.ok(found, 'No headless browser: set BROWSER'); + return found; +} +/** Drops the project's schema and the catalog's from the disposable database, so each run imports afresh. */ +function dropOwned(folder, catalog) { + const id = JSON.parse(fs.readFileSync(path.join(folder, 'tuldok.json'), 'utf8')).id; + execFileSync(python, ['-c', `import json, os, pathlib, sys, psycopg +from psycopg import sql +from tuldok_project import store +store.drop_project(sys.argv[1], os.environ['TULDOK_DATABASE_URL']) +root = pathlib.Path(sys.argv[2]) +if root.exists(): + with psycopg.connect(os.environ['TULDOK_DATABASE_URL'], autocommit=True) as c: + for p in root.rglob('.tuldok.json'): + v = json.loads(p.read_text()) + name = 'projection_' + v['projection_id'] if v.get('version') == 2 else 'catalog_' + v['dataset_id'] + c.execute(sql.SQL('DROP SCHEMA IF EXISTS {} CASCADE').format(sql.Identifier(name))) +`, id, catalog], { cwd: root, stdio: ['ignore', 'pipe', 'pipe'] }); +} +async function contract(name) { + const capabilities = await (await auth.fetch(origin + '/api/agent/capabilities')).json(); + const operation = capabilities.operations.find(item => item.id === 'project.' + name), c = operation.contracts[operation.contracts.length - 1]; + return 'project.' + name + '/' + c.version + '/' + c.sha256; +} +/** An operation as the owner. */ +async function api(name, body = {}) { + const headers = { 'Content-Type': 'application/json', 'Tuldok-Operation-Contract': await contract(name) }; + const response = await auth.fetch(origin + '/api/project/' + name, { method: 'POST', headers, body: JSON.stringify(body) }); + const value = await response.json(); assert.equal(response.status, 200, name + ': ' + JSON.stringify(value)); return value; +} + +// ---- The page's requests, from the browser's network, with their bodies ------------------------------------------------ +const calls = new Map(), finished = []; +function network(event) { + const p = event.params; + if (event.method === 'Network.requestWillBeSent' && /\/api\/project\/[a-z_]+$/.test(p.request.url)) { let body = null; try { body = p.request.postData ? JSON.parse(p.request.postData) : null; } catch (_) { body = null; } calls.set(p.requestId, { name: p.request.url.split('/').pop(), body, sent: Date.now() }); } + if ((event.method === 'Network.loadingFinished' || event.method === 'Network.loadingFailed') && calls.has(p.requestId)) { finished.push(Object.assign(calls.get(p.requestId), { done: Date.now() })); calls.delete(p.requestId); } +} +const asked = (name, since = 0, test = () => true) => finished.concat([...calls.values()]).filter(f => (name === null || f.name === name) && f.sent >= since && test(f.body || {})); +/** Waits until nothing reads: no "Reading…", nothing busy in the main area, no request of the project in flight. */ +async function settled(label) { + await until(() => evaluate(`(() => { const m = document.getElementById('main'); return ![...m.querySelectorAll('.note')].some(n => n.textContent === 'Reading…') && !m.hasAttribute('aria-busy') && !m.querySelector('[aria-busy]'); })()`).then(ok => ok && !calls.size), 'settled: ' + label); + await pause(250); +} +const byKey = key => `[data-key=${JSON.stringify(key)}]`; +async function mouse(type, x, y, buttons = 0) { await send('Input.dispatchMouseEvent', { type, x, y, button: type === 'mouseMoved' ? (buttons ? 'left' : 'none') : 'left', buttons, clickCount: type === 'mouseMoved' ? 0 : 1 }); } +async function press(selector) { + const at = await until(() => evaluate(`(() => { const e = document.querySelector(${JSON.stringify(selector)}); if (!e) return null; e.scrollIntoView({ block: 'center', inline: 'nearest' }); const r = e.getBoundingClientRect(); return { x: r.left + r.width / 2, y: r.top + r.height / 2 }; })()`), 'shown: ' + selector, 100); + await pause(100); await mouse('mouseMoved', at.x, at.y); await mouse('mousePressed', at.x, at.y, 1); await mouse('mouseReleased', at.x, at.y); +} +async function slide(selector, value) { await evaluate(`(() => { const r = document.querySelector(${JSON.stringify(selector)}); r.focus(); r.value = ${JSON.stringify(String(value))}; r.dispatchEvent(new Event('input', { bubbles: true })); return true; })()`); } +async function frames() { await evaluate('new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve)))'); } +async function shot(name) { + await frames(); + const png = Buffer.from((await send('Page.captureScreenshot', { format: 'png', captureBeyondViewport: false })).data, 'base64'); + fs.writeFileSync(path.join(report, name + '.png'), png); if (shots) fs.writeFileSync(path.join(shots, name + '.png'), png); +} +const close = (a, b, label, tol = 1e-12) => assert.ok(Math.abs(a - b) <= tol * Math.max(1, Math.abs(b)), label + ': ' + a + ' is not ' + b); +const same = (a, b) => a.every((v, i) => v === b[i]); +// A panel of the outputs: the colour at the centre of each cell of a rows x columns grid drawn square in it, and how +// often it was drawn. +const CELLS = `(sel, rows, cols) => { const c = document.querySelector(sel); if (!c || !c.width) return null; + const g = c.getContext('2d'), W = c.width, H = c.height, s = Math.min(W / cols, H / rows), x0 = (W - cols * s) / 2, y0 = (H - rows * s) / 2; + const cells = []; for (let r = 0; r < rows; r++) { const row = []; for (let k = 0; k < cols; k++) { const p = g.getImageData(Math.floor(x0 + (k + 0.5) * s), Math.floor(y0 + (r + 0.5) * s), 1, 1).data; row.push([p[0], p[1], p[2], p[3]]); } cells.push(row); } + const box = c.getBoundingClientRect(); return { cells, times: Number(c.dataset.drawn || 0), box: { left: box.left, top: box.top }, cell: { x0, y0, s, dpr: window.devicePixelRatio || 1 } }; }`; +const cellSel = (row, model) => `canvas.cmpv-cv[data-row="${row}"][data-model="${model}"]`; +const cells = (row, model, rows, cols) => evaluate(`(${CELLS})(${JSON.stringify(cellSel(row, model))}, ${rows}, ${cols})`); + +(async () => { + // ---- The fixture ------------------------------------------------------------------------------------------------- + fs.cpSync(path.join(root, 'tests', 'fixtures', 'tuldok_project', 'minimal'), path.join(temporary, 'fixture'), { recursive: true }); + const folder = path.join(temporary, 'fixture', 'project'), made = path.join(temporary, 'made'); + const X = JSON.parse(execFileSync(python, [path.join(root, 'tests', 'project_compare_browser_fixture.py'), '--out', made], { maxBuffer: 64 << 20 }).toString()); + for (const dir of ['recipes', 'benchmarks', 'charts']) for (const name of fs.readdirSync(path.join(made, dir))) fs.copyFileSync(path.join(made, dir, name), path.join(folder, dir, name)); + const git = ['-c', 'user.name=Tuldok Test', '-c', 'user.email=test@example.invalid', '-c', 'commit.gpgsign=false', '-c', 'init.defaultBranch=main', '-C', path.join(temporary, 'fixture')]; + execFileSync('git', [...git, 'init', '-q']); execFileSync('git', [...git, 'add', '-A']); execFileSync('git', [...git, 'commit', '-q', '-m', 'The fixture.']); + const home = path.join(temporary, 'home'), catalog = path.join(temporary, 'catalog'); fs.mkdirSync(home); + const env = { ...process.env, TULDOK_PROJECT_HOME: home, TULDOK_SETTINGS: path.join(temporary, 'settings.json') }; + owned = [folder, catalog]; dropOwned(folder, catalog); + const cli = (...args) => execFileSync(python, ['-m', 'tuldok_project', ...args], { cwd: root, env, stdio: ['ignore', 'pipe', 'pipe'] }).toString(); + const manifest = path.join(temporary, 'adopt.json'); + fs.writeFileSync(manifest, JSON.stringify({ format: 'tuldok_adoption_v1', products: MODELS.map(ref => { const dir = path.join(made, 'products', ref.split('/')[1]); return { reference: ref, files: Object.fromEntries(fs.readdirSync(dir).map(n => [n, path.join(dir, n)])) }; }) })); + cli('adopt', folder, manifest, '--copy'); + let output = ''; + server = launch(python, ['-u', 'app.py', '--port', '0', '--data', catalog, '--project-folder', folder], { cwd: root, env, stdio: ['ignore', 'pipe', 'pipe'] }); + server.stdout.on('data', chunk => { output += chunk; }); server.stderr.on('data', chunk => { serverErrors += chunk; }); + const port = await until(() => { if (server.exitCode !== null) throw Error('Tuldok exited: ' + serverErrors); return output.match(/127\.0\.0\.1:(\d+)/)?.[1]; }, 'Tuldok start-up', 3000); + origin = 'http://127.0.0.1:' + port; + auth = authenticatedFixture(); await auth.register(origin, catalog, root); + for (const name of fs.readdirSync(path.join(made, 'values'))) await api('import_values', { text: fs.readFileSync(path.join(made, 'values', name), 'utf8') }); + const IV = await api('intervals', { benchmark: BENCH }); + const ivOf = (s, m) => IV.intervals.find(r => r.subject === s && r.metric === m); + const [front] = IV.frontiers; + assert.deepEqual(front.not_separated, ['cm-b', 'cm-c'], 'The fixture: cm-b and cm-c are not told apart'); + + const browser = launch(findBrowser(), ['--headless', '--no-sandbox', '--disable-gpu', '--no-first-run', '--hide-scrollbars', '--remote-debugging-port=0', '--window-size=1440,900', '--user-data-dir=' + path.join(temporary, 'browser'), 'about:blank'], { stdio: 'ignore', env: { ...process.env, XDG_CONFIG_HOME: temporary, XDG_CACHE_HOME: temporary } }); + const debugPort = await waitForDebugger(browser, path.join(temporary, 'browser', 'DevToolsActivePort')); + const target = (await (await fetch('http://127.0.0.1:' + debugPort + '/json')).json()).find(item => item.type === 'page'); + socket = new WebSocket(target.webSocketDebuggerUrl); await once(socket, 'open'); + session = cdpSession(socket, { timeoutMs: 60000, onEvent: event => { + network(event); + if (event.method === 'Runtime.exceptionThrown') errors.push(event.params.exceptionDetails.exception?.description || event.params.exceptionDetails.text); + if (event.method === 'Runtime.consoleAPICalled' && event.params.type === 'error') errors.push(event.params.args.map(a => a.value ?? a.description).join(' ')); + if (event.method === 'Log.entryAdded' && event.params.entry.level === 'error') errors.push(event.params.entry.text + ' ' + (event.params.entry.url || '')); + if (event.method === 'Network.loadingFailed' && !event.params.canceled) failures.push({ id: event.params.requestId, error: event.params.errorText }); + if (event.method === 'Network.responseReceived' && event.params.response.status >= 400) failures.push({ url: event.params.response.url, status: event.params.response.status }); + } }); + send = session.send; + evaluate = async expression => { const result = await send('Runtime.evaluate', { expression, awaitPromise: true, returnByValue: true }); if (result.exceptionDetails) throw Error(JSON.stringify(result.exceptionDetails)); return result.result.value; }; + await send('Page.enable'); await send('Runtime.enable'); await send('Network.enable'); await send('Log.enable'); + const size = async (width, height) => send('Emulation.setDeviceMetricsOverride', { width, height, deviceScaleFactor: 1, mobile: width < 600 }); + const theme = async name => { await send('Emulation.setEmulatedMedia', { features: [{ name: 'prefers-color-scheme', value: name }, { name: 'prefers-reduced-motion', value: 'reduce' }] }); }; + await auth.browser(send, origin); // the owner's session + const load = async (name, query, hash) => { + await theme(name); + await send('Page.navigate', { url: 'about:blank' }); await pause(100); + await send('Page.navigate', { url: origin + '/?theme=' + name + (query ? '&' + query : '') + '#' + hash }); + await until(() => evaluate(`document.readyState === 'complete' && !!document.getElementById('needs-btn') && !document.getElementById('needs-btn').disabled`), 'the project read', 1200); + await settled('opened ' + hash); + }; + const drawn = () => until(() => evaluate(`(() => { const c = [...document.querySelectorAll('canvas.cmpv-cv')]; return c.length === 9 && c.every(x => Number(x.dataset.drawn) > 0); })()`), 'nine panels drawn'); + + // ---- 1. Compare from the Map's drawers, then the Compare tab --------------------------------------------------------- + await size(1440, 900); await load('light', '', 'map'); + for (const ref of MODELS) { + await evaluate(`(() => { location.hash = '#map/' + encodeURIComponent(${JSON.stringify(ref)}); return true; })()`); + await press(byKey('cmp-toggle-' + ref)); await settled('compare ' + ref); + assert.equal(await evaluate(`document.querySelector(${JSON.stringify(byKey('cmp-toggle-' + ref))}).textContent`), 'Remove from compare'); + } + assert.equal(new URLSearchParams(await evaluate('location.search')).get('cmp'), MODELS.join(','), 'The set is in the address'); + await press(byKey('cmp-open')); await until(() => evaluate(`location.hash === '#compare' && !!document.querySelector('table.cmpv')`), 'the Compare tab'); await settled('compare tab'); await drawn(); + const t1 = await evaluate(`(() => ({ cols: [...document.querySelectorAll('th.cmpv-col')].map(t => t.dataset.model), diffs: [...document.querySelectorAll('tr.cmpv-diff')].map(r => [r.dataset.kind, r.dataset.path, [...r.querySelectorAll('td')].map(t => t.textContent)]), + group: [...document.querySelectorAll('tr.cmpv-group th')].map(t => t.textContent), metrics: [...document.querySelectorAll('tr.cmpv-metric')].map(r => [r.dataset.metric, [...r.querySelectorAll('td')].map(t => [Number(t.dataset.value), Number(t.dataset.low), Number(t.dataset.high), t.classList.contains('best')])]), + front: [...document.querySelectorAll('tr.cmpv-front td')].map(t => [t.dataset.on, t.dataset.nsig]), tab: document.querySelector('#tabs [aria-current]').dataset.tab }))()`); + assert.deepEqual(t1.cols, MODELS, 'One column per model, in the set\'s order'); assert.equal(t1.tab, 'compare'); + assert.deepEqual(t1.diffs.map(d => d[1]), ['change', 'derived_from', 'run.inputs.extra', 'run.settings.learning_rate', 'run.settings.optimizer', 'run.settings.width'], 'Only the paths that differ, in order'); + assert.deepEqual(t1.diffs.map(d => d[0]), ['change', 'parent', 'data', 'setting', 'setting', 'setting']); + assert.deepEqual(t1.diffs[3][2], ['0.01', '0.001', '0.001']); assert.deepEqual(t1.diffs[1][2], ['—', '—', 'recipes/cm-b']); + assert.ok(t1.group.some(t => /6 paths differ · \d+ the same/.test(t)), 'The count of the same: ' + t1.group.join(' | ')); + for (const [metric, row] of t1.metrics) row.forEach(([v, lo, hi], i) => { const r = ivOf(MODELS[i].split('/')[1], metric); close(lo, r.median[0], 'low ' + metric + ' ' + i); close(hi, r.median[1], 'high ' + metric + ' ' + i); assert.ok(lo <= v && v <= hi, 'the value inside its interval'); }); + assert.deepEqual(t1.metrics.find(m => m[0] === 'err')[1].map(c => c[3]), [false, false, true], 'The best error is marked (cm-c)'); + assert.deepEqual(t1.front, [['true', ''], ['true', 'cm-c'], ['true', 'cm-b']], 'The frontier row'); + await shot('light-1440-1-compare'); + check('1. Compare from three Map drawers, Open Compare: three columns ' + t1.cols.join(', ') + '; the differing paths ' + t1.diffs.map(d => d[1]).join(', ') + ' (epochs, the same, not listed); intervals equal to the intervals operation; cm-b and cm-c on the frontier, not told apart'); + + // ---- 2. The outputs: one case, nine panels, one control for all ---------------------------------------------------- + const [R0, C0] = [X.shape[0], X.shape[1]], at = (values, i) => values[(i[0] * X.shape[1] + i[1]) * X.shape[2] + i[2]]; + assert.equal(await evaluate(`document.querySelector('[data-key="cmpv-case"]').value`), 'scene-a-frame-3', 'The case all three kept comes first'); + const native = await Promise.all(MODELS.map(m => cells('reference', m, R0, C0))), pred = await Promise.all(MODELS.map(m => cells('predicted', m, R0, C0))); + let agree = 0, differ = 0; + for (let r = 0; r < R0; r++) for (let c = 0; c < C0; c++) { + assert.ok(same(native[0].cells[r][c], native[1].cells[r][c]) && same(native[0].cells[r][c], native[2].cells[r][c]), 'The native field is one colour in every column at ' + [r, c]); + const values = MODELS.map(m => at(X.predicted[m.split('/')[1]], [r, c, 2])); + if (values[0] !== values[1]) { differ++; assert.ok(!same(pred[0].cells[r][c], pred[1].cells[r][c]), 'Predictions differ at ' + [r, c]); } + else { agree++; assert.deepEqual(pred[0].cells[r][c], pred[1].cells[r][c], 'Predictions agree at ' + [r, c]); } + } + assert.ok(differ > 0 && agree > 0); + await evaluate(`(() => { document.querySelector('table.cmpv').__mark = 1; document.querySelector('section.cmpv-out').__mark = 2; return true; })()`); + const before2 = await evaluate(`[...document.querySelectorAll('canvas.cmpv-cv')].map(c => Number(c.dataset.drawn))`), since2 = Date.now(); + await slide(byKey('cmpv-slider-2'), 0); await until(() => asked('field_compare', since2).length >= 3 && !calls.size, 'three requests'); await settled('slider'); + const req2 = asked('field_compare', since2); + assert.equal(req2.length, 3, 'One field_compare per column'); assert.ok(req2.every(f => JSON.stringify(f.body.index) === '[3,2,0]'), 'All at z = 0'); + const after2 = await evaluate(`[...document.querySelectorAll('canvas.cmpv-cv')].map(c => Number(c.dataset.drawn))`); + assert.ok(after2.every((n, i) => n > before2[i]), 'Every canvas drawn again: ' + before2 + ' → ' + after2); + assert.deepEqual(await evaluate(`[document.querySelector('table.cmpv').__mark, document.querySelector('section.cmpv-out').__mark]`), [1, 2], 'The rest of the tab is the same elements'); + assert.equal(new URLSearchParams(await evaluate('location.search')).get('cmpIndex'), '3,2,0', 'The place is in the address'); + await evaluate(`(() => { document.querySelector(${JSON.stringify(cellSel('predicted', MODELS[2]))}).scrollIntoView({ block: 'center' }); return true; })()`); await pause(200); + const p2 = await cells('predicted', MODELS[2], R0, C0), hr = 4, hc = 3; + await mouse('mouseMoved', p2.box.left + (p2.cell.x0 + (hc + 0.5) * p2.cell.s) / p2.cell.dpr, p2.box.top + (p2.cell.y0 + (hr + 0.5) * p2.cell.s) / p2.cell.dpr); await pause(150); + const tip = await evaluate(`(() => { const t = document.querySelector('.cmpv-tip'); return { hidden: t.hidden, model: t.dataset.model, cell: t.dataset.cell, rows: [...t.querySelectorAll('.fld-tip-row')].map(r => r.lastChild.textContent) }; })()`); + const fmtF = v => evaluate(`window.LabCharts.fmtSci(Math.fround(${v}))`), hi2 = [hr, hc, 0]; + assert.equal(tip.hidden, false); assert.equal(tip.model, MODELS[2]); assert.equal(tip.cell, JSON.stringify(hi2)); + assert.deepEqual(tip.rows, [await fmtF(at(X.reference, hi2)), await fmtF(at(X.predicted['cm-c'], hi2)), await fmtF(Math.fround(at(X.predicted['cm-c'], hi2) - at(X.reference, hi2)))], 'The tip gives the column\'s three values'); + await mouse('mouseMoved', 5, 5); + await shot('light-1440-2-outputs'); + check('2. Outputs of scene-a-frame-3: the native row one colour in all three columns, the predictions different at ' + differ + ' cells and the same at ' + agree + '; one slider move asked field_compare 3 times and drew all 9 canvases again in place; the tip gives cm-c\'s values'); + + // ---- 3 and 4. Benchmarks: parallel coordinates, brushing, intervals -------------------------------------------------- + await load('light', 'benchmark=' + BENCH, 'benchmarks'); + await until(() => evaluate(`!!document.querySelector('.bench-iv') && !!document.querySelector('section.pc svg')`), 'the intervals and parallel coordinates'); await settled('benchmarks with intervals'); + const axes = await evaluate(`[...document.querySelectorAll('section.pc .pc-axis')].map(a => a.dataset.axis)`); + assert.deepEqual(axes.slice(0, 2), ['m:err', 'm:ms'], 'The metrics first'); + for (const a of ['s:run.settings.learning_rate', 's:run.settings.width', 's:run.settings.optimizer', 's:change']) assert.ok(axes.includes(a), a + ' is an axis: ' + axes); + assert.ok(!axes.includes('s:run.settings.epochs'), 'A setting the same everywhere is not an axis'); + assert.equal(await evaluate(`document.querySelectorAll('section.pc path.pcl').length`), 5, 'One line per subject'); + // 4. Intervals. + const iv4 = await evaluate(`(() => ({ whiskers: [...document.querySelectorAll('.bench-chart[data-chart="charts/cmp-ranking"] g.ci')].map(g => [Number(g.dataset.lo), Number(g.dataset.hi), g.parentNode.querySelector('[data-id]').dataset.id]), table: [...document.querySelectorAll('.bench-all tr[data-subject]')].map(r => [r.dataset.subject, [...r.querySelectorAll('td[data-low]')].map(t => [Number(t.dataset.low), Number(t.dataset.high)])]), + rings: [...document.querySelectorAll('.bench-chart[data-chart="charts/cmp-tradeoff"] circle.nsig')].map(c => c.parentNode.querySelector('[data-id]').dataset.id).sort() }))()`); + assert.equal(iv4.whiskers.length, 5, 'A whisker per subject on the ranking chart'); + for (const [lo, hi, id] of iv4.whiskers) { const r = ivOf(id.split('/')[1], 'err'); close(lo, r.median[0], 'whisker low'); close(hi, r.median[1], 'whisker high'); } + for (const [s, cellsOf] of iv4.table) { assert.equal(cellsOf.length, 2, s + ' has two intervals in the table'); close(cellsOf[0][0], ivOf(s, 'err').median[0], s + ' err low'); close(cellsOf[1][1], ivOf(s, 'ms').median[1], s + ' ms high'); } + assert.deepEqual(iv4.rings, ['recipes/cm-b', 'recipes/cm-c'], 'The frontier points not told apart are ringed'); + await shot('light-1440-4-intervals'); + check('4. Intervals: 5 whiskers on the ranking chart and 10 low – high lines in the table, equal to the intervals operation; dashed rings on ' + iv4.rings.join(' and ')); + // 3. Brushing. + await evaluate(`(() => { document.querySelector('.bench-all table').__mark = 7; document.querySelector('section.pc').__mark = 8; return true; })()`); + const line = await evaluate(`(() => { const l = document.querySelector('section.pc .pc-axis[data-axis="m:err"] line.pc-line'); l.scrollIntoView({ block: 'center' }); const r = l.getBoundingClientRect(); return { x: r.left + r.width / 2, top: r.top, bottom: r.bottom }; })()`); + await pause(200); + const line2 = await evaluate(`(() => { const r = document.querySelector('section.pc .pc-axis[data-axis="m:err"] line.pc-line').getBoundingClientRect(); return { x: r.left + r.width / 2, top: r.top, bottom: r.bottom }; })()`); + const since3 = Date.now(), y0 = line2.bottom + 4, y1 = line2.bottom - 0.5 * (line2.bottom - line2.top); + await mouse('mouseMoved', line2.x, y0); await mouse('mousePressed', line2.x, y0, 1); + for (let k = 1; k <= 5; k++) { await mouse('mouseMoved', line2.x, y0 + (y1 - y0) * k / 5, 1); await pause(20); } + await mouse('mouseReleased', line2.x, y1); await pause(300); + assert.ok(line.x > 0); + const b3 = await evaluate(`(() => ({ kept: document.querySelector('.pc-count').dataset.kept, rows: [...document.querySelectorAll('.bench-all tr[data-subject]')].filter(r => !r.hidden).map(r => r.dataset.subject), out: [...document.querySelectorAll('.bench-chart g.pc-out [data-id]')].map(e => e.dataset.id), faint: [...document.querySelectorAll('section.pc path.pcl.out')].map(p => p.dataset.subject), note: (document.querySelector('.pc-filtered') || {}).textContent, marks: [document.querySelector('.bench-all table').__mark, document.querySelector('section.pc').__mark], brush: !!document.querySelector('.pc-axis[data-axis="m:err"] .pc-brush') }))()`); + assert.equal(b3.kept, '3', 'Three subjects inside the range'); assert.deepEqual(b3.rows.slice().sort(), ['cm-b', 'cm-c', 'cm-e'], 'The table keeps the rows inside'); + assert.deepEqual([...new Set(b3.out)].sort(), ['recipes/cm-a', 'recipes/cm-d'], 'The charts make the others faint'); + assert.equal(b3.out.length, 4, 'in both charts'); assert.deepEqual(b3.faint.sort(), ['cm-a', 'cm-d']); assert.ok(/3 rows shown/.test(b3.note), b3.note); + assert.deepEqual(b3.marks, [7, 8], 'The table and the section are the same elements'); assert.ok(b3.brush); + assert.equal(asked(null, since3).length, 0, 'Brushing asks nothing'); + await shot('light-1440-3-brushed'); + const since3b = Date.now(); + await press(byKey('pc-right-m:err')); await pause(200); + const order = await evaluate(`[...document.querySelectorAll('section.pc .pc-axis')].map(a => a.dataset.axis).slice(0, 2)`); + assert.deepEqual(order, ['m:ms', 'm:err'], 'The error axis moved right'); + await press(byKey('pc-log-m:err')); await pause(200); + const after3 = await evaluate(`(() => ({ log: document.querySelector('[data-key="pc-log-m:err"]').getAttribute('aria-pressed'), sub: document.querySelector('.pc-axis[data-axis="m:err"] .pc-sub').textContent, kept: document.querySelector('.pc-count').dataset.kept, brush: !!document.querySelector('.pc-axis[data-axis="m:err"] .pc-brush'), mark: document.querySelector('.bench-all table').__mark }))()`); + assert.equal(after3.log, 'true'); assert.match(after3.sub, /log/); assert.equal(after3.kept, '3', 'The range is kept'); assert.ok(after3.brush); assert.equal(after3.mark, 7); + assert.equal(asked(null, since3b).length, 0, 'Moving an axis and the log scale ask nothing'); + await press(byKey('pc-clear')); await pause(200); + const cleared = await evaluate(`(() => ({ rows: [...document.querySelectorAll('.bench-all tr[data-subject]')].filter(r => !r.hidden).length, out: document.querySelectorAll('.bench-chart g.pc-out').length, note: !!document.querySelector('.pc-filtered'), faint: document.querySelectorAll('section.pc path.pcl.out').length }))()`); + assert.deepEqual(cleared, { rows: 5, out: 0, note: false, faint: 0 }, 'Clear ranges shows everything again'); + check('3. Parallel coordinates over ' + axes.length + ' axes (' + axes.join(', ') + '); a range dragged on the error axis kept cm-b, cm-c and cm-e in the table and made cm-a and cm-d faint in both charts and the lines, with no request; the error axis moved right and on a log scale in place with the range kept; Clear ranges showed all 5 again'); + + // ---- 5. Light and dark, 1440 and 390 wide ------------------------------------------------------------------------- + const seen = []; + for (const [w, hgt] of [[1440, 900], [390, 844]]) for (const name of ['light', 'dark']) for (const tab of ['compare', 'benchmarks']) { + const tag = name + '-' + w + '-' + tab; + await size(w, hgt); await load(name, 'benchmark=' + BENCH + '&cmp=' + MODELS.join(','), tab); + if (tab === 'compare') await drawn(); else await until(() => evaluate(`!!document.querySelector('.bench-iv')`), 'intervals ' + tag); + await settled(tag); + const r = await evaluate(`(() => { const m = document.getElementById('main'); const cv = [...m.querySelectorAll('canvas.cmpv-cv')].map(c => { if (!c.width) return 0; const d = c.getContext('2d').getImageData(0, 0, c.width, c.height).data; let n = 0; for (let i = 3; i < d.length; i += 4) if (d[i]) n++; return n; }); const wide = [...m.querySelectorAll('*')].filter(e => e.getBoundingClientRect().right > m.getBoundingClientRect().right + 1 && e.getBoundingClientRect().width > 0 && !e.closest('.tv-wrap')).map(e => e.tagName + '.' + e.className).slice(0, 4); return { cv, page: document.documentElement.scrollWidth - innerWidth, main: m.scrollWidth - m.clientWidth, wide }; })()`); + assert.ok(r.cv.every(n => n > 10), tag + ': no blank canvas ' + JSON.stringify(r.cv)); + assert.ok(r.main <= 1 && !r.wide.length, tag + ': nothing in the main area overflows sideways ' + JSON.stringify(r)); + await evaluate(`(() => { const s = document.querySelector(${JSON.stringify(tab === 'compare' ? 'section.cmpv-out' : 'section.pc')}); if (s) s.scrollIntoView({ block: 'start' }); return true; })()`); await pause(200); + await shot(tag + '-5'); + seen.push(tag + (r.page > 0 ? ' (the page ' + r.page + ' px wider: its header)' : '')); + } + await size(1440, 900); + check('5. No blank canvas and nothing in the main area wider than it: ' + seen.join(', ') + (shots ? '; screenshots in ' + shots : '')); + + assert.deepEqual(errors, [], 'Script errors'); + assert.deepEqual(failures, [], 'Failed requests'); + check('No script error, no failed request'); + fs.writeFileSync(path.join(report, 'receipt.json'), JSON.stringify({ status: 'pass', folder, checks }, null, 2) + '\n'); + console.log('Receipt in ' + report); +})().catch(async error => { + process.exitCode = 1; + console.error(error); if (serverErrors) console.error('Server:', serverErrors.slice(-4000)); + console.error('Script errors:', JSON.stringify(errors)); console.error('Failed requests:', JSON.stringify(failures)); + try { if (evaluate) { await shot('failure'); console.error('Main:', (await evaluate('document.getElementById("main").innerText')).slice(0, 2500)); } } catch (_) { /* the page is gone */ } + fs.writeFileSync(path.join(report, 'failure.json'), JSON.stringify({ status: 'failed', error: String(error && error.stack || error), checks, errors, failures }, null, 2) + '\n'); +}).finally(async () => { + try { session?.close(); } catch (_) { /* closed */ } + for (const child of children.reverse()) await stop(child); + if (owned) try { dropOwned(...owned); } catch (error) { console.error('Dropping the disposable schemas failed:', error.message); process.exitCode = 1; } + try { execFileSync('chmod', ['-R', 'u+w', temporary]); } catch (_) { /* nothing was made read-only */ } + fs.rmSync(temporary, { recursive: true, force: true }); +}); diff --git a/tests/project_compare_browser_fixture.py b/tests/project_compare_browser_fixture.py new file mode 100644 index 00000000..90bfb798 --- /dev/null +++ b/tests/project_compare_browser_fixture.py @@ -0,0 +1,139 @@ +"""What the browser check of the Compare tab reads (tests/browser_project_workspace_compare.cjs). + +Written with the standard library only. Into --out: + +- recipes/cm-a.json … cm-e.json: five recipes of earlier work whose settings vary (learning rate, width, + optimizer; epochs the same), cm-c derived from cm-b with one more input; +- benchmarks/cmp-bench.json and charts/cmp-tradeoff.json, cmp-ranking.json: a benchmark of the five, its error + against its time, and its error by subject; +- values/.json: per-case values of every subject, 12 cases, made so that on the tradeoff chart's frontier + (a, b, c, e by median) cm-b and cm-c are not told apart by a bootstrap, and every other pair is; +- products/cm-a, cm-b, cm-c: the fields each run kept: case scene-a-frame-3 (6 x 5 x 4, float64) kept by all three + and scene-b-frame-9 by cm-a and cm-b; the native field is the same for all; each prediction is the native plus + 0.2 (i + 1) + 0.1 z where x >= 3 and y >= 2. + +It prints, as JSON, what the check compares the page with. +""" +import argparse +import json +import math +import os +import struct + +SHAPE = (6, 5, 4) +NOISE = [-0.5, -0.4, -0.3, -0.2, -0.1, -0.05, 0.05, 0.1, 0.2, 0.3, 0.4, 0.5] # median exactly 0 +SHUFFLE = [7, 2, 10, 0, 5, 11, 3, 8, 1, 9, 4, 6] +RECIPES = { + 'cm-a': {'title': 'Compare A', 'short': 'CA', 'change': 'architecture', 'lr': 0.01, 'width': 8, + 'optimizer': 'adam'}, + 'cm-b': {'title': 'Compare B', 'short': 'CB', 'change': 'training-policy', 'lr': 0.001, 'width': 16, + 'optimizer': 'adam'}, + 'cm-c': {'title': 'Compare C', 'short': 'CC', 'change': 'refinement', 'lr': 0.001, 'width': 16, 'optimizer': 'sgd', + 'derived_from': 'recipes/cm-b', 'extra': True}, + 'cm-d': {'title': 'Compare D', 'short': 'CD', 'change': 'component', 'lr': 0.005, 'width': 32, 'optimizer': 'sgd'}, + 'cm-e': {'title': 'Compare E', 'short': 'CE', 'change': 'architecture', 'lr': 0.0005, 'width': 64, + 'optimizer': 'adam'}, +} +# Each subject's error and time: a base, and the noise (shuffled for cm-c so its pairing with cm-b is noisy). +BASES = {'cm-a': (0.8, 1.0, False), 'cm-b': (0.4, 2.0, False), 'cm-c': (0.39, 2.02, True), 'cm-d': (0.6, 3.0, False), + 'cm-e': (0.2, 5.0, False)} + + +def indexes(shape): + out = [()] + for size in shape: + out = [index + (i,) for index in out for i in range(size)] + return out + + +def npy(shape, values): + header = repr({'descr': '= 3 and y >= 2 else 0.0) for r, (x, y, z) in zip(r0, cells)] + predicted[name] = p + folder = os.path.join(out, 'products', name) + os.makedirs(folder, exist_ok=True) + arrays = {'a-reference.npy': r0, 'a-prediction.npy': p} + cases = [{'member_ordinal': 0, 'predicted': {'name': 'a-prediction.npy'}, + 'reference': {'name': 'a-reference.npy'}, 'mask': None}] + members = [{'ordinal': 0, 'frozen_reference': {'member_id': 'scene-a-frame-3', 'split': 'validation'}}] + if name != 'cm-c': + arrays.update({'b-reference.npy': r0, 'b-prediction.npy': [v + 0.5 for v in r0]}) + cases.append({'member_ordinal': 1, 'predicted': {'name': 'b-prediction.npy'}, + 'reference': {'name': 'b-reference.npy'}, 'mask': None}) + members.append({'ordinal': 1, 'frozen_reference': {'member_id': 'scene-b-frame-9', 'split': 'test'}}) + for file, data in arrays.items(): + with open(os.path.join(folder, file), 'wb') as handle: + handle.write(npy(SHAPE, data)) + write(os.path.join(folder, 'field-index.json'), [{'run_id': 'e' * 32, 'cases': cases}]) + write(os.path.join(folder, 'probe.json'), {'format': 'probe_v1', 'members': members}) + print(json.dumps({'shape': list(SHAPE), 'reference': r0, 'predicted': predicted, 'values': values})) + + +if __name__ == '__main__': + main() From 21e8c7163d7ab4bf808c2d5024d86991f2d2dd01 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 19 Nov 2026 06:21:08 -0700 Subject: [PATCH 101/131] fix(project): setting axes weighed by how many subjects they cover; a run's code is never an axis On the lab's 150 pressure fits the axes led with list positions of run.sources held by six subjects, on chance correlations. The association is now weighed by the share of measured subjects it is made over, and run.command and run.sources are of kind code: compared, never an axis. Co-Authored-By: Claude Opus 5.5 --- tests/test_tuldok_project_comparing.py | 21 +++++++++++++++++---- tuldok_project/comparing.py | 21 ++++++++++++++------- 2 files changed, 31 insertions(+), 11 deletions(-) diff --git a/tests/test_tuldok_project_comparing.py b/tests/test_tuldok_project_comparing.py index 3bdc7b9f..36ae9944 100644 --- a/tests/test_tuldok_project_comparing.py +++ b/tests/test_tuldok_project_comparing.py @@ -79,8 +79,9 @@ def test_leaves_paths_and_identity_left_out(self): 'run.settings[""]': 2, 'run.settings["with space"].x': True, 'run.settings.empty': {}, 'run.inputs.training': 'datasets/w'}) self.assertEqual([comparing.kind_of(path) for path in ('group', 'change', 'derived_from', - 'run.inputs.training', 'run.settings.lr')], - ['group', 'change', 'parent', 'data', 'setting']) + 'run.inputs.training', 'run.settings.lr', + 'run.sources[3]', 'run.command[0]')], + ['group', 'change', 'parent', 'data', 'setting', 'code', 'code']) def test_bounds(self): document = {'run': {'settings': {f'k{i}': i for i in range(10)}}} @@ -237,8 +238,20 @@ def test_number_and_category_axes_and_their_order(self): flag = axes['run.settings.flag'] self.assertEqual((flag['kind'], flag['categories']), ('category', [False, True])) self.assertAlmostEqual(flag['association'], spearman([0, 0, 0, 1, 1], ys)) - order = [abs(axis['association']) for axis in got['settings'] if axis['association'] is not None] - self.assertEqual(order, sorted(order, reverse=True)) + # Ordered by |association| weighed by the share of the 5 measured subjects it is made over. + weighed = [abs(axis['association']) * sum(1 for row in got['subjects'][:5] + if row['settings'][axis['path']] is not None) / 5 + for axis in got['settings'] if axis['association'] is not None] + self.assertEqual(weighed, sorted(weighed, reverse=True)) + sparse = [dict(recipe) for recipe in recipes] + sparse[0] = {**sparse[0], 'rare': 1} + sparse[1] = {**sparse[1], 'rare': 2} + sparse[2] = {**sparse[2], 'rare': 3} # perfectly associated, but over 3 of 5 subjects + sparse[3] = {**sparse[3], 'run': {**sparse[3]['run'], 'sources': ['a.py']}} + sparse[4] = {**sparse[4], 'run': {**sparse[4]['run'], 'sources': ['b.py']}} + paths = [axis['path'] for axis in comparing.benchmark_axes(self.gathered(sparse, errors))['settings']] + self.assertNotIn('run.sources[0]', paths) # code is never an axis + self.assertLess(paths.index('run.settings.width'), paths.index('rare')) self.assertEqual(got['subjects'][1]['settings']['run.settings.opt'], 1) # sgd, second category self.assertEqual(got['subjects'][5]['metrics'], {'err': None}) self.assertEqual(got['metrics'][0]['positive'], True) diff --git a/tuldok_project/comparing.py b/tuldok_project/comparing.py index d32e21af..1b43183a 100644 --- a/tuldok_project/comparing.py +++ b/tuldok_project/comparing.py @@ -39,7 +39,8 @@ IDENTITY = ('format', 'kind', 'title', 'description', 'card', 'labels', 'earlier_work', 'compared_with') # Keys compared on rows of their own, first. _OWN_ROWS = {'group': 'group', 'change': 'change', 'derived_from': 'parent'} -_KIND_ORDER = {'group': 0, 'change': 1, 'parent': 2, 'data': 3, 'setting': 4} +_KIND_ORDER = {'group': 0, 'change': 1, 'parent': 2, 'data': 3, 'setting': 4, 'code': 5} +_CODE = ('run.command', 'run.sources') # the code a run ran: compared, never an axis _QUOTED = re.compile(r'[.\[\]" ]') @@ -83,11 +84,13 @@ def walk(value, path, level): def kind_of(path): - """group, change, parent, data (under run.inputs) or setting.""" + """group, change, parent, data (under run.inputs), code (run.command, run.sources) or setting.""" if path in _OWN_ROWS: return _OWN_ROWS[path] if path == 'run.inputs' or path.startswith(('run.inputs.', 'run.inputs[')): return 'data' + if any(path == code or path.startswith((code + '.', code + '[')) for code in _CODE): + return 'code' return 'setting' @@ -491,7 +494,7 @@ def benchmark_axes(gathered, statistic_name='median', *, most=SETTINGS): leading = next((values for values in metric_values.values() if len(values) >= 3), None) candidates = [] for path, values in by_path.items(): - if len(values) < 2 or len({_canon(value) for value in values.values()}) < 2: + if kind_of(path) == 'code' or len(values) < 2 or len({_canon(value) for value in values.values()}) < 2: continue if all(_number(value) for value in values.values()): axis = {'path': path, 'kind': 'number', 'categories': None, @@ -512,11 +515,15 @@ def benchmark_axes(gathered, statistic_name='median', *, most=SETTINGS): if leading is not None: both = [name for name in positions if name in leading] axis['association'] = spearman([positions[name] for name in both], [leading[name] for name in both]) + weight = abs(axis['association'] or 0) * len(both) / max(1, len(leading)) else: - axis['association'] = None - candidates.append((axis, positions)) - candidates.sort(key=lambda pair: (pair[0]['association'] is None, -abs(pair[0]['association'] or 0), - -pair[0]['count'], _natural(pair[0]['path']))) + axis['association'], weight = None, 0 + candidates.append((axis, positions, weight)) + # The strongest association first, weighed by the share of the measured subjects it is made over, so a path + # that six of 150 subjects have does not lead on a chance correlation (spec-t3, as built). + candidates.sort(key=lambda item: (item[0]['association'] is None, -item[2], -item[0]['count'], + _natural(item[0]['path']))) + candidates = [(axis, positions) for axis, positions, _ in candidates] chosen = candidates[:most] rows = [] for item in subjects: From 3760bde133bab07c87cfa9122f4ad170ea10665d Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 19 Nov 2026 06:26:00 -0700 Subject: [PATCH 102/131] docs(plan): spec-t3 as built Co-Authored-By: Claude Opus 5.5 --- docs/plans/training-and-curation/spec-t3.md | 31 +++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/docs/plans/training-and-curation/spec-t3.md b/docs/plans/training-and-curation/spec-t3.md index 31757dea..9ca56a91 100644 --- a/docs/plans/training-and-curation/spec-t3.md +++ b/docs/plans/training-and-curation/spec-t3.md @@ -96,3 +96,34 @@ The tab, for the models of the set that are recipes on the map (a benchmark subj ## 8. Out of scope Running anything to make a prediction; comparing more than four models; intervals for grouped rows (by horizon, say) and for results read from a file; multiple-comparison corrections; settings read from a recipe's settings file; brushing on the Map; a hyperparameter search's own view (phase 7 reuses this). + +## As built + +What differs from the text above, and what was found. Built on `feat/t3-compare` beside phase 1, which owns the Train tab and `tuldok_log/`; neither is touched here. Edits to shared files are small: `app.js` (the tab, the bound of four, the address), `tabs.js` (Compare in drawers, intervals, the parallel-coordinates hook), `screens.js` (Compare in the Map's drawer), `adapter.js` (`peek`), `charts.js` (whiskers, ring), `operations.py`, `service.py`, the service test's count (64 to 67). `base.css` and `docs/contracts/project-folder.md` are not changed: the styles are in a new `compare.css`, and no file contract is added. + +### T3a, the reader and the operations + +- **The setting axes are ordered by the association weighed by its coverage**: `|ρ| × (subjects with both) / (subjects with a value of the first metric)`, then by count and path. Section 3 said the plain `|ρ|`. On the lab's 150 pressure fits the plain order led with list positions of `run.sources` that six subjects hold, at |ρ| 0.88 to 0.95 by chance. For the same reason **`run.command` and `run.sources` are of a sixth kind, `code`**: listed in what differs (last), never an axis. `association` in the answer is still the plain ρ. +- **Categories are ordered** numbers first by value, then `false`, `true`, then texts, then the rest (written into section 3 before the build: ordering by JSON text put `"wide"` before `16` and `8` after `40`). +- **`model_compare` resamples only for its statistic.** Its intervals equal those of `intervals` for that statistic (the draws are the same sequence; the browser check compares them). +- **The intervals of a benchmark are kept** by comparing what was gathered with what was kept (no hash), 8 benchmarks. +- **Tests:** `tests/test_tuldok_project_comparing.py`, 13 (three with the database, through `Service`): flattening and its bounds, the differences, every statistic's interval and the paired and independent differences against the test's own seeded resampling and percentiles, the frontier pairs (separated, not separated, unknown, grouped, `touching`), the axes (number, category with mixed values, constant and 13-text paths left out, ρ against the test's own Spearman, the weighed order, code never an axis, `left_out`), the three operations on the minimal fixture with its values imported, refusals, and the catalog digest unchanged. In the minimal fixture's tradeoff chart only one point is on the frontier, so its pairs are tested on hand-made chart data. + +### T3b and T3c, the page + +- **The tab is `#compare`, after Benchmarks.** Its drawer is the model's drawer with Compare. Choosing another benchmark keeps the set (it used to empty it). +- **The intervals arrive after the tab:** the Benchmarks tab is put in place without them; when `intervals` answers, the tab is drawn again in place (`act.setUI('ivFor', …)`, the whole tab built off the page with its scroll, focus and ranges kept); afterwards the kept answer is peeked (`P.peek`) and the tab draws them at once. A line under the charts says how they are made. +- **The frontier mark** is a dashed ring round each point (not a dashed segment of the line). +- **Brushing is by pointer only**; the axes' move, log and remove buttons and the chooser are buttons and checkboxes, but a range cannot be set from the keyboard (doubt; a pair of number fields per axis would do). The lines are SVG paths with a ``, not focusable. +- **The outputs** take the shape and the first slice from the first model that kept the chosen case; a model that kept it in another shape says so in its cells. The colour bars sit with each row's title; under each column, relative L2, mean-free relative L2, RMSE and the largest error over the whole field. +- **Files beyond section 6's list:** `compare.css`, and the fixture writes recipes, a benchmark, two charts, values files and three products. + +### Runs (a disposable PostgreSQL, no GPU) + +Project suite 768 OK (755 before, and the 13 new); agent interface 43 OK (4 skipped); `browser_project_workspace_compare.cjs` 6 PASS (twice); unchanged `_fields.cjs` 8 PASS, `_structure.cjs` 8 PASS, `browser_project_workspace.cjs` 24 PASS. The page did not overflow sideways at 390 px on the Compare and Benchmarks tabs in the check. + +### On the lab folder (read only, no database) + +`benchmark_axes`' computation over `150-pressure-fits-complete-gpu-requests-128-consumed-cases`, from the folder's definitions and its results file only (a script giving `comparing.benchmark_axes` what `gather_axes` would read), in 0.03 s: 150 subjects, all 150 recipes found, 5 metric axes, 48 settings offered (39 more left out). The first settings: `run.resources.wall_hours`, `run.settings.training.learning_rate` (144 subjects, ρ 0.72 with the equation residual), `run.settings.resources.wall_seconds`, `run.settings.training.schedule[0].learning_rate`, the seeds, `group`, the datasets. Keeping the best tenth by mean-free pressure error (≤ 1.05e-4: 16 subjects) shows `wall_hours` 0.5 for all 16, and for the 10 of them that have it learning rate 1e-5, schedule learning rate 1e-6, `wall_seconds` 1800; 6 have no `run.settings.training` (their settings are elsewhere in their recipes). Not run in the browser on the lab folder. + +**Not verified:** the kept-fields comparison of three lab models (the owner, on his database); the time of `intervals` on the lab's real per-case values (estimated 20 s the first time for 150 subjects, five metrics and 128 cases: 25 ms a subject and metric measured); four models in the browser (three were checked); a case kept in two shapes; a refused `field_compare` in a column; the slider dragged quickly; a grouped tradeoff chart (no pairs, by design); the chooser past twelve axes and many axes at 390 px (titles are cut to the space between axes); Tab order and focus rings, by eye in the screenshots only. From 73ca2d0f1a9deea468c99467445fda627aa87302 Mon Sep 17 00:00:00 2001 From: MrScripty <TheEnvironmentGuy@protonmail.com> Date: Thu, 19 Nov 2026 06:26:38 -0700 Subject: [PATCH 103/131] feat(project): embeddings sets of a dataset read as a map, with duplicates, outliers, thin regions and leakage The contract embeddings/<name>.npy and .json (spec-t5 section 1); embeddings.py reads a set, makes its rows unit length and computes the principal components of a sample by subspace power iteration; the pair searches rule pairs out by a lower bound on the coordinates and compute the rest exactly within a budget. Six reads: embeddings (outside the lock), embedding_map, embedding_neighbours, embedding_duplicates, embedding_outliers and embedding_leakage (INSIDE_READS, with records_run among the product arguments). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --- docs/contracts/project-folder.md | 78 +++ tests/test_tuldok_project_curation.py | 400 +++++++++++ tuldok_project/embeddings.py | 929 ++++++++++++++++++++++++++ tuldok_project/operations.py | 36 + tuldok_project/service.py | 89 ++- 5 files changed, 1525 insertions(+), 7 deletions(-) create mode 100644 tests/test_tuldok_project_curation.py create mode 100644 tuldok_project/embeddings.py diff --git a/docs/contracts/project-folder.md b/docs/contracts/project-folder.md index 540c9f8d..709042fc 100644 --- a/docs/contracts/project-folder.md +++ b/docs/contracts/project-folder.md @@ -2293,6 +2293,12 @@ and result keys of each operation are in its contract. | `training_histograms` | inspect | Read one tensor's histograms of weights or gradients over the steps of a run's training, re-binned onto one grid. | | `training_samples` | inspect | List one page of the samples a run's training script kept, optionally of one name. | | `training_sample` | inspect | Read one sample a run's training script kept: an image's size and address, or an array's slice as 32-bit floats. | +| `embeddings` | inspect | List a dataset's embeddings sets: those in its own products and in the products of the datasets that take it as an input, each with its model, rows and the run whose records they are. | +| `embedding_map` | inspect | Read a map of an embeddings set's records in two dimensions (the script's own projection, or principal components Tuldok computes), each record's colour by a field, the map's cells and its thin regions. | +| `embedding_neighbours` | inspect | List the records of an embeddings set most like one of them, by cosine, exactly. | +| `embedding_duplicates` | inspect | List the pairs of an embeddings set's records at or above a cosine, most alike first, and whether every record was examined. | +| `embedding_outliers` | inspect | List the records of an embeddings set farthest from their k-th nearest record, and whether every record was examined. | +| `embedding_leakage` | inspect | List the records of an embeddings set outside the training split that have a near-copy in it, at or above a cosine. | | `set_definition` | edit | Check a definition's text and keep it as an unsaved edit. | | `remove_definition` | edit | Mark a definition that nothing uses as removed, until the project is saved. | | `revert_definition` | edit | Put back the file in the folder in place of a definition's unsaved edit or removal, or drop a definition the folder has no file for. | @@ -2882,6 +2888,78 @@ directory answers `training` with `present` false and the other four `not-found`. `GET /api/project/file` serves a file under `training/` of a run in any state that has a directory; any other file only of a finished run. +### A dataset's embeddings + +A product may hold **embeddings** of records: a vector per record, written by +a project's own script or by the step `embed` (see +[Steps Tuldok provides](#steps-tuldok-provides)). Tuldok computes no +embedding; it reads them to draw a dataset as a map and to search it for +near-duplicates, outliers, thin regions and leakage between splits. A set +named `<name>` (1 to 64 of `a-z 0-9 . _ -`, starting with a letter or digit) +is two files under `embeddings/` at the top of the product: + +- **`embeddings/<name>.npy`**: shape `(rows, dimensions)`, floats (`float32` + as written by Tuldok; `float16` and `float64` are read too), C order, every + value finite, no row all zeros. +- **`embeddings/<name>.json`**, the index, UTF-8 JSON of at most 16 MiB: + +```json +{"format": "tuldok_embeddings_v1", + "records": ["a1", "a2", "a3"], + "dimensions": 256, + "metric": "cosine", + "model": {"name": "embeddinggemma-2", "model_id": "unsloth/embeddinggemma-2-GGUF", "profile": "embed-gpu", + "capability": "text_embedding", "via": "pumas"}, + "prefix": "task: clustering | query: ", + "source": {"dataset": "datasets/photos", "run": null}, + "projection": {"file": "photos.map.npy", "method": "umap"}, + "notes": []} +``` + +`records` are the record ids in row order (1 to 50,000 different ids of 1 to +200 of `A-Z a-z 0-9 . _ -`); `dimensions` 1 to 4,096; `metric` is `cosine`; +`model` an object with a `name` (1 to 256 characters) and other short facts; +`prefix` the text put before each record's text, or null; `source` which +records the rows are: `dataset` (null for the product's own records) and +`run` (null when the script cannot know it). `projection`, optional, names a +`(rows, 2)` `.npy` beside the index that the script made (any method); Tuldok +draws it instead of its own map. `notes`, optional, at most 64 sentences. +Other keys are ignored. At most 40,000,000 values a set and 64 sets a +product are read. + +A dataset's sets are found in its own current products and in those of every +dataset whose `run.inputs` names it (a script that embeds its input writes +`source.dataset`). The records a set describes are those of `source.run` +when given; else of the product holding it when they are its own; else of the +run that the holding run recorded for that input. + +Tuldok makes the rows unit length (cosine is their dot product) and computes, +in 64-bit floats with the standard library, the mean and up to eight leading +principal components of an evenly spaced sample of the rows (at most +`max(256, 2^19 / dimensions)` of them) by subspace power iteration on the +sample's covariance; the map is every row's coordinates on the first two. +The pair searches use each row's coordinates on all of them and the length of +what they leave out, which bound the distance of two rows from below, to rule +pairs out without reading them, and compute the rest exactly: what they list +is never approximate. Each search examines rows in a fixed shuffled order and +stops after 20,000,000 comparisons of coordinates or 400,000,000 values +multiplied exactly; a row is examined whole or not at all, and `complete` +says whether every row was. What is computed is kept while the files are +unchanged. + +| Operation | Arguments | Result | +| --- | --- | --- | +| `embeddings` | `dataset` | `dataset`, `run` (its current product, or null), `sets`: each `run` (holding it), `holder`, `name`, `rows`, `dimensions`, `model`, `prefix`, `source`, `records_run`, `current`, `projection` (its method), `notes`, `problem` | +| `embedding_map` | `run`, `name`, `records_run` (default `run`), `colour` (`split`, `kind`, `annotation:<task>`, `field:<key of meta>`), `cells` (8 to 64, default 24), `thin` (0 to 1, default 0.25) | `name`, `rows`, `dimensions`, `model`, `method` (`pca` or the script's), `explained`, `sample`, `ids`, `x_f32`, `y_f32`, `bounds` (`[x0, x1, y0, y1]`), `missing` (rows whose record is not in the records' product), `colours`, `colour` (`by`, `type` `category` with `categories` and `codes_u16` (65535 for none), or `number` with `low`, `high` and `values_f32`), `grid` (`cells`, `counts`, rows from the lowest y), `thin` (cells holding some points but at most `thin` times the median count of the cells holding any: `cell`, `count`, `x`, `y`, `records`) | +| `embedding_neighbours` | `run`, `name`, `records_run`, `record`, `limit` (default 12, at most 200) | `record`, `neighbours` (`id`, `cosine`, `split`, `kind`), most alike first | +| `embedding_duplicates` | `run`, `name`, `records_run`, `threshold` (0.5 to 1, default 0.98), `limit` (default 200, at most 1,000) | `threshold`, `pairs` (`a`, `b`, `cosine`, `a_split`, `b_split`), `total`, `groups` (records in some pair), `complete`, `examined`, `rows` | +| `embedding_outliers` | `run`, `name`, `records_run`, `k` (1 to 50, default 5), `limit` (default 50) | `k`, `outliers` (`id`, `distance` (one minus the cosine to its k-th nearest), `nearest`, `split`), farthest first, `median`, `complete`, `examined`, `rows` | +| `embedding_leakage` | `run`, `name`, `records_run`, `threshold` (default 0.95), `train` (default `train`), `limit` | `threshold`, `train`, `splits`, `pairs` (`record` of another split, `split`, `near` (the training record), `cosine`), `total`, `leaked`, `complete`, `examined`, `rows` | + +A set that breaks a rule is listed by `embeddings` with its `problem` and +refused `unsupported` by the reads (`too-large` past a bound); a record not +in the set is `not-found`. + ### Annotating The five operations on annotations (see [Annotations in the database](#annotations-in-the-database)) diff --git a/tests/test_tuldok_project_curation.py b/tests/test_tuldok_project_curation.py new file mode 100644 index 00000000..b3c87929 --- /dev/null +++ b/tests/test_tuldok_project_curation.py @@ -0,0 +1,400 @@ +"""Curation by embeddings (docs/plans/training-and-curation/spec-t5.md). + +T5a: the contract, the principal components against the test's own +arithmetic on a planted structure, and the searches (neighbours, duplicates, +outliers, leakage, thin cells) against a brute force the test computes, on +fixtures with planted near-duplicates, one far record and one leaked +validation record. Every fixture is written by the test with the standard +library. No database for these. + +T5b (classes further down): the default embedder, the settings, the steps +embed and select and freeze's records, against tests/fake_pumas_typed.py. +""" +import base64 +import json +import math +import os +from pathlib import Path +import random +import statistics +import struct +import sys +import tempfile +import unittest +from unittest import mock + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) +sys.path.insert(0, str(Path(__file__).resolve().parent)) + +from tuldok_project import embeddings, inside # noqa: E402 +from tuldok_project.store import ProjectError # noqa: E402 + +DIMENSIONS = 24 + + +def unit(vector): + norm = math.sqrt(sum(item * item for item in vector)) + return [item / norm for item in vector] + + +def cosine(a, b): + return sum(x * y for x, y in zip(unit(a), unit(b))) + + +def floats(text): + raw = base64.b64decode(text) + return list(struct.unpack(f'<{len(raw) // 4}f', raw)) + + +def write_set(root, name, ids, rows, *, records=None, **index): + """embeddings/<name>.npy and .json under root (and records.jsonl when records is given).""" + directory = Path(root) / embeddings.DIRECTORY + directory.mkdir(parents=True, exist_ok=True) + dimensions = len(rows[0]) if rows else 1 + embeddings.write_npy(directory / f'{name}.npy', len(rows), dimensions, [item for row in rows for item in row]) + value = {'format': embeddings.FORMAT, 'records': list(ids), 'dimensions': dimensions, 'metric': 'cosine', + 'model': {'name': 'stand-in', 'via': 'test'}, 'prefix': None, + 'source': {'dataset': None, 'run': None}} + value.update(index) + (directory / f'{name}.json').write_text(json.dumps(value), encoding='utf-8') + if records is not None: + with open(Path(root) / 'records.jsonl', 'w', encoding='utf-8') as handle: + for record in records: + handle.write(json.dumps(record) + '\n') + return value + + +def fixture(seed=5): + """(ids, rows, records, planted): six clusters of records with splits, two pairs of near-duplicates in train, + one validation record that is a near-copy of a training one, and one record far from everything.""" + generator = random.Random(seed) + centres = [[generator.gauss(0, 1) for _ in range(DIMENSIONS)] for _ in range(6)] + ids, rows, records = [], [], [] + for i in range(180): + centre = centres[i % 6] + rows.append([value + generator.gauss(0, 0.35) for value in centre]) + ids.append(f'r{i:03d}') + split = 'validation' if i % 10 == 3 else 'test' if i % 10 == 7 else 'train' + records.append({'id': ids[-1], 'kind': 'text', 'text': f'record {i}', 'split': split, + 'meta': {'cluster': f'c{i % 6}', 'size': i}, 'annotations': {'quality': { + 'state': 'accepted', 'value': 'good' if i % 2 else 'bad'}}}) + + def near_copy(row): + return [value + generator.gauss(0, 0.003) for value in row] + + planted = {'duplicates': [('r010', 'd001'), ('r020', 'd002')], 'leaked': ('v001', 'r040'), 'far': 'far01'} + for copy_of, name, split in (('r010', 'd001', 'train'), ('r020', 'd002', 'train'), ('r040', 'v001', 'validation')): + rows.append(near_copy(rows[ids.index(copy_of)])) + ids.append(name) + records.append({'id': name, 'kind': 'text', 'text': 'copy', 'split': split}) + far = [generator.gauss(0, 1) for _ in range(DIMENSIONS)] + rows.append(far) + ids.append('far01') + records.append({'id': 'far01', 'kind': 'image', 'path': 'far.png', 'split': 'train'}) + return ids, rows, records, planted + + +class Product(unittest.TestCase): + def setUp(self): + directory = tempfile.TemporaryDirectory() + self.addCleanup(directory.cleanup) + self.root = Path(directory.name) + self.addCleanup(embeddings.forget) + embeddings.forget() + + def product(self, root=None): + return inside.Product('run-test', root or self.root) + + +class Contract(Product): + """Section 1: a set read; each rule broken once.""" + + def test_a_set_is_read_and_listed(self): + ids, rows, records, _ = fixture() + write_set(self.root, 'texts', ids, rows, records=records, prefix='task: clustering | query: ', + notes=['One note.']) + listed = embeddings.sets(self.product()) + self.assertEqual([(item['name'], item['problem']) for item in listed], [('texts', None)]) + shown = embeddings.described(listed[0]['index']) + self.assertEqual((shown['rows'], shown['dimensions'], shown['prefix'], shown['projection'], shown['notes']), + (len(ids), DIMENSIONS, 'task: clustering | query: ', None, ['One note.'])) + (self.root / 'nothing-here').mkdir() + self.assertEqual(embeddings.sets(self.product(self.root / 'nothing-here')), []) + + def refusal(self, **change): + ids, rows, _, _ = fixture() + write_set(self.root, 'broken', ids, rows) + index_path = self.root / 'embeddings' / 'broken.json' + value = json.loads(index_path.read_text()) + for key, item in change.items(): + if item is KeyError: + value.pop(key) + else: + value[key] = item + index_path.write_text(json.dumps(value)) + listed = embeddings.sets(self.product()) + self.assertEqual(listed[0]['index'], None) + with self.assertRaises(ProjectError) as raised: + embeddings.embedding_map(self.product(), self.product(), 'broken') + self.assertEqual(str(raised.exception), listed[0]['problem']) + return raised.exception + + def test_each_rule_of_the_index(self): + cases = {'format': ('tuldok_embeddings_v0', 'Its format must be'), + 'records': (['a', 'a'], "The record id 'a' is listed more than once."), + 'dimensions': (0, 'dimensions must be a whole number'), + 'metric': ('dot', 'metric must be "cosine"'), + 'model': ({'via': 'x'}, 'model must be an object with a name'), + 'prefix': (7, 'prefix must be a string'), + 'source': ({'dataset': 'photos', 'run': None}, 'source.dataset must be a reference'), + 'projection': ({'file': 'x.txt', 'method': 'umap'}, 'projection must be null or an object'), + 'notes': (['x' * 1001], 'notes must be a list')} + for key, (value, words) in cases.items(): + with self.subTest(key): + self.assertIn(words, str(self.refusal(**{key: value}))) + self.assertIn('records must be a list', str(self.refusal(records=KeyError))) + self.assertIn('is not 1 to 200 characters', str(self.refusal(records=['a/b']))) + + def test_the_vectors_and_the_projection(self): + ids, rows, _, _ = fixture() + write_set(self.root, 'short', ids[:-1], rows) + with self.assertRaises(ProjectError) as raised: + embeddings.analysis(self.product(), 'short') + self.assertIn('has the shape (184, 24); the index says (183, 24)', str(raised.exception)) + bad = [list(row) for row in rows] + bad[3][5] = float('nan') + write_set(self.root, 'nan', ids, bad) + with self.assertRaises(ProjectError) as raised: + embeddings.analysis(self.product(), 'nan') + self.assertEqual(str(raised.exception), 'Row 3 of the vectors holds a value that is not finite.') + zero = [list(row) for row in rows] + zero[7] = [0.0] * DIMENSIONS + write_set(self.root, 'zero', ids, zero) + with self.assertRaises(ProjectError) as raised: + embeddings.analysis(self.product(), 'zero') + self.assertIn('Row 7 of the vectors is all zeros', str(raised.exception)) + write_set(self.root, 'mapped', ids, rows, projection={'file': 'mapped.map.npy', 'method': 'umap'}) + embeddings.write_npy(self.root / 'embeddings' / 'mapped.map.npy', len(ids), 3, [0.0] * len(ids) * 3) + with self.assertRaises(ProjectError) as raised: + embeddings.embedding_map(self.product(), self.product(), 'mapped') + self.assertIn('mapped.map.npy has the shape (184, 3); the index says (184, 2)', str(raised.exception)) + with mock.patch.object(embeddings, 'VALUES_LIMIT', 1000): + with self.assertRaises(ProjectError) as raised: + embeddings.analysis(self.product(), 'nan') + self.assertEqual(raised.exception.code, 'too-large') + with self.assertRaises(ProjectError) as raised: + embeddings.analysis(self.product(), 'absent') + self.assertEqual(raised.exception.code, 'not-found') + with self.assertRaises(ProjectError) as raised: + embeddings.analysis(self.product(), '../records') + self.assertEqual(raised.exception.code, 'invalid') + + +class Components(Product): + """The map's components against the test's own arithmetic on a planted structure.""" + + def planted(self, count=400, dimensions=12): + generator = random.Random(11) + u = unit([generator.gauss(0, 1) for _ in range(dimensions)]) + v = [generator.gauss(0, 1) for _ in range(dimensions)] + dot = sum(a * b for a, b in zip(u, v)) + v = unit([b - dot * a for a, b in zip(u, v)]) + offset = [3.0] + [0.0] * (dimensions - 1) + sample = [[offset[d] + 3.0 * a * u[d] + 1.5 * b * v[d] + generator.gauss(0, 0.05) for d in range(dimensions)] + for a, b in ((generator.gauss(0, 1), generator.gauss(0, 1)) for _ in range(count))] + return sample, u, v + + def own_covariance(self, sample): + count, size = len(sample), len(sample[0]) + mean = [sum(row[d] for row in sample) / count for d in range(size)] + return [[sum((row[i] - mean[i]) * (row[j] - mean[j]) for row in sample) / count for j in range(size)] + for i in range(size)], mean + + def check(self, sample, u, v): + mean, components, variances, total, turns = embeddings.principal_components(sample, 4) + covariance, own_mean = self.own_covariance(sample) + self.assertTrue(all(abs(a - b) < 1e-9 for a, b in zip(mean, own_mean))) + self.assertAlmostEqual(total, sum(covariance[i][i] for i in range(len(covariance))), places=9) + for c, variance in zip(components, variances): + moved = [sum(row[j] * c[j] for j in range(len(c))) for row in covariance] + self.assertLess(max(abs(m - variance * x) for m, x in zip(moved, c)), 1e-6 * variances[0]) + self.assertAlmostEqual(sum(x * x for x in c), 1.0, places=9) + self.assertGreater(max(c, key=abs), 0) + for a in range(4): + for b in range(a + 1, 4): + self.assertAlmostEqual(sum(x * y for x, y in zip(components[a], components[b])), 0.0, places=9) + self.assertEqual(variances, sorted(variances, reverse=True)) + # The sample's own directions differ from the planted ones by its sampling alone. + self.assertGreater(abs(sum(x * y for x, y in zip(components[0], u))), 0.995) + self.assertGreater(abs(sum(x * y for x, y in zip(components[1], v))), 0.995) + own = [sum(x * y for x, y in zip(c, [sum(cov[j] * c[j] for j in range(len(c))) for cov in covariance])) + for c in components] + for mine, theirs in zip(own, variances): + self.assertAlmostEqual(mine, theirs, delta=1e-8 * variances[0]) + self.assertAlmostEqual(variances[0] / total, own[0] / total, places=9) + self.assertGreater(variances[0] / total, 0.7) + self.assertLess(turns, embeddings.POWER_TURNS) + + def test_planted_directions_and_variances(self): + self.check(*self.planted()) + + def test_the_covariance_applied_without_forming_it(self): + with mock.patch.object(embeddings, 'COVARIANCE_DIMENSIONS', 4): + self.check(*self.planted()) + + def test_the_map_and_a_scripts_projection(self): + sample, u, v = self.planted(count=300) + ids = [f'p{i}' for i in range(len(sample))] + write_set(self.root, 'planted', ids, sample, records=[{'id': i, 'kind': 'text', 'text': i} for i in ids]) + drawn = embeddings.embedding_map(self.product(), self.product(), 'planted') + self.assertEqual((drawn['method'], drawn['rows'], drawn['sample'], drawn['missing']), ('pca', 300, 300, 0)) + # The map's x is each unit row's coordinate on the first component of the unit rows: the test's own. + rows = [unit(row) for row in sample] + mean, components, variances, total, _ = embeddings.principal_components(rows, 8) + own_x = [sum((r[d] - mean[d]) * components[0][d] for d in range(len(r))) for r in rows] + self.assertLess(max(abs(a - b) for a, b in zip(floats(drawn['x_f32']), own_x)), 1e-5) + self.assertAlmostEqual(drawn['explained'][0], variances[0] / total, places=6) # rows kept as float32 + mapped = [[float(i), float(-i)] for i in range(300)] + write_set(self.root, 'mapped', ids, sample, projection={'file': 'mapped.map.npy', 'method': 'umap'}) + embeddings.write_npy(self.root / 'embeddings' / 'mapped.map.npy', 300, 2, + [value for pair in mapped for value in pair]) + drawn = embeddings.embedding_map(self.product(), self.product(), 'mapped') + self.assertEqual((drawn['method'], drawn['explained'], drawn['bounds']), ('umap', None, [0.0, 299.0, -299.0, 0.0])) + self.assertEqual(floats(drawn['y_f32'])[:3], [0.0, -1.0, -2.0]) + + +class Searched(Product): + """Neighbours, duplicates, outliers, leakage, thin cells and colours against the test's brute force.""" + + def setUp(self): + super().setUp() + self.ids, self.rows, self.records, self.planted = fixture() + write_set(self.root, 'texts', self.ids, self.rows, records=self.records) + self.units = [unit(row) for row in self.rows] + + def brute(self, threshold): + found = {} + for a in range(len(self.ids)): + for b in range(a + 1, len(self.ids)): + value = sum(x * y for x, y in zip(self.units[a], self.units[b])) + if value >= threshold: + found[tuple(sorted((self.ids[a], self.ids[b])))] = value + return found + + def test_neighbours_are_the_brute_forces(self): + got = embeddings.embedding_neighbours(self.product(), self.product(), 'texts', record='r010', limit=5) + i = self.ids.index('r010') + own = sorted(((sum(x * y for x, y in zip(self.units[i], self.units[j])), self.ids[j]) + for j in range(len(self.ids)) if j != i), reverse=True)[:5] + self.assertEqual([item['id'] for item in got['neighbours']], [name for _, name in own]) + self.assertEqual(got['neighbours'][0]['id'], 'd001') + self.assertAlmostEqual(got['neighbours'][0]['cosine'], own[0][0], places=6) + self.assertEqual((got['neighbours'][0]['split'], got['neighbours'][0]['kind']), ('train', 'text')) + with self.assertRaises(ProjectError) as raised: + embeddings.embedding_neighbours(self.product(), self.product(), 'texts', record='nobody') + self.assertEqual(raised.exception.code, 'not-found') + + def test_duplicates_are_the_brute_forces(self): + for threshold in (0.999, 0.98, 0.9): + with self.subTest(threshold): + embeddings.forget() + got = embeddings.embedding_duplicates(self.product(), self.product(), 'texts', threshold=threshold, + limit=10_000) + own = self.brute(threshold) + self.assertEqual({tuple(sorted((pair['a'], pair['b']))) for pair in got['pairs']}, set(own)) + self.assertTrue(got['complete']) + self.assertEqual((got['examined'], got['rows'], got['total']), (184, 184, len(own))) + for pair in got['pairs']: + self.assertAlmostEqual(pair['cosine'], own[tuple(sorted((pair['a'], pair['b'])))], places=6) + got = embeddings.embedding_duplicates(self.product(), self.product(), 'texts', threshold=0.999) + self.assertEqual({tuple(sorted((pair['a'], pair['b']))) for pair in got['pairs']}, + {('d001', 'r010'), ('d002', 'r020'), ('r040', 'v001')}) + self.assertEqual(got['groups'], 6) + self.assertEqual([pair['cosine'] for pair in got['pairs']], sorted([pair['cosine'] for pair in got['pairs']], + reverse=True)) + + def test_a_lowered_budget_lists_exactly_the_pairs_of_the_rows_examined(self): + with mock.patch.object(embeddings, 'EXACT_VALUES_BUDGET', DIMENSIONS * 300): + got = embeddings.embedding_duplicates(self.product(), self.product(), 'texts', threshold=0.9, limit=10_000) + self.assertFalse(got['complete']) + self.assertTrue(0 < got['examined'] < 184) + made = embeddings.analysis(self.product(), 'texts') + examined = {self.ids[i] for i in made.shuffled()[:got['examined']]} + own = {pair for pair in self.brute(0.9) if set(pair) & examined} + self.assertEqual({tuple(sorted((pair['a'], pair['b']))) for pair in got['pairs']}, own) + + def test_outliers_are_the_brute_forces(self): + got = embeddings.embedding_outliers(self.product(), self.product(), 'texts', k=3, limit=184) + own = [] + for i in range(len(self.ids)): + distances = sorted(1 - sum(x * y for x, y in zip(self.units[i], self.units[j])) + for j in range(len(self.ids)) if j != i) + own.append((distances[2], self.ids[i])) + own.sort(reverse=True) + self.assertTrue(got['complete']) + self.assertEqual(got['outliers'][0]['id'], 'far01') + self.assertEqual([item['id'] for item in got['outliers'][:10]], [name for _, name in own[:10]]) + by = {item['id']: item['distance'] for item in got['outliers']} + self.assertLess(max(abs(by[name] - distance) for distance, name in own), 1e-6) + self.assertAlmostEqual(got['median'], statistics.median(distance for distance, _ in own), places=6) + + def test_leakage_finds_the_leaked_validation_record(self): + got = embeddings.embedding_leakage(self.product(), self.product(), 'texts', threshold=0.99) + self.assertEqual(got['splits'], {'test': 18, 'train': 147, 'validation': 19}) + self.assertEqual([(pair['record'], pair['split'], pair['near']) for pair in got['pairs']], + [('v001', 'validation', 'r040')]) + self.assertEqual((got['leaked'], got['complete'], got['examined']), (1, True, 37)) + loose = embeddings.embedding_leakage(self.product(), self.product(), 'texts', threshold=0.9, limit=10_000) + split = {record['id']: record['split'] for record in self.records} + own = {(a, b) if split[a] != 'train' else (b, a) for a, b in self.brute(0.9) + if (split[a] == 'train') != (split[b] == 'train')} + self.assertEqual({(pair['record'], pair['near']) for pair in loose['pairs']}, own) + none = embeddings.embedding_leakage(self.product(), self.product(), 'texts', train='nothing') + self.assertEqual((none['pairs'], none['total']), ([], 0)) + + def test_the_map_its_colours_and_thin_cells(self): + drawn = embeddings.embedding_map(self.product(), self.product(), 'texts', colour='split', cells=8, thin=0.5) + self.assertEqual(drawn['colours'], ['split', 'kind', 'annotation:quality', 'field:cluster', 'field:size']) + colour = drawn['colour'] + self.assertEqual(colour['type'], 'category') + self.assertEqual([(item['name'], item['count']) for item in colour['categories']], + [('train', 147), ('validation', 19), ('test', 18)]) + raw = base64.b64decode(colour['codes_u16']) + codes = struct.unpack(f'<{len(raw) // 2}H', raw) + names = [item['name'] for item in colour['categories']] + self.assertEqual([names[code] for code in codes], [record['split'] for record in self.records]) + # The grid and thin cells against the test's own counting of the drawn points. + xs, ys = floats(drawn['x_f32']), floats(drawn['y_f32']) + x0, x1, y0, y1 = drawn['bounds'] + counts = [[0] * 8 for _ in range(8)] + for x, y in zip(xs, ys): + counts[min(7, int((y - y0) / (y1 - y0) * 8))][min(7, int((x - x0) / (x1 - x0) * 8))] += 1 + self.assertEqual(drawn['grid'], {'cells': 8, 'counts': counts}) + filled = [count for line in counts for count in line if count] + most = 0.5 * statistics.median(filled) + own = sorted((count, line, column) for line, row in enumerate(counts) for column, count in enumerate(row) + if count and count <= most) + self.assertEqual([(cell['count'], *cell['cell']) for cell in drawn['thin']], own) + self.assertTrue(own) + numbers = embeddings.embedding_map(self.product(), self.product(), 'texts', colour='field:size')['colour'] + self.assertEqual(numbers['type'], 'number') + self.assertEqual(floats(numbers['values_f32'])[:3], [0.0, 1.0, 2.0]) + self.assertTrue(math.isnan(floats(numbers['values_f32'])[-1])) + tasks = embeddings.embedding_map(self.product(), self.product(), 'texts', colour='annotation:quality') + self.assertEqual([item['name'] for item in tasks['colour']['categories']], ['bad', 'good']) + with self.assertRaises(ProjectError) as raised: + embeddings.embedding_map(self.product(), self.product(), 'texts', colour='size') + self.assertEqual(raised.exception.code, 'invalid') + + def test_records_of_another_product_and_missing_ones(self): + other = self.root / 'records-elsewhere' + other.mkdir() + with open(other / 'records.jsonl', 'w', encoding='utf-8') as handle: + for record in self.records[:100]: + handle.write(json.dumps(record) + '\n') + drawn = embeddings.embedding_map(self.product(), inside.Product('run-records', other), 'texts') + self.assertEqual(drawn['missing'], 84) + + +if __name__ == '__main__': + unittest.main() diff --git a/tuldok_project/embeddings.py b/tuldok_project/embeddings.py new file mode 100644 index 00000000..039718e6 --- /dev/null +++ b/tuldok_project/embeddings.py @@ -0,0 +1,929 @@ +"""Curation by embeddings: a product's embeddings sets, read and searched. + +Owns sections 1, 3 and 4 of docs/plans/training-and-curation/spec-t5.md. A +product holds a set <name> as embeddings/<name>.npy (one row per record, +rows by dimensions, floats) and embeddings/<name>.json, its index (the record +ids in row order, the model, the prefix, which records they are, and +optionally a two-dimensional projection the project's script made). sets() +lists a product's sets with the reason each cannot be read; the five reads +(embedding_map, embedding_neighbours, embedding_duplicates, +embedding_outliers, embedding_leakage) answer the operations of those names +from one set and the product of the records it describes. + +Tuldok computes no embedding. What it computes is standard-library +arithmetic on the rows a script or the step embed wrote: the rows made unit +length (cosine is a dot product, math.sumprod); the leading principal +components of a sample of them, by subspace power iteration with a small +Jacobi solve (Rayleigh-Ritz); every row's coordinates on them and the length +of what they leave out, which bound the distance between two rows from +below, so that the pair searches rule pairs out without reading them and +compute the rest exactly. A search examines rows in a fixed shuffled order +within a budget of comparisons and exact dot products; what it lists is +exactly right for the rows it examined, and it says whether that was all of +them. What is computed for a set is kept while its files are unchanged +(KEPT_SETS of them, KEPT_BYTES in all, least recently used dropped). Nothing +here writes, opens the project or runs the project's code. +""" +import base64 +import bisect +import collections +import heapq +import json +import math +import os +import random +import re +import statistics +import struct +import sys +import threading +from array import array +import operator +from itertools import compress, product, repeat + +from . import inside, inside_arrays +from .inside_archive import locate +from .store import ProjectError + +FORMAT = 'tuldok_embeddings_v1' +DIRECTORY = 'embeddings' +NAME = re.compile(r'[a-z0-9][a-z0-9._-]{0,63}') +_PROJECTION_FILE = re.compile(r'[A-Za-z0-9][A-Za-z0-9._-]{0,127}\.npy') +_ID = re.compile(r'[A-Za-z0-9._-]{1,200}') +INDEX_BYTES = 16 * 1024 * 1024 +ROWS_LIMIT = 50_000 +DIMENSIONS_LIMIT = 4096 +VALUES_LIMIT = 40_000_000 +SETS_LIMIT = 64 +NOTES_LIMIT = 64 +NOTE_CHARACTERS = 1000 +PREFIX_CHARACTERS = 1000 +MODEL_CHARACTERS = 256 +FACT_CHARACTERS = 1024 +METHOD_CHARACTERS = 64 +COMPONENTS = 8 # principal components computed +SAMPLE_VALUES = 2 ** 19 # rows x dimensions of the sample the components come from +SAMPLE_LEAST = 256 +COVARIANCE_DIMENSIONS = 1024 # the sample's covariance is formed whole up to this many dimensions +POWER_TURNS = 200 +POWER_TOLERANCE = 1e-9 +COMPARE_BUDGET = 20_000_000 # comparisons of coordinates one search makes +EXACT_VALUES_BUDGET = 400_000_000 # values multiplied by the exact dot products of one search +KEPT_SETS = 2 +KEPT_BYTES = 400 * 1024 * 1024 +CATEGORIES = 24 +NO_CODE = 65535 +THIN_CELLS = 64 +THIN_RECORDS = 20 +GRID_DIMENSIONS = 5 # coordinates the pair searches bucket rows by +SLACK = 1e-6 # rounding allowed when a bound rules a pair out +_NATIVE_LITTLE = sys.byteorder == 'little' + + +def _refuse(message, code='unsupported'): + raise ProjectError(message, code) + + +# --------------------------------------------------------------------- the index + +def _fact(value): + return value is None or isinstance(value, bool) or (isinstance(value, (int, float)) and math.isfinite(value)) \ + or (isinstance(value, str) and len(value) <= FACT_CHARACTERS) + + +def check_index(value, name): + """The problems of an index (a decoded JSON value) for the set name: a list of sentences, empty when none.""" + if not isinstance(value, dict): + return ['The index is not a JSON object.'] + problems = [] + if value.get('format') != FORMAT: + problems.append(f'Its format must be "{FORMAT}".') + records = value.get('records') + if not isinstance(records, list) or not 1 <= len(records) <= ROWS_LIMIT: + problems.append(f'records must be a list of 1 to {ROWS_LIMIT:,} record ids.') + else: + bad = next((item for item in records if not isinstance(item, str) or not _ID.fullmatch(item)), None) + if bad is not None: + problems.append(f'The record id {str(bad)[:80]!r} is not 1 to 200 characters of A-Z a-z 0-9 . _ -.') + elif len(set(records)) != len(records): + seen, twice = set(), None + for item in records: + if item in seen: + twice = item + break + seen.add(item) + problems.append(f'The record id {twice!r} is listed more than once.') + dimensions = value.get('dimensions') + if type(dimensions) is not int or not 1 <= dimensions <= DIMENSIONS_LIMIT: + problems.append(f'dimensions must be a whole number from 1 to {DIMENSIONS_LIMIT:,}.') + if value.get('metric') != 'cosine': + problems.append('metric must be "cosine".') + model = value.get('model') + if not isinstance(model, dict) or not isinstance(model.get('name'), str) \ + or not 1 <= len(model['name']) <= MODEL_CHARACTERS: + problems.append(f'model must be an object with a name of 1 to {MODEL_CHARACTERS} characters.') + elif not all(isinstance(key, str) and _fact(item) for key, item in model.items()): + problems.append('Each fact of model must be a short string, a number, true, false or null.') + prefix = value.get('prefix') + if prefix is not None and (not isinstance(prefix, str) or len(prefix) > PREFIX_CHARACTERS): + problems.append(f'prefix must be a string of at most {PREFIX_CHARACTERS:,} characters, or null.') + source = value.get('source') + if not isinstance(source, dict) or set(source) - {'dataset', 'run'} \ + or not all(item is None or (isinstance(item, str) and 1 <= len(item) <= 200) + for item in (source.get('dataset'), source.get('run'))): + problems.append('source must be an object of dataset (a reference or null) and run (a run id or null).') + elif source.get('dataset') is not None and not source['dataset'].startswith('datasets/'): + problems.append('source.dataset must be a reference to a dataset, such as datasets/<name>.') + projection = value.get('projection') + if projection is not None: + if not isinstance(projection, dict) or not isinstance(projection.get('file'), str) \ + or not _PROJECTION_FILE.fullmatch(projection['file']) or projection['file'] == f'{name}.npy' \ + or not isinstance(projection.get('method'), str) \ + or not 1 <= len(projection['method']) <= METHOD_CHARACTERS: + problems.append('projection must be null or an object of file (a .npy beside the index, not the ' + f'vectors) and method (1 to {METHOD_CHARACTERS} characters).') + notes = value.get('notes') + if notes is not None and (not isinstance(notes, list) or len(notes) > NOTES_LIMIT + or not all(isinstance(note, str) and len(note) <= NOTE_CHARACTERS for note in notes)): + problems.append(f'notes must be a list of at most {NOTES_LIMIT} sentences of at most {NOTE_CHARACTERS:,} ' + 'characters.') + return problems + + +def _vector_header(place, rows, dimensions, what): + """The NPY header of a (rows, dimensions) array of floats at place, checked; ProjectError otherwise.""" + header = inside_arrays.read_header(place) + if header.kind != 'f': + _refuse(f'{what} must hold floats; it is {header.dtype}.') + if header.fortran and len(header.shape) > 1 and min(header.shape) > 1: + _refuse(f'{what} must be stored in C order.') + if header.shape != [rows, dimensions]: + _refuse(f'{what} has the shape {tuple(header.shape)}; the index says ({rows}, {dimensions}).') + if rows * dimensions > VALUES_LIMIT: + _refuse(f'{what} holds {rows * dimensions:,} values; at most {VALUES_LIMIT:,} are read.', 'too-large') + if header.offset + header.count * header.itemsize > (place.size or 0): + _refuse(f'{what} is shorter than its shape says.') + return header + + +_index_lock = threading.Lock() +_indexes = collections.OrderedDict() # path -> (stat, value) + + +def _read_json(place): + info = os.stat(place.path) + stamp = (info.st_size, info.st_mtime_ns, info.st_ino) + with _index_lock: + kept = _indexes.get(place.path) + if kept is not None and kept[0] == stamp: + _indexes.move_to_end(place.path) + return kept[1] + if info.st_size > INDEX_BYTES: + _refuse(f'The index is {info.st_size:,} bytes; at most {INDEX_BYTES:,} are read.', 'too-large') + with open(place.path, 'rb') as handle: + raw = handle.read(INDEX_BYTES + 1) + try: + value = json.loads(raw.decode('utf-8')) + except (ValueError, RecursionError): + _refuse('The index is not UTF-8 JSON.') + with _index_lock: + _indexes[place.path] = (stamp, value) + while len(_indexes) > 16: + _indexes.popitem(last=False) + return value + + +def read_set(product, name): + """(index, vectors Place, its Header, projection Place and Header or None) of set name, checked.""" + if not isinstance(name, str) or not NAME.fullmatch(name): + _refuse(f'{name!r} is not the name of an embeddings set: 1 to 64 of a-z 0-9 . _ -.', 'invalid') + try: + place = locate(product.root, f'{DIRECTORY}/{name}.json') + except ProjectError: + _refuse(f'Run {product.run_id} has no embeddings set {name}.', 'not-found') + index = _read_json(place) + problems = check_index(index, name) + if problems: + _refuse(f'The embeddings set {name} cannot be read: ' + ' '.join(problems)) + rows, dimensions = len(index['records']), index['dimensions'] + try: + vectors = locate(product.root, f'{DIRECTORY}/{name}.npy') + except ProjectError: + _refuse(f'The embeddings set {name} has no {DIRECTORY}/{name}.npy.') + header = _vector_header(vectors, rows, dimensions, f'{DIRECTORY}/{name}.npy') + projected = None + if index.get('projection') is not None: + file = index['projection']['file'] + try: + where = locate(product.root, f'{DIRECTORY}/{file}') + except ProjectError: + _refuse(f'The embeddings set {name} names the projection {file}, which is not in {DIRECTORY}/.') + projected = (where, _vector_header(where, rows, 2, f'{DIRECTORY}/{file}')) + return index, vectors, header, projected + + +@inside.reading +def sets(product): + """[{name, index (or None), problem (or None)}] of the sets in a product's embeddings/, by name.""" + directory = os.path.join(product.root, DIRECTORY) + if not os.path.isdir(directory) or os.path.islink(directory): + return [] + names = sorted(entry[:-5] for entry in os.listdir(directory) + if entry.endswith('.json') and NAME.fullmatch(entry[:-5])) + found = [] + for name in names[:SETS_LIMIT]: + try: + index = read_set(product, name)[0] + except ProjectError as error: + found.append({'name': name, 'index': None, 'problem': str(error)}) + continue + found.append({'name': name, 'index': index, 'problem': None}) + return found + + +def described(index): + """What the operation embeddings shows of an index (the record ids left out).""" + projection = index.get('projection') + return {'rows': len(index['records']), 'dimensions': index['dimensions'], 'model': index['model'], + 'prefix': index.get('prefix'), 'source': {'dataset': index['source'].get('dataset'), + 'run': index['source'].get('run')}, + 'projection': projection['method'] if projection else None, 'notes': index.get('notes') or []} + + +# --------------------------------------------------------------- linear algebra + +def _unit(vector): + norm = math.sqrt(math.sumprod(vector, vector)) + return [item / norm for item in vector] if norm else list(vector) + + +def _orthonormal(vectors): + """Modified Gram-Schmidt; a vector that vanishes is replaced by a coordinate axis orthogonal to the rest.""" + found = [] + size = len(vectors[0]) if vectors else 0 + for vector in vectors: + work = list(vector) + for basis in found: + dot = math.sumprod(work, basis) + work = [a - dot * b for a, b in zip(work, basis)] + norm = math.sqrt(math.sumprod(work, work)) + if norm < 1e-12: + for axis in range(size): + work = [0.0] * size + work[axis] = 1.0 + for basis in found: + dot = math.sumprod(work, basis) + work = [a - dot * b for a, b in zip(work, basis)] + norm = math.sqrt(math.sumprod(work, work)) + if norm > 1e-6: + break + found.append([item / norm for item in work]) + return found + + +def jacobi(matrix): + """(eigenvalues, eigenvectors as rows) of a small symmetric matrix, largest first, by cyclic Jacobi turns.""" + size = len(matrix) + a = [list(row) for row in matrix] + v = [[1.0 if i == j else 0.0 for j in range(size)] for i in range(size)] + for _ in range(100): + off = math.fsum(a[i][j] ** 2 for i in range(size) for j in range(size) if i != j) + if off <= 1e-30 * max(1e-300, math.fsum(a[i][i] ** 2 for i in range(size))): + break + for p in range(size - 1): + for q in range(p + 1, size): + if abs(a[p][q]) < 1e-300: + continue + theta = (a[q][q] - a[p][p]) / (2 * a[p][q]) + t = math.copysign(1.0, theta) / (abs(theta) + math.sqrt(theta * theta + 1)) + c = 1 / math.sqrt(t * t + 1) + s = t * c + for k in range(size): + akp, akq = a[k][p], a[k][q] + a[k][p], a[k][q] = c * akp - s * akq, s * akp + c * akq + for k in range(size): + apk, aqk = a[p][k], a[q][k] + a[p][k], a[q][k] = c * apk - s * aqk, s * apk + c * aqk + for k in range(size): + vkp, vkq = v[k][p], v[k][q] + v[k][p], v[k][q] = c * vkp - s * vkq, s * vkp + c * vkq + pairs = sorted(((a[i][i], [v[k][i] for k in range(size)]) for i in range(size)), key=lambda item: -item[0]) + return [value for value, _ in pairs], [vector for _, vector in pairs] + + +def principal_components(sample, k, *, turns=POWER_TURNS, tolerance=POWER_TOLERANCE): + """(mean, components, variances, total variance, turns taken) of a sample: a list of rows of equal length. + + Subspace power iteration on the sample's covariance (formed whole up to + COVARIANCE_DIMENSIONS dimensions, else applied as X'(Xv)/n) with k + vectors, orthonormalised and rotated to the covariance's own axes each + turn (Rayleigh-Ritz), until the variances move less than tolerance (of the + largest) or after turns. Each component's largest entry is positive. + """ + count, size = len(sample), len(sample[0]) + k = max(0, min(k, size, count)) + flat = array('d') + for row in sample: + flat.extend(row) + columns = [flat[j::size] for j in range(size)] + mean = [math.fsum(column) / count for column in columns] + centred = [array('d', [item - mean[j] for item in columns[j]]) for j in range(size)] + total = math.fsum(math.sumprod(column, column) for column in centred) / count + if k == 0 or total <= 0: + return mean, [], [], max(total, 0.0), 0 + if size <= COVARIANCE_DIMENSIONS: + covariance = [[0.0] * size for _ in range(size)] + for i in range(size): + for j in range(i, size): + covariance[i][j] = covariance[j][i] = math.sumprod(centred[i], centred[j]) / count + apply = lambda vector: [math.sumprod(row, vector) for row in covariance] # noqa: E731 + else: + rows = [[row[j] - mean[j] for j in range(size)] for row in sample] + def apply(vector): + projected = [math.sumprod(row, vector) for row in rows] + return [math.sumprod(column, projected) / count for column in centred] + generator = random.Random(20261119) + basis = _orthonormal([[generator.gauss(0.0, 1.0) for _ in range(size)] for _ in range(k)]) + previous, taken = None, 0 + values = [0.0] * k + for taken in range(1, turns + 1): + moved = [apply(vector) for vector in basis] + small = [[math.sumprod(basis[i], moved[j]) for j in range(k)] for i in range(k)] + small = [[(small[i][j] + small[j][i]) / 2 for j in range(k)] for i in range(k)] + values, rotation = jacobi(small) + # The Ritz vectors (the basis rotated to the small matrix's axes) and their next power. + moved = [[math.fsum(rotation[r][i] * moved[i][x] for i in range(k)) for x in range(size)] for r in range(k)] + basis_rotated = [[math.fsum(rotation[r][i] * basis[i][x] for i in range(k)) for x in range(size)] + for r in range(k)] + if previous is not None and max(abs(a - b) for a, b in zip(values, previous)) \ + <= tolerance * max(abs(values[0]), 1e-300): + basis = basis_rotated + break + previous = values + basis = _orthonormal(moved) + components = [] + for vector in _orthonormal(basis): + largest = max(vector, key=abs) + components.append([-item for item in vector] if largest < 0 else vector) + variances = [max(0.0, math.sumprod(vector, apply(vector))) for vector in components] + return mean, components, variances, total, taken + + +# ------------------------------------------------------------------- one set read + +class Budget: + """What one search may still do: compare coordinates (compares) and multiply values exactly (values).""" + + def __init__(self, compares, values): + self.compares, self.values = compares, values + + def spent(self): + return self.compares <= 0 or self.values <= 0 + + +class Grid: + """Rows bucketed by their first GRID_DIMENSIONS coordinates in cells 2 x radius wide. Every row whose + coordinates lie within radius of a point's lies in one of the 2 ** dimensions cells around() gives for it: in + each dimension the point's own cell and the neighbour on the side of the cell's half it lies in.""" + + def __init__(self, q, radius): + self.width = max(2.0 * radius, 1e-9) + spans = [max(point[d] for point in q) - min(point[d] for point in q) for d in range(len(q[0]) - 1)] if q else [] + wide = [d for d in range(len(spans)) if spans[d] > self.width] + self.dimensions = wide[:GRID_DIMENSIONS] or [0] + cells = collections.defaultdict(lambda: ([], [])) + for row, point in enumerate(q): + rows, points = cells[tuple(math.floor(point[d] / self.width) for d in self.dimensions)] + rows.append(row) + points.append(point) + self.cells = dict(cells) + + def around(self, point): + choices = [] + for d in self.dimensions: + spot = point[d] / self.width + cell = math.floor(spot) + choices.append((cell, cell - 1) if spot - cell < 0.5 else (cell, cell + 1)) + for key in product(*choices): + found = self.cells.get(key) + if found is not None: + yield found + + +class Analysis: + """One set's rows made unit length, and what is computed from them, kept while its files are unchanged.""" + + def __init__(self, index, rows_array, dimensions, projection): + self.index = index + self.ids = index['records'] + self.n, self.d = len(self.ids), dimensions + self.unit = rows_array + self.view = memoryview(rows_array) + self.rows = [self.view[i * dimensions:(i + 1) * dimensions] for i in range(self.n)] + self.position = {identifier: row for row, identifier in enumerate(self.ids)} + self.projection = projection # [(x, y)] from the script, or None + self.lock = threading.Lock() + self._map = self._coords = None + self.answers, self.grids = {}, {} + self.bytes = rows_array.itemsize * len(rows_array) + + def row(self, i): + return self.rows[i] + + def components(self): + """(mean, components, variances, total, sample size), computed once.""" + with self.lock: + if self._map is None: + count = min(self.n, max(SAMPLE_LEAST, SAMPLE_VALUES // self.d)) + chosen = sorted({row * self.n // count for row in range(count)}) + sample = [self.row(i) for i in chosen] + mean, components, variances, total, _ = principal_components(sample, COMPONENTS) + self._map = (mean, components, variances, total, len(chosen)) + return self._map + + def coords(self): + """(q: per row its coordinates on the components and its residual length, rows sorted by the first + coordinate, those coordinates in that order, each row's place in it).""" + mean, components, _, _, _ = self.components() + with self.lock: + if self._coords is None: + offsets = [math.sumprod(mean, component) for component in components] + mean_square = math.sumprod(mean, mean) + q = [] + for i in range(self.n): + row = self.row(i) + projected = [math.sumprod(row, component) - offset + for component, offset in zip(components, offsets)] + length = 1.0 - 2.0 * math.sumprod(row, mean) + mean_square + residual = math.sqrt(max(0.0, length - math.sumprod(projected, projected))) + q.append(tuple(projected) + (residual,)) + if not components: + q = [(0.0, item[-1]) for item in q] + order = sorted(range(self.n), key=lambda i: (q[i][0], i)) + keys = [q[i][0] for i in order] + place = [0] * self.n + for at, i in enumerate(order): + place[i] = at + self._coords = (q, order, keys, [q[i] for i in order], place) + return self._coords + + def cosine(self, i, j, budget): + budget.values -= self.d + return math.sumprod(self.rows[i], self.rows[j]) + + def grid(self, radius): + """The rows bucketed by their leading coordinates in cells 2 x radius wide (kept per radius).""" + key = round(radius, 12) + with self.lock: + found = self.grids.get(key) + if found is None: + found = Grid(self.coords()[0], radius) + with self.lock: + self.grids[key] = found + while len(self.grids) > 8: + self.grids.pop(next(iter(self.grids))) + return found + + def within(self, i, radius_squared, budget, wanted=None): + """[(j, cosine)] of every row j other than i (with wanted[j] when given) whose distance from i is at most + sqrt(radius_squared): ruled out by the coordinates where they allow, else computed exactly.""" + q = self.coords()[0] + limit = math.sqrt(radius_squared + SLACK) + found = [] + for rows, points in self.grid(math.sqrt(radius_squared)).around(q[i]): + budget.compares -= len(rows) + for j in compress(rows, map(operator.le, map(math.dist, repeat(q[i]), points), repeat(limit))): + if j == i or (wanted is not None and not wanted[j]): + continue + cosine = self.cosine(i, j, budget) + if 2.0 - 2.0 * cosine <= radius_squared: + found.append((j, cosine)) + return found + + def nearest(self, i, k, budget, radius=None): + """[(distance squared, j)] of the k rows nearest i, exactly. + + First among the rows within radius of it (by the grid), which is + exact when k of them are found within radius; else searched outward + along the first coordinate.""" + q, order, keys, sorted_q, place = self.coords() + qi = q[i] + if radius is not None: + limit = radius + SLACK + heap = [] + for rows, points in self.grid(radius).around(qi): + budget.compares -= len(rows) + for j in compress(rows, map(operator.le, map(math.dist, repeat(qi), points), repeat(limit))): + if j != i: + heap.append((max(0.0, 2.0 - 2.0 * self.cosine(i, j, budget)), j)) + if len(heap) >= k: + heap.sort() + if heap[k - 1][0] <= radius * radius: + return heap[:k] + at, heap = place[i], [] # heap of (-distance squared, j) + sides = [at - 1, at + 1] + open_ = [True, True] + while open_[0] or open_[1]: + for side in (0, 1): + if not open_[side]: + continue + spot = sides[side] + if spot < 0 or spot >= self.n: + open_[side] = False + continue + sides[side] += -1 if side == 0 else 1 + worst = -heap[0][0] if len(heap) >= k else math.inf + gap = keys[spot] - qi[0] + if gap * gap > worst + SLACK: + open_[side] = False + continue + budget.compares -= 1 + bound = math.dist(qi, sorted_q[spot]) + if bound * bound > worst + SLACK: + continue + j = order[spot] + distance = max(0.0, 2.0 - 2.0 * self.cosine(i, j, budget)) + if len(heap) < k: + heapq.heappush(heap, (-distance, j)) + elif distance < worst: + heapq.heapreplace(heap, (-distance, j)) + return sorted((-value, j) for value, j in heap) + + def shuffled(self): + rows = list(range(self.n)) + random.Random(f'{self.n}:{self.d}').shuffle(rows) + return rows + + +_lock = threading.Lock() +_kept = collections.OrderedDict() # (root, name) -> (stamp, Analysis) + + +def _stamp(*places): + found = [] + for place in places: + info = os.stat(place.path) + found.append((info.st_size, info.st_mtime_ns, info.st_ino)) + return tuple(found) + + +def _rows(place, header, rows, dimensions): + """The rows of a vectors file made unit length, as one array of 32-bit floats; refused when one is not finite + or all zeros.""" + blob = place.blob() + raw = bytes(blob.view[header.offset:header.offset + rows * dimensions * header.itemsize]) + values = inside_arrays.decode(raw, header) + unit = array('f') + for i in range(rows): + row = values[i * dimensions:(i + 1) * dimensions] + square = math.sumprod(row, row) + if not math.isfinite(square): + _refuse(f'Row {i} of the vectors holds a value that is not finite.') + if square == 0: + _refuse(f'Row {i} of the vectors is all zeros; a cosine needs a direction.') + scale = 1.0 / math.sqrt(square) + unit.extend(map(scale.__mul__, row)) + return unit + + +def _projection(projected, rows): + place, header = projected + blob = place.blob() + raw = bytes(blob.view[header.offset:header.offset + rows * 2 * header.itemsize]) + values = inside_arrays.decode(raw, header) + pairs = [] + for i in range(rows): + x, y = float(values[2 * i]), float(values[2 * i + 1]) + if not (math.isfinite(x) and math.isfinite(y)): + _refuse(f'Row {i} of the projection holds a value that is not finite.') + pairs.append((x, y)) + return pairs + + +def analysis(product, name): + """The Analysis of set name of a product, made once and kept while its files are unchanged.""" + index, vectors, header, projected = read_set(product, name) + places = [vectors] + ([projected[0]] if projected else []) + key, stamp = (product.root, name), _stamp(*places) + with _lock: + kept = _kept.get(key) + if kept is not None and kept[0] == stamp and kept[1].index is index: + _kept.move_to_end(key) + return kept[1] + rows, dimensions = len(index['records']), index['dimensions'] + made = Analysis(index, _rows(vectors, header, rows, dimensions), dimensions, + _projection(projected, rows) if projected else None) + with _lock: + _kept[key] = (stamp, made) + while len(_kept) > KEPT_SETS or (len(_kept) > 1 and sum(item[1].bytes for item in _kept.values()) + > KEPT_BYTES): + _kept.popitem(last=False) + return made + + +def forget(): + with _lock: + _kept.clear() + with _index_lock: + _indexes.clear() + + +# ---------------------------------------------------------------------- the reads + +def _records(records_product, made): + """(the records index's record for each row, or None, how many rows have none).""" + index = inside.index_of(records_product) + found = [index.records[index.by_id[identifier]] if identifier in index.by_id else None + for identifier in made.ids] + return found, sum(record is None for record in found) + + +def _encode(values, code): + packed = array(code, values) + if not _NATIVE_LITTLE: + packed.byteswap() + return base64.b64encode(packed.tobytes()).decode('ascii') + + +def _annotation_value(entry): + if not isinstance(entry, dict): + return None + value = entry.get('value') + if isinstance(value, str): + return value + if isinstance(value, list) and all(isinstance(item, str) for item in value): + return ', '.join(value) if value else '(none)' + state = entry.get('state') + return state if isinstance(state, str) else None + + +def _colour_choices(records): + choices = [] + if any(record and record['split'] for record in records): + choices.append('split') + choices.append('kind') + tasks, keys = [], [] + for record in records: + if record is None: + continue + for task in record['annotations'] or {}: + if task not in tasks and len(tasks) < 32: + tasks.append(task) + for key, value in (record['meta'] or {}).items(): + if key not in keys and len(keys) < 64 and (value is None or isinstance(value, (str, int, float, bool))): + keys.append(key) + return choices + [f'annotation:{task}' for task in sorted(tasks)] + [f'field:{key}' for key in sorted(keys)] + + +def _colour(records, by): + """The colour answer of one choice: categories (with codes) or numbers (with values) per row.""" + if by == 'split': + values = [record['split'] if record else None for record in records] + elif by == 'kind': + values = [record['kind'] if record else None for record in records] + elif by.startswith('annotation:'): + task = by.split(':', 1)[1] + values = [_annotation_value((record['annotations'] or {}).get(task)) if record else None + for record in records] + elif by.startswith('field:'): + key = by.split(':', 1)[1] + values = [(record['meta'] or {}).get(key) if record else None for record in records] + else: + _refuse(f'Colour by split, kind, annotation:<task> or field:<key>, not {by!r}.', 'invalid') + present = [value for value in values if value is not None] + numeric = bool(present) and all(isinstance(value, (int, float)) and not isinstance(value, bool) + and math.isfinite(value) for value in present) + if numeric and len(set(present)) > CATEGORIES: + low, high = min(present), max(present) + return {'by': by, 'type': 'number', 'low': low, 'high': high, 'categories': [], + 'values_f32': _encode([math.nan if value is None else value for value in values], 'f')} + words = [None if value is None else (('true' if value else 'false') if isinstance(value, bool) else str(value)) + for value in values] + counted = collections.Counter(word for word in words if word is not None) + ranked = sorted(counted.items(), key=lambda item: (-item[1], item[0])) + kept = [word for word, _ in ranked[:CATEGORIES]] if len(ranked) <= CATEGORIES \ + else [word for word, _ in ranked[:CATEGORIES - 1]] + code_of = {word: code for code, word in enumerate(kept)} + categories = [{'name': word, 'count': counted[word]} for word in kept] + if len(ranked) > len(kept): + other = len(kept) + categories.append({'name': 'other', 'count': sum(count for word, count in ranked[len(kept):]), + 'other': True}) + else: + other = None + codes = [NO_CODE if word is None else code_of.get(word, other) for word in words] + return {'by': by, 'type': 'category', 'categories': categories, 'codes_u16': _encode(codes, 'H')} + + +def _bounds(points): + xs, ys = [point[0] for point in points], [point[1] for point in points] + x0, x1, y0, y1 = min(xs), max(xs), min(ys), max(ys) + if x1 - x0 < 1e-12: + x0, x1 = x0 - 0.5, x1 + 0.5 + if y1 - y0 < 1e-12: + y0, y1 = y0 - 0.5, y1 + 0.5 + return [x0, x1, y0, y1] + + +def grid(points, bounds, cells): + """(counts row by row, from the lowest y; the rows in each cell).""" + x0, x1, y0, y1 = bounds + counts = [[0] * cells for _ in range(cells)] + members = collections.defaultdict(list) + for row, (x, y) in enumerate(points): + column = min(cells - 1, max(0, int((x - x0) / (x1 - x0) * cells))) + line = min(cells - 1, max(0, int((y - y0) / (y1 - y0) * cells))) + counts[line][column] += 1 + members[line, column].append(row) + return counts, members + + +def thin_cells(counts, members, bounds, ids, fraction): + """The cells holding some points but at most fraction times the median count of those holding any.""" + filled = [count for line in counts for count in line if count] + if not filled: + return [] + most = fraction * statistics.median(filled) + cells = len(counts) + x0, x1, y0, y1 = bounds + width, height = (x1 - x0) / cells, (y1 - y0) / cells + found = [(count, line, column) for line, row in enumerate(counts) for column, count in enumerate(row) + if count and count <= most] + found.sort() + return [{'cell': [line, column], 'count': count, + 'x': [x0 + column * width, x0 + (column + 1) * width], 'y': [y0 + line * height, y0 + (line + 1) * height], + 'records': [ids[row] for row in members[line, column][:THIN_RECORDS]]} + for count, line, column in found[:THIN_CELLS]] + + +@inside.reading +def embedding_map(product, records_product, name, *, colour=None, cells=24, thin=0.25): + made = analysis(product, name) + mean, components, variances, total, sample = made.components() + if made.projection is not None: + points, method, explained = made.projection, made.index['projection']['method'], None + else: + method = 'pca' + offsets = [math.sumprod(mean, component) for component in components[:2]] + while len(offsets) < 2: + offsets.append(0.0) + axes = components[:2] + points = [] + for i in range(made.n): + row = made.row(i) + found = [math.sumprod(row, axis) - offset for axis, offset in zip(axes, offsets)] + points.append((found[0] if found else 0.0, found[1] if len(found) > 1 else 0.0)) + explained = [variance / total if total > 0 else 0.0 for variance in variances[:2]] + records, missing = _records(records_product, made) + bounds = _bounds(points) + counts, members = grid(points, bounds, cells) + choices = _colour_choices(records) + return {'name': name, 'rows': made.n, 'dimensions': made.d, 'model': made.index['model'], 'method': method, + 'explained': explained, 'sample': sample if method == 'pca' else None, 'ids': made.ids, + 'x_f32': inside_arrays.float32_base64([point[0] for point in points]), + 'y_f32': inside_arrays.float32_base64([point[1] for point in points]), + 'bounds': bounds, 'missing': missing, 'colours': choices, + 'colour': _colour(records, colour) if colour else None, + 'grid': {'cells': cells, 'counts': counts}, 'thin': thin_cells(counts, members, bounds, made.ids, thin)} + + +def _shown(records, row): + record = records[row] + return {'split': record['split'] if record else None, 'kind': record['kind'] if record else None} + + +@inside.reading +def embedding_neighbours(product, records_product, name, *, record, limit=12): + made = analysis(product, name) + if record not in made.position: + _refuse(f'The embeddings set {name} has no row for the record {record}.', 'not-found') + i = made.position[record] + mine = made.row(i) + scores = [math.sumprod(mine, made.row(j)) for j in range(made.n)] + best = heapq.nlargest(limit + 1, ((score, -j) for j, score in enumerate(scores) if j != i))[:limit] + records, _ = _records(records_product, made) + return {'record': record, 'neighbours': [{'id': made.ids[-j], 'cosine': score, **_shown(records, -j)} + for score, j in best]} + + +def _kept_answer(made, key, compute): + with made.lock: + if key in made.answers: + return made.answers[key] + found = compute() + with made.lock: + made.answers[key] = found + while len(made.answers) > 16: + made.answers.pop(next(iter(made.answers))) + return found + + +def _budget(): + return Budget(COMPARE_BUDGET, EXACT_VALUES_BUDGET) + + +def duplicate_pairs(made, threshold, rows=None): + """({(a, b): cosine} with a < b, rows examined, complete) of every pair at or above threshold among the rows + examined (rows: those to examine, default every row) within one budget.""" + radius_squared = max(0.0, 2.0 - 2.0 * threshold) + budget, pairs, examined = _budget(), {}, 0 + rows = made.shuffled() if rows is None else rows + for i in rows: + if budget.spent(): + break + for j, cosine in made.within(i, radius_squared, budget): + pairs[min(i, j), max(i, j)] = cosine + examined += 1 + return pairs, examined, examined == len(rows) + + +@inside.reading +def embedding_duplicates(product, records_product, name, *, threshold=0.98, limit=200): + made = analysis(product, name) + pairs, examined, complete = _kept_answer(made, ('duplicates', threshold), + lambda: duplicate_pairs(made, threshold)) + records, _ = _records(records_product, made) + ranked = sorted(pairs.items(), key=lambda item: (-item[1], item[0])) + members = {row for pair in pairs for row in pair} + return {'threshold': threshold, 'total': len(pairs), 'groups': len(members), 'complete': complete, + 'examined': examined, 'rows': made.n, + 'pairs': [{'a': made.ids[a], 'b': made.ids[b], 'cosine': cosine, 'a_split': _shown(records, a)['split'], + 'b_split': _shown(records, b)['split']} for (a, b), cosine in ranked[:limit]]} + + +def outlier_scores(made, k): + """([(distance, row, nearest row)] of the rows examined, complete): distance is one minus the cosine to the + row's k-th nearest.""" + budget, found = _budget(), [] + k = min(k, made.n - 1) + rows = made.shuffled() + if k < 1: + return [], True + # The radius searched first: the 90th percentile of the k-th nearest distance of a few rows, found exactly. + probe = [made.nearest(i, k, budget)[-1][0] for i in rows[:32]] + radius = math.sqrt(sorted(probe)[int(0.9 * (len(probe) - 1))]) if probe else None + for i in rows: + if budget.spent(): + break + near = made.nearest(i, k, budget, radius) + found.append((near[-1][0] / 2.0, i, near[0][1])) + return found, len(found) == len(rows) + + +@inside.reading +def embedding_outliers(product, records_product, name, *, k=5, limit=50): + made = analysis(product, name) + scores, complete = _kept_answer(made, ('outliers', k), lambda: outlier_scores(made, k)) + records, _ = _records(records_product, made) + ranked = sorted(scores, key=lambda item: (-item[0], item[1])) + return {'k': k, 'complete': complete, 'examined': len(scores), 'rows': made.n, + 'median': statistics.median([score for score, _, _ in scores]) if scores else None, + 'outliers': [{'id': made.ids[i], 'distance': distance, 'nearest': made.ids[nearest], + 'split': _shown(records, i)['split']} for distance, i, nearest in ranked[:limit]]} + + +@inside.reading +def embedding_leakage(product, records_product, name, *, threshold=0.95, train='train', limit=200): + made = analysis(product, name) + records, _ = _records(records_product, made) + splits = collections.Counter(record['split'] for record in records if record and record['split']) + if not splits: + return {'threshold': threshold, 'train': train, 'splits': {}, 'pairs': [], 'total': 0, 'leaked': 0, + 'complete': True, 'examined': 0, 'rows': made.n} + in_train = [bool(record) and record['split'] == train for record in records] + held = [i for i in made.shuffled() if records[i] and records[i]['split'] and records[i]['split'] != train] + + def compute(): + radius_squared = max(0.0, 2.0 - 2.0 * threshold) + budget, found, examined = _budget(), [], 0 + if any(in_train): + for i in held: + if budget.spent(): + break + found.extend((cosine, i, j) for j, cosine in made.within(i, radius_squared, budget, in_train)) + examined += 1 + else: + examined = len(held) + return found, examined + + found, examined = _kept_answer(made, ('leakage', threshold, train, tuple(held)), compute) + ranked = sorted(found, key=lambda item: (-item[0], item[1], item[2])) + return {'threshold': threshold, 'train': train, 'splits': dict(sorted(splits.items())), 'total': len(found), + 'leaked': len({i for _, i, _ in found}), 'complete': examined == len(held), 'examined': examined, + 'rows': made.n, + 'pairs': [{'record': made.ids[i], 'split': records[i]['split'], 'near': made.ids[j], 'cosine': cosine} + for cosine, i, j in ranked[:limit]]} + + +def write_npy(path, rows, dimensions, values): + """Write values (row by row) as a little-endian float32 .npy of shape (rows, dimensions): for tests and the + step embed, which hold their rows as numbers.""" + header = "{'descr': '<f4', 'fortran_order': False, 'shape': (%d, %d), }" % (rows, dimensions) + padding = 64 - (10 + len(header) + 1) % 64 + text = (header + ' ' * padding + '\n').encode('latin-1') + packed = array('f', values) + if not _NATIVE_LITTLE: + packed.byteswap() + with open(path, 'wb') as handle: + handle.write(b'\x93NUMPY\x01\x00' + struct.pack('<H', len(text)) + text) + handle.write(packed.tobytes()) diff --git a/tuldok_project/operations.py b/tuldok_project/operations.py index b8b5109e..25fb7555 100644 --- a/tuldok_project/operations.py +++ b/tuldok_project/operations.py @@ -39,6 +39,7 @@ INSTRUCTION_CHARACTERS = 4000 GRAPH_MODULES = 2000 # modules named open or closed by one model_graph (spec-t2.md section 3) GRAPH_OVERLAYS = ('parameters', 'outputs', 'operations', 'change') +EMBEDDING_LIMIT = 1000 # rows of one list of curation by embeddings (spec-t5.md section 4) @dataclass(frozen=True) @@ -119,6 +120,16 @@ def _arguments(required=(), **properties): MODEL_GRAPH = ('path', 'format', 'complete', 'reason', 'method', 'torch', 'model', 'inputs', 'notes', 'counts', 'modules', 'tensors', 'depth', 'open', 'nodes', 'edges') _MODULE_PATHS = {'type': 'array', 'items': {'type': 'string', 'maxLength': 1024}, 'maxItems': GRAPH_MODULES} +_SET_NAME = {'type': 'string', 'minLength': 1, 'maxLength': 64} +_SIMILARITY = {'type': 'number', 'minimum': 0.5, 'maximum': 1} +EMBEDDING_SETS = ('dataset', 'run', 'sets') +EMBEDDING_MAP = ('name', 'rows', 'dimensions', 'model', 'method', 'explained', 'sample', 'ids', 'x_f32', 'y_f32', + 'bounds', 'missing', 'colours', 'colour', 'grid', 'thin') + + +def _embedding_arguments(required=(), **properties): + """The arguments of a read of one embeddings set: run (holding it), name, records_run (whose records).""" + return _arguments(['run', 'name', *required], run=_RUN, name=_SET_NAME, records_run=_RUN, **properties) OPERATIONS = ( @@ -250,6 +261,31 @@ def _arguments(required=(), **properties): Operation('model_graph_compare', "Match the modules of two finished runs' model graphs by path: the same, " 'changed (class or tensor shapes), added or missing.', 'inspect', False, _arguments(['run', 'other_run'], run=_RUN, other_run=_RUN), ('modules', 'counts')), + Operation('embeddings', "List a dataset's embeddings sets: those in its own products and in the products of " + 'the datasets that take it as an input, each with its model, rows and the run whose records they are.', + 'inspect', False, _arguments(['dataset'], dataset=_REFERENCE), EMBEDDING_SETS), + Operation('embedding_map', "Read a map of an embeddings set's records in two dimensions (the script's own " + "projection, or principal components Tuldok computes), each record's colour by a field, the map's " + 'cells and its thin regions.', 'inspect', False, + _embedding_arguments(colour={'type': 'string', 'minLength': 1, 'maxLength': 300}, + cells={'type': 'integer', 'minimum': 8, 'maximum': 64}, + thin={'type': 'number', 'minimum': 0, 'maximum': 1}), EMBEDDING_MAP), + Operation('embedding_neighbours', "List the records of an embeddings set most like one of them, by cosine, " + 'exactly.', 'inspect', False, + _embedding_arguments(['record'], record=_RECORD_ID, limit=_limit(200)), ('record', 'neighbours')), + Operation('embedding_duplicates', "List the pairs of an embeddings set's records at or above a cosine, most " + 'alike first, and whether every record was examined.', 'inspect', False, + _embedding_arguments(threshold=_SIMILARITY, limit=_limit(EMBEDDING_LIMIT)), + ('threshold', 'pairs', 'total', 'groups', 'complete', 'examined', 'rows')), + Operation('embedding_outliers', "List the records of an embeddings set farthest from their k-th nearest " + 'record, and whether every record was examined.', 'inspect', False, + _embedding_arguments(k={'type': 'integer', 'minimum': 1, 'maximum': 50}, limit=_limit(EMBEDDING_LIMIT)), + ('k', 'outliers', 'median', 'complete', 'examined', 'rows')), + Operation('embedding_leakage', "List the records of an embeddings set outside the training split that have a " + 'near-copy in it, at or above a cosine.', 'inspect', False, + _embedding_arguments(threshold=_SIMILARITY, train={'type': 'string', 'minLength': 1, 'maxLength': 200}, + limit=_limit(EMBEDDING_LIMIT)), + ('threshold', 'train', 'splits', 'pairs', 'total', 'leaked', 'complete', 'examined', 'rows')), Operation('training', "List what a run's training script logged, while it runs or after: its scalar series, the " 'tensors whose histograms it kept, its samples and checkpoints, and the lines it could not read.', 'inspect', False, _arguments(['run'], run=_RUN), TRAINING), diff --git a/tuldok_project/service.py b/tuldok_project/service.py index 5dff8c0c..e0c27406 100644 --- a/tuldok_project/service.py +++ b/tuldok_project/service.py @@ -9,11 +9,14 @@ activity row, done or refused. The six operations on build requests are passed to build_requests. The five reads inside a product (spec-d1.md), the three reads of a model's weights (spec-d2.md), the two of the fields a run -kept (spec-d6.md) and the three of a model's graph (spec-t2.md) find the +kept (spec-d6.md), the three of a model's graph (spec-t2.md) and the five of +an embeddings set (docs/plans/training-and-curation/spec-t5.md) find the finished run (and for weights_compare and the graph's overlay and comparison -the other run) with the project open for a moment and read its output -directory through inside.py, inside_weights.py, inside_fields.py and -inside_graph.py after closing it; +the other run, for an embeddings set the run of its records) with the project +open for a moment and read its output directory through inside.py, +inside_weights.py, inside_fields.py, inside_graph.py and embeddings.py after +closing it; embeddings, which lists a dataset's sets, finds the products +under the lock and reads their indexes after; product_file does the same for the file route; those reads run outside the lock, so a long one holds up no other call. The five reads of what a training script logged (docs/plans/training-and-curation/spec-t1.md) do the @@ -57,7 +60,7 @@ import psycopg from . import (activity, annotation_records, annotation_rows, annotations, build_requests, builds, charts, check, - documents, environments, inside, inside_fields, inside_graph, inside_weights, launcher, local, operations, plan, + documents, embeddings, environments, inside, inside_fields, inside_graph, inside_weights, launcher, local, operations, plan, pumas, store, training, workspace) from .documents import Problem @@ -69,7 +72,7 @@ # and reads outside it: decompressing a large member, parsing a large mesh or comparing two large weights files takes # seconds, and the other calls (the page's own readings among them) must not wait for it. inside.py guards what it # keeps. -PRODUCT_ARGUMENTS = ('run', 'other_run') +PRODUCT_ARGUMENTS = ('run', 'other_run', 'records_run') INSIDE_READS = { 'records': lambda found, a: inside.records(found['run'], offset=a.get('offset', 0), limit=a.get('limit', 50), kind=a.get('kind'), split=a.get('split')), @@ -99,6 +102,22 @@ found['run'], kind=a['kind'], against=a.get('against'), other=found.get('other_run'), path=a.get('path'), other_path=a.get('other_path')), 'model_graph_compare': lambda found, a: inside_graph.model_graph_compare(found['run'], other=found['other_run']), + # Curation by embeddings (docs/plans/training-and-curation/spec-t5.md section 4): a set in run's product, the + # records it describes in records_run's (default run's). + 'embedding_map': lambda found, a: embeddings.embedding_map( + found['run'], found.get('records_run', found['run']), a['name'], colour=a.get('colour'), + cells=a.get('cells', 24), thin=a.get('thin', 0.25)), + 'embedding_neighbours': lambda found, a: embeddings.embedding_neighbours( + found['run'], found.get('records_run', found['run']), a['name'], record=a['record'], + limit=a.get('limit', 12)), + 'embedding_duplicates': lambda found, a: embeddings.embedding_duplicates( + found['run'], found.get('records_run', found['run']), a['name'], threshold=a.get('threshold', 0.98), + limit=a.get('limit', 200)), + 'embedding_outliers': lambda found, a: embeddings.embedding_outliers( + found['run'], found.get('records_run', found['run']), a['name'], k=a.get('k', 5), limit=a.get('limit', 50)), + 'embedding_leakage': lambda found, a: embeddings.embedding_leakage( + found['run'], found.get('records_run', found['run']), a['name'], threshold=a.get('threshold', 0.95), + train=a.get('train', 'train'), limit=a.get('limit', 200)), } # The reads of what a training script logged (docs/plans/training-and-curation/spec-t1.md section 4), each a function # of (training.Run, arguments): the run is found under the service's lock, whatever its state, and its files are read @@ -117,7 +136,7 @@ # The calls to the Pumas endpoint (spec-d5.md): each is made outside the service's lock; those that read a project # take the lock themselves, only for their database work. OUTSIDE_LOCK = ANNOTATION_READS + ('endpoint', 'set_endpoint', 'find_endpoints', 'suggestion_models', - 'suggest_annotation') + 'suggest_annotation', 'embeddings') POLL_SECONDS = 1.0 # how often the worker looks for a queued request CLOSE_SECONDS = 30.0 # how long close() waits for the worker WORKER_LOCK = 'build-requests.lock' @@ -594,6 +613,62 @@ def _product(self, run): return inside.Product(run_id, os.path.join(directory, builds.OUTPUT), view, recorded[0] if recorded else None) + def _embeddings(self, arguments, actor): + """A dataset's embeddings sets (spec-t5.md section 3): the products are found under the lock, read after.""" + reference = arguments['dataset'] + reference = reference if reference.startswith('datasets/') else f'datasets/{reference}' + with self._lock: + with self._open() as project: + if project._execute('SELECT 1 FROM {schema}.definitions WHERE directory = %s AND name = %s AND ' + 'NOT removed', ('datasets', reference.split('/', 1)[1])).fetchone() is None: + raise store.ProjectError(f'There is no dataset {reference}.', 'not-found') + holders = [reference] + for name, document in project._execute( + 'SELECT name, document FROM {schema}.definitions WHERE directory = %s AND NOT removed ' + 'ORDER BY name', ('datasets',)).fetchall(): + run = document.get('run') if isinstance(document, dict) else None + inputs = run.get('inputs') if isinstance(run, dict) else None + if isinstance(inputs, dict) and reference in inputs.values() and f'datasets/{name}' != reference: + holders.append(f'datasets/{name}') + found = [(holder, product) for holder in holders for product in builds.products(project, holder) + if product['run_id']] + recorded = {row[0]: row[1] or {} for row in project._execute( + 'SELECT id, inputs FROM {schema}.runs WHERE id = ANY(%s)', + ([product['run_id'] for _, product in found],)).fetchall()} + own = [product['run_id'] for holder, product in found if holder == reference] + sets = [] + for holder, product in found: + try: + listed = embeddings.sets(inside.Product(product['run_id'], product['directory'])) + except store.ProjectError: + continue + for item in listed: + entry = {'run': product['run_id'], 'holder': holder, 'name': item['name'], 'rows': None, + 'dimensions': None, 'model': None, 'prefix': None, 'source': None, 'records_run': None, + 'current': False, 'projection': None, 'notes': [], 'problem': item['problem']} + if item['index'] is not None: + entry.update(embeddings.described(item['index'])) + source = entry['source'] + named = source['dataset'] or holder + if named != reference: + continue + if source['run']: + entry['records_run'] = source['run'] + elif named == holder: + entry['records_run'] = product['run_id'] + else: + used = [value.get('run_id') for value in recorded.get(product['run_id'], {}).values() + if isinstance(value, dict) and value.get('reference') == reference] + entry['records_run'] = used[0] if used else None + if not used: + entry['problem'] = (f'The run {product["run_id"][:12]} that holds it recorded no input ' + f'{reference}, so its records cannot be found.') + entry['current'] = entry['records_run'] in own + elif holder != reference: + continue + sets.append(entry) + return {'dataset': reference, 'run': own[0] if own else None, 'sets': sets} + def _training_run(self, run): """The training.Run of a run in any state, read with the project open for a moment (spec-t1.md).""" with self._open() as project: From bd6e203defe5154957f2406a7c9efa35ffe259e8 Mon Sep 17 00:00:00 2001 From: MrScripty <TheEnvironmentGuy@protonmail.com> Date: Thu, 19 Nov 2026 06:40:23 -0700 Subject: [PATCH 104/131] feat(project): embed and select steps, EmbeddingGemma 2 as the default embedder, freeze by records pumas_operations decodes the embeddings result; pumas.py chooses the embedder (the definition, the machine's setting, else EmbeddingGemma 2 by alias or model id, the released GGUF first, never another model) and asks text_batch and content_batch requests. The step embed writes embeddings/<name>.npy and .json in batches, keeps what was answered and resumes from a failed run; select takes named records; freeze gains records. set_embedder, and endpoint answers the embedder. check, the schemas, the plan (blocked without an endpoint) and the contract are brought up to date. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --- docs/contracts/project-folder.md | 80 +++- docs/plans/training-and-curation/spec-t5.md | 2 +- pumas_operations.py | 13 +- tests/test_tuldok_project_curation.py | 432 ++++++++++++++++++- tests/test_tuldok_project_service.py | 15 +- tuldok_project/builds.py | 54 ++- tuldok_project/check.py | 75 +++- tuldok_project/embeddings.py | 13 +- tuldok_project/local.py | 32 +- tuldok_project/operations.py | 8 +- tuldok_project/plan.py | 13 +- tuldok_project/pumas.py | 174 +++++++- tuldok_project/schemas/benchmark.schema.json | 6 +- tuldok_project/schemas/dataset.schema.json | 6 +- tuldok_project/schemas/recipe.schema.json | 6 +- tuldok_project/schemas/step.schema.json | 6 +- tuldok_project/service.py | 34 +- tuldok_project/steps.py | 392 ++++++++++++++++- 18 files changed, 1300 insertions(+), 61 deletions(-) diff --git a/docs/contracts/project-folder.md b/docs/contracts/project-folder.md index 709042fc..f0691605 100644 --- a/docs/contracts/project-folder.md +++ b/docs/contracts/project-folder.md @@ -191,7 +191,7 @@ object. It is required unless `earlier_work.rebuild` is `no`. | Field | Required | Rule | | --- | --- | --- | | `command` | unless `step` is given | 1 to 64 strings, the program and its arguments; run in the code root. When the first string is exactly `python` it means the environment's interpreter | -| `step` | no | datasets only: `import`, `freeze` or `generate`, a step Tuldok provides in place of a command; see [Steps Tuldok provides](#steps-tuldok-provides) | +| `step` | no | datasets only: `import`, `freeze`, `generate`, `embed` or `select`, a step Tuldok provides in place of a command; see [Steps Tuldok provides](#steps-tuldok-provides) | | `environment` | when the first string of `command` is `python` | reference to `environments/` | | `inputs` | no | at most 32 entries; keys `^[a-z][a-z0-9_]{0,31}$`; values are inputs from `datasets/`, `recipes/` or `steps/` | | `settings` | no | object, free content, written to a file whose path replaces `{settings}`; not together with `settings_file` | @@ -264,12 +264,12 @@ Example, `datasets/sinusoidal-v1.json`: #### Steps Tuldok provides A dataset's `run` names either a `command` or a `step`, one of `import`, -`freeze` and `generate`. A run with `step` has no `command`, `environment`, `outputs`, +`freeze`, `generate`, `embed` and `select`. A run with `step` has no `command`, `environment`, `outputs`, `settings_file`, `env` or `estimate`: the step's outputs are fixed, its settings are inline in `settings`, and it runs with Tuldok's own interpreter (see [The command and its environment](#the-command-and-its-environment)). It may have `resources` and `sources`. A plan shows it as `tuldok import`, -`tuldok freeze` or `tuldok generate`. It is planned, requested, approved, run, cancelled and +`tuldok freeze`, `tuldok generate`, `tuldok embed` or `tuldok select`. It is planned, requested, approved, run, cancelled and recorded like any build, from a commit as builds are. `check` reports a setting the step does not take, a required one missing and a value of the wrong form. @@ -318,6 +318,7 @@ their annotations. Its run takes one input, `"inputs": {"records": | `seed` | yes | an integer of at most 63 bits | | `shares` | yes | 1 to 16 splits and their relative sizes, integers from 0 to 1,000,000, at least one above 0, for example `{"train": 8, "validation": 1, "test": 1}` | | `include` | no | the states of the first task's annotations that take a record in; default `["accepted"]` | +| `records` | no | 1 to 20,000 different record ids of the input: only those are taken, before the first task's states decide (a selection on the map); an id the input does not have fails the step | It reads each task's line file from the commit the build uses, at the project folder's place in the code's Git repository (a scratch build reads @@ -444,6 +445,48 @@ Example, `datasets/poem-lines.json`: } ``` +**`embed`** writes embeddings of its input's records (see +[A dataset's embeddings](#a-datasets-embeddings)) by asking the embedder the +machine's Pumas endpoint serves. Its run takes one input, `"inputs": +{"records": "datasets/<name>"}`, and no `annotations`. Every setting is +optional: + +| Setting | Rule | +| --- | --- | +| `model`, `profile` | the served alias (and its profile) to embed with. Without one, the machine's `embedding_model` (see [The project directory on this machine](#the-project-directory-on-this-machine)); without that, **EmbeddingGemma 2**: the served model whose alias or model id holds `embeddinggemma-2` (ignoring case), `unsloth/embeddinggemma-2-GGUF` first. When none is served the step fails naming the embedders the endpoint does serve; another model is never chosen in its stead | +| `prefix` | at most 1,000 characters put before each text; default the machine's `embedding_prefix`, else `task: clustering \| query: ` | +| `dimensions` | 1 to 4,096, asked as `{"kind": "embeddings", "dimensions": d}` (Pumas truncates and renormalises); checked against an advertised bound | +| `name` | the set's name, 1 to 64 of `a-z 0-9 . _ -`; default the input's name | +| `batch` | records a request carries, 1 to 256, default 32, at most the advertised `input_count` (and `image_count`, 4 when none, for images) | + +Texts (inline, or UTF-8 files of at most 64 KiB) are asked by +`text_embedding` with `{"kind": "text_batch", "texts": [...]}`; PNG and JPEG +images of at most 8 MiB by `multimodal_embedding` with `{"kind": +"content_batch", "items": [{"parts": [{"kind": "image", ...}]}]}`; other +records are not embedded and are said so in the index's `notes`. The +answer must hold one finite vector per item, all of one length. Before +anything is asked the step reads what the endpoint serves and fails when the +model is not served, cannot embed any kind the input holds, or `dimensions` +is past its bound. A request refused before the provider took it is asked +again after 1 s and 2 s; anything else fails the step with the batch's first +record. Every batch answered is kept in the run's output as it comes; when +the dataset's last run failed, the next build takes the rows that run was +answered, asked with the same input run, model, prefix and dimensions, and +asks only for the rest. Its product holds only `embeddings/<name>.npy` and +`.json`, `source` naming the input and its run, `model` what answered +(`name`, `model_id`, `profile`, `capability`, `dimensions_asked`, +`named_by`: `definition`, `setting` or `default`, `via: "pumas"`). Like a +`generate`, its run keeps the endpoint it asked, and a plan on a machine with +no endpoint shows it `blocked`. + +**`select`** takes some of its input's records: `"inputs": {"records": +"datasets/<name>"}` and `"settings": {"records": [ids]}` (1 to 20,000 +different ids). Its product holds exactly those records in the input's +order, each line as the input has it (its `split` and `annotations` kept), +its file linked under `files/`, its hash added when the input has none. An +id the input does not have fails the step. A selection on the map becomes +such a dataset. + ### `model` A model is an architecture. It produces nothing by itself; recipes train it. @@ -1682,7 +1725,8 @@ is 32 hexadecimal characters: | `output/` | what `{output}` names, made empty before the command starts; a succeeded run's `output/` is its product | | `settings.json` | the inline `settings` as the run saw them, when the definition has them | | `tasks.json`, `annotations/` | a freeze's tasks and the line files it read | -| `endpoint.json` | a generate's endpoint, `{address, version}`, as it found it; kept in the run's record as `endpoint` | +| `endpoint.json` | a generate's or an embed's endpoint, `{address, version}`, as it found it; kept in the run's record as `endpoint` | +| `embed.json` | what an embed is told: its input's reference and run, the machine's embedder and prefix, and the output of the last run when it failed | | `stdout.log`, `stderr.log` | the command's standard output and error | | `cancel` | present when cancellation was asked for | | `outcome.json` | how the command ended, written when every process of the run is gone | @@ -2322,6 +2366,7 @@ and result keys of each operation are in its contract. | `endpoint` | inspect | Read the Pumas endpoint this machine uses: its address, whether it answered, and each model and profile it serves with its modalities, its capabilities and what Tuldok can make with it. | | `set_endpoint` | owner | Set the Pumas endpoint this machine uses once it has answered what it serves, or clear it with null. | | `find_endpoints` | owner | List the Pumas endpoints advertising themselves on this machine, for the owner to pick from. | +| `set_embedder` | owner | Set the model this machine embeds with when a definition names none, and the text put before each record's text; null keeps EmbeddingGemma 2 and the default prefix. | | `suggestion_models` | inspect | List, for each kind of record in the product of a task's dataset, the models the Pumas endpoint serves that can suggest a value of the task. | | `suggest_annotation` | edit | Ask a model the Pumas endpoint serves for a value of a task for one record; nothing is stored, and an answer that is not a value of the task is refused. | @@ -2917,7 +2962,7 @@ is two files under `embeddings/` at the top of the product: ``` `records` are the record ids in row order (1 to 50,000 different ids of 1 to -200 of `A-Z a-z 0-9 . _ -`); `dimensions` 1 to 4,096; `metric` is `cosine`; +600 characters without control characters, as products name records); `dimensions` 1 to 4,096; `metric` is `cosine`; `model` an object with a `name` (1 to 256 characters) and other short facts; `prefix` the text put before each record's text, or null; `source` which records the rows are: `dataset` (null for the product's own records) and @@ -3053,7 +3098,7 @@ is given up. ## The Pumas endpoint -Generation and suggestions go through a Pumas endpoint, reached by HTTP +Generation, suggestions and embeddings go through a Pumas endpoint, reached by HTTP only: nothing of Pumas is part of Tuldok. The address is a setting of the machine, `pumas_endpoint` in the settings file (see [The project directory on this machine](#the-project-directory-on-this-machine)), @@ -3081,6 +3126,20 @@ numeric-loopback HTTP address Pumas 0.8.0 serves on, such as `unavailable` when it does not answer). It answers as `endpoint` does, and writes an activity row (`set` or `cleared`). +`endpoint` and `set_endpoint` also answer `embedder`: the machine's +`model`, `profile` and `prefix` (the default prefix when none is set), +`named_by` (`setting` or `default`), `default` (`embeddinggemma-2`), +`chosen` (the served `model`, `profile`, `model_id` and `capabilities` it +resolves to now, or null), `problem` (why none, or null) and `embedders` +(every served model and profile with an embedding capability available: +`model`, `profile`, `model_id`, `capabilities`, `dimensions`). + +**`set_embedder`** (owner) takes `model` (an alias, or null for +EmbeddingGemma 2), `profile` and `prefix` (null for the default), keeps them +in the settings file once the endpoint serves the model with an embedding +capability (refused `not-found` otherwise), writes an activity row (`set` or +`default`), and answers `embedder`. + **`find_endpoints`** takes nothing and answers `endpoints`, each `{address, version, component}`, the Pumas endpoints that advertise themselves on this machine's loopback listeners, and `rejected`, `{server_url, reason}` of those @@ -3102,12 +3161,17 @@ environment variable `TULDOK_SETTINGS` names. It is strict JSON as in [JSON rules](#json-rules), at most 64 KiB, and has no other fields: ```json -{"format": "tuldok_settings_v1", "project_home": "/absolute/path", "pumas_endpoint": "http://127.0.0.1:8765"} +{"format": "tuldok_settings_v1", "project_home": "/absolute/path", "pumas_endpoint": "http://127.0.0.1:8765", + "embedding_model": "nomic-embed", "embedding_prefix": "task: clustering | query: "} ``` `project_home` is optional and must be absolute. `pumas_endpoint` is optional, an `http` or `https` address of at most 2,048 characters with no spaces; it is -set by `set_endpoint` (see [The Pumas endpoint](#the-pumas-endpoint)). The file is read only when +set by `set_endpoint` (see [The Pumas endpoint](#the-pumas-endpoint)). `embedding_model` (1 to 256 +characters), `embedding_profile` (1 to 128) and `embedding_prefix` (at most +1,000) are optional and set by `set_embedder`: the embedder of an `embed` +that names none, in place of EmbeddingGemma 2, and the text put before each +record's text. The file is read only when the environment variable does not decide. A settings file that cannot be read or is not valid stops the command with a message naming the file and the fault, exit status 2, and stops the app's start-up; Tuldok never falls back to diff --git a/docs/plans/training-and-curation/spec-t5.md b/docs/plans/training-and-curation/spec-t5.md index d10a1d7d..2ef970f1 100644 --- a/docs/plans/training-and-curation/spec-t5.md +++ b/docs/plans/training-and-curation/spec-t5.md @@ -26,7 +26,7 @@ A product holds a set of embeddings `<name>` (1 to 64 characters of `a-z 0-9 . _ "notes": ["2 point clouds were not embedded: no model the endpoint serves takes them."]} ``` -- `records`: the record ids in row order, 1 to 50,000 different ids of spec-d1 (1 to 200 of `A-Z a-z 0-9 . _ -`). +- `records`: the record ids in row order, 1 to 50,000 different ids of 1 to 600 characters without control characters (a product read from its files names its records by their addresses, spec-d1). - `dimensions`: 1 to 4,096, the second axis of the `.npy`. `metric`: `cosine` (the only one). - `model`: an object with `name` (1 to 256 characters) and any other short facts (strings, numbers, booleans or null), shown as given. - `prefix`: the text put before each record's text, or null. EmbeddingGemma expects a task prefix (Pumas: "task prefixes … are part of the caller's text"). diff --git a/pumas_operations.py b/pumas_operations.py index df4304fa..86e174d5 100644 --- a/pumas_operations.py +++ b/pumas_operations.py @@ -9,6 +9,7 @@ import hashlib import http.client import json +import math import re import socket import threading @@ -33,7 +34,7 @@ MAX_PIXELS = 4194304 MAX_MESSAGE = 600 # The result kind of each output Tuldok asks for. -RESULT_KINDS = {'text': 'text', 'png_base64': 'image', 'decisions': 'decisions'} +RESULT_KINDS = {'text': 'text', 'png_base64': 'image', 'decisions': 'decisions', 'embeddings_float32': 'embeddings'} # Capabilities Tuldok sends, with their fixed contract-version-1 semantic task. USED_CAPABILITIES = {'chat_generation': 'chat_generation', 'image_generation': 'text_to_image', 'image_to_text': 'image_to_text'} @@ -639,6 +640,16 @@ def result(raw, request_id): response_fields(projected, ('kind', 'answers')) if type(projected['answers']) is not dict: raise ValueError('Invalid typed decisions result.') + elif projected.get('kind') == 'embeddings': + # One finite vector per item asked, all of one length; the caller checks the count against its batch. + response_fields(projected, ('kind', 'vectors')) + vectors = projected['vectors'] + if type(vectors) is not list or not vectors or any(type(vector) is not list or not vector + for vector in vectors): + raise ValueError('Invalid typed embeddings result.') + if len({len(vector) for vector in vectors}) != 1 or not all( + type(value) in (int, float) and math.isfinite(value) for vector in vectors for value in vector): + raise ValueError('Typed embeddings must be finite vectors of one length.') elif projected.get('kind') == 'image': response_fields(projected, ('kind', 'png_base64', 'seed')) if not isinstance(projected['png_base64'], str) or type(projected['seed']) is not int or not 0 <= projected['seed'] <= 4294967295: diff --git a/tests/test_tuldok_project_curation.py b/tests/test_tuldok_project_curation.py index b3c87929..0863b9c1 100644 --- a/tests/test_tuldok_project_curation.py +++ b/tests/test_tuldok_project_curation.py @@ -26,8 +26,14 @@ sys.path.insert(0, str(Path(__file__).resolve().parents[1])) sys.path.insert(0, str(Path(__file__).resolve().parent)) -from tuldok_project import embeddings, inside # noqa: E402 +import hashlib # noqa: E402 +import subprocess # noqa: E402 +import uuid # noqa: E402 + +import agent_api # noqa: E402 +from tuldok_project import builds, check, embeddings, inside, local, operations, plan, pumas, store # noqa: E402 from tuldok_project.store import ProjectError # noqa: E402 +import test_tuldok_project_pumas as fixtures # noqa: E402 DIMENSIONS = 24 @@ -153,7 +159,7 @@ def test_each_rule_of_the_index(self): with self.subTest(key): self.assertIn(words, str(self.refusal(**{key: value}))) self.assertIn('records must be a list', str(self.refusal(records=KeyError))) - self.assertIn('is not 1 to 200 characters', str(self.refusal(records=['a/b']))) + self.assertIn('is not 1 to 600 characters', str(self.refusal(records=['a\tb']))) def test_the_vectors_and_the_projection(self): ids, rows, _, _ = fixture() @@ -396,5 +402,427 @@ def test_records_of_another_product_and_missing_ones(self): self.assertEqual(drawn['missing'], 84) +# ======================================================================= T5b + +def embedder(model, model_id, *, text=True, image=False, profile=None, dimensions=768, input_count=16): + capabilities = [] + if text: + capabilities.append(fixtures._capability('text_embedding', ['text', 'text_batch'], ['embeddings_float32'], + ['text'], ['vector'], + [{'option': 'dimensions', 'minimum': 1.0, 'maximum': float(dimensions)}, + {'option': 'input_count', 'minimum': 1.0, + 'maximum': float(input_count)}])) + if image: + capabilities.append(fixtures._capability('multimodal_embedding', ['png_base64', 'jpeg_base64', 'content_batch'], + ['embeddings_float32'], ['text', 'image'], ['vector'], + [{'option': 'dimensions', 'minimum': 1.0, 'maximum': float(dimensions)}, + {'option': 'image_count', 'minimum': 1.0, 'maximum': 4.0}])) + entry = fixtures._model(model, profile or f'{model}-gpu', capabilities, ['text'] + (['image'] if image else []), + ['vector']) + entry['model_id'] = model_id + return entry + + +def embedding_listing(*extra, gemma=True): + value = fixtures.listing() + if gemma: + value['models'].append(embedder('embeddinggemma-2', 'unsloth/embeddinggemma-2-GGUF', image=True)) + value['models'].append(embedder('nomic-embed', 'nomic-ai/nomic-embed-text-v1.5-GGUF')) + value['models'] += list(extra) + return value + + +def decoded(raw): + import pumas_operations + return pumas_operations.decode_served_models(json.dumps(raw).encode()) + + +def vector_of(content, size): + digest = hashlib.sha256(content.encode('utf-8') if isinstance(content, str) else content).digest() + return [(digest[i % 32] / 255.0 - 0.5) + 0.01 * i for i in range(size)] + + +def embed_respond(body): + """The fake's answer to an embeddings request: a vector made from each item's text or image.""" + size = (body.get('options') or {}).get('dimensions', 12) + if body['input']['kind'] == 'text_batch': + items = body['input']['texts'] + else: + items = [base64.b64decode(item['parts'][0]['data_base64']) for item in body['input']['items']] + return {'kind': 'embeddings', 'vectors': [vector_of(item, size) for item in items]} + + +class Embedder(unittest.TestCase): + """Section 2: EmbeddingGemma 2 by default, never another model silently.""" + + def test_embeddinggemma_2_is_chosen_by_alias_or_model_id_the_released_gguf_first(self): + listing = decoded(embedding_listing()) + entry, named_by = pumas.choose_embedder(listing) + self.assertEqual((entry['model'], entry['model_id'], named_by), + ('embeddinggemma-2', 'unsloth/embeddinggemma-2-GGUF', 'default')) + # By its model id alone, and the released GGUF before another build of it. + other = embedder('gemma-embed-q8', 'someone/EmbeddingGemma-2-Q8') + listing = decoded(embedding_listing(other, embedder('local-gemma', 'unsloth/EmbeddingGemma-2-GGUF'), + gemma=False)) + self.assertEqual(pumas.choose_embedder(listing)[0]['model'], 'local-gemma') + listing = decoded(embedding_listing(other, gemma=False)) + self.assertEqual(pumas.choose_embedder(listing)[0]['model'], 'gemma-embed-q8') + # A named model comes first. + self.assertEqual(pumas.choose_embedder(decoded(embedding_listing()), 'nomic-embed')[0]['model'], + 'nomic-embed') + + def test_refused_when_not_served_naming_the_served_embedders(self): + listing = decoded(embedding_listing(gemma=False)) + with self.assertRaises(pumas.PumasError) as raised: + pumas.choose_embedder(listing) + self.assertEqual(raised.exception.code, 'not-found') + message = str(raised.exception) + self.assertIn('does not serve EmbeddingGemma 2', message) + self.assertIn('nomic-embed (nomic-ai/nomic-embed-text-v1.5-GGUF, nomic-embed-gpu)', message) + self.assertIn('Tuldok does not choose another', message) + # A served EmbeddingGemma 2 whose capability is unavailable is not chosen either. + down = embedder('embeddinggemma-2', 'unsloth/embeddinggemma-2-GGUF') + down['capabilities'][0]['availability'] = {'state': 'unavailable', 'reason': 'not_loaded'} + with self.assertRaises(pumas.PumasError): + pumas.choose_embedder(decoded(embedding_listing(down, gemma=False))) + with self.assertRaises(pumas.PumasError) as raised: + pumas.choose_embedder(decoded(embedding_listing()), 'writer') + self.assertIn('has no embedding capability', str(raised.exception)) + shown = pumas.embedder_shown(listing, {'model': None, 'profile': None, 'prefix': None}) + self.assertEqual((shown['chosen'], shown['named_by'], shown['prefix'], len(shown['embedders'])), + (None, 'default', 'task: clustering | query: ', 1)) + self.assertIn('does not serve EmbeddingGemma 2', shown['problem']) + + def test_routes_batches_and_the_result(self): + listing = decoded(embedding_listing()) + entry = pumas.choose_embedder(listing)[0] + routes = pumas.embedding_routes(entry) + self.assertEqual({kind: route[:2] for kind, route in routes.items()}, + {'text': ('text_embedding', 'text_batch'), 'image': ('multimodal_embedding', 'content_batch')}) + self.assertEqual((pumas.batch_size('text', routes['text'][2], 32), pumas.batch_size('image', routes['image'][2], 32)), + (16, 4)) + with self.assertRaises(pumas.PumasError) as raised: + pumas.check_dimensions(routes, 1024) + self.assertIn('dimensions 1024 is outside the bound 1 to 768', str(raised.exception)) + import pumas_operations + value = pumas_operations.result(json.dumps({'contract_version': 1, 'request_id': 'r', 'result': { + 'kind': 'embeddings', 'vectors': [[0.5, 1.0], [1, 2]]}}).encode(), 'r') + self.assertEqual(value['vectors'], [[0.5, 1.0], [1, 2]]) + for vectors in ([[1.0], [1.0, 2.0]], [], [[]]): + with self.assertRaises(pumas_operations.OperationError): + pumas_operations.result(json.dumps({'contract_version': 1, 'request_id': 'r', 'result': { + 'kind': 'embeddings', 'vectors': vectors}}).encode(), 'r') + + +class Settings(unittest.TestCase): + + def setUp(self): + directory = tempfile.TemporaryDirectory() + self.addCleanup(directory.cleanup) + self.file = Path(directory.name) / 'settings.json' + patcher = mock.patch.dict(os.environ, {local.SETTINGS_VARIABLE: str(self.file)}) + patcher.start() + self.addCleanup(patcher.stop) + + def test_the_machines_embedder_beside_the_endpoint(self): + local.set_pumas_endpoint('http://127.0.0.1:8765') + local.set_embedder('nomic-embed', None, 'task: search result | query: ') + self.assertEqual(local.embedder_settings(), {'model': 'nomic-embed', 'profile': None, + 'prefix': 'task: search result | query: '}) + local.set_pumas_endpoint(None) + self.assertEqual(local.embedder_settings()['model'], 'nomic-embed') + local.set_embedder(None, None, None) + self.assertEqual(json.loads(self.file.read_text()), {'format': local.SETTINGS_FORMAT}) + self.file.write_text(json.dumps({'format': local.SETTINGS_FORMAT, 'embedding_model': ''})) + with self.assertRaises(local.SettingsError): + local.embedder_settings() + + +def _embed(settings=None, source='datasets/notes'): + return {'format': 'tuldok_definition_v1', 'kind': 'dataset', 'title': 'Embedded', + 'run': {'step': 'embed', 'inputs': {'records': source}, 'settings': dict(settings or {})}} + + +def _select(records, source='datasets/notes'): + return {'format': 'tuldok_definition_v1', 'kind': 'dataset', 'title': 'Picked', + 'run': {'step': 'select', 'inputs': {'records': source}, 'settings': {'records': list(records)}}} + + +CURATION = { + 'datasets/notes': fixtures._import({'source': 'data/notes'}), + 'datasets/notes-embedded': _embed({'dimensions': 8, 'batch': 2}), + 'datasets/notes-named': _embed({'model': 'nomic-embed', 'name': 'by-nomic', 'prefix': ''}), + 'datasets/picked': _select(['c.txt', 'a.txt', 'photo.png']), + 'datasets/picked-wrong': _select(['a.txt', 'nobody.txt']), + 'annotations/quality': fixtures._task('datasets/notes', 'class', ['good', 'bad'], title='Quality'), + 'datasets/notes-frozen': {'format': 'tuldok_definition_v1', 'kind': 'dataset', 'title': 'Frozen', + 'run': {'step': 'freeze', 'inputs': {'records': 'datasets/notes'}, + 'annotations': ['annotations/quality'], + 'settings': {'seed': 7, 'shares': {'train': 1}, + 'records': ['a.txt', 'b.txt', 'd.txt']}}}, +} +NOTES = {'a.txt': 'A note about apples.', 'b.txt': 'A note about boats.', 'c.txt': 'A note about cats.', + 'd.txt': 'A note about dogs.', 'e.txt': 'A note about eels.'} + + +def write_curation_project(root, project_id): + folder, code = root / 'project', root / 'code' + for directory in ('datasets', 'annotations'): + (folder / directory).mkdir(parents=True) + (folder / 'tuldok.json').write_text(json.dumps({'format': 'tuldok_project_v1', 'id': project_id, + 'name': 'Curation test project', 'code_root': '../code'}, + indent=2) + '\n', encoding='utf-8') + for reference, document in CURATION.items(): + (folder / f'{reference}.json').write_text(json.dumps(document, indent=2) + '\n', encoding='utf-8') + lines = ''.join(json.dumps({'record': name, 'sha256': None, 'state': 'accepted' if name != 'b.txt' else 'rejected', + 'value': 'good' if name != 'b.txt' else None, 'by': 'owner', + 'at': '2026-11-19T10:00:00Z'}, separators=(',', ':')) + '\n' + for name in ('a.txt', 'b.txt', 'c.txt', 'd.txt')) + (folder / 'annotations' / 'quality.jsonl').write_text(lines, encoding='utf-8') + notes = code / 'data' / 'notes' + notes.mkdir(parents=True) + for name, text in NOTES.items(): + (notes / name).write_text(text, encoding='utf-8') + (notes / 'photo.png').write_bytes(fixtures.png()) + (notes / 'shape.xyz').write_text('0 0 0\n1 1 1\n', encoding='utf-8') + + +class Checked(unittest.TestCase): + """check on the settings of embed, select and freeze's records.""" + + def problems(self, document): + with tempfile.TemporaryDirectory() as directory: + root = Path(directory) + write_curation_project(root, uuid.uuid4().hex) + (root / 'project' / 'datasets' / 'probe.json').write_text(json.dumps(document), encoding='utf-8') + report = check.check_folder(root / 'project') + return {(problem.pointer, problem.severity) for problem in report.problems + if problem.path == 'datasets/probe.json'} + + def test_the_curation_project_checks(self): + with tempfile.TemporaryDirectory() as directory: + root = Path(directory) + write_curation_project(root, uuid.uuid4().hex) + report = check.check_folder(root / 'project') + self.assertEqual([problem for problem in report.problems if problem.severity == 'error'], []) + + def test_settings_refused(self): + self.assertEqual(self.problems(_embed()), set()) + self.assertEqual(self.problems(_embed({'dimensions': 0, 'batch': 999, 'name': 'Bad Name', 'prefix': 3, + 'profile': 'p', 'colour': 1})), + {('/run/settings/dimensions', 'error'), ('/run/settings/batch', 'error'), + ('/run/settings/name', 'error'), ('/run/settings/prefix', 'error'), + ('/run/settings/profile', 'error'), ('/run/settings/colour', 'error')}) + document = _embed() + document['run']['inputs'] = {'prompts': 'datasets/notes'} + self.assertIn(('/run/inputs', 'error'), self.problems(document)) + self.assertEqual(self.problems(_select(['a.txt'])), set()) + self.assertEqual(self.problems(_select([])), {('/run/settings/records', 'error')}) + self.assertEqual(self.problems(_select(['a.txt', 'a.txt'])), {('/run/settings/records', 'error')}) + self.assertEqual(self.problems(_select(['a\nb'])), {('/run/settings/records/0', 'error')}) + frozen = json.loads(json.dumps(CURATION['datasets/notes-frozen'])) + frozen['run']['settings']['records'] = 'a.txt' + self.assertEqual(self.problems(frozen), {('/run/settings/records', 'error')}) + + +@unittest.skipUnless(fixtures.DATABASE, 'TULDOK_DATABASE_URL is not set; database tests need a disposable cluster.') +class Built(fixtures.Endpoint): + """embed, select and freeze's records built for real by builds.execute against the fake.""" + + def setUp(self): + super().setUp() + self.fake['served_models'] = embedding_listing() + self.fake['respond'] = embed_respond + self.root = self.temporary / 'repository' + self.root.mkdir() + self.project_id = uuid.uuid4().hex + write_curation_project(self.root, self.project_id) + self.folder = self.root / 'project' + self.git('init', '-q') + self.git('add', '-A') + self.git('commit', '-q', '-m', 'The project.') + self.addCleanup(store.drop_project, self.project_id) + from tuldok_project.service import Service + self.service = Service(self.folder) + self.addCleanup(self.service.close) + self.addCleanup(embeddings.forget) + + git = fixtures.Project.git + call = fixtures.Project.call + refused = fixtures.Project.refused + build = fixtures.Project.build + product = fixtures.Project.product + + def set_endpoint(self): + return self.call('set_endpoint', {'address': self.base}) + + def stdout(self, item): + return (Path(item['directory']) / 'stdout.log').read_text(encoding='utf-8') + + def test_text_and_images_embedded_by_embeddinggemma_2_in_batches(self): + self.set_endpoint() + done = self.build('datasets/notes-embedded') + notes = self.product('datasets/notes') + made = self.product('datasets/notes-embedded') + files = sorted(str(path.relative_to(made['directory'])) for path in Path(made['directory']).rglob('*') + if path.is_file()) + self.assertEqual(files, ['embeddings/notes.json', 'embeddings/notes.npy']) + index = json.loads((Path(made['directory']) / 'embeddings' / 'notes.json').read_text()) + self.assertEqual(index['records'], ['a.txt', 'b.txt', 'c.txt', 'd.txt', 'e.txt', 'photo.png']) + self.assertEqual((index['dimensions'], index['prefix'], index['source']), + (8, 'task: clustering | query: ', {'dataset': 'datasets/notes', 'run': notes['run_id']})) + self.assertEqual(index['model'], {'name': 'embeddinggemma-2', 'model_id': 'unsloth/embeddinggemma-2-GGUF', + 'profile': 'embeddinggemma-2-gpu', + 'capability': 'multimodal_embedding, text_embedding', 'dimensions_asked': 8, + 'named_by': 'default', 'via': 'pumas'}) + self.assertEqual(index['notes'], ['1 pointcloud records were not embedded: Pumas 0.8.0 embeds texts and images.']) + posts = self.posts() + self.assertEqual([(body['capability'], body['input']['kind'], len(body['input'].get('texts') or + body['input'].get('items'))) + for body in posts], + [('text_embedding', 'text_batch', 2), ('text_embedding', 'text_batch', 2), + ('text_embedding', 'text_batch', 1), ('multimodal_embedding', 'content_batch', 1)]) + self.assertEqual(posts[0]['input']['texts'], ['task: clustering | query: A note about apples.', + 'task: clustering | query: A note about boats.']) + self.assertEqual((posts[0]['output'], posts[0]['options'], posts[0]['model'], posts[0]['profile']), + ('embeddings_float32', {'kind': 'embeddings', 'dimensions': 8}, 'embeddinggemma-2', + 'embeddinggemma-2-gpu')) + self.assertEqual(posts[3]['input']['items'][0]['parts'][0]['encoding'], 'png') + # The rows are the vectors the endpoint answered, in the index's order. + product = inside.Product(made['run_id'], made['directory']) + analysis = embeddings.analysis(product, 'notes') + expected = unit(vector_of('task: clustering | query: A note about cats.', 8)) + self.assertLess(max(abs(a - b) for a, b in zip(analysis.row(2), expected)), 1e-6) + self.assertIn('"stage":"embed","completed":6,"total":6', self.stdout(done['steps'][-1])) + self.assertEqual(fixtures.Project.run_row(self, done['steps'][-1]['run_id'])['endpoint'], + {'address': self.base, 'version': '0.8.0'}) + # Found from the dataset it describes, and read through the operations. + listed = self.call('embeddings', {'dataset': 'notes'}, actor=fixtures.EDITOR) + self.assertEqual((listed['dataset'], listed['run']), ('datasets/notes', notes['run_id'])) + [found] = listed['sets'] + self.assertEqual({key: found[key] for key in ('run', 'holder', 'name', 'rows', 'dimensions', 'records_run', + 'current', 'problem')}, + {'run': made['run_id'], 'holder': 'datasets/notes-embedded', 'name': 'notes', 'rows': 6, + 'dimensions': 8, 'records_run': notes['run_id'], 'current': True, 'problem': None}) + drawn = self.call('embedding_map', {'run': made['run_id'], 'name': 'notes', 'records_run': notes['run_id'], + 'colour': 'kind'}, actor=fixtures.EDITOR) + self.assertEqual((drawn['rows'], drawn['missing'], drawn['method']), (6, 0, 'pca')) + self.assertEqual([item['name'] for item in drawn['colour']['categories']], ['text', 'image']) + near = self.call('embedding_neighbours', {'run': made['run_id'], 'name': 'notes', + 'records_run': notes['run_id'], 'record': 'a.txt', 'limit': 2}) + self.assertEqual(len(near['neighbours']), 2) + self.assertEqual(self.call('embeddings', {'dataset': 'datasets/notes-embedded'})['sets'], []) + self.assertEqual(self.refused('embeddings', {'dataset': 'nothing'}).code, 'not-found') + # Built again only when the definition or its input changes. + self.assertEqual(self.call('plan', {'targets': ['datasets/notes-embedded']})['steps'][-1]['action'], 'built') + + def test_the_machines_embedder_then_the_definitions_model(self): + self.set_endpoint() + shown = self.call('endpoint')['embedder'] + self.assertEqual((shown['named_by'], shown['chosen']['model'], shown['prefix']), + ('default', 'embeddinggemma-2', 'task: clustering | query: ')) + self.assertEqual(self.refused('set_embedder', {'model': 'writer'}).code, 'not-found') + self.assertEqual(self.refused('set_embedder', {'model': 'nomic-embed'}, actor=fixtures.EDITOR).code, + 'forbidden') + kept = self.call('set_embedder', {'model': 'nomic-embed', 'prefix': 'task: search result | query: '}) + self.assertEqual((kept['named_by'], kept['chosen']['model'], kept['prefix']), + ('setting', 'nomic-embed', 'task: search result | query: ')) + self.assertEqual(json.loads(self.settings.read_text())['embedding_model'], 'nomic-embed') + self.build('datasets/notes-embedded') + made = self.product('datasets/notes-embedded') + index = json.loads((Path(made['directory']) / 'embeddings' / 'notes.json').read_text()) + self.assertEqual((index['model']['name'], index['model']['named_by'], index['prefix']), + ('nomic-embed', 'setting', 'task: search result | query: ')) + self.assertEqual(index['records'], ['a.txt', 'b.txt', 'c.txt', 'd.txt', 'e.txt']) + self.assertIn('1 records were not embedded: nomic-embed does not embed image.', index['notes']) + # The definition's model and prefix come before the machine's. + self.call('set_embedder', {'model': None}) + self.build('datasets/notes-named') + made = self.product('datasets/notes-named') + index = json.loads((Path(made['directory']) / 'embeddings' / 'by-nomic.json').read_text()) + self.assertEqual((index['model']['named_by'], index['prefix']), ('definition', None)) + self.assertEqual(self.posts()[-1]['input']['texts'][0], 'A note about apples.') + with store.open_project(self.folder) as project: + rows = project._execute("SELECT operation, outcome, detail FROM {schema}.activity WHERE operation = " + "'set_embedder' ORDER BY at, id").fetchall() + self.assertEqual([tuple(row[:2]) for row in rows], [('set_embedder', 'not-found'), ('set_embedder', 'done'), + ('set_embedder', 'done')]) + + def test_embeddinggemma_2_not_served_fails_before_anything_is_asked(self): + self.fake['served_models'] = embedding_listing(gemma=False) + self.set_endpoint() + done = self.build('datasets/notes-embedded', ok=False) + problem = (Path(done['steps'][-1]['directory']) / 'stderr.log').read_text(encoding='utf-8') + self.assertIn('does not serve EmbeddingGemma 2', problem) + self.assertIn('nomic-embed (nomic-ai/nomic-embed-text-v1.5-GGUF', problem) + self.assertEqual(self.posts(), []) + + def test_a_failure_part_way_then_a_build_that_asks_only_for_the_rest(self): + self.set_endpoint() + self.fake['modes'] = ['not_admitted', 'success', 'success', 'unknown'] + done = self.build('datasets/notes-embedded', ok=False) + failed = done['steps'][-1] + self.assertIn('Batch 3, from the record e.txt, failed', (Path(failed['directory']) / 'stderr.log').read_text()) + self.assertIn('Batch 1 was not admitted', self.stdout(failed)) + self.assertEqual(len(self.posts()), 4) + first_ids = [body['request_id'] for body in self.posts()] + self.assertTrue(first_ids[0].endswith(':1:1') and first_ids[1].endswith(':1:2'), first_ids) + self.fake['requests'].clear() + done = self.build('datasets/notes-embedded') + self.assertIn('4 rows were taken from the failed run before', self.stdout(done['steps'][-1])) + posts = self.posts() + self.assertEqual([body['input'].get('texts') or len(body['input']['items']) for body in posts], + [['task: clustering | query: A note about eels.'], 1]) + made = self.product('datasets/notes-embedded') + index = json.loads((Path(made['directory']) / 'embeddings' / 'notes.json').read_text()) + self.assertEqual(index['records'], ['a.txt', 'b.txt', 'c.txt', 'd.txt', 'e.txt', 'photo.png']) + analysis = embeddings.analysis(inside.Product(made['run_id'], made['directory']), 'notes') + for row, name in enumerate(index['records'][:5]): + expected = unit(vector_of('task: clustering | query: ' + NOTES[name], 8)) + self.assertLess(max(abs(a - b) for a, b in zip(analysis.row(row), expected)), 1e-6) + + def test_no_endpoint_the_plan_says_so(self): + self.build('datasets/notes') + made = self.call('plan', {'targets': ['datasets/notes-embedded']}) + self.assertFalse(made['buildable']) + self.assertEqual(made['steps'][-1]['blocked_by'][0]['reason'], plan.NO_ENDPOINT_EMBED) + + def test_select_and_freeze_take_exactly_the_records_named(self): + self.build('datasets/picked') + made = self.product('datasets/picked') + listed = fixtures.records_of(made['directory']) + self.assertEqual([record['id'] for record in listed], ['a.txt', 'c.txt', 'photo.png']) + self.assertEqual(listed[0]['sha256'], hashlib.sha256(NOTES['a.txt'].encode()).hexdigest()) + self.assertEqual(listed[2]['path'], 'files/photo.png') + self.assertTrue((Path(made['directory']) / 'files' / 'photo.png').is_file()) + done = self.build('datasets/picked-wrong', ok=False) + self.assertIn("The record 'nobody.txt' is not in the input", + (Path(done['steps'][-1]['directory']) / 'stderr.log').read_text()) + self.build('datasets/notes-frozen') + frozen = fixtures.records_of(self.product('datasets/notes-frozen')['directory']) + # a and d are named and accepted; b is named but rejected; c is accepted but not named. + self.assertEqual(sorted(record['id'] for record in frozen), ['a.txt', 'd.txt']) + self.assertEqual({record['split'] for record in frozen}, {'train'}) + + +class Published(unittest.TestCase): + + def test_the_seven_are_in_the_project_folder_profile_and_not_in_the_catalog(self): + names = ('embeddings', 'embedding_map', 'embedding_neighbours', 'embedding_duplicates', 'embedding_outliers', + 'embedding_leakage', 'set_embedder') + from tuldok_project import service + for name in names[1:-1]: + self.assertEqual((operations.by_name(name).who, operations.by_name(name).mutation), ('inspect', False)) + self.assertIn(name, service.INSIDE_READS) + self.assertEqual((operations.by_name('set_embedder').who, operations.by_name('set_embedder').mutation), + ('owner', True)) + folder = {item['id'] for item in agent_api.capabilities('b' * 32, profile='project_folder')['operations']} + catalog = agent_api.capabilities('b' * 32) + self.assertTrue({'project.' + name for name in names} <= folder) + self.assertFalse({'project.' + name for name in names} & {item['id'] for item in catalog['operations']}) + self.assertEqual((len(catalog['operations']), hashlib.sha256(agent_api.encoded(catalog)).hexdigest()), + (110, 'ad5cc7ac91646b39b7a20b9dfca5ec79ed96ded4b5e36732fcf1145f1cc24460')) + + if __name__ == '__main__': unittest.main() diff --git a/tests/test_tuldok_project_service.py b/tests/test_tuldok_project_service.py index ccabfad8..dcf6f505 100644 --- a/tests/test_tuldok_project_service.py +++ b/tests/test_tuldok_project_service.py @@ -48,7 +48,7 @@ class Table(unittest.TestCase): def test_every_operation_is_declared_once(self): names = [operation.name for operation in operations.OPERATIONS] - self.assertEqual(len(names), 69) # the rows of spec-m7.md section 2, of section 2 of spec-w1.md and spec-w3.md, of section 3 of spec-d1.md and spec-d2.md, of section 5 of spec-d4.md, of sections 2 and 4 of spec-d5.md, of section 2 of spec-d6.md, of section 3 of spec-t2.md, and of section 4 of spec-t1.md + self.assertEqual(len(names), 76) # the rows of spec-m7.md section 2, of section 2 of spec-w1.md and spec-w3.md, of section 3 of spec-d1.md and spec-d2.md, of section 5 of spec-d4.md, of sections 2 and 4 of spec-d5.md, of section 2 of spec-d6.md, of section 3 of spec-t2.md, of section 4 of spec-t1.md, and of sections 2 to 4 of spec-t5.md (7) self.assertEqual(len(set(names)), len(names)) for name in REQUEST_OPERATIONS: self.assertIsNotNone(operations.by_name(name)) @@ -80,10 +80,10 @@ def test_mutations_and_owner_rows(self): 'import_values', 'check_environment', 'connect_environment', 'disconnect_environment', 'request_build', 'approve_build', 'decline_build', 'cancel_build', 'cancel_run', 'stop_run', 'set_annotation', 'revert_annotations', - 'set_endpoint'}) + 'set_endpoint', 'set_embedder'}) owner = {operation.name for operation in operations.OPERATIONS if operation.who == 'owner'} self.assertEqual(owner, {'connect_environment', 'disconnect_environment', 'approve_build', 'decline_build', - 'set_endpoint', 'find_endpoints'}) + 'set_endpoint', 'find_endpoints', 'set_embedder'}) def test_error_status(self): self.assertEqual([operations.error_status(code) for code in @@ -224,6 +224,12 @@ def test_every_read(self): 'annotation': {'task': 'none-here', 'record': 'r1'}, 'endpoint': {}, 'find_endpoints': {}, 'suggestion_models': {'task': 'none-here'}, 'suggest_annotation': {'task': 'none-here', 'record': 'r1', 'model': 'm'}, + 'embeddings': {'dataset': 'datasets/numbers'}, + 'embedding_map': {'run': run_id, 'name': 'none-here'}, + 'embedding_neighbours': {'run': run_id, 'name': 'none-here', 'record': 'r1'}, + 'embedding_duplicates': {'run': run_id, 'name': 'none-here'}, + 'embedding_outliers': {'run': run_id, 'name': 'none-here'}, + 'embedding_leakage': {'run': run_id, 'name': 'none-here'}, } reads = [operation for operation in operations.OPERATIONS if not operation.mutation] arguments['build_requests'] = {'state': 'queued', 'limit': 5} @@ -260,6 +266,9 @@ def test_every_read(self): # test_tuldok_project_annotation_rows self.assertEqual(self.refused(operation.name, arguments[operation.name]).code, 'not-found') continue + if operation.name.startswith('embedding_'): # no embeddings here; test_tuldok_project_curation + self.assertEqual(self.refused(operation.name, arguments[operation.name]).code, 'not-found') + continue if operation.name == 'note': # this fixture has no notes; read in test_tuldok_project_workspace self.assertEqual(self.refused(operation.name, arguments['note']).code, 'not-found') continue diff --git a/tuldok_project/builds.py b/tuldok_project/builds.py index 7c575b8e..962f65ab 100644 --- a/tuldok_project/builds.py +++ b/tuldok_project/builds.py @@ -89,6 +89,7 @@ STEP_TASKS_FILE = 'tasks.json' # <run>/tasks.json: what a freeze is told of its tasks STEP_LINES = 'annotations' # <run>/annotations/<name>.jsonl: the line files a freeze read STEP_REPORT = 'endpoint.json' # <run>/endpoint.json: the endpoint a generate asked, and its version +STEP_FACTS = 'embed.json' # <run>/embed.json: what an embed is told (spec-t5.md section 5) REPORT_LIMIT = 4096 TABLES = ( @@ -826,8 +827,13 @@ def _step_argv(self, project, reference, run, step, values, prepared): return argv + ['--code', self.code.code_root] if step == 'generate': return argv + self._generate_argv(project, run, values, prepared) + if step == 'embed': + return argv + self._embed_argv(project, reference, run, values, prepared) + if step == 'select': + self._records_input(project, run, values, step) + return argv + ['--records', values['inputs.records']] if step != 'freeze': - raise StepProblem(f'Tuldok provides no step {step!r}; use import, freeze or generate.') + raise StepProblem(f'Tuldok provides no step {step!r}; use import, freeze, generate, embed or select.') inputs = _declared_inputs({'run': run}) used = inputs.get('records', (None, None))[0] if 'inputs.records' not in values or used is None: @@ -863,17 +869,55 @@ def _step_argv(self, project, reference, run, step, values, prepared): prepared['annotations'] = read return argv + ['--records', values['inputs.records'], '--tasks', tasks_file] - def _generate_argv(self, project, run, values, prepared): - """The arguments of a generate after its settings and output: the machine's endpoint, the report, the input.""" + def _endpoint_argv(self, prepared, doing='generated'): + """--endpoint and --report: the machine's Pumas endpoint, which the run's record keeps.""" try: address = local.pumas_endpoint() except local.SettingsError as exc: raise StepProblem(str(exc)) from None if address is None: - raise StepProblem('No Pumas endpoint is set on this machine, so nothing can be generated; the owner sets ' + raise StepProblem(f'No Pumas endpoint is set on this machine, so nothing can be {doing}; the owner sets ' 'one, then build again.') prepared['endpoint'] = {'address': address, 'version': None} - argv = ['--endpoint', address, '--report', os.path.join(prepared['directory'], STEP_REPORT)] + return ['--endpoint', address, '--report', os.path.join(prepared['directory'], STEP_REPORT)] + + def _records_input(self, project, run, values, step): + """The reference of a step's input records, which must have a product that is not shown through a view.""" + used = _declared_inputs({'run': run}).get('records', (None, None))[0] + if 'inputs.records' not in values or used is None: + raise StepProblem(f'A {step} reads the records of its input records; declare run.inputs.records.') + row = project._execute(f'SELECT document FROM {{schema}}.definitions WHERE NOT removed AND ' + f'{store._REFERENCE_SQL} = %s', (used,)).fetchone() + if row is not None and isinstance(row[0], dict) and row[0].get('view') is not None: + raise StepProblem(f'Its input records ({used}) is shown through a view, and {step} reads only a ' + "product's records.jsonl or its files.") + return used + + def _embed_argv(self, project, reference, run, values, prepared): + """The arguments of an embed: the endpoint, its input, and the facts file (spec-t5.md section 5): the + input's reference and run, the machine's embedder, and the output of the last run when it failed.""" + argv = self._endpoint_argv(prepared, 'embedded') + used = self._records_input(project, run, values, 'embed') + source = _current_product(project, used) + try: + machine = local.embedder_settings() + except local.SettingsError as exc: + raise StepProblem(str(exc)) from None + last = project._execute('SELECT state, directory FROM {schema}.runs WHERE reference = %s ' + 'ORDER BY queued_at DESC LIMIT 1', (reference,)).fetchone() + resume = None + if last is not None and last[0] == 'failed' and last[1] and os.path.isdir(os.path.join(last[1], OUTPUT)): + resume = os.path.join(last[1], OUTPUT) + facts = {'source': {'dataset': used, 'run': source['run_id'] if source else None}, + 'name': documents.parse_reference(used)[1][:64], 'model': machine['model'], + 'profile': machine['profile'], 'prefix': machine['prefix'], 'resume': resume} + file = os.path.join(prepared['directory'], STEP_FACTS) + prepared['files'][file] = (json.dumps(facts, ensure_ascii=False, indent=2) + '\n').encode('utf-8') + return argv + ['--records', values['inputs.records'], '--facts', file] + + def _generate_argv(self, project, run, values, prepared): + """The arguments of a generate after its settings and output: the machine's endpoint, the report, the input.""" + argv = self._endpoint_argv(prepared) used = _declared_inputs({'run': run}).get('prompts', (None, None))[0] if used is not None: row = project._execute(f'SELECT document FROM {{schema}}.definitions WHERE NOT removed AND ' diff --git a/tuldok_project/check.py b/tuldok_project/check.py index a2cef8c2..5469246a 100644 --- a/tuldok_project/check.py +++ b/tuldok_project/check.py @@ -132,9 +132,18 @@ def _check_view(view, path, add): # The settings of each step Tuldok provides (spec-d4.md section 6): {member: required}. STEP_SETTINGS = {'import': {'source': True, 'pattern': False, 'kind': False, 'rights': True, 'lines': False}, - 'freeze': {'seed': True, 'shares': True, 'include': False}, + 'freeze': {'seed': True, 'shares': True, 'include': False, 'records': False}, 'generate': {'make': True, 'model': True, 'profile': False, 'prompt': True, 'count': False, - 'per': False, 'seed': False, 'options': False, 'rights': True}} + 'per': False, 'seed': False, 'options': False, 'rights': True}, + # docs/plans/training-and-curation/spec-t5.md section 5 + 'embed': {'model': False, 'profile': False, 'prefix': False, 'dimensions': False, 'name': False, + 'batch': False}, + 'select': {'records': True}} +SELECT_LIMIT = 20_000 # records named by a select or a freeze's records +EMBED_PREFIX_LIMIT = 1000 +EMBED_DIMENSIONS_LIMIT = 4096 +EMBED_BATCH_LIMIT = 256 +_SET_NAME = re.compile(r'^[a-z0-9][a-z0-9._-]{0,63}$') SEED_LIMIT = 2 ** 63 GENERATE_SEED_LIMIT = 2 ** 32 # a seed Pumas takes is unsigned 32-bit PROMPT_LIMIT = 16_000 # characters of a generate prompt @@ -152,8 +161,9 @@ def _check_step(run, path, add): step = run['step'] settings = run.get('settings') if 'settings' not in run: + needed = [key for key, required in STEP_SETTINGS[step].items() if required] add('error', path, '/run/settings', f'Add the required field \'settings\'; the step {step} needs ' - + ' and '.join(key for key, needed in STEP_SETTINGS[step].items() if needed) + + (' and '.join(needed) if needed else 'it, {} when no setting is given') + '.') if isinstance(settings, dict): for key in settings: @@ -167,7 +177,7 @@ def _check_step(run, path, add): f'Add the required setting {key!r} of the step {step}.') settings = settings if isinstance(settings, dict) else {} where = lambda key: documents.pointer('run', 'settings', key) # noqa: E731 - if step in ('import', 'generate') and 'annotations' in run: + if step in ('import', 'generate', 'embed', 'select') and 'annotations' in run: add('error', path, '/run/annotations', 'Only the step freeze reads annotations; remove annotations.') if step == 'import': _check_import(settings, path, where, add) @@ -175,6 +185,12 @@ def _check_step(run, path, add): add('error', path, '/run/inputs', 'The step import reads files, not other products; remove inputs.') elif step == 'generate': _check_generate(run, settings, path, where, add) + elif step in ('embed', 'select'): + _check_records_input(run, step, path, add) + if step == 'embed': + _check_embed(settings, path, where, add) + elif 'records' in settings: + _check_record_ids(settings['records'], path, where, add) else: _check_freeze(run, settings, path, where, add) @@ -279,6 +295,55 @@ def _check_generate(run, settings, path, where, add): 'what may be done with what is made.') +def _check_records_input(run, step, path, add): + inputs = run.get('inputs') + if not isinstance(inputs, dict) or set(inputs) != {'records'} or not isinstance(inputs['records'], str) \ + or not inputs['records'].startswith('datasets/'): + add('error', path, '/run/inputs', f'The step {step} takes one input, records, naming a dataset: ' + '"inputs": {"records": "datasets/<name>"}.') + + +def _check_record_ids(records, path, where, add): + """records of a select or a freeze: 1 to SELECT_LIMIT different record ids (spec-t5.md section 5).""" + if not isinstance(records, list) or not 1 <= len(records) <= SELECT_LIMIT: + add('error', path, where('records'), f'records must be a list of 1 to {SELECT_LIMIT:,} record ids.') + return + for index, item in enumerate(records): + if not isinstance(item, str) or not 1 <= len(item) <= 600 or any(ord(char) < 32 or ord(char) == 127 + for char in item): + add('error', path, documents.pointer('run', 'settings', 'records', str(index)), + 'A record id is 1 to 600 characters with no control characters.') + return + if len(set(records)) != len(records): + add('error', path, where('records'), 'records names a record more than once.') + + +def _check_embed(settings, path, where, add): + """The settings of the step embed (spec-t5.md section 5); every one is optional.""" + model = settings.get('model') + if 'model' in settings and not (isinstance(model, str) and model and model == model.strip() + and len(model.encode('utf-8', 'surrogatepass')) <= 256 + and not any(ord(char) < 32 or ord(char) == 127 for char in model)): + add('error', path, where('model'), 'model must be the alias a Pumas endpoint serves: 1 to 256 bytes, with no ' + 'spaces around it and no control characters.') + if 'profile' in settings and not (isinstance(settings['profile'], str) and _PROFILE.match(settings['profile'])): + add('error', path, where('profile'), 'profile must be a Pumas profile: 1 to 128 of A-Z a-z 0-9 . _ -.') + if 'profile' in settings and 'model' not in settings: + add('error', path, where('profile'), 'profile goes with model; name the model too.') + prefix = settings.get('prefix') + if 'prefix' in settings and (not isinstance(prefix, str) or len(prefix) > EMBED_PREFIX_LIMIT): + add('error', path, where('prefix'), f'prefix must be a string of at most {EMBED_PREFIX_LIMIT:,} characters.') + dimensions = settings.get('dimensions') + if 'dimensions' in settings and (type(dimensions) is not int or not 1 <= dimensions <= EMBED_DIMENSIONS_LIMIT): + add('error', path, where('dimensions'), f'dimensions must be a whole number from 1 to ' + f'{EMBED_DIMENSIONS_LIMIT:,}.') + if 'name' in settings and not (isinstance(settings['name'], str) and _SET_NAME.match(settings['name'])): + add('error', path, where('name'), 'name must be 1 to 64 of a-z 0-9 . _ -, starting with a letter or digit.') + batch = settings.get('batch') + if 'batch' in settings and (type(batch) is not int or not 1 <= batch <= EMBED_BATCH_LIMIT): + add('error', path, where('batch'), f'batch must be a whole number from 1 to {EMBED_BATCH_LIMIT}.') + + def _check_freeze(run, settings, path, where, add): inputs = run.get('inputs') if not isinstance(inputs, dict) or set(inputs) != {'records'} or not isinstance(inputs['records'], str) \ @@ -307,6 +372,8 @@ def _check_freeze(run, settings, path, where, add): f'The share of {name!r} must be an integer from 0 to {SHARE_LIMIT:,}.') if all(type(size) is int for size in shares.values()) and not any(shares.values()): add('error', path, where('shares'), 'At least one share must be above 0.') + if 'records' in settings: + _check_record_ids(settings['records'], path, where, add) include = settings.get('include') if 'include' in settings: if not isinstance(include, list) or not include or len(set(map(str, include))) != len(include) \ diff --git a/tuldok_project/embeddings.py b/tuldok_project/embeddings.py index 039718e6..4ee5bb6b 100644 --- a/tuldok_project/embeddings.py +++ b/tuldok_project/embeddings.py @@ -49,7 +49,6 @@ DIRECTORY = 'embeddings' NAME = re.compile(r'[a-z0-9][a-z0-9._-]{0,63}') _PROJECTION_FILE = re.compile(r'[A-Za-z0-9][A-Za-z0-9._-]{0,127}\.npy') -_ID = re.compile(r'[A-Za-z0-9._-]{1,200}') INDEX_BYTES = 16 * 1024 * 1024 ROWS_LIMIT = 50_000 DIMENSIONS_LIMIT = 4096 @@ -91,6 +90,13 @@ def _fact(value): or (isinstance(value, str) and len(value) <= FACT_CHARACTERS) +def _record_id(item): + """A record's id as products have them: 1 to 600 characters, no control characters (an address when the + records are a product's files).""" + return isinstance(item, str) and 1 <= len(item) <= 600 and not any(ord(char) < 32 or ord(char) == 127 + for char in item) + + def check_index(value, name): """The problems of an index (a decoded JSON value) for the set name: a list of sentences, empty when none.""" if not isinstance(value, dict): @@ -102,9 +108,10 @@ def check_index(value, name): if not isinstance(records, list) or not 1 <= len(records) <= ROWS_LIMIT: problems.append(f'records must be a list of 1 to {ROWS_LIMIT:,} record ids.') else: - bad = next((item for item in records if not isinstance(item, str) or not _ID.fullmatch(item)), None) + bad = next((item for item in records if not _record_id(item)), None) if bad is not None: - problems.append(f'The record id {str(bad)[:80]!r} is not 1 to 200 characters of A-Z a-z 0-9 . _ -.') + problems.append(f'The record id {str(bad)[:80]!r} is not 1 to 600 characters without control ' + 'characters.') elif len(set(records)) != len(records): seen, twice = set(), None for item in records: diff --git a/tuldok_project/local.py b/tuldok_project/local.py index 4547b3f9..4b052449 100644 --- a/tuldok_project/local.py +++ b/tuldok_project/local.py @@ -12,6 +12,10 @@ The settings file also holds pumas_endpoint, the address of the Pumas endpoint this machine uses (spec-d5.md section 2), or nothing; it is never part of a project folder. pumas.py checks an address before set_pumas_endpoint keeps it. +It may hold the machine's embedder too (docs/plans/training-and-curation/ +spec-t5.md section 2): embedding_model and embedding_profile, the served +alias used in place of EmbeddingGemma 2 when a definition names none, and +embedding_prefix, the text put before each record's text. Working out a path never creates anything; a directory is made only when a caller asks for it with create=True, or by set_project_home. """ @@ -29,7 +33,9 @@ DEFAULT_SETTINGS = os.path.join('~', '.local', 'share', 'tuldok', 'settings.json') SETTINGS_FORMAT = 'tuldok_settings_v1' SETTINGS_LIMIT = 64 * 1024 -SETTINGS_FIELDS = ('format', 'project_home', 'pumas_endpoint') +SETTINGS_FIELDS = ('format', 'project_home', 'pumas_endpoint', 'embedding_model', 'embedding_profile', + 'embedding_prefix') +EMBEDDER_LIMITS = {'embedding_model': 256, 'embedding_profile': 128, 'embedding_prefix': 1000} ENDPOINT_LIMIT = 2048 # characters of pumas_endpoint ENVIRONMENTS = 'environments' _PROJECT_DIRECTORY = re.compile(r'^[a-f0-9]{32}$') @@ -71,9 +77,33 @@ def read_settings(): if 'pumas_endpoint' in settings and endpoint_problem(settings['pumas_endpoint']): raise SettingsError(f'The settings file {path} is not valid: its pumas_endpoint ' f'{endpoint_problem(settings["pumas_endpoint"])}.') + for key, most in EMBEDDER_LIMITS.items(): + value = settings.get(key) + if key in settings and not (isinstance(value, str) and len(value) <= most and (value or key == + 'embedding_prefix')): + raise SettingsError(f'The settings file {path} is not valid: its {key} must be a string of ' + f'{"0" if key == "embedding_prefix" else "1"} to {most} characters.') return settings +def embedder_settings(): + """{model, profile, prefix} of the machine's embedder: each None when the settings file names none.""" + settings = read_settings() + return {'model': settings.get('embedding_model'), 'profile': settings.get('embedding_profile'), + 'prefix': settings.get('embedding_prefix')} + + +def set_embedder(model, profile, prefix): + """Keep the machine's embedder (None removes a key); the caller has checked the model. The file's path.""" + settings = {key: value for key, value in read_settings().items() if key not in EMBEDDER_LIMITS} + for key, value in (('embedding_model', model), ('embedding_profile', profile), ('embedding_prefix', prefix)): + if value is not None: + if not isinstance(value, str) or len(value) > EMBEDDER_LIMITS[key]: + raise ValueError(f'{key} must be a string of at most {EMBEDDER_LIMITS[key]} characters.') + settings[key] = value + return _write_settings(settings) + + def endpoint_problem(value): """Why value cannot be a pumas_endpoint (an http or https address), or None.""" if not isinstance(value, str) or not 1 <= len(value) <= ENDPOINT_LIMIT: diff --git a/tuldok_project/operations.py b/tuldok_project/operations.py index 25fb7555..e1e4900b 100644 --- a/tuldok_project/operations.py +++ b/tuldok_project/operations.py @@ -116,7 +116,8 @@ def _arguments(required=(), **properties): SAVE = ('written', 'deleted', 'results_written', 'results_deleted', 'annotations_written', 'annotations_deleted') CANCEL_RUN = ('id', 'reference', 'subject', 'state', 'cancel_file', 'already_asked') STOP_RUN = ('id', 'reference', 'subject', 'was', 'state', 'killed', 'remaining', 'marked_unknown') -ENDPOINT = ('address', 'answered', 'version', 'models', 'problem') +ENDPOINT = ('address', 'answered', 'version', 'models', 'problem', 'embedder') +EMBEDDER = ('model', 'profile', 'prefix', 'named_by', 'default', 'chosen', 'problem', 'embedders') MODEL_GRAPH = ('path', 'format', 'complete', 'reason', 'method', 'torch', 'model', 'inputs', 'notes', 'counts', 'modules', 'tensors', 'depth', 'open', 'nodes', 'edges') _MODULE_PATHS = {'type': 'array', 'items': {'type': 'string', 'maxLength': 1024}, 'maxItems': GRAPH_MODULES} @@ -377,6 +378,11 @@ def _embedding_arguments(required=(), **properties): 'maxLength': ENDPOINT_CHARACTERS}), ENDPOINT), Operation('find_endpoints', 'List the Pumas endpoints advertising themselves on this machine, for the owner to ' 'pick from.', 'owner', False, _arguments(), ('endpoints', 'rejected')), + Operation('set_embedder', "Set the model this machine embeds with when a definition names none, and the " + 'text put before each record\'s text; null keeps EmbeddingGemma 2 and the default prefix.', 'owner', True, + _arguments(['model'], model={'type': ['string', 'null'], 'minLength': 1, 'maxLength': 256}, + profile={'type': ['string', 'null'], 'minLength': 1, 'maxLength': 128}, + prefix={'type': ['string', 'null'], 'maxLength': 1000}), EMBEDDER), Operation('request_build', "Ask for a build of the targets: the owner's request is queued, an agent's waits for " "the owner's approval (read build_request for its state), and a queued request not started by " 'its expires_at expires.', 'request', True, diff --git a/tuldok_project/plan.py b/tuldok_project/plan.py index 74c6e5c7..5d9bd754 100644 --- a/tuldok_project/plan.py +++ b/tuldok_project/plan.py @@ -21,7 +21,8 @@ built has the action built and is not work; one that is out-of-date or failed is built again, and its reasons say why. build_plan reads those states from builds.status, which looks at the code root's Git history only when some -product exists. A generate step (spec-d5.md section 3) to be built on a +product exists. A generate step (spec-d5.md section 3), or an embed step +(docs/plans/training-and-curation/spec-t5.md section 5), to be built on a machine with no Pumas endpoint set is blocked, says so, and keeps the plan from being buildable, as an environment that is not ready keeps it from running; the settings file is read for that only when such a step is to be @@ -40,6 +41,8 @@ CAUSE_LIMIT = 5 NO_ENDPOINT = ('No Pumas endpoint is set on this machine, so this dataset cannot be generated here; the owner sets ' 'one, then it can be built.') +NO_ENDPOINT_EMBED = ('No Pumas endpoint is set on this machine, so this dataset cannot be embedded here; the owner ' + 'sets one, then it can be built.') _CAUSE_LABELS = ('no', 'needs-work') @@ -288,10 +291,12 @@ def has_endpoint(): step['action'] = action = actions[reference] = 'blocked' if provided == 'freeze': notes.extend(_task_notes(definitions, reference, document)) - if provided == 'generate' and action == 'build' and not has_endpoint(): + if provided in ('generate', 'embed') and action == 'build' and not has_endpoint(): step['action'] = action = actions[reference] = 'blocked' - step['blocked_by'] = [{'reference': reference, 'rebuild': 'endpoint', 'reason': NO_ENDPOINT}] - notes.append(f'{reference} is generated through a Pumas endpoint, and none is set on this machine.') + step['blocked_by'] = [{'reference': reference, 'rebuild': 'endpoint', + 'reason': NO_ENDPOINT if provided == 'generate' else NO_ENDPOINT_EMBED}] + notes.append(f'{reference} is {"generated" if provided == "generate" else "embedded"} through a Pumas ' + 'endpoint, and none is set on this machine.') steps.append(step) continue if action == 'blocked': diff --git a/tuldok_project/pumas.py b/tuldok_project/pumas.py index e01bdea4..82e42e64 100644 --- a/tuldok_project/pumas.py +++ b/tuldok_project/pumas.py @@ -136,16 +136,26 @@ def shown(entry): 'makes': makes(entry)} -def observe(address): - """{address, answered, version, models, problem}: what the endpoint at address serves now, asked once.""" +def observe(address, embedder=None): + """{address, answered, version, models, problem}: what the endpoint at address serves now, asked once. + + With embedder (the machine's setting, local.embedder_settings()), also + embedder: what it resolves to (embedder_shown).""" if address is None: - return {'address': None, 'answered': False, 'version': None, 'models': [], 'problem': NO_ENDPOINT} - try: - listing = served(address) - except PumasError as exc: - return {'address': address, 'answered': False, 'version': None, 'models': [], 'problem': str(exc)} - return {'address': address, 'answered': True, 'version': version(address), - 'models': [shown(entry) for entry in listing['models']], 'problem': None} + found = {'address': None, 'answered': False, 'version': None, 'models': [], 'problem': NO_ENDPOINT} + listing = None + else: + try: + listing = served(address) + except PumasError as exc: + found = {'address': address, 'answered': False, 'version': None, 'models': [], 'problem': str(exc)} + listing = None + else: + found = {'address': address, 'answered': True, 'version': version(address), + 'models': [shown(entry) for entry in listing['models']], 'problem': None} + if embedder is not None: + found['embedder'] = embedder_shown(listing, embedder, found['problem']) + return found def find(): @@ -514,3 +524,149 @@ def _decided(task, vocabulary, answers): if probability > 0.5: chosen.append(term) return chosen, words + + +# ------------------------------------------------------------- embeddings + +# Curation by embeddings (docs/plans/training-and-curation/spec-t5.md sections 2 and 5). The default embedder is +# EmbeddingGemma 2 (the owner, 2026-11-19): a served model whose alias or model id holds DEFAULT_EMBEDDER, the +# released GGUF first. Another model is used only when a definition or the machine's setting names it. +DEFAULT_EMBEDDER = 'embeddinggemma-2' +PREFERRED_EMBEDDER_ID = 'unsloth/embeddinggemma-2-GGUF' +DEFAULT_EMBEDDER_TITLE = 'EmbeddingGemma 2' +DEFAULT_PREFIX = 'task: clustering | query: ' +EMBEDDING_OUTPUT = 'embeddings_float32' +# What each kind of record is embedded by: (capability, the request's input kind). +EMBEDDING_ROUTES = {'text': ('text_embedding', 'text_batch'), 'image': ('multimodal_embedding', 'content_batch')} +EMBED_RESPONSE_BYTES = 64 * 1024 * 1024 +IMAGES_PER_REQUEST = 4 # the release's image bound when none is advertised +IMAGE_REQUEST_BYTES = 16 * 1024 * 1024 + + +def embedding_capabilities(entry): + """The embedding capabilities of a served entry that are available now, in the endpoint's order.""" + return [row['capability'] for row in entry['capabilities'] + if row['capability'] in ('text_embedding', 'multimodal_embedding') + and row['availability']['state'] == 'available' and EMBEDDING_OUTPUT in row['output_formats']] + + +def embedders(listing): + """Every served (model, profile) with an embedding capability available: model, profile, model_id, + capabilities, dimensions (the advertised bound, or None).""" + found = [] + for entry in listing['models']: + names = embedding_capabilities(entry) + if names: + bound = next((_descriptor(entry, name)['option_bounds'].get('dimensions') for name in names + if _descriptor(entry, name)['option_bounds'].get('dimensions')), None) + found.append({'model': entry['model'], 'profile': entry['profile'], 'model_id': entry['model_id'], + 'capabilities': names, 'dimensions': bound}) + return found + + +def _listed(listing): + rows = embedders(listing) + return ', '.join(f'{row["model"]} ({row["model_id"]}, {row["profile"]})' for row in rows) or 'none' + + +def choose_embedder(listing, model=None, profile=None): + """(served entry, named_by) of the embedder: model (and profile) when named, else EmbeddingGemma 2. + + named_by is 'named' or 'default'. PumasError not-found when the named + model, or EmbeddingGemma 2, is not served with an embedding capability + available; another model is never chosen in its stead. + """ + if model is not None: + entry = choose(listing, model, profile) + if not embedding_capabilities(entry): + raise PumasError(f'{entry["model"]} ({entry["profile"]}) has no embedding capability available now; ' + f'the endpoint embeds with: {_listed(listing)}.', 'not-found') + return entry, 'named' + wanted = DEFAULT_EMBEDDER.lower() + found = [entry for entry in listing['models'] if embedding_capabilities(entry) + and (wanted in entry['model'].lower() or wanted in entry['model_id'].lower())] + found.sort(key=lambda entry: entry['model_id'].lower() != PREFERRED_EMBEDDER_ID.lower()) + if not found: + raise PumasError(f'No embedding model is named and the endpoint does not serve {DEFAULT_EMBEDDER_TITLE} ' + f'(an alias or model id holding {DEFAULT_EMBEDDER}, such as {PREFERRED_EMBEDDER_ID}), the ' + f'default embedder; Tuldok does not choose another. It embeds with: {_listed(listing)}. ' + 'Name one as the model, or set the machine\'s embedder.', 'not-found') + return found[0], 'default' + + +def embedder_shown(listing, setting, problem=None): + """The embedder as endpoint shows it: the setting, what it resolves to now and the served embedders.""" + named_by = 'setting' if setting.get('model') else 'default' + shown_ = {'model': setting.get('model'), 'profile': setting.get('profile'), + 'prefix': setting.get('prefix') if setting.get('prefix') is not None else DEFAULT_PREFIX, + 'named_by': named_by, 'default': DEFAULT_EMBEDDER, 'chosen': None, 'problem': problem, + 'embedders': embedders(listing) if listing is not None else []} + if listing is not None: + try: + entry, _ = choose_embedder(listing, setting.get('model'), setting.get('profile')) + except PumasError as exc: + shown_['problem'] = str(exc) + else: + shown_['chosen'] = {'model': entry['model'], 'profile': entry['profile'], 'model_id': entry['model_id'], + 'capabilities': embedding_capabilities(entry)} + return shown_ + + +def embedding_routes(entry): + """{kind: (capability, input kind, its descriptor)} of the kinds of record entry can embed now.""" + found = {} + for kind, (capability, input_kind) in EMBEDDING_ROUTES.items(): + if capability in client.available_capabilities(entry, input_kind, EMBEDDING_OUTPUT): + found[kind] = (capability, input_kind, _descriptor(entry, capability)) + return found + + +def check_dimensions(routes, dimensions): + """Refuse (PumasError invalid) dimensions outside a bound a route's capability advertises.""" + if dimensions is None: + return + for _, _, row in routes.values(): + _bound(row, 'dimensions', dimensions, 'The') + + +def batch_size(kind, row, wanted): + """How many records one request of this route carries: wanted, within the advertised input_count (and + image_count for images, IMAGES_PER_REQUEST when none is advertised).""" + most = wanted + for name in ('input_count',) + (('image_count',) if kind == 'image' else ()): + bound = row['option_bounds'].get(name) + if bound is not None: + most = min(most, max(1, int(bound['maximum']))) + if kind == 'image' and 'image_count' not in row['option_bounds']: + most = min(most, IMAGES_PER_REQUEST) + return max(1, most) + + +def image_part(data): + """The content part of PNG or JPEG bytes, as the release takes it (PumasError invalid otherwise).""" + part, _ = _image(data) + return part + + +def embed_batch(address, listing, entry, route, items, dimensions, request_id, stop=None): + """Ask for one vector per item (texts, or image parts); the vectors, checked, or PumasError. + + route is (capability, input kind, descriptor) of embedding_routes. + """ + capability, input_kind, row = route + if input_kind == 'text_batch': + input_value = {'kind': 'text_batch', 'texts': list(items)} + else: + input_value = {'kind': 'content_batch', 'items': [{'parts': [part]} for part in items]} + options = {'kind': 'embeddings'} + if dimensions is not None: + options['dimensions'] = dimensions + request = _request(entry, row, request_id, input_value, EMBEDDING_OUTPUT, options) + vectors = _exchange(address, listing, request, stop or threading.Event(), EMBED_RESPONSE_BYTES)['vectors'] + if len(vectors) != len(items): + raise PumasError(f'The endpoint answered {len(vectors)} vectors for {len(items)} items.', 'unavailable', + outcome='unknown') + if dimensions is not None and len(vectors[0]) != dimensions: + raise PumasError(f'The endpoint answered vectors of {len(vectors[0])} dimensions; {dimensions} were asked.', + 'unavailable', outcome='unknown') + return vectors diff --git a/tuldok_project/schemas/benchmark.schema.json b/tuldok_project/schemas/benchmark.schema.json index 4215457e..c830c0ad 100644 --- a/tuldok_project/schemas/benchmark.schema.json +++ b/tuldok_project/schemas/benchmark.schema.json @@ -320,9 +320,11 @@ "enum": [ "import", "freeze", - "generate" + "generate", + "embed", + "select" ], - "description": "a step Tuldok provides: import, freeze or generate" + "description": "a step Tuldok provides: import, freeze, generate, embed or select" }, "environment": { "type": "string", diff --git a/tuldok_project/schemas/dataset.schema.json b/tuldok_project/schemas/dataset.schema.json index 03257b51..96e35fe1 100644 --- a/tuldok_project/schemas/dataset.schema.json +++ b/tuldok_project/schemas/dataset.schema.json @@ -269,9 +269,11 @@ "enum": [ "import", "freeze", - "generate" + "generate", + "embed", + "select" ], - "description": "a step Tuldok provides: import, freeze or generate" + "description": "a step Tuldok provides: import, freeze, generate, embed or select" }, "environment": { "type": "string", diff --git a/tuldok_project/schemas/recipe.schema.json b/tuldok_project/schemas/recipe.schema.json index 07413d62..272b4916 100644 --- a/tuldok_project/schemas/recipe.schema.json +++ b/tuldok_project/schemas/recipe.schema.json @@ -251,9 +251,11 @@ "enum": [ "import", "freeze", - "generate" + "generate", + "embed", + "select" ], - "description": "a step Tuldok provides: import, freeze or generate" + "description": "a step Tuldok provides: import, freeze, generate, embed or select" }, "environment": { "type": "string", diff --git a/tuldok_project/schemas/step.schema.json b/tuldok_project/schemas/step.schema.json index 517fe152..a82f1dd5 100644 --- a/tuldok_project/schemas/step.schema.json +++ b/tuldok_project/schemas/step.schema.json @@ -202,9 +202,11 @@ "enum": [ "import", "freeze", - "generate" + "generate", + "embed", + "select" ], - "description": "a step Tuldok provides: import, freeze or generate" + "description": "a step Tuldok provides: import, freeze, generate, embed or select" }, "environment": { "type": "string", diff --git a/tuldok_project/service.py b/tuldok_project/service.py index e0c27406..094b4227 100644 --- a/tuldok_project/service.py +++ b/tuldok_project/service.py @@ -136,7 +136,7 @@ # The calls to the Pumas endpoint (spec-d5.md): each is made outside the service's lock; those that read a project # take the lock themselves, only for their database work. OUTSIDE_LOCK = ANNOTATION_READS + ('endpoint', 'set_endpoint', 'find_endpoints', 'suggestion_models', - 'suggest_annotation', 'embeddings') + 'suggest_annotation', 'embeddings', 'set_embedder') POLL_SECONDS = 1.0 # how often the worker looks for a queued request CLOSE_SECONDS = 30.0 # how long close() waits for the worker WORKER_LOCK = 'build-requests.lock' @@ -206,6 +206,8 @@ def _detail(name, result): return f'{result["reverted"]} reverted' if name == 'set_endpoint': return 'set' if result['address'] else 'cleared' + if name == 'set_embedder': + return 'set' if result['model'] else 'default' return '' @@ -902,19 +904,43 @@ def _revert_annotations(self, arguments, actor): # ------------------------------------------------------- the endpoint + @staticmethod + def _embedder_setting(): + try: + return local.embedder_settings() + except local.SettingsError as exc: + raise store.ProjectError(str(exc), 'invalid') from None + def _endpoint(self, arguments, actor): - return pumas.observe(local.pumas_endpoint()) + return pumas.observe(local.pumas_endpoint(), self._embedder_setting()) + + def _set_embedder(self, arguments, actor): + """Keep the machine's embedder once the endpoint serves it with an embedding capability (spec-t5.md + section 2); a null model is EmbeddingGemma 2, which needs no check.""" + model, profile, prefix = arguments['model'], arguments.get('profile'), arguments.get('prefix') + if model is None and profile is not None: + raise store.ProjectError('A profile goes with a model; name the model too, or clear both.', 'invalid') + if model is not None: + address = local.pumas_endpoint() + if address is None: + raise store.ProjectError(pumas.NO_ENDPOINT, 'unavailable') + try: + pumas.choose_embedder(pumas.served(address), model, profile) + except pumas.PumasError as exc: + raise store.ProjectError(str(exc), exc.code) from None + local.set_embedder(model, profile, prefix) + return self._endpoint({}, actor)['embedder'] def _set_endpoint(self, arguments, actor): """Ask the address once what it serves and keep it when it answered; null clears the setting.""" if arguments['address'] is None: local.set_pumas_endpoint(None) - return pumas.observe(None) + return pumas.observe(None, self._embedder_setting()) try: address = pumas.normalize(arguments['address']) except pumas.PumasError as exc: raise store.ProjectError(str(exc), exc.code) from None - seen = pumas.observe(address) + seen = pumas.observe(address, self._embedder_setting()) if not seen['answered']: raise store.ProjectError(f'The Pumas endpoint at {address} did not answer, so it was not set: ' f'{seen["problem"]}', 'unavailable') diff --git a/tuldok_project/steps.py b/tuldok_project/steps.py index ca5100a2..9c8ed328 100644 --- a/tuldok_project/steps.py +++ b/tuldok_project/steps.py @@ -1,14 +1,19 @@ """The steps Tuldok provides: import files into a dataset, freeze a dataset with splits from its annotations, -and generate a dataset by asking a model a Pumas endpoint serves. +generate a dataset by asking a model a Pumas endpoint serves, embed a dataset's records through that endpoint, +and select some of a dataset's records. -Owns section 6 of docs/plans/definition-first-projects/spec-d4.md and section -3 of spec-d5.md. A dataset whose run names a step (run.step) is built by +Owns section 6 of docs/plans/definition-first-projects/spec-d4.md, section +3 of spec-d5.md and section 5 of docs/plans/training-and-curation/spec-t5.md +(embed, select, and freeze's records). A dataset whose run names a step (run.step) is built by Tuldok's own interpreter running python -m tuldok_project.steps import <settings file> <output directory> --code <code root> python -m tuldok_project.steps freeze <settings file> <output directory> --records <input product> --tasks <file> python -m tuldok_project.steps generate <settings file> <output directory> --endpoint <address> --report <file> [--records <input product>] + python -m tuldok_project.steps embed <settings file> <output directory> --endpoint <address> + --report <file> --records <input product> --facts <file> + python -m tuldok_project.steps select <settings file> <output directory> --records <input product> with Tuldok's code first on the module path and the snapshot's code off it (builds.py sets PYTHONSAFEPATH and PYTHONPATH). A step reads files and writes @@ -23,8 +28,14 @@ writes the address and the endpoint's version to its report file, which the build keeps in the run's record. -import_files, freeze_records and generate_records are the steps as functions -on directories; main() is the command line. +embed reaches the endpoint the same way; the facts file the build writes +tells it which records it embeds (the input's reference and run), the +machine's embedder and prefix, and the output of the dataset's last run when +that run failed, from which it takes the rows already answered. + +import_files, freeze_records, generate_records, embed_records and +select_records are the steps as functions on directories; main() is the +command line. """ import argparse import hashlib @@ -49,7 +60,7 @@ 'mesh': ('.obj', '.stl'), 'array': ('.npy', '.npz', '.safetensors'), } -STEPS = ('import', 'freeze', 'generate') +STEPS = ('import', 'freeze', 'generate', 'embed', 'select') RECORD_LIST = 'records.jsonl' FILES = 'files' DEFAULT_PATTERN = '**/*' @@ -66,6 +77,10 @@ MAKES = ('text', 'image') # what generate makes (spec-d5.md section 3) GENERATE_LIMIT = 100_000 # items one generate makes RETRY_PAUSES = (1.0, 2.0) # before asking again an item the endpoint did not admit; twice at most +EMBED_BATCH = 32 # records one embed request carries, unless the definition says +EMBED_TEXT_BYTES = LINE_BYTES # a text record embedded (inline, or a UTF-8 file) +EMBED_IMAGE_BYTES = 8 * 1024 * 1024 # an image embedded (the release's bound on one image) +SELECT_LIMIT = 20_000 # records one select (or freeze's records) names class StepError(Exception): @@ -489,7 +504,7 @@ def freeze_records(settings, output, *, records, tasks, view=None, out=print): raise StepError('freeze needs at least one task.') root = os.path.realpath(records) counts = dict.fromkeys(('records', 'included', 'stale', 'excluded', 'unannotated', 'invalid', 'stale_other', - 'missing_files', 'too_long', 'bad_lines', 'copied'), 0) + 'missing_files', 'too_long', 'bad_lines', 'copied', 'not_named'), 0) by_id = _input_records(root, view, counts) counts['records'] = len(by_id) rows = [] @@ -498,6 +513,15 @@ def freeze_records(settings, output, *, records, tasks, view=None, out=print): rows.append(found) counts['invalid'] += invalid first, first_name = rows[0], tasks[0]['reference'].split('/', 1)[1] + if settings.get('records') is not None: + # Only the records named (a selection on the map, spec-t5.md section 5), before the states decide. + named = set(settings['records']) + absent = next((identifier for identifier in settings['records'] if identifier not in by_id), None) + if absent is not None: + raise StepError(f'The record {absent!r} named in records is not in the input.') + counts['not_named'] = sum(1 for identifier in first if identifier not in named) + first = {identifier: row for identifier, row in first.items() if identifier in named} + by_id = {identifier: record for identifier, record in by_id.items() if identifier in named} progress = Progress('freeze', len(first), out) progress(0, {}) chosen = [] @@ -527,6 +551,7 @@ def freeze_records(settings, output, *, records, tasks, view=None, out=print): _say(out, counts, (('stale', f'annotations of {first_name} are stale (the record is gone or its content ' 'differs) and were left out.'), ('excluded', f'records were left out by their state under {first_name}.'), + ('not_named', 'annotated records were left out since records does not name them.'), ('unannotated', f'records have no annotation under {first_name} and were left out.'), ('invalid', 'annotations are not valid for their task and were not read.'), ('stale_other', 'stale annotations of the other tasks were not carried.'), @@ -748,6 +773,347 @@ def _generated_record(output, identifier, make, made, rights, origin, counts): 'bytes': len(data), 'rights': rights, 'origin': origin} +# ------------------------------------------------------------------- select + +def select_records(settings, output, *, records, view=None, out=print): + """The select step (spec-t5.md section 5): the named records of the input product, in its order, each line as + the input has it (split and annotations kept), its file linked under files/. Returns the counts.""" + wanted = settings['records'] + root = os.path.realpath(records) + counts = dict.fromkeys(('records', 'selected', 'missing_files', 'too_long', 'bad_lines', 'copied'), 0) + by_id = _input_records(root, view, counts) + counts['records'] = len(by_id) + absent = next((identifier for identifier in wanted if identifier not in by_id), None) + if absent is not None: + raise StepError(f'The record {absent!r} is not in the input, which holds {len(by_id):,} records.') + named = set(wanted) + progress = Progress('select', len(named), out) + progress(0, {}) + used_ids, placed = set(), {} + with open(os.path.join(output, RECORD_LIST), 'x', encoding='utf-8') as listing: + for record in by_id.values(): + if record['id'] not in named: + continue + line = _selected(record, root, output, placed, used_ids, counts) + if line is not None: + listing.write(line) + counts['selected'] += 1 + progress(counts['selected'], {'selected': counts['selected']}) + progress(counts['selected'], {'selected': counts['selected']}, final=True) + out(f'{counts["selected"]} of {counts["records"]} records selected.') + _say(out, counts, (('missing_files', 'records whose file is missing from the input were left out.'), + ('too_long', f'records too long for one line ({LINE_BYTES} bytes) were left out.'), + ('bad_lines', f'lines of the input\'s {RECORD_LIST} are not records and were skipped.'), + ('copied', 'files were copied, since they could not be linked.'))) + return counts + + +def _selected(record, root, output, placed, used_ids, counts): + """The records.jsonl line of one selected record, as the input has it, its file linked under files/.""" + keys = (*_FROZEN_KEYS, 'split', 'annotations') + line = {key: record[key] for key in keys if record.get(key) is not None} + extra = {key: value for key, value in record.items() if key not in keys and key != 'hash'} + if extra: + line['meta'] = {**extra, **(line.get('meta') or {})} + line['sha256'] = _record_hash(root, record) + if line['sha256'] is None: + del line['sha256'] + if record.get('path') is not None: + outer = record['path'].split('!', 1)[0] + source = _confined(root, outer) + if source is None: + counts['missing_files'] += 1 + return None + target = outer if outer.startswith(f'{FILES}/') else f'{FILES}/{outer}' + if target not in placed: + if _place(source, os.path.join(output, *target.split('/'))) == 'copy': + counts['copied'] += 1 + placed[target] = os.path.getsize(source) + line['path'] = target + record['path'][len(outer):] + if '!' not in record['path'] and not isinstance(line.get('bytes'), int): + line['bytes'] = placed[target] + identifier = record['id'] if _ID.fullmatch(record['id']) else id_from(record['id']) + line['id'] = unique(identifier, used_ids, ID_LIMIT) + if identifier != record['id']: + line.setdefault('meta', {})['selected_from'] = record['id'] + ordered = {key: line[key] for key in keys if key in line} + text = _line(ordered) + if len(text.encode('utf-8')) > LINE_BYTES: + counts['too_long'] += 1 + return None + return text + + +# -------------------------------------------------------------------- embed + +def _embeddable(root, record, counts): + """(kind, what is sent: a text or image bytes) of one input record, or None (counted) when it is not sent.""" + kind = record['kind'] + if kind == 'text': + if record.get('path') is None: + text = record['text'] + else: + full = _confined(root, record['path']) if '!' not in record['path'] else None + if full is None or os.path.getsize(full) > EMBED_TEXT_BYTES: + counts['unread'] += 1 + return None + with open(full, 'rb') as handle: + try: + text = handle.read().decode('utf-8') + except UnicodeDecodeError: + counts['unread'] += 1 + return None + if not text.strip() or len(text.encode('utf-8', 'surrogatepass')) > EMBED_TEXT_BYTES: + counts['unread'] += 1 + return None + return 'text', text + if kind == 'image': + full = _confined(root, record['path']) if record.get('path') and '!' not in record['path'] else None + if full is None or os.path.getsize(full) > EMBED_IMAGE_BYTES: + counts['unread'] += 1 + return None + with open(full, 'rb') as handle: + data = handle.read() + if not (data.startswith(b'\x89PNG\r\n\x1a\n') or data.startswith(b'\xff\xd8')): + counts['unread'] += 1 + return None + return 'image', data + counts['other_kinds'] += 1 + counts.setdefault('kinds', {}) + counts['kinds'][kind] = counts['kinds'].get(kind, 0) + 1 + return None + + +class _Partial: + """The rows answered so far, appended as they come: embeddings/.<name>.partial (32-bit floats, little-endian), + .<name>.partial.ids (one id a line) and .<name>.partial.json (what they were asked with).""" + + def __init__(self, directory, name): + self.rows = os.path.join(directory, f'.{name}.partial') + self.ids = os.path.join(directory, f'.{name}.partial.ids') + self.meta = os.path.join(directory, f'.{name}.partial.json') + + def read(self, expected): + """{id: row bytes} of a partial whose meta equals expected; {} when there is none or it differs.""" + try: + with open(self.meta, encoding='utf-8') as handle: + meta = json.load(handle) + if meta != expected: + return {} + with open(self.ids, encoding='utf-8') as handle: + ids = [line.rstrip('\n') for line in handle if line.endswith('\n')] + width = meta['width'] * 4 if meta.get('width') else None + with open(self.rows, 'rb') as handle: + data = handle.read() + except (OSError, ValueError, KeyError, TypeError): + return {} + if not width: + return {} + count = min(len(ids), len(data) // width) + return {ids[i]: data[i * width:(i + 1) * width] for i in range(count)} + + +def _float_bytes(vector): + import array as array_module + packed = array_module.array('f', vector) + if sys.byteorder != 'little': + packed.byteswap() + return packed.tobytes() + + +def embed_records(settings, output, *, endpoint, records, facts, report=None, out=print, pauses=RETRY_PAUSES): + """The embed step (spec-t5.md section 5): one vector per text and image record of the input product, asked of + the embedder the endpoint serves, written as embeddings/<name>.npy and .json. + + facts: {source: {dataset, run}, name (the default set name), model, + profile, prefix (the machine's), resume (a failed run's output, or + None)}. Nothing is asked before what the endpoint serves has been read and + every kind of record checked against it. Returns the counts. + """ + from . import embeddings, pumas # the step's one way to the endpoint, and the contract's writer + root = os.path.realpath(records) + counts = dict.fromkeys(('embedded', 'resumed', 'records', 'unread', 'other_kinds', 'bad_lines', 'no_route'), 0) + by_id = _input_records(root, None, counts) + counts['records'] = len(by_id) + items = [] + for identifier, record in by_id.items(): + found = _embeddable(root, record, counts) + if found is not None: + items.append((identifier, *found)) + if not items: + raise StepError('Nothing in the input can be embedded: Pumas 0.8.0 embeds texts and PNG or JPEG images, ' + f'and its {len(by_id):,} records hold none that can be sent.') + try: + listing = pumas.served(endpoint) + except pumas.PumasError as exc: + raise StepError(f'The Pumas endpoint at {endpoint} did not say what it serves: {exc}') from None + if report is not None: + with open(report, 'w', encoding='utf-8') as handle: + json.dump({'address': endpoint, 'version': pumas.version(endpoint)}, handle) + named = settings.get('model') + model = named if named is not None else facts.get('model') + profile = settings.get('profile') if named is not None else facts.get('profile') + dimensions = settings.get('dimensions') + try: + entry, named_by = pumas.choose_embedder(listing, model, profile) + routes = pumas.embedding_routes(entry) + pumas.check_dimensions(routes, dimensions) + except pumas.PumasError as exc: + raise StepError(f'Nothing was asked: {exc}') from None + if named_by == 'named': + named_by = 'definition' if named is not None else 'setting' + kinds = {kind for _, kind, _ in items} + if not kinds & set(routes): + raise StepError(f'Nothing was asked: {entry["model"]} ({entry["profile"]}) cannot embed ' + + ' or '.join(sorted(kinds)) + ' now; it embeds ' + (' and '.join(sorted(routes)) or 'nothing') + + '.') + for kind in sorted(kinds - set(routes)): + counts['no_route'] += sum(1 for item in items if item[1] == kind) + counts.setdefault('unrouted', []).append(kind) + items = [item for item in items if item[1] in routes] + prefix = settings['prefix'] if 'prefix' in settings else facts.get('prefix') + if prefix is None: + prefix = pumas.DEFAULT_PREFIX + name = settings.get('name') or facts['name'] + directory = os.path.join(output, embeddings.DIRECTORY) + os.makedirs(directory, exist_ok=True) + partial = _Partial(directory, name) + asked = {'source_run': facts['source'].get('run'), 'model': entry['model'], 'profile': entry['profile'], + 'model_id': entry['model_id'], 'prefix': prefix, 'dimensions': dimensions} + taken = {} + if facts.get('resume'): + earlier = _Partial(os.path.join(facts['resume'], embeddings.DIRECTORY), name) + try: + with open(earlier.meta, encoding='utf-8') as handle: + width = json.load(handle).get('width') + except (OSError, ValueError, AttributeError): + width = None + if width: + taken = earlier.read({**asked, 'width': width}) + asked['width'] = width + wanted = {identifier for identifier, _, _ in items} + taken = {identifier: row for identifier, row in taken.items() if identifier in wanted} + width = asked.get('width') if taken else None + rows_file = open(partial.rows, 'xb') + ids_file = open(partial.ids, 'x', encoding='utf-8') + written = 0 + + def keep(identifiers, rows): + nonlocal written + rows_file.write(b''.join(rows)) + rows_file.flush() + ids_file.write(''.join(identifier + '\n' for identifier in identifiers)) + ids_file.flush() + written += len(identifiers) + + def meta(found_width): + with open(partial.meta, 'w', encoding='utf-8') as handle: + json.dump({**asked, 'width': found_width}, handle) + + try: + if taken: + meta(width) + order = [identifier for identifier, _, _ in items if identifier in taken] + keep(order, [taken[identifier] for identifier in order]) + counts['resumed'] = len(order) + out(f'{len(order)} rows were taken from the failed run before, asked with the same model, prefix and ' + 'dimensions; the rest are asked for.') + remaining = [item for item in items if item[0] not in taken] + progress = Progress('embed', len(items), out) + progress(counts['resumed'], {'embedded': counts['resumed'], 'resumed': counts['resumed']}) + out(f'Asking {entry["model"]} ({entry["profile"]}) for {len(remaining)} vectors' + + (f' of {dimensions} dimensions' if dimensions else '') + '.') + token = uuid.uuid4().hex[:16] + size = settings.get('batch', EMBED_BATCH) + number = 0 + for kind in ('text', 'image'): + route = routes.get(kind) + mine = [item for item in remaining if item[1] == kind] + if route is None or not mine: + continue + most = pumas.batch_size(kind, route[2], size) + at = 0 + while at < len(mine): + chunk = mine[at:at + most] + if kind == 'image': # at most the release's bytes in one request + while len(chunk) > 1 and sum(len(data) for _, _, data in chunk) * 4 // 3 > pumas.IMAGE_REQUEST_BYTES: + chunk = chunk[:-1] + at += len(chunk) + number += 1 + try: + sent = ([prefix + text for _, _, text in chunk] if kind == 'text' + else [pumas.image_part(data) for _, _, data in chunk]) + except pumas.PumasError as exc: + raise StepError(f'The record {chunk[0][0]} cannot be sent: {exc}') from None + vectors = _ask_vectors(pumas, endpoint, listing, entry, route, sent, dimensions, number, token, + pauses, out, chunk[0][0]) + if width is None: + width = len(vectors[0]) + meta(width) + elif len(vectors[0]) != width: + raise StepError(f'The endpoint answered vectors of {len(vectors[0])} dimensions for the record ' + f'{chunk[0][0]}; earlier ones had {width}.') + keep([identifier for identifier, _, _ in chunk], [_float_bytes(vector) for vector in vectors]) + counts['embedded'] += len(chunk) + progress(counts['embedded'] + counts['resumed'], + {'embedded': counts['embedded'] + counts['resumed'], 'resumed': counts['resumed']}) + finally: + rows_file.close() + ids_file.close() + total = counts['embedded'] + counts['resumed'] + progress(total, {'embedded': total, 'resumed': counts['resumed']}, final=True) + with open(partial.ids, encoding='utf-8') as handle: + ids = [line.rstrip('\n') for line in handle] + notes = [] + if counts['other_kinds']: + notes.append(', '.join(f'{count} {kind}' for kind, count in sorted(counts['kinds'].items())) + + ' records were not embedded: Pumas 0.8.0 embeds texts and images.') + if counts['no_route']: + notes.append(f'{counts["no_route"]} records were not embedded: {entry["model"]} does not embed ' + + ' or '.join(counts['unrouted']) + '.') + if counts['unread']: + notes.append(f'{counts["unread"]} records could not be sent (a text over {EMBED_TEXT_BYTES} bytes, not ' + f'UTF-8 or empty; an image over {EMBED_IMAGE_BYTES} bytes, not PNG or JPEG, or missing).') + header = "{'descr': '<f4', 'fortran_order': False, 'shape': (%d, %d), }" % (len(ids), width) + padding = 64 - (10 + len(header) + 1) % 64 + text = (header + ' ' * padding + '\n').encode('latin-1') + with open(os.path.join(directory, f'{name}.npy'), 'xb') as target, open(partial.rows, 'rb') as source: + target.write(b'\x93NUMPY\x01\x00' + len(text).to_bytes(2, 'little') + text) + shutil.copyfileobj(source, target) + used = sorted({routes[kind][0] for _, kind, _ in items}) + index = {'format': embeddings.FORMAT, 'records': ids, 'dimensions': width, 'metric': 'cosine', + 'model': {'name': entry['model'], 'model_id': entry['model_id'], 'profile': entry['profile'], + 'capability': ', '.join(used), 'dimensions_asked': dimensions, 'named_by': named_by, + 'via': 'pumas'}, + 'prefix': prefix if prefix and any(kind == 'text' for _, kind, _ in items) else None, + 'source': {'dataset': facts['source'].get('dataset'), 'run': facts['source'].get('run')}, + 'notes': notes} + with open(os.path.join(directory, f'{name}.json'), 'x', encoding='utf-8') as handle: + json.dump(index, handle, ensure_ascii=False, separators=(',', ':')) + for path in (partial.rows, partial.ids, partial.meta): + os.unlink(path) + out(f'{total} records embedded by {entry["model"]} ({width} dimensions)' + + (f', {counts["resumed"]} of them taken from the failed run before' if counts['resumed'] else '') + '.') + for note in notes: + out(note) + return counts + + +def _ask_vectors(pumas, endpoint, listing, entry, route, sent, dimensions, number, token, pauses, out, first): + """One batch's vectors, asking again (after a pause) what the endpoint refused before the provider took it.""" + for attempt in range(len(pauses) + 1): + try: + return pumas.embed_batch(endpoint, listing, entry, route, sent, dimensions, + f'tuldok-embed:{token}:{number}:{attempt + 1}') + except pumas.PumasError as exc: + if exc.outcome != 'not_admitted' or attempt == len(pauses): + tries = f' (asked {attempt + 1} times)' if attempt else '' + raise StepError(f'Batch {number}, from the record {first}, failed{tries}: {exc}') from None + out(f'Batch {number} was not admitted ({exc.provider_code or "refused"}); asking again in ' + f'{pauses[attempt]:g} s.') + time.sleep(pauses[attempt]) + + # --------------------------------------------------------------- command line def _arguments(argv): @@ -761,6 +1127,7 @@ def _arguments(argv): parser.add_argument('--tasks', help='freeze: a JSON file of the tasks and their line files') parser.add_argument('--endpoint', help='generate: the Pumas endpoint this machine uses') parser.add_argument('--report', help='generate: a file to write the endpoint\'s address and version to') + parser.add_argument('--facts', help='embed: a JSON file of the source, the machine\'s embedder and what to resume') return parser.parse_args(argv) @@ -774,6 +1141,17 @@ def main(argv=None): raise StepError(f'The output directory {arguments.output} does not exist.') if arguments.step == 'import': import_files(settings, arguments.output, code_root=arguments.code, out=out) + elif arguments.step == 'embed': + if arguments.endpoint is None or arguments.records is None or arguments.facts is None: + raise StepError('embed needs --endpoint, --records and --facts.') + with open(arguments.facts, encoding='utf-8') as handle: + facts = json.load(handle) + embed_records(settings, arguments.output, endpoint=arguments.endpoint, records=arguments.records, + facts=facts, report=arguments.report, out=out) + elif arguments.step == 'select': + if arguments.records is None: + raise StepError('select needs --records.') + select_records(settings, arguments.output, records=arguments.records, out=out) elif arguments.step == 'generate': if arguments.endpoint is None: raise StepError('generate needs --endpoint, the Pumas endpoint this machine uses.') From 2af5eb7f6c8a3db7bd70a2f7673ce6df1fb63f1f Mon Sep 17 00:00:00 2001 From: MrScripty <TheEnvironmentGuy@protonmail.com> Date: Thu, 19 Nov 2026 06:42:55 -0700 Subject: [PATCH 105/131] docs(plan): spec-t4, generated annotation, more kinds and quality control Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --- docs/plans/training-and-curation/spec-t4.md | 179 ++++++++++++++++++++ 1 file changed, 179 insertions(+) create mode 100644 docs/plans/training-and-curation/spec-t4.md diff --git a/docs/plans/training-and-curation/spec-t4.md b/docs/plans/training-and-curation/spec-t4.md new file mode 100644 index 00000000..6542390e --- /dev/null +++ b/docs/plans/training-and-curation/spec-t4.md @@ -0,0 +1,179 @@ +# Implementation spec: generated annotation, more kinds, and quality control + +This is phase 4 of [the training and curation plan](plan.md). It follows that plan's rule: Tuldok supplies a file contract, a reader and a view; a project's own script (or a model behind the Pumas endpoint) makes the annotations. It builds on [spec-d4.md](../definition-first-projects/spec-d4.md) (tasks, the line file, the working copy, the steps, the Annotate tab) and [spec-d5.md](../definition-first-projects/spec-d5.md) (the Pumas endpoint and suggestions); the viewers are spec-d1's (`inside.js`), and the page follows [spec-w4.md](../definition-first-projects/spec-w4.md). Section 1 of [spec-m1-m2.md](../definition-first-projects/spec-m1-m2.md) applies. + +**Owner, 2026-11-19:** "Tuldok also needs a strong set of annotation types, however i dont nessisarly want everything that Label Studio has beacuse Tuldok centers on generated annotations rather than human made ones. That means we can do things like automated/ai segmentors, polygons, depth mapping, image masks, ranking, time series, object tracking, point cloud objects (selecting points that belong to an object), some quality control tools like agreement betwene different models, etc." + +**After this phase** a task may be of nine more types. A project's annotator (its own script, or a model behind the Pumas endpoint) is built as a dataset with the step `annotate`; its product is an **annotation set** for one task. A task can have several sets side by side (one per annotator) and the **kept set**: the annotations in `annotations/<task>.jsonl` in Git, which people decide. Tuldok measures how far the sets agree, lists the records where they disagree most, draws each set over the record, and a person keeps one set's annotation, both, or neither; that decision is written by the existing working copy and Save. People review instead of drawing. + +**Words.** As spec-d4: record, annotation, task, term. An **annotator** is what made a set: a model, a script or a person. A **set** is the annotations of one annotator for one task. The word "label" is not used. + +## 1. The new types of task + +A task's `task` may now also be one of these. Coordinates on an image are pixels with the origin at the top left, x right, y down; a point may lie on the far edge (`x ≤ width`). + +| Task | An annotation's `value` | On records of kind | Vocabulary | +| --- | --- | --- | --- | +| `polygons` | a list of `{"term", "points": [[x, y], …]}`, 3 to 10,000 points each, inside the image | image | required | +| `mask` | an object: `{"file": <sidecar .png>}` or `{"rle": [[v, n], …]}`, and `"classes": {"<v>": term, …}` | image | required | +| `depth` | an object `{"file": <sidecar .npy>}` | image | none | +| `keypoints` | a list of `{"term", "points": [p, …]}`, one `p` per name of the task's `keypoints`, each `[x, y]`, `[x, y, v]` (v 0, 1 or 2 as COCO's visibility) or `null` | image | required | +| `ranking` | a list of different terms, best first, at least one | any but `file` | required: the candidates | +| `timeseries` | a list of `{"term", "start", "end"}`, `start` < `end`: seconds of a sound, or positions along the first axis of an array | audio, array | required | +| `track` | a list of `{"track", "term", "frames": [{"frame", "x", "y", "w", "h"}, …]}`, frames increasing; `track` an id of 1 to 64 characters, different in one annotation | array (frames on its first axis) | required | +| `points` | a list of `{"term", "indices": [i, …]}`, indices increasing, each below the cloud's point count; or an object `{"file": <sidecar .npy>, "classes": {"<id>": term}}` of one whole number per point (0: no object) | pointcloud | required | +| `box3d` | a list of `{"term", "center": [x, y, z], "size": [l, w, h], "yaw"}`, sizes above zero, `yaw` in radians about z | pointcloud | required | + +- **Fields of the task** for these types: `keypoints` (1 to 100 different names, required for and only for `keypoints`), `skeleton` (pairs of those names, optional), `units` (a string of 1 to 40 characters for `depth`, such as `m`, required for it), `mask` (`semantic` or `instance`, default `semantic`, only for `mask`). +- **Confidence.** Any item of a list value, and the object of a `mask`, `depth` or `points` file value, may carry `"confidence"`: a number from 0 to 1. A set's line may carry one too (section 3). +- **A mask.** `classes` maps a pixel value (1 to 65,535, written as its decimal text) to a term; 0 is nothing. In a `semantic` mask a pixel's value is its class; in an `instance` mask each value is one object and `classes` names its term. `rle` is the mask row by row from the top left as runs `[value, count]`, counts above zero, summing to width × height. A sidecar PNG is 8- or 16-bit greyscale, not interlaced, of the image's size. +- **A depth map** is a 2-D `.npy` of float32, float64 or uint16 of shape (height, width); 0 and values that are not finite mean no depth; its units are the task's. +- **A point-id file** is a 1-D `.npy` of whole numbers (8 to 64 bits), one per point of the cloud. +- **Checked against the record** where cheap: an image's size (polygons, keypoints, masks, depth maps), a cloud's point count (points), an array's shape (track: frames below its first axis's length, boxes inside its second and third; timeseries on an array: ends at most its first axis's length), a sound's length (timeseries, from WAV only, as segments). +- **Bounds:** 1,000 items in a list value (as spec-d4), 10,000 points in a polygon, 1,000,000 indices in a `points` value, 10,000 frames in a track, 4,000 runs of `rle` per image row on average and 16 Mpx for a mask or depth map, 256 classes. +- **Key order** of an item: `track`, `frame`, `term`, `x`, `y`, `w`, `h`, `start`, `end`, `text`, `points`, `indices`, `center`, `size`, `yaw`, `frames`, `confidence`; of an object value: `file`, `rle`, `classes`, `confidence`; `classes` by number. Inside `frames` the same order. + +`spans`, `segments`, `boxes`, `class`, `tags`, `text` and `review` are unchanged, but their list items may carry `confidence` too. + +## 2. Sidecars: payloads too large for a line + +A value that names a `file` names a **sidecar**: a file beside the annotations it belongs to. + +- **In the kept set** (Git): `annotations/<task>/<name>`, where `<name>` is the first 16 hexadecimal characters of the file's SHA-256 and `.png` or `.npy`. Content-addressed: the same mask kept twice is one file, a name never changes meaning, and a file is never rewritten. The directory holds such files only (no links, no subdirectories). +- **In a set made by an annotator:** `files/<path>` of its product, any relative path. +- `check`: a sidecar directory with no task of its name is an error; a line naming a sidecar that is not there is an error; a file of the directory no line names is a warning ("Save removes it"). +- **Kept from a set** (section 6), a sidecar is copied into the working copy (the database), and written to `annotations/<task>/` by Save, with the line that names it; Save also removes the files of that task's directory that no saved line names. A sidecar is at most 64 MiB. + +## 3. The annotation set: what an annotator writes + +The product of a dataset whose `run.step` is `annotate`: + +``` +annotator.json {"format": "tuldok_annotator_v1", "task": "annotations/<task>", "by": {...}, "records": n, "made": m, "at": "…Z"} +annotations.jsonl one line per record annotated, sorted by record +files/ the sidecars its lines name +``` + +A line is `{"record", "sha256", "value", "confidence"?, "note"?}`: the record's id, its hash as the input's `records.jsonl` gives it (or null), a value as section 1 and spec-d4 say for the task (never null), an optional confidence for the whole annotation, and an optional note of at most 4,000 characters. + +**Provenance.** `by` is `{"kind": "model" | "script" | "person", "name", "version"?, "settings"?}`: names of 1 to 200 characters, `version` up to 200, `settings` an object of at most 8 KiB. It holds for every line of the set. A line kept from a set into Git carries it in `from` (section 6), so the kept annotation still says what made it. + +## 4. The step `annotate` + +A dataset whose `run` has `step: "annotate"`, `inputs: {"records": <the task's dataset>}`, `annotations: [<one task>]`, and settings: + +| | | +| --- | --- | +| `by` | required: `kind`, `name`, `version` as section 3 (Tuldok adds `settings`: the run's settings without `by`) | +| `pumas` | `{"model", "profile"?, "instruction"?}`: ask a model the endpoint serves. Excludes `run.command` | +| `limit` | at most this many records, 1 to 1,000,000 (default all) | +| `options` | any JSON object of at most 8 KiB, passed to the command (in `TULDOK_ANNOTATE_OPTIONS`) and recorded in `by.settings` | + +Exactly one of `run.command` and `settings.pumas`. Unlike `import`, `freeze` and `generate`, an `annotate` with a command also takes `run.environment` (and `env`), since the command is the project's: **the project's code runs in its environment, not in Tuldok.** + +**With a command.** Tuldok's step process (as for every step) reads the input's records, writes the records still to do to `<run>/todo.jsonl` (lines of the input's `records.jsonl`, the files' paths made absolute), then runs the command, from the code snapshot, with the environment's interpreter, with: + +| Variable | | +| --- | --- | +| `TULDOK_RECORDS` | the input product's directory | +| `TULDOK_TODO` | the records to annotate | +| `TULDOK_TASK` | the task's definition, as a file | +| `TULDOK_ANNOTATIONS` | the file to append lines to: `<output>/annotations.jsonl` | +| `TULDOK_FILES` | the directory for sidecars: `<output>/files` | +| `TULDOK_ANNOTATE_OPTIONS` | `settings.options` as JSON, or `{}` | + +The command appends one line per record, in any order, and may print `tuldok_progress_v1` lines (they pass through). When it ends with status 0, the step reads what it wrote, keeps the last line of each record of the input with a valid value, counts and drops the rest (an unknown record, an invalid value, a sidecar that is missing or outside `files/`), writes the lines sorted, and `annotator.json`. A command that fails fails the step. + +**With the Pumas endpoint.** Only what a served model can produce, from what spec-d5 already asks: + +| Task | Record | Asked as | +| --- | --- | --- | +| `text`, `class`, `tags` | text, image, audio | as `suggest_annotation` (spec-d5 section 4, as built) | +| `boxes`, `polygons` | image | `image_to_text` with an instruction asking for a JSON list of `{"term", "x", "y", "w", "h"}` (or `points`) in pixels of the image of the size given, terms from the vocabulary; an answer that is not such a list is a refusal for that record | + +A record the model's answer does not fit is counted as refused and skipped; the step fails only when the endpoint cannot be reached or refuses every record of the first ten. `by` gets `kind: model`, the model, profile and capability. + +**Bounded, resumable, with progress.** Progress is records done of records to do. Lines are appended as they are made. A run of the same definition that failed or was cancelled leaves its lines: the next build starts from them (`--resume`), copying the valid lines (and their sidecars) of records whose hash is unchanged, and annotates only the others. A run never reads or writes outside its output and run directory. + +**`by.settings`** is the run's `settings` without `by`, so a set's provenance is what its definition says; the definition, in Git, is what made it. + +## 5. Quality control: agreement between sets + +The **sets of a task** are its kept set (`kept`: the working copy's annotations with a value, in any state but rejected) and the current product of every dataset that annotates it (`annotate` with `annotations` naming it), each named by that dataset's reference. + +**Pairs.** For two sets, a record is compared when either has an annotation for it. One without an annotation (or with one emptied by the confidence filter, below) scores 0 on that record and is listed as missing. Each record gets an **agreement** from 0 to 1; a pair's agreement is the mean over its records. With more than two sets, a record's agreement is the mean over the pairs that compare it, and its **disagreement** is 1 minus that. The **most disputed** records are those of greatest disagreement, ties broken by record id. + +**Per type** (what one record scores for one pair, and what the pair also reports): + +| Task | A record's agreement | The pair also reports | +| --- | --- | --- | +| `class` | 1 when the terms are equal, else 0 | Cohen's kappa over the records both annotated; with three or more sets, Fleiss' kappa over the records every set annotated | +| `tags` | Jaccard of the two term sets (1 when both are empty) | | +| `text` | `difflib.SequenceMatcher` ratio of the first 4,000 characters | exact matches | +| `ranking` | (τ + 1) / 2, Kendall's τ over the candidates both rank (1 when fewer than two are shared and those agree) | mean τ | +| `boxes`, `polygons`, `box3d`, `points` (both forms), `mask` (`instance`) | matched IoU: objects of the same term matched one to one maximising the summed IoU; the sum of the matched IoUs over the larger of the two counts (1 when both are empty) | mean IoU of matches, matches, F1 at IoU 0.5 | +| `mask` (`semantic`) | mean over the terms either uses of their pixel IoU | | +| `keypoints` | as matched IoU with OKS in place of IoU | mean OKS of matches | +| `depth` | 1 − min(1, mean ‖a − b‖ / mean (‖a‖ + ‖b‖) / 2) over pixels with depth in both | mean absolute difference in the task's units, δ < 1.25 | +| `spans`, `segments`, `timeseries` | mean over the terms either uses of the interval IoU (length of the intersection of the unions over that of the union) | | +| `track` | tracks of the same term matched as above by their track IoU (the mean box IoU over the frames either has, a frame one lacks scoring 0) | identity switches, fragments | +| `review` | not compared | | + +- **IoU.** Boxes: exact. Polygons: both drawn on a grid over their joint bounding box at most 128 × 128 cells, pixel centres, even-odd rule (so IoU is exact to the grid). Masks: by pixel, decoded. Point sets: of the index sets (a point-id file becomes one object per id). 3-D boxes: the area of the intersection of the two rotated rectangles seen from above (convex clipping) times the overlap of their heights, over the union of volumes. +- **Matching.** The Hungarian method (minimising 1 − IoU) when both sides have at most 64 objects of a term; otherwise greedy, the pair of greatest IoU first. Pairs with IoU 0 are not matches. +- **OKS** of two instances: the mean over the keypoints both have (visibility above 0 where given) of exp(−d² / (2 s² κ²)), s² the mean of the areas of the two instances' bounding boxes of their points (at least 1 px²), κ = 0.1 (the task may say `sigma`). A keypoint one has and the other lacks scores 0. +- **Tracks.** An identity switch: for a track of the first set, its box in each frame is matched to the box of greatest IoU (above 0.5) of the second set; a change of the matched track from one matched frame to the next counts one. A fragment: a gap in a track's frames (its frames are not consecutive). Both are counted per set and per pair. +- **Kappa.** Cohen's: (p_o − p_e) / (1 − p_e) with p_e from each side's term frequencies; 1 when p_e is 1. Fleiss': with n sets per record, P̄ from the agreeing pairs per record and P̄_e from the overall term shares; 1 when P̄_e is 1. +- **Confidence filter** (`min_confidence`): items below it are dropped from list values; a line (or a mask, depth or point-id object) below it is treated as no annotation. A value with no confidence passes. +- **Bounds.** At most 8 sets; the agreement reads at most 20,000 records per set and stops there, saying so; masks and depth maps over 16 Mpx are not compared (listed with the reason). + +## 6. Operations + +All in the `project_folder` profile, absent from `catalog` (its digest unchanged). + +| Operation | Who | Arguments | Result | +| --- | --- | --- | --- | +| `annotation_sets` | inspect | `task` | `task`, `type`, `sets`: each `set` (`kept` or a dataset reference), `title`, `by`, `run`, `annotated`, `skipped` (lines not valid), `problem` (a set that cannot be read, with why) | +| `annotation_agreement` | inspect | `task`; `sets` (2 to 8; default every set that can be read); `min_confidence`; `offset`, `limit` (of the disputed list, at most 200) | `task`, `type`, `sets`, `measure` (what the score is, in words), `pairs` (`a`, `b`, `records`, `agreement`, and the type's figures), `fleiss`, `records` (compared), `disputed` (`record`, `disagreement`, `pairs` {`a|b`: agreement}, `missing`), `total`, `offset`, `limit`, `truncated` | +| `annotation_compare` | inspect | `task`, `record`, `sets` (1 to 8), `min_confidence` | `task`, `type`, `record`, `sets`: each `set`, `value` (null when none), `confidence`, `drawn` (masks as `{width, height, rle}` by term, depth as `{width, height, low, high, values_u8}` downsampled to at most 256 px a side, point-id files as `points` lists), `problem`; `pairs` (this record's agreement per pair and the type's figures); `frames` (for `track`: the array's frames as 8-bit grey, at most 64 frames of at most 128 px a side) or `series` (for `timeseries` on an array: at most 1,024 positions of at most 8 channels) | +| `keep_annotation` | edit, changes | `task`, `record`, `keep` (`one`, `both` or `none`), `sets` (one set for `one`, two for `both`, any for `none`), `note` | `task`, `record`, `state`, `unsaved` | + +`keep_annotation` writes the kept set through the same path as `set_annotation` (checked against the task and the record, unsaved until Save, one activity row): `one` keeps that set's value as `accepted` with `from` `{"set", "run", "by"}` (`by` without `settings` when it would pass 2 KiB); `both` keeps the union of two list values (refused `invalid` for a type whose value is not a list) with `from` naming both; `none` keeps `rejected` with a null value and `from` naming the sets rejected. A kept value's sidecars are copied (section 2). `kept` cannot be named for `one` or `both` (it is already kept). + +## 7. The page + +**The Annotate tab gains a second mode, Review**, chosen in the bar when the task has at least one set made by an annotator. Annotate mode stays as spec-d4 built it; for the new types its form shows the kept value drawn over the record and the decision, with no drawing tools. + +Review mode, in the tab's three columns: + +- **Left: the agreement and the most disputed records.** Two set choosers (A and B; any two of the task's sets), the confidence filter, the measure in words, A–B's agreement and the type's figures (with Fleiss' kappa when there are three or more sets), then the disputed records in order, each with its disagreement as a number and a bar; selecting one shows it. +- **Middle: the record with the sets drawn over it.** Side by side (A left, B right) or overlaid (A and B in two colours, what only one has marked), switched by a toggle. On an image: boxes, polygons, keypoints (with the skeleton), masks (as colour by term or instance, half transparent), depth (as a colour map, with its scale). On a point cloud: each point object's points coloured by its term, the 3-D boxes as wireframes. On a sound or an array of one or two axes: timeseries, segments as bands under the waveform or the series. On an array of frames: the frame with each track's box and id, a frame slider and the arrow keys. Text: spans marked. +- **Right: the decision.** Each set's value in words (count of objects, terms, confidences), this record's agreement, **Keep A**, **Keep B**, **Keep both** (for list values), **Reject both**, a note; then **Save** (the strip's). A record already kept shows what was kept and from which set. +- **Light correction**, only on the kept value and only where cheap: a kept polygon's vertex can be dragged or deleted (select it, then Delete); a kept point object's points can be removed by dragging a rectangle on the cloud's view while "Remove points" is on. Each correction is kept with `set_annotation`, as an unsaved edit. + +Updating in place (spec-w4): the disputed list, the record and the decision are drawn in parts, each put in place only when what it shows differs; a reading that changed nothing redraws nothing; the choice of sets, the filter, the mode and the frame are the page's and survive readings. + +## 8. Slices + +| | Slice | Mainly | +| --- | --- | --- | +| T4a | The nine types, their fields, values and checks against the record; sidecars in the folder, `check` | `annotations.py`, `schemas/annotation.schema.json`, `annotation_records.py` (`facts`), `folder.py`, `store.py` (listing), `check.py` | +| T4b | The set format and its reader; the step `annotate` with a command and with Pumas; resume | new `annotation_sets.py`, `steps.py`, `builds.py`, `check.py`, `schemas/` (run) | +| T4c | Agreement: the measures, matching, the disputed list | new `annotation_agreement.py` | +| T4d | The four operations; the sidecar copy and Save | `operations.py`, `service.py`, `annotation_rows.py`, `store.py` | +| T4e | Review mode and the overlays, light correction | new `static/project-workspace/review.js`, `annotate.js`, `inside.js` (exports), `base.css`, `app.py`, `project-workspace.html` | +| T4f | The example's small data and stand-in annotators; the browser check | `examples/tiny-project`, `tests/` | + +`docs/contracts/project-folder.md` is brought up to date for the types, sidecars, sets and the step. + +## 9. Tests + +- **T4a,** `tests/test_tuldok_project_annotation_kinds.py`: a valid value of each type checks and each rule of section 1 broken once gives its error; checks against an image's size, a cloud's count, an array's shape and a sound's length; a sidecar PNG and `.npy` read and refused when of another size or type; RLE that does not sum; a line file of each type written and read back byte for byte, key order included; a sidecar directory without its task, a missing sidecar and an unreferenced one in `check`. +- **T4b,** `tests/test_tuldok_project_annotate_step.py`: two stand-in segmentors (scripts in the test, run in a test environment) annotate four small images and two small clouds of a dataset built by `import`; each set has the lines, sidecars and `annotator.json` expected; a line with a bad value or unknown record is dropped and counted; a failed run is resumed and annotates only the rest; the Pumas route against the fake endpoint for `class` and for `boxes`, an answer that is not a list refused; nothing contacts a real Pumas. +- **T4c,** `tests/test_tuldok_project_annotation_agreement.py`: every measure of section 5 against the test's own arithmetic on hand-made values: kappa and Fleiss on a known table, Kendall's τ, interval IoU, box, polygon (a square in a square), mask (instance and semantic), point-set and 3-D box IoU (a rotated pair), OKS, track switches and fragments, the Hungarian matching against brute force, the confidence filter, the disputed order. +- **T4d,** in the same file and `test_tuldok_project_service.py`: the four operations on the stand-ins' sets; `keep_annotation` one, both and none, Save writing the line and the sidecar, a second Save removing an unreferenced sidecar; refusals. +- **T4e and T4f,** `tests/browser_project_workspace_annotation_kinds.cjs`: on a project whose stand-ins have run, overlays drawn for each type of the fixture (masks, polygons, depth, keypoints, point objects, 3-D boxes, timeseries, tracks across frames), two sets compared side by side and overlaid, the agreement shown, the disputed list in the computed order, one record reviewed and kept (Save writes `annotations/`), a polygon vertex moved, nothing rebuilt by a reading that changed nothing; light and dark at 1440 and 390 px, nothing overflowing sideways, no script error. + +## 10. Out of scope + +A drawing editor (drawing masks, polygons, keypoints or 3-D boxes by hand); video files as records (frames are an array); agreement for `review` tasks; exporting sets to COCO or other formats; per-term confusion matrices; a set made by a person outside the kept set (a second person's set is an annotator's product like any other); weighting annotators. From 1a6fb87284492938aad30ceae11793d58f5b6e2c Mon Sep 17 00:00:00 2001 From: MrScripty <TheEnvironmentGuy@protonmail.com> Date: Thu, 19 Nov 2026 06:49:24 -0700 Subject: [PATCH 106/131] feat(project): nine more annotation types and their sidecars polygons, mask, depth, keypoints, ranking, timeseries, track, points and box3d (spec-t4 section 1), with confidence on items, checked against an image's size, a cloud's point count, an array's shape and a sound's length. Masks and arrays too large for a line are sidecars in annotations/<task>/, named by their content; check reports missing and unreferenced ones. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --- docs/contracts/project-folder.md | 41 ++- tests/test_tuldok_project_annotation_kinds.py | 273 +++++++++++++++ tests/test_tuldok_project_annotations.py | 4 +- tuldok_project/annotation_payloads.py | 225 ++++++++++++ tuldok_project/annotation_records.py | 21 +- tuldok_project/annotation_rows.py | 8 +- tuldok_project/annotations.py | 330 ++++++++++++++++-- tuldok_project/check.py | 46 ++- tuldok_project/folder.py | 24 ++ tuldok_project/schemas/annotation.schema.json | 229 +++++++++++- tuldok_project/store.py | 6 +- 11 files changed, 1160 insertions(+), 47 deletions(-) create mode 100644 tests/test_tuldok_project_annotation_kinds.py create mode 100644 tuldok_project/annotation_payloads.py diff --git a/docs/contracts/project-folder.md b/docs/contracts/project-folder.md index 540c9f8d..8d06cb0d 100644 --- a/docs/contracts/project-folder.md +++ b/docs/contracts/project-folder.md @@ -49,6 +49,7 @@ environments/<name>.json charts/<name>.json annotations/<name>.json annotations/<name>.jsonl the annotations of task <name> +annotations/<name>/ their sidecars: masks and arrays too large for a line results/<benchmark name>.csv notes/... ``` @@ -662,8 +663,13 @@ plans its dataset in its place. | Field | Required | Rule | | --- | --- | --- | | `dataset` | yes | reference to `datasets/` | -| `task` | yes | `review`, `class`, `tags`, `text`, `boxes`, `spans` or `segments` | -| `vocabulary` | for `class`, `tags`, `boxes`, `spans` and `segments`; not allowed for `review` and `text` | 1 to 500 different **terms**, each 1 to 200 characters without control characters | +| `task` | yes | `review`, `class`, `tags`, `text`, `boxes`, `spans`, `segments`, `polygons`, `mask`, `depth`, `keypoints`, `ranking`, `timeseries`, `track`, `points` or `box3d` | +| `vocabulary` | for every task but `review`, `text` and `depth`, which allow none | 1 to 500 different **terms**, each 1 to 200 characters without control characters; for `ranking`, the candidates ranked | +| `keypoints` | for `keypoints` only, required | 1 to 100 different names: the points of one instance, in the order its values list them | +| `skeleton` | for `keypoints` only | pairs of those names, joined when drawn | +| `sigma` | for `keypoints` only | a number above 0: the spread of the agreement measure (OKS); default 0.1 | +| `units` | for `depth` only, required | the units of the depth values, 1 to 40 characters, such as `m` | +| `mask` | for `mask` only | `semantic` (a pixel's value is its class) or `instance` (each value is one object); default `semantic` | `earlier_work` is not allowed here. `card` is where the guide for the people and agents who annotate is written. @@ -680,7 +686,18 @@ What an annotation's `value` is, by task, and which records it may describe: | `spans` | a list of `{"term", "start", "end"}`, whole numbers of characters (code points) of the text; 0 ≤ `start` < `end` ≤ the text's length | `text` | | `segments` | a list of `{"term", "start", "end"}` with an optional `"text"` (a string of at most 64 KiB), numbers of seconds; 0 ≤ `start` < `end` ≤ the sound's length | `audio` | -A list holds at most 1,000 items, and an item no other key. The value may be +| `polygons` | a list of `{"term", "points": [[x, y], …]}`: 3 to 10,000 points in pixels, inside the image | `image` | +| `mask` | `{"file": <sidecar .png>, "classes"}` or `{"rle": [[value, count], …], "classes"}`: `classes` maps a pixel value (`"1"` to `"65535"`) to a term, 0 is nothing; `rle` gives the pixels row by row from the top left and covers the image | `image` | +| `depth` | `{"file": <sidecar .npy>}`: a 2-D array (height, width) of float32, float64 or uint16 in the task's units; 0 and non-finite values are no depth | `image` | +| `keypoints` | a list of `{"term", "points"}`, one point per name of the task's `keypoints`: `[x, y]`, `[x, y, v]` (v 0, 1 or 2) or null | `image` | +| `ranking` | a list of different terms, best first | any but `file` | +| `timeseries` | a list of `{"term", "start", "end"}`, 0 ≤ `start` < `end`: seconds of a sound, or positions along the first axis of an array | `audio`, `array` | +| `track` | a list of `{"track", "term", "frames": [{"frame", "x", "y", "w", "h"}, …]}`: `track` an id of 1 to 64 characters, once per annotation; frames whole numbers increasing, below the array's first axis; boxes inside its frames | `array` | +| `points` | a list of `{"term", "indices": [i, …]}` (indices increasing, below the cloud's point count), or `{"file": <sidecar .npy>, "classes"}`, a 1-D array of one whole number per point (0: no object) | `pointcloud` | +| `box3d` | a list of `{"term", "center": [x, y, z], "size": [l, w, h], "yaw"}`, sizes above 0, `yaw` in radians about z | `pointcloud` | + +An item of a list value, and an object value, may also carry `"confidence"`, a +number from 0 to 1. A list holds at most 1,000 items, and an item no other key. The value may be null in any state but `accepted`. The record's kind, an image's size, a text's length and a sound's length are known only from the dataset's product, so the folder check cannot apply those rules; Tuldok applies them when an annotation @@ -723,8 +740,10 @@ changed annotation: - lines sorted by `record`, comparing the bytes of its UTF-8; - each line written compact (`,` and `:` with no spaces), with characters other than ASCII written as themselves rather than as `\u` escapes, the keys - in the order above and the keys of a `boxes`, `spans` or `segments` item in - the order of the table of tasks; + in the order above and the keys of an item in the order `track`, `frame`, + `term`, `x`, `y`, `w`, `h`, `start`, `end`, `text`, `points`, `indices`, + `center`, `size`, `yaw`, `frames`, `confidence` (an object value: `file`, + `rle`, `classes`, `confidence`; `classes` by number); - each line ending with `\n`, the last one included. A file with no line left is deleted when it is saved. The JSON rules above @@ -747,6 +766,18 @@ Example, `annotations/scene-quality.jsonl`: {"record":"scene-0003","sha256":null,"state":"draft","value":"noisy","by":"agent:helper","at":"2026-11-13T10:05:02Z"} ``` +#### Sidecars + +A `mask`, `depth` or `points` value naming a `file` names a **sidecar** in +`annotations/<name>/`, beside the task: a file named by the first 16 +hexadecimal characters of its SHA-256 and `.png` or `.npy` (so a name never +changes meaning and a file is never rewritten). The directory holds such +files only. A mask PNG is 8- or 16-bit greyscale, not interlaced, of the +image's size; an `.npy` is a C-order array of floats or whole numbers, never +pickled. The check reports a directory with no task, and a line naming a +sidecar that is not there, as errors, and a sidecar no line names as a +warning; Save removes those of a task it writes. Each is at most 64 MiB. + ## Results files `results/<name>.csv` is the summary of benchmark `benchmarks/<name>.json`, which diff --git a/tests/test_tuldok_project_annotation_kinds.py b/tests/test_tuldok_project_annotation_kinds.py new file mode 100644 index 00000000..2c8738e5 --- /dev/null +++ b/tests/test_tuldok_project_annotation_kinds.py @@ -0,0 +1,273 @@ +"""The nine task types of spec-t4.md section 1 and the sidecars of section 2 (slice T4a). + +A valid value of each type checks and each rule broken once gives its +error; the checks against an image's size, a cloud's point count, an +array's shape and a sound's length; sidecar PNGs and .npy arrays read, +written and refused; runs that do not cover the image; a line file of each +type written and read back byte for byte with its key order; and, in a +folder (a copy of tests/fixtures/tuldok_project/minimal), the task fields, +a sidecar directory without its task, a missing sidecar and one no line +names. No database is used. +""" +import json +from pathlib import Path +import shutil +import sys +import tempfile +import unittest + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) + +from tuldok_project import annotation_payloads as payloads, annotations # noqa: E402 +from tuldok_project.check import check_folder # noqa: E402 + +FIXTURE = Path(__file__).resolve().parents[1] / 'tests' / 'fixtures' / 'tuldok_project' / 'minimal' +AT = '2026-11-19T10:00:00Z' +TERMS = ['cell', 'car', 'a', 'b', 'c'] +FIELDS = {'keypoints': ['head', 'tail'], 'skeleton': [['head', 'tail']], 'units': 'm', 'mask': 'instance'} + +# One sound value per new type, with the record facts it is checked against. +VALUES = { + 'polygons': ([{'term': 'cell', 'points': [[1, 1], [10, 1], [10.5, 8], [1, 8]], 'confidence': 0.9}], + {'kind': 'image', 'size': (16, 12)}), + 'mask': ({'rle': [[0, 100], [1, 92]], 'classes': {'1': 'cell'}}, {'kind': 'image', 'size': (16, 12)}), + 'depth': ({'file': 'aaaaaaaaaaaaaaaa.npy', 'confidence': 0.5}, {'kind': 'image', 'size': (16, 12)}), + 'keypoints': ([{'term': 'car', 'points': [[2, 3, 2], None]}], {'kind': 'image', 'size': (16, 12)}), + 'ranking': (['b', 'a', 'c'], {'kind': 'text'}), + 'timeseries': ([{'term': 'a', 'start': 0, 'end': 4.5}], {'kind': 'array', 'shape': [10, 2]}), + 'track': ([{'track': 'car-1', 'term': 'car', 'frames': [{'frame': 0, 'x': 0, 'y': 0, 'w': 4, 'h': 4}, + {'frame': 3, 'x': 2, 'y': 1, 'w': 4, 'h': 4}]}], + {'kind': 'array', 'shape': [4, 8, 8]}), + 'points': ([{'term': 'car', 'indices': [0, 4, 9]}], {'kind': 'pointcloud', 'points': 10}), + 'box3d': ([{'term': 'car', 'center': [0, 0, 1], 'size': [4, 2, 1.5], 'yaw': 0.3}], {'kind': 'pointcloud'}), +} + + +def problems(task, value, facts=None, fields=FIELDS, state='accepted'): + errors, unknown = annotations.value_problems(task, TERMS, state, value, fields=fields, **(facts or {})) + return errors + [f'unknown {term}' for term in unknown] + + +class Values(unittest.TestCase): + def test_a_sound_value_of_each_type_checks(self): + for task, (value, facts) in VALUES.items(): + with self.subTest(task): + self.assertIn(task, annotations.TASKS) + self.assertEqual(problems(task, value, facts), []) + self.assertEqual(annotations.record_kinds(task)[:1] != (), True) + self.assertIn(facts['kind'], annotations.record_kinds(task)) + + def test_each_rule_broken_once(self): + size = {'size': (16, 12)} + cases = [ + ('polygons', [{'term': 'cell', 'points': [[1, 1], [2, 2]]}], size, '3 to'), + ('polygons', [{'term': 'cell', 'points': [[1, 1], [2, 2], [17, 2]]}], size, 'outside the image'), + ('polygons', [{'term': 'cell', 'points': [[1, 1], [2, 2], [3, 2]], 'confidence': 2}], size, 'confidence'), + ('polygons', [{'term': 'nope', 'points': [[1, 1], [2, 2], [3, 2]]}], size, 'unknown nope'), + ('polygons', [{'term': 'cell', 'pts': []}], size, 'unknown key'), + ('mask', {'classes': {'1': 'cell'}}, size, 'either file or rle'), + ('mask', {'rle': [[0, 0]], 'classes': {'1': 'cell'}}, size, 'count above zero'), + ('mask', {'rle': [[0, 1]], 'classes': {'0': 'cell'}}, size, 'numbers 1 to 65535'), + ('mask', {'file': '../x.png', 'classes': {'1': 'cell'}}, size, 'relative path'), + ('mask', {'file': 'x.npy', 'classes': {'1': 'cell'}}, size, 'not a .png'), + ('depth', {'file': 'x.png'}, size, 'not a .npy'), + ('depth', [], size, 'must be an object'), + ('keypoints', [{'term': 'car', 'points': [[1, 1]]}], size, 'one point per keypoint of the task (2)'), + ('keypoints', [{'term': 'car', 'points': [[1, 1, 3], None]}], size, 'visibility'), + ('keypoints', [{'term': 'car', 'points': [[1, 20], None]}], size, 'outside the image'), + ('ranking', ['a', 'a'], {}, 'more than once'), + ('ranking', [], {}, 'one or more terms'), + ('timeseries', [{'term': 'a', 'start': 3, 'end': 3}], {}, 'start < end'), + ('timeseries', [{'term': 'a', 'start': 0, 'end': 11}], {'shape': [10]}, 'past the 10 positions'), + ('timeseries', [{'term': 'a', 'start': 0, 'end': 2}], {'duration': 1.5}, 'past the sound'), + ('track', [{'track': 'x', 'term': 'car', 'frames': [{'frame': 1, 'x': 0, 'y': 0, 'w': 1, 'h': 1}, + {'frame': 1, 'x': 0, 'y': 0, 'w': 1, 'h': 1}]}], + {}, 'above the one before'), + ('track', [{'track': 'x', 'term': 'car', 'frames': [{'frame': 5, 'x': 0, 'y': 0, 'w': 1, 'h': 1}]}], + {'shape': [4, 8, 8]}, 'past the 4 frames'), + ('track', [{'track': 'x', 'term': 'car', 'frames': [{'frame': 0, 'x': 6, 'y': 0, 'w': 3, 'h': 1}]}], + {'shape': [4, 8, 8]}, 'outside the frame'), + ('track', [{'track': 'x', 'term': 'car', 'frames': [{'frame': 0, 'x': 0, 'y': 0, 'w': 1, 'h': 1}]}, + {'track': 'x', 'term': 'car', 'frames': [{'frame': 0, 'x': 0, 'y': 0, 'w': 1, 'h': 1}]}], + {}, 'repeats the track id'), + ('points', [{'term': 'car', 'indices': [3, 2]}], {}, 'from 0 upward'), + ('points', [{'term': 'car', 'indices': [1, 10]}], {'points': 10}, 'the cloud has 10 points'), + ('points', {'file': 'ids.npy'}, {}, 'lacks classes'), + ('box3d', [{'term': 'car', 'center': [0, 0, 0], 'size': [1, 0, 1], 'yaw': 0}], {}, 'above zero'), + ('box3d', [{'term': 'car', 'center': [0, 0], 'size': [1, 1, 1], 'yaw': 0}], {}, 'center [x, y, z]'), + ] + for task, value, facts, expected in cases: + with self.subTest(task=task, expected=expected): + found = problems(task, value, facts) + self.assertEqual(len(found), 1, found) + self.assertIn(expected, found[0]) + self.assertNotIn('label', found[0].lower()) + + def test_kinds_of_record(self): + self.assertEqual(problems('polygons', VALUES['polygons'][0], {'kind': 'text'}), + ['A polygons task does not annotate records of kind \'text\'; it takes image.']) + self.assertEqual(annotations.record_kinds('timeseries'), ('audio', 'array')) + self.assertEqual(annotations.record_kinds('ranking'), annotations.record_kinds('class')) + + def test_null_values_and_confidence_on_old_types(self): + self.assertEqual(problems('mask', None, state='draft'), []) + self.assertEqual(len(problems('mask', None)), 1) + self.assertEqual(problems('boxes', [{'term': 'cell', 'x': 0, 'y': 0, 'w': 1, 'h': 1, 'confidence': 1}]), []) + self.assertIn('confidence', problems('boxes', [{'term': 'cell', 'x': 0, 'y': 0, 'w': 1, 'h': 1, + 'confidence': -0.1}])[0]) + + def test_sidecars_named(self): + self.assertEqual(annotations.sidecars('mask', {'file': 'm.png', 'classes': {}}), ['m.png']) + self.assertEqual(annotations.sidecars('mask', {'rle': [], 'classes': {}}), []) + self.assertEqual(annotations.sidecars('points', [{'term': 'a', 'indices': [1]}]), []) + self.assertEqual(annotations.sidecars('polygons', VALUES['polygons'][0]), []) + + +class Lines(unittest.TestCase): + def test_each_type_round_trips_byte_for_byte_in_its_key_order(self): + for task, (value, _facts) in VALUES.items(): + with self.subTest(task): + shuffled = json.loads(json.dumps(value)) + if isinstance(shuffled, list) and shuffled and isinstance(shuffled[0], dict): + shuffled = [dict(reversed(list(item.items()))) for item in shuffled] + elif isinstance(shuffled, dict): + shuffled = dict(reversed(list(shuffled.items()))) + rows = [{'record': 'r2', 'sha256': None, 'state': 'accepted', 'value': shuffled, 'by': 'owner', + 'at': AT}, {'record': 'r1', 'sha256': None, 'state': 'draft', 'value': value, + 'by': 'agent:helper', 'at': AT}] + data = annotations.write(rows) + parsed = annotations.read(data, task, TERMS, FIELDS) + self.assertEqual([p.message for p in parsed.problems], []) + self.assertEqual(annotations.write([row for _, row in parsed.rows]), data) + self.assertEqual(parsed.rows[0][1]['value'], parsed.rows[1][1]['value']) + + def test_written_key_orders(self): + line = annotations.encode({'record': 'r', 'sha256': None, 'state': 'accepted', 'by': 'owner', 'at': AT, + 'value': [{'frames': [{'h': 1, 'w': 1, 'y': 0, 'x': 0, 'frame': 2}], + 'term': 'car', 'confidence': 0.5, 'track': 't'}]}) + self.assertIn('"value":[{"track":"t","term":"car","frames":[{"frame":2,"x":0,"y":0,"w":1,"h":1}],' + '"confidence":0.5}]', line) + line = annotations.encode({'record': 'r', 'sha256': None, 'state': 'accepted', 'by': 'owner', 'at': AT, + 'value': {'confidence': 1, 'classes': {'12': 'b', '3': 'a'}, 'file': 'f.png'}}) + self.assertIn('"value":{"file":"f.png","classes":{"3":"a","12":"b"},"confidence":1}', line) + + +class Payloads(unittest.TestCase): + def test_png_round_trip_8_and_16_bit(self): + for values in ([0, 1, 2, 255] * 6, [0, 300, 65535, 7] * 6): + data = payloads.write_png(4, 6, values) + self.assertEqual(payloads.png_size(data)[:2], (4, 6)) + width, height, read = payloads.read_png(data) + self.assertEqual((width, height, list(read)), (4, 6, values)) + + def test_png_with_row_filters(self): + import struct + import zlib + # Rows with each filter, worked out by hand: Sub, Up, Average and Paeth of a 3-pixel greyscale image. + rows = bytes([1, 10, 5, 5]) + bytes([2, 1, 1, 1]) + bytes([3, 2, 2, 2]) + bytes([4, 1, 0, 0]) + def chunk(kind, body): + return struct.pack('>I', len(body)) + kind + body + struct.pack('>I', zlib.crc32(kind + body)) + data = (b'\x89PNG\r\n\x1a\n' + chunk(b'IHDR', struct.pack('>IIBBBBB', 3, 4, 8, 0, 0, 0, 0)) + + chunk(b'IDAT', zlib.compress(rows)) + chunk(b'IEND', b'')) + _, _, values = payloads.read_png(data) + # Sub: 10, 15, 20. Up: 11, 16, 21. Average: 2 + (0 + 11) // 2 = 7, 2 + (7 + 16) // 2 = 13, + # 2 + (13 + 21) // 2 = 19. Paeth: 1 + up (7) = 8; then left 8 vs up 13, corner 7: p = 14 -> up 13; 13 vs 19, 13: 19. + self.assertEqual(list(values), [10, 15, 20, 11, 16, 21, 7, 13, 19, 8, 13, 19]) + + def test_png_refusals(self): + with self.assertRaises(payloads.PayloadError): + payloads.read_png(b'not a png at all, not at all, not at all') + rgb = payloads.write_png(2, 2, [0, 0, 0, 0]).replace(b'IHDR' + (2).to_bytes(4, 'big') * 2 + b'\x08\x00', + b'IHDR' + (2).to_bytes(4, 'big') * 2 + b'\x08\x02') + with self.assertRaises(payloads.PayloadError): + payloads.read_png(rgb) + + def test_runs(self): + values = [0, 0, 1, 1, 1, 0, 2] + runs = payloads.encode_runs(values) + self.assertEqual(runs, [[0, 2], [1, 3], [0, 1], [2, 1]]) + self.assertEqual(list(payloads.decode_runs(runs, 7, 1)), values) + with self.assertRaises(payloads.PayloadError): + payloads.decode_runs(runs, 4, 2) + + def test_npy(self): + data = payloads.write_npy([2, 3], [0.5, 1, 2, 3, 4, 5.25], '<f4') + shape, kind, values = payloads.read_npy(data) + self.assertEqual((shape, kind, list(values)), ([2, 3], 'f', [0.5, 1, 2, 3, 4, 5.25])) + data = payloads.write_npy([4], [0, 1, 1, 2], '<i4') + self.assertEqual(payloads.read_npy(data)[0], [4]) + with self.assertRaises(payloads.PayloadError): + payloads.read_npy(data, most=3) + with self.assertRaises(payloads.PayloadError): + payloads.read_npy(data.replace(b"'<i4'", b"'|O8'")) + with self.assertRaises(payloads.PayloadError): + payloads.read_npy(data[:-4]) + + def test_kept_names(self): + name = payloads.kept_name(b'abc', '.png') + self.assertTrue(payloads.is_kept_name(name)) + self.assertEqual(name, 'ba7816bf8f01cfea.png') + self.assertFalse(payloads.is_kept_name('ba7816bf8f01cfea.jpg')) + self.assertFalse(payloads.is_kept_name('mask.png')) + + +class Folder(unittest.TestCase): + def setUp(self): + directory = tempfile.TemporaryDirectory() + self.addCleanup(directory.cleanup) + base = Path(directory.name) / 'minimal' + shutil.copytree(FIXTURE, base) + self.folder = base / 'project' + + def task(self, name, **fields): + document = {'format': 'tuldok_definition_v1', 'kind': 'annotation', 'title': 'T', 'dataset': 'datasets/waves'} + document.update(fields) + (self.folder / f'annotations/{name}.json').write_text(json.dumps(document, indent=2) + '\n', encoding='utf-8') + + def problems(self): + return [(p.severity, p.path, p.pointer, p.message) for p in check_folder(self.folder).problems] + + def test_task_fields(self): + self.task('keys', task='keypoints', vocabulary=['car'], keypoints=['head', 'tail'], skeleton=[['head', 'tail']]) + self.task('depths', task='depth', units='m') + self.task('masks', task='mask', vocabulary=['cell'], mask='instance') + self.assertEqual(self.problems(), []) + self.task('keys', task='keypoints', vocabulary=['car'], keypoints=['head'], skeleton=[['head', 'wing']]) + found = self.problems() + self.assertEqual([(s, p, q) for s, p, q, _ in found], [('error', 'annotations/keys.json', '/skeleton/0')]) + self.task('keys', task='keypoints', vocabulary=['car']) + self.task('depths', task='depth', units='m', vocabulary=['x']) + self.task('masks', task='mask', vocabulary=['cell'], units='m') + found = sorted((p, q) for _s, p, q, _m in self.problems()) + self.assertEqual([p for p, _ in found], ['annotations/depths.json', 'annotations/keys.json', + 'annotations/masks.json']) + + def test_sidecars_in_the_folder(self): + mask = payloads.write_png(2, 2, [0, 1, 1, 0]) + name = payloads.kept_name(mask, '.png') + self.task('masks', task='mask', vocabulary=['cell']) + (self.folder / 'annotations/masks').mkdir() + (self.folder / 'annotations/masks' / name).write_bytes(mask) + row = {'record': 'r1', 'sha256': None, 'state': 'accepted', 'value': {'file': name, 'classes': {'1': 'cell'}}, + 'by': 'owner', 'at': AT} + (self.folder / 'annotations/masks.jsonl').write_bytes(annotations.write([row])) + self.assertEqual(self.problems(), []) + # A sidecar no line names is a warning; one a line names and that is not there, an error. + other = payloads.write_png(2, 2, [1, 1, 1, 1]) + (self.folder / 'annotations/masks' / payloads.kept_name(other, '.png')).write_bytes(other) + self.assertEqual([(s, p) for s, p, _q, _m in self.problems()], [('warning', 'annotations/masks')]) + (self.folder / 'annotations/masks' / name).unlink() + found = self.problems() + self.assertIn(('error', 'annotations/masks.jsonl', 'line 1'), [(s, p, q) for s, p, q, _m in found]) + # A file not named by its content, and a directory with no task. + (self.folder / 'annotations/masks' / 'mine.png').write_bytes(mask) + (self.folder / 'annotations/stray').mkdir() + found = [(s, p) for s, p, _q, _m in self.problems()] + self.assertIn(('error', 'annotations/masks/mine.png'), found) + self.assertIn(('error', 'annotations/stray'), found) + for _s, _p, _q, message in self.problems(): + self.assertTrue(message.endswith('.'), message) + + +if __name__ == '__main__': + unittest.main() diff --git a/tests/test_tuldok_project_annotations.py b/tests/test_tuldok_project_annotations.py index af7f07d4..18d08ba1 100644 --- a/tests/test_tuldok_project_annotations.py +++ b/tests/test_tuldok_project_annotations.py @@ -98,7 +98,7 @@ def test_each_rule_of_a_task(self): ('no dataset', {'dataset': None}, '/dataset'), ('dataset in another directory', {'dataset': 'recipes/stepper-k1'}, '/dataset'), ('dataset missing', {'dataset': 'datasets/nowhere'}, '/dataset'), - ('unknown task', {'task': 'polygons'}, '/task'), + ('unknown task', {'task': 'video'}, '/task'), ('class needs a vocabulary', {'vocabulary': None}, '/vocabulary'), ('review takes none', {'task': 'review'}, '/vocabulary'), ('text takes none', {'task': 'text'}, '/vocabulary'), @@ -132,7 +132,7 @@ def test_line_files_belong_to_annotations_only(self): self.assertOnly(('error', 'datasets/waves.jsonl', '')) def test_a_task_with_errors_leaves_its_lines_unchecked(self): - self.task(task='polygons') + self.task(task='video') self.lines('not json') self.assertEqual(self.problems(), [('error', 'annotations/wave-quality.json', '/task'), ('warning', 'annotations/wave-quality.jsonl', '')]) diff --git a/tuldok_project/annotation_payloads.py b/tuldok_project/annotation_payloads.py new file mode 100644 index 00000000..5e0f0f4c --- /dev/null +++ b/tuldok_project/annotation_payloads.py @@ -0,0 +1,225 @@ +"""The payloads of annotations too large for a line: masks (PNG or runs) and arrays (.npy), read and written. + +Owns the byte formats of section 1 and 2 of +docs/plans/training-and-curation/spec-t4.md: a sidecar PNG (8- or 16-bit +greyscale, not interlaced), a mask's runs ([value, count] row by row), and a +sidecar .npy (a 1-D or 2-D array of floats or whole numbers, C order). It is +pure and uses the standard library alone (the step process imports it): it +opens no file, never unpickles, and bounds what it decodes. Every reader +raises PayloadError with a sentence when the bytes are not what is wanted. +""" +from array import array +import ast +import hashlib +import struct +import sys +import zlib + +PIXEL_LIMIT = 16 * 1024 * 1024 # pixels of a mask or a depth map +NPY_HEADER_LIMIT = 64 * 1024 +SIDECAR_LIMIT = 64 * 1024 * 1024 # bytes of one sidecar +NAME_LENGTH = 16 # hexadecimal characters of a kept sidecar's name +_PNG = b'\x89PNG\r\n\x1a\n' +_NPY = b'\x93NUMPY' +_LITTLE = sys.byteorder == 'little' +_CODES = {('f', 4): 'f', ('f', 8): 'd', ('i', 1): 'b', ('i', 2): 'h', ('i', 4): 'i', ('i', 8): 'q', + ('u', 1): 'B', ('u', 2): 'H', ('u', 4): 'I', ('u', 8): 'Q'} + + +class PayloadError(ValueError): + """Bytes that are not the payload wanted; the message is a sentence.""" + + +def kept_name(data, extension): + """The name of a sidecar in annotations/<task>/: the first 16 hex of its SHA-256 and its extension.""" + return hashlib.sha256(data).hexdigest()[:NAME_LENGTH] + extension + + +def is_kept_name(name): + stem, _, extension = name.partition('.') + return (len(stem) == NAME_LENGTH and all(char in '0123456789abcdef' for char in stem) + and extension in ('png', 'npy')) + + +# ------------------------------------------------------------------- PNG + +def png_size(data): + """(width, height, bit depth, colour type, interlace) from a PNG's header; PayloadError when it is not one.""" + if len(data) < 33 or data[:8] != _PNG or data[12:16] != b'IHDR': + raise PayloadError('The file is not a PNG.') + width, height, depth, colour, _compression, _filter, interlace = struct.unpack('>IIBBBBB', data[16:29]) + return width, height, depth, colour, interlace + + +def read_png(data): + """(width, height, values) of an 8- or 16-bit greyscale PNG that is not interlaced; values row by row.""" + width, height, depth, colour, interlace = png_size(data) + if colour != 0 or depth not in (8, 16) or interlace != 0: + raise PayloadError('A mask PNG must be 8- or 16-bit greyscale and not interlaced.') + if width * height > PIXEL_LIMIT or not width or not height: + raise PayloadError(f'A mask of {width} by {height} pixels is empty or over {PIXEL_LIMIT:,} pixels.') + at, chunks = 8, [] + while at + 8 <= len(data): + length, kind = struct.unpack('>I4s', data[at:at + 8]) + if kind == b'IDAT': + chunks.append(data[at + 8:at + 8 + length]) + elif kind == b'IEND': + break + at += 12 + length + size = depth // 8 + stride = width * size + try: + decompressor = zlib.decompressobj() + raw = decompressor.decompress(b''.join(chunks), (stride + 1) * height + 1) + except zlib.error: + raise PayloadError('The PNG cannot be decompressed.') from None + if len(raw) < (stride + 1) * height: + raise PayloadError('The PNG holds fewer rows than its size says.') + out, previous = bytearray(), bytearray(stride) + for row in range(height): + start = row * (stride + 1) + kind, line = raw[start], bytearray(raw[start + 1:start + 1 + stride]) + for i in range(stride if kind else 0): + left = line[i - size] if i >= size else 0 + up = previous[i] + if kind == 1: + line[i] = (line[i] + left) & 255 + elif kind == 2: + line[i] = (line[i] + up) & 255 + elif kind == 3: + line[i] = (line[i] + ((left + up) >> 1)) & 255 + elif kind == 4: + corner = previous[i - size] if i >= size else 0 + guess = left + up - corner + a, b, c = abs(guess - left), abs(guess - up), abs(guess - corner) + line[i] = (line[i] + (left if a <= b and a <= c else up if b <= c else corner)) & 255 + else: + raise PayloadError(f'The PNG uses the unknown row filter {kind}.') + out += line + previous = line + if size == 1: + values = array('H') + values.extend(out) + return width, height, values + values = array('H', bytes(out)) + if _LITTLE: + values.byteswap() + return width, height, values + + +def write_png(width, height, values): + """An 8-bit (all values below 256) or 16-bit greyscale PNG of values row by row.""" + wide = any(value > 255 for value in values) + rows = bytearray() + for row in range(height): + rows.append(0) + chunk = values[row * width:(row + 1) * width] + rows += struct.pack(f'>{width}H', *chunk) if wide else bytes(chunk) + + def part(kind, body): + return struct.pack('>I', len(body)) + kind + body + struct.pack('>I', zlib.crc32(kind + body)) + return (_PNG + part(b'IHDR', struct.pack('>IIBBBBB', width, height, 16 if wide else 8, 0, 0, 0, 0)) + + part(b'IDAT', zlib.compress(bytes(rows), 9)) + part(b'IEND', b'')) + + +# ------------------------------------------------------------------ runs + +def runs_total(runs): + """The pixels runs cover; PayloadError when they are not [value, count] pairs of whole numbers.""" + total = 0 + for run in runs: + if (not isinstance(run, list) or len(run) != 2 or not all(type(item) is int for item in run) + or not 0 <= run[0] <= 65535 or run[1] < 1): + raise PayloadError('A run must be [value, count]: a value from 0 to 65,535 and a count above zero.') + total += run[1] + return total + + +def decode_runs(runs, width, height): + """The values of a mask given as runs, row by row.""" + if runs_total(runs) != width * height: + raise PayloadError(f'The runs cover {runs_total(runs):,} pixels; the image has {width * height:,}.') + out = array('H') + for value, count in runs: + out.extend([value]) if count == 1 else out.extend(array('H', [value]) * count) + return out + + +def encode_runs(values): + """values as runs [[value, count], ...].""" + runs, last, count = [], None, 0 + for value in values: + if value == last: + count += 1 + else: + if count: + runs.append([last, count]) + last, count = value, 1 + if count: + runs.append([last, count]) + return runs + + +# ------------------------------------------------------------------- NPY + +def npy_header(data): + """(shape, kind, itemsize, little, offset) of an NPY array in C order of floats or whole numbers.""" + if len(data) < 10 or data[:6] != _NPY: + raise PayloadError('The file is not an NPY array.') + major = data[6] + if major == 1: + start, end = 10, 10 + struct.unpack_from('<H', data, 8)[0] + elif major in (2, 3) and len(data) >= 12: + start, end = 12, 12 + struct.unpack_from('<I', data, 8)[0] + else: + raise PayloadError(f'NPY version {major} is not read.') + if end - start > NPY_HEADER_LIMIT or len(data) < end: + raise PayloadError('The NPY header is too long or cut short.') + try: + header = ast.literal_eval(data[start:end].decode('latin-1').strip()) + except (ValueError, SyntaxError, MemoryError, RecursionError): + raise PayloadError('The NPY header is not a literal Tuldok reads.') from None + if (not isinstance(header, dict) or set(header) != {'descr', 'fortran_order', 'shape'} + or not isinstance(header['shape'], tuple) or not all(type(n) is int and n >= 0 for n in header['shape'])): + raise PayloadError('The NPY header must hold descr, fortran_order and a shape of whole numbers.') + descr = header['descr'] + if not isinstance(descr, str) or len(descr) < 3 or descr[0] not in '<>|=' or not descr[2:].isdigit(): + raise PayloadError('The NPY array must be of floats or whole numbers.') + kind, itemsize = descr[1], int(descr[2:]) + if (kind, itemsize) not in _CODES: + raise PayloadError(f'The NPY type {descr} is not read; use float32, float64 or whole numbers.') + if header['fortran_order'] and len(header['shape']) > 1: + raise PayloadError('The NPY array must be in C order.') + little = _LITTLE if descr[0] in '=|' else descr[0] == '<' + return list(header['shape']), kind, itemsize, little, end + + +def read_npy(data, most=PIXEL_LIMIT): + """(shape, kind, values) of an NPY array of at most most values.""" + shape, kind, itemsize, little, offset = npy_header(data) + count = 1 + for n in shape: + count *= n + if count > most: + raise PayloadError(f'The array holds {count:,} values; at most {most:,} are read.') + raw = data[offset:offset + count * itemsize] + if len(raw) < count * itemsize: + raise PayloadError('The NPY array is shorter than its shape says.') + values = array(_CODES[(kind, itemsize)]) + values.frombytes(raw) + if itemsize > 1 and little != _LITTLE: + values.byteswap() + return shape, kind, values + + +def write_npy(shape, values, descr): + """The bytes of an NPY array (version 1) of values in C order; descr such as '<f4' or '<i4'.""" + header = "{'descr': '%s', 'fortran_order': False, 'shape': (%s), }" % ( + descr, ''.join(f'{n}, ' for n in shape) if len(shape) == 1 else ', '.join(str(n) for n in shape)) + pad = 64 - (10 + len(header) + 1) % 64 + text = (header + ' ' * pad + '\n').encode('latin-1') + kind, itemsize = descr[1], int(descr[2:]) + packed = array(_CODES[(kind, itemsize)], values) + if not _LITTLE: + packed.byteswap() + return _NPY + b'\x01\x00' + struct.pack('<H', len(text)) + text + packed.tobytes() diff --git a/tuldok_project/annotation_records.py b/tuldok_project/annotation_records.py index 9bac2002..6bdc5139 100644 --- a/tuldok_project/annotation_records.py +++ b/tuldok_project/annotation_records.py @@ -11,7 +11,8 @@ into rows, checked with annotations.validate against the task, the vocabulary, the record's kind and what is cheap to know of it: an image's size (from its first bytes), a text's length (when its file is at most -inside.COUNT_TEXT_BYTES) and a WAVE sound's length (from its header). +inside.COUNT_TEXT_BYTES), a WAVE sound's length (from its header), a point +cloud's count and an .npy array's shape (spec-t4.md section 1). content reads one record whole for a suggestion (spec-d5.md section 4). """ import codecs @@ -19,13 +20,14 @@ import os import struct -from . import annotation_rows, annotations, inside, inside_archive, inside_shapes +from . import annotation_rows, annotations, inside, inside_archive, inside_arrays, inside_shapes from .store import ProjectError HASH_LIMIT = 1 << 30 # bytes of a record hashed; a larger one is tied by its id alone ITEM_LIMIT = 200 # items of one set_annotation WAVE_HEAD = 64 * 1024 # read for a sound's length _CHUNK = 1 << 20 +SIZED = ('boxes', 'polygons', 'mask', 'depth', 'keypoints') # tasks checked against an image's size # ------------------------------------------------------------- the product @@ -166,9 +168,9 @@ def _wave_seconds(head, size): def facts(product, record, task): """{kind, size, length, duration} of a record, as far as task needs them and they are cheap to know.""" - found = {'kind': record['kind'], 'size': None, 'length': None, 'duration': None} + found = {'kind': record['kind'], 'size': None, 'length': None, 'duration': None, 'points': None, 'shape': None} try: - if task == 'boxes' and record['kind'] == 'image' and record['path'] is not None: + if task in SIZED and record['kind'] == 'image' and record['path'] is not None: content = inside_shapes.image_content(inside_archive.locate(product.root, record['path'])) if content['width'] is not None: found['size'] = (content['width'], content['height']) @@ -180,10 +182,15 @@ def facts(product, record, task): if (place.size or 0) <= inside.COUNT_TEXT_BYTES: raw = place.head(place.size or 0) found['length'] = len(codecs.decode(raw, 'utf-8', 'surrogateescape')) - elif (task == 'segments' and record['kind'] == 'audio' and record['path'] is not None + elif (task in ('segments', 'timeseries') and record['kind'] == 'audio' and record['path'] is not None and record['path'].lower().endswith('.wav')): place = inside_archive.locate(product.root, record['path']) found['duration'] = _wave_seconds(place.head(WAVE_HEAD), place.size or 0) + elif task in ('points', 'box3d') and record['kind'] == 'pointcloud' and record['path'] is not None: + found['points'] = inside_shapes.pointcloud_content(inside_archive.locate(product.root, record['path']))['count'] + elif (task in ('track', 'timeseries') and record['kind'] == 'array' and record['path'] is not None + and record['path'].lower().endswith('.npy')): + found['shape'] = inside_arrays.read_header(inside_archive.locate(product.root, record['path'])).shape except (ProjectError, *inside.DAMAGED): pass # not known: the bound is not checked return found @@ -253,7 +260,9 @@ def check_items(document, items, known, *, by, at, origin=None): if origin is not None: row['from'] = origin errors = annotations.validate(task, vocabulary, row, kind=info['kind'], size=info['size'], - length=info['length'], duration=info['duration']) + length=info['length'], duration=info['duration'], + fields=annotations.task_fields(document), points=info.get('points'), + shape=info.get('shape')) if not errors and annotation_rows.has_nul(row): errors.append('It holds the character U+0000, which Tuldok cannot keep.') if errors: diff --git a/tuldok_project/annotation_rows.py b/tuldok_project/annotation_rows.py index 229d1494..5e3c7ded 100644 --- a/tuldok_project/annotation_rows.py +++ b/tuldok_project/annotation_rows.py @@ -68,15 +68,17 @@ def fingerprint(document): """What of a task decides whether a value fits it: its task and vocabulary, as one digest.""" if not isinstance(document, dict): return None - shown = json.dumps([document.get('task'), document.get('vocabulary') or []], ensure_ascii=False, - separators=(',', ':')) + fields = annotations.task_fields(document) + shown = json.dumps([document.get('task'), document.get('vocabulary') or []] + ([fields] if fields else []), + ensure_ascii=False, separators=(',', ':'), sort_keys=True) return hashlib.sha256(shown.encode('utf-8', 'surrogatepass')).hexdigest() def fits(document, row): """Whether a row's value is one the task document allows (the record's kind is not judged here).""" errors, unknown = annotations.value_problems(document.get('task'), document.get('vocabulary') or [], - row.get('state'), row.get('value')) + row.get('state'), row.get('value'), + fields=annotations.task_fields(document)) return not errors and not unknown diff --git a/tuldok_project/annotations.py b/tuldok_project/annotations.py index 120fedef..6edd631f 100644 --- a/tuldok_project/annotations.py +++ b/tuldok_project/annotations.py @@ -15,8 +15,13 @@ import re import unicodedata -TASKS = ('review', 'class', 'tags', 'text', 'boxes', 'spans', 'segments') -VOCABULARY_TASKS = ('class', 'tags', 'boxes', 'spans', 'segments') +TASKS = ('review', 'class', 'tags', 'text', 'boxes', 'spans', 'segments', + # spec-t4.md section 1 + 'polygons', 'mask', 'depth', 'keypoints', 'ranking', 'timeseries', 'track', 'points', 'box3d') +VOCABULARY_TASKS = ('class', 'tags', 'boxes', 'spans', 'segments', 'polygons', 'mask', 'keypoints', 'ranking', + 'timeseries', 'track', 'points', 'box3d') +LIST_TASKS = ('boxes', 'spans', 'segments', 'polygons', 'keypoints', 'timeseries', 'track', 'box3d') +FILE_TASKS = ('mask', 'depth', 'points') # tasks whose value may name a sidecar (spec-t4.md section 2) STATES = ('draft', 'accepted', 'needs-work', 'rejected') RECORD_KINDS = ('text', 'image', 'audio', 'pointcloud', 'mesh', 'array', 'file') # spec-d1's kinds of record KEYS = ('record', 'sha256', 'state', 'value', 'note', 'by', 'at', 'from') @@ -28,13 +33,24 @@ NOTE_LIMIT = 4000 # characters BY_LIMIT = 80 # characters of an agent's label after 'agent:' FROM_LIMIT = 2048 # UTF-8 bytes of 'from', written compact -ITEM_LIMIT = 1000 # boxes, spans or segments in one annotation +ITEM_LIMIT = 1000 # items of a list value in one annotation +POLYGON_LIMIT = 10_000 # points of one polygon +INDEX_LIMIT = 1_000_000 # indices of a points value +FRAME_LIMIT = 10_000 # frames of one track +CLASS_LIMIT = 256 # classes of a mask or a point-id file +KEYPOINT_LIMIT = 100 # names of a keypoints task +TRACK_ID_LIMIT = 64 # characters of a track's id +UNITS_LIMIT = 40 # characters of a depth task's units +MASK_MODES = ('semantic', 'instance') PROBLEM_LIMIT = 20 # line problems reported per file before a count # The one kind of record a task needs; the other tasks take any kind but 'file'. -_ONLY_KIND = {'boxes': 'image', 'spans': 'text', 'segments': 'audio'} -# Key order of the objects inside a boxes, spans or segments value. -_ITEM_ORDER = ('term', 'x', 'y', 'w', 'h', 'start', 'end', 'text') +_ONLY_KIND = {'boxes': ('image',), 'spans': ('text',), 'segments': ('audio',), 'polygons': ('image',), + 'mask': ('image',), 'depth': ('image',), 'keypoints': ('image',), 'timeseries': ('audio', 'array'), + 'track': ('array',), 'points': ('pointcloud',), 'box3d': ('pointcloud',)} +# Key order of the objects inside a list value, and of an object value (spec-t4.md section 1). +_ITEM_ORDER = ('track', 'frame', 'term', 'x', 'y', 'w', 'h', 'start', 'end', 'text', 'points', 'indices', 'center', + 'size', 'yaw', 'frames', 'file', 'rle', 'classes', 'confidence') _ITEM_RANK = {key: index for index, key in enumerate(_ITEM_ORDER)} _ITEM_KEYS = {'boxes': ('term', 'x', 'y', 'w', 'h'), 'spans': ('term', 'start', 'end'), 'segments': ('term', 'start', 'end')} @@ -47,7 +63,7 @@ def record_kinds(task): """The kinds of record an annotation under task may describe, in RECORD_KINDS order.""" if task in _ONLY_KIND: - return (_ONLY_KIND[task],) + return _ONLY_KIND[task] return tuple(kind for kind in RECORD_KINDS if kind != 'file') @@ -88,7 +104,7 @@ def _items(task, value, vocabulary, unknown, size, length, duration): if not isinstance(item, dict): errors.append(f'{where} must be an object with {", ".join(keys)}.') continue - allowed = keys + (('text',) if task == 'segments' else ()) + allowed = keys + (('text',) if task == 'segments' else ()) + ('confidence',) extra = sorted(set(item) - set(allowed)) missing = [key for key in keys if key not in item] if extra or missing: @@ -101,6 +117,8 @@ def _items(task, value, vocabulary, unknown, size, length, duration): errors.append(f'{where} has a term that is not a string.') elif term not in vocabulary: unknown.add(term) + if 'confidence' in item and not _confidence(item['confidence']): + errors.append(f'{where} has a confidence that is not a number from 0 to 1.') if task == 'boxes': if not all(_number(item[key]) for key in ('x', 'y', 'w', 'h')): errors.append(f'{where} must give x, y, w and h as numbers of pixels.') @@ -131,7 +149,253 @@ def _items(task, value, vocabulary, unknown, size, length, duration): return errors -def value_problems(task, vocabulary, state, value, *, kind=None, size=None, length=None, duration=None): +def _confidence(value): + return _number(value) and 0 <= value <= 1 + + +def task_fields(document): + """The fields of a task beyond its type and vocabulary that its values are checked against (spec-t4.md section 1).""" + document = document if isinstance(document, dict) else {} + return {key: document[key] for key in ('keypoints', 'skeleton', 'units', 'mask', 'sigma') if key in document} + + +def _keys_problem(where, item, required, optional=()): + """A sentence when item is not an object of the required keys and some optional ones, else None.""" + if not isinstance(item, dict): + return f'{where} must be an object with {", ".join(required)}.' + allowed = tuple(required) + tuple(optional) + extra = sorted(set(item) - set(allowed)) + missing = [key for key in required if key not in item] + if extra or missing: + parts = ([f'has the unknown key{"s" if len(extra) > 1 else ""} {", ".join(extra)}'] if extra else []) \ + + ([f'lacks {", ".join(missing)}'] if missing else []) + return f'{where} {" and ".join(parts)}; it takes {", ".join(allowed)}.' + return None + + +def _term(where, item, vocabulary, unknown, errors): + term = item.get('term') + if not isinstance(term, str): + errors.append(f'{where} has a term that is not a string.') + elif term not in vocabulary: + unknown.add(term) + if 'confidence' in item and not _confidence(item['confidence']): + errors.append(f'{where} has a confidence that is not a number from 0 to 1.') + + +def _point_problem(point, size): + """A fragment saying why point is not [x, y] inside an image of size, or None.""" + if not (isinstance(point, list) and len(point) == 2 and all(_number(v) for v in point)): + return 'must be [x, y] in pixels' + if point[0] < 0 or point[1] < 0 or (size is not None and (point[0] > size[0] or point[1] > size[1])): + return 'lies outside the image' + (f' of {size[0]} by {size[1]} pixels' if size else '') + return None + + +def _list_value(task, value, errors): + if not isinstance(value, list): + errors.append(f'A {task} value must be a list of objects.') + return False + if len(value) > ITEM_LIMIT: + errors.append(f'A {task} value holds {len(value)} items; at most {ITEM_LIMIT} are allowed.') + return False + return True + + +def _classes(where, classes, vocabulary, unknown, errors): + if not (isinstance(classes, dict) and 1 <= len(classes) <= CLASS_LIMIT): + errors.append(f'{where} classes must be an object of 1 to {CLASS_LIMIT} entries.') + return + for key, term in classes.items(): + if not (key.isdigit() and key == str(int(key)) and 1 <= int(key) <= 65535 and key.isascii()): + errors.append(f'{where} classes has the key {key!r}; keys are the numbers 1 to 65535 as text.') + elif not isinstance(term, str): + errors.append(f'{where} classes maps {key} to something that is not a term.') + elif term not in vocabulary: + unknown.add(term) + + +def _file_name(where, name, errors): + if not (isinstance(name, str) and 1 <= len(name) <= 512 and not name.startswith('/') and '\\' not in name + and not _has_control(name) and '..' not in name.split('/') and '' not in name.split('/')): + errors.append(f'{where} names the file {name!r}, which is not a relative path without .. or empty parts.') + + +def _object_value(task, value, vocabulary, unknown, fields, errors): + """Errors of a mask, depth or point-id file value (an object).""" + where = f'The {task} value' + if task == 'mask': + problem = _keys_problem(where, value, ('classes',), ('file', 'rle', 'confidence')) + if problem is None and ('file' in value) == ('rle' in value): + problem = f'{where} must give either file or rle, not both or neither.' + elif task == 'depth': + problem = _keys_problem(where, value, ('file',), ('confidence',)) + else: + problem = _keys_problem(where, value, ('file', 'classes'), ('confidence',)) + if problem: + errors.append(problem) + return + if 'file' in value: + _file_name(where, value['file'], errors) + wanted = '.png' if task == 'mask' else '.npy' + if isinstance(value['file'], str) and not value['file'].endswith(wanted): + errors.append(f'{where} names a file that is not a {wanted} file.') + if 'rle' in value: + from .annotation_payloads import runs_total, PayloadError + if not isinstance(value['rle'], list): + errors.append(f'{where} rle must be a list of [value, count] runs.') + else: + try: + runs_total(value['rle']) + except PayloadError as exc: + errors.append(f'{where}: {exc}') + if 'classes' in value: + _classes(where, value['classes'], vocabulary, unknown, errors) + if 'confidence' in value and not _confidence(value['confidence']): + errors.append(f'{where} has a confidence that is not a number from 0 to 1.') + + +def _new_items(task, value, vocabulary, unknown, fields, size, points, shape, duration, errors): + """Errors of a value of one of the list tasks of spec-t4.md section 1.""" + if not _list_value(task, value, errors): + return + names = fields.get('keypoints') if isinstance(fields.get('keypoints'), list) else None + tracks = set() + for index, item in enumerate(value): + where = f'Item {index + 1} of the value' + if task == 'polygons': + problem = _keys_problem(where, item, ('term', 'points'), ('confidence',)) + elif task == 'keypoints': + problem = _keys_problem(where, item, ('term', 'points'), ('confidence',)) + elif task == 'timeseries': + problem = _keys_problem(where, item, ('term', 'start', 'end'), ('confidence',)) + elif task == 'track': + problem = _keys_problem(where, item, ('track', 'term', 'frames'), ('confidence',)) + else: + problem = _keys_problem(where, item, ('term', 'center', 'size', 'yaw'), ('confidence',)) + if problem: + errors.append(problem) + continue + _term(where, item, vocabulary, unknown, errors) + if task == 'polygons': + polygon = item['points'] + if not (isinstance(polygon, list) and 3 <= len(polygon) <= POLYGON_LIMIT): + errors.append(f'{where} must have 3 to {POLYGON_LIMIT:,} points.') + continue + wrong = next((f'point {n + 1} {p}' for n, p in enumerate(map(lambda q: _point_problem(q, size), polygon)) + if p), None) + if wrong: + errors.append(f'{where}: its {wrong}.') + elif task == 'keypoints': + found = item['points'] + if not isinstance(found, list) or (names is not None and len(found) != len(names)): + errors.append(f'{where} must list one point per keypoint of the task' + + (f' ({len(names)})' if names is not None else '') + ', null for one not seen.') + continue + for n, point in enumerate(found): + if point is None: + continue + shown = point[:2] if isinstance(point, list) and len(point) == 3 else point + wrong = _point_problem(shown, size) + if not wrong and isinstance(point, list) and len(point) == 3 and point[2] not in (0, 1, 2): + wrong = 'has a visibility that is not 0, 1 or 2' + if wrong: + errors.append(f'{where}: its point {n + 1} {wrong if wrong != "must be [x, y] in pixels" else "must be [x, y], [x, y, v] or null"}.') + break + elif task == 'timeseries': + start, end = item['start'], item['end'] + if not (_number(start) and _number(end)): + errors.append(f'{where} must give start and end as numbers.') + elif start < 0 or start >= end: + errors.append(f'{where} must have 0 ≤ start < end; it has start {start} and end {end}.') + elif duration is not None and end > duration: + errors.append(f'{where} ends at {end} seconds, past the sound of {duration} seconds.') + elif shape and end > shape[0]: + errors.append(f'{where} ends at {end}, past the {shape[0]} positions of the array.') + elif task == 'track': + identifier, frames = item['track'], item['frames'] + if not (isinstance(identifier, str) and 1 <= len(identifier) <= TRACK_ID_LIMIT + and not _has_control(identifier)): + errors.append(f'{where} must have a track id of 1 to {TRACK_ID_LIMIT} characters.') + elif identifier in tracks: + errors.append(f'{where} repeats the track id {identifier!r}; each track is one item.') + tracks.add(identifier) + if not (isinstance(frames, list) and 1 <= len(frames) <= FRAME_LIMIT): + errors.append(f'{where} must have 1 to {FRAME_LIMIT:,} frames.') + continue + last = -1 + for n, frame in enumerate(frames): + at = f'{where}, frame {n + 1},' + wrong = _keys_problem(at, frame, ('frame', 'x', 'y', 'w', 'h')) + if wrong: + errors.append(wrong) + break + if not _whole(frame['frame']) or frame['frame'] <= last: + errors.append(f'{at} must have a whole frame number above the one before.') + break + last = frame['frame'] + if shape and last >= shape[0]: + errors.append(f'{at} is past the {shape[0]} frames of the array.') + break + if not all(_number(frame[key]) for key in ('x', 'y', 'w', 'h')) or frame['x'] < 0 or frame['y'] < 0 \ + or frame['w'] <= 0 or frame['h'] <= 0: + errors.append(f'{at} must give x and y of at least 0 and w and h above zero.') + break + if shape and len(shape) >= 3 and (frame['x'] + frame['w'] > shape[2] or frame['y'] + frame['h'] > shape[1]): + errors.append(f'{at} reaches outside the frame of {shape[2]} by {shape[1]}.') + break + else: # box3d + centre, extent, yaw = item['center'], item['size'], item['yaw'] + if not (isinstance(centre, list) and len(centre) == 3 and all(_number(v) for v in centre)): + errors.append(f'{where} must have a center [x, y, z].') + elif not (isinstance(extent, list) and len(extent) == 3 and all(_number(v) and v > 0 for v in extent)): + errors.append(f'{where} must have a size [l, w, h] above zero.') + elif not _number(yaw): + errors.append(f'{where} must have a yaw in radians.') + + +def _points_value(value, vocabulary, unknown, points, errors): + """Errors of a points value: a list of {term, indices}.""" + if not _list_value('points', value, errors): + return + total = 0 + for index, item in enumerate(value): + where = f'Item {index + 1} of the value' + problem = _keys_problem(where, item, ('term', 'indices'), ('confidence',)) + if problem: + errors.append(problem) + continue + _term(where, item, vocabulary, unknown, errors) + indices = item['indices'] + total += len(indices) if isinstance(indices, list) else 0 + if not (isinstance(indices, list) and indices and all(_whole(i) for i in indices)): + errors.append(f'{where} must list one or more point indices as whole numbers.') + elif any(b <= a for a, b in zip(indices, indices[1:])) or indices[0] < 0: + errors.append(f'{where} must list its indices from 0 upward, each once.') + elif points is not None and indices[-1] >= points: + errors.append(f'{where} names point {indices[-1]}; the cloud has {points} points.') + if total > INDEX_LIMIT: + errors.append(f'A points value lists {total:,} indices; at most {INDEX_LIMIT:,} are allowed.') + + +def _ranking(value, vocabulary, unknown, errors): + if not (isinstance(value, list) and value and all(isinstance(term, str) for term in value)): + errors.append('A ranking value must be a list of one or more terms, best first.') + return + if len(set(value)) != len(value): + errors.append('A ranking value names a term more than once; rank each candidate once.') + unknown.update(term for term in value if term not in vocabulary) + + +def sidecars(task, value): + """The sidecar files a value names (spec-t4.md section 2), as written.""" + if task in FILE_TASKS and isinstance(value, dict) and isinstance(value.get('file'), str): + return [value['file']] + return [] + + +def value_problems(task, vocabulary, state, value, *, kind=None, size=None, length=None, duration=None, + fields=None, points=None, shape=None): """(errors, unknown terms) of one annotation's value under task. vocabulary is the task's list of terms (empty for review and text). state @@ -174,8 +438,19 @@ def value_problems(task, vocabulary, state, value, *, kind=None, size=None, leng errors.append('A text value must be a string.') elif (_utf8_size(value) or 0) > TEXT_LIMIT: errors.append(f'A text value is {_utf8_size(value)} bytes; at most {TEXT_LIMIT} are allowed.') - else: + elif task in _ITEM_KEYS: errors.extend(_items(task, value, vocabulary or (), unknown, size, length, duration)) + elif task == 'ranking': + _ranking(value, terms, unknown, errors) + elif task == 'points' and isinstance(value, list): + _points_value(value, terms, unknown, points, errors) + elif task in FILE_TASKS: + if not isinstance(value, dict): + errors.append(f'A {task} value must be an object' + (' or a list of objects.' if task == 'points' else '.')) + else: + _object_value(task, value, terms, unknown, fields or {}, errors) + else: + _new_items(task, value, terms, unknown, fields or {}, size, points, shape, duration, errors) return errors, sorted(unknown) @@ -232,12 +507,14 @@ def _real_time(text): return True -def validate(task, vocabulary, row, *, kind=None, size=None, length=None, duration=None): +def validate(task, vocabulary, row, *, kind=None, size=None, length=None, duration=None, fields=None, points=None, + shape=None): """Every error of one row under task, terms outside the vocabulary included, as sentences.""" errors = row_problems(row) if isinstance(row, dict) and 'value' in row: found, unknown = value_problems(task, vocabulary, row.get('state'), row['value'], - kind=kind, size=size, length=length, duration=duration) + kind=kind, size=size, length=length, duration=duration, fields=fields, + points=points, shape=shape) errors += found errors += [f'The term {term!r} is not in the vocabulary of the task.' for term in unknown] return errors @@ -249,16 +526,27 @@ def _compact(value): return json.dumps(value, ensure_ascii=False, separators=(',', ':'), allow_nan=False) +def _ordered_object(item): + """An item or object value with its keys in their written order, its frames likewise and classes by number.""" + ordered = {} + for key in sorted(item, key=lambda key: _ITEM_RANK.get(key, len(_ITEM_RANK))): + found = item[key] + if key == 'frames' and isinstance(found, list): + found = [_ordered_object(frame) if isinstance(frame, dict) else frame for frame in found] + elif key == 'classes' and isinstance(found, dict): + found = {name: found[name] for name in sorted( + found, key=lambda name: (0, int(name)) if name.isdigit() and name.isascii() else (1, name))} + ordered[key] = found + return ordered + + def _ordered_value(value): - """value with the keys of the objects in a boxes, spans or segments list in their written order.""" + """value with the keys of the objects in a list value, or of an object value, in their written order.""" + if isinstance(value, dict): + return _ordered_object(value) if not isinstance(value, list): return value - ordered = [] - for item in value: - if isinstance(item, dict): - item = {key: item[key] for key in sorted(item, key=lambda key: _ITEM_RANK.get(key, len(_ITEM_RANK)))} - ordered.append(item) - return ordered + return [_ordered_object(item) if isinstance(item, dict) else item for item in value] def encode(row): @@ -358,7 +646,7 @@ def _decode_line(text): raise ValueError(f'it is not valid JSON ({exc.msg} at column {exc.colno})') from None -def read(raw, task, vocabulary): +def read(raw, task, vocabulary, fields=None): """Read the bytes of a line file whose task is `task` with this vocabulary; return Parsed. Errors: a file that is not UTF-8; a line that is not a JSON object of the @@ -409,7 +697,7 @@ def read(raw, task, vocabulary): 'sort the lines by record.') previous = record if 'value' in row: - found, unknown = value_problems(task, vocabulary, row.get('state'), row['value']) + found, unknown = value_problems(task, vocabulary, row.get('state'), row['value'], fields=fields) errors += found for term in unknown: parsed.unknown.setdefault(term, []).append(number) diff --git a/tuldok_project/check.py b/tuldok_project/check.py index a2cef8c2..7a978a7a 100644 --- a/tuldok_project/check.py +++ b/tuldok_project/check.py @@ -80,7 +80,7 @@ def add(severity, path, pointer, message): check_cycles(definitions, add) check_map(project, definitions, add) _check_results(read.results, definitions, unsound, add) - _check_annotations(read.annotations, definitions, unsound, add) + _check_annotations(read.annotations, definitions, unsound, add, read.sidecars) problems.sort(key=lambda p: (p.path, p.pointer, _SEVERITY_ORDER.get(p.severity, 2), p.message)) decoded = {reference: d.document for reference, d in definitions.items() if d.document is not None} @@ -644,8 +644,29 @@ def _check_results(files, definitions, unsound, add): add(severity, file.path, pointer, message) -def _check_annotations(files, definitions, unsound, add): - """Each line file against its task: a file with no task is an error; a task with errors leaves it unchecked.""" +def _check_annotations(files, definitions, unsound, add, sidecars=None): + """Each line file against its task: a file with no task is an error; a task with errors leaves it unchecked. + + The sidecars of a task (spec-t4.md section 2): a directory with no task + is an error, a line naming a sidecar that is not there is an error, and a + sidecar no line names is a warning. + """ + sidecars = dict(sidecars or {}) + for name in sorted(sidecars): + task = definitions.get(documents.reference(folder_reader.ANNOTATIONS, name)) + if task is None: + add('error', f'{folder_reader.ANNOTATIONS}/{name}', '', + f'There is no {folder_reader.ANNOTATIONS}/{name}.json, the task of these sidecars; add the task or ' + 'remove the directory.') + for definition in definitions.values(): + document = definition.document + if definition.kind == 'annotation' and isinstance(document, dict) and document.get('task') == 'keypoints': + names = document.get('keypoints') if isinstance(document.get('keypoints'), list) else [] + for index, pair in enumerate(document.get('skeleton') or []): + if isinstance(pair, list) and any(point not in names for point in pair): + add('error', definition.path, documents.pointer('skeleton', index), + 'A pair of the skeleton names a point that is not in keypoints; name two of the keypoints.') + named = {} for file in files: name = file.path[len(f'{folder_reader.ANNOTATIONS}/'):-len(folder_reader.LINES_SUFFIX)] task = definitions.get(documents.reference(folder_reader.ANNOTATIONS, name)) @@ -658,6 +679,23 @@ def _check_annotations(files, definitions, unsound, add): if task.path in unsound: add('warning', file.path, '', f'Not checked, because {task.path} has errors; fix those first.') continue - parsed = annotations.read(file.raw, task.document['task'], task.document.get('vocabulary', [])) + parsed = annotations.read(file.raw, task.document['task'], task.document.get('vocabulary', []), + annotations.task_fields(task.document)) for problem in parsed.reported(): add(problem.severity, file.path, problem.pointer, problem.message) + held = sidecars.get(name, {}) + used = named.setdefault(name, set()) + for number, row in parsed.rows: + for sidecar in annotations.sidecars(task.document['task'], row.get('value')): + used.add(sidecar) + if sidecar not in held: + add('error', file.path, f'line {number}', f'The sidecar {folder_reader.ANNOTATIONS}/{name}/' + f'{sidecar} is not there; add it or change the line.') + for name, held in sorted(sidecars.items()): + if documents.reference(folder_reader.ANNOTATIONS, name) not in definitions: + continue + unused = sorted(set(held) - named.get(name, set())) + if unused: + add('warning', f'{folder_reader.ANNOTATIONS}/{name}', '', + f'{len(unused)} sidecar{"s" if len(unused) > 1 else ""} no annotation names ({", ".join(unused[:5])}' + f'{", …" if len(unused) > 5 else ""}); the next Save of this task removes them.') diff --git a/tuldok_project/folder.py b/tuldok_project/folder.py index 17a83846..2af6d839 100644 --- a/tuldok_project/folder.py +++ b/tuldok_project/folder.py @@ -66,6 +66,7 @@ class Folder: project: File | None = None definitions: list = field(default_factory=list) annotations: list = field(default_factory=list) # File per annotations/<name>.jsonl, document None + sidecars: dict = field(default_factory=dict) # task name -> {file name: size} of annotations/<name>/ (spec-t4) results: list = field(default_factory=list) notes: frozenset = frozenset() problems: list = field(default_factory=list) @@ -165,6 +166,9 @@ def _read_definitions(folder, root_fd, directory): for name, entry_kind in entries(fd): path = f'{directory}/{name}' lines = directory == ANNOTATIONS and name.endswith(LINES_SUFFIX) + if directory == ANNOTATIONS and entry_kind == 'directory' and documents.is_name(name): + _read_sidecars(folder, fd, name, path) + continue if entry_kind != 'file' or not (name.endswith('.json') or lines): allowed = ('<name>.json files, one task each, and their <name>.jsonl annotations' if directory == ANNOTATIONS else '<name>.json files, one definition each') @@ -188,6 +192,26 @@ def _read_definitions(folder, root_fd, directory): os.close(fd) +def _read_sidecars(folder, parent_fd, name, path): + """List annotations/<name>/, a task's sidecars (spec-t4.md section 2): regular files named by their content.""" + from .annotation_payloads import is_kept_name + fd = _open_directory(folder, parent_fd, name, path) + if fd is None: + return + found = folder.sidecars.setdefault(name, {}) + try: + for file, entry_kind in entries(fd): + if entry_kind != 'file' or not is_kept_name(file): + folder.problems.append(Problem('error', f'{path}/{file}', '', ( + _wrong_type(entry_kind, 'file') if entry_kind == 'link' else + f'{path}/ may hold only sidecars named by the first 16 hexadecimal characters of their SHA-256 ' + 'and .png or .npy; move or remove this.'))) + continue + found[file] = os.stat(file, dir_fd=fd, follow_symlinks=False).st_size + finally: + os.close(fd) + + def _read_results(folder, root_fd): fd = _open_directory(folder, root_fd, RESULTS, RESULTS) if fd is None: diff --git a/tuldok_project/schemas/annotation.schema.json b/tuldok_project/schemas/annotation.schema.json index 8bab9667..eef6f001 100644 --- a/tuldok_project/schemas/annotation.schema.json +++ b/tuldok_project/schemas/annotation.schema.json @@ -2,7 +2,7 @@ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://tuldok.invalid/schemas/annotation.schema.json", "title": "Tuldok annotation task definition", - "description": "One annotation task in annotations/<name>.json (tuldok_definition_v1). Its annotations are the lines of annotations/<name>.jsonl, checked in tuldok_project/annotations.py.", + "description": "One annotation task in annotations/<name>.json (tuldok_definition_v1). Its annotations are the lines of annotations/<name>.jsonl, checked in tuldok_project/annotations.py; the types of spec-t4.md section 1 are polygons to box3d.", "type": "object", "additionalProperties": false, "required": [ @@ -53,7 +53,16 @@ "text", "boxes", "spans", - "segments" + "segments", + "polygons", + "mask", + "depth", + "keypoints", + "ranking", + "timeseries", + "track", + "points", + "box3d" ] }, "vocabulary": { @@ -65,6 +74,49 @@ "$ref": "#/$defs/term" }, "description": "1 to 500 different terms" + }, + "keypoints": { + "type": "array", + "minItems": 1, + "maxItems": 100, + "uniqueItems": true, + "items": { + "$ref": "#/$defs/term" + }, + "description": "the names of a keypoints task's points, in the order its values list them" + }, + "skeleton": { + "type": "array", + "maxItems": 500, + "items": { + "type": "array", + "minItems": 2, + "maxItems": 2, + "items": { + "$ref": "#/$defs/term" + } + }, + "description": "pairs of keypoint names joined when drawn" + }, + "units": { + "type": "string", + "minLength": 1, + "maxLength": 40, + "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]*$", + "description": "the units of a depth task's values, such as m" + }, + "mask": { + "enum": [ + "semantic", + "instance" + ], + "description": "whether a mask's pixel values are classes (semantic) or objects (instance); default semantic" + }, + "sigma": { + "type": "number", + "exclusiveMinimum": 0, + "maximum": 10, + "description": "the keypoint spread of a keypoints task's agreement (OKS); default 0.1" } }, "allOf": [ @@ -77,7 +129,8 @@ "task": { "enum": [ "review", - "text" + "text", + "depth" ] } } @@ -86,7 +139,7 @@ "properties": { "vocabulary": { "not": {}, - "description": "A review or text task has no vocabulary; remove it." + "description": "A review, text or depth task has no vocabulary; remove it." } } } @@ -103,7 +156,15 @@ "tags", "boxes", "spans", - "segments" + "segments", + "polygons", + "mask", + "keypoints", + "ranking", + "timeseries", + "track", + "points", + "box3d" ] } } @@ -113,6 +174,164 @@ "vocabulary" ] } + }, + { + "if": { + "required": [ + "task" + ], + "properties": { + "task": { + "enum": [ + "keypoints" + ] + } + } + }, + "then": { + "required": [ + "keypoints" + ] + } + }, + { + "if": { + "not": { + "required": [ + "task" + ], + "properties": { + "task": { + "enum": [ + "keypoints" + ] + } + } + } + }, + "then": { + "properties": { + "keypoints": { + "not": {}, + "description": "Only a keypoints task names keypoints; remove it." + } + } + } + }, + { + "if": { + "not": { + "required": [ + "task" + ], + "properties": { + "task": { + "enum": [ + "keypoints" + ] + } + } + } + }, + "then": { + "properties": { + "skeleton": { + "not": {}, + "description": "Only a keypoints task has a skeleton; remove it." + } + } + } + }, + { + "if": { + "not": { + "required": [ + "task" + ], + "properties": { + "task": { + "enum": [ + "keypoints" + ] + } + } + } + }, + "then": { + "properties": { + "sigma": { + "not": {}, + "description": "Only a keypoints task has a sigma; remove it." + } + } + } + }, + { + "if": { + "required": [ + "task" + ], + "properties": { + "task": { + "enum": [ + "depth" + ] + } + } + }, + "then": { + "required": [ + "units" + ] + } + }, + { + "if": { + "not": { + "required": [ + "task" + ], + "properties": { + "task": { + "enum": [ + "depth" + ] + } + } + } + }, + "then": { + "properties": { + "units": { + "not": {}, + "description": "Only a depth task has units; remove them." + } + } + } + }, + { + "if": { + "not": { + "required": [ + "task" + ], + "properties": { + "task": { + "enum": [ + "mask" + ] + } + } + } + }, + "then": { + "properties": { + "mask": { + "not": {}, + "description": "Only a mask task says mask; remove it." + } + } + } } ], "$defs": { diff --git a/tuldok_project/store.py b/tuldok_project/store.py index 8fed5499..00713bf7 100644 --- a/tuldok_project/store.py +++ b/tuldok_project/store.py @@ -205,6 +205,9 @@ def _list_definitions(root): tasks = {name for name, entry_kind in listed if entry_kind == 'file'} for name, entry_kind in listed: path = f'{directory}/{name}' + if (directory == folder_reader.ANNOTATIONS and entry_kind == 'directory' + and documents.is_name(name) and name + '.json' in tasks): + continue # a task's sidecars (spec-t4.md section 2): named by content, never rewritten if (directory == folder_reader.ANNOTATIONS and name.endswith(folder_reader.LINES_SUFFIX) and entry_kind == 'file' and name[:-len(folder_reader.LINES_SUFFIX)] + '.json' in tasks): @@ -605,7 +608,8 @@ def _lines_to_import(self, root, disk, recorded, disk_lines, exists): problems.append(Problem('error', where, '', f'There is no {annotation_rows.reference(name)}.json, ' 'the task of these annotations.')) continue - parsed = annotations.read(raw, task.document.get('task'), task.document.get('vocabulary', [])) + parsed = annotations.read(raw, task.document.get('task'), task.document.get('vocabulary', []), + annotations.task_fields(task.document)) errors = [Problem(item.severity, where, item.pointer, item.message) for item in parsed.reported() if item.severity == 'error'] if errors: From 242496085bb781f45b82b93bef460164b035a5de Mon Sep 17 00:00:00 2001 From: MrScripty <TheEnvironmentGuy@protonmail.com> Date: Thu, 19 Nov 2026 06:52:46 -0700 Subject: [PATCH 107/131] feat(workspace): the Map of a dataset's embeddings, its curation lists, and the Embed form curation.js draws an embeddings set as a map on the Data tab (Map beside Records and Files), coloured by split, kind, an annotation or a field, with Box and Lasso, zoom and Move; More like this, Duplicates, Outliers, Leakage and Thin regions beside it. A choice becomes a select definition or fills Freeze's records. The Embed form offers EmbeddingGemma 2 as the default; the endpoint's drawer shows and sets the machine's embedder. The browser check browser_project_workspace_curation.cjs and its fixture; browser_fake_pumas.py serves embedders with --embedders. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --- app.py | 1 + docs/contracts/project-folder.md | 10 +- static/project-workspace.html | 1 + static/project-workspace/annotate.js | 20 +- static/project-workspace/base.css | 39 ++ static/project-workspace/curation.js | 501 +++++++++++++++++++ static/project-workspace/generate.js | 1 + static/project-workspace/inside.js | 23 +- static/project-workspace/tabs.js | 4 +- tests/browser_fake_pumas.py | 10 + tests/browser_project_workspace_curation.cjs | 377 ++++++++++++++ tests/project_curation_browser_fixture.py | 69 +++ 12 files changed, 1043 insertions(+), 13 deletions(-) create mode 100644 static/project-workspace/curation.js create mode 100644 tests/browser_project_workspace_curation.cjs create mode 100644 tests/project_curation_browser_fixture.py diff --git a/app.py b/app.py index 88af86f1..05457cc8 100644 --- a/app.py +++ b/app.py @@ -812,6 +812,7 @@ def _get(self): '/project-workspace/training.js': ('project-workspace/training.js', 'text/javascript'), '/project-workspace/annotate.js': ('project-workspace/annotate.js', 'text/javascript'), '/project-workspace/generate.js': ('project-workspace/generate.js', 'text/javascript'), + '/project-workspace/curation.js': ('project-workspace/curation.js', 'text/javascript'), '/project-workspace/app.js': ('project-workspace/app.js', 'text/javascript'), '/static/vendor/ubuntu-sans/UbuntuSans[wdth,wght].ttf': ('vendor/ubuntu-sans/UbuntuSans[wdth,wght].ttf', 'font/ttf'), '/static/vendor/ubuntu-sans/UbuntuSans-Italic[wdth,wght].ttf': ('vendor/ubuntu-sans/UbuntuSans-Italic[wdth,wght].ttf', 'font/ttf'), diff --git a/docs/contracts/project-folder.md b/docs/contracts/project-folder.md index f0691605..46ccdfa7 100644 --- a/docs/contracts/project-folder.md +++ b/docs/contracts/project-folder.md @@ -2208,8 +2208,14 @@ which keeps an annotation with `set_annotation`; Save writes the unsaved annotations with the unsaved definitions. Its Suggest asks `suggest_annotation` of a model `suggestion_models` offers and fills the form, and a kept suggestion passes its `from`. Train shows the machine's Pumas endpoint -(`endpoint`; for the owner `set_endpoint` and `find_endpoints`), and Data's -Generate form keeps a dataset whose run is the step `generate`. +(`endpoint`; for the owner `set_endpoint` and `find_endpoints`, and the +machine's embedder by `set_embedder`), and Data's +Generate form keeps a dataset whose run is the step `generate`. A dataset +opened on Data shows a Map beside its records and files when `embeddings` +lists a set for it (`embedding_map` and the four searches); a region chosen on +the map is kept as a dataset whose run is the step `select`, or fills the +Freeze form's `records`; Data's Embed form keeps a dataset whose run is the +step `embed`. Each of its controls calls one operation and is drawn only for a session that may call it, so a credential that may only inspect sees a page that changes nothing. The report is linked from the Overview tab. The page reads again diff --git a/static/project-workspace.html b/static/project-workspace.html index 4ba61606..01d7e880 100644 --- a/static/project-workspace.html +++ b/static/project-workspace.html @@ -23,6 +23,7 @@ <script defer src="/project-workspace/training.js"></script> <script defer src="/project-workspace/annotate.js"></script> <script defer src="/project-workspace/generate.js"></script> +<script defer src="/project-workspace/curation.js"></script> <script defer src="/project-workspace/tabs.js"></script> <script defer src="/project-workspace/app.js"></script> </head> diff --git a/static/project-workspace/annotate.js b/static/project-workspace/annotate.js index 857f5494..467bd7a3 100644 --- a/static/project-workspace/annotate.js +++ b/static/project-workspace/annotate.js @@ -874,7 +874,19 @@ window.LabAnnotate = (() => { } putInPlace(ofTasks, box); }; - f.appendChild(choice(s, key, 'dataset', 'The dataset whose records are frozen', sets.map(d => [d.reference, d.title + ' · ' + d.reference]), sets.length ? sets[0].reference : '', drawTasks)); + const named = h('div', 'ann-field'); + // Records chosen on a map of embeddings (curation.js, spec-t5 section 5): only those are frozen. + const drawNamed = ds => { + const box = h('div'); + if (Array.isArray(s.text.records) && s.text.recordsOf === ds) { + box.appendChild(h('p', 'small frz-records', 'Only the ' + s.text.records.length.toLocaleString('en-GB') + ' records chosen on the map: ' + s.text.records.slice(0, 3).join(', ') + (s.text.records.length > 3 ? ', …' : '') + '.')); + const b = h('button', 'btn sm ghost', 'Freeze every record instead'); b.type = 'button'; b.dataset.key = key + ':field:records-clear'; + b.addEventListener('click', () => { s.text.records = null; drawNamed(ds); }); box.appendChild(b); + } + putInPlace(named, box); + }; + f.appendChild(choice(s, key, 'dataset', 'The dataset whose records are frozen', sets.map(d => [d.reference, d.title + ' · ' + d.reference]), sets.length ? sets[0].reference : '', ds => { drawTasks(ds); drawNamed(ds); })); + f.appendChild(named); drawNamed(s.text.dataset); f.appendChild(ofTasks); drawTasks(s.text.dataset); const two = h('div', 'two'); two.appendChild(input(s, key, 'seed', 'Seed (required)', { type: 'number', value: '7', hint: 'an integer' })); @@ -919,16 +931,20 @@ window.LabAnnotate = (() => { const seed = Number(String(x.seed || '').trim()); if (!Number.isInteger(seed) || String(x.seed || '').trim() === '') throw Object.assign(Error('The seed is a whole number.'), { code: 'invalid' }); const settings = { seed, shares }; + if (Array.isArray(x.records) && x.records.length && x.recordsOf === x.dataset) settings.records = x.records.slice(); const include = (x.include || []).slice().sort((a, b) => ['accepted', 'needs-work', 'rejected', 'draft'].indexOf(a) - ['accepted', 'needs-work', 'rejected', 'draft'].indexOf(b)); if (!(include.length === 1 && include[0] === 'accepted')) settings.include = include; return { format: FORMAT, kind: 'dataset', title: (x.title || '').trim(), run: { step: 'freeze', inputs: { records: x.dataset }, annotations: (x.tasks || []).slice(), settings } }; } + /** The Freeze form filled in with records chosen on a map (curation.js): the dataset and only those records. */ + function fillFreeze(dataset, records) { const s = A.slot('newfreeze'); s.text.dataset = dataset; s.text.records = records.slice(); s.text.recordsOf = dataset; s.text.tasks = null; } + /** Needs you: the Annotate tab opens on this task. */ function choose(task) { ui.task = task; ui.page = 0; ui.filter = 'all'; } S.annotate = annotate; // The drawer forms' parts, for the Generate form (generate.js). const forms = { formDrawer, input, choice, header, slug, textOf }; - return { choose, datasetForm, forms }; + return { choose, datasetForm, forms, fillFreeze }; })(); diff --git a/static/project-workspace/base.css b/static/project-workspace/base.css index 5a0a0e6d..73a8dec7 100644 --- a/static/project-workspace/base.css +++ b/static/project-workspace/base.css @@ -950,3 +950,42 @@ canvas.trn-strip { display: block; width: 100%; background: var(--surface-2); bo .trn-thumb { display: block; width: 72px; height: 72px; object-fit: contain; background: var(--surface-2); border-radius: 3px; image-rendering: pixelated; } div.trn-thumb { display: grid; place-items: center; text-align: center; padding: 4px; } .trn-problems { color: var(--warn); margin: 0; } + +/* Curation by embeddings (curation.js, docs/plans/training-and-curation/spec-t5.md section 6): the Map mode of a + dataset opened. The categorical colours are the dataviz reference palette's eight, in its fixed order, stepped for + each surface. */ +:root { --cat-1: #2a78d6; --cat-2: #eb6834; --cat-3: #1baf7a; --cat-4: #eda100; --cat-5: #e87ba4; --cat-6: #008300; --cat-7: #6250d6; --cat-8: #e34948; } +@media (prefers-color-scheme: dark) { :root:not([data-theme="light"]) { --cat-1: #3987e5; --cat-2: #d95926; --cat-3: #199e70; --cat-4: #c98500; --cat-5: #d55181; --cat-6: #008300; --cat-7: #9085e9; --cat-8: #e66767; } } +:root[data-theme="dark"] { --cat-1: #3987e5; --cat-2: #d95926; --cat-3: #199e70; --cat-4: #c98500; --cat-5: #d55181; --cat-6: #008300; --cat-7: #9085e9; --cat-8: #e66767; } +.cur { display: grid; gap: 10px; min-width: 0; } +.cur-head { display: grid; gap: 6px; min-width: 0; } +.cur-head select { max-width: 100%; } +.cur-facts { margin: 0; overflow-wrap: anywhere; } +.cur-bar { display: flex; flex-wrap: wrap; align-items: center; gap: 8px 12px; min-width: 0; } +.cur-pick, .cur-num { display: inline-flex; align-items: center; gap: 6px; font-size: 13px; color: var(--ink-2); } +.cur-pick select { max-width: 220px; } +.cur-num input { width: 6.5em; } +.cur-map { position: relative; min-width: 0; border: 1px solid var(--line); border-radius: var(--radius); background: var(--surface); overflow: hidden; } +.cur-map canvas { display: block; width: 100%; touch-action: none; cursor: crosshair; } +.cur-map canvas:focus-visible { outline: 2px solid var(--focus); outline-offset: -2px; } +.cur-tip { position: absolute; pointer-events: none; display: grid; gap: 2px; max-width: 240px; padding: 4px 8px; font-size: 12px; background: var(--surface); color: var(--ink); border: 1px solid var(--line-strong); border-radius: var(--radius); box-shadow: 0 2px 6px rgba(0, 0, 0, .12); overflow-wrap: anywhere; } +.cur-tip span { color: var(--ink-2); } +.cur-legend > div { display: flex; flex-wrap: wrap; gap: 4px 14px; font-size: 12px; color: var(--ink-2); } +.cur-key { display: inline-flex; align-items: center; gap: 6px; } +.cur-key .sw { width: 10px; height: 10px; border-radius: 50%; flex: none; } +.cur-key .sw.thin { border-radius: 2px; background: color-mix(in srgb, var(--warn) 22%, var(--surface)); border: 1px solid var(--line-strong); } +.cur-ramp { display: inline-block; width: 80px; height: 10px; border-radius: 2px; background: linear-gradient(90deg, var(--ramp-lo), var(--ramp-hi)); vertical-align: middle; } +.cur-chosen > div { display: grid; gap: 8px; } +.cur-chosen-line { display: flex; flex-wrap: wrap; align-items: center; gap: 8px; } +.cur-form { border: 1px solid var(--line); border-radius: var(--radius); padding: 10px; background: var(--surface); } +.good-line { color: var(--good); margin: 0; } +.cur-lists > div { display: grid; gap: 8px; min-width: 0; } +.cur-tabs { flex-wrap: wrap; max-width: 100%; justify-self: start; } +.cur-controls { display: flex; flex-wrap: wrap; gap: 8px 14px; align-items: center; } +.cur-list > p { margin: 0; } +.cur-rows { max-height: 320px; overflow: auto; } +.cur-row { grid-template-columns: minmax(0, 1fr) auto; gap: 0 12px; padding: 5px 8px; } +.cur-row .title { overflow-wrap: anywhere; } +.cur-row .num { font-family: var(--mono); font-size: 12px; color: var(--ink-2); grid-row: 1 / span 2; grid-column: 2; align-self: center; } +.cur-row .sub { grid-column: 1; } +.frz-records { margin: 0 0 4px; overflow-wrap: anywhere; } diff --git a/static/project-workspace/curation.js b/static/project-workspace/curation.js new file mode 100644 index 00000000..cb974fb7 --- /dev/null +++ b/static/project-workspace/curation.js @@ -0,0 +1,501 @@ +'use strict'; +// Curation by embeddings on the page (docs/plans/training-and-curation/spec-t5.md section 6): the Map mode of a dataset +// opened on the Data tab (inside.js draws the mode switch and the viewer; this module draws the map and its lists), and +// the Data tab's Embed form, which keeps a new dataset whose run is the step embed as an unsaved edit, as Generate does. +// +// The map is a canvas of the set's records in two dimensions (embedding_map), coloured by a choice, with the thin cells +// shaded; the wheel zooms about the pointer, Move drags the view, Box and Lasso choose points. Hovering a point shows its +// id; resting on it shows the record in inside.js's viewer; a click opens it and asks for its neighbours. The chosen +// points become a new dataset (a select definition, kept with set_definition) or fill the Freeze form (annotate.js). +// Beside the map: More like this, Duplicates, Outliers, Leakage and Thin regions, each asked for when first shown. +// +// Updating in place (spec-w4): the answers are not watched; a reading that changed something makes inside.js draw the +// opened view again, and this module draws the map again from its kept state (the set, the colour, the view, the tool, +// what is chosen and opened, each list's controls). A person's own changes redraw only the part they change. +window.LabCuration = (() => { + const P = window.TuldokProject, S = window.LabScreens, A = window.LabActions, h = window.LabCharts.h; + const { putInPlace } = S.parts; + const FORMAT = 'tuldok_definition_v1'; + const SELECT_LIMIT = 20000; // records one select names (check.py) + const CATEGORIES = 8; // categorical colours: --cat-1 to --cat-8; the rest, and "other", are --ink-3 + const NO_CODE = 65535; + const REST_MS = 300; // resting on a point this long shows its record in the viewer + const button = (cls, text, key, onClick) => { const b = h('button', cls, text); b.type = 'button'; if (key) b.dataset.key = key; if (onClick) b.addEventListener('click', onClick); return b; }; + const count = (n, one, many) => n.toLocaleString('en-GB') + ' ' + (n === 1 ? one : many || one + 's'); + const pct = x => (x * 100).toFixed(x < 0.1 ? 1 : 0) + ' %'; + const cos = x => x.toFixed(4); + const D = () => window.LabInside.drawing; + const raw = b64 => { const s = atob(b64 || ''), u = new Uint8Array(s.length); for (let i = 0; i < s.length; i++) u[i] = s.charCodeAt(i); return u; }; + const u16 = b64 => { const u = raw(b64), d = new DataView(u.buffer), out = new Uint16Array(u.length >> 1); for (let i = 0; i < out.length; i++) out[i] = d.getUint16(i * 2, true); return out; }; + + // ---- What is kept per dataset across drawings ----------------------------------------------------------------- + const states = new Map(); + const stateOf = ref => { + if (!states.has(ref)) states.set(ref, { key: null, colour: undefined, view: { k: 1, cu: 0.5, cv: 0.5 }, tool: 'box', chosen: new Set(), opened: null, + list: 'duplicates', dup: '0.98', leak: '0.95', train: 'train', k: '5', form: false, kept: null }); + return states.get(ref); + }; + const usable = em => ((em && em.sets) || []).filter(s => !s.problem && s.records_run); + const keyOf = s => s.run + '/' + s.name; + /** The embeddings sets of a dataset (kept like any answer until a reading finds a change). */ + const sets = ref => P.read('embeddings', { dataset: ref }).catch(error => ({ error, sets: [] })); + const base = s => ({ run: s.run, name: s.name, records_run: s.records_run }); + + // ---- The Map mode ------------------------------------------------------------------------------------------------- + /** + * The map and its lists for a dataset opened in inside.js: ctx is {ref, em (the embeddings answer), act, + * show(id, run) (shows a record in the viewer), live() (whether the view is still on screen)}. + */ + function panel(ctx) { + const st = stateOf(ctx.ref), list = usable(ctx.em); + const root = h('section', 'cur'); root.setAttribute('aria-label', 'The records on a map of their embeddings'); + const broken = ((ctx.em && ctx.em.sets) || []).filter(s => s.problem); + if (!list.length) { + root.appendChild(h('p', 'empty', 'No embeddings of this dataset can be read.')); + for (const s of broken) root.appendChild(h('p', 'small warnline', s.holder + ' · ' + s.name + ': ' + s.problem)); + return root; + } + const set = list.find(s => keyOf(s) === st.key) || list[0]; st.key = keyOf(set); + const c = { ctx, st, set, root, m: null, pts: null, hover: null, rest: 0 }; + const head = h('div', 'cur-head'); + if (list.length > 1) { + const sel = h('select'); sel.setAttribute('aria-label', 'Embeddings'); sel.dataset.key = 'cur-set'; + for (const s of list) { const o = h('option', null, s.holder.replace(/^datasets\//, '') + ' · ' + s.name + ' · ' + s.model.name); o.value = keyOf(s); o.selected = keyOf(s) === st.key; sel.appendChild(o); } + sel.addEventListener('change', () => { st.key = sel.value; st.chosen = new Set(); st.opened = null; st.colour = undefined; st.view = { k: 1, cu: 0.5, cv: 0.5 }; putInPlace(root.parentNode, panel(ctx)); }); + head.appendChild(sel); + } + c.facts = h('p', 'small muted cur-facts', set.rows.toLocaleString('en-GB') + ' records · ' + set.dimensions + ' dimensions · ' + set.model.name + (set.prefix ? ' · prefix “' + set.prefix + '”' : '')); + head.appendChild(c.facts); + if (!set.current) head.appendChild(h('p', 'small warnline', 'These embeddings describe run ' + set.records_run.slice(0, 8) + ', not the dataset\'s current product: they may not match its records.')); + for (const s of broken) head.appendChild(h('p', 'small warnline', s.holder + ' · ' + s.name + ': ' + s.problem)); + const bar = h('div', 'cur-bar'); + c.colourSlot = h('span', 'cur-colour'); bar.appendChild(c.colourSlot); + const tools = h('div', 'seg'); tools.setAttribute('role', 'group'); tools.setAttribute('aria-label', 'Dragging on the map'); + for (const [tool, label] of [['move', 'Move'], ['box', 'Box'], ['lasso', 'Lasso']]) { + const b = button(null, label, 'cur-tool-' + tool, () => { st.tool = tool; for (const x of tools.children) x.setAttribute('aria-pressed', String(x === b)); }); + b.setAttribute('aria-pressed', String(st.tool === tool)); tools.appendChild(b); + } + bar.appendChild(tools); + bar.appendChild(button('btn sm ghost', 'Reset view', 'cur-reset', () => { st.view = { k: 1, cu: 0.5, cv: 0.5 }; paint(c); })); + head.appendChild(bar); + root.appendChild(head); + const box = h('div', 'cur-map'); + c.canvas = h('canvas'); c.canvas.tabIndex = 0; c.canvas.setAttribute('role', 'img'); c.canvas.dataset.key = 'cur-canvas'; + c.canvas.setAttribute('aria-label', 'Map of ' + set.rows + ' records; the arrow keys move between the nearest records, Enter opens one'); + c.tip = h('div', 'cur-tip'); c.tip.hidden = true; c.tip.setAttribute('aria-hidden', 'true'); + c.live = h('p', 'sr-only'); c.live.setAttribute('aria-live', 'polite'); + box.appendChild(c.canvas); box.appendChild(c.tip); box.appendChild(c.live); + root.appendChild(box); + c.legend = h('div', 'cur-legend'); root.appendChild(c.legend); + c.selBar = h('div', 'cur-chosen'); root.appendChild(c.selBar); + c.lists = h('div', 'cur-lists'); root.appendChild(c.lists); + c.canvas.parentNode.appendChild(h('p', 'note cur-reading', 'Reading the map…')); + wire(c); + load(c); + return root; + } + + async function load(c) { + const { st, set } = c; + let m; + try { + const first = await P.read('embedding_map', base(set)); + const colour = st.colour === undefined ? (first.colours.includes('split') ? 'split' : null) : st.colour; + st.colour = colour; + m = colour ? await P.read('embedding_map', { ...base(set), colour }) : first; + } catch (error) { + if (!c.ctx.live()) return; + putInPlace(c.root.querySelector('.cur-map'), A.refusal(error)); return; + } + if (!c.ctx.live() || !c.root.isConnected && c.m) return; + c.m = decode(m); + const reading = c.root.querySelector('.cur-reading'); if (reading) reading.remove(); + c.facts.textContent = [count(m.rows, 'record'), m.dimensions + ' dimensions', set.model.name, m.method === 'pca' ? 'principal components (' + m.explained.map(pct).join(' and ') + ' of the variance, from ' + count(m.sample, 'row') + ')' : 'the script\'s ' + m.method, + m.missing ? count(m.missing, 'row') + ' with no record in the product' : null, set.prefix ? 'prefix “' + set.prefix + '”' : null].filter(Boolean).join(' · '); + colourChoice(c); legend(c); + D().paints(c.canvas, () => paint(c)); + chosenBar(c); lists(c); + } + function decode(m) { + const x = D().floats(m.x_f32), y = D().floats(m.y_f32), at = new Map(m.ids.map((id, i) => [id, i])); + const col = m.colour ? (m.colour.type === 'category' ? { codes: u16(m.colour.codes_u16) } : { values: D().floats(m.colour.values_f32) }) : null; + return { ...m, x, y, at, col }; + } + + // ---- Colour ---------------------------------------------------------------------------------------------------------- + const WORD = c => c === 'split' ? 'Split' : c === 'kind' ? 'Kind' : c.startsWith('annotation:') ? 'Annotation · ' + c.slice(11) : 'Field · ' + c.slice(6); + function colourChoice(c) { + const l = h('label', 'cur-pick'); l.appendChild(document.createTextNode('Colour by ')); + const sel = h('select'); sel.dataset.key = 'cur-colour'; + for (const [v, t] of [['', 'nothing']].concat(c.m.colours.map(x => [x, WORD(x)]))) { const o = h('option', null, t); o.value = v; o.selected = v === (c.st.colour || ''); sel.appendChild(o); } + sel.addEventListener('change', async () => { + c.st.colour = sel.value || null; + try { c.m = decode(c.st.colour ? await P.read('embedding_map', { ...base(c.set), colour: c.st.colour }) : await P.read('embedding_map', base(c.set))); } catch (error) { putInPlace(c.legend, A.refusal(error)); return; } + legend(c); paint(c); + }); + l.appendChild(sel); putInPlace(c.colourSlot, l); + } + function palette() { + const t = D().token; const cats = []; for (let i = 1; i <= CATEGORIES; i++) cats.push(t('--cat-' + i)); + return { cats, other: t('--ink-3'), ink: t('--ink'), accent: t('--accent'), surface: t('--surface'), thin: t('--warn'), grid: t('--grid') }; + } + /** [r, g, b] of a row, or null for a row with no value. */ + function colourOf(c, pal, i) { + const col = c.m.col; + if (!col) return pal.cats[0]; + if (col.codes) { const k = col.codes[i]; if (k === NO_CODE) return null; const cat = c.m.colour.categories[k]; return cat && !cat.other && k < CATEGORIES ? pal.cats[k] : pal.other; } + const v = col.values[i]; if (!Number.isFinite(v)) return null; + return c._ramp(v); + } + function legend(c) { + const box = h('div'); const m = c.m, pal = palette(); + if (!m.colour) { box.appendChild(h('span', 'small muted', 'One colour: choose what to colour by.')); } + else if (m.colour.type === 'number') { + c._ramp = D().ramp(m.colour.low, m.colour.high); + const sw = h('span', 'cur-ramp'); sw.setAttribute('aria-hidden', 'true'); box.appendChild(h('span', 'small', WORD(m.colour.by) + ': ' + m.colour.low.toLocaleString('en-GB') + ' ')); box.appendChild(sw); box.appendChild(h('span', 'small', ' ' + m.colour.high.toLocaleString('en-GB'))); + } else { + m.colour.categories.forEach((cat, k) => { + const item = h('span', 'cur-key'); const sw = h('span', 'sw'); const rgb = !cat.other && k < CATEGORIES ? pal.cats[k] : pal.other; sw.style.background = 'rgb(' + rgb.join(',') + ')'; sw.dataset.cat = cat.other || k >= CATEGORIES ? 'other' : String(k + 1); + item.appendChild(sw); item.appendChild(h('span', null, cat.name + ' · ' + cat.count.toLocaleString('en-GB'))); box.appendChild(item); + }); + } + if (m.thin.length) { const item = h('span', 'cur-key'); const sw = h('span', 'sw thin'); item.appendChild(sw); item.appendChild(h('span', null, 'thin region')); box.appendChild(item); } + box.dataset.colour = m.colour ? m.colour.by : ''; + putInPlace(c.legend, box); + } + + // ---- Drawing -------------------------------------------------------------------------------------------------------- + const PAD = 12; + function frame(c, W, H) { + const dpr = window.devicePixelRatio || 1, p = PAD * dpr, [x0, x1, y0, y1] = c.m.bounds, v = c.st.view; + const iw = W - 2 * p, ih = H - 2 * p; + const sx = x => p + ((((x - x0) / (x1 - x0)) - v.cu) * v.k + 0.5) * iw; + const sy = y => p + (((1 - (y - y0) / (y1 - y0)) - v.cv) * v.k + 0.5) * ih; + const back = (px, py) => [((px - p) / iw - 0.5) / v.k + v.cu, ((py - p) / ih - 0.5) / v.k + v.cv]; + return { dpr, p, iw, ih, sx, sy, back }; + } + function paint(c) { + if (!c.m || !c.canvas.isConnected) return; + const wide = c.canvas.clientWidth; const size = D().fit(c.canvas, Math.max(260, Math.min(460, Math.round(wide * 0.7)))); if (!size) return; + const [W, H] = size, ctx = c.canvas.getContext('2d'), m = c.m, pal = palette(), f = frame(c, W, H); + if (m.colour && m.colour.type === 'number') c._ramp = D().ramp(m.colour.low, m.colour.high); + c.f = f; + ctx.clearRect(0, 0, W, H); + ctx.fillStyle = 'rgb(' + pal.surface.join(',') + ')'; ctx.fillRect(0, 0, W, H); + // Thin cells, washed. + const [x0, x1, y0, y1] = m.bounds, cells = m.grid.cells; + ctx.fillStyle = 'rgba(' + pal.thin.join(',') + ',0.14)'; + for (const t of m.thin) { const a = f.sx(t.x[0]), b = f.sx(t.x[1]), top = f.sy(t.y[1]), bot = f.sy(t.y[0]); ctx.fillRect(a, top, b - a, bot - top); } + void x0; void x1; void y0; void y1; void cells; + const r = Math.max(1.5, 2.4 * f.dpr), n = m.ids.length, px = new Float32Array(n), py = new Float32Array(n); + for (let i = 0; i < n; i++) { px[i] = f.sx(m.x[i]); py[i] = f.sy(m.y[i]); } + c.pts = { px, py }; + // Rows with no value first and faint, then the rest. + for (let pass = 0; pass < 2; pass++) for (let i = 0; i < n; i++) { + const rgb = colourOf(c, pal, i); if ((rgb === null) !== (pass === 0)) continue; + if (px[i] < -r || py[i] < -r || px[i] > W + r || py[i] > H + r) continue; + ctx.fillStyle = rgb === null ? 'rgba(' + pal.other.join(',') + ',0.45)' : 'rgb(' + rgb.join(',') + ')'; + ctx.beginPath(); ctx.arc(px[i], py[i], r, 0, 6.2832); ctx.fill(); + } + // What is chosen: a ring in ink. The opened record: a ring in the accent, joined to its most alike. + ctx.lineWidth = Math.max(1, f.dpr); ctx.strokeStyle = 'rgb(' + pal.ink.join(',') + ')'; + for (const id of c.st.chosen) { const i = m.at.get(id); if (i == null) continue; ctx.beginPath(); ctx.arc(px[i], py[i], r + 1.6 * f.dpr, 0, 6.2832); ctx.stroke(); } + const o = c.st.opened != null ? m.at.get(c.st.opened) : null; + if (o != null) { + ctx.strokeStyle = 'rgb(' + pal.accent.join(',') + ')'; ctx.lineWidth = 1.5 * f.dpr; + for (const nb of c.like || []) { const j = m.at.get(nb.id); if (j == null) continue; ctx.beginPath(); ctx.moveTo(px[o], py[o]); ctx.lineTo(px[j], py[j]); ctx.stroke(); } + ctx.lineWidth = 2 * f.dpr; ctx.beginPath(); ctx.arc(px[o], py[o], r + 3 * f.dpr, 0, 6.2832); ctx.stroke(); + } + if (c.drag && c.drag.tool !== 'move' && c.drag.path.length > 1) { + ctx.strokeStyle = 'rgb(' + pal.accent.join(',') + ')'; ctx.lineWidth = f.dpr; ctx.setLineDash([4 * f.dpr, 3 * f.dpr]); ctx.beginPath(); + if (c.drag.tool === 'box') { const [a, b] = [c.drag.path[0], c.drag.path[c.drag.path.length - 1]]; ctx.rect(a[0], a[1], b[0] - a[0], b[1] - a[1]); } + else { ctx.moveTo(c.drag.path[0][0], c.drag.path[0][1]); for (const q of c.drag.path) ctx.lineTo(q[0], q[1]); ctx.closePath(); } + ctx.stroke(); ctx.setLineDash([]); + } + c.canvas.dataset.drawn = String(n); + } + /** The row nearest the canvas point (device pixels) within 10 CSS pixels, or null. */ + function nearest(c, X, Y) { + if (!c.pts) return null; + const { px, py } = c.pts, lim = (10 * (window.devicePixelRatio || 1)) ** 2; let best = null, bd = lim; + for (let i = 0; i < px.length; i++) { const d = (px[i] - X) ** 2 + (py[i] - Y) ** 2; if (d < bd) { bd = d; best = i; } } + return best; + } + const at = (c, e) => { const r = c.canvas.getBoundingClientRect(), dpr = window.devicePixelRatio || 1; return [(e.clientX - r.left) * dpr, (e.clientY - r.top) * dpr]; }; + function inside(poly, x, y) { let inn = false; for (let i = 0, j = poly.length - 1; i < poly.length; j = i++) { const [xi, yi] = poly[i], [xj, yj] = poly[j]; if ((yi > y) !== (yj > y) && x < (xj - xi) * (y - yi) / (yj - yi) + xi) inn = !inn; } return inn; } + function valueWord(c, i) { + const col = c.m.col; if (!col) return ''; + if (col.codes) { const k = col.codes[i]; return k === NO_CODE ? 'no ' + WORD(c.m.colour.by).toLowerCase() : c.m.colour.categories[k].name; } + return Number.isFinite(col.values[i]) ? String(col.values[i]) : 'no value'; + } + function wire(c) { + const cv = c.canvas, st = c.st; + cv.addEventListener('wheel', e => { + if (!c.f) return; e.preventDefault(); + const [X, Y] = at(c, e), [u, v] = c.f.back(X, Y), k = Math.min(200, Math.max(1, st.view.k * Math.exp(-e.deltaY * 0.0015))); + const fx = (X - c.f.p) / c.f.iw - 0.5, fy = (Y - c.f.p) / c.f.ih - 0.5; + st.view = { k, cu: u - fx / k, cv: v - fy / k }; paint(c); + }, { passive: false }); + cv.addEventListener('pointerdown', e => { + if (!c.f || e.button !== 0) return; + cv.setPointerCapture(e.pointerId); + c.drag = { tool: e.shiftKey && st.tool === 'move' ? 'box' : st.tool, path: [at(c, e)], view: { ...st.view }, add: e.shiftKey, moved: false }; + }); + cv.addEventListener('pointermove', e => { + const [X, Y] = at(c, e); + if (c.drag) { + const d = c.drag, [sx, sy] = d.path[0]; + if (Math.abs(X - sx) + Math.abs(Y - sy) > 4) d.moved = true; + if (d.tool === 'move') st.view = { ...d.view, cu: d.view.cu - (X - sx) / c.f.iw / d.view.k, cv: d.view.cv - (Y - sy) / c.f.ih / d.view.k }; + else d.path.push([X, Y]); + paint(c); return; + } + hover(c, nearest(c, X, Y), e); + }); + const end = e => { + const d = c.drag; c.drag = null; if (!d) return; + if (!d.moved) { const i = nearest(c, ...at(c, e)); if (i != null) open(c, c.m.ids[i]); paint(c); return; } + if (d.tool !== 'move') { + const { px, py } = c.pts, chosen = d.add ? new Set(st.chosen) : new Set(); + if (d.tool === 'box') { + const [a, b] = [d.path[0], d.path[d.path.length - 1]], lx = Math.min(a[0], b[0]), hx = Math.max(a[0], b[0]), ly = Math.min(a[1], b[1]), hy = Math.max(a[1], b[1]); + for (let i = 0; i < px.length; i++) if (px[i] >= lx && px[i] <= hx && py[i] >= ly && py[i] <= hy) chosen.add(c.m.ids[i]); + } else for (let i = 0; i < px.length; i++) if (inside(d.path, px[i], py[i])) chosen.add(c.m.ids[i]); + st.chosen = chosen; st.form = false; st.kept = null; chosenBar(c); + c.live.textContent = count(chosen.size, 'record') + ' chosen.'; + } + paint(c); + }; + cv.addEventListener('pointerup', end); + cv.addEventListener('pointercancel', () => { c.drag = null; paint(c); }); + cv.addEventListener('pointerleave', () => hover(c, null)); + cv.addEventListener('keydown', e => { + if (!c.m || !c.pts) return; + const dirs = { ArrowLeft: [-1, 0], ArrowRight: [1, 0], ArrowUp: [0, -1], ArrowDown: [0, 1] }; + if (e.key === 'Enter' && c.hover != null) { e.preventDefault(); open(c, c.m.ids[c.hover]); return; } + if (e.key === 'Escape' && st.chosen.size) { st.chosen = new Set(); chosenBar(c); paint(c); return; } + const d = dirs[e.key]; if (!d) return; + e.preventDefault(); e.stopPropagation(); + const { px, py } = c.pts, from = c.hover != null ? c.hover : st.opened != null && c.m.at.has(st.opened) ? c.m.at.get(st.opened) : null; + let best = null, bd = Infinity; + for (let i = 0; i < px.length; i++) { + if (from == null) { const dd = (px[i] - c.canvas.width / 2) ** 2 + (py[i] - c.canvas.height / 2) ** 2; if (dd < bd) { bd = dd; best = i; } continue; } + if (i === from) continue; + const dx = px[i] - px[from], dy = py[i] - py[from], along = dx * d[0] + dy * d[1]; if (along <= 0) continue; + const across = Math.abs(dx * d[1] - dy * d[0]), score = along + 2 * across; if (score < bd) { bd = score; best = i; } + } + if (best != null) { hover(c, best); c.live.textContent = c.m.ids[best] + (c.m.col ? ', ' + valueWord(c, best) : '') + '.'; } + }); + } + function hover(c, i, e) { + c.hover = i; clearTimeout(c.rest); + if (i == null) { c.tip.hidden = true; return; } + const dpr = window.devicePixelRatio || 1; + c.tip.textContent = ''; c.tip.appendChild(h('b', 'mono', c.m.ids[i])); const w = valueWord(c, i); if (w) c.tip.appendChild(h('span', null, w)); + c.tip.style.left = Math.round(c.pts.px[i] / dpr + 10) + 'px'; c.tip.style.top = Math.round(c.pts.py[i] / dpr + 10) + 'px'; c.tip.hidden = false; + const id = c.m.ids[i]; + c.rest = setTimeout(() => { if (c.hover === i && c.ctx.live()) c.ctx.show(id, c.set.records_run); }, REST_MS); + void e; + } + /** Opens a record: the viewer shows it, the map rings it, More like this lists its neighbours. */ + function open(c, id) { + c.st.opened = id; c.ctx.show(id, c.set.records_run); + c.st.list = 'like'; lists(c); paint(c); + } + + // ---- What is chosen --------------------------------------------------------------------------------------------------- + function chosenBar(c) { + const st = c.st, box = h('div'), n = st.chosen.size; + if (st.kept) box.appendChild(h('p', 'small good-line', 'Kept ' + st.kept + ' as an unsaved edit; Save writes it to the project folder. Building it is planned as any build is.')); + if (!n) { box.appendChild(h('p', 'small muted', 'Drag with Box or Lasso to choose records (Shift adds to them).')); putInPlace(c.selBar, box); return; } + const line = h('div', 'cur-chosen-line'); line.appendChild(h('b', 'cur-count', count(n, 'record') + ' chosen')); + const ordered = () => c.m.ids.filter(id => st.chosen.has(id)); + if (A.may('edit')) { + line.appendChild(button('btn sm', 'New dataset from these', 'cur-new', () => { st.form = !st.form; chosenBar(c); })); + line.appendChild(button('btn sm', 'Freeze these', 'cur-freeze', () => { + if (n > SELECT_LIMIT) { st.form = false; putInPlace(c.selBar, refusalBox('At most ' + SELECT_LIMIT.toLocaleString('en-GB') + ' records can be frozen by name; ' + n.toLocaleString('en-GB') + ' are chosen.')); return; } + window.LabAnnotate.fillFreeze(c.ctx.ref, ordered()); c.ctx.act.go('data', 'new:freeze'); + })); + } + line.appendChild(button('btn sm ghost', 'Clear', 'cur-clear', () => { st.chosen = new Set(); st.form = false; chosenBar(c); paint(c); })); + box.appendChild(line); + if (st.form && A.may('edit')) box.appendChild(newForm(c, ordered)); + putInPlace(c.selBar, box); + } + const refusalBox = text => A.refusal(Object.assign(Error(text), { code: 'invalid' })); + function newForm(c, ordered) { + const F = window.LabAnnotate.forms, key = 'curnew', s = A.slot(key), f = h('div', 'form cur-form'); + let nameBox = null; + f.appendChild(F.input(s, key, 'title', 'Title (required)', { max: 200, onInput: () => { if (!s.text.nameTyped && nameBox) { nameBox.value = F.slug(s.text.title || ''); s.text.name = nameBox.value; } } })); + const nl = F.input(s, key, 'name', 'Name', { max: 120, hint: 'the file is datasets/<name>.json', placeholder: 'made from the title', onInput: v => { s.text.nameTyped = !!v; } }); + nameBox = nl.querySelector('input'); if (!s.text.nameTyped) { nameBox.value = F.slug(s.text.title || ''); s.text.name = nameBox.value; } + f.appendChild(nl); + f.appendChild(h('p', 'small faint', 'A dataset of exactly these ' + count(c.st.chosen.size, 'record') + ' of ' + c.ctx.ref + ', in its order, each as it is there (its split and annotations kept): the step select.')); + f.appendChild(A.group(key, [ + { id: 'keep', label: 'Keep', cls: 'btn primary', who: 'edit', op: 'set_definition', busy: 'Keeping…', + args: st => { + const ids = ordered(); + if (ids.length > SELECT_LIMIT) throw Object.assign(Error('At most ' + SELECT_LIMIT.toLocaleString('en-GB') + ' records can be selected by name; ' + ids.length.toLocaleString('en-GB') + ' are chosen.'), { code: 'invalid' }); + const doc = { format: FORMAT, kind: 'dataset', title: (st.text.title || '').trim(), run: { step: 'select', inputs: { records: c.ctx.ref }, settings: { records: ids } } }; + return { reference: 'datasets/' + (st.text.name || '').trim(), text: F.textOf(doc) }; + }, + done: r => { c.st.kept = r.reference; c.st.form = false; } }, + { id: 'back', label: 'Cancel', cls: 'btn ghost', onClick: () => { c.st.form = false; chosenBar(c); } }])); + return f; + } + + // ---- The lists ------------------------------------------------------------------------------------------------------ + const LISTS = [['like', 'More like this'], ['duplicates', 'Duplicates'], ['outliers', 'Outliers'], ['leakage', 'Leakage'], ['thin', 'Thin regions']]; + function lists(c) { + const st = c.st, box = h('div'); + const seg = h('div', 'seg cur-tabs'); seg.setAttribute('role', 'group'); seg.setAttribute('aria-label', 'Lists'); + const shown = LISTS.filter(([id]) => id !== 'leakage' || c.m.colours.includes('split')); + if (!shown.some(([id]) => id === st.list)) st.list = 'duplicates'; + for (const [id, label] of shown) { const b = button(null, label, 'cur-list-' + id, () => { if (st.list !== id) { st.list = id; lists(c); } }); b.setAttribute('aria-pressed', String(st.list === id)); seg.appendChild(b); } + box.appendChild(seg); + const body = h('div', 'cur-list'); body.dataset.list = st.list; box.appendChild(body); + putInPlace(c.lists, box); + fillList(c, body); + } + function rowButton(c, key, parts, onClick) { + const li = h('li'), b = button('row cur-row', null, key, onClick); + for (const [cls, text] of parts) b.appendChild(h('span', cls, text)); + li.appendChild(b); return li; + } + const status = r => r.complete ? 'Every one of the ' + count(r.rows, 'record') + ' was examined.' : count(r.examined, 'record') + ' of ' + r.rows.toLocaleString('en-GB') + ' were examined within the search\'s bound; what is listed is exact for those.'; + function numberControl(c, label, name, min, max, step) { + const l = h('label', 'cur-num'); l.appendChild(document.createTextNode(label + ' ')); + const i = h('input'); i.type = 'number'; i.min = String(min); i.max = String(max); i.step = String(step); i.value = c.st[name]; i.dataset.key = 'cur-' + name; + i.addEventListener('change', () => { const v = Number(i.value); if (Number.isFinite(v) && v >= min && v <= max) { c.st[name] = i.value; lists(c); } }); + l.appendChild(i); return l; + } + async function fillList(c, body) { + const st = c.st, set = c.set, controls = h('div', 'cur-controls'), ul = h('ul', 'rows cur-rows'), note = h('p', 'small muted'); + const done = () => { if (body.isConnected) { const f = document.createDocumentFragment(); f.appendChild(controls); f.appendChild(note); f.appendChild(ul); putInPlace(body, f); } }; + body.appendChild(h('p', 'note', 'Reading…')); + try { + if (st.list === 'like') { + if (st.opened == null) { note.textContent = 'Open a record (click it on the map, or a row of a list) to see the records most like it.'; c.like = []; return done(); } + const r = await P.read('embedding_neighbours', { ...base(set), record: st.opened, limit: 12 }); + c.like = r.neighbours; paint(c); + note.textContent = 'The ' + r.neighbours.length + ' records most like ' + r.record + ', by cosine.'; + for (const n of r.neighbours) ul.appendChild(rowButton(c, 'cur-like-' + n.id, [['title mono', n.id], ['sub', [n.split, n.kind].filter(Boolean).join(' · ')], ['num', cos(n.cosine)]], () => open(c, n.id))); + } else if (st.list === 'duplicates') { + controls.appendChild(numberControl(c, 'Cosine at least', 'dup', 0.5, 1, 0.001)); + const r = await P.read('embedding_duplicates', { ...base(set), threshold: Number(st.dup), limit: 200 }); + note.textContent = (r.total ? count(r.total, 'pair') + ' (' + count(r.groups, 'record') + ')' : 'No pair') + ' at or above ' + r.threshold + '. ' + status(r); + for (const p of r.pairs) ul.appendChild(rowButton(c, 'cur-dup-' + p.a + '-' + p.b, [['title mono', p.a + ' ≈ ' + p.b], ['sub', [p.a_split, p.b_split].filter(Boolean).join(' · ')], ['num', cos(p.cosine)]], () => { st.chosen = new Set([p.a, p.b]); chosenBar(c); open(c, p.a); })); + } else if (st.list === 'outliers') { + controls.appendChild(numberControl(c, 'Neighbour', 'k', 1, 50, 1)); + const r = await P.read('embedding_outliers', { ...base(set), k: Number(st.k), limit: 50 }); + note.textContent = 'Farthest from their ' + ordinal(r.k) + ' nearest record' + (r.median != null ? '; the median distance is ' + r.median.toFixed(4) : '') + '. ' + status(r); + for (const o of r.outliers) ul.appendChild(rowButton(c, 'cur-out-' + o.id, [['title mono', o.id], ['sub', 'nearest ' + o.nearest + (o.split ? ' · ' + o.split : '')], ['num', o.distance.toFixed(4)]], () => open(c, o.id))); + } else if (st.list === 'leakage') { + controls.appendChild(numberControl(c, 'Cosine at least', 'leak', 0.5, 1, 0.001)); + const splits = c.m.colour && c.m.colour.by === 'split' ? c.m.colour.categories.map(x => x.name) : [st.train]; + const l = h('label', 'cur-num'); l.appendChild(document.createTextNode('Trained on ')); const sel = h('select'); sel.dataset.key = 'cur-train'; + for (const s of new Set([st.train, ...splits])) { const o = h('option', null, s); o.value = s; o.selected = s === st.train; sel.appendChild(o); } + sel.addEventListener('change', () => { st.train = sel.value; lists(c); }); l.appendChild(sel); controls.appendChild(l); + const r = await P.read('embedding_leakage', { ...base(set), threshold: Number(st.leak), train: st.train, limit: 200 }); + note.textContent = !Object.keys(r.splits).length ? 'The records have no splits.' : (r.leaked ? count(r.leaked, 'record') + ' outside ' + r.train + ' ' + (r.leaked === 1 ? 'has' : 'have') + ' a near-copy in it' : 'No record outside ' + r.train + ' has a near-copy in it') + ' at or above ' + r.threshold + '. ' + status(r); + for (const p of r.pairs) ul.appendChild(rowButton(c, 'cur-leak-' + p.record, [['title mono', p.record + ' ≈ ' + p.near], ['sub', p.split + ' · ' + r.train], ['num', cos(p.cosine)]], () => { st.chosen = new Set([p.record, p.near]); chosenBar(c); open(c, p.record); })); + } else { + const m = c.m; + note.textContent = m.thin.length ? count(m.thin.length, 'cell') + ' of the map\'s ' + m.grid.cells + ' × ' + m.grid.cells + ' hold few records: at most a quarter of the median of the cells that hold any. A row chooses its records.' : 'No cell of the map is thin.'; + for (const t of m.thin) ul.appendChild(rowButton(c, 'cur-thin-' + t.cell.join('-'), [['title', 'Cell ' + (t.cell[1] + 1) + ', ' + (t.cell[0] + 1)], ['sub mono', t.records.slice(0, 4).join(', ') + (t.count > 4 ? ', …' : '')], ['num', String(t.count)]], () => { st.chosen = new Set(t.records); chosenBar(c); paint(c); })); + } + } catch (error) { controls.appendChild(A.refusal(error)); } + done(); + } + const ordinal = n => n + (n % 100 >= 11 && n % 100 <= 13 ? 'th' : ['th', 'st', 'nd', 'rd'][n % 10] || 'th'); + + // ---- Data: the Embed form ------------------------------------------------------------------------------------------ + /** Embed: a new datasets/<name> whose run is the step embed, kept as an unsaved edit. */ + function form(aside, act) { + const F = window.LabAnnotate.forms; + F.formDrawer(aside, 'data:new:embed', () => Promise.all([P.read('endpoint').catch(error => ({ error })), P.read('definitions', { kind: 'dataset' })]), (ins, [ep, defs]) => { + const key = 'newembed', s = A.slot(key), em = ep.embedder || null; + F.header(ins, 'new dataset · embed', 'Embed a dataset', + 'A vector for each text and image record of a dataset, asked of an embedding model the Pumas endpoint serves, written as embeddings Tuldok draws as a map. When the definition names no model, the machine\'s embedder is used: EmbeddingGemma 2 unless the owner set another.'); + const embedders = em ? em.embedders : []; + if (ep.error || !ep.address || !ep.answered || !embedders.length) { + const why = h('div', 'gen-none'); why.setAttribute('role', 'status'); + why.appendChild(h('p', 'failure', ep.error ? 'What the endpoint serves could not be read: ' + ep.error.message + : !ep.address ? 'No Pumas endpoint is set on this machine, so there is nothing to embed with.' + : !ep.answered ? 'The Pumas endpoint at ' + ep.address + ' does not answer: ' + (ep.problem || 'no reason was given.') + : 'The Pumas endpoint at ' + ep.address + ' serves no embedding model now.')); + const acts = h('div', 'actions'); acts.appendChild(button('btn', 'The endpoint on the Train tab', 'emb:endpoint', () => act.go('train', 'endpoint'))); acts.appendChild(button('btn ghost', 'Cancel', 'emb:cancel', () => act.select(null))); + why.appendChild(acts); ins.appendChild(why); return; + } + const sets = defs.definitions.filter(d => !d.removed), f = h('div', 'form emb-form'); + let nameBox = null; + f.appendChild(F.input(s, key, 'title', 'Title (required)', { max: 200, onInput: () => { if (!s.text.nameTyped && nameBox) { nameBox.value = F.slug(s.text.title || ''); s.text.name = nameBox.value; } } })); + const nl = F.input(s, key, 'name', 'Name', { max: 120, hint: 'the file is datasets/<name>.json', placeholder: 'made from the title', onInput: v => { s.text.nameTyped = !!v; } }); + nameBox = nl.querySelector('input'); if (!s.text.nameTyped) { nameBox.value = F.slug(s.text.title || ''); s.text.name = nameBox.value; } + f.appendChild(nl); + if (!sets.length) f.appendChild(h('p', 'failure', 'The project has no dataset to embed.')); + else f.appendChild(F.choice(s, key, 'dataset', 'The dataset whose records are embedded', sets.map(d => [d.reference, d.title + ' · ' + d.reference]), sets[0].reference)); + const named = em.named_by === 'setting' ? 'this machine\'s embedder, ' + em.model : 'EmbeddingGemma 2'; + const resolved = em.chosen ? em.chosen.model + ' · ' + em.chosen.profile + ' (' + em.chosen.model_id + ')' : 'not served now'; + const options = [['', 'Default: ' + named + ' → ' + resolved]].concat(embedders.map(x => [x.model + '\u0000' + x.profile, x.model + ' · ' + x.profile + ' (' + x.model_id + ')'])); + f.appendChild(F.choice(s, key, 'model', 'Model', options, '')); + const line = h('p', 'small faint emb-line'); line.dataset.key = 'emb-default'; + line.textContent = em.chosen ? 'With the default, the definition names no model: a build uses ' + named + ' as this machine resolves it then (now ' + resolved + '). Choose a model to write it into the definition.' + : 'The default embedder cannot be used now: ' + (em.problem || 'it is not served.') + ' Choose a served model, or the owner sets the machine\'s embedder on the Train tab.'; + f.appendChild(line); + f.appendChild(F.input(s, key, 'prefix', 'Prefix', { max: 1000, value: em.prefix, hint: 'put before each text; EmbeddingGemma expects a task, such as “task: clustering | query: ”. Unchanged, it is not written and the machine\'s applies.' })); + const two = h('div', 'two'); + const bound = (embedders.find(x => x.model + '\u0000' + x.profile === s.text.model) || em.chosen && embedders.find(x => x.model === em.chosen.model && x.profile === em.chosen.profile) || {}).dimensions; + const dims = F.input(s, key, 'dimensions', 'Dimensions', { type: 'number', hint: bound ? 'empty: the model\'s own; ' + bound.minimum + ' to ' + bound.maximum + ' (truncated by Pumas)' : 'empty: the model\'s own; Pumas truncates to fewer' }); + dims.querySelector('input').min = '1'; dims.querySelector('input').max = String(bound ? bound.maximum : 4096); two.appendChild(dims); + const batch = F.input(s, key, 'batch', 'Batch', { type: 'number', hint: 'records a request carries; empty: 32' }); batch.querySelector('input').min = '1'; batch.querySelector('input').max = '256'; two.appendChild(batch); + f.appendChild(two); + ins.appendChild(f); + ins.appendChild(A.group(key, [ + { id: 'keep', label: 'Keep', cls: 'btn primary', who: 'edit', op: 'set_definition', busy: 'Keeping…', + args: st => ({ reference: 'datasets/' + (st.text.name || '').trim(), text: F.textOf(embedDoc(st.text, em)) }), done: r => { act.select(r.reference); } }, + { id: 'back', label: 'Cancel', cls: 'btn ghost', onClick: () => act.select(null) }])); + ins.appendChild(h('p', 'note', 'Keep checks the definition and keeps it in Tuldok as an unsaved edit; Save writes it. Building it is planned and requested as any build is.')); + }); + } + function whole(text, label, min, max) { + const raw_ = String(text == null ? '' : text).trim(); if (!raw_) return null; + const v = Number(raw_); if (!Number.isInteger(v) || v < min || v > max) throw Object.assign(Error(label + ' is a whole number from ' + min + ' to ' + max + '; "' + raw_ + '" is not.'), { code: 'invalid' }); + return v; + } + /** The definition an embed writes (docs/contracts/project-folder.md, Steps Tuldok provides). */ + function embedDoc(x, em) { + const settings = {}; + if (x.model) { const [model, profile] = x.model.split('\u0000'); settings.model = model; if (em.embedders.filter(e => e.model === model).length > 1) settings.profile = profile; } + if (x.prefix != null && x.prefix !== em.prefix) settings.prefix = x.prefix; + const d = whole(x.dimensions, 'Dimensions', 1, 4096); if (d !== null) settings.dimensions = d; + const b = whole(x.batch, 'Batch', 1, 256); if (b !== null) settings.batch = b; + return { format: FORMAT, kind: 'dataset', title: (x.title || '').trim(), run: { step: 'embed', inputs: { records: x.dataset }, settings } }; + } + + // ---- Train: the machine's embedder in the endpoint's drawer ----------------------------------------------------------- + /** The embedder part of the endpoint's drawer (generate.js): what it resolves to; for the owner, a model and prefix to set. */ + function embedderPart(ins, ep) { + const em = ep.embedder; if (!em) return; + const part = h('div', 'ep-part emb-part'); part.appendChild(h('h3', null, 'Embedder')); + const dl = h('dl', 'setup'); const put = (k, v) => { dl.appendChild(h('dt', null, k)); dl.appendChild(h('dd', null, v)); }; + put('Named by', em.named_by === 'setting' ? 'this machine: ' + em.model + (em.profile ? ' · ' + em.profile : '') : 'the default, EmbeddingGemma 2'); + put('Resolves to', em.chosen ? em.chosen.model + ' · ' + em.chosen.profile + ' (' + em.chosen.model_id + ')' : 'nothing now'); + put('Prefix', em.prefix ? '“' + em.prefix + '”' : 'none'); + part.appendChild(dl); + if (em.problem && ep.address) part.appendChild(h('p', 'small warnline', em.problem)); + if (A.may('owner')) { + const key = 'endpoint:embedder', s = A.slot(key), F = window.LabAnnotate.forms, f = h('div', 'form'); + const options = [['', 'EmbeddingGemma 2 (the default)']].concat(em.embedders.map(x => [x.model + '\u0000' + x.profile, x.model + ' · ' + x.profile + ' (' + x.model_id + ')'])); + if (s.text.model == null) s.text.model = em.model ? em.model + '\u0000' + (em.profile || (em.chosen ? em.chosen.profile : '')) : ''; + f.appendChild(F.choice(s, key, 'model', 'Embed with, when a definition names no model', options, '')); + f.appendChild(F.input(s, key, 'prefix', 'Prefix', { max: 1000, value: em.prefix })); + f.appendChild(A.group(key, [{ id: 'set', label: 'Set the embedder', cls: 'btn', who: 'owner', op: 'set_embedder', busy: 'Checking…', + args: st => { const [model, profile] = (st.text.model || '').split('\u0000'); const several = model && em.embedders.filter(e => e.model === model).length > 1; return { model: model || null, profile: several ? profile : null, prefix: st.text.prefix == null ? em.prefix : st.text.prefix }; } }])); + part.appendChild(f); + } + ins.appendChild(part); + } + + return { sets, usable, panel, form, embedderPart }; +})(); diff --git a/static/project-workspace/generate.js b/static/project-workspace/generate.js index b5814394..ae0c8639 100644 --- a/static/project-workspace/generate.js +++ b/static/project-workspace/generate.js @@ -103,6 +103,7 @@ window.LabGenerate = (() => { ins.appendChild(dl); ins.appendChild(h('p', 'note', 'The address is kept in Tuldok\'s settings file on this machine, never in the project folder. Generation and suggestions go to it over HTTP; nothing of Pumas runs inside Tuldok.')); ins.appendChild(A.group('endpoint:again', [{ id: 'again', label: 'Ask it again', cls: 'btn sm', onClick: () => { P.forget(['endpoint']); act.refresh(); } }])); + if (window.LabCuration) window.LabCuration.embedderPart(ins, ep); // the machine's embedder (spec-t5 section 2) if (!A.may('owner')) { ins.appendChild(h('p', 'note', 'Only the owner of this Tuldok sets the endpoint.')); return; } const set = h('div', 'ep-part'); set.appendChild(h('h3', null, ep.address ? 'Set another address' : 'Set the address')); set.appendChild(h('p', 'note', 'A numeric loopback HTTP address, such as http://127.0.0.1:8765, without a path. Tuldok asks it once what it serves and keeps it only when it answers.')); diff --git a/static/project-workspace/inside.js b/static/project-workspace/inside.js index 2ce407d1..46409f7c 100644 --- a/static/project-workspace/inside.js +++ b/static/project-workspace/inside.js @@ -126,6 +126,10 @@ window.LabInside = (() => { const products = prods.products.filter(p => p.run_id); if (!products.length) return { def, products }; const product = products.find(p => p.run_id === v.run) || products[0]; v.run = product.run_id; + // The dataset's embeddings (curation.js, spec-t5): with any that can be read, Map joins Records and Files. + const em = window.LabCuration ? await window.LabCuration.sets(c.ref) : null; + const mapped = !!em && window.LabCuration.usable(em).length > 0; + if (v.mode === 'map' && !mapped) v.mode = 'records'; const args = { offset: v.page * PER_PAGE, limit: PER_PAGE, kind: v.kind, split: v.split }; let page = await R.records(v.run, args); if (!page.records.length && v.page > 0 && page.total) { v.page = Math.floor((page.total - 1) / PER_PAGE); args.offset = v.page * PER_PAGE; page = await R.records(v.run, args); } @@ -133,9 +137,9 @@ window.LabInside = (() => { if (v.mode === 'files') tree = await R.inside(v.run, { path: v.path, offset: v.treeOffset, limit: TREE_LIMIT }).catch(error => ({ error })); if (v.mode === 'records' && !page.records.some(r => r.id === v.sel)) v.sel = page.records.length ? page.records[v.selAt === -1 ? page.records.length - 1 : 0].id : null; v.selAt = 0; - const target = v.mode === 'files' ? v.treeTarget : v.sel ? { record: v.sel } : null; + const target = v.mode === 'files' ? v.treeTarget : v.mode === 'map' ? v.mapTarget || null : v.sel ? { record: v.sel } : null; const viewer = target ? await viewerFor(c, v, target) : null; - return { def, products, product, page, tree, viewer }; + return { def, products, product, page, tree, viewer, em, mapped }; } /** Draws the whole view (first: not on screen yet), built off the page and put in place in one step. */ @@ -184,7 +188,7 @@ window.LabInside = (() => { // The Files switch, the kinds and the splits as filters. const bar = h('div', 'filters'); const seg = h('div', 'seg'); seg.setAttribute('role', 'group'); seg.setAttribute('aria-label', 'Show'); - for (const [mode, label] of [['records', 'Records'], ['files', 'Files']]) { const b = button(null, label, () => { if (v.mode !== mode) { v.mode = mode; draw(c, false); } }); b.setAttribute('aria-pressed', String(v.mode === mode)); b.dataset.key = 'inside-mode-' + mode; seg.appendChild(b); } + for (const [mode, label] of [['records', 'Records'], ['files', 'Files']].concat(got.mapped ? [['map', 'Map']] : [])) { const b = button(null, label, () => { if (v.mode !== mode) { v.mode = mode; draw(c, false); } }); b.setAttribute('aria-pressed', String(v.mode === mode)); b.dataset.key = 'inside-mode-' + mode; seg.appendChild(b); } bar.appendChild(seg); if (v.mode === 'records') { const all = Object.values(page.kinds).reduce((a, b) => a + b, 0); @@ -193,12 +197,15 @@ window.LabInside = (() => { if (splits.length) bar.appendChild(chips('Split', [[null, 'All', null]].concat(splits.map(([s, n]) => [s, s, n])), v.split, s => { v.split = s; v.page = 0; v.sel = null; draw(c, false); }, 'split')); } root.appendChild(bar); - const body = h('div', 'ds-body'); + const body = h('div', 'ds-body' + (v.mode === 'map' ? ' cur-body' : '')); const left = h('div', 'inside-list'); - if (v.mode === 'records') records(c, v, page, left); else files(c, v, tree, left); + if (v.mode === 'records') records(c, v, page, left); + else if (v.mode === 'map') left.appendChild(window.LabCuration.panel({ ref: c.ref, em: got.em, act: c.act, live: () => here(c), + show: (id, run) => { v.mapTarget = { record: id, run }; showIn(c, v, v.mapTarget); } })); + else files(c, v, tree, left); body.appendChild(left); const panel = h('section', 'viewer'); panel.setAttribute('aria-label', 'Viewer'); - panel.appendChild(got.viewer || h('p', 'empty', v.mode === 'files' ? 'Choose a file or an array in the tree.' : 'Choose a record.')); + panel.appendChild(got.viewer || h('p', 'empty', v.mode === 'files' ? 'Choose a file or an array in the tree.' : v.mode === 'map' ? 'Rest on a point, or open one, to see its record.' : 'Choose a record.')); body.appendChild(panel); root.appendChild(body); } function chips(label, items, value, pick, key) { @@ -356,9 +363,9 @@ window.LabInside = (() => { * {path, array, kind, arrays}. A refusal is shown as the server's sentence. */ async function viewerFor(c, v, target) { - const run = v.run, el = h('div', 'iv'); + const run = target.run || v.run, el = h('div', 'iv'); try { - if (target.record != null) await recordView(c, v, el, await R.record(run, target.record)); + if (target.record != null) await recordView(c, target.run ? { ...v, run } : v, el, await R.record(run, target.record)); else await placeView(c, v, el, target); } catch (error) { el.replaceChildren(heading(target.record != null ? target.record : target.path + (target.array ? ' · ' + target.array : ''), null)); diff --git a/static/project-workspace/tabs.js b/static/project-workspace/tabs.js index 68dfdb44..54180402 100644 --- a/static/project-workspace/tabs.js +++ b/static/project-workspace/tabs.js @@ -647,7 +647,8 @@ if (window.LabAnnotate) { head.appendChild(h('span', 'spacer')); head.appendChild(A.group('data:new', [ { id: 'import', label: 'Import files', cls: 'btn sm', who: 'edit', onClick: () => act.select(sel === 'new:import' ? null : 'new:import') }, { id: 'freeze', label: 'Freeze a dataset', cls: 'btn sm', who: 'edit', onClick: () => act.select(sel === 'new:freeze' ? null : 'new:freeze') }, - { id: 'generate', label: 'Generate', cls: 'btn sm', who: 'edit', hidden: !window.LabGenerate, onClick: () => act.select(sel === 'new:generate' ? null : 'new:generate') }], { inline: true })); } + { id: 'generate', label: 'Generate', cls: 'btn sm', who: 'edit', hidden: !window.LabGenerate, onClick: () => act.select(sel === 'new:generate' ? null : 'new:generate') }, + { id: 'embed', label: 'Embed', cls: 'btn sm', who: 'edit', hidden: !window.LabCuration, onClick: () => act.select(sel === 'new:embed' ? null : 'new:embed') }], { inline: true })); } frag.appendChild(head); if (!sets.length) { frag.appendChild(h('p', 'empty', 'The project defines no dataset.')); return; } const grid = h('div', 'ds-grid'); @@ -676,6 +677,7 @@ }); if (!sel) return closeDrawer(aside); if (raw === 'new:generate' && window.LabGenerate && window.LabAnnotate) { window.LabGenerate.form(aside, act); return true; } + if (raw === 'new:embed' && window.LabCuration && window.LabAnnotate) { window.LabCuration.form(aside, act); return true; } // spec-t5, curation.js if (raw.startsWith('new:') && window.LabAnnotate) { window.LabAnnotate.datasetForm(aside, raw.slice(4), act); return true; } if (E && E.owns(raw, data)) { E.drawer(aside, raw, act, data, 'data'); return true; } drawer(aside, sel, () => Promise.all([P.read('definition', { reference: sel }), P.read('products', { reference: sel })]), (ins, [d, p]) => { diff --git a/tests/browser_fake_pumas.py b/tests/browser_fake_pumas.py index 824d77b1..c577d4c2 100644 --- a/tests/browser_fake_pumas.py +++ b/tests/browser_fake_pumas.py @@ -13,6 +13,10 @@ A text dataset asked by text (generate) is answered "made: <the prompt>", an image a PNG of the asked size. Nothing else is contacted; it ends with stdin. + +With --embedders (tests/browser_project_workspace_curation.cjs) it also serves the embedders of +tests/test_tuldok_project_curation.py (embeddinggemma-2, the default embedder, and nomic-embed) and answers an +embeddings request with a vector made from each item. """ import io import json @@ -29,10 +33,16 @@ def main(): server, base, state = fake_pumas_typed.start() state['served_models'] = listing() + embedders = '--embedders' in sys.argv[1:] + if embedders: + from test_tuldok_project_curation import embed_respond, embedding_listing + state['served_models'] = embedding_listing() state['advertise'] = '0.8.0' said = {'answer': 'A short text.', 'answers': {}} def respond(body): + if embedders and body['output'] == 'embeddings_float32': + return embed_respond(body) if body['capability'] == 'decision': return {'kind': 'decisions', 'answers': said['answers'], 'input_tokens': 7} if body['capability'] == 'image_generation': diff --git a/tests/browser_project_workspace_curation.cjs b/tests/browser_project_workspace_curation.cjs new file mode 100644 index 00000000..f6280c05 --- /dev/null +++ b/tests/browser_project_workspace_curation.cjs @@ -0,0 +1,377 @@ +'use strict'; +// Curation by embeddings on the page (docs/plans/training-and-curation/spec-t5.md sections 6 and 8, slice T5c) in a +// headless browser, the owner signed in, no GPU. The fixture is a project of its own in Git: datasets/curated, whose +// command (tests/project_curation_browser_fixture.py, standard library only) writes 244 texts with splits and the +// embeddings a script would write beside them, with near-duplicates planted in train, one validation record that is a +// near-copy of a training one and one record far from everything; annotations/quality, a class task on it; and +// datasets/notes, three texts imported. The machine's Pumas endpoint is a fake this check starts +// (tests/browser_fake_pumas.py --embedders: the vision fixture's models, embeddinggemma-2 and nomic-embed); no real +// Pumas is contacted, and nothing here builds an embed (test_tuldok_project_curation does, against the same fake). +// 1. The dataset opened shows Map beside Records and Files; the map is drawn, coloured by split (the legend's counts +// and the canvas's colours), and by a field when chosen. +// 2. Duplicates lists the three planted pairs; Leakage lists the leaked validation record alone; Outliers puts the far +// record first; a pair pressed opens its record (the viewer shows it) and More like this lists its copy first. +// 3. A box dragged on the map chooses exactly the records the test computes from embedding_map; "New dataset from +// these" keeps a select definition holding exactly those ids; "Freeze these" opens the Freeze form filled in, and +// its Keep writes them as records. +// 4. The Embed form shows EmbeddingGemma 2 as the default model, resolved to the served embeddinggemma-2, and keeps an +// embed definition; the endpoint's drawer shows the embedder. +// 5. With the map open, a record opened and points chosen, the window regaining focus and a reading on the timer add, +// remove and change no node. +// 6. Light and dark at 1440 by 900 and 390 by 844: nothing in the map or the drawer overflows sideways (the page's +// own overflow at 390, which is not this phase's, is recorded). +// It fails on any script error and on any failed request. +// node tests/browser_project_workspace_curation.cjs [--shots <dir>] +const assert = require('node:assert/strict'), fs = require('node:fs'), os = require('node:os'), path = require('node:path'), readline = require('node:readline'); +const { spawn, execFileSync } = require('node:child_process'), { once } = require('node:events'); +const { authenticatedFixture } = require('./auth_helpers.cjs'), { waitForDebugger } = require('./browser_startup.cjs'), { cdpSession } = require('./browser_cdp_session.cjs'), { qaDirectory } = require('./qa_artifacts.cjs'); + +const root = path.resolve(__dirname, '..'); +const argv = process.argv.slice(2), option = name => { const i = argv.indexOf(name); return i >= 0 ? argv[i + 1] : null; }; +assert.ok(process.env.TULDOK_DATABASE_URL, 'TULDOK_DATABASE_URL must name a disposable PostgreSQL cluster'); +const venv = path.join(root, '.venv', 'bin'); +if (fs.existsSync(path.join(venv, 'python'))) process.env.PATH = venv + path.delimiter + process.env.PATH; // auth_helpers runs python3 +const python = fs.existsSync(path.join(venv, 'python')) ? path.join(venv, 'python') : 'python3'; +const IDLE_MS = 15000; // the page's reading while nothing builds (app.js) +const WATCHED = ['summary', 'status', 'build_requests', 'environments', 'runs']; + +const temporary = fs.mkdtempSync(path.join(os.tmpdir(), 'tuldok-curation-browser-')); +const report = qaDirectory(root, 'project-workspace-curation'); +const shots = option('--shots') ? path.resolve(option('--shots')) : null; if (shots) fs.mkdirSync(shots, { recursive: true }); +const children = [], checks = [], errors = [], failures = []; +let server, serverErrors = '', origin, auth, socket, session, send, evaluate, owned = null, fake = null, fakeLines = null; +const pause = ms => new Promise(resolve => setTimeout(resolve, ms)); +async function until(fn, label, tries = 300) { for (let i = 0; i < tries; i++) { const value = await fn(); if (value) return value; await pause(100); } throw Error('Timed out: ' + label); } +function check(text) { checks.push(text); console.log('PASS ' + text); } +function launch(command, args, options) { const child = spawn(command, args, options); children.push(child); return child; } +async function stop(child) { if (!child || child.exitCode !== null || child.signalCode !== null) return; const exited = once(child, 'exit'); child.kill('SIGTERM'); await Promise.race([exited, pause(10000)]); if (child.exitCode === null && child.signalCode === null) { child.kill('SIGKILL'); await exited; } } +function findBrowser() { + const candidates = [process.env.BROWSER, '/usr/bin/chromium', '/usr/bin/chromium-browser', '/usr/bin/google-chrome']; + const cache = path.join(os.homedir(), '.cache', 'ms-playwright'); + if (fs.existsSync(cache)) for (const name of fs.readdirSync(cache).filter(n => n.startsWith('chromium_headless_shell-')).sort().reverse()) candidates.push(path.join(cache, name, 'chrome-headless-shell-linux64', 'chrome-headless-shell')); + const found = candidates.find(candidate => candidate && fs.existsSync(candidate)); + assert.ok(found, 'No headless browser: set BROWSER'); + return found; +} +/** Drops the project's schema and the catalog's from the disposable database, so each run imports afresh. */ +function dropOwned(folder, catalog) { + const id = JSON.parse(fs.readFileSync(path.join(folder, 'tuldok.json'), 'utf8')).id; + execFileSync(python, ['-c', `import json, os, pathlib, sys, psycopg +from psycopg import sql +from tuldok_project import store +store.drop_project(sys.argv[1], os.environ['TULDOK_DATABASE_URL']) +root = pathlib.Path(sys.argv[2]) +if root.exists(): + with psycopg.connect(os.environ['TULDOK_DATABASE_URL'], autocommit=True) as c: + for p in root.rglob('.tuldok.json'): + v = json.loads(p.read_text()) + name = 'projection_' + v['projection_id'] if v.get('version') == 2 else 'catalog_' + v['dataset_id'] + c.execute(sql.SQL('DROP SCHEMA IF EXISTS {} CASCADE').format(sql.Identifier(name))) +`, id, catalog], { cwd: root, stdio: ['ignore', 'pipe', 'pipe'] }); +} +async function contract(name) { + const capabilities = await (await auth.fetch(origin + '/api/agent/capabilities')).json(); + const operation = capabilities.operations.find(item => item.id === 'project.' + name), c = operation.contracts[operation.contracts.length - 1]; + return 'project.' + name + '/' + c.version + '/' + c.sha256; +} +/** An operation as the owner. */ +async function api(name, body = {}) { + const headers = { 'Content-Type': 'application/json', 'Tuldok-Operation-Contract': await contract(name) }; + const response = await auth.fetch(origin + '/api/project/' + name, { method: 'POST', headers, body: JSON.stringify(body) }); + const value = await response.json(); assert.equal(response.status, 200, name + ': ' + JSON.stringify(value)); return value; +} +/** A command to the fake endpoint (tests/browser_fake_pumas.py), and its answer. */ +async function tell(command) { fake.stdin.write(JSON.stringify(command) + '\n'); const [line] = await once(fakeLines, 'line'); return JSON.parse(line); } + +// ---- The page's readings, from the browser's network (as browser_project_workspace_still.cjs) ---------------- +const calls = new Map(), finished = []; +function network(event) { + const p = event.params; + if (event.method === 'Network.requestWillBeSent' && /\/api\/project\/[a-z_]+$/.test(p.request.url)) calls.set(p.requestId, { name: p.request.url.split('/').pop(), sent: Date.now() }); + if ((event.method === 'Network.loadingFinished' || event.method === 'Network.loadingFailed') && calls.has(p.requestId)) { finished.push(Object.assign(calls.get(p.requestId), { done: Date.now() })); calls.delete(p.requestId); } +} +async function reading(since, names, label, tries = 300) { + await until(() => names.every(name => finished.some(f => f.name === name && f.sent >= since)), 'a reading: ' + label, tries); + await until(() => !calls.size && Date.now() - Math.max(0, ...finished.map(f => f.done)) > 700, 'the reading done: ' + label, 300); + await settled(label); +} +/** Waits until nothing reads: no call of the project in flight, no "Reading…", nothing busy. */ +async function settled(label) { + await until(async () => !calls.size && await evaluate(`(() => { const reading = e => [...e.querySelectorAll('.note')].some(n => n.textContent === 'Reading…'); return !reading(document.getElementById('main')) && !reading(document.getElementById('aside')) && !document.getElementById('main').hasAttribute('aria-busy') && !document.querySelector('.act-group [aria-busy]') && !document.querySelector('#main [data-key="ann:suggest"][aria-busy]'); })()`), 'settled: ' + label); + await pause(200); + await until(async () => !calls.size, 'settled again: ' + label); +} +async function hash(value) { await evaluate(`location.hash = ${JSON.stringify('#' + value)}`); await settled('#' + value); await pause(200); await settled('#' + value); } +const byKey = key => `[data-key=${JSON.stringify(key)}]`; +async function centre(selector) { + return until(() => evaluate(`(() => { const e = [...document.querySelectorAll(${JSON.stringify(selector)})].find(e => e.offsetParent !== null); if (!e) return null; e.scrollIntoView({ block: 'nearest', inline: 'nearest' }); const r = e.getBoundingClientRect(), x = r.left + r.width / 2, y = r.top + r.height / 2, hit = document.elementFromPoint(x, y); return hit && (hit === e || e.contains(hit)) ? { x, y } : null; })()`), 'shown: ' + selector, 100); +} +async function mouse(type, x, y, buttons = 0) { await send('Input.dispatchMouseEvent', { type, x, y, button: type === 'mouseMoved' ? (buttons ? 'left' : 'none') : 'left', buttons, clickCount: type === 'mouseMoved' ? 0 : 1 }); } +async function press(selector) { const { x, y } = await centre(selector); await mouse('mouseMoved', x, y); await mouse('mousePressed', x, y, 1); await mouse('mouseReleased', x, y); } +const KEYS = { Enter: 13, Escape: 27, Tab: 9 }; +async function key(name) { + const code = KEYS[name] || name.toUpperCase().charCodeAt(0), text = name.length === 1 ? name : name === 'Enter' ? '\r' : undefined; + await send('Input.dispatchKeyEvent', { type: text ? 'keyDown' : 'rawKeyDown', key: name, code: name.length === 1 ? 'Key' + name.toUpperCase() : name, windowsVirtualKeyCode: code, text }); + await send('Input.dispatchKeyEvent', { type: 'keyUp', key: name, windowsVirtualKeyCode: code }); +} +async function type(selector, text) { await press(selector); await evaluate(`(() => { const e = document.activeElement; if (e.select) e.select(); return true; })()`); await send('Input.insertText', { text }); } +/** Sets a select's value as a person would choose it, focused and with its change event (no popup is opened: a form that draws itself again on a change would leave an Escape to the page). */ +async function choose(selector, value) { await centre(selector); await evaluate(`(() => { const s = document.querySelector(${JSON.stringify(selector)}); s.focus(); s.value = ${JSON.stringify(value)}; s.dispatchEvent(new Event('change', { bubbles: true })); return true; })()`); } +async function shot(name) { + await evaluate('new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve)))'); + const png = Buffer.from((await send('Page.captureScreenshot', { format: 'png', captureBeyondViewport: false })).data, 'base64'); + fs.writeFileSync(path.join(report, name + '.png'), png); if (shots) fs.writeFileSync(path.join(shots, name + '.png'), png); +} +const text = selector => evaluate(`(() => { const e = document.querySelector(${JSON.stringify(selector)}); return e ? e.innerText : null; })()`); +const value = selector => evaluate(`(() => { const e = document.querySelector(${JSON.stringify(selector)}); return e ? e.value : null; })()`); +const options = selector => evaluate(`[...document.querySelectorAll(${JSON.stringify(selector + ' option')})].map(o => o.value)`); + + +const WATCHER = `window.__still = (() => { + const ids = ['tabs', 'strip', 'main', 'aside', 'needs-panel'], el = id => document.getElementById(id); + let counts = null, flash = 0, timer = null, observers = []; + const name = n => !n ? '?' : n.nodeType === 1 ? n.tagName.toLowerCase() + (typeof n.className === 'string' && n.className ? '.' + n.className.trim().split(/\\s+/).join('.') : '') : '#text ' + JSON.stringify(String(n.data || '').slice(0, 30)); + const watch = (key, node) => { const o = new MutationObserver(list => { + if (!counts) return; + const c = counts[key]; + for (const r of list) { + if (r.type === 'childList') { c.added += r.addedNodes.length; c.removed += r.removedNodes.length; for (const n of [...r.addedNodes, ...r.removedNodes]) if (c.what.length < 6) c.what.push(name(n) + ' in ' + name(r.target)); } + else if (r.type === 'characterData') { const msg = el('strip').querySelector('.msg'); if (msg && r.target === msg.lastChild) c.readAt++; else { c.text++; if (c.what.length < 6) c.what.push('text of ' + name(r.target.parentNode)); } } + else { c.attrs++; if (c.what.length < 6) c.what.push('@' + r.attributeName + ' on ' + name(r.target)); } + } + }); o.observe(node, { childList: true, subtree: true, characterData: true, attributes: true }); observers.push(o); }; + return { + start() { + for (const o of observers) o.disconnect(); observers = []; + counts = {}; for (const id of ids) counts[id] = { added: 0, removed: 0, attrs: 0, text: 0, readAt: 0, what: [] }; + for (const id of ids) { watch(id, el(id)); for (const e of el(id).querySelectorAll('*')) e.__seen = 1; } + flash = 0; clearInterval(timer); timer = setInterval(() => { if ((el('main').textContent + el('aside').textContent).includes('Reading…')) flash++; }, 50); + }, + stop() { clearInterval(timer); const fresh = {}; for (const id of ids) fresh[id] = [...el(id).querySelectorAll('*')].filter(e => !e.__seen).length; const r = { counts, flash, fresh }; counts = null; for (const o of observers) o.disconnect(); observers = []; return r; } + }; +})(); true`; + +const REF = 'datasets/curated'; +let folder; +(async () => { + // ---- The fake endpoint, the fixture and Tuldok --------------------------------------------------------------------- + fake = launch(python, [path.join(root, 'tests', 'browser_fake_pumas.py'), '--embedders'], { cwd: root, stdio: ['pipe', 'pipe', 'pipe'] }); + let fakeErrors = ''; fake.stderr.on('data', chunk => { fakeErrors += chunk; }); + fakeLines = readline.createInterface({ input: fake.stdout }); + const base = await Promise.race([once(fakeLines, 'line').then(([line]) => line.trim()), once(fake, 'exit').then(() => { throw Error('The fake endpoint exited: ' + fakeErrors); })]); + assert.match(base, /^http:\/\/127\.0\.0\.1:\d+$/); + + const repo = path.join(temporary, 'fixture'), code = path.join(repo, 'code'); folder = path.join(repo, 'project'); + for (const d of ['datasets', 'annotations', 'environments']) fs.mkdirSync(path.join(folder, d), { recursive: true }); + fs.mkdirSync(path.join(code, 'notes'), { recursive: true }); + fs.writeFileSync(path.join(folder, 'tuldok.json'), JSON.stringify({ format: 'tuldok_project_v1', id: require('node:crypto').randomUUID().replace(/-/g, ''), name: 'Curation check', code_root: '../code' }, null, 2) + '\n'); + fs.copyFileSync(path.join(root, 'tests', 'project_curation_browser_fixture.py'), path.join(code, 'make_curated.py')); + for (const [n, t] of [['a', 'Apples in a bowl.'], ['b', 'Boats in a bay.'], ['c', 'Cats on a wall.']]) fs.writeFileSync(path.join(code, 'notes', n + '.txt'), t + '\n'); + const doc = o => JSON.stringify(Object.assign({ format: 'tuldok_definition_v1' }, o), null, 2) + '\n'; + fs.writeFileSync(path.join(folder, 'environments', 'test-python.json'), doc({ kind: 'environment', title: 'The interpreter running the tests', python: '3.12', device: 'cpu', packages: { jsonschema: '4.26.0' } })); + fs.writeFileSync(path.join(folder, 'datasets', 'curated.json'), doc({ kind: 'dataset', title: 'Curated notes', description: 'Texts with splits and their embeddings, for curation.', run: { command: ['python', 'make_curated.py', '--out', '{output}'], environment: 'environments/test-python', sources: ['make_curated.py'] } })); + fs.writeFileSync(path.join(folder, 'datasets', 'notes.json'), doc({ kind: 'dataset', title: 'Three notes', run: { step: 'import', settings: { source: 'notes', rights: 'Written for this check; free to use.' } } })); + fs.writeFileSync(path.join(folder, 'annotations', 'quality.json'), doc({ kind: 'annotation', title: 'Quality', dataset: REF, task: 'class', vocabulary: ['good', 'bad'] })); + const git = ['-c', 'user.name=Tuldok Test', '-c', 'user.email=test@example.invalid', '-c', 'commit.gpgsign=false', '-c', 'init.defaultBranch=main', '-C', repo]; + execFileSync('git', [...git, 'init', '-q']); execFileSync('git', [...git, 'add', '-A']); execFileSync('git', [...git, 'commit', '-q', '-m', 'The fixture.']); + const home = process.env.TULDOK_PROJECT_HOME || path.join(temporary, 'home'), catalog = path.join(temporary, 'catalog'); fs.mkdirSync(home, { recursive: true }); + const settingsFile = process.env.TULDOK_SETTINGS || path.join(temporary, 'settings.json'); + fs.mkdirSync(path.dirname(settingsFile), { recursive: true }); fs.writeFileSync(settingsFile, JSON.stringify({ format: 'tuldok_settings_v1', pumas_endpoint: base }) + '\n', { mode: 0o600 }); + const env = { ...process.env, TULDOK_PROJECT_HOME: home, TULDOK_SETTINGS: settingsFile }; + owned = [folder, catalog]; dropOwned(folder, catalog); + const cli = (...args) => execFileSync(python, ['-m', 'tuldok_project', ...args], { cwd: root, env, stdio: ['ignore', 'pipe', 'pipe'] }).toString(); + assert.match(cli('check', folder), /^0 errors/m); + cli('connect', folder, 'test-python', python); + cli('build', folder, REF, '--yes'); cli('build', folder, 'datasets/notes', '--yes'); + let output = ''; + server = launch(python, ['-u', 'app.py', '--port', '0', '--data', catalog, '--project-folder', folder], { cwd: root, env, stdio: ['ignore', 'pipe', 'pipe'] }); + server.stdout.on('data', chunk => { output += chunk; }); server.stderr.on('data', chunk => { serverErrors += chunk; }); + const port = await until(() => { if (server.exitCode !== null) throw Error('Tuldok exited: ' + serverErrors); return output.match(/127\.0\.0\.1:(\d+)/)?.[1]; }, 'Tuldok start-up', 3000); + origin = 'http://127.0.0.1:' + port; + auth = authenticatedFixture(); await auth.register(origin, catalog, root); + const run = (await api('products', { reference: REF })).products[0].run_id; + + const browser = launch(findBrowser(), ['--headless', '--no-sandbox', '--disable-gpu', '--no-first-run', '--hide-scrollbars', '--remote-debugging-port=0', '--window-size=1440,900', '--user-data-dir=' + path.join(temporary, 'browser'), 'about:blank'], { stdio: 'ignore', env: { ...process.env, XDG_CONFIG_HOME: temporary, XDG_CACHE_HOME: temporary } }); + const debugPort = await waitForDebugger(browser, path.join(temporary, 'browser', 'DevToolsActivePort')); + const target = (await (await fetch('http://127.0.0.1:' + debugPort + '/json')).json()).find(item => item.type === 'page'); + socket = new WebSocket(target.webSocketDebuggerUrl); await once(socket, 'open'); + session = cdpSession(socket, { timeoutMs: 60000, onEvent: event => { + network(event); + if (event.method === 'Runtime.exceptionThrown') errors.push(event.params.exceptionDetails.exception?.description || event.params.exceptionDetails.text); + if (event.method === 'Runtime.consoleAPICalled' && event.params.type === 'error') errors.push(event.params.args.map(a => a.value ?? a.description).join(' ')); + if (event.method === 'Log.entryAdded' && event.params.entry.level === 'error') errors.push(event.params.entry.text + ' ' + (event.params.entry.url || '')); + if (event.method === 'Network.loadingFailed' && !event.params.canceled) failures.push({ id: event.params.requestId, error: event.params.errorText }); + if (event.method === 'Network.responseReceived' && event.params.response.status >= 400) failures.push({ url: event.params.response.url, status: event.params.response.status }); + } }); + send = session.send; + evaluate = async expression => { const result = await send('Runtime.evaluate', { expression, awaitPromise: true, returnByValue: true }); if (result.exceptionDetails) throw Error(JSON.stringify(result.exceptionDetails)); return result.result.value; }; + await send('Page.enable'); await send('Runtime.enable'); await send('Network.enable'); await send('Log.enable'); + const size = async (width, height) => send('Emulation.setDeviceMetricsOverride', { width, height, deviceScaleFactor: 1, mobile: false }); + const theme = async name => { await send('Emulation.setEmulatedMedia', { features: [{ name: 'prefers-color-scheme', value: name }, { name: 'prefers-reduced-motion', value: 'reduce' }] }); }; + await size(1440, 900); await theme('light'); + await auth.browser(send, origin); + const load = async (name, place) => { + await theme(name); + await send('Page.navigate', { url: 'about:blank' }); await pause(100); + await send('Page.navigate', { url: origin + '/?theme=' + name + '#' + place }); + await until(() => evaluate(`document.readyState === 'complete' && !!document.getElementById('needs-btn') && !document.getElementById('needs-btn').disabled`), 'the project read', 1200); + await settled('opened ' + place); + }; + const kept = async label => { await until(async () => !(await evaluate(`!!document.querySelector('.act-group [aria-busy]')`)), 'kept: ' + label); await settled(label); }; + const drawn = () => evaluate(`(() => { const c = document.querySelector('#main .cur-map canvas'); return c ? Number(c.dataset.drawn || 0) : 0; })()`); + const listRows = () => evaluate(`[...document.querySelectorAll('#main .cur-list .cur-row')].map(b => b.dataset.key)`); + const listShown = async (name, label) => { await until(() => evaluate(`(() => { const l = document.querySelector('#main .cur-list'); return !!l && l.dataset.list === ${JSON.stringify(name)} && !/^Reading…$/.test(l.innerText.trim()); })()`), label); await settled(label); }; + const openMap = async name => { + await load(name, 'data/inside%3A' + REF); + await press(byKey('inside-mode-map')); + await until(async () => (await drawn()) === 244, 'the map drawn'); + await listShown('duplicates', 'the duplicates listed'); + }; + /** Colours present on the map's canvas: how many of its pixels are each of the tokens named. */ + const colours = names => evaluate(`(() => { + const c = document.querySelector('#main .cur-map canvas'), d = c.getContext('2d').getImageData(0, 0, c.width, c.height).data; + const want = ${JSON.stringify(names)}.map(n => { const v = getComputedStyle(document.documentElement).getPropertyValue(n).trim(), x = parseInt(v.slice(1), 16); return [n, [x >> 16, (x >> 8) & 255, x & 255]]; }); + const found = Object.fromEntries(want.map(([n]) => [n, 0])); + for (let i = 0; i < d.length; i += 4) for (const [n, rgb] of want) if (d[i] === rgb[0] && d[i + 1] === rgb[1] && d[i + 2] === rgb[2]) found[n]++; + return found; })()`); + + // ---- 1. The map, coloured by split ------------------------------------------------------------------------------- + await openMap('light'); + assert.equal(await value(byKey('cur-colour')), 'split', 'Coloured by split first'); + const legend = await text('#main .cur-legend'); + for (const words of ['train · 195', 'validation · 25', 'test · 24']) assert.ok(legend.includes(words), 'The legend: ' + legend); + const bySplit = await colours(['--cat-1', '--cat-2', '--cat-3']); + assert.ok(bySplit['--cat-1'] > 50 && bySplit['--cat-2'] > 10 && bySplit['--cat-3'] > 10, 'The three splits\' colours are drawn: ' + JSON.stringify(bySplit)); + const facts = await text('#main .cur-facts'); + assert.match(facts, /244 records · 16 dimensions · stand-in · principal components/); + await choose(byKey('cur-colour'), 'field:topic'); + await until(async () => /boats · 40/.test(await text('#main .cur-legend') || ''), 'coloured by topic'); + const byTopic = await colours(['--cat-1', '--cat-2', '--cat-3', '--cat-4', '--cat-5', '--cat-6']); + assert.ok(Object.values(byTopic).every(n => n > 10), 'Six topics drawn: ' + JSON.stringify(byTopic)); + await choose(byKey('cur-colour'), 'split'); await until(async () => /train · 195/.test(await text('#main .cur-legend') || ''), 'back to split'); + check('1. The dataset opened shows Map; the map draws 244 records ("' + facts.slice(0, 90) + '…") coloured by split (' + JSON.stringify(bySplit) + ' pixels of the three colours) and by a field (six topics)'); + + // ---- 2. The lists --------------------------------------------------------------------------------------------------- + const dups = await listRows(); + assert.deepEqual(dups.sort(), ['cur-dup-r010-d001', 'cur-dup-r020-d002', 'cur-dup-r040-v001'], 'The planted pairs'); + await press(byKey('cur-list-leakage')); await listShown('leakage', 'leakage'); + assert.deepEqual(await listRows(), ['cur-leak-v001'], 'The leaked record alone'); + const leakNote = await text('#main .cur-list'); + assert.match(leakNote, /1 record outside train has a near-copy in it/); + await press(byKey('cur-list-outliers')); await listShown('outliers', 'outliers'); + assert.equal((await listRows())[0], 'cur-out-far01', 'The far record first'); + await press(byKey('cur-list-duplicates')); await listShown('duplicates', 'duplicates again'); + await press(byKey('cur-dup-r010-d001')); await listShown('like', 'more like r010'); + assert.equal((await listRows())[0], 'cur-like-d001', 'Its copy is the most alike'); + await until(async () => (await text('#main .viewer .iv-head h3')) === 'r010', 'the viewer shows r010'); + assert.match(await text('#main .viewer'), /Note 10 about bees\./); + check('2. Duplicates lists the 3 planted pairs; Leakage lists v001 alone ("' + leakNote.split('\n').find(l => /near-copy/.test(l)).slice(0, 80) + '…"); Outliers puts far01 first; pressing r010 ≈ d001 opens r010 in the viewer and More like this lists d001 first'); + + // ---- 3. A region chosen becomes a dataset, and fills Freeze --------------------------------------------------------- + await press(byKey('cur-clear')); + const m = await api('embedding_map', { run, name: 'curated' }); + const f32 = b => { const buf = Buffer.from(b, 'base64'); return Array.from({ length: buf.length / 4 }, (_, i) => buf.readFloatLE(i * 4)); }; + const xs = f32(m.x_f32), ys = f32(m.y_f32), [x0, x1, y0, y1] = m.bounds; + const rect = await evaluate(`(() => { const r = document.querySelector('#main .cur-map canvas').getBoundingClientRect(); return { left: r.left, top: r.top, width: r.width, height: r.height }; })()`); + const PAD = 12, iw = rect.width - 2 * PAD, ih = rect.height - 2 * PAD; + const from = [rect.left + 4, rect.top + 4], to = [rect.left + rect.width * 0.42, rect.top + rect.height - 4]; + const expected = m.ids.filter((id, i) => { const px = rect.left + PAD + (xs[i] - x0) / (x1 - x0) * iw, py = rect.top + PAD + (1 - (ys[i] - y0) / (y1 - y0)) * ih; return px >= from[0] && px <= to[0] && py >= from[1] && py <= to[1]; }); + assert.ok(expected.length > 20 && expected.length < 200, 'The box holds some of the records: ' + expected.length); + await mouse('mouseMoved', ...from); await mouse('mousePressed', ...from, 1); + for (let t = 1; t <= 8; t++) await mouse('mouseMoved', from[0] + (to[0] - from[0]) * t / 8, from[1] + (to[1] - from[1]) * t / 8, 1); + await mouse('mouseReleased', ...to); + await until(async () => (await text('#main .cur-count')) === expected.length + ' records chosen', 'the box chosen: ' + expected.length); + await press(byKey('cur-new')); + await type(byKey('curnew:field:title'), 'Left of the map'); + await press(byKey('curnew:keep')); await kept('the new dataset'); + await until(async () => /Kept datasets\/left-of-the-map as an unsaved edit/.test(await text('#main .cur-chosen') || ''), 'kept, said beside the map'); + const picked = (await api('definition', { reference: 'datasets/left-of-the-map' })).document; + assert.deepEqual(picked.run, { step: 'select', inputs: { records: REF }, settings: { records: expected } }, 'The definition holds exactly the chosen records'); + assert.equal(await text('#main .cur-count'), expected.length + ' records chosen', 'The choice stays'); + await press(byKey('cur-freeze')); + await until(() => evaluate(`decodeURIComponent(location.hash) === '#data/new:freeze' && !!document.querySelector('#aside .frz-records')`), 'Freeze filled in'); + await settled('freeze'); + assert.equal(await value(byKey('newfreeze:field:dataset')), REF); + assert.match(await text('#aside .frz-records'), new RegExp('Only the ' + expected.length + ' records chosen on the map')); + await type(byKey('newfreeze:field:title'), 'Left frozen'); + await press(byKey('newfreeze:keep')); await kept('the freeze'); + const frozen = (await api('definition', { reference: 'datasets/left-frozen' })).document; + assert.deepEqual(frozen.run.inputs, { records: REF }); assert.deepEqual(frozen.run.annotations, ['annotations/quality']); + assert.deepEqual(frozen.run.settings.records, expected, 'Freeze names exactly the chosen records'); + check('3. A box dragged on the map chose exactly the ' + expected.length + ' records the test computed from embedding_map; New dataset from these kept datasets/left-of-the-map, a select of exactly those ids; Freeze these opened the Freeze form filled in, whose Keep wrote them as records'); + + // ---- 4. The Embed form and the embedder ----------------------------------------------------------------------------- + await load('light', 'data'); + await press(byKey('data:new:embed')); + await until(() => evaluate(`!!document.querySelector('#aside [data-key="newembed:field:model"]')`), 'the Embed form'); await settled('embed form'); + const first = await evaluate(`document.querySelector('#aside [data-key="newembed:field:model"] option').textContent`); + assert.equal(first, 'Default: EmbeddingGemma 2 → embeddinggemma-2 · embeddinggemma-2-gpu (unsloth/embeddinggemma-2-GGUF)'); + assert.deepEqual(await options('#aside [data-key="newembed:field:model"]'), ['', 'embeddinggemma-2\u0000embeddinggemma-2-gpu', 'nomic-embed\u0000nomic-embed-gpu']); + assert.equal(await value(byKey('newembed:field:prefix')), 'task: clustering | query: '); + await type(byKey('newembed:field:title'), 'Notes embedded'); await choose(byKey('newembed:field:dataset'), 'datasets/notes'); + await press(byKey('newembed:keep')); await kept('the embed'); + assert.deepEqual((await api('definition', { reference: 'datasets/notes-embedded' })).document.run, { step: 'embed', inputs: { records: 'datasets/notes' }, settings: {} }); + await load('light', 'train/endpoint'); + await until(() => text('#aside .emb-part'), 'the embedder in the endpoint\'s drawer'); + const part = await text('#aside .emb-part'); + assert.match(part, /the default, EmbeddingGemma 2/); assert.match(part, /embeddinggemma-2 · embeddinggemma-2-gpu \(unsloth\/embeddinggemma-2-GGUF\)/); + check('4. The Embed form offers "' + first + '" first, then the served embedders, with the prefix "task: clustering | query: ", and keeps an embed of datasets/notes naming no model; the endpoint\'s drawer shows the embedder and what it resolves to'); + + // ---- 5. Nothing redrawn by a reading --------------------------------------------------------------------------------- + await openMap('light'); + await press(byKey('cur-dup-r020-d002')); await listShown('like', 'more like r020'); + await evaluate(WATCHER); await evaluate(`window.__still.start()`); + let since = Date.now(); await evaluate(`window.dispatchEvent(new Event('focus')); true`); await reading(since, WATCHED.concat(['map']), 'focus'); + since = Date.now(); await reading(since, WATCHED, 'the timer', Math.round((IDLE_MS + 8000) / 100)); + const r = await evaluate(`window.__still.stop()`); + for (const id of ['tabs', 'main', 'aside']) assert.deepEqual([r.counts[id].added, r.counts[id].removed, r.counts[id].attrs, r.counts[id].text, r.fresh[id]], [0, 0, 0, 0, 0], id + ' untouched: ' + JSON.stringify(r.counts[id])); + assert.equal(r.flash, 0, 'no "Reading…"'); + assert.equal(await text('#main .cur-count'), '2 records chosen'); + check('5. With the map open, r020 opened and two records chosen, the window regaining focus and a reading on the timer added, removed and changed no node of the tab bar, the main area or the drawer'); + + // ---- 6. Light and dark, wide and narrow ----------------------------------------------------------------------------- + const seen = [], pageOver = {}; + const over = async label => { + const o = await evaluate(`(() => { const m = document.getElementById('main'), cur = document.querySelector('#main .cur'), a = document.getElementById('drawer'); + const inner = cur ? [...cur.querySelectorAll('*')].filter(e => e.scrollWidth - e.clientWidth > 1 && getComputedStyle(e).overflowX !== 'auto' && getComputedStyle(e).overflowX !== 'hidden').map(e => e.className) : []; + const r = cur ? cur.getBoundingClientRect() : null, mr = m.getBoundingClientRect(); + return { page: document.documentElement.scrollWidth - innerWidth, cur: cur ? cur.scrollWidth - cur.clientWidth : 0, past: r ? Math.round(r.right - mr.right) : 0, drawer: a.scrollWidth - a.clientWidth, inner }; })()`); + assert.ok(o.cur <= 1 && o.past <= 1 && o.drawer <= 1 && !o.inner.length, label + ': sideways overflow ' + JSON.stringify(o)); + pageOver[label] = o.page; + }; + const view = async (tag, name) => { await over(tag + ' ' + name); await shot(tag + '-' + name); seen.push(tag + ' ' + name); }; + for (const [w, hgt] of [[1440, 900], [390, 844]]) for (const name of ['light', 'dark']) { + const tag = name + '-' + w; + await size(w, hgt); + await openMap(name); await view(tag, 'map'); + await press(byKey('cur-list-leakage')); await listShown('leakage', 'leakage'); await press(byKey('cur-leak-v001')); await listShown('like', 'more like v001'); + await evaluate(`(() => { document.querySelector('#main .cur-lists').scrollIntoView({ block: 'start' }); return true; })()`); + await view(tag, 'more-like-this'); + await hash('data'); await press(byKey('data:new:embed')); await until(() => evaluate(`!!document.querySelector('#aside [data-key="newembed:field:model"]')`), 'the Embed form'); await settled('embed'); + await view(tag, 'embed-form'); + } + await size(1440, 900); + const wide = Object.entries(pageOver).filter(([k, v]) => v > 0); + assert.ok(wide.every(([k]) => / 390 /.test(' ' + k.replace('-', ' ') + ' ') || k.includes('-390')), 'The page overflows only at 390: ' + JSON.stringify(wide)); + check('6. Nothing in the map, its lists or the drawer overflows sideways in light and dark at 1440 × 900 and 390 × 844 (' + seen.length + ' views); the page itself is ' + (wide.length ? 'wider than 390 by ' + [...new Set(wide.map(([, v]) => v))].join(', ') + ' px (its header and strip, as found in phase 2)' : 'never wider than the window') + (shots ? '; screenshots in ' + shots : '')); + + // ---- Nothing failed --------------------------------------------------------------------------------------------------- + assert.deepEqual(errors, [], 'Script errors'); + assert.deepEqual(failures, [], 'Failed requests'); + check('No script error, no failed request'); + fs.writeFileSync(path.join(report, 'receipt.json'), JSON.stringify({ status: 'pass', folder, checks }, null, 2) + '\n'); + console.log('Receipt in ' + report); +})().catch(async error => { + process.exitCode = 1; + console.error(error); if (serverErrors) console.error('Server:', serverErrors.slice(-4000)); + console.error('Script errors:', JSON.stringify(errors)); console.error('Failed requests:', JSON.stringify(failures)); + try { if (evaluate) { await shot('failure'); console.error('Page:', (await evaluate('document.body.innerText')).slice(0, 3000)); } } catch (_) { /* the page is gone */ } + fs.writeFileSync(path.join(report, 'failure.json'), JSON.stringify({ status: 'failed', error: String(error && error.stack || error), checks, errors, failures }, null, 2) + '\n'); +}).finally(async () => { + try { session?.close(); } catch (_) { /* closed */ } + try { fake?.stdin.end(); } catch (_) { /* gone */ } + for (const child of children.reverse()) await stop(child); + if (owned) try { dropOwned(...owned); } catch (error) { console.error('Dropping the disposable schemas failed:', error.message); process.exitCode = 1; } + try { execFileSync('chmod', ['-R', 'u+w', temporary]); } catch (_) { /* nothing was made read-only */ } + fs.rmSync(temporary, { recursive: true, force: true }); +}); diff --git a/tests/project_curation_browser_fixture.py b/tests/project_curation_browser_fixture.py new file mode 100644 index 00000000..04b9e9a2 --- /dev/null +++ b/tests/project_curation_browser_fixture.py @@ -0,0 +1,69 @@ +"""The product of the curation check's dataset (tests/browser_project_workspace_curation.cjs), standard library only. + +Run as the fixture dataset's command: python make_curated.py --out <output>. It writes records.jsonl (244 texts +with splits, a topic and a length in meta) and the embeddings a project's own script would write beside them, +embeddings/curated.npy and .json (16 dimensions; six topics spread around a circle in the two leading ones). Planted: +d001 and d002 are near-copies of r010 and r020 in train; v001, in validation, is a near-copy of r040 in train (the +leak); far01 lies far from every topic. +""" +import argparse +import json +import math +import os +import random +import struct +import sys + +TOPICS = ('boats', 'birds', 'bread', 'bridges', 'bees', 'books') +DIMENSIONS = 16 + + +def write_npy(path, rows): + header = "{'descr': '<f4', 'fortran_order': False, 'shape': (%d, %d), }" % (len(rows), DIMENSIONS) + text = (header + ' ' * (64 - (10 + len(header) + 1) % 64) + '\n').encode('latin-1') + with open(path, 'wb') as handle: + handle.write(b'\x93NUMPY\x01\x00' + struct.pack('<H', len(text)) + text) + for row in rows: + handle.write(struct.pack(f'<{DIMENSIONS}f', *row)) + + +def main(argv=None): + parser = argparse.ArgumentParser() + parser.add_argument('--out', required=True) + out = parser.parse_args(argv).out + generator = random.Random(19) + centres = [] + for k in range(len(TOPICS)): + angle = 2 * math.pi * k / len(TOPICS) + centre = [4 * math.cos(angle), 4 * math.sin(angle)] + [generator.gauss(0, 0.4) for _ in range(DIMENSIONS - 2)] + centre[2] += 3.0 # every row leans one way, so cosines between topics stay below the thresholds + centres.append(centre) + records, rows = [], [] + for i in range(240): + k = i % len(TOPICS) + split = 'validation' if i % 10 == 3 else 'test' if i % 10 == 7 else 'train' + records.append({'id': f'r{i:03d}', 'kind': 'text', 'text': f'Note {i} about {TOPICS[k]}.', 'split': split, + 'meta': {'topic': TOPICS[k], 'length': 10 + i % 17}}) + rows.append([value + generator.gauss(0, 1.0) for value in centres[k]]) + for name, copy_of, split in (('d001', 10, 'train'), ('d002', 20, 'train'), ('v001', 40, 'validation')): + records.append({'id': name, 'kind': 'text', 'text': records[copy_of]['text'] + ' (again)', 'split': split, + 'meta': {'topic': records[copy_of]['meta']['topic'], 'length': 12}}) + rows.append([value + generator.gauss(0, 0.002) for value in rows[copy_of]]) + records.append({'id': 'far01', 'kind': 'text', 'text': 'Something else entirely.', 'split': 'train', + 'meta': {'topic': 'other', 'length': 30}}) + rows.append([generator.gauss(0, 1) for _ in range(DIMENSIONS - 3)] + [-6.0, 5.0, -4.0]) + os.makedirs(os.path.join(out, 'embeddings'), exist_ok=True) + with open(os.path.join(out, 'records.jsonl'), 'w', encoding='utf-8') as handle: + for record in records: + handle.write(json.dumps(record) + '\n') + write_npy(os.path.join(out, 'embeddings', 'curated.npy'), rows) + with open(os.path.join(out, 'embeddings', 'curated.json'), 'w', encoding='utf-8') as handle: + json.dump({'format': 'tuldok_embeddings_v1', 'records': [record['id'] for record in records], + 'dimensions': DIMENSIONS, 'metric': 'cosine', 'model': {'name': 'stand-in', 'via': 'a script'}, + 'prefix': None, 'source': {'dataset': None, 'run': None}}, handle) + print(f'{len(records)} records and their embeddings written.', file=sys.stderr) + return 0 + + +if __name__ == '__main__': + sys.exit(main()) From 6b09da5f2b8d0760533e8d327e44644a61ccb55e Mon Sep 17 00:00:00 2001 From: MrScripty <TheEnvironmentGuy@protonmail.com> Date: Thu, 19 Nov 2026 06:54:20 -0700 Subject: [PATCH 108/131] docs(plan): spec-t5 as built Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --- docs/plans/training-and-curation/spec-t5.md | 37 +++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/docs/plans/training-and-curation/spec-t5.md b/docs/plans/training-and-curation/spec-t5.md index 2ef970f1..9063ed96 100644 --- a/docs/plans/training-and-curation/spec-t5.md +++ b/docs/plans/training-and-curation/spec-t5.md @@ -125,3 +125,40 @@ Five reads, `inspect`, in `INSIDE_READS` like the others, in the `project_folder ## 9. Out of scope Computing embeddings in Tuldok; approximate nearest-neighbour indexes; UMAP or t-SNE in Tuldok (a script may write either as the projection); embeddings of sounds, point clouds and meshes through the endpoint (Pumas 0.8.0 embeds text and images only); colouring by an annotation that is not carried in the records (the working copy's annotations of a task); several sets on one map; clustering. + +## As built + +What differs from the text above, and what was found. Built on `feat/t5-curation` beside phase 3, which owns the Benchmarks and Analysis tabs and the Map's compare set; this phase touched `tabs.js` (the Embed button and its drawer, two lines), `base.css` (one block at its end), `operations.py`, `service.py`, `docs/contracts/project-folder.md` and the service test's count of operations (69 to 76) only where its own rows go. + +### T5a, the contract, the reader and the reads + +- **Record ids** in an index are 1 to 600 characters without control characters, not spec-d1's 1 to 200 of `A-Z a-z 0-9 . _ -`: a product read from its files names its records by their addresses (`notes/a.txt`), and those must be embeddable. Section 1 was corrected. +- **The blocking of the pair searches is a grid, not a sort.** As first built, rows were sorted by their first coordinate and each compared with those within the threshold along it. On clustered data (20 clusters, 256 dimensions) that window held most rows. The searches now bucket rows by up to five leading coordinates in cells twice the radius wide and look in the 2⁵ cells on the near side of each coordinate (exact: a row within the radius in every coordinate lies in one of them); the lower bound in all eight coordinates and the residual rules pairs out before the dot product. Outliers search the cells within the 90th percentile of the k-th nearest distance of 32 rows first, and fall back to the outward sort for a row whose k nearest are not all within it. +- **The budget is 20,000,000 coordinate comparisons or 400,000,000 values multiplied** (not 400,000 exact products: the cost of one depends on the dimensions), checked before each row; a row is examined whole. `complete` and `examined` say how far it got; a test lowers the budget and checks that the pairs listed are exactly the brute force's pairs of the rows examined (the shuffled order is `random.Random(f'{rows}:{dimensions}')`). +- **Measured** (this machine, CPU, pure Python, `math.sumprod` at about 8 to 12 ns a value), on the worst case the reader meets, clustered synthetic rows with no duplicate in them: 50,000 × 256 — reading and making unit 1.0 s, the map 2.4 s, more like this 0.18 s, duplicates 8.0 s and incomplete (634 rows examined), outliers 7.9 s (162), leakage 2.6 s (1,030 of 10,000 held-out rows); 10,000 × 768 — the map 8.8 s, duplicates 6.3 s (1,044), outliers 5.4 s (201), leakage complete in 1.0 s; 20,000 × 256 duplicates 6.8 s (1,587); 2,000 × 64 everything complete under 1 s. Each is computed once per set and kept. **The searches are complete for a few thousand rows only when the data is dense at the threshold's radius**; past that they list exact pairs for a shuffled sample of rows and say so. Without vectorised arithmetic this is the honest bound; an approximate index was left out (section 9). +- **Colour.** Numbers with at most 24 different values are drawn as categories (a split numbered 0, 1, 2 reads better so); more are a number scale. A category beyond the 24th is one `other`. +- **`embeddings`** is an operation outside the lock (it finds products under it, reads indexes after), not an `INSIDE_READS` row; `records_run` joined the service's product arguments. A set in a dataset that takes this one as an input whose index cannot be read is not listed (it cannot be told which records it describes); one in the dataset's own product is listed with its problem. +- **Tests:** `tests/test_tuldok_project_curation.py`, 13 for T5a (contract 3, components 3, searches 7). The catalog profile's digest is unchanged (110 operations). + +### T5b, the embedder, `embed`, `select` and freeze's records + +- **The default's match** is "the alias or `model_id` contains `embeddinggemma-2`" ignoring case; among those the `model_id` `unsloth/embeddinggemma-2-GGUF` (case ignored) first, then the endpoint's order; only entries with `text_embedding` or `multimodal_embedding` available and `embeddings_float32` out count. Several profiles of the default are not an error: the first is used. The refusal names every served embedder with its model id and profile. +- **The machine's setting** is `embedding_model`, `embedding_profile` and `embedding_prefix` in the settings file; `set_embedder` checks a named model against the endpoint (refused `not-found`, or `unavailable` with no endpoint) and writes an activity row `set` or `default`. A step reads the machine's setting at build time through the facts file (`<run>/embed.json`), so an `embed` that names no model is not reproducible from its definition alone; the index records what answered and `named_by` (`definition`, `setting` or `default`). +- **Requests.** `options` is always sent, `{"kind": "embeddings"}` and `dimensions` when set; `dimensions` is checked against an advertised bound when there is one and sent without one (the release accepts it on every embedder; spec-d5's rule that an option must be advertised was not applied here, since llama.cpp embedders may advertise none). Image batches stop short of 16 MiB of base64. +- **Rows are written in the order answered** (texts first, then images; on a resume, the rows taken first), and `records` follows that order; the contract allows any order. +- **A resume** takes rows only from the dataset's newest run, when it failed, and only when the input run, model, model id, profile, prefix and dimensions asked are all the same; the partial files are removed when the step ends, so a product holds only the set. +- **`pumas_operations`** gained the `embeddings` result (finite vectors of one length) beside `decisions`, additively; catalog mode never asks for it. +- **`select`** keeps a record's id when it is a list id and makes one (`id_from`) from an address otherwise, keeping the address in `meta.selected_from`. Freeze's `records` names input ids; one that is not in the input fails the step. +- **Not in the text:** `check` refuses `profile` without `model`; a step with no required setting still needs `"settings": {}`. +- **Tests:** 13 more in `tests/test_tuldok_project_curation.py` (the default embedder 3, settings 1, check 2, built for real against the fake 6, published 1). Project suite 799 OK (773 before, and these 26); agent interface 43 OK (4 skipped). + +### T5c, the page + +- **Map is a third mode of the opened dataset** (inside.js), shown when `embeddings` lists a readable set; its state is per dataset in page memory (the set, colour, view, tool, chosen, opened, each list's controls), not in the address: a reload opens on Records. The viewer beside the map is inside.js's, reading the record from the set's records run. +- **Tools** are Move, Box and Lasso (a toggle; Box first); a click that does not move opens the nearest point within 10 px. The wheel zooms about the pointer from 1 to 200 times. Keys: the arrows move a highlight to the nearest point in that direction (Enter opens it, Escape clears the choice), announced in a live region. +- **New dataset from these** is a form under the map (title, name, Keep), not a drawer, so the map stays; after Keep the line "Kept datasets/<name> as an unsaved edit" stays with the choice. **Freeze these** fills the Freeze form's slot (`annotate.js`'s new `fillFreeze`) and goes to `#data/new:freeze`, which shows "Only the N records chosen on the map" with a button to freeze every record instead; changing the dataset there drops them. +- **The embedder** is shown and set in the endpoint's drawer on Train (owner: a select with "EmbeddingGemma 2 (the default)" first, the prefix, Set the embedder); the Train section's rows were not changed. The Embed form's first model is "Default: <EmbeddingGemma 2 or the machine's> → <what it resolves to now>"; with the default chosen the definition names no model, and the prefix is written only when changed from the machine's. +- **Colours** are the dataviz reference palette's eight categorical hues as tokens `--cat-1` to `--cat-8` (light and dark steps); "other" and rows with no value are `--ink-3`; thin cells are washed with `--warn` at 14 %. Not run through the palette validator here (the palette is the validated reference instance). +- **The check,** `tests/browser_project_workspace_curation.cjs` (fixture `tests/project_curation_browser_fixture.py`, 244 texts in 16 dimensions with the plants; `browser_fake_pumas.py --embedders`): 7 PASS — the map drawn and coloured by split (pixels of the three colours counted on the canvas) and by a field; the three planted pairs, the leaked v001 alone, far01 the first outlier, more like this; a box of 97 records kept as a select of exactly the ids the test computes from `embedding_map`, and Freeze filled in and kept with them; the Embed form's default "EmbeddingGemma 2 → embeddinggemma-2 · embeddinggemma-2-gpu (unsloth/embeddinggemma-2-GGUF)"; nothing touched by a focus and a timer reading; light and dark at 1440 and 390, nothing in the map, its lists or the drawer overflowing. Regressions unchanged: `browser_project_workspace.cjs` (23 PASS), `_inside` (8), `_annotate` (10), `_endpoint` (8). +- **Found at 390 px:** the page is 553 to 554 px wider than the window on every tab, as phase 2 found (its header and strip); the check records it and asserts only the map, its lists and the drawer. +- **Not verified:** a real Pumas or a real EmbeddingGemma 2 (the owner's word is needed; no GPU was used); an embed built from the page (built in the unit tests against the fake); thin regions in the page (the fixture has none; tested in the reader); Lasso, Move and the wheel by a person (drawn and wired, not driven by the check); 50,000 points drawn in the browser (the map draws one arc a point, unmeasured past 244); a set whose records run is not current, and several sets of one dataset (the select is drawn, not exercised); colouring by an annotation the records carry in the page (tested in the reader); screen readers. From d9464624372373bc95f1f0cd2b3607b9088fabe6 Mon Sep 17 00:00:00 2001 From: MrScripty <TheEnvironmentGuy@protonmail.com> Date: Thu, 19 Nov 2026 06:54:28 -0700 Subject: [PATCH 109/131] docs(plan): spec-t5 as built, the regression counts Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --- docs/plans/training-and-curation/spec-t5.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/plans/training-and-curation/spec-t5.md b/docs/plans/training-and-curation/spec-t5.md index 9063ed96..07e07fca 100644 --- a/docs/plans/training-and-curation/spec-t5.md +++ b/docs/plans/training-and-curation/spec-t5.md @@ -159,6 +159,6 @@ What differs from the text above, and what was found. Built on `feat/t5-curation - **New dataset from these** is a form under the map (title, name, Keep), not a drawer, so the map stays; after Keep the line "Kept datasets/<name> as an unsaved edit" stays with the choice. **Freeze these** fills the Freeze form's slot (`annotate.js`'s new `fillFreeze`) and goes to `#data/new:freeze`, which shows "Only the N records chosen on the map" with a button to freeze every record instead; changing the dataset there drops them. - **The embedder** is shown and set in the endpoint's drawer on Train (owner: a select with "EmbeddingGemma 2 (the default)" first, the prefix, Set the embedder); the Train section's rows were not changed. The Embed form's first model is "Default: <EmbeddingGemma 2 or the machine's> → <what it resolves to now>"; with the default chosen the definition names no model, and the prefix is written only when changed from the machine's. - **Colours** are the dataviz reference palette's eight categorical hues as tokens `--cat-1` to `--cat-8` (light and dark steps); "other" and rows with no value are `--ink-3`; thin cells are washed with `--warn` at 14 %. Not run through the palette validator here (the palette is the validated reference instance). -- **The check,** `tests/browser_project_workspace_curation.cjs` (fixture `tests/project_curation_browser_fixture.py`, 244 texts in 16 dimensions with the plants; `browser_fake_pumas.py --embedders`): 7 PASS — the map drawn and coloured by split (pixels of the three colours counted on the canvas) and by a field; the three planted pairs, the leaked v001 alone, far01 the first outlier, more like this; a box of 97 records kept as a select of exactly the ids the test computes from `embedding_map`, and Freeze filled in and kept with them; the Embed form's default "EmbeddingGemma 2 → embeddinggemma-2 · embeddinggemma-2-gpu (unsloth/embeddinggemma-2-GGUF)"; nothing touched by a focus and a timer reading; light and dark at 1440 and 390, nothing in the map, its lists or the drawer overflowing. Regressions unchanged: `browser_project_workspace.cjs` (23 PASS), `_inside` (8), `_annotate` (10), `_endpoint` (8). +- **The check,** `tests/browser_project_workspace_curation.cjs` (fixture `tests/project_curation_browser_fixture.py`, 244 texts in 16 dimensions with the plants; `browser_fake_pumas.py --embedders`): 7 PASS — the map drawn and coloured by split (pixels of the three colours counted on the canvas) and by a field; the three planted pairs, the leaked v001 alone, far01 the first outlier, more like this; a box of 97 records kept as a select of exactly the ids the test computes from `embedding_map`, and Freeze filled in and kept with them; the Embed form's default "EmbeddingGemma 2 → embeddinggemma-2 · embeddinggemma-2-gpu (unsloth/embeddinggemma-2-GGUF)"; nothing touched by a focus and a timer reading; light and dark at 1440 and 390, nothing in the map, its lists or the drawer overflowing. Regressions unchanged: `browser_project_workspace.cjs` (24 PASS), `_inside` (8), `_annotate` (11), `_endpoint` (8). - **Found at 390 px:** the page is 553 to 554 px wider than the window on every tab, as phase 2 found (its header and strip); the check records it and asserts only the map, its lists and the drawer. - **Not verified:** a real Pumas or a real EmbeddingGemma 2 (the owner's word is needed; no GPU was used); an embed built from the page (built in the unit tests against the fake); thin regions in the page (the fixture has none; tested in the reader); Lasso, Move and the wheel by a person (drawn and wired, not driven by the check); 50,000 points drawn in the browser (the map draws one arc a point, unmeasured past 244); a set whose records run is not current, and several sets of one dataset (the select is drawn, not exercised); colouring by an annotation the records carry in the page (tested in the reader); screen readers. From ca2440a0c9c264d7df45b9d34bd19508d00ebdfb Mon Sep 17 00:00:00 2001 From: MrScripty <TheEnvironmentGuy@protonmail.com> Date: Thu, 19 Nov 2026 06:57:30 -0700 Subject: [PATCH 110/131] feat(project): the step annotate and the annotation sets it makes A dataset whose run is the step annotate makes an annotation set for one task: the project's own annotator command, run in its environment with the TULDOK_* contract variables, or a model of the Pumas endpoint (boxes and polygons asked of a vision model as JSON). Lines are checked and sorted, sidecars kept under files/, annotator.json names what made them; a failed run is resumed by the next build. annotation_sets reads a set back. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --- docs/contracts/project-folder.md | 44 +- tests/test_tuldok_project_annotate_step.py | 418 +++++++++++++++++++ tests/test_tuldok_project_pumas.py | 6 +- tuldok_project/annotation_payloads.py | 36 ++ tuldok_project/annotation_sets.py | 125 ++++++ tuldok_project/annotations.py | 3 + tuldok_project/builds.py | 47 ++- tuldok_project/check.py | 56 ++- tuldok_project/plan.py | 12 +- tuldok_project/pumas.py | 43 +- tuldok_project/schemas/benchmark.schema.json | 51 ++- tuldok_project/schemas/dataset.schema.json | 51 ++- tuldok_project/schemas/recipe.schema.json | 51 ++- tuldok_project/schemas/step.schema.json | 51 ++- tuldok_project/steps.py | 343 ++++++++++++++- 15 files changed, 1260 insertions(+), 77 deletions(-) create mode 100644 tests/test_tuldok_project_annotate_step.py create mode 100644 tuldok_project/annotation_sets.py diff --git a/docs/contracts/project-folder.md b/docs/contracts/project-folder.md index 8d06cb0d..a9379909 100644 --- a/docs/contracts/project-folder.md +++ b/docs/contracts/project-folder.md @@ -202,7 +202,7 @@ object. It is required unless `earlier_work.rebuild` is `no`. | `resources` | no | any of `gpu` (boolean), `cpu_threads` (integer ≥ 1), `memory_gb`, `wall_hours`, `disk_gb` (numbers > 0) | | `sources` | no | at most 64 code paths (files or directories); a change in them means the code changed | | `estimate` | no | `{"command": [...]}`, 1 to 64 strings; the command prints one JSON object with any of `disk_bytes`, `wall_seconds`, `items` | -| `annotations` | with `step: "freeze"` only | 1 to 32 different references to `annotations/`: the tasks a freeze reads | +| `annotations` | with `step: "freeze"` or `"annotate"` only | 1 to 32 different references to `annotations/`: the tasks a freeze reads, or the one task an annotate makes a set for | A **code path** is a path relative to the code root, at most 1,024 characters. `settings_file`, `sources`, a model's `config_file` and `sources`, and an @@ -265,7 +265,7 @@ Example, `datasets/sinusoidal-v1.json`: #### Steps Tuldok provides A dataset's `run` names either a `command` or a `step`, one of `import`, -`freeze` and `generate`. A run with `step` has no `command`, `environment`, `outputs`, +`freeze`, `generate` and `annotate`. A run with `step` has no `command`, `environment`, `outputs`, `settings_file`, `env` or `estimate`: the step's outputs are fixed, its settings are inline in `settings`, and it runs with Tuldok's own interpreter (see [The command and its environment](#the-command-and-its-environment)). @@ -445,6 +445,46 @@ Example, `datasets/poem-lines.json`: } ``` +##### `annotate`: an annotation set made by an annotator + +A dataset whose run is `"step": "annotate"` makes an **annotation set**: the +annotations of one annotator (a project's script, or a model behind the +Pumas endpoint) for one task, beside the task's own annotations in Git. Its +run takes one input, `"inputs": {"records": "datasets/<name>"}`, the task's +dataset, and `"annotations": ["annotations/<task>"]`. Unlike the other steps +it may have `command`, `environment` and `env`: the command is the project's +annotator, run in its environment from the code snapshot. Exactly one of +`run.command` and `settings.pumas`. Settings: + +| Setting | Required | Rule | +| --- | --- | --- | +| `by` | yes | `{"kind": "model", "script" or "person", "name": 1 to 200 characters, "version"?}`: what makes the annotations | +| `pumas` | no | `{"model", "profile"?, "instruction"?}`: ask this model of the machine's Pumas endpoint instead of a command; for `text`, `class` and `tags` as a suggestion is asked, for `boxes` and `polygons` on images as a JSON list asked of a vision model | +| `limit` | no | at most this many records, 1 to 1,000,000 | +| `options` | no | an object of at most 8 KiB, given to the command as `TULDOK_ANNOTATE_OPTIONS` | + +**The command's contract.** It runs with these variables: `TULDOK_RECORDS` +(the input product), `TULDOK_TODO` (a file of the input's record lines still +to annotate, their paths made absolute), `TULDOK_TASK` (the task's +definition), `TULDOK_ANNOTATIONS` (the file to append lines to), +`TULDOK_FILES` (the directory for sidecars) and `TULDOK_ANNOTATE_OPTIONS`. +It appends one line per record, `{"record", "value", "confidence"?, +"note"?}`, in any order, writes the sidecars its values name under +`TULDOK_FILES`, and may print progress lines. When it ends with status 0 the +step keeps the last valid line of each record of the input, drops and counts +the rest, and writes the product: + +``` +annotator.json {"format": "tuldok_annotator_v1", "task", "by": {"kind", "name", "version"?, "settings"}, "records", "made", "at"} +annotations.jsonl {"record", "sha256", "value", "confidence"?, "note"?} per record, sorted by record +files/ the sidecars the lines name +``` + +`by.settings` is the run's settings without `by`. A run of the same +definition that failed or was cancelled is resumed by the next build: its +valid lines (and sidecars) whose records are unchanged are kept, and only the +other records are given to the command (or asked of the model). + ### `model` A model is an architecture. It produces nothing by itself; recipes train it. diff --git a/tests/test_tuldok_project_annotate_step.py b/tests/test_tuldok_project_annotate_step.py new file mode 100644 index 00000000..53ac94bd --- /dev/null +++ b/tests/test_tuldok_project_annotate_step.py @@ -0,0 +1,418 @@ +"""The step annotate and the annotation sets it makes: sections 3 and 4 of spec-t4.md (slice T4b). + +Two stand-in segmentors (one script, code/segment.py, run with two +thresholds: a project's own command in a test environment connected to the +interpreter running the tests) annotate four small images (masks and +polygons) and two small point clouds (point objects) of a dataset built by +import, for real through builds.execute. Each set has the lines, sidecars and +annotator.json expected; a line naming a record the input lacks and a line +with a bad value are dropped and counted; a run that fails half way is +resumed by the next build, which annotates only the rest. The Pumas route +is asked of tests/fake_pumas_typed.py (as test_tuldok_project_pumas does): +boxes as a JSON list, an answer that is not one refused. No real Pumas, no +GPU. The database parts run only when TULDOK_DATABASE_URL names a disposable +cluster. The stand-ins and the test data are shared with +test_tuldok_project_annotation_agreement through make_project. +""" +import json +import os +from pathlib import Path +import struct +import subprocess +import sys +import tempfile +import unittest +from unittest import mock +import uuid +import zlib + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) +sys.path.insert(0, str(Path(__file__).resolve().parent)) + +from tuldok_project import (annotation_payloads as payloads, annotation_sets, builds, check, environments, # noqa: E402 + local, plan, steps, store) + +DATABASE = os.environ.get('TULDOK_DATABASE_URL') +GIT = ['git', '-c', 'user.name=Tuldok Test', '-c', 'user.email=test@example.invalid', '-c', 'commit.gpgsign=false'] +RIGHTS = 'Made for this test; anything may be done with it.' + +# ------------------------------------------------------------ the test data + +def png_rgb(width, height, pixel): + """An RGB PNG whose pixel(x, y) gives (r, g, b); rows unfiltered.""" + rows = b''.join(b'\x00' + b''.join(bytes(pixel(x, y)) for x in range(width)) for y in range(height)) + + def chunk(kind, body): + return struct.pack('>I', len(body)) + kind + body + struct.pack('>I', zlib.crc32(kind + body)) + return (b'\x89PNG\r\n\x1a\n' + chunk(b'IHDR', struct.pack('>IIBBBBB', width, height, 8, 2, 0, 0, 0)) + + chunk(b'IDAT', zlib.compress(rows)) + chunk(b'IEND', b'')) + + +def blobs(width, height, rectangles): + """An image of dark rectangles (x, y, w, h, red or blue) with a softer one-pixel rim, on white.""" + def pixel(x, y): + for bx, by, bw, bh, colour in rectangles: + inside = bx <= x < bx + bw and by <= y < by + bh + rim = bx - 1 <= x < bx + bw + 1 and by - 1 <= y < by + bh + 1 + dark = (40, 40, 200) if colour == 'blue' else (200, 40, 40) + if inside: + return dark + if rim: + return tuple((255 + value) // 2 for value in dark) # the rim: lighter, where thresholds differ + return (255, 255, 255) + return png_rgb(width, height, pixel) + + +IMAGES = { + 'images/a.png': blobs(24, 16, [(2, 2, 6, 5, 'red'), (14, 6, 7, 7, 'blue')]), + 'images/b.png': blobs(24, 16, [(4, 4, 10, 8, 'red')]), + 'images/c.png': blobs(24, 16, [(1, 1, 4, 4, 'blue'), (10, 3, 5, 9, 'blue')]), + 'images/d.png': blobs(24, 16, []), +} + + +def cloud(count, top): + """An ASCII PLY of count points on a line rising in z; the points above z = top are 'the top'.""" + lines = ['ply', 'format ascii 1.0', f'element vertex {count}', 'property float x', 'property float y', + 'property float z', 'end_header'] + lines += [f'{n * 0.1:.2f} {0.05 * (n % 3):.2f} {n / (count - 1):.3f}' for n in range(count)] + return ('\n'.join(lines) + '\n').encode('ascii') + + +CLOUDS = {'clouds/p.ply': cloud(20, 0.5), 'clouds/q.ply': cloud(30, 0.5)} + +# The stand-in segmentor: a project's own script. It reads the contract's variables and writes lines. +SEGMENT = r'''"""A stand-in segmentor for Tuldok's tests: dark pixels below a threshold, points above a height.""" +import json, os, struct, sys, zlib + +def read_png(path): + data = open(path, 'rb').read() + width, height = struct.unpack('>II', data[16:24]) + at, body = 8, b'' + while at < len(data): + length, kind = struct.unpack('>I4s', data[at:at + 8]) + if kind == b'IDAT': + body += data[at + 8:at + 8 + length] + at += 12 + length + raw = zlib.decompress(body) + rows = [raw[y * (width * 3 + 1) + 1:(y + 1) * (width * 3 + 1)] for y in range(height)] + return width, height, [[tuple(row[x * 3:x * 3 + 3]) for x in range(width)] for row in rows] + +def write_png(path, width, values): + rows = b''.join(b'\x00' + bytes(values[y * width:(y + 1) * width]) for y in range(len(values) // width)) + part = lambda kind, body: struct.pack('>I', len(body)) + kind + body + struct.pack('>I', zlib.crc32(kind + body)) + with open(path, 'wb') as out: + out.write(b'\x89PNG\r\n\x1a\n' + part(b'IHDR', struct.pack('>IIBBBBB', width, len(values) // width, 8, 0, 0, 0, 0)) + + part(b'IDAT', zlib.compress(rows)) + part(b'IEND', b'')) + +threshold = float(sys.argv[1]) +options = json.loads(os.environ['TULDOK_ANNOTATE_OPTIONS']) +task = json.load(open(os.environ['TULDOK_TASK'])) +todo = [json.loads(line) for line in open(os.environ['TULDOK_TODO'])] +marker = options.get('fail_once') +failing = marker is not None and not os.path.exists(marker) +if marker is not None and not failing: + open(marker + '.todo', 'w').write(json.dumps([r['id'] for r in todo])) +out = open(os.environ['TULDOK_ANNOTATIONS'], 'a') +for number, record in enumerate(todo): + if failing and number == 1: + open(marker, 'w').write('failed once') + sys.exit(4) + value = None + if record['kind'] == 'image': + width, height, pixels = read_png(record['path']) + ids, found = [0] * (width * height), {} + for y in range(height): + for x in range(width): + r, g, b = pixels[y][x] + if (r + g + b) / 3 < threshold: + colour = 'blue' if b > r else 'red' + ids[y * width + x] = found.setdefault(colour, len(found) + 1) + if task['task'] == 'mask': + name = record['id'] + '.png' + write_png(os.path.join(os.environ['TULDOK_FILES'], name), width, ids) + value = {'file': name, 'classes': {str(n): 'blob' for n in found.values()} or {'1': 'blob'}, + 'confidence': 0.9} + else: + value = [] + for colour, n in sorted(found.items()): + xs = [i % width for i, v in enumerate(ids) if v == n] + ys = [i // width for i, v in enumerate(ids) if v == n] + x0, y0, x1, y1 = min(xs), min(ys), max(xs) + 1, max(ys) + 1 + value.append({'term': colour, 'points': [[x0, y0], [x1, y0], [x1, y1], [x0, y1]], + 'confidence': round(1 - n / 10, 2)}) + else: + rows = open(record['path']).read().split('end_header\n')[1].split('\n') + zs = [float(row.split()[2]) for row in rows if row.strip()] + value = [{'term': 'top', 'indices': [i for i, z in enumerate(zs) if z > threshold / 255]}] + out.write(json.dumps({'record': record['id'], 'value': value}) + '\n') + out.flush() + print(json.dumps({'format': 'tuldok_progress_v1', 'stage': 'segment', 'completed': number + 1, + 'total': len(todo), 'metrics': {}}), flush=True) +if options.get('noise'): + out.write(json.dumps({'record': 'nobody', 'value': []}) + '\n') + out.write(json.dumps({'record': todo[0]['id'], 'value': 'not a value'}) + '\n') if todo else None + out.write('not json\n') +''' + + +def task(dataset, kind, vocabulary=None, **fields): + document = {'format': 'tuldok_definition_v1', 'kind': 'annotation', 'title': f'A {kind} task', + 'dataset': dataset, 'task': kind} + if vocabulary is not None: + document['vocabulary'] = vocabulary + document.update(fields) + return document + + +def annotator(task_reference, threshold, name, input_dataset='datasets/raw', **settings): + return {'format': 'tuldok_definition_v1', 'kind': 'dataset', 'title': f'{name} on {task_reference}', + 'run': {'step': 'annotate', 'inputs': {'records': input_dataset}, 'annotations': [task_reference], + 'command': ['python', 'segment.py', str(threshold)], 'environment': 'environments/test-python', + 'settings': {'by': {'kind': 'script', 'name': name, 'version': '1'}, **settings}}} + + +DEFINITIONS = { + 'datasets/raw': {'format': 'tuldok_definition_v1', 'kind': 'dataset', 'title': 'Images and clouds', + 'run': {'step': 'import', 'settings': {'source': 'data', 'rights': RIGHTS}}}, + 'annotations/masks': task('datasets/raw', 'mask', ['blob'], mask='instance'), + 'annotations/shapes': task('datasets/raw', 'polygons', ['red', 'blue']), + 'annotations/objects': task('datasets/raw', 'points', ['top']), + 'datasets/masks-a': annotator('annotations/masks', 160, 'segment-a'), + 'datasets/masks-b': annotator('annotations/masks', 200, 'segment-b'), + 'datasets/shapes-a': annotator('annotations/shapes', 160, 'segment-a', options={'noise': True}), + 'datasets/shapes-b': annotator('annotations/shapes', 200, 'segment-b'), + 'datasets/objects-a': annotator('annotations/objects', 128, 'segment-a'), + 'datasets/objects-b': annotator('annotations/objects', 140, 'segment-b'), + 'environments/test-python': {'format': 'tuldok_definition_v1', 'kind': 'environment', + 'title': 'The interpreter running the tests', 'python': '3.12', 'device': 'cpu', + 'packages': {'jsonschema': '4.26.0'}}, +} + + +def make_project(root, project_id, extra=None): + """root/project and root/code: the definitions, the stand-in and the images and clouds.""" + folder, code = root / 'project', root / 'code' + for directory in ('datasets', 'annotations', 'environments'): + (folder / directory).mkdir(parents=True, exist_ok=True) + (folder / 'tuldok.json').write_text(json.dumps({'format': 'tuldok_project_v1', 'id': project_id, + 'name': 'Annotators test project', 'code_root': '../code'}, + indent=2) + '\n', encoding='utf-8') + for reference, document in {**DEFINITIONS, **(extra or {})}.items(): + (folder / f'{reference}.json').write_text(json.dumps(document, indent=2) + '\n', encoding='utf-8') + for name, data in {**IMAGES, **CLOUDS}.items(): + path = code / 'data' / name + path.parent.mkdir(parents=True, exist_ok=True) + path.write_bytes(data) + (code / 'segment.py').write_text(SEGMENT, encoding='utf-8') + return folder + + +def _writable(root): + for current, directories, _files in os.walk(root): + for name in directories: + os.chmod(os.path.join(current, name), 0o755) + + +class Checked(unittest.TestCase): + """check on an annotate's run (spec-t4.md section 4), with no database.""" + + def setUp(self): + directory = tempfile.TemporaryDirectory() + self.addCleanup(directory.cleanup) + self.folder = make_project(Path(directory.name), uuid.uuid4().hex) + + def write(self, reference, document): + (self.folder / f'{reference}.json').write_text(json.dumps(document, indent=2) + '\n', encoding='utf-8') + + def problems(self, reference): + return {(p.pointer, p.severity) for p in check.check_folder(self.folder).problems + if p.path == f'{reference}.json'} + + def test_the_stand_ins_check(self): + self.assertEqual([p for p in check.check_folder(self.folder).problems if p.severity == 'error'], []) + + def test_each_rule(self): + document = annotator('annotations/masks', 1, 'x') + document['run']['settings']['pumas'] = {'model': 'm'} + self.write('datasets/masks-a', document) + self.assertIn(('/run', 'error'), self.problems('datasets/masks-a')) + document = annotator('annotations/masks', 1, 'x', limit=0) + document['run']['settings']['by'] = {'kind': 'robot', 'name': ''} + document['run']['annotations'] = ['annotations/masks', 'annotations/shapes'] + self.write('datasets/masks-a', document) + found = self.problems('datasets/masks-a') + for pointer in ('/run/settings/by', '/run/settings/limit', '/run/annotations'): + self.assertIn((pointer, 'error'), found) + document = annotator('annotations/masks', 1, 'x', input_dataset='datasets/masks-b') + self.write('datasets/masks-a', document) + self.assertIn(('/run/annotations/0', 'error'), self.problems('datasets/masks-a')) + # import, freeze and generate still take no command or environment + document = dict(DEFINITIONS['datasets/raw']) + document['run'] = dict(document['run'], environment='environments/test-python') + self.write('datasets/raw', document) + self.assertIn(('/run/environment', 'error'), self.problems('datasets/raw')) + + +@unittest.skipUnless(DATABASE, 'TULDOK_DATABASE_URL is not set; database tests need a disposable cluster.') +class Built(unittest.TestCase): + """The stand-ins run for real by builds.execute.""" + + def setUp(self): + directory = tempfile.TemporaryDirectory() + self.addCleanup(directory.cleanup) + self.temporary = Path(directory.name) + self.root = self.temporary / 'repository' + self.root.mkdir() + self.home = self.temporary / 'home' + self.addCleanup(_writable, self.home) + patcher = mock.patch.dict(os.environ, {local.HOME_VARIABLE: str(self.home), + local.SETTINGS_VARIABLE: str(self.temporary / 'settings.json')}) + patcher.start() + self.addCleanup(patcher.stop) + self.project_id = uuid.uuid4().hex + self.marker = self.temporary / 'failed-once' + extra = {'datasets/resumed': annotator('annotations/objects', 128, 'segment-r', + options={'fail_once': str(self.marker)})} + self.folder = make_project(self.root, self.project_id, extra) + subprocess.run([*GIT, '-C', str(self.root), 'init', '-q'], check=True) + subprocess.run([*GIT, '-C', str(self.root), 'add', '-A'], check=True) + subprocess.run([*GIT, '-C', str(self.root), 'commit', '-q', '-m', 'The project.'], check=True) + self.addCleanup(store.drop_project, self.project_id) + with store.open_project(self.folder) as project: + self.assertTrue(environments.connect(project, 'environments/test-python', sys.executable)['ok']) + + def build(self, *targets, ok=True): + with store.open_project(self.folder) as project: + made = plan.build_plan(project, list(targets)) + done = builds.execute(self.folder, made, confirm=lambda given: True) + self.assertEqual(done['ok'], ok, done) + return done + + def product(self, reference): + with store.open_project(self.folder) as project: + return builds.products(project, reference)[0]['directory'] + + def test_two_segmentors_make_two_sets(self): + self.build('datasets/masks-a', 'datasets/masks-b', 'datasets/shapes-a', 'datasets/shapes-b', + 'datasets/objects-a', 'datasets/objects-b') + tasks = {'masks': DEFINITIONS['annotations/masks'], 'shapes': DEFINITIONS['annotations/shapes'], + 'objects': DEFINITIONS['annotations/objects']} + sets = {} + for name in ('masks-a', 'masks-b', 'shapes-a', 'shapes-b', 'objects-a', 'objects-b'): + directory = self.product(f'datasets/{name}') + sets[name] = annotation_sets.read_set(directory, tasks[name.split('-')[0]]) + sets[name]['directory'] = directory + self.assertEqual(sorted(sets['masks-a']['records']), ['images__a.png', 'images__b.png', 'images__c.png', + 'images__d.png']) + self.assertEqual(sorted(sets['objects-a']['records']), ['clouds__p.ply', 'clouds__q.ply']) + annotator_file = json.loads(Path(sets['masks-a']['directory'], 'annotator.json').read_text()) + self.assertEqual(annotator_file['format'], 'tuldok_annotator_v1') + self.assertEqual(annotator_file['task'], 'annotations/masks') + self.assertEqual(annotator_file['by'], {'kind': 'script', 'name': 'segment-a', 'version': '1', + 'settings': {}}) + self.assertEqual((annotator_file['records'], annotator_file['made']), (6, 4)) + # The masks: the rim is dark enough for b (200) and not for a (160), so b's objects are one pixel wider. + line = sets['masks-a']['records']['images__a.png'] + self.assertEqual(line['value']['classes'], {'1': 'blob', '2': 'blob'}) + self.assertEqual(line['confidence'] if 'confidence' in line else line['value']['confidence'], 0.9) + a = payloads.read_png(annotation_sets.sidecar(sets['masks-a']['directory'], line['value']['file']))[2] + b = payloads.read_png(annotation_sets.sidecar(sets['masks-b']['directory'], + sets['masks-b']['records']['images__a.png']['value']['file']))[2] + self.assertEqual((sum(1 for v in a if v == 1), sum(1 for v in a if v == 2)), (30, 49)) + self.assertEqual((sum(1 for v in b if v == 1), sum(1 for v in b if v == 2)), (56, 81)) + # The point objects: points above 128/255 and 140/255 of the height. + self.assertEqual(sets['objects-a']['records']['clouds__p.ply']['value'], + [{'term': 'top', 'indices': list(range(10, 20))}]) + self.assertEqual(sets['objects-b']['records']['clouds__p.ply']['value'], + [{'term': 'top', 'indices': list(range(11, 20))}]) + # The noise of shapes-a: an unknown record, a bad value and a line that is not JSON, all dropped. + self.assertEqual(sorted(sets['shapes-a']['records']), sorted(sets['shapes-b']['records'])) + log = self.run_log('datasets/shapes-a') + for words in ('lines the annotator wrote are not JSON', 'name a record the input does not have', + 'hold a value the task does not allow'): + self.assertIn(words, log) + lines = Path(sets['shapes-a']['directory'], 'annotations.jsonl').read_text().splitlines() + self.assertEqual([json.loads(line)['record'] for line in lines], sorted(json.loads(line)['record'] + for line in lines)) + self.assertTrue(lines[0].startswith('{"record":"images__a.png","sha256":"')) + self.assertIn('"value":[{"term":"blue","points":[[14,6],[21,6],[21,13],[14,13]],"confidence":0.8}', lines[0]) + + def run_log(self, reference): + with store.open_project(self.folder) as project: + run = builds.products(project, reference)[0]['run_id'] + directory = project._execute('SELECT directory FROM {schema}.runs WHERE id = %s', (run,)).fetchone()[0] + return ''.join(path.read_text(errors='replace') for path in Path(directory).glob('*.log')) + + def test_a_failed_run_is_resumed(self): + done = self.build('datasets/resumed', ok=False) + self.assertEqual(done['steps'][-1]['state'], 'failed') + self.assertTrue(self.marker.exists()) + self.build('datasets/resumed') + given = json.loads(Path(str(self.marker) + '.todo').read_text()) + self.assertEqual(given, ['clouds__q.ply']) # p was annotated before the first run failed + found = annotation_sets.read_set(self.product('datasets/resumed'), DEFINITIONS['annotations/objects']) + self.assertEqual(sorted(found['records']), ['clouds__p.ply', 'clouds__q.ply']) + + +class Pumas(unittest.TestCase): + """The Pumas route of annotate, as a function on directories, against the fake endpoint.""" + + def setUp(self): + import fake_pumas_typed + from test_tuldok_project_pumas import listing + directory = tempfile.TemporaryDirectory() + self.addCleanup(directory.cleanup) + self.root = Path(directory.name) + self.server, self.base, self.fake = fake_pumas_typed.start() + self.addCleanup(self.server.server_close) + self.addCleanup(self.server.shutdown) + self.fake['served_models'] = listing() + records = self.root / 'records' + (records / 'files').mkdir(parents=True) + lines = [] + for name, data in IMAGES.items(): + identifier = name.replace('/', '__') + (records / 'files' / identifier).write_bytes(data) + lines.append({'id': identifier, 'kind': 'image', 'path': f'files/{identifier}'}) + (records / 'records.jsonl').write_text(''.join(json.dumps(line) + '\n' for line in lines)) + self.records = records + + def annotate(self, answers, kind='boxes', vocabulary=('red', 'blue')): + answers = list(answers) + self.fake['respond'] = lambda body: {'kind': 'text', 'text': answers.pop(0), 'finish_reason': 'stop'} + output = self.root / f'output-{len(list(self.root.iterdir()))}' + output.mkdir() + said = [] + counts = steps.annotate_records( + {'by': {'kind': 'model', 'name': 'vision'}, 'pumas': {'model': 'controlled-vision', + 'profile': 'vision-cpu'}}, + str(output), records=str(self.records), + task={'reference': 'annotations/boxes', 'document': task('datasets/raw', kind, list(vocabulary))}, + run_directory=str(self.root), endpoint=self.base, out=said.append) + return counts, output, said + + def test_boxes_asked_as_json(self): + answer = '```json\n[{"term": "red", "x": 2, "y": 2, "w": 6, "h": 5}]\n```' + counts, output, said = self.annotate([answer, '[]', 'I see two blue squares.', + '[{"term": "green", "x": 0, "y": 0, "w": 1, "h": 1}]']) + self.assertEqual((counts['kept'], counts['refused']), (2, 2)) + lines = [json.loads(line) for line in (output / 'annotations.jsonl').read_text().splitlines()] + self.assertEqual([(line['record'], line['value']) for line in lines], + [('images__a.png', [{'term': 'red', 'x': 2, 'y': 2, 'w': 6, 'h': 5}]), + ('images__b.png', [])]) + by = json.loads((output / 'annotator.json').read_text())['by'] + self.assertEqual(by['model'], {'model': 'controlled-vision', 'profile': 'vision-cpu', + 'capability': 'image_to_text'}) + asked = self.fake['requests'][-4] + self.assertEqual(asked['capability'], 'image_to_text') + self.assertIn('of 24 by 16 pixels', json.dumps(asked)) + self.assertTrue(any('not a JSON list of regions' in line for line in said)) + + def test_every_one_of_the_first_refused_fails(self): + with self.assertRaises(steps.StepError): + self.annotate(['no'] * 4) + + +if __name__ == '__main__': + unittest.main() diff --git a/tests/test_tuldok_project_pumas.py b/tests/test_tuldok_project_pumas.py index b834fa41..a1b3425f 100644 --- a/tests/test_tuldok_project_pumas.py +++ b/tests/test_tuldok_project_pumas.py @@ -325,9 +325,13 @@ def test_section_four(self): self.assertEqual(self.capabilities('writer', 'writer-cpu', 'class', 'text'), ['chat_generation']) self.assertEqual(self.capabilities(*vision, 'tags', 'image'), ['image_to_text']) self.assertEqual(self.capabilities('writer', 'writer-cpu', 'class', 'audio'), []) - for task in ('review', 'boxes', 'spans', 'segments'): + for task in ('review', 'spans', 'segments'): for model in self.models: self.assertEqual(self.capabilities(*model, task, 'image'), []) + for task in ('boxes', 'polygons'): # spec-t4.md section 4: regions asked of a vision model as JSON + self.assertEqual(self.capabilities(*vision, task, 'image'), ['image_to_text']) + self.assertEqual(self.capabilities('writer', 'writer-cpu', task, 'image'), []) + self.assertEqual(self.capabilities(*vision, task, 'text'), []) for kind in ('pointcloud', 'mesh', 'array', 'file'): for model in self.models: self.assertEqual(self.capabilities(*model, 'text', kind), []) diff --git a/tuldok_project/annotation_payloads.py b/tuldok_project/annotation_payloads.py index 5e0f0f4c..9acc2513 100644 --- a/tuldok_project/annotation_payloads.py +++ b/tuldok_project/annotation_payloads.py @@ -223,3 +223,39 @@ def write_npy(shape, values, descr): if not _LITTLE: packed.byteswap() return _NPY + b'\x01\x00' + struct.pack('<H', len(text)) + text + packed.tobytes() + + +# --------------------------------------------------------------- sidecars + +def sidecar_problem(task, data, *, size=None, points=None): + """A sentence when data is not a sidecar task's value may name (spec-t4.md section 1), else None. + + size is (width, height) of the image a mask or depth map covers, points + the count of the cloud a point-id file covers; each is checked when given. + """ + if len(data) > SIDECAR_LIMIT: + return f'The sidecar is over {SIDECAR_LIMIT:,} bytes.' + try: + if task == 'mask': + width, height, depth, colour, interlace = png_size(data) + if colour != 0 or depth not in (8, 16) or interlace: + return 'A mask PNG must be 8- or 16-bit greyscale and not interlaced.' + if size is not None and (width, height) != tuple(size): + return f'The mask is {width} by {height} pixels; the image is {size[0]} by {size[1]}.' + return None + shape, kind, _itemsize, _little, _offset = npy_header(data) + if task == 'depth': + if len(shape) != 2: + return f'A depth map must be a 2-D array; this one has shape {tuple(shape)}.' + if size is not None and (shape[1], shape[0]) != tuple(size): + return f'The depth map is {shape[1]} by {shape[0]}; the image is {size[0]} by {size[1]}.' + if shape[0] * shape[1] > PIXEL_LIMIT: + return f'The depth map is over {PIXEL_LIMIT:,} values.' + return None + if len(shape) != 1 or kind == 'f': + return 'A point-id file must be a 1-D array of whole numbers.' + if points is not None and shape[0] != points: + return f'The point-id file has {shape[0]} values; the cloud has {points} points.' + return None + except PayloadError as exc: + return str(exc) diff --git a/tuldok_project/annotation_sets.py b/tuldok_project/annotation_sets.py new file mode 100644 index 00000000..1a4742a8 --- /dev/null +++ b/tuldok_project/annotation_sets.py @@ -0,0 +1,125 @@ +"""Annotation sets: what an annotator wrote into its run's product, read back for review and agreement. + +Owns the reading side of section 3 of +docs/plans/training-and-curation/spec-t4.md. A set is the product of a +dataset whose run is the step annotate (annotator.json, annotations.jsonl and +files/); the kept set is the working copy's annotations of the task, given +by the caller. Reading is bounded (the lines file at most 64 MiB, at most +RECORDS_LIMIT records) and every line is checked again against the task as +it now stands, so a set made for an earlier vocabulary shows what still +fits and counts the rest. Nothing of the product is written, nothing is +unpickled, and a sidecar is read only from under the product's files/. +Standard library and Tuldok's pure modules only; no database. +""" +import json +import os + +from . import annotation_payloads as payloads, annotations + +KEPT = 'kept' # the name of the kept set: annotations/<task>.jsonl and its working copy +ANNOTATOR = 'annotator.json' +ANNOTATED = 'annotations.jsonl' +FILES = 'files' +LINES_LIMIT = 64 * 1024 * 1024 # bytes of a set's lines file +RECORDS_LIMIT = 20_000 # records of one set read for agreement (spec-t4.md section 5) +ANNOTATOR_LIMIT = 64 * 1024 # bytes of annotator.json +SETS_LIMIT = 8 + + +class SetProblem(Exception): + """A set that cannot be read; the message is a sentence.""" + + +def is_annotator(document, task_reference): + """True when document is a dataset whose run is an annotate for task_reference.""" + run = document.get('run') if isinstance(document, dict) else None + return (isinstance(run, dict) and run.get('step') == 'annotate' + and isinstance(run.get('annotations'), list) and run['annotations'][:1] == [task_reference]) + + +def _confined(root, relative): + """The real path of a regular file at relative under root, or None.""" + if not isinstance(relative, str) or relative.startswith('/') or '\x00' in relative: + return None + parts = relative.split('/') + if '..' in parts or '' in parts: + return None + full = os.path.realpath(os.path.join(root, *parts)) + base = os.path.realpath(root) + return full if full.startswith(base + os.sep) and os.path.isfile(full) else None + + +def read_annotator(directory): + """The annotator.json of a set's product directory, or SetProblem.""" + path = os.path.join(directory, ANNOTATOR) + try: + with open(path, 'rb') as handle: + raw = handle.read(ANNOTATOR_LIMIT + 1) + except OSError: + raise SetProblem(f'The product has no {ANNOTATOR}.') from None + try: + value = json.loads(raw) + except (ValueError, RecursionError): + raise SetProblem(f'Its {ANNOTATOR} is not JSON.') from None + if len(raw) > ANNOTATOR_LIMIT or not isinstance(value, dict) or not isinstance(value.get('by'), dict): + raise SetProblem(f'Its {ANNOTATOR} is not an annotator file with by.') + return value + + +def read_set(directory, document, *, limit=RECORDS_LIMIT): + """{by, at, records: {record: line}, skipped, truncated} of the set in a product directory. + + A line is {sha256, value, confidence?, note?}; a line whose value the task + (document) no longer allows is skipped and counted. + """ + annotator = read_annotator(directory) + path = os.path.join(directory, ANNOTATED) + try: + size = os.path.getsize(path) + except OSError: + raise SetProblem(f'The product has no {ANNOTATED}.') from None + if size > LINES_LIMIT: + raise SetProblem(f'Its {ANNOTATED} is over {LINES_LIMIT:,} bytes.') + task, vocabulary = document.get('task'), document.get('vocabulary') or [] + fields = annotations.task_fields(document) + records, skipped, truncated = {}, 0, False + with open(path, 'rb') as handle: + for raw in handle: + if not raw.strip(): + continue + if len(records) >= limit: + truncated = True + break + try: + line = json.loads(raw) + except (ValueError, RecursionError): + skipped += 1 + continue + if not isinstance(line, dict) or not isinstance(line.get('record'), str) or 'value' not in line: + skipped += 1 + continue + errors, unknown = annotations.value_problems(task, vocabulary, 'accepted', line['value'], fields=fields) + confidence = line.get('confidence') + if errors or unknown or (confidence is not None and not annotations._confidence(confidence)): + skipped += 1 + continue + kept = {'sha256': line.get('sha256'), 'value': line['value']} + if confidence is not None: + kept['confidence'] = confidence + if isinstance(line.get('note'), str): + kept['note'] = line['note'] + records[line['record']] = kept + return {'by': annotator['by'], 'at': annotator.get('at'), 'records': records, 'skipped': skipped, + 'truncated': truncated} + + +def sidecar(directory, name): + """The bytes of a set's sidecar files/<name>, or SetProblem.""" + full = _confined(os.path.join(directory, FILES), name) + if full is None: + raise SetProblem(f'The sidecar {name!r} is not under the product\'s {FILES}/.') + with open(full, 'rb') as handle: + data = handle.read(payloads.SIDECAR_LIMIT + 1) + if len(data) > payloads.SIDECAR_LIMIT: + raise SetProblem(f'The sidecar {name!r} is over {payloads.SIDECAR_LIMIT:,} bytes.') + return data diff --git a/tuldok_project/annotations.py b/tuldok_project/annotations.py index 6edd631f..298c23dc 100644 --- a/tuldok_project/annotations.py +++ b/tuldok_project/annotations.py @@ -549,6 +549,9 @@ def _ordered_value(value): return [_ordered_object(item) if isinstance(item, dict) else item for item in value] +ordered_value = _ordered_value + + def encode(row): """One row as its line, without the line end: keys in KEYS order, compact, not ASCII-escaped. diff --git a/tuldok_project/builds.py b/tuldok_project/builds.py index 7c575b8e..8278011e 100644 --- a/tuldok_project/builds.py +++ b/tuldok_project/builds.py @@ -59,6 +59,7 @@ from . import annotations, documents, environments, graph, launcher, local, result_rows, snapshot, store from . import folder as folder_reader +from . import steps as steps_module BUILT_KINDS = ('dataset', 'recipe', 'step', 'benchmark') ACTIVE = ('queued', 'running') @@ -782,6 +783,8 @@ def _resolve(self, project, reference, subject, *, estimate=False): for key, value in (run.get('env') or {}).items(): env[key] = _fill(value, values, missing, f'The value of env {key}') env.update(self.extra_env) + if step == 'annotate' and 'PYTHONPATH' in env: # the annotator command's own, given back to it + env['TULDOK_ANNOTATE_PYTHONPATH'] = env['PYTHONPATH'] if step is not None: # Tuldok's own code first; the snapshot's code (the working directory) never importable. env.update(PYTHONSAFEPATH='1', PYTHONPATH=TULDOK_ROOT) @@ -826,8 +829,10 @@ def _step_argv(self, project, reference, run, step, values, prepared): return argv + ['--code', self.code.code_root] if step == 'generate': return argv + self._generate_argv(project, run, values, prepared) + if step == 'annotate': + return argv + self._annotate_argv(project, reference, run, values, prepared) if step != 'freeze': - raise StepProblem(f'Tuldok provides no step {step!r}; use import, freeze or generate.') + raise StepProblem(f'Tuldok provides no step {step!r}; use import, freeze, generate or annotate.') inputs = _declared_inputs({'run': run}) used = inputs.get('records', (None, None))[0] if 'inputs.records' not in values or used is None: @@ -884,6 +889,46 @@ def _generate_argv(self, project, run, values, prepared): argv += ['--records', values['inputs.prompts']] return argv + def _annotate_argv(self, project, reference, run, values, prepared): + """The arguments of an annotate (spec-t4.md section 4): its input, task, command or endpoint, and resume.""" + used = _declared_inputs({'run': run}).get('records', (None, None))[0] + tasks = run.get('annotations') if isinstance(run.get('annotations'), list) else [] + if 'inputs.records' not in values or used is None or len(tasks) != 1: + raise StepProblem('An annotate reads the records of its input records for one task; declare ' + 'run.inputs.records and one task in run.annotations.') + row = project._execute(f'SELECT document FROM {{schema}}.definitions WHERE NOT removed AND ' + f'{store._REFERENCE_SQL} = %s', (tasks[0],)).fetchone() + if row is None or not isinstance(row[0], dict): + raise StepProblem(f'Its task {tasks[0]} does not exist.') + if row[0].get('dataset') != used: + raise StepProblem(f'Its task {tasks[0]} annotates {row[0].get("dataset")}, not its input {used}.') + task_file = os.path.join(prepared['directory'], STEP_TASKS_FILE) + prepared['files'][task_file] = (json.dumps({'reference': tasks[0], 'document': row[0]}, ensure_ascii=False, + indent=2) + '\n').encode('utf-8') + argv = ['--records', values['inputs.records'], '--task', task_file, '--run-directory', prepared['directory'], + '--code', self.code.code_root] + command = list(run.get('command') or []) + if command: + filled = [_fill(part, values, {}, f'The command word {part!r}') for part in command] + filled[0] = self._program(command, filled, prepared['environment']) + argv += ['--command-json', json.dumps(filled, ensure_ascii=False)] + else: + try: + address = local.pumas_endpoint() + except local.SettingsError as exc: + raise StepProblem(str(exc)) from None + if address is None: + raise StepProblem('No Pumas endpoint is set on this machine, so the model cannot be asked; the owner ' + 'sets one, then build again.') + prepared['endpoint'] = {'address': address, 'version': None} + argv += ['--endpoint', address] + earlier = project._execute("SELECT directory FROM {schema}.runs WHERE reference = %s AND definition = %s " + "AND state <> 'succeeded' AND state <> 'running' AND state <> 'queued' " + 'ORDER BY queued_at DESC LIMIT 1', (reference, prepared['definition'])).fetchone() + if earlier is not None and os.path.isfile(os.path.join(earlier[0], OUTPUT, steps_module.ANNOTATED)): + argv += ['--resume', os.path.join(earlier[0], OUTPUT)] + return argv + def _line_file(self, project, file): """(Git blob id or None, bytes or None) of a line file, relative to the project folder, as this build reads it. diff --git a/tuldok_project/check.py b/tuldok_project/check.py index 7a978a7a..cc6b206c 100644 --- a/tuldok_project/check.py +++ b/tuldok_project/check.py @@ -15,6 +15,7 @@ Problems are collected, never raised, so one bad file never hides another. """ from dataclasses import dataclass, field +import json import math import os import re @@ -134,7 +135,11 @@ def _check_view(view, path, add): STEP_SETTINGS = {'import': {'source': True, 'pattern': False, 'kind': False, 'rights': True, 'lines': False}, 'freeze': {'seed': True, 'shares': True, 'include': False}, 'generate': {'make': True, 'model': True, 'profile': False, 'prompt': True, 'count': False, - 'per': False, 'seed': False, 'options': False, 'rights': True}} + 'per': False, 'seed': False, 'options': False, 'rights': True}, + 'annotate': {'by': True, 'pumas': False, 'limit': False, 'options': False}} +BY_KINDS = ('model', 'script', 'person') # what made an annotation set (spec-t4.md section 3) +BY_TEXT_LIMIT = 200 +OPTIONS_BYTES = 8 * 1024 SEED_LIMIT = 2 ** 63 GENERATE_SEED_LIMIT = 2 ** 32 # a seed Pumas takes is unsigned 32-bit PROMPT_LIMIT = 16_000 # characters of a generate prompt @@ -168,13 +173,16 @@ def _check_step(run, path, add): settings = settings if isinstance(settings, dict) else {} where = lambda key: documents.pointer('run', 'settings', key) # noqa: E731 if step in ('import', 'generate') and 'annotations' in run: - add('error', path, '/run/annotations', 'Only the step freeze reads annotations; remove annotations.') + add('error', path, '/run/annotations', 'Only the steps freeze and annotate name tasks; remove annotations.') + if step == 'import': _check_import(settings, path, where, add) if 'inputs' in run: add('error', path, '/run/inputs', 'The step import reads files, not other products; remove inputs.') elif step == 'generate': _check_generate(run, settings, path, where, add) + elif step == 'annotate': + _check_annotate(run, settings, path, where, add) else: _check_freeze(run, settings, path, where, add) @@ -279,6 +287,46 @@ def _check_generate(run, settings, path, where, add): 'what may be done with what is made.') +def _check_annotate(run, settings, path, where, add): + """The input, task, annotator and settings of the step annotate (spec-t4.md section 4).""" + inputs = run.get('inputs') + if not isinstance(inputs, dict) or set(inputs) != {'records'} or not isinstance(inputs['records'], str) \ + or not inputs['records'].startswith('datasets/'): + add('error', path, '/run/inputs', 'The step annotate takes one input, records, naming the dataset of its ' + 'task: "inputs": {"records": "datasets/<name>"}.') + tasks = run.get('annotations') + if not isinstance(tasks, list) or len(tasks) != 1: + add('error', path, '/run/annotations', 'The step annotate makes a set for one task: ' + '"annotations": ["annotations/<name>"].') + if ('command' in run) == ('pumas' in settings): + add('error', path, '/run', 'An annotate runs either the project\'s command (run.command) or a model of the ' + 'Pumas endpoint (settings.pumas); give exactly one.') + by = settings.get('by') + if 'by' in settings: + wrong = not isinstance(by, dict) or set(by) - {'kind', 'name', 'version'} or by.get('kind') not in BY_KINDS \ + or not isinstance(by.get('name'), str) or not 1 <= len(by['name']) <= BY_TEXT_LIMIT \ + or ('version' in by and not (isinstance(by['version'], str) and len(by['version']) <= BY_TEXT_LIMIT)) + if wrong: + add('error', path, where('by'), 'by must say what makes the annotations: {"kind": "model", "script" or ' + f'"person", "name": 1 to {BY_TEXT_LIMIT} characters, and an optional ' + '"version"}.') + asked = settings.get('pumas') + if 'pumas' in settings and not (isinstance(asked, dict) and set(asked) <= {'model', 'profile', 'instruction'} + and isinstance(asked.get('model'), str) and asked['model'] + and (not isinstance(asked.get('profile'), str) or _PROFILE.match(asked['profile'])) + and all(isinstance(asked.get(key, ''), str) for key in ('profile', 'instruction')) + and len(asked.get('instruction', '')) <= PROMPT_LIMIT): + add('error', path, where('pumas'), 'pumas must name the served model: {"model", and optionally "profile" and ' + f'"instruction" (at most {PROMPT_LIMIT:,} characters)}}.') + limit = settings.get('limit') + if 'limit' in settings and (type(limit) is not int or not 1 <= limit <= steps.ANNOTATE_LIMIT): + add('error', path, where('limit'), f'limit must be a whole number from 1 to {steps.ANNOTATE_LIMIT:,}.') + if 'options' in settings: + options = settings['options'] + if not isinstance(options, dict) or len(json.dumps(options, separators=(',', ':'))) > OPTIONS_BYTES: + add('error', path, where('options'), f'options must be an object of at most {OPTIONS_BYTES:,} bytes.') + + def _check_freeze(run, settings, path, where, add): inputs = run.get('inputs') if not isinstance(inputs, dict) or set(inputs) != {'records'} or not isinstance(inputs['records'], str) \ @@ -320,7 +368,7 @@ def check_steps(definitions, add): check_references' problem).""" for definition in definitions.values(): run = definition.document.get('run') if isinstance(definition.document, dict) else None - if definition.kind != 'dataset' or not isinstance(run, dict) or run.get('step') != 'freeze': + if definition.kind != 'dataset' or not isinstance(run, dict) or run.get('step') not in ('freeze', 'annotate'): continue inputs = run.get('inputs') if isinstance(run.get('inputs'), dict) else {} used = inputs.get('records') if isinstance(inputs.get('records'), str) else None @@ -331,7 +379,7 @@ def check_steps(definitions, add): continue if used is not None and target.document.get('dataset') != used: add('error', definition.path, documents.pointer('run', 'annotations', index), - f'{task} annotates {target.document.get("dataset")}, not {used}, the input of this freeze; ' + f'{task} annotates {target.document.get("dataset")}, not {used}, the input of this {run["step"]}; ' 'name a task of its input.') diff --git a/tuldok_project/plan.py b/tuldok_project/plan.py index 74c6e5c7..e6ecbd8c 100644 --- a/tuldok_project/plan.py +++ b/tuldok_project/plan.py @@ -136,7 +136,7 @@ def _inputs(document): def _tasks(run): """The tasks a freeze step reads (run.annotations), in order; empty for any other run.""" - tasks = run.get('annotations') if run.get('step') == 'freeze' else None + tasks = run.get('annotations') if run.get('step') in ('freeze', 'annotate') else None return [task for task in (tasks if isinstance(tasks, list) else ()) if isinstance(task, str)] @@ -147,13 +147,14 @@ def _task_notes(definitions, reference, document): never a step. Such a freeze fails before it runs. """ used = _inputs(document).get('records', {}).get('reference') + verb = 'freezes by' if _run(document).get('step') == 'freeze' else 'annotates for' notes = [] for task in _tasks(_run(document)): target = definitions.get(task) if target is None: - notes.append(f'{reference} freezes by {task}, which does not exist; it fails when built.') + notes.append(f'{reference} {verb} {task}, which does not exist; it fails when built.') elif target.get('dataset') != used: - notes.append(f'{reference} freezes by {task}, which annotates {target.get("dataset")}, not its input ' + notes.append(f'{reference} {verb} {task}, which annotates {target.get("dataset")}, not its input ' f'{used}; it fails when built.') return notes @@ -286,9 +287,10 @@ def has_endpoint(): if action == 'build' and not step['subjects']['run']: # Nothing would run: blocked, though by no cause of its own. step['action'] = action = actions[reference] = 'blocked' - if provided == 'freeze': + if provided in ('freeze', 'annotate'): notes.extend(_task_notes(definitions, reference, document)) - if provided == 'generate' and action == 'build' and not has_endpoint(): + asks_pumas = provided == 'generate' or (provided == 'annotate' and 'command' not in (document.get('run') or {})) + if asks_pumas and action == 'build' and not has_endpoint(): step['action'] = action = actions[reference] = 'blocked' step['blocked_by'] = [{'reference': reference, 'rebuild': 'endpoint', 'reason': NO_ENDPOINT}] notes.append(f'{reference} is generated through a Pumas endpoint, and none is set on this machine.') diff --git a/tuldok_project/pumas.py b/tuldok_project/pumas.py index e01bdea4..baf6f4d7 100644 --- a/tuldok_project/pumas.py +++ b/tuldok_project/pumas.py @@ -318,6 +318,11 @@ def routes(entry, task, kind): fallback = {'text': ('messages', 'chat_generation'), 'image': ('image_messages', 'image_to_text')}.get(kind) if fallback and fallback[1] in client.available_capabilities(entry, fallback[0], 'text'): found.append({'capability': fallback[1], 'input': fallback[0], 'output': 'text', 'terms': True}) + elif task in ('boxes', 'polygons') and kind == 'image': + # spec-t4.md section 4: regions asked of a vision model as JSON, kept only when they are values of the task + if 'image_to_text' in client.available_capabilities(entry, 'image_messages', 'text'): + found.append({'capability': 'image_to_text', 'input': 'image_messages', 'output': 'text', 'terms': False, + 'regions': True}) return found @@ -392,13 +397,39 @@ def _terms(task, vocabulary, answer): return [term for term in vocabulary if term in found] +def _regions_instruction(task, vocabulary, instruction, size): + shape = ('{"term": <term>, "x": <left>, "y": <top>, "w": <width>, "h": <height>}' if task == 'boxes' + else '{"term": <term>, "points": [[<x>, <y>], ...]} with at least three points') + where = f' of {size[0]} by {size[1]} pixels' if size else '' + return ((instruction + '\n\n' if instruction else '') + + f'Find the regions of this image{where} that show one of these terms. Answer with a JSON list of ' + f'objects {shape}, in pixels from the top left corner, and nothing else; answer [] when there is none. ' + 'The terms:\n' + '\n'.join(vocabulary)) + + +def _regions(words): + """The JSON list a regions answer holds (fenced or not), or None.""" + text = words.strip() + if text.startswith('```'): + text = text.strip('`') + text = text[text.find('\n') + 1:] if '\n' in text else text + start, end = text.find('['), text.rfind(']') + if start < 0 or end < start: + return None + try: + value = json.loads(text[start:end + 1]) + except ValueError: + return None + return value if isinstance(value, list) else None + + def _quoted(words): words = ' '.join(str(words).split()) return '“' + words[:WORDS_SHOWN] + ('…' if len(words) > WORDS_SHOWN else '') + '”' def suggest(address, listing, entry, route, task, vocabulary, content, instruction=None, *, request_id, stop=None, - check=None): + check=None, size=None): """Ask entry for a value of task for one record's content, by route; the value, or PumasError. content is {'kind', 'text'} or {'kind', 'data'}. check(value) returns the @@ -423,6 +454,8 @@ def suggest(address, listing, entry, route, task, vocabulary, content, instructi else: if route['terms']: asked = _terms_instruction(task, vocabulary, instruction) + elif route.get('regions'): + asked = _regions_instruction(task, vocabulary, instruction, size) else: asked = instruction or (DEFAULT_CAPTION if kind == 'image' else DEFAULT_SUMMARY) input_value = _text_input(row, route, content, asked) @@ -433,11 +466,15 @@ def suggest(address, listing, entry, route, task, vocabulary, content, instructi finally: timer.cancel() words = value['text'] - suggestion = _terms(task, vocabulary, words) if route['terms'] else words.strip() + suggestion = (_terms(task, vocabulary, words) if route['terms'] else _regions(words) if route.get('regions') + else words.strip()) + if route.get('regions') and suggestion is None: + raise PumasError(f'The answer of {entry["model"]} is not a JSON list of regions. It answered ' + f'{_quoted(words)}.', 'unsuitable') if route['terms'] and suggestion is None: raise PumasError(f'The answer of {entry["model"]} is not made of the task\'s terms, so it is not a ' f'suggestion. It answered {_quoted(words)}.', 'unsuitable') - if not route['terms'] and not suggestion: + if not route['terms'] and not route.get('regions') and not suggestion: raise PumasError(f'{entry["model"]} answered with nothing.', 'unsuitable') problems = check(suggestion) if check is not None else [] if problems: diff --git a/tuldok_project/schemas/benchmark.schema.json b/tuldok_project/schemas/benchmark.schema.json index 4215457e..a3939932 100644 --- a/tuldok_project/schemas/benchmark.schema.json +++ b/tuldok_project/schemas/benchmark.schema.json @@ -320,9 +320,10 @@ "enum": [ "import", "freeze", - "generate" + "generate", + "annotate" ], - "description": "a step Tuldok provides: import, freeze or generate" + "description": "a step Tuldok provides: import, freeze, generate or annotate" }, "environment": { "type": "string", @@ -480,14 +481,6 @@ }, "then": { "properties": { - "command": { - "not": {}, - "description": "A run with step has no command; remove one of the two." - }, - "environment": { - "not": {}, - "description": "A step Tuldok provides runs with Tuldok's own interpreter; remove environment." - }, "outputs": { "not": {}, "description": "A step's outputs are fixed by the step; remove outputs." @@ -496,10 +489,6 @@ "not": {}, "description": "A step takes its settings inline; use settings, not settings_file." }, - "env": { - "not": {}, - "description": "A step Tuldok provides takes no environment variables; remove env." - }, "estimate": { "not": {}, "description": "A step Tuldok provides has no estimate command; remove estimate." @@ -513,7 +502,39 @@ "properties": { "annotations": { "not": {}, - "description": "annotations belong to a run with step freeze; add step or remove annotations." + "description": "annotations belong to a run with step freeze or annotate; add step or remove annotations." + } + } + } + }, + { + "if": { + "required": [ + "step" + ], + "properties": { + "step": { + "enum": [ + "import", + "freeze", + "generate" + ] + } + } + }, + "then": { + "properties": { + "command": { + "not": {}, + "description": "A run with step has no command; remove one of the two." + }, + "environment": { + "not": {}, + "description": "A step Tuldok provides runs with Tuldok's own interpreter; remove environment." + }, + "env": { + "not": {}, + "description": "A step Tuldok provides takes no environment variables; remove env." } } } diff --git a/tuldok_project/schemas/dataset.schema.json b/tuldok_project/schemas/dataset.schema.json index 03257b51..be03ab73 100644 --- a/tuldok_project/schemas/dataset.schema.json +++ b/tuldok_project/schemas/dataset.schema.json @@ -269,9 +269,10 @@ "enum": [ "import", "freeze", - "generate" + "generate", + "annotate" ], - "description": "a step Tuldok provides: import, freeze or generate" + "description": "a step Tuldok provides: import, freeze, generate or annotate" }, "environment": { "type": "string", @@ -429,14 +430,6 @@ }, "then": { "properties": { - "command": { - "not": {}, - "description": "A run with step has no command; remove one of the two." - }, - "environment": { - "not": {}, - "description": "A step Tuldok provides runs with Tuldok's own interpreter; remove environment." - }, "outputs": { "not": {}, "description": "A step's outputs are fixed by the step; remove outputs." @@ -445,10 +438,6 @@ "not": {}, "description": "A step takes its settings inline; use settings, not settings_file." }, - "env": { - "not": {}, - "description": "A step Tuldok provides takes no environment variables; remove env." - }, "estimate": { "not": {}, "description": "A step Tuldok provides has no estimate command; remove estimate." @@ -462,7 +451,39 @@ "properties": { "annotations": { "not": {}, - "description": "annotations belong to a run with step freeze; add step or remove annotations." + "description": "annotations belong to a run with step freeze or annotate; add step or remove annotations." + } + } + } + }, + { + "if": { + "required": [ + "step" + ], + "properties": { + "step": { + "enum": [ + "import", + "freeze", + "generate" + ] + } + } + }, + "then": { + "properties": { + "command": { + "not": {}, + "description": "A run with step has no command; remove one of the two." + }, + "environment": { + "not": {}, + "description": "A step Tuldok provides runs with Tuldok's own interpreter; remove environment." + }, + "env": { + "not": {}, + "description": "A step Tuldok provides takes no environment variables; remove env." } } } diff --git a/tuldok_project/schemas/recipe.schema.json b/tuldok_project/schemas/recipe.schema.json index 07413d62..a636e11b 100644 --- a/tuldok_project/schemas/recipe.schema.json +++ b/tuldok_project/schemas/recipe.schema.json @@ -251,9 +251,10 @@ "enum": [ "import", "freeze", - "generate" + "generate", + "annotate" ], - "description": "a step Tuldok provides: import, freeze or generate" + "description": "a step Tuldok provides: import, freeze, generate or annotate" }, "environment": { "type": "string", @@ -411,14 +412,6 @@ }, "then": { "properties": { - "command": { - "not": {}, - "description": "A run with step has no command; remove one of the two." - }, - "environment": { - "not": {}, - "description": "A step Tuldok provides runs with Tuldok's own interpreter; remove environment." - }, "outputs": { "not": {}, "description": "A step's outputs are fixed by the step; remove outputs." @@ -427,10 +420,6 @@ "not": {}, "description": "A step takes its settings inline; use settings, not settings_file." }, - "env": { - "not": {}, - "description": "A step Tuldok provides takes no environment variables; remove env." - }, "estimate": { "not": {}, "description": "A step Tuldok provides has no estimate command; remove estimate." @@ -444,7 +433,39 @@ "properties": { "annotations": { "not": {}, - "description": "annotations belong to a run with step freeze; add step or remove annotations." + "description": "annotations belong to a run with step freeze or annotate; add step or remove annotations." + } + } + } + }, + { + "if": { + "required": [ + "step" + ], + "properties": { + "step": { + "enum": [ + "import", + "freeze", + "generate" + ] + } + } + }, + "then": { + "properties": { + "command": { + "not": {}, + "description": "A run with step has no command; remove one of the two." + }, + "environment": { + "not": {}, + "description": "A step Tuldok provides runs with Tuldok's own interpreter; remove environment." + }, + "env": { + "not": {}, + "description": "A step Tuldok provides takes no environment variables; remove env." } } } diff --git a/tuldok_project/schemas/step.schema.json b/tuldok_project/schemas/step.schema.json index 517fe152..1a0ff152 100644 --- a/tuldok_project/schemas/step.schema.json +++ b/tuldok_project/schemas/step.schema.json @@ -202,9 +202,10 @@ "enum": [ "import", "freeze", - "generate" + "generate", + "annotate" ], - "description": "a step Tuldok provides: import, freeze or generate" + "description": "a step Tuldok provides: import, freeze, generate or annotate" }, "environment": { "type": "string", @@ -362,14 +363,6 @@ }, "then": { "properties": { - "command": { - "not": {}, - "description": "A run with step has no command; remove one of the two." - }, - "environment": { - "not": {}, - "description": "A step Tuldok provides runs with Tuldok's own interpreter; remove environment." - }, "outputs": { "not": {}, "description": "A step's outputs are fixed by the step; remove outputs." @@ -378,10 +371,6 @@ "not": {}, "description": "A step takes its settings inline; use settings, not settings_file." }, - "env": { - "not": {}, - "description": "A step Tuldok provides takes no environment variables; remove env." - }, "estimate": { "not": {}, "description": "A step Tuldok provides has no estimate command; remove estimate." @@ -395,7 +384,39 @@ "properties": { "annotations": { "not": {}, - "description": "annotations belong to a run with step freeze; add step or remove annotations." + "description": "annotations belong to a run with step freeze or annotate; add step or remove annotations." + } + } + } + }, + { + "if": { + "required": [ + "step" + ], + "properties": { + "step": { + "enum": [ + "import", + "freeze", + "generate" + ] + } + } + }, + "then": { + "properties": { + "command": { + "not": {}, + "description": "A run with step has no command; remove one of the two." + }, + "environment": { + "not": {}, + "description": "A step Tuldok provides runs with Tuldok's own interpreter; remove environment." + }, + "env": { + "not": {}, + "description": "A step Tuldok provides takes no environment variables; remove env." } } } diff --git a/tuldok_project/steps.py b/tuldok_project/steps.py index ca5100a2..ebc88365 100644 --- a/tuldok_project/steps.py +++ b/tuldok_project/steps.py @@ -49,7 +49,7 @@ 'mesh': ('.obj', '.stl'), 'array': ('.npy', '.npz', '.safetensors'), } -STEPS = ('import', 'freeze', 'generate') +STEPS = ('import', 'freeze', 'generate', 'annotate') RECORD_LIST = 'records.jsonl' FILES = 'files' DEFAULT_PATTERN = '**/*' @@ -66,6 +66,13 @@ MAKES = ('text', 'image') # what generate makes (spec-d5.md section 3) GENERATE_LIMIT = 100_000 # items one generate makes RETRY_PAUSES = (1.0, 2.0) # before asking again an item the endpoint did not admit; twice at most +ANNOTATED = 'annotations.jsonl' # an annotation set's lines (spec-t4.md section 3) +ANNOTATOR = 'annotator.json' # what made the set +ANNOTATOR_FORMAT = 'tuldok_annotator_v1' +TODO = 'todo.jsonl' # the records an annotator command is to annotate, in the run's directory +ANNOTATE_LIMIT = 1_000_000 # records one annotate annotates +ANNOTATE_LINE_BYTES = 64 * 1024 * 1024 # one line a command writes (a large polygon list) +GIVE_UP_AFTER = 10 # Pumas: every one of the first this many records refused fails the step class StepError(Exception): @@ -748,6 +755,327 @@ def _generated_record(output, identifier, make, made, rights, origin, counts): 'bytes': len(data), 'rights': rights, 'origin': origin} +# ---------------------------------------------------------------- annotate + +def _record_facts(root, record, task): + """What the value of task on record is checked against, as far as the step can tell from the file's head.""" + from . import annotation_payloads as payloads + facts = {'kind': record['kind'], 'size': None, 'points': None, 'shape': None} + path = record.get('path') + full = _confined(root, path) if isinstance(path, str) and '!' not in path else None + if full is None: + return facts + try: + with open(full, 'rb') as handle: + head = handle.read(64 * 1024) + if record['kind'] == 'image' and head.startswith(b'\x89PNG'): + facts['size'] = payloads.png_size(head)[:2] + elif record['kind'] == 'array' and head.startswith(b'\x93NUMPY'): + facts['shape'] = payloads.npy_header(head)[0] + elif record['kind'] == 'pointcloud' and task in ('points', 'box3d'): + facts['points'] = _cloud_count(full, head) + except (OSError, payloads.PayloadError): + pass + return facts + + +def _cloud_count(full, head): + """The points of a .ply (its vertex element), an .npy (its first axis) or an .xyz (its rows of numbers).""" + from . import annotation_payloads as payloads + if head.startswith(b'ply'): + for line in head.split(b'end_header', 1)[0].decode('ascii', 'replace').splitlines(): + words = line.split() + if len(words) == 3 and words[:2] == ['element', 'vertex'] and words[2].isdigit(): + return int(words[2]) + return None + if head.startswith(b'\x93NUMPY'): + return payloads.npy_header(head)[0][0] + count = 0 + with open(full, 'rb') as handle: + for line in handle: + words = line.decode('utf-8', 'replace').replace(',', ' ').split() + if len(words) >= 3 and not words[0].startswith('#'): + try: + [float(word) for word in words[:3]] + except ValueError: + continue + count += 1 + return count + + +def _set_line(raw, task, by_id, root, output, facts_of, counts): + """(record, line to keep) from one line an annotator wrote, or None with the reason counted.""" + from . import annotation_payloads as payloads + try: + value = json.loads(raw) + except (ValueError, RecursionError): + counts['not_json'] += 1 + return None + if not isinstance(value, dict) or not isinstance(value.get('record'), str) or 'value' not in value \ + or set(value) - {'record', 'sha256', 'value', 'confidence', 'note'}: + counts['not_lines'] += 1 + return None + record = by_id.get(value['record']) + if record is None: + counts['unknown_records'] += 1 + return None + confidence, note = value.get('confidence'), value.get('note') + if (confidence is not None and not (isinstance(confidence, (int, float)) and not isinstance(confidence, bool) + and 0 <= confidence <= 1)) \ + or (note is not None and not (isinstance(note, str) and len(note) <= annotations.NOTE_LIMIT)): + counts['invalid'] += 1 + return None + facts = facts_of(record) + document = task['document'] + errors, unknown = annotations.value_problems( + document['task'], document.get('vocabulary') or [], 'accepted', value['value'], kind=record['kind'], + size=facts['size'], fields=annotations.task_fields(document), points=facts['points'], shape=facts['shape']) + if errors or unknown or value['value'] is None: + counts['invalid'] += 1 + return None + for name in annotations.sidecars(document['task'], value['value']): + full = os.path.realpath(os.path.join(output, FILES, *name.split('/'))) + if not _inside(full, os.path.join(os.path.realpath(output), FILES)) or not os.path.isfile(full): + counts['missing_sidecars'] += 1 + return None + with open(full, 'rb') as handle: + data = handle.read(payloads.SIDECAR_LIMIT + 1) + if payloads.sidecar_problem(document['task'], data, size=facts['size'], points=facts['points']): + counts['invalid'] += 1 + return None + line = {'record': value['record'], 'sha256': _record_hash(root, record), 'value': value['value']} + if confidence is not None: + line['confidence'] = confidence + if note is not None: + line['note'] = note + return value['record'], line + + +def _set_text(line): + """One line of an annotation set: record, sha256, value (its keys as a line file orders them), confidence, note.""" + ordered = {'record': line['record'], 'sha256': line['sha256'], 'value': annotations.ordered_value(line['value'])} + for key in ('confidence', 'note'): + if key in line: + ordered[key] = line[key] + return json.dumps(ordered, ensure_ascii=False, separators=(',', ':')) + '\n' + + +def _read_written(path, task, by_id, root, output, facts_of, counts): + """The lines an annotator appended to path, the last valid one of each record kept.""" + kept = {} + if not os.path.isfile(path): + return kept + with open(path, 'rb') as handle: + for raw in handle: + if len(raw) > ANNOTATE_LINE_BYTES: + counts['not_lines'] += 1 + continue + if not raw.strip(): + continue + found = _set_line(raw, task, by_id, root, output, facts_of, counts) + if found is not None: + if found[0] in kept: + counts['repeated'] += 1 + kept[found[0]] = found[1] + return kept + + +def _resumed(resume, task, by_id, root, output, facts_of, counts): + """The valid lines (and their sidecars) of an earlier run of this definition whose records' hashes still hold.""" + kept = {} + path = os.path.join(resume, ANNOTATED) + if not os.path.isfile(path): + return kept + with open(path, 'rb') as handle: + for raw in handle: + try: + value = json.loads(raw) + except (ValueError, RecursionError): + continue + if not isinstance(value, dict) or value.get('record') not in by_id: + continue + record = by_id[value['record']] + if value.get('sha256') is not None and value.get('sha256') != _record_hash(root, record): + continue + for name in annotations.sidecars(task['document']['task'], value.get('value')): + parts = str(name).split('/') + if str(name).startswith('/') or '..' in parts or '' in parts: + continue + source = os.path.realpath(os.path.join(resume, FILES, *parts)) + if _inside(source, os.path.join(os.path.realpath(resume), FILES)) and os.path.isfile(source): + target = os.path.join(output, FILES, *parts) + os.makedirs(os.path.dirname(target), exist_ok=True) + shutil.copyfile(source, target) + found = _set_line(raw, task, by_id, root, output, facts_of, counts) + if found is not None: + kept[found[0]] = found[1] + counts['resumed'] = len(kept) + return kept + + +def _child_env(variables): + """The environment of an annotator command: the run's, without what makes Tuldok's own code importable.""" + env = {key: value for key, value in os.environ.items() if key not in ('PYTHONSAFEPATH', 'PYTHONPATH')} + if os.environ.get('TULDOK_ANNOTATE_PYTHONPATH'): + env['PYTHONPATH'] = env.pop('TULDOK_ANNOTATE_PYTHONPATH') + env.update(variables) + return env + + +def _ask_pumas(settings, task, todo, by_id, root, output, endpoint, lines, facts_of, counts, out, progress): + """Annotate the records of todo by asking a served model, appending a line for each answer that fits.""" + from . import pumas + document = task['document'] + asked = settings['pumas'] + try: + listing = pumas.served(endpoint) + entry = pumas.choose(listing, asked['model'], asked.get('profile')) + except pumas.PumasError as exc: + raise StepError(f'The Pumas endpoint at {endpoint} cannot be asked: {exc}') from None + capability = None + token = uuid.uuid4().hex[:16] + for number, record_id in enumerate(todo, 1): + record = by_id[record_id] + found = pumas.routes(entry, document['task'], record['kind']) + if not found: + counts['refused'] += 1 + else: + capability = found[0]['capability'] + facts = facts_of(record) + try: + content = _record_content(root, record) + value = pumas.suggest( + endpoint, listing, entry, found[0], document['task'], document.get('vocabulary') or [], + content, asked.get('instruction'), request_id=f'tuldok-annotate:{token}:{number}', + size=facts['size'], + check=lambda v: _fits(document, record, facts, v)) + except pumas.PumasError as exc: + if exc.code not in ('unsuitable', 'invalid'): + raise StepError(f'Record {record_id!r}: {exc}') from None + counts['refused'] += 1 + out(f'Record {record_id}: {exc}') + else: + line = {'record': record_id, 'sha256': _record_hash(root, record), 'value': value} + lines.write(_set_text(line)) + lines.flush() + counts['made'] += 1 + if number == min(GIVE_UP_AFTER, len(todo)) and not counts['made'] and counts['refused'] == number: + raise StepError(f'The model refused or could not answer every one of the first {number} records.') + progress(number, {'made': counts['made'], 'refused': counts['refused']}) + return {'kind': 'model', 'name': entry['model'], 'version': entry['profile'], + 'capability': capability} + + +def _fits(document, record, facts, value): + """The problems of a model's answer as a value of the task, terms outside the vocabulary included.""" + errors, unknown = annotations.value_problems(document['task'], document.get('vocabulary') or [], 'accepted', value, + kind=record['kind'], size=facts['size'], + fields=annotations.task_fields(document)) + return errors + [f'The term {term!r} is not in the vocabulary of the task.' for term in unknown] + + +def _record_content(root, record): + """{kind, text} or {kind, data} of a record, read whole up to the bound a suggestion sends.""" + if record.get('path') is None: + return {'kind': record['kind'], 'text': record.get('text') or ''} + full = _confined(root, record['path']) if '!' not in record['path'] else None + if full is None: + from . import pumas + raise pumas.PumasError(f'The record {record["id"]!r} cannot be read here.', 'invalid') + with open(full, 'rb') as handle: + data = handle.read(16 * 1024 * 1024 + 1) + if record['kind'] == 'text': + return {'kind': 'text', 'text': data.decode('utf-8', 'replace')} + return {'kind': record['kind'], 'data': data} + + +def annotate_records(settings, output, *, records, task, run_directory, command=None, code=None, endpoint=None, + resume=None, out=print): + """The annotate step (spec-t4.md section 4): an annotation set of task for the records of the input product. + + task is {'reference', 'document'}; command the annotator's argv (run from + code), or None to ask the model settings.pumas names at endpoint; resume + the output directory of an earlier run of the same definition. Returns + the counts. + """ + root = os.path.realpath(records) + counts = dict.fromkeys(('bad_lines', 'resumed', 'made', 'refused', 'not_json', 'not_lines', 'unknown_records', + 'invalid', 'missing_sidecars', 'repeated'), 0) + by_id = _input_records(root, None, counts) + facts_cache = {} + + def facts_of(record): + if record['id'] not in facts_cache: + facts_cache[record['id']] = _record_facts(root, record, task['document']['task']) + return facts_cache[record['id']] + os.makedirs(os.path.join(output, FILES), exist_ok=True) + kept = _resumed(resume, task, by_id, root, output, facts_of, counts) if resume else {} + limit = settings.get('limit', ANNOTATE_LIMIT) + todo = [record_id for record_id in by_id if record_id not in kept and annotations.allows_kind( + task['document']['task'], by_id[record_id]['kind'])][:max(0, limit - len(kept))] + out(f'{len(todo)} records to annotate for {task["reference"]}' + (f'; {len(kept)} kept from the run before' + if kept else '') + '.') + progress = Progress('annotate', len(todo), out) + progress(0, {}) + path = os.path.join(output, ANNOTATED) + with open(path, 'w', encoding='utf-8') as lines: + for record_id in sorted(kept, key=annotations.sort_key): + lines.write(_set_text(kept[record_id])) + by = dict(settings['by']) + if command is not None: + todo_path = os.path.join(run_directory, TODO) + with open(todo_path, 'w', encoding='utf-8') as handle: + for record_id in todo: + record = dict(by_id[record_id]) + record.pop('hash', None) + if record.get('path') is not None and '!' not in record['path']: + record['path'] = os.path.join(root, *record['path'].split('/')) + handle.write(_line(record)) + task_path = os.path.join(run_directory, 'task.json') + with open(task_path, 'w', encoding='utf-8') as handle: + json.dump(dict(task['document'], reference=task['reference']), handle, ensure_ascii=False, indent=2) + import subprocess + env = _child_env({'TULDOK_RECORDS': root, 'TULDOK_TODO': todo_path, 'TULDOK_TASK': task_path, + 'TULDOK_ANNOTATIONS': os.path.abspath(path), + 'TULDOK_FILES': os.path.abspath(os.path.join(output, FILES)), + 'TULDOK_ANNOTATE_OPTIONS': json.dumps(settings.get('options') or {})}) + status = subprocess.call(command, cwd=code or run_directory, env=env, stdin=subprocess.DEVNULL) + if status != 0: + raise StepError(f'The annotator command ended with status {status}; what it wrote is kept for the next ' + 'build to resume from.') + else: + if endpoint is None: + raise StepError('An annotate asking a model needs --endpoint, the Pumas endpoint this machine uses.') + with open(path, 'a', encoding='utf-8') as lines: + made = _ask_pumas(settings, task, todo, by_id, root, output, endpoint, lines, facts_of, counts, out, + progress) + by.setdefault('kind', 'model') + by.setdefault('name', made['name']) + by['model'] = {'model': made['name'], 'profile': made['version'], 'capability': made['capability']} + final = _read_written(path, task, by_id, root, output, facts_of, counts) + with open(path, 'w', encoding='utf-8') as lines: + for record_id in sorted(final, key=annotations.sort_key): + lines.write(_set_text(final[record_id])) + by['settings'] = {key: value for key, value in settings.items() if key != 'by'} + annotator = {'format': ANNOTATOR_FORMAT, 'task': task['reference'], 'by': by, 'records': len(by_id), + 'made': len(final), 'at': time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime())} + with open(os.path.join(output, ANNOTATOR), 'w', encoding='utf-8') as handle: + json.dump(annotator, handle, ensure_ascii=False, indent=2) + handle.write('\n') + counts['kept'] = len(final) + progress(len(todo), {'kept': len(final)}, final=True) + out(f'{len(final)} records annotated for {task["reference"]}.') + _say(out, counts, (('refused', 'records the model could not annotate were skipped.'), + ('not_json', 'lines the annotator wrote are not JSON and were dropped.'), + ('not_lines', 'lines the annotator wrote are not annotation lines and were dropped.'), + ('unknown_records', 'lines name a record the input does not have and were dropped.'), + ('invalid', 'lines hold a value the task does not allow and were dropped.'), + ('missing_sidecars', 'lines name a sidecar that is not under files/ and were dropped.'), + ('repeated', 'records were annotated more than once; the last line of each is kept.'), + ('bad_lines', f'lines of the input\'s {RECORD_LIST} are not records and were skipped.'))) + return counts + + # --------------------------------------------------------------- command line def _arguments(argv): @@ -761,6 +1089,10 @@ def _arguments(argv): parser.add_argument('--tasks', help='freeze: a JSON file of the tasks and their line files') parser.add_argument('--endpoint', help='generate: the Pumas endpoint this machine uses') parser.add_argument('--report', help='generate: a file to write the endpoint\'s address and version to') + parser.add_argument('--task', help='annotate: a JSON file {reference, document} of the task') + parser.add_argument('--command-json', help='annotate: the annotator command\'s argv as JSON') + parser.add_argument('--resume', help='annotate: the output of an earlier run of the same definition') + parser.add_argument('--run-directory', help='annotate: the run\'s directory') return parser.parse_args(argv) @@ -774,6 +1106,15 @@ def main(argv=None): raise StepError(f'The output directory {arguments.output} does not exist.') if arguments.step == 'import': import_files(settings, arguments.output, code_root=arguments.code, out=out) + elif arguments.step == 'annotate': + if arguments.records is None or arguments.task is None or arguments.run_directory is None: + raise StepError('annotate needs --records, --task and --run-directory.') + with open(arguments.task, encoding='utf-8') as handle: + task = json.load(handle) + annotate_records(settings, arguments.output, records=arguments.records, task=task, + run_directory=arguments.run_directory, + command=json.loads(arguments.command_json) if arguments.command_json else None, + code=arguments.code, endpoint=arguments.endpoint, resume=arguments.resume, out=out) elif arguments.step == 'generate': if arguments.endpoint is None: raise StepError('generate needs --endpoint, the Pumas endpoint this machine uses.') From e9f196b4114ada4133685a68e2f80da95d5e3103 Mon Sep 17 00:00:00 2001 From: MrScripty <TheEnvironmentGuy@protonmail.com> Date: Thu, 19 Nov 2026 07:00:10 -0700 Subject: [PATCH 111/131] feat(project): agreement between annotation sets and the most disputed records Per type: kappas, Kendall's tau, interval IoU, matched IoU (boxes, polygons on a grid, rotated 3-D boxes, point sets, instance masks; Hungarian up to 64 objects a term, greedy above), semantic mask IoU, OKS, depth difference, track IoU with identity switches and fragments; a confidence filter and the disputed list. Tested against the test's own arithmetic. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --- ...est_tuldok_project_annotation_agreement.py | 233 +++++++ tuldok_project/annotation_agreement.py | 597 ++++++++++++++++++ 2 files changed, 830 insertions(+) create mode 100644 tests/test_tuldok_project_annotation_agreement.py create mode 100644 tuldok_project/annotation_agreement.py diff --git a/tests/test_tuldok_project_annotation_agreement.py b/tests/test_tuldok_project_annotation_agreement.py new file mode 100644 index 00000000..338a4469 --- /dev/null +++ b/tests/test_tuldok_project_annotation_agreement.py @@ -0,0 +1,233 @@ +"""Agreement between annotation sets (spec-t4.md section 5, slice T4c) and the four operations (section 6, T4d). + +The measures are checked against arithmetic done here, on hand-made values: +kappas on a known table, Kendall's tau, interval IoU, box, polygon, mask +(instance and semantic), point-set and rotated 3-D box IoU, OKS, track +switches and fragments, the Hungarian matching against brute force, the +confidence filter and the order of the disputed list. The operations are +then asked of a Service on the stand-in segmentors' sets of +test_tuldok_project_annotate_step (database only). +""" +import itertools +import math +from pathlib import Path +import random +import sys +import unittest + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) +sys.path.insert(0, str(Path(__file__).resolve().parent)) + +from tuldok_project import annotation_agreement as agree, annotation_payloads as payloads # noqa: E402 + + +def entry(value, confidence=None): + found = {'value': value} + if confidence is not None: + found['confidence'] = confidence + return found + + +class Measures(unittest.TestCase): + def test_cohen_kappa_on_a_known_table(self): + # 50 records: both yes 20, a yes b no 5, a no b yes 10, both no 15. + pairs = [('yes', 'yes')] * 20 + [('yes', 'no')] * 5 + [('no', 'yes')] * 10 + [('no', 'no')] * 15 + observed = 35 / 50 + expected = (25 / 50) * (30 / 50) + (25 / 50) * (20 / 50) + self.assertAlmostEqual(agree.cohen_kappa(pairs), (observed - expected) / (1 - expected)) + self.assertAlmostEqual(agree.cohen_kappa(pairs), 0.4) + self.assertEqual(agree.cohen_kappa([('a', 'a')] * 3), 1.0) + self.assertIsNone(agree.cohen_kappa([])) + + def test_fleiss_kappa(self): + # Three raters, four records: (a,a,a), (a,a,b), (b,b,b), (a,b,b). + rows = [['a', 'a', 'a'], ['a', 'a', 'b'], ['b', 'b', 'b'], ['a', 'b', 'b']] + per_record = [(9 - 3) / 6, (4 + 1 - 3) / 6, (9 - 3) / 6, (1 + 4 - 3) / 6] + observed = sum(per_record) / 4 + share_a, share_b = 6 / 12, 6 / 12 + expected = share_a ** 2 + share_b ** 2 + self.assertAlmostEqual(agree.fleiss_kappa(rows), (observed - expected) / (1 - expected)) + + def test_kendall_tau(self): + self.assertEqual(agree.kendall_tau(['a', 'b', 'c'], ['a', 'b', 'c']), 1.0) + self.assertEqual(agree.kendall_tau(['a', 'b', 'c'], ['c', 'b', 'a']), -1.0) + # a b c d against b a c d: one discordant pair of six. + self.assertAlmostEqual(agree.kendall_tau(list('abcd'), list('bacd')), (5 - 1) / 6) + self.assertEqual(agree.kendall_tau(['a', 'x'], ['a', 'y']), 1.0) # one shared + score, figures = agree.compare({'task': 'ranking'}, list('abcd'), list('bacd')) + self.assertAlmostEqual(score, (4 / 6 + 1) / 2) + + def test_interval_iou(self): + # [0,4] against [2,6]: 2 over 6. Merged unions: [0,1]+[1,3] is [0,3]. + self.assertAlmostEqual(agree.interval_iou([(0, 4)], [(2, 6)]), 2 / 6) + self.assertAlmostEqual(agree.interval_iou([(0, 1), (1, 3)], [(0, 3)]), 1.0) + a = [{'term': 'x', 'start': 0, 'end': 4}, {'term': 'y', 'start': 0, 'end': 2}] + b = [{'term': 'x', 'start': 2, 'end': 6}] + self.assertAlmostEqual(agree.compare({'task': 'timeseries'}, a, b)[0], (2 / 6 + 0) / 2) + + def test_boxes_and_matching(self): + self.assertAlmostEqual(agree.box_iou((0, 0, 4, 4), (2, 0, 4, 4)), 8 / 24) + a = [{'term': 'c', 'x': 0, 'y': 0, 'w': 4, 'h': 4}, {'term': 'c', 'x': 10, 'y': 10, 'w': 2, 'h': 2}] + b = [{'term': 'c', 'x': 10, 'y': 10, 'w': 2, 'h': 2}, {'term': 'c', 'x': 2, 'y': 0, 'w': 4, 'h': 4}, + {'term': 'd', 'x': 0, 'y': 0, 'w': 4, 'h': 4}] + score, figures = agree.compare({'task': 'boxes'}, a, b) + self.assertAlmostEqual(score, (1 + 8 / 24) / 3) + self.assertEqual(figures['matches'], 2) + self.assertAlmostEqual(figures['mean_iou'], (1 + 8 / 24) / 2) + self.assertAlmostEqual(figures['f1'], 2 * 1 / 5) + self.assertEqual(agree.compare({'task': 'boxes'}, [], []), (1.0, {'matches': 0, 'mean_iou': None, 'f1': 1.0})) + + def test_hungarian_against_brute_force(self): + rng = random.Random(4) + for rows, columns in ((3, 3), (2, 5), (5, 2), (6, 6)): + table = [[rng.random() for _ in range(columns)] for _ in range(rows)] + chosen = agree.hungarian(table) + best = max((sum(table[r][c] for r, c in zip(order, perm)) for order in [range(rows)] + for perm in itertools.permutations(range(columns), rows)) if rows <= columns else + (sum(table[r][c] for r, c in zip(perm, range(columns))) + for perm in itertools.permutations(range(rows), columns))) + self.assertAlmostEqual(sum(table[r][c] for r, c in chosen), best) + self.assertEqual(len(chosen), min(rows, columns)) + + def test_polygon_iou(self): + # A 10 by 10 square and a 5 by 10 half of it: 50 of 100 pixel centres. + square = [(0, 0), (10, 0), (10, 10), (0, 10)] + half = [(0, 0), (5, 0), (5, 10), (0, 10)] + self.assertAlmostEqual(agree.polygon_iou(square, half), 0.5) + # A triangle covering half the square: on the grid, the centres under the diagonal (45 of 100 strictly). + triangle = [(0, 0), (10, 0), (0, 10)] + under = sum(1 for x in range(10) for y in range(10) if x + 0.5 + y + 0.5 < 10) + self.assertAlmostEqual(agree.polygon_iou(square, triangle), under / 100) + # Large polygons are drawn on at most GRID cells a side. + big = [(0, 0), (1000, 0), (1000, 1000), (0, 1000)] + self.assertAlmostEqual(agree.polygon_iou(big, [(0, 0), (500, 0), (500, 1000), (0, 1000)]), 0.5) + + def test_box3d_iou(self): + unit = ([0, 0, 0], [2, 2, 2], 0.0) + self.assertAlmostEqual(agree.box3d_iou(unit, unit), 1.0) + shifted = ([1, 0, 0], [2, 2, 2], 0.0) + self.assertAlmostEqual(agree.box3d_iou(unit, shifted), 4 / 12) + # Turned by 45 degrees: a 2 by 2 square and its turned copy overlap in a regular octagon. + side = 2 * (math.sqrt(2) - 1) + octagon = 2 * (1 + math.sqrt(2)) * side ** 2 + turned = ([0, 0, 0], [2, 2, 2], math.pi / 4) + self.assertAlmostEqual(agree.box3d_iou(unit, turned), octagon * 2 / (16 - octagon * 2)) + # Half the height overlapping. + self.assertAlmostEqual(agree.box3d_iou(unit, ([0, 0, 1], [2, 2, 2], 0.0)), 4 / 12) + + def test_point_sets_and_files(self): + a = [{'term': 'car', 'indices': [0, 1, 2, 3]}] + b = [{'term': 'car', 'indices': [2, 3, 4]}] + self.assertAlmostEqual(agree.compare({'task': 'points'}, a, b)[0], 2 / 5) + ids = payloads.write_npy([6], [0, 0, 1, 1, 1, 0], '<i4') + value = {'file': 'ids.npy', 'classes': {'1': 'car'}} + score, _ = agree.compare({'task': 'points'}, a, value, None, lambda name: ids) + self.assertAlmostEqual(score, 2 / 5) # {0,1,2,3} against {2,3,4} + + def test_masks(self): + # Two 4 by 2 instance masks: a has objects 1 (3 px) and 2 (2 px); b has 1 (2 px of a's 1) and 5 (b's 2's px). + a = {'rle': [[1, 3], [0, 1], [2, 2], [0, 2]], 'classes': {'1': 'cell', '2': 'cell'}} + b = {'rle': [[1, 2], [0, 2], [5, 2], [0, 2]], 'classes': {'1': 'cell', '5': 'cell'}} + score, figures = agree.compare({'task': 'mask', 'mask': 'instance'}, a, b) + self.assertAlmostEqual(score, (2 / 3 + 1) / 2) + self.assertEqual(figures['matches'], 2) + # The same pixels as a semantic mask: cell is 5 pixels in a, 4 in b, 4 together. + score, figures = agree.compare({'task': 'mask'}, a, b) + self.assertAlmostEqual(score, 4 / 5) + # From a PNG sidecar against runs. + png = payloads.write_png(4, 2, [1, 1, 1, 0, 2, 2, 0, 0]) + score, _ = agree.compare({'task': 'mask', 'mask': 'instance'}, {'file': 'm.png', 'classes': a['classes']}, + a, lambda name: png) + self.assertEqual(score, 1.0) + with self.assertRaises(agree.AgreementProblem): + agree.compare({'task': 'mask'}, a, {'rle': [[0, 9]], 'classes': {'1': 'cell'}}) + + def test_depth(self): + first = payloads.write_npy([1, 4], [1.0, 2.0, 0.0, 4.0], '<f4') + second = payloads.write_npy([1, 4], [1.0, 3.0, 5.0, 4.0], '<f4') + score, figures = agree.compare({'task': 'depth'}, {'file': 'a.npy'}, {'file': 'b.npy'}, + lambda n: first, lambda n: second) + # Pixels with depth in both: 1/1, 2/3, 4/4. Mean |a-b| 1/3; mean (|a|+|b|)/2 = (1 + 2.5 + 4) / 3. + self.assertAlmostEqual(figures['mean_abs'], 1 / 3) + self.assertAlmostEqual(score, 1 - (1 / 3) / (7.5 / 3)) + self.assertAlmostEqual(figures['delta'], 2 / 3) # 3/2 is not below 1.25 + + def test_keypoints_oks(self): + a = [[0, 0, 2], [10, 0, 2], [10, 10, 2]] + b = [[0, 0, 2], [10, 0, 2], [10, 13, 1]] + # Areas: a 10 x 10 = 100, b 10 x 13 = 130; s² = 115; one point off by 3. + expected = (1 + 1 + math.exp(-9 / (2 * 115 * 0.01))) / 3 + self.assertAlmostEqual(agree.oks(a, b), expected) + self.assertAlmostEqual(agree.oks(a, [[0, 0, 2], None, [10, 10, 0]]), 1 / 3) + score, figures = agree.compare({'task': 'keypoints'}, [{'term': 'p', 'points': a}], + [{'term': 'p', 'points': b}]) + self.assertAlmostEqual(score, expected) + self.assertAlmostEqual(figures['mean_oks'], expected) + + def test_tracks(self): + def track(identifier, frames, x=0): + return {'track': identifier, 'term': 'car', + 'frames': [{'frame': f, 'x': x, 'y': 0, 'w': 4, 'h': 4} for f in frames]} + a = [track('1', [0, 1, 2, 3])] + # b follows a's object as two tracks (a switch at frame 2) with a gap in the first (a fragment). + b = [track('x', [0, 1]), track('y', [2, 3])] + score, figures = agree.compare({'task': 'track'}, a, b) + self.assertEqual(figures['switches'], 1) + self.assertEqual(figures['fragments'], [0, 0]) + self.assertAlmostEqual(score, (2 / 4) / 2) # 1's match covers half its frames; the larger count is 2 + gappy = [track('1', [0, 1, 3, 6])] + self.assertEqual(agree.fragments(agree._tracks(gappy)), 2) + + def test_text_and_tags(self): + self.assertAlmostEqual(agree.compare({'task': 'tags'}, ['a', 'b'], ['b', 'c'])[0], 1 / 3) + self.assertEqual(agree.compare({'task': 'tags'}, [], [])[0], 1.0) + self.assertEqual(agree.compare({'task': 'text'}, 'abcd', 'abcd'), (1.0, {'exact': True})) + self.assertAlmostEqual(agree.compare({'task': 'text'}, 'abcd', 'abxd')[0], 2 * 3 / 8) + + +class Sets(unittest.TestCase): + def test_the_disputed_list_and_its_order(self): + sets = {'kept': {'r1': entry('a'), 'r2': entry('a'), 'r3': entry('b')}, + 'datasets/x': {'r1': entry('a'), 'r2': entry('b'), 'r3': entry('b'), 'r4': entry('a')}, + 'datasets/y': {'r1': entry('a'), 'r2': entry('b'), 'r3': entry('a'), 'r4': entry('a')}} + found = agree.agreement({'task': 'class'}, sets) + rows = {row['record']: row for row in found['disputed']} + # r4: kept lacks it, so kept-x and kept-y score 0, x-y 1: disagreement 1 - 1/3. + self.assertAlmostEqual(rows['r4']['disagreement'], 2 / 3) + self.assertEqual(rows['r4']['missing'], ['kept']) + # r2: a, b, b -> pairs 0, 0, 1; r3: b, b, a -> 1, 0, 0; both 2/3; r1 0. + self.assertEqual([row['record'] for row in found['disputed']], ['r2', 'r3', 'r4', 'r1']) + pairs = {(p['a'], p['b']): p for p in found['pairs']} + self.assertEqual(pairs[('kept', 'datasets/x')]['records'], 4) + self.assertAlmostEqual(pairs[('kept', 'datasets/x')]['agreement'], 2 / 4) + # Cohen's kappa over the records both annotated (r1 a-a, r2 a-b, r3 b-b). + self.assertAlmostEqual(pairs[('kept', 'datasets/x')]['kappa'], + agree.cohen_kappa([('a', 'a'), ('a', 'b'), ('b', 'b')])) + self.assertAlmostEqual(found['fleiss'], agree.fleiss_kappa([['a', 'a', 'a'], ['a', 'b', 'b'], + ['b', 'b', 'a']])) + page = agree.agreement({'task': 'class'}, sets, offset=1, limit=2) + self.assertEqual([row['record'] for row in page['disputed']], ['r3', 'r4']) + self.assertEqual(page['total'], 4) + + def test_the_confidence_filter(self): + a = {'r1': entry([{'term': 'c', 'x': 0, 'y': 0, 'w': 2, 'h': 2, 'confidence': 0.9}, + {'term': 'c', 'x': 5, 'y': 5, 'w': 2, 'h': 2, 'confidence': 0.2}]), + 'r2': entry([{'term': 'c', 'x': 0, 'y': 0, 'w': 2, 'h': 2}], confidence=0.1)} + b = {'r1': entry([{'term': 'c', 'x': 0, 'y': 0, 'w': 2, 'h': 2}]), + 'r2': entry([{'term': 'c', 'x': 0, 'y': 0, 'w': 2, 'h': 2}])} + loose = agree.agreement({'task': 'boxes'}, {'a': a, 'b': b}) + strict = agree.agreement({'task': 'boxes'}, {'a': a, 'b': b}, min_confidence=0.5) + self.assertAlmostEqual(loose['pairs'][0]['agreement'], (0.5 + 1) / 2) + # r1 loses its low box (agreement 1); r2's whole line is under the filter: missing in a, so 0. + self.assertAlmostEqual(strict['pairs'][0]['agreement'], (1 + 0) / 2) + self.assertEqual(strict['disputed'][0]['missing'], ['a']) + + def test_refusals(self): + with self.assertRaises(agree.AgreementProblem): + agree.agreement({'task': 'review'}, {'a': {}, 'b': {}}) + with self.assertRaises(agree.AgreementProblem): + agree.agreement({'task': 'class'}, {'a': {}}) + + +if __name__ == '__main__': + unittest.main() diff --git a/tuldok_project/annotation_agreement.py b/tuldok_project/annotation_agreement.py new file mode 100644 index 00000000..45091627 --- /dev/null +++ b/tuldok_project/annotation_agreement.py @@ -0,0 +1,597 @@ +"""Agreement between annotation sets: per record, per pair of sets, and the most disputed records. + +Owns section 5 of docs/plans/training-and-curation/spec-t4.md: how far two +or more sets of one task agree on each record (a number from 0 to 1), the +figures each type also reports (Cohen's and Fleiss' kappa, Kendall's tau, +IoU of matched objects, OKS, identity switches and fragments), the +confidence filter, and the order of the disputed list. It is pure and uses +the standard library alone: values come in as the sets hold them, and the +payload of a mask, a depth map or a point-id file is read through a loader +the caller gives (bytes of a sidecar). Nothing is written. + +A set is {record: {'value', 'confidence'?}}. A record's agreement for a pair +is 0 when one side has no annotation of it (or the filter emptied it). +""" +from array import array +import difflib +import itertools +import math + +from . import annotation_payloads as payloads + +SETS_LIMIT = 8 +HUNGARIAN_LIMIT = 64 # objects of one term per side matched exactly; above, greedily +GRID = 128 # cells across a polygon pair's joint box, at most +TEXT_COMPARED = 4000 # characters of a text compared +OKS_SIGMA = 0.1 # spread of a keypoint (the task may say sigma) +MATCH_IOU = 0.5 # an identity switch follows matches above this IoU; F1 counts them +DEPTH_RATIO = 1.25 # the δ of depth agreement + +MEASURES = { + 'class': 'Equal terms score 1. Cohen\'s kappa per pair; Fleiss\' kappa over the records every set annotated.', + 'tags': 'Jaccard of the two sets of terms.', + 'text': 'The similarity of the two texts (difflib ratio of their first 4,000 characters).', + 'ranking': '(τ + 1) / 2, Kendall\'s τ over the candidates both rank.', + 'boxes': 'Matched IoU: boxes of the same term matched one to one; summed IoU over the larger count.', + 'polygons': 'Matched IoU: polygons of the same term matched one to one; summed IoU over the larger count.', + 'box3d': 'Matched IoU: 3-D boxes of the same term matched one to one; summed IoU over the larger count.', + 'points': 'Matched IoU: point objects of the same term matched one to one; summed IoU over the larger count.', + 'mask': 'Instance masks: matched IoU of their objects. Semantic masks: mean pixel IoU over the terms used.', + 'keypoints': 'Matched OKS: instances of the same term matched one to one; summed OKS over the larger count.', + 'depth': '1 − mean |a − b| / mean (|a| + |b|) / 2 over the pixels with depth in both.', + 'spans': 'Mean over the terms used of the interval IoU.', + 'segments': 'Mean over the terms used of the interval IoU.', + 'timeseries': 'Mean over the terms used of the interval IoU.', + 'track': 'Matched track IoU: tracks of the same term matched one to one by their mean box IoU over the frames ' + 'either has; summed over the larger count.', +} + + +class AgreementProblem(Exception): + """A task or a value that cannot be compared; the message is a sentence.""" + + +# ------------------------------------------------------------- geometry + +def box_iou(a, b): + """IoU of two boxes (x, y, w, h).""" + ix = max(0.0, min(a[0] + a[2], b[0] + b[2]) - max(a[0], b[0])) + iy = max(0.0, min(a[1] + a[3], b[1] + b[3]) - max(a[1], b[1])) + inter = ix * iy + union = a[2] * a[3] + b[2] * b[3] - inter + return inter / union if union > 0 else 0.0 + + +def _inside(x, y, polygon): + """Even-odd rule.""" + hit = False + for (x1, y1), (x2, y2) in zip(polygon, polygon[1:] + polygon[:1]): + if (y1 > y) != (y2 > y) and x < x1 + (y - y1) * (x2 - x1) / (y2 - y1): + hit = not hit + return hit + + +def polygon_iou(a, b): + """IoU of two polygons drawn on a grid over their joint box: at most GRID cells a side, pixel centres.""" + xs = [p[0] for p in a + b] + ys = [p[1] for p in a + b] + x0, y0, x1, y1 = math.floor(min(xs)), math.floor(min(ys)), math.ceil(max(xs)), math.ceil(max(ys)) + step = max(1.0, max(x1 - x0, y1 - y0) / GRID) + both = either = 0 + y = y0 + step / 2 + while y < y1: + x = x0 + step / 2 + while x < x1: + in_a, in_b = _inside(x, y, a), _inside(x, y, b) + both += in_a and in_b + either += in_a or in_b + x += step + y += step + return both / either if either else 0.0 + + +def _corners(centre, size, yaw): + c, s = math.cos(yaw), math.sin(yaw) + half = ((size[0] / 2, size[1] / 2), (-size[0] / 2, size[1] / 2), (-size[0] / 2, -size[1] / 2), + (size[0] / 2, -size[1] / 2)) + return [(centre[0] + c * dx - s * dy, centre[1] + s * dx + c * dy) for dx, dy in half] + + +def _clip(subject, edge_a, edge_b): + """Sutherland-Hodgman: subject clipped by the half plane left of edge a -> b.""" + def left(p): + return (edge_b[0] - edge_a[0]) * (p[1] - edge_a[1]) - (edge_b[1] - edge_a[1]) * (p[0] - edge_a[0]) >= 0 + + def cross(p, q): + dx1, dy1 = q[0] - p[0], q[1] - p[1] + dx2, dy2 = edge_b[0] - edge_a[0], edge_b[1] - edge_a[1] + denominator = dx1 * dy2 - dy1 * dx2 + t = ((edge_a[0] - p[0]) * dy2 - (edge_a[1] - p[1]) * dx2) / denominator + return (p[0] + t * dx1, p[1] + t * dy1) + out = [] + for p, q in zip(subject, subject[1:] + subject[:1]): + if left(q): + if not left(p): + out.append(cross(p, q)) + out.append(q) + elif left(p): + out.append(cross(p, q)) + return out + + +def _area(polygon): + return abs(sum(p[0] * q[1] - q[0] * p[1] for p, q in zip(polygon, polygon[1:] + polygon[:1]))) / 2 + + +def box3d_iou(a, b): + """IoU of two 3-D boxes (center, size, yaw about z): rotated footprints intersected, times the height overlap.""" + footprint = _corners(a[0], a[1], a[2]) + for p, q in zip(_corners(b[0], b[1], b[2]), _corners(b[0], b[1], b[2])[1:] + _corners(b[0], b[1], b[2])[:1]): + if not footprint: + break + footprint = _clip(footprint, p, q) + base = _area(footprint) if len(footprint) >= 3 else 0.0 + low = max(a[0][2] - a[1][2] / 2, b[0][2] - b[1][2] / 2) + high = min(a[0][2] + a[1][2] / 2, b[0][2] + b[1][2] / 2) + inter = base * max(0.0, high - low) + union = a[1][0] * a[1][1] * a[1][2] + b[1][0] * b[1][1] * b[1][2] - inter + return inter / union if union > 0 else 0.0 + + +def set_iou(a, b): + union = len(a | b) + return len(a & b) / union if union else 0.0 + + +def oks(a, b, sigma=OKS_SIGMA): + """Object keypoint similarity of two instances' point lists ([x, y], [x, y, v] or None each).""" + def seen(point): + return point is not None and (len(point) < 3 or point[2] > 0) + + def area(points): + shown = [p for p in points if seen(p)] + if not shown: + return 0.0 + return (max(p[0] for p in shown) - min(p[0] for p in shown)) * (max(p[1] for p in shown) + - min(p[1] for p in shown)) + scale = max(1.0, (area(a) + area(b)) / 2) + total, count = 0.0, 0 + for p, q in zip(a, b): + if not seen(p) and not seen(q): + continue + count += 1 + if seen(p) and seen(q): + total += math.exp(-((p[0] - q[0]) ** 2 + (p[1] - q[1]) ** 2) / (2 * scale * sigma ** 2)) + return total / count if count else 1.0 + + +def interval_iou(a, b): + """IoU of two unions of intervals [(start, end), ...]: the length of their intersection over that of their union.""" + def merged(intervals): + out = [] + for start, end in sorted(intervals): + if out and start <= out[-1][1]: + out[-1][1] = max(out[-1][1], end) + else: + out.append([start, end]) + return out + first, second = merged(a), merged(b) + inter, i, j = 0.0, 0, 0 + while i < len(first) and j < len(second): + inter += max(0.0, min(first[i][1], second[j][1]) - max(first[i][0], second[j][0])) + if first[i][1] < second[j][1]: + i += 1 + else: + j += 1 + union = sum(e - s for s, e in first) + sum(e - s for s, e in second) - inter + return inter / union if union > 0 else 1.0 + + +# ------------------------------------------------------------- matching + +def hungarian(scores): + """The one-to-one assignment of rows to columns maximising the summed score: [(row, column)].""" + rows, columns = len(scores), len(scores[0]) if scores else 0 + if not rows or not columns: + return [] + flipped = rows > columns + if flipped: + scores = [list(column) for column in zip(*scores)] + rows, columns = columns, rows + big = max(max(row) for row in scores) + cost = [[big - value for value in row] for row in scores] + # Kuhn-Munkres with potentials (rows <= columns), 1-based. + u, v, p, way = [0.0] * (rows + 1), [0.0] * (columns + 1), [0] * (columns + 1), [0] * (columns + 1) + for i in range(1, rows + 1): + p[0], j0 = i, 0 + minimum, used = [math.inf] * (columns + 1), [False] * (columns + 1) + while True: + used[j0] = True + i0, delta, j1 = p[j0], math.inf, 0 + for j in range(1, columns + 1): + if not used[j]: + current = cost[i0 - 1][j - 1] - u[i0] - v[j] + if current < minimum[j]: + minimum[j], way[j] = current, j0 + if minimum[j] < delta: + delta, j1 = minimum[j], j + for j in range(columns + 1): + if used[j]: + u[p[j]] += delta + v[j] -= delta + else: + minimum[j] -= delta + j0 = j1 + if p[j0] == 0: + break + while j0: + j1 = way[j0] + p[j0] = p[j1] + j0 = j1 + pairs = [(p[j] - 1, j - 1) for j in range(1, columns + 1) if p[j]] + return sorted((c, r) for r, c in pairs) if flipped else sorted(pairs) + + +def match(first, second, score): + """Objects (term, payload) of two sides matched one to one within each term: [(i, j, score)] above 0.""" + found = [] + for term in sorted({t for t, _ in first} | {t for t, _ in second}, key=str): + a = [i for i, (t, _) in enumerate(first) if t == term] + b = [j for j, (t, _) in enumerate(second) if t == term] + if not a or not b: + continue + table = [[score(first[i][1], second[j][1]) for j in b] for i in a] + if len(a) <= HUNGARIAN_LIMIT and len(b) <= HUNGARIAN_LIMIT: + chosen = hungarian(table) + else: + ranked = sorted(((table[x][y], x, y) for x in range(len(a)) for y in range(len(b))), reverse=True) + used_x, used_y, chosen = set(), set(), [] + for value, x, y in ranked: + if value > 0 and x not in used_x and y not in used_y: + used_x.add(x) + used_y.add(y) + chosen.append((x, y)) + found += [(a[x], b[y], table[x][y]) for x, y in chosen if table[x][y] > 0] + return found + + +def _matched(first, second, score): + """(agreement, figures) of two lists of objects by one-to-one matching.""" + if not first and not second: + return 1.0, {'matches': 0, 'mean_iou': None, 'f1': 1.0} + found = match(first, second, score) + total = sum(value for _, _, value in found) + good = sum(1 for _, _, value in found if value >= MATCH_IOU) + f1 = 2 * good / (len(first) + len(second)) + return total / max(len(first), len(second)), {'matches': len(found), + 'mean_iou': total / len(found) if found else None, 'f1': f1} + + +# ------------------------------------------------------------- the values + +def _kept(item, minimum): + confidence = item.get('confidence') if isinstance(item, dict) else None + return minimum is None or confidence is None or confidence >= minimum + + +def filtered(task, entry, minimum): + """The value of a set's entry after the confidence filter, or None when it holds no annotation.""" + if entry is None or entry.get('value') is None: + return None + if minimum is not None and entry.get('confidence') is not None and entry['confidence'] < minimum: + return None + value = entry['value'] + if isinstance(value, dict): + return value if _kept(value, minimum) else None + if isinstance(value, list) and value and isinstance(value[0], dict): + return [item for item in value if _kept(item, minimum)] + return value + + +def _mask_values(value, load): + """The pixel values of a mask value, row by row.""" + if 'rle' in value: + out = array('H') + for number, count in value['rle']: + out.extend(array('H', [number]) * count) + return out + return payloads.read_png(load(value['file']))[2] + + +def _point_objects(value, load): + """A points value as [(term, frozenset of indices)].""" + if isinstance(value, list): + return [(item['term'], frozenset(item['indices'])) for item in value] + _shape, _kind, ids = payloads.read_npy(load(value['file'])) + groups = {} + for index, identifier in enumerate(ids): + if identifier: + groups.setdefault(int(identifier), set()).add(index) + classes = value.get('classes') or {} + return [(classes.get(str(identifier), str(identifier)), frozenset(found)) + for identifier, found in sorted(groups.items())] + + +def _intervals(value): + by_term = {} + for item in value: + by_term.setdefault(item['term'], []).append((item['start'], item['end'])) + return by_term + + +def _tracks(value): + return [(item['term'], {frame['frame']: (frame['x'], frame['y'], frame['w'], frame['h']) + for frame in item['frames']}, item['track']) for item in value] + + +def track_iou(a, b): + frames = set(a) | set(b) + return sum(box_iou(a[f], b[f]) for f in frames if f in a and f in b) / len(frames) if frames else 0.0 + + +def switches(first, second): + """Identity switches of first's tracks against second's: the matched track of a frame changing (IoU > 0.5).""" + count = 0 + for _term, frames, _identifier in first: + last = None + for frame in sorted(frames): + best, chosen = MATCH_IOU, None + for _t, other, identifier in second: + if frame in other: + value = box_iou(frames[frame], other[frame]) + if value > best: + best, chosen = value, identifier + if chosen is not None: + if last is not None and chosen != last: + count += 1 + last = chosen + return count + + +def fragments(tracks): + """Gaps in the tracks' frames: a frame number more than one after the one before.""" + return sum(sum(1 for a, b in zip(sorted(f), sorted(f)[1:]) if b - a > 1) for _t, f, _i in tracks) + + +def compare(document, a, b, load_a=None, load_b=None): + """(agreement from 0 to 1, figures) of two values of one record under the task document (both not None).""" + task = document.get('task') + if task == 'class': + return (1.0 if a == b else 0.0), {} + if task == 'tags': + first, second = set(a), set(b) + return (len(first & second) / len(first | second) if first | second else 1.0), {} + if task == 'text': + same = a == b + ratio = 1.0 if same else difflib.SequenceMatcher(None, a[:TEXT_COMPARED], b[:TEXT_COMPARED], + autojunk=False).ratio() + return ratio, {'exact': same} + if task == 'ranking': + tau = kendall_tau(a, b) + return (tau + 1) / 2, {'tau': tau} + if task == 'boxes': + return _matched([(i['term'], (i['x'], i['y'], i['w'], i['h'])) for i in a], + [(i['term'], (i['x'], i['y'], i['w'], i['h'])) for i in b], box_iou) + if task == 'polygons': + return _matched([(i['term'], [tuple(p) for p in i['points']]) for i in a], + [(i['term'], [tuple(p) for p in i['points']]) for i in b], polygon_iou) + if task == 'box3d': + return _matched([(i['term'], (i['center'], i['size'], i['yaw'])) for i in a], + [(i['term'], (i['center'], i['size'], i['yaw'])) for i in b], box3d_iou) + if task == 'points': + return _matched(_point_objects(a, load_a), _point_objects(b, load_b), set_iou) + if task == 'keypoints': + sigma = document.get('sigma', OKS_SIGMA) + agreement, figures = _matched([(i['term'], i['points']) for i in a], [(i['term'], i['points']) for i in b], + lambda p, q: oks(p, q, sigma)) + figures['mean_oks'] = figures.pop('mean_iou') + return agreement, figures + if task in ('spans', 'segments', 'timeseries'): + first, second = _intervals(a), _intervals(b) + terms = set(first) | set(second) + if not terms: + return 1.0, {} + return sum(interval_iou(first.get(t, []), second.get(t, [])) for t in terms) / len(terms), {} + if task == 'track': + first, second = _tracks(a), _tracks(b) + agreement, figures = _matched([(t, f) for t, f, _ in first], [(t, f) for t, f, _ in second], track_iou) + figures.update(switches=switches(first, second), fragments=[fragments(first), fragments(second)]) + return agreement, figures + if task == 'mask': + return _masks(document, a, b, load_a, load_b) + if task == 'depth': + return _depths(a, b, load_a, load_b) + raise AgreementProblem(f'A {task} task is not compared.') + + +def _masks(document, a, b, load_a, load_b): + first, second = _mask_values(a, load_a), _mask_values(b, load_b) + if len(first) != len(second): + raise AgreementProblem(f'The two masks cover {len(first):,} and {len(second):,} pixels.') + classes_a, classes_b = a.get('classes') or {}, b.get('classes') or {} + joint, count_a, count_b = {}, {}, {} + for x, y in zip(first, second): + if x or y: + joint[(x, y)] = joint.get((x, y), 0) + 1 + count_a[x] = count_a.get(x, 0) + 1 + count_b[y] = count_b.get(y, 0) + 1 + if document.get('mask', 'semantic') == 'instance': + objects_a = [(classes_a.get(str(v), str(v)), v) for v in sorted(count_a) if v] + objects_b = [(classes_b.get(str(v), str(v)), v) for v in sorted(count_b) if v] + + def iou(x, y): + inter = joint.get((x, y), 0) + return inter / (count_a[x] + count_b[y] - inter) if inter else 0.0 + return _matched(objects_a, objects_b, iou) + # Semantic: pixels mapped to terms, the IoU of each term either uses. + inter, union = {}, {} + for (x, y), n in joint.items(): + tx, ty = classes_a.get(str(x)) if x else None, classes_b.get(str(y)) if y else None + for term in {tx, ty} - {None}: + union[term] = union.get(term, 0) + n + if tx is not None and tx == ty: + inter[tx] = inter.get(tx, 0) + n + if not union: + return 1.0, {'terms': {}} + ious = {term: inter.get(term, 0) / union[term] for term in sorted(union)} + return sum(ious.values()) / len(ious), {'terms': ious} + + +def _depths(a, b, load_a, load_b): + shape_a, _k, first = payloads.read_npy(load_a(a['file'])) + shape_b, _k, second = payloads.read_npy(load_b(b['file'])) + if shape_a != shape_b: + raise AgreementProblem(f'The two depth maps have shapes {tuple(shape_a)} and {tuple(shape_b)}.') + absolute = mean = within = count = 0.0 + for x, y in zip(first, second): + if x > 0 and y > 0 and math.isfinite(x) and math.isfinite(y): + count += 1 + absolute += abs(x - y) + mean += (abs(x) + abs(y)) / 2 + within += max(x / y, y / x) < DEPTH_RATIO + if not count: + return 0.0, {'mean_abs': None, 'delta': None, 'pixels': 0} + return 1 - min(1.0, (absolute / count) / (mean / count)), {'mean_abs': absolute / count, 'delta': within / count, + 'pixels': int(count)} + + +def kendall_tau(a, b): + """Kendall's τ of two rankings (best first) over the candidates both rank; 1 when fewer than two are shared.""" + shared = [term for term in a if term in set(b)] + if len(shared) < 2: + return 1.0 + position = {term: index for index, term in enumerate(b)} + concordant = discordant = 0 + for x, y in itertools.combinations(shared, 2): # x before y in a + if position[x] < position[y]: + concordant += 1 + else: + discordant += 1 + return (concordant - discordant) / (concordant + discordant) + + +def cohen_kappa(pairs): + """Cohen's kappa of [(term a, term b)]; 1 when chance agreement is certain; None with no pair.""" + if not pairs: + return None + n = len(pairs) + observed = sum(1 for x, y in pairs if x == y) / n + first, second = {}, {} + for x, y in pairs: + first[x] = first.get(x, 0) + 1 + second[y] = second.get(y, 0) + 1 + expected = sum(first[t] * second.get(t, 0) for t in first) / (n * n) + return 1.0 if expected == 1 else (observed - expected) / (1 - expected) + + +def fleiss_kappa(rows): + """Fleiss' kappa of rows of terms (each row the terms every set gave one record); None with no row.""" + if not rows or len(rows[0]) < 2: + return None + raters = len(rows[0]) + shares, agreement = {}, 0.0 + for row in rows: + counts = {} + for term in row: + counts[term] = counts.get(term, 0) + 1 + shares[term] = shares.get(term, 0) + 1 + agreement += (sum(c * c for c in counts.values()) - raters) / (raters * (raters - 1)) + observed = agreement / len(rows) + expected = sum((c / (len(rows) * raters)) ** 2 for c in shares.values()) + return 1.0 if expected == 1 else (observed - expected) / (1 - expected) + + +# ------------------------------------------------------------- the sets + +def pair_name(a, b): + return f'{a}|{b}' + + +def agreement(document, sets, *, min_confidence=None, loaders=None, offset=0, limit=50): + """The agreement of sets ({name: {record: entry}}, two to eight, in order) under the task document. + + loaders maps a set's name to load(record, file) -> bytes of a sidecar. + Returns pairs, fleiss, the compared records' count, the disputed list + (most disputed first, then by record id; offset and limit page it), + total and problems (records that could not be compared, with why). + """ + task = document.get('task') + if task not in MEASURES: + raise AgreementProblem(f'A {task} task is not compared: it records a decision, not a value.') + names = list(sets) + if not 2 <= len(names) <= SETS_LIMIT: + raise AgreementProblem(f'Agreement needs 2 to {SETS_LIMIT} sets; {len(names)} were given.') + loaders = loaders or {} + values = {name: {record: filtered(task, entry, min_confidence) for record, entry in sets[name].items()} + for name in names} + records = sorted({record for name in names for record, value in values[name].items() if value is not None}, + key=lambda record: record.encode('utf-8', 'surrogatepass')) + pairs = {pair_name(a, b): {'a': a, 'b': b, 'records': 0, 'total': 0.0, 'figures': [], 'labels': []} + for a, b in itertools.combinations(names, 2)} + rows, problems = [], [] + for record in records: + scores, missing = {}, [name for name in names if values[name].get(record) is None] + for a, b in itertools.combinations(names, 2): + first, second = values[a].get(record), values[b].get(record) + if first is None and second is None: + continue + key = pair_name(a, b) + pair = pairs[key] + pair['records'] += 1 + score = 0.0 + if first is not None and second is not None: + try: + score, figures = compare(document, first, second, + (lambda n, r=record, s=a: loaders[s](r, n)) if a in loaders else None, + (lambda n, r=record, s=b: loaders[s](r, n)) if b in loaders else None) + pair['figures'].append(figures) + if task == 'class': + pair['labels'].append((first, second)) + except (AgreementProblem, payloads.PayloadError, KeyError, OSError) as exc: + problems.append({'record': record, 'pair': key, 'problem': str(exc)}) + pair['total'] += score + scores[key] = score + if scores: + rows.append({'record': record, 'disagreement': 1 - sum(scores.values()) / len(scores), + 'pairs': scores, 'missing': missing}) + rows.sort(key=lambda row: (-row['disagreement'], row['record'].encode('utf-8', 'surrogatepass'))) + answered = [] + for pair in pairs.values(): + shown = {'a': pair['a'], 'b': pair['b'], 'records': pair['records'], + 'agreement': pair['total'] / pair['records'] if pair['records'] else None} + shown.update(_figures(task, pair)) + answered.append(shown) + fleiss = None + if task == 'class' and len(names) >= 3: + fleiss = fleiss_kappa([[values[name][record] for name in names] for record in records + if all(values[name].get(record) is not None for name in names)]) + return {'type': task, 'measure': MEASURES[task], 'pairs': answered, 'fleiss': fleiss, 'records': len(rows), + 'disputed': rows[offset:offset + limit], 'total': len(rows), 'offset': offset, 'limit': limit, + 'problems': problems[:50]} + + +def _figures(task, pair): + """The figures of a pair beyond its agreement, from its records' figures.""" + figures = pair['figures'] + if task == 'class': + return {'kappa': cohen_kappa(pair['labels'])} + if task == 'text': + return {'exact': sum(1 for f in figures if f.get('exact'))} + if task == 'ranking': + return {'tau': sum(f['tau'] for f in figures) / len(figures) if figures else None} + if task in ('boxes', 'polygons', 'box3d', 'points', 'keypoints', 'track') or (figures and 'matches' in figures[0]): + key = 'mean_oks' if task == 'keypoints' else 'mean_iou' + matched = [f for f in figures if f.get(key) is not None] + shown = {'matches': sum(f.get('matches', 0) for f in figures), + key: (sum(f[key] * f['matches'] for f in matched) / sum(f['matches'] for f in matched) + if matched else None), + 'f1': sum(f['f1'] for f in figures) / len(figures) if figures else None} + if task == 'track': + shown['switches'] = sum(f['switches'] for f in figures) + shown['fragments'] = [sum(f['fragments'][0] for f in figures), sum(f['fragments'][1] for f in figures)] + return shown + if task == 'depth': + measured = [f for f in figures if f.get('mean_abs') is not None] + return {'mean_abs': sum(f['mean_abs'] for f in measured) / len(measured) if measured else None, + 'delta': sum(f['delta'] for f in measured) / len(measured) if measured else None} + return {} From c4713111fbc252842db1bc005f96e9038eda0349 Mon Sep 17 00:00:00 2001 From: MrScripty <TheEnvironmentGuy@protonmail.com> Date: Thu, 19 Nov 2026 07:05:30 -0700 Subject: [PATCH 112/131] feat(project): the sets of a task, their agreement, a record compared, and the decision kept annotation_sets, annotation_agreement, annotation_compare and keep_annotation (spec-t4 section 6), in the project_folder profile. A decision goes through set_annotation's own path; a kept sidecar is staged in the working copy and written to annotations/<task>/ by Save, which also removes those no saved line names. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --- docs/contracts/project-folder.md | 8 + ...est_tuldok_project_annotation_agreement.py | 146 ++++++++ tests/test_tuldok_project_service.py | 11 +- tuldok_project/annotation_review.py | 350 ++++++++++++++++++ tuldok_project/annotation_rows.py | 46 +++ tuldok_project/operations.py | 25 ++ tuldok_project/service.py | 43 ++- tuldok_project/store.py | 31 +- 8 files changed, 651 insertions(+), 9 deletions(-) create mode 100644 tuldok_project/annotation_review.py diff --git a/docs/contracts/project-folder.md b/docs/contracts/project-folder.md index a9379909..5dec6e3f 100644 --- a/docs/contracts/project-folder.md +++ b/docs/contracts/project-folder.md @@ -485,6 +485,14 @@ definition that failed or was cancelled is resumed by the next build: its valid lines (and sidecars) whose records are unchanged are kept, and only the other records are given to the command (or asked of the model). +The sets of a task (the kept set, `annotations/<task>.jsonl`, and every +annotate's product for it) are compared on the Annotate tab (Review): their +agreement per pair and per record, the most disputed records, each drawn +over the record, and a decision (keep one set's annotation, keep two sets' +together, or reject them) kept as an unsaved edit of `annotations/<task>.jsonl` +whose `from` names the set, its run and what made it; a kept sidecar is +copied into `annotations/<task>/` by Save. + ### `model` A model is an architecture. It produces nothing by itself; recipes train it. diff --git a/tests/test_tuldok_project_annotation_agreement.py b/tests/test_tuldok_project_annotation_agreement.py index 338a4469..7b64f60a 100644 --- a/tests/test_tuldok_project_annotation_agreement.py +++ b/tests/test_tuldok_project_annotation_agreement.py @@ -9,16 +9,25 @@ test_tuldok_project_annotate_step (database only). """ import itertools +import json import math +import os from pathlib import Path import random +import subprocess import sys +import tempfile import unittest +from unittest import mock +import uuid sys.path.insert(0, str(Path(__file__).resolve().parents[1])) sys.path.insert(0, str(Path(__file__).resolve().parent)) from tuldok_project import annotation_agreement as agree, annotation_payloads as payloads # noqa: E402 +from tuldok_project import builds, check, environments, local, plan, store # noqa: E402 +from tuldok_project.service import Service # noqa: E402 +from tuldok_project.store import ProjectError # noqa: E402 def entry(value, confidence=None): @@ -229,5 +238,142 @@ def test_refusals(self): agree.agreement({'task': 'class'}, {'a': {}}) +DATABASE = os.environ.get('TULDOK_DATABASE_URL') +OWNER = {'actor_id': 'owner-1', 'kind': 'owner', 'label': 'The owner', + 'scopes': ['approve-execution', 'cancel', 'edit', 'execute', 'inspect']} +READER = {'actor_id': 'agent-2', 'kind': 'agent', 'label': 'reader', 'scopes': ['inspect']} + + +@unittest.skipUnless(DATABASE, 'TULDOK_DATABASE_URL is not set; database tests need a disposable cluster.') +class Operations(unittest.TestCase): + """annotation_sets, annotation_agreement, annotation_compare and keep_annotation on the stand-ins' sets.""" + + @classmethod + def setUpClass(cls): + import test_tuldok_project_annotate_step as stand_ins + cls.stand_ins = stand_ins + directory = tempfile.TemporaryDirectory() + cls.addClassCleanup(directory.cleanup) + cls.temporary = Path(directory.name) + cls.root = cls.temporary / 'repository' + cls.root.mkdir() + patcher = mock.patch.dict(os.environ, {local.HOME_VARIABLE: str(cls.temporary / 'home'), + local.SETTINGS_VARIABLE: str(cls.temporary / 'settings.json')}) + patcher.start() + cls.addClassCleanup(patcher.stop) + cls.addClassCleanup(stand_ins._writable, cls.temporary / 'home') + cls.project_id = uuid.uuid4().hex + cls.folder = stand_ins.make_project(cls.root, cls.project_id) + for arguments in (['init', '-q'], ['add', '-A'], ['commit', '-q', '-m', 'The project.']): + subprocess.run([*stand_ins.GIT, '-C', str(cls.root), *arguments], check=True) + cls.addClassCleanup(store.drop_project, cls.project_id) + with store.open_project(cls.folder) as project: + environments.connect(project, 'environments/test-python', sys.executable) + made = plan.build_plan(project, ['datasets/masks-a', 'datasets/masks-b', 'datasets/objects-a', + 'datasets/objects-b', 'datasets/shapes-a', 'datasets/shapes-b']) + done = builds.execute(cls.folder, made, confirm=lambda given: True) + assert done['ok'], done + cls.service = Service(cls.folder) + cls.addClassCleanup(cls.service.close) + + def call(self, name, arguments, actor=OWNER): + return self.service.call(name, arguments, actor) + + def refused(self, name, arguments, actor=OWNER): + with self.assertRaises(ProjectError) as raised: + self.call(name, arguments, actor) + return raised.exception + + def test_a_sets(self): + found = self.call('annotation_sets', {'task': 'masks'}, READER) + self.assertEqual(found['type'], 'mask') + self.assertEqual([(s['set'], s['annotated']) for s in found['sets']], + [('kept', 0), ('datasets/masks-a', 4), ('datasets/masks-b', 4)]) + self.assertEqual(found['sets'][1]['by']['name'], 'segment-a') + + def test_b_agreement_against_the_arithmetic(self): + found = self.call('annotation_agreement', {'task': 'masks', 'sets': ['datasets/masks-a', 'datasets/masks-b']}, + READER) + rows = {row['record']: row['disagreement'] for row in found['disputed']} + # a.png: red 30 of 56 pixels, blue 49 of 81, both matched; d.png: no object in either: 1. + self.assertAlmostEqual(1 - rows['images__a.png'], (30 / 56 + 49 / 81) / 2) + self.assertAlmostEqual(rows['images__d.png'], 0.0) + # b.png: one red 10 x 8 against 12 x 10. c.png: the stand-in gives one id per colour, so its two blue + # rectangles are one object: 4 x 4 + 5 x 9 against 6 x 6 + 7 x 11. + self.assertAlmostEqual(1 - rows['images__b.png'], 80 / 120) + self.assertAlmostEqual(1 - rows['images__c.png'], (16 + 45) / (36 + 77)) + self.assertEqual([row['record'] for row in found['disputed']], + sorted(rows, key=lambda record: (-rows[record], record))) + pair = found['pairs'][0] + self.assertAlmostEqual(pair['agreement'], sum(1 - value for value in rows.values()) / 4) + objects = self.call('annotation_agreement', {'task': 'objects'}, READER) + self.assertEqual([p['a'] + ' ' + p['b'] for p in objects['pairs']], + ['kept datasets/objects-a', 'kept datasets/objects-b', 'datasets/objects-a datasets/objects-b']) + rows = {row['record']: row for row in objects['disputed']} + self.assertAlmostEqual(rows['clouds__p.ply']['pairs']['datasets/objects-a|datasets/objects-b'], 9 / 10) + self.assertEqual(rows['clouds__p.ply']['missing'], ['kept']) + # The confidence filter: the shapes' polygons carry 0.9 (red) and 0.8 (blue). + strict = self.call('annotation_agreement', {'task': 'shapes', 'sets': ['datasets/shapes-a', 'datasets/shapes-b'], + 'min_confidence': 0.85}, READER) + loose = self.call('annotation_agreement', {'task': 'shapes', 'sets': ['datasets/shapes-a', 'datasets/shapes-b']}, + READER) + self.assertNotEqual(strict['pairs'][0]['agreement'], loose['pairs'][0]['agreement']) + + def test_c_compare(self): + found = self.call('annotation_compare', {'task': 'masks', 'record': 'images__a.png', + 'sets': ['datasets/masks-a', 'datasets/masks-b']}, READER) + self.assertEqual(found['size'], [24, 16]) + drawn = found['sets'][0]['drawn'] + self.assertEqual((drawn['width'], drawn['height']), (24, 16)) + self.assertEqual(sum(n for v, n in drawn['runs'] if v == 1), 30) + self.assertAlmostEqual(found['pairs'][0]['agreement'], (30 / 56 + 49 / 81) / 2) + refused = self.refused('annotation_compare', {'task': 'masks', 'record': 'images__a.png', + 'sets': ['datasets/nobody']}, READER) + self.assertEqual(refused.code, 'not-found') + + def test_d_keep_and_save(self): + self.assertEqual(self.refused('keep_annotation', {'task': 'masks', 'record': 'images__a.png', 'keep': 'one', + 'sets': ['datasets/masks-a']}, READER).code, 'forbidden') + self.assertEqual(self.refused('keep_annotation', {'task': 'masks', 'record': 'images__a.png', 'keep': 'both', + 'sets': ['datasets/masks-a', 'datasets/masks-b']}).code, + 'invalid') # a mask is not a list + kept = self.call('keep_annotation', {'task': 'masks', 'record': 'images__a.png', 'keep': 'one', + 'sets': ['datasets/masks-b'], 'note': 'the wider one'}) + self.assertEqual((kept['state'], kept['unsaved']), ('accepted', 1)) + line = self.call('annotation', {'task': 'masks', 'record': 'images__a.png'})['annotation'] + self.assertEqual(line['from']['set'], 'datasets/masks-b') + self.assertEqual(line['from']['by']['name'], 'segment-b') + self.assertTrue(payloads.is_kept_name(line['value']['file'])) + # The kept set now agrees with b on a.png, and its sidecar is read from the working copy. + found = self.call('annotation_compare', {'task': 'masks', 'record': 'images__a.png', + 'sets': ['kept', 'datasets/masks-b']}) + self.assertEqual(found['pairs'][0]['agreement'], 1.0) + self.call('keep_annotation', {'task': 'masks', 'record': 'images__b.png', 'keep': 'none', + 'sets': ['datasets/masks-a', 'datasets/masks-b']}) + saved = self.call('save', {}) + self.assertIn('annotations/masks.jsonl', saved['annotations_written']) + sidecar = self.folder / 'annotations' / 'masks' / line['value']['file'] + self.assertTrue(sidecar.is_file()) + written = (self.folder / 'annotations' / 'masks.jsonl').read_text().splitlines() + self.assertEqual([json.loads(text)['state'] for text in written], ['accepted', 'rejected']) + self.assertEqual(check.check_folder(self.folder).problems, []) + # Both polygon sets kept together, then the mask replaced by a's: Save removes b's sidecar. + both = self.call('keep_annotation', {'task': 'shapes', 'record': 'images__c.png', 'keep': 'both', + 'sets': ['datasets/shapes-a', 'datasets/shapes-b']}) + self.assertEqual(both['state'], 'accepted') + value = self.call('annotation', {'task': 'shapes', 'record': 'images__c.png'})['annotation']['value'] + self.assertEqual(len(value), 2) + self.call('keep_annotation', {'task': 'masks', 'record': 'images__a.png', 'keep': 'one', + 'sets': ['datasets/masks-a']}) + self.call('save', {}) + files = sorted(path.name for path in (self.folder / 'annotations' / 'masks').iterdir()) + now = self.call('annotation', {'task': 'masks', 'record': 'images__a.png'})['annotation']['value']['file'] + self.assertEqual(files, [now]) + self.assertEqual(check.check_folder(self.folder).problems, []) + activity = [row for row in self.call('activity', {'limit': 20})['items'] + if row['operation'] == 'keep_annotation' and row['outcome'] == 'done'] + self.assertEqual(len(activity), 4) + + if __name__ == '__main__': unittest.main() diff --git a/tests/test_tuldok_project_service.py b/tests/test_tuldok_project_service.py index 1d76946d..1a22dbe3 100644 --- a/tests/test_tuldok_project_service.py +++ b/tests/test_tuldok_project_service.py @@ -48,7 +48,7 @@ class Table(unittest.TestCase): def test_every_operation_is_declared_once(self): names = [operation.name for operation in operations.OPERATIONS] - self.assertEqual(len(names), 72) # the rows of spec-m7.md section 2, of section 2 of spec-w1.md and spec-w3.md, of section 3 of spec-d1.md and spec-d2.md, of section 5 of spec-d4.md, of sections 2 and 4 of spec-d5.md, of section 2 of spec-d6.md, of section 3 of spec-t2.md, of section 4 of spec-t1.md, and of section 4 of spec-t3.md + self.assertEqual(len(names), 76) # the rows of spec-m7.md section 2, of section 2 of spec-w1.md and spec-w3.md, of section 3 of spec-d1.md and spec-d2.md, of section 5 of spec-d4.md, of sections 2 and 4 of spec-d5.md, of section 2 of spec-d6.md, of section 3 of spec-t2.md, of section 4 of spec-t1.md, of section 4 of spec-t3.md, and of section 6 of spec-t4.md self.assertEqual(len(set(names)), len(names)) for name in REQUEST_OPERATIONS: self.assertIsNotNone(operations.by_name(name)) @@ -80,7 +80,7 @@ def test_mutations_and_owner_rows(self): 'import_values', 'check_environment', 'connect_environment', 'disconnect_environment', 'request_build', 'approve_build', 'decline_build', 'cancel_build', 'cancel_run', 'stop_run', 'set_annotation', 'revert_annotations', - 'set_endpoint'}) + 'set_endpoint', 'keep_annotation'}) owner = {operation.name for operation in operations.OPERATIONS if operation.who == 'owner'} self.assertEqual(owner, {'connect_environment', 'disconnect_environment', 'approve_build', 'decline_build', 'set_endpoint', 'find_endpoints'}) @@ -224,6 +224,8 @@ def test_every_read(self): 'intervals': {'benchmark': 'benchmarks/score'}, 'annotation_tasks': {}, 'annotated_records': {'task': 'none-here'}, 'annotation': {'task': 'none-here', 'record': 'r1'}, + 'annotation_sets': {'task': 'none-here'}, 'annotation_agreement': {'task': 'none-here'}, + 'annotation_compare': {'task': 'none-here', 'record': 'r1', 'sets': ['kept']}, 'endpoint': {}, 'find_endpoints': {}, 'suggestion_models': {'task': 'none-here'}, 'suggest_annotation': {'task': 'none-here', 'record': 'r1', 'model': 'm'}, } @@ -258,8 +260,9 @@ def test_every_read(self): # test_tuldok_project_pumas self.assertEqual(self.refused(operation.name, arguments[operation.name]).code, 'not-found') continue - if operation.name in ('annotated_records', 'annotation'): # this fixture has no task; read in - # test_tuldok_project_annotation_rows + if operation.name in ('annotated_records', 'annotation', 'annotation_sets', 'annotation_agreement', + 'annotation_compare'): # this fixture has no task; read in + # test_tuldok_project_annotation_rows and test_tuldok_project_annotation_agreement self.assertEqual(self.refused(operation.name, arguments[operation.name]).code, 'not-found') continue if operation.name == 'note': # this fixture has no notes; read in test_tuldok_project_workspace diff --git a/tuldok_project/annotation_review.py b/tuldok_project/annotation_review.py new file mode 100644 index 00000000..edc6fe4e --- /dev/null +++ b/tuldok_project/annotation_review.py @@ -0,0 +1,350 @@ +"""Reviewing annotation sets: the sets of a task, their agreement, one record compared, and the decision kept. + +Owns the answers of the four operations of section 6 of +docs/plans/training-and-curation/spec-t4.md and what they draw (section 7). +gather() reads what the database holds of a task under the service's lock +(the kept set, the annotators and their current products); everything else +reads files outside it: the sets through annotation_sets, the agreement +through annotation_agreement, the record's product through inside. The kept +set's sidecars are read from annotations/<task>/ in the folder, or from the +working copy when kept and not yet saved. keep_items() turns a decision +into the items set_annotation keeps, so the decision goes the same way as +any edit. +""" +import base64 +import os + +from . import (annotation_agreement as agreement, annotation_payloads as payloads, annotation_records, + annotation_rows, annotation_sets as sets_reader, annotations, builds, documents, inside_archive) +from .store import ProjectError + +KEPT = sets_reader.KEPT +FROM_LIMIT = annotations.FROM_LIMIT +DRAWN_SIDE = 512 # pixels a side of a mask drawn +DEPTH_SIDE = 256 # of a depth map drawn +FRAME_SIDE = 128 # of a frame drawn +FRAMES_DRAWN = 64 +SERIES_POSITIONS = 1024 +SERIES_CHANNELS = 8 +ARRAY_BYTES = 64 * 1024 * 1024 + + +# ------------------------------------------------------------ under the lock + +def gather(project, name, document, located): + """What the database holds of a task's sets: read under the service's lock.""" + reference = annotation_rows.reference(name) + connection, schema = project._connection, project.schema + kept = annotation_rows.kept_values(connection, schema, name) + staged = annotation_rows.staged_sidecars(connection, schema, name) + found = [] + for directory, set_name, definition in project._execute( + "SELECT directory, name, document FROM {schema}.definitions WHERE directory = 'datasets' " + 'AND NOT removed ORDER BY name').fetchall(): + if not sets_reader.is_annotator(definition, reference): + continue + set_reference = documents.reference(directory, set_name) + row = project._execute('''SELECT p.run_id, r.directory FROM {schema}.products p + JOIN {schema}.runs r ON r.id = p.run_id + WHERE p.reference = %s AND p.subject = '' AND p.current + AND r.state IN ('succeeded', %s)''', (set_reference, builds.ADOPTED)).fetchone() + found.append({'set': set_reference, 'title': definition.get('title'), 'run': row[0] if row else None, + 'directory': os.path.join(row[1], builds.OUTPUT) if row and row[1] else None}) + return {'name': name, 'reference': reference, 'document': document, 'located': located, 'kept': kept, + 'staged': staged, 'annotators': found, 'folder': project._state()['folder']} + + +# ------------------------------------------------------------ outside the lock + +def _kept_loader(gathered): + folder = os.path.join(gathered['folder'], annotation_rows.DIRECTORY, gathered['name']) + + def load(_record, file): + if file in gathered['staged']: + return gathered['staged'][file] + if not payloads.is_kept_name(file): + raise sets_reader.SetProblem(f'The kept sidecar {file!r} is not named by its content.') + path = os.path.join(folder, file) + if not os.path.isfile(path) or os.path.islink(path): + raise sets_reader.SetProblem(f'The kept sidecar {file} is not in {annotation_rows.DIRECTORY}/' + f'{gathered["name"]}/.') + with open(path, 'rb') as handle: + return handle.read(payloads.SIDECAR_LIMIT + 1) + return load + + +def read_sets(gathered, wanted=None): + """({name: {record: entry}}, {name: loader}, [shown set]) of the task's sets that can be read, in order.""" + values, loaders, shown = {}, {}, [] + if wanted is None or KEPT in wanted: + values[KEPT] = {record: {'value': value} for record, value in gathered['kept'].items()} + loaders[KEPT] = _kept_loader(gathered) + shown.append({'set': KEPT, 'title': 'Kept in the project', 'by': {'kind': 'person', 'name': 'people'}, + 'run': None, 'annotated': len(values[KEPT]), 'skipped': 0, 'problem': None}) + for found in gathered['annotators']: + if wanted is not None and found['set'] not in wanted: + continue + item = {'set': found['set'], 'title': found['title'], 'by': None, 'run': found['run'], 'annotated': 0, + 'skipped': 0, 'problem': None} + if found['directory'] is None: + item['problem'] = 'It has no current product; build it.' + else: + try: + read = sets_reader.read_set(found['directory'], gathered['document']) + except sets_reader.SetProblem as exc: + item['problem'] = str(exc) + else: + item.update(by=read['by'], annotated=len(read['records']), skipped=read['skipped'], + truncated=read['truncated']) + values[found['set']] = read['records'] + loaders[found['set']] = (lambda directory: lambda _record, file: sets_reader.sidecar(directory, file))( + found['directory']) + shown.append(item) + if wanted is not None: + missing = [name for name in wanted if name not in values] + if missing: + known = {item['set']: item for item in shown} + reason = known.get(missing[0], {}).get('problem') or 'it is not a set of this task' + raise ProjectError(f'The set {missing[0]} cannot be read: {reason}', 'not-found', + references=[gathered['reference']]) + values = {name: values[name] for name in wanted} + return values, loaders, shown + + +def sets_answer(gathered): + _values, _loaders, shown = read_sets(gathered) + return {'task': gathered['reference'], 'type': gathered['document'].get('task'), 'sets': shown} + + +def agreement_answer(gathered, arguments): + wanted = arguments.get('sets') + if wanted is not None and len(set(wanted)) != len(wanted): + raise ProjectError('Name each set once.', 'invalid') + values, loaders, shown = read_sets(gathered, wanted) + try: + found = agreement.agreement(gathered['document'], values, min_confidence=arguments.get('min_confidence'), + loaders=loaders, offset=arguments.get('offset', 0), + limit=arguments.get('limit', 50)) + except agreement.AgreementProblem as exc: + raise ProjectError(str(exc), 'invalid', references=[gathered['reference']]) from None + truncated = any(item.get('truncated') for item in shown) + return {'task': gathered['reference'], **found, 'sets': [item for item in shown if item['set'] in values], + 'truncated': truncated} + + +# ------------------------------------------------------------ one record drawn + +def _downsample(values, width, height, side): + """(values, width, height) taken by nearest neighbour so that neither side passes side.""" + step = max(1, -(-max(width, height) // side)) + if step == 1: + return values, width, height + w, h = -(-width // step), -(-height // step) + return [values[(y * step) * width + x * step] for y in range(h) for x in range(w)], w, h + + +def _drawn_mask(value, load, size): + if 'rle' in value: + if size is None: + return None, 'The image\'s size is not known, so the runs cannot be drawn.' + width, height = size + try: + pixels = payloads.decode_runs(value['rle'], width, height) + except payloads.PayloadError as exc: + return None, str(exc) + else: + width, height, pixels = payloads.read_png(load(value['file'])) + shown, w, h = _downsample(pixels, width, height, DRAWN_SIDE) + return {'width': w, 'height': h, 'scale': width / w, 'runs': payloads.encode_runs(shown), + 'classes': value.get('classes') or {}}, None + + +def _drawn_depth(value, load): + shape, _kind, values = payloads.read_npy(load(value['file'])) + if len(shape) != 2: + return None, 'The depth map is not 2-D.' + height, width = shape + shown, w, h = _downsample(list(values), width, height, DEPTH_SIDE) + good = [v for v in shown if v > 0 and v == v and v not in (float('inf'), float('-inf'))] + low, high = (min(good), max(good)) if good else (0.0, 0.0) + span = (high - low) or 1.0 + quantised = bytes(0 if not (v > 0 and v == v and abs(v) != float('inf')) + else 1 + min(254, int((v - low) / span * 254)) for v in shown) + return {'width': w, 'height': h, 'scale': width / w, 'low': low, 'high': high, + 'values_u8': base64.b64encode(quantised).decode('ascii')}, None + + +def _array_values(product, record): + place = inside_archive.locate(product.root, record['path']) + if (place.size or 0) > ARRAY_BYTES: + raise payloads.PayloadError(f'The array is over {ARRAY_BYTES:,} bytes; it is not drawn here.') + return payloads.read_npy(place.head(place.size or 0)) + + +def _frames(product, record): + """The array's frames (first axis) as 8-bit grey, at most FRAMES_DRAWN of at most FRAME_SIDE a side.""" + shape, _kind, values = _array_values(product, record) + if len(shape) < 3: + return None, 'Tracks are drawn on an array of frames (frames, height, width).' + count, height, width = shape[0], shape[1], shape[2] + channels = 1 + for n in shape[3:]: + channels *= n + step = max(1, -(-count // FRAMES_DRAWN)) + finite = [v for v in values if v == v and abs(v) != float('inf')] + low, high = (min(finite), max(finite)) if finite else (0, 1) + span = (high - low) or 1 + frames = [] + for frame in range(0, count, step): + base = frame * height * width * channels + grey = [sum(values[base + (y * width + x) * channels + c] for c in range(channels)) / channels + for y in range(height) for x in range(width)] + shown, w, h = _downsample(grey, width, height, FRAME_SIDE) + frames.append({'frame': frame, 'u8': base64.b64encode(bytes( + max(0, min(255, int((v - low) / span * 255))) if v == v else 0 for v in shown)).decode('ascii')}) + w, h = _downsample([0] * (width * height), width, height, FRAME_SIDE)[1:] + return {'count': count, 'width': w, 'height': h, 'scale': width / w, 'frames': frames}, None + + +def _series(product, record): + shape, _kind, values = _array_values(product, record) + if len(shape) not in (1, 2): + return None, 'A timeseries is drawn over an array of one or two axes.' + positions = shape[0] + channels = 1 if len(shape) == 1 else min(SERIES_CHANNELS, shape[1]) + stride = 1 if len(shape) == 1 else shape[1] + step = max(1, -(-positions // SERIES_POSITIONS)) + lines = [[float(values[p * stride + c]) for p in range(0, positions, step)] for c in range(channels)] + return {'positions': positions, 'step': step, 'channels': lines}, None + + +def compare_answer(gathered, arguments, product, index): + """The record's value in each set, drawn, the pairs' agreement on it, and its frames or series.""" + record_id = arguments['record'] + task = gathered['document'].get('task') + wanted = arguments['sets'] + if len(set(wanted)) != len(wanted): + raise ProjectError('Name each set once.', 'invalid') + values, loaders, _shown = read_sets(gathered, wanted) + record = None + if index is not None and record_id in index.by_id: + record = index.records[index.by_id[record_id]] + facts = annotation_records.facts(product, record, task) if record is not None else {'size': None} + minimum = arguments.get('min_confidence') + answered, filtered = [], {} + for name in wanted: + entry = values[name].get(record_id) + value = agreement.filtered(task, entry, minimum) + filtered[name] = value + item = {'set': name, 'value': value, 'confidence': (entry or {}).get('confidence'), 'drawn': None, + 'problem': None} + load = (lambda n, s=name: loaders[s](record_id, n)) + try: + if value is not None and task == 'mask': + item['drawn'], item['problem'] = _drawn_mask(value, load, facts.get('size')) + elif value is not None and task == 'depth': + item['drawn'], item['problem'] = _drawn_depth(value, load) + elif value is not None and task == 'points' and isinstance(value, dict): + item['drawn'] = {'points': [{'term': term, 'indices': sorted(found)} + for term, found in agreement._point_objects(value, load)]} + except (payloads.PayloadError, sets_reader.SetProblem, OSError) as exc: + item['problem'] = str(exc) + answered.append(item) + pairs = [] + for position, a in enumerate(wanted): + for b in wanted[position + 1:]: + first, second = filtered[a], filtered[b] + shown = {'a': a, 'b': b, 'agreement': None, 'figures': {}, 'problem': None} + if first is None or second is None: + shown['agreement'] = 0.0 if (first is not None or second is not None) else None + else: + try: + shown['agreement'], shown['figures'] = agreement.compare( + gathered['document'], first, second, lambda n, s=a: loaders[s](record_id, n), + lambda n, s=b: loaders[s](record_id, n)) + except (agreement.AgreementProblem, payloads.PayloadError, sets_reader.SetProblem, OSError) as exc: + shown['problem'] = str(exc) + pairs.append(shown) + answer = {'task': gathered['reference'], 'type': task, 'record': record_id, 'in_product': record is not None, + 'size': list(facts['size']) if facts.get('size') else None, 'sets': answered, 'pairs': pairs, + 'frames': None, 'series': None, 'problem': None} + try: + if record is not None and record.get('path') and record['kind'] == 'array' and task == 'track': + answer['frames'], answer['problem'] = _frames(product, record) + elif record is not None and record.get('path') and record['kind'] == 'array' and task == 'timeseries': + answer['series'], answer['problem'] = _series(product, record) + except (payloads.PayloadError, ProjectError, OSError) as exc: + answer['problem'] = str(exc) + return answer + + +# ------------------------------------------------------------ the decision + +def _origin(item): + """The from of a line kept from a set: the set, its run and what made it, within FROM_LIMIT.""" + import json + origin = {'set': item['set'], 'run': item['run'], 'by': dict(item['by'] or {})} + if len(json.dumps(origin, separators=(',', ':'), ensure_ascii=False).encode('utf-8')) > FROM_LIMIT: + origin['by'].pop('settings', None) + return origin + + +def keep_items(gathered, arguments): + """(the set_annotation item, its from, {file: bytes} of sidecars to stage) of a decision on one record.""" + record_id, keep, wanted = arguments['record'], arguments['keep'], arguments['sets'] + task = gathered['document'].get('task') + if len(set(wanted)) != len(wanted): + raise ProjectError('Name each set once.', 'invalid') + if keep in ('one', 'both') and KEPT in wanted: + raise ProjectError('The kept set is what a decision writes; name the sets made by annotators.', 'invalid') + if (keep == 'one' and len(wanted) != 1) or (keep == 'both' and len(wanted) != 2): + raise ProjectError(f'keep {keep} takes {"one set" if keep == "one" else "two sets"}.', 'invalid') + values, loaders, shown = read_sets(gathered, wanted) + by_name = {item['set']: item for item in shown} + note = arguments.get('note') + if keep == 'none': + item = {'record': record_id, 'state': 'rejected', 'value': None} + origin = {'rejected': [_origin(by_name[name]) if name != KEPT else {'set': KEPT} for name in wanted]} + if len(origin.__repr__()) > FROM_LIMIT: + origin = {'rejected': [{'set': name} for name in wanted]} + if note: + item['note'] = note + return item, origin, {} + chosen = [] + for name in wanted: + entry = values[name].get(record_id) + if entry is None: + raise ProjectError(f'The set {name} has no annotation of {record_id!r}.', 'not-found', + references=[gathered['reference']]) + chosen.append(entry['value']) + staged = {} + if keep == 'one': + value = chosen[0] + for file in annotations.sidecars(task, value): + data = loaders[wanted[0]](record_id, file) + extension = '.png' if task == 'mask' else '.npy' + kept_name = payloads.kept_name(data, extension) + staged[kept_name] = data + value = dict(value, file=kept_name) + origin = _origin(by_name[wanted[0]]) + else: + if not all(isinstance(value, list) for value in chosen): + raise ProjectError(f'Both can be kept only of a task whose value is a list; a {task} value is not.', + 'invalid', references=[gathered['reference']]) + value = chosen[0] + chosen[1] + if task == 'track': + used, merged = set(), [] + for found in value: # a track id once per annotation: the second set's repeats are renamed + identifier, number = found['track'], 2 + while identifier in used: + identifier, number = f'{found["track"]}-{number}', number + 1 + used.add(identifier) + merged.append(dict(found, track=identifier[:annotations.TRACK_ID_LIMIT])) + value = merged + origin = {'both': [_origin(by_name[name]) for name in wanted]} + if len(repr(origin)) > FROM_LIMIT: + origin = {'both': [{'set': name, 'run': by_name[name]['run']} for name in wanted]} + item = {'record': record_id, 'state': 'accepted', 'value': value} + if note: + item['note'] = note + return item, origin, staged diff --git a/tuldok_project/annotation_rows.py b/tuldok_project/annotation_rows.py index 5e3c7ded..679c941b 100644 --- a/tuldok_project/annotation_rows.py +++ b/tuldok_project/annotation_rows.py @@ -44,6 +44,10 @@ '''CREATE TABLE IF NOT EXISTS {schema}.record_hashes ( run_id text NOT NULL, record text NOT NULL, sha256 text, PRIMARY KEY (run_id, record))''', + # Sidecars kept from an annotation set and not yet saved to annotations/<task>/ (spec-t4.md section 2). + '''CREATE TABLE IF NOT EXISTS {schema}.annotation_sidecars ( + task text NOT NULL, name text NOT NULL, data bytea NOT NULL, + PRIMARY KEY (task, name))''', ) _LINE_COLUMNS = 'record, sha256, state, value, note, "by", "at", origin' @@ -372,3 +376,45 @@ def mark_saved(connection, schema, name, lines): WHERE a.task = %s AND a.record = given.record AND (a.unsaved OR a.saved IS DISTINCT FROM given.line)'''), ([record for record, _ in lines], [line for _, line in lines], name)) + + +# ---------------------------------------------------------------- sidecars (spec-t4.md section 2) + +def kept_values(connection, schema, name): + """{record: value} of the task's annotations as they now are, with a value and not rejected: the kept set.""" + return {record: value for record, value in connection.execute( + _q(schema, "SELECT record, value FROM {schema}.annotations WHERE task = %s AND state IS NOT NULL " + "AND state <> 'rejected' AND value IS NOT NULL AND value <> 'null'::jsonb"), (name,))} + + +def stage_sidecar(connection, schema, name, file, data): + """Keep a sidecar's bytes until Save writes annotations/<name>/<file> (its name is its content's).""" + connection.execute(_q(schema, 'INSERT INTO {schema}.annotation_sidecars (task, name, data) VALUES (%s, %s, %s) ' + 'ON CONFLICT (task, name) DO NOTHING'), (name, file, data)) + + +def staged_sidecar(connection, schema, name, file): + """The bytes of a sidecar kept and not yet saved, or None.""" + row = connection.execute(_q(schema, 'SELECT data FROM {schema}.annotation_sidecars WHERE task = %s AND name = %s'), + (name, file)).fetchone() + return None if row is None else bytes(row[0]) + + +def staged_sidecars(connection, schema, name): + """{file: bytes} of every sidecar of the task kept and not yet saved.""" + return {file: bytes(data) for file, data in connection.execute( + _q(schema, 'SELECT name, data FROM {schema}.annotation_sidecars WHERE task = %s'), (name,))} + + +def drop_staged(connection, schema, name): + connection.execute(_q(schema, 'DELETE FROM {schema}.annotation_sidecars WHERE task = %s'), (name,)) + + +def named_sidecars(lines): + """The sidecar files the lines of a task's file name ([(record, line text)]).""" + found = set() + for _record, text in lines: + value = json.loads(text).get('value') + if isinstance(value, dict) and isinstance(value.get('file'), str): + found.add(value['file']) + return found diff --git a/tuldok_project/operations.py b/tuldok_project/operations.py index 4af24313..bfb6d283 100644 --- a/tuldok_project/operations.py +++ b/tuldok_project/operations.py @@ -63,6 +63,10 @@ class Operation: _TEXT = {'type': 'string'} _FLAG = {'type': 'boolean'} _OFFSET = {'type': 'integer', 'minimum': 0} +# An annotation set (spec-t4.md section 6): 'kept' or the reference of a dataset that annotates the task. +_SETS = {'type': 'array', 'minItems': 2, 'maxItems': 8, + 'items': {'type': 'string', 'minLength': 1, 'maxLength': 200}} +_CONFIDENCE = {'type': 'number', 'minimum': 0, 'maximum': 1} _THEME = {'type': 'string', 'enum': ['light', 'dark']} _TARGETS = {'type': 'array', 'items': _REFERENCE, 'maxItems': TARGET_LIMIT} _ADDRESS = {'type': 'string', 'minLength': 1, 'maxLength': 4096} # a path in a product; '!' names an archive member @@ -327,6 +331,27 @@ def _arguments(required=(), **properties): profile={'type': 'string', 'minLength': 1, 'maxLength': 128}, instruction={'type': 'string', 'minLength': 1, 'maxLength': INSTRUCTION_CHARACTERS}), ('task', 'record', 'suggestion')), + # spec-t4.md section 6: the sets of a task, their agreement, one record compared, and the decision kept. + Operation('annotation_sets', "List a task's annotation sets: the kept set and each annotator's product, with " + 'what made it and how many records it annotates.', 'inspect', False, + _arguments(['task'], task=_NAME), ('task', 'type', 'sets')), + Operation('annotation_agreement', "Measure how far two or more of a task's annotation sets agree, per pair and " + 'per record, with the records they disagree on most first.', 'inspect', False, + _arguments(['task'], task=_NAME, sets=_SETS, min_confidence=_CONFIDENCE, offset=_OFFSET, + limit=_limit(200)), + ('task', 'type', 'measure', 'sets', 'pairs', 'fleiss', 'records', 'disputed', 'total', 'offset', + 'limit', 'truncated', 'problems')), + Operation('annotation_compare', "Read one record's annotation in each of the named sets, ready to draw, and " + 'how far each pair agrees on it.', 'inspect', False, + _arguments(['task', 'record', 'sets'], task=_NAME, record=_RECORD_ID, + sets={**_SETS, 'minItems': 1}, min_confidence=_CONFIDENCE), + ('task', 'type', 'record', 'in_product', 'size', 'sets', 'pairs', 'frames', 'series', 'problem')), + Operation('keep_annotation', "Keep one set's annotation of a record, two sets' together, or reject them, as an " + 'unsaved edit of the kept annotations.', 'edit', True, + _arguments(['task', 'record', 'keep', 'sets'], task=_NAME, record=_RECORD_ID, + keep={'type': 'string', 'enum': ['one', 'both', 'none']}, sets={**_SETS, 'minItems': 1}, + note={'type': 'string', 'maxLength': 4000}), + ('task', 'record', 'state', 'unsaved')), Operation('set_definition', "Check a definition's text and keep it as an unsaved edit.", 'edit', True, _arguments(['reference', 'text'], reference=_REFERENCE, text=_TEXT), DEFINITION), Operation('remove_definition', 'Mark a definition that nothing uses as removed, until the project is saved.', diff --git a/tuldok_project/service.py b/tuldok_project/service.py index 00210082..4e009af4 100644 --- a/tuldok_project/service.py +++ b/tuldok_project/service.py @@ -58,7 +58,7 @@ import jsonschema import psycopg -from . import (activity, annotation_records, annotation_rows, annotations, build_requests, builds, charts, check, +from . import (activity, annotation_records, annotation_review, annotation_rows, annotations, build_requests, builds, charts, check, comparing, documents, environments, inside, inside_fields, inside_graph, inside_weights, launcher, local, operations, plan, pumas, store, training, workspace) from .documents import Problem @@ -115,12 +115,14 @@ 'training_sample': lambda run, a: training.sample(run, index=a['index']), } # The reads of annotations (spec-d4.md section 5): each takes the service's lock itself, only for its database work. -ANNOTATION_READS = ('annotation_tasks', 'annotated_records', 'annotation') +ANNOTATION_READS = ('annotation_tasks', 'annotated_records', 'annotation', + 'annotation_sets', 'annotation_agreement', 'annotation_compare') # the last three: spec-t4 # The calls to the Pumas endpoint (spec-d5.md): each is made outside the service's lock; those that read a project # take the lock themselves, only for their database work. # The comparisons of spec-t3.md that resample per-case values: read under the lock, computed outside it. COMPARING_READS = ('intervals', 'model_compare') -OUTSIDE_LOCK = ANNOTATION_READS + COMPARING_READS + ('endpoint', 'set_endpoint', 'find_endpoints', +# keep_annotation reads the sets outside the lock, then keeps its decision as set_annotation does (spec-t4.md). +OUTSIDE_LOCK = ANNOTATION_READS + COMPARING_READS + ('keep_annotation', 'endpoint', 'set_endpoint', 'find_endpoints', 'suggestion_models', 'suggest_annotation') POLL_SECONDS = 1.0 # how often the worker looks for a queued request CLOSE_SECONDS = 30.0 # how long close() waits for the worker @@ -191,6 +193,8 @@ def _detail(name, result): return f'{result["reverted"]} reverted' if name == 'set_endpoint': return 'set' if result['address'] else 'cleared' + if name == 'keep_annotation': + return f'{result["record"]} {result["state"]}' return '' @@ -947,6 +951,39 @@ def check(value): 'suggestion': {'value': value, 'from': {'model': entry['model'], 'profile': entry['profile'], 'capability': found[0]['capability']}}} + # --------------------------------------------- annotation sets (spec-t4.md) + + def _review(self, task): + """What the database holds of a task's sets (annotation_review.gather), read under the lock.""" + with self._lock, self._open() as project: + name, document = project.annotation_task(task) + return annotation_review.gather(project, name, document, self._located(project, document)) + + def _annotation_sets(self, arguments, actor): + return annotation_review.sets_answer(self._review(arguments['task'])) + + def _annotation_agreement(self, arguments, actor): + return annotation_review.agreement_answer(self._review(arguments['task']), arguments) + + def _annotation_compare(self, arguments, actor): + gathered = self._review(arguments['task']) + product, index = self._product_of(gathered['located']) + return annotation_review.compare_answer(gathered, arguments, product, index) + + def _keep_annotation(self, arguments, actor): + """A decision on one record kept through set_annotation's own path, its sidecars staged first.""" + gathered = self._review(arguments['task']) + item, origin, staged = annotation_review.keep_items(gathered, arguments) + if staged: + with self._lock, self._open() as project: + for file, data in staged.items(): + annotation_rows.stage_sidecar(project._connection, project.schema, gathered['name'], file, data) + setting = {'task': arguments['task'], 'items': [item], 'from': origin} + prepared = self._prepare_annotations(setting) + with self._lock: + done = self._set_annotation(setting, actor, prepared) + return {'task': done['task'], 'record': arguments['record'], 'state': item['state'], 'unsaved': done['unsaved']} + # ------------------------------------------------------------- changes def _set_definition(self, arguments, actor): diff --git a/tuldok_project/store.py b/tuldok_project/store.py index 00713bf7..44b4a1a0 100644 --- a/tuldok_project/store.py +++ b/tuldok_project/store.py @@ -1009,16 +1009,21 @@ def save(self): _write_path(root, folder_reader.RESULTS, f'{name}.csv', text.encode('utf-8')) results_written.append(name) annotations_written, annotations_deleted = [], [] - for name, data, must_change, _ in lines_plan: + for name, data, must_change, lines in lines_plan: if must_change and data is None: _delete_path(root, folder_reader.ANNOTATIONS, name + folder_reader.LINES_SUFFIX) annotations_deleted.append(annotation_rows.path(name)) elif must_change: _write_path(root, folder_reader.ANNOTATIONS, name + folder_reader.LINES_SUFFIX, data) annotations_written.append(annotation_rows.path(name)) + if must_change: + _save_sidecars(root, name, lines if data is not None else [], + annotation_rows.staged_sidecars(self._connection, self.schema, name)) with self._connection.transaction(): - for name, data, _, lines in lines_plan: + for name, data, must_change, lines in lines_plan: annotation_rows.mark_saved(self._connection, self.schema, name, lines) + if must_change: + annotation_rows.drop_staged(self._connection, self.schema, name) if data is None: annotation_rows.forget_file(self._connection, self.schema, name) else: # the file now holds data: its digest is known, its size and time are read @@ -1309,6 +1314,28 @@ def _delete_file(root, reference): _delete_path(root, directory, f'{name}.json') +def _save_sidecars(root, name, lines, staged): + """annotations/<name>/ holding exactly the sidecars the saved lines name (spec-t4.md section 2). + + A named sidecar not there is written from those kept here (staged); one + there that no line names is removed, and the directory when it is left + empty. Only files named by content are touched. + """ + from .annotation_payloads import is_kept_name + directory = f'{folder_reader.ANNOTATIONS}/{name}' + full = os.path.join(root, directory) + named = annotation_rows.named_sidecars(lines) + present = set(os.listdir(full)) if os.path.isdir(full) and not os.path.islink(full) else set() + for file in sorted(named - present): + if file in staged and is_kept_name(file): + _write_path(root, directory, file, staged[file]) + for file in sorted(present - named): + if is_kept_name(file): + _delete_path(root, directory, file) + if os.path.isdir(full) and not os.listdir(full): + os.rmdir(full) + + def _delete_path(root, directory, filename): target_directory = os.path.join(root, directory) try: From 900b1f2390228e6c2ff8374cf372efd4dc804527 Mon Sep 17 00:00:00 2001 From: MrScripty <TheEnvironmentGuy@protonmail.com> Date: Thu, 19 Nov 2026 07:20:49 -0700 Subject: [PATCH 113/131] feat(workspace): Review mode on the Annotate tab, overlays of every annotation type Two of a task's sets compared side by side or overlaid: masks, polygons, boxes, keypoints and depth drawn on the image, point objects and 3-D box wireframes on the point cloud, stretches under a series or a sound, tracks on an array's frames with a slider. The agreement, the most disputed records, Keep A / Keep B / Keep both / Reject both through keep_annotation, and a light correction of kept polygons and point objects. Parts are put in place only when they differ. New task offers the nine new types. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --- app.py | 2 + static/project-workspace.html | 2 + static/project-workspace/annotate.js | 70 ++-- static/project-workspace/inside.js | 23 +- static/project-workspace/review.css | 35 ++ static/project-workspace/review.js | 467 +++++++++++++++++++++++++++ 6 files changed, 576 insertions(+), 23 deletions(-) create mode 100644 static/project-workspace/review.css create mode 100644 static/project-workspace/review.js diff --git a/app.py b/app.py index 17867fdf..0a8c3182 100644 --- a/app.py +++ b/app.py @@ -800,6 +800,8 @@ def _get(self): '/project-workspace/compare.css': ('project-workspace/compare.css', 'text/css'), '/project-workspace/compare.js': ('project-workspace/compare.js', 'text/javascript'), '/project-workspace/parallel.js': ('project-workspace/parallel.js', 'text/javascript'), + '/project-workspace/review.css': ('project-workspace/review.css', 'text/css'), + '/project-workspace/review.js': ('project-workspace/review.js', 'text/javascript'), '/project-workspace/adapter.js': ('project-workspace/adapter.js', 'text/javascript'), '/project-workspace/charts.js': ('project-workspace/charts.js', 'text/javascript'), '/project-workspace/markdown.js': ('project-workspace/markdown.js', 'text/javascript'), diff --git a/static/project-workspace.html b/static/project-workspace.html index 805509bf..687720f3 100644 --- a/static/project-workspace.html +++ b/static/project-workspace.html @@ -9,6 +9,7 @@ <link rel="stylesheet" href="/auth.css"> <link rel="stylesheet" href="/project-workspace/base.css"> <link rel="stylesheet" href="/project-workspace/compare.css"> +<link rel="stylesheet" href="/project-workspace/review.css"> <script defer src="/auth.js"></script> <script defer src="/project-workspace/adapter.js"></script> <script defer src="/project-workspace/charts.js"></script> @@ -23,6 +24,7 @@ <script defer src="/project-workspace/fields.js"></script> <script defer src="/project-workspace/training.js"></script> <script defer src="/project-workspace/annotate.js"></script> +<script defer src="/project-workspace/review.js"></script> <script defer src="/project-workspace/generate.js"></script> <script defer src="/project-workspace/parallel.js"></script> <script defer src="/project-workspace/tabs.js"></script> diff --git a/static/project-workspace/annotate.js b/static/project-workspace/annotate.js index 857f5494..42ce325f 100644 --- a/static/project-workspace/annotate.js +++ b/static/project-workspace/annotate.js @@ -18,10 +18,13 @@ window.LabAnnotate = (() => { const P = window.TuldokProject, S = window.LabScreens, A = window.LabActions, C = window.LabCharts, h = C.h, V = window.LabInside.viewers; const { sect, putInPlace, putDrawer, turn, time, bytes } = S.parts; const PER_PAGE = 48; - const TYPES = ['review', 'class', 'tags', 'text', 'boxes', 'spans', 'segments']; - const TYPE_WORD = { review: 'Review', class: 'Class: one term', tags: 'Tags: any of the terms', text: 'Text: a caption or a transcript', boxes: 'Boxes on an image', spans: 'Spans of a text', segments: 'Segments of a sound' }; - const NEEDS_TERMS = ['class', 'tags', 'boxes', 'spans', 'segments']; - const ONLY = { boxes: 'image', spans: 'text', segments: 'audio' }; // the one kind of record these tasks describe + const TYPES = ['review', 'class', 'tags', 'text', 'boxes', 'spans', 'segments', 'polygons', 'mask', 'depth', 'keypoints', 'ranking', 'timeseries', 'track', 'points', 'box3d']; + const TYPE_WORD = { review: 'Review', class: 'Class: one term', tags: 'Tags: any of the terms', text: 'Text: a caption or a transcript', boxes: 'Boxes on an image', spans: 'Spans of a text', segments: 'Segments of a sound', + polygons: 'Polygons on an image', mask: 'A mask of an image', depth: 'A depth map of an image', keypoints: 'Keypoints on an image', ranking: 'A ranking of candidates', timeseries: 'Stretches of a series or a sound', track: 'Tracks across frames', points: 'Point objects of a point cloud', box3d: '3-D boxes in a point cloud' }; + const NEEDS_TERMS = ['class', 'tags', 'boxes', 'spans', 'segments', 'polygons', 'mask', 'keypoints', 'ranking', 'timeseries', 'track', 'points', 'box3d']; + // The kinds of record a task describes (spec-d4, spec-t4 section 1); the others take any kind but file. + const ONLY = { boxes: ['image'], spans: ['text'], segments: ['audio'], polygons: ['image'], mask: ['image'], depth: ['image'], keypoints: ['image'], timeseries: ['audio', 'array'], track: ['array'], points: ['pointcloud'], box3d: ['pointcloud'] }; + const GENERATED = ['polygons', 'mask', 'depth', 'keypoints', 'ranking', 'timeseries', 'track', 'points', 'box3d']; // reviewed, not drawn here const FILTERS = [['all', 'All'], ['todo', 'To do'], ['accepted', 'Accepted'], ['needs-work', 'Needs work'], ['rejected', 'Rejected'], ['stale', 'Stale']]; const DECISIONS = [['accepted', 'Accept', 'ok'], ['needs-work', 'Needs work', 'warn'], ['rejected', 'Reject', 'bad']]; const STATE = { none: ['neutral', 'not annotated'], draft: ['neutral', 'draft'], accepted: ['good', 'accepted'], 'needs-work': ['warn', 'needs work'], rejected: ['serious', 'rejected'] }; @@ -37,13 +40,13 @@ window.LabAnnotate = (() => { const textOf = doc => JSON.stringify(doc, null, 2) + '\n'; // ---- What is kept in this page ------------------------------------------------------------------------------------ - const ui = { task: null, filter: 'all', page: 0, sel: new Map(), selAt: 0, terms: new Map() }; // sel and terms: per task + const ui = { task: null, filter: 'all', page: 0, sel: new Map(), selAt: 0, terms: new Map(), mode: 'annotate' }; // sel and terms: per task const drafts = new Map(); // task + '\n' + record -> { state, value, note, dirty } const store = new Map(); // the viewers' settings (inside.js), per record let here = null; // the tab on screen: { main, act, root, keys, parts, t, page, rec, pick, repaint, relist } const draftKey = (t, rec) => t.task + '\n' + rec.id; - function emptyValue(type) { return type === 'class' || type === 'review' ? null : type === 'text' ? '' : []; } + function emptyValue(type) { return type === 'class' || type === 'review' || GENERATED.includes(type) ? null : type === 'text' ? '' : []; } /** A draft from the annotation as it is (not typed yet), or the one typed. */ function draftOf(t, rec, fresh) { const k = draftKey(t, rec), had = drafts.get(k); @@ -85,7 +88,9 @@ window.LabAnnotate = (() => { ui.selAt = 0; if (id) ui.sel.set(t.task, id); else ui.sel.delete(t.task); // The models that can suggest (spec-d5 section 4), for a session that may annotate; none when they cannot be read. const offers = A.may('edit') && SUGGESTS.includes(t.type) ? await P.read('suggestion_models', { task: t.task }).then(r => r.kinds || {}, () => ({})) : {}; - return { tasks, t, page, rec: page.records.find(r => r.id === id) || null, offers }; + // The task's annotation sets (spec-t4 section 6): Review is offered when an annotator made one. + const sets = await P.read('annotation_sets', { task: t.task }).then(r => r.sets, () => []); + return { tasks, t, page, rec: page.records.find(r => r.id === id) || null, offers, sets }; } // ---- The tab ----------------------------------------------------------------------------------------------------- @@ -111,9 +116,10 @@ window.LabAnnotate = (() => { main.setAttribute('aria-busy', 'true'); let got; try { got = await load(); } catch (error) { got = { error }; } if (main._paint !== mine || main._view !== view) return; - const kind = got.error ? 'error' : !got.tasks.length ? 'none' : !got.t.run ? 'unbuilt' : 'records'; + const reviewing = !got.error && got.t && got.t.run && ui.mode === 'review' && reviewable(got.sets); + const kind = got.error ? 'error' : !got.tasks.length ? 'none' : !got.t.run ? 'unbuilt' : reviewing ? 'review' : 'records'; const t = got.t || null, rec = got.rec || null, may = A.may('edit'); - const keys = { shape: kind, bar: kind === 'error' ? 'error' : JSON.stringify([got.tasks.map(x => [x.task, x.title, x.type]), t && [t.task, t.run, t.records, t.counts, t.dataset], ui.filter, may]) }; + const keys = { shape: kind, bar: kind === 'error' ? 'error' : JSON.stringify([got.tasks.map(x => [x.task, x.title, x.type]), t && [t.task, t.run, t.records, t.counts, t.dataset], ui.filter, may, ui.mode, reviewable(got.sets)]) }; if (kind === 'records') { keys.list = JSON.stringify([t.task, t.run, ui.filter, ui.page, got.page.total, got.page.records.map(r => [r.id, r.kind, r.path, r.preview || null, r.in_product, r.annotation && [r.annotation.state, r.annotation.stale, r.annotation.unsaved]])]); keys.view = rec ? JSON.stringify([t.task, t.type, t.run, rec.id, rec.kind, rec.in_product]) : 'none'; // its place in the list is set in place (place()) @@ -129,12 +135,13 @@ window.LabAnnotate = (() => { } catch (error) { build.view = h('div', 'iv'); build.view.appendChild(A.refusal(error)); } if (main._paint !== mine || main._view !== view) return; main.removeAttribute('aria-busy'); - here.t = t; here.page = got.page || null; here.rec = rec; here.tasks = got.tasks; here.offers = got.offers || {}; + here.t = t; here.page = got.page || null; here.rec = rec; here.tasks = got.tasks; here.offers = got.offers || {}; here.sets = got.sets || []; const fresh = !here.root || keys.shape !== here.keys.shape; if (fresh) { const root = h('div', 'annotate'); root.dataset.shape = kind; here.parts = { bar: h('div', 'ann-barbox') }; root.appendChild(here.parts.bar); - if (kind === 'records') { const body = h('div', 'ann-body'); for (const p of ['list', 'view', 'form']) { here.parts[p] = h('div', 'ann-' + p); body.appendChild(here.parts[p]); } here.parts.view.classList.add('viewer'); here.parts.view.setAttribute('aria-label', 'The record'); root.appendChild(body); } + if (kind === 'review') { here.parts.review = h('div', 'ann-review'); root.appendChild(here.parts.review); } + else if (kind === 'records') { const body = h('div', 'ann-body'); for (const p of ['list', 'view', 'form']) { here.parts[p] = h('div', 'ann-' + p); body.appendChild(here.parts[p]); } here.parts.view.classList.add('viewer'); here.parts.view.setAttribute('aria-label', 'The record'); root.appendChild(body); } else { here.parts.msg = h('div', 'ann-msg'); root.appendChild(here.parts.msg); } here.keys = { shape: kind }; here.root = root; @@ -144,7 +151,13 @@ window.LabAnnotate = (() => { here.keys[name] = keys[name]; const content = make(); if (fresh) here.parts[name].replaceChildren(content); else putInPlace(here.parts[name], content, main); }; - put('bar', () => kind === 'error' ? h('div') : buildBar(got.tasks, t)); + put('bar', () => kind === 'error' ? h('div') : buildBar(got.tasks, t, got.sets)); + if (kind === 'review') { + if (fresh) putInPlace(main, here.root); + main._painted = view; + await window.LabReview.draw(here.parts.review, t, got.sets, here.act); + return; + } if (kind === 'records') { put('list', () => buildList(t, got.page)); put('view', () => { const hooks = build.view._hooks || {}; here.repaint = hooks.repaint || null; here.textOf = hooks.textOf || null; here.play = hooks.play || null; return build.view; }); @@ -174,7 +187,9 @@ window.LabAnnotate = (() => { } // ---- The bar ----------------------------------------------------------------------------------------------------- - function buildBar(tasks, t) { + /** Review needs a set made by an annotator besides the kept set. */ + const reviewable = sets => (sets || []).some(x => x.set !== 'kept'); + function buildBar(tasks, t, sets) { const bar = h('div', 'ann-bar'); if (tasks.length) { const l = h('label', 'ann-task'); l.appendChild(document.createTextNode('Task')); @@ -184,6 +199,12 @@ window.LabAnnotate = (() => { l.appendChild(s); bar.appendChild(l); } bar.appendChild(A.group('annotate:new', [{ id: 'new', label: 'New task', cls: 'btn sm', who: 'edit', onClick: () => here.act.select('new-task') }], { inline: true })); + if (t && t.run && reviewable(sets)) { + const seg = h('div', 'seg ann-mode'); seg.setAttribute('role', 'group'); seg.setAttribute('aria-label', 'Annotate or review the annotators\' sets'); + for (const [id, label] of [['annotate', 'Annotate'], ['review', 'Review']]) { const b = button(null, label, 'ann:mode-' + id, () => { if (ui.mode !== id) { ui.mode = id; redraw(); } }); b.setAttribute('aria-pressed', String(ui.mode === id)); seg.appendChild(b); } + bar.appendChild(seg); + } + if (t && t.run && ui.mode === 'review' && reviewable(sets)) return bar; if (t && t.run) { const c = t.counts, n = { all: null, todo: c.unannotated + c.draft, accepted: c.accepted, 'needs-work': c['needs-work'], rejected: c.rejected, stale: c.stale }; const seg = h('div', 'seg ann-filter'); seg.setAttribute('role', 'group'); seg.setAttribute('aria-label', 'Show the records'); @@ -277,6 +298,7 @@ window.LabAnnotate = (() => { if (t.type === 'boxes' && rec.kind === 'image') boxView(el, got, t, rec); else if (t.type === 'spans' && rec.kind === 'text') spanView(el, got, t, rec); else if (t.type === 'segments' && rec.kind === 'audio') segmentView(el, got, t, rec); + else if (GENERATED.includes(t.type) && (draftOf(t, rec).value != null) && (el.appendChild(heading(rec.id, 'The kept annotation drawn over the record')), window.LabReview.overlay(el, got, t, draftOf(t, rec).value))) { /* drawn */ } else await V.record(el, got, t.run, store); return el; } @@ -525,7 +547,7 @@ window.LabAnnotate = (() => { // ---- The form ---------------------------------------------------------------------------------------------------- function buildForm(t, rec, detail) { here.relist = null; - const d = draftOf(t, rec, true), a = rec.annotation, may = A.may('edit'), fits = !ONLY[t.type] || rec.kind === ONLY[t.type]; + const d = draftOf(t, rec, true), a = rec.annotation, may = A.may('edit'), fits = !ONLY[t.type] || ONLY[t.type].includes(rec.kind); const form = h('div', 'inspector ann-formbox'); const hd = h('header'); hd.appendChild(h('span', 'kicker', t.title + ' · ' + t.type)); const t2 = h('h2', 'mono', rec.id); t2.tabIndex = -1; hd.appendChild(t2); @@ -547,7 +569,7 @@ window.LabAnnotate = (() => { const f = h('div', 'form ann-fields'); if (!rec.in_product) f.appendChild(h('p', 'note', 'Nothing can be set on a record that is not in the product.')); else if (rec.kind === 'file') f.appendChild(h('p', 'note', 'A file of no kind cannot be annotated.')); - else if (!fits) f.appendChild(h('p', 'note', 'This task annotates ' + ONLY[t.type] + ' records; this record is ' + (V.WORD[rec.kind] || rec.kind).toLowerCase() + ', so only a decision and a note can be kept for it.')); + else if (!fits) f.appendChild(h('p', 'note', 'This task annotates ' + ONLY[t.type].join(' or ') + ' records; this record is ' + (V.WORD[rec.kind] || rec.kind).toLowerCase() + ', so only a decision and a note can be kept for it.')); if (rec.in_product && rec.kind !== 'file' && fits) valueControls(f, t, rec, d, may); // The decision. const dl = h('div', 'ann-field'); dl.appendChild(h('h3', null, 'Decision')); @@ -583,6 +605,12 @@ window.LabAnnotate = (() => { /** The controls of the value, by task. */ function valueControls(f, t, rec, d, may) { if (t.type === 'review') return; + if (GENERATED.includes(t.type)) { // spec-t4: made by annotators and reviewed; the value is shown, not drawn here + const box = h('div', 'ann-field'); box.appendChild(h('h3', null, 'Value')); + box.appendChild(h('p', null, window.LabReview.summary(t, d.value))); + box.appendChild(h('p', 'small faint', here.sets && here.sets.some(x => x.set !== 'kept') ? 'This task\'s annotations are made by annotators: choose Review in the bar to compare their sets and keep one.' : 'This task\'s annotations are made by annotators (a dataset with the step annotate); the decision and the note can be kept here.')); + f.appendChild(box); return; + } if (t.type === 'text') { const l = h('label'); l.appendChild(document.createTextNode('Text')); const area = h('textarea'); area.rows = 5; area.value = d.value || ''; area.dataset.key = 'ann:text'; area.disabled = !may; area.placeholder = 'a caption, a transcript or a summary'; @@ -819,9 +847,12 @@ window.LabAnnotate = (() => { if (!sets.length) f.appendChild(h('p', 'failure', 'The project has no dataset: a task annotates the records of one.')); f.appendChild(choice(s, key, 'dataset', 'Dataset', sets.map(d => [d.reference, d.title + ' · ' + d.reference]), sets.length ? sets[0].reference : '')); const vocab = input(s, key, 'vocabulary', 'Vocabulary: one term per line', { area: 5, hint: '1 to 500 different terms of 1 to 200 characters', placeholder: 'clean\nnoisy\nbroken' }); - const showVocab = type => { vocab.hidden = !NEEDS_TERMS.includes(type); }; + const points = input(s, key, 'keypoints', 'Keypoints: one name per line', { area: 4, hint: 'the points of one instance, in the order its values list them', placeholder: 'head\ntail' }); + const units = input(s, key, 'units', 'Units of depth', { max: 40, placeholder: 'm' }); + const mode = choice(s, key, 'mask', 'A pixel\'s value is', [['semantic', 'its class (semantic)'], ['instance', 'one object (instance)']], 'semantic'); + const showVocab = type => { vocab.hidden = !NEEDS_TERMS.includes(type); points.hidden = type !== 'keypoints'; units.hidden = type !== 'depth'; mode.hidden = type !== 'mask'; }; f.appendChild(choice(s, key, 'task', 'Task', TYPES.map(x => [x, x + ' · ' + TYPE_WORD[x]]), 'class', showVocab)); - showVocab(s.text.task); f.appendChild(vocab); + f.appendChild(vocab); f.appendChild(points); f.appendChild(units); f.appendChild(mode); showVocab(s.text.task); ins.appendChild(f); const reference = () => 'annotations/' + (s.text.name || '').trim(); ins.appendChild(A.group(key, [ @@ -829,6 +860,9 @@ window.LabAnnotate = (() => { args: st => { const doc = { format: FORMAT, kind: 'annotation', title: (st.text.title || '').trim(), dataset: st.text.dataset, task: st.text.task }; if (NEEDS_TERMS.includes(st.text.task)) doc.vocabulary = lines(st.text.vocabulary); + if (st.text.task === 'keypoints') doc.keypoints = lines(st.text.keypoints); + if (st.text.task === 'depth') doc.units = (st.text.units || '').trim(); + if (st.text.task === 'mask' && st.text.mask === 'instance') doc.mask = 'instance'; return { reference: reference(), text: textOf(doc) }; }, done: r => { ui.task = r.reference; ui.page = 0; ui.filter = 'all'; act.select(null); } }, @@ -930,5 +964,5 @@ window.LabAnnotate = (() => { S.annotate = annotate; // The drawer forms' parts, for the Generate form (generate.js). const forms = { formDrawer, input, choice, header, slug, textOf }; - return { choose, datasetForm, forms }; + return { choose, datasetForm, forms, redraw }; })(); diff --git a/static/project-workspace/inside.js b/static/project-workspace/inside.js index 2ce407d1..bbd12c67 100644 --- a/static/project-workspace/inside.js +++ b/static/project-workspace/inside.js @@ -482,13 +482,26 @@ window.LabInside = (() => { } } ctx.putImageData(img, 0, 0); + // Wireframes (spec-t4: 3-D boxes): m.lines is [[x, y, z, x, y, z, [r, g, b]], ...], drawn over the points. + const project = (x, y, z) => { x -= centre[0]; y -= centre[1]; z -= centre[2]; const x1 = x * cy - y * sy, y1 = x * sy + y * cy; return [W / 2 + x1 * s, H / 2 - (-y1 * sp + z * cp) * s]; }; + for (const l of m.lines || []) { const a = project(l[0], l[1], l[2]), b = project(l[3], l[4], l[5]); ctx.strokeStyle = 'rgb(' + l[6].join(',') + ')'; ctx.lineWidth = Math.max(1, (window.devicePixelRatio || 1) * 1.5); ctx.beginPath(); ctx.moveTo(a[0], a[1]); ctx.lineTo(b[0], b[1]); ctx.stroke(); } + if (pick) { const k = W / cv.clientWidth; ctx.strokeStyle = 'rgb(' + token('--serious').join(',') + ')'; ctx.setLineDash([4, 3]); ctx.strokeRect(pick.x0 * k, pick.y0 * k, (pick.x1 - pick.x0) * k, (pick.y1 - pick.y0) * k); ctx.setLineDash([]); } + shown = { X, Y, W }; }; const later = () => { if (!frame) frame = requestAnimationFrame(draw); }; paints(cv, draw); - let drag = null; - cv.addEventListener('pointerdown', e => { if (e.button !== 0) return; drag = { x: e.clientX, y: e.clientY, id: e.pointerId }; cv.setPointerCapture(e.pointerId); cv.classList.add('dragging'); }); - cv.addEventListener('pointermove', e => { if (!drag || e.pointerId !== drag.id) return; st.yaw += (e.clientX - drag.x) * 0.01; st.pitch = Math.max(-1.55, Math.min(1.55, st.pitch + (e.clientY - drag.y) * 0.01)); drag.x = e.clientX; drag.y = e.clientY; later(); }); - const end = e => { if (drag && e.pointerId === drag.id) { drag = null; cv.classList.remove('dragging'); } }; + let drag = null, pick = null, shown = null; + // With m.select and st.selecting, a drag draws a rectangle and m.select gets the indices of the points shown in it. + cv.addEventListener('pointerdown', e => { if (e.button !== 0) return; const q = cv.getBoundingClientRect(); if (m.select && st.selecting) { pick = { x0: e.clientX - q.left, y0: e.clientY - q.top, x1: e.clientX - q.left, y1: e.clientY - q.top, id: e.pointerId, left: q.left, top: q.top }; cv.setPointerCapture(e.pointerId); later(); return; } drag = { x: e.clientX, y: e.clientY, id: e.pointerId }; cv.setPointerCapture(e.pointerId); cv.classList.add('dragging'); }); + cv.addEventListener('pointermove', e => { if (pick && e.pointerId === pick.id) { pick.x1 = e.clientX - pick.left; pick.y1 = e.clientY - pick.top; later(); return; } if (!drag || e.pointerId !== drag.id) return; st.yaw += (e.clientX - drag.x) * 0.01; st.pitch = Math.max(-1.55, Math.min(1.55, st.pitch + (e.clientY - drag.y) * 0.01)); drag.x = e.clientX; drag.y = e.clientY; later(); }); + const end = e => { + if (pick && e.pointerId === pick.id) { + const k = shown ? shown.W / cv.clientWidth : 1, [x0, x1] = [Math.min(pick.x0, pick.x1) * k, Math.max(pick.x0, pick.x1) * k], [y0, y1] = [Math.min(pick.y0, pick.y1) * k, Math.max(pick.y0, pick.y1) * k], found = []; + if (shown) for (let i = 0; i < shown.X.length; i++) if (shown.X[i] >= x0 && shown.X[i] <= x1 && shown.Y[i] >= y0 && shown.Y[i] <= y1) found.push(i); + pick = null; later(); m.select(found); return; + } + if (drag && e.pointerId === drag.id) { drag = null; cv.classList.remove('dragging'); } + }; cv.addEventListener('pointerup', end); cv.addEventListener('pointercancel', end); cv.addEventListener('wheel', e => { e.preventDefault(); st.zoom = Math.max(0.2, Math.min(25, st.zoom * Math.exp(-e.deltaY * 0.0015))); later(); }, { passive: false }); cv.addEventListener('keydown', e => { @@ -699,6 +712,6 @@ window.LabInside = (() => { * `record` (run: the product's run; store: a Map that keeps each viewer's settings, as a dataset opened here does), * and the parts its own drawing surfaces share with these viewers. */ - const viewers = { record: (el, got, run, store) => recordView(null, { run, viewers: store }, el, got), wave, paints, fit, token, glyph, WORD }; + const viewers = { record: (el, got, run, store) => recordView(null, { run, viewers: store }, el, got), wave, paints, fit, token, glyph, WORD, space, turned }; return { open, leave, PER_PAGE, viewers, drawing: { floats, token, ramp, paints, fit, heat, contain, ordinal } }; })(); diff --git a/static/project-workspace/review.css b/static/project-workspace/review.css new file mode 100644 index 00000000..c97c036c --- /dev/null +++ b/static/project-workspace/review.css @@ -0,0 +1,35 @@ +/* Review mode of the Annotate tab (docs/plans/training-and-curation/spec-t4.md section 7). The three columns are + the Annotate tab's own (.ann-body, .ann-list, .ann-view, .ann-form in base.css); only what review adds is here. */ +.ann-mode { flex: 0 0 auto; } +.rv-picks { display: grid; grid-template-columns: minmax(0, 1fr); gap: 6px; margin-bottom: 8px; } +.rv-pick, .rv-min { display: grid; grid-template-columns: 2.2em minmax(0, 1fr); gap: 6px; align-items: center; font-size: 12.5px; color: var(--ink-2); min-width: 0; } +.rv-min { grid-template-columns: auto 5.5em; margin: 8px 0 12px; } +.rv-pick select { min-width: 0; width: 100%; } +.rv-mode { margin: 4px 0; } +.rv-agree { border: 1px solid var(--line); border-radius: 8px; padding: 10px 12px; margin-bottom: 14px; background: var(--surface); min-width: 0; } +.rv-agree .rv-score { display: block; font-size: 28px; line-height: 1.1; margin: 2px 0 4px; color: var(--ink); } +.rv-figures { margin: 8px 0 0; } +.rv-disputed { list-style: none; margin: 0; padding: 0; display: grid; gap: 4px; max-height: 60vh; overflow-y: auto; } +.rv-rec { display: grid; grid-template-columns: minmax(0, 1fr) 64px 3.2em; grid-template-areas: "id bar n" "miss miss miss"; gap: 2px 8px; align-items: center; width: 100%; + text-align: left; padding: 6px 8px; border: 1px solid var(--line); border-radius: 6px; background: transparent; color: var(--ink); font: inherit; cursor: pointer; min-width: 0; } +.rv-rec[aria-pressed="true"] { border-color: var(--accent); background: var(--accent-wash); } +.rv-rec .rv-id { grid-area: id; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-size: 12.5px; } +.rv-rec .rv-bar { grid-area: bar; display: block; height: 6px; border-radius: 3px; background: var(--line); overflow: hidden; } +.rv-rec .rv-bar b { display: block; height: 100%; background: var(--serious); } +.rv-rec .rv-dis { grid-area: n; text-align: right; } +.rv-rec .faint { grid-area: miss; } +.rv-legend { display: flex; flex-wrap: wrap; align-items: center; gap: 4px; margin: 0 0 8px; } +.rv-sw { display: inline-block; width: 12px; height: 12px; border-radius: 2px; margin-right: 2px; } +.rv-panels { display: grid; grid-template-columns: minmax(0, 1fr); gap: 12px; } +.rv-panels.two { grid-template-columns: repeat(2, minmax(0, 1fr)); } +@container (max-width: 700px) { .rv-panels.two { grid-template-columns: minmax(0, 1fr); } } +.rv-panel { margin: 0; min-width: 0; } +.rv-panel figcaption { margin-bottom: 4px; color: var(--ink-2); overflow-wrap: anywhere; } +.rv-canvas { display: block; width: 100%; border: 1px solid var(--line); border-radius: 4px; background: var(--surface); } +.rv-canvas:focus-visible { outline: 2px solid var(--focus); outline-offset: 2px; } +.rv-frame { display: flex; flex-wrap: wrap; gap: 8px; align-items: center; margin-top: 10px; font-size: 12.5px; color: var(--ink-2); } +.rv-frame input { flex: 1 1 160px; min-width: 0; } +.rv-values dd { overflow-wrap: anywhere; white-space: pre-wrap; } +.rv-decide .seg, .rv-decide .actions { flex-wrap: wrap; } +.rv-kept { margin: 8px 0 12px; overflow-wrap: anywhere; } +.rv-correct { border-top: 1px solid var(--line); padding-top: 10px; } diff --git a/static/project-workspace/review.js b/static/project-workspace/review.js new file mode 100644 index 00000000..ae0c6f14 --- /dev/null +++ b/static/project-workspace/review.js @@ -0,0 +1,467 @@ +'use strict'; +// Review mode of the Annotate tab (docs/plans/training-and-curation/spec-t4.md section 7): two of a task's annotation +// sets (the kept set and the annotators' products) compared. Left: the set choosers, side by side or overlaid, the +// confidence filter, the agreement of the two and the records they disagree on most. Middle: the record with each +// set drawn over it (masks, polygons, boxes, keypoints and depth on an image; point objects and 3-D boxes on a point +// cloud; timeseries and segments as bands under a sound or a series; tracks on an array's frames with a frame +// slider). Right: each set's value in words, this record's agreement, and the decision (Keep A, Keep B, Keep both, +// Reject both), kept with keep_annotation as an unsaved edit that Save writes. A light correction of the kept value +// (a polygon's vertices moved or deleted, points removed from a point object) is kept with set_annotation. +// +// Updating in place (spec-w4): the three parts are each built off the page and put in place only when what they show +// differs; the selection is set in place; the frame slider repaints the canvases without drawing anything again. +// The choices (sets, mode, filter, record, frame, a correction under way) are the page's and survive readings. +window.LabReview = (() => { + const P = window.TuldokProject, S = window.LabScreens, A = window.LabActions, C = window.LabCharts, h = C.h, V = window.LabInside.viewers, D = window.LabInside.drawing; + const { sect, putInPlace } = S.parts; + const NEW = ['polygons', 'mask', 'depth', 'keypoints', 'ranking', 'timeseries', 'track', 'points', 'box3d']; + const LISTS = ['boxes', 'spans', 'segments', 'polygons', 'keypoints', 'timeseries', 'track', 'box3d']; + const KEPT = 'kept'; + const count = (n, one, many) => n.toLocaleString('en-GB') + ' ' + (n === 1 ? one : many || one + 's'); + const button = (cls, text, key, onClick) => { const b = h('button', cls, text); b.type = 'button'; if (key) b.dataset.key = key; if (onClick) b.addEventListener('click', onClick); return b; }; + const rgb = (c, a) => a == null ? 'rgb(' + c.join(',') + ')' : 'rgba(' + c.join(',') + ',' + a + ')'; + const fixed = (v, n = 2) => v == null || !Number.isFinite(v) ? '—' : v.toFixed(n); + const shortSet = name => name === KEPT ? 'kept' : name.slice(name.indexOf('/') + 1); + const copy = v => v == null ? v : JSON.parse(JSON.stringify(v)); + + // ---- What is kept in this page ------------------------------------------------------------------------------- + const ui = { pick: new Map(), mode: 'side', min: new Map(), sel: new Map(), frame: 0, editing: null, removing: false, notes: new Map() }; + const store = new Map(); // the 3-D views' settings, per record and panel + let here = null; // { box, t, keys, parts, repaint: [] } + + const keepPaint = paint => { if (here && here.repaint) here.repaint.push(paint); }; + /** Is list value: the types whose value may be two sets' together. */ + const isList = (t, v) => Array.isArray(v) && (LISTS.includes(t.type) || t.type === 'points'); + function choose(t, sets) { + const usable = sets.filter(s => !s.problem && (s.annotated || s.set === KEPT)).map(s => s.set); + let [a, b] = ui.pick.get(t.task) || []; + const made = usable.filter(n => n !== KEPT); + if (!usable.includes(a)) a = made[0] || usable[0]; + if (!usable.includes(b) || b === a) b = made.find(n => n !== a) || usable.find(n => n !== a); + ui.pick.set(t.task, [a, b]); + return { a, b, usable }; + } + + async function load(t, sets) { + const { a, b, usable } = choose(t, sets), min = ui.min.get(t.task); + if (!a || !b) return { a, b, usable, agreement: null }; + const args = { task: t.task, sets: [a, b], limit: 200 }; if (min != null) args.min_confidence = min; + const agreement = await P.read('annotation_agreement', args); + let fleiss = null; + if (t.type === 'class' && usable.length >= 3) fleiss = await P.read('annotation_agreement', { task: t.task, sets: usable.slice(0, 8), limit: 1 }).then(r => r.fleiss, () => null); + let id = ui.sel.get(t.task); + if (!id || !agreement.disputed.some(r => r.record === id)) id = agreement.disputed.length ? agreement.disputed[0].record : null; + if (id) ui.sel.set(t.task, id); + let compare = null, record = null, kept = null; + if (id) { + const names = [a, b].concat(a !== KEPT && b !== KEPT ? [KEPT] : []), cargs = { task: t.task, record: id, sets: names }; if (min != null) cargs.min_confidence = min; + [compare, kept] = await Promise.all([P.read('annotation_compare', cargs), P.annotations.one(t.task, id).catch(() => null)]); + if (compare.in_product) record = await P.product.record(t.run, id).catch(error => ({ error })); + } + return { a, b, usable, agreement, fleiss, id, compare, record, kept }; + } + + /** Draws review mode into box: each part put in place only when its content differs. */ + async function draw(box, t, sets, act) { + const mine = (box._review = (box._review || 0) + 1); + if (!here || here.box !== box) here = { box, keys: {}, parts: null, repaint: [] }; + here.act = act; here.t = t; + let got; try { got = await load(t, sets); } catch (error) { got = { error }; } + if (box._review !== mine) return; + const may = A.may('edit'); + const keys = { + left: JSON.stringify([t.task, got.error ? got.error.message : null, got.a, got.b, got.usable, ui.mode, ui.min.get(t.task), got.agreement, got.fleiss]), + middle: JSON.stringify([t.task, got.id, got.compare, got.record && (got.record.error ? 'error' : got.record.record), ui.mode, ui.editing && [ui.editing.key, ui.editing.version], ui.removing]), + right: JSON.stringify([t.task, got.id, got.compare && got.compare.sets.map(s => [s.set, s.value, s.confidence]), got.compare && got.compare.pairs, got.kept && [got.kept.annotation, got.kept.unsaved], may, ui.editing && [ui.editing.key, ui.editing.dirty, ui.editing.removed], ui.removing, got.a, got.b]) + }; + if (!here.parts) { + const body = h('div', 'ann-body rv-body'); + here.parts = { left: h('div', 'ann-list rv-left'), middle: h('div', 'ann-view viewer rv-middle'), right: h('div', 'ann-form rv-right') }; + here.parts.middle.setAttribute('aria-label', 'The record and its annotations'); + for (const p of ['left', 'middle', 'right']) body.appendChild(here.parts[p]); + box.replaceChildren(body); + } + here.got = got; + const put = (name, make) => { if (here.keys[name] === keys[name]) return; here.keys[name] = keys[name]; putInPlace(here.parts[name], make(), box.closest('main') || box); }; + put('left', () => buildLeft(t, sets, got)); + put('middle', () => { here.repaint = []; return buildMiddle(t, got); }); + put('right', () => buildRight(t, got, may)); + for (const b of here.parts.left.querySelectorAll('.rv-rec')) { const on = String(b.dataset.id === got.id); if (b.getAttribute('aria-pressed') !== on) b.setAttribute('aria-pressed', on); } + } + const again = () => { if (here && here.box && here.box.isConnected) window.LabAnnotate.redraw(); }; + + // ---- Left: choosers, agreement, the disputed list ------------------------------------------------------------- + function buildLeft(t, sets, got) { + const box = h('div', 'rv-leftbox'); + if (got.error) { box.appendChild(A.refusal(got.error)); return box; } + const pick = (label, which, value) => { + const l = h('label', 'rv-pick'); l.appendChild(document.createTextNode(label)); + const s = h('select'); s.dataset.key = 'rv:set-' + which; + for (const name of got.usable) { const found = sets.find(x => x.set === name) || {}; const o = h('option', null, shortSet(name) + (found.by && found.by.name ? ' · ' + found.by.name : '') + ' (' + count(found.annotated || 0, 'record') + ')'); o.value = name; o.selected = name === value; s.appendChild(o); } + s.addEventListener('change', () => { const pair = ui.pick.get(t.task).slice(); pair[which === 'a' ? 0 : 1] = s.value; if (pair[0] === pair[1]) pair[which === 'a' ? 1 : 0] = got.usable.find(n => n !== s.value); ui.pick.set(t.task, pair); ui.editing = null; again(); }); + l.appendChild(s); return l; + }; + box.appendChild(sect('Compare', count(got.usable.length, 'set'))); + const picks = h('div', 'rv-picks'); picks.appendChild(pick('A', 'a', got.a)); picks.appendChild(pick('B', 'b', got.b)); box.appendChild(picks); + const seg = h('div', 'seg rv-mode'); seg.setAttribute('role', 'group'); seg.setAttribute('aria-label', 'How the two sets are drawn'); + for (const [id, label] of [['side', 'Side by side'], ['over', 'Overlaid']]) { const b = button(null, label, 'rv:mode-' + id, () => { if (ui.mode !== id) { ui.mode = id; again(); } }); b.setAttribute('aria-pressed', String(ui.mode === id)); seg.appendChild(b); } + box.appendChild(seg); + const fl = h('label', 'rv-min'); fl.appendChild(document.createTextNode('Confidence at least')); + const fi = h('input'); fi.type = 'number'; fi.min = '0'; fi.max = '1'; fi.step = '0.05'; fi.placeholder = 'any'; fi.dataset.key = 'rv:min'; fi.className = 'ann-num'; + const min = ui.min.get(t.task); fi.value = min == null ? '' : String(min); + fi.addEventListener('change', () => { const v = fi.value === '' ? null : Number(fi.value); if (v != null && !(v >= 0 && v <= 1)) { fi.value = min == null ? '' : String(min); return; } ui.min.set(t.task, v); again(); }); + fl.appendChild(fi); box.appendChild(fl); + if (!got.agreement) { box.appendChild(h('p', 'empty', 'Two sets are needed to compare; build an annotator of this task.')); return box; } + const ag = got.agreement, pair = ag.pairs[0] || {}; + const card = h('div', 'rv-agree'); card.setAttribute('data-key', 'rv:agreement'); + card.appendChild(h('span', 'kicker', 'Agreement of A and B')); + card.appendChild(h('b', 'rv-score mono', fixed(pair.agreement))); + card.appendChild(h('p', 'small muted', 'over ' + count(pair.records || 0, 'record') + '. ' + ag.measure)); + const figures = []; + if (pair.kappa !== undefined) figures.push(['Cohen\'s κ', fixed(pair.kappa)]); + if (got.fleiss != null) figures.push(['Fleiss\' κ, all sets', fixed(got.fleiss)]); + if (pair.mean_iou !== undefined) figures.push(['Mean IoU of matches', fixed(pair.mean_iou)]); + if (pair.mean_oks !== undefined) figures.push(['Mean OKS of matches', fixed(pair.mean_oks)]); + if (pair.f1 !== undefined) figures.push([pair.mean_oks !== undefined ? 'F1 at OKS 0.5' : 'F1 at IoU 0.5', fixed(pair.f1)]); + if (pair.matches !== undefined) figures.push(['Matches', String(pair.matches)]); + if (pair.tau !== undefined) figures.push(['Mean Kendall τ', fixed(pair.tau)]); + if (pair.exact !== undefined) figures.push(['Exactly equal', String(pair.exact)]); + if (pair.mean_abs !== undefined) figures.push(['Mean |A − B|' + (t.units ? ' (' + t.units + ')' : ''), fixed(pair.mean_abs, 3)]); + if (pair.delta !== undefined) figures.push(['Within δ 1.25', fixed(pair.delta)]); + if (pair.switches !== undefined) figures.push(['Identity switches', String(pair.switches)], ['Fragments A · B', pair.fragments.join(' · ')]); + if (figures.length) { const dl = h('dl', 'setup rv-figures'); for (const [k, v] of figures) { dl.appendChild(h('dt', null, k)); dl.appendChild(h('dd', 'mono', v)); } card.appendChild(dl); } + if (ag.truncated) card.appendChild(h('p', 'small warn', 'A set holds more records than are compared here; the first 20,000 of each are.')); + box.appendChild(card); + box.appendChild(sect('Most disputed', ag.total ? count(ag.total, 'record') : '0')); + if (!ag.disputed.length) { box.appendChild(h('p', 'empty', 'Neither set annotates a record.')); return box; } + const ol = h('ol', 'rv-disputed'); ol.setAttribute('aria-label', 'The records A and B disagree on most, most first'); + for (const row of ag.disputed) { + const li = h('li'), b = button('rv-rec', null, 'rv-rec-' + row.record, () => { if (ui.sel.get(t.task) !== row.record) { ui.sel.set(t.task, row.record); ui.editing = null; ui.removing = false; again(); } }); + b.dataset.id = row.record; b.setAttribute('aria-pressed', 'false'); + b.appendChild(h('bdi', 'mono rv-id', row.record)); + const bar = h('i', 'rv-bar'), fill = h('b'); fill.style.width = Math.round(100 * row.disagreement) + '%'; bar.appendChild(fill); b.appendChild(bar); + b.appendChild(h('span', 'mono small rv-dis', fixed(row.disagreement))); + if (row.missing.length) b.appendChild(h('span', 'small faint', 'only in ' + ['A', 'B'].filter((x, i) => !row.missing.includes([got.a, got.b][i])).join(' '))); + b.setAttribute('aria-label', row.record + ', disagreement ' + fixed(row.disagreement) + (row.missing.length ? ', missing in ' + row.missing.map(shortSet).join(' and ') : '')); + li.appendChild(b); ol.appendChild(li); + } + box.appendChild(ol); + if (ag.total > ag.disputed.length) box.appendChild(h('p', 'small faint', 'The ' + ag.disputed.length + ' most disputed of ' + ag.total.toLocaleString('en-GB') + ' are listed.')); + return box; + } + + // ---- Colours ------------------------------------------------------------------------------------------------------ + const colourOf = which => V.token(which === 'a' ? '--ramp-neg' : which === 'b' ? '--ramp-pos' : '--good'); + const PALETTE = ['--ramp-neg', '--ramp-pos', '--good', '--warn', '--serious', '--accent']; + const termColour = (t, term) => { const i = Math.max(0, (t.vocabulary || []).indexOf(term)); return V.token(PALETTE[i % PALETTE.length]); }; + + // ---- Middle: the record with the sets drawn over it ----------------------------------------------------------- + function buildMiddle(t, got) { + const el = h('div', 'iv rv-iv'); + if (!got.id) { el.appendChild(h('p', 'empty', 'Choose a record.')); return el; } + const cmp = got.compare, byName = Object.fromEntries(cmp.sets.map(s => [s.set, s])); + el.appendChild(h('header', 'iv-head')).appendChild(h('h3', 'mono', got.id)); + if (!cmp.in_product) { el.appendChild(h('p', 'empty', 'This record is not in the current product of ' + t.dataset + '.')); return el; } + if (got.record && got.record.error) { el.appendChild(A.refusal(got.record.error)); return el; } + const legend = h('p', 'small rv-legend'); + const swatch = (which, text) => { const s = h('span', 'rv-sw'); s.style.background = rgb(colourOf(which)); legend.appendChild(s); legend.appendChild(document.createTextNode(text + ' ')); }; + if (ui.mode === 'over' && !ui.editing) { swatch('a', 'A ' + shortSet(got.a)); swatch('b', 'B ' + shortSet(got.b)); swatch('both', 'both'); legend.appendChild(h('span', 'faint', ' · dashed: only in one')); el.appendChild(legend); } + for (const s of cmp.sets) if (s.problem) el.appendChild(h('p', 'small warn', shortSet(s.set) + ': ' + s.problem)); + if (cmp.problem) el.appendChild(h('p', 'small warn', cmp.problem)); + const panels = ui.editing ? [['kept', [ui.editing.set]]] : ui.mode === 'over' ? [['over', [got.a, got.b]]] : [['a', [got.a]], ['b', [got.b]]]; + const grid = h('div', 'rv-panels' + (panels.length > 1 ? ' two' : '')); el.appendChild(grid); + const r = got.record ? got.record.record : null, k = got.record ? got.record.content || {} : {}; + for (const [which, names] of panels) { + const panel = h('figure', 'rv-panel'); grid.appendChild(panel); + const values = ui.editing ? [{ set: KEPT, value: ui.editing.value, drawn: null }] : names.map(n => byName[n]); + const cap = h('figcaption', 'small'); cap.textContent = ui.editing ? 'Correcting the kept annotation' : which === 'over' ? 'A and B' : which.toUpperCase() + ' · ' + shortSet(names[0]); panel.appendChild(cap); + const roles = ui.editing ? ['kept'] : which === 'over' ? ['a', 'b'] : [which]; + if (r && r.kind === 'image') imagePanel(panel, t, r, k, values, roles, cmp); + else if (r && r.kind === 'pointcloud') cloudPanel(panel, t, got.id, k, values, roles, which); + else if (cmp.frames) framesPanel(panel, t, cmp.frames, values, roles); + else if (cmp.series || (r && r.kind === 'audio')) bandsPanel(panel, t, cmp.series, k, values, roles); + else textPanel(panel, t, values, roles, r, k); + } + if (cmp.frames) el.appendChild(frameSlider(cmp.frames)); + return el; + } + + /** Matching for marking: an object of one side with no object of the same term at IoU 0.5 or more on the other. */ + function unmatched(objs, others) { + const iou = (a, b) => { const ix = Math.max(0, Math.min(a[0] + a[2], b[0] + b[2]) - Math.max(a[0], b[0])), iy = Math.max(0, Math.min(a[1] + a[3], b[1] + b[3]) - Math.max(a[1], b[1])), i = ix * iy, u = a[2] * a[3] + b[2] * b[3] - i; return u > 0 ? i / u : 0; }; + return objs.map(o => !others.some(p => p.term === o.term && iou(o.box, p.box) >= 0.5)); + } + const bboxOf = pts => { const xs = pts.filter(Boolean).map(p => p[0]), ys = pts.filter(Boolean).map(p => p[1]); if (!xs.length) return [0, 0, 0, 0]; const x0 = Math.min(...xs), y0 = Math.min(...ys); return [x0, y0, Math.max(...xs) - x0 || 1, Math.max(...ys) - y0 || 1]; }; + function objectsOf(t, value) { + if (!Array.isArray(value)) return []; + if (t.type === 'boxes') return value.map(o => ({ term: o.term, box: [o.x, o.y, o.w, o.h], o })); + if (t.type === 'polygons') return value.map(o => ({ term: o.term, box: bboxOf(o.points), o })); + if (t.type === 'keypoints') return value.map(o => ({ term: o.term, box: bboxOf(o.points), o })); + return []; + } + + function imagePanel(panel, t, r, k, values, roles, cmp) { + const cv = h('canvas', 'rv-canvas'); cv.tabIndex = 0; cv.dataset.key = 'rv:canvas-' + roles.join(''); cv.setAttribute('role', 'img'); + cv.setAttribute('aria-label', 'Image ' + r.id + ' with ' + roles.map(x => x === 'kept' ? 'the kept annotation' : 'set ' + x.toUpperCase()).join(' and ') + ' drawn over it'); + panel.appendChild(cv); + const img = new Image(); img.src = r.url; + const nw = k.width || (cmp.size || [])[0] || 1, nh = k.height || (cmp.size || [])[1] || 1; + const layers = values.map((s, i) => ({ s, role: roles[i], mask: s && s.drawn && s.drawn.runs ? maskPixels(s.drawn) : null })); + const objs = layers.map(l => objectsOf(t, l.s && l.s.value)); + const lone = layers.length === 2 ? [unmatched(objs[0], objs[1]), unmatched(objs[1], objs[0])] : [objs[0].map(() => false)]; + const edit = ui.editing && t.type === 'polygons' ? ui.editing : null; + // What is drawn, per set, as data-drawn (objects, or pixels of a mask or a depth map): read by the browser check. + cv.dataset.drawn = layers.map((l, i) => roles[i] + ':' + (l.mask ? l.mask.px.reduce((n, v) => n + (v ? 1 : 0), 0) : l.s && l.s.drawn && l.s.drawn.values_u8 ? atob(l.s.drawn.values_u8).split('').filter(c => c !== '\0').length : objs[i].length)).join(' '); + const paint = () => { + const size = V.fit(cv, Math.max(120, Math.round(cv.clientWidth * nh / nw))); if (!size) return; + const [W, H] = size, ctx = cv.getContext('2d'), sx = W / nw, sy = H / nh; + ctx.clearRect(0, 0, W, H); ctx.imageSmoothingEnabled = false; + if (img.complete && img.naturalWidth) ctx.drawImage(img, 0, 0, W, H); + if (t.type === 'mask') paintMasks(ctx, t, layers, W, H); + if (t.type === 'depth') paintDepth(ctx, layers, W, H); + const dpr = window.devicePixelRatio || 1; + layers.forEach((l, li) => { + if (!l.s || !Array.isArray(l.s.value)) return; + const col = roles.length > 1 ? colourOf(l.role) : null; + objs[li].forEach((ob, oi) => { + const c = col || termColour(t, ob.term), dashed = lone[li][oi] && roles.length > 1; + ctx.strokeStyle = rgb(c); ctx.fillStyle = rgb(c, 0.16); ctx.lineWidth = (dashed ? 2.5 : 1.6) * dpr; ctx.setLineDash(dashed ? [5 * dpr, 3 * dpr] : []); + const o = ob.o; + if (t.type === 'boxes') { ctx.strokeRect(o.x * sx, o.y * sy, o.w * sx, o.h * sy); } + else if (t.type === 'polygons') { ctx.beginPath(); o.points.forEach((p, i) => i ? ctx.lineTo(p[0] * sx, p[1] * sy) : ctx.moveTo(p[0] * sx, p[1] * sy)); ctx.closePath(); ctx.fill(); ctx.stroke(); } + else if (t.type === 'keypoints') { + const names = t.keypoints || [], at = n => o.points[names.indexOf(n)]; + ctx.setLineDash([]); for (const [m, n] of t.skeleton || []) { const p = at(m), q = at(n); if (p && q) { ctx.beginPath(); ctx.moveTo(p[0] * sx, p[1] * sy); ctx.lineTo(q[0] * sx, q[1] * sy); ctx.stroke(); } } + for (const p of o.points) if (p && (p.length < 3 || p[2] > 0)) { ctx.beginPath(); ctx.arc(p[0] * sx, p[1] * sy, 3 * dpr, 0, 7); ctx.fillStyle = rgb(c); ctx.fill(); } + } + ctx.setLineDash([]); ctx.fillStyle = rgb(c); ctx.font = (11 * dpr) + 'px ' + getComputedStyle(document.body).fontFamily; + ctx.fillText(ob.term + (o.confidence != null ? ' ' + o.confidence.toFixed(2) : ''), ob.box[0] * sx + 2 * dpr, Math.max(11 * dpr, ob.box[1] * sy - 3 * dpr)); + }); + }); + if (edit) for (const [pi, p] of edit.value.entries()) p.points.forEach((q, qi) => { const on = edit.vertex && edit.vertex[0] === pi && edit.vertex[1] === qi; ctx.fillStyle = rgb(on ? V.token('--serious') : V.token('--accent')); ctx.fillRect(q[0] * sx - 4 * dpr, q[1] * sy - 4 * dpr, 8 * dpr, 8 * dpr); }); + }; + img.addEventListener('load', paint, { once: true }); + V.paints(cv, paint); keepPaint(paint); + if (t.type === 'depth') { const d = values.map(s => s && s.drawn).filter(Boolean)[0]; if (d) panel.appendChild(h('p', 'small faint', roles.length > 1 ? 'Overlaid: the difference A − B, blue where A is nearer.' : 'Depth ' + fixed(d.low, 2) + ' to ' + fixed(d.high, 2) + (t.units ? ' ' + t.units : '') + ', light to dark.')); } + if (edit) correctPolygons(cv, edit, nw, nh, paint); + } + + /** A drawn mask's runs decoded to its pixel values. */ + function maskPixels(d) { const out = new Uint16Array(d.width * d.height); let at = 0; for (const [v, n] of d.runs) { out.fill(v, at, at + n); at += n; } return { d, px: out }; } + function paintMasks(ctx, t, layers, W, H) { + const ms = layers.map(l => l.mask); if (!ms.some(Boolean)) return; + const d = ms.find(Boolean).d, off = document.createElement('canvas'); off.width = d.width; off.height = d.height; + const o = off.getContext('2d'), img = o.createImageData(d.width, d.height), both = colourOf('both'); + const instance = t.mask === 'instance'; + for (let i = 0; i < d.width * d.height; i++) { + let c = null; + if (ms.length === 2) { const a = ms[0] ? ms[0].px[i] : 0, b = ms[1] ? ms[1].px[i] : 0; c = a && b ? both : a ? colourOf('a') : b ? colourOf('b') : null; } + else if (ms[0] && ms[0].px[i]) { const v = ms[0].px[i]; c = instance ? V.token(PALETTE[v % PALETTE.length]) : termColour(t, (ms[0].d.classes || {})[String(v)]); } + if (c) { img.data[i * 4] = c[0]; img.data[i * 4 + 1] = c[1]; img.data[i * 4 + 2] = c[2]; img.data[i * 4 + 3] = 170; } + } + o.putImageData(img, 0, 0); ctx.imageSmoothingEnabled = false; ctx.drawImage(off, 0, 0, W, H); + } + function paintDepth(ctx, layers, W, H) { + const ds = layers.map(l => l.s && l.s.drawn).filter(Boolean); if (!ds.length) return; + const raw = d => { const s = atob(d.values_u8), out = new Float32Array(s.length); for (let i = 0; i < s.length; i++) { const u = s.charCodeAt(i); out[i] = u ? d.low + (u - 1) / 254 * (d.high - d.low) : NaN; } return out; }; + let values = raw(ds[0]), colour = D.ramp(ds[0].low, ds[0].high); + if (ds.length === 2 && ds[1].width === ds[0].width) { const b = raw(ds[1]); values = values.map((v, i) => v - b[i]); const m = Math.max(1e-9, ...Array.from(values).filter(Number.isFinite).map(Math.abs)); colour = D.ramp(-m, m); } + ctx.globalAlpha = 0.85; D.heat(ctx, values, ds[0].height, ds[0].width, colour, 0, 0, W, H); ctx.globalAlpha = 1; + } + + /** The light correction of polygons: a vertex dragged, or chosen and deleted (a polygon keeps three). */ + function correctPolygons(cv, edit, nw, nh, paint) { + cv.setAttribute('aria-label', cv.getAttribute('aria-label') + '. Drag a vertex to move it; click one to choose it and Delete removes it.'); + const at = e => { const q = cv.getBoundingClientRect(); return [(e.clientX - q.left) / q.width * nw, (e.clientY - q.top) / q.height * nh]; }; + const near = p => { let best = null, dist = 8 * nw / cv.getBoundingClientRect().width; edit.value.forEach((poly, pi) => poly.points.forEach((q, qi) => { const d = Math.hypot(q[0] - p[0], q[1] - p[1]); if (d <= dist) { dist = d; best = [pi, qi]; } })); return best; }; + let dragging = null; + cv.addEventListener('pointerdown', e => { const v = near(at(e)); edit.vertex = v; if (v) { dragging = e.pointerId; cv.setPointerCapture(e.pointerId); } paint(); }); + cv.addEventListener('pointermove', e => { if (dragging !== e.pointerId || !edit.vertex) return; const [x, y] = at(e), q = edit.value[edit.vertex[0]].points[edit.vertex[1]]; q[0] = Math.round(Math.min(nw, Math.max(0, x)) * 10) / 10; q[1] = Math.round(Math.min(nh, Math.max(0, y)) * 10) / 10; edit.dirty = true; paint(); }); + cv.addEventListener('pointerup', e => { if (dragging === e.pointerId) { dragging = null; again(); } }); + cv.addEventListener('keydown', e => { + if ((e.key === 'Delete' || e.key === 'Backspace') && edit.vertex) { const poly = edit.value[edit.vertex[0]]; if (poly.points.length > 3) { poly.points.splice(edit.vertex[1], 1); edit.vertex = null; edit.dirty = true; paint(); again(); } e.preventDefault(); } + }); + } + + function cloudPanel(panel, t, id, k, values, roles, which) { + if (!k.points_f32) { panel.appendChild(h('p', 'note', 'The point cloud could not be read.')); return; } + const pts = D.floats(k.points_f32), n = pts.length / 3, stride = k.stride || 1, colours = new Uint8Array(n * 3), base = V.token('--ink-2'); + for (let i = 0; i < n; i++) colours.set(base, i * 3); + const objects = values.map(s => !s ? [] : s.drawn && s.drawn.points ? s.drawn.points : Array.isArray(s.value) && t.type === 'points' ? s.value : []); + const member = objects.map(list => { const m = new Map(); list.forEach(o => { for (const idx of o.indices) if (idx % stride === 0) m.set(idx / stride, o.term); }); return m; }); + for (let i = 0; i < n; i++) { + const inA = member[0] && member[0].has(i), inB = member[1] && member[1].has(i); + if (roles.length === 2) { if (inA || inB) colours.set(inA && inB ? colourOf('both') : inA ? colourOf('a') : colourOf('b'), i * 3); } + else if (inA) colours.set(termColour(t, member[0].get(i)), i * 3); + } + const lines = []; + values.forEach((s, li) => { + if (!s || t.type !== 'box3d' || !Array.isArray(s.value)) return; + const col = roles.length > 1 ? colourOf(roles[li]) : null; + for (const b of s.value) { + const [cx, cy, cz] = b.center, [l, w, hh] = b.size, c = Math.cos(b.yaw), sn = Math.sin(b.yaw); + const corner = (dx, dy, dz) => [cx + c * dx - sn * dy, cy + sn * dx + c * dy, cz + dz]; + const pts8 = []; for (const dz of [-hh / 2, hh / 2]) for (const [dx, dy] of [[l / 2, w / 2], [-l / 2, w / 2], [-l / 2, -w / 2], [l / 2, -w / 2]]) pts8.push(corner(dx, dy, dz)); + const edges = [[0, 1], [1, 2], [2, 3], [3, 0], [4, 5], [5, 6], [6, 7], [7, 4], [0, 4], [1, 5], [2, 6], [3, 7]]; + for (const [p, q] of edges) lines.push(pts8[p].concat(pts8[q], [col || termColour(t, b.term)])); + } + }); + const st = store.get(id + '\n' + which) || V.turned(); store.set(id + '\n' + which, st); + panel.dataset.drawn = roles.map((role, i) => role + ':' + member[i].size + '/' + values.filter((s, j) => j === i && s && Array.isArray(s.value) && t.type === 'box3d').reduce((n, s) => n + s.value.length, 0)).join(' '); + const editing = ui.editing && t.type === 'points' ? ui.editing : null; + st.selecting = !!(editing && ui.removing); + const m = { points: pts, colours, bounds: k.bounds, lines }; + if (editing) m.select = shown => { const gone = new Set(shown.map(i => i * stride)); let removed = 0; for (const o of editing.value) { const before = o.indices.length; o.indices = o.indices.filter(x => !gone.has(x)); removed += before - o.indices.length; } editing.value = editing.value.filter(o => o.indices.length); if (removed) { editing.dirty = true; editing.version = (editing.version || 0) + 1; editing.removed = (editing.removed || 0) + removed; again(); } }; + V.space(panel, m, st, 'Point cloud ' + id + ' with ' + roles.map(x => x === 'kept' ? 'the kept point objects' : 'set ' + x.toUpperCase()).join(' and ') + (st.selecting ? '. Drag a rectangle to remove the points in it from the kept objects.' : '')); + const said = t.type === 'box3d' ? values.map((s, i) => (roles[i] === 'kept' ? 'Kept' : roles[i].toUpperCase()) + ': ' + count(Array.isArray(s && s.value) ? s.value.length : 0, 'box', 'boxes')).join(' · ') + : objects.map((list, i) => (roles[i] === 'kept' ? 'Kept' : roles[i].toUpperCase()) + ': ' + (list.length ? list.map(o => o.term + ' ' + count(o.indices.length, 'point')).join(', ') : 'no object')).join(' · '); + panel.appendChild(h('p', 'small faint', said)); + } + + function framesPanel(panel, t, frames, values, roles) { + const cv = h('canvas', 'rv-canvas'); cv.tabIndex = 0; cv.dataset.key = 'rv:frames-' + roles.join(''); cv.setAttribute('role', 'img'); + cv.setAttribute('aria-label', 'Frames of the array with the tracks of ' + roles.map(x => 'set ' + x.toUpperCase()).join(' and ') + '; the left and right arrows change the frame'); + panel.appendChild(cv); + const paint = () => { + const f = frames.frames[Math.min(ui.frame, frames.frames.length - 1)]; if (!f) return; + const size = V.fit(cv, Math.max(120, Math.round(cv.clientWidth * frames.height / frames.width))); if (!size) return; + const [W, H] = size, ctx = cv.getContext('2d'), raw = atob(f.u8), off = document.createElement('canvas'); off.width = frames.width; off.height = frames.height; + const o = off.getContext('2d'), img = o.createImageData(frames.width, frames.height); + for (let i = 0; i < raw.length; i++) { const v = raw.charCodeAt(i); img.data[i * 4] = img.data[i * 4 + 1] = img.data[i * 4 + 2] = v; img.data[i * 4 + 3] = 255; } + o.putImageData(img, 0, 0); ctx.imageSmoothingEnabled = false; ctx.drawImage(off, 0, 0, W, H); + const sx = W / (frames.width * frames.scale), sy = H / (frames.height * frames.scale), dpr = window.devicePixelRatio || 1; + const drawn = values.map(() => 0); + values.forEach((s, li) => { + if (!s || !Array.isArray(s.value)) return; + for (const tr of s.value) { const b = tr.frames.find(x => x.frame === f.frame); if (!b) continue; drawn[li]++; const c = roles.length > 1 ? colourOf(roles[li]) : termColour(t, tr.term); ctx.strokeStyle = rgb(c); ctx.lineWidth = 1.8 * dpr; ctx.strokeRect(b.x * sx, b.y * sy, b.w * sx, b.h * sy); ctx.fillStyle = rgb(c); ctx.font = (11 * dpr) + 'px ' + getComputedStyle(document.body).fontFamily; ctx.fillText(tr.track, b.x * sx + 2 * dpr, Math.max(11 * dpr, b.y * sy - 3 * dpr)); } + }); + const said = 'frame ' + f.frame + ' ' + roles.map((role, i) => role + ':' + drawn[i] + (values[i] && Array.isArray(values[i].value) ? '=' + values[i].value.filter(tr => tr.frames.some(x => x.frame === f.frame)).map(tr => tr.track).join(',') : '')).join(' '); + if (cv.dataset.drawn !== said) cv.dataset.drawn = said; + }; + cv.addEventListener('keydown', e => { if (e.key === 'ArrowLeft' || e.key === 'ArrowRight') { e.preventDefault(); setFrame(ui.frame + (e.key === 'ArrowRight' ? 1 : -1), frames); } }); + V.paints(cv, paint); keepPaint(paint); + } + function frameSlider(frames) { + const box = h('label', 'rv-frame'); const n = frames.frames.length; + ui.frame = Math.min(ui.frame, n - 1); + const out = h('span', 'mono small'), say = () => { out.textContent = 'frame ' + frames.frames[ui.frame].frame + ' of ' + frames.count; }; + const r = h('input'); r.type = 'range'; r.min = '0'; r.max = String(n - 1); r.value = String(ui.frame); r.dataset.key = 'rv:frame'; r.setAttribute('aria-label', 'Frame'); + r.addEventListener('input', () => setFrame(Number(r.value), frames)); + box.appendChild(document.createTextNode('Frame')); box.appendChild(r); box.appendChild(out); say(); box._say = say; + return box; + } + /** A new frame: the canvases repainted and the slider set, in place. */ + function setFrame(i, frames) { + ui.frame = Math.max(0, Math.min(frames.frames.length - 1, i)); + const slider = here.parts.middle.querySelector('.rv-frame'); if (slider) { slider.querySelector('input').value = String(ui.frame); slider._say(); } + for (const p of here.repaint) p(); + } + + /** Timeseries or segments: bands of each set under a series (an array) or a waveform (a sound). */ + function bandsPanel(panel, t, series, k, values, roles) { + const cv = h('canvas', 'rv-canvas rv-bands'); cv.setAttribute('role', 'img'); cv.dataset.key = 'rv:bands-' + roles.join(''); + const length = series ? series.positions : k.seconds || 1; + cv.setAttribute('aria-label', (series ? 'The series' : 'The waveform') + ' with the stretches of ' + roles.map(x => 'set ' + x.toUpperCase()).join(' and ')); + panel.appendChild(cv); + const rows = values.length, terms = t.vocabulary || []; + cv.dataset.drawn = roles.map((role, i) => role + ':' + (values[i] && Array.isArray(values[i].value) ? values[i].value.length : 0)).join(' '); + const paint = () => { + const size = V.fit(cv, 96 + rows * 22); if (!size) return; + const [W, H] = size, ctx = cv.getContext('2d'), dpr = window.devicePixelRatio || 1, top = 96 * dpr; + ctx.clearRect(0, 0, W, H); + if (series) { + const all = series.channels.flat().filter(Number.isFinite), lo = Math.min(...all), hi = Math.max(...all), span = hi - lo || 1; + series.channels.forEach((line, ci) => { ctx.strokeStyle = rgb(V.token(PALETTE[(ci + 2) % PALETTE.length])); ctx.lineWidth = dpr; ctx.beginPath(); line.forEach((v, i) => { const x = i / Math.max(1, line.length - 1) * W, y = top - 4 * dpr - (v - lo) / span * (top - 8 * dpr); i ? ctx.lineTo(x, y) : ctx.moveTo(x, y); }); ctx.stroke(); }); + } else if (k.peaks) V.wave(ctx, W, top, k.peaks); + values.forEach((s, li) => { + const y = top + li * 22 * dpr + 3 * dpr, c0 = roles.length > 1 ? colourOf(roles[li]) : null; + ctx.fillStyle = rgb(V.token('--line-strong'), 0.25); ctx.fillRect(0, y, W, 16 * dpr); + for (const it of (s && Array.isArray(s.value) ? s.value : [])) { const c = c0 || termColour(t, it.term); ctx.fillStyle = rgb(c, 0.75); const x0 = it.start / length * W, x1 = it.end / length * W; ctx.fillRect(x0, y, Math.max(1, x1 - x0), 16 * dpr); ctx.fillStyle = rgb(V.token('--ink') || c); ctx.font = (10 * dpr) + 'px ' + getComputedStyle(document.body).fontFamily; ctx.fillText(it.term, x0 + 2 * dpr, y + 12 * dpr); } + ctx.fillStyle = rgb(c0 || V.token('--line-strong')); ctx.fillText(roles[li].toUpperCase(), W - 14 * dpr, y + 12 * dpr); + }); + void terms; + }; + V.paints(cv, paint); keepPaint(paint); + panel.appendChild(h('p', 'small faint', series ? count(series.positions, 'position') + (series.step > 1 ? ', every ' + series.step + 'th drawn' : '') : (k.seconds ? k.seconds.toFixed(2) + ' s' : 'The sound\'s length is read from WAV only.'))); + } + + /** What has no drawing surface here: each set's value in words (ranking, class, tags, text, spans). */ + function textPanel(panel, t, values, roles) { + const dl = h('dl', 'setup rv-values'); + values.forEach((s, i) => { dl.appendChild(h('dt', null, roles[i].toUpperCase())); dl.appendChild(h('dd', 'mono pre', s && s.value != null ? (Array.isArray(s.value) && t.type === 'ranking' ? s.value.map((x, j) => (j + 1) + '. ' + x).join('\n') : JSON.stringify(s.value, null, 1)) : 'not annotated')); }); + panel.appendChild(dl); + } + + // ---- Right: the values in words, this record's agreement, the decision ------------------------------------- + function summary(t, value) { + if (value == null) return 'not annotated'; + if (t.type === 'mask') return 'a mask of ' + count(Object.keys(value.classes || {}).length, 'class', 'classes') + (value.file ? ' (PNG)' : ' (runs)'); + if (t.type === 'depth') return 'a depth map'; + if (t.type === 'ranking') return value.join(' › '); + if (typeof value === 'string') return value.length > 80 ? value.slice(0, 80) + '…' : value; + if (!Array.isArray(value)) return value.file ? 'point ids in a file' : JSON.stringify(value).slice(0, 80); + if (t.type === 'tags') return value.join(', ') || 'no tag'; + if (t.type === 'points') return value.map(o => o.term + ' (' + count(o.indices.length, 'point') + ')').join(', ') || 'no object'; + const terms = {}; for (const o of value) terms[o.term] = (terms[o.term] || 0) + 1; + const conf = value.map(o => o.confidence).filter(x => x != null); + return (count(value.length, t.type === 'track' ? 'track' : 'object') + (value.length ? ': ' + Object.entries(terms).map(([k, n]) => n + ' ' + k).join(', ') : '')) + (conf.length ? ' · confidence ' + Math.min(...conf).toFixed(2) + '–' + Math.max(...conf).toFixed(2) : ''); + } + function buildRight(t, got, may) { + const box = h('div', 'inspector rv-decide'); + if (!got.id || !got.compare) { box.appendChild(h('p', 'empty', 'Choose a record from the list.')); return box; } + const cmp = got.compare, byName = Object.fromEntries(cmp.sets.map(s => [s.set, s])), line = got.kept ? got.kept.annotation : null; + const hd = h('header'); hd.appendChild(h('span', 'kicker', t.title + ' · ' + t.type)); const t2 = h('h2', 'mono', got.id); t2.tabIndex = -1; hd.appendChild(t2); box.appendChild(hd); + const dl = h('dl', 'setup'); + for (const [label, name] of [['A', got.a], ['B', got.b]]) { const s = byName[name]; dl.appendChild(h('dt', null, label + ' · ' + shortSet(name))); dl.appendChild(h('dd', null, summary(t, s && s.value) + (s && s.confidence != null ? ' · line confidence ' + s.confidence.toFixed(2) : ''))); } + const ab = cmp.pairs.find(p => (p.a === got.a && p.b === got.b) || (p.a === got.b && p.b === got.a)); + dl.appendChild(h('dt', null, 'Agreement here')); dl.appendChild(h('dd', 'mono', ab ? (ab.problem || fixed(ab.agreement)) : '—')); + box.appendChild(dl); + // What is kept now. + const kept = h('p', 'small rv-kept'); + if (line) kept.textContent = 'Kept: ' + line.state + (line.from && line.from.set ? ' · from ' + shortSet(line.from.set) : line.from && line.from.both ? ' · from both' : line.from && line.from.rejected ? ' · both rejected' : '') + (got.kept.unsaved ? ' · unsaved' : '') + ' · ' + summary(t, line.value); + else kept.textContent = 'Nothing is kept for this record yet.'; + box.appendChild(kept); + if (ui.editing) { box.appendChild(correctionBox(t, got)); return box; } + // The decision. + const note = h('textarea'); note.rows = 2; note.maxLength = 4000; note.placeholder = 'a note (optional)'; note.dataset.key = 'rv:note'; note.disabled = !may; + const nk = t.task + '\n' + got.id; note.value = ui.notes.get(nk) || ''; note.addEventListener('input', () => ui.notes.set(nk, note.value)); + const nl = h('div', 'form rv-note'), lab = h('label'); lab.appendChild(document.createTextNode('Note')); lab.appendChild(note); nl.appendChild(lab); + const va = byName[got.a] && byName[got.a].value, vb = byName[got.b] && byName[got.b].value; + const args = (keep, sets) => () => { const a = { task: t.task, record: got.id, keep, sets }; const n = (ui.notes.get(nk) || '').trim(); if (n) a.note = n; return a; }; + const done = () => { ui.notes.delete(nk); }; + box.appendChild(A.group('review:decide', [ + { id: 'keep-a', label: 'Keep A', cls: 'btn primary', who: 'edit', op: 'keep_annotation', busy: 'Keeping…', hidden: got.a === KEPT || va == null, args: args('one', [got.a]), done }, + { id: 'keep-b', label: 'Keep B', cls: 'btn primary', who: 'edit', op: 'keep_annotation', busy: 'Keeping…', hidden: got.b === KEPT || vb == null, args: args('one', [got.b]), done }, + { id: 'keep-both', label: 'Keep both', cls: 'btn', who: 'edit', op: 'keep_annotation', busy: 'Keeping…', hidden: got.a === KEPT || got.b === KEPT || !isList(t, va) || !isList(t, vb), args: args('both', [got.a, got.b]), done }, + { id: 'reject', label: 'Reject both', cls: 'btn', who: 'edit', op: 'keep_annotation', busy: 'Rejecting…', args: args('none', [got.a, got.b]), done } + ])); + box.appendChild(nl); + const correctable = line && line.state !== 'rejected' && Array.isArray(line.value) && ((t.type === 'polygons' && line.value.length) || (t.type === 'points' && line.value.length)); + if (may && correctable) box.appendChild(A.group('review:correct', [{ id: 'correct', label: t.type === 'polygons' ? 'Correct the kept polygons' : 'Correct the kept point objects', cls: 'btn ghost', onClick: () => { ui.editing = { key: nk, set: KEPT, value: copy(line.value), from: line.from || null, state: line.state, note: line.note || null, dirty: false }; ui.removing = t.type === 'points'; again(); } }])); + box.appendChild(h('p', 'note', may ? 'A decision is kept in Tuldok as an unsaved edit of ' + t.task + '.jsonl, naming the set it came from; Save writes it.' : 'This session may look but not decide: that needs the right to edit.')); + return box; + } + function correctionBox(t, got) { + const e = ui.editing, box = h('div', 'rv-correct'); + box.appendChild(h('p', 'small', t.type === 'polygons' ? 'Drag a vertex to move it. Click a vertex to choose it, then Delete removes it (a polygon keeps three).' : 'Drag a rectangle on the cloud to remove the points in it from the kept objects.' + (e.removed ? ' ' + count(e.removed, 'point') + ' removed so far.' : ''))); + const item = () => { const it = { record: got.id, state: 'accepted', value: e.value }; if (e.note) it.note = e.note; return it; }; + box.appendChild(A.group('review:correction', [ + { id: 'keep-correction', label: 'Keep the correction', cls: 'btn primary', who: 'edit', op: 'set_annotation', busy: 'Keeping…', hidden: !e.dirty, + args: () => Object.assign({ task: t.task, items: [item()] }, e.from ? { from: e.from } : {}), done: () => { ui.editing = null; ui.removing = false; } }, + { id: 'drop-correction', label: 'Drop the correction', cls: 'btn ghost', onClick: () => { ui.editing = null; ui.removing = false; again(); } } + ])); + return box; + } + + /** For annotate mode: a kept value of a new type drawn read-only over its record (no drawing tools). */ + function overlay(el, got, t, value) { + const panel = h('figure', 'rv-panel'), r = got.record, k = got.content || {}, s = { set: KEPT, value, drawn: null }; + const cmp = { size: k.width ? [k.width, k.height] : null }; + if (r.kind === 'image' && !['mask', 'depth'].includes(t.type)) imagePanel(panel, t, r, k, [s], ['kept'], cmp); + else if (r.kind === 'pointcloud' && ['points', 'box3d'].includes(t.type) && Array.isArray(value)) cloudPanel(panel, t, r.id, k, [s], ['kept'], 'annotate'); + else return false; + el.appendChild(panel); return true; + } + + return { draw, NEW, summary, overlay }; +})(); From e9f620a29210e1b02148a1c83f5451a0b1142f0a Mon Sep 17 00:00:00 2001 From: MrScripty <TheEnvironmentGuy@protonmail.com> Date: Thu, 19 Nov 2026 07:20:49 -0700 Subject: [PATCH 114/131] test(workspace): the tiny example's scenes and stand-in annotators, and the browser check of review examples/tiny-project gains make_scenes.py (about 4 KB of images, point clouds, frames and a series), a stand-in annotator, two tasks and four annotators. browser_project_workspace_annotation_kinds.cjs builds a task of eight types with two stand-ins each and checks the overlays, the agreement and disputed order, a decision kept and saved, both corrections, updates in place, light and dark at 1440 and 390. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --- examples/tiny-project/README.md | 23 +- .../tiny-project/code/annotators/standin.py | 168 ++++++++++ examples/tiny-project/code/make_scenes.py | 88 +++++ .../tiny-project/code/scenes/clouds/p.ply | 27 ++ .../tiny-project/code/scenes/clouds/q.ply | 37 ++ .../code/scenes/frames/moving.npy | Bin 0 -> 2048 bytes .../tiny-project/code/scenes/images/a.png | Bin 0 -> 119 bytes .../tiny-project/code/scenes/images/b.png | Bin 0 -> 96 bytes .../tiny-project/code/scenes/images/c.png | Bin 0 -> 120 bytes .../code/scenes/series/signal.npy | Bin 0 -> 512 bytes .../project/annotations/scene-masks.json | 12 + .../project/annotations/scene-objects.json | 11 + .../project/datasets/scene-masks-a.json | 28 ++ .../project/datasets/scene-masks-b.json | 28 ++ .../project/datasets/scene-objects-a.json | 28 ++ .../project/datasets/scene-objects-b.json | 28 ++ .../tiny-project/project/datasets/scenes.json | 14 + tests/browser_annotation_kinds_fixture.py | 81 +++++ ...ser_project_workspace_annotation_kinds.cjs | 316 ++++++++++++++++++ 19 files changed, 885 insertions(+), 4 deletions(-) create mode 100644 examples/tiny-project/code/annotators/standin.py create mode 100644 examples/tiny-project/code/make_scenes.py create mode 100644 examples/tiny-project/code/scenes/clouds/p.ply create mode 100644 examples/tiny-project/code/scenes/clouds/q.ply create mode 100644 examples/tiny-project/code/scenes/frames/moving.npy create mode 100644 examples/tiny-project/code/scenes/images/a.png create mode 100644 examples/tiny-project/code/scenes/images/b.png create mode 100644 examples/tiny-project/code/scenes/images/c.png create mode 100644 examples/tiny-project/code/scenes/series/signal.npy create mode 100644 examples/tiny-project/project/annotations/scene-masks.json create mode 100644 examples/tiny-project/project/annotations/scene-objects.json create mode 100644 examples/tiny-project/project/datasets/scene-masks-a.json create mode 100644 examples/tiny-project/project/datasets/scene-masks-b.json create mode 100644 examples/tiny-project/project/datasets/scene-objects-a.json create mode 100644 examples/tiny-project/project/datasets/scene-objects-b.json create mode 100644 examples/tiny-project/project/datasets/scenes.json create mode 100644 tests/browser_annotation_kinds_fixture.py create mode 100644 tests/browser_project_workspace_annotation_kinds.cjs diff --git a/examples/tiny-project/README.md b/examples/tiny-project/README.md index c55be4b9..0496be1f 100644 --- a/examples/tiny-project/README.md +++ b/examples/tiny-project/README.md @@ -29,6 +29,9 @@ phase are random, and predict the next 16 samples of the clean wave. | `datasets/samples` | the step `import`: the files under `code/samples` (two texts, a PNG, a WAV, a PLY point cloud and an OBJ mesh, written by `make_samples.py`), one record each | | `annotations/sample-quality` | a `class` task on `datasets/samples`: whether each sample is clean; its annotations are `annotations/sample-quality.jsonl` | | `datasets/samples-v1` | the step `freeze`: the samples whose quality is accepted, split three to one from seed 7 | +| `datasets/scenes` | the step `import`: the files under `code/scenes` (three images, two point clouds, an array of frames and a series, written by `make_scenes.py`) | +| `annotations/scene-masks`, `annotations/scene-objects` | a `mask` task (instance masks of the images' objects) and a `points` task (the top of each point cloud) on `datasets/scenes` | +| `datasets/scene-masks-a`, `-b`, `datasets/scene-objects-a`, `-b` | the step `annotate`: `code/annotators/standin.py`, a stand-in segmentor, run at two thresholds; each is an annotation set for its task | The benchmark has two subjects: `small-net-a`, the trained network, and `predict-zero`, which always predicts zero and shows the error any model has to @@ -76,10 +79,11 @@ P=examples/tiny-project/project .venv/bin/python -m tuldok_project build $P --all ``` -The plan has five build steps after the two environments: `datasets/waves`, -`recipes/small-net-a`, then `benchmarks/held-out` once for each subject, and -`datasets/samples` and `datasets/samples-v1`, which Tuldok's own steps build -in a moment with no environment. +The plan has ten build steps after the two environments: `datasets/waves`, +`recipes/small-net-a`, then `benchmarks/held-out` once for each subject, +`datasets/samples`, `datasets/samples-v1` and `datasets/scenes`, which +Tuldok's own steps build in a moment with no environment, and the four +annotators, which run `standin.py` in `environments/cpu` in a moment each. | Step | Time | | --- | --- | @@ -98,6 +102,17 @@ records whose annotation is accepted, as committed, and splits them; build it again after committing a change to the annotations. To write the samples again, run `python make_samples.py` from `code/`: the bytes are the same. +### Two segmentors, compared + +`datasets/scene-masks-a` and `-b` run the same stand-in segmentor at two +thresholds, so their masks differ by a rim of a pixel; `scene-objects-a` and +`-b` take slightly different tops of each cloud. On the Annotate tab, choose +`annotations/scene-masks` and Review: the two sets' agreement (matched IoU), +the records they disagree on most, each drawn over its image side by side or +overlaid, and Keep A, Keep B or Reject both, which Save writes to +`annotations/scene-masks.jsonl` and its mask to `annotations/scene-masks/`. To +write the scenes again, run `python make_scenes.py` from `code/`. + ### Watch the training While the recipe runs, in a second terminal: diff --git a/examples/tiny-project/code/annotators/standin.py b/examples/tiny-project/code/annotators/standin.py new file mode 100644 index 00000000..cc40a7d4 --- /dev/null +++ b/examples/tiny-project/code/annotators/standin.py @@ -0,0 +1,168 @@ +"""A stand-in annotator for the example: what a project's own segmentor would do, in a few lines of the standard library. + +Run by Tuldok's step annotate (docs/contracts/project-folder.md), it reads the records to annotate from +$TULDOK_TODO and the task from $TULDOK_TASK, and appends one line per record to $TULDOK_ANNOTATIONS, writing masks +and arrays under $TULDOK_FILES. Its one argument is a threshold, 0 to 255: two runs with different thresholds are +two "segmentors" that mostly agree, which is what the Annotate tab's Review compares. + + python annotators/standin.py 160 + +What it makes, by the task's type: on the scenes' images, pixels darker than the threshold are objects (one per +colour): a mask (an instance PNG), polygons (each object's outline box), keypoints (its top left and bottom right +corners) and a depth map (objects nearer than the ground); on the point clouds, the points higher than +threshold / 255 are one object (points) and its box (box3d); on an array of frames, the bright square's box in each +frame (a track; above a threshold of 180 the track is split in two at frame 3, an identity switch); on a series, +the stretches where the first channel is high (timeseries; above 180 each stretch ends one position later). +""" +import ast +import json +import os +import struct +import sys +import zlib + +THRESHOLD = float(sys.argv[1]) +TASK = json.load(open(os.environ['TULDOK_TASK'], encoding='utf-8')) +FILES = os.environ['TULDOK_FILES'] + + +def read_png(path): + """(width, height, rows of (r, g, b)) of an RGB PNG whose rows are not filtered (as make_scenes.py writes).""" + data = open(path, 'rb').read() + width, height = struct.unpack('>II', data[16:24]) + at, body = 8, b'' + while at < len(data): + length, kind = struct.unpack('>I4s', data[at:at + 8]) + if kind == b'IDAT': + body += data[at + 8:at + 8 + length] + at += 12 + length + raw = zlib.decompress(body) + stride = width * 3 + 1 + return width, height, [[tuple(raw[y * stride + 1 + x * 3:y * stride + 4 + x * 3]) for x in range(width)] + for y in range(height)] + + +def write_png(path, width, height, values): + rows = b''.join(b'\x00' + bytes(values[y * width:(y + 1) * width]) for y in range(height)) + + def chunk(kind, body): + return struct.pack('>I', len(body)) + kind + body + struct.pack('>I', zlib.crc32(kind + body)) + with open(path, 'wb') as out: + out.write(b'\x89PNG\r\n\x1a\n' + chunk(b'IHDR', struct.pack('>IIBBBBB', width, height, 8, 0, 0, 0, 0)) + + chunk(b'IDAT', zlib.compress(rows)) + chunk(b'IEND', b'')) + + +def read_npy(path): + data = open(path, 'rb').read() + length = struct.unpack('<H', data[8:10])[0] + header = ast.literal_eval(data[10:10 + length].decode('latin-1')) + body, count = data[10 + length:], 1 + for n in header['shape']: + count *= n + values = list(body[:count]) if header['descr'] == '|u1' else list(struct.unpack(f'<{count}f', body[:4 * count])) + return list(header['shape']), values + + +def write_npy(path, shape, values): + header = "{'descr': '<f4', 'fortran_order': False, 'shape': (%s), }" % ', '.join(map(str, shape)) + header += ' ' * (64 - (10 + len(header) + 1) % 64) + '\n' + with open(path, 'wb') as out: + out.write(b'\x93NUMPY\x01\x00' + struct.pack('<H', len(header)) + header.encode('latin-1') + + struct.pack(f'<{len(values)}f', *values)) + + +def objects(path): + """(width, height, ids row by row, {colour: id}) of the image's pixels darker than the threshold.""" + width, height, pixels = read_png(path) + ids, found = [0] * (width * height), {} + for y in range(height): + for x in range(width): + r, g, b = pixels[y][x] + if (r + g + b) / 3 < THRESHOLD: + ids[y * width + x] = found.setdefault('blue' if b > r else 'red', len(found) + 1) + return width, height, ids, found + + +def corners(ids, width, number): + xs = [i % width for i, v in enumerate(ids) if v == number] + ys = [i // width for i, v in enumerate(ids) if v == number] + return min(xs), min(ys), max(xs) + 1, max(ys) + 1 + + +def image_value(record): + width, height, ids, found = objects(record['path']) + kind = TASK['task'] + if kind == 'mask': + name = record['id'] + '.png' + write_png(os.path.join(FILES, name), width, height, ids) + return {'file': name, 'classes': {str(n): TASK['vocabulary'][0] for n in found.values()} or {'1': TASK['vocabulary'][0]}, + 'confidence': round(1 - abs(THRESHOLD - 180) / 400, 2)} + if kind == 'depth': + name = record['id'] + '.npy' + write_npy(os.path.join(FILES, name), [height, width], + [2.0 + THRESHOLD / 1000 if v else 5.0 for v in ids]) + return {'file': name} + value = [] + for colour, number in sorted(found.items()): + x0, y0, x1, y1 = corners(ids, width, number) + if kind == 'polygons': + value.append({'term': colour, 'points': [[x0, y0], [x1, y0], [x1, y1], [x0, y1]], + 'confidence': round(0.95 - 0.1 * number, 2)}) + elif kind == 'keypoints': + value.append({'term': colour, 'points': [[x0, y0, 2], [x1, y1, 2]]}) + return value + + +def cloud_value(record): + rows = open(record['path'], encoding='ascii').read().split('end_header\n')[1].split('\n') + points = [[float(word) for word in row.split()] for row in rows if row.strip()] + high = [i for i, p in enumerate(points) if p[2] > THRESHOLD / 255] + if TASK['task'] == 'points': + return [{'term': TASK['vocabulary'][0], 'indices': high}] if high else [] + if not high: + return [] + low = [min(points[i][axis] for i in high) for axis in range(3)] + top = [max(points[i][axis] for i in high) for axis in range(3)] + return [{'term': TASK['vocabulary'][0], 'center': [round((a + b) / 2, 3) for a, b in zip(low, top)], + 'size': [round(max(0.05, b - a), 3) for a, b in zip(low, top)], 'yaw': round(THRESHOLD / 2550, 3)}] + + +def array_value(record): + shape, values = read_npy(record['path']) + if TASK['task'] == 'track' and len(shape) == 3: + count, height, width = shape + track = {'track': 'square', 'term': TASK['vocabulary'][0], 'frames': []} + tracks = [track] + for frame in range(count): + lit = [i for i in range(height * width) if values[frame * height * width + i] > 128] + if not lit: + continue + xs, ys = [i % width for i in lit], [i // width for i in lit] + box = {'frame': frame, 'x': min(xs), 'y': min(ys), 'w': max(xs) - min(xs) + 1, 'h': max(ys) - min(ys) + 1} + if THRESHOLD > 180 and frame == 3: + track = {'track': 'square-2', 'term': TASK['vocabulary'][0], 'frames': []} + tracks.append(track) + track['frames'].append(box) + return tracks + if TASK['task'] == 'timeseries' and len(shape) == 2: + level = values[::shape[1]] + value, start = [], None + for n, v in enumerate(level + [0.0]): + if v > 0.5 and start is None: + start = n + elif v <= 0.5 and start is not None: + value.append({'term': TASK['vocabulary'][0], 'start': start, + 'end': min(len(level), n + (1 if THRESHOLD > 180 else 0))}) + start = None + return value + return None + + +with open(os.environ['TULDOK_ANNOTATIONS'], 'a', encoding='utf-8') as out: + for line in open(os.environ['TULDOK_TODO'], encoding='utf-8'): + record = json.loads(line) + value = (image_value(record) if record['kind'] == 'image' else + cloud_value(record) if record['kind'] == 'pointcloud' else + array_value(record) if record['kind'] == 'array' else None) + if value is not None: + out.write(json.dumps({'record': record['id'], 'value': value}) + '\n') diff --git a/examples/tiny-project/code/make_scenes.py b/examples/tiny-project/code/make_scenes.py new file mode 100644 index 00000000..0fbaedb3 --- /dev/null +++ b/examples/tiny-project/code/make_scenes.py @@ -0,0 +1,88 @@ +"""Writes scenes/, the small files datasets/scenes imports for the annotators: three images of dark rectangles +with a softer rim, two point clouds rising in height, an array of frames with a square moving across them and a +two-channel series. About five kilobytes in all. Standard library only; the same bytes on every run. + + python make_scenes.py (from code/; writes scenes/ beside this file) +""" +import math +import os +import struct +import zlib + +HERE = os.path.dirname(os.path.abspath(__file__)) + + +def png(width, height, rectangles): + """An RGB PNG of dark rectangles (x, y, w, h, 'red' or 'blue') with a one-pixel rim halfway to white.""" + def pixel(x, y): + for bx, by, bw, bh, colour in rectangles: + dark = (40, 40, 200) if colour == 'blue' else (200, 40, 40) + if bx <= x < bx + bw and by <= y < by + bh: + return dark + if bx - 1 <= x < bx + bw + 1 and by - 1 <= y < by + bh + 1: + return tuple((255 + value) // 2 for value in dark) + return (255, 255, 255) + rows = b''.join(b'\x00' + b''.join(bytes(pixel(x, y)) for x in range(width)) for y in range(height)) + + def chunk(kind, data): + return struct.pack('>I', len(data)) + kind + data + struct.pack('>I', zlib.crc32(kind + data)) + return (b'\x89PNG\r\n\x1a\n' + chunk(b'IHDR', struct.pack('>IIBBBBB', width, height, 8, 2, 0, 0, 0)) + + chunk(b'IDAT', zlib.compress(rows, 9)) + chunk(b'IEND', b'')) + + +def cloud(count): + """An ASCII PLY of count points along a line rising from z 0 to 1.""" + lines = ['ply', 'format ascii 1.0', f'element vertex {count}', 'property float x', 'property float y', + 'property float z', 'end_header'] + lines += [f'{n * 0.1:.2f} {0.05 * (n % 3):.2f} {n / (count - 1):.3f}' for n in range(count)] + return ('\n'.join(lines) + '\n').encode('ascii') + + +def npy(shape, values, descr): + """An NPY (version 1) array in C order.""" + header = "{'descr': '%s', 'fortran_order': False, 'shape': (%s), }" % ( + descr, ''.join(f'{n}, ' for n in shape) if len(shape) == 1 else ', '.join(map(str, shape))) + header += ' ' * (64 - (10 + len(header) + 1) % 64) + '\n' + code = {'|u1': 'B', '<f4': '<f'}[descr] + body = bytes(values) if code == 'B' else struct.pack(f'<{len(values)}f', *values) + return b'\x93NUMPY\x01\x00' + struct.pack('<H', len(header)) + header.encode('latin-1') + body + + +def frames(count=6, height=16, width=20): + """count frames of a 4 by 4 square (220) on a dark ground (20), moving two pixels right each frame.""" + values = [] + for frame in range(count): + x0 = 2 + 2 * frame + values += [220 if x0 <= x < x0 + 4 and 6 <= y < 10 else 20 for y in range(height) for x in range(width)] + return npy((count, height, width), values, '|u1') + + +def series(length=48): + """Two channels: a level that is high from 10 to 20 and 30 to 38, and a slow wave.""" + values = [] + for n in range(length): + values += [1.0 if 10 <= n < 20 or 30 <= n < 38 else 0.0, round(math.sin(n / 6), 4)] + return npy((length, 2), values, '<f4') + + +FILES = { + 'images/a.png': png(24, 16, [(2, 2, 6, 5, 'red'), (14, 6, 7, 7, 'blue')]), + 'images/b.png': png(24, 16, [(4, 4, 10, 8, 'red')]), + 'images/c.png': png(24, 16, [(1, 1, 4, 4, 'blue'), (10, 3, 5, 9, 'blue')]), + 'clouds/p.ply': cloud(20), + 'clouds/q.ply': cloud(30), + 'frames/moving.npy': frames(), + 'series/signal.npy': series(), +} + + +def main(): + for name, data in FILES.items(): + path = os.path.join(HERE, 'scenes', *name.split('/')) + os.makedirs(os.path.dirname(path), exist_ok=True) + with open(path, 'wb') as handle: + handle.write(data) + + +if __name__ == '__main__': + main() diff --git a/examples/tiny-project/code/scenes/clouds/p.ply b/examples/tiny-project/code/scenes/clouds/p.ply new file mode 100644 index 00000000..296f0330 --- /dev/null +++ b/examples/tiny-project/code/scenes/clouds/p.ply @@ -0,0 +1,27 @@ +ply +format ascii 1.0 +element vertex 20 +property float x +property float y +property float z +end_header +0.00 0.00 0.000 +0.10 0.05 0.053 +0.20 0.10 0.105 +0.30 0.00 0.158 +0.40 0.05 0.211 +0.50 0.10 0.263 +0.60 0.00 0.316 +0.70 0.05 0.368 +0.80 0.10 0.421 +0.90 0.00 0.474 +1.00 0.05 0.526 +1.10 0.10 0.579 +1.20 0.00 0.632 +1.30 0.05 0.684 +1.40 0.10 0.737 +1.50 0.00 0.789 +1.60 0.05 0.842 +1.70 0.10 0.895 +1.80 0.00 0.947 +1.90 0.05 1.000 diff --git a/examples/tiny-project/code/scenes/clouds/q.ply b/examples/tiny-project/code/scenes/clouds/q.ply new file mode 100644 index 00000000..90490b4e --- /dev/null +++ b/examples/tiny-project/code/scenes/clouds/q.ply @@ -0,0 +1,37 @@ +ply +format ascii 1.0 +element vertex 30 +property float x +property float y +property float z +end_header +0.00 0.00 0.000 +0.10 0.05 0.034 +0.20 0.10 0.069 +0.30 0.00 0.103 +0.40 0.05 0.138 +0.50 0.10 0.172 +0.60 0.00 0.207 +0.70 0.05 0.241 +0.80 0.10 0.276 +0.90 0.00 0.310 +1.00 0.05 0.345 +1.10 0.10 0.379 +1.20 0.00 0.414 +1.30 0.05 0.448 +1.40 0.10 0.483 +1.50 0.00 0.517 +1.60 0.05 0.552 +1.70 0.10 0.586 +1.80 0.00 0.621 +1.90 0.05 0.655 +2.00 0.10 0.690 +2.10 0.00 0.724 +2.20 0.05 0.759 +2.30 0.10 0.793 +2.40 0.00 0.828 +2.50 0.05 0.862 +2.60 0.10 0.897 +2.70 0.00 0.931 +2.80 0.05 0.966 +2.90 0.10 1.000 diff --git a/examples/tiny-project/code/scenes/frames/moving.npy b/examples/tiny-project/code/scenes/frames/moving.npy new file mode 100644 index 0000000000000000000000000000000000000000..2a7663153460e475eae89002bec8f2757792bbbe GIT binary patch literal 2048 zcmbR27wQ`j$;eQ~P_3SlTAW;@Zl$1JQ);NLqoAIaUsO_*m=~X4l#&V(cT3DEP6dh= zXCxM+0{I$dItqqBY-FIRqfo0r4&V|QFmMM5&@HD#4Bf2Z&!;4`u<0HCA%^ZlY@tAj m7`pkxpHE3>VbeSOLk!)A*g}C4F?92XKcAA&!lsv=AqD_13H<&5 literal 0 HcmV?d00001 diff --git a/examples/tiny-project/code/scenes/images/a.png b/examples/tiny-project/code/scenes/images/a.png new file mode 100644 index 0000000000000000000000000000000000000000..678ba10bbe1690f09763189860f0f4d15516824f GIT binary patch literal 119 zcmeAS@N?(olHy`uVBq!ia0vp^5<o1#!2~3m-82pXDLYRW$B>F!$v^y64=^0*SNA{G zb;9sPOB<V%lqK6k4mSa%n+iOt3N3j82P2eEDI^_O;rPY0qrhrW)Vt+CgAIGu?G~77 Re++06gQu&X%Q~loCICU}Bo_bx literal 0 HcmV?d00001 diff --git a/examples/tiny-project/code/scenes/images/b.png b/examples/tiny-project/code/scenes/images/b.png new file mode 100644 index 0000000000000000000000000000000000000000..3e79b183709433e9b6dd28cfe9e9c784f4029c7b GIT binary patch literal 96 zcmeAS@N?(olHy`uVBq!ia0vp^5<o1#!2~3m-82pXDRoa5$B>F!$v^y64;XatR@qb< uIl8QIR5vmCupqG6jdxLclT6u6F$O8#z5gtxeVhr@!r<xZ=d#Wzp$Pyj(Hg@5 literal 0 HcmV?d00001 diff --git a/examples/tiny-project/code/scenes/images/c.png b/examples/tiny-project/code/scenes/images/c.png new file mode 100644 index 0000000000000000000000000000000000000000..d35fb880ad8aafcdb8e51ef054787d15eed34611 GIT binary patch literal 120 zcmeAS@N?(olHy`uVBq!ia0vp^5<o1#!2~3m-82pXDSJ;B$B>F!$un$z8cO~07fWDx zb>)Huqq~VA$K{O`YZMa%Hi^`I54x%l)2Dt`!RDcP)&&96j+QBZ=X)i5kYr(aR&cFX TR7E}<XcU8|tDnm{r-UW|w+AK! literal 0 HcmV?d00001 diff --git a/examples/tiny-project/code/scenes/series/signal.npy b/examples/tiny-project/code/scenes/series/signal.npy new file mode 100644 index 0000000000000000000000000000000000000000..3fef6444bad4859490cf43cc2bcbe03c7349380f GIT binary patch literal 512 zcmbR27wQ`j$;eQ~P_3SlTAW;@Zl$1ZlV+l>qoAIaUsO_*m=~X4l#&V(cT3DEP6dh= zXCxM+0{I#y7CH(>nmP)#3giMV1|+cYp{5;(d#G(Wn0{US6-<};%h`j(_t)Bj>F%6x zFnuOA8%!6Rs{qrQG4(*Y!M^iS9hjE2C<oJzk7s~swI{(~T2$5&O#7Hif@v$|S3r9j z?Cry6gXz{90WjS%@9Z9sy-RhR_kn2sIh(<>Q7FTH5I@UT8B8zT>j<WGu0(<9PnUAR zbfIk(m@eN}52mLn)&c1T`--YkFujZ`4NT{m1VH$+O~CXk77;KlJ?|dSz6Sdi-hME> zN$=fWki9EReQiOsu5*kXh*p`tA52?bW3>nI)eSYkbjV{@FkLMY2d0lI6o6^@)@m^Q I^i#b(0P0?REdT%j literal 0 HcmV?d00001 diff --git a/examples/tiny-project/project/annotations/scene-masks.json b/examples/tiny-project/project/annotations/scene-masks.json new file mode 100644 index 00000000..9ecf4a22 --- /dev/null +++ b/examples/tiny-project/project/annotations/scene-masks.json @@ -0,0 +1,12 @@ +{ + "format": "tuldok_definition_v1", + "kind": "annotation", + "title": "Objects in the scenes, as masks", + "description": "An instance mask of each dark object of the scenes' images, made by the stand-in segmentors.", + "dataset": "datasets/scenes", + "task": "mask", + "mask": "instance", + "vocabulary": [ + "blob" + ] +} diff --git a/examples/tiny-project/project/annotations/scene-objects.json b/examples/tiny-project/project/annotations/scene-objects.json new file mode 100644 index 00000000..08c8061b --- /dev/null +++ b/examples/tiny-project/project/annotations/scene-objects.json @@ -0,0 +1,11 @@ +{ + "format": "tuldok_definition_v1", + "kind": "annotation", + "title": "The top of each point cloud", + "description": "The points of each cloud that belong to its top, made by the stand-in segmentors.", + "dataset": "datasets/scenes", + "task": "points", + "vocabulary": [ + "top" + ] +} diff --git a/examples/tiny-project/project/datasets/scene-masks-a.json b/examples/tiny-project/project/datasets/scene-masks-a.json new file mode 100644 index 00000000..82d82bda --- /dev/null +++ b/examples/tiny-project/project/datasets/scene-masks-a.json @@ -0,0 +1,28 @@ +{ + "format": "tuldok_definition_v1", + "kind": "dataset", + "title": "Segmentor A on scene-masks", + "description": "The stand-in segmentor at threshold 160: an annotation set for annotations/scene-masks.", + "run": { + "step": "annotate", + "inputs": { + "records": "datasets/scenes" + }, + "annotations": [ + "annotations/scene-masks" + ], + "command": [ + "python", + "annotators/standin.py", + "160" + ], + "environment": "environments/cpu", + "settings": { + "by": { + "kind": "script", + "name": "stand-in segmentor A", + "version": "1" + } + } + } +} diff --git a/examples/tiny-project/project/datasets/scene-masks-b.json b/examples/tiny-project/project/datasets/scene-masks-b.json new file mode 100644 index 00000000..9da26cde --- /dev/null +++ b/examples/tiny-project/project/datasets/scene-masks-b.json @@ -0,0 +1,28 @@ +{ + "format": "tuldok_definition_v1", + "kind": "dataset", + "title": "Segmentor B on scene-masks", + "description": "The stand-in segmentor at threshold 200: an annotation set for annotations/scene-masks.", + "run": { + "step": "annotate", + "inputs": { + "records": "datasets/scenes" + }, + "annotations": [ + "annotations/scene-masks" + ], + "command": [ + "python", + "annotators/standin.py", + "200" + ], + "environment": "environments/cpu", + "settings": { + "by": { + "kind": "script", + "name": "stand-in segmentor B", + "version": "1" + } + } + } +} diff --git a/examples/tiny-project/project/datasets/scene-objects-a.json b/examples/tiny-project/project/datasets/scene-objects-a.json new file mode 100644 index 00000000..12e5ee8f --- /dev/null +++ b/examples/tiny-project/project/datasets/scene-objects-a.json @@ -0,0 +1,28 @@ +{ + "format": "tuldok_definition_v1", + "kind": "dataset", + "title": "Segmentor A on scene-objects", + "description": "The stand-in segmentor at threshold 128: an annotation set for annotations/scene-objects.", + "run": { + "step": "annotate", + "inputs": { + "records": "datasets/scenes" + }, + "annotations": [ + "annotations/scene-objects" + ], + "command": [ + "python", + "annotators/standin.py", + "128" + ], + "environment": "environments/cpu", + "settings": { + "by": { + "kind": "script", + "name": "stand-in segmentor A", + "version": "1" + } + } + } +} diff --git a/examples/tiny-project/project/datasets/scene-objects-b.json b/examples/tiny-project/project/datasets/scene-objects-b.json new file mode 100644 index 00000000..423cfa09 --- /dev/null +++ b/examples/tiny-project/project/datasets/scene-objects-b.json @@ -0,0 +1,28 @@ +{ + "format": "tuldok_definition_v1", + "kind": "dataset", + "title": "Segmentor B on scene-objects", + "description": "The stand-in segmentor at threshold 140: an annotation set for annotations/scene-objects.", + "run": { + "step": "annotate", + "inputs": { + "records": "datasets/scenes" + }, + "annotations": [ + "annotations/scene-objects" + ], + "command": [ + "python", + "annotators/standin.py", + "140" + ], + "environment": "environments/cpu", + "settings": { + "by": { + "kind": "script", + "name": "stand-in segmentor B", + "version": "1" + } + } + } +} diff --git a/examples/tiny-project/project/datasets/scenes.json b/examples/tiny-project/project/datasets/scenes.json new file mode 100644 index 00000000..61330fab --- /dev/null +++ b/examples/tiny-project/project/datasets/scenes.json @@ -0,0 +1,14 @@ +{ + "format": "tuldok_definition_v1", + "kind": "dataset", + "title": "Scenes for the annotators", + "description": "Three images, two point clouds, an array of frames and a series, imported from code/scenes (written by code/make_scenes.py).", + "run": { + "step": "import", + "settings": { + "source": "scenes", + "pattern": "**/*", + "rights": "Made by make_scenes.py for this example; free to use." + } + } +} diff --git a/tests/browser_annotation_kinds_fixture.py b/tests/browser_annotation_kinds_fixture.py new file mode 100644 index 00000000..d7dbfdca --- /dev/null +++ b/tests/browser_annotation_kinds_fixture.py @@ -0,0 +1,81 @@ +"""The project of tests/browser_project_workspace_annotation_kinds.cjs: a Git repository with code/ and project/. + +code/ holds examples/tiny-project's make_scenes.py (run here: three images, two point clouds, an array of frames +and a series) and its stand-in annotator, annotators/standin.py. project/ imports the scenes (datasets/scenes) and +has a task of each type the stand-in makes, each with two annotators: the stand-in at two thresholds, in +environments/test-python (the interpreter running the check, connected by the check). Prints the task names, the +annotators and the project's id as JSON. + + python tests/browser_annotation_kinds_fixture.py <repository directory> +""" +import json +import pathlib +import shutil +import subprocess +import sys +import uuid + +EXAMPLE = pathlib.Path(__file__).resolve().parents[1] / 'examples' / 'tiny-project' / 'code' +GIT = ['git', '-c', 'user.name=Tuldok Test', '-c', 'user.email=test@example.invalid', '-c', 'commit.gpgsign=false', + '-c', 'init.defaultBranch=main'] +DEFINITION = 'tuldok_definition_v1' +# task -> (type, vocabulary, fields, thresholds of A and B) +TASKS = { + 'masks': ('mask', ['blob'], {'mask': 'instance'}, (160, 200)), + 'shapes': ('polygons', ['red', 'blue'], {}, (160, 200)), + 'depths': ('depth', None, {'units': 'm'}, (160, 200)), + 'corners': ('keypoints', ['red', 'blue'], {'keypoints': ['head', 'tail'], 'skeleton': [['head', 'tail']]}, + (160, 200)), + 'tops': ('points', ['top'], {}, (128, 140)), + 'boxes3d': ('box3d', ['top'], {}, (128, 140)), + 'stretches': ('timeseries', ['high'], {}, (160, 200)), + 'tracks': ('track', ['square'], {}, (160, 200)), +} + + +def write(path, document): + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(json.dumps(document, indent=2, ensure_ascii=False) + '\n', encoding='utf-8') + + +def main(repository): + repository = pathlib.Path(repository) + code, folder = repository / 'code', repository / 'project' + (code / 'annotators').mkdir(parents=True) + shutil.copyfile(EXAMPLE / 'make_scenes.py', code / 'make_scenes.py') + shutil.copyfile(EXAMPLE / 'annotators' / 'standin.py', code / 'annotators' / 'standin.py') + subprocess.run([sys.executable, 'make_scenes.py'], cwd=code, check=True) + project_id = uuid.uuid4().hex + write(folder / 'tuldok.json', {'format': 'tuldok_project_v1', 'id': project_id, 'name': 'Annotation kinds check', + 'code_root': '../code'}) + write(folder / 'environments' / 'test-python.json', { + 'format': DEFINITION, 'kind': 'environment', 'title': 'The interpreter running the check', 'python': '3.12', + 'device': 'cpu', 'packages': {'jsonschema': '4.26.0'}}) + write(folder / 'datasets' / 'scenes.json', { + 'format': DEFINITION, 'kind': 'dataset', 'title': 'Scenes', + 'run': {'step': 'import', 'settings': {'source': 'scenes', 'rights': 'Made for this check.'}}}) + annotators = [] + for name, (kind, vocabulary, fields, thresholds) in TASKS.items(): + task = {'format': DEFINITION, 'kind': 'annotation', 'title': f'The {name}', 'dataset': 'datasets/scenes', + 'task': kind, **fields} + if vocabulary: + task['vocabulary'] = vocabulary + write(folder / 'annotations' / f'{name}.json', task) + for letter, threshold in zip('ab', thresholds): + reference = f'datasets/{name}-{letter}' + annotators.append(reference) + write(folder / f'{reference}.json', { + 'format': DEFINITION, 'kind': 'dataset', 'title': f'Stand-in {letter.upper()} on {name}', + 'run': {'step': 'annotate', 'inputs': {'records': 'datasets/scenes'}, + 'annotations': [f'annotations/{name}'], + 'command': ['python', 'annotators/standin.py', str(threshold)], + 'environment': 'environments/test-python', + 'settings': {'by': {'kind': 'script', 'name': f'stand-in {letter.upper()}', 'version': '1'}}}}) + for arguments in (['init', '-q'], ['add', '-A'], ['commit', '-q', '-m', 'The fixture.']): + subprocess.run([*GIT, '-C', str(repository), *arguments], check=True) + print(json.dumps({'project_id': project_id, 'tasks': {name: spec[0] for name, spec in TASKS.items()}, + 'annotators': annotators})) + + +if __name__ == '__main__': + main(sys.argv[1]) diff --git a/tests/browser_project_workspace_annotation_kinds.cjs b/tests/browser_project_workspace_annotation_kinds.cjs new file mode 100644 index 00000000..4c3c4c9c --- /dev/null +++ b/tests/browser_project_workspace_annotation_kinds.cjs @@ -0,0 +1,316 @@ +'use strict'; +// Review of generated annotations (docs/plans/training-and-curation/spec-t4.md sections 7 and 9, slices T4e and T4f) +// in a headless browser, the owner signed in, no GPU, no Pumas. The fixture (tests/browser_annotation_kinds_fixture.py) +// is a project in Git whose code is examples/tiny-project's make_scenes.py and stand-in annotator: datasets/scenes +// imports three images, two point clouds, an array of frames and a series, and a task of each of eight types (mask, +// polygons, depth, keypoints, points, box3d, timeseries, track) has two annotators, the stand-in at two thresholds, +// built by the command line before Tuldok starts. +// 1. Annotate → Review on the masks: the agreement shown is the server's, the most disputed records are listed in +// the order computed, two panels side by side each draw their set's mask, and overlaid one panel draws both. +// 2. Every other type is drawn: polygons, depth maps and keypoints on the images, point objects and 3-D boxes on a +// point cloud, stretches under the series, and tracks on the frames, where the frame slider shows B's identity +// switch at frame 3. +// 3. One record is reviewed and B kept: the decision says so, the strip counts it, Save writes +// annotations/masks.jsonl with the line naming the set and annotations/masks/<its mask>. +// 4. A kept polygon is corrected: a vertex dragged, the correction kept and saved. +// 5. Updates in place: a change elsewhere (an agent sets another task's annotation) and the window regaining focus +// add, remove and change no node of the main area. +// 6. Light and dark at 1440 by 900 and 390 by 844: nothing overflows sideways (screenshots with --shots <dir>). +// It fails on any script error and any failed request. +// node tests/browser_project_workspace_annotation_kinds.cjs [--shots <dir>] +const assert = require('node:assert/strict'), fs = require('node:fs'), os = require('node:os'), path = require('node:path'); +const { spawn, execFileSync } = require('node:child_process'), { once } = require('node:events'); +const { authenticatedFixture } = require('./auth_helpers.cjs'), { waitForDebugger } = require('./browser_startup.cjs'), { cdpSession } = require('./browser_cdp_session.cjs'), { qaDirectory } = require('./qa_artifacts.cjs'); + +const root = path.resolve(__dirname, '..'); +const argv = process.argv.slice(2), option = name => { const i = argv.indexOf(name); return i >= 0 ? argv[i + 1] : null; }; +assert.ok(process.env.TULDOK_DATABASE_URL, 'TULDOK_DATABASE_URL must name a disposable PostgreSQL cluster'); +const venv = path.join(root, '.venv', 'bin'); +if (fs.existsSync(path.join(venv, 'python'))) process.env.PATH = venv + path.delimiter + process.env.PATH; +const python = fs.existsSync(path.join(venv, 'python')) ? path.join(venv, 'python') : 'python3'; +const WATCHED = ['summary', 'status', 'build_requests', 'environments', 'runs']; + +const temporary = fs.mkdtempSync(path.join(os.tmpdir(), 'tuldok-annotation-kinds-')); +const report = qaDirectory(root, 'project-workspace-annotation-kinds'); +const shots = option('--shots') ? path.resolve(option('--shots')) : null; if (shots) fs.mkdirSync(shots, { recursive: true }); +const children = [], checks = [], errors = [], failures = []; +let server, serverErrors = '', origin, auth, socket, session, send, evaluate, owned = null, folder; +const pause = ms => new Promise(resolve => setTimeout(resolve, ms)); +async function until(fn, label, tries = 300) { for (let i = 0; i < tries; i++) { const value = await fn(); if (value) return value; await pause(100); } throw Error('Timed out: ' + label); } +function check(text) { checks.push(text); console.log('PASS ' + text); } +function launch(command, args, options) { const child = spawn(command, args, options); children.push(child); return child; } +async function stop(child) { if (!child || child.exitCode !== null || child.signalCode !== null) return; const exited = once(child, 'exit'); child.kill('SIGTERM'); await Promise.race([exited, pause(10000)]); if (child.exitCode === null && child.signalCode === null) { child.kill('SIGKILL'); await exited; } } +function findBrowser() { + const candidates = [process.env.BROWSER, '/usr/bin/chromium', '/usr/bin/chromium-browser', '/usr/bin/google-chrome']; + const cache = path.join(os.homedir(), '.cache', 'ms-playwright'); + if (fs.existsSync(cache)) for (const name of fs.readdirSync(cache).filter(n => n.startsWith('chromium_headless_shell-')).sort().reverse()) candidates.push(path.join(cache, name, 'chrome-headless-shell-linux64', 'chrome-headless-shell')); + const found = candidates.find(candidate => candidate && fs.existsSync(candidate)); + assert.ok(found, 'No headless browser: set BROWSER'); + return found; +} +function dropOwned(id, catalog) { + execFileSync(python, ['-c', `import json, os, pathlib, sys, psycopg +from psycopg import sql +from tuldok_project import store +store.drop_project(sys.argv[1], os.environ['TULDOK_DATABASE_URL']) +root = pathlib.Path(sys.argv[2]) +if root.exists(): + with psycopg.connect(os.environ['TULDOK_DATABASE_URL'], autocommit=True) as c: + for p in root.rglob('.tuldok.json'): + v = json.loads(p.read_text()) + name = 'projection_' + v['projection_id'] if v.get('version') == 2 else 'catalog_' + v['dataset_id'] + c.execute(sql.SQL('DROP SCHEMA IF EXISTS {} CASCADE').format(sql.Identifier(name))) +`, id, catalog], { cwd: root, stdio: ['ignore', 'pipe', 'pipe'] }); +} +async function contract(name) { + const capabilities = await (await auth.fetch(origin + '/api/agent/capabilities')).json(); + const operation = capabilities.operations.find(item => item.id === 'project.' + name), c = operation.contracts[operation.contracts.length - 1]; + return 'project.' + name + '/' + c.version + '/' + c.sha256; +} +async function api(name, body = {}, bearer = null) { + const headers = { 'Content-Type': 'application/json', 'Tuldok-Operation-Contract': await contract(name) }; + const response = bearer ? await globalThis.fetch(origin + '/api/project/' + name, { method: 'POST', headers: { ...headers, Authorization: 'Bearer ' + bearer }, body: JSON.stringify(body) }) + : await auth.fetch(origin + '/api/project/' + name, { method: 'POST', headers, body: JSON.stringify(body) }); + const value = await response.json(); assert.equal(response.status, 200, name + ': ' + JSON.stringify(value)); return value; +} +async function credential(label, scopes) { + const response = await auth.fetch(origin + '/api/access/credentials', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ label, scopes, ttl_seconds: 3600 }) }); + const value = await response.json(); assert.equal(response.status, 201, JSON.stringify(value)); return value.token; +} + +// ---- The page's readings, from the browser's network ------------------------------------------------------------ +const calls = new Map(), finished = []; +function network(event) { + const p = event.params; + if (event.method === 'Network.requestWillBeSent' && /\/api\/project\/[a-z_]+$/.test(p.request.url)) calls.set(p.requestId, { name: p.request.url.split('/').pop(), sent: Date.now() }); + if ((event.method === 'Network.loadingFinished' || event.method === 'Network.loadingFailed') && calls.has(p.requestId)) { finished.push(Object.assign(calls.get(p.requestId), { done: Date.now() })); calls.delete(p.requestId); } +} +async function settled(label) { + await until(async () => !calls.size && await evaluate(`(() => { const reading = e => [...e.querySelectorAll('.note')].some(n => n.textContent === 'Reading…'); return !reading(document.getElementById('main')) && !reading(document.getElementById('aside')) && !document.getElementById('main').hasAttribute('aria-busy') && !document.querySelector('.act-group [aria-busy]'); })()`), 'settled: ' + label); + await pause(250); + await until(async () => !calls.size, 'settled again: ' + label); +} +async function reading(since, names, label) { + await until(() => names.every(name => finished.some(f => f.name === name && f.sent >= since)), 'a reading: ' + label); + await until(() => !calls.size && Date.now() - Math.max(0, ...finished.map(f => f.done)) > 700, 'the reading done: ' + label); + await settled(label); +} +const byKey = key => `[data-key=${JSON.stringify(key)}]`; +async function centre(selector) { + return until(() => evaluate(`(() => { const e = [...document.querySelectorAll(${JSON.stringify(selector)})].find(e => e.offsetParent !== null); if (!e) return null; e.scrollIntoView({ block: 'nearest', inline: 'nearest' }); const r = e.getBoundingClientRect(), x = r.left + r.width / 2, y = r.top + r.height / 2, hit = document.elementFromPoint(x, y); return hit && (hit === e || e.contains(hit)) ? { x, y } : null; })()`), 'shown: ' + selector, 100); +} +async function mouse(type, x, y, buttons = 0) { await send('Input.dispatchMouseEvent', { type, x, y, button: type === 'mouseMoved' ? (buttons ? 'left' : 'none') : 'left', buttons, clickCount: type === 'mouseMoved' ? 0 : 1 }); } +async function press(selector) { const { x, y } = await centre(selector); await mouse('mouseMoved', x, y); await mouse('mousePressed', x, y, 1); await mouse('mouseReleased', x, y); } +async function dragFrom(a, b, steps = 8) { await mouse('mouseMoved', a.x, a.y); await mouse('mousePressed', a.x, a.y, 1); for (let i = 1; i <= steps; i++) await mouse('mouseMoved', a.x + (b.x - a.x) * i / steps, a.y + (b.y - a.y) * i / steps, 1); await mouse('mouseReleased', b.x, b.y); } +async function choose(selector, value) { await evaluate(`(() => { const s = document.querySelector(${JSON.stringify(selector)}); s.value = ${JSON.stringify(value)}; s.dispatchEvent(new Event('change', { bubbles: true })); return true; })()`); } +async function shot(name) { + await evaluate('new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve)))'); + const png = Buffer.from((await send('Page.captureScreenshot', { format: 'png', captureBeyondViewport: false })).data, 'base64'); + fs.writeFileSync(path.join(report, name + '.png'), png); if (shots) fs.writeFileSync(path.join(shots, name + '.png'), png); +} +const fixed = v => v == null ? '—' : v.toFixed(2); +const drawn = selector => evaluate(`[...document.querySelectorAll(${JSON.stringify(selector)})].map(e => e.dataset.drawn)`); +/** Pixels of a canvas that are neither empty nor the page's white: something was drawn on it. */ +const inked = selector => evaluate(`[...document.querySelectorAll(${JSON.stringify(selector)})].map(c => { const d = c.getContext('2d').getImageData(0, 0, c.width, c.height).data; let n = 0; for (let i = 0; i < d.length; i += 4) if (d[i + 3] && !(d[i] > 245 && d[i + 1] > 245 && d[i + 2] > 245)) n++; return n; })`); +const lines = name => { const file = path.join(folder, 'annotations', name + '.jsonl'); return fs.existsSync(file) ? fs.readFileSync(file, 'utf8').split('\n').filter(Boolean).map(l => JSON.parse(l)) : []; }; + +const WATCHER = `window.__still = (() => { + const ids = ['tabs', 'main', 'aside', 'review'], el = id => id === 'review' ? document.querySelector('#main .rv-body') : document.getElementById(id); + let counts = null, observers = []; + return { + start() { + for (const o of observers) o.disconnect(); observers = []; counts = {}; + for (const id of ids) { counts[id] = { added: 0, removed: 0, attrs: 0, text: 0, what: [] }; const c = counts[id]; + const o = new MutationObserver(list => { for (const r of list) { if (r.type === 'childList') { c.added += r.addedNodes.length; c.removed += r.removedNodes.length; } else if (r.type === 'characterData') c.text++; else { c.attrs++; if (c.what.length < 6) c.what.push('@' + r.attributeName + ' ' + (r.target.className || r.target.tagName)); } } }); + o.observe(el(id), { childList: true, subtree: true, characterData: true, attributes: true }); observers.push(o); } + }, + stop() { for (const o of observers) o.disconnect(); observers = []; const r = counts; counts = null; return r; } + }; +})(); true`; + +(async () => { + // ---- The fixture ------------------------------------------------------------------------------------------------ + const repo = path.join(temporary, 'fixture'); folder = path.join(repo, 'project'); + const info = JSON.parse(execFileSync(python, [path.join(root, 'tests', 'browser_annotation_kinds_fixture.py'), repo], { cwd: root }).toString().trim().split('\n').pop()); + const home = path.join(temporary, 'home'), catalog = path.join(temporary, 'catalog'); fs.mkdirSync(home); + const env = { ...process.env, TULDOK_PROJECT_HOME: home, TULDOK_SETTINGS: path.join(temporary, 'settings.json') }; + owned = [info.project_id, catalog]; dropOwned(...owned); + const cli = (...args) => execFileSync(python, ['-m', 'tuldok_project', ...args], { cwd: root, env, stdio: ['ignore', 'pipe', 'pipe'] }).toString(); + assert.match(cli('check', folder), /^0 errors/m); + cli('connect', folder, 'environments/test-python', python); + cli('build', folder, ...info.annotators, '--yes'); + let output = ''; + server = launch(python, ['-u', 'app.py', '--port', '0', '--data', catalog, '--project-folder', folder], { cwd: root, env, stdio: ['ignore', 'pipe', 'pipe'] }); + server.stdout.on('data', chunk => { output += chunk; }); server.stderr.on('data', chunk => { serverErrors += chunk; }); + const port = await until(() => { if (server.exitCode !== null) throw Error('Tuldok exited: ' + serverErrors); return output.match(/127\.0\.0\.1:(\d+)/)?.[1]; }, 'Tuldok start-up', 3000); + origin = 'http://127.0.0.1:' + port; + auth = authenticatedFixture(); await auth.register(origin, catalog, root); + for (const task of Object.keys(info.tasks)) assert.equal((await api('annotation_sets', { task })).sets.filter(s => s.annotated).length, 2, task + ' has two sets'); + + const browser = launch(findBrowser(), ['--headless', '--no-sandbox', '--disable-gpu', '--no-first-run', '--hide-scrollbars', '--remote-debugging-port=0', '--window-size=1440,900', '--user-data-dir=' + path.join(temporary, 'browser'), 'about:blank'], { stdio: 'ignore', env: { ...process.env, XDG_CONFIG_HOME: temporary, XDG_CACHE_HOME: temporary } }); + const debugPort = await waitForDebugger(browser, path.join(temporary, 'browser', 'DevToolsActivePort')); + const target = (await (await fetch('http://127.0.0.1:' + debugPort + '/json')).json()).find(item => item.type === 'page'); + socket = new WebSocket(target.webSocketDebuggerUrl); await once(socket, 'open'); + session = cdpSession(socket, { timeoutMs: 60000, onEvent: event => { + network(event); + if (event.method === 'Runtime.exceptionThrown') errors.push(event.params.exceptionDetails.exception?.description || event.params.exceptionDetails.text); + if (event.method === 'Runtime.consoleAPICalled' && event.params.type === 'error') errors.push(event.params.args.map(a => a.value ?? a.description).join(' ')); + if (event.method === 'Log.entryAdded' && event.params.entry.level === 'error') errors.push(event.params.entry.text + ' ' + (event.params.entry.url || '')); + if (event.method === 'Network.loadingFailed' && !event.params.canceled) failures.push({ id: event.params.requestId, error: event.params.errorText }); + if (event.method === 'Network.responseReceived' && event.params.response.status >= 400) failures.push({ url: event.params.response.url, status: event.params.response.status }); + } }); + send = session.send; + evaluate = async expression => { const result = await send('Runtime.evaluate', { expression, awaitPromise: true, returnByValue: true }); if (result.exceptionDetails) throw Error(JSON.stringify(result.exceptionDetails)); return result.result.value; }; + await send('Page.enable'); await send('Runtime.enable'); await send('Network.enable'); await send('Log.enable'); + const size = async (width, height) => send('Emulation.setDeviceMetricsOverride', { width, height, deviceScaleFactor: 1, mobile: width < 600 }); + const theme = async name => { await send('Emulation.setEmulatedMedia', { features: [{ name: 'prefers-color-scheme', value: name }, { name: 'prefers-reduced-motion', value: 'reduce' }] }); }; + await size(1440, 900); await theme('light'); + await auth.browser(send, origin); + const load = async name => { + await theme(name); + await send('Page.navigate', { url: 'about:blank' }); await pause(100); + await send('Page.navigate', { url: origin + '/?theme=' + name + '#annotate' }); + await until(() => evaluate(`document.readyState === 'complete' && !!document.getElementById('needs-btn') && !document.getElementById('needs-btn').disabled`), 'the project read', 1200); + await settled('opened'); + }; + const pickTask = async name => { + const ref = 'annotations/' + name; + if ((await evaluate(`document.querySelector('[data-key="ann:task"]').value`)) !== ref) { await choose(byKey('ann:task'), ref); await settled('task ' + name); } + if ((await evaluate(`(document.querySelector('[data-key="ann:mode-review"]') || {}).getAttribute?.('aria-pressed')`)) !== 'true') { await press(byKey('ann:mode-review')); await settled('review ' + name); } + await until(() => evaluate(`!!document.querySelector('#main .rv-body .rv-rec')`), 'review of ' + name); + }; + const mode = async which => { if ((await evaluate(`document.querySelector('[data-key="rv:mode-${which}"]').getAttribute('aria-pressed')`)) !== 'true') { await press(byKey('rv:mode-' + which)); await settled('mode ' + which); } }; + const over = async label => { const o = await evaluate(`(() => { const m = document.getElementById('main'); return { page: document.documentElement.scrollWidth - innerWidth, main: m.scrollWidth - m.clientWidth }; })()`); assert.ok(o.page <= 0 && o.main <= 1, label + ': sideways overflow ' + JSON.stringify(o)); }; + await load('light'); + + // ---- 1. Masks: the agreement, the disputed order, side by side and overlaid ------------------------------------------ + await pickTask('masks'); + const ag = await api('annotation_agreement', { task: 'masks', sets: ['datasets/masks-a', 'datasets/masks-b'], limit: 200 }); + assert.equal(await evaluate(`document.querySelector('#main .rv-score').textContent`), fixed(ag.pairs[0].agreement)); + const listed = await evaluate(`[...document.querySelectorAll('#main .rv-rec')].map(b => [b.dataset.id, b.querySelector('.rv-dis').textContent])`); + assert.deepEqual(listed, ag.disputed.map(r => [r.record, fixed(r.disagreement)]), 'the most disputed, as computed'); + assert.equal(await evaluate(`document.querySelector('#main .rv-rec[aria-pressed="true"]').dataset.id`), ag.disputed[0].record); + await mode('side'); + const first = await api('annotation_compare', { task: 'masks', record: ag.disputed[0].record, sets: ['datasets/masks-a', 'datasets/masks-b'] }); + const pixels = s => s.drawn.runs.reduce((n, [v, c]) => n + (v ? c : 0), 0); + assert.deepEqual(await drawn('#main .rv-panel canvas'), ['a:' + pixels(first.sets[0]), 'b:' + pixels(first.sets[1])]); + assert.ok((await inked('#main .rv-panel canvas')).every(n => n > 0), 'both canvases drawn'); + await mode('over'); + assert.deepEqual(await drawn('#main .rv-panel canvas'), ['a:' + pixels(first.sets[0]) + ' b:' + pixels(first.sets[1])]); + await shot('light-1440-masks-overlaid'); + check('1. Review of the masks: the agreement ' + fixed(ag.pairs[0].agreement) + ' and the ' + ag.disputed.length + ' most disputed records (' + listed.map(r => r.join(' ')).join(', ') + ') as the server computed them; side by side two canvases each draw their mask (' + pixels(first.sets[0]) + ' and ' + pixels(first.sets[1]) + ' pixels), overlaid one draws both'); + + // ---- 2. Every other type drawn ------------------------------------------------------------------------------------ + await mode('side'); + const seen = []; + for (const [task, selector] of [['shapes', '#main .rv-panel canvas'], ['depths', '#main .rv-panel canvas'], ['corners', '#main .rv-panel canvas'], ['tops', '#main .rv-panel'], ['boxes3d', '#main .rv-panel'], ['stretches', '#main .rv-panel canvas'], ['tracks', '#main .rv-panel canvas']]) { + await pickTask(task); + const values = await drawn(selector); + assert.equal(values.length, 2, task + ': two panels'); + if (task === 'boxes3d') for (const v of values) assert.match(v, /^[ab]:0\/1$/, 'a 3-D box drawn: ' + v); + else for (const v of values) assert.match(v, /^(frame \d+ )?[ab]:[1-9]/, task + ' drew its set: ' + v); + assert.ok((await inked('#main .rv-panel canvas')).every(n => n > 0), task + ': canvases drawn'); + seen.push(task + ' ' + values.join(' | ')); + await shot('light-1440-' + task); + } + // Tracks: B's identity switch at frame 3, seen with the slider. + const before = await drawn('#main .rv-panel canvas'); + await evaluate(`(() => { const r = document.querySelector('[data-key="rv:frame"]'); r.value = '3'; r.dispatchEvent(new Event('input', { bubbles: true })); return true; })()`); + const after = await drawn('#main .rv-panel canvas'); + assert.deepEqual(before, ['frame 0 a:1=square', 'frame 0 b:1=square']); + assert.deepEqual(after, ['frame 3 a:1=square', 'frame 3 b:1=square-2']); + assert.match(await evaluate(`document.querySelector('#main .rv-figures').innerText`), /Identity switches\s+1/); + check('2. Drawn: ' + seen.join('; ') + '; on the frames the slider moved to frame 3 shows B\'s track renamed (an identity switch, counted 1)'); + + // ---- 3. One record reviewed and kept, then saved ---------------------------------------------------------------- + await pickTask('masks'); + const record = ag.disputed[0].record; + await press(byKey('rv-rec-' + record)); await settled('record'); + await press(byKey('review:decide:keep-b')); await settled('kept B'); + const said = await evaluate(`document.querySelector('#main .rv-kept').textContent`); + assert.match(said, /^Kept: accepted · from masks-b · unsaved/); + assert.match(await evaluate(`document.getElementById('strip').innerText`), /1 annotation unsaved/); + await press(byKey('save:save')); await settled('saved'); + const saved = lines('masks'); + assert.equal(saved.length, 1); assert.equal(saved[0].record, record); assert.equal(saved[0].state, 'accepted'); + assert.equal(saved[0].from.set, 'datasets/masks-b'); assert.equal(saved[0].from.by.name, 'stand-in B'); + assert.ok(fs.existsSync(path.join(folder, 'annotations', 'masks', saved[0].value.file)), 'the mask saved beside it'); + assert.match(await evaluate(`document.querySelector('#main .rv-kept').textContent`), /^Kept: accepted · from masks-b ·(?! unsaved)/); + check('3. ' + record + ' reviewed and B kept ("' + said.trim() + '"); Save wrote annotations/masks.jsonl naming datasets/masks-b and stand-in B, and annotations/masks/' + saved[0].value.file); + + // ---- 4. A kept polygon corrected ------------------------------------------------------------------------------------- + await pickTask('shapes'); + const shape = (await api('annotation_agreement', { task: 'shapes', sets: ['datasets/shapes-a', 'datasets/shapes-b'] })).disputed[0].record; + await press(byKey('rv-rec-' + shape)); await settled('shape'); + await press(byKey('review:decide:keep-a')); await settled('kept A'); + const keptValue = (await api('annotation', { task: 'shapes', record: shape })).annotation.value; + await press(byKey('review:correct:correct')); await settled('correcting'); + const vertex = keptValue[0].points[0]; + const at = await evaluate(`(() => { const c = document.querySelector('#main .rv-panel canvas'); c.scrollIntoView({ block: 'center' }); const r = c.getBoundingClientRect(); return { x: r.left + ${vertex[0]} / 24 * r.width, y: r.top + ${vertex[1]} / 16 * r.height, w: r.width }; })()`); + await dragFrom({ x: at.x, y: at.y }, { x: at.x + at.w / 24 * 2, y: at.y + at.w / 24 * 1 }); await settled('dragged'); + await press(byKey('review:correction:keep-correction')); await settled('correction kept'); + const corrected = (await api('annotation', { task: 'shapes', record: shape })).annotation.value; + assert.deepEqual(corrected[0].points[0], [vertex[0] + 2, vertex[1] + 1], 'the vertex moved by 2 and 1 pixels'); + assert.deepEqual(corrected[0].points.slice(1), keptValue[0].points.slice(1)); + await press(byKey('save:save')); await settled('saved shapes'); + assert.deepEqual(lines('shapes')[0].value[0].points[0], [vertex[0] + 2, vertex[1] + 1]); + check('4. The polygon kept from A on ' + shape + ' corrected: its vertex at ' + vertex.join(', ') + ' dragged to ' + corrected[0].points[0].join(', ') + ', kept and saved'); + + // A kept point object corrected: a rectangle over the right half of the cloud's view (where its top is drawn) removes + // the points shown there. + await pickTask('tops'); + await press(byKey('rv-rec-clouds__p.ply')); await settled('cloud'); + await press(byKey('review:decide:keep-b')); await settled('kept B of the cloud'); + const keptPoints = (await api('annotation', { task: 'tops', record: 'clouds__p.ply' })).annotation.value[0].indices; + await press(byKey('review:correct:correct')); await settled('correcting points'); + const box = await evaluate(`(() => { const c = document.querySelector('#main .rv-panel canvas'); c.scrollIntoView({ block: 'center' }); const r = c.getBoundingClientRect(); return { x: r.left, y: r.top, w: r.width, h: r.height }; })()`); + await dragFrom({ x: box.x + box.w * 0.5, y: box.y + 2 }, { x: box.x + box.w - 2, y: box.y + box.h - 2 }); await settled('points removed'); + assert.match(await evaluate(`document.querySelector('#main .rv-correct').innerText`), /\d+ points? removed so far/); + await press(byKey('review:correction:keep-correction')); await settled('points correction kept'); + const left = (await api('annotation', { task: 'tops', record: 'clouds__p.ply' })).annotation.value; + const remaining = left.length ? left[0].indices : []; + assert.ok(remaining.length < keptPoints.length && remaining.every(i => keptPoints.includes(i)), 'some points removed, none added: ' + JSON.stringify([keptPoints, remaining])); + check('4b. The point object kept from B on clouds__p.ply corrected: a rectangle over the right half of the view removed ' + (keptPoints.length - remaining.length) + ' of its ' + keptPoints.length + ' points, kept as an unsaved edit'); + + // ---- 5. Updates in place ------------------------------------------------------------------------------------------ + await pickTask('masks'); + await evaluate(WATCHER); await evaluate('window.__still.start()'); + const agent = await credential('An annotating agent', ['inspect', 'edit']); + let since = Date.now(); + await api('set_annotation', { task: 'stretches', items: [{ record: 'series__signal.npy', state: 'draft', value: [{ term: 'high', start: 10, end: 20 }] }] }, agent); + await evaluate(`window.dispatchEvent(new Event('focus')); true`); await reading(since, WATCHED, 'focus after the agent'); + since = Date.now(); await evaluate(`window.dispatchEvent(new Event('focus')); true`); await reading(since, WATCHED, 'focus'); + const still = await evaluate('window.__still.stop()'); + for (const id of ['tabs', 'review']) assert.deepEqual([still[id].added, still[id].removed, still[id].attrs, still[id].text], [0, 0, 0, 0], id + ' untouched: ' + JSON.stringify(still[id])); + assert.deepEqual([still.main.added, still.main.removed, still.main.text], [0, 0, 0], 'no node of the main area added, removed or written: ' + JSON.stringify(still.main)); + check('5. With the review of the masks on screen, an agent setting another task\'s annotation (a change, so the tab was read again) and the window regaining focus added, removed and changed no node of the review; the main area only had its busy mark set and cleared while it read (' + still.main.attrs + ' attribute changes on it)'); + + // ---- 6. Light and dark, 1440 and 390 ------------------------------------------------------------------------------ + const views = []; + for (const [w, hgt] of [[1440, 900], [390, 844]]) for (const name of ['light', 'dark']) { + await size(w, hgt); await load(name); + for (const task of ['masks', 'tops', 'tracks']) { + await pickTask(task); await over(name + ' ' + w + ' ' + task); await shot(name + '-' + w + '-' + task); views.push(name + ' ' + w + ' ' + task); + } + } + await size(1440, 900); + check('6. Nothing overflows sideways in ' + views.length + ' views (light and dark, 1440 × 900 and 390 × 844)' + (shots ? '; screenshots in ' + shots : '')); + + assert.deepEqual(errors, [], 'Script errors'); + assert.deepEqual(failures, [], 'Failed requests'); + check('No script error, no failed request'); + fs.writeFileSync(path.join(report, 'receipt.json'), JSON.stringify({ status: 'pass', folder, checks }, null, 2) + '\n'); + console.log('Receipt in ' + report); +})().catch(async error => { + process.exitCode = 1; + console.error(error); if (serverErrors) console.error('Server:', serverErrors.slice(-4000)); + console.error('Script errors:', JSON.stringify(errors)); console.error('Failed requests:', JSON.stringify(failures)); + try { if (evaluate) { await shot('failure'); console.error('Page:', (await evaluate('document.body.innerText')).slice(0, 3000)); } } catch (_) { /* the page is gone */ } + fs.writeFileSync(path.join(report, 'failure.json'), JSON.stringify({ status: 'failed', error: String(error && error.stack || error), checks, errors, failures }, null, 2) + '\n'); +}).finally(async () => { + try { session?.close(); } catch (_) { /* closed */ } + for (const child of children.reverse()) await stop(child); + if (owned) try { dropOwned(...owned); } catch (error) { console.error('Dropping the disposable schemas failed:', error.message); process.exitCode = 1; } + try { execFileSync('chmod', ['-R', 'u+w', temporary]); } catch (_) { /* nothing was made read-only */ } + fs.rmSync(temporary, { recursive: true, force: true }); +}); From feb4649d3fa9734c7bf3901585ce4e61f4015774 Mon Sep 17 00:00:00 2001 From: MrScripty <TheEnvironmentGuy@protonmail.com> Date: Thu, 19 Nov 2026 07:31:02 -0700 Subject: [PATCH 115/131] docs(plan): spec-t6, serving a trained model Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --- docs/plans/training-and-curation/spec-t6.md | 143 ++++++++++++++++++++ 1 file changed, 143 insertions(+) create mode 100644 docs/plans/training-and-curation/spec-t6.md diff --git a/docs/plans/training-and-curation/spec-t6.md b/docs/plans/training-and-curation/spec-t6.md new file mode 100644 index 00000000..96b4f458 --- /dev/null +++ b/docs/plans/training-and-curation/spec-t6.md @@ -0,0 +1,143 @@ +# Implementation spec: serving a trained model + +This is phase 6 of [the training and curation plan](plan.md). It follows that plan's rule: Tuldok supplies a contract (the `serve` declaration and the protocol), the orchestration (start, approval, supervision, stop) and the views; the project writes its own Python. Tuldok's server never imports the project's code: the entry point runs in a separate process, in the recipe's environment, as a build's command does ([spec-m6.md](../definition-first-projects/spec-m6.md) section 4). Who may do what follows [spec-w3.md](../definition-first-projects/spec-w3.md) and `service._allowed`; credentials and sessions are those of [actors.md](../../contracts/actors.md). The page follows [spec-w4.md](../definition-first-projects/spec-w4.md): what changes on its own (a model becoming ready) is set in place, nothing is rebuilt by a timer. Decision 4 of the plan holds: **a served model is reachable only from this machine**; Tuldok opens no new listener, and the endpoint is a route of the server Tuldok already runs on the loopback address. + +**Owner, 2026-11-19:** "We should also have serving trained models as a REST endpoint and autologging." + +**After this phase** a recipe may declare `serve`: the file and functions of the project's own entry point. The owner starts serving a built model from the Train tab or from the model's drawer (an agent asks, and the owner approves, as with a build); Tuldok starts the entry point in the recipe's environment with the model's product, waits for it to load, and answers `POST /api/serve/<model>/predict` behind Tuldok's credentials. Every request's time is logged; a session's timings can be written into a benchmark as per-case values, so the model as served is a benchmark subject like any other. A served model stops when asked, after an idle time, or when Tuldok stops. + +## 1. The declaration + +A recipe may have a `serve` object: + +| Field | Required | Rule | +| --- | --- | --- | +| `module_file` | yes | a code path (as `settings_file`) of a `.py` file: the project's entry point | +| `function` | no | a Python name (`^[A-Za-z_][A-Za-z0-9_]{0,63}$`), default `predict`: called for every request as `function(model, inputs)` | +| `load` | no | a Python name: called once at start as `load(product)` with the product directory; what it returns is `model`. Without `load`, `model` is the product directory (a string) | +| `environment` | no | a reference to `environments/`; default the recipe's `run.environment`. One of the two is required | +| `idle_minutes` | no | integer 1 to 1,440: stop after this long without a request; default the machine's (section 4) | +| `start_seconds` | no | number 1 to 3,600, default 120: how long `load` may take before the start fails | +| `request_seconds` | no | number 0.1 to 600, default 60: how long one request may take before the process is stopped as failed | +| `gpu` | no | boolean, default false: without it `CUDA_VISIBLE_DEVICES` is empty, as for a run | +| `example` | no | an object: the inputs the page's "Try it" starts with | + +`check` adds: `module_file` is a code path that must exist (an error; a warning for earlier work, as other code paths), and ends in `.py`; no environment in `serve` or in `run` is an error. `serve` is not an input: it never makes a model out of date, and building never reads it. + +Example: + +```json +"serve": {"module_file": "serve.py", "load": "load", "function": "predict", + "idle_minutes": 20, "example": {"x": [1, 2, 3]}} +``` + +and the project's `serve.py`: + +```python +import json, os + +def load(product): + with open(os.path.join(product, 'weights.json')) as handle: + return json.load(handle) + +def predict(model, inputs): + return {'y': [model['constant'] + value for value in inputs['x']]} +``` + +**Why a module and two functions, not a command that speaks a protocol.** Both run the project's code in its own process. With a command, every project writes the read loop, the framing, the bounds and the array encoding itself, and one stray `print` in the model's code (or a library's warning on standard output) corrupts the protocol. With a module, Tuldok's small adapter (section 2) owns all of that once, in the standard library: it moves the process's standard output to the log before importing the project's file, speaks the protocol on two private pipes, and decodes and encodes arrays. The project writes two plain functions it can also call from a test or a notebook. It is the simpler contract for projects and the one Tuldok can make safe. A project that needs a server of its own can still write one as a `run` and is outside this phase. + +There is no `tuldok_log` helper for this: the two functions above are the whole skeleton, and the contract document carries the example. + +## 2. The process and the protocol + +**Starting.** The model is the recipe; serving needs its current product (refused `not-built` without one) and the environment's recorded interpreter, checked as a build checks it (refused `not-ready`). The code is a snapshot as for a build (`snapshot.prepare`): the committed code at HEAD, refused `dirty` when tracked files under the code paths have changes, unless the start asks for `scratch` (the code root as it is on disk). The session records the commit, the product's run, the environment and the interpreter. + +Tuldok starts, in the code directory, `<interpreter> -I <Tuldok>/tuldok_project/serve_adapter.py` with the two pipe descriptors, the module file, the function names and the product directory as arguments. `-I` keeps Tuldok's own directory and `PYTHON*` variables out of the process; the adapter puts the code directory first on `sys.path`. The environment is a run's (`PATH`, `HOME`, `USER`, `LOGNAME`, `LANG`, `LC_ALL`, `TZ`), `CUDA_VISIBLE_DEVICES` empty unless `gpu`, `TULDOK_PRODUCT` (the product directory), `TULDOK_SERVE_MODEL` (the recipe) and `TULDOK_RUN_ID=serve-<session>`. Standard input is empty; standard output and standard error go to one log. The process is started in a session of its own with `PR_SET_PDEATHSIG` (it dies with Tuldok), from a thread that lives as long as the process (the signal follows the thread that started it). + +**The protocol,** one UTF-8 JSON object per line on the two private pipes: + +1. The adapter imports the module, calls `load`, and writes `{"ready": true, "load_seconds": s, "numpy": bool, "python": "3.12.3"}`, or `{"ready": false, "error": "<the exception, one line>"}` and exits. No line within `start_seconds`: the start fails and the process is stopped. +2. Per request Tuldok writes `{"id": n, "inputs": {…}}`; the adapter calls `function(model, inputs)` and writes `{"id": n, "ok": true, "outputs": …, "model_seconds": s}` or `{"id": n, "ok": false, "error": "…", "model_seconds": s}` (the model raised: the session stays ready). No answer within `request_seconds`, an answer longer than 16 MiB, one that is not JSON or has another id, or the process gone: the session fails and the process is stopped. +3. When Tuldok closes the request pipe the adapter exits. + +**Arrays.** A value in the inputs or outputs that is an object of exactly the keys `array` (`"float32"`), `shape` (0 to 8 integers ≥ 0) and `base64` (the little-endian float32 values in C order, standard base64, length exactly 4 × the product of the shape) is an array. The adapter gives `predict` such an input as a `numpy.ndarray` of float32 when NumPy is importable in the environment, otherwise as nested lists of floats. Nested lists of numbers are passed as they are. In the outputs, a NumPy array (anything with `shape`, `dtype` and `tobytes`) is cast to float32 and encoded so; a NumPy scalar becomes a number; tuples become lists; anything else that is not JSON is the request's error. Only float32 is encoded; other values are JSON numbers. + +**Bounds.** A request body is at most 8 MiB (1 MiB through the operation, which is the operation contract's bound), JSON nested at most 64 deep, an array at most 2²⁴ elements; an answer at most 16 MiB. At most 8 requests wait for a served model; the ninth is refused `busy`. One request is in the process at a time. + +**Stopping.** The request pipe is closed, the process group gets `SIGTERM`, then `SIGKILL` after 5 seconds, and every process carrying the session's `TULDOK_RUN_ID` is swept (`launcher.stop_strays`). The log keeps the first 4 MiB of output and then only says that more was dropped; the last 4 KiB are kept in memory as the tail shown with a failure. + +## 3. The endpoint and who may use it + +`POST /api/serve/<name>/predict`, where `<name>` is the recipe's name (`recipes/<name>`), on the server Tuldok already runs (`127.0.0.1` by default). The body is `application/json`, `{"inputs": {…}}` and nothing else. The credential is Tuldok's: a bearer credential, or the page's session cookie with a same-origin request, exactly as for `/api/project/<operation>`; no operation contract header is needed, so that any HTTP client can call it. It is answered only in project-folder mode. + +| Answer | When | +| --- | --- | +| 200 `{"model", "session", "outputs", "timing": {"queue_ms", "model_ms", "total_ms"}}` | answered | +| 400 `invalid` | not a JSON object of `inputs` only, a malformed array, too deep | +| 401, 403 | no credential, or one without `inspect` | +| 404 `not-served` | the model is not being served | +| 409 `not-ready` | it is starting or awaiting approval | +| 413 `too-large` | the body is over 8 MiB | +| 422 `predict-failed` | the project's function raised; `error` says what | +| 502 `serve-failed` | the process broke the protocol or died; the session is failed | +| 503 `busy` | eight requests are waiting already | +| 504 `timed-out` | no answer within `request_seconds`; the session is failed | + +**Who.** Calling `predict` needs `inspect`: it changes nothing kept, and the owner's start is the consent to run the code; least privilege lets an owner hand a client a credential that can only read and predict. Starting needs `request`, as a build: the owner's start runs at once, an agent's (with `execute`) waits for the owner's approval for up to an hour. Approving is the owner's. Stopping needs `cancel` (an agent with `cancel` may stop what it asked for or anything served, as it may cancel a build); stopping one that awaits approval declines it. Writing a session's timings into a benchmark needs `edit` (it imports values, as `import_values`). + +## 4. Sessions, limits and the log + +A **session** is one start of one model: `id` (32 hex), `model` (recipe reference), `state` (`awaiting-approval`, `starting`, `ready`, `failed`, `stopped`, `declined`, `expired`), `reason` (why it ended: `asked`, `idle`, `closing`, or the problem), who asked and decided, the times, the commit, scratch, the product's run and directory, the environment and interpreter, the pid, the idle minutes, the request counts, the last request's time and the output's tail. + +**Limits of the machine,** two optional fields of the settings file (`local.py`): `serve_most`, how many models may be starting or ready at once (1 to 16, default 2), and `serve_idle_minutes` (1 to 1,440, default 30), the idle time of a model whose `serve` names none. A start (or an approval) past `serve_most` is refused `limit`, naming the ones served. A model already awaiting approval, starting or ready is refused `already-served`. + +**The log,** under the project's local home, `serving/<session>/`: `session.json` (the session, written again at each change), `output.log` (section 2), and `requests.jsonl`, one line per request answered or refused after it reached the model: `{"n", "at", "ok", "status", "queue_ms", "model_ms", "total_ms", "bytes_in", "bytes_out", "error"?}` — the time waiting for the model, the model's own time (reported by the adapter around `function`), and the total from when Tuldok had read the request to when the answer was ready. At most 100,000 lines a session; past that requests are counted and not written. Sessions are in memory while Tuldok runs; `served` also lists the 50 newest sessions on disk, and a session left starting or ready by a Tuldok that is gone is shown `stopped` with the reason `Tuldok stopped`. + +**Timing summary** of a session (`serve_session`): the count, how many failed, the span from first to last request, the throughput (answered requests per second over that span, null under two requests), and for `queue_ms`, `model_ms` and `total_ms` the mean, p50, p95, p99 and max of the answered requests (percentiles by the linear interpolation of `results.summarise`). + +## 5. The model as served, as a benchmark subject + +`serve_values` turns a session's answered requests into a [values file](../../contracts/project-folder.md#values-files) and imports it, as `import_values` does: `benchmark` and `subject` name a subject of that benchmark (whose `recipe`, when it has one, must be the served model); `metrics` maps metric ids of the benchmark to one of `total_ms`, `model_ms`, `queue_ms`, `total_s`, `model_s`, `queue_s` (default: each metric whose id is one of those names). Each answered request is a case `request-000001`, …; a request the model failed is a value `null` with its error as the reason. The commit is the session's, `produced` the time of its last request. The file is also written to the session's directory. The benchmark then holds per-case values, its summary rows (median, p10, p90, …), the intervals of spec-t3 and its charts; p95, p99 and throughput, which the results format has no column for, stay in the session summary. + +How to use it: a benchmark of its own for serving, say `benchmarks/served-latency` with metrics `total_ms`, `model_ms` and `queue_ms` (`better: lower`, `units: ms`) and a subject per served model naming its recipe. Its `run` may be the project's own load script that calls the endpoint (built like any benchmark, writing its values), or it may be marked `earlier_work: {"rebuild": "no", …}` when its values come only from `serve_values`. The timings depend on what else ran on the machine; the session records when. + +## 6. Operations + +Seven rows of the `project_folder` profile, absent from `catalog` (its digest unchanged): + +| Operation | Who | Mutation | Arguments | Result | +| --- | --- | --- | --- | --- | +| `served` | inspect | no | — | `sessions` (newest first), `servable` (each recipe declaring `serve`: `model`, `title`, `module_file`, `environment`, `built`, `product_run`, `example`, `session`), `most`, `idle_minutes` | +| `serve_session` | inspect | no | `session` | the session, `summary` (section 4), `recent` (the 20 newest request lines) | +| `serve_start` | request | yes | `model`, `scratch` | the session | +| `serve_approve` | owner | yes | `session` | the session | +| `serve_stop` | cancel | yes | `session` | the session | +| `serve_predict` | inspect | no | `model`, `inputs` | `model`, `session`, `outputs`, `timing` | +| `serve_values` | edit | yes | `session`, `benchmark`, `subject`, `metrics` | `benchmark`, `subject`, `values`, `file` | + +They are answered outside the service's lock; those that read the project take it only for that. `serve_predict` never takes it. Refusals carry the codes of section 3 (`not-served`, `not-ready`, `busy`, …) with the statuses there. + +## 7. The page + +- **Train: Served models,** after Build requests: one row per recipe that declares `serve`, with its state (not served, awaiting approval, starting, ready, failed, stopped), its requests and its last session's line; **Serve** (`serve_start`) for a built model not served, **Stop** (two presses) for one starting or ready, **Approve** and **Decline** for one awaiting approval. A row opens the model's serving drawer (`serve:<recipe>`). +- **The serving drawer, and a Serving block in a model's drawer** (Map) for a model that declares `serve`: the state with its reason, the address of the endpoint (`POST /api/serve/<name>/predict`), the controls, the failure's output tail, the timing summary of the session, and **Try it**: a text field holding the inputs as JSON (the declaration's `example`, else `{}`), **Send**, and the answer (outputs, the three times) or the refusal in the server's words. +- **In place.** While a session shown is starting (or awaiting approval), the page asks `served` every second and sets the state mark, the line and the controls of that block in place; when it is ready the controls change from Stop-only to Stop and Try it. Nothing else is read again. Try it does not read the project again. + +## 8. Slices + +| | Slice | Files | +| --- | --- | --- | +| T6a | The declaration, the protocol, the adapter, the supervisor, the operations, the endpoint | `tuldok_project/serving.py`, `serve_protocol.py`, `serve_adapter.py` (new), `schemas/recipe.schema.json`, `check.py`, `local.py`, `operations.py`, `service.py`, `host.py`, `app.py`, `docs/contracts/project-folder.md`; tests `tests/test_tuldok_project_serving.py` (new), the service test's count | +| T6b | The page | `static/project-workspace/serving.js` (new), `tabs.js` (the section and drawer hooks), `screens.js` (the block in a model's drawer), `base.css` or a new `serving.css`, `project-workspace.html`, `app.py` (assets); `tests/browser_project_workspace_serving.cjs` and its fixture (new) | + +## 9. Tests + +**Unit:** the declaration (valid, missing environment, a bad name, a missing module file, not `.py`); the protocol's checks (a request of only `inputs`, a valid and a malformed array, its length against its shape, too deep, too large) and the adapter's own encoding and decoding with and without NumPy, run in a child process; the supervisor with a stand-in module: start to ready, a `load` that raises (failed, with its output's tail), a `load` that hangs (failed after `start_seconds`), a request that raises (422, still ready), a request that hangs (504, failed), idle stop, the limit, stop, and no process left after each test; approval (an agent's start awaits the owner; approve; stop declines); the credential checks through HTTP (none: 401; inspect only: predict yes, start no; owner: start and stop). + +**End to end:** the buildable fixture with `serve.py` and a `serve` block on `fit-a`, built, served through the owner's start, called through `POST /api/serve/fit-a/predict` with a reader credential (nested lists and a base64 array), refused without one; timings in `serve_session`; `serve_values` into a benchmark of served latency, whose summary rows the test checks against its own arithmetic. + +**Browser,** `tests/browser_project_workspace_serving.cjs`: start a served model from its drawer, its state goes to ready in place (the same elements), Try it returns a result, stop it; the Train tab's section; light and dark, 1440 and 390 wide, no sideways overflow, no script error. + +## 10. Out of scope + +A remote address (decision 4); more than one process per model, batching, streaming answers, GPU scheduling between serving and builds (a served model with `gpu` does not take the GPU lock: doubt); authentication other than Tuldok's credentials; serving a dataset or a benchmark; restarting a failed model on its own. From 79e323d879a2118aa8c1b5ada31486fbb8a41139 Mon Sep 17 00:00:00 2001 From: MrScripty <TheEnvironmentGuy@protonmail.com> Date: Thu, 19 Nov 2026 07:37:08 -0700 Subject: [PATCH 116/131] docs(plan): spec-t4 as built Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --- docs/plans/training-and-curation/spec-t4.md | 47 +++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/docs/plans/training-and-curation/spec-t4.md b/docs/plans/training-and-curation/spec-t4.md index 6542390e..69b7023a 100644 --- a/docs/plans/training-and-curation/spec-t4.md +++ b/docs/plans/training-and-curation/spec-t4.md @@ -177,3 +177,50 @@ Updating in place (spec-w4): the disputed list, the record and the decision are ## 10. Out of scope A drawing editor (drawing masks, polygons, keypoints or 3-D boxes by hand); video files as records (frames are an array); agreement for `review` tasks; exporting sets to COCO or other formats; per-term confusion matrices; a set made by a person outside the kept set (a second person's set is an annotator's product like any other); weighting annotators. + +## As built + +What differs from the text above, and what was chosen where it was silent. + +### T4a, the types and the sidecars + +- **The fields a task's values are checked against** (`keypoints`, `skeleton`, `units`, `mask`, `sigma`) are passed as `annotations.task_fields(document)`; `value_problems`, `validate` and `read` take them, and the working copy's fingerprint of a task now includes them (the fingerprint of a task without them is unchanged, so no row is judged again on upgrade). `check` also refuses a skeleton naming a point that is not in `keypoints`. +- **Sidecar names** are the first 16 hexadecimal characters of the SHA-256 and `.png` or `.npy`. The folder reader lists `annotations/<task>/` (names and sizes, nothing read); a file not named that way is an error, as a link or a subdirectory is. The store's listing skips such a directory when its task exists, and never compares it for changes on disk: content-addressed files are never rewritten. +- **The byte formats** are in a new pure module, `annotation_payloads.py` (the step process imports it): a PNG reader for 8- and 16-bit greyscale with every row filter, a PNG writer, runs (`[value, count]`, row by row), and an `.npy` reader and writer (C order, floats and whole numbers; never unpickled). `rle` in a value is checked for its shape in a line, and against the image's size only where the size is known (an edit, a set's line in the step). +- **A test changed:** `test_tuldok_project_annotations.py` used `polygons` as its example of an unknown task; it now uses `video`. +- **Not checked against the record:** a JPEG's size in the step (PNG only); a sound's length in the step (the set reader in Tuldok checks it as before for `segments`; `timeseries` on a sound is checked when kept); `rle` in the folder check (the image's size is not known there). + +### T4b, the step `annotate` + +- **`run` in all four run schemas:** `step` gains `annotate`; `command`, `environment` and `env` are refused only for `import`, `freeze` and `generate`; `annotations` belongs to `freeze` or `annotate`. `check` asks for one input `records`, one task, exactly one of `run.command` and `settings.pumas`, `by` as section 3, `limit` and `options` in their bounds, and that the task annotates the input. +- **The command's process.** Tuldok's step process (`python -m tuldok_project.steps annotate … --command-json …`) runs the command with `subprocess.call`, from the code snapshot, its argv filled and its program found as a build's are (`python` is the environment's interpreter). The command's environment is the run's without `PYTHONSAFEPATH` and `PYTHONPATH` (which make Tuldok's own code importable to the step); a `PYTHONPATH` the run's `env` set is given back to it. Its output goes to the run's log, so its progress lines are the run's. The task file is `<run>/tasks.json` (`{reference, document}`) and `<run>/task.json` (the document) for the command. +- **Resume** takes the latest run of the same reference whose state is neither succeeded, running nor queued and whose definition text is the same, when its output holds `annotations.jsonl`. +- **What is dropped and counted:** a line that is not JSON, not a line of section 3 (unknown keys, no record, no value), a record the input lacks, a value the task does not allow (null included), a sidecar missing, outside `files/` or not of the record's size or point count; a record annotated twice keeps its last valid line. +- **The Pumas route** asks `pumas.suggest` record by record (`by.model` records model, profile and capability); `boxes` and `polygons` on an image are asked of `image_to_text` with an instruction naming the image's size and the terms, and the first JSON list in the answer (a fenced block too) is kept when it is a value of the task. The step fails when each of the first `min(10, records)` is refused. `pumas.routes` now offers this route to `suggest_annotation` and `suggestion_models` as well; the page still asks only for `text`, `class` and `tags` (`test_tuldok_project_pumas.py`'s table of routes was brought up to date). A plan marks an `annotate` with `pumas` blocked when no endpoint is set, as a `generate`. +- **Not verified:** a real Pumas; polygons asked of a model (only boxes against the fake); cancelling a run while its command runs (the launcher stops the process group, as for any run); a set of many records. + +### T4c, agreement + +- As section 5. **Polygon IoU** is exact to the grid (1 px cells up to 128 px across, coarser above). **3-D IoU** clips the footprints with Sutherland–Hodgman. **Greedy matching** above 64 objects a term per side. A pair's figures are pooled over its records: mean IoU weighted by matches, F1 averaged per record. +- **Not measured:** time on large sets. Masks and depth maps are compared pixel by pixel in Python (a second or so per megapixel, by estimate). + +### T4d, the operations + +- **`keep_annotation`** reads the sets outside the service's lock, stages a kept sidecar in a new table `annotation_sidecars` (task, name, bytes), then goes through `_prepare_annotations` and `_set_annotation` as `set_annotation` does: the same checks against the record, one activity row (`"<record> accepted"` or `rejected`). `from` is `{"set", "run", "by"}` for one set, `{"both": [...]}` for two, `{"rejected": [...]}` for none, each cut to the 2 KiB `from` allows (first `by.settings`, then `by`). Keeping both tracks renames the second set's repeated track ids (`-2`, …). +- **Save** writes a task's staged sidecars that its saved lines name, removes from `annotations/<task>/` the content-named files no saved line names (and the directory when empty), and drops the task's staged rows. A revert leaves staged rows until that task's next Save. +- **The kept set** for agreement and review is the working copy's annotations with a value and not rejected, unsaved ones included, stale ones not left out. +- **Operations:** 76 (four new, `keep_annotation` a mutation); the catalog profile is unchanged. + +### T4e, the page + +- **Review** is a mode of the Annotate tab (`Annotate | Review` in the bar, offered when a task has a set made by an annotator); `review.js` (`window.LabReview`) draws it into the tab's own three columns, and `review.css` styles it (base.css is untouched). `annotate.js` gained the nine types (New task asks for keypoints, units and the mask's kind), the mode, and, for the new types in Annotate mode, the kept value in words and drawn read-only over an image or a point cloud. +- **Colours:** A is `--ramp-neg`, B `--ramp-pos`, both `--good`; one set alone is coloured by term. Overlaid, an object with no counterpart of the same term at a box IoU of 0.5 is drawn dashed (a quick greedy test in the page, for marking only); masks are coloured A only, B only and both by pixel; depth maps show A − B on the diverging ramp. +- **inside.js** exports `space` and `turned`; `space` draws `m.lines` (wireframes) and, with `m.select` and `st.selecting`, a dragged rectangle whose shown points it reports (`stride` is accounted for by the caller). +- Each panel carries `data-drawn` (what it drew per set), read by the browser check. +- **Not covered:** keyboard-only correction of polygons (the vertex is chosen and dragged by pointer; Delete needs the canvas focused); a session that may only inspect (the decision buttons are hidden by the usual rule); more than 200 disputed records listed (the list says how many are not); screen readers. + +### T4f, the example and the checks + +- `examples/tiny-project` gained `code/make_scenes.py` (writing `code/scenes`, 3,897 bytes: three 24 × 16 images, two point clouds of 20 and 30 points, 6 frames of 16 × 20, a series of 48 × 2), `code/annotators/standin.py` (one stand-in for mask, polygons, depth, keypoints, points, box3d, timeseries and track), `datasets/scenes`, `annotations/scene-masks` and `scene-objects`, and four annotators. `check` reports nothing. The example's annotators were not built here: its environment `cpu` needs numpy, which this checkout's interpreter lacks; the same stand-in is built by the browser check in an environment of its own. +- **Tests:** `test_tuldok_project_annotation_kinds.py` 15, `test_tuldok_project_annotate_step.py` 6, `test_tuldok_project_annotation_agreement.py` 21; project suite 828 (786 before), agent interface 43 (4 skipped). `tests/browser_project_workspace_annotation_kinds.cjs` passes (steps 1 to 6 of its header, 4b being the point correction; 4b's rectangle happens to take all nine points of the kept object, so a partial removal is not shown). +- **Regression checks:** `browser_project_workspace.cjs` passes (24). `browser_project_workspace_inside.cjs`, `_annotate.cjs` and `_endpoint.cjs` fail here exactly as they do on the base of this branch (`7a0b3665`, run from an archive of it): at 1000 px the page overflows sideways by 65 px (`page` 65, the main area 0), and `_annotate.cjs` also still expects the tab list without phase 3's Compare. With that one expectation updated (in a throwaway copy), `_annotate.cjs` passes the same nine steps before the same overflow on both trees; `_inside.cjs` and `_endpoint.cjs` pass six steps on both. The overflow is not this phase's and was not fixed here. From 5cb6c5294048ad3c4f4e7bbfa6d0271cce053702 Mon Sep 17 00:00:00 2001 From: MrScripty <TheEnvironmentGuy@protonmail.com> Date: Thu, 19 Nov 2026 07:41:21 -0700 Subject: [PATCH 117/131] feat(project): a recipe may declare serve, and the machine's serving limits Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --- tuldok_project/check.py | 26 +++++++++++ tuldok_project/local.py | 19 +++++++- tuldok_project/schemas/recipe.schema.json | 55 +++++++++++++++++++++++ tuldok_project/store.py | 1 + 4 files changed, 99 insertions(+), 2 deletions(-) diff --git a/tuldok_project/check.py b/tuldok_project/check.py index 5469246a..ea612903 100644 --- a/tuldok_project/check.py +++ b/tuldok_project/check.py @@ -76,6 +76,7 @@ def add(severity, path, pointer, message): check_references(definitions, add) check_steps(definitions, add) + check_serve(definitions, add) check_charts(definitions, unsound, add) check_cycles(definitions, add) check_map(project, definitions, add) @@ -494,6 +495,9 @@ def sources(holder, *prefix): source = settings.get('source') if run.get('step') == 'import' and isinstance(settings, dict) else None if isinstance(source, str) and source and not source.startswith('/'): yield '/run/settings/source', source # relative to the code root, read from the commit + serve = document.get('serve') + if isinstance(serve, dict) and 'module_file' in serve: + yield '/serve/module_file', serve['module_file'] # the entry point a served model runs (spec-t6.md) if 'config_file' in document: yield '/config_file', document['config_file'] yield from sources(document) @@ -567,6 +571,28 @@ def check_references(definitions, add): f'{use.target} declares no output named {use.output!r}; use one of its run.outputs or declare it there.') +def check_serve(definitions, add): + """Report a recipe's serve (spec-t6.md section 1): a .py module file, and an environment that exists.""" + for definition in definitions.values(): + document = definition.document + serve = document.get('serve') if isinstance(document, dict) else None + if definition.kind != 'recipe' or not isinstance(serve, dict): + continue + module_file = serve.get('module_file') + if isinstance(module_file, str) and not module_file.endswith('.py'): + add('error', definition.path, '/serve/module_file', + f'The module file {module_file!r} must be a Python file ending in .py.') + run = document.get('run') if isinstance(document.get('run'), dict) else {} + environment = serve.get('environment', run.get('environment')) + if not isinstance(environment, str): + add('error', definition.path, '/serve', + 'A served model runs in an environment; name one in serve.environment or run.environment.') + elif ('environment' in serve and (documents.parse_reference(environment) or ('',))[0] == 'environments' + and environment not in definitions): + add('error', definition.path, '/serve/environment', + f'{environment} does not exist; add {environment}.json or fix the reference.') + + def _sound_benchmark(chart, definitions, unsound): """Return the chart's benchmark document, or None when it is missing or has its own errors.""" target = definitions.get(chart.get('benchmark')) if isinstance(chart.get('benchmark'), str) else None diff --git a/tuldok_project/local.py b/tuldok_project/local.py index 4b052449..2ecf9360 100644 --- a/tuldok_project/local.py +++ b/tuldok_project/local.py @@ -15,7 +15,8 @@ It may hold the machine's embedder too (docs/plans/training-and-curation/ spec-t5.md section 2): embedding_model and embedding_profile, the served alias used in place of EmbeddingGemma 2 when a definition names none, and -embedding_prefix, the text put before each record's text. +embedding_prefix, the text put before each record's text. serve_most and +serve_idle_minutes bound the models this machine serves (spec-t6.md section 4). Working out a path never creates anything; a directory is made only when a caller asks for it with create=True, or by set_project_home. """ @@ -34,7 +35,9 @@ SETTINGS_FORMAT = 'tuldok_settings_v1' SETTINGS_LIMIT = 64 * 1024 SETTINGS_FIELDS = ('format', 'project_home', 'pumas_endpoint', 'embedding_model', 'embedding_profile', - 'embedding_prefix') + 'embedding_prefix', 'serve_most', 'serve_idle_minutes') +# The serving limits of the machine (docs/plans/training-and-curation/spec-t6.md section 4): (least, most, default). +SERVE_LIMITS = {'serve_most': (1, 16, 2), 'serve_idle_minutes': (1, 1440, 30)} EMBEDDER_LIMITS = {'embedding_model': 256, 'embedding_profile': 128, 'embedding_prefix': 1000} ENDPOINT_LIMIT = 2048 # characters of pumas_endpoint ENVIRONMENTS = 'environments' @@ -83,9 +86,21 @@ def read_settings(): 'embedding_prefix')): raise SettingsError(f'The settings file {path} is not valid: its {key} must be a string of ' f'{"0" if key == "embedding_prefix" else "1"} to {most} characters.') + for key, (least, most, _default) in SERVE_LIMITS.items(): + value = settings.get(key) + if key in settings and not (isinstance(value, int) and not isinstance(value, bool) and least <= value <= most): + raise SettingsError(f'The settings file {path} is not valid: its {key} must be an integer from {least} ' + f'to {most}.') return settings +def serve_settings(): + """{most, idle_minutes}: how many models this machine serves at once and their default idle time.""" + settings = read_settings() + return {'most': settings.get('serve_most', SERVE_LIMITS['serve_most'][2]), + 'idle_minutes': settings.get('serve_idle_minutes', SERVE_LIMITS['serve_idle_minutes'][2])} + + def embedder_settings(): """{model, profile, prefix} of the machine's embedder: each None when the settings file names none.""" settings = read_settings() diff --git a/tuldok_project/schemas/recipe.schema.json b/tuldok_project/schemas/recipe.schema.json index 272b4916..d646d058 100644 --- a/tuldok_project/schemas/recipe.schema.json +++ b/tuldok_project/schemas/recipe.schema.json @@ -98,6 +98,61 @@ } } } + }, + "serve": { + "type": "object", + "additionalProperties": false, + "required": [ + "module_file" + ], + "description": "How Tuldok serves this recipe's model (docs/plans/training-and-curation/spec-t6.md section 1).", + "properties": { + "backend": { + "enum": [ + "local" + ], + "description": "how the model is served: local, the project's own entry point run by Tuldok" + }, + "module_file": { + "$ref": "#/$defs/path" + }, + "function": { + "type": "string", + "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,63}$", + "description": "a Python name: letters, digits and '_', not starting with a digit, at most 64 characters" + }, + "load": { + "type": "string", + "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,63}$", + "description": "a Python name: letters, digits and '_', not starting with a digit, at most 64 characters" + }, + "environment": { + "type": "string", + "pattern": "^environments/[a-z0-9][a-z0-9._-]{0,119}$", + "description": "a reference to an environment, such as environments/<name>" + }, + "idle_minutes": { + "type": "integer", + "minimum": 1, + "maximum": 1440 + }, + "start_seconds": { + "type": "number", + "minimum": 1, + "maximum": 3600 + }, + "request_seconds": { + "type": "number", + "minimum": 0.1, + "maximum": 600 + }, + "gpu": { + "type": "boolean" + }, + "example": { + "type": "object" + } + } } }, "if": { diff --git a/tuldok_project/store.py b/tuldok_project/store.py index 8fed5499..ddd87bdc 100644 --- a/tuldok_project/store.py +++ b/tuldok_project/store.py @@ -290,6 +290,7 @@ def add(severity, path, pointer, message): problems.append(Problem(severity, path, pointer, message)) check.check_references(merged, add) + check.check_serve(merged, add) check.check_charts(merged, set(unsound), add) check.check_cycles(merged, add) check.check_map(project, merged, add) From 5195a73d5511b5ad5a3556a94d534fcf5fbd4933 Mon Sep 17 00:00:00 2001 From: MrScripty <TheEnvironmentGuy@protonmail.com> Date: Thu, 19 Nov 2026 07:41:21 -0700 Subject: [PATCH 118/131] feat(project): the serve adapter, its protocol, and the supervisor of served models Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --- tuldok_project/serve_adapter.py | 216 ++++++++++ tuldok_project/serve_protocol.py | 172 ++++++++ tuldok_project/serving.py | 665 +++++++++++++++++++++++++++++++ 3 files changed, 1053 insertions(+) create mode 100644 tuldok_project/serve_adapter.py create mode 100644 tuldok_project/serve_protocol.py create mode 100644 tuldok_project/serving.py diff --git a/tuldok_project/serve_adapter.py b/tuldok_project/serve_adapter.py new file mode 100644 index 00000000..3e95df9e --- /dev/null +++ b/tuldok_project/serve_adapter.py @@ -0,0 +1,216 @@ +"""The adapter Tuldok runs in a project's environment to serve its model (docs/plans/training-and-curation/spec-t6.md). + +Run as a file by the environment's interpreter with -I, never imported by +Tuldok's server: `python -I serve_adapter.py --requests FD --answers FD --code +DIR --module FILE --function NAME [--load NAME] --product DIR`. It moves the +process's standard output to standard error before anything of the project is +imported, so a stray print goes to the log and never into the protocol; it +imports the project's module from its file, calls load(product) once, writes +the ready line, then answers one request line at a time on the private pipes +until the request pipe closes (section 2). Arrays are decoded to NumPy float32 +arrays when NumPy is importable, else to nested lists, and NumPy values in the +outputs are encoded. Standard library only; Python 3.8 or later. +""" +import argparse +import base64 +import importlib.util +import json +import math +import os +import platform +import struct +import sys +import time + +ANSWER_LIMIT = 16 * 1024 * 1024 # bytes of one answer line (serve_protocol.ANSWER_LIMIT) +REQUEST_LIMIT = 9 * 1024 * 1024 # bytes of one request line, with room around an 8 MiB body +ERROR_CHARACTERS = 2000 +ARRAY_KEYS = ('array', 'base64', 'shape') +_LITTLE = sys.byteorder == 'little' + +try: + import numpy # noqa: F401 (only when the environment has it) +except ImportError: # pragma: no cover - depends on the environment + numpy = None + + +def _one_line(error): + text = f'{type(error).__name__}: {error}'.replace('\r', ' ').replace('\n', ' ') + return text[:ERROR_CHARACTERS] + + +# ------------------------------------------------------------------ arrays + +def _is_array(value): + return isinstance(value, dict) and tuple(sorted(value)) == ARRAY_KEYS and value.get('array') == 'float32' + + +def _nest(flat, shape): + if not shape: + return flat[0] + if len(shape) == 1: + return list(flat) + step = len(flat) // shape[0] if shape[0] else 0 + return [_nest(flat[i * step:(i + 1) * step], shape[1:]) for i in range(shape[0])] + + +def decode_array(value, *, use_numpy=True): + """An encoded array (already checked by Tuldok) as a NumPy float32 array, or nested lists of floats.""" + shape = [int(n) for n in value['shape']] + raw = base64.b64decode(value['base64'], validate=True) + count = 1 + for n in shape: + count *= n + if len(raw) != 4 * count: + raise ValueError(f'the array of shape {shape} needs {4 * count} bytes, not {len(raw)}') + if numpy is not None and use_numpy: + return numpy.frombuffer(raw, dtype='<f4').reshape(shape).astype(numpy.float32) + flat = list(struct.unpack('<%df' % count, raw)) + return _nest(flat, shape) + + +def decode(value, *, use_numpy=True): + """The inputs as predict sees them: every encoded array decoded.""" + if _is_array(value): + return decode_array(value, use_numpy=use_numpy) + if isinstance(value, dict): + return {key: decode(item, use_numpy=use_numpy) for key, item in value.items()} + if isinstance(value, list): + return [decode(item, use_numpy=use_numpy) for item in value] + return value + + +def encode_array(shape, values): + """{array, shape, base64} of float32 values (a flat sequence of numbers) in C order.""" + raw = struct.pack('<%df' % len(values), *values) + return {'array': 'float32', 'shape': list(shape), 'base64': base64.b64encode(raw).decode('ascii')} + + +def encode(value): + """The outputs as JSON: NumPy arrays encoded as float32, NumPy scalars as numbers, tuples as lists.""" + if value is None or isinstance(value, (bool, str)): + return value + if isinstance(value, int): + return value + if isinstance(value, float): + if not math.isfinite(value): + raise ValueError('an output is not a finite number') + return value + if isinstance(value, dict): + out = {} + for key, item in value.items(): + if not isinstance(key, str): + raise ValueError(f'an output key is {type(key).__name__}, not a string') + out[key] = encode(item) + return out + if isinstance(value, (list, tuple)): + return [encode(item) for item in value] + if hasattr(value, 'shape') and hasattr(value, 'dtype') and hasattr(value, 'tobytes'): + if numpy is not None and getattr(value, 'ndim', None) == 0: + return encode(value.item()) + array = value.astype('<f4') + raw = array.tobytes(order='C') + return {'array': 'float32', 'shape': [int(n) for n in value.shape], + 'base64': base64.b64encode(raw).decode('ascii')} + if hasattr(value, 'item') and callable(value.item): # a NumPy scalar + return encode(value.item()) + raise ValueError(f'an output of type {type(value).__name__} is not JSON') + + +# ---------------------------------------------------------------- the loop + +def _write(handle, message): + data = json.dumps(message, allow_nan=False, separators=(',', ':')).encode('utf-8') + b'\n' + if len(data) > ANSWER_LIMIT: + raise ValueError(f'the answer is {len(data)} bytes, more than {ANSWER_LIMIT}') + handle.write(data) + handle.flush() + + +def _load_module(code, module_file): + path = os.path.join(code, module_file) + name = '_tuldok_served_' + os.path.splitext(os.path.basename(module_file))[0].replace('-', '_') + spec = importlib.util.spec_from_file_location(name, path) + if spec is None or spec.loader is None: + raise ImportError(f'{module_file} cannot be imported') + module = importlib.util.module_from_spec(spec) + sys.modules[name] = module + spec.loader.exec_module(module) + return module + + +def _function(module, name, module_file): + found = getattr(module, name, None) + if not callable(found): + raise AttributeError(f'{module_file} has no function {name}') + return found + + +def answer(predict, model, line): + """The answer to one request line (bytes): {id, ok, outputs | error, model_seconds}.""" + started = time.perf_counter() + try: + request = json.loads(line) + number = request.get('id') + except ValueError as error: + return {'id': None, 'ok': False, 'error': _one_line(error), 'model_seconds': 0.0} + try: + outputs = encode(predict(model, decode(request.get('inputs', {})))) + return {'id': number, 'ok': True, 'outputs': outputs, 'model_seconds': time.perf_counter() - started} + except Exception as error: # the model's failure is the request's, not the process's + return {'id': number, 'ok': False, 'error': _one_line(error), + 'model_seconds': time.perf_counter() - started} + + +def main(argv=None): + parser = argparse.ArgumentParser() + parser.add_argument('--requests', type=int, required=True) + parser.add_argument('--answers', type=int, required=True) + parser.add_argument('--code', required=True) + parser.add_argument('--module', required=True) + parser.add_argument('--function', required=True) + parser.add_argument('--load', default='') + parser.add_argument('--product', required=True) + arguments = parser.parse_args(argv) + sys.dont_write_bytecode = True + requests = os.fdopen(arguments.requests, 'rb', buffering=0) + answers = os.fdopen(arguments.answers, 'wb') + os.dup2(2, 1) # standard output joins the log from here on; the protocol is on the private pipes only + sys.stdout = sys.stderr + code = os.path.abspath(arguments.code) + sys.path.insert(0, code) + started = time.perf_counter() + try: + module = _load_module(code, arguments.module) + predict = _function(module, arguments.function, arguments.module) + model = (_function(module, arguments.load, arguments.module)(arguments.product) + if arguments.load else arguments.product) + except BaseException as error: + import traceback + traceback.print_exc() + _write(answers, {'ready': False, 'error': _one_line(error)}) + return 1 + _write(answers, {'ready': True, 'load_seconds': time.perf_counter() - started, 'numpy': numpy is not None, + 'python': platform.python_version()}) + reader = requests + pending = b'' + while True: + chunk = reader.read(1 << 20) + if not chunk: + return 0 + pending += chunk + if len(pending) > REQUEST_LIMIT and b'\n' not in pending: + print('A request line was longer than the adapter accepts; stopping.', file=sys.stderr) + return 2 + while b'\n' in pending: + line, pending = pending.split(b'\n', 1) + reply = answer(predict, model, line) + try: + _write(answers, reply) + except ValueError as error: + _write(answers, {'id': reply.get('id'), 'ok': False, 'error': _one_line(error), + 'model_seconds': reply.get('model_seconds')}) + + +if __name__ == '__main__': + sys.exit(main()) diff --git a/tuldok_project/serve_protocol.py b/tuldok_project/serve_protocol.py new file mode 100644 index 00000000..d9660e65 --- /dev/null +++ b/tuldok_project/serve_protocol.py @@ -0,0 +1,172 @@ +"""What Tuldok's server checks of a served model's requests and answers, and the summary of their times. + +Owns sections 2 to 4 of docs/plans/training-and-curation/spec-t6.md on +Tuldok's side; serve_adapter.py is the other side, in the project's +environment. check_request takes a predict body (the decoded JSON) and +returns its inputs, or raises ServeError invalid: an object of exactly +`inputs`, an object; JSON nested at most DEPTH deep; every encoded array of +the right keys, shape and base64 length, within ARRAY_ELEMENTS. Arrays are +checked, never decoded into numbers here: the server passes the inputs on as +they came. check_answer does the same for an answer line from the adapter. +summary computes a session's timing summary from its request lines. Standard +library only. +""" +import base64 +import binascii +import json +import math + +REQUEST_LIMIT = 8 * 1024 * 1024 # bytes of a predict body over HTTP +ANSWER_LIMIT = 16 * 1024 * 1024 # bytes of one answer line from the adapter +DEPTH = 64 +ARRAY_ELEMENTS = 1 << 24 +ARRAY_DIMENSIONS = 8 +ARRAY_KEYS = ('array', 'base64', 'shape') +TIMES = ('queue_ms', 'model_ms', 'total_ms') +MEASURES = ('total_ms', 'model_ms', 'queue_ms', 'total_s', 'model_s', 'queue_s') +# The HTTP status of each refusal of a predict (spec-t6.md section 3). +STATUS = {'invalid': 400, 'forbidden': 403, 'not-found': 404, 'not-served': 404, 'not-ready': 409, + 'too-large': 413, 'predict-failed': 422, 'serve-failed': 502, 'busy': 503, 'timed-out': 504} + + +class ServeError(Exception): + """A refusal of a serving call; code is a key of STATUS or a ProjectError code.""" + + def __init__(self, message, code): + super().__init__(message) + self.code = code + + +def is_array(value): + """Whether value is written as an encoded array: an object of exactly array, shape and base64.""" + return isinstance(value, dict) and tuple(sorted(value)) == ARRAY_KEYS + + +def check_array(value, where='inputs'): + """Raise ServeError invalid unless value is a well-formed float32 array; return its element count.""" + if value.get('array') != 'float32': + raise ServeError(f'{where}: an array must say "array": "float32"; no other type is encoded.', 'invalid') + shape = value.get('shape') + if (not isinstance(shape, list) or len(shape) > ARRAY_DIMENSIONS + or not all(isinstance(n, int) and not isinstance(n, bool) and n >= 0 for n in shape)): + raise ServeError(f'{where}: an array\'s shape must be 0 to {ARRAY_DIMENSIONS} integers of 0 or more.', + 'invalid') + count = 1 + for n in shape: + count *= n + if count > ARRAY_ELEMENTS: + raise ServeError(f'{where}: an array may hold at most {ARRAY_ELEMENTS} values; this one {count}.', 'invalid') + text = value.get('base64') + if not isinstance(text, str): + raise ServeError(f'{where}: an array\'s base64 must be a string.', 'invalid') + try: + raw = base64.b64decode(text, validate=True) + except (binascii.Error, ValueError): + raise ServeError(f'{where}: an array\'s base64 is not standard base64.', 'invalid') from None + if len(raw) != 4 * count: + raise ServeError(f'{where}: an array of shape {shape} needs {4 * count} bytes; its base64 holds {len(raw)}.', + 'invalid') + return count + + +def _walk(value, where, depth): + if depth > DEPTH: + raise ServeError(f'{where}: the JSON is nested more than {DEPTH} deep.', 'invalid') + if is_array(value): + check_array(value, where) + elif isinstance(value, dict): + for key, item in value.items(): + _walk(item, f'{where}.{key}', depth + 1) + elif isinstance(value, list): + for index, item in enumerate(value): + _walk(item, f'{where}[{index}]', depth + 1) + elif isinstance(value, float) and not math.isfinite(value): + raise ServeError(f'{where}: a number is not finite.', 'invalid') + + +def check_request(body): + """The inputs of a predict body (the decoded JSON object), or ServeError invalid.""" + if not isinstance(body, dict) or set(body) != {'inputs'} or not isinstance(body['inputs'], dict): + raise ServeError('Send a JSON object {"inputs": {...}} and nothing else.', 'invalid') + _walk(body['inputs'], 'inputs', 1) + return body['inputs'] + + +def check_answer(line, number): + """An answer line (bytes, its newline removed) for request number, as an object; ServeError serve-failed.""" + try: + answer = json.loads(line.decode('utf-8'), parse_constant=_no_constant) + except (UnicodeDecodeError, ValueError): + raise ServeError('The served process answered with a line that is not JSON.', 'serve-failed') from None + if not isinstance(answer, dict) or answer.get('id') != number or not isinstance(answer.get('ok'), bool): + raise ServeError('The served process answered with something other than the answer to the request.', + 'serve-failed') + seconds = answer.get('model_seconds') + if not (isinstance(seconds, (int, float)) and not isinstance(seconds, bool) and math.isfinite(seconds) + and seconds >= 0): + raise ServeError('The served process did not say how long the model took.', 'serve-failed') + if answer['ok']: + if 'outputs' not in answer: + raise ServeError('The served process answered without outputs.', 'serve-failed') + try: + _walk(answer['outputs'], 'outputs', 1) + except ServeError as error: + raise ServeError(f'The served process answered with outputs Tuldok cannot pass on ({error}).', + 'serve-failed') from None + elif not isinstance(answer.get('error'), str): + raise ServeError('The served process failed a request without saying why.', 'serve-failed') + return answer + + +def check_ready(line): + """The ready line (bytes) as an object {ready, ...}; ServeError serve-failed when it is not one.""" + try: + ready = json.loads(line.decode('utf-8'), parse_constant=_no_constant) + except (UnicodeDecodeError, ValueError): + ready = None + if not isinstance(ready, dict) or not isinstance(ready.get('ready'), bool): + raise ServeError('The served process did not start with the ready line.', 'serve-failed') + return ready + + +def _no_constant(name): + raise ValueError(f'{name} is not JSON') + + +# ---------------------------------------------------------------- summary + +def percentile(ordered, p): + """The value at position p × (n − 1) of ordered values, interpolated linearly (results.summarise).""" + if not ordered: + return None + position = p * (len(ordered) - 1) + low = math.floor(position) + high = min(low + 1, len(ordered) - 1) + return ordered[low] + (position - low) * (ordered[high] - ordered[low]) + + +def summary(lines): + """The timing summary of a session's request lines (spec-t6.md section 4).""" + answered = [line for line in lines if line.get('ok')] + result = {'count': len(lines), 'answered': len(answered), 'failed': len(lines) - len(answered), + 'span_seconds': None, 'throughput_per_second': None} + stamps = sorted(line['at'] for line in answered if isinstance(line.get('at'), (int, float))) + if len(stamps) >= 2: + span = stamps[-1] - stamps[0] + result['span_seconds'] = span + result['throughput_per_second'] = (len(stamps) - 1) / span if span > 0 else None + for name in TIMES: + values = sorted(line[name] for line in answered if isinstance(line.get(name), (int, float))) + result[name] = None if not values else { + 'mean': math.fsum(values) / len(values), 'p50': percentile(values, 0.5), 'p95': percentile(values, 0.95), + 'p99': percentile(values, 0.99), 'max': values[-1]} + return result + + +def measure(line, name): + """One request line's value of a measure of MEASURES (milliseconds or seconds).""" + base, unit = name.rsplit('_', 1) + value = line.get(base + '_ms') + if not isinstance(value, (int, float)): + return None + return value if unit == 'ms' else value / 1000.0 diff --git a/tuldok_project/serving.py b/tuldok_project/serving.py new file mode 100644 index 00000000..1348974b --- /dev/null +++ b/tuldok_project/serving.py @@ -0,0 +1,665 @@ +"""Serving a trained model: sessions, their processes, their requests and their log. + +Owns sections 2 to 4 of docs/plans/training-and-curation/spec-t6.md. A +Supervisor holds the sessions of one project while Tuldok runs: a session is +created awaiting approval (an agent's start) or starting (the owner's), and is +started from a Launch, everything its process needs, which service.py works +out with the project open (the product, the environment's interpreter, the +code snapshot). How a session is run is its backend's: BACKENDS maps the +`backend` of a recipe's `serve` to an object with start(session, launch), +stop(session) and exchange(session, inputs, deadline); "local" (LocalBackend) +is the one built, the project's own entry point run by serve_adapter.py in +its environment. The Supervisor owns everything that does not depend on the +backend: the states, the limit of the machine, the approval's expiry, the idle +stop, the queue of one model's requests, the timings and the files under +<local home>/serving/<session>/. + +LocalBackend starts the adapter from a thread that lives as long as the +process (PR_SET_PDEATHSIG follows the thread that forked), in a session of +its own, with two private pipes for the protocol and one pipe for its output, +which another thread writes to output.log (bounded) and keeps the tail of. +Stopping closes the request pipe, sends SIGTERM to the process group, SIGKILL +after STOP_GRACE, and sweeps every process carrying the session's run id +(launcher.stop_strays). Nothing here imports the project's code. +""" +import collections +import dataclasses +import datetime +import errno +import fcntl +import json +import os +import select +import signal +import subprocess +import threading +import time +import uuid + +from . import builds, launcher, local, serve_protocol +from .serve_protocol import ServeError + +SERVING = 'serving' # <local home>/serving/<session>/ +ADAPTER = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'serve_adapter.py') +STATES = ('awaiting-approval', 'starting', 'ready', 'failed', 'stopped', 'declined', 'expired') +LIVE = ('starting', 'ready') +OPEN = ('awaiting-approval',) + LIVE +APPROVAL_SECONDS = 3600.0 # how long an agent's start waits for the owner +QUEUE_MOST = 8 # requests waiting for one served model +STOP_GRACE = 5.0 # seconds between SIGTERM and SIGKILL +WATCH_SECONDS = 1.0 # how often a session's thread looks at idleness +LOG_LIMIT = 4 * 1024 * 1024 # bytes of output.log +TAIL_BYTES = 4096 # bytes of output kept for a failure +REQUEST_LINES = 100_000 # lines of requests.jsonl a session +RECENT = 20 # request lines in serve_session +LISTED = 50 # sessions on disk listed by served +DEFAULTS = {'start_seconds': 120.0, 'request_seconds': 60.0} +BACKEND = 'local' + + +@dataclasses.dataclass(frozen=True) +class Launch: + """What a session's process needs, worked out with the project open (service.py).""" + model: str + serve: dict + product: str + product_run: str + environment: str + interpreter: str + code_root: str + commit: str + scratch: bool + + +def _now(): + return datetime.datetime.now(datetime.timezone.utc) + + +def _text(moment): + return None if moment is None else moment.isoformat() + + +def _who(actor): + return {key: actor.get(key) for key in ('actor_id', 'kind', 'label')} if actor else None + + +class Session: + """One start of one model; its fields are what to_dict answers, the rest is its process's.""" + + def __init__(self, model, title, *, actor, scratch, backend, idle_minutes, directory): + self.id = uuid.uuid4().hex + self.model, self.title, self.backend = model, title, backend + self.state, self.reason, self.problem = 'awaiting-approval', None, None + self.requested_by, self.requested_at = _who(actor), _now() + self.decided_by = None + self.expires_at = self.requested_at + datetime.timedelta(seconds=APPROVAL_SECONDS) + self.started_at = self.ready_at = self.ended_at = self.last_request_at = None + self.scratch, self.idle_minutes = scratch, idle_minutes + self.launch = None + self.pid = None + self.requests = self.failed_requests = self.unlogged = 0 + self.ready = {} # the adapter's ready line + self.directory = os.path.join(directory, self.id) + self.slot = threading.Lock() # one request in the process at a time + self.waiting = 0 + self.last_activity = time.monotonic() + self.in_flight = False + self.number = 0 + self.tail = collections.deque() # (bytes) of the output's last TAIL_BYTES + self.tail_size = 0 + self.exited = threading.Event() + self.stopping = threading.Event() # set by a stop; a process started after it is stopped at once + self.runtime_lock = threading.Lock() + self.runtime = {} # the backend's own: process, pipes, threads + + def output_tail(self): + return b''.join(self.tail).decode('utf-8', 'replace') + + def to_dict(self): + launch = self.launch + return {'id': self.id, 'model': self.model, 'title': self.title, 'backend': self.backend, + 'state': self.state, 'reason': self.reason, 'problem': self.problem, + 'requested_by': self.requested_by, 'requested_at': _text(self.requested_at), + 'decided_by': self.decided_by, + 'expires_at': _text(self.expires_at) if self.state == 'awaiting-approval' else None, + 'started_at': _text(self.started_at), 'ready_at': _text(self.ready_at), + 'ended_at': _text(self.ended_at), 'last_request_at': _text(self.last_request_at), + 'commit': launch.commit if launch else None, 'scratch': self.scratch, + 'product_run': launch.product_run if launch else None, + 'product': launch.product if launch else None, + 'environment': launch.environment if launch else None, + 'interpreter': launch.interpreter if launch else None, + 'pid': self.pid if self.state in LIVE else None, 'idle_minutes': self.idle_minutes, + 'requests': self.requests, 'failed_requests': self.failed_requests, + 'load_seconds': self.ready.get('load_seconds'), 'python': self.ready.get('python'), + 'numpy': self.ready.get('numpy'), 'output_tail': self.output_tail()} + + +# ----------------------------------------------------------------- local backend + +def _read_line(session, fd, deadline, limit): + """One line (without its newline) from fd by deadline (monotonic); ServeError timed-out or serve-failed.""" + buffer = session.runtime.setdefault('buffer', bytearray()) + while True: + cut = buffer.find(b'\n') + if cut >= 0: + line = bytes(buffer[:cut]) + del buffer[:cut + 1] + return line + if len(buffer) > limit: + raise ServeError(f'The served process wrote a line longer than {limit} bytes.', 'serve-failed') + left = deadline - time.monotonic() + if left <= 0: + raise ServeError('The served process did not answer in time.', 'timed-out') + ready, _, _ = select.select([fd], [], [], min(left, 1.0)) + if not ready: + continue + try: + chunk = os.read(fd, 1 << 20) + except BlockingIOError: + continue + except OSError as error: + raise ServeError(f'The served process could not be read: {error.strerror}.', 'serve-failed') from None + if not chunk: + raise ServeError('The served process ended.', 'serve-failed') + buffer += chunk + + +def _write_all(fd, data, deadline): + view = memoryview(data) + while view: + left = deadline - time.monotonic() + if left <= 0: + raise ServeError('The served process did not take the request in time.', 'timed-out') + _, ready, _ = select.select([], [fd], [], min(left, 1.0)) + if not ready: + continue + try: + written = os.write(fd, view) + except BlockingIOError: + continue + except OSError as error: + if error.errno == errno.EPIPE: + raise ServeError('The served process ended.', 'serve-failed') from None + raise ServeError(f'The served process could not be written to: {error.strerror}.', + 'serve-failed') from None + view = view[written:] + + +def _close(fd): + if fd is not None: + try: + os.close(fd) + except OSError: + pass + + +class LocalBackend: + """The project's own serve entry point, run by serve_adapter.py in its environment (spec-t6.md section 2).""" + name = 'local' + + def start(self, session, launch, on_ready, on_exit): + """Start the process from a thread of its own; on_ready(ready line or ServeError), on_exit(status).""" + thread = threading.Thread(target=self._run, args=(session, launch, on_ready, on_exit), + name=f'tuldok-serve-{session.id[:8]}', daemon=True) + session.runtime['thread'] = thread + thread.start() + + def _run(self, session, launch, on_ready, on_exit): + requests_read, requests_write = os.pipe() + answers_read, answers_write = os.pipe() + output_read, output_write = os.pipe() + serve = launch.serve + argv = [launch.interpreter, '-I', ADAPTER, '--requests', str(requests_read), '--answers', str(answers_write), + '--code', launch.code_root, '--module', serve['module_file'], + '--function', serve.get('function', 'predict'), '--product', launch.product] + if serve.get('load'): + argv += ['--load', serve['load']] + env = {key: os.environ[key] for key in builds.PASSED_VARIABLES if key in os.environ} + env.update(PYTHONDONTWRITEBYTECODE='1', PYTHONUNBUFFERED='1', TULDOK_PRODUCT=launch.product, + TULDOK_SERVE_MODEL=launch.model, **{launcher.RUN_ID_VARIABLE: 'serve-' + session.id}) + if not serve.get('gpu'): + env['CUDA_VISIBLE_DEVICES'] = '' + elif 'CUDA_VISIBLE_DEVICES' in os.environ: + env['CUDA_VISIBLE_DEVICES'] = os.environ['CUDA_VISIBLE_DEVICES'] + try: + process = subprocess.Popen(argv, cwd=launch.code_root, env=env, stdin=subprocess.DEVNULL, + stdout=output_write, stderr=output_write, + pass_fds=(requests_read, answers_write), start_new_session=True, + preexec_fn=launcher._child_setup(os.getpid()), close_fds=True) + except OSError as error: + for fd in (requests_read, requests_write, answers_read, answers_write, output_read, output_write): + _close(fd) + on_ready(ServeError(f'The served process could not be started: {error.strerror or error}.', + 'serve-failed')) + session.exited.set() + on_exit(None) + return + for fd in (requests_read, answers_write, output_write): + _close(fd) + fcntl.fcntl(requests_write, fcntl.F_SETFL, fcntl.fcntl(requests_write, fcntl.F_GETFL) | os.O_NONBLOCK) + session.pid = process.pid + with session.runtime_lock: + session.runtime.update(process=process, requests=requests_write, answers=answers_read) + stopping = session.stopping.is_set() + if stopping: # stopped while it was being started + _close(session.runtime.pop('requests', None)) + try: + os.killpg(process.pid, signal.SIGKILL) + except (ProcessLookupError, PermissionError): + pass + logger = threading.Thread(target=self._log, args=(session, output_read), + name=f'tuldok-serve-log-{session.id[:8]}', daemon=True) + logger.start() + deadline = time.monotonic() + float(serve.get('start_seconds', DEFAULTS['start_seconds'])) + try: + line = _read_line(session, answers_read, deadline, serve_protocol.ANSWER_LIMIT) + ready = serve_protocol.check_ready(line) + except ServeError as error: + if error.code == 'timed-out': + error = ServeError(f'The model did not load within {serve.get("start_seconds", 120)} seconds.', + 'timed-out') + ready = error + on_ready(ready) + # This thread started the process, so it stays until the process is gone (spec-t6.md section 2). + while True: + try: + status = process.wait(timeout=WATCH_SECONDS) + break + except subprocess.TimeoutExpired: + on_exit(...) # a tick: the supervisor looks at idleness + _close(session.runtime.pop('requests', None)) + logger.join(5) + _close(answers_read) + session.exited.set() + on_exit(status) + + def _log(self, session, fd): + path = os.path.join(session.directory, 'output.log') + written = 0 + with open(path, 'ab') as log: + while True: + try: + chunk = os.read(fd, 65536) + except OSError: + break + if not chunk: + break + session.tail.append(chunk) + session.tail_size += len(chunk) + while session.tail_size - len(session.tail[0]) >= TAIL_BYTES: + session.tail_size -= len(session.tail.popleft()) + if written < LOG_LIMIT: + part = chunk[:LOG_LIMIT - written] + log.write(part) + log.flush() + written += len(part) + if written >= LOG_LIMIT: + log.write(b'\n[Tuldok: the output past 4 MiB is not kept.]\n') + log.flush() + _close(fd) + if session.tail_size > TAIL_BYTES and session.tail: + joined = b''.join(session.tail)[-TAIL_BYTES:] + session.tail.clear() + session.tail.append(joined) + session.tail_size = len(joined) + + def exchange(self, session, inputs, deadline): + """Send one request and read its answer (serve_protocol.check_answer), by deadline.""" + session.number += 1 + number = session.number + requests = session.runtime.get('requests') + if requests is None: + raise ServeError('The served process has ended.', 'serve-failed') + line = json.dumps({'id': number, 'inputs': inputs}, allow_nan=False, separators=(',', ':')).encode() + b'\n' + _write_all(requests, line, deadline) + return serve_protocol.check_answer( + _read_line(session, session.runtime['answers'], deadline, serve_protocol.ANSWER_LIMIT), number) + + def stop(self, session): + """Close the request pipe, SIGTERM the group, SIGKILL after STOP_GRACE, sweep the run id.""" + with session.runtime_lock: + session.stopping.set() + _close(session.runtime.pop('requests', None)) + process = session.runtime.get('process') + if process is not None: + if not session.exited.wait(0.5): + for signum, wait in ((signal.SIGTERM, STOP_GRACE), (signal.SIGKILL, STOP_GRACE)): + try: + os.killpg(process.pid, signum) + except (ProcessLookupError, PermissionError): + pass + if session.exited.wait(wait): + break + try: + launcher.stop_strays('serve-' + session.id) + except Exception: # a sweep that cannot finish leaves nothing worse than before + pass + thread = session.runtime.get('thread') + if thread is not None and thread is not threading.current_thread(): + thread.join(STOP_GRACE) + + +BACKENDS = {'local': LocalBackend()} + + +# --------------------------------------------------------------------- supervisor + +class Supervisor: + """The sessions of one project while Tuldok runs; see the module docstring.""" + + def __init__(self, project_id): + self.project_id = project_id + self._lock = threading.Lock() + self._sessions = {} # id -> Session + self._closing = False + + # ---------------------------------------------------------------- paths + + def directory(self, create=False): + path = os.path.join(local.home(self.project_id, create=create), SERVING) + if create: + os.makedirs(path, exist_ok=True) + return path + + def _write(self, session): + """session.json, written again through a temporary file.""" + os.makedirs(session.directory, exist_ok=True) + path = os.path.join(session.directory, 'session.json') + temporary = path + '.tmp' + with open(temporary, 'w', encoding='utf-8') as handle: + json.dump(session.to_dict(), handle, indent=1) + os.replace(temporary, path) + + # ---------------------------------------------------------------- reading + + def _expire(self, session): + if session.state == 'awaiting-approval' and _now() >= session.expires_at: + session.state, session.reason, session.ended_at = 'expired', 'nobody approved it within an hour', _now() + self._write(session) + + def get(self, session_id): + """The session as a dict, from memory or from its file; ServeError not-found.""" + with self._lock: + session = self._sessions.get(session_id) + if session is not None: + self._expire(session) + return session.to_dict() + found = self._on_disk(session_id) + if found is None: + raise ServeError(f'There is no serving session {session_id}.', 'not-found') + return found + + def _on_disk(self, session_id): + if not (isinstance(session_id, str) and len(session_id) == 32 and all(c in '0123456789abcdef' + for c in session_id)): + return None + try: + with open(os.path.join(self.directory(), session_id, 'session.json'), encoding='utf-8') as handle: + found = json.load(handle) + except (OSError, ValueError): + return None + if not isinstance(found, dict): + return None + if found.get('state') in OPEN: # left by a Tuldok that is gone + found.update(state='stopped', reason='Tuldok stopped', pid=None, expires_at=None) + return found + + def sessions(self): + """Every session in memory and the newest LISTED on disk, newest first.""" + with self._lock: + for session in self._sessions.values(): + self._expire(session) + held = {session.id: session.to_dict() for session in self._sessions.values()} + try: + entries = sorted(os.scandir(self.directory()), key=lambda e: e.stat().st_mtime, reverse=True) + except OSError: + entries = [] + for entry in entries[:LISTED]: + if entry.name not in held: + found = self._on_disk(entry.name) + if found is not None: + held[entry.name] = found + return sorted(held.values(), key=lambda s: s.get('requested_at') or '', reverse=True) + + def requests(self, session_id, most=None): + """The request lines of a session (all, or the newest most).""" + path = os.path.join(self.directory(), session_id, 'requests.jsonl') + lines = [] + try: + with open(path, encoding='utf-8') as handle: + for text in handle: + try: + lines.append(json.loads(text)) + except ValueError: + continue + except OSError: + return [] + return lines[-most:] if most else lines + + # ---------------------------------------------------------------- starting + + def open_session(self, model, model_title, *, actor, scratch, backend, idle_minutes, most, awaiting): + """A new session of model, awaiting approval or not; ServeError already-served or limit.""" + with self._lock: + if self._closing: + raise ServeError('Tuldok is stopping.', 'unavailable') + for session in self._sessions.values(): + self._expire(session) + if session.model == model and session.state in OPEN: + raise ServeError(f'{model} is {session.state} already (session {session.id}).', + 'already-served') + if not awaiting: + self._check_limit(most) + session = Session(model, model_title, actor=actor, scratch=scratch, backend=backend, + idle_minutes=idle_minutes, directory=self.directory(create=True)) + self._sessions[session.id] = session + if not awaiting: + session.state, session.decided_by = 'starting', _who(actor) + self._write(session) + return session.to_dict() + + def _check_limit(self, most): + live = [s for s in self._sessions.values() if s.state in LIVE] + if len(live) >= most: + raise ServeError(f'This machine serves at most {most} models at once; ' + + ', '.join(s.model for s in live) + ' are served. Stop one first.', 'limit') + + def awaiting(self, session_id): + """The model and scratch of a session awaiting approval; ServeError not-found or not-awaiting.""" + with self._lock: + session = self._sessions.get(session_id) + if session is None: + raise ServeError(f'There is no serving session {session_id} awaiting approval.', 'not-found') + self._expire(session) + if session.state != 'awaiting-approval': + raise ServeError(f'Session {session_id} is {session.state}, not awaiting approval.', 'not-awaiting') + return session.model, session.scratch + + def approve(self, session_id, actor, most): + with self._lock: + session = self._sessions.get(session_id) + if session is None or session.state != 'awaiting-approval': + raise ServeError(f'Session {session_id} is not awaiting approval.', 'not-awaiting') + self._check_limit(most) + session.state, session.decided_by = 'starting', _who(actor) + self._write(session) + + def fail_start(self, session_id, problem): + """A starting session whose launch could not be worked out: failed, with the problem.""" + with self._lock: + session = self._sessions[session_id] + session.state, session.problem, session.reason, session.ended_at = 'failed', problem, problem, _now() + self._write(session) + return session.to_dict() + + def launch(self, session_id, launch): + """Start the process of a starting session; returns the session as it is then (starting).""" + with self._lock: + session = self._sessions[session_id] + if session.state != 'starting': # stopped while its launch was worked out + return session.to_dict() + session.launch, session.started_at = launch, _now() + backend = BACKENDS[session.backend] + self._write(session) + backend.start(session, launch, lambda ready: self._on_ready(session, ready), + lambda status: self._on_exit(session, status)) + return session.to_dict() + + def _on_ready(self, session, ready): + with self._lock: + if session.state != 'starting': + return + if isinstance(ready, ServeError) or not ready.get('ready'): + problem = str(ready) if isinstance(ready, ServeError) else ('The model did not load: ' + + str(ready.get('error') or '?')) + session.state, session.problem, session.reason, session.ended_at = 'failed', problem, problem, _now() + self._write(session) + stop = True + else: + session.ready = ready + session.state, session.ready_at = 'ready', _now() + session.last_activity = time.monotonic() + self._write(session) + stop = False + if stop: + threading.Thread(target=BACKENDS[session.backend].stop, args=(session,), daemon=True).start() + + def _on_exit(self, session, status): + if status is ...: # a tick of the process's thread: is it idle? + with self._lock: + idle = (session.state == 'ready' and not session.in_flight and session.waiting == 0 + and time.monotonic() - session.last_activity >= 60.0 * session.idle_minutes) + if idle: + threading.Thread(target=self.stop, args=(session.id, None, 'idle'), daemon=True).start() + return + with self._lock: + if session.state in LIVE: + word = 'signal ' + str(-status) if isinstance(status, int) and status < 0 else f'exit status {status}' + problem = f'The served process ended ({word}).' + session.state, session.problem, session.reason, session.ended_at = 'failed', problem, problem, _now() + self._write(session) + + # ---------------------------------------------------------------- stopping + + def stop(self, session_id, actor, reason='asked'): + """Stop a session: decline one awaiting approval, stop one starting or ready; the session after.""" + with self._lock: + session = self._sessions.get(session_id) + if session is None: + raise ServeError(f'There is no serving session {session_id} that runs.', 'not-found') + self._expire(session) + if session.state == 'awaiting-approval': + session.state, session.decided_by, session.ended_at = 'declined', _who(actor), _now() + session.reason = 'declined by ' + ((actor or {}).get('label') or (actor or {}).get('kind') or '?') + self._write(session) + return session.to_dict() + if session.state not in LIVE: + raise ServeError(f'Session {session_id} is {session.state}; there is nothing to stop.', 'not-running') + session.state, session.reason, session.ended_at = 'stopped', reason, _now() + self._write(session) + if session.launch is not None: + BACKENDS[session.backend].stop(session) + with self._lock: + self._write(session) + return session.to_dict() + + def close(self): + """Stop every session (reason closing); called when the service closes.""" + with self._lock: + self._closing = True + live = [s for s in self._sessions.values() if s.state in OPEN] + for session in live: + try: + self.stop(session.id, None, 'closing') + except ServeError: + pass + for session in list(self._sessions.values()): # a failed one may still be being stopped + if session.launch is not None and not session.exited.is_set(): + BACKENDS[session.backend].stop(session) + + # ---------------------------------------------------------------- requests + + def predict(self, model, inputs, received, size=None): + """Pass inputs to the served model; {model, session, outputs, timing}. + + received is time.perf_counter() when Tuldok had read the request; size its bytes (computed when None). + """ + if size is None: + size = len(json.dumps(inputs, separators=(',', ':'))) + with self._lock: + found = [s for s in self._sessions.values() if s.model == model and s.state in OPEN] + if not found: + raise ServeError(f'{model} is not being served.', 'not-served') + session = found[0] + if session.state != 'ready': + raise ServeError(f'{model} is {session.state}, not ready yet.', 'not-ready') + if session.waiting >= QUEUE_MOST: + raise ServeError(f'{QUEUE_MOST} requests are waiting for {model} already; try again.', 'busy') + session.waiting += 1 + try: + session.slot.acquire() + finally: + with self._lock: + session.waiting -= 1 + try: + queued = time.perf_counter() + with self._lock: + if session.state != 'ready': + raise ServeError(f'{model} stopped while the request waited.', 'not-served') + session.in_flight = True + seconds = float(session.launch.serve.get('request_seconds', DEFAULTS['request_seconds'])) + failure = None + answer = None + try: + answer = BACKENDS[session.backend].exchange(session, inputs, time.monotonic() + seconds) + except ServeError as error: + failure = error + done = time.perf_counter() + timing = {'queue_ms': 1000 * (queued - received), + 'model_ms': 1000 * answer['model_seconds'] if answer else None, + 'total_ms': 1000 * (done - received)} + ok = failure is None and answer['ok'] + self._log(session, ok, timing, size, answer, failure) + if failure is not None: + self._broken(session, failure, seconds) + raise failure + if not answer['ok']: + raise ServeError(answer['error'], 'predict-failed') + return {'model': model, 'session': session.id, 'outputs': answer['outputs'], 'timing': timing} + finally: + with self._lock: + session.in_flight = False + session.last_activity = time.monotonic() + session.slot.release() + + def _broken(self, session, failure, seconds): + problem = (f'A request took more than {seconds:g} seconds; the process was stopped.' + if failure.code == 'timed-out' else str(failure)) + with self._lock: + if session.state not in LIVE: + return + session.state, session.problem, session.reason, session.ended_at = 'failed', problem, problem, _now() + self._write(session) + BACKENDS[session.backend].stop(session) + + def _log(self, session, ok, timing, size, answer, failure): + with self._lock: + session.requests += 1 + session.failed_requests += 0 if ok else 1 + session.last_request_at = _now() + if session.requests > REQUEST_LINES: + session.unlogged += 1 + return + line = {'n': session.requests, 'at': time.time(), 'ok': ok, + 'status': 200 if ok else serve_protocol.STATUS.get( + failure.code if failure else 'predict-failed', 500), + **timing, + 'bytes_in': size, + 'bytes_out': len(json.dumps(answer.get('outputs'), separators=(',', ':'))) + if answer and answer.get('ok') else 0} + if not ok: + line['error'] = (str(failure) if failure else answer.get('error', ''))[:400] + with open(os.path.join(session.directory, 'requests.jsonl'), 'a', encoding='utf-8') as handle: + handle.write(json.dumps(line, separators=(',', ':')) + '\n') + self._write(session) From 813e08412ea2b93bf1502ec218ab718c4d5345bd Mon Sep 17 00:00:00 2001 From: MrScripty <TheEnvironmentGuy@protonmail.com> Date: Thu, 19 Nov 2026 07:41:21 -0700 Subject: [PATCH 119/131] feat(project): serving operations and POST /api/serve/<model>/predict behind Tuldok's credentials Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --- app.py | 32 ++ docs/contracts/project-folder.md | 75 +++- tests/test_tuldok_project_service.py | 13 +- tests/test_tuldok_project_serving.py | 598 +++++++++++++++++++++++++++ tuldok_project/host.py | 18 +- tuldok_project/operations.py | 34 +- tuldok_project/service.py | 241 ++++++++++- 7 files changed, 996 insertions(+), 15 deletions(-) create mode 100644 tests/test_tuldok_project_serving.py diff --git a/app.py b/app.py index 55ebb887..793ead00 100644 --- a/app.py +++ b/app.py @@ -47,12 +47,15 @@ from image_sources import ImageSources, Conflict, now, metadata, validate_annotation, CORNERS, VISIBILITY, SPLITS import tempfile import threading +import time import zipfile from datetime import datetime, timezone from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer from pathlib import Path from urllib.parse import urlsplit, parse_qs +from tuldok_project import serve_protocol + from PIL import Image, ImageOps ROOT = Path(__file__).resolve().parent @@ -416,6 +419,33 @@ def _project_folder_post(self, path): result, status = {'error': 'The operation failed: ' + type(error).__name__ + '.', 'code': 'internal'}, 500 return self.reply(result, status) + def _serve_post(self, path): + # A served model (docs/plans/training-and-curation/spec-t6.md, section 3): POST + # /api/serve/<name>/predict, a JSON object of inputs, behind the bound credential; no contract header. + parts = path.split('/') + if (len(parts) != 5 or parts[4] != 'predict' or not re.fullmatch('[a-z0-9][a-z0-9._-]{0,119}', parts[3]) + or urlsplit(self.path).query): + return self.reply({'error': 'Use POST /api/serve/<model>/predict.', 'code': 'not-found'}, 404) + lengths = self.headers.get_all('Content-Length', []) + if (self.headers.get_all('Transfer-Encoding', []) or len(lengths) != 1 + or not re.fullmatch('[0-9]{1,10}', lengths[0]) or int(lengths[0]) == 0): + return self.reply({'error': 'Send the body with one Content-Length.', 'code': 'invalid'}, 400) + if int(lengths[0]) > serve_protocol.REQUEST_LIMIT: + return self.reply({'error': 'A request to a served model may be at most 8 MiB.', + 'code': 'too-large'}, 413) + if self.headers.get_content_type() != 'application/json': + return self.reply({'error': 'Send a JSON object {"inputs": {...}}.', 'code': 'invalid'}, 400) + raw = self.rfile.read(int(lengths[0])) + observe_request_bytes(observer, getattr(self, '_observation', None), len(raw)) + try: + body = agent_api.decode(raw) + except agent_api.AgentAPIError: + return self.reply({'error': 'The body is not JSON.', 'code': 'invalid'}, 400) + self._observe_dispatch() + received = time.perf_counter() + status, answer = dataset.predict(parts[3], body, received=received, size=len(raw)) + return self.reply(answer, status) + def _project_folder_file(self): # The bytes of a product's file (spec-d1.md, section 5), for whoever may call an inspect operation. try: @@ -495,6 +525,8 @@ def _handle_POST(self): except access.AccessError as error: dataset.access.denial(error, 'http.post', path) raise + if path.startswith('/api/serve/') and getattr(dataset, 'project_folder_mode', False): + return self._serve_post(path) if path.startswith('/api/project/') or (getattr(dataset, 'project_folder_mode', False) and not path.startswith('/api/access/')): return self._project_folder_post(path) diff --git a/docs/contracts/project-folder.md b/docs/contracts/project-folder.md index 46ccdfa7..14e94552 100644 --- a/docs/contracts/project-folder.md +++ b/docs/contracts/project-folder.md @@ -522,6 +522,7 @@ A recipe trains a model; its product is weights. | `change` | no | `training-policy`, `architecture`, `refinement` or `component`: the kind of change this model makes | | `derived_from` | no | reference to another recipe in `recipes/`: the model this one was branched from. Never the recipe itself, and following `derived_from` never comes back to where it started | | `compared_with` | no | at most 50 objects, each `recipe` (reference to another recipe, each once in the list), `explanation` (1 to 2,000 characters) and `excerpt` (optional, at most 2,000 characters); no other field | +| `serve` | no | how Tuldok serves the model: `module_file` (a code path of a `.py` file, required), `function` (default `predict`), `load`, `backend` (`local`, the default and only one), `environment` (default `run.environment`; one of the two is required), `idle_minutes` (1 to 1,440), `start_seconds` (1 to 3,600), `request_seconds` (0.1 to 600), `gpu`, `example` (an object); see [Serving a model](#serving-a-model). Not an input: it never makes the model out of date | The label `short`, when a recipe has it, is the text of its node on the map (at most 16 characters are shown). `derived_from` and `compared_with` say how @@ -2364,6 +2365,13 @@ and result keys of each operation are in its contract. | `cancel_build` | cancel | Cancel a build request, stopping its build when it is running. | | `cancel_run` | cancel | Ask a queued or running run to stop. | | `stop_run` | cancel | Kill what a run whose build is gone left running, and mark it unknown. | +| `served` | inspect | List the serving sessions on this machine, newest first, the recipes that declare serve with whether each is built, and the machine's limits. | +| `serve_session` | inspect | Read one serving session with its timing summary and its newest requests' lines. | +| `serve_start` | request | Start serving a built recipe's model from its serve entry point: the owner's start runs at once, an agent's waits for the owner's approval. | +| `serve_approve` | owner | Approve a serving session awaiting approval, which starts it. | +| `serve_stop` | cancel | Stop a served model, or decline a serving session awaiting approval. | +| `serve_predict` | inspect | Pass inputs to a served model and read its outputs and the time taken; arrays are objects of array float32, shape and base64. | +| `serve_values` | edit | Import a serving session's request times as per-case values of a benchmark subject, one case per request. | | `annotation_tasks` | inspect | List the annotation tasks, each with its dataset, current product and counts of its records by the state of their annotations. | | `annotated_records` | inspect | Read one page of the records of a task's dataset with their annotations, optionally in one state or of one kind, with the counts. | | `annotation` | inspect | Read one record's annotation under a task as it now is and as it is in the file, whether it is unsaved or stale, and the hash of the record's content. | @@ -3102,6 +3110,69 @@ value of the task, the model's words quoted. The record is read and the endpoint asked outside the service's lock; an answer not given within 300 s is given up. +### Serving a model + +A recipe that declares `serve` can be served while Tuldok runs: the owner's +`serve_start` (or an agent's, once the owner approves it with `serve_approve`) +starts the project's own entry point in the environment, with the recipe's +current product, from the committed code at HEAD (or the code as it is with +`scratch`), and `POST /api/serve/<name>/predict` answers through it. The +entry point is two functions of the project: + +```python +def load(product): # once, with the product directory; what it returns is model + ... +def predict(model, inputs): # per request: inputs is the request's object, outputs any JSON + ... +``` + +Tuldok runs them in a separate process through its adapter +(`tuldok_project/serve_adapter.py`, run with `-I` by the environment's +interpreter); Tuldok's server never imports the project's code. Standard +output and standard error go to the session's log. The process gets +`TULDOK_PRODUCT`, `TULDOK_SERVE_MODEL` and `TULDOK_RUN_ID=serve-<session>`, +and `CUDA_VISIBLE_DEVICES` empty unless `gpu`. + +**The endpoint.** `POST /api/serve/<name>/predict` on Tuldok's own address +(loopback by default; nothing new listens), with Tuldok's credential (a bearer +credential, or the page's session with a same-origin request) allowed to +`inspect`; no contract header. The body is `application/json`, +`{"inputs": {...}}`, at most 8 MiB, nested at most 64 deep. An **array** is an +object of exactly `array` (`"float32"`), `shape` (0 to 8 integers) and +`base64` (the little-endian float32 values in C order, 4 × the product of the +shape bytes, at most 2²⁴ values); `predict` receives it as a NumPy float32 +array when NumPy is in the environment, else as nested lists. Nested lists of +numbers pass as they are. In the outputs, NumPy arrays are encoded as arrays +and NumPy scalars as numbers. The answer is +`{"model", "session", "outputs", "timing": {"queue_ms", "model_ms", "total_ms"}}`; +refusals are 400 `invalid`, 401 or 403, 404 `not-served`, 409 `not-ready`, +413 `too-large`, 422 `predict-failed` (the function raised), 502 `serve-failed`, +503 `busy` (eight requests already wait), 504 `timed-out` (the session fails). +One request is in the process at a time. + +**Sessions.** States `awaiting-approval` (an agent's start; expires after an +hour), `starting`, `ready`, `failed`, `stopped`, `declined`, `expired`. A +session stops when asked (`serve_stop`), after `idle_minutes` without a +request, or when Tuldok stops; it fails when `load` raises or takes more than +`start_seconds`, when a request takes more than `request_seconds`, or when the +process ends. At most `serve_most` models are starting or ready on the +machine (settings file, default 2), one session a model. Under the local home, +`serving/<session>/` holds `session.json`, `output.log` (its first 4 MiB) and +`requests.jsonl`: per request `n`, `at` (Unix time), `ok`, `status`, +`queue_ms`, `model_ms`, `total_ms`, `bytes_in`, `bytes_out` and `error`. +`serve_session` adds the timing summary: count, answered, failed, span, +throughput, and the mean, p50, p95, p99 and max of each time. + +**As a benchmark subject.** `serve_values` writes a session's requests as a +values file (one case `request-000001`, … per request; a failed request is a +`null` value with its error as the reason) for a subject of a benchmark whose +`recipe` is the served one, filling the metrics named in `metrics` (metric id +to `total_ms`, `model_ms`, `queue_ms`, `total_s`, `model_s` or `queue_s`; +by default each metric whose id is one of these), and imports it as +`import_values` does. A benchmark of served latency may be one whose run is +the project's own load script, or one marked `earlier_work.rebuild` `no` +whose values come only from sessions. + ## The Pumas endpoint Generation, suggestions and embeddings go through a Pumas endpoint, reached by HTTP @@ -3177,7 +3248,9 @@ set by `set_endpoint` (see [The Pumas endpoint](#the-pumas-endpoint)). `embeddin characters), `embedding_profile` (1 to 128) and `embedding_prefix` (at most 1,000) are optional and set by `set_embedder`: the embedder of an `embed` that names none, in place of EmbeddingGemma 2, and the text put before each -record's text. The file is read only when +record's text. `serve_most` (1 to 16, default 2) and `serve_idle_minutes` +(1 to 1,440, default 30) are optional: how many models this machine serves at +once, and the idle time of a served model whose `serve` names none. The file is read only when the environment variable does not decide. A settings file that cannot be read or is not valid stops the command with a message naming the file and the fault, exit status 2, and stops the app's start-up; Tuldok never falls back to diff --git a/tests/test_tuldok_project_service.py b/tests/test_tuldok_project_service.py index 377f7232..7a60e195 100644 --- a/tests/test_tuldok_project_service.py +++ b/tests/test_tuldok_project_service.py @@ -48,7 +48,7 @@ class Table(unittest.TestCase): def test_every_operation_is_declared_once(self): names = [operation.name for operation in operations.OPERATIONS] - self.assertEqual(len(names), 79) # the rows of spec-m7.md section 2, of section 2 of spec-w1.md and spec-w3.md, of section 3 of spec-d1.md and spec-d2.md, of section 5 of spec-d4.md, of sections 2 and 4 of spec-d5.md, of section 2 of spec-d6.md, of section 3 of spec-t2.md, of section 4 of spec-t1.md, and of sections 2 to 4 of spec-t3.md and spec-t5.md (7) + self.assertEqual(len(names), 86) # spec-t6.md section 6 (7), and the rows of spec-m7.md section 2, of section 2 of spec-w1.md and spec-w3.md, of section 3 of spec-d1.md and spec-d2.md, of section 5 of spec-d4.md, of sections 2 and 4 of spec-d5.md, of section 2 of spec-d6.md, of section 3 of spec-t2.md, of section 4 of spec-t1.md, and of sections 2 to 4 of spec-t3.md and spec-t5.md (7) self.assertEqual(len(set(names)), len(names)) for name in REQUEST_OPERATIONS: self.assertIsNotNone(operations.by_name(name)) @@ -80,10 +80,11 @@ def test_mutations_and_owner_rows(self): 'import_values', 'check_environment', 'connect_environment', 'disconnect_environment', 'request_build', 'approve_build', 'decline_build', 'cancel_build', 'cancel_run', 'stop_run', 'set_annotation', 'revert_annotations', - 'set_endpoint', 'set_embedder'}) + 'set_endpoint', 'set_embedder', 'serve_start', 'serve_approve', 'serve_stop', + 'serve_values'}) owner = {operation.name for operation in operations.OPERATIONS if operation.who == 'owner'} self.assertEqual(owner, {'connect_environment', 'disconnect_environment', 'approve_build', 'decline_build', - 'set_endpoint', 'find_endpoints', 'set_embedder'}) + 'set_endpoint', 'find_endpoints', 'set_embedder', 'serve_approve'}) def test_error_status(self): self.assertEqual([operations.error_status(code) for code in @@ -222,6 +223,8 @@ def test_every_read(self): 'training_samples': {'run': run_id}, 'training_sample': {'run': run_id, 'index': 0}, 'model_compare': {'recipes': ['recipes/fit-a', 'recipes/fit-b']}, 'benchmark_axes': {'benchmark': 'score'}, 'intervals': {'benchmark': 'benchmarks/score'}, + 'served': {}, 'serve_session': {'session': 'a' * 32}, + 'serve_predict': {'model': 'fit-a', 'inputs': {}}, 'annotation_tasks': {}, 'annotated_records': {'task': 'none-here'}, 'annotation': {'task': 'none-here', 'record': 'r1'}, 'endpoint': {}, 'find_endpoints': {}, 'suggestion_models': {'task': 'none-here'}, @@ -271,6 +274,10 @@ def test_every_read(self): if operation.name.startswith('embedding_'): # no embeddings here; test_tuldok_project_curation self.assertEqual(self.refused(operation.name, arguments[operation.name]).code, 'not-found') continue + if operation.name in ('serve_session', 'serve_predict'): # nothing served; test_tuldok_project_serving + self.assertIn(self.refused(operation.name, arguments[operation.name]).code, + ('not-found', 'not-served')) + continue if operation.name == 'note': # this fixture has no notes; read in test_tuldok_project_workspace self.assertEqual(self.refused(operation.name, arguments['note']).code, 'not-found') continue diff --git a/tests/test_tuldok_project_serving.py b/tests/test_tuldok_project_serving.py new file mode 100644 index 00000000..4aa66700 --- /dev/null +++ b/tests/test_tuldok_project_serving.py @@ -0,0 +1,598 @@ +"""Serving a trained model (docs/plans/training-and-curation/spec-t6.md). + +The declaration, the protocol's checks, the adapter's encoding and the +supervisor need no database: the supervisor tests serve a stand-in module +(pure Python, written by the test) with the interpreter running the tests, +under a temporary TULDOK_PROJECT_HOME, and check after each test that no +process of a session is left. The end-to-end tests need a database and run +only when TULDOK_DATABASE_URL names a disposable cluster: they start from +test_tuldok_project_http.Served (a Git-committed copy of the buildable fixture +served by the app on port 0, an owner, an agent and a reader credential), add +serve.py and a serve block to fit-a, build it with the fixture's stand-in +script, serve it and call it through POST /api/serve/fit-a/predict. No GPU, +no NumPy, nothing downloaded. +""" +import base64 +import http.client +import json +import math +import os +from pathlib import Path +import struct +import subprocess +import sys +import tempfile +import textwrap +import time +import types +import unittest +from unittest import mock +from urllib.error import HTTPError +from urllib.request import Request, urlopen + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) +sys.path.insert(0, str(Path(__file__).resolve().parent)) + +from tuldok_project import check, documents, launcher, local, serve_adapter, serve_protocol, serving # noqa: E402 +from tuldok_project.serve_protocol import ServeError # noqa: E402 +import test_tuldok_project_builds as builds_base # noqa: E402 +import test_tuldok_project_http as http_base # noqa: E402 + +OWNER = {'actor_id': 'owner-1', 'kind': 'owner', 'label': 'The owner', 'scopes': ['inspect', 'approve-execution']} +AGENT = {'actor_id': 'agent-1', 'kind': 'agent', 'label': 'An agent', 'scopes': ['inspect', 'execute', 'cancel']} + +STAND_IN = textwrap.dedent(''' + """A stand-in model: y = constant + x; it can be told to fail or hang through its inputs.""" + import json, os, time + + def load(product): + settings = json.load(open(os.path.join(product, 'weights.json'))) + if settings.get('fail'): + raise RuntimeError('the weights are broken on purpose') + if settings.get('hang'): + time.sleep(60) + print('loaded the stand-in') + return settings + + def flat(value): + if hasattr(value, 'ravel'): + return [float(v) for v in value.ravel()] + if isinstance(value, list): + return [v for item in value for v in flat(item)] + return [float(value)] + + def predict(model, inputs): + print('a stray print from predict') + if inputs.get('fail'): + raise ValueError('asked to fail') + if inputs.get('hang'): + time.sleep(60) + if 'a' in inputs: + return {'sum': sum(flat(inputs['a'])), 'echo': inputs['a']} + return {'y': [model['constant'] + x for x in inputs['x']]} +''') + + +def array(shape, values): + return {'array': 'float32', 'shape': list(shape), + 'base64': base64.b64encode(struct.pack('<%df' % len(values), *values)).decode('ascii')} + + +def floats(encoded): + raw = base64.b64decode(encoded['base64']) + return list(struct.unpack('<%df' % (len(raw) // 4), raw)) + + +class Definition: + def __init__(self, reference, document): + self.reference, self.document = reference, document + self.kind = documents.KINDS[reference.split('/')[0]] + self.path = reference + '.json' + + +RECIPE = {'format': 'tuldok_definition_v1', 'kind': 'recipe', 'title': 'Served', + 'run': {'command': ['train'], 'environment': 'environments/py'}, + 'serve': {'module_file': 'serve.py', 'load': 'load', 'example': {'x': [1]}}} + + +class Declaration(unittest.TestCase): + + def problems(self, document, extra=()): + found = [(pointer, message) for pointer, message in documents.schema_problems('recipe', document)] + definitions = {'recipes/served': Definition('recipes/served', document), + 'environments/py': Definition('environments/py', {})} + definitions.update({reference: Definition(reference, {}) for reference in extra}) + check.check_serve(definitions, lambda severity, path, pointer, message: found.append((pointer, message))) + return found + + def test_a_valid_declaration(self): + self.assertEqual(self.problems(RECIPE), []) + document = json.loads(json.dumps(RECIPE)) + document['serve'].update(backend='local', function='answer', environment='environments/other', + idle_minutes=5, start_seconds=10, request_seconds=0.5, gpu=False) + self.assertEqual(self.problems(document, ['environments/other']), []) + self.assertIn(('/serve/module_file', 'serve.py'), list(check._code_paths(document))) + + def test_what_is_refused(self): + def changed(**serve): + document = json.loads(json.dumps(RECIPE)) + document['serve'].update(serve) + return [pointer for pointer, _message in self.problems(document)] + self.assertTrue(changed(function='2bad')) + self.assertTrue(changed(backend='pumas')) # the seam is there; only local is built + self.assertTrue(changed(idle_minutes=0)) + self.assertTrue(changed(request_seconds=601)) + self.assertTrue(changed(example=[1])) + self.assertEqual(changed(module_file='serve.txt'), ['/serve/module_file']) + self.assertEqual(changed(environment='environments/none'), ['/serve/environment']) + document = json.loads(json.dumps(RECIPE)) + del document['run']['environment'] + self.assertEqual([pointer for pointer, _ in self.problems(document)], ['/serve']) + document['serve']['environment'] = 'environments/py' + self.assertEqual(self.problems(document), []) + document = json.loads(json.dumps(RECIPE)) + del document['serve']['module_file'] + self.assertTrue(self.problems(document)) + + +class Protocol(unittest.TestCase): + + def test_a_request(self): + inputs = {'x': [[1, 2], [3, 4]], 'a': array([2, 2], [1, 2, 3, 4]), 'name': 'x'} + self.assertIs(serve_protocol.check_request({'inputs': inputs}), inputs) + self.assertEqual(serve_protocol.check_request({'inputs': {'a': array([], [5])}})['a']['shape'], []) + for body in ({}, {'inputs': []}, {'inputs': {}, 'more': 1}, [1], {'inputs': {'x': float('nan')}}): + with self.subTest(body=body), self.assertRaises(ServeError) as refused: + serve_protocol.check_request(body) + self.assertEqual(refused.exception.code, 'invalid') + + def test_a_malformed_array(self): + good = array([3], [1, 2, 3]) + for wrong in ({**good, 'array': 'float64'}, {**good, 'shape': [2]}, {**good, 'shape': [-1]}, + {**good, 'shape': [True]}, {**good, 'shape': [1] * 9}, {**good, 'base64': 'no t!'}, + {**good, 'shape': [1 << 13, 1 << 12]}): + with self.subTest(wrong=wrong), self.assertRaises(ServeError) as refused: + serve_protocol.check_request({'inputs': {'a': wrong}}) + self.assertEqual(refused.exception.code, 'invalid') + + def test_depth(self): + value = 1 + for _ in range(serve_protocol.DEPTH): + value = [value] + with self.assertRaises(ServeError): + serve_protocol.check_request({'inputs': {'x': value}}) + serve_protocol.check_request({'inputs': {'x': value[0][0]}}) + + def test_an_answer(self): + line = json.dumps({'id': 3, 'ok': True, 'outputs': {'y': array([1], [2.0])}, 'model_seconds': 0.1}).encode() + self.assertEqual(serve_protocol.check_answer(line, 3)['outputs']['y']['shape'], [1]) + for wrong, number in ((b'not json', 1), (line, 4), (b'{"id": 3, "ok": true, "model_seconds": 1}', 3), + (b'{"id": 3, "ok": false, "model_seconds": 1}', 3), + (b'{"id": 3, "ok": true, "outputs": 1, "model_seconds": -1}', 3), + (b'{"id": 3, "ok": true, "outputs": NaN, "model_seconds": 1}', 3)): + with self.subTest(wrong=wrong), self.assertRaises(ServeError) as refused: + serve_protocol.check_answer(wrong, number) + self.assertEqual(refused.exception.code, 'serve-failed') + + def test_the_summary_against_its_own_arithmetic(self): + totals = [5.0, 1.0, 4.0, 2.0, 3.0, 10.0] + lines = [{'n': i + 1, 'at': 100.0 + i * 0.5, 'ok': True, 'queue_ms': 0.0, 'model_ms': t / 2, 'total_ms': t} + for i, t in enumerate(totals)] + [{'n': 7, 'at': 104.0, 'ok': False, 'total_ms': 99.0}] + found = serve_protocol.summary(lines) + ordered = sorted(totals) + + def at(p): + position = p * (len(ordered) - 1) + low = int(position) + return ordered[low] + (position - low) * (ordered[min(low + 1, 5)] - ordered[low]) + self.assertEqual((found['count'], found['answered'], found['failed']), (7, 6, 1)) + self.assertEqual(found['total_ms']['p50'], at(0.5)) + self.assertAlmostEqual(found['total_ms']['p95'], 0.25 * 5 + 0.75 * 10) + self.assertEqual(found['total_ms']['p99'], at(0.99)) + self.assertEqual(found['total_ms']['mean'], sum(totals) / 6) + self.assertEqual(found['total_ms']['max'], 10.0) + self.assertEqual(found['span_seconds'], 2.5) + self.assertEqual(found['throughput_per_second'], 5 / 2.5) + self.assertIsNone(serve_protocol.summary([])['total_ms']) + self.assertEqual(serve_protocol.measure(lines[0], 'total_s'), 0.005) + + +class Adapter(unittest.TestCase): + """serve_adapter's encoding and decoding, without NumPy (none is installed here).""" + + def test_decoding_without_numpy(self): + self.assertEqual(serve_adapter.decode({'a': array([2, 3], [0, 1, 2, 3, 4, 5]), 'b': [[1, 2]]}, + use_numpy=False), + {'a': [[0.0, 1.0, 2.0], [3.0, 4.0, 5.0]], 'b': [[1, 2]]}) + self.assertEqual(serve_adapter.decode(array([], [7]), use_numpy=False), 7.0) + self.assertEqual(serve_adapter.decode(array([0, 2], []), use_numpy=False), []) + + def test_encoding(self): + self.assertEqual(serve_adapter.encode({'t': (1, 2.5), 'n': None}), {'t': [1, 2.5], 'n': None}) + for wrong in ({'x': float('inf')}, {1: 2}, {'x': object()}): + with self.subTest(wrong=wrong), self.assertRaises(ValueError): + serve_adapter.encode(wrong) + + class Fake: # what the adapter takes for a NumPy array: shape, dtype, tobytes and astype + shape, dtype, ndim = (2,), 'float64', 1 + + def astype(self, kind): + return types.SimpleNamespace(tobytes=lambda order: struct.pack('<2f', 1.5, -2.0)) + + def tobytes(self): + return b'' + encoded = serve_adapter.encode({'w': Fake()})['w'] + self.assertEqual((encoded['array'], encoded['shape'], floats(encoded)), ('float32', [2], [1.5, -2.0])) + + def test_an_answer_of_the_adapter(self): + line = json.dumps({'id': 2, 'inputs': {'x': [1, 2]}}).encode() + answer = serve_adapter.answer(lambda model, inputs: {'y': [v * model for v in inputs['x']]}, 3, line) + self.assertEqual((answer['id'], answer['ok'], answer['outputs']), (2, True, {'y': [3, 6]})) + failed = serve_adapter.answer(lambda model, inputs: 1 / 0, 3, line) + self.assertEqual((failed['ok'], failed['error']), (False, 'ZeroDivisionError: division by zero')) + self.assertFalse(serve_adapter.answer(lambda m, i: 1, 3, b'{nope')['ok']) + + +def _alive(pid): + try: + with open(f'/proc/{pid}/stat', 'rb') as handle: + return handle.read().rsplit(b')', 1)[1].split()[0] != b'Z' + except OSError: + return False + + +class SupervisorCase(unittest.TestCase): + """A Supervisor under a temporary home, a stand-in module and product; no process left after a test.""" + + def setUp(self): + directory = tempfile.TemporaryDirectory() + self.addCleanup(directory.cleanup) + self.root = Path(directory.name) + patcher = mock.patch.dict(os.environ, {local.HOME_VARIABLE: str(self.root / 'home')}) + patcher.start() + self.addCleanup(patcher.stop) + for name, value in (('WATCH_SECONDS', 0.1), ('STOP_GRACE', 2.0)): + patcher = mock.patch.object(serving, name, value) + patcher.start() + self.addCleanup(patcher.stop) + (self.root / 'code').mkdir() + (self.root / 'code' / 'serve.py').write_text(STAND_IN, encoding='utf-8') + self.supervisor = serving.Supervisor('a' * 32) + self.addCleanup(self.no_process_left) + self.addCleanup(self.supervisor.close) + + def no_process_left(self): + for session in self.supervisor._sessions.values(): + if session.pid is not None: + self.assertFalse(_alive(session.pid), f'the process of session {session.id} is left') + self.assertEqual(launcher.strays('serve-' + session.id), []) + + def launch(self, weights=None, idle_minutes=30, most=2, actor=OWNER, awaiting=False, **serve): + product = self.root / ('product-' + str(len(list(self.root.glob('product-*'))))) + product.mkdir() + (product / 'weights.json').write_text(json.dumps(weights or {'constant': 2.0}), encoding='utf-8') + declared = {'module_file': 'serve.py', 'load': 'load', **serve} + session = self.supervisor.open_session('recipes/fit-a', 'Fit a', actor=actor, scratch=False, backend='local', + idle_minutes=idle_minutes, most=most, awaiting=awaiting) + made = serving.Launch(model='recipes/fit-a', serve=declared, product=str(product), product_run='r' * 32, + environment='environments/py', interpreter=sys.executable, + code_root=str(self.root / 'code'), commit='c' * 40, scratch=False) + if awaiting: + return session, made + return self.supervisor.launch(session['id'], made) + + def wait(self, session_id, *states, seconds=20): + deadline = time.monotonic() + seconds + while time.monotonic() < deadline: + found = self.supervisor.get(session_id) + if found['state'] in states: + return found + time.sleep(0.05) + self.fail(f'session {session_id} stayed {found["state"]}') + + def predict(self, inputs, model='recipes/fit-a'): + return self.supervisor.predict(model, inputs, time.perf_counter()) + + +class Supervisor(SupervisorCase): + + def test_start_ready_predict_stop(self): + session = self.launch() + self.assertEqual(session['state'], 'starting') + ready = self.wait(session['id'], 'ready') + self.assertIsInstance(ready['pid'], int) + self.assertEqual(ready['python'].split('.')[:2], [str(sys.version_info[0]), str(sys.version_info[1])]) + answer = self.predict({'x': [1, 2.5]}) + self.assertEqual(answer['outputs'], {'y': [3.0, 4.5]}) + self.assertEqual(set(answer['timing']), {'queue_ms', 'model_ms', 'total_ms'}) + self.assertLessEqual(answer['timing']['model_ms'], answer['timing']['total_ms']) + encoded = self.predict({'a': array([2, 2], [1, 2, 3, 4.5])})['outputs'] + self.assertEqual(encoded['sum'], 10.5) + self.assertEqual(encoded['echo'], [[1.0, 2.0], [3.0, 4.5]]) # no NumPy: decoded to lists, sent as lists + with self.assertRaises(ServeError) as refused: + self.predict({'fail': True}) + self.assertEqual(refused.exception.code, 'predict-failed') + self.assertIn('ValueError: asked to fail', str(refused.exception)) + self.assertEqual(self.supervisor.get(session['id'])['state'], 'ready') + self.assertIn('a stray print from predict', self.supervisor.get(session['id'])['output_tail']) + lines = self.supervisor.requests(session['id']) + self.assertEqual([(line['n'], line['ok'], line['status']) for line in lines], + [(1, True, 200), (2, True, 200), (3, False, 422)]) + pid = ready['pid'] + stopped = self.supervisor.stop(session['id'], OWNER) + self.assertEqual((stopped['state'], stopped['reason']), ('stopped', 'asked')) + self.assertFalse(_alive(pid)) + with self.assertRaises(ServeError) as refused: + self.predict({'x': [1]}) + self.assertEqual(refused.exception.code, 'not-served') + on_disk = json.loads((self.root / 'home' / ('a' * 32) / 'serving' / session['id'] / 'session.json') + .read_text(encoding='utf-8')) + self.assertEqual((on_disk['state'], on_disk['requests'], on_disk['failed_requests']), ('stopped', 3, 1)) + + def test_a_load_that_fails_or_hangs(self): + failed = self.wait(self.launch({'fail': True})['id'], 'failed') + self.assertIn('RuntimeError: the weights are broken on purpose', failed['problem']) + self.assertIn('Traceback', failed['output_tail']) + hung = self.wait(self.launch({'constant': 1, 'hang': True}, start_seconds=1)['id'], 'failed') + self.assertIn('did not load within 1 seconds', hung['problem']) + time.sleep(0.3) + + def test_a_request_that_hangs(self): + session = self.launch(request_seconds=0.5) + self.wait(session['id'], 'ready') + with self.assertRaises(ServeError) as refused: + self.predict({'hang': True}) + self.assertEqual(refused.exception.code, 'timed-out') + failed = self.supervisor.get(session['id']) + self.assertEqual(failed['state'], 'failed') + self.assertIn('more than 0.5 seconds', failed['problem']) + self.assertEqual(self.supervisor.requests(session['id'])[-1]['status'], 504) + + def test_an_idle_model_stops(self): + session = self.launch(idle_minutes=0.5 / 60) + self.wait(session['id'], 'ready') + stopped = self.wait(session['id'], 'stopped', seconds=10) + self.assertEqual(stopped['reason'], 'idle') + + def test_the_limit_and_one_session_a_model(self): + first = self.launch(most=1) + with self.assertRaises(ServeError) as refused: + self.launch(most=1) + self.assertEqual(refused.exception.code, 'already-served') + with self.assertRaises(ServeError) as refused: + self.supervisor.open_session('recipes/fit-b', 'Fit b', actor=OWNER, scratch=False, backend='local', + idle_minutes=1, most=1, awaiting=False) + self.assertEqual(refused.exception.code, 'limit') + self.supervisor.stop(first['id'], OWNER) + self.supervisor.open_session('recipes/fit-b', 'Fit b', actor=OWNER, scratch=False, backend='local', + idle_minutes=1, most=1, awaiting=True) # awaiting takes no place + + def test_approval(self): + session, made = self.launch(actor=AGENT, awaiting=True) + self.assertEqual((session['state'], session['requested_by']['kind']), ('awaiting-approval', 'agent')) + self.assertIsNotNone(session['expires_at']) + with self.assertRaises(ServeError) as refused: + self.predict({'x': [1]}) + self.assertEqual(refused.exception.code, 'not-ready') + self.assertEqual(self.supervisor.awaiting(session['id']), ('recipes/fit-a', False)) + self.supervisor.approve(session['id'], OWNER, 2) + self.supervisor.launch(session['id'], made) + ready = self.wait(session['id'], 'ready') + self.assertEqual(ready['decided_by']['kind'], 'owner') + self.supervisor.stop(session['id'], AGENT) + declined, _made = self.launch(actor=AGENT, awaiting=True) + self.assertEqual(self.supervisor.stop(declined['id'], OWNER)['state'], 'declined') + with self.assertRaises(ServeError) as refused: + self.supervisor.approve(declined['id'], OWNER, 2) + self.assertEqual(refused.exception.code, 'not-awaiting') + expiring, _made = self.launch(actor=AGENT, awaiting=True) + self.supervisor._sessions[expiring['id']].expires_at = serving._now() + self.assertEqual(self.supervisor.get(expiring['id'])['state'], 'expired') + + def test_a_session_left_by_a_tuldok_that_is_gone(self): + session = self.launch() + self.wait(session['id'], 'ready') + self.supervisor.close() + again = serving.Supervisor('a' * 32) + found = again.get(session['id']) + self.assertEqual(found['state'], 'stopped') + self.assertEqual([item['id'] for item in again.sessions()], [session['id']]) + path = self.root / 'home' / ('a' * 32) / 'serving' / session['id'] / 'session.json' + document = json.loads(path.read_text(encoding='utf-8')) + document['state'] = 'ready' + path.write_text(json.dumps(document), encoding='utf-8') + self.assertEqual((again.get(session['id'])['state'], again.get(session['id'])['reason']), + ('stopped', 'Tuldok stopped')) + + +SERVE_PY = textwrap.dedent(''' + import json, os + + def load(product): + with open(os.path.join(product, 'weights.json')) as handle: + return json.load(handle) + + def predict(model, inputs): + if 'a' in inputs: + return {'sum': sum(v for row in inputs['a'] for v in row)} + return {'y': [model['constant'] + x for x in inputs['x']]} +''') +LATENCY = {'format': 'tuldok_definition_v1', 'kind': 'benchmark', 'title': 'Served latency', + 'earlier_work': {'rebuild': 'no', 'reason': 'Its values come from serving sessions (serve_values).'}, + 'metrics': [{'id': 'total_ms', 'title': 'Total time', 'units': 'ms', 'better': 'lower'}, + {'id': 'model_ms', 'title': 'Model time', 'units': 'ms', 'better': 'lower'}, + {'id': 'wait', 'title': 'Queue time', 'units': 's', 'better': 'lower'}], + 'subjects': [{'name': 'fit-a-served', 'recipe': 'recipes/fit-a'}, {'name': 'other', 'recipe': 'recipes/fit-b'}]} + + +class EndToEnd(http_base.Served): + """fit-a with serve.py, built, served by the app and called over HTTP.""" + + def setUp(self): + super().setUp() + settings = Path(self.temporary) / 'settings.json' + patcher = mock.patch.dict(os.environ, {local.SETTINGS_VARIABLE: str(settings)}) + patcher.start() + self.addCleanup(patcher.stop) + self.write_code('serve.py', SERVE_PY) + self.edit('recipes/fit-a', lambda d: d.update(serve={'module_file': 'serve.py', 'load': 'load', + 'example': {'x': [1, 2]}})) + (self.folder / 'benchmarks' / 'served-latency.json').write_text(json.dumps(LATENCY, indent=2) + '\n', + encoding='utf-8') + for arguments in (('add', '-A'), ('commit', '-q', '-m', 'Serve fit-a.')): # self.root is the address here + subprocess.run([*builds_base.GIT, '-C', str(Path(self.temporary) / 'buildable'), *arguments], check=True, + capture_output=True, timeout=60) + done = self.build('recipes/fit-a') + self.assertTrue(done['ok'], done) + with self.opened() as project: + weights = json.loads(Path(project._execute( + "SELECT directory FROM {schema}.products WHERE reference = 'recipes/fit-a' AND current").fetchone()[0], + 'weights.json').read_text(encoding='utf-8')) + self.constant = weights['constant'] + self.addCleanup(self.no_process_left) + + def no_process_left(self): + self.host.service.serving.close() # what host.close does next; the processes are looked at after it + for session in self.host.service.serving._sessions.values(): + if session.pid is not None: + self.assertFalse(_alive(session.pid)) + self.assertEqual(launcher.strays('serve-' + session.id), []) + + def predict(self, body, token=None, *, raw=None, name='fit-a', content_type='application/json'): + headers = {'Content-Type': content_type} + if token: + headers['Authorization'] = 'Bearer ' + token + data = raw if raw is not None else json.dumps(body).encode() + request = Request(f'{self.root}/api/serve/{name}/predict', data=data, headers=headers) + try: + response = urlopen(request, timeout=30) + except HTTPError as error: + response = error + with response: + return response.status, json.loads(response.read()) + + def ready(self, session, token=None): + deadline = time.monotonic() + 30 + while time.monotonic() < deadline: + found = self.ok('serve_session', {'session': session}, token) + if found['state'] != 'starting': + return found + time.sleep(0.05) + self.fail('the model did not become ready') + + def test_served_through_the_endpoint_and_turned_into_a_benchmark_subject(self): + servable = self.ok('served')['servable'] + self.assertEqual([(item['model'], item['built'], item['example']) for item in servable], + [('recipes/fit-a', True, {'x': [1, 2]})]) + # The reader may predict but not start; the owner starts at once. + status, value = self.call('serve_start', {'model': 'fit-a'}, self.reader['token']) + self.assertEqual((status, value['code']), (403, 'forbidden')) + session = self.ok('serve_start', {'model': 'fit-a'}, self.owner.token) + self.assertEqual((session['state'], session['model'], session['backend']), ('starting', 'recipes/fit-a', + 'local')) + self.assertEqual(len(session['commit']), 40) + found = self.ready(session['id']) + self.assertEqual(found['state'], 'ready', found) + # No credential: refused; a reader's: answered. + status, value = self.predict({'inputs': {'x': [1, 2]}}) + self.assertEqual(status, 401, value) + status, value = self.predict({'inputs': {'x': [1, 2]}}, 'not-a-credential') + self.assertEqual(status, 401, value) + for _ in range(5): + status, value = self.predict({'inputs': {'x': [1, 2]}}, self.reader['token']) + self.assertEqual(status, 200, value) + self.assertEqual(value['outputs'], {'y': [self.constant + 1, self.constant + 2]}) + self.assertEqual((value['model'], value['session']), ('recipes/fit-a', session['id'])) + status, value = self.predict({'inputs': {'a': array([2, 2], [1, 2, 3, 4])}}, self.reader['token']) + self.assertEqual((status, value['outputs']), (200, {'sum': 10.0})) + # Refusals. + self.assertEqual(self.predict({'x': [1]}, self.reader['token'])[1]['code'], 'invalid') + self.assertEqual(self.predict(None, self.reader['token'], raw=b'{')[0], 400) + self.assertEqual(self.predict({'inputs': {}}, self.reader['token'], content_type='text/plain')[0], 400) + self.assertEqual(self.predict({'inputs': {'a': {**array([2], [1, 2]), 'shape': [3]}}}, + self.reader['token'])[0], 400) + status, value = self.predict({'inputs': {'x': 'no'}}, self.reader['token']) + self.assertEqual((status, value['code']), (422, 'predict-failed')) + status, value = self.predict({'inputs': {}}, self.reader['token'], name='fit-b') + self.assertEqual((status, value['code']), (404, 'not-served')) + connection = http.client.HTTPConnection('127.0.0.1', self.server.server_port, timeout=30) + connection.putrequest('POST', '/api/serve/fit-a/predict') + for key, value in (('Authorization', 'Bearer ' + self.reader['token']), ('Content-Type', 'application/json'), + ('Content-Length', str(serve_protocol.REQUEST_LIMIT + 1))): + connection.putheader(key, value) + connection.endheaders() # the body is never sent: the length alone is refused + response = connection.getresponse() + self.assertEqual((response.status, json.loads(response.read())['code']), (413, 'too-large')) + connection.close() + # Through the operation too. + answer = self.ok('serve_predict', {'model': 'recipes/fit-a', 'inputs': {'x': [0]}}, self.reader['token']) + self.assertEqual(answer['outputs'], {'y': [self.constant]}) + # The timings: the summary, then the benchmark's subject. + found = self.ok('serve_session', {'session': session['id']}) + self.assertEqual((found['summary']['count'], found['summary']['answered'], found['summary']['failed']), + (8, 7, 1)) + self.assertEqual(len(found['recent']), 8) + status, value = self.call('serve_values', {'session': session['id'], 'benchmark': 'served-latency', + 'subject': 'other'}) + self.assertEqual((status, value['code']), (400, 'invalid')) + status, value = self.call('serve_values', {'session': session['id'], 'benchmark': 'served-latency', + 'subject': 'fit-a-served'}, self.reader['token']) + self.assertEqual(status, 403) + done = self.ok('serve_values', {'session': session['id'], 'benchmark': 'served-latency', + 'subject': 'fit-a-served', 'metrics': {'total_ms': 'total_ms', + 'model_ms': 'model_ms', + 'wait': 'queue_s'}}) + self.assertEqual((done['benchmark'], done['subject']), ('served-latency', 'fit-a-served')) + self.assertTrue(Path(done['file']).is_file()) + lines = self.host.service.serving.requests(session['id']) + totals = sorted(line['total_ms'] for line in lines if line['ok']) + rows = {row['metric']: row for row in self.ok('results', {'benchmark': 'served-latency'})['rows']} + self.assertEqual((rows['total_ms']['count'], rows['total_ms']['unavailable']), (7, 1)) + self.assertAlmostEqual(rows['total_ms']['median'], totals[3]) + self.assertAlmostEqual(rows['total_ms']['min'], totals[0]) + self.assertAlmostEqual(rows['wait']['max'], max(line['queue_ms'] for line in lines if line['ok']) / 1000) + values = self.ok('values', {'benchmark': 'served-latency', 'subject': 'fit-a-served', 'limit': 100}) + self.assertEqual(values['total'], 24) + self.assertIn('request-000001', {value['case'] for value in values['rows']}) + # Stop: nothing answers; the activity names what was done. + stopped = self.ok('serve_stop', {'session': session['id']}, self.owner.token) + self.assertEqual(stopped['state'], 'stopped') + self.assertEqual(self.predict({'inputs': {'x': [1]}}, self.reader['token'])[0], 404) + done = [(item['operation'], item['target'], item['outcome']) for item in self.activity() + if item['operation'].startswith('serve')] + self.assertIn(('serve_start', 'recipes/fit-a', 'done'), done) + self.assertIn(('serve_stop', session['id'], 'done'), done) + + def test_an_agent_asks_and_the_owner_approves(self): + session = self.ok('serve_start', {'model': 'recipes/fit-a'}) + self.assertEqual(session['state'], 'awaiting-approval') + status, value = self.call('serve_approve', {'session': session['id']}) + self.assertEqual((status, value['code']), (403, 'forbidden')) + status, value = self.predict({'inputs': {'x': [1]}}, self.agent['token']) + self.assertEqual((status, value['code']), (409, 'not-ready')) + approved = self.ok('serve_approve', {'session': session['id']}, self.owner.token) + self.assertEqual(approved['state'], 'starting') + self.assertEqual(self.ready(session['id'])['state'], 'ready') + self.assertEqual(self.predict({'inputs': {'x': [1]}}, self.agent['token'])[0], 200) + self.assertEqual(self.ok('serve_stop', {'session': session['id']})['state'], 'stopped') # cancel scope + again = self.ok('serve_start', {'model': 'fit-a'}) + self.assertEqual(self.ok('serve_stop', {'session': again['id']}, self.owner.token)['state'], 'declined') + + def test_the_limit_of_the_machine_and_what_cannot_be_served(self): + Path(os.environ[local.SETTINGS_VARIABLE]).write_text( + json.dumps({'format': 'tuldok_settings_v1', 'serve_most': 1}), encoding='utf-8') + status, value = self.call('serve_start', {'model': 'fit-b'}, self.owner.token) + self.assertEqual((status, value['code']), (409, 'not-servable')) + status, value = self.call('serve_start', {'model': 'nothing'}, self.owner.token) + self.assertEqual(status, 404) + session = self.ok('serve_start', {'model': 'fit-a'}, self.owner.token) + status, value = self.call('serve_start', {'model': 'fit-a'}, self.owner.token) + self.assertEqual((status, value['code']), (409, 'already-served')) + self.assertEqual(self.ok('served')['most'], 1) + self.ready(session['id']) + self.host.service.close() # Tuldok stopping stops what it serves + self.assertEqual(self.ok('serve_session', {'session': session['id']})['state'], 'stopped') + + +if __name__ == '__main__': + unittest.main() diff --git a/tuldok_project/host.py b/tuldok_project/host.py index b982ab9e..3d4fc113 100644 --- a/tuldok_project/host.py +++ b/tuldok_project/host.py @@ -6,7 +6,9 @@ the folder. dispatch checks the caller's who rule with access.require inside the credential app.py has bound, passes the caller's identity to the service as its actor, and turns a ProjectError into a status and a refusal body; -product_file does the same for the bytes of a product's file. This is +product_file does the same for the bytes of a product's file, and predict +for a served model's endpoint (docs/plans/training-and-curation/spec-t6.md +section 3), whose refusals carry serve_protocol's statuses. This is the one module of the package that imports the app's kept layers (metadata, access, agent_api); access errors are left to app.py, which answers them. """ @@ -16,7 +18,7 @@ from access import Access, AccessError from metadata import Metadata -from . import local, operations, store +from . import local, operations, serve_protocol, store from .service import Service REFUSAL_PROBLEMS = 50 @@ -92,6 +94,18 @@ def product_file(self, run, address, range_header=None): except store.ProjectError as error: return refusal(error) + def predict(self, model, body, *, received, size): + """POST /api/serve/<model>/predict for the bound credential, which must be allowed to inspect: + (200, answer) or (status, refusal body).""" + self._require('inspect', 'serve.predict') + identity = self.access.identity() + actor = {key: identity[key] for key in ('actor_id', 'kind', 'label', 'scopes')} + try: + return 200, self.service.predict(model, body, actor, received=received, size=size) + except serve_protocol.ServeError as error: + return serve_protocol.STATUS.get(error.code, 409), {'error': str(error)[:MESSAGE_CHARACTERS], + 'code': error.code} + def _require(self, who, action): if who == 'owner': self.access.require('approve-execution', action, owner_only=True) diff --git a/tuldok_project/operations.py b/tuldok_project/operations.py index 85aa304a..482b2a7a 100644 --- a/tuldok_project/operations.py +++ b/tuldok_project/operations.py @@ -15,7 +15,10 @@ the five of section 5 of spec-d4.md (annotation_tasks, annotated_records, annotation, set_annotation, revert_annotations) and the five of sections 2 and 4 of spec-d5.md (endpoint, set_endpoint, -find_endpoints, suggestion_models, suggest_annotation). +find_endpoints, suggestion_models, suggest_annotation), and the seven of +section 6 of docs/plans/training-and-curation/spec-t6.md (served, +serve_session, serve_start, serve_approve, serve_stop, serve_predict, +serve_values). Each Operation names one operation project.<name>, the rule its caller must satisfy (who), whether it changes anything (mutation), a closed JSON Schema of its arguments and the result keys that are always present. service.py checks @@ -42,6 +45,7 @@ GRAPH_OVERLAYS = ('parameters', 'outputs', 'operations', 'change') COMPARED_MOST = 4 # recipes of one model_compare (spec-t3.md section 4) EMBEDDING_LIMIT = 1000 # rows of one list of curation by embeddings (spec-t5.md section 4) +SERVE_MEASURES = ('total_ms', 'model_ms', 'queue_ms', 'total_s', 'model_s', 'queue_s') # serve_protocol.MEASURES @dataclass(frozen=True) @@ -127,6 +131,11 @@ def _arguments(required=(), **properties): _SET_NAME = {'type': 'string', 'minLength': 1, 'maxLength': 64} _SIMILARITY = {'type': 'number', 'minimum': 0.5, 'maximum': 1} EMBEDDING_SETS = ('dataset', 'run', 'sets') +_SESSION = {'type': 'string', 'pattern': '^[0-9a-f]{32}$'} +SESSION = ('id', 'model', 'title', 'backend', 'state', 'reason', 'problem', 'requested_by', 'requested_at', + 'decided_by', 'expires_at', 'started_at', 'ready_at', 'ended_at', 'last_request_at', 'commit', 'scratch', + 'product_run', 'product', 'environment', 'interpreter', 'pid', 'idle_minutes', 'requests', + 'failed_requests', 'load_seconds', 'python', 'numpy', 'output_tail') EMBEDDING_MAP = ('name', 'rows', 'dimensions', 'model', 'method', 'explained', 'sample', 'ids', 'x_f32', 'y_f32', 'bounds', 'missing', 'colours', 'colour', 'grid', 'thin') @@ -415,6 +424,29 @@ def _embedding_arguments(required=(), **properties): CANCEL_RUN), Operation('stop_run', 'Kill what a run whose build is gone left running, and mark it unknown.', 'cancel', True, _arguments(['run'], run=_RUN), STOP_RUN), + # Serving a trained model (docs/plans/training-and-curation/spec-t6.md section 6). + Operation('served', 'List the serving sessions on this machine, newest first, the recipes that declare serve ' + "with whether each is built, and the machine's limits.", 'inspect', False, _arguments(), + ('sessions', 'servable', 'most', 'idle_minutes')), + Operation('serve_session', "Read one serving session with its timing summary and its newest requests' lines.", + 'inspect', False, _arguments(['session'], session=_SESSION), SESSION + ('summary', 'recent')), + Operation('serve_start', "Start serving a built recipe's model from its serve entry point: the owner's start " + "runs at once, an agent's waits for the owner's approval.", 'request', True, + _arguments(['model'], model=_REFERENCE, scratch=_FLAG), SESSION), + Operation('serve_approve', "Approve a serving session awaiting approval, which starts it.", 'owner', True, + _arguments(['session'], session=_SESSION), SESSION), + Operation('serve_stop', 'Stop a served model, or decline a serving session awaiting approval.', 'cancel', True, + _arguments(['session'], session=_SESSION), SESSION), + Operation('serve_predict', 'Pass inputs to a served model and read its outputs and the time taken; arrays are ' + 'objects of array float32, shape and base64.', 'inspect', False, + _arguments(['model', 'inputs'], model=_REFERENCE, inputs={'type': 'object'}), + ('model', 'session', 'outputs', 'timing')), + Operation('serve_values', "Import a serving session's request times as per-case values of a benchmark " + 'subject, one case per request.', 'edit', True, + _arguments(['session', 'benchmark', 'subject'], session=_SESSION, benchmark=_NAME, subject=_NAME, + metrics={'type': 'object', 'maxProperties': 64, + 'additionalProperties': {'type': 'string', 'enum': list(SERVE_MEASURES)}}), + ('benchmark', 'subject', 'values', 'file')), ) _BY_NAME = {operation.name: operation for operation in OPERATIONS} diff --git a/tuldok_project/service.py b/tuldok_project/service.py index bcaffcb0..d58eebff 100644 --- a/tuldok_project/service.py +++ b/tuldok_project/service.py @@ -34,8 +34,14 @@ suggest_annotation find the task's product under the lock and read it and ask the endpoint after releasing it. Two of the three comparisons of spec-t3.md (intervals, model_compare) read the project under the lock and -resample its per-case values after releasing it (comparing.py). Nothing here knows of HTTP or of the -app's access layer. +resample its per-case values after releasing it (comparing.py). The seven +operations of serving (docs/plans/training-and-curation/spec-t6.md section 6) +are answered outside the lock too: serve_start and serve_approve work out +what a served process needs with the project open (its product, its +environment's interpreter, the code snapshot) and leave the process to +serving.Supervisor, which the service holds and closes; serve_predict never +opens the project; serve_values imports values under the lock. Nothing here +knows of HTTP or of the app's access layer. The worker (section 4) is one thread per service, started by start() and stopped by close(). It runs queued build requests one at a time while it @@ -57,13 +63,15 @@ import math import os import threading +import time import jsonschema import psycopg from . import (activity, annotation_records, annotation_rows, annotations, build_requests, builds, charts, check, comparing, documents, embeddings, environments, inside, inside_fields, inside_graph, inside_weights, - launcher, local, operations, plan, pumas, store, training, workspace) + launcher, local, operations, plan, pumas, serve_protocol, serving, snapshot, store, training, + workspace) from .documents import Problem CHECK_PROBLEMS = 200 @@ -139,14 +147,17 @@ # take the lock themselves, only for their database work. # The comparisons of spec-t3.md that resample per-case values: read under the lock, computed outside it. COMPARING_READS = ('intervals', 'model_compare') -OUTSIDE_LOCK = ANNOTATION_READS + COMPARING_READS + ('endpoint', 'set_endpoint', 'find_endpoints', - 'suggestion_models', 'suggest_annotation', - 'embeddings', 'set_embedder') +# Serving (spec-t6.md section 6): each takes the lock itself, only to read or change the project. +SERVING_CALLS = ('served', 'serve_session', 'serve_start', 'serve_approve', 'serve_stop', 'serve_predict', + 'serve_values') +OUTSIDE_LOCK = ANNOTATION_READS + COMPARING_READS + SERVING_CALLS + ('endpoint', 'set_endpoint', 'find_endpoints', + 'suggestion_models', 'suggest_annotation', + 'embeddings', 'set_embedder') POLL_SECONDS = 1.0 # how often the worker looks for a queued request CLOSE_SECONDS = 30.0 # how long close() waits for the worker WORKER_LOCK = 'build-requests.lock' _LOG = logging.getLogger(__name__) -_TARGET_ARGUMENTS = ('reference', 'run', 'request', 'task') +_TARGET_ARGUMENTS = ('reference', 'run', 'request', 'task', 'session') def _plain(value): @@ -245,6 +256,7 @@ def __init__(self, folder, *, dsn=None): with builds.opened(self.folder, dsn) as project: self.project_id = project.project_id self.schema = project.schema + self.serving = serving.Supervisor(self.project_id) # ------------------------------------------------------------ lifecycle @@ -266,6 +278,7 @@ def close(self): ends. When the thread does not end in time it is left to finish (and to release the worker lock) on its own. """ + self.serving.close() # every served model is stopped (spec-t6.md section 2) thread, self._thread = self._thread, None self._worker = 'stopped' if thread is None: @@ -409,7 +422,8 @@ def call(self, name, arguments, actor): self._record_activity(actor, name, _target(arguments), 'error', f'{type(exc).__name__}: {exc}') raise if operation.mutation: - self._record_activity(actor, name, _target(arguments), 'done', _detail(name, result)) + target = result.get('model', '') if name == 'serve_start' else _target(arguments) + self._record_activity(actor, name, target, 'done', _detail(name, result)) return result prepared = () if name == 'set_annotation': # the records are found and read before the lock is taken to store them @@ -1114,3 +1128,214 @@ def _cancel_run(self, arguments, actor): def _stop_run(self, arguments, actor): return builds.stop(self.folder, arguments['run'], dsn=self.dsn) + + # ------------------------------------------------------------- serving + + @staticmethod + def _serve_error(error): + """A serving.ServeError as the ProjectError the caller sees, with the same code.""" + return store.ProjectError(str(error), error.code) + + def _served_recipe(self, project, model): + """(reference, title, document, serve) of a recipe that declares serve; ProjectError otherwise.""" + reference = 'recipes/' + _bare(model, 'recipes') + found = project.definition(reference) + if found['kind'] != 'recipe' or found['removed']: + raise store.ProjectError(f'There is no recipe {reference}.', 'not-found', references=[reference]) + document = found['document'] or {} + serve = document.get('serve') + if not isinstance(serve, dict): + raise store.ProjectError(f'{reference} declares no serve; add one to serve its model.', 'not-servable', + references=[reference]) + return reference, found['title'], document, serve + + def _launch_of(self, model, scratch): + """Everything a served process of model needs (serving.Launch); ProjectError when it cannot start.""" + with self._lock: + with self._open() as project: + reference, _title, document, serve = self._served_recipe(project, model) + product = builds._current_product(project, reference) + if product is None: + raise store.ProjectError(f'{reference} has no current product to serve; build it first.', + 'not-built', references=[reference]) + run = document.get('run') if isinstance(document.get('run'), dict) else {} + environment = serve.get('environment') or run.get('environment') + try: + shown = environments.check(project, environment) + except store.ProjectError as exc: + if exc.code != 'not-set-up': + raise + raise store.ProjectError(f'{environment} is not set up on this machine; set it up or connect ' + 'an interpreter, then serve again.', 'not-ready', + references=[environment]) from None + if not shown['ok']: + raise store.ProjectError(f'{environment} is not ready: its check found ' + + '; '.join(shown['problems']), 'not-ready', references=[environment]) + state = project._state() + code_paths = (store._read_project_file(state['folder']) or {}).get('code_paths') + code_root = builds._code_root(project) + home = local.home(project.project_id, create=True) + try: + code = snapshot.prepare(code_root, code_paths, home=home, scratch=scratch) + except snapshot.SnapshotError as exc: + raise builds._snapshot_error(exc) from None + if not os.path.isfile(os.path.join(code.code_root, serve['module_file'])): + raise store.ProjectError(f'The module file {serve["module_file"]} is not in the code' + + ('' if scratch else f' at commit {code.commit[:12]}') + '.', 'invalid') + return serving.Launch(model=reference, serve=dict(serve), product=product['directory'], + product_run=product['run_id'], environment=environment, + interpreter=shown['interpreter'], code_root=code.code_root, commit=code.commit, + scratch=scratch) + + def _served(self, arguments, actor): + limits = local.serve_settings() + sessions = self.serving.sessions() + latest = {} + for session in sessions: # newest first + latest.setdefault(session['model'], session) + servable = [] + with self._lock: + with self._open() as project: + for row in project.definitions('recipe'): + if row['removed']: + continue + document = project.definition(row['reference'])['document'] or {} + serve = document.get('serve') + if not isinstance(serve, dict): + continue + run = document.get('run') if isinstance(document.get('run'), dict) else {} + product = builds._current_product(project, row['reference']) + found = latest.get(row['reference']) + servable.append({'model': row['reference'], 'title': row['title'], + 'module_file': serve.get('module_file'), + 'backend': serve.get('backend', serving.BACKEND), + 'environment': serve.get('environment') or run.get('environment'), + 'built': product is not None, + 'product_run': product['run_id'] if product else None, + 'example': serve.get('example'), + 'idle_minutes': serve.get('idle_minutes', limits['idle_minutes']), + 'session': found}) + return {'sessions': sessions, 'servable': servable, 'most': limits['most'], + 'idle_minutes': limits['idle_minutes']} + + def _serve_session(self, arguments, actor): + try: + session = self.serving.get(arguments['session']) + except serving.ServeError as error: + raise self._serve_error(error) from None + lines = self.serving.requests(session['id']) + return {**session, 'summary': serve_protocol.summary(lines), 'recent': lines[-serving.RECENT:][::-1]} + + def _serve_start(self, arguments, actor): + scratch = arguments.get('scratch', False) + limits = local.serve_settings() + awaiting = actor.get('kind') != 'owner' + if awaiting: # an agent's start: what it names is checked now, the process worked out at approval + with self._lock: + with self._open() as project: + reference, title, _document, serve = self._served_recipe(project, arguments['model']) + if builds._current_product(project, reference) is None: + raise store.ProjectError(f'{reference} has no current product to serve; build it first.', + 'not-built', references=[reference]) + launch = None + else: + launch = self._launch_of(arguments['model'], scratch) + reference, serve = launch.model, launch.serve + with self._lock: + with self._open() as project: + title = project.definition(reference)['title'] + try: + session = self.serving.open_session(reference, title, actor=actor, scratch=scratch, + backend=serve.get('backend', serving.BACKEND), + idle_minutes=serve.get('idle_minutes', limits['idle_minutes']), + most=limits['most'], awaiting=awaiting) + return session if launch is None else self.serving.launch(session['id'], launch) + except serving.ServeError as error: + raise self._serve_error(error) from None + + def _serve_approve(self, arguments, actor): + try: + model, scratch = self.serving.awaiting(arguments['session']) + launch = self._launch_of(model, scratch) + self.serving.approve(arguments['session'], actor, local.serve_settings()['most']) + return self.serving.launch(arguments['session'], launch) + except serving.ServeError as error: + raise self._serve_error(error) from None + + def _serve_stop(self, arguments, actor): + try: + return self.serving.stop(arguments['session'], actor) + except serving.ServeError as error: + raise self._serve_error(error) from None + + def _serve_predict(self, arguments, actor, received=None, size=None): + """Pass inputs to a served model; received and size are the HTTP route's (time read, bytes).""" + received = time.perf_counter() if received is None else received + reference = 'recipes/' + _bare(arguments['model'], 'recipes') + try: + inputs = serve_protocol.check_request({'inputs': arguments['inputs']}) + return self.serving.predict(reference, inputs, received, size) + except serving.ServeError as error: + raise self._serve_error(error) from None + + def predict(self, model, body, actor, *, received, size): + """POST /api/serve/<model>/predict (host.py): the body is {inputs}; ServeError for every refusal.""" + if not _allowed('inspect', actor): + raise serving.ServeError('This credential may not call a served model.', 'forbidden') + inputs = serve_protocol.check_request(body) + reference = 'recipes/' + _bare(model, 'recipes') + return _plain(self.serving.predict(reference, inputs, received, size)) + + def _serve_values(self, arguments, actor): + try: + session = self.serving.get(arguments['session']) + except serving.ServeError as error: + raise self._serve_error(error) from None + benchmark = _bare(arguments['benchmark'], 'benchmarks') + with self._lock: + with self._open() as project: + document = project.definition('benchmarks/' + benchmark)['document'] or {} + subject = next((item for item in document.get('subjects') or [] + if isinstance(item, dict) and item.get('name') == arguments['subject']), None) + if subject is None: + raise store.ProjectError(f'benchmarks/{benchmark} has no subject {arguments["subject"]}.', 'not-found') + if isinstance(subject.get('recipe'), str) and subject['recipe'] != session['model']: + raise store.ProjectError(f'The subject {subject["name"]} is {subject["recipe"]}, not the served model ' + f'{session["model"]}.', 'invalid') + metric_ids = [m.get('id') for m in document.get('metrics') or [] if isinstance(m, dict)] + metrics = arguments.get('metrics') + if metrics is None: + metrics = {m: m for m in metric_ids if m in serve_protocol.MEASURES} + unknown = sorted(set(metrics) - set(metric_ids)) + if unknown or not metrics: + raise store.ProjectError( + f'benchmarks/{benchmark} has no metric {unknown[0]}.' if unknown else + f'Name the metrics of benchmarks/{benchmark} to fill (none of its metrics is one of ' + + ', '.join(serve_protocol.MEASURES) + ').', 'invalid') + lines = self.serving.requests(session['id']) + if not lines: + raise store.ProjectError(f'Session {session["id"]} answered no request.', 'invalid') + values = [] + for line in lines: + case = 'request-%06d' % line.get('n', 0) + for metric, measure in sorted(metrics.items()): + if line.get('ok'): + values.append({'case': case, 'metric': metric, 'value': serve_protocol.measure(line, measure)}) + else: + values.append({'case': case, 'metric': metric, 'value': None, + 'reason': ('The request failed: ' + str(line.get('error') or '?'))[:400]}) + last = max(line.get('at', 0) for line in lines) + produced = datetime.datetime.fromtimestamp(last, datetime.timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ') + commit = session.get('commit') or '' + text = json.dumps({'format': 'tuldok_results_v1', 'benchmark': benchmark, 'subject': subject['name'], + 'commit': commit if len(commit) == 40 else '', 'produced': produced, + 'values': values}, indent=1) + '\n' + path = os.path.join(self.serving.directory(create=True), session['id'], + f'values-{benchmark}-{subject["name"]}.json') + os.makedirs(os.path.dirname(path), exist_ok=True) + with open(path, 'w', encoding='utf-8') as handle: + handle.write(text) + with self._lock: + with self._open() as project: + done = project.import_values(text, path=path) + return {**done, 'file': path} From 5ecc279de64dd0944160a15dd0fd3c438782bd5c Mon Sep 17 00:00:00 2001 From: MrScripty <TheEnvironmentGuy@protonmail.com> Date: Thu, 19 Nov 2026 07:46:55 -0700 Subject: [PATCH 120/131] feat(workspace): serve, approve, stop and try a model from the Train tab and its drawer Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --- app.py | 2 + static/project-workspace.html | 2 + static/project-workspace/screens.js | 5 + static/project-workspace/serving.css | 19 ++ static/project-workspace/serving.js | 212 ++++++++++++++++ static/project-workspace/tabs.js | 13 +- tests/browser_project_workspace_serving.cjs | 261 ++++++++++++++++++++ 7 files changed, 509 insertions(+), 5 deletions(-) create mode 100644 static/project-workspace/serving.css create mode 100644 static/project-workspace/serving.js create mode 100644 tests/browser_project_workspace_serving.cjs diff --git a/app.py b/app.py index 793ead00..056a316d 100644 --- a/app.py +++ b/app.py @@ -848,6 +848,8 @@ def _get(self): '/project-workspace/annotate.js': ('project-workspace/annotate.js', 'text/javascript'), '/project-workspace/generate.js': ('project-workspace/generate.js', 'text/javascript'), '/project-workspace/curation.js': ('project-workspace/curation.js', 'text/javascript'), + '/project-workspace/serving.js': ('project-workspace/serving.js', 'text/javascript'), + '/project-workspace/serving.css': ('project-workspace/serving.css', 'text/css'), '/project-workspace/app.js': ('project-workspace/app.js', 'text/javascript'), '/static/vendor/ubuntu-sans/UbuntuSans[wdth,wght].ttf': ('vendor/ubuntu-sans/UbuntuSans[wdth,wght].ttf', 'font/ttf'), '/static/vendor/ubuntu-sans/UbuntuSans-Italic[wdth,wght].ttf': ('vendor/ubuntu-sans/UbuntuSans-Italic[wdth,wght].ttf', 'font/ttf'), diff --git a/static/project-workspace.html b/static/project-workspace.html index c7076f4a..e159c45e 100644 --- a/static/project-workspace.html +++ b/static/project-workspace.html @@ -9,6 +9,7 @@ <link rel="stylesheet" href="/auth.css"> <link rel="stylesheet" href="/project-workspace/base.css"> <link rel="stylesheet" href="/project-workspace/compare.css"> +<link rel="stylesheet" href="/project-workspace/serving.css"> <script defer src="/auth.js"></script> <script defer src="/project-workspace/adapter.js"></script> <script defer src="/project-workspace/charts.js"></script> @@ -26,6 +27,7 @@ <script defer src="/project-workspace/generate.js"></script> <script defer src="/project-workspace/parallel.js"></script> <script defer src="/project-workspace/curation.js"></script> +<script defer src="/project-workspace/serving.js"></script> <script defer src="/project-workspace/tabs.js"></script> <script defer src="/project-workspace/compare.js"></script> <script defer src="/project-workspace/app.js"></script> diff --git a/static/project-workspace/screens.js b/static/project-workspace/screens.js index 68b7daeb..3355683f 100644 --- a/static/project-workspace/screens.js +++ b/static/project-workspace/screens.js @@ -214,6 +214,11 @@ window.LabScreens = (() => { const stb = h('div', 'st-box'); stb.hidden = true; ins.insertBefore(stb, uses2); reads.push(window.LabStructure.block(stb, m, g, aside.parentElement, live).catch(error => { if (!live()) return; stb.hidden = false; stb.replaceChildren(h('h3', null, 'Structure'), A.refusal(error)); })); } + // Serving (serving.js, spec-t6 section 7), after Structure: shown only when its recipe declares serve. + if (window.LabServing) { + const sv = h('div', 'srv-box'); sv.hidden = true; ins.insertBefore(sv, uses2); + reads.push(window.LabServing.block(sv, m, live).catch(error => { if (!live()) return; sv.hidden = false; sv.replaceChildren(h('h3', null, 'Serving'), A.refusal(error)); })); + } if (more) more(ins); if (!same) aside.appendChild(ins); // first shown: at once, its blocks filled as they come const fill = (b, build) => p => { if (!live()) return; b.lastChild.remove(); try { build(b, p); } catch (error) { failure(b, error); } }; diff --git a/static/project-workspace/serving.css b/static/project-workspace/serving.css new file mode 100644 index 00000000..f2cca336 --- /dev/null +++ b/static/project-workspace/serving.css @@ -0,0 +1,19 @@ +/* Serving a trained model (docs/plans/training-and-curation/spec-t6.md section 7), on the tokens of base.css, so light + and dark follow it. */ +.srv { display: grid; gap: 8px; min-width: 0; } +.srv-head { display: flex; flex-wrap: wrap; align-items: center; gap: 6px 10px; min-width: 0; } +.srv-line { color: var(--ink-2); overflow-wrap: anywhere; min-width: 0; } +.srv-address { margin: 0; color: var(--ink-2); overflow-wrap: anywhere; } +.srv-acts:empty { display: none; } +.srv-fail p { margin: 0 0 6px; color: var(--serious); } +.srv-tail { max-height: 180px; } +.srv h4, .srv-times h4 { margin: 4px 0 2px; font-size: 13px; } +.srv-summary { font-size: 12.5px; } +.srv-try { display: grid; gap: 6px; min-width: 0; } +.srv-inputs { width: 100%; min-width: 0; font: 12px/1.5 var(--mono); padding: 8px; white-space: pre; overflow: auto; box-sizing: border-box; } +.srv-try .actions { margin: 0; } +.srv-answer { min-width: 0; } +.srv-timing { margin: 0 0 4px; color: var(--ink-2); } +.srv-outputs { max-height: 220px; } +.srv-rows .srv-row .sub.mono { overflow-wrap: anywhere; } +.srv-box { min-width: 0; } diff --git a/static/project-workspace/serving.js b/static/project-workspace/serving.js new file mode 100644 index 00000000..284d1691 --- /dev/null +++ b/static/project-workspace/serving.js @@ -0,0 +1,212 @@ +'use strict'; +// Serving a trained model on the page (docs/plans/training-and-curation/spec-t6.md section 7): the Train tab's +// Served models (a row per recipe that declares serve, opening its serving drawer, serve:<recipe>), and a Serving +// block in a model's drawer on the Map. Each panel shows the model's state, the endpoint's address, the controls +// (Serve, or Ask the owner to serve it; Approve and Decline; Stop, in two presses), the output's tail of a failure, +// the session's timing summary and Try it: the inputs as JSON, Send, and the answer of POST /api/serve/<name>/predict. +// +// Updating in place (spec-w4): a control's answer reads the project again as every control does (actions.js). While a +// panel or a row on the page shows a session starting or awaiting approval, `served` is asked every second and each +// one's state mark, line and controls are set in place, its Try it shown once it is ready; nothing else is read again +// and nothing is rebuilt. Try it reads nothing of the project; after an answer the panel's timing summary is read +// again (serve_session) and set in place. +window.LabServing = (() => { + const P = window.TuldokProject, S = window.LabScreens, A = window.LabActions, h = window.LabCharts.h; + const POLL_MS = 1000, SHOWN = 4000; + const TONE = { 'awaiting-approval': ['warn', 'awaiting approval'], starting: ['pending', 'starting'], ready: ['good', 'ready'], + failed: ['serious', 'failed'], stopped: ['neutral', 'stopped'], declined: ['neutral', 'declined'], expired: ['neutral', 'expired'] }; + const OPEN = ['awaiting-approval', 'starting', 'ready'], WAITING = ['awaiting-approval', 'starting']; + const nameOf = ref => ref.slice(ref.indexOf('/') + 1); + const address = ref => 'POST /api/serve/' + nameOf(ref) + '/predict'; + const ms = v => v == null ? '—' : v < 10 ? v.toFixed(2) + ' ms' : v < 1000 ? v.toFixed(1) + ' ms' : (v / 1000).toFixed(2) + ' s'; + const button = (cls, text, key, onClick) => { const b = h('button', cls, text); b.type = 'button'; if (key) b.dataset.key = key; if (onClick) b.addEventListener('click', onClick); return b; }; + const current = item => item.session && OPEN.includes(item.session.state) ? item.session : null; + + /** {tone, word, line} of a servable model: its open session, else its last one, else whether it can be served. */ + function standing(item) { + const s = item.session; + if (s && OPEN.includes(s.state)) { + const [tone, word] = TONE[s.state]; + const line = s.state === 'ready' ? s.requests + (s.requests === 1 ? ' request' : ' requests') + (s.failed_requests ? ', ' + s.failed_requests + ' failed' : '') + ' · stops after ' + s.idle_minutes + ' min idle' + : s.state === 'starting' ? 'loading its product in ' + (s.environment || 'its environment') + : 'asked by ' + ((s.requested_by && (s.requested_by.label || s.requested_by.kind)) || 'someone') + '; the owner approves it'; + return { tone, word, line }; + } + if (s) { const [tone, word] = TONE[s.state] || ['neutral', s.state]; return { tone, word, line: (s.reason || s.problem || '') + (item.built ? '' : ' · not built') }; } + return item.built ? { tone: 'neutral', word: 'not served', line: 'built; it can be served' } : { tone: 'neutral', word: 'not served', line: 'not built: build it before serving it' }; + } + function controls(item) { + const s = current(item), ref = item.model; + const items = []; + if (!s && item.built) items.push({ id: 'serve', label: A.may('owner') ? 'Serve' : 'Ask the owner to serve it', cls: 'btn sm primary', who: 'request', op: 'serve_start', args: () => ({ model: ref }), busy: 'Starting…' }); + if (s && s.state === 'awaiting-approval') { + items.push({ id: 'approve', label: 'Approve', cls: 'btn sm primary', who: 'owner', op: 'serve_approve', args: () => ({ session: s.id }), busy: 'Approving…' }); + items.push({ id: 'decline', label: 'Decline', cls: 'btn sm', who: 'cancel', op: 'serve_stop', args: () => ({ session: s.id }), busy: 'Declining…', confirm: 'Decline serving this model; nothing is started.' }); + } + if (s && (s.state === 'starting' || s.state === 'ready')) + items.push({ id: 'stop', label: 'Stop', cls: 'btn sm', who: 'cancel', op: 'serve_stop', args: () => ({ session: s.id }), busy: 'Stopping…', confirm: 'Stop serving this model; requests to it are refused from then on.' }); + return A.group('serve:' + ref + ':' + (s ? s.id + ':' + s.state : 'none'), items, { inline: true }); + } + + // ---- In place -------------------------------------------------------------------------------------------------- + /** Sets the state of every row and panel of item.model on the page from item, in place. */ + function update(item) { + for (const el of document.querySelectorAll('[data-serve-model]')) { + if (el.dataset.serveModel !== item.model || !el._serve) continue; + el._serve(item); + } + } + let timer = null; + function watch() { + if (timer) return; + timer = setTimeout(async () => { + timer = null; + const waiting = [...document.querySelectorAll('[data-serve-model]')].filter(el => el.isConnected && WAITING.includes(el.dataset.serveState)); + if (!waiting.length) return; + try { const served = await P.call('served'); for (const item of served.servable) update(item); } catch (error) { /* asked again on the next tick */ } + watch(); + }, POLL_MS); + } + /** The state mark and line of an element: replaced only when they differ. */ + function paintState(el, mark, line, item) { + const st = standing(item), stateKey = st.tone + ' ' + st.word; + if (mark._key !== stateKey) { const fresh = S.stateEl(st.tone, st.word); fresh._key = stateKey; fresh.classList.add('srv-mark'); mark.replaceWith(fresh); mark = fresh; } + if (line.textContent !== st.line) line.textContent = st.line; + el.dataset.serveState = item.session ? item.session.state : 'none'; + if (WAITING.includes(el.dataset.serveState)) watch(); + return mark; + } + + // ---- Train: Served models ------------------------------------------------------------------------------------------ + function section(frag, served, sel, act) { + const head = S.parts.sect('Served models', served.error ? '' : served.servable.length + ' declare serve · at most ' + served.most + ' at once'); head.classList.add('gap'); + frag.appendChild(head); + if (served.error) { frag.appendChild(A.refusal(served.error)); return; } + if (!served.servable.length) { frag.appendChild(h('p', 'empty', 'No recipe declares serve. A recipe serves its model through its own serve.py (see the project format).')); return; } + const ul = h('ul', 'rows srv-rows'); + for (const item of served.servable) { + const key = 'serve:' + item.model, li = h('li'), b = button('row env srv-row', null, 'open-' + key, () => act.select(sel === key ? null : key)); + b.setAttribute('aria-pressed', String(sel === key)); b.dataset.serveModel = item.model; + let mark = h('span'); b.appendChild(mark); + const t = h('span'), line = h('span', 'sub'); t.appendChild(h('span', 'title', item.title)); t.appendChild(line); b.appendChild(t); + b.appendChild(h('span', 'sub mono', nameOf(item.model) + ' · ' + item.module_file)); + b._serve = it => { mark = paintState(b, mark, line, it); }; + b._serve(item); + li.appendChild(b); ul.appendChild(li); + } + frag.appendChild(ul); + } + + // ---- A panel: the drawer and the block ------------------------------------------------------------------------------ + /** The panel of one servable item, updated in place by _serve(item). */ + function panel(item, heading) { + const box = h('section', 'srv'); box.dataset.serveModel = item.model; + if (heading) box.appendChild(h('h3', null, heading)); + const head = h('div', 'srv-head'); let mark = h('span'); const line = h('span', 'small srv-line'); head.appendChild(mark); head.appendChild(line); box.appendChild(head); + const where = h('p', 'small mono srv-address', address(item.model)); box.appendChild(where); + const acts = h('div', 'srv-acts'); box.appendChild(acts); + const fail = h('div', 'srv-fail'); fail.hidden = true; box.appendChild(fail); + const times = h('div', 'srv-times'); times.hidden = true; box.appendChild(times); + const tryBox = tryIt(item, () => box._times()); tryBox.hidden = true; box.appendChild(tryBox); + let cur = item, shown = null; + box._times = async () => { + const s = cur.session; + if (!s) { times.hidden = true; return; } + let found; + try { found = await P.call('serve_session', { session: s.id }); } catch (error) { times.hidden = true; return; } + if (cur.session && cur.session.id === found.id) { // the counts of the line, as the summary has them + cur = Object.assign({}, cur, { session: Object.assign({}, cur.session, { requests: found.requests, failed_requests: found.failed_requests }) }); + mark = paintState(box, mark, line, cur); + } + paintTimes(times, found); + }; + box._serve = it => { + cur = it; + mark = paintState(box, mark, line, it); + const s = it.session, now = (s ? s.id + ':' + s.state : 'none') + ':' + it.built; + if (now === shown) return; // the controls, the failure and Try it change with the state only + shown = now; + acts.replaceChildren(controls(it)); + const failed = s && s.state === 'failed'; + fail.hidden = !failed; fail.replaceChildren(); + if (failed) { fail.appendChild(h('p', 'small', s.problem || 'It failed.')); if (s.output_tail) { const pre = h('pre', 'evtext srv-tail'); pre.textContent = s.output_tail; fail.appendChild(pre); } } + tryBox.hidden = !(s && s.state === 'ready'); + box._times(); + }; + box._serve(item); + return box; + } + function paintTimes(times, found) { + const sum = found.summary; + times.hidden = !sum.count; + if (!sum.count) return; + const dl = h('dl', 'facts srv-summary'); + const put = (k, v) => { dl.appendChild(h('dt', null, k)); dl.appendChild(h('dd', 'num', v)); }; + put('Requests', sum.count + (sum.failed ? ' (' + sum.failed + ' failed)' : '') + (sum.throughput_per_second != null ? ' · ' + sum.throughput_per_second.toFixed(1) + ' a second' : '')); + for (const [k, title] of [['total_ms', 'Total'], ['model_ms', 'Model'], ['queue_ms', 'Queue']]) if (sum[k]) put(title, 'p50 ' + ms(sum[k].p50) + ' · p95 ' + ms(sum[k].p95) + ' · p99 ' + ms(sum[k].p99)); + times.replaceChildren(h('h4', null, 'This session'), dl); + } + /** Try it: the inputs as JSON, Send, and the answer; nothing of the project is read again. */ + function tryIt(item, after) { + const box = h('div', 'srv-try'), ref = item.model; + box.appendChild(h('h4', null, 'Try it')); + const area = h('textarea', 'srv-inputs'); area.rows = 4; area.spellcheck = false; area.dataset.key = 'serve-inputs-' + ref; area.setAttribute('aria-label', 'Inputs as JSON'); + area.value = JSON.stringify(item.example || {}); + const out = h('div', 'srv-answer'); out.setAttribute('aria-live', 'polite'); + const send = button('btn sm primary', 'Send', 'serve-send-' + ref, async () => { + let inputs; + try { inputs = JSON.parse(area.value); if (!inputs || typeof inputs !== 'object' || Array.isArray(inputs)) throw Error('The inputs must be a JSON object.'); } + catch (error) { out.replaceChildren(A.refusal(Error(error.message))); return; } + send.disabled = true; send.textContent = 'Sending…'; send.setAttribute('aria-busy', 'true'); + try { + const response = await window.TuldokAuth.fetch('/api/serve/' + nameOf(ref) + '/predict', { method: 'POST', cache: 'no-store', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ inputs }) }); + let value; try { value = await response.json(); } catch (e) { value = { error: 'The server answered ' + response.status + ' without JSON.' }; } + if (!response.ok) throw Object.assign(Error(value.error || 'Refused.'), { code: value.code }); + const text = JSON.stringify(value.outputs, null, 1), pre = h('pre', 'evtext srv-outputs'); + pre.textContent = text.length > SHOWN ? text.slice(0, SHOWN) + '\n…' : text; + out.replaceChildren(h('p', 'small srv-timing', 'total ' + ms(value.timing.total_ms) + ' · model ' + ms(value.timing.model_ms) + ' · queue ' + ms(value.timing.queue_ms)), pre); + after(); + } catch (error) { out.replaceChildren(A.refusal(error)); } + finally { send.disabled = false; send.textContent = 'Send'; send.removeAttribute('aria-busy'); } + }); + const row = h('div', 'actions'); row.appendChild(send); + box.appendChild(area); box.appendChild(row); box.appendChild(out); + box.appendChild(h('p', 'note', 'Arrays may be written as {"array": "float32", "shape": […], "base64": "…"}; the answer is shown as it came.')); + return box; + } + + /** The Train tab's drawer of one servable model (serve:<recipe>). */ + function drawer(aside, key, act) { + const ref = key.slice(6); + if (aside._for === key && !aside._again) return; + aside._for = key; + P.call('served').then(served => { + if (aside._for !== key) return; + const item = served.servable.find(x => x.model === ref); + const ins = h('div', 'inspector'), hd = h('header'); + hd.appendChild(h('span', 'kicker', 'serving · ' + nameOf(ref))); + const t = h('h2', null, item ? item.title : ref); t.tabIndex = -1; hd.appendChild(t); ins.appendChild(hd); + if (!item) ins.appendChild(h('p', 'empty', ref + ' declares no serve.')); + else { + const go = h('div', 'actions'); go.appendChild(button('btn sm ghost', 'On the map', null, () => act.go('map', ref))); ins.appendChild(go); + ins.appendChild(panel(item, null)); + const dl = h('dl', 'facts'); + for (const [k, v] of [['Entry point', item.module_file], ['Environment', item.environment || '—'], ['Product', item.product_run ? 'run ' + item.product_run.slice(0, 8) : 'none'], ['Idle stop', item.idle_minutes + ' min']]) { dl.appendChild(h('dt', null, k)); dl.appendChild(h('dd', 'mono', v)); } + ins.appendChild(dl); + } + S.parts.putDrawer(aside, ins); + }, error => { if (aside._for !== key) return; const frag = document.createDocumentFragment(); frag.appendChild(A.refusal(error)); S.parts.putDrawer(aside, frag); }); + } + + /** The Serving block of a model's drawer (screens.js): shown only for a model whose recipe declares serve. */ + async function block(box, m, live) { + const served = await P.call('served'); + if (!live()) return; + const item = served.servable.find(x => x.model === m.id); + if (!item) { box.hidden = true; return; } + box.replaceChildren(panel(item, 'Serving')); + box.hidden = false; + } + + return { section, drawer, block }; +})(); diff --git a/static/project-workspace/tabs.js b/static/project-workspace/tabs.js index 06282314..8a249987 100644 --- a/static/project-workspace/tabs.js +++ b/static/project-workspace/tabs.js @@ -11,7 +11,7 @@ // run kept (fields.js, spec-d6.md). Train draws the controls of spec-w3.md section 3.1 (actions.js): // Plan build, a build request's Approve, Decline and Cancel, a run's Cancel // run and Stop, an environment's Check again, Connect and Disconnect, and it -// shows a running run live, and the machine's Pumas endpoint beside the environments (generate.js); +// shows a running run live, the models served (serving.js), and the machine's Pumas endpoint beside the environments (generate.js); // it lists first what is planned (the page's drafts // and the models never built, spec-w3 section 3.2). Data's drawer has Edit; // the editor itself is editor.js's. Rule: the chrome holds no project words; titles, @@ -396,12 +396,12 @@ function train(main, aside, state, act, data) { const sel = state.sel.train || null; paint(main, async () => { - const [recipes, runs, requests, envs, endpoint] = await Promise.all([P.read('definitions', { kind: 'recipe' }), P.read('runs'), P.read('build_requests'), P.read('environments'), - window.LabGenerate ? P.read('endpoint').catch(error => ({ error })) : null]); + const [recipes, runs, requests, envs, endpoint, served] = await Promise.all([P.read('definitions', { kind: 'recipe' }), P.read('runs'), P.read('build_requests'), P.read('environments'), + window.LabGenerate ? P.read('endpoint').catch(error => ({ error })) : null, window.LabServing ? P.call('served').catch(error => ({ error })) : null]); const running = runs.runs.filter(r => r.state === 'running'); const progress = new Map(await Promise.all(running.map(r => P.call('progress', { run: r.id }).then(p => [r.id, p.event], () => [r.id, null])))); - return { recipes: recipes.definitions, runs: runs.runs, requests: requests.requests, envs: envs.environments, progress, endpoint }; - }, (frag, { recipes, runs, requests, envs, progress, endpoint }) => { + return { recipes: recipes.definitions, runs: runs.runs, requests: requests.requests, envs: envs.environments, progress, endpoint, served }; + }, (frag, { recipes, runs, requests, envs, progress, endpoint, served }) => { const g = graphFor(data.map), deviceOf = new Map(envs.map(e => [e.reference, e.device])); // Planned (spec-w3 section 3.2): the drafts of this page, then the models never built. const E = window.LabEditor, drafts = g.nodes.filter(m => m.draft); @@ -444,6 +444,8 @@ } frag.appendChild(ul); } + // Served models (serving.js, spec-t6 section 7). + if (served) window.LabServing.section(frag, served, sel, act); // Runs, newest first. const bar = h('div', 'filters gap'); bar.appendChild(searchBox(state, act, 'Find a run')); bar.appendChild(kindChips(state, act, g.nodes.map(m => m.kind))); bar.appendChild(h('span', 'pop', plural(runs.length, 'run') + ' on this machine')); @@ -496,6 +498,7 @@ else if (sel.startsWith('request:')) requestDrawer(aside, sel, act, data); else if (sel.startsWith('plan:')) A.planView(aside, sel, act.go, () => { const one = sel.slice(5); act.select(data.map.byId.has(one) ? one : null); }); else if (sel.startsWith('env:')) envDrawer(aside, sel, act, data); + else if (sel.startsWith('serve:') && window.LabServing) window.LabServing.drawer(aside, sel, act); else if (window.LabEditor && window.LabEditor.owns(sel, data)) window.LabEditor.drawer(aside, sel, act, data, 'train'); else if (data.map.byId.has(sel)) S.inspectorModel(aside, sel, act, data); else if (aside._for !== sel) { aside.textContent = ''; aside._for = sel; aside.appendChild(h('p', 'empty', 'There is no ' + sel + ' here.')); } diff --git a/tests/browser_project_workspace_serving.cjs b/tests/browser_project_workspace_serving.cjs new file mode 100644 index 00000000..3c81f866 --- /dev/null +++ b/tests/browser_project_workspace_serving.cjs @@ -0,0 +1,261 @@ +'use strict'; +// Serving a trained model on the page (docs/plans/training-and-curation/spec-t6.md sections 7 and 9) in a headless +// browser, the owner signed in, no GPU. Tuldok runs with --project-folder on a copy of the minimal fixture with the +// buildable fixture's definitions and code, a serve.py (pure Python, its load slowed by two seconds so that starting +// can be seen) and a serve block on fit-a, which is built with the stand-in trainer before Tuldok starts. +// 1. fit-a's drawer on the Map has a Serving block, not served; Serve starts it; the block shows starting, then +// ready in place: the same element, the drawer not rebuilt, only `served` asked meanwhile. +// 2. Try it sends the example inputs to POST /api/serve/fit-a/predict and shows the answer (the test's own +// arithmetic) and its times; the session's summary appears in place. +// 3. The Train tab lists fit-a under Served models as ready; its row opens the serving drawer. +// 4. Light and dark at 1440 and 390 wide, the Map drawer and the Train tab with the serving drawer: nothing wider +// than the drawer, nor than the main area on Train (the Map's main area is the map, which scrolls sideways). +// 5. Stop (two presses) stops it: the block says stopped, the process is gone, and the endpoint refuses. +// 6. No script error and no failed request. +// node tests/browser_project_workspace_serving.cjs [--shots <dir>] +const assert = require('node:assert/strict'), fs = require('node:fs'), os = require('node:os'), path = require('node:path'); +const { spawn, execFileSync } = require('node:child_process'), { once } = require('node:events'); +const { authenticatedFixture } = require('./auth_helpers.cjs'), { waitForDebugger } = require('./browser_startup.cjs'), { cdpSession } = require('./browser_cdp_session.cjs'), { qaDirectory } = require('./qa_artifacts.cjs'); + +const root = path.resolve(__dirname, '..'); +const argv = process.argv.slice(2), option = name => { const i = argv.indexOf(name); return i >= 0 ? argv[i + 1] : null; }; +assert.ok(process.env.TULDOK_DATABASE_URL, 'TULDOK_DATABASE_URL must name a disposable PostgreSQL cluster'); +const venv = path.join(root, '.venv', 'bin'); +if (fs.existsSync(path.join(venv, 'python'))) process.env.PATH = venv + path.delimiter + process.env.PATH; // auth_helpers runs python3 +const python = fs.existsSync(path.join(venv, 'python')) ? path.join(venv, 'python') : 'python3'; +const MODEL = 'recipes/fit-a'; +const SERVE_PY = `"""fit-a as served: y = constant + x; load waits two seconds so that starting is seen.""" +import json, os, time + +def load(product): + time.sleep(2) + with open(os.path.join(product, 'weights.json')) as handle: + return json.load(handle) + +def predict(model, inputs): + return {'y': [model['constant'] + x for x in inputs['x']]} +`; + +const temporary = fs.mkdtempSync(path.join(os.tmpdir(), 'tuldok-serving-browser-')); +const report = qaDirectory(root, 'project-workspace-serving'); +const shots = option('--shots') ? path.resolve(option('--shots')) : null; if (shots) fs.mkdirSync(shots, { recursive: true }); +const children = [], checks = [], errors = [], failures = []; +let server, serverErrors = '', origin, auth, socket, session, send, evaluate, owned = null; +const pause = ms => new Promise(resolve => setTimeout(resolve, ms)); +async function until(fn, label, tries = 300) { for (let i = 0; i < tries; i++) { const value = await fn(); if (value) return value; await pause(100); } throw Error('Timed out: ' + label); } +function check(text) { checks.push(text); console.log('PASS ' + text); } +function launch(command, args, options) { const child = spawn(command, args, options); children.push(child); return child; } +async function stop(child) { if (!child || child.exitCode !== null || child.signalCode !== null) return; const exited = once(child, 'exit'); child.kill('SIGTERM'); await Promise.race([exited, pause(10000)]); if (child.exitCode === null && child.signalCode === null) { child.kill('SIGKILL'); await exited; } } +function findBrowser() { + const candidates = [process.env.BROWSER, '/usr/bin/chromium', '/usr/bin/chromium-browser', '/usr/bin/google-chrome']; + const cache = path.join(os.homedir(), '.cache', 'ms-playwright'); + if (fs.existsSync(cache)) for (const name of fs.readdirSync(cache).filter(n => n.startsWith('chromium_headless_shell-')).sort().reverse()) candidates.push(path.join(cache, name, 'chrome-headless-shell-linux64', 'chrome-headless-shell')); + const found = candidates.find(candidate => candidate && fs.existsSync(candidate)); + assert.ok(found, 'No headless browser: set BROWSER'); + return found; +} +/** Drops the project's schema and the catalog's from the disposable database, so each run imports afresh. */ +function dropOwned(folder, catalog) { + const id = JSON.parse(fs.readFileSync(path.join(folder, 'tuldok.json'), 'utf8')).id; + execFileSync(python, ['-c', `import json, os, pathlib, sys, psycopg +from psycopg import sql +from tuldok_project import store +store.drop_project(sys.argv[1], os.environ['TULDOK_DATABASE_URL']) +root = pathlib.Path(sys.argv[2]) +if root.exists(): + with psycopg.connect(os.environ['TULDOK_DATABASE_URL'], autocommit=True) as c: + for p in root.rglob('.tuldok.json'): + v = json.loads(p.read_text()) + name = 'projection_' + v['projection_id'] if v.get('version') == 2 else 'catalog_' + v['dataset_id'] + c.execute(sql.SQL('DROP SCHEMA IF EXISTS {} CASCADE').format(sql.Identifier(name))) +`, id, catalog], { cwd: root, stdio: ['ignore', 'pipe', 'pipe'] }); +} +async function contract(name) { + const capabilities = await (await auth.fetch(origin + '/api/agent/capabilities')).json(); + const operation = capabilities.operations.find(item => item.id === 'project.' + name), c = operation.contracts[operation.contracts.length - 1]; + return 'project.' + name + '/' + c.version + '/' + c.sha256; +} +/** An operation as the owner. */ +async function api(name, body = {}) { + const headers = { 'Content-Type': 'application/json', 'Tuldok-Operation-Contract': await contract(name) }; + const response = await auth.fetch(origin + '/api/project/' + name, { method: 'POST', headers, body: JSON.stringify(body) }); + const value = await response.json(); assert.equal(response.status, 200, name + ': ' + JSON.stringify(value)); return value; +} + +// ---- The page's requests, from the browser's network ------------------------------------------------------------------ +const calls = new Map(), finished = []; +function network(event) { + const p = event.params; + if (event.method === 'Network.requestWillBeSent' && /\/api\/(project\/[a-z_]+|serve\/[a-z0-9._-]+\/predict)$/.test(p.request.url)) calls.set(p.requestId, { name: p.request.url.includes('/api/serve/') ? 'predict' : p.request.url.split('/').pop(), sent: Date.now() }); + if ((event.method === 'Network.loadingFinished' || event.method === 'Network.loadingFailed') && calls.has(p.requestId)) { finished.push(Object.assign(calls.get(p.requestId), { done: Date.now() })); calls.delete(p.requestId); } +} +const asked = (since = 0) => finished.concat([...calls.values()]).filter(f => f.sent >= since).map(f => f.name); +async function settled(label) { + await until(() => evaluate(`(() => { const m = document.getElementById('main'), a = document.getElementById('aside'); return ![...m.querySelectorAll('.note'), ...a.querySelectorAll('.note')].some(n => n.textContent === 'Reading…') && !m.hasAttribute('aria-busy'); })()`).then(ok => ok && !calls.size), 'settled: ' + label); + await pause(250); +} +const byKey = key => `[data-key=${JSON.stringify(key)}]`; +async function mouse(type, x, y, buttons = 0) { await send('Input.dispatchMouseEvent', { type, x, y, button: type === 'mouseMoved' ? (buttons ? 'left' : 'none') : 'left', buttons, clickCount: type === 'mouseMoved' ? 0 : 1 }); } +async function press(selector) { + const at = await until(() => evaluate(`(() => { const e = document.querySelector(${JSON.stringify(selector)}); if (!e || e.disabled) return null; e.scrollIntoView({ block: 'center', inline: 'nearest' }); const r = e.getBoundingClientRect(); return { x: r.left + r.width / 2, y: r.top + r.height / 2 }; })()`), 'shown: ' + selector, 100); + await pause(100); await mouse('mouseMoved', at.x, at.y); await mouse('mousePressed', at.x, at.y, 1); await mouse('mouseReleased', at.x, at.y); +} +async function frames() { await evaluate('new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve)))'); } +async function shot(name) { + await frames(); + const png = Buffer.from((await send('Page.captureScreenshot', { format: 'png', captureBeyondViewport: false })).data, 'base64'); + fs.writeFileSync(path.join(report, name + '.png'), png); if (shots) fs.writeFileSync(path.join(shots, name + '.png'), png); +} +const panel = (where = '#aside') => evaluate(`(() => { const p = document.querySelector(${JSON.stringify(where + ' .srv[data-serve-model="' + MODEL + '"]')}); if (!p) return null; + return { state: p.dataset.serveState, mark: p.__mark || null, word: (p.querySelector('.srv-mark') || {}).textContent || '', line: p.querySelector('.srv-line').textContent, address: p.querySelector('.srv-address').textContent, + tryShown: !p.querySelector('.srv-try').hidden, buttons: [...p.querySelectorAll('.srv-acts button')].map(b => b.textContent), times: p.querySelector('.srv-times').hidden ? null : p.querySelector('.srv-times').textContent, + drawer: (document.querySelector('#aside .inspector') || {}).__mark || null }; })()`); +const alive = pid => { try { return fs.readFileSync('/proc/' + pid + '/stat', 'utf8').split(') ').pop().split(' ')[0] !== 'Z'; } catch (_) { return false; } }; + +(async () => { + // ---- The fixture ----------------------------------------------------------------------------------------------------------- + fs.cpSync(path.join(root, 'tests', 'fixtures', 'tuldok_project', 'minimal'), path.join(temporary, 'fixture'), { recursive: true }); + const folder = path.join(temporary, 'fixture', 'project'), code = path.join(temporary, 'fixture', 'code'), buildable = path.join(root, 'tests', 'fixtures', 'tuldok_project', 'buildable'); + for (const kind of ['environments', 'datasets', 'recipes', 'benchmarks', 'charts']) for (const name of fs.readdirSync(path.join(buildable, 'project', kind))) fs.copyFileSync(path.join(buildable, 'project', kind, name), path.join(folder, kind, name)); + for (const name of fs.readdirSync(path.join(buildable, 'code'))) fs.cpSync(path.join(buildable, 'code', name), path.join(code, name), { recursive: true }); + fs.writeFileSync(path.join(code, 'serve.py'), SERVE_PY); + const recipeFile = path.join(folder, 'recipes', 'fit-a.json'), recipe = JSON.parse(fs.readFileSync(recipeFile, 'utf8')); + recipe.serve = { module_file: 'serve.py', load: 'load', example: { x: [1, 2.5] } }; + fs.writeFileSync(recipeFile, JSON.stringify(recipe, null, 2) + '\n'); + const git = ['-c', 'user.name=Tuldok Test', '-c', 'user.email=test@example.invalid', '-c', 'commit.gpgsign=false', '-c', 'init.defaultBranch=main', '-C', path.join(temporary, 'fixture')]; + execFileSync('git', [...git, 'init', '-q']); execFileSync('git', [...git, 'add', '-A']); execFileSync('git', [...git, 'commit', '-q', '-m', 'The fixture.']); + const home = path.join(temporary, 'home'), catalog = path.join(temporary, 'catalog'); fs.mkdirSync(home); + const env = { ...process.env, TULDOK_PROJECT_HOME: home, TULDOK_SETTINGS: path.join(temporary, 'settings.json') }; + owned = [folder, catalog]; dropOwned(folder, catalog); + const cli = (...args) => execFileSync(python, ['-m', 'tuldok_project', ...args], { cwd: root, env, stdio: ['ignore', 'pipe', 'pipe'] }).toString(); + cli('connect', folder, 'test-python', python); + cli('build', folder, MODEL, '--yes'); + let output = ''; + server = launch(python, ['-u', 'app.py', '--port', '0', '--data', catalog, '--project-folder', folder], { cwd: root, env, stdio: ['ignore', 'pipe', 'pipe'] }); + server.stdout.on('data', chunk => { output += chunk; }); server.stderr.on('data', chunk => { serverErrors += chunk; }); + const port = await until(() => { if (server.exitCode !== null) throw Error('Tuldok exited: ' + serverErrors); return output.match(/127\.0\.0\.1:(\d+)/)?.[1]; }, 'Tuldok start-up', 3000); + origin = 'http://127.0.0.1:' + port; + auth = authenticatedFixture(); await auth.register(origin, catalog, root); + const product = (await api('products', { reference: MODEL })).products[0]; + const constant = JSON.parse(fs.readFileSync(path.join(product.directory, 'weights.json'), 'utf8')).constant; + assert.equal((await api('served')).servable[0].built, true, 'fit-a is built and declares serve'); + + const browser = launch(findBrowser(), ['--headless', '--no-sandbox', '--disable-gpu', '--no-first-run', '--hide-scrollbars', '--remote-debugging-port=0', '--window-size=1440,900', '--user-data-dir=' + path.join(temporary, 'browser'), 'about:blank'], { stdio: 'ignore', env: { ...process.env, XDG_CONFIG_HOME: temporary, XDG_CACHE_HOME: temporary } }); + const debugPort = await waitForDebugger(browser, path.join(temporary, 'browser', 'DevToolsActivePort')); + const target = (await (await fetch('http://127.0.0.1:' + debugPort + '/json')).json()).find(item => item.type === 'page'); + socket = new WebSocket(target.webSocketDebuggerUrl); await once(socket, 'open'); + session = cdpSession(socket, { timeoutMs: 60000, onEvent: event => { + network(event); + if (event.method === 'Runtime.exceptionThrown') errors.push(event.params.exceptionDetails.exception?.description || event.params.exceptionDetails.text); + if (event.method === 'Runtime.consoleAPICalled' && event.params.type === 'error') errors.push(event.params.args.map(a => a.value ?? a.description).join(' ')); + if (event.method === 'Log.entryAdded' && event.params.entry.level === 'error') errors.push(event.params.entry.text + ' ' + (event.params.entry.url || '')); + if (event.method === 'Network.loadingFailed' && !event.params.canceled) failures.push({ id: event.params.requestId, error: event.params.errorText }); + if (event.method === 'Network.responseReceived' && event.params.response.status >= 400) failures.push({ url: event.params.response.url, status: event.params.response.status }); + } }); + send = session.send; + evaluate = async expression => { const result = await send('Runtime.evaluate', { expression, awaitPromise: true, returnByValue: true }); if (result.exceptionDetails) throw Error(JSON.stringify(result.exceptionDetails)); return result.result.value; }; + await send('Page.enable'); await send('Runtime.enable'); await send('Network.enable'); await send('Log.enable'); + const size = async (width, height) => send('Emulation.setDeviceMetricsOverride', { width, height, deviceScaleFactor: 1, mobile: width < 600 }); + const theme = async name => { await send('Emulation.setEmulatedMedia', { features: [{ name: 'prefers-color-scheme', value: name }, { name: 'prefers-reduced-motion', value: 'reduce' }] }); }; + await auth.browser(send, origin); // the owner's session + const load = async (name, hash) => { + await theme(name); + await send('Page.navigate', { url: 'about:blank' }); await pause(100); + await send('Page.navigate', { url: origin + '/?theme=' + name + '#' + hash }); + await until(() => evaluate(`document.readyState === 'complete' && !!document.getElementById('needs-btn') && !document.getElementById('needs-btn').disabled`), 'the project read', 1200); + await settled('opened ' + hash); + }; + const mapDrawer = 'map/' + encodeURIComponent(MODEL), trainDrawer = 'train/' + encodeURIComponent('serve:' + MODEL); + + // ---- 1. Serve from the drawer; starting, then ready in place ------------------------------------------------------------- + await size(1440, 900); await load('light', mapDrawer); + let p = await until(() => panel(), 'the Serving block'); + assert.equal(p.state, 'none'); assert.equal(p.word, 'not served'); assert.equal(p.address, 'POST /api/serve/fit-a/predict'); assert.deepEqual(p.buttons, ['Serve']); assert.equal(p.tryShown, false); + await shot('light-1440-1-not-served'); + await press(byKey('serve:' + MODEL + ':none:serve')); + p = await until(async () => { const q = await panel(); return q && q.state === 'starting' ? q : null; }, 'starting', 100); + assert.equal(p.word, 'starting'); assert.deepEqual(p.buttons, ['Stop']); assert.equal(p.tryShown, false); + await evaluate(`(() => { document.querySelector('#aside .srv').__mark = 7; document.querySelector('#aside .inspector').__mark = 8; return true; })()`); + await shot('light-1440-1-starting'); + const since1 = Date.now(); + p = await until(async () => { const q = await panel(); return q && q.state === 'ready' ? q : null; }, 'ready', 150); + assert.equal(p.mark, 7, 'The Serving block is the same element: set in place'); assert.equal(p.drawer, 8, 'The drawer was not rebuilt'); + assert.equal(p.word, 'ready'); assert.deepEqual(p.buttons, ['Stop']); assert.equal(p.tryShown, true); assert.match(p.line, /0 requests/); + const between = asked(since1); + assert.ok(between.length && between.every(n => n === 'served' || n === 'serve_session'), 'Only served (and the summary) asked while starting: ' + between.join(', ')); + const sessionId = (await api('served')).servable[0].session.id, pid = (await api('serve_session', { session: sessionId })).pid; + assert.ok(alive(pid), 'The served process runs'); + check('1. fit-a\'s drawer: not served, Serve; starting, then ready in place (the same block, the drawer not rebuilt, only ' + [...new Set(between)].join(' and ') + ' asked), Try it shown'); + + // ---- 2. Try it ----------------------------------------------------------------------------------------------------------------- + assert.deepEqual(JSON.parse(await evaluate(`document.querySelector('#aside .srv-inputs').value`)), { x: [1, 2.5] }, 'The example fills Try it'); + const since2 = Date.now(); + await press(byKey('serve-send-' + MODEL)); + const answer = await until(() => evaluate(`(() => { const o = document.querySelector('#aside .srv-outputs'); return o ? { outputs: JSON.parse(o.textContent), timing: document.querySelector('#aside .srv-timing').textContent } : null; })()`), 'the answer'); + assert.deepEqual(answer.outputs, { y: [constant + 1, constant + 2.5] }, 'The answer is y = constant + x'); + assert.match(answer.timing, /^total [0-9.]+ m?s · model [0-9.]+ m?s · queue [0-9.]+ m?s$/); + p = await until(async () => { const q = await panel(); return q && q.times ? q : null; }, 'the summary'); + assert.match(p.times, /Requests1/); assert.match(p.times, /p50 .* p95 .* p99/); assert.equal(p.mark, 7); assert.match(p.line, /^1 request /, 'The line counts it'); + assert.deepEqual([...new Set(asked(since2))].sort(), ['predict', 'serve_session'], 'Try it asks the endpoint and the summary only'); + await shot('light-1440-2-tried'); + check('2. Try it answered ' + JSON.stringify(answer.outputs) + ' (' + answer.timing + '); the summary appeared in place'); + + // ---- 3. The Train tab -------------------------------------------------------------------------------------------------------------- + await load('light', 'train'); + const row = await until(() => evaluate(`(() => { const r = document.querySelector('#main .srv-row[data-serve-model="${MODEL}"]'); return r ? { state: r.dataset.serveState, text: r.textContent } : null; })()`), 'the row'); + assert.equal(row.state, 'ready'); assert.match(row.text, /ready/); assert.match(row.text, /1 request/); + await press(byKey('open-serve:' + MODEL)); await settled('serving drawer'); + p = await until(() => panel(), 'the serving drawer'); + assert.equal(p.state, 'ready'); assert.equal(p.tryShown, true); + check('3. Train lists fit-a under Served models, ready with 1 request; its row opens the serving drawer'); + + // ---- 4. Light and dark, 1440 and 390 --------------------------------------------------------------------------------------------- + const seen = []; + for (const [w, hgt] of [[1440, 900], [390, 844]]) for (const name of ['light', 'dark']) for (const hash of [mapDrawer, trainDrawer]) { + const tag = name + '-' + w + '-' + hash.split('/')[0]; + await size(w, hgt); await load(name, hash); + await until(() => panel(), 'the panel ' + tag); + // On the Map the main area is the map, which scrolls sideways by design at 390 wide; the drawer is checked there. + const boxes = hash === mapDrawer ? ['aside'] : ['main', 'aside']; + const r = await evaluate(`(() => { const out = []; for (const id of ${JSON.stringify(boxes)}) { const box = document.getElementById(id); const right = box.getBoundingClientRect().right; out.push(...[...box.querySelectorAll('*')].filter(e => { const b = e.getBoundingClientRect(); return b.width > 0 && b.right > right + 1 && !e.closest('.tv-wrap') && !e.closest('pre'); }).map(e => id + ' ' + e.tagName + '.' + e.className).slice(0, 4)); } return { wide: out, page: document.documentElement.scrollWidth - innerWidth, main: document.getElementById('main').scrollWidth - document.getElementById('main').clientWidth }; })()`); + assert.ok(!r.wide.length && (hash === mapDrawer || r.main <= 1), tag + ': nothing overflows sideways ' + JSON.stringify(r)); + await evaluate(`(() => { const s = document.querySelector('#aside .srv'); if (s) s.scrollIntoView({ block: 'start' }); return true; })()`); await pause(150); + await shot(tag + '-4'); + seen.push(tag + (r.page > 0 ? ' (the page ' + r.page + ' px wider)' : '')); + } + await size(1440, 900); + check('4. Nothing wider than the main area or the drawer: ' + seen.join(', ') + (shots ? '; screenshots in ' + shots : '')); + + // ---- 5. Stop ------------------------------------------------------------------------------------------------------------------------- + await load('light', mapDrawer); + await until(async () => { const q = await panel(); return q && q.state === 'ready'; }, 'ready again'); + const stopKey = 'serve:' + MODEL + ':' + sessionId + ':ready:stop'; + await press(byKey(stopKey)); + await until(() => evaluate(`!!document.querySelector(${JSON.stringify(byKey(stopKey + ':confirm'))})`), 'the confirm state'); + await press(byKey(stopKey + ':confirm')); await settled('stopped'); + p = await until(async () => { const q = await panel(); return q && q.state === 'stopped' ? q : null; }, 'stopped'); + assert.deepEqual(p.buttons, ['Serve']); assert.equal(p.tryShown, false); assert.match(p.line, /asked/); + await until(() => !alive(pid), 'the process gone', 50); + const refused = await auth.fetch(origin + '/api/serve/fit-a/predict', { method: 'POST', headers: { 'Content-Type': 'application/json', Origin: origin }, body: JSON.stringify({ inputs: { x: [1] } }) }); + assert.equal(refused.status, 404, 'The endpoint refuses once it is stopped'); + await shot('light-1440-5-stopped'); + check('5. Stop, in two presses: stopped, Serve offered again, the process gone, the endpoint answers 404'); + + assert.deepEqual(errors, [], 'Script errors'); + assert.deepEqual(failures, [], 'Failed requests'); + check('6. No script error, no failed request'); + fs.writeFileSync(path.join(report, 'receipt.json'), JSON.stringify({ status: 'pass', folder, checks }, null, 2) + '\n'); + console.log('Receipt in ' + report); +})().catch(async error => { + process.exitCode = 1; + console.error(error); if (serverErrors) console.error('Server:', serverErrors.slice(-4000)); + console.error('Script errors:', JSON.stringify(errors)); console.error('Failed requests:', JSON.stringify(failures)); + try { if (evaluate) { await shot('failure'); console.error('Aside:', (await evaluate('document.getElementById("aside").innerText')).slice(0, 2500)); } } catch (_) { /* the page is gone */ } + fs.writeFileSync(path.join(report, 'failure.json'), JSON.stringify({ status: 'failed', error: String(error && error.stack || error), checks, errors, failures }, null, 2) + '\n'); +}).finally(async () => { + try { session?.close(); } catch (_) { /* closed */ } + for (const child of children.reverse()) await stop(child); + if (owned) try { dropOwned(...owned); } catch (error) { console.error('Dropping the disposable schemas failed:', error.message); process.exitCode = 1; } + try { execFileSync('chmod', ['-R', 'u+w', temporary]); } catch (_) { /* nothing was made read-only */ } + fs.rmSync(temporary, { recursive: true, force: true }); +}); From 41c243830c0082c2ad361fe53956c8658863e158 Mon Sep 17 00:00:00 2001 From: MrScripty <TheEnvironmentGuy@protonmail.com> Date: Thu, 19 Nov 2026 07:56:31 -0700 Subject: [PATCH 121/131] docs(plan): spec-t6 as built Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --- docs/plans/training-and-curation/spec-t6.md | 34 +++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/docs/plans/training-and-curation/spec-t6.md b/docs/plans/training-and-curation/spec-t6.md index 96b4f458..58e5d90d 100644 --- a/docs/plans/training-and-curation/spec-t6.md +++ b/docs/plans/training-and-curation/spec-t6.md @@ -141,3 +141,37 @@ They are answered outside the service's lock; those that read the project take i ## 10. Out of scope A remote address (decision 4); more than one process per model, batching, streaming answers, GPU scheduling between serving and builds (a served model with `gpu` does not take the GPU lock: doubt); authentication other than Tuldok's credentials; serving a dataset or a benchmark; restarting a failed model on its own. + +## As built + +What differs from the text above, and what was found. Built on `feat/t6-serving` beside phase 4 (annotation), which is not touched. Edits to shared files are small and local: `operations.py` (seven rows at the end of the table, `SESSION`, `SERVE_MEASURES`), `service.py` (the serving calls in `OUTSIDE_LOCK`, the supervisor held and closed, the methods appended at the end, `session` as an activity target), `app.py` (the route, two asset rows), `tabs.js` (`served` read with the Train tab, the section after Build requests, the `serve:` drawer), `screens.js` (the Serving block after Structure), `project-workspace.html`, `docs/contracts/project-folder.md` (the `serve` row of the recipe, seven operation rows, a section *Serving a model* before *The Pumas endpoint*, two settings), the service test's count (79 to 86) and its lists of mutations, owner rows and reads. `base.css` is not changed (its phone header kept); the styles are in a new `serving.css`. `check.py`, `store.py` (one line: `check_serve` among the cross-file checks), `local.py` and `schemas/recipe.schema.json` take the declaration. + +### The backend seam + +`serve.backend` is a field of the declaration: `"local"` (the default and the only value the schema accepts). In `serving.py`, `BACKENDS` maps a backend's name to an object with `start(session, launch, on_ready, on_exit)`, `exchange(session, inputs, deadline)` and `stop(session)`; `LocalBackend` is the one built. The `Supervisor` owns everything that is not the backend's (states, approval, the machine's limit, idle stop, the queue of one model, timings and the log) and calls the backend only through those three. A later `"pumas"` backend (registering an exported model with the owner's Pumas endpoint and forwarding requests to it, once Pumas offers a generic tensor-in/tensor-out capability; 0.8.0 does not) would be a second entry of `BACKENDS` and a value of the schema's enum; it is not built and Pumas is not contacted. `served` and the sessions answer `backend`. + +### T6a, the core + +- **Files:** `tuldok_project/serving.py` (sessions, `Launch`, `LocalBackend`, `Supervisor`), `serve_protocol.py` (the checks of a request, an answer and the ready line, the statuses of section 3, the summary), `serve_adapter.py` (the child side, run as a file with `-I`, Python 3.8 or later). +- **The code served** is the snapshot at HEAD, as section 2 says, not the code at the product's commit: a `serve.py` added after the model was built would not be in the older snapshot. The session records the commit it serves from; the product's run is recorded beside it. A dirty tree is refused `dirty` unless `scratch`. +- **An owner's start works out the launch first** (product, environment check, snapshot, the module file in the snapshot) and refuses (`not-built`, `not-ready`, `dirty`, `invalid`, `not-servable`) before any session is made; an agent's start only checks that the recipe declares `serve` and is built, and the launch is worked out at approval (a refusal then leaves the session awaiting). Refusal codes `not-servable`, `already-served`, `limit`, `not-awaiting`, `not-running` were added to section 3's list; through the operations they are 409 (`operations.error_status`), through the endpoint the statuses of `serve_protocol.STATUS`. +- **Times.** `total_ms` runs from when the app has read and parsed the body; `queue_ms` therefore holds Tuldok's credential check (a database query) as well as the wait for the model, about 0.3 to 2 ms on this machine when nothing waits. `model_ms` is the adapter's own time around `function`. Throughput is (answered − 1) / (last − first request time). +- **A stop that comes while the process is being started** (a race the first supervisor test found: the process was spawned after the stop and left running) is handled by a `stopping` event the starting thread looks at once the process exists. `close()` also stops the processes of sessions that failed and are still being stopped. +- **Approval** is held in memory, not in the database: an agent's start awaits the owner while Tuldok runs and is gone after a restart (its `session.json` reads `stopped`, reason `Tuldok stopped`). It is not in Needs you (adapter.js is not changed); it is shown on the Train tab's row and drawer with Approve and Decline. +- **The endpoint** needs no contract header; an `Origin` is required for a cookie, as for every POST. A body over 8 MiB is refused from its `Content-Length` before it is read (413). Answers go through `app.reply`; requests are not observed by the MCP observer beyond its stages. +- **Tests:** `tests/test_tuldok_project_serving.py`, 20: the declaration (valid, each refusal, `backend` other than `local` refused, the module file as a code path), the protocol (requests, malformed arrays, depth, answers, the summary against the test's own percentiles), the adapter (decoding to lists, encoding with a stand-in for a NumPy array, an answer and its failure), the supervisor with a pure-Python stand-in and the interpreter running the tests (start to ready, predict with lists and a base64 array, a stray `print` in the log and not in the protocol, a request that raises: 422 and still ready, stop; a `load` that raises and one that hangs; a request that hangs: 504 and failed; idle stop; one session a model and the limit; approval, decline and expiry; a session left by a Tuldok that is gone), each test checking that no process and no stray of its sessions is left; and three end-to-end tests through the app on port 0 (no credential and a wrong one 401, a reader's predict 200 with lists and a base64 array, the reader refused `serve_start` and `serve_values`, 400, 404, 413 and 422 refusals, `serve_predict`, `serve_session`'s summary, `serve_values` into a `served-latency` benchmark whose summary rows equal the test's own median, minimum and maximum, the activity rows; an agent's start awaiting approval, refused approval, the owner's approval, the agent's stop; the limit from the settings file, `not-servable`, `already-served`, and the service's close stopping what it serves). + +### T6b, the page + +- `static/project-workspace/serving.js` and `serving.css`. The Train tab's **Served models** is after Build requests; its rows and the panels update in place while a session shown is starting or awaiting approval (a one-second `served`, only then). After Try it the panel reads `serve_session` and sets its summary and its line's counts in place. +- `served` and `serve_session` are called, not kept (`P.call`): neither is in `P.WATCHED`, so a reading on the timer never redraws a panel; a control's answer redraws the drawer as every control does. +- **Doubts:** the Train tab's row does not update on its own while ready (its request count changes only when the tab is drawn again); "Try it" shows the answer as JSON, not as an image or a field; an agent's start is not in Needs you; keyboard use of Try it was not checked beyond the buttons being buttons and the field a textarea. +- `tests/browser_project_workspace_serving.cjs`: Serve from fit-a's drawer on the Map, starting and then ready in place (the same element, the drawer not rebuilt, only `served` and `serve_session` asked in between), Try it answering the test's own arithmetic with its times and the summary set in place, the Train tab's row and drawer, light and dark at 1440 and 390 (the drawer, and on Train the main area, not wider than themselves; on the Map at 390 the main area is the map, which scrolls sideways before this phase too, so only the drawer is checked there), Stop in two presses, the process gone and the endpoint answering 404; no script error and no failed request. + +### Runs (a disposable PostgreSQL, no GPU) + +Project suite 832 OK (812 before, and the 20 new); agent interface 43 OK (4 skipped); `browser_project_workspace_serving.cjs` 6 PASS (three runs); unchanged `browser_project_workspace.cjs` 24 PASS, `_actions.cjs` 27 PASS, `_training.cjs` 7 PASS. After every run no `serve_adapter.py` process was left. + +### Not verified + +NumPy in the adapter (no NumPy in the test environment and nothing downloaded: the decoding to a `numpy.ndarray` and the encoding of a real array are untested; the encoding was checked with a stand-in object); a model on the GPU (`gpu` only empties `CUDA_VISIBLE_DEVICES` or not, and a served model does not take the GPU lock that builds take); a project whose `serve.py` imports PyTorch; requests near the 8 MiB bound for speed; eight requests waiting at once (`busy`); the lab folder (nothing there declares `serve`). From b7c86e19f201a0863ef7a1bae856fe561a393866 Mon Sep 17 00:00:00 2001 From: MrScripty <TheEnvironmentGuy@protonmail.com> Date: Thu, 19 Nov 2026 08:04:31 -0700 Subject: [PATCH 122/131] docs(plan): spec-t7, hyperparameter search on this machine Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --- docs/plans/training-and-curation/spec-t7.md | 105 ++++++++++++++++++++ 1 file changed, 105 insertions(+) create mode 100644 docs/plans/training-and-curation/spec-t7.md diff --git a/docs/plans/training-and-curation/spec-t7.md b/docs/plans/training-and-curation/spec-t7.md new file mode 100644 index 00000000..a5c20c51 --- /dev/null +++ b/docs/plans/training-and-curation/spec-t7.md @@ -0,0 +1,105 @@ +# Implementation spec: hyperparameter search on this machine + +This is phase 7, the last, of [the training and curation plan](plan.md). It follows that plan's rule: Tuldok does not grow a training framework. A sweep varies the settings of a recipe the project already has and runs the project's own script for each trial, one after another, under the build machinery that already exists ([spec-m6.md](../definition-first-projects/spec-m6.md), [spec-m7.md](../definition-first-projects/spec-m7.md) section 4). What Tuldok adds is a definition (`sweep`), the schedule of trials, the decision to stop a poor trial early read from the metrics the script logs anyway ([spec-t1.md](spec-t1.md) section 2.1), and the views. Standard library only on the server; nothing of the project's code runs in Tuldok's server; the page follows [spec-w4.md](../definition-first-projects/spec-w4.md) and updates in place. + +**Owner, 2026-11-19:** "Hyperparameter search could be usful, Tuldok is a little bit limited for that since it is not distributed, but it could still work well on tiny models localy." + +**After this phase** a project can hold `sweeps/<name>.json`: the recipe it varies, the settings it varies and their ranges, a strategy (grid, random, or successive halving that stops poor trials early), one or two objectives read from the trials' training logs, and a budget (trials, minutes; one trial at a time). A build request for the sweep, approved once, runs the trials one after another. Each trial is a real recipe, derived from the varied one, drawn on the Map in a section of the sweep. The **Sweeps** tab shows a sweep's state live (trials done, running, pruned; best so far; budget used), its trials through parallel coordinates (its main view), its frontier when it has two objectives, and every trial in a table that opens it on the Map. + +## 1. Decisions + +- **One approval covers the whole budget.** A sweep is asked for with `request_build` naming it as the only target; the owner's request is queued, an agent's awaits approval, as for any build. What the approval covers is the sweep's text, the varied recipe's text, the texts of what that recipe needs (its inputs and environment) and the commit. Every trial is made by Tuldok from those two texts alone (section 4), so a trial is within the approval though its own text did not exist when it was approved. Changing the sweep or the recipe before the request runs makes it stale, as for any build. +- **Trials are recipes, kept in the project like any edit.** Each trial is written into Tuldok's working copy as a definition `recipes/<sweep>-<NNN>` with `derived_from` the varied recipe, `change` `sweep-trial`, and a `sweep` block naming the sweep, its number and the values it was given; it is an unsaved edit, and Save writes it into the folder like any other. Why the folder, and not a store of Tuldok's own until the owner keeps the winners: a trial's product is recorded against its definition text, and a run is only explained by a definition someone can read again; trials are small (one recipe each, a few hundred bytes); the folder is the place for definitions and high-level results, and keeping the pruned and failed trials too keeps the record of what was tried honest. The raw logs stay in the runs' directories on this machine, never in the folder. The owner who does not want a sweep's trials in Git removes them before saving (Remove on each, as for any definition); keeping only the winners by one control is not built (section 9). +- **Trials are never overwritten.** A trial named `<sweep>-007` that already exists with other values (the sweep's ranges changed since) is left alone, and the new trial takes `<sweep>-007-2` (then `-3`, …). An existing trial of this sweep with the same values and the same text is reused: built already, it is not run again. +- **Concurrency is one.** Trials run one after another on this machine; there is no distributed or parallel search. +- **Objectives are training metrics.** An objective is a series of the trial's `training/metrics.jsonl` (its last or best value), or the trial's last logged `time` or `step`. **A benchmark objective is not built:** a trial measured by a benchmark must be one of its subjects, and adding a subject changes the benchmark's definition, which makes every other subject of it out of date (builds.status compares the whole text); that would need a per-subject definition hash. The way to benchmark a sweep's winners is the existing one: add them as subjects once chosen. +- **Pruning is successive halving without resuming.** A trial cannot be paused and taken up again (there is no checkpoint contract to resume from), so the asynchronous rule of ASHA is applied as a stop rule: at each rung a trial reaches, it goes on only when it is among the best `1/factor` of the values recorded at that rung so far (section 5). + +## 2. The definition: `sweeps/<name>.json` + +A new kind, `sweep`, in a new directory `sweeps/`. Fields (unknown ones refused): + +| Field | Rule | +| --- | --- | +| `format`, `kind`, `title`, `description`, `card`, `labels` | as every definition; `kind` is `sweep` | +| `recipe` | required: `recipes/<name>`, the recipe whose settings it varies. It must have `run.settings` written in the definition (not `settings_file`); Branch from here gives a branch its own copy | +| `parameters` | required: 1 to 16 objects, each with `path` (a dotted path into `run.settings`: keys separated by `.`, a part of digits indexes a list; every part but the last must exist in the recipe's settings as an object or a list; the last may be absent) and either `values` (1 to 64 distinct numbers, texts, booleans or null) or a range: `low` < `high` (numbers), `scale` `linear` (default) or `log` (then `low` > 0), `integer` (default false; `low` and `high` then whole numbers), `count` (2 to 64: how many points of the range a grid takes). Each path once | +| `strategy` | required: `{"kind": "grid"}` (every range then needs `count`), `{"kind": "random", "seed": <0 … 2^63−1>}`, or `{"kind": "halving", "seed", "metric", "better", "unit", "min", "factor"}`: `metric` a series name (1 to 200 characters), `better` `lower` or `higher`, `unit` `step` (default) or `time` (seconds), `min` the first rung (> 0; a whole number for steps), `factor` a whole number from 2 to 8 (default 3) | +| `objectives` | required: one or two objects with distinct `metric` (a series name, or `time` or `step`: the last logged), `take` `last` (default) or `best`, `better` `lower` or `higher`, optional `title` (at most 200 characters) | +| `budget` | required: `trials` (1 to 1,000), optional `minutes` (> 0, at most 10,080), optional `concurrency` (only 1) | + +The checker reports as errors also: a `recipe` that is not a recipe (as any reference); a recipe without `run.settings`, or with `settings_file`; a path whose parents are not in the recipe's settings, or not objects or lists; a grid with a range without `count`; a grid of more than 100,000 points. As a warning: a grid with more points than `budget.trials` (the first in order are run). The edge from a sweep to its recipe has the role `varies`; it carries no state, and a plan does not follow it. + +A recipe gains two optional fields: `change` may be `sweep-trial`, and `sweep` is `{definition: "sweeps/<name>", trial: <1 or more>, values: {<path>: <value>}}` (at most 16 values). The edge from a trial to its sweep has the role `sweep`, a map role like `derived`. The flattening of spec-t3 section 1 leaves `sweep` out (its values are in `run.settings` already). + +## 3. The schedule + +The trials are numbered from 1 in the order the strategy gives them; the same definition gives the same schedule every time. A value drawn from a range is rounded to 6 significant digits (`float(f'{x:.6g}')`), and an integer range's to `floor(x + 0.5)` within `low` and `high`. + +- **Grid:** the Cartesian product in the order of `parameters`, the first varying slowest (`itertools.product`). A range's points are `low + i (high − low) / (count − 1)`, or on a log scale `exp(ln low + i (ln high − ln low) / (count − 1))`, for `i` from 0 to `count − 1`, rounded, repeats dropped. The first `budget.trials` points are run. +- **Random and halving:** `random.Random(seed)`; for each trial, each parameter in order draws: from `values`, `values[rng.randrange(len(values))]`; from a range, `u = rng.random()`, then `low + u (high − low)` or `exp(ln low + u (ln high − ln low))`, rounded. A draw equal to an earlier trial's values is dropped and drawn again; after 1,000 draws in a row with none new the schedule ends (a small space is exhausted). + +## 4. A trial's definition + +Made from the varied recipe's document as it is in the working copy: `format`, `kind`, `title` "<sweep title> · trial <n>", `description` "Trial <n> of sweeps/<name>: <path> = <value>, …", the recipe's `model` and `group` when it has them, `labels` `{"short": "T<n>"}`, `change` `sweep-trial`, `derived_from` the recipe, `sweep` as in section 2, and the recipe's `run` with each path set to the trial's value. Not carried over: `card`, `labels`, `earlier_work`, `compared_with`. JSON with two spaces of indentation and a newline at the end. It is stored with `set_definition`; a trial that does not check is recorded failed with the first problems, and the sweep goes on. + +## 5. Running a sweep + +The worker takes a request whose target is a sweep as any other (section 4 of spec-m7.md: the order, the expiry, the covers checked again), and runs it with `sweeps.execute`, which returns what `builds.execute` returns, so the request ends the same way: + +1. The code is prepared once, at the approved commit (or as it is on disk for a scratch request), and one plan id is used for every run of the sweep, so the request's runs are all of them and Cancel reaches the one running. +2. What the varied recipe needs and is not built is built first, as a build would. A failure there fails the sweep. +3. Then trial after trial in the schedule's order. Before each: the trials budget (trials recorded in this run of the sweep, reused ones included), the minutes budget (wall time since the sweep started), and a stop asked for (Cancel, or Tuldok closing). The trial's definition is made and kept (section 4); its SHA-256 is added to what the build expects, and it is run like a build step. +4. While a trial runs, a watcher reads its `training/metrics.jsonl` every quarter second (spec-t1's reader, only the lines appended) and records the trial's latest step, time and objective values. It stops the trial cleanly (the run's cancel file: SIGTERM, then SIGKILL after the launcher's grace) when the minutes budget is spent, when a stop is asked for, or when halving prunes it. +5. **Halving.** The rungs are `min × factor^k`, k = 0, 1, … (at most 32), in steps or seconds. A trial reaches rung k at the first line whose step (or time) is at least the rung; its value there is the latest finite value of the metric on that line or before (none: nothing is recorded at that rung and the trial goes on). It is then compared with the values recorded at rung k by the earlier trials of this sweep run: with n values including its own, while n < factor it goes on; otherwise it goes on when fewer than ceil(n / factor) values are strictly better than its own, and is pruned otherwise. A line crossing several rungs records each. Every value is recorded, the trial's own included, whether it goes on or not. +6. When the trial's run ends, its objectives are read from its log (a pruned or stopped trial's as far as it got), and it is recorded **completed** (the run succeeded), **pruned**, **stopped** (budget or a stop), or **failed** (the run failed, or the trial did not check). A pruned trial's run is cancelled and its problem says it was pruned and at which rung. +7. The sweep ends **finished** (the schedule or a budget is spent), **cancelled** or **failed**; its request succeeds when it finished. + +A trial reused from before (section 1) costs nothing: its objectives are read from its current product's run. A pruned trial of an earlier run of the same sweep with the same text is not reused; it runs again. + +**State.** Two tables of the project schema: `sweep_runs` (one row per run of a sweep: the sweep, the request, the plan, the state and why it ended, the texts' SHA-256 it ran with, the strategy, objectives and budget, when it started and finished, the owner process) and `sweep_trials` (per trial: number, reference, values, state, whether reused, run, start and finish, seconds, the rungs reached with their values and decisions, the objectives, the latest line seen, the problem). A run left running by a process that is gone is marked failed when sweeps are read. Nothing of these tables is written to the folder. + +**A sweep in a plan.** `plan` with a sweep as its only target answers the plan of what its recipe needs (the recipe itself left out) and one more step, of kind `sweep`: its action `build`, or `built` when its last run finished with the sweep's and the recipe's texts as they are now, or `blocked` when the recipe cannot be built for a reason other than its own `earlier_work` label; its reasons say what it will run, its resources the minutes as `wall_hours`. A sweep with other targets, or with `every`, is refused `invalid`. `request_build` with such a plan covers the recipe's text as well. + +## 6. Operations + +Two reads, `inspect`, in the `project_folder` profile only (the catalog's digest is unchanged): + +| Operation | Arguments | Result | +| --- | --- | --- | +| `sweeps` | none | `sweeps`: each `reference`, `title`, `recipe`, `strategy` (its kind), `objectives`, `budget`, `state` (as in a plan), and `run`: null or the latest run's `id`, `state`, `ended`, `started_at`, `finished_at`, `counts` (by trial state), `best` | +| `sweep` | `sweep` (a reference or a bare name), optional `run` (a run id; default the latest) | `reference`, `title`, `description`, `recipe`, `parameters`, `strategy`, `objectives`, `budget`, `state`, `changed` (the latest run ran another text), `request` (the newest build request naming it: `id`, `state`, `requested_by`), `run` (null, or `id`, `state`, `ended`, `problem`, `started_at`, `finished_at`, `seconds`, `trials`, `counts`), `runs` (the last 20: `id`, `state`, `started_at`, `trials`), `trials` (each `number`, `reference`, `values`, `state`, `reused`, `run_id`, `seconds`, `rungs`, `objectives`, `latest`, `problem`, `defined`), `best` (`number`, `reference`, `value`, or null), `frontier` (the numbers of the completed trials on the frontier of the two objectives; empty with one), `rungs` (the rung points up to the last reached and one more), `axes` (as `benchmark_axes` answers: `metrics` the objectives, `settings` the parameters, `subjects` the trials) | + +`map` gains a group per sweep that has trials (`id` the sweep's reference, `title` its title, `parent` the varied recipe's group, `sweep` true) and each model a `sweep` (the reference, or null); a trial's `group` in the answer is its sweep's group. The folder's `groups` are unchanged. + +## 7. The page: the Sweeps tab + +A tab **Sweeps** after Train (`#sweeps`; the chosen sweep in the address, `?sweep=`). + +- **Head:** the sweep chooser, its recipe (a link to it on the Map), the strategy, objectives and budget in words, and **New sweep** for a session that may edit: a recipe chosen, a sweep's text written from it (its numeric settings as ranges around their values, random, its first logged series as the objective, 8 trials) into the editor's text view, kept with Keep. +- **State, live:** the run's state; trials completed, running, pruned, stopped, failed of the budget's; the minutes used of the budget's; the running trial with its step and objective values; best so far; and the controls: **Plan sweep** (the plan view, with Request build), **Approve** and **Decline** when a request awaits approval, **Cancel** while it is queued or running. Updated in place on every reading while a sweep runs: texts and bar widths set, no node added or removed. +- **Trials, parallel coordinates** (its main view): `parallel.js` with the sweep's axes, one line per trial in the colour of its state (completed, pruned, stopped, failed, running); dragging ranges filters the table below. +- **Frontier** with two objectives: the tradeoff chart of `charts.js` over the completed trials, the frontier marked; with one objective, the progression chart (the objective by trial number, best so far as a step line). +- **The table:** every trial: number, values, state (and the rung it was pruned at), objectives, seconds; a row opens the trial's drawer (the model's drawer), and **Open on the Map** selects it there. +- **Updating in place:** a reading that finds the sweep's answer changed updates the state texts, appends rows for new trials and sets the changed cells, and draws the charts again in their hosts; the tab is never emptied, and a person's own choice (another sweep, an axis) draws it again in place (`putInPlace`). + +Trials carry the kind of change **Sweep trial** on the Map (a chip and a colour of their own, `--k-sweep-trial`, light and dark). + +## 8. Slices + +| | Slice | Files | +| --- | --- | --- | +| T7a | The kind, the checks, the schedule, the plan, the runner and its tables, the two operations, the map's groups | `tuldok_project/sweeps.py` (new), `schemas/sweep.schema.json` (new), `schemas/recipe.schema.json`, `documents.py`, `check.py`, `graph.py`, `plan.py`, `build_requests.py` (covers), `service.py` (dispatch, the reads), `store.py` (the tables), `operations.py`, `workspace.py`, `comparing.py` (`sweep` left out), `docs/contracts/project-folder.md`, `tests/test_tuldok_project_sweeps.py` (new), `tests/project_sweep_stand_in.py` (new), the service test's count | +| T7b | The Sweeps tab | `static/project-workspace/sweeps.js`, `sweeps.css` (new), `app.js` (the tab, the address), `adapter.js` (the kind), `parallel.js` (its selection and colours given by the caller), `static/project-workspace.html`, `app.py` (assets), `tests/browser_project_workspace_sweeps.cjs` (new) | + +## 9. Tests + +**T7a, `tests/test_tuldok_project_sweeps.py`:** the definition (schema and checker: each field, the paths against the recipe, a grid without count, the warning past the budget, the trial's `sweep` block and its edge); the grid and random schedules against the test's own arithmetic (product order, log points, rounding, integers, duplicates dropped, exhaustion); halving's decisions on fixture metrics logs against the test's arithmetic (rungs crossed together, values before the rung, n < factor, ties); budget enforcement (trials, minutes); the trial's text and its derivation link, reuse and the `-2` name; the plan of a sweep and its covers; end to end through a started `Service` with the stand-in `tests/project_sweep_stand_in.py` (plain Python, logging through `tuldok_log`, about a second a trial, its loss falling to a floor set by its settings): an agent's request approved once, trials run one after another, the poor ones pruned by halving, within the trials budget; a second sweep stopped by its minutes; the trials on the map in the sweep's group; the two reads; the operations in `project_folder` and not in `catalog`, the digest unchanged. + +**T7b, `tests/browser_project_workspace_sweeps.cjs`:** on a fixture with the stand-in: a sweep made with New sweep and kept; asked for by an agent and approved on the tab; while the trials run the state block's counts and the latest step change across readings with the block the same element and no node of it added or removed; the frontier and parallel coordinates show every trial; a trial opens on the Map; light and dark, 1440 and 390 wide, no sideways overflow, no script error, no failed request. + +**Regressions:** the project suite, the agent interface tests, `browser_project_workspace.cjs`, `_actions.cjs`, `_training.cjs`, `_compare.cjs`. + +## 10. Out of scope + +Running trials at once or on other machines; resuming a pruned trial (no checkpoint contract); Bayesian or other model-based strategies; benchmark objectives (section 1); a control keeping only a sweep's winners; any GPU run (the strategy is the same, the owner's word is needed first); the lab's models. From 362a677f8ca43d7144c2b71fe1fee975b6a0c1be Mon Sep 17 00:00:00 2001 From: MrScripty <TheEnvironmentGuy@protonmail.com> Date: Thu, 19 Nov 2026 08:20:16 -0700 Subject: [PATCH 123/131] feat(project): sweeps, a search over a recipe's settings run one trial after another A sweep definition (sweeps/<name>.json) names a recipe, the settings it varies, a strategy (grid, random, successive halving), one or two objectives from the trials' training logs and a budget. A build request for it alone covers the sweep, the recipe and what the recipe needs; the worker runs each trial as a derived recipe kept in the working copy, stops one that halving prunes or that outlasts the minutes, and records the runs and trials. Two reads, sweeps and sweep, and the map's groups of trials. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --- tests/project_sweep_stand_in.py | 59 ++ tests/test_tuldok_project_check.py | 3 +- tests/test_tuldok_project_service.py | 7 +- tests/test_tuldok_project_sweeps.py | 655 +++++++++++++ tuldok_project/build_requests.py | 3 +- tuldok_project/check.py | 2 + tuldok_project/comparing.py | 2 +- tuldok_project/documents.py | 3 + tuldok_project/graph.py | 6 +- tuldok_project/operations.py | 11 +- tuldok_project/plan.py | 3 + tuldok_project/schemas/recipe.schema.json | 27 +- tuldok_project/schemas/sweep.schema.json | 335 +++++++ tuldok_project/service.py | 20 +- tuldok_project/store.py | 3 +- tuldok_project/sweeps.py | 1068 +++++++++++++++++++++ tuldok_project/workspace.py | 4 +- 17 files changed, 2198 insertions(+), 13 deletions(-) create mode 100644 tests/project_sweep_stand_in.py create mode 100644 tests/test_tuldok_project_sweeps.py create mode 100644 tuldok_project/schemas/sweep.schema.json create mode 100644 tuldok_project/sweeps.py diff --git a/tests/project_sweep_stand_in.py b/tests/project_sweep_stand_in.py new file mode 100644 index 00000000..43d2cfe1 --- /dev/null +++ b/tests/project_sweep_stand_in.py @@ -0,0 +1,59 @@ +"""A stand-in training script for the sweep tests (docs/plans/training-and-curation/spec-t7.md): it trains nothing. + +It reads its settings file (learning_rate, width, steps, sleep) and logs +through tuldok_log, as a project's script would, one line a step: a loss +falling towards a floor that its settings decide, and a validation loss every +five steps. The floor is lowest at a learning rate of 0.01 and a wide model: + + floor = 0.1 * (log10(learning_rate) + 2) ** 2 + 1 / width + loss(step) = floor + exp(-step / 8) + +so every trial's curve has the same shape and trials are ordered by their +floor at every step, which lets a test say which trials halving keeps. It +sleeps `sleep` seconds a step (about a second a trial by default) and writes +weights.json at the end, the recipe's declared output. + + python project_sweep_stand_in.py --settings <settings.json> --out <output> +""" +import argparse +import json +import math +import os +import time + +from tuldok_log import Logger + + +def floor(learning_rate, width): + return 0.1 * (math.log10(learning_rate) + 2) ** 2 + 1 / width + + +def main(): + parser = argparse.ArgumentParser() + parser.add_argument('--settings', required=True) + parser.add_argument('--out', required=True) + arguments = parser.parse_args() + with open(arguments.settings, encoding='utf-8') as handle: + settings = json.load(handle) + learning_rate = float(settings.get('learning_rate', 0.01)) + width = int(settings.get('width', 8)) + steps = int(settings.get('steps', 20)) + pause = float(settings.get('sleep', 0.05)) + os.makedirs(arguments.out, exist_ok=True) + bottom = floor(learning_rate, width) + with Logger(arguments.out) as log: + for step in range(1, steps + 1): + time.sleep(pause) + loss = bottom + math.exp(-step / 8) + if step % 5 == 0: + log.log(step, loss=loss, **{'val/loss': loss * 1.1}) + else: + log.log(step, loss=loss) + print(json.dumps({'format': 'tuldok_progress_v1', 'stage': 'training', 'completed': step, + 'total': steps, 'metrics': {'loss': loss}}), flush=True) + with open(os.path.join(arguments.out, 'weights.json'), 'w', encoding='utf-8') as handle: + json.dump({'learning_rate': learning_rate, 'width': width, 'floor': bottom}, handle) + + +if __name__ == '__main__': + main() diff --git a/tests/test_tuldok_project_check.py b/tests/test_tuldok_project_check.py index d6a62ff8..cd0b8836 100644 --- a/tests/test_tuldok_project_check.py +++ b/tests/test_tuldok_project_check.py @@ -106,7 +106,8 @@ def test_fixture_has_no_problems_and_parses_the_project(self): report = check_folder(self.project) self.assertClean(report) self.assertEqual(report.project['code_root'], '../code') - self.assertEqual({d.kind for d in report.definitions.values()}, set(documents.DIRECTORIES)) + # Every kind but a sweep, whose tests write their own projects (test_tuldok_project_sweeps). + self.assertEqual({d.kind for d in report.definitions.values()}, set(documents.DIRECTORIES) - {'sweep'}) self.assertIn(graph.Edge('recipes/stepper-k2', 'recipes/stepper-k1', 'input:start'), report.edges) waves = report.definitions['datasets/waves'] self.assertEqual((waves.kind, waves.name, waves.path), ('dataset', 'waves', 'datasets/waves.json')) diff --git a/tests/test_tuldok_project_service.py b/tests/test_tuldok_project_service.py index 56533f02..20263e88 100644 --- a/tests/test_tuldok_project_service.py +++ b/tests/test_tuldok_project_service.py @@ -48,7 +48,7 @@ class Table(unittest.TestCase): def test_every_operation_is_declared_once(self): names = [operation.name for operation in operations.OPERATIONS] - self.assertEqual(len(names), 83) # the rows of spec-m7.md section 2, of section 2 of spec-w1.md and spec-w3.md, of section 3 of spec-d1.md and spec-d2.md, of section 5 of spec-d4.md, of sections 2 and 4 of spec-d5.md, of section 2 of spec-d6.md, of section 3 of spec-t2.md, of section 4 of spec-t1.md, of sections 2 to 4 of spec-t3.md and spec-t5.md (7), and of section 6 of spec-t4.md (4) + self.assertEqual(len(names), 85) # the rows of spec-m7.md section 2, of section 2 of spec-w1.md and spec-w3.md, of section 3 of spec-d1.md and spec-d2.md, of section 5 of spec-d4.md, of sections 2 and 4 of spec-d5.md, of section 2 of spec-d6.md, of section 3 of spec-t2.md, of section 4 of spec-t1.md, of sections 2 to 4 of spec-t3.md and spec-t5.md (7), of section 6 of spec-t4.md (4), and of section 6 of spec-t7.md (2) self.assertEqual(len(set(names)), len(names)) for name in REQUEST_OPERATIONS: self.assertIsNotNone(operations.by_name(name)) @@ -234,6 +234,8 @@ def test_every_read(self): 'embedding_duplicates': {'run': run_id, 'name': 'none-here'}, 'embedding_outliers': {'run': run_id, 'name': 'none-here'}, 'embedding_leakage': {'run': run_id, 'name': 'none-here'}, + 'sweeps': {}, + 'sweep': {'sweep': 'none-here'}, } reads = [operation for operation in operations.OPERATIONS if not operation.mutation] arguments['build_requests'] = {'state': 'queued', 'limit': 5} @@ -274,6 +276,9 @@ def test_every_read(self): if operation.name.startswith('embedding_'): # no embeddings here; test_tuldok_project_curation self.assertEqual(self.refused(operation.name, arguments[operation.name]).code, 'not-found') continue + if operation.name == 'sweep': # this fixture has no sweep; read in test_tuldok_project_sweeps + self.assertEqual(self.refused(operation.name, arguments['sweep']).code, 'not-found') + continue if operation.name == 'note': # this fixture has no notes; read in test_tuldok_project_workspace self.assertEqual(self.refused(operation.name, arguments['note']).code, 'not-found') continue diff --git a/tests/test_tuldok_project_sweeps.py b/tests/test_tuldok_project_sweeps.py new file mode 100644 index 00000000..6a6a4484 --- /dev/null +++ b/tests/test_tuldok_project_sweeps.py @@ -0,0 +1,655 @@ +"""Sweeps (docs/plans/training-and-curation/spec-t7.md): the definition, the schedule, halving, trials and the runs. + +The schedule, halving's decisions and a trial's text are checked against the +test's own arithmetic without a database. The rest needs a database and runs +only when TULDOK_DATABASE_URL names a disposable cluster: a project written +by the test, committed to a Git repository of its own, whose recipe runs the +stand-in tests/project_sweep_stand_in.py (plain Python, logging through +tuldok_log, about a second a trial, its loss falling to a floor its settings +decide) with this interpreter. No GPU is used. +""" +import hashlib +import itertools +import json +import math +import os +from pathlib import Path +import random +import shutil +import subprocess +import sys +import tempfile +import time +import unittest +from unittest import mock + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) +sys.path.insert(0, str(Path(__file__).resolve().parent)) + +import agent_api # noqa: E402 +from tuldok_project import (builds, check, environments, launcher, local, operations, plan, # noqa: E402 + service as service_module, store, sweeps, training) +from tuldok_project.service import Service # noqa: E402 +from tuldok_project.store import ProjectError # noqa: E402 + +REPOSITORY = Path(__file__).resolve().parents[1] +STAND_IN = Path(__file__).resolve().parent / 'project_sweep_stand_in.py' +DATABASE = os.environ.get('TULDOK_DATABASE_URL') +GIT = ['git', '-c', 'user.name=Tuldok Test', '-c', 'user.email=test@example.invalid', '-c', 'commit.gpgsign=false'] +ALL_SCOPES = ['admin', 'approve-execution', 'approve-review', 'cancel', 'edit', 'execute', 'expose-holdout', + 'freeze', 'inspect'] +OWNER = {'actor_id': 'owner-1', 'kind': 'owner', 'label': 'The owner', 'scopes': ALL_SCOPES} +AGENT = {'actor_id': 'agent-1', 'kind': 'agent', 'label': 'An agent', 'scopes': ['inspect', 'execute', 'cancel']} +ENDED = ('succeeded', 'failed', 'cancelled', 'declined', 'expired') + + +def r6(value): + return float(f'{value:.6g}') + + +def floor(learning_rate, width): + """The stand-in's floor (tests/project_sweep_stand_in.py).""" + return 0.1 * (math.log10(learning_rate) + 2) ** 2 + 1 / width + + +def recipe(settings, group=None): + document = {'format': 'tuldok_definition_v1', 'kind': 'recipe', 'title': 'The stand-in', + 'run': {'command': ['python', 'stand_in.py', '--settings', '{settings}', '--out', '{output}'], + 'environment': 'environments/here', 'settings': settings, + 'env': {'PYTHONPATH': str(REPOSITORY)}, + 'outputs': {'weights': {'path': 'weights.json', 'role': 'weights'}}, + 'sources': ['stand_in.py']}} + if group: + document['group'] = group + return document + + +def sweep(**fields): + document = {'format': 'tuldok_definition_v1', 'kind': 'sweep', 'title': 'Learning rate and width', + 'recipe': 'recipes/base', + 'parameters': [{'path': 'learning_rate', 'low': 0.001, 'high': 0.1, 'scale': 'log'}, + {'path': 'width', 'values': [4, 8, 16, 32]}], + 'strategy': {'kind': 'random', 'seed': 7}, + 'objectives': [{'metric': 'loss', 'better': 'lower'}], + 'budget': {'trials': 4}} + document.update(fields) + return document + + +# ======================================================================= the schedule + +class Schedule(unittest.TestCase): + + def test_a_grid_is_the_product_in_order_with_its_points_rounded(self): + document = sweep(parameters=[{'path': 'a', 'values': ['x', 'y']}, + {'path': 'b', 'low': 0.001, 'high': 0.1, 'scale': 'log', 'count': 3}, + {'path': 'c', 'low': 1, 'high': 2, 'integer': True, 'count': 5}], + strategy={'kind': 'grid'}) + b = [r6(math.exp(math.log(0.001) + i * (math.log(0.1) - math.log(0.001)) / 2)) for i in range(3)] + c = [] + for i in range(5): # 1, 1.25, 1.5, 1.75, 2 -> floor(x + 0.5): 1, 1, 2, 2, 2 + whole = math.floor(1 + i * 0.25 + 0.5) + if whole not in c: + c.append(whole) + self.assertEqual(c, [1, 2]) + expected = [{'a': a, 'b': bv, 'c': cv} for a, bv, cv in itertools.product(['x', 'y'], b, c)] + self.assertEqual(list(sweeps.schedule(document)), expected) + self.assertEqual(b, [0.001, 0.01, 0.1]) + + def test_random_draws_follow_the_seed_and_drop_repeats(self): + document = sweep() + rng = random.Random(7) + expected, seen = [], set() + while len(expected) < 30: + u = rng.random() + lr = r6(math.exp(math.log(0.001) + u * (math.log(0.1) - math.log(0.001)))) + width = [4, 8, 16, 32][rng.randrange(4)] + if (lr, width) in seen: + continue + seen.add((lr, width)) + expected.append({'learning_rate': lr, 'width': width}) + self.assertEqual(list(itertools.islice(sweeps.schedule(document), 30)), expected) + + def test_a_small_space_is_exhausted(self): + document = sweep(parameters=[{'path': 'width', 'values': [4, 8]}, {'path': 'deep', 'values': [True, False]}]) + drawn = list(sweeps.schedule(document)) + self.assertEqual(len(drawn), 4) + self.assertEqual({(item['width'], item['deep']) for item in drawn}, + {(4, True), (4, False), (8, True), (8, False)}) + + def test_one_and_one_point_zero_are_the_same_draw(self): + document = sweep(parameters=[{'path': 'x', 'values': [1, 1.0]}]) + self.assertEqual(len(list(sweeps.schedule(document))), 1) + + +# ======================================================================= halving + +class FakeConnection: + def __init__(self): + self.calls = [] + + def execute(self, query, parameters=None): + self.calls.append(parameters) + + +def write_log(directory, lines): + path = Path(directory) / 'output' / 'training' + path.mkdir(parents=True, exist_ok=True) + with open(path / 'metrics.jsonl', 'a', encoding='utf-8') as handle: + for line in lines: + handle.write(json.dumps(line) + '\n') + + +class Halving(unittest.TestCase): + STRATEGY = {'kind': 'halving', 'seed': 1, 'metric': 'loss', 'better': 'lower', 'min': 2, 'factor': 2} + + def setUp(self): + directory = tempfile.TemporaryDirectory() + self.addCleanup(directory.cleanup) + self.base = Path(directory.name) + self.addCleanup(training.forget) + + def watch(self, name, recorded, lines, strategy=None): + """A watcher of a trial whose log holds lines, read once as the runner reads it.""" + document = sweep(strategy=strategy or self.STRATEGY) + directory = self.base / name + write_log(directory, lines) + watch = sweeps._Watch(document, FakeConnection(), 's', 'run', 1, recorded, None, time.monotonic) + watch.directory, watch.output, watch.run_id = str(directory), str(directory / 'output'), name + watch.look() + return watch + + def test_rungs_and_their_crossing(self): + self.assertEqual(sweeps.rung_points(self.STRATEGY)[:4], [2, 4, 8, 16]) + self.assertEqual(sweeps.rung_points({**self.STRATEGY, 'unit': 'time', 'min': 0.5, 'factor': 3})[:3], + [0.5, 1.5, 4.5]) + rungs = sweeps.Rungs([2, 4, 8]) + self.assertEqual(rungs.feed(1, 0.9), []) + self.assertEqual(rungs.feed(5, 0.7), [(0, 2, 0.7), (1, 4, 0.7)]) # one line crossing two rungs + self.assertEqual(rungs.feed(5, 0.6), []) + self.assertEqual(rungs.feed(9, None), [(2, 8, None)]) + + def test_goes_on(self): + self.assertEqual(sweeps.goes_on(5.0, [], 'lower', 3), (True, 1, 1)) + self.assertEqual(sweeps.goes_on(5.0, [1.0], 'lower', 3), (True, 2, 1)) # n < factor + self.assertEqual(sweeps.goes_on(5.0, [1.0, 2.0], 'lower', 3), (False, 3, 1)) + self.assertEqual(sweeps.goes_on(0.5, [1.0, 2.0], 'lower', 3), (True, 3, 1)) + self.assertEqual(sweeps.goes_on(1.0, [1.0, 2.0], 'lower', 3), (True, 3, 1)) # a tie is not better + self.assertEqual(sweeps.goes_on(1.5, [1.0, 2.0, 3.0], 'lower', 3), (True, 4, 2)) + self.assertEqual(sweeps.goes_on(1.5, [1.0, 2.0, 3.0], 'higher', 3), (False, 4, 2)) + + def test_decisions_on_logs(self): + recorded = {} + # The value at a rung is the latest finite value on the line reaching it or before: here the line of + # step 3 (no loss) reaches rung 2 with 0.8, the loss of step 1. + first = self.watch('a', recorded, [{'step': 1, 'time': 0.1, 'loss': 0.8}, {'step': 3, 'time': 0.2}, + {'step': 4, 'time': 0.3, 'loss': 0.6}]) + self.assertEqual([(r['rung'], r['value'], r['goes_on']) for r in first.reached], [(0, 0.8, True), (1, 0.6, True)]) + self.assertIsNone(first.reason) + # A second trial worse at rung 2: n = 2 = factor, kept 1, one better: pruned, its cancel file written. + second = self.watch('b', recorded, [{'step': 2, 'time': 0.1, 'loss': 0.9}, {'step': 4, 'time': 0.2, 'loss': 0.1}]) + self.assertEqual([(r['rung'], r['value'], r['n'], r['kept'], r['goes_on']) for r in second.reached], + [(0, 0.9, 2, 1, False)]) + self.assertEqual(second.reason, 'pruned') + self.assertTrue((self.base / 'b' / launcher.CANCEL_FILE).exists()) + self.assertIn('rung 1 (step 2)', second.problem) + # A third, better at both rungs: n = 3, kept 2. + third = self.watch('c', recorded, [{'step': 2, 'time': 0.1, 'loss': 0.5}, {'step': 4, 'time': 0.2, 'loss': 0.4}]) + self.assertEqual([(r['n'], r['kept'], r['goes_on']) for r in third.reached], [(3, 2, True), (2, 1, True)]) + self.assertEqual(recorded, {0: [0.8, 0.9, 0.5], 1: [0.6, 0.4]}) + # A trial with no value of the metric records nothing and goes on. + fourth = self.watch('d', recorded, [{'step': 2, 'time': 0.1, 'other': 1.0}]) + self.assertEqual(fourth.reached, []) + self.assertIsNone(fourth.reason) + + def test_appended_lines_are_read_on(self): + recorded = {0: [0.1]} + watch = self.watch('a', recorded, [{'step': 1, 'time': 0.1, 'loss': 0.9}]) + self.assertEqual(watch.reached, []) + write_log(self.base / 'a', [{'step': 2, 'time': 0.2, 'loss': 0.95}]) + watch.look() + self.assertEqual(watch.reason, 'pruned') + self.assertEqual(watch.latest, {'loss': 0.95}) + + def test_minutes_stop_a_trial(self): + document = sweep() + directory = self.base / 'late' + write_log(directory, [{'step': 1, 'time': 0.1, 'loss': 0.9}]) + watch = sweeps._Watch(document, FakeConnection(), 's', 'run', 1, {}, 10.0, lambda: 11.0) + watch.directory, watch.output, watch.run_id = str(directory), str(directory / 'output'), 'late' + watch.look() + self.assertEqual(watch.reason, 'minutes') + self.assertTrue((directory / launcher.CANCEL_FILE).exists()) + + +# ======================================================================= a trial's definition + +class Trial(unittest.TestCase): + + def test_the_text_of_a_trial(self): + base = recipe({'training': {'learning_rate': 0.01, 'schedule': [{'lr': 1}, {'lr': 2}]}, 'width': 8}, + group='small') + base['card'] = 'notes/x.md' + base['labels'] = {'short': 'B'} + base['compared_with'] = [{'recipe': 'recipes/other', 'explanation': 'x'}] + base['model'] = 'models/m' + document = sweep(title='A search') + values = {'training.learning_rate': 0.003, 'training.schedule.1.lr': 5, 'width': 16} + text = sweeps.trial_text('sweeps/s', document, 'recipes/base', base, 3, values) + made = json.loads(text) + self.assertTrue(text.endswith('}\n')) + self.assertEqual(made['title'], 'A search · trial 3') + self.assertEqual((made['derived_from'], made['change'], made['group'], made['model'], made['labels']), + ('recipes/base', 'sweep-trial', 'small', 'models/m', {'short': 'T3'})) + self.assertEqual(made['sweep'], {'definition': 'sweeps/s', 'trial': 3, 'values': values}) + self.assertEqual(made['run']['settings'], {'training': {'learning_rate': 0.003, + 'schedule': [{'lr': 1}, {'lr': 5}]}, 'width': 16}) + self.assertNotIn('card', made) + self.assertNotIn('compared_with', made) + self.assertEqual(base['run']['settings']['width'], 8) # the recipe is not changed + self.assertEqual(made['description'], + 'Trial 3 of sweeps/s: training.learning_rate = 0.003, training.schedule.1.lr = 5, width = 16.') + + def test_names_never_overwrite(self): + self.assertEqual(sweeps.place_trial({}, 'sweeps/s', 7, 'A'), ('recipes/s-007', False)) + self.assertEqual(sweeps.place_trial({'recipes/s-007': 'A'}, 'sweeps/s', 7, 'A'), ('recipes/s-007', True)) + self.assertEqual(sweeps.place_trial({'recipes/s-007': 'B'}, 'sweeps/s', 7, 'A'), ('recipes/s-007-2', False)) + self.assertEqual(sweeps.place_trial({'recipes/s-007': 'B', 'recipes/s-007-2': 'C'}, 'sweeps/s', 7, 'A'), + ('recipes/s-007-3', False)) + self.assertEqual(sweeps.place_trial({}, 'sweeps/' + 'x' * 120, 1000, 'A')[0], 'recipes/' + 'x' * 100 + '-1000') + + def test_paths(self): + settings = {'a': {'b': [1, {'c': 2}]}, 'n': 3} + self.assertIsNone(sweeps.path_problem(settings, 'a.b.1.c')) + self.assertIsNone(sweeps.path_problem(settings, 'a.new')) + self.assertIn('not in the recipe', sweeps.path_problem(settings, 'x.y')) + self.assertIn('not an object or a list', sweeps.path_problem(settings, 'n.y')) + self.assertIn('past its end', sweeps.path_problem(settings, 'a.b.2')) + + +# ======================================================================= the checker + +class Checking(unittest.TestCase): + + def setUp(self): + directory = tempfile.TemporaryDirectory() + self.addCleanup(directory.cleanup) + self.folder = Path(directory.name) / 'project' + for part in ('recipes', 'sweeps', 'environments'): + (self.folder / part).mkdir(parents=True) + (self.folder / 'tuldok.json').write_text(json.dumps({'format': 'tuldok_project_v1', 'id': 'a' * 32, + 'name': 'Sweeps', 'code_root': '.'})) + self.write('environments/here', {'format': 'tuldok_definition_v1', 'kind': 'environment', 'title': 'Here', + 'python': '3.12', 'device': 'cpu', 'packages': {'jsonschema': '4.26.0'}}) + self.write('recipes/base', recipe({'learning_rate': 0.01, 'width': 8, 'nested': {'depth': 2}})) + + def write(self, reference, document): + (self.folder / f'{reference}.json').write_text(json.dumps(document, indent=2) + '\n') + + def problems(self, document, name='s'): + self.write(f'sweeps/{name}', document) + report = check.check_folder(self.folder, code=False) + return [(p.severity, p.path, p.pointer, p.message) for p in report.problems] + + def test_a_good_sweep_checks(self): + self.assertEqual(self.problems(sweep()), []) + + def test_the_schema(self): + found = self.problems(sweep(parameters=[{'path': 'learning_rate', 'values': [1], 'low': 0, 'high': 1}], + strategy={'kind': 'halving', 'seed': 1}, objectives=[], budget={'trials': 0, + 'concurrency': 2})) + pointers = {pointer for _, _, pointer, _ in found} + self.assertTrue({'/parameters/0', '/strategy/metric', '/objectives', '/budget/trials', '/budget/concurrency'} + <= pointers, found) + + def test_rules_beyond_the_schema(self): + found = self.problems(sweep(parameters=[{'path': 'learning_rate', 'low': 1, 'high': 0.5}, + {'path': 'learning_rate', 'low': -1, 'high': 1, 'scale': 'log'}, + {'path': 'width.x', 'values': [1, 1]}, + {'path': 'missing.y', 'values': [1]}, + {'path': 'steps', 'low': 1.5, 'high': 3, 'integer': True}], + objectives=[{'metric': 'loss', 'better': 'lower'}, + {'metric': 'loss', 'better': 'higher'}])) + messages = [(pointer, message) for _, _, pointer, message in found] + self.assertIn(('/parameters/0', 'low (1) must be less than high (0.5).'), messages) + self.assertIn(('/parameters/1/path', 'learning_rate is varied twice; keep one parameter for it.'), messages) + self.assertIn(('/parameters/1/low', 'A log scale needs low above 0.'), messages) + self.assertIn(('/parameters/2/values', 'The values repeat; list each once.'), messages) + self.assertIn(('/parameters/2/path', "width is not an object or a list in the recipe's settings."), messages) + self.assertIn(('/parameters/3/path', "missing is not in the recipe's settings."), messages) + self.assertIn(('/parameters/4', 'An integer range needs whole numbers for low and high.'), messages) + self.assertIn(('/objectives', 'The two objectives name the same metric; name two.'), messages) + + def test_a_grid(self): + found = self.problems(sweep(strategy={'kind': 'grid'})) + self.assertIn(('error', 'sweeps/s.json', '/parameters/0', + 'A grid takes count points of a range; add count (2 to 64).'), found) + found = self.problems(sweep(strategy={'kind': 'grid'}, + parameters=[{'path': 'learning_rate', 'low': 0.001, 'high': 0.1, 'count': 3}, + {'path': 'width', 'values': [4, 8]}])) + self.assertEqual(found, [('warning', 'sweeps/s.json', '/budget/trials', + 'The grid has 6 points and the budget 4; the first 4 in order are run.')]) + found = self.problems(sweep(strategy={'kind': 'grid'}, + parameters=[{'path': f'p{i}', 'low': 0, 'high': 1, 'count': 64} for i in range(3)])) + self.assertIn('at most 100,000', found[0][3]) + + def test_the_recipe(self): + found = self.problems(sweep(recipe='recipes/none')) + self.assertTrue(any(pointer == '/recipe' for _, _, pointer, _ in found), found) + filed = recipe({}) + del filed['run']['settings'] + filed['run']['settings_file'] = 'settings.json' + self.write('recipes/filed', filed) + found = self.problems(sweep(recipe='recipes/filed')) + self.assertEqual(len(found), 1) + self.assertIn('its settings are in a file', found[0][3]) + + def test_a_trial_names_a_sweep(self): + self.write('sweeps/s', sweep()) + trial = json.loads(sweeps.trial_text('sweeps/s', sweep(), 'recipes/base', recipe({'learning_rate': 0.01}), 1, + {'learning_rate': 0.02})) + self.write('recipes/s-001', trial) + report = check.check_folder(self.folder, code=False) + self.assertEqual(report.problems, []) + roles = {(edge.from_ref, edge.to_ref, edge.role) for edge in report.edges} + self.assertTrue({('recipes/s-001', 'sweeps/s', 'sweep'), ('sweeps/s', 'recipes/base', 'varies'), + ('recipes/s-001', 'recipes/base', 'derived')} <= roles) + trial['sweep']['definition'] = 'sweeps/gone' + self.write('recipes/s-001', trial) + report = check.check_folder(self.folder, code=False) + self.assertEqual([(p.path, p.pointer) for p in report.problems], [('recipes/s-001.json', '/sweep/definition')]) + + +# ======================================================================= with a database + +def _writable(root): + for current, directories, _files in os.walk(root): + for name in directories: + os.chmod(os.path.join(current, name), 0o755) + if os.path.isdir(root): + os.chmod(root, 0o755) + + +@unittest.skipUnless(DATABASE, 'TULDOK_DATABASE_URL is not set; database tests need a disposable cluster.') +class SweepCase(unittest.TestCase): + """A project written by the test: the stand-in as recipes/base, committed, its environment connected.""" + + SETTINGS = {'learning_rate': 0.01, 'width': 8, 'steps': 40, 'sleep': 0.03} + + def setUp(self): + directory = tempfile.TemporaryDirectory() + self.addCleanup(directory.cleanup) + self.temporary = Path(directory.name) + self.home = self.temporary / 'home' + self.addCleanup(_writable, self.home) + patcher = mock.patch.dict(os.environ, {local.HOME_VARIABLE: str(self.home)}) + patcher.start() + self.addCleanup(patcher.stop) + patcher = mock.patch.object(service_module, 'POLL_SECONDS', 0.1) + patcher.start() + self.addCleanup(patcher.stop) + self.addCleanup(training.forget) + self.root = self.temporary / 'repo' + self.folder = self.root / 'project' + code = self.root / 'code' + code.mkdir(parents=True) + shutil.copy(STAND_IN, code / 'stand_in.py') + for part in ('recipes', 'sweeps', 'environments'): + (self.folder / part).mkdir(parents=True) + self.project_id = __import__('uuid').uuid4().hex + (self.folder / 'tuldok.json').write_text(json.dumps({ + 'format': 'tuldok_project_v1', 'id': self.project_id, 'name': 'Sweeps', 'code_root': '../code', + 'groups': [{'id': 'small', 'title': 'Small models'}]}, indent=2) + '\n') + self.write('environments/here', {'format': 'tuldok_definition_v1', 'kind': 'environment', 'title': 'Here', + 'python': f'{sys.version_info[0]}.{sys.version_info[1]}', 'device': 'cpu', + 'packages': {'jsonschema': '4.26.0'}}) + self.write('recipes/base', recipe(dict(self.SETTINGS), group='small')) + self.git('init', '-q') + self.commit('The project.') + self.addCleanup(store.drop_project, self.project_id) + with builds.opened(self.folder) as project: + self.assertTrue(environments.connect(project, 'environments/here', sys.executable)['ok']) + self.addCleanup(self.stop_everything) + + def stop_everything(self): + try: + with builds.opened(self.folder) as project: + run_ids = [row[0] for row in project._execute('SELECT id FROM {schema}.runs').fetchall()] + except Exception: + run_ids = [] + for run_id in run_ids: + launcher.stop_strays(run_id) + + def write(self, reference, document): + (self.folder / f'{reference}.json').write_text(json.dumps(document, indent=2) + '\n') + + def git(self, *arguments): + subprocess.run([*GIT, '-C', str(self.root), *arguments], check=True, capture_output=True, timeout=60) + + def commit(self, message): + self.git('add', '-A') + self.git('commit', '-q', '-m', message) + + def keep(self, reference, document): + """Keep a definition through the store and save it, as the page does, then commit the folder.""" + with builds.opened(self.folder) as project: + project.set_definition(reference, json.dumps(document, indent=2) + '\n') + project.save() + self.commit(f'{reference}.') + + def service(self): + made = Service(self.folder) + self.addCleanup(made.close) + made.start() + return made + + def wait_for(self, served, request_id, seconds=120): + deadline = time.monotonic() + seconds + while True: + shown = served.call('build_request', {'request': request_id}, OWNER) + if shown['state'] in ENDED: + return shown + self.assertLess(time.monotonic(), deadline, f'request still {shown["state"]}') + time.sleep(0.1) + + +class Planning(SweepCase): + + def test_a_sweep_is_planned_alone_and_covers_its_recipe(self): + self.keep('sweeps/s', sweep()) + with builds.opened(self.folder) as project: + made = plan.build_plan(project, ['sweeps/s']) + self.assertEqual(made['targets'], ['sweeps/s']) + self.assertEqual([(step['reference'], step['kind'], step['action']) for step in made['steps']], + [('environments/here', 'environment', 'ready'), ('sweeps/s', 'sweep', 'build')]) + step = made['steps'][-1] + self.assertEqual((step['recipe'], step['trials'], step['state']), ('recipes/base', 4, 'not-built')) + self.assertTrue(made['buildable']) + self.assertEqual(made['counts']['build'], 1) + from tuldok_project import build_requests + covered = build_requests.covers(project, made, ['sweeps/s'], every=False, scratch=False) + self.assertEqual(set(covered['definitions']), {'environments/here', 'sweeps/s', 'recipes/base'}) + self.assertEqual(covered['steps'], [{'reference': 'sweeps/s', 'subjects': []}]) + for targets, every in ((['sweeps/s', 'recipes/base'], False), (['sweeps/s'], True)): + with self.assertRaises(ProjectError) as refused: + plan.build_plan(project, targets, every=every) + self.assertEqual(refused.exception.code, 'invalid') + + +class Running(SweepCase): + + def test_halving_through_a_service_approved_once(self): + strategy = {'kind': 'halving', 'seed': 3, 'metric': 'loss', 'better': 'lower', 'min': 2, 'factor': 2} + self.keep('sweeps/s', sweep(strategy=strategy, budget={'trials': 6}, + objectives=[{'metric': 'loss', 'better': 'lower'}, + {'metric': 'time', 'better': 'lower', 'title': 'Seconds'}])) + served = self.service() + asked = served.call('request_build', {'targets': ['sweeps/s']}, AGENT) + self.assertEqual(asked['state'], 'awaiting-approval') + self.assertEqual(served.call('sweep', {'sweep': 's'}, OWNER)['request']['state'], 'awaiting-approval') + served.call('approve_build', {'request': asked['id']}, OWNER) + done = self.wait_for(served, asked['id']) + self.assertEqual(done['state'], 'succeeded', done['problem']) + shown = served.call('sweep', {'sweep': 'sweeps/s'}, OWNER) + json.dumps(shown, allow_nan=False) + trials = shown['trials'] + # The test's arithmetic: the schedule, each trial's floor, and halving's rule over the rungs 2, 4, 8, 16, 32. + values = list(itertools.islice(sweeps.schedule(sweep(strategy=strategy)), 6)) + self.assertEqual([trial['values'] for trial in trials], values) + recorded, expected = {}, [] + for item in values: + bottom = floor(item['learning_rate'], item['width']) + state = 'completed' + for rung, point in enumerate([2, 4, 8, 16, 32]): + value = bottom + math.exp(-point / 8) + held = recorded.setdefault(rung, []) + n = len(held) + 1 + better = sum(1 for other in held if other < value) + held.append(value) + if n >= 2 and better >= math.ceil(n / 2): + state = 'pruned' + break + expected.append(state) + self.assertIn('pruned', expected) + self.assertEqual([trial['state'] for trial in trials], expected) + self.assertEqual(shown['run']['counts']['pruned'], expected.count('pruned')) + self.assertEqual((shown['run']['state'], shown['run']['ended'], shown['state']), ('finished', 'trials', 'built')) + for trial, item in zip(trials, values): + if trial['state'] == 'completed': + self.assertAlmostEqual(trial['objectives']['loss'], floor(item['learning_rate'], item['width']) + + math.exp(-40 / 8)) + else: + self.assertTrue(trial['problem'].startswith('Pruned by successive halving')) + self.assertLess(trial['latest']['step'], 40) + completed = [trial for trial in trials if trial['state'] == 'completed'] + best = min(completed, key=lambda trial: trial['objectives']['loss']) + self.assertEqual(shown['best'], {'number': best['number'], 'reference': best['reference'], + 'value': best['objectives']['loss']}) + self.assertTrue(set(shown['frontier']) <= {trial['number'] for trial in completed}) + self.assertIn(best['number'], shown['frontier']) + # The trials as axes: the objectives and the two parameters, one subject a trial. + axes = shown['axes'] + self.assertEqual([metric['id'] for metric in axes['metrics']], ['loss', 'time']) + self.assertEqual([(axis['path'], axis['kind']) for axis in axes['settings']], + [('learning_rate', 'number'), ('width', 'number')]) + self.assertEqual(len(axes['subjects']), 6) + # One approval: one request, one plan id over every run, every run of a trial. + runs = served.call('runs', {}, OWNER)['runs'] + self.assertEqual({run['plan_id'] for run in runs}, {done['plan_id']}) + self.assertEqual(sorted(run['reference'] for run in runs), sorted(trial['reference'] for trial in trials)) + self.assertEqual(len(done['runs']), 6) + pruned = [trial for trial in trials if trial['state'] == 'pruned'] + for trial in pruned: + run = served.call('run', {'run': trial['run_id']}, OWNER) + self.assertEqual(run['state'], 'cancelled') + self.assertEqual(run['problem'], trial['problem']) + # Trials are recipes, unsaved, derived from the recipe, grouped under the sweep on the map. + status = served.call('status', {}, OWNER) + self.assertEqual(status['unsaved'], sorted(trial['reference'] for trial in trials)) + trial = served.call('definition', {'reference': trials[0]['reference']}, OWNER) + self.assertEqual((trial['document']['derived_from'], trial['document']['change'], + trial['document']['sweep']['values']), ('recipes/base', 'sweep-trial', values[0])) + made = served.call('map', {}, OWNER) + group = [g for g in made['groups'] if g['id'] == 'sweeps/s'] + self.assertEqual(group, [{'id': 'sweeps/s', 'title': 'Learning rate and width', 'parent': 'small', + 'description': 'The trials of sweeps/s, a search over the settings of recipes/base.', + 'models': 6, 'sweep': True}]) + models = {model['reference']: model for model in made['models']} + self.assertEqual({models[trial['reference']]['group'] for trial in trials}, {'sweeps/s'}) + self.assertNotIn('sweep', models['recipes/base']) # only a trial and a sweep's group carry it + self.assertEqual((models[trials[0]['reference']]['sweep'], models[trials[0]['reference']]['derived_from']), + ('sweeps/s', 'recipes/base')) + listed = served.call('sweeps', {}, OWNER)['sweeps'] + self.assertEqual([(item['reference'], item['state'], item['run']['counts']['completed']) for item in listed], + [('sweeps/s', 'built', expected.count('completed'))]) + # Saved, the trials are files of the folder. + served.call('save', {}, OWNER) + self.assertTrue((self.folder / (trials[0]['reference'] + '.json')).exists()) + # Built already: asking again is refused. + self.assertEqual(self.refused(served, 'request_build', {'targets': ['sweeps/s']}), 'nothing-to-build') + + def refused(self, served, name, arguments): + with self.assertRaises(ProjectError) as refused: + served.call(name, arguments, OWNER) + return refused.exception.code + + def test_minutes_stop_a_sweep(self): + self.write('recipes/base', recipe({**self.SETTINGS, 'steps': 30, 'sleep': 0.1}, group='small')) + self.commit('Slower.') + self.keep('sweeps/m', sweep(budget={'trials': 10, 'minutes': 0.06})) + served = self.service() + asked = served.call('request_build', {'targets': ['sweeps/m']}, OWNER) + self.assertEqual(asked['state'], 'queued') + started = time.monotonic() + done = self.wait_for(served, asked['id']) + self.assertEqual(done['state'], 'succeeded', done['problem']) + shown = served.call('sweep', {'sweep': 'm'}, OWNER) + self.assertEqual((shown['run']['state'], shown['run']['ended']), ('finished', 'minutes')) + states = [trial['state'] for trial in shown['trials']] + self.assertEqual(states[-1], 'stopped', states) + self.assertLess(len(states), 10) + self.assertLess(time.monotonic() - started, 30) + self.assertEqual(shown['trials'][-1]['problem'], "The sweep's minutes were spent while it ran.") + + def test_a_grid_reuses_its_built_trials(self): + document = sweep(strategy={'kind': 'grid'}, parameters=[{'path': 'width', 'values': [4, 8, 16]}], + budget={'trials': 2}) + self.write('recipes/base', recipe({**self.SETTINGS, 'steps': 4, 'sleep': 0.01}, group='small')) + self.commit('Quicker.') + self.keep('sweeps/g', document) + with builds.opened(self.folder) as project: + made = plan.build_plan(project, ['sweeps/g']) + first = sweeps.execute(self.folder, made) + self.assertTrue(first['ok']) + self.assertEqual([item['reference'] for item in first['steps']], ['recipes/g-001', 'recipes/g-002']) + with builds.opened(self.folder) as project: + self.assertEqual(plan.build_plan(project, ['sweeps/g'])['steps'][-1]['action'], 'built') + # Another trial taking the name of the third with other settings is never overwritten. + other = json.loads(project.definition('recipes/g-001')['text']) + other['title'] = 'Someone else' + project.set_definition('recipes/g-003', json.dumps(other, indent=2) + '\n') + document['budget'] = {'trials': 3} + self.keep('sweeps/g', document) + with builds.opened(self.folder) as project: + made = plan.build_plan(project, ['sweeps/g']) + self.assertEqual(made['steps'][-1]['state'], 'not-built') + second = sweeps.execute(self.folder, made) + self.assertEqual([item['reference'] for item in second['steps']], ['recipes/g-003-2']) + with builds.opened(self.folder) as project: + shown = sweeps.show(project, 'g') + self.assertEqual([(t['reference'], t['state'], t['reused']) for t in shown['trials']], + [('recipes/g-001', 'completed', True), ('recipes/g-002', 'completed', True), + ('recipes/g-003-2', 'completed', False)]) + self.assertEqual(len(shown['runs']), 2) + self.assertEqual(json.loads(project.definition('recipes/g-003')['text'])['title'], 'Someone else') + self.assertEqual(json.loads(project.definition('recipes/g-003-2')['text'])['sweep']['values'], + {'width': 16}) + + def test_a_stale_definition_is_refused(self): + self.keep('sweeps/s', sweep()) + with builds.opened(self.folder) as project: + made = plan.build_plan(project, ['sweeps/s']) + from tuldok_project import build_requests + covered = build_requests.covers(project, made, ['sweeps/s'], every=False, scratch=False) + covered['definitions']['recipes/base'] = '0' * 64 + with self.assertRaises(ProjectError) as refused: + sweeps.execute(self.folder, made, expect=covered) + self.assertEqual(refused.exception.code, 'stale') + + +class Published(unittest.TestCase): + + def test_the_two_reads_are_in_the_project_folder_profile_and_not_in_the_catalog(self): + for name in ('sweeps', 'sweep'): + operation = operations.by_name(name) + self.assertEqual((operation.who, operation.mutation), ('inspect', False)) + folder = {item['id'] for item in agent_api.capabilities('b' * 32, profile='project_folder')['operations']} + catalog = agent_api.capabilities('b' * 32) + self.assertTrue({'project.sweeps', 'project.sweep'} <= folder) + self.assertFalse({'project.sweeps', 'project.sweep'} & {item['id'] for item in catalog['operations']}) + self.assertEqual((len(catalog['operations']), hashlib.sha256(agent_api.encoded(catalog)).hexdigest()), + (110, 'ad5cc7ac91646b39b7a20b9dfca5ec79ed96ded4b5e36732fcf1145f1cc24460')) + + +if __name__ == '__main__': + unittest.main() diff --git a/tuldok_project/build_requests.py b/tuldok_project/build_requests.py index 53ad8d75..22560ec0 100644 --- a/tuldok_project/build_requests.py +++ b/tuldok_project/build_requests.py @@ -105,7 +105,8 @@ def covers(project, made, targets, *, every, scratch): subjects = [name for name in step['subjects']['run'] if (held.get(name) or {}).get('state') != 'built'] steps.append({'reference': step['reference'], 'subjects': subjects}) references = sorted({step['reference'] for step in made['steps']} - | {task for step in made['steps'] for task in step.get('annotations') or ()}) + | {task for step in made['steps'] for task in step.get('annotations') or ()} + | {step['recipe'] for step in made['steps'] if step['kind'] == 'sweep'}) # spec-t7.md texts = dict(project._execute(f'SELECT {store._REFERENCE_SQL}, text FROM {{schema}}.definitions ' f'WHERE NOT removed AND {store._REFERENCE_SQL} = ANY(%s)', (references,)).fetchall()) return {'targets': list(targets), 'every': bool(every), 'scratch': bool(scratch), diff --git a/tuldok_project/check.py b/tuldok_project/check.py index 59388643..010b92ee 100644 --- a/tuldok_project/check.py +++ b/tuldok_project/check.py @@ -741,6 +741,8 @@ def check_map(project, definitions, add): add('error', folder_reader.PROJECT_FILE, '/map/chart', f'{chart} has the form {target.document.get("form")!r}, not progression; ' 'name a chart of the form progression.') + from . import sweeps # here: sweeps imports store, which imports this module + sweeps.check_sweeps(definitions, add) def _check_results(files, definitions, unsound, add): diff --git a/tuldok_project/comparing.py b/tuldok_project/comparing.py index 1b43183a..8882c989 100644 --- a/tuldok_project/comparing.py +++ b/tuldok_project/comparing.py @@ -36,7 +36,7 @@ STATISTICS = results.STATISTICS # Keys of a definition that say who a model is, not how it is made (left out of the comparison). -IDENTITY = ('format', 'kind', 'title', 'description', 'card', 'labels', 'earlier_work', 'compared_with') +IDENTITY = ('format', 'kind', 'title', 'description', 'card', 'labels', 'earlier_work', 'compared_with', 'sweep') # Keys compared on rows of their own, first. _OWN_ROWS = {'group': 'group', 'change': 'change', 'derived_from': 'parent'} _KIND_ORDER = {'group': 0, 'change': 1, 'parent': 2, 'data': 3, 'setting': 4, 'code': 5} diff --git a/tuldok_project/documents.py b/tuldok_project/documents.py index 93152a24..5f3bf152 100644 --- a/tuldok_project/documents.py +++ b/tuldok_project/documents.py @@ -29,6 +29,7 @@ 'environment': 'environments', 'chart': 'charts', 'annotation': 'annotations', + 'sweep': 'sweeps', # docs/plans/training-and-curation/spec-t7.md section 2 } KINDS = {directory: kind for kind, directory in DIRECTORIES.items()} @@ -48,6 +49,8 @@ 'annotations': ('annotations',), 'derived': ('recipes',), 'compared': ('recipes',), + 'varies': ('recipes',), # a sweep's recipe (spec-t7.md section 2) + 'sweep': ('sweeps',), # a trial's sweep } STATISTICS = ('mean', 'median', 'p10', 'p90', 'min', 'max') diff --git a/tuldok_project/graph.py b/tuldok_project/graph.py index 6c76e594..f1ae52c8 100644 --- a/tuldok_project/graph.py +++ b/tuldok_project/graph.py @@ -20,7 +20,7 @@ from . import documents # Roles that record how recipes relate on the map, not what a build needs. -MAP_ROLES = ('derived', 'compared') +MAP_ROLES = ('derived', 'compared', 'varies', 'sweep') # the last two: a sweep and its trials (spec-t7.md) @dataclass(frozen=True, order=True) @@ -88,6 +88,10 @@ def uses(document): found.append(Use('benchmark', '/benchmark', document['benchmark'])) if kind == 'annotation' and isinstance(document.get('dataset'), str): found.append(Use('dataset', '/dataset', document['dataset'])) + if kind == 'recipe' and isinstance(document.get('sweep'), dict) and isinstance(document['sweep'].get('definition'), str): + found.append(Use('sweep', '/sweep/definition', document['sweep']['definition'])) + if kind == 'sweep' and isinstance(document.get('recipe'), str): + found.append(Use('varies', '/recipe', document['recipe'])) return found diff --git a/tuldok_project/operations.py b/tuldok_project/operations.py index 20d72ee1..26d64b87 100644 --- a/tuldok_project/operations.py +++ b/tuldok_project/operations.py @@ -26,7 +26,7 @@ WHO = ('inspect', 'edit', 'cancel', 'request', 'owner') REQUEST_STATES = ('awaiting-approval', 'queued', 'running', 'succeeded', 'failed', 'cancelled', 'declined', 'expired') -KINDS = ('dataset', 'model', 'recipe', 'benchmark', 'step', 'environment', 'chart', 'annotation') +KINDS = ('dataset', 'model', 'recipe', 'benchmark', 'step', 'environment', 'chart', 'annotation', 'sweep') CHANGES = ('training-policy', 'architecture', 'refinement', 'component') # a recipe's kind of change RECORD_KINDS = ('text', 'image', 'audio', 'pointcloud', 'mesh', 'array', 'file') # the kinds of a product's record TARGET_LIMIT = 50 @@ -126,6 +126,8 @@ def _arguments(required=(), **properties): EMBEDDER = ('model', 'profile', 'prefix', 'named_by', 'default', 'chosen', 'problem', 'embedders') MODEL_GRAPH = ('path', 'format', 'complete', 'reason', 'method', 'torch', 'model', 'inputs', 'notes', 'counts', 'modules', 'tensors', 'depth', 'open', 'nodes', 'edges') +SWEEP = ('reference', 'title', 'description', 'recipe', 'parameters', 'strategy', 'objectives', 'budget', 'state', + 'changed', 'request', 'run', 'runs', 'trials', 'best', 'frontier', 'rungs', 'axes') _STATISTIC = {'type': 'string', 'enum': ['mean', 'median', 'p10', 'p90', 'min', 'max']} _MODULE_PATHS = {'type': 'array', 'items': {'type': 'string', 'maxLength': 1024}, 'maxItems': GRAPH_MODULES} _SET_NAME = {'type': 'string', 'minLength': 1, 'maxLength': 64} @@ -335,6 +337,13 @@ def _embedding_arguments(required=(), **properties): 'values held here, and whether neighbours on the frontier of its tradeoff charts are told apart.', 'inspect', False, _arguments(['benchmark'], benchmark=_NAME), ('benchmark', 'resamples', 'level', 'seed', 'intervals', 'frontiers')), + # docs/plans/training-and-curation/spec-t7.md section 6: the sweeps of the project and one sweep's trials. + Operation('sweeps', "List the project's sweeps, each with its state and its latest run in brief: how many of its " + 'trials ended each way, and the best.', 'inspect', False, _arguments(), ('sweeps',)), + Operation('sweep', "Read one sweep: its definition, its latest run (or the one named) with each trial's values, " + 'state, rungs and objectives, the best, the frontier of two objectives, and the trials as axes.', + 'inspect', False, + _arguments(['sweep'], sweep=_NAME, run={'type': 'string', 'minLength': 1, 'maxLength': 128}), SWEEP), Operation('annotation_tasks', 'List the annotation tasks, each with its dataset, current product and counts of ' 'its records by the state of their annotations.', 'inspect', False, _arguments(), ('tasks',)), Operation('annotated_records', "Read one page of the records of a task's dataset with their annotations, " diff --git a/tuldok_project/plan.py b/tuldok_project/plan.py index 8055d86f..7a835212 100644 --- a/tuldok_project/plan.py +++ b/tuldok_project/plan.py @@ -344,6 +344,9 @@ def build_plan(project, targets, *, every=False): references=[reference]) if reference not in definitions: raise ProjectError(f'There is no definition {reference}.', 'not-found', references=[reference]) + if any(reference.startswith('sweeps/') for reference in targets): # a sweep is planned alone (spec-t7.md) + from . import sweeps + return sweeps.plan(project, list(targets), every=every) built = builds.status(project) local = {**environments.recorded_states(project._connection, project.schema), **{reference: entry['state'] for reference, entry in built.items()}} diff --git a/tuldok_project/schemas/recipe.schema.json b/tuldok_project/schemas/recipe.schema.json index 7723c18c..dbdab7ef 100644 --- a/tuldok_project/schemas/recipe.schema.json +++ b/tuldok_project/schemas/recipe.schema.json @@ -67,12 +67,37 @@ "training-policy", "architecture", "refinement", - "component" + "component", + "sweep-trial" ] }, "derived_from": { "$ref": "#/$defs/recipe_reference" }, + "sweep": { + "type": "object", + "additionalProperties": false, + "required": [ + "definition", + "trial", + "values" + ], + "properties": { + "definition": { + "type": "string", + "pattern": "^sweeps/[a-z0-9][a-z0-9._-]{0,119}$", + "description": "a reference to a sweep, such as sweeps/<name>" + }, + "trial": { + "type": "integer", + "minimum": 1 + }, + "values": { + "type": "object", + "maxProperties": 16 + } + } + }, "compared_with": { "type": "array", "maxItems": 50, diff --git a/tuldok_project/schemas/sweep.schema.json b/tuldok_project/schemas/sweep.schema.json new file mode 100644 index 00000000..c803124b --- /dev/null +++ b/tuldok_project/schemas/sweep.schema.json @@ -0,0 +1,335 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://tuldok.invalid/schemas/sweep.schema.json", + "title": "Tuldok sweep definition", + "description": "One sweep definition in sweeps/<name>.json (tuldok_definition_v1): a search over a recipe's settings (docs/plans/training-and-curation/spec-t7.md section 2). Rules JSON Schema cannot express are checked in tuldok_project/sweeps.py.", + "type": "object", + "additionalProperties": false, + "required": [ + "format", + "kind", + "title", + "recipe", + "parameters", + "strategy", + "objectives", + "budget" + ], + "properties": { + "format": { + "const": "tuldok_definition_v1" + }, + "kind": { + "enum": [ + "dataset", + "model", + "recipe", + "benchmark", + "step", + "environment", + "chart", + "annotation", + "sweep" + ] + }, + "title": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "description": { + "type": "string", + "maxLength": 4000 + }, + "card": { + "type": "string", + "pattern": "^notes/", + "description": "a path under notes/, such as notes/<name>.md" + }, + "labels": { + "type": "object", + "maxProperties": 32, + "additionalProperties": { + "type": "string", + "maxLength": 400 + } + }, + "recipe": { + "type": "string", + "pattern": "^recipes/[a-z0-9][a-z0-9._-]{0,119}$", + "description": "a reference to a recipe, such as recipes/<name>" + }, + "parameters": { + "type": "array", + "minItems": 1, + "maxItems": 16, + "items": { + "$ref": "#/$defs/parameter" + } + }, + "strategy": { + "$ref": "#/$defs/strategy" + }, + "objectives": { + "type": "array", + "minItems": 1, + "maxItems": 2, + "items": { + "$ref": "#/$defs/objective" + } + }, + "budget": { + "type": "object", + "additionalProperties": false, + "required": [ + "trials" + ], + "properties": { + "trials": { + "type": "integer", + "minimum": 1, + "maximum": 1000 + }, + "minutes": { + "type": "number", + "exclusiveMinimum": 0, + "maximum": 10080 + }, + "concurrency": { + "const": 1, + "description": "1: trials run one after another on this machine" + } + } + } + }, + "$defs": { + "series": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "better": { + "enum": [ + "lower", + "higher" + ] + }, + "scalar": { + "type": [ + "number", + "string", + "boolean", + "null" + ] + }, + "parameter": { + "type": "object", + "additionalProperties": false, + "required": [ + "path" + ], + "properties": { + "path": { + "type": "string", + "minLength": 1, + "maxLength": 400, + "pattern": "^[^.]+(\\.[^.]+)*$", + "description": "a dotted path into the recipe's run.settings, such as training.learning_rate" + }, + "values": { + "type": "array", + "minItems": 1, + "maxItems": 64, + "items": { + "$ref": "#/$defs/scalar" + } + }, + "low": { + "type": "number" + }, + "high": { + "type": "number" + }, + "scale": { + "enum": [ + "linear", + "log" + ] + }, + "integer": { + "type": "boolean" + }, + "count": { + "type": "integer", + "minimum": 2, + "maximum": 64 + } + }, + "oneOf": [ + { + "required": [ + "values" + ], + "properties": { + "low": { + "not": {} + }, + "high": { + "not": {} + }, + "scale": { + "not": {} + }, + "integer": { + "not": {} + }, + "count": { + "not": {} + } + } + }, + { + "required": [ + "low", + "high" + ], + "properties": { + "values": { + "not": {} + } + } + } + ], + "description": "a parameter with a path and either values, or low and high (with scale, integer and count)" + }, + "strategy": { + "type": "object", + "required": [ + "kind" + ], + "properties": { + "kind": { + "enum": [ + "grid", + "random", + "halving" + ] + } + }, + "allOf": [ + { + "if": { + "properties": { + "kind": { + "const": "grid" + } + } + }, + "then": { + "properties": { + "kind": true + }, + "additionalProperties": false + } + }, + { + "if": { + "properties": { + "kind": { + "const": "random" + } + } + }, + "then": { + "required": [ + "seed" + ], + "additionalProperties": false, + "properties": { + "kind": true, + "seed": { + "type": "integer", + "minimum": 0, + "maximum": 9223372036854775807 + } + } + } + }, + { + "if": { + "properties": { + "kind": { + "const": "halving" + } + } + }, + "then": { + "required": [ + "seed", + "metric", + "better", + "min" + ], + "additionalProperties": false, + "properties": { + "kind": true, + "seed": { + "type": "integer", + "minimum": 0, + "maximum": 9223372036854775807 + }, + "metric": { + "$ref": "#/$defs/series" + }, + "better": { + "$ref": "#/$defs/better" + }, + "unit": { + "enum": [ + "step", + "time" + ] + }, + "min": { + "type": "number", + "exclusiveMinimum": 0 + }, + "factor": { + "type": "integer", + "minimum": 2, + "maximum": 8 + } + } + } + } + ] + }, + "objective": { + "type": "object", + "additionalProperties": false, + "required": [ + "metric", + "better" + ], + "properties": { + "metric": { + "$ref": "#/$defs/series" + }, + "take": { + "enum": [ + "last", + "best" + ] + }, + "better": { + "$ref": "#/$defs/better" + }, + "title": { + "type": "string", + "minLength": 1, + "maxLength": 200 + } + } + } + } +} diff --git a/tuldok_project/service.py b/tuldok_project/service.py index 1ea6bf8a..f2e7ba15 100644 --- a/tuldok_project/service.py +++ b/tuldok_project/service.py @@ -63,7 +63,7 @@ from . import (activity, annotation_records, annotation_review, annotation_rows, annotations, build_requests, builds, charts, check, comparing, documents, embeddings, environments, inside, inside_fields, inside_graph, - inside_weights, launcher, local, operations, plan, pumas, store, training, workspace) + inside_weights, launcher, local, operations, plan, pumas, store, sweeps, training, workspace) from .documents import Problem CHECK_PROBLEMS = 200 @@ -353,9 +353,13 @@ def stop(): outcome = {} try: - outcome['done'] = builds.execute(self.folder, made, confirm=lambda _plan: True, - scratch=request['scratch'], dsn=self.dsn, expect=request['covers'], - stop=stop, on_event=on_event) + if made.get('sweep'): # a sweep's trials, one after another (spec-t7.md section 5) + outcome['done'] = sweeps.execute(self.folder, made, request_id=request_id, scratch=request['scratch'], + dsn=self.dsn, expect=request['covers'], stop=stop, on_event=on_event) + else: + outcome['done'] = builds.execute(self.folder, made, confirm=lambda _plan: True, + scratch=request['scratch'], dsn=self.dsn, expect=request['covers'], + stop=stop, on_event=on_event) except store.ProjectError as exc: outcome['problem'] = str(exc) except Exception as exc: @@ -603,6 +607,14 @@ def _map(self, arguments, actor): def _note(self, arguments, actor): return workspace.read_note(self.folder, arguments['path']) # from disk; the project is not opened + def _sweeps(self, arguments, actor): + with self._open() as project: + return sweeps.listing(project) + + def _sweep(self, arguments, actor): + with self._open() as project: + return sweeps.show(project, arguments['sweep'], arguments.get('run')) + def _recipe_results(self, arguments, actor): recipe = 'recipes/' + _bare(arguments['recipe'], 'recipes') with self._open() as project: diff --git a/tuldok_project/store.py b/tuldok_project/store.py index 44b4a1a0..28cfa29d 100644 --- a/tuldok_project/store.py +++ b/tuldok_project/store.py @@ -361,9 +361,10 @@ def _schema_exists(self): (self.schema,)).fetchone() is not None def _create_schema(self): + from . import sweeps # here: sweeps imports store self._connection.execute(sql.SQL('CREATE SCHEMA IF NOT EXISTS {}').format(sql.Identifier(self.schema))) for statement in (*_TABLES, *environments.TABLES, *builds.TABLES, *activity.TABLES, *build_requests.TABLES, - *_MIGRATIONS): + *sweeps.TABLES, *_MIGRATIONS): self._execute(statement) def _state(self): diff --git a/tuldok_project/sweeps.py b/tuldok_project/sweeps.py new file mode 100644 index 00000000..62b1bc20 --- /dev/null +++ b/tuldok_project/sweeps.py @@ -0,0 +1,1068 @@ +"""Sweeps: searching a recipe's settings on this machine, one trial after another. + +Owns docs/plans/training-and-curation/spec-t7.md. A sweep definition +(sweeps/<name>.json) names a recipe, the settings it varies and their ranges, +a strategy (grid, random, or successive halving that stops poor trials +early), one or two objectives read from the trials' training logs, and a +budget. Here are: the checks a sweep needs beyond its schema (check_sweeps, +called by check.check_map); its schedule (schedule, a pure function of the +definition); the halving rule (Rungs, goes_on); a trial's definition +(trial_text); a sweep as a plan (plan, called by plan.build_plan for a sweep +target); the runner the build request worker calls for such a plan (execute), +which builds what the recipe needs, then each trial as a build step with one +plan id and one snapshot of the code, while a watcher reads the trial's +training/metrics.jsonl to record where it is and to stop it (its cancel +file) when halving prunes it or the minutes are spent; the two tables that +record a sweep's runs and trials; the reads sweeps and sweep; and the map's +groups of trials (map_groups). + +The runner never runs the project's code in this process: a trial is a +recipe built by builds._Build.run_one under the launcher, exactly as a build +step. It writes nothing to the folder; trials are kept as unsaved edits of +the working copy (set_definition), saved with the rest by save. +""" +import copy +import datetime +import hashlib +import itertools +import json +import math +import os +import random +import threading +import time +import uuid + +from psycopg.types.json import Jsonb + +from . import builds, comparing, documents, launcher, local, snapshot, store, training +from .store import ProjectError + +DIRECTORY = 'sweeps' +PARAMETERS = 16 +GRID_MOST = 100_000 # points of a grid at most +DRAWS_WITHOUT_NEW = 1000 # a random schedule ends after this many draws in a row with nothing new +RUNGS = 32 # rungs of halving at most +DEFAULT_FACTOR = 3 +DEFAULT_COUNT = None # a grid's range needs count; random and halving do not +SPECIAL = ('time', 'step') # objectives that are the last logged time or step +WATCH_SECONDS = 0.25 # how often a running trial's log is read +LATEST_SECONDS = 1.0 # how often the latest line of a running trial is recorded +RUNS_SHOWN = 20 +NAME_PART = 100 # characters of a sweep's name in its trials' names +TRIAL_STATES = ('running', 'completed', 'pruned', 'stopped', 'failed') +ORPHAN_PROBLEM = 'Tuldok stopped while this sweep ran.' + +TABLES = ( + '''CREATE TABLE IF NOT EXISTS {schema}.sweep_runs ( + id text PRIMARY KEY, sweep text NOT NULL, request_id text, plan_id text, + state text NOT NULL, ended text, problem text, + sweep_sha256 text NOT NULL, recipe text NOT NULL, recipe_sha256 text NOT NULL, + strategy jsonb NOT NULL, objectives jsonb NOT NULL, budget jsonb NOT NULL, + started_at timestamptz NOT NULL, finished_at timestamptz, + owner_pid integer, owner_boot text)''', + 'CREATE INDEX IF NOT EXISTS sweep_runs_sweep ON {schema}.sweep_runs (sweep, started_at)', + '''CREATE TABLE IF NOT EXISTS {schema}.sweep_trials ( + sweep_run text NOT NULL, number integer NOT NULL, reference text NOT NULL, "values" jsonb NOT NULL, + state text NOT NULL, reused boolean NOT NULL DEFAULT false, run_id text, + started_at timestamptz, finished_at timestamptz, seconds double precision, + rungs jsonb NOT NULL DEFAULT '[]', objectives jsonb, latest jsonb, problem text, + PRIMARY KEY (sweep_run, number))''', +) +_RUN_COLUMNS = ('id', 'sweep', 'request_id', 'plan_id', 'state', 'ended', 'problem', 'sweep_sha256', 'recipe', + 'recipe_sha256', 'strategy', 'objectives', 'budget', 'started_at', 'finished_at') +_TRIAL_COLUMNS = ('number', 'reference', 'values', 'state', 'reused', 'run_id', 'started_at', 'finished_at', + 'seconds', 'rungs', 'objectives', 'latest', 'problem') + + +def _sha256(text): + return hashlib.sha256(text.encode('utf-8')).hexdigest() + + +def _number(value): + return isinstance(value, (int, float)) and not isinstance(value, bool) and math.isfinite(value) + + +# ================================================================ paths into run.settings + +def parts(path): + """The parts of a dotted path: keys, and whole numbers for parts of digits (a list's index).""" + return [int(part) if part.isdigit() else part for part in path.split('.')] + + +def _child(holder, part): + """(found, value) of one part in an object or a list.""" + if isinstance(holder, dict) and isinstance(part, str) and part in holder: + return True, holder[part] + if isinstance(holder, dict) and isinstance(part, int) and str(part) in holder: + return True, holder[str(part)] + if isinstance(holder, list) and isinstance(part, int) and part < len(holder): + return True, holder[part] + return False, None + + +def path_problem(settings, path): + """A sentence when path cannot be set in settings (its parents missing, or not objects or lists), else None.""" + holder = settings + steps = parts(path) + for depth, part in enumerate(steps[:-1]): + found, value = _child(holder, part) + if not found: + return f'{".".join(map(str, steps[:depth + 1]))} is not in the recipe\'s settings' + if not isinstance(value, (dict, list)): + return f'{".".join(map(str, steps[:depth + 1]))} is not an object or a list in the recipe\'s settings' + holder = value + last = steps[-1] + if isinstance(holder, list) and not (isinstance(last, int) and last < len(holder)): + return f'{path} indexes a list of {len(holder)} items past its end' + return None + + +def set_path(settings, path, value): + """Set value at path in settings (changed in place); the parents exist (path_problem said so).""" + holder = settings + steps = parts(path) + for part in steps[:-1]: + holder = _child(holder, part)[1] + last = steps[-1] + if isinstance(holder, list): + holder[last] = value + else: + holder[str(last)] = value + + +# ================================================================ checking + +def check_sweeps(definitions, add): + """Report the rules of section 2 that need the recipe, or that a schema cannot say, for every sweep. + + definitions maps references to folder.Definition. A missing recipe is + check_references' problem. + """ + for reference, definition in definitions.items(): + document = definition.document + if definition.kind != 'sweep' or not isinstance(document, dict): + continue + path = definition.path + parameters = [item for item in document.get('parameters') or [] if isinstance(item, dict)] + seen = set() + for index, item in enumerate(parameters): + name = item.get('path') + if not isinstance(name, str): + continue + where = documents.pointer('parameters', index) + if name in seen: + add('error', path, where + '/path', f'{name} is varied twice; keep one parameter for it.') + seen.add(name) + low, high = item.get('low'), item.get('high') + if _number(low) and _number(high): + if low >= high: + add('error', path, where, f'low ({low}) must be less than high ({high}).') + if item.get('scale') == 'log' and low <= 0: + add('error', path, where + '/low', 'A log scale needs low above 0.') + if item.get('integer') and not (float(low).is_integer() and float(high).is_integer()): + add('error', path, where, 'An integer range needs whole numbers for low and high.') + values = item.get('values') + if isinstance(values, list) and len({json.dumps(value) for value in values}) != len(values): + add('error', path, where + '/values', 'The values repeat; list each once.') + strategy = document.get('strategy') if isinstance(document.get('strategy'), dict) else {} + if strategy.get('kind') == 'grid': + for index, item in enumerate(parameters): + if 'low' in item and 'count' not in item: + add('error', path, documents.pointer('parameters', index), + 'A grid takes count points of a range; add count (2 to 64).') + if not any(('low' in item and 'count' not in item) for item in parameters): + size = math.prod(len(_grid_points(item)) for item in parameters) if parameters else 0 + trials = (document.get('budget') or {}).get('trials') if isinstance(document.get('budget'), dict) else None + if size > GRID_MOST: + add('error', path, '/parameters', f'The grid has {size:,} points; at most {GRID_MOST:,} are allowed.') + elif isinstance(trials, int) and size > trials: + add('warning', path, '/budget/trials', f'The grid has {size:,} points and the budget {trials}; ' + f'the first {trials} in order are run.') + if strategy.get('kind') == 'halving' and strategy.get('unit', 'step') == 'step' and _number(strategy.get('min')) \ + and not float(strategy['min']).is_integer(): + add('error', path, '/strategy/min', 'A rung in steps is a whole number of steps.') + objectives = [item for item in document.get('objectives') or [] if isinstance(item, dict)] + if len({item.get('metric') for item in objectives}) != len(objectives): + add('error', path, '/objectives', 'The two objectives name the same metric; name two.') + recipe = definitions.get(document.get('recipe')) if isinstance(document.get('recipe'), str) else None + if recipe is None or recipe.kind != 'recipe' or not isinstance(recipe.document, dict): + continue + run = recipe.document.get('run') if isinstance(recipe.document.get('run'), dict) else None + if run is None or 'command' not in run: + add('error', path, '/recipe', f'{document["recipe"]} has no run.command, so it has no trials to run.') + continue + if not isinstance(run.get('settings'), dict): + add('error', path, '/recipe', f'{document["recipe"]} has no settings written in it' + + (' (its settings are in a file)' if 'settings_file' in run else '') + + '; a sweep varies run.settings. Branch from here gives a branch its own copy.') + continue + for index, item in enumerate(parameters): + if isinstance(item.get('path'), str): + wrong = path_problem(run['settings'], item['path']) + if wrong: + add('error', path, documents.pointer('parameters', index, 'path'), f'{wrong}.') + + +# ================================================================ the schedule + +def rounded(value, integer=False, low=None, high=None): + """A drawn value as kept: 6 significant digits, or for an integer floor(x + 0.5) within low and high.""" + if integer: + whole = math.floor(value + 0.5) + return int(min(high, max(low, whole))) + return float(f'{value:.6g}') + + +def _range_value(item, u): + low, high = float(item['low']), float(item['high']) + if item.get('scale') == 'log': + value = math.exp(math.log(low) + u * (math.log(high) - math.log(low))) + else: + value = low + u * (high - low) + return rounded(value, bool(item.get('integer')), low, high) + + +def _grid_points(item): + if 'values' in item: + return list(item['values']) + count = item.get('count') or 2 + points = [] + for index in range(count): + value = _range_value(item, index / (count - 1)) + if not any(_same(value, point) for point in points): + points.append(value) + return points + + +def _same(a, b): + return comparing._canon(a) == comparing._canon(b) + + +def _key(values): + return tuple(comparing._canon(value) for value in values) + + +def schedule(document): + """Yield {path: value} for each trial in order (section 3); finite for a grid, until exhausted for random.""" + parameters = document['parameters'] + names = [item['path'] for item in parameters] + strategy = document['strategy'] + if strategy['kind'] == 'grid': + for combination in itertools.product(*(_grid_points(item) for item in parameters)): + yield dict(zip(names, combination)) + return + rng = random.Random(strategy['seed']) + seen = set() + misses = 0 + while misses < DRAWS_WITHOUT_NEW: + drawn = [] + for item in parameters: + if 'values' in item: + drawn.append(item['values'][rng.randrange(len(item['values']))]) + else: + drawn.append(_range_value(item, rng.random())) + key = _key(drawn) + if key in seen: + misses += 1 + continue + misses = 0 + seen.add(key) + yield dict(zip(names, drawn)) + + +# ================================================================ halving + +def rung_points(strategy): + """The rungs of halving: min × factor^k, k from 0, at most RUNGS; whole numbers in steps.""" + factor = strategy.get('factor', DEFAULT_FACTOR) + first = strategy['min'] + steps = strategy.get('unit', 'step') == 'step' + return [int(first) * factor ** k if steps else float(first) * factor ** k for k in range(RUNGS)] + + +class Rungs: + """Which rungs a trial crosses as its lines arrive: feed(unit value, latest metric value) -> [(k, point, value)].""" + + def __init__(self, points): + self.points, self.next = points, 0 + + def feed(self, at, value): + crossed = [] + while self.next < len(self.points) and at >= self.points[self.next]: + crossed.append((self.next, self.points[self.next], value)) + self.next += 1 + return crossed + + +def goes_on(value, recorded, better, factor): + """(goes on, n, kept): a trial's value at a rung against the values recorded there before it (section 5).""" + n = len(recorded) + 1 + kept = math.ceil(n / factor) + if n < factor: + return True, n, kept + beaten_by = sum(1 for other in recorded if (other > value if better == 'higher' else other < value)) + return beaten_by < kept, n, kept + + +# ================================================================ objectives + +def _objective_of(log, objective): + """An objective's value from a read metrics log (training._Metrics), or None.""" + metric = objective['metric'] + if metric in SPECIAL: + if not len(log.steps): + return None + return float(log.times[-1]) if metric == 'time' else int(log.steps[-1]) + held = log.series.get(metric) + if held is None: + return None + finite = [value for value in held[1] if math.isfinite(value)] + if not finite: + return None + if objective.get('take', 'last') == 'best': + return max(finite) if objective['better'] == 'higher' else min(finite) + return finite[-1] + + +def read_objectives(output, objectives, run_id=''): + """{metric: value} of a trial's output directory as its training log now is (None where it has none).""" + run = training.Run(run_id, 'succeeded', output) + with training._Read(run, training.METRICS) as log: + if log is None: + return {item['metric']: None for item in objectives}, None + latest = {'step': int(log.steps[-1]), 'time': float(log.times[-1])} if len(log.steps) else None + return {item['metric']: _objective_of(log, item) for item in objectives}, latest + + +# ================================================================ a trial's definition + +def trial_document(sweep_reference, sweep, recipe_reference, recipe, number, values): + """The document of trial number of a sweep (section 4).""" + shown = ', '.join(f'{path} = {json.dumps(value)}' for path, value in values.items()) + document = {'format': documents.DEFINITION_FORMAT, 'kind': 'recipe', + 'title': f'{sweep["title"]} · trial {number}'[:200], + 'description': f'Trial {number} of {sweep_reference}: {shown}.'[:4000]} + for key in ('model', 'group'): + if key in recipe: + document[key] = recipe[key] + document['labels'] = {'short': f'T{number}'} + document['change'] = 'sweep-trial' + document['derived_from'] = recipe_reference + document['sweep'] = {'definition': sweep_reference, 'trial': number, 'values': dict(values)} + run = copy.deepcopy(recipe['run']) + for path, value in values.items(): + set_path(run['settings'], path, value) + document['run'] = run + return document + + +def trial_text(sweep_reference, sweep, recipe_reference, recipe, number, values): + return json.dumps(trial_document(sweep_reference, sweep, recipe_reference, recipe, number, values), + indent=2, ensure_ascii=False) + '\n' + + +def trial_names(sweep_reference, number): + """The names a trial may take, in order: <sweep>-<NNN>, then -2, -3, ...""" + base = f'{sweep_reference.split("/", 1)[1][:NAME_PART]}-{number:03d}' + yield base + for suffix in itertools.count(2): + yield f'{base}-{suffix}' + + +def place_trial(texts, sweep_reference, number, text): + """(reference, same) for a trial's text: the first name free or holding the same text (same true).""" + for name in trial_names(sweep_reference, number): + reference = f'recipes/{name}' + held = texts.get(reference) + if held is None: + return reference, False + if held == text: + return reference, True + + +# ================================================================ reading the tables + +def _q(schema, template): + from psycopg import sql + return sql.SQL(template).format(schema=sql.Identifier(schema)) + + +def reap(project): + """Mark failed every running sweep run whose process is gone (or ran before this boot).""" + rows = project._execute("SELECT id, owner_pid, owner_boot FROM {schema}.sweep_runs WHERE state = 'running'").fetchall() + boot = builds.boot_id() + for run_id, pid, owner_boot in rows: + if owner_boot != boot or pid is None or not builds._alive(pid) or pid == os.getpid() and not _active(run_id): + project._execute('''UPDATE {schema}.sweep_runs SET state = 'failed', ended = 'failed', problem = %s, + finished_at = now() WHERE id = %s AND state = 'running' ''', (ORPHAN_PROBLEM, run_id)) + project._execute("UPDATE {schema}.sweep_trials SET state = 'stopped', finished_at = now(), problem = %s " + "WHERE sweep_run = %s AND state = 'running'", (ORPHAN_PROBLEM, run_id)) + + +_ACTIVE = set() # sweep runs this process is running +_ACTIVE_LOCK = threading.Lock() + + +def _active(run_id): + with _ACTIVE_LOCK: + return run_id in _ACTIVE + + +def _runs_of(project, reference, limit=RUNS_SHOWN): + rows = project._execute('SELECT ' + ', '.join(_RUN_COLUMNS) + ' FROM {schema}.sweep_runs WHERE sweep = %s ' + 'ORDER BY started_at DESC, id LIMIT %s', (reference, limit)).fetchall() + return [dict(zip(_RUN_COLUMNS, row)) for row in rows] + + +def _trials_of(project, run_id): + rows = project._execute('SELECT ' + ', '.join(f'"{c}"' if c == 'values' else c for c in _TRIAL_COLUMNS) + + ' FROM {schema}.sweep_trials WHERE sweep_run = %s ORDER BY number', (run_id,)).fetchall() + return [dict(zip(_TRIAL_COLUMNS, row)) for row in rows] + + +def _texts(project, references=None): + if references is None: + rows = project._execute(f'SELECT {store._REFERENCE_SQL}, text FROM {{schema}}.definitions WHERE NOT removed') + else: + rows = project._execute(f'SELECT {store._REFERENCE_SQL}, text FROM {{schema}}.definitions ' + f'WHERE NOT removed AND {store._REFERENCE_SQL} = ANY(%s)', (list(references),)) + return dict(rows.fetchall()) + + +def _definition(project, reference): + directory, name = documents.parse_reference(reference) or (None, None) + row = project._execute('SELECT text, document FROM {schema}.definitions WHERE directory = %s AND name = %s ' + 'AND NOT removed', (directory, name)).fetchone() + return (None, None) if row is None else row + + +def find(project, text): + """The reference of the sweep named by text (sweeps/<name> or a bare name); not-found otherwise.""" + reference = text if isinstance(text, str) and text.startswith(DIRECTORY + '/') else f'{DIRECTORY}/{text}' + parsed = documents.parse_reference(reference) + if parsed is None or parsed[0] != DIRECTORY or _definition(project, reference)[0] is None: + raise ProjectError(f'There is no sweep {text}.', 'not-found', references=[reference]) + return reference + + +def sweep_state(project, reference, texts=None): + """not-built, running, built (its last run finished with the texts as they are now) or failed.""" + runs = _runs_of(project, reference, 1) + if not runs: + return 'not-built', None + last = runs[0] + if last['state'] == 'running': + return 'running', last + texts = texts or {} + sweep_text = texts.get(reference) or _definition(project, reference)[0] + recipe_text = texts.get(last['recipe']) or _definition(project, last['recipe'])[0] + same = (sweep_text is not None and _sha256(sweep_text) == last['sweep_sha256'] and recipe_text is not None + and _sha256(recipe_text) == last['recipe_sha256']) + if last['state'] == 'finished' and same: + return 'built', last + if last['state'] == 'failed' and same: + return 'failed', last + return 'not-built', last + + +# ================================================================ a sweep as a plan + +def _strategy_words(document): + strategy, budget = document['strategy'], document['budget'] + if strategy['kind'] == 'grid': + words = 'a grid' + elif strategy['kind'] == 'random': + words = f'random draws (seed {strategy.get("seed")})' + else: + rungs = ', '.join(f'{point:g}' for point in rung_points(strategy)[:4]) + words = (f'random draws (seed {strategy.get("seed")}) with successive halving on {strategy.get("metric")} at ' + f'{strategy.get("unit", "step")}s {rungs}, … (keeping the best 1/{strategy.get("factor", DEFAULT_FACTOR)})') + limit = f'at most {budget["trials"]} trials' + (f' and {budget["minutes"]:g} minutes' if budget.get('minutes') else '') + return f'Trials of {document["recipe"]} by {words}, {limit}, one at a time.' + + +def plan(project, targets, *, every=False): + """The plan of a sweep (section 5): what its recipe needs, then the sweep's own step. Refused invalid unless alone.""" + from . import plan as planning + if every or len(targets) != 1: + raise ProjectError('A sweep is planned and built alone: name it as the only target, without every.', + 'invalid', references=list(targets)) + reference = targets[0] + text, document = _definition(project, reference) + if text is None: + raise ProjectError(f'There is no definition {reference}.', 'not-found', references=[reference]) + recipe_reference = document['recipe'] + recipe_text, recipe = _definition(project, recipe_reference) + if recipe_text is None: + raise ProjectError(f'{reference} varies {recipe_reference}, which is not a recipe of the project.', + 'not-found', references=[recipe_reference]) + made = planning.build_plan(project, [recipe_reference]) + own = next((step for step in made['steps'] if step['reference'] == recipe_reference), None) + steps = [dict(step) for step in made['steps'] if step['reference'] != recipe_reference] + state, _last = sweep_state(project, reference, {reference: text, recipe_reference: recipe_text}) + blocked_by = [cause for cause in (own or {}).get('blocked_by', []) if cause['reference'] != recipe_reference] + run = recipe.get('run') if isinstance(recipe.get('run'), dict) else {} + budget = document['budget'] + reasons = [_strategy_words(document)] + if not isinstance(run.get('settings'), dict) or 'command' not in run: + action = 'blocked' + blocked_by.append({'reference': recipe_reference, 'rebuild': 'no', + 'reason': 'it has no run.command with settings written in it'}) + elif blocked_by or (own and own['action'] == 'blocked' and own['blocked_by'] and not + all(cause['reference'] == recipe_reference for cause in own['blocked_by'])): + action = 'blocked' + elif any(step['action'] == 'blocked' for step in steps): + action = 'blocked' + else: + action = 'built' if state == 'built' else 'build' + for number, step in enumerate(steps, 1): + step['number'] = number + steps.append({'number': len(steps) + 1, 'reference': reference, 'kind': 'sweep', 'title': document.get('title'), + 'state': state, 'action': action, 'command': run.get('command'), + 'environment': run.get('environment'), 'step': None, 'annotations': [], + 'inputs': (own or {}).get('inputs', {}), + 'resources': {'gpu': ((run.get('resources') or {}).get('gpu') is True), + 'cpu_threads': None, 'memory_gb': None, + 'wall_hours': budget['minutes'] / 60 if budget.get('minutes') else None, + 'disk_gb': None}, + 'estimate': None, 'blocked_by': blocked_by[:planning.CAUSE_LIMIT], + 'blocked_by_more': max(0, len(blocked_by) - planning.CAUSE_LIMIT), + 'reasons': reasons, 'scratch': False, 'adopted': False, + 'recipe': recipe_reference, 'trials': budget['trials']}) + blocked = [step['reference'] for step in steps if step['action'] == 'blocked'] + disk_gb, disk_unknown = planning._total(steps, 'disk_gb') + wall_hours, wall_unknown = planning._total(steps, 'wall_hours') + estimated_disk_gb, estimated_disk_steps = planning._estimated(steps, 'disk_bytes', 1000 ** 3) + estimated_wall_hours, estimated_wall_steps = planning._estimated(steps, 'wall_seconds', 3600) + notes = [note for note in made['notes']] + [ + f'{reference} builds trials of {recipe_reference}, each a recipe derived from it, one after another; ' + 'one approval covers them all.'] + return {'targets': [reference], 'every': False, 'buildable': reference not in blocked and not blocked, + 'blocked_targets': [reference] if blocked else [], + 'counts': {action_name: sum(step['action'] == action_name for step in steps) + for action_name in planning.ACTIONS}, + 'gpu_steps': sum(step['action'] == 'build' and step['resources']['gpu'] is True for step in steps), + 'disk_gb': disk_gb, 'disk_unknown': disk_unknown, 'wall_hours': wall_hours, 'wall_unknown': wall_unknown, + 'estimated_disk_gb': estimated_disk_gb, 'estimated_disk_steps': estimated_disk_steps, + 'estimated_wall_hours': estimated_wall_hours, 'estimated_wall_steps': estimated_wall_steps, + 'notes': notes, 'steps': steps, 'sweep': reference} + + +# ================================================================ running + +def _connect(dsn): + import psycopg + return psycopg.connect(store.connection_info(dsn), autocommit=True) + + +class _Watch: + """Reads a running trial's metrics, records where it is, and stops it when halving prunes it or time is up.""" + + def __init__(self, sweep, connection, schema, run_id, number, recorded, deadline, clock): + self.sweep, self.connection, self.schema = sweep, connection, schema + self.sweep_run, self.number, self.recorded = run_id, number, recorded + self.deadline, self.clock = deadline, clock + strategy = sweep['strategy'] + self.halving = strategy if strategy['kind'] == 'halving' else None + self.rungs = Rungs(rung_points(strategy)) if self.halving else None + self.metrics = [item['metric'] for item in sweep['objectives'] if item['metric'] not in SPECIAL] + if self.halving and self.halving['metric'] not in self.metrics: + self.metrics.append(self.halving['metric']) + self.pointer = {name: 0 for name in self.metrics} + self.latest = {name: None for name in self.metrics} + self.best = {name: None for name in self.metrics} + self.position = 0 + self.reached = [] # the rungs recorded: {rung, at, value, n, kept, goes_on} + self.reason = None # pruned, minutes + self.problem = None + self.directory = self.output = self.run_id = None + self.written = 0.0 + self.done = threading.Event() + self.lock = threading.Lock() + self.thread = None + + def begin(self, item): + self.directory, self.run_id = item['directory'], item['run_id'] + self.output = os.path.join(item['directory'], builds.OUTPUT) + self.connection.execute(_q(self.schema, 'UPDATE {schema}.sweep_trials SET run_id = %s, started_at = now() ' + 'WHERE sweep_run = %s AND number = %s'), + (self.run_id, self.sweep_run, self.number)) + self.thread = threading.Thread(target=self._loop, name=f'tuldok-sweep-trial-{self.number}', daemon=True) + self.thread.start() + + def _loop(self): + while not self.done.wait(WATCH_SECONDS): + try: + self.look() + except Exception: # a read that failed is tried again on the next look + pass + + def end(self): + self.done.set() + if self.thread is not None: + self.thread.join() + try: + self.look(final=True) + except Exception: + pass + + def _stop(self, reason, problem): + if self.reason is None: + self.reason, self.problem = reason, problem + try: + os.close(os.open(os.path.join(self.directory, launcher.CANCEL_FILE), + os.O_WRONLY | os.O_CREAT | os.O_NOFOLLOW | os.O_CLOEXEC, 0o644)) + except OSError: + pass # the run ended meanwhile + + def look(self, final=False): + with self.lock: + if self.output is None: + return + changed = False + run = training.Run(self.run_id or '', 'running', self.output) + with training._Read(run, training.METRICS) as log: + if log is not None: + changed = self._lines(log) + step = int(log.steps[-1]) if len(log.steps) else None + at = float(log.times[-1]) if len(log.times) else None + else: + step = at = None + if not final and self.reason is None and self.deadline is not None and self.clock() >= self.deadline: + self._stop('minutes', 'The sweep\'s minutes were spent while it ran.') + now = self.clock() + if changed and (final or now - self.written >= LATEST_SECONDS or self.reached and self._fresh_rung): + self._fresh_rung = False + self.written = now + latest = {'step': step, 'time': at, 'values': dict(self.latest)} + self.connection.execute(_q(self.schema, 'UPDATE {schema}.sweep_trials SET latest = %s, rungs = %s ' + 'WHERE sweep_run = %s AND number = %s'), + (Jsonb(latest), Jsonb(self.reached), self.sweep_run, self.number)) + + _fresh_rung = False + + def _lines(self, log): + count = len(log.steps) + if count <= self.position: + return False + for index in range(self.position, count): + for name in self.metrics: + held = log.series.get(name) + if held is None: + continue + positions, values = held + while self.pointer[name] < len(positions) and positions[self.pointer[name]] <= index: + value = values[self.pointer[name]] + if math.isfinite(value): + self.latest[name] = value + self.pointer[name] += 1 + if self.halving and self.reason is None: + at = log.steps[index] if self.halving.get('unit', 'step') == 'step' else log.times[index] + for rung, point, value in self.rungs.feed(at, self.latest[self.halving['metric']]): + if value is None: + continue + held = self.recorded.setdefault(rung, []) + keep, n, kept = goes_on(value, held, self.halving['better'], self.halving.get('factor', DEFAULT_FACTOR)) + held.append(value) + self.reached.append({'rung': rung, 'at': point, 'value': value, 'n': n, 'kept': kept, + 'goes_on': keep}) + self._fresh_rung = True + if not keep: + unit = self.halving.get('unit', 'step') + self._stop('pruned', f'Pruned by successive halving at rung {rung + 1} ({unit} {point}): ' + f'{self.halving["metric"]} {value:.6g} was not among the best {kept} of {n}.') + break + self.position = count + return True + + +def _now(): + return datetime.datetime.now(datetime.timezone.utc) + + +def execute(project_folder, made, *, request_id=None, extra_env=None, scratch=False, dsn=None, on_event=None, + expect=None, stop=None, clock=time.monotonic): + """Run a sweep's plan (plan()): what its recipe needs, then its trials; return what builds.execute returns. + + Refused as builds.execute refuses (blocked, running, the code, the + commit). stop() is asked before each step and each trial; on_event is + called with 'start' and 'end' for every run, as builds.execute calls it. + ok is true when the sweep finished (its schedule or a budget spent). + """ + folder = os.fspath(project_folder) + reference = made['sweep'] + if made['blocked_targets']: + raise ProjectError(f'{reference} cannot be built now. See plan for why.', 'blocked', + references=made['blocked_targets']) + sweep_step = next(step for step in made['steps'] if step['kind'] == 'sweep') + if sweep_step['state'] == 'running': + raise ProjectError(f'{reference} is running; wait for it to end.', 'running', references=[reference]) + to_build = [step for step in made['steps'] if step['action'] == 'build' and step['kind'] != 'sweep'] + running = [step['reference'] for step in to_build if step['state'] == 'running'] + if running: + raise ProjectError('Another build is running ' + ', '.join(running) + '; wait for it to end.', 'running', + references=running) + outer = on_event or (lambda kind, item: None) + build = builds._Build(folder, made, extra_env=extra_env, scratch=scratch, dsn=dsn, on_event=outer, + expect=copy.deepcopy(expect) if expect is not None else None) + with builds.opened(folder, dsn) as project: + state = project._state() + code_paths = (store._read_project_file(state['folder']) or {}).get('code_paths') + code_root = builds._code_root(project) + home = local.home(project.project_id, create=True) + schema = project.schema + sweep_text, sweep = _definition(project, reference) + recipe_reference = sweep['recipe'] + recipe_text, recipe = _definition(project, recipe_reference) + try: + build.code = snapshot.prepare(code_root, code_paths, home=home, scratch=scratch) + except snapshot.SnapshotError as exc: + raise builds._snapshot_error(exc) from None + approved = (expect or {}).get('commit') + if approved is not None and build.code.commit != approved: + raise ProjectError(f'The code is at commit {build.code.commit[:12] or "(none)"}, not at ' + f'{approved[:12]} as approved; ask for the build again.', 'stale') + for used, text in ((reference, sweep_text), (recipe_reference, recipe_text)): + wanted = ((expect or {}).get('definitions') or {}).get(used) + if expect is not None and wanted != _sha256(text): + raise ProjectError(f'{used} is not what the build was approved with; ask for the build again.', 'stale', + references=[used]) + result = {'plan_id': build.plan_id, 'confirmed': True, 'ok': False, 'steps': build.done, 'skipped': []} + run_id = uuid.uuid4().hex + connection = _connect(dsn) + with _ACTIVE_LOCK: + _ACTIVE.add(run_id) + try: + with builds.opened(folder, dsn) as project: + project._execute('INSERT INTO {schema}.plans (id, created_at, targets, steps, scratch) ' + 'VALUES (%s, now(), %s, %s, %s)', + (build.plan_id, Jsonb(made['targets']), Jsonb(made['steps']), scratch)) + project._execute('''INSERT INTO {schema}.sweep_runs (id, sweep, request_id, plan_id, state, sweep_sha256, + recipe, recipe_sha256, strategy, objectives, budget, started_at, owner_pid, + owner_boot) + VALUES (%s, %s, %s, %s, 'running', %s, %s, %s, %s, %s, %s, now(), %s, %s)''', + (run_id, reference, request_id, build.plan_id, _sha256(sweep_text), recipe_reference, + _sha256(recipe_text), Jsonb(sweep['strategy']), Jsonb(sweep['objectives']), + Jsonb(sweep['budget']), os.getpid(), builds.boot_id())) + ended, problem = _run(build, folder, dsn, connection, schema, run_id, reference, sweep, recipe_reference, + recipe, made, stop, clock) + except BaseException as exc: + connection.execute(_q(schema, '''UPDATE {schema}.sweep_runs SET state = 'failed', ended = 'failed', + problem = %s, finished_at = now() WHERE id = %s'''), + (f'{type(exc).__name__}: {exc}'[:2000], run_id)) + connection.execute(_q(schema, "UPDATE {schema}.sweep_trials SET state = 'stopped', finished_at = now() " + "WHERE sweep_run = %s AND state = 'running'"), (run_id,)) + raise + finally: + with _ACTIVE_LOCK: + _ACTIVE.discard(run_id) + final = {'failed': 'failed', 'cancelled': 'cancelled'}.get(ended, 'finished') + connection.execute(_q(schema, '''UPDATE {schema}.sweep_runs SET state = %s, ended = %s, problem = %s, + finished_at = now() WHERE id = %s'''), (final, ended, problem, run_id)) + connection.close() + result['ok'] = final == 'finished' + return result + + +def _run(build, folder, dsn, connection, schema, run_id, reference, sweep, recipe_reference, recipe, made, stop, + clock): + """The steps and trials of one sweep run; (why it ended, its problem).""" + needed = {step['environment'] for step in made['steps'] if step['action'] == 'build' and step['environment']} + for step in made['steps']: + if step['kind'] == 'environment': + if step['reference'] in needed: + with builds.opened(folder, dsn) as project: + build.environment(project, step['reference']) + continue + if step['kind'] == 'sweep' or step['action'] != 'build': + continue + if stop is not None and stop(): + return 'cancelled', 'It was cancelled before its trials.' + item = build.run_one(step['reference']) + build.done.append(item) + build.on_event('end', item) + if item['state'] != 'succeeded': + return 'failed', f'{step["reference"]} ended {item["state"]}: {item["problem"]}' + + budget = sweep['budget'] + started = clock() + deadline = started + budget['minutes'] * 60 if budget.get('minutes') else None + recorded = {} + used = 0 + outer = build.on_event + for number, values in enumerate(schedule(sweep), 1): + if used >= budget['trials']: + return 'trials', None + if deadline is not None and clock() >= deadline: + return 'minutes', None + if stop is not None and stop(): + return 'cancelled', 'It was cancelled.' + used += 1 + text = trial_text(reference, sweep, recipe_reference, recipe, number, values) + with builds.opened(folder, dsn) as project: + trial, same = place_trial(_texts(project), reference, number, text) + built = same and (builds.status(project).get(trial) or {}).get('state') == 'built' + problem = None + if not same: + try: + project.set_definition(trial, text) + except ProjectError as exc: + shown = '; '.join(item.message for item in (exc.problems or [])[:3]) + problem = f'The trial does not check: {exc}' + (f' {shown}' if shown else '') + product = builds._current_product(project, trial) if built else None + connection.execute(_q(schema, '''INSERT INTO {schema}.sweep_trials (sweep_run, number, reference, "values", + state, reused, started_at) VALUES (%s, %s, %s, %s, 'running', %s, now())'''), + (run_id, number, trial, Jsonb(values), built)) + if problem is not None: + _end_trial(connection, schema, run_id, number, 'failed', problem=problem) + continue + if built: + found, latest = read_objectives(product['directory'], sweep['objectives'], product['run_id']) + _end_trial(connection, schema, run_id, number, 'completed', run=product['run_id'], objectives=found, + latest=latest) + continue + if build.expect is not None: + build.expect.setdefault('definitions', {})[trial] = _sha256(text) + watch = _Watch(sweep, connection, schema, run_id, number, recorded, deadline, clock) + + def on_event(kind, item, watch=watch): + if kind == 'start': + watch.begin(item) + outer(kind, item) + + build.on_event = on_event + try: + item = build.run_one(trial) + finally: + watch.end() + build.on_event = outer + build.done.append(item) + outer('end', item) + output = os.path.join(item['directory'], builds.OUTPUT) + found, latest = read_objectives(output, sweep['objectives'], item['run_id']) + latest = latest and {**latest, 'values': {name: value for name, value in watch.latest.items()}} + if item['state'] == 'succeeded': + state, why = 'completed', None + elif item['state'] == 'cancelled' and watch.reason == 'pruned': + state, why = 'pruned', watch.problem + elif item['state'] == 'cancelled': + state, why = 'stopped', watch.problem or 'It was stopped.' + else: + state, why = 'failed', item['problem'] + if state in ('pruned', 'stopped'): + connection.execute(_q(schema, 'UPDATE {schema}.runs SET problem = %s WHERE id = %s'), + (why, item['run_id'])) + _end_trial(connection, schema, run_id, number, state, run=item['run_id'], objectives=found, latest=latest, + problem=why, seconds=item.get('seconds'), rungs=watch.reached) + if state == 'stopped': + if watch.reason == 'minutes': + return 'minutes', None + return 'cancelled', 'It was cancelled while a trial ran.' + return 'schedule', None + + +def _end_trial(connection, schema, run_id, number, state, *, run=None, objectives=None, latest=None, problem=None, + seconds=None, rungs=None): + connection.execute(_q(schema, '''UPDATE {schema}.sweep_trials SET state = %s, run_id = coalesce(%s, run_id), + objectives = %s, latest = coalesce(%s, latest), problem = %s, seconds = %s, + rungs = coalesce(%s, rungs), finished_at = now() + WHERE sweep_run = %s AND number = %s'''), + (state, run, Jsonb(objectives) if objectives is not None else None, + Jsonb(latest) if latest is not None else None, problem, seconds, + Jsonb(rungs) if rungs is not None else None, run_id, number)) + + +# ================================================================ the reads + +def _counts(trials): + counts = {state: 0 for state in TRIAL_STATES} + for trial in trials: + counts[trial['state']] = counts.get(trial['state'], 0) + 1 + return counts + + +def _best(trials, objective): + best = None + for trial in trials: + value = (trial['objectives'] or {}).get(objective['metric']) if trial['state'] == 'completed' else None + if value is None: + continue + if best is None or (value > best['value'] if objective['better'] == 'higher' else value < best['value']): + best = {'number': trial['number'], 'reference': trial['reference'], 'value': value} + return best + + +def _frontier(trials, objectives): + from . import charts + if len(objectives) != 2: + return [] + first, second = objectives + points = [(trial['number'], (trial['objectives'] or {}).get(second['metric']), + (trial['objectives'] or {}).get(first['metric'])) for trial in trials if trial['state'] == 'completed'] + points = [point for point in points if point[1] is not None and point[2] is not None] + flags = charts.frontier([(x, y) for _, x, y in points], first['better'], second['better']) + return [number for (number, _, _), on in zip(points, flags) if on] + + +def _axes(trials, parameters, objectives): + """The trials as benchmark_axes answers a benchmark's subjects: the objectives and the parameters as axes.""" + metrics = [] + for objective in objectives: + found = [(trial['objectives'] or {}).get(objective['metric']) for trial in trials] + found = [value for value in found if value is not None] + metrics.append({'id': objective['metric'], 'title': objective.get('title') or objective['metric'], 'units': '', + 'better': objective['better'], 'positive': bool(found) and all(v > 0 for v in found), + 'low': min(found) if found else None, 'high': max(found) if found else None}) + lead = objectives[0]['metric'] + settings, positions = [], {} + for item in parameters: + path = item['path'] + values = {trial['number']: trial['values'][path] for trial in trials if path in (trial['values'] or {})} + if all(_number(value) for value in values.values()): + axis = {'path': path, 'kind': 'number', 'categories': None, + 'low': min(values.values()) if values else None, 'high': max(values.values()) if values else None} + placed = dict(values) + else: + kinds = sorted({comparing._canon(value) for value in values.values()}, key=comparing._category_order) + first = {} + for value in values.values(): + first.setdefault(comparing._canon(value), value) + axis = {'path': path, 'kind': 'category', 'categories': [first[kind] for kind in kinds], + 'low': 0, 'high': max(0, len(kinds) - 1)} + placed = {number: kinds.index(comparing._canon(value)) for number, value in values.items()} + both = [trial for trial in trials if trial['state'] == 'completed' and trial['number'] in placed + and (trial['objectives'] or {}).get(lead) is not None] + axis['count'] = len(values) + axis['distinct'] = len({comparing._canon(value) for value in values.values()}) + axis['association'] = comparing.spearman([placed[trial['number']] for trial in both], + [trial['objectives'][lead] for trial in both]) + settings.append(axis) + positions[path] = placed + subjects = [{'subject': trial['reference'], 'title': f'Trial {trial["number"]}', 'recipe': trial['reference'], + 'number': trial['number'], 'state': trial['state'], + 'metrics': {objective['metric']: (trial['objectives'] or {}).get(objective['metric']) + for objective in objectives}, + 'settings': {item['path']: positions[item['path']].get(trial['number']) for item in parameters}} + for trial in trials] + return {'benchmark': None, 'statistic': None, 'metrics': metrics, 'settings': settings, 'left_out': 0, + 'subjects': subjects} + + +def _running_objectives(trial, objectives): + """A running trial's objectives so far, from its latest line (time and step as logged).""" + latest = trial['latest'] or {} + out = {} + for objective in objectives: + metric = objective['metric'] + out[metric] = latest.get(metric) if metric in SPECIAL else (latest.get('values') or {}).get(metric) + return out + + +def _request_of(project, reference): + row = project._execute('''SELECT id, state, requested_by, requested_at FROM {schema}.build_requests + WHERE targets = %s ORDER BY requested_at DESC, id LIMIT 1''', + (Jsonb([reference]),)).fetchone() + return None if row is None else dict(zip(('id', 'state', 'requested_by', 'requested_at'), row)) + + +def _rung_list(strategy, trials): + if strategy['kind'] != 'halving': + return [] + points = rung_points(strategy) + reached = max([rung['rung'] for trial in trials for rung in trial['rungs'] or []], default=-1) + return points[:max(2, reached + 2)] + + +def show(project, text, run=None): + """The answer of the read sweep (section 6).""" + reference = find(project, text) + reap(project) + sweep_text, document = _definition(project, reference) + runs = _runs_of(project, reference) + chosen = None + if run is not None: + chosen = next((item for item in runs if item['id'] == run), None) + if chosen is None: + raise ProjectError(f'{reference} has no run {run}.', 'not-found', references=[reference]) + elif runs: + chosen = runs[0] + trials = _trials_of(project, chosen['id']) if chosen else [] + defined = set(_texts(project, [trial['reference'] for trial in trials])) if trials else set() + objectives = document.get('objectives') or [] + for trial in trials: + trial['defined'] = trial['reference'] in defined + if trial['state'] == 'running': + trial['objectives'] = _running_objectives(trial, objectives) + state, _ = sweep_state(project, reference) + parameters = document.get('parameters') or [] + seconds = None + if chosen: + end = chosen['finished_at'] or _now() + seconds = (end - chosen['started_at']).total_seconds() + shown_run = None if chosen is None else { + 'id': chosen['id'], 'state': chosen['state'], 'ended': chosen['ended'], 'problem': chosen['problem'], + 'started_at': chosen['started_at'], 'finished_at': chosen['finished_at'], 'seconds': seconds, + 'trials': len(trials), 'counts': _counts(trials), 'request_id': chosen['request_id']} + return {'reference': reference, 'title': document.get('title'), 'description': document.get('description'), + 'recipe': document.get('recipe'), 'parameters': parameters, 'strategy': document.get('strategy'), + 'objectives': objectives, 'budget': document.get('budget'), 'state': state, + 'changed': bool(chosen) and chosen['sweep_sha256'] != _sha256(sweep_text), + 'request': _request_of(project, reference), 'run': shown_run, + 'runs': [{'id': item['id'], 'state': item['state'], 'started_at': item['started_at'], + 'trials': project._execute('SELECT count(*) FROM {schema}.sweep_trials WHERE sweep_run = %s', + (item['id'],)).fetchone()[0]} for item in runs], + 'trials': trials, 'best': _best(trials, objectives[0]) if objectives else None, + 'frontier': _frontier(trials, objectives), 'rungs': _rung_list(document.get('strategy') or {}, trials), + 'axes': _axes(trials, parameters, objectives) if objectives else None} + + +def listing(project): + """The answer of the read sweeps: every sweep with its latest run in brief.""" + reap(project) + rows = project._execute(f'SELECT {store._REFERENCE_SQL}, document FROM {{schema}}.definitions ' + "WHERE directory = 'sweeps' AND NOT removed ORDER BY name").fetchall() + out = [] + for reference, document in rows: + state, last = sweep_state(project, reference) + brief = None + if last is not None: + trials = _trials_of(project, last['id']) + objectives = document.get('objectives') or [] + brief = {'id': last['id'], 'state': last['state'], 'ended': last['ended'], 'started_at': last['started_at'], + 'finished_at': last['finished_at'], 'counts': _counts(trials), + 'best': _best(trials, objectives[0]) if objectives else None} + out.append({'reference': reference, 'title': document.get('title'), 'recipe': document.get('recipe'), + 'strategy': (document.get('strategy') or {}).get('kind'), 'objectives': document.get('objectives'), + 'budget': document.get('budget'), 'state': state, 'run': brief}) + return {'sweeps': out} + + +# ================================================================ the map + +def map_groups(definitions, models): + """Groups of the map for the sweeps that have trials, each model's sweep set (section 6); returns the groups. + + definitions maps references to {kind, title, document}; models are the + map's models (changed in place: sweep, and a trial's group). + """ + groups, counts = [], {} + for model in models: + document = definitions[model['reference']]['document'] + block = document.get('sweep') if isinstance(document.get('sweep'), dict) else None + sweep = block.get('definition') if block and isinstance(block.get('definition'), str) else None + found = definitions.get(sweep) if sweep else None + if found is None or found['kind'] != 'sweep': + continue + model['sweep'] = sweep + model['group'] = sweep + counts[sweep] = counts.get(sweep, 0) + 1 + for sweep in sorted(counts): + document = definitions[sweep]['document'] + recipe = definitions.get(document.get('recipe')) + parent = recipe['document'].get('group') if recipe is not None else None + groups.append({'id': sweep, 'title': definitions[sweep]['title'], + 'parent': parent if isinstance(parent, str) else None, + 'description': f'The trials of {sweep}, a search over the settings of {document.get("recipe")}.', + 'models': counts[sweep], 'sweep': True}) + return groups diff --git a/tuldok_project/workspace.py b/tuldok_project/workspace.py index be8525ad..62d36c35 100644 --- a/tuldok_project/workspace.py +++ b/tuldok_project/workspace.py @@ -187,13 +187,15 @@ def project_map(project): comparisons.append({'from': reference, 'to': item['recipe'], 'explanation': item.get('explanation'), 'excerpt': item.get('excerpt')}) + from . import sweeps # a sweep's trials are a group of their own on the map (spec-t7.md section 6) + swept = sweeps.map_groups(definitions, models) counts = {} for model in models: if model['group'] is not None: counts[model['group']] = counts.get(model['group'], 0) + 1 groups = [{'id': group['id'], 'title': group['title'], 'parent': group.get('parent'), 'description': group.get('description'), 'models': counts.get(group['id'], 0)} - for group in tuldok.get('groups', []) if isinstance(group, dict)] + for group in tuldok.get('groups', []) if isinstance(group, dict)] + swept return {'groups': groups, 'models': models, 'edges': edges, 'comparisons': comparisons, 'track': track} From e6438c312e37fa06b10ca306bd0312c17302c59e Mon Sep 17 00:00:00 2001 From: MrScripty <TheEnvironmentGuy@protonmail.com> Date: Thu, 19 Nov 2026 08:20:16 -0700 Subject: [PATCH 124/131] docs(contract): the sweep kind, its trials, its build and its two reads Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --- docs/contracts/project-folder.md | 102 +++++++++++++++++++- docs/plans/training-and-curation/spec-t7.md | 2 +- 2 files changed, 100 insertions(+), 4 deletions(-) diff --git a/docs/contracts/project-folder.md b/docs/contracts/project-folder.md index f0c6d344..d7a7cd55 100644 --- a/docs/contracts/project-folder.md +++ b/docs/contracts/project-folder.md @@ -50,6 +50,7 @@ charts/<name>.json annotations/<name>.json annotations/<name>.jsonl the annotations of task <name> annotations/<name>/ their sidecars: masks and arrays too large for a line +sweeps/<name>.json a search over a recipe's settings results/<benchmark name>.csv notes/... ``` @@ -57,7 +58,7 @@ notes/... - `tuldok.json` is required. Every other entry is optional. - Any other top-level entry is an error. Move such files into `notes/` or out of the folder. -- The eight **definition directories** (`datasets/` to `annotations/`) hold only +- The nine **definition directories** (`datasets/` to `annotations/`, and `sweeps/`) hold only `<name>.json` files, one definition each, and no subdirectories. `annotations/` also holds `<name>.jsonl`, the annotations of the task in `<name>.json`, which must exist. @@ -225,7 +226,7 @@ directory) and may not lead outside it through a symbolic link. Any other placeholder is an error, and so is a brace without its partner. Write `{{` and `}}` for literal braces. -## The eight kinds +## The nine kinds The examples below come from one project. References in them point at the other examples, except `environments/cuda-torch`, a second environment not shown. @@ -569,9 +570,10 @@ A recipe trains a model; its product is weights. | `run` | unless `earlier_work.rebuild` is `no` | see the `run` block | | `model` | no | reference to `models/` | | `group` | no | the `id` of one of the project's `groups` in `tuldok.json`: the section of the map it is shown in | -| `change` | no | `training-policy`, `architecture`, `refinement` or `component`: the kind of change this model makes | +| `change` | no | `training-policy`, `architecture`, `refinement`, `component` or `sweep-trial`: the kind of change this model makes | | `derived_from` | no | reference to another recipe in `recipes/`: the model this one was branched from. Never the recipe itself, and following `derived_from` never comes back to where it started | | `compared_with` | no | at most 50 objects, each `recipe` (reference to another recipe, each once in the list), `explanation` (1 to 2,000 characters) and `excerpt` (optional, at most 2,000 characters); no other field | +| `sweep` | no | a trial of a sweep (see [`sweep`](#sweep)): `definition` (reference to `sweeps/`), `trial` (its number, 1 or more) and `values` (the settings it was given, by path, at most 16); written by Tuldok when it runs the sweep | The label `short`, when a recipe has it, is the text of its node on the map (at most 16 characters are shown). `derived_from` and `compared_with` say how @@ -870,6 +872,51 @@ pickled. The check reports a directory with no task, and a line naming a sidecar that is not there, as errors, and a sidecar no line names as a warning; Save removes those of a task it writes. Each is at most 64 MiB. +### `sweep` + +A sweep searches the settings of one recipe on this machine, trial after +trial (docs/plans/training-and-curation/spec-t7.md). Each trial is a recipe +Tuldok writes, derived from the varied one; a sweep is built by asking for a +build of it alone, and one approval covers its whole budget. + +| Field | Required | Rule | +| --- | --- | --- | +| `recipe` | yes | reference to `recipes/`: the recipe whose `run.settings` it varies. That recipe has `run.command` and its settings written in it (not `settings_file`) | +| `parameters` | yes | 1 to 16 objects: `path`, a dotted path into `run.settings` (a part of digits indexes a list; every part but the last exists in the recipe as an object or a list), and either `values` (1 to 64 distinct numbers, texts, booleans or null) or a range `low` < `high` with `scale` (`linear`, the default, or `log`, then `low` > 0), `integer` (whole numbers) and `count` (2 to 64 points, for a grid). Each path once | +| `strategy` | yes | `{"kind": "grid"}` (every range has `count`; at most 100,000 points), `{"kind": "random", "seed"}`, or `{"kind": "halving", "seed", "metric", "better", "unit", "min", "factor"}`: random draws, and a trial stops early at a rung `min × factor^k` (in `step`s, the default, or seconds of `time`) where it is not among the best `1/factor` of the values of `metric` recorded there (`factor` 2 to 8, default 3) | +| `objectives` | yes | one or two objects with distinct `metric` (a series the trials log in `training/metrics.jsonl`, or `time` or `step`, the last logged), `better` (`lower` or `higher`), `take` (`last`, the default, or `best`) and an optional `title` | +| `budget` | yes | `trials` (1 to 1,000), optional `minutes` (above 0, at most 10,080) and `concurrency` (only 1: trials run one after another) | + +A grid with more points than `budget.trials` is a warning: the first in order +are run. The edge from a sweep to its recipe has the role `varies`, and a +trial's edge to its sweep the role `sweep`; like `derived`, building never +follows them. + +**A trial** is `recipes/<sweep name>-<NNN>` (then `-2`, `-3`, … when that name +holds something else; a trial is never overwritten), with the recipe's `run` +and its values set in `run.settings`, `derived_from` the recipe, `change` +`sweep-trial`, the label `short` `T<n>` and the `sweep` field. It is kept as +an unsaved edit and saved like any other. A trial of the same sweep with the +same text that is built already is reused, not run again. + +Example, `sweeps/lr-width.json`: + +```json +{ + "format": "tuldok_definition_v1", + "kind": "sweep", + "title": "Learning rate and width", + "recipe": "recipes/pilot-dense-k1", + "parameters": [ + {"path": "training.learning_rate", "low": 0.0001, "high": 0.01, "scale": "log"}, + {"path": "model.width", "values": [16, 32, 64]} + ], + "strategy": {"kind": "halving", "seed": 7, "metric": "val/loss", "better": "lower", "min": 200, "factor": 3}, + "objectives": [{"metric": "val/loss", "take": "best", "better": "lower"}, {"metric": "time", "better": "lower"}], + "budget": {"trials": 24, "minutes": 120} +} +``` + ## Results files `results/<name>.csv` is the summary of benchmark `benchmarks/<name>.json`, which @@ -3182,6 +3229,55 @@ value of the task, the model's words quoted. The record is read and the endpoint asked outside the service's lock; an answer not given within 300 s is given up. +### Sweeps + +A build of a sweep (`request_build` with the sweep as its only target) is +planned as what its recipe needs and one step of kind `sweep`, built, or +blocked when the recipe cannot be built for a reason other than its own +`earlier_work` label; what a request covers holds the recipe's text too. The +worker runs it trial after trial with one snapshot of the code and one plan +id, so Cancel on the request stops the trial running. While a trial runs +Tuldok reads its `training/metrics.jsonl` (as `training` does) every quarter +second, and stops it through its cancel file when halving prunes it or the +budget's minutes are spent; the run then ends `cancelled`, its problem saying +why. The request succeeds when the sweep finished (its schedule or a budget +spent). What each run of a sweep did is kept in the database (the tables +`sweep_runs` and `sweep_trials`), never in the folder. + +**`sweeps`** takes nothing and answers `sweeps`, each with `reference`, +`title`, `recipe`, `strategy` (its kind), `objectives`, `budget`, `state` +(`not-built`, `running`, `built` when its last run finished with the sweep and +its recipe as they are now, or `failed`) and `run`: null, or the latest run's +`id`, `state` (`running`, `finished`, `cancelled`, `failed`), `ended` +(`schedule`, `trials`, `minutes`, `cancelled`, `failed`), `started_at`, +`finished_at`, `counts` (trials by state: `running`, `completed`, `pruned`, +`stopped`, `failed`) and `best` (`number`, `reference`, `value` of the first +objective among the completed trials, or null). + +**`sweep`** takes `sweep` (its reference or name) and an optional `run` (an id; +default the latest) and answers the sweep's `reference`, `title`, +`description`, `recipe`, `parameters`, `strategy`, `objectives`, `budget` and +`state`; `changed` (the run shown ran another text of the sweep); `request` +(the newest build request naming it alone: `id`, `state`, `requested_by`, +`requested_at`, or null); `run` (as in `sweeps` with `problem`, `seconds`, +`trials` and `request_id`); `runs` (the last 20: `id`, `state`, `started_at`, +`trials`); `trials` (each `number`, `reference`, `values`, `state`, `reused`, +`run_id`, `started_at`, `finished_at`, `seconds`, `rungs` (each `rung`, `at`, +`value`, `n`, `kept`, `goes_on`), `objectives` (by metric; a running trial's +as far as it has logged), `latest` (`step`, `time`, `values`), `problem` and +`defined`); `best`; `frontier` (the numbers of the completed trials on the +frontier of two objectives, the second across); `rungs` (the rung points up to +the last reached and one more); and `axes`, the trials as `benchmark_axes` +answers a benchmark's subjects: `metrics` the objectives, `settings` the +parameters, `subjects` the trials (`subject` and `recipe` the trial's +reference, `number`, `state`, `metrics`, `settings`). + +**`map`** answers a group per sweep that has trials (`id` the sweep's +reference, `title` its title, `parent` the group of its recipe, `sweep` true), +after the folder's groups, and a trial's model gains `sweep` (the sweep's +reference) and has its sweep's group as `group` in the answer. Other groups +and models are answered as before, without `sweep`. + ## The Pumas endpoint Generation, suggestions and embeddings go through a Pumas endpoint, reached by HTTP diff --git a/docs/plans/training-and-curation/spec-t7.md b/docs/plans/training-and-curation/spec-t7.md index a5c20c51..9cb90202 100644 --- a/docs/plans/training-and-curation/spec-t7.md +++ b/docs/plans/training-and-curation/spec-t7.md @@ -70,7 +70,7 @@ Two reads, `inspect`, in the `project_folder` profile only (the catalog's digest | `sweeps` | none | `sweeps`: each `reference`, `title`, `recipe`, `strategy` (its kind), `objectives`, `budget`, `state` (as in a plan), and `run`: null or the latest run's `id`, `state`, `ended`, `started_at`, `finished_at`, `counts` (by trial state), `best` | | `sweep` | `sweep` (a reference or a bare name), optional `run` (a run id; default the latest) | `reference`, `title`, `description`, `recipe`, `parameters`, `strategy`, `objectives`, `budget`, `state`, `changed` (the latest run ran another text), `request` (the newest build request naming it: `id`, `state`, `requested_by`), `run` (null, or `id`, `state`, `ended`, `problem`, `started_at`, `finished_at`, `seconds`, `trials`, `counts`), `runs` (the last 20: `id`, `state`, `started_at`, `trials`), `trials` (each `number`, `reference`, `values`, `state`, `reused`, `run_id`, `seconds`, `rungs`, `objectives`, `latest`, `problem`, `defined`), `best` (`number`, `reference`, `value`, or null), `frontier` (the numbers of the completed trials on the frontier of the two objectives; empty with one), `rungs` (the rung points up to the last reached and one more), `axes` (as `benchmark_axes` answers: `metrics` the objectives, `settings` the parameters, `subjects` the trials) | -`map` gains a group per sweep that has trials (`id` the sweep's reference, `title` its title, `parent` the varied recipe's group, `sweep` true) and each model a `sweep` (the reference, or null); a trial's `group` in the answer is its sweep's group. The folder's `groups` are unchanged. +`map` gains a group per sweep that has trials (`id` the sweep's reference, `title` its title, `parent` the varied recipe's group, `sweep` true), and a trial's model a `sweep` (the reference); a trial's `group` in the answer is its sweep's group. The folder's `groups` and the other models are answered as before. ## 7. The page: the Sweeps tab From 0e5287e4b352eb1d5a7371379a6b9df83e6ce207 Mon Sep 17 00:00:00 2001 From: MrScripty <TheEnvironmentGuy@protonmail.com> Date: Thu, 19 Nov 2026 08:29:25 -0700 Subject: [PATCH 125/131] fix(project): a sweep's own connection is closed however it ends Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --- tuldok_project/sweeps.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/tuldok_project/sweeps.py b/tuldok_project/sweeps.py index 62b1bc20..e98888c9 100644 --- a/tuldok_project/sweeps.py +++ b/tuldok_project/sweeps.py @@ -747,6 +747,9 @@ def execute(project_folder, made, *, request_id=None, extra_env=None, scratch=Fa Jsonb(sweep['budget']), os.getpid(), builds.boot_id())) ended, problem = _run(build, folder, dsn, connection, schema, run_id, reference, sweep, recipe_reference, recipe, made, stop, clock) + final = {'failed': 'failed', 'cancelled': 'cancelled'}.get(ended, 'finished') + connection.execute(_q(schema, '''UPDATE {schema}.sweep_runs SET state = %s, ended = %s, problem = %s, + finished_at = now() WHERE id = %s'''), (final, ended, problem, run_id)) except BaseException as exc: connection.execute(_q(schema, '''UPDATE {schema}.sweep_runs SET state = 'failed', ended = 'failed', problem = %s, finished_at = now() WHERE id = %s'''), @@ -757,10 +760,7 @@ def execute(project_folder, made, *, request_id=None, extra_env=None, scratch=Fa finally: with _ACTIVE_LOCK: _ACTIVE.discard(run_id) - final = {'failed': 'failed', 'cancelled': 'cancelled'}.get(ended, 'finished') - connection.execute(_q(schema, '''UPDATE {schema}.sweep_runs SET state = %s, ended = %s, problem = %s, - finished_at = now() WHERE id = %s'''), (final, ended, problem, run_id)) - connection.close() + connection.close() result['ok'] = final == 'finished' return result From 4b9188aa7ad21df9b66d03d97fbd6bd0079499f5 Mon Sep 17 00:00:00 2001 From: MrScripty <TheEnvironmentGuy@protonmail.com> Date: Thu, 19 Nov 2026 08:29:25 -0700 Subject: [PATCH 126/131] feat(workspace): the Sweeps tab, a sweep's state live, its trials in parallel coordinates and on its frontier New sweep writes a sweep's text from a recipe's settings; the state block (run, trials by how they ended, budget used, running trial, best so far) is set in place on every reading; Approve and Decline when a request awaits approval; the trials table opens a trial in the drawer or on the Map, where trials carry the kind of change Sweep trial. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --- app.py | 2 + static/project-workspace.html | 2 + static/project-workspace/adapter.js | 3 +- static/project-workspace/app.js | 4 +- static/project-workspace/editor.js | 4 +- static/project-workspace/parallel.js | 6 +- static/project-workspace/sweeps.css | 46 +++ static/project-workspace/sweeps.js | 335 +++++++++++++++++++++ tests/browser_project_workspace_sweeps.cjs | 287 ++++++++++++++++++ 9 files changed, 681 insertions(+), 8 deletions(-) create mode 100644 static/project-workspace/sweeps.css create mode 100644 static/project-workspace/sweeps.js create mode 100644 tests/browser_project_workspace_sweeps.cjs diff --git a/app.py b/app.py index cea3d306..25d5328e 100644 --- a/app.py +++ b/app.py @@ -800,6 +800,8 @@ def _get(self): '/project-workspace/compare.css': ('project-workspace/compare.css', 'text/css'), '/project-workspace/compare.js': ('project-workspace/compare.js', 'text/javascript'), '/project-workspace/parallel.js': ('project-workspace/parallel.js', 'text/javascript'), + '/project-workspace/sweeps.css': ('project-workspace/sweeps.css', 'text/css'), + '/project-workspace/sweeps.js': ('project-workspace/sweeps.js', 'text/javascript'), '/project-workspace/review.css': ('project-workspace/review.css', 'text/css'), '/project-workspace/review.js': ('project-workspace/review.js', 'text/javascript'), '/project-workspace/adapter.js': ('project-workspace/adapter.js', 'text/javascript'), diff --git a/static/project-workspace.html b/static/project-workspace.html index bade2554..0cf646cf 100644 --- a/static/project-workspace.html +++ b/static/project-workspace.html @@ -10,6 +10,7 @@ <link rel="stylesheet" href="/project-workspace/base.css"> <link rel="stylesheet" href="/project-workspace/compare.css"> <link rel="stylesheet" href="/project-workspace/review.css"> +<link rel="stylesheet" href="/project-workspace/sweeps.css"> <script defer src="/auth.js"></script> <script defer src="/project-workspace/adapter.js"></script> <script defer src="/project-workspace/charts.js"></script> @@ -29,6 +30,7 @@ <script defer src="/project-workspace/parallel.js"></script> <script defer src="/project-workspace/curation.js"></script> <script defer src="/project-workspace/tabs.js"></script> +<script defer src="/project-workspace/sweeps.js"></script> <script defer src="/project-workspace/compare.js"></script> <script defer src="/project-workspace/app.js"></script> </head> diff --git a/static/project-workspace/adapter.js b/static/project-workspace/adapter.js index 93be789a..c101f813 100644 --- a/static/project-workspace/adapter.js +++ b/static/project-workspace/adapter.js @@ -16,7 +16,8 @@ window.TuldokProject = (() => { { id: 'training-policy', label: 'Training policy' }, { id: 'architecture', label: 'Architecture' }, { id: 'refinement', label: 'Refinement' }, - { id: 'component', label: 'Component' } + { id: 'component', label: 'Component' }, + { id: 'sweep-trial', label: 'Sweep trial' } // a trial a sweep made (spec-t7) ]; const UNSET = 'unset'; // the class and filter key of a model without a kind of change const kindLabel = id => (KINDS.find(k => k.id === id) || { label: 'Kind not set' }).label; diff --git a/static/project-workspace/app.js b/static/project-workspace/app.js index ef591c55..044658dd 100644 --- a/static/project-workspace/app.js +++ b/static/project-workspace/app.js @@ -19,7 +19,7 @@ // shows the conflict panel. (() => { const P = window.TuldokProject, S = window.LabScreens, A = window.LabActions; - const TABS = [['map', 'Map'], ['data', 'Data'], ['annotate', 'Annotate'], ['train', 'Train'], ['benchmarks', 'Benchmarks'], ['compare', 'Compare'], ['analysis', 'Analysis'], ['overview', 'Overview']]; + const TABS = [['map', 'Map'], ['data', 'Data'], ['annotate', 'Annotate'], ['train', 'Train'], ['sweeps', 'Sweeps'], ['benchmarks', 'Benchmarks'], ['compare', 'Compare'], ['analysis', 'Analysis'], ['overview', 'Overview']]; const POLL_MS = 2000, IDLE_MS = 15000; // how often the page asks again while something builds, and while nothing does const ACTIVE_RUN = ['queued', 'running'], ACTIVE_REQUEST = ['queued', 'running']; const $ = id => document.getElementById(id); @@ -65,7 +65,7 @@ }; // The settings of the Analysis tab the address keeps, so that a reload opens it where it was (spec-d6 section 3). // And those of the Training block of a run's drawer (spec-t1 section 6): the runs compared, the series, smoothing, log scale, across. - const ADDRESSED = ['anaBench', 'anaSubject', 'anaMetric', 'anaCase', 'anaAxis', 'anaIndex', 'anaMeanFree', 'trWith', 'trSeries', 'trSmooth', 'trLog', 'trX', 'cmpCase', 'cmpAxis', 'cmpIndex', 'cmpMeanFree']; + const ADDRESSED = ['anaBench', 'anaSubject', 'anaMetric', 'anaCase', 'anaAxis', 'anaIndex', 'anaMeanFree', 'trWith', 'trSeries', 'trSmooth', 'trLog', 'trX', 'cmpCase', 'cmpAxis', 'cmpIndex', 'cmpMeanFree', 'sweep']; // sweep: the Sweeps tab's (spec-t7) const COMPARE_MOST = 4; /** Writes the benchmark, the compare set and the Analysis tab's settings into the address without reloading, so the view can be shared. */ function address() { diff --git a/static/project-workspace/editor.js b/static/project-workspace/editor.js index a1ed5bd0..ee438f7c 100644 --- a/static/project-workspace/editor.js +++ b/static/project-workspace/editor.js @@ -16,8 +16,8 @@ window.LabEditor = (() => { const { sect, modelState } = S.parts; const isObject = v => !!v && typeof v === 'object' && !Array.isArray(v); const button = (cls, text, key, onClick) => { const b = h('button', cls, text); b.type = 'button'; if (key) b.dataset.key = key; if (onClick) b.addEventListener('click', onClick); return b; }; - const KIND_ORDER = ['recipe', 'dataset', 'annotation', 'model', 'step', 'benchmark', 'chart', 'environment']; - const KIND_TITLE = { recipe: 'Recipes', dataset: 'Datasets', model: 'Models', step: 'Steps', benchmark: 'Benchmarks', chart: 'Charts', environment: 'Environments', annotation: 'Annotation tasks' }; + const KIND_ORDER = ['recipe', 'sweep', 'dataset', 'annotation', 'model', 'step', 'benchmark', 'chart', 'environment']; + const KIND_TITLE = { recipe: 'Recipes', dataset: 'Datasets', model: 'Models', step: 'Steps', benchmark: 'Benchmarks', chart: 'Charts', environment: 'Environments', annotation: 'Annotation tasks', sweep: 'Sweeps' }; // ---- Page memory ------------------------------------------------------------ const buffers = new Map(); // reference -> { text, base }: typed and not kept yet diff --git a/static/project-workspace/parallel.js b/static/project-workspace/parallel.js index 6b449af6..50e6a433 100644 --- a/static/project-workspace/parallel.js +++ b/static/project-workspace/parallel.js @@ -67,10 +67,10 @@ window.LabParallel = (() => { function fill(ctx) { const { data, state, sec, all } = ctx, ui = state.ui, axes = shownAxes(all, ui), keep = keptOf(data, all, ui); const items = []; - const head = S.parts.sect('Settings and metrics', data.subjects.length + ' subjects · ' + axes.length + ' of ' + all.length + ' axes'); + const head = S.parts.sect('Settings and metrics', data.subjects.length + ' ' + (ctx.view.noun || 'subjects') + ' · ' + axes.length + ' of ' + all.length + ' axes'); const count = h('span', 'pc-count small'); count.setAttribute('aria-live', 'polite'); head.appendChild(count); ctx.count = count; items.push(head); - items.push(h('p', 'small faint bench-desc', 'One line per subject through its metrics (the ' + data.statistic + ' over its cases) and the recipe settings that vary between subjects. Drag along an axis to keep the subjects inside a range; the table and the charts above follow. ' + (data.left_out ? data.left_out + ' more settings are not offered.' : ''))); + items.push(h('p', 'small faint bench-desc', ctx.view.lead ? ctx.view.lead + (data.left_out ? ' ' + data.left_out + ' more settings are not offered.' : '') : 'One line per subject through its metrics (the ' + data.statistic + ' over its cases) and the recipe settings that vary between subjects. Drag along an axis to keep the subjects inside a range; the table and the charts above follow. ' + (data.left_out ? data.left_out + ' more settings are not offered.' : ''))); const host = h('div', 'pc-draw'); ctx.host = host; items.push(host); items.push(axisControls(ctx, axes)); items.push(chooser(ctx, axes)); @@ -95,7 +95,7 @@ window.LabParallel = (() => { const scales = axes.map(a => scaleOf(a, ui)); // The lines. const lines = el('g', { class: 'pc-lines' }); - const sel = state.sel.benchmarks || null; + const sel = view.selected !== undefined ? view.selected : state.sel.benchmarks || null; // a sweep's view gives its own for (const row of data.subjects) { const s = view.byName.get(row.subject), kind = s ? s.kind : 'other'; let d = '', open = false; diff --git a/static/project-workspace/sweeps.css b/static/project-workspace/sweeps.css new file mode 100644 index 00000000..83991722 --- /dev/null +++ b/static/project-workspace/sweeps.css @@ -0,0 +1,46 @@ +/* The Sweeps tab and the kind of change "sweep trial" (docs/plans/training-and-curation/spec-t7.md section 7), on + the tokens of base.css. The trial's colour is the purple of the training runs (--run-3), already checked beside + the other kinds' colours for colour-blind separation and contrast in both themes. */ +:root { --k-sweep-trial: #8a4fbf; } +@media (prefers-color-scheme: dark) { :root:not([data-theme="light"]) { --k-sweep-trial: #9a72d8; } } +:root[data-theme="dark"] { --k-sweep-trial: #9a72d8; } + +/* The kind of change wherever the others are drawn. */ +.chip.sweep-trial::before { background: var(--k-sweep-trial); } +.chart .pt.sweep-trial { fill: var(--k-sweep-trial); } +.tree-list .dot.sweep-trial { fill: var(--k-sweep-trial); } +.lk-sweep-trial { stroke: var(--k-sweep-trial); } +.tree-map .tpt.sweep-trial { fill: var(--k-sweep-trial); } +.tree-map .node.sweep-trial circle { fill: var(--k-sweep-trial); } +.tree-map .node.planned.sweep-trial circle { fill: var(--surface); stroke: var(--k-sweep-trial); } +.tree-list .dot.planned.sweep-trial { fill: var(--surface); stroke: var(--k-sweep-trial); } +.pc .pcl.sweep-trial { stroke: var(--k-sweep-trial); } + +/* The tab. */ +.sw-head { display: grid; gap: 8px; min-width: 0; } +.sw-head .sect { margin-top: 6px; } +.sw-what { margin: 0; max-width: 980px; overflow-wrap: anywhere; } +.linkish { background: none; border: 0; padding: 0; color: var(--accent); cursor: pointer; font: inherit; text-decoration: underline; text-underline-offset: 2px; } +.linkish:focus-visible { outline: 2px solid var(--focus); outline-offset: 2px; } +.sw-controls { margin-top: 12px; display: grid; gap: 6px; } +.sw-controls .sw-ask { margin: 0; } +.sw-state { margin-top: 14px; } +.sw-dl { grid-template-columns: minmax(110px, max-content) minmax(0, 1fr); } +.sw-dl dd { min-width: 0; overflow-wrap: anywhere; } +.sw-gap { margin-left: 6px; } +.sw-meter { display: flex; align-items: center; gap: 10px; flex-wrap: wrap; } +.sw-meter .hair { position: relative; width: 160px; max-width: 40vw; height: 4px; background: var(--grid); border-radius: 2px; flex: none; overflow: hidden; } +.sw-meter .hair i { position: absolute; left: 0; top: 0; bottom: 0; background: var(--accent); transition: width .3s; } +.sw-pc, .sw-chart, .sw-trials { margin-top: 18px; } +.sw-table tr.sw-row { cursor: pointer; } +.sw-table tr.sw-row:hover td, .sw-table tr.sw-row.on td { background: var(--accent-wash); } +.sw-table tr.sw-row:focus-visible { outline: 2px solid var(--focus); outline-offset: -2px; } +.sw-new .sw-text { width: 100%; min-height: 280px; font-size: 12.5px; } + +/* The trials' lines in parallel coordinates, by how they ended. */ +.pc .pcl.tr-completed { stroke: var(--k-sweep-trial); } +.pc .pcl.tr-running { stroke: var(--accent); stroke-width: 2.2; opacity: 1; } +.pc .pcl.tr-pruned { stroke: var(--ink-3); stroke-dasharray: 4 3; } +.pc .pcl.tr-stopped { stroke: var(--ink-3); stroke-dasharray: 1 3; } +.pc .pcl.tr-failed { stroke: var(--serious); stroke-dasharray: 4 3; } +.pc .pcl.tr-pruned.out, .pc .pcl.tr-stopped.out, .pc .pcl.tr-failed.out, .pc .pcl.tr-completed.out { opacity: .08; } diff --git a/static/project-workspace/sweeps.js b/static/project-workspace/sweeps.js new file mode 100644 index 00000000..d214fee2 --- /dev/null +++ b/static/project-workspace/sweeps.js @@ -0,0 +1,335 @@ +'use strict'; +// The Sweeps tab (docs/plans/training-and-curation/spec-t7.md section 7), added to window.LabScreens: one sweep at a +// time (the chooser, kept in the address as ?sweep=), its state live (the run, the trials by how they ended, the +// budget used, the running trial, the best so far), its controls (Plan sweep, Approve and Decline when a request +// awaits approval, Cancel), its trials through parallel coordinates (parallel.js, the trials as a benchmark's subjects, +// the main view), its frontier with two objectives (charts.js's tradeoff chart) or the progression of its one +// objective, and every trial in a table that opens it in the drawer or on the Map. The drawer holds a trial (the +// model's drawer), the plan view of the sweep, or New sweep: a recipe chosen, a sweep's text written from its +// settings, kept with Keep. +// +// Updating in place (spec-w4): the tab is built once for a sweep and the person's choices (tabs.js's paint). A +// reading of the page (app.js marks the drawer _again, and S.tick while a sweep runs) asks `sweep` again and sets what +// changed in place: the texts and bars of the state block (no node of it added or removed), the cells of the trials' +// rows (a row appended for a new trial), the charts drawn again in their hosts and parallel coordinates in their +// section, the controls when what they offer differs. The tab is never emptied by a reading. +(() => { + const S = window.LabScreens, P = window.TuldokProject, Tree = window.LabTree, C = window.LabCharts, h = C.h; + const A = window.LabActions; + const { sect, failure, putInPlace } = S.parts; + const fmt = C.fmtSci; + const TRIAL_TONE = { completed: 'good', running: 'pending', pruned: 'warn', stopped: 'neutral', failed: 'serious' }; + const TRIAL_STATES = ['completed', 'running', 'pruned', 'stopped', 'failed']; + const RUN_TONE = { running: 'pending', finished: 'good', cancelled: 'neutral', failed: 'serious' }; + const ENDED = { schedule: 'its schedule was done', trials: 'its trials were spent', minutes: 'its minutes were spent', cancelled: 'it was cancelled', failed: 'it failed' }; + const STATE_WORD = { 'not-built': 'not run yet', running: 'running', built: 'finished', failed: 'failed' }; + const REFRESH_MS = 500; // S.tick asks nothing when the drawing of this reading has just asked + const button = (cls, text, onClick, key) => { const b = h('button', cls, text); b.type = 'button'; if (key) b.dataset.key = key; if (onClick) b.addEventListener('click', onClick); return b; }; + const shown = v => v === null || v === undefined ? '—' : typeof v === 'number' ? fmt(v) : typeof v === 'string' ? v : JSON.stringify(v); + const plural = (n, one, many) => n + ' ' + (n === 1 ? one : many || one + 's'); + const minutes = s => s == null ? '—' : s < 90 ? Math.round(s) + ' s' : (s / 60).toFixed(1) + ' min'; + const title = o => o.title || o.metric; + let live = null; // the sweep on screen: { reference, main, answer, parts, at, busy } + + // ---- Reading ------------------------------------------------------------------------------------------------------ + const sweepOf = reference => P.call('sweep', { sweep: reference }); + + // ---- The screen --------------------------------------------------------------------------------------------------- + function sweeps(main, aside, state, act, data) { + const ui = state.ui, sel = state.sel.sweeps || null; + const again = document.getElementById('aside')._again; + if (again && live && live.main === main && main._painted === main._view && live.wanted === (ui.sweep || null)) refresh(act); + else S.paint(main, async () => { + const list = (await P.read('sweeps')).sweeps; + const chosen = list.find(s => s.reference === ui.sweep) || list[0] || null; + return { list, answer: chosen ? await sweepOf(chosen.reference) : null }; + }, (frag, { list, answer }, width) => { + live = null; + frag.appendChild(head(list, answer, act, ui)); + if (!answer) { frag.appendChild(h('p', 'empty', 'This project has no sweep yet. A sweep tries settings of a recipe, one trial after another, within a budget: New sweep writes one from a recipe.')); return; } + live = { reference: answer.reference, wanted: ui.sweep || null, main, answer, width, state, act, data, at: Date.now(), parts: {} }; + build(frag, live); + }); + return drawer(aside, sel, state, act, data); + } + + /** The drawer: New sweep, the plan view of the sweep, or a trial (the model's drawer). */ + function drawer(aside, sel, state, act, data) { + if (!sel) { aside.textContent = ''; aside._for = null; return false; } + if (sel === 'new') { newSweep(aside, act, data); return true; } + if (sel.startsWith('plan:')) { A.planView(aside, sel, act.go, () => act.select(null)); return true; } + if (data.map.byId.has(sel)) { S.inspectorModel(aside, sel, act, data); return true; } + aside.textContent = ''; aside._for = null; return false; + } + + /** The chooser, what the sweep is, and New sweep. */ + function head(list, answer, act, ui) { + const box = h('div', 'sw-head'); + const bar = h('div', 'filters'); + if (list.length) { + const s = h('select'); s.setAttribute('aria-label', 'Sweep'); s.dataset.key = 'sweep'; + for (const item of list) { const o = h('option', null, item.title + ' · ' + (STATE_WORD[item.state] || item.state)); o.value = item.reference; o.selected = answer && item.reference === answer.reference; s.appendChild(o); } + s.addEventListener('change', () => act.setUI('sweep', s.value)); + bar.appendChild(s); + } + if (A.may('edit')) bar.appendChild(button('btn sm', 'New sweep', () => act.select('new'), 'sweep-new')); + box.appendChild(bar); + if (!answer) return box; + box.appendChild(sect(answer.title, answer.reference)); + const what = h('p', 'small muted sw-what'); + what.appendChild(document.createTextNode('Varies ')); + const link = button('linkish mono', answer.recipe, () => act.go('map', answer.recipe), 'sweep-recipe'); link.title = 'Open the recipe on the Map'; what.appendChild(link); + what.appendChild(document.createTextNode(': ' + answer.parameters.map(p => p.path + ' ' + rangeWords(p)).join('; ') + '. ' + strategyWords(answer.strategy) + ' Objectives: ' + answer.objectives.map(o => title(o) + ' (' + (o.take === 'best' ? 'best' : 'last') + ', ' + o.better + ' is better)').join(' and ') + '. Budget: ' + plural(answer.budget.trials, 'trial') + (answer.budget.minutes ? ', ' + answer.budget.minutes + ' min' : '') + ', one at a time.')); + box.appendChild(what); + if (answer.description) box.appendChild(h('p', 'small faint sw-what', answer.description)); + return box; + } + const rangeWords = p => p.values ? 'in ' + p.values.map(shown).join(', ') : 'from ' + fmt(p.low) + ' to ' + fmt(p.high) + (p.scale === 'log' ? ' (log)' : '') + (p.integer ? ', whole numbers' : '') + (p.count ? ', ' + p.count + ' points' : ''); + function strategyWords(s) { + if (s.kind === 'grid') return 'Every point of the grid, in order.'; + if (s.kind === 'random') return 'Random draws (seed ' + s.seed + ').'; + return 'Random draws (seed ' + s.seed + '), stopping a trial at a rung (' + (s.unit === 'time' ? 'seconds' : 'steps') + ' ' + s.min + ', ×' + (s.factor || 3) + ' after) when its ' + s.metric + ' is not among the best 1/' + (s.factor || 3) + ' there.'; + } + + /** The sweep's sections, into frag; the parts that a reading sets in place are kept in v.parts. */ + function build(frag, v) { + const a = v.answer; + const controls = h('div', 'sw-controls'); controls.dataset.key = 'sw-controls'; v.parts.controls = controls; fillControls(v); + frag.appendChild(controls); + frag.appendChild(stateBlock(v)); + const pc = h('div', 'sw-pc'); v.parts.pc = pc; frag.appendChild(pc); drawAxes(v); + const chart = h('section', 'bench-chart sw-chart'); v.parts.chart = chart; frag.appendChild(chart); drawChart(v); + frag.appendChild(trialTable(v)); + if (window.LabParallel) window.LabParallel.apply(frag, viewOf(a), v.state); + setState(v); + } + + // ---- The state, set in place -------------------------------------------------------------------------------------- + function stateBlock(v) { + const sec = h('section', 'sw-state'); sec.dataset.key = 'sw-state'; sec.setAttribute('aria-live', 'polite'); + sec.appendChild(sect('Where it stands')); + const dl = h('dl', 'setup sw-dl'), p = v.parts; + const text = (cls) => { const t = document.createTextNode(''); const dd = h('dd', cls || null); dd.appendChild(t); return [dd, t]; }; + const row = (label, dd) => { dl.appendChild(h('dt', null, label)); dl.appendChild(dd); }; + { const dd = h('dd'); const chip = h('span', 'state neutral sw-chip'); p.chipText = document.createTextNode(''); chip.appendChild(p.chipText); p.chip = chip; dd.appendChild(chip); const t = document.createTextNode(''); p.runText = t; dd.appendChild(h('span', 'small faint sw-gap')).appendChild(t); row('Run', dd); } + { const [dd, t] = text(); p.counts = t; row('Trials', dd); } + { const dd = h('dd', 'sw-meter'); const hair = h('span', 'hair'); const i = h('i'); hair.appendChild(i); p.trialsBar = i; dd.appendChild(hair); const t = document.createTextNode(''); p.trialsText = t; dd.appendChild(h('span', 'small')).appendChild(t); row('Budget, trials', dd); } + { const dd = h('dd', 'sw-meter'); const hair = h('span', 'hair'); const i = h('i'); hair.appendChild(i); p.minutesBar = i; dd.appendChild(hair); const t = document.createTextNode(''); p.minutesText = t; dd.appendChild(h('span', 'small')).appendChild(t); row('Budget, time', dd); } + { const [dd, t] = text('mono'); p.running = t; row('Running', dd); } + { const [dd, t] = text(); p.best = t; row('Best so far', dd); } + sec.appendChild(dl); + p.state = sec; + return sec; + } + const setText = (node, text) => { if (node.data !== text) node.data = text; }; + function setState(v) { + const a = v.answer, p = v.parts, run = a.run, counts = run ? run.counts : {}; + const tone = run ? RUN_TONE[run.state] || 'neutral' : 'neutral'; + const cls = 'state sw-chip ' + (tone === 'pending' ? 'warn' : tone); + if (p.chip.className !== cls) p.chip.className = cls; + setText(p.chipText, run ? run.state : (a.request ? a.request.state.replace('-', ' ') : 'not run yet')); + setText(p.runText, run ? ' · started ' + S.parts.time(run.started_at) + (run.finished_at ? ', ended: ' + (ENDED[run.ended] || run.ended) : ' · ' + minutes(run.seconds) + ' so far') + (run.problem ? ' · ' + run.problem : '') + (a.changed ? ' · the sweep has changed since' : '') : a.request ? ' · a build request ' + a.request.state.replace('-', ' ') : ' · ask for a build of the sweep: Plan sweep'); + setText(p.counts, TRIAL_STATES.map(s => (counts[s] || 0) + ' ' + s).join(' · ')); + const used = run ? run.trials : 0, most = a.budget.trials; + const width = Math.round(100 * Math.min(1, used / Math.max(1, most))) + '%'; if (p.trialsBar.style.width !== width) p.trialsBar.style.width = width; + setText(p.trialsText, used + ' of ' + most); + const limit = a.budget.minutes ? a.budget.minutes * 60 : null, spent = run ? run.seconds : 0; + const mw = limit ? Math.round(100 * Math.min(1, (spent || 0) / limit)) + '%' : '0%'; if (p.minutesBar.style.width !== mw) p.minutesBar.style.width = mw; + setText(p.minutesText, minutes(spent || 0) + (limit ? ' of ' + minutes(limit) : ', no limit')); + const now = a.trials.find(t => t.state === 'running'); + setText(p.running, now ? 'Trial ' + now.number + ' · step ' + shown(now.latest && now.latest.step) + a.objectives.map(o => ' · ' + title(o) + ' ' + shown(now.objectives && now.objectives[o.metric])).join('') : '—'); + setText(p.best, a.best ? 'Trial ' + a.best.number + ' · ' + title(a.objectives[0]) + ' ' + fmt(a.best.value) : '—'); + } + + // ---- Controls ----------------------------------------------------------------------------------------------------- + function fillControls(v) { + const a = v.answer, r = a.request, waiting = r && r.state === 'awaiting-approval', active = r && ['awaiting-approval', 'queued', 'running'].includes(r.state); + const key = JSON.stringify([a.reference, a.state, r && r.id, r && r.state, A.may('owner'), A.may('request'), A.may('cancel')]); + const box = v.parts.controls; + if (box._key === key) return; + box._key = key; + const items = [{ id: 'plan', label: 'Plan sweep', cls: 'btn' + (active ? '' : ' primary'), who: 'request', onClick: () => v.act.select('plan:' + a.reference), hidden: !!active }]; + if (r) { + items.push({ id: 'approve', label: 'Approve', cls: 'btn primary', who: 'owner', op: 'approve_build', args: () => ({ request: r.id }), busy: 'Approving…', hidden: !waiting }); + items.push(Object.assign(A.declineItem(r.id), { cls: 'btn', hidden: !waiting })); + items.push({ id: 'cancel', label: 'Cancel', cls: 'btn ghost', who: 'cancel', op: 'cancel_build', args: () => ({ request: r.id }), busy: 'Cancelling…', hidden: !active, + confirm: r.state === 'running' ? 'Cancel the sweep: the running trial is stopped and no other starts.' : 'Cancel this request; no trial runs.' }); + } + const frag = document.createDocumentFragment(); + if (waiting) frag.appendChild(h('p', 'note sw-ask', (r.requested_by && (r.requested_by.label || r.requested_by.kind) || 'Someone') + ' asks for this sweep. One approval covers its whole budget: up to ' + plural(a.budget.trials, 'trial') + (a.budget.minutes ? ' and ' + a.budget.minutes + ' min' : '') + ', one after another.')); + frag.appendChild(A.group('sweep:' + a.reference + ':' + (r ? r.id : ''), items, { inline: true })); + if (box.isConnected) putInPlace(box, frag, document.getElementById('main')); else box.replaceChildren(frag); + } + + // ---- Parallel coordinates and the chart --------------------------------------------------------------------------- + /** The trials as parallel.js and its apply() see a benchmark's subjects: by reference, coloured by their state. */ + function viewOf(a) { + const byName = new Map(); + for (const t of a.trials) byName.set(t.reference, { name: t.reference, key: t.reference, full: 'Trial ' + t.number, kind: 'tr-' + t.state }); + return { name: 'sweep:' + a.reference, byName, byKey: byName, selected: null, noun: 'trials', lead: 'One line per trial through the settings it was given and its objectives (the colour is how it ended). Drag along an axis to keep the trials inside a range; the table below follows.' }; + } + function drawAxes(v) { + const a = v.answer, host = v.parts.pc; + host._key = JSON.stringify(a.axes); + if (!window.LabParallel || !a.axes || a.trials.length < 2) { host.replaceChildren(h('p', 'empty', a.trials.length ? 'Parallel coordinates are drawn from two trials on.' : 'No trial yet: its trials are drawn here as lines through their settings and objectives.')); return; } + const data = Object.assign({}, a.axes, { benchmark: 'sweep:' + a.reference, statistic: 'value' }); + const view = viewOf(a); + host.replaceChildren(window.LabParallel.section(data, view, v.state, v.act, v.width)); + } + function drawChart(v) { + const a = v.answer, host = v.parts.chart, done = a.trials.filter(t => t.state === 'completed'); + host._key = JSON.stringify([a.objectives, done.map(t => [t.number, t.objectives]), a.frontier]); + host.dataset.chart = 'sweep'; + const [y, x] = a.objectives; + const parts = []; + if (x) parts.push(sect(title(y) + ' against ' + title(x), done.length + ' completed trials · ' + a.frontier.length + ' on the frontier')); + else parts.push(sect(title(y) + ' by trial', done.length + ' completed trials, the best so far as a step line')); + const draw = h('div'); + const valued = done.filter(t => t.objectives && t.objectives[y.metric] != null && (!x || t.objectives[x.metric] != null)); + if (!valued.length) parts.push(h('p', 'empty', 'No completed trial has its objectives yet.')); + else { + parts.push(draw); + const front = new Set(a.frontier); + const rows = t => () => [{ b: 'Trial ' + t.number }].concat(a.objectives.map(o => ({ v: fmt(t.objectives[o.metric]), l: title(o) }))).concat(Object.entries(t.values).map(([k, val]) => ({ v: shown(val), l: k }))); + const select = id => v.act.select(v.state.sel.sweeps === id ? null : id); + if (x) { + C.scatter(draw, valued.map(t => ({ id: t.reference, name: 'Trial ' + t.number, short: 'T' + t.number, kind: 'sweep-trial', x: t.objectives[x.metric], y: t.objectives[y.metric], frontier: front.has(t.number), rows: rows(t) })), + { width: v.width, height: 320, xTitle: title(x), yTitle: title(y), xName: title(x), yName: title(y), xBetter: x.better, yBetter: y.better, selected: v.state.sel.sweeps, onSelect: select }); + parts.push(h('p', 'small faint', 'Line: the frontier of the completed trials, where no other is at least as good on both and better on one. Pruned and stopped trials are left out: they did not finish.')); + } else { + let best = null; + C.progression(draw, valued.map(t => { const val = t.objectives[y.metric]; if (best === null || (y.better === 'higher' ? val > best : val < best)) best = val; return { id: t.reference, name: 'Trial ' + t.number, short: 'T' + t.number, kind: 'sweep-trial', y: val, best, rows: rows(t) }; }), + { width: v.width, height: 240, yTitle: title(y), selected: v.state.sel.sweeps, onSelect: select }); + } + } + if (host.isConnected) { const frag = document.createDocumentFragment(); frag.append(...parts); putInPlace(host, frag, document.getElementById('main')); } + else host.replaceChildren(...parts); + } + + // ---- The trials --------------------------------------------------------------------------------------------------- + function trialTable(v) { + const a = v.answer, sec = h('section', 'bench-all sw-trials'); + sec.appendChild(sect('Trials', plural(a.trials.length, 'trial') + (a.run ? ' of this run' : ''))); + const t = h('table', 'tv sw-table'); t.setAttribute('aria-label', 'The trials of ' + a.title); + const thead = h('thead'), tr = h('tr'); + for (const [label, cls] of [['#', 'n']].concat(a.parameters.map(p => [p.path, 'n mono']), [['State'], ['Rung']], a.objectives.map(o => [title(o), 'n']), [['Time', 'n'], ['']])) tr.appendChild(h('th', cls || null, label)); + thead.appendChild(tr); t.appendChild(thead); + const tb = h('tbody'); v.parts.rows = new Map(); v.parts.tbody = tb; + for (const trial of a.trials) tb.appendChild(trialRow(v, trial)); + t.appendChild(tb); + const wrap = h('div', 'tv-wrap'); wrap.appendChild(t); sec.appendChild(wrap); + if (!a.trials.length) sec.appendChild(h('p', 'note', a.run ? 'No trial has started yet.' : 'No trial yet.')); + return sec; + } + function trialRow(v, trial) { + const a = v.answer, tr = h('tr'); tr.dataset.subject = trial.reference; tr.dataset.trial = String(trial.number); + const cells = { values: [], objectives: [] }; + const td = (cls, text) => { const c = h('td', cls || null); const t = document.createTextNode(text); c.appendChild(t); tr.appendChild(c); return t; }; + td('n', String(trial.number)); + for (const p of a.parameters) cells.values.push(td('n mono', shown(trial.values[p.path]))); + const st = h('td'); const chip = h('span', 'state'); const chipText = document.createTextNode(''); chip.appendChild(chipText); st.appendChild(chip); tr.appendChild(st); + cells.chip = chip; cells.chipText = chipText; + cells.rung = td('small'); + for (const o of a.objectives) cells.objectives.push(td('n')); + cells.seconds = td('n small'); + const act = h('td', 'nowrap'); + const open = button('btn sm ghost', 'Open on the Map', ev => { ev.stopPropagation(); v.act.go('map', trial.reference); }, 'sweep-map-' + trial.number); open.disabled = !trial.defined; act.appendChild(open); tr.appendChild(act); + tr.tabIndex = 0; tr.classList.add('sw-row'); + tr.addEventListener('click', () => v.act.select(v.state.sel.sweeps === trial.reference ? null : trial.reference)); + tr.addEventListener('keydown', ev => { if (ev.key === 'Enter' && ev.target === tr) v.act.select(trial.reference); }); + v.parts.rows.set(trial.number, { tr, cells, open }); + setRow(v, trial); + return tr; + } + function setRow(v, trial) { + const { tr, cells, open } = v.parts.rows.get(trial.number), a = v.answer; + const tone = TRIAL_TONE[trial.state] || 'neutral', cls = 'state ' + (tone === 'pending' ? 'warn' : tone); + if (cells.chip.className !== cls) cells.chip.className = cls; + setText(cells.chipText, trial.state + (trial.reused ? ' (built before)' : '')); + const last = (trial.rungs || []).slice(-1)[0]; + setText(cells.rung, last ? 'rung ' + (last.rung + 1) + (last.goes_on ? '' : ', stopped there') : ''); + a.objectives.forEach((o, i) => setText(cells.objectives[i], shown(trial.objectives && trial.objectives[o.metric]))); + setText(cells.seconds, trial.seconds == null ? (trial.state === 'running' && trial.latest ? 'step ' + trial.latest.step : '') : minutes(trial.seconds)); + if (open.disabled !== !trial.defined) open.disabled = !trial.defined; + if (trial.problem && tr.title !== trial.problem) tr.title = trial.problem; + const on = v.state.sel.sweeps === trial.reference; if (tr.classList.contains('on') !== on) tr.classList.toggle('on', on); + } + + // ---- A reading: everything set in place --------------------------------------------------------------------------- + async function refresh(act) { + const v = live; + if (!v || !v.main.isConnected || v.busy) return; + v.busy = true; + try { + const answer = await sweepOf(v.reference); + if (live !== v) return; + v.at = Date.now(); v.answer = answer; + if (act) v.act = act; + setState(v); fillControls(v); + const option = v.main.querySelector('select[data-key="sweep"] option:checked'), word = option && option.textContent.replace(/ · [^·]*$/, ' · ' + (STATE_WORD[answer.state] || answer.state)); + if (option && option.textContent !== word) option.textContent = word; + for (const trial of answer.trials) { if (v.parts.rows.has(trial.number)) setRow(v, trial); else v.parts.tbody.appendChild(trialRow(v, trial)); } + if (v.parts.pc._key !== JSON.stringify(answer.axes)) drawAxes(v); + const done = answer.trials.filter(t => t.state === 'completed'); + if (v.parts.chart._key !== JSON.stringify([answer.objectives, done.map(t => [t.number, t.objectives]), answer.frontier])) drawChart(v); + if (window.LabParallel) window.LabParallel.apply(v.main, viewOf(answer), v.state); + } catch (error) { /* the strip says when the project could not be read; what is on screen stays */ } + finally { v.busy = false; } + } + // Every reading of the page (app.js calls S.tick after drawing): the sweep on screen, while it runs or is asked for. + const before = S.tick; + S.tick = async () => { + if (before) await before(); + const v = live; + if (v && v.main.isConnected && Date.now() - v.at >= REFRESH_MS && document.location.hash.startsWith('#sweeps') && (v.answer.state === 'running' || (v.answer.request && ['awaiting-approval', 'queued', 'running'].includes(v.answer.request.state)))) await refresh(); + }; + + // ---- New sweep ---------------------------------------------------------------------------------------------------- + const drafting = { recipe: null, name: '', text: '', touched: false }; + /** A sweep's text from a recipe's settings: its numeric ones as ranges about their values, random draws, eight trials. */ + function template(reference, doc, name) { + const settings = doc.run && doc.run.settings && typeof doc.run.settings === 'object' ? doc.run.settings : {}; + const parameters = []; + for (const [k, val] of Object.entries(settings)) { + if (parameters.length >= 4) break; + if (typeof val === 'number' && Number.isInteger(val) && val >= 1) parameters.push({ path: k, low: Math.max(1, Math.floor(val / 2)), high: val * 2, integer: true }); + else if (typeof val === 'number' && val > 0) parameters.push({ path: k, low: +(val / 10).toPrecision(6), high: +(val * 10).toPrecision(6), scale: 'log' }); + else if (typeof val === 'boolean') parameters.push({ path: k, values: [true, false] }); + } + return JSON.stringify({ format: 'tuldok_definition_v1', kind: 'sweep', title: 'A search over ' + (doc.title || reference), + recipe: reference, parameters: parameters.length ? parameters : [{ path: 'learning_rate', low: 0.0001, high: 0.01, scale: 'log' }], + strategy: { kind: 'random', seed: 1 }, objectives: [{ metric: 'loss', better: 'lower' }], budget: { trials: 8 } }, null, 2) + '\n'; + } + function newSweep(aside, act, data) { + if (aside._for === 'new' && !aside._again) return; + const recipes = data.map.models.filter(m => m.kind !== 'sweep-trial' && !m.draft); + if (!drafting.recipe || !recipes.some(m => m.id === drafting.recipe)) { drafting.recipe = recipes.length ? recipes[0].id : null; drafting.touched = false; } + aside._for = 'new'; + const ins = h('div', 'inspector sw-new'); + const hd = h('header'); hd.appendChild(h('span', 'kicker', 'new sweep · kept as an unsaved edit')); const t = h('h2', null, 'A sweep of a recipe\'s settings'); t.tabIndex = -1; hd.appendChild(t); ins.appendChild(hd); + ins.appendChild(h('p', 'note', 'Choose the recipe; the text is written from its settings. Change the parameters, the objectives (the series its script logs) and the budget, then Keep. A recipe whose settings are in a file is branched first: Branch from here gives the branch its own copy.')); + const f = h('div', 'form'); + const lab = h('label', null, 'Recipe'); const s = h('select'); s.dataset.key = 'sweep-new-recipe'; + for (const m of recipes) { const o = h('option', null, Tree.nameOf(m) + ' · ' + m.id); o.value = m.id; o.selected = m.id === drafting.recipe; s.appendChild(o); } + lab.appendChild(s); f.appendChild(lab); + const nl = h('label', null, 'Name'); const name = h('input'); name.dataset.key = 'sweep-new-name'; name.value = drafting.name; name.placeholder = 'lowercase letters, digits, . _ -'; nl.appendChild(name); f.appendChild(nl); + const tl = h('label', null, 'Text'); const area = h('textarea', 'mono sw-text'); area.dataset.key = 'sweep-new-text'; area.rows = 18; area.spellcheck = false; area.value = drafting.text; tl.appendChild(area); f.appendChild(tl); + ins.appendChild(f); + const fill = async () => { + if (!drafting.recipe) return; + const def = await P.read('definition', { reference: drafting.recipe }); + if (!drafting.name || !drafting.touchedName) { drafting.name = drafting.recipe.slice(8, 100) + '-sweep'; name.value = drafting.name; } + drafting.text = template(drafting.recipe, def.document || {}, drafting.name); area.value = drafting.text; drafting.touched = false; + }; + s.addEventListener('change', () => { drafting.recipe = s.value; fill(); }); + name.addEventListener('input', () => { drafting.name = name.value; drafting.touchedName = true; }); + area.addEventListener('input', () => { drafting.text = area.value; drafting.touched = true; }); + ins.appendChild(A.group('sweep:new', [{ id: 'keep', label: 'Keep', cls: 'btn primary', who: 'edit', op: 'set_definition', busy: 'Keeping…', + args: () => ({ reference: 'sweeps/' + drafting.name.trim(), text: drafting.text }), + done: r => { const ref = r.reference; drafting.text = ''; drafting.name = ''; drafting.touched = false; drafting.touchedName = false; act.setUI('sweep', ref); act.select(null); } }])); + if (!drafting.text) fill().catch(error => failure(ins, error)); + S.parts.putDrawer(aside, ins); + } + + S.sweeps = sweeps; +})(); diff --git a/tests/browser_project_workspace_sweeps.cjs b/tests/browser_project_workspace_sweeps.cjs new file mode 100644 index 00000000..3be734d1 --- /dev/null +++ b/tests/browser_project_workspace_sweeps.cjs @@ -0,0 +1,287 @@ +'use strict'; +// The Sweeps tab (docs/plans/training-and-curation/spec-t7.md sections 7 and 9, slice T7b), in a headless browser, the +// owner signed in, no GPU. Tuldok runs with --project-folder on a project the check writes into a Git repository of +// its own: one recipe, recipes/base, that runs the stand-in tests/project_sweep_stand_in.py (plain Python, logging +// through tuldok_log, which the recipe puts on PYTHONPATH; its loss falls to a floor its settings decide). +// 1. The tab with no sweep says so; New sweep writes a sweep's text from the recipe; the check sets a halving +// sweep of six trials with two objectives (loss, and time) and keeps it; the tab shows it, not run yet. +// 2. An agent credential asks for a build of the sweep; the page shows that it awaits approval, with Approve. +// The owner approves it on the tab: one approval for the whole budget. +// 3. While the trials run, the state block's counts, budget and running trial change across readings while the +// block is the same element and no node of it is added or removed; rows are added to the trials table. +// 4. When the sweep has finished: six trials, some pruned; the frontier chart shows the completed trials and +// parallel coordinates one line per trial; a range dragged on an axis hides the table's rows outside it. +// 5. A trial's Open on the Map selects it on the Map, in a section of the sweep, its drawer naming it. +// 6. Light and dark at 1440 and 390 wide: nothing overflowing sideways; no script error and no failed request. +// node tests/browser_project_workspace_sweeps.cjs [--shots <dir>] +const assert = require('node:assert/strict'), fs = require('node:fs'), os = require('node:os'), path = require('node:path'); +const { spawn, execFileSync } = require('node:child_process'), { once } = require('node:events'); +const { authenticatedFixture } = require('./auth_helpers.cjs'), { waitForDebugger } = require('./browser_startup.cjs'), { cdpSession } = require('./browser_cdp_session.cjs'), { qaDirectory } = require('./qa_artifacts.cjs'); + +const root = path.resolve(__dirname, '..'); +const argv = process.argv.slice(2), option = name => { const i = argv.indexOf(name); return i >= 0 ? argv[i + 1] : null; }; +assert.ok(process.env.TULDOK_DATABASE_URL, 'TULDOK_DATABASE_URL must name a disposable PostgreSQL cluster'); +const venv = path.join(root, '.venv', 'bin'); +if (fs.existsSync(path.join(venv, 'python'))) process.env.PATH = venv + path.delimiter + process.env.PATH; // auth_helpers runs python3 +const python = fs.existsSync(path.join(venv, 'python')) ? path.join(venv, 'python') : 'python3'; +const TRIALS = 6; + +const temporary = fs.mkdtempSync(path.join(os.tmpdir(), 'tuldok-sweeps-browser-')); +const report = qaDirectory(root, 'project-workspace-sweeps'); +const shots = option('--shots') ? path.resolve(option('--shots')) : null; if (shots) fs.mkdirSync(shots, { recursive: true }); +const children = [], checks = [], errors = [], failures = []; +let server, serverErrors = '', origin, auth, socket, session, send, evaluate, owned = null; +const pause = ms => new Promise(resolve => setTimeout(resolve, ms)); +async function until(fn, label, tries = 300) { for (let i = 0; i < tries; i++) { const value = await fn(); if (value) return value; await pause(100); } throw Error('Timed out: ' + label); } +function check(text) { checks.push(text); console.log('PASS ' + text); } +function launch(command, args, options) { const child = spawn(command, args, options); children.push(child); return child; } +async function stop(child) { if (!child || child.exitCode !== null || child.signalCode !== null) return; const exited = once(child, 'exit'); child.kill('SIGTERM'); await Promise.race([exited, pause(10000)]); if (child.exitCode === null && child.signalCode === null) { child.kill('SIGKILL'); await exited; } } +function findBrowser() { + const candidates = [process.env.BROWSER, '/usr/bin/chromium', '/usr/bin/chromium-browser', '/usr/bin/google-chrome']; + const cache = path.join(os.homedir(), '.cache', 'ms-playwright'); + if (fs.existsSync(cache)) for (const name of fs.readdirSync(cache).filter(n => n.startsWith('chromium_headless_shell-')).sort().reverse()) candidates.push(path.join(cache, name, 'chrome-headless-shell-linux64', 'chrome-headless-shell')); + const found = candidates.find(candidate => candidate && fs.existsSync(candidate)); + assert.ok(found, 'No headless browser: set BROWSER'); + return found; +} +/** Drops the project's schema and the catalog's from the disposable database, so each run imports afresh. */ +function dropOwned(folder, catalog) { + const id = JSON.parse(fs.readFileSync(path.join(folder, 'tuldok.json'), 'utf8')).id; + execFileSync(python, ['-c', `import json, os, pathlib, sys, psycopg +from psycopg import sql +from tuldok_project import store +store.drop_project(sys.argv[1], os.environ['TULDOK_DATABASE_URL']) +root = pathlib.Path(sys.argv[2]) +if root.exists(): + with psycopg.connect(os.environ['TULDOK_DATABASE_URL'], autocommit=True) as c: + for p in root.rglob('.tuldok.json'): + v = json.loads(p.read_text()) + name = 'projection_' + v['projection_id'] if v.get('version') == 2 else 'catalog_' + v['dataset_id'] + c.execute(sql.SQL('DROP SCHEMA IF EXISTS {} CASCADE').format(sql.Identifier(name))) +`, id, catalog], { cwd: root, stdio: ['ignore', 'pipe', 'pipe'] }); +} +async function contract(name) { + const capabilities = await (await auth.fetch(origin + '/api/agent/capabilities')).json(); + const operation = capabilities.operations.find(item => item.id === 'project.' + name), c = operation.contracts[operation.contracts.length - 1]; + return 'project.' + name + '/' + c.version + '/' + c.sha256; +} +/** An operation as the owner (the fixture's session); bearer: as that agent credential instead. */ +async function api(name, body = {}, bearer = null) { + const headers = { 'Content-Type': 'application/json', 'Tuldok-Operation-Contract': await contract(name) }; + const response = bearer ? await globalThis.fetch(origin + '/api/project/' + name, { method: 'POST', headers: { ...headers, Authorization: 'Bearer ' + bearer }, body: JSON.stringify(body) }) + : await auth.fetch(origin + '/api/project/' + name, { method: 'POST', headers, body: JSON.stringify(body) }); + const value = await response.json(); assert.equal(response.status, 200, name + ': ' + JSON.stringify(value)); return value; +} +async function credential(label, scopes) { + const response = await auth.fetch(origin + '/api/access/credentials', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ label, scopes, ttl_seconds: 3600 }) }); + const value = await response.json(); assert.equal(response.status, 201, JSON.stringify(value)); return value.token; +} + +// ---- The page's requests, from the browser's network --------------------------------------------------------------------- +const calls = new Map(), finished = []; +function network(event) { + const p = event.params; + if (event.method === 'Network.requestWillBeSent' && /\/api\/project\/[a-z_]+$/.test(p.request.url)) calls.set(p.requestId, { name: p.request.url.split('/').pop(), sent: Date.now() }); + if ((event.method === 'Network.loadingFinished' || event.method === 'Network.loadingFailed') && calls.has(p.requestId)) { finished.push(Object.assign(calls.get(p.requestId), { done: Date.now() })); calls.delete(p.requestId); } +} +const asked = (name, since = 0) => finished.concat([...calls.values()]).filter(f => f.name === name && f.sent >= since); +async function settled(label) { + await until(() => evaluate(`(() => { const a = document.getElementById('aside'), m = document.getElementById('main'); return ![...a.querySelectorAll('.note'), ...m.querySelectorAll('.note')].some(n => n.textContent === 'Reading…') && !a.querySelector('[aria-busy]') && !m.hasAttribute('aria-busy'); })()`).then(ok => ok && !calls.size), 'settled: ' + label); + await pause(250); +} +async function frames() { await evaluate('new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve)))'); } +async function shot(name) { + await frames(); + const png = Buffer.from((await send('Page.captureScreenshot', { format: 'png', captureBeyondViewport: false })).data, 'base64'); + fs.writeFileSync(path.join(report, name + '.png'), png); if (shots) fs.writeFileSync(path.join(shots, name + '.png'), png); +} +const byKey = key => `[data-key=${JSON.stringify(key)}]`; +async function click(selector) { await evaluate(`(() => { const b = document.querySelector(${JSON.stringify(selector)}); if (!b) throw Error('no ' + ${JSON.stringify(selector)}); b.click(); return true; })()`); } +async function type(selector, value) { await evaluate(`(() => { const t = document.querySelector(${JSON.stringify(selector)}); t.focus(); t.value = ${JSON.stringify(value)}; t.dispatchEvent(new Event('input', { bubbles: true })); return true; })()`); } +const stateOf = () => evaluate(`(() => { const s = document.querySelector('#main .sw-state'); if (!s) return null; const dd = [...s.querySelectorAll('dd')].map(d => d.textContent); return { chip: s.querySelector('.sw-chip').textContent, run: dd[0], counts: dd[1], trials: dd[2], time: dd[3], running: dd[4], best: dd[5], bar: s.querySelector('.sw-meter .hair i').style.width }; })()`); +const rows = () => evaluate(`[...document.querySelectorAll('#main .sw-table tbody tr')].map(tr => ({ n: Number(tr.dataset.trial), ref: tr.dataset.subject, state: tr.children[3].textContent, hidden: tr.hidden }))`); +const buttonText = text => `[...document.querySelectorAll('#main .sw-controls button')].find(b => b.textContent === ${JSON.stringify(text)})`; + +(async () => { + // ---- The project ---------------------------------------------------------------------------------------------------------- + const repo = path.join(temporary, 'repo'), folder = path.join(repo, 'project'), code = path.join(repo, 'code'); + for (const d of ['recipes', 'environments']) fs.mkdirSync(path.join(folder, d), { recursive: true }); + fs.mkdirSync(code, { recursive: true }); + fs.copyFileSync(path.join(root, 'tests', 'project_sweep_stand_in.py'), path.join(code, 'stand_in.py')); + const write = (rel, value) => fs.writeFileSync(path.join(folder, rel), JSON.stringify(value, null, 2) + '\n'); + const id = require('node:crypto').randomUUID().replace(/-/g, ''); + write('tuldok.json', { format: 'tuldok_project_v1', id, name: 'Sweep check', code_root: '../code', groups: [{ id: 'small', title: 'Small models' }] }); + const version = execFileSync(python, ['-c', 'import sys; print(f"{sys.version_info[0]}.{sys.version_info[1]}")']).toString().trim(); + const jsonschema = execFileSync(python, ['-c', 'import importlib.metadata as m; print(m.version("jsonschema"))']).toString().trim(); + write('environments/here.json', { format: 'tuldok_definition_v1', kind: 'environment', title: 'This interpreter', python: version, device: 'cpu', packages: { jsonschema } }); + write('recipes/base.json', { format: 'tuldok_definition_v1', kind: 'recipe', title: 'The stand-in model', group: 'small', change: 'training-policy', labels: { short: 'BASE' }, + run: { command: ['python', 'stand_in.py', '--settings', '{settings}', '--out', '{output}'], environment: 'environments/here', settings: { learning_rate: 0.01, width: 8, steps: 40, sleep: 0.05 }, + env: { PYTHONPATH: root }, outputs: { weights: { path: 'weights.json', role: 'weights' } }, sources: ['stand_in.py'] } }); + const git = ['-c', 'user.name=Tuldok Test', '-c', 'user.email=test@example.invalid', '-c', 'commit.gpgsign=false', '-c', 'init.defaultBranch=main', '-C', repo]; + execFileSync('git', [...git, 'init', '-q']); execFileSync('git', [...git, 'add', '-A']); execFileSync('git', [...git, 'commit', '-q', '-m', 'The project.']); + const home = path.join(temporary, 'home'), catalog = path.join(temporary, 'catalog'); fs.mkdirSync(home); + const env = { ...process.env, TULDOK_PROJECT_HOME: home, TULDOK_SETTINGS: path.join(temporary, 'settings.json') }; + owned = [folder, catalog]; dropOwned(folder, catalog); + execFileSync(python, ['-m', 'tuldok_project', 'connect', folder, 'here', python], { cwd: root, env, stdio: ['ignore', 'pipe', 'pipe'] }); + let output = ''; + server = launch(python, ['-u', 'app.py', '--port', '0', '--data', catalog, '--project-folder', folder], { cwd: root, env, stdio: ['ignore', 'pipe', 'pipe'] }); + server.stdout.on('data', chunk => { output += chunk; }); server.stderr.on('data', chunk => { serverErrors += chunk; }); + const port = await until(() => { if (server.exitCode !== null) throw Error('Tuldok exited: ' + serverErrors); return output.match(/127\.0\.0\.1:(\d+)/)?.[1]; }, 'Tuldok start-up', 3000); + origin = 'http://127.0.0.1:' + port; + auth = authenticatedFixture(); await auth.register(origin, catalog, root); + + const browser = launch(findBrowser(), ['--headless', '--no-sandbox', '--disable-gpu', '--no-first-run', '--hide-scrollbars', '--remote-debugging-port=0', '--window-size=1440,900', '--user-data-dir=' + path.join(temporary, 'browser'), 'about:blank'], { stdio: 'ignore', env: { ...process.env, XDG_CONFIG_HOME: temporary, XDG_CACHE_HOME: temporary } }); + const debugPort = await waitForDebugger(browser, path.join(temporary, 'browser', 'DevToolsActivePort')); + const target = (await (await fetch('http://127.0.0.1:' + debugPort + '/json')).json()).find(item => item.type === 'page'); + socket = new WebSocket(target.webSocketDebuggerUrl); await once(socket, 'open'); + session = cdpSession(socket, { timeoutMs: 60000, onEvent: event => { + network(event); + if (event.method === 'Runtime.exceptionThrown') errors.push(event.params.exceptionDetails.exception?.description || event.params.exceptionDetails.text); + if (event.method === 'Runtime.consoleAPICalled' && event.params.type === 'error') errors.push(event.params.args.map(a => a.value ?? a.description).join(' ')); + if (event.method === 'Log.entryAdded' && event.params.entry.level === 'error') errors.push(event.params.entry.text + ' ' + (event.params.entry.url || '')); + if (event.method === 'Network.loadingFailed' && !event.params.canceled) failures.push({ id: event.params.requestId, error: event.params.errorText }); + if (event.method === 'Network.responseReceived' && event.params.response.status >= 400) failures.push({ url: event.params.response.url, status: event.params.response.status }); + } }); + send = session.send; + evaluate = async expression => { const result = await send('Runtime.evaluate', { expression, awaitPromise: true, returnByValue: true }); if (result.exceptionDetails) throw Error(JSON.stringify(result.exceptionDetails)); return result.result.value; }; + await send('Page.enable'); await send('Runtime.enable'); await send('Network.enable'); await send('Log.enable'); + const size = async (width, height) => send('Emulation.setDeviceMetricsOverride', { width, height, deviceScaleFactor: 1, mobile: width < 600 }); + const theme = async name => { await send('Emulation.setEmulatedMedia', { features: [{ name: 'prefers-color-scheme', value: name }, { name: 'prefers-reduced-motion', value: 'reduce' }] }); }; + await auth.browser(send, origin); + const load = async (name, hash, query) => { + await theme(name); + await send('Page.navigate', { url: 'about:blank' }); await pause(100); + await send('Page.navigate', { url: origin + '/?theme=' + name + (query ? '&' + query : '') + hash }); + await until(() => evaluate(`document.readyState === 'complete' && !!document.getElementById('needs-btn') && !document.getElementById('needs-btn').disabled`), 'the project read', 1200); + await settled('opened ' + hash); + }; + + // ---- 1. New sweep ------------------------------------------------------------------------------------------------------------ + await size(1440, 900); await load('light', '#sweeps'); + assert.match(await evaluate(`document.querySelector('#main .empty').textContent`), /no sweep yet/); + await click(byKey('sweep-new')); await settled('new sweep'); + const written = await until(() => evaluate(`(() => { const t = document.querySelector(${JSON.stringify(byKey('sweep-new-text'))}); return t && t.value ? t.value : null; })()`), 'the text written from the recipe'); + const drafted = JSON.parse(written); + assert.equal(drafted.recipe, 'recipes/base'); assert.deepEqual(drafted.parameters.map(p => p.path).sort(), ['learning_rate', 'sleep', 'steps', 'width']); // the stored document's order + await shot('light-1440-1-new'); + const text = JSON.stringify({ format: 'tuldok_definition_v1', kind: 'sweep', title: 'Learning rate and width', recipe: 'recipes/base', + parameters: [{ path: 'learning_rate', low: 0.001, high: 0.1, scale: 'log' }, { path: 'width', values: [4, 8, 16, 32] }], + strategy: { kind: 'halving', seed: 3, metric: 'loss', better: 'lower', min: 2, factor: 2 }, + objectives: [{ metric: 'loss', better: 'lower' }, { metric: 'time', better: 'lower', title: 'Seconds' }], budget: { trials: TRIALS } }, null, 2) + '\n'; + await type(byKey('sweep-new-name'), 'lr-width'); await type(byKey('sweep-new-text'), text); + await click('[data-group="sweep:new"] button'); await settled('kept'); + await until(() => evaluate(`!!document.querySelector('#main .sw-state') && !document.getElementById('drawer').classList.contains('open')`), 'the sweep shown'); + assert.equal(await evaluate(`document.querySelector(${JSON.stringify(byKey('sweep'))}).value`), 'sweeps/lr-width'); + const s1 = await stateOf(); + assert.match(s1.chip, /not run yet/); assert.equal(s1.trials, '0 of ' + TRIALS); + assert.equal(new URLSearchParams(await evaluate('location.search')).get('sweep'), 'sweeps/lr-width', 'the address keeps the sweep'); + check('1. New sweep wrote a sweep of recipes/base from its settings (' + drafted.parameters.map(p => p.path).join(', ') + '); a halving sweep of ' + TRIALS + ' trials kept as sweeps/lr-width, shown not run yet'); + + // ---- 2. Asked for by an agent, approved on the tab --------------------------------------------------------------------------- + const agent = await credential('A sweep check agent', ['inspect', 'execute']); + const ask = await api('request_build', { targets: ['sweeps/lr-width'] }, agent); + assert.equal(ask.state, 'awaiting-approval'); + await evaluate(`window.dispatchEvent(new Event('focus')); true`); + await until(() => evaluate(`!!(${buttonText('Approve')})`), 'Approve on the tab'); + assert.match(await evaluate(`document.querySelector('#main .sw-ask').textContent`), /One approval covers its whole budget/); + const s2 = await stateOf(); assert.match(s2.chip, /awaiting approval/); + await shot('light-1440-2-awaiting'); + // The block is marked before the approval: a reading must never replace it or add or remove a node of it. + await evaluate(`window.__sw = (() => { const s = document.querySelector('#main .sw-state'); s.__mark = 'state'; const counts = { added: 0, removed: 0 }; new MutationObserver(list => { for (const r of list) { counts.added += r.addedNodes.length; counts.removed += r.removedNodes.length; } }).observe(s, { childList: true, subtree: true }); return { counts, still: () => { const now = document.querySelector('#main .sw-state'); return !!now && now.__mark === 'state'; } }; })(); true`); + await evaluate(`${buttonText('Approve')}.click(); true`); + const running = await until(async () => { const s = await stateOf(); return s && /running/.test(s.chip) ? s : null; }, 'the sweep running', 300); + check('2. An agent asked for the sweep; the tab showed it awaiting approval with Approve and the sentence that one approval covers the budget; the owner approved it there and it runs'); + + // ---- 3. Live, in place --------------------------------------------------------------------------------------------------------- + const seen = [running]; + for (let i = 0; i < 3; i++) { + const before = seen[seen.length - 1]; + const next = await until(async () => { const s = await stateOf(); return s && (s.counts !== before.counts || s.running !== before.running) ? s : null; }, 'the state changes (' + i + ')', 300); + seen.push(next); + assert.ok(await evaluate('window.__sw.still()'), 'the state block is the same element after a reading'); + } + const counts3 = await evaluate('window.__sw.counts'); + assert.deepEqual([counts3.added, counts3.removed], [0, 0], 'no node of the state block added or removed: ' + JSON.stringify(counts3)); + const rowsLive = (await rows()).length; + await shot('light-1440-3-live'); + check('3. While it ran the state changed in place across readings (' + seen.map(s => s.counts.replace(/ · /g, '/')).join(' → ') + '; running: ' + seen.map(s => s.running).slice(-2).join(' → ') + '), the block the same element, no node of it added or removed; ' + rowsLive + ' rows in the table so far'); + + // ---- 4. Finished: the frontier, parallel coordinates, the table ---------------------------------------------------------------- + const done = await until(async () => { const r = (await api('build_request', { request: ask.id })); return ['succeeded', 'failed', 'cancelled'].includes(r.state) ? r : null; }, 'the sweep ends', 1200); + assert.equal(done.state, 'succeeded', done.problem); + const answer = await api('sweep', { sweep: 'lr-width' }); + await until(async () => { const s = await stateOf(); return /finished/.test(s.chip) && (await rows()).length === TRIALS; }, 'the tab shows it finished', 300); + assert.ok(await evaluate('window.__sw.still()'), 'the state block is still the same element'); + const states = answer.trials.map(t => t.state), completed = states.filter(s => s === 'completed').length; + assert.equal(states.length, TRIALS); assert.ok(states.includes('pruned'), 'halving pruned some trials: ' + states); + const table = await rows(); + assert.deepEqual(table.map(r => r.n), answer.trials.map(t => t.number)); + assert.deepEqual(table.map(r => r.state.split(' ')[0]), states); + const points = await evaluate(`document.querySelectorAll('#main .sw-chart circle.pt').length`); + assert.equal(points, completed, 'the frontier chart draws each completed trial'); + const frontierLine = await evaluate(`!!document.querySelector('#main .sw-chart path.frontier') || ${answer.frontier.length} < 2`); + assert.ok(frontierLine, 'the frontier is drawn'); + const lines = await evaluate(`document.querySelectorAll('#main .sw-pc path.pcl').length`); + assert.equal(lines, TRIALS, 'one line a trial in parallel coordinates'); + const axes = await evaluate(`[...document.querySelectorAll('#main .sw-pc .pc-axis')].map(g => g.dataset.axis)`); + assert.deepEqual(axes, ['m:loss', 'm:time', 's:learning_rate', 's:width']); + // A range dragged on the loss axis keeps the best trials; the table hides the rest. + await evaluate(`document.querySelector('#main .sw-pc').scrollIntoView({ block: 'center' }); true`); await frames(); + const box2 = await evaluate(`(() => { const r = document.querySelector('#main .sw-pc .pc-hit[data-axis="m:loss"]').getBoundingClientRect(); return { x: r.x + r.width / 2, top: r.y + 8, bottom: r.y + r.height - 8 }; })()`); + const lowY = box2.bottom, highY = box2.bottom - (box2.bottom - box2.top) * 0.5; + await send('Input.dispatchMouseEvent', { type: 'mousePressed', x: box2.x, y: lowY, button: 'left', clickCount: 1 }); + await send('Input.dispatchMouseEvent', { type: 'mouseMoved', x: box2.x, y: highY, button: 'left' }); + await send('Input.dispatchMouseEvent', { type: 'mouseReleased', x: box2.x, y: highY, button: 'left', clickCount: 1 }); + await frames(); + const filtered = await rows(); + const hiddenRows = filtered.filter(r => r.hidden).length; + assert.ok(hiddenRows > 0 && hiddenRows < TRIALS, 'a range on the loss axis hides some rows: ' + JSON.stringify(filtered)); + await shot('light-1440-4-finished'); + await click(byKey('pc-clear')); await frames(); + assert.equal((await rows()).filter(r => r.hidden).length, 0, 'Clear ranges shows every row'); + check('4. Finished: ' + states.join(', ') + '; the frontier chart drew the ' + completed + ' completed trials (' + answer.frontier.length + ' on the frontier), parallel coordinates ' + lines + ' lines through ' + axes.join(', ') + '; a range on the loss axis hid ' + hiddenRows + ' rows, Clear ranges showed them'); + + // ---- 5. A trial on the Map -------------------------------------------------------------------------------------------------------- + const trial = answer.trials[0]; + await click(byKey('sweep-map-' + trial.number)); await settled('the map'); + assert.equal(await evaluate('location.hash'), '#map/' + encodeURIComponent(trial.reference)); + await until(() => evaluate(`(() => { const h = document.querySelector('#aside h2'); return h && h.textContent === ${JSON.stringify('Learning rate and width · trial ' + trial.number)}; })()`), 'the trial\'s drawer on the Map'); + const section = await evaluate(`[...document.querySelectorAll('#main h3, #main text.bandlabel')].map(e => e.title || (e.querySelector('title') || {}).textContent || e.textContent).find(t => /Learning rate and width/.test(t)) || null`); + assert.equal(section, 'Small models / Learning rate and width', 'the map has a section of the sweep under its recipe\'s group'); + const chip = await evaluate(`document.querySelector('#aside .ins-meta .chip').textContent`); + assert.equal(chip, 'Sweep trial'); + await shot('light-1440-5-map'); + check('5. Open on the Map selected ' + trial.reference + ' on the Map: its drawer names it, its kind of change "Sweep trial", in the section "' + section + '"'); + + // ---- 6. Light and dark, 1440 and 390 wide --------------------------------------------------------------------------------------- + const seen6 = []; + for (const [w, hgt] of [[1440, 900], [390, 844]]) for (const name of ['light', 'dark']) { + const tag = name + '-' + w; + await size(w, hgt); await load(name, '#sweeps', 'sweep=sweeps/lr-width'); + await until(() => evaluate(`document.querySelectorAll('#main .sw-pc path.pcl').length === ${TRIALS}`), tag + ': drawn'); + const r = await evaluate(`(() => { const m = document.getElementById('main'); const wide = [...m.querySelectorAll('*')].filter(e => { const b = e.getBoundingClientRect(); return b.width > 0 && b.right > m.getBoundingClientRect().right + 1 && !e.closest('.tv-wrap'); }).map(e => e.tagName + '.' + (typeof e.className === 'string' ? e.className : '')).slice(0, 4); return { page: document.documentElement.scrollWidth - innerWidth, main: m.scrollWidth - m.clientWidth, wide }; })()`); + assert.ok(r.page <= 0 && r.main <= 1 && !r.wide.length, tag + ': nothing overflows sideways ' + JSON.stringify(r)); + await shot(tag + '-6-sweeps'); + seen6.push(tag); + } + await size(1440, 900); + check('6. The tab drawn with nothing overflowing sideways outside the table\'s own scrolling box: ' + seen6.join(', ') + (shots ? '; screenshots in ' + shots : '')); + + assert.deepEqual(errors, [], 'Script errors'); + assert.deepEqual(failures, [], 'Failed requests'); + check('No script error, no failed request'); + fs.writeFileSync(path.join(report, 'receipt.json'), JSON.stringify({ status: 'pass', folder, checks }, null, 2) + '\n'); + console.log('Receipt in ' + report); +})().catch(async error => { + process.exitCode = 1; + console.error(error); if (serverErrors) console.error('Server:', serverErrors.slice(-4000)); + console.error('Script errors:', JSON.stringify(errors)); console.error('Failed requests:', JSON.stringify(failures)); + try { if (evaluate) { await shot('failure'); console.error('Main:', (await evaluate('document.getElementById("main").innerText')).slice(0, 2500)); } } catch (_) { /* the page is gone */ } + fs.writeFileSync(path.join(report, 'failure.json'), JSON.stringify({ status: 'failed', error: String(error && error.stack || error), checks, errors, failures }, null, 2) + '\n'); +}).finally(async () => { + try { session?.close(); } catch (_) { /* closed */ } + for (const child of children.reverse()) await stop(child); + if (owned) try { dropOwned(...owned); } catch (error) { console.error('Dropping the disposable schemas failed:', error.message); process.exitCode = 1; } + try { execFileSync('chmod', ['-R', 'u+w', temporary]); } catch (_) { /* nothing was made read-only */ } + fs.rmSync(temporary, { recursive: true, force: true }); +}); From e8f72516279cd52ce4ff48f1d3bb34ca69eca624 Mon Sep 17 00:00:00 2001 From: MrScripty <TheEnvironmentGuy@protonmail.com> Date: Thu, 19 Nov 2026 08:37:11 -0700 Subject: [PATCH 127/131] docs(plan): spec-t7 as built Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --- docs/plans/training-and-curation/spec-t7.md | 35 +++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/docs/plans/training-and-curation/spec-t7.md b/docs/plans/training-and-curation/spec-t7.md index 9cb90202..baafa240 100644 --- a/docs/plans/training-and-curation/spec-t7.md +++ b/docs/plans/training-and-curation/spec-t7.md @@ -103,3 +103,38 @@ Trials carry the kind of change **Sweep trial** on the Map (a chip and a colour ## 10. Out of scope Running trials at once or on other machines; resuming a pruned trial (no checkpoint contract); Bayesian or other model-based strategies; benchmark objectives (section 1); a control keeping only a sweep's winners; any GPU run (the strategy is the same, the owner's word is needed first); the lab's models. + +## As built + +What differs from the text above, and what was found. Built on `feat/t7-sweeps` beside phase 6 (`tuldok-t6`, serving), which owns the Train tab's and the model drawer's new actions and a recipe's `serve`; neither is touched here. Edits to shared files are small and local: `app.js` (one tab, one addressed key), `operations.py` (two rows, the kind, a result tuple), `service.py` (two reads and three lines of dispatch in the worker), `check.py` (two lines at the end of `check_map`), `plan.py` (three lines in `build_plan`), `build_requests.py` (one line of `covers`), `store.py` (the tables, imported inside `_create_schema`), the recipe schema (`sweep-trial` and `sweep`), `docs/contracts/project-folder.md` (the layout, the recipe's two fields, a `### sweep` section, a `### Sweeps` section under the operations), the service test's operation count (83 to 85). `tabs.js` and `base.css` are not changed: the tab is a new `sweeps.js` that wraps `S.tick`, and its styles and the new kind's colour are a new `sweeps.css`. `builds.py` is not changed: the runner uses `builds._Build` (`run_one`, the snapshot, the environment check) as `builds.execute` does. + +### T7a, the core + +- **`tuldok_project/sweeps.py`** holds all of it: the checks (`check_sweeps`, called at the end of `check.check_map`, so `set_definition` reports them too), the schedule, the halving rule (`Rungs`, `goes_on`), the trial's text and name, the plan of a sweep (`plan.build_plan` hands a sweep target to `sweeps.plan`), the runner (`sweeps.execute`, which the worker calls instead of `builds.execute` when the plan names a sweep), the two tables and the two reads, and the map's groups (`map_groups`, called by `workspace.project_map`). +- **The map's shape is only extended where there are sweeps.** Section 6 first said every model and group gained `sweep`; as built, only a sweep's group (`sweep: true`) and a trial's model (`sweep`: the reference) carry it, so the answers of projects without sweeps are byte for byte what they were (the workspace tests compare whole answers). +- **A pruned decision taken after the trial ended** (the last lines are read once more when its run ends) is recorded in its rungs (`goes_on` false), and its values count for the later trials, but the trial is recorded **completed** because its run succeeded. With the watcher reading every quarter second this happens only to a trial whose last rung falls in its last quarter second. +- **The sweep's and the recipe's texts are checked against the approval once, before anything runs** (refused `stale`); a trial's text is added to what the build expects before it runs, so `_check_expected` checks it as any step's. +- **jsonb orders an object's keys** (shorter keys first), so a document read back from the database (`definition`'s `document`) lists the parameters in another order than the text; the schedule reads the document, whose list order is kept, so it is not affected. +- **Tests:** `tests/test_tuldok_project_sweeps.py`, 24 (19 without a database, 5 with): the schedule (a grid against the test's own product, log points and integer rounding; random draws against the test's own `random.Random`; exhaustion; `1` and `1.0` one draw), halving (the rung points, a line crossing two rungs, `goes_on` with ties and both directions, decisions on metrics logs the test writes, lines appended between two reads, the minutes stopping a trial through its cancel file), the trial's text and its names, the paths, the checker (the schema's pointers, each rule beyond it, the grid's count, warning and bound, a recipe whose settings are in a file, a trial's `sweep` edge and a missing sweep), the plan and its covers, and three runs end to end: **halving through a started `Service`**, an agent's request approved once by the owner, six trials of the stand-in one after another with one plan id, the test's own arithmetic of the stand-in's floors and the halving rule giving each trial's state (completed or pruned), the pruned runs `cancelled` with the problem, the best, the frontier, the axes, the trials unsaved, derived from the recipe and in the sweep's group on the map, saved into the folder, and asking again refused `nothing-to-build`; **the minutes budget** stopping a sweep mid-trial (`ended` minutes, the last trial stopped); **a grid run twice**, its built trials reused and a third trial taking `-003-2` because `-003` held another recipe; and a stale recipe refused. The stand-in is `tests/project_sweep_stand_in.py`. + +### T7b, the page + +- **The tab** is `#sweeps`, after Train; `?sweep=` keeps the chosen sweep. Its drawer holds New sweep (`#sweeps/new`), the plan view (`#sweeps/plan:sweeps/<name>`, `actions.js`'s, whose Request build goes to the request on Train as everywhere) or a trial (the model's drawer). +- **In place:** the tab is painted once per sweep and per person's choice; a reading that changed something (`aside._again`) and every reading while the sweep runs or is asked for (a wrapper of `S.tick`) ask `sweep` and set the state block's texts and bar widths, the trial rows' cells (appending a row for a new trial), the chooser's word, the controls (rebuilt in their own box only when what they offer changed), and draw the charts and parallel coordinates again in their hosts only when their data changed. The check counts no node added to or removed from the state block across a whole run. +- **`parallel.js`** gained three optional fields of its `view`: `selected`, `lead` (the sentence under the heading) and `noun` ("trials"); the Benchmarks tab passes none and is unchanged. The trials table has the Benchmarks table's class and rows keyed by subject, so `LabParallel.apply` filters it unchanged. +- **The chart** is `charts.js`'s scatter with two objectives (completed trials only, the frontier from the answer) and its progression with one. +- **New sweep** writes a sweep from the chosen recipe's numeric and boolean settings (at most four: an integer as a range from half to twice it, a positive number as a log range from a tenth to ten times it), random, `loss` as the objective and eight trials, for the person to change and keep. It reads the recipe's document from the database, so its parameters come in jsonb's key order. +- **The kind of change "Sweep trial"** is a fifth entry of `adapter.js`'s kinds; its colour `--k-sweep-trial` is the purple of the training runs (`--run-3`, already checked beside the other kinds' colours), defined with every rule that colours a kind in `sweeps.css`. The editor's list of every definition lists Sweeps after Recipes. +- **The check** (`tests/browser_project_workspace_sweeps.cjs`, 7 PASS on its last two runs; the first runs failed on the check's own expectations of key order and of the map's section title, and once on the page: a reading 0.4 s after the tab was drawn was skipped by a guard against asking twice, so a request made meanwhile was not shown; the guard now applies only to `S.tick`): New sweep from the recipe, the halving sweep of six trials kept; an agent's request shown awaiting approval and approved on the tab; the state changing in place across four readings with the block the same element and no node of it added or removed; finished with three completed and three pruned, the frontier chart of the three, parallel coordinates of six lines through loss, time, learning rate and width, a range on the loss axis hiding rows; Open on the Map selecting trial 1 in the section "Small models / Learning rate and width" with the kind Sweep trial; light and dark at 1440 and 390 with nothing overflowing sideways (the trials table scrolls in its own box). + +### Runs at the end + +Disposable PostgreSQL under `/tmp/claude-1000/t7`, `TULDOK_PROJECT_HOME` and `TULDOK_SETTINGS` there, no GPU: + +- `PYTHONPATH=tests .venv/bin/python -m unittest discover -s tests -p 'test_tuldok_project_*.py'`: 878 OK (854 before, plus the 24 of `test_tuldok_project_sweeps`; `test_tuldok_project_check`'s every-kind assertion leaves out `sweep`, and the service test reads `sweeps` and `sweep`). +- `PYTHONPATH=tests .venv/bin/python -m unittest test_agent_api test_agent_negotiation test_agent_http`: 43 OK, 4 skipped. The catalog's digest is unchanged (`ad5cc7ac…`, 110 operations), checked in the new test file too. +- Browser: `browser_project_workspace_sweeps.cjs` 7 PASS; unchanged `browser_project_workspace.cjs` 24 PASS, `_actions.cjs` 27 PASS, `_training.cjs` 7 PASS, `_compare.cjs` 6 PASS. + +### Not verified + +A sweep of a real model or on the GPU (nothing was trained; the stand-in sleeps); halving in `time` units end to end (unit-tested only); a grid larger than its budget in a run (checked as a warning only); a sweep cancelled from the page while a trial runs (cancelling a running request is the existing path, and the runner's stop is unit-reached only through the minutes; not run end to end); Tuldok stopped mid-sweep (the orphan rule is written, not exercised); two sweeps asked for at once (the worker runs requests one at a time, so they queue; not run); the agent's decline of a sweep on the tab; a trial that does not check (recorded failed; not run); a sweep whose recipe needs a dataset built first (the prerequisite path is the plan's, run with the environment step only); many trials (the table and the reads have no bound beyond the budget's 1,000); keyboard use of the trial rows beyond Enter; the coding-standards guidance (routed; core, router, implementation and verification were read, the other twelve modules it listed were not). From 17a614846a25f48ce48bf59d9fa1ba249bfb4e31 Mon Sep 17 00:00:00 2001 From: MrScripty <TheEnvironmentGuy@protonmail.com> Date: Thu, 19 Nov 2026 09:02:09 -0700 Subject: [PATCH 128/131] fix(project): served reads every recipe's document once On the lab's 206 recipes it asked definition() per recipe, which works out the whole project's states each time: 13 s. Now 0.09 s. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --- tuldok_project/service.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/tuldok_project/service.py b/tuldok_project/service.py index 732646f4..bff61523 100644 --- a/tuldok_project/service.py +++ b/tuldok_project/service.py @@ -1245,10 +1245,13 @@ def _served(self, arguments, actor): servable = [] with self._lock: with self._open() as project: + # Every document read at once: definition() works out the whole project's states each time it is + # asked, which on a project of 200 recipes took 13 s for a list that needs only `serve`. + documents_by_reference = project._documents(removed=False) for row in project.definitions('recipe'): if row['removed']: continue - document = project.definition(row['reference'])['document'] or {} + document = documents_by_reference.get(row['reference']) or {} serve = document.get('serve') if not isinstance(serve, dict): continue From 141a3eef6f901aaaf6af2d295f396211fe1e2e1a Mon Sep 17 00:00:00 2001 From: MrScripty <TheEnvironmentGuy@protonmail.com> Date: Thu, 19 Nov 2026 09:05:00 -0700 Subject: [PATCH 129/131] feat(workspace): Open wide shows a model's structure over the page at full width In the 420 px drawer only two or three operations fit across. Open wide draws the same block, with the same state, over the page; Escape or Back to the drawer closes it. The structure check opens and closes it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --- static/project-workspace/base.css | 3 +++ static/project-workspace/structure.js | 22 ++++++++++++++++++- tests/browser_project_workspace_structure.cjs | 8 +++++++ 3 files changed, 32 insertions(+), 1 deletion(-) diff --git a/static/project-workspace/base.css b/static/project-workspace/base.css index 233d07f6..050a810d 100644 --- a/static/project-workspace/base.css +++ b/static/project-workspace/base.css @@ -776,6 +776,9 @@ tr.wts-row:has(+ tr.wts-open) > td { background: var(--accent-wash); } .st-scroll { overflow: auto; max-height: 380px; border: 1px solid var(--line); border-radius: var(--radius); background: var(--surface-2); } .st-scroll svg { display: block; font-family: var(--font); } .st-scroll.fit svg { height: auto; } +/* "Open wide": the Structure block over the page, under the top bar, at the window's width. */ +.st-overlay { position: fixed; inset: 48px 0 0 0; z-index: 60; overflow: auto; padding: 16px 20px 24px; background: var(--page); border-top: 1px solid var(--line); } +.st-overlay .st-scroll { max-height: calc(100vh - 280px); } .st-edge { fill: none; stroke: var(--line-strong); stroke-width: 1.3; } .st-edge.back { stroke-dasharray: 3 3; } .st-arrowhead { fill: var(--line-strong); } diff --git a/static/project-workspace/structure.js b/static/project-workspace/structure.js index d04aa1af..8ebcfb60 100644 --- a/static/project-workspace/structure.js +++ b/static/project-workspace/structure.js @@ -67,6 +67,23 @@ window.LabStructure = (() => { putInPlace(ctx.box, root || h('div'), ctx.scroller); } + /** The Structure block drawn again over the page, full width; Escape or "Back to the drawer" closes it. */ + function openWide(ctx) { + if (ctx.st.wideCtx) return; + const box = h('div', 'st-overlay'); box.setAttribute('role', 'dialog'); box.setAttribute('aria-label', 'Structure, full width'); + document.body.appendChild(box); + const w = { ...ctx, box, scroller: box, turn: 0, wide: true, base: ctx }; + w.esc = ev => { if (ev.key === 'Escape') closeWide(w); }; + document.addEventListener('keydown', w.esc); + ctx.st.wideCtx = w; + again(w).then(() => { const b = box.querySelector('[data-key="st-wide"]'); if (b) b.focus(); }); + } + function closeWide(w) { + document.removeEventListener('keydown', w.esc); + w.box.remove(); w.st.wideCtx = null; + again(w.base).then(() => { const b = w.base.box.querySelector('[data-key="st-wide"]'); if (b) b.focus(); }); + } + /** The other models it can be compared with: the model it derives from and those derived from it, with a graph. */ async function choicesFor(m, g) { const refs = [m.parent].filter(p => p && g.byId.has(p)).map(p => ['parent', p]).concat(g.nodes.filter(n => n.parent === m.id).map(n => ['child', n.id])); @@ -115,7 +132,10 @@ window.LabStructure = (() => { const one = button('btn sm', 'Fold to depth 1', () => { Object.assign(st, { depth: 1, open: [], close: [] }); again(ctx); }); one.dataset.key = 'st-fold-1'; const fit = button('btn sm', 'Fit to width', () => { st.fit = !st.fit; again(ctx); }); fit.dataset.key = 'st-fit'; fit.setAttribute('aria-pressed', String(st.fit)); fit.title = 'Shrink the drawings to the drawer\'s width, for an overview; press again for their actual size'; - folds.appendChild(all); folds.appendChild(one); folds.appendChild(fit); bar.appendChild(folds); + // The drawer is narrow: the same view, with the same state, opens over the page at its full width. + const wide = button('btn sm', ctx.wide ? 'Back to the drawer' : 'Open wide', () => (ctx.wide ? closeWide(ctx) : openWide(ctx))); + wide.dataset.key = 'st-wide'; + folds.appendChild(all); folds.appendChild(one); folds.appendChild(fit); folds.appendChild(wide); bar.appendChild(folds); root.appendChild(bar); // The overlay and the comparison, read in full before anything is drawn. let overlay = null, overlayError = null; diff --git a/tests/browser_project_workspace_structure.cjs b/tests/browser_project_workspace_structure.cjs index 94fe8f96..96120a53 100644 --- a/tests/browser_project_workspace_structure.cjs +++ b/tests/browser_project_workspace_structure.cjs @@ -267,6 +267,14 @@ const nodes = (which = 'this') => evaluate(`[...document.querySelectorAll('#asid await shot('light-1440-3b-fit'); await press(byKey('st-fit')); await settled('actual size'); assert.ok(await evaluate(`(() => { const sc = document.querySelector('#aside .st-draw[data-which="this"] .st-scroll'); return sc.scrollWidth - sc.clientWidth > 100; })()`), 'Actual size scrolls again'); + // Open wide: the same view over the page at the window's width; Escape closes it. + await press(byKey('st-wide')); + await until(() => evaluate(`!!document.querySelector('.st-overlay .st-draw[data-which="this"] svg')`), 'the wide view'); + const wide4 = await evaluate(`(() => { const sc = document.querySelector('.st-overlay .st-draw[data-which="this"] .st-scroll'), d = document.querySelector('#aside .st-scroll'); return { wide: sc.clientWidth, drawer: d ? d.clientWidth : 0 }; })()`); + assert.ok(wide4.wide > 2 * wide4.drawer, 'The wide view is much wider than the drawer: ' + JSON.stringify(wide4)); + await shot('light-1440-3c-wide'); + await evaluate(`(() => { document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape' })); return true; })()`); + await until(() => evaluate(`!document.querySelector('.st-overlay')`), 'the wide view closed'); check('4. Coloured by parameters (' + fills4.size + ' fills, each value the server\'s), then by the change from the starting weights (stem ' + n4b.find(n => n.id === stem.id).value.toFixed(4) + ', the fixture\'s ' + X.against_initial.stem.toFixed(4) + ')'); // ---- 5. Compared with the parent ------------------------------------------------------------------------------------------ From 9a06ef8bc9419f885dbbb004b981184c78de8f5c Mon Sep 17 00:00:00 2001 From: MrScripty <TheEnvironmentGuy@protonmail.com> Date: Thu, 19 Nov 2026 09:05:36 -0700 Subject: [PATCH 130/131] docs(plan): Tuldok before and after the training-and-curation plan Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --- .../plans/training-and-curation/comparison.md | 70 +++++++++++++++++++ docs/plans/training-and-curation/plan.md | 2 +- 2 files changed, 71 insertions(+), 1 deletion(-) create mode 100644 docs/plans/training-and-curation/comparison.md diff --git a/docs/plans/training-and-curation/comparison.md b/docs/plans/training-and-curation/comparison.md new file mode 100644 index 00000000..41c4ecd2 --- /dev/null +++ b/docs/plans/training-and-curation/comparison.md @@ -0,0 +1,70 @@ +# Tuldok before and after the training-and-curation plan + +**Before:** the tag `tuldok-before-training-and-curation` (`58226bb5`, 2026-11-19). +**After:** `feat/definition-first-projects` at the commit that adds this file. Nothing is pushed. + +Between them: 7 phases, 50+ commits, 123 files, about 24,000 lines added. Every phase was specified first (`spec-t1.md` … `spec-t7.md`, each with an "As built" section), built by an agent on a branch of its own, reviewed, merged and tested again after the merge. + +## Seeing them side by side + +Both run against your lab project (`projects/surrogate-lab`) and your own Tuldok database: + +| Version | Address | +| --- | --- | +| Before (the tag) | http://127.0.0.1:8093/ | +| After (latest) | http://127.0.0.1:8092/ | + +Each asks for a sign-in code; one code works for both, since they share the same data folder. The newer version adds a few tables to the database, which the older one ignores, so neither disturbs the other. + +**What your lab data shows today.** The lab's earlier runs were made before these contracts existed, so they have no training logs, model graphs, embeddings, annotation sets, sweeps or `serve` declarations. On the lab the new version therefore shows: the **Compare** tab (with kept-field outputs of three earlier pressure models side by side), **parallel coordinates** over the 150 pressure fits on Benchmarks, the two new tabs (**Sweeps**, **Compare**), and empty states that say what each new block needs. The rest is shown on the test fixtures. The screenshots of each check are listed below (git-ignored, on this machine under `build/qa/`). + +## What changed, tab by tab + +| Where | Before | After | +| --- | --- | --- | +| Tabs | Map, Data, Annotate, Train, Benchmarks, Analysis, Overview | adds **Sweeps** and **Compare**; the tab bar scrolls instead of widening the page; on a phone the tabs take their own row | +| Train → a run | progress, standard output and error | **live training curves** (series, several runs overlaid, smoothing, log scale, step or time), **weight and gradient histograms over steps**, a strip of **samples**; all updated in place while the run writes | +| Train → served models | — | **serve a trained model** from its own `serve.py` (`load`, `predict`), on this machine, behind Tuldok's credentials: `POST /api/serve/<model>/predict`; start, approve, stop, "Try it"; latency p50/p95/p99 and throughput; a served session can become a benchmark subject | +| Map → a model's drawer | card, runs, weights | adds **Structure**: the model's graph from `model-graph.json` (modules folded into groups, colour by parameters or by change from the starting weights or the parent, compared with another model, a node's tensors linked to Weights, **Open wide** over the page); **Serve** | +| Data → a dataset | records, files, look inside | adds **Map**: the dataset's embeddings in two dimensions, coloured by split or annotation, box and lasso select, **more like this, duplicates, outliers, leakage across splits, thin regions**; a selection becomes a dataset (`select`) or a freeze; an **Embed** form (default embedder **EmbeddingGemma 2** through Pumas) | +| Annotate | decision, class, tags, text, boxes, spans, segments; suggestions | adds **polygons, masks, depth maps, keypoints, ranking, time series, tracks, point-cloud objects, 3D boxes**; annotation **sets** made by an annotator (a project's script or a Pumas model) via the step `annotate`; **Review**: two sets side by side or overlaid, **agreement** (kappa, IoU, OKS, Kendall's τ, track switches), the most disputed records, Keep A / Keep B / both / neither, light corrections | +| Sweeps (new) | — | **hyperparameter search** on this machine: a `sweeps/<name>.json` (grid, random, halving with early stopping), one approval for the whole budget, trials as derived recipes on the Map, live state, the trials' frontier and parallel coordinates | +| Benchmarks | charts, table, compare set of 3 | adds **parallel coordinates** (metrics and varying recipe settings, brushing linked to the table and charts), **bootstrap 95 % intervals** where per-case values exist (whiskers, and frontier points marked when not told apart), a compare set of 4; opens on a benchmark with an accuracy-against-time chart | +| Compare (new) | — | 2 to 4 models: what differs, metrics with intervals, place on the frontier, and their **outputs side by side** on a shared case (native, predicted, signed error, one slice control for all) | + +**For project scripts:** a small helper package, `tuldok_log`, writes these files in a few lines: `log`, `log_histograms`, `log_sample`, `autolog(model, optimizer)` for PyTorch, and `export_graph(model, example_inputs, path)`. Projects may write the files themselves instead; the formats are in `docs/contracts/project-folder.md`. + +## Tests on the final code + +| Suite | Before (at the tag) | After | +| --- | --- | --- | +| Project suite (`test_tuldok_project_*`) | 735 | **898**, all pass | +| Agent interface (catalog digest unchanged) | 43, 4 skipped | 43, 4 skipped | +| Workspace browser checks | 8 files | **15 files**, all pass (actions 27, annotate 11, annotation kinds 8, workspace 24, compare 6, curation 7, endpoint 8, fields 8, inside 8, serving 6, still 6, structure 8, sweeps 7, training 7, weights 7) | +| `tuldok_log` with PyTorch 2.8 on the CPU (the lab's environment, read only) | — | 13 pass | + +**On your real lab data, read only:** the new reads answer on the 206-model project (map 0.09 s, compare of three models 0.04 s, parallel coordinates over 150 fits 0.05 s). One was slow and was fixed: listing servable models took 13 s and now takes 0.09 s. + +## Screenshots of each new part (from the browser checks) + +| Part | Directory under `build/qa/` | +| --- | --- | +| Training curves, histograms, samples, live | `project-workspace-training/` | +| Structure, folded, compared, wide | `project-workspace-structure/` (`light-1440-3c-wide.png`) | +| Compare tab, outputs, parallel coordinates, intervals | `project-workspace-compare/` | +| Annotation types, review, agreement | `project-workspace-annotation-kinds/` | +| Embedding map, curation lists, Embed form | `project-workspace-curation/` | +| Serving | `project-workspace-serving/` | +| Sweeps | `project-workspace-sweeps/` | + +## Not done, and not verified + +- Nothing was trained on the GPU, nothing was benchmarked, and no running Pumas was contacted. EmbeddingGemma 2, Pumas annotators and the Pumas endpoint were tested against a fake. +- Your lab has none of the new inputs yet (training logs, graphs, embeddings, annotation sets, sweeps, `serve`). A converter of the lab's earlier `history.json` into training logs was deferred. +- Known limits are in each spec's "As built". The larger ones: + - Curation searches finish over every record only up to a few thousand records on dense data; the page says how many were examined. + - A sweep's objectives are training metrics, not benchmark metrics. + - Serving uses the code at HEAD, not at the product's commit. + - Mask and depth agreement is computed pixel by pixel in Python. + - At phone width the closed drawer still sits 9 px past the edge. +- Pumas cannot serve these models yet. It serves only models in its library, and only for fixed task types. A Pumas backend for serving is left as a seam (`serve.backend`). diff --git a/docs/plans/training-and-curation/plan.md b/docs/plans/training-and-curation/plan.md index 35d0fefd..be981154 100644 --- a/docs/plans/training-and-curation/plan.md +++ b/docs/plans/training-and-curation/plan.md @@ -1,6 +1,6 @@ # Plan: training views, model structure, generated annotation, curation, comparison, serving and search -**Status:** approved 2026-11-19 ("I agree"), with the four decisions as recommended. The baseline before this plan is the tag `tuldok-before-training-and-curation`. Embeddings through the Pumas endpoint default to EmbeddingGemma 2 (owner, 2026-11-19: "Set embeddinggemma 2 as the default embbedder for Pumas"). +**Status:** built 2026-11-19, phases 1 to 7 (see [comparison.md](comparison.md)); approved 2026-11-19 ("I agree"), with the four decisions as recommended. The baseline before this plan is the tag `tuldok-before-training-and-curation`. Embeddings through the Pumas endpoint default to EmbeddingGemma 2 (owner, 2026-11-19: "Set embeddinggemma 2 as the default embbedder for Pumas"). **Owner, 2026-11-19:** "Tuldok needs live training views and model structure viwer. … Tuldok also needs a strong set of annotation types … Tuldok centers on generated annotations rather than human made ones … automated/ai segmentors, polygons, depth mapping, image masks, ranking, time series, object tracking, point cloud objects (selecting points that belong to an object), some quality control tools like agreement betwene different models … We should also have serving trained models as a REST endpoint and autologging. … it would be great if it could compare selected models deeper like also showing output results next to eachother. … Tuldok should have curarion by embeddings. … Parallel coordinates sound very usful for Tuldok. Hyperparameter search could be usful … on tiny models localy. We are not going to add a model zoo now." From a04f4c93905c91b9670eb3523af18965112840a5 Mon Sep 17 00:00:00 2001 From: MrScripty <TheEnvironmentGuy@protonmail.com> Date: Thu, 19 Nov 2026 13:56:47 -0700 Subject: [PATCH 131/131] test(serving): expect an encoded array back when NumPy is installed On CI the environment has NumPy, so predict receives a float32 array and the answer encodes it again; the test assumed lists. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --- tests/test_tuldok_project_serving.py | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/tests/test_tuldok_project_serving.py b/tests/test_tuldok_project_serving.py index 4aa66700..65924372 100644 --- a/tests/test_tuldok_project_serving.py +++ b/tests/test_tuldok_project_serving.py @@ -308,7 +308,13 @@ def test_start_ready_predict_stop(self): self.assertLessEqual(answer['timing']['model_ms'], answer['timing']['total_ms']) encoded = self.predict({'a': array([2, 2], [1, 2, 3, 4.5])})['outputs'] self.assertEqual(encoded['sum'], 10.5) - self.assertEqual(encoded['echo'], [[1.0, 2.0], [3.0, 4.5]]) # no NumPy: decoded to lists, sent as lists + # Without NumPy the array arrives as nested lists and goes back as lists; with NumPy (as on CI) predict gets a + # float32 array and the answer encodes it again as an array. + try: + import numpy # noqa: F401 + self.assertEqual(encoded['echo'], array([2, 2], [1, 2, 3, 4.5])) + except ImportError: + self.assertEqual(encoded['echo'], [[1.0, 2.0], [3.0, 4.5]]) with self.assertRaises(ServeError) as refused: self.predict({'fail': True}) self.assertEqual(refused.exception.code, 'predict-failed')

                            f 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] +const assert = require('node:assert/strict'), fs = require('node:fs'), os = require('node:os'), path = require('node:path'), crypto = require('node:crypto'); +const { spawn, execFileSync } = require('node:child_process'), { once } = require('node:events'); +const { authenticatedFixture } = require('./auth_helpers.cjs'), { waitForDebugger } = require('./browser_startup.cjs'), { cdpSession } = require('./browser_cdp_session.cjs'), { qaDirectory, screenshotOptions } = require('./qa_artifacts.cjs'); + +const root = path.resolve(__dirname, '..'); +const argv = process.argv.slice(2), labAt = argv.indexOf('--lab-root'); +const labRoot = labAt >= 0 ? path.resolve(argv[labAt + 1] || '') : null; +if (labAt >= 0) assert.ok(argv[labAt + 1] && fs.existsSync(path.join(labRoot, 'tuldok.json')), '--lab-root names a project folder (it holds tuldok.json)'); +assert.ok(process.env.TULDOK_DATABASE_URL, 'TULDOK_DATABASE_URL must name a disposable PostgreSQL cluster'); +const venv = path.join(root, '.venv', 'bin'); +if (fs.existsSync(path.join(venv, 'python'))) process.env.PATH = venv + path.delimiter + process.env.PATH; // auth_helpers runs python3 +const python = fs.existsSync(path.join(venv, 'python')) ? path.join(venv, 'python') : 'python3'; +const WIDTH = 1440, HEIGHT = 900; +const TABS = ['map', 'data', 'train', 'benchmarks', 'analysis', 'overview']; +const BUILT = ['map', 'overview']; + +const temporary = fs.mkdtempSync(path.join(os.tmpdir(), 'tuldok-workspace-browser-')); +const report = qaDirectory(root, labRoot ? 'project-workspace-lab' : 'project-workspace'); +const children = [], checks = [], errors = [], failedRequests = [], bounds = []; +let server, serverErrors = '', origin, auth, socket, session, send, evaluate; +const pause = ms => new Promise(resolve => setTimeout(resolve, ms)); +async function until(fn, label, tries = 300) { for (let i = 0; i < tries; i++) { const value = await fn(); if (value) return value; await pause(100); } throw Error('Timed out: ' + label); } +function check(text) { checks.push(text); console.log('PASS ' + text); } +function launch(command, args, options) { const child = spawn(command, args, options); children.push(child); return child; } +async function stop(child) { if (!child || child.exitCode !== null || child.signalCode !== null) return; const exited = once(child, 'exit'); child.kill('SIGTERM'); await Promise.race([exited, pause(10000)]); if (child.exitCode === null && child.signalCode === null) { child.kill('SIGKILL'); await exited; } } +function snapshot(directory) { + const files = {}; + (function walk(at) { for (const item of fs.readdirSync(at, { withFileTypes: true })) { const next = path.join(at, item.name); if (item.isDirectory()) walk(next); else files[path.relative(directory, next)] = item.isFile() ? crypto.createHash('sha256').update(fs.readFileSync(next)).digest('hex') : 'special'; } })(directory); + return files; +} +function findBrowser() { + const candidates = [process.env.BROWSER, '/usr/bin/chromium', '/usr/bin/chromium-browser', '/usr/bin/google-chrome']; + const cache = path.join(os.homedir(), '.cache', 'ms-playwright'); + if (fs.existsSync(cache)) for (const name of fs.readdirSync(cache).filter(n => n.startsWith('chromium_headless_shell-')).sort().reverse()) candidates.push(path.join(cache, name, 'chrome-headless-shell-linux64', 'chrome-headless-shell')); + const found = candidates.find(candidate => candidate && fs.existsSync(candidate)); + assert.ok(found, 'No headless browser: set BROWSER'); + return found; +} +/** Drops the project's schema and the catalog's from the disposable database, so each run imports afresh. */ +function dropOwned(folder, catalog) { + const id = JSON.parse(fs.readFileSync(path.join(folder, 'tuldok.json'), 'utf8')).id; + execFileSync(python, ['-c', `import json, os, pathlib, sys, psycopg +from psycopg import sql +from tuldok_project import store +store.drop_project(sys.argv[1], os.environ['TULDOK_DATABASE_URL']) +root = pathlib.Path(sys.argv[2]) +if root.exists(): + with psycopg.connect(os.environ['TULDOK_DATABASE_URL'], autocommit=True) as c: + for p in root.rglob('.tuldok.json'): + v = json.loads(p.read_text()) + name = 'projection_' + v['projection_id'] if v.get('version') == 2 else 'catalog_' + v['dataset_id'] + c.execute(sql.SQL('DROP SCHEMA IF EXISTS {} CASCADE').format(sql.Identifier(name))) +`, id, catalog], { cwd: root, stdio: ['ignore', 'pipe', 'pipe'] }); +} +let owned = null; +async function api(name, body = {}) { + const capabilities = await (await auth.fetch(origin + '/api/agent/capabilities')).json(); + const operation = capabilities.operations.find(item => item.id === 'project.' + name), contract = operation.contracts[operation.contracts.length - 1]; + const response = await auth.fetch(origin + '/api/project/' + name, { method: 'POST', headers: { 'Content-Type': 'application/json', 'Tuldok-Operation-Contract': 'project.' + name + '/' + contract.version + '/' + contract.sha256 }, body: JSON.stringify(body) }); + const value = await response.json(); assert.equal(response.status, 200, JSON.stringify(value)); return value; +} + +async function shot(name) { + await evaluate('new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve)))'); + fs.writeFileSync(path.join(report, name + '.jpg'), Buffer.from((await send('Page.captureScreenshot', screenshotOptions)).data, 'base64')); +} +/** No sideways overflow of the page or of a non-map main area, and a main area that shows something. */ +async function inspect(label) { + const value = await evaluate(`(() => { + const main = document.getElementById('main'), top = document.querySelector('.top'), strip = document.getElementById('strip'); + const text = main.innerText.trim(); + return { label: ${JSON.stringify(label)}, viewport: innerWidth, page: document.documentElement.scrollWidth, body: document.body.scrollWidth, + main: main.classList.contains('map') ? null : [main.scrollWidth, main.clientWidth], top: [top.scrollWidth, top.clientWidth], strip: [strip.scrollWidth, strip.clientWidth], + text: text.length, children: main.children.length, reading: /^Reading/.test(text), + shifted: [document.body, document.querySelector('.stage')].some(e => e.scrollLeft || e.scrollTop) }; + })()`); + bounds.push(value); + assert.ok(value.page <= value.viewport && value.body <= value.viewport, 'Sideways overflow of the page: ' + JSON.stringify(value)); + assert.ok(!value.main || value.main[0] <= value.main[1] + 1, 'Sideways overflow of the main area: ' + JSON.stringify(value)); + assert.ok(value.top[0] <= value.top[1] + 1 && value.strip[0] <= value.strip[1] + 1, 'Sideways overflow of the top bar or strip: ' + JSON.stringify(value)); + assert.ok(value.text > 0 && value.children > 0 && !value.reading, 'Empty main area: ' + JSON.stringify(value)); + assert.ok(!value.shifted, 'The shell is scrolled: ' + JSON.stringify(value)); +} +async function open(theme, hash) { + await send('Emulation.setEmulatedMedia', { features: [{ name: 'prefers-color-scheme', value: theme }, { name: 'prefers-reduced-motion', value: 'reduce' }] }); + await send('Page.navigate', { url: origin + '/?theme=' + theme + '#' + hash }); + await until(() => evaluate(`document.readyState === 'complete' && !!document.getElementById('needs-btn') && !document.getElementById('needs-btn').disabled`), 'the project read (' + hash + ')'); +} +async function tab(name) { + await evaluate(`location.hash = '#${name}'`); + await until(() => evaluate(`(() => { const t = document.getElementById('main').innerText; return t.trim().length > 0 && !t.includes('Reading'); })()`), 'tab ' + name); +} +async function mouse(x, y, click = false) { + await send('Input.dispatchMouseEvent', { type: 'mouseMoved', x, y }); + if (click) { await send('Input.dispatchMouseEvent', { type: 'mousePressed', x, y, button: 'left', clickCount: 1 }); await send('Input.dispatchMouseEvent', { type: 'mouseReleased', x, y, button: 'left', clickCount: 1 }); } +} +async function centre(selector) { + const box = await evaluate(`(() => { const e = document.querySelector(${JSON.stringify(selector)}); if (!e) return null; e.scrollIntoView({ block: 'nearest', inline: 'nearest' }); const r = e.getBoundingClientRect(); return { x: r.left + r.width / 2, y: r.top + r.height / 2 }; })()`); + assert.ok(box, 'Missing ' + selector); + return box; +} +async function press(selector) { const { x, y } = await centre(selector); await mouse(x, y, true); } + +(async () => { + let folder; + if (labRoot) folder = labRoot; + else { + fs.cpSync(path.join(root, 'tests', 'fixtures', 'tuldok_project', 'minimal'), path.join(temporary, 'fixture'), { recursive: true }); + folder = path.join(temporary, 'fixture', 'project'); + // One more model with no group, no kind of change, no training date and no result, to show each absence. + fs.writeFileSync(path.join(folder, 'recipes', 'loose.json'), JSON.stringify({ format: 'tuldok_definition_v1', kind: 'recipe', title: 'A recipe with nothing set', description: 'Neither grouped, nor kinded, nor dated, nor measured.', earlier_work: { rebuild: 'no', reason: 'A browser check fixture.' }, model: 'models/stepper' }, null, 2) + '\n'); + } + const before = labRoot ? null : snapshot(folder); + const home = path.join(temporary, 'home'), catalog = path.join(temporary, 'catalog'); fs.mkdirSync(home); + owned = [folder, catalog]; dropOwned(folder, catalog); + let output = ''; + server = launch(python, ['-u', 'app.py', '--port', '0', '--data', catalog, '--project-folder', folder], { cwd: root, env: { ...process.env, TULDOK_PROJECT_HOME: home }, stdio: ['ignore', 'pipe', 'pipe'] }); + server.stdout.on('data', chunk => { output += chunk; }); server.stderr.on('data', chunk => { serverErrors += chunk; }); + const port = await until(() => { if (server.exitCode !== null) throw Error('Tuldok exited: ' + serverErrors); return output.match(/127\.0\.0\.1:(\d+)/)?.[1]; }, 'Tuldok start-up', 1800); + origin = 'http://127.0.0.1:' + port; + auth = authenticatedFixture(); await auth.register(origin, catalog, root); + const map = await api('map'), summary = await api('summary'); + check('Tuldok serves ' + summary.name + ' with ' + map.models.length + ' models, ' + map.groups.length + ' groups, ' + map.edges.filter(e => e.kind === 'derived').length + ' derivations, ' + map.comparisons.length + ' comparisons and ' + map.models.filter(m => m.value != null).length + ' track values'); + + const browser = launch(findBrowser(), ['--headless', '--no-sandbox', '--disable-gpu', '--no-first-run', '--hide-scrollbars', '--remote-debugging-port=0', `--window-size=${WIDTH},${HEIGHT}`, '--user-data-dir=' + path.join(temporary, 'browser'), 'about:blank'], { stdio: 'ignore', env: { ...process.env, XDG_CONFIG_HOME: temporary, XDG_CACHE_HOME: temporary } }); + const debugPort = await waitForDebugger(browser, path.join(temporary, 'browser', 'DevToolsActivePort')); + const target = (await (await fetch('http://127.0.0.1:' + debugPort + '/json')).json()).find(item => item.type === 'page'); + socket = new WebSocket(target.webSocketDebuggerUrl); await once(socket, 'open'); + session = cdpSession(socket, { timeoutMs: 60000, onEvent: event => { + if (event.method === 'Runtime.exceptionThrown') errors.push(event.params.exceptionDetails.exception?.description || event.params.exceptionDetails.text); + if (event.method === 'Runtime.consoleAPICalled' && event.params.type === 'error') errors.push(event.params.args.map(a => a.value ?? a.description).join(' ')); + if (event.method === 'Log.entryAdded' && event.params.entry.level === 'error') errors.push(event.params.entry.text + ' ' + (event.params.entry.url || '')); + if (event.method === 'Network.loadingFailed' && !event.params.canceled) failedRequests.push({ id: event.params.requestId, error: event.params.errorText }); + if (event.method === 'Network.responseReceived' && event.params.response.status >= 400) failedRequests.push({ url: event.params.response.url, status: event.params.response.status }); + } }); + send = session.send; + evaluate = async expression => { const result = await send('Runtime.evaluate', { expression, awaitPromise: true, returnByValue: true }); if (result.exceptionDetails) throw Error(JSON.stringify(result.exceptionDetails)); return result.result.value; }; + await send('Page.enable'); await send('Runtime.enable'); await send('Network.enable'); await send('Log.enable'); + await send('Emulation.setDeviceMetricsOverride', { width: WIDTH, height: HEIGHT, deviceScaleFactor: 1, mobile: false }); + await auth.browser(send, origin); + + for (const theme of ['light', 'dark']) { + await open(theme, 'map'); + assert.equal(await evaluate(`getComputedStyle(document.documentElement).colorScheme`), theme); + for (const name of TABS) { + await tab(name); + await inspect(theme + ' ' + name); + if (!BUILT.includes(name)) assert.match(await evaluate(`document.getElementById('main').innerText`), /is not built yet\.$/); + await shot(theme + '-' + name); + if (name === 'map') { // the rest of a wide map, and the end of the list + const wide = await evaluate(`(() => { const m = document.querySelector('.tree-map'); return m.scrollWidth > m.clientWidth + 10; })()`); + if (wide) { + await evaluate(`(() => { const m = document.querySelector('.tree-map'); m.scrollLeft = (m.scrollWidth - m.clientWidth) / 2; })()`); await shot(theme + '-map-middle'); + await evaluate(`(() => { const m = document.querySelector('.tree-map'); m.scrollLeft = m.scrollWidth; document.querySelector('.tree-host').scrollTop = 1e7; })()`); await shot(theme + '-map-end'); + await evaluate(`(() => { document.querySelector('.tree-map').scrollLeft = 0; document.querySelector('.tree-host').scrollTop = 0; })()`); + } + } + } + check('Every tab in ' + theme + ' at ' + WIDTH + ' by ' + HEIGHT + ': no overflow, no empty main area; the four tabs of the next slice say they are not built yet'); + } + const fonts = await evaluate(`document.fonts.ready.then(() => [...document.fonts].filter(f => f.status === 'loaded').map(f => f.family + ' ' + f.style))`); + assert.ok(fonts.some(f => /Ubuntu Sans"? normal/.test(f)) && fonts.some(f => /Ubuntu Sans Mono"? normal/.test(f)), 'The vendored faces load: ' + JSON.stringify(fonts)); + check('The vendored Ubuntu Sans and Ubuntu Sans Mono load: ' + fonts.join(', ')); + + for (const theme of ['light', 'dark']) { + await open(theme, 'map'); + const shown = await evaluate(`({ sections: [...document.querySelectorAll('.tree-map .bandlabel')].map(t => t.firstChild.textContent), nodes: document.querySelectorAll('.tree-map .node').length, rows: document.querySelectorAll('.tree-list .trow').length, lines: document.querySelectorAll('.tree-map .der').length, + unset: document.querySelectorAll('.tree-map .node.unset').length, unsetChips: [...document.querySelectorAll('.tree-list .chip.unset')].map(c => c.textContent), noValue: document.querySelectorAll('.tree-list .mbar.none').length })`); + assert.equal(shown.nodes, map.models.length); assert.equal(shown.rows, map.models.length); + // Each absence is shown: a section for models without a group, a hollow mark named for those without a kind, an empty bar without a value. + assert.equal(shown.sections.includes('Not in a group'), map.models.some(m => !m.group)); + assert.equal(shown.unset, map.models.filter(m => !m.change).length); assert.ok(shown.unsetChips.every(t => t === 'Kind not set')); + assert.equal(shown.noValue, map.models.filter(m => m.value == null).length); + // Hover a node with a track value: its tip names it. + const hovered = map.models.find(m => m.value != null && m.short) || map.models[0]; + const { x, y } = await centre(`.tree-map .node[data-id="${hovered.reference}"]`); + await mouse(x, y); + const tip = await until(() => evaluate(`(() => { const t = document.querySelector('#main > .tip'); return t && !t.hidden && t.innerText; })()`), 'the hover tip'); + assert.ok(tip.includes(hovered.title), 'The tip names the hovered model: ' + tip); + await shot(theme + '-map-hover'); + // Open a model with a card in the drawer. + const opened = map.models.find(m => m.card && map.comparisons.some(c => c.from === m.reference || c.to === m.reference)) || map.models.find(m => m.card) || map.models[0]; + await press(`.tree-map .node[data-id="${opened.reference}"]`); + await until(() => evaluate(`document.getElementById('drawer').classList.contains('open') && ![...document.querySelectorAll('#aside .note')].some(e => e.textContent === 'Reading…')`), 'the drawer filled'); + const drawer = await evaluate(`({ title: document.querySelector('#aside h2').textContent, card: document.querySelector('#aside .card-md') ? document.querySelector('#aside .card-md').children.length : 0, arcs: document.querySelectorAll('.tree-map .cmp').length, failures: [...document.querySelectorAll('#aside .failure')].map(e => e.textContent), hash: location.hash })`); + assert.equal(drawer.title, opened.title); assert.deepEqual(drawer.failures, []); + if (opened.card) assert.ok(drawer.card > 0, 'The card is rendered'); + assert.equal(drawer.hash, '#map/' + encodeURIComponent(opened.reference)); + await evaluate(`document.getElementById('drawer').scrollTop = 0`); + await shot(theme + '-map-drawer'); + await evaluate(`(() => { const c = document.querySelector('#aside .card-md'); if (c) c.scrollIntoView({ block: 'start' }); })()`); + await shot(theme + '-map-card'); + // The track. + if (map.track) { + await press('#main .filters button[title]'); + await until(() => evaluate(`document.querySelectorAll('.tree-map .tpt').length`), 'the track'); + assert.equal(await evaluate(`document.querySelectorAll('.tree-map .tpt').length`), map.models.filter(m => m.value != null).length); + await evaluate(`document.querySelector('.tree-map').scrollTop = 1e6`); + await shot(theme + '-map-track'); + await press('#main .filters button[title]'); + } + await press('#drawer .close'); + await until(() => evaluate(`!document.getElementById('drawer').classList.contains('open')`), 'the drawer closed'); + check(theme + ': ' + shown.sections.length + ' sections, every model on the map and in the list, a hover tip, ' + opened.reference + ' opened with its card (' + drawer.card + ' blocks, ' + drawer.arcs + ' comparison arcs)' + (map.track ? ', the track drawn' : '')); + } + + // The card renderer builds elements only, whatever the text holds. + await open('light', 'map'); + const sample = ['# Title ', '', 'Some **bold**, *italic*, `code` and [a link](https://example.invalid/x) not bold.', '', + '- one', ' - nested *two*', '- three', '', '1. first', '2. second', '', '| A | B |', '| --- | ---: |', '| `x|y` | 2 |', '', + '```js', 'const a = " + diff --git a/static/project-workspace/app.js b/static/project-workspace/app.js index eefa8d10..bb843cca 100644 --- a/static/project-workspace/app.js +++ b/static/project-workspace/app.js @@ -11,7 +11,7 @@ const TABS = [['map', 'Map'], ['data', 'Data'], ['train', 'Train'], ['benchmarks', 'Benchmarks'], ['analysis', 'Analysis'], ['overview', 'Overview']]; const POLL_MS = 2000; const $ = id => document.getElementById(id); - const state = { screen: 'map', sel: {}, kinds: null, query: '', zoom: 1, track: false }; + const state = { screen: 'map', sel: {}, kinds: null, query: '', zoom: 1, track: false, ui: {}, benchmark: null, cmp: [] }; const data = { summary: null, map: null, standing: null, needs: null, readAt: '', polling: false }; let failed = null, mapText = null, pollTimer = null; const clock = () => new Date().toLocaleTimeString('en-GB', { hour: '2-digit', minute: '2-digit' }); @@ -28,8 +28,21 @@ setQuery: q => { state.query = q; render(); }, zoom: d => { state.zoom = Math.round(Math.min(1.6, Math.max(0.5, (state.zoom || 1) + d)) * 10) / 10; render(); }, toggleKind: (k, all) => { if (!state.kinds) state.kinds = new Set([k]); else if (state.kinds.has(k)) { state.kinds.delete(k); if (!state.kinds.size) state.kinds = null; } else { state.kinds.add(k); if (state.kinds.size === all.length) state.kinds = null; } render(); }, - toggleTrack: () => { state.track = !state.track; render(); } + toggleTrack: () => { state.track = !state.track; render(); }, + // The other tabs: their own settings (state.ui), and the benchmark and compare set, which the address keeps (?benchmark=, ?cmp=). + setUI: (k, v) => { state.ui[k] = v; render(); }, + setBenchmark: name => { state.benchmark = name; state.cmp = []; address(); render(); }, + toggleCompare: id => { const i = state.cmp.indexOf(id); if (i >= 0) state.cmp.splice(i, 1); else if (state.cmp.length < 3) state.cmp.push(id); address(); render(); }, + clearCompare: () => { state.cmp = []; address(); render(); } }; + /** Writes the benchmark and compare set into the address without reloading, so the view can be shared. */ + function address() { + const q = new URLSearchParams(location.search); + if (state.benchmark) q.set('benchmark', state.benchmark); else q.delete('benchmark'); + if (state.cmp.length) q.set('cmp', state.cmp.join(',')); else q.delete('cmp'); + const text = q.toString().replace(/%2C/g, ',').replace(/%2F/g, '/'); // references read as they are + history.replaceState(null, '', location.pathname + (text ? '?' + text : '') + location.hash); + } // ---- The status strip and Needs you --------------------------------------- function strip() { @@ -63,7 +76,7 @@ drawer.classList.remove('open'); drawer.setAttribute('aria-hidden', 'true'); main.classList.remove('with-drawer'); return; } - const wasMap = main.classList.contains('map'), view = state.screen + '/' + (state.screen === 'map' ? '' : state.sel[state.screen] || ''); + const wasMap = main.classList.contains('map'), view = state.screen + '/' + (state.screen === 'overview' ? state.sel.overview || '' : ''); // a selection elsewhere opens the drawer and keeps the place main.className = state.screen === 'map' ? 'map' : 'content'; if (state.screen !== 'map' && wasMap) main._tree = null; if (main._view !== view) { main.scrollTop = 0; main.scrollLeft = 0; main._view = view; } // a new screen starts at its top @@ -96,7 +109,7 @@ if (busy && !pollTimer) pollTimer = setTimeout(poll, POLL_MS); } catch (error) { data.needs = null; data.standing = Object.assign({}, data.standing, { text: data.standing.text + ' ' + error.message }); } strip(); - if (state.screen === 'overview') render(); + if (state.screen === 'overview' || state.screen === 'train') render(); } async function poll() { pollTimer = null; @@ -107,12 +120,13 @@ /** Everything again, when the window regains focus; the map is redrawn only when it changed. */ async function again() { if (failed) { P.forget(['summary', 'map']); return first(); } - P.forget(['summary', 'status', 'build_requests', 'environments', 'runs', 'map', 'activity', 'definitions', 'definition', 'recipe_results', 'products', 'note']); + P.forget(['summary', 'status', 'build_requests', 'environments', 'runs', 'map', 'activity', 'definitions', 'definition', 'recipe_results', 'products', 'note', + 'graph', 'results_overview', 'results', 'chart', 'values', 'build_request', 'run']); try { data.summary = await P.read('summary'); const text = JSON.stringify(await P.read('map')); if (text !== mapText) { mapText = text; data.map = await P.map(); $('aside')._for = null; render(); } - else if (state.screen === 'overview') render(); + else if (state.screen !== 'map') render(); } catch (error) { failed = error.message; render(); } await standing(); } @@ -131,6 +145,7 @@ window.addEventListener('hashchange', () => { parse(); render(); }); window.addEventListener('focus', () => { if (data.summary || failed) again(); }); window.addEventListener('tuldok-session', () => { if (failed) again(); }); + { const q = new URLSearchParams(location.search); state.benchmark = q.get('benchmark') || null; state.cmp = (q.get('cmp') || '').split(',').filter(Boolean).slice(0, 3); } parse(); strip(); render(); first(); } if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', start, { once: true }); else start(); diff --git a/static/project-workspace/base.css b/static/project-workspace/base.css index 60ed417a..726a4ca8 100644 --- a/static/project-workspace/base.css +++ b/static/project-workspace/base.css @@ -319,6 +319,76 @@ table.tv td.nowrap, table.tv td.ck { white-space: nowrap; } .cases .b { fill: var(--mark); } .cases .b.sel { fill: var(--accent); } .cases .base { stroke: var(--line-strong); } +/* The Benchmarks, Train, Data and Analysis tabs (tabs.js), from the mockup's base.css. */ +.chart .pt { fill: var(--k-component); } +.chart .pt.other { fill: var(--surface); stroke: var(--ink-2); stroke-width: 1.5; } +.chart g:hover > .pt, .chart g:focus-within > .pt { stroke: var(--ink); } +.chart .best { fill: none; stroke: var(--good); stroke-width: 1.5; stroke-dasharray: 5 3; } +.chart .stem { stroke: var(--line-strong); stroke-width: 1; } +.chart .rk { fill: var(--ink); font-size: 12.5px; font-family: var(--font); } +.chart .rk.on { font-weight: 600; } +.chart .rv { fill: var(--ink-2); font-size: 12px; font-family: var(--font); font-variant-numeric: tabular-nums; } +.chart .hit.band { fill: transparent; } +.chart .hit.band:hover, .chart .hit.band:focus-visible { fill: var(--surface-2); } +.legend .chip.other::before { background: transparent; box-shadow: inset 0 0 0 1.5px var(--ink-2); } +.chart.cases svg { height: auto; } +.cases .b.none { fill: none; stroke: var(--ink-3); stroke-width: 1; } +.cases g:hover > .b, .cases g:focus-within > .b { fill: var(--ink); } +.chart .hit ~ * { pointer-events: none; } /* the marks over a hit area never take the pointer from it */ +.bench-chart { margin-top: 22px; } +.bench-chart h3.panel { font-size: 13px; color: var(--ink-2); margin: 14px 0 4px; } +.bench-desc { margin: -4px 0 8px; } +.bench-note { margin: 0 0 12px; } +.bench-cmp, .bench-all { margin-top: 28px; } +.tv-wrap { overflow-x: auto; max-width: 100%; } +table.tv th button { font: inherit; color: inherit; background: none; border: 0; padding: 0; cursor: pointer; text-align: inherit; } +table.tv th button[aria-sort="ascending"]::after { content: " ↑"; color: var(--ink-3); } +table.tv th button[aria-sort="descending"]::after { content: " ↓"; color: var(--ink-3); } +table.tv tr.is-sel td { background: var(--accent-wash); } +table.tv tr.rowbtn { cursor: pointer; } +table.tv tr.rowbtn:hover td { background: var(--surface-2); } +table.tv td .linkish { font: inherit; color: var(--ink); background: none; border: 0; padding: 0; text-align: left; cursor: pointer; } +table.tv td.grp { max-width: 220px; overflow: hidden; text-overflow: ellipsis; } +table.tv td.best { color: var(--good); font-weight: 600; } +table.tv.pts { margin-top: 8px; } +.cmp-chips { display: flex; flex-wrap: wrap; gap: 6px; align-items: center; } +.cmp-chips .c { display: inline-flex; align-items: center; gap: 6px; padding: 2px 6px 2px 10px; border: 1px solid var(--line); border-radius: 999px; font-size: 12.5px; background: var(--surface); max-width: 100%; } +.cmp-chips .c i { width: 10px; height: 10px; border-radius: 50%; display: inline-block; flex: none; } +.cmp-chips .c button { border: 0; background: none; padding: 0 2px; color: var(--ink-3); font-size: 14px; line-height: 1; cursor: pointer; } +.cmp-chips .c.s1 i { background: var(--k-architecture); } .cmp-chips .c.s2 i { background: var(--k-refinement); } .cmp-chips .c.s3 i { background: var(--k-training-policy); } +table.cmpt { margin-top: 12px; } +table.cmpt .d { color: var(--ink-2); font-size: 12.5px; } +table.cmpt .d.better { color: var(--good); } table.cmpt .d.worse { color: var(--serious); } +.sect.gap, .filters.gap { margin-top: 28px; } +.row.todo { grid-template-columns: 120px minmax(0, 1fr) 140px; } +.row.request { grid-template-columns: 150px minmax(0, 1fr) 170px; } +.row.run { grid-template-columns: 120px minmax(160px, 1fr) 130px 70px 150px; } +.row.run .ck { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; } +.row.env { grid-template-columns: 120px minmax(0, 1fr) minmax(0, 0.8fr); } +.row.env .mono { color: var(--ink-3); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; direction: rtl; text-align: left; } +.row .sub.warnline { color: var(--warn); white-space: normal; } +.row .sub.live { display: flex; align-items: center; gap: 8px; } +.row .hair { position: relative; width: 120px; height: 2px; background: var(--grid); flex: none; } +.row .hair i { position: absolute; left: 0; top: 0; bottom: 0; background: var(--accent); } +.setup { display: grid; grid-template-columns: max-content minmax(0, 1fr); gap: 6px 14px; font-size: 13px; margin: 0; } +.setup dt { color: var(--ink-2); } +.setup dd { margin: 0; overflow-wrap: anywhere; min-width: 0; } +.setup dd.pre { white-space: pre-wrap; } +.evtext { white-space: pre-wrap; overflow-wrap: anywhere; font: 12px/1.5 var(--mono); padding: 10px; margin: 0; background: var(--surface-2); border-radius: var(--radius); color: var(--ink); max-height: 360px; overflow: auto; } +.ds-card .pv { display: block; width: 100%; aspect-ratio: 16 / 9; background: var(--surface-2); border-bottom: 1px solid var(--line); } +.ds-card .pv.text { display: grid; place-items: center; color: var(--ink-3); font: 12px/1.6 var(--mono); padding: 10px; white-space: pre; overflow: hidden; text-align: left; } +.ds-card .t .meta .state { margin-left: auto; } +.ds-card .t .uses { font-size: 12px; color: var(--ink-3); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; } +.viewer-bar { display: flex; flex-wrap: wrap; gap: 8px; align-items: center; margin-bottom: 14px; } +.viewer-bar select { max-width: 420px; } +.filters select { max-width: 300px; } +.filters input[type="search"] { width: 180px; } +.ana-sum { grid-template-columns: repeat(4, minmax(0, 160px)); margin: 4px 0 10px; } +.ana-none { margin-top: 8px; } +.pager { display: flex; gap: 8px; align-items: center; font-size: 12.5px; color: var(--ink-2); margin: 10px 0; } +table.cases-t { margin-top: 8px; } +@media (max-width: 1100px) { .row.run { grid-template-columns: 90px minmax(0, 1fr) 70px 130px; } .row.run > .chip { display: none; } } + /* ---- The shell: top bar, tabs, status strip, stage, drawer (b-map.html). ---- */ body.shell { height: 100vh; display: grid; grid-template-rows: 48px auto 1fr; overflow: clip; } /* clip: not even a script or scrollIntoView can scroll the shell */ .top { display: flex; align-items: center; gap: 22px; padding: 0 20px; border-bottom: 1px solid var(--line); background: var(--surface); min-width: 0; } diff --git a/static/project-workspace/charts.js b/static/project-workspace/charts.js index 716acde8..ca036bec 100644 --- a/static/project-workspace/charts.js +++ b/static/project-workspace/charts.js @@ -64,5 +64,170 @@ window.LabCharts = (() => { hide() { t.hidden = true; } }; } - return { el, h, fmtSci, scale, tooltip }; + // ---- Charts of benchmark results (the Benchmarks and Analysis tabs) -------- + // Each draws from data the page holds (the chart operation's points, or + // per-case values) at a given pixel width, so its text stays at the type + // scale whatever the window; every point can be hovered and focused, and + // Enter or a click selects it when the chart is given onSelect. + + /** A nice step (1, 2 or 5 times a power of ten) near span / count. */ + function niceStep(span, count) { const raw = span / Math.max(1, count), p = Math.pow(10, Math.floor(Math.log10(raw))), f = raw / p; return (f <= 1 ? 1 : f <= 2 ? 2 : f <= 5 ? 5 : 10) * p; } + /** + * The brief's axis: logarithmic over whole decades when every value is + * positive and they span at least two decades, linear otherwise (from zero + * when every value is positive). at(v) is 0 at the low end, 1 at the high. + */ + function axis(values) { + const xs = values.filter(v => v != null && Number.isFinite(v)); + if (!xs.length) return null; + const min = Math.min(...xs), max = Math.max(...xs); + if (min > 0 && max / min >= 100) { + const lo = Math.floor(Math.log10(min)), hi = Math.max(lo + 1, Math.ceil(Math.log10(max))), step = Math.ceil((hi - lo) / 6), ticks = []; + for (let e = lo; e <= hi; e += step) ticks.push(Math.pow(10, e)); + return { log: true, ticks, at: v => (Math.log10(Math.max(v, Math.pow(10, lo))) - lo) / (hi - lo), label: tickLabel }; + } + let lo = min >= 0 ? 0 : min, hi = max <= 0 ? 0 : max; if (hi === lo) hi = lo + (Math.abs(lo) || 1); + const step = niceStep(hi - lo, 5); lo = Math.floor(lo / step) * step; hi = Math.ceil(hi / step - 1e-9) * step; + const ticks = []; for (let v = lo; v <= hi + step / 2; v += step) ticks.push(Math.abs(v) < step / 1e6 ? 0 : v); + return { log: false, ticks, at: v => (v - lo) / (hi - lo), label: fmtSci }; + } + const axisWords = (title, a) => title + (a && a.log ? ' (log scale)' : ''); + /** Wires hover, focus, click and Enter of a focusable mark to a tip and onSelect. */ + function interactive(node, host, svg, at, rows, onSelect) { + const tip = host._tip || (host._tip = tooltip(host)); + const show = () => { const r = host.getBoundingClientRect(), s = svg.getBoundingClientRect(), [x, y] = at(); tip.show(s.left - r.left + x * s.width / svg.viewBox.baseVal.width, s.top - r.top + y * s.height / svg.viewBox.baseVal.height, rows()); }; + node.addEventListener('pointerenter', show); node.addEventListener('focus', show); + node.addEventListener('pointerleave', () => tip.hide()); node.addEventListener('blur', () => tip.hide()); + if (onSelect) { node.addEventListener('click', onSelect); node.addEventListener('keydown', e => { if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); onSelect(); } }); } + } + function frame(width, height, label) { const svg = el('svg', { viewBox: `0 0 ${width} ${height}`, role: 'group', 'aria-label': label }); return svg; } + function yGrid(svg, ax, Y, L, R, W) { const grid = el('g', { class: 'grid' }), labels = el('g', { class: 'axis' }); for (const v of ax.ticks) { grid.appendChild(el('line', { x1: L, y1: Y(v), x2: W - R, y2: Y(v) })); labels.appendChild(el('text', { x: L - 8, y: Y(v) + 4, 'text-anchor': 'end' }, ax.label(v))); } svg.appendChild(grid); svg.appendChild(labels); } + const textWidth = (text, size = 12) => text.length * size * 0.56; + + /** + * A scatter of points {id, name, x, y, kind, frontier, rows} with the + * frontier drawn through the points marked on it (in x order); the ends of + * the frontier are named. opts: width, height, xTitle, yTitle, xBetter, + * yBetter, selected, onSelect(id), dimOff (dim points off the frontier). + */ + function scatter(host, points, opts) { + host.textContent = ''; host.classList.add('chart'); host._tip = null; + const W = Math.max(360, opts.width), H = opts.height || 340, L = 64, R = 20, T = 22, B = 40; + const xa = axis(points.map(p => p.x)), ya = axis(points.map(p => p.y)); + const X = v => L + xa.at(v) * (W - L - R), Y = v => T + (1 - ya.at(v)) * (H - T - B); + const svg = frame(W, H, axisWords(opts.yTitle, ya) + ' against ' + axisWords(opts.xTitle, xa) + ', ' + points.length + ' points'); + yGrid(svg, ya, Y, L, R, W); + const ax = el('g', { class: 'axis' }); + xa.ticks.forEach((v, i) => { ax.appendChild(el('line', { x1: X(v), y1: H - B, x2: X(v), y2: H - B + 4, class: 'base' })); ax.appendChild(el('text', { x: X(v), y: H - B + 16, 'text-anchor': i === xa.ticks.length - 1 ? 'end' : 'middle' }, xa.label(v))); }); + ax.appendChild(el('line', { x1: L, y1: H - B, x2: W - R, y2: H - B, class: 'base' })); + ax.appendChild(el('text', { x: W - R, y: H - 4, 'text-anchor': 'end', class: 'label' }, axisWords(opts.xTitle, xa))); + ax.appendChild(el('text', { x: L, y: T - 8, class: 'label' }, axisWords(opts.yTitle, ya))); + svg.appendChild(ax); + const front = points.filter(p => p.frontier).sort((a, b) => a.x - b.x || a.y - b.y); + if (front.length > 1) svg.appendChild(el('path', { class: 'frontier', d: front.map((p, i) => (i ? 'L' : 'M') + X(p.x).toFixed(1) + ',' + Y(p.y).toFixed(1)).join(' ') })); + const order = points.slice().sort((a, b) => (a.id === opts.selected) - (b.id === opts.selected)); + for (const p of order) { + const g = el('g'), cx = X(p.x), cy = Y(p.y); + const hit = el('circle', { cx, cy, r: 11, class: 'hit', tabindex: 0, role: 'button', 'data-id': p.id, 'aria-label': p.name + ', ' + opts.yTitle + ' ' + fmtSci(p.y) + ', ' + opts.xTitle + ' ' + fmtSci(p.x) + (p.frontier ? ', on the frontier' : '') }); + g.appendChild(hit); g.appendChild(el('circle', { cx, cy, r: 6, class: 'pt ' + p.kind + ((opts.dimOff && !p.frontier) || p.dim ? ' dim' : '') })); + if (p.id === opts.selected) g.appendChild(el('circle', { cx, cy, r: 9, class: 'sel' })); + interactive(hit, host, svg, () => [cx, cy], p.rows, opts.onSelect && (() => opts.onSelect(p.id))); + svg.appendChild(g); + } + if (front.length) { // name the two ends of the frontier, as the mockup does + const lowY = opts.yBetter === 'higher' ? front.reduce((a, b) => b.y > a.y ? b : a) : front.reduce((a, b) => b.y < a.y ? b : a); + const lowX = opts.xBetter === 'higher' ? front.reduce((a, b) => b.x > a.x ? b : a) : front.reduce((a, b) => b.x < a.x ? b : a); + const word = (better, title) => { const t = (better === 'higher' ? 'highest ' : 'lowest ') + title.charAt(0).toLowerCase() + title.slice(1); return t.length > 34 ? t.slice(0, 33) + '…' : t; }; + const put = (p, text, dy) => { const w = textWidth(text), right = X(p.x) + 10 + w <= W - R; svg.appendChild(el('text', { x: right ? X(p.x) + 10 : X(p.x) - 10, y: Math.min(H - B - 4, Math.max(T + 10, Y(p.y) + dy)), 'text-anchor': right ? 'start' : 'end', class: 'label' }, text)); }; + put(lowY, lowY.short + ' · ' + word(opts.yBetter, opts.yName || opts.yTitle), 4); + if (lowX !== lowY) { // on the side the frontier does not leave by, so the line does not run through the words + const at = front.indexOf(lowX), next = front[at + 1] || front[at - 1]; + put(lowX, lowX.short + ' · ' + word(opts.xBetter, opts.xName || opts.xTitle), next && Y(next.y) >= Y(lowX.y) ? -12 : 18); + } + } + host.appendChild(svg); + return { frontier: front }; + } + + /** + * Values in training order {id, name, y, best, kind, rows}: the values as a + * line of points, the best so far as a step line in the good colour. + */ + function progression(host, points, opts) { + host.textContent = ''; host.classList.add('chart'); host._tip = null; + const W = Math.max(360, opts.width), H = opts.height || 240, L = 64, R = 20, T = 22, B = 36, n = points.length; + const ya = axis(points.map(p => p.y).concat(points.map(p => p.best))); + const X = i => L + (n > 1 ? i / (n - 1) : 0.5) * (W - L - R), Y = v => T + (1 - ya.at(v)) * (H - T - B); + const svg = frame(W, H, axisWords(opts.yTitle, ya) + ' for ' + n + ' subjects in training order, with the best so far'); + yGrid(svg, ya, Y, L, R, W); + const ax = el('g', { class: 'axis' }); + ax.appendChild(el('line', { x1: L, y1: H - B, x2: W - R, y2: H - B, class: 'base' })); + const every = Math.max(1, Math.ceil(n / Math.max(1, Math.floor((W - L - R) / 90)))); + points.forEach((p, i) => { if (i % every === 0 || i === n - 1) { const t = p.short.length > 12 ? p.short.slice(0, 11) + '…' : p.short; ax.appendChild(el('text', { x: X(i), y: H - B + 16, 'text-anchor': n === 1 ? 'middle' : i === 0 ? 'start' : i === n - 1 ? 'end' : 'middle' }, t)); } }); + ax.appendChild(el('text', { x: L, y: T - 8, class: 'label' }, axisWords(opts.yTitle, ya))); + ax.appendChild(el('text', { x: W - R, y: H - 4, 'text-anchor': 'end', class: 'label' }, 'training order')); + svg.appendChild(ax); + if (n > 1) { + svg.appendChild(el('path', { class: 'line', d: points.map((p, i) => (i ? 'L' : 'M') + X(i).toFixed(1) + ',' + Y(p.y).toFixed(1)).join(' ') })); + svg.appendChild(el('path', { class: 'best', d: points.map((p, i) => (i ? 'H' + X(i).toFixed(1) + 'V' : 'M' + X(i).toFixed(1) + ',') + Y(p.best).toFixed(1)).join(' ') })); + } + points.forEach((p, i) => { + const g = el('g'), cx = X(i), cy = Y(p.y); + const hit = el('circle', { cx, cy, r: Math.max(6, Math.min(11, (W - L - R) / Math.max(1, n) / 2)), class: 'hit', tabindex: 0, role: 'button', 'data-id': p.id, 'aria-label': p.name + ', ' + opts.yTitle + ' ' + fmtSci(p.y) + ', best so far ' + fmtSci(p.best) }); + g.appendChild(hit); g.appendChild(el('circle', { cx, cy, r: n > 80 ? 3 : 4, class: 'pt ' + p.kind + (p.dim ? ' dim' : '') })); + if (p.id === opts.selected) g.appendChild(el('circle', { cx, cy, r: 8, class: 'sel' })); + interactive(hit, host, svg, () => [cx, cy], p.rows, opts.onSelect && (() => opts.onSelect(p.id))); + svg.appendChild(g); + }); + host.appendChild(svg); + } + + /** Subjects best first {id, name, y, kind, rows}: one row each, a dot on the value axis with a hairline from its start. */ + function ranking(host, points, opts) { + host.textContent = ''; host.classList.add('chart'); host._tip = null; + const n = points.length, RH = n > 60 ? 16 : 20, W = Math.max(360, opts.width), L = Math.min(260, Math.max(120, W * 0.24)), R = 64, T = 26, H = T + n * RH + 8; + const xa = axis(points.map(p => p.y)), X = v => L + xa.at(v) * (W - L - R); + const svg = frame(W, H, axisWords(opts.yTitle, xa) + ' for ' + n + ' subjects, best first'); + const grid = el('g', { class: 'grid' }), ax = el('g', { class: 'axis' }); + xa.ticks.forEach((v, i) => { grid.appendChild(el('line', { x1: X(v), y1: T - 4, x2: X(v), y2: H - 8 })); ax.appendChild(el('text', { x: X(v), y: T - 10, 'text-anchor': i === xa.ticks.length - 1 && xa.ticks.length > 1 ? 'end' : 'middle' }, xa.label(v))); }); + svg.appendChild(grid); svg.appendChild(ax); + points.forEach((p, i) => { + const cy = T + i * RH + RH / 2, cx = X(p.y), g = el('g'); + const max = Math.floor((L - 14) / 6.6), t = p.name.length > max ? p.name.slice(0, max - 1) + '…' : p.name; + g.appendChild(el('text', { x: L - 10, y: cy + 4, 'text-anchor': 'end', class: 'rk' + (p.id === opts.selected ? ' on' : '') }, t)); + g.appendChild(el('line', { x1: L, y1: cy, x2: cx, y2: cy, class: 'stem' })); + const hit = el('rect', { x: 0, y: cy - RH / 2, width: W, height: RH, class: 'hit band', tabindex: 0, role: 'button', 'data-id': p.id, 'aria-label': p.name + ', ' + opts.yTitle + ' ' + fmtSci(p.y) }); + g.insertBefore(hit, g.firstChild); + g.appendChild(el('circle', { cx, cy, r: 4.5, class: 'pt ' + p.kind + (p.dim ? ' dim' : '') })); + if (p.id === opts.selected) g.appendChild(el('circle', { cx, cy, r: 8, class: 'sel' })); + g.appendChild(el('text', { x: W - 4, y: cy + 4, 'text-anchor': 'end', class: 'rv' }, fmtSci(p.y))); + interactive(hit, host, svg, () => [cx, cy], p.rows, opts.onSelect && (() => opts.onSelect(p.id))); + svg.appendChild(g); + }); + host.appendChild(svg); + } + + /** One mark per case {label, value, reason}: a bar for a value, a hollow tick at the base for a missing one. */ + function strip(host, items, opts) { + host.textContent = ''; host.classList.add('chart', 'cases'); host._tip = null; + const W = Math.max(360, opts.width), H = opts.height || 96, L = 64, R = 12, T = 10, B = 14, n = items.length; + const ya = axis(items.map(c => c.value)) || axis([0, 1]), Y = v => T + (1 - ya.at(v)) * (H - T - B); + const svg = frame(W, H, opts.label + ', ' + n + ' cases'); + yGrid(svg, ya, Y, L, R, W); + const step = (W - L - R) / Math.max(1, n), bw = Math.max(1.5, Math.min(18, step - (step > 4 ? 2 : 0.5))), base = Y(ya.log ? ya.ticks[0] : 0); + svg.appendChild(el('line', { x1: L, y1: H - B, x2: W - R, y2: H - B, class: 'base' })); + items.forEach((c, i) => { + const x = L + i * step + (step - bw) / 2, g = el('g'); + const has = c.value != null && Number.isFinite(c.value), top = has ? Y(c.value) : H - B - 3; + const mark = has ? el('rect', { x, y: Math.min(top, base), width: bw, height: Math.max(1.5, Math.abs(base - top)), rx: Math.min(1.5, bw / 3), class: 'b' + (c.id === opts.selected ? ' sel' : '') }) + : el('rect', { x, y: H - B - 3, width: bw, height: 3, class: 'b none' }); + const hit = el('rect', { x: L + i * step, y: T, width: Math.max(step, 2), height: H - T - B, class: 'hit', tabindex: 0, role: 'button', 'aria-label': c.label + ', ' + (has ? fmtSci(c.value) : 'no value' + (c.reason ? ': ' + c.reason : '')) }); + g.appendChild(hit); g.appendChild(mark); + interactive(hit, host, svg, () => [x + bw / 2, top], () => [{ b: c.label }, has ? { v: fmtSci(c.value), l: opts.valueTitle } : { l: 'no value' + (c.reason ? ': ' + c.reason : '') }], opts.onSelect && (() => opts.onSelect(c.id))); + svg.appendChild(g); + }); + host.appendChild(svg); + } + + return { el, h, fmtSci, scale, tooltip, axis, scatter, progression, ranking, strip }; })(); diff --git a/static/project-workspace/screens.js b/static/project-workspace/screens.js index 3e7f6c56..968b6546 100644 --- a/static/project-workspace/screens.js +++ b/static/project-workspace/screens.js @@ -1,6 +1,6 @@ 'use strict'; // The screens, from the mockup's screens.js. A screen is one function -// (main, aside, state, act) that fills the main area, fills the drawer when it +// (main, aside, state, act, data) that fills the main area, fills the drawer when it // has something to show there, and returns whether the drawer is open. It // reads the project only through window.TuldokProject. Rule: the chrome holds // no project words; names, groups, metrics and text come from the project. @@ -203,9 +203,6 @@ window.LabScreens = (() => { return false; } - // ---- Tabs of the next slice ---------------------------------------------- - const notYet = label => (main, aside) => { main.textContent = ''; aside.textContent = ''; aside._for = null; main.appendChild(h('p', 'notyet', 'The ' + label + ' tab is not built yet.')); return false; }; - // ---- Theme toggle (system, light, dark) ----------------------------------- const theme = { init(btn) { @@ -217,5 +214,7 @@ window.LabScreens = (() => { } }; - return { map, overview, data: notYet('Data'), train: notYet('Train'), benchmarks: notYet('Benchmarks'), analysis: notYet('Analysis'), inspectorModel, needsList, icon, stateEl, theme }; + // The Data, Train, Benchmarks and Analysis screens are added by tabs.js, which builds with these parts. + const parts = { sect, cell, block, time, bytes, failure, modelState, graphFor }; + return { map, overview, inspectorModel, needsList, icon, stateEl, theme, parts }; })(); diff --git a/static/project-workspace/tabs.js b/static/project-workspace/tabs.js new file mode 100644 index 00000000..f3fe44e5 --- /dev/null +++ b/static/project-workspace/tabs.js @@ -0,0 +1,599 @@ +'use strict'; +// The Data, Train, Benchmarks and Analysis screens, from the mockup's +// screens.js, added to window.LabScreens. Each is a screen like the others +// (main, aside, state, act, data): it shows "Reading…" the first time, reads +// what it needs through window.TuldokProject, then builds its content off the +// page and swaps it in, so a re-render (a sort, a filter, the refresh while a +// build runs) keeps the scroll and the focus. Every one of them only reads; +// none draws a control that would change the project. Rule: the chrome holds +// no project words; titles, metrics and text come from the project. +(() => { + const S = window.LabScreens, P = window.TuldokProject, Tree = window.LabTree, C = window.LabCharts, h = C.h; + const { sect, cell, block, time, bytes, failure, modelState, graphFor } = S.parts; + const fmt = C.fmtSci; + const STATISTICS = ['median', 'mean', 'p10', 'p90', 'min', 'max']; + const plural = (n, one, many) => n.toLocaleString('en-GB') + ' ' + (n === 1 ? one : many || one + 's'); + const nameOfRef = ref => ref.slice(ref.indexOf('/') + 1); + const seconds = s => s == null ? '' : s < 1 ? '<1 s' : s < 90 ? Math.round(s) + ' s' : s < 5400 ? Math.round(s / 60) + ' min' : (s / 3600).toFixed(1) + ' h'; + const button = (cls, text, onClick) => { const b = h('button', cls, text); b.type = 'button'; if (onClick) b.addEventListener('click', onClick); return b; }; + const better = m => m.better === 'higher' ? 'higher is better' : m.better === 'lower' ? 'lower is better' : 'no better direction'; + const units = m => m.units && m.units !== '1' ? ' (' + m.units + ')' : ''; + + /** + * The pixel width the main area gives its content, for charts drawn before + * they are on the page: from the drawer's class, not the padding, which may + * be mid-transition. + */ + function contentWidth(main) { const left = parseFloat(getComputedStyle(main).paddingLeft) || 20; return Math.max(360, main.clientWidth - left - (main.classList.contains('with-drawer') ? Math.min(420, 0.92 * innerWidth) + 20 : left)); } + + /** + * Fills main from load() (a promise of what build reads): "Reading…" only + * when this view has not been painted, the content built off the page and + * swapped in when it is still the newest render of the same view; the + * focused control (by data-key) and its caret are given back. + */ + function paint(main, load, build) { + const view = main._view, mine = main._paint = (main._paint || 0) + 1; + if (main._painted !== view) { main.textContent = ''; main.appendChild(h('p', 'note', 'Reading…')); } + main.setAttribute('aria-busy', 'true'); + const done = () => { if (main._paint === mine) main.removeAttribute('aria-busy'); }; + load().then(value => { + done(); if (main._paint !== mine || main._view !== view) return; + const width = contentWidth(main), frag = document.createDocumentFragment(); + try { build(frag, value, width); } catch (error) { frag.textContent = ''; failure(frag, error); console.error(error); } + swap(main, frag); main._painted = view; + }, error => { + done(); if (main._paint !== mine || main._view !== view) return; + main.textContent = ''; failure(main, error); main._painted = view; + }); + } + function swap(main, frag) { + const active = document.activeElement, key = active && main.contains(active) && active.dataset ? active.dataset.key : null; + const caret = key && typeof active.selectionStart === 'number' ? active.selectionStart : null; + const top = main.scrollTop; + main.textContent = ''; main.appendChild(frag); main.scrollTop = top; + if (key) { const again = main.querySelector('[data-key="' + CSS.escape(key) + '"]'); if (again) { again.focus({ preventScroll: true }); if (caret !== null && again.setSelectionRange) again.setSelectionRange(caret, caret); } } + } + /** Fills the drawer from load() once per id; build(ins, value). */ + function drawer(aside, id, load, build) { + if (aside._for === id) return; + aside._for = id; aside.textContent = ''; + const note = h('p', 'note', 'Reading…'); aside.appendChild(note); + load().then(value => { if (aside._for !== id) return; aside.textContent = ''; const ins = h('div', 'inspector'); try { build(ins, value); } catch (error) { failure(ins, error); } aside.appendChild(ins); }, + error => { if (aside._for !== id) return; aside.textContent = ''; failure(aside, error); }); + } + const closeDrawer = aside => { aside.textContent = ''; aside._for = null; return false; }; + const setup = () => { const dl = h('dl', 'setup'); return { dl, put(k, v, cls) { dl.appendChild(h('dt', null, k)); const dd = h('dd', cls || null); if (typeof v === 'string') dd.textContent = v; else if (v) dd.appendChild(v); dl.appendChild(dd); } }; }; + const searchBox = (state, act, placeholder) => { const q = h('input'); q.type = 'search'; q.placeholder = placeholder; q.value = state.query || ''; q.dataset.key = 'search'; q.setAttribute('aria-label', placeholder); q.addEventListener('input', () => act.setQuery(q.value)); return q; }; + function kindChips(state, act, present) { + const kinds = P.KINDS.map(k => k.id).concat(present.includes(P.UNSET) ? [P.UNSET] : []); + const grp = h('div', 'grp'); grp.setAttribute('role', 'group'); grp.setAttribute('aria-label', 'Kind of change'); + for (const k of kinds) { const b = button('btn sm chip ' + k, P.kindLabel(k), () => act.toggleKind(k, kinds)); b.dataset.kind = k; b.dataset.key = 'kind-' + k; b.setAttribute('aria-pressed', String(!state.kinds || state.kinds.has(k))); grp.appendChild(b); } + return grp; + } + const toggle = (label, on, onClick, key) => { const b = button('btn sm', label, onClick); b.dataset.key = key; b.setAttribute('aria-pressed', String(!!on)); return b; }; + const select = (label, options, value, onChange, key) => { + const s = h('select'); s.setAttribute('aria-label', label); s.dataset.key = key; + for (const [v, t] of options) { const o = h('option', null, t); o.value = v; o.selected = v === value; s.appendChild(o); } + s.addEventListener('change', () => onChange(s.value)); return s; + }; + const wrapTable = t => { const d = h('div', 'tv-wrap'); d.appendChild(t); return d; }; + function headRow(cols) { const thead = h('thead'), tr = h('tr'); for (const [t, cls] of cols) tr.appendChild(h('th', cls || null, t)); thead.appendChild(tr); return thead; } + + // ---- Benchmarks: what is read -------------------------------------------- + async function allResults(name) { + const rows = []; let offset = 0; + for (;;) { const page = await P.read('results', { benchmark: name, group: '', offset, limit: 2000 }); rows.push(...page.rows); offset += page.rows.length; if (!page.rows.length || offset >= page.total) return rows; } + } + /** Each chart definition's benchmark and form, read once. */ + async function chartIndex() { + const defs = (await P.read('definitions', { kind: 'chart' })).definitions.filter(d => !d.removed); + return Promise.all(defs.map(async d => { const full = await P.read('definition', { reference: d.reference }); const doc = full.document || {}; return { reference: d.reference, title: d.title, benchmark: typeof doc.benchmark === 'string' ? nameOfRef(doc.benchmark) : null, form: doc.form }; })); + } + async function benchmarkList() { + const [overview, defs] = await Promise.all([P.read('results_overview'), P.read('definitions', { kind: 'benchmark' })]); + const titles = new Map(defs.definitions.map(d => [nameOfRef(d.reference), d])); + return overview.benchmarks.map(b => ({ ...b, title: titles.has(b.benchmark) ? titles.get(b.benchmark).title : b.benchmark, state: titles.has(b.benchmark) ? titles.get(b.benchmark).state : null })); + } + const pickBenchmark = (list, wanted) => (list.find(b => b.benchmark === wanted) || list.find(b => b.subjects_with_results > 0) || list[0] || null); + /** + * One benchmark as the tab shows it: its metrics, its subjects (each with + * the model of its recipe from the map, its values per metric for every + * statistic, and whether its summaries come from per-case values held + * here), and its charts' data. + */ + async function benchmarkView(name, mapShaped) { + const [def, rows, charts] = await Promise.all([P.read('definition', { reference: 'benchmarks/' + name }), allResults(name), chartIndex()]); + const doc = def.document || {}, metrics = (doc.metrics || []).map(m => ({ id: m.id, title: m.title || m.id, units: m.units, better: m.better || 'none' })); + const subjects = (doc.subjects || []).map(s => { + const model = s.recipe && mapShaped.byId.get(s.recipe) || null; + return { name: s.name, title: s.title || s.name, recipe: s.recipe || null, model, key: model ? model.id : 'subject:' + s.name, + short: model ? Tree.refName(model) : s.name, full: model ? Tree.nameOf(model) : s.title || s.name, kind: model ? model.kind : 'other', + group: model ? model.groupTitle || '' : '', values: {}, count: null, perCase: false }; + }); + const byName = new Map(subjects.map(s => [s.name, s])); + for (const r of rows) { const s = byName.get(r.subject); if (!s) continue; s.values[r.metric] = r; s.count = Math.max(s.count || 0, r.count); if (r.origin === 'values') s.perCase = true; } + const ORDER = ['tradeoff', 'progression', 'ranking', 'comparison']; // the mockup leads with accuracy against time + const mine = charts.filter(c => c.benchmark === name).sort((a, b) => ORDER.indexOf(a.form) - ORDER.indexOf(b.form) || a.title.localeCompare(b.title)); + const data = await Promise.all(mine.map(c => P.read('chart', { chart: c.reference }).then(r => ({ ...c, data: r.data }), error => ({ ...c, error })))); + return { name, title: def.title, description: doc.description || '', metrics, subjects, byName, byKey: new Map(subjects.map(s => [s.key, s])), charts: data, cases: doc.cases || null }; + } + const valueOf = (s, metric, stat) => { const r = s.values[metric]; return r && r.count > 0 && r[stat] != null ? r[stat] : null; }; + const visibleSubject = (state) => s => (!state.kinds || state.kinds.has(s.kind)) && (!state.query || [s.full, s.name, s.title, s.recipe].some(t => t && t.toLowerCase().includes(state.query.toLowerCase()))); + + // ---- Benchmarks: the screen ------------------------------------------------- + function benchmarks(main, aside, state, act, data) { + const sel = state.sel.benchmarks || null, ui = state.ui; + paint(main, async () => { const list = await benchmarkList(); const b = pickBenchmark(list, state.benchmark); return { list, view: b ? await benchmarkView(b.benchmark, data.map) : null, picked: b }; }, (frag, { list, view, picked }, width) => { + if (!view) { frag.appendChild(h('p', 'empty', 'This project defines no benchmark.')); return; } + const stat = STATISTICS.includes(ui.stat) ? ui.stat : 'median', cmp = state.cmp.filter(k => view.byKey.has(k)); + const bar = h('div', 'filters'); + bar.appendChild(select('Benchmark', list.map(b => [b.benchmark, b.title + ' · ' + plural(b.subjects_with_results, 'subject') + ' with results']), view.name, v => act.setBenchmark(v), 'benchmark')); + bar.appendChild(kindChips(state, act, view.subjects.map(s => s.kind))); + bar.appendChild(select('Statistic', STATISTICS.map(s => [s, s.charAt(0).toUpperCase() + s.slice(1)]), stat, v => act.setUI('stat', v), 'stat')); + if (view.charts.some(c => c.form === 'tradeoff')) bar.appendChild(toggle('Frontier only', ui.frontierOnly, () => act.setUI('frontierOnly', !ui.frontierOnly), 'frontier')); + bar.appendChild(toggle('With results only', ui.resultsOnly, () => act.setUI('resultsOnly', !ui.resultsOnly), 'results-only')); + bar.appendChild(toggle('Table view', ui.chartTables, () => act.setUI('chartTables', !ui.chartTables), 'tables')); + bar.appendChild(searchBox(state, act, 'Find a subject')); + frag.appendChild(bar); + // Coverage: how many subjects have a result here, so the smaller plotted counts are explained. + const every = view.subjects.filter(s => view.metrics.length && view.metrics.every(m => valueOf(s, m.id, stat) != null)).length; + const some = view.subjects.filter(s => view.metrics.some(m => valueOf(s, m.id, stat) != null)).length - every; + const none = view.subjects.length - every - some, perCase = view.subjects.filter(s => s.perCase).length; + const cov = h('div', 'coverage'); const add = (n, t) => { const sp = h('span'); sp.appendChild(h('b', null, n.toLocaleString('en-GB'))); sp.appendChild(document.createTextNode(' ' + t)); cov.appendChild(sp); }; + add(view.subjects.length, view.subjects.length === 1 ? 'subject' : 'subjects'); if (every) add(every, view.metrics.length === 1 ? 'with a result' : 'with every metric'); if (some) add(some, 'with some metrics'); if (none) add(none, 'with no result'); add(perCase, 'with per-case values on this machine'); + frag.appendChild(cov); + if (picked.differs_from_file) frag.appendChild(h('p', 'small muted bench-note', 'The results held here differ from the results file of this benchmark.')); + const show = visibleSubject(state), select_ = key => act.select(key === sel ? null : key); + // Charts, by their form. + if (!view.charts.length) frag.appendChild(h('p', 'empty bench-note', 'No chart is defined for this benchmark; every value is in the table below.')); + for (const c of view.charts) frag.appendChild(chartSection(c, view, { width, sel, onSelect: select_, show, frontierOnly: !!ui.frontierOnly, tables: !!ui.chartTables })); + // The compare set. + if (cmp.length) frag.appendChild(compareSection(view, cmp, stat, act)); + // Every subject. + frag.appendChild(subjectTable(view, state, act, stat, sel, cmp)); + }); + if (!sel) return closeDrawer(aside); + benchmarkDrawer(aside, sel, state, act, data); + return true; + } + /** The drawer of a selected subject: the model's drawer when it is made from a recipe of the map, with Compare. */ + function benchmarkDrawer(aside, sel, state, act, data) { + const isModel = data.map.byId.has(sel); + if (isModel) S.inspectorModel(aside, sel, act, data); + else if (aside._for !== sel) { + const name = sel.startsWith('subject:') ? sel.slice('subject:'.length) : sel; + drawer(aside, sel, async () => { const list = await benchmarkList(); const b = pickBenchmark(list, state.benchmark); return b ? benchmarkView(b.benchmark, data.map) : null; }, (ins, view) => { + const s = view && view.byName.get(name); + const hd = h('header'); hd.appendChild(h('span', 'kicker', 'benchmark subject · ' + name)); hd.appendChild(h('h2', null, s ? s.title : name)); ins.appendChild(hd); + if (!s) { ins.appendChild(h('p', 'empty', 'This benchmark has no subject ' + name + '.')); return; } + ins.appendChild(h('p', 'note', s.recipe ? 'Made from ' + s.recipe + ', which is not on the map.' : 'Not made from a recipe of this project.')); + const dl = h('dl', 'metrics'); for (const m of view.metrics) dl.appendChild(cell(m.title, fmt(valueOf(s, m.id, 'median')), m.units && m.units !== '1' ? m.units : '')); ins.appendChild(dl); + ins.appendChild(h('p', 'note', 'Medians over ' + (s.count == null ? 'no cases' : plural(s.count, 'case')) + ' of ' + view.title + '.')); + compareActs(ins, sel, state, act, false); + }); + } + const ins = aside.querySelector('.inspector'); if (ins) compareActs(ins, sel, state, act, isModel); + } + /** Compare, kept current on every render (a drawer is built once per selection). */ + function compareActs(ins, sel, state, act, isModel) { + const old = ins.querySelector('.bench-acts'); if (old) old.remove(); + const acts = h('div', 'actions bench-acts'), on = state.cmp.includes(sel); + const b = button('btn', on ? 'Remove from compare' : 'Compare', () => act.toggleCompare(sel)); b.disabled = !on && state.cmp.length >= 3; acts.appendChild(b); + if (isModel) acts.appendChild(button('btn ghost', 'On the map', () => act.go('map', sel))); + const head = ins.querySelector('header'); head.after(acts); + } + + /** One chart: its heading and population in words, the drawing by form (a panel per group value), and its table when asked. */ + function chartSection(c, view, o) { + const sec = h('section', 'bench-chart'); sec.dataset.chart = c.reference; + if (c.error) { sec.appendChild(sect(c.title)); failure(sec, c.error); return sec; } + const d = c.data, series = d.series || []; + const plotted = d.form === 'comparison' ? new Set(d.rows.map(r => r.subject)).size : new Set(series.flatMap(s => s.points.map(p => p.subject))).size; + const words = [plotted + ' of ' + plural(d.subject_count, 'subject') + ' drawn', d.statistic + ' over each subject\'s cases']; + if (d.form === 'tradeoff') words.push(series.reduce((n, s) => n + s.points.filter(p => p.frontier).length, 0) + ' on the frontier'); + if (d.missing.length) words.push(d.missing.length + ' without a value not drawn'); + sec.appendChild(sect(c.title, words.join(' · '))); + if (d.description) sec.appendChild(h('p', 'small muted bench-desc', d.description)); + const subjectOf = p => view.byName.get(p.subject); + const point = p => { const s = subjectOf(p); return { id: s ? s.key : 'subject:' + p.subject, name: s ? s.full : p.title, short: s ? s.short : p.subject, kind: s ? s.kind : 'other', dim: s ? !o.show(s) : false }; }; + const tipRows = (p, extra) => () => { const s = subjectOf(p); return [{ b: s ? s.full : p.title }, { v: fmt(p.value), l: d.metric.title + units(d.metric) }].concat(extra || []).concat([{ v: s && s.model ? P.kindLabel(s.kind) : 'not a model of the map', l: (p.count != null ? '· ' + plural(p.count, 'case') : '') }]); }; + const panels = series.length > 1 || d.group; + if (d.form === 'comparison') { sec.appendChild(comparisonTable(d, view, o)); return sec; } + if (!series.some(s => s.points.length)) { sec.appendChild(h('p', 'empty', 'No subject has a value for this chart yet.')); return sec; } + for (const s of series) { + const host = h('div'); host.dataset.series = s.group; + if (panels) sec.appendChild(h('h3', 'panel', d.group + ' = ' + s.group)); + if (!s.points.length) { sec.appendChild(h('p', 'empty', 'No subject has a value here.')); continue; } + sec.appendChild(host); + if (d.form === 'tradeoff') { + const pts = s.points.map(p => ({ ...point(p), x: p.x, y: p.value, frontier: p.frontier, rows: tipRows(p, [{ v: fmt(p.x), l: d.metric_x.title + units(d.metric_x) }, { l: p.frontier ? 'on the frontier' : '' }]) })); + C.scatter(host, pts, { width: o.width, height: 340, xTitle: d.metric_x.title + units(d.metric_x), yTitle: d.metric.title + units(d.metric), xName: d.metric_x.title, yName: d.metric.title, xBetter: d.metric_x.better, yBetter: d.metric.better, selected: o.sel, onSelect: o.onSelect, dimOff: o.frontierOnly }); + host.appendChild(legend(pts, 'Line: the frontier, where no other subject is at least as good on both and better on one')); + } else if (d.form === 'progression') { + const pts = s.points.map(p => ({ ...point(p), y: p.value, best: p.best_so_far, rows: tipRows(p, [{ v: fmt(p.best_so_far), l: 'best so far' }, { l: p.trained_at ? 'trained ' + P.day(p.trained_at) : 'no training date' }]) })); + C.progression(host, pts, { width: o.width, height: 240, yTitle: d.metric.title + units(d.metric), selected: o.sel, onSelect: o.onSelect }); + host.appendChild(legend(pts, 'Step line: the best so far, ' + better(d.metric))); + } else { + const pts = s.points.map(p => ({ ...point(p), y: p.value, rows: tipRows(p) })); + C.ranking(host, pts, { width: o.width, yTitle: d.metric.title + units(d.metric), selected: o.sel, onSelect: o.onSelect }); + host.appendChild(legend(pts, 'Best first, ' + better(d.metric))); + } + if (o.tables) sec.appendChild(pointsTable(d, s)); + } + return sec; + } + function legend(points, line) { + const ul = h('ul', 'legend'), kinds = new Set(points.map(p => p.kind)); + for (const k of P.KINDS.map(x => x.id).concat([P.UNSET, 'other'])) if (kinds.has(k)) ul.appendChild(h('li', 'chip ' + k, k === 'other' ? 'Not a model of the map' : P.kindLabel(k))); + ul.appendChild(h('li', null, line)); return ul; + } + /** The table view of one chart panel: every drawn value as text. */ + function pointsTable(d, s) { + const cols = [['Subject'], [d.metric.title + units(d.metric), 'n']]; + if (d.form === 'tradeoff') cols.push([d.metric_x.title + units(d.metric_x), 'n'], ['Frontier']); + if (d.form === 'progression') cols.push(['Best so far', 'n'], ['Trained']); + cols.push(['Cases', 'n']); + const t = h('table', 'tv pts'); t.setAttribute('aria-label', d.title + (s.group ? ', ' + d.group + ' = ' + s.group : '') + ', as a table'); t.appendChild(headRow(cols)); + const tb = h('tbody'); + for (const p of s.points) { + const tr = h('tr'); tr.appendChild(h('td', null, p.title)); tr.appendChild(h('td', 'n', fmt(p.value))); + if (d.form === 'tradeoff') { tr.appendChild(h('td', 'n', fmt(p.x))); tr.appendChild(h('td', null, p.frontier ? 'yes' : '')); } + if (d.form === 'progression') { tr.appendChild(h('td', 'n', fmt(p.best_so_far))); tr.appendChild(h('td', 'small faint nowrap', p.trained_at ? P.day(p.trained_at) : '—')); } + tr.appendChild(h('td', 'n', String(p.count))); tb.appendChild(tr); + } + t.appendChild(tb); return wrapTable(t); + } + /** A comparison chart: every metric per subject, the best of each column marked. */ + function comparisonTable(d, view, o) { + if (!d.rows.length) return h('p', 'empty', 'No subject has a value for this chart yet.'); + const best = {}; + for (const m of d.metrics) { const xs = d.rows.map(r => r.values[m.id]).filter(v => v != null); if (xs.length && m.better !== 'none') best[m.id] = m.better === 'higher' ? Math.max(...xs) : Math.min(...xs); } + const cols = [['Subject']].concat(d.group ? [[d.group]] : []).concat(d.metrics.map(m => [m.title + units(m), 'n'])); + const t = h('table', 'tv cmpgrid'); t.appendChild(headRow(cols)); const tb = h('tbody'); + for (const r of d.rows) { + const s = view.byName.get(r.subject), key = s ? s.key : 'subject:' + r.subject; + const tr = h('tr', 'rowbtn' + (key === o.sel ? ' is-sel' : '')); tr.tabIndex = 0; tr.dataset.key = 'cmpgrid-' + key + '-' + r.group; + tr.addEventListener('click', () => o.onSelect(key)); tr.addEventListener('keydown', e => { if (e.key === 'Enter') o.onSelect(key); }); + tr.appendChild(h('td', null, s ? s.full : r.title)); if (d.group) tr.appendChild(h('td', 'small faint', r.group)); + for (const m of d.metrics) { const v = r.values[m.id], td = h('td', 'n' + (v != null && v === best[m.id] ? ' best' : ''), fmt(v)); if (v != null && v === best[m.id]) td.title = 'Best of the column, ' + better(m); tr.appendChild(td); } + tb.appendChild(tr); + } + t.appendChild(tb); const w = wrapTable(t); + const foot = h('p', 'small faint bench-desc', 'Marked: the best value of each column.'); const box = h('div'); box.appendChild(w); box.appendChild(foot); return box; + } + /** Up to three subjects side by side: every metric, with the change from the first. */ + function compareSection(view, cmp, stat, act) { + const sec = h('section', 'bench-cmp'); sec.appendChild(sect('Compare', cmp.length + ' of 3')); + const list = cmp.map(k => view.byKey.get(k)); + const chips = h('div', 'cmp-chips'); + list.forEach((s, i) => { const c = h('span', 'c s' + (i + 1)); c.appendChild(h('i')); c.appendChild(document.createTextNode(s.full)); const x = button(null, '×', () => act.toggleCompare(s.key)); x.setAttribute('aria-label', 'Remove ' + s.full); c.appendChild(x); chips.appendChild(c); }); + chips.appendChild(button('btn sm ghost', 'Clear', () => act.clearCompare())); sec.appendChild(chips); + const t = h('table', 'tv cmpt'); t.appendChild(headRow([['']].concat(list.map(s => [s.full, 'n'])))); const tb = h('tbody'), base = list[0]; + for (const m of view.metrics) { + const tr = h('tr'); tr.appendChild(h('td', null, m.title + units(m) + ' · ' + stat)); + list.forEach((s, i) => { + const v = valueOf(s, m.id, stat), td = h('td', 'n', fmt(v)), b0 = valueOf(base, m.id, stat); + if (i > 0 && v != null && b0 != null && b0 !== 0) { const d = (v - b0) / Math.abs(b0), good = m.better === 'higher' ? d > 0 : m.better === 'lower' ? d < 0 : null; td.appendChild(h('span', 'd' + (d === 0 || good === null ? '' : good ? ' better' : ' worse'), ' ' + (d > 0 ? '+' : '') + (Math.abs(d) >= 10 ? (d * 100).toFixed(0) : (d * 100).toFixed(1)) + '%')); } + tr.appendChild(td); + }); + tb.appendChild(tr); + } + const cr = h('tr'); cr.appendChild(h('td', null, 'Cases')); list.forEach(s => cr.appendChild(h('td', 'n', s.count == null ? '—' : String(s.count)))); tb.appendChild(cr); + const vr = h('tr'); vr.appendChild(h('td', null, 'Per-case values here')); list.forEach(s => vr.appendChild(h('td', 'n', s.perCase ? 'yes' : 'no'))); tb.appendChild(vr); + t.appendChild(tb); sec.appendChild(wrapTable(t)); + sec.appendChild(h('p', 'small faint bench-desc', 'The change is from ' + base.full + '; it is coloured only for metrics with a better direction.')); + return sec; + } + /** Every subject of the benchmark, sortable by any column; a row opens the subject, its box adds it to the compare set. */ + function subjectTable(view, state, act, stat, sel, cmp) { + const sec = h('section', 'bench-all'), show = visibleSubject(state); + const rows = view.subjects.filter(s => show(s) && (!state.ui.resultsOnly || view.metrics.some(m => valueOf(s, m.id, stat) != null))); + const sort = state.ui.sort || { key: view.metrics.length ? 'm:' + view.metrics[0].id : 'full', dir: 1 }; + const keyOf = (s, k) => k === 'short' ? (s.model && s.model.short) || null : k === 'full' ? (s.model ? s.model.title : s.title) : k === 'kind' ? (s.model ? P.kindLabel(s.kind) : null) : k === 'group' ? s.group || null : k === 'count' ? s.count : k === 'perCase' ? (s.perCase ? 1 : null) : k.startsWith('m:') ? valueOf(s, k.slice(2), stat) : null; + const metricOf = k => k.startsWith('m:') ? view.metrics.find(m => m.id === k.slice(2)) : null; + const flip = (metricOf(sort.key) || {}).better === 'higher' ? -1 : 1; // a metric column sorts best first + rows.sort((a, b) => { const ka = keyOf(a, sort.key), kb = keyOf(b, sort.key); if (ka == null && kb == null) return a.full.localeCompare(b.full); if (ka == null) return 1; if (kb == null) return -1; return (typeof ka === 'number' ? (ka - kb) * flip : String(ka).localeCompare(String(kb))) * sort.dir; }); + sec.appendChild(sect('All subjects', rows.length + ' of ' + view.subjects.length + ' · ' + stat + ' of each metric')); + const cols = [['', 'cmp'], ['', 'short', 'ck'], ['Subject', 'full'], ['Kind', 'kind'], ['Group', 'group']].concat(view.metrics.map(m => [m.title + units(m), 'm:' + m.id, 'n'])).concat([['Cases', 'count', 'n'], ['Per case', 'perCase']]); + const t = h('table', 'tv all'), thead = h('thead'), tr = h('tr'); + for (const [label, key, cls] of cols) { + const th = h('th', cls === 'n' ? 'n' : null); + if (key === 'cmp') { th.appendChild(h('span', 'sr-only', 'Compare')); tr.appendChild(th); continue; } + const b = button(null, label || 'Short name', () => act.setUI('sort', sort.key === key ? { key, dir: -sort.dir } : { key, dir: 1 })); b.dataset.key = 'sort-' + key; + if (!label) { b.textContent = ''; b.appendChild(h('span', 'sr-only', 'Short name')); b.appendChild(document.createTextNode('#')); } + if (sort.key === key) { b.setAttribute('aria-sort', sort.dir > 0 ? 'ascending' : 'descending'); th.setAttribute('aria-sort', sort.dir > 0 ? 'ascending' : 'descending'); } + th.appendChild(b); tr.appendChild(th); + } + thead.appendChild(tr); t.appendChild(thead); + const tb = h('tbody'); + for (const s of rows) { + const row = h('tr', 'rowbtn' + (s.key === sel ? ' is-sel' : '')); row.dataset.subject = s.name; row.addEventListener('click', () => act.select(s.key === sel ? null : s.key)); + const tdc = h('td'), cb = h('input'); cb.type = 'checkbox'; cb.checked = cmp.includes(s.key); cb.disabled = !cb.checked && cmp.length >= 3; cb.dataset.key = 'cmp-' + s.key; cb.setAttribute('aria-label', 'Compare ' + s.full); + cb.addEventListener('click', ev => { ev.stopPropagation(); act.toggleCompare(s.key); }); tdc.appendChild(cb); row.appendChild(tdc); + row.appendChild(h('td', 'ck', s.model && s.model.short ? s.model.short : '')); + const nt = h('td'); const nb = button('linkish', s.model ? s.model.title : s.title, ev => { ev.stopPropagation(); act.select(s.key === sel ? null : s.key); }); nb.dataset.key = 'open-' + s.key; nt.appendChild(nb); row.appendChild(nt); + const kt = h('td'); kt.appendChild(s.model ? h('span', 'chip ' + s.kind, P.kindLabel(s.kind)) : h('span', 'small faint', 'not on the map')); row.appendChild(kt); + row.appendChild(h('td', 'small faint nowrap grp', s.group)); + for (const m of view.metrics) row.appendChild(h('td', 'n', valueOf(s, m.id, stat) == null ? '' : fmt(valueOf(s, m.id, stat)))); + row.appendChild(h('td', 'n', s.count == null ? '' : String(s.count))); row.appendChild(h('td', 'small faint', s.perCase ? 'held here' : '')); + tb.appendChild(row); + } + t.appendChild(tb); sec.appendChild(wrapTable(t)); + if (!rows.length) sec.appendChild(h('p', 'empty', 'No subject matches the filters.')); + return sec; + } + + // ---- Train -------------------------------------------------------------------- + const TO_BUILD = ['not-built', 'out-of-date', 'failed']; + const RUN_TONE = { succeeded: 'good', adopted: 'good', running: 'pending', queued: 'pending', failed: 'serious', 'timed-out': 'serious', 'over-disk': 'serious', unknown: 'warn', cancelled: 'neutral' }; + const REQUEST_TONE = { 'awaiting-approval': 'pending', queued: 'pending', running: 'pending', succeeded: 'good', failed: 'serious', cancelled: 'neutral', declined: 'neutral', expired: 'neutral' }; + const runState = st => S.stateEl(RUN_TONE[st] || 'neutral', st === 'timed-out' ? 'ran out of time' : st === 'over-disk' ? 'over its disk budget' : st); + const requestState = st => S.stateEl(REQUEST_TONE[st] || 'neutral', st === 'awaiting-approval' ? 'awaiting approval' : st); + const who = r => r && (r.label || r.kind) || 'someone'; + const covering = r => r.every ? 'everything buildable' : (r.targets || []).join(', ') || 'nothing named'; + function train(main, aside, state, act, data) { + const sel = state.sel.train || null; + paint(main, async () => { + const [recipes, runs, requests, envs] = await Promise.all([P.read('definitions', { kind: 'recipe' }), P.read('runs'), P.read('build_requests'), P.read('environments')]); + const running = runs.runs.filter(r => r.state === 'running'); + const progress = new Map(await Promise.all(running.map(r => P.call('progress', { run: r.id }).then(p => [r.id, p.event], () => [r.id, null])))); + return { recipes: recipes.definitions, runs: runs.runs, requests: requests.requests, envs: envs.environments, progress }; + }, (frag, { recipes, runs, requests, envs, progress }) => { + const g = graphFor(data.map), deviceOf = new Map(envs.map(e => [e.reference, e.device])); + // Models not built yet. + const todo = recipes.filter(d => !d.removed && TO_BUILD.includes(d.state)); + frag.appendChild(sect('To build', todo.length + ' of ' + plural(recipes.length, 'model'))); + if (!todo.length) frag.appendChild(h('p', 'empty', 'Every model is built, or cannot be rebuilt from its definition.')); + else { + const ul = h('ul', 'rows'); + for (const d of todo) { + const m = g.byId.get(d.reference), li = h('li'), b = button('row todo'); b.setAttribute('aria-pressed', String(d.reference === sel)); b.dataset.key = 'open-' + d.reference; + b.appendChild(modelState(d.state)); const t = h('span'); t.appendChild(h('span', 'title', m ? Tree.nameOf(m) : d.title)); t.appendChild(h('span', 'sub', m ? m.groupTitle + (m.description ? ' · ' + m.description : '') : d.reference)); b.appendChild(t); + b.appendChild(m ? h('span', 'chip ' + m.kind, P.kindLabel(m.kind)) : h('span')); + b.addEventListener('click', () => act.select(d.reference === sel ? null : d.reference)); li.appendChild(b); ul.appendChild(li); + } + frag.appendChild(ul); + } + // Build requests. + const rh = sect('Build requests', String(requests.length)); rh.classList.add('gap'); frag.appendChild(rh); + if (!requests.length) frag.appendChild(h('p', 'empty', 'Nobody has asked for a build of this project through Tuldok.')); + else { + const ul = h('ul', 'rows'); + for (const r of requests) { + const li = h('li'), key = 'request:' + r.id, b = button('row request'); b.setAttribute('aria-pressed', String(key === sel)); b.dataset.key = 'open-' + key; + b.appendChild(requestState(r.state)); const t = h('span'); t.appendChild(h('span', 'title', 'A build of ' + covering(r))); t.appendChild(h('span', 'sub', 'asked by ' + who(r.requested_by) + (r.scratch ? ' · from the code as it is' : '') + (r.problem ? ' · ' + r.problem : ''))); b.appendChild(t); + b.appendChild(h('span', 'sub num', time(r.requested_at))); + b.addEventListener('click', () => act.select(key === sel ? null : key)); li.appendChild(b); ul.appendChild(li); + } + frag.appendChild(ul); + } + // Runs, newest first. + const bar = h('div', 'filters gap'); bar.appendChild(searchBox(state, act, 'Find a run')); bar.appendChild(kindChips(state, act, g.nodes.map(m => m.kind))); + bar.appendChild(h('span', 'pop', plural(runs.length, 'run') + ' on this machine')); + frag.appendChild(bar); + const q = (state.query || '').toLowerCase(); + const shown = runs.filter(r => { const m = g.byId.get(r.reference); return (!state.kinds || (m && state.kinds.has(m.kind))) && (!q || [r.reference, r.subject, r.id, m && Tree.nameOf(m)].some(t => t && t.toLowerCase().includes(q))); }); + frag.appendChild(sect('Runs', shown.length + ' of ' + runs.length + ' · newest first')); + if (!runs.length) frag.appendChild(h('p', 'empty', 'Nothing has been built or adopted in this project on this machine.')); + else { + const ul = h('ul', 'rows'); + for (const r of shown) { + const m = g.byId.get(r.reference), li = h('li'), key = 'run:' + r.id, b = button('row run'); b.setAttribute('aria-pressed', String(key === sel)); b.dataset.key = 'open-' + key; b.dataset.run = r.id; + b.appendChild(h('span', 'ck', m ? Tree.refName(m) : nameOfRef(r.reference))); + const t = h('span'); t.appendChild(h('span', 'title', (m ? m.title : r.reference) + (r.subject ? ' · ' + r.subject : ''))); + const when = r.finished_at || r.started_at || r.queued_at, ev = progress.get(r.id); + if (r.state === 'running' && ev) { + const line = h('span', 'sub live'); const hair = h('span', 'hair'); const i = h('i'); i.style.width = Math.round(100 * ev.completed / Math.max(1, ev.total)) + '%'; hair.appendChild(i); line.appendChild(hair); + line.appendChild(document.createTextNode(ev.stage + ' ' + ev.completed + ' of ' + ev.total + Object.entries(ev.metrics).slice(0, 2).map(([k, v]) => ' · ' + k + ' ' + fmt(v)).join(''))); t.appendChild(line); + } else t.appendChild(h('span', 'sub', [r.state === 'running' ? 'started ' + time(r.started_at) + ' · no progress reported yet' : time(when), seconds(r.seconds), r.bytes != null ? bytes(r.bytes) : null, r.scratch ? 'from the code as it is' : null].filter(Boolean).join(' · '))); + b.appendChild(t); + b.appendChild(m ? h('span', 'chip ' + m.kind, P.kindLabel(m.kind)) : h('span', 'small faint', nameOfRef(r.reference).length ? r.reference.split('/')[0].replace(/s$/, '') : '')); + b.appendChild(h('span', 'sub', (r.environment && deviceOf.get(r.environment.reference)) || '—')); + b.appendChild(runState(r.state)); + b.addEventListener('click', () => act.select(key === sel ? null : key)); li.appendChild(b); ul.appendChild(li); + } + frag.appendChild(ul); + if (runs.length >= 100) frag.appendChild(h('p', 'note', 'The hundred newest runs are listed.')); + } + // Environments. + const eh = sect('Environments', String(envs.length)); eh.classList.add('gap'); frag.appendChild(eh); + if (!envs.length) frag.appendChild(h('p', 'empty', 'The project defines no environment.')); + else { + const ul = h('ul', 'rows'); + for (const e of envs) { + const li = h('li'), r = h('div', 'row env'); r.appendChild(modelState(e.state)); + const t = h('span'); t.appendChild(h('span', 'title', e.title)); + const asks = ['asks Python ' + (e.python || '—'), e.device, plural(Object.keys(e.packages || {}).length, 'package')].filter(Boolean).join(', '); + const found = e.found ? 'found Python ' + (e.found.python || '?') + ', ' + plural(Object.keys(e.found.packages || {}).length, 'package') : e.interpreter ? 'not checked' : 'no interpreter recorded here'; + t.appendChild(h('span', 'sub', asks + ' · ' + found + (e.checked_at ? ' · checked ' + P.day(e.checked_at) : ''))); + if (e.problems && e.problems.length) t.appendChild(h('span', 'sub warnline', e.problems.join(' '))); + r.appendChild(t); r.appendChild(h('span', 'sub mono', e.interpreter || '')); li.appendChild(r); ul.appendChild(li); + } + frag.appendChild(ul); + } + }); + if (!sel) return closeDrawer(aside); + if (sel.startsWith('run:')) runDrawer(aside, sel, act, data); + else if (sel.startsWith('request:')) requestDrawer(aside, sel, act, data); + else if (data.map.byId.has(sel)) S.inspectorModel(aside, sel, act, data); + else { aside.textContent = ''; aside._for = sel; aside.appendChild(h('p', 'empty', 'There is no ' + sel + ' here.')); } + return true; + } + const tail = (text, lines) => { const all = text.replace(/\n$/, '').split('\n'); return (all.length > lines ? '…\n' : '') + all.slice(-lines).join('\n'); }; + /** A definition's value in one line: a list of words as a command line, an object as key: value pairs. */ + const brief = v => v == null ? '—' : typeof v !== 'object' ? String(v) : Array.isArray(v) ? (v.every(x => typeof x === 'string') ? v.join(' ') : v.map(brief).join(', ')) : Object.entries(v).map(([k, x]) => k + ': ' + (x && typeof x === 'object' && !Array.isArray(x) ? '{' + brief(x) + '}' : brief(x))).join(', '); + const json = v => { if (typeof v === 'string') { try { v = JSON.parse(v); } catch (e) { return v; } } return brief(v); }; + function runDrawer(aside, key, act, data) { + const id = key.slice(4); + drawer(aside, key, () => Promise.all([P.read('run', { run: id }), P.call('progress', { run: id })]), (ins, [r, pr]) => { + const m = graphFor(data.map).byId.get(r.reference); + const hd = h('header'); hd.appendChild(h('span', 'kicker', 'run ' + r.id)); hd.appendChild(h('h2', null, (m ? Tree.nameOf(m) : r.reference) + (r.subject ? ' · ' + r.subject : ''))); + const meta = h('div', 'ins-meta'); if (m) meta.appendChild(h('span', 'chip ' + m.kind, P.kindLabel(m.kind))); meta.appendChild(runState(r.state)); if (r.scratch) meta.appendChild(h('span', 'small faint', 'from the code as it is')); hd.appendChild(meta); ins.appendChild(hd); + if (m) { const acts = h('div', 'actions'); acts.appendChild(button('btn sm ghost', 'On the map', () => act.go('map', m.id))); acts.appendChild(button('btn sm ghost', 'Its model', () => act.select(m.id))); ins.appendChild(acts); } + const su = setup(); + su.put('Definition', r.reference, 'mono'); + if (r.subject) su.put('Subject', r.subject); + su.put('Queued', time(r.queued_at)); su.put('Started', time(r.started_at)); su.put('Finished', time(r.finished_at)); + su.put('Took', r.seconds == null ? '—' : seconds(r.seconds)); if (r.exit_status != null) su.put('Exit status', String(r.exit_status)); + if (r.environment) su.put('Environment', r.environment.reference + (r.environment.found ? ' · Python ' + r.environment.found.python : '') + (r.environment.interpreter ? ' · ' + r.environment.interpreter : ''), 'mono'); + su.put('Commit', r.commit || '—', 'mono'); + su.put('Command', (r.argv || []).join(' ') || '—', 'mono cmdline'); + const inputs = Object.entries(r.inputs || {}); + su.put('Inputs', inputs.length ? inputs.map(([k, v]) => k + ' ← ' + (v.reference || '?') + (v.output ? ' (' + v.output + ')' : '') + (v.run_id ? ' · run ' + v.run_id.slice(0, 8) : '')).join('\n') : 'none', 'mono pre'); + if (r.settings != null) su.put('Settings', json(r.settings), 'mono'); + if (r.env_names && r.env_names.length) su.put('Variables', r.env_names.join(', ') + ' (values not shown)', 'mono'); + if (r.product) su.put('Product', r.product.directory + '\n' + Object.entries(r.product.outputs || {}).map(([k, v]) => k + ': ' + v.path + ' · ' + bytes(v.bytes)).join('\n') + (r.product.current ? '' : '\n(no longer current)') + (r.product.adopted ? '\n(adopted)' : ''), 'mono pre'); + else su.put('Product', 'none'); + if (r.bytes != null) su.put('Size', bytes(r.bytes)); + if (r.problem) su.put('Problem', r.problem); + ins.appendChild(su.dl); + if (pr.event) { const ev = pr.event; const p = h('p', 'small'); p.textContent = ev.stage + ': ' + ev.completed + ' of ' + ev.total + Object.entries(ev.metrics).map(([k, v]) => ' · ' + k + ' ' + fmt(v)).join(''); ins.appendChild(block('Latest progress', p)); } + for (const [name, title] of [['stdout', 'Standard output'], ['stderr', 'Standard error']]) { + const log = pr[name] || { text: '' }; + ins.appendChild(block(title + (log.size != null ? ' · ' + bytes(log.size) : ''), log.text ? h('pre', 'evtext', tail(log.text, 40)) : h('p', 'note', log.size == null ? 'No log on this machine.' : 'Empty.'))); + } + }); + } + function requestDrawer(aside, key, act, data) { + const id = key.slice(8); + drawer(aside, key, () => P.read('build_request', { request: id }), (ins, r) => { + const hd = h('header'); hd.appendChild(h('span', 'kicker', 'build request ' + r.id)); hd.appendChild(h('h2', null, 'A build of ' + covering(r))); + const meta = h('div', 'ins-meta'); meta.appendChild(requestState(r.state)); hd.appendChild(meta); ins.appendChild(hd); + const su = setup(); + su.put('Asked by', who(r.requested_by) + ' · ' + time(r.requested_at)); + if (r.decided_at) su.put('Decided by', who(r.decided_by) + ' · ' + time(r.decided_at)); + if (r.started_at) su.put('Started', time(r.started_at)); if (r.finished_at) su.put('Finished', time(r.finished_at)); + if (r.expires_at) su.put('Expires', time(r.expires_at)); + su.put('Code', r.scratch ? 'as it is, uncommitted changes included' : (r.covers && r.covers.commit ? 'commit ' + r.covers.commit : 'committed'), 'mono'); + if (r.problem) su.put('Problem', r.problem); + if (r.result) su.put('Result', json(r.result), 'mono'); + ins.appendChild(su.dl); + const steps = (r.covers && r.covers.steps) || []; + const ul = h('ul', 'links'); + for (const s of steps) { const m = data.map.byId.get(s.reference), li = h('li'); const b = button(null, m ? Tree.nameOf(m) : s.reference, m ? () => act.select(m.id) : null); if (!m) b.disabled = true; if (s.subjects && s.subjects.length) b.appendChild(h('span', 'why', 'subjects: ' + s.subjects.join(', '))); li.appendChild(b); ul.appendChild(li); } + ins.appendChild(block('What it covers · ' + plural(steps.length, 'step'), steps.length ? ul : h('p', 'note', 'Nothing.'))); + if (r.covers && r.covers.definitions) ins.appendChild(h('p', 'note', 'Approved as these ' + Object.keys(r.covers.definitions).length + ' definitions stand now: ' + Object.keys(r.covers.definitions).join(', ') + '.')); + const rl = h('ul', 'rows'); + for (const run of r.runs || []) { const li = h('li'), b = button('row'); b.style.gridTemplateColumns = 'minmax(0, 1fr) auto'; const t = h('span'); t.appendChild(h('span', 'title', run.reference + (run.subject ? ' · ' + run.subject : ''))); t.appendChild(h('span', 'sub', [time(run.finished_at || run.started_at || run.queued_at), seconds(run.seconds)].filter(Boolean).join(' · '))); b.appendChild(t); b.appendChild(runState(run.state)); b.addEventListener('click', () => act.select('run:' + run.id)); li.appendChild(b); rl.appendChild(li); } + ins.appendChild(block('Its runs', (r.runs || []).length ? rl : h('p', 'note', r.state === 'awaiting-approval' ? 'None: it has not been approved.' : 'None.'))); + }); + } + + // ---- Data ----------------------------------------------------------------------- + function data_(main, aside, state, act, data) { + const sel = state.sel.data || null; + paint(main, () => Promise.all([P.read('definitions', { kind: 'dataset' }), P.read('products'), P.read('graph')]), (frag, [defs, products, graph]) => { + const sets = defs.definitions.filter(d => !d.removed), byRef = new Map(); + for (const p of products.products) { if (!byRef.has(p.reference)) byRef.set(p.reference, []); byRef.get(p.reference).push(p); } + const users = new Map(); for (const e of graph.edges) { if (!users.has(e.to)) users.set(e.to, new Set()); users.get(e.to).add(e.from); } + const built = sets.filter(d => byRef.has(d.reference)).length, adopted = sets.filter(d => (byRef.get(d.reference) || []).some(p => p.adopted)).length; + const total = sets.reduce((n, d) => n + (byRef.get(d.reference) || []).reduce((a, p) => a + (p.bytes || 0), 0), 0); + frag.appendChild(sect('Datasets', sets.length + ' · ' + built + ' with files on this machine' + (adopted ? ', ' + adopted + ' adopted' : '') + (total ? ' · ' + bytes(total) : ''))); + if (!sets.length) { frag.appendChild(h('p', 'empty', 'The project defines no dataset.')); return; } + const grid = h('div', 'ds-grid'); + for (const d of sets) { + const ps = byRef.get(d.reference) || [], outputs = ps.flatMap(p => Object.entries(p.outputs || {}).map(([k, v]) => ({ name: k, ...v, directory: p.directory }))), size = ps.reduce((a, p) => a + (p.bytes || 0), 0); + const card = button('ds-card'); card.setAttribute('aria-pressed', String(d.reference === sel)); card.dataset.key = 'open-' + d.reference; card.dataset.ref = d.reference; + const pv = h('div', 'pv text'); pv.setAttribute('aria-hidden', 'true'); + // A product with no declared outputs is its directory as a whole. + const whole = !outputs.length && ps.length > 0; + pv.textContent = outputs.length ? outputs.slice(0, 4).map(o => o.path + ' ' + bytes(o.bytes)).join('\n') + (outputs.length > 4 ? '\n…' : '') : whole ? 'the whole directory ' + bytes(size) : 'no files on this machine'; + card.appendChild(pv); + const t = h('div', 't'); t.appendChild(h('div', 'title', d.title)); + const meta = h('div', 'meta'); meta.appendChild(h('span', null, outputs.length ? plural(outputs.length, 'output') + ' · ' + bytes(size) : whole ? 'a directory · ' + bytes(size) : 'no files here')); + const st = ps.some(p => p.adopted) ? S.stateEl('good', 'adopted') : modelState(d.state); st.classList.add('glyphs'); meta.appendChild(st); t.appendChild(meta); + const used = [...(users.get(d.reference) || [])].sort(); + t.appendChild(h('div', 'uses', used.length ? 'used by ' + used.length + ': ' + used.map(nameOfRef).join(', ') : 'used by nothing')); + t.appendChild(h('div', 'path', ps.length ? ps[0].directory : d.reference)); card.appendChild(t); + card.title = d.title; + card.addEventListener('click', () => act.select(d.reference === sel ? null : d.reference)); grid.appendChild(card); + } + frag.appendChild(grid); + }); + if (!sel) return closeDrawer(aside); + drawer(aside, sel, () => Promise.all([P.read('definition', { reference: sel }), P.read('products', { reference: sel })]), (ins, [d, p]) => { + const hd = h('header'); hd.appendChild(h('span', 'kicker', d.reference)); hd.appendChild(h('h2', null, d.title)); + const meta = h('div', 'ins-meta'); meta.appendChild(p.products.some(x => x.adopted) ? S.stateEl('good', 'adopted') : modelState(d.state)); if (d.unsaved) meta.appendChild(h('span', 'small faint', 'unsaved edit')); hd.appendChild(meta); ins.appendChild(hd); + const doc = d.document || {}; + ins.appendChild(block('Description', doc.description ? h('p', null, doc.description) : h('p', 'note', 'The definition has no description.'))); + const su = setup(); const skip = new Set(['format', 'kind', 'title', 'description']); + for (const [k, v] of Object.entries(doc)) { + if (skip.has(k)) continue; + if (v && typeof v === 'object' && !Array.isArray(v)) for (const [k2, v2] of Object.entries(v)) su.put(k + ' · ' + k2, brief(v2), 'mono'); + else su.put(k, brief(v), 'mono'); + } + ins.appendChild(block('Definition', su.dl.children.length ? su.dl : h('p', 'note', 'No other fields.'))); + const files = h('div'); + if (!p.products.length) files.appendChild(h('p', 'note', 'No files of this dataset on this machine.')); + for (const pr of p.products) { + const dl = setup(); dl.put('Folder', pr.directory, 'mono'); + for (const [k, o] of Object.entries(pr.outputs || {})) dl.put(k, pr.directory.replace(/\/$/, '') + '/' + o.path + ' · ' + bytes(o.bytes), 'mono'); + dl.put('Made', (pr.adopted ? 'adopted' : 'built') + ' · ' + time(pr.finished_at) + (pr.commit ? ' · ' + pr.commit.slice(0, 12) : '') + (pr.scratch ? ' · from the code as it is' : '')); + if (pr.subject) dl.put('Subject', pr.subject); + files.appendChild(dl.dl); + } + ins.appendChild(block('Files', files)); + const ul = h('ul', 'links'); + for (const u of d.used_by) { const m = data.map.byId.get(u.reference), li = h('li'); const b = button(null, m ? Tree.nameOf(m) : u.reference, m ? () => act.go('map', m.id) : null); b.appendChild(h('span', 'why', u.role)); if (!m) b.disabled = true; li.appendChild(b); ul.appendChild(li); } + ins.appendChild(block('Used by', d.used_by.length ? ul : h('p', 'note', 'Nothing uses it.'))); + }); + return true; + } + + // ---- Analysis: per-case values --------------------------------------------------- + const PAGE = 200; + function analysis(main, aside, state, act, data) { + const ui = state.ui, sel = state.sel.analysis || null; + paint(main, async () => { + const list = await benchmarkList(); + const b = list.find(x => x.benchmark === (ui.anaBench || state.benchmark)) || list.find(x => x.subjects_with_values > 0) || pickBenchmark(list, null); + if (!b) return { list }; + const view = await benchmarkView(b.benchmark, data.map); + const subject = view.byName.get(ui.anaSubject) || view.subjects.find(s => s.perCase) || view.subjects[0] || null; + const metric = view.metrics.find(m => m.id === ui.anaMetric) || view.metrics[0] || null; + const page = Math.max(0, ui.anaPage || 0); + const values = subject && metric ? await P.read('values', { benchmark: view.name, subject: subject.name, metric: metric.id, offset: page * PAGE, limit: PAGE }) : null; + return { list, b, view, subject, metric, page, values }; + }, (frag, { list, view, subject, metric, page, values }, width) => { + if (!view) { frag.appendChild(h('p', 'empty', 'This project defines no benchmark.')); return; } + const bar = h('div', 'viewer-bar'); + bar.appendChild(select('Benchmark', list.map(x => [x.benchmark, x.title + (x.subjects_with_values ? ' · ' + x.subjects_with_values + ' with per-case values' : '')]), view.name, v => { state.ui.anaSubject = null; state.ui.anaPage = 0; act.setUI('anaBench', v); }, 'ana-bench')); + if (view.subjects.length) bar.appendChild(select('Subject', view.subjects.map(s => [s.name, s.full + (s.perCase ? ' · per-case values' : '')]), subject.name, v => { state.ui.anaPage = 0; act.setUI('anaSubject', v); }, 'ana-subject')); + if (view.metrics.length) bar.appendChild(select('Metric', view.metrics.map(m => [m.id, m.title + units(m)]), metric.id, v => { state.ui.anaPage = 0; act.setUI('anaMetric', v); }, 'ana-metric')); + frag.appendChild(bar); + if (!subject || !metric) { frag.appendChild(h('p', 'empty', 'This benchmark has no ' + (subject ? 'metric' : 'subject') + '.')); return; } + if (!values.total) { + frag.appendChild(sect('Per case', metric.title + units(metric) + ' · ' + subject.full)); + const p = h('p', 'empty ana-none'); p.appendChild(document.createTextNode('This machine holds no per-case values of ' + subject.full + ' for ' + metric.title + ' on ' + view.title + '; its summaries are on the ')); + const a = h('a', null, 'Benchmarks tab'); a.href = '#benchmarks'; a.addEventListener('click', ev => { ev.preventDefault(); act.setBenchmark(view.name); act.go('benchmarks'); }); p.appendChild(a); p.appendChild(document.createTextNode('.')); frag.appendChild(p); return; + } + const rows = values.rows.map(r => ({ ...r, id: r.case + (r.group ? ' · ' + r.group : ''), label: r.case + (r.group ? ' · ' + r.group.replace(/;/g, ', ') : '') })); + const pages = Math.ceil(values.total / PAGE), first = page * PAGE + 1, last = page * PAGE + rows.length; + const sec = h('section'); sec.appendChild(sect('Per case', metric.title + units(metric) + ' · ' + subject.full + ' · ' + (pages > 1 ? first + '–' + last + ' of ' : '') + plural(values.total, 'value'))); + const xs = rows.map(r => r.value).filter(v => v != null), sorted = xs.slice().sort((a, b) => a - b); + const dl = h('dl', 'metrics ana-sum'); + const worst = !xs.length ? null : metric.better === 'higher' ? sorted[0] : sorted[sorted.length - 1]; + dl.appendChild(cell(pages > 1 ? 'Values on this page' : 'Values', String(xs.length))); + dl.appendChild(cell('Median', fmt(sorted.length ? sorted[Math.floor(sorted.length / 2)] : null))); + dl.appendChild(cell(metric.better === 'none' ? 'Largest' : 'Worst', fmt(metric.better === 'none' ? (sorted.length ? sorted[sorted.length - 1] : null) : worst))); + dl.appendChild(cell('Without a value', String(rows.length - xs.length))); + sec.appendChild(dl); + const host = h('div'); sec.appendChild(host); + C.strip(host, rows, { width, height: 110, label: metric.title + ' per case of ' + subject.full, valueTitle: metric.title + units(metric), selected: sel, onSelect: id => act.select(id === sel ? null : id) }); + sec.appendChild(h('p', 'small faint bench-desc', 'One mark per case' + (rows.some(r => r.group) ? ' and group' : '') + ', in the order of the cases; ' + better(metric) + '.' + (rows.length > xs.length ? ' A short hollow mark has no value.' : ''))); + if (pages > 1) { + const pg = h('div', 'pager'); + const pb = button('btn sm', 'Previous', () => act.setUI('anaPage', page - 1)); pb.disabled = page === 0; pb.dataset.key = 'prev'; + const nb = button('btn sm', 'Next', () => act.setUI('anaPage', page + 1)); nb.disabled = page + 1 >= pages; nb.dataset.key = 'next'; + pg.appendChild(pb); pg.appendChild(nb); pg.appendChild(h('span', null, 'page ' + (page + 1) + ' of ' + pages)); sec.appendChild(pg); + } + const t = h('table', 'tv cases-t'); t.appendChild(headRow([['Case'], ['Group'], [metric.title + units(metric), 'n'], ['Why no value']])); const tb = h('tbody'); + for (const r of rows) { const tr = h('tr', 'rowbtn' + (r.id === sel ? ' is-sel' : '')); tr.addEventListener('click', () => act.select(r.id === sel ? null : r.id)); tr.appendChild(h('td', 'ck', r.case)); tr.appendChild(h('td', 'small faint', r.group || '')); tr.appendChild(h('td', 'n', r.value == null ? '—' : fmt(r.value))); tr.appendChild(h('td', 'small faint', r.reason || '')); tb.appendChild(tr); } + t.appendChild(tb); sec.appendChild(wrapTable(t)); frag.appendChild(sec); + }); + return closeDrawer(aside); + } + + Object.assign(S, { benchmarks, train, data: data_, analysis }); +})(); diff --git a/tests/browser_project_workspace.cjs b/tests/browser_project_workspace.cjs index 248c4d23..cd1abafa 100644 --- a/tests/browser_project_workspace.cjs +++ b/tests/browser_project_workspace.cjs @@ -1,11 +1,17 @@ 'use strict'; -// The project workspace (docs/plans/definition-first-projects/spec-w2.md, slice T18) in a headless browser: -// Tuldok started with --project-folder on a copy of the minimal fixture, or with --lab-root on a real project -// folder (opened in place, read only: opening imports it into the disposable database named by -// TULDOK_DATABASE_URL). Signs in, opens every built tab in light and dark at 1440 by 900, opens a model and its -// card, hovers a map node, uses the kind and text filters, the track, the status strip and Needs you, and fails on -// any script error, failed request, sideways overflow or empty main area. Nothing may be asked of the project -// that changes it: its activity log stays empty and the fixture copy is unchanged byte for byte. +// The project workspace (docs/plans/definition-first-projects/spec-w2.md, slices T18 and T19) in a headless +// browser: Tuldok started with --project-folder on a copy of the minimal fixture, or with --lab-root on a real +// project folder (opened in place, read only: opening imports it into the disposable database named by +// TULDOK_DATABASE_URL). The fixture copy also gets the buildable fixture's definitions and stand-in commands +// (which finish in a second and train nothing), and before Tuldok starts the command line builds some of them, +// lets one fail, imports per-case values, and an agent asks for a build that waits for approval: so the Train, +// Data and Analysis tabs have runs, products, a request and values to show. +// Signs in, opens every tab in light and dark at 1440 by 900, opens a model and its card, hovers a map node, uses +// the kind and text filters, the track, the status strip and Needs you; on Benchmarks picks a benchmark, hovers +// and focuses a point, sorts the table and makes a compare set of two that the address keeps; opens a run and a +// build request on Train, a dataset on Data, picks a metric on Analysis; and fails on any script error, failed +// request, sideways overflow or empty main area. Nothing may be asked of the project that changes it: its +// activity log gains nothing while the page is open and the fixture copy is unchanged byte for byte. // node tests/browser_project_workspace.cjs [--lab-root ] const assert = require('node:assert/strict'), fs = require('node:fs'), os = require('node:os'), path = require('node:path'), crypto = require('node:crypto'); const { spawn, execFileSync } = require('node:child_process'), { once } = require('node:events'); @@ -21,7 +27,6 @@ if (fs.existsSync(path.join(venv, 'python'))) process.env.PATH = venv + path.del const python = fs.existsSync(path.join(venv, 'python')) ? path.join(venv, 'python') : 'python3'; const WIDTH = 1440, HEIGHT = 900; const TABS = ['map', 'data', 'train', 'benchmarks', 'analysis', 'overview']; -const BUILT = ['map', 'overview']; const temporary = fs.mkdtempSync(path.join(os.tmpdir(), 'tuldok-workspace-browser-')); const report = qaDirectory(root, labRoot ? 'project-workspace-lab' : 'project-workspace'); @@ -110,6 +115,127 @@ async function centre(selector) { } async function press(selector) { const { x, y } = await centre(selector); await mouse(x, y, true); } +/** Waits until neither the main area nor the drawer is still reading. */ +async function settled(label) { + await until(() => evaluate(`(() => { const reading = e => [...e.querySelectorAll('.note')].some(n => n.textContent === 'Reading…'); return !reading(document.getElementById('main')) && !reading(document.getElementById('aside')) && !document.getElementById('main').hasAttribute('aria-busy'); })()`), label); + await pause(150); +} +async function choose(selector, value) { + await evaluate(`(() => { const s = document.querySelector(${JSON.stringify(selector)}); s.value = ${JSON.stringify(value)}; s.dispatchEvent(new Event('change')); })()`); + await settled('the choice ' + value); +} +async function tipShown() { return until(() => evaluate(`(() => { const t = [...document.querySelectorAll('#main .tip')].find(t => !t.hidden); return t && t.innerText; })()`), 'a chart tip'); } +async function drawerOpen() { await until(() => evaluate(`document.getElementById('drawer').classList.contains('open')`), 'the drawer'); await settled('the drawer filled'); assert.deepEqual(await evaluate(`[...document.querySelectorAll('#aside .failure')].map(e => e.textContent)`), [], 'The drawer reads without failure'); } +async function scrollTo(selector) { await evaluate(`(() => { const e = document.querySelector(${JSON.stringify(selector)}); const m = document.getElementById('main'); m.scrollTop += e.getBoundingClientRect().top - m.getBoundingClientRect().top - 8; })()`); } + +/** The Benchmarks, Train, Data and Analysis tabs, with what can be done on them, in both themes. */ +async function otherTabs(map) { + const overview = await api('results_overview'), charts = (await api('definitions', { kind: 'chart' })).definitions; + const chartBench = {}; + for (const c of charts) { const d = await api('definition', { reference: c.reference }); chartBench[c.reference] = { benchmark: String(d.document.benchmark).replace(/^benchmarks\//, ''), form: d.document.form }; } + // The benchmark with the most chart forms (the fixture's rollout has all four). + const forms = name => new Set(Object.values(chartBench).filter(c => c.benchmark === name).map(c => c.form)).size; + const bench = overview.benchmarks.slice().sort((a, b) => forms(b.benchmark) - forms(a.benchmark) || b.subjects_with_results - a.subjects_with_results)[0].benchmark; + const runs = (await api('runs')).runs, requests = (await api('build_requests')).requests, products = (await api('products')).products; + for (const theme of ['light', 'dark']) { + // Benchmarks: pick, hover and focus a point, sort, compare two, open one. + await open(theme, 'benchmarks'); await settled('benchmarks'); + await choose('#main select[data-key="benchmark"]', bench); + const drawn = await evaluate(`({ charts: document.querySelectorAll('#main .bench-chart').length, svgs: document.querySelectorAll('#main .bench-chart svg').length, rows: document.querySelectorAll('#main .bench-all tbody tr').length, coverage: document.querySelector('#main .coverage').innerText, heads: [...document.querySelectorAll('#main .bench-chart .sect')].map(e => e.innerText.replace(/\\n/g, ' ')) })`); + assert.equal(drawn.charts, Object.values(chartBench).filter(c => c.benchmark === bench).length, 'One section per chart of ' + bench); + assert.ok(drawn.rows > 0, 'The all-subjects table has rows'); + await inspect(theme + ' benchmarks ' + bench); await shot(theme + '-benchmarks-picked'); + for (let i = 1; i < Math.min(drawn.charts, 4); i++) { await scrollTo(`#main .bench-chart:nth-of-type(${i + 1})`); await shot(theme + '-benchmarks-chart-' + (i + 1)); } + await evaluate(`document.getElementById('main').scrollTop = 0`); + if (drawn.svgs) { + const hit = await evaluate(`(() => { const e = document.querySelector('#main .bench-chart .hit'); return e.getAttribute('aria-label'); })()`); + const { x, y } = await centre('#main .bench-chart .hit'); await mouse(x, y); + const tip = await tipShown(); assert.ok(tip.length > 0, 'The hovered point has a tip'); + await shot(theme + '-benchmarks-hover'); + await mouse(5, 5); + await evaluate(`document.querySelectorAll('#main .bench-chart .hit')[1]?.focus() ?? document.querySelector('#main .bench-chart .hit').focus()`); + const focused = await tipShown(); assert.ok(focused.length > 0, 'A focused point has a tip'); + await evaluate(`document.activeElement.blur()`); + check(theme + ' Benchmarks ' + bench + ': ' + drawn.charts + ' charts (' + drawn.heads.join(' | ') + '); "' + drawn.coverage.replace(/\n/g, ' ') + '"; hovered "' + hit + '" and focused a point, each with a tip'); + } else check(theme + ' Benchmarks ' + bench + ': no chart drawn; "' + drawn.coverage.replace(/\n/g, ' ') + '"'); + // Sort by subject, then the other way. + await press('#main .bench-all th button[data-key="sort-full"]'); await settled('sorted'); + const names = async () => evaluate(`[...document.querySelectorAll('#main .bench-all tbody td:nth-child(3)')].map(e => e.textContent)`); + const up = await names(); assert.deepEqual(up, up.slice().sort((a, b) => a.localeCompare(b)), 'Sorted by subject'); + assert.equal(await evaluate(`document.querySelector('#main .bench-all th button[data-key="sort-full"]').getAttribute('aria-sort')`), 'ascending'); + await press('#main .bench-all th button[data-key="sort-full"]'); await settled('sorted back'); + assert.deepEqual(await names(), up.slice().reverse(), 'Sorted by subject, descending'); + await scrollTo('#main .bench-all'); await shot(theme + '-benchmarks-sorted'); + // A compare set of two, kept by the address. + await press('#main .bench-all tbody tr:nth-child(1) input[type="checkbox"]'); await settled('compare one'); + await press('#main .bench-all tbody tr:nth-child(2) input[type="checkbox"]'); await settled('compare two'); + const cmp = await evaluate(`({ chips: document.querySelectorAll('#main .bench-cmp .cmp-chips .c').length, cols: document.querySelectorAll('#main .bench-cmp thead th').length, search: location.search })`); + assert.equal(cmp.chips, 2); assert.equal(cmp.cols, 3); assert.match(cmp.search, /[?&]cmp=[^&,]+,[^&,]+/); assert.match(cmp.search, new RegExp('[?&]benchmark=' + bench)); + await scrollTo('#main .bench-cmp'); await inspect(theme + ' benchmarks compare'); await shot(theme + '-benchmarks-compare'); + // Open a subject in the drawer. + await press('#main .bench-all tbody tr:nth-child(1) .linkish'); await drawerOpen(); + const opened = await evaluate(`({ title: document.querySelector('#aside h2').textContent, compare: !!document.querySelector('#aside .bench-acts'), hash: location.hash })`); + assert.ok(opened.compare, 'The drawer offers Compare'); + await inspect(theme + ' benchmarks drawer'); await shot(theme + '-benchmarks-drawer'); + // The address alone gives the same compare set. + const shared = origin + '/' + cmp.search + '#benchmarks'; + await send('Page.navigate', { url: shared }); await until(() => evaluate(`!!document.querySelector('#main .bench-cmp')`), 'the shared compare set'); + assert.equal(await evaluate(`document.querySelectorAll('#main .bench-cmp .cmp-chips .c').length`), 2); + // The table view of the charts. + await settled('shared'); if (drawn.svgs) { await press('#main .filters button[data-key="tables"]'); await settled('tables'); assert.ok(await evaluate(`document.querySelectorAll('#main table.pts').length > 0`)); await scrollTo('#main table.pts'); await shot(theme + '-benchmarks-tables'); await inspect(theme + ' benchmarks tables'); await press('#main .filters button[data-key="tables"]'); } + check(theme + ' Benchmarks: table sorted both ways, a compare set of two (' + cmp.search + ') that the address restores, ' + opened.title + ' opened in the drawer (' + opened.hash + ')'); + + // Train: open a run and a build request. + await open(theme, 'train'); await settled('train'); + const train = await evaluate(`({ runs: document.querySelectorAll('#main .row.run').length, requests: document.querySelectorAll('#main .row.request').length, todo: document.querySelectorAll('#main .row.todo').length, envs: document.querySelectorAll('#main .row.env').length, text: document.getElementById('main').innerText })`); + assert.equal(train.runs, Math.min(100, runs.length)); assert.equal(train.requests, requests.length); + let trained = theme + ' Train: ' + train.todo + ' to build, ' + train.requests + ' build requests, ' + train.runs + ' runs, ' + train.envs + ' environments'; + if (runs.length) { + const run = runs.find(r => r.state === 'failed') || runs[0]; + await press(`#main .row.run[data-run="${run.id}"]`); await drawerOpen(); + const shown = await evaluate(`({ blocks: [...document.querySelectorAll('#aside h3')].map(e => e.textContent), command: [...document.querySelectorAll('#aside .setup dt')].some(e => e.textContent === 'Command'), logs: [...document.querySelectorAll('#aside pre.evtext')].map(e => e.textContent.length) })`); + assert.ok(shown.command, 'The run shows its command'); assert.ok(shown.blocks.some(b => b.startsWith('Standard error')), 'The run shows its logs'); + await inspect(theme + ' train run'); await shot(theme + '-train-run'); + trained += '; run ' + run.id.slice(0, 8) + ' (' + run.state + ') opened: ' + shown.blocks.join(', '); + } + if (requests.length) { + await press('#main .row.request'); await drawerOpen(); + const req = await evaluate(`({ title: document.querySelector('#aside h2').textContent, buttons: [...document.querySelectorAll('#aside button')].map(b => b.textContent) })`); + assert.ok(!req.buttons.some(t => /approve|decline|cancel/i.test(t)), 'No control that changes the project: ' + req.buttons.join(', ')); + await shot(theme + '-train-request'); + trained += '; request opened: ' + req.title; + } else await shot(theme + '-train-empty'); + check(trained); + + // Data: open a dataset (one with files when there is one). + await open(theme, 'data'); await settled('data'); + const withFiles = products.find(p => p.reference.startsWith('datasets/')); + const pick = withFiles ? withFiles.reference : await evaluate(`document.querySelector('#main .ds-card').dataset.ref`); + await press(`#main .ds-card[data-ref="${pick}"]`); await drawerOpen(); + const ds = await evaluate(`({ cards: document.querySelectorAll('#main .ds-card').length, blocks: [...document.querySelectorAll('#aside h3')].map(e => e.textContent), files: [...document.querySelectorAll('#aside .setup dd.mono')].map(e => e.textContent).filter(t => t.includes('/')).length })`); + assert.deepEqual(ds.blocks.slice(0, 4), ['Description', 'Definition', 'Files', 'Used by']); + if (withFiles) assert.ok(ds.files > 0, 'The dataset shows its files\' paths'); + await inspect(theme + ' data drawer'); await shot(theme + '-data-dataset'); + check(theme + ' Data: ' + ds.cards + ' cards; ' + pick + ' opened with ' + ds.files + ' paths'); + + // Analysis: pick a metric; hover a case when there are values. + await open(theme, 'analysis'); await settled('analysis'); + const metrics = await evaluate(`[...document.querySelectorAll('#main select[data-key="ana-metric"] option')].map(o => o.value)`); + if (metrics.length > 1) await choose('#main select[data-key="ana-metric"]', metrics[1]); + const ana = await evaluate(`({ marks: document.querySelectorAll('#main .cases .b').length, rows: document.querySelectorAll('#main table.cases-t tbody tr').length, none: document.querySelector('#main .ana-none')?.innerText || '' })`); + if (ana.marks) { + assert.equal(ana.marks, ana.rows); + const { x, y } = await centre('#main .cases .hit'); await mouse(x, y); const tip = await tipShown(); + await inspect(theme + ' analysis'); await shot(theme + '-analysis-metric'); + check(theme + ' Analysis: metric ' + (metrics[1] || metrics[0]) + ', ' + ana.marks + ' cases, a hovered case reads "' + tip.replace(/\n/g, ' ') + '"'); + } else { + assert.ok(ana.none.length > 0, 'Without per-case values a sentence says so'); + await inspect(theme + ' analysis'); await shot(theme + '-analysis-metric'); + check(theme + ' Analysis: no per-case values: "' + ana.none + '"'); + } + } +} + (async () => { let folder; if (labRoot) folder = labRoot; @@ -118,17 +244,35 @@ async function press(selector) { const { x, y } = await centre(selector); await folder = path.join(temporary, 'fixture', 'project'); // One more model with no group, no kind of change, no training date and no result, to show each absence. fs.writeFileSync(path.join(folder, 'recipes', 'loose.json'), JSON.stringify({ format: 'tuldok_definition_v1', kind: 'recipe', title: 'A recipe with nothing set', description: 'Neither grouped, nor kinded, nor dated, nor measured.', earlier_work: { rebuild: 'no', reason: 'A browser check fixture.' }, model: 'models/stepper' }, null, 2) + '\n'); + // The buildable fixture's definitions and stand-in commands, beside the minimal fixture's (no name is shared). + const buildable = path.join(root, 'tests', 'fixtures', 'tuldok_project', 'buildable'); + for (const kind of ['environments', 'datasets', 'recipes', 'benchmarks', 'charts']) for (const name of fs.readdirSync(path.join(buildable, 'project', kind))) fs.copyFileSync(path.join(buildable, 'project', kind, name), path.join(folder, kind, name)); + for (const name of fs.readdirSync(path.join(buildable, 'code'))) fs.cpSync(path.join(buildable, 'code', name), path.join(temporary, 'fixture', 'code', name), { recursive: true }); + const git = ['-c', 'user.name=Tuldok Test', '-c', 'user.email=test@example.invalid', '-c', 'commit.gpgsign=false', '-c', 'init.defaultBranch=main', '-C', path.join(temporary, 'fixture')]; + execFileSync('git', [...git, 'init', '-q']); execFileSync('git', [...git, 'add', '-A']); execFileSync('git', [...git, 'commit', '-q', '-m', 'The fixture.']); } - const before = labRoot ? null : snapshot(folder); const home = path.join(temporary, 'home'), catalog = path.join(temporary, 'catalog'); fs.mkdirSync(home); owned = [folder, catalog]; dropOwned(folder, catalog); + if (!labRoot) { // runs, products, a failed run, per-case values and a request awaiting approval, before Tuldok starts + const cli = (...args) => execFileSync(python, ['-m', 'tuldok_project', ...args], { cwd: root, env: { ...process.env, TULDOK_PROJECT_HOME: home }, stdio: ['ignore', 'pipe', 'pipe'] }).toString(); + cli('connect', folder, 'test-python', python); + cli('build', folder, 'datasets/numbers', 'recipes/fit-a', 'benchmarks/score', '--yes'); + try { cli('build', folder, 'recipes/fit-b', '--yes', '--env', 'BUILDABLE_FAIL=train'); assert.fail('The build of recipes/fit-b was to fail'); } catch (error) { if (error.code === 'ERR_ASSERTION') throw error; } + cli('import-values', folder, ...fs.readdirSync(path.join(temporary, 'fixture', 'values')).map(name => path.join(temporary, 'fixture', 'values', name))); + execFileSync(python, ['-c', `import sys +from tuldok_project import service +agent = {'actor_id': 'agent-browser-check', 'kind': 'agent', 'label': 'A browser check agent', 'scopes': ['inspect', 'execute']} +assert service.Service(sys.argv[1]).call('request_build', {'targets': ['recipes/fit-b']}, agent)['state'] == 'awaiting-approval' +`, folder], { cwd: root, env: { ...process.env, TULDOK_PROJECT_HOME: home }, stdio: ['ignore', 'pipe', 'pipe'] }); + } + const before = labRoot ? null : snapshot(folder); let output = ''; server = launch(python, ['-u', 'app.py', '--port', '0', '--data', catalog, '--project-folder', folder], { cwd: root, env: { ...process.env, TULDOK_PROJECT_HOME: home }, stdio: ['ignore', 'pipe', 'pipe'] }); server.stdout.on('data', chunk => { output += chunk; }); server.stderr.on('data', chunk => { serverErrors += chunk; }); const port = await until(() => { if (server.exitCode !== null) throw Error('Tuldok exited: ' + serverErrors); return output.match(/127\.0\.0\.1:(\d+)/)?.[1]; }, 'Tuldok start-up', 1800); origin = 'http://127.0.0.1:' + port; auth = authenticatedFixture(); await auth.register(origin, catalog, root); - const map = await api('map'), summary = await api('summary'); + const map = await api('map'), summary = await api('summary'), activityBefore = (await api('activity')).total; check('Tuldok serves ' + summary.name + ' with ' + map.models.length + ' models, ' + map.groups.length + ' groups, ' + map.edges.filter(e => e.kind === 'derived').length + ' derivations, ' + map.comparisons.length + ' comparisons and ' + map.models.filter(m => m.value != null).length + ' track values'); const browser = launch(findBrowser(), ['--headless', '--no-sandbox', '--disable-gpu', '--no-first-run', '--hide-scrollbars', '--remote-debugging-port=0', `--window-size=${WIDTH},${HEIGHT}`, '--user-data-dir=' + path.join(temporary, 'browser'), 'about:blank'], { stdio: 'ignore', env: { ...process.env, XDG_CONFIG_HOME: temporary, XDG_CACHE_HOME: temporary } }); @@ -154,7 +298,7 @@ async function press(selector) { const { x, y } = await centre(selector); await for (const name of TABS) { await tab(name); await inspect(theme + ' ' + name); - if (!BUILT.includes(name)) assert.match(await evaluate(`document.getElementById('main').innerText`), /is not built yet\.$/); + assert.doesNotMatch(await evaluate(`document.getElementById('main').innerText`), /is not built yet/); await shot(theme + '-' + name); if (name === 'map') { // the rest of a wide map, and the end of the list const wide = await evaluate(`(() => { const m = document.querySelector('.tree-map'); return m.scrollWidth > m.clientWidth + 10; })()`); @@ -165,7 +309,7 @@ async function press(selector) { const { x, y } = await centre(selector); await } } } - check('Every tab in ' + theme + ' at ' + WIDTH + ' by ' + HEIGHT + ': no overflow, no empty main area; the four tabs of the next slice say they are not built yet'); + check('Every tab in ' + theme + ' at ' + WIDTH + ' by ' + HEIGHT + ': no overflow, no empty main area'); } const fonts = await evaluate(`document.fonts.ready.then(() => [...document.fonts].filter(f => f.status === 'loaded').map(f => f.family + ' ' + f.style))`); assert.ok(fonts.some(f => /Ubuntu Sans"? normal/.test(f)) && fonts.some(f => /Ubuntu Sans Mono"? normal/.test(f)), 'The vendored faces load: ' + JSON.stringify(fonts)); @@ -274,11 +418,12 @@ async function press(selector) { const { x, y } = await centre(selector); await const frameBox = await evaluate(`(() => { const r = document.querySelector('iframe.report-frame').getBoundingClientRect(), b = document.querySelector('.report-bar').getBoundingClientRect(); return [Math.round(r.left), Math.round(r.top), Math.round(r.width), Math.round(r.height), Math.round(b.left), Math.round(b.top)]; })()`); check('The Overview links to the report, shown in a sandboxed frame at ' + frameBox.join(',')); + await otherTabs(map); const activity = await api('activity'); - assert.equal(activity.total, 0, 'Nothing was asked of the project: ' + JSON.stringify(activity.items)); + assert.equal(activity.total, activityBefore, 'Nothing was asked of the project while the page was open: ' + JSON.stringify(activity.items)); if (before) assert.deepEqual(snapshot(folder), before, 'The fixture copy is unchanged'); assert.deepEqual(errors, [], 'Script errors'); assert.deepEqual(failedRequests, [], 'Failed requests'); - check('No script error, no failed request, an empty activity log' + (before ? ', the folder unchanged' : '')); + check('No script error, no failed request, nothing added to the activity log (' + activityBefore + ' entries from the set-up)' + (before ? ', the folder unchanged' : '')); fs.writeFileSync(path.join(report, 'receipt.json'), JSON.stringify({ status: 'pass', folder, checks, bounds }, null, 2) + '\n'); console.log('Screenshots and receipt in ' + report); })().catch(async error => { @@ -292,5 +437,6 @@ async function press(selector) { const { x, y } = await centre(selector); await try { session?.close(); } catch (_) { /* closed */ } for (const child of children.reverse()) await stop(child); if (owned) try { dropOwned(...owned); } catch (error) { console.error('Dropping the disposable schemas failed:', error.message); process.exitCode = 1; } + try { execFileSync('chmod', ['-R', 'u+w', temporary]); } catch (_) { /* nothing was made read-only */ } // finished runs leave their directories read-only fs.rmSync(temporary, { recursive: true, force: true }); }); diff --git a/tests/test_tuldok_project_adoption.py b/tests/test_tuldok_project_adoption.py index 3821379d..31abe476 100644 --- a/tests/test_tuldok_project_adoption.py +++ b/tests/test_tuldok_project_adoption.py @@ -134,6 +134,9 @@ def whole(document): # use the dataset's directory as a whole self.assertEqual((entry['outputs'], entry['missing']), ({}, [])) total = self.numbers.stat().st_size + 7 self.assertEqual(self.runs('datasets/numbers')[0]['bytes'], total) + # The product of a definition with no declared outputs is the directory: its size is the run's. + listed = [item for item in self.products() if item['reference'] == 'datasets/numbers'] + self.assertEqual([item['bytes'] for item in listed], [total]) product = self.products('datasets/numbers')[0] self.assertEqual((product['outputs'], product['adopted']), ({}, True)) self.assertTrue((Path(entry['directory']) / 'any' / 'where' / 'notes.txt').is_file()) diff --git a/tests/test_tuldok_project_http.py b/tests/test_tuldok_project_http.py index 0d0e9cf3..53e96d21 100644 --- a/tests/test_tuldok_project_http.py +++ b/tests/test_tuldok_project_http.py @@ -47,6 +47,7 @@ '/project-workspace/markdown.js': 'text/javascript', '/project-workspace/tree.js': 'text/javascript', '/project-workspace/screens.js': 'text/javascript', + '/project-workspace/tabs.js': 'text/javascript', '/project-workspace/app.js': 'text/javascript', '/static/vendor/ubuntu-sans/UbuntuSans[wdth,wght].ttf': 'font/ttf', '/static/vendor/ubuntu-sans/UbuntuSans-Italic[wdth,wght].ttf': 'font/ttf', diff --git a/tuldok_project/builds.py b/tuldok_project/builds.py index d84b0068..0f1d2001 100644 --- a/tuldok_project/builds.py +++ b/tuldok_project/builds.py @@ -394,10 +394,10 @@ def runs(project, reference=None): def products(project, reference=None): - """The current products, by reference and subject: run, size of the declared outputs, directory, scratch, adopted.""" + """The current products, by reference and subject: run, size (of the declared outputs, or of the whole directory when none is declared), directory, scratch, adopted.""" reap_orphans(project._connection, project.schema) query = '''SELECT p.reference, p.subject, p.run_id, p.directory, p.outputs, r.scratch, r.commit, r.finished_at, - r.state + r.state, r.bytes FROM {schema}.products p JOIN {schema}.runs r ON r.id = p.run_id WHERE p.current''' parameters = () if reference is not None: @@ -405,10 +405,12 @@ def products(project, reference=None): parameters = (reference,) query += ' ORDER BY p.reference, p.subject' found = [] - for reference_, subject, run_id, directory, outputs, scratch, commit, finished, state in project._execute( + for reference_, subject, run_id, directory, outputs, scratch, commit, finished, state, run_bytes in project._execute( query, parameters).fetchall(): + # A product with no declared outputs is its directory as a whole: its size is what the run recorded. + size = sum(item.get('bytes') or 0 for item in outputs.values()) if outputs else (run_bytes or 0) found.append({'reference': reference_, 'subject': subject, 'run_id': run_id, 'directory': directory, - 'outputs': outputs, 'bytes': sum(item.get('bytes') or 0 for item in outputs.values()), + 'outputs': outputs, 'bytes': size, 'scratch': scratch, 'commit': commit, 'finished_at': finished, 'adopted': state == ADOPTED}) return found From fb97ea2005d6e035c50e8731cc16f4ec60be4f39 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 12 Nov 2026 12:33:21 -0700 Subject: [PATCH 045/131] docs(plan): record Map phase 2 in the ledger Co-Authored-By: Claude Fable 5.2 --- .../execution-ledger.md | 29 +++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/docs/plans/definition-first-projects/execution-ledger.md b/docs/plans/definition-first-projects/execution-ledger.md index 49726ddc..1ce1dbd2 100644 --- a/docs/plans/definition-first-projects/execution-ledger.md +++ b/docs/plans/definition-first-projects/execution-ledger.md @@ -430,3 +430,32 @@ The clone was not built: that needs the reference solver and the dataset generat **Starting values to correct.** Kinds, parents and short labels were carried from the mockup, which inferred kinds and parents from card text: 128 models have a short label, 43 a parent (36 from C53, 4 from C37, 3 from C44). The group "Pressure proposal fits" has no model of its own, only child groups. **Next:** phase 2, the page, read-only. + +## 2026-11-12 — the Map workspace, phase 2: the page, read-only + +Spec: [spec-w2.md](spec-w2.md). + +**Commits** (none pushed). Tuldok `feat/definition-first-projects`: spec `e7eae194`; the shell, the map, the drawer and Overview `1f66f5a0`; Benchmarks, Train, Data and Analysis `50e73ddb`. Lab `reorg/reproducible-lab-20261102`: descriptions that lead with each model's purpose `7774816a5`. + +| Slice | What | +| --- | --- | +| T18 | `static/project-workspace.html` and `static/project-workspace/` (the adapter, the shell, the map, the charts helper, a Markdown renderer, the Map and Overview screens), Ubuntu Sans vendored with its licence, `description` on each model of `map`, the stand-in report page removed, `tests/browser_project_workspace.cjs` | +| T19 | `static/project-workspace/tabs.js`: Benchmarks, Train, Data, Analysis; the charts by form; the browser check extended | +| L7 | each earlier recipe's description leads with the Purpose paragraph of its card (205 of 205 cards have one) | + +Tuldok project tests: 561, about 4 minutes. The browser check passes on its fixture and on the lab folder: every tab in light and dark at 1440 by 900, no script error, no failed request, no sideways overflow, nothing added to the activity log. + +**Reviewed against the mockup** on the lab's 206 models, screenshot by screenshot: the top bar and tabs, the status strip, the map with its sections, the lanes "from C37" and "from C44", the minimap and the track, the list with short label, title, purpose, kind and bar, and the drawer with the card rendered, in light and dark. + +**Changed in review:** + +- A product with no declared outputs reported a size of zero, so the lab's adopted dataset directories read as empty on the Data tab. `products` now gives the size the run recorded; on the owner's project the 25 adopted datasets show 15.67 GB. +- The label of the fastest end of the frontier was printed over the frontier line; it now sits on the side the line does not leave by. + +**Where the page differs from the mockup, on purpose:** no Layout switch; no control that changes anything (phase 3); the drawer's figures are the track metric, cases, benchmarks with results and state; the track scale fits the project's values; inputs are drawn only for the selected model; the Benchmarks picker chooses a benchmark where the mockup chose a population, and each chart definition is drawn by its own form; no studies, planned models, thumbnails, volume viewer or field slices. + +**Not verified:** the hairline and progress line of a run while it runs, and the two-second refresh during a build: no fixture has a running run with a progress event. They are checked in phase 3, whose acceptance runs a real build. + +**On the owner's machine.** A preview of the committed page runs from an export of the commit in `workspace/scratch/tuldok-preview` on port 8092, on the owner's database, catalog and project directory; the older page still runs on port 8091. + +**Next:** phase 3, acting from the page, after the owner has looked at phase 2. From b15c979d8de757cd3cf8147b0856f35f2ace6c3f Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 12 Nov 2026 14:09:24 -0700 Subject: [PATCH 046/131] docs(plan): spec for Map phase 3, acting from the page Co-Authored-By: Claude Fable 5.2 --- .../definition-first-projects/spec-w3.md | 97 +++++++++++++++++++ 1 file changed, 97 insertions(+) create mode 100644 docs/plans/definition-first-projects/spec-w3.md diff --git a/docs/plans/definition-first-projects/spec-w3.md b/docs/plans/definition-first-projects/spec-w3.md new file mode 100644 index 00000000..f3a82d49 --- /dev/null +++ b/docs/plans/definition-first-projects/spec-w3.md @@ -0,0 +1,97 @@ +# Implementation spec: the Map workspace, phase 3: acting from the page + +This is phase 3 of [the Map workspace plan](workspace-plan.md); [spec-w1.md](spec-w1.md) and [spec-w2.md](spec-w2.md) are phases 1 and 2. Section 1 of [spec-m1-m2.md](spec-m1-m2.md) (rules for implementers) applies, with the import rule as amended by [spec-m7.md](spec-m7.md). The reference for how things look is still the mockup, `docs/plans/project-workspace-redesign/mockups/` (`b-map.html`, `shared/screens.js`: `inspectorPlanned`, `inspectorPlannedRun`, the `steps` list, the `form` and `actions` styles), and its brief. + +**Done when:** on a copy of the tiny example, in a browser and with nothing typed in a terminal after Tuldok starts: a model is branched from the trained one, a setting of the branch is changed, it is kept, saved and its build planned and requested, the training runs on the GPU and its progress is seen on the page while it runs, and the new model appears on the map as built with a line from its parent; and a build an agent asked for is approved from the page and runs. + +## 1. Decisions + +- **Every control is one operation of the project.** After it answers, the page forgets what it can have changed and reads again. A refusal is shown where the control was pressed, in the server's words, with its problems listed under it. Nothing is retried on its own. +- **A control is drawn only for a session that may use it**, read from the signed-in identity's kind and scopes with the rules of `service._allowed`. Someone who may only inspect sees the page of phase 2. +- **Edits live in Tuldok until saved.** Keep stores an edit in the working copy as an unsaved edit; Save writes every unsaved edit to the project folder. The page writes nothing else to disk and never touches Git. The strip always says how many edits are unsaved. +- **No build is asked for without its plan on screen.** Request build is a button of the plan view, never of a row. +- **Costly or destructive controls take two presses in place:** the button becomes "Confirm" with what will happen in words, beside "Back". This applies to cancelling a build or a run, stopping what a run left behind, discarding an edit, removing a definition, disconnecting an environment and taking the files in a conflict. No `window.confirm`, `alert` or `prompt`. +- **A branch is a draft in the page until it is kept.** Tuldok stores only definitions that check, and a branch of an earlier model often does not check yet (its code is lost). The draft is drawn on the map from the moment it is made and survives a reload (`sessionStorage`, keyed by the project's id). +- **Not in this phase:** studies and trials; target metric and threshold; attempts; anything that changes code or Git; running a benchmark for one model from the Benchmarks tab; annotation and the viewers. + +## 2. Additions to the core + +Two operations of the `project_folder` profile and two additions to `map`. + +**`draft_branch`**, for `inspect`, not a mutation. Arguments: `recipe` (a reference), `title` (1 to 200 characters), and optional `name`, `change` (one of the four kinds) and `description` (at most 4,000 characters). Result: `reference`, `text`, `parent`, `inlined`, `problems`. It stores nothing. + +- `reference` is `recipes/`. A given `name` must fit the format's name rule and be free (a removed definition's name is not free): otherwise `invalid`. Without `name` it is made from the title: lowercase, each run of characters outside `[a-z0-9]` becomes one `-`, trimmed of `-` at both ends and to 80 characters (`recipe` when nothing is left), then `-2`, `-3` and so on until it is free. +- `text` is a recipe written from the parent's document as it is in the working copy: `format`, `kind`, `title`, `description` when given, the parent's `model` and `group` when it has them, `change` (the argument, else the parent's), `derived_from` naming the parent, and the parent's `run` when it has one. Not carried over: `card`, `labels`, `earlier_work`, `compared_with`. It is JSON with the indentation of the parent's text (two spaces when the parent's has none) and ends with a newline. +- When the parent's `run` has `settings_file` and that file, read from the code root as it is on disk, is a JSON object of at most 256 KiB, the branch carries its content as `settings` in place of `settings_file`, and `inlined` is the file's path; otherwise `inlined` is null and `run` is carried as it is. +- `problems` is what `set_definition` would say of `text` at `reference`, errors and warnings, as a list of problems. A branch of a model without `run`, or whose code paths are missing, is returned with those errors for the caller to fix. +- A `recipe` that is no recipe of the project (or is removed) is refused `not-found`. + +**`revert_definition`**, for `edit`, a mutation. Argument `reference`. Result `{reference, dropped}`. For a definition that has an unsaved edit or is marked removed: when the folder holds its file, the file's text takes the edit's place and the definition is neither unsaved nor removed, checked as `set_definition` checks (a file that no longer checks is refused `invalid` with its problems, nothing changed); when the folder holds no file for it, it is dropped as `remove_definition` drops one that was never saved, refused `in-use` while anything uses it, and `dropped` is true. A definition with neither an unsaved edit nor the removed mark is refused `nothing-to-revert`. + +**`map`:** each model gains `unsaved` (whether its definition has an unsaved edit). A model's `trained_at` is its label, and without the label the time the run of its current product finished (null when it has no product or the product was adopted). + +**Command line:** `branch FOLDER RECIPE --title TITLE [--name NAME] [--change KIND] [--description TEXT] [--keep] [--json]` prints the draft's reference, its problems and its text; with `--keep` it stores the text as an unsaved edit when it has no error. `revert FOLDER REFERENCE` reverts. + +The contract document gains both operations, the `map` additions and the two commands. + +## 3. The page + +### 3.1 Builds (slice T21) + +| Where | What | +| --- | --- | +| Strip | When definitions are unsaved or marked removed: their count and **Save** (`save`). A save refused `changed-on-disk` shows the files and **Read the project again** | +| Needs you | Each item keeps its sentence and gains its controls. Awaiting approval: **Approve**, **Decline**, and a link to the request on Train. Unsaved edits: **Save**, and each named definition opens it. An environment not ready: **Check again** (`check_environment`), and a link to it on Train. A last run that ended badly: a link to the run, and **Plan build** | +| Plan view (drawer) | From `plan`, for one or more targets or everything buildable: the steps in order with what each would do (build, built already, blocked and why), how many use the GPU, disk and time (stated, estimated or unknown), the notes, and the targets that are blocked. A checkbox "Run from the code as it is on disk; the product is marked scratch". **Request build** (`request_build`). For an agent credential the button reads "Ask the owner for this build" | +| Train: to build | Each model not built, out of date or failed has **Plan build**; the section has **Plan everything buildable** | +| Train: a build request | Opening one reads `build_request`: who asked and when, what it covers (targets, the commit, scratch or not, how many definitions), its state with the problem or the reason when it has one, and its runs as links. Awaiting approval: **Approve** (`approve_build`), **Decline** with a reason of at most 400 characters (`decline_build`). Awaiting approval, queued or running: **Cancel** (`cancel_build`) | +| Train: a run | A queued or running run has **Cancel run** (`cancel_run`). A run still marked running whose builder is gone has **Stop what it left running** (`stop_run`). A running run shows its progress hairline, its latest progress line and the last lines of its two logs, read on with the offsets `progress` returns while it runs | +| Train: an environment | **Check again**; for the owner a field for an interpreter's absolute path with **Connect** (`connect_environment`), and **Disconnect** on a connected one | +| A model's drawer (Map) | **Plan build** when the model is not built, out of date or failed | +| Conflict | When a read is refused `conflict`, the main area shows the server's sentence, the definitions named, and **Keep my edits** and **Take the files** (`resolve_conflict` with `keep` or `discard`); then everything is read again | + +While a build request is queued or running the page asks again every two seconds, as in phase 2, and now also for the open run's progress and logs and for `map` when a run ends, so a model turns to built without a reload. + +### 3.2 Editing and branching (slice T22) + +**The editor** opens in the drawer from **Edit** on any definition the page shows: a model on the Map, a dataset on Data, and every definition from a new list on Overview (by kind: name, title, state, an unsaved mark). It has two views of one text: + +- **Text**, for every kind: the definition's JSON in a monospace field. +- **Form**, for a recipe: title; short label (the label `short`, at most 16 characters); kind of change (the four kinds, or not set); group (the project's groups, or none); derived from (the parent's name, **Pick on the map**, after which the next model pressed on the map becomes the parent, and **Clear**); description, labelled "What this model changes"; and, when the recipe has `run`: environment (the project's environments), each input that comes from a dataset (the project's datasets, keeping a named output), the settings, and the resources `gpu`, `wall_hours` and `disk_gb`. Settings: when `run.settings` is an object, one field per top-level key whose value is a number, a text or true/false, and a line naming the keys that are edited in the text; when the recipe has `settings_file`, its path and a sentence that a branch carries its own copy. + +The form writes the JSON with the indentation the text had, changing only the fields touched. What is typed stays in the page per definition until it is kept or discarded, so leaving the drawer loses nothing; a definition with typing not yet kept says so. + +| Control | Does | +| --- | --- | +| **Keep** | `set_definition`. Problems are listed with where they are in the document; nothing is kept while there is an error | +| **Discard edit** | drops what was typed; on a definition with an unsaved edit, `revert_definition` | +| **Remove** | `remove_definition`; the refusal names what uses it | +| **Save** | `save`, as on the strip | + +An unsaved definition carries an "unsaved" mark in the drawer's header, in its list row and on its map node. + +**Branch from here**, in a model's drawer: a title (required), the kind of change (the parent's to begin with) and what the model changes. **Create** calls `draft_branch` and the page holds the answer as a draft: + +- The draft is drawn on the map right after its parent, in its parent's lane, hollow and dashed, labelled "new", and is selected. In the list its chip reads "draft". +- Its drawer is the editor in the form view, opening with the draft's problems when it has them and, when settings were copied from a file, a line saying so. +- Below the form, the steps of the mockup's planned model with the real states: Kept, Saved, Build requested, Running, Built. The primary button is the next step: **Keep**, **Save**, **Plan build** (the plan view, with **Request build**), then **Open in Train**. **Discard** drops a draft, and on a kept one reverts it. +- Once kept it is a definition like any other: `map` returns it, not built and unsaved, and the page draws a model that has never been built hollow and dashed. A model without a date that names a parent is placed right after that parent (after the parent's earlier such children); the others stay where phase 2 put them. +- Train lists drafts first, under "Planned", with the models never built. + +### 3.3 Rules for both slices + +The rules of spec-w2 section 1 hold: no build step, no framework, no external reference, text through text nodes, both themes, the mockup's type, spacing and components (`btn`, `btn primary`, `btn ghost`, `form`, `actions`, `steps`, `radio`, `two`). A control that is waiting for its answer is disabled and says so. Keyboard: every control is reachable and operable, Escape leaves the two-press state and the pick-on-map state, and focus returns to what opened a view. + +## 4. Checking + +- **Unit tests** for section 2 in the project's test files, the operation count and the pinned contract digest updated the way spec-w1's were. +- **A browser check**, `tests/browser_project_workspace_actions.cjs`, beside the read-only one (which must still pass unchanged in what it asserts). It runs Tuldok on a copy of the fixture project committed to a Git repository of its own, with stand-in commands that train nothing; one of them takes about four seconds and prints progress lines. Signed in as the owner it: approves a build an agent asked for and sees the hairline partly filled while it runs, then the run succeeded; declines another with a reason and sees the reason; plans and requests a build and cancels it; branches a built model, changes a setting in the form, keeps, saves (the file is in the folder with `derived_from` and the changed setting), plans, requests, and sees the model built on the map with its line; edits an existing recipe in the form and discards the edit; saves a changed kind of change; types invalid JSON in the text view and sees the problem with nothing kept; sets a parent by picking on the map; makes a conflict (an unsaved edit and the same file changed on disk) and resolves it both ways; checks an environment again. It captures each new surface in light and dark and fails on any script error, failed request (other than the refusals it provokes), sideways overflow or control left disabled. +- **The acceptance run** of the "Done when" sentence is made by the orchestrating session on a copy of the tiny example with the machine's real interpreters and a throwaway database, driven in a headless browser, with screenshots. + +## 5. Slices + +| Slice | Files | Notes | +| --- | --- | --- | +| T20 core | `tuldok_project/operations.py`, `service.py`, `store.py`, `workspace.py`, `__main__.py`, their tests, the pinned digest, `docs/contracts/project-folder.md` | first; touches nothing under `static/` | +| T21 builds | `static/project-workspace/` (the controls of 3.1, the plan view, the conflict panel), asset rows in `app.py` for new files, `tests/browser_project_workspace_actions.cjs` | after T20 | +| T22 editing | `static/project-workspace/` (the editor, Branch from here, drafts on the map, the Overview list), the browser check extended | after T21 | From 0864c98cdea4472b3c79ec0667040b8bffd38ebf Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 12 Nov 2026 14:30:15 -0700 Subject: [PATCH 047/131] feat(project): draft a branch of a model, revert an unsaved edit, and what the map says of unsaved and newly built models draft_branch writes a new recipe from one of the project's without storing it, carrying the parent's settings file as its own settings, and says what keeping it would find wrong. revert_definition puts the folder's file back in place of an unsaved edit or a removal, or drops a definition never saved. Each model of map says whether it is unsaved, and a model without a trained_at label is dated by the run of its current product. Co-Authored-By: Claude Fable 5.2 --- docs/contracts/project-folder.md | 76 ++++- .../definition-first-projects/spec-w3.md | 4 +- tests/test_tuldok_project_service.py | 29 +- tests/test_tuldok_project_store.py | 106 +++++++ tests/test_tuldok_project_workspace.py | 278 +++++++++++++++++- tuldok_project/__main__.py | 69 ++++- tuldok_project/operations.py | 15 +- tuldok_project/service.py | 10 + tuldok_project/store.py | 189 +++++++++--- tuldok_project/workspace.py | 151 +++++++++- 10 files changed, 864 insertions(+), 63 deletions(-) diff --git a/docs/contracts/project-folder.md b/docs/contracts/project-folder.md index 5d2edbfa..a730db55 100644 --- a/docs/contracts/project-folder.md +++ b/docs/contracts/project-folder.md @@ -596,6 +596,8 @@ to the folder. Each project has its own schema, `project_`, named after the | `status` | Lists definitions edited or removed in the database and not yet saved, and definition files added, changed or missing on disk since the last import. | | `set REFERENCE FILE` | Replaces or adds the definition at `REFERENCE` with the text of `FILE`, in the database only. The text is checked on its own and against the rest of the project; an edit with any error is refused and changes nothing. | | `remove REFERENCE` | Removes the definition in the database only. It is refused while another definition uses it, or while it is the chart `tuldok.json` names in `map.chart`. | +| `revert REFERENCE` | Undoes the unsaved edit or the removal of a definition, in the database only: the file in the folder takes its place again. A definition the folder has no file for is dropped instead (refused while another definition uses it). A file that no longer checks is refused, and a definition with neither an unsaved edit nor a removal has nothing to revert (exit status 1). | +| `branch RECIPE --title TITLE [--name NAME] [--change KIND] [--description TEXT] [--keep]` | Prints a new recipe branched from `RECIPE` (a bare name or `recipes/`), as the operation `draft_branch` writes it: its reference, its problems in the form `check` prints them, and its text. Nothing is stored, unless `--keep` is given and the text has no error: then it is kept as an unsaved edit, as `set` keeps one. With `--keep` and an error, exit status 1. Here `--keep` keeps the branch; `branch` takes no `--keep` or `--discard` for a conflict. | | `map` | Prints the project's map: per group in order, its title, how many models (recipes) it has and how many of each kind of change, then the models in no group and the totals, then how many lines (`derived_from`, and recipes used as inputs by recipes) and comparisons there are, and the track. Reads the database only, never a results file, values file or note. | | `save` | Writes every unsaved definition to its file and deletes the files of removed ones. It writes nothing when one of those files changed on disk since it was imported, and names them. | | `forget` | Drops the project's copy from the database, including unsaved edits. The folder is not touched. | @@ -627,10 +629,10 @@ Options: | Option | Commands | Meaning | | --- | --- | --- | | `--database-url URL` | all but `check` and `note` | The Postgres database. Without it, the `TULDOK_DATABASE_URL` environment variable is used; with neither, the command stops with exit status 2. | -| `--json` | `open`, `list`, `show`, `graph`, `map`, `status`, `save`, `results`, `values`, `import-values`, `chart`, `plan`, `environments`, `connect`, `check-environment`, `set-up`, `runs`, `run`, `progress`, `cancel`, `stop`, `products`, `estimate` | Print one JSON document with the same content as the text. | +| `--json` | `open`, `list`, `show`, `graph`, `map`, `status`, `revert`, `branch`, `save`, `results`, `values`, `import-values`, `chart`, `plan`, `environments`, `connect`, `check-environment`, `set-up`, `runs`, `run`, `progress`, `cancel`, `stop`, `products`, `estimate` | Print one JSON document with the same content as the text. | | `--rebind` | all that open | The copy is bound to the folder it was first opened from. Opening the same project from another path is refused unless `--rebind` is given, which binds the copy to the new path. | -| `--keep` | all that open | Where a file changed on disk and the same definition has unsaved edits, keep the edits; the changed file becomes the version that `save` replaces. | -| `--discard` | all that open | Where a file changed on disk and the same definition has unsaved edits, drop the edits and take the file. | +| `--keep` | all that open but `branch` | Where a file changed on disk and the same definition has unsaved edits, keep the edits; the changed file becomes the version that `save` replaces. | +| `--discard` | all that open but `branch` | Where a file changed on disk and the same definition has unsaved edits, drop the edits and take the file. | Without `--keep` or `--discard`, such a conflict is refused and names the definitions concerned. @@ -1863,8 +1865,10 @@ and result keys of each operation are in its contract. | `map` | inspect | Read the map of the project: its groups, every recipe as a model with its group, kind of change, state and track value, the lines between them and the comparisons. | | `note` | inspect | Read one file under the notes directory of the project folder, given relative to it. | | `recipe_results` | inspect | Read the summary rows of every benchmark subject made from one recipe, ungrouped or for one group. | +| `draft_branch` | inspect | Write the text of a new recipe branched from one of the project's, with its name and what keeping it would find wrong; nothing is stored. | | `set_definition` | edit | Check a definition's text and keep it as an unsaved edit. | | `remove_definition` | edit | Mark a definition that nothing uses as removed, until the project is saved. | +| `revert_definition` | edit | Put back the file in the folder in place of a definition's unsaved edit or removal, or drop a definition the folder has no file for. | | `save` | edit | Write the unsaved edits and changed results files to the project folder. | | `resolve_conflict` | edit | Open a project whose files changed on disk where it has unsaved edits, keeping or discarding those edits. | | `import_values` | edit | Import one per-case values file, replacing that subject's values and summaries. | @@ -1880,22 +1884,78 @@ and result keys of each operation are in its contract. `map` answers `groups` (in their order, each with `id`, `title`, `parent`, `description` and `models`, the number of recipes naming it), `models` (one per -recipe, by the label `trained_at` and then by name: `reference`, `title`, -`short`, `group`, `change`, `derived_from`, `trained_at`, `state`, `adopted`, -`card`, `value` and `count`, `benchmarks`), `edges` (`{from, to, kind}`, +recipe, by `trained_at` and then by name: `reference`, `title`, +`short`, `group`, `change`, `derived_from`, `trained_at`, `state`, `unsaved` +(whether the definition has an unsaved edit), `adopted`, `card`, `value` and +`count`, `benchmarks`), `edges` (`{from, to, kind}`, `derived` or `input`), `comparisons` (`{from, to, explanation, excerpt}` as authored) and `track` (null, or `{chart, benchmark, metric, statistic}` from `map.chart`). A model's `value` and `count` are the track's statistic on the ungrouped row of its subject and how many cases it summarises; when a recipe is the subject under several names, the best by the metric's `better` is -taken. `map` runs the same few queries whatever the number of recipes and -reads no file. `note` takes `path`, relative to `notes/`, and reads it from +taken. A model's `trained_at` is its label `trained_at`; without the label, +the time the run that made its current product finished (ISO 8601 in UTC), +and null when it has no product or its product was adopted. Models with a +`trained_at` come first, earliest first. `map` runs the same few queries +whatever the number of recipes and reads no file. `note` takes `path`, relative to `notes/`, and reads it from the folder without opening the project; anything it refuses is `not-found`. `recipe_results` takes `recipe` and an optional `group` (absent: the ungrouped rows only) and answers `rows`, each as in `results` with `benchmark` added, ordered by benchmark, subject and metric, and `benchmarks`, the benchmarks with a subject made from that recipe. +`draft_branch` takes `recipe` (the parent, a bare name or `recipes/`), +`title` (1 to 200 characters) and optionally `name`, `change` (one of the four +kinds of change) and `description` (at most 4,000 characters). It stores +nothing and answers `reference`, `text`, `parent`, `inlined` and `problems`: + +- `reference` is `recipes/`. A given `name` must follow the name rule and + be free, and a removed definition's name is not free; otherwise the call is + refused `invalid`. Without `name` it is made from the title: lowercase, each + run of characters outside `[a-z0-9]` one `-`, trimmed of `-` at both ends and + to 80 characters (`recipe` when nothing is left), then `-2`, `-3` and so on + until it is free. +- `text` is the new recipe, written from the parent's text as it is in the + working copy: `format`, `kind`, `title`, `description` when given, the + parent's `model` and `group` when it has them, `change` (the argument, else + the parent's), `derived_from` naming the parent, and the parent's `run` when + it has one. `card`, `labels`, `earlier_work` and `compared_with` are not + carried. It is JSON indented as the parent's text is (two spaces when the + parent's has no indentation) and ends with a newline. +- When the parent's `run` has `settings_file` and that file, read from the code + root as it is on disk, is a regular file holding one JSON object of at most + 256 KiB, the new `run` carries that object as `settings` in place of + `settings_file`, and `inlined` is the file's path. A file reached through a + link that leaves the code root is not read. Otherwise `inlined` is null and + `run` is carried as it is. +- `problems` is what `set_definition` would find in `text` at `reference`, + errors and warnings, each `{severity, path, pointer, message}`. A branch of a + model without `run`, or whose code paths are missing, comes back with those + errors for the caller to fix before keeping it. + +A `recipe` that is not a recipe of the project, or is removed, is refused +`not-found`. + +`revert_definition` takes `reference` and answers `{reference, dropped}`. It +applies to a definition with an unsaved edit or marked removed: + +- When the folder holds its file, the file's text takes its place as an import + of that file would put it (text, title, kind, the file's digest and the uses + it makes), and it is neither unsaved nor removed; `dropped` is false. The text + is checked as `set_definition` checks it, and a file that no longer checks, or + that cannot be read, is refused `invalid` with its problems and nothing + changes. A benchmark's summary rows are kept to what fits it, as + `set_definition` keeps them; when its results file on disk is still the one + last imported, that file is imported again, so a benchmark whose removal is + reverted has the rows of its results file back (per-case values imported + from values files went with the removal and are not). +- When the folder holds no file for it, it is dropped as `remove_definition` + drops a definition never saved, and `dropped` is true; this is refused + `in-use` while another definition uses it. + +A definition with neither an unsaved edit nor the removed mark is refused +`nothing-to-revert`, and an unknown one `not-found`. + Installing an environment (`set-up`), measuring estimates (`estimate`), variables passed to a build (`build --env`), rebinding and forgetting a project stay command-line actions. diff --git a/docs/plans/definition-first-projects/spec-w3.md b/docs/plans/definition-first-projects/spec-w3.md index f3a82d49..b52690ff 100644 --- a/docs/plans/definition-first-projects/spec-w3.md +++ b/docs/plans/definition-first-projects/spec-w3.md @@ -26,11 +26,11 @@ Two operations of the `project_folder` profile and two additions to `map`. - `problems` is what `set_definition` would say of `text` at `reference`, errors and warnings, as a list of problems. A branch of a model without `run`, or whose code paths are missing, is returned with those errors for the caller to fix. - A `recipe` that is no recipe of the project (or is removed) is refused `not-found`. -**`revert_definition`**, for `edit`, a mutation. Argument `reference`. Result `{reference, dropped}`. For a definition that has an unsaved edit or is marked removed: when the folder holds its file, the file's text takes the edit's place and the definition is neither unsaved nor removed, checked as `set_definition` checks (a file that no longer checks is refused `invalid` with its problems, nothing changed); when the folder holds no file for it, it is dropped as `remove_definition` drops one that was never saved, refused `in-use` while anything uses it, and `dropped` is true. A definition with neither an unsaved edit nor the removed mark is refused `nothing-to-revert`. +**`revert_definition`**, for `edit`, a mutation. Argument `reference`. Result `{reference, dropped}`. For a definition that has an unsaved edit or is marked removed: when the folder holds its file, the file's text takes the edit's place and the definition is neither unsaved nor removed, checked as `set_definition` checks (a file that no longer checks is refused `invalid` with its problems, nothing changed); when the folder holds no file for it, it is dropped as `remove_definition` drops one that was never saved, refused `in-use` while anything uses it, and `dropped` is true. A definition with neither an unsaved edit nor the removed mark is refused `nothing-to-revert`. *Added when it was built:* removing a benchmark drops its summary rows, so reverting a removed benchmark also imports its results file again when that file is still the one last imported; otherwise the next save would have deleted the file. Per-case values that the removal dropped are not restored. **`map`:** each model gains `unsaved` (whether its definition has an unsaved edit). A model's `trained_at` is its label, and without the label the time the run of its current product finished (null when it has no product or the product was adopted). -**Command line:** `branch FOLDER RECIPE --title TITLE [--name NAME] [--change KIND] [--description TEXT] [--keep] [--json]` prints the draft's reference, its problems and its text; with `--keep` it stores the text as an unsaved edit when it has no error. `revert FOLDER REFERENCE` reverts. +**Command line:** `branch FOLDER RECIPE --title TITLE [--name NAME] [--change KIND] [--description TEXT] [--keep] [--json]` prints the draft's reference, its problems and its text; with `--keep` it stores the text as an unsaved edit when it has no error. `revert FOLDER REFERENCE` reverts. `branch` does not take the other commands' `--keep` and `--discard` for a conflict, since its own `--keep` means something else. The contract document gains both operations, the `map` additions and the two commands. diff --git a/tests/test_tuldok_project_service.py b/tests/test_tuldok_project_service.py index 5213596e..5b68ee56 100644 --- a/tests/test_tuldok_project_service.py +++ b/tests/test_tuldok_project_service.py @@ -48,7 +48,7 @@ class Table(unittest.TestCase): def test_every_operation_is_declared_once(self): names = [operation.name for operation in operations.OPERATIONS] - self.assertEqual(len(names), 39) # the rows of spec-m7.md section 2 and of spec-w1.md section 2 + self.assertEqual(len(names), 41) # the rows of spec-m7.md section 2 and of section 2 of spec-w1.md and spec-w3.md self.assertEqual(len(set(names)), len(names)) for name in REQUEST_OPERATIONS: self.assertIsNotNone(operations.by_name(name)) @@ -76,7 +76,7 @@ def test_every_row_has_a_summary_sentence_a_rule_and_result_keys(self): def test_mutations_and_owner_rows(self): mutations = {operation.name for operation in operations.OPERATIONS if operation.mutation} - self.assertEqual(mutations, {'set_definition', 'remove_definition', 'save', 'resolve_conflict', + self.assertEqual(mutations, {'set_definition', 'remove_definition', 'revert_definition', 'save', 'resolve_conflict', 'import_values', 'check_environment', 'connect_environment', 'disconnect_environment', 'request_build', 'approve_build', 'decline_build', 'cancel_build', 'cancel_run', 'stop_run'}) @@ -204,6 +204,7 @@ def test_every_read(self): 'environment': {'reference': 'environments/test-python'}, 'runs': {'limit': 2}, 'run': {'run': run_id}, 'progress': {'run': run_id[:8]}, 'products': {}, 'activity': {}, 'map': {}, 'note': {'path': 'missing.md'}, 'recipe_results': {'recipe': 'recipes/fit-a'}, + 'draft_branch': {'recipe': 'recipes/fit-a', 'title': 'Fit c'}, } reads = [operation for operation in operations.OPERATIONS if not operation.mutation] arguments['build_requests'] = {'state': 'queued', 'limit': 5} @@ -300,6 +301,30 @@ def test_set_remove_and_save(self): self.assertEqual((page['total'], [item['operation'] for item in page['items']]), (5, ['set_definition', 'save'])) + def test_revert(self): + before = self.call('definition', {'reference': 'recipes/fit-b'}) + text = self.edited('recipes/fit-b', lambda document: document.update(title='Fit b, edited')) + self.call('set_definition', {'reference': 'recipes/fit-b', 'text': text}) + self.assertEqual(self.refused('revert_definition', {'reference': 'recipes/fit-b'}, actor=agent('inspect')).code, + 'forbidden') + self.assertEqual(self.call('revert_definition', {'reference': 'recipes/fit-b'}, actor=agent('edit')), + {'reference': 'recipes/fit-b', 'dropped': False}) + self.assertEqual(self.call('definition', {'reference': 'recipes/fit-b'}), before) + self.assertEqual(self.refused('revert_definition', {'reference': 'recipes/fit-b'}).code, 'nothing-to-revert') + self.assertEqual(self.refused('revert_definition', {'reference': 'recipes/none'}).code, 'not-found') + draft = self.call('draft_branch', {'recipe': 'fit-a', 'title': 'Fit c'}, actor=agent('inspect')) + self.assertEqual(draft['problems'], []) + self.call('set_definition', {'reference': draft['reference'], 'text': draft['text']}) + self.assertEqual(self.call('revert_definition', {'reference': draft['reference']}), + {'reference': 'recipes/fit-c', 'dropped': True}) + rows = [(row['operation'], row['target'], row['outcome'], row['actor']['kind']) for row in self.activity()] + self.assertEqual(rows, [('revert_definition', 'recipes/fit-c', 'done', 'owner'), + ('set_definition', 'recipes/fit-c', 'done', 'owner'), + ('revert_definition', 'recipes/none', 'not-found', 'owner'), + ('revert_definition', 'recipes/fit-b', 'nothing-to-revert', 'owner'), + ('revert_definition', 'recipes/fit-b', 'done', 'agent'), + ('set_definition', 'recipes/fit-b', 'done', 'owner')]) + def refused_detail(self, reference): return f'{reference} is used by benchmarks/score, recipes/fit-a, recipes/fit-b; change those first.' diff --git a/tests/test_tuldok_project_store.py b/tests/test_tuldok_project_store.py index 5709dabf..b659c9c7 100644 --- a/tests/test_tuldok_project_store.py +++ b/tests/test_tuldok_project_store.py @@ -529,6 +529,112 @@ def test_file_removed_on_disk_with_an_unsaved_edit(self): self.assertNotIn('charts/speed-accuracy', [r['reference'] for r in project.definitions()]) +class Revert(StoreCase): + """revert_definition and definition_problems (spec-w3.md section 2).""" + + def setUp(self): + super().setUp() + self.project = self.open() + + def dump(self): + """Every row, in an order that does not depend on the order rows were written.""" + return {table: sorted(rows, key=repr) for table, rows in super().dump().items()} + + def refused(self, reference, code): + before = self.dump() + with self.assertRaises(ProjectError) as caught: + self.project.revert_definition(reference) + self.assertEqual(caught.exception.code, code) + self.assertEqual(self.dump(), before) + return caught.exception + + def test_an_unsaved_edit_gives_way_to_the_file(self): + before = self.dump() + self.project.set_definition('recipes/stepper-k2', self.edited('recipes/stepper-k2', lambda d: d.update( + title='Edited', change='component', derived_from='recipes/early-fit'))) + self.assertNotEqual(self.dump(), before) + self.assertEqual(self.project.revert_definition('recipes/stepper-k2'), + {'reference': 'recipes/stepper-k2', 'dropped': False}) + self.assertEqual(self.dump(), before) # text, document, title, kind, file digest, flags and edges + self.assertEqual(self.project.status(), CLEAN_STATUS) + + def test_a_removed_definition_comes_back(self): + before = self.dump() + self.project.remove_definition('charts/speed-accuracy') + self.project.revert_definition('charts/speed-accuracy') + self.assertEqual(self.dump(), before) + self.assertIn('charts/speed-accuracy', [node['reference'] for node in self.project.graph()['nodes']]) + + def test_the_file_as_it_is_now_on_disk_is_taken(self): + self.project.remove_definition('charts/speed-accuracy') + text = self.edited('charts/speed-accuracy', lambda d: d.update(title='Changed on disk')) + self.write('charts/speed-accuracy', text) + self.project.revert_definition('charts/speed-accuracy') + shown = self.project.definition('charts/speed-accuracy') + self.assertEqual((shown['text'], shown['title'], shown['unsaved'], shown['removed']), + (text, 'Changed on disk', False, False)) + self.assertEqual(self.project.status()['changed'], []) # its digest is the file's now + + def test_a_removed_benchmark_gets_its_result_rows_back(self): + self.close(self.project) + project_file = self.folder / 'tuldok.json' + document = json.loads(project_file.read_text(encoding='utf-8')) + del document['map'] + project_file.write_text(json.dumps(document, indent=2) + '\n', encoding='utf-8') + self.project = self.open() + before = self.dump() + for chart in ('speed-accuracy', 'rollout-ranking', 'rollout-progression', 'rollout-comparison'): + self.project.remove_definition(f'charts/{chart}') + self.project.remove_definition('benchmarks/rollout') + self.assertEqual(self.dump()['result_summaries'], []) + self.project.revert_definition('benchmarks/rollout') + for chart in ('speed-accuracy', 'rollout-ranking', 'rollout-progression', 'rollout-comparison'): + self.project.revert_definition(f'charts/{chart}') + self.assertEqual(self.dump(), before) + self.assertEqual(self.project.status(), CLEAN_STATUS) + + def test_a_definition_never_saved_is_dropped(self): + extra = json.dumps({'format': 'tuldok_definition_v1', 'kind': 'model', 'title': 'Extra'}) + self.project.set_definition('models/extra', extra) + user = self.edited('recipes/stepper-k1', lambda d: d.update(model='models/extra')) + self.project.set_definition('recipes/stepper-k1', user) + refused = self.refused('models/extra', 'in-use') + self.assertEqual(refused.references, ['recipes/stepper-k1']) + self.project.revert_definition('recipes/stepper-k1') + self.assertEqual(self.project.revert_definition('models/extra'), {'reference': 'models/extra', 'dropped': True}) + self.assertNotIn('models/extra', [row['reference'] for row in self.project.definitions()]) + self.assertEqual(self.project.status(), CLEAN_STATUS) + + def test_a_file_that_no_longer_checks_is_refused(self): + self.project.set_definition('recipes/stepper-k2', self.edited('recipes/stepper-k2', lambda d: d.update( + title='Edited'))) + self.write('recipes/stepper-k2', self.edited('recipes/stepper-k2', lambda d: d.update(model='models/missing'))) + refused = self.refused('recipes/stepper-k2', 'invalid') + self.assertIn(('recipes/stepper-k2.json', '/model'), [(p.path, p.pointer) for p in refused.problems]) + self.write('recipes/stepper-k2', '{"format": ') + self.assertEqual(self.refused('recipes/stepper-k2', 'invalid').problems[0].path, 'recipes/stepper-k2.json') + (self.folder / 'recipes' / 'stepper-k2.json').unlink() + (self.folder / 'recipes' / 'stepper-k2.json').symlink_to(self.folder / 'recipes' / 'stepper-k1.json') + self.refused('recipes/stepper-k2', 'invalid') + + def test_nothing_to_revert_and_not_found(self): + self.refused('recipes/stepper-k1', 'nothing-to-revert') + self.refused('recipes/missing', 'not-found') + self.refused('things/waves', 'not-found') + + def test_definition_problems_stores_nothing_and_has_warnings(self): + before = self.dump() + text = self.edited('recipes/early-fit', lambda d: d.update(run={ + 'command': ['sh', 'missing.sh'], 'sources': ['missing.sh']})) + problems = self.project.definition_problems('recipes/early-fit', text) + self.assertEqual([(p.severity, p.pointer) for p in problems], [('warning', '/run/sources/0')]) + problems = self.project.definition_problems('recipes/new', self.edited('recipes/stepper-k1', lambda d: d.update( + model='models/missing'))) + self.assertEqual([(p.severity, p.path, p.pointer) for p in problems], [('error', 'recipes/new.json', '/model')]) + self.assertEqual(self.project.definition_problems('recipes/new', '{')[0].path, 'recipes/new.json') + self.assertEqual(self.dump(), before) + + class Drop(StoreCase): def test_drop_project(self): diff --git a/tests/test_tuldok_project_workspace.py b/tests/test_tuldok_project_workspace.py index 34b56852..c94aca48 100644 --- a/tests/test_tuldok_project_workspace.py +++ b/tests/test_tuldok_project_workspace.py @@ -9,6 +9,9 @@ buildable fixture (BuildCase) with comparisons and a derivation added, which must build exactly as without them. Anything that could reach the local project home points TULDOK_PROJECT_HOME at a temporary directory. +Section 2 of spec-w3.md is tested here too: the map's unsaved and trained_at +fallback (MapAdditions), draft_branch (Branch, Operations) and the branch and +revert commands; revert_definition itself is tested in the store's tests. """ import copy import json @@ -50,14 +53,14 @@ 'description': 'A stepper trained before this format; only its weights and measurements remain.', 'short': 'F42', 'group': 'steppers', 'change': 'architecture', 'derived_from': None, 'trained_at': '2026-03-14', 'state': 'cannot-rebuild', - 'adopted': False, 'card': 'notes/fits/early-fit.md', 'value': 0.625, 'count': 4, 'benchmarks': 1}, + 'unsaved': False, 'adopted': False, 'card': 'notes/fits/early-fit.md', 'value': 0.625, 'count': 4, 'benchmarks': 1}, {'reference': 'recipes/stepper-k1', 'title': 'Stepper on wave scenes', 'description': None, 'short': 'K1', 'group': 'steppers', 'change': 'training-policy', 'derived_from': 'recipes/early-fit', 'trained_at': None, 'state': 'not-built', - 'adopted': False, 'card': None, 'value': 0.875, 'count': 8, 'benchmarks': 1}, + 'unsaved': False, 'adopted': False, 'card': None, 'value': 0.875, 'count': 8, 'benchmarks': 1}, {'reference': 'recipes/stepper-k2', 'title': 'Stepper fine-tuned from k1', 'description': None, 'short': 'K2', 'group': 'fine-tuned', 'change': 'refinement', 'derived_from': 'recipes/stepper-k1', 'trained_at': None, - 'state': 'not-built', 'adopted': False, 'card': None, 'value': 0.5, 'count': 8, 'benchmarks': 1}, + 'state': 'not-built', 'unsaved': False, 'adopted': False, 'card': None, 'value': 0.5, 'count': 8, 'benchmarks': 1}, ], 'edges': [ {'from': 'recipes/stepper-k1', 'to': 'recipes/early-fit', 'kind': 'derived'}, @@ -504,6 +507,203 @@ def test_recipe_results_under_two_names_and_with_none(self): self.assertEqual(workspace.recipe_results(project, 'recipes/stepper-k3'), {'rows': [], 'benchmarks': []}) +def _record_product(project, reference, finished_at, *, state='succeeded'): + """A run and the current product it made for reference, written straight into the tables builds.py owns.""" + run_id = f'run-{reference.split("/")[1]}-0000' + text = project.definition(reference)['text'] + project._execute("""INSERT INTO {schema}.runs (id, reference, subject, plan_id, state, scratch, commit, definition, + inputs, argv, env, directory, queued_at, started_at, finished_at) + VALUES (%s, %s, '', 'plan-0000', %s, true, '', %s, '{{}}', '[]', '{{}}', '/nonexistent', + %s, %s, %s)""", (run_id, reference, state, text, finished_at, finished_at, finished_at)) + project._execute("""INSERT INTO {schema}.products (run_id, reference, subject, directory, outputs, current) + VALUES (%s, %s, '', '/nonexistent', '{{}}', true)""", (run_id, reference)) + + +@unittest.skipUnless(DATABASE, 'TULDOK_DATABASE_URL is not set; database tests need a disposable cluster.') +class MapAdditions(store_base.StoreCase): + """The map's unsaved and the trained_at fallback (spec-w3.md section 2).""" + + def test_unsaved(self): + project = self.open() + text = (self.folder / 'recipes' / 'stepper-k2.json').read_text(encoding='utf-8') + project.set_definition('recipes/stepper-k2', text.replace('Stepper fine-tuned from k1', 'Edited')) + models = {model['reference']: model for model in workspace.project_map(project)['models']} + self.assertEqual({reference: model['unsaved'] for reference, model in models.items()}, + {'recipes/early-fit': False, 'recipes/stepper-k1': False, 'recipes/stepper-k2': True}) + + def test_trained_at_falls_back_to_the_finish_of_the_current_product(self): + project = self.open() + _record_product(project, 'recipes/stepper-k1', '2026-01-02T03:04:05+00:00') + _record_product(project, 'recipes/stepper-k2', '2025-01-01T00:00:00+00:00', state='adopted') + _record_product(project, 'recipes/early-fit', '2025-01-01T00:00:00+00:00') # its label wins + found = workspace.project_map(project) + models = {model['reference']: model for model in found['models']} + self.assertEqual(models['recipes/stepper-k1']['trained_at'], '2026-01-02T03:04:05+00:00') + self.assertEqual((models['recipes/stepper-k2']['trained_at'], models['recipes/stepper-k2']['adopted']), + (None, True)) + self.assertEqual(models['recipes/early-fit']['trained_at'], '2026-03-14') + self.assertEqual([model['reference'] for model in found['models']], + ['recipes/stepper-k1', 'recipes/early-fit', 'recipes/stepper-k2']) + + def test_the_number_of_queries_is_the_same_with_products(self): + project = self.open() + counting = _Counting(project._connection) + workspace.project_map(project) + without = counting.count + _record_product(project, 'recipes/stepper-k1', '2026-01-02T03:04:05+00:00') + _record_product(project, 'recipes/stepper-k2', '2026-01-03T03:04:05+00:00') + counting = _Counting(project._connection) + workspace.project_map(project) + # builds.status asks more once any run exists; neither it nor the map asks per recipe or product. + with_runs = counting.count + _record_product(project, 'recipes/early-fit', '2026-01-04T03:04:05+00:00') + counting = _Counting(project._connection) + workspace.project_map(project) + self.assertEqual(counting.count, with_runs) + self.assertGreater(without, 0) + + +@unittest.skipUnless(DATABASE, 'TULDOK_DATABASE_URL is not set; database tests need a disposable cluster.') +class Branch(store_base.StoreCase): + """draft_branch (spec-w3.md section 2).""" + + def setUp(self): + super().setUp() + self.code = self.base / 'code' + + def draft(self, recipe='recipes/stepper-k1', title='Stepper k1, more epochs!', **options): + project = self.open() + before = self.dump() + found = workspace.draft_branch(project, recipe, title, **options) + self.assertEqual(self.dump(), before) # nothing is stored + self.close(project) + json.dumps(found, allow_nan=False) + return found + + def test_a_branch_of_a_recipe_with_a_settings_file(self): + found = self.draft() + self.assertEqual(set(found), {'reference', 'text', 'parent', 'inlined', 'problems'}) + self.assertEqual((found['reference'], found['parent'], found['inlined'], found['problems']), + ('recipes/stepper-k1-more-epochs', 'recipes/stepper-k1', 'configs/train-k1.json', [])) + parent = json.loads((self.folder / 'recipes' / 'stepper-k1.json').read_text(encoding='utf-8')) + document = json.loads(found['text']) + self.assertEqual(list(document), ['format', 'kind', 'title', 'model', 'group', 'change', 'derived_from', 'run']) + self.assertEqual((document['title'], document['change'], document['derived_from'], document['group']), + ('Stepper k1, more epochs!', 'training-policy', 'recipes/stepper-k1', 'steppers')) + settings = json.loads((self.code / 'configs' / 'train-k1.json').read_text(encoding='utf-8')) + expected_run = {('settings' if key == 'settings_file' else key): (settings if key == 'settings_file' else value) + for key, value in parent['run'].items()} + self.assertEqual(document['run'], expected_run) + self.assertEqual(list(document['run']), list(expected_run)) # the parent's order of keys + self.assertEqual(found['text'], json.dumps(document, indent=2, ensure_ascii=False) + '\n') + project = self.open() + project.set_definition(found['reference'], found['text']) # it can be kept as it is + self.assertTrue(project.definition(found['reference'])['unsaved']) + + def test_what_is_and_is_not_carried(self): + found = self.draft('recipes/early-fit', 'Again', change='component', description='Retrained.') + document = json.loads(found['text']) + self.assertEqual(document, {'format': 'tuldok_definition_v1', 'kind': 'recipe', 'title': 'Again', + 'description': 'Retrained.', 'model': 'models/stepper', 'group': 'steppers', + 'change': 'component', 'derived_from': 'recipes/early-fit'}) + self.assertIsNone(found['inlined']) + # Without run and earlier_work it does not check yet: the caller is told so. + self.assertEqual([(p['severity'], p['path'], p['pointer']) for p in found['problems']], + [('error', 'recipes/again.json', '/run')]) + self.assertEqual(json.loads(self.draft('recipes/stepper-k2', 'K3')['text'])['change'], 'refinement') + + def test_inline_settings_and_indentation_are_kept(self): + found = self.draft('recipes/stepper-k2', 'K3') + self.assertIsNone(found['inlined']) + self.assertEqual(json.loads(found['text'])['run']['settings'], {'epochs': 2, 'learning_rate': 0.0005, 'seed': 2}) + path = self.folder / 'recipes' / 'stepper-k2.json' + document = json.loads(path.read_text(encoding='utf-8')) + for indent, expected in ((4, ' '), ('\t', '\t'), (None, ' ')): + with self.subTest(indent=indent): + path.write_text(json.dumps(document, indent=indent), encoding='utf-8') + text = self.draft('recipes/stepper-k2', 'K3')['text'] + self.assertEqual(text, json.dumps(json.loads(text), indent=expected, ensure_ascii=False) + '\n') + + def test_names(self): + self.assertEqual(self.draft(title=' Héllo, World!! ')['reference'], 'recipes/h-llo-world') + self.assertEqual(self.draft(title='!!!')['reference'], 'recipes/recipe') + long = self.draft(title='a' * 79 + ' b' + 'c' * 100)['reference'] + self.assertEqual(long, 'recipes/' + 'a' * 79) # cut to 80, then trimmed of the '-' it ends with + self.assertEqual(self.draft(title='Stepper K1')['reference'], 'recipes/stepper-k1-2') + _add_recipe(self.folder, 'stepper-k1-2') + self.assertEqual(self.draft(title='Stepper K1')['reference'], 'recipes/stepper-k1-3') + self.assertEqual(self.draft(title='x', name='chosen')['reference'], 'recipes/chosen') + + def test_a_name_that_is_wrong_or_taken_is_refused(self): + _add_recipe(self.folder, 'spare') + project = self.open() + project.remove_definition('recipes/spare') + for name in ('Upper', '-dash', 'a' * 121, 'stepper-k1', 'spare'): + with self.subTest(name=name): + with self.assertRaises(ProjectError) as caught: + workspace.draft_branch(project, 'recipes/stepper-k1', 'x', name=name) + self.assertEqual(caught.exception.code, 'invalid') + self.assertEqual(workspace.draft_branch(project, 'recipes/stepper-k1', 'Spare')['reference'], + 'recipes/spare-2') # a removed definition's name is not free + + def test_an_unknown_or_removed_recipe_is_not_found(self): + _add_recipe(self.folder, 'spare') + project = self.open() + project.remove_definition('recipes/spare') + for recipe in ('recipes/missing', 'recipes/spare', 'models/stepper', 'nonsense'): + with self.subTest(recipe=recipe): + with self.assertRaises(ProjectError) as caught: + workspace.draft_branch(project, recipe, 'x') + self.assertEqual(caught.exception.code, 'not-found') + + def replace_settings(self, make): + """Replace stepper-k1's settings file in the code root with what make(path) puts there.""" + path = self.code / 'configs' / 'train-k1.json' + if path.is_dir() and not path.is_symlink(): + path.rmdir() + elif path.exists() or path.is_symlink(): + path.unlink() + make(path) + + def test_settings_that_are_not_carried(self): + self.close(self.open()) # imported once: later opens attach without looking at the code root + outside = self.temporary / 'outside.json' + outside.write_text('{"secret": 1}', encoding='utf-8') + cases = { + 'a list': lambda path: path.write_text('[1, 2]', encoding='utf-8'), + 'not JSON': lambda path: path.write_text('{"a": ', encoding='utf-8'), + 'a key twice': lambda path: path.write_text('{"a": 1, "a": 2}', encoding='utf-8'), + 'over the limit': lambda path: path.write_text( + '{"a": "' + 'x' * (workspace.SETTINGS_LIMIT - 8) + '"}', encoding='utf-8'), + 'a link out of the code root': lambda path: path.symlink_to(outside), + 'a directory': lambda path: path.mkdir(), + 'missing': lambda path: None, + } + for case, make in cases.items(): + with self.subTest(case=case): + self.replace_settings(make) + found = self.draft() + run = json.loads(found['text'])['run'] + self.assertIsNone(found['inlined']) + self.assertEqual(run['settings_file'], 'configs/train-k1.json') + self.assertNotIn('settings', run) + if case in ('a link out of the code root', 'missing'): + self.assertIn('/run/settings_file', [problem['pointer'] for problem in found['problems']]) + + def test_settings_carried_through_a_link_inside_the_code_root_and_at_the_limit(self): + self.close(self.open()) + real = self.code / 'configs' / 'real.json' + real.write_text('{"epochs": 9}', encoding='utf-8') + self.replace_settings(lambda path: path.symlink_to(real)) + found = self.draft() + self.assertEqual((found['inlined'], json.loads(found['text'])['run']['settings']), + ('configs/train-k1.json', {'epochs': 9})) + exact = '{"a": "' + 'x' * (workspace.SETTINGS_LIMIT - 9) + '"}' + self.assertEqual(len(exact.encode()), workspace.SETTINGS_LIMIT) + self.replace_settings(lambda path: path.write_text(exact, encoding='utf-8')) + self.assertEqual(self.draft()['inlined'], 'configs/train-k1.json') + + @unittest.skipUnless(DATABASE, 'TULDOK_DATABASE_URL is not set; database tests need a disposable cluster.') class Operations(store_base.StoreCase): """The three operations through Service.call, for an inspect credential.""" @@ -551,10 +751,35 @@ def test_recipe_results(self): self.assertEqual(self.refused('recipe_results', {'recipe': 'recipes/missing'}), 'not-found') self.assertEqual(self.refused('recipe_results', {}), 'invalid') + def test_draft_branch(self): + found = self.call('draft_branch', {'recipe': 'stepper-k1', 'title': 'More epochs', 'change': 'refinement', + 'description': 'Twice the epochs.'}) + self.assertEqual((found['reference'], found['parent'], found['inlined'], found['problems']), + ('recipes/more-epochs', 'recipes/stepper-k1', 'configs/train-k1.json', [])) + self.assertEqual(json.loads(found['text'])['change'], 'refinement') + self.assertEqual(self.call('draft_branch', {'recipe': 'recipes/stepper-k1', 'title': 'x', 'name': 'k9'}) + ['reference'], 'recipes/k9') + self.assertEqual(self.call('definitions', {'kind': 'recipe'})['definitions'][-1]['reference'], + 'recipes/stepper-k2') # nothing was stored + self.assertEqual(self.refused('draft_branch', {'recipe': 'recipes/missing', 'title': 'x'}), 'not-found') + self.assertEqual(self.refused('draft_branch', {'recipe': 'stepper-k1', 'title': 'x', 'name': 'stepper-k2'}), + 'invalid') + for wrong in ({'recipe': 'stepper-k1'}, {'recipe': 'stepper-k1', 'title': ''}, + {'recipe': 'stepper-k1', 'title': 'x' * 201}, {'recipe': 'stepper-k1', 'title': 'x', 'change': 'big'}, + {'recipe': 'stepper-k1', 'title': 'x', 'description': 'x' * 4001}, + {'recipe': 'stepper-k1', 'title': 'x', 'keep': True}): + with self.subTest(arguments=wrong): + self.assertEqual(self.refused('draft_branch', wrong), 'invalid') + self.assertEqual(self.refused('draft_branch', {'recipe': 'stepper-k1', 'title': 'x'}, NOBODY), 'forbidden') + + def test_revert_needs_edit(self): + self.assertEqual(self.refused('revert_definition', {'reference': 'recipes/stepper-k1'}), 'forbidden') + def test_none_writes_activity(self): self.call('map', {}) self.call('note', {'path': 'decisions.md'}) self.call('recipe_results', {'recipe': 'recipes/early-fit'}) + self.call('draft_branch', {'recipe': 'recipes/early-fit', 'title': 'x'}) self.assertEqual(self.service.call('activity', {}, INSPECTOR)['total'], 0) @@ -582,6 +807,53 @@ def test_map(self): shown = _run('map', self.folder, '--json', home=self.temporary / 'home') self.assertEqual(json.loads(shown.stdout), FIXTURE_MAP) + def test_branch(self): + home = self.temporary / 'home' + done = _run('branch', self.folder, 'stepper-k1', '--title', 'More epochs', home=home) + self.assertEqual(done.returncode, 0, done.stderr) + first, *rest = done.stdout.splitlines() + self.assertEqual(first, 'recipes/more-epochs, branched from recipes/stepper-k1, with the settings of ' + 'configs/train-k1.json copied in.') + shown = _run('branch', self.folder, 'recipes/stepper-k1', '--title', 'More epochs', '--json', home=home) + found = json.loads(shown.stdout) + self.assertEqual(done.stdout.split('\n', 2)[2], found['text']) # the text after the line and a blank one + self.assertFalse((self.folder / 'recipes' / 'more-epochs.json').exists()) + + kept = _run('branch', self.folder, 'stepper-k1', '--title', 'More epochs', '--change', 'component', '--keep', + home=home) + self.assertEqual(kept.returncode, 0, kept.stderr) + self.assertIn('Kept recipes/more-epochs in the database; run save to write it to the folder.', kept.stdout) + status = _run('status', self.folder, '--json', home=home) + self.assertEqual(json.loads(status.stdout)['unsaved'], ['recipes/more-epochs']) + + refused = _run('branch', self.folder, 'early-fit', '--title', 'Again', '--keep', home=home) + self.assertEqual(refused.returncode, 1) + self.assertIn('error recipes/again.json /run', refused.stdout) + self.assertIn('recipes/again was not kept: it has 1 error.', refused.stderr) + missing = _run('branch', self.folder, 'missing', '--title', 'x', home=home) + self.assertEqual(missing.returncode, 1) + self.assertIn('There is no recipe recipes/missing to branch from.', missing.stderr) + self.assertEqual(_run('branch', self.folder, 'stepper-k1', home=home).returncode, 2) # --title is required + + reverted = _run('revert', self.folder, 'recipes/more-epochs', '--json', home=home) + self.assertEqual(json.loads(reverted.stdout), {'reference': 'recipes/more-epochs', 'dropped': True}) + again = _run('revert', self.folder, 'recipes/more-epochs', home=home) + self.assertEqual(again.returncode, 1) + self.assertIn('There is no definition recipes/more-epochs.', again.stderr) + + def test_revert(self): + home = self.temporary / 'home' + path = self.folder / 'recipes' / 'stepper-k2.json' + edited = self.temporary / 'edited.json' + edited.write_text(path.read_text(encoding='utf-8').replace('Stepper fine-tuned from k1', 'Edited'), + encoding='utf-8') + self.assertEqual(_run('set', self.folder, 'recipes/stepper-k2', edited, home=home).returncode, 0) + done = _run('revert', self.folder, 'recipes/stepper-k2', home=home) + self.assertEqual((done.returncode, done.stdout), (0, 'Reverted recipes/stepper-k2 to its file in the folder.\n')) + nothing = _run('revert', self.folder, 'recipes/stepper-k2', home=home) + self.assertEqual(nothing.returncode, 1) + self.assertIn('there is nothing to revert', nothing.stderr) + def test_note(self): done = _run('note', self.folder, 'fits/early-fit.md', home=self.temporary / 'home') self.assertEqual(done.returncode, 0, done.stderr) diff --git a/tuldok_project/__main__.py b/tuldok_project/__main__.py index 831fcf48..7ec8c0fd 100644 --- a/tuldok_project/__main__.py +++ b/tuldok_project/__main__.py @@ -24,6 +24,9 @@ only for a moment (waiting while a build has it open) and read the run's logs with it closed. `estimate` runs the build steps' estimate commands, the one command besides `build` that runs project code; `plan` shows what it stored. +`branch` prints a new recipe branched from one (workspace.draft_branch) and, +with --keep, stores it as an unsaved edit; `revert` puts a definition's file +back in place of its unsaved edit or removal. `map` prints the project's map (workspace.py): its groups with how many models of each kind of change they hold, the lines, the comparisons and the track, from the database only. `note` prints one file under notes/, read @@ -41,6 +44,7 @@ import time from . import documents, folder as folder_reader, results as results_format +from .operations import CHANGES from .check import check_folder DATABASE_VARIABLE = 'TULDOK_DATABASE_URL' @@ -115,6 +119,21 @@ def add(name, parents, help_text): setting.add_argument('file', help='the file holding the new definition text') removing = add('remove', [opening], 'remove a definition in the database (not saved to the folder)') removing.add_argument('reference', help='for example recipes/pilot-dense-k1') + # Not [reading]: there --keep keeps unsaved edits in a conflict; here it keeps the branch (spec-w3.md section 2). + branching = add('branch', [database], "print a new recipe branched from a recipe, with its name and problems") + branching.set_defaults(on_conflict=None) + branching.add_argument('--rebind', action='store_true', + help='take the copy over from the folder it is bound to and bind it to this one') + branching.add_argument('--json', action='store_true', help="print the draft as one JSON document") + branching.add_argument('recipe', help='the parent, for example pilot-dense-k1 or recipes/pilot-dense-k1') + branching.add_argument('--title', required=True, help='the title of the new recipe, 1 to 200 characters') + branching.add_argument('--name', help='its name; by default one made from the title') + branching.add_argument('--change', choices=CHANGES, help="its kind of change; by default the parent's") + branching.add_argument('--description', help='what the new model changes, at most 4,000 characters') + branching.add_argument('--keep', action='store_true', + help='store it as an unsaved edit when it has no error (not saved to the folder)') + reverting = add('revert', [reading], "put a definition's file back in place of its unsaved edit or removal") + reverting.add_argument('reference', help='for example recipes/pilot-dense-k1') add('save', [reading], 'write the unsaved edits to the folder') showing = add('results', [reading], "show the benchmarks' results, or one benchmark's summary rows") showing.add_argument('benchmark', nargs='?', help='a benchmark, for example rollout or benchmarks/rollout') @@ -341,6 +360,45 @@ def _remove(project, arguments): return 0 +def _branch(project, arguments): + from . import workspace + from .documents import Problem + + draft = workspace.draft_branch(project, arguments.recipe, arguments.title, name=arguments.name, + change=arguments.change, description=arguments.description) + problems = [Problem(**problem) for problem in draft['problems']] + errors = [problem for problem in problems if problem.severity == 'error'] + kept = arguments.keep and not errors + if kept: + project.set_definition(draft['reference'], draft['text']) + if arguments.json: + _json(draft) + else: + print(f'{draft["reference"]}, branched from {draft["parent"]}' + + (f', with the settings of {draft["inlined"]} copied in' if draft['inlined'] else '') + '.') + for problem in problems: + print(_problem_line(problem)) + print() + sys.stdout.write(draft['text']) + if kept and not arguments.json: + print(f'Kept {draft["reference"]} in the database; run save to write it to the folder.') + if arguments.keep and not kept: + print(f'{draft["reference"]} was not kept: it has {_plural(len(errors), "error")}.', file=sys.stderr) + return 1 + return 0 + + +def _revert(project, arguments): + done = project.revert_definition(arguments.reference) + if arguments.json: + _json(done) + elif done['dropped']: + print(f'Dropped {done["reference"]} from the database: the folder holds no file for it.') + else: + print(f'Reverted {done["reference"]} to its file in the folder.') + return 0 + + def _save(project, arguments): saved = project.save() if arguments.json: @@ -518,9 +576,6 @@ def _chart(project, arguments): return 0 -_CHANGES = ('training-policy', 'architecture', 'refinement', 'component') - - def _map(project, arguments): from . import workspace @@ -530,11 +585,11 @@ def _map(project, arguments): return 0 def counted(title, models): - kinds = [sum(1 for model in models if model['change'] == kind) for kind in _CHANGES] + kinds = [sum(1 for model in models if model['change'] == kind) for kind in CHANGES] return (title, len(models), *kinds, len(models) - sum(kinds)) models = drawn['models'] - rows = [('group', 'models', *_CHANGES, 'no kind')] + rows = [('group', 'models', *CHANGES, 'no kind')] rows += [counted(group['title'], [model for model in models if model['group'] == group['id']]) for group in drawn['groups']] known = {group['id'] for group in drawn['groups']} @@ -1442,7 +1497,7 @@ def _adopt(project, arguments): _STORE_COMMANDS = {'open': _open, 'list': _list, 'show': _show, 'graph': _graph, 'status': _status, 'map': _map, - 'set': _set, 'remove': _remove, 'save': _save, 'results': _results, 'values': _values, + 'set': _set, 'remove': _remove, 'branch': _branch, 'revert': _revert, 'save': _save, 'results': _results, 'values': _values, 'import-values': _import_values, 'chart': _chart, 'report': _report, 'plan': _plan, 'environments': _environments, 'connect': _connect, 'check-environment': _check_environment, 'set-up': _set_up, 'disconnect': _disconnect, 'runs': _runs, 'products': _products, @@ -1522,6 +1577,8 @@ def _run_store(arguments, dsn): arguments.benchmark = _bare(arguments.benchmark, 'benchmarks') if arguments.command == 'chart': arguments.chart = _bare(arguments.chart, 'charts') + if arguments.command == 'branch': + arguments.recipe = 'recipes/' + _bare(arguments.recipe, 'recipes') if arguments.command in ('connect', 'set-up', 'disconnect'): arguments.environment = 'environments/' + _bare(arguments.environment, 'environments') if arguments.command == 'check-environment': diff --git a/tuldok_project/operations.py b/tuldok_project/operations.py index 279a0b64..42cf59d5 100644 --- a/tuldok_project/operations.py +++ b/tuldok_project/operations.py @@ -1,7 +1,8 @@ """The operations a served project folder offers, as data: names, who may call them, arguments and results. Owns the table of section 2 of docs/plans/definition-first-projects/spec-m7.md, with the three -rows of section 2 of spec-w1.md (map, note, recipe_results). +rows of section 2 of spec-w1.md (map, note, recipe_results) and the two of +section 2 of spec-w3.md (draft_branch, revert_definition). Each Operation names one operation project., the rule its caller must satisfy (who), whether it changes anything (mutation), a closed JSON Schema of its arguments and the result keys that are always present. service.py checks @@ -13,6 +14,7 @@ WHO = ('inspect', 'edit', 'cancel', 'request', 'owner') REQUEST_STATES = ('awaiting-approval', 'queued', 'running', 'succeeded', 'failed', 'cancelled', 'declined', 'expired') KINDS = ('dataset', 'model', 'recipe', 'benchmark', 'step', 'environment', 'chart') +CHANGES = ('training-policy', 'architecture', 'refinement', 'component') # a recipe's kind of change TARGET_LIMIT = 50 REASON_CHARACTERS = 400 @@ -129,10 +131,21 @@ def _arguments(required=(), **properties): Operation('recipe_results', "Read the summary rows of every benchmark subject made from one recipe, ungrouped " 'or for one group.', 'inspect', False, _arguments(['recipe'], recipe=_REFERENCE, group=_TEXT), ('rows', 'benchmarks')), + Operation('draft_branch', 'Write the text of a new recipe branched from one of the project\'s, with its name ' + 'and what keeping it would find wrong; nothing is stored.', 'inspect', False, + _arguments(['recipe', 'title'], recipe=_REFERENCE, + title={'type': 'string', 'minLength': 1, 'maxLength': 200}, + name={'type': 'string', 'minLength': 1, 'maxLength': 120}, + change={'type': 'string', 'enum': list(CHANGES)}, + description={'type': 'string', 'maxLength': 4000}), + ('reference', 'text', 'parent', 'inlined', 'problems')), Operation('set_definition', "Check a definition's text and keep it as an unsaved edit.", 'edit', True, _arguments(['reference', 'text'], reference=_REFERENCE, text=_TEXT), DEFINITION), Operation('remove_definition', 'Mark a definition that nothing uses as removed, until the project is saved.', 'edit', True, _arguments(['reference'], reference=_REFERENCE), ('removed',)), + Operation('revert_definition', 'Put back the file in the folder in place of a definition\'s unsaved edit or ' + 'removal, or drop a definition the folder has no file for.', 'edit', True, + _arguments(['reference'], reference=_REFERENCE), ('reference', 'dropped')), Operation('save', 'Write the unsaved edits and changed results files to the project folder.', 'edit', True, _arguments(), SAVE), Operation('resolve_conflict', 'Open a project whose files changed on disk where it has unsaved edits, keeping ' diff --git a/tuldok_project/service.py b/tuldok_project/service.py index 0112e1ea..c8a0c8e3 100644 --- a/tuldok_project/service.py +++ b/tuldok_project/service.py @@ -417,6 +417,12 @@ def _recipe_results(self, arguments, actor): with self._open() as project: return workspace.recipe_results(project, recipe, arguments.get('group')) + def _draft_branch(self, arguments, actor): + recipe = 'recipes/' + _bare(arguments['recipe'], 'recipes') + with self._open() as project: + return workspace.draft_branch(project, recipe, arguments['title'], name=arguments.get('name'), + change=arguments.get('change'), description=arguments.get('description')) + # ------------------------------------------------------------- changes def _set_definition(self, arguments, actor): @@ -429,6 +435,10 @@ def _remove_definition(self, arguments, actor): project.remove_definition(arguments['reference']) return {'removed': arguments['reference']} + def _revert_definition(self, arguments, actor): + with self._open() as project: + return project.revert_definition(arguments['reference']) + def _save(self, arguments, actor): with self._open() as project: return project.save() diff --git a/tuldok_project/store.py b/tuldok_project/store.py index 35f135ce..9ab66775 100644 --- a/tuldok_project/store.py +++ b/tuldok_project/store.py @@ -28,6 +28,9 @@ The state row also keeps tuldok.json as last imported (spec-w1.md: the map's groups and track are read from it); a change to it alone imports the folder again, and the chart its map.chart names cannot be removed. +revert_definition (spec-w3.md section 2) undoes an unsaved edit or a removed +mark from the folder's file, and definition_problems says what set_definition +would say of a text without storing it; both check with set_definition's code. """ from dataclasses import dataclass import hashlib @@ -87,7 +90,8 @@ class ProjectError(Exception): code is one of: invalid (the folder or the edit breaks the format; problems lists why), conflict (files changed on disk where the database has unsaved - edits), bound-elsewhere, busy, in-use, changed-on-disk, not-found; and for + edits), bound-elsewhere, busy, in-use, changed-on-disk, not-found, + nothing-to-revert (revert_definition); and for environments (environments.py): not-set-up (nothing is recorded for it), no-install, no-installer, target-exists, install-failed; and for builds (builds.py): blocked, running, not-ready, and a snapshot.SnapshotError's @@ -602,23 +606,20 @@ def status(self): # ------------------------------------------------------------ editing - def set_definition(self, reference, text): - """Validate text as the definition at reference and store it as an unsaved edit (4.4). + def _text_problems(self, reference, text, state): + """(document, problems): every error and warning set_definition finds in text at reference. - It is checked alone (strict JSON, schema, kind against directory, card, - placeholders, paths into the code root) and against the project as it - would then be (references, named outputs, charts, cycles). Raises - ProjectError with code 'invalid' and the problems, changing nothing, - when any error is found. + document is None when text is not a strict JSON object (problems then + holds that one error). It is checked alone (strict JSON, schema, kind + against directory, card, placeholders, paths into the code root) and + against the project as it would then be (references, named outputs, + charts, cycles); the caller holds the transaction that reads the project. """ - directory, name = _split(reference) path = f'{reference}.json' try: document = documents.decode(text) except documents.DocumentError as exc: - raise ProjectError(f'{reference} is not valid: {exc}', 'invalid', - problems=[Problem('error', path, '', str(exc))]) from None - state = self._state() + return None, [Problem('error', path, '', str(exc))] candidate = _definition(reference, text, document) problems = [] @@ -628,11 +629,31 @@ def add(severity, where, pointer, message): check.check_definition(candidate, _notes(state['folder']), add) code_root = os.path.realpath(os.path.join(state['folder'], state['code_root'])) check.check_code_paths(candidate, code_root if os.path.isdir(code_root) else None, add) - alone = _errors(problems) + alone = bool(_errors(problems)) + merged = self._merged_definitions() + merged[reference] = candidate + return document, problems + _cross_problems(merged, {path} if alone else (), state['project']) + + def definition_problems(self, reference, text): + """The errors and warnings set_definition would find in text at reference; nothing is stored.""" + _split(reference) + state = self._state() with self._connection.transaction(): - merged = self._merged_definitions() - merged[reference] = candidate - errors = alone + _errors(_cross_problems(merged, {path} if alone else (), state['project'])) + return self._text_problems(reference, text, state)[1] + + def set_definition(self, reference, text): + """Validate text as the definition at reference and store it as an unsaved edit (4.4). + + It is checked by _text_problems. Raises ProjectError with code + 'invalid' and the errors, changing nothing, when any error is found. + """ + directory, name = _split(reference) + state = self._state() + with self._connection.transaction(): + document, problems = self._text_problems(reference, text, state) + errors = _errors(problems) + if document is None: + raise ProjectError(f'{reference} is not valid: {errors[0].message}', 'invalid', problems=errors) if errors: raise ProjectError(f'{reference} cannot be set; see the problems.', 'invalid', problems=errors, references=[reference]) @@ -644,7 +665,7 @@ def add(severity, where, pointer, message): document = EXCLUDED.document, removed = false, unsaved = {schema}.definitions.unsaved OR {schema}.definitions.removed OR {schema}.definitions.text IS DISTINCT FROM EXCLUDED.text''', - (directory, name, candidate.kind, document['title'], text, Jsonb(document))) + (directory, name, documents.KINDS[directory], document['title'], text, Jsonb(document))) self._write_edges(graph.edges({reference: document}), [reference]) if directory == 'benchmarks': result_rows.prune(self._connection, self.schema, name, document) @@ -665,26 +686,115 @@ def remove_definition(self, reference): (directory, name)).fetchone() if row is None: raise ProjectError(f'There is no definition {reference}.', 'not-found', references=[reference]) - users = [source for (source,) in self._execute( - 'SELECT DISTINCT from_ref FROM {schema}.edges WHERE to_ref = %s ORDER BY 1', (reference,))] - project = self._state()['project'] or {} - if isinstance(project.get('map'), dict) and project['map'].get('chart') == reference: - users.append(folder_reader.PROJECT_FILE) # its map.chart (spec-w1.md section 1) - if users: - raise ProjectError(f'{reference} is used by {", ".join(users)}; change those first.', 'in-use', - references=users) + self._refuse_in_use(reference) if row[0] is None: # Never written to disk: there is no file for save() to delete. - self._execute('DELETE FROM {schema}.definitions WHERE directory = %s AND name = %s', (directory, name)) + self._drop(reference) else: self._execute('UPDATE {schema}.definitions SET removed = true WHERE directory = %s AND name = %s', (directory, name)) - self._write_edges([], [reference]) - builds.forget(self._connection, self.schema, reference) + self._forget(reference) + + def _refuse_in_use(self, reference): + """Raise ProjectError in-use naming what uses reference; the chart in map.chart counts as used.""" + users = [source for (source,) in self._execute( + 'SELECT DISTINCT from_ref FROM {schema}.edges WHERE to_ref = %s ORDER BY 1', (reference,))] + project = self._state()['project'] or {} + if isinstance(project.get('map'), dict) and project['map'].get('chart') == reference: + users.append(folder_reader.PROJECT_FILE) # its map.chart (spec-w1.md section 1) + if users: + raise ProjectError(f'{reference} is used by {", ".join(users)}; change those first.', 'in-use', + references=users) + + def _drop(self, reference): + """Delete a definition's row outright (there is no file for save() to delete) and forget its records.""" + self._execute('DELETE FROM {schema}.definitions WHERE directory = %s AND name = %s', + documents.parse_reference(reference)) + self._forget(reference) + + def _forget(self, reference): + """Drop what a definition that is gone leaves: its edges, runs and products, results, environment record.""" + directory, name = documents.parse_reference(reference) + self._write_edges([], [reference]) + builds.forget(self._connection, self.schema, reference) + if directory == 'benchmarks': + result_rows.remove_benchmark(self._connection, self.schema, name) + if directory == environments.DIRECTORY: + environments.forget(self._connection, self.schema, name) + + def revert_definition(self, reference): + """Undo a definition's unsaved edit or removed mark (spec-w3.md section 2); returns {reference, dropped}. + + When the folder holds the definition's file, its text takes the row's + place as an import of that file would put it (text, document, title, + kind, file digest, edges), checked as set_definition checks; a file that + no longer checks, or cannot be read, is refused invalid with nothing + changed. A benchmark's result rows are pruned as set_definition prunes + them, and its results file is imported again when it is still the file + last imported, since removing the benchmark dropped its rows. When the + folder holds no file, the row is dropped as remove_definition drops one + never saved (refused in-use while anything uses it). Refused + nothing-to-revert for a definition with neither, not-found for none. + """ + directory, name = _split(reference) + state = self._state() + with self._connection.transaction(): + row = self._execute('SELECT unsaved, removed FROM {schema}.definitions ' + 'WHERE directory = %s AND name = %s FOR UPDATE', (directory, name)).fetchone() + if row is None: + raise ProjectError(f'There is no definition {reference}.', 'not-found', references=[reference]) + if not (row[0] or row[1]): + raise ProjectError(f'{reference} has no unsaved edit and is not marked removed; there is nothing ' + 'to revert.', 'nothing-to-revert', references=[reference]) + path = f'{reference}.json' + try: + raw = _read_path(state['folder'], directory, f'{name}.json', folder_reader.DEFINITION_LIMIT) + except folder_reader.Unsafe as exc: + raise ProjectError(f'{reference} cannot be reverted: its file cannot be read.', 'invalid', + problems=[Problem('error', path, '', str(exc))], references=[reference]) from None + if raw is None: + self._refuse_in_use(reference) + self._drop(reference) + return {'reference': reference, 'dropped': True} + try: + text = raw.decode('utf-8') + except UnicodeDecodeError as exc: + raise ProjectError(f'{reference} cannot be reverted: its file is not UTF-8 text.', 'invalid', + problems=[Problem('error', path, '', f'The file is not UTF-8 text (bad byte at ' + f'offset {exc.start}).')], + references=[reference]) from None + document, problems = self._text_problems(reference, text, state) + errors = _errors(problems) + if errors: + raise ProjectError(f'{reference} cannot be reverted: its file in the folder no longer checks; see ' + 'the problems.', 'invalid', problems=errors, references=[reference]) + self._execute('''UPDATE {schema}.definitions SET kind = %s, title = %s, text = %s, document = %s, + file_sha256 = %s, unsaved = false, removed = false + WHERE directory = %s AND name = %s''', + (documents.KINDS[directory], document['title'], text, Jsonb(document), _sha(raw), + directory, name)) + self._write_edges(graph.edges({reference: document}), [reference]) if directory == 'benchmarks': - result_rows.remove_benchmark(self._connection, self.schema, name) - if directory == environments.DIRECTORY: - environments.forget(self._connection, self.schema, name) + result_rows.prune(self._connection, self.schema, name, document) + self._import_results_again(name, document) + return {'reference': reference, 'dropped': False} + + def _import_results_again(self, benchmark, document): + """Import results/.csv again when it is still the file last imported and fits the benchmark.""" + recorded = self._execute('SELECT file_sha256 FROM {schema}.results_files WHERE benchmark = %s', + (benchmark,)).fetchone() + if recorded is None: + return + try: + raw = _read_path(self._state()['folder'], folder_reader.RESULTS, f'{benchmark}.csv', + folder_reader.RESULTS_LIMIT) + except folder_reader.Unsafe: + return + if raw is None or _sha(raw) != recorded[0]: + return # gone or changed on disk: the next open takes it as it takes any results file + if any(severity == 'error' for severity, _, _ in results.check_results(raw, document)): + return + result_rows.import_file(self._connection, self.schema, benchmark, raw.decode('utf-8'), document) def save(self): """Write unsaved definitions and changed results files, and delete the files of removed ones. @@ -840,18 +950,27 @@ def _file_sha(root, reference): def _path_sha(root, directory, filename, limit): """SHA-256 of directory/filename on disk, None when it does not exist, 'unreadable' when it is not a plain file.""" + try: + raw = _read_path(root, directory, filename, limit) + except folder_reader.Unsafe: + return 'unreadable' + return None if raw is None else _sha(raw) + + +def _read_path(root, directory, filename, limit): + """The bytes of directory/filename on disk; None when it does not exist, folder.Unsafe when not a plain file.""" try: fd = os.open(os.path.join(root, directory), folder_reader.DIRECTORY_FLAGS) except FileNotFoundError: return None - except OSError: - return 'unreadable' + except OSError as exc: + raise folder_reader.Unsafe(f'The directory {directory} cannot be opened: {exc.strerror}.') from None try: - return _sha(folder_reader.read(fd, filename, limit)) + return folder_reader.read(fd, filename, limit) except folder_reader.Unsafe: if not os.path.lexists(os.path.join(root, directory, filename)): return None - return 'unreadable' + raise finally: os.close(fd) diff --git a/tuldok_project/workspace.py b/tuldok_project/workspace.py index db5bce04..be8525ad 100644 --- a/tuldok_project/workspace.py +++ b/tuldok_project/workspace.py @@ -9,9 +9,19 @@ regular file of at most NOTE_LIMIT bytes, strict UTF-8; it opens no project. recipe_results reads the summary rows of every benchmark subject made from one recipe. +draft_branch (spec-w3.md section 2) writes the text of a new recipe branched +from one of the project's, names it, and says what set_definition would say +of it, storing nothing. Its settings file, when it has one, is read from the +code root as it is on disk, never through a link that leaves the code root. +The map also says which models have unsaved edits and, for a model with no +trained_at label, when the run of its current product finished. """ +import copy import dataclasses +import datetime +import json import os +import re from psycopg import sql @@ -20,6 +30,10 @@ NOTE_LIMIT = 1024 * 1024 DESCRIPTION_LIMIT = 300 # characters of a recipe's description on the map (spec-w2.md section 2) +SETTINGS_LIMIT = 256 * 1024 # bytes of a settings file a branch carries as its own settings (spec-w3.md section 2) +SLUG_LENGTH = 80 # characters of a branch's name made from its title, before any -2, -3, ... +_NOT_SLUG = re.compile(r'[^a-z0-9]+') +_INDENT = re.compile(r'\n([ \t]+)\S') def _labels(document): @@ -90,12 +104,30 @@ def _track(project, chart_reference, definitions): return track, values +def _product_finish_times(project): + """{reference: when the run that made its current product finished, as ISO 8601 text in UTC}, one query. + + A product that was adopted, or whose run has no finish time, is left out. + """ + found = {} + for reference, finished_at, state in project._execute( + "SELECT p.reference, r.finished_at, r.state FROM {schema}.products p " + "JOIN {schema}.runs r ON r.id = p.run_id WHERE p.current AND p.subject = ''"): + if finished_at is not None and state != builds.ADOPTED: + found[reference] = finished_at.astimezone(datetime.timezone.utc).isoformat() + return found + + def project_map(project): - """The map of an open project (spec-w1.md section 2): groups, models, edges, comparisons and the track.""" - rows = project._execute(f'SELECT {_REFERENCE_SQL}, kind, title, document FROM {{schema}}.definitions ' + """The map of an open project (spec-w1.md section 2): groups, models, edges, comparisons and the track. + + Each model also says whether it is unsaved, and its trained_at falls back + to its current product's finish time (spec-w3.md section 2). + """ + rows = project._execute(f'SELECT {_REFERENCE_SQL}, kind, title, document, unsaved FROM {{schema}}.definitions ' 'WHERE NOT removed').fetchall() - definitions = {reference: {'kind': kind, 'title': title, 'document': document} - for reference, kind, title, document in rows} + definitions = {reference: {'kind': kind, 'title': title, 'document': document, 'unsaved': unsaved} + for reference, kind, title, document, unsaved in rows} documents_by_reference = {reference: item['document'] for reference, item in definitions.items()} state = project._state() tuldok = state['project'] or {} @@ -118,6 +150,8 @@ def project_map(project): if recipe is not None: with_rows.setdefault(recipe, set()).add(benchmark) + finished = _product_finish_times(project) + recipes = sorted(reference for reference, item in definitions.items() if item['kind'] == 'recipe') models = [] for reference in recipes: @@ -128,8 +162,9 @@ def project_map(project): 'description': _description(document), 'short': _text(_labels(document).get('short')), 'group': _text(document.get('group')), 'change': _text(document.get('change')), 'derived_from': _text(document.get('derived_from')), - 'trained_at': _text(_labels(document).get('trained_at')), - 'state': states[reference], 'adopted': bool((status.get(reference) or {}).get('adopted')), + 'trained_at': _text(_labels(document).get('trained_at')) or finished.get(reference), + 'state': states[reference], 'unsaved': definitions[reference]['unsaved'], + 'adopted': bool((status.get(reference) or {}).get('adopted')), 'card': _text(document.get('card')), 'value': value, 'count': count, 'benchmarks': len(with_rows.get(reference, ())), }) @@ -231,3 +266,107 @@ def recipe_results(project, recipe, group=None): stored = result_rows._stored(record[1:]) rows.append({'benchmark': record[0], **dataclasses.asdict(stored.row), 'origin': stored.origin}) return {'rows': rows, 'benchmarks': sorted({benchmark for benchmark, _ in pairs})} + + +# ------------------------------------------------------------ branching + +def _branch_name(title, taken): + """A free name from title: lowercase, each run outside [a-z0-9] one '-', trimmed, then -2, -3, ... when taken.""" + base = _NOT_SLUG.sub('-', title.lower()).strip('-')[:SLUG_LENGTH].strip('-') or 'recipe' + name, number = base, 1 + while name in taken: + number += 1 + name = f'{base}-{number}' + return name + + +def _indent(text): + """The indentation of the first indented line of a definition's text; two spaces when it has none.""" + match = _INDENT.search(text) + return match.group(1) if match else ' ' + + +def _settings_object(code_root, path): + """The JSON object in the settings file path under code_root, or None when it cannot be carried. + + The file is read as it is on disk: its real path must stay inside the + code root (a link inside the code root is followed, one out of it is + not), it must be a regular file of at most SETTINGS_LIMIT bytes, and it + must hold one strict JSON object. + """ + if documents.relative_path_problem(path) or not os.path.isdir(code_root): + return None + target = os.path.realpath(os.path.join(code_root, path)) + if os.path.commonpath([code_root, target]) != code_root or target == code_root: + return None + try: + fd = os.open(os.path.dirname(target), folder_reader.DIRECTORY_FLAGS) + except OSError: + return None + try: + raw = folder_reader.read(fd, os.path.basename(target), SETTINGS_LIMIT) + return documents.decode(raw) + except (folder_reader.Unsafe, documents.DocumentError): + return None + finally: + os.close(fd) + + +def draft_branch(project, recipe, title, *, name=None, change=None, description=None): + """{reference, text, parent, inlined, problems}: a new recipe branched from recipe, stored nowhere (spec-w3.md). + + The text carries the parent's model, group and run, its kind of change + unless change is given, and derived_from naming the parent; not its card, + labels, earlier_work or comparisons. A run whose settings_file is a JSON + object under the code root carries it as settings, and inlined names the + file. problems are the errors and warnings set_definition would find in + the text at reference, as dicts. Raises ProjectError not-found for a + recipe that is not one of the project's, and invalid for a name that + breaks the name rule or is taken (a removed definition's name included). + """ + parsed = documents.parse_reference(recipe) + row = project._execute("SELECT text FROM {schema}.definitions WHERE directory = 'recipes' " + 'AND name = %s AND NOT removed', (parsed[1],)).fetchone() \ + if parsed and parsed[0] == 'recipes' else None + if row is None: + raise ProjectError(f'There is no recipe {recipe} to branch from.', 'not-found', references=[recipe]) + parent_text = row[0] + parent = documents.decode(parent_text) # from the text, not the jsonb column, to keep the order of its keys + taken = {taken_name for (taken_name,) in project._execute( + "SELECT name FROM {schema}.definitions WHERE directory = 'recipes'")} + if name is not None: + if not documents.is_name(name): + raise ProjectError(f'{name!r} is not a name: use 1 to 120 lowercase letters, digits, ".", "_" or "-", ' + 'starting with a letter or digit.', 'invalid', references=[f'recipes/{name}']) + if name in taken: + raise ProjectError(f'recipes/{name} is taken (a removed definition keeps its name until the project ' + 'is saved); choose another name.', 'invalid', references=[f'recipes/{name}']) + else: + name = _branch_name(title, taken) + reference = documents.reference('recipes', name) + + document = {'format': parent['format'], 'kind': 'recipe', 'title': title} + if description is not None: + document['description'] = description + for field in ('model', 'group'): + if field in parent: + document[field] = parent[field] + if change is not None or 'change' in parent: + document['change'] = change if change is not None else parent['change'] + document['derived_from'] = recipe + inlined = None + if isinstance(parent.get('run'), dict): + run = copy.deepcopy(parent['run']) + path = run.get('settings_file') + if isinstance(path, str) and 'settings' not in run: + state = project._state() + settings = _settings_object(os.path.realpath(os.path.join(state['folder'], state['code_root'])), path) + if settings is not None: + run = {('settings' if key == 'settings_file' else key): (settings if key == 'settings_file' else value) + for key, value in run.items()} + inlined = path + document['run'] = run + text = json.dumps(document, indent=_indent(parent_text), ensure_ascii=False) + '\n' + problems = project.definition_problems(reference, text) + return {'reference': reference, 'text': text, 'parent': recipe, 'inlined': inlined, + 'problems': [problem.as_dict() for problem in problems]} From a7ed05ea98515918a9b2827113f366fe8f034e69 Mon Sep 17 00:00:00 2001 From: MrScripty Date: Thu, 12 Nov 2026 14:54:09 -0700 Subject: [PATCH 048/131] feat(app): act on builds from the workspace: approve, decline, cancel, plan and request, resolve a conflict Controls are drawn only for a session that may use them. A plan is shown before a build can be asked for; cancelling and the like take two presses. While something runs the page reads again every two seconds, shows the open run's progress and logs, and reads the map again when a run ends. Co-Authored-By: Claude Fable 5.2 --- app.py | 1 + docs/contracts/project-folder.md | 7 +- static/project-workspace.html | 2 + static/project-workspace/actions.js | 333 ++++++++++++++ static/project-workspace/adapter.js | 21 +- static/project-workspace/app.js | 157 +++++-- static/project-workspace/base.css | 64 ++- static/project-workspace/screens.js | 100 +++-- static/project-workspace/tabs.js | 129 +++++- tests/browser_project_workspace.cjs | 12 +- tests/browser_project_workspace_actions.cjs | 467 ++++++++++++++++++++ tests/test_tuldok_project_http.py | 1 + 12 files changed, 1188 insertions(+), 106 deletions(-) create mode 100644 static/project-workspace/actions.js create mode 100644 tests/browser_project_workspace_actions.cjs diff --git a/app.py b/app.py index d9b8ee52..ab1eef59 100644 --- a/app.py +++ b/app.py @@ -991,6 +991,7 @@ def _get(self): '/project-workspace/markdown.js': ('project-workspace/markdown.js', 'text/javascript'), '/project-workspace/tree.js': ('project-workspace/tree.js', 'text/javascript'), '/project-workspace/screens.js': ('project-workspace/screens.js', 'text/javascript'), + '/project-workspace/actions.js': ('project-workspace/actions.js', 'text/javascript'), '/project-workspace/tabs.js': ('project-workspace/tabs.js', 'text/javascript'), '/project-workspace/app.js': ('project-workspace/app.js', 'text/javascript'), '/static/vendor/ubuntu-sans/UbuntuSans[wdth,wght].ttf': ('vendor/ubuntu-sans/UbuntuSans[wdth,wght].ttf', 'font/ttf'), diff --git a/docs/contracts/project-folder.md b/docs/contracts/project-folder.md index a730db55..a4298d87 100644 --- a/docs/contracts/project-folder.md +++ b/docs/contracts/project-folder.md @@ -1770,8 +1770,11 @@ status 2. The app opens the project only for each operation, as the commands do, so files changed on disk are imported before an operation answers and the command line keeps working beside the app. -The page at `/` shows the project's name and folder and its report, in the -theme the browser prefers. It has no editing and no approval buttons. +The page at `/` is the Map workspace: the tabs Map, Data, Train, Benchmarks, +Analysis and Overview over the project, read through the operations below. +Each of its controls calls one operation and is drawn only for a session that +may call it, so a credential that may only inspect sees a page that changes +nothing. The report is linked from the Overview tab. ### Signing in and issuing an agent credential diff --git a/static/project-workspace.html b/static/project-workspace.html index 2dea9357..0387577c 100644 --- a/static/project-workspace.html +++ b/static/project-workspace.html @@ -14,6 +14,7 @@ + @@ -26,6 +27,7 @@

                          • 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